Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions usvm-ts-fast-check/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,35 @@ JSON again because the process boundary must not trust malformed input. Diagnost
language: `FastCheckDiagnosticCode.kt` for Kotlin and `diagnostics.ts` for Node. Node also sends the diagnostic category,
so Kotlin never infers error meaning from code prefixes.

## Bounded property observations

`PropertyRunConfiguration.observationRequest` opts into one observation artifact on the run result. Each requested
point names an assertion operand and its call site. The adapter records each callback invocation's original input,
precondition admission, predicate outcome, and phase. `invocation.input` is captured automatically at the callback
boundary. Named argument, return, intermediate, pre, and post operand points need explicit
`observePoint(id, value)` hook in the selected TypeScript source. The hook returns the same value. Repeated hits at one
static point have zero-based `occurrence` values and invocation-local `eventOrdinal` values.

The request bounds invocations (at most 64), points per invocation (at most 8), array elements (at most 64), and
artifact bytes (at most 65,536). Dropped invocations and points are counted. A snapshot refuses proxies, accessors,
sparse arrays, nonstandard array prototypes, extra array properties, aliases, cycles, unsupported object types, and
arrays beyond the declared depth or element bound. Such values have an explicit `unsupported` status rather than a
fabricated concrete value. Byte-limited values have `truncated` status. Snapshot time is reported as
`captureTimeMillis`; it measures capture work, not end-to-end runtime overhead.

The byte budget covers the entire artifact, including property identity, selected-source hashes, and final metadata.
If the mandatory envelope cannot fit, the request is rejected before importing the predicate. Identities are never
shortened to fit. Capture reserves the longest final admission/outcome and full safe-integer counters/timing before
accepting a record; counters and capture time saturate at `Number.MAX_SAFE_INTEGER`. Internal serialization never
consults user `toJSON` methods, including methods inherited by tagged values and protocol arrays.

Before importing the predicate, the adapter checks SHA-256 bytes of every selected source module in the request.
`verifiedSources` identifies only those selected modules. The build status remains `unverified`: the adapter does not
verify transpiled output, the loader, or transitive imports. Observation phases come from fast-check arbitrary
generation and shrink calls, explicit example identity, and replay requests. An `unknown` phase must not be treated
as a fresh independent sample. Observation is empirical and does not make an assertion sound or prove that a
recorded point is semantically relevant to a failure.

## One property run

```mermaid
Expand Down
1 change: 1 addition & 0 deletions usvm-ts-fast-check/fast-check-adapter/src/diagnostics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ export const adapterDiagnostic = {
entryPointModuleNotFound: entryPoint('entrypoint.module.not-found'),
entryPointModuleAmbiguous: entryPoint('entrypoint.module.ambiguous'),
entryPointModuleImportFailed: entryPoint('entrypoint.module.import-failed'),
entryPointSourceHashMismatch: entryPoint('entrypoint.source-hash.mismatch'),
entryPointExecutionKindMismatch: entryPoint('entrypoint.execution-kind.mismatch'),
entryPointResultInvalid: entryPoint('entrypoint.result.invalid'),
entryPointPreconditionThrew: entryPoint('entrypoint.precondition.threw'),
Expand Down
20 changes: 19 additions & 1 deletion usvm-ts-fast-check/fast-check-adapter/src/entry-point.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { realpath, stat } from 'node:fs/promises';
import { createHash } from 'node:crypto';
import { readFile, realpath, stat } from 'node:fs/promises';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import { register as registerCommonJs } from 'tsx/cjs/api';
Expand Down Expand Up @@ -66,6 +67,23 @@ export async function loadEntryPoint(
};
}

/** Verifies one selected source module's exact bytes before importing user code. */
export async function verifySourceHash(
module: string,
expectedSha256: string,
sourceRoots: string[],
): Promise<void> {
const modulePath = await resolveModule(module, sourceRoots, 'observationRequest.sources');
const actual = createHash('sha256').update(await readFile(modulePath)).digest('hex');
if (actual !== expectedSha256) {
throw protocolError(
adapterDiagnostic.entryPointSourceHashMismatch,
`Selected TypeScript source changed: ${module}`,
'observationRequest.sources',
);
}
}

async function resolveModule(
module: string,
sourceRoots: string[],
Expand Down
Loading