ADR 0039: Research Versions share Project publication authority

Implementation: Storage foundation in #1535; selected physical retention in #1536; public facade and bindings in #1537. #1350 remains the close gate.

Context

Checkpoint names retain whole generations and checkpoint restoration replaces the whole workspace. Neither behavior is a research Branch. Research needs independent immutable content identities, independently advancing context heads, and operation history which restoration cannot rewind. ADR 0018’s one publication authority and acknowledgement boundary still apply.

Decision

Add the mandatory research@1 capability and authenticated registry@1 JSON participant. It contains bounded immutable Version descriptors, context heads, retention roots and durable operation receipts. Every change carries the full current Project participant set through the existing writer-lock, validation, publication and recovery protocol. There is no second commit pointer.

A Version identifies frozen content, not its storage generation, checkpoint name, package digest or current head. Its content commitment includes the exact selected participant descriptors and complete-versus-projected scope. A projection identifies its source Version as provenance and has a distinct identity; conflicting content under an existing Version identity is rejected. The descriptor records producer and required capability identities. Unsupported readers fail closed; no pre-v1 migration or perpetual reader compatibility is promised.

Context heads select immutable Versions. Restoring a context publishes a new Version and advances only that context’s head. Other heads, retained Versions, and current operation/acceptance history remain unchanged. These storage contexts are foundation fixtures until the Branch lifecycle owns their public meaning. Project-level restoration must explicitly replace Project research content and retain current history; legacy whole-workspace checkpoint revert must not rewind a research registry.

The Project-level scope, implemented by the public integration in #1537, is the complete frozen Project participant set (graph, research metadata, ontology composition, Sources/Artifacts and local change records). It must preserve stable Project identity and current research registry, independent context heads, receipts and accepted provenance. Context restoration in #1535 changes only that context head and its frozen content reference; it does not replace the live Project’s participant set.

The Source/Artifact owner supplies the exact evidence dependency closure to the storage operation. Storage authenticates local digest/length references and marks their objects during cleanup. External-only and unverifiable references remain explicit frozen disclosures and are never fetched. This keeps domain ledger interpretation out of storage; facade integration must collect the complete owner-validated closure before invoking the primitive.

Receipts are outside Version-frozen content. Exact operation retries return the original receipt after subsequent publications and restoration. Changed request content under an operation identity returns GF_IDEMPOTENCY_CONFLICT. Pre-linearization failures leave prior state; post-linearization errors retain the existing truthful committed diagnostic and reconciliation through reopen. Receipt retention lasts for the Project’s lifetime, with an explicit finite registry capacity and resource-limit refusal before mutation. There is no implicit expiry or checkpoint-tombstone replay window. Receipt retention alone does not claim perpetual availability of released Version payloads. Accepted contribution deduplication remains a separately retained dependency owned by the later Proposal implementation.

Retention and staged implementation

Retained Versions and context heads are roots. Required references must exist and agree with their immutable identity; provenance-only identifiers are not additional roots. Deletion reports actual head/root blockers. Local evidence and ontology participants are retained with graph content; external-only bytes remain external and are never fetched as a historical replacement.

The foundation conservatively pins each Version’s authenticated source generation. This makes foundation publication/reopen safe but does not meet #1350’s bounded selected-retention criteria. #1536 must replace that physical representation with selected closure and repacking, prove increasing-parent and increasing-history retained bytes, and preserve these identity, history and restoration rules. #1350 cannot close on the foundation alone.

Alternatives and consequences

Reusing checkpoint names would conflate mutable naming with immutable identity and whole-workspace restoration with context restoration. A separate Branch container would introduce a second publication authority. Both conflict with the existing requirements, so neither is used.

The bounded registry adds metadata publication cost. Explicit capacity refusal is preferable to silently losing replay or accepted provenance. Later storage representation changes must be versioned and must not weaken authentication, root closure or truthful commit reporting.

Selected content amendment (#1536)

Research capability and registry revision 2 add authenticated per-Version CAS materialization markers and optional graph selection commitments. Revision 1 readers must refuse revision 2. No migration command or compatibility promise is added. New publications use revision 2.

A materialized Version keeps its immutable identity and exact participant commitments. Its source generation identifies origin but no longer grants physical retention: the registry now roots the committed participant CAS objects, their graph manifest closure, and local evidence objects. This map is physical placement metadata outside the Version identity. Complete Versions retain complete content; projected Versions retain only their selected content. Compaction publishes placement changes and its receipt through CURRENT before cleanup can reclaim an ancestor. Checkpoints and configured ancestor windows continue to retain their expressly selected whole generations.

A graph projection has a separate Version identity and records its selector, closure and logical graph fingerprint. Native graph projection rewrites shared Parquet units to selected rows, preserving required endpoint and catalog closure. Non-graph participant and evidence selection stays explicit and must be owner-validated. Genealogy alone never becomes a required-content edge. Creation evidence distinguishes read/scanning work from copied and retained payload bytes; reading a shared parent does not claim constant-time selection.

Exact inspection pins the registry generation until participant bytes and local evidence are authenticated. Historical graph materialization uses only that retained inventory and cannot expand through a live ancestor. Corrupt or missing required CAS objects refuse cleanup before destructive work.

Public Project restoration (#1537)

Project restoration explicitly replaces all frozen non-history Project research participants (graph, ontology/configuration, research metadata and domain ledgers) from a complete retained Version. It preserves the current research registry, other context heads, roots, permanent identities/receipts and the workspace restoration-transition history. A projection is not a complete Project restore source. The context-only restoration primitive remains separate for future Branch owners. Both publish the new Version and receipt atomically through CURRENT; an exact replay never reinstalls historical current state.

Public preparation freezes source selection and owner-derived Artifact closure before commit. Committing that exact prepared request preserves stable retry content after later Project changes or payload release. Historical native views materialize retained participants and graph/evidence into private temporary containers; their temporary storage identity is not the immutable citation.