A fail-closed market snapshot contract

Inputs

• Raw exports of ranking data per domain and snapshot date from a research tool or a rank tracker. Collection is outside the method, and the contract never touches it.

• A snapshot directory layout in which every run is a directory of its own.

• A verification tool that computes hashes and writes the manifest.

• At least two independent implementations of the same read, for instance Python with DuckDB and Rust.

Procedure

1. Fail closed

   A snapshot without a complete marker and an explicit run id is not a snapshot, and the reader refuses it with a reason. A partial run never looks like a success.

2. Bind the source set before any transformation

   The set of source files is recorded and every file is bound by a SHA-256 hash before the first transformation. A file's modification time never decides anything.

3. Keep the verified immutable

   Verified files are never rewritten. A correction is a new run id, and the old one stays readable as it was.

4. Keep the canonical layer clean

   The canonical layer holds only the source's own entities under their own names and an explicit version string. Derived scores, aliases and projections live on top of it, never inside it.

5. Benchmark the implementations for parity

   The benchmark names the implementation and the alias projection, runs the integrity gates, rereads the snapshot independently and compares the result with a Python oracle row by row. The result is a verified artifact with the benchmark's conditions written in.

6. Trace every figure to a run

   Every figure in a report carries the run id and the version. A figure that cannot be traced is not in the report.

Outputs and how to read them

• The canonical tables with version and run id, and the manifest with hashes.

• A verified benchmark artifact: implementation, projection, gates, oracle and result.

• A refusal with its reasons when anything is missing.

Failure modes

• The newest file is read as the right one because it is the newest.

• A partial snapshot passes, and the gap shows only in the report.

• Derived fields creep into the canonical layer, and source and interpretation mix.

• The benchmark compares an implementation with itself.

• A defect is fixed in place, and the old result can no longer be reproduced.

Where it is used

In the market-intelligence pipeline: the contract and the benchmark are the acceptance gates for every new snapshot, and they never touch collection.