Phase 2A: durable cases and bound C++ evidence (#6)

* feat(storage): add durable governed case store

* feat(engine): admit bound C++ v1 evidence

* docs: publish Phase 2A operator contract

* fix(engine): accept checkout canonical remote

* fix: preserve deterministic behavior on Windows

Author: MrithunjoyB

.github/workflows/ci.yml

@@ -91,3 +91,50 @@ jobs:
         run: python -m scripts.inspect_packages --dist-dir dist
       - name: Verify runtime and CLI versions
         run: python -c "import quantforge, subprocess, sys; assert quantforge.__version__ == '0.1.0'; subprocess.run([sys.executable, '-m', 'quantforge', '--version'], check=True)"
+
+  cpp-v1-adapter:
+    name: C++ v1.0.0 adapter / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-14]
+    steps:
+      - name: Check out exact QuantForge source
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          path: quantforge-ai
+          persist-credentials: false
+      - name: Check out immutable C++ v1.0.0 source
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: MrithunjoyB/cpp-event-driven-backtester
+          ref: v1.0.0
+          fetch-depth: 0
+          fetch-tags: true
+          path: cpp-engine
+          persist-credentials: false
+      - name: Set up Python 3.12 with lock-bound cache
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: quantforge-ai/requirements-dev.lock
+      - name: Install the reviewed QuantForge development lock
+        working-directory: quantforge-ai
+        run: python -m pip install --require-hashes -r requirements-dev.lock
+      - name: Build the immutable C++ release target
+        working-directory: cpp-engine
+        run: >-
+          cmake -S . -B build
+          -DCMAKE_BUILD_TYPE=Release
+          -DQUANT_ENABLE_STRICT_WARNINGS=ON
+          && cmake --build build --parallel 2
+      - name: Exercise the read-only release adapter twice
+        working-directory: quantforge-ai
+        run: python -m pytest -q tests/integration/test_cpp_v1_adapter.py
+        env:
+          QUANTFORGE_CPP_V1_EXECUTABLE: ${{ github.workspace }}/cpp-engine/build/quant_cli
+          QUANTFORGE_CPP_V1_REPOSITORY: ${{ github.workspace }}/cpp-engine
+          QUANTFORGE_CPP_V1_WORK_ROOT: ${{ runner.temp }}

CHANGELOG.md

@@ -6,7 +6,27 @@ policy versions remain independently governed.
 
 ## [Unreleased]
 
-No changes recorded.
+### Added
+
+- Add a backend-neutral durable case-store contract, crash-safe SQLite backend, forward-only
+  checksummed migrations, historical fixture, deterministic reconstruction, and export lineage.
+- Add a read-only adapter for the exact protected C++ v1.0.0 public synthetic fixture and canonical
+  engine-evidence bundles with optional fixture-only signing.
+- Add narrowly scoped store, migration, engine, evidence, reconstruction, and package CLI commands.
+- Add adversarial storage/bundle/process tests and Linux/macOS tagged-engine integration CI.
+
+### Security
+
+- Bind engine evidence to release, executable, invocation, configuration, inputs, complete outputs,
+  validators, methodology, case, workflow revision, constitution, amendments, and bundle lineage.
+- Reject injection, stale writers, schema tampering, path/symlink attacks, substitution, malformed or
+  non-finite output, process flooding, audit/graph drift, and post-finalization admission.
+
+### Limitations
+
+- The adapter is research-only, read-only, and limited to one public synthetic fixture. Live
+  providers, market data, brokers, orders, live trading, investment advice, and profitability claims
+  remain out of scope.
 
 ## [0.1.0] - 2026-07-15
 

README.md

@@ -13,8 +13,9 @@ pure policy compute the strongest defensible verdict.
 > Most financial AI searches for strategies to believe. QuantForge searches for reasons not to
 > believe them.
 
-This is the independently audited **Phase 1 governance foundation**, prepared as a local `v0.1.0`
-publication candidate. It is not an AI investment committee: roles may propose or explain, but
+This repository contains the independently audited **Phase 1 governance foundation** and the Phase
+2A durable local case store plus research-only C++ v1.0.0 evidence adapter. Version `v0.1.0` remains
+the immutable Phase 1 release; current Phase 2A work is unreleased. Roles may propose or explain, but
 code owns workflow state, evidence validity, human approval, and verdict strength.
 
 After the locked development environment is installed, the exact offline demo command is:
@@ -27,9 +28,11 @@ The command uses packaged synthetic fixtures, performs no network request, and e
 case, evidence, claim-graph, manifest, and audit artifacts. Those artifacts are validation evidence
 for governance behavior—not financial evidence and not evidence of profitability.
 
-Current limitations are deliberate: there is no live model provider, real OpenAI execution,
-market-data ingestion, real C++ engine integration, database, retrieval system, web UI, broker
-connectivity, order submission, live trading, production deployment, or investment advice.
+Phase 2A adds a schema-versioned SQLite backend, deterministic case packages, and one narrowly
+allow-listed, read-only adapter for the protected C++ `v1.0.0` public synthetic fixture. The C++
+release remains the numerical authority. There is no live OpenAI/provider integration, external
+market-data ingestion, retrieval system, web UI, broker connectivity, order submission, live
+trading, production deployment, investment advice, profitability claim, or guarantee.
 
 ## Install and verify offline behavior
 
@@ -96,6 +99,13 @@ remains human-directed, reviewed, and maintained by Mrithunjoy Basumatary. AI sy
 project authors or copyright holders.
 
 - [Architecture](docs/ARCHITECTURE.md)
+- [Storage model](docs/STORAGE_MODEL.md)
+- [Migration policy](docs/MIGRATION_POLICY.md)
+- [C++ engine integration contract](docs/ENGINE_INTEGRATION_CONTRACT.md)
+- [Evidence model](docs/EVIDENCE_MODEL.md)
+- [Deterministic semantics](docs/DETERMINISM.md)
+- [Operator runbook](docs/OPERATOR_RUNBOOK.md)
+- [Limitations](docs/LIMITATIONS.md)
 - [Governance](docs/GOVERNANCE.md)
 - [Security Model](docs/SECURITY_MODEL.md)
 - [Threat Model](docs/THREAT_MODEL.md)

docs/ARCHITECTURE.md

@@ -1,25 +1,47 @@
 # Architecture
 
-QuantForge Phase 1 is a deterministic domain application arranged as inward-facing layers:
+QuantForge is a deterministic, offline research tribunal arranged as inward-facing layers:
 
-1. `domain` owns immutable versioned contracts and constitution factories.
-2. `serialization` owns canonical JSON, SHA-256 identity, defensive parsing, and export.
-3. `evidence` owns the append-only ledger and typed claim graph.
-4. `audit` owns the single-case append-only hash chain, hashed payloads, and full state replay.
-5. `verdict` owns the pure conservative policy.
+1. `domain` owns immutable, versioned contracts and constitution factories.
+2. `serialization` owns canonical JSON, SHA-256 identity, defensive parsing, and atomic files.
+3. `evidence` owns the append-only ledger, typed claim graph, and bound engine bundles.
+4. `audit` owns the single-case append-only hash chain and semantic state replay.
+5. `verdict` owns the pure conservative eligibility policy.
 6. `roles` owns provider-neutral typed interfaces and authority checks.
 7. `workflow` owns the only legal sequential orchestration.
-8. `adapters` contains package-owned mock roles and evidence only.
-9. `cli` exposes offline demos and validators.
+8. `storage` owns a backend-neutral case-store contract, SQLite implementation, migrations,
+   reconstruction, and deterministic package export.
+9. `engine` owns the narrow read-only adapter contract for the protected C++ release.
+10. `adapters` contains package-owned mock roles and synthetic evidence only.
+11. `cli` exposes bounded offline operations; it is not an arbitrary process or filesystem API.
 
-The architecture deliberately uses an in-memory aggregate and canonical files. A database, graph
-database, web framework, queue, vector store, and agent framework would add operational state without
-evidence that Phase 1 needs it.
+## Authority boundary
 
-External provider output can enter only through a future adapter that returns the same validated
-domain models. Workflow state, evidence integrity, and verdict policy remain code-owned even when a
-language model later proposes role findings.
+QuantForge owns workflow state, human approval, constitution locking, evidence admission, reviewer
+authority, audit replay, the claim graph, verdict eligibility, and Chair constraints. The protected
+`MrithunjoyB/cpp-event-driven-backtester` release `v1.0.0` remains the numerical authority for
+simulation, statistics, reconstruction artifacts, and engine-side validation. The adapter cannot
+let the engine change tribunal state or decide that its own output is evidence.
 
-A case file is a deterministic snapshot, not independent proof of history. Governed restoration
-requires the complete audit JSONL: replay validates every state, actor, action, payload, identity,
-derived verdict input, and final snapshot. The CLI therefore requires both files for `case validate`.
+Raw engine files are untrusted. The adapter first validates the exact release and executable,
+stages a fixed public synthetic fixture into an isolated directory, executes fixed argument arrays,
+runs the release validator, inventories and hashes every output, and emits a bundle. QuantForge then
+checks the bundle against current durable case state in the same transaction that appends its
+workflow event and evidence materialization.
+
+## Durable and derived state
+
+The semantic audit chain is authoritative for case reconstruction. SQLite stores that chain plus
+referentially constrained materializations of the constitution, evidence, graph, reviewer outputs,
+verdict result, bundle inventory, and export lineage. Reconstruction replays the events and compares
+every materialization and hash; a snapshot is never trusted independently. See
+[Storage Model](STORAGE_MODEL.md) and [Migration Policy](MIGRATION_POLICY.md).
+
+SQLite is deliberately local and single-node. It provides transactions, WAL recovery, foreign keys,
+bounded busy waiting, and optimistic revisions, but not distributed consensus or an external trust
+anchor. A complete locally rehashed replacement remains detectable only when compared with a trusted
+external digest or signed/anchored publication.
+
+No live provider, market-data ingestion, broker, order, or trading component exists. A later
+provider adapter may propose typed role output, but code-owned workflow and evidence authority must
+remain unchanged.

docs/DETERMINISM.md

@@ -0,0 +1,27 @@
+# Deterministic Semantics
+
+QuantForge distinguishes semantic identity from observations that necessarily vary between runs.
+
+- Canonical JSON sorts object keys and normalizes Unicode, UTC timestamps, finite decimals, and
+  negative zero.
+- Audit event hashes, case semantic hashes, materialization hashes, migration checksums, artifact
+  semantic hashes, and export manifests use canonical JSON.
+- Engine bundle semantic hashes contain every meaningful input, invocation, schema, validator,
+  output value, methodology, unit, and lineage identity.
+- Execution/admission time and raw byte observations have a separate observation hash. Documented
+  volatile JSON provenance fields are removed only from semantic artifact hashing; their original
+  artifact bytes remain byte-hashed in observations and therefore remain bound by the bundle hash.
+- Exports include no export-time clock. Their ID derives from case ID and revision; parent lineage is
+  the prior durable manifest; artifacts and manifest end in one normalized newline.
+
+Repeated approved fixture execution must produce identical output semantics, numeric facts,
+validator identity, config/input identity, and canonical semantic bundle bytes. Observation and full
+bundle hashes may differ when truthful timestamps or raw volatile bytes differ. Re-exporting the
+same revision to new empty directories must be byte-identical. Reconstructing from events must equal
+the stored case, ledger, graph, verdict result, and audit head. Migration must not change those
+semantic identities.
+
+Tests exercise repeated fake and real tagged-engine runs, repeat export, independent package
+verification, serial full-suite runs, reversed file order, and branch-aware coverage. This design
+does not claim bit-identical executables across compilers or remove meaningful provenance to create
+an artificial deterministic result.

docs/ENGINE_INTEGRATION_CONTRACT.md

@@ -1,23 +1,51 @@
-# Future Engine Integration Contract
+# C++ Engine Integration Contract
 
-The protected dependency is `cpp-event-driven-backtester` release `v1.0.0`.
+The protected numerical dependency is `MrithunjoyB/cpp-event-driven-backtester` release `v1.0.0`:
 
-- Annotated tag object: `20ac53c5e4b61ae7b431d5bb263f246e35f8d2a2`
-- Release commit: `2f86b71dbc9f29dbda861942d8afbb10c04b6625`
-- Integration status: disabled in Phase 1
+- annotated tag object: `20ac53c5e4b61ae7b431d5bb263f246e35f8d2a2`;
+- peeled release target: `2f86b71dbc9f29dbda861942d8afbb10c04b6625`;
+- invocation contract: `1.0`;
+- numerical methodology: `causal_daily_v3_stochastic_v2`;
+- stable RNG identity reported by the executable: `portable_bounded_v1`.
 
-The future read-only adapter may invoke only reviewed argument arrays for the documented
-`validate-config`, `print-resolved-config`, `run --dry-run`, and `run` CLI forms. It must never accept
-a command string or shell expansion. Inputs and outputs use explicit normalized paths inside an
-isolated run directory. The adapter must confirm the release identity, executable digest, resolved
-configuration, input and manifest hashes, output inventory, schemas, validator results, and
-provenance before producing evidence.
+The Phase 2A adapter is research-only and read-only. It neither changes nor builds inside the
+protected sibling checkout. A separately reviewed executable is supplied with an expected SHA-256,
+and all experiment outputs go to an isolated `quantforge-engine-*` directory outside both
+repositories.
 
-The C++ release is the numerical authority. An LLM cannot modify engine source, configuration after
-constitution lock, canonical outputs, manifests, or validators. Failed schemas, hashes, provenance,
-or reconstruction produce failed evidence; they are never repaired by prose. The sibling repository
-must not be a writable submodule or copied implementation.
+## Exact allow-list
 
-This contract is derived read-only from release documentation at `v1.0.0`, including
-`docs/CONFIGURATION.md`, `docs/RESULT_SCHEMA.md`, and `docs/REPRODUCIBILITY.md`. No adapter code or
-engine source is copied here.
+The adapter has no command-string API. It executes argument vectors corresponding only to:
+
+```text
+quant_cli version
+quant_cli validate-config --config configs/portfolio_equal_weight.json
+quant_cli print-resolved-config --config configs/portfolio_equal_weight.json
+quant_cli run --config configs/portfolio_equal_weight.json --dry-run
+quant_cli run --config configs/portfolio_equal_weight.json --execution-mode serial --threads 1
+python scripts/validate_results.py
+```
+
+The `python` label documents the normalized contract; execution uses the current trusted Python
+interpreter and the release validator copied from the verified tag. Processes use `shell=False`, an
+explicit working directory, stdin isolation, a minimal environment, `C` locale, UTC timezone,
+timeouts, output caps, process-group termination, and return-code checks. Arbitrary arguments,
+configuration paths, input paths, commands, environment inheritance, and symlinks are rejected.
+
+## Identity and staging
+
+Before every identity query or run the adapter checks the approved remote, clean tracked tree,
+annotated tag object, peeled target, release-relative config/input/validator diff, executable regular
+file and executable bit, executable size/digest, version, methodology, and RNG lines. The only inputs
+are the fixed equal-weight config and six public synthetic files. Each is copied with no-follow and
+inode/replacement checks, bounded size, exclusive destination creation, and `fsync`.
+
+Successful execution alone is insufficient. Admission additionally requires the exact config/input
+semantic and byte hashes, a complete bounded output inventory, supported JSON/CSV schema versions,
+the release `validate_results.py` result, finite decimal facts at declared CSV locations, closed
+units, and methodology metadata. The resulting bundle must match the locked constitution, case,
+workflow revision, amendment-chain head, engine identity, and prior-bundle head.
+
+The C++ engine remains authoritative for numerical values; QuantForge validates and cites those
+values without recalculating or strengthening them. Failed identity, schema, validation, provenance,
+or inventory checks fail closed and cannot be repaired by prose.