Implement retention namespace generation transitions

.github/workflows/ci.yml

@@ -69,6 +69,9 @@ jobs:
       - name: Test documentation
         run: cargo test --workspace --doc --locked
 
+      - name: Build documentation
+        run: cargo doc --workspace --no-deps --locked
+
       - name: Check MSRV contract
         run: cargo +1.96.0 check --workspace --all-targets --all-features --locked
 

.gitignore

@@ -29,3 +29,9 @@
 *.swp
 *.swo
 *~
+
+# Local mktxt repository snapshots (exceed the documentation corpus byte budget)
+/keep.txt
+
+# Local agent journals (code-smell and cool-idea logs); never tracked.
+.claude/

conformance/segment-store/v2/ORIGIN.md

@@ -0,0 +1,67 @@
+# Version 2 Corpus Origin
+
+The corpus was constructed on 2026-07-29 with:
+
+- `rustc 1.96.0 (ac68faa20 2026-05-25)`;
+- `cargo 1.96.0 (30a34c682 2026-05-25)`; and
+- `b3sum 1.8.5`.
+
+## Independent inputs
+
+The oracle imports exact bytes only from these previously accepted fixtures:
+
+- `conformance/segment-store/v1/one-zero-segment.hex`;
+- `conformance/segment-store/v1/one-zero-catalog.hex`;
+- `conformance/segment-store/v1/one-zero-head.hex`;
+- the one-zero `BlobId` canonical text and `LayoutId` binary identity from
+  `conformance/layout/v1/layouts.tsv`.
+
+It parses the version-1 head coordinate, catalog predecessor, and segment and
+catalog semantic digests directly from fixed offsets. The oracle constructs the
+59-byte `BlobId` from the accepted binary grammar and verifies its length and
+digest against the layout table; the table directly supplies the 60-byte
+`LayoutId`. It does not call a production encoder, decoder, retention type,
+migration adapter, serializer, or filesystem implementation.
+
+## Definition verification
+
+The profile digest was checked independently with:
+
+```bash
+{
+  printf 'keep.retention-realization-profile/v1\0'
+  cat conformance/segment-store/v2/retention-profile.tsv
+} | b3sum --no-names
+```
+
+Exact output:
+
+```text
+db1c1c1a50613ef11f7c0ee0882e37b6d24e2db2ca57783d01197ba51b61ce59
+```
+
+The format-definition digest was checked independently with:
+
+```bash
+{
+  printf 'keep.segment-store-definition/v2\0'
+  cat conformance/segment-store/v2/definition.tsv
+} | b3sum --no-names
+```
+
+Exact output:
+
+```text
+32381f1ac332d1277a7e1faf8f11576993cb55b7e85d2a110b74dc9c3b873427
+```
+
+## Materialization boundary
+
+A temporary ignored Rust test wrote the initially reviewed TSV and hexadecimal
+artifacts from the handwritten oracle. That write path was removed immediately
+after materialization. The committed oracle is read-only and rejects drift.
+
+Changing any fixture requires a deliberate specification change, an updated
+definition or profile digest when affected, fresh independent construction,
+and review of every dependent migration and retention coordinate. A fixture is
+never regenerated to make a production implementation pass.

conformance/segment-store/v2/README.md

@@ -0,0 +1,74 @@
+# Durable Segment Store Version 2 Corpus
+
+This corpus freezes independent canonical inputs and golden bytes for
+`keep.segment-store/v2`. It proves the written format has one executable byte
+interpretation. It does not prove that a production encoder, decoder,
+migration, retention transition, or garbage collector exists.
+
+## Corpus files
+
+| File | Contract |
+| --- | --- |
+| `definition.tsv` | Sorted format-definition key/value bytes |
+| `retention-profile.tsv` | Registered realization-profile definition |
+| `inventory.tsv` | Canonical one-segment, one-catalog migration inventory |
+| `migration-source.tsv` | Exact version-1 and derived migration coordinates |
+| `artifacts.tsv` | Golden artifact lengths, digests, checksums, and filenames |
+| `format-marker.hex` | Canonical 96-byte `FORMAT` record |
+| `migration-intent.hex` | Canonical 256-byte migration intent |
+| `migration-receipt.hex` | Canonical 256-byte migration receipt |
+| `one-anchor-root.hex` | Generation-1 root with one nontext namespace |
+| `one-root-manifest.hex` | Generation-1 one-namespace manifest |
+| `one-root-head.hex` | Generation-1 retention head |
+| `ORIGIN.md` | Construction provenance and verification boundary |
+
+Every text file uses UTF-8 or ASCII, LF line endings, and one final newline.
+Every hex fixture is one lowercase hexadecimal line with one final newline.
+In `artifacts.tsv`, `bound_digest_hex` is the marker content digest for
+`format-marker`, the intent digest for `migration-intent`, the referenced
+intent digest for `migration-receipt`, the canonical record digest for
+`retention-root` and `retention-manifest`, and the referenced manifest digest
+for `retention-head`.
+
+## Frozen identities
+
+The realization-profile digest is
+`db1c1c1a50613ef11f7c0ee0882e37b6d24e2db2ca57783d01197ba51b61ce59`.
+It hashes the exact `retention-profile.tsv` bytes under the registered profile
+domain.
+
+The format-definition digest is
+`32381f1ac332d1277a7e1faf8f11576993cb55b7e85d2a110b74dc9c3b873427`.
+It hashes the exact `definition.tsv` bytes under the registered format domain.
+The definition binds the profile digest, every named domain, magic, version,
+field order, record width, format limit, and migration synchronization mask.
+
+The migration fixture preserves the version-1 one-zero segment and generation-1
+catalog. Its canonical two-entry inventory digest is
+`40bf5d49c34847ac9cf46a256f343cee80cd980d1405d2dd02ceff8f58d674f9`.
+The derived logical store identifier is
+`0cd9d3dfbec9b349fe42d21475271b0e8de23c043440d6427a1c37898ad1dd79`.
+Fixture-only root device, mount, and file coordinates are `1`, `2`, and `3`;
+they bind in-place recovery but do not enter the logical store identifier.
+
+The retention fixture uses namespace bytes `00 2f ff`, proving the namespace is
+opaque and not a path or Unicode string. Its one anchor combines the canonical
+one-zero `BlobId` and `LayoutId` values from the existing layout corpus.
+
+## Verification
+
+Run:
+
+```bash
+cargo test --manifest-path xtask/Cargo.toml \
+  --test retention_store_v2_format_oracle
+```
+
+The test-only oracle constructs every record from handwritten offsets and
+domain preimages, compares exact fixture bytes and tables, and imports no
+production version-2 codec. The repository protocol and documentation gates
+route this corpus separately.
+
+Passing this corpus is necessary but insufficient for issue #19. Production
+code still needs parser, corruption, property, model, crash, recovery,
+concurrency, fuzz, and public API evidence.

conformance/segment-store/v2/artifacts.tsv

@@ -0,0 +1,8 @@
+keep.segment-store-v2.artifacts/v1
+case	kind	byte_length	generation	entry_count	bound_digest_hex	final_checksum_hex	fixture
+format-marker	format-marker	96	-	-	4b063c329085abdebe86b256d531b112c7ea33cb2f545caa40a7a869ff3337ce	06384cbaf2b69e0a12eeb2bf62df4c49e193d56f2bde940b3c5637320458abc1	format-marker.hex
+migration-intent	migration-intent	256	1	2	a15a00000219df20979da36419046eae9a0ba998645fbfe308ea4335a8326b44	7bec10cc8c1eef5ab0e8e8b6a33240bba291252d4263147df134062eb70d3f1f	migration-intent.hex
+migration-receipt	migration-receipt	256	1	2	a15a00000219df20979da36419046eae9a0ba998645fbfe308ea4335a8326b44	3a6a5f29bfafeffb9401de5ba814c09c345adbad69e8ba0531e3eb1ebb0b681d	migration-receipt.hex
+one-anchor-root	retention-root	378	1	1	ca4c11f265c3bed07073bdc3b6aef003e964ac8cb36fcfcc92f20fa6f0b60085	28c52ff0f8d6533234be083f425e921d699639e204e2c66dec0cae2ff0a2dc34	one-anchor-root.hex
+one-root-manifest	retention-manifest	296	1	1	f46b96a2bf3379320cf59e8af15b9d108de06025c415307b28953714bd7a80eb	10597643c3fc9485c7ecd3bb511d6726e726fd92f0f769a204b899c5fdc77d2c	one-root-manifest.hex
+one-root-head	retention-head	144	1	1	f46b96a2bf3379320cf59e8af15b9d108de06025c415307b28953714bd7a80eb	ac049edb33af7e957c6ff11ead7e1bcf9c40fa9793cc84979215ffbba5f630b7	one-root-head.hex

conformance/segment-store/v2/definition.tsv

@@ -0,0 +1,90 @@
+keep.segment-store.definition/v2
+key	value
+domain.empty-disposition-set	keep.empty-disposition-set/v2\0
+domain.format-definition	keep.segment-store-definition/v2\0
+domain.format-marker	keep.store-format-marker/v2\0
+domain.format-marker-checksum	keep.segment-store-marker-checksum/v2\0
+domain.gc-candidate-set	keep.gc-candidate-set/v2\0
+domain.gc-intent	keep.gc-retirement-intent/v2\0
+domain.gc-intent-checksum	keep.gc-retirement-intent-checksum/v2\0
+domain.gc-receipt-checksum	keep.gc-retirement-receipt-checksum/v2\0
+domain.initial-gc-state	keep.initial-gc-state/v2\0
+domain.initial-retention-state	keep.initial-retention-state/v2\0
+domain.migration-intent	keep.store-migration-intent/v2\0
+domain.migration-intent-checksum	keep.store-migration-intent-checksum/v2\0
+domain.migration-inventory	keep.store-v1-pool-inventory/v2\0
+domain.migration-receipt-checksum	keep.store-migration-receipt-checksum/v2\0
+domain.recovery-disposition-checksum	keep.recovery-disposition-receipt-checksum/v2\0
+domain.retention-anchor-set	keep.retention-anchor-set/v2\0
+domain.retention-head-checksum	keep.retention-head-checksum/v2\0
+domain.retention-manifest	keep.retention-manifest/v2\0
+domain.retention-manifest-checksum	keep.retention-manifest-checksum/v2\0
+domain.retention-manifest-entries	keep.retention-manifest-entries/v2\0
+domain.retention-namespace	keep.retention-namespace/v1\0
+domain.retention-profile	keep.retention-realization-profile/v1\0
+domain.retention-root	keep.retention-root/v2\0
+domain.retention-root-checksum	keep.retention-root-checksum/v2\0
+domain.store-identifier	keep.store-identifier/v2\0
+format.coordinate	keep.segment-store/v2
+format.marker.fields	magic:16,version:u16,record_length:u16,flags:u32,definition_digest:32,maximum_namespace_count:u32,reserved:u32,checksum:32
+format.marker.length	96
+format.marker.magic	KEEP:STORE:V2\0\0\0
+format.marker.version	2
+gc.intent.candidate-width	72
+gc.intent.fields	magic:16,version:u16,header_length:u16,flags:u32,total_length:u64,generation:u64,candidate_width:u16,reserved:u16,candidate_count:u32,liveness_generation:u64,manifest_digest:32,catalog_generation:u64,catalog_digest:32,profile_identity:u32,profile_version:u32,profile_digest:32,catalog_proof_digest:32,pool_digest:32,disposition_set_digest:32,reader_device:u64,reader_mount:u64,reader_file:u64,candidate_set_digest:32,candidates:count*72,intent_digest:32,checksum:32
+gc.intent.header-length	320
+gc.intent.magic	KEEP:GC:INTENT2\0
+gc.intent.maximum-candidates	65536
+gc.intent.maximum-length	4718976
+gc.intent.version	2
+gc.receipt.fields	magic:16,version:u16,record_length:u16,flags:u32,generation:u64,intent_digest:32,retired_set_digest:32,pool_state_digest:32,liveness_generation:u64,manifest_digest:32,catalog_generation:u64,catalog_digest:32,reader_device:u64,reader_mount:u64,reader_file:u64,synchronization_count:u64,reserved:48,checksum:32
+gc.receipt.length	320
+gc.receipt.magic	KEEP:GC:RECEIPT2
+gc.receipt.version	2
+migration.intent.fields	magic:16,version:u16,record_length:u16,flags:u32,catalog_generation:u64,catalog_length:u64,catalog_digest:32,predecessor_digest:32,inventory_digest:32,root_device:u64,root_mount:u64,root_file:u64,definition_digest:32,store_id:32,checksum:32
+migration.intent.length	256
+migration.intent.magic	KEEP:MIG:INT2\0\0\0
+migration.intent.version	2
+migration.inventory.entry-fields	kind:u8,reserved:7,catalog_generation:u64,artifact_length:u64,artifact_digest:32
+migration.inventory.entry-width	56
+migration.inventory.maximum-entries	2097152
+migration.receipt.fields	magic:16,version:u16,record_length:u16,flags:u32,intent_digest:32,store_id:32,format_marker_digest:32,initial_retention_digest:32,initial_gc_digest:32,disposition_set_digest:32,synchronization_mask:u64,checksum:32
+migration.receipt.length	256
+migration.receipt.magic	KEEP:MIG:REC2\0\0\0
+migration.receipt.synchronization-mask	0x00000000000003ff
+migration.receipt.version	2
+recovery.disposition.fields	magic:16,version:u16,record_length:u16,flags:u32,artifact_kind:u16,decision:u16,classification:u16,reserved:u16,artifact_length:u64,artifact_identity_digest:32,artifact_content_digest:32,publication_generation:u64,publication_checksum:32,catalog_generation:u64,catalog_digest:32,liveness_generation:u64,manifest_digest:32,reader_device:u64,reader_mount:u64,reader_file:u64,decision_evidence_digest:32,reserved:8,checksum:32
+recovery.disposition.length	320
+recovery.disposition.magic	KEEP:REC:DISP2\0\0
+recovery.disposition.maximum-receipts	65536
+recovery.disposition.version	2
+retention.anchor.fields	blob_id:59,layout_id:60
+retention.anchor.width	119
+retention.closure.maximum-depth	8
+retention.closure.maximum-encoded-bytes	16777216
+retention.closure.maximum-nodes	1048576
+retention.closure.maximum-physical-bytes	1073741824
+retention.head.fields	magic:16,version:u16,record_length:u16,flags:u32,liveness_generation:u64,manifest_length:u64,manifest_digest:32,predecessor_manifest_digest:32,reserved:u64,checksum:32
+retention.head.length	144
+retention.head.magic	KEEP:RET:HEAD2\0\0
+retention.head.version	2
+retention.manifest.entry-fields	namespace_digest:32,root_generation:u64,root_digest:32
+retention.manifest.entry-width	72
+retention.manifest.fields	magic:16,version:u16,header_length:u16,flags:u32,total_length:u64,liveness_generation:u64,entry_width:u16,reserved:u16,entry_count:u32,predecessor_digest:32,entry_set_digest:32,reserved:48,entries:count*72,manifest_digest:32,checksum:32
+retention.manifest.header-length	160
+retention.manifest.magic	KEEP:RET:LIVE2\0\0
+retention.manifest.maximum-entries	4096
+retention.manifest.maximum-length	295136
+retention.manifest.version	2
+retention.maximum-namespaces	4096
+retention.namespace.maximum-length	255
+retention.namespace.minimum-length	1
+retention.profile.digest	db1c1c1a50613ef11f7c0ee0882e37b6d24e2db2ca57783d01197ba51b61ce59
+retention.profile.identity	1
+retention.profile.version	1
+retention.root.fields	magic:16,version:u16,header_length:u16,flags:u32,total_length:u64,root_generation:u64,namespace_length:u16,anchor_width:u16,anchor_count:u32,profile_identity:u32,profile_version:u32,profile_digest:32,closure_node_limit:u64,closure_depth_limit:u16,reserved:u16,encoded_byte_limit:u64,physical_byte_limit:u64,predecessor_digest:32,anchor_set_digest:32,reserved:12,namespace:namespace_length,anchors:count*119,root_digest:32,checksum:32
+retention.root.header-length	192
+retention.root.magic	KEEP:RET:ROOT2\0\0
+retention.root.maximum-anchors	65536
+retention.root.maximum-length	7799295
+retention.root.version	2

conformance/segment-store/v2/format-marker.hex

@@ -0,0 +1 @@
+4b4545503a53544f52453a5632000000000200600000000032381f1ac332d1277a7e1faf8f11576993cb55b7e85d2a110b74dc9c3b873427000010000000000006384cbaf2b69e0a12eeb2bf62df4c49e193d56f2bde940b3c5637320458abc1

conformance/segment-store/v2/inventory.tsv

@@ -0,0 +1,4 @@
+keep.segment-store-v2.inventory/v1
+kind	generation	byte_length	artifact_digest_hex	source_fixture
+segment	0	337	b7542dced2ab770894a14d1d04b066e3a899942602c5986d35ba6df6c1a35cfc	one-zero-segment.hex
+catalog	1	352	04b82519b0399baefd0b9c0f32a871052e4c47e3a00226ab03b21661470f7320	one-zero-catalog.hex

conformance/segment-store/v2/migration-intent.hex

@@ -0,0 +1 @@
+4b4545503a4d49473a494e543200000000020100000000000000000000000001000000000000016004b82519b0399baefd0b9c0f32a871052e4c47e3a00226ab03b21661470f7320000000000000000000000000000000000000000000000000000000000000000040bf5d49c34847ac9cf46a256f343cee80cd980d1405d2dd02ceff8f58d674f900000000000000010000000000000002000000000000000332381f1ac332d1277a7e1faf8f11576993cb55b7e85d2a110b74dc9c3b8734270cd9d3dfbec9b349fe42d21475271b0e8de23c043440d6427a1c37898ad1dd797bec10cc8c1eef5ab0e8e8b6a33240bba291252d4263147df134062eb70d3f1f

conformance/segment-store/v2/migration-receipt.hex

@@ -0,0 +1 @@
+4b4545503a4d49473a524543320000000002010000000000a15a00000219df20979da36419046eae9a0ba998645fbfe308ea4335a8326b440cd9d3dfbec9b349fe42d21475271b0e8de23c043440d6427a1c37898ad1dd794b063c329085abdebe86b256d531b112c7ea33cb2f545caa40a7a869ff3337ced52f1f022edb1de7b840c5bf8fb55de7932ca69370ae85e2bee4179143792bc3ba0ea200a5b06741564c43a79a91945bef0b0fac51c960ea4f8207094f3e1e31a80259fcd1237203ea6c6cc5065514abdeb01da603c3194b096a045cf694c95a00000000000003ff3a6a5f29bfafeffb9401de5ba814c09c345adbad69e8ba0531e3eb1ebb0b681d

conformance/segment-store/v2/migration-source.tsv

@@ -0,0 +1,3 @@
+keep.segment-store-v2.migration-source/v1
+case	catalog_generation	catalog_length	catalog_digest_hex	predecessor_digest_hex	inventory_digest_hex	definition_digest_hex	store_id_hex	root_device	root_mount	root_file
+one-zero	1	352	04b82519b0399baefd0b9c0f32a871052e4c47e3a00226ab03b21661470f7320	0000000000000000000000000000000000000000000000000000000000000000	40bf5d49c34847ac9cf46a256f343cee80cd980d1405d2dd02ceff8f58d674f9	32381f1ac332d1277a7e1faf8f11576993cb55b7e85d2a110b74dc9c3b873427	0cd9d3dfbec9b349fe42d21475271b0e8de23c043440d6427a1c37898ad1dd79	1	2	3

conformance/segment-store/v2/one-anchor-root.hex

@@ -0,0 +1 @@
+4b4545503a5245543a524f4f54320000000200c000000000000000000000017a000000000000000100030077000000010000000100000001db1c1c1a50613ef11f7c0ee0882e37b6d24e2db2ca57783d01197ba51b61ce59000000000000000400020000000000000000100000000000000010000000000000000000000000000000000000000000000000000000000000000000227f6333d1bcc380899ba25903b5d7d2b8804cc828e8f580b5876b0677d024f5000000000000000000000000002fff4b4545503a424c4f423a49440000000000010100000000000000011cfb8fa9e917aba15a1f592095f377ff180755fe1212b0d7d2ec750bd128b6064b4545503a4c41594f55543a494400000001000100000000000000dc887da23f1a7483359a78fc9a7fde80030ec2c4690603803f0ab7d0edb56575b8ca4c11f265c3bed07073bdc3b6aef003e964ac8cb36fcfcc92f20fa6f0b6008528c52ff0f8d6533234be083f425e921d699639e204e2c66dec0cae2ff0a2dc34

conformance/segment-store/v2/one-root-head.hex

@@ -0,0 +1 @@
+4b4545503a5245543a48454144320000000200900000000000000000000000010000000000000128f46b96a2bf3379320cf59e8af15b9d108de06025c415307b28953714bd7a80eb00000000000000000000000000000000000000000000000000000000000000000000000000000000ac049edb33af7e957c6ff11ead7e1bcf9c40fa9793cc84979215ffbba5f630b7

conformance/segment-store/v2/one-root-manifest.hex

@@ -0,0 +1 @@
+4b4545503a5245543a4c495645320000000200a0000000000000000000000128000000000000000100480000000000010000000000000000000000000000000000000000000000000000000000000000e763e4d12e1ed333daeb84cc6336d9c3262f639b9d410c0a69c8d23680e9049a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000ddde2ac65c5ba3829bf0fbd6f36e90272d69a0459fade92272b728a80d7ae6e20000000000000001ca4c11f265c3bed07073bdc3b6aef003e964ac8cb36fcfcc92f20fa6f0b60085f46b96a2bf3379320cf59e8af15b9d108de06025c415307b28953714bd7a80eb10597643c3fc9485c7ecd3bb511d6726e726fd92f0f769a204b899c5fdc77d2c

conformance/segment-store/v2/retention-profile.tsv

@@ -0,0 +1,3 @@
+keep.retention-realization-profiles/v1
+identity	version	canonical_name	witness_count	selection
+1	1	keep.retention-single-canonical-witness/v1	1	canonical-physical-catalog-coordinate

docs/formats/README.md

@@ -8,7 +8,8 @@ admitted merely because one Rust type can serialize and deserialize it.
 | Format | Coordinate | Status | Evidence |
 | --- | --- | --- | --- |
 | [Flat Chunk Layout v1](flat-chunk-layout-v1/README.md) | `keep.flat-chunks/v1` | Implemented through verified reconstruction in issues #10 and #13 | [Golden corpus](../../conformance/layout/v1/README.md) |
-| [Durable Segment Store v1](segment-store-v1/README.md) | `keep.segment-store/v1` | Specified in issue #14; segment I/O implemented in issue #15; publication and recovery remain in issues #16–#17 | [Golden corpus](../../conformance/segment-store/v1/README.md) |
+| [Durable Segment Store v1](segment-store-v1/README.md) | `keep.segment-store/v1` | Implemented through initialization, publication, restart, and recovery in issues #14–#17 | [Golden corpus](../../conformance/segment-store/v1/README.md) |
+| [Durable Segment Store v2](segment-store-v2/README.md) | `keep.segment-store/v2` | One-way migration, version-two reopen, and forward retention publication implemented; retention recovery, reader fencing, and collection planned in issue #19 | [Golden corpus](../../conformance/segment-store/v2/README.md) |
 
 The registry records protocol specifications, including formats whose
 implementation is still planned. Each format page states its exact proof