feat: add explicit retrospective v2 computation contracts (#20)

handoff-retrospective-contract-v2.md

@@ -0,0 +1,88 @@
+# 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.