Introduced in 0.1.0.dev5; supported in 0.1.0. See INSTALL.md for
current installation qualification. Example paths also work after exporting
with structdet-code examples --output ./examples. All commands remain passive;
dev5 snapshots still require their original matching software/runtime identity.
python3 -m structdet_code trace --study examples/interventions/study.json --design examples/interventions/design.json --evidence examples/interventions/evidence.json --format markdown
python3 -m structdet_code inspect --study examples/interventions/study.json --evidence examples/interventions/evidence.json --format json
python3 -m structdet_code snapshot --action trace --study examples/interventions/study.json --design examples/interventions/design.json --evidence examples/interventions/evidence.json --output /tmp/structdet-code-snapshot
python3 -m structdet_code replay --bundle /tmp/structdet-code-snapshot --format markdownThe snapshot directory must be new. It contains result.json, result.md, snapshot.json and the exact input files. Move the complete directory together. The original study directory is not required for replay.
The owned example has two stipulated runs, each with the mechanism sequence RELAX, FIFO, RELAX. Its nine ordered intervention records include initial prompts, test feedback, a copied reference, an alternative-strategy instruction and a withheld reference. A shared fixture root and repeated source bytes remain explicit. The final RELAX is an observed reappearance.
Run I1 explicitly claims reference copying, with equal reference/output bytes. I2 records an alternative instruction and a withheld reference whose bytes also match the final output. The withheld event is not counted as agent-visible. Neither content equality nor temporal association establishes which event caused the revision, autonomous discovery, independent recovery or new model capacity. Several events can precede one revision without separate outcome observations.
The bad RELAX and bad FIFO implementations both fail T04, T05, T06, T07, T08 and T10. The final corrected program passes those inputs. Four supplied profiles expose that overlap. Their labels differ while their finite failure sets match. These facts do not qualify independent ensemble risks.
The fixture builder executes four fixed owned reference/defect strings against an independent graph oracle. Ten receipts contain 100 actual finite outcomes. Histories, interventions, visibility, reuse, conditions and budgets are stipulated software-fixture claims; no model was called. Production analysis reads receipts and never runs that builder or any imported source.
python3 -m structdet_code evidence-template --study examples/interventions/study.json --output /tmp/my-evidence.jsonThis creates an empty sidecar bound to the exact study bytes. Fill only records you possess. No assignment, intervention, provenance, exposure or test outcome is invented to fill the template. The study schema remains unchanged.
| Top-level field | Contract |
|---|---|
| schema_version | structdet-code.evidence/0.1 |
| study_sha256 | SHA-256 of the exact study manifest |
| materials | At most 64 records |
| interventions | At most 512 records |
| failure_profiles | At most 32 records |
| Field | Contract |
|---|---|
| id | Unique bounded identifier |
| path | Relative regular payload path, or null if uncaptured |
| sha256 | Exact lowercase SHA-256, or null when no bytes/hash are available |
| kind | instruction, reference_code, test_feedback, other |
| origin | external, project_fixture, supplied, unknown |
| source_ref | Supplied nonempty reference text, or null |
| independence_claim | unknown, shared_origin, claimed_independent |
For a non-null path, sha256 must match the captured bytes. For a null path, a supplied hash is a reference claim only; there is no verified byte match. Paths are relative to the evidence sidecar. Payloads may hold prompt/reference bytes and are never imported or executed. Reports expose IDs, fingerprints, capture status and claims. They omit raw content, paths and source-reference text. Independence remains unverified even when a supplier claims it.
| Field | Contract |
|---|---|
| id, run_id | Unique event ID and existing study run |
| after_revision_id | Recorded ancestor anchor, or null for a root baseline prompt |
| before_revision_id | Revision produced after this recorded event interval |
| order | Positive integer up to 1000000, unique within the run |
| kind | baseline_prompt, alternative_strategy, test_feedback, reference_material, other |
| material_ids | Referenced sidecar materials |
| feedback_ids | Referenced study feedback events |
| visibility | visible, withheld, unknown |
| reuse_claim | copied, adapted, none, unknown |
Order describes the supplied event order. Withheld and unknown records do not establish exposure. Ordered target revision ordinals cannot move backward. The after anchor must be a known ancestor of the before revision in the same run. A null after anchor is allowed only for a baseline prompt before a root. The interval does not invent a finer timestamp, another code revision or another generation. Merge/gap semantics remain those of the trace.
Feedback must examine the after anchor. A visible feedback event must appear in the before revision's received feedback IDs; withheld/unknown events cannot contradict already recorded receipt. test_feedback requires an actual study test-feedback record bound to a receipt. The original study prevents withheld evaluation receipts from being exposed as visible feedback.
copied/adapted require a reference-material event with material references. They remain supplied claims. An exact_material_matches entry additionally requires captured reference-code bytes equal to the subsequent artifact. This equality does not prove how that artifact was produced.
All supplied events remain visible, including events for study runs outside the trace roster. Selected-path relations distinguish first_observed, observed_again, persisted, unresolved_assignment and outside_selected_path. Static inspection uses not_traced, since its final population is not a selected lineage. An agent_visible_association requires visible exposure and selected path membership. It does not qualify a mechanism when the assignment remains unresolved.
The study configuration describes the original conditions; ordered intervention records add subsequent supplied context. Cohort changes remain descriptive under the declared collection protocol. No numeric change is attributed to an event.
Each profile has id, receipt_id and outcomes. Each outcome has id (the exact suite case ID) and status: passed, failed, not_completed or not_attempted.
Include exactly one outcome for every case in the receipt's suite. The passed count equals receipt.passed; passed plus failed equals completed; adding not_completed equals attempted. One profile per receipt is allowed. Aggregate receipt counts alone cannot reconstruct per-input outcomes, so an empty template creates no profiles.
Profiles stay attached to exact receipt/revision/source/suite identities. Their analysis-selection flag distinguishes the static selected receipt or a receipt on the selected trace path from extra evidence. Optional profiles do not override validity or mechanism admission. Passing all recorded cases does not override a failed conformance assessment.
Pairing requires equal suite bytes, oracle, environment fingerprint, execution basis and known visibility. Mixed or unknown scope leaves both inventories and an unavailable pair. In a comparable pair:
- both_failed contains failures among cases completed by both.
- left_failed_right_passed and its reverse require a known pass on the other side.
- failures_other_unobserved preserves failures opposite missing/incomplete tests.
- both_completed/suite_cases and complete_suite_both expose coverage.
Same-source and same-run relationships are disclosed. A partial profile can support an overlap on its jointly completed subset, without a full-suite robustness claim. No failure-independence or deployment-reliability estimate is computed. Changing a suite/environment/visibility does not become new correctness.
Use review-template and apply-review as in C02. An applied review appends a new assignment version and writes a new study manifest in the original study directory. Source artifacts and revision records stay unchanged.
The response includes dependent_bindings with previous/new study SHA-256 and the next action. Existing trace designs, comparison designs and evidence sidecars are stale against the new manifest and fail closed. Regenerate their templates, review the carried evidence/selection decisions and restore only known context. New trace templates use the latest assignments, including withdrawals to unresolved. Do not merely replace a digest while retaining stale assessment IDs.
Create a fresh snapshot for corrected conclusions. An older bundle still replays its captured history under matching software, including the older assignment; its successful replay does not make that assignment current. Source/task/receipt changes likewise require fresh validated bindings. No automatic invalidation registry, cascading file rewrite or migration service is introduced.
snapshot accepts --action inspect, trace or compare:
| Action | Arguments |
|---|---|
| inspect | --study, optional --evidence |
| trace | --study, optional --design and --evidence |
| compare | --left and --right, optional --design |
All require --output naming a new directory. Without a design, the ordinary unknown-context/default-template behavior is preserved in the captured analysis. Failure profiles and intervention sidecars currently attach to inspect/trace; compare uses its existing two-study contract.
Snapshot acquisition captures the exact manifests and referenced source/suite bytes, then performs full validation/analysis on those copies before creating the persistent output. Designs, optional materials, results and invocation arguments are bound with hashes and sizes. No source program or archived software executes.
The saved software identity includes version, method ID, installed package Python modules and task data, Python implementation/version and platform family. Replay requires that identity, checks each listed file, and recomputes from a temporary copy containing only listed inputs. Both result.json and result.md must match exactly, including unresolved states and qualifiers. Ordinary no-follow input checks still apply. Unlisted files cannot provide a missing source or validator.
Replay output is a wrapper with replay_verified, result_sha256 and the recomputed result. Markdown adds a short verification line before the ordinary report. Malformed/stale/tampered inputs and software/report mismatches exit 2 with a bounded JSON error. There is no automatic software upgrade, migration, model labeling, resampling or candidate rerun. Bindings verify internal consistency; they do not authenticate a bundle's author or the claimed execution history.
The bundle contains original private inputs, including prompts, source files and captured reference material. Share its reports independently when those inputs should remain private. Snapshots use a new owner-only directory and exclusive owner-readable/writable files. Failed writes may leave an incomplete directory; only a successful command is a completed snapshot.
Limits: 1 MiB per input JSON, 256 KiB per source/material, original 4 MiB per study or sidecar/material read scope, 4 MiB per rendered result, 512 bundle payload files and 24 MiB cumulative bundle reads. JSON depth remains 24. Refusals are errors, with no truncated success or arbitrary fallback plugin.
python3 tools/run_demonstrations.py --output /tmp/structdet-code-demonstrationsThe output must be new. Each named directory contains a complete snapshot and both reports; summary.md identifies the demonstrations. Every analysis is replayed by the same production engine before success is reported.
| Directory | Supplied example | Observable behavior |
|---|---|---|
| surface | static sorting | Renamed/presentation variants retain their mechanism; unresolved code remains unadmitted |
| mechanisms | graph condition comparison | FIFO, SETTLE and RELAX remain distinct under one graph task |
| concentration | trace/concentration.json | Finite passing 2/6, 4/6, 6/6; support 3, 2, 1 |
| stable | trace/stable.json | The same passing counts; support stays 3 |
| attrition | trace/attrition.json | Stopped and missing runs change available cases; matched A3/A4 retain FIFO |
| interventions | interventions/study.json with its design/evidence | RELAX reappears after recorded events; copied/withheld references and shared failures remain explicit |
These are designed software examples with real owned-program finite receipts, and zero live model calls. They do not establish empirical agent convergence. C06 remains responsible for installed distribution usability and supported platform qualification.