Initialize repository snapshot

spec/MAPPING.md

@@ -0,0 +1,36 @@
+# Blueprint → Code Mapping (v0)
+
+This document maps Blueprint objects to concrete modules/files and to the local SQLite ledger evidence they must produce.
+
+## Mapping Table
+
+| Blueprint object | Implementation location | Ledger tables touched | Proof artifacts emitted | Trace propagation rules |
+|---|---|---|---|---|
+| ProofRune | `ledger/db.py` (artifact hashing), `ledger/redact.py` (safe storage), engine scroll emitters | `proof_artifacts` | `proof_artifacts.kind=*` (file/hash recorded) | `proof_artifacts.trace_id` should match the initiating tool/MCP trace |
+| OuroborosReceipt (local seal bundle) | `cli/ledger.py` subcommand `seal` | `proof_artifacts` (and read-only queries over `tool_invocations`, `mcp_calls`) | `kind=ouroboros_seal_bundle` | Seal bundle should include selection (since/until/trace_ids) and record the sealing `trace_id` |
+| External anchor evidence | **Pipeline/ops**, recorded back into SQLite via CLI/tooling | `proof_artifacts` | `kind=external_anchor` (planned) | Anchor artifact must reference seal digest + seal artifact id/path |
+| ShadowReceipt | `ledger/schema/0003_shadow_receipts.sql` + `ledger/db.py` helper | `shadow_receipts` | Optional: `kind=shadow_receipt_attachment` for large payloads | `shadow_receipts.trace_id` must correlate to the considered action chain |
+| Guardian (generic) | `vaultmesh-guardian/` (Rust), `vaultmesh-offsec/`, `vaultmesh-observability/` (future), plus Python engines as needed | `tool_invocations`, `mcp_calls`, `proof_artifacts` | `kind=guardian_report`, `kind=guardian_policy_proposal` (planned) | Guardian-generated events must either reuse the upstream `trace_id` or emit a new trace id and link it in meta |
+| DEE proposal output | `engines/` (planned controller module) | `proof_artifacts` | `kind=dee_proposal` (planned) | Proposal artifacts must link to the evidence set used to produce them (seal ids, trace ids) |
+| Epoch (mode) | Stored as a field inside proposal/seal payloads; epoch changes logged as receipts (future) | `proof_artifacts` (and engine scrolls) | `kind=epoch_change` (planned) | Epoch changes must be sealed and externally anchored for high-impact transitions |
+| Autogene (read-only) | `engines/` (planned analytics job) | `proof_artifacts` | `kind=autogene_forecast`, `kind=autogene_recommendation` (planned) | Outputs must never trigger execution; they must be consumable as inputs to an approval gate |
+| Console receipt scroll + Merkle root | `engines/console/receipts.py` | (not SQLite by default) | Root file(s) under `receipts/**/ROOT.*.txt` | Seal bundles should include the root files as inputs; optional `proof_artifacts` rows can reference root files |
+| Approvals | `engines/console/approvals.py` (receipted), `cli/vm_cli.py` (entrypoint) | (scroll-based today; SQLite optional later) | Receipt types `console_approval_request` and `console_approval` | Approval decisions should carry the same `trace_id` as the action being approved (planned wiring) |
+| Local ledger introspection | `cli/ledger.py` | Read-only queries over `tool_invocations`, `mcp_calls`, `proof_artifacts` | None (unless exporting reports) | Reporting commands should preserve trace correlation when exporting artifacts |
+
+## SQLite Ledger Schema (Current)
+
+Defined in:
+- `ledger/schema/0001_init.sql` (tables)
+- `ledger/schema/0002_indexes.sql` (indexes)
+
+Tables:
+- `tool_invocations`
+- `mcp_calls`
+- `proof_artifacts`
+
+## Planned Additions (Not Yet Implemented)
+
+1) External anchoring capture:
+   - Insert `proof_artifacts.kind=external_anchor` referencing a prior `ouroboros_seal_bundle`
+   - Store RFC-3161 tokens and/or chain txids either embedded in `meta_json` or as file paths