quant_engine/handoff-retrospective-contract-v2.md

Quant Engine retrospective v2 compatibility

Scope: implement the user-authorized retrospective v2 compatibility without changing v1 semantics, financial algorithms, original results, production databases, deployment or trading. No claim of complete Quant OS delivery or real-data qualification.

Branch: codex/research-quant-os-retrospective-contract-v2-20260908. Declared base: accepted main@68dd68392a26251391fbdae40c22eee370adb56e. One isolated delivery worktree; the old primary checkout is preserved. This is not reactivation of an old registered stage or creation of a new stage ledger.

Dependency baseline

Public RP data-contract candidate: PR #100, initial schemas/goldens at 7da27e5bd33dc6d06f2c7c60f47029111156293a (review/acceptance pending). EDB mapping candidate: PR #13, initial implementation 88433df, local full validation passed. Neither candidate is silently treated as accepted owner evidence. The shared public major is 2.0.0; preserve the accepted v1 paths independently.

Order: public data contracts -> EDB mapping/Foundation -> Quant Engine typed factor/backtest/portfolio/risk -> RP governance -> Research Results -> RP read. Accepted owner-version bindings and runtime admission must still close every boundary.

Internal reuse decision

Need: carry observation-aware inputs and retrospective-only claims through computation. Existing: strict canonical JSON, immutable envelopes, factor definitions, input/output closure, numerical algorithms, governed backtest and portfolio/risk contracts. External candidates: not needed; this is project-owned semantics, not a missing library. Approach: reuse those primitives and algorithms; introduce explicit new-major wrappers only where upstream identity, time or usage semantics change. Risk: reusing the v1 decoder or coercing observed-by into knowledge/PIT would make a false historical claim. Unknown versions and unsupported usages must fail closed.

Implemented, not yet accepted or released

Five separate v2 modules now implement immutable DatasetSnapshot/Foundation decoding and materialized-content verification, FactorSet with explicit v2 nested bindings, BacktestRunRef and replay ancestry, nine-table BacktestEvidenceManifest, PerformanceEvidence, PortfolioTarget/Decision and RiskAssessment. The metadata registers the new major alongside every existing v1 entry. See docs/RETROSPECTIVE_COMPUTATION_V2.md for normative clocks, JSON profiles, input closure, replay and owner-port boundaries.

Factor definitions, generic output/receipt/constraint/covariance primitives and financial implementations are reused without semantic edits. Table schema remains 1.1.0; v1 business source, v1 goldens, pyproject.toml, uv.lock and ci-profile.yml are unchanged. Package version remains unreleased. Only module metadata, its exact inventory test and README gain v2 alongside the new files.

The frozen synthetic computation vector includes fresh factor/backtest/manifest/ performance/target/portfolio/risk documents and synthetic artifact tables. It is explicitly envelope-only, not an end-to-end claim that the one-day data fixture produced the four-day synthetic financial artifact. No old real run was rerun, retagged or backdated.

Local verification (2026-09-08)

• Full repository unit suite: 1039 passed, 1166 warnings, 31.50 seconds.
• S4 focused new + unchanged v1 contracts: 120 passed; new S4 332 statements, 20 branches, 100% measured coverage. Coverage is not source authentication or proof of complete business semantics.
• All five new source modules passed mypy; all six new test modules, five new sources and the updated metadata test passed Ruff.
• The combined synthetic vector and metadata smoke checks: 3 passed.
• Actual negative tests reproduced and fixed missing covariance-estimation context in result identity, untyped malformed-JSON errors, and risk-time stale-manifest reuse. Other modules' earlier RED/GREEN evidence remains part of the same turn.

The full suite was run directly against the frozen local environment. This is not the same claim as remote CI or central ship acceptance; the unchanged declared CI profile is lite with the module-metadata smoke command. Central validation and Draft PR creation follow the implementation commit. No Ready, merge, accepted upstream binding or independent-review pass is claimed here.

Actual computation/admission times are distinct from simulated business dates. New formal outputs cannot inherit the old run's producer identity or be backdated to it. Real receipt/qualification/view/clock ports remain mandatory; typed objects and hashes are not source authentication. The optional independent reviewer delegation is still awaiting the already-requested user choice.

Next: preserve the candidate for review, then carry explicit v2 facts through RP governance -> Research Results publication -> RP read compatibility. Bind final accepted upstream versions only when actual acceptance evidence exists. The entire Quant OS goal is not complete at this intermediate owner unit.

Rollback: disable the explicit v2 path and retain v1 plus immutable artifacts; never retag v2 into v1 or silently use synthetic evidence for real admission.