Story 2052: The Context Engine's contracts — one seam, span-carrying, versioned, pure

🛰️ Satellite: the atom the whole engine points at

Everything in the engine — every card field, every assertion, every graph node and edge, every bundle item, every cited answer — points at ONE shape: source_span.v1. A span is a byte-exact address into documents.document_pages (never the synthesised document.md): a document, a page, a paragraph, a character range, and the verbatim quote those bytes contain. Build on that atom four layers of typed DTOs — cards (L1), evidence hits (L2), assertions and graph edges (L3), bundles (L4) — plus the seven tool result envelopes and the honesty types (EngineState, context_provenance). All of it lives in src/shared/context_contracts/, a package with no sqlalchemy, no boto3, no settings: brains import it as the single source of contract truth; the executors that fill it in live functions-side and arrive in sibling stories (CE-2…CE-24).

✈️ Airplane: the analogy — an exhibit tag on every fact

Think of a courtroom. Nothing is "in the record" until it carries an exhibit tag pointing at the exact page and line it came from; an assertion with no tag is inadmissible — the judge will not read it. SourceSpan is that exhibit tag. CitedValue[T] is a fact that cannot be filed without one: its spans field is min_length=1, so a cited value with an empty span list fails to construct — the "no naked strings" rule is enforced by the type system, not a downstream reviewer who might forget. The single carve-out is NonCitable (the card summary): display garnish, explicitly typed as tag-free, and by that same typing barred from ever entering a bundle item or a graph node as evidence.

            documents.document_pages  (the real record, byte-exact)
                        ▲
                        │  span_id = "sp1:{doc}:{page}:{block}:{start-end}"
                        │  + verbatim quote  (V-CITE byte match)
                   SourceSpan  ──────────── the exhibit tag
                   ▲    ▲    ▲    ▲    ▲
        CitedValue │    │    │    │    │  spans: min_length=1  (LAW)
       ┌───────────┴┐  ┌┴────┴┐  ┌┴──────┴─┐  ┌──────────┐
       │DocumentCard│  │Asser-│  │Chrono-  │  │EvidenceHit│
       │  (L1)      │  │tion  │  │logyEvent│  │  (L2)     │
       └────────────┘  │AssertionEdge (L3) │  └──────────┘
                       └───────────────────┘
                        assembled into ▼
                  ContextBundle (L4) ── sections carry EngineState + truncated

🔬 Microscopic: how each invariant is welded in

The whole package is thirteen small files; there is no logic to run, only shape to freeze. Each freeze is one line of Pydantic:

# _base.py — the frozen wire model every DTO extends
model_config = ConfigDict(extra="forbid", populate_by_name=True)
#   extra="forbid"  → an unknown field is contract drift, raises on validate

# source_span.py — the version pin + the provenance law
schema_version: Literal["source_span.v1"] = "source_span.v1"
#   a wrong version string ("source_span.v2") is rejected by the Literal
class CitedValue[T](ContractModel):
    spans: list[SourceSpan] = Field(min_length=1)   # empty list → ValidationError

# bundle.py — one section, mixed item types, still typed
BundleSectionItem = DocumentCard | ChronologyEvent | EvidenceHit | Assertion | ContradictionItem
#   pydantic's smart union re-hydrates each item to its OWN type through JSON —
#   distinct schema_version literals / required fields make discrimination safe

"Additive-only versioning" is not a comment, it is the shape: every carrier pins a schema_version Literal; new fields land as optional-with-default within a vN; a meaning change forks vN+1 beside the old one. And purity is proven, not asserted: a fresh interpreter imports the package and fails the test if sqlalchemy or boto3 ever appears in sys.modules — transitive leaks caught, not just direct imports.

What changed

Acceptance mapping

Deferred (sibling stories, not this Story)

CE-1 is contracts only. The stores and RLS (CE-2), the chunker + embed worker (CE-3), the retrieval + rerank service (CE-5), the Neptune graph substrate and tenancy helper (CE-8), the normalizer/judge/chronology writers (CE-9…CE-11), the bundle builder (CE-13), the broker pre-fetch (CE-14), and the cite endpoint (CE-17) all consume these shapes and are their own stories. A deliberate omission here: the span_id compose helper and byte-exact resolution belong with the store (CE-2's V-CITE reuse), not the pure DTO package.

Verification

uv run ruff check src/shared/context_contracts tests/unit/context_contracts
uv run ruff format --check src/shared/context_contracts tests/unit/context_contracts
uv run mypy src/shared/context_contracts          # local-only per AGENTS.md
uv run pytest tests/unit/context_contracts -q     # 55 passed
make openapi                                       # no drift — DTOs wired to no route yet

Recall in one sentence: CE-1 freezes the Context Engine's one shared seam — every fact carries a byte-exact exhibit tag it cannot be constructed without, every carrier pins its version, and the package stays pure so a brain can read a citation without importing a database.