Merge pull request 'Docs: cultcache-ts publishing is off; tag runs use the tagged workflow' (#32) from libby/publish-docs-cleanup into main

The header comment, semver-policy and F16 of the content map still listed cultcache-ts-v*
as a trigger. They now say publishing is deliberately off and that a tag run uses the
workflow at the tagged commit (cultcache-ts-v0.15.0 sits on 7d292085, before the guard).
semver-policy gains a "Before pushing a tag" note. The guard's comment moves above `tags:`:
inside the list it broke the three `workflow:` tests of check-changelog-semver.test.mjs,
which read `tags:` followed directly by its items.

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

.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,10 @@ 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).
 
 ## Live Invariants
 
@@ -122,6 +124,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"]
     },
     "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\".", "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/error-vectors.json

@@ -0,0 +1,150 @@
+{
+  "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
+        }
+      }
+    }
+  ]
+}

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

@@ -31,6 +31,79 @@ copy of the solver and the warm/cold sweep, `suite` a scratch copy of `packages/
    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
 

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` 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` |
 | 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 |

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

@@ -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:
 
@@ -352,10 +352,21 @@ 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. Read `.github/workflows/publish-packages.yml`
+(and any workflow that triggers on tags) at the tagged sha before pushing any tag:
+a guard merged after that commit does not protect a tag that points before it.
+`cultcache-ts-v0.15.0` sits on `7d292085`, which predates the guard, and its push
+started a publish run (it failed; nothing reached npm).
+
 ### 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,7 +1184,7 @@
     },
     "packages/cultcache-ts": {
       "name": "@gamecult/cultcache-ts",
-      "version": "0.14.2",
+      "version": "0.15.0",
       "license": "MIT",
       "dependencies": {
         "@msgpack/msgpack": "^3.1.3",
@@ -1200,15 +1200,16 @@
       }
     },
     "packages/cultmesh-browser": {
+      "name": "@gamecult/cultmesh-browser",
       "version": "0.4.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.3.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",
-        "cultmesh-ts": "^0.2.0",
         "typescript": "^5.9.0"
       },
       "engines": {
@@ -1216,11 +1217,12 @@
       }
     },
     "packages/cultmesh-ts": {
+      "name": "@gamecult/cultmesh-ts",
       "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.3.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
+        "@gamecult/cultnet-ts": "^0.3.0",
         "koffi": "3.3.0"
       },
       "devDependencies": {
@@ -1233,10 +1235,11 @@
       }
     },
     "packages/cultnet-ts": {
+      "name": "@gamecult/cultnet-ts",
       "version": "0.3.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.1",
+        "@gamecult/cultcache-ts": "^0.15.0",
         "@msgpack/msgpack": "^3.1.3",
         "ajv": "^8.17.1"
       },

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,6 +26,38 @@ 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
@@ -37,6 +69,7 @@ fn main() -> Result<()> {
     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}")),
     }

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,26 @@
 All notable changes to `@gamecult/cultcache-ts` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.14.2]
+## [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
@@ -15,8 +32,12 @@ All notable changes to `@gamecult/cultcache-ts` are recorded here, following
   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.
@@ -24,11 +45,5 @@ All notable changes to `@gamecult/cultcache-ts` are recorded here, following
   under the lock.
 
 ### Dependencies
+
 - `koffi` 3.3.0, loaded only on the first write.
-
-## [0.14.1]
-
-### Added
-- `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.

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
 

packages/cultcache-ts/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@gamecult/cultcache-ts",
-  "version": "0.14.2",
+  "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"
       ]
     }
   },

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,13 +1,13 @@
-import { lstat, mkdir, readFile } 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 { commitStoreFile, withStoreWriteLock } from "./store-file";
-import { STORE_FORMAT_VERSION, isV1Snapshot, requireV1RecordSlots } from "./store-format";
+import { STORE_FORMAT_VERSION, SchemaConflictError, type StoreFormat, StoreUnreadableError, isStoreSnapshot, refuseUnreadStoreBytes, requireStoreSlots, requireV1RecordSlots } from "./store-format";
 import type {
   CacheBackingStore,
   CultCacheEnvelope,
@@ -39,110 +39,89 @@ 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[]> {
-    const { envelopes, healLegacy } = await this.#readDisk();
-    if (healLegacy) {
+    // 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 = await this.#readDisk();
-        if (again.healLegacy) {
-          await this.#writeAll(again.envelopes);
+        const again = this.#readDisk();
+        this.#format = again.format;
+        if (again.repairedLegacyPayload) {
+          await this.#writeAll([], again.envelopes);
         }
       });
     }
 
-    return envelopes;
-  }
-
-  async #readDisk(): Promise<{ envelopes: CultCacheEnvelope[]; healLegacy: boolean }> {
-    // 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 { envelopes: [], healLegacy: false };
-    }
-
-    const decoded = decode(data);
-    const snapshot = decodeSnapshot(decoded);
-    if (snapshot) {
-      const envelopes = 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}".`);
-        }
-
-        return {
-          key: record.key,
-          type: catalogEntry.schemaName,
-          schemaId: record.schemaId,
-          catalogEntry,
-          payload: documentPayloadFromBytes(record.payload),
-          storedAt: record.storedAt,
-        };
-      });
-      return { envelopes, healLegacy: false };
-    }
-
-    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),
-      }));
-
-      return { envelopes: parsed, healLegacy: repairedLegacyPayload };
-    }
-
-    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.#readDisk()).envelopes;
+      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.#readDisk()).envelopes;
+      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;
 
@@ -161,29 +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 });
 
-    await commitStoreFile(this.filePath, encode(encodeSnapshot(entries)));
+    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;
@@ -192,7 +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" });
+  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 = {
@@ -203,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) => [
@@ -220,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 {
@@ -279,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-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/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}");
+            }
+        }
+    }
 }

packages/cultmath/tests/CultMath.Tests/fixtures/device-bounds-lavapipe.txt

@@ -96,9 +96,9 @@ lavapipe-glsl	91	vec3 cultmath_cycles_mix_val(float, vec3, vec3)	ulp-bounded	256
 lavapipe-glsl	92	vec3 cultmath_cycles_mix_color(float, vec3, vec3)	ulp-bounded	256	0	0	00067b1567bcd6c07a81fa5002f145dfca22437a3f3df5389b2665334d14909b
 lavapipe-glsl	93	vec3 cultmath_cycles_mix_soft(float, vec3, vec3)	ulp-bounded	157	1.9750388068880254	0	ed7c5508ca0543cc20a5f0c5624e75e3ca2a2d6044d481816eeda2edc50c0592
 lavapipe-glsl	94	vec3 cultmath_cycles_mix_linear(float, vec3, vec3)	ulp-bounded	256	0	0	672435cc30bcbbb253cce7316ee0712b1a18f06924bc89cea2d3388dd164a15d
-lavapipe-glsl	95	float cultmath_cycles_arcsine(float)	ulp-bounded, platform asin	154	2734.286809678319	0	f28f3ed0a53ffeebdfa84865d2d3d41590e6b46fc1578d40e1215e2a9e1af585
+lavapipe-glsl	95	float cultmath_cycles_arcsine(float)	ulp-bounded, platform asin	155	2734.286809678319	0	f28f3ed0a53ffeebdfa84865d2d3d41590e6b46fc1578d40e1215e2a9e1af585
 lavapipe-glsl	96	float cultmath_cycles_arccosine(float)	ulp-bounded, platform acos	79	1046.8674409774287	0	22a2c38ab5a232cdbb33cf0c133362581a398f64a4d0d5d6dd89dc5af06bd890
-lavapipe-glsl	97	float cultmath_cycles_arctan2(float, float)	ulp-bounded, platform atan	6	25.5	0	2c60447d80186f6dc9726f19c09fa96ec3f66d8f5688968da533d9195ea463c4
+lavapipe-glsl	97	float cultmath_cycles_arctan2(float, float)	ulp-bounded, platform atan	7	25.5	0	2c60447d80186f6dc9726f19c09fa96ec3f66d8f5688968da533d9195ea463c4
 lavapipe-glsl	98	mat3 cultmath_snoise_hessian(vec3)	ulp-bounded	30	1358.4375	0	62bbafb8420ed5aaa0ce11d1470ca98945e690b186c33a1e7cf4d71478396465
 lavapipe-glsl	99	mat3 cultmath_snoise_hessian(vec3)	ulp-bounded, on the simplex tie set	110	1317.4754224467295	0	0efd9b3a637b46033ed0351f64de274db4d9ce05bb83dd1ce57afb3ceaea26bc
 lavapipe-glsl	100	float cultmath_integral_clamp_linear(float, float, float, float, float, float)	ulp-bounded	256	0	0	84bf9c9a2126b3114a692507cc54f58d313afc33de8a1cac83969cc508433cbe
@@ -126,6 +126,7 @@ lavapipe-glsl	121	float cultmath_lattice_distance(vec2, vec2, float, vec2, float
 lavapipe-glsl	122	float cultmath_lattice_smooth_step(float, float, float, float)	ulp-bounded	256	0	0	6cbeddde536b12e83873f2e5ac60d16bef22049d2a7dea61af0ff1e0d5b84740
 lavapipe-glsl	123	vec4 cultmath_power_border(vec3, vec4[128], int)	ulp-bounded	188	65.72121683891783	0	8427c2b99109a4f59ff745fdb87f261deb1cbae34ce99bc1ae05ebb7f9963b4d
 lavapipe-glsl	124	vec4 cultmath_weighted_lattice_cells(vec2, float, vec4[128], int, float, float, float, float, float, vec2, float)	ulp-bounded	179	3	0	fd3b58c4e2ba8a7bf801a1e6cdff82468abcb368442bc98b2583fda9d2e6f823
+lavapipe-glsl	125	float cultmath_fbm(vec3, int, float, float)	ulp-bounded	43	190.375	0	8f852b55293bd75a4e2e64cd1d1f5083605c2ba2d0877cdf4e8e507c72890135
 lavapipe-hlsl	0	float cultmath_snoise(vec3)	ulp-bounded	94	122.6875	0	5d41c14241a13124f2e1b49f230f5df0c48d0d69fb1be9ef2f33dc1702bf0b0a
 lavapipe-hlsl	1	float cultmath_snoise(vec2)	ulp-bounded	204	1	0	81d9c62726afdccbbe4ffef173b5c92731eb6bf5927b3979d653e50dbd5d4064
 lavapipe-hlsl	2	vec4 cultmath_snoise_grad(vec3)	ulp-bounded	71	617.5	0	f7e9ed1707cdb015efaba0e0150193309da0d4c125349518f8b7c60a17b25790
@@ -221,9 +222,9 @@ lavapipe-hlsl	91	vec3 cultmath_cycles_mix_val(float, vec3, vec3)	ulp-bounded	256
 lavapipe-hlsl	92	vec3 cultmath_cycles_mix_color(float, vec3, vec3)	ulp-bounded	256	0	0	00067b1567bcd6c07a81fa5002f145dfca22437a3f3df5389b2665334d14909b
 lavapipe-hlsl	93	vec3 cultmath_cycles_mix_soft(float, vec3, vec3)	ulp-bounded	157	1.9750388068880254	0	ed7c5508ca0543cc20a5f0c5624e75e3ca2a2d6044d481816eeda2edc50c0592
 lavapipe-hlsl	94	vec3 cultmath_cycles_mix_linear(float, vec3, vec3)	ulp-bounded	256	0	0	672435cc30bcbbb253cce7316ee0712b1a18f06924bc89cea2d3388dd164a15d
-lavapipe-hlsl	95	float cultmath_cycles_arcsine(float)	ulp-bounded, platform asin	154	2734.286809678319	0	f28f3ed0a53ffeebdfa84865d2d3d41590e6b46fc1578d40e1215e2a9e1af585
+lavapipe-hlsl	95	float cultmath_cycles_arcsine(float)	ulp-bounded, platform asin	155	2734.286809678319	0	f28f3ed0a53ffeebdfa84865d2d3d41590e6b46fc1578d40e1215e2a9e1af585
 lavapipe-hlsl	96	float cultmath_cycles_arccosine(float)	ulp-bounded, platform acos	79	1046.8674409774287	0	22a2c38ab5a232cdbb33cf0c133362581a398f64a4d0d5d6dd89dc5af06bd890
-lavapipe-hlsl	97	float cultmath_cycles_arctan2(float, float)	ulp-bounded, platform atan	6	25.5	0	2c60447d80186f6dc9726f19c09fa96ec3f66d8f5688968da533d9195ea463c4
+lavapipe-hlsl	97	float cultmath_cycles_arctan2(float, float)	ulp-bounded, platform atan	7	25.5	0	2c60447d80186f6dc9726f19c09fa96ec3f66d8f5688968da533d9195ea463c4
 lavapipe-hlsl	98	mat3 cultmath_snoise_hessian(vec3)	ulp-bounded	33	2377.8799856935966	0	a64853839f394cc7c367ba5e107caa8bb396f07cf202263aa917095dd1c939f7
 lavapipe-hlsl	99	mat3 cultmath_snoise_hessian(vec3)	ulp-bounded, on the simplex tie set	132	1317.4754224467295	0	9066a49e50731881583ffca16c949171bb61578a1dfd497c54dafe773ab49488
 lavapipe-hlsl	100	float cultmath_integral_clamp_linear(float, float, float, float, float, float)	ulp-bounded	256	0	0	84bf9c9a2126b3114a692507cc54f58d313afc33de8a1cac83969cc508433cbe
@@ -251,3 +252,4 @@ lavapipe-hlsl	121	float cultmath_lattice_distance(vec2, vec2, float, vec2, float
 lavapipe-hlsl	122	float cultmath_lattice_smooth_step(float, float, float, float)	ulp-bounded	256	0	0	6cbeddde536b12e83873f2e5ac60d16bef22049d2a7dea61af0ff1e0d5b84740
 lavapipe-hlsl	123	vec4 cultmath_power_border(vec3, vec4[128], int)	ulp-bounded	188	65.72121683891783	0	8427c2b99109a4f59ff745fdb87f261deb1cbae34ce99bc1ae05ebb7f9963b4d
 lavapipe-hlsl	124	vec4 cultmath_weighted_lattice_cells(vec2, float, vec4[128], int, float, float, float, float, float, vec2, float)	ulp-bounded	179	3	0	fd3b58c4e2ba8a7bf801a1e6cdff82468abcb368442bc98b2583fda9d2e6f823
+lavapipe-hlsl	125	float cultmath_fbm(vec3, int, float, float)	ulp-bounded	49	190.375	0	cd02f850f1d01ff77a3cb1c49af2bb49e51bb18c395936703cb37b7729ad2c88

packages/cultmath/tests/CultMath.Tests/fixtures/glsl-parity.json

@@ -1,5 +1,6 @@
 {
   "generator": "GlslMirrorTests.GoldenFixtureMatchesCSharp (packages/cultmath/tests/CultMath.Tests); regenerate with CULTMATH_WRITE_GLSL=1",
+  "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)",
   "seed": 20261002,
   "points": 256,
   "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",
@@ -6820,7 +6821,7 @@
     {
       "glsl": "vec2 cultmath_iv_exp(vec2)",
       "tolerance": "ulp-bounded, platform exp",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "41202b2a 4120314e -> 46ade79e 46ae2a6b",
         "c0d1a016 bfb9db96 -> 3abb4cbc 3e6fb77f",
@@ -7083,7 +7084,7 @@
     {
       "glsl": "CultPhasor cultmath_phacelle(vec3, vec3, float, float)",
       "tolerance": "ulp-bounded, platform exp, sin, cos; across platforms |diff| <= 2^-20 max(|v|, 1); on a device |diff| <= 2^-18 max(|v|, 1)",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "c01d8630 41b2cd8c 41ea274c bfa19894 40aeb6ce 40918978 3e9be843 3f000000 -> bf74d9fb 3fb71956 bf35fe4e 3f21280a c01277e2 403b5fe4 40464bbd bd5b4455",
         "c2234cf7 4237b112 419ae0c0 c0acbcd4 bf60f9a0 bfeb2b08 3ebf0a10 3f000000 -> c0d0048f 3f228da3 bfc85f60 3edaf41b c0171c80 be137f8c be1c92a3 bf5747bf",
@@ -12591,7 +12592,7 @@
     {
       "glsl": "float cultmath_cycles_power(float, float)",
       "tolerance": "ulp-bounded, platform pow",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "bfb8bc1c 00000000 -> 3f800000",
         "3f7fc090 3fa15ed0 -> 3f7fb009",
@@ -12854,7 +12855,7 @@
     {
       "glsl": "float cultmath_cycles_logarithm(float, float)",
       "tolerance": "ulp-bounded, platform log",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "416175a4 418f2e6d -> 3f6ac789",
         "40d2d3ad 416ecd13 -> 3f328da7",
@@ -24907,7 +24908,7 @@
     {
       "glsl": "float cultmath_cycles_arcsine(float)",
       "tolerance": "ulp-bounded, platform asin",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "3f74439c -> 3fa22776",
         "beaa06dc -> bead5166",
@@ -24919,27 +24920,27 @@
         "bf44c25b -> bf606b2a",
         "be9326d8 -> be9541be",
         "bf047a79 -> bf0b3e4e",
-        "3f6fb444 -> 3f9b2514",
+        "3f6fb444 -> 3f9b2513",
         "bec3bc1c -> bec8d8b0",
         "3ed94bc8 -> 3ee069a8",
         "be732cb0 -> be75852c",
         "bf525772 -> bf76dbfc",
         "3f5f4508 -> 3f87a01e",
-        "3f5243a0 -> 3f76b93a",
+        "3f5243a0 -> 3f76b939",
         "3f6f8480 -> 3f9ae13d",
         "bf43af08 -> bf5ebe7a",
         "3fb52362 -> 3fc90fdb",
         "3eae8380 -> 3eb2152a",
         "bf3ff8fb -> bf590ffc",
         "3f7bb06c -> 3fb189e5",
-        "3dee93e0 -> 3def1ede",
+        "3dee93e0 -> 3def1edd",
         "bfb0b96e -> bfc90fdb",
         "bf454824 -> bf613cb1",
         "3f23fb40 -> 3f31f9c7",
         "be9b0000 -> be9d788d",
         "3fb7c110 -> 3fc90fdb",
         "bf0c30e4 -> bf145b51",
-        "3e855c0c -> 3e86ea5c",
+        "3e855c0c -> 3e86ea5d",
         "bf0e2123 -> bf16ae2c",
         "3f72c708 -> 3f9fbe32",
         "3f98afd8 -> 3fc90fdb",
@@ -24970,7 +24971,7 @@
         "3f81d10a -> 3fc90fdb",
         "bf033714 -> bf09c506",
         "3fa3a04a -> 3fc90fdb",
-        "3f1281b8 -> 3f1bfaf2",
+        "3f1281b8 -> 3f1bfaf3",
         "bf34447a -> bf480038",
         "bf9eb144 -> bfc90fdb",
         "3f38d780 -> 3f4e86c5",
@@ -25014,7 +25015,7 @@
         "3f039538 -> 3f0a32b8",
         "3f4cd500 -> 3f6d70e3",
         "3ee655e4 -> 3eeee961",
-        "3ef23d20 -> 3efc5474",
+        "3ef23d20 -> 3efc5473",
         "3e0c9370 -> 3e0d0572",
         "3f9f079c -> 3fc90fdb",
         "3e4b1770 -> 3e4c7278",
@@ -25038,7 +25039,7 @@
         "3f982f94 -> 3fc90fdb",
         "3ef183b4 -> 3efb8213",
         "bed4d500 -> bedb7e63",
-        "bf49041d -> bf672e44",
+        "bf49041d -> bf672e45",
         "bf986f2a -> bfc90fdb",
         "3eeeeb04 -> 3ef89167",
         "bf05421c -> bf0c27dd",
@@ -25072,7 +25073,7 @@
         "3f48bf60 -> 3f66bf61",
         "3f953182 -> 3fc90fdb",
         "3e21e6d0 -> 3e229577",
-        "bf043606 -> bf0aee58",
+        "bf043606 -> bf0aee57",
         "3d94f740 -> 3d9518f5",
         "3c15e400 -> 3c15e489",
         "bfb51e92 -> bfc90fdb",
@@ -25103,7 +25104,7 @@
         "3f4133b0 -> 3f5aedab",
         "3f25a7cc -> 3f3429d9",
         "3f4f5e44 -> 3f71b78b",
-        "3f795244 -> 3fabc288",
+        "3f795244 -> 3fabc287",
         "3de214a0 -> 3de28ad3",
         "3e8fe798 -> 3e91deba",
         "bf9af793 -> bfc90fdb",
@@ -25127,7 +25128,7 @@
         "3ecad4fc -> 3ed08d21",
         "3e05a058 -> 3e06022f",
         "beb65270 -> beba69cf",
-        "3f5058c0 -> 3f7364a8",
+        "3f5058c0 -> 3f7364a7",
         "3fa6360c -> 3fc90fdb",
         "3f466ed4 -> 3f630d19",
         "3f700570 -> 3f9b993a",
@@ -25144,12 +25145,12 @@
         "beaaf660 -> beae4f6a",
         "3f92651c -> 3fc90fdb",
         "3f8dddfa -> 3fc90fdb",
-        "3f2ed97c -> 3f407a92",
+        "3f2ed97c -> 3f407a93",
         "be5e0a78 -> be5fd19b",
         "bf794a5d -> bfabb123",
         "bf166554 -> bf20c10e",
         "3ec7db68 -> 3ecd50d0",
-        "3f0f3a38 -> 3f1800b6",
+        "3f0f3a38 -> 3f1800b5",
         "bf9d2433 -> bfc90fdb",
         "be1b6e70 -> be1c08d6",
         "3f8cf9f4 -> 3fc90fdb",
@@ -25170,7 +25171,7 @@
     {
       "glsl": "float cultmath_cycles_arccosine(float)",
       "tolerance": "ulp-bounded, platform acos",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "3da419e0 -> 3fbecb6b",
         "bccc7dc0 -> 3fcc41e7",
@@ -25185,7 +25186,7 @@
         "3f99f728 -> 00000000",
         "3efe6a30 -> 3f867f99",
         "bf8e3141 -> 40490fdb",
-        "be1ccb60 -> 3fdcbd18",
+        "be1ccb60 -> 3fdcbd17",
         "bf6312e3 -> 402a57f6",
         "beca9b18 -> 3ffd2360",
         "bfa261f2 -> 40490fdb",
@@ -25221,7 +25222,7 @@
         "3e8561b8 -> 3fa753cc",
         "bf888ac6 -> 40490fdb",
         "3fbb7d54 -> 00000000",
-        "3ec05018 -> 3f97c656",
+        "3ec05018 -> 3f97c657",
         "bf8c0f8c -> 40490fdb",
         "bf72b2f0 -> 40345736",
         "3f244db8 -> 3f5fba77",
@@ -25250,7 +25251,7 @@
         "3f8f186c -> 00000000",
         "3f30b1e8 -> 3f4f1b53",
         "3d953310 -> 3fbfba8c",
-        "bde0dee0 -> 3fd7250e",
+        "bde0dee0 -> 3fd7250d",
         "3f7b8300 -> 3e4007f6",
         "3f35601c -> 3f488ecf",
         "bf9a050a -> 40490fdb",
@@ -25272,7 +25273,7 @@
         "bfb4c70e -> 40490fdb",
         "3e93057c -> 3fa3c820",
         "3f2b8624 -> 3f56293a",
-        "bf51e010 -> 40220aae",
+        "bf51e010 -> 40220aaf",
         "bf8aa06c -> 40490fdb",
         "3f9839c8 -> 00000000",
         "3f28eed8 -> 3f59a156",
@@ -25297,7 +25298,7 @@
         "3e8aea00 -> 3fa5e480",
         "3ed35888 -> 3f9298c3",
         "3f567510 -> 3f13e3ce",
-        "3e9761c8 -> 3fa2a464",
+        "3e9761c8 -> 3fa2a463",
         "3fbc3ca0 -> 00000000",
         "bf5814bd -> 4024d6ee",
         "3f807f68 -> 00000000",
@@ -25306,7 +25307,7 @@
         "3f1a4008 -> 3f6c92ef",
         "3fa491d4 -> 00000000",
         "3f385e00 -> 3f44484f",
-        "3e9ac620 -> 3fa1c0e6",
+        "3e9ac620 -> 3fa1c0e5",
         "3e9541ec -> 3fa3329f",
         "bf647da0 -> 402b1eac",
         "3dc1c080 -> 3fbcef2e",
@@ -25351,7 +25352,7 @@
         "beab7798 -> 3ff4c5fc",
         "3f0df694 -> 3f7ba4b1",
         "3f94dda6 -> 00000000",
-        "bf5c7d84 -> 4026f34c",
+        "bf5c7d84 -> 4026f34d",
         "3f9296ba -> 00000000",
         "bfbada1e -> 40490fdb",
         "3f8cf40a -> 00000000",
@@ -25364,7 +25365,7 @@
         "bf6b7605 -> 402f4022",
         "bfad549a -> 40490fdb",
         "3faa5d8c -> 00000000",
-        "3e8b7c88 -> 3fa5be6e",
+        "3e8b7c88 -> 3fa5be6f",
         "3f3fa580 -> 3f398dc6",
         "bf61690a -> 4029746e",
         "bf73a264 -> 403516b7",
@@ -25427,13 +25428,13 @@
         "3f930316 -> 00000000",
         "bf6bfdd5 -> 402f9730",
         "3fa53312 -> 00000000",
-        "bf1a0e9a -> 400ddba4"
+        "bf1a0e9a -> 400ddba5"
       ]
     },
     {
       "glsl": "float cultmath_cycles_arctan2(float, float)",
       "tolerance": "ulp-bounded, platform atan",
-      "platform": "Ubuntu 24.04.5 LTS; .NET 10.0.12",
+      "platform": "Debian GNU/Linux 13 (trixie); .NET 10.0.14",
       "cases": [
         "c08cbc16 c1549681 -> c0349aac",
         "418c8108 41948858 -> 3f41f3ee",
@@ -25442,7 +25443,7 @@
         "c1853a3e 4183660c -> bf4ad4c8",
         "40cc3750 c18864ad -> 4032239a",
         "c1841fce 414eb7b4 -> bf682df1",
-        "3f7f11c0 41915dcc -> 3d605f59",
+        "3f7f11c0 41915dcc -> 3d605f58",
         "c1190690 40822148 -> bf959a14",
         "41235546 414a8e7c -> 3f2db91b",
         "c173027e 4157ae48 -> bf584be7",
@@ -25451,12 +25452,12 @@
         "41504298 c1432d3c -> 4014b8bf",
         "41976732 4165afb0 -> 3f6bff17",
         "c12faa83 c19c5692 -> c0284d67",
-        "c0aa038c c0cb2194 -> c01c7634",
+        "c0aa038c c0cb2194 -> c01c7633",
         "c0df2a78 c0a67120 -> c00d8b25",
         "4144767c c11a39a5 -> 400f2006",
         "c00c8aa0 4194be56 -> bdf0c4af",
         "3f876310 c1937378 -> 404564aa",
-        "41636814 c1172a84 -> 400a13e2",
+        "41636814 c1172a84 -> 400a13e1",
         "3f81e2e0 bd4f6800 -> 3fcf71a7",
         "41309010 c08f8f1c -> 3ffa7c90",
         "40982a9c 3f904760 -> 3fab4541",
@@ -25467,23 +25468,23 @@
         "4192314a 4086f2c0 -> 3fac080a",
         "411b37ca c171da02 -> 40248b70",
         "c1664f18 c130242c -> c00e512f",
-        "40eced38 40bd9198 -> 3f655f42",
-        "4104386c 411d5130 -> 3f32ed70",
+        "40eced38 40bd9198 -> 3f655f43",
+        "4104386c 411d5130 -> 3f32ed71",
         "bdd98800 c15cd654 -> c04891c6",
         "c161bae2 c19f6675 -> c021a16c",
         "c15bccb4 4139d89a -> bf5e709e",
         "c1065de6 c1860dc7 -> c02b5428",
         "419a2318 416c82f8 -> 3f6a973f",
-        "bf911740 3eafb040 -> bfa36fa4",
+        "bf911740 3eafb040 -> bfa36fa5",
         "41961b7c c01fd768 -> 3fd9fffb",
         "4042f5d8 c00cea20 -> 400c95f1",
-        "c12f053d 418e307c -> bf0d3c4a",
+        "c12f053d 418e307c -> bf0d3c4b",
         "403d4400 c11dc866 -> 40366a62",
         "c15831c7 412e7716 -> bf644dcc",
         "c0d29330 41698de0 -> bed8d810",
         "c0fd3872 415963f8 -> bf0702af",
         "c131bb1f c074e670 -> bff386a5",
-        "417f6828 40a71880 -> 3fa09868",
+        "417f6828 40a71880 -> 3fa09869",
         "40497b80 41717390 -> 3e529a28",
         "413af82e c196608f -> 40257713",
         "4179eb80 bfb8a2f0 -> 3fd4d959",
@@ -25492,8 +25493,8 @@
         "414f2488 c180a1ba -> 401dad4f",
         "4036b5f0 c15671f1 -> 403ba162",
         "bf97a3d0 c0046bb8 -> c027c818",
-        "40ae84d8 c0f9a4b6 -> 402203ec",
-        "3feb4440 40f9d6e0 -> 3e6cc1c5",
+        "40ae84d8 c0f9a4b6 -> 402203eb",
+        "3feb4440 40f9d6e0 -> 3e6cc1c6",
         "419f7088 411a15a2 -> 3f8f723b",
         "c188441a bfeff970 -> bfd71812",
         "40560bd0 410fd5de -> 3eb65b86",
@@ -25508,10 +25509,10 @@
         "414c9fc4 418893dc -> 3f249745",
         "c033b3b8 c18b7729 -> c03ed777",
         "c13f3667 c152d7a7 -> c019eb30",
-        "c086fb50 41627eb4 -> be9446ba",
+        "c086fb50 41627eb4 -> be9446b9",
         "c13dde75 41858b9e -> bf1e348f",
         "41655ddc c13d8347 -> 4010b9bb",
-        "40a95660 41584940 -> 3ebf0aa4",
+        "40a95660 41584940 -> 3ebf0aa3",
         "4141fbc4 c0ce1146 -> 4003c77a",
         "c0091050 c155ea5c -> c03ee580",
         "40b8f0c0 c18079b9 -> 4032f416",
@@ -25524,17 +25525,17 @@
         "40a7d388 c07a5f68 -> 400d8c45",
         "4186baee c161afee -> 4011273b",
         "c1988920 3f471480 -> bfc3d822",
-        "3f70c440 40be95d8 -> 3e2060cf",
+        "3f70c440 40be95d8 -> 3e2060d0",
         "417834e8 415d5098 -> 3f57b555",
         "c1775234 40c0f8f8 -> bf99734e",
         "c1974114 4198ffc8 -> bf479800",
         "410c0ec4 bff12930 -> 3fe432a6",
         "413a6dc4 c09ce414 -> 3ffc0b0b",
         "be987ac0 c097edfc -> c0450d7e",
-        "bfa53460 4194fa8e -> bd8db6e0",
+        "bfa53460 4194fa8e -> bd8db6e1",
         "40d38cc8 c19c290d -> 403429aa",
         "415e9230 bea6b840 -> 3fcc0ec1",
-        "c1612e94 4199eb08 -> bf21ad98",
+        "c1612e94 4199eb08 -> bf21ad99",
         "c102419c 3f3e0580 -> bfbd6c6a",
         "c171e10c 3e75cd00 -> bfc70799",
         "c159f7c3 c040e368 -> bfe4ee5c",
@@ -25543,18 +25544,18 @@
         "c0ebecc4 4188a552 -> bed0a0ee",
         "40b612c0 419e96ba -> 3e8f1b96",
         "c1392859 c184cf09 -> c02219d5",
-        "40f88828 c0379bc8 -> 3ff65a7b",
+        "40f88828 c0379bc8 -> 3ff65a7c",
         "4183657e 418c205a -> 3f40d57c",
         "3d64c400 c049c398 -> 4047eda0",
-        "c184e5e2 c0ba5c6c -> bff438b2",
-        "c13cf1d2 c09df406 -> bffbbd3f",
+        "c184e5e2 c0ba5c6c -> bff438b3",
+        "c13cf1d2 c09df406 -> bffbbd40",
         "41951ea0 40d3e958 -> 3f9d5e14",
         "4117a1c4 4182e3fa -> 3f0666f9",
         "c100421b 3fa11c00 -> bfb52067",
         "c0a4c048 3fd9b1a0 -> bfa0392a",
         "c0bce6f0 c0a756e0 -> c012ed67",
-        "410f31a8 4089ad2c -> 3f8fb3fa",
-        "beb17800 40836d64 -> bdac6ea3",
+        "410f31a8 4089ad2c -> 3f8fb3f9",
+        "beb17800 40836d64 -> bdac6ea4",
         "c0724d88 bee688c0 -> bfd836b1",
         "3fb83bc0 c1693dec -> 4042c367",
         "c18c3dd4 4027c610 -> bfb60fc6",
@@ -25562,7 +25563,7 @@
         "41231d74 404d91d0 -> 3fa1fe4e",
         "c0e92c5a c04e1b80 -> bffe543d",
         "404ffd08 c1396f46 -> 403790b4",
-        "bf50eb60 41702f48 -> bd5e7502",
+        "bf50eb60 41702f48 -> bd5e7501",
         "c0294f90 412b4d2a -> be780e6d",
         "c0fe6df0 41350240 -> bf1cd3f4",
         "bfd3b0d0 41824f24 -> bdcf3ab0",
@@ -25571,15 +25572,15 @@
         "400eab20 c180166a -> 4040354a",
         "40b741d8 415a8318 -> 3ecb4b31",
         "c0b19f72 c1844941 -> c03455ba",
-        "418bd268 c0f5d76c -> 3ffe1262",
+        "418bd268 c0f5d76c -> 3ffe1263",
         "3fa6a0a0 c19bf37a -> 4044cb60",
         "417687a4 418fb914 -> 3f357bee",
-        "c104b28d 40b23950 -> bf7abbaa",
+        "c104b28d 40b23950 -> bf7abba9",
         "40b00cb0 be7bb000 -> 3fcec6d5",
         "41836b9a c15bc2b2 -> 40111937",
         "40697890 417344c4 -> 3e7121a8",
         "4190121e c158f0df -> 400dd562",
-        "c18bdd8b bf6a2c00 -> bfcfc0bd",
+        "c18bdd8b bf6a2c00 -> bfcfc0be",
         "418b5438 4191f240 -> 3f431ff0",
         "c0f7e4e4 410571fe -> bf3f9e8f",
         "c163d334 bd98d600 -> bfc9bb97",
@@ -25590,27 +25591,27 @@
         "c133cbd1 c12c03ab -> c015618c",
         "bf32bb00 c1111506 -> c04424d8",
         "40e3794c bfa93e10 -> 3fe099e8",
-        "419cd3d2 bf1c60c0 -> 3fcd0c96",
+        "419cd3d2 bf1c60c0 -> 3fcd0c97",
         "bf800240 40cf58c0 -> be1ccef2",
         "c1630418 4194bc52 -> bf26e0ae",
-        "419ee38a c0d13810 -> 3ff1c4a8",
+        "419ee38a c0d13810 -> 3ff1c4a9",
         "c0554ad8 bf756f80 -> bfecea8c",
         "4155c1e0 c086c8b0 -> 3ff02782",
         "c19438df c155bc54 -> c00c82ae",
         "4181ed52 c072d0e0 -> 3fe66fdc",
         "41335fee c12dcd2f -> 4015c95e",
         "c1571882 c194fd20 -> c0210be4",
-        "c19a88b4 c0b6e8d0 -> bfede30f",
-        "c153621e c19b2864 -> c022ca69",
-        "40a5abdc 419f6cf2 -> 3e822341",
+        "c19a88b4 c0b6e8d0 -> bfede310",
+        "c153621e c19b2864 -> c022ca68",
+        "40a5abdc 419f6cf2 -> 3e822342",
         "40d30c58 419f1e6c -> 3ea3ee9c",
         "418c0490 c0b33c62 -> 3ff0b4e5",
-        "c0831f14 40e27288 -> bf065d6a",
-        "bf2ad860 4075b2b0 -> be303f57",
+        "c0831f14 40e27288 -> bf065d69",
+        "bf2ad860 4075b2b0 -> be303f56",
         "bf04a640 bffc8c00 -> c038a00e",
         "bf41b3a0 40b8c260 -> be056f50",
         "4021d860 c14d4bd9 -> 403c9ba3",
-        "3d83a000 40cb8cf8 -> 3c258915",
+        "3d83a000 40cb8cf8 -> 3c258914",
         "c178b13e c0fba980 -> c0028267",
         "c0108e98 40935624 -> bee9826e",
         "40833c68 40d08ed0 -> 3f0fc87b",
@@ -25623,13 +25624,13 @@
         "c1000d87 419fc51c -> bec32579",
         "c0814a50 c18dda43 -> c03ab943",
         "c186e3b7 c15b7765 -> c0103ce8",
-        "4183a496 c01779a8 -> 3fdb58d2",
+        "4183a496 c01779a8 -> 3fdb58d3",
         "40e51c20 bfe49ed0 -> 3fe85ad7",
-        "4187b382 c1690142 -> 4011ef14",
-        "40d37970 419b19ac -> 3ea83333",
+        "4187b382 c1690142 -> 4011ef13",
+        "40d37970 419b19ac -> 3ea83332",
         "3fa7f3f0 c0b5afc8 -> 403a86cd",
         "c122c32b 416a72a0 -> bf1b5a62",
-        "40374b70 c19b6a93 -> 403fb1c2",
+        "40374b70 c19b6a93 -> 403fb1c3",
         "c08588a0 c19f609e -> c03bd8f2",
         "419cbe90 c170df46 -> 400e75e0",
         "4182e2b4 c1643109 -> 40126ac4",
@@ -25642,9 +25643,9 @@
         "c1300d51 c108ac40 -> c00ec793",
         "410261e6 c1588362 -> 40265f3f",
         "419adcac 40054e48 -> 3fbb5784",
-        "41798160 c0ecc4b0 -> 4000e25e",
+        "41798160 c0ecc4b0 -> 4000e25f",
         "40639318 c1702fdd -> 403a2d2c",
-        "c1794797 c1829f3b -> c0184bca",
+        "c1794797 c1829f3b -> c0184bc9",
         "c0904192 c0035a40 -> bfffbf67",
         "41787da0 c19a2a35 -> 401da5e0",
         "4120e654 c1014c4b -> 400fdab9",
@@ -25664,15 +25665,15 @@
         "4112e32a c18e9f42 -> 402aa0a2",
         "bfaa2d50 40ef51f8 -> be3427dc",
         "c16ae95c 406f7cb0 -> bfa91e64",
-        "40d2db80 405037e8 -> 3f8e5b81",
+        "40d2db80 405037e8 -> 3f8e5b82",
         "be920280 419b18c2 -> bc70fbde",
         "41823e9c c10676ec -> 4003074a",
         "40fc01e0 40a9689c -> 3f7a9c4a",
         "416ade10 c15a3b2c -> 40147298",
         "c12b4626 419bd752 -> bf00a1ec",
-        "413a29aa c0cd07be -> 4004befe",
+        "413a29aa c0cd07be -> 4004beff",
         "c199d0c3 c1866487 -> c0127d6a",
-        "419e0288 c1425a56 -> 4007d1b2",
+        "419e0288 c1425a56 -> 4007d1b3",
         "4144a97c 4083fd0c -> 3f9f9ec3",
         "4104e2a2 3f327440 -> 3fbe57fd",
         "c10cd1b9 40378e30 -> bfa0bd4e",
@@ -25685,7 +25686,7 @@
         "3fc08c60 c177750c -> 4042db49",
         "c10a43a9 c0be1246 -> c00b121d",
         "4061f8c0 40e4294c -> 3eeb6b1a",
-        "c0aa3df6 4165c098 -> beb5a9ce",
+        "c0aa3df6 4165c098 -> beb5a9cf",
         "c13c904c c1220f4d -> c011f7c3",
         "4141fe18 c13691ef -> 4014db0f",
         "c043e348 40bf5874 -> bef239e5",
@@ -32770,6 +32771,268 @@
         "c486ccb7 4464268f 42b60000 44088700 42475598 00000000 43258de7 44372289 44df86e2 00000000 43904267 42f00000 c2b40000 40e00000 42b80000 43200000 c2f00000 40e00000 42ba0000 43480000 c3160000 40e00000 42bc0000 43700000 c3340000 40e00000 42be0000 438c0000 c3520000 40e00000 42c00000 43a00000 c3700000 40e00000 42c20000 43b40000 c3870000 40e00000 42c40000 43c80000 c3960000 40e00000 42c60000 43dc0000 c3a50000 40e00000 42c80000 43f00000 c3b40000 40e00000 42ca0000 44020000 c3c30000 40e00000 42cc0000 440c0000 c3d20000 40e00000 42ce0000 44160000 c3e10000 40e00000 42d00000 44200000 c3f00000 40e00000 42d20000 442a0000 c3ff0000 40e00000 42d40000 44340000 c4070000 40e00000 42d60000 443e0000 c40e8000 40e00000 42d80000 44480000 c4160000 40e00000 42da0000 44520000 c41d8000 40e00000 42dc0000 445c0000 c4250000 40e00000 42de0000 44660000 c42c8000 40e00000 42e00000 44700000 c4340000 40e00000 42e20000 447a0000 c43b8000 40e00000 42e40000 44820000 c4430000 40e00000 42e60000 44870000 c44a8000 40e00000 42e80000 448c0000 c4520000 40e00000 42ea0000 44910000 c4598000 40e00000 42ec0000 44960000 c4610000 40e00000 42ee0000 449b0000 c4688000 40e00000 42f00000 44a00000 c4700000 40e00000 42f20000 44a50000 c4778000 40e00000 42f40000 44aa0000 c47f0000 40e00000 42f60000 44af0000 c4834000 40e00000 42f80000 44b40000 c4870000 40e00000 42fa0000 44b90000 c48ac000 40e00000 42fc0000 44be0000 c48e8000 40e00000 42fe0000 44c30000 c4924000 40e00000 43000000 44c80000 c4960000 40e00000 43010000 44cd0000 c499c000 40e00000 43020000 44d20000 c49d8000 40e00000 43030000 44d70000 c4a14000 40e00000 43040000 44dc0000 c4a50000 40e00000 43050000 44e10000 c4a8c000 40e00000 43060000 44e60000 c4ac8000 40e00000 43070000 44eb0000 c4b04000 40e00000 43080000 44f00000 c4b40000 40e00000 43090000 44f50000 c4b7c000 40e00000 430a0000 44fa0000 c4bb8000 40e00000 430b0000 44ff0000 c4bf4000 40e00000 430c0000 45020000 c4c30000 40e00000 430d0000 45048000 c4c6c000 40e00000 430e0000 45070000 c4ca8000 40e00000 430f0000 45098000 c4ce4000 40e00000 43100000 450c0000 c4d20000 40e00000 43110000 450e8000 c4d5c000 40e00000 43120000 45110000 c4d98000 40e00000 43130000 45138000 c4dd4000 40e00000 43140000 45160000 c4e10000 40e00000 43150000 45188000 c4e4c000 40e00000 43160000 451b0000 c4e88000 40e00000 43170000 451d8000 c4ec4000 40e00000 43180000 45200000 c4f00000 40e00000 43190000 45228000 c4f3c000 40e00000 431a0000 45250000 c4f78000 40e00000 431b0000 45278000 c4fb4000 40e00000 431c0000 452a0000 c4ff0000 40e00000 431d0000 452c8000 c5016000 40e00000 431e0000 452f0000 c5034000 40e00000 431f0000 45318000 c5052000 40e00000 43200000 45340000 c5070000 40e00000 43210000 45368000 c508e000 40e00000 43220000 45390000 c50ac000 40e00000 43230000 453b8000 c50ca000 40e00000 43240000 453e0000 c50e8000 40e00000 43250000 45408000 c5106000 40e00000 43260000 45430000 c5124000 40e00000 43270000 45458000 c5142000 40e00000 43280000 45480000 c5160000 40e00000 43290000 454a8000 c517e000 40e00000 432a0000 454d0000 c519c000 40e00000 432b0000 454f8000 c51ba000 40e00000 432c0000 45520000 c51d8000 40e00000 432d0000 45548000 c51f6000 40e00000 432e0000 45570000 c5214000 40e00000 432f0000 45598000 c5232000 40e00000 43300000 455c0000 c5250000 40e00000 43310000 455e8000 c526e000 40e00000 43320000 45610000 c528c000 40e00000 43330000 45638000 c52aa000 40e00000 43340000 45660000 c52c8000 40e00000 43350000 45688000 c52e6000 40e00000 43360000 456b0000 c5304000 40e00000 43370000 456d8000 c5322000 40e00000 43380000 45700000 c5340000 40e00000 43390000 45728000 c535e000 40e00000 433a0000 45750000 c537c000 40e00000 433b0000 45778000 c539a000 40e00000 433c0000 457a0000 c53b8000 40e00000 433d0000 457c8000 c53d6000 40e00000 433e0000 457f0000 c53f4000 40e00000 433f0000 4580c000 c5412000 40e00000 43400000 45820000 c5430000 40e00000 43410000 45834000 c544e000 40e00000 43420000 45848000 c546c000 40e00000 43430000 4585c000 c548a000 40e00000 43440000 45870000 c54a8000 40e00000 43450000 45884000 c54c6000 40e00000 43460000 45898000 c54e4000 40e00000 43470000 458ac000 c5502000 40e00000 43480000 458c0000 c5520000 40e00000 43490000 458d4000 c553e000 40e00000 434a0000 458e8000 c555c000 40e00000 434b0000 458fc000 c557a000 40e00000 434c0000 45910000 c5598000 40e00000 434d0000 45924000 c55b6000 40e00000 434e0000 45938000 c55d4000 40e00000 434f0000 4594c000 c55f2000 40e00000 43500000 45960000 c5610000 40e00000 43510000 45974000 c562e000 40e00000 43520000 45988000 c564c000 40e00000 43530000 4599c000 c566a000 40e00000 43540000 459b0000 c5688000 40e00000 43550000 459c4000 c56a6000 40e00000 43560000 459d8000 c56c4000 40e00000 43570000 459ec000 c56e2000 40e00000 43580000 45a00000 c5700000 40e00000 43590000 00000002 43820000 3f333333 3fcccccd 42f00000 3eb33333 00000000 00000000 3f800000 -> 3ef8c434 3f32636d 3efbcd58 3e549b04",
         "c4b3e76c 444241a0 42500000 435b9579 4136dbcf 00000000 43945431 43041651 43830dcc 00000000 43652355 c48bf352 44d33444 00000000 434dc873 c3000002 c10833d3 00000000 433550ff c28b6e94 c30f7278 00000000 438d43a6 44a4de09 c4f12ff1 00000000 425a0d22 44d428d3 430976c5 00000000 434b973e 441d5713 44a7fc0b 00000000 438e7c40 c4ab19d7 44f2b987 00000000 41e038cc c455d2d5 c2a36170 00000000 43908b8d c3801d60 c40e138a 00000000 431363cc 43396792 c37f2156 00000000 437ac80c 439f85f6 420c7863 00000000 42150b58 4428e36e 44c2bb96 00000000 43837958 c47c7670 44a88b01 00000000 4294d48d c40641aa c285e8ba 00000000 4232d05c c40ca53f c4a8ca3a 00000000 4378763b 42cfefd3 c306ba40 00000000 430371e3 44b979fd 434ebfb9 00000000 43421a7a 42b44286 43616d19 00000000 43047467 c2892c2a 42ac8e8b 00000000 4332087f c4f373b1 c39604df 00000000 42b3908c c4071e02 c4b04c5b 00000000 4347459e 43fd006f c41a827e 00000000 4208fda6 44c75602 43869ead 00000000 42421b44 4351a83b 440ee820 00000000 42cc9909 c48345c8 449bb4d1 00000000 42125362 c4abe6d8 c37c9d2e 00000000 433a98a6 c43a8ecd c5050f9b 00000000 42b796d8 4488f948 c49dcc59 00000000 43638b9c 4518e99d 43f2fa58 00000000 4271681e 4436363e 450837cb 00000000 437c8686 c49f0216 44b1f01c 00000000 438026fe c4af2be6 c395b304 00000000 43814487 c3f349af c4befb18 00000000 428c07fa 4424afd0 c4330845 00000000 42decd7b 4513cf17 44073fe5 00000000 438a0efc 442d8bbd 450f5844 00000000 434b07a5 c493ef20 449c3dfb 00000000 437f587e c4222d07 c31e43fc 00000000 43128220 c4066f1d c4ea31b9 00000000 4340306c 43e81d81 c3ee2e59 00000000 4330577c 4514ae2d 441a3491 00000000 43869616 439ae709 448ea55a 00000000 43226a3e c4068e80 440626bb 00000000 430d975e c49c9b56 c3ac1805 00000000 42dea520 c4161f98 c5129034 00000000 42da3948 44400c36 c43a07ca 00000000 43826b94 44c6d8dc 43e6e324 00000000 438edae5 4396e0d8 449ca83c 00000000 43643dd5 c35d19fc 4350154a 00000000 430efc77 c485b6e4 c3a3a64d 00000000 4312ff68 c3cdea28 c4e43378 00000000 4385fba4 44224024 c4145936 00000000 435e4c43 43a49d73 42d3e418 00000000 438636f8 43ed8fd2 450d12ed 00000000 4210bc80 c2dcc99b 42c41aba 00000000 4299b2ee c50fdfe9 c44262e4 00000000 42fe5060 c3dac9b9 c50be58c 00000000 42f0366f 44ca1d48 c4ae6032 00000000 4382f138 4475cf34 43adfc47 00000000 420467d2 4383e7ac 44b69e10 00000000 42939fb6 c4a5b2bc 448ad7eb 00000000 41f43fa8 c461b848 c3a71faa 00000000 434a4234 c358c6a6 c4a37e3e 00000000 423c3b16 42ae5790 c28ddcb8 00000000 435f71b1 44586d7a 43a75f50 00000000 431dfe64 43126575 44726ffe 00000000 42e181b4 c3da9fe9 43acb878 00000000 436eefe3 c4efcdc3 c4416fe4 00000000 423c53dc c344a113 c4b46166 00000000 435ffd97 44553a65 c4238580 00000000 430092b5 4499e952 440156a4 00000000 430fbb25 42c9a36d 444f404d 00000000 4369e56c c43b5358 440b6b0e 00000000 41cf9cce c5087fe5 c46ebaa1 00000000 42caf529 c21191e4 c3aa0683 00000000 4344d73b 443ee95e c409dbcb 00000000 41f53bb8 44f6e532 44606df7 00000000 42aa10aa 433460d1 44f3d985 00000000 43582457 c48b83c0 44436f9c 00000000 4350ab77 c4098067 c381cd3a 00000000 41ad0134 c32c4d09 c50a24e7 00000000 4293fef2 44bb391d c47e4d73 00000000 432790ce 44ec7b40 4467a0ac 00000000 43470d71 420e374b 440c07c0 00000000 425deb6d c4911239 443effdb 00000000 4366654f c43619f1 c3b8eb31 00000000 434e068d c2a05b66 c4cc6faf 00000000 4291eb66 44b5dd54 c468003e 00000000 42acbd25 44cd3c28 4457e72d 00000000 433ac26f 41e50db8 444eeade 00000000 431d0e95 c3beb1b5 436b9aef 00000000 435bf745 c4afd8d7 c43f8161 00000000 435bc798 c10e3dc0 c3dc6413 00000000 42e0327b 448376b9 c41d3ced 00000000 439027f4 42ccb7fb 4266a7eb 00000000 42561b63 4107706a 44b7ae4c 00000000 4386c984 c49102da 4427d07c 00000000 43041b2c c48de2f6 c4254afa 00000000 42dc4d73 417fe3ca c4e73dfa 00000000 436e328f 44fdd280 c48e0708 00000000 435a40e7 44dfcd51 4486b7c0 00000000 437af18e c22ffde1 44ee8d5d 00000000 42ebac6a c445a9ae 43d5c9a6 00000000 43543326 c45fbee4 c40b1d1a 00000000 43507e5b 425680ee c4b2d793 00000000 432a871c 45066678 c48c65e4 00000000 438c4680 44501288 44059013 00000000 435e3b80 c2e08f5e 45072ba4 00000000 428609a6 c4a3143d 44246ade 00000000 4395e45b c4556a6b c40d5fe9 00000000 4321ff85 4206eb23 c3fe1841 00000000 42ab0018 43addb6e c3290c04 00000000 4308e930 43dc68f5 43969f8a 00000000 430610e6 c2126c9e 43e25da0 00000000 42ae86ef c4c4feae 4438935d 00000000 42ef05dd c486c228 c43def39 00000000 438f4904 4321a791 c4d3da54 00000000 433ab2f6 44c00026 c42d31f8 00000000 42db619b 44f338d9 44b0b3b2 00000000 42c2bff2 c2dd8512 447bddda 00000000 4313918c c505ea13 44685e96 00000000 4372ce6f 459b0000 c5688000 40e00000 43550000 459c4000 c56a6000 40e00000 43560000 459d8000 c56c4000 40e00000 43570000 459ec000 c56e2000 40e00000 43580000 45a00000 c5700000 40e00000 43590000 0000007b 43820000 3f333333 3fcccccd 42f00000 3eb33333 3f19999a 3f4ccccd 3f800000 -> 3f1796ad 3f2abc83 3f147ad8 3f6031e3"
       ]
+    },
+    {
+      "glsl": "float cultmath_fbm(vec3, int, float, float)",
+      "tolerance": "ulp-bounded",
+      "cases": [
+        "c11a9d90 c04202a0 c20bc826 00000004 40000000 3f000000 -> 3f27d6ca",
+        "41601e80 4005e0a0 41eba008 00000004 40000000 3f000000 -> be8cf3fd",
+        "407e0d30 c181cd2c 41cbe660 00000004 40000000 3f000000 -> 3eebda0d",
+        "41b7f3d4 c129244c c0fdb2f0 00000004 40000000 3f000000 -> bd3ada1f",
+        "407005a0 4118392c 41a44bb4 00000004 40000000 3f000000 -> beabbce1",
+        "c1830e64 c2048dab 422a3126 00000004 40000000 3f000000 -> 3e53b796",
+        "407894c0 c2091ce8 4243e388 00000004 40000000 3f000000 -> beff701d",
+        "c1f06795 c23c1b2b c2412342 00000004 40000000 3f000000 -> 3ec7b869",
+        "c1bdbda4 41dc0d48 c22f43c4 00000004 40000000 3f000000 -> bec760f6",
+        "408126b0 c1ea0445 c1a7655d 00000004 40000000 3f000000 -> 3e0a4e06",
+        "413dbdcc 422bc160 40f21a68 00000004 40000000 3f000000 -> bea53f12",
+        "c1484ebc 420439be 416f96b0 00000004 40000000 3f000000 -> 3e72cffa",
+        "c1ba67c0 408252b0 421a9588 00000004 40000000 3f000000 -> bf451a7c",
+        "c16b1c64 41a06cd4 c176d898 00000004 40000000 3f000000 -> 3f02099c",
+        "4120d64c 41de56d4 40b8cd88 00000004 40000000 3f000000 -> 3f2bebc0",
+        "c1ca675a c230dc20 c22de33d 00000004 40000000 3f000000 -> 3f1cd196",
+        "4137ed30 4146d32c c21ce93a 00000004 40000000 3f000000 -> 3da3b336",
+        "c08f7cb0 4226b458 41db68b4 00000004 40000000 3f000000 -> be182486",
+        "41f4cfe4 c1ece732 c0c027f0 00000004 40000000 3f000000 -> 3daec608",
+        "c212a4e3 c1446638 41c4aed0 00000004 40000000 3f000000 -> be06a746",
+        "41ba2790 4247bbfe c213e474 00000004 40000000 3f000000 -> 3f08da39",
+        "c065a220 c21b758b c060a740 00000004 40000000 3f000000 -> 3f0948cb",
+        "420a0656 c206ebf6 41d3a918 00000004 40000000 3f000000 -> be0f2d50",
+        "c231bfd1 c22c5352 414c9ffc 00000004 40000000 3f000000 -> 3d5ad4f0",
+        "c2386461 c1fb5f35 c08a9a88 00000004 40000000 3f000000 -> bf0307b4",
+        "416666b8 411e5a8c c1c68d2b 00000004 40000000 3f000000 -> bf3c2a7e",
+        "c081e798 c241ab24 41adc588 00000004 40000000 3f000000 -> 3ecf6bca",
+        "42469f7a 422a298a 41052448 00000004 40000000 3f000000 -> bd9e0e93",
+        "c1fd92e8 c206a0f6 c242f2f6 00000004 40000000 3f000000 -> bea9dec8",
+        "41f11de8 40dc22f8 414ab55c 00000004 40000000 3f000000 -> bd8bc474",
+        "c1e82aab c2128efd c2069c1b 00000004 40000000 3f000000 -> be7c0319",
+        "c20fc1e0 41409478 41a0f4d8 00000004 40000000 3f000000 -> 3da2f1d0",
+        "c1e3a366 c211704c 418541ec 00000004 40000000 3f000000 -> 3f3968b5",
+        "c222dbdb c11ce808 421e0fd6 00000004 40000000 3f000000 -> 3eb06c7c",
+        "c19f6f92 40bdd8e0 40b040e8 00000004 40000000 3f000000 -> 3d4ea228",
+        "c0011390 c1062cd4 41b8c7e4 00000004 40000000 3f000000 -> bed7e250",
+        "c191f0aa c20731bd 4127d710 00000004 40000000 3f000000 -> 3e0d1a30",
+        "c1f97cd1 418b3020 c15db9a8 00000004 40000000 3f000000 -> 3dfd58fc",
+        "c23c8b5e 41bce8a0 c22a6d8e 00000004 40000000 3f000000 -> 3c465804",
+        "409693d0 c1af215b 42332b6c 00000004 40000000 3f000000 -> bee9b32d",
+        "c098bbf0 c236889e 41163eac 00000004 40000000 3f000000 -> 3f0bd913",
+        "c210d8cb 420a5584 422e3bac 00000004 40000000 3f000000 -> bebb6492",
+        "c063be60 421f5d7e 40d15a40 00000004 40000000 3f000000 -> 3ebd15a8",
+        "41cc6488 c0e4a4f8 c06f9100 00000004 40000000 3f000000 -> 3db49ff4",
+        "410861d0 c155845c 41363b78 00000004 40000000 3f000000 -> bdcb6293",
+        "4200d2ee 419cae84 c1564644 00000004 40000000 3f000000 -> 3edb892a",
+        "c23cbf0a 41a28f8c 41c5d480 00000004 40000000 3f000000 -> bf2d47fb",
+        "c1aeadcf bfcf1700 c1152790 00000004 40000000 3f000000 -> be5972ba",
+        "c23f486c c23f56ed c0813868 00000004 40000000 3f000000 -> 3ee6dc4a",
+        "41f1a4a0 c21b3682 4219b0ce 00000004 40000000 3f000000 -> bf0eadc6",
+        "414b9fe8 4186b7a4 420e2062 00000004 40000000 3f000000 -> 3e2980bf",
+        "41aeeb18 4160ee88 c162c594 00000004 40000000 3f000000 -> bee70d01",
+        "c19effaa c206defe 41aacb30 00000004 40000000 3f000000 -> 3de761d6",
+        "413f31c0 c241d553 3fe2e9a0 00000004 40000000 3f000000 -> bde2b38a",
+        "c205c755 40c6ab38 41bac5c0 00000004 40000000 3f000000 -> 3ed8ad73",
+        "c20f112c 4124a490 c19a0db2 00000004 40000000 3f000000 -> bdc30b1c",
+        "41c60570 c1eabc98 c237e2f2 00000004 40000000 3f000000 -> bf4faa5b",
+        "41a64804 3ff230a0 40f93c68 00000004 40000000 3f000000 -> bee98cca",
+        "c1ef7da7 c203c097 40bf80d8 00000004 40000000 3f000000 -> 3db61265",
+        "c1fa4ce3 c219905e 4201ac72 00000004 40000000 3f000000 -> bf387f6a",
+        "c019d480 4181e398 41e52800 00000004 40000000 3f000000 -> be033562",
+        "4190f4f4 c214b5b7 41d01f1c 00000004 40000000 3f000000 -> 3d5e261c",
+        "412b9a38 4212a2e8 41b4c68c 00000004 40000000 3f000000 -> 3f336c18",
+        "c1c37f7b 40052c30 405363f0 00000004 40000000 3f000000 -> 3e9fce4c",
+        "41742360 c1122dec 41963a2c 00000004 40000000 3f000000 -> 3d369949",
+        "c1d85a1d c2198f93 4228b1e0 00000004 40000000 3f000000 -> 3e151611",
+        "418aa674 4217c8c0 c1020040 00000004 40000000 3f000000 -> 3d9e5382",
+        "c20b2034 c232306a 422227ca 00000004 40000000 3f000000 -> 3d21dba6",
+        "420993c0 4227c3f8 c20c35b2 00000004 40000000 3f000000 -> 3e254db8",
+        "c1b20e56 3fe68be0 c0403c60 00000004 40000000 3f000000 -> 3e00593c",
+        "41eebd00 c21a5963 c2354e9f 00000004 40000000 3f000000 -> bf023291",
+        "421bb928 c20e9648 c16b1c78 00000004 40000000 3f000000 -> bf0b8dcb",
+        "41b90698 bfc839c0 c0d3a708 00000004 40000000 3f000000 -> bf1723c8",
+        "423d5354 40608460 41bd0c74 00000004 40000000 3f000000 -> bcc26220",
+        "41025788 bf4f6280 41949de4 00000004 40000000 3f000000 -> beed4e99",
+        "3f39b3c0 c231e4d4 c21be301 00000004 40000000 3f000000 -> be0bb9b2",
+        "421c0a76 423c6e3a c2323104 00000004 40000000 3f000000 -> bf40bdcd",
+        "415cf8ec 3fb0caa0 c1d2b23c 00000004 40000000 3f000000 -> be851f93",
+        "c1174dfc c18cfa28 412c88d4 00000004 40000000 3f000000 -> 3f111826",
+        "42186c38 4206e6ba c1e8f35c 00000004 40000000 3f000000 -> bec21f9a",
+        "41311500 c188248e c17245d8 00000004 40000000 3f000000 -> 3d6acd72",
+        "c1c331e9 c088f1f0 c1154f68 00000004 40000000 3f000000 -> 3f32b2ec",
+        "bfaf6440 41d29f60 c1bbea67 00000004 40000000 3f000000 -> 3d96329a",
+        "c1843796 be305a00 4152c8e8 00000004 40000000 3f000000 -> bdce91e5",
+        "bf9b27e0 419fffcc c178fe1c 00000004 40000000 3f000000 -> 3e94636d",
+        "4191f36c 40e24f50 40c86908 00000004 40000000 3f000000 -> beb06eb9",
+        "c1e04e4e c182a61e 4211a8cc 00000004 40000000 3f000000 -> 3e4f51ee",
+        "c23852b1 c1344684 40963120 00000004 40000000 3f000000 -> 3f06fbc7",
+        "c1074b08 c207dfba 41208124 00000004 40000000 3f000000 -> 3f44398c",
+        "41f81500 bfce6b20 41ffcd98 00000004 40000000 3f000000 -> 3db207ed",
+        "41c42d58 420c1714 416b5de8 00000004 40000000 3f000000 -> be56c8b1",
+        "c1dbf666 c15bc7b4 c1ebcae6 00000004 40000000 3f000000 -> be987233",
+        "c133a140 c18ba254 c23a1f4c 00000004 40000000 3f000000 -> be6063b7",
+        "c1b0ba6b c23f9e0f c1a66906 00000004 40000000 3f000000 -> 3e71480d",
+        "420a1232 40b13200 c02e16b0 00000004 40000000 3f000000 -> bda67ee4",
+        "c0f719f8 c20be886 41fb0cd8 00000004 40000000 3f000000 -> be9018c6",
+        "421ce668 41b26594 41ca7208 00000004 40000000 3f000000 -> 3f33ea18",
+        "c235eaec 418126bc 3d672000 00000004 40000000 3f000000 -> bea45437",
+        "c17889e4 40e4bf88 4230ff5a 00000004 40000000 3f000000 -> beb68251",
+        "41f150cc 420839ce c1a27d07 00000004 40000000 3f000000 -> bcbd7004",
+        "41f517bc 418cf4bc c1b079ee 00000004 40000000 3f000000 -> bb24d74c",
+        "c0aedff8 410f3624 416ce240 00000004 40000000 3f000000 -> 3f0d6ce0",
+        "4241dac2 c1bdbc18 c1821c58 00000004 40000000 3f000000 -> bea85f48",
+        "c2105a14 c1a43bf4 c1cbc9d9 00000004 40000000 3f000000 -> 3ebe4d06",
+        "4032c6d0 42303610 c19369ff 00000004 40000000 3f000000 -> 3ee7e743",
+        "40e6ea70 c1f4c9c7 4204c81e 00000004 40000000 3f000000 -> be98d471",
+        "c22a5870 4245107c c243f735 00000004 40000000 3f000000 -> bed2576b",
+        "41e533b8 42272418 41d0b3b4 00000004 40000000 3f000000 -> 3e0d2bde",
+        "c22d5237 41a00334 c1f8f891 00000004 40000000 3f000000 -> 3e1a4a1f",
+        "c20d624e 42182746 41e8ec44 00000004 40000000 3f000000 -> bd73af1a",
+        "c1bdc99a 4109bd28 bfc15ee0 00000004 40000000 3f000000 -> bdd4a46b",
+        "41be3e70 c02e9130 c17861bc 00000004 40000000 3f000000 -> be9a49dc",
+        "c242f78d c1204738 423a58b8 00000004 40000000 3f000000 -> bd8f7f9e",
+        "4201e604 c0c5f000 421af586 00000004 40000000 3f000000 -> bd939ee0",
+        "c016b680 41ca80f8 c0e579d8 00000004 40000000 3f000000 -> be949954",
+        "3f477c00 3fdd1520 41b0ba9c 00000004 40000000 3f000000 -> 3f61641f",
+        "c1fc2271 41da0074 c1440cb0 00000004 40000000 3f000000 -> 3d22d4bd",
+        "c21bc8c4 41b601ac 420b2952 00000004 40000000 3f000000 -> bea1ff75",
+        "c1aa8e9f c2400dfe 41ceac90 00000004 40000000 3f000000 -> bf0ee9ae",
+        "3fed25c0 c1422724 421bcbf0 00000004 40000000 3f000000 -> 3e7b8260",
+        "c0825938 42073d10 c13c1548 00000004 40000000 3f000000 -> 3e8108b9",
+        "4093dd90 42168aba 41a6e578 00000004 40000000 3f000000 -> bf70dcc5",
+        "41d04c14 41e81a68 c04e0de0 00000004 40000000 3f000000 -> 3f169ba9",
+        "423c6370 40bea6d8 41eb59d4 00000004 40000000 3f000000 -> be27a3b6",
+        "42126f66 c1c87ce9 40ae73e0 00000004 40000000 3f000000 -> bdecf67a",
+        "c216ecbb c197f579 c2061c65 00000004 40000000 3f000000 -> bec0f5a1",
+        "c185edd2 40bc7ec8 c1fdce1e 00000004 40000000 3f000000 -> beaeea8a",
+        "c04d9980 4238aeec c21cd8f3 00000004 40000000 3f000000 -> bf4c5f9d",
+        "c10a1ac8 c20b1c08 420f6e74 00000004 40000000 3f000000 -> bca013bc",
+        "415b2edc c09ccbc8 c096d8b0 00000004 40000000 3f000000 -> be5536d7",
+        "410a4524 bf182e80 c23f8806 00000004 40000000 3f000000 -> 3ee6c4f3",
+        "c2297336 c1573b54 412013c4 00000004 40000000 3f000000 -> 3c3ab7a0",
+        "3efd6c00 422c18e8 4216b5c2 00000004 40000000 3f000000 -> beeca0ab",
+        "41afbc10 41c5efcc 41b5b6e8 00000004 40000000 3f000000 -> bf364b64",
+        "c1c583a7 c1e4e94f c1e5a945 00000004 40000000 3f000000 -> bf34f4f8",
+        "41053fa4 c1cc7056 c00c0b50 00000004 40000000 3f000000 -> bdda9df2",
+        "c1a54a53 c2065a94 41a7d97c 00000004 40000000 3f000000 -> 3e6ae330",
+        "4115cab4 c1fb3fd3 41ffccbc 00000004 40000000 3f000000 -> be2050ce",
+        "41a565fc 42448e70 42168e26 00000004 40000000 3f000000 -> bd95b845",
+        "c1b458be c212fd9c 41b34d84 00000004 40000000 3f000000 -> bde52094",
+        "420c044a c216a5ac c180b2a6 00000004 40000000 3f000000 -> 3ea3b257",
+        "c24205c8 c138b768 c22dca6a 00000004 40000000 3f000000 -> bf026e60",
+        "41da69e0 41e7c53c 42199060 00000004 40000000 3f000000 -> 3e296457",
+        "4235c98a 413c61b4 c1404e8c 00000004 40000000 3f000000 -> bd267211",
+        "c1a9a44f 4134ac38 41f92fec 00000004 40000000 3f000000 -> bd77a9b6",
+        "c08e1418 c1e42f89 41c64724 00000004 40000000 3f000000 -> 3f071a60",
+        "421dfbb0 42042964 42231c22 00000004 40000000 3f000000 -> be057b84",
+        "c13f435c c17a3c80 c1aa7dc8 00000004 40000000 3f000000 -> bece20fe",
+        "41c27058 42451e9c c19981a2 00000004 40000000 3f000000 -> be79305d",
+        "c1eedcc7 c15098d0 c1497518 00000004 40000000 3f000000 -> be9e1b90",
+        "41b2ed98 c1d7b191 41ee2d04 00000004 40000000 3f000000 -> 3d44b899",
+        "c20af100 4213d9c0 41467648 00000004 40000000 3f000000 -> 3ec0aa40",
+        "c1332ce4 c1d17816 4203b932 00000004 40000000 3f000000 -> be11a895",
+        "c20d0a38 41f835f0 c090d638 00000004 40000000 3f000000 -> be1498a4",
+        "4116bbac c180dd68 409467f0 00000004 40000000 3f000000 -> bf0fd158",
+        "c187ff3c c19b7655 40e9a840 00000004 40000000 3f000000 -> 3e89df12",
+        "c244b197 c1c714ff 41dd4c6c 00000004 40000000 3f000000 -> 3ead3f11",
+        "c214956d c140a03c c19e4e02 00000004 40000000 3f000000 -> 3ef4d00f",
+        "41fd1540 c042ae00 41dfd2e8 00000004 40000000 3f000000 -> 3d973e78",
+        "c2331a6e c1b67be9 c12d31d4 00000004 40000000 3f000000 -> be750957",
+        "41cdeccc 40e51a98 c0ffb978 00000004 40000000 3f000000 -> be253870",
+        "3f7b69c0 c1d75a82 c1343b2c 00000004 40000000 3f000000 -> 3dbf25d2",
+        "41035764 c211e128 41c2a2a0 00000004 40000000 3f000000 -> 3f151eee",
+        "c1fa0b38 c22cf74a 423ea448 00000004 40000000 3f000000 -> bd6e638c",
+        "42276a60 41c60bd0 c23ff195 00000004 40000000 3f000000 -> bf359aaa",
+        "c09648b8 41e5007c c246206c 00000004 40000000 3f000000 -> 3ec9a87b",
+        "41c06838 c10b20d4 4195b38c 00000004 40000000 3f000000 -> be8ff22f",
+        "41bc1450 c1f57998 c2189bb5 00000004 40000000 3f000000 -> 3e28b2f1",
+        "411bf210 411830e4 420c4f46 00000004 40000000 3f000000 -> be20e42c",
+        "bee13d80 c182f740 c11fed84 00000004 40000000 3f000000 -> bf6b6b32",
+        "4209b41c c1836194 423a81ea 00000004 40000000 3f000000 -> 3eebe724",
+        "c0c7d2c8 c1300278 c1d110b4 00000004 40000000 3f000000 -> 3edf09dc",
+        "c23a2398 c2263ebc c21cc173 00000004 40000000 3f000000 -> 3f347bc5",
+        "c2086436 41c65514 c203da03 00000004 40000000 3f000000 -> be4a016a",
+        "4203e3b8 42005406 c1fd266b 00000004 40000000 3f000000 -> 3e92d85b",
+        "41f003dc c1e7ff9b 41534824 00000004 40000000 3f000000 -> bf51dab7",
+        "c1ae6ad8 c15ab124 4192a9c8 00000004 40000000 3f000000 -> 3ea4064b",
+        "41dc13c0 c1969d16 420f8a40 00000004 40000000 3f000000 -> 3f0909f0",
+        "41a3b388 c23f13c1 c1427f80 00000004 40000000 3f000000 -> 3e6ede51",
+        "c19eb6f5 4224f120 41591a18 00000004 40000000 3f000000 -> 3e6ab4d3",
+        "406a1ef0 c22567ab 41ef34f0 00000004 40000000 3f000000 -> bf055e0e",
+        "c17acd40 c17ae6e4 41b97304 00000004 40000000 3f000000 -> be66940a",
+        "c243dda3 bff368e0 c163e5e4 00000004 40000000 3f000000 -> bd501bea",
+        "41e12d8c c10295fc 41a17df0 00000004 40000000 3f000000 -> 3dd3be72",
+        "421ea106 4102614c 41841a84 00000004 40000000 3f000000 -> bf09bbcc",
+        "3fd67940 42222670 c14c4344 00000004 40000000 3f000000 -> 3ee83191",
+        "422df782 41edf52c c137cfe8 00000004 40000000 3f000000 -> 3d22e603",
+        "c1e10584 c1e51a20 423d30aa 00000004 40000000 3f000000 -> 3f0369ee",
+        "41ad5f78 c22c55c3 c23e623f 00000004 40000000 3f000000 -> bd8b828e",
+        "c21d0856 41ba57c4 c153b374 00000004 40000000 3f000000 -> bf83804f",
+        "42101786 41ba6fc4 c2032fdd 00000004 40000000 3f000000 -> 3e0487d8",
+        "c0307f90 4143e76c 41812468 00000004 40000000 3f000000 -> bf30ffd4",
+        "c14dd1ec bfad1f00 c00f2420 00000004 40000000 3f000000 -> bdccd9c1",
+        "c09a65b8 41e7bf24 41b736f4 00000004 40000000 3f000000 -> 3f093490",
+        "c1b468fb 3d4f3800 4231f934 00000004 40000000 3f000000 -> 3c21555a",
+        "424095ea 421768d8 41b83244 00000004 40000000 3f000000 -> bece4789",
+        "c1f50604 c1f9b40a c2193a31 00000004 40000000 3f000000 -> be4a50c7",
+        "c2458f10 c1554bf0 c21a0974 00000004 40000000 3f000000 -> bf1acbb9",
+        "c1c78b00 c191b69e 42152566 00000004 40000000 3f000000 -> be957456",
+        "420269ce 414a73d0 c1b4c7ed 00000004 40000000 3f000000 -> 3e697510",
+        "41a63780 42212ab4 41c671ac 00000004 40000000 3f000000 -> 3f139976",
+        "4243f362 42287f3e 4194453c 00000004 40000000 3f000000 -> 3c50a516",
+        "403eed70 c0f2b800 42379e78 00000004 40000000 3f000000 -> beba9818",
+        "c24684f1 c20dd7bc c101c264 00000004 40000000 3f000000 -> 3d3cca45",
+        "421de172 bfd77900 c244e4fc 00000004 40000000 3f000000 -> 3f050db9",
+        "4179c230 4231b1ba 41aa7e40 00000004 40000000 3f000000 -> 3e3e0e04",
+        "c23cc88c 41bc33a8 c1f77d37 00000004 40000000 3f000000 -> 3d7074f3",
+        "c1a4f6c3 42257aac 40902f38 00000004 40000000 3f000000 -> 3cded1fb",
+        "c1c76558 420da696 c155d488 00000004 40000000 3f000000 -> bdb2d8a1",
+        "c2312669 c1de84f2 c19c55ac 00000004 40000000 3f000000 -> bf733e95",
+        "41e6d99c 40910dc0 420ffa14 00000004 40000000 3f000000 -> be87cefb",
+        "c1ed1c98 41c32f10 421ab4de 00000004 40000000 3f000000 -> beac3f5c",
+        "424062a4 c1ac4fc1 40fda488 00000004 40000000 3f000000 -> bed84bad",
+        "c1c052d0 c09ac768 c0920138 00000004 40000000 3f000000 -> 3e8a6d70",
+        "41d8f554 c1f7fc22 c2370249 00000004 40000000 3f000000 -> 3eb1ddd1",
+        "419e6cd0 c21b7082 421968ce 00000004 40000000 3f000000 -> be530987",
+        "c21d2479 411727cc c14a3428 00000004 40000000 3f000000 -> 3dd46038",
+        "c20819bc 41ee64b4 421c8320 00000004 40000000 3f000000 -> bdbaa7c4",
+        "c226a55b c109a378 4243b008 00000004 40000000 3f000000 -> 3da8d91f",
+        "c1ed9a23 41bf4c20 c22d2758 00000004 40000000 3f000000 -> be4a641a",
+        "c190d081 c02eac10 c1ee290f 00000004 40000000 3f000000 -> 3e49c3d4",
+        "41772540 c1e3e37f 41201a34 00000004 40000000 3f000000 -> be5c48b4",
+        "40bcaa98 4198df7c 41bf595c 00000004 40000000 3f000000 -> 3f1b99b9",
+        "c21799da 418c1bd0 417f6670 00000004 40000000 3f000000 -> bd1b2a24",
+        "c2127570 41d6c1b8 c1ad1a80 00000004 40000000 3f000000 -> 3d032504",
+        "41bd0318 40109f50 41b2f178 00000004 40000000 3f000000 -> be738350",
+        "3e841880 40a8b758 41c22e30 00000004 40000000 3f000000 -> be993b38",
+        "bfdbbdc0 4233fe10 414bce50 00000004 40000000 3f000000 -> be35bd5c",
+        "422c6234 414e1a28 41c5deb8 00000004 40000000 3f000000 -> 3eaa7016",
+        "423b76f4 c217e8f1 c187ff32 00000004 40000000 3f000000 -> 3ec9b4b3",
+        "421f04d6 41de5f6c 40919080 00000004 40000000 3f000000 -> be522d95",
+        "3f9b7d20 42303ed8 423f91d4 00000004 40000000 3f000000 -> beed15a0",
+        "c1c65740 c2194ea5 423df3ae 00000004 40000000 3f000000 -> be9b386d",
+        "c0b846b8 c2105eea c0ff01f8 00000004 40000000 3f000000 -> be6e4c9a",
+        "c20e43e2 42427560 4227bc0c 00000004 40000000 3f000000 -> 3eb83eb6",
+        "41ab32b4 c23da44d c23c2e83 00000004 40000000 3f000000 -> bf1c83e6",
+        "412c4184 c1749b9c 421c8d2c 00000004 40000000 3f000000 -> be315e50",
+        "c1bb9168 41a0557c c1fae1b8 00000004 40000000 3f000000 -> be39850e",
+        "c18c7cde 420675ae 401172f0 00000004 40000000 3f000000 -> bec5ccdb",
+        "40efbf28 41b2ce34 410a1ed8 00000004 40000000 3f000000 -> bf1e2c8b",
+        "420d1730 41107978 40e2c578 00000004 40000000 3f000000 -> 3eb26d1a",
+        "c1114ee0 c1dd3d62 421ede34 00000004 40000000 3f000000 -> 3db35cba",
+        "c21a5874 4142baa4 42032204 00000004 40000000 3f000000 -> bcff40fb",
+        "c19c3e28 bfca5a80 c1169d98 00000004 40000000 3f000000 -> bf81fcc7",
+        "41c70a18 c22feef8 c10a28ac 00000004 40000000 3f000000 -> bea49aff",
+        "c18e1152 c181341a 423988ae 00000004 40000000 3f000000 -> 3e720a62",
+        "41a66f10 c1e26e4d 4124ab60 00000004 40000000 3f000000 -> 3e3bbee8",
+        "41ae3bc0 c15e65b4 41da7bec 00000004 40000000 3f000000 -> 3e0672ef",
+        "c0c46630 4153362c c228fb08 00000004 40000000 3f000000 -> bf217d87",
+        "c1617454 c1f9cb51 c21e36d6 00000004 40000000 3f000000 -> be923997",
+        "c08c2ae0 418db8f4 c12ad700 00000004 40000000 3f000000 -> bef08fdd",
+        "c1325020 410f7fe4 409c15b8 00000004 40000000 3f000000 -> be423c5a",
+        "420bc714 41bc1fb0 41d22824 00000004 40000000 3f000000 -> 3e0456ea",
+        "c23f2228 411fc738 c1194bd4 00000004 40000000 3f000000 -> 3b981998",
+        "c1eea110 c19da117 42112bee 00000004 40000000 3f000000 -> beafb6e7",
+        "bfb96dc0 3fd647a0 416066d8 00000004 40000000 3f000000 -> be699b27"
+      ]
     }
   ]
 }

packages/cultmath/tools/phacelle-lipschitz/Program.cs

@@ -0,0 +1,92 @@
+// Measures the Lipschitz constant of math.phacelle's (cosine, sine) field, the number docs/design.md quotes and
+// PhacelleTests.GradientNormStaysUnderTheDocumentedLipschitzEnvelope pins.
+//   dotnet run -c Release --project packages/cultmath/tools/phacelle-lipschitz -- <samples per cell> <normalizations> <side lengths>
+//   e.g. ... -- 4000000 0,0.5,0.75,0.9 0.25,0.5,1,1.5,2,4,8,12.5,25
+// Columns: sampledMax (random p), climbedMax (hill-climbed from the 256 best samples; the number to quote), secantMax
+// (value differences around the climbed argmax, the check that the analytic gradient is the field's slope),
+// scalarMax (the larger of |grad cosine|, |grad sine| over the samples), p99.99 (the typical tail), and climbed*(1-n)/|side|.
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using CultMath;
+
+// Lipschitz bound of math.phacelle's (cosine, sine) field: sup over p of the operator norm of its 2x3 Jacobian,
+// found by (1) random sampling of the exact analytic gradient, (2) hill-climbing from the top samples over
+// (p, off, side direction), (3) a secant check on the VALUES (|f(p+d) - f(p)| / |d|) so the gradient itself is not trusted.
+static double Op(float3 p, float3 side, float off, float n, out double comp)
+{
+    var r = math.phacelle(p, side, off, n);
+    double a = r.cosine.x*r.cosine.x + r.cosine.y*r.cosine.y + r.cosine.z*r.cosine.z;
+    double d = r.sine.x*r.sine.x + r.sine.y*r.sine.y + r.sine.z*r.sine.z;
+    double b = r.cosine.x*r.sine.x + r.cosine.y*r.sine.y + r.cosine.z*r.sine.z;
+    double tr = a + d, det = a*d - b*b;
+    comp = Math.Sqrt(Math.Max(a, d));
+    var op = Math.Sqrt(tr/2 + Math.Sqrt(Math.Max(0, tr*tr/4 - det)));
+    return double.IsFinite(op) ? op : 0;
+}
+static float3 Dir(double u, double th, double len) { var s = Math.Sqrt(Math.Max(0, 1-u*u)); return new float3((float)(s*Math.Cos(th)*len), (float)(s*Math.Sin(th)*len), (float)(u*len)); }
+
+float[]? norms = null, sides = null;
+try { norms = args.Length == 3 ? args[1].Split(',').Select(float.Parse).ToArray() : null; sides = args.Length == 3 ? args[2].Split(',').Select(float.Parse).ToArray() : null; }
+catch (FormatException) { }
+if (args.Length != 3 || !long.TryParse(args[0], out var N) || N <= 0 || norms is null || sides is null)
+{
+    Console.Error.WriteLine("usage: phacelle-lipschitz <samples per cell> <normalizations> <side lengths>");
+    Console.Error.WriteLine("  e.g. phacelle-lipschitz 4000000 0,0.5,0.75,0.9 0.25,0.5,1,1.5,2,4,8,12.5,25");
+    return 2;
+}
+Console.WriteLine("n\t|side|\tN\tsampledMax\tclimbedMax\tsecantMax\tscalarMax(cos|sin)\tp99.99\tclimbed*(1-n)/|side|");
+foreach (var n in norms) foreach (var sl in sides)
+{
+    int T = Environment.ProcessorCount;
+    var tops = new (double v, float3 p, double u, double th, float off)[T][];
+    var allv = new double[T][]; var scal = new double[T];
+    Parallel.For(0, T, t =>
+    {
+        var rng = new System.Random(unchecked(99991 * t + (int)(n * 1000) * 131 + (int)(sl * 100)));
+        var top = new (double v, float3 p, double u, double th, float off)[16];
+        var list = new double[N / T];
+        double sc = 0;
+        for (long i = 0; i < N / T; i++)
+        {
+            var p = new float3((float)(rng.NextDouble()*64-32), (float)(rng.NextDouble()*64-32), (float)(rng.NextDouble()*64-32));
+            double u = rng.NextDouble()*2-1, th = rng.NextDouble()*Math.PI*2; float off = (float)rng.NextDouble();
+            var v = Op(p, Dir(u, th, sl), off, n, out var c);
+            list[i] = v; if (c > sc) sc = c;
+            int m = 0; for (int k = 1; k < 16; k++) if (top[k].v < top[m].v) m = k;
+            if (v > top[m].v) top[m] = (v, p, u, th, off);
+        }
+        tops[t] = top; allv[t] = list; scal[t] = sc;
+    });
+    var all = allv.SelectMany(x => x).ToArray(); Array.Sort(all);
+    double sampled = all[^1], p9999 = all[(int)(all.Length * 0.9999)];
+    // hill-climb the best 16*T by random local search
+    var seeds = tops.SelectMany(x => x).OrderByDescending(x => x.v).Take(256).ToArray();
+    var climbed = new (double v, float3 p, double u, double th, float off)[seeds.Length];
+    Parallel.For(0, seeds.Length, s =>
+    {
+        var rng = new System.Random(s + 17);
+        var cur = seeds[s]; double step = 0.05;
+        for (int it = 0; it < 10000; it++)
+        {
+            var q = new float3(cur.p.x + (float)((rng.NextDouble()-.5)*step), cur.p.y + (float)((rng.NextDouble()-.5)*step), cur.p.z + (float)((rng.NextDouble()-.5)*step));
+            var u = Math.Clamp(cur.u + (rng.NextDouble()-.5)*step, -1, 1); var th = cur.th + (rng.NextDouble()-.5)*step; var off = cur.off + (float)((rng.NextDouble()-.5)*step);
+            var v = Op(q, Dir(u, th, sl), off, n, out _);
+            if (v > cur.v) cur = (v, q, u, th, off); else if (it % 1000 == 999) step *= 0.5;
+        }
+        climbed[s] = cur;
+    });
+    var best = climbed.OrderByDescending(x => x.v).First();
+    // secant check around the climbed argmax: values only, tiny displacements in random directions
+    double secant = 0; var sr = new System.Random(5);
+    var side0 = Dir(best.u, best.th, sl);
+    for (int i = 0; i < 20000; i++)
+    {
+        double e = Math.Pow(10, -2 - 2*sr.NextDouble()); var d = Dir(sr.NextDouble()*2-1, sr.NextDouble()*6.2832, e);
+        var a = math.phacelle(best.p, side0, best.off, n); var b = math.phacelle(best.p + d, side0, best.off, n);
+        double dc = b.cosine.w - a.cosine.w, ds = b.sine.w - a.sine.w; var dl = Math.Sqrt((double)d.x*d.x + (double)d.y*d.y + (double)d.z*d.z);
+        secant = Math.Max(secant, Math.Sqrt(dc*dc + ds*ds) / dl);
+    }
+    Console.WriteLine($"{n}\t{sl}\t{N}\t{sampled:F3}\t{best.v:F3}\t{secant:F3}\t{scal.Max():F3}\t{p9999:F3}\t{best.v*(1-n)/sl:F3}");
+}
+return 0;

packages/cultmath/tools/phacelle-lipschitz/phacelle-lipschitz.csproj

@@ -0,0 +1,4 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup><OutputType>Exe</OutputType><TargetFramework>net10.0</TargetFramework><Nullable>enable</Nullable><AllowUnsafeBlocks>true</AllowUnsafeBlocks><InvariantGlobalization>true</InvariantGlobalization><ServerGarbageCollector>false</ServerGarbageCollector></PropertyGroup>
+  <ItemGroup><ProjectReference Include="../../src/CultMath/CultMath.csproj" /></ItemGroup>
+</Project>

packages/cultmath/unity/org.gamecult.cultmath/CHANGELOG.md

@@ -7,12 +7,74 @@ backfilled here; see `docs/semver-policy.md` for why.
 
 ## [Unreleased]
 
+### Added
+
+- `math.fbm(float3 p, int octaves, float lacunarity, float gain)` and `math.fbm(float3 p)` (four octaves,
+  lacunarity 2, gain 0.5): the value-only octave sum of `snoise`, the cost of `fbm_grad` without the gradient.
+  The shaders carry `cultmath_fbm` in HLSL and GLSL; octaves clamp to [0, 16] as `fbm_grad`'s do.
+
+## [0.5.0]
+
 ### Breaking
 
 - `CultPhasor.cos` and `.sin` are now `.cosine` and `.sine` in C#, HLSL and GLSL,
   constructor parameters included, because SPIRV-Cross renames members that match
-  GLSL builtins. This is a minor bump on 0.y.z, so the next cultmath-unity release
-  is 0.5.0.
+  GLSL builtins.
+- The `const` `math.SNOISE_HESSIAN` (and `CULTMATH_SNOISE_HESSIAN`) is re-pinned
+  from 56.050385 to 55.642143, measured on the analytic `snoise_hessian` instead of
+  central differences of `snoise_grad`, whose rounding read high
+  (`NoiseBoundTests`). A consumer compiled against 0.4.x keeps the old value
+  inlined until it recompiles. `af_snoise` and `af_fbm` read it, so their
+  remainder terms are slightly tighter.
+
+### Changed
+
+- The package license expression is `MIT AND MPL-2.0 AND Apache-2.0` (was
+  `MIT AND MPL-2.0`): the Cycles files below are Apache-2.0 (`LICENSE.md`,
+  `THIRD-PARTY-NOTICES.md`).
+
+### Added
+
+- Cycles node semantics (Apache-2.0, `math.Cycles.cs` and the new
+  `Shaders/CultMath.Cycles.hlsl`): `math.cycles_*` and `cultmath_cycles_*` compute
+  what Blender's Cycles computes for the Math node operations whose results differ
+  from a plain intrinsic (`cycles_divide`, `cycles_power`, `cycles_modulo`,
+  `cycles_wrap`, `cycles_pingpong`, `cycles_smooth_min`, `cycles_arctan2`, ...),
+  Map Range (`linear`, `stepped`, `smoothstep`, `smootherstep`), Clamp, Mix
+  (`cycles_mix_float`, `cycles_mix_vector` and every colour blend mode as
+  `cycles_mix_<mode>`), RGB to BW, HSV conversion and `cycles_ramp_index`.
+  `CyclesOracleTests` holds the C# and the HLSL mirror to fixtures recorded from
+  Blender 5.2.2's CPU Cycles.
+- `CultMath.Expr`: an immutable scalar SSA expression graph (`ExprGraph`, built by
+  `ExprBuilder` with substitution, validated by `ExprGraph.Create` on build and on
+  decode), parameter bindings (`ExprBindings`), an evaluator (`ExprEvaluator`) and
+  the op table (`ExprOps`). The package carries no serializer for it.
+- Site cells: `math.power_score`, `multiplicative_score`, the `CultSiteCells`
+  accumulator (`site_cells_empty`, `site_cells_insert`, `site_cells_border`), the
+  exact power cell border (`power_border`, `power_border_step`) and
+  `gabriel_margin`, each with an HLSL twin (`cultmath_` prefix); the shader
+  `cultmath_power_border` takes a fixed-capacity site array of
+  `CULTMATH_MAX_SITES` (128 unless defined before the include). `power_cells`,
+  `multiplicative_cells` and `soft_gabriel_gate` are C# only.
+- Weighted lattice cells: `math.weighted_lattice_cells` with an exact ring-exit
+  search and its four public steps (`lattice_site`, `lattice_weight`,
+  `lattice_distance`, `lattice_smooth_step`), the range constants
+  `LatticeMaxBoost`, `LatticeMaxStretch`, `LatticeMaxSmoothing` and
+  `LatticeMaxRing`, and the HLSL twins (`cultmath_weighted_lattice_cells`,
+  `cultmath_lattice_cell_distance`).
+- Span stages: `math.span_fbm` and `span_ridged` over a `SpanPath` and a
+  `SpanStage` return `SpanNoise` (field, curvature and fold), widened by float
+  rounding allowances, with HLSL twins; `cultmath_span_rounding` and
+  `cultmath_span_slack` own the allowances.
+- `math.snoise_hessian(float3)` (`float3x3`), the next-order bound
+  `SNOISE_THIRD` (535.8009), and the snoise read rounding constants
+  `CULTMATH_SNOISE_READ_VALUE` and `CULTMATH_SNOISE_READ_GRADIENT` in HLSL.
+- `math.integral_clamp_linear(a, b, lo, hi, t0, t1)`, the integral of
+  `clamp(a + b t, lo, hi)` over `[t0, t1]` in closed form, with its HLSL twin. It
+  is finite for an infinite clamp bound, and `lo` above `hi` clamps to `hi`
+  everywhere, as `clamp` does.
+- `math.segment_closest` and the out-free `distance_to_segment` for `float2`
+  and `float3`, with HLSL twins.
 
 ## [0.4.1]