Semantic Snapshots and Correlation

This is the reference page for archived semantic contract truth, not just for one diff command.

Use it when the real question is what contract meaning was recorded, what changed between two semantic states, or whether new blockers line up with contract drift.

• use it when you need to inspect the archived normalized contract truth behind a receipt
• use it when you want semantic diff against current repo truth or another archived state
• use it when you want receipt compare output to explain whether new blockers are likely related to contract drift
• use Diff and Explain when the question is only command behavior for ota diff or ota explain

V10 exposes three connected but distinct surfaces.

Treat them as one workflow: inspect archived truth, compare semantic states, then read correlation only when failures appear.

Use ota receipt --snapshot when you need the archived semantic contract truth itself instead of only seeing it indirectly through diff or readiness output.

This stays read-only and does not rerun doctor, archive a new receipt, or mutate repo state.

• --snapshot latest resolves the newest matching archived receipt for the same contract and reads its normalized snapshot
• --snapshot promoted resolves the explicit promoted baseline pointer and reads the archived normalized snapshot behind it
• --snapshot <receipt.json> follows receipt.contract_snapshot_ref from an archived repo receipt JSON artifact
• --snapshot <snapshot.json> accepts an archived normalized .ota/contracts/... snapshot JSON file directly
• snapshot JSON also publishes assumption_set_hash and summary.assumption_count, so automation can fingerprint semantic meaning separately from whole-snapshot identity

ota receipt --snapshot latestota receipt --snapshot promotedota receipt --snapshot ./.ota/receipts/repo-receipt-20260621-120000-000Z.jsonota receipt --snapshot ./.ota/contracts/sha256-....jsonota receipt --json --snapshot latest

ota diff is the semantic contract comparison lane inside this broader snapshot workflow.

The important boundary is that the diff runs on normalized assumption keys and can resolve archived receipt inputs through the matching .ota/contracts/... snapshot behind the scenes.

• text output shows the resolved input kinds for each side, including receipt-backed snapshot lanes
• JSON output adds base_input and target_input with the resolved semantic input kind and any snapshot_path used during resolution
• use it before merges, in CI review gates, or whenever you need semantic impact instead of a raw YAML diff

ota diff ./before/ota.yaml ./after/ota.yamlota diff ./.ota/receipts/repo-receipt-20260621-120000-000Z.json ./ota.yamlota diff ./.ota/contracts/sha256-....json ./ota.yamlota diff --json ./before/ota.yaml ./after/ota.yaml

Correlation is the advisory layer on top of receipt compare, not a separate command.

Its job is to join new blocking findings with semantic contract drift honestly, without pretending that every failure has one certain contract cause.

• use ota receipt --json --baseline promoted or --baseline latest when a repo keeps archived receipts and wants drift-aware compare gates
• read summary.comparison.contract_snapshot_changed to see whether the archived baseline and current semantic contract truth differ at all
• read contract_changes[] for the ordered semantic assumption diff between the archived baseline snapshot and current contract truth
• read likely_related_changes[] for the best-ranked plausible contract changes when new blockers appear
• read summary.comparison.correlation to distinguish likely_related, possibly_related, and no_clear_correlation without inferring posture from array presence alone
• ordering prefers the sharpest declared semantic evidence Ota can recover honestly: exact owner truth first, then owner subtree drift, then named references, then broader same-family overlap
• expect reusable surfaces.<name> and readiness.probes.<name> truth to outrank weaker workflow references when both are plausible for the same failure

ota receipt --json --archive --promote-baselineota receipt --json --baseline promotedota receipt --json --baseline latest --fail-on-new-blockers

{  summary: {    comparison: {      contract_snapshot_changed: true,      correlation: "likely_related"    }  },  contract_changes: [    {      path: "env.vars.DATABASE_URL.required",      status: "add",      category: "env",      risk: "high",      target: "true"    }  ],  likely_related_changes: [    {      path: "env.vars.DATABASE_URL.required",      status: "add",      category: "env",      risk: "high",      target: "true"    }  ]}

When likely_related_changes[] is present, ordering is part of the trust contract, not presentation noise.

Ota should publish the sharpest declared semantic explanation it can recover before weaker adjacent drift.

• exact declared owner truth ranks first
• declared owner subtree drift ranks next
• named requirement or attachment references rank after direct owners
• broader same-family overlap is the fallback when no sharper declared match can be recovered honestly
• reusable surfaces.<name> and readiness.probes.<name> are strong owner lanes, not loose labels

• choose ota receipt --snapshot when you need archived semantic truth directly
• choose ota diff when you need semantic comparison between two contract states
• choose ota receipt --json --baseline ... when you need new-blocker comparison plus semantic drift correlation
• choose the JSON output reference when you need machine-readable field-by-field payload detail
• choose Diff and Explain when the question is command selection and remediation planning rather than archived contract truth