Merge pull request 'TS: write_admitted / error.v1 decoder, WriteTracker, vector replay runner' (#62) from libby/ts-write-receipt-client into main

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.github/workflows/cultmesh-portability.yml

@@ -9,44 +9,6 @@ on:
   workflow_dispatch:
 
 jobs:
-  getting-started:
-    name: ${{ matrix.os }} one-command multiplayer onboarding
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [windows-latest, ubuntu-latest]
-
-    steps:
-      - name: Check out CultLib
-        uses: actions/checkout@v4
-        with:
-          path: CultLib
-
-      - name: Check out the matching Eve contract
-        uses: actions/checkout@v4
-        with:
-          repository: GameCult/Eve
-          # Eve main is the contract this sample is written against; the codex
-          # branch this used to pin was never merged and stopped on 2026-08-25.
-          ref: ${{ vars.EVE_INTEGRATION_REF || 'main' }}
-          path: Eve
-
-      - name: Set up .NET
-        uses: actions/setup-dotnet@v4
-        with:
-          dotnet-version: 10.0.x
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
-      - name: Run the documented one-command checkpoint
-        shell: pwsh
-        run: ./CultLib/scripts/verify-eve-getting-started.ps1 -EveRoot ./Eve
-
   reactive-and-resource-lifetime:
     name: ${{ matrix.os }} reactive semantics and leases
     runs-on: ${{ matrix.os }}
@@ -54,7 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-latest, ubuntu-latest]
+        # The forge runner is Ubuntu-only: Windows legs run on workflow_dispatch (GitHub or a Windows runner), Ubuntu gates push and PR.
+        os: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '["windows-latest", "ubuntu-latest"]' || '["ubuntu-latest"]') }}
 
     steps:
       - name: Check out CultLib
@@ -114,6 +77,11 @@ jobs:
       - name: Verify the CultCache document owner with the TypeScript cache
         run: npm run test --workspace packages/cultcache-ts
 
+      # Packs the four TypeScript packages and installs them into a clean consumer, so a package that builds but does
+      # not install or load fails here.
+      - name: Verify the packed TypeScript packages install and load from a clean consumer
+        run: npm run test:pack:ts
+
       - name: Verify the CultMesh authority rules with the TypeScript verifier
         run: npm run test --workspace packages/cultnet-ts
 

.github/workflows/cultnet-interop.yml

@@ -1,10 +1,9 @@
 name: CultNet cross-runtime interop
 
+# workflow_dispatch only: this job is Windows-only (pwsh Kotlin build, setup steps), and the forge
+# runner is Ubuntu-only, so a push or pull_request trigger would queue a job that can never run.
+# Run it from GitHub or any Windows runner.
 on:
-  push:
-    branches:
-      - main
-  pull_request:
   workflow_dispatch:
 
 jobs:

.github/workflows/publish-packages.yml

@@ -8,15 +8,26 @@ name: Publish packages
 # directly, which is already how Ghostlight, Epiphany, CodexConnector and Odin
 # consume the core stack.
 #
-# Tag a release to publish, for example `cultcache-ts-v0.13.6` or
-# `cultnet-py-v0.1.0`. The tag's version must match the version in the package
-# manifest; scripts/release-after-suite.mjs refuses the release otherwise rather
-# than shipping a mislabelled artifact.
+# Tag a Python release to publish, for example `cultnet-py-v0.1.0`. The tag's
+# version must match the version in the package manifest;
+# scripts/release-after-suite.mjs refuses the release otherwise rather than
+# shipping a mislabelled artifact.
+#
+# npm publishing of @gamecult/cultcache-ts is deliberately off: `cultcache-ts-v*`
+# is not a tag trigger until it is ruled on (the cultcache-ts job below runs from
+# workflow_dispatch only, which publishes nothing). A tag run uses the workflow
+# file at the tagged commit, not the one on main, so a tag on an older commit
+# (`cultcache-ts-v0.15.0` sits on 7d292085, before the guard) still runs that
+# commit's triggers and jobs. Read this file at the tagged sha before pushing a tag.
 
 on:
   push:
+    # cultcache-ts-v* is deliberately not a trigger: publishing @gamecult/cultcache-ts is disabled
+    # until it is ruled on, and whether NPM_TOKEN is set is unknown, so a pushed tag must not reach
+    # `npm publish`. The cultcache-ts jobs below still run from workflow_dispatch, which publishes nothing.
+    # (The comment sits above `tags:` because the tag-prefix pin in scripts/check-changelog-semver.test.mjs
+    # reads the list as `tags:` followed directly by its items.)
     tags:
-      - "cultcache-ts-v*"
       - "cultcache-py-v*"
       - "cultnet-py-v*"
       - "cultmesh-py-v*"

.gitignore

@@ -322,6 +322,10 @@ node_modules/
 !packages/cultmesh-browser/**
 !packages/cultmesh-kotlin/
 !packages/cultmesh-kotlin/**
+!packages/heimdall-delegation/
+!packages/heimdall-delegation/**
+!packages/heimdall-stake/
+!packages/heimdall-stake/**
 packages/**/node_modules/
 packages/**/dist/
 packages/**/dist-test/

CultLib.sln

@@ -35,10 +35,6 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GameCult.Networking.WebSock
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GameCult.Networking.WebSockets.Tests", "tests\GameCult.Networking.WebSockets.Tests\GameCult.Networking.WebSockets.Tests.csproj", "{B9A441EC-DADE-4500-B092-C635F3EB296A}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{5D20AA90-6969-D8BD-9DCD-8634F4692FDA}"
-EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "EveBrowserNetworkSample", "samples\eve-browser-network\EveBrowserNetworkSample.csproj", "{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}"
-EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "packages", "packages", "{809F86A1-1C4C-B159-0CD4-DF9D33D876CE}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "cultmath", "cultmath", "{B48EAE30-152F-01E3-6E31-82B350494D3C}"
@@ -49,6 +45,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CultMath.Tests", "packages\
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GameCult.Caching.ConsumerBuild", "tests\GameCult.Caching.ConsumerBuild\GameCult.Caching.ConsumerBuild.csproj", "{D3138F3C-9531-4906-A5D3-74BD857D0685}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GameCult.Caching.GeneratorConsumer", "tests\GameCult.Caching.GeneratorConsumer\GameCult.Caching.GeneratorConsumer.csproj", "{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GameCult.Caching.OutsideStoreTests", "tests\GameCult.Caching.OutsideStoreTests\GameCult.Caching.OutsideStoreTests.csproj", "{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -227,18 +227,6 @@ Global
 		{B9A441EC-DADE-4500-B092-C635F3EB296A}.Release|x64.Build.0 = Release|Any CPU
 		{B9A441EC-DADE-4500-B092-C635F3EB296A}.Release|x86.ActiveCfg = Release|Any CPU
 		{B9A441EC-DADE-4500-B092-C635F3EB296A}.Release|x86.Build.0 = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|x64.ActiveCfg = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|x64.Build.0 = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|x86.ActiveCfg = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Debug|x86.Build.0 = Debug|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|Any CPU.Build.0 = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|x64.ActiveCfg = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|x64.Build.0 = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|x86.ActiveCfg = Release|Any CPU
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB}.Release|x86.Build.0 = Release|Any CPU
 		{54D543F7-8EB7-4A11-977E-22D3EE2D8C3F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{54D543F7-8EB7-4A11-977E-22D3EE2D8C3F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{54D543F7-8EB7-4A11-977E-22D3EE2D8C3F}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -275,6 +263,30 @@ Global
 		{D3138F3C-9531-4906-A5D3-74BD857D0685}.Release|x64.Build.0 = Release|Any CPU
 		{D3138F3C-9531-4906-A5D3-74BD857D0685}.Release|x86.ActiveCfg = Release|Any CPU
 		{D3138F3C-9531-4906-A5D3-74BD857D0685}.Release|x86.Build.0 = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|x64.Build.0 = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Debug|x86.Build.0 = Debug|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|x64.ActiveCfg = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|x64.Build.0 = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|x86.ActiveCfg = Release|Any CPU
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B}.Release|x86.Build.0 = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|x64.Build.0 = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Debug|x86.Build.0 = Debug|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|x64.ActiveCfg = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|x64.Build.0 = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|x86.ActiveCfg = Release|Any CPU
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -294,10 +306,11 @@ Global
 		{21F26329-2119-4037-93CC-DD1801A1AB78} = {39D316AB-ABB5-49A2-8E83-CAF4C75B48F4}
 		{7F32D96B-AB5D-4A72-9217-B5DCCFEFC7E5} = {E733CBFF-42AE-4B6A-B5B9-0071ECFB45F1}
 		{B9A441EC-DADE-4500-B092-C635F3EB296A} = {39D316AB-ABB5-49A2-8E83-CAF4C75B48F4}
-		{5FA81CC7-87B2-4585-9D8E-9BBEC0AD85FB} = {5D20AA90-6969-D8BD-9DCD-8634F4692FDA}
 		{B48EAE30-152F-01E3-6E31-82B350494D3C} = {809F86A1-1C4C-B159-0CD4-DF9D33D876CE}
 		{54D543F7-8EB7-4A11-977E-22D3EE2D8C3F} = {B48EAE30-152F-01E3-6E31-82B350494D3C}
 		{FEF9DA88-2177-4FD0-885D-7096ACFA8A9D} = {B48EAE30-152F-01E3-6E31-82B350494D3C}
 		{D3138F3C-9531-4906-A5D3-74BD857D0685} = {39D316AB-ABB5-49A2-8E83-CAF4C75B48F4}
+		{1A75EA8F-00B3-49AB-8398-B1B7723BE10B} = {39D316AB-ABB5-49A2-8E83-CAF4C75B48F4}
+		{A54C2C29-941A-46A9-9DDE-9711B2F2EADD} = {39D316AB-ABB5-49A2-8E83-CAF4C75B48F4}
 	EndGlobalSection
 EndGlobal

README.md

@@ -1,5 +1,7 @@
 # CultLib
 
+**New here? Start at [`docs/start`](docs/start/README.md)**: a language x package matrix with tested first-call snippets.
+
 CultLib is GameCult's shared state, transport, and runtime substrate. It started
 as reusable C# game infrastructure, but the useful thing now is larger: typed
 `.cc` persistence, schema-stable wire formats, ergonomic reliable-UDP
@@ -30,6 +32,30 @@ bespoke JSON bridge at every boundary. A frontend is just another CultMesh
 client: the daemon publishes a typed Eve/CultUI surface, and any compatible
 runtime can lower that surface where it needs to live.
 
+## Entry Points
+
+- C# reference runtime: `src/` (`GameCult.Caching`, `GameCult.Networking`,
+  `GameCult.Mesh`, `GameCult.Geometry`, `GameCult.Unity`). Build and test with
+  `dotnet build CultLib.sln` and `dotnet test CultLib.sln`.
+- Other runtimes, wire-compatible with the C# CultCache: `packages/cultcache-ts`,
+  `cultcache-py`, `cultcache-rs`, and the CultNet and CultMesh packages beside
+  them under `packages/`; portable math in `packages/cultmath`.
+- Smallest working path: `src/GameCult.Mesh/docs/durable-node-quickstart.md`.
+  Application path: `src/GameCult.Mesh/docs/getting-started/README.md` and
+  `samples/eve-two-runtime`.
+
+## Live And Planned
+
+Live: typed CultCache persistence, CultNet schema-v0 transports and native RUDP,
+CultMesh nodes with Verse discovery, shard replication and authority leases,
+the geometry documents, and CultUI for Unity. The browser client boundary
+(`packages/cultmesh-browser`, `GameCult.Networking.WebSockets`) is proven on
+loopback under an explicit `local-development` trust policy by
+`samples/eve-browser-network`.
+
+Planned: a complete public Verse proof over deployed infrastructure; the
+remaining gates are listed in `src/GameCult.Mesh/docs/browser-verse-transport.md`.
+
 ## Which Package Do I Want?
 
 If the job is shared game state, start here before inventing a fourth drawer
@@ -72,7 +98,8 @@ start with the maintained
 series. Its first executable package-consumer checkpoint is
 [`samples/eve-two-runtime`](samples/eve-two-runtime/README.md).
 The real-process browser continuation is
-[`samples/eve-browser-network`](samples/eve-browser-network/README.md).
+[`samples/eve-browser-network`](samples/eve-browser-network/README.md); it
+needs a sibling Eve checkout (`--eve-root`) and is not in `CultLib.sln`.
 One documented command runs both layers:
 
 ```powershell
@@ -97,7 +124,6 @@ The solution includes:
 - `GameCult.Logging`: common logging abstraction plus console and file implementations
 - `GameCult.Caching`: `DatabaseEntry`-based cache, indexes, global entries, and backing-store abstractions
 - `GameCult.Caching.MessagePack`: MessagePack-backed persistence for the cache
-- `GameCult.Caching.NewtonsoftJson`: Newtonsoft.Json-backed persistence for the cache
 - `GameCult.Math` / CultMath: portable numeric primitives, deterministic random, noise, and shader-parity helpers
 - `GameCult.Geometry` / CultGeometry: engine-neutral geometry algorithms plus CultCache-native domain, selected-cut, and mesh artifact documents
 - `GameCult.Networking`: encrypted login/register/verify flows, schema-v0 contracts, transport adapters, and native RUDP sessions
@@ -125,7 +151,6 @@ src/
   GameCult.Logging/
   GameCult.Caching/
   GameCult.Caching.MessagePack/
-  GameCult.Caching.NewtonsoftJson/
   GameCult.Geometry/
   GameCult.Networking/
   GameCult.Networking.WebSockets/
@@ -344,7 +369,6 @@ Each subproject has a local README with package-specific detail:
 - [GameCult.Logging](src/GameCult.Logging/README.md)
 - [GameCult.Caching](src/GameCult.Caching/README.md)
 - [GameCult.Caching.MessagePack](src/GameCult.Caching.MessagePack/README.md)
-- [GameCult.Caching.NewtonsoftJson](src/GameCult.Caching.NewtonsoftJson/README.md)
 - [GameCult.Geometry](src/GameCult.Geometry/README.md)
 - [GameCult.Networking](src/GameCult.Networking/README.md)
 - [GameCult.Mesh](src/GameCult.Mesh/README.md)

contracts/cultmesh/content-vectors.cs-written.json

@@ -168,22 +168,22 @@
     {
       "label": "manifest",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJllNlAZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3Ns4ABAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzaU2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZpTZQGFhMTQ0NGJlNGI2NDA5OGY1ZGQ4NjNiNWIwYWM1NjE0ODBiM2ZiNWM0MWZjMDdjZjUwYTYyZWRjOTQxMjRiY2POAAwAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazphYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjlNlAMjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMs4AEAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOjI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDKU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOQgA=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NqYyNjIxNDSV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAyzgAQAADOAAQAANlPbWVzaDpjZG46Y2h1bms6MjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMqcxMDQ4NTc2ldlANTk5M2FjNjA0MDdlODY2MDE4NzNiYzM4ZWU2ZjhkYjNlYTkxMmU5ODc2MWNiNTU4YWI5Nzk1ZGIzMDZiNDc0Y84AFAAAzRLf2U9tZXNoOmNkbjpjaHVuazo1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjpzEzMTA3MjCQgA=="
     },
     {
       "label": "manifest_out_of_order",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY5TZQDMxYTFmOWRlYTAxNjk1NTEwOTJkMDVlOGJmNGE0NDYyMjhjOGMzZWI0YzliNzEzYzY2YWRjYjdmZDUzYzg5YmUAzgAEAADZT21lc2g6Y2RuOmNodW5rOjMxYTFmOWRlYTAxNjk1NTEwOTJkMDVlOGJmNGE0NDYyMjhjOGMzZWI0YzliNzEzYzY2YWRjYjdmZDUzYzg5YmWU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOU2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NpTZQDI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDLOABAAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazoyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAylNlAYzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZs4ACAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmM3ZjFiZGU5ZTFlZmE3ZDEzODVkNTFiMDc3ZWE4N2IwYzM4NjBkMjhkYTQzZDVkNmYyMjFlODQ1YzRjMjM2MGaQgA=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOnMTMxMDcyMJXZQGUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzbOAAQAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazplMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2pjI2MjE0NJXZQDI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDLOABAAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazoyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAypzEwNDg1NzaV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiQgA=="
     },
     {
       "label": "manifest_metadata_order",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJllNlAZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3Ns4ABAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzaU2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZpTZQGFhMTQ0NGJlNGI2NDA5OGY1ZGQ4NjNiNWIwYWM1NjE0ODBiM2ZiNWM0MWZjMDdjZjUwYTYyZWRjOTQxMjRiY2POAAwAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazphYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjlNlAMjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMs4AEAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOjI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDKU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOQg6R6ZXRhoTGlYWxwaGGhMqNtaWShMw=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NqYyNjIxNDSV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAyzgAQAADOAAQAANlPbWVzaDpjZG46Y2h1bms6MjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMqcxMDQ4NTc2ldlANTk5M2FjNjA0MDdlODY2MDE4NzNiYzM4ZWU2ZjhkYjNlYTkxMmU5ODc2MWNiNTU4YWI5Nzk1ZGIzMDZiNDc0Y84AFAAAzRLf2U9tZXNoOmNkbjpjaHVuazo1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjpzEzMTA3MjCQg6R6ZXRhoTGlYWxwaGGhMqNtaWShMw=="
     },
     {
       "label": "manifest_empty_body",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQC8YXBwbGljYXRpb24veC1jdWx0bmV0LXZlY3RvctkhMjAyNi0wOS0yMlQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZTZQGUzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUAANlPbWVzaDpjZG46Y2h1bms6ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NZCA"
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQC8YXBwbGljYXRpb24veC1jdWx0bmV0LXZlY3RvctkhMjAyNi0wOS0yMlQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZXZQGUzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUAANlPbWVzaDpjZG46Y2h1bms6ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NaEwkIA="
     }
   ]
-}
+}

contracts/cultmesh/content-vectors.rs-written.json

@@ -138,22 +138,22 @@
     {
       "label": "manifest",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJllNlAZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3Ns4ABAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzaU2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZpTZQGFhMTQ0NGJlNGI2NDA5OGY1ZGQ4NjNiNWIwYWM1NjE0ODBiM2ZiNWM0MWZjMDdjZjUwYTYyZWRjOTQxMjRiY2POAAwAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazphYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjlNlAMjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMs4AEAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOjI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDKU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOQgA=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NqYyNjIxNDSV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAyzgAQAADOAAQAANlPbWVzaDpjZG46Y2h1bms6MjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMqcxMDQ4NTc2ldlANTk5M2FjNjA0MDdlODY2MDE4NzNiYzM4ZWU2ZjhkYjNlYTkxMmU5ODc2MWNiNTU4YWI5Nzk1ZGIzMDZiNDc0Y84AFAAAzRLf2U9tZXNoOmNkbjpjaHVuazo1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjpzEzMTA3MjCQgA=="
     },
     {
       "label": "manifest_out_of_order",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY5TZQDMxYTFmOWRlYTAxNjk1NTEwOTJkMDVlOGJmNGE0NDYyMjhjOGMzZWI0YzliNzEzYzY2YWRjYjdmZDUzYzg5YmUAzgAEAADZT21lc2g6Y2RuOmNodW5rOjMxYTFmOWRlYTAxNjk1NTEwOTJkMDVlOGJmNGE0NDYyMjhjOGMzZWI0YzliNzEzYzY2YWRjYjdmZDUzYzg5YmWU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOU2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NpTZQDI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDLOABAAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazoyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAylNlAYzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZs4ACAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmM3ZjFiZGU5ZTFlZmE3ZDEzODVkNTFiMDc3ZWE4N2IwYzM4NjBkMjhkYTQzZDVkNmYyMjFlODQ1YzRjMjM2MGaQgA=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOnMTMxMDcyMJXZQGUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzbOAAQAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazplMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2pjI2MjE0NJXZQDI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDLOABAAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazoyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAypzEwNDg1NzaV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiQgA=="
     },
     {
       "label": "manifest_metadata_order",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaU2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJllNlAZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3Ns4ABAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOmUzMWJkYzYzNTc3ZmU3NmY2NDQxMDE0YWFhYTIyMjZkOWZmY2UxMWI0NGQwZDUxMGNhZGUxMzJiNzlmZDdkNzaU2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZpTZQGFhMTQ0NGJlNGI2NDA5OGY1ZGQ4NjNiNWIwYWM1NjE0ODBiM2ZiNWM0MWZjMDdjZjUwYTYyZWRjOTQxMjRiY2POAAwAAM4ABAAA2U9tZXNoOmNkbjpjaHVuazphYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjlNlAMjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMs4AEAAAzgAEAADZT21lc2g6Y2RuOmNodW5rOjI4MzE3MTU4NTlmMDFmM2Y5NjNkZDBmMTE5NGRiZGJiNzYwOTk5NzQyMzAxNWQzMWY2MDc5MTFlMWJmODY0MDKU2UA1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjzgAUAADNEt/ZT21lc2g6Y2RuOmNodW5rOjU5OTNhYzYwNDA3ZTg2NjAxODczYmMzOGVlNmY4ZGIzZWE5MTJlOTg3NjFjYjU1OGFiOTc5NWRiMzA2YjQ3NGOQg6R6ZXRhoTGlYWxwaGGhMqNtaWShMw=="
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZjRhZTJhN2M5NWY0ZDk2NjA1OGY3NWMxMzE4NWFhMGFiNmE5MWZjNWFmYWQ4ODYyOTZlZjJhZWU3NTVhMmFmMc4AFBLfvGFwcGxpY2F0aW9uL3gtY3VsdG5ldC12ZWN0b3LZITIwMjYtMDktMjJUMDA6MDA6MDAuMDAwMDAwMCswMDowMJaV2UAzMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJlAM4ABAAA2U9tZXNoOmNkbjpjaHVuazozMWExZjlkZWEwMTY5NTUxMDkyZDA1ZThiZjRhNDQ2MjI4YzhjM2ViNGM5YjcxM2M2NmFkY2I3ZmQ1M2M4OWJloTCV2UBlMzFiZGM2MzU3N2ZlNzZmNjQ0MTAxNGFhYWEyMjI2ZDlmZmNlMTFiNDRkMGQ1MTBjYWRlMTMyYjc5ZmQ3ZDc2zgAEAADOAAQAANlPbWVzaDpjZG46Y2h1bms6ZTMxYmRjNjM1NzdmZTc2ZjY0NDEwMTRhYWFhMjIyNmQ5ZmZjZTExYjQ0ZDBkNTEwY2FkZTEzMmI3OWZkN2Q3NqYyNjIxNDSV2UBjN2YxYmRlOWUxZWZhN2QxMzg1ZDUxYjA3N2VhODdiMGMzODYwZDI4ZGE0M2Q1ZDZmMjIxZTg0NWM0YzIzNjBmzgAIAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YzdmMWJkZTllMWVmYTdkMTM4NWQ1MWIwNzdlYTg3YjBjMzg2MGQyOGRhNDNkNWQ2ZjIyMWU4NDVjNGMyMzYwZqY1MjQyODiV2UBhYTE0NDRiZTRiNjQwOThmNWRkODYzYjViMGFjNTYxNDgwYjNmYjVjNDFmYzA3Y2Y1MGE2MmVkYzk0MTI0YmNjzgAMAADOAAQAANlPbWVzaDpjZG46Y2h1bms6YWExNDQ0YmU0YjY0MDk4ZjVkZDg2M2I1YjBhYzU2MTQ4MGIzZmI1YzQxZmMwN2NmNTBhNjJlZGM5NDEyNGJjY6Y3ODY0MzKV2UAyODMxNzE1ODU5ZjAxZjNmOTYzZGQwZjExOTRkYmRiYjc2MDk5OTc0MjMwMTVkMzFmNjA3OTExZTFiZjg2NDAyzgAQAADOAAQAANlPbWVzaDpjZG46Y2h1bms6MjgzMTcxNTg1OWYwMWYzZjk2M2RkMGYxMTk0ZGJkYmI3NjA5OTk3NDIzMDE1ZDMxZjYwNzkxMWUxYmY4NjQwMqcxMDQ4NTc2ldlANTk5M2FjNjA0MDdlODY2MDE4NzNiYzM4ZWU2ZjhkYjNlYTkxMmU5ODc2MWNiNTU4YWI5Nzk1ZGIzMDZiNDc0Y84AFAAAzRLf2U9tZXNoOmNkbjpjaHVuazo1OTkzYWM2MDQwN2U4NjYwMTg3M2JjMzhlZTZmOGRiM2VhOTEyZTk4NzYxY2I1NThhYjk3OTVkYjMwNmI0NzRjpzEzMTA3MjCQg6R6ZXRhoTGlYWxwaGGhMqNtaWShMw=="
     },
     {
       "label": "manifest_empty_body",
       "kind": "manifest",
-      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQC8YXBwbGljYXRpb24veC1jdWx0bmV0LXZlY3RvctkhMjAyNi0wOS0yMlQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZTZQGUzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUAANlPbWVzaDpjZG46Y2h1bms6ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NZCA"
+      "messagePackBase64": "mrVldXJla2EvY29udGVudC12ZWN0b3KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQC8YXBwbGljYXRpb24veC1jdWx0bmV0LXZlY3RvctkhMjAyNi0wOS0yMlQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZXZQGUzYjBjNDQyOThmYzFjMTQ5YWZiZjRjODk5NmZiOTI0MjdhZTQxZTQ2NDliOTM0Y2E0OTU5OTFiNzg1MmI4NTUAANlPbWVzaDpjZG46Y2h1bms6ZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NaEwkIA="
     }
   ]
-}
+}

contracts/cultmesh/content-vectors.ts-written.json

@@ -35,7 +35,7 @@
         }
       },
       "recordKey": "mesh:cdn:artifact:pixel-heroes-hüt:unversioned:cf8a453a36981321977355448d24df49bcefee22be6e3730b9140e87c29013f9",
-      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSg2UBjZjhhNDUzYTM2OTgxMzIxOTc3MzU1NDQ4ZDI0ZGY0OWJjZWZlZTIyYmU2ZTM3MzBiOTE0MGU4N2MyOTAxM2Y5zgAL3jG/YXBwbGljYXRpb24veC1jdWx0bmV0LXRzLXZlY3RvctkhMjAyNi0xMC0xOVQwMDowMDowMC4wMDAwMDAwKzAwOjAwlpTZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDgAzgACAADZT21lc2g6Y2RuOmNodW5rOjM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDiU2UAzNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4zgACAADOAAIAANlPbWVzaDpjZG46Y2h1bms6Mzc3YzdiMGNjMjI5ZjQ3MDU2NzBkNjNkNTQ0YzI3NWI2NjNkZjZlOGM4MzFiMDk4NDZhNWM0OGNjYTA4Yjg0OJTZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDjOAAQAAM4AAgAA2U9tZXNoOmNkbjpjaHVuazozNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4lNlAMzc3YzdiMGNjMjI5ZjQ3MDU2NzBkNjNkNTQ0YzI3NWI2NjNkZjZlOGM4MzFiMDk4NDZhNWM0OGNjYTA4Yjg0OM4ABgAAzgACAADZT21lc2g6Y2RuOmNodW5rOjM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDiU2UAzNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4zgAIAADOAAIAANlPbWVzaDpjZG46Y2h1bms6Mzc3YzdiMGNjMjI5ZjQ3MDU2NzBkNjNkNTQ0YzI3NWI2NjNkZjZlOGM4MzFiMDk4NDZhNWM0OGNjYTA4Yjg0OJTZQGEwYmI2OWY0NDg2MWViM2RiNTYwMjZhMWFiYmY5MWZmYTYyMTMyNTA4ZDVhMDZlMGQwZGRjNWNjMjZiZTMzZmPOAAoAAM4AAd4x2U9tZXNoOmNkbjpjaHVuazphMGJiNjlmNDQ4NjFlYjNkYjU2MDI2YTFhYmJmOTFmZmE2MjEzMjUwOGQ1YTA2ZTBkMGRkYzVjYzI2YmUzM2ZjkqFhoWKDojEwoXilYWxwaGGheaEyoXo="
+      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSg2UBjZjhhNDUzYTM2OTgxMzIxOTc3MzU1NDQ4ZDI0ZGY0OWJjZWZlZTIyYmU2ZTM3MzBiOTE0MGU4N2MyOTAxM2Y5zgAL3jG/YXBwbGljYXRpb24veC1jdWx0bmV0LXRzLXZlY3RvctkhMjAyNi0xMC0xOVQwMDowMDowMC4wMDAwMDAwKzAwOjAwlpXZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDgAzgACAADZT21lc2g6Y2RuOmNodW5rOjM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDihMJXZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDjOAAIAAM4AAgAA2U9tZXNoOmNkbjpjaHVuazozNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4pjEzMTA3MpXZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDjOAAQAAM4AAgAA2U9tZXNoOmNkbjpjaHVuazozNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4pjI2MjE0NJXZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDjOAAYAAM4AAgAA2U9tZXNoOmNkbjpjaHVuazozNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4pjM5MzIxNpXZQDM3N2M3YjBjYzIyOWY0NzA1NjcwZDYzZDU0NGMyNzViNjYzZGY2ZThjODMxYjA5ODQ2YTVjNDhjY2EwOGI4NDjOAAgAAM4AAgAA2U9tZXNoOmNkbjpjaHVuazozNzdjN2IwY2MyMjlmNDcwNTY3MGQ2M2Q1NDRjMjc1YjY2M2RmNmU4YzgzMWIwOTg0NmE1YzQ4Y2NhMDhiODQ4pjUyNDI4OJXZQGEwYmI2OWY0NDg2MWViM2RiNTYwMjZhMWFiYmY5MWZmYTYyMTMyNTA4ZDVhMDZlMGQwZGRjNWNjMjZiZTMzZmPOAAoAAM4AAd4x2U9tZXNoOmNkbjpjaHVuazphMGJiNjlmNDQ4NjFlYjNkYjU2MDI2YTFhYmJmOTFmZmE2MjEzMjUwOGQ1YTA2ZTBkMGRkYzVjYzI2YmUzM2ZjpjY1NTM2MJKhYaFig6IxMKF4pWFscGhhoXmhMqF6"
     },
     {
       "label": "ts empty body",
@@ -72,7 +72,7 @@
         }
       },
       "recordKey": "mesh:cdn:artifact:pixel-heroes-hüt:unversioned:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSg2UBlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1AL9hcHBsaWNhdGlvbi94LWN1bHRuZXQtdHMtdmVjdG9y2SEyMDI2LTEwLTE5VDAwOjAwOjAwLjAwMDAwMDArMDA6MDCRlNlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAA2U9tZXNoOmNkbjpjaHVuazplM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1kqFhoWKDojEwoXilYWxwaGGheaEyoXo="
+      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSg2UBlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1AL9hcHBsaWNhdGlvbi94LWN1bHRuZXQtdHMtdmVjdG9y2SEyMDI2LTEwLTE5VDAwOjAwOjAwLjAwMDAwMDArMDA6MDCRldlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAA2U9tZXNoOmNkbjpjaHVuazplM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1oTCSoWGhYoOiMTCheKVhbHBoYaF5oTKheg=="
     },
     {
       "label": "ts single chunk, versioned",
@@ -93,7 +93,7 @@
         }
       },
       "recordKey": "mesh:cdn:artifact:pixel-heroes-hüt:v1-beta:89f4ff56a25dd1db06a4ce6033603775d705fb96f30f8693733fef602a1ca532",
-      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSnVjEgQmV0YdlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMs0D6L9hcHBsaWNhdGlvbi94LWN1bHRuZXQtdHMtdmVjdG9y2SEyMDI2LTEwLTE5VDAwOjAwOjAwLjAwMDAwMDArMDA6MDCRlNlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMgDNA+jZT21lc2g6Y2RuOmNodW5rOjg5ZjRmZjU2YTI1ZGQxZGIwNmE0Y2U2MDMzNjAzNzc1ZDcwNWZiOTZmMzBmODY5MzczM2ZlZjYwMmExY2E1MzKQgA=="
+      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOlYXNzZXSnVjEgQmV0YdlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMs0D6L9hcHBsaWNhdGlvbi94LWN1bHRuZXQtdHMtdmVjdG9y2SEyMDI2LTEwLTE5VDAwOjAwOjAwLjAwMDAwMDArMDA6MDCRldlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMgDNA+jZT21lc2g6Y2RuOmNodW5rOjg5ZjRmZjU2YTI1ZGQxZGIwNmE0Y2U2MDMzNjAzNzc1ZDcwNWZiOTZmMzBmODY5MzczM2ZlZjYwMmExY2E1MzKhMJCA"
     },
     {
       "label": "ts whitespace version, padded kind and mime",
@@ -114,7 +114,7 @@
         }
       },
       "recordKey": "mesh:cdn:artifact:pixel-heroes-hüt:unversioned:89f4ff56a25dd1db06a4ce6033603775d705fb96f30f8693733fef602a1ca532",
-      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOnIGJ1aWxkIKIgINlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMs0D6L0gIHRleHQvcGxhaW47IGNoYXJzZXQ9dXRmLTggINkhMjAyNi0xMC0xOVQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZTZQDg5ZjRmZjU2YTI1ZGQxZGIwNmE0Y2U2MDMzNjAzNzc1ZDcwNWZiOTZmMzBmODY5MzczM2ZlZjYwMmExY2E1MzIAzQPo2U9tZXNoOmNkbjpjaHVuazo4OWY0ZmY1NmEyNWRkMWRiMDZhNGNlNjAzMzYwMzc3NWQ3MDVmYjk2ZjMwZjg2OTM3MzNmZWY2MDJhMWNhNTMykIA="
+      "messagePackBase64": "mrVQaXhlbCBIZXJvZXMvSMO8dCDimIOnIGJ1aWxkIKIgINlAODlmNGZmNTZhMjVkZDFkYjA2YTRjZTYwMzM2MDM3NzVkNzA1ZmI5NmYzMGY4NjkzNzMzZmVmNjAyYTFjYTUzMs0D6L0gIHRleHQvcGxhaW47IGNoYXJzZXQ9dXRmLTggINkhMjAyNi0xMC0xOVQwMDowMDowMC4wMDAwMDAwKzAwOjAwkZXZQDg5ZjRmZjU2YTI1ZGQxZGIwNmE0Y2U2MDMzNjAzNzc1ZDcwNWZiOTZmMzBmODY5MzczM2ZlZjYwMmExY2E1MzIAzQPo2U9tZXNoOmNkbjpjaHVuazo4OWY0ZmY1NmEyNWRkMWRiMDZhNGNlNjAzMzYwMzc3NWQ3MDVmYjk2ZjMwZjg2OTM3MzNmZWY2MDJhMWNhNTMyoTCQgA=="
     }
   ]
 }

contracts/cultnet/cultnet-distributed-database.md

@@ -111,8 +111,13 @@ Not implemented yet:
 not guess. Adding a code is therefore a coordinated change across every runtime, made together: the schema (both
 copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and a captured-bytes case in
 `packages/cultnet-rs/tests/error_message.rs` for it. TypeScript reads the schema. The current codes are
-`selection_invalid`, `cursor_stale`, `cursor_invalid`, `reference_outside_target`, `variant_unsupported` and
-`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns).
+`selection_invalid`, `cursor_stale`, `cursor_invalid`, `reference_outside_target`, `variant_unsupported`,
+`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns),
+`write_not_authorized` (a peer's put or delete its server's remote write authority did not grant) and
+`unsupported_schema_version` (a message whose `schemaVersion` the peer does not speak; `details` names `schemaVersion` and the offered value) and
+`limit_reached` (a receipt-capable server's per-session remembered-write table is full, so a new write is refused; `details` all null) and
+`message_invalid` (a request that lacks a required field or carries an ill-typed one: a document-put or delete, or a subscription without an id; `details.field` names the request field, or `message` when the whole frame cannot be read).
+A malformed put or delete is `message_invalid`, not a per-operation code: the peer knows which operation it sent.
 
 ## Live Invariants
 
@@ -122,6 +127,9 @@ copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and
 - One primary owns writes for a shard until a stronger policy exists.
 - Non-owner writes are rejected or explicitly forwarded. They are not silently
   applied.
+- A peer's put or delete is applied or forwarded only when the server's
+  `RemoteWriteAuthority` grants it; none configured refuses every remote write.
+  The connection key admits a peer to the transport and is never a grant.
 - Raw snapshot/put/delete messages must pass through `CultNetDatabase`, not
   bypass shard policy.
 - The accepted shard log is stored in replica catch-up wire form. Object logs

contracts/cultnet/cultnet.error.schema.json

@@ -28,7 +28,7 @@
     "code": {
       "description": "Machine-readable refusal code (R-N). Additive: a v0 peer that does not know this field ignores it. The set is a closed enum: Rust and TypeScript refuse a message whose code is not listed, so adding a code is one coordinated change across every runtime (this schema, the C# factory, the Rust CultNetErrorCode, and a captured-bytes case for each).",
       "type": ["string", "null"],
-      "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema"]
+      "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema", "write_not_authorized", "unsupported_schema_version", "message_invalid"]
     },
     "details": {
       "description": "Code-specific structured detail (R-N). Every field is populated only for the code that defines it; the others are null, not omitted.",
@@ -36,8 +36,8 @@
       "additionalProperties": false,
       "required": ["field", "value", "asOf", "current"],
       "properties": {
-        "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\".", "type": ["string", "null"] },
-        "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns.", "type": ["string", "null"] },
+        "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\". unsupported_schema_version: \"schemaVersion\". message_invalid: the request field that is missing or ill-typed (\"message\" when the whole frame cannot be read).", "type": ["string", "null"] },
+        "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns. write_not_authorized: the key of the refused write. unsupported_schema_version: the schemaVersion the peer does not speak.", "type": ["string", "null"] },
         "asOf": { "description": "cursor_stale: the cursor's own minted asOf.", "type": ["integer", "null"], "minimum": 0 },
         "current": { "description": "cursor_stale: the answering server's current asOf.", "type": ["integer", "null"], "minimum": 0 }
       }

contracts/cultnet/cultnet.witness-artifact-bundle.schema.json

@@ -59,6 +59,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "id": { "type": "string", "minLength": 1 },
         "role": { "type": "string", "minLength": 1 },
         "schemaId": { "type": "string", "minLength": 1 },
         "schemaVersion": { "type": "string", "minLength": 1 },
@@ -74,6 +75,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "id": { "type": "string", "minLength": 1 },
         "role": { "type": "string", "minLength": 1 },
         "uri": { "type": "string", "minLength": 1 },
         "mediaType": { "type": "string", "minLength": 1 },
@@ -92,6 +94,7 @@
       ],
       "additionalProperties": false,
       "properties": {
+        "id": { "type": "string", "minLength": 1 },
         "stage": { "type": "string", "minLength": 1 },
         "startedAt": { "type": "string", "minLength": 1 },
         "completedAt": { "type": "string", "minLength": 1 },

contracts/cultnet/interop/carrier-vectors.cs-written.json

@@ -0,0 +1,346 @@
+{
+  "vectors": [
+    {
+      "name": "snapshot_request_v1_defaults",
+      "schemaVersion": "cultnet.snapshot_request.v1",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9uu2N1bHRuZXQuc25hcHNob3RfcmVxdWVzdC52MaltZXNzYWdlSWShbalzZWxlY3Rpb26Jp3NjaGVtYXPApGtleXPApmZpZWxkc8ClY2l0ZXPApWNpdGVkwKpwcm9qZWN0aW9upmhlYWRlcqpkZXNjZW5kaW5nwqVsaW1pdMCmY3Vyc29ywKdzaGFyZElkwKpzaGFyZEVwb2NowA==",
+      "expected": {
+        "schemaVersion": "cultnet.snapshot_request.v1",
+        "messageId": "m",
+        "selection": {
+          "schemas": null,
+          "keys": null,
+          "fields": null,
+          "cites": null,
+          "cited": null,
+          "projection": "header",
+          "descending": false,
+          "limit": null,
+          "cursor": null
+        },
+        "shardId": null,
+        "shardEpoch": null
+      }
+    },
+    {
+      "name": "snapshot_request_v1_full_selection_and_shard",
+      "schemaVersion": "cultnet.snapshot_request.v1",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9uu2N1bHRuZXQuc25hcHNob3RfcmVxdWVzdC52MaltZXNzYWdlSWSmbS1mdWxsqXNlbGVjdGlvbomnc2NoZW1hc5KpbGVhZl9hLnY52UdzaGEyNTY6ZmYzNWYzZDlkNmRlM2YxMDY2YjkzNjllNzNmZTZjNzY0OGU4ODM2OGQxOGVmYzIyNzVjOTk0NzMwY2Q4NGNmZqRrZXlzkqRhLWVxqPCfmIAtcm93pmZpZWxkc5KEpWluZGV4pGtpbmSib3CmYW55X29mpnZhbHVlc5Kmd2VhcG9upHRvb2ymbnVtYmVywISlaW5kZXikbWFzc6JvcKJnZaZ2YWx1ZXPApm51bWJlcqstMjIzMzc1OS4yNaVjaXRlc4KmdGFyZ2V0gqhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmapcmVjb3JkS2V5pGEtZXGkcm9sZaZEZXNpZ26lY2l0ZWSCpHJvbGWmRGVzaWdupmV4aXN0c8KqcHJvamVjdGlvbqhkb2N1bWVudKpkZXNjZW5kaW5nw6VsaW1pdMzIpmN1cnNvcq1vcGFxdWUtY3Vyc29yp3NoYXJkSWSnc2hhcmQtMapzaGFyZEVwb2NoBw==",
+      "expected": {
+        "schemaVersion": "cultnet.snapshot_request.v1",
+        "messageId": "m-full",
+        "selection": {
+          "schemas": [
+            "leaf_a.v9",
+            "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff"
+          ],
+          "keys": [
+            "a-eq",
+            "\uD83D\uDE00-row"
+          ],
+          "fields": [
+            {
+              "index": "kind",
+              "op": "any_of",
+              "values": [
+                "weapon",
+                "tool"
+              ],
+              "number": null
+            },
+            {
+              "index": "mass",
+              "op": "ge",
+              "values": null,
+              "number": "-2233759.25"
+            }
+          ],
+          "cites": {
+            "target": {
+              "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+              "recordKey": "a-eq"
+            },
+            "role": "Design"
+          },
+          "cited": {
+            "role": "Design",
+            "exists": false
+          },
+          "projection": "document",
+          "descending": true,
+          "limit": 200,
+          "cursor": "opaque-cursor"
+        },
+        "shardId": "shard-1",
+        "shardEpoch": 7
+      }
+    },
+    {
+      "name": "database_subscribe_v1_defaults",
+      "schemaVersion": "cultnet.database_subscribe.v1",
+      "messagePackBase64": "iK1zY2hlbWFWZXJzaW9uvWN1bHRuZXQuZGF0YWJhc2Vfc3Vic2NyaWJlLnYxqW1lc3NhZ2VJZKFtrnN1YnNjcmlwdGlvbklko3N1YqlzZWxlY3Rpb26Jp3NjaGVtYXPApGtleXPApmZpZWxkc8ClY2l0ZXPApWNpdGVkwKpwcm9qZWN0aW9upmhlYWRlcqpkZXNjZW5kaW5nwqVsaW1pdMCmY3Vyc29ywK9pbmNsdWRlU25hcHNob3TDsWNvbnN1bWVyUnVudGltZUlkwKdib2R5SWRzwLdzdXBwb3J0ZWRCb2R5VHJhbnNwb3J0c8A=",
+      "expected": {
+        "schemaVersion": "cultnet.database_subscribe.v1",
+        "messageId": "m",
+        "subscriptionId": "sub",
+        "selection": {
+          "schemas": null,
+          "keys": null,
+          "fields": null,
+          "cites": null,
+          "cited": null,
+          "projection": "header",
+          "descending": false,
+          "limit": null,
+          "cursor": null
+        },
+        "includeSnapshot": true,
+        "consumerRuntimeId": null,
+        "bodyIds": null,
+        "supportedBodyTransports": null
+      }
+    },
+    {
+      "name": "database_subscribe_v1_full",
+      "schemaVersion": "cultnet.database_subscribe.v1",
+      "messagePackBase64": "iK1zY2hlbWFWZXJzaW9uvWN1bHRuZXQuZGF0YWJhc2Vfc3Vic2NyaWJlLnYxqW1lc3NhZ2VJZKZtLWZ1bGyuc3Vic2NyaXB0aW9uSWSoc3ViLWZ1bGypc2VsZWN0aW9uiadzY2hlbWFzkqlsZWFmX2EudjnZR3NoYTI1NjpmZjM1ZjNkOWQ2ZGUzZjEwNjZiOTM2OWU3M2ZlNmM3NjQ4ZTg4MzY4ZDE4ZWZjMjI3NWM5OTQ3MzBjZDg0Y2ZmpGtleXOSpGEtZXGo8J\u002BYgC1yb3emZmllbGRzkoSlaW5kZXika2luZKJvcKZhbnlfb2amdmFsdWVzkqZ3ZWFwb26kdG9vbKZudW1iZXLAhKVpbmRleKRtYXNzom9womdlpnZhbHVlc8CmbnVtYmVyqy0yMjMzNzU5LjI1pWNpdGVzgqZ0YXJnZXSCqHNjaGVtYUlk2UdzaGEyNTY6ZmYzNWYzZDlkNmRlM2YxMDY2YjkzNjllNzNmZTZjNzY0OGU4ODM2OGQxOGVmYzIyNzVjOTk0NzMwY2Q4NGNmZqlyZWNvcmRLZXmkYS1lcaRyb2xlpkRlc2lnbqVjaXRlZIKkcm9sZaZEZXNpZ26mZXhpc3Rzwqpwcm9qZWN0aW9uqGRvY3VtZW50qmRlc2NlbmRpbmfDpWxpbWl0zMimY3Vyc29yrW9wYXF1ZS1jdXJzb3KvaW5jbHVkZVNuYXBzaG90wrFjb25zdW1lclJ1bnRpbWVJZKhjb25zdW1lcqdib2R5SWRzkaZib2R5LWG3c3VwcG9ydGVkQm9keVRyYW5zcG9ydHOSpHJ1ZHCkcXVpYw==",
+      "expected": {
+        "schemaVersion": "cultnet.database_subscribe.v1",
+        "messageId": "m-full",
+        "subscriptionId": "sub-full",
+        "selection": {
+          "schemas": [
+            "leaf_a.v9",
+            "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff"
+          ],
+          "keys": [
+            "a-eq",
+            "\uD83D\uDE00-row"
+          ],
+          "fields": [
+            {
+              "index": "kind",
+              "op": "any_of",
+              "values": [
+                "weapon",
+                "tool"
+              ],
+              "number": null
+            },
+            {
+              "index": "mass",
+              "op": "ge",
+              "values": null,
+              "number": "-2233759.25"
+            }
+          ],
+          "cites": {
+            "target": {
+              "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+              "recordKey": "a-eq"
+            },
+            "role": "Design"
+          },
+          "cited": {
+            "role": "Design",
+            "exists": false
+          },
+          "projection": "document",
+          "descending": true,
+          "limit": 200,
+          "cursor": "opaque-cursor"
+        },
+        "includeSnapshot": false,
+        "consumerRuntimeId": "consumer",
+        "bodyIds": [
+          "body-a"
+        ],
+        "supportedBodyTransports": [
+          "rudp",
+          "quic"
+        ]
+      }
+    },
+    {
+      "name": "snapshot_response_raw_v1_headers",
+      "schemaVersion": "cultnet.snapshot_response_raw.v1",
+      "messagePackBase64": "i61zY2hlbWFWZXJzaW9u2SBjdWx0bmV0LnNuYXBzaG90X3Jlc3BvbnNlX3Jhdy52MaltZXNzYWdlSWShbadtYXRjaGVkAqRhc09mBaRuZXh0q25leHQtY3Vyc29yp2hlYWRlcnOSiqhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmaqc2NoZW1hTmFtZaZsZWFmX2Gtc2NoZW1hVmVyc2lvbqExsXNjaGVtYUNvbnRlbnRIYXNoo2FiY6lyZWNvcmRLZXmkYS1lcahzdG9yZWRBdLgxOTcwLTAxLTAxVDAwOjAwOjAwLjAwMFqvc291cmNlUnVudGltZUlkonJ0rXNvdXJjZUFnZW50SWSlYWdlbnSqc291cmNlUm9sZaRyb2xlpHRhZ3PAiqhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmaqc2NoZW1hTmFtZaZsZWFmX2Gtc2NoZW1hVmVyc2lvbqExsXNjaGVtYUNvbnRlbnRIYXNoo2FiY6lyZWNvcmRLZXmkYS1sb6hzdG9yZWRBdLgxOTcwLTAxLTAxVDAwOjAwOjAwLjAwMFqvc291cmNlUnVudGltZUlkonJ0rXNvdXJjZUFnZW50SWSlYWdlbnSqc291cmNlUm9sZaRyb2xlpHRhZ3OSpWFscGhhpGJldGGpZG9jdW1lbnRzwKVlZGdlc8Cnc2hhcmRJZKdzaGFyZC0xqnNoYXJkRXBvY2gDsHNoYXJkTG9nU2VxdWVuY2Up",
+      "expected": {
+        "schemaVersion": "cultnet.snapshot_response_raw.v1",
+        "messageId": "m",
+        "matched": 2,
+        "asOf": 5,
+        "next": "next-cursor",
+        "headers": [
+          {
+            "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+            "schemaName": "leaf_a",
+            "schemaVersion": "1",
+            "schemaContentHash": "abc",
+            "recordKey": "a-eq",
+            "storedAt": "1970-01-01T00:00:00.000Z",
+            "sourceRuntimeId": "rt",
+            "sourceAgentId": "agent",
+            "sourceRole": "role",
+            "tags": null
+          },
+          {
+            "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+            "schemaName": "leaf_a",
+            "schemaVersion": "1",
+            "schemaContentHash": "abc",
+            "recordKey": "a-lo",
+            "storedAt": "1970-01-01T00:00:00.000Z",
+            "sourceRuntimeId": "rt",
+            "sourceAgentId": "agent",
+            "sourceRole": "role",
+            "tags": [
+              "alpha",
+              "beta"
+            ]
+          }
+        ],
+        "documents": null,
+        "edges": null,
+        "shardId": "shard-1",
+        "shardEpoch": 3,
+        "shardLogSequence": 41
+      }
+    },
+    {
+      "name": "snapshot_response_raw_v1_documents_and_edges",
+      "schemaVersion": "cultnet.snapshot_response_raw.v1",
+      "messagePackBase64": "i61zY2hlbWFWZXJzaW9u2SBjdWx0bmV0LnNuYXBzaG90X3Jlc3BvbnNlX3Jhdy52MaltZXNzYWdlSWShbadtYXRjaGVkAaRhc09mBaRuZXh0wKdoZWFkZXJzwKlkb2N1bWVudHORjKhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmaqc2NoZW1hTmFtZcCtc2NoZW1hVmVyc2lvbsCxc2NoZW1hQ29udGVudEhhc2jAqXJlY29yZEtleaRhLWVxqHN0b3JlZEF0uDE5NzAtMDEtMDFUMDA6MDA6MDAuMDAwWq9wYXlsb2FkRW5jb2RpbmerbWVzc2FnZXBhY2uncGF5bG9hZMQEgaFrAa9zb3VyY2VSdW50aW1lSWTArXNvdXJjZUFnZW50SWTAqnNvdXJjZVJvbGXApHRhZ3PApWVkZ2VzkoWkZnJvbYKoc2NoZW1hSWTZR3NoYTI1Njo5ZDBiYzlhZWJjMzYxOWIwN2FhYmY1NjRmOTg2NjdhZmRlNDE0NDRjMWI4NjY2NjFkNzc3Njg3ZDQ0MzYwOGRjqXJlY29yZEtleadjaXRlci0xpHJvbGWmRGVzaWduonRvgqhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmapcmVjb3JkS2V5pGEtZXGvcGF5bG9hZEVuY29kaW5nwKdwYXlsb2FkwIWkZnJvbYKoc2NoZW1hSWTZR3NoYTI1Njo5ZDBiYzlhZWJjMzYxOWIwN2FhYmY1NjRmOTg2NjdhZmRlNDE0NDRjMWI4NjY2NjFkNzc3Njg3ZDQ0MzYwOGRjqXJlY29yZEtleadjaXRlci0xpHJvbGWmRGVzaWduonRvgqhzY2hlbWFJZNlHc2hhMjU2OmZmMzVmM2Q5ZDZkZTNmMTA2NmI5MzY5ZTczZmU2Yzc2NDhlODgzNjhkMThlZmMyMjc1Yzk5NDczMGNkODRjZmapcmVjb3JkS2V5pGEtZXGvcGF5bG9hZEVuY29kaW5nq21lc3NhZ2VwYWNrp3BheWxvYWTEAwECA6dzaGFyZElkwKpzaGFyZEVwb2NowLBzaGFyZExvZ1NlcXVlbmNlwA==",
+      "expected": {
+        "schemaVersion": "cultnet.snapshot_response_raw.v1",
+        "messageId": "m",
+        "matched": 1,
+        "asOf": 5,
+        "next": null,
+        "headers": null,
+        "documents": [
+          {
+            "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+            "schemaName": null,
+            "schemaVersion": null,
+            "schemaContentHash": null,
+            "recordKey": "a-eq",
+            "storedAt": "1970-01-01T00:00:00.000Z",
+            "payloadEncoding": "messagepack",
+            "payload": "gaFrAQ==",
+            "sourceRuntimeId": null,
+            "sourceAgentId": null,
+            "sourceRole": null,
+            "tags": null
+          }
+        ],
+        "edges": [
+          {
+            "from": {
+              "schemaId": "sha256:9d0bc9aebc3619b07aabf564f98667afde41444c1b866661d777687d443608dc",
+              "recordKey": "citer-1"
+            },
+            "role": "Design",
+            "to": {
+              "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+              "recordKey": "a-eq"
+            },
+            "payloadEncoding": null,
+            "payload": null
+          },
+          {
+            "from": {
+              "schemaId": "sha256:9d0bc9aebc3619b07aabf564f98667afde41444c1b866661d777687d443608dc",
+              "recordKey": "citer-1"
+            },
+            "role": "Design",
+            "to": {
+              "schemaId": "sha256:ff35f3d9d6de3f1066b9369e73fe6c7648e88368d18efc2275c994730cd84cff",
+              "recordKey": "a-eq"
+            },
+            "payloadEncoding": "messagepack",
+            "payload": "AQID"
+          }
+        ],
+        "shardId": null,
+        "shardEpoch": null,
+        "shardLogSequence": null
+      }
+    },
+    {
+      "name": "error_plain",
+      "schemaVersion": "cultnet.error.v0",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9usGN1bHRuZXQuZXJyb3IudjClZXJyb3KkYm9vbatyb3V0aW5nSGludMCkY29kZcCnZGV0YWlsc8A=",
+      "expected": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "boom",
+        "routingHint": null,
+        "code": null,
+        "details": null
+      }
+    },
+    {
+      "name": "error_selection_invalid",
+      "schemaVersion": "cultnet.error.v0",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9usGN1bHRuZXQuZXJyb3IudjClZXJyb3LZOnNlbGVjdGlvbl9pbnZhbGlkOiBmaWVsZHNbMF0uaW5kZXggImtpbmQiIGlzIG5vdCBkZWNsYXJlZC6rcm91dGluZ0hpbnTApGNvZGWxc2VsZWN0aW9uX2ludmFsaWSnZGV0YWlsc4SlZmllbGSvZmllbGRzWzBdLmluZGV4pXZhbHVlpGtpbmSkYXNPZsCnY3VycmVudMA=",
+      "expected": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "selection_invalid: fields[0].index \u0022kind\u0022 is not declared.",
+        "routingHint": null,
+        "code": "selection_invalid",
+        "details": {
+          "field": "fields[0].index",
+          "value": "kind",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "error_cursor_stale",
+      "schemaVersion": "cultnet.error.v0",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9usGN1bHRuZXQuZXJyb3IudjClZXJyb3KzY3Vyc29yX3N0YWxlOiBzdGFsZatyb3V0aW5nSGludMCkY29kZaxjdXJzb3Jfc3RhbGWnZGV0YWlsc4SlZmllbGTApXZhbHVlwKRhc09mA6djdXJyZW50CQ==",
+      "expected": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "cursor_stale: stale",
+        "routingHint": null,
+        "code": "cursor_stale",
+        "details": {
+          "field": null,
+          "value": null,
+          "asOf": 3,
+          "current": 9
+        }
+      }
+    },
+    {
+      "name": "error_cursor_invalid_no_details",
+      "schemaVersion": "cultnet.error.v0",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9usGN1bHRuZXQuZXJyb3IudjClZXJyb3KzY3Vyc29yX2ludmFsaWQ6IGJhZKtyb3V0aW5nSGludMCkY29kZa5jdXJzb3JfaW52YWxpZKdkZXRhaWxzwA==",
+      "expected": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "cursor_invalid: bad",
+        "routingHint": null,
+        "code": "cursor_invalid",
+        "details": null
+      }
+    },
+    {
+      "name": "error_write_not_authorized",
+      "schemaVersion": "cultnet.error.v0",
+      "messagePackBase64": "ha1zY2hlbWFWZXJzaW9usGN1bHRuZXQuZXJyb3IudjClZXJyb3K0d3JpdGVfbm90X2F1dGhvcml6ZWSrcm91dGluZ0hpbnTApGNvZGW0d3JpdGVfbm90X2F1dGhvcml6ZWSnZGV0YWlsc4SlZmllbGSpcmVjb3JkS2V5pXZhbHVloWukYXNPZsCnY3VycmVudMA=",
+      "expected": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "write_not_authorized",
+        "routingHint": null,
+        "code": "write_not_authorized",
+        "details": {
+          "field": "recordKey",
+          "value": "k",
+          "asOf": null,
+          "current": null
+        }
+      }
+    }
+  ]
+}

contracts/cultnet/interop/cultnet.error.v1.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.error.v1.schema.json",
+  "title": "CultNet Error Message v1",
+  "description": "cultnet.error.v0 plus messageId (write-receipt.md). Sent in place of cultnet.error.v0 only to a connection that declared the write-receipt capability. v0 is unchanged: its schema is closed (additionalProperties false), so an extra key would make a v0 peer reject the frame instead of ignoring it. Map-mode: every key is written, messageId nil when the error answers no readable message. The code enum is the v0 enum plus limit_reached (write-receipt.md, Remembered-write limits).",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "error",
+    "routingHint",
+    "code",
+    "details",
+    "messageId"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": "cultnet.error.v1"
+    },
+    "error": {
+      "type": "string",
+      "minLength": 1
+    },
+    "routingHint": {
+      "description": "Optional shard routing detail for an authority failure. Null for every selection/cursor refusal code (R-N).",
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "required": [
+        "shard",
+        "reason"
+      ],
+      "properties": {
+        "shard": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "code": {
+      "description": "Machine-readable refusal code (R-N). Additive: a v0 peer that does not know this field ignores it. The set is a closed enum: Rust and TypeScript refuse a message whose code is not listed, so adding a code is one coordinated change across every runtime (this schema, the C# factory, the Rust CultNetErrorCode, and a captured-bytes case for each). limit_reached: a receipt-capable server refuses a NEW write because its per-session remembered-write table (1024 entries) or its server-wide memory budget is full; messageId is the write's id.",
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        null,
+        "selection_invalid",
+        "cursor_stale",
+        "cursor_invalid",
+        "reference_outside_target",
+        "variant_unsupported",
+        "unowned_schema",
+        "write_not_authorized",
+        "unsupported_schema_version",
+        "message_invalid",
+        "limit_reached"
+      ]
+    },
+    "details": {
+      "description": "Code-specific structured detail (R-N). Every field is populated only for the code that defines it; the others are null, not omitted.",
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": false,
+      "required": [
+        "field",
+        "value",
+        "asOf",
+        "current"
+      ],
+      "properties": {
+        "field": {
+          "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\". unsupported_schema_version: \"schemaVersion\". message_invalid: the request field that is missing or ill-typed (\"message\" when the whole frame cannot be read). limit_reached: no field; details stay all null. message_invalid also names \"messageId\" (over 256 bytes), \"document\", \"schemaId\" or \"channel\" (write on an unreliable channel).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "value": {
+          "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns. write_not_authorized: the key of the refused write. unsupported_schema_version: the schemaVersion the peer does not speak.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "asOf": {
+          "description": "cursor_stale: the cursor's own minted asOf.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "current": {
+          "description": "cursor_stale: the answering server's current asOf.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        }
+      }
+    },
+    "messageId": {
+      "description": "The messageId of the write (or other request) this error answers, echoed byte for byte. Null only when the frame was unreadable or carried no messageId.",
+      "type": [
+        "string",
+        "null"
+      ],
+      "minLength": 1
+    }
+  }
+}

contracts/cultnet/interop/cultnet.write-admitted.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.write-admitted.schema.json",
+  "title": "CultNet Write Admitted",
+  "description": "The receipt for one admitted document put or delete (write-receipt.md). Sent only after the write's commit point, only to a connection that declared the write-receipt capability, once per messageId. Map-mode: every key is written, none is nil. A receipt never carries an error, and an error.v1 never carries admission.",
+  "type": "object",
+  "required": ["schemaVersion", "messageId", "operation", "schemaId", "recordKey"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": "cultnet.write_admitted.v0" },
+    "messageId": { "description": "The messageId of the put or delete this admits, echoed byte for byte.", "type": "string", "minLength": 1 },
+    "operation": { "enum": ["put", "delete"] },
+    "schemaId": { "description": "The schemaId of the admitted write, echoed.", "type": "string", "minLength": 1 },
+    "recordKey": { "description": "The recordKey of the admitted write, echoed.", "type": "string", "minLength": 1 }
+  }
+}

contracts/cultnet/interop/error-vectors.json

@@ -0,0 +1,166 @@
+{
+  "provenance": "Captured from MessagePack C# 3.1.7 (CultNetErrorMessage/CultNetErrorDetails, Options = Standard.WithSecurity(UntrustedData)); pinned byte-for-byte by packages/cultnet-rs/tests/error_message.rs, whose inline hex equals messagePackHex here (test error_vectors_file_matches_the_inline_csharp_captures). Rust encodes to these exact bytes, so C#-written and Rust-written bytes are one set. Every key is written on the wire, nil included.",
+  "vectors": [
+    {
+      "name": "selection_invalid_schemas_null",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92473656C656374696F6E5F696E76616C69643A206D757374206E6F7420626520656D707479AB726F7574696E6748696E74C0A4636F6465B173656C656374696F6E5F696E76616C6964A764657461696C7384A56669656C64A7736368656D6173A576616C7565C0A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "selection_invalid: must not be empty",
+        "routingHint": null,
+        "code": "selection_invalid",
+        "details": {
+          "field": "schemas",
+          "value": null,
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "selection_invalid_field_value",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92273656C656374696F6E5F696E76616C69643A20626C616E6B206B657920656E747279AB726F7574696E6748696E74C0A4636F6465B173656C656374696F6E5F696E76616C6964A764657461696C7384A56669656C64A46B657973A576616C7565A3202020A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "selection_invalid: blank key entry",
+        "routingHint": null,
+        "code": "selection_invalid",
+        "details": {
+          "field": "keys",
+          "value": "   ",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "cursor_stale",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72BD637572736F725F7374616C653A20637572736F72206973207374616C65AB726F7574696E6748696E74C0A4636F6465AC637572736F725F7374616C65A764657461696C7384A56669656C64C0A576616C7565C0A461734F6601A763757272656E7402",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "cursor_stale: cursor is stale",
+        "routingHint": null,
+        "code": "cursor_stale",
+        "details": {
+          "field": null,
+          "value": null,
+          "asOf": 1,
+          "current": 2
+        }
+      }
+    },
+    {
+      "name": "cursor_invalid",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D923637572736F725F696E76616C69643A2063616E6E6F7420706172736520637572736F72AB726F7574696E6748696E74C0A4636F6465AE637572736F725F696E76616C6964A764657461696C73C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "cursor_invalid: cannot parse cursor",
+        "routingHint": null,
+        "code": "cursor_invalid",
+        "details": null
+      }
+    },
+    {
+      "name": "reference_outside_target",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D9317265666572656E63655F6F7574736964655F7461726765743A206F757473696465206465636C6172656420746172676574AB726F7574696E6748696E74C0A4636F6465B87265666572656E63655F6F7574736964655F746172676574A764657461696C73C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "reference_outside_target: outside declared target",
+        "routingHint": null,
+        "code": "reference_outside_target",
+        "details": null
+      }
+    },
+    {
+      "name": "variant_unsupported_subscription_ended",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72B876617269616E7420756E737570706F727465642068657265AB726F7574696E6748696E74C0A4636F6465B376617269616E745F756E737570706F72746564A764657461696C7384A56669656C64AE737562736372697074696F6E4964A576616C7565A57375622D31A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "variant unsupported here",
+        "routingHint": null,
+        "code": "variant_unsupported",
+        "details": {
+          "field": "subscriptionId",
+          "value": "sub-1",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "variant_unsupported_no_subscription",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72B876617269616E7420756E737570706F727465642068657265AB726F7574696E6748696E74C0A4636F6465B376617269616E745F756E737570706F72746564A764657461696C73C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "variant unsupported here",
+        "routingHint": null,
+        "code": "variant_unsupported",
+        "details": null
+      }
+    },
+    {
+      "name": "unowned_schema",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D95C756E6F776E65645F736368656D613A204E6F207368617264206F776E7320736368656D612027736F6D652E736368656D612E763127206B65792027736F6D653A6B6579273B207468652077726974652077617320726566757365642EAB726F7574696E6748696E74C0A4636F6465AE756E6F776E65645F736368656D61A764657461696C7384A56669656C64A8736368656D614964A576616C7565AE736F6D652E736368656D612E7631A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "unowned_schema: No shard owns schema 'some.schema.v1' key 'some:key'; the write was refused.",
+        "routingHint": null,
+        "code": "unowned_schema",
+        "details": {
+          "field": "schemaId",
+          "value": "some.schema.v1",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "write_not_authorized",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92177726974655F6E6F745F617574686F72697A65643A206E6F74206772616E746564AB726F7574696E6748696E74C0A4636F6465B477726974655F6E6F745F617574686F72697A6564A764657461696C7384A56669656C64A97265636F72644B6579A576616C7565A8736F6D653A6B6579A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "write_not_authorized: not granted",
+        "routingHint": null,
+        "code": "write_not_authorized",
+        "details": {
+          "field": "recordKey",
+          "value": "some:key",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "unsupported_schema_version",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D92C756E737570706F727465645F736368656D615F76657273696F6E3A2063756C746E65742E68656C6C6F2E7631AB726F7574696E6748696E74C0A4636F6465BA756E737570706F727465645F736368656D615F76657273696F6EA764657461696C7384A56669656C64AD736368656D6156657273696F6EA576616C7565B063756C746E65742E68656C6C6F2E7631A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "unsupported_schema_version: cultnet.hello.v1",
+        "routingHint": null,
+        "code": "unsupported_schema_version",
+        "details": {
+          "field": "schemaVersion",
+          "value": "cultnet.hello.v1",
+          "asOf": null,
+          "current": null
+        }
+      }
+    },
+    {
+      "name": "message_invalid",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D93E6D6573736167655F696E76616C69643A2052617720707574206D65737361676573206D75737420636F6E7461696E206120646F63756D656E74206D61702EAB726F7574696E6748696E74C0A4636F6465AF6D6573736167655F696E76616C6964A764657461696C7384A56669656C64A8646F63756D656E74A576616C7565C0A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "message_invalid: Raw put messages must contain a document map.",
+        "routingHint": null,
+        "code": "message_invalid",
+        "details": {
+          "field": "document",
+          "value": null,
+          "asOf": null,
+          "current": null
+        }
+      }
+    }
+  ]
+}

contracts/cultnet/interop/write-receipt.md

@@ -0,0 +1,83 @@
+# CultNet write receipt (specification)
+
+Status: specification. No runtime implements it yet; the conformance follow-ups below do.
+Rules: Heimdall's ruling of 2026-11-08 (a write completes on its result frame; an ack or a return is not admission).
+Files here: `cultnet.write-admitted.schema.json`, `cultnet.error.v1.schema.json`, `write-receipt-vectors.json`. They move to `contracts/cultnet/` when the first runtime implements them.
+
+## The problem
+
+A put or delete today has two answers on the wire: nothing (admitted, or the server never read it) and `cultnet.error.v0` (refused, with no id saying which write). A transport ack proves delivery. Clients that completed on the ack, or on a window with no refusal, reported refused writes as done (CultLib #55 to #58 bound this with a result window; this spec replaces the window with an answer).
+
+## Frames
+
+**`cultnet.write_admitted.v0`**: `{ schemaVersion, messageId, operation: "put"|"delete", schemaId, recordKey }`, every key written, none nil. Sent once a put or delete is admitted. The id echoes the write's `messageId` byte for byte; `operation`, `schemaId`, `recordKey` echo the write.
+
+**`cultnet.error.v1`**: `cultnet.error.v0` plus a required `messageId` (string or nil). The code enum is v0's plus `limit_reached` (see Remembered-write limits); `cultnet.error.v1.schema.json` is the authority for the closed set. Sent in place of `error.v0` to a receipt-capable connection. `messageId` is the id of the request the error answers; nil only when the frame was unreadable or carried no id.
+
+Why a new error version and not an extra key on v0: the v0 schema is closed (`additionalProperties: false`) and the TypeScript decoder (Ajv over the closed schemas) rejects unknown keys and unknown `schemaVersion`s, and `parseCultNetMessage` throws on an unknown version; Rust's decoder errors on an unknown version too. Unknown-key tolerance of the Rust, Python and Kotlin error decoders was not checked, so none is assumed, so a surprise key or frame breaks an old client's whole receive path. Old clients are therefore never sent either new frame. This reverses the "old clients ignore it" assumption, which is false for today's decoders.
+
+## Capability: opting in
+
+A connection is receipt-capable when its `cultnet.hello.v0` (sent before its first write; the schema channel is reliable and ordered) lists both `cultnet.write_admitted.v0` and `cultnet.error.v1` in `supportedMessageVersions`. A server MUST NOT send either new frame to any other connection, and answers it exactly as before (no receipt, `error.v0`). A receipt-capable server lists both in its own hello, so a client can tell a legacy server from a receipt server that has not answered yet. A client that sends no hello gets legacy behaviour. A server advertises the two frames in its hello only if it implements the receipt rules end to end.
+
+**The capability changes framing only; it never authorizes.** A hello authenticates nothing and grants nothing: who may write, and which keys, is decided by the server from the transport-authenticated actor exactly as without the capability. Declaring the capability never makes a refused write admitted, never widens an actor's authority, and never changes what a write does; it selects only which frame the answer arrives in.
+
+## Server rules
+
+1. **One answer.** For every put or delete on a receipt-capable connection the server sends exactly one of `write_admitted` or `error.v1`, carrying that write's `messageId`. Never both, never two different answers.
+2. **After the commit point.** `write_admitted` is sent only after the write is committed by the same rule that makes it visible to readers. Receipt of the bytes, parse, or authorisation alone is not admission.
+3. **Id on every refusal.** Every refusal of a write, whatever its code (`write_not_authorized`, `message_invalid`, `unowned_schema`, `unsupported_schema_version`, shard authority errors, ...), is an `error.v1` whose `messageId` is the write's id. When the frame is readable enough to find the id, it is found; `message_invalid` for a missing or ill-typed field still carries the id. Nil only when no id can be read.
+4. **Batches.** There is no batch frame; a batch is N writes, each with its own `messageId`, each answered under rules 1 to 3. A failed batch names its member by that id. A server may not collapse a batch into one answer.
+5. **Identity and idempotent resend.** A `messageId` is unique per authenticated actor and session: the client mints it, never reuses it for different content in that session, and a server never accepts the id of one actor as the id of another. The server's dedupe key is `(actor, messageId)`, where *actor* is the transport-authenticated identity, never a name the hello or the frame claims. Alongside the key it keeps the **content hash** of the write and the answer it gave. The content hash is SHA-256 of the MessagePack array `[operation, schemaId, recordKey, payload]`, where `payload` is the raw document payload as a MessagePack `bin` for a put and nil for a delete (the vectors give worked hashes). **Scope: at least the session.** The key lives for the life of the session it was made in, and a server may bound how many writes it remembers per session (see Remembered-write limits; a server never forgets an id it promised to answer). A server MAY keep the key longer for the same actor, up to `DEDUPE_RETENTION_MS` (10 minutes), but a client MUST NOT rely on it: **a reconnect is a new session, and a resend on the new session is a new write.**
+   - Same key, same content hash, answer was `write_admitted`: answer `write_admitted` again with the same body. The write is not applied twice.
+   - Same key, same content hash, answer was a refusal: the same refusal again.
+   - **Same key, different content hash: refuse `message_invalid` (details `field: "messageId"`) and never re-send the old receipt.** Old receipts are for the old content; showing one for new content would report an unapplied write as admitted. The original write's state is unchanged.
+   - **Id size.** A write's `messageId` is at most 256 bytes of UTF-8. A longer id is refused `message_invalid` (`details.field: "messageId"`, the refusal's `messageId` the id as received, text fixed per Fixed texts) BEFORE anything is remembered: no table entry, no digest, no budget charge. Such a refusal is therefore not replayed from the table; a resend is refused afresh, identically.
+   - **What is remembered.** Per entry a server keeps only fixed-size digests (SHA-256) of the `messageId` and of the content hash, plus the answer (`admitted`, or the refusal's code and details). Memory per entry is bounded independent of id length and payload size. Lookup compares digests.
+   - **Remembered-write limits.** The per-session table holds at most 1024 entries. A server MAY also enforce a server-wide memory budget across all sessions (reference: 32 MiB of remembered entries). A NEW write (a key not already in the table) that would exceed either bound is refused `limit_reached` for that write alone, `messageId` the write's id, `details` all null; the write is not applied and the session continues. A resend of a remembered key is still answered from the table.
+   - **Limit refusals are remembered.** A `limit_reached` refusal is remembered like any other: a resend of the same id and content hash replays `limit_reached`. No slot is freed mid-session, so an id refused at a bound never becomes admitted later in that session (a server at the cap keeps the refused digest pair in a bounded refusal set of at most 1024 per session, outside the entry budget; past it, a further new write is refused `limit_reached` without being remembered, and the session refuses every id it has not seen for the rest of its life, even if a server-wide budget has since freed, so a refusal that was not remembered is never followed by an admission of the same id). The client mints a new id on a new session.
+   - **Required fields.** A put or delete whose document or `schemaId` is null or missing is refused `message_invalid` with `details.field` `"document"` or `"schemaId"` (the first missing in that order) and fixed text; the write is not applied. A `schemaId` or `recordKey` that is empty or only whitespace (present but names nothing) is not "missing": the write is refused `message_invalid` exactly as a frame that does not read, with `details.field` `"message"` and the write's id (vector `error_v1_empty_schema_id_is_unreadable_and_names_the_write`), and is never applied; a server must not hand it to its store.
+   - **Fixed texts.** The `error` string of these refusals is fixed, so vectors can compare it: `message_invalid: messageId exceeds 256 bytes`, `message_invalid: document is required`, `message_invalid: schemaId is required`, `message_invalid: receipt sessions require the reliable channel`, `limit_reached: the session's remembered-write limit is full`.
+   - **Reliable channel only.** A write is accepted on a receipt session only on a channel that is reliable and not sequenced (reliable ordered and reliable unordered both qualify; a sequenced channel drops superseded packets, so a write on it can vanish without trace). A write arriving on any other channel is refused `message_invalid` with `details.field: "channel"` (the transport profile's word for it) and fixed text. Receipts and refusals travel the reliable channel; a write that could be lost without trace cannot be answered once.
+   - Past the session (or a server's longer retention, if it keeps one) a resend is a new write.
+6. **Forwarded writes.** A server that forwards a non-primary write answers the original peer only with what the primary answered: the primary's receipt becomes `write_admitted` with the original id, its refusal becomes `error.v1` with the original id. If the forward gets no answer the server relays nothing: no receipt, no error, no synthesized refusal. The client's own rule below then reports the write as unconfirmed. A forwarder never turns an absent or ambiguous primary answer into an admission.
+7. **Looks alike.** An admitted and a refused write differ in `schemaVersion`; a receipt has no `error`, an `error.v1` has no admission. A transport ack is neither.
+
+## Client rules: three outcomes
+
+A write settles as exactly one of:
+
+- **admitted**: a `write_admitted` whose `messageId` is the write's.
+- **refused**: an `error.v1` whose `messageId` is the write's, carrying its `code` and `details` as the typed error.
+- **unconfirmed**: nothing settled it. Reasons: `window_elapsed` (the result window ran from the *send* and passed with no answer; see Result window), `session_ended` (the peer closed the session, or it ended, before the write was answered) and `local_send_failed` (the client's own send of this write failed). A local send failure is never reported as refused: no server answer exists, and the write may or may not have left the machine. Unconfirmed is not success and not refusal. APIs that return a value return the tri-state; APIs that throw throw a distinct refused error and a distinct unconfirmed error and return normally only for admitted. A caller that needs admission treats unconfirmed as not admitted. Resend with the same `messageId` and unchanged content, **on the same session**, is safe against a receipt-capable server (rule 5). After a reconnect the resend is a new write, and a legacy server may apply a resend twice: the caller resends only writes that are idempotent by record key (a put of the same content to the same key, a delete of a key), and reads the record back before resending any other.
+
+**Result window.** Two named constants (also in the vectors): `RECEIPT_RESULT_WINDOW_MS = 5000`, the default against a receipt-capable server (its hello lists both frames); `LEGACY_RESULT_WINDOW_MS = 500`, used only as the fallback against a server whose hello does not list them (or that sent none). The window runs from the send. A receipt-capable server that has not answered within its window is reported as unconfirmed like any other; clients log it as a server that missed its window.
+
+**Late answers.** An answer for a write that already settled `unconfirmed` does not change what the caller was told, but the client records it on the write: a late `write_admitted` makes the write's recorded state `admitted_late`, a late refusal makes it `refused_late`. The write handle exposes that state, and a caller that got `unconfirmed` MUST consult it (and the record) before resending: it must not blind-resend a write that was admitted late. A resend on the same session with the same id and content is harmless on a receipt-capable server (rule 5); across a reconnect the caller follows the idempotence rule above.
+
+**Legacy answers.** An `error.v0`, or an `error.v1` with nil `messageId`, names no write. It is attributed to a write only when exactly one write on the connection is unanswered; it then refuses that write. With two or more unanswered writes it settles none of them and each ends unconfirmed at its window. A frame naming a `messageId` that is not in flight settles nothing.
+
+**Batches can commit partially.** A batch is N independent writes with no atomicity: some members may be admitted while others are refused or unanswered, and nothing is rolled back. The client reports each member's outcome and a batch result is only their set: admitted if every member is admitted, refused if any member is refused (naming the members), otherwise unconfirmed (naming the unanswered members). The caller owns retry: it resends exactly the members that are not admitted, with their original ids.
+
+## Changes to what #55 to #58 shipped
+
+Those clients complete *successfully* when the window ends with no refusal. Under this spec that case is `unconfirmed`. The TypeScript one-shot writer (#62) already reports it so: it resolves `admitted` only on a `write_admitted` carrying the put's id, and no other frame, a put echoed under the same id included, ever counts as admission. A caller whose server cannot answer a write yet (Odin, until it is receipt-capable) opts into the explicit send-only mode per call (`sendOnly: true`), which resolves the distinct outcome `sent` once the transport has acknowledged the put and never `admitted`. The Idunn presence publisher is send-only by its own function (`sendPresenceDocument`, not the `sendOnly` option): the same `sent` result, plus a rejection if a refusal naming the put (or naming nothing) arrives by the transport ack. Receipts and send-only are both opt-in, neither is the default. The C# and Rust clients of #55 to #58 keep the window-success until their conformance work lands, and callers of those must not read it as admission.
+
+## Vectors
+
+`write-receipt-vectors.json`: `constants` (the named windows and retention), `contentHash` (worked dedupe hashes), `dedupe` (server replay cases for rule 5), `wire` (MessagePack hex plus the decoded message for each new frame; the bytes are spec-authored with msgpack-python and every runtime's first conformance PR re-captures them with its own encoder and must match), `schemaInvalid` (frames that must be refused by a validator, each with why), and `scenarios` (event replays with the outcome each write must settle as; the clock is abstract; each case names its window constant). A conformant client passes every scenario; a conformant server's answers for the same inputs satisfy server rules 1 to 7.
+
+## Conformance status
+
+| Server class | Advertises both frames | Server-wide memory budget (MAY, Remembered-write limits) |
+|---|---|---|
+| `CultNetDatabaseServer` | yes | not implemented: only the per-session limit of 1024 applies |
+| Shard write forwarder | yes | not implemented: only the per-session limit of 1024 applies |
+| Rust RUDP document server | yes | implemented (32 MiB default, `max_remembered_write_bytes`) |
+| C# RUDP schema server (`CultNetRudpSchemaServer`, `src/GameCult.Networking/CultNetRudpSchemaServer.cs`) | no | n/a |
+
+Advertising is per server class, not per transport. A class advertises both frames in its hello only if it implements the receipt rules end to end; the C# RUDP schema server stays "no" until it answers writes with receipts.
+
+## Conformance follow-ups (not in this PR)
+
+C# server and client, Rust, TypeScript, Python, Kotlin: emit and parse the two frames; hello capability; tri-state client outcome; replace the #55 to #58 window-success; re-capture the wire vectors in each runtime. Server write paths include the shard write forwarder (rule 6) and the Odin catalog.

docs/c2a-land-map.md

@@ -0,0 +1,441 @@
+# C2a land map
+
+What C2a (`hands/variants-c2a`, a5c7954e) must still prove to merge to main, measured
+on 2026-10-22 against main 7a8933b0 and the 2.0.0 release candidate
+`hands/cultlib-unity-release-2.0.0` (5b5d8573, which carries f91e30ed). The land cut
+is the merge plus the gate. Everything else is classified below. Governing ruling:
+`cultlib-gaps:ruling:release-now-c2a-bumps-format`.
+
+## Cut sequence to main (2026-10-27, branch head 7c7cc799)
+
+Landed since the facts below: `land-c2a` (h1), `land-c2a-merge-api-docs` (h1-h6), the 2.0.1 and
+cultcache-rs 0.3.1 merges (5baa02fa, f54472e5), `land-c2a-gate` r4 (h1), `store-gate-one-owner`
+(h1-h7, Soul s6) and `restamp-on-write` (h1-h2, 8ee66714..7c7cc799, Soul s2 holds). One static `Owns`
+decides ownership for cache and cacheless writers, and the High finding
+`cut-land-c2a-gate.s1.reflist-record-read-only-at-head` is Fixed by 7c7cc799. origin/main is 73e684b1:
+21 commits past the merge base 02cf04b5, all docs and research (15 files, +1879, none under src/,
+tests/ or packages/, none on a path the branch changed). What stands between the branch and main, in
+order:
+
+1. **claimant-one-owner** (spec r1 at 7c7cc799, Hands then Soul). Restamp's Soul s2 left four Lows
+   on the landing path. Which entry reads a persisted entry is chosen twice (`Claimant` at
+   CultCache.cs:703-750, `ClaimantEntry` at :797-799), and so a cacheless writer handed registry {A,B}
+   overwrites a record that a cache with {A,B} holds read-only (probe X4). The cut keeps one `Claimant`
+   precedence over a by-id/by-name lookup that the registry or a single entry supplies. A cacheless
+   writer with a registry then takes its claimant from that registry. The cut also pins the
+   unpublished-id case and fixes the stale test comment. It closes `claimant-selection-duplicated`,
+   `cacheless-inverts-registry-claimant`, `unpublished-id-guard-unpinned` and `stale-flag-copy-comment`.
+   It is kept apart from the gate so that Soul can falsify it alone. Its files (CultCache.cs, the
+   persistence contract, RestampOnWriteTests.cs) are disjoint from the gate's, so it can run before or
+   beside step 2. The second cut to land rebases.
+2. **land-c2a-gate** (spec r7 at 7c7cc799, Hands h2 then Soul). The ref-list gate does the same write
+   at 2.0.1 and at head and compares schema ids. The committed vectors are pinned byte for byte under a
+   fixed clock, and every stage counts its cases. r7 drops r6's head-only restamp assertions, which
+   `RestampOnWriteTests.TheCommitted1060VectorsListRecordIsWrittenUnderTheHoldersOwnId` already pins.
+   It also drops the red-at-193cf1c3 run, because restamp is measured. The cut closes
+   `single-vector-hand-edit-passes`, `gate-green-with-no-refusal-probes` and follow-up
+   `gate-reads-1x-written-store`.
+3. **Ledger** (Self, no Hands; can run now, beside steps 1 and 2). Each of these is in force though
+   its fix has landed:
+   - The seven `cut-land-c2a.s1.*` findings. `land-c2a-merge-api-docs` carried their pins (source reads
+     2026-10-27: GameCult.Caching grants InternalsVisibleTo only to `.Tests` and `.MessagePack`, the
+     residual being follow-up `caching-messagepack-ivt`; PreCut2StoreFormatTests pins "with a suffix
+     of"). Close each one against its commit, or defer it. `stale-unity-plugin-dlls` defers to the
+     Unity 3.0.0 release cut (the plugins are 2.0.1 builds, 1eeb1a01).
+   - `cut-c2a-write-set.s1.untouched-dropped-slot-resurrects` and follow-up `slot-reuse-contract-doc`.
+     Ruling `slot-reuse-documented` decided the behaviour, and the paragraph is in
+     cultcache-schema-compatibility.md:64-66.
+   - `cut-restamp-on-write.s1.websockets-tests-unreported`, Fixed by h2 (s2 promise
+     `websockets-tests-reported` holds).
+   - Follow-up `gate-bound-test-tighten`, carried by restamp r2 (50362447, a768b821). Close it if
+     restamp's Soul passes measured it; otherwise route it.
+   - After steps 1 and 2 hold: the four s2 Lows, the two remaining `cut-land-c2a-gate.s1` Lows and
+     `gate-reads-1x-written-store`.
+4. **Consumer pins** (ruling `unpinned-consumers-at-land-3`, follow-up `consumer-pins-before-land`).
+   Brokkr, Aquarium, Ymir, AquaSynth and Mimir have no `CultLibRevision`/`VerifyCultLibRevision` guard,
+   and each builds against the sibling `..\CultLib` checkout. In its own repo, each adopts Aetheria's
+   guard at the 2.0.0 tag, with one Hands per repo, before the merge reaches main. The pins touch no
+   CultLib file, so they can start now and run in parallel with steps 1-3. Eve and Gjallar get no pin
+   (ruled). The step is done when each repo's guard fails a build against a CultLib checkout at
+   another revision and passes at the tag, and the follow-up is resolved.
+5. **Main into the branch, then full verification.** After steps 1, 2 and 4, `git merge origin/main`
+   into `hands/variants-c2a`. It should be clean, because main's commits since 02cf04b5 are docs and
+   research only. Re-check that before merging (`git diff --stat 02cf04b5 origin/main -- src tests
+   packages unity`). Then run every suite at the merged head on Yggdrasil: Caching, Mesh, Networking,
+   Geometry, WebSockets, ConsumerBuild, InteropPeer, cultcache-ts/-rs/-py, cultnet-ts and cultmesh-ts.
+   Run `old-reader-refusal.sh gate` for csharp, typescript, python and rust. If main gained code by then,
+   a Soul pass covers the merge.
+6. **Land.** The land is `git merge --no-ff`, never a squash, so the SHAs that every report and verdict cites stay reachable from main (skip the branch's non-building commits with `git bisect --first-parent`). Steps 1 and 2 closed at 723b7996 (claimant-one-owner, land-c2a-gate); step 5 closed at the merge commit 3157d4b3 (Soul `cut-land-c2a-main.s1` holds). Step 3 closed except `cut-land-c2a.s1.stale-unity-plugin-dlls` and `cut-land-c2a-gate.s2.mutation-table-reads-gate-as-zero`, which wait on the 3.0.0 release cut and the Eureka tools respectively; step 4 closed with `consumer-pins-before-land` (pins since 2026-10-22). Run `git merge --no-ff hands/variants-c2a` onto main, with an empty diff against the
+   verified head. There is no tag: tags, the Unity plugin rebuild and `declared-range-gate-own-version`
+   belong to the 3.0.0 release cut. Open follow-ups `c2a-load-slower` (load 2 to 2.3 times slower than
+   main on a synthetic Aetheria catalog) and `drift-write-ownership-leaves` do not say "before land".
+   `c2a-load-slower` still needs a reason or a fix before the 3.0.0 release, under
+   `cultlib-gaps:ruling:database-shaped-built-for-load`.
+
+## Facts
+
+**1. The merge.** A trial `git merge origin/main` on a5c7954e gives 12 conflicted files and
+33 hunks of about 950 marker lines (CultCache.cs 17 hunks/196; cult-cache.test.ts 337;
+single-file-messagepack-backing-store.ts 4/106; rs lib.rs 2/51; VariantTests 51; three
+CHANGELOG add/adds; store-composition contract 32; Directory store 14; InteropPeer 21).
+Main moved 4.8k lines in the cache runtimes since base 1a12bc2d. Three semantic collisions
+are not textual:
+
+- *Durable record identity has two owners.* Main added `CultStoredDocument.PersistedSchemaId`
+  and `CacheBackingStore.MarkWritten` (73d438db, afd799ba, 3f6dda8b). Conditional commit
+  compares the persisted schema id plus storedAt. C2a already owns this as
+  `StoredSchemaId` + `StoredVersion` (SHA-256 of the stored bytes, which names the schema
+  id and storedAt) set by `CultCache.Wrote`. After the merge, 9 references in
+  ConditionalCommitTests and the contract name main's owner. The version is the owner.
+  PersistedSchemaId and MarkWritten are deleted, and main's +309 test lines are ported as
+  pins against StoredVersion. 2.0.0 ships MarkWritten as protected API, and C2a also
+  removes `SerializeSnapshot`/`DeserializeSnapshot` overrides and changes `ConditionsHold`.
+  C2a is therefore a major release (3.0.0), which semver forces.
+- *TS store commit moved.* Main's `store-file.ts` (0e6452c9, 0010ee92; 391 lines) now owns
+  commit, replace and the `<path>.lock`. C2a's v3 read and keep-v3-on-rewrite
+  (`STORE_FORMAT_ELEMENT_IDS`) lives in the old store file and must move into store-file.ts.
+- *Rust decode door.* Main's cultcache-rs 0.3.0 grown decoder (`decode_stack`, fc630d3b)
+  must sit under C2a's `readable_store_format` and v3 `decode_store_file`.
+
+**2. The gate already holds; it needs a test, not a format change.** C2a stamps
+`cultcache.store.v3` (single file) or `...v5.directory-content-addressed-pages` exactly when
+a record holds an id (`HeaderFor`, CultCache.cs:3543). It also marks when a copied record
+decodes holding one (`CopiedHoldIds`, :4285). The 2.0 C# reader accepts only v1/v2
+(CultDocumentMessagePackSerialization.cs:229) and directory v4 (Directory store :452).
+Main's TS, Rust and Python readers accept only v1 (store-format.ts `isV1Snapshot`, lib.rs:1274,
+stores.py:192). Probe on Yggdrasil at 5b5d8573 plus C2a's `v3-base.msgpack` (job
+`gate1.log`): 4/4 pass. The single file is refused naming v3, and a later flush leaves it
+byte-identical. A v5-stamped directory store is refused naming v5, and its 4 files are
+byte-identical after a later add and flush. **The pin:** C2a already ships
+`tests/vectors/document-variants-c2a/old-reader-refusal.sh`, which stages an old revision
+plus probes on a scratch ref and runs them per runtime. The land cut sets its
+`OLD_READER_REV` default to the tag `cultlib-unity-v2.0.0`. It also adds the never-rewritten
+assertion and the v5 directory case to the C# probe, and runs all four runtimes at the
+tag. If the tag is absent, the land waits for it. The tag, not a package, is the pin: the tag's
+tree holds every runtime's released reader.
+
+*Outside C2a's reach (release session):* in 2.0, `CultMesh.WriteSingleFileDocument`/
+`WriteSingleFileDocumentPayload` (CultMeshSingleFileDocuments.cs:211-245 at 7a8933b0) build
+a fresh one-record v1 snapshot and replace the file without reading it. A 2.0 Mesh write
+to a C2a v3 path therefore discards it whole, ids and other records included, and no header
+gate can stop a writer that never reads. C2a's version reads under the lock and refuses.
+Fix it in 2.0.0 before tagging, or record it.
+
+**5. Consumers.** Aetheria pins a CultLib revision (`VerifyCultLibRevision`) and Unity tags.
+Ghostlight, Eve's Rust crates, Huginn and the Brokkr daemon pin cultcache-rs by git rev.
+None of them moves when main moves. Two C# consumers build against an unpinned sibling
+`..\CultLib` checkout: Eve `GameCult.Eve.Surface.csproj:16` and Brokkr's three csprojs.
+Eve.Surface has `[MessagePackObject]` element arrays with no `[CultElementId]`
+(`EveAssetCatalogEntry[]`, `EveEntitySoaBuffer[]`, `EveInputActionDocument[]`,
+`IReadOnlyList<EveCommandTemplate>`, 0 ids in the repo), so C2a registration refuses its
+documents as soon as the checkout pulls the land. Grep finds no object lists in Brokkr's
+`[CultDocument]` files (not build-verified). Removed C2a API (`Options`, `AsSchemaAlias`) is
+unused by Eve and Brokkr. Fork: `variants:question:unpinned-consumers-at-land`.
+
+## Classification
+
+| Item | Class | Why |
+|---|---|---|
+| c2a-format-version-gate | **a** | The gate test above. No new header: v3/v5 already refuse. |
+| slot-reuse-contract-doc | **a** | The ruled consequence of the write set C2a lands. One paragraph in cultcache-schema-compatibility.md, absent at a5c7954e (grep). |
+| foreign-ids-under-v1-header | **b** | Obsoleted by fb065f0d (write-time `CopiedHoldIds`, after the finding) for every C# writer with the type. The residual (non-C# or opaque writers) is what `non-csharp-writers-mark-ids-2` ruled to carry, and the contract states it (persistence-format.md:434-439). The gate changes neither side, so no fork remains. Resolve as Superseded by that ruling. |
+| custom-resolver-element-ids | **b** | Fixed by b091d21f (19:52Z, after the 18:27Z follow-up): `ListElementsClaimedByAResolverAreRefused`, `AResolverClaimingTheListTypeOfAnObjectListIsRefused`. s6 holds on the claim loop. |
+| codec-door-proven-mismatch | **b** | Done in h6 57fdf70c (s6 `only-proven-mismatch` Holds; Geometry 76/0). |
+| consumer-element-id-sweep-r2 | **c** | Each repo's sweep is its own work (q3). Only the unpinned trackers matter at land, and that is the question below. Aetheria bumps a pin on purpose (C4). |
+| schema-discovery-holder-recogniser | **c** | `TryGetDictionaryRefTypes` is identical on main (CultCache.cs:1288). It describes record-ref dictionaries and is not on the id path. Changing it moves schema hashes, which is its own epoch event. |
+| copy-check-memo | **c** | Performance only (about 3x flush on unmarked stores of 20k records). Correct as is. |
+| string-key-field-and-shadow-pins | **c** | No wrong behaviour at 64ec14f9. These are test pins and may ride the land cut if Hands touches the file. |
+| declared-range-gate-own-version, range-check-in-ci | **c** | The script exists only on C2a and runs in no CI. It guards a TS publish, not a merge. Fix both before the first TS release from main after the land. |
+| s6 Unproven: Unity/IL2CPP identity, other MessagePack versions | **c** | The merge reaches no Unity build. Unity sees C2a only at the 3.0.0 tag, so measure it in the Unity release cut (operator Unity check, C3). |
+| multi-store-commit-atomicity, store-replace-cut, reader-refuses-duplicate-keys, soft-flush-all-runtimes, writer-dangling-link-tolerance, unique-index-cut, py-shared-write-lock, rust-lock-open-waits, ts-lock-test-hardening, c0/legacy/directory vectors, culture-test, wire-id-cuts, remaining-variant-cuts, golden-path, paged store | **c** | None says "before land". Each is pre-existing on main or C2a-independent. None lets a released reader strip ids or corrupt a C2a store. |
+
+## The land cut's shape (transcribe once the question is ruled)
+
+- **Base.** Merge main at or after the `cultlib-unity-v2.0.0` tag into `hands/variants-c2a`.
+  Versions stay main's. CHANGELOGs get Unreleased entries, and the Unity entry says major.
+- **Deletes and collapses.** Delete `PersistedSchemaId`, `PersistedIdentity`,
+  `CultStoredDocument.MarkWritten` and `CacheBackingStore.MarkWritten` (main, about 60 lines),
+  and the store-composition contract's MarkWritten paragraph. C2a's `StoredVersion`/`Wrote`
+  is the one owner. In TS, delete C2a's header handling in
+  single-file-messagepack-backing-store.ts and move it into store-file.ts. In Rust, C2a's v3
+  decode goes through the grown decoder.
+- **Adds.** Retarget old-reader-refusal.sh to the tag. Add the C# probe's never-rewritten
+  assertion and the v5 directory case (as in gate1.log). Add the slot-reuse paragraph.
+  Port main's ConditionalCommitTests to the version identity.
+- **Verification.** Full suites: Caching, Mesh, Networking, Geometry, WebSockets,
+  ConsumerBuild, InteropPeer, cultcache-ts/-rs/-py, cultnet-ts and cultmesh-ts, all on
+  Yggdrasil. Run old-reader-refusal.sh for all four runtimes at the tag, and it must refuse.
+  Negative greps over the merged tree: `PersistedSchemaId|MarkWritten`, conflict markers.
+  Mutation: drop the v3/v5 stamp in `HeaderFor` and the gate probe must fail.
+- **Estimate.** About 950 conflict lines resolved. Net -60 to -150 from the identity
+  collapse and TS de-duplication, +80 to +120 tests and docs. One Hands pass of 100-150
+  calls, then one Soul pass.
+- **Precondition (question).** Eve.Surface, and Brokkr if confirmed, are pinned or swept
+  before the merge reaches main.
+
+## Store gate: attachment is the attach's hold (store-gate-one-owner r2)
+
+Spec `variants:cut_spec:cut-store-gate-one-owner.r2` (base ec94ab98), question
+`variants:question:pulled-variant-codec`. It closes Soul s3's
+`attach-window-cacheless-write` (Medium) and `codec-loan-pinned-by-reflection` (Low).
+
+**Facts (source reads at ec94ab98 and a probe, 2026-10-25).**
+
+- The window. AddBackingStore holds the cache's gate, then the store's gate through
+  `InStoreHold`, lends the registry and codec, sets `Loaded`, adds the store to `_stores`,
+  pulls, and only then sets `store.Cache` (CultCache.cs 2268-2312). `InStoreHold` lets any
+  call on the same store's gate re-enter it (2825-2831). So a journal the pull's Admit runs
+  on the attaching thread can call `store.WriteDocument`: `Gate(cacheless)` guesses null,
+  re-enters the store's gate, finds `Cache == null` and runs the write, and its `finally`
+  calls `UseRegistry(null, null)` (Soul s3 P1, full1.log lines 49-53). Other threads are not
+  in the window: they queue on the store's gate and see either the published cache or a
+  store that the failed attach put back.
+- The codec loan has no reader on the attach path. A pulled variant's codec is read only
+  by `CultStoredDocument.HoldsIds` (543-557). Header decisions read `HoldsIds` only on
+  staged entries (single-file 4318, 4447 and 4472; directory store 362), and a staged entry
+  is always the document the cache pushed (`Push` sets `Entries[key] = entry`, 4211-4215).
+  A single-file `PullAll` returns without loading while the store is dirty (4157-4159), so
+  a pulled copy is never staged. A refused write unstages its keys before it adopts the
+  reload. The directory store refuses variants (ruling `q6-directory-and-cultnet-refuse`;
+  DirectoryMessagePackBackingStore.cs 139-144 and 642-643). Admit re-resolves every pulled
+  variant with the cache's codec (CultCache.cs 3259). Soul's N4 mutant (the attach lends
+  no codec) was caught only by the reflection test, and h4's M2 only by a bare-store test
+  that sets `Loaded` and calls `UseRegistry` by hand.
+- Probe (scratch clone `imagination-store-gate-r2/clone`, commits 4663934e and c099b9e8 on
+  ec94ab98; Yggdrasil t1.log, t2.log and t3.log; 2026-10-25 around 20:50 CEST). The
+  probe did three things. `InStoreHold` refuses a cacheless call that re-enters the same
+  store's gate. The `_codec` field and the two-argument `UseRegistry` are deleted. The pull
+  builds variants with a null codec. Results:
+  - Mesh is 342/0/4.
+  - In the Caching suite, the only failures were two probe tests, both from authoring
+    errors: a key `AddAsync` minted, and an element id that was not 12 hex characters.
+    No existing test failed, `UserCodeInACachelessCallMayCallItsOwnStore` included.
+  - Soul's P1 as a test: the journal's write is refused with the new message. The attach
+    keeps its registry and the file holds only `a`. After the attach, a cache write, a
+    flush and `store.PullAll()` all succeed.
+  - A cacheless write nested in another on the same store is refused, the outer write
+    fails, and no file is written.
+  - Through a real attach, a store holding a name-override variant flushes an unrelated
+    commit with a `cultcache.store.v2` header. With no codec loan, the pulled copy does not
+    mark the store.
+  - Mutant `return cacheless` changed to `return false`, which is ec94ab98's behaviour,
+    fails both new gate tests. In that mutant the nested write succeeds and the file exists.
+
+**Rationale.**
+
+- Attachment has one fact again. While the attach runs, the store's gate is the attach's
+  hold, and `Cache` is published when that hold ends. A cacheless write is a write the
+  store owns outright, so it must be the outermost hold of its store's gate. One more
+  argument to the existing owner of per-thread gate facts (`InStoreHold`) refuses it. No
+  field mirrors `Cache`, and `Loaded` and `_registry` are not read. Precedent:
+  `ConcurrentHashMap.computeIfAbsent` refuses a mapping function that updates the same
+  map with `IllegalStateException("Recursive update")` since Java 9. That is from
+  memory, not fetched this pass; the 2026-10-23 prior-art note covers the documented
+  restriction in its counter-positions. Non-cacheless store calls from user code still
+  re-enter: `UserCodeInACachelessCallMayCallItsOwnStore` stays green.
+- The late publish stays. It is what bounds `Gate` at two passes (s2's finding). Publishing
+  early would bring back the failure-rate-bounded retry.
+- The codec loan goes: it is a value nothing on the attach path reads. A pulled variant
+  carries no codec and counts as holding ids (the documented conservative answer), and
+  the cache's resolved copy is what any header decision sees. This reverses the codec
+  half of Defaulted ruling `late-publish-needs-attach-codec`, so it goes to Self as
+  `variants:question:pulled-variant-codec`. The spec is written for the recommended option.
+- Scar check: `git log -S` over CultCache.cs for `reentrant`, `outermost` and `_attaching`
+  finds nothing. `Cache?.Codec` appears in 1468a83a (h4) and 619e089f only. No earlier
+  re-entry refusal was built and deleted.
+- Behaviour change, stated in the CHANGELOG: a cacheless write made from user code that
+  another cacheless write of the same store runs used to succeed, and its `finally` took
+  the outer call's registry. It is now refused.
+
+## Store gate: Cache is the one attachment fact (store-gate-one-owner r3)
+
+Spec `variants:cut_spec:cut-store-gate-one-owner.r3` (base 0fa836cb), superseding r2. It
+closes Soul s4's `attach-window-held-store-writes` (Medium), `cacheless-refusal-order-unpinned`
+(Low) and `interop-consumer-suite-unrun` (Low). This is the third time the attach window has
+beaten the rule (s3 from the cacheless side, s4 from the held side), so r3 moves the
+decision instead of patching the next entry point.
+
+**Facts: every entry point that reads or decides attachment, at 0fa836cb.** Source reads of
+CultCache.cs, DirectoryMessagePackBackingStore.cs and CultMeshSingleFileDocuments.cs. The
+window column is a journal on the attaching thread, through a real attach of a store holding
+`a`. Probe: scratch clone `imagination-store-gate-r3/clone`, commit b2330b6d (test R3Probes),
+Yggdrasil `probe-base.log`, 2026-10-25 around 23:00 CEST. "Disagree" means that after the
+attach, a commit of `later` and a flush, the attaching cache holds `a,later` and a fresh cache
+over the same file reads something else.
+
+| Entry point (line) | Fact it reads | In the attach window at 0fa836cb |
+| --- | --- | --- |
+| Single-file `PullAll` (4156) | `Gate`: `Cache` guessed unlocked, then re-read under the re-entered store gate | Runs as detached; its `Loaded` re-enters the cache and is refused as a journal write. Agrees. |
+| Single-file `Push` (4212) | same | Runs as detached and stages `b`. Disagree: fresh reads `a,b,later`. |
+| Single-file `Delete` (4223) | same | Runs as detached and stages a removal the cache never made (dirty after the attach). |
+| Single-file `PushAll` (4239), and `Dispose` (3722) through it | same, then in-body `Cache == null` (4531, 4543, 4588, 4603, 4611, 4661) | Runs as a cacheless writer. Push then PushAll writes `b` to the file inside the attach (disagree). Delete then PushAll is refused with the cacheless writer's text. On a variant store it is refused as "a writer with no CultCache" (Soul s4). |
+| Single-file `CommitBatch` (4256) | same | Runs as detached and commits `b`. Disagree. |
+| Single-file `JudgeChecks` (4568), `RefuseRemovalOfUndeclared` and `StageChecks` (4558, 3915) | same | Run as detached. Agree in the probe, but under the wrong gate's rules. |
+| Single-file `ReadStoreSnapshot` (4687) | same | Runs as detached and reads the file. |
+| `WriteRecord` (4342), `WriteDocument` (4366) | `InStoreHold`'s per-thread hold (cacheless re-entry), before `Cache` | Refused with the re-entry text (h5). Agree. |
+| Directory `PullAll` (48) | `Gate`, as above | Refused as a journal write. Agree. |
+| Directory `Push` (147), `Delete` (160), `CommitBatch` (172) | same | Run as detached. Disagree: fresh reads `a,b,later` after Push or CommitBatch, and `later` after Delete. |
+| Directory `PushAll` (235) | same | Runs as detached. Push then PushAll and Delete then PushAll disagree. |
+| Directory `JudgeChecks` (269), `RefuseRemovalOfUndeclared` (259) | same | Run as detached. Agree. |
+| In-body reads: `StoredAtOver` clock (4028), refusal text and `DurableAt` (4531, 4543), declares and cacheless refusal (4588, 4603, 4611), `Wrote` (4661) | `Cache`, under the gate `Gate` chose | On the attaching thread they read null while the thread holds the cache's gate, so a held call runs as a cacheless writer. |
+| `AddBackingStore` (2259-2314) | writes `Cache` under both gates, after the pull | The window's author: the store is attached for the pull (registry lent, `Loaded` set, in `_stores`) while `Cache` is null. |
+| Mesh `CultMeshSingleFileDocuments` writes and reads (99, 143, 174, 226) | none of the attached store's | `StoreAt` (239) builds a new store per call, so they never touch an attached store object. A file it shares with an attached store is the file lock's and the write set's business. |
+| `IsDirty`, `HasStagedChecks`, `ForeignRecords`, `LastSchemaMigrationReports`, `HeaderFor`, `HeaderForWrite` | none | Ungated values or static decisions. They read no attachment fact. |
+
+So during an attach, cacheless entry points decide attachment from the hold, and every held
+entry point, plus every in-body read, decides it from `Cache`, which is still null. These are
+two facts.
+
+**Probe of the chosen shape** (commit 4695390c on b2330b6d; `proto-full.log`). `AddBackingStore`
+publishes `Cache` before the pull and takes it back in the same hold if the pull fails. `Gate`
+becomes straight-line code: guess, then the store's gate, where `Cache` is settled, then the
+settled cache's gate. Results:
+
+- All 21 probe cases are refused. The cacheless writes get the re-entry text and every other
+  case gets "A journal entered the cache it journals". After the flush, the attaching cache
+  and a fresh cache both read `a,later`.
+- Caching: the only failures are the two tests that pin the late publish:
+  `AnAttachLendsTheRegistryAndPublishesTheCacheAfterThePull` (asserts no cache during the
+  pull) and `ACallWhoseGateChangesTwiceUnderItThrowsInsteadOfLooping` (asserts the old message
+  text; the tampering reader still throws). The churn, queued-reader and failed-attach tests
+  pass unchanged.
+- Mesh and Networking are green.
+- The cultcache-ts suite, which builds and drives the C# InteropPeer, passes on this shape:
+  175 tests, 171 pass, 0 fail, 4 skipped. The C#, Rust and Python interop tests ran, the C#
+  edit-in-place one included (`proto-ts2.log`, commit f5f02053). Recipe `clone/r3ts.sh`:
+  image node:24-bookworm, apt python3-msgpack, dotnet-install for 10.0, rustup minimal.
+
+**Shapes weighed (rationale).**
+
+- (a) Publish `Cache` before the pull, as a616431e did. Chosen. What s2 found was not that an
+  early publish is unbounded. It was that `Gate` re-read `Cache` *unlocked* after a stale
+  guess, so a churn of failing attaches could hand it a new stale guess every pass. The fix is
+  where `Gate` reads on its second step. Under the store's gate, `Cache` is settled: an attach
+  publishes and takes it back inside one hold of that gate, and no other thread can hold that
+  gate during the attach. A settled cache is permanent, because there is no detach. So `Gate`
+  needs at most three acquisitions, with no loop and no counter: the guess's gate, the store's
+  gate, and then the settled cache's gate, which cannot miss. This deletes a fact rather than
+  reconciling two. During the attach the store *is* attached, so every entry point, cacheless
+  or held, and every in-body read sees one answer. A journal's call is then refused by the rule
+  journals already have (AddJournal: "any hold on this cache while a journal runs throws"),
+  exactly as it is after the attach. Prior art: `ConcurrentHashMap.computeIfAbsent` installs a
+  ReservationNode in the bin *before* running the mapping function, so a recursive update on
+  the same thread finds the owner and throws, and on failure the reservation is removed (see
+  `docs/research/2026-10-23-store-lock-user-code-prior-art.md` item 4 on main: the re-check
+  after locking, and the ReservationNode on the empty-bin path). The validate-after-acquire in
+  `Gate` is the same item.
+- (b) Keep the late publish and make the attach's hold the one fact for every entry point.
+  Rejected. `InStoreHold` knows that this thread holds the store's gate, not *whose* hold it is.
+  Refusing every same-store re-entry kills `UserCodeInACachelessCallMayCallItsOwnStore` (r2's
+  R5), so (b) needs an "attaching" marker beside `Cache`. That is the second fact that s3 and
+  s4 rule out, plus every in-body `Cache == null` read would need to consult it as well.
+- (c) Run no user code on the attaching thread under the store's hold during a pull: defer the
+  pull's journals to after the hold (open calls). Rejected as insufficient on its own. Getters
+  and constructors still run during the pull's decode, so the window stays open to any user
+  code that is not a journal. It also moves journal timing, which is a documented contract
+  ("right after an admission is applied").
+- Scar check: `git log -S` over CultCache.cs finds `store.Cache = null` and `MaxStaleGuesses`
+  only in ba658965 and 1468a83a. The early publish was not removed for a correctness reason of
+  its own: 1468a83a removed it to bound `Gate` and to lend the codec, and the codec loan is gone
+  (`pulled-variant-codec`). No settled read under the store's gate was built before. The
+  precedent recipe (no root filter) finds no same decision.
+- Not a product fork. A journal's store call during an attach now throws, as it already does
+  after the attach. Cacheless writes on the attaching thread stay refused, with the same text.
+  Getters and constructors during the pull see an attached store, as they do during any held
+  call. It changes the late-publish clause of Defaulted ruling `variants:ruling:pulled-variant-codec`,
+  so Self defaults a superseding ruling (recommended label `cache-published-for-the-pull`)
+  before dispatch.
+- Residual, not in r3. `Push`, `Delete`, `PushAll` and `CommitBatch` are public, so user code
+  that is not a journal (another thread, or a getter during any held call) can stage records
+  behind an attached store's cache. Soul s4 shows this with `other-thread-push`: file `a,b`,
+  cache `a`. That is true before, during and after an attach, so it is not the window's
+  two-fact problem. Closing it changes public API (a store's writes taken only from its
+  cache), so it is a follow-up and an operator question for Self, not part of this cut.
+
+## Body facts: claimant-one-owner r2 (Imagination, 2026-10-27, base fc74cf6f)
+
+Why a revision: Soul beat the same rule three times (s1 claimant choice, s2 compatible ids, s3 shape). Each time a
+cacheless write lent a registry let the registry's entry for the written schema id decide ownership beside the entry
+the caller passed. Two descriptions of one type reached `Owns`; each fix (h2 schema-id compare, h3 subset of compatible
+ids) compared one more facet of the two and left the rest open. r2 removes the second description from the lookup.
+
+### Where the two descriptions met (source read, fc74cf6f)
+
+- `OwnsOnDisk` cacheless arm (`CultCache.cs:4725-4740`): with a lent registry it called
+  `lent.Owns(id, catalog, declared, written)`, whose lookup is the registry's `_indexes` and whose `entryOf` is
+  `descriptor.ToCatalogEntry()` (`:824-825`). The claimant for the written schema id was the registry's descriptor,
+  so `ReadsWhole(persisted, claimantEntry)` (`:848`) judged shape against the registry's entry, and the claimant
+  precedence (`:756-806`) walked the registry's compatible ids. `written` (`:4734-4736`) then compared the two entries
+  by schema id plus a subset of compatible ids.
+- `WriteDocument` (`:4495-4524`) takes its entry from the registry (`resolvedRegistry.GetRequired<TDocument>().ToCatalogEntry()`),
+  so its two descriptions are always identical. Only `WriteRecord(record, catalogEntry, holdsIds, registry)` (`:4471`) can
+  pass an entry that disagrees with the registry's entry for the same id.
+- `CopiedHoldIds` (`:4600-4630`) also reads `AttachedRegistry`, to decide the v3 header from copied records. It is a
+  positive-only header decision, not ownership, and out of this cut.
+
+### Consumer audit (2026-10-27)
+
+- `WriteRecord` and `WriteDocument` are new in the Unreleased 3.0.0 entry; `main` has neither (`git show main:src/GameCult.Caching/CultCache.cs`).
+- Per-repo `rg` over every git repo directly under `F:\Projects` for `.WriteRecord(`, `.WriteDocument(`, `WriteSingleFileDocument`
+  (Library, obj, bin, PackageCache excluded): hits only in CultLib and in vendored CultLib copies under Heimdall and StreamPixels
+  (`vendor\CultLib`, older pins without these methods). No consumer outside CultLib calls either method.
+- Inside CultLib at fc74cf6f: Mesh `WriteSingleFileDocument` calls `WriteDocument(key, document, storedAt, registry)`;
+  Mesh's raw-payload path calls `WriteRecord(..., registry: null)` (`CultMeshSingleFileDocuments.cs:129, 226`). The only
+  `WriteRecord` calls with a registry are tests: `CachelessSingleFileTests.cs:453, 660` (a registry `{IdDeck}` that does
+  not hold the written entry `One` at all, used for the copied-record header), `RestampOnWriteTests.cs:595, 599`, and
+  Soul's probes. Packages: no TS, Python or Rust counterpart takes a registry (cultnet-rs `write_record` is an example helper).
+- Consequence: the registry's documented role in `WriteRecord` is to describe the other records in the store. A shape
+  that derives the written entry from the registry (or refuses an entry the registry does not hold) breaks
+  `CachelessSingleFileTests.cs:660` and removes that role.
+
+### Candidate shapes weighed
+
+| Shape | One description? | Public API | Kills s2/s3 | Cost |
+|---|---|---|---|---|
+| A. Lent registry's entry decides; refuse a passed entry that disagrees | yes, after a door check | signature kept; new refusal | yes | an equality check over a redundant parameter; breaks the registry-describes-others use (`:660`) when the registry lacks the written type unless it falls back to the passed entry, which is two descriptions again |
+| B. Passed entry is the only description of its schema id; the registry supplies other types only | yes, by construction | signature kept; doc only | yes (probed) | one lookup class gains the registry; one registry overload deleted |
+| C. Overloads: `WriteRecord(record, catalogEntry, holdsIds)` and `WriteRecord(record, registry, holdsIds)` | yes, by type | changes a 3.0.0 signature | yes | loses the registry-describes-others use |
+| D. Delete `WriteRecord`'s registry parameter | yes | changes a 3.0.0 signature | yes | loses the copied-record header decision for raw writes |
+
+Picked B. It is the only shape that keeps every documented use of the registry, needs no public signature change,
+and deletes the comparison instead of extending it. It is ordinary scoping (an inner binding shadows the outer one
+for its name), applied to schema ids.
+
+### Probes (Starfire, local filtered runs, 2026-10-27)
+
+Scratch clone of fc74cf6f at `<scratchpad>/imagination-claimant-r2/clone`, Soul's `SoulClaimantProbe.cs`,
+`SoulClaimant2Probe.cs`, `SoulClaimant3Probe.cs` copied into `tests/GameCult.Caching.Tests`.
+
+Base fc74cf6f (`probe-base.log`):
+- P7 (registry {N lists own, A, B}; passed entry N with the list varied; record k under O, named like N): lent R / no
+  registry C for rows b, b2, e, g, h, k, l, l2; lent C for a, c, d, f, i, j. Confirms `subset-refuses-own-drift`.
+- P9 (registry {NW: Name, Value, Colour}; passed NW minus Colour): lent C (restamped, Colour lost), no registry R.
+  Confirms `lent-shape-widens-passed-entry`.
+- P6 (bare X1 entry, registry {X1} listing OX, record under OX): lent R, no registry R, cache C. h3 closed the id axis.
+- P4: 12 states x 8 registries, violations=0. P1d: a cache {N,L} commits N over L's listed old id (`cache-replaces-other-types-record`).
+
+Prototype B (scratch commit 349ea3f3 on the clone, not for landing; `probe-protoB2.log`): `CatalogEntryLookup` takes
+the written entries and an optional registry and drops every registry descriptor whose schema id a written entry has;
+the registry's `Owns(schemaId, catalog, declared, mayClaim)` overload is deleted; the cacheless arm always asks
+`CultDocumentRegistry.Owns(id, catalog, declared, new CatalogEntryLookup(writes, AttachedRegistry), entry => entry,
+claimant => writes has claimant's schema id)`.
+- P7: lent == no registry on all 14 rows (all C).
+- P9: lent R, no registry R, wide entry C.
+- P6: unchanged (R, R, C). P4: identical table to base, violations=0. P1a-f, P2a-d: identical to base.
+- `RestampOnWriteTests`, `CachelessSingleFileTests` and the probes: 139/139 passed locally.
+- Yggdrasil, 349ea3f3, `ygg-protoB-full.log`: GameCult.Caching.Tests 1180 passed / 0 failed / 2 skipped;
+  GameCult.Mesh.Tests 342 / 0 / 4.
+
+Negative greps, each tested at fc74cf6f (each matches there, and none may match after the cut, src and tests):
+`claimant.CompatibleSchemaIds.All(` (1, the subset), `lent.Owns(` (1), `Func<CultSchemaCatalogEntry, bool> mayClaim) =>`
+(1, the deleted overload), `CatalogEntryLookup(writes)` (3, one-argument construction). CHANGELOG and docs:
+`never widens what the passed entry declares` (1), `with no compatible id the passed entry does not list` (1).
+
+### Not settled by r2
+
+- `cache-replaces-other-types-record` (s2, PreExisting, cache arm): r2 touches only the cacheless lookup, so it does
+  not settle whether a cache may replace another registered type's record at a shared key.
+- Whether a registry-less `WriteDocument` should consult `CultDocumentRegistry.Shared` for claimants at all (s1
+  `shared-decides-registryless-write`, closed Fixed by documentation in h2). r2 keeps today's answer.
+- `variants:finding:cut-restamp-on-write.s2.cacheless-inverts-registry-claimant` is still in force although r1 was
+  mapped to close it; Self should close or re-triage it after r2's Soul pass.

docs/cultlib-gaps-map.md

@@ -27,6 +27,83 @@ copy of the solver and the warm/cold sweep, `suite` a scratch copy of `packages/
    key tests read C#-written bytes instead of literals.
 7. `decode-stack-safety` (section D): cultcache-rs's one decode door grows its stack at every container level
    (ruling `decode-stack-mechanism-ruled`). Independent of 5 and 6; thing2's contract-rs merge waits on it.
+8. `expect-persisted-schema` (section E): an observed entry keeps the schema id it was persisted under and
+   conditional commit compares that (ruling `aetheria-release:ruling:expect-fix-in-cultcache`). C# only. The
+   release that carries it to Aetheria follows question `cultlib-gaps:question:expect-fix-release-lane`; the
+   Aetheria pin bump is an Aetheria follow-on, not this cut.
+9. `aot-record-ref-generator` (section A, AOT cut 1): a consumer with MessagePack's source generator on can declare
+   `CultRecordRef<T>` members and dictionary keys. Base: the C2a branch head `a768b821`; Hands starts after C2a merges
+   to main or rebases onto it. Serves `record-ref-breaks-msgpack-generator`, the first cut of
+   `cs-aot-safe-registration` (operator 2026-10-27: "I'm not a fan of requiring reflection. ... AoT is a nice thing to
+   support anyway.").
+10. Not mapped (AOT cut 2): the generator reaches consumers that reference only `GameCult.Caching.MessagePack` (today its
+   analyzer is `PrivateAssets="all"`, so they run every document on Reflection.Emit).
+11. Not mapped (AOT cut 3): registration descriptors are generated instead of reflected (`BuildDescriptor`,
+   `DiscoverMembers`, `CultDocumentResolver`, `CultMessagePackSecurity`), and C2a's element-id walk stops reflecting
+   (A6), so a NativeAOT consumer round-trips a ref-keyed dictionary.
+
+## A. AOT cut 1: CultRecordRef under MessagePack's source generator (cut `aot-record-ref-generator`)
+
+Imagination pass `imagination-aot-cut1`, session `self-2026-10-27-eureka`, pinned to `origin/hands/variants-c2a` at
+`a768b821` (C2a's head; merge base with main `02cf04b5`). Starting evidence: `research/cultmesh-garden-path/cultcache-aot-probe-2026-10-27.md`
+(main `eb6a8f2c`). Probes: the scratch console from that note, copied to the session scratchpad
+`imagination-aot-cut1/aot-probe/` and committed only as dangling commits on top of `a768b821` (`a0f06b2c`, `6d382961`,
+`dc6cf9dc`, `99cae039`, `07b89982`), run on Yggdrasil in `mcr.microsoft.com/dotnet/sdk:10.0` (MessagePack 3.1.7, .NET
+10.0.12). Logs `job1.log` to `job5.log` beside the probe. Variants: G = `CultRecordRef<T>` member only, H = ref-keyed
+`Dictionary<CultRecordRef<T>, float>` only, B = both. Every variant references `MessagePack` directly (generator on).
+
+### Body facts
+
+- A1. The generator does not discover `CultRecordRefFormatter<T>`. For a generic type it does not know, it collects
+  the type's definition as an object and names the formatter it would generate, `<Type>Formatter<T>`, nested in
+  `GeneratedMessagePackResolver`. For a type from another assembly it then generates nothing, so the resolver names
+  `GeneratedMessagePackResolver.GameCult.Caching.CultRecordRefFormatter<T>`, which does not exist (CS0426). The match
+  with our formatter's name is a coincidence. Evidence (job1): `[ExcludeFormatterFromSourceGeneratedResolver]` on the
+  formatter, and an `internal` formatter, both still fail G, H and B with the same line. Upstream issue
+  MessagePack-CSharp#2133 (open, no maintainer reply) reports the same failure for any open-generic type with a
+  formatter in another package.
+- A2. Consumer MessagePack 3.1.12, the newest stable, fails G, H and B the same way (job1). Upgrading does not fix it.
+- A3. `[MessagePackFormatter(typeof(CultRecordRefFormatter<>))]` on the `CultRecordRef<T>` struct stops the
+  generator naming a formatter for it (the mangled line is gone), but the generator then reports `MsgPack006` (error)
+  in every consumer: it checks `typeof(X<>)`'s interfaces, which an unbound generic does not list. Adding the
+  non-generic `IMessagePackFormatter` marker to the formatter does not help (job2 `ta2`). With `MsgPack006`
+  suppressed by the consumer, G, H and B build and run (job2). Rejected: it needs the formatter moved into
+  `GameCult.Caching`, which then needs the whole `MessagePack` package instead of `MessagePack.Annotations`, and every
+  generator consumer still has to suppress an error.
+- A4. `[assembly: MessagePackAssumedFormattable(typeof(CultRecordRef<>))]` in the consumer assembly fixes G, H and B
+  with no library change (job2 `base@ASSUMED`). The generator stops collecting `CultRecordRef<T>`; the generated
+  document formatter asks the resolver, and `CultDocumentResolver` serves the ref. This is the attribute MessagePack
+  documents for "a formatter added through a custom resolver at runtime". The same attribute as an MSBuild
+  `AssemblyAttribute` item in the consumer project (`_Parameter1_IsLiteral`), which is what a package's
+  `buildTransitive` targets injects, does the same (job3 MG, MH, MB). The attribute declared in the library assembly
+  does not reach the consumer's generator (job4 LIBATTR: CS0426).
+- A5. Generated and dynamic formatters write the same bytes. RefDoc (B) payload is `93A172A17081A170CA3F000000` from
+  the Reflection.Emit fallback with no generator (job3 BASE) and from the generated formatter (job3 MB). The document
+  formatter is `GeneratedMessagePackResolver+Probe+RefDocFormatter` (`dynamic=False`); the ref formatter is the
+  library's `CultRecordRefFormatter<PlainDoc>` through `CultDocumentResolver`.
+- A6. NativeAOT (`PublishAot`, probe assembly rooted, linux-x64): G round-trips (payload, upsert, flush, reopen) with
+  payload `92A172A170`, identical to JIT (job4 G0). B fails, in C2a code, not in the generator path: upsert fails in
+  `CultElementIds.MapEntries`, whose `MakeGenericMethod(key, value)` has no native code for a struct key (job4 B0). With
+  that walk reading the map through non-generic `IDictionary` instead, upsert passes under AOT and JIT is unchanged
+  (job5 B1), but the payload and flush still throw `TargetInvocationException` from a second reflective call on the
+  serialize path. By source read the candidate is `ResolverClaim`'s `GetFormatterMethod.MakeGenericMethod(type)`
+  (`CultDocumentMessagePackSerialization.cs:84`), not proven. Both are runtime reflection over element-id paths, which is
+  AOT cut 3's ground, so cut 1 proves AOT on the member shape and leaves the key shape's AOT round trip to cut 3.
+- A7. `GameCult.Geometry` already runs the generator (it references `MessagePack` directly) and carries the per-member
+  workaround on three members (`CultGeometryDocuments.cs:164,239,328`). Under A4 those attributes are redundant.
+
+### Shape the cut lands, and why
+
+`GameCult.Caching.MessagePack` ships `buildTransitive/GameCult.Caching.MessagePack.targets`, which adds the A4 assembly
+attribute to every project that consumes the package. NuGet consumers need no line of their own, which is what a
+consumer expects from a library whose type breaks the generator. Unity consumers and in-repo `ProjectReference`
+consumers do not get `buildTransitive`: Unity consumers write the one attribute line (README), and in-repo consumers
+import the targets file, so they exercise the file that ships. The attribute type comes from `MessagePack.Annotations`,
+which `GameCult.Caching` already brings, so the injection compiles in a consumer with or without the generator. Wire
+bytes do not change: no formatter changes, only which code path asks for it (A5).
+
+Rejected: a type-level formatter attribute (A3); excluding or hiding the formatter (A1); upgrading MessagePack (A2);
+declaring the attribute in the library (A4); keeping per-member attributes, which cannot reach dictionary keys.
 
 ## B. BoundedLeastSquares stopping
 
@@ -684,6 +761,65 @@ door-checked `rmpv::Value`s that way (follow-up `rs-redecode-outside-door-r2`).
 Rejected inside the ruling: the derive placement (above), and writing the wrapper by hand (D9: established
 tooling, one owner upstream).
 
+## E. Expect under compatible schema drift (cut `expect-persisted-schema`)
+
+Pinned base: `origin/main` at `b549d731` (2026-10-21). Imagination pass `imagination-expect`, session
+`self-2026-10-19-ag7`. Probe `probe1` (`ProbeExpectDrift.cs`, written into the clone by the job command, never
+committed) ran on Yggdrasil, dotnet sdk 10.0, against `b549d731`. Fixture: a record written under
+`DriftWide` (`tests.variant_drift.v1`) and read by a cache whose registry holds only `DriftNarrow` (v2) loads
+as CompatibleDrift.
+
+### Body facts
+
+- **E1. The defect.** `CultCommitRequest.ConditionsHold` (`CultCache.cs:1677-1696`) compares the durable
+  record's `SchemaId` with the observed entry's `Descriptor.SchemaId` (`Expect` captures it at `:1772`;
+  `ExpectUnchanged` reads it at `:1694`). `ToStoredDocument` (`:3212-3268`) resolves a persisted record to the
+  local descriptor and drops `record.SchemaId`. So the observed side holds the local id and the durable side
+  the persisted id. Probe: unchanged drifted record, `Expect` + `Upsert` commits **False** on the single-file
+  store (P1) and on the directory store (P7). Same code at Aetheria's pin `45c2f40` (`CultCache.cs:1147-1207`).
+- **E2. What must still refuse, at base.** Another cache commits a changed value (new minted `storedAt`):
+  Expect False (P4). Another cache reading under v3 (`DriftReused`) flushes the file, rewriting the record under
+  v3 with the **same** `storedAt`: Expect False (P5).
+- **E3. A whole-file write rewrites every record under its local schema and keeps `storedAt`.**
+  `ToPersistedRecord` (`:3194-3204`) writes `entry.Descriptor.SchemaId` with `entry.StoredAt`, and both the
+  single-file `PushAll` (`:3361-3375`) and an unconditional or dirty `CommitBatchCore` (`:3393-3399`) write the
+  whole view. So the contract sentence "every write to a key mints a later storedAt"
+  (`Contracts/cultcache-store-composition.md:229-231`) is false for a flush: the schema id is the half of the
+  identity that sees it. The directory store writes only staged keys, each freshly stamped
+  (`DirectoryMessagePackBackingStore.cs:240-293`), so it never normalises a clean record.
+- **E4. Lifetime at base.** After the cache's own `PushAll`, Expect commits True (P2): disk and descriptor now
+  agree. After *another* cache's normalising flush to the observer's own local schema, Expect commits True (P3);
+  after a re-pull, True (P6).
+- **E5. Re-reads.** Both pull filters skip a record whose `storedAt` and local descriptor id are unchanged
+  (`CultCache.cs:3323-3327`, `DirectoryMessagePackBackingStore.cs:110-114`). A record normalised P to L by
+  another writer keeps `storedAt` and the local id, so with the persisted id on the entry the filter must
+  compare the persisted id, or a re-read never refreshes it and Expect stays a Mismatch forever.
+- **E6. Other runtimes.** cultcache-rs `SingleFileMessagePackBackingStore::compare_exchange` and the snapshot
+  form (`packages/cultcache-rs/src/lib.rs:1352-1393`, `:1427-1450`) compare whole raw envelopes as read from
+  disk (`schema_id: Some(record.1)`, `:3189`); the expectation *is* the persisted envelope, and the crate has
+  no compatible-drift resolution, so the split cannot occur. Unchanged. cultcache-ts and cultcache-py have no
+  conditional commit (`cultcache-persistence-format.md:67-69`; grep finds none); nor do the cultnet and
+  cultmesh packages or cultmesh-kotlin. Not added here.
+- **E7. Release path.** Aetheria pins `org.gamecult.cultlib#cultlib-unity-v1.0.60` and
+  `org.gamecult.caching.unity#caching-unity-v1.4.0`, both locked at `45c2f400` (2026-09-17). The CultCache
+  runtime ships as DLLs in `unity/org.gamecult.cultlib` (built by `scripts/build-unity-package.ps1`). Main is
+  1363 commits past the pin with a `### Breaking` section under `[Unreleased]`
+  (`unity/org.gamecult.cultlib/CHANGELOG.md`). `release/cultlib-unity-1.0.x` is the pin plus one commit
+  (1.0.61, Win64 QUIC plugins).
+
+### Authority, and why
+
+The backing store that read or wrote a record's durable bytes owns the schema id it is persisted under. It is set
+when the store builds the entry from a persisted record (`ToStoredDocument`), defaults to the descriptor's id
+for an entry this cache stamps (it is about to be written under that id), and is reset to the descriptor's id,
+under the hold, after a whole-file write the store completed. The commit check, `Expect` and the pull filters
+only read it. `Descriptor.SchemaId` stays what the entry decodes as; it is no longer the record's durable identity.
+
+Consequence, recorded rather than ruled: after another writer's whole-file flush rewrites a drifted record
+under a schema id this cache did not read it under, an `Expect` captured before is a Mismatch until the cache
+re-reads (E4's P3 flips). That is the ruling's "compares that persisted id" applied to a rewrite that kept
+`storedAt`; it is fail-closed, the standard retry (re-read, retry) recovers, and it is what refuses E2's P5.
+
 ## Observed, not owned by these cuts
 
 - At the default tolerance the solver's answer on allocator-shaped problems depends on the start by up to the whole

docs/cultmesh-garden-path-map.md

@@ -0,0 +1,88 @@
+# CultMesh garden path: map
+
+Campaign `cultmesh-garden-path`, stage 1 (server-authoritative garden path for the
+orbs .io game). Target: `docs/cultmesh-garden-path-target.md` (typed as
+`cultmesh-garden-path:target:r2`). Rulings, questions and follow-ups are documents
+in the mind; this page holds the model page, body facts and the stage 1 cut lines.
+
+Written by Imagination (`imagination-gp-0b`, session `self-2026-10-27-eureka`)
+against CultLib `d1bf21b3`. Refreshed by `imagination-gp-stage1` (session
+`self-2026-10-27c-eureka`) against `51ca81a1`: every fork the page waited on is
+ruled, and the cells below carry the rulings.
+
+## Model page
+
+One row per kind. "Store" says where it lives: a CultCache document in the room's
+store, or transient per-tick data that never enters a store. Proposed values are
+marked as such; they are the design this page offers for the cuts, not landed
+behaviour. A cell that waits on an operator question names it.
+
+The governing split, from `state-is-cultcache` and the CultCache scope restraint:
+every value that crosses a boundary is CultCache-encoded (one serialisation model,
+no JSON), but only state that outlives a tick is a record in a store. Inputs, ticks
+and snapshots are typed CultNet message payloads, not store records. The store
+receives exactly one write set per tick (ruled `tick-state-commit`: tick-batch).
+
+| Kind | Store | Identity (what names it) | Lifecycle (what happens to it) | Authority (who decides; forbidden writers) |
+|---|---|---|---|---|
+| **Game definition** (documents, systems, authority declaration, tick rate) | Proposed: one CultCache document per server process (`gamecult.mesh.game_definition`), read-only to everyone but the server's startup. | Game id string from code (`"orbs"`), namespaced by Verse id. The id alone is not injective (two builds share it), so proposed identity is `(game id, definition hash)`, the hash derived from the lowered definition: document schema ids and versions, system ids, order and marks (`[Predicted]`, later `[Adjudicable]`), tick rate, authority declaration. Schema ids (`orbs.player`) are global strings; the game prefix is convention, not enforced (body fact F9). | Created at server startup from code; never revised at runtime; a new build supersedes it with a new hash. Clients carry their own compiled hash (C# in wasm, ruling `browser-sim-runtime`) and are refused at join on mismatch. A declaration a mode cannot honour is refused at startup (`modes-do-not-leak`). Never replayed. | The game's code, through the builder, at startup; the runtime validates. Forbidden: clients, any runtime mutation, Odin (Odin may read and index it, never write it). |
+| **Game document** (Player, Pellet, Shot) | CultCache documents in the room store. | `(schema id, record key)`. Today the key is a free string the caller picks; `[CultIndex] Id` in the illustration is an index, not the key. Proposed: the runtime mints keys. Player key derives from the session principal (one Player per principal per room). Spawned documents (Shot, Pellet) key on `(spawner key, tick, spawn ordinal within that tick)`, so a client's predicted spawn and the server's authoritative spawn derive the same key and reconcile instead of duplicating. That is injective as long as spawn order within a system step is deterministic for the predicting client, which the predicted system's own code gives under one runtime (C# both sides). The developer's `Id` field becomes redundant; whether to keep it as a mirror of the key is an API call for the cut, not an operator fork. | Created by a system during a tick, or by the join system (Player). Revised at most once per tick, in that tick's commit. Deleted by a system (pellet eaten) or by the game's leave system after a session ends. Across reconnect within the grace window the Player record is unchanged; only the session's connection binding moves. Across a server restart: gone (ruled `room-durability`: ephemeral; a restart is a new room epoch at tick 0). Replayed only on the client, during reconciliation; the server never replays in stage 1. | The server tick runner on the room's primary is the one writer of committed state, and systems write only through the tick's working set. Forbidden writers: client document puts through `CultNetDatabaseServer.HandlePutAsync` (today accepted from any peer, F1); `PutPredictedAsync` and `CultMeshGameSession.PredictAsync` on any networked store; game code calling database APIs; the simulation-fact committer (F7). |
+| **Player input** | Transient. A CultCache-encoded payload on a CultNet message; never a store record in stage 1. | `(session principal, input sequence)`, the sequence monotonic per session; each input also carries the tick it targets. Namespace: the room. Injective given the principal. The input type is a schema'd CultCache type, so the schema catalog publishes it like any document. | Sampled each client tick (devices read by the TS shell, handed to wasm); sent with the last few unacknowledged inputs repeated, so one loss is absorbed; buffered by the server per session against its target tick; consumed exactly once by the matching tick (proposed policy for late inputs: applied to the next tick and counted); acknowledged in the snapshot as "last processed sequence"; kept by the client until acknowledged, for replay; then discarded. Stage 4 changes this: inputs become signed, hash-chained and retained for a dispute window. | The client's principal authors the content; the tick runner decides which tick consumes it. Forbidden: server code altering input content; other clients; any input that arrives without a bound session. |
+| **Tick** | Transient counter; proposed: the last committed tick is written into the room record in each tick's batch, so a snapshot or checkpoint knows it. | `(room id, room epoch, tick number)`, the number starting at 0 when the room epoch starts. Injective with the epoch. | Advanced only by the server tick runner at the one declared rate (ruled `tick-model`: one-fixed-rate); never revised. The client estimates the server tick from snapshots and runs its predicted tick ahead by its round trip plus a buffer; on reconnect it re-syncs from the next full snapshot. | Server tick runner. Forbidden: client clocks, transport arrival time, wall-clock reads inside systems (systems receive the tick, not the time). Today no tick scheduler exists anywhere in the C# body (F6). |
+| **Predicted state and reconciliation** | Client-side only. In the browser they live in the C# wasm CultCache store; the TS renderer reads a per-frame view (ruled `browser-client-store`: wasm-owns-store). | Same `(schema id, record key)` as the authoritative document, plus the client tick it was predicted for. | Each client tick: predicted systems run over owned documents and the client's own spawns. On a snapshot for tick T acknowledging input sequence S: predicted documents are replaced by the authoritative ones at T, then inputs after S are replayed through the predicted systems up to the current client tick; predicted spawns are matched by derived key, and an unmatched one is removed once the acknowledgement passes its tick. Today `Reconciled` means "the authoritative put replaced the predicted copy" with no replay (F3); the replay loop does not exist. | Predicted state owns nothing outside the client. It is derived from the last authoritative snapshot plus unacknowledged inputs plus the predicted systems. The snapshot owns truth. Forbidden: sending predicted documents to the server; `CultNetClientAuthorityScope` in server mode (F4); the renderer writing. |
+| **Session and the player's identity** | Proposed: session membership as a small CultCache document in the room store (`gamecult.mesh.game_session`, low churn, readable by systems and present in snapshots). The connection handle is transient process state. | Principal: the fingerprint of a browser-held P-256 key, proved by signing a join challenge (ruled `player-identity`: browser-keypair). Connection: a server-minted id per transport connection (ephemeral). Logical session: `(principal, room)`, bound across reconnects. Today the client's identity is a self-asserted `runtimeId` string (browser client options; `SourceRuntimeId` on operation envelopes); CultMesh's session identity proves the server to the client and not the reverse (F5). The body still has no authenticated client principal (F5, F13); the session cut builds it. | Connect, then join (definition hash check, principal proof), then the session record is created and the join system spawns the Player. Disconnect suspends the session for a grace window; resume binds a new connection to the same session; expiry ends the session, systems see the leave, and the game's leave system removes the Player. On server restart sessions end (ruled `room-durability`). | The server's join and leave handler on the room primary decides membership; the principal proves itself by signing the join challenge. Forbidden: a client-asserted `runtimeId` as identity; transport peer address; peer catalogs. |
+| **Authority declaration and the lease it lowers to** | Declaration: inside the game definition. Lease: proposed as a CultCache document (`gamecult.mesh.authority_lease`); today a plain class in an in-memory dictionary (F2). | Declaration: per document type, `(writer, checker, arbiter)`. Lease: `LeaseId`, carrying Verse, peer, roles, shard ids, issuer, validity window, epoch and signature (`CultMeshAuthorityLease`). Namespace: the Verse. | Declaration fixed per build. At startup `Authority.Server` lowers to: the server holds a `ShardPrimary` lease on the room shard, and clients hold no write scope at all. Renewed before expiry; revocation or expiry stops the tick runner from committing; a new primary takes a new epoch. Proposed issuer in stage 1: the server's own deployment key, which clients pin through the browser trust policy, so an indie deployment needs no Odin. Odin-issued leases stay possible. | The game definition decides the declaration; the issuer issues leases; `CultMeshAuthorityResolver` decides whether a peer holds a role on a shard. Today the database's write gate (`CultNetShardDescriptor.IsPrimary`, `CultNetClientAuthorityScope`, both set from options) never consults the resolver: two authority structures (F2, F4). Proposed: the write gate is derived from lease resolution. First step (cut `remote-write-authority`): a peer's put or delete reaches the database only when `CultNetDatabaseServerOptions.RemoteWriteAuthority` grants it; none configured refuses every remote write (F1, GP1). The lease-backed grant needs an authenticated principal bound to the connection, so it follows the session cut. `CultNetClientAuthorityScope` is no longer an owner; it is derived from the declaration, and in stage 1 it is empty. |
+| **Shard / room** (stage 1: one) | `CultNetShardDescriptor` (configuration); the room's state is its CultCache store. | Room id `(Verse, game id, room name)`, for example `orbs/main`, carried as the shard id plus the shard epoch. | Created at server start (epoch 1; on restart a new epoch, ruled `room-durability`); never moved in stage 1; ended at shutdown. Join means "join the one room"; matchmaking is out of scope. Interest management is stage 5 per the target, so in stage 1 every client receives the whole room. | The runtime holding the `ShardPrimary` lease. Forbidden: a second primary; clients. |
+| **Snapshot sent to clients** | Transient. A CultNet message whose payload is CultCache-encoded documents; never stored. The server keeps per-client baselines in memory for deltas. | `(room, epoch, tick, recipient session, baseline tick)`. | Derived after a tick commit at the send rate; a delta against the recipient's last acknowledged snapshot, or a full snapshot on join and resume; carries the last processed input sequence for that session. Discarded once sent; a baseline is dropped when a newer one is acknowledged. Today the nearest things are per-record change pushes from `CultNetDatabaseSubscriptionServer` (no tick, no acknowledgement, no input sequence) and shard catch-up snapshots in `CultMeshSnapshots.cs` (F8). | The snapshot builder decides nothing; it is derived from the committed tick. Forbidden: the per-record subscription stream acting as a second game replication path. That stream stays for non-game observers. |
+| **Simulation fact / witness observation** (found) | `CultMeshSimulationFact` is a CultCache document; observations are hub memory. | `(shard, epoch, frame, subject, kind)`. | Stage 1: not used. The target replaces it at stage 4. | Today `CultMeshGameSession` serves observations by default (`ServeSimulationObservations = true`) and commits quorum facts through the primary (F7). In server mode there is no checker, so the observation server and the committer must not be wired. Forbidden writer in stage 1. |
+| **Shard mutation log entry** (found) | `CultNetDatabase` in-memory `SortedList` per shard, plus an optional durable store. | `(shard id, sequence)`. | Today every primary write appends one entry, and the in-memory list is never trimmed (F10). Per-record writes at tick rate would grow it without bound. In stage 1 the tick's write set either bypasses the per-record log or lands as one bounded entry per tick. Ruled: the tick's write set lands as one batch per tick (`tick-state-commit`), in memory (`room-durability`); the bounded per-tick entry is the tick-runner cut's to specify. | `CultNetDatabase` on the primary. Forbidden: per-system-write appends from the tick runner. |
+
+### Cells filled by rulings (2026-10-27)
+
+- Session principal: `player-identity` (browser-keypair). Not yet in the body (F5, F13).
+- Browser documents and the renderer's read: `browser-client-store` (wasm-owns-store).
+- Room state across restarts: `room-durability` (ephemeral).
+- Tick rate model: `tick-model` (one-fixed-rate).
+- How a tick reaches the store: `tick-state-commit` (tick-batch; the tick-runner cut times `CultCacheBatch` at tick rate first).
+- Stage 1 transport: `browser-transport` (WebSocket behind a port carrying only inputs and snapshots; a WebTransport server in parallel, `webtransport-server-layer`: managed C# over the MsQuic bridge).
+- Still unprobed: `CultCacheBatch` commit cost at tick rate for about 50 players plus pellets (wasm measuring probe and tick-runner cut).
+
+## Body facts
+
+All are source reads at CultLib `d1bf21b3` on 2026-10-27 by `imagination-gp-0b`. No
+runtime probe was run in this pass. Each fact names the read that would falsify it.
+
+- **F1. The primary applies any peer's document put.** `CultNetDatabaseServer.HandlePutAsync(message, peer)` (`src/GameCult.Networking/CultNetDatabaseServer.cs:307`) calls `ApplyPutAsync(message)` (`CultNetDatabase.cs:1022`), which checks only that this runtime is primary for the shard and the epoch matches (`EnsurePrimary`, `:2003`). `peer` is used only to send errors. Any connected client can overwrite any game document on the server.
+- **F2. Leases are not typed state and do not gate writes.** `CultMeshAuthorityLease` is a plain class (no `[CultDocument]`); `CultMeshAuthorityLeaseCatalog` is a `Dictionary` (`CultMeshAuthority.cs:242`). The only `[CultDocument]` types in `GameCult.Mesh` are body publication, CDN chunk and manifest, content transfer state, discovery state, entity prefab package and simulation fact. `GameCult.Networking` (the database) references no lease type; the one Networking file naming `Lease` is `CultNetSchemaMessages.cs`.
+- **F3. Reconciliation is replacement, not replay.** `CultNetDatabase.cs:1247-1252`: a predicted put records a prediction key; the next non-predicting write to that key turns the change into `Reconciled`. No code re-applies inputs after an authoritative state.
+- **F4. Client write scope is a runtime-id string match from options.** `CultNetClientAuthorityScope.Matches` compares `OwnerRuntimeId` with the database's own `_runtimeId` (`CultNetDatabase.cs:111-153`, `EnsureClientAuthority` `:1934`). It gates local prediction only and has no relation to leases.
+- **F5. No authenticated client principal.** `CultMeshSessionIdentity.cs` verifies transports for `(verse, authorityRuntimeId, protocol, routeGeneration)`, which proves the server to the client. The browser client's `runtimeId` (`packages/cultmesh-browser/src/index.ts:182`) and the operation envelope's `SourceRuntimeId` (`CultNetOperationServer.cs:39`) are self-asserted.
+- **F6. No tick scheduler.** A grep of `GameCult.Networking` and `GameCult.Mesh` for tick or timestep names finds none. `Frame` exists only as a witness-asserted number in `CultNetSimulationConsensus` and `CultMeshSimulationFact`.
+- **F7. The game session serves the witness path by default.** `CultMeshGameSession` constructs `CultNetSimulationObservationServer` when `ServeSimulationObservations` (default `true`) and always constructs a `CultMeshSimulationFactCommitter` (`CultMeshGameSession.cs:70-104`). `PredictAsync` is `PutPredictedAsync` (`:161`).
+- **F8. The browser can watch and invoke, not put.** The `cultmesh-browser` README says it "does not expose direct document writes". The client offers `leaseRawDocument` (`index.ts:349`) and `invoke` of typed operations (`:370`), over one WebSocket. On C#: `CultNetDatabaseSubscriptionServer` and `CultNetOperationServer` take `ICultNetSchemaServer`, so they run over `CultNetWebSocketSchemaServer`; `CultNetDatabaseServer` (puts) takes the concrete UDP `Server` (`CultNetDatabaseServer.cs:36`). Operations are request and response with receipts and idempotency keys, which is a poor fit for an input stream at tick rate.
+- **F9. Schema-id namespacing is convention.** `[CultDocument("orbs.player", ...)]` ids are global strings; nothing ties a schema id to a game id.
+- **F10. The in-memory mutation log is never trimmed.** `RecordMutationLogEntry` (`CultNetDatabase.cs:1610`) inserts into a per-shard `SortedList`; no `Remove` or trim on that list exists in the file. Compaction applies to the durable store and to burned sequences only.
+- **F11. CultCache has a write-set batch; CultNetDatabase does not expose one.** `CultCacheBatch` with `Commit` and `TryCommit` (`GameCult.Caching/CultCache.cs:1796`, `:2212`) is the 2.0.0 write set (`variants:ruling:write-set-content-version-declared-ownership`). `CultNetDatabase` has no batch method: every write is a per-record door.
+- **F12. A reflection site on the mesh put path.** `CultMesh.cs:3502` `PutDatabaseDocumentAsync` picks `PutAsync` or `PutPredictedAsync` by `GetMethods` and `MakeGenericMethod`, which matters to the AOT prerequisite (`cultlib-gaps:follow_up:cs-aot-safe-registration`; probe in `research/cultmesh-garden-path/cultcache-aot-probe-2026-10-27.md`).
+
+- **GP1 (runtime probe, 2026-10-28, `imagination-gp-stage1`).** Scratch NUnit test at `51ca81a1`, run on Yggdrasil (`ygg-verify.sh`, `mcr.microsoft.com/dotnet/sdk:10.0`, filter `ImagGpProbeTests`, never pushed to origin). The server writes `gp:player` = "server-owned" through `CultNetDatabase.PutAsync` on a primary shard. `CultNetDatabaseServer._putHandler`, invoked with an uninitialized `CultNetServerPeer` (no field set: no endpoint, no transport, no identity) and a put of "client-overwrote", leaves the record "client-overwrote", and `Server.CanProcessBeforeVerification(put)` returns `true`. Output: `GP1 after=client-overwrote canProcessBeforeVerification=True`, Passed 1. This confirms F1 at runtime: nothing about the peer is consulted, and puts and deletes pass before the legacy login verification (`Server.cs:562-575`).
+- **F13. A server peer carries no identity.** `CultNetServerPeer` (`Server.cs:829`) holds the LiteNetLib `NetPeer`, its endpoint and transport stats. The only principal on `Server` is the legacy username and password login (`PlayerData.PlayerId`, `IsVerified` `:697`), which the database door never reads. `ServerSecurityOptions` is one shared `ConnectionKey`: transport admission, not authority.
+- **F14. A new refusal code is a coordinated change.** The `cultnet.error.v0` `code` is a closed enum (`contracts/cultnet/cultnet.error.schema.json:28-31`, with a byte-identical copy under `packages/cultnet-rs/contracts/`). Rust `CultNetErrorCode` (`packages/cultnet-rs/src/contracts.rs:242-273`) refuses unknown codes, `packages/cultnet-rs/tests/error_message.rs` decodes captured C# bytes per code, and TypeScript imports the root schema (`packages/cultnet-ts/src/contracts.ts:10`). `unowned_schema` was added this way and is the pattern.
+- **F15. Forwarding re-sends as a new client.** `TryForwardPutAsync` (`CultNetDatabaseServer.cs:654`) forwards a `not_primary` put through `ICultNetShardWriteForwarder`, and `CultNetSchemaWriteForwarder` opens its own client connection (`CultNetShardWriteForwarding.cs:122-128`). The primary therefore sees the forwarding runtime, never the original peer.
+- **F16. Consumers of the remote write door.** No C# consumer outside CultLib constructs `CultNetDatabaseServer` (grep of the Aetheria, Epiphany, Ghostlight, huginn and gamecult-ops `*.cs` files finds only vendored CultLib copies). In CultLib, tests reach the put and delete handlers directly in `CultNetJournalTests.cs:738`, `:935-936` and `SoulP4cProbeTests.cs:57`. `CultNetDatabaseServer.ApplyPutAsync` and `ApplyDeleteAsync` (`:73`, `:81`) have no caller in `src` or `tests` besides the handlers. TypeScript puts (the `cultnet-ts` Idunn presence and signed health publishers) target Rust servers.
+- **F17. The Rust document server admits a put by size only.** In `packages/cultmesh-rs/src/rudp_document_server.rs:682-720`, a `DocumentPutRaw` is refused only when its served response would not fit; no authority is asked. This is F1's gap in the Rust runtime (a follow-up, not stage 1).
+
+## Cut sequence (stage 1)
+
+One line per cut not yet mapped. The model page has no empty cell as of 2026-10-28. Remote write authority (`cultmesh-garden-path:cut_spec:cut-remote-write-authority.r1`, mapped 2026-10-28, so no longer a line here) goes first: it waits on nothing, every later server cut stands on a closed write door, and GP1 shows the door open today. The wasm measuring probe is the sibling that may run beside it, since it touches no file this cut does; ruling `browser-sim-runtime` names it the first cut of the browser runtime track, not of stage 1 as a whole.
+
+- **Wasm runtime measuring probe.** Download size, startup and 60 Hz tick cost of a stub orbs tick under Mono browser-wasm and NetWasm, including `CultCacheBatch` commit cost at tick rate. This is the first cut named by ruling `browser-sim-runtime`, which it can overturn. Its NetWasm and AOT variant waits on `cultlib-gaps:follow_up:cs-aot-safe-registration`.
+- **Witness services off in server mode.** `CultMeshGameSession` stops constructing the observation server and fact committer when the declaration has no checker (F7). Waits on nothing; can run beside remote write authority.
+- **Leases as typed state and the lease-derived grant.** `CultMeshAuthorityLease` becomes a CultCache document, the lease catalog a store view, and the Mesh host's `RemoteWriteAuthority` resolves the connection's principal through `CultMeshAuthorityResolver`. Waits on remote write authority and on session and principal.
+- **Demote `CultNetClientAuthorityScope`.** It becomes derived from the authority declaration (empty in server mode). Waits on game definition.
+- **Changelog entry for the remote write refusal.** `unity/org.gamecult.cultlib/CHANGELOG.md` is also written by `variants:cut_spec:cut-write-ownership-cs.r1`, so Self adds this cut's bullet at merge, after that cut lands, and the two specs share no file.
+- **Game definition and server tick runner.** Builder, document and system registration, definition document and hash, fixed tick, tick-boundary commit. Rests on rulings `tick-model`, `tick-state-commit` and `room-durability`; waits on nothing mapped.
+- **Session and principal.** Join, resume and leave; principal proof; session document. Rests on ruling `player-identity`; waits on game definition (the join checks the definition hash).
+- **Input and snapshot path.** Input messages with redundancy, a server input buffer, acknowledgements, delta snapshots. Rests on ruling `browser-transport`; waits on session and principal.
+- **Browser client runtime.** Wasm simulation host, TypeScript shell for transport and rendering, prediction with replay reconciliation. Waits on the measuring probe and `browser-client-store`.
+- **Orbs reference game and garden-path proof.** The game written with no networking code (`garden-path-needs-no-networking`), and a browser client that writes (`browser-is-first-class`). Waits on all of the above.

docs/cultmesh-garden-path-target.md

@@ -0,0 +1,153 @@
+# CultMesh garden path: target
+
+Status: draft target for campaign `cultmesh-garden-path`, 2026-10-27. It holds the
+ends, not the means. The code below is illustrative: it shows what a developer
+should have to write, and no name in it is decided.
+
+## The problem
+
+Operator, 2026-10-27: "the value is in solving the multiplayer scaling problem
+for indie developers in an ergonomic fashion. Having one authoritative server is
+fine, up to a point, but there's no real open source playbook on how to ship an
+MMO, and existing solutions like SpacetimeDB have a huge ergonomics gap. I want
+CultMesh to feel like magic: as a garden path, you annotate your domain POCOs and
+simulation code and declare your authority structure ... and it'll all just work
+without the developer needing to understand networking deeply."
+
+Prior art: `research/cultmesh-garden-path/prior-art-2026-10-27.md` (frameworks,
+ergonomics, scale-out) and `research/witness-authoritative-networking/` (consensus
+and P2P anti-cheat). What the field shows, in short:
+
+- One API over several authority modes ships today (Photon Fusion: Server, Host,
+  Shared; Unity NGO: client-server and distributed authority), and in both the
+  modes leak into the developer's code (`IsServer` against `HasAuthority`,
+  features missing in one mode).
+- SpacetimeDB gives one machine per database. Scaling past it, client
+  prediction, and the reducer-shaped rewrite of game code are left to the
+  developer.
+- Determinism, where it is required at all, is required of the whole simulation
+  (Croquet/Multisynq, Photon Quantum), and that tax is the main ergonomic cost.
+- Shipped world-scale designs treat a spatial unit as indivisible and move
+  players between units (EVE, Pax Dei, Folia); nobody publishes an open,
+  end-to-end playbook (Astron, the nearest, is discontinued).
+
+## What a developer writes (illustrative)
+
+The reference game is a small browser .io game (operator, 2026-10-27: "the .io
+game, Aetheria later"): players steer orbs, eat pellets, and shoot.
+
+```csharp
+[CultDocument("orbs.player", "orbs.player.v1")]
+public sealed class Player
+{
+    [CultIndex] public string Id { get; set; } = "";
+    public Fix2 Position { get; set; }
+    public Fix2 Velocity { get; set; }
+    public int Mass { get; set; }
+}
+
+[CultDocument("orbs.shot", "orbs.shot.v1")]
+public sealed class Shot
+{
+    [CultIndex] public string Id { get; set; } = "";
+    public string Shooter { get; set; } = "";
+    public Fix2 Origin { get; set; }
+    public Fix2 Direction { get; set; }
+}
+
+// Runs every tick. Predicted on the owning client, corrected by authority.
+public sealed class Movement : CultSystem
+{
+    [Predicted]
+    public void Step(Player player, PlayerInput input, Tick tick) { /* ... */ }
+}
+
+// A non-owner may re-run this to settle a dispute, so it must be
+// deterministic. The analyzer enforces that on this system only.
+[Adjudicable]
+public sealed class Hits : CultSystem
+{
+    public HitResult Resolve(Shot shot, Rewind<Player> target) { /* ... */ }
+}
+
+var game = CultMesh.Game("orbs")
+    .Documents<Player, Pellet, Shot>()
+    .Systems<Movement, Eating, Hits>()
+    .Authority(Authority.Server);
+//  .Authority(Authority.TrustedCoop);
+//  .Authority(Authority.Witnessed(w => w.Challenger(Party.Victim).Quorum(3).Arbiter(Party.Server)));
+//  .Authority(Authority.Regions(r => r.Grid(512).Handoff()));   // later: past one server
+```
+
+Changing the authority line is the whole migration between modes, unless the new
+mode re-executes a system on a non-owner and that system is not yet
+deterministic. Then the analyzer names exactly those systems.
+
+## Invariants
+
+- `one-model`: server-authoritative, trusted co-op, witnessed and regioned
+  authority are configurations of one authority declaration, answering per
+  document: who writes, who checks, who arbitrates. No mode has its own API for
+  state, systems or queries.
+- `modes-do-not-leak`: game code does not branch on the authority mode or ask
+  "am I the server"; a system states what it does and the runtime decides where
+  it runs. Where a mode cannot offer a capability, the declaration is refused at
+  startup with a reason, never degraded silently at runtime.
+- `determinism-is-per-system`: only code a non-owner may re-execute must be
+  deterministic. That requirement is marked on the system and checked by an
+  analyzer at build time, not by documentation or by desync in production.
+- `state-is-cultcache`: game state is ordinary CultCache documents; the
+  framework adds no second state model and no JSON on the load-bearing path.
+- `authority-is-typed-state`: who holds authority over what is CultMesh state
+  (leases, shard primaries), inspectable and revocable, never inferred from
+  transport success or peer catalogs.
+- `garden-path-needs-no-networking`: the reference game is written without the
+  developer touching sockets, serialisation, tick scheduling, prediction or
+  reconciliation code.
+- `honest-guarantees`: each mode states its fault model (trusted server, trusted
+  peers, honest-majority sampled witnesses with server arbitration) and its
+  documentation and tests claim nothing past it.
+- `browser-is-first-class`: the reference game's client runs in a browser and can
+  write (submit inputs, own predicted state), not only watch.
+- `built-for-load`: what the garden path ships that is database-shaped (the
+  tick commit, the batch door, logs, subscriptions) is architected for
+  unreasonable load from the start (operator 2026-10-27,
+  `cultlib-gaps:ruling:database-shaped-built-for-load`): "if what we're shipping
+  is database shaped, people will use it as such".
+
+## Sequence (each a campaign or stage of its own; one foundation at a time)
+
+1. Server-authoritative garden path for the .io game: documents, systems,
+   ticked scheduling, client prediction and reconciliation, browser client that
+   writes. This is the proof of ergonomics.
+2. Trusted co-op: authority moves to the owning peer; same game code.
+3. Deterministic dispute kernel (CultMath fixed-point hit tests, cross-runtime
+   vectors) and the `[Adjudicable]` analyzer.
+4. Witnessed authority: signed, hash-chained inputs; victim challenge; sampled
+   network-near witnesses; server arbitration; browser-to-browser channels.
+   Demonstration: a cheating client caught and corrected.
+5. Regions: spatial authority handoff and interest management past one server.
+6. Aetheria on the same declaration.
+
+## Not in scope
+
+- Aetheria until stage 6. Eve and Gjallar (deprecated).
+- A new CultCache storage engine (the paged single-file store stays postponed,
+  `variants:ruling:page-tree-store-postponed`). The garden path fills gaps in
+  their owners, built for load.
+- Asynchronous Byzantine total ordering, zero-knowledge proofs, and chains of
+  any kind.
+- The existing witness aggregator (`CultNetSimulationConsensus`, unsigned and
+  weighted by observed votes) as a base for stage 4: it is the trusted co-op
+  first stage by design and will be replaced, not extended.
+
+## Open forks (to the Fork Desk, each with prior art first)
+
+1. Where simulation code runs in the browser: C# compiled to WebAssembly (one
+   implementation everywhere, which also shrinks the determinism problem to
+   fixed-point maths, at the cost of runtime download size), C# on the server
+   with TypeScript systems in the browser (two implementations of each predicted
+   system), or another arrangement.
+2. Server transport for the browser: WebSocket as today, or WebTransport
+   (QUIC datagrams) on the provider side.
+3. Tick model: fixed tick with a declared rate, or per-system rates.

docs/cultmesh-ts-content-map.md

@@ -34,7 +34,7 @@ ran under the session scratchpad (`imagination/`), not in the repo.
 | F13 | Cross-process precedent for C# against a Node provider exists. `packages/cultnet-ts/test/interop/cultnet-interop.test.ts:536-560` spawns the TS QUIC provider, then runs `dotnet test --filter NativeConnectorReceivesFromExternalProvider` with the endpoint in `CULTMESH_NATIVE_EXTERNAL_ENDPOINT`. The C# test skips without the variable (`tests/GameCult.Mesh.Quic.Native.Tests`, line 21). | source |
 | F14 | `cultnet-ts` is CommonJS. Its `./wire`, `./contracts` and `./authority` subpaths import only `@msgpack/msgpack`, `ajv` and `cultcache-ts/document`, so they are browser-safe. Its root `index` pulls `node:` modules (`peer`, `rudp`, `transport`, `security` and others). `cultmesh-browser` (ESM) already imports `cultnet-ts/wire`, `/contracts` and `/authority`. `cultmesh-ts` loads `koffi` lazily, inside a function (`realtime-quic-native.ts:139`), so a new subpath of it pays no native load. The root has `esbuild` ^0.28.1 as a devDependency. | source, grep |
 | F15 | TS packages build with `tsc` and test with `node --test dist-test/test/*.test.js` per workspace. `scripts/run-typescript-workspaces.mjs` runs them in order `cultcache-ts, cultnet-ts, cultmesh-ts, cultmesh-browser`, after `check-typescript-tests-wired.mjs`. No StrykerJS config exists in CultLib (`docs/mutation-testing.md:156-159`). | source |
-| F16 | **No CultLib TS package except `cultcache-ts` has a publish job.** `publish-packages.yml` triggers on `cultcache-ts-v*`, `cultcache-py-v*`, `cultnet-py-v*` and `cultmesh-py-v*` only. Tags `cultnet-ts-v0.1.1` and `cultmesh-ts-v0.1.1` exist, but no workflow consumes them. `npm view` returns 404 anonymously for `cultnet-ts`, `cultmesh-ts`, `cultmesh-browser` and even `@gamecult/cultcache-ts` (`@gamecult/cultcache-ts` may be private; unverified). The doctrine's rule of at most three tags per push stands (SKILL.md:674). | source; `npm view` |
+| F16 | **No CultLib TS package except `cultcache-ts` has a publish job.** `publish-packages.yml` triggered on `cultcache-ts-v*`, `cultcache-py-v*`, `cultnet-py-v*` and `cultmesh-py-v*` when this was written; it now triggers on the three `-py-v*` patterns only, because npm publishing is deliberately off until ruled on (a tag run uses the workflow at the tagged commit, so `cultcache-ts-v0.15.0` on `7d292085`, before that change, still ran the old one). Tags `cultnet-ts-v0.1.1` and `cultmesh-ts-v0.1.1` exist, but no workflow consumes them. `npm view` returned 404 anonymously on 2026-11-08 for `cultnet-ts`, `cultmesh-ts`, `cultmesh-browser` and even `@gamecult/cultcache-ts` (`@gamecult/cultcache-ts` may be private; unverified). The doctrine's rule of at most three tags per push stands (SKILL.md:674). | source; `npm view` |
 | F17 | StreamPixels consumes CultLib as the git submodule `vendor/CultLib` (gitlink `30ee8b97`) with `file:` deps and `pnpm.overrides`. Its CI and Idunn recipes build the vendored workspaces (`npm ci --ignore-scripts`, then build `cultcache-ts`, `cultnet-ts` and `cultmesh-ts`). `apps/web` depends only on `cultnet-ts` today, not on `cultmesh-browser`. | StreamPixels `.gitmodules`, `apps/*/package.json`, CI workflow lines 62-95 |
 | F18 | The Rust reader sets two guards that the TS reader should match. A caller cap `max_bytes` is checked before any request. And a zero-size chunk is refused unless it is the only one, because a manifest of zero-size chunks would be a request flood. | source `cultnet-rs/src/content.rs:364-385` |
 | F19 | `BuildChunkUri` on more endpoint shapes, as `AbsoluteUri` (what `HttpClient` sends). `https://h` and `https://h/` both give `https://h/?chunkHash=…&recordKey=k`. `https://h:443/x` drops the default port. `https://H.Example/X/` lowercases the host and keeps the path's case. `https://h/x#frag` keeps the fragment after the query. `https://h/x?a=%20b+c` keeps the existing query verbatim and joins with `&`. **`https://h/x?` (an empty query) gives `https://h/x?&chunkHash=…`**, because `UriBuilder.Query` is `?`, which is not blank. `https://[::1]:8443/c` keeps the bracketed host. `Uri.EscapeDataString("!'()*~-._ +é𐐀")` is `%21%27%28%29%2A~-._%20%2B%C3%A9%F0%90%90%80`: unlike JS `encodeURIComponent`, it escapes `!'()*`. | probe: `dotnet fsi` on .NET 10, the three lines of `BuildChunkUri` (`CultMeshHttpsContentTransport.cs:114-122`) copied verbatim |
@@ -276,11 +276,10 @@ remains:
      history (Keep a Changelog headings).
    - A Soul pass over the release diff, then four tags: `cultcache-ts-v…`,
      `cultnet-ts-v0.3.0`, `cultmesh-ts-v0.2.0` and `cultmesh-browser-v0.4.0`.
-     These go in **two pushes** (at most three tags per push, SKILL.md):
-     `cultcache-ts` first, because its tag triggers `publish-packages.yml`
-     (F16), and the three plane tags second. Whether the `cultcache-ts` tag's
-     npm publish job still runs, and to where, is checked before that push;
-     follow-up `npm-publish-ts-packages` owns the rest.
+     These go in **two pushes** (at most three tags per push, SKILL.md). No
+     `-ts-v*` tag triggers `publish-packages.yml` on main (F16), so these tags
+     publish nothing;
+     follow-up `npm-publish-ts-packages` owns npm publishing.
    - The consumer's pickup (StreamPixels bumping `vendor/CultLib` to the
      tagged commit) is StreamPixels' B-cuts, not this campaign.
    - Size: about 60 lines of version and CHANGELOG text; a short Hands pass.

docs/cultnet-rudp-ack-cut.md

@@ -441,8 +441,8 @@ consumer that waits wants delivered, which is now just Acknowledged.
 | `cultmesh-rs/src/lib.rs:781-838` `request_raw_snapshot_from_rudp_catalog` (Idunn `src/drivers.rs:5527` uses it) | a hand-rolled loop until `Acknowledged`, then the response | Cut 4: `wait_acknowledged` |
 | `cultmesh-rs/src/lib.rs:870-900` `publish_cultnet_message_to_rudp_catalog` (Odin `odin-daemon`) | a hand-rolled loop until `Acknowledged`, then disconnect. The doc at `:869` claims "application admission" | Cut 4: `wait_acknowledged`; the doc says delivered to the document server's sink (`rudp_document_server.rs:343-372`) |
 | `cultmesh-rs/src/lib.rs:918-938` `publish_cultnet_messages_to_rudp_catalog` (Ghostlight `mesh.rs:323`) | `flush_reliable`, then drop. **Several ordered frames, then close** | None; flush now means it |
-| `cultmesh-ts/src/index.ts:6070-6098` `publishRudpDocumentOnce` (Heimdall, StreamPixels, Stonks, weksa, Bifrost, VoidBot, Hermodr) | `peer.flush` (`cultnet-ts/src/peer.ts:109-110`), then close | None. Cut 5 moves its connect-and-wait helper (`index.ts:6603-6650`) into cultnet-ts |
-| `cultnet-ts/src/idunn-odin-presence-publisher.ts:89-215` `publishDocument`, behind `createIdunnRuntimePresencePublisher`. **StreamPixels' service runs this**: `apps/service/scripts/idunn-entry.mjs` runs `deployment/idunn/runtime-presence.mjs`, which calls `createIdunnRuntimePresencePublisher` (`:46`) from its vendored CultLib `542ddd3` (StreamPixels `a49f7d8`; pass 2's `30ee8b9` is stale), where it lives under its older name `cultnet-ts/src/idunn-runtime-authority.ts:206` | a hand-rolled session loop (`:186-208`) until `outstandingReliablePacketCount === 0`. It does resend (`:205`). It drops `readyToSend` (`:198`), so promoted queued packets wait for the resend timer. It pins `initialSequence: 1` (`:103`) and never sends a Disconnect, so Odin's hub keeps each publish's peer until it times out (each publish binds a new port, so each is a new peer) | Cut 5: the socket transport, `connectAndWait`, `send("schema")`, `flush`, `close` (which sends the Disconnect, `rudp.ts:956-969`) |
+| `cultmesh-ts/src/index.ts:6211-6303` `publishRudpDocumentOnce` (Heimdall, StreamPixels, Stonks, weksa, Bifrost, VoidBot, Hermodr) | `peer.flush` (`cultnet-ts/src/peer.ts:109-110`), then close | None. Cut 5 moves its connect-and-wait helper (`index.ts:6603-6650`) into cultnet-ts |
+| `cultnet-ts/src/idunn-odin-presence-publisher.ts:97-136` `sendPresenceDocument` (formerly `publishDocument`), behind `createIdunnRuntimePresencePublisher`. **StreamPixels' service runs this**: `apps/service/scripts/idunn-entry.mjs` runs `deployment/idunn/runtime-presence.mjs`, which calls `createIdunnRuntimePresencePublisher` (`:46`) from its vendored CultLib `542ddd3` (StreamPixels `a49f7d8`; pass 2's `30ee8b9` is stale), where it lives under its older name `cultnet-ts/src/idunn-runtime-authority.ts:206` | a hand-rolled session loop (`:186-208`) until `outstandingReliablePacketCount === 0`. It does resend (`:205`). It drops `readyToSend` (`:198`), so promoted queued packets wait for the resend timer. It pins `initialSequence: 1` (`:103`) and never sends a Disconnect, so Odin's hub keeps each publish's peer until it times out (each publish binds a new port, so each is a new peer) | Cut 5: the socket transport, `connectAndWait`, `send("schema")`, `flush`, `close` (which sends the Disconnect, `rudp.ts:956-969`) |
 | `cultnet-ts/src/signed-daemon-health.ts:104-162` `publishSignedDaemonHealth` (Hermodr, Odin `idunn-rudp.cjs`) | a hand-rolled loop: sends the packets `sendMany` admitted, waits up to 500 ms for the **first** Ack packet of any content (`:146-153`), swallows the timeout, closes. Resends run inside that wait (`:303`) but promoted queued packets are never sent | Cut 5, as above. Today a write not acked within 500 ms, or any payload over 32 packets, is reported published |
 | `cultnet-ts/src/operation-service.ts` | the operation response | none (the response is the proof) |
 | C# `FlushReliable` callers: Gjallar `Program.cs:3055-3080` (two ordered frames, flush, dispose) | flush | None |

docs/document-variants-cut.md

@@ -91,6 +91,121 @@ Probes run 2026-10-12 from `F:\Projects\CultLib-c2afix` with git only (no builds
   `unstored-same-tick-unpinned`) caught at head. `git grep RawBytes de401056 -- src tests`: no
   match. Those findings were never closed in the mind.
 
+### Body at 2026-10-15: element ids and the MessagePack walk (Modeling, from the Imagination and Soul passes)
+
+Probes ran on Yggdrasil (`mcr.microsoft.com/dotnet/sdk:10.0`, MessagePack 3.1.7 in every csproj) as probe
+tests that were never committed: at `6afa8ed9` for I1 to I4, at `494ad9ab` for r4 and r5, at `6e70626b` for r6.
+Logs and sources are under `F:\Projects\eureka-handoff-aux-2026-10-15\scratchpad-self-2026-10-14b-eureka\`
+(`imag\`, `imag-r4\`, `imag-r5\`; Soul's `soul-c2a-id-holes-s5\` is in that session's scratchpad). The typed
+record of each fact is in the mind: `variants:cut_spec:cut-c2a-element-id-holes.r5` and `.r6` (`first`),
+verdicts `cut-c2a-element-id-holes.s5` and `.s6`, spec `cut-c2a-ids-header.r1` (`first`). This section keeps
+what was run and what it showed.
+
+**What an id is on disk and in memory.**
+- An id is an ordinary keyed string in the payload. A list element whose `[CultElementId]` member holds
+  `a1b2c3d4e5f6` and one whose plain `Tag` holds the same value encode to identical bytes
+  (`92A1649192AC61316232633364346535663607`; `c2a-ids-header` r1 probe, base `2774a7fe`). No reader can tell
+  from a record's bytes that it holds ids; only the store header says so.
+- `StubArm`, a union arm that is not an object type, is never minted (`imag\imag1.log`, I1): for a document of
+  `StubArm` and `Unit8`, `Plan` counts 1, `StubArm.Id` stays `''`, `Unit8.Id` is minted, `Inspect` reports 0
+  problems.
+- Resolver over-mark (I2): a consumer `[assembly: CultCacheFormatterResolver]` claims a keyed arm with a
+  formatter that writes only `N`. The cache mints an id in memory, `Holds` is true and the header is stamped
+  `v3`, but the payload (`92A263319192009104`) carries no id, and a reopen mints a different one (`8f5e929888ca`
+  in memory, `a1ea2b683d98` after reload). The header claims ids the disk lacks.
+- `[MessagePackFormatter]` on an element type is honoured (I3): the attribute formatter wrote
+  `92A26131919104`, no id, and `Inspect` reported 0 problems at that base. Registration refuses it from r5 on
+  (`declares [MessagePackFormatter]`).
+- Python store (I4): `py-store/leaf-record.cc` (header `v1`, ids `000000000021/22`) loads in C# with
+  `HoldsIds = true`, `IdsInMemoryOnly = false`. A C# write that adds an unrelated record copies it forward,
+  the header stays `v1`, and the ids survive reload. cultcache-py, -ts and -rs have no declaration of which
+  member is an id, so they keep a `v3` they found and never decide one.
+- Header narrowing (`c2a-ids-header` r1): per-record `StoredHoldsIds`, set from the type that decoded a
+  record, is falsified by the identical-bytes probe above. The durable header owns "these stored bytes hold
+  ids" at store granularity. A write that copies any record forward keeps a marked header; only a write that
+  encodes every record decides by content. `StoredHoldsIds` and `KnownIdFree` are deleted.
+- Object list versus value list (r4, `imag-r4\probe1.log`, `probe2.log`): ids sit on object-list elements only
+  (ruling `q7-object-list-elements-only`). `Dictionary`, `ConcurrentDictionary`, `SortedDictionary`,
+  `IReadOnlyDictionary`, and `ILookup` of keyed arms round-trip with the id at
+  the element's own slot (e.g. `ConcDict` `81A16B92AC30313233343536373839616200`: key, then `[id, 0]`). A list
+  or map of scalars has no element to carry one and never enters the id path.
+
+**How MessagePack decides what it writes** (r5 `imag-r5\probe1.log`, `probe3.log`; Soul s5 `job2.log`).
+- Member discovery, `MessagePack.Internal.ObjectSerializationInfo.CreateOrNull(Type, bool forceStringKey,
+  bool contractless, bool allowPrivate)`, is internal, and so is `StandardResolver.Resolvers`. The public
+  surface allows one test: `StandardResolver`'s formatter for `T` is reference-equal to the formatter one
+  public singleton hands out for `T`, each caching one instance per type. `DynamicObjectResolver.Instance`
+  matches keyed classes and structs, `DynamicUnionResolver.Instance` `[Union]` types,
+  `DynamicGenericResolver.Instance` List, arrays, maps, KeyValuePair, tuples, Lazy, Memory, ArraySegment and
+  Nullable, and `ImmutableCollectionResolver.Instance` (namespace `MessagePack.ImmutableCollection`)
+  `ImmutableArray` and `ImmutableList`. Asking `DynamicObjectResolver` for a collection type throws
+  `TypeInitializationException`, so a family probe swallows exceptions.
+- Kind facts (`probe3`): a `[MessagePackObject]` class implementing only `IEnumerable<T>` or
+  `IReadOnlyList<T>` (`KBag`, `KNode`, `KRo`) is written by key (object resolver). One that is also
+  `ICollection<T>`, a `List<T>` subclass or a `Dictionary` subclass (`KC2`, `KColl`, `KList2<T>`, `KDict`) is
+  written as a collection (generic resolver) and its `[Key]` members are dropped.
+- Member facts (`probe3`; `ap` is `AllowPrivate`, `R` written, `W` read back). A member is written when it
+  has an integer `[Key]`, no `[IgnoreMember]`, and is a public field or a property with a public getter. It is
+  read back when it is a public non-readonly field, a property with a public setter (`init` counts), or a
+  `[SerializationConstructor]` parameter. At `ap=False`: `PG` (private getter) `R=False W=True`, `PS`
+  (private setter) `R=True W=False`, `GetOnly` `R=True W=False`, `InitOnly` both. `IdPriv`
+  (`Id { get; private set; }`) is written and not read back (wire `91AC62...`, back `<null>`), and `IdCtor` is
+  `W=False`. At `ap=True` every one of these, `priv` included, is `R=True W=True`, except `GetOnly`
+  (`W=False`).
+- AllowPrivate attribute form (Soul s5 `SoulS5Probe.C`, `ApTrueArm`): on a type declared
+  `[MessagePackObject(AllowPrivate = true)]`, `StandardResolver` writes private `[Key]` members and a
+  private-setter id round-trips. The oracle test calls `CreateOrNull(type, false, false, false)` and reports
+  none of them, so the walk's member set misses that form.
+- Collection written as object (r6 `probe2.log`): a `[DataContract]` class implementing only `IEnumerable<T>`
+  over an id-carrying arm (`DcSeq`) is a collection in the walk, yet `StandardResolver`'s formatter is
+  `DynamicObjectResolver`'s (wire `91 91 91 92 AC..`, written as an object). A `[DataContract]` `List<T>`
+  subclass (`DcColl`) is written by the generic resolver, and the object resolver hands out a different
+  instance for it. For `DcBad` (two members on one `Order`) `StandardResolver` uses the generic resolver, and
+  Soul s5 measured both `DcColl` and `DcBad` passing the door.
+- Geometry (r6 `probe2.log`, `probe3.log`): Geometry has a direct MessagePack 3.1.7 `PackageReference`, so the
+  source generator runs, and its assembly carries `[GeneratedAssemblyMessagePackResolverAttribute(
+  typeof(GeneratedMessagePackResolver), 3, 1)]`. For `CultGeometryDomainNode`, `DomainDocument` and
+  `FeatureClaim`, `StandardResolver` returns `GeneratedMessagePackResolver`'s formatter and every public
+  singleton returns a different instance or null. For `CultGeometryDomainNode[]` and `FeatureClaim[]` it is
+  the generated resolver's `ArrayFormatter`, not `DynamicGenericResolver`'s. No Geometry id-path type matches
+  a family singleton. Caching.Tests has no generator (analyzers do not flow through a `ProjectReference`), so
+  its keyed types match `DynamicObjectResolver`.
+- Generated assemblies (Soul s5, fresh generator-enabled assembly `SoulGen`, `job2.log` GEN rows): a keyed
+  `List` or `Dictionary` subclass (`GKColl`, `GKDict`) is written by key, wire `["c",[7]]`, with its elements
+  dropped by MessagePack; the walk reads it by key too (Plan 0). A generated-assembly `[DataContract]`
+  enumerable (`GDcSeq`) is still written by `DynamicObjectResolver`, because the generator emits no
+  DataContract formatters.
+- Null standard (Soul s6 finding `null-standard-untyped`): for a non-generic interface or abstract class that
+  enumerates arms, `StandardResolver` returns null instead of throwing, and the door neither refuses nor
+  types it.
+- Wire pin (Soul s5, s6 `SoulS5Pin`): a deterministic document with 12 minted ids, encoded by the codec and
+  decoded independently with `MessagePackSerializer.ConvertToJson`, carries every id. The ids are
+  byte-identical at `494ad9ab` and `57fdf70c`, `0f8964b58a08` and `7eb4fb13d530` among them.
+- Not measured: Unity/IL2CPP, where the package bundles its own `MessagePack.dll` (version not read) and the
+  dynamic resolvers cannot emit, and MessagePack versions other than 3.1.7.
+
+**Whole-list holders at `57fdf70c`** (Imagination r2 for `c2a-id-closed-world`, 2026-10-16; probe tests in a
+scratch commit `dc629459` that was never pushed, Yggdrasil `sdk:10.0`; logs `job1.log` and `job2.log` in the
+Imagination scratchpad `imagination-c2a-closed-world-r2`).
+- Shapes the walk does not own already behave as whole values. A keyed document holding
+  `ImmutableArray<PElem>`, `(List<PElem>, int)`, `KeyValuePair<string, List<PElem>>`, a non-enumerable
+  `[DataContract]` holder, or a string-keyed holder (`[Key("items")]`) gives `Inspect` problems 0, an empty
+  IdPath, `CanHoldIds` false, `Plan` 0 (random and deterministic), and `Holds` false with ids set.
+- The marker and the copy check do not count them. Committed with ids `aaaaaaaaaaaa`/`bbbbbbbbbbbb`, the store
+  header stays `cultcache.store.v1`. A fresh cache that writes another record over that file (the copy-forward
+  check) keeps `v1`. Reload returns the ids exactly as written, and unset ids stay null after write and reload.
+- Variants replace them whole, and that is the C2a resolver's behaviour for every list. A variant `Set` of the
+  `ImmutableArray` slot resolved to `[9:eeeeeeeeeeee]` with the base untouched, header `v2`, `HoldsIds` false.
+  A path step `[1:aaaaaaaaaaaa]` is refused: "this runtime resolves top-level Set overrides only". No C2a gap.
+  The gap belongs to C2b, in the cut sequence below.
+- AllowPrivate is read from the most derived `[MessagePackObject]`. `ApDerived` (AllowPrivate over a base
+  without it) is written `[[],[],4,[]]`: base-chain privates and a private-getter property, with
+  `ObjectSerializationInfo` at `allowPrivate: true` = `[baseStash, own, N, Pg]`. `NoApDerived` (plain over an
+  AllowPrivate base) is written `[nil, 5]`. The walk read only `[N]` for both.
+- A `[DataContract]` `List<T>` subclass is written by `NonGenericListFormatter`, and its record does not read
+  back ("System.Object[] is not of type PElem"), whatever the walk does. That is a MessagePack limit, not an
+  id fact.
+
 ## 2. Model page (step 0b)
 
 | Kind | Named by | Over time | Decided by |
@@ -99,16 +214,16 @@ Probes run 2026-10-12 from `F:\Projects\CultLib-c2afix` with git only (no builds
 | Base reference | the base's key, in the record's variant slot | changed only by an explicit rebase; a base cannot be deleted while it has variants, unless the same batch rebases or removes them | author; the cache refuses a cycle, a missing base, a different concrete type, a global type |
 | Override entry | `(op, path, id, value)`; op is Set, Insert or Remove | added by editing; removed by clearing; survives base edits while its path resolves | author; the cache refuses entries a base edit strands (Q2); an entry whose member left the type soft-drifts with a warning (Q4 c) |
 | Member path | a sequence of `(slot, elementId)` steps; `slot` is the MessagePack `[Key]`; `elementId` is `""` unless the step enters an object-list element | a type change can invalidate it | the type's owner (slot authority); ids by the element's creator |
-| Element id | a `[CultElementId]` string member on an object-list element type; `""` means unset | minted by the cache on write when unset; copied unchanged into variants; a moved element is a new element | cache mints it; it is never retargeted |
+| Element id | a `[CultElementId]` string member on the element type of an object list in a shape the walk owns (arrays, `IEnumerable<T>`, `IDictionary`/`IReadOnlyDictionary` values, `[MessagePackObject]`/`[Union]` types with integer keys), one MessagePack writes and reads back (integer `[Key]`, no `[IgnoreMember]`; public, or any visibility under the most derived `AllowPrivate`); `""` means unset. **Exception (q3 amended 2026-10-16):** a shape the walk does not own is one whole value: `ImmutableArray`, `ArraySegment`, `Memory`, `KeyValuePair`, tuples, `Lazy`, unkeyed or `[DataContract]` classes, string-keyed types, a type or member with `[MessagePackFormatter]`, and a non-public member without `AllowPrivate`. Its elements carry no ids: a `[CultElementId]` inside is a plain string | minted by the cache on write when unset; copied unchanged into variants; a moved element is a new element. Inside a whole value: never minted, never checked, never counted for `v3` | cache mints it; it is never retargeted. `CultElementIds.Classify` alone decides owned versus whole |
 | Resolved view | `CultStoredDocument.Document` for a variant key | recomputed inside the hold that admits the variant, or any base on its chain | the cache only; never persisted, never written back (Q1) |
 | Index and name entries | as today, from the resolved view | a dependent's entries are dropped and re-added in the same `Apply` as its base change | the cache; a variant must override the `[CultName]` member (rule R6) |
 | Watches | as today; each re-resolved dependent emits `Updated` with its own `Sequence` | published in the same hold as the base change | the cache |
 | Compare-exchange | `(schemaId, storedAt)` of the stored delta (ruling 2) | a base change does not stamp its variants | the cache; the resolved view is not an identity |
-| Persisted format version | store header `formatVersion` | `cultcache.store.v2` when the store holds at least one variant; `v1` otherwise (Q5) | the writing store, from content |
+| Persisted format version | store header `formatVersion` | `cultcache.store.v2` when the store holds at least one variant; `v1` otherwise (Q5); a marked `v3` (`v5` directory) stays while a write copies any record forward, and only a write that encodes every record drops it by content | the writing store, from content; the durable header alone says the bytes hold element ids |
 | Single-file store file | the path; one MessagePack array `[header, catalog, records]` | replaced whole and atomically; refused when unreadable; see "Store authorities" | each runtime's one reader decides what is a store; the writer derives the header from it |
 | Store lock and staging files | `<file>.lock`; a unique temp beside the store | the lock is taken by C# and Rust writers (CultMesh included, through `ReplaceDurable`); staging is removed on a failed write | the store, never CultMesh or a consumer |
 | Variant slot on the wire (CultNet) | **empty cell**: no CultNet message carries a delta today | C5 | ruling 4 decides deltas; the message shape is C5's design |
-| Dictionary entries, scalar lists, arrays | **empty cell**: no stable identity exists | whole-member Set only (Q7) | Q7 |
+| Dictionary entries, scalar lists, arrays, whole-list holders | **empty cell**: no stable identity exists | whole-member Set only (Q7; whole-list holders by q3 amended) | Q7, q3 amended |
 | Template (non-item) bases | **empty cell**: parked by ruling 6 | none | not in these cuts |
 
 ## 3. Where the Body contradicts the target
@@ -220,20 +335,21 @@ Dictionary entries, scalar lists and arrays are replaced whole.
 - **Recommend yes.** Aetheria's cases (`Hardpoints` whole; `Behaviors[id]...Max`) fit. Keyed
   dictionary addressing can be added later without a format change. Affects C2.
 
-## Cut sequence (2026-10-12)
+## Cut sequence (2026-10-15)
 
-Mapped now (specs in the mind): `c2a-declared-apply` r2, the C# commit-time fix batch on
-`hands/variants-c2a` (the stash, finished, with tests and contract text), and its sibling
-`main-into-c2a` r2, main merged into C2a on `hands/variants-c2a-main` in its own worktree. Later
-cuts, one line each, mapped only when Self is about to dispatch them:
+Landed since 2026-10-12: `c2a-declared-apply` (r3, Soul s5) and `main-into-c2a` (r2, Soul s2); the
+reconcile step is done, `hands/variants-c2a` is at the reconciled head `6afa8ed9`. Element ids part 1,
+`c2a-element-id-holes` (r6), is held by Soul s5/s6 on `hands/variants-c2a-element-id-holes`. Mapped
+now: part 2, `c2a-id-closed-world` r2 (2026-10-16, under the amended q3), not blocked. Its open fork
+`variants:question:c2a-whole-list-opt-in` holds under every option. Later cuts, one line each, mapped
+only when Self is about to dispatch them:
 
-1. **reconcile**: merge `hands/variants-c2a` into `hands/variants-c2a-main` after both Soul passes
-   hold; Self moves `hands/variants-c2a` there. Waits on both mapped cuts.
+1. **reconcile**: done at `6afa8ed9`.
 2. **parity-ts**: TypeScript write set, one record per key, undeclared records carried and refused,
-   unheld removals judged at commit. Waits on reconcile.
+   unheld removals judged at commit. Waits on element ids parts 1 and 2 merged into C2a.
 3. **parity-rs**: Rust `push_all` and `put_prepared_batch` apply a write set, ownership by
-   declaration, the same commit-time checks. Waits on reconcile; can run beside parity-ts.
-4. **parity-py**: Python write-set apply. Waits on reconcile and on `cultlib-gaps` cut
+   declaration, the same commit-time checks. Waits as parity-ts; can run beside it.
+4. **parity-py**: Python write-set apply. Waits as parity-ts, and on `cultlib-gaps` cut
    `py-msgpack-default` landing on main (then a main merge into C2a first).
 5. **write-set-vectors**: one cross-runtime manifest, read and acted on by all four runtimes;
    carries follow-ups `c0-bad-canonical-in-manifest`, `legacy-vectors-all-runtimes`,
@@ -242,6 +358,11 @@ cuts, one line each, mapped only when Self is about to dispatch them:
    with an empty diff against the verified head; no tag. Waits on write-set-vectors, Soul holding,
    and `asura:cut_spec:cut-semver-measured` landed. Asura Cut 3 bases on its merge commit.
 
+Element-id part 2: `c2a-id-closed-world` r2 decides deferred findings `s5.member-set-misses-allowprivate`, `s5.enumerating-rule-unpinned`, `s6.null-standard-untyped`, `s6.two-recognisers-one-rule`, `s4.unrecognised-holders-fail-open` and follow-up `c2a-datacontract-holder-unwalked` (see its `first`).
+
+- **marker-for-whole-lists** (only if `c2a-whole-list-opt-in` is ruled `marker-when-ids-declared` or `marker-for-any-keyed-object`): a CarriesElements predicate, a refusal unless the member is marked, and a public attribute. It is additive after part 2.
+- **C2b constraint** (owed to `variants:follow_up:remaining-variant-cuts`): nested path resolution must refuse a step `[slot:elementId]` that enters a whole value, naming the holder. A whole value is any shape `CultElementIds.Classify` calls Leaf, so C2b asks Classify and keeps no recogniser of its own. Today's C2a resolver refuses every non-top-level step, so no store can hold such an override yet.
+
 Rationale. The 2026-10-02 order (parity, vectors, then merge main) was right when main was close.
 Main has since moved 453 commits and rebuilt exactly what the parity cuts change: cultcache-ts
 payload ownership, cultmesh-ts, cultcache-rs. Parity mapped before the merge would be mapped
@@ -1484,7 +1605,7 @@ The one door per runtime, and who walks through it:
 - **Inputs.** The bytes at the path. **Outputs.** The decoded store with header and catalog; or a typed refusal (`CultStoreUnreadableException` in C#; `CultCacheStoreUnreadable{path, kind}` in Rust, kind `Undecodable` or `UnsupportedFormat`; `StoreUnreadableError` in TS and Python). A refusal names a header only as `cultcache.store.v<digits>`.
 - **Derived state.** The write header is never decided by the writer: it is the reader's verdict (header read, whole-store flag, whether ids or variants are held). A rewrite of a file that cannot be read cannot happen, because the reader throws first.
 - **Forbidden writers.** A second header classifier. Deleted: Rust `leading_header`, `read_array_header`, `read_string`; cultnet-ts's own decode of the store header; the TS async `readStore`; Rust `StoreUnreadableError` (negative grep `StoreUnreadableError` in `packages/cultcache-rs`: no match); Python `_decode_v1_snapshot`.
-- **Shared paths.** cultnet-ts reaches the header decision only through `readSingleFileStore` (AUTH:4, :321) and checks only record count, schema id and type. cultnet-ts therefore declares cultcache-ts `^0.15.0`, the first release that exports it.
+- **Shared paths.** cultnet-ts reaches the header decision only through `readSingleFileStore` (AUTH:4, :321) and checks only record count, schema id and type. cultnet-ts therefore needs a cultcache-ts release that exports it, which is the release that ships with this change; the manifests move to that version then (c0-ships-with-c2a), not before.
 - **Cut line.** `merge-r1` h3 (Rust) and h4 (TS, cultnet-ts); spec `cut-merge-r1.r3` authority map.
 - **Pinned by.** `tests/vectors/document-variants-c2a/readability/manifest.txt`, walked by `StoreReadabilityTests.OpenReadsExactlyTheFilesTheVectorsSayItReads` (C#), `CultMeshSingleFileReadabilityTests.AWriteReplacesAFileExactlyWhenItReads` (Mesh), `a_file_is_replaced_exactly_when_it_reads` (RS:5132), "SingleFileMessagePackBackingStore replaces a file exactly when it reads" (TS test :2321) and `test_single_file_replaces_a_file_exactly_when_it_reads` (Python). AUTH cases: `packages/cultnet-ts/test/idunn-runtime-authority.test.ts`. Declared divergences in the manifest: `legacy-envelopes.bin` (C# refuses; the others read and replace it) and `variant-slot-v3.bin` (C# reads; the others refuse).
 - **Known gaps.** `variants:follow_up:c0-bad-canonical-in-manifest` (`current-catalog-bad-canonical.msgpack` is not in the manifest; TS reads it, Rust refuses). `variants:follow_up:legacy-vectors-all-runtimes` (the three `legacy-catalog-*` c0 vectors have a verdict only in C# tests; all four runtimes refuse them, probed). `variants:follow_up:range-check-in-ci` (`npm run test:pack:ts` builds every admitted tag and checks exports, but `.github/workflows/publish-packages.yml` does not run it).

docs/document-variants-id-sweep.md

@@ -0,0 +1,272 @@
+# Element-id sweep list (C2a)
+
+Data for the per-consumer sweep in docs/document-variants-cut.md, C2. Every object type below sits in a list (`List<T>`, `T[]`, `IEnumerable<T>`, and the like) reachable from a registered document type, and needs one string member with `[Key(n)]` and `[CultElementId]` before that consumer can take a CultLib that requires ids. A union base takes the member on the base; its subclasses inherit it, so put the slot above the subclasses' highest key.
+
+Method: a static scan of `F:\Projects\<consumer>` C# files for types marked `[CultDocument(`, walked through keyed members, base classes, dictionary values and `[Union]` subtypes. Read-only; no consumer was edited. Worktree copies (`Aetheria-catalog`, `CultLib-*`, and so on) are excluded. Struct elements are values and need no id. Non-C# consumers carry the id as an ordinary member and are not listed. The scan is text-based: a document registered without a literal `[CultDocument(` attribute, or a type whose members lack an integer `[Key]`, is missed, so the sweep pass should confirm each repo by registering its types once.
+
+Lines: `Type  file:line  (via Owner.Member)`, paths relative to the consumer root.
+
+
+## Aetheria (13 element types)
+
+- BehaviorData  Assets/Scripts/ServerShared/Behaviors/Behaviors.cs:190  (via ConsumableItemData.Behaviors)
+- EntityPack  Assets/Scripts/ServerShared/EntitySerializer.cs:171  (via ZonePack.Entities)
+- ProductRole  Assets/Scripts/ServerShared/FactionProduct.cs:38  (via FactionProductData.Roles)
+- InputLayoutRow  Assets/Scripts/ServerShared/InputLayout.cs:32  (via InputLayout.Rows)
+- InputLayoutColumn  Assets/Scripts/ServerShared/InputLayout.cs:52  (via InputLayoutKeyRow.Columns)
+- ItemRole  Assets/Scripts/ServerShared/ItemData.cs:325  (via CraftedItemData.Roles)
+- AudioStat  Assets/Scripts/ServerShared/ItemData.cs:441  (via EquippableItemData.AudioStats)
+- HardpointData  Assets/Scripts/ServerShared/ItemData.cs:553  (via HullData.Hardpoints)
+- StatTerm  Assets/Scripts/ServerShared/ItemData.cs:630  (via PerformanceStat.Terms)
+- LoadoutSlot  Assets/Scripts/ServerShared/Loadout.cs:23  (via Loadout.Slots)
+- RoleFill  Assets/Scripts/ServerShared/Provenance.cs:84  (via Lot.Roles)
+- SavedActionBarBinding  Assets/Scripts/ServerShared/SavedGame.cs:168  (via SavedGame.ActionBarBindings)
+- Asteroid  Assets/Scripts/ServerShared/ZoneData.cs:133  (via AsteroidBeltData.Asteroids)
+
+## AetheriaEve (115 element types)
+
+- AetheriaCorporationAllegiance  Aetheria.State/Documents/AetheriaCorporation.cs:67  (via AetheriaCorporation.Allegiances)
+- AetheriaShapeCell  Aetheria.State/Documents/AetheriaItemDefinition.cs:178  (via AetheriaItemDefinition.ShapeCells)
+- AetheriaItemHardpoint  Aetheria.State/Documents/AetheriaItemDefinition.cs:188  (via AetheriaItemDefinition.Hardpoints)
+- AetheriaCurveKey  Aetheria.State/Documents/AetheriaItemDefinition.cs:222  (via AetheriaItemDefinition.ThermalPerformanceCurveKeys)
+- AetheriaItemAudioStat  Aetheria.State/Documents/AetheriaItemDefinition.cs:238  (via AetheriaItemDefinition.AudioStats)
+- AetheriaBehaviorPayload  Aetheria.State/Documents/AetheriaItemDefinition.cs:267  (via AetheriaItemDefinition.BehaviorPayloads)
+- AetheriaBehaviorField  Aetheria.State/Documents/AetheriaItemDefinition.cs:286  (via AetheriaBehaviorPayload.Fields)
+- AetheriaBehaviorMapEntry  Aetheria.State/Documents/AetheriaItemDefinition.cs:296  (via AetheriaBehaviorValue.MapEntries)
+- AetheriaBehaviorValue  Aetheria.State/Documents/AetheriaItemDefinition.cs:306  (via AetheriaBehaviorValue.Children)
+- AetheriaLegacyCatalogFile  Aetheria.State/Documents/AetheriaLegacyCatalogQuarantine.cs:41  (via AetheriaLegacyCatalogQuarantine.NameFiles)
+- AetheriaMigrationCount  Aetheria.State/Documents/AetheriaMigrationLedger.cs:35  (via AetheriaMigrationLedger.Counts)
+- AetheriaLegacyCatalogEntrySummary  Aetheria.State/Documents/AetheriaMigrationLedger.cs:45  (via AetheriaMigrationLedger.LegacyCatalogEntries)
+- AetheriaStoryFileHash  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:42  (via AetheriaPlayerSettings.StoryFileHashes)
+- AetheriaInputBindingOverride  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:85  (via AetheriaPlayerInputSettings.BindingOverrides)
+- AetheriaEntityLoadout  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:119  (via AetheriaEntityLoadout.Children)
+- AetheriaLoadoutItemSlot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:186  (via AetheriaEntityLoadout.Equipment)
+- AetheriaCargoBayLoadout  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:199  (via AetheriaEntityLoadout.CargoContents)
+- AetheriaFactionZoneState  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:268  (via AetheriaRunState.HomeZones)
+- AetheriaAgentTaskState  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:275  (via AetheriaRunState.AgentTasks)
+- AetheriaDroppedPickupSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:346  (via AetheriaZoneState.DroppedPickups)
+- AetheriaOrbitSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:362  (via AetheriaZoneState.Orbits)
+- AetheriaBodySnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:384  (via AetheriaZoneState.Bodies)
+- AetheriaBodyResource  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:449  (via AetheriaBodySnapshot.Resources)
+- AetheriaAsteroidSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:459  (via AetheriaBodySnapshot.Asteroids)
+- AetheriaAsteroidMiningAccumulatorSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:484  (via AetheriaAsteroidSnapshot.MiningAccumulators)
+- AetheriaColor  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:545  (via AetheriaGasGiantVisualState.Colors)
+- AetheriaFogFieldEmitterSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:691  (via AetheriaEntitySnapshot.FogFieldEmitters)
+- AetheriaLoadoutGenerationSelection  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:723  (via AetheriaLoadoutGenerationReceipt.Selections)
+- AetheriaEntityContactSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:734  (via AetheriaEntitySnapshot.Contacts)
+- AetheriaEntityItemSlot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:751  (via AetheriaEntitySnapshot.Equipment)
+- AetheriaWeaponGroupSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:782  (via AetheriaEntitySnapshot.WeaponGroups)
+- AetheriaEntityStatGrid  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:789  (via AetheriaEntitySnapshot.StatGrids)
+- AetheriaActiveConsumableSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:805  (via AetheriaEntitySnapshot.ActiveConsumables)
+- AetheriaConsumableBehaviorStateSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:828  (via AetheriaActiveConsumableSnapshot.BehaviorStates)
+- AetheriaBehaviorProgressSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:844  (via AetheriaEntitySnapshot.BehaviorProgress)
+- AetheriaWeaponStateSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:863  (via AetheriaEntitySnapshot.WeaponStates)
+- AetheriaBehaviorStateSnapshot  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:924  (via AetheriaEntitySnapshot.BehaviorStates)
+- AetheriaFactionRelationshipState  Aetheria.State/Documents/AetheriaRuntimeStateDocuments.cs:1093  (via AetheriaRunState.FactionRelationships)
+- AetheriaItemRarityTier  Aetheria.State/Documents/AetheriaTradeValuePolicy.cs:29  (via AetheriaTradeValuePolicy.Tiers)
+- AetheriaRuntimeAgentTaskCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeAgentTasks.cs:35  (via AetheriaRuntimeRunCheckpointCommit.AgentTasks)
+- AetheriaRuntimeAssetManifestEntry  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeAssetDocuments.cs:102  (via AetheriaRuntimeAssetManifestDocument.Assets)
+- AetheriaRuntimeCurveKey  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeCatalogSnapshot.cs:446  (via AetheriaRuntimeShotReceiptCommit.GuidanceCurve)
+- AetheriaRuntimeCorporation  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeCatalogSnapshot.cs:620  (via AetheriaRuntimeCatalogSnapshot.Corporations)
+- AetheriaRuntimeNameFile  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeCatalogSnapshot.cs:669  (via AetheriaRuntimeCatalogSnapshot.NameFiles)
+- AetheriaRuntimeLoadoutTemplateSnapshot  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeCatalogSnapshot.cs:796  (via AetheriaRuntimeLoadoutTemplatesDocument.Templates)
+- AetheriaRuntimeDaemonCommandBoundaryEntry  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonDocuments.cs:462  (via AetheriaRuntimeDaemonCommandBoundaryDocument.Commands)
+- AetheriaRuntimeDaemonSoaIdentityDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonSoaDocuments.cs:143  (via AetheriaRuntimeDaemonSoaViewDocument.Identities)
+- AetheriaRuntimeDaemonRenderGroupDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonSoaDocuments.cs:156  (via AetheriaRuntimeDaemonSoaViewDocument.RenderGroups)
+- AetheriaRuntimeDaemonSoaBufferDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonSoaDocuments.cs:222  (via AetheriaRuntimeDaemonSoaViewDocument.Buffers)
+- AetheriaRuntimeDaemonSoaColumnDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonSoaDocuments.cs:253  (via AetheriaRuntimeDaemonSoaViewDocument.Columns)
+- AetheriaRuntimeDaemonSoaDirtyRangeDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeDaemonSoaDocuments.cs:284  (via AetheriaRuntimeDaemonSoaViewDocument.DirtyRanges)
+- AetheriaRuntimeEveSurfaceAdvertisement  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeEveSurfaceCatalog.cs:11  (via AetheriaRuntimeDaemonProviderAdvertisementDocument.EveSurfaces)
+- AetheriaRuntimeEvePluginRequirement  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeEveSurfaceCatalog.cs:58  (via AetheriaRuntimeEveSurfaceAdvertisement.RequiresPlugins)
+- AetheriaRuntimeZoneTargetRow  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:410  (via AetheriaRuntimeZoneContactsDocument.Targets)
+- AetheriaRuntimeZoneContactRow  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:441  (via AetheriaRuntimeZoneContactsDocument.Contacts)
+- AetheriaRuntimeStationStockItem  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:551  (via AetheriaRuntimeStationRefitEntityOption.CargoItems)
+- AetheriaRuntimeStationRefitEntityOption  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:585  (via AetheriaRuntimeStationRefitDocument.AvailableEntities)
+- AetheriaRuntimeStationDockingBayRow  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:620  (via AetheriaRuntimeStationRefitDocument.DockingBays)
+- AetheriaRuntimeStationLoadoutRestoreOption  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:655  (via AetheriaRuntimeStationRefitDocument.LoadoutRestoreOptions)
+- AetheriaRuntimeStationCargoTargetRow  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:674  (via AetheriaRuntimeStationRefitDocument.CargoTargets)
+- AetheriaRuntimeSectorMapZone  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:765  (via AetheriaRuntimeSectorMapDocument.Zones)
+- AetheriaRuntimeSectorMapLink  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:802  (via AetheriaRuntimeSectorMapDocument.Links)
+- AetheriaRuntimeZoneRenderAdjacentZone  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1197  (via AetheriaRuntimeZoneRenderDocument.AdjacentZones)
+- AetheriaRuntimeZoneRenderWormholeExit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1210  (via AetheriaRuntimeZoneRenderDocument.WormholeExits)
+- AetheriaRuntimeZoneRenderBodyPose  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1229  (via AetheriaRuntimeZoneRenderDocument.BodyPoses)
+- AetheriaRuntimeZoneRenderAsteroidBeltPose  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1260  (via AetheriaRuntimeZoneRenderDocument.AsteroidBeltPoses)
+- AetheriaRuntimeZoneRenderAsteroidInstancePose  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1286  (via AetheriaRuntimeZoneRenderAsteroidBeltPose.InstancePoses)
+- AetheriaRuntimeViewportObject  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1382  (via AetheriaRuntimeGameViewportDocument.Objects)
+- AetheriaRuntimeInventoryItem  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1458  (via AetheriaRuntimeViewportObject.Inventory)
+- AetheriaRuntimeGravityInfluence  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1493  (via AetheriaRuntimeGameViewportDocument.GravityInfluences)
+- AetheriaRuntimeBodyView  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeGameViewportDocuments.cs:1530  (via AetheriaRuntimeGameViewportDocument.Bodies)
+- AetheriaHangarShip  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeHangarDocuments.cs:119  (via AetheriaHangarState.Ships)
+- AetheriaHangarItemStack  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeHangarDocuments.cs:129  (via AetheriaHangarState.Inventory)
+- AetheriaHangarCurrency  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeHangarDocuments.cs:136  (via AetheriaHangarState.Currencies)
+- AetheriaDeploymentReceipt  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeHangarDocuments.cs:155  (via AetheriaHangarState.Deployments)
+- AetheriaProgressionVerseOption  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeProgressionSourceDocuments.cs:45  (via AetheriaProgressionSourceDocument.AvailableVerses)
+- AetheriaRuntimeStoryFileHashDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSettingsDocuments.cs:87  (via AetheriaRuntimePlayerSettingsDocument.StoryFileHashes)
+- AetheriaRuntimeInputBindingOverrideDocument  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSettingsDocuments.cs:108  (via AetheriaRuntimePlayerSettingsDocument.BindingOverrides)
+- AetheriaRuntimeEntityLoadoutCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:78  (via AetheriaRuntimeEntityLoadoutCommit.Children)
+- AetheriaRuntimeLoadoutItemSlotCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:143  (via AetheriaRuntimeEntitySnapshotCommit.Equipment)
+- AetheriaRuntimeCargoBayLoadoutCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:159  (via AetheriaRuntimeEntitySnapshotCommit.CargoContents)
+- AetheriaRuntimeGameEventCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:490  (via AetheriaRuntimeRunCheckpointCommit.GameEvents)
+- AetheriaRuntimeFactionZoneCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:509  (via AetheriaRuntimeRunCheckpointCommit.HomeZones)
+- AetheriaRuntimeShotReceiptCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:539  (via AetheriaRuntimeRunCheckpointCommit.ShotReceipts)
+- AetheriaRuntimePickupContactReceiptCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:591  (via AetheriaRuntimeRunCheckpointCommit.PickupContactReceipts)
+- AetheriaRuntimeDamageCellCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:603  (via AetheriaRuntimeShotReceiptCommit.DamageCells)
+- AetheriaRuntimeCorporationSurveyCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:614  (via AetheriaRuntimeRunCheckpointCommit.CorporationSurveys)
+- AetheriaRuntimeFactionRelationshipCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:623  (via AetheriaRuntimeRunCheckpointCommit.FactionRelationships)
+- AetheriaRuntimeZoneSnapshotCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:636  (via AetheriaRuntimeRunCheckpointCommit.Zones)
+- AetheriaRuntimePhysicalPayloadCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:699  (via AetheriaRuntimeZoneSnapshotCommit.PhysicalPayloads)
+- AetheriaRuntimeDroppedPickupCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:771  (via AetheriaRuntimeZoneSnapshotCommit.DroppedPickups)
+- AetheriaRuntimeOrbitSnapshotCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:805  (via AetheriaRuntimeZoneSnapshotCommit.Orbits)
+- AetheriaRuntimeBodySnapshotCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:830  (via AetheriaRuntimeZoneSnapshotCommit.Bodies)
+- AetheriaRuntimeBodyResourceCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:901  (via AetheriaRuntimeBodySnapshotCommit.Resources)
+- AetheriaRuntimeAsteroidCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:911  (via AetheriaRuntimeBodySnapshotCommit.Asteroids)
+- AetheriaRuntimeAsteroidMiningAccumulatorCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:936  (via AetheriaRuntimeAsteroidCommit.MiningAccumulators)
+- AetheriaRuntimeColorCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1008  (via AetheriaRuntimeGasGiantVisualCommit.Colors)
+- AetheriaRuntimeEntitySnapshotCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1024  (via AetheriaRuntimeZoneSnapshotCommit.Entities)
+- AetheriaRuntimeFogFieldEmitterCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1198  (via AetheriaRuntimeEntitySnapshotCommit.FogFieldEmitters)
+- AetheriaRuntimeEquipmentStateCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1240  (via AetheriaRuntimeEntitySnapshotCommit.EquipmentStates)
+- AetheriaRuntimeLoadoutGenerationSelectionCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1264  (via AetheriaRuntimeLoadoutGenerationReceiptCommit.Selections)
+- AetheriaRuntimeEntityContactCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1275  (via AetheriaRuntimeEntitySnapshotCommit.Contacts)
+- AetheriaRuntimeEntityStatGridCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1291  (via AetheriaRuntimeEntitySnapshotCommit.StatGrids)
+- AetheriaRuntimeActiveConsumableCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1307  (via AetheriaRuntimeEntitySnapshotCommit.ActiveConsumables)
+- AetheriaRuntimeConsumableBehaviorStateCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1330  (via AetheriaRuntimeActiveConsumableCommit.BehaviorStates)
+- AetheriaRuntimeBehaviorProgressCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1355  (via AetheriaRuntimeEntitySnapshotCommit.BehaviorProgress)
+- AetheriaRuntimeWeaponStateCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1374  (via AetheriaRuntimeEntitySnapshotCommit.WeaponStates)
+- AetheriaRuntimeBehaviorStateCommit  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeSnapshotDocuments.cs:1444  (via AetheriaRuntimeEntitySnapshotCommit.BehaviorStates)
+- AetheriaRuntimeStarbridgeStationStockItem  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeStarbridgeDocuments.cs:71  (via AetheriaRuntimeStarbridgeScenarioDocument.StationStock)
+- AetheriaRuntimeStarbridgeWaveDefinition  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeStarbridgeDocuments.cs:83  (via AetheriaRuntimeStarbridgeScenarioDocument.Waves)
+- AetheriaRuntimeStarbridgeWaveForecast  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeStarbridgeDocuments.cs:94  (via AetheriaRuntimeStarbridgeSessionSummaryDocument.WaveForecast)
+- AetheriaRuntimeStarbridgeRuntimeRole  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeStarbridgeDocuments.cs:104  (via AetheriaRuntimeStarbridgeScenarioDocument.RuntimeRoles)
+- AetheriaRuntimeAuthorityRuntimeRole  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeVerseAuthorityPolicy.cs:194  (via AetheriaRuntimeVerseAuthorityPolicyDocument.RuntimeRoles)
+- AetheriaRuntimeAuthorityRule  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeVerseAuthorityPolicy.cs:201  (via AetheriaRuntimeVerseAuthorityPolicyDocument.Rules)
+- AetheriaRuntimeArenaSeat  Packages/org.gamecult.aetheria.state/Runtime/AetheriaRuntimeVerseAuthorityPolicy.cs:255  (via AetheriaRuntimeArenaRosterDocument.Seats)
+
+## AquaSynth (0 element types)
+
+None.
+
+
+## Aquarium (1 element types)
+
+- AquariumFaceVoiceEndpointState  src/Aquarium.Epiphany/State/AquariumLiveState.cs:61  (via AquariumLiveState.FaceVoiceEndpoints)
+
+## Brokkr (4 element types)
+
+- BrokkrGameObjectSnapshot  surfaces/unity/Packages/com.gamecult.brokkr/Runtime/BrokkrHostSnapshot.cs:42  (via BrokkrHostSnapshot.sceneObjects)
+- BrokkrComponentSnapshot  surfaces/unity/Packages/com.gamecult.brokkr/Runtime/BrokkrHostSnapshot.cs:62  (via BrokkrGameObjectSnapshot.components)
+- BrokkrSerializedPropertySnapshot  surfaces/unity/Packages/com.gamecult.brokkr/Runtime/BrokkrHostSnapshot.cs:73  (via BrokkrComponentSnapshot.properties)
+- BrokkrAssetSnapshot  surfaces/unity/Packages/com.gamecult.brokkr/Runtime/BrokkrHostSnapshot.cs:84  (via BrokkrHostSnapshot.assets)
+
+## Delvehold (0 element types)
+
+None.
+
+
+## Eve (17 element types)
+
+- EveAssetCatalogEntry  packages/org.gamecult.eve.surface/Runtime/EveAssetCatalogDocument.cs:52  (via EveAssetCatalogDocument.Assets)
+- EveAssetVariant  packages/org.gamecult.eve.surface/Runtime/EveAssetCatalogDocument.cs:89  (via EveAssetCatalogEntry.Variants)
+- EveEntitySoaBuffer  packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:33  (via EveEntitySoaViewDocument.Buffers)
+- EveEntitySoaColumn  packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:41  (via EveEntitySoaViewDocument.Columns)
+- EveEntitySoaDirtyRange  packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:55  (via EveEntitySoaViewDocument.DirtyRanges)
+- EveEntityIdentity  packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:64  (via EveEntitySoaViewDocument.Identities)
+- EveEntityRenderGroup  packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:77  (via EveEntitySoaViewDocument.RenderGroups)
+- EveInputActionDocument  packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:22  (via EveInputCapabilityDocument.Actions)
+- EveInputProfileDocument  packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:51  (via EveInputCapabilityDocument.DefaultProfiles)
+- EveInputBindingDocument  packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:59  (via EveInputProfileDocument.Bindings)
+- EveProviderWitness  packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:249  (via EveProviderAdvertisementDocument.Witnesses)
+- EveAdvertisedSurface  packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:265  (via EveProviderAdvertisementDocument.Surfaces)
+- EveAdvertisedCommand  packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:333  (via EveProviderAdvertisementDocument.Commands)
+- EveSurfaceComponent  packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:106  (via EveSurfaceComponent.Children)
+- EveEmbeddedDocumentSlot  packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:230  (via EveSurfaceComponent.EmbeddedDocuments)
+- EveStyleToken  packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:277  (via EveSurfaceTree.Styles)
+- EveCommandTemplate  packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:295  (via EveSurfaceDocument.Commands)
+
+## EvePlugins (1 element types)
+
+- EveFieldsSplatLayer  plugins/eve-plugin-fields/unity/org.gamecult.eve.plugin-fields/Runtime/EveFieldsDocuments.cs:38  (via EveFieldsSplatsDocument.Layers)
+
+## Ghostlight (17 element types)
+
+These types are a vendored copy of Eve (`vendor/eve`); they change when Eve does and the pin bumps.
+
+- EveAssetCatalogEntry  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveAssetCatalogDocument.cs:52  (via EveAssetCatalogDocument.Assets)
+- EveAssetVariant  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveAssetCatalogDocument.cs:89  (via EveAssetCatalogEntry.Variants)
+- EveEntitySoaBuffer  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:33  (via EveEntitySoaViewDocument.Buffers)
+- EveEntitySoaColumn  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:41  (via EveEntitySoaViewDocument.Columns)
+- EveEntitySoaDirtyRange  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:55  (via EveEntitySoaViewDocument.DirtyRanges)
+- EveEntityIdentity  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:64  (via EveEntitySoaViewDocument.Identities)
+- EveEntityRenderGroup  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveEntitySoaViewDocument.cs:77  (via EveEntitySoaViewDocument.RenderGroups)
+- EveInputActionDocument  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:22  (via EveInputCapabilityDocument.Actions)
+- EveInputProfileDocument  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:51  (via EveInputCapabilityDocument.DefaultProfiles)
+- EveInputBindingDocument  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveInputCapabilityDocument.cs:59  (via EveInputProfileDocument.Bindings)
+- EveProviderWitness  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:249  (via EveProviderAdvertisementDocument.Witnesses)
+- EveAdvertisedSurface  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:265  (via EveProviderAdvertisementDocument.Surfaces)
+- EveAdvertisedCommand  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveProviderDocuments.cs:333  (via EveProviderAdvertisementDocument.Commands)
+- EveSurfaceComponent  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:106  (via EveSurfaceComponent.Children)
+- EveEmbeddedDocumentSlot  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:230  (via EveSurfaceComponent.EmbeddedDocuments)
+- EveStyleToken  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:277  (via EveSurfaceTree.Styles)
+- EveCommandTemplate  vendor/eve/packages/org.gamecult.eve.surface/Runtime/EveSurfaceDocument.cs:295  (via EveSurfaceDocument.Commands)
+
+## Gjallar (3 element types)
+
+- GjallarAdvertisedSchema  src/Gjallar/VerseState.cs:462  (via GjallarProviderAdvertisementRecord.Schemas)
+- GjallarAdvertisedWitness  src/Gjallar/VerseState.cs:470  (via GjallarProviderAdvertisementRecord.Witnesses)
+- GjallarAdvertisedSurface  src/Gjallar/VerseState.cs:480  (via GjallarProviderAdvertisementRecord.Surfaces)
+
+## Heimdall (12 element types)
+
+These types are a vendored copy of CultLib (`vendor/CultLib`); C2a already adds the ids in CultLib, so they resolve when the pin bumps. The witness bundle types are the fork reported with C2a.
+
+- CultGeometryDomainNode  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:61  (via CultGeometryDomainNode.Children)
+- CultGeometryFeatureClaim  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:106  (via CultGeometryDomainNode.Claims)
+- CultGeometryContributionRow  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:262  (via CultGeometrySelectedCutManifest.Diagnostics)
+- CultMeshBodyDescriptor  vendor/CultLib/src/GameCult.Mesh/CultMeshBodies.cs:35  (via CultMeshBodyPublicationDocument.Representations)
+- CultMeshCdnChunkRef  vendor/CultLib/src/GameCult.Mesh/CultMeshCdn.cs:73  (via CultMeshCdnArtifactManifest.Chunks)
+- CultMeshDiscoveryCandidateDocument  vendor/CultLib/src/GameCult.Mesh/CultMeshDiscoveryService.cs:418  (via CultMeshDiscoveryStateDocument.Candidates)
+- CultMeshEntityPrefabComponent  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:81  (via CultMeshEntityPrefabNode.Components)
+- CultMeshEntityPrefabAssetRef  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:96  (via CultMeshEntityPrefabPackage.Assets)
+- CultMeshEntityPrefabNode  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:127  (via CultMeshEntityPrefabPackage.Nodes)
+- CultWitnessContractPin  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:105  (via CultWitnessArtifactBundle.Contracts)
+- CultWitnessArtifactEntry  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:136  (via CultWitnessArtifactBundle.Artifacts)
+- CultWitnessTimingEntry  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:179  (via CultWitnessArtifactBundle.TimingWitnesses)
+
+## Mimir (0 element types)
+
+None.
+
+
+## StreamPixels (20 element types)
+
+`CultGeometryDomainNode` is the vendored CultLib copy; C2a already adds its id.
+
+- ActivationCondition  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/ActivationCondition.cs:18  (via CharacterConditions.Conditions)
+- BattleEffect  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/BattleEffect.cs:8  (via BattleAction.Effects)
+- GearStatEffect  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/GearStatEffect.cs:7  (via GearData.StatEffects)
+- OverlaySceneIntent  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/ServiceLink/OverlayFrameDocuments.cs:33  (via OverlaySceneIntentWindow.Intents)
+- PlayedIntentRecord  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/ServiceLink/PlayedIntentLedger.cs:25  (via OverlayPlayedIntents.Entries)
+- StatModifier  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/StatModifier.cs:7  (via GearStatEffect.Modifiers)
+- StatusEffect  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/StatusEffect.cs:10  (via StatusData.Effects)
+- WeaponDamageTypeMultiplier  apps/overlay-unity/Assets/Scripts/Assembly-CSharp/WeaponDamageTypeMultiplier.cs:7  (via WeaponData.DamageMultipliers)
+- CultGeometryDomainNode  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:61  (via CultGeometryDomainNode.Children)
+- CultGeometryFeatureClaim  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:106  (via CultGeometryDomainNode.Claims)
+- CultGeometryContributionRow  vendor/CultLib/src/GameCult.Geometry/CultGeometryDocuments.cs:262  (via CultGeometrySelectedCutManifest.Diagnostics)
+- CultMeshBodyDescriptor  vendor/CultLib/src/GameCult.Mesh/CultMeshBodies.cs:35  (via CultMeshBodyPublicationDocument.Representations)
+- CultMeshCdnChunkRef  vendor/CultLib/src/GameCult.Mesh/CultMeshCdn.cs:73  (via CultMeshCdnArtifactManifest.Chunks)
+- CultMeshDiscoveryCandidateDocument  vendor/CultLib/src/GameCult.Mesh/CultMeshDiscoveryService.cs:418  (via CultMeshDiscoveryStateDocument.Candidates)
+- CultMeshEntityPrefabComponent  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:81  (via CultMeshEntityPrefabNode.Components)
+- CultMeshEntityPrefabAssetRef  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:96  (via CultMeshEntityPrefabPackage.Assets)
+- CultMeshEntityPrefabNode  vendor/CultLib/src/GameCult.Mesh/CultMeshEntityPrefabs.cs:127  (via CultMeshEntityPrefabPackage.Nodes)
+- CultWitnessContractPin  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:105  (via CultWitnessArtifactBundle.Contracts)
+- CultWitnessArtifactEntry  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:136  (via CultWitnessArtifactBundle.Artifacts)
+- CultWitnessTimingEntry  vendor/CultLib/src/GameCult.Networking/CultWitnessArtifactBundle.cs:179  (via CultWitnessArtifactBundle.TimingWitnesses)
+
+## Ymir (1 element types)
+
+- YmirTransportLoweringDocument  src/Ymir.Core/YmirServicePublicationDocument.cs:63  (via YmirProviderAdvertisementDocument.CommandLowerings)
+
+## CultLib itself
+
+C2a adds ids to: `CultGeometryDomainNode`, `CultGeometryFeatureClaim`, `CultGeometryContributionRow` (`src/GameCult.Geometry/CultGeometryDocuments.cs`); `CultMeshBodyDescriptor` (`src/GameCult.Mesh/CultMeshBodies.cs:35`); `CultMeshDiscoveryCandidateDocument` (`CultMeshDiscoveryService.cs:418`); `CultMeshEntityPrefabAssetRef`, `CultMeshEntityPrefabComponent`, `CultMeshEntityPrefabNode` (`CultMeshEntityPrefabs.cs`); `CultWitnessContractPin`, `CultWitnessArtifactEntry`, `CultWitnessTimingEntry` (`src/GameCult.Networking/CultWitnessArtifactBundle.cs`).
+
+`CultMeshCdnChunkRef` (`src/GameCult.Mesh/CultMeshCdn.cs:73`) has a derived id, `[CultElementId(nameof(Offset))]`: the decimal text of its offset, never random, so packing the same body encodes the same manifest bytes. `contracts/cultmesh/content-vectors.*.json` and the Rust runtime carry it. A consumer with content-addressed elements declares the same way.

docs/nuget-packaging.md

@@ -25,5 +25,5 @@ closure through UPM rather than NuGet restore.
 Install the Unity package from the immutable release tag:
 
 ```text
-https://github.com/GameCult/CultLib.git?path=/unity/org.gamecult.cultlib#cultlib-unity-v1.0.57
+https://github.com/GameCult/CultLib.git?path=/unity/org.gamecult.cultlib#cultlib-unity-v2.0.0
 ```

docs/research/2026-10-22-consumer-pinning-at-breaking-land.md

@@ -0,0 +1,59 @@
+# Consumer pinning at a breaking land: prior art and internal state
+
+Serves fork `variants:question:unpinned-consumers-at-land` (campaign `variants`, session `self-2026-10-22-eureka-c2a`).
+Eyes pass, 2026-10-22. Facts and evidence pointers only; no recommendation.
+
+Question as admitted: Eve.Surface and Brokkr build against an unpinned sibling `..\CultLib` source checkout. C2a (refuse element types with no id) lands on main. Options: pin-then-land, sweep-then-land, land-and-break.
+
+## Sources
+
+| # | Source | URL | Status |
+|---|---|---|---|
+| S1 | Abseil, About / philosophy | https://abseil.io/about/philosophy | fetched |
+| S2 | Abseil, compatibility guidelines | https://abseil.io/about/compatibility | fetched |
+| S3 | Software Engineering at Google, ch. 21 Dependency Management | https://abseil.io/resources/swe-book/html/ch21.html | fetched |
+| S4 | Software Engineering at Google, ch. 16 Version Control and Branch Management | https://abseil.io/resources/swe-book/html/ch16.html | fetched (does not cover live at head) |
+| S5 | Russ Cox, Minimal Version Selection | https://research.swtch.com/vgo-mvs | fetched |
+| S6 | Cargo book, Cargo.toml vs Cargo.lock | https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html | fetched |
+| S7 | npm docs, package-lock.json | https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json | fetched |
+| S8 | Chromium src, dependencies doc (DEPS, gclient, roll-dep) | https://chromium.googlesource.com/chromium/src/+/main/docs/dependencies.md | fetched |
+| S9 | Pro Git, Submodules | https://git-scm.com/book/en/v2/Git-Tools-Submodules | fetched |
+| S10 | chromium infra dependencies.md | https://chromium.googlesource.com/infra/infra/+/main/docs/dependencies.md | 404, not retrieved |
+| L1 | `F:\Projects\Aetheria\Directory.Build.targets`, `Directory.Build.props`, git history | local files | read |
+| L2 | `F:\Projects\Aetheria\docs\cultcache-migration-cut.md` (Q6 table, lines ~565-580; pin guard notes ~1900-1925) | local file | read |
+| L3 | `F:\Projects\Eve` and `F:\Projects\Brokkr` csprojs and git file lists | local files | read |
+| L4 | voidbot `search_history` (two queries), `search_sources` (one query) | MCP | queried |
+
+Anything not in a "fetched" row above is not claimed from the web.
+
+## 1. Established practice: who pays for a breaking upstream change, and when
+
+- **Abseil / live at head (S1, S2).** Recommends users track the latest code. Says it will provide a tool to perform an API refactor for well-behaved code (S1). Requires of downstream: show how you call it, stay within the compatibility guidelines; otherwise fork or use periodic supported branches (about every 6 months, patched 2 years) (S1). Says every change is potentially breaking for someone; breaks are announced in commit messages and LTS notes, and users are asked to report undetected breaks on GitHub (S2). Users should be able to temporarily pin to an earlier commit if a newer change is a problem (S2). S1/S2 do not mention Rosie, the Beyonce rule, or caller-fixing; the fetched pages describe tooling and a feedback channel only.
+- **Live at Head as described in SWE at Google ch. 21 (S3).** Providers are expected to test changes against downstream dependents before committing; breaking changes wait until dependents are updated or an automated migration tool exists. Consumers must keep meaningful tests. Stated preconditions: unit tests across dependencies run in CI, a visible reverse-dependency graph, substantial compute, no pinning of dependencies, provider acceptance of the downstream-testing duty. Called "costly but effective" inside Google and "largely unproven at scale." Notes that under SemVer a major bump costs maintainers little and many indirect users a lot. Ch. 16 (S4) does not address live at head; it states large-scale changes across trunk are costly and tooling-supported.
+- **Go MVS (S5).** Selects the oldest version satisfying all declared minimums. Publishing a new version changes nobody's build; a consumer gets it only when a requirement names it, directly or through another module. Upgrades are explicit edits to `go.mod` by the top-level module. Compatibility rule: newer versions inside one major version are expected to work where older did; a major version is a different module identity. Cost of a breaking change falls on whoever opts into the new version, at the time they opt in.
+- **Cargo (S6).** Git dependency without `rev` takes the default-branch tip at first build and fixes that commit in `Cargo.lock`; changes arrive only on `cargo update`. A `rev` in `Cargo.toml` pins explicitly; the Cargo book calls hand-managed SHAs "tedious and error prone" and prefers the lockfile. Consumer pays at `cargo update` time.
+- **npm (S7).** `package-lock.json` records the exact tree; installs stay on it until the lockfile changes and is committed. It is not published with a package. The page gives no timeline for when updates reach a consumer.
+- **Chromium DEPS (S8).** `DEPS` stores dependency URLs and commit hashes (often in `vars`). Developers roll with `gclient setdep`, `roll-dep`, or manual `git update-index`; some projects (Skia) are autorolled. The page says manual rolling after an upstream change is good practice to confirm the roll compiles and tests pass. It does not describe revert procedure. Cost is paid by the roller at roll time.
+- **Git submodules (S9).** The superproject records one commit SHA (gitlink, mode 160000). Upstream commits never move the pin; it moves when someone updates the checkout and commits the new SHA in the superproject. Collaborators receive the pin via pull and must run `git submodule update`.
+
+## 2. Internal precedent
+
+- **Aetheria pin (L1).** `Directory.Build.props` holds `CultLibRevision` (currently `45c2f4006f5f7dab357426cabd3197e8d0a17f66`) and `CultMathRevision` (`9c1b06cd703bfa44352050e819b0d0659cf5978a`). `Directory.Build.targets` target `VerifyCultLibRevision` (BeforeTargets `ResolveProjectReferences`) errors if the sibling checkout's `git rev-parse HEAD` differs from the pin, or if `git status --porcelain` is non-empty; escape hatch `SkipCultLibRevisionCheck=true`. File is 39 lines; the pin is one pair of properties per pinned package.
+- **Why added (L1 git).** Commit `4f4beb0f` (2026-09-14, "Pin CultLib for headless builds"): "Directory.Build.targets carries Delvehold's VerifyCultLibRevision guard, checking for CultMath.csproj: HEAD must equal the pin and the worktree must be clean." Commit `e91ba369` (2026-09-24, "Pin CultLib per package, as Unity's manifest does"): headless build must compile the revisions Unity consumes; a single pin would have compiled six commits of newer CultCache under headless tests while Unity stays on its tag. The Aetheria cut doc (L2, ~line 1905) calls the guard "the only working pin for a sibling checkout." Aetheria's `Packages/manifest.json` pins Unity packages by git tag.
+- **Pin guard already in Delvehold (L4/search_sources hit, `Delvehold:Directory.Build.targets`)** and a variant in AetheriaEve (archived, `Aetheria.State.Dependencies.targets`, also checks a Unity package tree hash). Delvehold's guard checks `GameCult.Mesh.csproj` exists, HEAD equals `CultLibRevision`, tree clean. Date of Delvehold's first guard: not determined.
+- **Consumer table (L2, Q6 in Aetheria `docs/cultcache-migration-cut.md`).** Aquarium, Ymir, AquaSynth, Mimir, Gjallar: ".NET sibling, unpinned", compile against main at once. Brokkr, Eve, EveUnity, EvePlugins: "Unity package / sibling", pin "various". Delvehold: sibling with revision guard at `334e60f`, 52 behind, "Not until it re-pins." Heimdall: submodule `b6b1d9c`. Rust consumers (Idunn, Epiphany, Odin, Ghostlight, Muninn, Ratatoskr, CodexConnector): Cargo by commit.
+- **Operator discussion (L4).** voidbot `search_history` ("pin CultLib revision vs track main for consumers"; "Brokkr Eve sibling CultLib checkout build pin") returned no relevant operator statement on pinning versus tracking; hits were unrelated Discord chatter. Nearest operator words found in the Discord index: Metacrat, 2026-05-09, "Oh, anyone using CultLib will still be paying the blood price, you can count on that" (message 1502671320406687894; context not fetched, so its subject is not confirmed). No operator quote on pinning versus tracking was found in memory files grepped (`C:\Users\Meta\.claude\projects\F--Projects\memory`, pattern pin/track main/unpinned/sibling) beyond a retired Idunn pin line and Odin/Muninn pin-branch coordination notes.
+- Aetheria cut doc operator mentions near pins are about content (Schematic-shape drawer, 2026-09-14; Studio grouping, 2026-09-17), not pinning policy.
+
+## 3. Current state of the two consumers (L3)
+
+- **Eve.** `packages/org.gamecult.eve.surface/GameCult.Eve.Surface.csproj:16` `CultLibRoot` defaults to `$(MSBuildThisFileDirectory)..\..\..\CultLib`; lines 20-21 ProjectReference `$(CultLibRoot)\src\GameCult.Caching\...` and `...\GameCult.Mesh\...`. `tests/GameCult.Eve.Surface.Serialization.Tests/*.csproj:19` references `$(CultLibRoot)\src\GameCult.Mesh\...` (and Eve.Surface by relative path). `git ls-files` shows only `packages/org.gamecult.eve.surface/Directory.Build.props` (sets only BaseOutputPath/BaseIntermediateOutputPath/MSBuildProjectExtensionsPath, no revision). No `Directory.Build.targets`, no `global.json`, no `.gitmodules`, no revision property or check. Eve also holds Cargo.toml/Cargo.lock (Rust side, not examined).
+- **Brokkr.** `brokkr-command/Brokkr.Command.csproj:7`, `brokkr-contracts.Tests/Brokkr.Contracts.Tests.csproj:7`, `brokkr-contracts/Brokkr.Contracts.csproj:8`: `CultLibRoot` defaults to `..\..\CultLib`. ProjectReferences: Caching, Caching.MessagePack, Mesh, Networking (by project). No `Directory.Build.*`, no `.gitmodules` in `git ls-files`; no revision property or check.
+- Neither repo contains `CultLibRevision`, a `VerifyCultLibRevision` target, or any HEAD check. Both build whatever `F:\Projects\CultLib` currently holds (including dirty or other-branch states).
+- Fork text claims (not re-verified here): Eve.Surface has 0 `[CultElementId]`; Brokkr `[CultDocument]` files show no object lists by grep.
+
+## Gaps
+
+- S10 (Chromium infra) 404; Chromium autoroller behavior beyond S8 not fetched.
+- Rosie / Beyonce rule not found in fetched pages; not cited from memory.
+- No operator statement on pin-versus-track found in voidbot or the memory grep.

docs/research/2026-10-23-schema-drift-write-back-prior-art.md

@@ -0,0 +1,74 @@
+Serves the C2a fork on finding variants:finding:cut-land-c2a-gate.s1.reflist-record-read-only-at-head (campaign variants), 2026-10-23.
+
+# Prior art: read with an old writer schema, then write back
+
+Facts only. Pages were fetched 2026-10-23 through a summarising fetcher; "not stated" means the fetched page did not say it, not that no source does. Items marked (memory) are my background knowledge, not verified from a fetched page.
+
+## 1. Apache Avro
+- Source: https://avro.apache.org/docs/current/specification/ (Schema Resolution; summarised via apache/avro doc source), Java `DataFileWriter` javadoc (1.11.1).
+- Model: the writer schema travels with the data. The reader resolves it against its own reader schema. Resolution is a read-time projection; the spec defines no write-back.
+- Data loss on projection: "the writer's value for that field is ignored" when the reader schema lacks the field. A reader-only field takes its default, or the read errors if it has none.
+- Write-back: the spec states no rule. Object container files store one schema in the header ("Each datum in a file is of the same schema"). `appendTo` is documented only as "Open a writer appending to an existing file"; it does not say which schema the append uses. (memory: Java `appendTo` reuses the file's header schema, so an append never restamps.)
+- Stated reason for the read-time design: readers and writers evolve separately (fields added or removed in a different software version).
+
+## 2. Protocol Buffers (proto3)
+- Source: https://protobuf.dev/programming-guides/proto3/ (Unknown Fields).
+- On write: unknown fields are "included during parsing and in the serialized output" (matches proto2). Round-trip keeps fields the current type does not know.
+- Loss cases the page lists: serializing to JSON, and copying a message field by field into a new message (it recommends `CopyFrom`/`MergeFrom`).
+- No schema id or version is written. The wire format carries only field numbers, so "restamp" has no meaning here.
+- Not stated: behaviour in versions before 3.5 (memory: proto3 dropped unknown fields before 3.5, then reversed). The Java reference page says nothing on preservation.
+- Stated reason: preserve data across a mixed-version fleet.
+
+## 3. Confluent Schema Registry
+- Source: https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html
+- BACKWARD (default): consumers on the new schema read data written with the new or the previous version. FORWARD: data written with the new schema is readable by consumers on the old one. FULL: both.
+- Write: "Each schema version gets a unique ID and an incremented version number." A producer writes under the schema it holds (its own current version). The id is stamped per message at serialisation, from the producer's schema.
+- Upgrade order is how the rules prevent loss. BACKWARD means upgrade consumers before producers. FORWARD means upgrade producers first, and keep old-schema data away from consumers until they are upgraded.
+- Not stated on the page: what a consume-modify-produce app writes. (memory: it re-serialises under its own latest schema, so fields it does not model are lost unless a compatibility rule kept them.)
+- The registry gates registration. It does not gate individual rewrites.
+
+## 4. Document DBs and ORMs with stored versions
+### MongoDB schema-versioning pattern
+- Sources: https://www.mongodb.com/blog/post/building-with-patterns-the-schema-versioning-pattern ; https://www.mongodb.com/docs/manual/data-modeling/design-patterns/data-versioning/schema-versioning/
+- Documents carry `schema_version` (absent means 1). The app keeps a handler per version and writes new documents at the current version.
+- Migration strategy is the app's choice: migrate all, migrate "when accessed" (lazy), or never.
+- Not stated: whether an update of an old document restamps it. The manual's update example branches on `schemaVersion` and writes into each version's own shape. It notes its `else: null` branch adds stray null fields to the other shape.
+- Stated reasons: no downtime, failed migrations easier to handle, timing flexibility. Cost: handler code per live version.
+
+### Realm (Atlas Device SDKs, now deprecated)
+- Source: https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/model-data/change-an-object-model.md
+- Per-file schema version. A changed schema needs an incremented `schemaVersion`, plus a `migrationBlock` for non-trivial changes. The file is migrated whole at open, before any read or write, and Realm "will throw an error" if the version is lower or the same but the schema differs.
+- No lazy per-object restamp. Writes happen only on a migrated file.
+- Data loss: the manual says "Deleting a property will not impact existing objects", i.e. removal is automatic and needs no developer step. Required new properties and renames need a manual block. (memory: removed-property values are dropped from the file.)
+
+### Core Data
+- Source: web search results only (Apple forum threads 745114 and 785427, WWDC22-10120, "staged migrations" doc). The Apple docs URL I tried returned 404.
+- A store whose model hash differs from the current model fails to open with an incompatible-version error. Opening migrates the whole store when `NSMigratePersistentStoresAutomaticallyOption` and `NSInferMappingModelAutomaticallyOption` are set. Lightweight migration covers only obvious patterns (add entity, remove relationship, required to optional, rename). Anything else needs a staged or custom migration.
+- Migration is store-wide at open. It does not happen per record on write.
+
+### EF Core
+- Not fetched. (memory: no per-row schema stamp. Migrations are explicit, ordered DDL, tracked in a `__EFMigrationsHistory` table.)
+
+## 5. Old-schema data held read-only until explicit migration
+### Elasticsearch archive indices
+- Sources: https://www.elastic.co/docs/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions ; https://www.elastic.co/guide/en/elasticsearch/reference/current/archive-indices.html ; 8.0 migration notes (7.0+ indices readable, 6.x or earlier must be reindexed).
+- Indices from an older major are readable through search and field-caps. "They do not support the Get API or any write APIs."
+- The route to a writable copy is reindex into a new index that is "fully compatible with the current Elasticsearch version". `_source` is readable, so no data is lost on reindex.
+- Stated reason: the page does not say why they are read-only. It describes archive access as "slower read-only access", with limited query capability. Some legacy mappings cannot be imported (the original is kept in `_meta`), and that is the one place the page shows a lossy translation.
+- Third-party (Search Guard blog, unverified against Elastic): in 9.x a plain `index.blocks.write` does not satisfy the boot check; `index.verified_read_only` is needed.
+- This is the closest match to option (b) in the fetched set: an old format, readable but not writable, left until the owner reindexes it.
+
+## Where restamp-on-write loses data (from the sources above)
+- Avro: a field present in the writer schema and absent from the reader schema is dropped at read, "ignored". Any rewrite from the resolved value would omit it.
+- Protobuf: unknown fields survive a binary round trip. They are lost via JSON, or when copied field by field.
+- Realm: removed properties are deleted by the automatic migration.
+- MongoDB: a handler that writes only the current shape can lose or relocate old-shape fields (the manual's example adds nulls).
+- Confluent: loss is prevented by compatibility rules at registration time, not at each write.
+
+## Pattern across the set
+- No fetched system restamps a single record on write when the record's writer schema differs from the application's type, on an app-visible, per-record basis.
+  - Avro, protobuf and Confluent carry the schema per file or message.
+  - Realm, Core Data and Elasticsearch move or block the whole store or index at open.
+  - MongoDB leaves it to the app.
+- Whole-store migration at open is the usual explicit step (Realm, Core Data). Elasticsearch is the one case of read-only-until-reindex.
+- Not found: a system that declares per-schema-id compatibility, as in option (b). Avro schema resolution and Confluent compatibility rules are the nearest analogues. Both are read-side or registration-side declarations.

docs/research/2026-10-23-store-lock-user-code-prior-art.md

@@ -0,0 +1,53 @@
+Serves question variants:question:store-hold-user-code (campaign variants), 2026-10-23.
+
+# Prior-art check: user code under a lock
+
+Facts and pointers only. Each source was fetched or searched this session; what was not reachable is marked.
+
+## 1. Goetz et al., Java Concurrency in Practice (Addison-Wesley, 2006), ch. 10 "Avoiding Liveness Hazards"
+Status: EXISTS, SECTION NUMBER CORRECTED.
+- "Open Calls" is **10.1.4**, not 10.1.3. 10.1.3 is "Deadlocks Between Cooperating Objects"; 10.1.2 is "Dynamic Lock Order Deadlocks"; 10.1.5 is "Resource Deadlocks". Source: text extracted from a PDF copy of the book (its TOC lists Listing 10.6 "Using Open Calls to Avoiding Deadlock Between Cooperating Objects", p. 133). The copy is an unofficial one at library.megu.edu.ua; a publisher link was not checked.
+- (a) 10.1.3 gives the warning sign: an "alien method" (defined p. 40 as a method whose behavior the calling class does not fully specify) called while holding a lock. Paraphrase: such a call may take other locks (deadlock risk) or block a long time, stalling threads that need the lock you hold. 10.1.4 defines an open call as a call made with no locks held (credited to Lea, CPJ 2.4.1.3) and says programs restricted to open calls are far easier to analyze for deadlock-freedom than ones that allow alien calls under lock.
+- Cost it names: moving a call out of a synchronized block makes an atomic operation non-atomic (its getImage example stops being a snapshot). Where atomicity is needed it suggests structuring so only one thread can run the code path after the open call (service shutdown example).
+- (b), (c): not addressed in this section.
+- Pointer: JCIP 10.1.3 and 10.1.4, pp. ~132-134 (chapter 10 starts p. 128).
+
+## 2. Sutter, "Effective Concurrency: Avoid Calling Unknown Code While Inside a Critical Section"
+Status: VERIFIED, with date caveat.
+- Dr. Dobb's column in the "Effective Concurrency" series. Sutter's blog teaser is dated 2007-11-06: https://herbsutter.com/2007/11/06/effective-concurrency-avoid-calling-unknown-code-while-inside-a-critical-section/ . Original link ddj.com/architect/202802983; Dr. Dobb's mirror https://drdobbs.com/cpp/avoid-calling-unknown-code-while-inside/202802983 (4 pages). The Dr. Dobb's issue date was not shown in anything fetched; the blog date is the only date confirmed. www.drdobbs.com did not resolve from this machine, so the column body comes from search-result summaries and the blog teaser, not a full first-hand read.
+- (a) Core claim: locks do not compose; two separately correct modules can deadlock when combined. Trigger: caller inside a critical section, callee enters another critical section or blocks, another thread can take the same two in the opposite order. "Unknown code" listed as: library functions, plug-ins, callbacks/function pointers, virtual methods, generic types.
+- Mitigations listed: move the call outside the critical section; pass copies instead of shared data; narrow the critical section (finer locks, reader-writer); require callees not to block (documentation/discipline only).
+- (b), (c): not addressed.
+
+## 3. Linux lockdep
+Status: VERIFIED, with a nuance.
+- Source: kernel docs "Runtime locking correctness validator", https://docs.kernel.org/locking/lockdep-design.html .
+- (b) Lockdep tracks lock classes, not instances, and records dependencies between classes as sequences are observed. It reports a circular order as a potential deadlock even if the deadlock never happened. Its "Proof of 100% correctness" section says that once each simple single-task locking sequence has occurred at least once, no timing of them can deadlock. Each new lock chain is validated once and hashed; repeats skip validation.
+- Nuance: it flags the dependency edge that closes a cycle, so both orders must have been exercised at some point (possibly by different, non-concurrent runs). A lone nesting is flagged only if it breaks a single-lock rule (IRQ-safe vs unsafe, same-class recursion). "Refuses on first sight" fits the closing edge or a single-lock rule violation only. It warns; it does not block the acquisition.
+
+## 4. ConcurrentHashMap re-check after locking
+Status: VERIFIED.
+- Source: OpenJDK java/util/concurrent/ConcurrentHashMap.java, `putVal` and `computeIfAbsent`: head node `f` is read unlocked, `synchronized (f)` is taken, then `tabAt(tab, i) == f` is re-checked; on failure nothing is done and the loop retries. The overview comment gives the reason: the locked node can be replaced, so first-in-bin must be confirmed after locking. (Only the first 100k of 269k chars were read; both methods were reported found there.) Empty-bin `computeIfAbsent` uses a ReservationNode plus CAS instead.
+- (c) This is the pattern: choose the lock from an unlocked read, validate the read after acquiring.
+
+## 5. LMDB
+Status: VERIFIED (paraphrase). Not about alien code or lock order.
+- Source: lmdb.h, `mdb_txn_begin` and `mdb_env_open` (https://github.com/LMDB/lmdb, libraries/liblmdb/lmdb.h). A thread may hold one transaction at a time (plus children); a transaction and its cursors belong to one thread; one write transaction at a time, so writers cannot deadlock each other; MDB_NOTLS ties reader slots to the txn object instead of the thread, and the application must then serialize writers itself because write locking is unaware of user threads.
+- Relevance: "one hold per thread" as a deliberate rule, parallel to CultCache's one-cache-gate-per-thread.
+
+## 6. SQLite btmutex.c
+Status: VERIFIED (summary of trunk source).
+- Source: https://github.com/sqlite/sqlite/blob/master/src/btmutex.c (read via raw.githubusercontent.com; sqlite.org served a bot check).
+- (b) Prevention by ordering, not detection: sharable B-trees on a connection sit in a list sorted by BtShared address and are always locked ascending (`sqlite3BtreeEnterAll`). `sqlite3BtreeEnter` try-locks first; on failure it releases later-ordered locks, waits, then reacquires in order. `wantToLock` is a count that makes a non-recursive mutex behave recursively.
+- No alien-code or callback discussion in these comments.
+
+## Counter-positions and how they stay safe
+- Callbacks under lock, documented: Java `ConcurrentHashMap.compute`/`computeIfAbsent`. Javadoc (Java 21): the function should be short and simple because other threads' updates may block meanwhile, and must not modify the map. The javadoc does not say "internal lock"; that it runs under the bin lock is inferred from the source in item 4. Safety rests on documented restrictions, not enforcement.
+- Opposite choice: .NET `ConcurrentDictionary.GetOrAdd(key, valueFactory)`. Writes use fine-grained locks but valueFactory runs outside them, "to avoid the problems that can arise from executing unknown code under a lock" (doc remarks). Price: not atomic; the factory may run more than once; a recheck decides the winner (another thread's insert wins). https://learn.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentdictionary-2.getoradd . Same shape as option `encode-first` (user code outside the lock, then recheck and commit) and as item 4.
+- JCIP and Sutter both name the cost of leaving the lock: lost atomicity. Sutter also offers "pass copies" and "callee must not block" as alternatives to leaving.
+- Not researched (no source fetched): Linux notifier chains, Java `synchronized` event listeners, other systems that call back under lock by design. No verified citation for them.
+
+## Unverified / not done
+- JCIP: section numbers and text come from one PDF copy, not the publisher edition.
+- Sutter: full column body not read first-hand.
+- No Discord or voidbot content read.

docs/research/2026-10-27-default-registry-write-ownership-prior-art.md

@@ -0,0 +1,90 @@
+# Prior art: a process-global default registry deciding write ownership
+
+Serves `variants:question:registryless-write-reads-shared` (campaign `variants`). Eyes pass, session `self-2026-10-27b-eureka`, 2026-10-27. Facts only; items marked "summary" rest on search summaries not opened.
+
+# Prior art: process-global type registries and write/overwrite ownership
+
+Fork: `variants:question:registryless-write-reads-shared` (viewed in full via eureka-state, status InForce, options `shared-decides` / `written-type-only`, recommended `shared-decides` at ~65%).
+Facts only. No conclusion. Date 2026-10-27.
+
+Method note: web pages were read through WebFetch (a small model summarises the page) and WebSearch summaries. Quotes below are what those tools returned; where only a summary was available it is marked "summary". Nothing was run.
+
+## A. Local mechanics (CultLib, read-only, `C:\cl-wt\c2a-land\src\GameCult.Caching\CultCache.cs`)
+
+- `CultDocumentRegistry.Shared` is `Lazy<CultDocumentRegistry>` (line 639-645). Its public constructor calls `Refresh()` (647-650), which scans `ReflectionExtensions.GetAttributedDocumentTypes()` (688; defined in `ReflectionExtensions.cs:10`) and rebuilds the indexes under `_registrationGate`. So Shared's initial content is whatever `[CultDocument]` types are in loaded assemblies at first touch of `Shared`.
+- `GetRequired(Type)` (697-711) registers an unregistered `[CultDocument]` type on demand. So Shared also grows whenever any caller asks for a type. `Refresh()` is public and rebuilds the index from currently loaded assemblies.
+- `ForTypes(IEnumerable<Type>)` (658-669) builds a registry with `discoverLoadedDocuments:false`, containing only the given types (plus those `GetRequired` pulls in).
+- `CultCache(registry = null, ...)` sets `_registry = registry ?? CultDocumentRegistry.Shared` (2202-2205).
+- `WriteDocument<TDocument>(key, doc, storedAt, registry = null)` (4515-4545): `resolvedRegistry = registry ?? Shared`; `catalogEntry = resolvedRegistry.GetRequired<TDocument>().ToCatalogEntry()`; then `Cacheless(resolvedRegistry, ...)` lends that registry to the store for the call. XML doc (4510) says Shared "can only refuse more".
+- `WriteRecord(..., registry = null)` (4491-4497): XML doc (4489) says that with registry omitted "it decides nothing for copied records and the one entry is the only claimant".
+- `OwnsOnDisk(upserts)` (4741-4759): when the store is cacheless and upserts are given, ownership of an on-disk record is decided by `CultDocumentRegistry.Owns(id, catalog, declared, new CatalogEntryLookup(writes, AttachedRegistry), ..., claimant => writes.Any(entry => entry.SchemaId == claimant.SchemaId))`. The comment (4731-4735, 4738-4740) says written entries shadow the lent registry's type for their ids, the registry adds other claimants, and the record is owned only when the claimant is a written entry, "a registry can only refuse more". `CatalogEntryLookup` ctor at 604 takes `(entries, CultDocumentRegistry? others)`.
+- Net: with `registry == null` the lent registry's claimant set is Shared's current contents, which depend on assemblies loaded and on every prior `GetRequired` call in the process.
+
+## B. Q1. Process-global, lazily filled registries in established libraries
+
+### MongoDB C# driver, `BsonClassMap`
+- Global: yes. `BsonClassMap.RegisterClassMap` is process-wide static; unregistered types are auto-mapped on first use. Docs: "You must register a class map _before_ it's needed in your code." and "We recommend registering class maps before initializing a connection with MongoDB." https://www.mongodb.com/docs/drivers/csharp/current/serialization/class-mapping/ (WebFetch; the page itself says nothing on freezing or late-registration errors).
+- Behaviour depends on what has been touched: EF Core provider issue EF-88 reports "Unknown discriminator value 'List`1'" when the first operation after startup is a read; reporter links it to a class map that is created only on write. Status Closed/Fixed in 8.0.0; page has no maintainer comment. https://jira.mongodb.org/browse/EF-88 (WebFetch). Reporter says explicit `RegisterClassMap` at startup did not fix it for them.
+- A MongoDB community answer (via search summary, not opened): discriminator mappings persist once registered, so a read after an insert works; fix offered is `[BsonKnownTypes]`. https://mongodb.com/community/forums/t/c-driver-why-is-bsonknowntypes-attribute-needed-for-polymorphism/2183 (summary only).
+- Register-once contract: CSHARP-4424 states the three `RegisterClassMap` methods are "meant to only be called once for a given type"; requested because several libraries share data models and do not control init order. Closed Done, fix version 2.19.0; the page does not say which API shipped. https://jira.mongodb.org/browse/CSHARP-4424 (WebFetch). Community workaround named in search summary: `BsonClassMap.IsClassMapRegistered`.
+- CSHARP-1879 (search summary): `RegisterClassMap` accepted an unfrozen map and failed later on use; fixed 2.4.2. https://jira.mongodb.com/browse/CSHARP-1879 (not opened).
+- CSHARP-5597 (search summary): `BsonSerializer.RegisterDiscriminator` has no effect; discriminator dictionary populated at class-map registration. https://jira.mongodb.org/browse/CSHARP-5597 (not opened).
+- Polymorphic docs: "You must specify hierarchical discriminators in root-to-leaf order." and the relationship of all classes in a hierarchy must be documented before deserialization. https://www.mongodb.com/docs/drivers/csharp/current/serialization/polymorphic-objects/ (WebFetch).
+- Particular docs report an order-dependent GuidSerializer failure ("incorrect order of class mappings"). https://docs.particular.net/persistence/upgrades/mongodb-4to5 (search summary, not opened).
+- Did they move away: not found. Class maps remain global static; mitigation is documentation plus the IfNotRegistered API.
+
+### protobuf-net `RuntimeTypeModel.Default`
+- Global: yes. README: "The Serializer.* methods are basically just shortcuts to RuntimeTypeModel.Default.*". https://cdn.jsdelivr.net/gh/protobuf-net/protobuf-net@main/README.md (WebFetch).
+- Lazy fill, freezing, order-dependent bugs: NOT verified. README is silent; a direct docs fetch (docs.protobuf-net.dev/runtime) was redirected and not followed. No issue found.
+
+### MessagePack-CSharp
+- Global mutable default exists: `MessagePackSerializer.DefaultOptions`. README (WebFetch): labelled "Global state; Not recommended when writing library code." Safe if you control all MessagePack code; libraries should pass options explicitly because others "may change this static property." Libraries "must not use StaticCompositeResolver - as it is global state". https://github.com/MessagePack-CSharp/MessagePack-CSharp/blob/master/README.md
+- Resolvers are an ordered list (`CompositeResolver`): order matters by construction.
+- Whether it moved away from the global: not found.
+
+### System.Text.Json
+- `JsonSerializerOptions.Default`: "Gets a read-only, singleton instance"; remarks give a performance reason: shared instance avoids "redundant recomputation of converters". https://learn.microsoft.com/dotnet/api/system.text.json.jsonserializeroptions.default (WebFetch). The page states no rationale about cross-component interference; any such reading is inference. Design-discussion issue in dotnet/runtime: searched, not found. Whether Default was ever mutable: not verified.
+- Type-info resolvers: not researched beyond the above.
+
+### Json.NET
+- `TypeNameHandling` is a security concern, not an order concern: CA2326 says "An attacker could modify the serialized data to include unexpected types"; mitigation is a custom `ISerializationBinder` restricting types. https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/quality-rules/ca2326 (WebFetch).
+- `JsonConvert.DefaultSettings` global behaviour/guidance: the Newtonsoft page fetched says nothing about global effects. Not verified.
+
+### Orleans
+- Serializer discovery is build-time source generation (`[GenerateSerializer]`, `[Id]`), not a runtime scan; the docs' older code-generation section lists scan of assemblies referencing the core library plus `KnownType`/`KnownAssembly` attributes. Aliases: "Type aliases are globally scoped, and you cannot have two aliases with the same value in an application." https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/serialization (saved locally: `C:\Users\Meta\.claude\projects\F--Projects-CultLib\0840c7c7-0e31-410e-9012-afb79c3c0742\tool-results\toolu_0148m7no1AbrJzWmNLicn6N9.txt`, lines 134, 839-841).
+- Type manifest / codec registry runtime behaviour, issues: not researched.
+
+### EF Core
+- Model is built per `DbContext` type and cached (IMemoryCache; "the built model has a cache size of 100"); initialised at first operation: "just creating a DbContext instance does not cause the EF model to be initialized." https://learn.microsoft.com/en-us/ef/core/performance/advanced-performance-topics
+- Assembly scan: `ApplyConfigurationsFromAssembly` — "The order in which the configurations will be applied is undefined, therefore this method should only be used when the order doesn't matter." https://learn.microsoft.com/en-us/ef/core/modeling/ ; and "`EntityTypeConfigurationAttribute` types will not be automatically discovered in an assembly."
+- So EF's registry is per context type, not process-global; assembly scan is opt-in and documented as order-undefined.
+
+### Marten
+- Storage is a table and upsert function per document type, alias `mt_doc_<alias>`; alias collisions are resolved with `DocumentAlias`. https://martendb.io/schema/storage (WebFetch). Hierarchies share one table via `AddSubClass<T>()`; subclass docs are "stored as the parent type" in the identity map. https://www.martendb.io/documents/hierarchies (WebFetch). Schema is configured in `StoreOptions` per store, not a process-global.
+
+### Java ServiceLoader
+- "Service providers are loaded and instantiated lazily, that is, on demand." Providers on the class path load in the order `getResources` finds config files; "The ordering of modules in a module layer is not defined." "Instances of this class are not safe for use by multiple concurrent threads." Caches cleared by `reload`. https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ServiceLoader.html (WebFetch). Visibility is class-loader dependent ("must be visible to the class loader").
+
+## C. Q2. Write/overwrite decisions against an existing record of another type
+
+- RavenDB: REST put docs, request body section: updates must "include its collection name in the metadata" and "A document's collection cannot be modified." Server error code for mismatch: the first fetch summary said HTTP 500; not confirmed on a second fetch. https://docs.ravendb.net/7.1/client-api/rest-api/document-commands/put-documents (WebFetch twice). Ayende, RavenDB 4.0 storage: document key namespace is global, same key cannot exist in two collections (summary). https://ayende.com/blog/173954/the-design-of-ravendb-4-0-physically-segregating-collections The check is against the collection named in the write (derived from the writer's type by the client), not a registry; the "client maps entity type to collection" part is inference from the search summary, not a quoted source. `PutDocumentCommand` page: a missing collection means `@empty`; concurrency via `changeVector`, null "to skip the check". https://docs.ravendb.net/client-api/commands/documents/put
+- Marten: per-type tables, so the same id under two types are two rows in two tables; no cross-type check. Same id across subclasses of one hierarchy table: not covered by docs fetched; unverified. Marten docs: upsert is used so users "don't have to check whether a document is new or existing" (search summary of https://www.martendb.io/documents/storing, not opened).
+- MongoDB: the server has no type; `_id` unique per collection; the C# driver writes a `_t` discriminator from the written object's class map. Whether the driver checks an existing document's `_t` on replace: not researched; nothing found stating it does.
+- Couchbase: key unique within a collection; upsert replaces; no server-side type field enforcement; guidance is one type per collection. https://docs.couchbase.com/server/7.0/learn/data/scopes-and-collections.html (search summary, not opened).
+- Orleans: grain identity is type plus key ("type/key"), so same key under two grain classes is two identities, not a conflict. https://learn.microsoft.com/en-ca/%20dotnet/orleans/grains/grain-identity (search summary, not opened). How storage providers key state: not found.
+- Result of this pass: no store found in which a process-global type registry decides whether a write may replace an existing record of another type. Found: collection/type fixed by metadata of the writer (RavenDB), type as part of the key (Orleans, Marten tables), or no check (Couchbase upsert). This is a negative search result, not proof of absence. Not searched: Cosmos DB, DynamoDB, EF Core TPH update of an existing row with another discriminator, Realm, LiteDB, Akka.Persistence.
+
+## D. Q3. Guidance on ambient/global registries and determinism
+
+- Mark Seemann (ploeh, 2019): after discussion with co-author van Deursen, "Ambient Context really is an anti-pattern." Reasons given: he has never used it and superior alternatives exist; he says the claim is unproven. https://blog.ploeh.dk/2019/01/21/some-thoughts-on-anti-patterns/ (WebFetch). Examples he cites as found in the BCL (search summary, not verified on page): `Thread.CurrentPrincipal`, `CultureInfo.CurrentCulture`, `HttpContext.Current`. DI book 2nd ed. chapter 5 lists it among DI anti-patterns: https://www.oreilly.com/library/view/dependency-injection-principles/9781617294730/OEBPS/Text/c05.xhtml (not opened).
+- MessagePack README (above) is itself a library-author statement on global mutable defaults. MongoDB CSHARP-4424 (above) states the shared-library init-order problem. EF Core docs (above) state assembly-scan order is undefined.
+- No .NET guidance specifically about AppDomain-wide/assembly-scan registries and write decisions found.
+
+## E. Not verified / gaps
+- protobuf-net lazy registration, freezing and bug history.
+- Why System.Text.Json made Default immutable; no maintainer statement found.
+- Json.NET DefaultSettings guidance.
+- RavenDB exact error text and HTTP status; whether the stored document is unchanged after refusal.
+- Marten same-id-across-subclasses behaviour.
+- MongoDB driver behaviour on replacing a document whose `_t` differs.
+- Several items above rest on WebSearch summaries I did not open (marked "summary").

docs/research/2026-10-27-structural-schema-ids-prior-art.md

@@ -0,0 +1,90 @@
+# Prior art: structural versus name-inclusive schema ids
+
+Serves the store-identity question raised 2026-10-27 in campaign `variants` (operator: member and declared names vary with runtime naming conventions). Eyes pass, session `self-2026-10-27b-eureka`. Facts only; items marked "summary" rest on search summaries not opened.
+
+# Prior art: structural vs name-inclusive schema identity (campaign variants)
+
+Eyes pass, 2026-10-27. Facts and evidence pointers only. "(fetched)" = page opened via WebFetch (the answer is a small-model extraction of the page, not raw text). "(summary)" = WebSearch result summary, page not opened.
+
+## 0. Local facts (read-only)
+
+- `F:\Projects\CultLib\src\GameCult.Caching\CultCache.cs:717-718` schemaId = Sha256(BuildSemanticFingerprint(...)). `:735-761` fingerprint = `schemaName|schemaVersion` then per member ordered by Slot: `slot:MemberName:TypeName:ref|value:TargetSchemaName:one|many`. `contentHash` (`:716`) is a separate Sha256 of canonical JSON (`:763+`).
+- `TypeName` = `CultSchemaTypeNames.FromType`: CLR `Type.FullName` (namespace-qualified), generics as `Name<args>`, arrays `T[]` (`src\GameCult.Caching\CultSchemaTypeNames.cs:9-31`). So the fingerprint contains .NET type names as well as member names.
+- Contract `Contracts\cultcache-persistence-format.md:257-284` lists what canonicalization must preserve: slots, types, required/default, nullability, collection semantics, enum constraints, encoding shape. Member names and declared schema name are not in that list. `:171-179` says the id is not derived from C#/Rust/TS type names and the same shape should give the same id "regardless of origin language". `:180-190` defines schemaId = "same semantic persistence shape?" vs contentHash = "exact same canonical schema document?". Example catalog entry (`:140-170`) carries optional `supersedesSchemaIds`, `migrationFamily`; its example canonicalSchema fields do carry `"name": "Name"` (PascalCase). Soft-migration reader flow `:286-345` (exact_match / soft_migrate / reject).
+- Runtimes do not derive ids; they emulate C# names:
+  - Python: `packages\cultcache-py\src\cultcache_py\documents.py:326` `member_name=_pascal_case(field.name)`; `:516-517` splits on `_` and capitalises. `schema_id` defaults to `self.type` (`:218`); `compatible_schema_ids` field (`:188,242`).
+  - TypeScript: `packages\cultcache-ts\src\codec.ts:226-232` `pascalCase` (splits on non-alphanumerics), `:267` `memberName: pascalCase(field.name)`; throws if a codec has no C# type name (`:~262`).
+  - Rust: `packages\cultcache-rs\src\lib.rs:295,308` `serde(rename_all = "camelCase")` on envelope structs; `schema_id: Some(T::TYPE.to_string())` at `:2856`. I did not trace how Rust document types obtain a sha256 id.
+  - Python test pins a literal id from shared vectors: `packages\cultcache-py\tests\test_cultcache.py:808` (`tests\vectors\document-variants-c0`).
+- C# also has `CompatibleSchemaIds` (`CultCache.cs:28,313,570`): a record whose persisted id is in the list is accepted (an alias-list mechanism; I saw only the grep lines, not the logic).
+- Ruling `variants:ruling:wire-id-is-version` (eureka-state, InForce, ruled 2026-09-30, operator quote "Agreed on schema identity"): wire schema id = declared version string `<name>.vN`; every runtime stamps/resolves it exactly; a wire binding without `.v<digits>` is refused; "Store ids are unchanged." Cited source: document-variants-cut.md:552-555 (not opened).
+
+## 1. How established formats define identity/compatibility, and whether names participate
+
+Protocol Buffers (fetched https://protobuf.dev/programming-guides/proto3/ and /json/)
+- Field number identifies the field in the binary wire; changing it = delete + add. Field names appear only in TextProto/JSON encodings; reserve deleted numbers and, for JSON/text, names. The proto3 page has no explicit safe/unsafe entry for renaming; names matter only for JSON/text.
+- JSON mapping: names become lowerCamelCase unless `json_name` is set; "Parsers accept both the lowerCamelCase name" and the original proto name (/programming-guides/json/).
+- Message type identity in `Any` is by name: default type URL `type.googleapis.com/<package>.<message>`, "a globally unique identifier" (proto3 page, #any). Type identity is nominal; compatibility is by field numbers.
+
+Apache Avro (fetched https://avro.apache.org/docs/1.11.1/specification/)
+- Parsing Canonical Form (PCF): STRIP keeps only attributes relevant to parsing (type, name, fields, symbols, items, values, size); doc and aliases dropped; FULLNAMES replaces short names with fullnames and drops namespace attributes. Textually equal PCF means "the same" for any reader. Names ARE in the canonical form (record and field names), as is field declaration order. Defaults are absent from the kept list (extractor's inference; spec text not confirmed).
+- Fingerprints: CRC-64-AVRO in single-object encoding (marker C3 01 + 8-byte LE fingerprint); spec recommends at least a 64-bit Rabin, with SHA-256 / MD5 options for larger sets.
+- Name rules: `[A-Za-z_][A-Za-z0-9_]*`, dot-separated namespaces, equality on case-sensitive fullname.
+- Resolution: records match on same unqualified name; "Named types and fields may have aliases"; implementations "may optionally" use aliases to map writer to reader. So in Avro names participate in identity (fingerprint) and resolution; aliases are the rename mechanism and are excluded from the fingerprint.
+
+Cap'n Proto (fetched https://capnproto.org/language.html)
+- Files and types carry 64-bit IDs; `capnp id` generates them randomly. Default ID for a declaration without one = first 8 bytes of MD5 of (parent scope ID, declaration name). "You cannot change the name of a type that doesn't have an explicit ID"; symbolic names can change if ID/ordinals stay. Stated rationale for IDs: short, unambiguous, full names waste wire space. The page does not say why structural hashes were rejected; I found no Varda statement (search pointed at a mailing-list thread "Schema Refactoring and Unique IDs", Aug 2023, unopened).
+- Encoding page (https://capnproto.org/encoding.html, fetched): adding fields is backward compatible because field positions depend only on lower-numbered fields; nothing on type identity.
+
+FlatBuffers (fetched https://flatbuffers.dev/evolution/ and /schema/)
+- Field positions by declaration order or explicit `id: n` (contiguous from 0, on all fields if used). Renaming "generally OK" because names are not in the binary. `file_identifier` is exactly 4 chars at bytes 4-7; docs frame it as a file-level check and recommend unions for distinguishing messages.
+
+Thrift (fetched https://raw.githubusercontent.com/apache/thrift/master/doc/specs/thrift-binary-protocol.md)
+- Binary protocol: field header = type + field id; "the field name is not encoded". (IDL page gave nothing on omitted ids.)
+
+MessagePack-CSharp (fetched https://github.com/MessagePack-CSharp/MessagePack-CSharp, first 100k of 105k chars)
+- `[Key(int)]` on all members => array encoding; string keys => map. Keys should be sequential from 0 (gaps cost nulls); do not reuse indexes of removed members; keep obsolete members until clients update. Union keys are ints, unique, serialized as [key, object]. No type identity in the payload.
+
+Microsoft Bond (fetched https://microsoft.github.io/bond/manual/bond_cpp.html)
+- Changing field ordinals breaks wire compat; no explicit versioning; Simple JSON matches by field name so a rename breaks it. No schema hash/GUID documented there. Bebop: wiki page empty (points to docs.bebop.sh, not opened).
+
+Unison (fetched https://www.unison-lang.org/docs/the-big-idea/ and /docs/language-reference/unique-types; hash size from search summary)
+- Definitions identified by hash of syntax tree; names are "separately stored metadata"; hash excludes names (512-bit SHA3 per search summary, unopened).
+- Structural types: "Unison does not uniquely identify a type by its name"; same-shape types are the same type (Suit/Direction, four nullary constructors, interchangeable). `unique` types: compiler generates a UUID that feeds the hash, so identity becomes nominal. Which is the default keyword was not confirmed.
+
+IPLD (fetched https://ipld.io/docs/schemas/)
+- Matching is structural: "the names of types aren't expected to be found in the serialized data"; match is by structural outline. The page does not say schemas are themselves content-addressed. Versioning is left to developers; "Migrations" subpage not opened.
+
+## 2. Failure modes of purely structural identity
+
+- Unison documents it directly: structurally identical enums are one type unless declared `unique` (unison-lang.org/docs/language-reference/unique-types, fetched). Its mitigation is a per-declaration UUID mixed into the hash (identity re-nominalised).
+- Language literature (summary, pages not opened): structural typing is prone to accidental conformance/type equivalence; nominal typing prevents it at the cost of rigidity (Wikipedia "Nominal type system"; arXiv 1007.2123 lecture notes; Erlang nominals doc https://www.erlang.org/doc/system/nominals.html says nominal types exist to prevent misuse of same-structure types). TypeScript "brand" = phantom discriminator field. No serialization-specific source found.
+- Formats that avoid the collision by carrying a name or tag outside the shape: protobuf Any type URL (full name), Avro fullname in PCF, Cap'n Proto explicit IDs, Unison `unique`, MessagePack-CSharp union key ints, FlatBuffers file_identifier/unions.
+- Not found: a documented incident of two same-shape serialized types colliding under a structural id (one search, nothing).
+
+## 3. Failure modes of name-inclusive identity across languages
+
+- Protobuf: default camelCase conversion is "always valid but not necessarily unique"; proto3 compiler rejects JSON-name conflicts; serialized duplicate keys parse differently by runtime (Edition Zero design doc, summary: https://flutter.googlesource.com/third_party/protobuf/+/HEAD/docs/design/editions/edition-zero-json-handling.md). Snake_case vs camelCase JSON mismatches in practice: https://github.com/fullstorydev/grpcurl/issues/105 (summary); https://github.com/open-telemetry/opentelemetry-proto/issues/476 (summary: spec contradicted itself on camelCase vs original names). Protobuf's mitigation: parsers accept both forms.
+- Serde (fetched https://serde.rs/container-attrs.html): `rename_all` accepts lowercase, UPPERCASE, PascalCase, camelCase, snake_case; per-field `rename`.
+- Avro restricts names to `[A-Za-z_][A-Za-z0-9_]*` with case-sensitive fullname equality, so snake_case and PascalCase spellings are distinct names; renames go through aliases, which PCF drops.
+- Cap'n Proto: auto-derived IDs depend on the declaration name, so a rename without an explicit ID changes the ID.
+- Bond Simple JSON: rename breaks compatibility (name matching).
+- Local: Python/TS already convert to PascalCase to reproduce C#'s fingerprint (section 0); the fingerprint's TypeName is the CLR full name (`CultSchemaTypeNames.cs:30`) and TS throws when a codec lacks a C# type name.
+- Registry normalisation (summary): Confluent Schema Registry `normalize.schemas=true` maps semantically-equal schemas to one id (https://www.confluent.io/blog/best-practices-for-confluent-schema-registry/); sources disagree on whether JSON Schema property order is normalised.
+
+## 4. Migration precedents for changing identity derivation
+
+- Git SHA-1 -> SHA-256 (fetched https://git-scm.com/docs/hash-function-transition): per-repo format marker (`extensions.objectFormat`, `compatObjectFormat`, `repositoryFormatVersion=1` makes old git refuse); bidirectional SHA-256<->SHA-1 mapping (pack idx v3, `loose-object-idx`); four transition modes (dark launch, early, late, post); conversion at the network boundary. It is a design doc, not a statement of what has shipped.
+- IPFS CIDv0 -> CIDv1 (fetched https://docs.ipfs.tech/concepts/content-addressing/): v0 (46 chars, "Qm") and v1 (self-describing version/codec/multihash) coexist; `ipfs cid format -v 1` converts; v1->v0 only for dag-pb.
+- Docker manifest schema 1 -> 2 (summary, mirror pages unopened): digests differ per manifest format; pull-by-digest gets no translation, pull-by-tag may be translated; repush converts. https://pulp.plan.io/issues/2099.
+- Warpcast API hash v1 -> v2 (summary, https://warpcast.notion.site/Warpcast-API-Hash-Migration-Public-ccdd6de8ac604783b9596cfd623ddbac): two-week dual-hash period, then only v2.
+- Cap'n Proto explicit-ID escape hatch for renamed/moved declarations; Avro aliases as the rename bridge in resolution; MessagePack-CSharp keep-obsolete-members (all fetched, above).
+- Local: contract `supersedesSchemaIds` / `migrationFamily` (`cultcache-persistence-format.md:~140-170`) and C#/Py `CompatibleSchemaIds` exist as alias lists.
+- Not found: Unison changing its hash derivation (one search, no docs); any serialization store that switched from name-inclusive to structural ids.
+
+## Could not verify / not done
+- Cap'n Proto designer's rationale against structural hashing (not in docs; mailing list unopened).
+- Avro: whether PCF drops defaults (spec text) and any JIRA on it; spec page was summarised by the fetch model.
+- Bebop, Thrift IDL id-omission rule, Unison default struct/unique keyword, IPLD Migrations page, Edition Zero doc (summary only), Confluent blog (summary only), nominal/structural papers (titles only).
+- Rust runtime's sha256 derivation path; `document-variants-cut.md:552-555` not opened; `CompatibleSchemaIds` logic not read.
+- eureka-state worked (whoami ok); only the one ruling was queried.

docs/research/2026-10-29-presence-provider-library-split-prior-art.md

@@ -0,0 +1,28 @@
+# Prior art: presence provider as a library, launcher as a consumer
+
+Served: `cultlib-gaps:cut_spec:cut-cultnet-rs-presence-provider-a.r1` and the
+Defaulted rulings `presence-provider-network-free-core`,
+`presence-credentials-both-idunn-drivers` and `presence-provider-consumers-adopt`,
+applying the operator's `gamecult-chat:ruling:presence-one-owner-library-launcher-consumer`.
+Imagination pass, 2026-10-29, from recall of the cited manuals (not re-fetched).
+
+- libsystemd `sd_notify(3)`: a service links a small library and reports its
+  own state (READY, STATUS, WATCHDOG); programs that cannot link it use
+  `systemd-notify(1)` or a wrapper. Same split as cultnet-rs provider plus
+  idunn-launch as the sidecar consumer.
+- `sd_listen_fds_with_names(3)`: checks LISTEN_PID against the process, sets
+  close-on-exec on passed descriptors, finds them by name, and can unset the
+  LISTEN_* environment. This set is the descriptor rule the provider adopts.
+- systemd watchdog (`WATCHDOG=1` within `WatchdogSec`): the model for the
+  warming heartbeat.
+- Consul: TTL checks updated by the service through the client API, versus
+  script/HTTP checks the agent runs for services that cannot. In-process
+  versus sidecar again.
+- Kubernetes: kubelet-run probes observe from outside; readiness gates are
+  reported by the app. Idunn's route challenge is the outside observer, the
+  signed presence the app's own report.
+
+Existing copies compared: CodexConnector `src/idunn_health.rs` (two
+descriptors, strict PID check), Idunn launcher (two descriptors, no PID check),
+cultnet-ts `idunn-runtime-authority.ts` (descriptors by name, systemd private
+PID case). The provider takes the strictest union.

docs/runtime-parity-scope.md

@@ -15,6 +15,9 @@ Cross-runtime parity has three layers:
   without translation folklore.
   Every store reader refuses, by name, a header or record slot it does not
   understand (vectors: `tests/vectors/document-variants-c0`).
+  Element ids: a store that can hold them declares `cultcache.store.v3`; TypeScript,
+  Python and Rust read it and keep the header, and readers older than ids refuse it
+  (vectors: `tests/vectors/document-variants-c2a`).
   Document variants: C# resolves them (`cultcache.store.v2`); every other runtime,
   CultMesh single-file reads, the directory store and CultNet refuse a variant by name
   (vector written by C#: `tests/vectors/document-variants-c1`).
@@ -41,8 +44,8 @@ to speak CultNet or participate in CultMesh.
 | C# | Reference implementation and production game/server substrate | CultCache typed documents, CultNet schema-v0, LiteNetLib production path with adapter profile, shared transport profiles, shared RUDP socket transport, C# multi-peer RUDP listener and schema service host, C# interop RUDP serve/dial path, connected RUDP CultMesh client helpers, RUDP-backed schema-client selection for `rudp://` service endpoints, RUDP reconnect policy/controller and reconnect-loop helper, LiteNetLib client reconnect-controller adoption, schema-client transport port for service request/response clients, CultMesh node/session/catalog/stream/simulation/RUDP surfaces, authorized peer lookup | No need to abandon LiteNetLib before the CultNet adapter fully owns production service adoption |
 | Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup, shard catalogs/logs, schema-transport factory for raw client request/subscription flows, local TCP and RUDP CultMesh server listeners, Python interop RUDP serve/dial path, session/prediction/simulation fact helpers, RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe |
 | TypeScript | Node/browser-adjacent projection and interop runtime | CultCache parity tests, CultNet schema-v0 peer, advertised schema/shard catalog wire contracts plus request/sync helpers, transport profiles, TCP-framed transport port and peer helper, shared RUDP socket transport, RUDP interop serve/dial path, RUDP reconnect policy/controller, RUDP reconnect-loop helper, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup | Full C# game session/server stack |
-| Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, schema and shard catalog helpers, typed same-schema alias hydration from raw snapshots, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport, Rust interop RUDP serve/dial path, connected RUDP CultMesh client helpers, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, small CultMesh facade for schema registry, shard catalog, peer cards, authority leases, authorized peer lookup, RUDP endpoint parsing, and peer-card/authorized-peer RUDP client construction | Full CultMesh game-session/server facade or production game-session server. `packages/cultmesh-rs` now holds a Rust stream and session surface -- node, document sets, RUDP document publication, stream descriptors, negotiation, stream catalog, and shared-memory frame rings -- but no interop lane exercises it, so it carries no cross-runtime parity claim |
-| Kotlin | JVM/Android client substrate | Typed MessagePack cache, one-call typed snapshot document sync through local same-schema aliases, built-in schema catalog advertisement, schema/shard catalogs with shared schema-message transport fetch/sync helpers, authority leases, authorized peer lookup, stream catalog, branded `CultMesh` facade, WebSocket transport profile/connection helper, RUDP client/server sugar, connected RUDP CultMesh client helpers, Kotlin interop RUDP serve/dial path, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence | C# SoA store (parked at `parked/cultcache-soa`), full C# server daemon, or Unity hot-loop memory layout |
+| Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, schema and shard catalog helpers, typed hydration of raw snapshots into the receiver's own registered type for each schema id, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport, Rust interop RUDP serve/dial path, connected RUDP CultMesh client helpers, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, small CultMesh facade for schema registry, shard catalog, peer cards, authority leases, authorized peer lookup, RUDP endpoint parsing, and peer-card/authorized-peer RUDP client construction | Full CultMesh game-session/server facade or production game-session server. `packages/cultmesh-rs` now holds a Rust stream and session surface -- node, document sets, RUDP document publication, stream descriptors, negotiation, stream catalog, and shared-memory frame rings -- but no interop lane exercises it, so it carries no cross-runtime parity claim |
+| Kotlin | JVM/Android client substrate | Typed MessagePack cache, one-call typed snapshot document sync into the receiver's own registered type for the schema, built-in schema catalog advertisement, schema/shard catalogs with shared schema-message transport fetch/sync helpers, authority leases, authorized peer lookup, stream catalog, branded `CultMesh` facade, WebSocket transport profile/connection helper, RUDP client/server sugar, connected RUDP CultMesh client helpers, Kotlin interop RUDP serve/dial path, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence | C# SoA store (parked at `parked/cultcache-soa`), full C# server daemon, or Unity hot-loop memory layout |
 
 ## Evidence Gates
 

docs/semver-policy.md

@@ -26,7 +26,7 @@ caught before it ships instead of written up afterward.
 | `org.gamecult.cultlib` | Unity UPM | `scripts/build-unity-package.ps1`, consumed by git tag |
 | `org.gamecult.caching.unity` | Unity UPM | tagged directly (no build script; see "Coverage gaps") |
 | `org.gamecult.cultmath` | Unity UPM | `packages/cultmath/scripts/build-unity-package.ps1`, consumed by git tag |
-| `@gamecult/cultcache-ts` | npm | `.github/workflows/publish-packages.yml` |
+| `@gamecult/cultcache-ts` | npm | `.github/workflows/publish-packages.yml`, `workflow_dispatch` only; npm publishing is off (see "Coverage gaps") |
 | `cultcache-py` | PyPI | `.github/workflows/publish-packages.yml` |
 | `cultnet-py` | PyPI | `.github/workflows/publish-packages.yml` |
 | `cultmesh-py` | PyPI | `.github/workflows/publish-packages.yml` |
@@ -111,7 +111,7 @@ swap under "Changed" rather than "Breaking".
 
 ## Pre-1.0 packages
 
-A package at `0.y.z` (currently `org.gamecult.cultmath`, at `0.4.x`) uses the
+A package at `0.y.z` (currently `org.gamecult.cultmath`, at `0.5.x`) uses the
 standard pre-1.0 convention: `MAJOR` stays `0` during initial development, so
 `MINOR` carries what `MAJOR` means once the package reaches `1.0.0`. Concretely:
 
@@ -198,8 +198,8 @@ or a missing declaration refuses), and:
    proof: with no tag of its own prefix it is a first release. The suite test
    that pins every declared prefix guards it: each prefix is declared once, each
    workflow tag trigger must be a declared prefix, and each such package's prefix
-   must be a workflow trigger or, for the Caching Unity package the workflow does
-   not build, the prefix of tags that hold its own manifest at the tag's own
+   must be a workflow trigger or, for a package the workflow does not tag-trigger
+   (the Caching Unity package, `cultcache-ts`), the prefix of tags that hold its own manifest at the tag's own
    version, so a typo or a copied prefix fails the suite. Nothing releases
    without the suite passing; see below for how each release path runs it.
    Releases run from a full clone with every tag (`fetch-depth: 0` in CI), the
@@ -352,10 +352,40 @@ own path into the DLL. No `global.json` pins the .NET SDK, so the same refusal
 at unchanged source and CRLF checkout means this SDK or host differs from the
 one that built the tracked DLL.
 
+### Before pushing a tag
+
+A tag run uses the workflow files at the tagged commit, not the ones on main, and
+the forge's GitHub mirror forwards the tag, so both CI systems run it. Before
+pushing any tag, resolve the commit it will point at and read the tag-triggering
+workflows as they are at that commit:
+
+```
+sha=$(git rev-parse <commit-the-tag-will-point-at>)
+git ls-tree -r --name-only "$sha" .github/workflows
+git show "$sha":.github/workflows/publish-packages.yml | sed -n '/^on:/,/^jobs:/p'
+```
+
+Confirm that the tag's prefix is a trigger there if you mean it to publish, and
+is not if you do not. Do the same for every other workflow listed that has a
+`tags:` trigger. A guard merged after that commit does not protect a tag that
+points before it.
+
+`cultcache-ts-v0.15.0` was pushed on `7d292085`, which predates the guard, and
+its push started a publish run on both systems (GitHub run 42392334869, forge run
+454). The forge job log shows how it ended: the Publish step ran
+`release-after-suite.mjs`, whose `npm test` failed (11 cross-runtime tests,
+`cargo: not found` on the runner), so it printed "@gamecult/cultcache-ts's own
+tests failed; not releasing." and never reached `npm publish`. Neither
+`cultcache-ts` nor `@gamecult/cultcache-ts` exists on the npm registry
+(both return 404, checked 2026-11-08). The GitHub run's own log needs a login
+to read, so its failure cause is inferred from the identical workflow and sha.
+
 ### Coverage gaps
 
-`publish-packages.yml` only triggers on `cultcache-ts-v*`, `cultcache-py-v*`,
-`cultnet-py-v*`, and `cultmesh-py-v*` tag pushes — it does not build or gate
+`publish-packages.yml` only triggers on `cultcache-py-v*`, `cultnet-py-v*`, and
+`cultmesh-py-v*` tag pushes (`cultcache-ts-v*` is deliberately not a trigger: npm
+publishing is off until ruled on, and the cultcache-ts job runs from
+`workflow_dispatch` only, publishing nothing) — it does not build or gate
 the Unity UPM packages at all; those are consumed directly by git tag
 (`unity/org.gamecult.cultlib`, `packages/cultmath/unity/org.gamecult.cultmath`,
 `src/GameCult.Unity/Assets/Caching`), so a workflow trigger on their tags

docs/start/README.md

@@ -0,0 +1,466 @@
+# Start Here
+
+CultLib is one stack in several languages: **CultCache** (typed `.cc` persistence),
+**CultNet** (schema-v0 wire messages and transports) on top of it, and **CultMesh** (Verse
+discovery, replication, authority) on top of that. **CultMath** and **Geometry** sit beside the
+stack as portable numerics and engine-neutral geometry. The C# runtime in `src/` is the
+reference; the other runtimes keep wire parity with it.
+
+If you want typed state on disk, start with CultCache. Everything else assumes it.
+
+## Language x package
+
+A cell links a snippet that a test in this repo runs, or says **not yet**. "Package" links
+the package's own README or source, which is real but carries no tested first-call snippet from
+this page.
+
+| | CultCache | CultMath | Geometry | CultNet | CultMesh |
+| --- | --- | --- | --- | --- | --- |
+| **C#** | [first call, tested](#c-first-call) | [package](../../packages/cultmath/README.md); snippet not yet | [package](../../src/GameCult.Geometry/README.md); snippet not yet | [first call, tested](#c-cultnet-first-call); [package](../../src/GameCult.Networking) | [quickstart](../../src/GameCult.Mesh/docs/durable-node-quickstart.md); run by `scripts/verify-eve-getting-started.ps1` |
+| **TypeScript** | [first call, tested](#typescript-first-call) | not yet | not yet | [first call, tested](#typescript-cultnet-first-call); [package](../../packages/cultnet-ts/README.md) | [package](../../packages/cultmesh-ts/README.md); snippet not yet; [recipe: two-client .io game](io-game.md), tested with two live clients, browser page not yet run |
+| **Rust** | [first call, tested](#rust-first-call) | [native core](../../packages/cultmath/native/cultmath-core); snippet not yet | not yet | [first call, tested](#rust-cultnet-first-call); [package](../../packages/cultnet-rs/README.md), [examples](../../packages/cultnet-rs/examples) | [package](../../packages/cultmesh-rs); snippet not yet |
+| **Python** | [first call, tested](#python-first-call) | not yet | not yet | [first call, tested](#python-cultnet-first-call); [package](../../packages/cultnet-py/README.md) | [package](../../packages/cultmesh-py/README.md); snippet not yet |
+
+For the whole
+picture of what each piece is for, see the
+[package chooser in the top-level README](../../README.md#which-package-do-i-want).
+
+## C# first call
+
+Define a typed document, put it in a cache backed by a `.cc` file, read it back through a second
+cache. The source is
+[`tests/GameCult.Caching.Tests/FirstCallTests.cs`](../../tests/GameCult.Caching.Tests/FirstCallTests.cs),
+which is what `dotnet test tests/GameCult.Caching.Tests --filter FirstCallTests` runs, so the snippet
+cannot drift without the test failing.
+
+```csharp
+using System.Threading.Tasks;
+using GameCult.Caching;
+using GameCult.Caching.MessagePack;
+using MessagePack;
+
+[CultDocument("gamecult.first_call_item", "gamecult.first_call_item.v1")]
+[MessagePackObject]
+public sealed class Item
+{
+    [Key(0)] [CultName] public string Name = string.Empty;
+    [Key(1)] [CultIndex] public string Category = string.Empty;
+    [Key(2)] public int Value;
+}
+
+public static class FirstCall
+{
+    public static async Task<Item?> Run(string path)
+    {
+        var store = new SingleFileMessagePackBackingStore(path);
+        var cache = new CultCache();
+        cache.AddBackingStore(store);
+        var handle = await cache.AddAsync(new Item { Name = "Potion", Category = "Consumable", Value = 50 });
+        store.PushAll();                                   // write the .cc file
+
+        var reopened = new CultCache();
+        reopened.AddBackingStore(new SingleFileMessagePackBackingStore(path));
+        await reopened.PullAllBackingStoresAsync();        // read it back
+        var potion = reopened.Get<Item>(handle.Key);       // by key
+        var byName = reopened.GetByName<Item>("Potion");   // by [CultName]
+        return byName ?? potion;
+    }
+}
+```
+
+`FirstCall.Run` is the call; a second test in that file fails if the block above stops matching it. More: `src/GameCult.Caching/README.md`.
+
+## TypeScript first call
+
+Same shape in TypeScript: the document is a name, a schema id and a `parse`-able schema (zod here),
+and the `.cc` file is wire-compatible with the C# one. The source is
+[`packages/cultcache-ts/test/first-call.test.ts`](../../packages/cultcache-ts/test/first-call.test.ts),
+run by `npm test` in `packages/cultcache-ts` (or `node --test dist-test/test/first-call.test.js`
+after `tsc`).
+
+```ts
+import { z } from "zod";
+import {
+  CultCache,
+  SingleFileMessagePackBackingStore,
+  defineDocumentRegistry,
+  defineDocumentType,
+} from "@gamecult/cultcache-ts";
+
+const itemDocument = defineDocumentType({
+  type: "item",
+  schemaId: "gamecult.first_call_item.v1",
+  schemaName: "gamecult.first_call_item",
+  schemaVersion: "gamecult.first_call_item.v1",
+  schema: z.object({ name: z.string(), category: z.string(), value: z.number().int() }),
+  name: "name",
+  indexes: { category: "category" },
+});
+const registry = defineDocumentRegistry(itemDocument);
+
+async function firstCall(path: string) {
+  const cache = CultCache.builder()
+    .withRegistry(registry)
+    .withGenericStore(new SingleFileMessagePackBackingStore(path))
+    .build();
+  await cache.pullAllBackingStores();
+  await cache.put(itemDocument, "item:potion", { name: "Potion", category: "Consumable", value: 50 });
+
+  const reopened = CultCache.builder()
+    .withRegistry(registry)
+    .withGenericStore(new SingleFileMessagePackBackingStore(path))
+    .build();
+  await reopened.pullAllBackingStores();
+  const potion = reopened.get(itemDocument, "item:potion");
+  const byName = reopened.getByName(itemDocument, "Potion");
+  return { potion, byName };
+}
+```
+
+The test imports from `../src/index` where the block reads `@gamecult/cultcache-ts`; a second test in that file fails if the block stops matching the rest. More:
+`packages/cultcache-ts/README.md`.
+
+## Rust first call
+
+Same shape with `derive(DatabaseEntry)`: slots are `#[cultcache(key = N)]`, so the `.cc` payload is the
+slot-indexed array the C# runtime writes. The source is
+[`packages/cultcache-rs/tests/first_call.rs`](../../packages/cultcache-rs/tests/first_call.rs), run by
+`cargo test --test first_call` in `packages/cultcache-rs`; a second test in that file fails if the block
+below stops matching the file. The Rust runtime has no name lookup, so the read-back is by key. More:
+`packages/cultcache-rs/README.md`.
+
+```rust
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "item")]
+struct Item {
+    #[cultcache(key = 0)]
+    name: String,
+    #[cultcache(key = 1)]
+    category: String,
+    #[cultcache(key = 2, default)]
+    value: u32,
+}
+
+fn first_call() -> anyhow::Result<()> {
+    let dir = tempfile::tempdir()?;
+    let path = dir.path().join("first-call.cc");
+
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Item>()?;
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path));
+    cache.pull_all_backing_stores()?;
+    cache.put("item:potion", &Item {
+        name: "Potion".to_string(),
+        category: "Consumable".to_string(),
+        value: 50,
+    })?; // written to the .cc file before this returns
+
+    let mut reopened = CultCache::new();
+    reopened.register_entry_type::<Item>()?;
+    reopened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path));
+    reopened.pull_all_backing_stores()?; // read it back
+    let potion = reopened.get_required::<Item>("item:potion")?;
+    assert_eq!(potion.name, "Potion");
+    assert_eq!(potion.value, 50);
+    Ok(())
+}
+```
+
+## Python first call
+
+A document is a definition with an encoder and decoder; `name=` and `indexes=` register the name lookup
+and indexes. The source is
+[`packages/cultcache-py/tests/test_first_call.py`](../../packages/cultcache-py/tests/test_first_call.py),
+run by `python -m unittest tests.test_first_call` in `packages/cultcache-py` with `src` on `PYTHONPATH`
+and `msgpack` installed (the store needs it). A second test fails if the block below stops matching the
+file. More: `packages/cultcache-py/README.md`.
+
+```python
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from cultcache_py import CultCache, SingleFileMessagePackBackingStore, define_document_type
+
+
+@dataclass
+class Item:
+    name: str
+    category: str
+    value: int
+
+
+item_doc = define_document_type(
+    "item",
+    encode=lambda item: asdict(item),
+    decode=lambda raw: Item(**raw),
+    name="name",
+    indexes={"category": "category"},
+)
+
+
+def first_call() -> Item:
+    path = Path(tempfile.mkdtemp()) / "first-call.cc"
+
+    cache = (
+        CultCache.builder()
+        .register_document_type(item_doc)
+        .add_generic_store(SingleFileMessagePackBackingStore(path))
+        .build()
+    )
+    cache.pull_all_backing_stores()
+    cache.put(item_doc, "item:potion", Item("Potion", "Consumable", 50))  # written to the .cc file
+
+    reopened = (
+        CultCache.builder()
+        .register_document_type(item_doc)
+        .add_generic_store(SingleFileMessagePackBackingStore(path))
+        .build()
+    )
+    reopened.pull_all_backing_stores()  # read it back
+    assert reopened.get_by_name(item_doc, "Potion") == reopened.get_required(item_doc, "item:potion")
+    return reopened.get_required(item_doc, "item:potion")
+```
+
+## CultNet first calls
+
+CultNet is schema-v0 messages in length-prefixed frames. The first call in each runtime is the same
+shape: define a typed document, build a `cultnet.document_put_raw.v0` message carrying its MessagePack
+payload, send one frame over a loopback pipe, and apply the received message to a second cache. Each
+block is verbatim from the test that runs it; a second test in the same file fails if the block stops
+matching.
+
+### C# CultNet first call
+
+Source: [`tests/GameCult.Networking.Tests/CultNetFirstCallTests.cs`](../../tests/GameCult.Networking.Tests/CultNetFirstCallTests.cs),
+run by `dotnet test tests/GameCult.Networking.Tests --filter CultNetFirstCallTests`. More: `src/GameCult.Networking/README.md`.
+
+```csharp
+using System.Net;
+using System.Net.Sockets;
+using System.Threading.Tasks;
+using GameCult.Caching;
+using GameCult.Networking;
+using MessagePack;
+
+[CultDocument("gamecult.first_call_note", "gamecult.first_call_note.v1")]
+[MessagePackObject]
+public sealed class Note
+{
+    [Key(0)] [CultName] public string Title = string.Empty;
+    [Key(1)] public string Body = string.Empty;
+}
+
+public static class CultNetFirstCall
+{
+    public static async Task<Note?> Run()
+    {
+        var inbox = new CultCache();                            // the receiver's cache
+        var documents = new CultNetDocumentRegistry();
+        var received = new TaskCompletionSource<bool>();
+
+        // Receive: a loopback listener that applies each raw document put to the inbox.
+        using var server = new TcpFramedCultNetSchemaServer(new TcpListener(IPAddress.Loopback, 0));
+        server.OnCultNet<CultNetDocumentPutRawMessage>(async (put, peer) =>
+        {
+            await documents.ApplyRawDocumentPutMessageAsync<Note>(inbox, put);
+            received.TrySetResult(true);
+        });
+
+        // Send: a typed document as a cultnet.document_put_raw.v0 message.
+        using var client = new TcpFramedCultNetSchemaClient();
+        client.Connect("127.0.0.1", server.LocalEndPoint.Port);
+        var handle = new CultRecordHandle<Note>(new CultRecordKey("note:hello"));
+        client.SendCultNet(documents.CreateRawDocumentPutMessage(
+            "put-1", handle, new Note { Title = "Hello", Body = "sent over CultNet" }));
+
+        await received.Task.WaitAsync(TimeSpan.FromSeconds(5));
+        return inbox.Get<Note>(handle.Key);
+    }
+}
+```
+
+### TypeScript CultNet first call
+
+Source: [`packages/cultnet-ts/test/first-call.test.ts`](../../packages/cultnet-ts/test/first-call.test.ts), run by
+`npm test` in `packages/cultnet-ts` (build `packages/cultcache-ts` first: `npm run build` there). The test imports
+from `../src` where the block reads `@gamecult/cultnet-ts`. More: `packages/cultnet-ts/README.md`.
+
+```ts
+import { createServer, connect } from "node:net";
+import { z } from "zod";
+import { CultCache, defineDocumentType } from "@gamecult/cultcache-ts";
+import {
+  CultNetDocumentRegistry,
+  createTcpFramedCultNetPeer,
+  defineCultNetDocumentBinding,
+} from "@gamecult/cultnet-ts";
+
+const noteDocument = defineDocumentType({
+  type: "note",
+  schemaId: "gamecult.first_call_note.v1",
+  schemaName: "gamecult.first_call_note",
+  schemaVersion: "gamecult.first_call_note.v1",
+  schema: z.object({ title: z.string(), body: z.string() }),
+  name: "title",
+});
+const documents = new CultNetDocumentRegistry([defineCultNetDocumentBinding({ definition: noteDocument })]);
+
+async function firstCall() {
+  const options = { runtimeId: "first-call", wireContract: "cultnet.schema.v0" } as const;
+  const inbox = CultCache.builder().withDocumentType(noteDocument).build(); // the receiver's cache
+
+  // Receiver: a loopback listener whose peer applies each document put to the inbox.
+  const received = new Promise<void>((resolve, reject) => {
+    const server = createServer((socket) => {
+      const peer = createTcpFramedCultNetPeer(socket, options);
+      peer.on("invalidMessage", reject);
+      peer.on("message", async (message) => {
+        if (message.schemaVersion !== "cultnet.document_put_raw.v0") return;
+        await documents.applyRawDocumentPutMessage(inbox, message);
+        peer.close();
+        server.close();
+        resolve();
+      });
+    }).listen(0, "127.0.0.1", () => {
+      // Sender: connect, build a typed put message, send it.
+      const { port } = server.address() as { port: number };
+      const sender = createTcpFramedCultNetPeer(connect(port, "127.0.0.1"), options);
+      sender.send(
+        documents.createRawDocumentPutMessage(documents.get("note")!, "put-1", "note:hello", {
+          title: "Hello",
+          body: "sent over CultNet",
+        }),
+      );
+      received.finally(() => sender.close());
+    });
+  });
+  await received;
+  return inbox.get(noteDocument, "note:hello");
+}
+```
+
+### Rust CultNet first call
+
+Source: [`packages/cultnet-rs/tests/first_call.rs`](../../packages/cultnet-rs/tests/first_call.rs), run by
+`cargo test --test first_call` in `packages/cultnet-rs`. More: `packages/cultnet-rs/README.md`.
+
+```rust
+use std::net::{TcpListener, TcpStream};
+use std::thread;
+
+use cultnet_rs::{
+    CultNetDocumentBinding, CultNetDocumentPutOptions, CultNetDocumentRegistry, CultNetWireContract,
+    TcpFramedTransportConnection, create_tcp_framed_transport_profile,
+    decode_cultnet_message_from_slice, encode_cultnet_message_to_vec,
+};
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "note")]
+struct Note {
+    #[cultcache(key = 0)]
+    title: String,
+    #[cultcache(key = 1)]
+    body: String,
+}
+
+fn first_call() -> anyhow::Result<Note> {
+    let mut documents = CultNetDocumentRegistry::new();
+    documents.register(CultNetDocumentBinding::for_entry_with_schema_id::<Note>(
+        "gamecult.first_call_note.v1".to_string(),
+        "gamecult.first_call_note.v1".to_string(),
+    ))?;
+    let profile = |runtime_id| create_tcp_framed_transport_profile(runtime_id, Default::default());
+
+    // Receiver: a loopback listener that applies the document put it receives to its own cache.
+    let listener = TcpListener::bind("127.0.0.1:0")?;
+    let port = listener.local_addr()?.port();
+    let receiver = thread::spawn({
+        let (documents, profile) = (documents.clone(), profile("receiver"));
+        move || -> anyhow::Result<Note> {
+            let (stream, _) = listener.accept()?;
+            let frame = TcpFramedTransportConnection::new(stream, profile).receive()?;
+            let message = decode_cultnet_message_from_slice(&frame.payload, CultNetWireContract::CultNetSchemaV0)?;
+            let mut inbox = CultCache::new();
+            inbox.register_entry_type::<Note>()?;
+            documents.apply_raw_document_put_message::<Note>(&mut inbox, &message)
+        }
+    });
+
+    // Sender: build a typed put message, encode it for the wire, send one frame.
+    let put = documents.create_raw_document_put_message(
+        "put-1",
+        "note:hello",
+        &Note { title: "Hello".to_string(), body: "sent over CultNet".to_string() },
+        CultNetDocumentPutOptions::default(),
+    )?;
+    let bytes = encode_cultnet_message_to_vec(&put, CultNetWireContract::CultNetSchemaV0)?;
+    TcpFramedTransportConnection::new(TcpStream::connect(("127.0.0.1", port))?, profile("sender"))
+        .send("schema", &bytes)?;
+
+    receiver.join().expect("receiver thread")
+}
+```
+
+### Python CultNet first call
+
+Source: [`packages/cultnet-py/tests/test_first_call.py`](../../packages/cultnet-py/tests/test_first_call.py), run by
+`python -m unittest tests.test_first_call` in `packages/cultnet-py` with both `src` and `../cultcache-py/src` on
+`PYTHONPATH` and `msgpack` installed. The socket pair stands in for a TCP connection. More: `packages/cultnet-py/README.md`.
+
+```python
+import socket
+from dataclasses import asdict, dataclass
+
+from cultcache_py import CultCache, define_document_type
+from cultnet_py import (
+    apply_raw_document_record,
+    document_put_raw,
+    encode_frame,
+    parse_message,
+    read_frame,
+    schema_document_map,
+)
+
+
+@dataclass
+class Note:
+    title: str
+    body: str
+
+
+note_doc = define_document_type(
+    "note",
+    encode=lambda note: asdict(note),
+    decode=lambda raw: Note(**raw),
+    name="title",
+)
+
+
+def first_call() -> Note:
+    sender, receiver = socket.socketpair()  # an in-process pipe; use socket.create_connection for TCP
+
+    # Send: a typed document as a cultnet.document_put_raw.v0 message in one length-prefixed frame.
+    put = document_put_raw(
+        message_id="put-1",
+        key="note:hello",
+        schema_id=note_doc.catalog_entry().schema_id,
+        stored_at="2026-01-01T00:00:00Z",
+        payload=note_doc.encode_payload(Note("Hello", "sent over CultNet")),
+    )
+    sender.sendall(encode_frame(put.to_bytes()))
+
+    # Receive: read the frame, parse the message, apply its record to a second cache.
+    message = parse_message(read_frame(receiver.makefile("rb")))
+    assert message.schema_version == "cultnet.document_put_raw.v0"
+    inbox = CultCache.builder().register_document_type(note_doc).build()
+    apply_raw_document_record(inbox, schema_document_map([note_doc]), message.body["document"])
+    sender.close()
+    receiver.close()
+    return inbox.get_required(note_doc, "note:hello")
+```
+
+## Where next
+
+- Smallest durable mesh path: `src/GameCult.Mesh/docs/durable-node-quickstart.md`.
+- Application path, four chapters: `src/GameCult.Mesh/docs/getting-started/README.md`.

docs/start/io-game.md

@@ -0,0 +1,196 @@
+# Recipe: a two-client .io game over CultCache + CultMesh (TypeScript)
+
+A tiny arena. One process is the authority: it holds a single `io.arena_state` document in a CultCache
+and serves it over CultMesh. Each client discovers the authority through the Odin catalog, leases the
+document, and invokes `join`, `move` and `leave` operations. Two clients see each other join, move and
+leave because both lease the same document.
+
+## What ran, what did not
+
+| Piece | Status |
+| --- | --- |
+| Two clients, real WebSockets, real `@gamecult/cultmesh-browser` client, one arena: join, see each other, move, leave | **tested** (`arena.test.ts`) |
+| Edge clamp, and the source below matching the files that ran | **tested** |
+| Browser bundle builds and the page is served | **tested** (HTTP fetch only) |
+| The page running in a real browser, two windows | **not yet**: no browser on the host that built this recipe |
+| Run by CI / `npm run test:ts` | **not yet**: the recipe has its own `package.json` (for `ws`) outside the workspaces; run it by hand as below |
+| Authority state on disk (`.cc` file) | **not yet**: the arena cache is in memory |
+| Remote play: Odin roots and a signed route | **not yet**: the client uses `local-development` trust, loopback only |
+| Dropped players: a closed tab that never sent `leave` stays in the arena | **not yet**: operations do not carry a connection identity to the authority |
+| `CultCache` in the browser | **not yet**: the `@gamecult/cultcache-ts` entry imports Node built-ins, so the client keeps the decoded document in a variable and only `./document` is imported |
+
+No `@gamecult/cultmesh-ts` or `@gamecult/cultnet-ts` TypeScript authority server exists. The server below is the CultNet
+message handling a provider owes, written in this recipe with the `ws` package.
+
+## Run it
+
+```
+npm ci --ignore-scripts                          # repo root
+(cd packages/cultnet-ts && npm run build)        # then cultcache-ts, cultmesh-browser, same command
+cd docs/start/io-game && npm install
+npm test                                         # node --test arena.test.ts, Node 24
+node serve.ts                                    # http://127.0.0.1:8080, open it twice
+```
+
+Tested on Node v24.14, which runs `.ts` files directly (no type check; `tsc` is not part of this recipe).
+
+## schema.ts
+
+```ts
+import { defineDocumentType } from "@gamecult/cultcache-ts/document";
+
+export interface Player { x: number; y: number }
+export interface ArenaState { players: Record<string, Player> }
+
+// The one shared document: every player's position. The server owns it; clients lease it.
+export const arenaDocument = defineDocumentType({
+  type: "io.arena_state",
+  schemaId: "io.arena_state.v1",
+  schema: { parse: (value: unknown) => value as ArenaState },
+});
+
+export const arenaKey = "arena:main";
+export const verseId = "io.arena";
+export const authorityRuntimeId = "io.arena-daemon";
+export const arenaSize = 100;
+```
+
+## server.ts
+
+```ts
+import { createServer, type RequestListener, type Server } from "node:http";
+import { CultCache } from "@gamecult/cultcache-ts";
+import { defineDocumentRegistry } from "@gamecult/cultcache-ts/document";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
+import { encodeCultNetMessageForWire, parseCultNetMessage, type CultNetMessage } from "@gamecult/cultnet-ts/contracts";
+import { WebSocketServer, type WebSocket } from "ws";
+import { arenaDocument, arenaKey, arenaSize, authorityRuntimeId, verseId, type ArenaState } from "./schema.ts";
+
+const bytesToBase64 = (b: Uint8Array) => Buffer.from(b).toString("base64");
+const base64ToBytes = (s: string) => new Uint8Array(Buffer.from(s, "base64"));
+
+// One process plays both CultMesh roles: Odin (/odin tells clients where the authority is) and the authority (/mesh).
+export async function startArena(port = 0, host = "127.0.0.1", onRequest?: RequestListener) {
+  const cache = CultCache.builder().withRegistry(defineDocumentRegistry(arenaDocument)).build();
+  await cache.put(arenaDocument, arenaKey, { players: {} });
+  const http: Server = createServer(onRequest ?? ((_, res) => { res.writeHead(404).end(); }));
+  await new Promise<void>(resolve => http.listen(port, host, resolve));
+  const endpoint = `ws://${host}:${(http.address() as { port: number }).port}`;
+
+  const subscribers = new Map<WebSocket, string[]>();
+  const send = (ws: WebSocket, m: CultNetMessage) => ws.send(encodeWireValue(encodeCultNetMessageForWire(m)));
+  const record = () => ({
+    schemaId: arenaDocument.schemaId, schemaName: arenaDocument.type, schemaVersion: arenaDocument.schemaId,
+    schemaContentHash: arenaDocument.schemaId, recordKey: arenaKey, storedAt: new Date().toISOString(),
+    payloadEncoding: "messagepack" as const,
+    payload: encodeWireValue(cache.getRequired(arenaDocument, arenaKey)) as never,
+    sourceRuntimeId: authorityRuntimeId,
+  });
+  const publish = async (next: ArenaState) => {
+    await cache.put(arenaDocument, arenaKey, next);
+    for (const [ws, ids] of subscribers) for (const subscriptionId of ids) {
+      send(ws, { schemaVersion: "cultnet.database_change_raw.v0", messageId: crypto.randomUUID(), subscriptionId, changeKind: "updated", document: record() });
+    }
+  };
+
+  let nextId = 0;
+  const operations: Record<string, (p: any) => Promise<object>> = {
+    join: async () => {
+      const id = `p${++nextId}`;
+      const state = cache.getRequired(arenaDocument, arenaKey);
+      await publish({ players: { ...state.players, [id]: { x: Math.floor(Math.random() * arenaSize), y: Math.floor(Math.random() * arenaSize) } } });
+      return { id };
+    },
+    move: async ({ id, dx, dy }: { id: string; dx: number; dy: number }) => {
+      const state = cache.getRequired(arenaDocument, arenaKey);
+      const me = state.players[id];
+      if (!me) return { ok: false };
+      const clamp = (v: number) => Math.max(0, Math.min(arenaSize, v));
+      await publish({ players: { ...state.players, [id]: { x: clamp(me.x + Math.sign(dx)), y: clamp(me.y + Math.sign(dy)) } } });
+      return { ok: true };
+    },
+    leave: async ({ id }: { id: string }) => {
+      const { [id]: _gone, ...rest } = cache.getRequired(arenaDocument, arenaKey).players;
+      await publish({ players: rest });
+      return { ok: true };
+    },
+  };
+
+  const wss = new WebSocketServer({ server: http });
+  wss.on("connection", (ws, req) => {
+    const odin = req.url === "/odin";
+    ws.on("close", () => subscribers.delete(ws));
+    ws.on("message", async raw => {
+      const m = parseCultNetMessage(decodeWireValue(new Uint8Array(raw as Buffer)));
+      if (odin && m.schemaVersion === "cultmesh.verse_catalog_request.v0") {
+        send(ws, {
+          schemaVersion: "cultmesh.verse_catalog_response.v0", messageId: m.messageId,
+          verses: [{
+            verseId, displayName: "Arena", authorityModel: "ServerAuthoritative",
+            compatibility: { transportVersion: "cultmesh.v1", rulesHash: "arena-v1", compatibleVerseIds: [], requiredPluginIds: [], optionalPluginIds: [] },
+            discoveryEndpoints: [`${endpoint}/mesh`], authorityRuntimeIds: [authorityRuntimeId],
+            authorityRoutes: [{ authorityRuntimeId, endpoint: `${endpoint}/mesh`, protocolIds: ["cultmesh.documents.v1"], priority: 0, generation: "arena-1" }],
+          }],
+        });
+      } else if (m.schemaVersion === "cultmesh.session_open.v2") {
+        send(ws, { schemaVersion: "cultmesh.session_accepted.v2", messageId: m.messageId, accepted: true, verseId: m.verseId, authorityRuntimeId,
+          protocolId: m.protocolId, routeGeneration: m.routeGeneration, clientNonce: m.clientNonce, providerKeyId: "", providerSignature: "" });
+      } else if (m.schemaVersion === "cultnet.database_subscribe.v0") {
+        subscribers.set(ws, [...(subscribers.get(ws) ?? []), m.subscriptionId]);
+        send(ws, { schemaVersion: "cultnet.snapshot_response_raw.v0", messageId: m.messageId, documents: [record()] });
+      } else if (m.schemaVersion === "cultnet.database_unsubscribe.v0") {
+        subscribers.set(ws, (subscribers.get(ws) ?? []).filter(id => id !== m.subscriptionId));
+      } else if (m.schemaVersion === "cultnet.operation_request.v0") {
+        const handler = operations[m.operation];
+        const receipt = handler ? await handler(decodeWireValue(base64ToBytes(m.payload))) : undefined;
+        send(ws, {
+          schemaVersion: "cultnet.operation_response.v0", messageId: m.messageId, serviceId: m.serviceId, operation: m.operation,
+          status: handler ? "accepted" : "invalid", payloadSchema: "io.receipt.v1", payloadEncoding: "messagepack-base64",
+          payload: bytesToBase64(encodeWireValue(receipt ?? { ok: false })), sourceRuntimeId: authorityRuntimeId,
+        });
+      }
+    });
+  });
+
+  return {
+    odinUrl: `${endpoint}/odin`,
+    state: () => cache.getRequired(arenaDocument, arenaKey),
+    close: async () => { for (const c of wss.clients) c.terminate(); wss.close(); await new Promise(r => http.close(r)); },
+  };
+}
+```
+
+## client.ts
+
+```ts
+import { CultMeshBrowserClient, CultMeshBrowserOdinRendezvous, decodeCultNetOperationPayload, decodeCultNetPayload } from "@gamecult/cultmesh-browser";
+import { arenaDocument, arenaKey, authorityRuntimeId, verseId, type ArenaState } from "./schema.ts";
+
+// Runs unchanged in a browser or in Node 22+: both have a global WebSocket.
+export async function joinArena(odinUrl: string, runtimeId: string, onState: (state: ArenaState, myId: string) => void) {
+  const rendezvous = new CultMeshBrowserOdinRendezvous({ endpoints: [odinUrl], runtimeId: `${runtimeId}.discovery` });
+  const mesh = await CultMeshBrowserClient.connect({
+    verseId, authorityRuntimeId, runtimeId, rendezvous,
+    trust: { mode: "local-development" }, // loopback only; remote Verses need Odin roots
+  });
+  let latest: ArenaState | undefined; // CultCache itself pulls in Node built-ins, so the browser client keeps the decoded document
+  const call = async (operation: string, payload: object) =>
+    decodeCultNetOperationPayload<{ id?: string }>(await mesh.invoke({ serviceId: "io.arena", operation, payloadSchema: "io.request.v1", payload }));
+
+  const lease = await mesh.leaseRawDocument({ schemaId: arenaDocument.schemaId, recordKey: arenaKey });
+  const { id } = await call("join", {});
+  lease.watch(record => {
+    if (!record) return;
+    latest = decodeCultNetPayload(record, arenaDocument);
+    onState(latest, id!);
+  });
+  return {
+    id: id!,
+    move: (dx: number, dy: number) => call("move", { id, dx, dy }),
+    state: () => latest,
+    leave: async () => { await call("leave", { id }); lease.dispose(); await mesh.dispose(); },
+  };
+}
+```
+
+`browser.ts`, `index.html` and `serve.ts` in [`io-game/`](io-game/) draw the canvas and bundle the client with esbuild.

docs/start/io-game/arena.test.ts

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { joinArena } from "./client.ts";
+import { startArena } from "./server.ts";
+import { arenaSize, type ArenaState } from "./schema.ts";
+
+const until = async (cond: () => boolean) => {
+  for (let i = 0; i < 200 && !cond(); i++) await new Promise(r => setTimeout(r, 10));
+  assert.ok(cond(), "condition not reached in 2s");
+};
+
+test("two clients join one arena, see each other, and see each other move", async () => {
+  const arena = await startArena();
+  const seenByA: ArenaState[] = [];
+  const seenByB: ArenaState[] = [];
+  const a = await joinArena(arena.odinUrl, "client-a", s => seenByA.push(structuredClone(s)));
+  const b = await joinArena(arena.odinUrl, "client-b", s => seenByB.push(structuredClone(s)));
+  try {
+    assert.notEqual(a.id, b.id);
+    await until(() => Object.keys(a.state()?.players ?? {}).length === 2);
+    await until(() => Object.keys(b.state()?.players ?? {}).length === 2);
+
+    const before = structuredClone(b.state()!.players[a.id]!);
+    // Moves clamp at the arena edge, so pick a direction that always has room to move.
+    const dx = before.x > 0 ? -1 : 1;
+    await a.move(dx, 0);
+    await until(() => b.state()!.players[a.id]!.x !== before.x);
+    assert.equal(b.state()!.players[a.id]!.x, before.x + dx);
+    assert.deepEqual(a.state(), arena.state());
+    assert.deepEqual(b.state(), arena.state());
+
+    await b.leave();
+    await until(() => !(a.id !== b.id && b.id in a.state()!.players));
+    assert.deepEqual(Object.keys(a.state()!.players), [a.id]);
+  } finally {
+    await a.leave().catch(() => undefined);
+    await arena.close();
+  }
+});
+
+test("a player cannot walk out of the arena", async () => {
+  const arena = await startArena();
+  const a = await joinArena(arena.odinUrl, "client-a", () => undefined);
+  try {
+    for (let i = 0; i <= arenaSize; i++) await a.move(-1, 0);
+    assert.equal(arena.state().players[a.id]!.x, 0);
+  } finally {
+    await a.leave();
+    await arena.close();
+  }
+});
+
+test("serve.ts bundles the browser client and serves the page", async () => {
+  const { serveArena } = await import("./serve.ts");
+  const site = await serveArena(0);
+  try {
+    const html = await (await fetch(site.url)).text();
+    assert.match(html, /<canvas/);
+    const js = await (await fetch(`${site.url}/browser.js`)).text();
+    assert.match(js, /CultMeshBrowserClient/);
+  } finally {
+    await site.close();
+  }
+});
+
+test("the recipe page shows the source files verbatim", () => {
+  const page = readFileSync(new URL("../io-game.md", import.meta.url), "utf8").replace(/\r\n/g, "\n");
+  for (const file of ["schema.ts", "server.ts", "client.ts"]) {
+    const text = readFileSync(new URL(`./${file}`, import.meta.url), "utf8").replace(/\r\n/g, "\n");
+    assert.ok(page.includes(text), `docs/start/io-game.md no longer shows ${file} verbatim`);
+  }
+});

docs/start/io-game/browser.ts

@@ -0,0 +1,17 @@
+import { joinArena } from "./client.ts";
+import { arenaSize, type ArenaState } from "./schema.ts";
+
+const canvas = document.querySelector("canvas")!;
+const ctx = canvas.getContext("2d")!;
+const scale = canvas.width / arenaSize;
+
+const game = await joinArena(`ws://${location.host}/odin`, `browser-${crypto.randomUUID()}`, (state: ArenaState, me: string) => {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  for (const [id, p] of Object.entries(state.players)) {
+    ctx.fillStyle = id === me ? "#f5c542" : "#6aa9ff";
+    ctx.fillRect(p.x * scale, p.y * scale, scale * 2, scale * 2);
+  }
+});
+const keys: Record<string, [number, number]> = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
+addEventListener("keydown", e => { const d = keys[e.key]; if (d) void game.move(...d); });
+addEventListener("pagehide", () => void game.leave());

docs/start/io-game/client.ts

@@ -0,0 +1,28 @@
+import { CultMeshBrowserClient, CultMeshBrowserOdinRendezvous, decodeCultNetOperationPayload, decodeCultNetPayload } from "@gamecult/cultmesh-browser";
+import { arenaDocument, arenaKey, authorityRuntimeId, verseId, type ArenaState } from "./schema.ts";
+
+// Runs unchanged in a browser or in Node 22+: both have a global WebSocket.
+export async function joinArena(odinUrl: string, runtimeId: string, onState: (state: ArenaState, myId: string) => void) {
+  const rendezvous = new CultMeshBrowserOdinRendezvous({ endpoints: [odinUrl], runtimeId: `${runtimeId}.discovery` });
+  const mesh = await CultMeshBrowserClient.connect({
+    verseId, authorityRuntimeId, runtimeId, rendezvous,
+    trust: { mode: "local-development" }, // loopback only; remote Verses need Odin roots
+  });
+  let latest: ArenaState | undefined; // CultCache itself pulls in Node built-ins, so the browser client keeps the decoded document
+  const call = async (operation: string, payload: object) =>
+    decodeCultNetOperationPayload<{ id?: string }>(await mesh.invoke({ serviceId: "io.arena", operation, payloadSchema: "io.request.v1", payload }));
+
+  const lease = await mesh.leaseRawDocument({ schemaId: arenaDocument.schemaId, recordKey: arenaKey });
+  const { id } = await call("join", {});
+  lease.watch(record => {
+    if (!record) return;
+    latest = decodeCultNetPayload(record, arenaDocument);
+    onState(latest, id!);
+  });
+  return {
+    id: id!,
+    move: (dx: number, dy: number) => call("move", { id, dx, dy }),
+    state: () => latest,
+    leave: async () => { await call("leave", { id }); lease.dispose(); await mesh.dispose(); },
+  };
+}

docs/start/io-game/index.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>arena</title>
+<canvas width="500" height="500" style="border:1px solid #888"></canvas>
+<p>Arrow keys. Open this page in a second window.</p>
+<script type="module" src="/browser.js"></script>

docs/start/io-game/package-lock.json

@@ -0,0 +1,64 @@
+{
+  "name": "cultlib-start-io-game",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "cultlib-start-io-game",
+      "dependencies": {
+        "ws": "^8.18.0"
+      },
+      "devDependencies": {
+        "@types/ws": "^8.5.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "26.6.6",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz",
+      "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.9.0"
+      }
+    },
+    "node_modules/@types/ws": {
+      "version": "8.18.2",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.2.tgz",
+      "integrity": "sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
+      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ws": {
+      "version": "8.22.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.1.tgz",
+      "integrity": "sha512-oyL6OPYme/CmiFvNuGzeoxCJ4nOrZE2O1FwM9MWM1AsGri6nLXB2pg+lNA8aLeXMSav0J6eIVS1j6vUPzUtK9g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

docs/start/io-game/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "cultlib-start-io-game",
+  "private": true,
+  "type": "module",
+  "description": "docs/start recipe: a tiny two-client browser game over CultCache + CultMesh (TypeScript).",
+  "scripts": { "test": "node --test arena.test.ts" },
+  "dependencies": { "ws": "^8.18.0" },
+  "devDependencies": { "@types/ws": "^8.5.0" }
+}

docs/start/io-game/schema.ts

@@ -0,0 +1,16 @@
+import { defineDocumentType } from "@gamecult/cultcache-ts/document";
+
+export interface Player { x: number; y: number }
+export interface ArenaState { players: Record<string, Player> }
+
+// The one shared document: every player's position. The server owns it; clients lease it.
+export const arenaDocument = defineDocumentType({
+  type: "io.arena_state",
+  schemaId: "io.arena_state.v1",
+  schema: { parse: (value: unknown) => value as ArenaState },
+});
+
+export const arenaKey = "arena:main";
+export const verseId = "io.arena";
+export const authorityRuntimeId = "io.arena-daemon";
+export const arenaSize = 100;

docs/start/io-game/serve.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from "node:fs";
+import { build } from "esbuild";
+import { startArena } from "./server.ts";
+
+// Serves the page, the bundled browser client, and the arena's WebSocket on one port.
+export async function serveArena(port = 8080, host = "127.0.0.1") {
+  const bundle = await build({ entryPoints: [new URL("./browser.ts", import.meta.url).pathname], bundle: true, format: "esm", target: "es2022", write: false });
+  const html = readFileSync(new URL("./index.html", import.meta.url));
+  const arena = await startArena(port, host, (req, res) => {
+    if (req.url === "/") res.writeHead(200, { "content-type": "text/html" }).end(html);
+    else if (req.url === "/browser.js") res.writeHead(200, { "content-type": "text/javascript" }).end(bundle.outputFiles[0]!.contents);
+    else res.writeHead(404).end();
+  });
+  return { url: arena.odinUrl.replace("ws:", "http:").replace("/odin", ""), close: arena.close };
+}
+
+if (import.meta.main) console.log(`arena at ${(await serveArena()).url}`);

docs/start/io-game/server.ts

@@ -0,0 +1,100 @@
+import { createServer, type RequestListener, type Server } from "node:http";
+import { CultCache } from "@gamecult/cultcache-ts";
+import { defineDocumentRegistry } from "@gamecult/cultcache-ts/document";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
+import { encodeCultNetMessageForWire, parseCultNetMessage, type CultNetMessage } from "@gamecult/cultnet-ts/contracts";
+import { WebSocketServer, type WebSocket } from "ws";
+import { arenaDocument, arenaKey, arenaSize, authorityRuntimeId, verseId, type ArenaState } from "./schema.ts";
+
+const bytesToBase64 = (b: Uint8Array) => Buffer.from(b).toString("base64");
+const base64ToBytes = (s: string) => new Uint8Array(Buffer.from(s, "base64"));
+
+// One process plays both CultMesh roles: Odin (/odin tells clients where the authority is) and the authority (/mesh).
+export async function startArena(port = 0, host = "127.0.0.1", onRequest?: RequestListener) {
+  const cache = CultCache.builder().withRegistry(defineDocumentRegistry(arenaDocument)).build();
+  await cache.put(arenaDocument, arenaKey, { players: {} });
+  const http: Server = createServer(onRequest ?? ((_, res) => { res.writeHead(404).end(); }));
+  await new Promise<void>(resolve => http.listen(port, host, resolve));
+  const endpoint = `ws://${host}:${(http.address() as { port: number }).port}`;
+
+  const subscribers = new Map<WebSocket, string[]>();
+  const send = (ws: WebSocket, m: CultNetMessage) => ws.send(encodeWireValue(encodeCultNetMessageForWire(m)));
+  const record = () => ({
+    schemaId: arenaDocument.schemaId, schemaName: arenaDocument.type, schemaVersion: arenaDocument.schemaId,
+    schemaContentHash: arenaDocument.schemaId, recordKey: arenaKey, storedAt: new Date().toISOString(),
+    payloadEncoding: "messagepack" as const,
+    payload: encodeWireValue(cache.getRequired(arenaDocument, arenaKey)) as never,
+    sourceRuntimeId: authorityRuntimeId,
+  });
+  const publish = async (next: ArenaState) => {
+    await cache.put(arenaDocument, arenaKey, next);
+    for (const [ws, ids] of subscribers) for (const subscriptionId of ids) {
+      send(ws, { schemaVersion: "cultnet.database_change_raw.v0", messageId: crypto.randomUUID(), subscriptionId, changeKind: "updated", document: record() });
+    }
+  };
+
+  let nextId = 0;
+  const operations: Record<string, (p: any) => Promise<object>> = {
+    join: async () => {
+      const id = `p${++nextId}`;
+      const state = cache.getRequired(arenaDocument, arenaKey);
+      await publish({ players: { ...state.players, [id]: { x: Math.floor(Math.random() * arenaSize), y: Math.floor(Math.random() * arenaSize) } } });
+      return { id };
+    },
+    move: async ({ id, dx, dy }: { id: string; dx: number; dy: number }) => {
+      const state = cache.getRequired(arenaDocument, arenaKey);
+      const me = state.players[id];
+      if (!me) return { ok: false };
+      const clamp = (v: number) => Math.max(0, Math.min(arenaSize, v));
+      await publish({ players: { ...state.players, [id]: { x: clamp(me.x + Math.sign(dx)), y: clamp(me.y + Math.sign(dy)) } } });
+      return { ok: true };
+    },
+    leave: async ({ id }: { id: string }) => {
+      const { [id]: _gone, ...rest } = cache.getRequired(arenaDocument, arenaKey).players;
+      await publish({ players: rest });
+      return { ok: true };
+    },
+  };
+
+  const wss = new WebSocketServer({ server: http });
+  wss.on("connection", (ws, req) => {
+    const odin = req.url === "/odin";
+    ws.on("close", () => subscribers.delete(ws));
+    ws.on("message", async raw => {
+      const m = parseCultNetMessage(decodeWireValue(new Uint8Array(raw as Buffer)));
+      if (odin && m.schemaVersion === "cultmesh.verse_catalog_request.v0") {
+        send(ws, {
+          schemaVersion: "cultmesh.verse_catalog_response.v0", messageId: m.messageId,
+          verses: [{
+            verseId, displayName: "Arena", authorityModel: "ServerAuthoritative",
+            compatibility: { transportVersion: "cultmesh.v1", rulesHash: "arena-v1", compatibleVerseIds: [], requiredPluginIds: [], optionalPluginIds: [] },
+            discoveryEndpoints: [`${endpoint}/mesh`], authorityRuntimeIds: [authorityRuntimeId],
+            authorityRoutes: [{ authorityRuntimeId, endpoint: `${endpoint}/mesh`, protocolIds: ["cultmesh.documents.v1"], priority: 0, generation: "arena-1" }],
+          }],
+        });
+      } else if (m.schemaVersion === "cultmesh.session_open.v2") {
+        send(ws, { schemaVersion: "cultmesh.session_accepted.v2", messageId: m.messageId, accepted: true, verseId: m.verseId, authorityRuntimeId,
+          protocolId: m.protocolId, routeGeneration: m.routeGeneration, clientNonce: m.clientNonce, providerKeyId: "", providerSignature: "" });
+      } else if (m.schemaVersion === "cultnet.database_subscribe.v0") {
+        subscribers.set(ws, [...(subscribers.get(ws) ?? []), m.subscriptionId]);
+        send(ws, { schemaVersion: "cultnet.snapshot_response_raw.v0", messageId: m.messageId, documents: [record()] });
+      } else if (m.schemaVersion === "cultnet.database_unsubscribe.v0") {
+        subscribers.set(ws, (subscribers.get(ws) ?? []).filter(id => id !== m.subscriptionId));
+      } else if (m.schemaVersion === "cultnet.operation_request.v0") {
+        const handler = operations[m.operation];
+        const receipt = handler ? await handler(decodeWireValue(base64ToBytes(m.payload))) : undefined;
+        send(ws, {
+          schemaVersion: "cultnet.operation_response.v0", messageId: m.messageId, serviceId: m.serviceId, operation: m.operation,
+          status: handler ? "accepted" : "invalid", payloadSchema: "io.receipt.v1", payloadEncoding: "messagepack-base64",
+          payload: bytesToBase64(encodeWireValue(receipt ?? { ok: false })), sourceRuntimeId: authorityRuntimeId,
+        });
+      }
+    });
+  });
+
+  return {
+    odinUrl: `${endpoint}/odin`,
+    state: () => cache.getRequired(arenaDocument, arenaKey),
+    close: async () => { for (const c of wss.clients) c.terminate(); wss.close(); await new Promise(r => http.close(r)); },
+  };
+}

docs/write-ownership-map.md

@@ -0,0 +1,119 @@
+# Write-ownership map
+
+Imagination, 2026-10-27/28, session `self-2026-10-27c-eureka`. Base: CultLib `main` at `b7a68884` (C2a landed).
+Serves `variants:follow_up:write-ownership-cut`. Spec: `variants:cut_spec:cut-write-ownership-cs.r1`. Question:
+`variants:question:written-type-undeclared-drift`.
+
+## The rulings: what decides and what illustrates
+
+- `variants:ruling:cache-refuses-retype`. Her words decide: a stored record's schema id identifies its type, so a write of
+  another type at that key is the wrong type and is refused, by a cache exactly as by a cacheless write. Retyping is an
+  explicit remove plus add. The Household / `_pet` / rake analogy is an illustration, not a rule about object fields. Self's
+  gloss (ownership becomes per staged key) is Self's reading, not hers.
+- `variants:ruling:write-ownership-by-written-type`. Her words decide one thing: a record under the written type's own id is
+  equivalent by construction, so which type owns that id cannot change the write. The full rule ("own id or one the written
+  type declares it migrates from; anything else is refused; no registry, Shared included, and no owner/lister precedence
+  enters a write's ownership decision") is Self's reading, which she accepted in the same exchange. Her remark that ids
+  indicating structural equivalence beats demanding names match is context for the open
+  `variants:question:store-schema-id-derivation`, not a ruling here.
+- In force and touched: `variants:ruling:drift-record-write-ownership` (operator: a type that reads a record as compatible
+  drift owns it and restamps it, as 2.0.1 does), `variants:ruling:mesh-writes-bound-by-declaration`,
+  `variants:ruling:undeclared-read-only`, `variants:ruling:unheld-removal-refused-at-commit`,
+  `variants:ruling:unheld-removal-multi-store-cost-ruled`.
+
+The two Self readings disagree on one case: a record under an undeclared older id of the written schema name, read whole
+(an undeclared version bump). Literal "anything else is refused" makes it read-only; `drift-record-write-ownership` makes it
+owned. That is `variants:question:written-type-undeclared-drift`, and only the operator can settle it.
+
+## Body facts (probed at b7a68884)
+
+Probes: scratch tests in this worktree, removed. C# filtered runs on Starfire (one job each); TS and Rust on Yggdrasil
+(`ygg-verify.sh`, scratch commit `78f604fd`, not pushed to the forge); Python locally. Types A (`tests.wo_a`) and B
+(`tests.wo_b`) share one shape; N1/N2 are two versions of `tests.wo_n`, nothing declared.
+
+| Probe | C# | TypeScript | Rust | Python |
+|---|---|---|---|---|
+| P1 cache {A,B}: B at k, then A at k | **C**: B's record replaced, k now A's id | C, and **both** records live at k | C, both live at k | C, both live at k |
+| P2 cache {A} only, store holds B at k, write A at k | R `CultSchemaConflictException` (B is foreign, carried) | R at load: "No schema is registered for persisted schema id" | R at load, same | R at load: "Unknown persisted document type" |
+| P3 cacheless `WriteDocument<A>` over B, registry null / {A} / {A,B} | R / R / R | no cacheless write | no cacheless write | no cacheless write |
+| P4 cache {A,B}: remove k and upsert A at k in one batch | C (k is A's) | n/a | n/a | n/a |
+| P5 cache {A,B}: remove, then add in a second commit | C | n/a | n/a | n/a |
+| P6 N2 over an N1 record (undeclared name drift), cache {N2} / cacheless reg {N2} | C restamped / C restamped | not probed | not probed | C (cache) |
+
+What this establishes:
+
+- C#: one record per key. The only path that retypes is the cache arm (P1): `CacheBackingStore.RefuseUndeclared`
+  (`CultCache.cs:3994-4009`) and the on-disk judge (`OwnsOnDisk`, `:4731-4763`) ask `Registry.Owns(schemaId, catalog)`
+  (`:841-842`), which answers per schema id for the whole registry: any registered type declaring the id makes every
+  registered type's write to that key owned. The cacheless arm already refuses the retype (P3) but decides it through
+  `CatalogEntryLookup`'s registry half (`:596-634`) and the claimant precedence, which is what the ruling removes.
+  The judge is also per batch, not per key: the cacheless predicate's `declared` is the union over every written entry
+  (`:4752-4754`), and `UndeclaredOnDisk` memoises one answer per schema id (`:4784-4797`).
+- Retype as remove plus add already works in the cache (P4, P5); the cut adds no new primitive.
+- Directory store: its own judge (`DirectoryMessagePackBackingStore.cs:287-306`) asks `Registry.Owns` for every key,
+  upserts included. It must take the same per-key rule.
+- TypeScript, Rust, Python: records are keyed by `(type, key)` (Rust `entries: BTreeMap<(String, String), _>`,
+  `lib.rs:2659`; TS `#entryId(definition.type, key)`, `cult-cache.ts:323`; Python sorts and stores by `(type, key)`).
+  A write of A at k never meets B's record: both live at k (P1). None carries a foreign record; a store holding an
+  unregistered type does not load (P2). So no leaf has a "write meets another type's record" path to fix. Bringing the
+  ruling to the leaves first needs C#'s key identity (one record per key) and C#'s foreign carry, which are parity changes
+  of the leaves' store model, not a write-ownership rule. Owned by the new follow-up `variants:follow_up:leaf-key-identity-parity`.
+- Interop (unproven): a Python store holding A and B at k fails C# decode first on payload encoding (Python's
+  lambda-defined document wrote JSON payloads), so what C# does with two records at one key was not reached.
+
+## Model and authority table
+
+| Value | Today (b7a68884) | After the cut |
+|---|---|---|
+| May an upsert of T replace the stored record at k? | cache: `Registry.Owns(id)` (any registered type); cacheless: union of written entries' declarations plus claimant over written entries and the lent registry | **Owner: `CultDocumentRegistry.WrittenOwns(T's entry, stored id, catalog)`**, per key, both arms, both store kinds |
+| May a removal (or check) at k proceed? | cache: `Registry.Owns`; cacheless: the written-entries predicate | unchanged in kind: cache `Registry.Owns`; cacheless: owned when some entry the call writes `WrittenOwns` it (no registry) |
+| Which type reads a record (claimant precedence) | `Claimant<T>` | unchanged; read machinery only, no write asks it except through `WrittenOwns`' one-entry lookup (option `own-entry-reads-whole`) |
+| Lent registry in a cacheless write | encodes, decides copied-record v3 header, adds claimants | encodes and decides the copied-record header (`CopiedHoldIds`, `:4600-4630`); **adds no claimants** |
+| `CatalogEntryLookup` registry half (`_others`, `Other`, `Others`) | live | **deleted** |
+| `CultDocumentRegistry.Lookup` | live | **deleted** |
+| `Owns<T>`'s `mayClaim` | live | **deleted** (the lookup holds only the written entry) |
+| Foreign record at k | refused for every write | unchanged |
+
+Authority map (also in the spec):
+
+- Owner: `WrittenOwns(written, storedId, catalog)` decides whether an upsert of `written` may replace the record stored at
+  its key. Inputs: the written catalog entry, the stored record's schema id, the catalog that publishes it. Nothing else.
+- Derived: `Registry.Owns` is demoted to the removal/check rule and to load-time read-only marking; it no longer decides
+  upserts. `Claimant` is read machinery.
+- Forbidden writers: `Registry.Owns` on an upsert key; `CatalogEntryLookup` with a registry; the per-batch union `declared`;
+  the per-schema-id memo across different written entries.
+- Shared paths: cache staging (`Claim` -> `RefuseUndeclared`, `:3156`), single-file on-disk judge (`ApplyWriteSet` ->
+  `RefuseUndeclaredOnDisk`, `:4565`, `:4736`), single-file `JudgeChecks` (`:4726`, checks only), directory store judge,
+  `WriteRecord`, `WriteDocument`, unattached `PushAll`, Mesh's `WriteSingleFileDocument` and raw-payload write.
+
+## Absorb or leave
+
+- `variants:follow_up:drift-write-ownership-leaves`: **leave**, but it now waits on `leaf-key-identity-parity`. Its premise
+  (give each leaf the C# Owns rule) assumes one record per key, which no leaf has (P1). The leaf write-ownership cuts in the
+  sequence below close it together with this follow-up's leaf half.
+- `variants:follow_up:public-store-writes-behind-cache`: **leave**. It asks who may stage behind an attached cache (API
+  shape); this cut changes what any staging is judged by. No collision: direct `Push`/`CommitBatch` reach the same on-disk
+  judge, so they get the per-key rule for free. Hands must not give direct staging a different predicate.
+- `variants:follow_up:writer-dangling-link-tolerance`: **leave**. Rust/TS whole-store `push_all` reading a dangling link is
+  a reader/writer tolerance question, not ownership; this cut touches no leaf.
+
+## Deferred doc findings this cut fixes
+
+The ownership-docs rewrite in part 1 is the fix for (each resolved `Deferred` to `write-ownership-cut`):
+`variants:finding:cut-claimant-one-owner.s2.changelog-underdescribes-refusals`,
+`variants:finding:cut-claimant-one-owner.s3.changelog-misstates-subset`,
+`variants:finding:cut-claimant-one-owner.s5.refusal-list-ignores-declared-win`,
+`variants:finding:cut-claimant-one-owner.s5.shared-read-stated-as-contract`.
+Sites: `unity/org.gamecult.cultlib/CHANGELOG.md:16`, `src/GameCult.Caching/Contracts/cultcache-persistence-format.md:209-219`,
+`CultCache.cs` `WriteRecord`/`WriteDocument` registry docs (`:4476-4519`). Self closes them `Fixed` after Soul holds.
+
+## Cut sequence
+
+1. `cut-write-ownership-cs` (spec r1, admitted, blocked on `variants:question:written-type-undeclared-drift`): C# reference,
+   both arms, both store kinds, docs. Lands before the 3.0.0 release cut.
+2. `leaf-key-identity` (one per leaf, TS, Rust, Python; follow-up `leaf-key-identity-parity`): one record per key and
+   foreign carry at C# parity, with a cross-runtime vector. Not mapped.
+3. `leaf-write-ownership` (one per leaf, after 2): `WrittenOwns` per leaf; closes `drift-write-ownership-leaves`. Not mapped.
+
+Leaves ship on their own versions (cultcache-ts 0.14.2), not in the 3.0.0 Unity package, so 2 and 3 do not gate 3.0.0;
+whether they must land first is Self's call.

package-lock.json

@@ -482,6 +482,18 @@
       "resolved": "packages/cultcache-ts",
       "link": true
     },
+    "node_modules/@gamecult/cultmesh-browser": {
+      "resolved": "packages/cultmesh-browser",
+      "link": true
+    },
+    "node_modules/@gamecult/cultmesh-ts": {
+      "resolved": "packages/cultmesh-ts",
+      "link": true
+    },
+    "node_modules/@gamecult/cultnet-ts": {
+      "resolved": "packages/cultnet-ts",
+      "link": true
+    },
     "node_modules/@jsdevtools/ono": {
       "version": "7.1.3",
       "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz",
@@ -865,18 +877,6 @@
       "dev": true,
       "license": "Python-2.0"
     },
-    "node_modules/cultmesh-browser": {
-      "resolved": "packages/cultmesh-browser",
-      "link": true
-    },
-    "node_modules/cultmesh-ts": {
-      "resolved": "packages/cultmesh-ts",
-      "link": true
-    },
-    "node_modules/cultnet-ts": {
-      "resolved": "packages/cultnet-ts",
-      "link": true
-    },
     "node_modules/esbuild": {
       "version": "0.28.1",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
@@ -1184,10 +1184,11 @@
     },
     "packages/cultcache-ts": {
       "name": "@gamecult/cultcache-ts",
-      "version": "0.14.0",
+      "version": "0.15.0",
       "license": "MIT",
       "dependencies": {
         "@msgpack/msgpack": "^3.1.3",
+        "koffi": "3.3.0",
         "zod": "^3.25.76"
       },
       "devDependencies": {
@@ -1195,30 +1196,33 @@
         "typescript": "^5.9.0"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "packages/cultmesh-browser": {
-      "version": "0.3.0",
+      "name": "@gamecult/cultmesh-browser",
+      "version": "0.4.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.2.0"
+        "@gamecult/cultcache-ts": "^0.15.0",
+        "@gamecult/cultnet-ts": "^0.3.0"
       },
       "devDependencies": {
+        "@gamecult/cultmesh-ts": "^0.2.0",
         "@types/node": "^24.0.0",
         "typescript": "^5.9.0"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "packages/cultmesh-ts": {
-      "version": "0.1.1",
+      "name": "@gamecult/cultmesh-ts",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.2.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
+        "@gamecult/cultnet-ts": "^0.3.0",
         "koffi": "3.3.0"
       },
       "devDependencies": {
@@ -1227,14 +1231,15 @@
         "zod": "^3.25.76"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "packages/cultnet-ts": {
-      "version": "0.2.0",
+      "name": "@gamecult/cultnet-ts",
+      "version": "0.3.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
         "@msgpack/msgpack": "^3.1.3",
         "ajv": "^8.17.1"
       },
@@ -1245,7 +1250,7 @@
         "zod": "^3.25.76"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     }
   }

package.json

@@ -10,7 +10,7 @@
   "scripts": {
     "build:ts": "node scripts/run-typescript-workspaces.mjs build",
     "test:ts": "node scripts/run-typescript-workspaces.mjs test",
-    "test:pack:ts": "node scripts/test-typescript-package-closure.mjs",
+    "test:pack:ts": "node scripts/test-typescript-package-closure.mjs && node scripts/test-declared-dependency-ranges.mjs",
     "test:eve-browser-network": "node scripts/verify-eve-browser-network.mjs"
   },
   "devDependencies": {

packages/cultcache-py/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+### Changed
+
+- `msgpack` is a hard dependency, as `pyproject.toml` declared it. The optional-import fallbacks and the `cultcache-py[msgpack]` extra they named (which never existed) are gone: a missing msgpack is an `ImportError` at import.
+- The single-file store's `push`, `push_all` and `delete` take the cross-process lock on `<path>.lock` (flock; LockFileEx over the whole file on Windows) across the read and the replace, waiting up to `lock_timeout` seconds (30 by default, `TimeoutError` after), and exclude the C#, Rust and TypeScript runtimes' writers. The staged file is `<path>.tmp-<pid>-<uuid>`, fsynced before the replace, with a directory fsync after it off Windows. A fixed `<path>.tmp` is no longer used.
+
+### Breaking
+
+- A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
+- A write over a file the reader refuses (`StoreUnreadableError`, from `push`, `push_all` and `delete`) refuses and leaves the file as it is. A flush used to replace such a file. A write set cannot merge with a disk it cannot read, so the file is repaired or removed by its owner before the store writes again.
+- Added `StoreUnreadableError` (a `ValueError`) for a store file this runtime cannot read, and `SchemaConflictError` (a `ValueError`) for a
+  write the catalog cannot describe. A store is exactly three slots; a schema is never recovered from a record's payload.
+- The single-file writer derives the catalog from the records it writes: one entry per carried schema id, the registered entry over an
+  arrived one, written as chosen and never merged. A cache stamps a record with its registered schema's id.
+- Every registration refusal is now a `SchemaConflictError`, a `ValueError`, where it was a `CultCacheError`, a `RuntimeError`: registering a document type or a schema name twice no longer raises what `except CultCacheError` or `except RuntimeError` catches.
+- Two documents that own one schema id are refused at registration (`SchemaConflictError`). 2.0.1 accepted them. A document may still list another's id as compatible.
+- A loaded record resolves by its schema id first: the document that owns the id, else the one document that lists it as compatible; several listers and no owner refuse the record with `SchemaConflictError`. The record's type name resolves it only when its schema id names no registered document. 2.0.1 resolved by the record's type name alone.

packages/cultcache-py/src/cultcache_py/__init__.py

@@ -17,7 +17,7 @@ from .documents import (
     define_union,
 )
 from .leaves import SlotCodec
-from .stores import JsonLinesBackingStore, SingleFileMessagePackBackingStore
+from .stores import JsonLinesBackingStore, SchemaConflictError, SingleFileMessagePackBackingStore, StoreUnreadableError
 
 __all__ = [
     "BackingStore",
@@ -32,8 +32,10 @@ __all__ = [
     "JsonLinesBackingStore",
     "MAX_PAYLOAD_DEPTH",
     "MAX_SLOT_KEY",
+    "SchemaConflictError",
     "SingleFileMessagePackBackingStore",
     "SlotCodec",
+    "StoreUnreadableError",
     "UnionArm",
     "leaves",
     "database_entry_field",

packages/cultcache-py/src/cultcache_py/cache.py

@@ -7,6 +7,7 @@ from typing import Any, Callable, Generic, TypeVar
 
 from .backing_store import BackingStore, CultCacheEnvelope
 from .documents import DocumentDefinition, extract_value
+from .stores import SchemaConflictError
 
 T = TypeVar("T")
 F = TypeVar("F", bound=Callable[..., Any])
@@ -138,11 +139,28 @@ class CultCache:
         self._register_document_type(document)
 
     def _register_document_type(self, document: DocumentDefinition[Any]) -> None:
+        # Every registration refusal is a SchemaConflictError naming the new document's schema id and both schema names.
+        entry = document.catalog_entry()
+        schema_name = entry.schema_name
+
+        def refuse(registered: DocumentDefinition[Any], what: str) -> SchemaConflictError:
+            return SchemaConflictError(
+                entry.schema_id,
+                [registered.catalog_entry().schema_name, schema_name],
+                "",
+                message=f"{what} is already registered to document type {registered.type!r} and cannot also be claimed by "
+                f"{document.type!r}.",
+            )
+
         if document.type in self._state.documents:
-            raise CultCacheError(f"Document type already registered: {document.type}")
-        schema_name = document.catalog_entry().schema_name
+            raise refuse(self._state.documents[document.type], f"Document type {document.type!r}")
         if schema_name in self._state.documents_by_schema_name:
-            raise CultCacheError(f"Document schema name already registered: {schema_name}")
+            raise refuse(self._state.documents_by_schema_name[schema_name], f"Schema name {schema_name!r}")
+        # One document owns each schema id. Others may list it as compatible beside its owner: a record under the id resolves to
+        # its owner, and to a lister only when nothing owns it. Neither depends on the order documents were registered in.
+        for registered in self._state.documents.values():
+            if registered.catalog_entry().schema_id == entry.schema_id:
+                raise refuse(registered, f"Schema id {entry.schema_id!r}")
         name_extractors = dict(self._state.name_extractors)
         index_extractors = {type: dict(indexes) for type, indexes in self._state.index_extractors.items()}
         if document.name is not None:
@@ -280,6 +298,7 @@ class CultCache:
                     if envelope.key != GLOBAL_KEY:
                         loaded_legacy_global_keys[envelope.type] = envelope.key
                         envelope = replace(envelope, key=GLOBAL_KEY)
+                envelope = self._stamped(document, envelope)
                 value = document.decode_payload(envelope.payload)
                 loaded_values.setdefault(envelope.type, {})[envelope.key] = value
                 loaded_envelopes.setdefault(envelope.type, {})[envelope.key] = envelope
@@ -372,6 +391,7 @@ class CultCache:
     def put_envelope(self, document: DocumentDefinition[T], envelope: CultCacheEnvelope) -> T:
         self._assert_registered(document)
         self._check_envelope(document, envelope)
+        envelope = self._stamped(document, envelope)
         value = document.decode_payload(envelope.payload)
         self._write(document, [(envelope, value)], batch=False)
         return value
@@ -380,12 +400,21 @@ class CultCache:
     def put_envelopes(self, document: DocumentDefinition[T], envelopes: list[CultCacheEnvelope]) -> list[T]:
         self._assert_registered(document)
         values: list[T] = []
+        stamped: list[CultCacheEnvelope] = []
         for envelope in envelopes:
             self._check_envelope(document, envelope)
+            stamped.append(self._stamped(document, envelope))
             values.append(document.decode_payload(envelope.payload))
-        self._write(document, list(zip(envelopes, values)), batch=True)
+        self._write(document, list(zip(stamped, values)), batch=True)
         return values
 
+    @staticmethod
+    def _stamped(document: DocumentDefinition[Any], envelope: CultCacheEnvelope) -> CultCacheEnvelope:
+        """The record under its registered schema's id, whatever id the envelope arrived under, so the catalog entry a store
+        writes is the one its schema id names."""
+        entry = document.catalog_entry()
+        return replace(envelope, schema_id=entry.schema_id, catalog_entry=entry)
+
     @staticmethod
     def _check_envelope(document: DocumentDefinition[Any], envelope: CultCacheEnvelope) -> None:
         if envelope.type != document.type:
@@ -581,6 +610,27 @@ class CultCache:
             raise CultCacheError(f"Document type is not global: {document.type}")
 
     def _resolve_document_for_envelope(self, envelope: CultCacheEnvelope) -> DocumentDefinition[Any] | None:
+        """A record resolves by its schema id: the document that owns the id, else the one document that lists it as compatible.
+        Several listers and no owner name no single document, and the record is refused. The name its catalog carries is
+        metadata; it names a document only when the id names none (a store from a runtime whose schema ids this one cannot
+        know)."""
+        if envelope.schema_id:
+            entries = [(document, document.catalog_entry()) for document in self._state.documents.values()]
+            for document, entry in entries:
+                if entry.schema_id == envelope.schema_id:
+                    return document
+            listers = [document for document, entry in entries if envelope.schema_id in entry.compatible_schema_ids]
+            if len(listers) > 1:
+                raise SchemaConflictError(
+                    envelope.schema_id,
+                    sorted(document.catalog_entry().schema_name for document in listers),
+                    envelope.key,
+                    message=f"Schema id {envelope.schema_id!r} of record {envelope.key!r} is owned by no registered document and "
+                    f"declared compatible by several ({', '.join(sorted(document.type for document in listers))}), so it resolves "
+                    "to none. Register the document that owns the id, or declare it on one document.",
+                )
+            if listers:
+                return listers[0]
         document = self._state.documents.get(envelope.type)
         if document is not None:
             return document

packages/cultcache-py/src/cultcache_py/documents.py

@@ -6,6 +6,9 @@ from collections.abc import Mapping, Sequence, Set
 from itertools import chain
 from typing import Any, Callable, Generic, Iterable, TypeVar
 
+import msgpack
+from msgpack.exceptions import StackError as _MsgpackStackError
+
 from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember
 from .leaves import Float32, SlotCodec
 from .leaves import any as _any_leaf
@@ -24,12 +27,7 @@ or skipped, the outermost one is depth 1; depth 256 is accepted and 257 refused,
 MAX_SLOT_KEY = 65535
 """The largest slot key a record may define: the largest MessagePack array16 length."""
 
-try:
-    from msgpack.exceptions import StackError as _MsgpackStackError
-
-    _STACK_FAULTS: tuple[type[BaseException], ...] = (_MsgpackStackError,)
-except ModuleNotFoundError:
-    _STACK_FAULTS = ()
+_STACK_FAULTS: tuple[type[BaseException], ...] = (_MsgpackStackError,)
 
 
 _CONTAINERS = (Mapping, Sequence, Set)
@@ -85,22 +83,10 @@ def _json_payload_decoder(payload: bytes) -> Any:
     return json.loads(payload.decode("utf-8"))
 
 
-def _msgpack() -> Any:
-    try:
-        import msgpack  # type: ignore
-    except ModuleNotFoundError as exc:
-        raise RuntimeError(
-            "MessagePack payload encoding requires the optional 'msgpack' dependency. "
-            "Install with: python -m pip install cultcache-py[msgpack]"
-        ) from exc
-    return msgpack
-
-
 def _pack_tree(tree: Any) -> bytes:
     """The bytes of the tree the leaves produced. `packb` writes everything but a `Float32`, which it refuses with a
     TypeError; only then does an iterative walk pack each array and map header and each value, a `Float32` through a
     single-float packer."""
-    msgpack = _msgpack()
     try:
         return msgpack.packb(tree, use_bin_type=True)  # type: ignore[no-any-return]
     except TypeError:
@@ -125,13 +111,6 @@ def _pack_tree(tree: Any) -> bytes:
 
 
 def _messagepack_payload_decoder(payload: bytes) -> Any:
-    try:
-        import msgpack  # type: ignore
-    except ModuleNotFoundError as exc:
-        raise RuntimeError(
-            "MessagePack payload decoding requires the optional 'msgpack' dependency. "
-            "Install with: python -m pip install cultcache-py[msgpack]"
-        ) from exc
     return msgpack.unpackb(payload, raw=False)
 
 

packages/cultcache-py/src/cultcache_py/leaves.py

@@ -16,10 +16,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import Any, Callable, NoReturn
 
-try:
-    from msgpack import ExtType as _ExtType
-except ModuleNotFoundError:
-    _ExtType = ()  # type: ignore[assignment,misc]
+from msgpack import ExtType as _ExtType
 
 _bool, _bytes, _list, _int, _float, _str = bool, bytes, list, int, float, str
 _BYTE_LIKE = (_bytes, bytearray, memoryview)

packages/cultcache-py/src/cultcache_py/stores.py

@@ -3,9 +3,15 @@
 import base64
 import json
 import os
+import sys
 import threading
+import time
+import uuid
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Callable, TypeVar
+from typing import Any, Callable, Iterator, TypeVar
+
+import msgpack
 
 from .backing_store import (
     CultCacheEnvelope,
@@ -14,11 +20,44 @@ from .backing_store import (
 )
 
 STORE_FORMAT_VERSION = "cultcache.store.v1"
+# A store that can hold element ids. A reader older than element ids refuses this header: it would skip the id slots of a
+# nested element and rewrite the element without them. This runtime writes it back only for a store it read under it; it
+# does not decide when a document carries ids.
+STORE_FORMAT_ELEMENT_IDS = "cultcache.store.v3"
+_READABLE_STORE_FORMATS = (STORE_FORMAT_VERSION, STORE_FORMAT_ELEMENT_IDS)
 _STORE_FORMAT_PREFIX = "cultcache.store."
 _PERSISTED_RECORD_SLOTS = 4
+_LOCK_POLL_SECONDS = 0.01
+LOCK_TIMEOUT_SECONDS = 30.0
 _Contents = TypeVar("_Contents")
 
 
+class StoreUnreadableError(ValueError):
+    """A store file this runtime cannot read: not exactly one complete store (truncated, bytes after it, a missing or extra
+    slot), a header or record it does not know, or a body it cannot decode. Open, push, delete and push_all refuse a file
+    with this error, and a refused file is left as it was. The cause is `__cause__`."""
+
+    def __init__(self, path: Path, cause: BaseException) -> None:
+        super().__init__(f"CultCache store {path} is not readable: {cause}")
+        self.path = path
+
+
+class SchemaConflictError(ValueError):
+    """A write the catalog cannot describe: records of different types under one schema id, two arrived schemas that share an id
+    and disagree on the schema name, or a record no chosen entry publishes. Nothing is written. It names the id, the names
+    involved (`schema_names`) and a record key (`record_key`). A cache raises it too, with an empty record key, when a
+    document registers a schema id another registered document already carries."""
+
+    def __init__(self, schema_id: str, schema_names: list[str], record_key: str, *, message: str | None = None) -> None:
+        super().__init__(
+            message
+            or f"Schema id {schema_id!r} cannot describe record {record_key!r}: {', '.join(repr(name) for name in schema_names)}"
+        )
+        self.schema_id = schema_id
+        self.schema_names = schema_names
+        self.record_key = record_key
+
+
 class JsonLinesBackingStore:
     def __init__(self, path: str | os.PathLike[str]) -> None:
         self.path = Path(path)
@@ -83,76 +122,226 @@ class JsonLinesBackingStore:
 
 
 class SingleFileMessagePackBackingStore:
-    def __init__(self, path: str | os.PathLike[str]) -> None:
+    def __init__(self, path: str | os.PathLike[str], lock_timeout: float = LOCK_TIMEOUT_SECONDS) -> None:
         self.path = Path(path)
+        self.lock_timeout = lock_timeout
         self._lock = threading.RLock()
+        # The header this store read; a rewrite keeps it, so a store that holds element ids never sheds its marker.
+        self._format = STORE_FORMAT_VERSION
 
     def pull_all(self) -> list[CultCacheEnvelope]:
-        msgpack = self._msgpack()
         with self._lock:
             # An empty file is not a store (no writer leaves one), so it is decoded and refused.
+            # The disk decides the header: a file that is gone is not marked.
+            self._format = STORE_FORMAT_VERSION
             data = _read_store(self.path, Path.read_bytes)
             if data is None:
                 return []
-            decoded = msgpack.unpackb(data, raw=False)
-            snapshot = _decode_v1_snapshot(decoded)
-            if snapshot is not None:
-                return snapshot
-            return _decode_legacy_envelopes(decoded, msgpack)
+            try:
+                decoded = msgpack.unpackb(data, raw=False)
+                snapshot = _decode_snapshot(decoded)
+                if snapshot is not None:
+                    self._format, envelopes = snapshot
+                    return envelopes
+                return _decode_legacy_envelopes(decoded)
+            except Exception as exc:
+                raise StoreUnreadableError(self.path, exc) from exc
 
     def push(self, envelope: CultCacheEnvelope) -> None:
-        with self._lock:
-            existing = {(item.type, item.key): item for item in self.pull_all()}
-            existing[(envelope.type, envelope.key)] = envelope
-            self._replace_all(list(existing.values()))
+        with self._write_transaction():
+            self._replace_all([envelope], self.pull_all())
 
     def push_all(self, envelopes: list[CultCacheEnvelope]) -> None:
-        with self._lock:
-            existing = {(item.type, item.key): item for item in self.pull_all()}
-            for envelope in envelopes:
-                existing[(envelope.type, envelope.key)] = envelope
-            self._replace_all(list(existing.values()))
+        with self._write_transaction():
+            self._replace_all(list(envelopes), self.pull_all())
 
     def delete(self, type: str, key: str) -> None:
+        with self._write_transaction():
+            self._replace_all([], [item for item in self.pull_all() if not (item.type == type and item.key == key)])
+
+    @contextmanager
+    def _write_transaction(self) -> Iterator[None]:
+        """The thread lock, then the cross-process lock on `<path>.lock`, held across the read and the replace so two
+        processes never rewrite from the same stale read."""
         with self._lock:
-            existing = [item for item in self.pull_all() if not (item.type == type and item.key == key)]
-            self._replace_all(existing)
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with store_write_lock(self.path, self.lock_timeout):
+                yield
 
-    def _replace_all(self, envelopes: list[CultCacheEnvelope]) -> None:
-        msgpack = self._msgpack()
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        temp = self.path.with_suffix(self.path.suffix + ".tmp")
-        temp.write_bytes(msgpack.packb(_encode_v1_snapshot(envelopes), use_bin_type=True))
-        temp.replace(self.path)
-
-    @staticmethod
-    def _msgpack() -> Any:
-        try:
-            import msgpack  # type: ignore
-        except ModuleNotFoundError as exc:
-            raise RuntimeError(
-                "SingleFileMessagePackBackingStore requires the optional 'msgpack' dependency. "
-                "Install with: python -m pip install cultcache-py[msgpack]"
-            ) from exc
-        return msgpack
+    def _replace_all(self, supplied: list[CultCacheEnvelope], arrived: list[CultCacheEnvelope]) -> None:
+        commit_store_file(self.path, msgpack.packb(_encode_snapshot(supplied, arrived, self._format), use_bin_type=True))
 
 
-def _encode_v1_snapshot(envelopes: list[CultCacheEnvelope]) -> list[Any]:
-    catalog_by_schema_id: dict[str, CultCacheSchemaCatalogEntry] = {}
-    for envelope in envelopes:
+
+def canonical(candidates: Any) -> list[CultCacheSchemaCatalogEntry]:
+    """Entries that tie, in one fixed order, so the catalog does not depend on the order they arrive in."""
+    return sorted(candidates, key=lambda entry: (entry.schema_name, entry.content_hash, ",".join(entry.compatible_schema_ids)))
+
+
+def _derive_catalog(records: list[tuple[CultCacheEnvelope, bool]]) -> list[CultCacheSchemaCatalogEntry]:
+    """The catalog a write leaves, derived from the records being written and nothing else. For each schema id a record carries,
+    one entry that publishes it: the entry that owns the id (a registered one, else one that arrived with the records), else one
+    that lists it as compatible (registered first). Entries are written as chosen, never merged; a registered entry wins over an
+    arrived one with the same own id. Records of different types under one id, two arrived entries with the same own id and
+    different schema names, or a record no chosen entry publishes, refuse the write. `records` are (envelope, registered): an
+    envelope the caller supplied is registered, one read back from the file is arrived."""
+    entries: list[tuple[CultCacheSchemaCatalogEntry, bool]] = []
+    by_id: dict[str, list[CultCacheEnvelope]] = {}
+    tiers: dict[str, list[tuple[CultCacheEnvelope, bool, CultCacheSchemaCatalogEntry]]] = {}
+    for envelope, registered in records:
         schema_id = _schema_id_for(envelope)
-        if schema_id not in catalog_by_schema_id:
-            catalog_by_schema_id[schema_id] = envelope.catalog_entry or _default_catalog_entry(envelope)
+        supplied = envelope.catalog_entry
+        publishes = supplied is not None and (supplied.schema_id == schema_id or schema_id in supplied.compatible_schema_ids)
+        entry = supplied if publishes else _default_catalog_entry(envelope)
+        entries.append((entry, registered))
+        by_id.setdefault(schema_id, []).append(envelope)
+        tiers.setdefault(schema_id, []).append((envelope, registered, entry))
 
+    chosen: dict[str, tuple[CultCacheSchemaCatalogEntry, bool]] = {}
+    for schema_id in sorted(by_id):
+        carrying = by_id[schema_id]
+        record_key = min(envelope.key for envelope in carrying)
+        # Records of one tier under one id are one type. Across tiers the id keeps the type its records resolve to, so a write may
+        # not retype records that are already there: unless the entries of both tiers own the id, which is a rename of the schema
+        # under a stable id, and the registered descriptor wins. A read-back record's type is its schema's name, so tiers compare
+        # the names of the entries that publish the id.
+        for tier in (True, False):
+            types = sorted({envelope.type for envelope, registered, _ in tiers[schema_id] if registered == tier})
+            if len(types) > 1:
+                raise SchemaConflictError(schema_id, types, record_key)
+        registered_names = sorted({entry.schema_name for _, registered, entry in tiers[schema_id] if registered})
+        arrived_names = sorted({entry.schema_name for _, registered, entry in tiers[schema_id] if not registered})
+        owned_by = lambda tier: any(entry.schema_id == schema_id for _, registered, entry in tiers[schema_id] if registered == tier)
+        if registered_names and arrived_names and registered_names[0] != arrived_names[0] and not (owned_by(True) and owned_by(False)):
+            raise SchemaConflictError(schema_id, sorted([registered_names[0], arrived_names[0]]), record_key)
+        own_registered = next(iter(canonical(entry for entry, registered in entries if registered and entry.schema_id == schema_id)), None)
+        own_arrived = canonical(entry for entry, registered in entries if not registered and entry.schema_id == schema_id)
+        own_registered_all = canonical(entry for entry, registered in entries if registered and entry.schema_id == schema_id)
+        # Entries of one tier that share an own id must be one schema; a registered entry settles a disagreement among arrived ones.
+        names = sorted({entry.schema_name for entry in (own_registered_all or own_arrived)})
+        if len(names) > 1:
+            raise SchemaConflictError(schema_id, names, record_key)
+        if own_registered is not None:
+            pick, registered_pick = own_registered, True
+        elif own_arrived:
+            pick, registered_pick = own_arrived[0], False
+        else:
+            listed_registered = next(iter(canonical(entry for entry, registered in entries if registered and schema_id in entry.compatible_schema_ids)), None)
+            listed_arrived = next(iter(canonical(entry for entry, registered in entries if not registered and schema_id in entry.compatible_schema_ids)), None)
+            pick = listed_registered if listed_registered is not None else listed_arrived
+            registered_pick = listed_registered is not None
+        if pick is None:
+            continue
+        prior = chosen.get(pick.schema_id)
+        if prior is not None and prior[1] and not registered_pick:
+            continue
+        chosen[pick.schema_id] = (pick, registered_pick)
+
+    for schema_id in sorted(by_id):
+        if not any(entry.schema_id == schema_id or schema_id in entry.compatible_schema_ids for entry, _ in chosen.values()):
+            raise SchemaConflictError(
+                schema_id, sorted(entry.schema_name for entry, _ in chosen.values()), min(envelope.key for envelope in by_id[schema_id])
+            )
+    return [entry for entry, _ in chosen.values()]
+
+
+def _encode_snapshot(
+    supplied: list[CultCacheEnvelope], arrived: list[CultCacheEnvelope], format_version: str
+) -> list[Any]:
+    replaced = {(envelope.type, envelope.key) for envelope in supplied}
+    kept = [envelope for envelope in arrived if (envelope.type, envelope.key) not in replaced]
+    envelopes = [*kept, *supplied]
     catalog = [
         _encode_catalog_entry(entry)
-        for entry in sorted(catalog_by_schema_id.values(), key=lambda item: item.schema_name)
+        for entry in sorted(
+            _derive_catalog([*((envelope, False) for envelope in kept), *((envelope, True) for envelope in supplied)]),
+            key=lambda item: (item.schema_name, item.schema_id),
+        )
     ]
     records = [
         [envelope.key, _schema_id_for(envelope), envelope.stored_at, envelope.payload]
         for envelope in sorted(envelopes, key=lambda item: item.key)
     ]
-    return [STORE_FORMAT_VERSION, catalog, records]
+    return [format_version, catalog, records]
+
+def commit_store_file(path: Path, data: bytes) -> None:
+    """Writes `data` to a unique staged file beside the store, fsyncs it, replaces the store with it and, off Windows,
+    fsyncs the directory so the replace is durable. A failure before the replace removes the staged file and leaves the
+    store untouched. The caller holds the store lock."""
+    staged = path.with_name(f"{path.name}.tmp-{os.getpid()}-{uuid.uuid4().hex}")
+    try:
+        fd = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o666)
+        try:
+            view = memoryview(data)
+            while view:
+                view = view[os.write(fd, view):]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(staged, path)
+    except BaseException:
+        try:
+            os.unlink(staged)
+        except OSError:
+            pass
+        raise
+    if sys.platform != "win32":
+        directory = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+
+
+@contextmanager
+def store_write_lock(path: Path, timeout: float = LOCK_TIMEOUT_SECONDS) -> Iterator[None]:
+    """Holds the exclusive store lock on `<path>.lock`, the lock the C#, Rust and TypeScript runtimes take: flock on Unix,
+    LockFileEx over the whole file on Windows, polled every 10 ms with no handle held between polls. The lock file is
+    created if absent and never written or deleted."""
+    lock_path = path.with_name(path.name + ".lock")
+    deadline = time.monotonic() + timeout
+    while True:
+        release = _try_lock(lock_path)
+        if release is not None:
+            break
+        if time.monotonic() >= deadline:
+            raise TimeoutError(f"CultCache timed out after {timeout} s waiting for the store lock {lock_path}.")
+        time.sleep(_LOCK_POLL_SECONDS)
+    try:
+        yield
+    finally:
+        release()
+
+
+def _try_lock(lock_path: Path) -> Callable[[], None] | None:
+    if sys.platform == "win32":
+        return _try_lock_windows(lock_path)
+    import fcntl
+
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o666)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        os.close(fd)
+        return None
+    return lambda: os.close(fd)  # closing drops the flock
+
+
+def _try_lock_windows(lock_path: Path) -> Callable[[], None] | None:
+    import ctypes
+    import msvcrt
+    from ctypes import wintypes
+
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel.LockFileEx.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p]
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT | os.O_BINARY, 0o666)
+    handle = msvcrt.get_osfhandle(fd)
+    overlapped = ctypes.create_string_buffer(32)
+    # LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY over the whole range, as the TypeScript runtime takes it.
+    if not kernel.LockFileEx(handle, 0x3, 0, 0xFFFFFFFF, 0xFFFFFFFF, overlapped):
+        os.close(fd)
+        return None
+    return lambda: os.close(fd)  # closing drops the lock
 
 
 def _read_store(path: Path, read: Callable[[Path], _Contents]) -> _Contents | None:
@@ -186,25 +375,29 @@ def _describe_header(header: str) -> str:
     return f"an unrecognised {_STORE_FORMAT_PREFIX}* header of {len(header.encode('utf-8'))} bytes"
 
 
-def _decode_v1_snapshot(decoded: Any) -> list[CultCacheEnvelope] | None:
+def _decode_snapshot(decoded: Any) -> tuple[str, list[CultCacheEnvelope]] | None:
     if not isinstance(decoded, list) or not decoded:
         return None
-    if isinstance(decoded[0], str) and decoded[0].startswith(_STORE_FORMAT_PREFIX) and decoded[0] != STORE_FORMAT_VERSION:
+    if isinstance(decoded[0], str) and decoded[0].startswith(_STORE_FORMAT_PREFIX) and decoded[0] not in _READABLE_STORE_FORMATS:
         raise ValueError(
             f"CultCache store format {_describe_header(decoded[0])} is not one this runtime reads; "
-            f"it reads {STORE_FORMAT_VERSION!r} only"
+            f"it reads {STORE_FORMAT_VERSION!r} and {STORE_FORMAT_ELEMENT_IDS!r} only"
         )
-    if decoded[0] != STORE_FORMAT_VERSION:
+    if decoded[0] not in _READABLE_STORE_FORMATS:
         return None
-    if len(decoded) < 3 or not isinstance(decoded[1], list) or not isinstance(decoded[2], list):
+    if len(decoded) != 3:
+        raise ValueError(f"CultCache store has {len(decoded)} top-level slots; this runtime reads 3 (header, schema catalog, records)")
+    if not isinstance(decoded[1], list) or not isinstance(decoded[2], list):
         raise ValueError("CultCache v1 snapshot must contain a schema catalog and record array")
 
+    # An id names the entry that owns it; only an id no entry owns names the entry that lists it as compatible.
+    entries = [_decode_catalog_entry(raw_entry) for raw_entry in decoded[1]]
     catalog_by_schema_id: dict[str, CultCacheSchemaCatalogEntry] = {}
-    for raw_entry in decoded[1]:
-        entry = _decode_catalog_entry(raw_entry)
-        catalog_by_schema_id[entry.schema_id] = entry
+    for entry in entries:
+        catalog_by_schema_id.setdefault(entry.schema_id, entry)
+    for entry in entries:
         for compatible_schema_id in entry.compatible_schema_ids:
-            catalog_by_schema_id[compatible_schema_id] = entry
+            catalog_by_schema_id.setdefault(compatible_schema_id, entry)
 
     envelopes: list[CultCacheEnvelope] = []
     for raw_record in decoded[2]:
@@ -225,19 +418,7 @@ def _decode_v1_snapshot(decoded: Any) -> list[CultCacheEnvelope] | None:
             raise ValueError("CultCache persisted records must declare storedAt")
         catalog_entry = catalog_by_schema_id.get(schema_id)
         if catalog_entry is None:
-            schema_version = _infer_schema_version_from_payload(_normalize_payload(payload))
-            schema_name = _infer_schema_name(schema_version) if schema_version is not None else None
-            if schema_name is None:
-                raise ValueError(f'CultCache persisted record "{key}" references missing schema id "{schema_id}"')
-            catalog_entry = CultCacheSchemaCatalogEntry(
-                schema_id=schema_id,
-                schema_name=schema_name,
-                schema_version=schema_version,
-                content_hash=schema_id,
-                canonical_schema_json="",
-                compatible_schema_ids=(),
-                members=(),
-            )
+            raise ValueError(f"CultCache persisted record '{key}' references schema id '{schema_id}', which the store's catalog does not publish")
         normalized_payload = _normalize_payload(payload)
         envelopes.append(
             CultCacheEnvelope(
@@ -249,10 +430,10 @@ def _decode_v1_snapshot(decoded: Any) -> list[CultCacheEnvelope] | None:
                 catalog_entry=catalog_entry,
             )
         )
-    return envelopes
+    return decoded[0], envelopes
 
 
-def _decode_legacy_envelopes(decoded: Any, msgpack: Any) -> list[CultCacheEnvelope]:
+def _decode_legacy_envelopes(decoded: Any) -> list[CultCacheEnvelope]:
     if not isinstance(decoded, list):
         raise ValueError("CultCache MessagePack store is not a recognized snapshot")
     envelopes: list[CultCacheEnvelope] = []
@@ -376,27 +557,3 @@ def _normalize_payload(payload: Any) -> bytes:
     if isinstance(payload, list) and all(isinstance(item, int) and 0 <= item <= 255 for item in payload):
         return bytes(payload)
     raise ValueError("CultCache record payload must be binary MessagePack bytes")
-
-
-def _infer_schema_version_from_payload(payload: bytes) -> str | None:
-    try:
-        msgpack = SingleFileMessagePackBackingStore._msgpack()
-        decoded = msgpack.unpackb(payload, raw=False)
-    except Exception:
-        return None
-    if isinstance(decoded, list) and decoded and isinstance(decoded[0], str):
-        return decoded[0]
-    if isinstance(decoded, dict):
-        value = decoded.get("schemaVersion", decoded.get("schema_version"))
-        return value if isinstance(value, str) else None
-    return None
-
-
-def _infer_schema_name(schema_version: str) -> str | None:
-    marker = schema_version.rfind(".v")
-    if marker <= 0:
-        return None
-    version = schema_version[marker + 2:]
-    if not version or not version.isdigit():
-        return None
-    return schema_version[:marker]

packages/cultcache-py/tests/test_cultcache.py

@@ -12,6 +12,7 @@ from cultcache_py import (
     CultCache,
     JsonLinesBackingStore,
     SingleFileMessagePackBackingStore,
+    StoreUnreadableError,
     define_database_entry_type,
     define_document_type,
 )
@@ -186,7 +187,7 @@ class CultCacheTests(unittest.TestCase):
             self.assertEqual(raw[2][0][0], "app")
             self.assertEqual(raw[2][0][1], "settings")
 
-    def test_messagepack_store_recovers_schema_stamped_record_missing_catalog_entry(self) -> None:
+    def test_messagepack_store_refuses_a_record_whose_schema_the_catalog_does_not_publish(self) -> None:
         try:
             import msgpack  # type: ignore
         except ModuleNotFoundError:
@@ -227,11 +228,490 @@ class CultCacheTests(unittest.TestCase):
                 .build()
             )
 
-            cache.pull_all_backing_stores()
-            self.assertEqual(cache.get_required(document, "record-1")["value"], "still readable")
-            envelope = cache.get_required_envelope(document, "record-1")
-            self.assertEqual(envelope.type, "runtime-policy")
-            self.assertEqual(envelope.schema_id, "sha256:stale-schema-id-from-cold-record")
+            # The payload opens with a schema version, and the catalog is the store's own description: no recovery.
+            with self.assertRaises(StoreUnreadableError):
+                cache.pull_all_backing_stores()
+
+    def _foreign_id_document(self):
+        return define_database_entry_type(
+            "tests.foreign-id",
+            [("name", 0)],
+            schema_id="tests.foreign-id.current",
+            schema_name="tests.foreign-id",
+            schema_version="tests.foreign_id.v1",
+            compatible_schema_ids=["tests.foreign-id.current", "tests.foreign-id.older"],
+        )
+
+    def _open_foreign_id_store(self, document, path: Path) -> CultCache:
+        cache = CultCache.builder().register_document_type(document).add_generic_store(
+            SingleFileMessagePackBackingStore(path)
+        ).build()
+        cache.pull_all_backing_stores()
+        return cache
+
+    # A record put under an id its schema only lists as compatible is stamped with the registered id, and the store the write
+    # leaves opens and takes the next write.
+    def test_put_envelope_under_a_compatible_schema_id_writes_a_store_that_reopens(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import CultCacheSchemaCatalogEntry
+
+        document = self._foreign_id_document()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            cache = self._open_foreign_id_store(document, path)
+            payload = document.encode_payload({"name": "foreign"})
+            foreign_entry = CultCacheSchemaCatalogEntry(
+                schema_id="tests.foreign-id.older",
+                schema_name="tests.foreign-id",
+                schema_version="tests.foreign_id.v1",
+                content_hash="tests.foreign-id.older",
+                canonical_schema_json="",
+                compatible_schema_ids=("tests.foreign-id.older",),
+                members=(),
+            )
+            cache.put_envelope(
+                document,
+                CultCacheEnvelope(
+                    key="foreign",
+                    type="tests.foreign-id",
+                    payload=payload,
+                    stored_at="2026-09-30T00:00:00Z",
+                    schema_id="tests.foreign-id.older",
+                    catalog_entry=foreign_entry,
+                ),
+            )
+            stored = msgpack.unpackb(path.read_bytes(), raw=False)
+            self.assertEqual([entry[0] for entry in stored[1]], ["tests.foreign-id.current"])
+            self.assertEqual(stored[2][0][1], "tests.foreign-id.current")
+            reopened = self._open_foreign_id_store(document, path)
+            self.assertEqual(reopened.get_required(document, "foreign")["name"], "foreign")
+            reopened.put(document, "next", {"name": "next"})
+            self.assertEqual(self._open_foreign_id_store(document, path).get_required(document, "next")["name"], "next")
+
+    def test_the_store_publishes_a_records_schema_id_even_when_the_envelopes_catalog_entry_does_not(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import CultCacheSchemaCatalogEntry
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            store = SingleFileMessagePackBackingStore(path)
+            store.push(CultCacheEnvelope(
+                key="k",
+                type="tests.store-publishes",
+                payload=msgpack.packb({"name": "k"}, use_bin_type=True),
+                stored_at="2026-09-30T00:00:00Z",
+                schema_id="tests.store-publishes.record",
+                catalog_entry=CultCacheSchemaCatalogEntry(
+                    schema_id="tests.store-publishes.other",
+                    schema_name="tests.store-publishes",
+                    schema_version="tests.store_publishes.v1",
+                    content_hash="tests.store-publishes.other",
+                    canonical_schema_json="",
+                    compatible_schema_ids=("tests.store-publishes.other",),
+                    members=(),
+                ),
+            ))
+            stored = msgpack.unpackb(path.read_bytes(), raw=False)
+            self.assertEqual(stored[2][0][1], "tests.store-publishes.record")
+            self.assertEqual([entry[0] for entry in stored[1]], ["tests.store-publishes.record"])
+            self.assertEqual(len(SingleFileMessagePackBackingStore(path).pull_all()), 1)
+
+    # The catalog a write leaves is derived from its records: one entry per carried id, chosen and never merged, the same whatever
+    # order the records arrive in. A registered (supplied) entry wins over an arrived (read back) entry with the same own id.
+    @staticmethod
+    def _writer_entry(schema_id: str, name: str, content_hash: str, compatible: tuple[str, ...]):
+        from cultcache_py import CultCacheSchemaCatalogEntry
+
+        return CultCacheSchemaCatalogEntry(
+            schema_id=schema_id, schema_name=name, schema_version=name + ".v1", content_hash=content_hash,
+            canonical_schema_json="", compatible_schema_ids=compatible, members=(),
+        )
+
+    def _writer_record(self, key: str, type: str, schema_id: str, catalog_entry=None) -> CultCacheEnvelope:
+        import msgpack  # type: ignore
+
+        return CultCacheEnvelope(
+            key=key, type=type, payload=msgpack.packb({"key": key}, use_bin_type=True),
+            stored_at="2026-09-30T00:00:00Z", schema_id=schema_id, catalog_entry=catalog_entry,
+        )
+
+    @staticmethod
+    def _raw_entry(entry) -> list:
+        return [entry.schema_id, entry.schema_name, entry.schema_version, entry.content_hash, "", list(entry.compatible_schema_ids), []]
+
+    def test_a_registered_entry_is_written_as_it_is_over_the_arrived_entries_with_the_same_own_id_in_either_order(self) -> None:
+        import msgpack  # type: ignore
+
+        stale1 = self._writer_entry("tests.x", "tests.n", "a-stale-1", ("tests.x", "old"))
+        stale2 = self._writer_entry("tests.x", "tests.n", "a-stale-2", ("tests.x",))
+        registered = self._writer_record("a", "tests.n", "tests.x", self._writer_entry("tests.x", "tests.n", "fresh", ("tests.x",)))
+        for entries in ([stale1, stale2], [stale2, stale1]):
+            with tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.msgpack"
+                path.write_bytes(msgpack.packb([
+                    "cultcache.store.v1", [self._raw_entry(entry) for entry in entries],
+                    [["b", "tests.x", "2026-09-30T00:00:00Z", msgpack.packb({"b": 1}, use_bin_type=True)]],
+                ], use_bin_type=True))
+                SingleFileMessagePackBackingStore(path).push(registered)
+                catalog = msgpack.unpackb(path.read_bytes(), raw=False)[1]
+                self.assertEqual(len(catalog), 1)
+                self.assertEqual(catalog[0][3], "fresh")
+                self.assertEqual(catalog[0][5], ["tests.x"], "written as chosen, no union with the arrived entries' ids")
+
+    def test_a_rename_with_a_stable_schema_id_a_whole_view_write_names_the_registered_schema(self) -> None:
+        import msgpack  # type: ignore
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1", [self._raw_entry(self._writer_entry("tests.x", "tests.old", "stale", ("tests.x",)))],
+                [["a", "tests.x", "2026-09-30T00:00:00Z", msgpack.packb({"a": 1}, use_bin_type=True)]],
+            ], use_bin_type=True))
+            SingleFileMessagePackBackingStore(path).push_all(
+                [self._writer_record("a", "tests.old", "tests.x", self._writer_entry("tests.x", "tests.new", "fresh", ("tests.x",)))]
+            )
+            catalog = msgpack.unpackb(path.read_bytes(), raw=False)[1]
+            self.assertEqual([(entry[1], entry[3]) for entry in catalog], [("tests.new", "fresh")])
+
+    def test_two_entries_of_one_tier_that_share_an_own_id_and_disagree_on_the_schema_name_refuse_the_write_typed(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        first = self._writer_record("b", "tests.first", "tests.x", self._writer_entry("tests.x", "tests.first", "h1", ("tests.x",)))
+        second = self._writer_record("a", "tests.first", "tests.x", self._writer_entry("tests.x", "tests.second", "h2", ("tests.x",)))
+        for order in ([first, second], [second, first]):
+            with tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.msgpack"
+                with self.assertRaises(SchemaConflictError) as refused:
+                    SingleFileMessagePackBackingStore(path).push_all(order)
+                self.assertEqual(refused.exception.schema_id, "tests.x")
+                self.assertEqual(refused.exception.record_key, "a")
+                self.assertEqual(refused.exception.schema_names, ["tests.first", "tests.second"])
+                self.assertFalse(path.exists())
+
+    def test_records_of_different_types_under_one_schema_id_refuse_the_write_typed_and_no_record_changes_type(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        a = self._writer_record("a", "tests.n", "tests.y", self._writer_entry("tests.x", "tests.n", "h1", ("tests.x", "tests.y")))
+        b = self._writer_record("b", "tests.m", "tests.y", self._writer_entry("tests.y", "tests.m", "h2", ("tests.y",)))
+        for order in ([a, b], [b, a]):
+            with tempfile.TemporaryDirectory() as tmp:
+                with self.assertRaises(SchemaConflictError) as refused:
+                    SingleFileMessagePackBackingStore(Path(tmp) / "store.msgpack").push_all(order)
+                self.assertEqual(refused.exception.schema_id, "tests.y")
+                self.assertEqual(refused.exception.schema_names, ["tests.m", "tests.n"])
+
+    def test_an_entry_that_owns_an_id_is_chosen_over_one_that_lists_it(self) -> None:
+        import msgpack  # type: ignore
+
+        owner = self._writer_record("a", "tests.n", "tests.y", self._writer_entry("tests.y", "tests.n", "h1", ("tests.y",)))
+        lister = self._writer_record("b", "tests.n", "tests.x", self._writer_entry("tests.x", "tests.n", "h2", ("tests.x", "tests.y")))
+        for order in ([lister, owner], [owner, lister]):
+            with tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.msgpack"
+                SingleFileMessagePackBackingStore(path).push_all(order)
+                catalog = msgpack.unpackb(path.read_bytes(), raw=False)[1]
+                self.assertEqual(sorted((entry[0], entry[5]) for entry in catalog), [("tests.x", ["tests.x", "tests.y"]), ("tests.y", ["tests.y"])])
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            SingleFileMessagePackBackingStore(path).push_all([owner])
+            self.assertEqual([entry[0] for entry in msgpack.unpackb(path.read_bytes(), raw=False)[1]], ["tests.y"])
+
+    def test_entries_of_one_tier_that_tie_are_taken_in_one_fixed_order_and_a_registered_lister_beats_an_arrived_one(self) -> None:
+        import msgpack  # type: ignore
+
+        # The content hash orders them against the order their compatible ids would give: h1 sorts first, its list sorts last.
+        one = self._writer_record("a", "tests.n", "tests.x", self._writer_entry("tests.x", "tests.n", "h2", ("tests.x",)))
+        two = self._writer_record("b", "tests.n", "tests.x", self._writer_entry("tests.x", "tests.n", "h1", ("tests.x", "tests.y")))
+        for order in ([one, two], [two, one]):
+            with tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.msgpack"
+                SingleFileMessagePackBackingStore(path).push_all(order)
+                self.assertEqual([entry[3] for entry in msgpack.unpackb(path.read_bytes(), raw=False)[1]], ["h1"])
+
+        # z sits under old, which the arrived entry (id x) lists; the supplied entry (id r) lists it too: the registered one publishes it.
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1", [self._raw_entry(self._writer_entry("tests.x", "tests.n", "stale", ("tests.x", "old")))],
+                [["z", "old", "2026-09-30T00:00:00Z", msgpack.packb({"z": 1}, use_bin_type=True)]],
+            ], use_bin_type=True))
+            SingleFileMessagePackBackingStore(path).push(
+                self._writer_record("a", "tests.n", "tests.r", self._writer_entry("tests.r", "tests.n", "fresh", ("tests.r", "old")))
+            )
+            self.assertEqual([entry[0] for entry in msgpack.unpackb(path.read_bytes(), raw=False)[1]], ["tests.r"])
+
+    # A registered entry that owns an id keeps it against an arrived entry that owns it too and lists the id another record sits
+    # under, whichever of the two ids sorts first: the arrived entry's list is not merged in, so the record under the listed id is
+    # published by no chosen entry.
+    def test_an_arrived_entry_that_owns_a_registered_id_does_not_replace_it_nor_publish_what_it_lists(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import SchemaConflictError
+
+        for own_id, listed_id in (("tests.a", "tests.b"), ("tests.b", "tests.a")):
+            with tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.msgpack"
+                path.write_bytes(msgpack.packb([
+                    "cultcache.store.v1", [self._raw_entry(self._writer_entry(own_id, "tests.arrived", "stale", (own_id, listed_id)))],
+                    [["k2", listed_id, "2026-09-30T00:00:00Z", msgpack.packb({"k": 2}, use_bin_type=True)]],
+                ], use_bin_type=True))
+                before = path.read_bytes()
+                with self.assertRaises(SchemaConflictError) as refused:
+                    SingleFileMessagePackBackingStore(path).push(
+                        self._writer_record("k1", "tests.registered", own_id, self._writer_entry(own_id, "tests.registered", "fresh", (own_id,)))
+                    )
+                self.assertEqual(refused.exception.schema_id, listed_id)
+                self.assertEqual(refused.exception.record_key, "k2")
+                self.assertEqual(path.read_bytes(), before, "the file is left as it was")
+
+    # Ids are taken in sorted order, so which entry survives, and so which id the refusal names, does not depend on the order the
+    # records arrive in.
+    def test_the_refusal_names_the_same_id_whatever_order_the_records_arrive_in(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        one = self._writer_record("r1", "tests.n", "tests.y", self._writer_entry("tests.x", "tests.n", "h1", ("tests.x", "tests.y")))
+        two = self._writer_record("r2", "tests.n", "tests.z", self._writer_entry("tests.x", "tests.n", "h2", ("tests.x", "tests.z")))
+        for order in ([one, two], [two, one]):
+            with tempfile.TemporaryDirectory() as tmp:
+                with self.assertRaises(SchemaConflictError) as refused:
+                    SingleFileMessagePackBackingStore(Path(tmp) / "store.msgpack").push_all(order)
+                self.assertEqual(refused.exception.schema_id, "tests.y")
+                self.assertEqual(refused.exception.record_key, "r1")
+
+    # A write may not retype records already in the file: across tiers the id keeps the type its records resolve to, unless the
+    # entries of both tiers own it, which is a rename under a stable id and the registered descriptor wins.
+    def test_a_write_that_would_change_the_type_an_existing_record_resolves_to_refuses_typed_and_leaves_the_file(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import SchemaConflictError
+
+        cases = [
+            ("registered entry lists the id, arrived entry owns it",
+             self._writer_entry("tests.x", "tests.arrived", "h1", ("tests.x",)),
+             self._writer_record("a", "tests.registered", "tests.x", self._writer_entry("tests.r", "tests.registered", "h2", ("tests.r", "tests.x")))),
+            ("registered entry owns the id, arrived entry lists it",
+             self._writer_entry("tests.r", "tests.arrived", "h1", ("tests.r", "tests.x")),
+             self._writer_record("a", "tests.registered", "tests.x", self._writer_entry("tests.x", "tests.registered", "h2", ("tests.x",)))),
+        ]
+        payload = msgpack.packb({"z": 1}, use_bin_type=True)
+        with tempfile.TemporaryDirectory() as tmp:
+            for name, catalog, registered in cases:
+                path = Path(tmp) / (name.split(",")[0].replace(" ", "-") + ".msgpack")
+                path.write_bytes(msgpack.packb(
+                    ["cultcache.store.v1", [self._raw_entry(catalog)], [["z", "tests.x", "2026-09-30T00:00:00Z", payload]]], use_bin_type=True))
+                before = path.read_bytes()
+                with self.assertRaises(SchemaConflictError, msg=name) as refused:
+                    SingleFileMessagePackBackingStore(path).push(registered)
+                self.assertEqual(refused.exception.schema_id, "tests.x", name)
+                self.assertEqual(sorted(refused.exception.schema_names), ["tests.arrived", "tests.registered"], name)
+                self.assertEqual(path.read_bytes(), before, name)
+
+            # The same registered record renames the schema when both tiers own the id: it writes, and the reader finds every record.
+            path = Path(tmp) / "rename.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1", [self._raw_entry(self._writer_entry("tests.x", "tests.arrived", "h1", ("tests.x",)))],
+                [["z", "tests.x", "2026-09-30T00:00:00Z", payload]],
+            ], use_bin_type=True))
+            SingleFileMessagePackBackingStore(path).push(
+                self._writer_record("a", "tests.registered", "tests.x", self._writer_entry("tests.x", "tests.registered", "h2", ("tests.x",)))
+            )
+            self.assertEqual([(entry[0], entry[1]) for entry in msgpack.unpackb(path.read_bytes(), raw=False)[1]], [("tests.x", "tests.registered")])
+            self.assertEqual(len(SingleFileMessagePackBackingStore(path).pull_all()), 2)
+
+    def test_a_record_no_chosen_entry_publishes_refuses_the_write_typed_and_leaves_the_file(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import SchemaConflictError
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1", [self._raw_entry(self._writer_entry("tests.x", "tests.legacy", "stale", ("tests.x", "old")))],
+                [["z", "old", "2026-09-30T00:00:00Z", msgpack.packb({"z": 1}, use_bin_type=True)]],
+            ], use_bin_type=True))
+            before = path.read_bytes()
+            with self.assertRaises(SchemaConflictError) as refused:
+                SingleFileMessagePackBackingStore(path).push(
+                    self._writer_record("a", "tests.legacy", "tests.x", self._writer_entry("tests.x", "tests.legacy", "fresh", ("tests.x",)))
+                )
+            self.assertEqual(refused.exception.schema_id, "old")
+            self.assertEqual(refused.exception.record_key, "z")
+            self.assertEqual(path.read_bytes(), before)
+
+    def test_an_id_an_entry_owns_names_that_entry_not_one_that_lists_it_as_compatible(self) -> None:
+        for vector in ("own-id-over-compatible-v3.bin", "compatible-before-owner-v3.bin"):
+            store = SingleFileMessagePackBackingStore(self._C2A_VECTORS / "readability" / vector)
+            self.assertEqual([envelope.type for envelope in store.pull_all()], ["vectors.item", "vectors.item"], vector)
+
+    def test_a_record_loaded_under_a_compatible_schema_id_is_written_back_under_the_id_its_catalog_entry_carries(self) -> None:
+        import msgpack  # type: ignore
+
+        document = self._foreign_id_document()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1",
+                [["tests.foreign-id.current", "tests.foreign-id", "tests.foreign_id.v1", "tests.foreign-id.current", "",
+                  ["tests.foreign-id.current", "tests.foreign-id.older"], []]],
+                [["old", "tests.foreign-id.older", "2026-09-30T00:00:00Z", document.encode_payload({"name": "old"})]],
+            ], use_bin_type=True))
+            cache = self._open_foreign_id_store(document, path)
+            self.assertEqual(cache.get_required_envelope(document, "old").schema_id, "tests.foreign-id.current")
+            cache.put(document, "next", {"name": "next"})
+            reopened = self._open_foreign_id_store(document, path)
+            self.assertEqual(reopened.get_required(document, "old")["name"], "old")
+            self.assertEqual(reopened.get_required(document, "next")["name"], "next")
+
+    # The cache restamps a record on load, so a store's writer never has to: a record loaded under an id the registered document
+    # only lists is held, and written back by a whole write, under the id its catalog entry carries. A document that does not list
+    # the id a record sits under cannot have that record published by a write that leaves it in place: the put is refused, typed.
+    def test_a_cache_that_does_not_list_the_id_a_loaded_record_sits_under_is_refused_a_put_and_the_file_is_left(self) -> None:
+        import msgpack  # type: ignore
+        from cultcache_py import SchemaConflictError
+
+        document = define_database_entry_type(
+            "tests.foreign-id", [("name", 0)], schema_id="tests.foreign-id.current",
+            schema_name="tests.foreign-id", schema_version="tests.foreign_id.v1",
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(msgpack.packb([
+                "cultcache.store.v1",
+                [["tests.foreign-id.current", "tests.foreign-id", "tests.foreign_id.v1", "tests.foreign-id.current", "",
+                  ["tests.foreign-id.current", "tests.foreign-id.older"], []]],
+                [["old", "tests.foreign-id.older", "2026-09-30T00:00:00Z", document.encode_payload({"name": "old"})]],
+            ], use_bin_type=True))
+            before = path.read_bytes()
+            cache = self._open_foreign_id_store(document, path)
+            self.assertEqual(cache.get_required_envelope(document, "old").schema_id, "tests.foreign-id.current")
+            with self.assertRaises(SchemaConflictError) as refused:
+                cache.put(document, "next", {"name": "next"})
+            self.assertEqual(refused.exception.schema_id, "tests.foreign-id.older")
+            self.assertEqual(refused.exception.record_key, "old")
+            self.assertEqual(path.read_bytes(), before)
+
+    # A record resolves to a local document by its schema id, never by the name its catalog entry carries: a schema renamed under
+    # a stable id opens, and an id that names one document is not overruled by a name that names another.
+    def _store_of(self, path: Path, catalog: list, records: list) -> None:
+        import msgpack  # type: ignore
+
+        path.write_bytes(msgpack.packb(["cultcache.store.v1", catalog, records], use_bin_type=True))
+
+    def test_a_schema_renamed_under_a_stable_id_opens_by_its_id(self) -> None:
+        document = define_database_entry_type(
+            "tests.old", [("name", 0)], schema_id="tests.stable", schema_name="tests.old", schema_version="tests.old.v1",
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            self._store_of(
+                path,
+                [["tests.stable", "tests.renamed", "tests.renamed.v1", "renamed", "", ["tests.stable"], []]],
+                [["a", "tests.stable", "2026-09-30T00:00:00Z", document.encode_payload({"name": "a"})]],
+            )
+            cache = self._open_foreign_id_store(document, path)
+            self.assertEqual(cache.get_required(document, "a")["name"], "a")
+
+    def test_a_schema_id_that_names_one_document_is_not_overruled_by_a_name_that_names_another(self) -> None:
+        first = define_database_entry_type("tests.a", [("name", 0)], schema_id="id.a", schema_name="tests.a", schema_version="tests.a.v1")
+        second = define_database_entry_type(
+            "tests.b", [("name", 0)], schema_id="id.b", schema_name="tests.b", schema_version="tests.b.v1", compatible_schema_ids=["id.b", "id.b.older"],
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            for schema_id in ("id.b", "id.b.older"):
+                path = Path(tmp) / (schema_id + ".msgpack")
+                # The entry that publishes the id carries the other document's name.
+                self._store_of(
+                    path,
+                    [["id.b", "tests.a", "tests.b.v1", "h", "", ["id.b", "id.b.older"], []]],
+                    [["k", schema_id, "2026-09-30T00:00:00Z", second.encode_payload({"name": "k"})]],
+                )
+                cache = CultCache.builder().register_document_type(first).register_document_type(second).add_generic_store(
+                    SingleFileMessagePackBackingStore(path)
+                ).build()
+                cache.pull_all_backing_stores()
+                self.assertEqual(cache.get_required(second, "k")["name"], "k", schema_id)
+                self.assertIsNone(cache.get(first, "k"), schema_id)
+
+    def _assert_second_claim_refused(self, first, second, schema_id: str) -> None:
+        """A registration refusal is typed, names the id and both schema names and document types, and the cache keeps what it
+        had."""
+        from cultcache_py import SchemaConflictError
+
+        cache = CultCache()
+        cache.register_document_type(first)
+        with self.assertRaises(SchemaConflictError) as refused:
+            cache.register_document_type(second)
+        self.assertEqual(refused.exception.schema_id, schema_id)
+        self.assertEqual(refused.exception.schema_names, [first.catalog_entry().schema_name, second.catalog_entry().schema_name])
+        self.assertIn(first.type, str(refused.exception))
+        self.assertIn(second.type, str(refused.exception))
+        if second is not first:
+            with self.assertRaisesRegex(CultCacheError, "not registered"):
+                cache.put(second, "k", {"name": "k"})
+
+    def _pull(self, documents: list, catalog: list, records: list) -> CultCache:
+        tmp = tempfile.mkdtemp()
+        path = Path(tmp) / "store.msgpack"
+        self._store_of(path, catalog, records)
+        builder = CultCache.builder()
+        for document in documents:
+            builder = builder.register_document_type(document)
+        cache = builder.add_generic_store(SingleFileMessagePackBackingStore(path)).build()
+        cache.pull_all_backing_stores()
+        return cache
+
+    def test_a_document_listing_an_id_another_owns_registers_beside_it_in_either_order_and_the_owner_wins(self) -> None:
+        owner = define_database_entry_type("tests.owner", [("name", 0)], schema_id="id.owned", schema_name="tests.owner", schema_version="tests.owner.v1")
+        lister = define_database_entry_type(
+            "tests.lister", [("name", 0)], schema_id="id.lister", schema_name="tests.lister", schema_version="tests.lister.v1",
+            compatible_schema_ids=["id.lister", "id.owned"],
+        )
+        catalog = [
+            ["id.owned", "tests.owner", "tests.owner.v1", "h1", "", ["id.owned"], []],
+            ["id.lister", "tests.lister", "tests.lister.v1", "h2", "", ["id.lister", "id.owned"], []],
+        ]
+        records = [
+            ["o", "id.owned", "2026-09-30T00:00:00Z", owner.encode_payload({"name": "o"})],
+            ["l", "id.lister", "2026-09-30T00:00:00Z", lister.encode_payload({"name": "l"})],
+        ]
+        for order in ([owner, lister], [lister, owner]):
+            cache = self._pull(order, catalog, records)
+            self.assertEqual(cache.get_required(owner, "o")["name"], "o")
+            self.assertIsNone(cache.get(lister, "o"))
+            self.assertEqual(cache.get_required(lister, "l")["name"], "l")
+        self.assertEqual(self._pull([lister], catalog, records[:1]).get_required(lister, "o")["name"], "o")
+
+    def test_two_documents_listing_one_id_register_and_a_record_under_it_needs_an_owner(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        a = define_database_entry_type(
+            "tests.list-a", [("name", 0)], schema_id="id.a", schema_name="tests.list-a", compatible_schema_ids=["id.a", "id.shared"],
+        )
+        b = define_database_entry_type(
+            "tests.list-b", [("name", 0)], schema_id="id.b", schema_name="tests.list-b", compatible_schema_ids=["id.b", "id.shared"],
+        )
+        owner = define_database_entry_type("tests.shared", [("name", 0)], schema_id="id.shared", schema_name="tests.shared")
+        catalog = [["id.shared", "tests.shared", "tests.shared.v1", "h", "", ["id.shared"], []]]
+        records = [["k", "id.shared", "2026-09-30T00:00:00Z", owner.encode_payload({"name": "k"})]]
+        for listers in ([a, b], [b, a]):
+            with self.assertRaises(SchemaConflictError) as refused:
+                self._pull(listers, catalog, records)
+            self.assertEqual(refused.exception.schema_id, "id.shared")
+            self.assertEqual(refused.exception.record_key, "k")
+            self.assertEqual(refused.exception.schema_names, ["tests.list-a", "tests.list-b"])
+            for documents in ([*listers, owner], [owner, *listers]):
+                cache = self._pull(documents, catalog, records)
+                self.assertEqual(cache.get_required(owner, "k")["name"], "k")
+
+    def test_two_documents_owning_one_schema_id_are_refused_in_either_order(self) -> None:
+        # Each declares an older id and not its own, so the id they share is only ever their own.
+        a = define_database_entry_type("tests.own-a", [("name", 0)], schema_id="id.same", schema_name="tests.own-a", compatible_schema_ids=["id.a-older"])
+        b = define_database_entry_type("tests.own-b", [("name", 0)], schema_id="id.same", schema_name="tests.own-b", compatible_schema_ids=["id.b-older"])
+        self._assert_second_claim_refused(a, b, "id.same")
+        self._assert_second_claim_refused(b, a, "id.same")
+
+    def test_every_registration_refusal_is_a_schema_conflict(self) -> None:
+        first = define_database_entry_type("tests.named", [("name", 0)], schema_id="id.first", schema_name="tests.named")
+        same_name = define_database_entry_type("tests.renamed", [("name", 0)], schema_id="id.second", schema_name="tests.named")
+        self._assert_second_claim_refused(first, same_name, "id.second")
+        self._assert_second_claim_refused(first, first, "id.first")
 
     def test_interop_cli_helpers_round_trip_v1_store(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
@@ -893,6 +1373,32 @@ class CultCacheTests(unittest.TestCase):
                         self.assertNotIn(repr(value[0]), message)
                         self.assertIn(f"of {len(value[0])} bytes", message)
 
+    def test_single_file_refusals_say_exactly_what_was_found_and_what_is_read(self) -> None:
+        import msgpack  # type: ignore
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.cc"
+            reads = "it reads 'cultcache.store.v1' and 'cultcache.store.v3' only"
+            for header, found in (
+                ("cultcache.store.v12", "'cultcache.store.v12'"),
+                ("cultcache.store.SECRET", "an unrecognised cultcache.store.* header of 22 bytes"),
+                ("cultcache.store.v", "an unrecognised cultcache.store.* header of 17 bytes"),
+                # Digits are ASCII only: two Arabic-Indic digits are four bytes and are not the known shape.
+                ("cultcache.store.v١٢", "an unrecognised cultcache.store.* header of 21 bytes"),
+            ):
+                path.write_bytes(msgpack.packb([header, [], []], use_bin_type=True))
+                with self.assertRaises(ValueError) as caught:
+                    SingleFileMessagePackBackingStore(path).pull_all()
+                self.assertIn(f"CultCache store format {found} is not one this runtime reads; {reads}", str(caught.exception))
+
+            path.write_bytes(msgpack.packb(["cultcache.store.v1", [], [["k", "s", "t", b"\x90", "extra"]]], use_bin_type=True))
+            with self.assertRaises(ValueError) as caught:
+                SingleFileMessagePackBackingStore(path).pull_all()
+            self.assertIn(
+                "CultCache record 'k' (schema 's') has 5 slots, more than the 4 of a cultcache.store.v1 record, so this is not a valid store",
+                str(caught.exception),
+            )
+
     def test_single_file_record_refusal_names_only_a_string_key(self) -> None:
         import msgpack  # type: ignore
 
@@ -966,5 +1472,120 @@ class CultCacheTests(unittest.TestCase):
                 self.assertNotIsInstance(caught.exception, FileNotFoundError)
 
 
+    # The element-id marker: tests/vectors/document-variants-c2a/v3-base.msgpack is v1-base with its header replaced.
+    _C2A_VECTORS = Path(__file__).resolve().parents[3] / "tests" / "vectors" / "document-variants-c2a"
+
+    def _header_after_rewrite(self, vector: Path) -> str:
+        import msgpack
+
+        with tempfile.TemporaryDirectory() as tmp:
+            store_path = Path(tmp) / "store.msgpack"
+            store_path.write_bytes(vector.read_bytes())
+            store = SingleFileMessagePackBackingStore(store_path)
+            envelopes = store.pull_all()
+            self.assertEqual([e.key for e in envelopes], ["alpha", "beta"])
+            store.push(envelopes[0])
+            return msgpack.unpackb(store_path.read_bytes(), raw=False)[0]
+
+    def test_single_file_reads_a_v3_element_id_store_and_a_rewrite_keeps_the_marker(self) -> None:
+        self.assertEqual(self._header_after_rewrite(self._C2A_VECTORS / "v3-base.msgpack"), "cultcache.store.v3")
+
+    def test_single_file_rewrite_of_a_v1_store_stays_v1(self) -> None:
+        self.assertEqual(self._header_after_rewrite(self._VECTORS / "v1-base.msgpack"), "cultcache.store.v1")
+
+    def test_single_file_flush_after_the_marked_file_is_gone_writes_unmarked(self) -> None:
+        import msgpack
+
+        with tempfile.TemporaryDirectory() as tmp:
+            store_path = Path(tmp) / "store.msgpack"
+            store_path.write_bytes((self._C2A_VECTORS / "v3-base.msgpack").read_bytes())
+            store = SingleFileMessagePackBackingStore(store_path)
+            envelopes = store.pull_all()
+            store_path.unlink()
+            store.push_all(envelopes)
+            self.assertEqual(msgpack.unpackb(store_path.read_bytes(), raw=False)[0], "cultcache.store.v1")
+
+    def test_single_file_push_after_the_marked_file_is_gone_writes_unmarked(self) -> None:
+        import msgpack
+
+        with tempfile.TemporaryDirectory() as tmp:
+            store_path = Path(tmp) / "store.msgpack"
+            store_path.write_bytes((self._C2A_VECTORS / "v3-base.msgpack").read_bytes())
+            store = SingleFileMessagePackBackingStore(store_path)
+            envelopes = store.pull_all()
+            store_path.unlink()
+            store.push(envelopes[0])
+            self.assertEqual(msgpack.unpackb(store_path.read_bytes(), raw=False)[0], "cultcache.store.v1")
+
+    def test_single_file_push_all_refuses_a_store_whose_header_it_cannot_read_and_leaves_it_untouched(self) -> None:
+        envelopes = SingleFileMessagePackBackingStore(self._C2A_VECTORS / "v3-base.msgpack").pull_all()
+        vectors = self._VECTORS.parent
+        for vector in (
+            self._VECTORS / "unknown-header.msgpack",
+            self._VECTORS / "variant-v2.msgpack",
+            vectors / "document-variants-c1" / "variant-store.msgpack",
+        ):
+            with tempfile.TemporaryDirectory() as tmp:
+                store_path = Path(tmp) / "store.msgpack"
+                store_path.write_bytes(vector.read_bytes())
+                before = store_path.read_bytes()
+                with self.assertRaisesRegex(StoreUnreadableError, "is not readable"):
+                    SingleFileMessagePackBackingStore(store_path).push_all(envelopes)
+                self.assertEqual(store_path.read_bytes(), before, f"{vector.name} was rewritten")
+
+    # A file is replaced by a rewrite exactly when this runtime's own reader opens it: one verdict per file, asked by
+    # pull_all, push_all, push and delete alike. The bytes and every runtime's verdict:
+    # tests/vectors/document-variants-c2a/readability.
+    def test_single_file_replaces_a_file_exactly_when_it_reads(self) -> None:
+        import msgpack  # type: ignore
+
+        root = self._C2A_VECTORS / "readability"
+        rows = [
+            line.split()
+            for line in (root / "manifest.txt").read_text(encoding="utf-8").splitlines()
+            if line and not line.startswith("#")
+        ]
+        # Every vector in the folder has a manifest row.
+        self.assertEqual(
+            sorted(path.name for path in root.glob("*.bin")),
+            sorted(vector for vector, *_ in rows if not vector.startswith("..")),
+        )
+        envelopes = SingleFileMessagePackBackingStore(self._C2A_VECTORS / "v3-base.msgpack").pull_all()
+        for vector, _, _, _, python in rows:
+            content = (root / vector).read_bytes()
+            for operation in ("pull_all", "push_all", "push", "delete"):
+                with tempfile.TemporaryDirectory() as tmp:
+                    store_path = Path(tmp) / "store.msgpack"
+                    store_path.write_bytes(content)
+                    store = SingleFileMessagePackBackingStore(store_path)
+                    run = {
+                        "pull_all": store.pull_all,
+                        "push_all": lambda: store.push_all(envelopes),
+                        "push": lambda: store.push(envelopes[0]),
+                        "delete": lambda: store.delete(envelopes[0].type, envelopes[0].key),
+                    }[operation]
+                    if python == "reads":
+                        run()
+                        if operation == "pull_all":
+                            continue
+                        # The replaced file is a store: it carries the header its old content decides (a v3 store keeps its
+                        # marker, all else is v1), and it holds what the operation wrote.
+                        expected = "cultcache.store.v3" if "v3" in vector else "cultcache.store.v1"
+                        self.assertEqual(msgpack.unpackb(store_path.read_bytes(), raw=False)[0], expected, f"{vector} {operation}")
+                        keys = [envelope.key for envelope in SingleFileMessagePackBackingStore(store_path).pull_all()]
+                        if operation == "push_all":
+                            self.assertEqual(sorted(set(keys) & {e.key for e in envelopes}), sorted(e.key for e in envelopes), f"{vector} {operation}")
+                        elif operation == "push":
+                            self.assertIn(envelopes[0].key, keys, f"{vector} {operation}")
+                        else:
+                            self.assertNotIn(envelopes[0].key, keys, f"{vector} {operation}")
+                    else:
+                        with self.assertRaises(StoreUnreadableError, msg=f"{vector} {operation}") as refused:
+                            run()
+                        self.assertIsNotNone(refused.exception.__cause__, f"{vector} {operation}")
+                        self.assertEqual(store_path.read_bytes(), content, f"{vector} {operation} rewrote a file it cannot read")
+
+
+
 if __name__ == "__main__":
     unittest.main()

packages/cultcache-py/tests/test_first_call.py

@@ -0,0 +1,67 @@
+"""The Python CultCache first call from docs/start/README.md. The docs show the region between the
+`snippet` markers verbatim, and test_docs_show_the_tested_snippet fails when they differ."""
+
+import unittest
+from pathlib import Path
+
+# snippet:begin
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from cultcache_py import CultCache, SingleFileMessagePackBackingStore, define_document_type
+
+
+@dataclass
+class Item:
+    name: str
+    category: str
+    value: int
+
+
+item_doc = define_document_type(
+    "item",
+    encode=lambda item: asdict(item),
+    decode=lambda raw: Item(**raw),
+    name="name",
+    indexes={"category": "category"},
+)
+
+
+def first_call() -> Item:
+    path = Path(tempfile.mkdtemp()) / "first-call.cc"
+
+    cache = (
+        CultCache.builder()
+        .register_document_type(item_doc)
+        .add_generic_store(SingleFileMessagePackBackingStore(path))
+        .build()
+    )
+    cache.pull_all_backing_stores()
+    cache.put(item_doc, "item:potion", Item("Potion", "Consumable", 50))  # written to the .cc file
+
+    reopened = (
+        CultCache.builder()
+        .register_document_type(item_doc)
+        .add_generic_store(SingleFileMessagePackBackingStore(path))
+        .build()
+    )
+    reopened.pull_all_backing_stores()  # read it back
+    assert reopened.get_by_name(item_doc, "Potion") == reopened.get_required(item_doc, "item:potion")
+    return reopened.get_required(item_doc, "item:potion")
+# snippet:end
+
+
+class FirstCallTests(unittest.TestCase):
+    def test_first_call_round_trips_through_a_second_cache(self) -> None:
+        self.assertEqual(first_call(), Item("Potion", "Consumable", 50))
+
+    def test_docs_show_the_tested_snippet(self) -> None:
+        source = Path(__file__).read_text(encoding="utf-8")
+        snippet = source.split("# snippet:begin\n", 1)[1].split("# snippet:end\n", 1)[0]
+        docs = (Path(__file__).parents[3] / "docs" / "start" / "README.md").read_text(encoding="utf-8")
+        self.assertIn("```python\n" + snippet + "```", docs)
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultcache-py/tests/test_slot_nil.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+import msgpack
+
+from cultcache_py import database_entry_field, define_database_entry_type, define_record_codec, leaves as t
+
+# tests/vectors/slot-nil is written only by the C# reference (SlotNilVectorTests): what it reads and rewrites for a nil, a
+# str in a byte[] slot, and a record short of its last slots. This runtime accepts what the reference accepts and rewrites
+# the same bytes.
+VECTORS = Path(__file__).resolve().parents[3] / "tests" / "vectors" / "slot-nil"
+
+
+def _probe():
+    inner = define_record_codec("SlotNilInner", [database_entry_field("x", 0, default="", codec=t.string)])
+    return define_database_entry_type(
+        "tests.slot-nil",
+        [
+            database_entry_field("s", 0, default="", codec=t.nullable(t.string)),
+            database_entry_field("i", 1, default=0, codec=t.int32),
+            database_entry_field("b", 2, default=b"", codec=t.nullable(t.bytes)),
+            database_entry_field("r", 3, default=None, codec=t.nullable(inner)),
+            database_entry_field("l", 4, default=[], codec=t.nullable(t.list(t.string))),
+        ],
+    )
+
+
+class SlotNilVectorTests(unittest.TestCase):
+    def test_slots_read_and_rewrite_exactly_what_the_reference_does_for_nil_str_in_bytes_and_short_records(self) -> None:
+        rows = msgpack.unpackb((VECTORS / "reads.msgpack").read_bytes(), raw=False)
+        probe = _probe()
+        self.assertEqual(17, len(rows))
+        accepted = 0
+        for name, payload, was_accepted, rewritten in rows:
+            with self.subTest(name):
+                if was_accepted:
+                    self.assertEqual(rewritten.hex(), probe.encode_payload(probe.decode_payload(payload)).hex())
+                    accepted += 1
+                else:
+                    with self.assertRaises(Exception):
+                        probe.decode_payload(payload)
+        self.assertEqual(15, accepted)
+
+    def test_a_character_outside_the_bmp_is_four_utf8_bytes(self) -> None:
+        rows = {name: (payload, rewritten) for name, payload, _, rewritten in msgpack.unpackb((VECTORS / "reads.msgpack").read_bytes(), raw=False)}
+        probe = _probe()
+        self.assertEqual("\U0001F600", probe.decode_payload(rows["string-astral"][0])["s"])
+        self.assertEqual(b"\xf0\x9f\x98\x80", probe.decode_payload(rows["bytes-str-astral"][0])["b"])
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultcache-py/tests/test_store_lock.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from cultcache_py import SingleFileMessagePackBackingStore, stores
+from cultcache_py.backing_store import CultCacheEnvelope
+
+REPO = Path(__file__).resolve().parents[3]
+TS_STORE_FILE = REPO / "packages" / "cultcache-ts" / "dist" / "store-file.js"
+HOLD_SECONDS = 1.5
+
+# A holder that takes the lock the way the Rust runtime does (an exclusive file lock), not through this package.
+PY_HOLDER = """
+import fcntl, os, sys, time
+fd = os.open(sys.argv[1] + '.lock', os.O_RDWR | os.O_CREAT, 0o666)
+fcntl.flock(fd, fcntl.LOCK_EX)
+print('HELD', flush=True)
+time.sleep(float(sys.argv[2]))
+"""
+# A holder that is the TypeScript runtime's own withStoreWriteLock, built from packages/cultcache-ts.
+TS_HOLDER = """
+const { withStoreWriteLock } = require(process.argv[1]);
+withStoreWriteLock(process.argv[2], async () => {
+  console.log('HELD');
+  await new Promise((r) => setTimeout(r, Number(process.argv[3]) * 1000));
+});
+"""
+
+
+def envelope(key: str) -> CultCacheEnvelope:
+    return CultCacheEnvelope(key=key, type="t", payload=b"\x01", stored_at="2026-11-06T00:00:00Z")
+
+
+def start_holder(argv: list[str]) -> subprocess.Popen[str]:
+    holder = subprocess.Popen(argv, stdout=subprocess.PIPE, text=True)
+    assert holder.stdout is not None and holder.stdout.readline().strip() == "HELD"
+    holder.held_at = time.monotonic()  # type: ignore[attr-defined]
+    return holder
+
+
+@unittest.skipIf(sys.platform == "win32", "the foreign holders here use flock; Windows is covered by the TS holder")
+class StoreLockTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+        self.path = self.dir / "state.cc"
+
+    def assert_write_waits_for(self, holder: subprocess.Popen[str]) -> None:
+        self.addCleanup(holder.wait)
+        self.addCleanup(holder.stdout.close)  # type: ignore[union-attr]
+        refused = SingleFileMessagePackBackingStore(self.path, lock_timeout=0.2)
+        with self.assertRaises(TimeoutError):
+            refused.push(envelope("blocked"))
+        self.assertFalse(self.path.exists(), "a write that could not take the lock must not touch the store")
+
+        SingleFileMessagePackBackingStore(self.path, lock_timeout=10).push(envelope("after"))
+        self.assertGreaterEqual(time.monotonic() - holder.held_at, HOLD_SECONDS - 0.1, "the write finished while the holder still held the lock")  # type: ignore[attr-defined]
+        self.assertEqual(["after"], [e.key for e in SingleFileMessagePackBackingStore(self.path).pull_all()])
+
+    def test_write_waits_while_a_foreign_process_holds_the_lock(self) -> None:
+        self.assert_write_waits_for(start_holder([sys.executable, "-c", PY_HOLDER, str(self.path), str(HOLD_SECONDS)]))
+
+    @unittest.skipUnless(shutil.which("node") and TS_STORE_FILE.exists(), "needs node and a built packages/cultcache-ts (npm run build)")
+    def test_write_waits_while_the_typescript_runtime_holds_the_lock(self) -> None:
+        holder = start_holder(["node", "-e", TS_HOLDER, str(TS_STORE_FILE), str(self.path), str(HOLD_SECONDS)])
+        self.assert_write_waits_for(holder)
+
+    def test_the_lock_is_released_after_each_write(self) -> None:
+        store = SingleFileMessagePackBackingStore(self.path, lock_timeout=0.2)
+        for key in "abc":
+            store.push(envelope(key))
+        self.assertEqual(["a", "b", "c"], sorted(e.key for e in store.pull_all()))
+
+    def test_concurrent_processes_lose_no_writes(self) -> None:
+        script = (
+            "import sys\n"
+            "from cultcache_py import SingleFileMessagePackBackingStore as S\n"
+            "from cultcache_py.backing_store import CultCacheEnvelope as E\n"
+            "s = S(sys.argv[1])\n"
+            "for i in range(25):\n"
+            "    s.push(E(key=f'{sys.argv[2]}{i}', type='t', payload=b'\\x01', stored_at='x'))\n"
+        )
+        env = {**os.environ, "PYTHONPATH": str(Path(stores.__file__).parents[1])}
+        procs = [subprocess.Popen([sys.executable, "-c", script, str(self.path), tag], env=env) for tag in "pqr"]
+        for proc in procs:
+            self.assertEqual(0, proc.wait())
+        self.assertEqual(75, len(SingleFileMessagePackBackingStore(self.path).pull_all()))
+
+
+class StagedWriteTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.dir = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
+        self.path = self.dir / "state.cc"
+
+    def test_the_staged_file_is_fsynced_before_the_replace(self) -> None:
+        order: list[str] = []
+        real_fsync, real_replace = os.fsync, os.replace
+        with mock.patch("os.fsync", side_effect=lambda fd: (order.append("fsync"), real_fsync(fd))[1]), mock.patch(
+            "os.replace", side_effect=lambda a, b: (order.append("replace"), real_replace(a, b))[1]
+        ):
+            SingleFileMessagePackBackingStore(self.path).push(envelope("a"))
+        self.assertEqual("fsync", order[0])
+        self.assertLess(order.index("fsync"), order.index("replace"))
+
+    def test_the_staged_name_is_unique_per_write(self) -> None:
+        names: list[str] = []
+        real_replace = os.replace
+        with mock.patch("os.replace", side_effect=lambda a, b: (names.append(os.fspath(a)), real_replace(a, b))[1]):
+            store = SingleFileMessagePackBackingStore(self.path)
+            store.push(envelope("a"))
+            store.push(envelope("b"))
+        self.assertEqual(2, len(set(names)))
+        self.assertNotIn(os.fspath(self.path) + ".tmp", names)
+
+    def test_a_failed_replace_leaves_the_store_and_no_staged_file(self) -> None:
+        store = SingleFileMessagePackBackingStore(self.path)
+        store.push(envelope("a"))
+        before = self.path.read_bytes()
+        with mock.patch("os.replace", side_effect=OSError("boom")), self.assertRaises(OSError):
+            store.push(envelope("b"))
+        self.assertEqual(before, self.path.read_bytes())
+        self.assertEqual([], [p.name for p in self.dir.iterdir() if ".tmp" in p.name])
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultcache-py/tests/test_typed_leaves.py

@@ -133,6 +133,7 @@ def _inner_record() -> t.SlotCodec:
         [
             database_entry_field("n", 0, default="", codec=t.string),
             database_entry_field("w", 1, default=0.0, codec=t.float32),
+            database_entry_field("id", 2, default="", codec=t.string),
         ],
         type_name=REFERENCE + "LeafInner",
     )
@@ -662,7 +663,7 @@ def _python_authored_leaf_record() -> dict:
     return {
         "id": "py", "flag": False, "blob": bytearray([1, 255]), "i": -(2**31), "l": 2**63 - 1, "f": 0.1, "d": 1e-300,
         "maybe_i": None, "tags": [], "names": ("\u00e9", "z"), "any": {"k": [1, True, None, 2.5, "s"], "n": -3},
-        "nested": None, "items": [{"n": "one", "w": 2**53 + 2**29 + 1}, {"n": "two", "w": 1e-40}],
+        "nested": None, "items": [{"n": "one", "w": 2**53 + 2**29 + 1, "id": "000000000021"}, {"n": "two", "w": 1e-40, "id": "000000000022"}],
         "shape": UnionArm("LeafCircle", {"r": 0.1}), "floats": [0.1, 3, -0.0, 1e39], "maybe_f": None,
     }
 

packages/cultcache-py/tests/test_union_parity.py

@@ -68,22 +68,51 @@ image = define_record_codec(
     ],
     type_name=_GOLDEN + "Image",
 )
-wrap = define_record_codec("Wrap", [database_entry_field("inner", 0, codec=_node)], type_name=_GOLDEN + "Wrap")
+wrap = define_record_codec(
+    "Wrap",
+    [database_entry_field("inner", 0, codec=_node), database_entry_field("id", 1, codec=t.string)],
+    type_name=_GOLDEN + "Wrap",
+)
 node = define_union(
     "Node",
     {0: ("Box", box), 1: ("Text", text), 2: ("Use", use), 5: ("Image", image), 6: ("Wrap", wrap)},
     type_name=_GOLDEN + "Node",
 )
+# The golden's Outcome: the arms of a list carry an element id, so Denied, Floor and Ceiling are one-slot records.
+_id_only = lambda name: define_record_codec(name, [database_entry_field("id", 0, codec=t.string)])  # noqa: E731
 outcome = define_union(
+    "Outcome",
+    {
+        0: (
+            "Pending",
+            define_record_codec(
+                "Pending",
+                [database_entry_field("message", 0, codec=t.string), database_entry_field("id", 1, codec=t.string)],
+            ),
+        ),
+        1: (
+            "Completed",
+            define_record_codec(
+                "Completed",
+                [database_entry_field("source_version", 0, codec=t.int32), database_entry_field("id", 1, codec=t.string)],
+            ),
+        ),
+        2: ("Denied", _id_only("Denied")),
+        -2147483648: ("Floor", _id_only("Floor")),
+        2147483647: ("Ceiling", _id_only("Ceiling")),
+    },
+    type_name=_GOLDEN + "Outcome",
+)
+# The codec's unit arms (no value, written [key, []]), kept apart from the golden: a document list's arms carry ids.
+unit_outcome = define_union(
     "Outcome",
     {
         0: ("Pending", define_record_codec("Pending", [database_entry_field("message", 0, codec=t.string)])),
-        1: ("Completed", define_record_codec("Completed", [database_entry_field("source_version", 0, codec=t.int32)])),
         2: ("Denied", None),
         -2147483648: ("Floor", None),
         2147483647: ("Ceiling", None),
     },
-    type_name=_GOLDEN + "Outcome",
+    type_name=_GOLDEN + "UnitOutcome",
 )
 tool = define_record_codec(
     "Tool",
@@ -121,41 +150,41 @@ def _surface_value() -> dict:
         "root": UnionArm(
             "Box",
             {
-                "id": "root",
+                "id": "0000000000c0",
                 "children": [
-                    UnionArm("Text", {"id": "t1", "content": "hello"}),
+                    UnionArm("Text", {"id": "0000000000c1", "content": "hello"}),
                     UnionArm(
                         "Use",
                         {
-                            "id": "u1",
+                            "id": "0000000000c2",
                             "composition": {
                                 "name": "comp",
                                 "body": UnionArm(
                                     "Box",
                                     {
-                                        "id": "inner",
+                                        "id": "0000000000d0",
                                         "children": [
-                                            UnionArm("Text", {"id": "deep", "content": "x"}),
-                                            UnionArm("Image", {"id": "img", "uri": "uri://a", "alt": "alt"}),
+                                            UnionArm("Text", {"id": "0000000000d1", "content": "x"}),
+                                            UnionArm("Image", {"id": "0000000000d2", "uri": "uri://a", "alt": "alt"}),
                                         ],
                                     },
                                 ),
                             },
                             "slots": [
-                                UnionArm("Text", {"id": "s1", "content": "slot"}),
+                                UnionArm("Text", {"id": "0000000000e1", "content": "slot"}),
                                 None,
-                                UnionArm("Box", {"id": "b2", "children": []}),
+                                UnionArm("Box", {"id": "0000000000e2", "children": []}),
                             ],
                         },
                     ),
-                    UnionArm("Image", {"id": "i2", "uri": "uri://b", "alt": ""}),
+                    UnionArm("Image", {"id": "0000000000c3", "uri": "uri://b", "alt": ""}),
                 ],
             },
         ),
         "outcomes": [
-            UnionArm("Pending", {"message": "wait"}),
-            UnionArm("Completed", {"source_version": 7}),
-            UnionArm("Denied"),
+            UnionArm("Pending", {"message": "wait", "id": "0000000000a1"}),
+            UnionArm("Completed", {"source_version": 7, "id": "0000000000a2"}),
+            UnionArm("Denied", {"id": "0000000000a3"}),
         ],
         "part": UnionArm("Tool", {"name": "hammer", "uses": 12}),
         "crafted": UnionArm("Part", {"name": "gear", "count": 4}),
@@ -256,12 +285,14 @@ class UnionCodecRuleTests(unittest.TestCase):
         )
 
     def test_unit_arm_is_written_with_empty_slots_and_reads_back(self) -> None:
-        self.assertEqual(outcome.encode(UnionArm("Denied")), [2, []])
-        self.assertEqual(outcome.decode([2, []]), UnionArm("Denied", None))
+        # The bytes are the C# reference's (tests/vectors/union-parity/unit-arm-denied.msgpack), not spelled here.
+        reference = _vector("unit-arm-denied.msgpack")
+        self.assertEqual(msgpack.packb(unit_outcome.encode(UnionArm("Denied"))), reference)
+        self.assertEqual(unit_outcome.decode(msgpack.unpackb(reference, raw=False)), UnionArm("Denied", None))
 
     def test_unit_arm_refuses_a_value_to_carry(self) -> None:
         with self.assertRaises(ValueError) as caught:
-            outcome.encode(UnionArm("Denied", {"message": self.CANARY}))
+            unit_outcome.encode(UnionArm("Denied", {"message": self.CANARY}))
         self.assertEqual(str(caught.exception), "Union 'Outcome' arm 2 is a unit arm and carries no value")
 
     def test_arm_keys_are_written_as_declared(self) -> None:
@@ -333,7 +364,7 @@ class UnionCodecRuleTests(unittest.TestCase):
         self.assertEqual(row.decode(encoded), {"id": "r", "cells": cells})
 
     def test_a_unit_arm_with_extra_slots_is_read_past(self) -> None:
-        self.assertEqual(outcome.decode([2, ["extra"]]), UnionArm("Denied"))
+        self.assertEqual(unit_outcome.decode([2, ["extra"]]), UnionArm("Denied"))
 
     def test_union_arms_are_immutable_hashable_values(self) -> None:
         arm = UnionArm("Denied")
@@ -478,7 +509,7 @@ CANARY = "CANARY-union-golden-4c2a"
 def _wrap_chain(wraps: int, leaf: UnionArm) -> UnionArm:
     value = leaf
     for _ in range(wraps):
-        value = UnionArm("Wrap", {"inner": value})
+        value = UnionArm("Wrap", {"inner": value, "id": "0000000000b1"})
     return value
 
 
@@ -521,9 +552,9 @@ class BoundsVectorTests(unittest.TestCase):
         self.assertEqual(counts, {"accepted": 4, "refused": 7, "read-only": 1})
 
     def test_the_value_at_the_limit_writes_the_vector_and_the_value_past_it_is_refused_on_write(self) -> None:
-        at_limit = {**_surface_value(), "root": _wrap_chain(126, UnionArm("Box", {"id": "leaf", "children": []}))}
+        at_limit = {**_surface_value(), "root": _wrap_chain(126, UnionArm("Box", {"id": "0000000000f0", "children": []}))}
         self.assertEqual(surface_document.encode_payload(at_limit), _vector("depth-at-limit.msgpack"))
-        past = {**_surface_value(), "root": _wrap_chain(127, UnionArm("Text", {"id": "leaf", "content": CANARY}))}
+        past = {**_surface_value(), "root": _wrap_chain(127, UnionArm("Text", {"id": "0000000000f0", "content": CANARY}))}
         with self.assertRaises(CultCachePayloadDepthError) as caught:
             surface_document.encode_payload(past)
         message = str(caught.exception)
@@ -533,7 +564,7 @@ class BoundsVectorTests(unittest.TestCase):
         self.assertNotIn(CANARY, message)
 
     def test_a_cache_put_of_the_value_past_the_limit_refuses_and_stores_nothing(self) -> None:
-        past = {**_surface_value(), "root": _wrap_chain(127, UnionArm("Box", {"id": "leaf", "children": []}))}
+        past = {**_surface_value(), "root": _wrap_chain(127, UnionArm("Box", {"id": "0000000000f0", "children": []}))}
         with tempfile.TemporaryDirectory() as tmp:
             path = Path(tmp) / "store.cc"
             cache = (
@@ -709,8 +740,12 @@ class UnionDecodeBoundsTests(unittest.TestCase):
                 self.assertEqual(str(caught.exception), expected)
 
     def test_the_ends_of_the_int32_key_domain_are_unit_arms_that_read_and_write(self) -> None:
-        self.assertEqual(outcome.decode([-(2**31), []]), UnionArm("Floor"))
-        self.assertEqual(outcome.encode(UnionArm("Ceiling")), [2**31 - 1, []])
+        floor = _vector("unit-arm-floor.msgpack")
+        ceiling = _vector("unit-arm-ceiling.msgpack")
+        self.assertEqual(unit_outcome.decode(msgpack.unpackb(floor, raw=False)), UnionArm("Floor"))
+        self.assertEqual(msgpack.packb(unit_outcome.encode(UnionArm("Floor"))), floor)
+        self.assertEqual(unit_outcome.decode(msgpack.unpackb(ceiling, raw=False)), UnionArm("Ceiling"))
+        self.assertEqual(msgpack.packb(unit_outcome.encode(UnionArm("Ceiling"))), ceiling)
 
 
 if __name__ == "__main__":

packages/cultcache-rs/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `cultcache-rs` are recorded here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Earlier releases are recorded
+only in git history.
+
+## Unreleased
+
+### Breaking
+
+- A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
+- A write over a file the reader refuses (a zero-byte file, a truncated store, a stamp this runtime does not read) refuses with `CultCacheStoreUnreadable` and leaves the file as it is. A whole-store write used to replace such a file. This reverses 0.3.1, where `push_all` replaced a file with no readable stamp (healing it); the stamp rule now has one owner, the reader every write asks under the lock, and it accepts v1 and v3 (0.3.1 refused v3).
+
+### Added
+
+- Lookups, matching the C# `GetByName`, `GetByIndex` and `GetGlobal`. `#[cultcache(name)]` and `#[cultcache(index)]` / `#[cultcache(index = "alias")]` on `DatabaseEntry` fields and `#[cultcache(global)]` on the struct give `CultCache::get_by_name`, `get_by_index` and `get_global`. An empty name and a blank index value are not found; records of one type sharing a name or value find the one with the smallest key. A second record of a global type under another key is refused on every write path and on load with `CultCacheSecondGlobal`. Two `name` members, or two members with one index alias, are refused at compile time. A member's text comes from `CultLookupValue` (`String`, `Option` of one, integers, `bool`, `char`).
+- `SchemaConflictError`, the typed refusal of a write the catalog cannot describe: records of different types under one schema id, or an arrived schema and a registered one that share an id and disagree on the schema name. A whole-store write (`push_all`) refuses with it, names the schema id, the names involved and a record key, writes nothing and leaves the file as it is. A caller tells it apart with `error.downcast_ref::<SchemaConflictError>()`.
+
+## [0.3.1]
+
+### Fixed
+- `push_all` reads the store's header under the lock and refuses a format this runtime does
+  not read, with `CultCacheStoreUnreadable` `UnsupportedFormat`, leaving the file as it was.
+  A file with no readable stamp is still replaced, so a whole write heals it.

packages/cultcache-rs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cultcache-rs"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 license = "MIT"
 publish = false

packages/cultcache-rs/README.md

@@ -174,6 +174,9 @@ without pretending Rust has runtime reflection hiding under the floorboards.
 - `get_required_envelope::<T>`
 - `get_all::<T>`
 - `get_all_with_keys::<T>`
+- `get_by_name::<T>`
+- `get_by_index::<T>`
+- `get_global::<T>`
 - `soa::<T>`
 - `put::<T>`
 - `put_envelope::<T>`

packages/cultcache-rs/cultcache-rs-derive/src/lib.rs

@@ -22,6 +22,7 @@ fn database_entry_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStr
     let ident = input.ident.clone();
     let mut entry_type: Option<LitStr> = None;
     let mut schema_name: Option<LitStr> = None;
+    let mut global = false;
 
     for attribute in input
         .attrs
@@ -37,6 +38,12 @@ fn database_entry_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStr
                 once(&schema_name, &meta, "schema")?;
                 schema_name = Some(meta.value()?.parse()?);
                 Ok(())
+            } else if meta.path.is_ident("global") {
+                if global {
+                    return Err(meta.error("repeated `global`: #[cultcache(global)] is given once"));
+                }
+                global = true;
+                Ok(())
             } else {
                 Err(meta.error("unsupported cultcache attribute"))
             }
@@ -54,11 +61,40 @@ fn database_entry_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStr
 
     let slots = named_slots(input.data, &ident, "DatabaseEntry")?;
     let codec = slot_codec(&ident, &slots);
+    let name_member = slots.iter().find(|slot| slot.name).map(|slot| &slot.ident);
+    let name_fn = name_member.map(|member| {
+        quote! {
+            fn cult_name(&self) -> ::std::option::Option<::std::string::String> {
+                ::cultcache_rs::CultLookupValue::lookup_value(&self.#member)
+            }
+        }
+    });
+    let index_members = slots.iter().filter_map(|slot| slot.index.as_ref().map(|alias| (alias, &slot.ident)));
+    let index_pushes = index_members.map(|(alias, member)| {
+        quote! {
+            if let ::std::option::Option::Some(value) = ::cultcache_rs::CultLookupValue::lookup_value(&self.#member) {
+                held.push((#alias, value));
+            }
+        }
+    });
+    let index_pushes: Vec<_> = index_pushes.collect();
+    let indexes_fn = (!index_pushes.is_empty()).then(|| {
+        quote! {
+            fn cult_indexes(&self) -> ::std::vec::Vec<(&'static str, ::std::string::String)> {
+                let mut held = ::std::vec::Vec::new();
+                #(#index_pushes)*
+                held
+            }
+        }
+    });
 
     Ok(quote! {
         impl ::cultcache_rs::DatabaseEntry for #ident {
             const TYPE: &'static str = #entry_type;
             const SCHEMA_NAME: &'static str = #schema_name;
+            const GLOBAL: bool = #global;
+            #name_fn
+            #indexes_fn
         }
 
         #codec
@@ -133,6 +169,8 @@ fn named_slots(data: Data, ident: &syn::Ident, owner: &str) -> syn::Result<Vec<C
         let mut key: Option<usize> = None;
         let mut default = false;
         let mut bytes = false;
+        let mut name = false;
+        let mut index: Option<String> = None;
         for attribute in field
             .attrs
             .iter()
@@ -157,6 +195,22 @@ fn named_slots(data: Data, ident: &syn::Ident, owner: &str) -> syn::Result<Vec<C
                 } else if meta.path.is_ident("bytes") {
                     bytes = true;
                     Ok(())
+                } else if owner == "DatabaseEntry" && meta.path.is_ident("name") {
+                    if name {
+                        return Err(meta.error("repeated `name`: #[cultcache(name)] is given once"));
+                    }
+                    name = true;
+                    Ok(())
+                } else if owner == "DatabaseEntry" && meta.path.is_ident("index") {
+                    once(&index, &meta, "index")?;
+                    // A bare `index`, or an alias that is blank, names the field itself.
+                    let alias = if meta.input.peek(syn::Token![=]) {
+                        meta.value()?.parse::<LitStr>()?.value()
+                    } else {
+                        String::new()
+                    };
+                    index = Some(if alias.trim().is_empty() { field_ident.to_string() } else { alias });
+                    Ok(())
                 } else {
                     Err(meta.error("unsupported field cultcache attribute"))
                 }
@@ -180,8 +234,28 @@ fn named_slots(data: Data, ident: &syn::Ident, owner: &str) -> syn::Result<Vec<C
             ty: field.ty,
             default,
             bytes,
+            name,
+            index,
         });
     }
+    if let Some(second) = slots.iter().filter(|slot| slot.name).nth(1) {
+        return Err(syn::Error::new_spanned(
+            &second.ident,
+            format!("{owner} declares #[cultcache(name)] on more than one member; a record has one name"),
+        ));
+    }
+    for (position, slot) in slots.iter().enumerate() {
+        let Some(alias) = &slot.index else { continue };
+        if let Some(first) = slots[..position].iter().find(|earlier| earlier.index.as_ref() == Some(alias)) {
+            return Err(syn::Error::new_spanned(
+                &slot.ident,
+                format!(
+                    "{owner} members {} and {} both declare index alias \"{alias}\"; an index alias must name one member",
+                    first.ident, slot.ident
+                ),
+            ));
+        }
+    }
     slots.sort_by_key(|slot| slot.key);
     Ok(slots)
 }
@@ -367,6 +441,10 @@ struct CultCacheSlot {
     ty: Type,
     default: bool,
     bytes: bool,
+    /// `#[cultcache(name)]`: the member `get_by_name` finds the record by.
+    name: bool,
+    /// `#[cultcache(index)]` or `#[cultcache(index = "alias")]`: the alias `get_by_index` finds the record by.
+    index: Option<String>,
 }
 
 fn union_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
@@ -842,4 +920,89 @@ mod tests {
         let input: DeriveInput = syn::parse_str(source).expect("the fixture parses");
         named_slots(input.data, &input.ident, "CultSlots").expect("the fixture is accepted");
     }
+    fn entry_error(source: &str) -> String {
+        let input: DeriveInput = syn::parse_str(source).expect("the fixture parses");
+        database_entry_codec(input).expect_err("the fixture is refused").to_string()
+    }
+
+    fn entry_tokens(source: &str) -> String {
+        let input: DeriveInput = syn::parse_str(source).expect("the fixture parses");
+        database_entry_codec(input).expect("the fixture is accepted").to_string().replace(' ', "")
+    }
+
+    #[test]
+    fn name_index_and_global_generate_the_lookup_surface() {
+        let tokens = entry_tokens(
+            r#"#[cultcache(type = "t", global)] struct S {
+                #[cultcache(key = 0, name)] label: String,
+                #[cultcache(key = 1, index)] code: String,
+                #[cultcache(key = 2, index = "sku")] stock: Option<String>,
+            }"#,
+        );
+        assert!(tokens.contains("constGLOBAL:bool=true"), "{tokens}");
+        assert!(tokens.contains("fncult_name"), "{tokens}");
+        assert!(tokens.contains("(\"code\",value)"), "{tokens}");
+        assert!(tokens.contains("(\"sku\",value)"), "{tokens}");
+    }
+
+    #[test]
+    fn a_record_without_lookups_generates_none_of_them() {
+        let tokens = entry_tokens(r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0)] a: String }"#);
+        assert!(tokens.contains("constGLOBAL:bool=false"), "{tokens}");
+        assert!(!tokens.contains("fncult_name") && !tokens.contains("fncult_indexes"), "{tokens}");
+    }
+
+    // ResolveIndexAlias: a blank alias is the member's name.
+    #[test]
+    fn a_blank_index_alias_is_the_member_name() {
+        let tokens = entry_tokens(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, index = "  ")] code: String }"#,
+        );
+        assert!(tokens.contains("(\"code\",value)"), "{tokens}");
+    }
+
+    #[test]
+    fn two_names_are_refused_for_that_reason() {
+        let message = entry_error(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, name)] a: String, #[cultcache(key = 1, name)] b: String }"#,
+        );
+        assert!(message.contains("more than one member"), "{message}");
+    }
+
+    // D10: two members that declare one alias; a bare index is the member name, so it collides with an explicit alias of it.
+    #[test]
+    fn two_members_with_one_index_alias_are_refused_for_that_reason() {
+        let message = entry_error(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, index = "k")] a: String, #[cultcache(key = 1, index = "k")] b: String }"#,
+        );
+        assert!(message.contains("both declare index alias \"k\""), "{message}");
+        let message = entry_error(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, index)] a: String, #[cultcache(key = 1, index = "a")] b: String }"#,
+        );
+        assert!(message.contains("both declare index alias \"a\""), "{message}");
+    }
+
+    #[test]
+    fn a_repeated_lookup_attribute_is_refused() {
+        let message = entry_error(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, name, name)] a: String }"#,
+        );
+        assert!(message.contains("repeated `name`"), "{message}");
+        let message = entry_error(
+            r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, index, index = "x")] a: String }"#,
+        );
+        assert!(message.contains("repeated `index`"), "{message}");
+        let message = entry_error(r#"#[cultcache(type = "t", global, global)] struct S { #[cultcache(key = 0)] a: String }"#);
+        assert!(message.contains("repeated `global`"), "{message}");
+    }
+
+    // Only a DatabaseEntry is looked up: a nested slot record carrying the attributes is refused as before.
+    #[test]
+    fn lookup_attributes_are_refused_on_a_slots_record() {
+        let message = slots_error(r#"struct S { #[cultcache(key = 0, name)] a: String }"#);
+        assert!(message.contains("unsupported field cultcache attribute"), "{message}");
+        let message = slots_error(r#"struct S { #[cultcache(key = 0, index)] a: String }"#);
+        assert!(message.contains("unsupported field cultcache attribute"), "{message}");
+    }
+
 }

packages/cultcache-rs/examples/cultcache_interop.rs

@@ -26,22 +26,72 @@ struct CultCacheInteropNote {
     tags: Vec<String>,
 }
 
+// An object list: each mark is a positional array [label, id], the id an ordinary member at slot 1.
+#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+struct CultCacheInteropMark(String, String);
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "cultcache.interop-deck", schema = "CultCacheInteropDeck")]
+struct CultCacheInteropDeck {
+    #[cultcache(key = 0)]
+    document_id: String,
+    #[cultcache(key = 1, default)]
+    marks: Vec<CultCacheInteropMark>,
+}
+
+fn read_deck(file: &str) -> Result<()> {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<CultCacheInteropDeck>()?;
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(file))?;
+    cache.pull_all_backing_stores()?;
+    let decks = cache.get_all::<CultCacheInteropDeck>()?;
+    let deck = decks
+        .first()
+        .ok_or_else(|| anyhow!("no cultcache.interop-deck records found"))?;
+    println!(
+        "{}",
+        serde_json::to_string(&json!({
+            "documentId": deck.document_id,
+            "ids": deck.marks.iter().map(|mark| mark.1.clone()).collect::<Vec<_>>(),
+        }))?
+    );
+    Ok(())
+}
+
 fn main() -> Result<()> {
     let mut args = std::env::args().skip(1);
     let mode = args
         .next()
-        .ok_or_else(|| anyhow!("expected mode: write | read"))?;
+        .ok_or_else(|| anyhow!("expected mode: write | read | hold-lock"))?;
     let options = parse_args(args.collect());
     let file = require_arg(&options, "file")?;
 
     match mode.as_str() {
         "write" => write_note(file, require_arg(&options, "runtime-id")?)?,
         "read" => read_note(file)?,
+        "read-deck" => read_deck(file)?,
+        "hold-lock" => hold_lock(file, require_arg(&options, "ms")?.parse()?)?,
         _ => return Err(anyhow!("unknown mode {mode}")),
     }
     Ok(())
 }
 
+/// Holds the store lock as the library opens it (`<file>.lock`, fs2 exclusive), for `ms`.
+fn hold_lock(file: &str, ms: u64) -> Result<()> {
+    let lock = std::fs::OpenOptions::new()
+        .create(true)
+        .read(true)
+        .truncate(false)
+        .write(true)
+        .open(format!("{file}.lock"))?;
+    fs2::FileExt::lock_exclusive(&lock)?;
+    println!("{}", json!({ "held": true }));
+    std::io::Write::flush(&mut std::io::stdout())?;
+    std::thread::sleep(std::time::Duration::from_millis(ms));
+    fs2::FileExt::unlock(&lock)?;
+    Ok(())
+}
+
 fn write_note(file: &str, runtime_id: &str) -> Result<()> {
     let mut cache = build_cache(file)?;
     cache.pull_all_backing_stores()?;

packages/cultcache-rs/tests/first_call.rs

@@ -0,0 +1,56 @@
+//! The Rust CultCache first call from docs/start/README.md. The docs show the region between the
+//! `snippet` markers verbatim, and `docs_show_the_tested_snippet` fails when they differ.
+
+use cultcache_rs::{CultCache, DatabaseEntry, SingleFileMessagePackBackingStore};
+
+// snippet:begin
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "item")]
+struct Item {
+    #[cultcache(key = 0)]
+    name: String,
+    #[cultcache(key = 1)]
+    category: String,
+    #[cultcache(key = 2, default)]
+    value: u32,
+}
+
+fn first_call() -> anyhow::Result<()> {
+    let dir = tempfile::tempdir()?;
+    let path = dir.path().join("first-call.cc");
+
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Item>()?;
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path));
+    cache.pull_all_backing_stores()?;
+    cache.put("item:potion", &Item {
+        name: "Potion".to_string(),
+        category: "Consumable".to_string(),
+        value: 50,
+    })?; // written to the .cc file before this returns
+
+    let mut reopened = CultCache::new();
+    reopened.register_entry_type::<Item>()?;
+    reopened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path));
+    reopened.pull_all_backing_stores()?; // read it back
+    let potion = reopened.get_required::<Item>("item:potion")?;
+    assert_eq!(potion.name, "Potion");
+    assert_eq!(potion.value, 50);
+    Ok(())
+}
+// snippet:end
+
+#[test]
+fn first_call_round_trips_through_a_second_cache() {
+    first_call().unwrap();
+}
+
+#[test]
+fn docs_show_the_tested_snippet() {
+    let source = std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/first_call.rs")).unwrap();
+    let begin = source.find("// snippet:begin\n").unwrap() + "// snippet:begin\n".len();
+    let end = source.find("// snippet:end\n").unwrap();
+    let docs = std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/../../docs/start/README.md")).unwrap();
+    let block = format!("```rust\n{}```", &source[begin..end]);
+    assert!(docs.contains(&block), "docs/start/README.md no longer shows tests/first_call.rs verbatim");
+}

packages/cultcache-rs/tests/lookups.rs

@@ -0,0 +1,352 @@
+//! Lookups parity with the C# reference: `GetByName`, `GetByIndex` and `GetGlobal`
+//! (`src/GameCult.Caching/CultCache.cs`) and the one-global rule its commit enforces.
+
+use cultcache_rs::{
+    CacheBackingStore, CultCache, CultCacheSecondGlobal, CultCacheSoaTable, DatabaseEntry,
+    SingleFileMessagePackBackingStore,
+};
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "item")]
+struct Item {
+    #[cultcache(key = 0, name)]
+    name: String,
+    #[cultcache(key = 1, index)]
+    category: String,
+    #[cultcache(key = 2, index = "sku")]
+    code: Option<String>,
+    #[cultcache(key = 3, default)]
+    value: u32,
+}
+
+fn item(name: &str, category: &str, code: Option<&str>) -> Item {
+    Item { name: name.into(), category: category.into(), code: code.map(Into::into), value: 0 }
+}
+
+/// Same names and values as `Item`, a different type: lookups never cross types.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "gadget")]
+struct Gadget {
+    #[cultcache(key = 0, name)]
+    name: String,
+    #[cultcache(key = 1, index)]
+    category: String,
+}
+
+/// Sorts after `Item` and has its exact shape: a lookup that ran past the end of its own type would answer from it.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "zed")]
+struct Zed {
+    #[cultcache(key = 0, name)]
+    name: String,
+    #[cultcache(key = 1, index)]
+    category: String,
+    #[cultcache(key = 2, index = "sku")]
+    code: Option<String>,
+    #[cultcache(key = 3, default)]
+    value: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "settings", global)]
+struct Settings {
+    #[cultcache(key = 0)]
+    value: String,
+}
+
+fn settings(value: &str) -> Settings {
+    Settings { value: value.into() }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "plain")]
+struct Plain {
+    #[cultcache(key = 0)]
+    value: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "numbered")]
+struct Numbered {
+    #[cultcache(key = 0, name)]
+    id: u32,
+    #[cultcache(key = 1, index)]
+    owner: u64,
+}
+
+fn cache() -> CultCache {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Item>().unwrap();
+    cache.register_entry_type::<Gadget>().unwrap();
+    cache.register_entry_type::<Zed>().unwrap();
+    cache.register_entry_type::<Settings>().unwrap();
+    cache.register_entry_type::<Plain>().unwrap();
+    cache.register_entry_type::<Numbered>().unwrap();
+    cache
+}
+
+fn reopened(path: &std::path::Path) -> CultCache {
+    let mut reopened = cache();
+    reopened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path)).unwrap();
+    reopened.pull_all_backing_stores().unwrap();
+    reopened
+}
+
+fn stored_cache(path: &std::path::Path) -> CultCache {
+    let mut stored = cache();
+    stored.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path)).unwrap();
+    stored.pull_all_backing_stores().unwrap();
+    stored
+}
+
+// The C# FirstCall snippet: a record written to a .cc file is found by its [CultName] through a second cache.
+#[test]
+fn a_record_is_found_by_name_and_by_index_after_a_reopen() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("lookups.cc");
+    let mut written = stored_cache(&path);
+    written.put("item:potion", &Item { value: 50, ..item("Potion", "Consumable", Some("P-1")) }).unwrap();
+
+    let reopened = reopened(&path);
+    let by_name = reopened.get_by_name::<Item>("Potion").unwrap().unwrap();
+    assert_eq!(by_name.value, 50);
+    assert_eq!(reopened.get_by_index::<Item>("category", "Consumable").unwrap(), Some(by_name.clone()));
+    assert_eq!(reopened.get_by_index::<Item>("sku", "P-1").unwrap(), Some(by_name));
+}
+
+#[test]
+fn a_missing_name_or_value_is_none_and_an_unregistered_type_is_refused() {
+    let mut cache = cache();
+    cache.put("item:a", &item("A", "cat", Some("a-1"))).unwrap();
+
+    assert_eq!(cache.get_by_name::<Item>("B").unwrap(), None);
+    assert_eq!(cache.get_by_name::<Item>("a").unwrap(), None, "names compare ordinally");
+    assert_eq!(cache.get_by_index::<Item>("category", "other").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("nosuchalias", "cat").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("code", "a-1").unwrap(), None, "the alias is sku, not the member name");
+
+    let bare = CultCache::new();
+    assert!(bare.get_by_name::<Item>("A").is_err());
+    assert!(bare.get_by_index::<Item>("category", "cat").is_err());
+    assert!(bare.get_global::<Settings>().is_err());
+}
+
+#[test]
+fn an_index_without_an_alias_is_named_by_its_member() {
+    let mut cache = cache();
+    cache.put("item:a", &item("A", "cat", None)).unwrap();
+    assert!(cache.get_by_index::<Item>("category", "cat").unwrap().is_some());
+}
+
+// A blank name is no name; a blank index value is not indexed; a nil member holds no value.
+#[test]
+fn blank_and_nil_values_are_not_found() {
+    let mut cache = cache();
+    cache.put("item:blank", &item("", "  ", None)).unwrap();
+    assert_eq!(cache.get_by_name::<Item>("").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("category", "  ").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("category", "").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("sku", "").unwrap(), None);
+
+    // Only emptiness voids a name: whitespace is a name, as in C# (Length > 0).
+    cache.put("item:space", &item(" ", "x", None)).unwrap();
+    assert_eq!(cache.get_by_name::<Item>(" ").unwrap().unwrap().category, "x");
+}
+
+#[test]
+fn lookups_never_cross_types() {
+    let mut cache = cache();
+    cache.put("item:a", &item("same", "same", None)).unwrap();
+    cache.put("gadget:a", &Gadget { name: "same".into(), category: "same".into() }).unwrap();
+    cache.put("zed:a", &Zed { name: "same".into(), category: "same".into(), code: None, value: 0 }).unwrap();
+
+    assert_eq!(cache.get_by_name::<Gadget>("same").unwrap().unwrap().name, "same");
+    cache.delete::<Item>("item:a").unwrap();
+    assert_eq!(cache.get_by_name::<Item>("same").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("category", "same").unwrap(), None);
+    assert!(cache.get_by_name::<Gadget>("same").unwrap().is_some());
+    assert!(cache.get_by_index::<Gadget>("category", "same").unwrap().is_some());
+}
+
+#[test]
+fn a_name_and_index_follow_a_rewritten_record_and_leave_a_removed_one() {
+    let mut cache = cache();
+    cache.put("item:a", &item("old", "c1", None)).unwrap();
+    cache.put("item:a", &item("new", "c2", None)).unwrap();
+
+    assert_eq!(cache.get_by_name::<Item>("old").unwrap(), None, "a stale name is not found");
+    assert_eq!(cache.get_by_index::<Item>("category", "c1").unwrap(), None, "a stale value is not found");
+    assert!(cache.get_by_name::<Item>("new").unwrap().is_some());
+    assert!(cache.get_by_index::<Item>("category", "c2").unwrap().is_some());
+
+    cache.delete::<Item>("item:a").unwrap();
+    assert_eq!(cache.get_by_name::<Item>("new").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("category", "c2").unwrap(), None);
+}
+
+#[test]
+fn non_string_members_are_found_by_their_text() {
+    let mut cache = cache();
+    let owner = 161_u64;
+    cache.put("numbered:1", &Numbered { id: 42, owner }).unwrap();
+    assert!(cache.get_by_name::<Numbered>("42").unwrap().is_some());
+    assert!(cache.get_by_index::<Numbered>("owner", "161").unwrap().is_some());
+}
+
+// VariantTests.RemovingTheHolderADuplicateValueFindsLeavesTheOtherFindable: records sharing a value find the one with
+// the smallest key, whatever the write order, live and after a reopen; removing the holder finds the other.
+#[test]
+fn records_sharing_a_value_find_the_smallest_key_and_removing_it_finds_the_next() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("shared.cc");
+    {
+        let mut cache = stored_cache(&path);
+        cache.put("item:p2", &item("p2", "x", None)).unwrap();
+        cache.put("item:p1", &item("p1", "x", None)).unwrap();
+        let found = |cache: &CultCache| cache.get_by_index::<Item>("category", "x").unwrap().map(|found| found.name);
+        assert_eq!(found(&cache).as_deref(), Some("p1"), "the smallest key, though written second");
+        assert_eq!(reopened(&path).get_by_index::<Item>("category", "x").unwrap().unwrap().name, "p1");
+
+        cache.delete::<Item>("item:p1").unwrap();
+        assert_eq!(found(&cache).as_deref(), Some("p2"), "removing the holder finds the other one");
+
+        cache.put("item:p1", &item("p1", "x", None)).unwrap();
+        assert_eq!(found(&cache).as_deref(), Some("p1"));
+        cache.delete::<Item>("item:p2").unwrap();
+        assert_eq!(found(&cache).as_deref(), Some("p1"), "removing the other changes nothing");
+        cache.delete::<Item>("item:p1").unwrap();
+        assert_eq!(found(&cache), None);
+    }
+    assert_eq!(reopened(&path).get_by_index::<Item>("category", "x").unwrap(), None);
+}
+
+#[test]
+fn records_sharing_a_name_find_the_smallest_key() {
+    let mut cache = cache();
+    cache.put("item:b", &Item { value: 2, ..item("twin", "c", None) }).unwrap();
+    cache.put("item:a", &Item { value: 1, ..item("twin", "c", None) }).unwrap();
+    assert_eq!(cache.get_by_name::<Item>("twin").unwrap().unwrap().value, 1);
+    cache.delete::<Item>("item:a").unwrap();
+    assert_eq!(cache.get_by_name::<Item>("twin").unwrap().unwrap().value, 2);
+}
+
+// BackingStoreTests.HydratesPersistedGlobal: opening a store invents no global; a written one survives a reopen.
+#[test]
+fn a_global_is_none_until_written_and_survives_a_reopen() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("global.cc");
+    {
+        let mut seed = stored_cache(&path);
+        assert_eq!(seed.get_global::<Settings>().unwrap(), None, "opening a store invented a global");
+        seed.put("global:settings", &settings("durable authority")).unwrap();
+        assert_eq!(seed.get_global::<Settings>().unwrap(), Some(settings("durable authority")));
+    }
+    assert_eq!(reopened(&path).get_global::<Settings>().unwrap(), Some(settings("durable authority")));
+}
+
+#[test]
+fn a_type_that_is_not_a_global_has_no_global() {
+    let mut cache = cache();
+    cache.put("plain:one", &Plain { value: "v".into() }).unwrap();
+    assert_eq!(cache.get_global::<Plain>().unwrap(), None);
+}
+
+#[test]
+fn a_second_global_under_another_key_is_refused_and_writes_nothing() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("second.cc");
+    let mut cache = stored_cache(&path);
+    cache.put("g1", &settings("one")).unwrap();
+
+    let refusal = cache.put("g2", &settings("two")).unwrap_err();
+    let second = refusal.downcast_ref::<CultCacheSecondGlobal>().expect("a typed refusal");
+    assert_eq!((second.existing_key.as_str(), second.key.as_str()), ("g1", "g2"));
+    assert!(refusal.to_string().contains("is a global and already has record g1; g2 would be a second."));
+    assert_eq!(cache.get_global::<Settings>().unwrap(), Some(settings("one")));
+    assert_eq!(reopened(&path).get_global::<Settings>().unwrap(), Some(settings("one")), "nothing reached the store");
+
+    // The same key is the same record, not a second.
+    cache.put("g1", &settings("one again")).unwrap();
+    assert_eq!(cache.get_global::<Settings>().unwrap(), Some(settings("one again")));
+}
+
+// RetypeEvictionTests.EvictingAGlobalFreesItsSlot: removing the global frees the slot for another key.
+#[test]
+fn removing_a_global_frees_its_slot() {
+    let mut cache = cache();
+    cache.put("g1", &settings("one")).unwrap();
+    assert!(cache.put("g2", &settings("two")).is_err());
+    cache.delete::<Settings>("g1").unwrap();
+    assert_eq!(cache.get_global::<Settings>().unwrap(), None);
+    cache.put("g2", &settings("two")).unwrap();
+    assert_eq!(cache.get_global::<Settings>().unwrap(), Some(settings("two")));
+}
+
+#[test]
+fn every_write_path_refuses_a_second_global() {
+    let mut cache = cache();
+    cache.put("g1", &settings("one")).unwrap();
+    let (second, _) = cache.prepare_entry("g2", &settings("two")).unwrap();
+
+    assert!(cache.put_envelope::<Settings>(second.clone()).unwrap_err().is::<CultCacheSecondGlobal>());
+    assert!(cache.put_raw_envelope(second.clone()).unwrap_err().is::<CultCacheSecondGlobal>());
+    let (plain, _) = cache.prepare_entry("plain:1", &Plain { value: "v".into() }).unwrap();
+    assert!(cache.put_prepared_batch(vec![plain, second]).unwrap_err().is::<CultCacheSecondGlobal>());
+    assert_eq!(cache.get::<Plain>("plain:1").unwrap(), None, "a refused batch lands none of it");
+    assert_eq!(cache.get_global::<Settings>().unwrap(), Some(settings("one")));
+}
+
+#[test]
+fn a_batch_that_stages_two_globals_is_refused_whole() {
+    let mut cache = cache();
+    let (one, _) = cache.prepare_entry("g1", &settings("one")).unwrap();
+    let (two, _) = cache.prepare_entry("g2", &settings("two")).unwrap();
+    assert!(cache.put_prepared_batch(vec![one, two]).unwrap_err().is::<CultCacheSecondGlobal>());
+    assert_eq!(cache.get_global::<Settings>().unwrap(), None);
+}
+
+// StoreRoutingTests: a store holding two globals is refused on load rather than answering one of them.
+#[test]
+fn loading_a_store_that_holds_two_globals_is_refused() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("two.cc");
+    let source = cache();
+    let mut store = SingleFileMessagePackBackingStore::new(&path);
+    for (key, value) in [("g1", "one"), ("g2", "two")] {
+        let (entry, _) = source.prepare_entry(key, &settings(value)).unwrap();
+        store.push(&entry).unwrap();
+    }
+
+    let mut loading = cache();
+    loading.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    assert!(loading.pull_all_backing_stores().unwrap_err().is::<CultCacheSecondGlobal>());
+    assert_eq!(loading.get_global::<Settings>().unwrap(), None, "a refused load installs nothing");
+}
+
+// load_soa installs a whole table at once, so the one-global rule has to hold there too: a table holding two
+// records of a global type is refused whole and the prior view survives.
+#[test]
+fn loading_an_soa_table_that_holds_two_globals_is_refused() {
+    let source = cache();
+    let (first, _) = source.prepare_entry("g1", &settings("one")).unwrap();
+    let (second, _) = source.prepare_entry("g2", &settings("two")).unwrap();
+
+    let mut loading = cache();
+    loading.put("g0", &settings("prior")).unwrap();
+    loading.put("plain:1", &Plain { value: "prior".into() }).unwrap();
+
+    let refusal = loading
+        .load_soa(CultCacheSoaTable::from_envelopes(vec![first.clone(), second]))
+        .unwrap_err();
+    let second_global = refusal.downcast_ref::<CultCacheSecondGlobal>().expect("a typed refusal");
+    let mut named = [second_global.existing_key.as_str(), second_global.key.as_str()];
+    named.sort();
+    assert_eq!(named, ["g1", "g2"], "the refusal names both records");
+    assert_eq!(loading.get_global::<Settings>().unwrap(), Some(settings("prior")), "a refused load keeps the prior view");
+    assert_eq!(loading.get::<Plain>("plain:1").unwrap(), Some(Plain { value: "prior".into() }));
+
+    // One global in the table is the rule's own case, not a second.
+    loading.load_soa(CultCacheSoaTable::from_envelopes(vec![first])).unwrap();
+    assert_eq!(loading.get_global::<Settings>().unwrap(), Some(settings("one")));
+    assert_eq!(loading.get::<Plain>("plain:1").unwrap(), None, "a load replaces the view");
+}

packages/cultcache-rs/tests/union_parity.rs

@@ -32,6 +32,8 @@ enum Node {
 struct WrapArm {
     #[cultcache(key = 0)]
     inner: Option<std::boxed::Box<Node>>,
+    #[cultcache(key = 1)]
+    id: String,
 }
 
 #[derive(Clone, Debug, PartialEq, CultSlots)]
@@ -85,6 +87,17 @@ enum Outcome {
     Pending(PendingArm),
     #[cultcache(key = 1)]
     Completed(CompletedArm),
+    #[cultcache(key = 2)]
+    Denied(IdArm),
+    #[cultcache(key = -2147483648)]
+    Floor(IdArm),
+    #[cultcache(key = 2147483647)]
+    Ceiling(IdArm),
+}
+
+// The codec's unit arm (no members, written [key, []]), kept apart from the golden: a document list's arms carry ids.
+#[derive(Clone, Debug, PartialEq, CultUnion)]
+enum UnitOutcome {
     #[cultcache(key = 2)]
     Denied,
     #[cultcache(key = -2147483648)]
@@ -97,12 +110,23 @@ enum Outcome {
 struct PendingArm {
     #[cultcache(key = 0)]
     message: String,
+    #[cultcache(key = 1)]
+    id: String,
+}
+
+// An arm with no members of its own: just its element id.
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+struct IdArm {
+    #[cultcache(key = 0)]
+    id: String,
 }
 
 #[derive(Clone, Debug, PartialEq, CultSlots)]
 struct CompletedArm {
     #[cultcache(key = 0)]
     source_version: i32,
+    #[cultcache(key = 1)]
+    id: String,
 }
 
 #[derive(Clone, Debug, PartialEq, CultSlots)]
@@ -178,26 +202,26 @@ fn boxed(id: &str, children: Vec<Node>) -> Node {
 }
 
 fn constructed() -> UnionSurface {
-    let inner = boxed("inner", vec![text("deep", "x"), image("img", "uri://a", "alt")]);
+    let inner = boxed("0000000000d0", vec![text("0000000000d1", "x"), image("0000000000d2", "uri://a", "alt")]);
     UnionSurface {
         id: "surface".into(),
         version: 3,
         root: Some(boxed(
-            "root",
+            "0000000000c0",
             vec![
-                text("t1", "hello"),
+                text("0000000000c1", "hello"),
                 Node::Use(UseArm {
-                    id: "u1".into(),
+                    id: "0000000000c2".into(),
                     composition: Composition { name: "comp".into(), body: Some(std::boxed::Box::new(inner)) },
-                    slots: vec![Some(text("s1", "slot")), None, Some(boxed("b2", vec![]))],
+                    slots: vec![Some(text("0000000000e1", "slot")), None, Some(boxed("0000000000e2", vec![]))],
                 }),
-                image("i2", "uri://b", ""),
+                image("0000000000c3", "uri://b", ""),
             ],
         )),
         outcomes: vec![
-            Outcome::Pending(PendingArm { message: "wait".into() }),
-            Outcome::Completed(CompletedArm { source_version: 7 }),
-            Outcome::Denied,
+            Outcome::Pending(PendingArm { message: "wait".into(), id: "0000000000a1".into() }),
+            Outcome::Completed(CompletedArm { source_version: 7, id: "0000000000a2".into() }),
+            Outcome::Denied(id_arm("0000000000a3")),
         ],
         part: Some(Item::Tool(UsesArm { name: "hammer".into(), uses: 12 })),
         crafted: Some(CraftedItem::Part(CountArm { name: "gear".into(), count: 4 })),
@@ -205,6 +229,10 @@ fn constructed() -> UnionSurface {
     }
 }
 
+fn id_arm(id: &str) -> IdArm {
+    IdArm { id: id.into() }
+}
+
 fn vector(name: &str) -> Vec<u8> {
     let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
         .join("../../tests/vectors/union-parity")
@@ -226,8 +254,25 @@ fn union_surface_decodes_and_reencodes() {
 
 #[test]
 fn a_unit_arm_is_a_key_and_an_empty_slots_array() {
-    assert_eq!(rmp_serde::to_vec(&Outcome::Denied).unwrap(), [0x92, 0x02, 0x90]);
-    assert_eq!(rmp_serde::from_slice::<Outcome>(&[0x92, 0x02, 0x90]).unwrap(), Outcome::Denied);
+    // The bytes are the C# reference's, not spelled here.
+    for (file, arm) in [
+        ("unit-arm-denied.msgpack", UnitOutcome::Denied),
+        ("unit-arm-floor.msgpack", UnitOutcome::Floor),
+        ("unit-arm-ceiling.msgpack", UnitOutcome::Ceiling),
+    ] {
+        let reference = vector(file);
+        assert_eq!(rmp_serde::to_vec(&arm).unwrap(), reference, "{file}");
+        assert_eq!(rmp_serde::from_slice::<UnitOutcome>(&reference).unwrap(), arm, "{file}");
+    }
+}
+
+#[test]
+fn an_id_only_arm_is_a_key_and_a_one_slot_array() {
+    let mut bytes = vec![0x92, 0x02, 0x91, 0xac];
+    bytes.extend_from_slice(b"0000000000a3");
+    let denied = Outcome::Denied(id_arm("0000000000a3"));
+    assert_eq!(rmp_serde::to_vec(&denied).unwrap(), bytes);
+    assert_eq!(rmp_serde::from_slice::<Outcome>(&bytes).unwrap(), denied);
 }
 
 #[test]
@@ -246,7 +291,7 @@ fn union_refusal_vectors() {
                     let key = key.expect(&file);
                     assert!(message.contains(&format!("unknown arm key {key} ")), "{file}: {message}");
                 }
-                for canary in ["root", "hello", "uri://", "surface"] {
+                for canary in ["0000000000c0", "hello", "uri://", "surface"] {
                     assert!(!message.contains(canary), "{file} echoed a value: {message}");
                 }
             }
@@ -287,8 +332,8 @@ fn a_union_that_is_not_a_key_and_slots_pair_is_refused_naming_the_enum() {
         ("a unit arm with slots", rmp_serde::to_vec(&(2u64, ("CANARY-slot",))).unwrap()),
     ];
     for (label, bytes) in cases {
-        let message = rmp_serde::from_slice::<Outcome>(&bytes).unwrap_err().to_string();
-        assert!(message.contains("Outcome"), "{label}: {message}");
+        let message = rmp_serde::from_slice::<UnitOutcome>(&bytes).unwrap_err().to_string();
+        assert!(message.contains("UnitOutcome"), "{label}: {message}");
         assert!(!message.contains("CANARY"), "{label}: {message}");
     }
 }
@@ -679,9 +724,9 @@ fn bounds_vectors() {
                 let value = result.unwrap_or_else(|message| panic!("{file}: {message}"));
                 assert_eq!(rmp_serde::to_vec(&value).unwrap(), vector(detail), "{file}");
                 match file {
-                    "arm-key-int32-min.msgpack" => assert_eq!(value.outcomes.last(), Some(&Outcome::Floor)),
+                    "arm-key-int32-min.msgpack" => assert_eq!(value.outcomes.last(), Some(&Outcome::Floor(id_arm("0000000000a4")))),
                     "arm-key-int32-max.msgpack" | "arm-key-wide-coding.msgpack" => {
-                        assert_eq!(value.outcomes.last(), Some(&Outcome::Ceiling))
+                        assert_eq!(value.outcomes.last(), Some(&Outcome::Ceiling(id_arm("0000000000a5"))))
                     }
                     _ => {}
                 }
@@ -715,7 +760,7 @@ fn bounds_vectors() {
 fn wrap_chain(wraps: usize, leaf: Node) -> UnionSurface {
     let mut node = leaf;
     for _ in 0..wraps {
-        node = Node::Wrap(WrapArm { inner: Some(std::boxed::Box::new(node)) });
+        node = Node::Wrap(WrapArm { inner: Some(std::boxed::Box::new(node)), id: "0000000000b1".into() });
     }
     UnionSurface { root: Some(node), ..constructed() }
 }
@@ -724,9 +769,9 @@ fn wrap_chain(wraps: usize, leaf: Node) -> UnionSurface {
 // children) ends at 2 * (wraps + 1) + 2 and a Text leaf at 2 * (wraps + 1) + 1.
 #[test]
 fn the_constructed_chains_write_the_vector_bytes() {
-    let at_limit = wrap_chain(126, boxed("leaf", vec![]));
+    let at_limit = wrap_chain(126, boxed("0000000000f0", vec![]));
     assert_eq!(rmp_serde::to_vec(&at_limit).unwrap(), vector("depth-at-limit.msgpack"));
-    let past_limit = wrap_chain(127, text("leaf", CANARY));
+    let past_limit = wrap_chain(127, text("0000000000f0", CANARY));
     assert_eq!(rmp_serde::to_vec(&past_limit).unwrap(), vector("depth-past-limit.msgpack"));
 }
 
@@ -744,14 +789,14 @@ fn write_refused_past_limit() {
     cache.register_entry_type::<UnionSurface>().unwrap();
     cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
 
-    let at_limit = wrap_chain(126, boxed("leaf", vec![]));
+    let at_limit = wrap_chain(126, boxed("0000000000f0", vec![]));
     assert_eq!(cache.put("at", &at_limit).unwrap(), at_limit);
     let stored = cache.snapshot_envelopes();
     assert_eq!(stored.len(), 1);
     assert_eq!(stored[0].payload, vector("depth-at-limit.msgpack"));
     let file_before = std::fs::read(&path).unwrap();
 
-    let error = cache.put("past", &wrap_chain(127, text("leaf", CANARY))).unwrap_err();
+    let error = cache.put("past", &wrap_chain(127, text("0000000000f0", CANARY))).unwrap_err();
     assert_eq!(error.downcast_ref::<PayloadTooDeep>(), Some(&PayloadTooDeep { depth: 257, limit: 256 }));
     assert!(!format!("{error:#}").contains(CANARY), "{error:#}");
     assert_eq!(cache.get::<UnionSurface>("past").unwrap(), None);
@@ -808,8 +853,8 @@ fn raw(type_name: &str, key: &str, payload: Vec<u8>) -> CultCacheEnvelope {
 
 #[test]
 fn the_raw_doors_hold_the_bound_for_arms_maps_and_arrays() {
-    let arms_at = rmp_serde::to_vec(&wrap_chain(126, boxed("leaf", vec![]))).unwrap();
-    let arms_past = rmp_serde::to_vec(&wrap_chain(127, text("leaf", CANARY))).unwrap();
+    let arms_at = rmp_serde::to_vec(&wrap_chain(126, boxed("0000000000f0", vec![]))).unwrap();
+    let arms_past = rmp_serde::to_vec(&wrap_chain(127, text("0000000000f0", CANARY))).unwrap();
     let maps_at = rmp_serde::to_vec_named(&map_doc(MAX_PAYLOAD_DEPTH - 1)).unwrap();
     let maps_past = rmp_serde::to_vec_named(&map_doc(MAX_PAYLOAD_DEPTH)).unwrap();
     let arrays_at = vector("depth-at-limit.msgpack");
@@ -857,13 +902,13 @@ fn the_union_chain_at_the_limit_decodes_on_a_1mib_thread() {
         .spawn(|| {
             assert_eq!(
                 through_cache(&vector("depth-at-limit.msgpack")).unwrap(),
-                wrap_chain(126, boxed("leaf", vec![]))
+                wrap_chain(126, boxed("0000000000f0", vec![]))
             );
             let refused = through_cache(&vector("depth-past-limit.msgpack")).unwrap_err();
             assert!(refused.contains("the limit is 256"), "{refused}");
             let mut cache = CultCache::new();
             cache.register_entry_type::<UnionSurface>().unwrap();
-            let value = wrap_chain(126, boxed("leaf", vec![]));
+            let value = wrap_chain(126, boxed("0000000000f0", vec![]));
             assert_eq!(cache.put("at", &value).unwrap(), value);
             assert_eq!(cache.get::<UnionSurface>("at").unwrap(), Some(value));
             let mut deep = vec![0x91u8; 100_000];

packages/cultcache-ts/CHANGELOG.md

@@ -3,9 +3,47 @@
 All notable changes to `@gamecult/cultcache-ts` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.14.1]
+## [0.15.0]
+
+0.14.1 and 0.14.2 were never tagged or published; this entry carries them with the Unreleased work, and `cultcache-ts-v0.14.0` is the previous release.
+
+### Breaking
+
+- A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
+- A single-file store refuses a zero-byte file as `StoreUnreadableError`; only a path with nothing at it is an empty store. A header this runtime does not read is refused, and the refusal echoes the header only as `cultcache.store.v<digits>`.
+- A write over a file the reader refuses (`StoreUnreadableError`, from `push`, `pushAll` and `delete`) refuses and leaves the file as it is. A flush used to replace such a file. A write set cannot merge with a disk it cannot read, so the file is repaired or removed by its owner before the store writes again. A full `pushAll` over a file with no readable stamp does not replace it: the reader refuses it. The stamp rule has one owner, `refuseUnreadFormat`, asked only by the one reader that every write consults under the lock. The reader judges the stamp from the header before it decodes the body, so a newer store is refused by name whether or not its body is whole.
+- A dangling symbolic link at the store path is an I/O error with code `ENOENT`, not an empty store.
 
 ### Added
+
+- `@gamecult/cultcache-ts/browser`, also what a bundler resolves for the package root under the `browser` export condition: the root surface without `SingleFileMessagePackBackingStore` and `readSingleFileStore`, so it imports no `node:*` built-in and no `koffi` and bundles with esbuild `platform: "browser"`. The Node entry exports exactly what it did.
+- `readSingleFileStore(path)`, the one synchronous reader of a single-file store, for consumers that must read a store file rather than decode it themselves. `pullAll`, `push`, `delete` and `pushAll` ask the same reader.
+- `StoreUnreadableError` for a store file this runtime cannot read, `SchemaConflictError` for a write the catalog cannot describe, and `schemaIdentityOf` with its result type `CultCacheSchemaIdentity` (`schemaId`, `schemaName`, `schemaVersion`, `compatibleSchemaIds`), the one derivation of a definition's identity.
+- The document payload codec, exported from `@gamecult/cultcache-ts/document`: `decodeDocumentPayload`, `encodeDocumentPayload`, and the two named byte escapes `documentPayloadFromBytes` and `documentPayloadBytes`.
+- `SingleFileStoreRead`, exported: the result type of `readSingleFileStore` (`absent`, `format`, `envelopes`, `repairedLegacyPayload`).
+- `CultCacheInspection.format` is `StoreFormat | "legacy.envelope-array"`: it reports `cultcache.store.v3` for a v3 store.
+- A soft `pushAll` writes only where nothing is at the path, leaves a store it can read byte for byte, and refuses what the reader refuses.
+- `SingleFileMessagePackBackingStore` takes a cross-process write lock on `<file>.lock`,
+  interoperable with the C# and Rust runtimes (`flock` on Unix, `LockFileEx` on Windows).
+  `push` and `delete` read the current file, merge and replace it under the lock, so concurrent
+  TypeScript and Rust writers no longer lose each other's records across those calls. A full
+  `pushAll` still replaces the whole store, so records a concurrent writer added are lost to it.
+  C# writes are not all alike: a conditional commit on a clean store lands onto the file as it
+  is, but C# writers can still overwrite records a concurrent TypeScript writer added.
+- The staged file is fsynced before the replace, and on Unix the directory after it. A
+  directory sync failure after the replace is reported as replaced but not durable.
 - `checkPayloadDepth` is re-exported from `@gamecult/cultcache-ts/document`, so dependents
   (`cultnet-ts/content`) bound payload nesting with the same check the cache
   applies on decode.
+
+### Changed
+
+- The Windows replace is a POSIX-semantics rename first (it lands while C# and Rust readers
+  hold the store open), falling back to a write-through `MoveFileExW`, with 25 attempts 20 ms
+  apart on errors 5, 32 and 33. Writers wait up to 30 s for the lock.
+- Opening a legacy store that needs healing rewrites it under the lock, from a read taken
+  under the lock.
+
+### Dependencies
+
+- `koffi` 3.3.0, loaded only on the first write.

packages/cultcache-ts/README.md

@@ -61,7 +61,7 @@ const note = decodeDocumentPayload(noteDocument, envelope.payload); // parsed No
 const payload = encodeDocumentPayload(noteDocument, note); // DocumentPayload
 ```
 
-Browsers import the same names from `@gamecult/cultcache-ts/document`, which holds no Node built-ins.
+Browsers import the same names from `@gamecult/cultcache-ts/document`, which holds no Node built-ins. The whole cache without the single-file store is `@gamecult/cultcache-ts/browser`, which is also what bundlers resolve for the package root (`browser` condition); bring your own `CacheBackingStore`.
 
 ## `.cc` Inspection
 
@@ -358,7 +358,8 @@ That is the TypeScript version of the original CultCache trick:
 - each record is `[key, schemaId, storedAt, payload]`
 - each catalog entry is `[schemaId, schemaName, schemaVersion, contentHash, canonicalSchemaJson, compatibleSchemaIds, members]`
 - it still reads the older TS/Rust-style envelope array and rewrites repaired legacy payloads as v1 snapshots
-- it queues local writes so one process does not step on its own shoelaces
+- it queues local writes in order, then takes the shared `<file>.lock` (`flock` on Unix, `LockFileEx` on Windows, via koffi, loaded on the first write) for each one, so C#, Rust and TypeScript writers exclude each other; the read a write merges from is taken under that lock
+- it fsyncs the staged file and, on Unix, the directory after the replace; on Windows it replaces with a POSIX-semantics rename and falls back to a write-through `MoveFileExW`, retrying briefly on sharing violations
 - it persists raw MessagePack payload bytes inside schema-addressed records
 
-It is a control-plane store, not a tiny god. If multiple processes hammer the same file, you still need a coordinator or an external lock instead of prayer.
+It is a control-plane store, not a tiny god: every write rewrites the whole file.

packages/cultcache-ts/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@gamecult/cultcache-ts",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "CultCache-style typed persistence for TypeScript with schema-backed polymorphic MessagePack storage.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "require": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
     "./document": {
       "types": "./dist/document.d.ts",
       "require": "./dist/document.js",
@@ -25,6 +31,9 @@
     "*": {
       "document": [
         "dist/document.d.ts"
+      ],
+      "browser": [
+        "dist/browser.d.ts"
       ]
     }
   },
@@ -61,6 +70,7 @@
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3",
+    "koffi": "3.3.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {

packages/cultcache-ts/src/browser.ts

@@ -0,0 +1,49 @@
+// Browser-safe surface: everything the package root exports except the node-only single-file store
+// (node:fs, koffi). Bring your own CacheBackingStore, or none.
+export * as codecs from "./codec";
+export type { Codec, SlotsCodec } from "./codec";
+export { CultCache, CultCacheBuilder } from "./cult-cache";
+export { inspectCultCacheBytes } from "./cult-cache-inspector";
+export {
+  decodeDocumentPayload,
+  defineDocumentRegistry,
+  defineDocumentType,
+  documentPayloadBytes,
+  documentPayloadFromBytes,
+  encodeDocumentPayload,
+  schemaIdentityOf,
+  type CultCacheSchemaIdentity,
+} from "./document";
+export { CultCachePayloadDepthError, MAX_PAYLOAD_DEPTH } from "./payload-depth";
+export type { DocumentPayload } from "./document";
+export { SchemaConflictError, StoreUnreadableError } from "./store-format";
+export type {
+  AnyCultCacheDocumentDefinition,
+  CacheBackingStore,
+  CultCacheDocumentAccessor,
+  CultCacheDocumentDefinition,
+  CultCacheDocumentFieldName,
+  CultCacheDocumentFormatter,
+  CultCacheDocumentIndexDefinition,
+  CultCacheDocumentRegistry,
+  CultCacheSchemaCatalogEntry,
+  CultCacheSchemaCatalogMember,
+  CultCacheSchema,
+  CultCacheDocumentValue,
+  CultCacheEnvelope,
+  CultCacheIndexScalar,
+  InferCultCacheSchemaValue,
+  CultCacheStoreRegistration,
+  PushAllOptions,
+} from "./types";
+export type {
+  CultCacheInspection,
+  InspectedCatalogEntry,
+  InspectedCatalogMember,
+  InspectedRecord,
+} from "./cult-cache-inspector";
+export {
+  defineSwarmDocuments,
+  type DefineDocumentType,
+  type SwarmDocumentCatalog,
+} from "./swarm-documents";

packages/cultcache-ts/src/cult-cache-inspector.ts

@@ -1,12 +1,12 @@
 import { decode } from "@msgpack/msgpack";
 
 import { checkPayloadDepth } from "./payload-depth";
-import { STORE_FORMAT_VERSION, isV1Snapshot, requireV1RecordSlots } from "./store-format";
+import { type StoreFormat, isStoreSnapshot, refuseUnreadStoreBytes, requireStoreSlots, requireV1RecordSlots } from "./store-format";
 
 export interface CultCacheInspection {
   filePath: string;
   fileSizeBytes: number;
-  format: "cultcache.store.v1" | "legacy.envelope-array";
+  format: StoreFormat | "legacy.envelope-array";
   catalog: InspectedCatalogEntry[];
   records: InspectedRecord[];
 }
@@ -47,9 +47,10 @@ export function inspectCultCacheBytes(
   bytes: Uint8Array,
   fileSizeBytes = bytes.length,
 ): CultCacheInspection {
+  refuseUnreadStoreBytes(bytes);
   const decoded = decode(bytes);
 
-  if (isV1Snapshot(decoded)) {
+  if (isStoreSnapshot(decoded)) {
     return inspectV1Snapshot(filePath, fileSizeBytes, decoded);
   }
 
@@ -60,7 +61,8 @@ export function inspectCultCacheBytes(
   throw new Error("CultCache file is not a recognized v1 snapshot or legacy envelope array.");
 }
 
-function inspectV1Snapshot(filePath: string, fileSizeBytes: number, decoded: unknown[]): CultCacheInspection {
+function inspectV1Snapshot(filePath: string, fileSizeBytes: number, decoded: [StoreFormat, ...unknown[]]): CultCacheInspection {
+  requireStoreSlots(decoded);
   const catalogRaw = decoded[1];
   const recordsRaw = decoded[2];
   if (!Array.isArray(catalogRaw) || !Array.isArray(recordsRaw)) {
@@ -68,36 +70,25 @@ function inspectV1Snapshot(filePath: string, fileSizeBytes: number, decoded: unk
   }
 
   const catalog = catalogRaw.map(decodeCatalogEntry);
+  // An id names the entry that owns it; only an id no entry owns names the entry that lists it as compatible.
   const catalogBySchemaId = new Map<string, InspectedCatalogEntry>();
   for (const entry of catalog) {
-    catalogBySchemaId.set(entry.schemaId, entry);
-    for (const compatibleSchemaId of entry.compatibleSchemaIds) {
-      catalogBySchemaId.set(compatibleSchemaId, entry);
+    if (!catalogBySchemaId.has(entry.schemaId)) {
+      catalogBySchemaId.set(entry.schemaId, entry);
     }
   }
-  const records = recordsRaw.map((record) => decodeV1Record(record, catalogBySchemaId));
-  for (const record of records) {
-    if (!catalog.some((entry) => entry.schemaId === record.schemaId)) {
-      const schemaVersion = inferSchemaVersionFromPayloadPreview(record.payloadPreview);
-      const schemaName = schemaVersion ? inferSchemaName(schemaVersion) : undefined;
-      if (schemaName) {
-        catalog.push({
-          schemaId: record.schemaId,
-          schemaName,
-          schemaVersion: schemaVersion!,
-          contentHash: record.schemaId,
-          canonicalSchemaJson: "",
-          compatibleSchemaIds: [],
-          members: [],
-        });
+  for (const entry of catalog) {
+    for (const compatibleSchemaId of entry.compatibleSchemaIds) {
+      if (!catalogBySchemaId.has(compatibleSchemaId)) {
+        catalogBySchemaId.set(compatibleSchemaId, entry);
       }
     }
   }
-
+  const records = recordsRaw.map((record) => decodeV1Record(record, catalogBySchemaId));
   return {
     filePath,
     fileSizeBytes,
-    format: STORE_FORMAT_VERSION,
+    format: decoded[0],
     catalog,
     records,
   };
@@ -205,64 +196,21 @@ function decodeV1Record(value: unknown, catalogBySchemaId: Map<string, Inspected
   }
 
   const payloadBytes = normalizePayloadBytes(payload);
-  const catalogEntry = catalogBySchemaId.get(schemaId) ?? recoverCatalogEntry(schemaId, payloadBytes);
+  const catalogEntry = catalogBySchemaId.get(schemaId);
+  if (!catalogEntry) {
+    throw new Error(`CultCache persisted record "${key}" references missing schema id "${schemaId}".`);
+  }
+
   return {
     key,
     schemaId,
-    schemaName: catalogEntry?.schemaName ?? "<missing catalog entry>",
+    schemaName: catalogEntry.schemaName,
     storedAt,
     payloadBytes: payloadBytes.length,
     ...previewPayload(payloadBytes),
   };
 }
 
-function recoverCatalogEntry(schemaId: string, payload: Uint8Array): InspectedCatalogEntry | undefined {
-  let payloadPreview: unknown;
-  try {
-    payloadPreview = decodeBoundedPayload(payload);
-  } catch {
-    return undefined;
-  }
-
-  const schemaVersion = inferSchemaVersionFromPayloadPreview(payloadPreview);
-  if (!schemaVersion) {
-    return undefined;
-  }
-
-  const schemaName = inferSchemaName(schemaVersion);
-  if (!schemaName) {
-    return undefined;
-  }
-
-  return {
-    schemaId,
-    schemaName,
-    schemaVersion,
-    contentHash: schemaId,
-    canonicalSchemaJson: "",
-    compatibleSchemaIds: [],
-    members: [],
-  };
-}
-
-function inferSchemaVersionFromPayloadPreview(payloadPreview: unknown): string | undefined {
-  if (Array.isArray(payloadPreview) && typeof payloadPreview[0] === "string") {
-    return payloadPreview[0];
-  }
-
-  if (isRecord(payloadPreview)) {
-    const schemaVersion = payloadPreview.schemaVersion ?? payloadPreview.schema_version;
-    return typeof schemaVersion === "string" ? schemaVersion : undefined;
-  }
-
-  return undefined;
-}
-
-function inferSchemaName(schemaVersion: string): string | undefined {
-  const match = /^(.*)\.v\d+$/.exec(schemaVersion);
-  return match?.[1];
-}
-
 function decodeLegacyEnvelope(value: unknown): InspectedRecord {
   if (!isRecord(value)) {
     throw new Error("CultCache legacy envelopes must be MessagePack maps.");

packages/cultcache-ts/src/cult-cache.ts

@@ -4,9 +4,11 @@ import {
   documentPayloadFromBytes,
   encodeDocumentPayload,
   resolveDocumentMembers,
+  schemaIdentityOf,
 } from "./document";
 import { resolveDocumentFormatter } from "./document-formatter";
 import type { DocumentPayload } from "./document";
+import { SchemaConflictError } from "./store-format";
 import type {
   AnyCultCacheDocumentDefinition,
   CacheBackingStore,
@@ -161,7 +163,9 @@ export class CultCache {
   }
 
   readonly #definitions = new Map<string, RegisteredDefinition>();
+  // The definition that owns each schema id, and every definition listing an id as compatible, in registration order.
   readonly #schemaIdDefinitions = new Map<string, RegisteredDefinition>();
+  readonly #listingDefinitions = new Map<string, RegisteredDefinition[]>();
   readonly #schemaNameDefinitions = new Map<string, RegisteredDefinition>();
   #hydrated = emptyHydratedState();
   readonly #stores: CultCacheStoreRegistration[] = [];
@@ -474,8 +478,10 @@ export class CultCache {
         type: envelope.type,
         payload,
         storedAt: envelope.storedAt,
-        schemaId: envelope.schemaId ?? registered.catalogEntry.schemaId,
-        catalogEntry: envelope.catalogEntry ?? registered.catalogEntry,
+        // The record is stamped with its registered schema's id, whatever id the envelope arrived under, so the
+        // catalog entry the store writes is the one its schema id names.
+        schemaId: registered.catalogEntry.schemaId,
+        catalogEntry: registered.catalogEntry,
       };
       await this.#writeNow(registered, entry, parsed);
       return parsed;
@@ -535,9 +541,13 @@ export class CultCache {
   }
 
   #registerNow(definition: AnyCultCacheDocumentDefinition): void {
+    // Every registration refusal is a SchemaConflictError naming the new definition's schema id and both schema names.
+    const refuse = (holder: RegisteredDefinition, claimed: CultCacheSchemaCatalogEntry, what: string) =>
+      new SchemaConflictError(claimed.schemaId, [holder.catalogEntry.schemaName, claimed.schemaName], "",
+        `CultCache ${what} is already registered for type "${holder.definition.type}" and cannot also be claimed by type "${definition.type}".`);
     const existing = this.#definitions.get(definition.type);
     if (existing && existing.definition !== definition) {
-      throw new Error(`CultCache already has a different definition registered for type "${definition.type}".`);
+      throw refuse(existing, this.#createCatalogEntry(definition), `type "${definition.type}"`);
     }
 
     const registered: RegisteredDefinition = existing ?? {
@@ -557,25 +567,28 @@ export class CultCache {
       indexAccessors.set(indexName, this.#compileAccessor(definition.type, `index "${indexName}"`, accessor));
     }
 
-    const schemaIds = registered.catalogEntry.compatibleSchemaIds ?? [registered.catalogEntry.schemaId];
-    for (const schemaId of schemaIds) {
-      const existingBySchema = this.#schemaIdDefinitions.get(schemaId);
-      if (existingBySchema && existingBySchema !== registered) {
-        throw new Error(`CultCache schema id "${schemaId}" is already registered for type "${existingBySchema.definition.type}".`);
-      }
+    // One definition owns each schema id. Others may list it as compatible beside its owner: a record under the id resolves to
+    // its owner, and to a lister only when nothing owns it. Neither depends on the order definitions were registered in.
+    const ownId = registered.catalogEntry.schemaId;
+    const listed = (registered.catalogEntry.compatibleSchemaIds ?? []).filter((schemaId) => schemaId !== ownId);
+    const owner = this.#schemaIdDefinitions.get(ownId);
+    if (owner && owner !== registered) {
+      throw refuse(owner, registered.catalogEntry, `schema id "${ownId}"`);
     }
     const existingBySchemaName = this.#schemaNameDefinitions.get(registered.catalogEntry.schemaName);
     if (existingBySchemaName && existingBySchemaName !== registered) {
-      throw new Error(
-        `CultCache schema name "${registered.catalogEntry.schemaName}" is already registered for type "${existingBySchemaName.definition.type}".`,
-      );
+      throw refuse(existingBySchemaName, registered.catalogEntry, `schema name "${registered.catalogEntry.schemaName}"`);
     }
     const derived = this.#deriveTypeLookups(definition.type, nameAccessor, indexAccessors);
 
     // Every check and accessor has run; install.
     this.#definitions.set(definition.type, registered);
-    for (const schemaId of schemaIds) {
-      this.#schemaIdDefinitions.set(schemaId, registered);
+    this.#schemaIdDefinitions.set(ownId, registered);
+    for (const schemaId of listed) {
+      const listers = this.#listingDefinitions.get(schemaId) ?? [];
+      if (!listers.includes(registered)) {
+        this.#listingDefinitions.set(schemaId, [...listers, registered]);
+      }
     }
     this.#schemaNameDefinitions.set(registered.catalogEntry.schemaName, registered);
     this.#installAccessors(registered, nameAccessor, indexAccessors, derived);
@@ -698,8 +711,7 @@ export class CultCache {
   }
 
   #createCatalogEntry(definition: AnyCultCacheDocumentDefinition): CultCacheSchemaCatalogEntry {
-    const schemaName = definition.schemaName ?? definition.type;
-    const schemaVersion = definition.schemaVersion ?? `${schemaName}.v1`;
+    const { schemaId, schemaName, schemaVersion, compatibleSchemaIds } = schemaIdentityOf(definition);
     const canonicalSchemaJson = definition.canonicalSchemaJson ?? JSON.stringify({
       schemaName,
       schemaVersion,
@@ -716,10 +728,6 @@ export class CultCache {
           isName: member.isName === true,
         })),
     });
-    const schemaId = definition.schemaId ?? schemaName;
-    const compatibleSchemaIds = [
-      ...new Set([schemaId, ...(definition.compatibleSchemaIds ?? [])]),
-    ];
 
     return {
       schemaId,
@@ -727,7 +735,7 @@ export class CultCache {
       schemaVersion,
       contentHash: definition.contentHash ?? schemaId,
       canonicalSchemaJson,
-      compatibleSchemaIds,
+      compatibleSchemaIds: [...compatibleSchemaIds],
       members: [...resolveDocumentMembers(definition)]
         .sort((left, right) => left.slot - right.slot)
         .map((member) => ({
@@ -810,7 +818,16 @@ export class CultCache {
 
   #resolveDefinitionForEnvelope(entry: CultCacheEnvelope): RegisteredDefinition | undefined {
     if (entry.schemaId) {
-      return this.#schemaIdDefinitions.get(entry.schemaId)
+      const listers = this.#listingDefinitions.get(entry.schemaId) ?? [];
+      const owner = this.#schemaIdDefinitions.get(entry.schemaId);
+      if (!owner && listers.length > 1) {
+        const types = listers.map((lister) => lister.definition.type).sort();
+        throw new SchemaConflictError(entry.schemaId, listers.map((lister) => lister.catalogEntry.schemaName).sort(), entry.key,
+          `CultCache schema id "${entry.schemaId}" of record "${entry.key}" is owned by no registered type and declared compatible by ` +
+          `several (${types.join(", ")}), so it resolves to none. Register the type that owns the id, or declare it on one type.`);
+      }
+      return owner
+        ?? listers[0]
         ?? this.#schemaNameDefinitions.get(entry.type)
         ?? this.#definitions.get(entry.type);
     }
@@ -880,8 +897,10 @@ export class CultCache {
     return {
       ...entry,
       payload: this.#cloneBytes(entry.payload),
-      schemaId: entry.schemaId ?? registered.catalogEntry.schemaId,
-      catalogEntry: entry.catalogEntry ?? registered.catalogEntry,
+      // Admitted under the registered schema's id, as a put stamps it: a record loaded under a compatible id is
+      // written back under the id its catalog entry carries.
+      schemaId: registered.catalogEntry.schemaId,
+      catalogEntry: registered.catalogEntry,
       value,
       lookups: this.#lookupsFor(registered.nameAccessor, registered.indexAccessors, value),
     };

packages/cultcache-ts/src/document.ts

@@ -149,6 +149,27 @@ export function resolveDocumentMembers(definition: AnyCultCacheDocumentDefinitio
   }));
 }
 
+// The identity a definition's records carry: the schema id they are stamped with, the schema name and version, and every id
+// the definition answers to (its own first). Every CultCache runtime surface and every CultNet or CultMesh layer over it
+// derives a definition's identity here and nowhere else, so a record's id means the same type wherever it is read.
+export interface CultCacheSchemaIdentity {
+  readonly schemaId: string;
+  readonly schemaName: string;
+  readonly schemaVersion: string;
+  readonly compatibleSchemaIds: readonly string[];
+}
+
+export function schemaIdentityOf(definition: AnyCultCacheDocumentDefinition): CultCacheSchemaIdentity {
+  const schemaName = definition.schemaName ?? definition.type;
+  const schemaId = definition.schemaId ?? schemaName;
+  return {
+    schemaId,
+    schemaName,
+    schemaVersion: definition.schemaVersion ?? `${schemaName}.v1`,
+    compatibleSchemaIds: [...new Set([schemaId, ...(definition.compatibleSchemaIds ?? [])])],
+  };
+}
+
 export function defineDocumentRegistry<
   TDefinitions extends readonly AnyCultCacheDocumentDefinition[],
 >(...definitions: TDefinitions): CultCacheDocumentRegistry<TDefinitions> {

packages/cultcache-ts/src/index.ts

@@ -1,45 +1,2 @@
-export * as codecs from "./codec";
-export type { Codec, SlotsCodec } from "./codec";
-export { CultCache, CultCacheBuilder } from "./cult-cache";
-export { inspectCultCacheBytes } from "./cult-cache-inspector";
-export {
-  decodeDocumentPayload,
-  defineDocumentRegistry,
-  defineDocumentType,
-  documentPayloadBytes,
-  documentPayloadFromBytes,
-  encodeDocumentPayload,
-} from "./document";
-export { CultCachePayloadDepthError, MAX_PAYLOAD_DEPTH } from "./payload-depth";
-export type { DocumentPayload } from "./document";
-export { SingleFileMessagePackBackingStore } from "./single-file-messagepack-backing-store";
-export type {
-  AnyCultCacheDocumentDefinition,
-  CacheBackingStore,
-  CultCacheDocumentAccessor,
-  CultCacheDocumentDefinition,
-  CultCacheDocumentFieldName,
-  CultCacheDocumentFormatter,
-  CultCacheDocumentIndexDefinition,
-  CultCacheDocumentRegistry,
-  CultCacheSchemaCatalogEntry,
-  CultCacheSchemaCatalogMember,
-  CultCacheSchema,
-  CultCacheDocumentValue,
-  CultCacheEnvelope,
-  CultCacheIndexScalar,
-  InferCultCacheSchemaValue,
-  CultCacheStoreRegistration,
-  PushAllOptions,
-} from "./types";
-export type {
-  CultCacheInspection,
-  InspectedCatalogEntry,
-  InspectedCatalogMember,
-  InspectedRecord,
-} from "./cult-cache-inspector";
-export {
-  defineSwarmDocuments,
-  type DefineDocumentType,
-  type SwarmDocumentCatalog,
-} from "./swarm-documents";
+export * from "./browser";
+export { SingleFileMessagePackBackingStore, readSingleFileStore, type SingleFileStoreRead } from "./single-file-messagepack-backing-store";

packages/cultcache-ts/src/single-file-messagepack-backing-store.ts

@@ -1,12 +1,13 @@
-import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstatSync, readFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
 import { decode, encode } from "@msgpack/msgpack";
 import { z } from "zod";
 
 import { documentPayloadBytes, documentPayloadFromBytes } from "./document";
-import { checkPayloadDepth } from "./payload-depth";
-import { STORE_FORMAT_VERSION, isV1Snapshot, requireV1RecordSlots } from "./store-format";
+import { commitStoreFile, withStoreWriteLock } from "./store-file";
+import { STORE_FORMAT_VERSION, SchemaConflictError, type StoreFormat, StoreUnreadableError, isStoreSnapshot, refuseUnreadStoreBytes, requireStoreSlots, requireV1RecordSlots } from "./store-format";
 import type {
   CacheBackingStore,
   CultCacheEnvelope,
@@ -38,104 +39,97 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
 
   #writeQueue: Promise<void> = Promise.resolve();
 
+  // The header this store read; a rewrite keeps it, so a store that holds element ids never sheds its marker.
+  #format: StoreFormat = STORE_FORMAT_VERSION;
+
   constructor(filePath: string) {
     this.filePath = resolve(filePath);
   }
 
   async pullAll(): Promise<CultCacheEnvelope[]> {
-    // An empty file is not a store, since no CultCache writer leaves one, so it is
-    // decoded and refused. Only a read that finds nothing at the path is an empty store.
-    const data = await readStore(this.filePath);
-    if (data === undefined) {
-      return [];
-    }
-
-    const decoded = decode(data);
-    const snapshot = decodeSnapshot(decoded);
-    if (snapshot) {
-      return snapshot.records.map((record) => {
-        const catalogEntry = resolveCatalogEntryForRecord(record, snapshot.catalogBySchemaId);
-        if (!catalogEntry) {
-          throw new Error(`CultCache persisted record "${record.key}" references missing schema id "${record.schemaId}".`);
+    // The disk decides the header: a file that is gone or legacy is not marked.
+    this.#format = STORE_FORMAT_VERSION;
+    const disk = this.#readDisk();
+    this.#format = disk.format;
+    if (disk.repairedLegacyPayload) {
+      // The heal decides from its own read, taken under the store lock.
+      await this.#enqueue(async () => {
+        const again = this.#readDisk();
+        this.#format = again.format;
+        if (again.repairedLegacyPayload) {
+          await this.#writeAll([], again.envelopes);
         }
-
-        return {
-          key: record.key,
-          type: catalogEntry.schemaName,
-          schemaId: record.schemaId,
-          catalogEntry,
-          payload: documentPayloadFromBytes(record.payload),
-          storedAt: record.storedAt,
-        };
       });
     }
 
-    const legacy = decodeLegacyEnvelopeArray(decoded);
-    if (legacy) {
-      let repairedLegacyPayload = false;
-      const normalized = legacy.map((entry) => {
-        const payload = normalizePayload(entry.payload);
-        if (payload !== entry.payload) {
-          repairedLegacyPayload = true;
-        }
-
-        return {
-          ...entry,
-          payload,
-        };
-      });
-      const parsed: CultCacheEnvelope[] = envelopeArraySchema.parse(normalized).map((entry) => ({
-        ...entry,
-        payload: documentPayloadFromBytes(entry.payload),
-      }));
-
-      if (repairedLegacyPayload) {
-        await this.#writeAll(parsed);
-      }
-
-      return parsed;
-    }
-
-    throw new Error(`CultCache file ${this.filePath} is not a recognized CultCache MessagePack store.`);
+    return disk.envelopes;
   }
 
   async push(entry: CultCacheEnvelope): Promise<void> {
     await this.#enqueue(async () => {
-      const existing = await this.pullAll();
+      const disk = this.#readDisk();
+      this.#format = disk.format;
+      const existing = disk.envelopes;
       const filtered = existing.filter(
         (candidate) => !(candidate.type === entry.type && candidate.key === entry.key),
       );
-      filtered.push(entry);
-      await this.#writeAll(filtered);
+      await this.#writeAll([entry], filtered);
     });
   }
 
   async delete(entry: CultCacheEnvelope): Promise<void> {
     await this.#enqueue(async () => {
-      const existing = await this.pullAll();
+      const disk = this.#readDisk();
+      this.#format = disk.format;
+      const existing = disk.envelopes;
       const filtered = existing.filter(
         (candidate) => !(candidate.type === entry.type && candidate.key === entry.key),
       );
-      await this.#writeAll(filtered);
+      await this.#writeAll([], filtered);
     });
   }
 
   async pushAll(entries: CultCacheEnvelope[], options: PushAllOptions = {}): Promise<void> {
     await this.#enqueue(async () => {
-      if (options.soft && (await readStore(this.filePath)) !== undefined) {
-        return;
+      // A flush of the whole store writes the header the file on disk carries, read now: a file marked for element ids
+      // stays marked, and one that is not (or is gone or legacy) is written unmarked. The file is read by the same
+      // reader as `pullAll`, so one it would refuse (not exactly one store, a variant, a body it cannot decode) is refused
+      // and left as it is. A soft flush asks that reader too: nothing at the path is written, a store is left alone.
+      try {
+        const disk = this.#readDisk();
+        if (options.soft && !disk.absent) {
+          return;
+        }
+
+        this.#format = disk.format;
+      } catch (error) {
+        // Only a dangling link reaches here with ENOENT: it holds no store, so a whole-store flush has no header to keep and
+        // replaces the link (R3 pins this). A soft flush does not replace what it cannot read, and every merging writer
+        // has already refused the link when it read the current entries.
+        if (options.soft || (error as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw error;
+        }
+
+        this.#format = STORE_FORMAT_VERSION;
       }
 
-      await this.#writeAll(entries);
+      await this.#writeAll(entries, []);
     });
   }
 
+  // The one reader of the store file, asked by open, push, delete and flush alike; see readSingleFileStore.
+  #readDisk(): SingleFileStoreRead {
+    return readSingleFileStore(this.filePath);
+  }
+
   async #enqueue<T>(operation: () => Promise<T>): Promise<T> {
     let result!: T;
 
-    const next = this.#writeQueue.then(async () => {
-      result = await operation();
-    });
+    const next = this.#writeQueue.then(() =>
+      withStoreWriteLock(this.filePath, async () => {
+        result = await operation();
+      }),
+    );
 
     this.#writeQueue = next.then(
       () => undefined,
@@ -146,39 +140,54 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
     return result;
   }
 
-  async #writeAll(entries: CultCacheEnvelope[]): Promise<void> {
+  async #writeAll(supplied: CultCacheEnvelope[], arrived: CultCacheEnvelope[]): Promise<void> {
     await mkdir(dirname(this.filePath), { recursive: true });
 
-    const tempPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}-${Math.random()
-      .toString(36)
-      .slice(2)}`;
-
-    try {
-      await writeFile(tempPath, encode(encodeSnapshot(entries)));
-      await renameWithRetry(tempPath, this.filePath);
-    } catch (error) {
-      await rm(tempPath, { force: true }).catch(() => undefined);
-      throw error;
-    }
+    await commitStoreFile(this.filePath, encode(encodeSnapshot(supplied, arrived, this.#format)));
   }
 }
 
 /**
- * Reads a store file, or returns undefined when nothing is at its path. A dangling symbolic
- * link is something: reading it as empty would let the writer rename a file over the link
- * and move the store off its volume. Any other failure to reach the file is thrown.
+ * The one reader of a CultCache single-file store, for this package's store and for any consumer that must read a
+ * store file (an authority bundle, say) rather than decode it itself. A path with nothing at it is an absent, empty,
+ * unmarked store. A dangling symbolic link is something: reading it as empty would let a writer rename a file over
+ * the link and move the store off its volume, so it throws with code ENOENT, as does any other failure to reach the
+ * file. A zero-byte file is not a store and, like anything that does not decode completely, throws StoreUnreadableError.
+ * The read is synchronous so a consumer that loads authority at start-up needs no second reader to stay synchronous.
  */
-async function readStore(path: string): Promise<Uint8Array | undefined> {
+export function readSingleFileStore(path: string): SingleFileStoreRead {
+  const data = readStoreBytes(path);
+  if (data === undefined) {
+    return { absent: true, format: STORE_FORMAT_VERSION, envelopes: [], repairedLegacyPayload: false };
+  }
+
   try {
-    return await readFile(path);
+    return { absent: false, ...decodeStoreFile(data) };
+  } catch (error) {
+    throw new StoreUnreadableError(path, error);
+  }
+}
+
+/**
+ * The bytes at `path`, or undefined when nothing is there. Nothing is there only when both looks agree: the read found no
+ * file and the follow-up lstat found no entry. Every other outcome is an error, because the path may have changed
+ * between the two calls (a link in a parent swapped for a file, a store created or removed): an lstat failure other than
+ * ENOENT is thrown as it is, and an entry the lstat does find, a dangling link or one that appeared since the read, is
+ * thrown with code ENOENT rather than read as an empty store. `lstat` is a seam so a test can stage the second look;
+ * this module exports the function for that test, and the package index does not.
+ */
+export function readStoreBytes(path: string, lstat: (path: string) => { isSymbolicLink(): boolean } = lstatSync): Uint8Array | undefined {
+  try {
+    return readFileSync(path);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
       throw error;
     }
   }
 
+  let entry: { isSymbolicLink(): boolean };
   try {
-    await lstat(path);
+    entry = lstat(path);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       return undefined;
@@ -187,33 +196,8 @@ async function readStore(path: string): Promise<Uint8Array | undefined> {
     throw error;
   }
 
-  throw Object.assign(new Error(`CultCache store ${path} is a symbolic link whose target does not exist.`), { code: "ENOENT" });
-}
-
-async function renameWithRetry(source: string, destination: string): Promise<void> {
-  let delayMs = 10;
-  let lastError: unknown;
-  for (let attempt = 0; attempt < 10; attempt++) {
-    try {
-      await rename(source, destination);
-      return;
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") {
-        throw error;
-      }
-
-      lastError = error;
-      await delay(delayMs);
-      delayMs *= 2;
-    }
-  }
-
-  throw lastError;
-}
-
-function delay(milliseconds: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+  const what = entry.isSymbolicLink() ? "is a symbolic link whose target does not exist" : "appeared while it was being read";
+  throw Object.assign(new Error(`CultCache store ${path} ${what}.`), { code: "ENOENT" });
 }
 
 type PersistedRecord = {
@@ -224,13 +208,19 @@ type PersistedRecord = {
 };
 
 type DecodedSnapshot = {
+  format: StoreFormat;
   catalogBySchemaId: Map<string, CultCacheSchemaCatalogEntry>;
   records: PersistedRecord[];
 };
 
-function encodeSnapshot(entries: CultCacheEnvelope[]): unknown[] {
-  const catalog = [...catalogEntriesFor(entries).values()]
-    .sort((left, right) => compareOrdinal(left.schemaName, right.schemaName));
+function encodeSnapshot(supplied: CultCacheEnvelope[], arrived: CultCacheEnvelope[], format: StoreFormat): unknown[] {
+  const replaced = new Set(supplied.map((entry) => `${entry.type}::${entry.key}`));
+  const kept = arrived.filter((entry) => !replaced.has(`${entry.type}::${entry.key}`));
+  const entries = [...kept, ...supplied];
+  const catalog = catalogEntriesFor([
+    ...kept.map((envelope) => ({ envelope, registered: false })),
+    ...supplied.map((envelope) => ({ envelope, registered: true })),
+  ]).sort((left, right) => compareOrdinal(left.schemaName, right.schemaName) || compareOrdinal(left.schemaId, right.schemaId));
   const records = [...entries]
     .sort((left, right) => compareOrdinal(left.key, right.key))
     .map((entry) => [
@@ -241,34 +231,134 @@ function encodeSnapshot(entries: CultCacheEnvelope[]): unknown[] {
     ]);
 
   return [
-    STORE_FORMAT_VERSION,
+    format,
     catalog.map(encodeCatalogEntry),
     records,
   ];
 }
 
-function catalogEntriesFor(entries: CultCacheEnvelope[]): Map<string, CultCacheSchemaCatalogEntry> {
-  const catalog = new Map<string, CultCacheSchemaCatalogEntry>();
-  for (const entry of entries) {
-    const schemaId = schemaIdForEnvelope(entry);
-    if (!catalog.has(schemaId)) {
-      catalog.set(schemaId, entry.catalogEntry ?? {
+// The catalog a write leaves, derived from the records being written and nothing else. For each schema id a record carries, one
+// entry that publishes it: the entry that owns the id (a registered one, else one that arrived with the records), else one that
+// lists it as compatible (registered first). Entries are written as chosen, never merged; a registered entry wins over an arrived
+// one with the same own id. Records of different types under one id, two arrived entries with the same own id and different schema
+// names, or a record no chosen entry publishes, refuse the write. An envelope the caller supplied is registered; one read back
+// from the file is arrived.
+function catalogEntriesFor(
+  records: Array<{ envelope: CultCacheEnvelope; registered: boolean }>,
+): CultCacheSchemaCatalogEntry[] {
+  const entries: Array<{ entry: CultCacheSchemaCatalogEntry; registered: boolean }> = [];
+  const byId = new Map<string, CultCacheEnvelope[]>();
+  const tiers = new Map<string, Array<{ envelope: CultCacheEnvelope; registered: boolean; entry: CultCacheSchemaCatalogEntry }>>();
+  for (const { envelope, registered } of records) {
+    const schemaId = schemaIdForEnvelope(envelope);
+    const supplied = envelope.catalogEntry;
+    const publishes =
+      supplied !== undefined && (supplied.schemaId === schemaId || (supplied.compatibleSchemaIds ?? []).includes(schemaId));
+    const entry = publishes && supplied ? supplied : defaultEntryFor(envelope);
+    entries.push({ entry, registered });
+    byId.set(schemaId, [...(byId.get(schemaId) ?? []), envelope]);
+    tiers.set(schemaId, [...(tiers.get(schemaId) ?? []), { envelope, registered, entry }]);
+  }
+
+  const lists = (entry: CultCacheSchemaCatalogEntry, schemaId: string): boolean =>
+    (entry.compatibleSchemaIds ?? [entry.schemaId]).includes(schemaId);
+  const chosen = new Map<string, { entry: CultCacheSchemaCatalogEntry; registered: boolean }>();
+  for (const schemaId of [...byId.keys()].sort(compareOrdinal)) {
+    const carrying = byId.get(schemaId)!;
+    const recordKey = carrying.map((envelope) => envelope.key).sort(compareOrdinal)[0]!;
+    // Records of one tier under one id are one type. Across tiers the id keeps the type its records resolve to, so a write may
+    // not retype records that are already there: unless the entries of both tiers own the id, which is a rename of the schema
+    // under a stable id, and the registered descriptor wins. A read-back record's type is its schema's name, so tiers compare
+    // the names of the entries that publish the id.
+    const carried = tiers.get(schemaId)!;
+    for (const tier of [true, false]) {
+      const types = [...new Set(carried.filter((candidate) => candidate.registered === tier).map((candidate) => candidate.envelope.type))].sort(
+        compareOrdinal,
+      );
+      if (types.length > 1) {
+        throw new SchemaConflictError(schemaId, types, recordKey);
+      }
+    }
+
+    const tierNames = (tier: boolean): string[] => [
+      ...new Set(carried.filter((candidate) => candidate.registered === tier).map((candidate) => candidate.entry.schemaName)),
+    ];
+    const ownedBy = (tier: boolean): boolean =>
+      carried.some((candidate) => candidate.registered === tier && candidate.entry.schemaId === schemaId);
+    const [registeredName, arrivedName] = [tierNames(true)[0], tierNames(false)[0]];
+    if (registeredName !== undefined && arrivedName !== undefined && registeredName !== arrivedName && !(ownedBy(true) && ownedBy(false))) {
+      throw new SchemaConflictError(schemaId, [registeredName, arrivedName].sort(compareOrdinal), recordKey);
+    }
+
+    const ownRegistered = canonical(entries.filter((candidate) => candidate.registered && candidate.entry.schemaId === schemaId))[0];
+    const ownArrived = canonical(entries.filter((candidate) => !candidate.registered && candidate.entry.schemaId === schemaId));
+    // Entries of one tier that share an own id must be one schema; a registered entry settles a disagreement among arrived ones.
+    const ownRegisteredAll = canonical(entries.filter((candidate) => candidate.registered && candidate.entry.schemaId === schemaId));
+    const names = [
+      ...new Set((ownRegisteredAll.length > 0 ? ownRegisteredAll : ownArrived).map((candidate) => candidate.entry.schemaName)),
+    ].sort(compareOrdinal);
+    if (names.length > 1) {
+      throw new SchemaConflictError(schemaId, names, recordKey);
+    }
+
+    let pick: { entry: CultCacheSchemaCatalogEntry; registered: boolean } | undefined;
+    if (ownRegistered !== undefined) {
+      pick = ownRegistered;
+    } else if (ownArrived.length > 0) {
+      pick = ownArrived[0];
+    } else {
+      pick =
+        canonical(entries.filter((candidate) => candidate.registered && lists(candidate.entry, schemaId)))[0] ??
+        canonical(entries.filter((candidate) => !candidate.registered && lists(candidate.entry, schemaId)))[0];
+    }
+
+    if (pick === undefined) {
+      continue;
+    }
+
+    const prior = chosen.get(pick.entry.schemaId);
+    if (prior !== undefined && prior.registered && !pick.registered) {
+      continue;
+    }
+
+    chosen.set(pick.entry.schemaId, pick);
+  }
+
+  for (const [schemaId, carrying] of byId) {
+    if (![...chosen.values()].some(({ entry }) => entry.schemaId === schemaId || lists(entry, schemaId))) {
+      throw new SchemaConflictError(
         schemaId,
-        schemaName: entry.type,
-        schemaVersion: `${entry.type}.v1`,
-        contentHash: schemaId,
-        canonicalSchemaJson: JSON.stringify({
-          schemaName: entry.type,
-          schemaVersion: `${entry.type}.v1`,
-          members: [],
-        }),
-        compatibleSchemaIds: [schemaId],
-        members: [],
-      });
+        [...chosen.values()].map(({ entry }) => entry.schemaName).sort(compareOrdinal),
+        carrying.map((envelope) => envelope.key).sort(compareOrdinal)[0]!,
+      );
     }
   }
 
-  return catalog;
+  return [...chosen.values()].map(({ entry }) => entry);
+}
+
+// Entries that tie, in one fixed order, so the catalog does not depend on the order they arrive in.
+function canonical<T extends { entry: CultCacheSchemaCatalogEntry }>(candidates: T[]): T[] {
+  const key = (candidate: T): string =>
+    [candidate.entry.schemaName, candidate.entry.contentHash ?? "", (candidate.entry.compatibleSchemaIds ?? []).join(",")].join("\u0000");
+  return [...candidates].sort((left, right) => compareOrdinal(key(left), key(right)));
+}
+
+function defaultEntryFor(entry: CultCacheEnvelope): CultCacheSchemaCatalogEntry {
+  const schemaId = schemaIdForEnvelope(entry);
+  return {
+    schemaId,
+    schemaName: entry.type,
+    schemaVersion: `${entry.type}.v1`,
+    contentHash: schemaId,
+    canonicalSchemaJson: JSON.stringify({
+      schemaName: entry.type,
+      schemaVersion: `${entry.type}.v1`,
+      members: [],
+    }),
+    compatibleSchemaIds: [schemaId],
+    members: [],
+  };
 }
 
 function schemaIdForEnvelope(entry: CultCacheEnvelope): string {
@@ -300,82 +390,89 @@ function encodeCatalogMember(member: CultCacheSchemaCatalogMember): unknown[] {
   ];
 }
 
+export type SingleFileStoreRead = {
+  // True when nothing is at the path; the other fields then describe an empty unmarked store.
+  absent: boolean;
+  format: StoreFormat;
+  envelopes: CultCacheEnvelope[];
+  // A legacy file whose payloads were not bytes: reading it repairs them, and the store rewrites the file.
+  repairedLegacyPayload: boolean;
+};
+
+function decodeStoreFile(data: Uint8Array): Omit<SingleFileStoreRead, "absent"> {
+  // The stamp is judged before the body is decoded, as Rust's store_header does: a newer store is refused by name.
+  refuseUnreadStoreBytes(data);
+  const decoded = decode(data);
+  const snapshot = decodeSnapshot(decoded);
+  if (snapshot) {
+    const envelopes = snapshot.records.map((record): CultCacheEnvelope => {
+      const catalogEntry = snapshot.catalogBySchemaId.get(record.schemaId);
+      if (!catalogEntry) {
+        throw new Error(`CultCache persisted record "${record.key}" references missing schema id "${record.schemaId}".`);
+      }
+
+      return {
+        key: record.key,
+        type: catalogEntry.schemaName,
+        schemaId: record.schemaId,
+        catalogEntry,
+        payload: documentPayloadFromBytes(record.payload),
+        storedAt: record.storedAt,
+      };
+    });
+    return { format: snapshot.format, envelopes, repairedLegacyPayload: false };
+  }
+
+  const legacy = decodeLegacyEnvelopeArray(decoded);
+  if (!legacy) {
+    throw new Error("CultCache file is not a recognized CultCache MessagePack store.");
+  }
+
+  let repairedLegacyPayload = false;
+  const normalized = legacy.map((entry) => {
+    const payload = normalizePayload(entry.payload);
+    if (payload !== entry.payload) {
+      repairedLegacyPayload = true;
+    }
+
+    return {
+      ...entry,
+      payload,
+    };
+  });
+  return { format: STORE_FORMAT_VERSION, envelopes: envelopeArraySchema.parse(normalized).map((entry) => ({ ...entry, payload: documentPayloadFromBytes(entry.payload) })) as CultCacheEnvelope[], repairedLegacyPayload };
+}
+
 function decodeSnapshot(decoded: unknown): DecodedSnapshot | undefined {
-  if (!isV1Snapshot(decoded)) {
+  if (!isStoreSnapshot(decoded)) {
     return undefined;
   }
 
+  requireStoreSlots(decoded);
   const catalogRaw = decoded[1];
   const recordsRaw = decoded[2];
   if (!Array.isArray(catalogRaw) || !Array.isArray(recordsRaw)) {
     throw new Error("CultCache v1 snapshot must contain a schema catalog and record array.");
   }
 
+  // A schema id names the entry that has it as its own id; only an id no entry owns names the entry that lists it as compatible.
+  const catalogEntries = catalogRaw.map(decodeCatalogEntry);
   const catalogBySchemaId = new Map<string, CultCacheSchemaCatalogEntry>();
-  for (const entry of catalogRaw) {
-    const catalogEntry = decodeCatalogEntry(entry);
-    catalogBySchemaId.set(catalogEntry.schemaId, catalogEntry);
+  for (const catalogEntry of catalogEntries) {
+    if (!catalogBySchemaId.has(catalogEntry.schemaId)) {
+      catalogBySchemaId.set(catalogEntry.schemaId, catalogEntry);
+    }
+  }
+  for (const catalogEntry of catalogEntries) {
     for (const compatibleSchemaId of catalogEntry.compatibleSchemaIds ?? []) {
-      catalogBySchemaId.set(compatibleSchemaId, catalogEntry);
+      if (!catalogBySchemaId.has(compatibleSchemaId)) {
+        catalogBySchemaId.set(compatibleSchemaId, catalogEntry);
+      }
     }
   }
 
   const records = recordsRaw.map(decodeRecord);
-  return { catalogBySchemaId, records };
-}
-
-function resolveCatalogEntryForRecord(
-  record: PersistedRecord,
-  catalogBySchemaId: Map<string, CultCacheSchemaCatalogEntry>,
-): CultCacheSchemaCatalogEntry | undefined {
-  const existing = catalogBySchemaId.get(record.schemaId);
-  if (existing) {
-    return existing;
-  }
-
-  const schemaVersion = inferSchemaVersionFromPayload(record.payload);
-  if (!schemaVersion) {
-    return undefined;
-  }
-
-  const schemaName = inferSchemaName(schemaVersion);
-  if (!schemaName) {
-    return undefined;
-  }
-
-  return {
-    schemaId: record.schemaId,
-    schemaName,
-    schemaVersion,
-    contentHash: record.schemaId,
-    canonicalSchemaJson: "",
-    compatibleSchemaIds: [],
-    members: [],
-  };
-}
-
-function inferSchemaVersionFromPayload(payload: Uint8Array): string | undefined {
-  try {
-    checkPayloadDepth(payload);
-    const decoded = decode(payload);
-    if (Array.isArray(decoded) && typeof decoded[0] === "string") {
-      return decoded[0];
-    }
-
-    if (isObject(decoded)) {
-      const schemaVersion = decoded.schemaVersion ?? decoded.schema_version;
-      return typeof schemaVersion === "string" ? schemaVersion : undefined;
-    }
-
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function inferSchemaName(schemaVersion: string): string | undefined {
-  const match = /^(.*)\.v\d+$/.exec(schemaVersion);
-  return match?.[1];
+  return { format: decoded[0], catalogBySchemaId, records };
 }
 
 function decodeCatalogEntry(value: unknown): CultCacheSchemaCatalogEntry {

packages/cultcache-ts/src/store-file.ts

@@ -0,0 +1,391 @@
+// The TypeScript owner of a single-file store's write transaction: the cross-process lock on
+// `<path>.lock`, the staged file, its fsync, the replace and the directory fsync.
+// Node only, and not exported from the package index. The OS calls Node does not expose
+// (flock, LockFileEx, a POSIX-semantics rename on Windows) go through koffi, which is required
+// lazily inside `loadKernel`, so a consumer that never writes a store never loads it.
+
+import { closeSync, openSync, constants as fsConstants } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const LOCK_POLL_MS = 10;
+const LOCK_TIMEOUT_MS = 30_000;
+
+/** Thrown when the staged file replaced the store but the directory entry may not be durable. */
+export class StoreReplacedNotDurableError extends Error {
+  readonly replaced = true;
+  constructor(storePath: string, cause: unknown) {
+    super(
+      `CultCache store ${storePath} was replaced, but syncing its directory failed, so the replace may not survive a crash: ${
+        cause instanceof Error ? cause.message : String(cause)
+      }`,
+    );
+    this.name = "StoreReplacedNotDurableError";
+  }
+}
+
+/** The file operations of one commit. Tests record or fail them; production uses `nodeStoreFileOps`. */
+export interface StoreFileOps {
+  createExclusive(path: string): Promise<FileHandle>;
+  write(handle: FileHandle, bytes: Uint8Array): Promise<void>;
+  sync(handle: FileHandle): Promise<void>;
+  close(handle: FileHandle): Promise<void>;
+  replace(staged: string, destination: string): Promise<void>;
+  syncDirectory(directory: string): Promise<void>;
+  remove(path: string): Promise<void>;
+}
+
+export const nodeStoreFileOps: StoreFileOps = {
+  createExclusive: (path) => open(path, "wx"),
+  write: async (handle, bytes) => {
+    await handle.writeFile(bytes);
+  },
+  sync: (handle) => handle.sync(),
+  close: (handle) => handle.close(),
+  replace: (staged, destination) => replaceStoreFile(staged, destination),
+  syncDirectory: async (directory) => {
+    const handle = await open(directory, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  },
+  remove: (path) => rm(path, { force: true }),
+};
+
+/**
+ * Writes `bytes` to a unique staged file beside the store, fsyncs it, replaces the store with it
+ * and, on Unix, fsyncs the directory so the replace is durable. Windows relies on the replace
+ * itself, as the Rust runtime does. Any failure before the replace removes the staged file and
+ * leaves the store untouched; a directory sync failure after it throws
+ * `StoreReplacedNotDurableError`. The caller holds the store lock.
+ */
+export async function commitStoreFile(
+  storePath: string,
+  bytes: Uint8Array,
+  ops: StoreFileOps = nodeStoreFileOps,
+): Promise<void> {
+  const staged = `${storePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  let handle: FileHandle | undefined;
+  try {
+    handle = await ops.createExclusive(staged);
+    await ops.write(handle, bytes);
+    await ops.sync(handle);
+    const closing = handle;
+    handle = undefined;
+    await ops.close(closing);
+    await ops.replace(staged, storePath);
+  } catch (error) {
+    if (handle) {
+      await ops.close(handle).catch(() => undefined);
+    }
+    await ops.remove(staged).catch(() => undefined);
+    throw error;
+  }
+
+  if (process.platform !== "win32") {
+    try {
+      await ops.syncDirectory(dirname(storePath));
+    } catch (error) {
+      throw new StoreReplacedNotDurableError(storePath, error);
+    }
+  }
+}
+
+/** Replaces `destination` with `staged`: POSIX-first on Windows, `rename` elsewhere. */
+export async function replaceStoreFile(staged: string, destination: string): Promise<void> {
+  if (process.platform === "win32") {
+    await replaceStoreFileWindows(staged, destination, windowsKernel());
+    return;
+  }
+
+  await rename(staged, destination);
+}
+
+const ERROR_ACCESS_DENIED = 5;
+const ERROR_SHARING_VIOLATION = 32;
+const ERROR_LOCK_VIOLATION = 33;
+const ERROR_NOT_SUPPORTED = 50;
+const ERROR_INVALID_PARAMETER = 87;
+const REPLACE_ATTEMPTS = 25;
+const REPLACE_RETRY_MS = 20;
+/** MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH. */
+export const MOVEFILE_REPLACE_WRITE_THROUGH = 0x9;
+
+/** The kernel32 calls a Windows replace needs, each answering 0 or a Win32 error code. */
+export interface ReplaceKernel {
+  /** CreateFileW(staged, DELETE|SYNCHRONIZE) then FileRenameInfoEx with REPLACE_IF_EXISTS|POSIX_SEMANTICS, then CloseHandle. */
+  renamePosix(staged: string, destination: string): number;
+  /** MoveFileExW(staged, destination, flags). */
+  moveFileEx(staged: string, destination: string, flags: number): number;
+  sleep(milliseconds: number): Promise<void>;
+}
+
+export async function replaceStoreFileWindows(
+  staged: string,
+  destination: string,
+  kernel: ReplaceKernel,
+): Promise<void> {
+  let posix = true;
+  let lastCode = 0;
+  for (let attempt = 1; attempt <= REPLACE_ATTEMPTS; attempt++) {
+    let code = posix ? kernel.renamePosix(staged, destination) : kernel.moveFileEx(staged, destination, MOVEFILE_REPLACE_WRITE_THROUGH);
+    if (posix && (code === 1 || code === ERROR_NOT_SUPPORTED || code === ERROR_INVALID_PARAMETER)) {
+      // POSIX semantics are unsupported here (FAT, exFAT, before Windows 10 1607): the rest of this call is write-through.
+      posix = false;
+      code = kernel.moveFileEx(staged, destination, MOVEFILE_REPLACE_WRITE_THROUGH);
+    }
+
+    if (code === 0) {
+      return;
+    }
+
+    if (code !== ERROR_ACCESS_DENIED && code !== ERROR_SHARING_VIOLATION && code !== ERROR_LOCK_VIOLATION) {
+      throw new Error(`CultCache could not replace the store: Win32 error ${code}.`);
+    }
+
+    lastCode = code;
+    await kernel.sleep(REPLACE_RETRY_MS);
+  }
+
+  throw new Error(
+    `CultCache could not replace the store after ${REPLACE_ATTEMPTS} attempts: last Win32 error ${lastCode}.`,
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// The cross-process write lock.
+
+export interface StoreLockOptions {
+  /** How long to wait for the lock; 30 s by default, as the C# runtime waits. */
+  timeoutMs?: number;
+}
+
+/**
+ * Runs `operation` while holding the exclusive store lock on `<storePath>.lock`. C# holds it
+ * by a share-none open, Rust by an exclusive file lock; this takes the same lock by LockFileEx
+ * on Windows and flock on Unix, so all of them exclude each other. Polls every 10 ms and holds
+ * no handle on the lock file between polls. The lock file is created if absent, never
+ * written and never deleted.
+ */
+export async function withStoreWriteLock<T>(
+  storePath: string,
+  operation: () => Promise<T>,
+  options: StoreLockOptions = {},
+): Promise<T> {
+  const lockPath = `${storePath}.lock`;
+  const timeoutMs = options.timeoutMs ?? LOCK_TIMEOUT_MS;
+  await mkdir(dirname(lockPath), { recursive: true });
+
+  const started = Date.now();
+  let release: (() => void) | undefined;
+  while (release === undefined) {
+    release = tryLock(lockPath);
+    if (release === undefined) {
+      if (Date.now() - started >= timeoutMs) {
+        throw new Error(`CultCache timed out after ${timeoutMs} ms waiting for the store lock ${lockPath}.`);
+      }
+
+      await sleep(LOCK_POLL_MS);
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    release();
+  }
+}
+
+function tryLock(lockPath: string): (() => void) | undefined {
+  const platform = process.platform;
+  if (platform === "win32") {
+    return tryLockWindows(lockPath);
+  }
+
+  if (platform === "linux" || platform === "darwin") {
+    return tryLockUnix(lockPath, platform);
+  }
+
+  throw new Error(`CultCache cross-process store lock is not implemented on ${platform}.`);
+}
+
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+// ---------------------------------------------------------------------------------------------
+// koffi bindings, loaded on first use.
+
+const GENERIC_READ_WRITE = 0xc0000000;
+const GENERIC_ALL_DELETE_SYNC = 0x00110000; // DELETE | SYNCHRONIZE
+const SHARE_READ_WRITE_DELETE = 0x7;
+const OPEN_EXISTING = 3;
+const OPEN_ALWAYS = 4;
+const FILE_ATTRIBUTE_NORMAL = 0x80;
+const LOCKFILE_EXCLUSIVE_FAIL_IMMEDIATELY = 0x3;
+const FILE_RENAME_INFO_EX = 22;
+const RENAME_REPLACE_POSIX = 0x3;
+const INVALID_HANDLE_VALUE = -1;
+const LOCK_EX_NB = 6;
+const LOCK_UN = 8;
+const EINTR = 4;
+
+type Kernel32 = {
+  createFile(path: string, access: number, share: number, disposition: number): number;
+  lockFileEx(handle: number): boolean;
+  unlockFileEx(handle: number): void;
+  closeHandle(handle: number): void;
+  setRenameInfo(handle: number, buffer: Buffer): boolean;
+  moveFileEx(staged: string, destination: string, flags: number): boolean;
+  lastError(): number;
+};
+
+type Libc = {
+  flock(fd: number, operation: number): number;
+  errno(): number;
+};
+
+let kernel32Cache: Kernel32 | undefined;
+let libcCache: Libc | undefined;
+
+function loadKernel32(): Kernel32 {
+  if (kernel32Cache) {
+    return kernel32Cache;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const koffi = require("koffi");
+  const lib = koffi.load("kernel32.dll");
+  const createFileW = lib.func(
+    "intptr_t CreateFileW(str16 name, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t flags, void *template)",
+  );
+  const lockFileEx = lib.func(
+    "int LockFileEx(intptr_t handle, uint32_t flags, uint32_t reserved, uint32_t low, uint32_t high, void *overlapped)",
+  );
+  const unlockFileEx = lib.func(
+    "int UnlockFileEx(intptr_t handle, uint32_t reserved, uint32_t low, uint32_t high, void *overlapped)",
+  );
+  const closeHandle = lib.func("int CloseHandle(intptr_t handle)");
+  const setFileInformationByHandle = lib.func(
+    "int SetFileInformationByHandle(intptr_t handle, int infoClass, void *info, uint32_t size)",
+  );
+  const moveFileExW = lib.func("int MoveFileExW(str16 existing, str16 destination, uint32_t flags)");
+  const getLastError = lib.func("uint32_t GetLastError()");
+
+  kernel32Cache = {
+    createFile: (path, access, share, disposition) =>
+      Number(createFileW(path, access, share, null, disposition, FILE_ATTRIBUTE_NORMAL, null)),
+    lockFileEx: (handle) => lockFileEx(handle, LOCKFILE_EXCLUSIVE_FAIL_IMMEDIATELY, 0, 0xffffffff, 0xffffffff, Buffer.alloc(32)) !== 0,
+    unlockFileEx: (handle) => {
+      unlockFileEx(handle, 0, 0xffffffff, 0xffffffff, Buffer.alloc(32));
+    },
+    closeHandle: (handle) => {
+      closeHandle(handle);
+    },
+    setRenameInfo: (handle, buffer) => setFileInformationByHandle(handle, FILE_RENAME_INFO_EX, buffer, buffer.length) !== 0,
+    moveFileEx: (staged, destination, flags) => moveFileExW(staged, destination, flags) !== 0,
+    lastError: () => Number(getLastError()),
+  };
+  return kernel32Cache;
+}
+
+function loadLibc(platform: "linux" | "darwin"): Libc {
+  if (libcCache) {
+    return libcCache;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const koffi = require("koffi");
+  const lib = koffi.load(platform === "darwin" ? "libSystem.B.dylib" : "libc.so.6");
+  const flock = lib.func("int flock(int fd, int operation)");
+  libcCache = {
+    flock: (fd, operation) => flock(fd, operation),
+    errno: () => koffi.errno(),
+  };
+  return libcCache;
+}
+
+/** The bound kernel32 replace calls; exported for the tests that run them against the real kernel. */
+export function windowsKernel(): ReplaceKernel {
+  const k = loadKernel32();
+  return {
+    renamePosix: (staged, destination) => {
+      const handle = k.createFile(staged, GENERIC_ALL_DELETE_SYNC, SHARE_READ_WRITE_DELETE, OPEN_EXISTING);
+      if (handle === INVALID_HANDLE_VALUE) {
+        return k.lastError();
+      }
+
+      try {
+        const name = Buffer.from(destination, "utf16le");
+        const info = Buffer.alloc(20 + name.length + 2);
+        info.writeUInt32LE(RENAME_REPLACE_POSIX, 0);
+        info.writeUInt32LE(name.length, 16);
+        name.copy(info, 20);
+        return k.setRenameInfo(handle, info) ? 0 : k.lastError();
+      } finally {
+        k.closeHandle(handle);
+      }
+    },
+    moveFileEx: (staged, destination, flags) => (k.moveFileEx(staged, destination, flags) ? 0 : k.lastError()),
+    sleep,
+  };
+}
+
+function tryLockWindows(lockPath: string): (() => void) | undefined {
+  const k = loadKernel32();
+  const handle = k.createFile(lockPath, GENERIC_READ_WRITE, SHARE_READ_WRITE_DELETE, OPEN_ALWAYS);
+  if (handle === INVALID_HANDLE_VALUE) {
+    const code = k.lastError();
+    if (code === ERROR_SHARING_VIOLATION) {
+      // A C# holder opened the lock file share-none.
+      return undefined;
+    }
+
+    throw new Error(`CultCache could not open the store lock ${lockPath}: Win32 error ${code}.`);
+  }
+
+  if (!k.lockFileEx(handle)) {
+    const code = k.lastError();
+    k.closeHandle(handle);
+    if (code === ERROR_LOCK_VIOLATION) {
+      // A Rust or TypeScript holder holds the exclusive byte-range lock.
+      return undefined;
+    }
+
+    throw new Error(`CultCache could not lock the store lock ${lockPath}: Win32 error ${code}.`);
+  }
+
+  return () => {
+    k.unlockFileEx(handle);
+    k.closeHandle(handle);
+  };
+}
+
+function tryLockUnix(lockPath: string, platform: "linux" | "darwin"): (() => void) | undefined {
+  const libc = loadLibc(platform);
+  const wouldBlock = platform === "darwin" ? 35 : 11; // EWOULDBLOCK == EAGAIN
+  const fd = openSync(lockPath, fsConstants.O_RDWR | fsConstants.O_CREAT, 0o666);
+  for (;;) {
+    if (libc.flock(fd, LOCK_EX_NB) === 0) {
+      return () => {
+        libc.flock(fd, LOCK_UN);
+        closeSync(fd);
+      };
+    }
+
+    const errno = libc.errno();
+    if (errno === EINTR) {
+      continue;
+    }
+
+    closeSync(fd);
+    if (errno === wouldBlock) {
+      return undefined;
+    }
+
+    throw new Error(`CultCache could not lock the store lock ${lockPath}: errno ${errno}.`);
+  }
+}

packages/cultcache-ts/src/store-format.ts

@@ -1,24 +1,109 @@
+import { decode } from "@msgpack/msgpack";
+
 export const STORE_FORMAT_VERSION = "cultcache.store.v1";
 
+/**
+ * A store that can hold element ids. A reader older than element ids refuses this header: it would skip the id slots
+ * of a nested element and rewrite the element without them. This runtime writes it back only for a store it read
+ * under it; it does not decide when a document carries ids.
+ */
+export const STORE_FORMAT_ELEMENT_IDS = "cultcache.store.v3";
+
+export type StoreFormat = typeof STORE_FORMAT_VERSION | typeof STORE_FORMAT_ELEMENT_IDS;
+
 const STORE_FORMAT_PREFIX = "cultcache.store.";
 const PERSISTED_RECORD_SLOTS = 4;
+const STORE_SLOTS = 3;
 
 /**
- * True for a v1 snapshot, false for anything that is not a CultCache store header (the legacy
- * envelope array). Any other `cultcache.store.*` header is refused by name.
+ * True for a decoded array that leads with a `cultcache.store.*` stamp, false for the legacy envelope array. It judges the
+ * shape only: the verdict on the stamp is {@link refuseUnreadStoreBytes}, which a reader calls on the bytes before it decodes,
+ * so the stamp of a decoded array it is given is one this runtime reads.
  */
-export function isV1Snapshot(decoded: unknown): decoded is unknown[] {
-  if (!Array.isArray(decoded) || typeof decoded[0] !== "string" || !decoded[0].startsWith(STORE_FORMAT_PREFIX)) {
-    return false;
-  }
+export function isStoreSnapshot(decoded: unknown): decoded is [StoreFormat, ...unknown[]] {
+  return Array.isArray(decoded) && typeof decoded[0] === "string" && decoded[0].startsWith(STORE_FORMAT_PREFIX);
+}
 
-  if (decoded[0] !== STORE_FORMAT_VERSION) {
+/**
+ * Refuses a store whose header names a format this runtime does not read, judging the header alone: the leading array's first
+ * element, when it is a complete string. The reader calls it before it decodes the body, so a newer store is refused by name
+ * whether or not its body is whole. Bytes with no such header (a legacy array, an empty, truncated or garbled file) are not
+ * refused here.
+ */
+export function refuseUnreadStoreBytes(bytes: Uint8Array): void {
+  const header = peekHeader(bytes);
+  if (header !== undefined && header.startsWith(STORE_FORMAT_PREFIX)) {
+    refuseUnreadFormat(header);
+  }
+}
+
+// The first element of a leading non-empty MessagePack array when it is a complete string; anything else is undefined. The
+// string is decoded by the decoder a read uses, so a stamp gets one verdict from the peek and from the whole decode.
+function peekHeader(bytes: Uint8Array): string | undefined {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const lead = bytes[0];
+  let offset: number;
+  if (lead === undefined) return undefined;
+  if (lead >= 0x91 && lead <= 0x9f) offset = 1;
+  else if (lead === 0xdc && bytes.length >= 3 && view.getUint16(1) > 0) offset = 3;
+  else if (lead === 0xdd && bytes.length >= 5 && view.getUint32(1) > 0) offset = 5;
+  else return undefined;
+  const start = offset;
+  const tag = bytes[offset];
+  let length: number;
+  if (tag === undefined) return undefined;
+  if (tag >= 0xa0 && tag <= 0xbf) { length = tag & 0x1f; offset += 1; }
+  else if (tag === 0xd9 && bytes.length >= offset + 2) { length = bytes[offset + 1]!; offset += 2; }
+  else if (tag === 0xda && bytes.length >= offset + 3) { length = view.getUint16(offset + 1); offset += 3; }
+  else if (tag === 0xdb && bytes.length >= offset + 5) { length = view.getUint32(offset + 1); offset += 5; }
+  else return undefined;
+  if (bytes.length < offset + length) return undefined;
+  const header = decode(bytes.subarray(start, offset + length));
+  return typeof header === "string" ? header : undefined;
+}
+
+/** The one verdict on a stamp: this runtime reads v1 and v3, and any other `cultcache.store.*` header is refused by name. */
+function refuseUnreadFormat(header: string): void {
+  if (header !== STORE_FORMAT_VERSION && header !== STORE_FORMAT_ELEMENT_IDS) {
     throw new Error(
-      `CultCache store format ${describeHeader(decoded[0])} is not one this runtime reads; it reads "${STORE_FORMAT_VERSION}" only.`,
+      `CultCache store format ${describeHeader(header)} is not one this runtime reads; it reads "${STORE_FORMAT_VERSION}" and "${STORE_FORMAT_ELEMENT_IDS}" only.`,
     );
   }
+}
 
-  return true;
+/**
+ * A write the catalog cannot describe: records of different types under one schema id, two arrived schemas that share an id and
+ * disagree on the schema name, or a record no chosen entry publishes. Nothing is written. It names the id, the names involved and
+ * a record key. A cache throws it too, with an empty record key, when a definition cannot register beside one it already holds,
+ * and when a record's schema id names no single registered definition.
+ */
+export class SchemaConflictError extends Error {
+  readonly schemaId: string;
+  readonly schemaNames: string[];
+  readonly recordKey: string;
+
+  constructor(schemaId: string, schemaNames: string[], recordKey: string, message?: string) {
+    super(message ?? `Schema id "${schemaId}" cannot describe record "${recordKey}": ${schemaNames.map((name) => `"${name}"`).join(", ")}.`);
+    this.name = "SchemaConflictError";
+    this.schemaId = schemaId;
+    this.schemaNames = schemaNames;
+    this.recordKey = recordKey;
+  }
+}
+
+/**
+ * A store file this runtime cannot read: not exactly one complete store (truncated, bytes after it, a missing or extra slot),
+ * a header or record it does not know, or a body it cannot decode. Open, flush and every rewrite refuse a file with this
+ * error, and a refused file is left as it was. `cause` is what the reader choked on.
+ */
+export class StoreUnreadableError extends Error {
+  readonly filePath: string;
+
+  constructor(filePath: string, cause: unknown) {
+    super(`CultCache store ${filePath} is not readable: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.name = "StoreUnreadableError";
+    this.filePath = filePath;
+  }
 }
 
 /**
@@ -59,3 +144,10 @@ export function requireV1RecordSlots(record: unknown[]): void {
     );
   }
 }
+
+/** Refuses a store array with more or fewer slots than the header, the schema catalog and the records; a header alone is not a store. */
+export function requireStoreSlots(decoded: unknown[]): void {
+  if (decoded.length !== STORE_SLOTS) {
+    throw new Error(`CultCache store has ${decoded.length} top-level slots; this runtime reads ${STORE_SLOTS} (header, schema catalog, records).`);
+  }
+}

packages/cultcache-ts/test/browser-entry.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { join } from "node:path";
+import test from "node:test";
+import { runInNewContext } from "node:vm";
+import { build } from "esbuild";
+
+// dist-test/test/ -> dist-test/src/
+const srcDir = join(__dirname, "..", "src");
+
+async function bundleForBrowser(entry: string): Promise<string> {
+  const result = await build({
+    entryPoints: [join(srcDir, entry)],
+    bundle: true,
+    platform: "browser",
+    format: "iife",
+    globalName: "cultcache",
+    write: false,
+    logLevel: "silent",
+  });
+  return result.outputFiles[0].text;
+}
+
+test("the browser entry bundles for platform=browser and runs without node", async () => {
+  const code = await bundleForBrowser("browser.js");
+  assert.ok(!/node:fs|koffi/.test(code), "no node-only store in the browser bundle");
+  // A context with no require/process/Buffer: only what a browser page has.
+  const sandbox: Record<string, unknown> = { TextEncoder, TextDecoder };
+  runInNewContext(code + "\nglobalThis.__api = cultcache;", sandbox);
+  const api = sandbox.__api as Record<string, unknown>;
+  assert.equal(typeof api.CultCache, "function");
+  assert.equal(typeof api.defineDocumentType, "function");
+  assert.equal(api.SingleFileMessagePackBackingStore, undefined);
+});
+
+test("the node entry still exports the single-file store and everything the browser entry has", async () => {
+  const node = await import(join(srcDir, "index.js"));
+  const browser = await import(join(srcDir, "browser.js"));
+  assert.equal(typeof node.SingleFileMessagePackBackingStore, "function");
+  assert.equal(typeof node.readSingleFileStore, "function");
+  for (const name of Object.keys(browser)) assert.ok(name in node, `node entry lost ${name}`);
+});
+
+test("the package root keeps the node-only store out of the browser build", async () => {
+  await assert.rejects(bundleForBrowser("index.js"), /node:fs|node:path|koffi/);
+});

packages/cultcache-ts/test/first-call.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+// The TypeScript first-call snippet that docs/start/README.md shows: define a typed document, store it
+// in a .cc file, read it back through a second cache. Keep it small; it is the front door. The docs show
+// the region between the `snippet` markers verbatim, except that the package import reads
+// "@gamecult/cultcache-ts" where this file reads "../src/index"; the docs test below fails when they differ.
+// snippet:begin
+import { z } from "zod";
+import {
+  CultCache,
+  SingleFileMessagePackBackingStore,
+  defineDocumentRegistry,
+  defineDocumentType,
+} from "../src/index";
+
+const itemDocument = defineDocumentType({
+  type: "item",
+  schemaId: "gamecult.first_call_item.v1",
+  schemaName: "gamecult.first_call_item",
+  schemaVersion: "gamecult.first_call_item.v1",
+  schema: z.object({ name: z.string(), category: z.string(), value: z.number().int() }),
+  name: "name",
+  indexes: { category: "category" },
+});
+const registry = defineDocumentRegistry(itemDocument);
+
+async function firstCall(path: string) {
+  const cache = CultCache.builder()
+    .withRegistry(registry)
+    .withGenericStore(new SingleFileMessagePackBackingStore(path))
+    .build();
+  await cache.pullAllBackingStores();
+  await cache.put(itemDocument, "item:potion", { name: "Potion", category: "Consumable", value: 50 });
+
+  const reopened = CultCache.builder()
+    .withRegistry(registry)
+    .withGenericStore(new SingleFileMessagePackBackingStore(path))
+    .build();
+  await reopened.pullAllBackingStores();
+  const potion = reopened.get(itemDocument, "item:potion");
+  const byName = reopened.getByName(itemDocument, "Potion");
+  return { potion, byName };
+}
+// snippet:end
+
+test("define, store and read back a typed document", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "cultcache-first-call-"));
+  try {
+    const { potion, byName } = await firstCall(join(dir, "first-call.cc"));
+    assert.equal(potion?.value, 50);
+    assert.equal(byName?.category, "Consumable");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("docs show the tested snippet", async () => {
+  // Compiled to dist-test/test/first-call.test.js, so the package root is two levels up.
+  const source = await readFile(join(__dirname, "..", "..", "test", "first-call.test.ts"), "utf8");
+  const snippet = source
+    .split("// snippet:begin\n")[1]
+    .split("// snippet:end\n")[0]
+    .replace('"../src/index"', '"@gamecult/cultcache-ts"');
+  const docs = (await readFile(join(__dirname, "..", "..", "..", "..", "docs", "start", "README.md"), "utf8")).replace(/\r\n/g, "\n");
+  assert.ok(docs.includes("```ts\n" + snippet + "```"), "docs/start/README.md no longer shows test/first-call.test.ts");
+});

packages/cultcache-ts/test/payload-depth.test.ts

@@ -20,7 +20,6 @@ import {
 } from "../src/document";
 import * as codecs from "../src/codec";
 import { checkPayloadDepth } from "../src/payload-depth";
-import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store";
 
 const L = MAX_PAYLOAD_DEPTH;
 const CANARY = "CANARY-payload-depth-91d3";
@@ -175,11 +174,11 @@ test("the limit and its error are exported from the root, and the walk itself is
   assert.equal("checkPayloadDepth" in root, false);
 });
 
-// A v1 store whose one record carries `payload` as bin and no catalog entry, so the record's schema is inferred from the
-// payload's first element.
+// A v1 store whose one record carries `payload` as bin, under a catalog entry that names its schema.
 async function storeWith(payload: Uint8Array): Promise<string> {
   const file = join(await mkdtemp(join(tmpdir(), "cultcache-payload-depth-")), "deep.cc");
-  await writeFile(file, encode(["cultcache.store.v1", [], [["record-1", "sha256:stale", "2026-06-25T12:00:00Z", payload]]]));
+  const entry = ["sha256:stale", "tests.schema_stamped_entry", "tests.schema_stamped_entry.v1", "stale", "", [], []];
+  await writeFile(file, encode(["cultcache.store.v1", [entry], [["record-1", "sha256:stale", "2026-06-25T12:00:00Z", payload]]]));
   return file;
 }
 const stamped = (containersInsideTheStamp: number) =>
@@ -189,25 +188,16 @@ test("the inspector previews a payload at the limit and reports one past it, or
   const atLimit = await storeWith(stamped(L - 1));
   const previewed = inspectCultCacheBytes(atLimit, await readFile(atLimit)).records[0]!;
   assert.equal(previewed.payloadDecodeError, undefined);
-  assert.equal(previewed.schemaName, "tests.schema_stamped_entry", "a payload the walk accepts yields its stamp");
+  assert.equal(previewed.schemaName, "tests.schema_stamped_entry");
 
   for (const inside of [L, 100_000]) {
     const file = await storeWith(stamped(inside));
     const record = inspectCultCacheBytes(file, await readFile(file)).records[0]!;
     assert.equal(record.payloadDecodeError, "document payload nests 257 MessagePack containers deep; the limit is 256.");
-    assert.equal(record.schemaName, "<missing catalog entry>", "the stamp of a payload the walk refuses is not recovered");
+    assert.equal(record.schemaName, "tests.schema_stamped_entry");
   }
 });
 
-test("the single-file store infers a legacy record's schema from a payload at the limit and from none past it", async () => {
-  const atLimit = await storeWith(stamped(L - 1));
-  const [read] = await new SingleFileMessagePackBackingStore(atLimit).pullAll();
-  assert.equal(read.catalogEntry?.schemaVersion, "tests.schema_stamped_entry.v1");
-
-  const past = await storeWith(stamped(L));
-  await assert.rejects(() => new SingleFileMessagePackBackingStore(past).pullAll(), /missing schema id/u);
-});
-
 // A header whose length or count needs all four bytes: the low sixteen bits of the length are small, the whole is not.
 const be32 = (n: number) => bytes((n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
 

packages/cultcache-ts/test/store-file.test.ts

@@ -0,0 +1,716 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdirSync, readFileSync } from "node:fs";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import fsp = require("node:fs/promises");
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+
+import { decode, encode } from "@msgpack/msgpack";
+
+import { documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
+import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store";
+import type { CultCacheEnvelope } from "../src/types";
+
+import {
+  MOVEFILE_REPLACE_WRITE_THROUGH,
+  StoreReplacedNotDurableError,
+  commitStoreFile,
+  nodeStoreFileOps,
+  replaceStoreFile,
+  replaceStoreFileWindows,
+  windowsKernel,
+  withStoreWriteLock,
+} from "../src/store-file";
+import type { ReplaceKernel, StoreFileOps } from "../src/store-file";
+
+const execFileAsync = promisify(execFile);
+
+async function scratch(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "cultcache-store-file-"));
+}
+
+function recordingOps(calls: string[], overrides: Partial<StoreFileOps> = {}): StoreFileOps {
+  const real = nodeStoreFileOps;
+  return {
+    createExclusive: async (path) => {
+      calls.push("create");
+      return real.createExclusive(path);
+    },
+    write: async (handle, bytes) => {
+      calls.push("write");
+      await real.write(handle, bytes);
+    },
+    sync: async (handle) => {
+      calls.push("sync");
+      await real.sync(handle);
+    },
+    close: async (handle) => {
+      calls.push("close");
+      await real.close(handle);
+    },
+    replace: async (staged, destination) => {
+      calls.push("replace");
+      await real.replace(staged, destination);
+    },
+    syncDirectory: async (directory) => {
+      calls.push("syncDirectory");
+      await real.syncDirectory(directory);
+    },
+    remove: async (path) => {
+      calls.push("remove");
+      await real.remove(path);
+    },
+    ...overrides,
+  };
+}
+
+test("a commit syncs the staged file before it replaces the store, and the directory after (Unix)", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    const calls: string[] = [];
+    await commitStoreFile(store, new Uint8Array([1, 2, 3]), recordingOps(calls));
+
+    const expected = ["create", "write", "sync", "close", "replace"];
+    if (process.platform !== "win32") {
+      expected.push("syncDirectory");
+    }
+    assert.deepEqual(calls, expected);
+    assert.deepEqual([...(await readFile(store))], [1, 2, 3]);
+    assert.deepEqual(await readdir(directory), ["store.cc"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+// The default write path, with nothing injected: every file handle it opens is observed through
+// fs/promises.open (the module object, read at call time), recording what the handle did and what the
+// store held at that moment. The replace is seen as the store's bytes changing, so the order holds on
+// every platform without a seam in the replace itself.
+test("the default write path syncs and closes the staged file before the store changes, and syncs the directory after (Unix)", async () => {
+  const directory = await scratch();
+  const realOpen = fsp.open;
+  try {
+    const store = join(directory, "store.cc");
+    await writeFile(store, "old");
+    const storeNow = () => readFileSync(store, "utf8");
+    const events: string[] = [];
+    (fsp as { open: typeof fsp.open }).open = (async (path: string, flags?: string) => {
+      const handle = await realOpen(path, flags as never);
+      const kind = basename(String(path)) === basename(directory) ? "dir" : String(path).includes(".tmp-") ? "staged" : "other";
+      const sync = handle.sync.bind(handle);
+      const close = handle.close.bind(handle);
+      handle.sync = () => {
+        events.push(`sync:${kind}:${storeNow()}`);
+        return sync();
+      };
+      handle.close = () => {
+        events.push(`close:${kind}:${storeNow()}`);
+        return close();
+      };
+      return handle;
+    }) as typeof fsp.open;
+
+    await commitStoreFile(store, new TextEncoder().encode("new"));
+    (fsp as { open: typeof fsp.open }).open = realOpen;
+
+    // The staged file is synced, then closed, while the store still holds its old bytes.
+    assert.deepEqual(events.filter((event) => event.includes(":staged:")), ["sync:staged:old", "close:staged:old"]);
+    if (process.platform === "win32") {
+      assert.deepEqual(events.filter((event) => event.includes(":dir:")), [], "Windows relies on the replace and opens no directory");
+    } else {
+      // The directory is synced and closed after the store changed.
+      assert.deepEqual(events.filter((event) => event.includes(":dir:")), ["sync:dir:new", "close:dir:new"]);
+    }
+    assert.equal(storeNow(), "new");
+  } finally {
+    (fsp as { open: typeof fsp.open }).open = realOpen;
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a commit that fails before the replace leaves the store byte for byte and no staged file behind", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    await writeFile(store, Buffer.from([9, 9, 9]));
+    const calls: string[] = [];
+    const ops = recordingOps(calls, {
+      replace: async () => {
+        calls.push("replace");
+        throw new Error("replace refused");
+      },
+    });
+
+    await assert.rejects(commitStoreFile(store, new Uint8Array([1]), ops), /replace refused/);
+
+    assert.deepEqual([...(await readFile(store))], [9, 9, 9]);
+    assert.deepEqual(await readdir(directory), ["store.cc"]);
+    assert.ok(calls.includes("remove"));
+    assert.equal(calls.filter((call) => call === "close").length, 1, "the staged handle is closed exactly once");
+    assert.ok(!calls.includes("syncDirectory"));
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a commit whose staged file cannot be synced never replaces the store", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    await writeFile(store, Buffer.from([9]));
+    const calls: string[] = [];
+    const ops = recordingOps(calls, {
+      sync: async () => {
+        calls.push("sync");
+        throw new Error("disk full");
+      },
+    });
+
+    await assert.rejects(commitStoreFile(store, new Uint8Array([1]), ops), /disk full/);
+
+    assert.ok(!calls.includes("replace"));
+    assert.ok(calls.indexOf("close") !== -1 && calls.indexOf("close") < calls.indexOf("remove"), "the staged handle is closed, then the file removed");
+    assert.deepEqual([...(await readFile(store))], [9]);
+    assert.deepEqual(await readdir(directory), ["store.cc"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test(
+  "a directory sync failure after the replace reports the store replaced but not durable",
+  { skip: process.platform === "win32" },
+  async () => {
+    const directory = await scratch();
+    try {
+      const store = join(directory, "store.cc");
+      await writeFile(store, Buffer.from([9]));
+      const ops = recordingOps([], {
+        syncDirectory: async () => {
+          throw new Error("EIO");
+        },
+      });
+
+      await assert.rejects(commitStoreFile(store, new Uint8Array([1]), ops), (error: unknown) => {
+        assert.ok(error instanceof StoreReplacedNotDurableError);
+        assert.equal(error.replaced, true);
+        assert.equal(error.name, "StoreReplacedNotDurableError");
+        assert.match(error.message, /was replaced/);
+        return true;
+      });
+
+      assert.deepEqual([...(await readFile(store))], [1]);
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+function fakeKernel(
+  posix: number[],
+  moveEx: number[],
+): { kernel: ReplaceKernel; log: string[]; sleeps: number[] } {
+  const log: string[] = [];
+  const sleeps: number[] = [];
+  const kernel: ReplaceKernel = {
+    renamePosix: () => {
+      log.push("posix");
+      return posix.shift() ?? 0;
+    },
+    moveFileEx: (_staged, _destination, flags) => {
+      log.push(`moveex:${flags}`);
+      return moveEx.shift() ?? 0;
+    },
+    sleep: async (ms) => {
+      sleeps.push(ms);
+    },
+  };
+  return { kernel, log, sleeps };
+}
+
+test("the Windows replace falls back to write-through MoveFileExW where POSIX rename is unsupported, retries 5/32/33, and gives up after 25 attempts", async () => {
+  for (const unsupported of [1, 50, 87]) {
+    const { kernel, log } = fakeKernel([unsupported], [0]);
+    await replaceStoreFileWindows("a", "b", kernel);
+    assert.deepEqual(log, ["posix", `moveex:${MOVEFILE_REPLACE_WRITE_THROUGH}`]);
+  }
+  assert.equal(MOVEFILE_REPLACE_WRITE_THROUGH, 0x9);
+
+  // Once POSIX is unsupported the rest of the call stays on MoveFileExW.
+  {
+    const { kernel, log } = fakeKernel([87], [32, 0]);
+    await replaceStoreFileWindows("a", "b", kernel);
+    assert.deepEqual(log, ["posix", "moveex:9", "moveex:9"]);
+  }
+
+  for (const transient of [5, 32, 33]) {
+    const { kernel, log, sleeps } = fakeKernel([transient, transient, 0], []);
+    await replaceStoreFileWindows("a", "b", kernel);
+    assert.deepEqual(log, ["posix", "posix", "posix"], "a transient error retries the same primitive");
+    assert.deepEqual(sleeps, [20, 20]);
+  }
+
+  // A POSIX rename that works is the whole replace.
+  {
+    const { kernel, log, sleeps } = fakeKernel([0], []);
+    await replaceStoreFileWindows("a", "b", kernel);
+    assert.deepEqual(log, ["posix"]);
+    assert.deepEqual(sleeps, []);
+  }
+
+  // Once on MoveFileExW, an "unsupported" code is an error in any later attempt, never another fallback.
+  {
+    const { kernel, log } = fakeKernel([87], [32, 87]);
+    await assert.rejects(replaceStoreFileWindows("a", "b", kernel), /Win32 error 87/);
+    assert.deepEqual(log, ["posix", "moveex:9", "moveex:9"]);
+  }
+
+  // After the fallback, an "unsupported" code is an error, not another fallback.
+  for (const unsupported of [1, 50, 87]) {
+    const { kernel, log } = fakeKernel([87], [unsupported]);
+    await assert.rejects(replaceStoreFileWindows("a", "b", kernel), new RegExp(`Win32 error ${unsupported}`));
+    assert.deepEqual(log, ["posix", "moveex:9"]);
+  }
+
+  {
+    const { kernel, log } = fakeKernel(Array(30).fill(32), []);
+    await assert.rejects(replaceStoreFileWindows("a", "b", kernel), /after 25 attempts.*32/);
+    assert.equal(log.length, 25);
+  }
+
+  {
+    const { kernel, log } = fakeKernel([2], []);
+    await assert.rejects(replaceStoreFileWindows("a", "b", kernel), /Win32 error 2/);
+    assert.equal(log.length, 1);
+  }
+
+  {
+    const { kernel } = fakeKernel([87], [3]);
+    await assert.rejects(replaceStoreFileWindows("a", "b", kernel), /Win32 error 3/);
+  }
+});
+
+// The reader is a koffi CreateFileW holding the store sharing read, write and delete, the way
+// the C# and Rust readers hold it.
+function openSharingAll(path: string): { close: () => void } {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const koffi = require("koffi");
+  const lib = koffi.load("kernel32.dll");
+  const createFileW = lib.func(
+    "intptr_t CreateFileW(str16 name, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t flags, void *template)",
+  );
+  const closeHandle = lib.func("int CloseHandle(intptr_t handle)");
+  const handle = Number(createFileW(path, 0x80000000, 0x7, null, 3, 0x80, null));
+  assert.notEqual(handle, -1, "the reader could not open the store");
+  let closed = false;
+  return { close: () => { if (!closed) { closed = true; closeHandle(handle); } } };
+}
+
+function openSharingReadWrite(path: string): { close: () => void } {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const koffi = require("koffi");
+  const lib = koffi.load("kernel32.dll");
+  const createFileW = lib.func(
+    "intptr_t CreateFileW(str16 name, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t flags, void *template)",
+  );
+  const closeHandle = lib.func("int CloseHandle(intptr_t handle)");
+  const handle = Number(createFileW(path, 0x80000000, 0x3, null, 3, 0x80, null));
+  assert.notEqual(handle, -1, "the reader could not open the store");
+  let closed = false;
+  return { close: () => { if (!closed) { closed = true; closeHandle(handle); } } };
+}
+
+test(
+  "windows: a store replace lands while a reader holds the store sharing delete, as C# and Rust readers do",
+  { skip: process.platform !== "win32" },
+  async () => {
+    const directory = await scratch();
+    try {
+      const store = join(directory, "store.cc");
+      const staged = join(directory, "staged.tmp");
+      await writeFile(store, Buffer.from([1, 1, 1]));
+      await writeFile(staged, Buffer.from([2, 2, 2]));
+      const reader = openSharingAll(store);
+      try {
+        await replaceStoreFile(staged, store);
+        assert.deepEqual([...(await readFile(store))], [2, 2, 2]);
+      } finally {
+        reader.close();
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+test(
+  "windows: a replace waits out a reader that holds the store without delete sharing",
+  { skip: process.platform !== "win32" },
+  async () => {
+    const directory = await scratch();
+    try {
+      const store = join(directory, "store.cc");
+      const staged = join(directory, "staged.tmp");
+      await writeFile(store, Buffer.from([1, 1, 1]));
+      await writeFile(staged, Buffer.from([2, 2, 2]));
+      const reader = openSharingReadWrite(store);
+      const release = setTimeout(() => reader.close(), 120);
+      try {
+        await replaceStoreFile(staged, store);
+        assert.deepEqual([...(await readFile(store))], [2, 2, 2]);
+      } finally {
+        clearTimeout(release);
+        reader.close();
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------------------------
+// The cross-process write lock (TypeScript against TypeScript; C# and Rust are in cult-cache.test.ts).
+
+const entryOf = (key: string, type = "t", marker = 0): CultCacheEnvelope => ({
+  key,
+  type,
+  payload: documentPayloadFromBytes(Uint8Array.of(0x91, marker)),
+  storedAt: "2026-10-20T00:00:00Z",
+});
+
+function sleepFor(milliseconds: number): Promise<void> {
+  return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
+}
+
+function within<T>(promise: Promise<T>, milliseconds: number, what: string): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const expired = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${what} did not finish within ${milliseconds} ms (deadlock)`)), milliseconds);
+  });
+  return Promise.race([promise, expired]).finally(() => clearTimeout(timer));
+}
+
+test("a second writer in this process waits for the store lock and runs after release", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    const order: string[] = [];
+    let second: Promise<void> | undefined;
+    await withStoreWriteLock(store, async () => {
+      second = withStoreWriteLock(store, async () => {
+        order.push("second");
+      });
+      await sleepFor(150);
+      order.push("first-done");
+    });
+    await second;
+    assert.deepEqual(order, ["first-done", "second"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("the store lock gives up after its wait bound and names the lock path", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    await withStoreWriteLock(store, async () => {
+      await assert.rejects(
+        withStoreWriteLock(store, async () => undefined, { timeoutMs: 200 }),
+        (error: Error) => error.message.includes(`${store}.lock`) && /200 ms/.test(error.message),
+      );
+    });
+    // The failed waiter released nothing it did not hold: the lock is free again.
+    assert.equal(await withStoreWriteLock(store, async () => "free", { timeoutMs: 200 }), "free");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a directory at the lock path fails at once with the lock path named, not after the 30 s wait", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    mkdirSync(`${store}.lock`);
+    const started = Date.now();
+    let ran = false;
+    // The default wait bound (30 s) is in force: only a failure that does not wait can beat the race.
+    const outcome = await Promise.race([
+      withStoreWriteLock(store, async () => {
+        ran = true;
+      }).then(
+        () => ({ error: undefined as Error | undefined }),
+        (error: Error) => ({ error }),
+      ),
+      new Promise<"waiting">((resolveWait) => setTimeout(() => resolveWait("waiting"), 3000).unref()),
+    ]);
+    assert.notEqual(outcome, "waiting", "the lock attempt was still waiting after 3 s");
+    const { error } = outcome as { error: Error | undefined };
+    assert.ok(error, "locking a directory must fail");
+    assert.ok(error.message.includes(`${store}.lock`), error.message);
+    assert.ok(!/timed out/.test(error.message), error.message);
+    assert.ok(Date.now() - started < 3000);
+    assert.equal(ran, false);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("the store lock is released when the operation throws", async () => {
+  const directory = await scratch();
+  try {
+    const store = join(directory, "store.cc");
+    await assert.rejects(withStoreWriteLock(store, async () => Promise.reject(new Error("boom"))), /boom/);
+    assert.equal(await withStoreWriteLock(store, async () => "free", { timeoutMs: 200 }), "free");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+const legacyObjectPayload = (): Uint8Array =>
+  encode([{ key: "note:hello", type: "note", payload: { title: "Hello" }, storedAt: "2026-10-20T00:00:00Z" }]);
+
+test("an open that heals a legacy store waits for the store lock and heals from its own read", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "legacy.cc");
+    const legacy = legacyObjectPayload();
+    await writeFile(path, legacy);
+    const store = new SingleFileMessagePackBackingStore(path);
+    let healed: Promise<unknown> | undefined;
+    let settled = false;
+    await withStoreWriteLock(path, async () => {
+      healed = store.pullAll().then(() => {
+        settled = true;
+      });
+      await sleepFor(300);
+      assert.equal(settled, false, "the heal must wait for the lock");
+      assert.deepEqual([...(await readFile(path))], [...legacy], "the file keeps its legacy bytes while the lock is held elsewhere");
+    });
+    await within(healed!, 5000, "the heal");
+    assert.equal((decode(await readFile(path)) as unknown[])[0], "cultcache.store.v1");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("push and delete over a legacy store that needs healing finish instead of waiting on their own lock", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "legacy.cc");
+    await writeFile(path, legacyObjectPayload());
+    const store = new SingleFileMessagePackBackingStore(path);
+    await within(store.push(entryOf("a")), 5000, "push");
+    await writeFile(path, legacyObjectPayload());
+    await within(store.delete(entryOf("a")), 5000, "delete");
+    const keys = (await store.pullAll()).map((entry) => entry.key);
+    assert.deepEqual(keys, ["note:hello"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("two TypeScript processes pushing distinct keys to one store lose none", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    const dist = resolve(__dirname, "..", "..", "dist");
+    const script = `
+      const { SingleFileMessagePackBackingStore } = require(${JSON.stringify(join(dist, "single-file-messagepack-backing-store.js"))});
+      const { documentPayloadFromBytes } = require(${JSON.stringify(join(dist, "document.js"))});
+      (async () => {
+        const store = new SingleFileMessagePackBackingStore(${JSON.stringify(path)});
+        for (let i = 0; i < 40; i++) {
+          await store.push({ key: process.argv[1] + "-" + i, type: "t", payload: documentPayloadFromBytes(Uint8Array.of(0x90)), storedAt: "2026-10-20T00:00:00Z" });
+        }
+      })().catch((error) => { console.error(error); process.exit(1); });
+    `;
+    await Promise.all(
+      ["p", "q"].map((name) => execFileAsync(process.execPath, ["-e", script, name], { timeout: 120_000 })),
+    );
+    const keys = (await new SingleFileMessagePackBackingStore(path).pullAll()).map((entry) => entry.key).sort();
+    assert.equal(keys.length, 80);
+    assert.equal(new Set(keys).size, 80);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+const snapshotOf = async (store: SingleFileMessagePackBackingStore): Promise<string[]> =>
+  (await store.pullAll())
+    .map((entry) => `${entry.type}/${entry.key}:${[...documentPayloadBytes(entry.payload)].at(-1)}`)
+    .sort();
+
+test("push replaces the record at the same type and key and keeps every other", async () => {
+  const directory = await scratch();
+  try {
+    const store = new SingleFileMessagePackBackingStore(join(directory, "store.cc"));
+    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("a", "u", 3)]);
+    await store.push(entryOf("a", "t", 9));
+    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "u/a:3"]);
+    await store.push(entryOf("c", "t", 4));
+    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "t/c:4", "u/a:3"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("delete removes only the record at that type and key", async () => {
+  const directory = await scratch();
+  try {
+    const store = new SingleFileMessagePackBackingStore(join(directory, "store.cc"));
+    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("a", "u", 3)]);
+    await store.delete(entryOf("a", "t"));
+    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/a:3"]);
+    await store.delete(entryOf("zzz", "t"));
+    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/a:3"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("pushAll replaces the whole store, and a soft pushAll leaves an existing store alone", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    const store = new SingleFileMessagePackBackingStore(path);
+    await store.pushAll([entryOf("a", "t", 1)], { soft: true });
+    assert.deepEqual(await snapshotOf(store), ["t/a:1"]);
+    const before = await readFile(path);
+    await store.pushAll([entryOf("b", "t", 2)], { soft: true });
+    assert.deepEqual([...(await readFile(path))], [...before], "soft leaves an existing store byte for byte");
+    await store.pushAll([entryOf("b", "t", 2)]);
+    assert.deepEqual(await snapshotOf(store), ["t/b:2"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a read of a current store never waits for the store lock, and a missing store reads empty", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    const store = new SingleFileMessagePackBackingStore(path);
+    await store.push(entryOf("a"));
+    await withStoreWriteLock(path, async () => {
+      assert.deepEqual(await within(store.pullAll().then((rows) => rows.map((row) => row.key)), 2000, "a read"), ["a"]);
+      const missing = new SingleFileMessagePackBackingStore(join(directory, "absent.cc"));
+      assert.deepEqual(await within(missing.pullAll(), 2000, "a read of a missing store"), []);
+    });
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+// A share-none open succeeds only when no other handle on the file is open, as C# readers and
+// writers need it to.
+function canOpenShareNone(path: string): boolean {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const koffi = require("koffi");
+  const lib = koffi.load("kernel32.dll");
+  const createFileW = lib.func(
+    "intptr_t CreateFileW(str16 name, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t flags, void *template)",
+  );
+  const closeHandle = lib.func("int CloseHandle(intptr_t handle)");
+  const handle = Number(createFileW(path, 0x80000000, 0, null, 3, 0x80, null));
+  if (handle === -1) {
+    return false;
+  }
+
+  closeHandle(handle);
+  return true;
+}
+
+test(
+  "windows: the real kernel replaces through both primitives and reports the Win32 error of a missing source",
+  { skip: process.platform !== "win32" },
+  async () => {
+    const directory = await scratch();
+    try {
+      const kernel = windowsKernel();
+      for (const [name, replace] of [
+        ["posix", (staged: string, store: string) => kernel.renamePosix(staged, store)],
+        ["moveex", (staged: string, store: string) => kernel.moveFileEx(staged, store, MOVEFILE_REPLACE_WRITE_THROUGH)],
+      ] as const) {
+        const store = join(directory, `${name}.cc`);
+        const staged = join(directory, `${name}.tmp`);
+        await writeFile(store, Buffer.from([1]));
+        await writeFile(staged, Buffer.from([2]));
+        assert.equal(replace(staged, store), 0, name);
+        assert.ok(canOpenShareNone(store), `${name}: the replace left a handle open on the store`);
+        assert.deepEqual([...(await readFile(store))], [2], name);
+        assert.deepEqual(await readdir(directory).then((names) => names.filter((n) => n === `${name}.tmp`)), [], name);
+        assert.equal(replace(join(directory, "missing.tmp"), store), 2, `${name}: ERROR_FILE_NOT_FOUND`);
+      }
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+test(
+  "windows: after a write and after a waiter gave up, the lock file is held by no handle, so a share-none open (C#'s lock) succeeds",
+  { skip: process.platform !== "win32" },
+  async () => {
+    const directory = await scratch();
+    try {
+      const store = join(directory, "store.cc");
+      await withStoreWriteLock(store, async () => {
+        // A waiter that polls and gives up must not leave a handle on the lock file either.
+        await assert.rejects(withStoreWriteLock(store, async () => undefined, { timeoutMs: 100 }), /timed out/);
+      });
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const koffi = require("koffi");
+      const lib = koffi.load("kernel32.dll");
+      const createFileW = lib.func(
+        "intptr_t CreateFileW(str16 name, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t flags, void *template)",
+      );
+      const closeHandle = lib.func("int CloseHandle(intptr_t handle)");
+      const handle = Number(createFileW(`${store}.lock`, 0xc0000000, 0, null, 4, 0x80, null));
+      assert.notEqual(handle, -1, "the lock file is still held open after the write");
+      closeHandle(handle);
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+);
+
+test("a store file of an unrecognized shape is refused, and a store naming a missing schema id is refused naming the record", async () => {
+  const directory = await scratch();
+  try {
+    const odd = join(directory, "odd.cc");
+    await writeFile(odd, encode({ not: "a store" }));
+    await assert.rejects(new SingleFileMessagePackBackingStore(odd).pullAll(), /is not a recognized CultCache MessagePack store/);
+
+    const dangling = join(directory, "dangling.cc");
+    await writeFile(dangling, encode(["cultcache.store.v1", [], [["rec:1", "sha256:missing", "2026-10-20T00:00:00Z", Uint8Array.of(0x90)]]]));
+    await assert.rejects(
+      new SingleFileMessagePackBackingStore(dangling).pullAll(),
+      /persisted record "rec:1" references missing schema id "sha256:missing"/,
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("opening a store that needs no healing writes nothing: a missing store leaves no lock file, a legacy store with byte payloads keeps its bytes", async () => {
+  const directory = await scratch();
+  try {
+    const absent = join(directory, "nested", "absent.cc");
+    assert.deepEqual(await new SingleFileMessagePackBackingStore(absent).pullAll(), []);
+    assert.deepEqual(await readdir(directory), [], "a read of a missing store creates neither its directory nor its lock");
+
+    const legacyBytes = encode([{ key: "k", type: "t", payload: Uint8Array.of(0x90), storedAt: "2026-10-20T00:00:00Z" }]);
+    const path = join(directory, "legacy-bytes.cc");
+    await writeFile(path, legacyBytes);
+    assert.deepEqual((await new SingleFileMessagePackBackingStore(path).pullAll()).map((entry) => entry.key), ["k"]);
+    assert.deepEqual([...(await readFile(path))], [...legacyBytes], "a legacy store whose payloads are already bytes is not rewritten");
+    assert.deepEqual((await readdir(directory)).sort(), ["legacy-bytes.cc"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

packages/cultcache-ts/test/union-parity.test.ts

@@ -48,16 +48,23 @@ type Node =
   | { kind: "Text"; id: string; content: string }
   | { kind: "Use"; id: string; composition: Composition; slots: (Node | null)[] }
   | { kind: "Image"; id: string; uri: string; alt: string }
-  | { kind: "Wrap"; inner: Node | null };
+  | { kind: "Wrap"; inner: Node | null; id: string };
 interface Composition { name: string; body: Node | null }
 type Outcome = { kind: "Pending"; message: string } | { kind: "Completed"; sourceVersion: number } | { kind: "Denied" } | { kind: "Floor" } | { kind: "Ceiling" };
+// The golden's Outcome: the arms of a list carry an element id, so Denied, Floor and Ceiling are one-slot records.
+type GoldenOutcome =
+  | { kind: "Pending"; message: string; id: string }
+  | { kind: "Completed"; sourceVersion: number; id: string }
+  | { kind: "Denied"; id: string }
+  | { kind: "Floor"; id: string }
+  | { kind: "Ceiling"; id: string };
 type Item = { kind: "Gem"; name: string } | { kind: "Tool"; name: string; uses: number } | { kind: "Part"; name: string; count: number };
 type CraftedItem = { kind: "Tool"; name: string; uses: number } | { kind: "Part"; name: string; count: number };
 interface Surface {
   id: string;
   version: number;
   root: Node | null;
-  outcomes: (Outcome | null)[];
+  outcomes: (GoldenOutcome | null)[];
   part: Item | null;
   crafted: CraftedItem | null;
   missing: Node | null;
@@ -71,7 +78,7 @@ const node: Codec<Node | null> = union<Node>("Node", {
     0: ["id", string], 1: ["composition", composition], 2: ["slots", list(lazy(() => node))],
   })],
   5: ["Image", slots<{ id: string; uri: string; alt: string }>({ 0: ["id", string], 1: ["uri", string], 3: ["alt", string] })],
-  6: ["Wrap", slots<{ inner: Node | null }>({ 0: ["inner", lazy(() => node)] })],
+  6: ["Wrap", slots<{ inner: Node | null; id: string }>({ 0: ["inner", lazy(() => node)], 1: ["id", string] })],
 }, `${CS}Node`);
 const outcome = union<Outcome>("Outcome", {
   0: ["Pending", slots<{ message: string }>({ 0: ["message", string] })],
@@ -80,6 +87,14 @@ const outcome = union<Outcome>("Outcome", {
   [-2147483648]: ["Floor", unit],
   2147483647: ["Ceiling", unit],
 }, `${CS}Outcome`);
+const idOnly = slots<{ id: string }>({ 0: ["id", string] });
+const goldenOutcome = union<GoldenOutcome>("Outcome", {
+  0: ["Pending", slots<{ message: string; id: string }>({ 0: ["message", string], 1: ["id", string] })],
+  1: ["Completed", slots<{ sourceVersion: number; id: string }>({ 0: ["sourceVersion", int32], 1: ["id", string] })],
+  2: ["Denied", idOnly],
+  [-2147483648]: ["Floor", idOnly],
+  2147483647: ["Ceiling", idOnly],
+}, `${CS}Outcome`);
 const toolArm = slots<{ name: string; uses: number }>({ 0: ["name", string], 1: ["uses", int32] });
 const partArm = slots<{ name: string; count: number }>({ 0: ["name", string], 1: ["count", int32] });
 const item = union<Item>("Item", {
@@ -92,7 +107,7 @@ const surfaceCodec = slots<Surface>({
   0: ["id", string],
   1: ["version", int32],
   2: ["root", node],
-  3: ["outcomes", list(outcome)],
+  3: ["outcomes", list(goldenOutcome)],
   4: ["part", item],
   5: ["crafted", craftedItem],
   6: ["missing", node, null],
@@ -111,7 +126,7 @@ const nodeSchema: z.ZodType<Node | null> = z.lazy(() =>
         slots: z.array(nodeSchema),
       }),
       z.object({ kind: z.literal("Image"), id: z.string(), uri: z.string(), alt: z.string() }),
-      z.object({ kind: z.literal("Wrap"), inner: nodeSchema }),
+      z.object({ kind: z.literal("Wrap"), inner: nodeSchema, id: z.string() }),
     ]),
   ]));
 const surfaceSchema = z.object({
@@ -121,11 +136,11 @@ const surfaceSchema = z.object({
   outcomes: z.array(z.union([
     z.null(),
     z.discriminatedUnion("kind", [
-      z.object({ kind: z.literal("Pending"), message: z.string() }),
-      z.object({ kind: z.literal("Completed"), sourceVersion: z.number() }),
-      z.object({ kind: z.literal("Denied") }),
-      z.object({ kind: z.literal("Floor") }),
-      z.object({ kind: z.literal("Ceiling") }),
+      z.object({ kind: z.literal("Pending"), message: z.string(), id: z.string() }),
+      z.object({ kind: z.literal("Completed"), sourceVersion: z.number(), id: z.string() }),
+      z.object({ kind: z.literal("Denied"), id: z.string() }),
+      z.object({ kind: z.literal("Floor"), id: z.string() }),
+      z.object({ kind: z.literal("Ceiling"), id: z.string() }),
     ]),
   ])),
   part: z.union([z.null(), z.discriminatedUnion("kind", [
@@ -157,29 +172,33 @@ const golden: Surface = {
   version: 3,
   root: {
     kind: "Box",
-    id: "root",
+    id: "0000000000c0",
     children: [
-      { kind: "Text", id: "t1", content: "hello" },
+      { kind: "Text", id: "0000000000c1", content: "hello" },
       {
         kind: "Use",
-        id: "u1",
+        id: "0000000000c2",
         composition: {
           name: "comp",
           body: {
             kind: "Box",
-            id: "inner",
+            id: "0000000000d0",
             children: [
-              { kind: "Text", id: "deep", content: "x" },
-              { kind: "Image", id: "img", uri: "uri://a", alt: "alt" },
+              { kind: "Text", id: "0000000000d1", content: "x" },
+              { kind: "Image", id: "0000000000d2", uri: "uri://a", alt: "alt" },
             ],
           },
         },
-        slots: [{ kind: "Text", id: "s1", content: "slot" }, null, { kind: "Box", id: "b2", children: [] }],
+        slots: [{ kind: "Text", id: "0000000000e1", content: "slot" }, null, { kind: "Box", id: "0000000000e2", children: [] }],
       },
-      { kind: "Image", id: "i2", uri: "uri://b", alt: "" },
+      { kind: "Image", id: "0000000000c3", uri: "uri://b", alt: "" },
     ],
   },
-  outcomes: [{ kind: "Pending", message: "wait" }, { kind: "Completed", sourceVersion: 7 }, { kind: "Denied" }],
+  outcomes: [
+    { kind: "Pending", message: "wait", id: "0000000000a1" },
+    { kind: "Completed", sourceVersion: 7, id: "0000000000a2" },
+    { kind: "Denied", id: "0000000000a3" },
+  ],
   part: { kind: "Tool", name: "hammer", uses: 12 },
   crafted: { kind: "Part", name: "gear", count: 4 },
   missing: null,
@@ -200,8 +219,13 @@ test("the union surface vector decodes to the constructed value and re-encodes b
   assert.equal(hex(writeWire(surfaceCodec.encode(golden))), hex(committed));
 });
 
-test("a unit arm is written [key, []] and its payload must be an array", () => {
-  assert.deepEqual(outcome.encode({ kind: "Denied" }), [2, []]);
+test("a unit arm is written as the C# reference writes it, and its payload must be an array", async () => {
+  // The bytes are tests/vectors/union-parity/unit-arm-*.msgpack, written by the reference, not spelled here.
+  for (const [file, kind] of [["denied", "Denied"], ["floor", "Floor"], ["ceiling", "Ceiling"]] as const) {
+    const reference = await read(`unit-arm-${file}.msgpack`);
+    assert.deepEqual(outcome.decode(readWire(reference)), { kind }, file);
+    assert.equal(hex(writeWire(outcome.encode({ kind }))), hex(reference), file);
+  }
   assert.throws(() => outcome.decode([2, null]), /Union Outcome/u);
 });
 
@@ -814,14 +838,14 @@ test("a bytes slot reads a MessagePack str as its bytes and writes bin, and refu
 
 const wrapChain = (wraps: number, leaf: Node): Node => {
   let node: Node = leaf;
-  for (let index = 0; index < wraps; index += 1) node = { kind: "Wrap", inner: node };
+  for (let index = 0; index < wraps; index += 1) node = { kind: "Wrap", inner: node, id: "0000000000b1" };
   return node;
 };
 // A Wrap adds 2 containers, a Box with no children 3, a Text leaf 2, and the outermost array is 1 (the C# test's arithmetic).
 const AT_LIMIT_WRAPS = (MAX_PAYLOAD_DEPTH - 1 - 3) / 2;
 const PAST_LIMIT_WRAPS = (MAX_PAYLOAD_DEPTH + 1 - 1 - 2) / 2;
-const atLimitValue: Surface = { ...golden, root: wrapChain(AT_LIMIT_WRAPS, { kind: "Box", id: "leaf", children: [] }) };
-const pastLimitValue: Surface = { ...golden, root: wrapChain(PAST_LIMIT_WRAPS, { kind: "Text", id: "leaf", content: CANARY }) };
+const atLimitValue: Surface = { ...golden, root: wrapChain(AT_LIMIT_WRAPS, { kind: "Box", id: "0000000000f0", children: [] }) };
+const pastLimitValue: Surface = { ...golden, root: wrapChain(PAST_LIMIT_WRAPS, { kind: "Text", id: "0000000000f0", content: CANARY }) };
 
 async function boundsEntries() {
   const raw = decode(await read("bounds-outcomes.msgpack")) as unknown[][];

packages/cultmath/README.md

@@ -29,7 +29,8 @@ shader semantics.
   `cross`, `length`, `distance`, `normalize`, `reflect`, `csum`, `erf`,
   `erfinv` (scalar only), exponential
   `decay`/`damp`, intercept/segment helpers (`distance_to_segment` in 2D and 3D, with and without `out closest`, and `segment_closest`), Catmull-Rom, Bezier curves, and
-  deterministic value-noise primitives
+  deterministic value-noise primitives, and `fbm(p)` / `fbm(p, octaves, lacunarity, gain)`, the value-only octave sum
+  of `snoise` (`cultmath_fbm` in HLSL and GLSL)
 - Site cells: `power_cells` and `multiplicative_cells` return the two nearest sites of a point as `CultSiteCells`,
   `soft_gabriel_gate` gates a pair of sites by the empty-disc margin. Each is a loop over the shader steps
   `cultmath_power_score` / `cultmath_multiplicative_score`, `cultmath_site_cells_empty`, `cultmath_site_cells_insert`,

packages/cultmath/docs/design.md

@@ -451,6 +451,26 @@ together, laid out as `float4(gradient.xyz, value.w)`, with no value-only twin
   nearly cancels. The total weight `W` is positive for every `pcg3d` input (the
   smallest found by hill-climbing is 0.056); `W = 0`, and a NaN output, needs
   adversarial jitter no hash yields.
+  Lipschitz bound of the `(cosine, sine)` field in `p` (one cell is 1 unit): the
+  largest singular value of its 2×3 Jacobian is at most
+  `max(10, 1.25 |side|) / (1 - normalization)` for `normalization` in `[0, 0.9]` and
+  `|side|` in `[0.25, 25]`. A scalar use of `cosine` or `sine` alone is bounded by the same number (its gradient norm is
+  one row of the Jacobian, never above the largest singular value). Method (`tools/phacelle-lipschitz`):
+  random `p` (a 64-unit cube), a uniformly random `side` direction and offset, the
+  exact gradient at each, 4 million samples per (normalization, |side|); then
+  hill-climbing from the 256 best samples over `p`, `side` direction and offset
+  (10 000 steps each); then value differences around the climbed argmax to confirm the
+  gradient is the field's slope (agreement within 3%). Random sampling alone
+  undershoots the climbed maximum by up to 4×, because the maxima sit at near-cancellation
+  points of the blend (`1/|I|`); quote the climbed number. The climbed sup is 0.016 to 0.88 of
+  the envelope over the sweep: tightest (within 1.15×) at `normalization` 0 and `|side| >= 8`,
+  and 1.5 to 60× loose at small `|side|` or large `normalization`, where the
+  envelope's constant 10 is the worst case over all `|side|`. The typical gradient (99.99th percentile of the
+  samples) is 2 to 5× below the sup, so a sphere trace steps safely at `distance / L`
+  and can step farther with the returned gradient. The bound is not a proof (a
+  search found it, not an argument) and it does not hold as `normalization` approaches 1:
+  the 1/|I| factor is unbounded there (sampled 1335 at `normalization` 1, `|side|` 2π, and
+  rising with the sample count). If the caller scales `p` by `f` the bound scales by `f`.
   Cells whose per-axis lower bound `Σ max(0, |local - g| - 0.5)²` is at least
   2.25 lie outside the support and have weight exactly 0, so they are skipped,
   which changes no output bit. Cells whose bound sits just under 2.25 can still

packages/cultmath/shaders/CultMath.glsl

@@ -342,6 +342,26 @@ vec4 cultmath_fbm_grad(vec3 p, int octaves, float lacunarity, float gain)
     return vec4(gradient, value);
 }
 
+// Value-only octave sum of cultmath_snoise; see the C# math.fbm comment. The one-argument form is four octaves,
+// lacunarity 2, gain 0.5.
+float cultmath_fbm(vec3 p, int octaves, float lacunarity, float gain)
+{
+    octaves = clamp(octaves, 0, 16);
+    float amplitude = 1.0;
+    float frequency = 1.0;
+    float value = 0.0;
+    for (int i = 0; i < octaves; i++)
+    {
+        value += amplitude * cultmath_snoise(p * frequency);
+        frequency *= lacunarity;
+        amplitude *= gain;
+    }
+
+    return value;
+}
+
+float cultmath_fbm(vec3 value) { return cultmath_fbm(value, 4, 2.0, 0.5); }
+
 // Ridged multifractal noise (Musgrave, Texturing and Modeling, ch. 16); see the C# math.ridged_grad
 // comment for the fold/sign derivation, the deliberate crease at n = 0, and why octaves is clamped.
 vec4 cultmath_ridged_grad(vec3 p, int octaves, float lacunarity, float gain)

packages/cultmath/shaders/CultMath.hlsl

@@ -342,6 +342,26 @@ float4 cultmath_fbm_grad(float3 p, int octaves, float lacunarity, float gain)
     return float4(gradient, value);
 }
 
+// Value-only octave sum of cultmath_snoise; see the C# math.fbm comment. The one-argument form is four octaves,
+// lacunarity 2, gain 0.5.
+float cultmath_fbm(float3 p, int octaves, float lacunarity, float gain)
+{
+    octaves = clamp(octaves, 0, 16);
+    float amplitude = 1.0;
+    float frequency = 1.0;
+    float value = 0.0;
+    for (int i = 0; i < octaves; i++)
+    {
+        value += amplitude * cultmath_snoise(p * frequency);
+        frequency *= lacunarity;
+        amplitude *= gain;
+    }
+
+    return value;
+}
+
+float cultmath_fbm(float3 value) { return cultmath_fbm(value, 4, 2.0, 0.5); }
+
 // Ridged multifractal noise (Musgrave, Texturing and Modeling, ch. 16); see the C# math.ridged_grad
 // comment for the fold/sign derivation, the deliberate crease at n = 0, and why octaves is clamped.
 float4 cultmath_ridged_grad(float3 p, int octaves, float lacunarity, float gain)

packages/cultmath/src/CultMath/CultMath.csproj

@@ -10,7 +10,7 @@
     <PackageId>GameCult.Math</PackageId>
     <!-- MIT overall; math.Phacelle.cs and CultPhasor.cs (and the two Phacelle HLSL files) are MPL-2.0; math.Cycles.cs and CultMath.Cycles.hlsl are Apache-2.0. -->
     <PackageLicenseExpression>MIT AND MPL-2.0 AND Apache-2.0</PackageLicenseExpression>
-    <Version>0.4.1</Version>
+    <Version>0.5.0</Version>
     <Description>Clean-room C# math shaped for HLSL-style renderer code.</Description>
     <Authors>GameCult</Authors>
     <PackageReadmeFile>README.md</PackageReadmeFile>

packages/cultmath/src/CultMath/math.cs

@@ -823,6 +823,29 @@ public static partial class math
         return new float4(gradient, value);
     }
 
+    // Value-only fractional Brownian motion: the octave sum of snoise, octave i at frequency lacunarity^i and
+    // amplitude gain^i. It is fbm_grad(p, octaves, lacunarity, gain).w without the gradient work (to float
+    // rounding: snoise and snoise_grad.w order their arithmetic differently), so a loop that only wants the height
+    // (a sphere trace) does not pay for the gradient. octaves clamps to [0, 16] as fbm_grad's does. The one-argument
+    // form is the stock four octaves, lacunarity 2, gain 1/2: its range is within +-1.875 times snoise's.
+    public static float fbm(float3 p, int octaves, float lacunarity, float gain)
+    {
+        octaves = clamp(octaves, 0, 16);
+        var amplitude = 1.0f;
+        var frequency = 1.0f;
+        var value = 0.0f;
+        for (var i = 0; i < octaves; i++)
+        {
+            value += amplitude * snoise(p * frequency);
+            frequency *= lacunarity;
+            amplitude *= gain;
+        }
+
+        return value;
+    }
+
+    public static float fbm(float3 value) => fbm(value, 4, 2.0f, 0.5f);
+
     // Ridged multifractal noise (Musgrave, Texturing and Modeling, ch. 16; the operator's dune term,
     // 2026-09-25): each octave folds snoise_grad about zero, value = Sum a_i*(1 - |n_i|), gradient =
     // -Sum a_i*f_i*sign(n_i)*grad(n_i), the same per-octave frequency scaling as fbm_grad's chain

packages/cultmath/tests/CultMath.Tests/CyclesOracleTests.cs

@@ -19,11 +19,23 @@ namespace CultMath.Tests;
 /// </summary>
 public sealed class CyclesOracleTests
 {
-    // The ulp distance a function is allowed from the reference. Empty: the fixtures are the SSE4.2 kernel's results
-    // and every function equals them, power and logarithm included (glibc's powf and logf, 0 ulp from MathF on Linux).
+    // The ulp distance a function is allowed from the reference; a function not named is held to 0. The fixtures are
+    // the SSE4.2 kernel's results and almost every function equals them, power and logarithm included (glibc's powf and
+    // logf, 0 ulp from MathF on Linux). asin, acos and atan2 are the exception: the fixtures' glibc and the libm these
+    // tests run on round them one ulp apart (glsl-parity.json families 95-97 are the same three, platform families
+    // there too), so each is allowed 1 ulp, never more (TolerancesAreCappedAtOneUlpAndStayOnTheDriftingFunctions).
     // An entry needs a measured case on the reference named in it (a failing case's bits and ulp); other builds'
     // tolerances belong to the class table in tools/cycles-oracle/README.md, not here.
-    private static readonly Dictionary<string, (int Ulp, string Measured)> Tolerances = new();
+    private const int MaxToleratedUlp = 1;
+
+    private static readonly Dictionary<string, (int Ulp, string Measured)> Tolerances = new()
+    {
+        ["cycles_arcsine"] = (1, "case 3f4dd9af -> 3f6f256c, C# 3f6f256d"),
+        ["cycles_arccosine"] = (1, "case 3f027192 -> 3f84a03c, C# 3f84a03b"),
+        ["cycles_arctan2"] = (1, "case 3f000000 bdcccccd -> 3fe2541c, C# 3fe2541d"),
+    };
+
+    private static int Allowed(string function) => Tolerances.TryGetValue(function, out var tolerance) ? tolerance.Ulp : 0;
 
     private const string CSharp = "C#";
     private const string Mirror = "HLSL mirror";
@@ -120,7 +132,7 @@ public sealed class CyclesOracleTests
             var name = (string)entry!["function"]!;
             var method = Method(name);
             var clamped = (string?)entry["then"] is not null;
-            var allowed = Tolerances.TryGetValue(name, out var tolerance) ? tolerance.Ulp : 0;
+            var allowed = Allowed(name);
             var worst = 0L;
             string? worstCase = null;
             var cases = entry["cases"]!.AsArray();
@@ -158,6 +170,24 @@ public sealed class CyclesOracleTests
         Assert.True(failures.Count == 0, string.Join(Environment.NewLine, failures));
     }
 
+    [Fact]
+    public void TolerancesAreCappedAtOneUlpAndStayOnTheDriftingFunctions()
+    {
+        Assert.Equal(new[] { "cycles_arccosine", "cycles_arcsine", "cycles_arctan2" }, Tolerances.Keys.Order().ToArray());
+        Assert.All(Tolerances.Values, t => Assert.InRange(t.Ulp, 1, MaxToleratedUlp));
+        Assert.All(Tolerances.Values, t => Assert.NotEmpty(t.Measured));
+
+        // A result two ulps from the reference is past every allowance, and one ulp is within the drifting functions' only.
+        foreach (var function in Tolerances.Keys.Append("cycles_power"))
+        {
+            var want = 0.7f;
+            var twoAway = MathF.BitIncrement(MathF.BitIncrement(want));
+            Assert.Equal(2, Distance(want, twoAway));
+            Assert.True(Distance(want, twoAway) > Allowed(function), $"{function}: a 2 ulp miss would pass");
+            Assert.Equal(function != "cycles_power", Distance(want, MathF.BitIncrement(want)) <= Allowed(function));
+        }
+    }
+
     private static JsonNode RampEntry(string interpolation) =>
         Load("ramp")["functions"]!.AsArray().Single(e => e!["node"]!.ToString() == "ShaderNodeValToRGB " + interpolation)!;
 

packages/cultmath/tests/CultMath.Tests/FbmTests.cs

@@ -0,0 +1,73 @@
+using System;
+using CultMath;
+using Xunit;
+
+namespace CultMath.Tests;
+
+public sealed class FbmTests
+{
+    private static float3 Point(System.Random r) => new(r.NextSingle() * 20.0f - 10.0f, r.NextSingle() * 20.0f - 10.0f, r.NextSingle() * 20.0f - 10.0f);
+
+    [Fact]
+    public void OneOctaveIsSnoise()
+    {
+        var random = new System.Random(0xFB01);
+        for (var i = 0; i < 64; i++)
+        {
+            var p = Point(random);
+            Assert.Equal(math.snoise(p), math.fbm(p, 1, 1.0f + random.NextSingle() * 3.0f, 0.1f + random.NextSingle() * 0.8f));
+        }
+    }
+
+    [Fact]
+    public void ZeroOrNegativeOctavesSumNothing()
+    {
+        var p = new float3(0.3f, 1.7f, -2.2f);
+        Assert.Equal(0.0f, math.fbm(p, 0, 2.0f, 0.5f));
+        Assert.Equal(0.0f, math.fbm(p, -5, 2.0f, 0.5f));
+    }
+
+    [Fact]
+    public void OctavesCompoundGainAndLacunarityIndependently()
+    {
+        // gain != lacunarity and neither is 1, so applying either once, or swapping them, changes the sum.
+        const float lacunarity = 2.3f;
+        const float gain = 0.4f;
+        var random = new System.Random(0xFB02);
+        for (var i = 0; i < 64; i++)
+        {
+            var p = Point(random);
+            var expected = math.snoise(p) + gain * math.snoise(p * lacunarity) + gain * gain * math.snoise(p * (lacunarity * lacunarity));
+            Assert.Equal(expected, math.fbm(p, 3, lacunarity, gain), 5);
+        }
+    }
+
+    [Fact]
+    public void ValueIsFbmGradsValue()
+    {
+        var random = new System.Random(0xFB03);
+        for (var i = 0; i < 128; i++)
+        {
+            var p = Point(random);
+            Assert.Equal(math.fbm_grad(p, 5, 2.0f, 0.55f).w, math.fbm(p, 5, 2.0f, 0.55f), 4);
+        }
+    }
+
+    [Fact]
+    public void OctaveCountClampsToSixteenLikeFbmGrad()
+    {
+        var p = new float3(0.3f, 1.7f, -2.2f);
+        Assert.Equal(math.fbm(p, 16, 1.1f, 0.9f), math.fbm(p, 1000, 1.1f, 0.9f));
+    }
+
+    [Fact]
+    public void OneArgumentFormIsFourOctavesLacunarityTwoGainHalf()
+    {
+        var random = new System.Random(0xFB04);
+        for (var i = 0; i < 64; i++)
+        {
+            var p = Point(random);
+            Assert.Equal(math.fbm(p, 4, 2.0f, 0.5f), math.fbm(p));
+        }
+    }
+}

packages/cultmath/tests/CultMath.Tests/GlslMirrorTests.cs

@@ -904,6 +904,7 @@ static int4 clamp(int4 x, int4 a, int4 b) { if (a.x > b.x || a.y > b.y || a.z >
         // The site-array functions: a fixed-capacity array and a count, killed on the device (the lattice at rings up to 17).
         new Family($"vec4 cultmath_power_border(vec3, vec4[{SiteArrays.Capacity}], int)", "ulp-bounded", SiteArrays.PowerBorderArguments),
         new Family($"vec4 cultmath_weighted_lattice_cells(vec2, float, vec4[{SiteArrays.Capacity}], int, float, float, float, float, float, vec2, float)", "ulp-bounded", SiteArrays.LatticeArguments),
+        new Family("float cultmath_fbm(vec3, int, float, float)", "ulp-bounded", r => new object[] { Point3(r), 4, 2.0f, 0.5f }),
     }).ToArray();
 
     // A point of magnitude m, m log-uniform in [lo, hi]: one component at +-m, the other two uniform in [-m, m],
@@ -974,6 +975,7 @@ static int4 clamp(int4 x, int4 a, int4 b) { if (a.x > b.x || a.y > b.y || a.z >
         var json = new StringBuilder();
         json.Append("{\n");
         json.Append("  \"generator\": \"GlslMirrorTests.GoldenFixtureMatchesCSharp (packages/cultmath/tests/CultMath.Tests); regenerate with CULTMATH_WRITE_GLSL=1\",\n");
+        json.Append("  \"recorded_on\": \"platform families: Yggdrasil's mcr.microsoft.com/dotnet/sdk:10.0 image (Debian GNU/Linux 13 trixie, .NET 10.0.14); lavapipe device bounds: fixtures/device-bounds-lavapipe.txt (llvmpipe LLVM 20.1.2, mesa-vulkan-drivers 25.2.8-0ubuntu0.24.04.4, ubuntu:24.04 probe image)\",\n");
         json.Append($"  \"seed\": {Seed},\n");
         json.Append($"  \"points\": {Points},\n");
         json.Append("  \"encoding\": \"each case is 'arguments -> result', every scalar a float32 or 32-bit integer bit pattern in hex, vectors and structs flattened in field order\",\n");

packages/cultmath/tests/CultMath.Tests/HlslSourceCompatibilityTests.cs

@@ -47,6 +47,8 @@ public sealed class HlslSourceCompatibilityTests
         Assert.NotNull(ShaderFunction(shader, "cultmath_snoise_hessian", typeof(float3)));
         Assert.NotNull(ShaderFunction(shader, "cultmath_integral_clamp_linear", typeof(float), typeof(float), typeof(float), typeof(float), typeof(float), typeof(float)));
         Assert.NotNull(ShaderFunction(shader, "cultmath_fbm_grad", typeof(float3), typeof(int), typeof(float), typeof(float)));
+        Assert.NotNull(ShaderFunction(shader, "cultmath_fbm", typeof(float3), typeof(int), typeof(float), typeof(float)));
+        Assert.NotNull(ShaderFunction(shader, "cultmath_fbm", typeof(float3)));
         Assert.NotNull(ShaderFunction(shader, "cultmath_ridged_grad", typeof(float3), typeof(int), typeof(float), typeof(float)));
         Assert.NotNull(ShaderFunction(shader, "cultmath_phacelle", typeof(float3), typeof(float3), typeof(float), typeof(float)));
         Assert.NotNull(ShaderFunction(shader, "cultmath_iv_snoise_ball", typeof(float3), typeof(float)));
@@ -205,7 +207,7 @@ public sealed class HlslSourceCompatibilityTests
 
         Assert.True(mismatches.Count == 0, $"{mismatches.Count} mismatches:{Environment.NewLine}{string.Join(Environment.NewLine, mismatches.Take(12))}");
         // The three site-array functions are compared by SiteArrayMirrorsMatchCSharp, which draws their counts and arrays.
-        Assert.Equal(140, compared.Count);
+        Assert.Equal(141, compared.Count);
     }
 
     /// <summary>

packages/cultmath/tests/CultMath.Tests/PhacelleRowOrderTests.cs

@@ -0,0 +1,91 @@
+using System;
+using System.Linq;
+using CultMath;
+using Xunit;
+
+namespace CultMath.Tests;
+
+/// <summary>
+/// A ring-buffer terrain (Voxel Space) fills height rows in whatever order the camera uncovers them, so a
+/// Phacelle row must be a pure function of world x, z and the seed: the same row, bit for bit, whether the
+/// rows around it were generated forward, backward or shuffled. C# phacelle mirrors cultmath_phacelle in
+/// shaders/CultMath.Phacelle.glsl; GlslMirrorTests pins the two together, and this pins that neither keeps
+/// state between calls.
+/// </summary>
+public sealed class PhacelleRowOrderTests
+{
+    private const int Rows = 24;
+    private const int Columns = 48;
+    private const int Seed = 7919;
+
+    // One height sample: world (x, z) and the seed alone choose the point, the stripe direction and the phase.
+    private static int[] Sample(int worldX, int worldZ, int seed)
+    {
+        var p = new float3(worldX * 0.173f, (seed & 0xff) * 0.37f, worldZ * 0.173f);
+        var angle = (seed >> 8) * 0.61f;
+        var side = new float3(math.cos(angle), 0.0f, math.sin(angle)) * (math.TAU * 0.9f);
+        var phasor = math.phacelle(p, side, (seed & 0xf) / 16.0f, 0.5f);
+        return new[]
+        {
+            Bits(phasor.cosine.x), Bits(phasor.cosine.y), Bits(phasor.cosine.z), Bits(phasor.cosine.w),
+            Bits(phasor.sine.x), Bits(phasor.sine.y), Bits(phasor.sine.z), Bits(phasor.sine.w),
+        };
+    }
+
+    private static int Bits(float value) => BitConverter.SingleToInt32Bits(value);
+
+    private static int[][] Row(int worldZ, int seed) =>
+        Enumerable.Range(-Columns / 2, Columns).Select(x => Sample(x, worldZ, seed)).ToArray();
+
+    private static int[][][] Generate(int[] order, int seed)
+    {
+        var rows = new int[Rows][][];
+        foreach (var z in order) rows[z] = Row(z - Rows / 2, seed);
+        return rows;
+    }
+
+    private static void AssertSameRows(int[][][] expected, int[][][] actual)
+    {
+        for (var z = 0; z < Rows; z++)
+        for (var x = 0; x < Columns; x++)
+            Assert.True(expected[z][x].SequenceEqual(actual[z][x]), $"row {z} column {x} differs bit for bit");
+    }
+
+    [Fact]
+    public void RowsAreBitIdenticalForwardBackwardAndShuffled()
+    {
+        var forward = Enumerable.Range(0, Rows).ToArray();
+        var backward = forward.Reverse().ToArray();
+        var shuffled = (int[])forward.Clone();
+        var random = new System.Random(20261104);
+        for (var i = shuffled.Length - 1; i > 0; i--)
+        {
+            var j = random.Next(i + 1);
+            (shuffled[i], shuffled[j]) = (shuffled[j], shuffled[i]);
+        }
+
+        Assert.False(shuffled.SequenceEqual(forward) || shuffled.SequenceEqual(backward));
+        var reference = Generate(forward, Seed);
+        AssertSameRows(reference, Generate(backward, Seed));
+        AssertSameRows(reference, Generate(shuffled, Seed));
+    }
+
+    [Fact]
+    public void ARowIsTheSameWhenRegeneratedAfterAnyOtherSeedAndRow()
+    {
+        var first = Row(5, Seed);
+        _ = Row(-3, Seed + 1);
+        _ = Row(5, Seed + 1);
+        var again = Row(5, Seed);
+        for (var x = 0; x < Columns; x++) Assert.True(first[x].SequenceEqual(again[x]));
+    }
+
+    // Guards the test itself: a different seed or a different row must change the bits, or the equalities
+    // above would hold for a function that ignores its inputs.
+    [Fact]
+    public void RowsDependOnSeedAndWorldRow()
+    {
+        Assert.False(Row(5, Seed).SelectMany(s => s).SequenceEqual(Row(5, Seed + 1).SelectMany(s => s)));
+        Assert.False(Row(5, Seed).SelectMany(s => s).SequenceEqual(Row(6, Seed).SelectMany(s => s)));
+    }
+}

packages/cultmath/tests/CultMath.Tests/PhacelleTests.cs

@@ -337,4 +337,33 @@ public sealed class PhacelleTests
         Assert.Equal(BitConverter.SingleToInt32Bits(expected.z), BitConverter.SingleToInt32Bits(actual.z));
         Assert.Equal(BitConverter.SingleToInt32Bits(expected.w), BitConverter.SingleToInt32Bits(actual.w));
     }
+
+    // The Lipschitz envelope of the (cosine, sine) field in p, per docs/design.md ("Lipschitz bound"): the largest
+    // singular value of its 2x3 Jacobian never exceeds max(10, 1.25 |side|) / (1 - normalization), for normalization
+    // in [0, 0.9] and |side| in [0.25, 25]. tools/phacelle-lipschitz measures it by sampling and hill-climbing; this
+    // pins that no ordinary sample passes it (the climbed maximum is at most 0.88 of the envelope).
+    [Theory]
+    [InlineData(0.0f)]
+    [InlineData(0.5f)]
+    [InlineData(0.75f)]
+    [InlineData(0.9f)]
+    public void GradientNormStaysUnderTheDocumentedLipschitzEnvelope(float normalization)
+    {
+        var random = new System.Random(0x11B5);
+        foreach (var sideLength in new[] { 0.25f, 1.0f, 1.5f, 4.0f, 12.5f, 25.0f })
+        {
+            var envelope = Math.Max(10.0, 1.25 * sideLength) / (1.0 - normalization);
+            for (var i = 0; i < 20000; i++)
+            {
+                var p = RandomPoint(random, 32.0f);
+                var side = math.normalize(RandomSide(random)) * sideLength;
+                var phasor = math.phacelle(p, side, random.NextSingle(), normalization);
+                var a = (double)math.dot(phasor.cosine.xyz, phasor.cosine.xyz);
+                var d = (double)math.dot(phasor.sine.xyz, phasor.sine.xyz);
+                var b = (double)math.dot(phasor.cosine.xyz, phasor.sine.xyz);
+                var norm = Math.Sqrt((a + d) / 2.0 + Math.Sqrt(Math.Max(0.0, (a + d) * (a + d) / 4.0 - (a * d - b * b))));
+                Assert.True(norm <= envelope, $"|J| {norm} passes the envelope {envelope} at p {p}, side {side}, normalization {normalization}");
+            }
+        }
+    }
 }