Lineage stage 1: extract and qualify the pure exact-head contract

[jeffhuber]

Part of #963, stabilization epic #979, and roadmap #900. Stage 1 before #991 trusted publication and #992 atomic consumer activation.

Revised approach after contract review

Unaccepted prototypes #989 and #993 remain preserved and unmerged. The complete #993 review confirmed surviving falsey-history convenience paths, unnormalized stored episode lanes, and renderer chains lacking one immutable target. Stop further revisions of #993; rebuild a deliberately small pure core from accepted main in a fresh Codex-source PR, independently reviewed by qualified Claude.

Reuse schema fixtures and confirmed regressions, not prototype helpers or serial repair commits. Remove optional-context, generic evidence-composer, REST-history selector and environment-loading convenience APIs. Live accepted consumer behavior remains unchanged until #992.

Small explicit contract

• Target: immutable validated repo, positive non-boolean integer PR number, nonempty valid branch, full canonical SHA. Exact resolution never falls back. Identity-only resolution is a separate explicit API with no evidence argument.
• Episode: direct construction and mapping ingestion share validation/canonical stored values. Metadata-only target, lane/head binding and verified handoff/continuation shapes.
• Identity: one immutable canonical normalization of account/branch aliases, insertion-order-independent conflict refusal, longest prefix, declared policy-field preservation and canonical own-reviewer floor. No environment input or arbitrary opaque mutable configuration. Immutable branch binding preserves exact case separately from prefix-signal normalization.
• History and Authorities: explicit validated raw comments/pages; malformed present shapes/fields reject before normalization/trust. Genuine [], supported user:null and omitted optional body remain valid. Unavailable history is distinct from successful empty history. Marker authority is a separate explicit immutable account set, never inferred from identity authors.
• Chain: exact Target-bound empty or ordered nonempty chain from at most560 raw arrivals before deduplication, at most32 distinct contiguous episodes, one immutable repo/PR/branch, verified continuity and writer states. Parsing retains raw cumulative arrivals until one owning chain validator deduplicates; no composer resets the budget. Stale head waits and cannot admit.
• Resolve/parse/render/admit: one Chain factory owns raw-arrival validation/budget/deduplication; exact resolution uses that Chain's own Target with no raw-evidence overload or competing Target argument. One canonical full decision includes branch conflicts with zero episodes; strict announced complete unique-key/nonempty marker grammar; unrelated/untrusted comments confer no authority; rendering accepts only a validated nonempty Chain and never truncates; admission compares canonical reviewer/contributors and resolved decision.

One owning pure module plus standalone mirror is preferred. No store, environment, filesystem, network, provider, publisher or mutation dependencies. No legacy facade unless its explicit-input invariants exactly match. Keep the live tools/decisions.py adapter unchanged for #992.

Reviewable delivery and convergence

One fresh isolated Code Mower Codex writer from accepted main and one draft PR closing #990, Refs #963. Independent contributor-excluded Claude review must demonstrably read the entire exact diff/source. Target <=10 changed files and <=180,000 base-to-head diff bytes including tests, enforced before push; no automatic cap increase. A spec contradiction or scope overage stops before push for a decomposition decision. Use finite supervised source duration/output controls; Codex CLI has no native USD cap, so do not claim dollar enforcement. No hosted Devin create allowance.

Owning tests are unittest-native with isolated fixtures. Cover constructor/factory canonical equality, strict target versus explicit identity-only, aliases in both orders, zero-episode branch conflicts, valid recorded takeover/stale head, malformed and nullable raw history/pages, strict marker grammar/trust, common-target chain, full528+32 cumulative replay,561duplicate refusal before dedup and bounded consumption, renderer roundtrip/refusal, pure/transitive import boundary, mirror parity, and actual isolated init-materialized import/parse/resolve with package/repo source unavailable.

After clean Code Mower delivery: deterministic pure matrix, exact Ruff/privacy/package guard/readiness, canonical manifest regeneration equality, one exact CI-style full unittest discovery, one complete independent exact-head audit, full CI and authoritative gate, source quiescence/lease closeout. New broad design findings stop for assessment; no automatic repair loop. #990 accepts only the core; #963 remains open through #991/#992 and final consumer matrix. #915 still owns published-package pin/artifact qualification.

[jeffhuber]

Code Mower implementation work order for #990 (Refs #963).

Claude Code is the sole source author on claude/990-pure-lineage-contract, starting from accepted main db4506d2b3232e4c6a7c5683251eeb536b2b8355; Codex brokers delivery. The preserved #989 candidate is historical extraction evidence, not accepted code or review approval.

Deliver only the dependency-free pure episode/resolver, strict marker/raw-comment/page parsing, configured identity/branch/trust contracts, owning pure regressions, and required canonical/tool/package materialization. Environment, private store, GitHub/provider I/O, publication/label mutations and live consumer activation are deferred. Pure test fixtures must not import later-stage adapters.

One bounded source episode: maximum $30 and 45 minutes. Stop before push for scope adjustment if the complete diff exceeds 250,000 bytes or 15 changed files. One draft PR with Closes #990 and Refs #963, actual Claude builder provenance, focused/unittest/Ruff/privacy/package checks, then independent Codex review of the immutable complete head. Root owns merge. No hosted Devin creates.

[jeffhuber]

Fresh Codex-source replacement for #990, Refs #963, from accepted main. Prior #989 and #993 remain unaccepted evidence; this is a new implementation and new draft PR.

The typed pure contract is deliberately small: immutable validated Target, canonical Episode and Identity, explicit History and Authorities, and a sole target-bound Chain factory. Exact resolution consumes the Chain's own Target; explicit identity-only resolution accepts no evidence. Parsing preserves bounded raw cumulative arrivals; only the Chain factory deduplicates. Rendering accepts a validated nonempty Chain only. No legacy context, optional-history, composer, environment-selector, provider, publisher or live-consumer integration.

Owning unittest regressions cover canonical construction, aliases, exact binding and branch case, all contributors, raw transport validation, strict trusted markers, the 560-arrival limit, mixed-target refusal, and actual isolated init-materialized import/parse/resolve. Preserve package parity and existing live behavior.

One fresh Code Mower Codex source writer, configured model/settings, accepted bounded permission profile and canonical Python parity. The runtime Git-write/guard/outside-write probe and fresh builder admission must pass before execution. Supervision is capped at 30 minutes with finite output; no native USD cap is claimed. Pre-push enforces at most 10 files and 180,000 diff bytes, the pure scope and the tools/decisions.py exclusion. No cap increase or source repair loop is automatically authorized.

After clean delivery: canonical focused checks/guards/manifest, sole full unittest discovery, independent qualified Claude review of the complete immutable diff, CI/gate and lease closeout. Keep the PR draft; root owns merge.