Python: a payload is one MessagePack value (bytes-after-py) (#129)

The native QUIC bridge DLL is not restaged: its source is unchanged since 2.0.1 and the rebuild is not byte-stable.

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

.github/workflows/cultmesh-portability.yml

@@ -1,50 +1,121 @@
 name: CultMesh portability and performance
 
+# The forge runs one job at a time and this workflow holds the slot 14 to 30 minutes, so it runs once per change:
+# on the pull request (never again on the push that merges it; a break that merges from a stale base waits for the
+# schedule), skipped for design-note-only changes, and on a
+# daily schedule so main is still exercised when nobody opens a pull request.
 on:
-  push:
-    branches:
-      - main
-      - "codex/**"
   pull_request:
+    paths-ignore:
+      # Not `**/*.md` or `docs/**`: docs/start/README.md is read by the first-call tests of every runtime.
+      - "docs/*.md"
+      - "research/**"
+      - ".voidbot/**"
+  schedule:
+    - cron: "17 3 * * *"
   workflow_dispatch:
 
+concurrency:
+  # A newer push or PR update replaces the older run on the same ref. Tag pushes and
+  # workflow_dispatch runs are never cancelled: a tag run carries a release.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')) }}
+
 jobs:
   reactive-and-resource-lifetime:
     name: ${{ matrix.os }} reactive semantics and leases
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
+    # The job dies at the lower of this value and the forge runner's own cap, which Eureka is raising from 30 to 60 minutes
+    # (run 1378 carried 60 and was still cancelled at 30:02); the two must both say 60 before a full run can finish.
+    timeout-minutes: 60
     strategy:
       fail-fast: false
       matrix:
-        # The forge runner is Ubuntu-only: Windows legs run on workflow_dispatch (GitHub or a Windows runner), Ubuntu gates push and PR.
+        # The forge runner (label `ubuntu-latest`) is Linux-only and no Windows runner exists: the Windows leg runs on workflow_dispatch only (GitHub or a Windows runner), the ubuntu-latest leg gates push and PR. Windows push/PR triggers return in the PR that registers a Windows runner.
         os: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '["windows-latest", "ubuntu-latest"]' || '["ubuntu-latest"]') }}
 
     steps:
       - name: Check out CultLib
         uses: actions/checkout@v4
+        with:
+          # The declared-dependency-range test builds the admitted releases from their tags.
+          fetch-depth: 0
+          fetch-tags: true
 
       - name: Set up .NET
         uses: actions/setup-dotnet@v4
         with:
           dotnet-version: 10.0.x
 
+      # The forge runner image (catthehacker/ubuntu:act-latest) carries Node 24 and Python 3.12 on PATH, and these two
+      # setup actions downloaded them again from github.com anyway (about 2.7 and 2.8 minutes, run 639) because the
+      # image's tool cache is not the one they read. They run only where the image does not carry the tools (the
+      # workflow_dispatch Windows leg); the check below fails a Linux image that stops carrying them.
       - name: Set up Node.js
+        if: runner.os != 'Linux'
         uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: npm
 
       - name: Set up Python
+        if: runner.os != 'Linux'
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
+      - name: Check the image carries Node 24 and Python 3.12
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          node --version | grep -E '^v24\.'
+          python --version | grep -E '^Python 3\.12\.'
+
+      # The image's Python is distro-managed (PEP 668): pip refuses to install into it, so the Linux leg installs the
+      # CultLib packages into a venv under RUNNER_TEMP that later steps find first on PATH.
+      - name: Create the Python environment
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m venv "$RUNNER_TEMP/venv"
+          echo "$RUNNER_TEMP/venv/bin" >> "$GITHUB_PATH"
+
       - name: Install TypeScript workspace dependencies
         run: npm install --no-package-lock
 
       - name: Install Python CultLib packages
         run: python -m pip install -e packages/cultcache-py -e packages/cultnet-py -e packages/cultmesh-py
 
+      # The forge runner images carry no cargo either (the cross-runtime store tests build the Rust interop example); GitHub's hosted images do.
+      - name: Install Rust toolchain
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          if ! command -v cargo >/dev/null && [ ! -x "$HOME/.cargo/bin/cargo" ]; then
+            curl -fsSL https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
+          fi
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      # The forge runner images carry no pwsh; GitHub's Windows and hosted images do.
+      - name: Install PowerShell
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          if command -v pwsh >/dev/null; then pwsh -Version; exit 0; fi
+          SUDO=""; [ "$(id -u)" -eq 0 ] || SUDO="sudo"
+          PWSH_VERSION=7.4.6
+          curl -fsSL "https://github.com/PowerShell/PowerShell/releases/download/v${PWSH_VERSION}/powershell-${PWSH_VERSION}-linux-x64.tar.gz" -o "${RUNNER_TEMP:-/tmp}/powershell.tar.gz"
+          $SUDO mkdir -p /opt/microsoft/powershell/7
+          $SUDO tar -xzf "${RUNNER_TEMP:-/tmp}/powershell.tar.gz" -C /opt/microsoft/powershell/7
+          $SUDO chmod +x /opt/microsoft/powershell/7/pwsh
+          $SUDO ln -sf /opt/microsoft/powershell/7/pwsh /usr/local/bin/pwsh
+          echo "DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1" >> "$GITHUB_ENV"
+          DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 pwsh -Version
+
       - name: Verify explicit reactive scheduling across runtimes
         shell: pwsh
         run: ./scripts/verify-reactive-document-scaling.ps1
@@ -60,8 +131,8 @@ jobs:
           --logger "console;verbosity=minimal"
 
       # The TypeScript side of the CultMesh authority rules. This job is the
-      # only one that runs on both Windows and Linux for main, codex/** and
-      # pull requests: cultnet-interop.yml is windows-latest and main-only, so
+      # only one that runs on Linux for main, codex/** and pull requests (and on
+      # Windows too under workflow_dispatch): cultnet-interop.yml is windows-latest and dispatch-only, so
       # until these steps existed the shared verifier's tests never ran on
       # Linux at all, and the browser client's never ran in CI on any OS.
       # packages/cultnet-ts verifies both vector files (content.test.ts judges both
@@ -77,6 +148,26 @@ jobs:
       - name: Verify the CultCache document owner with the TypeScript cache
         run: npm run test --workspace packages/cultcache-ts
 
+      # The Python cache's unit suite ran only in cultnet-interop.yml (windows-latest, dispatch-only), so on Linux
+      # it ran nowhere. It sits after the TypeScript cache's test so the built cultcache-ts store holder exists for the
+      # cross-runtime store-lock test, which skips without it.
+      - name: Verify the CultCache document owner with the Python cache
+        run: python -m unittest discover -s packages/cultcache-py/tests
+
+      # cargo test for packages/cultcache-rs ran in no workflow: the Rust cache's own unit and doc tests were unwatched
+      # (only the interop example built, inside the C# store tests). The target directory is under RUNNER_TEMP, away from the checkout.
+      - name: Verify the CultCache document owner with the Rust cache
+        shell: bash
+        run: CARGO_TARGET_DIR="$RUNNER_TEMP/cultcache-rs-target" cargo test --manifest-path packages/cultcache-rs/Cargo.toml
+
+      # tests/GameCult.Caching.Tests, the C# reference cache's own suite (about 1,260 tests, under a minute), ran in no
+      # forge workflow; only the Mesh tests above exercised the reference.
+      # The forge runner is globalization-invariant, so ADeterministicIdIsTheSameUnderEveryCulture... cannot construct a
+      # culture and throws CultureNotFoundException; it is excluded here and still runs wherever ICU is present
+      # (variants:follow_up:culture-test-invariant-image).
+      - name: Verify the CultCache document owner with the C# reference
+        run: dotnet test tests/GameCult.Caching.Tests/GameCult.Caching.Tests.csproj --filter "FullyQualifiedName!~ADeterministicIdIsTheSameUnderEveryCulture" --logger "console;verbosity=minimal"
+
       # Packs the four TypeScript packages and installs them into a clean consumer, so a package that builds but does
       # not install or load fails here.
       - name: Verify the packed TypeScript packages install and load from a clean consumer

.github/workflows/cultnet-interop.yml

@@ -1,7 +1,7 @@
 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.
+# runner is Ubuntu-only (no Windows runner exists; push and pull_request return in the PR that registers one), so a push or pull_request trigger would queue a job that can never run.
 # Run it from GitHub or any Windows runner.
 on:
   workflow_dispatch:

.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*"

.github/workflows/quic-native.yml

@@ -9,15 +9,29 @@ name: CultMesh QUIC native
 # from the pinned debian:13 container below, never from a local or Yggdrasil
 # build.
 
+# Only a change to the committed binaries, their manifest or this workflow can change what verify-committed checks,
+# so a branch push or pull request runs it for those paths alone; a tag always runs it.
 on:
   push:
     branches:
       - main
+    paths:
+      - "packages/cultmesh-ts/native/**"
+      - ".github/workflows/quic-native.yml"
     tags:
       - "cultmesh-quic-native-v*"
   pull_request:
+    paths:
+      - "packages/cultmesh-ts/native/**"
+      - ".github/workflows/quic-native.yml"
   workflow_dispatch:
 
+concurrency:
+  # A newer push or PR update replaces the older run on the same ref. Tag pushes and
+  # workflow_dispatch runs are never cancelled: a tag run carries a release.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')) }}
+
 permissions:
   contents: read
 
@@ -49,11 +63,12 @@ jobs:
 
   # workflow_dispatch and a cultmesh-quic-native-v* tag run the two builds.
   # A dry (workflow_dispatch) run uploads artifacts and creates no release.
+  # No Windows runner is registered on the forge, so this job is workflow_dispatch only
+  # (run it on GitHub or a Windows runner). The tag trigger returns in the PR that registers one.
+  # Until then a tag push skips the release job, which needs this build.
   build-win32-x64:
     name: Build win32-x64
-    if: >-
-      github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/cultmesh-quic-native-v'))
+    if: github.event_name == 'workflow_dispatch'
     runs-on: windows-latest
     timeout-minutes: 20
     steps:
@@ -92,8 +107,8 @@ jobs:
     runs-on: ubuntu-latest
     # Q6 A: this pinned Debian 13 container is the only permitted Linux
     # release builder. The digest is the pin; the `debian:13` tag is only a
-    # label. The artifact links against this image's glibc (2.41); a bare
-    # ubuntu-latest runner carries glibc 2.39, which is not the deploy host's
+    # label. The artifact links against this image's glibc (2.41);
+    # a bare runner's OS image has its own glibc (a GitHub ubuntu-latest image carried 2.39), which is not the deploy host's
     # OS (docs/typescript-quic-realtime-cut.md:2192-2197).
     container:
       image: debian:13@sha256:f324c7ff54321e8d9c588493a20244965938ce0aa50bbd1022d38010e9ffc4b1

contracts/cultmesh/content-acceptance-vectors.json

@@ -899,23 +899,23 @@
     {
       "label": "trailing_nil",
       "inputBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRlNlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWuRoXiBoWuhdsA=",
-      "accepted": true,
-      "reencodedBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRldlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWugkaF4gaFroXY=",
-      "recordKey": "mesh:cdn:artifact:a-b:1:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      "accepted": false,
+      "reencodedBase64": null,
+      "recordKey": null
     },
     {
       "label": "trailing_reserved_code",
       "inputBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRlNlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWuRoXiBoWuhdsE=",
-      "accepted": true,
-      "reencodedBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRldlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWugkaF4gaFroXY=",
-      "recordKey": "mesh:cdn:artifact:a-b:1:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      "accepted": false,
+      "reencodedBase64": null,
+      "recordKey": null
     },
     {
       "label": "trailing_truncated_array",
       "inputBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRlNlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWuRoXiBoWuhdpI=",
-      "accepted": true,
-      "reencodedBase64": "mqNhL2KlYXNzZXShMdlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQCvYXBwbGljYXRpb24veC10oXSRldlAZTNiMGM0NDI5OGZjMWMxNDlhZmJmNGM4OTk2ZmI5MjQyN2FlNDFlNDY0OWI5MzRjYTQ5NTk5MWI3ODUyYjg1NQAAoWugkaF4gaFroXY=",
-      "recordKey": "mesh:cdn:artifact:a-b:1:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      "accepted": false,
+      "reencodedBase64": null,
+      "recordKey": null
     },
     {
       "label": "top_nil",

contracts/cultnet/cultnet-distributed-database.md

@@ -114,7 +114,10 @@ copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and
 `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).
+`unsupported_schema_version` (a message whose `schemaVersion` the peer does not speak; `details` names `schemaVersion` and the offered value) and
+`limit_reached` (a receipt-capable server's per-session remembered-write table is full, so a new write is refused; `details` all null) and
+`message_invalid` (a request that lacks a required field or carries an ill-typed one: a document-put or delete, or a subscription without an id; `details.field` names the request field, or `message` when the whole frame cannot be read).
+A malformed put or delete is `message_invalid`, not a per-operation code: the peer knows which operation it sent.
 
 ## Live Invariants
 
@@ -137,6 +140,15 @@ copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and
 - A shard snapshot represents a log sequence. Applying it replaces the local
   shard view and advances the replica cursor to that sequence.
 - Realtime subscriptions publish domain changes, not storage envelopes.
+- A subscription's `database_change_raw` messages may carry `commitId` and `commitCount`: the changes of one cache
+  commit that this subscription delivers (`commitCount` of them, at least two). Both fields are optional and additive; a
+  peer that does not know them ignores them and applies each change alone. A replica that knows them applies the
+  commit's changes as one commit, so the replica judges the result (a swap of two unique-index values) and not the state
+  between records. A replica whose cache refuses a commit is faulted, never silent. `commitId` is opaque and valid only
+  within the subscription. The C# subscription server and database server tag commits; other runtimes adopt next.
+- The C# writer sets every key of a `database_change_raw` message, nil where unset: a removed change carries `document`
+  nil, an added or updated one `recordKey` and `schemaId` nil. The schema accepts those nils; an added or updated change
+  still needs a document, and a removed one a `recordKey` and `schemaId`.
 - Client-owned input documents may be predicted locally only inside explicit
   `CultNetClientAuthorityScope` declarations.
 - Predicted input state is not authoritative shared state. The shard log still

contracts/cultnet/cultnet.database-change-raw.schema.json

@@ -10,15 +10,29 @@
     "messageId": { "type": "string", "minLength": 1 },
     "subscriptionId": { "type": "string", "minLength": 1 },
     "changeKind": { "enum": ["added", "updated", "removed"] },
-    "document": { "$ref": "./cultnet.raw-document-record.schema.json" },
-    "recordKey": { "type": "string", "minLength": 1 },
-    "schemaId": { "type": "string", "minLength": 1 }
+    "document": {
+      "oneOf": [{ "type": "null" }, { "$ref": "./cultnet.raw-document-record.schema.json" }]
+    },
+    "recordKey": { "type": ["string", "null"], "minLength": 1 },
+    "schemaId": { "type": ["string", "null"], "minLength": 1 },
+    "commitId": { "type": ["string", "null"], "minLength": 1 },
+    "commitCount": { "type": ["integer", "null"], "minimum": 2 }
   },
-  "allOf": [
+  "oneOf": [
     {
-      "if": { "properties": { "changeKind": { "const": "removed" } } },
-      "then": { "required": ["recordKey", "schemaId"] },
-      "else": { "required": ["document"] }
+      "properties": {
+        "changeKind": { "const": "removed" },
+        "recordKey": { "type": "string" },
+        "schemaId": { "type": "string" }
+      },
+      "required": ["recordKey", "schemaId"]
+    },
+    {
+      "properties": {
+        "changeKind": { "enum": ["added", "updated"] },
+        "document": { "$ref": "./cultnet.raw-document-record.schema.json" }
+      },
+      "required": ["document"]
     }
   ]
 }

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", "write_not_authorized", "unsupported_schema_version"]
+      "enum": [null, "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported", "unowned_schema", "write_not_authorized", "unsupported_schema_version", "message_invalid"]
     },
     "details": {
       "description": "Code-specific structured detail (R-N). Every field is populated only for the code that defines it; the others are null, not omitted.",
@@ -36,7 +36,7 @@
       "additionalProperties": false,
       "required": ["field", "value", "asOf", "current"],
       "properties": {
-        "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\". unsupported_schema_version: \"schemaVersion\".", "type": ["string", "null"] },
+        "field": { "description": "selection_invalid: the selection field that failed. variant_unsupported: \"subscriptionId\", when a subscription was ended. unowned_schema: \"schemaId\". write_not_authorized: \"recordKey\". unsupported_schema_version: \"schemaVersion\". message_invalid: the request field that is missing or ill-typed (\"message\" when the whole frame cannot be read).", "type": ["string", "null"] },
         "value": { "description": "selection_invalid: the offending value, when there is one string worth naming. variant_unsupported: the id of the subscription that ended. unowned_schema: the schema id no shard owns. write_not_authorized: the key of the refused write. unsupported_schema_version: the schemaVersion the peer does not speak.", "type": ["string", "null"] },
         "asOf": { "description": "cursor_stale: the cursor's own minted asOf.", "type": ["integer", "null"], "minimum": 0 },
         "current": { "description": "cursor_stale: the answering server's current asOf.", "type": ["integer", "null"], "minimum": 0 }

contracts/cultnet/governance/fork-card.md

@@ -0,0 +1,206 @@
+# CultNet fork-desk contract v0 (specification)
+
+Status: specification, drafted for Heimdall (Bifrost receiver), Huginn (the second door) and Void (Ratatoskr desk). No runtime implements it yet.
+Rule source: `/opt/commons/handoff/fork-desk-answer-binding-20261110.md` (Heimdall; sections 1.1 to 1.5, 1.3a to 1.3d), amended by the Persona briefs of 2026-11-10 (Eureka's fit check). Where this page differs from that file it says so under "Differences from the binding file".
+Format source: the fork desk artifact in `/opt/commons/handoff/fork-desk-original/` (ruling `eureka-substrate:ruling:fork-desk-nibu-format`).
+Files here: `fork-card.schema.json` (one schema, a `$defs` entry per document), `fork-card-vectors.json`. Conformance: `tests/GameCult.Networking.Tests/GovernanceVectorTests.cs` (C#) and `packages/cultnet-ts/test/governance-vectors.test.ts` (TypeScript), both generated against vectors written by `scripts/gen-governance-vectors.py`. Each suite computes every hash with its own code and replays every scenario through a reference judge written from this page.
+
+All documents are CultNet map-mode: every key written, nil where absent, closed schemas. Field names are snake_case as in the binding file and the mind's records; `schemaVersion` keeps CultNet's spelling (open choice 1). The bytes of every document are pinned in the vectors as `messagePackHex`.
+
+## Documents
+
+| schema id | what | who writes it |
+|---|---|---|
+| `gamecult.fork.card.v0` | the fork as shown | the publisher (a Mind's card projection) |
+| `gamecult.fork.answer_request.v0` | the answer a decider sends | the client; Bifrost forwards it unchanged to Huginn's second door |
+| `gamecult.desk_answer.v0` | the stored answer with one tagged outcome | Huginn only |
+| `gamecult.fork.answer_result.v0` | what the sender gets back for a stored answer | Bifrost, from the stored `desk_answer` |
+| `gamecult.fork.refusal.v0` | a body refused at the door, nothing stored (but `fork_too_large` on a stale answer, which sits over a stored `Refused(stale_fork)`) | Bifrost |
+| `gamecult.fork.record.v0` | a fork's answers plus the derived counted answer | a projection of the stored `desk_answer`s |
+| `gamecult.fork.ruling_cite.v0` | the citation a ruling carries | the Mind admitting the ruling |
+| `gamecult.fork.list_request.v0` | list a Mind's forks (Transport) | the desk |
+| `gamecult.fork.list.v0` | a page of entries, counts and a stamp | Bifrost, projected from Huginn |
+| `gamecult.fork.read_request.v0` | read one fork (Transport) | the desk |
+| `gamecult.fork.entry.v0` | one card with its record | Bifrost, projected from Huginn |
+| `gamecult.fork.unavailable.v0` | the outcome is not confirmed (the second door or Huginn did not answer); retry with the same `request_id` | Bifrost |
+
+### card
+
+`{schemaVersion, fork_id, title, context, options[{id, text}], recommendation, depends[], leans, flag, raised_in, raised_at, deciders[], decider_count, status, ruling, ruled_from[], order, options_hash}`.
+
+- `fork_id`: the mind's `question` key, `<campaign>:question:<label>`.
+- **Hashed (the shown members):** `title`, `context`, `options` (each `{id, text}`, in shown order), `recommendation` (an option id, **never nil**: the stored `question` requires `recommended`), `depends` (strings, each one of the stored question's `depends` lines verbatim, at most 8, each at most 1000 UTF-8 bytes (the stored `Line`), in shown order, empty when none; the stored kind holds prose lines, so a line may read like a reference such as `campaign:kind:label` but is hashed as the text it is).
+- **Not hashed:** `fork_id` (bound beside the hash), `leans` (an option id or nil), `flag`, `raised_in`, `raised_at` (the instant the question was first admitted, an RFC3339 instant string as `answered_at`, or nil when the mind holds no admission time, as for a card projected before the field; the key is always written; it never moves when the question is edited; age is the client's: now minus `raised_at`), `deciders`, `decider_count` (the number of deciders of the call, set beside `deciders`; neither it nor the emptiness of `deciders` enters the hash, so the hash a non-decider recomputes is a decider's), `status` (`open` or `closed`), `ruling` (the ruling id when a ruling closed the fork; nil when the card is open, and nil on a closed card whose question was withdrawn or otherwise resolved with no ruling), `ruled_from` (answer ids a ruling has been admitted from; non-empty only on a closed card), `order`, and `options_hash` itself.
+- **`deciders` is read-only data.** The list is set outside the Mind, through Bifrost's admin path, and **Bifrost sends it per call**: Huginn keeps no copy (M5). The card projection copies the list the call carried. **The per-call list holds one to 64 ids** (Huginn's bound; vectors `deciders_at_the_cap_of_64`, `deciders_65`); the per-call list has no schema here, so the bound is stated for the cut that builds it. **`decider_count` is the size of that list, an integer 1 to 64, always written** (vectors `decider_count_missing`, `_zero`, `_65`, `_string`, `_null`). A fork with no decider is still refused, now as `decider_count` 0. **`deciders` holds that list for a decider and is empty for a reader who is not one: empty means "the ids are withheld from this reader", never "no deciders"** (vector `withheld_deciders`). Rule R-card: when `deciders` is non-empty it holds exactly `decider_count` ids; a visible list is whole (vectors `decider_count_fewer_than_the_ids`, `decider_count_more_than_the_ids_shown`). A question's own `audience` may only narrow it. A Mind never writes it, so a Mind cannot add itself and answer its own fork.
+- Rules a schema cannot say, each with a negative vector: a `depends` line is at most 1000 UTF-8 bytes (the schema bounds 8 lines and 1000 characters; bytes need the rule); option ids are unique; `order` is unique among a Mind's cards (a list with two cards on one `order` is refused, naming both fork ids); `recommendation` and `leans` name an option; deciders are unique; an open card names no `ruling` and its `ruled_from` is empty (a ruling that answers a fork closes it); `ruled_from` is non-empty only when `ruling` is set; a closed card may name no ruling (the question was withdrawn, superseded or deferred: step 6 reads `status`, not the ruling); `options_hash` equals the hash of the shown members; R-card (above); R-answer-result: `answer_result.answer.answerer` is never nil, being the sender's own stamped account (vector `answer_result_with_a_nil_answerer`); R-record, R-entry and R-list ("Reader views" below).
+
+**Reader views.** A card and its record are shown in one of two views. The **decider view** carries the ids: `deciders` whole, every `answerer` named, and the counts equal to the ids. The **non-decider view** withholds them: `deciders` empty, every `answerer` nil, the counts kept (`decider_count`; `answerer_count` on the record). Who is a decider is Huginn's decision, not this contract's: a reader is a decider exactly when the call's subject is byte-equal to one of the call's deciders (`eureka-substrate:ruling:desk-read-visibility-withheld-ids`); Huginn's door withholds, Bifrost cannot (the card is opaque to it). There is no viewer flag on any document: the view is read off whether `deciders` is empty. This contract carries both views and refuses a view that leaks: R-record: if every `answerer` is named, `answerer_count` is the number of distinct ids; if all are nil and there is at least one answer, `answerer_count` is between 1 and the number of answers; with no answers it is 0 (vectors `answerer_count_disagrees_with_the_ids`, `answerer_count_counts_answers_not_people`, `withheld_count_over_the_answers`, `withheld_count_zero_over_answers`, `withheld_count_over_no_answers`); R-entry, the leak rule: an entry with `deciders` non-empty names every answerer, an entry with `deciders` empty names none (vectors `decider_card_with_withheld_answers`, `withheld_card_with_named_answers`, `withheld_card_with_a_named_answerer_among_nils`); R-list: all entries of one page agree on the view (vector `a_page_mixes_views`). The view does not move the page: `non_decider_page` has the counts, order, cursor and stamp of the decider page it twins, and the vectors' no-leak check finds no id string in a non-decider vector's bytes. `options_hash` is the same in both views, and the bound-answer and `stale_fork` machinery is untouched.
+
+### Options hash (canonical bytes)
+
+`options_hash` = lowercase hex SHA-256 of the UTF-8 bytes of the following, byte for byte:
+
+1. Build an object with exactly the five members `title`, `context`, `options`, `recommendation`, `depends`. Each option is an object with exactly `id` and `text`.
+2. **NFC-normalise every string, object keys included.** No trimming, no newline rewriting, no case folding. A string with a lone surrogate is not a card (it has no UTF-8). Normalisation stability makes NFC stable across Unicode versions for already-assigned code points; a runtime's own normaliser is trusted and the vectors include a decomposed pair and astral code points (open choice 2).
+3. Serialise as RFC 8785 (JCS): no whitespace; object keys sorted by UTF-16 code unit, which for these ASCII keys is `context, depends, options, recommendation, title` and, inside an option, `id, text`; array order is as shown (option order and `depends` order are part of the hash).
+4. Strings are written in double quotes; only `"` and `\` are backslash-escaped, U+0008, U+0009, U+000A, U+000C, U+000D as `\b \t \n \f \r`, every other code point below U+0020 as `\u00xx` in lowercase hex; everything else is written raw as UTF-8 (U+007F, U+2028, `<`, `&` and astral code points included).
+5. **Numbers and nulls:** the member set contains none. There is no number to canonicalise (a number anywhere in the five members is a defect) and `recommendation` is never nil, so no nil is hashed.
+
+`fork_id` is not in the hash and is bound beside it in its own field, so one hash cannot be replayed under another fork. The publisher computes the hash and stores it in the card; the client recomputes it from what it rendered and refuses to send on a mismatch; the receiver recomputes from its stored fork, never from the client.
+
+Vectors `optionsHash`: the seven of the binding file (`heimdall_A..G`), computed by the Python generator, by the C# suite and by the TypeScript suite independently, plus text, title, context and `depends`-order mutations, a case showing the unshown members do not move the hash, escapes and markup, and astral ids. Each suite also mutates every shown member, an option id included, and asserts the hash changes.
+
+### answer_request
+
+`{schemaVersion, fork_id, options_hash, answer, retracted, retracts, answered_at, request_id}`. **`request_id`** is set by the client, a lowercase D-format UUID, one per intended answer, kept across retries; the first stored answer that carries it binds it to the stamped `answerer`. "Same body" means every field equal, `answered_at` included, so a client resends identical bytes. A **retry with the same `request_id` and the same body returns the stored outcome unchanged** (a `Refused` one included; a replayed `stale_fork` carries the **current** card, because a stored `desk_answer` has no card field and no storage is added for one) and **never adds a Revision**; the same `request_id` with a different body is `request_id_conflict` (409, a refusal, nothing stored). The same id from another account is another request, judged on its own: Y reusing X's `request_id` with a body identical to X's gets **Y's own new answer, with its own answer id, stamped Y**; X's stored outcome (a `Refused` one included) is never returned in its place, and Y's request neither conflicts with it nor replays it. An `of` that names the counted answer is allowed, because answer ids are not secret between deciders (vectors V14: an off-list X's `Refused`, then a decider Y's identical body is its own `Counted`; X's `Counted`, then Y's identical body is its own `Revision` whose `of` names X's answer, and X's later retry still returns X's answer). Both suites assert it on every scenario: a response's `answerer` is the step's account, and an id first bound by another account never yields that account's answer id or document. **`retracted` is part of the body**: the same `request_id` with `retracted: true` and then `false` (or the reverse) and every other field equal is `request_id_conflict`, for the illegal forms as for any other (vectors `R1_retracted_true_then_false_...`, `R1_retracted_false_then_true_...`). Each illegal form's own retry, byte for byte, replays its stored `bad_retraction` (vectors `R1_a_retraction_with_an_answer_...`, `R1_a_retraction_with_no_target_...`, `R1_a_plain_answer_with_a_target_...`). A body refused at step 1 or 2 binds nothing, so its id is free to reuse; so a target-less retraction resent with `retracted: false` (no answer, no retraction) is `body_invalid` at step 2, not a conflict. The lookup comes after steps 1 and 2 and before the fork is looked up, so a retry gets its stored outcome even if the card has since changed. `answer` is `{choice, note}` (at least one non-nil) or nil on a retraction. `choice` is an option id; `note` is the person's words, verbatim, 1 to 4000 **UTF-8 bytes**, not blank. A schema counts characters, not bytes, so its `maxLength: 4000` (code points) is only the looser bound and both suites enforce the byte limit as a rule: 4000 ASCII bytes pass; 1000 astral characters (4000 bytes) pass and 1001 (4004) fail; `e` plus a combining acute is 3 bytes, so 1333 of them and an `x` pass and 1334 fail; 1999 two-byte characters plus three ASCII (4001 bytes) fail. A note over the limit is `body_invalid`. `answered_at` is the client's claim. **A request never carries `answerer` or `authority`**: both are stamped by Huginn (`answerer` from the verified subject the receiver passes; `authority` from the door's configuration). A body that names either key at any depth is refused whole, never stripped (`body_forbidden_field`); any other unknown key is `body_unknown_field`. The request type Bifrost sends over the second door is this document; it has no field for either key, so a client cannot supply them by construction, and Bifrost's scan is the first line, not the only one. How Huginn receives the verified subject is the door's authenticated context, not a body field (open choice 3). In map-mode `retracted` is always written (the binding file's optional `retracted` becomes `false`).
+
+### desk_answer (the stored kind)
+
+`{schemaVersion, answer_id, fork_id, outcome, of, retracts, code, options_hash, choice, note, answered_at, received_at, claim_in_future, answerer, authority, request_id}`, key `<campaign>:desk_answer:<question-label>.n<seq>`; `answer_id` is `n<seq>`, assigned by Huginn per question, and **an answer is named by its answer id** everywhere (`retracts`, `of`, `ruled_from`).
+
+The stamped `authority` field of a stored answer is an **attribution**: the role the verified account holds (`Operator`, `Steward`, `Member`), copied from Bifrost's state. A stored answer confers no authority. Authority exists only where a ruling cites a counted answer ("Operator authority" below); the field keeps the binding file's spelling (open choice 8). One tagged `outcome`, each variant carrying only its own link:
+
+- `Counted`: the answer that counts. `of`, `retracts`, `code` nil.
+- `Revision`: a later passing answer, kept, not counted while the first stands. `of` names the counted answer at the time.
+- `Retraction`: the stored form of `retracted: true` plus `retracts`. `retracts` names the answer retracted; `choice` and `note` nil. The illegal pair (a retraction with no target, or a target with no retraction) cannot be written.
+- `Refused`: any refusal from steps 4 to 7 or R1 and R2, with its `code`, stored too. `choice` and `note` keep what the body carried, and so does `retracts`: a refused body that named a target (a retraction of any refusal code, or a plain answer carrying one) projects it as `n<seq>`, never nil; a refused body that named none has `retracts` nil. `of` is nil.
+
+`received_at` is Huginn's admission time; "first" means first by admission order (the `n<seq>` ordinal), never by `answered_at`. `claim_in_future` is true when `answered_at` is more than five minutes after `received_at`: accepted but flagged. It is a function of the two stored values, so the writer compares against the `received_at` it stores, at the precision it stores it (a flag decided against an unrounded clock and a stored second-truncated `received_at` disagrees with the document it sits in). **Not stored, and no answer id:** a body refused at step 1 or 2 (Bifrost; it never reaches Huginn), and a body naming an unknown fork (step 3; Huginn answers it from its stored forks, but with no question there is nothing to key a record under). Each gets a `refusal` and is dropped. A malformed body is therefore never stored, and neither is an unknown fork. Every refusal from step 4 on is stored. **`unavailable`** (503) is not a refusal and not in the refusal set: Bifrost answers it when the second door or Huginn did not answer after the auth steps and the body shape passed (a bad body is still refused first). **It says the outcome is NOT CONFIRMED, never that nothing was stored**: a timeout after the request reached Huginn may have stored it. It carries no answer id. The desk retries the same request with the same `request_id` and learns the outcome: the stored one if Huginn had it, a fresh one if not. It covers **calls 1 and 2 as well as the answer POST** when Huginn cannot be reached (Transport; a read has no outcome to confirm, so a retry is plain). `retryAfterSeconds` is nil when Bifrost has no hint.
+
+**The record.** `record` is `{schemaVersion, fork_id, options_hash, counted_answer_id, answerer_count, answers[]}`. `answerer_count` is an integer of at least 0: the number of distinct answerer ids over every stored answer of the fork, refusals included (a refusal stores the stamped answerer too), and it is the same number in both views (vectors `answerer_count_missing`, `_negative`, `_null`). `answers[].answerer` is a string or nil (nil only in the non-decider view).
+
+**The mind's record and this document.** Huginn keeps the answer as its own record kind (`epiphany.pipeline.desk_answer.v2`, key `<campaign>:desk_answer:<question-label>.n<seq>`, the outcome as one externally tagged value, the fork as `fork`). The second door projects it to this document and nothing else crosses: `answer_id` is the key's `n<seq>` part, `fork_id` is the stored `fork`, the tagged outcome flattens into `outcome`, `of`, `retracts` and `code`, and the six refusal codes are spelt as in the schema (snake_case; the record's enum spells them in the mind's own PascalCase). On the wire an answer is named by its `n<seq>` alone, always inside the fork whose `fork_id` the document carries; a runtime that holds the full record key converts at the door, in one place. Huginn's stored `desk_answer` keeps a non-nil `answerer`; nil exists only in a record projected to a non-decider. `body_sha256` and any other digest Huginn keeps to decide "same body" stay in the record: Huginn alone decides a replay or a `request_id_conflict` and Bifrost never compares bodies, so no digest is a field of this document. A digest is a valid way to decide it only if it covers `fork_id`, `options_hash`, `answer.choice`, `answer.note`, `retracted`, `retracts` and `answered_at` (every field of the request but `request_id`), is computed by Huginn and never read from a client.
+
+**Huginn's digest, pinned in the vectors (`bodyDigests`; informative, not a wire document).** SHA-256 of one compact JSON object as `serde_json::to_string` writes it (UTF-8, no spaces), lowercase hex, keys in this order, `null` for a missing value, strings verbatim: `fork`, `options_hash`, `answered_at`, `choice`, `note`, `retracts` (the **full stored key** `<campaign>:desk_answer:<label>.n<seq>`: the door converts the wire's `n<seq>` before the digest), then, **only for the three illegal forms** (R1: a retraction carrying an answer, a retraction naming no target, a plain answer carrying a target), `illegal_retraction: true` and `retracted: true|false`. `request_id` is not in it. A plain answer and a legal retraction carry neither trailing key, so their digests are the ones Huginn main pins (`8a4d5b2e`, `9f807538`) and do not move. `9f807538` is pinned for a target no door produces (`Q1.1`); the golden for the real legal retraction is the door's form, the wire's `n1` converted to `Q1.n1` (`84576840`, vector `legal_retraction_door_form`, also main-valid). Source: Eureka's `desk-body-digest-order-20261110.md`, computed with `sha256sum`; the generator, the C# suite and the TypeScript suite recompute every digest from the input fields. **Status:** the three `retracted` goldens (`935cab1a`, `82b24ccc`, `34ef86ed`, and `79eee623` for form (i) with a null target) are the form of `cut-desk-digest-retracted.r2`, merged as Huginn #30. Eureka reports that these four and the door-form legal retraction (`84576840`) reproduce byte for byte on Huginn main `f0ca504` (the #30 fix); that run is hers, reported to us, and was not rerun here. Before #30, Huginn main (`7ea11b4`) wrote `illegal_retraction` alone, so forms (i) and (iii) collided there (`69074cc6`, pinned as `illegal_i_and_iii_alike_on_main`). The wire contract does not wait on it: the conflict scenarios are pinned in `scenarios`.
+
+### Counting rules (in order; the first failure refuses with that code)
+
+| step | rule | refusal | stored |
+|---|---|---|---|
+| 1 | verified session or bearer | `unauthenticated` (401) | no |
+| 2 | closed body; no `answerer`/`authority` at any depth; type-correct; not (no `answer` and not a retraction) | `body_forbidden_field`, `body_unknown_field`, `body_invalid` (400) | no |
+| 3 | `fork_id` is a stored fork | `fork_unknown` (404) | no |
+| 4 | `options_hash` equals the stored fork's hash | `stale_fork` (409) | **yes**; the result carries the current card |
+| 5 | the stamped `answerer` is on `deciders` | `not_a_decider` (403) | yes |
+| 6 | the fork is open (`status: open`) | `fork_closed` (409) | yes |
+| 7 | `choice`, if present, is an option id | `choice_invalid` (400) | yes |
+| 8 | first passing answer for `(fork_id, options_hash)` is `Counted`; later passing answers are `Revision`s naming the counted one | | yes |
+| 9 | a Matrix edit, redaction or reaction changes nothing | | no event is an answer |
+
+**Retraction** (`retracted: true`, `retracts: <answer id>`, `answer: nil`, `options_hash` still carried, so step 4 applies) passes steps 1 to 6, then:
+
+- R1 form: it carries no `answer`, it names a `Counted` or `Revision` answer of this fork under this `options_hash`; else `bad_retraction` (400). A retraction naming an answer already retracted is `already_retracted` (409). `retracts` on a body that is not a retraction is `bad_retraction`.
+- R2 who: the original answerer or any other decider; step 5 already requires a decider.
+- R3 is dropped and its label stays vacant, so R4 keeps its name in the binding file. A ruling that answers a fork closes it (Eureka and Heimdall, 2026-11-10), so a ruling cannot cite an answer on an open fork (that is the stale-click gap, and a card with `ruled_from` set and `status: open` is invalid), and a retraction after a ruling meets step 6: refused `fork_closed`, stored. There is no `ruled` code (vector `V10a_a_ruling_that_closed_the_fork_makes_a_retraction_fork_closed`).
+- R4 counted answer: retracting the counted answer removes it from the count and the next passing answer in admission order counts again. Retracting an answer that was not counted changes nothing. After every answer is retracted, a fresh answer is `Counted`. Records stay append-only.
+
+**The counted answer is derived**, not stored: the first `Counted` or `Revision` answer under the card's current `options_hash` that no `Retraction` names. When the card changes, answers under the old hash stop counting and the next answer under the new hash is `Counted` (vectors `a_changed_card_...`). The `record` projection carries it as `counted_answer_id`.
+
+### Operator authority
+
+A ruling may carry `authority: Operator` only if it cites (`ruling_cite.answer_id`) a stored `desk_answer` whose outcome is `Counted` and whose stamped attribution (the answer's `authority` field) is `Operator` (or a stamped relay of her words from a mapped door, which this contract does not model). The citation is what gives a ruling authority: an attribution on an answer is a fact about the account, and authority exists only where a ruling cites a counted answer. The cited answer id is what `ruled_from` lists on the closed card. Negative vectors (`rulingCites`): no citation, a `Revision`, a `Refused` answer, a Counted answer by a non-operator, an answer that does not exist. Other authorities need no citation.
+
+## Transport
+
+Source: the desk's client needs (Ratatoskr PR #24 section 12, `ratatoskr-desk-spec-20261110.md`) and Heimdall's binding file, `/opt/commons/handoff/fork-desk-answer-binding-20261110.md`, section 1.3c, which is the source for the second door. **Everything in this section is spec text for Bifrost to build; no route, scope or audience below exists in Bifrost today.** The routes (with the `{mind}` segment), the scope names `desk.read` and `desk.answer`, the audience `bifrost-desk` and the auth order are Heimdall's rulings (his file, sections 4.1 to 4.3a); this page writes them as documents and vectors.
+
+**Authorities.** Cards are projected **read-only from Huginn**: Bifrost never authors a card, a ruling or a status, and the desk never writes one. Bifrost verifies the bearer, resolves the actor from its `sub` (a `UserAccount.Id`), and for an answer forwards a typed `DeskAnswer` on the peer-checked second door to Huginn, then returns **Huginn's outcome unchanged**: the stored `desk_answer` in an `answer_result`, or its refusal. The wire of the second door is **pending**: Eureka's cut spec follows her record PR, so this page defines the documents the desk sees and not the bytes between Bifrost and Huginn (open choice 3).
+
+| call | route (proposal) | request | response | token |
+|---|---|---|---|---|
+| 1 list | `GET /api/desk/{mind}/forks?status=&cursor=&limit=` | `list_request`: `mind` from the path, the rest from the query string | `list` | audience `bifrost-desk`, scope `desk.read` |
+| 2 read | `GET /api/desk/{mind}/forks/{fork_id}` (the id percent-encoded) | `read_request`, its `mind` and `fork_id` from the path | `entry`, or `refusal` `fork_unknown` (404) or `fork_too_large` (422) | `desk.read` |
+| 3 answer | `POST /api/desk/{mind}/answers` | `answer_request` as the body; `fork_id` stays in the body, the Mind is the route's and is no body field | `answer_result` (200 for `Counted`, `Revision` and `Retraction`; a stored `Refused` answer keeps the `answer_result` body and takes its code's status from the counting-rules table: `stale_fork` 409, `not_a_decider` 403, `fork_closed` 409, `choice_invalid` 400, `bad_retraction` 400, `already_retracted` 409, as the vectors' `results` pin; a replay returns the same status as the first call; the desk reads `outcome` and `code` from the body), or a `refusal` (`fork_unknown`, or `fork_too_large` when a stale answer's card re-read is past the cap), or `unavailable` | audience `bifrost-desk`, scope `desk.answer` |
+
+**The `{mind}` segment** (Heimdall's rulings M1 to M5; vectors `transport.mindRoutes`).
+
+- **M1.** `{mind}` is looked up in a **fixed configured list** of Mind ids, each mapped in configuration to that Mind's socket on the peer-checked door. The segment is percent-decoded once and compared, ordinally, with the list's ids: no case folding, trimming or Unicode normalisation, and a decoding failure is a miss. It is **never joined into a path, a socket name or a query**, so a value off the list opens nothing (`../x`, `a/b`, `a%2fb`, `eureka%00`, a 4 KB string, `GAMECULT-CHAT` for `gamecult-chat`, a trailing space, bytes that are not UTF-8: all unknown, 404, no socket opened).
+- **M2.** An unknown Mind gets **the same refusal as an unknown fork**: `fork_unknown`, 404, the same bytes (the document's `error` names neither the Mind nor the fork). The list of Minds is not probeable. Auth is judged first, so a caller without a valid token, scope or Active membership learns nothing about which Minds exist.
+- **M3.** On the POST the route's Mind must hold `fork_id`: step 3 is judged against **that Mind's** stored forks, so a `fork_id` the route's Mind does not hold is `fork_unknown` and nothing is stored, in either Mind. A fork cannot be answered through another Mind's route. A body that names `mind` is `body_unknown_field`: the Mind is the route's.
+- **M4.** Scopes are **not per Mind**: `desk.read` and `desk.answer` open the routes of every configured Mind; every reader sees every fork's card and outcome (a non-decider sees no account id, "Reader views"), and which forks a caller may answer is the decider list.
+- **M5. The decider list is sent per call.** Bifrost holds the admin-set list and sends it with **every answer, read and list request** to Huginn, as a typed field on the same peer-checked door; Huginn keeps no copy of it. Because it travels with read and list too, a projected card's `deciders` is the list of that call for a decider and empty for a reader who is not one, with `decider_count` travelling with both views, and step 5 judges an answer against the list the same call carried. It comes only from Bifrost's admin-set state: never from a Mind and never from any request body a client controls: no HTTP field, header or query parameter on any desk route sets or extends it, and a body naming `deciders` is `body_unknown_field` (scenario `M5_...`). A request carrying it from a Mind's own door or session is refused. **This is Bifrost and Huginn work and no vector here can test it** (the typed field and the door's wire are pending, open choice 3); the rule is stated so that the cut that builds the request has it. (Heimdall's ruling, #minds 2026-11-10 19:26Z; it replaces the earlier reading of a list Huginn receives once and holds.) **Envelope names:** the desk's envelope on that door uses the names this page uses, `mind`, `authority`, `subject` and `deciders`, with no conversion at the door (Eureka, #minds 2026-11-10 19:58Z); `deciders` is a per-call list of short ids at the envelope's top level beside `subject`, never inside the request body, and Huginn keeps no copy.
+
+Calls 1 and 2 are enough for a read-only desk. Every response is the pinned MessagePack document or its JSON form with the same keys (open choice 1 of `vote-api.md`: the media type is unsettled).
+
+**Auth, in order, per route.** (1) A bearer, else `unauthenticated` (401). (2) The token's audience is `bifrost-desk`: **the Matrix Authentication Service token chat holds today is refused, and so is any `votes.*` token** (audience `bifrost-votes`), both as `unauthenticated`. (3) The scope the route needs, else `insufficient_scope` (403): `desk.read` for calls 1 and 2, `desk.answer` for call 3, and neither implies the other. (4) The account behind `sub` is an Active member, else `forbidden` (403), as in the vote API; scope is judged first. (5) For call 3 the body is then shaped (steps 1 and 2 above), so **a non-Active member who sends a bad body, including one naming `answerer` or `authority`, gets `forbidden`, not a body refusal**; a body naming either key at any depth is `body_forbidden_field` only for an Active member. (6) Only then is Huginn asked, so `unavailable` never hides an auth or body refusal. A `votes.*` token touches none of the three. Heimdall's file leaves the audience and the claims check open; `insufficient_scope`, `forbidden`, `request_invalid` (400, a list or read request that fails its document; an unknown key, `authority` included, is `request_invalid` here, whatever Huginn's own decode does with it) and `request_id_conflict` are added to the door refusals, and so is `fork_too_large` (422, list and read; see List and Read). **`request_id_conflict` is answer-only**: the idempotency key exists only on the answer. A door `request_id_conflict` on a read or list is a door fault and reaches the client as 503 `unavailable`, never as `request_id_conflict` (Persona, 2026-11-11, agreed with Heimdall; vectors `transport.doorFaults`, each carrying the client response's bytes). The `unavailable` text's "same request_id" retry hint is for answers; reads and lists carry no request_id..
+
+**List.** `list_request`: `{mind, status, cursor, limit}`. `mind` is the route's `{mind}`, a Mind id from the configured list. `status` is `open`, `recorded` or nil for both; `recorded` means a closed card. Cards come **newest first by `order`**. `order` is the card's unique rank per Mind: an integer from 0 that never changes once the card exists, later questions only appending (Huginn derives it from the Mind's questions sorted by admission ordinal, then key). A Mind never holds two cards of one `order`; a list or card set that does is refused, and the refusal names both fork ids. 0 is legal, but no cursor names it (`c0` fails the cursor pattern): a page ending at order 1 returns `c1`, and the next page returns the order-0 card alone with `next_cursor` nil. `limit` is 0 to 50; **`limit` 0 returns no entries, only the counts and the stamp**, which is what "N open" on the Mind's header needs. `cursor` is nil or `c<N>`: the cards whose `order` is below N; a client treats it as opaque and sends back the `next_cursor` it was given. `list`: `{mind, stamp, open_count, recorded_count, forks[entry], next_cursor}`. The counts cover every card the viewer may see, whatever `status` and `cursor` asked for. `stamp` is `s<N>`, N the receiver's last-seen Huginn admission ordinal for the Mind's desk documents: the same stamp means the same state, so a desk polls `limit` 0 and fetches bodies only when the stamp moves. `next_cursor` is nil on the last page. **A page may hold fewer than `limit` entries** when the next entry would push the encoded response past the receiver's response budget (Huginn: 65536 bytes); it then holds at least one, `next_cursor` is `c<order of the last entry returned>` so the next page resumes below it, and the counts and the stamp are those of the full list, unchanged. **`fork_too_large`** (HTTP 422) refuses a page whose **first** entry alone is past the budget: 422 because the request is well formed and authorised but names a resource the list cannot carry, and 413 is for a request body that is too large, which this is not; retrying returns the same refusal. Its `error` names the fork id and its `order`, for example `fork_too_large: fork <fork_id> (order <n>) alone is past the response budget`. **A refusal's `error` text is informational and not pinned**: the contract pins the code, the HTTP status, that the text names the fork id (and the order on a list), and the `c<order>` continuation on a list; the vectors' wording is a sample, and the judges check those four things, not the bytes of the text. The client continues the list with cursor `c<n>`, the cards strictly below that order, which skips this fork; it is then readable only by id (the read route returns the whole entry, and refuses with the same code only when that entry alone is past the cap, see Read); `c<n>` is valid only when n is at least 1, so for order 0 there is nothing below and the client has reached the end. `limit` 0 returns no entries and never refuses. (Ruled by Persona, 2026-11-11.) An `entry` is `{card, record}`: the card and its `record` (the answers with their outcomes and the derived `counted_answer_id`).
+
+**Read.** `read_request` is `{mind, fork_id}`; the response is the `entry` for one fork of that Mind. Its `card.options_hash` is **computed by the server** from the five shown members as in "Options hash" and the client recomputes it from what it rendered; a card whose hash is not the hash of its members is no card (negative vector `card_hash_wrong`). The record's `fork_id` and `options_hash` are the card's, and `counted_answer_id` is derived, not copied (negative vectors for each). Every `desk.read` holder sees every fork's card and outcome in a configured Mind; only a decider's notes depend on the caller, going to callers in the admin-set `deciders` list, which Bifrost enforces at the door (ruling `desk-read-visibility`, option (c)); `fork_unknown` is only for a fork id that does not exist under the route's Mind (an unknown Mind answers the same, M2), so no fork is ever hidden by it, and a caller without `desk.read` is refused by the auth order above (`insufficient_scope`) before any lookup. **Huginn withholds account ids from a reader who is not a decider and returns counts ("Reader views"); Bifrost still strips notes.** Every `desk.read` holder sees cards and outcomes; notes (a decider's own words) only go to callers in the admin-set `deciders` list. The read and list shapes are unchanged and carry no audience field (`eureka-substrate:question:desk-read-visibility`, Heimdall's option (c)). **A read is refused `fork_too_large` (422) when the whole entry is past the reply cap** (Huginn's daemon caps every reply at 65536 bytes; the cap, not the page budget, is what a read meets). Its `error` names the fork id and has no order and no cursor to carry, because there is nothing to continue with (sample: `fork_too_large: fork <fork_id> alone is past the response budget`) (vector `transport.readTooLarge`; the cap is in no vector). **The answer route meets the same cap:** when an answer is `stale_fork`, Bifrost re-reads the current card to attach it, and if that read is past the cap the answer is refused `fork_too_large` (422) with the read form of the text, the same document as a read. Huginn has already stored the answer as `Refused(stale_fork)`, as for any stale answer, and it is never counted; the client is told `fork_too_large` instead of receiving the current card, and a replay of the same `request_id` gets the same 422 while the fork stays oversize. It is never `unavailable` (vector `transport.answerTooLarge`). A stripped read serves a decider's `note` as `note: null`, never omitted (map-mode: every key is written); `desk_answer.note` is already nullable in the schema, so a served record validates as it stands.
+
+**Answer.** The body is the `answer_request` and nothing else a client may set: `fork_id`, `options_hash`, `answer`, `answered_at`, `request_id` (plus `retracted` and `retracts`, written `false` and nil unless the call retracts). The response is the stored outcome: `Counted`, `Revision`, `Retraction`, or `Refused` with its code, and the **`counted_answer_id`** the fork has once this call is applied (`n<seq>` or nil; derived as in "The counted answer is derived", the same value the `record` projection carries, so the desk needs no second read). A replay returns the stored outcome with the `counted_answer_id` current at the retry, not the one it had when first stored. **A `stale_fork` refusal carries the current card** in `answer_result.card`, so the desk can show the new fork without another read. Nothing is stored for a step 1 or 2 refusal, an unknown fork (or an unknown Mind, or a fork another Mind holds) or a `request_id_conflict`. `unavailable` promises nothing either way.
+
+**Vectors (`transport` in `fork-card-vectors.json`).** `listRequest`, `readRequest` and `entry` (valid and invalid, with bytes); `listInvalid` (including `two_cards_share_one_order`, whose `refusal` is the exact text both judges must produce: `order 4 is shared by <first fork id> and <second fork id>`); `listScenarios` (six scenarios: over one Mind's five cards, paged open-only, recorded-only, all and `limit` 0; an empty Mind; and `order_zero_is_legal_but_no_cursor_names_it`, four cards of orders 3 to 0 paged by 3, whose first page ends at order 1 with `c1` and whose second page is the order-0 card with `next_cursor` nil; each response with its bytes, the cursor of page two being page one's `next_cursor`); `listShortPages` (three scenarios: a page that stops short and resumes below its last entry; `fork_too_large` on a first entry of order 3, continued with `c3`; and a short page ending at order 1 followed by `fork_too_large` on order 0, where the client is at the end; each step carries its bytes, and the receiver's budget is in no vector, so the judges check a short page as a nonempty strict prefix of the unbudgeted page and a refusal as naming the entry the page would open with); `doorFaults` (three cases: a door `request_id_conflict` is `unavailable` 503 on read and list and itself 409 on the answer); `readTooLarge` (one case: a read whose entry is past the cap, refused `fork_too_large` 422 with the read-form text and its bytes); `answerTooLarge` (one case: a stale answer whose card re-read is past the cap, the same 422 document over a stored `Refused(stale_fork)`: `outcome` `Refused`, `code` `stale_fork`, `counted` false); `authCases` (twenty-two cases: the MAS token, three `votes.*` tokens, a desk token with the other route's scope, a non-Active member on each route, and Huginn down on each route, with auth and membership judged first). Both suites replay the list requests through a reference judge and the auth cases through another. `mindRoutes` (a configured list of two Minds with their sockets and forks; 57 cases over the three routes: bad and percent-encoded segments, unknown Mind against unknown fork with `sameResponse` pairs of equal bytes, the POST on a Mind that does not hold the fork, scopes that are not per Mind, and auth judged before the Mind lookup) is replayed by both suites through a reference judge that reports the refusal, the socket it would open and the Mind that stored an answer. Top-level `unavailable` pins the 503 document. Scenarios pin: an `unavailable` where Huginn never had the request, retried into a `Counted` answer; an `unavailable` where Huginn had stored it, whose retry returns the stored outcome and adds no Revision; a replayed `Refused` with its card; `request_id_conflict`; the same id from another account; and a non-Active member with a bad body, with the door down, getting `forbidden` first. A bad body is refused before the door is asked.
+
+**Bifrost must still build:** all three routes; the `bifrost-desk` audience and the `desk.read` and `desk.answer` scopes on the OIDC token it issues to chat; the configured Mind list and its sockets (M1); the projection of cards and records from Huginn, the stamp, the cursor and the counts; the `DeskAnswer` call on the second door and the pass-through of its outcome; the decider list, sent with every answer, read and list request from the admin-set list only (M5); the `unavailable` answer. **Huginn must still build** the second door's wire, the per-call decider list it receives with each answer, read and list request, keeping no copy (M5), and the read side the projection uses (Eureka's cut spec, after her record PR). **The desk may build today** against the vectors: nothing in them needs a live service.
+
+## Old format, the mind's record, and what maps to what
+
+The old desk (`index.html`) read `questions/<id>` and wrote `answers/<id>` in a shared store. The mind's `question` record is the source in the new design; the card is its projection.
+
+| old desk | mind `question` record | card |
+|---|---|---|
+| `qid`, `id` | key `campaign:question:label` | `fork_id` |
+| `title` | `title` | `title` |
+| `body` | `question` (the long text) | `context` |
+| `depends`: a free string | `depends`: up to 8 prose lines (`huginn schema question`) | `depends`: the lines verbatim |
+| `options[{key, label, text}]` | `options[{label, text}]` | `options[{id, text}]` |
+| option `key` | option `label` (a slug, the id) | option `id` |
+| option `label` (a human title) | none | **dropped**: not stored, not hashed; shown text is `text` |
+| `rec` (a key) | `recommended` (a label) | `recommendation` (an id), never nil |
+| `lean` ("Self leans" mark) | none | `leans` (an id or nil), not hashed |
+| `flag` (the provisional line) | none | `flag` (a string or nil), not hashed |
+| `status` open or closed, `ruling` | derived from the resolution (status is never written): any resolution of the question closes it; the ruling is the one that answered it | `status`, `ruling`, both a projection (`ruling` is nil on an open card and on a card closed with no ruling) |
+| `order` | none (unique rank per Mind, from 0) | `order` |
+| none | `raised_in`, `asked_on` | `raised_in`; `asked_on` is not carried |
+| none | the question's admission time (no timestamp in the old format; `asked_on` is a date and stays uncarried) | `raised_at`, an instant or nil, not hashed |
+| none | none | `deciders` (outside the Mind), `ruled_from`, `options_hash` |
+| none | none | `decider_count`, `answerer_count` (counts that stand in for withheld ids) |
+| answer `{choice: key or null, note, question, updatedAt}`, one mutable document per question | none | `answer_request` then an append-only `desk_answer` |
+| `note`: her words verbatim | | `answer.note`, verbatim |
+| "Clear pick": `choice` back to null so the note stands alone | | an `answer` with `choice` nil and `note` set, as the first answer or as a `Revision` |
+| "Changing an answer is fine until it's admitted as a ruling" | | a later answer is a `Revision`; `Retraction` withdraws one; neither changes who counted first, and a ruling that answers the fork closes it, after which no answer or retraction is taken (`fork_closed`) |
+
+Differences that need Void's choice: the old page **overwrites** one answer per question and the new store **appends**, so the booth cannot show "your answer" as one mutable field (it shows the latest answer by the person, plus its history); the old page needs no identity and the new one stamps `answerer` from a verified session; the old `label` has nowhere to live unless the card's `text` carries it.
+
+## Transport note for Void: Matrix event versus how the mind carries questions
+
+How a mind carries a question today: a typed `question` record in Huginn (`huginn view`, `huginn query`); the Persona relays it to the operator in chat, and the operator's reply comes back as chat text that Self reads and admits as a `ruling` in her words. Identity is whoever the chat attributes the message to; nothing binds an answer to the question text she saw.
+
+Option A, **a Matrix event in the Mind's room with the answer as a reply.** Gains: it sits where people already are, needs no sign-in beyond Matrix, and the thread shows the exchange. Loses: the sender is an mxid, not a Bifrost account, so `answerer` and `authority` have no verified source; an edit or redaction changes the visible message but not the decision (binding rule 9), so the thread and the record can disagree; there is nowhere to carry `options_hash`, so a stale card cannot be refused; and a reply is free text, so `choice` is lost.
+
+Option B, **Bifrost receives the answer and Huginn stores it** (the design in this page; Ratatoskr PR #24 also withdraws the Matrix carrier). Gains: a verified account, a bound hash, refusals that are stored and visible, one counted answer, retractions. Loses: the booth needs Bifrost sign-in, which does not reach chat yet (Bifrost PR #9 and #37 design it), so until then the desk is read-only; and the exchange is no longer in the room.
+
+**Recommendation: B, with Matrix as presentation only.** The Mind may post a card as a listing and a link into the desk; no Matrix event is ever an answer (rule 9). Confidence: high on the rule (it is Heimdall's and Eureka's already), moderate on the interim, where read-only until sign-in is a real cost; if the operator needs to answer before sign-in reaches chat, the honest stopgap is the old path (chat text, Self admits a ruling in her words) rather than a Matrix reply the record cannot bind.
+
+## Differences from the binding file
+
+- Spelling: every field is as the binding file names it (`fork_id`, `options_hash`, `answered_at`, `retracted`, `retracts`, `answer.choice`, `answer.note`, `recommendation`, `depends`, option `id`), except that `schemaVersion` keeps CultNet's camelCase and `answer_id` replaces the earlier `receipt id` (Persona brief).
+- Map-mode writes every key: `retracted` is always present; nothing is "optional".
+- `Refused` stores every refusal from steps 4 to 7 and R1 and R2 (his section 1.3b); only steps 1 and 2 and `fork_unknown` are not stored. The binding file does not say whether `fork_unknown` is stored; it cannot be keyed without a question, so it is not (open choice 4).
+- The binding file's `choice_valid` has no named refusal code; this page names it `choice_invalid`. `fork_known` is `fork_unknown`. A type-invalid body is `body_invalid`.
+- `ruled` (his R3 and V10) is dropped: a ruling that answers a fork closes it, so the case is `fork_closed` (V4, V10a). His file drops it too.
+- Heimdall's section 1.3e (Q1 to Q6, V12 to V18) is the source for `request_id`; this page matches it, with two notes. Q1's open item is settled by his ruling: a replayed `stale_fork` returns the current card. In V14 a decider's identical body is a `Revision` whose `of` necessarily names the first account's counted answer id (the record shows it to every decider), so "never contains X's answer_id" holds for Y's answer id and document, not for `of` (Heimdall: `of` naming the counted answer is allowed); the vector with an off-list first account pins the case with a `Counted`, which has no `of`.
+- `request_id` (on the request and the stored `desk_answer`) and `request_id_conflict` are this page's: his file has no idempotency key, and a retry after `unavailable` needs one. Eureka's `desk_answer` kind and Huginn's request type must carry it.
+- Transport: the routes, the `{mind}` segment, the scopes, the audience and the auth order are his rulings (4.1 to 4.3a); the documents (list, read, `unavailable`) are this page's. The note limit is 4000 UTF-8 bytes here, as his 1.1 leaves the unit unsaid.
+- The recommendation is never nil. The binding file's earlier vectors D and E used a nil recommendation; its updated D and E use `"a"`, as here.
+- `raised_at` (2026-11-11) is the desk-feed addition (Bifrost PR 67): a required key, an instant or nil, outside `options_hash` (the five hashed members and every digest are unchanged; vectors `raised_at_nil`, `raised_at_epoch_integer`, `raised_at_date_only`, `raised_at_missing`). The card is spec-authored and no runtime deploys it, so the schema id stays `gamecult.fork.card.v0`.
+- Reader views (2026-11-11) are the desk-feed addition behind Huginn PR 56 and `eureka-substrate:ruling:desk-read-visibility-withheld-ids`: the card gains `decider_count` and `deciders` may be empty; the record gains `answerer_count` and `answerer` may be nil, the counts beside the collections they summarise (not on the list envelope, which neither the read entry nor the `stale_fork` card travels in). `options_hash` and every digest are unchanged. The schema ids stay `gamecult.fork.card.v0` and `gamecult.fork.record.v0` for the same reason as `raised_at`.
+- Hash vectors: A, B, C, D, E, F and G of the binding file are reproduced digest for digest by the Python generator, the C# suite and the TypeScript suite (the generator prints `same` for each; none differs).
+
+## Open choices
+
+1. Case of field names: snake_case for the fork documents (as the binding file) beside camelCase for the vote documents (as Bifrost's serializer). One convention would be tidier.
+2. NFC across runtimes relies on each runtime's normaliser; a pinned table, as `write-receipt.md` does for letters, would remove the reliance. The risk is only for code points assigned after a runtime's Unicode version.
+3. How Huginn learns the verified subject: the second door's authenticated context (the peer credential names Bifrost the service, not the member), so the subject must travel beside the request. This contract has no envelope for it.
+4. Whether `fork_unknown` and shape refusals should leave an audit record somewhere other than a `desk_answer`.
+5. Whether `leans` and `flag`, which the booth shows, should join the hash. The binding file's five members do not include them; a changed lean would not make an answer stale. `raised_at` is immutable, so it was kept out of the hash for the same reason it need not be in: it can never make a shown card stale.
+6. What the person sees of a retracted counted answer when the next answer counts: this contract only says the count moves.
+7. `received_at` is not in the binding file's stored fields; it is kept for `claim_in_future` and could be dropped if the `n<seq>` answer ordinal alone decided answer order.
+8. The stamped `authority` field is an attribution, not an authority (above); renaming it `attribution` would say so, at the price of a new key the door must also refuse in a body.
+9. The claims Bifrost verifies are PR #24's open item 5. (The audience `bifrost-desk`, the three routes and the scope names are ruled by Heimdall.)
+10. The second door's wire between Bifrost and Huginn (pending Eureka's cut spec). `unavailable` is a document of its own, outside the refusal set, so a desk can retry it; calls 1 and 2 use it too when Huginn is down (vectors `huginn_down_*`).
+11. While a known Mind's door is down its routes answer `unavailable` (503) and an unknown Mind answers `fork_unknown` (404), so the two are distinguishable for that period. M2 makes them identical only when every door is up; making them identical when one is down means answering `unavailable` for any `{mind}` not on the list, which tells a client nothing about which Minds exist but also hides a typo. Heimdall's to rule; the vectors do not pin it.
+12. A fork's answers are unbounded in number, so a fork's entry can grow past the reply cap and become unreadable (`fork_too_large` on read, and on list when it is the first entry of a page). Whether the contract should cap the answers per fork is for Persona and Heimdall to rule; nothing here decides it.
+13. The read form of `fork_too_large` is a target, not current behaviour: Huginn's door answers an over-cap read as `Refused(ResponseTooLarge{bytes, limit})`, which carries no fork id and is not `fork_too_large`. Bifrost maps it to `fork_too_large` (422) using the route's `fork_id`; until it does, a read past the cap reaches the client as 503 `unavailable`. The same holds for the answer route: a `stale_fork` answer whose card re-read is past the cap is a Bifrost target too (`fork_too_large` 422 over a stored `Refused(stale_fork)`), and until it is built the client sees 503 `unavailable`.
+14. What a non-decider can still infer: the card's `status` and `order`, the `authority` role on each answer (a role, not an id, and the ruling leaves it whole), and `answerer_count`. Whether a role plus a count is too much to show is Eureka's ruling to revisit.

contracts/cultnet/governance/vote-api.md

@@ -0,0 +1,107 @@
+# CultNet vote API v0 (specification)
+
+Status: specification, drafted for Heimdall (Bifrost) and a Ratatoskr voting module. No server implements it yet.
+Files here: `vote-api.schema.json` (one schema, a `$defs` entry per document), `vote-api-vectors.json`. Conformance suites: `tests/GameCult.Networking.Tests/GovernanceVectorTests.cs` (C#) and `packages/cultnet-ts/test/governance-vectors.test.ts` (TypeScript). The vectors are written by `scripts/gen-governance-vectors.py`.
+Facts it rests on: `/opt/commons/handoff/bifrost-browser-voting-facts.md` (Bifrost `416f11a`; `416f11a..276f611` changes four files: a Standard-close concurrency fix in `MotionGovernanceService.cs`, two test files and `docs/deploy-main-to-live.md`; none touches the sealed API, so the facts hold at `276f611`) and Bifrost PR #37 (`docs/ratatoskr-voting-auth.md`, see "PR #37" below).
+
+## Scope
+
+**Which API covers which.** This contract covers **sealed-ballot motions only** (`gamecult.sealed_ballot.v0`). **Standard motions are not covered here.** Bifrost PR #37 also serves them (`PUT /api/votes/motions/{id}/ballot`, a receipt `{motionId, choice, revision, castAtUtc, receiptId}`), and that API is #37's own: this page defines no document for it, and a Standard motion id sent to any exchange below is answered `not_found`. Today Standard motions have no JSON read or cast API at all, no Mind path, and no receipt (open choice 1). The contract names four exchanges and one refusal document:
+
+| exchange | request | response |
+|---|---|---|
+| motion list | `gamecult.vote.motion_list_request.v0` | `gamecult.vote.motion_list.v0` |
+| motion read | `gamecult.vote.motion_read_request.v0` | `gamecult.vote.motion.v0` |
+| cast (commit or reveal) | `gamecult.vote.cast.v0` | `gamecult.vote.receipt.v0` |
+| any refusal | | `gamecult.vote.refusal.v0` |
+
+Every document is CultNet map-mode: all keys are written, nil where absent, and the schema is closed (`additionalProperties: false`). Instants are RFC 3339 UTC with a `Z` and up to seven fractional digits. Ids are lowercase `D`-format UUIDs. A motion states `highStakes`, a boolean fixed when the motion opens and never changed after (Bifrost PR #37, D2): it is the property that makes a commit demand a fresh sign-in (`reauthentication_required`). The bytes of every document are pinned by `messagePackHex` in the vectors (shortest integers, shortest strings, keys in the order the schema lists them); JSON with the same keys is the xenos-boundary form of the same documents (open choice 4: the wire format).
+
+## Documents
+
+- **motion_list_request**: `{schemaVersion, phase}`; `phase` is `Commit`, `Reveal`, `Closed` or nil for all.
+- **motion_list**: `{schemaVersion, motions: [{id, title, round, phase, commitClosesAtUtc, closesAtUtc, highStakes}]}`. **Heimdall must add this endpoint**: Bifrost has no list route for sealed motions today, only fetch-by-id. No pagination in v0 (open choice 2).
+- **motion_read_request**: `{schemaVersion, motionId}`.
+- **motion**: Bifrost's `SealedMotionState` with its names: `{schemaVersion, id, title, summary, round, priorMotionId, ballotSchema, phase, candidates (two or more), commitClosesAtUtc, closesAtUtc, highStakes, yourVoterId, yourCommitment (a receipt or nil), announcement}`. It never carries a tally, a turnout, or another voter's commitment or ballot (a `tally` key is a negative vector). `yourVoterId` is the voter's `UserAccount.Id`, the `voterUserAccountId` of the commitment.
+- **cast**: `{schemaVersion, motionId, verb, commitment, ballot}` with exactly one of two shapes: `verb: "commit"` with a 64-hex `commitment` and `ballot: nil`, or `verb: "reveal"` with `commitment: nil` and a `ballot`. One document for both verbs; today's two routes (`/commit`, `/reveal`) may stay, taking this document as the body, with a `verb` that must match the route (open choice 3).
+- **ballot** (inside a reveal): `{schema: "gamecult.sealed_ballot.v0", motionId, round, candidate, reason, salt, persona}`. `candidate` and `reason` are single-line and **already trimmed** (no Unicode White_Space at either end, using the White_Space list of `write-receipt.md`); the contract refuses an untrimmed value rather than trimming it, so the bytes hashed are the bytes sent. **This is a behaviour change Bifrost must make:** it trims `candidate` and `reason` silently on reveal today (facts file section 3c, `SealedBallotService.cs:154, 385-387`), so an untrimmed reveal is accepted and hashed trimmed; under this contract it is `invalid` (open choice 5). `reason` is 1 to 280 characters counted in UTF-16 code units, as Bifrost counts. A JSON Schema `maxLength` counts code points, so the schema alone accepts up to 280 astral characters; both suites add the rule (vectors `cast_reveal_reason_140_astral_280_units` valid, `ballot_reason_141_astral_282_units` refused). `salt` is 32 to 128 lowercase hex. `persona` is `""` for a member and a printable-ASCII, space-free id of at most 64 characters for a Mind.
+- **receipt**: Bifrost's `SealedBallotReceipt`: `{schemaVersion, motionId, voterUserAccountId, commitment, revision (>= 1), committedAtUtc, revealed}`. The receipt for a reveal has `revealed: true` and **echoes nothing of the ballot** (no candidate, reason or salt; negative vectors for each).
+- **refusal**: `{schemaVersion, code, error, retryAfterSeconds}`; the `code` set is closed:
+
+| code | HTTP | trigger |
+|---|---|---|
+| `unauthenticated` | 401 | no bearer, or one Heimdall does not know (the API must answer this, not redirect to a sign-in page) |
+| `reauthentication_required` | 401 | a commit on a `highStakes` motion with no sign-in fresh enough (#37 D2: `prompt=login`, `max_age`); the voter signs in again at the top level and retries |
+| `forbidden` | 403 | authenticated but not an Active member, or a Mind key used on a route it may not call |
+| `not_found` | 404 | unknown motion id, a Standard motion id, or a reveal with no prior commit |
+| `wrong_phase` | 409 | commit outside Commit, reveal outside Reveal |
+| `contended` | 409 | a reveal raced the close fence: send it again |
+| `invalid` | 400 | the body fails the schema or an in-document rule (untrimmed text, candidate not in the motion, `round` or `motionId` mismatch, `persona` wrong for the credential) |
+| `commitment_mismatch` | 400 | a reveal whose canonical bytes do not hash to the stored commitment |
+| `payload_too_large` | 413 | body over 4096 bytes |
+| `rate_limited` | 429 | cast rate exceeded, per account; `retryAfterSeconds >= 1`, mirrored in `Retry-After` |
+| `held` | 503 | the Ratatoskr voting brake is set (#37 D5): nothing is read or stored while it is |
+
+Each code has a vector (`refusals`), and every failure of the schema has a negative vector (`invalid`).
+
+**Not on Bifrost's member API yet.** The **413 body cap of 4096 bytes** and the **429 per-account cast limit** are not on Bifrost's member sealed API today (facts file sections 3c and 5): both exist only on the Mind intake route (4096 bytes; 30 requests a minute per source address). #37 proposes 30 casts per 10 minutes per account for the member routes (its D6). `reauthentication_required` and `held` are #37 proposals (D2, D5) and exist nowhere in code. All four are spec text until Heimdall builds them.
+
+**Two refusals Bifrost must split first.** Bifrost returns a reveal whose bytes do not hash to the stored commitment as a plain `400` `Invalid` ("The ballot does not match the stored commitment."), the same status and error type as every other bad body, so `commitment_mismatch` and `invalid` are one today. It returns a contended reveal (a race with the close fence, `SealedBallotService.cs:186-189`) as `WrongPhase` `409`, the same type as a reveal outside the Reveal phase, so `contended` and `wrong_phase` are one today. A client cannot tell "send it again" from "too late", or "wrong ballot" from "malformed body", until Bifrost splits each pair.
+
+## Commitment
+
+`commitment = lowercase hex SHA-256 of the UTF-8 bytes of`
+
+    gamecult.sealed_ballot.v0 \n {motionId} \n {voterUserAccountId} \n {persona} \n {round} \n {candidate} \n {reason} \n {salt}
+
+with `\n` U+000A, ids in `D` format, `round` in decimal, `persona` empty for a member. This is Bifrost's formula as the code has it (`SealedBallotService.cs:154, 385-387`); `docs/sealed-ballot-motion.md:22-23` omits `{persona}` and is stale. The vectors give the canonical bytes (`canonicalHex`) and the digest for a member, a Mind, non-ASCII text, and a decomposed-versus-precomposed pair (no normalisation: they are different ballots). `pairs` pins what a reveal must match: the right ballot matches; a changed reason, another voter id, or a dropped persona does not, and the answer is `commitment_mismatch`.
+
+## Receipts the voter can check later
+
+A cast returns the receipt. The voter checks it later in two places that must agree byte for byte with it: `motion.yourCommitment` on a motion read (a commit receipt is present from the commit; the revision counts re-commits), and, after close, the `commitment` the result lists for them. The contract adds no receipt id or signature: the receipt is the commitment, its revision and the time (open choice 6).
+
+## Personas
+
+A Persona votes only on sealed motions, through a Mind key (Bifrost binds an Ed25519 public key 1:1 to an Active member account). The ballot's `persona` is the bound persona id and the commitment covers it, so a Mind's ballot cannot be replayed as a member's (`pairs`: dropping the persona does not match). The Mind-intake route today takes a signed `MindEnvelope` anonymously; this contract does not model that envelope, nonce or signature (open choice 7). Standard motions have no Mind path.
+
+## Authentication
+
+On the wire the credential is an opaque `Authorization: Bearer` header. The token route, claims, scopes and audience belong to Heimdall and Bifrost and are not designed here. A request without a usable bearer is answered `unauthenticated` as a typed refusal.
+
+**Auth per route, now and after #37.** Routes are Bifrost's; this contract fixes the documents, not the paths (open choice 3).
+
+| exchange | today (`/api/sealed-motions`, facts file 3c) | after #37 (`/api/votes`) |
+|---|---|---|
+| motion list | no route | bearer, scope `votes.read` |
+| motion read | session cookie + Active member | bearer, scope `votes.read` |
+| commit, reveal | session cookie + Active member | bearer, scope `votes.cast`, audience `bifrost-votes`; a high-stakes commit also needs a fresh sign-in |
+| Mind cast | anonymous; the Ed25519 signature on a `MindEnvelope` is the credential | unchanged: Minds never use `/api/votes` (#37) |
+| open a motion, Mind-key registry | session cookie + moderator | unchanged, cookie only |
+
+Today a member route has **no bearer scheme**: it accepts the host-only `__Host-bifrost_session` cookie and answers an unauthenticated call with a redirect to the sign-in page, not a 401. After #37 `/api/votes` is bearer-only and answers a typed 401. The wire header stays an opaque bearer either way; only Bifrost knows which of the two it is checking.
+
+## PR #37 (Bifrost `docs/ratatoskr-voting-auth.md`, head `447a7cb`)
+
+Checked 2026-11-10 by an Eyes pass over the PR and the schema; conflicts for Heimdall:
+
+1. **Standard motions.** The PR serves them (`PUT /api/votes/motions/{id}/ballot {choice, comment?}`, a receipt `{motionId, choice, revision, castAtUtc, receiptId}`); the contract is sealed-only and answers `not_found` for a Standard id.
+2. **Verb model.** The PR keeps `POST .../commit` and `.../reveal` and adds `GET .../result`; the contract has one `cast` document and no result document.
+3. **List and read as GET.** The PR names GET routes; the contract's request documents carry a `phase` filter and a `motionId`. The mapping (query string and path) is undefined until Heimdall fixes the routes.
+4. **Refusals.** The PR lists 401/403/404/409/429 with `WWW-Authenticate`; the contract adds 400 (`invalid`, `commitment_mismatch`) and 413, and a typed body.
+5. **Minds.** The PR says Minds never use `/api/votes` and keeps the anonymous signed `/mind` route; the contract carries `persona` in the ballot and a `forbidden` case for a Mind key on a route it may not call. The PR's token is never a Persona's.
+6. **Authority.** The contract's `unauthenticated` says a bearer "Heimdall does not know"; the PR makes Bifrost the OIDC issuer (a second client, scopes `votes.read` and `votes.cast`, audience `bifrost-votes`) and notes that Bifrost OIDC is not live (its D7).
+7. **Rate limits.** The PR keys per account (30 casts per 10 minutes); the contract now says per account too, and neither exists on the member API yet (above).
+8. **Wire format.** The PR's errors are JSON; the contract's vectors are MessagePack. Nothing settles the media type.
+9. **The PR's seven open decisions** (consent for `votes.cast`, re-authentication, no refresh token, grant revocation, a Ratatoskr brake, rate numbers, MAS rollout order) assume nothing the contract contradicts. D2 (re-authentication at cast) is answered yes for sealed commit in this contract: `reauthentication_required`, with `highStakes` fixed at open. D5 (a brake) is `held`.
+
+## Open choices for Heimdall
+
+1. Standard motions in v0 or a v1 (the PR already serves them).
+2. Pagination and filters on the list.
+3. One `cast` route or the two existing ones; `verb` redundancy.
+4. Wire format: MessagePack documents with a JSON export, or JSON only (the PR is JSON).
+5. Refuse untrimmed `candidate` and `reason` (this contract) or keep trimming server-side.
+6. Whether a receipt should carry an id or a server signature so a voter can prove it to a third party.
+7. The Mind path: keep the signed envelope on its own route, or take Mind keys as a bearer credential.
+8. `reason` length in UTF-16 code units (as Bifrost) or code points.
+9. Whether the result document (`GET .../result`) joins this contract.

contracts/cultnet/governance/vote-api.schema.json

@@ -0,0 +1,420 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/governance/vote-api.schema.json",
+  "title": "CultNet vote API v0 (sealed-ballot motions)",
+  "description": "Typed documents for listing, reading and casting on sealed-ballot motions, and the receipt a cast returns. Map-mode: every key is written, nil where absent. Spec: vote-api.md. Vectors: vote-api-vectors.json.",
+  "$defs": {
+    "uuid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
+    "instant": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,7})?Z$"
+    },
+    "hex64": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "trimmedLine": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![\\t-\\r \\u0085   - 

  　])[^\\n\\r\\u0085

]+(?<![\\t-\\r \\u0085   - 

  　])$"
+    },
+    "ballot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema",
+        "motionId",
+        "round",
+        "candidate",
+        "reason",
+        "salt",
+        "persona"
+      ],
+      "properties": {
+        "schema": {
+          "const": "gamecult.sealed_ballot.v0"
+        },
+        "motionId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "round": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "candidate": {
+          "$ref": "#/$defs/trimmedLine"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 280,
+          "pattern": "^(?![\\t-\\r \\u0085   - 

  　])[^\\n\\r\\u0085

]+(?<![\\t-\\r \\u0085   - 

  　])$"
+        },
+        "salt": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{32,128}$"
+        },
+        "persona": {
+          "type": "string",
+          "pattern": "^[!-~]{0,64}$"
+        }
+      }
+    },
+    "motionListRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "phase"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.motion_list_request.v0"
+        },
+        "phase": {
+          "oneOf": [
+            {
+              "enum": [
+                "Commit",
+                "Reveal",
+                "Closed"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "motionListItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "title",
+        "round",
+        "phase",
+        "commitClosesAtUtc",
+        "closesAtUtc",
+        "highStakes"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/uuid"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "round": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "phase": {
+          "enum": [
+            "Commit",
+            "Reveal",
+            "Closed"
+          ]
+        },
+        "commitClosesAtUtc": {
+          "$ref": "#/$defs/instant"
+        },
+        "closesAtUtc": {
+          "$ref": "#/$defs/instant"
+        },
+        "highStakes": {
+          "type": "boolean",
+          "description": "Fixed when the motion opens and never changed after: a high-stakes sealed motion needs a fresh sign-in at commit (Bifrost PR #37, D2)."
+        }
+      }
+    },
+    "motionList": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "motions"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.motion_list.v0"
+        },
+        "motions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/motionListItem"
+          }
+        }
+      }
+    },
+    "motionReadRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "motionId"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.motion_read_request.v0"
+        },
+        "motionId": {
+          "$ref": "#/$defs/uuid"
+        }
+      }
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "motionId",
+        "voterUserAccountId",
+        "commitment",
+        "revision",
+        "committedAtUtc",
+        "revealed"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.receipt.v0"
+        },
+        "motionId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "voterUserAccountId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "commitment": {
+          "$ref": "#/$defs/hex64"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "committedAtUtc": {
+          "$ref": "#/$defs/instant"
+        },
+        "revealed": {
+          "type": "boolean"
+        }
+      }
+    },
+    "motion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "id",
+        "title",
+        "summary",
+        "round",
+        "priorMotionId",
+        "ballotSchema",
+        "phase",
+        "candidates",
+        "commitClosesAtUtc",
+        "closesAtUtc",
+        "highStakes",
+        "yourVoterId",
+        "yourCommitment",
+        "announcement"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.motion.v0"
+        },
+        "id": {
+          "$ref": "#/$defs/uuid"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string"
+        },
+        "round": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "priorMotionId": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/uuid"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ballotSchema": {
+          "const": "gamecult.sealed_ballot.v0"
+        },
+        "phase": {
+          "enum": [
+            "Commit",
+            "Reveal",
+            "Closed"
+          ]
+        },
+        "candidates": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "$ref": "#/$defs/trimmedLine"
+          }
+        },
+        "commitClosesAtUtc": {
+          "$ref": "#/$defs/instant"
+        },
+        "closesAtUtc": {
+          "$ref": "#/$defs/instant"
+        },
+        "highStakes": {
+          "type": "boolean",
+          "description": "Fixed when the motion opens and never changed after: a high-stakes sealed motion needs a fresh sign-in at commit (Bifrost PR #37, D2)."
+        },
+        "yourVoterId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "yourCommitment": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/receipt"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "announcement": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "commitCast": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "motionId",
+        "verb",
+        "commitment",
+        "ballot"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.cast.v0"
+        },
+        "motionId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "verb": {
+          "const": "commit"
+        },
+        "commitment": {
+          "$ref": "#/$defs/hex64"
+        },
+        "ballot": {
+          "type": "null"
+        }
+      }
+    },
+    "revealCast": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "motionId",
+        "verb",
+        "commitment",
+        "ballot"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.cast.v0"
+        },
+        "motionId": {
+          "$ref": "#/$defs/uuid"
+        },
+        "verb": {
+          "const": "reveal"
+        },
+        "commitment": {
+          "type": "null"
+        },
+        "ballot": {
+          "$ref": "#/$defs/ballot"
+        }
+      }
+    },
+    "cast": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/commitCast"
+        },
+        {
+          "$ref": "#/$defs/revealCast"
+        }
+      ]
+    },
+    "refusal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "code",
+        "error",
+        "retryAfterSeconds"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.vote.refusal.v0"
+        },
+        "code": {
+          "enum": [
+            "unauthenticated",
+            "forbidden",
+            "reauthentication_required",
+            "not_found",
+            "wrong_phase",
+            "contended",
+            "invalid",
+            "commitment_mismatch",
+            "payload_too_large",
+            "rate_limited",
+            "held"
+          ]
+        },
+        "error": {
+          "type": "string",
+          "minLength": 1
+        },
+        "retryAfterSeconds": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    }
+  }
+}

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

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

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

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

contracts/cultnet/interop/error-vectors.json

@@ -145,6 +145,22 @@
           "current": null
         }
       }
+    },
+    {
+      "name": "message_invalid",
+      "messagePackHex": "85AD736368656D6156657273696F6EB063756C746E65742E6572726F722E7630A56572726F72D93E6D6573736167655F696E76616C69643A2052617720707574206D65737361676573206D75737420636F6E7461696E206120646F63756D656E74206D61702EAB726F7574696E6748696E74C0A4636F6465AF6D6573736167655F696E76616C6964A764657461696C7384A56669656C64A8646F63756D656E74A576616C7565C0A461734F66C0A763757272656E74C0",
+      "message": {
+        "schemaVersion": "cultnet.error.v0",
+        "error": "message_invalid: Raw put messages must contain a document map.",
+        "routingHint": null,
+        "code": "message_invalid",
+        "details": {
+          "field": "document",
+          "value": null,
+          "asOf": null,
+          "current": null
+        }
+      }
     }
   ]
 }

contracts/cultnet/interop/write-receipt.md

@@ -0,0 +1,89 @@
+# CultNet write receipt (specification)
+
+Status: specification. No runtime implements it yet; the conformance follow-ups below do.
+Rules: Heimdall's ruling of 2026-11-08 (a write completes on its result frame; an ack or a return is not admission).
+Files here: `cultnet.write-admitted.schema.json`, `cultnet.error.v1.schema.json`, `write-receipt-vectors.json`. They move to `contracts/cultnet/` when the first runtime implements them.
+
+## The problem
+
+A put or delete today has two answers on the wire: nothing (admitted, or the server never read it) and `cultnet.error.v0` (refused, with no id saying which write). A transport ack proves delivery. Clients that completed on the ack, or on a window with no refusal, reported refused writes as done (CultLib #55 to #58 bound this with a result window; this spec replaces the window with an answer).
+
+## Frames
+
+**`cultnet.write_admitted.v0`**: `{ schemaVersion, messageId, operation: "put"|"delete", schemaId, recordKey }`, every key written, none nil. Sent once a put or delete is admitted. The id echoes the write's `messageId` byte for byte; `operation`, `schemaId`, `recordKey` echo the write.
+
+**A `write_admitted` `messageId` is valid only if it contains at least one Unicode letter (`\p{L}`) or number (`\p{N}`) and no Default_Ignorable_Code_Point (DerivedCoreProperties).** The compare is raw: the id is echoed byte for byte, so a decoder never trims or normalizes it (`" a "` is valid; U+2800 is not, and neither is `a` followed by U+200B). Unlike the Required fields rule, this is not a White_Space test. The letters, numbers and Default_Ignorable code points are those of **Unicode 16.0** in every runtime, taken from tables embedded in each runtime and generated by `scripts/gen-unicode-messageid-tables.py` from `DerivedGeneralCategory.txt` (Lu Ll Lt Lm Lo Nd Nl No) and `DerivedCoreProperties.txt`; no runtime asks its platform's Unicode data, so a runtime's own Unicode version cannot change a result. Bumping the version is one coordinated change: regenerate the five tables and update the vectors that pin the version in the same commit. The rule is on the decoded string, which must be well-formed Unicode: a lone surrogate refuses. A runtime whose MessagePack reader rejects invalid UTF-8 refuses the frame earlier; byte-level strictness is a property of the reader and is not required of a decoder. A frame with more than one `messageId` key is malformed: a decoder that can see the duplicate (the C# and Rust decoders) refuses it; a decoder that collapses the map (Python, TypeScript, Kotlin) judges the value it ends up with, the last key, and refuses if that value is invalid, so no decoder echoes an invalid id (vectors `admittedMessageIdDuplicates` declare each policy and every runner asserts its own). A decoder refuses an invalid id the way it refuses an empty or ill-typed one; the rule is for `write_admitted` only and `error.v1` is unchanged.
+
+**Where a received `messageId` decides, and what that relies on.** Beyond echoing it, a received `messageId` is used in exactly two places. On a server, the remembered-write key `(actor, messageId)` with the content hash, the per-session limit and the replay of rule 5 are taken from the id of the write frame the server itself parsed. On a client, the write tracker attributes a `write_admitted` or `error.v1` to a write by equality with the id of a write that client itself sent (a frame naming an id not in flight settles nothing), and attributes an id-less error by the count of unanswered writes, not by any id. Both rely on the receiver being the only parser of that frame: a decoder's `messageId` on a frame that carries more than one `messageId` key is not trusted for any authorization, dedupe, replay or ordering decision, and the map-collapsing runtimes (Python, TypeScript, Kotlin, and C#'s typed deserializer on write frames) cannot see the duplicate. If a frame is ever parsed by two runtimes in a chain (a relay, proxy or forwarder that re-reads it), or a consumer needs `messageId` for authorization, dedupe, replay or ordering beyond echo and equality with a self-sent id, all runtimes must first refuse a duplicate `messageId` key (a spec change plus byte-level duplicate detection in the runtimes that decode to a map) before that use lands. Today Rust refuses a repeated key on write frames and on `write_admitted` (serde's `duplicate field messageId`, and `refuse_duplicate_keys` for the raw-list frames such as `document_put_raw`), though its `readable_message_id` names the first key when it names an unreadable frame; C# does not on write frames (a duplicate-key write is deduped on its last id, while the id it names in a refusal for an unreadable frame is read from the first key), and the Python server (`cultmesh_py/server.py`) only echoes the id while the TypeScript and Kotlin code matches it by equality with a request it sent.
+
+**`cultnet.error.v1`**: `cultnet.error.v0` plus a required `messageId` (string or nil). The code enum is v0's plus `limit_reached` (see Remembered-write limits); `cultnet.error.v1.schema.json` is the authority for the closed set. Sent in place of `error.v0` to a receipt-capable connection. `messageId` is the id of the request the error answers; nil only when the frame was unreadable or carried no id.
+
+Why a new error version and not an extra key on v0: the v0 schema is closed (`additionalProperties: false`) and the TypeScript decoder (Ajv over the closed schemas) rejects unknown keys and unknown `schemaVersion`s, and `parseCultNetMessage` throws on an unknown version; Rust's decoder errors on an unknown version too. Unknown-key tolerance of the Rust, Python and Kotlin error decoders was not checked, so none is assumed, so a surprise key or frame breaks an old client's whole receive path. Old clients are therefore never sent either new frame. This reverses the "old clients ignore it" assumption, which is false for today's decoders.
+
+## Capability: opting in
+
+A connection is receipt-capable when its `cultnet.hello.v0` (sent before its first write; the schema channel is reliable and ordered) lists both `cultnet.write_admitted.v0` and `cultnet.error.v1` in `supportedMessageVersions`. A server MUST NOT send either new frame to any other connection, and answers it exactly as before (no receipt, `error.v0`). A receipt-capable server lists both in its own hello, so a client can tell a legacy server from a receipt server that has not answered yet. A client that sends no hello gets legacy behaviour. A server advertises the two frames in its hello only if it implements the receipt rules end to end.
+
+**The capability changes framing only; it never authorizes.** A hello authenticates nothing and grants nothing: who may write, and which keys, is decided by the server from the transport-authenticated actor exactly as without the capability. Declaring the capability never makes a refused write admitted, never widens an actor's authority, and never changes what a write does; it selects only which frame the answer arrives in.
+
+## Server rules
+
+1. **One answer.** For every put or delete on a receipt-capable connection the server sends exactly one of `write_admitted` or `error.v1`, carrying that write's `messageId`. Never both, never two different answers.
+2. **After the commit point.** `write_admitted` is sent only after the write is committed by the same rule that makes it visible to readers. Receipt of the bytes, parse, or authorisation alone is not admission.
+3. **Id on every refusal.** Every refusal of a write, whatever its code (`write_not_authorized`, `message_invalid`, `unowned_schema`, `unsupported_schema_version`, shard authority errors, ...), is an `error.v1` whose `messageId` is the write's id. When the frame is readable enough to find the id, it is found; `message_invalid` for a missing or ill-typed field still carries the id. Nil only when no id can be read.
+4. **Batches.** There is no batch frame; a batch is N writes, each with its own `messageId`, each answered under rules 1 to 3. A failed batch names its member by that id. A server may not collapse a batch into one answer.
+5. **Identity and idempotent resend.** A `messageId` is unique per authenticated actor and session: the client mints it, never reuses it for different content in that session, and a server never accepts the id of one actor as the id of another. The server's dedupe key is `(actor, messageId)`, where *actor* is the transport-authenticated identity, never a name the hello or the frame claims. Alongside the key it keeps the **content hash** of the write and the answer it gave. The content hash is SHA-256 of the MessagePack array `[operation, schemaId, recordKey, payload]`, where `payload` is the raw document payload as a MessagePack `bin` for a put and nil for a delete (the vectors give worked hashes). **Scope: at least the session.** The key lives for the life of the session it was made in, and a server may bound how many writes it remembers per session (see Remembered-write limits; a server never forgets an id it promised to answer). A server MAY keep the key longer for the same actor, up to `DEDUPE_RETENTION_MS` (10 minutes), but a client MUST NOT rely on it: **a reconnect is a new session, and a resend on the new session is a new write.**
+   - Same key, same content hash, answer was `write_admitted`: answer `write_admitted` again with the same body. The write is not applied twice.
+   - Same key, same content hash, answer was a refusal: the same refusal again.
+   - **Same key, different content hash: refuse `message_invalid` (details `field: "messageId"`) and never re-send the old receipt.** Old receipts are for the old content; showing one for new content would report an unapplied write as admitted. The original write's state is unchanged.
+   - **Id size.** A write's `messageId` is at most 256 bytes of UTF-8. A longer id is refused `message_invalid` (`details.field: "messageId"`, the refusal's `messageId` the id as received, text fixed per Fixed texts) BEFORE anything is remembered: no table entry, no digest, no budget charge. Such a refusal is therefore not replayed from the table; a resend is refused afresh, identically.
+   - **What is remembered.** Per entry a server keeps only fixed-size digests (SHA-256) of the `messageId` and of the content hash, plus the answer (`admitted`, or the refusal's code and details). Memory per entry is bounded independent of id length and payload size. Lookup compares digests.
+   - **Remembered-write limits.** The per-session table holds at most 1024 entries. A server MAY also enforce a server-wide memory budget across all sessions (reference: 32 MiB of remembered entries). A NEW write (a key not already in the table) that would exceed either bound is refused `limit_reached` for that write alone, `messageId` the write's id, `details` all null; the write is not applied and the session continues. A resend of a remembered key is still answered from the table.
+   - **Limit refusals are remembered.** A `limit_reached` refusal is remembered like any other: a resend of the same id and content hash replays `limit_reached`. No slot is freed mid-session, so an id refused at a bound never becomes admitted later in that session (a server at the cap keeps the refused digest pair in a bounded refusal set of at most 1024 per session, outside the entry budget; past it, a further new write is refused `limit_reached` without being remembered, and the session refuses every id it has not seen for the rest of its life, even if a server-wide budget has since freed, so a refusal that was not remembered is never followed by an admission of the same id). The client mints a new id on a new session.
+   - **Required fields.** A put or delete whose document or `schemaId` is null or missing is refused `message_invalid` with `details.field` `"document"` or `"schemaId"` (the first missing in that order) and fixed text; the write is not applied. A put or delete that is present but names nothing is not "missing": the write is refused `message_invalid` exactly as a frame that does not read, with `details.field` `"message"`, the fixed unreadable text and the write's id (vector `error_v1_empty_schema_id_is_unreadable_and_names_the_write`), and is never applied; a server must not hand it to its store. Names nothing means, on a put or delete, a `schemaId` or `recordKey` that is blank; on a put's document, also a `storedAt` that is blank, a `payload` of zero bytes (a MessagePack value is at least one byte, so an empty payload is no document), a `sourceRuntimeId`, `sourceAgentId` or `sourceRole` that is present and blank, and a `tags` entry that is blank. **Blank** means empty or made only of Unicode White_Space code points (the PropList property) and nothing else, in every runtime, whatever its platform's own whitespace test says. The set is exactly U+0009 to U+000D, U+0020, U+0085, U+00A0, U+1680, U+2000 to U+200A, U+2028, U+2029, U+202F, U+205F and U+3000. U+200B, U+200C, U+200D, U+2060, U+FEFF, U+180E and U+001C to U+001F are not White_Space (some platforms' whitespace tests accept U+001C to U+001F or U+180E, for example Java's `Character.isWhitespace` and older .NET, so a runtime must check the list, not its platform test): a string of them names something. The vectors list both sets (`whiteSpaceCodePoints`, `notWhiteSpaceCodePoints`) and a runtime checks every code point in every covered field. Absent or nil source ids and tags, and an empty `tags` list, are valid. The rule holds on every connection, receipt-capable or not (a legacy connection is refused with the `error.v0` of the same code, details and text); the vectors' `blankFields` section lists each case.
+   - **Fixed texts.** The `error` string of these refusals is fixed, so vectors can compare it: `message_invalid: messageId exceeds 256 bytes`, `message_invalid: document is required`, `message_invalid: schemaId is required`, `message_invalid: the message could not be read` (a frame that does not decode, or a write that names nothing; the text is the same for both and never carries a decoder's own wording), `message_invalid: receipt sessions require the reliable channel`, `limit_reached: the session's remembered-write limit is full`.
+   - **Reliable channel only.** A write is accepted on a receipt session only on a channel that is reliable and not sequenced (reliable ordered and reliable unordered both qualify; a sequenced channel drops superseded packets, so a write on it can vanish without trace). A write arriving on any other channel is refused `message_invalid` with `details.field: "channel"` (the transport profile's word for it) and fixed text. Receipts and refusals travel the reliable channel; a write that could be lost without trace cannot be answered once. The server refuses a sequenced write whenever it can read the write's id: from the delivered frame, and from a superseded packet that carries its whole frame. A write sent as several fragments whose frame is superseded is dropped whole and may go unanswered; the client's unconfirmed outcome covers it.  A repeat of a packet the server already took, or a packet too far ahead to be taken, draws no further answer (rule 1).
+   - Past the session (or a server's longer retention, if it keeps one) a resend is a new write.
+6. **Forwarded writes.** A server that forwards a non-primary write answers the original peer only with what the primary answered: the primary's receipt becomes `write_admitted` with the original id, its refusal becomes `error.v1` with the original id. If the forward gets no answer the server relays nothing: no receipt, no error, no synthesized refusal. The client's own rule below then reports the write as unconfirmed. A forwarder never turns an absent or ambiguous primary answer into an admission.
+7. **Looks alike.** An admitted and a refused write differ in `schemaVersion`; a receipt has no `error`, an `error.v1` has no admission. A transport ack is neither.
+
+## Client rules: three outcomes
+
+A write settles as exactly one of:
+
+- **admitted**: a `write_admitted` whose `messageId` is the write's.
+- **refused**: an `error.v1` whose `messageId` is the write's, carrying its `code` and `details` as the typed error.
+- **unconfirmed**: nothing settled it. Reasons: `window_elapsed` (the result window ran from the *send* and passed with no answer; see Result window), `session_ended` (the peer closed the session, or it ended, before the write was answered; a write registered after the session ended settles this way when it is sent) and `local_send_failed` (the client's own send of this write failed). A local send failure is never reported as refused: no server answer exists, and the write may or may not have left the machine. Unconfirmed is not success and not refusal. APIs that return a value return the tri-state; APIs that throw throw a distinct refused error and a distinct unconfirmed error and return normally only for admitted. A caller that needs admission treats unconfirmed as not admitted. Resend with the same `messageId` and unchanged content, **on the same session**, is safe against a receipt-capable server (rule 5). After a reconnect the resend is a new write, and a legacy server may apply a resend twice: the caller resends only writes that are idempotent by record key (a put of the same content to the same key, a delete of a key), and reads the record back before resending any other.
+
+**Result window.** Two named constants (also in the vectors): `RECEIPT_RESULT_WINDOW_MS = 5000`, the default against a receipt-capable server (its hello lists both frames); `LEGACY_RESULT_WINDOW_MS = 500`, used only as the fallback against a server whose hello does not list them (or that sent none). The window runs from the send. It ends when the write's age reaches it: an answer arriving at exactly that instant is late. A receipt-capable server that has not answered within its window is reported as unconfirmed like any other; clients log it as a server that missed its window.
+
+**Late answers.** An answer for a write that already settled `unconfirmed` does not change what the caller was told, but the client records it on the write: a late `write_admitted` makes the write's recorded state `admitted_late`, a late refusal makes it `refused_late`. The write handle exposes that state, and a caller that got `unconfirmed` MUST consult it (and the record) before resending: it must not blind-resend a write that was admitted late. A resend on the same session with the same id and content is harmless on a receipt-capable server (rule 5); across a reconnect the caller follows the idempotence rule above.
+
+**Legacy answers.** An `error.v0`, or an `error.v1` with nil `messageId`, names no write. It is attributed to a write only when exactly one write on the connection is unanswered; it then refuses that write. With two or more unanswered writes it settles none of them and each ends unconfirmed at its window. A frame naming a `messageId` that is not in flight settles nothing.
+
+**Batches can commit partially.** A batch is N independent writes with no atomicity: some members may be admitted while others are refused or unanswered, and nothing is rolled back. The client reports each member's outcome and a batch result is only their set: admitted if every member is admitted, refused if any member is refused (naming the members), otherwise unconfirmed (naming the unanswered members). The caller owns retry: it resends exactly the members that are not admitted, with their original ids.
+
+## Changes to what #55 to #58 shipped
+
+Those clients complete *successfully* when the window ends with no refusal. Under this spec that case is `unconfirmed`. The TypeScript one-shot writer (#62) already reports it so: it resolves `admitted` only on a `write_admitted` carrying the put's id, and no other frame, a put echoed under the same id included, ever counts as admission. A caller whose server cannot answer a write yet (Odin, until it is receipt-capable) opts into the explicit send-only mode per call (`sendOnly: true`), which resolves the distinct outcome `sent` once the transport has acknowledged the put and never `admitted`. The Idunn presence publisher is send-only by its own function (`sendPresenceDocument`, not the `sendOnly` option): the same `sent` result, plus a rejection if a refusal naming the put (or naming nothing) arrives by the transport ack. Receipts and send-only are both opt-in, neither is the default. The C# and Rust clients of #55 to #58 keep the window-success until their conformance work lands, and callers of those must not read it as admission.
+
+## Vectors
+
+`write-receipt-vectors.json`: `constants` (the named windows and retention), `contentHash` (worked dedupe hashes), `dedupe` (server replay cases for rule 5), `wire` (MessagePack hex plus the decoded message for each new frame; the bytes are spec-authored with msgpack-python and every runtime's first conformance PR re-captures them with its own encoder and must match), `schemaInvalid` (frames that must be refused by a validator, each with why), and `blankFields` (server input cases for the Required fields rule: which document fields make a put unreadable, which are accepted), `admittedMessageId` (the `write_admitted` id rule above: code-point lists, each marked refuse or accept; a lone surrogate, and a frame that repeats the key, are carried as whole frames in `wireHex`, because a lone surrogate is not valid UTF-8 and only some runtimes' strings can hold it; `write-admitted-message-id-ranges.json` lists every range of the embedded tables, and each runtime probes the first and last point of each range and the points either side), `scenarios` (event replays with the outcome each write must settle as; the clock is abstract; each case names its window constant). A conformant client passes every scenario; a conformant server's answers for the same inputs satisfy server rules 1 to 7.
+
+## Conformance status
+
+| Server class | Advertises both frames | Server-wide memory budget (MAY, Remembered-write limits) |
+|---|---|---|
+| `CultNetDatabaseServer` | yes | not implemented: only the per-session limit of 1024 applies |
+| Shard write forwarder | yes | not implemented: only the per-session limit of 1024 applies |
+| Rust RUDP document server | yes | implemented (32 MiB default, `max_remembered_write_bytes`) |
+| C# RUDP schema server (`CultNetRudpSchemaServer`, `src/GameCult.Networking/CultNetRudpSchemaServer.cs`) | no | n/a |
+
+Advertising is per server class, not per transport. A class advertises both frames in its hello only if it implements the receipt rules end to end; the C# RUDP schema server stays "no" until it answers writes with receipts.
+
+Cross-runtime check: `packages/cultmesh-ts/test/interop/write-receipt-interop.test.ts` (`npm run test:interop` in `packages/cultmesh-ts`) runs the TypeScript client (`WriteTracker`, the decoder, the one-shot writer) against the real Rust RUDP document server and the real `CultNetDatabaseServer` over loopback, one scenario set against both. Known gap it records as a todo: the Rust RUDP document server refuses every delete (`write_not_authorized: the server does not take deletes`), where this spec has an admitted delete receipted like a put.
+
+## Conformance follow-ups (not in this PR)
+
+C# server and client, Rust, TypeScript, Python, Kotlin: emit and parse the two frames; hello capability; tri-state client outcome; replace the #55 to #58 window-success; re-capture the wire vectors in each runtime. Server write paths include the shard write forwarder (rule 6) and the Odin catalog.

docs/cultmesh-ts-content-map.md

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

docs/cultnet-rudp-ack-cut.md

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

docs/document-variants-cut.md

@@ -701,6 +701,7 @@ checked by the operator in the editor.
 - Run `MintElementIds` once over `GameData/Aetheria.cc`.
 - AetherDb migrations skip variants or use the variant API (Q1a).
 - Re-author the families listed in section 6.
+- Hull families live in each ship's own `.cc`, not in `GameData/Aetheria.cc`, because hulls are mod-owned packages (Nibu's ruling about her data, 2026-11-11, #minds).
 
 ### C5. CultNet deltas (C# reference)
 
@@ -1608,7 +1609,7 @@ The one door per runtime, and who walks through 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).
+- **Known gaps.** `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).
 
 ### B. Existence and links (what "nothing at the path" means)
 
@@ -1639,7 +1640,7 @@ The one door per runtime, and who walks through it:
 - **Shared paths.** Open, commit, Mesh read and write.
 - **Cut line.** `mesh-single-file-reader` h1 (the C# clause). Rust, TS and Python were correct by construction of their reads.
 - **Pinned by.** C#: `ADirectoryAtTheStorePathIsAnIoErrorOnOpenAndOnCommitNotAnEmptyStore` (`StoreReadabilityTests.cs:236`). Mesh: `ADirectoryAtThePathIsAnIoErrorOnReadAndWriteAndIsLeftAlone` (:149). Rust: `a_write_over_a_directory_stops_at_the_read_and_leaves_no_staging_file` RS:5726.
-- **Known gaps.** TS and Python have no test for a directory at the store path. No follow-up is registered; the natural home is `write-set-vectors` with the other readability pins.
+- **Known gaps.** None open. The `@directory` manifest row is walked by all four runtimes: every operation including delete is refused and leaves the directory untouched; Rust pins an I/O failure rather than a typed unreadable store.
 
 ### E. Lock
 

docs/document-variants-id-sweep.md

@@ -4,6 +4,8 @@ Data for the per-consumer sweep in docs/document-variants-cut.md, C2. Every obje
 
 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.
 
+A type that already has a readable string id keeps it and adds a trailing keyed string member marked `[CultElementId(nameof(ExistingId))]`; see the Element ids section of `src/GameCult.Caching/README.md`.
+
 Lines: `Type  file:line  (via Owner.Member)`, paths relative to the consumer root.
 
 

docs/nuget-packaging.md

@@ -25,5 +25,13 @@ 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-v2.0.0
+https://github.com/GameCult/CultLib.git?path=/unity/org.gamecult.cultlib#cultlib-unity-v3.0.0
 ```
+
+## Rolling back across the store format
+
+A consumer that upgrades and writes a store holding an element id leaves a
+`cultcache.store.v3` single-file store (`v5` directory store). Refusal by name depends on the store kind and the pin. A **directory** store (`v5`) is refused by every Unity pin from `cultlib-unity-v1.0.57` and `caching-unity-v1.2.0` on (the earliest tags of each line whose `DirectoryMessagePackBackingStore` reads only the `v4` stamp: "only ... is readable"). A **single-file** store (`v3`) is refused only from `cultlib-unity-v2.0.0` and `caching-unity-v2.0.0`: `cultlib-unity-v1.0.61` and `caching-unity-v1.4.0` read the header string and never compare it. The NuGet line (`cultlib-v1.0.32`, the last `cultlib-v` tag) refuses neither: its directory store writes `cultcache.store.v1.directory` and never checks the stamp on read. Rolling back a single-file store to any of those pins reads it silently, drops the ids, and can rewrite the elements without them. That is the dangerous case. There is
+no general carry-back; restore from a copy taken before upgrading, and upgrade
+readers before writers. Detail: the Store format and rollback section of
+`src/GameCult.Caching/README.md`.

docs/runtime-parity-scope.md

@@ -16,7 +16,7 @@ Cross-runtime parity has three layers:
   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
+  Python and Rust read it and keep the header, and the C# runtime decides the mark from content, and these runtimes never drop it. A C# reader from `cultlib-unity-v2.0.0` on refuses a v3 single-file store it cannot read (earlier pins do not)
   (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

docs/semver-policy.md

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

docs/start/README.md

@@ -44,7 +44,7 @@ using MessagePack;
 public sealed class Item
 {
     [Key(0)] [CultName] public string Name = string.Empty;
-    [Key(1)] [CultIndex] public string Category = string.Empty;
+    [Key(1)] public string Category = string.Empty;
     [Key(2)] public int Value;
 }
 
@@ -94,7 +94,6 @@ const itemDocument = defineDocumentType({
   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);
 
@@ -168,8 +167,8 @@ fn first_call() -> anyhow::Result<()> {
 
 ## 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
+A document is a definition with an encoder and decoder; `name=` registers the name lookup, `indexes=` unique lookups and
+`roles=` many-row selection aliases. 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
@@ -195,7 +194,6 @@ item_doc = define_document_type(
     encode=lambda item: asdict(item),
     decode=lambda raw: Item(**raw),
     name="name",
-    indexes={"category": "category"},
 )
 
 

docs/studio-grouping-cut.md

@@ -33,9 +33,9 @@ Recovered from the legacy "Database Tools" window (Aetheria `d3db1730`,
 **The attribute is not `[CultIndex]`.** `[CultIndex]` means unique (operator, 2026-09-30;
 `CultDocumentContracts.cs:34`). Grouping is `CultInspectorGroupByAttribute`, in
 `CultInspectorAttributes.cs`, read only by `CultInspectorModel`. It changes no schema id,
-catalog entry, index, or store byte. The index cut's deletion of grouping-only `[CultIndex]`
-declarations (CultMesh, Geometry) adds no `[CultInspectorGroupBy]` in their place: those are
-service stores, not Studio-authored catalogs.
+catalog entry, index, or store byte. The index cut converts the grouping and selection `[CultIndex]`
+declarations (CultMesh, Geometry) to `[CultRole]` rather than deleting them, and adds no
+`[CultInspectorGroupBy]` in their place: those are service stores, not Studio-authored catalogs.
 
 ### Invariants
 

docs/write-ownership-map.md

@@ -33,13 +33,16 @@ Probes: scratch tests in this worktree, removed. C# filtered runs on Starfire (o
 
 | 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" |
+| P1 cache {A,B}: B at k, then A at k | **C**: B's record replaced, k now A's id | R `SchemaConflictError` (cultcache-ts: one record per key) | R `SchemaConflictError` naming k, A not written (leaf cut) | R `SchemaConflictError`, A's write refused, B kept (was C, both live) |
+| P2 cache {A} only, store holds B at k, write A at k | R `CultSchemaConflictException` (B is foreign, carried) | R `SchemaConflictError` at write (foreign loads, carried; cultcache-ts) | R `SchemaConflictError` (B loads as foreign, carried; leaf cut) | R `SchemaConflictError` (B is foreign, carried; the load admits it; was R at load) |
 | 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) |
 
+The C#-written probe the leaves are held to is `tests/vectors/key-identity` (12 rows: retype, foreign carry, key in two stores), walked by
+`KeyIdentityVectorTests`; each leaf cut corrects its own column above.
+
 What this establishes:
 
 - C#: one record per key. The only path that retypes is the cache arm (P1): `CacheBackingStore.RefuseUndeclared`
@@ -52,12 +55,22 @@ What this establishes:
 - 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`.
+- TypeScript and Python: records are keyed by `(type, key)` (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). Neither carries
+  a foreign record; a store holding an unregistered type does not load (P2). So neither has a "write meets another type's
+  record" path to fix: bringing the ruling to them first needs C#'s key identity (one record per key) and C#'s foreign
+  carry, parity changes of their store model, not a write-ownership rule (follow-up `variants:follow_up:leaf-key-identity-parity`).
+- Rust is that follow-up's first leaf cut (`cut-leaf-key-identity-rs`). The cache keeps its `(type, key)` map; one judge
+  (`refuse_retype`) refuses another registered type at a key the cache holds, or any write at a key a store carries
+  foreign, on every write path, pull and SoA load, comparing types, not the ids envelopes claim. At a key the cache does not
+  hold (a fresh key, or one another writer filled after this cache's pull) the single-file store's commit guard judges by
+  the stored and claimed schema ids, so an envelope claiming another registered type's id is refused earlier, at every
+  envelope admission (`refuse_claimed_id`, the pull's own `resolve_registered_type` lookup); an id naming no registered type
+  passes, trusted as claimed: an envelope under such an id can replace another writer's record stored under it at a key
+  this cache does not hold, or be served as another type by a reader that registers the type the id names (Soul g8a, g8c,
+  open: which ids a Rust type owns is not declared to CultCache). Store-level writers called directly (`push`,
+  `insert_entry_if_absent`, compare-and-swap) trust the claimed id.
+  The cache carries an unregistered type's records as foreign and walks the vector's 12 rows.
 - 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.
 

package-lock.json

@@ -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",
@@ -1204,7 +1204,7 @@
       "version": "0.4.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
         "@gamecult/cultnet-ts": "^0.3.0"
       },
       "devDependencies": {
@@ -1221,7 +1221,7 @@
       "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
         "@gamecult/cultnet-ts": "^0.3.0",
         "koffi": "3.3.0"
       },
@@ -1239,7 +1239,7 @@
       "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"
       },

packages/cultcache-py/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+
+- `read_payload_tree(type_name, payload, decoder=None)`: the exported owner of the one-value, depth-first payload read that `decode_payload` uses, for payloads read outside a definition (`cultnet-py`'s witness bundle decode needs it, so `cultnet-py` now requires `cultcache-py>=0.4.0`). The manifest version is 0.4.0, the minor these Unreleased breaking changes imply, set in this change so the workspace install resolves the new bound; the `## Unreleased` heading becomes `## [0.4.0]` when it is tagged.
+
 ### 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.
@@ -9,7 +13,18 @@
 
 ### 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 record whose payload carries a slot past its reader's declared slots, at any depth (the document, a nested record, a list element, a union arm, a unit arm), is read, held read-only, and every write or removal of its key (`put`, `put_global`, `update`, `put_envelope`, `put_envelopes`, `delete`, `delete_global`) is refused with `SchemaConflictError` before any store is touched (`cultlib-gaps:ruling:extra-trailing-slots`). Reading dropped those slots silently and the next write shed them. `SchemaConflictError.unread_slots` is an `UnreadSlots(type_name, slot_count, declared_count, occurrences, depth0_only)` and the message names the type and both counts, never a slot value. A depth-0 mark is consented, and the record writable, only when the record is stored under an id the document lists in `compatible_schema_ids` and that id's catalog entry has slots past the document's, covering the mark's slot count (`cultlib-gaps:ruling:slot-mark-consent`); a nested mark, or a mark under the document's own id, keeps the record read-only whatever is declared. Missing trailing slots keep their declared defaults. An untouched marked record keeps its stored bytes through every other write. Added `CultCache.is_writable(document, key)` (advisory; the write still decides: it also answers False for a foreign-carried key, for a key held as a type the document does not own, and for a global document at a non-global key; `delete` asks the same judges, so removing a key held as another type is refused with `SchemaConflictError` unless the document owns that record's schema id (its own or one it lists compatible), in which case the removal removes that record, its file row and its lookups, as a write of the key would replace it; it returned silently and removed nothing), `DocumentDefinition.decode_payload_marked`, and `UnreadSlots`. A document with a custom `decode` (no slot codec) never marks. A store holding a variant record is still unreadable here. Implies a minor bump while the version is 0.x (0.3.0 to 0.4.0): code that wrote back a record from a newer writer now gets `SchemaConflictError`.
+- A payload is one MessagePack value: `DocumentDefinition.decode_payload` refuses bytes after it, by count, with `ValueError` `<type> payload has N bytes after its first MessagePack value (refused on read).` (never the bytes, never the depth refusal; a payload that ends early stays the decoder's), as the C# reference does (`tests/vectors/union-parity/bytes-after-outcomes.msgpack`). It raised `msgpack.ExtraData` (a `ValueError`, so only a caller naming `msgpack.ExtraData` is affected); this is a minor-version bump while pre-1.0. The refused set is unchanged. Cache loads, `get` and every definition built on the MessagePack decoder go through it; a user `payload_decoder` that raises `ExtraData` is refused the same way. Depth is judged first, so a value nested past 256 with a tail is the depth refusal, as in C#.
+- A cache holds one record per key whatever its type (`variants:ruling:cache-refuses-retype`). A `put`, `put_envelope`, `put_envelopes` or `put_global` of a second type under a key the cache holds, or under a key a store carries foreign, is refused with `SchemaConflictError` naming the key, even with no store, and changes nothing; retype a key by deleting it, then putting the new type. A write may replace another registered type's record only when the written type owns its schema id (declares it or lists it compatible) and both types share one home store. A load that reads one key from two stores, whatever the types, is refused with `CultCacheError` naming the key and both types, and admits nothing. A store that holds a record no registered type claims now loads and is carried: the cache does not serve it, the store keeps its bytes through every write, `delete` or `put` at its key is refused with `SchemaConflictError`, and registering a type that declares its schema id claims it at the next load. It raised `CultCacheError` "Unknown persisted document type". Two global types share the key `__global__`, so a second global type in one cache is now refused, and a store that already holds two global types at `__global__` (a JSONL store written by caches that never pulled could produce one) no longer loads: the pull raises `CultCacheError` and admits nothing. C# refuses a second persisted global on pull the same way (`cultcache-store-composition.md`, "Globals never invented"); repair such a file by deleting one of the two records with the runtime that wrote it.
+- Added `foreign_records()` and the frozen `ForeignRecord(key, schema_id, schema_name, stored_at)`, sorted by key in UTF-16 code-unit order. `stores.retyped` and `stores.written_owns` lose their underscore: the cache judge and the single-file store's commit guard ask one predicate.
+
+- A single-file store holding two records under one key is unreadable: the v1 reader and the legacy envelope-array reader refuse it with `StoreUnreadableError` (a key is compared by its exact code points, no case folding or normalisation). A catalog slot whose canonical schema is not a string is refused the same way. A store that loaded before can now be refused: repair it with the runtime that wrote the duplicate.
+- A `put` or `push_all` that would land a second type under a key the store holds is refused with `SchemaConflictError`, and the file is left as it was. Retype a key by deleting it, then putting the new type. A write replaces the record at a key only when the written type owns it: its catalog entry declares the stored schema id (its own, or one it lists compatible), so a renamed type that lists the old id compatible may replace the record, or it has the stored record's schema name. This runtime does not compare shapes, so a same-name type is never refused for dropping persisted slots as C# refuses it.
+- Writes of the same type replace by key: the last record wins, in a batch as in the file.
+
+- `indexes` are unique, as C# `[CultIndex]`: a write, load or `register_index` that leaves two records of a type holding one non-blank value under one alias is refused (`CultCacheError`) naming both keys and the alias, and writes nothing. Index text is the C# canonical text (`True`/`False`, integers as digits, floats as the exact expansion, blank values never indexed), so an empty or whitespace string is no longer a value. A new `roles` map names the many-row selection aliases (never indexed for lookup, same catalog `index_alias`). Classify every `indexes` key per the README before updating. The verdict is the contract, the text is informational.
+
+- A single-file store written as `cultcache.store.v3` is read and written: a store the C# runtime marked v3 (it holds a record with an element id: an owned list element with a `[CultElementId]` member) keeps its header here, and is carried through every rewrite with its ids; this runtime never drops the mark. A runtime from before this change refuses a v3 store by name. Rolling back to an older release after a store has been written as v3 is one-way: there is no carry-back, so restore from a copy taken before upgrading.
 - 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.

packages/cultcache-py/README.md

@@ -19,7 +19,12 @@ discovery, sessions, local server) build on it, mirroring `cultcache-rs` /
   `[format, schemaCatalog, records]`
 - records store raw MessagePack payload bytes under schema-catalog identity
 - payloads decode only through the registered document definition for that type
-- unknown persisted types fail closed
+- a payload is exactly one MessagePack value: bytes after it are refused on read, by count
+- a cache holds one record per key whatever its type: a write of a second type at a held key is refused with
+  `SchemaConflictError` (in memory too), and two stores holding one key refuse the load
+- a store record no registered type claims loads and is carried as foreign: `cache.foreign_records()` lists it, the store
+  keeps its bytes through every write, a write or removal at its key is refused, and registering a type that declares its
+  schema id claims it at the next load
 - global documents are singleton-style per type
 - one home store per document type: a store added with `add_backing_store`
   owns its types, otherwise the generic store is the home; a type claimed by a
@@ -73,7 +78,7 @@ store.
 - `register_document_type(...)`
 - `register_registry(...)`
 - `register_name_lookup(...)`
-- `register_index(...)`
+- `register_index(...)` (a unique index)
 - `add_backing_store(...)`
 - `add_generic_store(...)`
 - `pull_all_backing_stores()`
@@ -93,8 +98,36 @@ store.
 - `update_global(...)`
 - `delete(...)`
 - `delete_global(...)`
+- `is_writable(document, key)` (advisory: would a write or removal of the key be refused; see below)
 - `snapshot()`
 
+## Indexes And Roles
+
+`indexes=` are unique lookups (variants:ruling:unique-indexes; C# `[CultIndex]`): within one document type and one alias
+no two records hold one non-blank value, judged on the result of every write (a batch is judged whole, so a swap inside
+one `put_envelopes` lands) and of every load and `register_index`. A refusal is a `CultCacheError`,
+`Records <k1> and <k2> (<schema name>) both hold unique index '<alias>'; an index value names one record.`, keys in
+ordinal order, never the value; it writes nothing, and a refused load or registration installs nothing. The contract is
+the verdict; the text is informational. Blank values (absent, empty, or only C# `White_Space` characters) are never
+indexed and never conflict. Two types may share an alias and a value. Values compare as the C# canonical text: strings as
+is (never trimmed), `True`/`False`, integers as digits, a non-integral float as its exact decimal expansion, NaN and
+infinities no value.
+
+`roles=` name selection aliases (C# `[CultRole]`): many records may share a value, nothing is indexed or refused,
+`get_by_index` on a role answers `None`, and the member's catalog `index_alias` is the same either way, so catalog bytes
+do not move. An alias is declared in one of the two. `CultMeshDatabase.watch_by_index` reads `indexes` only.
+
+Migrating an existing `indexes` key, per key, before bumping:
+
+1. Nothing looks records up by the key (`get_by_index`, `get_key_by_index`, `node.get_by_index`, `watch_by_index`): move it to `roles`.
+2. Something looks it up: it stays unique only when two live records can never hold one non-blank value (the record key
+   is derived from that value alone, or it is an outside identity: email, sku, external id). Enums, statuses, kinds,
+   categories, parent or foreign ids, shared hashes and timestamps are roles; select them with `get_all` plus a filter.
+3. Open each real `.cc` once with the new definitions. A refusal names both keys and the alias and writes nothing.
+
+Misclassifying: a role declared unique makes a store that holds a shared value refuse to open until the key is
+reclassified; a unique key declared a role answers no lookups and stops refusing duplicates.
+
 ## Persistence Model
 
 Backing stores persist envelopes, not caller domain objects. The cache decodes payloads through registered document definitions and rejects unknown type discriminators. This keeps Python's dynamic runtime from turning persistence into an open polymorphic sewer with a cheerful docstring.
@@ -112,6 +145,10 @@ used by the TypeScript, Rust, and C# runtimes:
 
 Large corpora should use a sharded store or a real database. A single snapshot file is a scalpel, not a forklift.
 
+## Store format and rollback
+
+A store whose elements hold an id is marked `cultcache.store.v3` by the C# runtime. This runtime reads and writes a v3 single-file store, keeps the header it read and carries the ids through a rewrite; it never drops the mark, so it has no carry-back. A cultcache-py from before element ids refuses a v3 store by name, so rolling back to it after a store has been written as v3 is one-way: restore from a copy taken before upgrading, and upgrade every reader before any writer. (The C# line is different: CultLib 1.x does not refuse; see the GameCult.Caching README.)
+
 ## DatabaseEntry Slot Contract
 
 For cross-runtime cache entries, use `define_database_entry_type(...)` instead
@@ -145,6 +182,16 @@ The payload is a MessagePack array. Field keys are durable slot indexes:
 - newly added fields should use new keys
 - fields with defaults tolerate missing or nil slots when older payloads are read
 
+A payload carrying a slot past the slots a reader declares, at any depth (the document, a nested record, a list element, a
+union arm, a unit arm), was written by a newer build. It is read, and the record is held read-only: `put`, `update`,
+`put_envelope(s)`, `delete` and their global forms refuse its key with `SchemaConflictError` before any store is touched, and
+`SchemaConflictError.unread_slots` is an `UnreadSlots(type_name, slot_count, declared_count, occurrences, depth0_only)` naming the
+first type read with extra slots (never a slot value). `CultCache.is_writable(document, key)` answers the same question before
+the write: False for such a record, for a key a store carries foreign, and for a key held as another type's record; the write
+still decides. `DocumentDefinition.decode_payload_marked(payload)` returns the value and its `UnreadSlots` (or None). Declaring the
+stored id in `compatible_schema_ids` consents to the loss of depth-0 slots that id's catalog entry reports; a nested mark never is.
+A store keeps a read-only record's bytes through every other write. A document with a custom `decode` never marks.
+
 That matches the Rust `#[derive(DatabaseEntry)]` formatter shape and the C#
 `[Key(n)]` intent: schema evolution comes from stable field slots, not source
 member order.

packages/cultcache-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cultcache-py"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python CultCache runtime for GameCult typed state."
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -1,7 +1,7 @@
 from .backing_store import BackingStore, CultCacheEnvelope
 from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember
 from . import leaves
-from .cache import CultCache, CultCacheBuilder
+from .cache import CultCache, CultCacheBuilder, ForeignRecord
 from .documents import (
     MAX_PAYLOAD_DEPTH,
     MAX_SLOT_KEY,
@@ -9,12 +9,14 @@ from .documents import (
     DatabaseEntryField,
     DocumentDefinition,
     UnionArm,
+    UnreadSlots,
     database_entry_field,
     define_database_entry_type,
     define_document_registry,
     define_document_type,
     define_record_codec,
     define_union,
+    read_payload_tree,
 )
 from .leaves import SlotCodec
 from .stores import JsonLinesBackingStore, SchemaConflictError, SingleFileMessagePackBackingStore, StoreUnreadableError
@@ -29,6 +31,7 @@ __all__ = [
     "CultCacheSchemaCatalogMember",
     "DatabaseEntryField",
     "DocumentDefinition",
+    "ForeignRecord",
     "JsonLinesBackingStore",
     "MAX_PAYLOAD_DEPTH",
     "MAX_SLOT_KEY",
@@ -37,6 +40,8 @@ __all__ = [
     "SlotCodec",
     "StoreUnreadableError",
     "UnionArm",
+    "UnreadSlots",
+    "read_payload_tree",
     "leaves",
     "database_entry_field",
     "define_database_entry_type",

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

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import functools
+import math
 import threading
+from decimal import Decimal
 from dataclasses import dataclass, field, replace
-from typing import Any, Callable, Generic, TypeVar
+from typing import Any, Callable, Generic, Iterable, TypeVar
 
 from .backing_store import BackingStore, CultCacheEnvelope
-from .documents import DocumentDefinition, extract_value
-from .stores import SchemaConflictError
+from .documents import DocumentDefinition, UnreadSlots, extract_value
+from .stores import SchemaConflictError, retyped, written_owns
 
 T = TypeVar("T")
 F = TypeVar("F", bound=Callable[..., Any])
@@ -52,6 +54,52 @@ class CultCacheError(RuntimeError):
     pass
 
 
+# Blank is no value: empty or only C# White_Space characters (the 25 chars string.IsNullOrWhiteSpace is true for).
+# An explicit set, not str.isspace(): Python also counts U+001C-001F, which C# does not, and omits nothing C# counts.
+_BLANK_INDEX_CHARS = frozenset(
+    chr(code)
+    for code in (
+        *range(0x09, 0x0E),
+        0x20,
+        0x85,
+        0xA0,
+        0x1680,
+        *range(0x2000, 0x200B),
+        0x2028,
+        0x2029,
+        0x202F,
+        0x205F,
+        0x3000,
+    )
+)
+
+
+def _utf16_order(text: str) -> bytes:
+    """Sorts as C# StringComparer.Ordinal does: by UTF-16 code unit, not code point."""
+    return text.encode("utf-16-be", "surrogatepass")
+
+
+def index_text(value: Any) -> str | None:
+    """The canonical text of an index value, as C# IndexValue and RenderCanonicalNumber, or None when it names no
+    value: a string is as is (never trimmed), a boolean is `True`/`False`, an integer is its digits, a non-integral
+    finite float is its exact decimal expansion, NaN and infinities and blank strings are no value."""
+    if value is None:
+        return None
+    if isinstance(value, bool):  # before int: bool is an int subclass
+        return "True" if value else "False"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            return None
+        if value.is_integer():
+            return str(int(value))  # -0.0 is 0
+        text = format(Decimal(value), "f")  # Decimal(float) is exact
+        return text.rstrip("0").rstrip(".") if "." in text else text
+    text = value if isinstance(value, str) else str(value)
+    return None if all(char in _BLANK_INDEX_CHARS for char in text) else text
+
+
 @dataclass
 class _State:
     documents: dict[str, DocumentDefinition[Any]] = field(default_factory=dict)
@@ -72,6 +120,24 @@ class _State:
     # of that global removes it from the home store. Remove once no store holds a global under a key
     # other than GLOBAL_KEY.
     legacy_global_keys: dict[str, str] = field(default_factory=dict)
+    # The records the last pull read that no registered type claims, sorted by key. Derived from the pull and swapped with the
+    # rest of the state, written nowhere else; it decides only refusals at its keys. A store keeps their bytes.
+    foreign: list["ForeignRecord"] = field(default_factory=list)
+    # The records held read-only, by key (a key holds one record) with the type that holds it: the payload carried slots past the
+    # declared ones and nothing consents to the loss. Derived from the load or the write that admitted the record and swapped with
+    # the rest of the state; it decides only refusals at its keys, and any other key is absent.
+    unread: dict[str, tuple[str, UnreadSlots]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ForeignRecord:
+    """A record a store holds that no registered type claims: the cache does not serve it, refuses a write or a removal at its
+    key, and a store keeps its bytes. Registering a type that declares its schema id claims it at the next load."""
+
+    key: str
+    schema_id: str
+    schema_name: str
+    stored_at: str
 
 
 @dataclass(frozen=True)
@@ -186,6 +252,8 @@ class CultCache:
     @_mutating
     def register_index(self, document: DocumentDefinition[Any], index: str, extractor: str | Any) -> None:
         self._assert_registered(document)
+        if index in document.roles:
+            raise CultCacheError(f"Index '{index}' of {document.type} is declared as a role; a role is never a unique index.")
         index_extractors = {type: dict(indexes) for type, indexes in self._state.index_extractors.items()}
         index_extractors.setdefault(document.type, {})[index] = extractor
         self._install_lookups(self._state.name_extractors, index_extractors)
@@ -195,7 +263,11 @@ class CultCache:
     ) -> None:
         """Derives every lookup under the candidate extractors, then installs extractors and lookups
         together. An extractor that raises on a held value installs nothing."""
-        names, indexes, lookup_keys = self._derive_lookups(self._state.values, name_extractors, index_extractors)
+        names, indexes, lookup_keys = self._derive_lookups(
+            [(type, key, value) for type, values in self._state.values.items() for key, value in values.items()],
+            name_extractors,
+            index_extractors,
+        )
         (
             self._state.name_extractors,
             self._state.index_extractors,
@@ -263,19 +335,29 @@ class CultCache:
         structures, running every check and every user extractor; the cache's state is replaced
         only once that build finishes, so a refused load admits nothing."""
         loaded_values: dict[str, dict[str, Any]] = {}
+        read_values: dict[tuple[str, str], Any] = {}  # (type, key) -> value, one per key, the last read wins; the judge is order-free
         loaded_envelopes: dict[str, dict[str, CultCacheEnvelope]] = {}
         loaded_legacy_global_keys: dict[str, str] = {}
         routes, generic = self._state.stores_by_type, self._state.generic_store
         seen_globals: set[str] = set()
+        foreign: list[ForeignRecord] = []
+        loaded_unread: dict[str, tuple[str, UnreadSlots]] = {}
+        type_at_key: dict[str, tuple[str, int]] = {}  # one record per key across every store: its type (or schema name) and store
         stores: list[BackingStore] = []
         for candidate in [*self._state.stores_by_type.values(), self._state.generic_store]:
             if candidate is not None and all(candidate is not store for store in stores):
                 stores.append(candidate)
-        for store in stores:
+        for position, store in enumerate(stores):
             for envelope in store.pull_all():
                 document = self._resolve_document_for_envelope(envelope)
                 if document is None:
-                    raise CultCacheError(f"Unknown persisted document type: {envelope.type}")
+                    entry = envelope.catalog_entry
+                    held_name = entry.schema_name if entry is not None else envelope.type
+                    self._claim_key(type_at_key, envelope.key, held_name, position)
+                    foreign.append(
+                        ForeignRecord(envelope.key, envelope.schema_id or envelope.type, held_name, envelope.stored_at)
+                    )
+                    continue
                 if envelope.type != document.type:
                     envelope = CultCacheEnvelope(
                         key=envelope.key,
@@ -298,12 +380,16 @@ 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)
+                self._claim_key(type_at_key, envelope.key, envelope.type, position)
+                arrived, envelope = envelope, self._stamped(document, envelope)
+                value, unread = self._decode_marked(document, arrived)
+                if unread is not None:
+                    loaded_unread[envelope.key] = (envelope.type, unread)
                 loaded_values.setdefault(envelope.type, {})[envelope.key] = value
+                read_values[(envelope.type, envelope.key)] = value
                 loaded_envelopes.setdefault(envelope.type, {})[envelope.key] = envelope
         loaded_names, loaded_indexes, loaded_lookup_keys = self._derive_lookups(
-            loaded_values, self._state.name_extractors, self._state.index_extractors
+            [(type, key, value) for (type, key), value in read_values.items()], self._state.name_extractors, self._state.index_extractors
         )
         # Plain attribute assignments: nothing fallible runs once the swap begins.
         (
@@ -313,7 +399,30 @@ class CultCache:
             self._state.indexes,
             self._state.lookup_keys,
             self._state.legacy_global_keys,
-        ) = (loaded_values, loaded_envelopes, loaded_names, loaded_indexes, loaded_lookup_keys, loaded_legacy_global_keys)
+            self._state.foreign,
+            self._state.unread,
+        ) = (
+            loaded_values,
+            loaded_envelopes,
+            loaded_names,
+            loaded_indexes,
+            loaded_lookup_keys,
+            loaded_legacy_global_keys,
+            sorted(foreign, key=lambda record: _utf16_order(record.key)),
+            loaded_unread,
+        )
+
+    @staticmethod
+    def _claim_key(type_at_key: dict[str, tuple[str, int]], key: str, type: str, store: int) -> None:
+        """A key holds one record whatever its type, across every store a load reads. The refusal names the key and both types,
+        never a payload."""
+        held, held_store = type_at_key.setdefault(key, (type, store))
+        if held != type or held_store != store:
+            raise CultCacheError(f"Record {key!r} is held by both {held} and {type}: a key holds one record; the load admitted nothing.")
+
+    def foreign_records(self) -> list[ForeignRecord]:
+        """The records the last load read that no registered type claims, sorted by key (UTF-16 code-unit order)."""
+        return list(self._state.foreign)
 
     def get(self, document: DocumentDefinition[T], key: str) -> T | None:
         self._assert_registered(document)
@@ -391,9 +500,9 @@ 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)
+        arrived, envelope = envelope, self._stamped(document, envelope)
+        value, unread = self._decode_marked(document, envelope)
+        self._write(document, [(envelope, value)], batch=False, unread={envelope.key: unread})
         return value
 
     @_mutating
@@ -401,13 +510,33 @@ class CultCache:
         self._assert_registered(document)
         values: list[T] = []
         stamped: list[CultCacheEnvelope] = []
+        unread: dict[str, UnreadSlots | None] = {}
         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(stamped, values)), batch=True)
+            value, unread[envelope.key] = self._decode_marked(document, stamped[-1])
+            values.append(value)
+        self._write(document, list(zip(stamped, values)), batch=True, unread=unread)
         return values
 
+    @staticmethod
+    def _decode_marked(document: DocumentDefinition[Any], held_as: CultCacheEnvelope) -> tuple[Any, UnreadSlots | None]:
+        """The payload decoded under the document, with the mark of any slot it carried past the declared ones, or no mark when the
+        loss is consented. `held_as` is the envelope under the id the record is stored under: a load's arrival, a write's stamped
+        envelope, so a key is writable in memory exactly when it is after a reload. A depth-0 mark is consented only when that id is
+        one the document lists compatible and its catalog entry has slots past the document's that cover the mark's slot count (the
+        loss a compatible-id declaration consents to, cultlib-gaps:ruling:slot-mark-consent). Any other mark keeps the record read-only."""
+        value, slots = document.decode_payload_marked(held_as.payload)
+        if slots is None:
+            return value, None
+        entry, stored = document.catalog_entry(), held_as.catalog_entry
+        if slots.depth0_only and stored is not None and held_as.schema_id in entry.compatible_schema_ids and held_as.schema_id != entry.schema_id:
+            declared = {member.slot for member in entry.members}
+            reported = [member.slot for member in stored.members if member.slot not in declared]
+            if reported and slots.slot_count <= max(reported) + 1:
+                return value, None
+        return value, slots
+
     @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
@@ -427,17 +556,32 @@ class CultCache:
             raise CultCacheError(f"Global document {document.type} must use key {GLOBAL_KEY}")
 
     def _write(
-        self, document: DocumentDefinition[Any], records: list[tuple[CultCacheEnvelope, Any]], *, batch: bool
+        self,
+        document: DocumentDefinition[Any],
+        records: list[tuple[CultCacheEnvelope, Any]],
+        *,
+        batch: bool,
+        unread: dict[str, UnreadSlots | None] | None = None,
     ) -> None:
         """Validates every record (home and name and index extractors included) before the store is
         touched; once the store accepts, applying to the cache has no fallible step."""
         type = document.type
+        # A batch naming a key twice lands the last record for it, as C# CultCacheBatch stages one operation per key. The
+        # judge, the store and the apply all read this one list.
+        records = list({envelope.key: (envelope, value) for envelope, value in records}.values())
+        self._refuse_unread([envelope.key for envelope, _ in records])
         name_extractor = self._state.name_extractors.get(type)
         index_extractors = self._state.index_extractors.get(type, {})
         admitted = [
             (envelope, value, self._lookup_keys_for(value, name_extractor, index_extractors))
             for envelope, value in records
         ]
+        displaced = self._refuse_retype(document, [envelope for envelope, _ in records])
+        self._refuse_index_sharing(
+            [(type, envelope.key, keys) for envelope, _, keys in admitted],
+            self._state.indexes,
+            {(type, envelope.key) for envelope, _ in records},
+        )
         store = self._store_for_type(type)
         legacy_key = self._state.legacy_global_keys.get(type)
         if store is not None:
@@ -451,16 +595,99 @@ class CultCache:
         values = self._state.values.setdefault(type, {})
         envelopes = self._state.envelopes.setdefault(type, {})
         lookup_keys = self._state.lookup_keys.setdefault(type, {})
+        for other, key in displaced:
+            self._drop(other, key)
         for envelope, value, keys in admitted:
             self._remove_lookups(type, envelope.key)
             values[envelope.key] = value
             envelopes[envelope.key] = envelope
+            # A held mark refused this write above, so a key reaching here carries none to clear.
+            if (mark := (unread or {}).get(envelope.key)) is not None:
+                self._state.unread[envelope.key] = (type, mark)
             lookup_keys[envelope.key] = keys
             if keys.name is not None:
                 self._state.names[(type, keys.name)] = envelope.key
             for index, index_value in keys.indexes.items():
                 self._state.indexes[(type, index, index_value)] = envelope.key
 
+    def _refuse_retype(self, document: DocumentDefinition[Any], written: list[CultCacheEnvelope]) -> list[tuple[str, str]]:
+        """The one key-identity judge (variants:ruling:cache-refuses-retype): a key holds one record whatever its type, so a write
+        may not land at a key this cache holds another type's record at, unless the written type owns that record's schema id
+        (the single-file store's commit guard asks the same question of the file), and may not land at a key a store carries
+        foreign. Returns the (type, key) records an owning write replaces; refuses, changing nothing, otherwise."""
+        replaced: list[tuple[str, str]] = []
+        foreign = {record.key: record for record in self._state.foreign}
+        for envelope in written:
+            carried = foreign.get(envelope.key)
+            if carried is not None:
+                raise self._foreign_refusal(carried)
+            for other, held_envelopes in self._state.envelopes.items():
+                held = held_envelopes.get(envelope.key)
+                if other == document.type or held is None:
+                    continue
+                if not written_owns(held, envelope) or self._store_for_type(other) is not self._store_for_type(document.type):
+                    raise retyped(held, envelope)
+                replaced.append((other, envelope.key))
+        return replaced
+
+    @_locked
+    def is_writable(self, document: DocumentDefinition[Any], key: str) -> bool:
+        """Whether a write or removal of the key by this document would pass the judges that run before any store is touched: False for
+        a record held read-only (its payload carried slots past the declared ones, at any depth, and nothing consents to the loss, so
+        writing it would drop data a newer writer stored), for a key a store carries foreign, and for a key held as another type's
+        record this document does not own. Advisory (the write still decides): it answers at call time, and a key nothing holds is
+        writable."""
+        self._assert_registered(document)
+        try:
+            self._refuse_at(document, key)
+        except (SchemaConflictError, CultCacheError):
+            return False
+        return True
+
+    def _refuse_at(self, document: DocumentDefinition[Any], key: str) -> list[tuple[str, str]]:
+        """The judges a write or removal of the key by this document passes before any store is touched, asked by `is_writable` and
+        by `delete`: a global document writes only its global key, a record held read-only is never replaced, and a key held as
+        another type's record or carried foreign is refused (`_refuse_retype`)."""
+        if document.global_document and key != GLOBAL_KEY:
+            raise CultCacheError(f"Global document {document.type} must use key {GLOBAL_KEY}")
+        self._refuse_unread([key])
+        entry = document.catalog_entry()
+        probe = CultCacheEnvelope.create(key=key, type=document.type, payload=b"", schema_id=entry.schema_id, catalog_entry=entry)
+        return self._refuse_retype(document, [probe])
+
+    def _refuse_unread(self, keys: list[str]) -> None:
+        """The one check every write and removal asks before any store is touched."""
+        for key in keys:
+            held = self._state.unread.get(key)
+            if held is None:
+                continue
+            type, slots = held
+            raise SchemaConflictError(
+                self._state.envelopes[type][key].schema_id or type,
+                [self._state.documents[type].catalog_entry().schema_name],
+                key,
+                message=(
+                    f"{self._state.documents[type].catalog_entry().schema_name} record {key} is read-only: {slots.type_name} was read with "
+                    f"{slots.slot_count} slots where this build declares {slots.declared_count} ({slots.occurrences} object(s) in the "
+                    "record). Writing it would drop data a newer writer stored; read it with types that declare those slots, or "
+                    "write it from that build."
+                ),
+                unread_slots=slots,
+            )
+
+    @staticmethod
+    def _foreign_refusal(record: ForeignRecord) -> SchemaConflictError:
+        return SchemaConflictError(
+            record.schema_id,
+            [record.schema_name],
+            record.key,
+            message=(
+                f"Record {record.key!r} is held by the store as a {record.schema_name} (schema id {record.schema_id!r}) that no "
+                "registered type claims; a write or removal there would replace what this cache cannot read. Register the type "
+                "that owns the schema id, or remove the record with the runtime that wrote it."
+            ),
+        )
+
     @staticmethod
     def _retire_legacy_global(store: BackingStore, type: str, legacy_key: str) -> None:
         """The first write of a global loaded from a legacy key removes that record in the same write. If
@@ -500,19 +727,29 @@ class CultCache:
 
     def _delete(self, document: DocumentDefinition[Any], key: str) -> None:
         self._assert_registered(document)
+        # A key held as another type's record this document owns is removed, as a write of the key would replace it (C# Remove is by key).
+        owned = self._refuse_at(document, key)
         store = self._store_for_type(document.type)
         legacy_key = self._state.legacy_global_keys.get(document.type) if key == GLOBAL_KEY else None
         if store is not None:
-            store.delete(document.type, key if legacy_key is None else legacy_key)
+            # One record per key: the owned record when this document does not hold the key, else its own, in one store call.
+            holder = owned[0][0] if owned else document.type
+            store.delete(holder, key if legacy_key is None else legacy_key)
         if legacy_key is not None:
             del self._state.legacy_global_keys[document.type]
-        self._remove_lookups(document.type, key)
+        for other, _ in owned:
+            self._drop(other, key)
+        self._drop(document.type, key)
+
+    def _drop(self, type: str, key: str) -> None:
+        """Removes the held record and its lookups from the cache's maps; the store is the caller's."""
+        self._remove_lookups(type, key)
         for by_type in (self._state.values, self._state.envelopes, self._state.lookup_keys):
-            held = by_type.get(document.type)
+            held = by_type.get(type)
             if held is not None:
                 held.pop(key, None)
                 if not held:
-                    by_type.pop(document.type, None)
+                    by_type.pop(type, None)
 
     @_mutating
     def delete_global(self, document: DocumentDefinition[Any]) -> None:
@@ -552,36 +789,76 @@ class CultCache:
         name = None if name_extractor is None else extract_value(value, name_extractor)
         indexes: dict[str, str] = {}
         for index, extractor in index_extractors.items():
-            index_value = extract_value(value, extractor)
+            index_value = index_text(extract_value(value, extractor))
             if index_value is not None:
-                indexes[index] = str(index_value)
+                indexes[index] = index_value
         return _LookupKeys(None if name is None else str(name), indexes)
 
     def _derive_lookups(
         self,
-        values_by_type: dict[str, dict[str, Any]],
+        records: list[tuple[str, str, Any]],
         name_extractors: dict[str, str | Any],
         index_extractors: dict[str, dict[str, str | Any]],
     ) -> tuple[_Names, _Indexes, _LookupKeysByType]:
-        """Builds name and index lookups for the given values in fresh dicts, touching no cache state."""
+        """Builds name and index lookups for the given (type, key, value) records, judged whole and order-free, in fresh dicts, touching no cache state."""
         names: _Names = {}
         indexes: _Indexes = {}
         lookup_keys: _LookupKeysByType = {}
-        for type, values in values_by_type.items():
-            name_extractor = name_extractors.get(type)
-            type_index_extractors = index_extractors.get(type, {})
-            for key, value in values.items():
-                keys = self._lookup_keys_for(value, name_extractor, type_index_extractors)
-                lookup_keys.setdefault(type, {})[key] = keys
+        landing: list[tuple[str, str, _LookupKeys]] = []
+        for type, key, value in records:
+            keys = self._lookup_keys_for(value, name_extractors.get(type), index_extractors.get(type, {}))
+            lookup_keys.setdefault(type, {})[key] = keys
+            landing.append((type, key, keys))
+        # Judged whole and order-free, over every type at once and on the file alone (never against what the cache held): a held value can
+        # have been mutated in place since it was admitted, and another process may have moved a value between records.
+        self._refuse_index_sharing(landing, {}, ())
+        for type in lookup_keys:
+            for key, keys in lookup_keys.get(type, {}).items():
                 if keys.name is not None:
                     names[(type, keys.name)] = key
                 for index, index_value in keys.indexes.items():
                     indexes[(type, index, index_value)] = key
         return names, indexes, lookup_keys
 
+    def _refuse_index_sharing(
+        self,
+        landing: list[tuple[str, str, _LookupKeys]],
+        held: dict[tuple[str, str, str], str],
+        replaced: Iterable[tuple[str, str]],
+    ) -> None:
+        """The one index rule (variants:ruling:unique-indexes): within one type and one unique alias, no two records hold one
+        non-blank value, judged on the state the admission would leave and never on staging, file or pull order. The holders
+        of a value are the landing keys projecting it plus the held key unless this admission replaces it. Of every
+        (type, alias, value) with two or more distinct holders, the refusal names the least by (alias, its least key, its
+        second-least key, schema name), each compared by UTF-16 code unit, never the value."""
+        released = set(replaced)
+        landed: dict[tuple[str, str, str], list[str]] = {}
+        for type, key, keys in landing:
+            for index, index_value in keys.indexes.items():
+                landed.setdefault((type, index, index_value), []).append(key)
+        violations: list[tuple[bytes, bytes, bytes, bytes, str, str, str, str]] = []
+        for (type, index, index_value), keys in landed.items():
+            held_key = held.get((type, index, index_value))
+            if held_key is not None and (type, held_key) not in released:
+                keys = [*keys, held_key]
+            distinct = sorted(keys, key=_utf16_order)
+            if len(distinct) > 1:
+                document = self._state.documents.get(type)
+                schema_name = (document.schema_name if document is not None else None) or type
+                violations.append(
+                    (_utf16_order(index), _utf16_order(distinct[0]), _utf16_order(distinct[1]), _utf16_order(schema_name),
+                     index, distinct[0], distinct[1], schema_name)
+                )
+        if violations:
+            *_, index, first, second, schema_name = min(violations, key=lambda violation: violation[:4])
+            raise CultCacheError(
+                f"Records {first} and {second} ({schema_name}) both hold unique index '{index}'; "
+                "an index value names one record."
+            )
+
     def _remove_lookups(self, type: str, key: str) -> None:
-        """Removes the lookups the held record produced at admission, handing a name or index value to
-        another held record that produced it too. Reads stored lookup keys only; runs no extractor."""
+        """Removes the lookups the held record produced at admission, handing a name to another held
+        record that produced it too (an index value has one holder). Reads stored lookup keys only; runs no extractor."""
         held = self._state.lookup_keys.get(type, {})
         keys = held.get(key)
         if keys is None:
@@ -596,9 +873,6 @@ class CultCache:
             if self._state.indexes.get(lookup_key) != key:
                 continue
             del self._state.indexes[lookup_key]
-            for candidate_key, candidate in held.items():
-                if candidate_key != key and candidate.indexes.get(index) == index_value:
-                    self._state.indexes[lookup_key] = candidate_key
 
     def _assert_registered(self, document: DocumentDefinition[Any]) -> None:
         if self._state.documents.get(document.type) is not document:

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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import threading
 from dataclasses import MISSING, dataclass, field
 from collections.abc import Mapping, Sequence, Set
 from itertools import chain
@@ -30,6 +31,49 @@ MAX_SLOT_KEY = 65535
 _STACK_FAULTS: tuple[type[BaseException], ...] = (_MsgpackStackError,)
 
 
+@dataclass(frozen=True)
+class UnreadSlots:
+    """What a payload decode found past the slots this runtime declares, at any depth: the first type read with extra slots, how
+    many slots it carried against how many it declares, and how many objects in the payload did. It holds no slot value, so a
+    refusal can name it. `depth0_only` is True when every mark sat in the document's own record (the half of consent the payload
+    decides). A record carrying it is read-only unless the schema comparison explains every mark (see `CultCache.is_writable`)."""
+
+    type_name: str
+    slot_count: int
+    declared_count: int
+    occurrences: int
+    depth0_only: bool
+
+
+class _SlotScope:
+    """Opened by `DocumentDefinition.decode_payload_marked`; the record codec and the union codec note into it. It is thread-local,
+    so no codec signature carries it, and a codec decoded outside a payload decode notes nothing."""
+
+    def __init__(self) -> None:
+        self.depth = 0  # records entered: 0 while the document's own record is read
+        self.first: tuple[str, int, int] | None = None
+        self.occurrences = 0
+        self.depth0_only = True
+
+    def note(self, type_name: str, slot_count: int, declared_count: int, depth0: bool) -> None:
+        if self.first is None:
+            self.first = (type_name, slot_count, declared_count)
+        self.occurrences += 1
+        self.depth0_only = self.depth0_only and depth0
+
+    def result(self) -> UnreadSlots | None:
+        if self.first is None:
+            return None
+        return UnreadSlots(*self.first, self.occurrences, self.depth0_only)
+
+
+_scope = threading.local()
+
+
+def _current_scope() -> _SlotScope | None:
+    return getattr(_scope, "open", None)
+
+
 _CONTAINERS = (Mapping, Sequence, Set)
 _SCALAR_SEQUENCES = (str, bytes, bytearray, memoryview)
 
@@ -114,6 +158,26 @@ def _messagepack_payload_decoder(payload: bytes) -> Any:
     return msgpack.unpackb(payload, raw=False)
 
 
+def read_payload_tree(type_name: str, payload: bytes, decoder: Callable[[bytes], Any] | None = None) -> Any:
+    """The one read of a payload's tree: exactly one MessagePack value, within the nesting limit. Depth is judged first,
+    on the value read so far, so a tail never pre-empts it (C# throws at container 257 before it reaches the tail); then a
+    tail is refused by count and never echoed. Raised outside the handler so no `__context__` keeps the tail."""
+    after = -1
+    unpacked: Any = None
+    try:
+        tree = (decoder or _messagepack_payload_decoder)(payload)
+    except _STACK_FAULTS:
+        raise CultCachePayloadDepthError(type_name, "read") from None
+    except msgpack.ExtraData as error:
+        after = len(error.extra)
+        unpacked = error.unpacked
+    if after >= 0:
+        _refuse_past_depth_limit(unpacked, type_name, "read")
+        raise ValueError(f"{type_name} payload has {after} bytes after its first MessagePack value (refused on read).")
+    _refuse_past_depth_limit(tree, type_name, "read")
+    return tree
+
+
 @dataclass(frozen=True)
 class DatabaseEntryField:
     name: str
@@ -157,6 +221,11 @@ class DocumentDefinition(Generic[T]):
     global_document: bool = False
     name: str | Extractor[T] | None = None
     indexes: dict[str, str | Extractor[T]] = field(default_factory=dict)
+    """Unique lookups (C# `[CultIndex]`): no two records of the type hold one non-blank value, judged at every commit and
+    load. `get_by_index` answers the one holder."""
+    roles: dict[str, str | Extractor[T]] = field(default_factory=dict)
+    """Selection aliases (C# `[CultRole]`): many records may share a value. Never indexed for lookup, never refuse; the
+    member's catalog `index_alias` is the same either way."""
     payload_encoder: Callable[[Any], bytes] = _json_payload_encoder
     payload_decoder: Callable[[bytes], Any] = _json_payload_decoder
     schema_id: str | None = None
@@ -180,15 +249,29 @@ class DocumentDefinition(Generic[T]):
         return self.payload_encoder(tree)
 
     def decode_payload(self, payload: bytes) -> T:
+        return self.decode_payload_marked(payload)[0]
+
+    def decode_payload_marked(self, payload: bytes) -> tuple[T, UnreadSlots | None]:
+        """The value and what the decode found past the declared slots, at any depth. The payload depth check runs first: a
+        payload past the limit is refused, never marked."""
+        tree = read_payload_tree(self.type, payload, self.payload_decoder)
+        outer, opened = _current_scope(), _SlotScope()
+        _scope.open = opened
         try:
-            tree = self.payload_decoder(payload)
-        except _STACK_FAULTS:
-            raise CultCachePayloadDepthError(self.type, "read") from None
-        _refuse_past_depth_limit(tree, self.type, "read")
-        value = self.decode(tree)
+            value = self.decode(tree)
+        finally:
+            _scope.open = outer
         if self.validate:
             self.validate(value)
-        return value
+        return value, opened.result()
+
+    def __post_init__(self) -> None:
+        # Judged here so every constructor passes it: the factories, the dataclass constructor and dataclasses.replace.
+        for alias in self.roles:
+            if alias in self.indexes:
+                raise ValueError(
+                    f"Document type {self.type} declares '{alias}' as both an index and a role; an index already names its role."
+                )
 
     def catalog_entry(self) -> CultCacheSchemaCatalogEntry:
         if self._catalog_entry is not None:
@@ -241,6 +324,7 @@ def define_document_type(
     global_document: bool = False,
     name: str | Extractor[T] | None = None,
     indexes: dict[str, str | Extractor[T]] | None = None,
+    roles: dict[str, str | Extractor[T]] | None = None,
     payload_encoder: Callable[[Any], bytes] = _json_payload_encoder,
     payload_decoder: Callable[[bytes], Any] = _json_payload_decoder,
     schema_id: str | None = None,
@@ -259,6 +343,7 @@ def define_document_type(
         global_document=global_document,
         name=name,
         indexes=indexes or {},
+        roles=roles or {},
         payload_encoder=payload_encoder,
         payload_decoder=payload_decoder,
         schema_id=schema_id,
@@ -280,6 +365,7 @@ def define_database_entry_type(
     global_document: bool = False,
     name: str | Extractor[T] | None = None,
     indexes: dict[str, str | Extractor[T]] | None = None,
+    roles: dict[str, str | Extractor[T]] | None = None,
     schema_id: str | None = None,
     schema_name: str | None = None,
     schema_version: str | None = None,
@@ -296,7 +382,7 @@ def define_database_entry_type(
 
     normalized = _normalize_fields(type, fields)
     member_name_lookup = name if isinstance(name, str) else None
-    index_lookup = indexes or {}
+    index_lookup = {**(roles or {}), **(indexes or {})}
 
     def members() -> tuple[CultCacheSchemaCatalogMember, ...]:
         return tuple(
@@ -323,6 +409,7 @@ def define_database_entry_type(
         global_document=global_document,
         name=name,
         indexes=indexes,
+        roles=roles,
         payload_encoder=_pack_tree,
         payload_decoder=_messagepack_payload_decoder,
         schema_id=schema_id,
@@ -401,6 +488,9 @@ def define_union(
             raise ValueError(f"Union {name!r} value is malformed: expected [armKey, [armSlots]]")
         arm_name, codec = by_key[key]
         if codec is None:
+            scope = _current_scope()
+            if scope is not None and raw[1]:
+                scope.note(arm_name, len(raw[1]), 0, False)
             return UnionArm(arm_name, None)
         try:
             return UnionArm(arm_name, codec.decode(raw[1]))
@@ -462,17 +552,26 @@ def _record_codec(
     def decode(raw: Any) -> Any:
         if not isinstance(raw, list):
             raise ValueError(f"DatabaseEntry document type {type!r} expected a MessagePack array")
+        scope = _current_scope()
+        if scope is not None and len(raw) > max_key + 1:
+            scope.note(type, len(raw), max_key + 1, scope.depth == 0)
         values: dict[str, Any] = {}
-        for field in normalized:
-            if field.key < len(raw):
-                try:
-                    values[field.name] = field.codec.decode(raw[field.key])
-                except ValueError as error:
-                    raise ValueError(f"{type} slot {field.key} ({field.name}): {error}") from None
-            elif field.default is MISSING:
-                values[field.name] = None
-            else:
-                values[field.name] = field.default() if callable(field.default) else field.default
+        if scope is not None:
+            scope.depth += 1
+        try:
+            for field in normalized:
+                if field.key < len(raw):
+                    try:
+                        values[field.name] = field.codec.decode(raw[field.key])
+                    except ValueError as error:
+                        raise ValueError(f"{type} slot {field.key} ({field.name}): {error}") from None
+                elif field.default is MISSING:
+                    values[field.name] = None
+                else:
+                    values[field.name] = field.default() if callable(field.default) else field.default
+        finally:
+            if scope is not None:
+                scope.depth -= 1
         if cls is None:
             return values
         return cls(**values)

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

@@ -13,6 +13,7 @@ from typing import Any, Callable, Iterator, TypeVar
 
 import msgpack
 
+from .documents import UnreadSlots
 from .backing_store import (
     CultCacheEnvelope,
     CultCacheSchemaCatalogEntry,
@@ -46,9 +47,19 @@ 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."""
+    document registers a schema id another registered document already carries. `unread_slots` is None except for the refusal to
+    write or remove a record held read-only because its payload carries slots past the declared ones; its message names the type
+    and both slot counts and never holds a slot value."""
 
-    def __init__(self, schema_id: str, schema_names: list[str], record_key: str, *, message: str | None = None) -> None:
+    def __init__(
+        self,
+        schema_id: str,
+        schema_names: list[str],
+        record_key: str,
+        *,
+        message: str | None = None,
+        unread_slots: UnreadSlots | 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)}"
@@ -56,6 +67,7 @@ class SchemaConflictError(ValueError):
         self.schema_id = schema_id
         self.schema_names = schema_names
         self.record_key = record_key
+        self.unread_slots = unread_slots
 
 
 class JsonLinesBackingStore:
@@ -245,11 +257,44 @@ def _derive_catalog(records: list[tuple[CultCacheEnvelope, bool]]) -> list[CultC
     return [entry for entry, _ in chosen.values()]
 
 
+def retyped(held: CultCacheEnvelope, written: CultCacheEnvelope) -> SchemaConflictError:
+    """The refusal of a write that would put a second type under a key the store already holds (C# CacheBackingStore.Retyped)."""
+    return SchemaConflictError(
+        _schema_id_for(held),
+        [held.type],
+        held.key,
+        message=(
+            f"Record '{held.key}' is a {held.type} (schema id '{_schema_id_for(held)}'); writing a {written.type} there would "
+            "retype the key. Remove the record first, in the same batch or an earlier commit, then add the other type's."
+        ),
+    )
+
+
+def written_owns(held: CultCacheEnvelope, written: CultCacheEnvelope) -> bool:
+    """Whether a write of `written` may replace `held` at its key (C# WrittenOwns): the written type's entry declares the held
+    record's schema id (its own id or one it lists compatible), or it is the type of the same schema name. The same-name half
+    stands in for C#'s "reads the published entry whole": this runtime does not compare shapes, so it never refuses a
+    same-name type for dropping slots."""
+    stored_id = _schema_id_for(held)
+    entry = written.catalog_entry if written.catalog_entry is not None else _default_catalog_entry(written)
+    return stored_id == entry.schema_id or stored_id in entry.compatible_schema_ids or held.type == written.type
+
+
 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]
+    # A key names one record whatever its type, so a supplied record replaces the arrived one by key alone, and only of the
+    # type that owns it: retyping a key is a removal and an add, so a record another type owns under the key refuses the write.
+    held_by_key = {envelope.key: envelope for envelope in arrived}
+    landing: dict[str, CultCacheEnvelope] = {}
+    for envelope in supplied:
+        for held in (landing.get(envelope.key), held_by_key.get(envelope.key)):
+            if held is not None and not written_owns(held, envelope):
+                raise retyped(held, envelope)
+        landing[envelope.key] = envelope
+    supplied = list(landing.values())
+    replaced = set(landing)
+    kept = [envelope for envelope in arrived if envelope.key not in replaced]
     envelopes = [*kept, *supplied]
     catalog = [
         _encode_catalog_entry(entry)
@@ -400,6 +445,7 @@ def _decode_snapshot(decoded: Any) -> tuple[str, list[CultCacheEnvelope]] | None
             catalog_by_schema_id.setdefault(compatible_schema_id, entry)
 
     envelopes: list[CultCacheEnvelope] = []
+    seen: set[str] = set()
     for raw_record in decoded[2]:
         if not isinstance(raw_record, list) or len(raw_record) < 4:
             raise ValueError("CultCache persisted records must be MessagePack arrays")
@@ -412,6 +458,9 @@ def _decode_snapshot(decoded: Any) -> tuple[str, list[CultCacheEnvelope]] | None
         key, schema_id, stored_at, payload = raw_record
         if not isinstance(key, str) or not key:
             raise ValueError("CultCache persisted records must declare a key")
+        if key in seen:
+            raise ValueError(f"CultCache record {key!r} appears more than once")
+        seen.add(key)
         if not isinstance(schema_id, str) or not schema_id:
             raise ValueError("CultCache persisted records must declare a schema id")
         if not isinstance(stored_at, str) or not stored_at:
@@ -437,9 +486,13 @@ 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] = []
+    seen: set[Any] = set()
     for item in decoded:
         if not isinstance(item, dict):
             raise ValueError("CultCache legacy envelopes must be MessagePack maps")
+        if item.get("key") in seen:
+            raise ValueError(f"CultCache record {item['key']!r} appears more than once")
+        seen.add(item.get("key"))
         try:
             payload = item["payload"]
             envelopes.append(
@@ -484,12 +537,14 @@ def _decode_catalog_entry(value: Any) -> CultCacheSchemaCatalogEntry:
         raise ValueError(f'CultCache schema catalog entry "{schema_id}" has invalid compatible schema ids')
     if not isinstance(members, list):
         raise ValueError(f'CultCache schema catalog entry "{schema_id}" has invalid members')
+    if not isinstance(canonical_schema_json, str):
+        raise ValueError(f'CultCache schema catalog entry "{schema_id}" has an invalid canonical schema')
     return CultCacheSchemaCatalogEntry(
         schema_id=schema_id,
         schema_name=schema_name,
         schema_version=schema_version if isinstance(schema_version, str) and schema_version else f"{schema_name}.v1",
         content_hash=content_hash if isinstance(content_hash, str) and content_hash else schema_id,
-        canonical_schema_json=canonical_schema_json if isinstance(canonical_schema_json, str) else "",
+        canonical_schema_json=canonical_schema_json,
         compatible_schema_ids=tuple(compatible_schema_ids),
         members=tuple(_decode_catalog_member(member) for member in members),
     )

packages/cultcache-py/tests/test_cultcache.py

@@ -103,20 +103,20 @@ class CultCacheTests(unittest.TestCase):
         self.assertEqual(cache.get_key_by_name(document, "Elixir"), "item:potion")
         self.assertEqual(cache.get_by_index(document, "category", "Rare").name, "Elixir")
 
-    def test_incremental_lookup_delete_restores_duplicate_owner(self) -> None:
+    def test_incremental_lookup_delete_restores_duplicate_name_owner(self) -> None:
         document = item_doc()
         cache = CultCache()
         cache.register_document_type(document)
 
         cache.put(document, "item:first", Item(name="Potion", category="Consumable", value=50))
-        cache.put(document, "item:second", Item(name="Potion", category="Consumable", value=60))
+        cache.put(document, "item:second", Item(name="Potion", category="Rare", value=60))
         self.assertEqual(cache.get_key_by_name(document, "Potion"), "item:second")
-        self.assertEqual(cache.get_key_by_index(document, "category", "Consumable"), "item:second")
 
         cache.delete(document, "item:second")
 
         self.assertEqual(cache.get_key_by_name(document, "Potion"), "item:first")
         self.assertEqual(cache.get_key_by_index(document, "category", "Consumable"), "item:first")
+        self.assertIsNone(cache.get_key_by_index(document, "category", "Rare"))
 
     def test_database_entry_formatter_uses_slot_indexed_messagepack_array(self) -> None:
         try:
@@ -1121,6 +1121,25 @@ class CultCacheTests(unittest.TestCase):
             catalog_entry=catalog_entry,
         )
 
+    def test_pulling_a_synthetic_pre_v1_envelope_array_leaves_the_file_bytes_identical(self) -> None:
+        try:
+            import msgpack  # type: ignore
+        except ImportError:
+            self.skipTest("msgpack optional dependency is not installed")
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "legacy.cc"
+            legacy = msgpack.packb(
+                [{"key": "note:hello", "type": "note", "payload": {"title": "Hello"}, "storedAt": "2026-10-20T00:00:00Z"}],
+                use_bin_type=True,
+            )
+            path.write_bytes(legacy)
+
+            envelopes = SingleFileMessagePackBackingStore(path).pull_all()
+
+            self.assertEqual([e.key for e in envelopes], ["note:hello"])
+            self.assertEqual(path.read_bytes(), legacy)
+            self.assertEqual(sorted(p.name for p in Path(tmp).iterdir()), ["legacy.cc"])
+
     def test_legacy_key_global_loads_without_writing_and_first_write_leaves_one_global(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
             settings = define_document_type("settings", global_document=True)
@@ -1548,15 +1567,19 @@ class CultCacheTests(unittest.TestCase):
         # 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("..")),
+            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()
+            # "@directory": the walker makes an empty directory at the store path; it is refused and left untouched.
+            content = None if vector == "@directory" else (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)
+                    if content is None:
+                        store_path.mkdir()
+                    else:
+                        store_path.write_bytes(content)
                     store = SingleFileMessagePackBackingStore(store_path)
                     run = {
                         "pull_all": store.pull_all,
@@ -1579,12 +1602,129 @@ class CultCacheTests(unittest.TestCase):
                             self.assertIn(envelopes[0].key, keys, f"{vector} {operation}")
                         else:
                             self.assertNotIn(envelopes[0].key, keys, f"{vector} {operation}")
+                    elif content is None:
+                        # A path that cannot be reached as a file stays an OSError (_read_store): not a store that failed to decode.
+                        with self.assertRaises(OSError, msg=f"{vector} {operation}"):
+                            run()
+                        self.assertTrue(store_path.is_dir() and not any(store_path.iterdir()), f"{vector} {operation} touched the directory")
                     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")
 
+    @staticmethod
+    def _rec(type: str, key: str, second: int = 0) -> CultCacheEnvelope:
+        return CultCacheEnvelope(key=key, type=type, payload=b"\x90", stored_at=f"2026-09-30T00:00:0{second}Z")
+
+    def test_a_supplied_record_replaces_an_arrived_one_of_the_same_type_by_key(self) -> None:
+        import msgpack  # type: ignore
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            store = SingleFileMessagePackBackingStore(path)
+            store.push(self._rec("first", "k"))
+            store.push(self._rec("first", "k", 1))
+            store.push_all([self._rec("first", "k", 2), self._rec("first", "k", 3)])
+            records = msgpack.unpackb(path.read_bytes(), raw=False)[2]
+            self.assertEqual([record[0] for record in records], ["k"])
+            self.assertEqual([(e.type, e.stored_at) for e in store.pull_all()], [("first", "2026-09-30T00:00:03Z")])
+
+    def test_a_write_that_would_retype_a_key_is_refused_and_leaves_the_file(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            store = SingleFileMessagePackBackingStore(path)
+            store.push(self._rec("first", "k"))
+            content = path.read_bytes()
+            for run in (
+                lambda: store.push(self._rec("second", "k", 1)),
+                lambda: store.push_all([self._rec("other", "j"), self._rec("second", "k", 1)]),
+            ):
+                with self.assertRaises(SchemaConflictError) as refused:
+                    run()
+                self.assertEqual(refused.exception.record_key, "k")
+                self.assertEqual(refused.exception.schema_names, ["first"])
+                self.assertIn("would retype the key", str(refused.exception))
+                self.assertEqual(path.read_bytes(), content)
+            # Retyping is a removal and an add.
+            store.delete("first", "k")
+            store.push(self._rec("second", "k", 1))
+            self.assertEqual([e.type for e in SingleFileMessagePackBackingStore(path).pull_all()], ["second"])
+
+    def test_a_retype_is_judged_by_the_stored_schema_id_the_written_type_declares_not_by_name(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            store = SingleFileMessagePackBackingStore(path)
+            store.push(self._writer_record("k", "old", "id-old", self._writer_entry("id-old", "old", "h1", ("id-old",))))
+            content = path.read_bytes()
+            # A renamed type that lists the stored id compatible owns the record, so its write replaces it.
+            renamed = self._writer_record("k", "new", "id-new", self._writer_entry("id-new", "new", "h2", ("id-new", "id-old")))
+            # A type that lists nothing of the stored id and has another name does not.
+            stranger = self._writer_record("k", "stranger", "id-x", self._writer_entry("id-x", "stranger", "h3", ("id-x",)))
+            for run in (lambda: store.push(stranger), lambda: store.push_all([stranger])):
+                with self.assertRaises(SchemaConflictError):
+                    run()
+                self.assertEqual(path.read_bytes(), content)
+            store.push(renamed)
+            self.assertEqual([(e.type, e.schema_id) for e in SingleFileMessagePackBackingStore(path).pull_all()], [("new", "id-new")])
+
+    def test_a_batch_naming_one_key_under_two_types_is_refused_whole(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            store = SingleFileMessagePackBackingStore(path)
+            with self.assertRaises(SchemaConflictError):
+                store.push_all([self._rec("first", "k"), self._rec("second", "k", 1)])
+            self.assertFalse(path.exists())
+
+    def test_a_cache_put_of_a_second_type_under_a_key_is_refused_and_persists_nothing_new(self) -> None:
+        from cultcache_py import SchemaConflictError
+
+        other = define_document_type("other", encode=lambda item: asdict(item), decode=lambda raw: Item(**raw))
+        document = item_doc()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+
+            def build() -> CultCache:
+                cache = (
+                    CultCache.builder()
+                    .register_document_type(document)
+                    .register_document_type(other)
+                    .add_generic_store(SingleFileMessagePackBackingStore(path))
+                    .build()
+                )
+                cache.pull_all_backing_stores()
+                return cache
+
+            cache = build()
+            cache.put(document, "shared", Item(name="A", category="c", value=1))
+            content = path.read_bytes()
+            with self.assertRaises(SchemaConflictError):
+                cache.put(other, "shared", Item(name="B", category="c", value=2))
+            self.assertEqual(path.read_bytes(), content)
+            self.assertIsNone(cache.get(other, "shared"))
+            reloaded = build()
+            self.assertEqual(reloaded.get_required(document, "shared").value, 1)
+            self.assertIsNone(reloaded.get(other, "shared"))
+            cache.delete(document, "shared")
+            cache.put(other, "shared", Item(name="B", category="c", value=2))
+            self.assertEqual(build().get_required(other, "shared").value, 2)
+
+    def test_a_catalog_entry_with_a_non_string_canonical_schema_is_unreadable(self) -> None:
+        # Direct probe of the c0 vector; its manifest row is added by the TS cut.
+        vector = self._C2A_VECTORS.parent / "document-variants-c0" / "current-catalog-bad-canonical.msgpack"
+        content = vector.read_bytes()
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.msgpack"
+            path.write_bytes(content)
+            with self.assertRaises(StoreUnreadableError):
+                SingleFileMessagePackBackingStore(path).pull_all()
+            self.assertEqual(path.read_bytes(), content)
 
 
 if __name__ == "__main__":

packages/cultcache-py/tests/test_first_call.py

@@ -24,7 +24,6 @@ item_doc = define_document_type(
     encode=lambda item: asdict(item),
     decode=lambda raw: Item(**raw),
     name="name",
-    indexes={"category": "category"},
 )
 
 

packages/cultcache-py/tests/test_key_identity_vector.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import re
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+import msgpack
+
+from cultcache_py.cache import CultCacheError
+from cultcache_py import (
+    CultCache,
+
+    JsonLinesBackingStore,
+    SchemaConflictError,
+    SingleFileMessagePackBackingStore,
+    database_entry_field,
+    define_database_entry_type,
+    leaves as t,
+)
+
+# variants:ruling:cache-refuses-retype, write-ownership-by-written-type, unheld-removal-refused-at-commit. The vector in
+# tests/vectors/key-identity is written only by the C# reference; this walks every row against the Python cache.
+VECTORS = Path(__file__).resolve().parents[3] / "tests" / "vectors" / "key-identity"
+
+IDS = {
+    "alpha": "sha256:b20703a98f49c253898404ab50ba2c630720f0b8a5e1a41614d5650be22799fe",
+    "beta": "sha256:dee4b727cf2ee04e61ab635ff0c5f3dca7345a411dc5f1018e583ab16009cf94",
+    "gamma": "sha256:fbc26e351e00c9e7185e8de171c7486aba707c229c949f0aae6b889288af5f6d",
+}
+DOCUMENTS = {
+    label: define_database_entry_type(
+        f"tests.ki_{label}",
+        [database_entry_field("text", 0, codec=t.string)],
+        schema_id=schema_id,
+        schema_name=f"tests.ki_{label}",
+    )
+    for label, schema_id in IDS.items()
+}
+LABEL_OF = {document.type: label for label, document in DOCUMENTS.items()}
+
+def file_records(path: Path) -> list[list[str]]:
+    return sorted([envelope.key, envelope.type] for envelope in SingleFileMessagePackBackingStore(path).pull_all())
+
+def stored(path: Path, key: str):
+    for envelope in SingleFileMessagePackBackingStore(path).pull_all():
+        if envelope.key == key:
+            return envelope.schema_id, envelope.stored_at, envelope.payload
+    return None
+
+class KeyIdentityVectorTests(unittest.TestCase):
+    def test_rows(self) -> None:
+        rows = msgpack.unpackb((VECTORS / "rows.msgpack").read_bytes(), raw=False)
+        walked = 0
+        for label, registered, ops, expect in rows:
+            with self.subTest(row=label), tempfile.TemporaryDirectory() as tmp:
+                self.walk(Path(tmp), registered, ops, expect)
+                walked += 1
+        self.assertEqual(walked, 12)
+
+    def walk(self, tmp: Path, registered: list[str], ops: list, expect: list) -> None:
+        refusal, held, file, foreign, kept = expect
+        state: dict = {"cache": None, "path": None, "before": None, "attached": []}
+
+        def builder() -> CultCache.builder:
+            made = CultCache.builder()
+            for name in registered:
+                made.register_document_type(DOCUMENTS[name])
+            return made
+
+        def open_cache(target) -> None:
+            if target == "memory":
+                state["cache"], state["path"] = builder().build(), None
+                return
+            path = tmp / "store.cc"
+            if target is not None and target != path:
+                shutil.copyfile(VECTORS / target, path)
+                state["before"] = path.read_bytes()
+            state["path"] = path
+            made = builder().add_generic_store(SingleFileMessagePackBackingStore(path))
+            state["cache"] = made.build()
+            state["cache"].pull_all_backing_stores()
+
+        def perform(op: list) -> None:
+            cache = state["cache"]
+            if op[0] == "open":
+                open_cache(op[1])
+            elif op[0] == "attach":
+                path = tmp / f"attached-{len(state['attached'])}.cc"
+                shutil.copyfile(VECTORS / op[1], path)
+                state["attached"].append((path, path.read_bytes()))
+                cache.add_backing_store(
+                    SingleFileMessagePackBackingStore(path), [DOCUMENTS[name].type for name in op[2]]
+                )
+                cache.pull_all_backing_stores()
+            elif op[0] == "reopen":
+                open_cache(state["path"])  # the same file, no fresh copy
+            elif op[0] == "put":
+                cache.put(DOCUMENTS[op[1]], op[2], {"text": op[3]})
+            elif op[0] == "delete":
+                cache.delete(DOCUMENTS[op[1]], op[2])
+            else:
+                self.fail(f"unknown op {op[0]}")
+
+        for op in ops[:-1]:
+            perform(op)
+        if refusal is None:
+            perform(ops[-1])
+        else:
+            key = refusal[0]
+            with self.assertRaises((SchemaConflictError, ValueError, RuntimeError)) as caught:
+                perform(ops[-1])
+            if ops[-1][0] == "attach":
+                # The key is read out of the refusal's own text (it opens "Record 'key' is held by") and occurs only as a
+                # delimited token, never inside a schema name or other word.
+                message = str(caught.exception)
+                named = re.match(r"Record '([^']*)' is held by", message)
+                self.assertIsNotNone(named, message)
+                self.assertEqual(named.group(1), key)
+                self.assertEqual(len(re.findall(rf"(?<![A-Za-z0-9_]){re.escape(key)}(?![A-Za-z0-9_])", message)), 1)
+                self.assertEqual(message.count(key), 1)
+                for path, before in state["attached"]:
+                    self.assertEqual(path.read_bytes(), before)
+            else:
+                self.assertIsInstance(caught.exception, SchemaConflictError)
+                self.assertEqual(caught.exception.record_key, key)
+                self.assertIn(key, str(caught.exception))
+        cache = state["cache"]
+        got_held = sorted(
+            [LABEL_OF[type], key, value["text"]]
+            for type, values in cache.snapshot().items()
+            for key, value in values.items()
+        )
+        self.assertEqual(got_held, held)
+        path = state["path"]
+        if file is None:
+            self.assertIsNone(path)
+        else:
+            self.assertEqual(file_records(path), file)
+        self.assertEqual([record.key for record in cache.foreign_records()], foreign)
+        if kept:
+            vector = tmp / "vector-before.cc"
+            vector.write_bytes(state["before"])
+            for key in kept:
+                self.assertIsNotNone(stored(vector, key))
+                self.assertEqual(stored(path, key), stored(vector, key))
+
+def alpha_beta(*names: str, store=None) -> CultCache:
+    made = CultCache.builder()
+    for name in names:
+        made.register_document_type(DOCUMENTS[name])
+    if store is not None:
+        made.add_generic_store(store)
+    return made.build()
+
+class KeyIdentityTests(unittest.TestCase):
+    def test_two_global_types_are_refused_in_one_cache_and_a_store_holding_both_does_not_load(self) -> None:
+        # C# refuses a second persisted global on pull (cultcache-store-composition.md, "Globals never invented"); the Python
+        # JSONL store and a cache with no store used to let two global types share __global__, so such a file can exist.
+        ga = define_database_entry_type(
+            "tests.ki_ga", [database_entry_field("text", 0, codec=t.string)], schema_id="sha256:" + "1" * 64, global_document=True
+        )
+        gb = define_database_entry_type(
+            "tests.ki_gb", [database_entry_field("text", 0, codec=t.string)], schema_id="sha256:" + "2" * 64, global_document=True
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.jsonl"
+            for document in (ga, gb):  # one cache per type that never pulled: how a file got two globals
+                writer = CultCache.builder().register_document_type(document).add_generic_store(JsonLinesBackingStore(path)).build()
+                writer.put_global(document, {"text": document.type})
+            both = CultCache.builder().register_document_type(ga).register_document_type(gb).add_generic_store(JsonLinesBackingStore(path)).build()
+            with self.assertRaises(CultCacheError) as caught:
+                both.pull_all_backing_stores()
+            self.assertIn("'__global__' is held by both", str(caught.exception))
+            self.assertEqual(both.snapshot(), {})
+            memory = CultCache.builder().register_document_type(ga).register_document_type(gb).build()
+            memory.put_global(ga, {"text": "a"})
+            with self.assertRaises(SchemaConflictError):
+                memory.put_global(gb, {"text": "b"})
+            self.assertEqual(memory.get_required_global(ga), {"text": "a"})
+
+    def test_every_write_path_refuses_a_second_type_and_never_echoes_the_payload(self) -> None:
+        alpha, beta = DOCUMENTS["alpha"], DOCUMENTS["beta"]
+        for name in ("put", "put_envelope", "put_envelopes"):
+            with self.subTest(path=name):
+                cache = alpha_beta("alpha", "beta")
+                cache.put(alpha, "k", {"text": "held"})
+                envelope = cache.get_envelope(alpha, "k")
+                other = type(envelope).create(
+                    key="k", type=beta.type, payload=beta.encode_payload({"text": "CANARY"}), schema_id=IDS["beta"]
+                )
+                writes = {
+                    "put": lambda: cache.put(beta, "k", {"text": "CANARY"}),
+                    "put_envelope": lambda: cache.put_envelope(beta, other),
+                    "put_envelopes": lambda: cache.put_envelopes(beta, [other]),
+                }
+                with self.assertRaises(SchemaConflictError) as caught:
+                    writes[name]()
+                self.assertEqual(caught.exception.record_key, "k")
+                self.assertNotIn("CANARY", str(caught.exception))
+                self.assertEqual(cache.get(alpha, "k"), {"text": "held"})
+                self.assertIsNone(cache.get(beta, "k"))
+
+    def test_two_routed_stores_holding_one_key_refuse_the_pull_and_keep_the_earlier_state(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            one, two = Path(tmp) / "one.cc", Path(tmp) / "two.cc"
+            shutil.copyfile(VECTORS / "catalog-store.cc", one)
+            shutil.copyfile(VECTORS / "run-store.cc", two)
+            cache = alpha_beta("alpha", "beta")
+            cache.add_backing_store(SingleFileMessagePackBackingStore(one), [DOCUMENTS["alpha"].type])
+            cache.pull_all_backing_stores()
+            cache.add_backing_store(SingleFileMessagePackBackingStore(two), [DOCUMENTS["beta"].type])
+            with self.assertRaises(Exception) as caught:
+                cache.pull_all_backing_stores()
+            self.assertIn("'qx'", str(caught.exception))
+            self.assertEqual(cache.get(DOCUMENTS["alpha"], "qx"), {"text": "a"})
+            self.assertIsNone(cache.get(DOCUMENTS["beta"], "qx"))
+
+    def test_a_foreign_record_is_listed_and_its_bytes_survive_writes_and_removals_elsewhere(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.cc"
+            shutil.copyfile(VECTORS / "foreign-store.cc", path)
+            before = stored(path, "k")
+            cache = alpha_beta("alpha", store=SingleFileMessagePackBackingStore(path))
+            cache.pull_all_backing_stores()
+            [record] = cache.foreign_records()
+            self.assertEqual((record.key, record.schema_id, record.schema_name), ("k", IDS["gamma"], "tests.ki_gamma"))
+            self.assertEqual(record.stored_at, before[1])
+            cache.put(DOCUMENTS["alpha"], "m", {"text": "m"})
+            cache.delete(DOCUMENTS["alpha"], "j")
+            self.assertEqual(stored(path, "k"), before)
+            self.assertEqual(file_records(path), [["k", "tests.ki_gamma"], ["m", "tests.ki_alpha"]])
+            claimed = alpha_beta("alpha", "gamma", store=SingleFileMessagePackBackingStore(path))
+            claimed.pull_all_backing_stores()
+            self.assertEqual(claimed.foreign_records(), [])
+            self.assertEqual(claimed.get(DOCUMENTS["gamma"], "k"), {"text": "g"})
+
+    def test_the_foreign_list_is_sorted_by_utf16_code_unit_and_replaced_by_the_next_pull(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.cc"
+            store = SingleFileMessagePackBackingStore(path)
+            gamma = DOCUMENTS["gamma"]
+            writer = alpha_beta("gamma", store=store)
+            for key in ("\U00010400", "Ａ", "b", "B"):
+                writer.put(gamma, key, {"text": "x"})
+            cache = alpha_beta("alpha", store=SingleFileMessagePackBackingStore(path))
+            cache.pull_all_backing_stores()
+            self.assertEqual([record.key for record in cache.foreign_records()], ["B", "b", "\U00010400", "Ａ"])
+            for key in ("B", "b", "\U00010400", "Ａ"):
+                writer.delete(gamma, key)
+            cache.pull_all_backing_stores()
+            self.assertEqual(cache.foreign_records(), [])
+
+class OwnershipAndStoreKindTests(unittest.TestCase):
+    """The cache judge answers on its own where the store has no commit guard (JSONL) or the records live in two stores."""
+
+    def test_a_jsonl_store_gets_no_help_from_a_disk_judge(self) -> None:
+        from cultcache_py import JsonLinesBackingStore
+
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "store.jsonl"
+            gamma = DOCUMENTS["gamma"]
+            alpha_beta("gamma", store=JsonLinesBackingStore(path)).put(gamma, "k", {"text": "g"})
+            before = path.read_bytes()
+            cache = alpha_beta("alpha", store=JsonLinesBackingStore(path))
+            cache.pull_all_backing_stores()
+            self.assertEqual([record.key for record in cache.foreign_records()], ["k"])
+            with self.assertRaises(SchemaConflictError):
+                cache.put(DOCUMENTS["alpha"], "k", {"text": "x"})
+            with self.assertRaises(SchemaConflictError):
+                cache.delete(DOCUMENTS["alpha"], "k")
+            self.assertEqual(path.read_bytes(), before)
+            cache.put(DOCUMENTS["alpha"], "j", {"text": "a"})  # the foreign line is carried through a write elsewhere
+            self.assertIn(b"tests.ki_gamma", path.read_bytes())
+
+    def test_a_foreign_key_in_two_stores_refuses_the_pull(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            one, two = Path(tmp) / "one.cc", Path(tmp) / "two.cc"
+            for path in (one, two):
+                alpha_beta("gamma", store=SingleFileMessagePackBackingStore(path)).put(DOCUMENTS["gamma"], "k", {"text": "g"})
+            cache = alpha_beta("alpha")
+            cache.add_backing_store(SingleFileMessagePackBackingStore(one), [DOCUMENTS["alpha"].type])
+            cache.add_backing_store(SingleFileMessagePackBackingStore(two), [DOCUMENTS["beta"].type])
+            with self.assertRaises(Exception) as caught:
+                cache.pull_all_backing_stores()
+            self.assertIn("'k'", str(caught.exception))
+
+    def test_a_type_that_owns_the_held_schema_id_replaces_the_record_and_the_key_keeps_one_type(self) -> None:
+        successor = define_database_entry_type(
+            "tests.ki_alpha2",
+            [database_entry_field("text", 0, codec=t.string)],
+            schema_id="sha256:" + "a" * 64,
+            schema_name="tests.ki_alpha2",
+            compatible_schema_ids=[IDS["alpha"]],
+        )
+        for routed in (False, True):
+            with self.subTest(routed=routed), tempfile.TemporaryDirectory() as tmp:
+                one, two = Path(tmp) / "one.cc", Path(tmp) / "two.cc"
+                made = CultCache.builder().register_document_type(DOCUMENTS["alpha"]).register_document_type(successor)
+                if routed:
+                    made.add_backing_store(SingleFileMessagePackBackingStore(one), [DOCUMENTS["alpha"].type])
+                    made.add_backing_store(SingleFileMessagePackBackingStore(two), [successor.type])
+                else:
+                    made.add_generic_store(SingleFileMessagePackBackingStore(one))
+                cache = made.build()
+                cache.put(DOCUMENTS["alpha"], "k", {"text": "old"})
+                if routed:
+                    with self.assertRaises(SchemaConflictError):  # one key would live in two stores
+                        cache.put(successor, "k", {"text": "new"})
+                    self.assertEqual(cache.get(DOCUMENTS["alpha"], "k"), {"text": "old"})
+                else:
+                    cache.put(successor, "k", {"text": "new"})
+                    self.assertIsNone(cache.get(DOCUMENTS["alpha"], "k"))
+                    self.assertEqual(cache.get(successor, "k"), {"text": "new"})
+                    self.assertEqual(file_records(one), [["k", "tests.ki_alpha2"]])

packages/cultcache-py/tests/test_slot_readonly.py

@@ -0,0 +1,492 @@
+from __future__ import annotations
+
+import dataclasses
+import shutil
+import threading
+import tempfile
+import unittest
+from pathlib import Path
+
+import msgpack
+from cultcache_py.cache import CultCacheError
+
+from cultcache_py import (
+    CultCache,
+    CultCachePayloadDepthError,
+    SlotCodec,
+    SchemaConflictError,
+    SingleFileMessagePackBackingStore,
+    UnionArm,
+    UnreadSlots,
+    database_entry_field,
+    define_database_entry_type,
+    define_record_codec,
+    leaves as t,
+)
+import test_union_parity as _parity
+from test_union_parity import (
+    VECTORS,
+    _surface_value,
+    _vector,
+    surface_document,
+    unit_outcome,
+)
+
+SLOT = "extra-slot"  # the canary: the value of every extra slot in the vectors; no refusal may carry it
+
+# The vectors name the C# types; this runtime names a type by its codec's name, a document by its document type.
+_NAMES = {"UnionSurface": surface_document.type, "SurfaceDeclaring": surface_document.type, "Denied2": "Denied"}
+
+slot_unit_document = define_database_entry_type(
+    "tests.slot_unit",
+    [database_entry_field("name", 0, codec=t.string), database_entry_field("outcome", 1, codec=unit_outcome)],
+    name="name",
+)
+# The reader of extra-slot-consent.cc: the surface document's slots under a new schema id that lists the old one compatible.
+declaring_document = define_database_entry_type(
+    "tests.union_surface",
+    [
+        database_entry_field("id", 0, codec=t.string),
+        database_entry_field("version", 1, codec=t.int32),
+        database_entry_field("root", 2, codec=_parity._node),
+        database_entry_field("outcomes", 3, codec=t.list(_parity.outcome)),
+        database_entry_field("part", 4, codec=t.nullable(_parity.item)),
+        database_entry_field("crafted", 5, codec=t.nullable(_parity.crafted)),
+        database_entry_field("missing", 6, codec=_parity._node),
+    ],
+    name="id",
+    schema_id="tests.union_surface.v2",
+    schema_name="tests.union_surface",
+    compatible_schema_ids=("tests.union_surface.wide",),
+)
+
+# file -> (type, slots carried, slots declared, every mark at depth 0): the README table.
+_PAYLOADS = {
+    "extra-slot-record.msgpack": ("UnionSurface", 8, 7, True),
+    "extra-slot-nested-record.msgpack": ("Composition", 3, 2, False),
+    "extra-slot-arm.msgpack": ("Box", 3, 2, False),
+    "extra-slot-list-element.msgpack": ("Text", 3, 2, False),
+    "depth-skipped-at-limit.msgpack": ("UnionSurface", 8, 7, True),
+}
+
+
+def _copy_store_without_variants(source: Path, target: Path) -> None:
+    """This runtime holds no variant records (a five-slot record makes a store unreadable here), so the store vector is
+    walked with its variant row removed; every other byte is the C# writer's."""
+    [snapshot] = list(msgpack.Unpacker(open(source, "rb"), raw=False))
+    snapshot[2] = [record for record in snapshot[2] if len(record) <= 4]
+    target.write_bytes(msgpack.packb(snapshot, use_bin_type=True))
+
+
+def _open(path: Path, *documents) -> CultCache:
+    builder = CultCache.builder()
+    for document in documents:
+        builder.register_document_type(document)
+    cache = builder.add_generic_store(SingleFileMessagePackBackingStore(path)).build()
+    cache.pull_all_backing_stores()
+    return cache
+
+
+def _rows():
+    return msgpack.unpackb(_vector("slot-outcomes.msgpack"), raw=False)
+
+
+class PayloadMarkTests(unittest.TestCase):
+    def test_every_read_only_payload_decodes_and_names_its_mark(self) -> None:
+        for file, (type_name, carried, declared, depth0) in _PAYLOADS.items():
+            with self.subTest(file=file):
+                value, mark = surface_document.decode_payload_marked(_vector(file))
+                self.assertEqual(value, _surface_value())
+                self.assertEqual(mark, UnreadSlots(_NAMES.get(type_name, type_name), carried, declared, 1, depth0))
+                self.assertEqual(surface_document.decode_payload(_vector(file)), _surface_value())
+
+    def test_the_outcomes_manifest_still_counts_nine_rows_and_four_read_only(self) -> None:
+        rows = msgpack.unpackb(_vector("outcomes.msgpack"), raw=False)
+        self.assertEqual(len(rows), 9)
+        self.assertEqual([row[0] for row in rows if row[1] == "read-only"], [f for f in _PAYLOADS if f != "depth-skipped-at-limit.msgpack"])
+
+    def test_a_clean_payload_and_a_short_one_carry_no_mark(self) -> None:
+        self.assertEqual(surface_document.decode_payload_marked(_vector("union-surface.msgpack")), (_surface_value(), None))
+        slots = msgpack.unpackb(_vector("union-surface.msgpack"), raw=False)
+        slots[2] = [1, ["only-id"]]  # a Text arm with a missing trailing slot: defaults, no mark
+        _, mark = surface_document.decode_payload_marked(msgpack.packb(slots, use_bin_type=True))
+        self.assertIsNone(mark)
+
+    def test_a_retired_slot_below_the_highest_key_does_not_mark(self) -> None:
+        slots = msgpack.unpackb(_vector("union-surface.msgpack"), raw=False)
+        # Image's declared slots are 0, 1, 3 (2 retired): four carried, four declared.
+        image = slots[2][1][1][2]
+        self.assertEqual(image[0], 5)
+        image[1][2] = "retired-slot-value"
+        _, mark = surface_document.decode_payload_marked(msgpack.packb(slots, use_bin_type=True))
+        self.assertIsNone(mark)
+
+    def test_the_depth_check_runs_before_the_mark(self) -> None:
+        with self.assertRaises(CultCachePayloadDepthError):
+            surface_document.decode_payload_marked(_vector("depth-skipped-past-limit.msgpack"))
+
+    def test_the_unit_arm_with_extra_slots_is_read_past_and_marked(self) -> None:
+        payload = msgpack.packb(["unit-arm", [2, [SLOT]]], use_bin_type=True)
+        value, mark = slot_unit_document.decode_payload_marked(payload)
+        self.assertEqual(value, {"name": "unit-arm", "outcome": UnionArm("Denied")})
+        self.assertEqual(mark, UnreadSlots("Denied", 1, 0, 1, False))
+        self.assertEqual(slot_unit_document.decode_payload_marked(msgpack.packb(["ok", [2, []]]))[1], None)
+
+    def test_a_codec_decoded_outside_a_payload_decode_notes_nothing(self) -> None:
+        self.assertEqual(unit_outcome.decode([2, [SLOT]]), UnionArm("Denied"))
+
+    def test_the_scope_belongs_to_its_thread(self) -> None:
+        def decode_elsewhere(raw):
+            thread = threading.Thread(target=lambda: unit_outcome.decode([2, [SLOT]]))
+            thread.start()
+            thread.join()
+            return raw
+
+        outer = define_database_entry_type("tests.threaded", [database_entry_field("a", 0, codec=SlotCodec(lambda v: v, decode_elsewhere))])
+        self.assertIsNone(outer.decode_payload_marked(msgpack.packb(["x"]))[1])
+
+    def test_a_nested_payload_decode_restores_the_outer_scope(self) -> None:
+        def decode_clean_inside(raw):
+            surface_document.decode_payload_marked(_vector("union-surface.msgpack"))
+            return raw
+
+        inner = define_record_codec("Inner", [database_entry_field("x", 0, codec=t.string)])
+        outer = define_database_entry_type(
+            "tests.nested",
+            [
+                database_entry_field("a", 0, codec=SlotCodec(lambda v: v, decode_clean_inside)),
+                database_entry_field("b", 1, codec=inner),
+            ],
+        )
+        _, mark = outer.decode_payload_marked(msgpack.packb(["x", ["v", SLOT]]))
+        self.assertEqual(mark, UnreadSlots("Inner", 2, 1, 1, False))
+
+
+class StoreRowTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+
+    def _store(self, name: str) -> tuple[Path, CultCache]:
+        path = self.tmp / name
+        _copy_store_without_variants(VECTORS / name, path)
+        documents = (declaring_document,) if name == "extra-slot-consent.cc" else (surface_document, slot_unit_document)
+        return path, _open(path, *documents)
+
+    def _document(self, store: str, key: str):
+        if key == "unit-arm":
+            return slot_unit_document
+        return declaring_document if store == "extra-slot-consent.cc" else surface_document
+
+    def test_every_row_is_writable_exactly_where_the_vector_says_and_refuses_with_its_mark(self) -> None:
+        walked = 0
+        for store, key, writable, explained, type_name, carried, declared, occurrences, flatten in _rows():
+            if flatten is not None:
+                continue  # a variant: this runtime holds none (deviation)
+            walked += 1
+            with self.subTest(store=store, key=key):
+                path, cache = self._store(store)
+                document = self._document(store, key)
+                before = path.read_bytes()
+                self.assertEqual(cache.is_writable(document, key), writable)
+                held = cache.get(document, key)
+                self.assertIsNotNone(held)
+                if writable:
+                    continue
+                self.assertEqual(explained, False)
+                for attempt in (
+                    lambda: cache.put(document, key, held),
+                    lambda: cache.delete(document, key),
+                    lambda: cache.put_envelope(document, cache.get_required_envelope(document, key)),
+                    lambda: cache.put_envelopes(document, [cache.get_required_envelope(document, key)]),
+                    lambda: cache.update(document, key, lambda value: value),
+                ):
+                    with self.assertRaises(SchemaConflictError) as caught:
+                        attempt()
+                    refusal = caught.exception
+                    self.assertEqual(
+                        refusal.unread_slots,
+                        UnreadSlots(_NAMES.get(type_name, type_name), carried, declared, occurrences, refusal.unread_slots.depth0_only),
+                    )
+                    self.assertEqual(refusal.record_key, key)
+                    message = str(refusal)
+                    self.assertNotIn(SLOT, message)
+                    self.assertIn(refusal.unread_slots.type_name, message)
+                    self.assertIn(f"{carried} slots", message)
+                    self.assertIn(f"declares {declared}", message)
+                    self.assertEqual(path.read_bytes(), before)
+                self.assertTrue(cache.get(document, key) is held)
+        self.assertEqual(walked, 7)  # eight rows, the variant not walked
+
+    def test_a_key_no_store_holds_and_another_key_are_writable_while_a_marked_one_is_held(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        self.assertFalse(cache.is_writable(surface_document, "marked"))
+        self.assertTrue(cache.is_writable(surface_document, "nothing-here"))
+        cache.put(surface_document, "other", cache.get_required(surface_document, "clean"))
+        self.assertEqual(cache.get(surface_document, "other"), _surface_value())
+
+    def test_consent_lands_an_explained_mark_and_refuses_the_others(self) -> None:
+        path, cache = self._store("extra-slot-consent.cc")
+        self.assertTrue(cache.is_writable(declaring_document, "consented"))
+        cache.put(declaring_document, "consented", cache.get_required(declaring_document, "consented"))
+        [stored] = [e for e in SingleFileMessagePackBackingStore(path).pull_all() if e.key == "consented"]
+        self.assertEqual(stored.schema_id, "tests.union_surface.v2")
+        self.assertEqual(len(msgpack.unpackb(stored.payload, raw=False)), 7)  # the consented slot is gone
+        self.assertTrue(cache.is_writable(declaring_document, "consented"))
+        for key in ("over-consent", "nested"):
+            self.assertFalse(cache.is_writable(declaring_document, key), key)
+            with self.assertRaises(SchemaConflictError):
+                cache.put(declaring_document, key, cache.get_required(declaring_document, key))
+
+    def test_a_reload_marks_again_and_a_write_of_a_clean_envelope_over_a_marked_key_is_refused(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        envelope = cache.get_required_envelope(surface_document, "clean")
+        with self.assertRaises(SchemaConflictError):
+            cache.put_envelope(surface_document, type(envelope)(**{**envelope.__dict__, "key": "marked"}))
+        cache.pull_all_backing_stores()
+        self.assertFalse(cache.is_writable(surface_document, "marked"))
+
+    def test_a_written_envelope_that_carries_extra_slots_is_held_read_only(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        envelope = cache.get_required_envelope(surface_document, "clean")
+        carrying = type(envelope)(**{**envelope.__dict__, "key": "arrived", "payload": _vector("extra-slot-arm.msgpack")})
+        cache.put_envelope(surface_document, carrying)
+        self.assertFalse(cache.is_writable(surface_document, "arrived"))
+        with self.assertRaises(SchemaConflictError):
+            cache.delete(surface_document, "arrived")
+        cache.pull_all_backing_stores()
+        self.assertFalse(cache.is_writable(surface_document, "arrived"))
+
+    def test_a_batch_of_envelopes_that_carry_extra_slots_is_held_read_only(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        envelope = cache.get_required_envelope(surface_document, "clean")
+        batch = [
+            type(envelope)(**{**envelope.__dict__, "key": key, "payload": _vector(file)})
+            for key, file in (("b1", "extra-slot-arm.msgpack"), ("b2", "union-surface.msgpack"))
+        ]
+        cache.put_envelopes(surface_document, batch)
+        self.assertEqual([cache.is_writable(surface_document, key) for key in ("b1", "b2")], [False, True])
+
+    def test_a_mark_under_an_id_the_reader_does_not_list_compatible_is_not_consented(self) -> None:
+        unlisted = define_database_entry_type(
+            "tests.union_surface",
+            [database_entry_field("id", 0, codec=t.string)] + [database_entry_field(n, i, codec=c) for n, i, c in (
+                ("version", 1, t.int32), ("root", 2, _parity._node), ("outcomes", 3, t.list(_parity.outcome)),
+                ("part", 4, t.nullable(_parity.item)), ("crafted", 5, t.nullable(_parity.crafted)), ("missing", 6, _parity._node))],
+            name="id",
+            schema_id="tests.union_surface.v2",
+            schema_name="tests.union_surface",
+        )
+        path = self.tmp / "unlisted.cc"
+        _copy_store_without_variants(VECTORS / "extra-slot-consent.cc", path)
+        cache = _open(path, unlisted)
+        self.assertFalse(cache.is_writable(unlisted, "consented"))
+
+    def test_a_written_envelope_is_judged_on_the_id_it_is_stored_under_so_a_reload_agrees(self) -> None:
+        path, cache = self._store("extra-slot-consent.cc")
+        arrived = next(e for e in SingleFileMessagePackBackingStore(path).pull_all() if e.key == "consented")
+        self.assertEqual(arrived.schema_id, "tests.union_surface.wide")
+        cache.put_envelope(declaring_document, dataclasses.replace(arrived, key="via-envelope"))
+        cache.put_envelopes(declaring_document, [dataclasses.replace(arrived, key="via-batch")])
+        in_memory = [cache.is_writable(declaring_document, k) for k in ("via-envelope", "via-batch")]
+        cache.pull_all_backing_stores()
+        self.assertEqual([cache.is_writable(declaring_document, k) for k in ("via-envelope", "via-batch")], in_memory)
+        self.assertEqual(in_memory, [False, False])
+
+    def test_is_writable_agrees_with_the_write_for_a_key_a_store_carries_foreign(self) -> None:
+        path = self.tmp / "foreign.cc"
+        _copy_store_without_variants(VECTORS / "extra-slot-store.cc", path)
+        cache = _open(path, surface_document)  # tests.slot_unit is not registered: its record is carried foreign
+        self.assertEqual([r.key for r in cache.foreign_records()], ["unit-arm"])
+        self.assertFalse(cache.is_writable(surface_document, "unit-arm"))
+        with self.assertRaises(SchemaConflictError):
+            cache.put(surface_document, "unit-arm", _surface_value())
+        with self.assertRaises(SchemaConflictError):
+            cache.delete(surface_document, "unit-arm")
+
+    def test_every_key_of_a_batch_is_checked_wherever_the_marked_one_stands(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        before = path.read_bytes()
+        envelope = cache.get_required_envelope(surface_document, "clean")
+        fresh = dataclasses.replace(envelope, key="fresh")
+        marked = dataclasses.replace(envelope, key="marked")
+        for batch in ([fresh, marked], [marked, fresh], [fresh, dataclasses.replace(envelope, key="f2"), marked]):
+            with self.assertRaises(SchemaConflictError) as caught:
+                cache.put_envelopes(surface_document, batch)
+            self.assertEqual(caught.exception.record_key, "marked")
+            self.assertEqual(path.read_bytes(), before)
+            self.assertIsNone(cache.get(surface_document, "fresh"))
+
+    def test_only_the_marks_that_hold_a_record_read_only_are_kept_by_key(self) -> None:
+        _, store = self._store("extra-slot-store.cc")
+        self.assertEqual({k: v[0] for k, v in store._state.unread.items()}, {"marked": surface_document.type, "unit-arm": "tests.slot_unit"})
+        _, consent = self._store("extra-slot-consent.cc")
+        self.assertEqual(sorted(consent._state.unread), ["nested", "over-consent"])  # the consented mark is no state
+
+    def test_an_arrival_with_no_catalog_entry_under_a_listed_id_is_not_consented(self) -> None:
+        wide = next(e for e in SingleFileMessagePackBackingStore(VECTORS / "extra-slot-consent.cc").pull_all() if e.key == "consented")
+        bare = dataclasses.replace(wide, catalog_entry=None)
+
+        class Held:
+            def pull_all(self):
+                return [bare]
+
+            def push(self, envelope): ...
+
+            def push_all(self, envelopes): ...
+
+            def delete(self, type, key): ...
+
+        cache = CultCache.builder().register_document_type(declaring_document).add_generic_store(Held()).build()
+        cache.pull_all_backing_stores()
+        self.assertFalse(cache.is_writable(declaring_document, "consented"))
+
+    def test_a_removal_is_refused_where_is_writable_says_no(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        before = path.read_bytes()
+        other = define_database_entry_type("tests.other", [database_entry_field("a", 0, codec=t.string)], name="a")
+        cache2 = _open(self.tmp / "extra-slot-store.cc", surface_document, slot_unit_document, other)
+        self.assertFalse(cache2.is_writable(other, "clean"))
+        with self.assertRaises(SchemaConflictError):
+            cache2.delete(other, "clean")
+        self.assertEqual(path.read_bytes(), before)
+        self.assertIsNotNone(cache2.get(surface_document, "clean"))
+        self.assertTrue(cache2.is_writable(other, "nothing-here"))
+
+    def test_a_global_document_is_not_writable_at_a_key_other_than_the_global_one(self) -> None:
+        solo = define_database_entry_type("tests.solo", [database_entry_field("a", 0, codec=t.string)], global_document=True)
+        cache = CultCache.builder().register_document_type(solo).build()
+        self.assertFalse(cache.is_writable(solo, "elsewhere"))
+        with self.assertRaises(CultCacheError):
+            cache.put(solo, "elsewhere", {"a": "x"})
+        with self.assertRaises(CultCacheError):
+            cache.delete(solo, "elsewhere")
+        self.assertTrue(cache.is_writable(solo, CultCache.GLOBAL_KEY))
+
+    def test_a_reload_replaces_the_marks_wholesale(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        self.assertFalse(cache.is_writable(surface_document, "marked"))
+        # The store is repaired by its owner: the marked record is rewritten clean. The reload must forget the old mark.
+        [snapshot] = list(msgpack.Unpacker(open(path, "rb"), raw=False))
+        clean = next(r for r in snapshot[2] if r[0] == "clean")
+        for record in snapshot[2]:
+            if record[0] in ("marked", "unit-arm"):
+                record[3] = clean[3] if record[0] == "marked" else record[3]
+        snapshot[2] = [r for r in snapshot[2] if r[0] != "unit-arm"]
+        path.write_bytes(msgpack.packb(snapshot, use_bin_type=True))
+        cache.pull_all_backing_stores()
+        self.assertTrue(cache.is_writable(surface_document, "marked"))
+        self.assertEqual(cache._state.unread, {})
+
+    def test_a_listed_id_whose_catalog_reports_no_extra_slot_does_not_consent(self) -> None:
+        wide = next(e for e in SingleFileMessagePackBackingStore(VECTORS / "extra-slot-consent.cc").pull_all() if e.key == "consented")
+        same = dataclasses.replace(wide, catalog_entry=declaring_document.catalog_entry())  # the stored entry has no slot past the reader's
+
+        class Held:
+            def pull_all(self):
+                return [same]
+
+            def push(self, envelope): ...
+
+            def push_all(self, envelopes): ...
+
+            def delete(self, type, key): ...
+
+        cache = CultCache.builder().register_document_type(declaring_document).add_generic_store(Held()).build()
+        cache.pull_all_backing_stores()
+        self.assertFalse(cache.is_writable(declaring_document, "consented"))
+
+    def test_a_record_stored_under_the_readers_own_id_is_never_consented(self) -> None:
+        own = dataclasses.replace(
+            next(e for e in SingleFileMessagePackBackingStore(VECTORS / "extra-slot-consent.cc").pull_all() if e.key == "consented"),
+            schema_id="tests.union_surface.v2",
+        )
+        wider = dataclasses.replace(own.catalog_entry, schema_id="tests.union_surface.v2", compatible_schema_ids=("tests.union_surface.v2",))
+        listing = dataclasses.replace(
+            declaring_document, schema_id="tests.union_surface.v2", compatible_schema_ids=("tests.union_surface.wide", "tests.union_surface.v2")
+        )
+
+        class Held:
+            def pull_all(self):
+                return [dataclasses.replace(own, catalog_entry=wider)]
+
+            def push(self, envelope): ...
+
+            def push_all(self, envelopes): ...
+
+            def delete(self, type, key): ...
+
+        cache = CultCache.builder().register_document_type(listing).add_generic_store(Held()).build()
+        cache.pull_all_backing_stores()
+        self.assertFalse(cache.is_writable(listing, "consented"))
+
+    def test_a_removal_by_the_owner_of_a_key_held_as_another_type_removes_it_as_a_write_would_replace_it(self) -> None:
+        a = define_database_entry_type(
+            "tests.owned_a", [database_entry_field("a", 0, codec=t.string)], name="a", indexes={"by_a": "a"}
+        )
+        b = define_database_entry_type(
+            "tests.owned_b",
+            [database_entry_field("a", 0, codec=t.string)],
+            compatible_schema_ids=(a.catalog_entry().schema_id,),
+        )
+        path = self.tmp / "owned.cc"
+        writer = _open(path, a)
+        writer.put(a, "k", {"a": "x"})
+        writer.put(a, "other", {"a": "y"})
+        cache = _open(path, a, b)
+        self.assertTrue(cache.is_writable(b, "k"))
+        cache.delete(b, "k")
+        self.assertIsNone(cache.get(a, "k"))
+        self.assertIsNone(cache.get_by_index(a, "by_a", "x"))
+        self.assertEqual([e.key for e in SingleFileMessagePackBackingStore(path).pull_all()], ["other"])
+        self.assertTrue(cache.is_writable(b, "k"))
+
+    def test_an_owners_removal_is_one_store_call_so_the_cache_and_the_store_agree_when_it_fails(self) -> None:
+        a = define_database_entry_type("tests.one_a", [database_entry_field("a", 0, codec=t.string)], name="a")
+        b = define_database_entry_type(
+            "tests.one_b", [database_entry_field("a", 0, codec=t.string)], compatible_schema_ids=(a.catalog_entry().schema_id,)
+        )
+        path = self.tmp / "one.cc"
+        _open(path, a).put(a, "k", {"a": "x"})
+
+        class SecondDeleteFails(SingleFileMessagePackBackingStore):
+            calls = 0
+
+            def delete(self, type, key):
+                self.calls += 1
+                if self.calls > 1:
+                    raise OSError("second delete")
+                super().delete(type, key)
+
+        store = SecondDeleteFails(path)
+        cache = CultCache.builder().register_document_type(a).register_document_type(b).add_generic_store(store).build()
+        cache.pull_all_backing_stores()
+        cache.delete(b, "k")
+        self.assertEqual(store.calls, 1)
+        self.assertIsNone(cache.get(a, "k"))
+        self.assertEqual(SingleFileMessagePackBackingStore(path).pull_all(), [])
+
+    def test_writing_another_record_and_flushing_carries_the_marked_one_unchanged(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        original = {e.key: e for e in SingleFileMessagePackBackingStore(path).pull_all()}
+        cache.put(surface_document, "clean", {**_surface_value(), "version": 9})
+        after = {e.key: e for e in SingleFileMessagePackBackingStore(path).pull_all()}
+        for key in ("marked", "unit-arm"):
+            self.assertEqual(after[key].payload, original[key].payload, key)
+            self.assertEqual(after[key].schema_id, original[key].schema_id, key)
+            self.assertEqual(after[key].stored_at, original[key].stored_at, key)
+        self.assertNotEqual(after["clean"].payload, original["clean"].payload)
+        self.assertEqual(after["marked"].catalog_entry, original["marked"].catalog_entry)
+
+    def test_the_vector_store_loads_under_the_reference_documents_and_marks_nothing_else(self) -> None:
+        path, cache = self._store("extra-slot-store.cc")
+        self.assertTrue(cache.is_writable(surface_document, "clean"))
+        self.assertFalse(cache.is_writable(surface_document, "marked"))
+        self.assertFalse(cache.is_writable(slot_unit_document, "unit-arm"))
+        self.assertEqual(
+            cache.get(slot_unit_document, "unit-arm"), {"name": "unit-arm", "outcome": UnionArm("Denied")}
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultcache-py/tests/test_union_parity.py

@@ -261,7 +261,9 @@ class UnionSurfaceVectorTests(unittest.TestCase):
             else:
                 read_only += 1
                 self.assertEqual(outcome_kind, "read-only", file)
-                self.assertEqual(surface_document.decode_payload(payload), _surface_value(), file)
+                value, mark = surface_document.decode_payload_marked(payload)
+                self.assertEqual(value, _surface_value(), file)
+                self.assertIsNotNone(mark, file)  # read past and marked: tests/test_slot_readonly.py pins what the mark holds
         self.assertEqual((refused, read_only), (5, 4))
 
 
@@ -526,7 +528,9 @@ class BoundsVectorTests(unittest.TestCase):
                     surface_document.encode_payload(surface_document.decode_payload(payload)), _vector(detail), file
                 )
             elif outcome_kind == "read-only":
-                self.assertEqual(surface_document.decode_payload(payload), _surface_value(), file)
+                value, mark = surface_document.decode_payload_marked(payload)
+                self.assertEqual(value, _surface_value(), file)
+                self.assertIsNotNone(mark, file)
             else:
                 with self.assertRaises(ValueError, msg=file) as caught:
                     surface_document.decode_payload(payload)
@@ -657,6 +661,78 @@ def _as_tuple(tree: object) -> object:
     return tuple(_as_tuple(child) for child in tree) if isinstance(tree, list) else tree
 
 
+
+class BytesAfterVectorTests(unittest.TestCase):
+    CLAUSE = "bytes after its first MessagePack value (refused on read)"
+
+    def _assert_chain_clean(self, error: BaseException, file: str) -> None:
+        link: BaseException | None = error
+        while link is not None:
+            self.assertNotIn(CANARY, str(link), file)
+            self.assertNotIsInstance(link, msgpack.ExtraData, file)
+            link = link.__cause__ or link.__context__
+
+    def test_every_bytes_after_vector_is_refused(self) -> None:
+        base = _vector("union-surface.msgpack")
+        entries = msgpack.unpackb(_vector("bytes-after-outcomes.msgpack"), raw=False)
+        self.assertEqual(len(entries), 4)
+        for file, outcome_kind, union, key, detail in entries:
+            self.assertEqual((outcome_kind, union, key, detail), ("refused", "UnionSurface", None, "bytes-after"), file)
+            payload = _vector(file)
+            self.assertTrue(payload.startswith(base), file)
+            count = len(payload) - len(base)
+            with self.assertRaises(ValueError, msg=file) as caught:
+                surface_document.decode_payload(payload)
+            error = caught.exception
+            self.assertIs(type(error), ValueError, file)
+            self.assertNotIsInstance(error, CultCachePayloadDepthError, file)
+            self.assertEqual(
+                str(error), f"{surface_document.type} payload has {count} {self.CLAUSE}.", file
+            )
+            self.assertNotIn("the limit is", str(error), file)
+            self._assert_chain_clean(error, file)
+
+    def test_a_single_file_store_holding_a_tail_as_a_record_payload_refuses_on_load(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "tail.cc"
+            shutil.copyfile(VECTORS / "union-surface.cc", path)
+            store = SingleFileMessagePackBackingStore(path)
+            [envelope] = store.pull_all()
+            store.push(dataclasses.replace(envelope, payload=_vector("bytes-after-nil.msgpack")))
+            cache = (
+                CultCache.builder()
+                .register_document_type(surface_document)
+                .add_generic_store(SingleFileMessagePackBackingStore(path))
+                .build()
+            )
+            with self.assertRaises(ValueError) as caught:
+                cache.pull_all_backing_stores()
+            self.assertIn(f"1 {self.CLAUSE}", str(caught.exception))
+            self.assertIn(surface_document.type, str(caught.exception))
+            self.assertIsNone(cache.get(surface_document, "surface"))
+
+    def test_depth_wins_over_a_tail_whatever_the_unpackers_own_stack_limit(self) -> None:
+        # Vector-independent: a value nested past 256 is the depth refusal even with a tail, as C# throws at container 257
+        # before it reaches the tail; 2000 is past msgpack's own stack, so the winner is not a library constant.
+        for depth in (257, 300, 900, 2000, 100000):
+            for tail in (b"\xc0", b"\xc1\xc1"):
+                with self.subTest(depth=depth, tail=len(tail)):
+                    with self.assertRaises(CultCachePayloadDepthError) as caught:
+                        surface_document.decode_payload(b"\x91" * depth + b"\xc0" + tail)
+                    self.assertIn("refused on read", str(caught.exception))
+        for depth in (1, 255, 256):
+            with self.subTest(at=depth):
+                with self.assertRaises(ValueError) as caught:
+                    surface_document.decode_payload(b"\x91" * depth + b"\xc0\xc0")
+                self.assertNotIsInstance(caught.exception, CultCachePayloadDepthError)
+                self.assertIn(f"1 {self.CLAUSE}", str(caught.exception))
+
+    def test_a_payload_that_ends_early_is_the_decoders_not_bytes_after(self) -> None:
+        truncated = _vector("union-surface.msgpack")[:-1]
+        with self.assertRaises(Exception) as caught:
+            surface_document.decode_payload(truncated)
+        self.assertNotIn("bytes after", str(caught.exception))
+
 class PayloadDepthRuleTests(unittest.TestCase):
     """The nesting rule at its seam, on definitions that are not unions: the same routine serves any payload codec."""
 

packages/cultcache-py/tests/test_unique_index.py

@@ -0,0 +1,664 @@
+from __future__ import annotations
+
+import itertools
+import shutil
+import tempfile
+import unittest
+from dataclasses import asdict, dataclass
+from decimal import Decimal
+from pathlib import Path
+
+import msgpack
+
+from cultcache_py import (
+    CultCache,
+    CultCacheEnvelope,
+    SingleFileMessagePackBackingStore,
+    define_database_entry_type,
+    define_document_type,
+    leaves as t,
+    database_entry_field,
+)
+from cultcache_py.cache import CultCacheError, index_text
+
+# variants:ruling:unique-indexes. `indexes` are unique within one type, `roles` are selection aliases. The vectors in
+# tests/vectors/unique-index are written by the C# reference; the rest of the behaviour is pinned here.
+VECTORS = Path(__file__).resolve().parents[3] / "tests" / "vectors" / "unique-index"
+
+
+@dataclass
+class Item:
+    sku: object = None
+    serial: object = None
+    group: object = None
+
+
+def refusal(key_a: str, key_b: str, schema_name: str, alias: str) -> str:
+    return f"Records {key_a} and {key_b} ({schema_name}) both hold unique index '{alias}'; an index value names one record."
+
+
+def item_doc(type: str = "item", *, indexes=None, roles=None):
+    return define_document_type(
+        type,
+        encode=asdict,
+        decode=lambda raw: Item(**raw),
+        indexes={"sku": "sku", "serial": "serial"} if indexes is None else indexes,
+        roles={"group": "group"} if roles is None else roles,
+    )
+
+
+def envelope(document, key: str, item: Item) -> CultCacheEnvelope:
+    return CultCacheEnvelope.create(key=key, type=document.type, payload=document.encode_payload(item))
+
+
+def cache_of(*documents, store=None) -> CultCache:
+    builder = CultCache.builder()
+    for document in documents:
+        builder.register_document_type(document)
+    if store is not None:
+        builder.add_generic_store(store)
+    return builder.build()
+
+
+class RecordingStore:
+    """A store that counts what reaches it; the judge must refuse before any store call."""
+
+    def __init__(self) -> None:
+        self.pushed: list[str] = []
+
+    def pull_all(self):
+        return []
+
+    def push(self, envelope) -> None:
+        self.pushed.append(envelope.key)
+
+    def push_all(self, envelopes) -> None:
+        self.pushed.extend(envelope.key for envelope in envelopes)
+
+    def delete(self, type, key) -> None:
+        pass
+
+
+class IndexTextTests(unittest.TestCase):
+    def test_canonical_text(self) -> None:
+        cases = [
+            ("S-1", "S-1"),
+            (" a ", " a "),
+            ("", ""),
+            ("\x1f", "\x1f"),
+            ("\x1c", "\x1c"),
+            ("\x1d", "\x1d"),
+            ("\x1e", "\x1e"),
+            ("᠎", "᠎"),
+            ("​", "​"),
+            (True, "True"),
+            (False, "False"),
+            (7, "7"),
+            (-7, "-7"),
+            (9223372036854775807, "9223372036854775807"),
+            (18446744073709551615, "18446744073709551615"),
+            (0.0, "0"),
+            (-0.0, "0"),
+            (2.0, "2"),
+            (-3.0, "-3"),
+            (1e21, "1000000000000000000000"),
+            (0.1, "0.1000000000000000055511151231257827021181583404541015625"),
+            (-0.5, "-0.5"),
+            (2.5e-07, "0.00000024999999999999998868702795647156467140348468092270195484161376953125"),
+        ]
+        for value, text in cases:
+            with self.subTest(value=value):
+                self.assertEqual(index_text(value), text)
+                self.assertIsInstance(index_text(value), str)
+
+    def test_no_value(self) -> None:
+        blank = ["", " ", "\t", "\n", "\x0b", "\x0c", "\r", "\x85", "\xa0", " ", "
", "
", " ",
+                 " ", "　", " 　\x85 ", *map(chr, range(0x2000, 0x200B))]
+        for value in [None, float("nan"), float("inf"), float("-inf"), *blank]:
+            with self.subTest(value=repr(value)):
+                self.assertIsNone(index_text(value))
+
+    def test_blank_set_is_exactly_the_csharp_set(self) -> None:
+        csharp = {*range(0x09, 0x0E), 0x20, 0x85, 0xA0, 0x1680, *range(0x2000, 0x200B), 0x2028, 0x2029, 0x202F, 0x205F, 0x3000}
+        self.assertEqual(len(csharp), 25)
+        got = {code for code in range(0x110000) if 0xD800 > code or code > 0xDFFF if index_text(chr(code)) is None}
+        self.assertEqual(got, csharp)
+        # Python's isspace is the wrong test: it also counts U+001C-001F.
+        self.assertTrue("\x1f".isspace())
+        self.assertEqual(index_text("\x1f"), "\x1f")
+
+    def test_floats_render_exactly_not_through_str(self) -> None:
+        for value in (0.1, 1e-7, 123456789.123456789, 5e-324, 1.7976931348623157e308):
+            with self.subTest(value=value):
+                text = index_text(value)
+                self.assertNotIn("e", text.lower())
+                self.assertEqual(Decimal(text), Decimal(value))
+                self.assertFalse(text.endswith("0") and "." in text)
+
+    def test_bool_is_not_an_integer(self) -> None:
+        self.assertEqual(index_text(True), "True")
+        self.assertNotEqual(index_text(True), "1")
+
+
+class UniqueIndexTests(unittest.TestCase):
+    def test_a_write_of_a_held_value_at_another_key_is_refused_by_every_write_path(self) -> None:
+        for alias in ("sku", "serial"):  # two unique indexes: each is judged
+            other = "serial" if alias == "sku" else "sku"
+            paths = {
+                "put": lambda cache, d, k, i: cache.put(d, k, i),
+                "put_envelope": lambda cache, d, k, i: cache.put_envelope(d, envelope(d, k, i)),
+                "put_envelopes": lambda cache, d, k, i: cache.put_envelopes(d, [envelope(d, k, i)]),
+                "update": lambda cache, d, k, i: cache.update(d, k, lambda _held: i),
+            }
+            for name, write in paths.items():
+                with self.subTest(alias=alias, path=name):
+                    document = item_doc()
+                    store = RecordingStore()
+                    cache = cache_of(document, store=store)
+                    cache.put(document, "item:b", Item(sku="CANARY-b", serial="canary-b"))
+                    cache.put(document, "item:a", Item(sku="CANARY-a", serial="canary-a"))
+                    before = cache.snapshot()
+                    pushed = list(store.pushed)
+                    taken = "CANARY-b" if alias == "sku" else "canary-b"
+                    landing = Item(**{alias: taken, other: "fresh"})
+                    with self.assertRaises(CultCacheError) as caught:
+                        write(cache, document, "item:a", landing)
+                    self.assertEqual(str(caught.exception), refusal("item:a", "item:b", "item", alias))
+                    self.assertNotIn("anary", str(caught.exception))
+                    self.assertEqual(cache.snapshot(), before)
+                    self.assertEqual(store.pushed, pushed)
+                    self.assertEqual(cache.get_key_by_index(document, alias, taken), "item:b")
+                    self.assertIsNone(cache.get_key_by_index(document, other, "fresh"))
+
+    def test_a_record_rewriting_its_own_key_keeps_its_value(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku="S", serial="1", group="g"))
+        cache.put(document, "item:a", Item(sku="S", serial="2", group="h"))
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:a")
+        self.assertIsNone(cache.get_key_by_index(document, "serial", "1"))
+        self.assertEqual(cache.get_key_by_index(document, "serial", "2"), "item:a")
+
+    def test_the_refusal_names_the_schema_not_the_type(self) -> None:
+        document = define_document_type(
+            "t.item", indexes={"sku": "sku"}, schema_name="schema.Item", schema_id="schema.Item.v1"
+        )
+        cache = cache_of(document)
+        cache.put(document, "k:1", {"sku": "S"})
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put(document, "k:2", {"sku": "S"})
+        self.assertEqual(str(caught.exception), refusal("k:1", "k:2", "schema.Item", "sku"))
+
+    def test_the_two_smallest_keys_are_named_in_ordinal_order(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:m", Item(sku="S"))
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put_envelopes(document, [envelope(document, "item:z", Item(sku="S")), envelope(document, "item:A", Item(sku="S"))])
+        self.assertEqual(str(caught.exception), refusal("item:A", "item:m", "item", "sku"))
+
+    def test_put_envelopes_holding_one_value_twice_is_refused_whole(self) -> None:
+        document = item_doc()
+        store = RecordingStore()
+        cache = cache_of(document, store=store)
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put_envelopes(
+                document,
+                [
+                    envelope(document, "item:b", Item(sku="S")),
+                    envelope(document, "item:c", Item(sku="T")),
+                    envelope(document, "item:a", Item(sku="S")),
+                ],
+            )
+        self.assertEqual(str(caught.exception), refusal("item:a", "item:b", "item", "sku"))
+        self.assertEqual(cache.snapshot(), {})
+        self.assertEqual(store.pushed, [])
+        self.assertIsNone(cache.get_key_by_index(document, "sku", "T"))
+
+    def test_verdict_does_not_depend_on_batch_order(self) -> None:
+        document = item_doc()
+        rows = [("item:a", Item(sku="S", serial="1")), ("item:b", Item(sku="T", serial="1")), ("item:c", Item(sku="U"))]
+        for order in itertools.permutations(rows):
+            with self.subTest(order=[key for key, _ in order]):
+                cache = cache_of(document)
+                with self.assertRaises(CultCacheError) as caught:
+                    cache.put_envelopes(document, [envelope(document, key, item) for key, item in order])
+                self.assertEqual(str(caught.exception), refusal("item:a", "item:b", "item", "serial"))
+                self.assertEqual(cache.snapshot(), {})
+
+    def test_put_envelopes_swapping_two_records_values_lands(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku="S", serial="1"))
+        cache.put(document, "item:b", Item(sku="T", serial="2"))
+        cache.put_envelopes(
+            document,
+            [envelope(document, "item:a", Item(sku="T", serial="2")), envelope(document, "item:b", Item(sku="S", serial="1"))],
+        )
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:b")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "T"), "item:a")
+        self.assertEqual(cache.get_key_by_index(document, "serial", "1"), "item:b")
+        self.assertEqual(cache.get_key_by_index(document, "serial", "2"), "item:a")
+
+    def test_a_batch_may_take_a_value_the_batch_releases(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku="S"))
+        cache.put_envelopes(document, [envelope(document, "item:a", Item(sku="T")), envelope(document, "item:b", Item(sku="S"))])
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:b")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "T"), "item:a")
+
+    def test_delete_frees_the_value(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku="S"))
+        cache.delete(document, "item:a")
+        self.assertIsNone(cache.get_key_by_index(document, "sku", "S"))
+        cache.put(document, "item:b", Item(sku="S"))
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:b")
+
+    def test_blank_values_never_conflict(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        blanks = ["", " ", "\x85", "　", None]
+        for number, blank in enumerate(blanks):
+            cache.put(document, f"item:blank{number}", Item(sku=blank, serial=blank))
+        cache.put_envelopes(document, [envelope(document, "item:more", Item(sku="  ")), envelope(document, "item:more2", Item(sku=""))])
+        for blank in ("", " ", "\x85"):
+            self.assertIsNone(cache.get_key_by_index(document, "sku", blank))
+        # U+001F and U+FEFF are values.
+        cache.put(document, "item:us", Item(sku="\x1f"))
+        cache.put(document, "item:bom", Item(sku=""))
+        self.assertEqual(cache.get_key_by_index(document, "sku", "\x1f"), "item:us")
+        self.assertEqual(cache.get_key_by_index(document, "sku", ""), "item:bom")
+        with self.assertRaises(CultCacheError):
+            cache.put(document, "item:us2", Item(sku="\x1f"))
+
+    def test_values_compare_as_the_canonical_text(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku=1))
+        for same in (1, 1.0, "1"):
+            with self.subTest(same=same), self.assertRaises(CultCacheError):
+                cache.put(document, "item:b", Item(sku=same))
+        cache.put(document, "item:true", Item(sku=True))
+        self.assertEqual(cache.get_key_by_index(document, "sku", "True"), "item:true")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "1"), "item:a")
+        cache.put(document, "item:f", Item(sku=0.1))
+        self.assertEqual(cache.get_key_by_index(document, "sku", "0.1000000000000000055511151231257827021181583404541015625"), "item:f")
+
+    def test_two_types_may_share_an_alias_and_a_value(self) -> None:
+        one, two = item_doc("one"), item_doc("two")
+        cache = cache_of(one, two)
+        cache.put(one, "k:1", Item(sku="S", serial="1"))
+        cache.put(two, "k:2", Item(sku="S", serial="1"))
+        self.assertEqual(cache.get_key_by_index(one, "sku", "S"), "k:1")
+        self.assertEqual(cache.get_key_by_index(two, "sku", "S"), "k:2")
+        cache.delete(one, "k:1")
+        self.assertEqual(cache.get_key_by_index(two, "sku", "S"), "k:2")
+
+    def test_roles_may_share_values_and_are_not_looked_up(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:a", Item(sku="1", group="g"))
+        cache.put(document, "item:b", Item(sku="2", group="g"))
+        self.assertIsNone(cache.get_key_by_index(document, "group", "g"))
+        self.assertIsNone(cache.get_by_index(document, "group", "g"))
+
+    def test_an_alias_in_both_indexes_and_roles_is_refused(self) -> None:
+        with self.assertRaisesRegex(ValueError, "both an index and a role"):
+            define_document_type("bad", indexes={"a": "a"}, roles={"a": "a"})
+        with self.assertRaisesRegex(ValueError, "both an index and a role"):
+            define_database_entry_type("bad", [("a", 0)], indexes={"a": "a"}, roles={"a": "a"})
+        define_document_type("fine", indexes={"a": "a"}, roles={"b": "a"})
+
+    def test_register_index_over_held_duplicates_installs_nothing(self) -> None:
+        document = item_doc(indexes={}, roles={})
+        cache = cache_of(document)
+        cache.put(document, "item:b", Item(sku="S", serial="1"))
+        cache.put(document, "item:a", Item(sku="S", serial="2"))
+        with self.assertRaises(CultCacheError) as caught:
+            cache.register_index(document, "sku", "sku")
+        self.assertEqual(str(caught.exception), refusal("item:a", "item:b", "item", "sku"))
+        self.assertIsNone(cache.get_key_by_index(document, "sku", "S"))
+        cache.register_index(document, "serial", "serial")  # an installed alias is not poisoned by the refused one
+        self.assertEqual(cache.get_key_by_index(document, "serial", "2"), "item:a")
+        # Nothing was installed, so a write sharing the refused alias's value is still admitted.
+        cache.put(document, "item:c", Item(sku="S", serial="3"))
+
+    def test_registration_names_an_installed_alias_a_caller_mutated_into_a_collision(self) -> None:
+        document = item_doc(indexes={"sku": "sku"}, roles={})
+        cache = cache_of(document)
+        cache.put(document, "item:x", Item(sku="1", serial="s1"))
+        cache.put(document, "item:y", Item(sku="2", serial="s2"))
+        cache.get_required(document, "item:y").sku = "1"  # the cache hands out its held value
+        with self.assertRaises(CultCacheError) as caught:
+            cache.register_index(document, "serial", "serial")
+        self.assertEqual(str(caught.exception), refusal("item:x", "item:y", "item", "sku"))
+
+    def test_derive_names_the_ordinal_first_alias_then_value(self) -> None:
+        document = item_doc(indexes={}, roles={})
+        cache = cache_of(document)
+        cache.put(document, "item:1", Item(sku="a", serial="p", group="x"))
+        cache.put(document, "item:2", Item(sku="a", serial="p", group="x"))
+        cache.put(document, "item:3", Item(sku="b", serial="q", group="y"))
+        cache.put(document, "item:4", Item(sku="b", serial="q", group="y"))
+        with self.assertRaises(CultCacheError) as caught:
+            cache.register_index(document, "serial", "serial")
+        self.assertEqual(str(caught.exception), refusal("item:1", "item:2", "item", "serial"))
+
+    def test_a_document_in_two_unique_indexes_loads_and_registers_through_every_path(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "items.cc"
+            document = item_doc()
+            cache = cache_of(document, store=SingleFileMessagePackBackingStore(path))
+            cache.put(document, "item:a", Item(sku="S", serial="1"))
+            cache.put(document, "item:b", Item(sku="T", serial="2"))
+            # a store written by a looser definition, then opened by this one
+            loose = item_doc(indexes={}, roles={})
+            writer = cache_of(loose, store=SingleFileMessagePackBackingStore(path))
+            writer.pull_all_backing_stores()
+            writer.put(loose, "item:c", Item(sku="U", serial="2"))
+            before = path.read_bytes()
+            reader = cache_of(document, store=SingleFileMessagePackBackingStore(path))
+            with self.assertRaises(CultCacheError) as caught:
+                reader.pull_all_backing_stores()
+            self.assertEqual(str(caught.exception), refusal("item:b", "item:c", "item", "serial"))
+            self.assertEqual(path.read_bytes(), before)
+            self.assertEqual(reader.snapshot(), {})
+
+    def test_a_refused_load_keeps_the_held_state(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "items.cc"
+            loose = item_doc(indexes={}, roles={})
+            writer = cache_of(loose, store=SingleFileMessagePackBackingStore(path))
+            writer.put(loose, "item:a", Item(sku="S"))
+            writer.put(loose, "item:b", Item(sku="S"))
+            document = item_doc()
+            cache = cache_of(document, store=SingleFileMessagePackBackingStore(path))
+            with self.assertRaises(CultCacheError):
+                cache.pull_all_backing_stores()
+            self.assertIsNone(cache.get_key_by_index(document, "sku", "S"))
+            self.assertEqual(cache.get_all(document), [])
+
+
+class SimulationFactTests(unittest.TestCase):
+    def test_simulation_fact_catalog_entry_is_unchanged_by_indexes_to_roles(self) -> None:
+        import re
+
+        from cultnet_py.cultmesh_contracts import SIMULATION_FACT_DOCUMENT_TYPE, simulation_fact_document as document
+
+        aliases = {"shard": "shard_id", "frame": "frame", "subject": "subject_id", "claim_kind": "claim_kind"}
+        self.assertEqual(document.roles, aliases)
+        self.assertEqual(document.indexes, {})
+        entry = document.catalog_entry()
+        snake = lambda name: re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()  # noqa: E731
+        twin = define_database_entry_type(
+            SIMULATION_FACT_DOCUMENT_TYPE,
+            [(snake(m.member_name), m.slot) for m in entry.members],
+            name="fact_id",
+            indexes=aliases,
+            schema_name=entry.schema_name,
+            schema_version=entry.schema_version,
+        )
+        self.assertEqual(entry.canonical_schema_json, twin.catalog_entry().canonical_schema_json)
+        self.assertEqual(entry.content_hash, twin.catalog_entry().content_hash)
+        self.assertEqual(entry.members, twin.catalog_entry().members)
+        self.assertEqual({m.index_alias for m in entry.members if m.index_alias}, set(aliases))
+
+    def test_facts_sharing_every_role_value_are_all_admitted(self) -> None:
+        from cultnet_py.cultmesh_contracts import CultMeshSimulationFact, simulation_fact_document as document
+
+        cache = cache_of(document)
+        for number in range(3):
+            fact = CultMeshSimulationFact.from_candidate(
+                {"shardId": "s", "shardEpoch": 1, "frame": 4, "subjectId": "x", "claimKind": "k", "claimHash": f"h{number}",
+                 "witnessCount": 1, "supportWeight": 1.0, "totalWeight": 1.0, "confidence": 1.0}
+            )
+            cache.put(document, f"simulation:{number}", fact)
+        self.assertEqual(len(cache.get_all(document)), 3)
+        self.assertIsNone(cache.get_key_by_index(document, "shard", "s"))
+
+
+class VectorTests(unittest.TestCase):
+    def test_values_rows(self) -> None:
+        document = item_doc(indexes={"sku": "sku"}, roles={})
+        for label, kind, value, text in msgpack.unpackb((VECTORS / "values.msgpack").read_bytes(), raw=False):
+            with self.subTest(label=label):
+                self.assertEqual(index_text(value), text)
+                cache = cache_of(document)
+                cache.put(document, "item:1", Item(sku=value))
+                if text is None:
+                    cache.put(document, "item:2", Item(sku=value))  # blank: two records commit
+                    self.assertEqual(len(cache.get_all(document)), 2)
+                else:
+                    self.assertEqual(cache.get_key_by_index(document, "sku", text), "item:1")
+                    with self.assertRaises(CultCacheError):
+                        cache.put(document, "item:2", Item(sku=value))
+
+    def test_store_verdicts(self) -> None:
+        unit = define_database_entry_type
+        outcomes = msgpack.unpackb((VECTORS / "outcomes.msgpack").read_bytes(), raw=False)
+        self.assertEqual(len(outcomes), 3)
+        for name, alias, verdict, key_a, key_b in outcomes:
+            for roles_first in (False, True):  # the verdict does not depend on declaration order
+                with self.subTest(file=name, alias=alias, roles_first=roles_first), tempfile.TemporaryDirectory() as tmp:
+                    path = Path(tmp) / name
+                    shutil.copyfile(VECTORS / name, path)
+                    before = path.read_bytes()
+                    fields = [database_entry_field("sku", 0, codec=t.string), database_entry_field("category", 1, codec=t.string)]
+                    declared = {"indexes": {alias: "sku"} if alias else {}, "roles": {} if alias else {"Sku": "sku"}}
+                    if roles_first:
+                        declared = dict(reversed(list(declared.items())))
+                    document = unit(
+                        "tests.unique_item",
+                        fields,
+                        schema_id="sha256:93bb890de83069061af696b23f94fd32fb3c2dad3c91ee645e8add56085f1882",
+                        schema_name="tests.unique_item",
+                        **declared,
+                    )
+                    cache = cache_of(document, store=SingleFileMessagePackBackingStore(path))
+                    if verdict == "open":
+                        cache.pull_all_backing_stores()
+                        self.assertGreaterEqual(len(cache.get_all(document)), 2)
+                    else:
+                        with self.assertRaises(CultCacheError) as caught:
+                            cache.pull_all_backing_stores()
+                        self.assertEqual(str(caught.exception), refusal(key_a, key_b, "tests.unique_item", alias))
+                        self.assertNotIn("S-1", str(caught.exception))
+                        self.assertEqual(cache.snapshot(), {})
+                    self.assertEqual(path.read_bytes(), before)
+
+
+    def test_refusals(self) -> None:
+        ids = {
+            "tests.unique_item": "sha256:93bb890de83069061af696b23f94fd32fb3c2dad3c91ee645e8add56085f1882",
+            "tests.uq_pair": "sha256:2538cceafb6dcbce22ef11b932ecb804af5f96bc3aaedff692a52d3640433e60",
+            "tests.uq_alias": "sha256:77a77a394ebd8bf71e14b9b6f2cea4978c25d4e705fd12364f660edbf6c63b1f",
+            "tests.uq_wide": "sha256:b79eecd11eed5e456902f095d2748da7f59125c4c8972b0da7dddc81d07fc03f",
+            "tests.uq_alpha": "sha256:53aeaf2ea9b25e85ade6b15fc04c7653e7b206c87e258f1aa74dd32a840a1389",
+            "tests.uq_beta": "sha256:45ed62a64c91f6d815d3ec975c4a4a1b2ce07b6e7262a32d828673cf10899586",
+        }
+        aliases = {
+            "tests.uq_pair": {"Sku": "sku", "Alt": "second"},
+            "tests.uq_alias": {"Sku": "sku", "alt": "second"},
+            "tests.uq_wide": {"\uff21": "sku", "\U00010400": "second"},  # U+FF21 and U+10400: code-unit order puts the astral alias first
+        }
+        documents = {
+            name: define_database_entry_type(
+                name,
+                [database_entry_field("sku", 0, codec=t.string), database_entry_field("second", 1, codec=t.string)],
+                indexes=aliases.get(name, {"Sku": "sku"}),
+                roles={},
+                schema_id=schema_id,
+                schema_name=name,
+            )
+            for name, schema_id in ids.items()
+        }
+        rows = msgpack.unpackb((VECTORS / "refusals.msgpack").read_bytes(), raw=False)
+        walked = 0
+        for label, ops, expected in rows:
+            if any(op[0] == "commit" and len({schema for _, schema, _, _ in op[1]}) > 1 for op in ops):
+                continue  # put_envelopes takes one type: no batch across types (rows 3 and 26)
+            with self.subTest(label=label), tempfile.TemporaryDirectory() as tmp:
+                path = Path(tmp) / "store.cc"
+                state: dict[str, CultCache] = {}
+
+                def perform(op) -> None:
+                    if op[0] == "open":
+                        if op[1] is not None:
+                            shutil.copyfile(VECTORS / op[1], path)
+                        state["cache"] = cache_of(*documents.values(), store=SingleFileMessagePackBackingStore(path))
+                        state["cache"].pull_all_backing_stores()
+                    elif op[0] == "pull":
+                        shutil.copyfile(VECTORS / op[1], path)
+                        state["cache"].pull_all_backing_stores()
+                    else:
+                        document = documents[op[1][0][1]]
+                        state["cache"].put_envelopes(
+                            document, [envelope(document, key, {"sku": sku, "second": second}) for key, _, sku, second in op[1]]
+                        )
+
+                for op in ops[:-1]:
+                    perform(op)
+                if expected is None:
+                    perform(ops[-1])
+                else:
+                    last = ops[-1]
+                    if last[0] == "open":
+                        before = (VECTORS / last[1]).read_bytes()
+                    elif last[0] == "pull":
+                        before = (VECTORS / last[1]).read_bytes()
+                    else:
+                        before = path.read_bytes() if path.exists() else b""
+                    k1, k2, schema, alias = expected
+                    with self.assertRaises(CultCacheError) as caught:
+                        perform(last)
+                    self.assertEqual(str(caught.exception), refusal(k1, k2, schema, alias))
+                    self.assertEqual(path.read_bytes() if path.exists() else b"", before)
+                walked += 1
+        self.assertEqual(walked, 35)
+
+
+class ListStore(RecordingStore):
+    """A store whose contents the test swaps between loads: another process rewrote the file."""
+
+    def __init__(self, envelopes=()) -> None:
+        super().__init__()
+        self.envelopes = list(envelopes)
+
+    def pull_all(self):
+        return list(self.envelopes)
+
+
+class BatchAndOrderTests(unittest.TestCase):
+    def test_a_batch_naming_a_key_twice_lands_the_last_record_and_keeps_every_held_lookup(self) -> None:
+        # C# CultCacheBatch stages one operation per key, the last one named.
+        document = item_doc()
+        store = RecordingStore()
+        cache = cache_of(document, store=store)
+        cache.put(document, "item:h", Item(sku="S"))
+        store.pushed.clear()
+        cache.put_envelopes(
+            document, [envelope(document, "item:k", Item(sku="S")), envelope(document, "item:k", Item(sku="T"))]
+        )
+        self.assertEqual(store.pushed, ["item:k"])
+        self.assertEqual(cache.get_required(document, "item:k").sku, "T")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:h")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "T"), "item:k")
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put(document, "item:z", Item(sku="S"))
+        self.assertEqual(str(caught.exception), refusal("item:h", "item:z", "item", "sku"))
+
+    def test_a_batch_naming_a_key_twice_is_judged_on_the_record_that_lands(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        cache.put(document, "item:h", Item(sku="S"))
+        # the first record for k would collide with h; only the last lands, so the batch is admitted
+        cache.put_envelopes(
+            document, [envelope(document, "item:k", Item(sku="S")), envelope(document, "item:k", Item(sku="T"))]
+        )
+        # and the reverse order lands the colliding record, which is refused
+        with self.assertRaises(CultCacheError):
+            cache.put_envelopes(
+                document, [envelope(document, "item:j", Item(sku="U")), envelope(document, "item:j", Item(sku="S"))]
+            )
+        self.assertNotIn("item:j", cache.snapshot().get("item", {}))
+
+    def test_a_load_judges_every_type_at_once_aliases_in_ordinal_order(self) -> None:
+        first = item_doc("first", indexes={"zeta": "sku"}, roles={})
+        second = item_doc("second", indexes={"alpha": "sku"}, roles={})
+        loose_first, loose_second = item_doc("first", indexes={}, roles={}), item_doc("second", indexes={}, roles={})
+        store = ListStore(
+            [envelope(loose_first, "f:1", Item(sku="S")), envelope(loose_first, "f:2", Item(sku="S"))]
+            + [envelope(loose_second, "s:1", Item(sku="S")), envelope(loose_second, "s:2", Item(sku="S"))]
+        )
+        cache = cache_of(first, second, store=store)
+        with self.assertRaises(CultCacheError) as caught:
+            cache.pull_all_backing_stores()
+        self.assertEqual(str(caught.exception), refusal("s:1", "s:2", "second", "alpha"))
+
+    def test_aliases_sort_by_utf16_code_unit_not_code_point(self) -> None:
+        astral, bmp = "k\U0001F600", "k\uff01"  # code points: bmp < astral; UTF-16 units: D83D < FF01
+        document = item_doc(indexes={bmp: "sku", astral: "serial"}, roles={})
+        cache = cache_of(document)
+        rows = [Item(sku="S", serial="T"), Item(sku="S", serial="T")]
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put_envelopes(document, [envelope(document, f"item:{n}", row) for n, row in enumerate(rows)])
+        self.assertEqual(str(caught.exception), refusal("item:0", "item:1", "item", astral))
+
+    def test_a_load_names_the_least_violation_whatever_order_the_store_yields(self) -> None:
+        alpha, beta = item_doc("alpha", indexes={"k": "sku"}, roles={}), item_doc("beta", indexes={"k": "sku"}, roles={})
+        loose_alpha, loose_beta = item_doc("alpha", indexes={}, roles={}), item_doc("beta", indexes={}, roles={})
+        store = ListStore(
+            [
+                envelope(loose_alpha, "a:0", Item(sku="Q")),
+                envelope(loose_beta, "b:1", Item(sku="S")),
+                envelope(loose_beta, "b:2", Item(sku="S")),
+                envelope(loose_alpha, "a:1", Item(sku="P")),
+                envelope(loose_alpha, "a:2", Item(sku="P")),
+            ]
+        )
+        cache = cache_of(alpha, beta, store=store)
+        with self.assertRaises(CultCacheError) as caught:
+            cache.pull_all_backing_stores()
+        self.assertEqual(str(caught.exception), refusal("a:1", "a:2", "alpha", "k"))
+
+    def test_register_index_refuses_an_alias_the_definition_declares_as_a_role(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        with self.assertRaises(CultCacheError):
+            cache.register_index(document, "group", "group")
+        cache.put_envelopes(
+            document, [envelope(document, "item:1", Item(group="guide")), envelope(document, "item:2", Item(group="guide"))]
+        )
+
+
+class LoadFreshnessTests(unittest.TestCase):
+    def test_a_load_is_judged_on_the_file_alone_not_against_the_held_map(self) -> None:
+        document = item_doc()
+        store = ListStore([envelope(document, "item:b", Item(sku="S")), envelope(document, "item:c", Item(sku="T"))])
+        cache = cache_of(document, store=store)
+        cache.pull_all_backing_stores()
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:b")
+        # another process moved S from b to a, and b to T's old place
+        store.envelopes = [envelope(document, "item:a", Item(sku="S")), envelope(document, "item:b", Item(sku="U")), store.envelopes[1]]
+        cache.pull_all_backing_stores()
+        self.assertEqual(cache.get_key_by_index(document, "sku", "S"), "item:a")
+        self.assertEqual(cache.get_key_by_index(document, "sku", "U"), "item:b")
+
+
+class DefinitionTests(unittest.TestCase):
+    def test_every_constructor_refuses_an_alias_in_both_indexes_and_roles(self) -> None:
+        from dataclasses import replace
+
+        from cultcache_py import DocumentDefinition
+
+        with self.assertRaisesRegex(ValueError, "both an index and a role"):
+            DocumentDefinition(type="item", indexes={"sku": "sku"}, roles={"sku": "sku"})
+        with self.assertRaisesRegex(ValueError, "both an index and a role"):
+            replace(item_doc(roles={}), roles={"sku": "sku"})
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultcache-rs/CHANGELOG.md

@@ -8,12 +8,30 @@ only in git history.
 
 ### 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.
+Semver: this is a breaking change in the 0.x line (0.3.x to 0.4.0).
+
+- A record whose payload carries unread slots is read-only. A payload with a slot past its type's declared slots, at any depth (record, nested record, list element, union arm, unit arm), still decodes, and every write or removal of its key is now refused before any store is touched: `put`, `put_envelope`, `put_raw_envelope`, `put_prepared_batch` (the whole batch) and `delete`, so `update` too. The refusal is `SchemaConflictError` with the new `unread_slots`; its message names the type and both slot counts and never a slot value. Holders of such a record used to overwrite it and drop the extra slots silently. The payload nesting refusal still runs first. A held payload this build cannot read at all (an arm it lacks from a newer writer, or a corrupt record) is read-only too: every write or removal is refused with an error naming the type and key (a newer writer's record is read with that build; a corrupt one is restored from a backup or removed at the store itself, as no cache call removes it), and `is_writable` answers false. `load_soa` is a write of every held key it omits or changes, so it refuses to drop or replace a read-only record. `is_writable` also answers false for a key a store carries as a foreign record and for a type other than the one holding the key, as the writes do. Each write over a held key decodes the held payload once to ask (about 40% of a `put` of a 200,000-element record, measured in release); keys nothing holds pay nothing.
+- cultmesh-rs `pull_rudp_catalog_snapshot` applies documents one by one with `put_raw_envelope`, so a snapshot document for a key the node holds read-only ends the pull at that document and the documents before it stay applied. C# applies a raw snapshot as one cache commit, so there a refusal applies nothing: this is a divergence, owed by follow-up `mesh-snapshot-atomic` (stage the pull through `put_prepared_batch`).
+- `SchemaConflictError` gains the public field `unread_slots: Option<UnreadSlots>`; code that builds it with a struct literal must set it (`None`).
+- A unit arm with slots (`[N, [extra...]]`) decodes as the unit arm and marks the record, where the derive refused it.
+- The registration map's value changes from the schema name to a private struct holding the schema name and the unread-slots check.
+- A single-file store written as `cultcache.store.v3` is read and written: a store the C# runtime marked v3 (it holds a record with an element id: an owned list element with a `[CultElementId]` member) keeps its header here, and is carried through every rewrite with its ids; this runtime never drops the mark. A runtime from before this change refuses a v3 store by name. Rolling back to an older release after a store has been written as v3 is one-way: there is no carry-back, so restore from a copy taken before upgrading.
 - 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).
+- `#[cultcache(index)]` means unique, as in C# `RefuseIndexSharing`: within one type and one alias no two records hold one non-blank value. A put, batch, push or load that would make two records hold a value is refused, naming both keys and the alias, and a store that already holds a duplicate does not open. A grouping index is no longer expressible; a consumer that relied on shared values must drop the `index` and look up by another way.
+- `bool` index and lookup text renders `True` / `False`, as C# does, where it rendered `true` / `false`.
+- `DatabaseEntry::UNIQUE_INDEXES` replaces `cult_indexes` as the one index declaration and changes type (its members are the unique aliases); a hand implementation overriding `cult_indexes` no longer compiles.
+- `register_entry_type` over a type that already holds records re-judges them under the new declaration (unique indexes and the global rule) and refuses, changing nothing, when they violate it. A declaration with an index also refuses when a held record cannot be decoded as the new type; a declaration without one does not read the records, so it does not.
+- A single-file store holds one record per key. The v1 and legacy readers refuse a store with two records under one key (`CultCacheStoreUnreadable`, the record `Undecodable`): the store does not open, and a write over it refuses and leaves the file. A consumer that holds such a file must repair it with the runtime that wrote it before opening it here.
+- Every single-file writer (`push`, `push_all`, `insert_entry_if_absent`, the compare-exchange and snapshot-append family, and the cache's puts and batches) refuses to put a second type under a key the store holds, with `SchemaConflictError` naming the key and both types, writing nothing. Retyping a key is a delete, then an add (one batch may hold both). A write owns the held record when its schema id equals the id the held record is stored under, as C# `WrittenOwns` asks; a type renamed under a stable id therefore replaces its own record, and a write of another type name under another id is refused (`push` of the same type name under another id still replaces the record, as before; `compare_and_swap_entry`, and a `push_all` batch holding one type under two ids, refuse it). Registered types here declare no compatible ids, so equality is the whole test. Writers used to leave two records under the key.
+- `compare_and_swap_entry` over a single file refuses an in-place retype (expected `A/k`, replacement `B/k` under another schema id) with the same `SchemaConflictError`, as `compare_exchange` does, where it used to retype the record and return `true`. A lost race still returns `false` first.
+- A cache holds one record per key. `put`, `put_envelope`, `put_raw_envelope` and a batch of a second type under a key the cache holds, or a key a store carries foreign, are refused with `SchemaConflictError` even with no store (a memory-only cache used to hold both), whatever schema id the envelope claims: another registered type's record is never owned. `put_envelope`, `put_raw_envelope`, `put_prepared_batch` and `load_soa` also refuse, at any key, an envelope whose schema id names another type registered in this cache (the id a pull would resolve the record by). An id this cache does not register is trusted as the envelope claims it: at a key this cache does not hold, the single-file store decides ownership by that id, so such an envelope can replace another writer's record stored under it, and a reader registering the type the id names serves the record as that type. Store-level writers called directly (`push`, `insert_entry_if_absent`, compare-and-swap) still trust the claimed id. A refused write or pull changes nothing. Two stores holding one key refuse the pull, naming the key and both types, and so does one store holding two records at a key that resolve to one type. A store holding a record no registered type claims now loads (it used to refuse with "No schema is registered for persisted entry type") and the record is carried, through `put_prepared_batch` too, which lays foreign records back byte for byte; `delete` at a foreign key is refused. `load_soa` refuses a second type at a key or a record at a foreign key, and still refuses an unregistered type. The redb stores still key by `(type, key)`, and their own writers (`push`, `insert_entry_if_absent`, compare-and-swap) still put a second type at a held key: a cache now refuses to pull such a redb store with `SchemaConflictError`, where it used to load both records.
+- A write of the same type under a held key replaces the record by key, and in one `push_all` the last given of several entries under a key and a schema id is the record, whatever their type names. The redb stores are unchanged and still key by type and key.
 
 ### 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`).
+- `UnreadSlots { type_name, slot_count, declared_count, occurrences }`, `decode_payload_marked` (the decode that returns the mark) and `CultCache::is_writable(type, key)`. The derives' slot visitors note into a thread-local scope the decode entry opens (`__enter_slots`, `__note_unread_slots`, `__UnitArmSlots`, doc-hidden); a decode outside that entry notes nothing.
+- `CultCache::foreign_records()` and `ForeignRecord { key, schema_id, schema_name, stored_at }`: the records the last pull found that no registered type claims, sorted by key.
+- 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 find the one with the smallest key (an index value is unique, below). 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]

packages/cultcache-rs/README.md

@@ -21,8 +21,14 @@ CultCache is a domain cache with persistence adapters.
 
 - `CultCache` is the query and mutation surface.
 - Domain structs implement `DatabaseEntry`.
-- Entries are stored behind a `type::key` identity, so multiple entry types
-  can share a logical key without colliding.
+- A cache holds one record per key whatever its type. Records are held per
+  `(type, key)`, but a write of a second type under a key the cache holds, or a
+  key a store carries foreign, is refused with `SchemaConflictError` naming the
+  key (no store needed); retyping a key is a delete, then an add. A store
+  record no registered type claims loads: the cache does not serve it, lists it
+  in `foreign_records()`, lays it back byte for byte through every write
+  including `put_prepared_batch`, and refuses a write or delete at its key.
+  Registering a type that claims its schema id picks it up at the next pull.
 - Each payload is encoded directly from the known `DatabaseEntry` type into
   MessagePack bytes.
 - Backing stores are adapters, not the public data model.
@@ -230,6 +236,17 @@ assert_eq!(rmp_serde::from_slice::<Node>(&bytes)?, tree);
 # Ok::<(), Box<dyn std::error::Error>>(())
 ```
 
+## Records written by a newer build
+
+A payload that carries a slot past the slots its type declares, in a record, a nested record, a list element or a union
+arm (a unit arm declares none), still decodes: the extra slots are skipped. The cache then holds that record read-only,
+because writing it would drop what the newer writer stored. `put`, `put_envelope`, `put_raw_envelope`,
+`put_prepared_batch` and `delete` of its key are refused with `SchemaConflictError`, whose `unread_slots` names the type
+and the slot counts and never a value; `CultCache::is_writable(type, key)` answers the same check. An untouched
+read-only record keeps its bytes through every other write. A short payload (missing trailing slots) is not marked, and
+a payload nested past `MAX_PAYLOAD_DEPTH` is refused before anything is read. `decode_payload_marked` is the decode that
+returns the `UnreadSlots` mark. This runtime has no compatible schema ids, so no mark is consented.
+
 ## Structure Of Arrays
 
 The C# CultCache hot path exposes CPU-local SoA scans as:
@@ -394,6 +411,10 @@ fn outcome(error: &anyhow::Error) {
 }
 ```
 
+## Store format and rollback
+
+A store whose elements hold an id is marked `cultcache.store.v3` by the C# runtime. This runtime reads and writes a v3 single-file store, keeps the header it read and carries the ids through a rewrite; it never drops the mark, so it has no carry-back. A cultcache-rs from before element ids refuses a v3 store by name, so rolling back to it after a store has been written as v3 is one-way: restore from a copy taken before upgrading, and upgrade every reader before any writer. (The C# line is different: CultLib 1.x does not refuse; see the GameCult.Caching README.)
+
 ## Near-Term Ergonomic Improvements
 
 1. **Derive macro**
@@ -412,7 +433,9 @@ fn outcome(error: &anyhow::Error) {
 
 3. **Name and index lookups**
    - `cache.get_by_name::<T>("Potion")`
-   - `cache.get_by_index::<T>("faction", "Lucent")`
+   - `cache.get_by_index::<T>("callsign", "Lucent-7")`: `#[cultcache(index)]` is unique. Within one type no two
+     records hold one non-blank value of the alias; a put, batch or load that would make two is refused, naming both
+     keys and the alias, and writes nothing. A grouping (faction, kind, status) is not an index: filter `get_all`.
    - generated extractors instead of reflection strings
 
 4. **Schema/version metadata**
@@ -452,7 +475,7 @@ That is the Rust version of the original trick:
 
 - C# refuses to store objects outside the `DatabaseEntry` root type.
 - Runtime-visible `DatabaseEntry` subclasses get dedicated formatters.
-- Unknown or unregistered types are rejected.
+- A write of an unregistered type is rejected; a stored record of an unregistered type is carried as foreign, not decoded.
 - MessagePack payload bytes deserialize through known concrete formatters, not
   an open-world type loader or generic structured-value bridge.
 

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

@@ -69,23 +69,16 @@ fn database_entry_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStr
             }
         }
     });
-    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)| {
+    let index_members: Vec<_> = slots.iter().filter_map(|slot| slot.index.as_ref().map(|alias| (alias, &slot.ident))).collect();
+    let index_rows = index_members.iter().map(|(alias, member)| {
         quote! {
-            if let ::std::option::Option::Some(value) = ::cultcache_rs::CultLookupValue::lookup_value(&self.#member) {
-                held.push((#alias, value));
-            }
+            (#alias, (|record: &Self| ::cultcache_rs::CultLookupValue::lookup_value(&record.#member))
+                as fn(&Self) -> ::std::option::Option<::std::string::String>)
         }
     });
-    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
-            }
-        }
+    let index_rows: Vec<_> = index_rows.collect();
+    let unique_indexes = (!index_rows.is_empty()).then(|| {
+        quote! { const UNIQUE_INDEXES: &'static [::cultcache_rs::CultIndexMember<Self>] = &[#(#index_rows),*]; }
     });
 
     Ok(quote! {
@@ -93,8 +86,8 @@ fn database_entry_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStr
             const TYPE: &'static str = #entry_type;
             const SCHEMA_NAME: &'static str = #schema_name;
             const GLOBAL: bool = #global;
+            #unique_indexes
             #name_fn
-            #indexes_fn
         }
 
         #codec
@@ -388,6 +381,7 @@ fn slot_codec(ident: &syn::Ident, slots: &[CultCacheSlot]) -> proc_macro2::Token
                     where
                         __A: ::serde::de::SeqAccess<'de>,
                     {
+                        let __ticket = ::cultcache_rs::__enter_slots();
                         #(#option_declarations)*
                         let mut index = 0usize;
                         while index <= #max_slot {
@@ -397,7 +391,15 @@ fn slot_codec(ident: &syn::Ident, slots: &[CultCacheSlot]) -> proc_macro2::Token
                             }
                             index += 1;
                         }
-                        while let ::std::option::Option::Some(_) = seq.next_element::<::serde::de::IgnoredAny>()? {}
+                        // The slots past the declared ones are skipped and counted: the decode entry marks the record
+                        // that carried them read-only.
+                        let mut __extra = 0usize;
+                        while seq.next_element::<::serde::de::IgnoredAny>()?.is_some() {
+                            __extra += 1;
+                        }
+                        if __extra > 0 {
+                            ::cultcache_rs::__note_unread_slots(__ticket, stringify!(#ident), #max_slot + 1 + __extra, #max_slot + 1);
+                        }
                         Ok(#ident {
                             #(#build_fields),*
                         })
@@ -443,7 +445,8 @@ struct CultCacheSlot {
     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.
+    /// `#[cultcache(index)]` or `#[cultcache(index = "alias")]`: a unique lookup. Within one type no two records hold one
+    /// non-blank value of the alias; `get_by_index` finds the record by it.
     index: Option<String>,
 }
 
@@ -573,10 +576,13 @@ fn union_codec(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream> {
             quote! {
                 #key => {
                     match seq
-                        .next_element::<::std::option::Option<[(); 0]>>()
+                        .next_element::<::std::option::Option<::cultcache_rs::__UnitArmSlots>>()
                         .map_err(|_| ::serde::de::Error::custom(#arity_message))?
                     {
-                        ::std::option::Option::Some(::std::option::Option::Some(_)) => #ident::#variant,
+                        ::std::option::Option::Some(::std::option::Option::Some(slots)) => {
+                            slots.note(stringify!(#variant));
+                            #ident::#variant
+                        }
                         ::std::option::Option::Some(::std::option::Option::None) => {
                             return ::std::result::Result::Err(::serde::de::Error::custom(
                                 format!(#nil_slots_message, #key),
@@ -941,15 +947,15 @@ mod tests {
         );
         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}");
+        assert!(tokens.contains("(\"code\","), "{tokens}");
+        assert!(tokens.contains("(\"sku\","), "{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}");
+        assert!(!tokens.contains("fncult_name") && !tokens.contains("UNIQUE_INDEXES"), "{tokens}");
     }
 
     // ResolveIndexAlias: a blank alias is the member's name.
@@ -958,7 +964,7 @@ mod tests {
         let tokens = entry_tokens(
             r#"#[cultcache(type = "t")] struct S { #[cultcache(key = 0, index = "  ")] code: String }"#,
         );
-        assert!(tokens.contains("(\"code\",value)"), "{tokens}");
+        assert!(tokens.contains("(\"code\","), "{tokens}");
     }
 
     #[test]

packages/cultcache-rs/tests/common/mod.rs

@@ -0,0 +1,235 @@
+//! The union-parity vectors' types and constructed value, shared by the test files that walk them.
+#![allow(dead_code)]
+
+use std::path::PathBuf;
+
+use cultcache_rs::CultSlots;
+use cultcache_rs::CultUnion;
+use cultcache_rs::DatabaseEntry;
+
+
+#[derive(Clone, Debug, PartialEq, CultUnion)]
+pub enum Node {
+    #[cultcache(key = 0)]
+    Box(BoxArm),
+    #[cultcache(key = 1)]
+    Text(TextArm),
+    #[cultcache(key = 2)]
+    Use(UseArm),
+    #[cultcache(key = 5)]
+    Image(ImageArm),
+    #[cultcache(key = 6)]
+    Wrap(WrapArm),
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct WrapArm {
+    #[cultcache(key = 0)]
+    pub inner: Option<std::boxed::Box<Node>>,
+    #[cultcache(key = 1)]
+    pub id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct BoxArm {
+    #[cultcache(key = 0)]
+    pub id: String,
+    #[cultcache(key = 1)]
+    pub children: Vec<Node>,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct TextArm {
+    #[cultcache(key = 0)]
+    pub id: String,
+    #[cultcache(key = 1)]
+    pub content: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct UseArm {
+    #[cultcache(key = 0)]
+    pub id: String,
+    #[cultcache(key = 1)]
+    pub composition: Composition,
+    #[cultcache(key = 2)]
+    pub slots: Vec<Option<Node>>,
+}
+
+// Slot 2 is retired: a gap written nil.
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct ImageArm {
+    #[cultcache(key = 0)]
+    pub id: String,
+    #[cultcache(key = 1)]
+    pub uri: String,
+    #[cultcache(key = 3)]
+    pub alt: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct Composition {
+    #[cultcache(key = 0)]
+    pub name: String,
+    #[cultcache(key = 1)]
+    pub body: Option<std::boxed::Box<Node>>,
+}
+
+#[derive(Clone, Debug, PartialEq, CultUnion)]
+pub enum Outcome {
+    #[cultcache(key = 0)]
+    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)]
+pub enum UnitOutcome {
+    #[cultcache(key = 2)]
+    Denied,
+    #[cultcache(key = -2147483648)]
+    Floor,
+    #[cultcache(key = 2147483647)]
+    Ceiling,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct PendingArm {
+    #[cultcache(key = 0)]
+    pub message: String,
+    #[cultcache(key = 1)]
+    pub id: String,
+}
+
+// An arm with no members of its own: just its element id.
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct IdArm {
+    #[cultcache(key = 0)]
+    pub id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct CompletedArm {
+    #[cultcache(key = 0)]
+    pub source_version: i32,
+    #[cultcache(key = 1)]
+    pub id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct NamedArm {
+    #[cultcache(key = 0)]
+    pub name: String,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct UsesArm {
+    #[cultcache(key = 0)]
+    pub name: String,
+    #[cultcache(key = 1)]
+    pub uses: i32,
+}
+
+#[derive(Clone, Debug, PartialEq, CultSlots)]
+pub struct CountArm {
+    #[cultcache(key = 0)]
+    pub name: String,
+    #[cultcache(key = 1)]
+    pub count: i32,
+}
+
+#[derive(Clone, Debug, PartialEq, CultUnion)]
+pub enum Item {
+    #[cultcache(key = 0)]
+    Gem(NamedArm),
+    #[cultcache(key = 1)]
+    Tool(UsesArm),
+    #[cultcache(key = 2)]
+    Part(CountArm),
+}
+
+// The same arms as Item under its own keys: key 2 is unknown to it.
+#[derive(Clone, Debug, PartialEq, CultUnion)]
+pub enum CraftedItem {
+    #[cultcache(key = 0)]
+    Tool(UsesArm),
+    #[cultcache(key = 1)]
+    Part(CountArm),
+}
+
+#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
+#[cultcache(type = "tests.union_surface", schema = "tests.union_surface.v1")]
+pub struct UnionSurface {
+    #[cultcache(key = 0)]
+    pub id: String,
+    #[cultcache(key = 1)]
+    pub version: i32,
+    #[cultcache(key = 2)]
+    pub root: Option<Node>,
+    #[cultcache(key = 3)]
+    pub outcomes: Vec<Outcome>,
+    #[cultcache(key = 4)]
+    pub part: Option<Item>,
+    #[cultcache(key = 5)]
+    pub crafted: Option<CraftedItem>,
+    #[cultcache(key = 6)]
+    pub missing: Option<Node>,
+}
+
+pub fn text(id: &str, content: &str) -> Node {
+    Node::Text(TextArm { id: id.into(), content: content.into() })
+}
+
+pub fn image(id: &str, uri: &str, alt: &str) -> Node {
+    Node::Image(ImageArm { id: id.into(), uri: uri.into(), alt: alt.into() })
+}
+
+pub fn boxed(id: &str, children: Vec<Node>) -> Node {
+    Node::Box(BoxArm { id: id.into(), children })
+}
+
+pub fn constructed() -> UnionSurface {
+    let inner = boxed("0000000000d0", vec![text("0000000000d1", "x"), image("0000000000d2", "uri://a", "alt")]);
+    UnionSurface {
+        id: "surface".into(),
+        version: 3,
+        root: Some(boxed(
+            "0000000000c0",
+            vec![
+                text("0000000000c1", "hello"),
+                Node::Use(UseArm {
+                    id: "0000000000c2".into(),
+                    composition: Composition { name: "comp".into(), body: Some(std::boxed::Box::new(inner)) },
+                    slots: vec![Some(text("0000000000e1", "slot")), None, Some(boxed("0000000000e2", vec![]))],
+                }),
+                image("0000000000c3", "uri://b", ""),
+            ],
+        )),
+        outcomes: vec![
+            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 })),
+        missing: None,
+    }
+}
+
+pub fn id_arm(id: &str) -> IdArm {
+    IdArm { id: id.into() }
+}
+
+pub fn vector(name: &str) -> Vec<u8> {
+    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("../../tests/vectors/union-parity")
+        .join(name);
+    std::fs::read(&path).unwrap_or_else(|error| panic!("{}: {error}", path.display()))
+}

packages/cultcache-rs/tests/key_identity_vector.rs

@@ -0,0 +1,283 @@
+//! `tests/vectors/key-identity`, written only by the C# reference: a cache holds one record per key whatever its type, and a
+//! store holding a record no registered type claims loads, lists it as foreign and keeps its bytes
+//! (`variants:ruling:cache-refuses-retype`, `write-ownership-by-written-type`, `unheld-removal-refused-at-commit`).
+//! Every row is walked against this cache: each put row twice, once as `put` and once as a one-entry `put_prepared_batch`.
+
+use std::path::{Path, PathBuf};
+
+use cultcache_rs::{
+    CacheBackingStore, CultCache, DatabaseEntry, SchemaConflictError, SingleFileMessagePackBackingStore,
+};
+use serde_json::Value;
+
+// The ids C# writes in the store catalogs and on every record (the vector's README).
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "sha256:b20703a98f49c253898404ab50ba2c630720f0b8a5e1a41614d5650be22799fe", schema = "tests.ki_alpha")]
+struct Alpha {
+    #[cultcache(key = 0)]
+    text: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "sha256:dee4b727cf2ee04e61ab635ff0c5f3dca7345a411dc5f1018e583ab16009cf94", schema = "tests.ki_beta")]
+struct Beta {
+    #[cultcache(key = 0)]
+    text: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "sha256:fbc26e351e00c9e7185e8de171c7486aba707c229c949f0aae6b889288af5f6d", schema = "tests.ki_gamma")]
+struct Gamma {
+    #[cultcache(key = 0)]
+    text: String,
+}
+
+fn vectors() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../tests/vectors/key-identity")
+}
+
+/// `[refusal key or nil, held [type, key, text], file [key, schema name] or nil, foreign keys, kept foreign keys]`.
+type Expect = (Option<Vec<String>>, Vec<(String, String, String)>, Option<Vec<(String, String)>>, Vec<String>, Vec<String>);
+type Row = (String, Vec<String>, Vec<Vec<Value>>, Expect);
+
+fn text(value: &Value) -> &str {
+    value.as_str().unwrap()
+}
+
+fn register(cache: &mut CultCache, names: &[String]) {
+    for name in names {
+        match name.as_str() {
+            "alpha" => drop(cache.register_entry_type::<Alpha>().unwrap()),
+            "beta" => drop(cache.register_entry_type::<Beta>().unwrap()),
+            "gamma" => drop(cache.register_entry_type::<Gamma>().unwrap()),
+            other => panic!("unknown type {other}"),
+        }
+    }
+}
+
+fn short(entry_type: &str) -> &'static str {
+    match entry_type {
+        t if t == Alpha::TYPE => "alpha",
+        t if t == Beta::TYPE => "beta",
+        t if t == Gamma::TYPE => "gamma",
+        other => panic!("unknown entry type {other}"),
+    }
+}
+
+fn put(cache: &mut CultCache, as_batch: bool, kind: &str, key: &str, body: &str) -> anyhow::Result<()> {
+    macro_rules! write {
+        ($t:ident) => {{
+            let value = $t { text: body.to_string() };
+            if as_batch {
+                let (entry, _) = cache.prepare_entry(key, &value)?;
+                cache.put_prepared_batch(vec![entry])
+            } else {
+                cache.put(key, &value).map(drop)
+            }
+        }};
+    }
+    match kind {
+        "alpha" => write!(Alpha),
+        "beta" => write!(Beta),
+        "gamma" => write!(Gamma),
+        other => panic!("unknown type {other}"),
+    }
+}
+
+fn delete(cache: &mut CultCache, kind: &str, key: &str) -> anyhow::Result<bool> {
+    match kind {
+        "alpha" => cache.delete::<Alpha>(key),
+        "beta" => cache.delete::<Beta>(key),
+        "gamma" => cache.delete::<Gamma>(key),
+        other => panic!("unknown type {other}"),
+    }
+}
+
+fn open_cache(registered: &[String], path: Option<&Path>) -> anyhow::Result<CultCache> {
+    let mut cache = CultCache::new();
+    register(&mut cache, registered);
+    if let Some(path) = path {
+        cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path))?;
+        cache.pull_all_backing_stores()?;
+    }
+    Ok(cache)
+}
+
+/// The records a store file holds, read by a fresh store: (key, schema name, schema id, stored-at, payload).
+fn file_records(path: &Path) -> Vec<(String, String, Option<String>, String, Vec<u8>)> {
+    let mut records: Vec<_> = SingleFileMessagePackBackingStore::new(path)
+        .pull_all()
+        .unwrap()
+        .into_iter()
+        .map(|entry| (entry.key, entry.r#type, entry.schema_id, entry.stored_at, entry.payload))
+        .collect();
+    records.sort_by(|left, right| left.0.encode_utf16().cmp(right.0.encode_utf16()));
+    records
+}
+
+fn walk(row: &Row, as_batch: bool) -> Result<(), String> {
+    let (label, registered, ops, expect) = row;
+    let dir = tempfile::tempdir().unwrap();
+    let mut path: Option<PathBuf> = None;
+    let mut before = Vec::new();
+    let mut cache: Option<CultCache> = None;
+    let mut refused: Option<anyhow::Error> = None;
+    let mut refused_key: Option<String> = None;
+    let mut shared_key: Option<String> = None;
+    let mut wrote = false;
+    for (index, op) in ops.iter().enumerate() {
+        let last = index == ops.len() - 1;
+        let result: anyhow::Result<()> = match text(&op[0]) {
+            "open" => {
+                drop(cache.take());
+                match &op[1] {
+                    Value::String(file) if file == "memory" => open_cache(registered, None).map(|opened| cache = Some(opened)),
+                    file => {
+                        let fresh = dir.path().join("store.cc");
+                        if let Value::String(file) = file {
+                            std::fs::copy(vectors().join(file), &fresh).unwrap();
+                        }
+                        before = if fresh.exists() { file_records(&fresh) } else { Vec::new() };
+                        let opened = open_cache(registered, Some(&fresh));
+                        path = Some(fresh);
+                        opened.map(|opened| cache = Some(opened))
+                    }
+                }
+            }
+            "reopen" => {
+                drop(cache.take());
+                open_cache(registered, path.as_deref()).map(|opened| cache = Some(opened))
+            }
+            "attach" => {
+                let file = text(&op[1]);
+                let attached = dir.path().join(file);
+                std::fs::copy(vectors().join(file), &attached).unwrap();
+                let held: Vec<String> = cache.as_ref().unwrap().snapshot().into_iter().map(|entry| entry.key).collect();
+                let shared: Vec<String> = file_records(&attached).into_iter().map(|record| record.0).filter(|key| held.contains(key)).collect();
+                let home: Vec<String> = op[2].as_array().unwrap().iter().map(|name| short_to_type(text(name)).to_string()).collect();
+                let cache = cache.as_mut().unwrap();
+                let attach = cache
+                    .add_backing_store(SingleFileMessagePackBackingStore::new(&attached), home)
+                    .and_then(|()| cache.pull_all_backing_stores());
+                if attach.is_err() && last && shared.len() == 1 {
+                    refused_key = Some(shared[0].clone());
+                    shared_key = refused_key.clone();
+                    assert_eq!(std::fs::read(&attached).unwrap(), std::fs::read(vectors().join(file)).unwrap(), "{label}: a refused attach leaves the store as it was");
+                }
+                attach
+            }
+            "put" => {
+                wrote = true;
+                put(cache.as_mut().unwrap(), as_batch, text(&op[1]), text(&op[2]), text(&op[3]))
+            }
+            "delete" => delete(cache.as_mut().unwrap(), text(&op[1]), text(&op[2])).map(drop),
+            other => panic!("{label}: unknown op {other}"),
+        };
+        match result {
+            Ok(()) => {}
+            Err(error) if last => refused = Some(error),
+            Err(error) => return Err(format!("{label}: op {index} failed: {error:#}")),
+        }
+    }
+    if !wrote && as_batch {
+        return Ok(()); // not a write row: the batch variant is the same walk
+    }
+    let Some(cache) = cache.as_ref() else {
+        return Err(format!("{label} (batch {as_batch}): the cache did not open: {:#}", refused.unwrap()));
+    };
+    let last = ops.last().unwrap();
+    if let Some(error) = &refused {
+        if let Some(conflict) = error.downcast_ref::<SchemaConflictError>() {
+            refused_key = Some(conflict.record_key.clone());
+            let named = if text(&last[0]) == "attach" { shared_key.clone().unwrap() } else { text(&last[2]).to_string() };
+            assert_eq!(named, conflict.record_key, "{label}: the refusal names the key written, removed or shared");
+        }
+        let key = refused_key.clone().unwrap_or_default();
+        let message = format!("{error:#}");
+        let (all, delimited) = occurrences(&message, &key);
+        assert!(!key.is_empty() && delimited > 0, "{label}: the refusal names the key as a token: {message}");
+        if text(&last[0]) == "attach" {
+            assert_eq!(all, delimited, "{label}: the key occurs in the refusal only as a delimited token: {message}");
+        }
+    }
+    let mut held: Vec<(String, String, String)> = cache
+        .snapshot()
+        .into_iter()
+        .map(|entry| {
+            let body = match short(&entry.r#type) {
+                "alpha" => cache.get::<Alpha>(&entry.key).unwrap().unwrap().text,
+                "beta" => cache.get::<Beta>(&entry.key).unwrap().unwrap().text,
+                _ => cache.get::<Gamma>(&entry.key).unwrap().unwrap().text,
+            };
+            (short(&entry.r#type).to_string(), entry.key, body)
+        })
+        .collect();
+    held.sort_by(|a, b| (a.0.as_str(), a.1.encode_utf16().collect::<Vec<_>>()).cmp(&(b.0.as_str(), b.1.encode_utf16().collect::<Vec<_>>())));
+    let foreign: Vec<String> = cache.foreign_records().into_iter().map(|record| record.key).collect();
+    let (file, kept) = match &path {
+        None => (None, Vec::new()),
+        Some(path) => {
+            let after = file_records(path);
+            let kept = foreign
+                .iter()
+                .filter(|key| {
+                    let original = before.iter().find(|record| &record.0 == *key);
+                    let now = after.iter().find(|record| &record.0 == *key);
+                    original.is_some() && original.map(|r| (&r.2, &r.3, &r.4)) == now.map(|r| (&r.2, &r.3, &r.4))
+                })
+                .cloned()
+                .collect();
+            // This writer names a catalog entry by the record's type, which for these types is the id; C# names it by the
+            // schema name. Which type the record at a key is, is the verdict, so the id reads as its schema name.
+            let name = |described: String| match described.as_str() {
+                t if t == Alpha::TYPE => Alpha::SCHEMA_NAME.to_string(),
+                t if t == Beta::TYPE => Beta::SCHEMA_NAME.to_string(),
+                t if t == Gamma::TYPE => Gamma::SCHEMA_NAME.to_string(),
+                _ => described,
+            };
+            (Some(after.into_iter().map(|record| (record.0, name(record.1))).collect::<Vec<_>>()), kept)
+        }
+    };
+    let observed: Expect = (refused_key.map(|key| vec![key]), held, file, foreign, kept);
+    if &observed == expect { Ok(()) } else { Err(format!("{label} (batch {as_batch}): committed {expect:?} but this cache answers {observed:?}")) }
+}
+
+/// How often `key` occurs in `message`, and how often as a delimited token (not a piece of a longer word, schema name or id).
+fn occurrences(message: &str, key: &str) -> (usize, usize) {
+    let word = |c: Option<char>| c.is_some_and(|c| c.is_ascii_alphanumeric() || c == '_');
+    let found: Vec<usize> = message.match_indices(key).map(|(at, _)| at).collect();
+    let delimited = found
+        .iter()
+        .filter(|at| !word(message[..**at].chars().next_back()) && !word(message[**at + key.len()..].chars().next()))
+        .count();
+    (found.len(), delimited)
+}
+
+fn short_to_type(name: &str) -> &'static str {
+    match name {
+        "alpha" => Alpha::TYPE,
+        "beta" => Beta::TYPE,
+        "gamma" => Gamma::TYPE,
+        other => panic!("unknown type {other}"),
+    }
+}
+
+#[test]
+fn key_identity_rows_hold_their_verdicts() {
+    let bytes = std::fs::read(vectors().join("rows.msgpack")).unwrap();
+    let rows: Vec<Row> = rmp_serde::from_slice(&bytes).unwrap();
+    let mut walked = 0;
+    let mut failed = Vec::new();
+    for row in &rows {
+        let mut ok = true;
+        for as_batch in [false, true] {
+            if let Err(message) = walk(row, as_batch) {
+                failed.push(message);
+                ok = false;
+            }
+        }
+        walked += usize::from(ok);
+    }
+    assert!(failed.is_empty(), "{}", failed.join("\n"));
+    assert_eq!(walked, 12, "rows walked");
+}

packages/cultcache-rs/tests/lookups.rs

@@ -11,7 +11,7 @@ use cultcache_rs::{
 struct Item {
     #[cultcache(key = 0, name)]
     name: String,
-    #[cultcache(key = 1, index)]
+    #[cultcache(key = 1)]
     category: String,
     #[cultcache(key = 2, index = "sku")]
     code: Option<String>,
@@ -30,7 +30,7 @@ struct Gadget {
     #[cultcache(key = 0, name)]
     name: String,
     #[cultcache(key = 1, index)]
-    category: String,
+    serial: String,
 }
 
 /// Sorts after `Item` and has its exact shape: a lookup that ran past the end of its own type would answer from it.
@@ -39,7 +39,7 @@ struct Gadget {
 struct Zed {
     #[cultcache(key = 0, name)]
     name: String,
-    #[cultcache(key = 1, index)]
+    #[cultcache(key = 1)]
     category: String,
     #[cultcache(key = 2, index = "sku")]
     code: Option<String>,
@@ -48,7 +48,7 @@ struct Zed {
 }
 
 #[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
-#[cultcache(type = "settings", global)]
+#[cultcache(type = "settings", schema = "tests.settings", global)]
 struct Settings {
     #[cultcache(key = 0)]
     value: String,
@@ -71,7 +71,7 @@ struct Numbered {
     #[cultcache(key = 0, name)]
     id: u32,
     #[cultcache(key = 1, index)]
-    owner: u64,
+    badge: u64,
 }
 
 fn cache() -> CultCache {
@@ -110,7 +110,6 @@ fn a_record_is_found_by_name_and_by_index_after_a_reopen() {
     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));
 }
 
@@ -121,31 +120,32 @@ fn a_missing_name_or_value_is_none_and_an_unregistered_type_is_refused() {
 
     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>("sku", "other").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("nosuchalias", "a-1").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Item>("category", "cat").unwrap(), None, "category is a grouping, not an index");
     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_by_index::<Item>("sku", "a-1").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());
+    cache.put("numbered:1", &Numbered { id: 1, badge: 7 }).unwrap();
+    assert!(cache.get_by_index::<Numbered>("badge", "7").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();
+    cache.put("item:blank", &item("", "  ", Some("  "))).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);
+    assert_eq!(cache.get_by_index::<Item>("sku", "").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).
@@ -156,68 +156,41 @@ fn blank_and_nil_values_are_not_found() {
 #[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("item:a", &item("same", "same", Some("same"))).unwrap();
+    cache.put("gadget:a", &Gadget { name: "same".into(), serial: "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_eq!(cache.get_by_index::<Item>("sku", "same").unwrap(), None);
     assert!(cache.get_by_name::<Gadget>("same").unwrap().is_some());
-    assert!(cache.get_by_index::<Gadget>("category", "same").unwrap().is_some());
+    assert!(cache.get_by_index::<Gadget>("serial", "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();
+    cache.put("item:a", &item("old", "cat", Some("c1"))).unwrap();
+    cache.put("item:a", &item("new", "cat", Some("c2"))).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_eq!(cache.get_by_index::<Item>("sku", "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());
+    assert!(cache.get_by_index::<Item>("sku", "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);
+    assert_eq!(cache.get_by_index::<Item>("sku", "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();
+    let badge = 161_u64;
+    cache.put("numbered:1", &Numbered { id: 42, badge }).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);
+    assert!(cache.get_by_index::<Numbered>("badge", "161").unwrap().is_some());
 }
 
 #[test]
@@ -244,6 +217,71 @@ fn a_global_is_none_until_written_and_survives_a_reopen() {
     assert_eq!(reopened(&path).get_global::<Settings>().unwrap(), Some(settings("durable authority")));
 }
 
+/// `Settings` as an ordinary type: the same type id and schema, no global rule.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "settings", schema = "tests.settings")]
+struct LooseSettings {
+    #[cultcache(key = 0)]
+    value: String,
+}
+
+// Declaring a held type global judges the records it holds: two are already a second, so the registration is
+// refused and the type stays ordinary.
+#[test]
+fn registering_a_type_global_over_two_held_records_is_refused_and_changes_nothing() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<LooseSettings>().unwrap();
+    cache.put("a", &LooseSettings { value: "one".into() }).unwrap();
+    cache.put("b", &LooseSettings { value: "two".into() }).unwrap();
+
+    let refusal = cache.register_entry_type::<Settings>().unwrap_err();
+    assert!(refusal.downcast_ref::<CultCacheSecondGlobal>().is_some(), "{refusal:#}");
+
+    cache.put("c", &LooseSettings { value: "three".into() }).unwrap();
+    assert_eq!(cache.get_all_with_keys::<LooseSettings>().unwrap().len(), 3, "still ordinary");
+}
+
+// One held record may become the global; a second is then refused as a second global.
+#[test]
+fn registering_a_type_global_over_one_held_record_is_admitted() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<LooseSettings>().unwrap();
+    cache.put("a", &LooseSettings { value: "one".into() }).unwrap();
+    cache.register_entry_type::<Settings>().unwrap();
+    let refusal = cache.put("b", &Settings { value: "two".into() }).unwrap_err();
+    assert!(refusal.downcast_ref::<CultCacheSecondGlobal>().is_some(), "{refusal:#}");
+}
+
+/// A global with an indexed member, and the same type and schema declaring that member as an integer.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "indexed_global", schema = "tests.indexed_global", global)]
+struct IndexedGlobal {
+    #[cultcache(key = 0, index = "V")]
+    v: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "indexed_global", schema = "tests.indexed_global", global)]
+struct RetypedGlobal {
+    #[cultcache(key = 0, index = "V")]
+    v: i64,
+}
+
+// A refused re-registration over an already-global type leaves it global: the rule keeps refusing a second record.
+#[test]
+fn a_refused_reregistration_leaves_a_global_type_global() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<IndexedGlobal>().unwrap();
+    cache.put("a", &IndexedGlobal { v: "x".into() }).unwrap();
+
+    assert!(cache.register_entry_type::<RetypedGlobal>().is_err(), "the held text cannot be decoded as an integer");
+
+    let refusal = cache.put("b", &IndexedGlobal { v: "y".into() }).unwrap_err();
+    assert!(refusal.downcast_ref::<CultCacheSecondGlobal>().is_some(), "{refusal:#}");
+    assert_eq!(cache.get_global::<IndexedGlobal>().unwrap(), Some(IndexedGlobal { v: "x".into() }));
+    assert_eq!(cache.get_by_index::<IndexedGlobal>("V", "x").unwrap(), cache.get::<IndexedGlobal>("a").unwrap());
+}
+
 #[test]
 fn a_type_that_is_not_a_global_has_no_global() {
     let mut cache = cache();

packages/cultcache-rs/tests/slot_readonly.rs

@@ -0,0 +1,493 @@
+//! A record whose payload carries unread slots at any depth is read-only: the C# reference's union-parity vectors
+//! (README "Extra trailing slot" and "Slot stores") walked through the cache. This runtime has no compatible schema
+//! ids, so every mark is unconsented and no `explained` outcome can arise.
+
+mod common;
+
+use std::path::Path;
+
+use common::*;
+use cultcache_rs::CultCache;
+use cultcache_rs::CultCacheEnvelope;
+use cultcache_rs::DatabaseEntry;
+use cultcache_rs::SchemaConflictError;
+use cultcache_rs::SingleFileMessagePackBackingStore;
+use cultcache_rs::UnreadSlots;
+use cultcache_rs::decode_payload_marked;
+
+/// A row of `slot-outcomes.msgpack`: store, key, writable, explained, type, slots, declared, occurrences, flattenRefusedBy.
+type SlotRow = (String, String, bool, Option<bool>, Option<String>, Option<usize>, Option<usize>, Option<usize>, Option<String>);
+
+const SLOT_VALUE: &str = "extra-slot";
+
+/// `tests.slot_unit`, a document `[Name, Outcome: UnitOutcome]`.
+#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
+#[cultcache(type = "tests.slot_unit", schema = "tests.slot_unit.v1")]
+struct SlotUnit {
+    #[cultcache(key = 0)]
+    name: String,
+    #[cultcache(key = 1)]
+    outcome: UnitOutcome,
+}
+
+/// Two declared slots, the second defaulted: a payload of one slot is short, not marked.
+#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
+#[cultcache(type = "tests.shortened", schema = "tests.shortened.v1")]
+struct Shortened {
+    #[cultcache(key = 0)]
+    id: String,
+    #[cultcache(key = 1, default)]
+    note: String,
+}
+
+fn registered() -> CultCache {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<UnionSurface>().unwrap();
+    cache.register_entry_type::<SlotUnit>().unwrap();
+    cache
+}
+
+/// Any MessagePack value a store holds, enough to drop one record from a store and write the rest back.
+#[derive(serde::Serialize, serde::Deserialize)]
+#[serde(untagged)]
+enum Packed {
+    Nil(()),
+    Bool(bool),
+    Int(i64),
+    Text(String),
+    Bin(#[serde(with = "serde_bytes")] Vec<u8>),
+    Array(Vec<Packed>),
+}
+
+/// The committed store without its `marked-variant` record. A variant is a five-slot record, which this runtime's
+/// store reader refuses whole (`the_variant_row_...`), so the other rows are walked from a copy without it.
+fn without_variant_row(store: &[u8]) -> Vec<u8> {
+    let Packed::Array(mut parts) = rmp_serde::from_slice(store).unwrap() else { panic!("a store is an array") };
+    let Packed::Array(records) = parts.last_mut().unwrap() else { panic!("a store ends in its records") };
+    let before = records.len();
+    records.retain(|record| !matches!(record, Packed::Array(fields) if matches!(fields.first(), Some(Packed::Text(key)) if key == "marked-variant")));
+    assert_eq!(records.len(), before - 1);
+    rmp_serde::to_vec(&parts).unwrap()
+}
+
+/// A copy of a committed store, opened with both types registered; the vector itself is never written. The slot store
+/// is read without its variant row.
+fn open_copy(file: &str, dir: &Path) -> (CultCache, std::path::PathBuf) {
+    let path = dir.join(file);
+    let bytes = if file == "extra-slot-store.cc" { without_variant_row(&vector(file)) } else { vector(file) };
+    std::fs::write(&path, bytes).unwrap();
+    let mut cache = registered();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    cache.pull_all_backing_stores().unwrap();
+    (cache, path)
+}
+
+fn envelope(key: &str, payload: Vec<u8>) -> CultCacheEnvelope {
+    CultCacheEnvelope {
+        key: key.into(),
+        r#type: UnionSurface::TYPE.into(),
+        payload,
+        stored_at: "2026-01-01T00:00:00Z".into(),
+        schema_id: None,
+    }
+}
+
+fn conflict(error: &anyhow::Error) -> &SchemaConflictError {
+    error.downcast_ref::<SchemaConflictError>().unwrap_or_else(|| panic!("not a schema conflict: {error:#}"))
+}
+
+fn mark(type_name: &str, slot_count: usize, declared_count: usize, occurrences: usize) -> UnreadSlots {
+    UnreadSlots { type_name: type_name.into(), slot_count, declared_count, occurrences }
+}
+
+/// The marks the README table pins, by `detail`. The reference names an arm by its class; here an arm is the
+/// `...Arm` struct the union wraps.
+fn expected_mark(detail: &str) -> UnreadSlots {
+    match detail {
+        "record" | "depth" => mark("UnionSurface", 8, 7, 1),
+        "nested-record" => mark("Composition", 3, 2, 1),
+        "arm" => mark("BoxArm", 3, 2, 1),
+        "list-element" => mark("TextArm", 3, 2, 1),
+        other => panic!("unknown detail {other}"),
+    }
+}
+
+fn assert_refused_with(error: &anyhow::Error, key: &str, expected: &UnreadSlots) {
+    let refusal = conflict(error);
+    assert_eq!(refusal.unread_slots.as_ref(), Some(expected));
+    assert_eq!(refusal.record_key, key);
+    assert_eq!(refusal.schema_names.len(), 1);
+    let message = error.to_string();
+    assert!(message.contains(&expected.type_name), "{message}");
+    assert!(message.contains(&expected.slot_count.to_string()) && message.contains(&expected.declared_count.to_string()), "{message}");
+    assert!(!message.contains(SLOT_VALUE), "a refusal echoed the slot value: {message}");
+}
+
+#[test]
+fn every_read_only_vector_decodes_marked_and_is_not_writable() {
+    let rows: Vec<(String, String, String, Option<i64>, String)> = rmp_serde::from_slice(&vector("outcomes.msgpack")).unwrap();
+    assert_eq!(rows.len(), 9);
+    let bounds: Vec<serde_json::Value> = rmp_serde::from_slice(&vector("bounds-outcomes.msgpack")).unwrap();
+    let mut cases: Vec<(String, String)> = rows
+        .into_iter()
+        .filter(|(_, outcome, ..)| outcome == "read-only")
+        .map(|(file, _, _, _, detail)| (file, detail))
+        .collect();
+    for entry in &bounds[1..] {
+        let fields: Vec<&str> = entry.as_array().unwrap().iter().filter_map(|field| field.as_str()).collect();
+        if fields[1] == "read-only" {
+            cases.push((fields[0].to_string(), fields[3].to_string()));
+        }
+    }
+    assert_eq!(cases.len(), 5);
+    for (file, detail) in cases {
+        let payload = vector(&file);
+        let (value, found) = decode_payload_marked::<UnionSurface>(&payload).unwrap_or_else(|error| panic!("{file}: {error:#}"));
+        assert_eq!(value, constructed(), "{file}");
+        assert_eq!(found, Some(expected_mark(&detail)), "{file}");
+
+        let mut cache = registered();
+        let dir = tempfile::tempdir().unwrap();
+        cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(dir.path().join("s.cc"))).unwrap();
+        cache.put_raw_envelope(envelope("k", payload.clone())).unwrap();
+        assert_eq!(cache.get::<UnionSurface>("k").unwrap(), Some(constructed()), "{file}");
+        assert!(!cache.is_writable(UnionSurface::TYPE, "k").unwrap(), "{file}");
+        assert!(cache.is_writable(UnionSurface::TYPE, "unheld").unwrap(), "{file}");
+        let error = cache.put("k", &constructed()).unwrap_err();
+        assert_refused_with(&error, "k", &expected_mark(&detail));
+    }
+}
+
+#[test]
+fn clean_and_short_payloads_are_writable_and_unmarked() {
+    let (value, found) = decode_payload_marked::<UnionSurface>(&vector("union-surface.msgpack")).unwrap();
+    assert_eq!((value, found), (constructed(), None));
+    // A payload short of its declared slots keeps its defaults and does not mark.
+    let (value, found) = decode_payload_marked::<Shortened>(&rmp_serde::to_vec(&("only",)).unwrap()).unwrap();
+    assert_eq!((value.id.as_str(), value.note.as_str(), found), ("only", "", None));
+}
+
+#[test]
+fn a_payload_past_the_nesting_limit_is_refused_never_marked() {
+    for file in ["depth-skipped-past-limit.msgpack", "depth-past-limit.msgpack"] {
+        let error = decode_payload_marked::<UnionSurface>(&vector(file)).unwrap_err();
+        assert!(error.to_string().contains("the limit is 256"), "{file}: {error:#}");
+    }
+}
+
+#[test]
+fn a_plain_serde_decode_marks_nothing_and_does_not_leak_a_scope() {
+    // No scope is open: the visitors note into nothing.
+    let value: UnionSurface = rmp_serde::from_slice(&vector("extra-slot-record.msgpack")).unwrap();
+    assert_eq!(value, constructed());
+    // A marked decode followed by a clean one: the first mark does not survive into the second.
+    assert!(decode_payload_marked::<UnionSurface>(&vector("extra-slot-record.msgpack")).unwrap().1.is_some());
+    assert_eq!(decode_payload_marked::<UnionSurface>(&vector("union-surface.msgpack")).unwrap().1, None);
+}
+
+#[test]
+fn the_slot_store_rows_walk_through_the_cache() {
+    let rows: Vec<SlotRow> =
+        rmp_serde::from_slice(&vector("slot-outcomes.msgpack")).unwrap();
+    assert_eq!(rows.len(), 8);
+    let dir = tempfile::tempdir().unwrap();
+    let mut walked = 0;
+    for (store, key, writable, _explained, type_name, slots, declared, occurrences, flatten_refused_by) in rows {
+        // The variant row is a record this runtime cannot hold: see the variant test. The consent store's `writable` and
+        // `explained` answer the compatible-id declaration, which this runtime has none of; its marks are walked below.
+        if flatten_refused_by.is_some() || store == "extra-slot-consent.cc" {
+            continue;
+        }
+        let case = dir.path().join(&key);
+        std::fs::create_dir_all(&case).unwrap();
+        let (mut cache, _) = open_copy(&store, &case);
+        let type_id = if key == "unit-arm" { SlotUnit::TYPE } else { UnionSurface::TYPE };
+        assert_eq!(cache.is_writable(type_id, &key).unwrap(), writable, "{store} {key}");
+        let removal = if key == "unit-arm" { cache.delete::<SlotUnit>(&key) } else { cache.delete::<UnionSurface>(&key) };
+        match writable {
+            true => assert!(removal.unwrap()),
+            false => {
+                let found = conflict(&removal.unwrap_err()).unread_slots.clone().unwrap();
+                // The reference names the unit arm's class, Denied2; here the variant.
+                let expected_type = match type_name.as_deref().unwrap() {
+                    "Denied2" => "Denied",
+                    other => other,
+                };
+                assert_eq!((found.type_name.as_str(), Some(found.slot_count), Some(found.declared_count), Some(found.occurrences)), (expected_type, slots, declared, occurrences));
+                assert!(cache.snapshot_envelopes().iter().any(|held| held.key == key), "a refused removal removed {key}");
+            }
+        }
+        walked += 1;
+    }
+    assert_eq!(walked, 3);
+}
+
+#[test]
+fn the_consent_store_marks_are_unconsented_here() {
+    let rows: Vec<SlotRow> =
+        rmp_serde::from_slice(&vector("slot-outcomes.msgpack")).unwrap();
+    let dir = tempfile::tempdir().unwrap();
+    let mut found = 0;
+    for (store, key, _writable, _explained, _type_name, slots, declared, occurrences, _) in rows {
+        if store != "extra-slot-consent.cc" {
+            continue;
+        }
+        let (cache, _) = open_copy(&store, dir.path());
+        let held = cache.snapshot_envelopes().into_iter().find(|held| held.key == key).unwrap();
+        let (_, mark) = decode_payload_marked::<UnionSurface>(&held.payload).unwrap();
+        match slots {
+            // The reference's `consented` row is writable there (a listed compatible id covers it); here every mark refuses.
+            None => assert_eq!(mark, None, "{key}"),
+            Some(slots) => {
+                let mark = mark.unwrap_or_else(|| panic!("{key} carried no mark"));
+                // The first type read is the document, whose reference name is SurfaceDeclaring.
+                assert_eq!(mark.type_name, "UnionSurface", "{key}");
+                assert_eq!((Some(mark.slot_count), Some(mark.declared_count), Some(mark.occurrences)), (Some(slots), declared, occurrences), "{key}");
+                assert!(!cache.is_writable(UnionSurface::TYPE, &key).unwrap(), "{key}");
+            }
+        }
+        found += 1;
+    }
+    assert_eq!(found, 4);
+}
+
+#[test]
+fn every_write_entry_refuses_a_marked_key_before_any_store_is_touched() {
+    let dir = tempfile::tempdir().unwrap();
+    let (mut cache, path) = open_copy("extra-slot-store.cc", dir.path());
+    let expected = mark("Composition", 3, 2, 1);
+    let before = std::fs::read(&path).unwrap();
+    let held = cache.snapshot_envelopes().into_iter().find(|held| held.key == "marked").unwrap();
+    let clean = cache.snapshot_envelopes().into_iter().find(|held| held.key == "clean").unwrap();
+    assert!(!cache.is_writable(UnionSurface::TYPE, "marked").unwrap());
+    assert!(cache.is_writable(UnionSurface::TYPE, "clean").unwrap());
+
+    let replacing = envelope("marked", rmp_serde::to_vec(&constructed()).unwrap());
+    assert_refused_with(&cache.put("marked", &constructed()).unwrap_err(), "marked", &expected);
+    assert_refused_with(&cache.put_envelope::<UnionSurface>(replacing.clone()).unwrap_err(), "marked", &expected);
+    assert_refused_with(&cache.put_raw_envelope(replacing.clone()).unwrap_err(), "marked", &expected);
+    assert_refused_with(&cache.put_prepared_batch(vec![replacing]).unwrap_err(), "marked", &expected);
+    assert_refused_with(&cache.delete::<UnionSurface>("marked").unwrap_err(), "marked", &expected);
+    assert_refused_with(
+        &cache.update::<UnionSurface, _>("marked", |current| current.unwrap()).unwrap_err(),
+        "marked",
+        &expected,
+    );
+
+    // A batch with a marked key refuses whole: its clean member is not written either.
+    let mut rewritten = clean.clone();
+    rewritten.payload = rmp_serde::to_vec(&UnionSurface { version: 9, ..constructed() }).unwrap();
+    let batch = vec![rewritten, envelope("marked", rmp_serde::to_vec(&constructed()).unwrap())];
+    assert_refused_with(&cache.put_prepared_batch(batch).unwrap_err(), "marked", &expected);
+
+    assert_eq!(std::fs::read(&path).unwrap(), before, "a refused write touched the store");
+    assert_eq!(cache.snapshot_envelopes().into_iter().find(|entry| entry.key == "marked").unwrap(), held);
+    assert_eq!(cache.snapshot_envelopes().into_iter().find(|entry| entry.key == "clean").unwrap(), clean);
+
+    // A write to another key succeeds, and the marked record's bytes, schema id and stored-at are carried unchanged.
+    cache.put("clean", &UnionSurface { version: 9, ..constructed() }).unwrap();
+    cache.put("other", &constructed()).unwrap();
+    assert!(cache.delete::<UnionSurface>("other").unwrap());
+    let mut reopened = registered();
+    reopened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    reopened.pull_all_backing_stores().unwrap();
+    let carried = reopened.snapshot_envelopes().into_iter().find(|entry| entry.key == "marked").unwrap();
+    assert_eq!(carried, held);
+    assert_eq!(carried.payload, vector("extra-slot-nested-record.msgpack"));
+    assert_eq!(reopened.get::<UnionSurface>("clean").unwrap().unwrap().version, 9);
+}
+
+#[test]
+fn a_unit_arm_with_slots_decodes_as_the_unit_arm_and_marks() {
+    let (document, found) = decode_payload_marked::<SlotUnit>(&unit_arm_payload()).unwrap();
+    assert_eq!(document, SlotUnit { name: "unit-arm".into(), outcome: UnitOutcome::Denied });
+    assert_eq!(found, Some(mark("Denied", 1, 0, 1)));
+
+    let dir = tempfile::tempdir().unwrap();
+    let (mut cache, _) = open_copy("extra-slot-store.cc", dir.path());
+    assert_eq!(cache.get::<SlotUnit>("unit-arm").unwrap(), Some(document.clone()));
+    assert!(!cache.is_writable(SlotUnit::TYPE, "unit-arm").unwrap());
+    let error = cache.put("unit-arm", &document).unwrap_err();
+    assert_refused_with(&error, "unit-arm", &mark("Denied", 1, 0, 1));
+    assert_refused_with(&cache.delete::<SlotUnit>("unit-arm").unwrap_err(), "unit-arm", &mark("Denied", 1, 0, 1));
+
+    // Several elements are still one marked object, and a clean unit arm is unmarked.
+    let (_, found) = decode_payload_marked::<UnitOutcome>(&rmp_serde::to_vec(&(2u64, ("a", "b", "c"))).unwrap()).unwrap();
+    assert_eq!(found, Some(mark("Denied", 3, 0, 1)));
+    let (_, found) = decode_payload_marked::<UnitOutcome>(&vector("unit-arm-denied.msgpack")).unwrap();
+    assert_eq!(found, None);
+}
+
+fn unit_arm_payload() -> Vec<u8> {
+    let dir = tempfile::tempdir().unwrap();
+    let (cache, _) = open_copy("extra-slot-store.cc", dir.path());
+    cache.snapshot_envelopes().into_iter().find(|held| held.key == "unit-arm").unwrap().payload
+}
+
+#[test]
+fn the_variant_row_of_the_slot_store_is_refused_whole_by_the_store_reader() {
+    // `marked-variant` is a five-slot record (a variant): this runtime holds no variants, and its v1 snapshot reader
+    // refuses such a record, so the store as written cannot load here and the other rows are walked without it.
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("extra-slot-store.cc");
+    std::fs::write(&path, vector("extra-slot-store.cc")).unwrap();
+    let mut cache = registered();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    let error = cache.pull_all_backing_stores().unwrap_err();
+    assert!(format!("{error:#}").contains("is not decodable"), "{error:#}");
+}
+
+fn slot_unit_envelope(key: &str, payload: Vec<u8>) -> CultCacheEnvelope {
+    CultCacheEnvelope { r#type: SlotUnit::TYPE.into(), ..envelope(key, payload) }
+}
+
+#[test]
+fn a_held_payload_the_type_cannot_read_is_read_only_and_refused_by_name() {
+    let mut cache = registered();
+    // A newer writer's record: an arm this build lacks and an extra root slot. get cannot read it, and it is the data
+    // read-only exists to protect.
+    let newer = rmp_serde::to_vec(&("CANARY-name", (99u64, ("x",)), "CANARY-extra")).unwrap();
+    cache.put_raw_envelope(slot_unit_envelope("n", newer)).unwrap();
+    assert!(cache.get::<SlotUnit>("n").is_err());
+    assert!(!cache.is_writable(SlotUnit::TYPE, "n").unwrap());
+    let replacement = SlotUnit { name: "n".into(), outcome: UnitOutcome::Denied };
+    let held = cache.snapshot_envelopes();
+    for error in [
+        cache.put("n", &replacement).unwrap_err(),
+        cache.put_raw_envelope(slot_unit_envelope("n", rmp_serde::to_vec(&replacement).unwrap())).unwrap_err(),
+        cache.delete::<SlotUnit>("n").unwrap_err(),
+    ] {
+        let message = format!("{error:#}");
+        assert!(message.contains("\"n\"") && message.contains("tests.slot_unit") && message.contains("read-only"), "{message}");
+        assert!(!message.contains("CANARY"), "{message}");
+    }
+    assert_eq!(cache.snapshot_envelopes(), held);
+}
+
+#[test]
+fn a_corrupt_held_payload_is_refused_naming_the_key_never_its_bytes() {
+    let mut cache = registered();
+    cache.put_raw_envelope(envelope("broken", rmp_serde::to_vec(&("CANARY-id", "CANARY-version")).unwrap())).unwrap();
+    assert!(!cache.is_writable(UnionSurface::TYPE, "broken").unwrap());
+    let error = cache.delete::<UnionSurface>("broken").unwrap_err();
+    let message = format!("{error:#}");
+    assert!(message.contains("\"broken\"") && message.contains("backup") && message.contains("store"), "{message}");
+    assert!(!message.contains("build that wrote it"), "{message}");
+    assert!(!message.contains("CANARY"), "{message}");
+    assert!(cache.is_writable("tests.unregistered", "broken").is_err());
+}
+
+fn held_marked_and_clean() -> (CultCache, tempfile::TempDir, std::path::PathBuf) {
+    let dir = tempfile::tempdir().unwrap();
+    let (cache, path) = open_copy("extra-slot-store.cc", dir.path());
+    (cache, dir, path)
+}
+
+#[test]
+fn load_soa_does_not_replace_or_drop_a_marked_record() {
+    use cultcache_rs::CultCacheSoaTable;
+    let (mut cache, _dir, path) = held_marked_and_clean();
+    let all = cache.snapshot_envelopes();
+    let held = all.iter().find(|held| held.key == "marked").unwrap().clone();
+    let without: Vec<_> = all.iter().filter(|held| held.key != "marked").cloned().collect();
+    let mut replaced = all.clone();
+    replaced.iter_mut().find(|held| held.key == "marked").unwrap().payload = rmp_serde::to_vec(&constructed()).unwrap();
+    for table in [without, replaced] {
+        let error = cache.load_soa(CultCacheSoaTable::from_envelopes(table)).unwrap_err();
+        assert_refused_with(&error, "marked", &mark("Composition", 3, 2, 1));
+        assert_eq!(cache.snapshot_envelopes(), all, "a refused load changed the image");
+    }
+    // The same record carried unchanged, with another key added, loads.
+    let mut kept = all.clone();
+    kept.push(envelope("added", rmp_serde::to_vec(&constructed()).unwrap()));
+    cache.load_soa(CultCacheSoaTable::from_envelopes(kept)).unwrap();
+    assert_eq!(cache.snapshot_envelopes().iter().find(|held| held.key == "marked"), Some(&held));
+    // A clean record may be dropped by a load.
+    let no_clean: Vec<_> = cache.snapshot_envelopes().into_iter().filter(|held| held.key != "clean").collect();
+    cache.load_soa(CultCacheSoaTable::from_envelopes(no_clean)).unwrap();
+    // The marked record is still on disk after the next batch.
+    let rewrite = envelope("added", rmp_serde::to_vec(&UnionSurface { version: 5, ..constructed() }).unwrap());
+    cache.put_prepared_batch(vec![rewrite]).unwrap();
+    let mut reopened = registered();
+    reopened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    reopened.pull_all_backing_stores().unwrap();
+    assert_eq!(reopened.snapshot_envelopes().iter().find(|held| held.key == "marked"), Some(&held));
+}
+
+#[test]
+fn is_writable_agrees_with_the_writes_for_foreign_keys_and_other_types() {
+    let dir = tempfile::tempdir().unwrap();
+    // Only UnionSurface registered: the store's unit-arm record is foreign here.
+    let path = dir.path().join("extra-slot-store.cc");
+    std::fs::write(&path, without_variant_row(&vector("extra-slot-store.cc"))).unwrap();
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<UnionSurface>().unwrap();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    cache.pull_all_backing_stores().unwrap();
+    assert!(cache.put("unit-arm", &constructed()).is_err());
+    assert!(!cache.is_writable(UnionSurface::TYPE, "unit-arm").unwrap());
+    assert!(cache.is_writable(UnionSurface::TYPE, "unheld").unwrap());
+
+    // Another registered type at a key a record of this one holds.
+    let (mut cache, _dir, _) = held_marked_and_clean();
+    let other = SlotUnit { name: "clean".into(), outcome: UnitOutcome::Denied };
+    assert!(cache.put("clean", &other).is_err());
+    assert!(!cache.is_writable(SlotUnit::TYPE, "clean").unwrap());
+    assert!(!cache.is_writable(SlotUnit::TYPE, "marked").unwrap());
+    assert!(cache.is_writable(UnionSurface::TYPE, "clean").unwrap());
+}
+
+#[test]
+fn a_marked_key_refuses_a_batch_wherever_it_sits() {
+    let (mut cache, _dir, path) = held_marked_and_clean();
+    let before = std::fs::read(&path).unwrap();
+    let marked = envelope("marked", rmp_serde::to_vec(&constructed()).unwrap());
+    let clean = |key: &str| envelope(key, rmp_serde::to_vec(&constructed()).unwrap());
+    for batch in [
+        vec![marked.clone(), clean("a"), clean("b")],
+        vec![clean("a"), marked.clone(), clean("b")],
+        vec![clean("a"), clean("b"), marked.clone()],
+    ] {
+        let error = cache.put_prepared_batch(batch).unwrap_err();
+        assert_refused_with(&error, "marked", &mark("Composition", 3, 2, 1));
+        assert_eq!(std::fs::read(&path).unwrap(), before);
+        assert!(cache.snapshot_envelopes().iter().all(|held| held.key != "a" && held.key != "b"));
+    }
+}
+
+#[test]
+fn a_marked_decode_leaves_no_scope_open() {
+    assert_eq!(cultcache_rs::__enter_slots(), 0);
+    decode_payload_marked::<UnionSurface>(&vector("extra-slot-record.msgpack")).unwrap();
+    assert_eq!(cultcache_rs::__enter_slots(), 0, "a marked decode left its scope open on this thread");
+    let _ = decode_payload_marked::<UnionSurface>(&vector("depth-skipped-past-limit.msgpack"));
+    assert_eq!(cultcache_rs::__enter_slots(), 0);
+}
+
+#[test]
+fn is_writable_is_false_for_a_type_with_no_home_store() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut cache = registered();
+    // One store, routed to SlotUnit only: UnionSurface has no home.
+    cache.add_backing_store(SingleFileMessagePackBackingStore::new(dir.path().join("s.cc")), [SlotUnit::TYPE]).unwrap();
+    assert!(cache.put("k", &constructed()).is_err());
+    assert!(!cache.is_writable(UnionSurface::TYPE, "k").unwrap());
+    assert!(cache.is_writable(SlotUnit::TYPE, "k").unwrap());
+}
+
+#[test]
+fn load_soa_refuses_a_same_length_replacement_of_a_marked_record() {
+    use cultcache_rs::CultCacheSoaTable;
+    let (mut cache, _dir, _) = held_marked_and_clean();
+    let all = cache.snapshot_envelopes();
+    let marked = all.iter().find(|held| held.key == "marked").unwrap();
+    // The clean record's bytes padded to the marked record's length: same length, different bytes.
+    let mut same_length = vec![0xc0; marked.payload.len()];
+    same_length[..2].copy_from_slice(&[0x91, 0xa1]);
+    assert_eq!(same_length.len(), marked.payload.len());
+    let mut replaced = all.clone();
+    replaced.iter_mut().find(|held| held.key == "marked").unwrap().payload = same_length;
+    let error = cache.load_soa(CultCacheSoaTable::from_envelopes(replaced)).unwrap_err();
+    assert_refused_with(&error, "marked", &mark("Composition", 3, 2, 1));
+    assert_eq!(cache.snapshot_envelopes(), all);
+}

packages/cultcache-rs/tests/union_parity.rs

@@ -1,244 +1,17 @@
 //! The Rust runtime held to tests/vectors/union-parity, written by the C# reference.
 //! Bytes and outcomes are read from the committed files; only the constructed value is spelled here.
 
-use std::path::PathBuf;
-
 use cultcache_rs::CultCache;
 use cultcache_rs::CacheBackingStore;
 use cultcache_rs::CultCacheEnvelope;
 use cultcache_rs::MAX_PAYLOAD_DEPTH;
 use cultcache_rs::PayloadTooDeep;
 use cultcache_rs::check_payload_depth;
-use cultcache_rs::CultSlots;
-use cultcache_rs::CultUnion;
 use cultcache_rs::DatabaseEntry;
 use cultcache_rs::SingleFileMessagePackBackingStore;
 
-#[derive(Clone, Debug, PartialEq, CultUnion)]
-enum Node {
-    #[cultcache(key = 0)]
-    Box(BoxArm),
-    #[cultcache(key = 1)]
-    Text(TextArm),
-    #[cultcache(key = 2)]
-    Use(UseArm),
-    #[cultcache(key = 5)]
-    Image(ImageArm),
-    #[cultcache(key = 6)]
-    Wrap(WrapArm),
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct WrapArm {
-    #[cultcache(key = 0)]
-    inner: Option<std::boxed::Box<Node>>,
-    #[cultcache(key = 1)]
-    id: String,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct BoxArm {
-    #[cultcache(key = 0)]
-    id: String,
-    #[cultcache(key = 1)]
-    children: Vec<Node>,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct TextArm {
-    #[cultcache(key = 0)]
-    id: String,
-    #[cultcache(key = 1)]
-    content: String,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct UseArm {
-    #[cultcache(key = 0)]
-    id: String,
-    #[cultcache(key = 1)]
-    composition: Composition,
-    #[cultcache(key = 2)]
-    slots: Vec<Option<Node>>,
-}
-
-// Slot 2 is retired: a gap written nil.
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct ImageArm {
-    #[cultcache(key = 0)]
-    id: String,
-    #[cultcache(key = 1)]
-    uri: String,
-    #[cultcache(key = 3)]
-    alt: String,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct Composition {
-    #[cultcache(key = 0)]
-    name: String,
-    #[cultcache(key = 1)]
-    body: Option<std::boxed::Box<Node>>,
-}
-
-#[derive(Clone, Debug, PartialEq, CultUnion)]
-enum Outcome {
-    #[cultcache(key = 0)]
-    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)]
-    Floor,
-    #[cultcache(key = 2147483647)]
-    Ceiling,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-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)]
-struct NamedArm {
-    #[cultcache(key = 0)]
-    name: String,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct UsesArm {
-    #[cultcache(key = 0)]
-    name: String,
-    #[cultcache(key = 1)]
-    uses: i32,
-}
-
-#[derive(Clone, Debug, PartialEq, CultSlots)]
-struct CountArm {
-    #[cultcache(key = 0)]
-    name: String,
-    #[cultcache(key = 1)]
-    count: i32,
-}
-
-#[derive(Clone, Debug, PartialEq, CultUnion)]
-enum Item {
-    #[cultcache(key = 0)]
-    Gem(NamedArm),
-    #[cultcache(key = 1)]
-    Tool(UsesArm),
-    #[cultcache(key = 2)]
-    Part(CountArm),
-}
-
-// The same arms as Item under its own keys: key 2 is unknown to it.
-#[derive(Clone, Debug, PartialEq, CultUnion)]
-enum CraftedItem {
-    #[cultcache(key = 0)]
-    Tool(UsesArm),
-    #[cultcache(key = 1)]
-    Part(CountArm),
-}
-
-#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
-#[cultcache(type = "tests.union_surface", schema = "tests.union_surface.v1")]
-struct UnionSurface {
-    #[cultcache(key = 0)]
-    id: String,
-    #[cultcache(key = 1)]
-    version: i32,
-    #[cultcache(key = 2)]
-    root: Option<Node>,
-    #[cultcache(key = 3)]
-    outcomes: Vec<Outcome>,
-    #[cultcache(key = 4)]
-    part: Option<Item>,
-    #[cultcache(key = 5)]
-    crafted: Option<CraftedItem>,
-    #[cultcache(key = 6)]
-    missing: Option<Node>,
-}
-
-fn text(id: &str, content: &str) -> Node {
-    Node::Text(TextArm { id: id.into(), content: content.into() })
-}
-
-fn image(id: &str, uri: &str, alt: &str) -> Node {
-    Node::Image(ImageArm { id: id.into(), uri: uri.into(), alt: alt.into() })
-}
-
-fn boxed(id: &str, children: Vec<Node>) -> Node {
-    Node::Box(BoxArm { id: id.into(), children })
-}
-
-fn constructed() -> UnionSurface {
-    let inner = boxed("0000000000d0", vec![text("0000000000d1", "x"), image("0000000000d2", "uri://a", "alt")]);
-    UnionSurface {
-        id: "surface".into(),
-        version: 3,
-        root: Some(boxed(
-            "0000000000c0",
-            vec![
-                text("0000000000c1", "hello"),
-                Node::Use(UseArm {
-                    id: "0000000000c2".into(),
-                    composition: Composition { name: "comp".into(), body: Some(std::boxed::Box::new(inner)) },
-                    slots: vec![Some(text("0000000000e1", "slot")), None, Some(boxed("0000000000e2", vec![]))],
-                }),
-                image("0000000000c3", "uri://b", ""),
-            ],
-        )),
-        outcomes: vec![
-            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 })),
-        missing: None,
-    }
-}
-
-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")
-        .join(name);
-    std::fs::read(&path).unwrap_or_else(|error| panic!("{}: {error}", path.display()))
-}
+mod common;
+use common::*;
 
 fn decode(bytes: &[u8]) -> Result<UnionSurface, String> {
     rmp_serde::from_slice(bytes).map_err(|error| error.to_string())
@@ -325,11 +98,10 @@ fn an_unknown_arm_lists_the_declared_keys_and_never_echoes_the_payload() {
 
 #[test]
 fn a_union_that_is_not_a_key_and_slots_pair_is_refused_naming_the_enum() {
-    let cases: [(&str, Vec<u8>); 4] = [
+    let cases: [(&str, Vec<u8>); 3] = [
         ("an empty array", vec![0x90]),
         ("a trailing element", rmp_serde::to_vec(&(1u64, (7u8,), 0u8)).unwrap()),
         ("a string key", rmp_serde::to_vec(&("CANARY-key", (7u8,))).unwrap()),
-        ("a unit arm with slots", rmp_serde::to_vec(&(2u64, ("CANARY-slot",))).unwrap()),
     ];
     for (label, bytes) in cases {
         let message = rmp_serde::from_slice::<UnitOutcome>(&bytes).unwrap_err().to_string();

packages/cultcache-rs/tests/unique_index.rs

@@ -0,0 +1,775 @@
+//! `#[cultcache(index)]` is unique (`variants:ruling:unique-indexes`; C# `RefuseIndexSharing`): within one type and one
+//! alias no two records hold one non-blank value, judged on the result of each admission, on every write path and every
+//! load. The refusal text is informational; the contract is the verdict, so most pins assert the verdict and the
+//! shared vectors in `tests/vectors/unique-index` pin the text and the canonical index text.
+
+use std::path::{Path, PathBuf};
+
+use cultcache_rs::{
+    CultCache, CultCacheEnvelope, CultCacheSoaTable, DatabaseEntry, SingleFileMessagePackBackingStore,
+};
+use serde::Deserialize;
+
+/// The vectors' `tests.unique_item`: Sku is unique, Category a grouping.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "unique_item", schema = "tests.unique_item")]
+struct Unique {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+    #[cultcache(key = 1)]
+    category: String,
+}
+
+/// The same type with no index: a role, which writes the duplicates `Unique` refuses.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "unique_item", schema = "tests.unique_item")]
+struct Twin {
+    #[cultcache(key = 0)]
+    sku: String,
+    #[cultcache(key = 1)]
+    category: String,
+}
+
+/// Two unique indexes declared out of alphabetical order, so no ordering is an accident of declaration.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "multi", schema = "Multi")]
+struct Multi {
+    #[cultcache(key = 0, index = "B")]
+    b: Option<String>,
+    #[cultcache(key = 1, index = "A")]
+    a: Option<String>,
+}
+
+/// Another type sharing the alias `Sku`: types never conflict.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "other", schema = "Other")]
+struct Other {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "plain", schema = "Plain")]
+struct Plain {
+    #[cultcache(key = 0)]
+    value: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "vs", schema = "VS")]
+struct VString {
+    #[cultcache(key = 0, index = "V")]
+    v: String,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "vi", schema = "VI")]
+struct VInt {
+    #[cultcache(key = 0, index = "V")]
+    v: i64,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "vu", schema = "VU")]
+struct VUint {
+    #[cultcache(key = 0, index = "V")]
+    v: u64,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "vb", schema = "VB")]
+struct VBool {
+    #[cultcache(key = 0, index = "V")]
+    v: bool,
+}
+
+/// The refusals vector's other schemas: `Sku` is unique in each; `Alt` is a second unique index in `uq_pair` (alias
+/// `Alt`) and `uq_alias` (alias `alt`, sorting after `Sku` only under an ordinal compare); alpha and beta are plain.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "uq_pair", schema = "tests.uq_pair")]
+struct UqPair {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+    #[cultcache(key = 1, index = "Alt")]
+    alt: String,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "uq_alias", schema = "tests.uq_alias")]
+struct UqAlias {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+    #[cultcache(key = 1, index = "alt")]
+    alt: String,
+}
+/// Aliases U+FF21 and U+10400: UTF-16 puts the astral alias first (D801 DC00 < FF21), code-point order the other way.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "uq_wide", schema = "tests.uq_wide")]
+struct UqWide {
+    #[cultcache(key = 0, index = "\u{FF21}")]
+    sku: String,
+    #[cultcache(key = 1, index = "\u{10400}")]
+    alt: String,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "uq_alpha", schema = "tests.uq_alpha")]
+struct UqAlpha {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+    #[cultcache(key = 1)]
+    second: String,
+}
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "uq_beta", schema = "tests.uq_beta")]
+struct UqBeta {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: String,
+    #[cultcache(key = 1)]
+    second: String,
+}
+
+fn unique(sku: &str) -> Unique {
+    Unique { sku: sku.into(), category: "c".into() }
+}
+
+fn multi(a: Option<&str>, b: Option<&str>) -> Multi {
+    Multi { a: a.map(Into::into), b: b.map(Into::into) }
+}
+
+fn refusal(k1: &str, k2: &str, schema: &str, alias: &str) -> String {
+    format!("Records {k1} and {k2} ({schema}) both hold unique index '{alias}'; an index value names one record.")
+}
+
+fn cache_at(path: &Path) -> CultCache {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Unique>().unwrap();
+    cache.register_entry_type::<Multi>().unwrap();
+    cache.register_entry_type::<Other>().unwrap();
+    cache.register_entry_type::<Plain>().unwrap();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path)).unwrap();
+    cache.pull_all_backing_stores().unwrap();
+    cache
+}
+
+fn memory_cache() -> CultCache {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Unique>().unwrap();
+    cache.register_entry_type::<Multi>().unwrap();
+    cache.register_entry_type::<Other>().unwrap();
+    cache
+}
+
+fn twin_cache_at(path: &Path) -> CultCache {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Twin>().unwrap();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path)).unwrap();
+    cache.pull_all_backing_stores().unwrap();
+    cache
+}
+
+fn error_text(result: anyhow::Result<impl std::fmt::Debug>) -> String {
+    format!("{:#}", result.unwrap_err())
+}
+
+fn skus(cache: &CultCache) -> Vec<(String, String)> {
+    cache.get_all_with_keys::<Unique>().unwrap().into_iter().map(|(key, value)| (key, value.sku)).collect()
+}
+
+#[test]
+fn the_derive_emits_the_unique_aliases() {
+    fn aliases<T: DatabaseEntry>() -> Vec<&'static str> {
+        T::UNIQUE_INDEXES.iter().map(|(alias, _)| *alias).collect()
+    }
+    assert_eq!(aliases::<Unique>(), ["Sku"]);
+    assert_eq!(aliases::<Multi>(), ["B", "A"]);
+    assert!(aliases::<Plain>().is_empty());
+}
+
+#[test]
+fn a_put_of_a_held_value_at_another_key_is_refused_and_changes_nothing() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("u.cc");
+    let mut cache = cache_at(&path);
+    cache.put("item:b", &unique("S-1")).unwrap();
+    let bytes = std::fs::read(&path).unwrap();
+
+    let text = error_text(cache.put("item:a", &unique("S-1")));
+    assert_eq!(text, refusal("item:a", "item:b", "tests.unique_item", "Sku"));
+    assert!(!text.contains("S-1"), "the refusal never names the value");
+    assert_eq!(std::fs::read(&path).unwrap(), bytes, "the store is untouched");
+    assert_eq!(cache.get::<Unique>("item:a").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S-1").unwrap().unwrap().sku, "S-1");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S-1").unwrap(), cache.get::<Unique>("item:b").unwrap());
+}
+
+// The old bug: write b then a sharing a value used to answer whichever key sorted first.
+#[test]
+fn the_first_holder_keeps_the_value_whatever_the_key_order() {
+    let mut cache = memory_cache();
+    cache.put("item:z", &unique("S")).unwrap();
+    assert!(cache.put("item:a", &unique("S")).is_err());
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap().unwrap(), unique("S"));
+    assert_eq!(skus(&cache), vec![("item:z".to_string(), "S".to_string())]);
+}
+
+#[test]
+fn a_record_rewriting_its_own_key_keeps_its_value_and_a_change_releases_the_old_one() {
+    let mut cache = memory_cache();
+    cache.put("k", &unique("S")).unwrap();
+    cache.put("k", &Unique { sku: "S".into(), category: "other".into() }).unwrap();
+    assert!(cache.get_by_index::<Unique>("Sku", "S").unwrap().is_some());
+
+    cache.put("k", &unique("T")).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None, "a stale value is not found");
+    cache.put("j", &unique("S")).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap().unwrap().sku, "S");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "T").unwrap().unwrap().sku, "T");
+    // Updating through `update` is the same rule.
+    assert!(cache.update::<Unique, _>("k", |_| unique("S")).is_err());
+    assert_eq!(cache.get::<Unique>("k").unwrap().unwrap().sku, "T");
+}
+
+#[test]
+fn delete_releases_a_value() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("d.cc");
+    let mut cache = cache_at(&path);
+    cache.put("item:a", &unique("S")).unwrap();
+    assert!(cache.put("item:b", &unique("S")).is_err());
+    assert!(cache.delete::<Unique>("item:a").unwrap());
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None);
+    cache.put("item:b", &unique("S")).unwrap();
+    assert!(cache.get_by_index::<Unique>("Sku", "S").unwrap().is_some());
+    assert!(!cache.delete::<Unique>("item:a").unwrap(), "deleting an absent key releases nothing");
+    assert!(cache.get_by_index::<Unique>("Sku", "S").unwrap().is_some());
+    assert!(cache_at(&path).get_by_index::<Unique>("Sku", "S").unwrap().is_some());
+}
+
+#[test]
+fn types_sharing_an_alias_and_a_value_do_not_conflict() {
+    let mut cache = memory_cache();
+    cache.put("a", &unique("S")).unwrap();
+    cache.put("oa", &Other { sku: "S".into() }).unwrap();
+    cache.put("ob", &Other { sku: "T".into() }).unwrap();
+    assert!(cache.put("ob", &Other { sku: "S".into() }).is_err());
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap().unwrap(), unique("S"));
+    assert_eq!(cache.get_by_index::<Other>("Sku", "S").unwrap().unwrap(), Other { sku: "S".into() });
+}
+
+#[test]
+fn an_alias_the_type_does_not_declare_finds_nothing() {
+    let mut cache = memory_cache();
+    cache.put("a", &unique("S")).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("sku", "S").unwrap(), None);
+    assert_eq!(cache.get_by_index::<Unique>("Category", "c").unwrap(), None);
+}
+
+#[test]
+fn blank_and_none_values_never_conflict() {
+    let mut cache = memory_cache();
+    for (key, sku) in [("a", " "), ("b", ""), ("c", "\u{85}"), ("d", "\t\n\u{a0}\u{3000}")] {
+        cache.put(key, &unique(sku)).unwrap();
+    }
+    cache.put("m1", &multi(None, None)).unwrap();
+    cache.put("m2", &multi(None, Some(" "))).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", " ").unwrap(), None);
+    // U+FEFF, U+001F, U+200B, U+180E are values, never trimmed.
+    cache.put("e", &unique("\u{feff}")).unwrap();
+    assert!(cache.put("f", &unique("\u{feff}")).is_err());
+    cache.put("g", &unique(" S ")).unwrap();
+    cache.put("h", &unique("S")).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", " S ").unwrap().unwrap().sku, " S ");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap().unwrap().sku, "S");
+}
+
+// C# `string.IsNullOrWhiteSpace` over every code unit: exactly these 25 are blank (probed at 7760219b, dotnet 10).
+#[test]
+fn the_blank_set_is_exactly_the_csharp_white_space() {
+    let blank: Vec<u32> = (0x9..=0xD)
+        .chain([0x20, 0x85, 0xA0, 0x1680])
+        .chain(0x2000..=0x200A)
+        .chain([0x2028, 0x2029, 0x202F, 0x205F, 0x3000])
+        .collect();
+    assert_eq!(blank.len(), 25);
+    let mut cache = memory_cache();
+    let mut found = Vec::new();
+    for unit in (0..=0xFFFF_u32).filter(|unit| char::from_u32(*unit).is_some()) {
+        let text = char::from_u32(unit).unwrap().to_string();
+        cache.put("a", &unique(&text)).unwrap();
+        let second = cache.put("b", &unique(&text));
+        if second.is_ok() {
+            found.push(unit);
+            cache.delete::<Unique>("b").unwrap();
+            assert_eq!(cache.get_by_index::<Unique>("Sku", &text).unwrap(), None, "U+{unit:04X} blank is never found");
+        } else {
+            assert_eq!(cache.get_by_index::<Unique>("Sku", &text).unwrap().unwrap().sku, text);
+        }
+    }
+    assert_eq!(found, blank);
+}
+
+fn staged<T: DatabaseEntry>(cache: &CultCache, rows: &[(&str, T)]) -> Vec<CultCacheEnvelope> {
+    rows.iter().map(|(key, value)| cache.prepare_entry(*key, value).unwrap().0).collect()
+}
+
+// Two unique indexes, collision on the second-declared, through every write path.
+#[test]
+fn every_write_path_refuses_and_changes_nothing() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("paths.cc");
+    let mut cache = cache_at(&path);
+    cache.put("m:held", &multi(Some("a1"), Some("b1"))).unwrap();
+    let bytes = std::fs::read(&path).unwrap();
+    let before = cache.snapshot();
+
+    let clash_b = multi(Some("a2"), Some("b1"));
+    let clash_a = multi(Some("a1"), Some("b2"));
+    for (clash, alias) in [(&clash_b, "B"), (&clash_a, "A")] {
+        let pick = |text: &str| {
+            let (first, second) = if "m:new" < "m:held" { ("m:new", "m:held") } else { ("m:held", "m:new") };
+            assert_eq!(text, refusal(first, second, "Multi", alias));
+        };
+        pick(&error_text(cache.put("m:new", clash)));
+        pick(&error_text(cache.update::<Multi, _>("m:new", |_| clash.clone())));
+        let envelope = staged(&cache, &[("m:new", clash.clone())]).remove(0);
+        pick(&error_text(cache.put_envelope::<Multi>(envelope.clone())));
+        pick(&error_text(cache.put_raw_envelope(envelope.clone())));
+        pick(&error_text(cache.put_prepared_batch(vec![envelope])));
+        assert_eq!(std::fs::read(&path).unwrap(), bytes);
+        assert_eq!(cache.snapshot(), before);
+        assert_eq!(cache.get_by_index::<Multi>("B", "b2").unwrap(), None);
+    }
+    // A clean row through every path lands and is found by both aliases.
+    let fine = multi(Some("a9"), Some("b9"));
+    cache.put("m:1", &fine).unwrap();
+    let envelope = staged(&cache, &[("m:2", multi(Some("a8"), Some("b8")))]).remove(0);
+    cache.put_envelope::<Multi>(envelope).unwrap();
+    let envelope = staged(&cache, &[("m:3", multi(Some("a7"), Some("b7")))]).remove(0);
+    cache.put_raw_envelope(envelope).unwrap();
+    cache.put_prepared_batch(staged(&cache, &[("m:4", multi(Some("a6"), Some("b6")))])).unwrap();
+    for (alias, value, key) in [("A", "a9", 1), ("B", "b8", 2), ("A", "a7", 3), ("B", "b6", 4)] {
+        let found = cache.get_by_index::<Multi>(alias, value).unwrap().unwrap();
+        assert_eq!(Some(found), cache.get::<Multi>(&format!("m:{key}")).unwrap());
+    }
+    // Held values survive a reopen of the store: the load installs the same holders.
+    let mut reopened = cache_at(&path);
+    assert!(reopened.put("m:x", &multi(None, Some("b9"))).is_err());
+    assert!(reopened.put("m:x", &multi(Some("a6"), None)).is_err());
+    assert!(reopened.put("m:x", &multi(Some("zz"), Some("yy"))).is_ok());
+}
+
+#[test]
+fn a_batch_is_judged_whole() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("batch.cc");
+    let mut cache = cache_at(&path);
+    cache.put("a", &unique("X")).unwrap();
+    cache.put("b", &unique("Y")).unwrap();
+
+    // A swap inside one batch lands.
+    cache.put_prepared_batch(staged(&cache, &[("a", unique("Y")), ("b", unique("X"))])).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "Y").unwrap(), cache.get::<Unique>("a").unwrap());
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "X").unwrap(), cache.get::<Unique>("b").unwrap());
+    assert_eq!(cache_at(&path).get_by_index::<Unique>("Sku", "X").unwrap().unwrap().sku, "X");
+
+    // A batch taking a value a record being replaced just released lands; one holding a value twice is refused whole.
+    cache.put_prepared_batch(staged(&cache, &[("a", unique("Z")), ("c", unique("Y"))])).unwrap();
+    let bytes = std::fs::read(&path).unwrap();
+    let before = cache.snapshot();
+    let text = error_text(cache.put_prepared_batch(staged(&cache, &[("p", unique("N")), ("q", unique("N")), ("r", unique("W"))])));
+    assert_eq!(text, refusal("p", "q", "tests.unique_item", "Sku"));
+    assert_eq!(std::fs::read(&path).unwrap(), bytes);
+    assert_eq!(cache.snapshot(), before);
+
+    // A key staged twice lands as its last envelope.
+    cache.put_prepared_batch(staged(&cache, &[("d", unique("D1")), ("d", unique("D2")), ("e", unique("D1"))])).unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "D2").unwrap(), cache.get::<Unique>("d").unwrap());
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "D1").unwrap(), cache.get::<Unique>("e").unwrap());
+}
+
+#[test]
+fn a_load_of_a_duplicate_image_is_refused_and_keeps_the_prior_view() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("load.cc");
+    let mut cache = cache_at(&path);
+    cache.put("item:keep", &unique("K")).unwrap();
+
+    let mut twin = twin_cache_at(&path);
+    twin.put("item:b", &Twin { sku: "S".into(), category: "c".into() }).unwrap();
+    twin.put("item:a", &Twin { sku: "S".into(), category: "c".into() }).unwrap();
+    let bytes = std::fs::read(&path).unwrap();
+
+    let before = cache.snapshot();
+    assert_eq!(error_text(cache.pull_all_backing_stores()), refusal("item:a", "item:b", "tests.unique_item", "Sku"));
+    assert_eq!(cache.snapshot(), before, "a refused pull admits nothing");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "K").unwrap().unwrap().sku, "K");
+    assert_eq!(std::fs::read(&path).unwrap(), bytes);
+
+    // load_soa of the same image through a cache with no store.
+    let table: CultCacheSoaTable = twin.snapshot_soa();
+    let mut soa = memory_cache();
+    soa.put("item:keep", &unique("K")).unwrap();
+    let before = soa.snapshot();
+    assert_eq!(error_text(soa.load_soa(table)), refusal("item:a", "item:b", "tests.unique_item", "Sku"));
+    assert_eq!(soa.snapshot(), before);
+    assert!(soa.get_by_index::<Unique>("Sku", "K").unwrap().is_some());
+
+    // A clean image loads and replaces the holders with the image's.
+    let mut clean = twin_cache_at(&dir.path().join("clean.cc"));
+    clean.put("item:x", &Twin { sku: "X".into(), category: "c".into() }).unwrap();
+    soa.load_soa(clean.snapshot_soa()).unwrap();
+    assert_eq!(soa.get_by_index::<Unique>("Sku", "K").unwrap(), None);
+    assert!(soa.get_by_index::<Unique>("Sku", "X").unwrap().is_some());
+    soa.put("item:y", &unique("K")).unwrap();
+}
+
+#[test]
+fn a_multi_index_store_with_a_duplicate_on_the_second_alias_refuses_to_open() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("multi.cc");
+    {
+        #[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+        #[cultcache(type = "multi", schema = "Multi")]
+        struct Role {
+            #[cultcache(key = 0)]
+            b: Option<String>,
+            #[cultcache(key = 1)]
+            a: Option<String>,
+        }
+        let mut cache = CultCache::new();
+        cache.register_entry_type::<Role>().unwrap();
+        cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+        cache.pull_all_backing_stores().unwrap();
+        cache.put("m:1", &Role { b: Some("b".into()), a: Some("a1".into()) }).unwrap();
+        cache.put("m:2", &Role { b: Some("b".into()), a: Some("a2".into()) }).unwrap();
+    }
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Multi>().unwrap();
+    cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+    assert_eq!(error_text(cache.pull_all_backing_stores()), refusal("m:1", "m:2", "Multi", "B"));
+}
+
+#[test]
+fn a_bool_index_is_found_by_the_csharp_text() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<VBool>().unwrap();
+    cache.put("t", &VBool { v: true }).unwrap();
+    assert!(cache.put("u", &VBool { v: true }).is_err());
+    cache.put("f", &VBool { v: false }).unwrap();
+    assert_eq!(cache.get_by_index::<VBool>("V", "True").unwrap().unwrap().v, true);
+    assert_eq!(cache.get_by_index::<VBool>("V", "False").unwrap().unwrap().v, false);
+    assert_eq!(cache.get_by_index::<VBool>("V", "true").unwrap(), None);
+    assert_eq!(cache.get_by_index::<VBool>("V", "false").unwrap(), None);
+}
+
+// ---- shared vectors, written by the C# reference ----
+
+#[allow(dead_code)]
+#[derive(Debug, Deserialize)]
+#[serde(untagged)]
+enum Cell {
+    Nil,
+    Bool(bool),
+    Int(i64),
+    Uint(u64),
+    Double(f64),
+    Text(String),
+}
+
+fn vectors() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../tests/vectors/unique-index")
+}
+
+type ValueRow = (String, String, Cell, Option<String>);
+
+#[test]
+fn vectors_values_give_the_csharp_index_text() {
+    let bytes = std::fs::read(vectors().join("values.msgpack")).unwrap();
+    let rows: Vec<ValueRow> = rmp_serde::from_slice(&bytes).unwrap();
+    assert!(!rows.is_empty());
+    let mut checked = 0;
+    for (label, kind, value, text) in rows {
+        let mut cache = CultCache::new();
+        cache.register_entry_type::<VString>().unwrap();
+        cache.register_entry_type::<VInt>().unwrap();
+        cache.register_entry_type::<VUint>().unwrap();
+        cache.register_entry_type::<VBool>().unwrap();
+        // `double` rows are skipped: CultLookupValue has no float impl, so Rust cannot index a double member.
+        match (kind.as_str(), value) {
+            ("string", Cell::Text(held)) => {
+                cache.put("one", &VString { v: held.clone() }).unwrap();
+                match text {
+                    Some(text) => {
+                        assert_eq!(cache.get_by_index::<VString>("V", &text).unwrap().unwrap().v, held, "{label}");
+                        assert!(cache.put("two", &VString { v: held }).is_err(), "{label}");
+                    }
+                    None => {
+                        cache.put("two", &VString { v: held.clone() }).unwrap();
+                        assert_eq!(cache.get_by_index::<VString>("V", &held).unwrap(), None, "{label}");
+                    }
+                }
+            }
+            ("int64", Cell::Int(held)) => {
+                cache.put("one", &VInt { v: held }).unwrap();
+                assert_eq!(cache.get_by_index::<VInt>("V", &text.unwrap()).unwrap().unwrap().v, held, "{label}");
+                assert!(cache.put("two", &VInt { v: held }).is_err(), "{label}");
+            }
+            ("uint64", Cell::Uint(held)) => {
+                cache.put("one", &VUint { v: held }).unwrap();
+                assert_eq!(cache.get_by_index::<VUint>("V", &text.unwrap()).unwrap().unwrap().v, held, "{label}");
+                assert!(cache.put("two", &VUint { v: held }).is_err(), "{label}");
+            }
+            ("uint64", Cell::Int(held)) => {
+                cache.put("one", &VUint { v: held as u64 }).unwrap();
+                assert_eq!(cache.get_by_index::<VUint>("V", &text.unwrap()).unwrap().unwrap().v, held as u64, "{label}");
+            }
+            ("int64", Cell::Uint(held)) => {
+                cache.put("one", &VInt { v: held as i64 }).unwrap();
+                assert_eq!(cache.get_by_index::<VInt>("V", &text.unwrap()).unwrap().unwrap().v, held as i64, "{label}");
+            }
+            ("bool", Cell::Bool(held)) => {
+                cache.put("one", &VBool { v: held }).unwrap();
+                assert_eq!(cache.get_by_index::<VBool>("V", &text.unwrap()).unwrap().unwrap().v, held, "{label}");
+            }
+            ("double", Cell::Double(_) | Cell::Int(_) | Cell::Uint(_) | Cell::Nil) => continue,
+            (kind, value) => panic!("{label}: unexpected vector row {kind} {value:?}"),
+        }
+        checked += 1;
+    }
+    assert!(checked > 10, "the vectors were read, not skipped: {checked}");
+}
+
+type OutcomeRow = (String, Option<String>, String, Option<String>, Option<String>);
+
+#[test]
+fn vectors_stores_hold_their_verdicts() {
+    let bytes = std::fs::read(vectors().join("outcomes.msgpack")).unwrap();
+    let rows: Vec<OutcomeRow> = rmp_serde::from_slice(&bytes).unwrap();
+    assert!(rows.len() >= 3);
+    let dir = tempfile::tempdir().unwrap();
+    for (file, alias, verdict, k1, k2) in rows {
+        let path = dir.path().join(&file);
+        std::fs::copy(vectors().join(&file), &path).unwrap();
+        let before = std::fs::read(&path).unwrap();
+        let attach = |cache: &mut CultCache| {
+            cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+            cache.pull_all_backing_stores()
+        };
+        let mut cache = CultCache::new();
+        let opened = match alias.as_deref() {
+            Some("Sku") => {
+                cache.register_entry_type::<Unique>().unwrap();
+                attach(&mut cache)
+            }
+            None => {
+                cache.register_entry_type::<Twin>().unwrap();
+                attach(&mut cache)
+            }
+            Some(other) => panic!("unexpected vector alias {other}"),
+        };
+        match verdict.as_str() {
+            "open" => opened.unwrap_or_else(|error| panic!("{file} / {alias:?} should open: {error:#}")),
+            "refused" => assert_eq!(
+                error_text(opened),
+                refusal(&k1.unwrap(), &k2.unwrap(), "tests.unique_item", "Sku"),
+                "{file}"
+            ),
+            other => panic!("unexpected verdict {other}"),
+        }
+        assert_eq!(std::fs::read(&path).unwrap(), before, "{file} is byte-identical");
+    }
+}
+
+/// One op of a refusals row: `["open", file-or-nil]`, `["pull", file]` or `["commit", [[key, schema, sku, second], ...]]`.
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum Arg {
+    Records(Vec<(String, String, String, String)>),
+    File(Option<String>),
+}
+
+type RefusalRow = (String, Vec<(String, Arg)>, Option<(String, String, String, String)>);
+
+/// Rows `[label, ops, refusal]`: the pair a refusal names is a function of the state the admission would leave
+/// (`tests/vectors/unique-index/README.md`, RULE), whatever the staging, file or pull order, key case or alias case.
+#[test]
+fn vectors_refusals_hold_the_rule() {
+    let bytes = std::fs::read(vectors().join("refusals.msgpack")).unwrap();
+    let rows: Vec<RefusalRow> = rmp_serde::from_slice(&bytes).unwrap();
+    let dir = tempfile::tempdir().unwrap();
+    let mut walked = 0;
+    for (index, (label, ops, refused)) in rows.into_iter().enumerate() {
+        let path = dir.path().join(format!("row-{index}.cc"));
+        let mut cache: Option<CultCache> = None;
+        let mut failure = None;
+        for (at, (kind, arg)) in ops.iter().enumerate() {
+            let last = at + 1 == ops.len();
+            let mut before = path.exists().then(|| std::fs::read(&path).unwrap());
+            let result = match (kind.as_str(), arg) {
+                ("open", Arg::File(file)) => {
+                    if let Some(file) = file {
+                        std::fs::copy(vectors().join(file), &path).unwrap();
+                    }
+                    let mut opened = CultCache::new();
+                    opened.register_entry_type::<Unique>().unwrap();
+                    opened.register_entry_type::<UqPair>().unwrap();
+                    opened.register_entry_type::<UqAlias>().unwrap();
+                    opened.register_entry_type::<UqWide>().unwrap();
+                    opened.register_entry_type::<UqAlpha>().unwrap();
+                    opened.register_entry_type::<UqBeta>().unwrap();
+                    opened.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&path)).unwrap();
+                    let pulled = opened.pull_all_backing_stores();
+                    cache = Some(opened);
+                    pulled
+                }
+                ("pull", Arg::File(Some(file))) => {
+                    std::fs::copy(vectors().join(file), &path).unwrap();
+                    before = Some(std::fs::read(&path).unwrap());
+                    cache.as_mut().unwrap().pull_all_backing_stores()
+                }
+                ("commit", Arg::Records(records)) => {
+                    let cache = cache.as_mut().unwrap();
+                    let staged: Vec<_> = records
+                        .iter()
+                        .map(|(key, schema, sku, second)| {
+                            let (sku, second) = (sku.clone(), second.clone());
+                            match schema.as_str() {
+                                "tests.unique_item" => cache.prepare_entry(key, &Unique { sku, category: second }).map(|(envelope, _)| envelope),
+                                "tests.uq_pair" => cache.prepare_entry(key, &UqPair { sku, alt: second }).map(|(envelope, _)| envelope),
+                                "tests.uq_alias" => cache.prepare_entry(key, &UqAlias { sku, alt: second }).map(|(envelope, _)| envelope),
+                                "tests.uq_wide" => cache.prepare_entry(key, &UqWide { sku, alt: second }).map(|(envelope, _)| envelope),
+                                "tests.uq_alpha" => cache.prepare_entry(key, &UqAlpha { sku, second }).map(|(envelope, _)| envelope),
+                                "tests.uq_beta" => cache.prepare_entry(key, &UqBeta { sku, second }).map(|(envelope, _)| envelope),
+                                other => panic!("{label}: unexpected schema {other}"),
+                            }
+                            .unwrap()
+                        })
+                        .collect();
+                    cache.put_prepared_batch(staged)
+                }
+                other => panic!("{label}: unexpected op {:?}", other.0),
+            };
+            if last {
+                failure = Some((result, before));
+            } else {
+                result.unwrap_or_else(|error| panic!("{label}: op {at} should succeed: {error:#}"));
+            }
+        }
+        let (result, before) = failure.unwrap();
+        match refused {
+            None => result.unwrap_or_else(|error| panic!("{label}: should succeed: {error:#}")),
+            Some((k1, k2, schema, alias)) => {
+                let error = result.err().unwrap_or_else(|| panic!("{label}: should refuse"));
+                assert_eq!(format!("{error:#}"), refusal(&k1, &k2, &schema, &alias), "{label}");
+                if let Some(before) = before {
+                    assert_eq!(std::fs::read(&path).unwrap(), before, "{label}: the file is byte-identical");
+                }
+            }
+        }
+        walked += 1;
+    }
+    assert_eq!(walked, 37);
+}
+
+// A pull replaces the holder table with the stored image's: a value another writer changed is released, not kept.
+#[test]
+fn a_second_pull_replaces_the_holders_with_the_stored_image() {
+    let dir = tempfile::tempdir().unwrap();
+    let path = dir.path().join("pull.cc");
+    let mut cache = cache_at(&path);
+    cache.put("a", &unique("S")).unwrap();
+
+    cache_at(&path).put("a", &unique("T")).unwrap();
+    cache.pull_all_backing_stores().unwrap();
+
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None, "the replaced value is no longer held");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "T").unwrap(), cache.get::<Unique>("a").unwrap());
+    cache.put("b", &unique("S")).unwrap();
+    assert!(cache.put("c", &unique("T")).is_err());
+}
+
+// The projector decides what held records hold: declaring an index for a type that already has records derives
+// their holders, or refuses the registration when they collide.
+#[test]
+fn registering_an_index_over_held_records_derives_their_holders() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Twin>().unwrap();
+    cache.put("a", &Twin { sku: "S".into(), category: "x".into() }).unwrap();
+    cache.put("b", &Twin { sku: "T".into(), category: "x".into() }).unwrap();
+
+    cache.register_entry_type::<Unique>().unwrap();
+
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), cache.get::<Unique>("a").unwrap());
+    assert!(cache.get_by_index::<Unique>("Sku", "S").unwrap().is_some());
+    assert!(cache.put("c", &unique("S")).is_err(), "a held value is refused");
+    cache.put("c", &unique("U")).unwrap();
+}
+
+#[test]
+fn registering_an_index_over_colliding_held_records_is_refused_and_changes_nothing() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Twin>().unwrap();
+    cache.put("a", &Twin { sku: "S".into(), category: "x".into() }).unwrap();
+    cache.put("b", &Twin { sku: "S".into(), category: "y".into() }).unwrap();
+
+    let text = error_text(cache.register_entry_type::<Unique>());
+    assert_eq!(text, refusal("a", "b", "tests.unique_item", "Sku"));
+
+    // Still the unindexed declaration: duplicates keep landing, nothing is looked up.
+    cache.put("c", &Twin { sku: "S".into(), category: "z".into() }).unwrap();
+    assert_eq!(cache.get_all_with_keys::<Twin>().unwrap().len(), 3);
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None);
+}
+
+/// The same type and schema declaring Sku as an integer: the held text cannot be decoded as one.
+#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+#[cultcache(type = "unique_item", schema = "tests.unique_item")]
+struct Retyped {
+    #[cultcache(key = 0, index = "Sku")]
+    sku: i64,
+}
+
+/// A refused re-registration leaves the previous declaration in force: it keeps judging, so a later duplicate is refused.
+#[test]
+fn a_refused_reregistration_keeps_the_previous_index_judging() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Unique>().unwrap();
+    cache.put("a", &unique("S")).unwrap();
+    cache.put("b", &unique("T")).unwrap();
+
+    // A different declaration over the same type (Category is the unique alias) collides on held records.
+    #[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
+    #[cultcache(type = "unique_item", schema = "tests.unique_item")]
+    struct ByCat {
+        #[cultcache(key = 0)]
+        sku: String,
+        #[cultcache(key = 1, index = "Cat")]
+        category: String,
+    }
+    assert!(cache.register_entry_type::<ByCat>().is_err(), "a and b both hold category c");
+
+    assert!(cache.put("z", &unique("S")).is_err(), "the previous index still judges");
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), cache.get::<Unique>("a").unwrap());
+    cache.put("z", &unique("U")).unwrap();
+}
+
+// A held record the new declaration cannot decode refuses the registration; the unindexed declaration stays.
+#[test]
+fn registering_an_index_over_an_undecodable_held_record_is_refused_and_changes_nothing() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Twin>().unwrap();
+    cache.put("a", &Twin { sku: "S".into(), category: "x".into() }).unwrap();
+
+    assert!(cache.register_entry_type::<Retyped>().is_err());
+
+    cache.put("b", &Twin { sku: "S".into(), category: "y".into() }).unwrap();
+    assert_eq!(cache.get_all_with_keys::<Twin>().unwrap().len(), 2, "no index judges the duplicate");
+}
+
+// Dropping the declaration releases the holders.
+#[test]
+fn registering_without_the_index_releases_the_holders() {
+    let mut cache = CultCache::new();
+    cache.register_entry_type::<Unique>().unwrap();
+    cache.put("a", &unique("S")).unwrap();
+    cache.register_entry_type::<Twin>().unwrap();
+    assert_eq!(cache.get_by_index::<Unique>("Sku", "S").unwrap(), None, "no declaration, no holders");
+    cache.put("b", &Twin { sku: "S".into(), category: "x".into() }).unwrap();
+    assert!(cache.register_entry_type::<Unique>().is_err(), "the duplicate now written is a held violation");
+}

packages/cultcache-ts/CHANGELOG.md

@@ -3,29 +3,56 @@
 All notable changes to `@gamecult/cultcache-ts` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## Unreleased
+## [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 single-file store marked `cultcache.store.v3` (it holds an element id, written by the C# runtime) is read, and a rewrite keeps the mark and the ids; this runtime does not decide when a document carries ids. A runtime from before this change refuses a v3 store by name, so rolling back to an older release after a store has been written as v3 is one-way: there is no carry-back, so restore from a copy taken before upgrading.
+- `indexes` are unique, as C# `[CultIndex]`: a write or a load that leaves two records of a type holding one non-blank
+  value under one alias is refused naming both keys and the alias, and writes nothing. Index text is the C# canonical
+  text (booleans `True`/`False`, integers as digits, doubles as the exact expansion, blank values never indexed), so
+  an empty string is no longer a value. `registerIndex` over held duplicates installs nothing. A new `roles` map names
+  the many-row selection aliases (never indexed for lookup, same catalog `indexAlias`). The per-key migration rule is
+  in the README; classify every key before the CultLib your tools load is updated. The refusal verdict is the contract, its text is informational.
+- The single-file reader (v1 and the legacy envelope array) refuses a store that holds two records under one key as `StoreUnreadableError`; a store that opened before may now be refused. Repair it by removing the extra record with the runtime that wrote it.
+- A `put`, `push` or `pushAll` that would land a second type under a held key (against the file, or within one batch) is refused with `SchemaConflictError`, and nothing is written. The written type may replace the record when its catalog entry carries the stored schema id as its own or lists it compatible (a type renamed under a stable id restamps the record, as C# does); otherwise retyping a key is a delete, then a put. The C# allowance for an undeclared older id of the same schema name that reads whole is not ported: a same-named type keeps passing, including one that drops persisted slots, which C# refuses.
+- Same-type writes replace by key; in one `pushAll` batch the last entry for a key wins.
+- A store whose canonical-schema catalog slot is not a string is refused as `StoreUnreadableError`.
+- The cache holds one record per key (variants:ruling:cache-refuses-retype). A `put` or `putEnvelope` that lands a second type under a key the cache holds, or under a key a store carries foreign, is refused with `SchemaConflictError` naming the key, even with no store (a memory-only cache used to hold both types at the key). A type that owns the held record's schema id (as for the store) replaces it, unless the held record is in a store other than the written type's home: that rename is refused with `SchemaConflictError` (remove the record first). Two stores holding one key, registered or foreign, refuse the load and admit nothing. A store's `delete` removes the record whose stored schema id the removal's type owns, whatever the arrived record's `type` string.
+- A store holding a record no registered type claims now loads (it used to throw "No schema is registered..."): the cache does not serve the record, lists it in `foreignRecords()`, keeps its bytes through every write, and refuses a `put` or a `delete` at its key with `SchemaConflictError` (variants:ruling:unheld-removal-refused-at-commit). Registering a type that claims its schema id serves it at the next `pullAllBackingStores`.
+- A record whose payload carries a slot past its reader's declared slots, at any depth (the record, a nested record, a list element, a union arm, a unit arm), is now held read-only: it loads and reads, and every `put`, `putEnvelope`, `update` or `delete` of its key is refused with `SchemaConflictError` before a store is touched (cultlib-gaps:ruling:extra-trailing-slots, as the C# reference). A load used to skip the extra slots silently and a later write shed them. The refusal names the schema, the key, the type that was read with extra slots and both slot counts, never a slot value, and carries them as `SchemaConflictError.unreadSlots`. An untouched record keeps its bytes through writes of other keys. Missing trailing slots keep their declared defaults and mark nothing. A `put` never marks (the value is encoded by this runtime); a `putEnvelope` of a payload carrying extra slots lands its bytes and holds the record read-only. A mark at depth 0 is consented to only when the record arrived under a schema id other than the reader's own that the reader lists compatible, and that id's catalog entry lists those slots (a writer that adds a slot and keeps the reader's id is never consented to) (`unreadSlots.explained`); every other mark refuses whatever is declared. New: `CultCache.isWritable(definition, key)` (live, advisory), `CultCache.unreadSlots(definition, key)` and the exported `CultCacheUnreadSlots`. Documents with no slot codec (a plain map, a user formatter) never mark. A `delete` is by key: a type that owns the schema id of the record held at the key as another type removes that one record (one store call, the cache dropped once the store has removed it), and a type that does not own it is refused with `SchemaConflictError`, as a `put` is; `isWritable` answers both. Implied semver: a minor bump (0.16.0) while the package is 0.x; a major one at 1.0 and after.
+
+### Added
+
+- `CultCache.foreignRecords()`: the `{key, schemaId, schemaName, storedAt}` of every record the last pull carried and no registered type claims, sorted by key ordinal.
+
+### Changed
+
+- Opening a legacy (pre-v1) store is a pure read: payloads that were not bytes are normalized in memory and the
+  file is left as it was, so a codec that refuses the content cannot lose the old bytes. The next push, delete or
+  flush rewrites the file as v1, merging what the open read.
+- `SingleFileStoreRead` no longer carries `repairedLegacyPayload`; no consumer used it.
+
+## [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 store the C# runtime marked v3 (it holds a record with an element id: an owned list element with a `[CultElementId]` member) keeps its header here, and is carried through every rewrite with its ids; this runtime never drops the mark. 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.
-- This reverses the 0.14.2 `pushAll` fix in two ways. A full `pushAll` over a file with no readable stamp no longer replaces it (healing it): the reader refuses it, and the file is left as it is. And a `cultcache.store.v3` stamp is read, not refused. 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 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.
-
-## [0.14.2]
-
-### Added
 - `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
@@ -35,27 +62,16 @@ 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.
-
-### Changed
-- The Windows replace is a POSIX-semantics rename first (it lands while C# and Rust readers
-  hold the store open), falling back to a write-through `MoveFileExW`, with 25 attempts 20 ms
-  apart on errors 5, 32 and 33. Writers wait up to 30 s for the lock.
-- Opening a legacy store that needs healing rewrites it under the lock, from a read taken
-  under the lock.
-
-### Fixed
-- A full `pushAll` reads the store's header under the lock first and refuses a store format
-  this runtime does not read (the same error a read gives), leaving the file as it was. A
-  file with no readable stamp is still replaced, so a whole write heals it. Soft `pushAll`
-  is unchanged. The stamp is decoded by the decoder a read uses, so a stamp followed by bytes
-  that are not UTF-8 is refused by a whole write as a read refuses it.
-
-### 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.
+
+### 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.
+
+### Dependencies
+
+- `koffi` 3.3.0, loaded only on the first write.

packages/cultcache-ts/README.md

@@ -63,6 +63,10 @@ const payload = encodeDocumentPayload(noteDocument, note); // DocumentPayload
 
 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`.
 
+## Store format and rollback
+
+A store whose elements hold an id is marked `cultcache.store.v3` by the C# runtime. This runtime reads a v3 store, keeps the header it read and carries the ids through a rewrite; it never drops the mark, so it has no carry-back. A cultcache-ts from before element ids refuses a v3 store by name, so rolling back to it after a store has been written as v3 is one-way: restore from a copy taken before upgrading, and upgrade every reader before any writer. (The C# line is different: CultLib 1.x does not refuse; see the GameCult.Caching README.)
+
 ## `.cc` Inspection
 
 CultCache files may use the `.cc` extension. The bytes are still the canonical
@@ -93,12 +97,16 @@ const itemDocument = defineDocumentType({
   schemaVersion: "item.v1",
   schema: z.object({
     name: z.string(),
+    sku: z.string(),
     category: z.string(),
     value: z.number().int(),
   }),
   name: "name",
   indexes: {
-    category: "category",
+    sku: "sku", // unique: a sku names one item
+  },
+  roles: {
+    category: "category", // a selection alias: many items share a category
   },
 });
 
@@ -122,6 +130,7 @@ await cache.pullAllBackingStores();
 
 await cache.put(itemDocument, "item:potion", {
   name: "Potion",
+  sku: "POT-001",
   category: "Consumable",
   value: 50,
 });
@@ -132,7 +141,7 @@ await cache.putGlobal(settingsDocument, {
 });
 
 const potion = cache.getByName(itemDocument, "Potion");
-const consumable = cache.getByIndex(itemDocument, "category", "Consumable");
+const bySku = cache.getByIndex(itemDocument, "sku", "POT-001");
 const settings = cache.getRequiredGlobal(settingsDocument);
 ```
 
@@ -194,7 +203,7 @@ A document type has exactly one home store
 
 ## Name, Index, and Global Semantics
 
-`name` and `indexes` can be declared on the document definition:
+`name`, `indexes` and `roles` can be declared on the document definition:
 
 ```ts
 const playerDocument = defineDocumentType({
@@ -202,17 +211,80 @@ const playerDocument = defineDocumentType({
   schema: playerSchema,
   name: "displayName",
   indexes: {
-    faction: "faction",
-    email: "email",
+    email: "email", // unique lookup
+  },
+  roles: {
+    faction: "faction", // selection alias, many players share one
   },
 });
 ```
 
+`indexes` are unique (variants:ruling:unique-indexes; C# `[CultIndex]`, Rust `#[cultcache(index)]`). Within one type
+and one alias no two records hold one non-blank value, judged on the result of every write and of every load; a
+refusal reads `Records <k1> and <k2> (<schema name>) both hold unique index '<alias>'; an index value names one record.`
+(keys in ordinal order, never the value), and writes nothing. The contract is the verdict, which stores and writes are
+refused; the text is informational. On a load TS judges record by record in file order and names the first collision
+it meets, where C# judges the whole store, so the two runtimes can name different pairs of one store. A blank value (absent, empty, or only whitespace) is
+never indexed and never conflicts. Two types may share an alias and a value. Index values are compared as the C#
+reference renders them: strings as is (never trimmed), `True`/`False`, integers as digits, a non-integral number as
+its exact decimal expansion; NaN and infinities have no value. `roles` name selection and reference aliases (the
+member's catalog `indexAlias`, so the catalog bytes are the same either way); they imply nothing about uniqueness and
+are never indexed for lookup, so `getByIndex` on a role answers `undefined`. An alias is declared in one of the two.
+
+### One record per key, and foreign records
+
+A cache holds one record per key whatever its type (variants:ruling:cache-refuses-retype). A write of a type that does not
+own the held record's schema id (it carries that id as its own or lists it compatible) is refused with
+`SchemaConflictError` naming the key, with or without a store; retyping a key is `delete` then `put`. A store that holds a
+record no registered type claims still loads: the cache does not serve it, `foreignRecords()` lists it (`key`,
+`schemaId`, `schemaName`, `storedAt`, by key ordinal), every write keeps its bytes, and a `put` or `delete` at its key is
+refused. Registering a type that claims its schema id serves it at the next `pullAllBackingStores`. Two stores that hold
+one key refuse the load and admit nothing.
+
+### Migrating an existing `indexes` key
+
+Apply per key, and do it BEFORE the CultLib checkout your tools load is rebuilt or updated. A consumer that loads
+CultLib at run time (Bifrost reads `$VOIDBOT_CULTLIB_ROOT`, else the sibling `../CultLib` dist) has no pin to hold: its
+next start after the checkout moves is the bump. A consumer that pins a version applies this before it bumps the pin.
+Moving an `indexes` key to `roles` is safe on the old CultLib too when the definition lists `members` explicitly (an old
+codec definition without `members` derives `indexAlias` from `indexes` only, so a moved key would lose its catalog alias),
+so the consumer edit lands first:
+
+1. Nothing looks records up by the key (`getByIndex`, `getKeyByIndex`, `getIdByIndex`; Python `get_by_index`,
+   `get_key_by_index`, `node.get_by_index`, `watch_by_index`; Rust `get_by_index`): it is a role. Move it to `roles`;
+   where a definition lists `members` explicitly, delete it from `indexes` and keep the member's `indexAlias` (the
+   catalog is the same).
+2. Something looks it up: it stays unique only when two live records can never hold one non-blank value, because the
+   record key is derived from that value alone, or the value is an outside identity (email, sku, external id).
+   Enums, statuses, kinds, categories, parent or foreign ids, shared hashes and timestamps are roles; a lookup on
+   one already answered an arbitrary record, so move it to a selection (`any_of`) or `getAll` plus a filter.
+3. Before the checkout moves, open each real `.cc` once with the new definitions. A refusal names both keys and the alias and
+   writes nothing.
+
+Misclassifying costs differently each way. A role declared unique: the second record holding a shared value is
+refused at commit, and a store already holding one refuses to open, so that store is down until the key is
+reclassified (loud, names both keys and the alias). A unique key declared a role: lookups by it answer nothing and
+duplicates stop being refused.
+
+The Bifrost TS stores (at 781e6ea) call no lookup anywhere, so by rule 1 every key is a role and no key becomes unique.
+All six definitions list `members` explicitly, each with its `indexAlias`, so the edit is deleting each `indexes` block:
+the catalog is unchanged and the edit is safe on the CultLib it loads today. It must land before that checkout is
+updated:
+
+| Definition | Keys | Verdict |
+|---|---|---|
+| `update-request` (`tools/agent-transport.mjs`) | `targetRepoName`, `targetAgentIdentity`, `status` | role: many requests per repo and agent; status is an enum |
+| `crossing_receipt` (`tools/bifrost-crossing-documents.mjs`) | `commandId`, `crossingKind`, `status` | role: receipts are `crossing_<commandId>_<activityKind>`, several per command; the rest are enums |
+| release authority (`tools/bifrost-repository-release-authority.mjs`) | `repositoryFullName`, `upstreamRef`, `commitSha`, `status` | role: the authority id is derived from repo, ref and sha, so one sha under two refs is two records |
+| `topic` (`tools/governance-threads.mjs`) | `jurisdictionRepoName`, `jurisdictionAgentIdentity`, `status` | role: many topics per jurisdiction |
+| `comment` (`tools/governance-threads.mjs`) | `topicId`, `authorId`, `stance` | role: many comments per topic; stance is an enum |
+| `advertisement` (`tools/provider-advertisement.mjs`) | `serviceName` | role: one record holds it today, but nothing looks it up |
+
 You can also register them later if you feel like changing the machine after boot:
 
 ```ts
 await cache.registerNameLookup(playerDocument, "displayName");
-await cache.registerIndex(playerDocument, "faction", "faction");
+await cache.registerIndex(playerDocument, "email", "email");
 ```
 
 Registration, `addBackingStore`, `pullAllBackingStores` and every write and
@@ -299,8 +371,11 @@ const sceneDocument = defineDocumentType({
 });
 ```
 
-- A slot is `[name, codec, default?]`. A gap is written nil and skipped on read; an extra trailing slot is skipped; a
-  slot missing from the payload (or nil, when a default is declared) takes its default, and is refused without one.
+- A slot is `[name, codec, default?]`. A gap is written nil and skipped on read; an extra trailing slot is read past and
+  marks the record read-only (every write or removal of its key is refused with `SchemaConflictError`, `cache.isWritable`
+  asks first). The one writable case is a depth-0 extra slot of a record that arrived under a schema id other than the reader's own, which the
+  reader lists in `compatibleSchemaIds`, whose catalog entry lists those slots: declaring that id consents to the loss, and a write restamps
+  the record. A nested slot, or a writer that keeps the reader's own id, is never consented to. A slot missing from the payload (or nil, when a default is declared) takes its default, and is refused without one.
 - A union refuses an undeclared arm key on read, naming the union, the key and the declared keys. Nothing falls back
   to a default arm. An arm with no slots is `codecs.unit` and is written `[key, []]`.
 - A refusal names the union, the field and the slot; it never echoes the value it refused.
@@ -357,7 +432,7 @@ That is the TypeScript version of the original CultCache trick:
 - the top-level MessagePack value is `[formatVersion, schemaCatalog, records]`
 - each record is `[key, schemaId, storedAt, payload]`
 - each catalog entry is `[schemaId, schemaName, schemaVersion, contentHash, canonicalSchemaJson, compatibleSchemaIds, members]`
-- it still reads the older TS/Rust-style envelope array and rewrites repaired legacy payloads as v1 snapshots
+- it still reads the older TS/Rust-style envelope array (object payloads are normalized in memory; opening never rewrites the file) and replaces it with a v1 snapshot on the next push, delete or flush
 - it queues local writes in order, then takes the shared `<file>.lock` (`flock` on Unix, `LockFileEx` on Windows, via koffi, loaded on the first write) for each one, so C#, Rust and TypeScript writers exclude each other; the read a write merges from is taken under that lock
 - it fsyncs the staged file and, on Unix, the directory after the replace; on Windows it replaces with a POSIX-semantics rename and falls back to a write-through `MoveFileExW`, retrying briefly on sharing violations
 - it persists raw MessagePack payload bytes inside schema-addressed records

packages/cultcache-ts/package.json

@@ -1,6 +1,6 @@
 {
   "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",

packages/cultcache-ts/src/browser.ts

@@ -2,7 +2,7 @@
 // (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 { CultCache, CultCacheBuilder, type CultCacheForeignRecord } from "./cult-cache";
 export { inspectCultCacheBytes } from "./cult-cache-inspector";
 export {
   decodeDocumentPayload,
@@ -34,6 +34,7 @@ export type {
   CultCacheIndexScalar,
   InferCultCacheSchemaValue,
   CultCacheStoreRegistration,
+  CultCacheUnreadSlots,
   PushAllOptions,
 } from "./types";
 export type {

packages/cultcache-ts/src/codec.ts

@@ -198,6 +198,66 @@ type SlotSpec<TValue, TName extends string = string> =
 
 type SlotsSpec<TValue> = Readonly<Record<number, { [K in keyof TValue & string]: SlotSpec<TValue[K], K> }[keyof TValue & string]>>;
 
+// The slots a payload decode read past, noted by `slots` and the unit arm while the one decode entry (decodeNoting) has a scope
+// open, and read out by that entry. Module-scoped as the reference's is thread-bound: a decode is synchronous, and a decode
+// outside the entry (a codec called directly, a CultMesh read) notes nothing. No codec signature carries it.
+export interface NotedSlots {
+  /** The first type read with extra slots, outermost first. */
+  readonly typeName: string;
+  readonly slotCount: number;
+  readonly declaredCount: number;
+  readonly occurrences: number;
+  /** True when every noted object was the document's own: a union adds no depth, each record or arm inside a field adds one. */
+  readonly depth0Only: boolean;
+}
+
+interface SlotScope {
+  depth: number;
+  found?: { typeName: string; slotCount: number; declaredCount: number; occurrences: number; depth0Only: boolean };
+}
+
+let scope: SlotScope | undefined;
+
+/** The one decode entry: runs the decode with a scope open and returns its value with what it noted. */
+export function decodeNoting<T>(decode: () => T): { value: T; unreadSlots?: NotedSlots } {
+  const outer = scope;
+  const mine: SlotScope = { depth: 0 };
+  scope = mine;
+  try {
+    const value = decode();
+    return mine.found ? { value, unreadSlots: mine.found } : { value };
+  } finally {
+    scope = outer;
+  }
+}
+
+function noteExtraSlots(typeName: string, slotCount: number, declaredCount: number): void {
+  if (!scope) return;
+  const found = scope.found;
+  if (found) {
+    found.occurrences += 1;
+    found.depth0Only &&= scope.depth === 0;
+  } else {
+    scope.found = { typeName, slotCount, declaredCount, occurrences: 1, depth0Only: scope.depth === 0 };
+  }
+}
+
+// What a record inside a field reads at: one deeper than the record holding the field.
+function nested<T>(read: () => T): T {
+  if (!scope) return read();
+  scope.depth += 1;
+  try {
+    return read();
+  } finally {
+    scope.depth -= 1;
+  }
+}
+
+// The reference's type name for a mark: the type, not its namespace or the type it is nested in.
+function simpleTypeName(typeName: string | undefined): string {
+  return typeName === undefined ? "record" : typeName.slice(Math.max(typeName.lastIndexOf("."), typeName.lastIndexOf("+")) + 1);
+}
+
 const INT32_MIN = -(2 ** 31);
 const INT32_MAX = 2 ** 31 - 1;
 
@@ -232,7 +292,7 @@ function pascalCase(name: string): string {
 }
 
 // A positional record: slot `key` holds field `name`. Gaps are written nil and skipped on read, extra trailing slots
-// are skipped, and a slot missing from the payload takes its declared default or is refused. A default fills only a
+// are read past and noted (decodeNoting): the record that carried them is read-only, never rewritten without them, and a slot missing from the payload takes its declared default or is refused. A default fills only a
 // missing trailing slot, never a nil: as in the reference, a nil in a reference slot (string, bytes, record, union,
 // list) reads as null and writes back as nil, so a record the reference wrote re-encodes byte-identical, and a nil in
 // a value slot (int, float, bool) is refused unless the slot is nullable.
@@ -281,6 +341,9 @@ export function slots<TValue extends object>(spec: SlotsSpec<TValue>, typeName?:
     decode(raw) {
       expect(raw, "an array of slots", Array.isArray(raw));
       const input = raw as unknown[];
+      if (input.length > length) {
+        noteExtraSlots(simpleTypeName(typeName), input.length, length);
+      }
       const out: Record<string, unknown> = {};
       for (const field of fields) {
         const present = field.key < input.length;
@@ -291,7 +354,7 @@ export function slots<TValue extends object>(spec: SlotsSpec<TValue>, typeName?:
           ? defaultOf(field)
           : input[field.key] === null && !field.codec.valueType
             ? null
-            : at(`${field.name} (slot ${field.key})`, () => field.codec.decode(input[field.key]));
+            : at(`${field.name} (slot ${field.key})`, () => nested(() => field.codec.decode(input[field.key])));
       }
       return out as TValue;
     },
@@ -363,6 +426,9 @@ export function union<TValue extends { kind: string }>(
       if (arm === undefined) {
         throw new Error(`Union ${name}: unknown arm key ${key} (declared keys: ${declared}).`);
       }
+      if (arm.body === unit && raw[1].length > 0) {
+        noteExtraSlots(arm.armName, raw[1].length, 0);
+      }
       const fields = arm.body === unit ? {} : at(`arm ${arm.armName}`, () => (arm.body as SlotsCodec<any>).decode(raw[1]));
       return { kind: arm.armName, ...fields } as unknown as TValue;
     },

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

@@ -1,5 +1,6 @@
 import {
-  decodeDocumentPayload,
+  declaresRole,
+  decodeDocumentPayloadMarked,
   documentPayloadBytes,
   documentPayloadFromBytes,
   encodeDocumentPayload,
@@ -7,8 +8,9 @@ import {
   schemaIdentityOf,
 } from "./document";
 import { resolveDocumentFormatter } from "./document-formatter";
+import type { NotedSlots } from "./codec";
 import type { DocumentPayload } from "./document";
-import { SchemaConflictError } from "./store-format";
+import { SchemaConflictError, schemaIdForEnvelope, writtenOwns } from "./store-format";
 import type {
   AnyCultCacheDocumentDefinition,
   CacheBackingStore,
@@ -19,6 +21,7 @@ import type {
   CultCacheEnvelope,
   CultCacheSchemaCatalogEntry,
   CultCacheStoreRegistration,
+  CultCacheUnreadSlots,
 } from "./types";
 
 type Accessor = (value: unknown) => string | undefined;
@@ -26,7 +29,7 @@ type Accessor = (value: unknown) => string | undefined;
 // A registered definition reads and writes its documents through the owner, on payloads the cache has cloned.
 type RegisteredFormatter = {
   encode(value: unknown): DocumentPayload;
-  decode(payload: DocumentPayload): unknown;
+  decode(payload: DocumentPayload): { value: unknown; unreadSlots?: NotedSlots };
 };
 
 type RegisteredDefinition = {
@@ -46,8 +49,13 @@ type EntryLookups = {
 };
 
 type HydratedEntry = CultCacheEnvelope & {
+  catalogEntry: NonNullable<CultCacheEnvelope["catalogEntry"]>;
   value: unknown;
   lookups: EntryLookups;
+  // What the payload decode read past: set when the record was admitted, and it makes the record read-only unless explained.
+  unreadSlots?: CultCacheUnreadSlots;
+  // The schema id the record arrived under, before it was admitted under its reader's: what an unread-slots refusal names.
+  storedSchemaId?: string;
 };
 
 // Everything a pull replaces. Built whole, then swapped in with one assignment.
@@ -62,6 +70,17 @@ type HydratedState = {
   // delete of that global removes it from the home store. Remove once no store holds a global under
   // a key other than GLOBAL_KEY.
   readonly legacyGlobals: Map<string, CultCacheEnvelope>;
+  // The records the last pull found that no registered type claims. Derived from the pull and replaced with the state; it
+  // decides nothing but the refusal of a write or a removal at its keys.
+  readonly foreign: CultCacheForeignRecord[];
+};
+
+/** A record a store carries that no registered type claims: the cache does not serve it, keeps its bytes, and refuses a write or a removal at its key. */
+export type CultCacheForeignRecord = {
+  readonly key: string;
+  readonly schemaId: string;
+  readonly schemaName: string;
+  readonly storedAt: string;
 };
 
 // Lookups for every held record of one type under candidate accessors, derived before anything is installed.
@@ -71,6 +90,20 @@ type DerivedTypeLookups = {
   readonly indexMaps: Map<string, Map<string, string>>;
 };
 
+// The consent a compatible-id declaration gives (cultlib-gaps:ruling:slot-mark-consent): a mark is explained only when the record
+// arrived under an id other than the reader's own that the reader lists compatible, it is at
+// depth 0 and the schema comparison of the catalog entry the record arrived with against the reader's own reported the slots it
+// carries as ignored, so its slot count is at most the highest ignored slot plus one. A record written or put through the cache
+// arrives under the reader's own entry, which ignores nothing, so no mark of it is explained.
+function explainedBy(noted: NotedSlots, reader: CultCacheSchemaCatalogEntry, arrivedId: string, arrived: CultCacheSchemaCatalogEntry | undefined): boolean {
+  if (arrivedId === reader.schemaId || !(reader.compatibleSchemaIds ?? []).includes(arrivedId)) {
+    return false;
+  }
+  const declared = new Set((reader.members ?? []).map((member) => member.slot));
+  const ignored = (arrived?.members ?? []).map((member) => member.slot).filter((slot) => !declared.has(slot));
+  return noted.depth0Only && noted.slotCount <= Math.max(-1, ...ignored) + 1;
+}
+
 function emptyHydratedState(): HydratedState {
   return {
     entries: new Map(),
@@ -79,6 +112,7 @@ function emptyHydratedState(): HydratedState {
     indexToKeyMaps: new Map(),
     globalKeys: new Map(),
     legacyGlobals: new Map(),
+    foreign: [],
   };
 }
 
@@ -224,7 +258,7 @@ export class CultCache {
     return this.#serial(() => {
       const registered = this.#requireDefinition(definition);
       const nameAccessor = this.#compileAccessor(definition.type, "name", accessor);
-      const derived = this.#deriveTypeLookups(definition.type, nameAccessor, registered.indexAccessors);
+      const derived = this.#deriveTypeLookups(definition.type, registered.catalogEntry.schemaName, nameAccessor, registered.indexAccessors);
       this.#installAccessors(registered, nameAccessor, registered.indexAccessors, derived);
       return definition;
     });
@@ -240,10 +274,14 @@ export class CultCache {
         throw new Error(`CultCache index names for type "${definition.type}" must be non-empty.`);
       }
 
+      if (declaresRole(definition, indexName)) {
+        throw new Error(`Index "${indexName}" of ${definition.type} is declared as a role; a role is never a unique index.`);
+      }
+
       const registered = this.#requireDefinition(definition);
       const indexAccessors = new Map(registered.indexAccessors);
       indexAccessors.set(indexName, this.#compileAccessor(definition.type, `index "${indexName}"`, accessor));
-      const derived = this.#deriveTypeLookups(definition.type, registered.nameAccessor, indexAccessors);
+      const derived = this.#deriveTypeLookups(definition.type, registered.catalogEntry.schemaName, registered.nameAccessor, indexAccessors);
       this.#installAccessors(registered, registered.nameAccessor, indexAccessors, derived);
       return definition;
     });
@@ -274,11 +312,14 @@ export class CultCache {
         for (const entry of entries) {
           const registered = this.#resolveDefinitionForEnvelope(entry);
           if (!registered) {
-            throw new Error(
-              entry.schemaId
-                ? `No schema is registered for persisted schema id "${entry.schemaId}".`
-                : `No schema is registered for persisted document type "${entry.type}".`,
-            );
+            // A store may hold what this cache has no type for; it is carried, not served, and not a reason to refuse the load.
+            next.foreign.push({
+              key: entry.key,
+              schemaId: schemaIdForEnvelope(entry),
+              schemaName: entry.catalogEntry?.schemaName ?? entry.type,
+              storedAt: entry.storedAt,
+            });
+            continue;
           }
 
           const type = registered.definition.type;
@@ -291,7 +332,7 @@ export class CultCache {
           }
 
           const payload = this.#cloneBytes(entry.payload);
-          const value = registered.formatter.decode(payload);
+          const { value, unreadSlots } = registered.formatter.decode(payload);
           let admitted: CultCacheEnvelope = { ...entry, type, payload };
           if (registered.global) {
             const persistedKey = persistedGlobalKeys.get(type);
@@ -306,11 +347,38 @@ export class CultCache {
               admitted = { ...admitted, key: CultCache.GLOBAL_KEY };
             }
           }
-          const hydrated = this.#admitEntry(next, registered, admitted, value);
+          const hydrated = this.#admitEntry(next, registered, admitted, value, unreadSlots);
+          const other = this.#heldUnderOtherType(next, type, hydrated.key);
+          if (other !== undefined) {
+            throw new Error(`Record ${hydrated.key} is held by two stores, as type "${other.type}" and as type "${type}".`);
+          }
           this.#installEntry(next, registered, hydrated);
         }
       }
 
+      const foreignByKey = new Map<string, string>();
+      for (const record of next.foreign) {
+        const first = foreignByKey.get(record.key);
+        if (first !== undefined) {
+          throw new Error(`Record ${record.key} is held by two stores, as schema "${first}" and as schema "${record.schemaName}".`);
+        }
+        foreignByKey.set(record.key, record.schemaName);
+        const other = [...this.#definitions.keys()].map((type) => next.entries.get(this.#entryId(type, record.key))).find((held) => held !== undefined);
+        if (other !== undefined) {
+          throw new Error(`Record ${record.key} is held by two stores, as type "${other.type}" and as schema "${record.schemaName}".`);
+        }
+      }
+
+      // Judged whole, once: the refusal names the least violation of the state this load would leave, whatever the
+      // order of the stores and of the entries in them.
+      refuseLeastIndexSharing(function* () {
+        for (const entry of next.entries.values()) {
+          for (const [alias, value] of entry.lookups.indexes) {
+            yield { type: entry.type, schemaName: entry.catalogEntry.schemaName, alias, value, key: entry.key };
+          }
+        }
+      }());
+
       this.#hydrated = next;
     });
   }
@@ -418,6 +486,7 @@ export class CultCache {
     return key ? this.get(definition, key) : undefined;
   }
 
+  // A unique index: one key per non-blank value. A roles alias is never indexed and answers undefined.
   getKeyByIndex<TDefinition extends AnyCultCacheDocumentDefinition>(
     definition: TDefinition,
     indexName: string,
@@ -469,10 +538,9 @@ export class CultCache {
       if (!envelope.storedAt || envelope.storedAt.trim().length === 0) {
         throw new Error(`CultCache envelope storedAt for type "${definition.type}" must be non-empty.`);
       }
-      this.#requireGlobalKey(registered, envelope.key);
 
       const payload = this.#cloneBytes(envelope.payload);
-      const parsed = registered.formatter.decode(payload) as CultCacheDocumentValue<TDefinition>;
+      const { value: parsed, unreadSlots } = registered.formatter.decode(payload) as { value: CultCacheDocumentValue<TDefinition>; unreadSlots?: NotedSlots };
       const entry: CultCacheEnvelope = {
         key: envelope.key,
         type: envelope.type,
@@ -483,7 +551,7 @@ export class CultCache {
         schemaId: registered.catalogEntry.schemaId,
         catalogEntry: registered.catalogEntry,
       };
-      await this.#writeNow(registered, entry, parsed);
+      await this.#writeNow(registered, entry, parsed, unreadSlots);
       return parsed;
     });
   }
@@ -536,6 +604,34 @@ export class CultCache {
     });
   }
 
+  /** What the record's payload carried past this build's declared slots, or undefined: the held record is read-only unless `explained`. */
+  unreadSlots(definition: AnyCultCacheDocumentDefinition, key: string): CultCacheUnreadSlots | undefined {
+    return this.#hydrated.entries.get(this.#entryId(this.#requireDefinition(definition).definition.type, key))?.unreadSlots;
+  }
+
+  /**
+   * Whether a write of the record's own type at the key would be let through: it asks the judge #writeNow asks, of the record the
+   * cache holds (a key a store carries foreign, a record of another type the write does not own or cannot replace, a global at
+   * another key, a record carrying unread slots nothing consents to). It answers the WRITE form. A removal asks the judge's
+   * removal form and differs in two states: an owner's `delete` of a record held in another store than its own home succeeds
+   * where this is false (a write would push to the wrong store), and `delete` of a global type at a key other than __global__ is
+   * the plain false of an unheld key where this is false. Live and advisory: the write or removal still decides.
+   */
+  isWritable(definition: AnyCultCacheDocumentDefinition, key: string): boolean {
+    const registered = this.#requireDefinition(definition);
+    try {
+      this.#judge(registered, key, this.#probe(registered, key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // What the last pull found that no registered type claims, by key ordinal. A later registration claims a record at the next pull.
+  foreignRecords(): readonly CultCacheForeignRecord[] {
+    return [...this.#hydrated.foreign].sort((left, right) => compareOrdinal(left.key, right.key));
+  }
+
   snapshot(): CultCacheEnvelope[] {
     return [...this.#hydrated.entries.values()].map((entry) => this.#toEnvelope(entry));
   }
@@ -579,7 +675,7 @@ export class CultCache {
     if (existingBySchemaName && existingBySchemaName !== registered) {
       throw refuse(existingBySchemaName, registered.catalogEntry, `schema name "${registered.catalogEntry.schemaName}"`);
     }
-    const derived = this.#deriveTypeLookups(definition.type, nameAccessor, indexAccessors);
+    const derived = this.#deriveTypeLookups(definition.type, registered.catalogEntry.schemaName, nameAccessor, indexAccessors);
 
     // Every check and accessor has run; install.
     this.#definitions.set(definition.type, registered);
@@ -626,9 +722,8 @@ export class CultCache {
     value: CultCacheDocumentValue<TDefinition>,
   ): Promise<CultCacheDocumentValue<TDefinition>> {
     const registered = this.#requireDefinition(definition);
-    this.#requireGlobalKey(registered, key);
     const payload = registered.formatter.encode(value);
-    const parsed = registered.formatter.decode(payload) as CultCacheDocumentValue<TDefinition>;
+    const { value: parsed, unreadSlots } = registered.formatter.decode(payload) as { value: CultCacheDocumentValue<TDefinition>; unreadSlots?: NotedSlots };
     const entry: CultCacheEnvelope = {
       key,
       type: definition.type,
@@ -637,24 +732,150 @@ export class CultCache {
       schemaId: registered.catalogEntry.schemaId,
       catalogEntry: registered.catalogEntry,
     };
-    await this.#writeNow(registered, entry, parsed);
+    await this.#writeNow(registered, entry, parsed, unreadSlots);
     return parsed;
   }
 
   // Validates the whole write (home, global singleton, name and index accessors) before the store
   // is touched; once the store accepts, applying to the cache has no fallible step.
-  async #writeNow(registered: RegisteredDefinition, entry: CultCacheEnvelope, value: unknown): Promise<void> {
+  async #writeNow(registered: RegisteredDefinition, entry: CultCacheEnvelope, value: unknown, unreadSlots?: NotedSlots): Promise<void> {
     const home = this.#homeStore(entry.type);
-    const hydrated = this.#admitEntry(this.#hydrated, registered, entry, value);
+    const retyped = this.#judge(registered, entry.key, entry);
+    const hydrated = this.#admitEntry(this.#hydrated, registered, entry, value, unreadSlots);
+    this.#refuseIndexSharing(this.#hydrated, entry.type, registered.catalogEntry.schemaName, entry.key, hydrated.lookups);
     const legacy = this.#hydrated.legacyGlobals.get(entry.type);
     await home?.push(entry);
     if (home && legacy) {
       await this.#retireLegacyGlobal(home, legacy, entry);
     }
     this.#hydrated.legacyGlobals.delete(entry.type);
+    if (retyped !== undefined) {
+      // The record the write restamped (it owns the held id) is the same record: one key, one held type.
+      this.#removeEntry(this.#hydrated, this.#definitions.get(retyped.type)!, retyped);
+    }
     this.#installEntry(this.#hydrated, registered, hydrated);
   }
 
+  // An envelope of the definition's type at the key, carrying nothing: what the judge asks about a write or a removal by that type.
+  #probe(registered: RegisteredDefinition, key: string): CultCacheEnvelope {
+    return {
+      key, type: registered.definition.type, payload: documentPayloadFromBytes(new Uint8Array(0)), storedAt: "",
+      schemaId: registered.catalogEntry.schemaId, catalogEntry: registered.catalogEntry,
+    };
+  }
+
+  // The one judge of whether a key may be written (a written envelope) or removed (none), before any store is touched: it throws the
+  // refusal, and #writeNow, #deleteNow and isWritable all ask it, so the query cannot disagree with the write. For a write it
+  // returns the held record of another type that the write owns and so restamps, if any. A refusal names keys and schemas,
+  // never a payload or a slot value.
+  #judge(registered: RegisteredDefinition, key: string, written?: CultCacheEnvelope): HydratedEntry | undefined {
+    const type = registered.definition.type;
+    const held = this.#hydrated.entries.get(this.#entryId(type, key));
+    if (written === undefined) {
+      // A removal is by key: the record it removes is the one held at the key, of this type or of another type whose schema id
+      // this type owns (the record a write of this type would replace). A held record of a type it does not own is refused.
+      this.#refuseForeignKey(key, type, "removed");
+      this.#refuseUnread(held);
+      if (held !== undefined) {
+        return undefined;
+      }
+      const other = this.#heldUnderOtherType(this.#hydrated, type, key);
+      if (other === undefined) {
+        return undefined;
+      }
+      if (!writtenOwns(this.#probe(registered, key), schemaIdForEnvelope(other))) {
+        throw new SchemaConflictError(
+          registered.catalogEntry.schemaId,
+          [other.type, type],
+          key,
+          `CultCache holds record "${key}" as type "${other.type}", so type "${type}" cannot remove it.`,
+        );
+      }
+      this.#refuseUnread(other);
+      return other;
+    }
+    this.#requireGlobalKey(registered, key);
+    const retyped = this.#refuseRetype(written);
+    this.#refuseUnread(held);
+    this.#refuseUnread(retyped);
+    if (retyped !== undefined && this.#homeStore(retyped.type) !== this.#homeStore(type)) {
+      // The write owns the held record's id and would replace it, but the held record is in another store; the push
+      // reaches only this type's home, so the old record would stay in its own file and load as a second holder.
+      throw new SchemaConflictError(
+        schemaIdForEnvelope(written),
+        [retyped.type, type],
+        key,
+        `CultCache holds record "${key}" as type "${retyped.type}" in another store than the home of type "${type}", so the rename cannot replace it; remove the record first.`,
+      );
+    }
+    return retyped;
+  }
+
+  // The one refusal of a record held read-only for the slots its payload carries past this build's: a write or a removal of
+  // its key. It names the type and the counts, never a slot value. A mark that is explained (see #admitEntry) is consented to.
+  #unreadRefusal(held: HydratedEntry | undefined): SchemaConflictError | undefined {
+    const unread = held?.unreadSlots;
+    if (held === undefined || unread === undefined || unread.explained) {
+      return undefined;
+    }
+    return new SchemaConflictError(
+      held.storedSchemaId ?? held.schemaId ?? held.type,
+      [held.catalogEntry.schemaName],
+      held.key,
+      `${held.catalogEntry.schemaName} record ${held.key} is read-only: ${unread.typeName} was read with ${unread.slotCount} slots where this build declares ${unread.declaredCount} ` +
+        `(${unread.occurrences} object(s) in the record). Writing it would drop data a newer writer stored; read it with types that declare those slots, or write it from that build.`,
+      unread,
+    );
+  }
+
+  #refuseUnread(held: HydratedEntry | undefined): void {
+    const refusal = this.#unreadRefusal(held);
+    if (refusal !== undefined) {
+      throw refusal;
+    }
+  }
+
+  // The one key-identity judge of the cache: may this write land at its key, given what the cache holds there under
+  // every registered type and the keys its stores carry foreign. The store judges the file with the same predicate
+  // (writtenOwns); this judges the cache, which a store-less cache has no other judge for. Returns the held record of
+  // another type the write owns and so replaces, if any. A refusal names the key and schemas, never a payload.
+  #refuseRetype(entry: CultCacheEnvelope): HydratedEntry | undefined {
+    this.#refuseForeignKey(entry.key, entry.type, "written");
+    const held = this.#heldUnderOtherType(this.#hydrated, entry.type, entry.key);
+    if (held === undefined || writtenOwns(entry, schemaIdForEnvelope(held))) {
+      return held;
+    }
+    throw new SchemaConflictError(
+      schemaIdForEnvelope(entry),
+      [held.type, entry.type],
+      entry.key,
+      `CultCache holds record "${entry.key}" as type "${held.type}", so type "${entry.type}" cannot be written under the same key; remove the record first.`,
+    );
+  }
+
+  #refuseForeignKey(key: string, type: string, what: "written" | "removed"): void {
+    const foreign = this.#hydrated.foreign.find((record) => record.key === key);
+    if (foreign !== undefined) {
+      throw new SchemaConflictError(
+        foreign.schemaId,
+        [foreign.schemaName],
+        key,
+        `CultCache store carries record "${key}" as schema "${foreign.schemaName}" (${foreign.schemaId}), which no registered type claims, so type "${type}" cannot be ${what} at that key.`,
+      );
+    }
+  }
+
+  // The record another registered type holds at the key, if any.
+  #heldUnderOtherType(state: HydratedState, type: string, key: string): HydratedEntry | undefined {
+    for (const other of this.#definitions.keys()) {
+      const held = other === type ? undefined : state.entries.get(this.#entryId(other, key));
+      if (held !== undefined) {
+        return held;
+      }
+    }
+    return undefined;
+  }
+
   // The first write of a global loaded from a legacy key removes that record in the same write. If the
   // removal fails, the new record is taken back out, so the store keeps only the legacy record.
   async #retireLegacyGlobal(home: CacheBackingStore, legacy: CultCacheEnvelope, written: CultCacheEnvelope): Promise<void> {
@@ -671,15 +892,20 @@ export class CultCache {
     key: string,
   ): Promise<boolean> {
     const registered = this.#requireDefinition(definition);
-    const entry = this.#hydrated.entries.get(this.#entryId(definition.type, key));
+    // variants:ruling:unheld-removal-refused-at-commit: a key a store carries foreign is refused, a key held by nobody is the
+    // existing false; a key held as another type is removed by an owner of its id and refused to any other type.
+    // Removal is by key, in one store call: the record held at the key of this type, else the one of another type this type owns.
+    const owned = this.#judge(registered, key);
+    const entry = this.#hydrated.entries.get(this.#entryId(definition.type, key)) ?? owned;
     if (!entry) {
       return false;
     }
 
-    const home = this.#homeStore(definition.type);
-    await home?.delete(this.#hydrated.legacyGlobals.get(definition.type) ?? this.#toEnvelope(entry));
-    this.#hydrated.legacyGlobals.delete(definition.type);
-    this.#removeEntry(this.#hydrated, registered, entry);
+    // The cache drops the record only once the store has removed it.
+    const home = this.#homeStore(entry.type);
+    await home?.delete(this.#hydrated.legacyGlobals.get(entry.type) ?? this.#toEnvelope(entry));
+    this.#hydrated.legacyGlobals.delete(entry.type);
+    this.#removeEntry(this.#hydrated, this.#definitions.get(entry.type)!, entry);
     return true;
   }
 
@@ -706,7 +932,7 @@ export class CultCache {
 
     return {
       encode: (value: unknown) => this.#cloneBytes(encodeDocumentPayload(definition, value)),
-      decode: (payload: DocumentPayload) => decodeDocumentPayload(definition, this.#cloneBytes(payload)),
+      decode: (payload: DocumentPayload) => decodeDocumentPayloadMarked(definition, this.#cloneBytes(payload)),
     };
   }
 
@@ -795,11 +1021,13 @@ export class CultCache {
 
     switch (typeof value) {
       case "string":
-        return value;
-      case "number":
+        return isBlankIndexText(value) ? undefined : value;
       case "boolean":
+        return value ? "True" : "False";
       case "bigint":
-        return String(value);
+        return value.toString();
+      case "number":
+        return canonicalNumberText(value);
       default:
         throw new Error(`CultCache ${label} accessor for type "${type}" produced a non-scalar value.`);
     }
@@ -884,6 +1112,7 @@ export class CultCache {
     registered: RegisteredDefinition,
     entry: CultCacheEnvelope,
     value: unknown,
+    noted?: NotedSlots,
   ): HydratedEntry {
     if (registered.global) {
       const currentGlobalKey = state.globalKeys.get(entry.type);
@@ -894,6 +1123,7 @@ export class CultCache {
       }
     }
 
+    const lookups = this.#lookupsFor(registered.nameAccessor, registered.indexAccessors, value);
     return {
       ...entry,
       payload: this.#cloneBytes(entry.payload),
@@ -902,10 +1132,24 @@ export class CultCache {
       schemaId: registered.catalogEntry.schemaId,
       catalogEntry: registered.catalogEntry,
       value,
-      lookups: this.#lookupsFor(registered.nameAccessor, registered.indexAccessors, value),
+      lookups,
+      storedSchemaId: entry.schemaId ?? entry.type,
+      ...(noted ? { unreadSlots: { ...noted, explained: explainedBy(noted, registered.catalogEntry, entry.schemaId ?? entry.type, entry.catalogEntry) } } : {}),
     };
   }
 
+  // The one index rule (variants:ruling:unique-indexes): within one type and one unique alias, no two records hold one
+  // non-blank value. The held key at the landing record's own key is its previous self and keeps its value. The message
+  // names both keys, ordinal, and the alias, never the value.
+  #refuseIndexSharing(state: HydratedState, type: string, schemaName: string, key: string, lookups: EntryLookups): void {
+    for (const alias of [...lookups.indexes.keys()].sort(compareOrdinal)) {
+      const held = state.indexToKeyMaps.get(this.#indexId(type, alias))?.get(lookups.indexes.get(alias)!);
+      if (held !== undefined && held !== key) {
+        throw indexSharingRefusal(held, key, schemaName, alias);
+      }
+    }
+  }
+
   // Infallible half of admission: replaces any held record at the same key and installs the admitted one.
   #installEntry(state: HydratedState, registered: RegisteredDefinition, hydrated: HydratedEntry): void {
     const entryId = this.#entryId(hydrated.type, hydrated.key);
@@ -966,6 +1210,7 @@ export class CultCache {
   // Runs the candidate accessors over every held record of the type into local maps.
   #deriveTypeLookups(
     type: string,
+    schemaName: string,
     nameAccessor: Accessor | undefined,
     indexAccessors: ReadonlyMap<string, Accessor>,
   ): DerivedTypeLookups {
@@ -983,10 +1228,18 @@ export class CultCache {
         nameMap?.set(lookups.name, entry.key);
       }
       for (const [indexName, indexValue] of lookups.indexes) {
-        indexMaps.get(indexName)?.set(indexValue, entry.key);
+        const map = indexMaps.get(indexName)!;
+        if (!map.has(indexValue)) map.set(indexValue, entry.key);
       }
     }
 
+    // Judged whole, by the same judge as a load: the least violation of the state the registration would leave.
+    refuseLeastIndexSharing(function* () {
+      for (const [entry, lookups] of entryLookups) {
+        for (const [alias, value] of lookups.indexes) yield { type, schemaName, alias, value, key: entry.key };
+      }
+    }());
+
     return { entryLookups, nameMap, indexMaps };
   }
 
@@ -1057,3 +1310,70 @@ export class CultCache {
     return documentPayloadFromBytes(new Uint8Array(documentPayloadBytes(payload)));
   }
 }
+
+function compareOrdinal(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// The whole-state judge (variants:question:unique-index-refusal-pair-rule): over every (type, alias, value) held at two
+// or more distinct keys, throws for the one least by (alias, least key, second-least key, schema name), each compared by
+// UTF-16 code unit. A function of the state, never of the order the rows arrive in.
+function refuseLeastIndexSharing(rows: Iterable<{ type: string; schemaName: string; alias: string; value: string; key: string }>): void {
+  const groups = new Map<string, { schemaName: string; alias: string; keys: string[] }>();
+  for (const { type, schemaName, alias, value, key } of rows) {
+    const id = JSON.stringify([type, alias, value]);
+    const group = groups.get(id);
+    if (group) group.keys.push(key);
+    else groups.set(id, { schemaName, alias, keys: [key] });
+  }
+  let least: { schemaName: string; alias: string; first: string; second: string } | undefined;
+  for (const { schemaName, alias, keys } of groups.values()) {
+    if (keys.length < 2) continue;
+    keys.sort(compareOrdinal);
+    const candidate = { schemaName, alias, first: keys[0], second: keys[1] };
+    if (!least || compareLeast(candidate, least) < 0) least = candidate;
+  }
+  if (least) throw indexSharingRefusal(least.first, least.second, least.schemaName, least.alias);
+}
+
+function compareLeast(
+  a: { schemaName: string; alias: string; first: string; second: string },
+  b: { schemaName: string; alias: string; first: string; second: string },
+): number {
+  return compareOrdinal(a.alias, b.alias) || compareOrdinal(a.first, b.first) || compareOrdinal(a.second, b.second) || compareOrdinal(a.schemaName, b.schemaName);
+}
+
+function indexSharingRefusal(keyA: string, keyB: string, schemaName: string, alias: string): Error {
+  const [first, second] = compareOrdinal(keyA, keyB) <= 0 ? [keyA, keyB] : [keyB, keyA];
+  return new Error(`Records ${first} and ${second} (${schemaName}) both hold unique index '${alias}'; an index value names one record.`);
+}
+
+// Blank is no value: empty or only C# White_Space characters. Not JavaScript's \s, which counts U+FEFF and omits U+0085.
+const BLANK_INDEX_TEXT = /^[\t-\r \u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*$/;
+
+function isBlankIndexText(value: string): boolean {
+  return BLANK_INDEX_TEXT.test(value);
+}
+
+// The canonical text of a number, as C# RenderCanonicalNumber: integers as their digits (-0 is 0), a non-integral finite
+// double as its exact decimal expansion, NaN and infinities as no value.
+function canonicalNumberText(value: number): string | undefined {
+  if (!Number.isFinite(value)) {
+    return undefined;
+  }
+  if (Number.isInteger(value)) {
+    return BigInt(value).toString();
+  }
+
+  // value = mantissa * 2^exponent with exponent < 0, so value = mantissa * 5^k / 10^k for k = -exponent.
+  const view = new DataView(new ArrayBuffer(8));
+  view.setFloat64(0, value);
+  const bits = view.getBigUint64(0);
+  const biasedExponent = Number((bits >> 52n) & 0x7ffn);
+  const fraction = bits & 0xfffffffffffffn;
+  const mantissa = biasedExponent === 0 ? fraction : fraction | (1n << 52n);
+  const k = -((biasedExponent === 0 ? 1 : biasedExponent) - 1075);
+  const digits = (mantissa * 5n ** BigInt(k)).toString().padStart(k + 1, "0");
+  const text = `${digits.slice(0, digits.length - k)}.${digits.slice(digits.length - k)}`.replace(/0+$/, "").replace(/\.$/, "");
+  return value < 0 ? `-${text}` : text;
+}

packages/cultcache-ts/src/document-formatter.ts

@@ -1,7 +1,7 @@
 import { decode, encode } from "@msgpack/msgpack";
 
 import { MAX_PAYLOAD_DEPTH } from "./payload-depth";
-import type { SlotsCodec } from "./codec";
+import { decodeNoting, type NotedSlots, type SlotsCodec } from "./codec";
 import type { AnyCultCacheDocumentDefinition, CultCacheDocumentFormatter } from "./types";
 import { readWire, writeWire } from "./wire";
 
@@ -16,6 +16,13 @@ export function resolveDocumentFormatter(definition: AnyCultCacheDocumentDefinit
   return definition.formatter ?? (definition.codec ? codecFormatter(definition.codec) : plainDocumentFormatter);
 }
 
+// The one decode of a document's bytes, with the slots it read past. A plain formatter or a user formatter has no slot codec
+// and carries everything, so it notes nothing.
+export function decodeMarked(definition: AnyCultCacheDocumentDefinition, bytes: Uint8Array): { value: unknown; unreadSlots?: NotedSlots } {
+  const formatter = resolveDocumentFormatter(definition);
+  return decodeNoting(() => formatter.decode(bytes));
+}
+
 const plainDocumentFormatter: CultCacheDocumentFormatter<unknown> = {
   // The encoder's own depth refusal (100 by default) is set above the limit, so the payload walk decides.
   encode: (value: unknown) => encode(value, { maxDepth: MAX_PAYLOAD_DEPTH * 2 }),

packages/cultcache-ts/src/document.ts

@@ -1,4 +1,5 @@
-import { resolveDocumentFormatter } from "./document-formatter";
+import type { NotedSlots } from "./codec";
+import { decodeMarked, resolveDocumentFormatter } from "./document-formatter";
 import { checkPayloadDepth } from "./payload-depth";
 import type {
   AnyCultCacheDocumentDefinition,
@@ -32,23 +33,22 @@ export function defineDocumentType<TSchema extends CultCacheSchema>(
     throw new Error(`CultCache document type "${definition.type}" declares an invalid name accessor.`);
   }
 
-  if (Array.isArray(definition.indexes)) {
-    const seen = new Set<string>();
-    for (const index of definition.indexes) {
-      if (!index.name || index.name.trim().length === 0) {
-        throw new Error(`CultCache document type "${definition.type}" declares an index with an empty name.`);
-      }
-      if (seen.has(index.name)) {
-        throw new Error(`CultCache document type "${definition.type}" declares duplicate index "${index.name}".`);
-      }
-      seen.add(index.name);
-    }
-  } else if (definition.indexes) {
-    for (const name of Object.keys(definition.indexes)) {
+  const declared = new Set<string>();
+  for (const [kind, set] of [["index", definition.indexes], ["role", definition.roles]] as const) {
+    const names = new Set<string>();
+    for (const name of Array.isArray(set) ? set.map((entry) => entry.name) : set ? Object.keys(set) : []) {
       if (!name || name.trim().length === 0) {
-        throw new Error(`CultCache document type "${definition.type}" declares an index with an empty name.`);
+        throw new Error(`CultCache document type "${definition.type}" declares ${kind === "index" ? "an index" : "a role"} with an empty name.`);
       }
+      if (names.has(name)) {
+        throw new Error(`CultCache document type "${definition.type}" declares duplicate ${kind} "${name}".`);
+      }
+      if (kind === "role" && declared.has(name)) {
+        throw new Error(`CultCache document type "${definition.type}" declares "${name}" as both an index and a role; an index already names its role.`);
+      }
+      names.add(name);
     }
+    for (const name of names) declared.add(name);
   }
 
   if (definition.members) {
@@ -119,10 +119,20 @@ export function decodeDocumentPayload<TDefinition extends AnyCultCacheDocumentDe
   definition: TDefinition,
   payload: DocumentPayload,
 ): CultCacheDocumentValue<TDefinition> {
+  return decodeDocumentPayloadMarked(definition, payload).value;
+}
+
+// The same read with the slots it read past (cult-cache-ts slot-readonly). The depth check runs first: a payload past the
+// limit is refused, never marked.
+export function decodeDocumentPayloadMarked<TDefinition extends AnyCultCacheDocumentDefinition>(
+  definition: TDefinition,
+  payload: DocumentPayload,
+): { value: CultCacheDocumentValue<TDefinition>; unreadSlots?: NotedSlots } {
   const bytes = documentPayloadBytes(payload);
   if (writesLibraryMessagePack(definition)) checkPayloadDepth(bytes, `document type "${definition.type}" payload`);
-  const decoded = resolveDocumentFormatter(definition).decode(bytes);
-  return definition.schema.parse(decoded) as CultCacheDocumentValue<TDefinition>;
+  const { value: decoded, unreadSlots } = decodeMarked(definition, bytes);
+  const value = definition.schema.parse(decoded) as CultCacheDocumentValue<TDefinition>;
+  return unreadSlots ? { value, unreadSlots } : { value };
 }
 
 // The one writer: the definition's schema first, then its formatter, codec or plain map.
@@ -132,16 +142,25 @@ export function encodeDocumentPayload(definition: AnyCultCacheDocumentDefinition
   return documentPayloadFromBytes(bytes);
 }
 
+// Whether the definition declares `name` as a role alias (either `roles` form).
+export function declaresRole(definition: AnyCultCacheDocumentDefinition, name: string): boolean {
+  const roles = definition.roles;
+  return Array.isArray(roles) ? roles.some((entry) => entry.name === name) : roles ? Object.hasOwn(roles, name) : false;
+}
+
 // The schema members of a document: the ones it declares, else those its codec derives, else none.
 export function resolveDocumentMembers(definition: AnyCultCacheDocumentDefinition): readonly CultCacheSchemaCatalogMember[] {
   if (definition.members || !definition.codec) {
     return definition.members ?? [];
   }
   const codec = definition.codec;
-  const indexAlias = (slotName: string) =>
-    !Array.isArray(definition.indexes) && definition.indexes
-      ? Object.entries(definition.indexes).find(([, accessor]) => accessor === slotName)?.[0] ?? null
-      : null;
+  const indexAlias = (slotName: string) => {
+    for (const set of [definition.indexes, definition.roles]) {
+      const alias = !Array.isArray(set) && set ? Object.entries(set).find(([, accessor]) => accessor === slotName)?.[0] : undefined;
+      if (alias !== undefined) return alias;
+    }
+    return null;
+  };
   return codec.members.map((member, index) => ({
     ...member,
     isName: (definition.name as unknown) === codec.names[index],

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

@@ -7,7 +7,7 @@ import { z } from "zod";
 
 import { documentPayloadBytes, documentPayloadFromBytes } from "./document";
 import { commitStoreFile, withStoreWriteLock } from "./store-file";
-import { STORE_FORMAT_VERSION, SchemaConflictError, type StoreFormat, StoreUnreadableError, isStoreSnapshot, refuseUnreadStoreBytes, requireStoreSlots, requireV1RecordSlots } from "./store-format";
+import { STORE_FORMAT_VERSION, SchemaConflictError, type StoreFormat, StoreUnreadableError, isStoreSnapshot, refuseUnreadStoreBytes, requireStoreSlots, requireV1RecordSlots, schemaIdForEnvelope, writtenOwns } from "./store-format";
 import type {
   CacheBackingStore,
   CultCacheEnvelope,
@@ -47,21 +47,11 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
   }
 
   async pullAll(): Promise<CultCacheEnvelope[]> {
-    // The disk decides the header: a file that is gone or legacy is not marked.
-    this.#format = STORE_FORMAT_VERSION;
+    // A pure read: the disk decides the header, and a legacy file is normalized in memory only. The file is rewritten
+    // as v1 by the next push, delete or flush, which merges what this read returns; opening never replaces bytes the
+    // consumer's codec has not yet accepted.
     const disk = this.#readDisk();
     this.#format = disk.format;
-    if (disk.repairedLegacyPayload) {
-      // The heal decides from its own read, taken under the store lock.
-      await this.#enqueue(async () => {
-        const again = this.#readDisk();
-        this.#format = again.format;
-        if (again.repairedLegacyPayload) {
-          await this.#writeAll([], again.envelopes);
-        }
-      });
-    }
-
     return disk.envelopes;
   }
 
@@ -70,9 +60,8 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
       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),
-      );
+      requireOneTypePerKey(this.filePath, [entry], existing);
+      const filtered = existing.filter((candidate) => candidate.key !== entry.key);
       await this.#writeAll([entry], filtered);
     });
   }
@@ -82,8 +71,10 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
       const disk = this.#readDisk();
       this.#format = disk.format;
       const existing = disk.envelopes;
+      // The record the file stores at the key is the one removed when the removal's schema owns its stored id: the
+      // arrived record's type is its schema's name, which a type of another name does not carry.
       const filtered = existing.filter(
-        (candidate) => !(candidate.type === entry.type && candidate.key === entry.key),
+        (candidate) => !(candidate.key === entry.key && (schemaIdForEnvelope(candidate) === schemaIdForEnvelope(entry) || writtenOwns(entry, schemaIdForEnvelope(candidate)))),
       );
       await this.#writeAll([], filtered);
     });
@@ -113,7 +104,9 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
         this.#format = STORE_FORMAT_VERSION;
       }
 
-      await this.#writeAll(entries, []);
+      requireOneTypePerKey(this.filePath, entries, []);
+      // A key is held once: of same-type entries sharing a key in one batch, the last is kept.
+      await this.#writeAll([...new Map(entries.map((entry) => [entry.key, entry])).values()], []);
     });
   }
 
@@ -147,6 +140,28 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
   }
 }
 
+// A store holds a key once, and the reader refuses a file that holds it twice, so a write that would put a second type under a
+// key (against a record on disk, or within its own batch) is refused before anything is written. Retyping a record is a delete
+// of the old type followed by a put of the new one.
+function requireOneTypePerKey(path: string, supplied: CultCacheEnvelope[], held: CultCacheEnvelope[]): void {
+  const typeByKey = new Map<string, CultCacheEnvelope>();
+  for (const entry of held) {
+    typeByKey.set(entry.key, entry);
+  }
+  for (const entry of supplied) {
+    const prior = typeByKey.get(entry.key);
+    if (prior !== undefined && prior.type !== entry.type && !writtenOwns(entry, schemaIdForEnvelope(prior))) {
+      throw new SchemaConflictError(
+        schemaIdForEnvelope(entry),
+        [prior.type, entry.type],
+        entry.key,
+        `CultCache store ${path} holds record "${entry.key}" as type "${prior.type}", so type "${entry.type}" cannot be written under the same key; remove the record first.`,
+      );
+    }
+    typeByKey.set(entry.key, entry);
+  }
+}
+
 /**
  * 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,
@@ -158,7 +173,7 @@ export class SingleFileMessagePackBackingStore implements CacheBackingStore {
 export function readSingleFileStore(path: string): SingleFileStoreRead {
   const data = readStoreBytes(path);
   if (data === undefined) {
-    return { absent: true, format: STORE_FORMAT_VERSION, envelopes: [], repairedLegacyPayload: false };
+    return { absent: true, format: STORE_FORMAT_VERSION, envelopes: [] };
   }
 
   try {
@@ -214,8 +229,9 @@ type DecodedSnapshot = {
 };
 
 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}`));
+  // A key is held once: a supplied record replaces the arrived record under its key whatever the type.
+  const replaced = new Set(supplied.map((entry) => entry.key));
+  const kept = arrived.filter((entry) => !replaced.has(entry.key));
   const entries = [...kept, ...supplied];
   const catalog = catalogEntriesFor([
     ...kept.map((envelope) => ({ envelope, registered: false })),
@@ -361,10 +377,6 @@ function defaultEntryFor(entry: CultCacheEnvelope): CultCacheSchemaCatalogEntry
   };
 }
 
-function schemaIdForEnvelope(entry: CultCacheEnvelope): string {
-  return entry.schemaId ?? entry.type;
-}
-
 function encodeCatalogEntry(entry: CultCacheSchemaCatalogEntry): unknown[] {
   return [
     entry.schemaId,
@@ -395,8 +407,6 @@ export type SingleFileStoreRead = {
   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"> {
@@ -420,7 +430,7 @@ function decodeStoreFile(data: Uint8Array): Omit<SingleFileStoreRead, "absent">
         storedAt: record.storedAt,
       };
     });
-    return { format: snapshot.format, envelopes, repairedLegacyPayload: false };
+    return { format: snapshot.format, envelopes };
   }
 
   const legacy = decodeLegacyEnvelopeArray(decoded);
@@ -428,19 +438,9 @@ function decodeStoreFile(data: Uint8Array): Omit<SingleFileStoreRead, "absent">
     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 };
+  requireUniqueKeys(legacy);
+  const normalized = legacy.map((entry) => ({ ...entry, payload: normalizePayload(entry.payload) }));
+  return { format: STORE_FORMAT_VERSION, envelopes: envelopeArraySchema.parse(normalized).map((entry) => ({ ...entry, payload: documentPayloadFromBytes(entry.payload) })) as CultCacheEnvelope[] };
 }
 
 function decodeSnapshot(decoded: unknown): DecodedSnapshot | undefined {
@@ -472,9 +472,21 @@ function decodeSnapshot(decoded: unknown): DecodedSnapshot | undefined {
   }
 
   const records = recordsRaw.map(decodeRecord);
+  requireUniqueKeys(records);
   return { format: decoded[0], catalogBySchemaId, records };
 }
 
+// A store holds a key once, whatever the type: a repeat is refused in a v1 snapshot and in a legacy envelope array alike.
+function requireUniqueKeys(records: Array<{ key: string }>): void {
+  const seen = new Set<string>();
+  for (const { key } of records) {
+    if (seen.has(key)) {
+      throw new Error(`CultCache record "${key}" appears more than once.`);
+    }
+    seen.add(key);
+  }
+}
+
 function decodeCatalogEntry(value: unknown): CultCacheSchemaCatalogEntry {
   if (!Array.isArray(value)) {
     throw new Error("CultCache schema catalog entries must be MessagePack arrays.");
@@ -502,12 +514,16 @@ function decodeCatalogEntry(value: unknown): CultCacheSchemaCatalogEntry {
     throw new Error(`CultCache schema catalog entry "${schemaId}" has invalid members.`);
   }
 
+  if (typeof canonicalSchemaJson !== "string") {
+    throw new Error(`CultCache schema catalog entry "${schemaId}" has an invalid canonical schema.`);
+  }
+
   return {
     schemaId,
     schemaName,
     schemaVersion: isNonEmptyString(schemaVersion) ? schemaVersion : `${schemaName}.v1`,
     contentHash: isNonEmptyString(contentHash) ? contentHash : schemaId,
-    canonicalSchemaJson: typeof canonicalSchemaJson === "string" ? canonicalSchemaJson : "",
+    canonicalSchemaJson,
     compatibleSchemaIds,
     members: members.map(decodeCatalogMember),
   };

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

@@ -1,5 +1,7 @@
 import { decode } from "@msgpack/msgpack";
 
+import type { CultCacheEnvelope, CultCacheUnreadSlots } from "./types";
+
 export const STORE_FORMAT_VERSION = "cultcache.store.v1";
 
 /**
@@ -81,13 +83,16 @@ export class SchemaConflictError extends Error {
   readonly schemaId: string;
   readonly schemaNames: string[];
   readonly recordKey: string;
+  /** Set when the refusal is for unread slots; undefined for every other refusal. */
+  readonly unreadSlots?: CultCacheUnreadSlots;
 
-  constructor(schemaId: string, schemaNames: string[], recordKey: string, message?: string) {
+  constructor(schemaId: string, schemaNames: string[], recordKey: string, message?: string, unreadSlots?: CultCacheUnreadSlots) {
     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;
+    this.unreadSlots = unreadSlots;
   }
 }
 
@@ -151,3 +156,19 @@ export function requireStoreSlots(decoded: unknown[]): void {
     throw new Error(`CultCache store has ${decoded.length} top-level slots; this runtime reads ${STORE_SLOTS} (header, schema catalog, records).`);
   }
 }
+
+/** The schema id a record is stored under: the one it carries, else its type. */
+export function schemaIdForEnvelope(entry: CultCacheEnvelope): string {
+  return entry.schemaId ?? entry.type;
+}
+
+/**
+ * As C# WrittenOwns' declared half: the written type owns the stored schema id when its catalog entry carries that id as its own
+ * or lists it compatible, so a type renamed under a stable id restamps the record it already holds. (The C# half that lets an
+ * undeclared older id of the same schema name through when it reads whole is not ported; a same-named type keeps passing.)
+ * The one predicate of the key-identity rule: the store judges the file with it and the cache judges what it holds.
+ */
+export function writtenOwns(written: CultCacheEnvelope, storedId: string): boolean {
+  const entry = written.catalogEntry;
+  return entry !== undefined && (entry.schemaId === storedId || (entry.compatibleSchemaIds ?? []).includes(storedId));
+}

packages/cultcache-ts/src/types.ts

@@ -59,9 +59,21 @@ export interface CultCacheDocumentDefinition<TSchema extends CultCacheSchema = C
   members?: readonly CultCacheSchemaCatalogMember[];
   global?: boolean;
   name?: CultCacheDocumentAccessor<InferCultCacheSchemaValue<TSchema>>;
+  /**
+   * Unique lookup aliases. A non-blank value names one record of the type: a write that would leave two records holding
+   * one value, and a store that already holds two, is refused naming both keys and the alias. Blank values (absent,
+   * empty, or only whitespace) are never indexed. `getByIndex` and `getKeyByIndex` answer from these.
+   */
   indexes?:
     | Readonly<Record<string, CultCacheDocumentAccessor<InferCultCacheSchemaValue<TSchema>>>>
     | readonly CultCacheDocumentIndexDefinition<InferCultCacheSchemaValue<TSchema>>[];
+  /**
+   * Selection and reference aliases: the member's catalog `indexAlias`. A role implies nothing about uniqueness, many
+   * records may share a value, and it is never indexed for lookup. An alias is declared in `indexes` or `roles`, not both.
+   */
+  roles?:
+    | Readonly<Record<string, CultCacheDocumentAccessor<InferCultCacheSchemaValue<TSchema>>>>
+    | readonly CultCacheDocumentIndexDefinition<InferCultCacheSchemaValue<TSchema>>[];
   formatter?: CultCacheDocumentFormatter<InferCultCacheSchemaValue<TSchema>>;
   codec?: SlotsCodec<InferCultCacheSchemaValue<TSchema> & object>;
 }
@@ -87,6 +99,26 @@ export interface CultCacheEnvelope {
   catalogEntry?: CultCacheSchemaCatalogEntry;
 }
 
+/**
+ * What a payload decode found past the slots this build declares, at any depth: the first type read with extra slots, how many
+ * slots it carried against how many it declares, and how many objects in the record did. It holds no slot value, so a refusal
+ * can name it. A record carrying it is read-only unless `explained`.
+ */
+export interface CultCacheUnreadSlots {
+  /** The first type read with extra slots (the unit arm's arm name for a unit arm). */
+  readonly typeName: string;
+  readonly slotCount: number;
+  readonly declaredCount: number;
+  readonly occurrences: number;
+  /** True when every mark sat in the document's own object. */
+  readonly depth0Only: boolean;
+  /**
+   * True only when every mark is at depth 0 and the schema comparison of the id the record was stored under reported every slot
+   * the mark carries (slotCount is at most the highest reported slot plus one): the loss a compatible-id declaration consents to.
+   */
+  readonly explained: boolean;
+}
+
 export interface PushAllOptions {
   soft?: boolean;
 }

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

@@ -14,7 +14,7 @@ import { z } from "zod";
 import { CultCache } from "../src/cult-cache";
 import { inspectCultCacheBytes } from "../src/cult-cache-inspector";
 import { defineDocumentRegistry, defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
-import { SingleFileMessagePackBackingStore, readStoreBytes } from "../src/single-file-messagepack-backing-store";
+import { SingleFileMessagePackBackingStore, readSingleFileStore, readStoreBytes } from "../src/single-file-messagepack-backing-store";
 import { SchemaConflictError, StoreUnreadableError, refuseUnreadStoreBytes } from "../src/store-format";
 import type { AnyCultCacheDocumentDefinition, CacheBackingStore, CultCacheEnvelope, CultCacheSchema } from "../src/types";
 
@@ -143,6 +143,63 @@ test("CultCache supports registry bootstrap, global documents, and lookup by nam
   });
 });
 
+test("a put that would land a second type under a persisted key is refused, the cache and the file are unchanged, and the store reloads", async () => {
+  const alpha = defineDocumentType({ type: "alpha", schema: z.object({ v: z.number() }) });
+  const beta = defineDocumentType({ type: "beta", schema: z.object({ v: z.number() }) });
+  const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-ts-")), "cache.msgpack");
+  const registry = defineDocumentRegistry(alpha, beta);
+  const open = () => CultCache.builder().withRegistry(registry).withGenericStore(new SingleFileMessagePackBackingStore(storePath)).build();
+
+  const cache = open();
+  await cache.put(alpha, "shared", { v: 1 });
+  const before = [...(await readFile(storePath))];
+  await assert.rejects(() => cache.put(beta, "shared", { v: 2 }), SchemaConflictError);
+  assert.deepEqual([...(await readFile(storePath))], before);
+  assert.deepEqual(cache.get(alpha, "shared"), { v: 1 });
+  assert.equal(cache.get(beta, "shared"), undefined);
+
+  const reloaded = open();
+  await reloaded.pullAllBackingStores();
+  assert.deepEqual(reloaded.get(alpha, "shared"), { v: 1 });
+
+  assert.equal(await cache.delete(alpha, "shared"), true);
+  await cache.put(beta, "shared", { v: 2 });
+  const retyped = open();
+  await retyped.pullAllBackingStores();
+  assert.equal(retyped.get(alpha, "shared"), undefined);
+  assert.deepEqual(retyped.get(beta, "shared"), { v: 2 });
+});
+
+test("a put by a type renamed under the stored id, which lists that id compatible, restamps the record; an unrelated type is refused", async () => {
+  const old = defineDocumentType({ type: "ren.old", schema: z.object({ v: z.number() }), schemaId: "ren.id.v1", schemaName: "ren.old" });
+  const renamed = defineDocumentType({
+    type: "ren.new",
+    schema: z.object({ v: z.number() }),
+    schemaId: "ren.id.v2",
+    schemaName: "ren.new",
+    compatibleSchemaIds: ["ren.id.v2", "ren.id.v1"],
+  });
+  const other = defineDocumentType({ type: "ren.other", schema: z.object({ v: z.number() }), schemaId: "ren.id.other", schemaName: "ren.other" });
+  const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-ts-")), "cache.msgpack");
+  const open = (...types: (typeof old)[]) =>
+    types
+      .reduce((builder, type) => builder.withDocumentType(type), CultCache.builder())
+      .withGenericStore(new SingleFileMessagePackBackingStore(storePath))
+      .build();
+
+  await open(old).put(old, "k", { v: 1 });
+  const cache = open(renamed, other as unknown as typeof old);
+  await cache.pullAllBackingStores();
+  assert.deepEqual(cache.get(renamed, "k"), { v: 1 });
+  await assert.rejects(() => cache.put(other, "k", { v: 9 }), SchemaConflictError);
+  await cache.put(renamed, "k", { v: 2 });
+
+  const reloaded = open(renamed);
+  await reloaded.pullAllBackingStores();
+  assert.deepEqual(reloaded.get(renamed, "k"), { v: 2 });
+  assert.equal(readSingleFileStore(storePath).envelopes.filter((envelope) => envelope.key === "k").length, 1);
+});
+
 test("CultCache can register name and index lookups after entries already exist", async () => {
   const noteDocument = defineDocumentType({
     type: "note",
@@ -209,10 +266,10 @@ test("CultCache fails closed on unknown or illegal persisted polymorphic state",
     ]))
     .build();
 
-  await assert.rejects(
-    async () => cacheWithUnknownType.pullAllBackingStores(),
-    /No schema is registered for persisted document type "forbidden"\./,
-  );
+  // A record no registered type claims is carried, not a reason to refuse the load.
+  await cacheWithUnknownType.pullAllBackingStores();
+  assert.deepEqual(cacheWithUnknownType.snapshot(), []);
+  assert.deepEqual(cacheWithUnknownType.foreignRecords().map((record) => [record.key, record.schemaName]), [["mystery", "forbidden"]]);
 
   const cacheWithDuplicateGlobal = CultCache.builder()
     .withDocumentType(settingsDocument)
@@ -504,46 +561,56 @@ test("SingleFileMessagePackBackingStore refuses a record whose schema the catalo
   await assert.rejects(() => cache.pullAllBackingStores(), StoreUnreadableError);
 });
 
-test("SingleFileMessagePackBackingStore heals legacy envelopes whose payload was persisted as an object", async () => {
-  const noteDocument = defineDocumentType({
-    type: "note",
-    schema: z.object({
-      title: z.string(),
-      body: z.string(),
-    }),
-  });
+const legacyNoteType = defineDocumentType({
+  type: "note",
+  schema: z.object({ title: z.string(), body: z.string().optional() }),
+});
 
+// SYNTHETIC pre-v1 file (no real one is known): an envelope array with object payloads.
+async function legacyNoteStore(second: unknown): Promise<{ storePath: string; bytes: Uint8Array }> {
   const storePath = join(await mkdtemp(join(tmpdir(), "cultcache-ts-")), "legacy.msgpack");
-  const envelopePayload = {
-    title: "Hello",
-    body: "world",
-  };
-
-  await writeFile(
-    storePath,
-    encode([
-      {
-        key: "note:hello",
-        type: "note",
-        payload: envelopePayload,
-        storedAt: new Date().toISOString(),
-      },
-    ]),
-  );
+  const bytes = encode([
+    { key: "note:hello", type: "note", payload: { title: "Hello", body: "world" }, storedAt: "2026-10-20T00:00:00Z" },
+    { key: "note:other", type: "note", payload: second, storedAt: "2026-10-20T00:00:00Z" },
+  ]);
+  await writeFile(storePath, bytes);
+  return { storePath, bytes };
+}
 
+test("a codec that refuses a synthetic pre-v1 store's content leaves the file byte-identical", async () => {
+  const { storePath, bytes } = await legacyNoteStore({ title: 42 });
   const cache = CultCache.builder()
-    .withDocumentType(noteDocument)
+    .withDocumentType(legacyNoteType)
+    .withGenericStore(new SingleFileMessagePackBackingStore(storePath))
+    .build();
+
+  await assert.rejects(() => cache.pullAllBackingStores());
+  assert.deepEqual([...(await readFile(storePath))], [...bytes]);
+  assert.deepEqual((await readdir(dirname(storePath))).sort(), ["legacy.msgpack"]);
+});
+
+test("a synthetic pre-v1 store is read untouched and becomes v1 only when the consumer writes, keeping its other entries", async () => {
+  const { storePath, bytes } = await legacyNoteStore({ title: "Other" });
+  const cache = CultCache.builder()
+    .withDocumentType(legacyNoteType)
     .withGenericStore(new SingleFileMessagePackBackingStore(storePath))
     .build();
 
   await cache.pullAllBackingStores();
-  assert.deepEqual(cache.getRequired(noteDocument, "note:hello"), envelopePayload);
+  assert.deepEqual(cache.getRequired(legacyNoteType, "note:hello"), { title: "Hello", body: "world" });
+  assert.deepEqual([...(await readFile(storePath))], [...bytes], "reading does not rewrite the file");
 
-  const rewritten = decode(await readFile(storePath)) as unknown[];
-  assert.equal(rewritten[0], "cultcache.store.v1");
-  const records = rewritten[2] as unknown[][];
-  assert.equal(records.length, 1);
-  assert.ok(records[0]?.[3] instanceof Uint8Array);
+  await cache.put(legacyNoteType, "note:new", { title: "New" });
+  assert.equal((decode(await readFile(storePath)) as unknown[])[0], "cultcache.store.v1");
+
+  const reopened = CultCache.builder()
+    .withDocumentType(legacyNoteType)
+    .withGenericStore(new SingleFileMessagePackBackingStore(storePath))
+    .build();
+  await reopened.pullAllBackingStores();
+  assert.deepEqual(reopened.getRequired(legacyNoteType, "note:hello"), { title: "Hello", body: "world" });
+  assert.deepEqual(reopened.getRequired(legacyNoteType, "note:other"), { title: "Other" });
+  assert.deepEqual(reopened.getRequired(legacyNoteType, "note:new"), { title: "New" });
 });
 
 test("CultCache rejects a second generic backing store", async () => {
@@ -2515,17 +2582,24 @@ test("SingleFileMessagePackBackingStore replaces a file exactly when it reads",
     .filter((line) => line.length > 0 && !line.startsWith("#"))
     .map((line) => line.split(/\s+/u));
   // Every vector in the folder has a manifest row.
-  const listed = rows.map(([vector]) => vector!).filter((vector) => !vector.startsWith("..")).sort();
+  const listed = rows.map(([vector]) => vector!).filter((vector) => !vector.startsWith("..") && !vector.startsWith("@")).sort();
   assert.deepEqual((await readdir(root)).filter((name) => name.endsWith(".bin")).sort(), listed);
   const dir = await mkdtemp(join(tmpdir(), "cultcache-readability-"));
   const seed = await copyVector(dir, join(c2aVectors, "v3-base.msgpack"), "seed.msgpack");
   const envelopes = await new SingleFileMessagePackBackingStore(seed).pullAll();
   for (const [vector, , , typescript] of rows) {
     const reads = typescript === "reads";
-    const bytes = await readFile(join(root, vector));
+    // "@directory": the walker makes an empty directory at the store path; the runtime refuses to open or replace it and leaves it be.
+    const isDirectory = vector === "@directory";
+    const bytes = isDirectory ? Buffer.alloc(0) : await readFile(join(root, vector));
     for (const operation of ["pullAll", "softPushAll", "pushAll", "push", "delete"] as const) {
       const file = join(dir, `${vector.replace(/[^a-z0-9.-]/giu, "_")}.${operation}.msgpack`);
-      await writeFile(file, bytes);
+      if (isDirectory) {
+        assert.equal(typescript, "refuses", "a directory is never a store");
+        await mkdir(file);
+      } else {
+        await writeFile(file, bytes);
+      }
       const store = new SingleFileMessagePackBackingStore(file);
       const run = () =>
         operation === "pullAll"
@@ -2560,6 +2634,10 @@ test("SingleFileMessagePackBackingStore replaces a file exactly when it reads",
         } else {
           assert.ok(!keys.includes(envelopes[0]!.key), `${vector} ${operation}`);
         }
+      } else if (isDirectory) {
+        await assert.rejects(run, (error) => !(error instanceof StoreUnreadableError), `${vector} ${operation}: an I/O failure, not a typed refusal`);
+        assert.ok((await lstat(file)).isDirectory(), `${vector} ${operation} replaced the directory`);
+        assert.deepEqual(await readdir(file), [], `${vector} ${operation} wrote into the directory`);
       } else {
         await assert.rejects(
           run,
@@ -2572,6 +2650,27 @@ test("SingleFileMessagePackBackingStore replaces a file exactly when it reads",
   }
 });
 
+// One key is held once: a push whose type does not own the stored schema id is refused, so the writer cannot emit a store its own
+// reader refuses; one whose type owns it (its own id, or one it lists compatible, as C# WrittenOwns) restamps the record in place.
+test("SingleFileMessagePackBackingStore push asks whether the written type owns the stored id, not what the types are called", async () => {
+  // One cache holds one record per key, so each envelope is made in a cache of its own.
+  const owner = CultCache.builder().withDocumentType(ownsId).build();
+  const lister = CultCache.builder().withDocumentType(listsId).build();
+  await owner.put(ownsId, "k", { name: "owner" });
+  await lister.put(listsId, "k", { name: "lister" });
+  const file = join(await mkdtemp(join(tmpdir(), "cultcache-push-key-")), "store.msgpack");
+  const store = new SingleFileMessagePackBackingStore(file);
+  const idsOf = async () => ((decode(await readFile(file)) as unknown[][])[2] as unknown[][]).map((record) => [record[0], record[1]]);
+
+  await store.push(lister.getRequiredEnvelope(listsId, "k"));
+  await assert.rejects(() => store.push(owner.getRequiredEnvelope(ownsId, "k")), SchemaConflictError);
+  assert.deepEqual(await idsOf(), [["k", "id.lister"]]);
+
+  await store.pushAll([lister.getRequiredEnvelope(listsId, "k")]);
+  await store.push(lister.getRequiredEnvelope(listsId, "k"));
+  assert.equal((await store.pullAll()).length, 1);
+});
+
 // Owner beats lister: a definition that owns an id and one that lists it as compatible register together in either order. A record
 // under the id is the owner's, and a lister's only when nothing owns it; two listers and no owner name no single definition.
 const ownsId = defineDocumentType({ type: "tests.owns", schema: z.object({ name: z.string() }), schemaId: "id.owned", schemaName: "tests.owns" });

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

@@ -24,7 +24,6 @@ const itemDocument = defineDocumentType({
   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);
 

packages/cultcache-ts/test/key-identity-vector.test.ts

@@ -0,0 +1,377 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { copyFile, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+
+import { decode, encode } from "@msgpack/msgpack";
+import { z } from "zod";
+
+import { CultCache } from "../src/cult-cache";
+import { defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
+import { SingleFileMessagePackBackingStore, readSingleFileStore } from "../src/single-file-messagepack-backing-store";
+import { SchemaConflictError } from "../src/store-format";
+import type { AnyCultCacheDocumentDefinition, CultCacheEnvelope } from "../src/types";
+
+// variants:ruling:cache-refuses-retype, write-ownership-by-written-type, unheld-removal-refused-at-commit. The vectors in
+// tests/vectors/key-identity are written by the C# reference (see its README for the rule and the row shapes); this walks
+// every row against the TS cache. A leaf keeps no verdict of its own.
+
+function findVectors(from: string): string {
+  for (let dir = from; ; dir = resolve(dir, "..")) {
+    if (existsSync(join(dir, "tests", "vectors", "key-identity"))) return join(dir, "tests", "vectors", "key-identity");
+    if (resolve(dir, "..") === dir) throw new Error("tests/vectors/key-identity not found above the test.");
+  }
+}
+const vectors = findVectors(__dirname);
+
+// One string slot [0: Text]; the schema ids are the ones C# wrote (README). The type is the schema name, the name a record
+// read back from a store carries as its type (the store's delete matches on it).
+function kiType(type: string, id: string) {
+  const schemaName = `tests.ki_${type}`;
+  return defineDocumentType({
+    type: schemaName,
+    schemaId: `sha256:${id}`,
+    schemaName,
+    schemaVersion: `${schemaName}.v1`,
+    schema: z.object({ text: z.string() }),
+    formatter: {
+      encode: (value: { text: string }) => encode([value.text]),
+      decode: (payload: Uint8Array) => ({ text: (decode(payload) as [string])[0] }),
+    },
+  });
+}
+const types: Record<string, AnyCultCacheDocumentDefinition> = {
+  alpha: kiType("alpha", "b20703a98f49c253898404ab50ba2c630720f0b8a5e1a41614d5650be22799fe"),
+  beta: kiType("beta", "dee4b727cf2ee04e61ab635ff0c5f3dca7345a411dc5f1018e583ab16009cf94"),
+  gamma: kiType("gamma", "fbc26e351e00c9e7185e8de171c7486aba707c229c949f0aae6b889288af5f6d"),
+};
+
+type Op = [string, ...unknown[]];
+type Row = [string, string[], Op[], [[string] | null, [string, string, string][], [string, string][] | null, string[], string[]]];
+
+const compare = (left: string, right: string) => (left < right ? -1 : left > right ? 1 : 0);
+const textOf = (envelope: CultCacheEnvelope) => (decode(documentPayloadBytes(envelope.payload)) as [string])[0];
+const stored = (path: string) => new Map(readSingleFileStore(path).envelopes.map((e) => [e.key, e]));
+const sameRecord = (left: CultCacheEnvelope | undefined, right: CultCacheEnvelope | undefined) =>
+  left !== undefined && right !== undefined && left.schemaId === right.schemaId && left.storedAt === right.storedAt &&
+  Buffer.compare(Buffer.from(documentPayloadBytes(left.payload)), Buffer.from(documentPayloadBytes(right.payload))) === 0;
+
+test("vectors rows.msgpack: every row's refusal, held records, file, foreign list and kept bytes", async () => {
+  const rows = decode(await readFile(join(vectors, "rows.msgpack"))) as Row[];
+  assert.equal(rows.length, 12);
+  let walked = 0;
+  const failures: string[] = [];
+  for (const [label, registered, ops, expect] of rows) {
+    const dir = await mkdtemp(join(tmpdir(), "ki-"));
+    try {
+      const [refusal, held, file, foreign, kept] = expect;
+      let counter = 0;
+      let path: string | undefined;
+      let cache!: CultCache;
+      let before: Map<string, CultCacheEnvelope> | undefined;
+      const attached: string[] = [];
+      const build = (store: string | undefined) => {
+        let builder = CultCache.builder();
+        for (const name of registered) builder = builder.withDocumentType(types[name]!);
+        if (store !== undefined) builder = builder.withGenericStore(new SingleFileMessagePackBackingStore(store));
+        return builder.build();
+      };
+      const fresh = async (name: string) => {
+        const copy = join(dir, `${counter++}-${name}`);
+        await copyFile(join(vectors, name), copy);
+        return copy;
+      };
+
+      let refused: unknown;
+      let failed = false;
+      let beforeBytes: Buffer | undefined;
+      let beforeCache: CultCacheEnvelope[] = [];
+      let beforeAttached: Buffer[] = [];
+      for (const [index, op] of ops.entries()) {
+        const last = index === ops.length - 1;
+        if (last) {
+          beforeCache = cache?.snapshot() ?? [];
+          beforeAttached = await Promise.all(attached.map((copy) => readFile(copy)));
+          beforeBytes = path !== undefined ? await readFile(path) : undefined;
+        }
+        try {
+          switch (op[0]) {
+            case "open": {
+              const arg = op[1] as string | null;
+              path = arg === "memory" ? undefined : arg === null ? join(dir, "fresh.cc") : await fresh(arg);
+              if (path !== undefined && arg !== null) before = stored(path);
+              cache = build(path);
+              await cache.pullAllBackingStores();
+              break;
+            }
+            case "attach": {
+              const copy = await fresh(op[1] as string);
+              attached.push(copy);
+              await cache.addBackingStore(new SingleFileMessagePackBackingStore(copy), ...(op[2] as string[]).map((name) => types[name]!));
+              await cache.pullAllBackingStores();
+              break;
+            }
+            case "reopen":
+              cache = build(path);
+              await cache.pullAllBackingStores();
+              break;
+            case "put":
+              await cache.put(types[op[1] as string]!, op[2] as string, { text: op[3] as string } as never);
+              break;
+            case "delete":
+              await cache.delete(types[op[1] as string]!, op[2] as string);
+              break;
+            default:
+              assert.fail(`${label}: unknown op ${op[0]}`);
+          }
+        } catch (error) {
+          if (!last) throw error;
+          refused = error;
+          failed = true;
+        }
+      }
+
+      if (refusal === null) {
+        assert.equal(failed, false, `${label}: the last op lands (${String(refused)})`);
+      } else {
+        assert.equal(failed, true, `${label}: the last op is refused`);
+        const [key] = refusal;
+        if (label === "key-in-two-stores-refused") {
+          // The key is read out of the refusal as a delimited token: the message opens "Record <key> is held by" and the key
+          // occurs nowhere else in it (not inside a schema name).
+          const message = (refused as Error).message;
+          const named = /^Record (\S+) is held by/u.exec(message);
+          assert.equal(named?.[1], key, `${label}: the refusal opens with the key`);
+          assert.equal(message.split(/[^A-Za-z0-9_.]+/u).filter((token) => token === key).length, 1, `${label}: the key occurs only as a delimited token`);
+          assert.deepEqual(cache.snapshot(), beforeCache, `${label}: the earlier pulled state survives`);
+          assert.deepEqual(await Promise.all(attached.slice(0, beforeAttached.length).map((copy) => readFile(copy))), beforeAttached, `${label}: the attached files are byte-identical`);
+        } else {
+          assert.ok(refused instanceof SchemaConflictError, `${label}: a typed schema conflict, got ${String(refused)}`);
+          assert.equal((refused as SchemaConflictError).recordKey, key, `${label}: names the key`);
+          assert.deepEqual(cache.snapshot(), beforeCache, `${label}: the cache is unchanged`);
+          if (path !== undefined) assert.deepEqual(await readFile(path), beforeBytes, `${label}: the store is byte-identical`);
+        }
+      }
+
+      assert.deepEqual(
+        cache.snapshot()
+          .map((e) => [e.type.replace("tests.ki_", ""), e.key, textOf(e)] as [string, string, string])
+          .sort((l, r) => compare(l[0], r[0]) || compare(l[1], r[1])),
+        held,
+        `${label}: held`,
+      );
+      if (path === undefined) {
+        assert.equal(file, null, `${label}: no store`);
+      } else {
+        assert.deepEqual(
+          [...stored(path).values()]
+            .map((e) => [e.key, e.catalogEntry?.schemaName ?? e.type] as [string, string])
+            .sort((l, r) => compare(l[0], r[0])),
+          file,
+          `${label}: file`,
+        );
+        if (before !== undefined) {
+          const after = stored(path);
+          assert.deepEqual(foreign.filter((key) => sameRecord(before!.get(key), after.get(key))), kept, `${label}: kept`);
+        }
+      }
+      assert.deepEqual(cache.foreignRecords().map((record: { key: string }) => record.key), foreign, `${label}: foreign`);
+      walked++;
+    } catch (error) {
+      failures.push(`${label}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  assert.deepEqual(failures, [], "every row holds its verdict");
+  assert.equal(walked, 12);
+});
+
+// Beyond the vector: what the walker's string-typed rows cannot say.
+const CANARY = "CANARY-ki-77c1";
+const plain = (type: string, schemaId: string, compatibleSchemaIds?: string[]) =>
+  defineDocumentType({ type, schemaId, schemaName: type, schemaVersion: `${type}.v1`, schema: z.object({ v: z.string() }), ...(compatibleSchemaIds ? { compatibleSchemaIds } : {}) });
+
+test("a refusal names the key and schemas and never echoes the written value", async () => {
+  const alpha = plain("cn.alpha", "cn.alpha.v1");
+  const beta = plain("cn.beta", "cn.beta.v1");
+  const cache = CultCache.builder().withDocumentType(alpha).withDocumentType(beta).build();
+  await cache.put(alpha, "k", { v: "first" });
+  await assert.rejects(cache.put(beta, "k", { v: CANARY }), (error: Error) => {
+    assert.ok(error instanceof SchemaConflictError && error.recordKey === "k");
+    assert.ok(!error.message.includes(CANARY));
+    return true;
+  });
+  assert.deepEqual(cache.get(alpha, "k"), { v: "first" });
+  assert.equal(cache.get(beta, "k"), undefined);
+  await assert.rejects(cache.putEnvelope(beta, { key: "k", type: "cn.beta", payload: documentPayloadFromBytes(encode({ v: CANARY })), storedAt: "2026-01-01T00:00:00Z" }), SchemaConflictError);
+  assert.equal(cache.snapshot().length, 1);
+});
+
+test("a type that owns the held record's id replaces it: one record at the key, no second type held", async () => {
+  const old = plain("cn.old", "cn.id.v1");
+  const renamed = plain("cn.new", "cn.id.v2", ["cn.id.v2", "cn.id.v1"]);
+  const cache = CultCache.builder().withDocumentType(old).withDocumentType(renamed).build();
+  await cache.put(old, "k", { v: "a" });
+  await cache.put(renamed, "k", { v: "b" });
+  assert.deepEqual(cache.snapshot().map((e) => [e.type, e.key]), [["cn.new", "k"]]);
+  assert.equal(cache.get(old, "k"), undefined);
+});
+
+test("a store carrying an unregistered record loads, lists it sorted, keeps it through writes of other keys, and a later registration claims it", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ki-"));
+  try {
+    const path = join(dir, "s.cc");
+    await copyFile(join(vectors, "foreign-store.cc"), path);
+    const open = (...names: string[]) => {
+      let builder = CultCache.builder();
+      for (const name of names) builder = builder.withDocumentType(types[name]!);
+      return builder.withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+    };
+    const cache = open("alpha");
+    await cache.pullAllBackingStores();
+    const record = stored(path).get("k")!;
+    assert.deepEqual(cache.foreignRecords(), [
+      { key: "k", schemaId: "sha256:fbc26e351e00c9e7185e8de171c7486aba707c229c949f0aae6b889288af5f6d", schemaName: "tests.ki_gamma", storedAt: record.storedAt },
+    ]);
+    await cache.put(types.alpha!, "z", { text: "z" } as never);
+    await cache.delete(types.alpha!, "j");
+    assert.ok(sameRecord(stored(path).get("k"), record), "the foreign record's stored bytes survive");
+    assert.equal(await cache.delete(types.alpha!, "nobody"), false);
+
+    const claimed = open("alpha", "gamma");
+    await claimed.pullAllBackingStores();
+    assert.deepEqual(claimed.foreignRecords(), []);
+    assert.equal(claimed.snapshot().length, 2);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a foreign key one store carries and another holds under a registered type refuses the load and admits nothing", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ki-"));
+  try {
+    const foreign = join(dir, "foreign.cc");
+    const catalog = join(dir, "catalog.cc");
+    await copyFile(join(vectors, "catalog-store.cc"), catalog);
+    const writer = CultCache.builder().withDocumentType(types.gamma!).withGenericStore(new SingleFileMessagePackBackingStore(foreign)).build();
+    await writer.put(types.gamma!, "qx", { text: "g" } as never);
+    const cache = CultCache.builder().withDocumentType(types.alpha!).build();
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(catalog), types.alpha!);
+    await cache.pullAllBackingStores();
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(foreign));
+    await assert.rejects(cache.pullAllBackingStores(), /held by two stores/u);
+    assert.deepEqual(cache.snapshot().map((e) => e.key), ["qx"], "the earlier pulled state survives");
+    assert.deepEqual(cache.foreignRecords(), []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+// The cache judge answers for what the cache holds whatever the store is: a store that never judges (it only records
+// what it is asked) is asked nothing at a foreign key, and foreign records list by key ordinal.
+test("a foreign key is refused by the cache before any store is asked, and foreign records list sorted", async () => {
+  const calls: string[] = [];
+  const record = (key: string, schemaId: string): CultCacheEnvelope => ({
+    key,
+    type: "unclaimed",
+    schemaId,
+    storedAt: "2026-01-01T00:00:00Z",
+    payload: documentPayloadFromBytes(encode(["x"])),
+  });
+  const store = {
+    pullAll: async () => [record("m", "unclaimed.m.v1"), record("b", "unclaimed.b.v1")],
+    push: async (entry: CultCacheEnvelope) => void calls.push(`push ${entry.key}`),
+    delete: async (entry: CultCacheEnvelope) => void calls.push(`delete ${entry.key}`),
+  };
+  const cache = CultCache.builder().withDocumentType(types.alpha!).withGenericStore(store).build();
+  await cache.pullAllBackingStores();
+  assert.deepEqual(cache.foreignRecords().map((r) => [r.key, r.schemaId, r.schemaName]), [["b", "unclaimed.b.v1", "unclaimed"], ["m", "unclaimed.m.v1", "unclaimed"]]);
+  await assert.rejects(cache.put(types.alpha!, "m", { text: CANARY } as never), (error: Error) => {
+    assert.ok(error instanceof SchemaConflictError && error.recordKey === "m");
+    assert.ok(!error.message.includes(CANARY));
+    return true;
+  });
+  await assert.rejects(cache.delete(types.alpha!, "b"), (error: Error) => error instanceof SchemaConflictError && error.recordKey === "b");
+  assert.equal(await cache.delete(types.alpha!, "nobody"), false);
+  assert.deepEqual(calls, []);
+});
+
+// The store's delete matches the record the file stores by its schema id, not by the type string: a record read back is
+// typed by its schema's name, which a type of another name does not carry.
+test("a delete removes the record the file stores although the type differs from the schema name, and the key retypes across a reload", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ki-"));
+  try {
+    const path = join(dir, "s.cc");
+    const named = (type: string, schemaName: string, schemaId: string) =>
+      defineDocumentType({ type, schemaId, schemaName, schemaVersion: `${schemaName}.v1`, schema: z.object({ v: z.string() }) });
+    const first = named("app.first", "wire.first", "wire.first.v1");
+    const second = named("app.second", "wire.second", "wire.second.v1");
+    const open = () => CultCache.builder().withDocumentType(first).withDocumentType(second).withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+    const writer = open();
+    await writer.put(first, "k", { v: "a" });
+    const reader = open();
+    await reader.pullAllBackingStores();
+    assert.equal(await reader.delete(first, "k"), true);
+    assert.deepEqual([...stored(path).keys()], [], "the record is gone from the file");
+    await reader.put(second, "k", { v: "b" });
+    assert.deepEqual([...stored(path).values()].map((e) => [e.key, e.catalogEntry?.schemaName]), [["k", "wire.second"]]);
+    const again = open();
+    await again.pullAllBackingStores();
+    assert.deepEqual(again.snapshot().map((e) => [e.type, e.key]), [["app.second", "k"]]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("an owned rename whose two types home in different stores is refused, and neither store changes", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ki-"));
+  try {
+    const oldPath = join(dir, "old.cc");
+    const newPath = join(dir, "new.cc");
+    const old = plain("rn.old", "rn.id.v1");
+    const renamed = plain("rn.new", "rn.id.v2", ["rn.id.v2", "rn.id.v1"]);
+    const cache = CultCache.builder().withDocumentType(old).withDocumentType(renamed).build();
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(oldPath), old);
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(newPath), renamed);
+    await cache.put(old, "k", { v: "a" });
+    const before = await readFile(oldPath);
+    await assert.rejects(cache.put(renamed, "k", { v: CANARY }), (error: Error) => {
+      assert.ok(error instanceof SchemaConflictError && error.recordKey === "k");
+      assert.ok(!error.message.includes(CANARY));
+      return true;
+    });
+    assert.deepEqual(await readFile(oldPath), before);
+    assert.equal(existsSync(newPath), false, "the new home was never written");
+    assert.deepEqual(cache.snapshot().map((e) => [e.type, e.key]), [["rn.old", "k"]]);
+    // Same home: the rename replaces.
+    const together = CultCache.builder().withDocumentType(old).withDocumentType(renamed).withGenericStore(new SingleFileMessagePackBackingStore(join(dir, "one.cc"))).build();
+    await together.put(old, "k", { v: "a" });
+    await together.put(renamed, "k", { v: "b" });
+    assert.deepEqual(together.snapshot().map((e) => [e.type, e.key]), [["rn.new", "k"]]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("two stores each carrying an unregistered record at one key refuse the load and admit nothing", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "ki-"));
+  try {
+    const paths = [join(dir, "a.cc"), join(dir, "b.cc")];
+    for (const path of paths) {
+      const writer = CultCache.builder().withDocumentType(types.gamma!).withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+      await writer.put(types.gamma!, "k", { text: "g" } as never);
+    }
+    // Neither store's records are claimed: gamma is not registered here.
+    const cache = CultCache.builder().withDocumentType(types.alpha!).withDocumentType(types.beta!).build();
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(paths[0]!), types.alpha!);
+    await cache.addBackingStore(new SingleFileMessagePackBackingStore(paths[1]!), types.beta!);
+    await assert.rejects(cache.pullAllBackingStores(), /^Error: Record k is held by two stores/u);
+    assert.deepEqual(cache.foreignRecords(), []);
+    assert.deepEqual(cache.snapshot(), []);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

packages/cultcache-ts/test/slot-readonly.test.ts

@@ -0,0 +1,461 @@
+import assert from "node:assert/strict";
+import { copyFile, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { decode, encode } from "@msgpack/msgpack";
+import { z } from "zod";
+
+import { codecs } from "../src";
+import { CultCache } from "../src/cult-cache";
+import { defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
+import { SingleFileMessagePackBackingStore, readSingleFileStore } from "../src/single-file-messagepack-backing-store";
+import { SchemaConflictError, StoreUnreadableError } from "../src/store-format";
+import type { CacheBackingStore, CultCacheEnvelope, CultCacheUnreadSlots } from "../src/types";
+import {
+  type Surface, envelopeOf, golden, hex, memoryStore, read, slotUnitDocument, surfaceCodec, surfaceDeclaringDocument, surfaceDocument, surfaceSchema, vectors,
+} from "./union-surface-fixture";
+
+// cultlib-gaps:cut:slot-readonly-ts. A payload carrying a slot past its reader's declared slots, at any depth, is read, held
+// read-only, and every write or removal of its key is refused before a store is touched. The vectors are written by the C#
+// reference: tests/vectors/union-parity/README.md, "Extra trailing slot" and "Slot stores".
+
+const { slots, string } = codecs;
+const SLOT_VALUE = "extra-slot";
+
+function mark(typeName: string, slotCount: number, declaredCount: number, depth0Only: boolean, explained = false, occurrences = 1): CultCacheUnreadSlots {
+  return { typeName, slotCount, declaredCount, occurrences, depth0Only, explained };
+}
+
+// File, then the mark the README table gives for it.
+const PAYLOAD_ROWS: [string, CultCacheUnreadSlots][] = [
+  ["extra-slot-record.msgpack", mark("UnionSurface", 8, 7, true)],
+  ["extra-slot-nested-record.msgpack", mark("Composition", 3, 2, false)],
+  ["extra-slot-arm.msgpack", mark("Box", 3, 2, false)],
+  ["extra-slot-list-element.msgpack", mark("Text", 3, 2, false)],
+  ["depth-skipped-at-limit.msgpack", mark("UnionSurface", 8, 7, true)],
+];
+
+async function readOnlyFiles(name: string): Promise<string[]> {
+  const rows = decode(await read(name)) as unknown[][];
+  return rows.filter((row) => row[1] === "read-only").map((row) => row[0] as string);
+}
+
+test("the read-only payload vectors are exactly the ones this walker names: four in outcomes, one in bounds", async () => {
+  const listed = [...(await readOnlyFiles("outcomes.msgpack")), ...(await readOnlyFiles("bounds-outcomes.msgpack"))];
+  assert.deepEqual(listed.sort(), PAYLOAD_ROWS.map(([file]) => file).sort());
+});
+
+for (const [file, expected] of PAYLOAD_ROWS) {
+  test(`${file}: read past the extra slot, held read-only with the mark, every write and removal of the key refused`, async () => {
+    const document = surfaceDocument();
+    const entries = [envelopeOf(await read(file))];
+    const before = hex(documentPayloadBytes(entries[0]!.payload));
+    const cache = CultCache.builder().withDocumentType(document).withGenericStore(memoryStore(entries)).build();
+    await cache.pullAllBackingStores();
+
+    assert.deepEqual(cache.get(document, "surface"), golden, "the extra slot is read past");
+    assert.deepEqual(cache.unreadSlots(document, "surface"), expected);
+    assert.equal(cache.isWritable(document, "surface"), false);
+    assert.equal(cache.isWritable(document, "another"), true);
+
+    const refused = (error: unknown) => {
+      assert.ok(error instanceof SchemaConflictError, "a SchemaConflictError");
+      assert.deepEqual(error.unreadSlots, expected);
+      assert.equal(error.recordKey, "surface");
+      assert.ok(error.message.includes(expected.typeName), error.message);
+      assert.ok(error.message.includes(`read with ${expected.slotCount} slots where this build declares ${expected.declaredCount} (${expected.occurrences} object(s)`), error.message);
+      assert.ok(!error.message.includes(SLOT_VALUE), "the refusal never holds a slot value");
+      return true;
+    };
+    await assert.rejects(() => cache.put(document, "surface", golden), refused);
+    await assert.rejects(() => cache.update(document, "surface", (value) => ({ ...value!, version: 4 })), refused);
+    const replacement = envelopeOf(await read("union-surface.msgpack"));
+    await assert.rejects(() => cache.putEnvelope(document, replacement), refused);
+    await assert.rejects(() => cache.delete(document, "surface"), refused);
+    assert.equal(entries.length, 1, "nothing reached the store");
+    assert.equal(hex(documentPayloadBytes(entries[0]!.payload)), before, "the held bytes are untouched");
+    assert.deepEqual(cache.get(document, "surface"), golden, "the record is still held");
+
+    await cache.put(document, "another", golden);
+    assert.equal(entries.length, 2, "another key of the same store writes");
+  });
+}
+
+test("a clean payload and a short one are writable: missing trailing slots keep the defaults and mark nothing", async () => {
+  const document = surfaceDocument();
+  const short = encode([...(decode(await read("union-surface.msgpack")) as unknown[]).slice(0, 6)]);
+  const entries = [envelopeOf(await read("union-surface.msgpack")), { ...envelopeOf(short), key: "short" }];
+  const cache = CultCache.builder().withDocumentType(document).withGenericStore(memoryStore(entries)).build();
+  await cache.pullAllBackingStores();
+  for (const key of ["surface", "short"]) {
+    assert.equal(cache.unreadSlots(document, key), undefined);
+    assert.equal(cache.isWritable(document, key), true);
+  }
+  await cache.put(document, "short", golden);
+});
+
+test("a payload past the nesting limit is refused, never marked", async () => {
+  const entries = [envelopeOf(await read("depth-skipped-past-limit.msgpack"))];
+  const cache = CultCache.builder().withDocumentType(surfaceDocument()).withGenericStore(memoryStore(entries)).build();
+  await assert.rejects(() => cache.pullAllBackingStores(), /nesting|depth/iu);
+});
+
+test("putEnvelope of a payload carrying extra slots lands the bytes and holds the record read-only", async () => {
+  const document = surfaceDocument();
+  const entries: ReturnType<typeof envelopeOf>[] = [];
+  const cache = CultCache.builder().withDocumentType(document).withGenericStore(memoryStore(entries)).build();
+  const marked = envelopeOf(await read("extra-slot-nested-record.msgpack"));
+  await cache.putEnvelope(document, marked);
+  assert.equal(hex(documentPayloadBytes(entries[0]!.payload)), hex(await read("extra-slot-nested-record.msgpack")), "the bytes are carried");
+  assert.deepEqual(cache.unreadSlots(document, "surface"), mark("Composition", 3, 2, false));
+  assert.equal(cache.isWritable(document, "surface"), false);
+  await assert.rejects(() => cache.put(document, "surface", golden), SchemaConflictError);
+});
+
+test("a key a store carries foreign is not writable", async () => {
+  const document = surfaceDocument();
+  const foreign = { ...envelopeOf(await read("union-surface.msgpack")), key: "stranger", type: "tests.unknown", schemaId: "tests.unknown.v1" };
+  const cache = CultCache.builder().withDocumentType(document).withGenericStore(memoryStore([foreign])).build();
+  await cache.pullAllBackingStores();
+  assert.equal(cache.isWritable(document, "stranger"), false);
+  assert.equal(cache.isWritable(document, "other"), true);
+});
+
+test("a write by a type that owns the held record's id restamps it, and is refused when that record carries unread slots", async () => {
+  const typed = (type: string, schemaId: string, compatibleSchemaIds: string[] = []) =>
+    defineDocumentType({ type, schemaId, schemaName: type, schemaVersion: `${type}.v1`, compatibleSchemaIds, schema: surfaceSchema, codec: surfaceCodec, name: "id" });
+  const older = typed("tests.surface_older", "tests.surface_older.v1");
+  const newer = typed("tests.surface_newer", "tests.surface_newer.v1", ["tests.surface_older.v1"]);
+  for (const [file, lands] of [["union-surface.msgpack", true], ["extra-slot-record.msgpack", false]] as const) {
+    const held = { ...envelopeOf(await read(file)), type: older.type, schemaId: "tests.surface_older.v1" };
+    const cache = CultCache.builder().withDocumentType(older).withDocumentType(newer).withGenericStore(memoryStore([held])).build();
+    await cache.pullAllBackingStores();
+    assert.equal(cache.isWritable(newer, "surface"), lands, `${file}: isWritable agrees with the write by the type that owns the id`);
+    const write = cache.put(newer, "surface", golden);
+    if (lands) {
+      await write;
+    } else {
+      await assert.rejects(() => write, (error: unknown) => error instanceof SchemaConflictError && error.unreadSlots?.typeName === "UnionSurface");
+    }
+  }
+});
+
+// The store vectors. TS has no variant records: extra-slot-store.cc carries one (marked-variant), so the whole file is refused
+// by name, and the walk runs over the file without that record.
+async function copyOf(name: string): Promise<string> {
+  const path = join(await mkdtemp(join(tmpdir(), "slot-readonly-")), name);
+  await copyFile(join(vectors, name), path);
+  return path;
+}
+
+async function withoutVariant(path: string): Promise<void> {
+  const [format, catalog, records] = decode(await readFile(path)) as [unknown, unknown[], unknown[][]];
+  await writeFile(path, encode([format, catalog, records.filter((record) => record[0] !== "marked-variant")]));
+}
+
+type SlotRow = [string, string, boolean, boolean | null, string | null, number | null, number | null, number | null, string | null];
+
+async function slotRows(): Promise<SlotRow[]> {
+  return decode(await read("slot-outcomes.msgpack")) as SlotRow[];
+}
+
+// The catalog entry the file publishes for a schema: its id and the reference's content hash, which a store rewrites with the
+// definition's own.
+async function catalogOf(file: string, schemaName: string): Promise<[string, string]> {
+  const [, catalog] = decode(await read(file)) as [unknown, string[][]];
+  const entry = catalog.find((candidate) => candidate[1] === schemaName)!;
+  return [entry[0]!, entry[3]!];
+}
+
+async function openStore(file: string, consent: boolean) {
+  const path = await copyOf(file);
+  if (file === "extra-slot-store.cc") await withoutVariant(path);
+  const surface = consent ? surfaceDeclaringDocument() : surfaceDocument(...(await catalogOf(file, "tests.union_surface")));
+  const slotUnit = consent ? undefined : slotUnitDocument(...(await catalogOf(file, "tests.slot_unit")));
+  const builder = CultCache.builder().withDocumentType(surface).withGenericStore(new SingleFileMessagePackBackingStore(path));
+  const cache = (slotUnit ? builder.withDocumentType(slotUnit) : builder).build();
+  await cache.pullAllBackingStores();
+  return { path, cache, surface, slotUnit };
+}
+
+test("extra-slot-store.cc carries a variant, which this runtime refuses by name; the rest of the file is walked", async () => {
+  const path = await copyOf("extra-slot-store.cc");
+  assert.throws(() => readSingleFileStore(path), StoreUnreadableError);
+});
+
+test("every slot-outcomes row holds: the mark, IsWritable, and the removal refused exactly where the record is not writable", async () => {
+  const rows = await slotRows();
+  assert.equal(rows.length, 8);
+  let walked = 0;
+  for (const [file, key, writable, explained, typeName, slots, declared, occurrences, flattenRefusedBy] of rows) {
+    if (flattenRefusedBy !== null) continue; // a variant: this runtime holds none
+    walked += 1;
+    const { path, cache, surface, slotUnit } = await openStore(file!, file === "extra-slot-consent.cc");
+    const document = key === "unit-arm" ? slotUnit! : surface;
+    const label = `${file} ${key}`;
+    const found = cache.unreadSlots(document, key!);
+    if (typeName === null) {
+      assert.equal(found, undefined, label);
+    } else {
+      assert.ok(found, label);
+      assert.deepEqual([found.explained, found.typeName, found.slotCount, found.declaredCount, found.occurrences], [explained, typeName, slots, declared, occurrences], label);
+    }
+    assert.equal(cache.isWritable(document, key!), writable, label);
+
+    const original = await readFile(path);
+    if (writable) {
+      assert.equal(await cache.delete(document, key!), true, label);
+    } else {
+      await assert.rejects(
+        () => cache.delete(document, key!),
+        (error: unknown) => error instanceof SchemaConflictError && error.unreadSlots?.typeName === typeName && !error.message.includes(SLOT_VALUE),
+        label,
+      );
+      assert.equal(Buffer.compare(original, await readFile(path)), 0, `${label}: the file is unchanged`);
+    }
+  }
+  assert.equal(walked, 7);
+});
+
+test("consent: a write of the explained record lands; the over-consent write is refused; the nested mark is refused", async () => {
+  const consented = await openStore("extra-slot-consent.cc", true);
+  const value = consented.cache.get(consented.surface, "consented") as Surface;
+  assert.deepEqual(value, golden);
+  await consented.cache.put(consented.surface, "consented", value);
+  assert.equal(consented.cache.unreadSlots(consented.surface, "consented"), undefined, "the write dropped the explained slot and the mark with it");
+  assert.equal(readSingleFileStore(consented.path).envelopes.find((e) => e.key === "consented")!.schemaId, "tests.union_surface.v2");
+
+  for (const key of ["over-consent", "nested"]) {
+    const refused = await openStore("extra-slot-consent.cc", true);
+    await assert.rejects(
+      () => refused.cache.put(refused.surface, key, golden),
+      (error: unknown) => error instanceof SchemaConflictError && error.schemaId === "tests.union_surface.wide",
+      `${key}: the refusal names the id the record was stored under`,
+    );
+  }
+});
+
+test("carried: after writing another record, the marked record's bytes, schema id, stored-at and every catalog entry are the originals", async () => {
+  const { path, cache, surface } = await openStore("extra-slot-store.cc", false);
+  const originals = readSingleFileStore(path);
+  await cache.put(surface, "clean", golden);
+  const after = readSingleFileStore(path);
+  for (const key of ["marked", "unit-arm"]) {
+    const was = originals.envelopes.find((e) => e.key === key)!;
+    const now = after.envelopes.find((e) => e.key === key)!;
+    assert.equal(hex(documentPayloadBytes(now.payload)), hex(documentPayloadBytes(was.payload)), key);
+    assert.equal(now.schemaId, was.schemaId, key);
+    assert.equal(now.storedAt, was.storedAt, key);
+    assert.deepEqual(now.catalogEntry, was.catalogEntry, key);
+  }
+});
+
+// A writer that adds a slot and keeps its schema id (TS ids are hand-written; C# ids hash the members): the reader of that
+// same id has declared nothing, so it consents to nothing.
+test("a wider writer under the reader's own schema id is read-only, and a real round trip does not shed the slot", async () => {
+  const doc = (columns: 1 | 2, compatibleSchemaIds: string[] = []) => defineDocumentType({
+    type: "tests.own_id",
+    schemaId: "tests.own_id.v1",
+    schemaName: "tests.own_id",
+    compatibleSchemaIds,
+    schema: z.object({ n: z.string(), extra: z.string().optional() }),
+    codec: columns === 2
+      ? slots<{ n: string; extra: string }>({ 0: ["n", string], 1: ["extra", string] }, "Own")
+      : slots<{ n: string }>({ 0: ["n", string] }, "Own"),
+    name: "n",
+  });
+  const path = join(await mkdtemp(join(tmpdir(), "slot-readonly-")), "own.cc");
+  const wide = doc(2);
+  const writer = CultCache.builder().withDocumentType(wide).withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+  await writer.put(wide, "k", { n: "n1", extra: "kept" });
+  const bytes = await readFile(path);
+
+  for (const compatible of [[], ["tests.own_id.v1"]]) {
+    const reader = doc(1, compatible);
+    const cache = CultCache.builder().withDocumentType(reader).withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+    await cache.pullAllBackingStores();
+    assert.deepEqual(cache.unreadSlots(reader, "k"), mark("Own", 2, 1, true), "unexplained: the arrived id is the reader's own");
+    assert.equal(cache.isWritable(reader, "k"), false);
+    await assert.rejects(() => cache.put(reader, "k", { n: "n2" }), SchemaConflictError);
+    await assert.rejects(() => cache.delete(reader, "k"), SchemaConflictError);
+    assert.equal(Buffer.compare(bytes, await readFile(path)), 0, "the file still holds the slot");
+  }
+});
+
+test("a record that arrived under an id the reader does not list compatible is never consented to", async () => {
+  const path = await copyOf("extra-slot-consent.cc");
+  const reader = surfaceDocument("tests.union_surface.v2"); // resolves by type name; lists nothing
+  const cache = CultCache.builder().withDocumentType(reader).withGenericStore(new SingleFileMessagePackBackingStore(path)).build();
+  await cache.pullAllBackingStores();
+  assert.equal(cache.unreadSlots(reader, "consented")?.explained, false);
+  assert.equal(cache.isWritable(reader, "consented"), false);
+});
+
+// isWritable is the write's own judge, not a second one: for every key state it answers what put does.
+test("isWritable equals the outcome of put for every key state the write judges", async () => {
+  const typed = (type: string, schemaId: string, extra: Record<string, unknown> = {}) =>
+    defineDocumentType({ type, schemaId, schemaName: type, schemaVersion: `${type}.v1`, schema: surfaceSchema, codec: surfaceCodec, name: "id", ...extra });
+  const older = typed("tests.surface_older", "tests.surface_older.v1");
+  const newer = typed("tests.surface_newer", "tests.surface_newer.v1", { compatibleSchemaIds: ["tests.surface_older.v1"] });
+  const stranger = typed("tests.surface_stranger", "tests.surface_stranger.v1");
+  const global = typed("tests.surface_global", "tests.surface_global.v1", { global: true });
+  const clean = (key: string, type: string, schemaId: string) => ({ ...envelopeOf(new Uint8Array()), key, type, schemaId });
+  const held = async (key: string, file: string, type: string, schemaId: string) =>
+    ({ ...envelopeOf(await read(file)), key, type, schemaId });
+
+  type Row = { name: string; build: () => Promise<{ cache: CultCache; target: typeof older; key: string }> };
+  const rows: Row[] = [
+    { name: "owned clean record in the writer's own store", build: async () => {
+      const cache = CultCache.builder().withDocumentType(older).withDocumentType(newer)
+        .withGenericStore(memoryStore([await held("k", "union-surface.msgpack", older.type, older.schemaId!)])).build();
+      return { cache, target: newer, key: "k" };
+    } },
+    { name: "owned record held in a store other than the writer's home", build: async () => {
+      const cache = CultCache.builder().withDocumentType(older).withDocumentType(newer)
+        .withBackingStore(memoryStore([await held("k", "union-surface.msgpack", older.type, older.schemaId!)]), older)
+        .withBackingStore(memoryStore([]), newer).build();
+      return { cache, target: newer, key: "k" };
+    } },
+    { name: "a record of a type that does not own the writer's id", build: async () => {
+      const cache = CultCache.builder().withDocumentType(older).withDocumentType(stranger)
+        .withGenericStore(memoryStore([await held("k", "union-surface.msgpack", older.type, older.schemaId!)])).build();
+      return { cache, target: stranger, key: "k" };
+    } },
+    { name: "a global type at a key other than the global key", build: async () => {
+      const cache = CultCache.builder().withDocumentType(global).withGenericStore(memoryStore([])).build();
+      return { cache, target: global, key: "x" };
+    } },
+    { name: "a key a store carries foreign", build: async () => {
+      const cache = CultCache.builder().withDocumentType(older)
+        .withGenericStore(memoryStore([{ ...clean("k", "tests.unknown", "tests.unknown.v1"), payload: documentPayloadFromBytes(await read("union-surface.msgpack")) }])).build();
+      return { cache, target: older, key: "k" };
+    } },
+    { name: "a marked record of the writer's own type", build: async () => {
+      const cache = CultCache.builder().withDocumentType(older)
+        .withGenericStore(memoryStore([await held("k", "extra-slot-record.msgpack", older.type, older.schemaId!)])).build();
+      return { cache, target: older, key: "k" };
+    } },
+    { name: "an unheld key", build: async () => ({ cache: CultCache.builder().withDocumentType(older).withGenericStore(memoryStore([])).build(), target: older, key: "k" }) },
+  ];
+  const outcomes: [string, boolean, boolean][] = [];
+  for (const row of rows) {
+    const { cache, target, key } = await row.build();
+    await cache.pullAllBackingStores();
+    const predicted = cache.isWritable(target, key);
+    const landed = await cache.put(target, key === "x" ? "x" : key, golden).then(() => true, () => false);
+    assert.equal(predicted, landed, row.name);
+    outcomes.push([row.name, predicted, landed]);
+  }
+  assert.deepEqual(outcomes.map(([, writable]) => writable), [true, false, false, false, false, false, true]);
+  // The same judge refuses a removal of a key held read-only or carried foreign.
+  const removals = CultCache.builder().withDocumentType(older)
+    .withGenericStore(memoryStore([await held("k", "extra-slot-record.msgpack", older.type, older.schemaId!)])).build();
+  await removals.pullAllBackingStores();
+  await assert.rejects(() => removals.delete(older, "k"), SchemaConflictError);
+  const stranger2 = CultCache.builder().withDocumentType(older)
+    .withGenericStore(memoryStore([{ ...envelopeOf(await read("union-surface.msgpack")), key: "f", type: "tests.unknown", schemaId: "tests.unknown.v1" }])).build();
+  await stranger2.pullAllBackingStores();
+  await assert.rejects(() => stranger2.delete(older, "f"), SchemaConflictError);
+});
+
+// A removal is by key (C# Remove): the owner of a held record's id removes the one record that exists, in one store call and
+// with the cache dropped only once the store has; a type that does not own it is refused like put, and isWritable agrees.
+test("delete of a key held as another type: the owner removes it once, a stranger is refused, a failing store leaves cache and store agreeing", async () => {
+  const typed = (type: string, schemaId: string, extra: Record<string, unknown> = {}) =>
+    defineDocumentType({ type, schemaId, schemaName: type, schemaVersion: `${type}.v1`, schema: surfaceSchema, codec: surfaceCodec, name: "id", ...extra });
+  const older = typed("tests.surface_older", "tests.surface_older.v1");
+  const newer = typed("tests.surface_newer", "tests.surface_newer.v1", { compatibleSchemaIds: ["tests.surface_older.v1"] });
+  const stranger = typed("tests.surface_stranger", "tests.surface_stranger.v1");
+  const heldRecord = async (): Promise<CultCacheEnvelope> => ({ ...envelopeOf(await read("union-surface.msgpack")), key: "k", type: older.type, schemaId: older.schemaId });
+  const open = async (failing = false) => {
+    const rows = [await heldRecord()];
+    const calls: string[] = [];
+    const store: CacheBackingStore = {
+      async pullAll() { return rows.map((row) => ({ ...row })); },
+      async push(entry) { rows.push(entry); },
+      async delete(entry) {
+        calls.push(entry.key);
+        if (failing) throw new Error("store refused the removal");
+        rows.splice(rows.findIndex((row) => row.key === entry.key), 1);
+      },
+    };
+    const cache = CultCache.builder().withDocumentType(older).withDocumentType(newer).withDocumentType(stranger).withGenericStore(store).build();
+    await cache.pullAllBackingStores();
+    return { cache, rows, calls };
+  };
+
+  const owner = await open();
+  assert.equal(owner.cache.isWritable(newer, "k"), true);
+  assert.equal(await owner.cache.delete(newer, "k"), true, "the owner's removal removes the one record");
+  assert.deepEqual([owner.rows.length, owner.calls.length, owner.cache.get(older, "k")], [0, 1, undefined], "one store call, record gone from store and cache");
+
+  const refused = await open();
+  assert.equal(refused.cache.isWritable(stranger, "k"), false);
+  await assert.rejects(() => refused.cache.delete(stranger, "k"), SchemaConflictError);
+  assert.deepEqual([refused.rows.length, refused.calls.length, refused.cache.get(older, "k") !== undefined], [1, 0, true]);
+
+  const failing = await open(true);
+  await assert.rejects(() => failing.cache.delete(newer, "k"), /store refused/u);
+  assert.deepEqual([failing.rows.length, failing.calls.length, failing.cache.get(older, "k") !== undefined], [1, 1, true], "the store failed: neither side dropped it");
+
+  const same = await open();
+  assert.equal(await same.cache.delete(older, "k"), true);
+  assert.equal(await same.cache.delete(older, "k"), false, "an unheld key is still the plain false");
+});
+
+// The removal form's three finer behaviours (cultlib-gaps:finding:cut-slot-readonly-ts.s4.removal-form-unpinned).
+test("an owner's delete: refused for a marked record, taken from the held record's store, and clears the held type's lookups", async () => {
+  const typed = (type: string, schemaId: string, extra: Record<string, unknown> = {}) =>
+    defineDocumentType({ type, schemaId, schemaName: type, schemaVersion: `${type}.v1`, schema: surfaceSchema, codec: surfaceCodec, name: "id", ...extra });
+  const older = typed("tests.surface_older", "tests.surface_older.v1", { indexes: { byVersion: (value: Surface) => String(value.version) } });
+  const newer = typed("tests.surface_newer", "tests.surface_newer.v1", { compatibleSchemaIds: ["tests.surface_older.v1"] });
+  const heldIn = async (file: string): Promise<CultCacheEnvelope> =>
+    ({ ...envelopeOf(await read(file)), key: "k", type: older.type, schemaId: older.schemaId });
+  const recording = (rows: CultCacheEnvelope[]) => {
+    const removed: string[] = [];
+    const store: CacheBackingStore = {
+      async pullAll() { return rows.map((row) => ({ ...row })); },
+      async push(entry) { rows.push(entry); },
+      async delete(entry) { removed.push(entry.key); rows.splice(rows.findIndex((row) => row.key === entry.key), 1); },
+    };
+    return { store, removed, rows };
+  };
+
+  // 1. The owner may not remove a record carrying unread slots nothing consents to.
+  const marked = recording([await heldIn("extra-slot-record.msgpack")]);
+  const markedCache = CultCache.builder().withDocumentType(older).withDocumentType(newer).withGenericStore(marked.store).build();
+  await markedCache.pullAllBackingStores();
+  await assert.rejects(() => markedCache.delete(newer, "k"), (error: unknown) => error instanceof SchemaConflictError && error.unreadSlots?.typeName === "UnionSurface");
+  assert.deepEqual([marked.rows.length, marked.removed.length, markedCache.get(older, "k") !== undefined], [1, 0, true]);
+
+  // 2. The removal goes to the store of the record that exists, not the deleting type's; there the write form is false (it would
+  //    push to the wrong store) while the removal succeeds.
+  const olderStore = recording([await heldIn("union-surface.msgpack")]);
+  const newerStore = recording([]);
+  const split = CultCache.builder().withDocumentType(older).withDocumentType(newer)
+    .withBackingStore(olderStore.store, older).withBackingStore(newerStore.store, newer).build();
+  await split.pullAllBackingStores();
+  assert.equal(split.isWritable(newer, "k"), false, "isWritable answers the write form: the rename cannot replace a record in another store");
+  assert.equal(await split.delete(newer, "k"), true);
+  assert.deepEqual([olderStore.removed, newerStore.removed, split.get(older, "k")], [["k"], [], undefined]);
+
+  // 3. The held type's name and index lookups are cleared with the record.
+  const single = recording([await heldIn("union-surface.msgpack")]);
+  const cache = CultCache.builder().withDocumentType(older).withDocumentType(newer).withGenericStore(single.store).build();
+  await cache.pullAllBackingStores();
+  assert.equal(cache.getKeyByName(older, "surface"), "k");
+  assert.equal(cache.getKeyByIndex(older, "byVersion", "3"), "k");
+  await cache.delete(newer, "k");
+  assert.equal(cache.getKeyByName(older, "surface"), undefined);
+  assert.equal(cache.getKeyByIndex(older, "byVersion", "3"), undefined);
+  assert.equal(cache.getAll(older).length, 0);
+});
+
+test("a global type at a key other than the global key: isWritable is false and delete is the plain false of an unheld key", async () => {
+  const global = defineDocumentType({ type: "tests.surface_global", schemaId: "tests.surface_global.v1", schemaName: "tests.surface_global", schemaVersion: "tests.surface_global.v1", schema: surfaceSchema, codec: surfaceCodec, name: "id", global: true });
+  const cache = CultCache.builder().withDocumentType(global).withGenericStore(memoryStore([])).build();
+  assert.equal(cache.isWritable(global, "x"), false);
+  assert.equal(await cache.delete(global, "x"), false);
+});

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

@@ -12,6 +12,7 @@ import { decode, encode } from "@msgpack/msgpack";
 
 import { documentPayloadBytes, documentPayloadFromBytes } from "../src/document";
 import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store";
+import { SchemaConflictError, StoreUnreadableError } from "../src/store-format";
 import type { CultCacheEnvelope } from "../src/types";
 
 import {
@@ -471,44 +472,70 @@ test("the store lock is released when the operation throws", async () => {
   }
 });
 
+// SYNTHETIC pre-v1 vector: no real file of this shape is known to exist. A top-level array of {key,type,payload,storedAt}
+// whose payload is not binary (an object, a Node Buffer JSON, an int array) is what the removed heal-on-open rewrote.
 const legacyObjectPayload = (): Uint8Array =>
   encode([{ key: "note:hello", type: "note", payload: { title: "Hello" }, storedAt: "2026-10-20T00:00:00Z" }]);
 
-test("an open that heals a legacy store waits for the store lock and heals from its own read", async () => {
+test("opening a synthetic pre-v1 store with object payloads returns them normalized and leaves the file untouched, even while another holder has the lock", async () => {
   const directory = await scratch();
   try {
     const path = join(directory, "legacy.cc");
     const legacy = legacyObjectPayload();
     await writeFile(path, legacy);
     const store = new SingleFileMessagePackBackingStore(path);
-    let healed: Promise<unknown> | undefined;
-    let settled = false;
     await withStoreWriteLock(path, async () => {
-      healed = store.pullAll().then(() => {
-        settled = true;
-      });
-      await sleepFor(300);
-      assert.equal(settled, false, "the heal must wait for the lock");
-      assert.deepEqual([...(await readFile(path))], [...legacy], "the file keeps its legacy bytes while the lock is held elsewhere");
+      const [lockHeld] = await Promise.all([readdir(directory)]);
+      const envelopes = await within(store.pullAll(), 5000, "an open does not wait for the write lock");
+      assert.deepEqual(envelopes.map((entry) => entry.key), ["note:hello"]);
+      assert.deepEqual(decode(documentPayloadBytes(envelopes[0].payload)), { title: "Hello" });
+      assert.deepEqual([...(await readFile(path))], [...legacy]);
+      assert.deepEqual((await readdir(directory)).sort(), lockHeld.sort(), "an open adds no lock or temp file");
     });
-    await within(healed!, 5000, "the heal");
-    assert.equal((decode(await readFile(path)) as unknown[])[0], "cultcache.store.v1");
+    assert.deepEqual([...(await readFile(path))], [...legacy]);
+    assert.deepEqual((await readdir(directory)).filter((name) => name !== "legacy.cc" && name !== "legacy.cc.lock"), []);
   } finally {
     await rm(directory, { recursive: true, force: true });
   }
 });
 
-test("push and delete over a legacy store that needs healing finish instead of waiting on their own lock", async () => {
+test("opening a synthetic pre-v1 store with Buffer-JSON and int-array payloads normalizes them in memory and leaves the file untouched", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "legacy.cc");
+    const inner = encode({ title: "Hello" });
+    const legacy = encode([
+      { key: "a", type: "note", payload: { type: "Buffer", data: [...inner] }, storedAt: "2026-10-20T00:00:00Z" },
+      { key: "b", type: "note", payload: [...inner], storedAt: "2026-10-20T00:00:00Z" },
+    ]);
+    await writeFile(path, legacy);
+    const envelopes = await new SingleFileMessagePackBackingStore(path).pullAll();
+    assert.deepEqual(envelopes.map((entry) => entry.key), ["a", "b"]);
+    for (const envelope of envelopes) {
+      assert.deepEqual(decode(documentPayloadBytes(envelope.payload)), { title: "Hello" });
+    }
+    assert.deepEqual([...(await readFile(path))], [...legacy]);
+    assert.deepEqual(await readdir(directory), ["legacy.cc"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("push and delete over a synthetic pre-v1 store write v1 and keep the other legacy entries, normalized payloads included", async () => {
   const directory = await scratch();
   try {
     const path = join(directory, "legacy.cc");
     await writeFile(path, legacyObjectPayload());
     const store = new SingleFileMessagePackBackingStore(path);
     await within(store.push(entryOf("a")), 5000, "push");
+    assert.equal((decode(await readFile(path)) as unknown[])[0], "cultcache.store.v1");
+    assert.deepEqual((await store.pullAll()).map((entry) => entry.key).sort(), ["a", "note:hello"]);
     await writeFile(path, legacyObjectPayload());
     await within(store.delete(entryOf("a")), 5000, "delete");
-    const keys = (await store.pullAll()).map((entry) => entry.key);
-    assert.deepEqual(keys, ["note:hello"]);
+    assert.equal((decode(await readFile(path)) as unknown[])[0], "cultcache.store.v1");
+    const kept = await store.pullAll();
+    assert.deepEqual(kept.map((entry) => entry.key), ["note:hello"]);
+    assert.deepEqual(decode(documentPayloadBytes(kept[0].payload)), { title: "Hello" });
   } finally {
     await rm(directory, { recursive: true, force: true });
   }
@@ -545,15 +572,84 @@ const snapshotOf = async (store: SingleFileMessagePackBackingStore): Promise<str
     .map((entry) => `${entry.type}/${entry.key}:${[...documentPayloadBytes(entry.payload)].at(-1)}`)
     .sort();
 
-test("push replaces the record at the same type and key and keeps every other", async () => {
+test("push replaces the record under the same key and type and keeps every other; retyping is delete then push", async () => {
   const directory = await scratch();
   try {
     const store = new SingleFileMessagePackBackingStore(join(directory, "store.cc"));
-    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("a", "u", 3)]);
+    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("c", "u", 3)]);
     await store.push(entryOf("a", "t", 9));
-    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "u/a:3"]);
-    await store.push(entryOf("c", "t", 4));
-    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "t/c:4", "u/a:3"]);
+    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "u/c:3"]);
+    await store.push(entryOf("d", "t", 4));
+    assert.deepEqual(await snapshotOf(store), ["t/a:9", "t/b:2", "t/d:4", "u/c:3"]);
+    await store.delete(entryOf("a", "t"));
+    await store.push(entryOf("a", "u", 5));
+    assert.deepEqual(await snapshotOf(store), ["t/b:2", "t/d:4", "u/a:5", "u/c:3"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a push that would land a second type under an existing key is refused and the file is byte for byte unchanged", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    const store = new SingleFileMessagePackBackingStore(path);
+    await store.pushAll([entryOf("k", "t", 1), entryOf("m", "t", 2)]);
+    const before = [...(await readFile(path))];
+    await assert.rejects(
+      () => store.push(entryOf("k", "u", 9)),
+      (error: unknown) => error instanceof SchemaConflictError && error.recordKey === "k" && /holds record "k" as type "t"/u.test(error.message),
+    );
+    assert.deepEqual([...(await readFile(path))], before);
+    assert.deepEqual(await snapshotOf(new SingleFileMessagePackBackingStore(path)), ["t/k:1", "t/m:2"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a pushAll batch that carries one key under two types is refused and writes nothing", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    const store = new SingleFileMessagePackBackingStore(path);
+    await assert.rejects(() => store.pushAll([entryOf("k", "t", 1), entryOf("k", "u", 2)]), SchemaConflictError);
+    assert.equal((await readdir(directory)).includes("store.cc"), false);
+    await store.pushAll([entryOf("a", "t", 1)]);
+    const before = [...(await readFile(path))];
+    await assert.rejects(() => store.pushAll([entryOf("k", "t", 1), entryOf("k", "u", 2)]), SchemaConflictError);
+    assert.deepEqual([...(await readFile(path))], before);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a pushAll batch that carries one key twice under one type keeps the last and the file reads back with one record", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "store.cc");
+    await new SingleFileMessagePackBackingStore(path).pushAll([entryOf("k", "t", 1), entryOf("a", "t", 3), entryOf("k", "t", 2)]);
+    assert.deepEqual(await snapshotOf(new SingleFileMessagePackBackingStore(path)), ["t/a:3", "t/k:2"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a legacy envelope array that holds a key under two types is refused on open, as a v1 store is", async () => {
+  const directory = await scratch();
+  try {
+    const path = join(directory, "legacy.cc");
+    const bytes = encode([
+      { key: "a", type: "t", payload: { n: 1 }, storedAt: "2026-10-20T00:00:00Z" },
+      { key: "a", type: "u", payload: { n: 2 }, storedAt: "2026-10-20T00:00:00Z" },
+    ]);
+    await writeFile(path, bytes);
+    const store = new SingleFileMessagePackBackingStore(path);
+    await assert.rejects(
+      () => store.pullAll(),
+      (error: unknown) => error instanceof StoreUnreadableError && /"a" appears more than once/u.test(error.message),
+    );
+    await assert.rejects(() => store.push(entryOf("b")), StoreUnreadableError);
+    assert.deepEqual([...(await readFile(path))], [...bytes]);
   } finally {
     await rm(directory, { recursive: true, force: true });
   }
@@ -563,11 +659,12 @@ test("delete removes only the record at that type and key", async () => {
   const directory = await scratch();
   try {
     const store = new SingleFileMessagePackBackingStore(join(directory, "store.cc"));
-    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("a", "u", 3)]);
+    await store.pushAll([entryOf("a", "t", 1), entryOf("b", "t", 2), entryOf("c", "u", 3)]);
     await store.delete(entryOf("a", "t"));
-    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/a:3"]);
+    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/c:3"]);
     await store.delete(entryOf("zzz", "t"));
-    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/a:3"]);
+    await store.delete(entryOf("c", "t"));
+    assert.deepEqual(await snapshotOf(store), ["t/b:2", "u/c:3"]);
   } finally {
     await rm(directory, { recursive: true, force: true });
   }
@@ -697,7 +794,7 @@ test("a store file of an unrecognized shape is refused, and a store naming a mis
   }
 });
 
-test("opening a store that needs no healing writes nothing: a missing store leaves no lock file, a legacy store with byte payloads keeps its bytes", async () => {
+test("opening writes nothing: a missing store leaves no lock file, a legacy store with byte payloads keeps its bytes", async () => {
   const directory = await scratch();
   try {
     const absent = join(directory, "nested", "absent.cc");

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

@@ -1,8 +1,7 @@
 import assert from "node:assert/strict";
-import { existsSync } from "node:fs";
 import { mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { test } from "node:test";
 
 import { decode, encode } from "@msgpack/msgpack";
@@ -22,190 +21,14 @@ import {
   encodeDocumentPayload,
 } from "../src/document";
 import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store";
-import type { AnyCultCacheDocumentDefinition, CacheBackingStore, CultCacheEnvelope } from "../src/types";
+import type { AnyCultCacheDocumentDefinition, CultCacheEnvelope } from "../src/types";
+
+import {
+  CANARY, type Node, type Surface, golden, hex, node, outcome, read, surfaceCodec, surfaceDocument, surfaceSchema, vectors, envelopeOf, memoryStore,
+} from "./union-surface-fixture";
 
 const { array, boolean, bytes, float32, float64, int32, int64, lazy, list, nullable, slots, string, union, unit } = codecs;
 
-// The names the C# reference gives the fixture's types (CultSchemaTypeNames.FromType), as union-surface.cc carries them.
-const CS = "GameCult.Caching.Tests.UnionParityVectorTests+";
-
-// The golden is tests/vectors/union-parity, written by the C# reference. Everything below that is bytes or an expected
-// outcome is read from those committed files; only the value the payload must decode to is spelled here.
-function findVectors(from: string): string {
-  for (let dir = from; ; dir = resolve(dir, "..")) {
-    if (existsSync(join(dir, "tests", "vectors", "union-parity"))) return join(dir, "tests", "vectors", "union-parity");
-    if (resolve(dir, "..") === dir) throw new Error("tests/vectors/union-parity not found above the test.");
-  }
-}
-const vectors = findVectors(__dirname);
-const read = async (name: string) => new Uint8Array(await readFile(join(vectors, name)));
-
-// The string the C# writer put inside every refusal payload, to prove a refusal never echoes the payload.
-const CANARY = "CANARY-union-golden-4c2a";
-
-type Node =
-  | { kind: "Box"; id: string; children: (Node | null)[] }
-  | { 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; 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: (GoldenOutcome | null)[];
-  part: Item | null;
-  crafted: CraftedItem | null;
-  missing: Node | null;
-}
-
-const composition = slots<Composition>({ 0: ["name", string], 1: ["body", lazy(() => node)] }, `${CS}Composition`);
-const node: Codec<Node | null> = union<Node>("Node", {
-  0: ["Box", slots<{ id: string; children: (Node | null)[] }>({ 0: ["id", string], 1: ["children", list(lazy(() => node))] })],
-  1: ["Text", slots<{ id: string; content: string }>({ 0: ["id", string], 1: ["content", string] })],
-  2: ["Use", slots<{ id: string; composition: Composition; slots: (Node | null)[] }>({
-    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; id: string }>({ 0: ["inner", lazy(() => node)], 1: ["id", string] })],
-}, `${CS}Node`);
-const outcome = union<Outcome>("Outcome", {
-  0: ["Pending", slots<{ message: string }>({ 0: ["message", string] })],
-  1: ["Completed", slots<{ sourceVersion: number }>({ 0: ["sourceVersion", int32] })],
-  2: ["Denied", unit],
-  [-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", {
-  0: ["Gem", slots<{ name: string }>({ 0: ["name", string] })],
-  1: ["Tool", toolArm],
-  2: ["Part", partArm],
-}, `${CS}Item`);
-const craftedItem = union<CraftedItem>("CraftedItem", { 0: ["Tool", toolArm], 1: ["Part", partArm] }, `${CS}CraftedItem`);
-const surfaceCodec = slots<Surface>({
-  0: ["id", string],
-  1: ["version", int32],
-  2: ["root", node],
-  3: ["outcomes", list(goldenOutcome)],
-  4: ["part", item],
-  5: ["crafted", craftedItem],
-  6: ["missing", node, null],
-}, `${CS}UnionSurface`);
-
-const nodeSchema: z.ZodType<Node | null> = z.lazy(() =>
-  z.union([
-    z.null(),
-    z.discriminatedUnion("kind", [
-      z.object({ kind: z.literal("Box"), id: z.string(), children: z.array(nodeSchema) }),
-      z.object({ kind: z.literal("Text"), id: z.string(), content: z.string() }),
-      z.object({
-        kind: z.literal("Use"),
-        id: z.string(),
-        composition: z.object({ name: z.string(), body: nodeSchema }),
-        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, id: z.string() }),
-    ]),
-  ]));
-const surfaceSchema = z.object({
-  id: z.string(),
-  version: z.number(),
-  root: nodeSchema,
-  outcomes: z.array(z.union([
-    z.null(),
-    z.discriminatedUnion("kind", [
-      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", [
-    z.object({ kind: z.literal("Gem"), name: z.string() }),
-    z.object({ kind: z.literal("Tool"), name: z.string(), uses: z.number() }),
-    z.object({ kind: z.literal("Part"), name: z.string(), count: z.number() }),
-  ])]),
-  crafted: z.union([z.null(), z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("Tool"), name: z.string(), uses: z.number() }),
-    z.object({ kind: z.literal("Part"), name: z.string(), count: z.number() }),
-  ])]),
-  missing: nodeSchema,
-}) as unknown as z.ZodType<Surface>;
-
-function surfaceDocument(schemaId?: string) {
-  return defineDocumentType({
-    type: "tests.union_surface",
-    schemaId: schemaId ?? "tests.union_surface.v1",
-    schemaName: "tests.union_surface",
-    schemaVersion: "tests.union_surface.v1",
-    schema: surfaceSchema,
-    codec: surfaceCodec,
-    name: "id",
-  });
-}
-
-const golden: Surface = {
-  id: "surface",
-  version: 3,
-  root: {
-    kind: "Box",
-    id: "0000000000c0",
-    children: [
-      { kind: "Text", id: "0000000000c1", content: "hello" },
-      {
-        kind: "Use",
-        id: "0000000000c2",
-        composition: {
-          name: "comp",
-          body: {
-            kind: "Box",
-            id: "0000000000d0",
-            children: [
-              { kind: "Text", id: "0000000000d1", content: "x" },
-              { kind: "Image", id: "0000000000d2", uri: "uri://a", alt: "alt" },
-            ],
-          },
-        },
-        slots: [{ kind: "Text", id: "0000000000e1", content: "slot" }, null, { kind: "Box", id: "0000000000e2", children: [] }],
-      },
-      { kind: "Image", id: "0000000000c3", uri: "uri://b", alt: "" },
-    ],
-  },
-  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,
-};
-
-const hex = (data: Uint8Array) => Buffer.from(data).toString("hex");
-
 async function outcomeEntries() {
   const entries = decode(await read("outcomes.msgpack")) as [string, string, string, number | null, string][];
   return entries.map(([file, outcome, unionName, key, detail]) => ({ file, outcome, unionName, key, detail }));
@@ -729,19 +552,6 @@ test("the Int32 edges of an arm key: the largest is an arm, one past either end
   assert.throws(() => edge.decode(readWire(fromHex("92d3ffffffff8000000090"))), { message: "Union U: unknown arm key -2147483648 (declared keys: 2147483647)." });
 });
 
-function envelopeOf(payload: Uint8Array): CultCacheEnvelope {
-  return { key: "surface", type: "tests.union_surface", payload: documentPayloadFromBytes(payload), storedAt: new Date().toISOString() };
-}
-
-function memoryStore(entries: CultCacheEnvelope[]): CacheBackingStore & { entries: CultCacheEnvelope[] } {
-  return {
-    entries,
-    async pullAll() { return entries.map((entry) => ({ ...entry })); },
-    async push(entry) { entries.push(entry); },
-    async delete() {},
-  };
-}
-
 test("arm keys span Int32 and are listed ascending; slot keys are non-negative Int32", () => {
   const keys = union<{ kind: "High" | "Zero" | "Neg" | "Low" }>("U", {
     2147483647: ["High", unit],

packages/cultcache-ts/test/union-surface-fixture.ts

@@ -0,0 +1,240 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { z } from "zod";
+
+import { codecs } from "../src";
+import type { Codec } from "../src/codec";
+import { defineDocumentType, documentPayloadFromBytes } from "../src/document";
+import type { CacheBackingStore, CultCacheEnvelope } from "../src/types";
+
+// The union-surface fixture: the codecs, schema and value tests/vectors/union-parity was written from, shared by the
+// union-parity walker and the slot-readonly walker so the shape is spelled once.
+const { list, int32, lazy, slots, string, union, unit } = codecs;
+
+
+// The names the C# reference gives the fixture's types (CultSchemaTypeNames.FromType), as union-surface.cc carries them.
+export const CS = "GameCult.Caching.Tests.UnionParityVectorTests+";
+
+// The golden is tests/vectors/union-parity, written by the C# reference. Everything below that is bytes or an expected
+// outcome is read from those committed files; only the value the payload must decode to is spelled here.
+export function findVectors(from: string): string {
+  for (let dir = from; ; dir = resolve(dir, "..")) {
+    if (existsSync(join(dir, "tests", "vectors", "union-parity"))) return join(dir, "tests", "vectors", "union-parity");
+    if (resolve(dir, "..") === dir) throw new Error("tests/vectors/union-parity not found above the test.");
+  }
+}
+export const vectors = findVectors(__dirname);
+export const read = async (name: string) => new Uint8Array(await readFile(join(vectors, name)));
+
+// The string the C# writer put inside every refusal payload, to prove a refusal never echoes the payload.
+export const CANARY = "CANARY-union-golden-4c2a";
+
+export type Node =
+  | { kind: "Box"; id: string; children: (Node | null)[] }
+  | { 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; id: string };
+export interface Composition { name: string; body: Node | null }
+export 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.
+export 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 };
+export type Item = { kind: "Gem"; name: string } | { kind: "Tool"; name: string; uses: number } | { kind: "Part"; name: string; count: number };
+export type CraftedItem = { kind: "Tool"; name: string; uses: number } | { kind: "Part"; name: string; count: number };
+export interface Surface {
+  id: string;
+  version: number;
+  root: Node | null;
+  outcomes: (GoldenOutcome | null)[];
+  part: Item | null;
+  crafted: CraftedItem | null;
+  missing: Node | null;
+}
+
+export const composition = slots<Composition>({ 0: ["name", string], 1: ["body", lazy(() => node)] }, `${CS}Composition`);
+export const node: Codec<Node | null> = union<Node>("Node", {
+  0: ["Box", slots<{ id: string; children: (Node | null)[] }>({ 0: ["id", string], 1: ["children", list(lazy(() => node))] }, `${CS}Box`)],
+  1: ["Text", slots<{ id: string; content: string }>({ 0: ["id", string], 1: ["content", string] }, `${CS}Text`)],
+  2: ["Use", slots<{ id: string; composition: Composition; slots: (Node | null)[] }>({
+    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; id: string }>({ 0: ["inner", lazy(() => node)], 1: ["id", string] })],
+}, `${CS}Node`);
+export const outcome = union<Outcome>("Outcome", {
+  0: ["Pending", slots<{ message: string }>({ 0: ["message", string] })],
+  1: ["Completed", slots<{ sourceVersion: number }>({ 0: ["sourceVersion", int32] })],
+  2: ["Denied", unit],
+  [-2147483648]: ["Floor", unit],
+  2147483647: ["Ceiling", unit],
+}, `${CS}Outcome`);
+export const idOnly = slots<{ id: string }>({ 0: ["id", string] });
+export 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`);
+export const toolArm = slots<{ name: string; uses: number }>({ 0: ["name", string], 1: ["uses", int32] });
+export const partArm = slots<{ name: string; count: number }>({ 0: ["name", string], 1: ["count", int32] });
+export const item = union<Item>("Item", {
+  0: ["Gem", slots<{ name: string }>({ 0: ["name", string] })],
+  1: ["Tool", toolArm],
+  2: ["Part", partArm],
+}, `${CS}Item`);
+export const craftedItem = union<CraftedItem>("CraftedItem", { 0: ["Tool", toolArm], 1: ["Part", partArm] }, `${CS}CraftedItem`);
+export const surfaceCodecOf = (typeName: string) => slots<Surface>({
+  0: ["id", string],
+  1: ["version", int32],
+  2: ["root", node],
+  3: ["outcomes", list(goldenOutcome)],
+  4: ["part", item],
+  5: ["crafted", craftedItem],
+  6: ["missing", node, null],
+}, typeName);
+export const surfaceCodec = surfaceCodecOf(`${CS}UnionSurface`);
+
+export const nodeSchema: z.ZodType<Node | null> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.discriminatedUnion("kind", [
+      z.object({ kind: z.literal("Box"), id: z.string(), children: z.array(nodeSchema) }),
+      z.object({ kind: z.literal("Text"), id: z.string(), content: z.string() }),
+      z.object({
+        kind: z.literal("Use"),
+        id: z.string(),
+        composition: z.object({ name: z.string(), body: nodeSchema }),
+        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, id: z.string() }),
+    ]),
+  ]));
+export const surfaceSchema = z.object({
+  id: z.string(),
+  version: z.number(),
+  root: nodeSchema,
+  outcomes: z.array(z.union([
+    z.null(),
+    z.discriminatedUnion("kind", [
+      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", [
+    z.object({ kind: z.literal("Gem"), name: z.string() }),
+    z.object({ kind: z.literal("Tool"), name: z.string(), uses: z.number() }),
+    z.object({ kind: z.literal("Part"), name: z.string(), count: z.number() }),
+  ])]),
+  crafted: z.union([z.null(), z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("Tool"), name: z.string(), uses: z.number() }),
+    z.object({ kind: z.literal("Part"), name: z.string(), count: z.number() }),
+  ])]),
+  missing: nodeSchema,
+}) as unknown as z.ZodType<Surface>;
+
+// The reference's SurfaceDeclaring: the same layout, schema tests.union_surface.v2, listing the older wide id compatible.
+export function surfaceDeclaringDocument() {
+  return defineDocumentType({
+    type: "tests.union_surface",
+    schemaId: "tests.union_surface.v2",
+    schemaName: "tests.union_surface",
+    schemaVersion: "tests.union_surface.v2",
+    compatibleSchemaIds: ["tests.union_surface.wide"],
+    schema: surfaceSchema,
+    codec: surfaceCodecOf(`${CS}SurfaceDeclaring`),
+    name: "id",
+  });
+}
+
+export function surfaceDocument(schemaId?: string, contentHash?: string) {
+  return defineDocumentType({
+    ...(contentHash === undefined ? {} : { contentHash }),
+    type: "tests.union_surface",
+    schemaId: schemaId ?? "tests.union_surface.v1",
+    schemaName: "tests.union_surface",
+    schemaVersion: "tests.union_surface.v1",
+    schema: surfaceSchema,
+    codec: surfaceCodec,
+    name: "id",
+  });
+}
+
+export const golden: Surface = {
+  id: "surface",
+  version: 3,
+  root: {
+    kind: "Box",
+    id: "0000000000c0",
+    children: [
+      { kind: "Text", id: "0000000000c1", content: "hello" },
+      {
+        kind: "Use",
+        id: "0000000000c2",
+        composition: {
+          name: "comp",
+          body: {
+            kind: "Box",
+            id: "0000000000d0",
+            children: [
+              { kind: "Text", id: "0000000000d1", content: "x" },
+              { kind: "Image", id: "0000000000d2", uri: "uri://a", alt: "alt" },
+            ],
+          },
+        },
+        slots: [{ kind: "Text", id: "0000000000e1", content: "slot" }, null, { kind: "Box", id: "0000000000e2", children: [] }],
+      },
+      { kind: "Image", id: "0000000000c3", uri: "uri://b", alt: "" },
+    ],
+  },
+  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,
+};
+export const hex = (data: Uint8Array) => Buffer.from(data).toString("hex");
+
+// tests.slot_unit: a document [Name, Outcome: UnitOutcome], whose one arm Denied2 is a unit arm (extra-slot-store.cc, record
+// unit-arm). The reader's names are the reference's: a mark names Denied2.
+export const unitOutcome = union<{ kind: "Denied2" }>("UnitOutcome", { 2: ["Denied2", unit] }, `${CS}UnitOutcome`);
+export function slotUnitDocument(schemaId: string, contentHash?: string) {
+  return defineDocumentType({
+    ...(contentHash === undefined ? {} : { contentHash }),
+    type: "tests.slot_unit",
+    schemaId,
+    schemaName: "tests.slot_unit",
+    schemaVersion: "tests.slot_unit.v1",
+    schema: z.object({ name: z.string(), outcome: z.union([z.null(), z.object({ kind: z.literal("Denied2") })]) }),
+    codec: slots<{ name: string; outcome: { kind: "Denied2" } | null }>({ 0: ["name", string], 1: ["outcome", unitOutcome] }, `${CS}SlotUnit`),
+    name: "name",
+  });
+}
+
+export function envelopeOf(payload: Uint8Array): CultCacheEnvelope {
+  return { key: "surface", type: "tests.union_surface", payload: documentPayloadFromBytes(payload), storedAt: new Date().toISOString() };
+}
+
+export function memoryStore(entries: CultCacheEnvelope[]): CacheBackingStore & { entries: CultCacheEnvelope[] } {
+  return {
+    entries,
+    async pullAll() { return entries.map((entry) => ({ ...entry })); },
+    async push(entry) { entries.push(entry); },
+    async delete() {},
+  };
+}
+

packages/cultcache-ts/test/unique-index.test.ts

@@ -0,0 +1,583 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { copyFile, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+
+import { decode } from "@msgpack/msgpack";
+import { z } from "zod";
+
+import { codecs } from "../src";
+import { CultCache } from "../src/cult-cache";
+import { defineDocumentType, resolveDocumentMembers } from "../src/document";
+import { SingleFileMessagePackBackingStore } from "../src/single-file-messagepack-backing-store";
+import type { AnyCultCacheDocumentDefinition } from "../src/types";
+
+// variants:ruling:unique-indexes. `indexes` are unique within one type, `roles` are selection aliases. The vectors in
+// tests/vectors/unique-index are written by the C# reference; the rest of the behaviour is pinned here.
+
+function findVectors(from: string): string {
+  for (let dir = from; ; dir = resolve(dir, "..")) {
+    if (existsSync(join(dir, "tests", "vectors", "unique-index"))) return join(dir, "tests", "vectors", "unique-index");
+    if (resolve(dir, "..") === dir) throw new Error("tests/vectors/unique-index not found above the test.");
+  }
+}
+const vectors = findVectors(__dirname);
+
+const CANARY = "CANARY-uidx-5e1b";
+
+const skuSchema = z.object({ sku: z.any().optional(), group: z.string().optional() });
+
+function item(type: string, where: "indexes" | "roles" | "none" = "indexes", schemaName = `tests.${type}`) {
+  return defineDocumentType({
+    type,
+    schemaId: `${schemaName}.v1`,
+    schemaName,
+    schemaVersion: `${schemaName}.v1`,
+    schema: skuSchema,
+    ...(where === "none" ? {} : { [where]: { sku: "sku" } }),
+  });
+}
+
+// A definition whose payload is never read back, so a value of any scalar kind (a bigint included) can be held and indexed.
+function scalar(type: string) {
+  const held: unknown[] = [];
+  return defineDocumentType({
+    type,
+    schemaId: `tests.${type}.v1`,
+    schemaName: `tests.${type}`,
+    schemaVersion: `tests.${type}.v1`,
+    schema: skuSchema,
+    formatter: {
+      encode: (value: unknown) => new Uint8Array([held.push(value) - 1]),
+      decode: (payload: Uint8Array) => held[payload[0]] as never,
+    },
+    indexes: { sku: "sku" },
+  });
+}
+
+function memory(...definitions: AnyCultCacheDocumentDefinition[]) {
+  let builder = CultCache.builder();
+  for (const definition of definitions) builder = builder.withDocumentType(definition);
+  return builder.build();
+}
+
+function refusal(keyA: string, keyB: string, schemaName: string, alias: string) {
+  return `Records ${keyA} and ${keyB} (${schemaName}) both hold unique index '${alias}'; an index value names one record.`;
+}
+
+test("a put of a held value at another key is refused naming both keys and the alias, and nothing moves", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "uidx-"));
+  try {
+    const file = join(dir, "items.cc");
+    const document = item("item");
+    const cache = CultCache.builder().withDocumentType(document).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+    await cache.pullAllBackingStores();
+    await cache.put(document, "zeta", { sku: CANARY });
+    const before = await readFile(file);
+    const snapshot = cache.snapshot();
+
+    await assert.rejects(cache.put(document, "alpha", { sku: CANARY }), (error: Error) => {
+      assert.equal(error.message, refusal("alpha", "zeta", "tests.item", "sku"));
+      assert.ok(!error.message.includes(CANARY), "the value is never echoed");
+      return true;
+    });
+    assert.deepEqual(await readFile(file), before, "the store is byte-identical");
+    assert.deepEqual(cache.snapshot(), snapshot);
+    assert.equal(cache.get(document, "alpha"), undefined);
+    assert.equal(cache.getKeyByIndex(document, "sku", CANARY), "zeta");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("rewriting a record's own key with its own value lands", async () => {
+  const document = item("item");
+  const cache = memory(document);
+  await cache.put(document, "a", { sku: "S", group: "one" });
+  await cache.put(document, "a", { sku: "S", group: "two" });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), "a");
+  assert.equal(cache.get(document, "a")?.group, "two");
+});
+
+test("a removed or changed holder releases its value", async () => {
+  const document = item("item");
+  const cache = memory(document);
+  await cache.put(document, "b", { sku: "S" });
+  await assert.rejects(cache.put(document, "a", { sku: "S" }), /Records a and b/u);
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), "b", "the refused write did not take the value");
+
+  await cache.delete(document, "b");
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), undefined);
+  await cache.put(document, "a", { sku: "S" });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), "a");
+
+  await cache.put(document, "a", { sku: "T" });
+  await cache.put(document, "b", { sku: "S" });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), "b");
+  assert.equal(cache.getKeyByIndex(document, "sku", "T"), "a");
+});
+
+// The C# White_Space set, and nothing else, is blank. Every UTF-16 code unit is judged, so a rule written for a few
+// characters (or for JavaScript's \s, which counts U+FEFF and omits U+0085) cannot pass.
+const CSHARP_WHITE_SPACE = (code: number) =>
+  (code >= 0x09 && code <= 0x0d) || code === 0x20 || code === 0x85 || code === 0xa0 || code === 0x1680 ||
+  (code >= 0x2000 && code <= 0x200a) || code === 0x2028 || code === 0x2029 || code === 0x202f || code === 0x205f || code === 0x3000;
+
+test("blank is exactly the C# White_Space set: every code unit, alone, repeated and padded", async () => {
+  const document = item("item");
+  const cache = memory(document);
+  const disagreements: string[] = [];
+  for (let code = 0; code <= 0xffff; code++) {
+    if (code >= 0xd800 && code <= 0xdfff) continue; // lone surrogates do not survive MessagePack text
+    const character = String.fromCharCode(code);
+    await cache.put(document, "x", { sku: character });
+    let blank = true;
+    try {
+      await cache.put(document, "y", { sku: character });
+    } catch {
+      blank = false;
+    }
+    if (blank !== CSHARP_WHITE_SPACE(code)) disagreements.push(code.toString(16));
+    await cache.delete(document, "x");
+    await cache.delete(document, "y");
+  }
+  assert.deepEqual(disagreements, []);
+
+  // Not trimmed: a padded value is the value, distinct from its trimmed form.
+  await cache.put(document, "x", { sku: " a " });
+  await cache.put(document, "y", { sku: "a" });
+  assert.equal(cache.getKeyByIndex(document, "sku", " a "), "x");
+  assert.equal(cache.getKeyByIndex(document, "sku", "a"), "y");
+  await assert.rejects(cache.put(document, "z", { sku: " a " }), /Records x and z/u);
+});
+
+test("blank values are never indexed and never conflict: empty, spaces, absent", async () => {
+  const document = item("item");
+  const cache = memory(document);
+  for (const [key, sku] of [["a", ""], ["b", " "], ["c", "\u0085"], ["d", undefined], ["e", "　"]] as const) {
+    await cache.put(document, key, { sku });
+  }
+  assert.equal(cache.getKeyByIndex(document, "sku", ""), undefined);
+  assert.equal(cache.getKeyByIndex(document, "sku", " "), undefined);
+  // U+FEFF and U+001F are values.
+  await cache.put(document, "f", { sku: "" });
+  await assert.rejects(cache.put(document, "g", { sku: "" }), /Records f and g/u);
+  await cache.put(document, "h", { sku: "\u001F" });
+  await assert.rejects(cache.put(document, "i", { sku: "\u001F" }), /Records h and i/u);
+});
+
+test("two types may share an alias and a value", async () => {
+  const first = item("first");
+  const second = item("second");
+  const cache = memory(first, second);
+  await cache.put(first, "a", { sku: "S" });
+  await cache.put(second, "b", { sku: "S" });
+  assert.equal(cache.getKeyByIndex(first, "sku", "S"), "a");
+  assert.equal(cache.getKeyByIndex(second, "sku", "S"), "b");
+});
+
+test("roles may share values and are not looked up", async () => {
+  const document = item("item", "roles");
+  const cache = memory(document);
+  await cache.put(document, "a", { sku: "S" });
+  await cache.put(document, "b", { sku: "S" });
+  await cache.put(document, "c", { sku: "S" });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), undefined);
+  assert.equal(cache.getByIndex(document, "sku", "S"), undefined);
+});
+
+test("an alias declared in indexes and roles is refused at definition; each map is checked like indexes", () => {
+  const base = { type: "bad", schema: skuSchema, schemaId: "tests.bad.v1", schemaName: "tests.bad", schemaVersion: "tests.bad.v1" };
+  assert.throws(
+    () => defineDocumentType({ ...base, indexes: { sku: "sku" }, roles: { sku: "sku" } }),
+    { message: 'CultCache document type "bad" declares "sku" as both an index and a role; an index already names its role.' },
+  );
+  assert.throws(() => defineDocumentType({ ...base, roles: { " ": "sku" } }), /declares a role with an empty name/u);
+  assert.throws(
+    () => defineDocumentType({ ...base, roles: [{ name: "r", accessor: "sku" }, { name: "r", accessor: "group" }] }),
+    /declares duplicate role "r"/u,
+  );
+  assert.doesNotThrow(() => defineDocumentType({ ...base, indexes: { sku: "sku" }, roles: { group: "group" } }));
+});
+
+test("a codec definition's catalog entry is identical with an alias under indexes or roles", async () => {
+  const codec = codecs.slots<{ sku: string; group: string }>({ 0: ["sku", codecs.string], 1: ["group", codecs.string] }, "T.Item");
+  const make = (where: "indexes" | "roles") =>
+    defineDocumentType({
+      type: "codec_item",
+      schemaId: "tests.codec_item.v1",
+      schemaName: "tests.codec_item",
+      schemaVersion: "tests.codec_item.v1",
+      schema: z.object({ sku: z.string(), group: z.string() }),
+      codec,
+      [where]: { sku: "sku" },
+    });
+  const catalog = async (definition: AnyCultCacheDocumentDefinition) => {
+    const cache = memory(definition);
+    await cache.put(definition, "a", { sku: "S", group: "g" } as never);
+    return cache.snapshot()[0].catalogEntry!;
+  };
+  const members = (definition: AnyCultCacheDocumentDefinition) => resolveDocumentMembers(definition);
+  assert.deepEqual(members(make("indexes")), members(make("roles")));
+  assert.equal(members(make("roles")).find((member) => member.memberName === "Sku")?.indexAlias, "sku");
+  const [unique, role] = [await catalog(make("indexes")), await catalog(make("roles"))];
+  assert.equal(unique.canonicalSchemaJson, role.canonicalSchemaJson);
+  assert.equal(unique.contentHash, role.contentHash);
+  assert.equal(unique.schemaId, role.schemaId);
+});
+
+test("vectors values.msgpack: every row's canonical text, blank rows no value", async () => {
+  const rows = decode(await readFile(join(vectors, "values.msgpack")), { useBigInt64: true }) as [string, string, unknown, string | null][];
+  assert.ok(rows.length >= 20);
+  for (const [label, kind, value, text] of rows) {
+    const document = scalar(`value_${label.replaceAll(/[^a-z0-9]/gu, "_")}`);
+    const cache = memory(document);
+    void kind;
+    const normalized = value;
+    await cache.put(document, "one", { sku: normalized });
+    if (text === null) {
+      await cache.put(document, "two", { sku: normalized });
+      assert.equal(cache.get(document, "two") !== undefined, true, `${label}: a blank value commits twice`);
+      for (const probe of ["", " ", "NaN", "0", "Infinity", "-Infinity", "null", "undefined"]) {
+        assert.equal(cache.getKeyByIndex(document, "sku", probe), undefined, `${label}: found by '${probe}'`);
+      }
+    } else {
+      assert.equal(cache.getKeyByIndex(document, "sku", text), "one", `${label}: found by its text`);
+      await assert.rejects(cache.put(document, "two", { sku: normalized }), /Records one and two/u, label);
+    }
+  }
+});
+
+// An independent oracle for the double rule: the text must denote exactly the double, so N / 10^d == mantissa * 2^exponent
+// in exact integer arithmetic, with no trailing zero and no bare point. A rule written to a few spellings cannot pass.
+function exactlyDenotes(text: string, value: number): boolean {
+  const match = /^(-?)(\d+)(?:\.(\d*[1-9]))?$/u.exec(text);
+  if (!match) return false;
+  const decimals = match[3]?.length ?? 0;
+  const numerator = BigInt(match[2] + (match[3] ?? ""));
+  const view = new DataView(new ArrayBuffer(8));
+  view.setFloat64(0, Math.abs(value));
+  const bits = view.getBigUint64(0);
+  const biased = Number((bits >> 52n) & 0x7ffn);
+  const mantissa = biased === 0 ? bits & 0xfffffffffffffn : (bits & 0xfffffffffffffn) | (1n << 52n);
+  const exponent = (biased === 0 ? 1 : biased) - 1075;
+  const lhs = numerator * (exponent >= 0 ? 1n : 2n ** BigInt(-exponent));
+  const rhs = mantissa * (exponent >= 0 ? 2n ** BigInt(exponent) : 1n) * 10n ** BigInt(decimals);
+  return (match[1] === "-") === (value < 0) && lhs === rhs;
+}
+
+test("a number's index text is its exact value: integers as digits, doubles as the exact expansion, NaN and infinities none", async () => {
+  const document = scalar("number");
+  const cache = memory(document);
+  const probes = [0.1, -0.1, 2.5e-7, 1.5, -123.456, 5e-324, 2.2250738585072014e-308, 1e-10, 123456789.123456789, Number.MIN_VALUE * 3,
+    ...Array.from({ length: 200 }, (_, i) => Math.sin(i + 1) * 10 ** ((i % 40) - 20)), 1e21 + 2 ** 20 + 0.5 * 0];
+  // Round trip through lookups: the exact expansion of each probe is found, and it denotes the probe exactly.
+  for (const value of probes) {
+    if (Number.isInteger(value)) continue;
+    await cache.put(document, "k", { sku: value });
+    const candidates = candidateTexts(value);
+    const found = candidates.filter((candidate) => cache.getKeyByIndex(document, "sku", candidate) === "k");
+    assert.equal(found.length, 1, `${value}: exactly one spelling is its index text`);
+    assert.ok(exactlyDenotes(found[0], value), `${value}: ${found[0]} denotes it exactly`);
+  }
+
+  await cache.put(document, "k", { sku: 1e21 });
+  assert.equal(cache.getKeyByIndex(document, "sku", "1000000000000000000000"), "k");
+  await cache.put(document, "k", { sku: -0 });
+  assert.equal(cache.getKeyByIndex(document, "sku", "0"), "k");
+  await cache.put(document, "k", { sku: 12n });
+  assert.equal(cache.getKeyByIndex(document, "sku", "12"), "k");
+  await cache.put(document, "k", { sku: true });
+  assert.equal(cache.getKeyByIndex(document, "sku", "True"), "k");
+  await cache.put(document, "k", { sku: false });
+  assert.equal(cache.getKeyByIndex(document, "sku", "False"), "k");
+  for (const value of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+    await cache.put(document, "p", { sku: value });
+    await cache.put(document, "q", { sku: value });
+  }
+});
+
+// Spellings a lookup could be probed with: the exact decimal expansion computed by an arbitrary-precision route.
+function candidateTexts(value: number): string[] {
+  const view = new DataView(new ArrayBuffer(8));
+  view.setFloat64(0, Math.abs(value));
+  const bits = view.getBigUint64(0);
+  const biased = Number((bits >> 52n) & 0x7ffn);
+  const mantissa = biased === 0 ? bits & 0xfffffffffffffn : (bits & 0xfffffffffffffn) | (1n << 52n);
+  const k = 1075 - (biased === 0 ? 1 : biased);
+  const scaled = (mantissa * 5n ** BigInt(k)).toString().padStart(k + 1, "0");
+  const point = scaled.length - k;
+  const text = `${scaled.slice(0, point)}.${scaled.slice(point)}`.replace(/0+$/u, "").replace(/\.$/u, "");
+  return [(value < 0 ? "-" : "") + text, String(value), value.toString()].filter((spelling, i, all) => all.indexOf(spelling) === i);
+}
+
+function twoDefinitions(schemaId: string, where: "indexes" | "roles") {
+  return defineDocumentType({
+    type: "unique_item",
+    schemaId,
+    schemaName: "tests.unique_item",
+    schemaVersion: "tests.unique_item.v1",
+    schema: z.object({ sku: z.string(), category: z.string() }),
+    codec: codecs.slots<{ sku: string; category: string }>({ 0: ["sku", codecs.string], 1: ["category", codecs.string] }, "UqVecItem"),
+    [where]: { Sku: "sku" },
+  });
+}
+
+test("vectors duplicate-store.cc and blank-store.cc hold their verdicts", async () => {
+  const outcomes = decode(await readFile(join(vectors, "outcomes.msgpack"))) as [string, string | null, string, string | null, string | null][];
+  assert.equal(outcomes.length, 3);
+  const dir = await mkdtemp(join(tmpdir(), "uidx-vec-"));
+  try {
+    for (const [name, alias, outcome, key1, key2] of outcomes) {
+      const file = join(dir, `${outcomes.indexOf(outcomes.find((row) => row[0] === name && row[1] === alias)!)}-${name}`);
+      await copyFile(join(vectors, name), file);
+      const before = await readFile(file);
+      const [envelope] = await new SingleFileMessagePackBackingStore(file).pullAll();
+      const document = twoDefinitions(envelope.schemaId!, alias === null ? "roles" : "indexes");
+      const cache = CultCache.builder().withDocumentType(document).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      const stateBefore = cache.snapshot();
+      if (outcome === "open") {
+        await cache.pullAllBackingStores();
+        assert.equal(cache.snapshot().length, name === "blank-store.cc" ? 2 : 4);
+        if (alias === null) assert.equal(cache.getKeyByIndex(document, "Sku", "S-1"), undefined);
+      } else {
+        await assert.rejects(cache.pullAllBackingStores(), (error: Error) => {
+          assert.equal(error.message, refusal(key1!, key2!, "tests.unique_item", alias!));
+          assert.ok(!error.message.includes("S-1"));
+          return true;
+        });
+        assert.deepEqual(cache.snapshot(), stateBefore, "a refused load admits nothing");
+      }
+      assert.deepEqual(await readFile(file), before, `${name} is untouched`);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+// refusals.msgpack: rows [label, ops, refusal] written by the C# reference. TypeScript has no batch commit
+// (variants:idea:unique-index-runtimes.ts-batch-commit), so it performs every row whose commits each hold one record:
+// 5, 8-13, 19-22, 24, 25, 27, 29, 31, 32, 33, 35 and 37 of the README (20).
+const REFUSAL_SCHEMAS: [string, string, string, Record<string, "sku" | "second">][] = [
+  ["unique_item", "tests.unique_item", "sha256:93bb890de83069061af696b23f94fd32fb3c2dad3c91ee645e8add56085f1882", { Sku: "sku" }],
+  ["uq_pair", "tests.uq_pair", "sha256:2538cceafb6dcbce22ef11b932ecb804af5f96bc3aaedff692a52d3640433e60", { Sku: "sku", Alt: "second" }],
+  ["uq_alias", "tests.uq_alias", "sha256:77a77a394ebd8bf71e14b9b6f2cea4978c25d4e705fd12364f660edbf6c63b1f", { Sku: "sku", alt: "second" }],
+  ["uq_wide", "tests.uq_wide", "sha256:b79eecd11eed5e456902f095d2748da7f59125c4c8972b0da7dddc81d07fc03f", { "\uFF21": "sku", "\u{10400}": "second" }],
+  ["uq_alpha", "tests.uq_alpha", "sha256:53aeaf2ea9b25e85ade6b15fc04c7653e7b206c87e258f1aa74dd32a840a1389", { Sku: "sku" }],
+  ["uq_beta", "tests.uq_beta", "sha256:45ed62a64c91f6d815d3ec975c4a4a1b2ce07b6e7262a32d828673cf10899586", { Sku: "sku" }],
+];
+
+type RefusalOp = ["open", string | null] | ["pull", string] | ["commit", [string, string, string, string][]];
+
+test("vectors refusals.msgpack: every row TS can perform", async () => {
+  const rows = decode(await readFile(join(vectors, "refusals.msgpack"))) as [string, RefusalOp[], [string, string, string, string] | null][];
+  const definitions = new Map(
+    REFUSAL_SCHEMAS.map(([type, schemaName, schemaId, indexes]) => [
+      schemaName,
+      defineDocumentType({
+        type,
+        schemaId,
+        schemaName,
+        schemaVersion: `${schemaName}.v1`,
+        schema: z.object({ sku: z.string(), second: z.string() }),
+        codec: codecs.slots<{ sku: string; second: string }>({ 0: ["sku", codecs.string], 1: ["second", codecs.string] }, `Uq${type}`),
+        indexes,
+      }),
+    ]),
+  );
+  const dir = await mkdtemp(join(tmpdir(), "uidx-refusals-"));
+  let walked = 0;
+  try {
+    for (const [label, ops, refused] of rows) {
+      if (ops.some((op) => op[0] === "commit" && op[1].length > 1)) continue;
+      const file = join(dir, `${walked}.cc`);
+      let cache: CultCache | undefined;
+      const perform = async (op: RefusalOp) => {
+        if (op[0] === "open") {
+          if (op[1] !== null) await copyFile(join(vectors, op[1]), file);
+          let builder = CultCache.builder().withGenericStore(new SingleFileMessagePackBackingStore(file));
+          for (const definition of definitions.values()) builder = builder.withDocumentType(definition);
+          cache = builder.build();
+          await cache.pullAllBackingStores();
+        } else if (op[0] === "pull") {
+          await copyFile(join(vectors, op[1]), file);
+          await cache!.pullAllBackingStores();
+        } else {
+          for (const [key, schema, sku, second] of op[1]) await cache!.put(definitions.get(schema)!, key, { sku, second });
+        }
+      };
+      for (const op of ops.slice(0, -1)) await perform(op);
+      const last = ops[ops.length - 1];
+      if (refused === null) {
+        await perform(last);
+      } else {
+        const [k1, k2, schema, alias] = refused;
+        const before = last[0] === "commit" || (last[0] === "open" && last[1] === null)
+          ? (existsSync(file) ? await readFile(file) : Buffer.alloc(0))
+          : await readFile(join(vectors, last[1]!));
+        await assert.rejects(perform(last), { message: refusal(k1, k2, schema, alias) }, label);
+        assert.deepEqual(existsSync(file) ? await readFile(file) : Buffer.alloc(0), before, `${label}: the file is untouched`);
+      }
+      walked++;
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+  assert.equal(walked, 20);
+});
+
+test("a refused load leaves the cache's prior state as it was, and a later good load still works", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "uidx-load-"));
+  try {
+    const bad = join(dir, "bad.cc");
+    await copyFile(join(vectors, "duplicate-store.cc"), bad);
+    const [envelope] = await new SingleFileMessagePackBackingStore(bad).pullAll();
+    const document = twoDefinitions(envelope.schemaId!, "indexes");
+    const cache = CultCache.builder().withDocumentType(document).withGenericStore(new SingleFileMessagePackBackingStore(bad)).build();
+    await assert.rejects(cache.pullAllBackingStores(), /Records item:a and item:b/u);
+    assert.equal(cache.get(document, "item:a"), undefined);
+    assert.equal(cache.getKeyByIndex(document, "Sku", "S-1"), undefined);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("registerIndex refuses a name the definition declares as a role", async () => {
+  const document = item("item", "roles");
+  const cache = memory(document);
+  await cache.put(document, "a", { sku: "S", group: "g" });
+  await cache.put(document, "b", { sku: "S", group: "h" });
+  await assert.rejects(cache.registerIndex(document, "sku", "sku"), { message: /declared as a role; a role is never a unique index/u });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), undefined);
+  await cache.put(document, "c", { sku: "S", group: "i" });
+});
+
+test("registerIndex over held duplicates installs nothing", async () => {
+  const document = item("item", "none");
+  const cache = memory(document);
+  await cache.put(document, "a", { sku: "S", group: "g" });
+  await cache.put(document, "b", { sku: "S", group: "h" });
+  await assert.rejects(cache.registerIndex(document, "sku", "sku"), { message: refusal("a", "b", "tests.item", "sku") });
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), undefined, "no map was installed");
+  await cache.put(document, "c", { sku: "S", group: "i" });
+  await cache.registerIndex(document, "group", "group");
+  assert.equal(cache.getKeyByIndex(document, "group", "h"), "b");
+  await assert.rejects(cache.put(document, "d", { sku: "x", group: "h" }), /Records b and d/u);
+});
+
+test("registerIndex over distinct held values installs the lookup", async () => {
+  const document = item("item", "none");
+  const cache = memory(document);
+  await cache.put(document, "a", { sku: "S" });
+  await cache.registerIndex(document, "sku", "sku");
+  assert.equal(cache.getKeyByIndex(document, "sku", "S"), "a");
+});
+
+// ---- a type with several unique indexes: the second alias is judged, in alias order, in both judges ----
+
+const pairSchema = z.object({ a: z.string().optional(), b: z.string().optional() });
+
+function pair(where: { indexes?: Record<string, "a" | "b">; roles?: Record<string, "a" | "b"> }) {
+  return defineDocumentType({
+    type: "pair",
+    schemaId: "tests.pair.v1",
+    schemaName: "tests.pair",
+    schemaVersion: "tests.pair.v1",
+    schema: pairSchema,
+    ...where,
+  });
+}
+
+// Declared b first, so insertion order is the opposite of alias order.
+const BOTH_UNIQUE = { indexes: { b: "b", a: "a" } as Record<string, "a" | "b"> };
+
+test("a collision on the second unique alias is refused, with a value on the first alias that does not collide", async () => {
+  const document = pair(BOTH_UNIQUE);
+  const cache = memory(document);
+  await cache.put(document, "k1", { a: "x1", b: "shared" });
+  await assert.rejects(cache.put(document, "k2", { a: "x2", b: "shared" }), { message: refusal("k1", "k2", "tests.pair", "b") });
+  await assert.rejects(cache.put(document, "k2", { a: "x1", b: "y" }), { message: refusal("k1", "k2", "tests.pair", "a") });
+  assert.equal(cache.get(document, "k2"), undefined);
+});
+
+test("when two aliases collide the first alias in ordinal order is named, and its keys are in ordinal order", async () => {
+  const document = pair(BOTH_UNIQUE);
+  const cache = memory(document);
+  await cache.put(document, "m", { a: "same-a", b: "same-b" });
+  await assert.rejects(cache.put(document, "c", { a: "same-a", b: "same-b" }), { message: refusal("c", "m", "tests.pair", "a") });
+  // The colliding holders differ per alias: a is held by m, b by n; alias a is still the one named.
+  await cache.put(document, "n", { a: "other-a", b: "other-b" });
+  await assert.rejects(cache.put(document, "z", { a: "same-a", b: "other-b" }), { message: refusal("m", "z", "tests.pair", "a") });
+});
+
+test("a load judges every unique alias: a store collision on the second alias refuses the open", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "uidx-pair-"));
+  try {
+    for (const [name, records, expected] of [
+      ["second-only", [["k1", { a: "1", b: "s" }], ["k2", { a: "2", b: "s" }]], refusal("k1", "k2", "tests.pair", "b")],
+      ["both-aliases", [["m", { a: "s", b: "s" }], ["c", { a: "s", b: "s" }]], refusal("c", "m", "tests.pair", "a")],
+    ] as const) {
+      const file = join(dir, `${name}.cc`);
+      const roles = pair({ roles: { b: "b", a: "a" } });
+      const writer = CultCache.builder().withDocumentType(roles).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      for (const [key, value] of records) await writer.put(roles, key, value);
+      const before = await readFile(file);
+
+      const unique = pair(BOTH_UNIQUE);
+      const reader = CultCache.builder().withDocumentType(unique).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      await assert.rejects(reader.pullAllBackingStores(), { message: expected }, name);
+      assert.deepEqual(reader.snapshot(), [], "a refused load admits nothing");
+      assert.deepEqual(await readFile(file), before);
+
+      const rolesReader = CultCache.builder().withDocumentType(roles).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      await rolesReader.pullAllBackingStores();
+      assert.equal(rolesReader.snapshot().length, 2, `${name}: the same store opens under roles`);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("registerIndex of a second unique alias judges it, naming the two smallest keys whatever order they were written in", async () => {
+  const document = pair({ indexes: { a: "a" } });
+  const cache = memory(document);
+  await cache.put(document, "z", { a: "1", b: "s" });
+  await cache.put(document, "m", { a: "2", b: "s" });
+  await cache.put(document, "q", { a: "3", b: "s" });
+  await assert.rejects(cache.registerIndex(document, "b", "b"), { message: refusal("m", "q", "tests.pair", "b") });
+  assert.equal(cache.getKeyByIndex(document, "a", "1"), "z", "the alias already installed is intact");
+  assert.equal(cache.getKeyByIndex(document, "b", "s"), undefined);
+});
+
+// ---- the single-put judge's two orders, which no pair-order vector row reaches from TS (a vector row's second record
+// arrives in a batch that TS cannot perform): aliases by UTF-16 code unit, then the key pair by UTF-16 code unit ----
+
+test("a put colliding on two aliases names the one least by UTF-16 code unit, not by code point", async () => {
+  // U+10400 is the surrogate pair D801 DC00, so it sorts before U+FF21 by code unit and after it by code point.
+  const document = pair({ indexes: { "Ａ": "a", "\u{10400}": "b" } });
+  const cache = memory(document);
+  await cache.put(document, "h1", { a: "s1", b: "t1" });
+  await cache.put(document, "h2", { a: "s2", b: "t2" });
+  await assert.rejects(cache.put(document, "p", { a: "s1", b: "t2" }), { message: refusal("h2", "p", "tests.pair", "\u{10400}") });
+  assert.equal(cache.get(document, "p"), undefined);
+});
+
+test("a put names its key pair by UTF-16 code unit, not by normalised form", async () => {
+  // "e" U+0302 is the NFD form of U+00EA: equal when normalised, and less by code unit.
+  const document = item("item");
+  const cache = memory(document);
+  await cache.put(document, "ê", { sku: "v" });
+  await assert.rejects(cache.put(document, "ê", { sku: "v" }), { message: refusal("ê", "ê", "tests.item", "sku") });
+  assert.equal(cache.get(document, "ê"), undefined);
+});
+
+test("a put colliding on two aliases orders them by UTF-16 code unit, not by normalised form", async () => {
+  // U+00EA normalises to e U+0302, which is less than e U+0303 when normalised and greater by code unit.
+  const document = pair({ indexes: { "ê": "a", "ẽ": "b" } });
+  const cache = memory(document);
+  await cache.put(document, "h1", { a: "s1", b: "t1" });
+  await cache.put(document, "h2", { a: "s2", b: "t2" });
+  await assert.rejects(cache.put(document, "p", { a: "s1", b: "t2" }), { message: refusal("h2", "p", "tests.pair", "ẽ") });
+});

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.5.0</Version>
+    <Version>0.5.1</Version>
     <Description>Clean-room C# math shaped for HLSL-style renderer code.</Description>
     <Authors>GameCult</Authors>
     <PackageReadmeFile>README.md</PackageReadmeFile>

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

@@ -5,7 +5,7 @@ All notable changes to this package are documented in this file.
 Earlier releases (0.2.0-0.2.3) predate this package's changelog and are not
 backfilled here; see `docs/semver-policy.md` for why.
 
-## [Unreleased]
+## [0.5.1] - 2026-11-11
 
 ### Added
 

packages/cultmath/unity/org.gamecult.cultmath/package.json

@@ -1,7 +1,7 @@
 {
   "name": "org.gamecult.cultmath",
   "displayName": "CultMath",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "unity": "2021.3",
   "description": "Precompiled CultMath numeric primitives and matching HLSL semantics for GameCult Unity runtimes.",
   "license": "MIT AND MPL-2.0 AND Apache-2.0",

packages/cultmesh-browser/package.json

@@ -41,7 +41,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@gamecult/cultcache-ts": "^0.14.0",
+    "@gamecult/cultcache-ts": "^0.15.0",
     "@gamecult/cultnet-ts": "^0.3.0"
   },
   "devDependencies": {

packages/cultmesh-browser/test/content.test.ts

@@ -567,8 +567,14 @@ test("a size the runtime cannot allocate is too-large in both exports, not a Ran
   const count = 2 ** 15;
   const huge = { ...manifest, sizeBytes: count * int32Max, chunks: Array.from({ length: count }, (_, index) => ({ ...manifest.chunks[0]!, offset: index * int32Max, sizeBytes: int32Max })) };
   const server = double(() => { throw new Error("no request expected"); });
-  await assert.rejects(fetchVerifiedContent(ENDPOINT, huge, { fetch: server.fetch, maxBytes: size }), codeOf("too-large"));
-  await assert.rejects(fetchVerifiedChunk(ENDPOINT, manifest.chunks[0]!.chunkHash!, size, { fetch: server.fetch, maxBytes: size }), codeOf("too-large"));
+  // a host with overcommit hands out 64 TiB lazily, so the refusal is made certain: the runtime cannot allocate it
+  const native = globalThis.Uint8Array;
+  const refusing = new Proxy(native, { construct: (target, args, receiver) => { if (typeof args[0] === "number" && args[0] > 2 ** 40) throw new RangeError("Array buffer allocation failed"); return Reflect.construct(target, args, receiver); } });
+  globalThis.Uint8Array = refusing;
+  try {
+    await assert.rejects(fetchVerifiedContent(ENDPOINT, huge, { fetch: server.fetch, maxBytes: size }), codeOf("too-large"));
+    await assert.rejects(fetchVerifiedChunk(ENDPOINT, manifest.chunks[0]!.chunkHash!, size, { fetch: server.fetch, maxBytes: size }), codeOf("too-large"));
+  } finally { globalThis.Uint8Array = native; }
   assert.equal(server.calls.length, 0);
 });
 

packages/cultmesh-kotlin/README.md

@@ -474,3 +474,14 @@ powershell -ExecutionPolicy Bypass -File .\packages\cultmesh-kotlin\build.ps1
 The build writes `artifacts/cultmesh-kotlin/cultmesh-kotlin.jar`.
 It also runs the built-in RUDP packet fixture and localhost UDP socket
 self-test.
+
+## Write Receipt
+
+`WriteReceipt.kt` decodes `cultnet.write_admitted.v0` and `cultnet.error.v1` (and `error.v0`) strictly against their
+closed schemas (`decodeWriteAdmitted`, `decodeErrorFrame`), computes the dedupe `writeContentHash`, tests a hello with
+`helloAdvertisesWriteReceipts`, and settles sent writes as admitted, refused or unconfirmed in `WriteTracker`
+(pure state machine, abstract clock; the caller owns transport and timers). Kotlin has no write client yet, so nothing
+sends a put and waits on this. `WriteReceiptVectors.kt` replays
+`contracts/cultnet/interop/write-receipt-vectors.json` (constants, contentHash, wire, schemaInvalid, scenarios; the
+server-side `dedupe` and `blankFields` sections are not run); `build.ps1` runs it after the self-test, or run
+`CultMeshKt write-receipt-vectors <path>`.

packages/cultmesh-kotlin/build.ps1

@@ -26,4 +26,7 @@ $sources = Get-ChildItem $src -Recurse -Filter *.kt | Select-Object -ExpandPrope
 if ($LASTEXITCODE -ne 0) { throw "kotlinc failed with exit code $LASTEXITCODE" }
 & $java -cp "$jarPath;$kotlinStdlib" org.gamecult.cultmesh.CultMeshKt
 if ($LASTEXITCODE -ne 0) { throw "cultmesh-kotlin self-test failed with exit code $LASTEXITCODE" }
+$vectors = Join-Path $repoRoot "contracts\cultnet\interop\write-receipt-vectors.json"
+& $java -cp "$jarPath;$kotlinStdlib" org.gamecult.cultmesh.CultMeshKt write-receipt-vectors $vectors
+if ($LASTEXITCODE -ne 0) { throw "write-receipt vector replay failed with exit code $LASTEXITCODE" }
 Write-Host "Built $jarPath"

packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt

@@ -19,6 +19,7 @@ import java.net.Socket
 import java.net.SocketTimeoutException
 import java.net.URI
 import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
 import java.nio.charset.StandardCharsets
 import java.security.SecureRandom
 import java.security.MessageDigest
@@ -808,6 +809,7 @@ interface CultNetSchemaMessageTransport : AutoCloseable {
     val profile: CultNetTransportProfile
     val stats: CultNetTransportStats
 
+    /** Fire-and-forget: an ack or a return is not admission; read the result frame. */
     fun sendSchemaMessage(message: CultNetMessage)
 
     fun receiveSchemaMessage(timeoutMs: Long = 1_000, pollIntervalMs: Long = 5): CultNetMessage?
@@ -1099,9 +1101,9 @@ data class CultNetRawDocumentRecord(
             "payloadEncoding" to payloadEncoding,
             "payload" to payload.copyOf(),
         )
-        if (!sourceRuntimeId.isNullOrBlank()) wire["sourceRuntimeId"] = sourceRuntimeId
-        if (!sourceAgentId.isNullOrBlank()) wire["sourceAgentId"] = sourceAgentId
-        if (!sourceRole.isNullOrBlank()) wire["sourceRole"] = sourceRole
+        if (!isBlankText(sourceRuntimeId)) wire["sourceRuntimeId"] = sourceRuntimeId
+        if (!isBlankText(sourceAgentId)) wire["sourceAgentId"] = sourceAgentId
+        if (!isBlankText(sourceRole)) wire["sourceRole"] = sourceRole
         if (tags.isNotEmpty()) wire["tags"] = tags
         return wire
     }
@@ -2363,6 +2365,9 @@ fun parseCultNetMessage(payload: ByteArray): CultNetMessage {
     if (schemaVersion !is String || schemaVersion.isBlank()) {
         throw IOException("CultNet schema-v0 messages must declare schemaVersion")
     }
+    // A write_admitted id is echoed byte for byte, so that frame alone is read again with invalid UTF-8 refused; document payload
+    // strings elsewhere keep decoding as before.
+    if (schemaVersion == WRITE_ADMITTED_VERSION) MessagePackReader(payload, strictUtf8 = true).readAny()
     val body = linkedMapOf<String, Any?>()
     for ((key, value) in decoded) {
         if (key !is String) throw IOException("CultNet schema-v0 message keys must be strings")
@@ -3167,13 +3172,16 @@ class CultNetRudpSocketTransportConnection(
         return connected
     }
 
+    /** Fire-and-forget: an ack or a return is not admission; read the result frame. */
     fun send(channelId: String, payload: ByteArray) {
         session.sendMany(channelId, payload, channelSendOptions(channelId, nowMs()), maxFragmentBytes).forEach { sendPacket(it) }
         framesSent += 1
     }
 
+    /** Fire-and-forget: an ack or a return is not admission; read the result frame. */
     fun send(channelId: String, payload: String) = send(channelId, payload.toByteArray(StandardCharsets.UTF_8))
 
+    /** Fire-and-forget: an ack or a return is not admission; read the result frame. */
     fun sendSchema(payload: ByteArray) = send("schema", payload)
 
     fun sendSchema(payload: String) = sendSchema(payload.toByteArray(StandardCharsets.UTF_8))
@@ -3409,6 +3417,7 @@ fun main(args: Array<String>) {
         rudpClientBindsLoopbackOnlyForALoopbackEndpoint()
         rudpSocketTransportHandshakesAndCarriesReliableOrderedSchemaFrames()
         rudpSocketTransportCarriesFragmentedReliableOrderedSchemaFrames()
+        rawDocumentRecordDropsOnlyWhiteSpaceSourceIds()
         return
     }
 
@@ -3420,6 +3429,7 @@ fun main(args: Array<String>) {
         "rudp-dial-message-once" -> rudpDialSchemaMessageOnce(options)
         "serve" -> interopServe(options)
         "dial" -> interopDial(options)
+        "write-receipt-vectors" -> if (!replayWriteReceiptVectors(args.getOrNull(1) ?: error("usage: write-receipt-vectors <vectors.json>"))) kotlin.system.exitProcess(1)
         else -> error("Unknown mode ${args[0]}")
     }
 }
@@ -6145,7 +6155,8 @@ private fun requireSchemaResponse(message: CultNetMessage?, expectedSchemaVersio
     return response
 }
 
-class MessagePackReader(payload: ByteArray) {
+/** [strictUtf8] makes a str whose bytes are not UTF-8 throw instead of becoming U+FFFD; only the write_admitted frame asks for it. */
+class MessagePackReader(payload: ByteArray, private val strictUtf8: Boolean = false) {
     private val input = DataInputStream(ByteArrayInputStream(payload))
     private var pushed = -1
 
@@ -6300,7 +6311,10 @@ class MessagePackReader(payload: ByteArray) {
             code == 0xdb -> input.readInt()
             else -> throw IOException("expected string")
         }
-        return String(readPayload(length), StandardCharsets.UTF_8)
+        val bytes = readPayload(length)
+        if (!strictUtf8) return String(bytes, StandardCharsets.UTF_8)
+        return StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT)
+            .decode(ByteBuffer.wrap(bytes)).toString()
     }
 
     private fun readBinaryAfterCode(code: Int): ByteArray {

packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/UnicodeMessageIdTables.kt

@@ -0,0 +1,129 @@
+// generated, Unicode 16.0.0, by scripts/gen-unicode-messageid-tables.py (inputs sha256 24a07ef9fabf71e3); do not edit
+
+package org.gamecult.cultmesh
+
+// (low, high) pairs, flattened and sorted.
+internal val LETTER_OR_NUMBER: IntArray = intArrayOf(
+    0x30, 0x39, 0x41, 0x5A, 0x61, 0x7A, 0xAA, 0xAA, 0xB2, 0xB3, 0xB5, 0xB5, 0xB9, 0xBA, 0xBC, 0xBE, 0xC0, 0xD6, 0xD8,
+    0xF6, 0xF8, 0x2C1, 0x2C6, 0x2D1, 0x2E0, 0x2E4, 0x2EC, 0x2EC, 0x2EE, 0x2EE, 0x370, 0x374, 0x376, 0x377, 0x37A,
+    0x37D, 0x37F, 0x37F, 0x386, 0x386, 0x388, 0x38A, 0x38C, 0x38C, 0x38E, 0x3A1, 0x3A3, 0x3F5, 0x3F7, 0x481, 0x48A,
+    0x52F, 0x531, 0x556, 0x559, 0x559, 0x560, 0x588, 0x5D0, 0x5EA, 0x5EF, 0x5F2, 0x620, 0x64A, 0x660, 0x669, 0x66E,
+    0x66F, 0x671, 0x6D3, 0x6D5, 0x6D5, 0x6E5, 0x6E6, 0x6EE, 0x6FC, 0x6FF, 0x6FF, 0x710, 0x710, 0x712, 0x72F, 0x74D,
+    0x7A5, 0x7B1, 0x7B1, 0x7C0, 0x7EA, 0x7F4, 0x7F5, 0x7FA, 0x7FA, 0x800, 0x815, 0x81A, 0x81A, 0x824, 0x824, 0x828,
+    0x828, 0x840, 0x858, 0x860, 0x86A, 0x870, 0x887, 0x889, 0x88E, 0x8A0, 0x8C9, 0x904, 0x939, 0x93D, 0x93D, 0x950,
+    0x950, 0x958, 0x961, 0x966, 0x96F, 0x971, 0x980, 0x985, 0x98C, 0x98F, 0x990, 0x993, 0x9A8, 0x9AA, 0x9B0, 0x9B2,
+    0x9B2, 0x9B6, 0x9B9, 0x9BD, 0x9BD, 0x9CE, 0x9CE, 0x9DC, 0x9DD, 0x9DF, 0x9E1, 0x9E6, 0x9F1, 0x9F4, 0x9F9, 0x9FC,
+    0x9FC, 0xA05, 0xA0A, 0xA0F, 0xA10, 0xA13, 0xA28, 0xA2A, 0xA30, 0xA32, 0xA33, 0xA35, 0xA36, 0xA38, 0xA39, 0xA59,
+    0xA5C, 0xA5E, 0xA5E, 0xA66, 0xA6F, 0xA72, 0xA74, 0xA85, 0xA8D, 0xA8F, 0xA91, 0xA93, 0xAA8, 0xAAA, 0xAB0, 0xAB2,
+    0xAB3, 0xAB5, 0xAB9, 0xABD, 0xABD, 0xAD0, 0xAD0, 0xAE0, 0xAE1, 0xAE6, 0xAEF, 0xAF9, 0xAF9, 0xB05, 0xB0C, 0xB0F,
+    0xB10, 0xB13, 0xB28, 0xB2A, 0xB30, 0xB32, 0xB33, 0xB35, 0xB39, 0xB3D, 0xB3D, 0xB5C, 0xB5D, 0xB5F, 0xB61, 0xB66,
+    0xB6F, 0xB71, 0xB77, 0xB83, 0xB83, 0xB85, 0xB8A, 0xB8E, 0xB90, 0xB92, 0xB95, 0xB99, 0xB9A, 0xB9C, 0xB9C, 0xB9E,
+    0xB9F, 0xBA3, 0xBA4, 0xBA8, 0xBAA, 0xBAE, 0xBB9, 0xBD0, 0xBD0, 0xBE6, 0xBF2, 0xC05, 0xC0C, 0xC0E, 0xC10, 0xC12,
+    0xC28, 0xC2A, 0xC39, 0xC3D, 0xC3D, 0xC58, 0xC5A, 0xC5D, 0xC5D, 0xC60, 0xC61, 0xC66, 0xC6F, 0xC78, 0xC7E, 0xC80,
+    0xC80, 0xC85, 0xC8C, 0xC8E, 0xC90, 0xC92, 0xCA8, 0xCAA, 0xCB3, 0xCB5, 0xCB9, 0xCBD, 0xCBD, 0xCDD, 0xCDE, 0xCE0,
+    0xCE1, 0xCE6, 0xCEF, 0xCF1, 0xCF2, 0xD04, 0xD0C, 0xD0E, 0xD10, 0xD12, 0xD3A, 0xD3D, 0xD3D, 0xD4E, 0xD4E, 0xD54,
+    0xD56, 0xD58, 0xD61, 0xD66, 0xD78, 0xD7A, 0xD7F, 0xD85, 0xD96, 0xD9A, 0xDB1, 0xDB3, 0xDBB, 0xDBD, 0xDBD, 0xDC0,
+    0xDC6, 0xDE6, 0xDEF, 0xE01, 0xE30, 0xE32, 0xE33, 0xE40, 0xE46, 0xE50, 0xE59, 0xE81, 0xE82, 0xE84, 0xE84, 0xE86,
+    0xE8A, 0xE8C, 0xEA3, 0xEA5, 0xEA5, 0xEA7, 0xEB0, 0xEB2, 0xEB3, 0xEBD, 0xEBD, 0xEC0, 0xEC4, 0xEC6, 0xEC6, 0xED0,
+    0xED9, 0xEDC, 0xEDF, 0xF00, 0xF00, 0xF20, 0xF33, 0xF40, 0xF47, 0xF49, 0xF6C, 0xF88, 0xF8C, 0x1000, 0x102A,
+    0x103F, 0x1049, 0x1050, 0x1055, 0x105A, 0x105D, 0x1061, 0x1061, 0x1065, 0x1066, 0x106E, 0x1070, 0x1075, 0x1081,
+    0x108E, 0x108E, 0x1090, 0x1099, 0x10A0, 0x10C5, 0x10C7, 0x10C7, 0x10CD, 0x10CD, 0x10D0, 0x10FA, 0x10FC, 0x1248,
+    0x124A, 0x124D, 0x1250, 0x1256, 0x1258, 0x1258, 0x125A, 0x125D, 0x1260, 0x1288, 0x128A, 0x128D, 0x1290, 0x12B0,
+    0x12B2, 0x12B5, 0x12B8, 0x12BE, 0x12C0, 0x12C0, 0x12C2, 0x12C5, 0x12C8, 0x12D6, 0x12D8, 0x1310, 0x1312, 0x1315,
+    0x1318, 0x135A, 0x1369, 0x137C, 0x1380, 0x138F, 0x13A0, 0x13F5, 0x13F8, 0x13FD, 0x1401, 0x166C, 0x166F, 0x167F,
+    0x1681, 0x169A, 0x16A0, 0x16EA, 0x16EE, 0x16F8, 0x1700, 0x1711, 0x171F, 0x1731, 0x1740, 0x1751, 0x1760, 0x176C,
+    0x176E, 0x1770, 0x1780, 0x17B3, 0x17D7, 0x17D7, 0x17DC, 0x17DC, 0x17E0, 0x17E9, 0x17F0, 0x17F9, 0x1810, 0x1819,
+    0x1820, 0x1878, 0x1880, 0x1884, 0x1887, 0x18A8, 0x18AA, 0x18AA, 0x18B0, 0x18F5, 0x1900, 0x191E, 0x1946, 0x196D,
+    0x1970, 0x1974, 0x1980, 0x19AB, 0x19B0, 0x19C9, 0x19D0, 0x19DA, 0x1A00, 0x1A16, 0x1A20, 0x1A54, 0x1A80, 0x1A89,
+    0x1A90, 0x1A99, 0x1AA7, 0x1AA7, 0x1B05, 0x1B33, 0x1B45, 0x1B4C, 0x1B50, 0x1B59, 0x1B83, 0x1BA0, 0x1BAE, 0x1BE5,
+    0x1C00, 0x1C23, 0x1C40, 0x1C49, 0x1C4D, 0x1C7D, 0x1C80, 0x1C8A, 0x1C90, 0x1CBA, 0x1CBD, 0x1CBF, 0x1CE9, 0x1CEC,
+    0x1CEE, 0x1CF3, 0x1CF5, 0x1CF6, 0x1CFA, 0x1CFA, 0x1D00, 0x1DBF, 0x1E00, 0x1F15, 0x1F18, 0x1F1D, 0x1F20, 0x1F45,
+    0x1F48, 0x1F4D, 0x1F50, 0x1F57, 0x1F59, 0x1F59, 0x1F5B, 0x1F5B, 0x1F5D, 0x1F5D, 0x1F5F, 0x1F7D, 0x1F80, 0x1FB4,
+    0x1FB6, 0x1FBC, 0x1FBE, 0x1FBE, 0x1FC2, 0x1FC4, 0x1FC6, 0x1FCC, 0x1FD0, 0x1FD3, 0x1FD6, 0x1FDB, 0x1FE0, 0x1FEC,
+    0x1FF2, 0x1FF4, 0x1FF6, 0x1FFC, 0x2070, 0x2071, 0x2074, 0x2079, 0x207F, 0x2089, 0x2090, 0x209C, 0x2102, 0x2102,
+    0x2107, 0x2107, 0x210A, 0x2113, 0x2115, 0x2115, 0x2119, 0x211D, 0x2124, 0x2124, 0x2126, 0x2126, 0x2128, 0x2128,
+    0x212A, 0x212D, 0x212F, 0x2139, 0x213C, 0x213F, 0x2145, 0x2149, 0x214E, 0x214E, 0x2150, 0x2189, 0x2460, 0x249B,
+    0x24EA, 0x24FF, 0x2776, 0x2793, 0x2C00, 0x2CE4, 0x2CEB, 0x2CEE, 0x2CF2, 0x2CF3, 0x2CFD, 0x2CFD, 0x2D00, 0x2D25,
+    0x2D27, 0x2D27, 0x2D2D, 0x2D2D, 0x2D30, 0x2D67, 0x2D6F, 0x2D6F, 0x2D80, 0x2D96, 0x2DA0, 0x2DA6, 0x2DA8, 0x2DAE,
+    0x2DB0, 0x2DB6, 0x2DB8, 0x2DBE, 0x2DC0, 0x2DC6, 0x2DC8, 0x2DCE, 0x2DD0, 0x2DD6, 0x2DD8, 0x2DDE, 0x2E2F, 0x2E2F,
+    0x3005, 0x3007, 0x3021, 0x3029, 0x3031, 0x3035, 0x3038, 0x303C, 0x3041, 0x3096, 0x309D, 0x309F, 0x30A1, 0x30FA,
+    0x30FC, 0x30FF, 0x3105, 0x312F, 0x3131, 0x318E, 0x3192, 0x3195, 0x31A0, 0x31BF, 0x31F0, 0x31FF, 0x3220, 0x3229,
+    0x3248, 0x324F, 0x3251, 0x325F, 0x3280, 0x3289, 0x32B1, 0x32BF, 0x3400, 0x4DBF, 0x4E00, 0xA48C, 0xA4D0, 0xA4FD,
+    0xA500, 0xA60C, 0xA610, 0xA62B, 0xA640, 0xA66E, 0xA67F, 0xA69D, 0xA6A0, 0xA6EF, 0xA717, 0xA71F, 0xA722, 0xA788,
+    0xA78B, 0xA7CD, 0xA7D0, 0xA7D1, 0xA7D3, 0xA7D3, 0xA7D5, 0xA7DC, 0xA7F2, 0xA801, 0xA803, 0xA805, 0xA807, 0xA80A,
+    0xA80C, 0xA822, 0xA830, 0xA835, 0xA840, 0xA873, 0xA882, 0xA8B3, 0xA8D0, 0xA8D9, 0xA8F2, 0xA8F7, 0xA8FB, 0xA8FB,
+    0xA8FD, 0xA8FE, 0xA900, 0xA925, 0xA930, 0xA946, 0xA960, 0xA97C, 0xA984, 0xA9B2, 0xA9CF, 0xA9D9, 0xA9E0, 0xA9E4,
+    0xA9E6, 0xA9FE, 0xAA00, 0xAA28, 0xAA40, 0xAA42, 0xAA44, 0xAA4B, 0xAA50, 0xAA59, 0xAA60, 0xAA76, 0xAA7A, 0xAA7A,
+    0xAA7E, 0xAAAF, 0xAAB1, 0xAAB1, 0xAAB5, 0xAAB6, 0xAAB9, 0xAABD, 0xAAC0, 0xAAC0, 0xAAC2, 0xAAC2, 0xAADB, 0xAADD,
+    0xAAE0, 0xAAEA, 0xAAF2, 0xAAF4, 0xAB01, 0xAB06, 0xAB09, 0xAB0E, 0xAB11, 0xAB16, 0xAB20, 0xAB26, 0xAB28, 0xAB2E,
+    0xAB30, 0xAB5A, 0xAB5C, 0xAB69, 0xAB70, 0xABE2, 0xABF0, 0xABF9, 0xAC00, 0xD7A3, 0xD7B0, 0xD7C6, 0xD7CB, 0xD7FB,
+    0xF900, 0xFA6D, 0xFA70, 0xFAD9, 0xFB00, 0xFB06, 0xFB13, 0xFB17, 0xFB1D, 0xFB1D, 0xFB1F, 0xFB28, 0xFB2A, 0xFB36,
+    0xFB38, 0xFB3C, 0xFB3E, 0xFB3E, 0xFB40, 0xFB41, 0xFB43, 0xFB44, 0xFB46, 0xFBB1, 0xFBD3, 0xFD3D, 0xFD50, 0xFD8F,
+    0xFD92, 0xFDC7, 0xFDF0, 0xFDFB, 0xFE70, 0xFE74, 0xFE76, 0xFEFC, 0xFF10, 0xFF19, 0xFF21, 0xFF3A, 0xFF41, 0xFF5A,
+    0xFF66, 0xFFBE, 0xFFC2, 0xFFC7, 0xFFCA, 0xFFCF, 0xFFD2, 0xFFD7, 0xFFDA, 0xFFDC, 0x10000, 0x1000B, 0x1000D,
+    0x10026, 0x10028, 0x1003A, 0x1003C, 0x1003D, 0x1003F, 0x1004D, 0x10050, 0x1005D, 0x10080, 0x100FA, 0x10107,
+    0x10133, 0x10140, 0x10178, 0x1018A, 0x1018B, 0x10280, 0x1029C, 0x102A0, 0x102D0, 0x102E1, 0x102FB, 0x10300,
+    0x10323, 0x1032D, 0x1034A, 0x10350, 0x10375, 0x10380, 0x1039D, 0x103A0, 0x103C3, 0x103C8, 0x103CF, 0x103D1,
+    0x103D5, 0x10400, 0x1049D, 0x104A0, 0x104A9, 0x104B0, 0x104D3, 0x104D8, 0x104FB, 0x10500, 0x10527, 0x10530,
+    0x10563, 0x10570, 0x1057A, 0x1057C, 0x1058A, 0x1058C, 0x10592, 0x10594, 0x10595, 0x10597, 0x105A1, 0x105A3,
+    0x105B1, 0x105B3, 0x105B9, 0x105BB, 0x105BC, 0x105C0, 0x105F3, 0x10600, 0x10736, 0x10740, 0x10755, 0x10760,
+    0x10767, 0x10780, 0x10785, 0x10787, 0x107B0, 0x107B2, 0x107BA, 0x10800, 0x10805, 0x10808, 0x10808, 0x1080A,
+    0x10835, 0x10837, 0x10838, 0x1083C, 0x1083C, 0x1083F, 0x10855, 0x10858, 0x10876, 0x10879, 0x1089E, 0x108A7,
+    0x108AF, 0x108E0, 0x108F2, 0x108F4, 0x108F5, 0x108FB, 0x1091B, 0x10920, 0x10939, 0x10980, 0x109B7, 0x109BC,
+    0x109CF, 0x109D2, 0x10A00, 0x10A10, 0x10A13, 0x10A15, 0x10A17, 0x10A19, 0x10A35, 0x10A40, 0x10A48, 0x10A60,
+    0x10A7E, 0x10A80, 0x10A9F, 0x10AC0, 0x10AC7, 0x10AC9, 0x10AE4, 0x10AEB, 0x10AEF, 0x10B00, 0x10B35, 0x10B40,
+    0x10B55, 0x10B58, 0x10B72, 0x10B78, 0x10B91, 0x10BA9, 0x10BAF, 0x10C00, 0x10C48, 0x10C80, 0x10CB2, 0x10CC0,
+    0x10CF2, 0x10CFA, 0x10D23, 0x10D30, 0x10D39, 0x10D40, 0x10D65, 0x10D6F, 0x10D85, 0x10E60, 0x10E7E, 0x10E80,
+    0x10EA9, 0x10EB0, 0x10EB1, 0x10EC2, 0x10EC4, 0x10F00, 0x10F27, 0x10F30, 0x10F45, 0x10F51, 0x10F54, 0x10F70,
+    0x10F81, 0x10FB0, 0x10FCB, 0x10FE0, 0x10FF6, 0x11003, 0x11037, 0x11052, 0x1106F, 0x11071, 0x11072, 0x11075,
+    0x11075, 0x11083, 0x110AF, 0x110D0, 0x110E8, 0x110F0, 0x110F9, 0x11103, 0x11126, 0x11136, 0x1113F, 0x11144,
+    0x11144, 0x11147, 0x11147, 0x11150, 0x11172, 0x11176, 0x11176, 0x11183, 0x111B2, 0x111C1, 0x111C4, 0x111D0,
+    0x111DA, 0x111DC, 0x111DC, 0x111E1, 0x111F4, 0x11200, 0x11211, 0x11213, 0x1122B, 0x1123F, 0x11240, 0x11280,
+    0x11286, 0x11288, 0x11288, 0x1128A, 0x1128D, 0x1128F, 0x1129D, 0x1129F, 0x112A8, 0x112B0, 0x112DE, 0x112F0,
+    0x112F9, 0x11305, 0x1130C, 0x1130F, 0x11310, 0x11313, 0x11328, 0x1132A, 0x11330, 0x11332, 0x11333, 0x11335,
+    0x11339, 0x1133D, 0x1133D, 0x11350, 0x11350, 0x1135D, 0x11361, 0x11380, 0x11389, 0x1138B, 0x1138B, 0x1138E,
+    0x1138E, 0x11390, 0x113B5, 0x113B7, 0x113B7, 0x113D1, 0x113D1, 0x113D3, 0x113D3, 0x11400, 0x11434, 0x11447,
+    0x1144A, 0x11450, 0x11459, 0x1145F, 0x11461, 0x11480, 0x114AF, 0x114C4, 0x114C5, 0x114C7, 0x114C7, 0x114D0,
+    0x114D9, 0x11580, 0x115AE, 0x115D8, 0x115DB, 0x11600, 0x1162F, 0x11644, 0x11644, 0x11650, 0x11659, 0x11680,
+    0x116AA, 0x116B8, 0x116B8, 0x116C0, 0x116C9, 0x116D0, 0x116E3, 0x11700, 0x1171A, 0x11730, 0x1173B, 0x11740,
+    0x11746, 0x11800, 0x1182B, 0x118A0, 0x118F2, 0x118FF, 0x11906, 0x11909, 0x11909, 0x1190C, 0x11913, 0x11915,
+    0x11916, 0x11918, 0x1192F, 0x1193F, 0x1193F, 0x11941, 0x11941, 0x11950, 0x11959, 0x119A0, 0x119A7, 0x119AA,
+    0x119D0, 0x119E1, 0x119E1, 0x119E3, 0x119E3, 0x11A00, 0x11A00, 0x11A0B, 0x11A32, 0x11A3A, 0x11A3A, 0x11A50,
+    0x11A50, 0x11A5C, 0x11A89, 0x11A9D, 0x11A9D, 0x11AB0, 0x11AF8, 0x11BC0, 0x11BE0, 0x11BF0, 0x11BF9, 0x11C00,
+    0x11C08, 0x11C0A, 0x11C2E, 0x11C40, 0x11C40, 0x11C50, 0x11C6C, 0x11C72, 0x11C8F, 0x11D00, 0x11D06, 0x11D08,
+    0x11D09, 0x11D0B, 0x11D30, 0x11D46, 0x11D46, 0x11D50, 0x11D59, 0x11D60, 0x11D65, 0x11D67, 0x11D68, 0x11D6A,
+    0x11D89, 0x11D98, 0x11D98, 0x11DA0, 0x11DA9, 0x11EE0, 0x11EF2, 0x11F02, 0x11F02, 0x11F04, 0x11F10, 0x11F12,
+    0x11F33, 0x11F50, 0x11F59, 0x11FB0, 0x11FB0, 0x11FC0, 0x11FD4, 0x12000, 0x12399, 0x12400, 0x1246E, 0x12480,
+    0x12543, 0x12F90, 0x12FF0, 0x13000, 0x1342F, 0x13441, 0x13446, 0x13460, 0x143FA, 0x14400, 0x14646, 0x16100,
+    0x1611D, 0x16130, 0x16139, 0x16800, 0x16A38, 0x16A40, 0x16A5E, 0x16A60, 0x16A69, 0x16A70, 0x16ABE, 0x16AC0,
+    0x16AC9, 0x16AD0, 0x16AED, 0x16B00, 0x16B2F, 0x16B40, 0x16B43, 0x16B50, 0x16B59, 0x16B5B, 0x16B61, 0x16B63,
+    0x16B77, 0x16B7D, 0x16B8F, 0x16D40, 0x16D6C, 0x16D70, 0x16D79, 0x16E40, 0x16E96, 0x16F00, 0x16F4A, 0x16F50,
+    0x16F50, 0x16F93, 0x16F9F, 0x16FE0, 0x16FE1, 0x16FE3, 0x16FE3, 0x17000, 0x187F7, 0x18800, 0x18CD5, 0x18CFF,
+    0x18D08, 0x1AFF0, 0x1AFF3, 0x1AFF5, 0x1AFFB, 0x1AFFD, 0x1AFFE, 0x1B000, 0x1B122, 0x1B132, 0x1B132, 0x1B150,
+    0x1B152, 0x1B155, 0x1B155, 0x1B164, 0x1B167, 0x1B170, 0x1B2FB, 0x1BC00, 0x1BC6A, 0x1BC70, 0x1BC7C, 0x1BC80,
+    0x1BC88, 0x1BC90, 0x1BC99, 0x1CCF0, 0x1CCF9, 0x1D2C0, 0x1D2D3, 0x1D2E0, 0x1D2F3, 0x1D360, 0x1D378, 0x1D400,
+    0x1D454, 0x1D456, 0x1D49C, 0x1D49E, 0x1D49F, 0x1D4A2, 0x1D4A2, 0x1D4A5, 0x1D4A6, 0x1D4A9, 0x1D4AC, 0x1D4AE,
+    0x1D4B9, 0x1D4BB, 0x1D4BB, 0x1D4BD, 0x1D4C3, 0x1D4C5, 0x1D505, 0x1D507, 0x1D50A, 0x1D50D, 0x1D514, 0x1D516,
+    0x1D51C, 0x1D51E, 0x1D539, 0x1D53B, 0x1D53E, 0x1D540, 0x1D544, 0x1D546, 0x1D546, 0x1D54A, 0x1D550, 0x1D552,
+    0x1D6A5, 0x1D6A8, 0x1D6C0, 0x1D6C2, 0x1D6DA, 0x1D6DC, 0x1D6FA, 0x1D6FC, 0x1D714, 0x1D716, 0x1D734, 0x1D736,
+    0x1D74E, 0x1D750, 0x1D76E, 0x1D770, 0x1D788, 0x1D78A, 0x1D7A8, 0x1D7AA, 0x1D7C2, 0x1D7C4, 0x1D7CB, 0x1D7CE,
+    0x1D7FF, 0x1DF00, 0x1DF1E, 0x1DF25, 0x1DF2A, 0x1E030, 0x1E06D, 0x1E100, 0x1E12C, 0x1E137, 0x1E13D, 0x1E140,
+    0x1E149, 0x1E14E, 0x1E14E, 0x1E290, 0x1E2AD, 0x1E2C0, 0x1E2EB, 0x1E2F0, 0x1E2F9, 0x1E4D0, 0x1E4EB, 0x1E4F0,
+    0x1E4F9, 0x1E5D0, 0x1E5ED, 0x1E5F0, 0x1E5FA, 0x1E7E0, 0x1E7E6, 0x1E7E8, 0x1E7EB, 0x1E7ED, 0x1E7EE, 0x1E7F0,
+    0x1E7FE, 0x1E800, 0x1E8C4, 0x1E8C7, 0x1E8CF, 0x1E900, 0x1E943, 0x1E94B, 0x1E94B, 0x1E950, 0x1E959, 0x1EC71,
+    0x1ECAB, 0x1ECAD, 0x1ECAF, 0x1ECB1, 0x1ECB4, 0x1ED01, 0x1ED2D, 0x1ED2F, 0x1ED3D, 0x1EE00, 0x1EE03, 0x1EE05,
+    0x1EE1F, 0x1EE21, 0x1EE22, 0x1EE24, 0x1EE24, 0x1EE27, 0x1EE27, 0x1EE29, 0x1EE32, 0x1EE34, 0x1EE37, 0x1EE39,
+    0x1EE39, 0x1EE3B, 0x1EE3B, 0x1EE42, 0x1EE42, 0x1EE47, 0x1EE47, 0x1EE49, 0x1EE49, 0x1EE4B, 0x1EE4B, 0x1EE4D,
+    0x1EE4F, 0x1EE51, 0x1EE52, 0x1EE54, 0x1EE54, 0x1EE57, 0x1EE57, 0x1EE59, 0x1EE59, 0x1EE5B, 0x1EE5B, 0x1EE5D,
+    0x1EE5D, 0x1EE5F, 0x1EE5F, 0x1EE61, 0x1EE62, 0x1EE64, 0x1EE64, 0x1EE67, 0x1EE6A, 0x1EE6C, 0x1EE72, 0x1EE74,
+    0x1EE77, 0x1EE79, 0x1EE7C, 0x1EE7E, 0x1EE7E, 0x1EE80, 0x1EE89, 0x1EE8B, 0x1EE9B, 0x1EEA1, 0x1EEA3, 0x1EEA5,
+    0x1EEA9, 0x1EEAB, 0x1EEBB, 0x1F100, 0x1F10C, 0x1FBF0, 0x1FBF9, 0x20000, 0x2A6DF, 0x2A700, 0x2B739, 0x2B740,
+    0x2B81D, 0x2B820, 0x2CEA1, 0x2CEB0, 0x2EBE0, 0x2EBF0, 0x2EE5D, 0x2F800, 0x2FA1D, 0x30000, 0x3134A, 0x31350,
+    0x323AF,
+)
+
+internal val DEFAULT_IGNORABLE: IntArray = intArrayOf(
+    0xAD, 0xAD, 0x34F, 0x34F, 0x61C, 0x61C, 0x115F, 0x1160, 0x17B4, 0x17B5, 0x180B, 0x180F, 0x200B, 0x200F, 0x202A,
+    0x202E, 0x2060, 0x206F, 0x3164, 0x3164, 0xFE00, 0xFE0F, 0xFEFF, 0xFEFF, 0xFFA0, 0xFFA0, 0xFFF0, 0xFFF8, 0x1BCA0,
+    0x1BCA3, 0x1D173, 0x1D17A, 0xE0000, 0xE0FFF,
+)

packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/WriteReceipt.kt

@@ -0,0 +1,286 @@
+package org.gamecult.cultmesh
+
+// The write receipt (contracts/cultnet/interop/write-receipt.md): the two frames, their strict decode, the dedupe
+// content hash, the hello capability test and the client settle rules. Mirrors packages/cultnet-ts (contracts.ts,
+// write-tracker.ts) and packages/cultnet-rs (write_content_hash). The replay of write-receipt-vectors.json lives in
+// WriteReceiptVectors.kt. Server rules (dedupe, limits, blank fields) are not a decoder's business and are not here.
+
+import java.io.IOException
+import java.security.MessageDigest
+
+const val WRITE_ADMITTED_VERSION = "cultnet.write_admitted.v0"
+const val ERROR_V1_VERSION = "cultnet.error.v1"
+const val ERROR_V0_VERSION = "cultnet.error.v0"
+
+/** A connection is receipt-capable only when its hello lists both frames. */
+val CULTNET_WRITE_RECEIPT_MESSAGE_VERSIONS: List<String> = listOf(WRITE_ADMITTED_VERSION, ERROR_V1_VERSION)
+
+const val RECEIPT_RESULT_WINDOW_MS = 5000L
+const val LEGACY_RESULT_WINDOW_MS = 500L
+
+fun resultWindowMs(serverAdvertisesReceipts: Boolean): Long =
+    if (serverAdvertisesReceipts) RECEIPT_RESULT_WINDOW_MS else LEGACY_RESULT_WINDOW_MS
+
+/** The closed refusal-code set of error.v0; error.v1 adds `limit_reached`. */
+val CULTNET_ERROR_V0_CODES: Set<String> = setOf(
+    "selection_invalid", "cursor_stale", "cursor_invalid", "reference_outside_target", "variant_unsupported",
+    "unowned_schema", "write_not_authorized", "unsupported_schema_version", "message_invalid",
+)
+val CULTNET_ERROR_V1_CODES: Set<String> = CULTNET_ERROR_V0_CODES + "limit_reached"
+
+fun helloAdvertisesWriteReceipts(hello: CultNetMessage): Boolean {
+    val versions = hello.body["supportedMessageVersions"] as? List<*> ?: return false
+    return CULTNET_WRITE_RECEIPT_MESSAGE_VERSIONS.all { it in versions }
+}
+
+data class CultNetWriteAdmitted(val messageId: String, val operation: String, val schemaId: String, val recordKey: String) {
+    fun toMessage() = CultNetMessage(
+        WRITE_ADMITTED_VERSION,
+        linkedMapOf("messageId" to messageId, "operation" to operation, "schemaId" to schemaId, "recordKey" to recordKey),
+    )
+}
+
+data class CultNetErrorDetails(val field: String?, val value: String?, val asOf: Long?, val current: Long?)
+
+/** error.v0 (`messageId` always null, `version` 0) or error.v1 (`version` 1). */
+data class CultNetErrorFrame(
+    val version: Int,
+    val error: String,
+    val routingHint: Map<String, Any?>?,
+    val code: String?,
+    val details: CultNetErrorDetails?,
+    val messageId: String?,
+) {
+    fun toMessage(): CultNetMessage {
+        val body = linkedMapOf<String, Any?>(
+            "error" to error,
+            "routingHint" to routingHint,
+            "code" to code,
+            "details" to details?.let {
+                linkedMapOf("field" to it.field, "value" to it.value, "asOf" to it.asOf, "current" to it.current)
+            },
+        )
+        if (version == 1) body["messageId"] = messageId
+        return CultNetMessage(if (version == 1) ERROR_V1_VERSION else ERROR_V0_VERSION, body)
+    }
+}
+
+/**
+ * Strict decode of a write_admitted.v0 message against its closed schema: exactly five keys, a non-empty string each,
+ * operation put|delete.
+ */
+fun decodeWriteAdmitted(message: CultNetMessage): CultNetWriteAdmitted {
+    if (message.schemaVersion != WRITE_ADMITTED_VERSION) throw IOException("not a $WRITE_ADMITTED_VERSION message")
+    closedKeys(message, setOf("messageId", "operation", "schemaId", "recordKey"))
+    val operation = nonEmpty(message, "operation")
+    if (operation != "put" && operation != "delete") throw IOException("operation must be put or delete")
+    return CultNetWriteAdmitted(admittedMessageId(message), operation, nonEmpty(message, "schemaId"), nonEmpty(message, "recordKey"))
+}
+
+// write-receipt.md: a letter (Lu Ll Lt Lm Lo) or number (Nd Nl No) somewhere, no Default_Ignorable code point anywhere, as of
+// Unicode 16.0, compared raw (never trimmed). The tables are embedded (UnicodeMessageIdTables.kt, generated by
+// scripts/gen-unicode-messageid-tables.py), not the JDK's, so the running JVM's Unicode version changes no result; the other
+// four runtimes embed the same generated tables.
+private fun inRanges(ranges: IntArray, point: Int): Boolean {
+    var low = 0
+    var high = ranges.size / 2 - 1
+    while (low <= high) {
+        val mid = (low + high) ushr 1
+        when {
+            point < ranges[2 * mid] -> high = mid - 1
+            point > ranges[2 * mid + 1] -> low = mid + 1
+            else -> return true
+        }
+    }
+    return false
+}
+
+private fun admittedMessageId(message: CultNetMessage): String {
+    val id = nonEmpty(message, "messageId")
+    var hasLetterOrNumber = false
+    id.codePoints().forEach { cp ->
+        if (inRanges(DEFAULT_IGNORABLE, cp)) throw IOException("messageId holds a Default_Ignorable code point")
+        if (inRanges(LETTER_OR_NUMBER, cp)) hasLetterOrNumber = true
+    }
+    if (!hasLetterOrNumber) throw IOException("messageId must contain a letter or number")
+    return id
+}
+
+/** Strict decode of error.v0 (no messageId, no limit_reached) or error.v1 (messageId required, string or nil, never empty). */
+fun decodeErrorFrame(message: CultNetMessage): CultNetErrorFrame {
+    val version = when (message.schemaVersion) {
+        ERROR_V1_VERSION -> 1
+        ERROR_V0_VERSION -> 0
+        else -> throw IOException("not an error message")
+    }
+    closedKeys(message, setOf("error", "routingHint", "code", "details") + if (version == 1) setOf("messageId") else emptySet())
+    val error = nonEmpty(message, "error")
+    val codeValue = message.body["code"]
+    if (codeValue != null && (codeValue !is String || codeValue !in (if (version == 1) CULTNET_ERROR_V1_CODES else CULTNET_ERROR_V0_CODES))) {
+        throw IOException("unknown error code")
+    }
+    var messageId: String? = null
+    if (version == 1) {
+        val id = message.body["messageId"]
+        if (id != null && (id !is String || id.isEmpty())) throw IOException("messageId must be a non-empty string or nil")
+        messageId = id as String?
+    }
+    return CultNetErrorFrame(version, error, routingHintOf(message.body["routingHint"]), codeValue as String?, detailsOf(message.body["details"]), messageId)
+}
+
+private fun closedKeys(message: CultNetMessage, required: Set<String>) {
+    if (!message.body.keys.containsAll(required)) throw IOException("${message.schemaVersion} is missing ${required - message.body.keys}")
+    val unknown = message.body.keys - required
+    if (unknown.isNotEmpty()) throw IOException("${message.schemaVersion} carries unknown keys $unknown")
+}
+
+private fun nonEmpty(message: CultNetMessage, key: String): String {
+    val value = message.body[key]
+    if (value !is String || value.isEmpty()) throw IOException("$key must be a non-empty string")
+    return value
+}
+
+private fun routingHintOf(value: Any?): Map<String, Any?>? {
+    if (value == null) return null
+    if (value !is Map<*, *> || value.keys != setOf("shard", "reason")) throw IOException("routingHint must be nil or {shard, reason}")
+    if (value["shard"] != null && value["shard"] !is Map<*, *>) throw IOException("routingHint.shard must be an object or nil")
+    if (value["reason"] !is String) throw IOException("routingHint.reason must be a string")
+    @Suppress("UNCHECKED_CAST")
+    return value as Map<String, Any?>
+}
+
+private fun detailsOf(value: Any?): CultNetErrorDetails? {
+    if (value == null) return null
+    if (value !is Map<*, *> || value.keys != setOf("field", "value", "asOf", "current")) {
+        throw IOException("details must be nil or {field, value, asOf, current}")
+    }
+    fun text(key: String): String? = value[key].let { if (it == null || it is String) it as String? else throw IOException("details.$key must be a string or nil") }
+    fun cursor(key: String): Long? = value[key].let {
+        if (it == null) null else if (it is Long && it >= 0) it else throw IOException("details.$key must be a non-negative integer or nil")
+    }
+    return CultNetErrorDetails(text("field"), text("value"), cursor("asOf"), cursor("current"))
+}
+
+/** sha256 of the MessagePack array [operation, schemaId, recordKey, payload]: payload a bin for a put, nil for a delete. Lowercase hex. */
+fun writeContentHash(operation: String, schemaId: String, recordKey: String, payload: ByteArray?): String {
+    val writer = MessagePackWriter().array(4).string(operation).string(schemaId).string(recordKey)
+    if (payload == null) writer.nil() else writer.binary(payload)
+    return MessageDigest.getInstance("SHA-256").digest(writer.toByteArray()).joinToString("") { "%02x".format(it) }
+}
+
+/** Why nothing settled a write. */
+enum class WriteUnconfirmedReason(val wire: String) { WINDOW_ELAPSED("window_elapsed"), SESSION_ENDED("session_ended"), LOCAL_SEND_FAILED("local_send_failed") }
+
+/** What a late answer is recorded as on a write that already settled unconfirmed. */
+enum class WriteRecorded(val wire: String) { ADMITTED_LATE("admitted_late"), REFUSED_LATE("refused_late") }
+
+/** What the caller was told. Settled once; never changed by a later frame. */
+sealed class WriteSettlement {
+    object Admitted : WriteSettlement()
+    data class Refused(val code: String?, val error: String, val response: CultNetErrorFrame) : WriteSettlement()
+    data class Unconfirmed(val reason: WriteUnconfirmedReason) : WriteSettlement()
+}
+
+/**
+ * The client half of the receipt rules: a pure state machine with an abstract clock, one decision, how each sent write
+ * settles. Transport, timers and decoding belong to the caller; `frame` takes a message and decodes it strictly.
+ */
+class WriteTracker(private val windowMs: Long, private val onSettle: (String, WriteSettlement) -> Unit = { _, _ -> }) {
+    private class Entry(val sentAtMs: Long) {
+        var settlement: WriteSettlement? = null
+        var recorded: WriteRecorded? = null
+    }
+
+    private val writes = linkedMapOf<String, Entry>()
+    private var ended = false
+
+    /** Registers a write sent at [atMs]. Re-sending a known id is the same write and does not restart its window. */
+    fun send(messageId: String, atMs: Long) {
+        tick(atMs)
+        if (messageId in writes) return
+        val entry = Entry(atMs)
+        writes[messageId] = entry
+        // On a session that already ended nothing can answer this write.
+        if (ended) settle(messageId, entry, WriteSettlement.Unconfirmed(WriteUnconfirmedReason.SESSION_ENDED))
+    }
+
+    /** Feeds one received message. Only write_admitted, error.v1 and error.v0 answer; anything else is ignored. */
+    fun frame(message: CultNetMessage, atMs: Long) {
+        tick(atMs)
+        when (message.schemaVersion) {
+            WRITE_ADMITTED_VERSION -> {
+                answer(decodeWriteAdmitted(message).messageId, WriteSettlement.Admitted, WriteRecorded.ADMITTED_LATE)
+                return
+            }
+            ERROR_V1_VERSION, ERROR_V0_VERSION -> {
+                val error = decodeErrorFrame(message)
+                val refusal = WriteSettlement.Refused(error.code, error.error, error)
+                if (error.messageId != null) {
+                    answer(error.messageId, refusal, WriteRecorded.REFUSED_LATE)
+                    return
+                }
+                // An error that names no write is attributable only when exactly one write is unanswered.
+                val unanswered = writes.filterValues { it.settlement == null }
+                if (unanswered.size == 1) settle(unanswered.keys.first(), unanswered.values.first(), refusal)
+            }
+            else -> return
+        }
+    }
+
+    /** Every unanswered write whose window, counted from its own send, has run settles unconfirmed. */
+    fun tick(atMs: Long) {
+        for ((id, entry) in writes) {
+            if (entry.settlement == null && atMs - entry.sentAtMs >= windowMs) settle(id, entry, WriteSettlement.Unconfirmed(WriteUnconfirmedReason.WINDOW_ELAPSED))
+        }
+    }
+
+    /** The session ended: every unanswered write settles unconfirmed, and so does any write sent afterwards. */
+    fun sessionEnd(atMs: Long) {
+        tick(atMs)
+        ended = true
+        for ((id, entry) in writes) if (entry.settlement == null) settle(id, entry, WriteSettlement.Unconfirmed(WriteUnconfirmedReason.SESSION_ENDED))
+    }
+
+    /** This client's own send of [messageId] failed: that write settles unconfirmed; the others are untouched. */
+    fun sendFailed(messageId: String, atMs: Long) {
+        val entry = writes[messageId]
+        if (entry != null && entry.settlement == null) settle(messageId, entry, WriteSettlement.Unconfirmed(WriteUnconfirmedReason.LOCAL_SEND_FAILED))
+        tick(atMs)
+    }
+
+    /** The settlement told to the caller, or null while unanswered or unknown. */
+    fun settlement(messageId: String): WriteSettlement? = writes[messageId]?.settlement
+
+    /** The late answer recorded on an unconfirmed write. */
+    fun recorded(messageId: String): WriteRecorded? = writes[messageId]?.recorded
+
+    private fun answer(messageId: String, settlement: WriteSettlement, late: WriteRecorded) {
+        val entry = writes[messageId] ?: return // names a write that is not in flight: settles nothing
+        val current = entry.settlement
+        if (current == null) settle(messageId, entry, settlement)
+        else if (current is WriteSettlement.Unconfirmed && entry.recorded == null) entry.recorded = late
+    }
+
+    private fun settle(messageId: String, entry: Entry, settlement: WriteSettlement) {
+        entry.settlement = settlement
+        onSettle(messageId, settlement)
+    }
+}
+
+/** Unicode White_Space (PropList), the one definition of "blank" in write-receipt.md rule 5; Kotlin's own isBlank takes U+001C to U+001F. */
+private val WHITE_SPACE_CODE_POINTS: Set<Int> = (0x0009..0x000D).toSet() + 0x0020 + 0x0085 + 0x00A0 + 0x1680 +
+    (0x2000..0x200A).toSet() + 0x2028 + 0x2029 + 0x202F + 0x205F + 0x3000
+
+/** True for null, empty, or only White_Space code points. */
+fun isBlankText(text: String?): Boolean = text == null || text.codePoints().allMatch { it in WHITE_SPACE_CODE_POINTS }
+
+/** Self-test: blank is White_Space, not Kotlin's isBlank (rule 5): U+001C to U+001F name something, U+00A0 and U+0085 do not. */
+fun rawDocumentRecordDropsOnlyWhiteSpaceSourceIds() {
+    fun wireKeys(id: String) = CultNetRawDocumentRecord("note.v0", "note:1", "2026-11-08T00:00:00Z", payload = byteArrayOf(1), sourceRuntimeId = id, sourceAgentId = id, sourceRole = id).toWireMap().keys
+    for (blank in listOf("", "\u0085", "\u00a0\u2003", "\u3000", "\t\r\n ")) {
+        check(isBlankText(blank) && "sourceRuntimeId" !in wireKeys(blank)) { "blank ${blank.map { it.code }} must be dropped" }
+    }
+    for (named in listOf("\u001c", "\u001f", "\u200b", "\ufeff", "\u180e", "a")) {
+        check(!isBlankText(named) && "sourceRuntimeId" in wireKeys(named) && "sourceRole" in wireKeys(named)) { "${named.map { it.code }} names something and must be kept" }
+    }
+}

packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/WriteReceiptVectors.kt

@@ -0,0 +1,310 @@
+package org.gamecult.cultmesh
+
+// Replays contracts/cultnet/interop/write-receipt-vectors.json against this runtime: constants, contentHash, every
+// `wire` frame (decode to the vector's fields, re-encode to its bytes), every `schemaInvalid` frame (must be refused),
+// and every `scenarios` event replay through WriteTracker. `dedupe` and `blankFields` are server inputs and are not
+// run here. Mode: `java -cp ... org.gamecult.cultmesh.CultMeshKt write-receipt-vectors <vectors.json>`.
+
+import java.io.File
+import java.io.IOException
+
+// The event actions scenarios.semantics names; anything else is refused, not skipped.
+private val EVENT_KEYS = listOf("send", "frame", "tick", "sessionEnd", "sendFailed", "transportAck")
+
+fun replayWriteReceiptVectors(path: String): Boolean {
+    @Suppress("UNCHECKED_CAST")
+    val vectors = JsonReader(File(path).readText(Charsets.UTF_8)).readDocument() as Map<String, Any?>
+    val results = linkedMapOf<String, List<String>>()
+    fun check(name: String, run: () -> List<String>) {
+        results[name] = try { run() } catch (e: Throwable) { listOf("threw: $e") }
+    }
+
+    val constants = obj(vectors["constants"])
+    check("constants") {
+        listOfNotNull(
+            "RECEIPT window".takeIf { constants["RECEIPT_RESULT_WINDOW_MS"] != RECEIPT_RESULT_WINDOW_MS },
+            "LEGACY window".takeIf { constants["LEGACY_RESULT_WINDOW_MS"] != LEGACY_RESULT_WINDOW_MS },
+        )
+    }
+
+    for (case in list(obj(vectors["contentHash"])["cases"])) {
+        val c = obj(case)
+        check("contentHash/${c["name"]}") {
+            val got = writeContentHash(c["operation"] as String, c["schemaId"] as String, c["recordKey"] as String, (c["payloadHex"] as String?)?.let(::unhex))
+            if (got == c["sha256"]) emptyList() else listOf("$got != ${c["sha256"]}")
+        }
+    }
+
+    for (case in list(vectors["wire"])) {
+        val c = obj(case)
+        check("wire/${c["name"]}") {
+            val bytes = unhex(c["messagePackHex"] as String)
+            val problems = mutableListOf<String>()
+            val message = decodeReceiptFrame(parseCultNetMessage(bytes))
+            if (message.toWireMap() != c["message"]) problems += "decoded ${message.toWireMap()} != ${c["message"]}"
+            val again = message.toBytes().joinToString("") { "%02X".format(it) }
+            if (again != (c["messagePackHex"] as String).uppercase()) problems += "re-encoded bytes $again != captured ${c["messagePackHex"]}"
+            problems
+        }
+    }
+
+    // admittedMessageId: a write_admitted messageId needs a letter or number and no Default_Ignorable code point, compared
+    // raw. The frame is built with this runtime's own encoder; a case with `wireHex` (the lone surrogate, invalid UTF-8)
+    // supplies the whole frame.
+    for (case in list(obj(vectors["admittedMessageId"])["cases"])) {
+        val c = obj(case)
+        check("admittedMessageId/${c["name"]}") {
+            val id = list(c["codePoints"]).joinToString("") { String(Character.toChars((it as String).toInt(16))) }.repeat(((c["repeat"] as Long?) ?: 1L).toInt())
+            val bytes = (c["wireHex"] as String?)?.let(::unhex) ?: MessagePackWriter().value(linkedMapOf(
+                "schemaVersion" to WRITE_ADMITTED_VERSION, "messageId" to id, "operation" to "put", "schemaId" to "note.v0", "recordKey" to "note:1",
+            )).toByteArray()
+            val decoded = try { decodeReceiptFrame(parseCultNetMessage(bytes)) } catch (_: IOException) { null }
+            when {
+                c["expect"] == "refuse" -> if (decoded == null) emptyList() else listOf("accepted an id that must be refused (${c["why"]})")
+                decoded == null -> listOf("refused an id that must be accepted (${c["why"]})")
+                decoded.toWireMap()["messageId"] != id -> listOf("id not echoed raw: ${decoded.toWireMap()["messageId"]}")
+                else -> emptyList()
+            }
+        }
+    }
+
+    // The generated ranges file is the independent copy of the embedded tables: first, last and the points either side of every
+    // range, so deleting or narrowing any range fails here.
+    check("unicodeTableRanges") {
+        @Suppress("UNCHECKED_CAST")
+        val ranges = JsonReader(File(File(path).parentFile, "write-admitted-message-id-ranges.json").readText(Charsets.UTF_8)).readDocument() as Map<String, Any?>
+        fun pairs(key: String) = list(ranges[key]).map { list(it).map { n -> (n as Long).toInt() } }
+        val letters = pairs("letterOrNumber")
+        val ignorable = pairs("defaultIgnorable")
+        val problems = mutableListOf<String>()
+        if (letters.size <= 700 || ignorable.size != 17) problems += "ranges file holds ${letters.size} and ${ignorable.size} ranges"
+        fun accepted(id: String): Boolean = try {
+            decodeReceiptFrame(parseCultNetMessage(MessagePackWriter().value(linkedMapOf(
+                "schemaVersion" to WRITE_ADMITTED_VERSION, "messageId" to id, "operation" to "put", "schemaId" to "note.v0", "recordKey" to "note:1",
+            )).toByteArray()))
+            true
+        } catch (_: IOException) { false }
+        for ((low, high) in letters) for ((point, want) in listOf(low to true, high to true, low - 1 to false, high + 1 to false)) {
+            if (accepted(String(Character.toChars(point))) != want) problems += "U+${point.toString(16)} alone should be ${if (want) "accepted" else "refused"}"
+        }
+        for ((low, high) in ignorable) for ((point, want) in listOf(low to false, high to false, low - 1 to true, high + 1 to true)) {
+            if (accepted("a" + String(Character.toChars(point))) != want) problems += "a + U+${point.toString(16)} should be ${if (want) "accepted" else "refused"}"
+        }
+        problems
+    }
+
+    // A document payload string with a lone surrogate (ED A0 80) is not a write_admitted id: the shared MessagePack reader keeps
+    // reading it. Strictness is scoped to the write_admitted frame, never to the reader.
+    check("documentPayloadStringWithLoneSurrogateStillDecodes") {
+        val text = MessagePackReader(unhex("A3EDA080")).readString()
+        if (text.isNotEmpty()) emptyList() else listOf("decoded to an empty string")
+    }
+
+    // admittedMessageIdDuplicates: Kotlin decodes the frame to a map, so it cannot see a repeated key: it judges the last one.
+    for (case in list(obj(vectors["admittedMessageIdDuplicates"])["cases"])) {
+        val c = obj(case)
+        check("admittedMessageIdDuplicates/${c["name"]}") {
+            val decoded = try { decodeReceiptFrame(parseCultNetMessage(unhex(c["wireHex"] as String))) } catch (_: IOException) { null }
+            when {
+                c["lastKeyWins"] == "refuse" -> if (decoded == null) emptyList() else listOf("accepted a frame whose last messageId key is invalid")
+                decoded == null -> listOf("refused a frame whose last messageId key is valid")
+                decoded.toWireMap()["messageId"] != c["lastKeyWinsEcho"] -> listOf("echoed ${decoded.toWireMap()["messageId"]}, wanted ${c["lastKeyWinsEcho"]}")
+                else -> emptyList()
+            }
+        }
+    }
+
+    for (case in list(vectors["schemaInvalid"])) {
+        val c = obj(case)
+        check("schemaInvalid/${c["name"]}") {
+            try {
+                decodeReceiptFrame(parseCultNetMessage(unhex(c["messagePackHex"] as String)))
+                listOf("accepted a frame that must be refused (${c["why"]})")
+            } catch (_: IOException) {
+                emptyList()
+            }
+        }
+    }
+
+    // Not a vector: `limit_reached` is in error.v1's enum only (write-receipt.md), as the TS and Rust suites also pin.
+    check("error_v0_refuses_the_v1_only_limit_reached_code") {
+        val body = linkedMapOf<String, Any?>("error" to "x", "routingHint" to null, "code" to "limit_reached", "details" to null)
+        val v1 = decodeErrorFrame(CultNetMessage(ERROR_V1_VERSION, body + ("messageId" to null))).code
+        try {
+            decodeErrorFrame(CultNetMessage(ERROR_V0_VERSION, body))
+            listOf("error.v0 accepted limit_reached")
+        } catch (_: IOException) {
+            if (v1 == "limit_reached") emptyList() else listOf("error.v1 lost limit_reached")
+        }
+    }
+
+    for (case in list(obj(vectors["scenarios"])["cases"])) {
+        val scenario = obj(case)
+        check("scenario/${scenario["name"]}") {
+            val problems = mutableListOf<String>()
+            // The fake server states its capability the only way a real one does: in its hello.
+            val hello = cultNetHello(
+                "fake-server", "fake",
+                supportedMessageVersions = if (scenario["server"] == "receipt") CULTNET_WRITE_RECEIPT_MESSAGE_VERSIONS else emptyList(),
+            )
+            val windowMs = resultWindowMs(helloAdvertisesWriteReceipts(hello))
+            if (windowMs != constants[scenario["window"] as String]) problems += "window $windowMs != ${scenario["window"]}"
+            val told = linkedMapOf<String, WriteSettlement>()
+            val tracker = WriteTracker(windowMs) { id, settlement ->
+                if (id in told) problems += "$id settled twice"
+                told[id] = settlement
+            }
+            for (event in list(scenario["events"]).map(::obj).sortedBy { it["atMs"] as Long }) {
+                val at = event["atMs"] as Long
+                val actions = event.keys - "atMs"
+                if (actions.size != 1 || actions.first() !in EVENT_KEYS) { problems += "event at $at has keys $actions, wanted atMs and exactly one of $EVENT_KEYS"; continue }
+                when {
+                    "send" in event -> tracker.send(event["send"] as String, at)
+                    // A frame reaches the client as bytes: the fake server encodes it, the client decodes it.
+                    "frame" in event -> tracker.frame(parseCultNetMessage(MessagePackWriter().value(event["frame"]).toByteArray()), at)
+                    "tick" in event -> tracker.tick(at)
+                    "sessionEnd" in event -> tracker.sessionEnd(at)
+                    "sendFailed" in event -> tracker.sendFailed(event["sendFailed"] as String, at)
+                    // transportAck: delivery is not an answer; the tracker has no such input and must not need one.
+                }
+            }
+            val expect = obj(scenario["expect"])
+            for ((id, wantAny) in expect) {
+                val want = obj(wantAny)
+                val got = told[id]
+                if (got == null) { problems += "$id: never settled, wanted ${want["outcome"]}"; continue }
+                val (outcome, code, reason) = when (got) {
+                    is WriteSettlement.Admitted -> Triple("admitted", null, null)
+                    is WriteSettlement.Refused -> Triple("refused", got.code, null)
+                    is WriteSettlement.Unconfirmed -> Triple("unconfirmed", null, got.reason.wire)
+                }
+                if (outcome != want["outcome"]) problems += "$id: told $outcome, wanted ${want["outcome"]}"
+                if ("code" in want && code != want["code"]) problems += "$id: code $code, wanted ${want["code"]}"
+                if ("reason" in want && reason != want["reason"]) problems += "$id: reason $reason, wanted ${want["reason"]}"
+                if (tracker.recorded(id)?.wire != want["recorded"]) problems += "$id: recorded ${tracker.recorded(id)?.wire}, wanted ${want["recorded"]}"
+            }
+            for (id in told.keys) if (id !in expect) problems += "$id: settled but the scenario expects nothing for it"
+            problems
+        }
+    }
+
+    // A runner that read fewer vectors than the file declares has silently skipped some.
+    check("counts") {
+        val declared = obj(vectors["counts"])
+        fun ran(prefix: String) = results.keys.count { it.startsWith(prefix) }
+        val loaded = mapOf(
+            "wire" to list(vectors["wire"]).size, "schemaInvalid" to list(vectors["schemaInvalid"]).size,
+            "contentHashCases" to list(obj(vectors["contentHash"])["cases"]).size, "scenarioCases" to list(obj(vectors["scenarios"])["cases"]).size,
+            "admittedMessageIdCases" to list(obj(vectors["admittedMessageId"])["cases"]).size,
+        )
+        val executed = mapOf("wire" to ran("wire/"), "schemaInvalid" to ran("schemaInvalid/"), "contentHashCases" to ran("contentHash/"), "scenarioCases" to ran("scenario/"), "admittedMessageIdCases" to ran("admittedMessageId/"))
+        loaded.keys.filter { loaded[it] != (declared[it] as Long).toInt() || executed[it] != loaded[it] }
+            .map { "$it: declared ${declared[it]}, loaded ${loaded[it]}, ran ${executed[it]}" }
+    }
+
+    for ((name, problems) in results) {
+        println(if (problems.isEmpty()) "PASS $name" else "FAIL $name")
+        problems.forEach { println("     $it") }
+    }
+    val failed = results.values.count { it.isNotEmpty() }
+    println("${results.size - failed}/${results.size} passed")
+    return failed == 0
+}
+
+/** Strict decode of whichever receipt-family frame this is, returned as the message its typed form encodes; anything else is refused. */
+private fun decodeReceiptFrame(message: CultNetMessage): CultNetMessage = when (message.schemaVersion) {
+    WRITE_ADMITTED_VERSION -> decodeWriteAdmitted(message).toMessage()
+    ERROR_V1_VERSION, ERROR_V0_VERSION -> decodeErrorFrame(message).toMessage()
+    else -> throw IOException("not a receipt frame: ${message.schemaVersion}")
+}
+
+@Suppress("UNCHECKED_CAST")
+private fun obj(value: Any?): Map<String, Any?> = value as Map<String, Any?>
+private fun list(value: Any?): List<Any?> = value as List<Any?>
+
+private fun unhex(text: String): ByteArray = ByteArray(text.length / 2) { text.substring(it * 2, it * 2 + 2).toInt(16).toByte() }
+
+/** A small JSON reader for the vector file: objects, arrays, strings, integers, true/false/null. */
+private class JsonReader(private val text: String) {
+    private var at = 0
+
+    fun readDocument(): Any? = readValue().also { skipSpace(); if (at != text.length) throw IOException("trailing JSON") }
+
+    private fun skipSpace() { while (at < text.length && text[at] in " \t\r\n") at++ }
+
+    private fun readValue(): Any? {
+        skipSpace()
+        return when (val c = text[at]) {
+            '{' -> {
+                at++
+                val map = linkedMapOf<String, Any?>()
+                skipSpace()
+                if (text[at] == '}') { at++; return map }
+                do {
+                    skipSpace()
+                    val key = readString()
+                    skipSpace(); expect(':')
+                    map[key] = readValue()
+                    skipSpace()
+                } while (closes('}'))
+                map
+            }
+            '[' -> {
+                at++
+                val items = mutableListOf<Any?>()
+                skipSpace()
+                if (text[at] == ']') { at++; return items }
+                do {
+                    items += readValue()
+                    skipSpace()
+                } while (closes(']'))
+                items
+            }
+            '"' -> readString()
+            't' -> literal("true", true)
+            'f' -> literal("false", false)
+            'n' -> literal("null", null)
+            else -> {
+                if (c != '-' && !c.isDigit()) throw IOException("unexpected '$c' at $at")
+                val start = at++
+                while (at < text.length && text[at].isDigit()) at++
+                text.substring(start, at).toLong()
+            }
+        }
+    }
+
+    /** After an element: false when [close] ends the container, true after a comma. */
+    private fun closes(close: Char): Boolean {
+        val c = text[at++]
+        if (c == close) return false
+        if (c != ',') throw IOException("expected , or $close at ${at - 1}")
+        return true
+    }
+
+    private fun literal(word: String, value: Any?): Any? {
+        if (!text.startsWith(word, at)) throw IOException("bad literal at $at")
+        at += word.length
+        return value
+    }
+
+    private fun expect(c: Char) { if (text[at++] != c) throw IOException("expected $c at ${at - 1}") }
+
+    private fun readString(): String {
+        expect('"')
+        val out = StringBuilder()
+        while (true) {
+            val c = text[at++]
+            when (c) {
+                '"' -> return out.toString()
+                '\\' -> when (val e = text[at++]) {
+                    'n' -> out.append('\n'); 't' -> out.append('\t'); 'r' -> out.append('\r')
+                    'b' -> out.append('\b'); 'f' -> out.append('\u000c')
+                    'u' -> { out.append(text.substring(at, at + 4).toInt(16).toChar()); at += 4 }
+                    '"', '\\', '/' -> out.append(e)
+                    else -> throw IOException("bad escape \\$e")
+                }
+                else -> out.append(c)
+            }
+        }
+    }
+}

packages/cultmesh-py/README.md

@@ -43,9 +43,10 @@ from cultmesh_py import (
 
 note_doc = define_database_entry_type(
     "mesh.note",
-    [("body", 0), ("name", 1), ("kind", 2)],
+    [("body", 0), ("name", 1), ("kind", 2), ("slug", 3)],
     name="name",
-    indexes={"kind": "kind"},
+    indexes={"slug": "slug"},  # unique: no two notes hold one slug; watch_by_index and get_key_by_index look it up
+    roles={"kind": "kind"},  # many notes share a kind: a selection alias, never a lookup
 )
 node = CultMesh.start_node(
     "mesh.cc",
@@ -55,13 +56,13 @@ node = CultMesh.start_node(
 node.database.register_document(note_doc)
 unsubscribe = node.database.watch_record(note_doc, "note:1", lambda change: print(change.change_kind))
 unsubscribe_named = node.database.watch_by_name(note_doc, "intro", lambda change: print(change.record_key))
-unsubscribe_kind = node.database.watch_by_index(note_doc, "kind", "guide", lambda change: print(change.record_key))
-node.database.put(note_doc, "note:1", {"body": "hello", "name": "intro", "kind": "guide"})
+unsubscribe_slug = node.database.watch_by_index(note_doc, "slug", "intro-guide", lambda change: print(change.record_key))
+node.database.put(note_doc, "note:1", {"body": "hello", "name": "intro", "kind": "guide", "slug": "intro-guide"})
 live_note = node.database.get_required(note_doc, "note:1")
 put_message = node.database.put_raw_message(
     note_doc,
     "note:2",
-    {"body": "wire me", "name": "wire", "kind": "interop"},
+    {"body": "wire me", "name": "wire", "kind": "interop", "slug": "wire-me"},
     shard_id="interop",
     shard_epoch=1,
 )
@@ -122,6 +123,33 @@ server = CultMesh.serve_node(
 )
 ```
 
+## Peer writes
+
+**Breaking (0.x):** a served node refuses every peer `document_put_raw` and `document_delete` unless a write
+authority grants it, mirroring C# `ICultNetRemoteWriteAuthority`. Before this, any connected peer could overwrite
+or delete the node's documents. The refusal is a typed `cultnet.error.v0` with code `write_not_authorized` and the
+record key in `details`; an authority that raises, or returns no decision, refuses too.
+
+Known residual: ungranted peers can still distinguish registered from unregistered schemas by timing (the node resolves the
+schema before the gate so the authority sees the canonical id); the refusal itself is identical.
+
+```python
+from cultmesh_py import CultMeshGrantAllWrites, CultMeshRemoteWriteDecision, CultMeshRemoteWriteRequest
+
+class OwnKeysOnly:
+    def decide(self, request: CultMeshRemoteWriteRequest) -> CultMeshRemoteWriteDecision:
+        if request.record_key.startswith("input:python:"):
+            return CultMeshRemoteWriteDecision.grant()
+        return CultMeshRemoteWriteDecision.refuse("not your key")
+
+server = CultMesh.serve_node(node, write_authority=OwnKeysOnly())
+```
+
+The request carries the peer (`endpoint`, `transport`), the operation, the canonical schema id the node
+resolved (never the alias the peer sent), the record key and the shard id and epoch as sent. `session.serve(...)`
+takes the same `write_authority`. A host that already authenticates its peers, or a test rig, opts in to
+`CultMeshGrantAllWrites()`; the daemon's equivalent is `--allow-peer-writes`. Without it the daemon is read-only to peers.
+
 The same local server can be launched as a package daemon when another runtime
 or operator process needs a CultNet endpoint without embedding Python glue:
 

packages/cultmesh-py/pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
 ]
-dependencies = ["cultcache-py>=0.2.0", "cultnet-py>=0.1.0", "cryptography>=41"]
+dependencies = ["cultcache-py>=0.4.0", "cultnet-py>=0.1.0", "cryptography>=41"]
 [project.scripts]
 cultmesh-py-daemon = "cultmesh_py.daemon:main"
 cultmesh-py-verify = "cultmesh_py.verify:main"

packages/cultmesh-py/src/cultmesh_py/__init__.py

@@ -39,6 +39,14 @@ from .simulation import (
     CultMeshSimulationFactCommitter,
     simulation_fact_document,
 )
+from .write_authority import (
+    CultMeshGrantAllWrites,
+    CultMeshRemoteWriteAuthority,
+    CultMeshRemoteWriteDecision,
+    CultMeshRemoteWriteOperation,
+    CultMeshRemoteWriteRequest,
+    CultMeshServerPeer,
+)
 from cultnet_py.cultmesh_contracts import (
     PEER_EXCHANGE_REQUEST,
     PEER_EXCHANGE_RESPONSE,
@@ -89,6 +97,12 @@ __all__ = [
     "CultMeshSimulationFact",
     "CultMeshSimulationFactCommit",
     "CultMeshSimulationFactCommitter",
+    "CultMeshGrantAllWrites",
+    "CultMeshRemoteWriteAuthority",
+    "CultMeshRemoteWriteDecision",
+    "CultMeshRemoteWriteOperation",
+    "CultMeshRemoteWriteRequest",
+    "CultMeshServerPeer",
     "CultMeshAuthorityLease",
     "CultMeshAuthorityLeaseCatalog",
     "CultMeshHmacAuthorityLeaseVerifier",

packages/cultmesh-py/src/cultmesh_py/daemon.py

@@ -13,6 +13,7 @@ from cultnet_py import CultNetSimulationConsensusOptions, CultNetSimulationObser
 
 from .facade import CultMesh
 from .server import CultMeshLocalServer
+from .write_authority import CultMeshGrantAllWrites
 from cultnet_py.cultmesh_contracts import (
     CultMeshPeerCard,
     CultMeshPeerCatalog,
@@ -53,6 +54,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--simulation-quorum-ratio", type=float, default=0.5)
     parser.add_argument("--verse-id")
     parser.add_argument("--verse-display-name")
+    parser.add_argument("--allow-peer-writes", action="store_true", help="grant every connected peer put and delete; without it peer writes are refused")
     parser.add_argument("--role", action="append", dest="roles")
     args = parser.parse_args(argv)
 
@@ -117,6 +119,7 @@ def start_server(args: argparse.Namespace, parser: argparse.ArgumentParser) -> C
             display_name=args.display_name,
             max_snapshot_documents=args.max_snapshot_documents,
             max_snapshot_bytes=args.max_snapshot_bytes,
+            write_authority=CultMeshGrantAllWrites() if args.allow_peer_writes else None,
         )
     except ValueError as error:
         # The server owns its option rules; a limit it refuses is a usage error, not a crash.

packages/cultmesh-py/src/cultmesh_py/facade.py

@@ -35,6 +35,7 @@ from .node import (
 from .server import CULTMESH_RUDP_DEFAULT_MAX_FRAGMENT_BYTES, CultMeshLocalServer
 from .session import CultMeshGameSession, CultMeshGameSessionOptions
 from .simulation import CultMeshSimulationFactCommitter
+from .write_authority import CultMeshRemoteWriteAuthority
 from cultnet_py.cultmesh_contracts import (
     AuthorityLeaseVerifier,
     CultMeshAuthorityLeaseCatalog,
@@ -400,6 +401,7 @@ class CultMesh:
         verse_catalog: CultMeshVerseCatalog | None = None,
         peer_catalog: CultMeshPeerCatalog | None = None,
         observation_hub: CultNetSimulationObservationHub | None = None,
+        write_authority: CultMeshRemoteWriteAuthority | None = None,
         host: str = "127.0.0.1",
         port: int = 0,
         display_name: str | None = None,
@@ -416,6 +418,7 @@ class CultMesh:
             verse_catalog=verse_catalog or CultMeshVerseCatalog(),
             peer_catalog=peer_catalog or CultMeshPeerCatalog(),
             observation_hub=observation_hub,
+            write_authority=write_authority,
             host=host,
             port=port,
             display_name=display_name,

packages/cultmesh-py/src/cultmesh_py/node.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import Any, Callable
 
 from cultcache_py import CultCache, CultCacheEnvelope, SingleFileMessagePackBackingStore
-from cultcache_py.cache import CultCacheError
+from cultcache_py.cache import CultCacheError, index_text
 from cultcache_py.documents import DocumentDefinition, extract_value
 from cultnet_py import (
     CultNetAppliedRecord,
@@ -520,7 +520,7 @@ class CultMeshDatabase:
             raise ValueError(f"Document type {document.type!r} has no index {index!r}")
 
         def filtered(change: CultMeshDatabaseChange) -> None:
-            if self._change_matches_extractor(change, extractor, value):
+            if self._change_matches_extractor(change, extractor, value, index_text):
                 callback(self._change_as_document(change, requested))
 
         return self.watch(filtered, document=document)
@@ -650,6 +650,29 @@ class CultMeshDatabase:
         self._append_shard_log_delete(message)
         return message
 
+    def raw_put_target(self, message: dict[str, Any]) -> tuple[str, str] | None:
+        """The canonical schema id and record key a raw put would write, or None when it would not apply."""
+        document_record = message.get("document")
+        # Only a document of the wire shape is resolved, so an ungranted peer's payload is never
+        # converted or allocated here: a malformed one is the store's refusal, after the authority.
+        if (
+            not isinstance(document_record, dict)
+            or not isinstance(document_record.get("recordKey"), str)
+            or not isinstance(document_record.get("payload"), (bytes, bytearray, memoryview))
+        ):
+            return None
+        try:
+            prepared = self._raw_put_envelope(message)
+        except Exception:  # noqa: BLE001 - any other malformed shape
+            return None
+        return None if prepared is None else (prepared[0].catalog_entry().schema_id, prepared[1].key)
+
+    def raw_delete_target(self, message: dict[str, Any]) -> tuple[str, str] | None:
+        """The canonical schema id and record key a raw delete names, or None when its schema is not registered."""
+        document = self._document_for_schema(str(message.get("schemaId") or ""))
+        record_key = str(message.get("recordKey") or "")
+        return None if document is None or not record_key else (document.catalog_entry().schema_id, record_key)
+
     def apply_raw_put_message(self, message: dict[str, Any]) -> CultMeshDatabaseChange | None:
         prepared = self._raw_put_envelope(message)
         if prepared is None:
@@ -1272,10 +1295,11 @@ class CultMeshDatabase:
         change: CultMeshDatabaseChange,
         extractor: str | Callable[[Any], str | int | float | bool | None],
         expected: str,
+        render: Callable[[Any], str | None] = str,
     ) -> bool:
         return (
-            self._value_matches_extractor(change.value, extractor, expected)
-            or self._value_matches_extractor(change.previous_value, extractor, expected)
+            self._value_matches_extractor(change.value, extractor, expected, render)
+            or self._value_matches_extractor(change.previous_value, extractor, expected, render)
         )
 
     def _value_matches_extractor(
@@ -1283,11 +1307,12 @@ class CultMeshDatabase:
         value: Any | None,
         extractor: str | Callable[[Any], str | int | float | bool | None],
         expected: str,
+        render: Callable[[Any], str | None] = str,
     ) -> bool:
         if value is None:
             return False
         actual = extract_value(value, extractor)
-        return actual is not None and str(actual) == expected
+        return actual is not None and render(actual) == expected
 
     def _previous_values_for_snapshot_response(self, response: dict[str, Any]) -> dict[tuple[str, str], Any]:
         if response.get("schemaVersion") != "cultnet.snapshot_response_raw.v0":

packages/cultmesh-py/src/cultmesh_py/server.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import errno
 import logging
 import socket
 import threading
@@ -10,6 +11,8 @@ from typing import Any
 import msgpack
 
 from cultnet_py import (
+    error_message,
+    message_invalid_error,
     unsupported_schema_version_error,
     CultNetRawSnapshotResponse,
     CultNetSimulationObservationHub,
@@ -28,6 +31,12 @@ from cultnet_py import (
 )
 
 from .node import CultMeshNode
+from .write_authority import (
+    CultMeshRemoteWriteAuthority,
+    CultMeshRemoteWriteOperation,
+    CultMeshRemoteWriteRequest,
+    CultMeshServerPeer,
+)
 
 # The shortest message id this server answers a snapshot request under. It takes a
 # request's messageId as given, an empty one included, so no response it sends is smaller.
@@ -51,6 +60,17 @@ from cultnet_py.cultmesh_contracts import (
 
 _LOGGER = logging.getLogger(__name__)
 
+# How many consecutive refused frames of one kind a RUDP session may send before it is ended: undecodable
+# frames (reset by any frame that decodes) and deletes the write authority refuses (reset by any decoded
+# frame that is not a refused delete). Fewer are answered with a typed refusal and the session is kept; the
+# frame that reaches this number is answered too, then the session ends. The same number is the cap in every
+# runtime.
+MAX_CONSECUTIVE_REFUSED_FRAMES = 8
+
+# How long a session whose capped frame was answered waits for the peer to acknowledge the answer before it ends anyway.
+_RUDP_CAPPED_ANSWER_GRACE_MS = 2000
+_EPHEMERAL_PAIR_ATTEMPTS = 64
+
 
 class _ReplyUnqueueable(Exception):
     """A reply the peer's reliable queue cannot take. The peer's session ends, and the peer is
@@ -80,6 +100,10 @@ class _DatabaseSubscription:
 class _RudpPeerConnection:
     session: CultNetRudpSession
     subscriptions: dict[str, _DatabaseSubscription] = field(default_factory=dict)
+    undecodable_frames_in_a_row: int = 0
+    refused_deletes_in_a_row: int = 0
+    # Set once the peer's capped frame has been answered: the session ends when the answers are acknowledged.
+    ending_deadline_ms: int | None = None
 
 
 @dataclass
@@ -88,6 +112,9 @@ class CultMeshLocalServer:
     verse_catalog: CultMeshVerseCatalog = field(default_factory=CultMeshVerseCatalog)
     peer_catalog: CultMeshPeerCatalog = field(default_factory=CultMeshPeerCatalog)
     observation_hub: CultNetSimulationObservationHub | None = None
+    # Asked once per peer put and delete. None refuses every one of them (write_not_authorized); a node's own
+    # writes never come through here.
+    write_authority: CultMeshRemoteWriteAuthority | None = None
     host: str = "127.0.0.1"
     port: int = 0
     display_name: str | None = None
@@ -158,26 +185,49 @@ class CultMeshLocalServer:
     def start(self) -> "CultMeshLocalServer":
         if self._socket is not None:
             return self
-        server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        server.bind((self.host, self.port))
-        server.listen()
+        server, rudp_socket = self._bind_sockets()
         server.settimeout(0.2)
         self._socket = server
         self.port = int(server.getsockname()[1])
         self._stop.clear()
         self._thread = threading.Thread(target=self._accept_loop, daemon=True)
         self._thread.start()
-        if self.enable_rudp:
-            rudp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
-            rudp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-            rudp_socket.bind((self.host, self.port))
+        if rudp_socket is not None:
             rudp_socket.settimeout(0.02)
             self._rudp_socket = rudp_socket
             self._rudp_thread = threading.Thread(target=self._rudp_loop, daemon=True)
             self._rudp_thread.start()
         return self
 
+    def _bind_sockets(self) -> tuple[socket.socket, socket.socket | None]:
+        """The listening TCP socket and, when RUDP is on, the UDP socket on the same port number.
+
+        An explicit port is bound as asked and a failure is the caller's. Port 0 asks for any free port, and the
+        kernel picks the TCP one without knowing whether another process holds that number for UDP, so a
+        UDP collision retries with a fresh TCP port instead of failing the start. Both sockets are bound
+        before any thread starts, so a failed start leaves nothing running or open.
+        """
+        attempts = _EPHEMERAL_PAIR_ATTEMPTS if self.port == 0 and self.enable_rudp else 1
+        for attempt in range(attempts):
+            server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            rudp_socket = None
+            try:
+                server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                server.bind((self.host, self.port))
+                server.listen()
+                if self.enable_rudp:
+                    rudp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+                    rudp_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                    rudp_socket.bind((self.host, int(server.getsockname()[1])))
+                return server, rudp_socket
+            except OSError as error:
+                server.close()
+                if rudp_socket is not None:
+                    rudp_socket.close()
+                if error.errno != errno.EADDRINUSE or attempt == attempts - 1:
+                    raise
+        raise AssertionError("unreachable")
+
     def stop(self) -> None:
         self._stop.set()
         if self._rudp_socket is not None:
@@ -238,14 +288,15 @@ class CultMeshLocalServer:
             if server is None:
                 return
             try:
-                client, _ = server.accept()
+                client, address = server.accept()
             except TimeoutError:
                 continue
             except OSError:
                 return
-            threading.Thread(target=self._handle_connection, args=(client,), daemon=True).start()
+            peer = CultMeshServerPeer(f"{address[0]}:{address[1]}", "tcp")
+            threading.Thread(target=self._handle_connection, args=(client, peer), daemon=True).start()
 
-    def _handle_connection(self, client: socket.socket) -> None:
+    def _handle_connection(self, client: socket.socket, peer: CultMeshServerPeer) -> None:
         with client:
             stream = client.makefile("rwb")
             transport = TcpFramedTransportConnection(
@@ -267,7 +318,7 @@ class CultMeshLocalServer:
                 if not isinstance(message, dict):
                     continue
                 try:
-                    responses = self._handle_connection_message(message, subscriptions)
+                    responses = self._handle_connection_message(message, subscriptions, peer=peer)
                 except Exception as error:  # noqa: BLE001 - one message never ends the connection
                     # Whatever a peer's message makes the handling raise is that peer's failure:
                     # it is refused with fixed text and the connection serves on. The log names
@@ -309,6 +360,7 @@ class CultMeshLocalServer:
             if packet.connection_id != self.rudp_connection_id:
                 continue
 
+            self._end_answered_peers(rudp_socket, peers)
             now_ms = _now_ms()
             peer = peers.get(remote_addr)
             if packet.packet_type == CultNetRudpPacketType.CONNECT:
@@ -357,13 +409,31 @@ class CultMeshLocalServer:
                 for delivered in result.delivered:
                     if delivered.channel_id != "schema":
                         continue
+                    if peer.ending_deadline_ms is not None:
+                        # The capped frame was answered; nothing after it is served while the answer is delivered.
+                        break
                     try:
                         message = msgpack.unpackb(delivered.payload, raw=False)
                     except (msgpack.ExtraData, msgpack.FormatError, msgpack.StackError, ValueError):
-                        continue
-                    if not isinstance(message, dict):
-                        continue
-                    responses = self._handle_connection_message(message, peer.subscriptions, over_rudp=True)
+                        message = None
+                    if isinstance(message, dict):
+                        peer.undecodable_frames_in_a_row = 0
+                        responses = self._handle_connection_message(
+                            message,
+                            peer.subscriptions,
+                            over_rudp=True,
+                            peer=CultMeshServerPeer(f"{remote_addr[0]}:{remote_addr[1]}", "rudp"),
+                        )
+                        refused_delete = message.get("schemaVersion") == "cultnet.document_delete.v0" and any(
+                            response.get("code") == "write_not_authorized" for response in responses
+                        )
+                        peer.refused_deletes_in_a_row = peer.refused_deletes_in_a_row + 1 if refused_delete else 0
+                        refused, run = refused_delete, peer.refused_deletes_in_a_row
+                    else:
+                        # A frame that is no CultNet message is answered, not dropped, and the session kept.
+                        peer.undecodable_frames_in_a_row += 1
+                        refused, run = True, peer.undecodable_frames_in_a_row
+                        responses = [self._message_invalid({}, "message", "CultMesh RUDP server could not read the message.")]
                     for response in responses:
                         if unsendable is None:
                             unsendable = self._send_rudp_schema_frame(
@@ -373,6 +443,11 @@ class CultMeshLocalServer:
                                 msgpack.packb(response, use_bin_type=True),
                                 message_id=str(response.get("messageId") or ""),
                             )
+                    if refused and run >= MAX_CONSECUTIVE_REFUSED_FRAMES:
+                        # The capped frame is answered like any other, reliably. The session ends once the peer
+                        # has acknowledged every answer (or the grace runs out): see _end_answered_peers.
+                        peer.ending_deadline_ms = now_ms + _RUDP_CAPPED_ANSWER_GRACE_MS
+                        break
             except Exception as error:  # noqa: BLE001 - one peer's message never ends the thread
                 # Whatever a peer's message makes the handling raise is that peer's failure.
                 # The session recorded the frame's sequence, so it cannot be kept: a retransmit
@@ -403,11 +478,26 @@ class CultMeshLocalServer:
             if unsendable is not None:
                 self._end_unsendable_peer(rudp_socket, peers, remote_addr, unsendable)
 
+    def _end_answered_peers(
+        self,
+        rudp_socket: socket.socket,
+        peers: dict[tuple[str, int], _RudpPeerConnection],
+    ) -> None:
+        """Ends each session whose capped frame was answered once the peer has acknowledged every answer (a lost
+        answer is resent first), or when the grace has run out."""
+        now_ms = _now_ms()
+        for remote_addr, peer in list(peers.items()):
+            if peer.ending_deadline_ms is None:
+                continue
+            if peer.session.outstanding_reliable_packet_count == 0 or now_ms >= peer.ending_deadline_ms:
+                self._end_refused_peer(rudp_socket, peers, remote_addr)
+
     def _poll_rudp_resends(
         self,
         rudp_socket: socket.socket,
         peers: dict[tuple[str, int], _RudpPeerConnection],
     ) -> None:
+        self._end_answered_peers(rudp_socket, peers)
         now_ms = _now_ms()
         for remote_addr, peer in list(peers.items()):
             for packet in peer.session.due_resends(now_ms):
@@ -519,6 +609,7 @@ class CultMeshLocalServer:
         subscriptions: dict[str, _DatabaseSubscription],
         *,
         over_rudp: bool = False,
+        peer: CultMeshServerPeer | None = None,
     ) -> list[dict[str, Any]]:
         schema_version = message.get("schemaVersion")
         if schema_version == "cultnet.database_subscribe.v0":
@@ -542,9 +633,9 @@ class CultMeshLocalServer:
             subscriptions.pop(str(message.get("subscriptionId") or ""), None)
             return []
         if schema_version == "cultnet.document_put_raw.v0":
-            return self._handle_raw_put(message, subscriptions, over_rudp=over_rudp)
+            return self._handle_raw_put(message, subscriptions, over_rudp=over_rudp, peer=peer)
         if schema_version == "cultnet.document_delete.v0":
-            return self._handle_raw_delete(message, subscriptions)
+            return self._handle_raw_delete(message, subscriptions, peer=peer)
         if schema_version == "cultnet.simulation_observation.v0":
             return self._candidate_responses(message)
         response = self.handle_message(message)
@@ -556,14 +647,27 @@ class CultMeshLocalServer:
         subscriptions: dict[str, _DatabaseSubscription],
         *,
         over_rudp: bool = False,
+        peer: CultMeshServerPeer | None = None,
     ) -> list[dict[str, Any]]:
         document_record = message.get("document")
         if not isinstance(document_record, dict):
-            return [self._error_response(
-                "Raw put messages must contain a document map.",
-                message_id=str(message.get("messageId") or ""),
-                code="malformed_document_put",
-            )]
+            return [self._message_invalid(message, "document", "Raw put messages must contain a document map.")]
+        malformed_shard = self._malformed_shard_fields(message)
+        if malformed_shard is not None:
+            return [malformed_shard]
+        # Refusal precedes every other judgment of the put. The node resolves the schema first, because the
+        # authority must be asked about the canonical schema id (a payload-inferred alias included), as C#
+        # does; only a payload of the wire shape is resolved, so nothing of an ungranted peer's is
+        # allocated. A put the node cannot resolve is asked about under the ids as sent. Residual: the
+        # refusal is the same either way, but an ungranted peer can still tell registered from unregistered
+        # schemas by timing.
+        target = self.node.database.raw_put_target(message) or (
+            str(document_record.get("schemaId") or ""),
+            str(document_record.get("recordKey") or ""),
+        )
+        refusal = self._refuse_unauthorized_write(peer, CultMeshRemoteWriteOperation.PUT, target, message)
+        if refusal is not None:
+            return [refusal]
         unservable = self._unservable_put(message, over_rudp=over_rudp)
         if unservable is not None:
             return [unservable]
@@ -575,11 +679,7 @@ class CultMeshLocalServer:
             # raises. It is refused to the peer that sent it; no thread and no other peer is
             # affected. Neither the refusal nor the log quotes the error, which can quote the put.
             _LOGGER.warning("CultMesh server refused a raw put the store could not take (%s).", type(error).__name__)
-            return [self._error_response(
-                "Raw put document could not be stored.",
-                message_id=str(message.get("messageId") or ""),
-                code="malformed_document_put",
-            )]
+            return [self._message_invalid(message, "document", "Raw put document could not be stored.")]
         if change is None:
             return [self._error_response(
                 "Raw put message did not apply to a registered document.",
@@ -598,15 +698,22 @@ class CultMeshLocalServer:
         self,
         message: dict[str, Any],
         subscriptions: dict[str, _DatabaseSubscription],
+        *,
+        peer: CultMeshServerPeer | None = None,
     ) -> list[dict[str, Any]]:
         schema_id = str(message.get("schemaId") or "")
         record_key = str(message.get("recordKey") or "")
         if not schema_id or not record_key:
-            return [self._error_response(
-                "Raw delete messages must contain schemaId and recordKey.",
-                message_id=str(message.get("messageId") or ""),
-                code="malformed_document_delete",
+            return [self._message_invalid(
+                message, "schemaId" if not schema_id else "recordKey", "Raw delete messages must contain schemaId and recordKey.",
             )]
+        malformed_shard = self._malformed_shard_fields(message)
+        if malformed_shard is not None:
+            return [malformed_shard]
+        target = self.node.database.raw_delete_target(message) or (schema_id, record_key)
+        refusal = self._refuse_unauthorized_write(peer, CultMeshRemoteWriteOperation.DELETE, target, message)
+        if refusal is not None:
+            return [refusal]
         change = self.node.database.apply_raw_delete_message(message)
         if change is None:
             return [self._error_response(
@@ -616,6 +723,70 @@ class CultMeshLocalServer:
             )]
         return self._database_delete_notifications(message, subscriptions, resolved_schema_id=change.schema_id)
 
+    def _message_invalid(self, message: dict[str, Any], field: str, reason: str) -> dict[str, Any]:
+        """The typed `message_invalid` refusal naming the request field at fault, under the request's messageId."""
+        response = message_invalid_error(field, reason).to_wire()
+        response["messageId"] = str(message.get("messageId") or "")
+        return response
+
+    def _malformed_shard_fields(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        """The protocol error for a shardId that is not a string or a shardEpoch that is not an int (a bool is
+        not), else None. It precedes the gate, so the authority only ever judges a write whose shard it can
+        read, and the store never files a write under a shard the authority did not see."""
+        shard_id = message.get("shardId")
+        shard_epoch = message.get("shardEpoch")
+        if (shard_id is None or isinstance(shard_id, str)) and (
+            shard_epoch is None or (isinstance(shard_epoch, int) and not isinstance(shard_epoch, bool))
+        ):
+            return None
+        return self._message_invalid(
+            message,
+            "shardId" if not (shard_id is None or isinstance(shard_id, str)) else "shardEpoch",
+            "shardId must be a string and shardEpoch an integer.",
+        )
+
+    def _refuse_unauthorized_write(
+        self,
+        peer: CultMeshServerPeer | None,
+        operation: CultMeshRemoteWriteOperation,
+        target: tuple[str, str],
+        message: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """None when the write may proceed, else the typed refusal for the sending peer.
+
+        No authority configured refuses; an authority that raises refuses too (fail closed) and is logged.
+        """
+        schema_id, record_key = target
+        reason: str | None
+        authority = self.write_authority
+        if authority is None:
+            reason = "no remote write authority is configured"
+        else:
+            request = CultMeshRemoteWriteRequest(
+                peer=peer or CultMeshServerPeer("", "unknown"),
+                operation=operation,
+                schema_id=schema_id,
+                record_key=record_key,
+                shard_id=message.get("shardId"),
+                shard_epoch=message.get("shardEpoch"),
+            )
+            try:
+                decision = authority.decide(request)
+            except Exception as error:  # noqa: BLE001 - a failing authority refuses
+                _LOGGER.error("CultMesh remote write authority failed (%s); the write was refused.", type(error).__name__)
+                decision = None
+                reason = "the write authority failed"
+            else:
+                reason = getattr(decision, "reason", None)
+            if decision is not None and getattr(decision, "is_granted", False) is True:
+                return None
+        _LOGGER.warning("CultMesh %s of %s refused: write not authorized.", operation.value, schema_id)
+        return error_message(
+            f"write_not_authorized: {reason}" if reason and reason.strip() else "write_not_authorized",
+            code="write_not_authorized",
+            details={"field": "recordKey", "value": record_key},
+        ).to_wire()
+
     def _database_change_notifications(
         self,
         message: dict[str, Any],
@@ -803,11 +974,7 @@ class CultMeshLocalServer:
             and isinstance(document_record.get("recordKey"), str)
             and isinstance(document_record.get("payload"), (bytes, bytearray))
         ):
-            return self._error_response(
-                "Raw put documents must carry a string recordKey and a binary payload.",
-                message_id=str(message.get("messageId") or ""),
-                code="malformed_document_put",
-            )
+            return self._message_invalid(message, "document", "Raw put documents must carry a string recordKey and a binary payload.")
         if self.max_snapshot_bytes is None and not over_rudp:
             return None
         alone = self.node.database.raw_put_served_alone(message, message_id=_SHORTEST_SERVED_MESSAGE_ID)

packages/cultmesh-py/src/cultmesh_py/session.py

@@ -27,6 +27,7 @@ from cultnet_py.cultmesh_contracts import CultMeshAuthorityLeaseCatalog, CultMes
 
 if TYPE_CHECKING:
     from .server import CultMeshLocalServer
+    from .write_authority import CultMeshRemoteWriteAuthority
 
 
 @dataclass(frozen=True)
@@ -83,6 +84,7 @@ class CultMeshGameSession:
     def serve(
         self,
         *,
+        write_authority: CultMeshRemoteWriteAuthority | None = None,
         host: str = "127.0.0.1",
         port: int = 0,
         display_name: str | None = None,
@@ -96,6 +98,7 @@ class CultMeshGameSession:
             verse_catalog=self.verse_catalog if self._serve_verse_discovery else CultMeshVerseCatalog(),
             peer_catalog=self.peer_catalog if self._serve_peer_exchange else CultMeshPeerCatalog(),
             observation_hub=self.observation_hub if self._serve_simulation_observations else None,
+            write_authority=write_authority,
             host=host,
             port=port,
             display_name=display_name,

packages/cultmesh-py/src/cultmesh_py/write_authority.py

@@ -0,0 +1,66 @@
+"""The one question a CultMesh server asks before it applies a peer's write.
+
+Mirrors C# ``ICultNetRemoteWriteAuthority``: a server with no authority refuses every peer put and
+delete, so serving a node never lets a connected peer overwrite its documents by default.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+
+class CultMeshRemoteWriteOperation(Enum):
+    PUT = "put"
+    DELETE = "delete"
+
+
+@dataclass(frozen=True)
+class CultMeshServerPeer:
+    """The connection a write arrived on: its endpoint and transport, nothing the peer claimed."""
+
+    endpoint: str
+    transport: str
+
+
+@dataclass(frozen=True)
+class CultMeshRemoteWriteRequest:
+    """One peer write as the authority sees it.
+
+    ``schema_id`` is the canonical id the node resolved for the write, never an alias the peer sent.
+    ``shard_id`` and ``shard_epoch`` are as the peer sent them.
+    """
+
+    peer: CultMeshServerPeer
+    operation: CultMeshRemoteWriteOperation
+    schema_id: str
+    record_key: str
+    shard_id: str | None = None
+    shard_epoch: int | None = None
+
+
+@dataclass(frozen=True)
+class CultMeshRemoteWriteDecision:
+    is_granted: bool
+    reason: str | None = None
+
+    @staticmethod
+    def grant() -> CultMeshRemoteWriteDecision:
+        return CultMeshRemoteWriteDecision(True)
+
+    @staticmethod
+    def refuse(reason: str | None = None) -> CultMeshRemoteWriteDecision:
+        return CultMeshRemoteWriteDecision(False, reason)
+
+
+class CultMeshRemoteWriteAuthority(Protocol):
+    def decide(self, request: CultMeshRemoteWriteRequest) -> CultMeshRemoteWriteDecision: ...
+
+
+class CultMeshGrantAllWrites:
+    """Grants every peer write. For a host that has already authenticated its peers (or a test rig); it is
+    an explicit choice because serving without an authority refuses writes."""
+
+    def decide(self, request: CultMeshRemoteWriteRequest) -> CultMeshRemoteWriteDecision:
+        return CultMeshRemoteWriteDecision.grant()

packages/cultmesh-py/tests/test_client_write_completion.py

@@ -0,0 +1,52 @@
+"""Heimdall's invariant: no client treats a reliable-transport ack as write admission. A put completes only on
+its result frame (write_not_authorized, or the success reply).
+
+The Python write path is a subscription over RUDP: `send` queues the put, `read_next` returns the result frame
+and raises the peer's refusal. The server here refuses the put; its reliable ack of the put arrives (the test
+waits for it) and the client still reports the refusal, never success. The transport's `receive` yields data
+frames only, so the order of the ack against the refusal cannot change what `read_next` reports.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from cultcache_py import define_database_entry_type
+from cultmesh_py import CultMesh, create_node
+from cultmesh_py.server import CultMeshLocalServer
+from cultnet_py import CultNetDatabaseSubscription, CultNetPeerError, create_rudp_schema_transport
+
+from test_remote_write_authority import KEY_A, NOTE, SCHEMA_ID, put_of
+
+
+class ClientWriteCompletionTests(unittest.TestCase):
+    def test_a_put_the_server_refused_is_reported_refused_after_its_ack_arrived(self) -> None:
+        node = create_node(runtime_id="completion-server")
+        node.database.register_document(NOTE)
+        server = CultMeshLocalServer(node=node, port=0, write_authority=None)
+        server.start()
+        try:
+            subscription = CultNetDatabaseSubscription(
+                host="127.0.0.1",
+                port=server.port,
+                timeout_seconds=4.0,
+                subscription_id="completion",
+                schema_ids=[SCHEMA_ID],
+                include_snapshot=False,
+                create_transport=lambda: create_rudp_schema_transport(
+                    host="127.0.0.1", port=server.port, connection_id=server.rudp_connection_id, timeout_seconds=4.0
+                ),
+            )
+            with subscription as sub:
+                sub.send(put_of(KEY_A, "peer"))
+                sub._transport.flush_reliable(2.0)  # the put's reliable ack has arrived
+                with self.assertRaises(CultNetPeerError) as raised:
+                    sub.read_next()
+        finally:
+            server.stop()
+        self.assertEqual(raised.exception.response["code"], "write_not_authorized")
+        self.assertIsNone(server.node.cache.get(NOTE, KEY_A))
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultmesh-py/tests/test_cultmesh.py

@@ -24,7 +24,9 @@ from cultcache_py import (
     define_document_type,
 )
 from cultcache_py.interop import INTEROP_SCHEMA_VERSION, interop_note_document
+from cultmesh_py.server import MAX_CONSECUTIVE_REFUSED_FRAMES
 from cultmesh_py.verify import verify
+from cultmesh_py.write_authority import CultMeshRemoteWriteDecision
 from cultnet_py import (
     compute_simulation_claim_hash,
     CultNetClientAuthorityScope,
@@ -68,7 +70,7 @@ from cultnet_py import (
     snapshot_request,
 )
 from cultnet_py.cultmesh_contracts import VERSE_CATALOG_REQUEST
-from cultmesh_py import create_node
+from cultmesh_py import CultMeshGrantAllWrites, create_node
 from cultmesh_py import (
     CultMesh,
     CultMeshDatabase,
@@ -1631,7 +1633,7 @@ class CultMeshTests(unittest.TestCase):
         )
         primary = CultMesh.create_node(runtime_id="forward-primary")
         primary.database.register_document(document)
-        server = CultMesh.serve_node(primary)
+        server = CultMesh.serve_node(primary, write_authority=CultMeshGrantAllWrites())
         try:
             shard = CultNetShardDescriptor(
                 shard_id="forward",
@@ -3015,7 +3017,7 @@ class CultMeshTests(unittest.TestCase):
         source.database.put_raw_message(document, "note:live", CanonicalNote("initial"))
         target = CultMesh.create_node(runtime_id="subscription-alias-target")
         target.database.register_document(document)
-        server = CultMesh.serve_node(source)
+        server = CultMesh.serve_node(source, write_authority=CultMeshGrantAllWrites())
         try:
             raw_client = CultMesh.create_client("127.0.0.1", server.port, timeout_seconds=2.0)
             with CultMesh.subscribe_document(target, raw_client, alias, "note:live") as subscription:
@@ -3533,6 +3535,7 @@ class CultMeshTests(unittest.TestCase):
                     sys.executable,
                     "-m",
                     "cultmesh_py.daemon",
+                    "--allow-peer-writes",
                     "--runtime-id",
                     "live-daemon-peer",
                     "--port",
@@ -3723,6 +3726,7 @@ class CultMeshTests(unittest.TestCase):
                     sys.executable,
                     "-m",
                     "cultmesh_py.daemon",
+                    "--allow-peer-writes",
                     "--runtime-id",
                     "forwarder-daemon-peer",
                     "--port",
@@ -3998,6 +4002,7 @@ class CultMeshTests(unittest.TestCase):
         server = CultMesh.serve_node(
             node,
             verse_catalog=verses,
+            write_authority=CultMeshGrantAllWrites(),
             peer_catalog=peers,
             observation_hub=observation_hub,
             display_name="Mesh Server",
@@ -4274,7 +4279,7 @@ class CultMeshTests(unittest.TestCase):
         node = CultMesh.create_node(runtime_id="mesh-alias-sub-server")
         node.database.register_document(document)
 
-        server = CultMesh.serve_node(node)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
         try:
             raw_client = CultMesh.create_client("127.0.0.1", server.port, timeout_seconds=2.0)
             with raw_client.subscribe_database(
@@ -4323,7 +4328,7 @@ class CultMeshTests(unittest.TestCase):
             shard_epoch=1,
         )
 
-        server = CultMesh.serve_node(node)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
         try:
             raw_client = CultMesh.create_client("127.0.0.1", server.port, timeout_seconds=2.0)
             with raw_client.subscribe_database(
@@ -4420,7 +4425,7 @@ class CultMeshTests(unittest.TestCase):
         def served_alone_bytes(key: str, body_length: int) -> int:
             node = CultMesh.create_node(runtime_id="mesh-served-bound-probe")
             node.database.register_document(document)
-            server = CultMesh.serve_node(node, enable_rudp=False)
+            server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites(), enable_rudp=False)
             try:
                 response, payload = exchange(server, put("probe", key, body_length), empty_id_snapshot)
             finally:
@@ -4434,7 +4439,7 @@ class CultMeshTests(unittest.TestCase):
 
         node = CultMesh.create_node(runtime_id="mesh-served-bound")
         node.database.register_document(document)
-        server = CultMesh.serve_node(node, max_snapshot_bytes=limit, enable_rudp=False)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites(), max_snapshot_bytes=limit, enable_rudp=False)
         try:
             refused, _ = exchange(server, put("put-over", "note:over", 101))
             stored_after_refusal = node.database.get(document, "note:over")
@@ -4498,7 +4503,7 @@ class CultMeshTests(unittest.TestCase):
         document = self._rudp_bound_note()
         node = CultMesh.create_node(runtime_id="mesh-rudp-large")
         node.database.register_document(document)
-        server = CultMesh.serve_node(node)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
         try:
             served, payload = self._rudp_exchange(
                 server,
@@ -4524,7 +4529,7 @@ class CultMeshTests(unittest.TestCase):
         def served_alone_bytes(body_length: int) -> int:
             node = CultMesh.create_node(runtime_id="mesh-rudp-bound-probe")
             node.database.register_document(document)
-            server = CultMesh.serve_node(node)
+            server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
             try:
                 _, payload = self._rudp_exchange(
                     server, self._rudp_note_put(document, "probe", key, body_length),
@@ -4554,7 +4559,7 @@ class CultMeshTests(unittest.TestCase):
 
         node = CultMesh.create_node(runtime_id="mesh-rudp-bound")
         node.database.register_document(document)
-        server = CultMesh.serve_node(node, rudp_max_fragment_bytes=100, rudp_max_pending_reliable_packets=8)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites(), rudp_max_fragment_bytes=100, rudp_max_pending_reliable_packets=8)
         try:
             refusals = [
                 self._rudp_exchange(server, self._rudp_note_put(document, f"put-{served}", "note:q", body_for(served)))[0]
@@ -4792,7 +4797,7 @@ class CultMeshTests(unittest.TestCase):
         body_for = self._rudp_body_for(document, "note:w")
         node = CultMesh.create_node(runtime_id="mesh-rudp-wide")
         node.database.register_document(document)
-        server = CultMesh.serve_node(node, rudp_max_fragment_bytes=1)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites(), rudp_max_fragment_bytes=1)
         try:
             transport = create_rudp_schema_transport(
                 host="127.0.0.1", port=server.port, connection_id=server.rudp_connection_id,
@@ -4857,7 +4862,7 @@ class CultMeshTests(unittest.TestCase):
         document = self._rudp_bound_note()
         node = CultMesh.create_node(runtime_id="mesh-rudp-malformed")
         node.database.register_document(document)
-        server = CultMesh.serve_node(node)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
         try:
             refusals = []
             for field_name, value in (
@@ -4880,11 +4885,146 @@ class CultMeshTests(unittest.TestCase):
         for message_id, refusal in refusals:
             self.assertEqual(refusal["schemaVersion"], "cultnet.error.v0", message_id)
             self.assertEqual(refusal["messageId"], message_id)
-            self.assertEqual(refusal["code"], "malformed_document_put", message_id)
+            self.assertEqual(refusal["code"], "message_invalid", message_id)
+            self.assertEqual(refusal["details"]["field"], "document", message_id)
         self.assertEqual(after["messageId"], "after")
         self.assertEqual(after["documents"], [])
         self.assertTrue(alive)
 
+    def _rudp_open(self, server: Any) -> Any:
+        return create_rudp_schema_transport(
+            host="127.0.0.1",
+            port=server.port,
+            connection_id=server.rudp_connection_id,
+            timeout_seconds=4.0,
+            max_fragment_bytes=1200,
+        )
+
+    def _rudp_answer(self, transport: Any, payload: bytes) -> dict[str, Any]:
+        transport.send("schema", payload)
+        return msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+
+    def _assert_rudp_session_ended(self, transport: Any, server: Any) -> None:
+        transport.send("schema", msgpack.packb(snapshot_request(message_id="after-cap").to_wire(), use_bin_type=True))
+        with self.assertRaises(Exception):
+            transport.receive(timeout_seconds=1.0)
+        self.assertTrue(server._rudp_thread.is_alive())
+
+    def test_cultmesh_local_server_answers_unreadable_frames_and_ends_the_session_at_eight_in_a_row(self) -> None:
+        # An undecodable frame (not a msgpack map) is answered message_invalid and the session kept;
+        # eight in a row end it (the eighth is answered too); any decoded frame resets the run.
+        self.assertEqual(MAX_CONSECUTIVE_REFUSED_FRAMES, 8)
+        node = CultMesh.create_node(runtime_id="mesh-rudp-unreadable")
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
+        garbage = b"\xc1"
+        snapshot = msgpack.packb(snapshot_request(message_id="ok").to_wire(), use_bin_type=True)
+        transport = self._rudp_open(server)
+        try:
+            for _ in range(2):
+                for _ in range(MAX_CONSECUTIVE_REFUSED_FRAMES - 1):
+                    reply = self._rudp_answer(transport, garbage)
+                    self.assertEqual(reply["code"], "message_invalid")
+                    self.assertEqual(reply["details"]["field"], "message")
+                self.assertEqual(self._rudp_answer(transport, snapshot)["messageId"], "ok")
+            for _ in range(MAX_CONSECUTIVE_REFUSED_FRAMES - 1):
+                self._rudp_answer(transport, garbage)
+            transport.send("schema", garbage)
+            eighth = msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+            self.assertEqual(eighth["code"], "message_invalid")
+            self._assert_rudp_session_ended(transport, server)
+        finally:
+            transport.close()
+            server.stop()
+
+    def test_cultmesh_local_server_resends_a_lost_capped_answer_before_it_ends_the_session(self) -> None:
+        # The eighth refusal is answered reliably: the datagram carrying it is lost on the wire, and the
+        # peer still gets the answer (by resend) before the goodbye. An unreliable final answer, or a
+        # goodbye sent at once, would leave the peer without it.
+        node = CultMesh.create_node(runtime_id="mesh-rudp-lost-answer")
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
+        send = server._send_rudp_packet
+        dropped: list[Any] = []
+        armed = threading.Event()
+
+        def lossy(rudp_socket: Any, remote_addr: Any, packet: Any) -> Any:
+            if armed.is_set() and not dropped and packet.packet_type == CultNetRudpPacketType.DATA and b"message_invalid" in (packet.payload or b""):
+                dropped.append(packet)
+                return None
+            return send(rudp_socket, remote_addr, packet)
+
+        server._send_rudp_packet = lossy
+        transport = self._rudp_open(server)
+        try:
+            for _ in range(MAX_CONSECUTIVE_REFUSED_FRAMES - 1):
+                self._rudp_answer(transport, b"\xc1")
+            armed.set()
+            reply = self._rudp_answer(transport, b"\xc1")
+            self.assertEqual(len(dropped), 1, "fixture: the first transmission of the last answer was lost")
+            self.assertEqual(reply["code"], "message_invalid")
+            self._assert_rudp_session_ended(transport, server)
+        finally:
+            transport.close()
+            server.stop()
+
+    def test_cultmesh_local_server_serves_nothing_after_the_capped_frame(self) -> None:
+        node = CultMesh.create_node(runtime_id="mesh-rudp-after-cap")
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
+        transport = self._rudp_open(server)
+        try:
+            for _ in range(MAX_CONSECUTIVE_REFUSED_FRAMES - 1):
+                self._rudp_answer(transport, b"\xc1")
+            transport.send("schema", b"\xc1")
+            transport.send("schema", msgpack.packb(snapshot_request(message_id="behind-the-cap").to_wire(), use_bin_type=True))
+            first = msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+            self.assertEqual(first["code"], "message_invalid")
+            with self.assertRaises(Exception):
+                transport.receive(timeout_seconds=1.0)
+        finally:
+            transport.close()
+            server.stop()
+
+    def test_cultmesh_local_server_ends_the_session_at_eight_refused_deletes_in_a_row(self) -> None:
+        class GrantOnlyKeyB:
+            def decide(self, request: Any) -> Any:
+                return CultMeshRemoteWriteDecision.grant() if request.record_key == "note:b" else CultMeshRemoteWriteDecision.refuse("no")
+
+        document = self._rudp_bound_note()
+        node = CultMesh.create_node(runtime_id="mesh-rudp-deletes")
+        node.database.register_document(document)
+        server = CultMesh.serve_node(node, write_authority=GrantOnlyKeyB())
+
+        def delete(key: str) -> bytes:
+            return msgpack.packb({
+                "schemaVersion": "cultnet.document_delete.v0",
+                "messageId": f"del-{key}",
+                "schemaId": document.schema_id,
+                "recordKey": key,
+            }, use_bin_type=True)
+
+        snapshot = msgpack.packb(snapshot_request(message_id="ok").to_wire(), use_bin_type=True)
+        transport = self._rudp_open(server)
+        try:
+            def refused_run(count: int) -> None:
+                for _ in range(count):
+                    reply = self._rudp_answer(transport, delete("note:a"))
+                    self.assertEqual(reply["code"], "write_not_authorized")
+                    self.assertEqual(reply["details"]["value"], "note:a")
+
+            refused_run(MAX_CONSECUTIVE_REFUSED_FRAMES - 1)
+            # A granted delete resets the run (nothing is stored under it, so the store answers that).
+            self.assertEqual(self._rudp_answer(transport, delete("note:b"))["code"], "unregistered_document_delete")
+            refused_run(MAX_CONSECUTIVE_REFUSED_FRAMES - 1)
+            # So does any decoded non-delete frame.
+            self.assertEqual(self._rudp_answer(transport, snapshot)["messageId"], "ok")
+            refused_run(MAX_CONSECUTIVE_REFUSED_FRAMES - 1)
+            transport.send("schema", delete("note:a"))
+            eighth = msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+            self.assertEqual(eighth["code"], "write_not_authorized")
+            self._assert_rudp_session_ended(transport, server)
+        finally:
+            transport.close()
+            server.stop()
+
     def test_cultmesh_local_server_refuses_a_put_its_store_cannot_take_and_serves_on(self) -> None:
         # Well-formed puts the store refuses: a blank key, a payload that is not MessagePack, a
         # payload its schema cannot decode, a global document under another key. Each is refused
@@ -4917,7 +5057,7 @@ class CultMeshTests(unittest.TestCase):
         node = CultMesh.create_node(runtime_id="mesh-unstorable-put")
         node.database.register_document(document)
         node.database.register_document(global_document)
-        server = CultMesh.serve_node(node)
+        server = CultMesh.serve_node(node, write_authority=CultMeshGrantAllWrites())
         try:
             rudp_refusals = [(put["messageId"], self._rudp_exchange(server, put)[0]) for put in cases()]
             rudp_after, _ = self._rudp_exchange(server, hello(runtime_id="rudp-after").to_wire())
@@ -4939,7 +5079,8 @@ class CultMeshTests(unittest.TestCase):
         for message_id, refusal in rudp_refusals + tcp_refusals:
             self.assertEqual(refusal["schemaVersion"], "cultnet.error.v0", message_id)
             self.assertEqual(refusal["messageId"], message_id)
-            self.assertEqual(refusal["code"], "malformed_document_put", message_id)
+            self.assertEqual(refusal["code"], "message_invalid", message_id)
+            self.assertEqual(refusal["details"]["field"], "document", message_id)
             self.assertNotIn("note:ok", refusal["error"], message_id)
         self.assertEqual(len(tcp_refusals), 5)
         self.assertEqual(rudp_after["schemaVersion"], "cultnet.hello.v0")
@@ -5053,9 +5194,11 @@ class CultMeshTests(unittest.TestCase):
         self.assertEqual(unsupported["details"]["value"], "cultnet.nope.v0")
         self.assertIn("unsupported_schema_version", unsupported["error"])
         self.assertEqual(malformed_put["messageId"], "bad-put")
-        self.assertEqual(malformed_put["code"], "malformed_document_put")
+        self.assertEqual(malformed_put["code"], "message_invalid")
+        self.assertEqual(malformed_put["details"]["field"], "document")
         self.assertEqual(malformed_delete["messageId"], "bad-delete")
-        self.assertEqual(malformed_delete["code"], "malformed_document_delete")
+        self.assertEqual(malformed_delete["code"], "message_invalid")
+        self.assertEqual(malformed_delete["details"]["field"], "recordKey")
         self.assertEqual(unsupported_v1["code"], "unsupported_schema_version")
         self.assertEqual(unsupported_v1["details"]["value"], "cultnet.snapshot_request.v1")
 

packages/cultmesh-py/tests/test_remote_write_authority.py

@@ -0,0 +1,338 @@
+"""A peer's put or delete is applied only when the server's write authority grants it.
+
+Ports the behaviours of C# RemoteWriteAuthorityTests. The C# forwarding behaviour (a refused write is never
+forwarded) has no counterpart: this server does not forward non-primary writes. The handlers are reached with
+the peer the connection loop would pass, and one test drives the same path over a real TCP connection.
+"""
+
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+from typing import Any
+
+import msgpack
+from cultcache_py import define_database_entry_type
+from cultmesh_py import (
+    CultMesh,
+    CultMeshGrantAllWrites,
+    CultMeshRemoteWriteDecision,
+    CultMeshRemoteWriteOperation,
+    CultMeshRemoteWriteRequest,
+    CultMeshServerPeer,
+    create_node,
+)
+from cultmesh_py.server import CultMeshLocalServer
+from cultnet_py import CultNetPeerError, create_rudp_schema_transport, document_delete, document_put_raw, error_message
+
+SCHEMA_ID = "sha256:authority-note"
+ALIAS = "runtime.generated.authority-note.ui.42"
+SHARD_ID = "authority-shard"
+KEY_A = "tests:authority:a"
+KEY_B = "tests:authority:b"
+PEER = CultMeshServerPeer("127.0.0.1:50000", "tcp")
+
+_REPO = Path(__file__).resolve().parents[3]
+_VECTORS = json.loads((_REPO / "contracts/cultnet/interop/error-vectors.json").read_text(encoding="utf-8"))["vectors"]
+
+NOTE = define_database_entry_type(
+    "tests.authority_note",
+    [("schema_version", 0), ("text", 1)],
+    schema_id=SCHEMA_ID,
+    schema_name="tests.authority_note",
+    schema_version="tests.authority_note.v1",
+)
+
+
+class Recording:
+    def __init__(self, decide: Any) -> None:
+        self._decide = decide
+        self.requests: list[CultMeshRemoteWriteRequest] = []
+
+    def decide(self, request: CultMeshRemoteWriteRequest) -> Any:
+        self.requests.append(request)
+        return self._decide(request)
+
+
+def put_of(key: str, text: str, *, schema_id: str = SCHEMA_ID) -> dict[str, Any]:
+    return document_put_raw(
+        message_id="wire",
+        key=key,
+        schema_id=schema_id,
+        stored_at="2026-11-07T00:00:00Z",
+        payload=NOTE.encode_payload({"schema_version": "tests.authority_note.v1", "text": text}),
+        shard_id=SHARD_ID,
+        shard_epoch=1,
+    ).to_wire()
+
+
+def delete_of(key: str, *, schema_id: str = SCHEMA_ID) -> dict[str, Any]:
+    return document_delete(
+        message_id="wire-delete", schema_id=schema_id, record_key=key, shard_id=SHARD_ID, shard_epoch=1
+    ).to_wire()
+
+
+class RemoteWriteAuthorityTests(unittest.TestCase):
+    def build(self, authority: Any = None) -> CultMeshLocalServer:
+        node = create_node(runtime_id="authority-server")
+        node.database.register_document(NOTE)
+        return CultMeshLocalServer(node=node, port=0, write_authority=authority)
+
+    def text_of(self, server: CultMeshLocalServer, key: str) -> str | None:
+        value = server.node.cache.get(NOTE, key)
+        return None if value is None else value["text"]
+
+    def send(self, server: CultMeshLocalServer, message: dict[str, Any]) -> list[dict[str, Any]]:
+        subscriptions: dict[str, Any] = {}
+        return server._handle_connection_message(message, subscriptions, peer=PEER)
+
+    def assert_refused(self, replies: list[dict[str, Any]], key: str, *, error: str | None = None) -> None:
+        self.assertEqual(len(replies), 1)
+        reply = replies[0]
+        self.assertEqual(reply["schemaVersion"], "cultnet.error.v0")
+        self.assertEqual(reply["code"], "write_not_authorized")
+        self.assertTrue(reply["error"].startswith("write_not_authorized"))
+        self.assertEqual(reply["details"]["field"], "recordKey")
+        self.assertEqual(reply["details"]["value"], key)
+        if error is not None:
+            self.assertEqual(reply["error"], error)
+
+    def seed(self, server: CultMeshLocalServer, key: str, text: str) -> None:
+        # The host writes its own record through its own door, which asks no remote authority.
+        self.assertEqual(server.node.database.apply_raw_put_message(put_of(key, text)).change_kind, "added")
+
+    def test_with_no_authority_a_peers_put_and_delete_are_refused_and_change_nothing(self) -> None:
+        server = self.build(None)
+        self.seed(server, KEY_A, "server")
+
+        with self.assertLogs("cultmesh_py.server", level="WARNING") as logs:
+            self.assert_refused(self.send(server, put_of(KEY_A, "peer")), KEY_A)
+            self.assert_refused(self.send(server, delete_of(KEY_A)), KEY_A)
+            self.assert_refused(self.send(server, put_of(KEY_B, "peer")), KEY_B)
+
+        self.assertEqual(self.text_of(server, KEY_A), "server")
+        self.assertIsNone(self.text_of(server, KEY_B))
+        self.assertEqual(sum("write not authorized" in line for line in logs.output), 3)
+
+    def test_a_refusal_publishes_no_change_to_a_subscriber(self) -> None:
+        server = self.build(None)
+        server.start()
+        try:
+            client = CultMesh.create_client("127.0.0.1", server.port, timeout_seconds=2.0)
+            with client.subscribe_database(subscription_id="s", schema_ids=[SCHEMA_ID], include_snapshot=False) as sub:
+                with self.assertRaises(CultNetPeerError) as raised:
+                    sub.send(put_of(KEY_A, "peer"))
+                    sub.read_next()
+        finally:
+            server.stop()
+        self.assertEqual(raised.exception.response["code"], "write_not_authorized")
+        self.assertIsNone(self.text_of(server, KEY_A))
+
+    def test_a_granted_put_and_delete_commit_and_the_authority_saw_this_peer(self) -> None:
+        authority = Recording(lambda _: CultMeshRemoteWriteDecision.grant())
+        server = self.build(authority)
+
+        put_replies = self.send(server, put_of(KEY_A, "peer"))
+        self.assertEqual(self.text_of(server, KEY_A), "peer")
+        self.assertEqual(put_replies, [])
+        self.send(server, delete_of(KEY_A))
+        self.assertIsNone(self.text_of(server, KEY_A))
+
+        self.assertEqual(len(authority.requests), 2)
+        self.assertTrue(all(request.peer is PEER for request in authority.requests))
+
+    def test_the_request_carries_the_resolved_write_and_scoped_grants_refuse_their_neighbours(self) -> None:
+        authority = Recording(
+            lambda request: CultMeshRemoteWriteDecision.grant()
+            if request.operation is CultMeshRemoteWriteOperation.PUT and request.record_key == KEY_A
+            else CultMeshRemoteWriteDecision.refuse("scoped")
+        )
+        server = self.build(authority)
+        self.seed(server, KEY_A, "server")
+
+        self.send(server, put_of(KEY_A, "aliased", schema_id=ALIAS))
+
+        request = authority.requests[0]
+        self.assertEqual(request.schema_id, SCHEMA_ID, "the authority sees the canonical id, not the alias as sent")
+        self.assertIs(request.operation, CultMeshRemoteWriteOperation.PUT)
+        self.assertEqual(request.record_key, KEY_A)
+        self.assertEqual(request.shard_id, SHARD_ID)
+        self.assertEqual(request.shard_epoch, 1)
+        self.assertEqual(self.text_of(server, KEY_A), "aliased")
+
+        self.assert_refused(self.send(server, put_of(KEY_B, "other-key")), KEY_B)
+        self.assert_refused(self.send(server, delete_of(KEY_A)), KEY_A)
+        self.assertIsNone(self.text_of(server, KEY_B), "a grant scoped to key a refuses key b")
+        self.assertEqual(self.text_of(server, KEY_A), "aliased", "a grant scoped to put refuses delete")
+        self.assertIs(authority.requests[-1].operation, CultMeshRemoteWriteOperation.DELETE)
+        self.assertEqual(authority.requests[-1].schema_id, SCHEMA_ID)
+
+    def test_refusal_precedes_every_other_judgment_of_the_put(self) -> None:
+        refusing = self.build(None)
+        unowned = put_of("unrelated:authority", "x", schema_id="sha256:nobody-owns-this")
+        unowned["document"]["payload"] = msgpack.packb(["nobody.owns.this.v1", "x"], use_bin_type=True)
+        self.assert_refused(self.send(refusing, unowned), "unrelated:authority")
+        blank_key = put_of("", "x")
+        self.assert_refused(self.send(refusing, blank_key), "")
+
+        granting = self.build(Recording(lambda _: CultMeshRemoteWriteDecision.grant()))
+        reply = self.send(granting, unowned)
+        self.assertEqual(reply[0]["code"], "unregistered_document_put", "a granted put still meets the store's refusal")
+
+    def test_an_authority_that_raises_refuses_and_is_logged_as_an_error(self) -> None:
+        def explode(_: Any) -> Any:
+            raise RuntimeError("authority exploded")
+
+        server = self.build(Recording(explode))
+        self.seed(server, KEY_A, "server")
+
+        with self.assertLogs("cultmesh_py.server", level="ERROR") as logs:
+            self.assert_refused(self.send(server, put_of(KEY_A, "peer")), KEY_A)
+            self.assert_refused(self.send(server, delete_of(KEY_A)), KEY_A)
+
+        self.assertEqual(self.text_of(server, KEY_A), "server", "fail closed")
+        self.assertTrue(any("RuntimeError" in line for line in logs.output))
+
+    def test_a_refusal_with_no_reason_still_says_why(self) -> None:
+        server = self.build(Recording(lambda _: CultMeshRemoteWriteDecision.refuse()))
+        self.assert_refused(self.send(server, put_of(KEY_A, "peer")), KEY_A, error="write_not_authorized")
+
+    def test_the_refusal_names_the_key_and_the_code_in_the_pinned_bytes(self) -> None:
+        vector = next(v for v in _VECTORS if v["name"] == "write_not_authorized")
+        message = error_message(
+            "write_not_authorized: not granted",
+            code="write_not_authorized",
+            details={"field": "recordKey", "value": "some:key"},
+        )
+        self.assertEqual(message.to_bytes(), bytes.fromhex(vector["messagePackHex"]))
+
+        server = self.build(Recording(lambda _: CultMeshRemoteWriteDecision.refuse("not granted")))
+        reply = self.send(server, put_of("some:key", "peer"))[0]
+        self.assertEqual(msgpack.packb(reply, use_bin_type=True), bytes.fromhex(vector["messagePackHex"]))
+
+    def test_the_peer_receives_the_typed_refusal_over_tcp_and_a_grant_sends_nothing_back(self) -> None:
+        authority = Recording(
+            lambda request: CultMeshRemoteWriteDecision.grant()
+            if request.record_key == KEY_A
+            else CultMeshRemoteWriteDecision.refuse("only a")
+        )
+        server = self.build(authority)
+        server.start()
+        try:
+            client = CultMesh.create_client("127.0.0.1", server.port, timeout_seconds=2.0)
+            with client.subscribe_database(subscription_id="s", schema_ids=[SCHEMA_ID], include_snapshot=False) as sub:
+                sub.send(put_of(KEY_A, "peer"))
+                self.assertEqual(sub.read_next_change().record_key, KEY_A, "the granted write was answered by its change, not an error")
+                sub.send(put_of(KEY_B, "peer"))
+                with self.assertRaises(CultNetPeerError) as raised:
+                    sub.read_next()
+        finally:
+            server.stop()
+
+        reply = raised.exception.response
+        self.assertEqual(reply["error"], "write_not_authorized: only a")
+        self.assertEqual(reply["details"]["value"], KEY_B)
+        self.assertTrue(authority.requests[0].peer.endpoint.startswith("127.0.0.1:"))
+        self.assertEqual(authority.requests[0].peer.transport, "tcp")
+        self.assertEqual(self.text_of(server, KEY_A), "peer")
+        self.assertIsNone(self.text_of(server, KEY_B))
+
+    def test_a_delete_sent_under_a_schema_alias_asks_the_authority_with_the_canonical_id(self) -> None:
+        authority = Recording(lambda _: CultMeshRemoteWriteDecision.grant())
+        server = self.build(authority)
+        self.seed(server, KEY_A, "server")
+
+        self.send(server, delete_of(KEY_A, schema_id="tests.authority_note.v1"))
+
+        request = authority.requests[0]
+        self.assertIs(request.operation, CultMeshRemoteWriteOperation.DELETE)
+        self.assertEqual(request.schema_id, SCHEMA_ID)
+        self.assertIsNone(self.text_of(server, KEY_A), "the aliased delete was granted and applied")
+
+    def test_a_missing_decision_refuses_put_and_delete(self) -> None:
+        server = self.build(Recording(lambda _: None))
+        self.seed(server, KEY_A, "server")
+
+        self.assert_refused(self.send(server, put_of(KEY_A, "peer")), KEY_A)
+        self.assert_refused(self.send(server, delete_of(KEY_A)), KEY_A)
+        self.assert_refused(self.send(server, put_of(KEY_B, "peer")), KEY_B)
+
+        self.assertEqual(self.text_of(server, KEY_A), "server")
+        self.assertIsNone(self.text_of(server, KEY_B))
+
+    def test_a_peer_over_rudp_is_refused_with_its_rudp_endpoint_and_the_server_serves_on(self) -> None:
+        authority = Recording(lambda _: CultMeshRemoteWriteDecision.refuse("rudp no"))
+        server = self.build(authority)
+        server.start()
+        try:
+            transport = create_rudp_schema_transport(
+                host="127.0.0.1", port=server.port, connection_id=server.rudp_connection_id, timeout_seconds=4.0
+            )
+            try:
+                transport.send("schema", msgpack.packb(put_of(KEY_A, "peer"), use_bin_type=True))
+                reply = msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+                transport.send("schema", msgpack.packb(delete_of(KEY_A), use_bin_type=True))
+                delete_reply = msgpack.unpackb(transport.receive(timeout_seconds=4.0).payload, raw=False)
+            finally:
+                transport.close()
+        finally:
+            server.stop()
+        self.assertEqual(reply["error"], "write_not_authorized: rudp no")
+        self.assertEqual(delete_reply["code"], "write_not_authorized")
+        self.assertEqual([r.peer.transport for r in authority.requests], ["rudp", "rudp"])
+        self.assertTrue(all(r.peer.endpoint.startswith("127.0.0.1:") for r in authority.requests))
+        self.assertIsNone(self.text_of(server, KEY_A))
+
+    def test_a_put_with_an_absurd_payload_is_refused_by_the_gate_not_crashed_on(self) -> None:
+        server = self.build(None)
+        absurd = put_of(KEY_A, "x")
+        absurd["document"]["payload"] = 2**70
+        self.assert_refused(self.send(server, absurd), KEY_A)
+
+    def test_an_ungranted_peers_huge_payload_is_refused_without_allocating_it(self) -> None:
+        import tracemalloc
+
+        server = self.build(None)
+        huge = put_of(KEY_A, "x")
+        huge["document"]["payload"] = 10**9  # bytes(10**9) would allocate a gigabyte
+        tracemalloc.start()
+        try:
+            replies = self.send(server, huge)
+            _, peak = tracemalloc.get_traced_memory()
+        finally:
+            tracemalloc.stop()
+        self.assert_refused(replies, KEY_A)
+        self.assertLess(peak, 10_000_000)
+
+    def test_wrong_typed_shard_fields_are_refused_before_the_gate_and_write_nothing(self) -> None:
+        authority = Recording(lambda _: CultMeshRemoteWriteDecision.grant())
+        server = self.build(authority)
+        self.seed(server, KEY_B, "server")
+        shards_before = server.node.database.shard_ids()
+        for field, value in (("shardId", {"not": "a string"}), ("shardId", 5), ("shardEpoch", "7"), ("shardEpoch", True), ("shardEpoch", 1.5)):
+            for operation in ("put", "delete"):
+                with self.subTest(field=field, value=value, operation=operation):
+                    message = put_of(KEY_A, "x") if operation == "put" else delete_of(KEY_B)
+                    message[field] = value
+                    replies = self.send(server, message)
+                    self.assertEqual([(reply["code"], reply["details"]["field"]) for reply in replies], [("message_invalid", field)])
+        self.assertEqual(authority.requests, [], "the authority was never asked")
+        self.assertIsNone(self.text_of(server, KEY_A), "nothing was written")
+        self.assertEqual(self.text_of(server, KEY_B), "server", "nothing was deleted")
+        self.assertEqual(server.node.database.shard_ids(), shards_before, "no shard or log entry was filed")
+
+    def test_well_typed_shard_fields_reach_the_authority_as_sent(self) -> None:
+        authority = Recording(lambda _: CultMeshRemoteWriteDecision.grant())
+        server = self.build(authority)
+        self.send(server, put_of(KEY_A, "x"))
+        self.assertEqual((authority.requests[0].shard_id, authority.requests[0].shard_epoch), (SHARD_ID, 1))
+
+    def test_grant_all_is_an_explicit_choice_that_grants_every_write(self) -> None:
+        server = self.build(CultMeshGrantAllWrites())
+        self.send(server, put_of(KEY_A, "peer"))
+        self.assertEqual(self.text_of(server, KEY_A), "peer")
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultmesh-py/tests/test_rudp_server_generation.py

@@ -10,7 +10,7 @@ from dataclasses import dataclass
 
 import msgpack
 from cultcache_py import define_database_entry_type
-from cultmesh_py import create_node
+from cultmesh_py import CultMeshGrantAllWrites, create_node
 from cultmesh_py.server import CultMeshLocalServer
 from cultnet_py import (
     CultNetRudpSendOptions,
@@ -49,7 +49,7 @@ class RudpServerGenerationTests(unittest.TestCase):
         node = create_node(runtime_id="rudp-generation")
         node.database.register_document(NOTE)
         # Replies stay whole datagrams here, so each server packet the pump reads is one message.
-        self.server = CultMeshLocalServer(node=node, rudp_connection_id=CONNECTION_ID, rudp_max_fragment_bytes=60_000)
+        self.server = CultMeshLocalServer(node=node, rudp_connection_id=CONNECTION_ID, rudp_max_fragment_bytes=60_000, write_authority=CultMeshGrantAllWrites())
         self.server.start()
         self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
         self.sock.bind(("127.0.0.1", 0))

packages/cultmesh-py/tests/test_server_bind.py

@@ -0,0 +1,69 @@
+"""A server asked for any port finds a TCP+UDP pair; one asked for a port gets that port or an honest failure."""
+
+from __future__ import annotations
+
+import errno
+import socket
+import threading
+import unittest
+from unittest.mock import patch
+
+from cultmesh_py import create_node
+from cultmesh_py.server import CultMeshLocalServer
+
+
+def server(**kwargs) -> CultMeshLocalServer:
+    return CultMeshLocalServer(node=create_node(runtime_id="bind-test"), host="127.0.0.1", **kwargs)
+
+
+class ServerBindTests(unittest.TestCase):
+    def test_port_zero_retries_with_a_fresh_port_when_another_process_holds_the_udp_number(self) -> None:
+        real_bind = socket.socket.bind
+        refused: list[int] = []
+
+        def bind(sock: socket.socket, address) -> None:
+            # The first two UDP binds find the number taken, as a UDP listener of another process would.
+            if sock.type == socket.SOCK_DGRAM and len(refused) < 2:
+                refused.append(address[1])
+                raise OSError(errno.EADDRINUSE, "Address already in use")
+            real_bind(sock, address)
+
+        with patch.object(socket.socket, "bind", bind):
+            started = server().start()
+        try:
+            self.assertEqual(len(refused), 2)
+            self.assertNotIn(started.port, refused[:1], "the retry used a fresh TCP port")
+            probe = socket.create_connection(("127.0.0.1", started.port), timeout=2.0)
+            probe.close()
+        finally:
+            started.stop()
+
+    def test_an_explicit_port_whose_udp_number_is_taken_fails_and_leaves_nothing_running(self) -> None:
+        holder = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        holder.bind(("127.0.0.1", 0))
+        port = holder.getsockname()[1]
+        free = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            free.bind(("127.0.0.1", port))  # the TCP number is free: only the UDP one is taken
+        finally:
+            free.close()
+        threads_before = threading.active_count()
+        try:
+            failing = server(port=port)
+            with self.assertRaises(OSError) as raised:
+                failing.start()
+            self.assertEqual(raised.exception.errno, errno.EADDRINUSE)
+            self.assertIsNone(failing._socket)
+            self.assertEqual(threading.active_count(), threads_before, "no accept thread was left running")
+            # The TCP number was released, not left listening.
+            free = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            try:
+                free.bind(("127.0.0.1", port))
+            finally:
+                free.close()
+        finally:
+            holder.close()
+
+
+if __name__ == "__main__":
+    unittest.main()