Example verification contracts

Every canonical example has a versioned machine-readable contract. A contract makes a test reproducible; a receipt proves that a specific Grid build executed it.

What a contract proves

Each example entry pins:

the exact exported .grid path, byte length, and SHA-256;
the Grid version and Grid Core source commit;
one or more named scenarios;
scenario-required capability labels used for review and coverage taxonomy;
exact fixture paths, bytes, and SHA-256 values;
observable assertions and matcher policy.

The site build verifies complete coverage of all 29 canonical examples and checks every identity against the Grid Core export manifest.

What it does not prove

A contract does not assert that Grid ran. Source-derived arithmetic, editorial checkpoints, and compile expectations remain declared expectations until a Runtime Host produces a receipt.

The current public bundle contains 12 receipts, covering all 10 coordinate-compatible scenarios, the one named-binding scenario, the one compile/deploy scenario, and all 12 portable-exact scenarios overall. An example page reports a runtime receipt only when the published evidence binds that exact scenario; all other pages continue to report source contract checked · runtime execution receipt pending.

Runtime classifications

Class	Reproducibility boundary
`portable-exact`	Exact authored state with no external fixture
`fixture-exact`	Exact only with the pinned data, module, or provider stub
`clocked-exact`	Exact with the pinned fake clock and scheduler state
`history-dependent`	Requires the declared revision history
`provider-dependent`	Live values may vary; assert lifecycle or policy, not provider numbers
`surface-dependent`	Requires the named renderer and interaction contract
`solver-dependent`	Requires solver capability and explicit numeric tolerances
`simulation-dependent`	Requires the declared clock, integrator, seed, and tracked outputs

Receipt requirements

A valid receipt binds to the complete contract digest, example and scenario IDs, source digest, fixture digest set, Grid build digest, platform, and required capability labels. Fixture comparison is order-insensitive. These labels classify the scenario; they are not inferred from similarly named Runtime catalog entries. Runtime RPC receipts additionally bind the Runtime-native catalog fingerprint and a canonical digest independently recomputed over the complete returned catalog body. Every receipt contains exactly one passing observation for every assertion in that scenario.

Receipts live separately so adding observations does not silently rewrite the expectation set. When the contract or any fixture changes, old receipts become stale and the build rejects them.

The managed coordinate adapter accepts only initial binding assertions with exact equality and no fixtures. It records the bound ready snapshot fields—including array spill and inferred-dimension metadata—and mechanically derives each semantic observation from the runtime's typed value envelope. The named-binding adapter additionally pins exact symbol spelling and the runtime's distinct named-wire IDs. The compile/deploy adapter accepts only a single compile-phase ready assertion and derives it from an exact-key deployment snapshot containing the complete submitted source, matching model and source identities, empty diagnostics, Rust engine, private visibility, and fresh revision state. Fixtures, actions, histories, providers, surfaces, solvers, simulations, and other diagnostic policies still require separate trusted adapters.

The text-and-quality/authored-baseline scenario is receipted against the frozen Grid 0.65.0 candidate. Runtime Host returns the symbol literal :accepted in a string wire envelope whose typeTag is "symbol"; the coordinate adapter therefore projects the observation to {kind: "symbol", value: "accepted"} while preserving the Runtime's documented semantic type.

Consumer workflow

Select an example and scenario from the contract document.
Treat the scenario capability labels as review taxonomy, and separately confirm that the target build's complete capability-catalog identity matches reviewed provenance.
Fetch the exact source and the base64 fixture bundle; decode and verify their raw byte digests.
Apply the declared setup and run the scenario in an isolated model.
Evaluate each assertion with its matcher and tolerance.
Emit a receipt containing the complete runtime provenance.

Do not upgrade a “contract checked” badge to “runtime verified” by copying expected values into a result file. A receipt must contain observations from the bound Grid build.

Maintainer capture workflow

Run npm run capture:example-receipts -- --list to see captured, capturable, and unsupported portable scenarios. A managed capture requires GRID_RUNTIME_HOST_BIN to name the exact Runtime Host executable. The harness calls its authenticated RPC surface directly; it does not execute a separate Node API checkout or dependency tree.

Without --write, the command emits a complete candidate receipt document and leaves the repository unchanged. Both candidate and write modes proceed only when the executable digest has one unique reviewed entry in content/example-verification/runtime-build-provenance.json. That registry records an operator-reviewed commit, clean-state claim, source tree/archive identity, lockfile digest, toolchain, build recipe, and capability-catalog identity for new builds; runtime health itself reports only the live PID, binary path, and coarse profile. The harness snapshots the accepted bytes into a private read-only executable, starts that copy as an isolated authenticated loopback Runtime Host, requires that health profile to match exactly, checks the capability catalog's schema and product version, recomputes a canonical digest over its complete body, requires both catalog fingerprints to match the reviewed build, checks every source digest, captures adapter-specific evidence, deletes its temporary models, rechecks the private executable, and validates the complete candidate with the same verifier used by npm run verify:examples. Every verifier run is pinned to the exact contract, candidate receipt, Runtime-provenance, and export-manifest bytes read by the capture. With --write, the harness then replaces the receipt file atomically. Final receipt, executable, provenance-registry, contract, schema, export-manifest, and selected-source digest comparisons plus a writer lock prevent concurrent evidence from being overwritten.

By default the harness attempts every missing adapter-supported portable scenario. Use --example <slug> for a targeted capture. Recapture requires --replace together with at least one explicit --example.