Skip to main content

Ledger Boundary & Enforcement (Execution Truth)

This document defines how Evalium enforces the Execution Ledger boundary in code and schema. It is the operational companion to the invariants in docs/architecture/FOUNDATION.md.

Goal: make WORM (write-once, read-many) guarantees explicit and testable.

1) Canonical WORM Boundary​

Execution ledger data is append-only and never mutated in place.

1.1 Ledger tables (WORM enforced)​

These tables are considered Execution Ledger and must follow WORM rules:

  • submissions
  • submission_items
  • submission_score_versions
  • result_corrections
  • result_correction_batches
  • ledger_events (execution metadata)
  • audit_logs (operational accountability)
  • compliance_ledger (privacy/legal evidence)
  • evidence ledger events (when introduced)
  • ratification events (future)

1.2 Scaffolding tables (mutable by design)​

These tables are runtime scaffolding, not execution truth:

  • delivery_sessions
  • assignments
  • compliance_ledger_outbox (mutable status queue)
  • reporting read models (e.g., reporting.*)
  • auth/session tables

2) Enforcement Rules​

2.1 No destructive writes to ledger tables​

Ledger tables MUST NOT be updated or deleted for business logic changes. Corrections are additive:

  • scores → new submission_score_versions
  • answer corrections → new result_corrections
  • UI "edit" → amend event, not overwrite

Audit/compliance ledgers are append-only (no UPDATE/DELETE), with any corrections captured as new ledger events.

2.2 Ledger writes go through one canonical path​

All ledger writes must go through service-layer methods that:

  • accept scope via TxManager
  • validate snapshot presence
  • enforce context requirements when policy demands it

No direct handler writes to ledger tables.

2.3 Snapshots are required for execution​

version_snapshot is mandatory for submissions. Reporting and reconstruction must read from snapshots, not live authoring tables.

2.4 Keyed idempotency at write boundaries​

Durable/admin mutating endpoints must enforce keyed idempotency.

  • Idempotency-Key is required for in-scope mutating operations
  • retries with the same key and payload replay prior response
  • key reuse with a different payload is rejected

This is required to preserve ledger integrity under client, network, or worker retries.

Policy reference: ➡️ docs/architecture/IDEMPOTENCY-AND-RETRY-POLICY.md

3) Test Gates (Non-Optional)​

3.1 WORM integrity checks​

Add tests that fail when a ledger table is mutated in place:

  • no direct UPDATE/DELETE allowed on ledger tables in service paths
  • remediation creates new rows, not overwrites

3.2 Snapshot completeness checks​

Tests must fail if version_snapshot is missing required fields for reporting or reconstruction (evaluation structure, questions, tags, scoring config).

4) Acceptance Criteria (Phase 0: Ledger Hardening)​

Phase 0 is considered complete only when all of the following are true:

  1. Canonical write path exists
    Ledger writes (submissions, submission_items, corrections) go through service‑layer methods only.

  2. Corrections are additive
    Score changes and remediation create new rows (e.g., score versions, corrections) rather than overwriting ledger truth.

  3. Snapshot completeness is enforced
    Tests fail when required snapshot fields are missing.

  4. WORM guardrails are tested
    Tests cover: “no destructive mutation for business corrections” and “amend/void semantics only.”

  5. Reporting uses snapshots
    Any reporting query that needs authoring data must read from version_snapshot, not live authoring tables.

  6. Idempotency is enforced at write boundaries
    Durable/admin mutating endpoints require keyed idempotency per policy and are covered by regression tests.

5) Migration Discipline​

  • Ledger tables change additively only (new columns, new tables).
  • Backfills must be idempotent and replayable.
  • Read models must remain FK-free to OLTP tables to avoid lock-order violations.

6) references​

  • docs/architecture/FOUNDATION.md (Execution Ledger invariants)
  • docs/architecture/architecture (Execution World)
  • docs/architecture/IDEMPOTENCY-AND-RETRY-POLICY.md (Keyed idempotency scope and implementation)
  • docs/product/implementation-status-feature-matrix.md (WORM scope)
  • docs/implementation/Defensibility-First-Engineering-Roadmap.md (Phase 0)