89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# 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.
|