cultcache-rs: #[cultcache(index)] is unique at commit and load; re-registration re-judges held records (#95)

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

.github/workflows/cultmesh-portability.yml

@@ -8,6 +8,12 @@ on:
   pull_request:
   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
@@ -92,8 +98,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

.github/workflows/quic-native.yml

@@ -18,6 +18,12 @@ on:
   pull_request:
   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
 

contracts/cultnet/cultnet-distributed-database.md

@@ -140,6 +140,12 @@ A malformed put or delete is `message_invalid`, not a per-operation code: the pe
 - 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.
 - 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

@@ -12,7 +12,9 @@
     "changeKind": { "enum": ["added", "updated", "removed"] },
     "document": { "$ref": "./cultnet.raw-document-record.schema.json" },
     "recordKey": { "type": "string", "minLength": 1 },
-    "schemaId": { "type": "string", "minLength": 1 }
+    "schemaId": { "type": "string", "minLength": 1 },
+    "commitId": { "type": ["string", "null"], "minLength": 1 },
+    "commitCount": { "type": ["integer", "null"], "minimum": 2 }
   },
   "allOf": [
     {

contracts/cultnet/governance/fork-card.md

@@ -0,0 +1,197 @@
+# 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, deciders[], 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`, `deciders`, `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 list holds one to 64 ids** (Huginn's bound), on the card and in the per-call list alike (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. 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.
+
+### 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 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. `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, 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, 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. **Bifrost applies visibility at the door; Huginn returns the whole record to the door.** 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 | none | `deciders` (outside the Mind), `ruled_from`, `options_hash` |
+| 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.
+- 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.
+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`.

contracts/cultnet/governance/fork-card.schema.json

@@ -0,0 +1,987 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/governance/fork-card.schema.json",
+  "title": "CultNet fork-desk contract v0",
+  "description": "A fork card, the answer request a decider sends, the stored desk_answer with its tagged outcome, the result and door refusals returned to the sender, the record a fork keeps, and the ruling citation. Map-mode: every key is written, nil where absent. A request never carries answerer or authority: Huginn stamps both. Rule source: /opt/commons/handoff/fork-desk-answer-binding-20261110.md. Spec: fork-card.md. Vectors: fork-card-vectors.json.",
+  "$defs": {
+    "hex64": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "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$"
+    },
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "answerId": {
+      "type": "string",
+      "pattern": "^n[1-9][0-9]*$"
+    },
+    "option": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "text"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "id"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "minLength": 1
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "card": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "fork_id",
+        "title",
+        "context",
+        "options",
+        "recommendation",
+        "depends",
+        "leans",
+        "flag",
+        "raised_in",
+        "deciders",
+        "status",
+        "ruling",
+        "ruled_from",
+        "order",
+        "options_hash"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.card.v0"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "context": {
+          "type": "string"
+        },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "$ref": "#/$defs/option"
+          }
+        },
+        "recommendation": {
+          "type": "string",
+          "minLength": 1
+        },
+        "depends": {
+          "type": "array",
+          "maxItems": 8,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "leans": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "flag": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "raised_in": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/ref"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "deciders": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "maxItems": 64
+        },
+        "status": {
+          "enum": [
+            "open",
+            "closed"
+          ]
+        },
+        "ruling": {
+          "oneOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "ruled_from": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/answerId"
+          }
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        }
+      }
+    },
+    "words": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000,
+      "pattern": "^(?![\\t-\\r \\u0085   - 

  　]+$)[\\s\\S]+$",
+      "description": "At most 4000 UTF-8 bytes, which a schema cannot say: maxLength here counts code points and is only the looser bound (a code point is at least one byte). The byte limit is a rule both suites enforce (fork-card.md, answer_request)."
+    },
+    "answerObject": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "choice",
+            "note"
+          ],
+          "properties": {
+            "choice": {
+              "$ref": "#/$defs/id"
+            },
+            "note": {
+              "$ref": "#/$defs/words"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "choice",
+            "note"
+          ],
+          "properties": {
+            "choice": {
+              "$ref": "#/$defs/id"
+            },
+            "note": {
+              "type": "null"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "choice",
+            "note"
+          ],
+          "properties": {
+            "choice": {
+              "type": "null"
+            },
+            "note": {
+              "$ref": "#/$defs/words"
+            }
+          }
+        }
+      ]
+    },
+    "answerRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "fork_id",
+        "options_hash",
+        "answer",
+        "retracted",
+        "retracts",
+        "answered_at",
+        "request_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.answer_request.v0"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "answer": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerObject"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "retracted": {
+          "type": "boolean"
+        },
+        "retracts": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerId"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "answered_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        }
+      }
+    },
+    "deskAnswerCounted": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "answer_id",
+        "fork_id",
+        "outcome",
+        "of",
+        "retracts",
+        "code",
+        "options_hash",
+        "choice",
+        "note",
+        "answered_at",
+        "received_at",
+        "claim_in_future",
+        "answerer",
+        "authority",
+        "request_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.desk_answer.v0"
+        },
+        "answer_id": {
+          "$ref": "#/$defs/answerId"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "outcome": {
+          "const": "Counted"
+        },
+        "of": {
+          "type": "null"
+        },
+        "retracts": {
+          "type": "null"
+        },
+        "code": {
+          "type": "null"
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "choice": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/id"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "note": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/words"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "answered_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "received_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "claim_in_future": {
+          "type": "boolean"
+        },
+        "answerer": {
+          "$ref": "#/$defs/id"
+        },
+        "authority": {
+          "$ref": "#/$defs/id"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        }
+      }
+    },
+    "deskAnswerRevision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "answer_id",
+        "fork_id",
+        "outcome",
+        "of",
+        "retracts",
+        "code",
+        "options_hash",
+        "choice",
+        "note",
+        "answered_at",
+        "received_at",
+        "claim_in_future",
+        "answerer",
+        "authority",
+        "request_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.desk_answer.v0"
+        },
+        "answer_id": {
+          "$ref": "#/$defs/answerId"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "outcome": {
+          "const": "Revision"
+        },
+        "of": {
+          "$ref": "#/$defs/answerId"
+        },
+        "retracts": {
+          "type": "null"
+        },
+        "code": {
+          "type": "null"
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "choice": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/id"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "note": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/words"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "answered_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "received_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "claim_in_future": {
+          "type": "boolean"
+        },
+        "answerer": {
+          "$ref": "#/$defs/id"
+        },
+        "authority": {
+          "$ref": "#/$defs/id"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        }
+      }
+    },
+    "deskAnswerRetraction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "answer_id",
+        "fork_id",
+        "outcome",
+        "of",
+        "retracts",
+        "code",
+        "options_hash",
+        "choice",
+        "note",
+        "answered_at",
+        "received_at",
+        "claim_in_future",
+        "answerer",
+        "authority",
+        "request_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.desk_answer.v0"
+        },
+        "answer_id": {
+          "$ref": "#/$defs/answerId"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "outcome": {
+          "const": "Retraction"
+        },
+        "of": {
+          "type": "null"
+        },
+        "retracts": {
+          "$ref": "#/$defs/answerId"
+        },
+        "code": {
+          "type": "null"
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "choice": {
+          "type": "null"
+        },
+        "note": {
+          "type": "null"
+        },
+        "answered_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "received_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "claim_in_future": {
+          "type": "boolean"
+        },
+        "answerer": {
+          "$ref": "#/$defs/id"
+        },
+        "authority": {
+          "$ref": "#/$defs/id"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        }
+      }
+    },
+    "deskAnswerRefused": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "answer_id",
+        "fork_id",
+        "outcome",
+        "of",
+        "retracts",
+        "code",
+        "options_hash",
+        "choice",
+        "note",
+        "answered_at",
+        "received_at",
+        "claim_in_future",
+        "answerer",
+        "authority",
+        "request_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.desk_answer.v0"
+        },
+        "answer_id": {
+          "$ref": "#/$defs/answerId"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "outcome": {
+          "const": "Refused"
+        },
+        "of": {
+          "type": "null"
+        },
+        "retracts": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerId"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "code": {
+          "enum": [
+            "stale_fork",
+            "not_a_decider",
+            "fork_closed",
+            "choice_invalid",
+            "bad_retraction",
+            "already_retracted"
+          ]
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "choice": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/id"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "note": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/words"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "answered_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "received_at": {
+          "$ref": "#/$defs/instant"
+        },
+        "claim_in_future": {
+          "type": "boolean"
+        },
+        "answerer": {
+          "$ref": "#/$defs/id"
+        },
+        "authority": {
+          "$ref": "#/$defs/id"
+        },
+        "request_id": {
+          "$ref": "#/$defs/requestId"
+        }
+      }
+    },
+    "deskAnswer": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/deskAnswerCounted"
+        },
+        {
+          "$ref": "#/$defs/deskAnswerRevision"
+        },
+        {
+          "$ref": "#/$defs/deskAnswerRetraction"
+        },
+        {
+          "$ref": "#/$defs/deskAnswerRefused"
+        }
+      ]
+    },
+    "answerResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "answer",
+        "card",
+        "counted_answer_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.answer_result.v0"
+        },
+        "answer": {
+          "$ref": "#/$defs/deskAnswer"
+        },
+        "card": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/card"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "counted_answer_id": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerId"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "refusal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "code",
+        "error"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.refusal.v0"
+        },
+        "code": {
+          "enum": [
+            "unauthenticated",
+            "body_forbidden_field",
+            "body_unknown_field",
+            "body_invalid",
+            "fork_unknown",
+            "fork_too_large",
+            "insufficient_scope",
+            "forbidden",
+            "request_invalid",
+            "request_id_conflict"
+          ]
+        },
+        "error": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "fork_id",
+        "options_hash",
+        "counted_answer_id",
+        "answers"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.record.v0"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        },
+        "options_hash": {
+          "$ref": "#/$defs/hex64"
+        },
+        "counted_answer_id": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerId"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "answers": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/deskAnswer"
+          }
+        }
+      }
+    },
+    "rulingCite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "ruling_id",
+        "authority",
+        "answer_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.ruling_cite.v0"
+        },
+        "ruling_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "authority": {
+          "type": "string",
+          "minLength": 1
+        },
+        "answer_id": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/answerId"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "cursor": {
+      "type": "string",
+      "pattern": "^c[1-9][0-9]*$",
+      "description": "Opaque to a client. c<N> means: the cards whose order is below N."
+    },
+    "stamp": {
+      "type": "string",
+      "pattern": "^s[0-9]+$",
+      "description": "s<N>, N the receiver's last-seen Huginn admission ordinal for the Mind's desk documents. Two lists with the same stamp are the same state."
+    },
+    "listRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "mind",
+        "status",
+        "cursor",
+        "limit"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.list_request.v0"
+        },
+        "mind": {
+          "$ref": "#/$defs/id"
+        },
+        "status": {
+          "oneOf": [
+            {
+              "enum": [
+                "open",
+                "recorded"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "cursor": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/cursor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 50
+        }
+      }
+    },
+    "readRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "mind",
+        "fork_id"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.read_request.v0"
+        },
+        "mind": {
+          "$ref": "#/$defs/id"
+        },
+        "fork_id": {
+          "$ref": "#/$defs/id"
+        }
+      }
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "card",
+        "record"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.entry.v0"
+        },
+        "card": {
+          "$ref": "#/$defs/card"
+        },
+        "record": {
+          "$ref": "#/$defs/record"
+        }
+      }
+    },
+    "list": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "mind",
+        "stamp",
+        "open_count",
+        "recorded_count",
+        "forks",
+        "next_cursor"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.list.v0"
+        },
+        "mind": {
+          "$ref": "#/$defs/id"
+        },
+        "stamp": {
+          "$ref": "#/$defs/stamp"
+        },
+        "open_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "recorded_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "forks": {
+          "type": "array",
+          "maxItems": 50,
+          "items": {
+            "$ref": "#/$defs/entry"
+          }
+        },
+        "next_cursor": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/cursor"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "unavailable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "code",
+        "error",
+        "retryAfterSeconds"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "gamecult.fork.unavailable.v0"
+        },
+        "code": {
+          "const": "unavailable"
+        },
+        "error": {
+          "type": "string",
+          "minLength": 1
+        },
+        "retryAfterSeconds": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "description": "The outcome is NOT CONFIRMED: the request may have reached Huginn and been stored before the reply was lost. Retry with the same request_id to learn the outcome."
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+      "description": "Set by the client, a lowercase D-format UUID. Bound to the stamped answerer by the first stored answer that carries it."
+    }
+  }
+}

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"
+            }
+          ]
+        }
+      }
+    }
+  }
+}

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
 

packages/cultcache-py/CHANGELOG.md

@@ -9,6 +9,8 @@
 
 ### Breaking
 
+- `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 record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
 - A write over a file the reader refuses (`StoreUnreadableError`, from `push`, `push_all` and `delete`) refuses and leaves the file as it is. A flush used to replace such a file. A write set cannot merge with a disk it cannot read, so the file is repaired or removed by its owner before the store writes again.
 - Added `StoreUnreadableError` (a `ValueError`) for a store file this runtime cannot read, and `SchemaConflictError` (a `ValueError`) for a

packages/cultcache-py/README.md

@@ -73,7 +73,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()`
@@ -95,6 +95,33 @@ store.
 - `delete_global(...)`
 - `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.

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

@@ -1,9 +1,11 @@
 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
@@ -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)
@@ -432,12 +480,20 @@ class CultCache:
         """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())
         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
         ]
+        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:
@@ -552,9 +608,9 @@ 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(
@@ -571,17 +627,52 @@ class CultCache:
             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
+                lookup_keys.setdefault(type, {})[key] = self._lookup_keys_for(value, name_extractor, type_index_extractors)
+        # Judged whole, 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(
+            [(type, key, keys) for type, by_key in lookup_keys.items() for key, keys in by_key.items()], {}, ()
+        )
+        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), in the order of C# RefuseIndexSharing: within one type and one
+        unique alias, no two records hold one non-blank value, judged on the result. The holders of a value are the landing
+        keys projecting it (in landing order) plus the held key unless this admission replaces it; two distinct holders
+        refuse, naming the two smallest keys (UTF-16 code-unit order) and the alias, never the value. Aliases are judged in
+        UTF-16 order, values in the order they landed."""
+        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)
+        for (type, index, index_value), keys in sorted(landed.items(), key=lambda item: _utf16_order(item[0][1])):
+            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(dict.fromkeys(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
+                raise CultCacheError(
+                    f"Records {distinct[0]} and {distinct[1]} ({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 +687,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

@@ -157,6 +157,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
@@ -190,6 +195,14 @@ class DocumentDefinition(Generic[T]):
             self.validate(value)
         return value
 
+    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:
             return self._catalog_entry
@@ -241,6 +254,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 +273,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 +295,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 +312,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 +339,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,

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)

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_unique_index.py

@@ -0,0 +1,575 @@
+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)
+
+
+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_values_are_named_in_landing_order(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        rows = [("item:a", "B"), ("item:b", "B"), ("item:x", "A"), ("item:y", "A")]
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put_envelopes(document, [envelope(document, key, Item(sku=sku)) for key, sku in rows])
+        self.assertEqual(str(caught.exception), refusal("item:a", "item:b", "item", "sku"))
+
+    def test_keys_sort_by_utf16_code_unit_not_code_point(self) -> None:
+        document = item_doc()
+        cache = cache_of(document)
+        astral, bmp = "k\U0001F600", "k\uff01"  # code points: bmp < astral; UTF-16 units: D83D < FF01
+        with self.assertRaises(CultCacheError) as caught:
+            cache.put_envelopes(document, [envelope(document, bmp, Item(sku="S")), envelope(document, astral, Item(sku="S"))])
+        self.assertEqual(str(caught.exception), refusal(astral, bmp, "item", "sku"))
+
+    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"))
+
+
+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

@@ -10,10 +10,14 @@ only in git history.
 
 - A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.
 - A write over a file the reader refuses (a zero-byte file, a truncated store, a stamp this runtime does not read) refuses with `CultCacheStoreUnreadable` and leaves the file as it is. A whole-store write used to replace such a file. This reverses 0.3.1, where `push_all` replaced a file with no readable stamp (healing it); the stamp rule now has one owner, the reader every write asks under the lock, and it accepts v1 and v3 (0.3.1 refused v3).
+- `#[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.
 
 ### 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`).
+- 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

@@ -412,7 +412,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**

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
@@ -443,7 +436,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>,
 }
 
@@ -941,15 +935,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 +952,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/src/lib.rs

@@ -168,12 +168,14 @@ pub trait DatabaseEntry: Serialize + DeserializeOwned + Clone + Send + 'static {
     fn cult_name(&self) -> Option<String> {
         None
     }
-    /// Each `#[cultcache(index)]` member as (alias, value), which `get_by_index` finds the record by.
-    fn cult_indexes(&self) -> Vec<(&'static str, String)> {
-        Vec::new()
-    }
+    /// The `#[cultcache(index)]` members, the one declaration: each is an alias with the reader of its value. Each is
+    /// unique: within one type no two records hold one non-blank value of it, and `get_by_index` finds the record by it.
+    const UNIQUE_INDEXES: &'static [CultIndexMember<Self>] = &[];
 }
 
+/// An index alias and how to read its value from a record; `None` is no value.
+pub type CultIndexMember<T> = (&'static str, fn(&T) -> Option<String>);
+
 /// What a `#[cultcache(name)]` or `#[cultcache(index)]` member says it is called: its text, or `None` for a member
 /// that holds no value (an `Option` that is `None`). The cache treats an empty name and a blank index value as none.
 pub trait CultLookupValue {
@@ -192,6 +194,13 @@ impl<T: CultLookupValue> CultLookupValue for Option<T> {
     }
 }
 
+/// C# renders a boolean `True` or `False`; the index text is shared across runtimes.
+impl CultLookupValue for bool {
+    fn lookup_value(&self) -> Option<String> {
+        Some(if *self { "True" } else { "False" }.to_string())
+    }
+}
+
 macro_rules! lookup_value_by_display {
     ($($ty:ty),* $(,)?) => {$(
         impl CultLookupValue for $ty {
@@ -202,7 +211,7 @@ macro_rules! lookup_value_by_display {
     )*};
 }
 
-lookup_value_by_display!(bool, char, i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize);
+lookup_value_by_display!(char, i8, i16, i32, i64, i128, isize, u8, u16, u32, u64, u128, usize);
 
 /// A global type already holds a record under another key; a second would leave `get_global` with two answers.
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -2719,9 +2728,46 @@ pub struct CultCache {
     globals: BTreeSet<String>,
     schema_name_definitions: BTreeMap<String, String>,
     entries: BTreeMap<(String, String), CultCacheEnvelope>,
+    /// Derived from `entries` by the uniqueness judge: (type, alias, value) -> the one key holding that value. It
+    /// decides nothing; `get_by_index` reads it.
+    index_holders: IndexHolders,
+    /// Per registered type with `UNIQUE_INDEXES`: decodes a payload as that type and returns its non-blank index
+    /// values. Registration data, so the judge decodes only indexed types.
+    projectors: BTreeMap<String, IndexProjector>,
     stores: Vec<CultCacheStoreRegistration>,
 }
 
+type IndexProjector = fn(&[u8]) -> Result<Vec<(&'static str, String)>>;
+type IndexSlot = (String, String, String);
+type IndexHolders = BTreeMap<IndexSlot, String>;
+
+fn project_indexes<T: DatabaseEntry>(payload: &[u8]) -> Result<Vec<(&'static str, String)>> {
+    let document = decode_payload::<T>(payload)?;
+    Ok(T::UNIQUE_INDEXES
+        .iter()
+        .filter_map(|(alias, read)| read(&document).map(|value| (*alias, value)))
+        .filter(|(_, value)| !value.trim().is_empty())
+        .collect())
+}
+
+/// What an admission does to the holder map: slots it releases (still held by the key that held them) and slots it takes.
+#[derive(Default)]
+struct IndexChange {
+    released: Vec<(IndexSlot, String)>,
+    taken: Vec<(IndexSlot, String)>,
+}
+
+impl IndexChange {
+    fn apply(self, holders: &mut IndexHolders) {
+        for (slot, key) in self.released {
+            if holders.get(&slot) == Some(&key) {
+                holders.remove(&slot);
+            }
+        }
+        holders.extend(self.taken);
+    }
+}
+
 impl CultCache {
     pub fn new() -> Self {
         Self {
@@ -2729,6 +2775,8 @@ impl CultCache {
             globals: BTreeSet::new(),
             schema_name_definitions: BTreeMap::new(),
             entries: BTreeMap::new(),
+            index_holders: BTreeMap::new(),
+            projectors: BTreeMap::new(),
             stores: Vec::new(),
         }
     }
@@ -2756,12 +2804,40 @@ impl CultCache {
                 existing_type
             ));
         }
-        self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME);
+        // The declaration decides what the held records hold (index projector, global flag), so a changed declaration
+        // re-judges them; a held violation (or a record the new type cannot decode) refuses the registration and
+        // changes nothing.
+        let previous = self.projectors.get(T::TYPE).copied();
+        let was_global = self.globals.contains(T::TYPE);
+        if T::UNIQUE_INDEXES.is_empty() {
+            self.projectors.remove(T::TYPE);
+        } else {
+            self.projectors.insert(T::TYPE.to_string(), project_indexes::<T>);
+        }
         if T::GLOBAL {
             self.globals.insert(T::TYPE.to_string());
         } else {
             self.globals.remove(T::TYPE);
         }
+        let held_type = self.entries.range((T::TYPE.to_string(), String::new())..).next().is_some_and(|((held, _), _)| held == T::TYPE);
+        if held_type {
+            match self.refuse_second_globals(&self.entries).and_then(|()| self.judge_image(&self.entries)) {
+                Ok(holders) => self.index_holders = holders,
+                Err(refusal) => {
+                    match previous {
+                        Some(project) => self.projectors.insert(T::TYPE.to_string(), project),
+                        None => self.projectors.remove(T::TYPE),
+                    };
+                    if was_global {
+                        self.globals.insert(T::TYPE.to_string());
+                    } else {
+                        self.globals.remove(T::TYPE);
+                    }
+                    return Err(refusal);
+                }
+            }
+        }
+        self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME);
         self.schema_name_definitions
             .insert(T::SCHEMA_NAME.to_string(), T::TYPE.to_string());
         Ok(())
@@ -2869,7 +2945,9 @@ impl CultCache {
             }
         }
         self.refuse_second_globals(&loaded)?;
+        let holders = self.judge_image(&loaded)?;
         self.entries = loaded;
+        self.index_holders = holders;
         Ok(())
     }
 
@@ -2973,20 +3051,18 @@ impl CultCache {
         self.find_record::<T>(|document| document.cult_name().as_deref() == Some(name))
     }
 
-    /// The record whose `#[cultcache(index)]` member `alias` holds `value`. A blank value is not indexed, so it finds
-    /// nothing. Records of one type sharing a value find the one with the smallest key (ordinal), whatever order they
-    /// were written or loaded in; removing it finds the next.
+    /// The record whose `#[cultcache(index)]` member `alias` holds `value`: at most one, since an index is unique. A
+    /// blank value is not indexed, so it finds nothing; neither does an alias `T` does not declare.
     pub fn get_by_index<T: DatabaseEntry>(&self, alias: &str, value: &str) -> Result<Option<T>> {
         self.require_entry_type::<T>()?;
-        if value.trim().is_empty() {
+        if value.trim().is_empty() || !T::UNIQUE_INDEXES.iter().any(|(declared, _)| *declared == alias) {
             return Ok(None);
         }
-        self.find_record::<T>(|document| {
-            document
-                .cult_indexes()
-                .iter()
-                .any(|(held_alias, held_value)| *held_alias == alias && held_value == value)
-        })
+        let slot = (T::TYPE.to_string(), alias.to_string(), value.to_string());
+        match self.index_holders.get(&slot) {
+            Some(key) => self.get::<T>(key),
+            None => Ok(None),
+        }
     }
 
     /// The first record of `T`, in key order, that `matches`.
@@ -3029,10 +3105,12 @@ impl CultCache {
     pub fn put<T: DatabaseEntry>(&mut self, key: impl Into<String>, value: &T) -> Result<T> {
         let (entry, parsed) = self.prepare_entry(key, value)?;
         self.refuse_second_global(&self.entries, &entry.r#type, &entry.key)?;
+        let change = self.judge_unique(&[&entry])?;
         if let Some(home) = self.home_index(T::TYPE)? {
             self.stores[home].store.push(&entry)?;
         }
         self.entries.insert(entry_id(&entry), entry);
+        change.apply(&mut self.index_holders);
         Ok(parsed)
     }
 
@@ -3141,6 +3219,7 @@ impl CultCache {
             next.insert(entry_id(entry), entry.clone());
         }
         self.refuse_second_globals(&next)?;
+        let change = self.judge_unique(&staged.iter().collect::<Vec<_>>())?;
         if let Some(store_index) = store_index {
             // The home store receives its own records only: those it already
             // holds in this cache plus the staged ones.
@@ -3154,16 +3233,19 @@ impl CultCache {
                 .push_all(&snapshot, PushAllOptions::default())?;
         }
         self.entries = next;
+        change.apply(&mut self.index_holders);
         Ok(())
     }
 
     pub fn put_envelope<T: DatabaseEntry>(&mut self, entry: CultCacheEnvelope) -> Result<T> {
         let parsed = self.validate_envelope::<T>(&entry)?;
         self.refuse_second_global(&self.entries, &entry.r#type, &entry.key)?;
+        let change = self.judge_unique(&[&entry])?;
         if let Some(home) = self.home_index(T::TYPE)? {
             self.stores[home].store.push(&entry)?;
         }
         self.entries.insert(entry_id(&entry), entry);
+        change.apply(&mut self.index_holders);
         Ok(parsed)
     }
 
@@ -3193,10 +3275,12 @@ impl CultCache {
         }
         require_payload_depth(&entry)?;
         self.refuse_second_global(&self.entries, &entry.r#type, &entry.key)?;
+        let change = self.judge_unique(&[&entry])?;
         if let Some(home) = self.home_index(&entry.r#type)? {
             self.stores[home].store.push(&entry)?;
         }
         self.entries.insert(entry_id(&entry), entry);
+        change.apply(&mut self.index_holders);
         Ok(())
     }
 
@@ -3247,10 +3331,12 @@ impl CultCache {
         let Some(entry) = self.entries.get(&id).cloned() else {
             return Ok(false);
         };
+        let released = self.projected_slots(&entry)?;
         if let Some(home) = self.home_index(T::TYPE)? {
             self.stores[home].store.delete(&entry)?;
         }
         self.entries.remove(&id);
+        IndexChange { released, taken: Vec::new() }.apply(&mut self.index_holders);
         Ok(true)
     }
 
@@ -3279,10 +3365,86 @@ impl CultCache {
             loaded.insert(entry_id(&entry), entry);
         }
         self.refuse_second_globals(&loaded)?;
+        let holders = self.judge_image(&loaded)?;
         self.entries = loaded;
+        self.index_holders = holders;
         Ok(())
     }
 
+    /// The slots an envelope holds: its type's non-blank index values, each held by its key.
+    fn projected_slots(&self, entry: &CultCacheEnvelope) -> Result<Vec<(IndexSlot, String)>> {
+        let Some(project) = self.projectors.get(&entry.r#type) else {
+            return Ok(Vec::new());
+        };
+        let held = project(&entry.payload).with_context(|| {
+            format!("failed to project the unique indexes of CultCache entry {:?} at key {:?}", entry.r#type, entry.key)
+        })?;
+        Ok(held
+            .into_iter()
+            .map(|(alias, value)| ((entry.r#type.clone(), alias.to_string(), value), entry.key.clone()))
+            .collect())
+    }
+
+    /// The one index rule (C# `RefuseIndexSharing`), judged on the result of an admission: within one type and one
+    /// unique alias, no two records hold one non-blank value. The holders of a value are the held key (unless this
+    /// admission rewrites it) plus every landing key projecting it; two distinct holders refuse, naming both keys
+    /// (ordinal) and the alias, never the value. A key landing twice lands as its last envelope.
+    fn judge_unique(&self, landing: &[&CultCacheEnvelope]) -> Result<IndexChange> {
+        self.judge_against(&self.index_holders, landing, true)
+    }
+
+    /// Judges a whole image against an empty holder map and returns the map it installs.
+    fn judge_image(&self, image: &BTreeMap<(String, String), CultCacheEnvelope>) -> Result<IndexHolders> {
+        let landing: Vec<_> = image.values().collect();
+        let mut holders = IndexHolders::new();
+        self.judge_against(&holders, &landing, false)?.apply(&mut holders);
+        Ok(holders)
+    }
+
+    fn judge_against(&self, held: &IndexHolders, landing: &[&CultCacheEnvelope], replacing: bool) -> Result<IndexChange> {
+        let mut last: BTreeMap<(&str, &str), &CultCacheEnvelope> = BTreeMap::new();
+        for entry in landing {
+            last.insert((entry.r#type.as_str(), entry.key.as_str()), entry);
+        }
+        let mut change = IndexChange::default();
+        let mut groups: Vec<(IndexSlot, BTreeSet<String>)> = Vec::new();
+        let mut at: BTreeMap<IndexSlot, usize> = BTreeMap::new();
+        for entry in last.values() {
+            if !self.projectors.contains_key(&entry.r#type) {
+                continue;
+            }
+            if replacing && let Some(old) = self.entries.get(&entry_id(entry)) {
+                change.released.extend(self.projected_slots(old)?);
+            }
+            for (slot, key) in self.projected_slots(entry)? {
+                let index = *at.entry(slot.clone()).or_insert_with(|| {
+                    groups.push((slot, BTreeSet::new()));
+                    groups.len() - 1
+                });
+                groups[index].1.insert(key);
+            }
+        }
+        groups.sort_by(|left, right| left.0.1.cmp(&right.0.1));
+        for (slot, mut holders) in groups {
+            if let Some(held_key) = held.get(&slot)
+                && !last.contains_key(&(slot.0.as_str(), held_key.as_str()))
+            {
+                holders.insert(held_key.clone());
+            }
+            let mut ordered = holders.iter();
+            if let (Some(first), Some(second)) = (ordered.next(), ordered.next()) {
+                return Err(anyhow!(
+                    "Records {first} and {second} ({}) both hold unique index '{}'; an index value names one record.",
+                    self.definitions.get(&slot.0).copied().unwrap_or(&slot.0),
+                    slot.1
+                ));
+            }
+            let key = holders.into_iter().next().expect("a group holds at least one key");
+            change.taken.push((slot, key));
+        }
+        Ok(change)
+    }
+
     fn refuse_second_global(
         &self,
         entries: &BTreeMap<(String, String), CultCacheEnvelope>,
@@ -6136,6 +6298,27 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn pulling_a_synthetic_pre_v1_envelope_array_leaves_the_file_bytes_identical() -> Result<()> {
+        // SYNTHETIC pre-v1 vector: no real file of this shape is known; the Rust envelope payload is binary.
+        let temp = tempfile::tempdir()?;
+        let path = temp.path().join("legacy.cc");
+        let legacy = rmp_serde::to_vec_named(&vec![CultCacheEnvelope {
+            key: "note:hello".to_string(),
+            r#type: "note".to_string(),
+            payload: vec![0x90],
+            stored_at: "2026-10-20T00:00:00Z".to_string(),
+            schema_id: None,
+        }])?;
+        fs::write(&path, &legacy)?;
+
+        let envelopes = SingleFileMessagePackBackingStore::new(&path).pull_all()?;
+
+        assert_eq!(envelopes.iter().map(|e| e.key.as_str()).collect::<Vec<_>>(), ["note:hello"]);
+        assert_eq!(fs::read(&path)?, legacy);
+        Ok(())
+    }
+
     #[test]
     fn a_newer_store_is_named_once_its_header_string_is_complete() -> Result<()> {
         let vector = fs::read(

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/unique_index.rs

@@ -0,0 +1,669 @@
+//! `#[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,
+}
+
+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("a", &Other { sku: "S".into() }).unwrap();
+    cache.put("b", &Other { sku: "T".into() }).unwrap();
+    assert!(cache.put("b", &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());
+}
+
+// The verdict and the named pair do not depend on key order, staging order, or alias declaration order.
+#[test]
+fn the_refusal_names_the_ordinal_pair_whatever_the_order() {
+    let orders: [[&str; 3]; 6] =
+        [["a", "b", "c"], ["a", "c", "b"], ["b", "a", "c"], ["b", "c", "a"], ["c", "a", "b"], ["c", "b", "a"]];
+    for order in orders {
+        let mut cache = memory_cache();
+        let rows: Vec<_> = order.iter().map(|key| (*key, unique("S"))).collect();
+        let text = error_text(cache.put_prepared_batch(staged(&cache, &rows)));
+        assert_eq!(text, refusal("a", "b", "tests.unique_item", "Sku"), "{order:?}");
+        assert!(skus(&cache).is_empty());
+    }
+    // Both aliases collide in one batch: the alias sorting first is named, though `B` is declared first.
+    for order in [["x", "y"], ["y", "x"]] {
+        let mut cache = memory_cache();
+        let rows: Vec<_> = order.iter().map(|key| (*key, multi(Some("s"), Some("t")))).collect();
+        let text = error_text(cache.put_prepared_batch(staged(&cache, &rows)));
+        assert_eq!(text, refusal("x", "y", "Multi", "A"));
+    }
+    // A held key and a landing key: the pair is ordinal, not held-first.
+    let mut cache = memory_cache();
+    cache.put("m", &unique("S")).unwrap();
+    assert_eq!(error_text(cache.put("z", &unique("S"))), refusal("m", "z", "tests.unique_item", "Sku"));
+    assert_eq!(error_text(cache.put("a", &unique("S"))), refusal("a", "m", "tests.unique_item", "Sku"));
+    // A value that differs only by case or by a surrounding space is another value.
+    cache.put("n", &unique("s")).unwrap();
+    cache.put("o", &unique("S ")).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");
+    }
+}
+
+// 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,6 +3,24 @@
 All notable changes to `@gamecult/cultcache-ts` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Breaking
+
+- `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.
+
+### 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.
@@ -41,8 +59,6 @@ All notable changes to `@gamecult/cultcache-ts` are recorded here, following
 - The Windows replace is a POSIX-semantics rename first (it lands while C# and Rust readers
   hold the store open), falling back to a write-through `MoveFileExW`, with 25 attempts 20 ms
   apart on errors 5, 32 and 33. Writers wait up to 30 s for the lock.
-- Opening a legacy store that needs healing rewrites it under the lock, from a read taken
-  under the lock.
 
 ### Dependencies
 

packages/cultcache-ts/README.md

@@ -93,12 +93,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 +126,7 @@ await cache.pullAllBackingStores();
 
 await cache.put(itemDocument, "item:potion", {
   name: "Potion",
+  sku: "POT-001",
   category: "Consumable",
   value: 50,
 });
@@ -132,7 +137,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 +199,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 +207,70 @@ 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.
+
+### 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
@@ -357,7 +415,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/src/cult-cache.ts

@@ -224,7 +224,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;
     });
@@ -243,7 +243,7 @@ export class CultCache {
       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;
     });
@@ -418,6 +418,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,
@@ -579,7 +580,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);
@@ -795,11 +796,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.`);
     }
@@ -894,6 +897,8 @@ export class CultCache {
       }
     }
 
+    const lookups = this.#lookupsFor(registered.nameAccessor, registered.indexAccessors, value);
+    this.#refuseIndexSharing(state, entry.type, registered.catalogEntry.schemaName, entry.key, lookups);
     return {
       ...entry,
       payload: this.#cloneBytes(entry.payload),
@@ -902,10 +907,22 @@ export class CultCache {
       schemaId: registered.catalogEntry.schemaId,
       catalogEntry: registered.catalogEntry,
       value,
-      lookups: this.#lookupsFor(registered.nameAccessor, registered.indexAccessors, value),
+      lookups,
     };
   }
 
+  // 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,12 +983,14 @@ 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 {
     const entryLookups: Array<[HydratedEntry, EntryLookups]> = [];
     const nameMap = nameAccessor ? new Map<string, string>() : undefined;
     const indexMaps = new Map<string, Map<string, string>>();
+    const sharing = new Map<string, string[]>();
     for (const indexName of indexAccessors.keys()) {
       indexMaps.set(indexName, new Map());
     }
@@ -983,10 +1002,23 @@ 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)!;
+        const holder = map.get(indexValue);
+        if (holder === undefined) {
+          map.set(indexValue, entry.key);
+        } else {
+          sharing.set(`${indexName}\u0000${indexValue}`, [...(sharing.get(`${indexName}\u0000${indexValue}`) ?? [holder]), entry.key]);
+        }
       }
     }
 
+    // Judged whole: any value held by two records refuses, naming the two smallest of its keys. Held records already
+    // passed the judge for every alias installed before, so only the alias being registered can be shared here.
+    for (const [id, keys] of sharing) {
+      keys.sort(compareOrdinal);
+      throw indexSharingRefusal(keys[0], keys[1], schemaName, id.slice(0, id.indexOf("\u0000")));
+    }
+
     return { entryLookups, nameMap, indexMaps };
   }
 
@@ -1057,3 +1089,42 @@ export class CultCache {
     return documentPayloadFromBytes(new Uint8Array(documentPayloadBytes(payload)));
   }
 }
+
+function compareOrdinal(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+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.ts

@@ -32,23 +32,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) {
@@ -138,10 +137,13 @@ export function resolveDocumentMembers(definition: AnyCultCacheDocumentDefinitio
     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

@@ -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;
   }
 
@@ -158,7 +148,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 {
@@ -395,8 +385,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 +408,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 +416,8 @@ 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 };
+  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 {

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>;
 }

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

@@ -504,46 +504,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 () => {

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/store-file.test.ts

@@ -471,44 +471,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 });
   }
@@ -697,7 +723,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/unique-index.test.ts

@@ -0,0 +1,504 @@
+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");
+});
+
+test("the keys in a refusal are in ordinal order whichever one lands second", async () => {
+  const document = item("item");
+  const cache = memory(document);
+  await cache.put(document, "m", { sku: "S" });
+  await assert.rejects(cache.put(document, "z", { sku: "S" }), { message: refusal("m", "z", "tests.item", "sku") });
+  await assert.rejects(cache.put(document, "B", { sku: "S" }), { message: refusal("B", "m", "tests.item", "sku") });
+});
+
+// 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 });
+  }
+});
+
+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 over held duplicates installs nothing", 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: 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" }, roles: { b: "b" } });
+  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);
+});
+
+test("verdict parity: the same stores are refused whatever the load order, and the first collision refuses (text is informational)", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "uidx-verdict-"));
+  try {
+    // Three records, one pair colliding; whichever position the pair has in the file, the store is refused and a clean store opens.
+    const roles = pair({ roles: { a: "a" } });
+    for (const [name, values, refused] of [
+      ["pair-first", ["s", "s", "t"], true],
+      ["pair-last", ["t", "s", "s"], true],
+      ["pair-split", ["s", "t", "s"], true],
+      ["distinct", ["r", "s", "t"], false],
+    ] as const) {
+      const file = join(dir, `${name}.cc`);
+      const writer = CultCache.builder().withDocumentType(roles).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      for (const [i, a] of values.entries()) await writer.put(roles, `r${i}`, { a });
+      const unique = pair({ indexes: { a: "a" } });
+      const reader = CultCache.builder().withDocumentType(unique).withGenericStore(new SingleFileMessagePackBackingStore(file)).build();
+      if (refused) await assert.rejects(reader.pullAllBackingStores(), /both hold unique index 'a'/u, name);
+      else await reader.pullAllBackingStores();
+      assert.equal(reader.snapshot().length, refused ? 0 : 3, name);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

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-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,
 )

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)
@@ -1295,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(
@@ -1306,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/tests/test_unique_index_watch.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+from cultcache_py import define_database_entry_type
+from cultcache_py.cache import CultCacheError
+from cultmesh_py import CultMesh
+
+# variants:ruling:unique-indexes. `indexes` are unique lookups, `roles` are selection aliases. A watch by index reads the
+# lookup's own canonical text (cultcache_py.cache.index_text), never a second rendering of the value.
+
+
+class WatchByIndexTests(unittest.TestCase):
+    def test_the_watch_and_the_lookup_agree_on_the_text_of_a_value(self) -> None:
+        document = define_database_entry_type("mesh.priced", [("price", 0)], indexes={"price": "price"})
+        node = CultMesh.create_node(runtime_id="mesh-watch-text")
+        node.database.register_document(document)
+        cases = [
+            (2.0, "2", "2.0"),
+            (0.1, "0.1000000000000000055511151231257827021181583404541015625", "0.1"),
+            (-0.0, "0", "-0.0"),
+        ]
+        for index, (value, text, str_text) in enumerate(cases):
+            with self.subTest(value=value):
+                key = f"item:{index}"
+                heard: list[str] = []
+                misheard: list[str] = []
+                node.database.watch_by_index(document, "price", text, lambda change: heard.append(change.record_key))
+                node.database.watch_by_index(document, "price", str_text, lambda change: misheard.append(change.record_key))
+                node.database.put(document, key, {"price": value})
+                self.assertEqual(node.database.get_by_index(document, "price", text), {"price": value})
+                self.assertEqual(heard, [key])
+                if str_text != text:
+                    self.assertEqual(misheard, [])
+                    self.assertIsNone(node.database.get_by_index(document, "price", str_text))
+
+    def test_a_blank_value_is_never_indexed_so_never_watched(self) -> None:
+        document = define_database_entry_type("mesh.blank", [("sku", 0)], indexes={"sku": "sku"})
+        node = CultMesh.create_node(runtime_id="mesh-watch-blank")
+        node.database.register_document(document)
+        heard: list[str] = []
+        node.database.watch_by_index(document, "sku", " ", lambda change: heard.append(change.record_key))
+        node.database.put(document, "item:1", {"sku": " "})
+        self.assertEqual(heard, [])
+
+    def test_a_role_alias_is_not_watchable_by_index(self) -> None:
+        document = define_database_entry_type("mesh.roles", [("kind", 0)], roles={"kind": "kind"})
+        node = CultMesh.create_node(runtime_id="mesh-watch-role")
+        node.database.register_document(document)
+        with self.assertRaisesRegex(ValueError, "has no index"):
+            node.database.watch_by_index(document, "kind", "guide", lambda _: None)
+
+
+class ReadmeTests(unittest.TestCase):
+    def test_the_readme_note_document_admits_many_notes_of_one_kind(self) -> None:
+        readme = (Path(__file__).parents[1] / "README.md").read_text(encoding="utf-8")
+        declaration = re.search(r"^note_doc = define_database_entry_type\(\n.*?^\)\n", readme, re.S | re.M)
+        self.assertIsNotNone(declaration)
+        scope: dict = {"define_database_entry_type": define_database_entry_type}
+        exec(declaration.group(0), scope)  # noqa: S102 - the README's own declaration
+        note_doc = scope["note_doc"]
+        node = CultMesh.create_node(runtime_id="mesh-readme")
+        node.database.register_document(note_doc)
+        node.database.put(note_doc, "note:1", {"body": "a", "name": "one", "kind": "guide", "slug": "one"})
+        node.database.put(note_doc, "note:2", {"body": "b", "name": "two", "kind": "guide", "slug": "two"})
+        self.assertEqual(node.database.get_by_index(note_doc, "slug", "two")["body"], "b")
+        with self.assertRaises(CultCacheError):
+            node.database.put(note_doc, "note:3", {"body": "c", "name": "three", "kind": "guide", "slug": "one"})
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultnet-py/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased (breaking; version 0.x, so the next minor)
 
+- `CultNetDatabaseChange` carries `commit_id` and `commit_count` (`commitId`/`commitCount`; None outside a multi-record commit, as C# writes nil): `from_wire` refuses an empty or non-string id and a count that is not an integer of at least 2, `to_wire` writes them when set, and the published `database_change_raw` schema lists both. Python applies no batch. The `simulation_fact` document's `shard`, `frame`, `subject` and `claim_kind` aliases are `roles` (many facts share each); the catalog bytes do not move.
 - Decodes the write receipt frames of `contracts/cultnet/interop/write-receipt.md`: `parse_message` validates `cultnet.write_admitted.v0` and `cultnet.error.v1` against their closed schemas (unknown keys, empty or non-string ids, an unknown operation or code are refused; `error.v1` requires `messageId`, string or null; `limit_reached` is `error.v1` only). Added `CULTNET_ERROR_V1_CODES`, `CULTNET_WRITE_RECEIPT_MESSAGE_VERSIONS`, `write_content_hash` and `hello_advertises_write_receipts`; `hello` takes `supported_message_versions`. `tests/test_write_receipt.py` replays the vectors' `contentHash`, `wire` and `schemaInvalid` sections. Not implemented here: the client write tracker (`scenarios`) and the server rules (`dedupe`, `blankFields`); this package has no receipt server and no write client.
 - Added `message_invalid` to `CULTNET_ERROR_CODES` and `message_invalid_error(field, reason)`, byte-identical to the C# `ForMessageInvalid`. `cultmesh-py` refuses a malformed put or delete with it instead of the out-of-schema `malformed_document_put` and `malformed_document_delete`, which are removed.
 - Added `CultNetRudpSocketTransportServer` (`cultnet_py.rudp_server`): one UDP socket serving many RUDP peers, one session per

packages/cultnet-py/src/cultnet_py/cultmesh_contracts.py

@@ -692,7 +692,7 @@ simulation_fact_document: DocumentDefinition[CultMeshSimulationFact] = define_da
     ],
     cls=CultMeshSimulationFact,
     name="fact_id",
-    indexes={"shard": "shard_id", "frame": "frame", "subject": "subject_id", "claim_kind": "claim_kind"},
+    roles={"shard": "shard_id", "frame": "frame", "subject": "subject_id", "claim_kind": "claim_kind"},
     schema_name=SIMULATION_FACT_DOCUMENT_TYPE,
     schema_version=SIMULATION_FACT_SCHEMA_VERSION,
 )

packages/cultnet-py/src/cultnet_py/schema_catalog.py

@@ -432,6 +432,8 @@ def wire_message_schema_properties(schema_version: str) -> dict[str, Any]:
             "document": {"$ref": "#/$defs/rawDocumentRecord"},
             "schemaId": common["schemaId"],
             "recordKey": common["recordKey"],
+            "commitId": {"type": ["string", "null"], "minLength": 1},
+            "commitCount": {"type": ["integer", "null"], "minimum": 2},
         },
         "cultnet.shard_catalog_request.v0": {
             **common,

packages/cultnet-py/src/cultnet_py/subscription.py

@@ -15,6 +15,10 @@ class CultNetDatabaseChange:
     raw_document: CultNetRawDocumentRecord | None = None
     schema_id: str | None = None
     record_key: str | None = None
+    commit_id: str | None = None
+    """Set on every change of one multi-record commit, the same for all of them; None outside one (C# writes nil)."""
+    commit_count: int | None = None
+    """How many changes the commit holds (>= 2); None outside one. Carried data: Python applies no batch."""
 
     @classmethod
     def from_wire(cls, message: dict[str, Any]) -> "CultNetDatabaseChange":
@@ -31,6 +35,12 @@ class CultNetDatabaseChange:
         if raw_document is not None:
             schema_id = schema_id or raw_document.schema_id
             record_key = record_key or raw_document.record_key
+        commit_id = message.get("commitId")
+        if commit_id is not None and not (isinstance(commit_id, str) and commit_id):
+            raise ValueError(f"database change commitId must be a non-empty string, received {commit_id!r}")
+        commit_count = message.get("commitCount")
+        if commit_count is not None and (isinstance(commit_count, bool) or not isinstance(commit_count, int) or commit_count < 2):
+            raise ValueError(f"database change commitCount must be an integer of at least 2, received {commit_count!r}")
         return cls(
             message_id=str(message.get("messageId") or ""),
             subscription_id=str(message.get("subscriptionId") or ""),
@@ -39,6 +49,8 @@ class CultNetDatabaseChange:
             raw_document=raw_document,
             schema_id=schema_id,
             record_key=record_key,
+            commit_id=commit_id,
+            commit_count=commit_count,
         )
 
     def to_wire(self) -> dict[str, Any]:
@@ -56,6 +68,10 @@ class CultNetDatabaseChange:
             wire["schemaId"] = self.schema_id
         if self.record_key is not None:
             wire["recordKey"] = self.record_key
+        if self.commit_id is not None:
+            wire["commitId"] = self.commit_id
+        if self.commit_count is not None:
+            wire["commitCount"] = self.commit_count
         return wire
 
 

packages/cultnet-py/tests/test_cultnet.py

@@ -1566,6 +1566,63 @@ class CultNetTests(unittest.TestCase):
         self.assertEqual(delete_change.schema_id, "schema-note")
         self.assertEqual(delete_change.to_wire()["recordKey"], "note:1")
 
+    def test_cultnet_database_change_commit_fields(self) -> None:
+        base = {
+            "schemaVersion": "cultnet.database_change_raw.v0",
+            "messageId": "change-commit",
+            "subscriptionId": "sub-1",
+            "changeKind": "removed",
+            "schemaId": "schema-note",
+            "recordKey": "note:1",
+        }
+        grouped = CultNetDatabaseChange.from_wire({**base, "commitId": "commit-7", "commitCount": 3})
+        self.assertEqual((grouped.commit_id, grouped.commit_count), ("commit-7", 3))
+        self.assertEqual(grouped.to_wire()["commitId"], "commit-7")
+        self.assertEqual(grouped.to_wire()["commitCount"], 3)
+        self.assertEqual(CultNetDatabaseChange.from_wire(grouped.to_wire()), grouped)
+
+        for absent in (base, {**base, "commitId": None, "commitCount": None}):  # C# writes nil outside a commit
+            change = CultNetDatabaseChange.from_wire(absent)
+            self.assertIsNone(change.commit_id)
+            self.assertIsNone(change.commit_count)
+            self.assertNotIn("commitId", change.to_wire())
+            self.assertNotIn("commitCount", change.to_wire())
+
+        for field, bad in (
+            ("commitId", ""),
+            ("commitId", 7),
+            ("commitCount", 1),
+            ("commitCount", 0),
+            ("commitCount", True),
+            ("commitCount", 2.0),
+            ("commitCount", "3"),
+        ):
+            with self.subTest(field=field, bad=bad), self.assertRaisesRegex(ValueError, field):
+                CultNetDatabaseChange.from_wire({**base, field: bad})
+
+    def test_a_two_change_commit_from_the_csharp_server_parses(self) -> None:
+        # CultNetDatabaseServer.DeliverCommit (CultNetDatabaseServer.cs:791-797) tags every change of a commit with its
+        # commitId and commitCount = the number of changes delivered, so a swap of two records arrives with commitCount 2.
+        # Shaped as the C# [MessagePackObject] writes it: every key present, nil where unset.
+        swap = [
+            {
+                "schemaVersion": "cultnet.database_change_raw.v0",
+                "messageId": f"change-{index}",
+                "subscriptionId": "sub-1",
+                "changeKind": "updated",
+                "document": None,
+                "recordKey": key,
+                "schemaId": "schema-note",
+                "commitId": "9f1c0f0e4b7a4c1f9d2e",
+                "commitCount": 2,
+            }
+            for index, key in enumerate(("note:a", "note:b"))
+        ]
+        changes = [CultNetDatabaseChange.from_wire(message) for message in swap]
+        self.assertEqual([change.commit_count for change in changes], [2, 2])
+        self.assertEqual({change.commit_id for change in changes}, {"9f1c0f0e4b7a4c1f9d2e"})
+        self.assertEqual([change.to_wire()["commitCount"] for change in changes], [2, 2])
+
     def test_cultnet_raw_put_helper_carries_message_id(self) -> None:
         put = document_put_raw(
             message_id="put-1",
@@ -2272,6 +2329,8 @@ class CultNetTests(unittest.TestCase):
         self.assertIn("document", change_schema["properties"])
         self.assertIn("schemaId", change_schema["properties"])
         self.assertIn("recordKey", change_schema["properties"])
+        self.assertEqual(change_schema["properties"]["commitId"], {"type": ["string", "null"], "minLength": 1})
+        self.assertEqual(change_schema["properties"]["commitCount"], {"type": ["integer", "null"], "minimum": 2})
 
         log_schema = json.loads(by_version["cultnet.shard_log_response.v0"]["schemaJson"])
         self.assertIn("entries", log_schema["required"])

packages/cultnet-ts/README.md

@@ -66,6 +66,7 @@ Current message families:
 - `cultnet.snapshot_response.v0`
 - `cultnet.snapshot_response_raw.v0`
 - `cultnet.snapshot_request.v1`, `cultnet.database_subscribe.v1`, `cultnet.snapshot_response_raw.v1` (typed-selection carriers; no selection engine yet)
+- `cultnet.database_change_raw.v0` (optional `commitId` and `commitCount >= 2` mark the changes of one commit; carried and validated here, no TS code groups or applies by them)
 - `cultnet.sample.change_name.v0`
 - `cultnet.sample.chat.v0`
 

packages/cultnet-ts/src/contracts.ts

@@ -424,6 +424,10 @@ export interface CultNetDatabaseChangeRawMessage {
   document?: CultNetRawDocumentRecord;
   recordKey?: string;
   schemaId?: string;
+  /** Opaque, one subscription: changes sharing a commitId are the changes of one commit. */
+  commitId?: string | null;
+  /** How many changes the commit carries, at least two. The C# server sends null on a change outside a grouped commit. */
+  commitCount?: number | null;
 }
 
 export interface CultNetSchemaDescriptor {
@@ -1397,6 +1401,15 @@ function validateDatabaseChangeRawMessage(
     );
   }
 
+  if (candidate.commitId !== undefined && candidate.commitId !== null &&
+      (typeof candidate.commitId !== "string" || candidate.commitId.length === 0)) {
+    throw new Error("Validation failed for cultnet.database_change_raw.v0: /commitId: must be a non-empty string");
+  }
+  if (candidate.commitCount !== undefined && candidate.commitCount !== null &&
+      (typeof candidate.commitCount !== "number" || !Number.isInteger(candidate.commitCount) || candidate.commitCount < 2)) {
+    throw new Error("Validation failed for cultnet.database_change_raw.v0: /commitCount: must be an integer of at least 2");
+  }
+
   if (candidate.changeKind === "removed") {
     requireNonEmptyString(candidate.recordKey, "/recordKey");
     requireNonEmptyString(candidate.schemaId, "/schemaId");

packages/cultnet-ts/test/cultnet.test.ts

@@ -54,6 +54,7 @@ import {
   validateGhostlightAgentStateGenerated,
   validateGhostlightAgentState,
   shardServes,
+  type CultNetDatabaseChangeRawMessage,
   type CultNetLoginMessage,
   type GhostlightAgentStateShape,
   type GhostlightAgentStateDocument,
@@ -1688,6 +1689,55 @@ test("database subscription contracts match the C# live document lane", () => {
   assert.equal(removed.schemaVersion, "cultnet.database_change_raw.v0");
   assert.equal(removed.recordKey, "counter:main");
 
+  const grouped = parseCultNetMessage({
+    schemaVersion: "cultnet.database_change_raw.v0",
+    messageId: "change-counter-3",
+    subscriptionId: "counter:browser-1",
+    changeKind: "removed",
+    recordKey: "counter:main",
+    schemaId: "sample.counter_state.v1",
+    commitId: "c1",
+    commitCount: 2,
+  });
+  assert.equal((grouped as CultNetDatabaseChangeRawMessage).commitId, "c1");
+  assert.equal((grouped as CultNetDatabaseChangeRawMessage).commitCount, 2);
+  assert.deepEqual(encodeCultNetMessageForWire(grouped), grouped, "both commit fields travel");
+  assert.equal((removed as CultNetDatabaseChangeRawMessage).commitId, undefined, "a change without them parses as before");
+  const changeWith = (extra: Record<string, unknown>) => () => parseCultNetMessage({
+    schemaVersion: "cultnet.database_change_raw.v0",
+    messageId: "change-counter-4",
+    subscriptionId: "counter:browser-1",
+    changeKind: "removed",
+    recordKey: "counter:main",
+    schemaId: "sample.counter_state.v1",
+    ...extra,
+  });
+  // The C# server writes commitId and commitCount as nil on every change outside a grouped commit, so null is absent.
+  const ungrouped = changeWith({ commitId: null, commitCount: null })() as CultNetDatabaseChangeRawMessage;
+  assert.equal(ungrouped.commitId, null);
+  assert.equal(ungrouped.commitCount, null);
+  assert.doesNotThrow(changeWith({ commitId: null }));
+  assert.doesNotThrow(changeWith({ commitCount: null }));
+  assert.doesNotThrow(() => parseCultNetMessage({
+    schemaVersion: "cultnet.database_change_raw.v0",
+    messageId: "change-counter-5",
+    subscriptionId: "counter:browser-1",
+    changeKind: "added",
+    document: {
+      schemaId: "sample.counter_state.v1",
+      recordKey: "counter:main",
+      storedAt: "2026-08-17T00:00:00Z",
+      payloadEncoding: "messagepack",
+      payload: new Uint8Array([0x81, 0xa5, 0x63, 0x6f, 0x75, 0x6e, 0x74, 0x01]),
+    },
+    recordKey: null,
+    schemaId: null,
+    commitId: null,
+    commitCount: null,
+  }));
+  for (const commitId of ["", 5]) assert.throws(changeWith({ commitId }), /\/commitId/, `commitId ${JSON.stringify(commitId)}`);
+  for (const commitCount of [1, 0, 2.5, "two", -3]) assert.throws(changeWith({ commitCount }), /\/commitCount/, `commitCount ${commitCount}`);
+
   const unsubscribe = parseCultNetMessage({
     schemaVersion: "cultnet.database_unsubscribe.v0",
     messageId: "unsubscribe-counter",

packages/cultnet-ts/test/governance-vectors.test.ts

@@ -0,0 +1,600 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+
+import Ajv2020 from "ajv/dist/2020.js";
+import { decode, encode } from "@msgpack/msgpack";
+
+// contracts/cultnet/governance: the vote-API and fork-card contracts (vote-api.md, fork-card.md). The vectors are spec-authored
+// (scripts/gen-governance-vectors.py); this suite re-encodes every message with this runtime and must reproduce the bytes, judges
+// every negative with the committed schema, and replays the fork scenarios through a reference judge written from fork-card.md.
+const DIR = join(__dirname, "..", "..", "..", "..", "contracts", "cultnet", "governance");
+const read = (name: string) => JSON.parse(readFileSync(join(DIR, name), "utf8"));
+const vote = read("vote-api-vectors.json");
+const fork = read("fork-card-vectors.json");
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const voteSchema = read("vote-api.schema.json");
+const forkSchema = read("fork-card.schema.json");
+ajv.addSchema(voteSchema);
+ajv.addSchema(forkSchema);
+const check = (schema: { $id: string }, def: string, value: unknown): boolean => {
+  const validate = ajv.getSchema(`${schema.$id}#/$defs/${def}`);
+  assert.ok(validate, `no schema def ${def}`);
+  return validate(value) as boolean;
+};
+const hexOf = (value: unknown): string => Buffer.from(encode(value)).toString("hex").toUpperCase();
+const sha = (bytes: Buffer | string): string => createHash("sha256").update(bytes).digest("hex");
+
+// Rules a JSON Schema cannot say: vote-api.md counts a reason in UTF-16 code units (as Bifrost does); maxLength counts code points.
+const voteRuleErrors = (def: string, message: any): string[] =>
+  def === "cast" && message.ballot !== null && message.ballot.reason.length > 280 ? ["reason is over 280 UTF-16 code units"] : [];
+
+test("vote API: every valid document validates, encodes to the vector bytes and decodes back", () => {
+  for (const v of vote.valid) {
+    assert.ok(check(voteSchema, v.def, v.message), v.name);
+    assert.deepEqual(voteRuleErrors(v.def, v.message), [], v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    assert.deepEqual(decode(Buffer.from(v.messagePackHex, "hex")), v.message, v.name);
+  }
+});
+
+test("vote API: every negative is refused by the schema, and its bytes are the vector's", () => {
+  for (const v of vote.invalid) {
+    assert.ok(!check(voteSchema, v.def, v.message) || voteRuleErrors(v.def, v.message).length > 0, `${v.name}: ${v.why}`);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+  }
+});
+
+test("vote API: the commitment is SHA-256 of the canonical bytes", () => {
+  for (const c of vote.commitment) {
+    const b = c.ballot;
+    const bytes = Buffer.from(`gamecult.sealed_ballot.v0\n${b.motionId}\n${c.voterUserAccountId}\n${b.persona}\n${b.round}\n${b.candidate}\n${b.reason}\n${b.salt}`, "utf8");
+    assert.equal(bytes.toString("hex").toUpperCase(), c.canonicalHex, c.name);
+    assert.equal(sha(bytes), c.sha256, c.name);
+  }
+});
+
+test("vote API: a reveal matches its commit exactly when the ballot hashes to the commitment", () => {
+  for (const p of vote.pairs) {
+    const b = p.reveal.ballot;
+    const digest = sha(Buffer.from(`gamecult.sealed_ballot.v0\n${b.motionId}\n${p.voterUserAccountId}\n${b.persona}\n${b.round}\n${b.candidate}\n${b.reason}\n${b.salt}`, "utf8"));
+    assert.equal(digest === p.commit.commitment, p.matches, p.name);
+    assert.ok(check(voteSchema, "cast", p.commit) && check(voteSchema, "cast", p.reveal), p.name);
+  }
+});
+
+test("vote API: each refusal code has a vector, a status and the vector bytes", () => {
+  const codes = (voteSchema.$defs.refusal.properties.code as { enum: string[] }).enum;
+  assert.deepEqual(vote.refusals.map((r: { message: { code: string } }) => r.message.code).sort(), [...codes].sort());
+  for (const r of vote.refusals) {
+    assert.ok(check(voteSchema, "refusal", r.message), r.name);
+    assert.equal(hexOf(r.message), r.messagePackHex, r.name);
+    assert.ok(r.httpStatus >= 400, r.name);
+  }
+  assert.ok(vote.refusals.find((r: { name: string }) => r.name === "rate_limited").message.retryAfterSeconds >= 1);
+});
+
+// ---- fork card (rule source: /opt/commons/handoff/fork-desk-answer-binding-20261110.md) ----
+const jstr = (s: string): string => {
+  let out = '"';
+  for (const ch of s) {
+    const o = ch.codePointAt(0)!;
+    out += ch === '"' ? '\\"' : ch === "\\" ? "\\\\" : o === 8 ? "\\b" : o === 9 ? "\\t" : o === 10 ? "\\n" : o === 12 ? "\\f" : o === 13 ? "\\r"
+      : o < 0x20 ? "\\u" + o.toString(16).padStart(4, "0") : ch;
+  }
+  return out + '"';
+};
+type Option = { id: string; text: string };
+type Shown = { title: string; context: string; options: Option[]; recommendation: string; depends: string[] };
+type Card = Shown & { fork_id: string; leans: string | null; deciders: string[]; status: string; ruling: string | null; ruled_from: string[]; options_hash: string };
+// RFC 8785 over the five shown members, every string NFC-normalised first; keys sorted; no numbers in the member set.
+const nfc = (s: string): string => s.normalize("NFC");
+const canonical = (c: Shown): Buffer =>
+  Buffer.from(`{"context":${jstr(nfc(c.context))},"depends":[${c.depends.map((d) => jstr(nfc(d))).join(",")}],"options":[${c.options.map((o) => `{"id":${jstr(nfc(o.id))},"text":${jstr(nfc(o.text))}}`).join(",")}],"recommendation":${jstr(nfc(c.recommendation))},"title":${jstr(nfc(c.title))}}`, "utf8");
+const optionsHash = (c: Shown): string => sha(canonical(c));
+
+const cardRuleErrors = (c: Card): string[] => {
+  const ids = c.options.map((o) => o.id);
+  const errors: string[] = [];
+  if (new Set(ids).size !== ids.length) errors.push("duplicate option ids");
+  if (!ids.includes(c.recommendation)) errors.push("recommendation is not an option");
+  if (c.leans !== null && !ids.includes(c.leans)) errors.push("leans is not an option");
+  if (new Set(c.deciders).size !== c.deciders.length) errors.push("duplicate deciders");
+  if (c.depends.some((d) => Buffer.byteLength(d, "utf8") > 1000)) errors.push("a depends line is over 1000 UTF-8 bytes");
+  if (c.status === "open" && c.ruling !== null) errors.push("an open card names a ruling");
+  if (c.ruling === null && c.ruled_from.length > 0) errors.push("ruled_from without a ruling");
+  if (c.options_hash !== optionsHash(c)) errors.push("options_hash is not the hash of the shown members");
+  return errors;
+};
+
+test("fork card: options hash is SHA-256 of the canonical JSON, computed here, and every shown member moves it", () => {
+  for (const h of fork.optionsHash) {
+    const bytes = canonical(h);
+    assert.equal(bytes.toString("utf8"), h.canonical, h.name);
+    assert.equal(bytes.toString("hex").toUpperCase(), h.canonicalHex, h.name);
+    assert.equal(sha(bytes), h.sha256, h.name);
+  }
+  const byName = new Map<string, string>(fork.optionsHash.map((h: { name: string; sha256: string }) => [h.name, h.sha256]));
+  const base = byName.get("heimdall_A_five_members")!;
+  assert.equal(byName.get("hidden_members_do_not_move_it"), base);
+  assert.equal(byName.get("heimdall_E_decomposed_equals_D"), byName.get("heimdall_D_nfc_escapes_astral"), "an NFD and an NFC spelling hash alike");
+  for (const moved of ["heimdall_B_recommendation_changed", "heimdall_C_option_order_changed", "heimdall_F_option_id_changed", "heimdall_G_depends_emptied", "option_text_changed",
+                       "title_changed", "context_changed", "depends_order_changed", "depends_order_changed_reversed"]) {
+    assert.notEqual(byName.get(moved), base, moved);
+  }
+});
+
+test("fork card: an answer result without counted_answer_id is refused by the schema", () => {
+  const result = structuredClone(fork.scenarios.flatMap((sc: any) => sc.steps).find((st: any) => st.response?.answer).response);
+  assert.ok(check(forkSchema, "answerResult", result));
+  delete result.counted_answer_id;
+  assert.ok(!check(forkSchema, "answerResult", result));
+});
+
+// body_sha256 is Huginn's private "same body" digest, not a wire field: compact JSON, fixed key order, null for missing, the two illegal-form keys only when present.
+test("fork card: the body digest is SHA-256 of the compact JSON in the stated key order, and the fixed forms separate retracted true from false", () => {
+  const byName = new Map<string, any>(fork.bodyDigests.map((d: { name: string }) => [d.name, d]));
+  for (const d of fork.bodyDigests) {
+    const o: Record<string, unknown> = {};
+    for (const key of ["fork", "options_hash", "answered_at", "choice", "note", "retracts", "illegal_retraction", "retracted"]) {
+      if ((key === "illegal_retraction" || key === "retracted") && d.input[key] === null) continue;
+      o[key] = d.input[key];
+    }
+    const json = JSON.stringify(o);
+    assert.equal(json, d.canonical, d.name);
+    assert.equal(sha(Buffer.from(json, "utf8")), d.sha256, d.name);
+  }
+  assert.ok(byName.get("plain_answer_choice_A").sha256.startsWith("8a4d5b2e"));
+  assert.ok(byName.get("legal_retraction").sha256.startsWith("9f807538"));
+  assert.ok(byName.get("legal_retraction_door_form").sha256.startsWith("84576840"));
+  assert.ok(byName.get("legal_retraction_door_form").input.retracts.endsWith(".n1"), "the door's form: the wire n<seq> converted to the full key");
+  assert.ok(byName.get("illegal_i_retraction_with_an_answer_retracted_true").sha256.startsWith("935cab1a"));
+  assert.ok(byName.get("illegal_iii_plain_answer_with_a_target_retracted_false").sha256.startsWith("82b24ccc"));
+  assert.ok(byName.get("illegal_ii_no_answer_no_target_retracted_true").sha256.startsWith("34ef86ed"));
+  assert.equal(new Set(fork.bodyDigests.map((d: { sha256: string }) => d.sha256)).size, fork.bodyDigests.length, "no two vectors share a digest");
+});
+
+test("fork card: mutating any shown member, an option id included, changes the hash", () => {
+  const card = fork.card.valid[0].message as Card;
+  const base = optionsHash(card);
+  const mutations: ((c: Card) => void)[] = [
+    (c) => { c.title += "x"; }, (c) => { c.context += "x"; }, (c) => { c.options[0].id += "x"; }, (c) => { c.options[0].text += "x"; },
+    (c) => { c.options.reverse(); }, (c) => { c.recommendation = c.options[0].id; }, (c) => { c.depends = [...c.depends, "a:b:c"]; }, (c) => { c.depends = []; },
+  ];
+  for (const [i, mutate] of mutations.entries()) {
+    const copy = structuredClone(card);
+    mutate(copy);
+    assert.notEqual(optionsHash(copy), base, `mutation ${i}`);
+  }
+  const hidden = structuredClone(card);
+  hidden.fork_id = "other:question:id"; hidden.leans = "yes"; hidden.deciders = ["x"]; hidden.status = "closed"; hidden.ruled_from = ["n1"];
+  assert.equal(optionsHash(hidden), base, "fork_id and the unshown members stay outside the hash");
+});
+
+test("fork card: documents validate and encode to the vector bytes", () => {
+  for (const v of fork.card.valid) {
+    assert.ok(check(forkSchema, "card", v.message), v.name);
+    assert.deepEqual(cardRuleErrors(v.message), [], v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+  }
+  for (const [section, def] of [["request", "answerRequest"], ["deskAnswer", "deskAnswer"]] as const) {
+    for (const v of fork[section].valid) {
+      assert.ok(check(forkSchema, def, v.message), v.name);
+      assert.deepEqual(noteRuleErrors(def, v.message), [], v.name);
+      assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+      assert.deepEqual(decode(Buffer.from(v.messagePackHex, "hex")), v.message, v.name);
+    }
+  }
+  const resultCodes = (forkSchema.$defs.deskAnswerRefused.properties.code as { enum: string[] }).enum;
+  assert.deepEqual(fork.results.map((r: { name: string }) => r.name).sort(), [...resultCodes].sort());
+  for (const v of fork.results) {
+    assert.ok(check(forkSchema, "answerResult", v.message), v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    assert.equal(v.message.card !== null, v.name === "stale_fork", "only a stale refusal shows the new fork");
+  }
+  for (const v of fork.unavailable) {
+    assert.ok(check(forkSchema, "unavailable", v.message), v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    assert.equal(v.httpStatus, 503, v.name);
+  }
+  const doorCodes = (forkSchema.$defs.refusal.properties.code as { enum: string[] }).enum;
+  assert.ok(!doorCodes.includes("unavailable"), "unavailable is kept apart from the refusal set");
+  assert.deepEqual(fork.doorRefusals.map((r: { name: string }) => r.name).sort(), [...doorCodes].sort());
+  for (const v of fork.doorRefusals) {
+    assert.ok(check(forkSchema, "refusal", v.message), v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+  }
+  assert.equal(fork.doorRefusals.find((r: { name: string }) => r.name === "fork_too_large").httpStatus, 422);
+});
+
+test("fork card: every negative is refused by the schema or a stated rule", () => {
+  for (const v of fork.card.invalid) {
+    assert.ok(!check(forkSchema, "card", v.message) || cardRuleErrors(v.message).length > 0, `${v.name}: ${v.why}`);
+  }
+  for (const [section, def] of [["request", "answerRequest"], ["deskAnswer", "deskAnswer"]] as const) {
+    for (const v of fork[section].invalid) {
+      assert.ok(!check(forkSchema, def, v.message) || noteRuleErrors(def, v.message).length > 0, `${v.name}: ${v.why}`);
+      assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    }
+  }
+});
+
+// Rules a JSON Schema cannot say: a note is at most 4000 UTF-8 bytes (maxLength counts code points and is only the looser bound).
+const noteRuleErrors = (def: string, message: any): string[] => {
+  const note = def === "answerRequest" ? message?.answer?.note : def === "deskAnswer" ? message?.note : null;
+  return note != null && Buffer.byteLength(note, "utf8") > 4000 ? ["note is over 4000 UTF-8 bytes"] : [];
+};
+
+const TAILS: Record<string, string> = {
+  unauthenticated: "a verified session is required",
+  body_forbidden_field: "answerer and authority are set by the receiver",
+  body_unknown_field: "the body is a closed shape",
+  body_invalid: "the body does not satisfy gamecult.fork.answer_request.v0",
+  fork_unknown: "no such fork",
+  forbidden: "only Active members may use the desk",
+  request_id_conflict: "this request_id was used for a different body",
+};
+const REQUEST_KEYS = ["schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at", "request_id"];
+const hasKey = (v: unknown, names: string[]): boolean =>
+  typeof v === "object" && v !== null && Object.entries(v).some(([k, x]) => names.includes(k) || hasKey(x, names));
+const SECONDS = (iso: string): number => Date.parse(iso);
+
+// The reference judge: Huginn's half behind the second door as fork-card.md states it. Server-set fields come from the step.
+function judge(start: Card, steps: { kind: string; body: Record<string, any> | null; server: Record<string, any> | null; card?: Card }[]) {
+  let card = start;
+  const answers: Record<string, any>[] = [];
+  const responses: unknown[] = [];
+  const seen = new Map<string, { body: Record<string, any>; response: unknown }>();   // (answerer, request_id) -> the first stored outcome
+  const counted = (): string | null => {
+    const hash = optionsHash(card);
+    const live = answers.find((a) => (a.outcome === "Counted" || a.outcome === "Revision") && a.options_hash === hash
+      && !answers.some((r) => r.outcome === "Retraction" && r.retracts === a.answer_id));
+    return live ? live.answer_id : null;
+  };
+  for (const step of steps) {
+    if (step.kind === "matrix_event") { responses.push(null); continue; }       // rule 9: Matrix never changes a decision
+    if (step.kind === "card") { card = step.card!; responses.push(null); continue; }
+    const s = step.server!, b = step.body!;
+    const door = (code: string) => ({ schemaVersion: "gamecult.fork.refusal.v0", code, error: `${code}: ${TAILS[code]}` });
+    const store = (outcome: string, link: string | null, code: string | null) => {
+      const a = b.answer ?? { choice: null, note: null };
+      const doc = { schemaVersion: "gamecult.desk_answer.v0", answer_id: s.answer_id, fork_id: b.fork_id, outcome,
+        of: outcome === "Revision" ? link : null, retracts: outcome === "Retraction" ? link : outcome === "Refused" ? b.retracts : null, code: outcome === "Refused" ? code : null,
+        options_hash: b.options_hash, choice: a.choice, note: a.note, answered_at: b.answered_at, received_at: s.received_at,
+        claim_in_future: SECONDS(b.answered_at) - SECONDS(s.received_at) > 300_000, answerer: s.answerer, authority: s.authority, request_id: b.request_id };
+      answers.push(doc);
+      const stored = { schemaVersion: "gamecult.fork.answer_result.v0", answer: doc, card: code === "stale_fork" ? card : null, counted_answer_id: counted() };
+      seen.set(`${s.answerer}|${b.request_id}`, { body: structuredClone(b), response: structuredClone(stored) });
+      return stored;
+    };
+    const refuse = (code: string) => store("Refused", null, code);
+    const down = s.door_down === true, reached = s.stored === true;   // the second door failed to answer; "stored" says whether Huginn had the request by then
+    const unavailable = () => ({ schemaVersion: "gamecult.fork.unavailable.v0", code: "unavailable", error: "unavailable: the outcome is not confirmed, try again with the same request_id", retryAfterSeconds: s.retry_after_seconds });
+    // a stored desk_answer has no card, so a replayed stale_fork carries the CURRENT card (fork-card.md, request_id)
+    const replay = (stored: any) => { const copy = structuredClone(stored); if (copy.answer.code === "stale_fork") copy.card = structuredClone(card); copy.counted_answer_id = counted(); return copy; };
+    let response: unknown;
+    if (s.answerer === null) response = door("unauthenticated");
+    else if (s.active === false) response = door("forbidden");
+    else if (hasKey(b, ["answerer", "authority"])) response = door("body_forbidden_field");
+    else if (Object.keys(b).some((k) => !REQUEST_KEYS.includes(k)) || (b.answer && Object.keys(b.answer).some((k) => k !== "choice" && k !== "note"))) response = door("body_unknown_field");
+    else if (!check(forkSchema, "answerRequest", b) || noteRuleErrors("answerRequest", b).length > 0 || (!b.retracted && b.answer === null)) response = door("body_invalid");
+    else if (down && !reached) response = unavailable();
+    else if (seen.has(`${s.answerer}|${b.request_id}`)) { const prior = seen.get(`${s.answerer}|${b.request_id}`)!; response = isDeepStrictEqual(prior.body, b) ? replay(prior.response) : door("request_id_conflict"); }
+    else if (b.fork_id !== card.fork_id) response = door("fork_unknown");
+    else if (b.options_hash !== optionsHash(card)) response = refuse("stale_fork");
+    else if (!card.deciders.includes(s.answerer)) response = refuse("not_a_decider");
+    else if (card.status === "closed") response = refuse("fork_closed");
+    else if (b.retracted || b.retracts !== null) {
+      const target = answers.find((a) => a.answer_id === b.retracts && (a.outcome === "Counted" || a.outcome === "Revision") && a.options_hash === b.options_hash);
+      if (!b.retracted || b.answer !== null || b.retracts === null || !target) response = refuse("bad_retraction");
+      else if (answers.some((a) => a.outcome === "Retraction" && a.retracts === target.answer_id)) response = refuse("already_retracted");
+      else response = store("Retraction", target.answer_id, null);
+    } else if (b.answer.choice !== null && !card.options.some((o) => o.id === b.answer.choice)) response = refuse("choice_invalid");
+    else {
+      const first = counted();
+      response = first === null ? store("Counted", null, null) : store("Revision", first, null);
+    }
+    responses.push(down && reached ? unavailable() : response);
+  }
+  return { responses, record: { schemaVersion: "gamecult.fork.record.v0", fork_id: card.fork_id, options_hash: optionsHash(card), counted_answer_id: counted(), answers } };
+}
+
+test("fork card: every scenario replays to the vector's responses and record, bytes included", () => {
+  for (const sc of fork.scenarios) {
+    assert.equal(optionsHash(sc.card), sc.optionsHash, sc.name);
+    assert.deepEqual(cardRuleErrors(sc.card), [], sc.name);
+    const { responses, record } = judge(sc.card, sc.steps);
+    assert.deepEqual(responses, sc.steps.map((s: { response: unknown }) => s.response), sc.name);
+    assert.deepEqual(record, sc.record, sc.name);
+    assert.ok(check(forkSchema, "record", record), sc.name);
+    assert.equal(hexOf(record), sc.recordHex, sc.name);
+    for (const s of sc.steps) if (s.response) assert.ok(check(forkSchema, "answerResult", s.response) || check(forkSchema, "refusal", s.response) || check(forkSchema, "unavailable", s.response), sc.name);
+  }
+});
+
+test("fork card: a request id belongs to its account; another account's identical body gets its own answer, never the first account's outcome", () => {
+  let crossed = 0;
+  for (const sc of fork.scenarios) {
+    const first = new Map<string, { answerer: string; result: any }>();   // request_id -> the account that first got a stored result and what it got
+    for (const s of sc.steps) {
+      if (s.kind !== "answer" || !s.response?.answer) continue;
+      assert.equal(s.response.answer.answerer, s.server.answerer, `${sc.name}: a result is stamped with the account that asked`);
+      const prior = first.get(s.body.request_id);
+      if (!prior) { first.set(s.body.request_id, { answerer: s.server.answerer, result: s.response }); continue; }
+      if (prior.answerer === s.server.answerer) continue;
+      crossed++;
+      assert.notEqual(s.response.answer.answer_id, prior.result.answer.answer_id, `${sc.name}: its own answer id`);
+      assert.notDeepEqual(s.response, prior.result, `${sc.name}: the first account's outcome is never returned`);
+    }
+  }
+  assert.ok(crossed >= 3, "the vectors carry the cross-account cases");
+});
+
+test("fork card: a body refused at the door or naming an unknown fork is never stored", () => {
+  const door = new Set(["unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "forbidden", "request_id_conflict"]);
+  let doorRefusals = 0;
+  for (const sc of fork.scenarios) {
+    for (const s of sc.steps) {
+      // unavailable promises nothing: the outcome is not confirmed, so the answer is stored exactly when Huginn had it
+      if (s.response?.code === "unavailable") assert.equal(sc.record.answers.some((a: { answer_id: string }) => a.answer_id === s.server.answer_id), s.server.stored === true, `${sc.name} unavailable`);
+      if (s.response && door.has(s.response.code)) {
+        doorRefusals++;
+        assert.ok(!sc.record.answers.some((a: { answer_id: string }) => a.answer_id === s.server.answer_id), `${sc.name} stored a door refusal`);
+      }
+    }
+  }
+  assert.ok(doorRefusals >= 8);
+});
+
+test("fork card: the scenarios cover every outcome and every refusal code", () => {
+  const seen = new Set<string>();
+  for (const sc of fork.scenarios) {
+    for (const s of sc.steps) if (s.response) seen.add(s.response.code ?? s.response.answer.code ?? s.response.answer.outcome);
+    for (const a of sc.record.answers) seen.add(a.outcome);
+  }
+  for (const want of ["Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "forbidden", "request_id_conflict", "stale_fork", "not_a_decider",
+                      "fork_closed", "choice_invalid", "bad_retraction", "already_retracted"]) {
+    assert.ok(seen.has(want), want);
+  }
+});
+
+// A ruling may carry authority Operator only if it cites a Counted desk_answer stamped Operator (binding file 1.3d).
+const admitRuling = (cite: { authority: string; answer_id: string | null }, answers: { answer_id: string; outcome: string; authority: string }[]): boolean => {
+  if (cite.authority !== "Operator") return true;
+  const cited = answers.find((a) => a.answer_id === cite.answer_id);
+  return cited !== undefined && cited.outcome === "Counted" && cited.authority === "Operator";
+};
+
+test("fork card: operator authority needs a cited Counted answer record", () => {
+  for (const c of fork.rulingCites) {
+    assert.ok(check(forkSchema, "rulingCite", c.message), c.name);
+    assert.equal(hexOf(c.message), c.messagePackHex, c.name);
+    assert.equal(admitRuling(c.message, c.answers), c.admit, c.name);
+  }
+});
+
+// ---- transport: list, read, auth (fork-card.md "Transport") ----
+const entryRuleErrors = (e: { card: Card; record: { fork_id: string; options_hash: string; counted_answer_id: string | null; answers: Record<string, any>[] } }): string[] => {
+  const errors = cardRuleErrors(e.card);
+  if (e.record.fork_id !== e.card.fork_id) errors.push("record of another fork");
+  if (e.record.options_hash !== e.card.options_hash) errors.push("record under another hash");
+  const counted = e.record.answers.find((a) => (a.outcome === "Counted" || a.outcome === "Revision") && a.options_hash === e.card.options_hash
+    && !e.record.answers.some((r) => r.outcome === "Retraction" && r.retracts === a.answer_id));
+  if ((counted?.answer_id ?? null) !== e.record.counted_answer_id) errors.push("counted_answer_id is not derived");
+  return errors;
+};
+
+// Order is a unique rank per Mind: the refusal names both fork ids, the first holder and the second.
+const orderErrors = (cards: { fork_id: string; order: number }[]): string[] => {
+  const holder = new Map<number, string>();
+  const errors: string[] = [];
+  for (const c of cards) {
+    if (holder.has(c.order)) errors.push(`order ${c.order} is shared by ${holder.get(c.order)} and ${c.fork_id}`);
+    else holder.set(c.order, c.fork_id);
+  }
+  return errors;
+};
+
+// The reference list judge: newest first by card order, status filter, cursor c<N> = cards below order N, a page of limit, counts over the whole set.
+const judgeList = (entries: { card: Card }[], ordinal: number, rq: { mind: string; status: string | null; cursor: string | null; limit: number }) => {
+  const rows = [...entries].sort((a, b) => (b.card as any).order - (a.card as any).order);
+  let want = rows.filter((e) => rq.status === null || (e.card.status === "open") === (rq.status === "open"));
+  if (rq.cursor !== null) want = want.filter((e) => (e.card as any).order < Number(rq.cursor!.slice(1)));
+  const page = want.slice(0, rq.limit);
+  const more = want.length > page.length && page.length > 0;
+  return { schemaVersion: "gamecult.fork.list.v0", mind: rq.mind, stamp: `s${ordinal}`, open_count: rows.filter((e) => e.card.status === "open").length,
+    recorded_count: rows.filter((e) => e.card.status === "closed").length, forks: page, next_cursor: more ? `c${(page[page.length - 1].card as any).order}` : null };
+};
+
+// Bearer, audience, scope, in that order: a votes.* token fails at the audience and a desk token without the route's scope fails at the scope.
+const authJudge = (route: string, token: { audience: string; scopes: string[]; active: boolean } | null, huginnDown: boolean): string => {
+  if (token === null || token.audience !== "bifrost-desk") return "unauthenticated";
+  if (!token.scopes.includes(route === "answer" ? "desk.answer" : "desk.read")) return "insufficient_scope";
+  if (!token.active) return "forbidden";
+  return huginnDown ? "unavailable" : "ok";
+};
+
+// The {mind} segment is decoded once and compared, exactly, only with the configured list; nothing is opened from it (fork-card.md, "The {mind} segment").
+type MindResult = { code: string; opened: string | null; storedIn: string | null };
+const mindRoute = (config: any, route: string, segment: string, fork: string | null, token: any): MindResult => {
+  const auth = authJudge(route, token, false);
+  if (auth !== "ok") return { code: auth, opened: null, storedIn: null };
+  let mind: string;
+  try { mind = decodeURIComponent(segment); } catch { return { code: "fork_unknown", opened: null, storedIn: null }; }
+  if (!Object.prototype.hasOwnProperty.call(config.minds, mind)) return { code: "fork_unknown", opened: null, storedIn: null };
+  const opened: string = config.minds[mind];
+  if (route !== "list" && !config.forks[mind].includes(fork)) return { code: "fork_unknown", opened, storedIn: null };
+  return { code: "ok", opened, storedIn: route === "answer" ? mind : null };
+};
+
+test("fork transport: the mind segment is only compared with the configured list; an unknown mind is the unknown fork refusal", () => {
+  const config = fork.transport.mindRoutes;
+  const refusals = new Map<string, any>(fork.doorRefusals.map((r: { name: string }) => [r.name, r]));
+  const byName = new Map<string, MindResult>();
+  for (const c of config.cases) {
+    const got = mindRoute(config, c.route, c.mind, c.fork_id, c.token);
+    byName.set(c.name, got);
+    assert.equal(got.code, c.expect, c.name);
+    assert.equal(got.opened, c.opened, `${c.name}: the socket opened`);
+    assert.equal(got.storedIn, c.stored_in, `${c.name}: where an answer was stored`);
+    assert.equal(c.httpStatus, got.code === "ok" ? 200 : refusals.get(got.code).httpStatus, c.name);
+    if (got.code === "fork_unknown") {
+      const error: string = refusals.get("fork_unknown").message.error;
+      assert.ok(!error.includes(c.mind) && !(c.fork_id !== null && error.includes(c.fork_id)), `${c.name}: the refusal names neither the Mind nor the fork`);
+    }
+  }
+  for (const [a, b] of config.sameResponse) {
+    const x = byName.get(a)!, y = byName.get(b)!;
+    assert.equal(x.code, y.code);
+    const built = (code: string) => hexOf({ schemaVersion: "gamecult.fork.refusal.v0", code, error: `${code}: ${TAILS[code]}` });
+    assert.equal(built(x.code), built(y.code), `${a} and ${b} answer with the same bytes, built from the spec's rule`);
+    assert.equal(built(x.code), refusals.get(x.code).messagePackHex, a);
+  }
+  const all = [...byName.values()];
+  assert.ok(all.filter((v) => v.code === "fork_unknown" && v.opened === null).length >= 39, "every bad segment opens nothing");
+  assert.equal(new Set(all.filter((v) => v.storedIn !== null).map((v) => v.storedIn)).size, 2, "an answer is stored in the route's Mind only, and both Minds take one");
+});
+
+test("fork transport: requests and entries validate and encode to the vector bytes, and every negative is refused", () => {
+  const t = fork.transport;
+  for (const [section, def] of [["listRequest", "listRequest"], ["readRequest", "readRequest"], ["entry", "entry"]] as const) {
+    for (const v of t[section].valid) {
+      assert.ok(check(forkSchema, def, v.message), v.name);
+      if (def === "entry") assert.deepEqual(entryRuleErrors(v.message), [], v.name);
+      assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    }
+    for (const v of t[section].invalid) {
+      assert.ok(!check(forkSchema, def, v.message) || (def === "entry" && entryRuleErrors(v.message).length > 0), `${v.name}: ${v.why}`);
+      assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+    }
+  }
+  for (const v of t.listInvalid) {
+    const refused = !check(forkSchema, "list", v.message) || orderErrors(v.message.forks.map((f: any) => f.card)).length > 0;
+    assert.ok(refused, `${v.name}: ${v.why}`);
+    if (v.refusal !== undefined) assert.deepEqual(orderErrors(v.message.forks.map((f: any) => f.card)), [v.refusal], v.name);
+    assert.equal(hexOf(v.message), v.messagePackHex, v.name);
+  }
+});
+
+test("fork transport: every list request replays to the vector's response, newest first, paged by the cursor", () => {
+  for (const sc of fork.transport.listScenarios) {
+    for (const e of sc.entries) assert.deepEqual(entryRuleErrors(e), [], sc.name);
+    assert.deepEqual(orderErrors(sc.entries.map((e: any) => e.card)), [], sc.name);
+    let previous: { next_cursor: string | null } | null = null;
+    for (const step of sc.steps) {
+      const response = judgeList(sc.entries, sc.ordinal, step.request);
+      assert.deepEqual(response, step.response, sc.name);
+      assert.ok(check(forkSchema, "list", response), sc.name);
+      assert.equal(hexOf(response), step.responseHex, sc.name);
+      const orders = response.forks.map((f: any) => f.card.order);
+      assert.deepEqual(orders, [...orders].sort((a: number, b: number) => b - a), sc.name);
+      if (previous !== null) assert.equal(step.request.cursor, previous.next_cursor, `${sc.name}: the second request follows the first page's cursor`);
+      previous = response;
+    }
+  }
+});
+
+test("fork transport: order 0 is legal, no cursor names it, and the page ending at order 1 hands on to it", () => {
+  const sc = fork.transport.listScenarios.find((x: any) => x.name === "order_zero_is_legal_but_no_cursor_names_it");
+  assert.deepEqual(sc.steps.map((s: any) => s.response.next_cursor), ["c1", null]);
+  assert.deepEqual(sc.steps[1].response.forks.map((f: any) => f.card.order), [0]);
+  assert.equal(check(forkSchema, "cursor", "c0"), false);
+});
+
+test("fork transport: a page may stop short of limit, and a first entry past the budget is fork_too_large (422) continued below its order", () => {
+  const sc = fork.transport.listShortPages;
+  assert.deepEqual(sc.map((x: any) => x.name), ["a_short_page_resumes_below_its_last_entry", "a_first_entry_past_the_budget_is_fork_too_large_and_the_client_continues_below_its_order", "fork_too_large_on_order_zero_leaves_nothing_below"]);
+  assert.ok((forkSchema.$defs.refusal.properties.code as { enum: string[] }).enum.includes("fork_too_large"));
+  const covered: number[] = [];
+  for (const s of sc) {
+    let last: string | null | undefined = undefined;
+    s.steps.forEach((step: any, i: number) => {
+      if (last !== undefined) assert.equal(step.request.cursor, last, `${s.name}: the step follows the cursor or the refused order`);
+      const full = judgeList(s.entries, s.ordinal, step.request);
+      if (step.response !== undefined) {
+        const r = step.response as any, n = r.forks.length;
+        assert.ok(check(forkSchema, "list", r), s.name);
+        assert.equal(hexOf(r), step.responseHex, s.name);
+        assert.deepEqual(r.forks, full.forks.slice(0, n), `${s.name}: a prefix of the unbudgeted page`);
+        assert.ok(n >= 1, s.name);
+        assert.equal(r.next_cursor, full.next_cursor !== null || n < full.forks.length ? `c${r.forks[n - 1].card.order}` : null, s.name);
+        assert.equal(r.stamp, full.stamp); assert.equal(r.open_count, full.open_count); assert.equal(r.recorded_count, full.recorded_count);
+        covered.push(...r.forks.map((f: any) => f.card.order));
+        last = r.next_cursor;
+      } else {
+        const r = step.refusal, first = full.forks[0].card as any;
+        assert.ok(check(forkSchema, "refusal", r), s.name);
+        assert.equal(hexOf(r), step.refusalHex, s.name);
+        assert.equal(r.code, "fork_too_large");
+        assert.equal(step.httpStatus, 422);
+        assert.equal(step.fork_id, first.fork_id); assert.equal(step.order, first.order);
+        assert.ok(r.error.includes(first.fork_id) && new RegExp(`\\b${first.order}\\b`).test(r.error.replace(first.fork_id, "")), `${s.name}: the text names the fork id and the order`);
+        assert.ok(step.request.limit >= 1, "limit 0 never refuses");
+        if (first.order >= 1) { assert.ok(i + 1 < s.steps.length, s.name); last = `c${first.order}`; assert.ok(check(forkSchema, "cursor", last)); }
+        else { assert.equal(i, s.steps.length - 1, `${s.name}: order 0 is the end`); assert.equal(check(forkSchema, "cursor", "c0"), false); last = undefined; }
+      }
+    });
+  }
+  assert.deepEqual(sc[0].steps.map((x: any) => x.response.next_cursor), ["c2", null]);
+  assert.deepEqual(sc[0].steps.map((x: any) => x.response.forks.length), [2, 2]);
+  assert.deepEqual([sc[1].steps[0].order, sc[2].steps[1].order], [3, 0]);
+  assert.deepEqual(covered, [3, 2, 1, 0, 2, 1, 0, 1]);
+});
+
+test("fork transport: a read whose entry is past the cap is fork_too_large (422), named by fork id alone", () => {
+  const doorStatus = fork.doorRefusals.find((r: any) => r.name === "fork_too_large").httpStatus;
+  assert.equal(fork.transport.readTooLarge.length, 1);
+  for (const c of fork.transport.readTooLarge) {
+    const held = c.entries.find((e: any) => e.card.fork_id === c.request.fork_id);
+    assert.ok(held !== undefined && check(forkSchema, "readRequest", c.request), c.name);
+    assert.ok(check(forkSchema, "refusal", c.refusal), c.name);
+    assert.equal(c.refusal.code, "fork_too_large");
+    assert.ok(c.refusal.error.includes(held.card.fork_id), "the text names the fork id");
+    assert.equal(hexOf(c.refusal), c.refusalHex, c.name);
+    assert.equal(c.httpStatus, 422); assert.equal(c.httpStatus, doorStatus);
+  }
+});
+
+test("fork transport: a stale answer whose card re-read is past the cap is the read-form fork_too_large (422), over a stored Refused(stale_fork)", () => {
+  assert.equal(fork.transport.answerTooLarge.length, 1);
+  const read = fork.transport.readTooLarge[0];
+  for (const c of fork.transport.answerTooLarge) {
+    const held = c.entries.find((e: any) => e.card.fork_id === c.request.fork_id);
+    assert.ok(held !== undefined && check(forkSchema, "answerRequest", c.request), c.name);
+    assert.notEqual(c.request.options_hash, held.card.options_hash, "the card moved: the answer is stale");
+    assert.ok(check(forkSchema, "refusal", c.refusal), c.name);
+    assert.equal(c.refusal.code, "fork_too_large");
+    assert.ok(c.refusal.error.includes(held.card.fork_id), "the text names the fork id");
+    assert.equal(hexOf(c.refusal), c.refusalHex, c.name);
+    assert.equal(c.refusal.code, read.refusal.code, "the same refusal as the read form");
+    assert.equal(c.httpStatus, 422); assert.equal(c.httpStatus, fork.doorRefusals.find((r: any) => r.name === "fork_too_large").httpStatus);
+    assert.equal(c.outcome, "Refused"); assert.equal(c.code, "stale_fork"); assert.equal(c.counted, false);
+  }
+});
+
+test("fork transport: a door request_id_conflict is a fault on read and list (503 unavailable) and a refusal only on the answer", () => {
+  assert.deepEqual(fork.transport.doorFaults.map((c: any) => c.route), ["read", "list", "answer"]);
+  for (const c of fork.transport.doorFaults) {
+    const source = c.route === "answer" ? fork.doorRefusals.find((r: any) => r.name === c.doorCode) : fork.unavailable[0];
+    assert.equal(c.responseHex, source.messagePackHex, c.name);
+    assert.equal(hexOf(c.response), c.responseHex, c.name);
+    assert.equal(c.httpStatus, source.httpStatus, c.name);
+    assert.ok(check(forkSchema, c.route === "answer" ? "refusal" : "unavailable", c.response), c.name);
+  }
+});
+
+test("fork transport: auth is bearer, then audience, then scope, and a votes token touches nothing", () => {
+  const codes = (forkSchema.$defs.refusal.properties.code as { enum: string[] }).enum;
+  const seen = new Set<string>();
+  for (const c of fork.transport.authCases) {
+    const got = authJudge(c.route, c.token, c.huginn_down);
+    assert.equal(got, c.expect, c.name);
+    if (got !== "ok" && got !== "unavailable") assert.ok(codes.includes(got), c.name);
+    seen.add(`${c.route}:${got}`);
+  }
+  for (const want of ["list:insufficient_scope", "answer:insufficient_scope", "read:forbidden", "list:unavailable", "read:unavailable", "answer:unavailable", "read:unauthenticated", "answer:ok"]) assert.ok(seen.has(want), want);
+});

scripts/gen-governance-vectors.py

@@ -0,0 +1,660 @@
+#!/usr/bin/env python3
+"""Writes contracts/cultnet/governance/{vote-api,fork-card}-vectors.json.
+
+The bytes are spec-authored with msgpack-python (minimal ints, str8 only past 31 bytes, map keys in the order written here);
+each runtime's conformance test re-encodes the `message` and must produce the same hex. Run: python3 scripts/gen-governance-vectors.py
+Needs: pip install msgpack.
+"""
+import hashlib, json, pathlib, unicodedata
+import msgpack
+
+OUT = pathlib.Path(__file__).resolve().parent.parent / "contracts" / "cultnet" / "governance"
+def hx(m): return msgpack.packb(m, use_bin_type=True).hex().upper()
+def sha(b): return hashlib.sha256(b).hexdigest()
+
+M1 = "5b1c2e9a-3f4d-4c8e-9a61-0d7e2f4b8c13"
+M2 = "a7d3f0c2-6b15-4e29-8f3a-91c4d5e6f708"
+V1 = "0c9f6a4e-7d2b-4a35-b8e1-3f5a6c7d8e90"
+T0 = "2026-11-12T18:00:00Z"; T1 = "2026-11-15T18:00:00Z"; T2 = "2026-11-18T18:00:00Z"
+SALT = "d41d8cd98f00b204e9800998ecf8427e5f1c0a7b3e92d6a48b15c7f0e3a9d2b6"
+
+# ---------- vote API ----------
+def commitment_bytes(motion, voter, persona, rnd, candidate, reason, salt):
+    return f"gamecult.sealed_ballot.v0\n{motion}\n{voter}\n{persona}\n{rnd}\n{candidate}\n{reason}\n{salt}".encode("utf-8")
+
+def ballot(motion=M1, rnd=1, candidate="Adopt the ledger", reason="It keeps the books honest.", salt=SALT, persona=""):
+    return {"schema": "gamecult.sealed_ballot.v0", "motionId": motion, "round": rnd, "candidate": candidate,
+            "reason": reason, "salt": salt, "persona": persona}
+def digest(b, voter=V1):
+    return sha(commitment_bytes(b["motionId"], voter, b["persona"], b["round"], b["candidate"], b["reason"], b["salt"]))
+
+B_MEMBER = ballot()
+B_PERSONA = ballot(persona="libby", candidate="Defer to round two", reason="The sealed window is too short to weigh both.")
+C_MEMBER = digest(B_MEMBER); C_PERSONA = digest(B_PERSONA)
+
+def receipt(commitment, revision=1, revealed=False, motion=M1):
+    return {"schemaVersion": "gamecult.vote.receipt.v0", "motionId": motion, "voterUserAccountId": V1,
+            "commitment": commitment, "revision": revision, "committedAtUtc": "2026-11-12T19:04:11.1234567Z", "revealed": revealed}
+def motion(phase, your=None, mid=M1, high=False):
+    return {"schemaVersion": "gamecult.vote.motion.v0", "id": mid, "title": "Ledger or lantern", "summary": "Pick one.",
+            "round": 1, "priorMotionId": None, "ballotSchema": "gamecult.sealed_ballot.v0", "phase": phase,
+            "candidates": ["Adopt the ledger", "Defer to round two"], "commitClosesAtUtc": T0, "closesAtUtc": T1, "highStakes": high,
+            "yourVoterId": V1, "yourCommitment": your, "announcement": None}
+def cast_commit(c, motion=M1): return {"schemaVersion": "gamecult.vote.cast.v0", "motionId": motion, "verb": "commit", "commitment": c, "ballot": None}
+def cast_reveal(b): return {"schemaVersion": "gamecult.vote.cast.v0", "motionId": b["motionId"], "verb": "reveal", "commitment": None, "ballot": b}
+def refusal(code, error, retry=None): return {"schemaVersion": "gamecult.vote.refusal.v0", "code": code, "error": error, "retryAfterSeconds": retry}
+def item(i, title, phase, high=False): return {"id": i, "title": title, "round": 1, "phase": phase, "commitClosesAtUtc": T0, "closesAtUtc": T1, "highStakes": high}
+
+valid = [
+ ("motion_list_request_all", "motionListRequest", {"schemaVersion": "gamecult.vote.motion_list_request.v0", "phase": None}),
+ ("motion_list_request_reveal", "motionListRequest", {"schemaVersion": "gamecult.vote.motion_list_request.v0", "phase": "Reveal"}),
+ ("motion_list_two", "motionList", {"schemaVersion": "gamecult.vote.motion_list.v0", "motions": [item(M1, "Ledger or lantern", "Commit"), item(M2, "Second thoughts", "Closed", True)]}),
+ ("motion_list_empty", "motionList", {"schemaVersion": "gamecult.vote.motion_list.v0", "motions": []}),
+ ("motion_read_request", "motionReadRequest", {"schemaVersion": "gamecult.vote.motion_read_request.v0", "motionId": M1}),
+ ("motion_commit_phase_no_receipt", "motion", motion("Commit")),
+ ("motion_high_stakes_commit_phase", "motion", motion("Commit", high=True)),
+ ("motion_reveal_phase_committed", "motion", motion("Reveal", receipt(C_MEMBER))),
+ ("motion_closed_revealed", "motion", motion("Closed", receipt(C_MEMBER, 2, True))),
+ ("cast_reveal_reason_140_astral_280_units", "cast", cast_reveal(ballot(reason="\U0001F600" * 140))),
+ ("cast_commit", "cast", cast_commit(C_MEMBER)),
+ ("cast_reveal_member", "cast", cast_reveal(B_MEMBER)),
+ ("cast_reveal_persona", "cast", cast_reveal(B_PERSONA)),
+ ("receipt_committed", "receipt", receipt(C_MEMBER)),
+ ("receipt_revealed_echoes_no_ballot", "receipt", receipt(C_MEMBER, 2, True)),
+]
+refusals = [
+ ("unauthenticated", 401, "no bearer, or one Heimdall does not know", refusal("unauthenticated", "A bearer token is required.")),
+ ("reauthentication_required", 401, "a commit on a high-stakes motion with no sign-in fresh enough (Bifrost PR #37, D2); the voter signs in again at the top level and retries", refusal("reauthentication_required", "Sign in again to commit on this motion.")),
+ ("forbidden", 403, "authenticated, not an Active member, or a Mind key used on a motion route it may not call", refusal("forbidden", "Only Active members may vote.")),
+ ("not_found", 404, "unknown motion id, a standard (non-sealed) motion id, or reveal without a prior commit", refusal("not_found", "No such sealed-ballot motion.")),
+ ("wrong_phase", 409, "commit outside Commit, reveal outside Reveal", refusal("wrong_phase", "The commit window is not open.")),
+ ("contended", 409, "reveal raced the close fence; send it again", refusal("contended", "The reveal is contended; send it again.")),
+ ("invalid", 400, "body fails vote-api.schema.json or an in-document rule (untrimmed candidate or reason, candidate not in the motion, round or motionId mismatch, persona wrong for the credential)", refusal("invalid", "The cast does not satisfy gamecult.vote.cast.v0.")),
+ ("commitment_mismatch", 400, "reveal whose canonical bytes do not hash to the stored commitment", refusal("commitment_mismatch", "The ballot does not match the stored commitment.")),
+ ("payload_too_large", 413, "body over 4096 bytes", refusal("payload_too_large", "The body exceeds 4096 bytes.")),
+ ("held", 503, "the Ratatoskr voting brake is set (Bifrost PR #37, D5): no cast is read or stored while it is", refusal("held", "Voting is held.")),
+ ("rate_limited", 429, "more than the per-account cast rate; Retry-After mirrors retryAfterSeconds", refusal("rate_limited", "Too many casts.", 30)),
+]
+def tweak(d, **kw):
+    d = json.loads(json.dumps(d)); 
+    for k, v in kw.items():
+        if k.startswith("b_"): d["ballot"][k[2:]] = v
+        else: d[k] = v
+    return d
+rev = cast_reveal(B_MEMBER)
+invalid = [
+ ("cast_commit_carries_a_ballot", "cast", tweak(cast_commit(C_MEMBER), ballot=B_MEMBER), "a commit names exactly the commitment; a ballot beside it would put content on the wire before the reveal"),
+ ("cast_reveal_carries_a_commitment", "cast", tweak(rev, commitment=C_MEMBER), "a reveal names exactly the ballot"),
+ ("cast_commit_without_commitment", "cast", tweak(cast_commit(C_MEMBER), commitment=None), "commit needs its hash"),
+ ("cast_verb_unknown", "cast", tweak(rev, verb="recast"), "verb is commit or reveal"),
+ ("cast_commitment_uppercase", "cast", cast_commit(C_MEMBER.upper()), "commitment is lowercase hex"),
+ ("cast_commitment_63_chars", "cast", cast_commit(C_MEMBER[:63]), "commitment is 64 hex characters"),
+ ("cast_unknown_key", "cast", tweak(cast_commit(C_MEMBER), note="hi"), "closed document"),
+ ("cast_motion_id_uppercase", "cast", cast_commit(C_MEMBER, M1.upper()), "ids are lowercase D-format uuids"),
+ ("ballot_reason_empty", "cast", tweak(rev, b_reason=""), "reason is 1 to 280 characters"),
+ ("ballot_reason_281", "cast", tweak(rev, b_reason="x" * 281), "reason is at most 280 characters"),
+ ("ballot_reason_141_astral_282_units", "cast", tweak(rev, b_reason="\U0001F600" * 141), "reason is at most 280 UTF-16 code units (vote-api.md); the schema counts code points and accepts this, so a rule refuses it"),
+ ("ballot_reason_multiline", "cast", tweak(rev, b_reason="one\ntwo"), "reason is a single line"),
+ ("ballot_reason_leading_space", "cast", tweak(rev, b_reason=" because"), "the contract refuses untrimmed text; it never trims for the sender, so the hashed bytes are the sent bytes"),
+ ("ballot_candidate_trailing_nbsp", "cast", tweak(rev, b_candidate="Adopt the ledger "), "NO-BREAK SPACE is White_Space; trimming is judged by the same list as write-receipt Required fields"),
+ ("ballot_salt_31_hex", "cast", tweak(rev, b_salt=SALT[:31]), "salt is 32 to 128 lowercase hex characters"),
+ ("ballot_salt_uppercase", "cast", tweak(rev, b_salt=SALT.upper()), "salt is lowercase hex"),
+ ("ballot_schema_wrong", "cast", tweak(rev, b_schema="gamecult.sealed_ballot.v1"), "ballot schema is gamecult.sealed_ballot.v0"),
+ ("ballot_persona_with_space", "cast", tweak(rev, b_persona="my mind"), "persona is printable ASCII without space, at most 64"),
+ ("ballot_round_zero", "cast", tweak(rev, b_round=0), "rounds start at 1"),
+ ("receipt_echoes_candidate", "receipt", dict(receipt(C_MEMBER, 2, True), candidate="Adopt the ledger"), "sealed casts never echo ballot content; the receipt is closed"),
+ ("receipt_echoes_salt", "receipt", dict(receipt(C_MEMBER, 2, True), salt=SALT), "the salt never comes back before close"),
+ ("receipt_revision_zero", "receipt", receipt(C_MEMBER, 0), "revision starts at 1"),
+ ("receipt_time_without_zone", "receipt", dict(receipt(C_MEMBER), committedAtUtc="2026-11-12T19:04:11"), "instants are UTC with a Z"),
+ ("motion_one_candidate", "motion", dict(motion("Commit"), candidates=["Only"]), "a motion has two or more candidates"),
+ ("motion_phase_unknown", "motion", dict(motion("Commit"), phase="Open"), "phase is Commit, Reveal or Closed"),
+ ("motion_high_stakes_not_boolean", "motion", dict(motion("Commit"), highStakes="yes"), "highStakes is a boolean, fixed at open"),
+ ("motion_without_high_stakes", "motion", {k: v for k, v in motion("Commit").items() if k != "highStakes"}, "map-mode writes every key; a motion states whether it is high-stakes"),
+ ("motion_list_item_without_high_stakes", "motionListItem", {k: v for k, v in item(M1, "x", "Commit").items() if k != "highStakes"}, "every list item states whether the motion is high-stakes"),
+ ("motion_leaks_tally", "motion", dict(motion("Reveal"), tally=[]), "mid-vote a client sees no tallies; the document is closed"),
+ ("motion_list_item_without_phase", "motionList", {"schemaVersion": "gamecult.vote.motion_list.v0", "motions": [{k: v for k, v in item(M1, "x", "Commit").items() if k != "phase"}]}, "every item names its phase"),
+ ("refusal_code_unknown", "refusal", refusal("teapot", "no"), "the code set is closed"),
+ ("refusal_without_error", "refusal", dict(refusal("invalid", "x"), error=""), "error is non-empty"),
+]
+pairs = [
+ {"name": "member_commit_matches_reveal", "voterUserAccountId": V1, "commit": cast_commit(C_MEMBER), "reveal": cast_reveal(B_MEMBER), "matches": True},
+ {"name": "persona_commit_matches_reveal", "voterUserAccountId": V1, "commit": cast_commit(C_PERSONA), "reveal": cast_reveal(B_PERSONA), "matches": True},
+ {"name": "reveal_with_changed_reason_does_not_match", "voterUserAccountId": V1, "commit": cast_commit(C_MEMBER), "reveal": cast_reveal(ballot(reason="It keeps the books honest!")), "matches": False, "refusal": "commitment_mismatch"},
+ {"name": "reveal_under_another_voter_does_not_match", "voterUserAccountId": M2, "commit": cast_commit(C_MEMBER), "reveal": cast_reveal(B_MEMBER), "matches": False, "refusal": "commitment_mismatch"},
+ {"name": "persona_dropped_does_not_match", "voterUserAccountId": V1, "commit": cast_commit(C_PERSONA), "reveal": cast_reveal(ballot(persona="", candidate=B_PERSONA["candidate"], reason=B_PERSONA["reason"])), "matches": False, "refusal": "commitment_mismatch"},
+]
+commitments = []
+for name, b, voter in [("member", B_MEMBER, V1), ("persona", B_PERSONA, V1), ("non_ascii", ballot(candidate="Café ☕", reason="naïve – but fine"), V1),
+                       ("decomposed_e_is_another_ballot", ballot(candidate="Café ☕", reason="naïve – but fine"), V1)]:
+    cb = commitment_bytes(b["motionId"], voter, b["persona"], b["round"], b["candidate"], b["reason"], b["salt"])
+    commitments.append({"name": name, "voterUserAccountId": voter, "ballot": b, "canonicalHex": cb.hex().upper(), "sha256": sha(cb)})
+
+vote = {
+  "provenance": "Spec-authored with msgpack-python (scripts/gen-governance-vectors.py); every runtime re-encodes `message` and must match messagePackHex. Commitment hashes follow vote-api.md 'Commitment'.",
+  "commitment": commitments,
+  "valid": [{"name": n, "def": d, "message": m, "messagePackHex": hx(m)} for n, d, m in valid],
+  "invalid": [{"name": n, "def": d, "message": m, "why": w, "messagePackHex": hx(m)} for n, d, m, w in invalid],
+  "pairs": pairs,
+  "refusals": [{"name": n, "httpStatus": s, "trigger": t, "message": m, "messagePackHex": hx(m)} for n, s, t, m in refusals],
+}
+(OUT / "vote-api-vectors.json").write_text(json.dumps(vote, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+# ---------- fork card ----------
+# Rule source: /opt/commons/handoff/fork-desk-answer-binding-20261110.md (Heimdall), sections 1.1 to 1.5 and 1.3a. The seven hash
+# vectors A to G below are that file's, with its expected digests asserted.
+def jstr(x):
+    out = ['"']
+    for ch in x:
+        o = ord(ch)
+        if ch == '"': out.append('\\"')
+        elif ch == "\\": out.append("\\\\")
+        elif ch == "\b": out.append("\\b")
+        elif ch == "\t": out.append("\\t")
+        elif ch == "\n": out.append("\\n")
+        elif ch == "\f": out.append("\\f")
+        elif ch == "\r": out.append("\\r")
+        elif o < 0x20: out.append("\\u%04x" % o)
+        else: out.append(ch)
+    out.append('"')
+    return "".join(out)
+def nfc(x): return unicodedata.normalize("NFC", x)
+def canonical_json(title, context, options, recommendation, depends):
+    """RFC 8785 over {context, depends, options:[{id,text}], recommendation, title} after NFC on every string; keys sorted; no numbers. (None is accepted only to check Heimdall's null digests.)"""
+    opts = ",".join('{"id":%s,"text":%s}' % (jstr(nfc(o["id"])), jstr(nfc(o["text"]))) for o in options)
+    dep = ",".join(jstr(nfc(d)) for d in depends)
+    rec = "null" if recommendation is None else jstr(nfc(recommendation))
+    return ('{"context":%s,"depends":[%s],"options":[%s],"recommendation":%s,"title":%s}' % (jstr(nfc(context)), dep, opts, rec, jstr(nfc(title)))).encode("utf-8")
+
+OP = "e0d1c2b3-a495-4687-8879-6a5b4c3d2e1f"; ST = "11111111-2222-4333-8444-555555555555"; HM = "9f8e7d6c-5b4a-4392-8170-0f1e2d3c4b5a"
+FID = "gamecult-chat:question:slot-mark-consent"
+OPT = [{"id": "yes", "text": "Share it."}, {"id": "no", "text": "Keep it local."}]
+DEP = ["gamecult-chat:question:file-zone-audience"]
+def chash(c): return sha(canonical_json(c["title"], c["context"], c["options"], c["recommendation"], c["depends"]))
+def card(**kw):
+    c = {"schemaVersion": "gamecult.fork.card.v0", "fork_id": FID, "title": "Slot mark consent", "context": "Should a slot mark be shared?",
+         "options": OPT, "recommendation": "no", "depends": DEP, "leans": None, "flag": None,
+         "raised_in": {"kind": "CutSpec", "id": "cultlib-gaps:cut_spec:cut-slot-tolerance.r4"}, "deciders": [OP],
+         "status": "open", "ruling": None, "ruled_from": [], "order": 3, "options_hash": ""}
+    c.update(kw); c["options_hash"] = chash(c); return c
+CARD = card(); H = CARD["options_hash"]
+
+hashes = []
+CLAIMED = {"A": "7d95fc87d532420611fe415c1def27a3447617bb68235f46e3af130aea361c48", "B": "14b8ffbdb61106dbc06f69f3fc8e2072af7a205d766e4cc040e89733013d54dc",
+           "C": "ac67b41539f869f6203ac0908819df046e4328b27795743a919bd4ab390596b5", "D": "71d5c413478ad06aaa1cbdd9e91c53f0cb4cef1dbd4c51bf3d473bccc6a5a272",
+           "E": "71d5c413478ad06aaa1cbdd9e91c53f0cb4cef1dbd4c51bf3d473bccc6a5a272", "F": "fb53aa3a9f7e74029f755d774064eedd240ab90d8fc64723f97c31b3d2846d40",
+           "G": "f856edce121db4121b5f1af400b1c471ebbfa6579a042aca9a34ae31c15f5c86"}
+def hv(name, c, heimdall=None):
+    b = canonical_json(c["title"], c["context"], c["options"], c["recommendation"], c["depends"])
+    if heimdall: print("heimdall", heimdall, "same" if CLAIMED[heimdall] == sha(b) else f"DIFFERS mine={sha(b)} his={CLAIMED[heimdall]}")
+    hashes.append({"name": name, "heimdall": heimdall, "title": c["title"], "context": c["context"], "options": c["options"],
+                   "recommendation": c["recommendation"], "depends": c["depends"], "canonical": b.decode("utf-8"),
+                   "canonicalHex": b.hex().upper(), "sha256": sha(b)})
+CD = dict(title="Caf\u00e9 \u201cdesk\u201d", context="Line one\nLine two \u2014 \U0001F600", options=[{"id": "a", "text": "x"}, {"id": "b", "text": "y"}], recommendation="a", depends=[])
+hv("heimdall_A_five_members", CARD, "A")
+hv("heimdall_B_recommendation_changed", card(recommendation="yes"), "B")
+hv("heimdall_C_option_order_changed", card(options=[OPT[1], OPT[0]]), "C")
+hv("heimdall_D_nfc_escapes_astral", card(**CD), "D")
+hv("heimdall_E_decomposed_equals_D", card(**dict(CD, title="Cafe\u0301 \u201cdesk\u201d")), "E")
+hv("heimdall_F_option_id_changed", card(options=[{"id": "share", "text": "Share it."}, OPT[1]]), "F")
+hv("heimdall_G_depends_emptied", card(depends=[]), "G")
+hv("option_text_changed", card(options=[dict(OPT[0], text="Share it!"), OPT[1]]))
+hv("title_changed", card(title="Slot mark consent?"))
+hv("context_changed", card(context="Should slot marks be shared?"))
+hv("depends_order_changed", card(depends=DEP + ["x:question:y"]))
+hv("depends_order_changed_reversed", card(depends=["x:question:y"] + DEP))
+hv("hidden_members_do_not_move_it", card(leans="yes", flag="provisional", deciders=[OP, HM], status="closed", ruling="r:1", ruled_from=["rc-1"], order=9, raised_in=None, fork_id="other:question:id"))
+hv("control_characters_and_markup_are_escaped_minimally", card(title='q " b \\ t \t n \n bell \u0007 del \u007f', context="</script> \u2028 &"))
+hv("astral_option_id_and_text", card(options=[{"id": "\U0001F600", "text": "\U0001D11E"}, OPT[1]]))
+assert [h["sha256"] for h in hashes if h["heimdall"] == "D"] == [h["sha256"] for h in hashes if h["heimdall"] == "E"]
+assert len({h["sha256"] for h in hashes if h["name"] in ("heimdall_A_five_members", "hidden_members_do_not_move_it")}) == 1
+
+RID = [0]
+def next_rid():
+    RID[0] += 1; n = RID[0]
+    return f"{n:08x}-0000-4000-8000-{n:012x}"
+def body(choice=None, note=None, h=None, at="2026-11-12T19:02:00Z", fork=FID, retracts=None, answer="auto", rid=None):
+    a = {"choice": choice, "note": note} if answer == "auto" else answer
+    if answer == "auto" and choice is None and note is None: a = None
+    return {"schemaVersion": "gamecult.fork.answer_request.v0", "fork_id": fork, "options_hash": h or H, "answer": a,
+            "retracted": retracts is not None, "retracts": retracts, "answered_at": at, "request_id": rid or next_rid()}
+def retraction(target, **kw): return body(retracts=target, **kw)
+NOTE = "Keep it local: a slot mark is the author's call, and sharing it is a separate act."
+def srv(aid, who, at, auth="Operator"): return {"answer_id": aid, "answerer": who, "authority": auth, "received_at": at}
+TAIL = {"unauthenticated": "a verified session is required", "body_forbidden_field": "answerer and authority are set by the receiver", "body_unknown_field": "the body is a closed shape",
+        "body_invalid": "the body does not satisfy gamecult.fork.answer_request.v0", "fork_unknown": "no such fork",
+        "insufficient_scope": "the token lacks the scope this route needs", "forbidden": "only Active members may use the desk", "request_id_conflict": "this request_id was used for a different body", "request_invalid": "the request does not satisfy its document"}
+DOOR = set(TAIL)
+def refusal_doc(code): return {"schemaVersion": "gamecult.fork.refusal.v0", "code": code, "error": f"{code}: {TAIL[code]}"}
+def unavailable_doc(retry=30): return {"schemaVersion": "gamecult.fork.unavailable.v0", "code": "unavailable", "error": "unavailable: the outcome is not confirmed, try again with the same request_id", "retryAfterSeconds": retry}
+def future(a, r):
+    import datetime as dt
+    p = lambda x: dt.datetime.fromisoformat(x.replace("Z", "+00:00"))
+    return (p(a) - p(r)).total_seconds() > 300
+def da(outcome, link, code, b, server):
+    a = b["answer"] or {"choice": None, "note": None}
+    return {"schemaVersion": "gamecult.desk_answer.v0", "answer_id": server["answer_id"], "fork_id": b["fork_id"], "outcome": outcome,
+            "of": link if outcome == "Revision" else None, "retracts": link if outcome == "Retraction" else (b["retracts"] if outcome == "Refused" else None), "code": code if outcome == "Refused" else None,
+            "options_hash": b["options_hash"], "choice": a["choice"], "note": a["note"], "answered_at": b["answered_at"], "received_at": server["received_at"],
+            "claim_in_future": future(b["answered_at"], server["received_at"]), "answerer": server["answerer"], "authority": server["authority"], "request_id": b["request_id"]}
+def result(answer, c=None): return {"schemaVersion": "gamecult.fork.answer_result.v0", "answer": answer, "card": c, "counted_answer_id": None}   # sc() fills counted_answer_id
+def record(counted, answers, h=H, fork=FID): return {"schemaVersion": "gamecult.fork.record.v0", "fork_id": fork, "options_hash": h, "counted_answer_id": counted, "answers": answers}
+T = lambda m, sec=5: f"2026-11-12T19:{m:02d}:{sec:02d}Z"
+def step(kind, body_=None, server=None, response=None, **kw):
+    d = {"kind": kind, "body": body_, "server": server, "response": response}; d.update(kw); return d
+def ok(b, server, outcome, of):
+    a = da(outcome, of, None, b, server); return step("answer", b, server, result(a)), a
+def rf(b, server, code, c=None):
+    a = da("Refused", None, code, b, server); return step("answer", b, server, result(a, c)), a
+def door(b, server, code): return step("answer", b, server, refusal_doc(code)), None
+def sc(name, c, items, counted, h=None):
+    # answer_result.counted_answer_id: the counted answer after the step, derived from the answers stored so far under the card's current hash
+    steps, answers, cur = [], [], c["options_hash"]
+    def live(): return next((a["answer_id"] for a in answers if a["outcome"] in ("Counted", "Revision") and a["options_hash"] == cur
+                             and not any(r["outcome"] == "Retraction" and r["retracts"] == a["answer_id"] for r in answers)), None)
+    for i in items:
+        st = i[0] if isinstance(i, tuple) else i
+        if isinstance(i, tuple) and i[1] is not None: answers.append(i[1])
+        if st["kind"] == "card": cur = st["card"]["options_hash"]
+        if st["kind"] == "answer" and (st["response"] or {}).get("schemaVersion") == "gamecult.fork.answer_result.v0":
+            st = dict(st, response=dict(st["response"], counted_answer_id=live()))
+        steps.append(st)
+    assert live() == counted, (name, live(), counted)
+    return (name, c, steps, record(counted, answers, h or c["options_hash"]))
+
+x1 = body("no", NOTE); sx1 = srv("n1", OP, T(2))
+x2 = body("yes", "On reflection, share it.", at="2026-11-12T19:06:00Z"); sx2 = srv("n2", OP, T(6))
+y1 = body("yes", "Share it, the audience is settled.", at="2026-11-12T19:05:00Z"); sy1 = srv("n3", HM, T(5), auth="Steward")
+z1 = body("yes", "Share, please."); sz = srv("n4", ST, T(3), auth="Member")
+pick = body("no", None); words = body(None, NOTE)
+STALE_H = chash(card(recommendation="yes"))
+def stale_body(**kw): return body("no", NOTE, h=STALE_H, **kw)
+FORKC = card(status="closed", ruling="cultlib-gaps:resolution:question.slot-mark-consent.n1")
+RULED = card(status="closed", ruling="cultlib-gaps:resolution:question.slot-mark-consent.n1", ruled_from=["n1"])
+Y_CARD = card(deciders=[OP, HM])
+fork_edit = card(title="Slot mark consent (revised)"); H2 = fork_edit["options_hash"]
+RET = lambda t: retraction(t, at="2026-11-12T19:09:00Z")
+def sr(aid, who=OP, m=9, auth="Operator"): return srv(aid, who, T(m), auth)
+MATRIX = [step("matrix_event", None, None, None, matrix_kind=k, choice=c) for k, c in (("m.replace", "yes"), ("m.redaction", None), ("m.reaction", "yes"))]
+X1 = ok(x1, sx1, "Counted", None)
+REPLAY1 = (step("answer", x1, dict(sx1, answer_id="n9"), X1[0]["response"]), None)
+LOST = [(step("answer", x1, dict(sx1, door_down=True, stored=True, retry_after_seconds=30), unavailable_doc(30)), X1[1])]
+STALE_BODY = stale_body(); STALE_RF = rf(STALE_BODY, sx1, "stale_fork", c=CARD)
+OFFLIST = rf(x1, srv("n1", ST, T(2), "Member"), "not_a_decider")
+OFFLIST_REPLAY = (step("answer", x1, srv("n9", ST, T(4), "Member"), OFFLIST[0]["response"]), None)
+scen = [
+ sc("operator_answers_and_is_counted", CARD, [X1], "n1"),
+ sc("choice_alone_is_counted", CARD, [ok(pick, sx1, "Counted", None)], "n1"),
+ sc("note_alone_is_counted_a_clear_pick", CARD, [ok(words, sx1, "Counted", None)], "n1"),
+ sc("V1_answerer_in_the_body_is_refused_at_the_door_and_stores_nothing", CARD, [door(dict(x1, answerer="x"), sx1, "body_forbidden_field")], None),
+ sc("V1_authority_nested_in_answer_is_refused", CARD, [door(dict(x1, answer={"choice": "no", "note": None, "authority": "Operator"}), sx1, "body_forbidden_field")], None),
+ sc("V1_both_are_refused_not_stripped", CARD, [door(dict(x1, answerer=OP, authority="Operator"), sx1, "body_forbidden_field")], None),
+ sc("M5_a_body_naming_deciders_is_an_unknown_key_the_decider_list_is_never_the_bodys", CARD, [door(dict(x1, deciders=[ST]), sx1, "body_unknown_field")], None),
+ sc("M1_a_body_naming_a_mind_is_an_unknown_key_the_mind_is_the_routes", CARD, [door(dict(x1, mind="nibu"), sx1, "body_unknown_field")], None),
+ sc("an_unknown_key_is_refused_the_body_is_closed", CARD, [door(dict(x1, mood="happy"), sx1, "body_unknown_field")], None),
+ sc("an_answer_with_neither_choice_nor_note_is_invalid", CARD, [door(body(answer={"choice": None, "note": None}), sx1, "body_invalid")], None),
+ sc("a_non_retraction_without_an_answer_is_invalid", CARD, [door(body(answer=None), sx1, "body_invalid")], None),
+ sc("unavailable_before_huginn_stored_nothing_is_retried_into_a_Counted_answer", CARD, [step("answer", x1, dict(sx1, answer_id="n9", door_down=True, retry_after_seconds=30), unavailable_doc(30)), ok(x1, sx1, "Counted", None)], "n1"),
+ sc("unavailable_after_huginn_stored_the_retry_with_the_same_request_id_returns_the_stored_outcome", CARD, LOST + [REPLAY1], "n1"),
+ sc("a_retry_never_adds_a_Revision", CARD, [X1, REPLAY1], "n1"),
+ sc("Q1_a_replayed_stale_fork_returns_the_CURRENT_card_and_stores_nothing_new", CARD, [STALE_RF, step("card", None, None, None, card=fork_edit),
+    (step("answer", STALE_BODY, dict(sx1, answer_id="n9"), result(STALE_RF[1], fork_edit)), None)], None, H2),
+ sc("V13_only_answered_at_changed_is_request_id_conflict", CARD, [X1, door(dict(x1, answered_at="2026-11-12T19:03:00Z"), dict(sx1, answer_id="n9"), "request_id_conflict")], "n1"),
+ sc("V14_an_identical_body_from_another_account_gets_its_own_Counted_and_never_the_first_accounts_outcome", Y_CARD, [OFFLIST, ok(x1, srv("n2", HM, T(3), "Steward"), "Counted", None), OFFLIST_REPLAY], "n2"),
+ sc("V14_an_identical_body_from_another_decider_is_its_own_Revision_and_the_first_retry_still_returns_n1", Y_CARD, [X1, ok(x1, sy1, "Revision", "n1"), (step("answer", x1, dict(sx1, answer_id="n9"), X1[0]["response"]), None)], "n1"),
+ sc("V16_Q5_a_forbidden_request_binds_no_request_id", CARD, [door(x1, dict(sx1, answer_id="n9", active=False), "forbidden"), ok(x1, sx1, "Counted", None)], "n1"),
+ sc("V17_Q6_a_body_refused_at_the_door_binds_no_request_id", CARD, [door(dict(x1, mood="happy"), dict(sx1, answer_id="n9"), "body_unknown_field"), ok(x1, sx1, "Counted", None)], "n1"),
+ sc("V17_Q6_an_unknown_fork_binds_no_request_id", CARD, [door(dict(x1, fork_id="gamecult-chat:question:nope"), dict(sx1, answer_id="n9"), "fork_unknown"), ok(x1, sx1, "Counted", None)], "n1"),
+ sc("the_same_request_id_with_another_body_is_request_id_conflict", CARD, [X1, door(dict(x1, answer={"choice": "yes", "note": None}), dict(sx1, answer_id="n9"), "request_id_conflict")], "n1"),
+ sc("the_same_request_id_from_another_account_is_another_request", Y_CARD, [X1, ok(dict(y1, request_id=x1["request_id"]), sy1, "Revision", "n1")], "n1"),
+ sc("a_non_active_member_is_forbidden_before_the_body_is_read", CARD, [door(dict(x1, answerer="x"), dict(sx1, active=False), "forbidden"), door(x1, dict(sx1, active=False), "forbidden"),
+                                                                       door(dict(x1, mood="happy"), dict(sx1, active=False, door_down=True, retry_after_seconds=30), "forbidden")], None),
+ sc("no_session_is_unauthenticated", CARD, [door(x1, srv("n1", None, T(2), None), "unauthenticated")], None),
+ sc("an_unknown_fork_is_refused_at_the_door", CARD, [door(body("no", NOTE, fork="gamecult-chat:question:nope"), sx1, "fork_unknown")], None),
+ sc("V2_stale_hash_is_refused_not_counted_and_stored_as_Refused", CARD, [STALE_RF], None),
+ sc("V2_a_stale_answer_then_a_fresh_one_the_fresh_one_is_counted", CARD, [rf(stale_body(), sx1, "stale_fork", c=CARD), ok(x1, sx2, "Counted", None)], "n2"),
+ sc("V3_an_answer_off_the_decider_list_is_Refused_not_a_decider_and_stored", CARD, [rf(z1, sz, "not_a_decider")], None),
+ sc("a_non_decider_with_a_stale_hash_is_stale_first", CARD, [rf(dict(z1, options_hash=STALE_H), sz, "stale_fork", c=CARD)], None),
+ sc("V4_a_closed_fork_refuses_and_stores_the_refusal", FORKC, [rf(x1, sx1, "fork_closed")], None),
+ sc("V5_second_answer_from_one_decider_is_a_Revision_the_first_stays_counted", CARD, [X1, ok(x2, sx2, "Revision", "n1")], "n1"),
+ sc("V5_receiver_order_decides_not_answered_at", CARD, [ok(x2, srv("n1", OP, T(2)), "Counted", None), ok(x1, srv("n2", OP, T(3)), "Revision", "n1")], "n1"),
+ sc("V5_reversed_arrival_reverses_the_result", CARD, [ok(x1, srv("n1", OP, T(2)), "Counted", None), ok(x2, srv("n2", OP, T(3)), "Revision", "n1")], "n1"),
+ sc("a_second_decider_answer_is_recorded_as_a_Revision", Y_CARD, [X1, ok(y1, sy1, "Revision", "n1")], "n1"),
+ sc("a_claim_exactly_five_minutes_ahead_is_not_flagged", CARD, [ok(body("no", NOTE, at="2026-11-12T19:07:05Z"), sx1, "Counted", None)], "n1"),
+ sc("a_claim_five_minutes_and_half_a_second_ahead_is_flagged_from_the_stored_received_at", CARD, [ok(body("no", NOTE, at="2026-11-12T19:07:05.500Z"), sx1, "Counted", None)], "n1"),
+ sc("a_claim_more_than_five_minutes_ahead_is_accepted_and_flagged", CARD, [ok(body("no", NOTE, at="2026-11-12T19:09:00Z"), sx1, "Counted", None)], "n1"),
+ sc("V6_a_matrix_edit_redaction_or_reaction_changes_nothing", CARD, [X1] + MATRIX, "n1"),
+ sc("V7_a_choice_that_is_not_an_option_is_Refused_choice_invalid", CARD, [rf(body("maybe", None), sx1, "choice_invalid")], None),
+ sc("a_changed_card_stops_the_old_answers_counting_and_a_new_answer_is_counted", CARD,
+    [X1, step("card", None, None, None, card=fork_edit), ok(body("no", NOTE, h=H2), sx2, "Counted", None)], "n2", H2),
+ sc("a_changed_card_leaves_no_counted_answer_until_one_arrives", CARD, [X1, step("card", None, None, None, card=fork_edit)], None, H2),
+ sc("V8_retraction_with_an_answer_is_bad", CARD, [X1, rf(dict(retraction("n1"), answer={"choice": "no", "note": None}), sr("n9"), "bad_retraction")], "n1"),
+ sc("V8_retraction_without_retracts_is_bad", CARD, [X1, rf(dict(retraction("n1"), retracts=None), sr("n9"), "bad_retraction")], "n1"),
+ sc("V8_retracts_on_a_plain_answer_is_bad", CARD, [X1, rf(dict(x2, retracts="n1"), sr("n9"), "bad_retraction")], "n1"),
+ sc("V8_retraction_naming_an_unknown_answer_is_bad", CARD, [X1, rf(retraction("n99"), sr("n9"), "bad_retraction")], "n1"),
+ sc("V8_retraction_naming_a_Refused_answer_is_bad", CARD, [rf(stale_body(), sx1, "stale_fork", c=CARD), rf(retraction("n1"), sr("n9"), "bad_retraction")], None),
+ sc("V8_retracting_twice_is_already_retracted", CARD, [X1, ok(RET("n1"), sr("n8"), "Retraction", "n1"), rf(RET("n1"), sr("n9", m=10), "already_retracted")], None),
+ sc("V8_retraction_under_a_stale_hash_is_stale_fork", CARD, [X1, rf(retraction("n1", h=STALE_H), sr("n9"), "stale_fork", c=CARD)], "n1"),
+ sc("V9_another_decider_retracts_and_the_answer_stops_counting", Y_CARD, [X1, ok(RET("n1"), sr("n7", HM, 9, "Steward"), "Retraction", "n1")], None),
+ sc("V9_an_account_off_the_list_cannot_retract", CARD, [X1, rf(RET("n1"), sr("n6", ST, 9, "Member"), "not_a_decider")], "n1"),
+ sc("V10a_a_ruling_that_closed_the_fork_makes_a_retraction_fork_closed", CARD, [X1, step("card", None, None, None, card=RULED), rf(RET("n1"), sr("n9"), "fork_closed")], "n1"),
+ sc("V11_retracting_the_counted_answer_makes_the_next_decider_answer_counted", Y_CARD, [X1, ok(y1, sy1, "Revision", "n1"), ok(RET("n1"), sr("n8"), "Retraction", "n1")], "n3"),
+ sc("V11_retracting_an_answer_that_was_not_counted_changes_nothing", Y_CARD, [X1, ok(y1, sy1, "Revision", "n1"), ok(RET("n3"), sr("n8"), "Retraction", "n3")], "n1"),
+ sc("after_every_answer_is_retracted_a_fresh_answer_is_Counted_again", CARD, [X1, ok(RET("n1"), sr("n8"), "Retraction", "n1"), ok(x2, sx2, "Counted", None)], "n2"),
+]
+# The three illegal forms (R1) under fixed request ids (a fresh next_rid() here would move every later vector). A and C differ only in `retracted`.
+IL_A = dict(retraction("n1", rid="0000a001-0000-4000-8000-00000000a001"), answer={"choice": "no", "note": None})   # a retraction carrying an answer
+IL_B = dict(retraction("n1", rid="0000b001-0000-4000-8000-00000000b001"), retracts=None)                           # a retraction naming no target
+IL_C = dict(body("no", None, rid="0000a001-0000-4000-8000-00000000a001"), retracts="n1")                          # a plain answer carrying a target
+assert {k: v for k, v in IL_A.items() if k != "retracted"} == {k: v for k, v in IL_C.items() if k != "retracted"} and IL_A["retracted"] and not IL_C["retracted"]
+def replayed(first, server): return (step("answer", first[0]["body"], dict(server, answer_id="n9"), first[0]["response"]), None)
+for _n, _f in (("a_retraction_with_an_answer", IL_A), ("a_retraction_with_no_target", IL_B), ("a_plain_answer_with_a_target", IL_C)):
+    _r = rf(_f, sr("n2"), "bad_retraction")
+    scen.append(sc(f"R1_{_n}_is_a_stored_bad_retraction_and_a_retry_replays_it", CARD, [X1, _r, replayed(_r, sr("n2"))], "n1"))
+scen += [
+ sc("a_replay_returns_the_counted_answer_id_current_at_the_retry_not_the_one_stored", CARD, [X1, ok(RET("n1"), sr("n8"), "Retraction", "n1"), REPLAY1], None),
+ sc("R1_retracted_true_with_an_answer_and_no_target_is_a_stored_bad_retraction", CARD, [X1, rf(dict(IL_A, retracts=None), sr("n2"), "bad_retraction")], "n1"),
+ sc("R1_retracted_true_then_false_under_one_request_id_is_request_id_conflict", CARD, [X1, rf(IL_A, sr("n2"), "bad_retraction"), door(IL_C, sr("n9"), "request_id_conflict")], "n1"),
+ sc("R1_retracted_false_then_true_under_one_request_id_is_request_id_conflict", CARD, [X1, rf(IL_C, sr("n2"), "bad_retraction"), door(IL_A, sr("n9"), "request_id_conflict")], "n1"),
+ sc("R1_a_target_less_retraction_with_retracted_flipped_is_body_invalid_before_any_request_id_lookup", CARD, [X1, rf(IL_B, sr("n2"), "bad_retraction"), door(dict(IL_B, retracted=False), sr("n9"), "body_invalid")], "n1"),
+]
+REASON_CODES = ["stale_fork", "not_a_decider", "fork_closed", "choice_invalid", "bad_retraction", "already_retracted"]
+HTTP = {"unauthenticated": 401, "body_forbidden_field": 400, "body_unknown_field": 400, "body_invalid": 400, "fork_unknown": 404, "insufficient_scope": 403, "forbidden": 403, "request_id_conflict": 409, "request_invalid": 400, "fork_too_large": 422,
+        "stale_fork": 409, "not_a_decider": 403, "fork_closed": 409, "choice_invalid": 400, "bad_retraction": 400, "already_retracted": 409}
+STORED_REFUSALS = []
+for reason in REASON_CODES:
+    a = da("Refused", None, reason, x1, sx1)
+    STORED_REFUSALS.append({"name": reason, "httpStatus": HTTP[reason], "message": result(a, CARD if reason == "stale_fork" else None)})
+# ruling citation: authority Operator must cite a Counted answer record whose answerer holds Operator authority
+CNT = da("Counted", None, None, x1, sx1); REV = da("Revision", "n1", None, x2, sx2)
+REF = da("Refused", None, "fork_closed", x1, srv("n5", OP, T(7))); NONOP = da("Counted", None, None, z1, sz)
+def cite(authority, ans, ruling="cultlib-gaps:resolution:question.slot-mark-consent.n1"):
+    return {"schemaVersion": "gamecult.fork.ruling_cite.v0", "ruling_id": ruling, "authority": authority, "answer_id": ans}
+cites = [
+ {"name": "operator_cites_a_counted_operator_answer", "answers": [CNT], "message": cite("Operator", "n1"), "admit": True},
+ {"name": "operator_cites_nothing", "answers": [CNT], "message": cite("Operator", None), "admit": False},
+ {"name": "operator_cites_a_revision", "answers": [CNT, REV], "message": cite("Operator", "n2"), "admit": False},
+ {"name": "operator_cites_a_refused_answer", "answers": [REF], "message": cite("Operator", "n5"), "admit": False},
+ {"name": "operator_cites_a_counted_answer_by_a_non_operator", "answers": [NONOP], "message": cite("Operator", "n4"), "admit": False},
+ {"name": "operator_cites_an_answer_that_does_not_exist", "answers": [CNT], "message": cite("Operator", "n99"), "admit": False},
+ {"name": "steward_needs_no_citation", "answers": [], "message": cite("Steward", None), "admit": True},
+]
+for cz in cites: cz["messagePackHex"] = hx(cz["message"])
+# ---------- transport: list, read, auth ----------
+def fcard(n, status="open", **kw):
+    c = card(fork_id=f"gamecult-chat:question:q{n}", title=f"Fork {n}", order=n, status=status, **kw)
+    return c
+def fbody(c, choice, aid_note):
+    return body(choice, aid_note, h=c["options_hash"], fork=c["fork_id"])
+def fentry(c, answers=(), counted=None):
+    return {"schemaVersion": "gamecult.fork.entry.v0", "card": c, "record": record(counted, list(answers), c["options_hash"], c["fork_id"])}
+q5 = fcard(5); q4 = fcard(4); q2 = fcard(2)
+q3 = fcard(3, "closed", ruling="cultlib-gaps:resolution:question.q3.n1", ruled_from=["n1"]); q1 = fcard(1, "closed", ruling="cultlib-gaps:resolution:question.q1.n1")
+a5 = da("Counted", None, None, fbody(q5, "no", NOTE), srv("n1", OP, T(2)))
+a3 = da("Counted", None, None, fbody(q3, "yes", NOTE), srv("n1", OP, T(2)))
+r3 = da("Refused", None, "fork_closed", fbody(q3, "no", NOTE), srv("n2", HM, T(4), "Steward"))
+ENTRIES = [fentry(q5, [a5], "n1"), fentry(q4), fentry(q3, [a3, r3], "n1"), fentry(q2), fentry(q1)]
+q0 = fcard(0)
+ORDER0 = [fentry(fcard(3)), fentry(fcard(2)), fentry(fcard(1)), fentry(q0)]   # a Mind whose oldest card has order 0
+q4b = dict(fcard(4), fork_id="gamecult-chat:question:q4b")                      # a second card on order 4 in the same Mind
+def order_shared(entries):
+    seen, out = {}, []
+    for e in entries:
+        c = e["card"]
+        if c["order"] in seen: out.append(f"order {c['order']} is shared by {seen[c['order']]} and {c['fork_id']}")
+        else: seen[c["order"]] = c["fork_id"]
+    return out
+def lreq(mind="gamecult-chat", status=None, cursor=None, limit=10): return {"schemaVersion": "gamecult.fork.list_request.v0", "mind": mind, "status": status, "cursor": cursor, "limit": limit}
+def judge_list(entries, ordinal, rq):
+    rows = sorted(entries, key=lambda e: -e["card"]["order"])
+    want = [e for e in rows if rq["status"] is None or (e["card"]["status"] == "open") == (rq["status"] == "open")]
+    if rq["cursor"] is not None: want = [e for e in want if e["card"]["order"] < int(rq["cursor"][1:])]
+    page = want[:rq["limit"]]
+    more = len(want) > len(page) and len(page) > 0
+    return {"schemaVersion": "gamecult.fork.list.v0", "mind": rq["mind"], "stamp": f"s{ordinal}",
+            "open_count": sum(e["card"]["status"] == "open" for e in rows), "recorded_count": sum(e["card"]["status"] == "closed" for e in rows),
+            "forks": page, "next_cursor": f"c{page[-1]['card']['order']}" if more else None}
+def lstep(entries, ordinal, rq): r = judge_list(entries, ordinal, rq); return {"request": rq, "response": r, "responseHex": hx(r)}
+LISTS = [
+ {"name": "newest_first_paged_open_only", "ordinal": 412, "entries": ENTRIES, "steps": [lstep(ENTRIES, 412, lreq(status="open", limit=2)), lstep(ENTRIES, 412, lreq(status="open", cursor="c4", limit=2))]},
+ {"name": "all_forks_one_page", "ordinal": 412, "entries": ENTRIES, "steps": [lstep(ENTRIES, 412, lreq(limit=50))]},
+ {"name": "recorded_only_paged", "ordinal": 412, "entries": ENTRIES, "steps": [lstep(ENTRIES, 412, lreq(status="recorded", limit=1)), lstep(ENTRIES, 412, lreq(status="recorded", cursor="c3", limit=1))]},
+ {"name": "limit_zero_is_the_count_and_stamp_only", "ordinal": 412, "entries": ENTRIES, "steps": [lstep(ENTRIES, 412, lreq(limit=0))]},
+ {"name": "order_zero_is_legal_but_no_cursor_names_it", "ordinal": 9, "entries": ORDER0, "steps": [lstep(ORDER0, 9, lreq(limit=3)), lstep(ORDER0, 9, lreq(cursor="c1", limit=3))]},
+ {"name": "a_mind_with_no_forks", "ordinal": 7, "entries": [], "steps": [lstep([], 7, lreq(mind="nibu", limit=10))]},
+]
+# A page may stop short of `limit` when the next entry would pass the receiver's response budget; a list whose first
+# entry alone passes it is refused `fork_too_large` (422). The budget is not in the vector: a step records what the receiver answered, and the
+# judges check it against the unbudgeted page (a nonempty strict prefix, resumed below its last entry) or against the entry the page would open with.
+def too_large_doc(c): return {"schemaVersion": "gamecult.fork.refusal.v0", "code": "fork_too_large", "error": f"fork_too_large: fork {c['fork_id']} (order {c['order']}) alone is past the response budget"}
+def read_too_large_doc(c): return {"schemaVersion": "gamecult.fork.refusal.v0", "code": "fork_too_large", "error": f"fork_too_large: fork {c['fork_id']} alone is past the response budget"}
+READ_TOO_LARGE = [{"name": "a_read_whose_entry_is_past_the_cap_is_fork_too_large_without_an_order", "ordinal": 9, "entries": ORDER0,
+                   "request": {"schemaVersion": "gamecult.fork.read_request.v0", "mind": "gamecult-chat", "fork_id": ORDER0[0]["card"]["fork_id"]},
+                   "refusal": read_too_large_doc(ORDER0[0]["card"]), "refusalHex": hx(read_too_large_doc(ORDER0[0]["card"])), "httpStatus": HTTP["fork_too_large"], "fork_id": ORDER0[0]["card"]["fork_id"]}]
+# An answer on a stale card whose current-card re-read is past the cap: the same refusal document as the read form over a stored Refused(stale_fork), never counted.
+_big = ORDER0[0]["card"]
+ANSWER_TOO_LARGE = [{"name": "a_stale_answer_whose_card_reread_is_past_the_cap_is_fork_too_large_over_a_stored_stale_refusal",
+                     "entries": ORDER0, "request": body("yes", NOTE, h=STALE_H, fork=_big["fork_id"], rid="0000a001-0000-4000-8000-00000000a001"),
+                     "refusal": read_too_large_doc(_big), "refusalHex": hx(read_too_large_doc(_big)), "httpStatus": HTTP["fork_too_large"], "outcome": "Refused", "code": "stale_fork", "counted": False, "fork_id": _big["fork_id"]}]
+def short_step(entries, ordinal, rq, keep):
+    full = judge_list(entries, ordinal, rq); page = full["forks"][:keep]
+    assert 0 < keep < len(full["forks"])
+    r = dict(full, forks=page, next_cursor=f"c{page[-1]['card']['order']}"); return {"request": rq, "response": r, "responseHex": hx(r)}
+def large_step(entries, ordinal, rq):
+    c = judge_list(entries, ordinal, rq)["forks"][0]["card"]; r = too_large_doc(c)
+    return {"request": rq, "refusal": r, "refusalHex": hx(r), "httpStatus": HTTP["fork_too_large"], "fork_id": c["fork_id"], "order": c["order"]}
+SHORT_PAGES = [
+ {"name": "a_short_page_resumes_below_its_last_entry", "ordinal": 9, "entries": ORDER0, "steps": [short_step(ORDER0, 9, lreq(limit=3), 2), lstep(ORDER0, 9, lreq(cursor="c2", limit=3))]},
+ {"name": "a_first_entry_past_the_budget_is_fork_too_large_and_the_client_continues_below_its_order", "ordinal": 9, "entries": ORDER0,
+  "steps": [large_step(ORDER0, 9, lreq(limit=3)), lstep(ORDER0, 9, lreq(cursor="c3", limit=3))]},
+ {"name": "fork_too_large_on_order_zero_leaves_nothing_below", "ordinal": 9, "entries": ORDER0[2:],
+  "steps": [short_step(ORDER0[2:], 9, lreq(limit=5), 1), large_step(ORDER0[2:], 9, lreq(cursor="c1", limit=5))]},
+]
+DUP_LIST = judge_list(ENTRIES + [fentry(q4b)], 412, lreq(limit=50))
+assert order_shared(DUP_LIST["forks"]) == ["order 4 is shared by gamecult-chat:question:q4 and gamecult-chat:question:q4b"]
+TOK = lambda aud, *sc, active=True: {"audience": aud, "scopes": list(sc), "active": active}
+AUTH = [
+ ("list_with_desk_read", "list", TOK("bifrost-desk", "desk.read"), "ok"), ("read_with_desk_read", "read", TOK("bifrost-desk", "desk.read"), "ok"),
+ ("answer_with_desk_answer", "answer", TOK("bifrost-desk", "desk.answer"), "ok"), ("answer_with_both_scopes", "answer", TOK("bifrost-desk", "desk.read", "desk.answer"), "ok"),
+ ("no_bearer_list", "list", None, "unauthenticated"), ("no_bearer_answer", "answer", None, "unauthenticated"),
+ ("the_MAS_token_is_refused", "list", TOK("matrix-authentication-service", "openid", "profile"), "unauthenticated"),
+ ("a_votes_token_cannot_list", "list", TOK("bifrost-votes", "votes.read"), "unauthenticated"),
+ ("a_votes_token_cannot_read", "read", TOK("bifrost-votes", "votes.read"), "unauthenticated"),
+ ("a_votes_token_cannot_answer", "answer", TOK("bifrost-votes", "votes.cast"), "unauthenticated"),
+ ("desk_audience_with_a_votes_scope_only", "answer", TOK("bifrost-desk", "votes.cast"), "insufficient_scope"),
+ ("desk_read_cannot_answer", "answer", TOK("bifrost-desk", "desk.read"), "insufficient_scope"),
+ ("desk_answer_cannot_list", "list", TOK("bifrost-desk", "desk.answer"), "insufficient_scope"),
+ ("a_non_active_member_cannot_list", "list", TOK("bifrost-desk", "desk.read", active=False), "forbidden"),
+ ("a_non_active_member_cannot_read", "read", TOK("bifrost-desk", "desk.read", active=False), "forbidden"),
+ ("a_non_active_member_cannot_answer", "answer", TOK("bifrost-desk", "desk.answer", active=False), "forbidden"),
+ ("scope_is_judged_before_membership", "answer", TOK("bifrost-desk", "desk.read", active=False), "insufficient_scope"),
+ ("huginn_down_list", "list", TOK("bifrost-desk", "desk.read"), "unavailable", True),
+ ("huginn_down_read", "read", TOK("bifrost-desk", "desk.read"), "unavailable", True),
+ ("huginn_down_answer", "answer", TOK("bifrost-desk", "desk.answer"), "unavailable", True),
+ ("auth_is_judged_before_huginn_is_asked", "list", None, "unauthenticated", True),
+ ("membership_is_judged_before_huginn_is_asked", "read", TOK("bifrost-desk", "desk.read", active=False), "forbidden", True),
+]
+# ---------- transport: the {mind} segment (Heimdall's file 4.3a, M1 to M4) ----------
+import urllib.parse
+MINDS = {"gamecult-chat": "huginn-gamecult-chat.sock", "nibu": "huginn-nibu.sock"}
+MIND_FORKS = {"gamecult-chat": ["gamecult-chat:question:q1", "gamecult-chat:question:q2", FID], "nibu": ["nibu:question:glow-order"]}
+def auth_code(route, tok):
+    if tok is None or tok["audience"] != "bifrost-desk": return "unauthenticated"
+    if ("desk.answer" if route == "answer" else "desk.read") not in tok["scopes"]: return "insufficient_scope"
+    return "forbidden" if not tok["active"] else "ok"
+def mind_route(route, seg, fork, tok):
+    code = auth_code(route, tok)
+    if code != "ok": return code, None, None
+    try: mind = urllib.parse.unquote(seg, errors="strict")
+    except UnicodeDecodeError: mind = None
+    if mind not in MINDS: return "fork_unknown", None, None          # never joined into a path; no socket is opened
+    if route != "list" and fork not in MIND_FORKS[mind]: return "fork_unknown", MINDS[mind], None
+    return "ok", MINDS[mind], mind if route == "answer" else None
+DESK_READ, DESK_ANSWER = TOK("bifrost-desk", "desk.read"), TOK("bifrost-desk", "desk.answer")
+def mcase(name, route, seg, fork=None, tok=None):
+    tok = None if tok == "none" else tok or (DESK_ANSWER if route == "answer" else DESK_READ)
+    code, opened, stored = mind_route(route, seg, fork, tok)
+    return {"name": name, "route": route, "mind": seg, "fork_id": fork, "token": tok, "expect": code, "httpStatus": 200 if code == "ok" else HTTP[code], "opened": opened, "stored_in": stored}
+BAD_SEGMENTS = [("dot_dot", "../x"), ("slash", "a/b"), ("encoded_slash", "a%2fb"), ("encoded_dot_dot", "%2e%2e%2fx"), ("nul", "eureka%00"), ("four_kb", "a" * 4096),
+                ("other_case", "GAMECULT-CHAT"), ("trailing_space", "nibu%20"), ("invalid_utf8", "%ff"), ("dot", "."), ("dots", ".."), ("double_encoded", "%256eibu")]
+MINDCASES = [
+  mcase("list_a_percent_encoded_configured_mind_is_decoded_once", "list", "%6eibu"), mcase("list_a_configured_mind", "list", "gamecult-chat"), mcase("list_another_configured_mind", "list", "nibu"),
+  mcase("read_a_fork_the_mind_holds", "read", "gamecult-chat", FID), mcase("answer_a_fork_the_mind_holds_is_stored_in_that_mind", "answer", "gamecult-chat", FID),
+  mcase("answer_on_the_other_mind", "answer", "nibu", "nibu:question:glow-order"),
+] + [mcase(f"M1_{route}_{n}_is_unknown_and_opens_nothing", route, seg, FID if route != "list" else None) for route in ("list", "read", "answer") for n, seg in BAD_SEGMENTS] + [
+  mcase("M2_read_unknown_mind_known_fork", "read", "ghost", FID), mcase("M2_read_known_mind_unknown_fork", "read", "gamecult-chat", "gamecult-chat:question:ghost"),
+  mcase("M2_answer_unknown_mind_known_fork", "answer", "ghost", FID), mcase("M2_answer_known_mind_unknown_fork", "answer", "gamecult-chat", "gamecult-chat:question:ghost"),
+  mcase("M2_list_unknown_mind", "list", "ghost"),
+  mcase("M3_answer_on_nibu_with_a_fork_gamecult_chat_holds", "answer", "nibu", FID), mcase("M3_answer_on_gamecult_chat_with_a_fork_nibu_holds", "answer", "gamecult-chat", "nibu:question:glow-order"),
+  mcase("M4_desk_read_lists_every_mind", "list", "nibu", tok=DESK_READ), mcase("M4_desk_read_reads_every_mind", "read", "nibu", "nibu:question:glow-order", tok=DESK_READ),
+  mcase("M4_desk_answer_cannot_list_any_mind", "list", "gamecult-chat", tok=DESK_ANSWER), mcase("M4_desk_answer_cannot_list_the_other_mind", "list", "nibu", tok=DESK_ANSWER),
+  mcase("M4_desk_read_cannot_answer_on_any_mind", "answer", "nibu", "nibu:question:glow-order", tok=DESK_READ),
+  mcase("auth_comes_before_the_mind_lookup_no_bearer", "list", "ghost", tok="none"), mcase("auth_comes_before_the_mind_lookup_scope", "answer", "ghost", FID, tok=DESK_READ),
+  mcase("auth_comes_before_the_mind_lookup_non_active", "read", "ghost", FID, tok=TOK("bifrost-desk", "desk.read", active=False)),
+]
+SAME_RESPONSE = [["M2_read_unknown_mind_known_fork", "M2_read_known_mind_unknown_fork"], ["M2_answer_unknown_mind_known_fork", "M2_answer_known_mind_unknown_fork"],
+                 ["M2_list_unknown_mind", "M2_read_known_mind_unknown_fork"], ["M3_answer_on_nibu_with_a_fork_gamecult_chat_holds", "M2_answer_known_mind_unknown_fork"]]
+def bad(name, why, m, **kw): return dict({"name": name, "why": why, "message": m}, **kw)
+DECIDERS_64 = [f"{i:08x}-0000-4000-8000-{i:012x}" for i in range(1, 65)]   # the card's `deciders` holds at most 64 (Huginn's bound)
+# body_sha256: Huginn's private "same body" digest (fork-card.md, "The mind's record"); no wire document carries it. Input per
+# /opt/commons/handoff/desk-body-digest-order-20261110.md (Eureka): SHA-256 of compact serde_json UTF-8, keys in this order, null for missing,
+# `retracts` the full stored key, request_id out. `illegal_retraction` and `retracted` are written only when the input has them (non-null).
+DIGEST_KEYS = ["fork", "options_hash", "answered_at", "choice", "note", "retracts", "illegal_retraction", "retracted"]
+def digest_bytes(i): return json.dumps({k: i[k] for k in DIGEST_KEYS if k in ("fork", "options_hash", "answered_at", "choice", "note", "retracts") or i.get(k) is not None},
+                                       separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+DQ = {"fork": "eureka-state:question:Q1", "options_hash": "a" * 64, "answered_at": "2026-11-10T12:00:00Z"}
+DT = "eureka-state:desk_answer:Q1.n1"
+def dg(name, status, sha_expected, why, **kw):
+    i = dict(DQ, choice=None, note=None, retracts=None, illegal_retraction=None, retracted=None); i.update(kw)
+    b = digest_bytes(i); got = sha(b)
+    assert got == sha_expected, (name, got)
+    return {"name": name, "status": status, "why": why, "input": i, "canonical": b.decode("utf-8"), "sha256": got}
+MAIN, FIX = "main_7ea11b4_must_not_move", "reproduced_on_huginn_main_f0ca504_reported_by_eureka_not_rerun_here"
+BODY_DIGESTS = [
+  dg("plain_answer_choice_A", MAIN, "8a4d5b2ed0b3452bfed2f3a276b2828974e6824a3edcc643cfe9cfcdda34173a", "a plain answer: choice and note as sent, retracts null; no illegal or retracted key", choice="A"),
+  dg("legal_retraction", MAIN, "9f8075382556898c0bea364ed7c6deb2a86d8c78288a1f34e06da6e9bf5f58a3", "a legal retraction as Huginn main pins it: retracts is `Q1.1`, a string no door produces (the key grammar is .n<seq>); kept for the frozen-form test", retracts="eureka-state:desk_answer:Q1.1"),
+  dg("illegal_i_and_iii_alike_on_main", MAIN, "69074cc60829ef5edb12358746f7549ad08da97653d59359c945cea102f53565", "main writes `illegal_retraction: true` and no `retracted`, so (i) and (iii) collide: the defect the fix removes", choice="A", retracts=DT, illegal_retraction=True),
+  dg("legal_retraction_door_form", MAIN, "84576840247830b9b75754b460dc4ea52883ca1e410f9f011521e0f69b99eee1", "a legal retraction as the door produces it: the wire's n1 converted to the full stored key Q1.n1 before the digest; the golden that stands for the real form (digest unaffected by .n<seq> vs .1)", retracts=DT),
+  dg("illegal_ii_on_main", MAIN, "1a36c4aba0d1c30d0736f20243ebfdb84fe84a5eabd4f69709a096a32c3cc6e3", "(ii) no answer, no target, on main", illegal_retraction=True),
+  dg("illegal_i_retraction_with_an_answer_retracted_true", FIX, "935cab1a0ae34606b809d8ebca7cffa2889d20b3585d2622d32153a4d6898af1", "(i) answer present, retracted true, target Q1.n1", choice="A", retracts=DT, illegal_retraction=True, retracted=True),
+  dg("illegal_iii_plain_answer_with_a_target_retracted_false", FIX, "82b24cccb4ed2535a549f95f844fcd935074c3712b5b832f0b2cbd89c71fd9a6", "(iii) the same bytes as (i) with retracted false: another body, so request_id_conflict", choice="A", retracts=DT, illegal_retraction=True, retracted=False),
+  dg("illegal_i_retraction_with_an_answer_and_no_target_retracted_true", "reproduced_on_huginn_main_f0ca504_reported_by_eureka_not_rerun_here", "79eee623fd6712db6537a4867cedf54ca49ee4885416c2c8e4acec59f811b894", "(i) with the target null (the order doc: retracts set or null); Eureka re-derived it with sha256sum (order doc addendum)", choice="A", illegal_retraction=True, retracted=True),
+  dg("illegal_ii_no_answer_no_target_retracted_true", FIX, "34ef86ed63b9318459965d4b85e794d2636ffc15736da866036b087c9c4a30eb", "(ii) no answer, no target, retracted true", illegal_retraction=True, retracted=True),
+]
+fork = {
+  "provenance": "Rule source: /opt/commons/handoff/fork-desk-answer-binding-20261110.md (Heimdall), amended by the Persona briefs of 2026-11-10 (Eureka's fit check). Bytes spec-authored with msgpack-python (scripts/gen-governance-vectors.py); every runtime re-encodes `message` and must match messagePackHex. options_hash follows fork-card.md 'Options hash'; the vectors named heimdall_* are that file's, with its digests.",
+  "optionsHash": hashes,
+  "bodyDigests": BODY_DIGESTS,
+  "card": {"valid": [{"name": "operator_fork", "message": CARD, "messagePackHex": hx(CARD)},
+                     {"name": "leans_flag_closed_two_deciders", "message": card(leans="yes", flag="provisional: Self expects this to move", deciders=[OP, HM], depends=[], raised_in=None, status="closed", ruling="x:resolution:y", ruled_from=["n1"], order=0),
+                      "messagePackHex": hx(card(leans="yes", flag="provisional: Self expects this to move", deciders=[OP, HM], depends=[], raised_in=None, status="closed", ruling="x:resolution:y", ruled_from=["n1"], order=0))},
+                     {"name": "depends_at_both_caps", "message": card(depends=["a"] * 7 + ["\u00e9" * 500]), "messagePackHex": hx(card(depends=["a"] * 7 + ["\u00e9" * 500]))},
+                     {"name": "closed_without_a_ruling_the_question_was_withdrawn", "message": card(status="closed"), "messagePackHex": hx(card(status="closed"))},
+                     {"name": "deciders_at_the_cap_of_64", "message": card(deciders=DECIDERS_64), "messagePackHex": hx(card(deciders=DECIDERS_64))}],
+           "invalid": [bad(n, w, m) for n, w, m in [
+               ("depends_nine_lines", "depends holds at most 8 lines (the stored question's limit)", card(depends=["a"] * 9)),
+               ("depends_line_1001_code_points", "a depends line is at most 1000 characters", card(depends=["a" * 1001])),
+               ("depends_line_1001_bytes", "rule: one byte over the limit (500 two-byte characters and one more; not expressible in the schema)", card(depends=["\u00e9" * 500 + "a"])),
+               ("depends_line_over_1000_bytes", "rule: a depends line is at most 1000 UTF-8 bytes (the stored Line limit; not expressible in the schema)", card(depends=["\u00e9" * 501])),
+               ("one_option", "two or more options", card(options=[OPT[0]], recommendation="yes")),
+               ("no_deciders", "a fork with no decider cannot be answered", card(deciders=[])),
+               ("null_recommendation", "every card recommends an option", dict(card(), recommendation=None)),
+               ("unknown_key", "closed document", dict(card(), note="x")),
+               ("option_with_a_label", "options are {id,text}; the old format's display label is not a member (fork-card.md, Old format)", card(options=[dict(OPT[0], label="Yes"), OPT[1]])),
+               ("status_unknown", "status is open or closed", card(status="provisional")),
+               ("options_hash_not_hex", "options_hash is 64 lowercase hex", dict(card(), options_hash="XYZ")),
+               ("duplicate_option_ids", "rule: option ids are unique (not expressible in the schema)", card(options=[OPT[0], dict(OPT[1], id=OPT[0]["id"])])),
+               ("recommendation_not_an_option", "rule: recommendation is an option id (not expressible in the schema)", card(recommendation="maybe")),
+               ("leans_not_an_option", "rule: leans is nil or an option id (not expressible in the schema)", card(leans="maybe")),
+               ("duplicate_deciders", "rule: deciders are unique (not expressible in the schema)", card(deciders=[OP, OP])),
+               ("ruled_from_on_an_open_card", "rule: a ruling that answers a fork closes it, so an open card cites no answer in ruled_from (not expressible in the schema)", card(ruled_from=["n1"])),
+               ("open_card_names_a_ruling", "rule: only a closed card names a ruling (not expressible in the schema)", card(ruling="cultlib-gaps:resolution:question.slot-mark-consent.n1")),
+               ("ruled_from_without_a_ruling", "rule: ruled_from lists answers a ruling was admitted from, so it needs the ruling (not expressible in the schema)", card(status="closed", ruled_from=["n1"])),
+               ("options_hash_of_another_card", "rule: options_hash equals the hash of the shown members (not expressible in the schema)", dict(card(), options_hash=STALE_H)),
+               ("deciders_65", "deciders holds at most 64 (Huginn's bound)", card(deciders=DECIDERS_64 + ["00000041-0000-4000-8000-000000000041"])),
+           ]]},
+  "request": {"valid": [{"name": n, "message": m, "messagePackHex": hx(m)} for n, m in
+                       [("choice_and_note", x1), ("choice_alone", pick), ("note_alone_clear_pick", words), ("retraction", retraction("n1")),
+                        ("note_4000_ascii_bytes", body(None, "x" * 4000)), ("note_astral_4000_bytes", body(None, "\U0001F600" * 1000)),
+                        ("note_combining_4000_bytes", body(None, "e\u0301" * 1333 + "x"))]],
+             "invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+               ("answer_with_neither", "an answer object holds a choice, a note, or both", body(answer={"choice": None, "note": None})),
+               ("blank_note", "a blank note is no answer", body(None, "  \u00a0 ")),
+               ("request_id_missing", "map-mode writes every key; a retry needs the id", {k: v for k, v in x1.items() if k != "request_id"}),
+               ("request_id_uppercase", "request_id is lowercase", dict(x1, request_id="0000000A-0000-4000-8000-00000000000B")),
+               ("request_id_not_a_uuid", "request_id is a lowercase D-format UUID", dict(x1, request_id="retry-1")),
+               ("note_over_4000", "notes are at most 4000 UTF-8 bytes", body(None, "x" * 4001)),
+               ("note_multibyte_4001_bytes", "a note is counted in UTF-8 bytes: 1999 e-acute is 3998 bytes, plus three ASCII is 4001 (rule: not expressible in the schema, 2002 characters)", body(None, "\u00e9" * 1999 + "abc")),
+               ("note_astral_4004_bytes", "1001 astral characters are 4004 bytes though only 1001 code points (rule: not expressible in the schema)", body(None, "\U0001F600" * 1001)),
+               ("note_combining_4002_bytes", "e plus a combining acute is 3 bytes: 1334 of them are 4002 (rule: not expressible in the schema)", body(None, "e\u0301" * 1334)),
+               ("options_hash_uppercase", "hash is lowercase hex", body("no", None, h=H.upper())),
+               ("answerer_key", "answerer is server-set; the door answers body_forbidden_field", dict(x1, answerer=OP)),
+               ("authority_key", "authority is server-set; the door answers body_forbidden_field", dict(x1, authority="Operator")),
+               ("answer_object_with_a_key", "the answer object is closed", body(answer={"choice": "no", "note": None, "weight": 1})),
+               ("answered_at_without_zone", "instants are UTC with a Z", body("no", None, at="2026-11-12T19:02:00")),
+               ("retracted_not_a_boolean", "retracted is a boolean", dict(x1, retracted="no")),
+               ("fork_id_empty", "fork_id names a fork", body("no", None, fork="")),
+           ]]},
+  "deskAnswer": {"valid": [{"name": n, "message": m, "messagePackHex": hx(m)} for n, m in
+                           [("counted", CNT), ("revision", REV), ("retraction", da("Retraction", "n1", None, retraction("n1"), sr("n8"))),
+                            ("refused_stale", da("Refused", None, "stale_fork", stale_body(), sx1)),
+                            ("refused_closed_retraction_names_its_target", da("Refused", None, "fork_closed", retraction("n1"), sr("n9")))]],
+                 "invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+                   ("counted_with_a_code", "only Refused carries a code", dict(CNT, code="fork_closed")),
+                   ("refused_without_a_code", "Refused carries a reason code", dict(REF, code=None)),
+                   ("refused_with_an_unknown_code", "the code set is closed", dict(REF, code="because")),
+                   ("counted_naming_another_answer", "Counted names none", dict(CNT, of="n0")),
+                   ("revision_naming_none", "a Revision names the counted answer", dict(REV, of=None)),
+                   ("revision_that_also_retracts", "a variant carries only its own link (a retraction with no target, or a target with no retraction, cannot exist)", dict(REV, retracts="n1")),
+                   ("retraction_naming_no_target", "a Retraction names the answer it retracts", dict(da("Retraction", "n1", None, retraction("n1"), sr("n8")), retracts=None)),
+                   ("refused_naming_another_answer_as_of", "a Refused answer names no counted answer (`of` is a Revision's)", dict(REF, of="n1")),
+                   ("refused_with_a_target_that_is_not_an_answer_id", "a Refused answer's retracts is nil or an answer id (n<seq>), never the stored key", dict(REF, retracts="cultlib-gaps:desk_answer:slot-mark-consent.n1")),
+                   ("retraction_carrying_a_choice", "a Retraction carries no choice or note", dict(da("Retraction", "n1", None, retraction("n1"), sr("n8")), choice="no")),
+                   ("outcome_lower_case", "outcome tags are Counted, Revision, Retraction, Refused", dict(CNT, outcome="counted")),
+                   ("no_answerer", "answerer is stamped on every stored answer", dict(CNT, answerer="")),
+                 ]]},
+  "results": [{"name": r["name"], "httpStatus": r["httpStatus"], "message": r["message"], "messagePackHex": hx(r["message"])} for r in STORED_REFUSALS],
+  "doorRefusals": [{"name": c, "httpStatus": HTTP[c], "message": refusal_doc(c), "messagePackHex": hx(refusal_doc(c))} for c in TAIL] + [{"name": "fork_too_large", "httpStatus": HTTP["fork_too_large"], "message": SHORT_PAGES[1]["steps"][0]["refusal"], "messagePackHex": SHORT_PAGES[1]["steps"][0]["refusalHex"]}],
+  "unavailable": [{"name": "second_door_down", "httpStatus": 503, "message": unavailable_doc(30), "messagePackHex": hx(unavailable_doc(30))},
+                  {"name": "second_door_down_no_hint", "httpStatus": 503, "message": unavailable_doc(None), "messagePackHex": hx(unavailable_doc(None))}],
+  "rulingCites": cites,
+  "transport": {
+    "listRequest": {"valid": [{"name": "list_open_page", "message": lreq(status="open", limit=2), "messagePackHex": hx(lreq(status="open", limit=2))},
+                              {"name": "list_next_page", "message": lreq(status="open", cursor="c4", limit=2), "messagePackHex": hx(lreq(status="open", cursor="c4", limit=2))},
+                              {"name": "list_count_only", "message": lreq(limit=0), "messagePackHex": hx(lreq(limit=0))}],
+                    "invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+                      ("limit_51", "a page is at most 50 forks", lreq(limit=51)), ("limit_negative", "limit is 0 to 50", lreq(limit=-1)),
+                      ("status_all", "status is open, recorded or nil", lreq(status="all")), ("cursor_malformed", "a cursor is c<N>", lreq(cursor="next")),
+                      ("cursor_zero", "a cursor names a positive order", lreq(cursor="c0")), ("mind_empty", "a list names a Mind", lreq(mind="")),
+                      ("unknown_key", "closed document", dict(lreq(), sort="oldest"))]]},
+    "readRequest": {"valid": [{"name": "read_one", "message": {"schemaVersion": "gamecult.fork.read_request.v0", "mind": "gamecult-chat", "fork_id": FID}, "messagePackHex": hx({"schemaVersion": "gamecult.fork.read_request.v0", "mind": "gamecult-chat", "fork_id": FID})}],
+                    "invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+                      ("fork_id_empty", "a read names a fork", {"schemaVersion": "gamecult.fork.read_request.v0", "mind": "gamecult-chat", "fork_id": ""}),
+                      ("mind_empty", "a read names a Mind", {"schemaVersion": "gamecult.fork.read_request.v0", "mind": "", "fork_id": FID}),
+                      ("mind_missing", "map-mode writes every key; the Mind is the route's", {"schemaVersion": "gamecult.fork.read_request.v0", "fork_id": FID})]]},
+    "entry": {"valid": [{"name": n, "message": e, "messagePackHex": hx(e)} for n, e in [("open_no_answers", ENTRIES[1]), ("open_counted", ENTRIES[0]), ("closed_with_ruling_and_a_refusal", ENTRIES[2])]],
+              "invalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+                ("entry_without_record", "an entry holds the card and its record", {k: v for k, v in ENTRIES[0].items() if k != "record"}),
+                ("record_of_another_fork", "rule: the record names the card's fork (not expressible in the schema)", dict(ENTRIES[0], record=dict(ENTRIES[0]["record"], fork_id="gamecult-chat:question:q9"))),
+                ("record_under_another_hash", "rule: the record is under the card's options_hash (not expressible in the schema)", dict(ENTRIES[0], record=dict(ENTRIES[0]["record"], options_hash=STALE_H))),
+                ("counted_answer_not_derived", "rule: counted_answer_id is the first live Counted or Revision answer under the card's hash (not expressible in the schema)", dict(ENTRIES[0], record=dict(ENTRIES[0]["record"], counted_answer_id=None))),
+                ("card_hash_wrong", "rule: the server computes options_hash and a client recomputes it; a card with another hash is no card", dict(ENTRIES[1], card=dict(ENTRIES[1]["card"], options_hash=STALE_H), record=dict(ENTRIES[1]["record"], options_hash=STALE_H)))]]},
+    "listInvalid": [dict(bad(n, w, m), messagePackHex=hx(m)) for n, w, m in [
+      ("next_cursor_malformed", "a cursor is c<N>", dict(LISTS[0]["steps"][0]["response"], next_cursor="more")),
+      ("stamp_malformed", "a stamp is s<N>", dict(LISTS[0]["steps"][0]["response"], stamp="412")),
+      ("count_negative", "counts are not negative", dict(LISTS[0]["steps"][0]["response"], open_count=-1))]]
+      + [dict(bad("two_cards_share_one_order", "rule: order is a unique rank per Mind; the refusal names both fork ids (not expressible in the schema)", DUP_LIST),
+              messagePackHex=hx(DUP_LIST), refusal=order_shared(DUP_LIST["forks"])[0])],
+    "listScenarios": [{"name": l["name"], "ordinal": l["ordinal"], "entries": l["entries"], "steps": l["steps"]} for l in LISTS],
+    "listShortPages": SHORT_PAGES,
+    "readTooLarge": READ_TOO_LARGE,
+    "answerTooLarge": ANSWER_TOO_LARGE,
+    "doorFaults": [dict(c, response=r, responseHex=hx(r)) for c, r in
+                   [({"name": f"{x}_door_answers_request_id_conflict_the_client_sees_unavailable", "route": x, "doorCode": "request_id_conflict", "httpStatus": 503}, unavailable_doc(30)) for x in ("read", "list")]
+                   + [({"name": "answer_door_answers_request_id_conflict_the_client_sees_it", "route": "answer", "doorCode": "request_id_conflict", "httpStatus": HTTP["request_id_conflict"]}, refusal_doc("request_id_conflict"))]],
+    "mindRoutes": {"minds": MINDS, "forks": MIND_FORKS, "cases": MINDCASES, "sameResponse": SAME_RESPONSE},
+    "authCases": [{"name": a[0], "route": a[1], "token": a[2], "expect": a[3], "huginn_down": len(a) > 4} for a in AUTH],
+  },
+  "scenarios": [{"name": n, "card": c, "optionsHash": c["options_hash"], "steps": steps, "record": r, "recordHex": hx(r)} for n, c, steps, r in scen],
+}
+(OUT / "fork-card-vectors.json").write_text(json.dumps(fork, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+print("ok", len(vote["valid"]), len(vote["invalid"]), len(fork["scenarios"]))

src/GameCult.Caching/Contracts/cultcache-store-composition.md

@@ -110,7 +110,10 @@ which route wrote it.
   already agree when publication starts.
 - An admission runs a record's `[CultName]` and `[CultIndex]` getters once per
   landing record, before the store is written and before any `Sequence` is
-  minted. A conditional commit on a clean file store is judged a second time
+  minted. An admission is refused when it would leave two records of one type
+  holding one `[CultIndex]` value (blank is no value), and a load of a store
+  holding such a pair refuses naming both keys and the index. Concurrent writers on a
+  directory store are not covered by this rule. A conditional commit on a clean file store is judged a second time
   against the file it merges onto whenever the cache holds variants in any store,
   the batch lands a variant, or the file holds one. That second read runs the
   getters again for the records the batch lands, for any variant it re-resolves,

src/GameCult.Caching/CultCache.cs

@@ -885,6 +885,10 @@ namespace GameCult.Caching
             return indexes.BySchemaId.ContainsKey(schemaId) || indexes.ByCompatibleSchemaId.ContainsKey(schemaId);
         }
 
+        // Whether the type registered under this schema id declares a [CultIndex]: its records are written through a cache, which judges uniqueness.
+        internal bool HoldsUniqueIndex(string schemaId) =>
+            _indexes.BySchemaId.TryGetValue(schemaId, out var descriptor) && descriptor.IndexAccessors.Count > 0;
+
         // A persisted entry a local entry reads whole: identical content, or compatible shapes that leave no persisted slot ignored.
         internal static bool ReadsWhole(CultSchemaCatalogEntry persisted, CultSchemaCatalogEntry local) =>
             string.Equals(persisted.ContentHash, local.ContentHash, StringComparison.Ordinal) ||
@@ -1006,10 +1010,10 @@ namespace GameCult.Caching
                 throw new InvalidOperationException(ids.Problems[0]);
             var nameMember = members.FirstOrDefault(member => member.IsName);
             var indexAccessors = members
-                .Where(member => member.IndexAlias != null)
+                .Where(member => member.IsUnique)
                 .ToDictionary(
                     member => member.IndexAlias!,
-                    member => member.Getter,
+                    member => member.IndexValue,
                     StringComparer.Ordinal);
             var descriptorMembers = members
                 .Select(member => new CultDocumentMemberDescriptor
@@ -1481,6 +1485,13 @@ namespace GameCult.Caching
                 rejections.Add(HiddenMemberMessage(type.Name, Qualified(pair[0].Member), Qualified(pair[1].Member)));
             }
 
+            // A member names its role once: [CultIndex] already is a role.
+            foreach (var entry in keyed.OrderBy(entry => entry.Member.Name, StringComparer.Ordinal))
+            {
+                if (entry.Member.GetCustomAttribute<CultIndexAttribute>() != null && entry.Member.GetCustomAttribute<CultRoleAttribute>() != null)
+                    rejections.Add($"Cult document {type.Name} member {Qualified(entry.Member)} declares both [CultIndex] and [CultRole]; [CultIndex] already names its role.");
+            }
+
             // D10: two differently-named members that independently declare the same index alias. A
             // hiding member sharing one slot is already caught above; this is two distinct members whose
             // alias map entry (BuildDescriptor's indexAccessors) would otherwise collide silently.
@@ -1580,14 +1591,19 @@ namespace GameCult.Caching
 
         private static string Qualified(MemberInfo member) => member.DeclaringType!.Name.Split('`')[0] + "." + member.Name;
 
+        // The member's role alias, from [CultIndex] or [CultRole] (the member name when the alias is blank).
         // Shared by DiscoverMembers' D10/D11 rejections and PersistedMember.FromMember, so registration
         // refuses exactly the shapes the accessor it builds afterward could not have walked anyway.
         private static string? ResolveIndexAlias(MemberInfo member)
         {
-            var indexAttribute = member.GetCustomAttribute<CultIndexAttribute>();
-            if (indexAttribute == null)
+            string? alias;
+            if (member.GetCustomAttribute<CultIndexAttribute>() is { } index)
+                alias = index.Alias;
+            else if (member.GetCustomAttribute<CultRoleAttribute>() is { } role)
+                alias = role.Alias;
+            else
                 return null;
-            return string.IsNullOrWhiteSpace(indexAttribute.Alias) ? member.Name : indexAttribute.Alias;
+            return string.IsNullOrWhiteSpace(alias) ? member.Name : alias;
         }
 
         private static bool IsCultRecordRefType(Type type) =>
@@ -1854,6 +1870,7 @@ namespace GameCult.Caching
             public int Slot { get; set; }
             public bool IsName { get; set; }
             public string? IndexAlias { get; set; }
+            public bool IsUnique { get; set; }
             public bool IsReference { get; set; }
             public bool IsMany { get; set; }
             public string? TargetSchemaName { get; set; }
@@ -1866,6 +1883,10 @@ namespace GameCult.Caching
             public Func<object, string> Getter { get; set; } = default!;
             public Func<object, string?> GetterNullable { get; set; } = default!;
 
+            // What a [CultIndex] value is: culture-invariant, and a number is its canonical decimal (1.0m and 1.00m are one value,
+            // 0.0 and -0.0 are one value), so the value that decides a refusal is the value a lookup names.
+            public Func<object, string> IndexValue { get; set; } = default!;
+
             // D8/Q-J (revised 2026-09-22): non-null exactly for the closed CLR numeric set (Nullable<T>
             // unwrapped), rendered as the member's exact canonical decimal string - never a double, so
             // no CLR numeric type's range or precision is lost rendering it. docs/cultnet-selection-cut.md
@@ -1896,6 +1917,7 @@ namespace GameCult.Caching
                     Slot = slot,
                     IsName = member.GetCustomAttribute<CultNameAttribute>() != null,
                     IndexAlias = ResolveIndexAlias(member),
+                    IsUnique = member.GetCustomAttribute<CultIndexAttribute>() != null,
                     IsReference = isReference,
                     IsMany = many,
                     TargetSchemaName = targetSchemaName,
@@ -1903,6 +1925,13 @@ namespace GameCult.Caching
                     IsNumeric = IsNumericClrType(memberType),
                     Getter = document => getValue(document)?.ToString() ?? string.Empty,
                     GetterNullable = document => getValue(document)?.ToString(),
+                    IndexValue = document => getValue(document) switch
+                    {
+                        null => string.Empty,
+                        var raw when IsNumericClrType(raw.GetType()) => RenderCanonicalNumber(raw) ?? string.Empty,
+                        IFormattable formattable => formattable.ToString(null, CultureInfo.InvariantCulture),
+                        var raw => raw.ToString() ?? string.Empty
+                    },
                     NumberOf = document =>
                     {
                         var raw = getValue(document);
@@ -2200,8 +2229,8 @@ namespace GameCult.Caching
         private readonly List<(CacheBackingStore Store, Type[] Homes)> _stores = new();
         private readonly Dictionary<string, CultStoredDocument> _entries = new(StringComparer.Ordinal);
         private readonly Dictionary<Type, Dictionary<string, string>> _names = new();
-        // Every key holding a value (unordered): the index is truthful about duplicates, so removing one holder never hides another.
-        private readonly Dictionary<(Type Type, string Alias), Dictionary<string, List<string>>> _indexes = new();
+        // One key per value: RefuseIndexSharing decides it, Apply only records it.
+        private readonly Dictionary<(Type Type, string Alias), Dictionary<string, string>> _indexes = new();
         private readonly Dictionary<Type, string> _globals = new();
         private readonly CultCodec? _codec;
         // Keys holding a variant: derived from the entries by Apply, never decided anywhere else.
@@ -2671,16 +2700,12 @@ namespace GameCult.Caching
                 .SelectMany(pair => pair.Value.TryGetValue(name, out var key) ? new[] { key } : Array.Empty<string>()));
         }
 
-        // A value held by one record finds it. Records of one type sharing a value (plain duplicates) find the holder with the
-        // smallest key (ordinal), whatever order they were written or loaded in: the choice is a function of the held set, so
-        // it is the same live, after a flush and after a reopen, and removing that holder finds the next.
+        // A [CultIndex] value names one record of its type; blank values are not indexed.
         public T? GetByIndex<T>(string alias, string value) where T : class
         {
             return Single<T>($"index {alias}='{value}'", () => _indexes
                 .Where(pair => pair.Key.Alias == alias && typeof(T).IsAssignableFrom(pair.Key.Type))
-                .SelectMany(pair => pair.Value.TryGetValue(value, out var keys)
-                    ? new[] { keys.Aggregate((best, next) => string.CompareOrdinal(next, best) < 0 ? next : best) }
-                    : Array.Empty<string>()));
+                .SelectMany(pair => pair.Value.TryGetValue(value, out var key) ? new[] { key } : Array.Empty<string>()));
         }
 
         public void Dispose()
@@ -3270,12 +3295,10 @@ namespace GameCult.Caching
         {
             var plan = ResolveVariants(admitted, evicted, source);
             Project(plan);
-            // The variant rules are judged only when a variant is involved.
+            RefuseIndexSharing(plan, evicted);
+            // The variant name rule is judged only when a variant is involved.
             if (_variantKeys.Count != 0 || admitted.Any(stored => stored.Variant != null))
-            {
                 RefuseVariantNameSharing(plan);
-                RefuseVariantIndexSharing(plan, evicted);
-            }
 
             return plan;
         }
@@ -3472,62 +3495,41 @@ namespace GameCult.Caching
             }
         }
 
-        // The one index rule, judged on the commit's result whatever the write order: a variant may not share an indexed
-        // value with another record. It reads the truthful held index (every holder of a value), minus the records this
-        // commit replaces or removes, plus the records it lands. Plain-vs-plain sharing is not this rule's business.
-        // A unique index maps a value to one key at lookup; a variant sharing it would be found in place of its
-        // holder or lose the value, and the store would refuse to reopen.
-        private void RefuseVariantIndexSharing(VariantPlan plan, IReadOnlyList<CultStoredDocument> evicted)
+        // The one index rule, judged on the commit's result whatever the write order: within one document type and one
+        // [CultIndex] alias, no two records hold one non-blank value. The holders of a value are the held key (unless this
+        // admission replaces or evicts it) plus every landing key projecting it; two distinct holders refuse, naming both
+        // keys and the index and never the value. One pass over what lands, one lookup per (index, value).
+        private void RefuseIndexSharing(VariantPlan plan, IReadOnlyList<CultStoredDocument> evicted)
         {
             var landing = plan.Admitted.Concat(plan.Dependents).ToList();
             if (landing.All(stored => stored.Descriptor.IndexAccessors.Count == 0))
                 return;
             var replaced = new HashSet<string>(
                 plan.Admitted.Concat(evicted).Concat(plan.Dependents).Select(stored => stored.Key.Value), StringComparer.Ordinal);
-            var landingByKey = landing.ToDictionary(stored => stored.Key.Value, StringComparer.Ordinal);
-
-            bool IsVariant(string key) =>
-                landingByKey.TryGetValue(key, out var landed) ? landed.Variant != null : _variantKeys.Contains(key);
-
-            // One pass over what lands, one lookup per (index, value): the rule is linear in the records landing.
-            var landedValues = new List<(CultStoredDocument Stored, (Type Type, string Alias) Index, string Value)>();
             var landed = new Dictionary<((Type Type, string Alias) Index, string Value), List<string>>();
+            var schemaNames = landing.Select(stored => stored.Descriptor).GroupBy(descriptor => descriptor.DocumentType)
+                .ToDictionary(group => group.Key, group => group.First().SchemaName);
             foreach (var stored in landing)
             {
                 foreach (var (alias, value) in plan.Projections[stored.Key.Value].Indexes)
                 {
-                    var index = (stored.Descriptor.DocumentType, alias);
-                    landedValues.Add((stored, index, value));
-                    if (!landed.TryGetValue((index, value), out var landedKeys))
-                        landed[(index, value)] = landedKeys = new List<string>();
-                    landedKeys.Add(stored.Key.Value);
+                    var slot = ((stored.Descriptor.DocumentType, alias), value);
+                    if (!landed.TryGetValue(slot, out var keys))
+                        landed[slot] = keys = new List<string>();
+                    keys.Add(stored.Key.Value);
                 }
             }
 
-            var holdersOf = new Dictionary<((Type Type, string Alias) Index, string Value), (string[] All, string[] Variants)>();
-            foreach (var (stored, index, value) in landedValues)
+            foreach (var ((index, value), landedKeys) in landed.OrderBy(pair => pair.Key.Index.Alias, StringComparer.Ordinal))
             {
-                if (!holdersOf.TryGetValue((index, value), out var known))
-                {
-                    var all = (_indexes.TryGetValue(index, out var held) && held.TryGetValue(value, out var heldKeys)
-                            ? heldKeys.Where(heldKey => !replaced.Contains(heldKey))
-                            : Enumerable.Empty<string>())
-                        .Concat(landed[(index, value)])
-                        .Distinct(StringComparer.Ordinal)
-                        .ToArray();
-                    holdersOf[(index, value)] = known = (all, all.Where(IsVariant).ToArray());
-                }
-
-                var self = stored.Key.Value;
-                var holder = known.All.FirstOrDefault(candidate => candidate != self);
-                if (stored.Variant != null && holder != null)
+                var holders = landedKeys.AsEnumerable();
+                if (_indexes.TryGetValue(index, out var held) && held.TryGetValue(value, out var heldKey) && !replaced.Contains(heldKey))
+                    holders = holders.Append(heldKey);
+                var distinct = holders.Distinct(StringComparer.Ordinal).OrderBy(key => key, StringComparer.Ordinal).Take(2).ToArray();
+                if (distinct.Length > 1)
                     throw new InvalidOperationException(
-                        $"Variant {self} and {holder} both hold index {index.Alias} '{value}'; a variant must override its indexed member.");
-                var variantHolder = known.Variants.FirstOrDefault(candidate => candidate != self);
-                if (stored.Variant == null && variantHolder != null)
-                    throw new InvalidOperationException(
-                        $"Record {self} and variant {variantHolder} both hold index {index.Alias} '{value}'; " +
-                        "a variant may not share an indexed value with another record.");
+                        $"Records {distinct[0]} and {distinct[1]} ({schemaNames[index.Type]}) " +
+                        $"both hold unique index '{index.Alias}'; an index value names one record.");
             }
         }
 
@@ -3633,7 +3635,7 @@ namespace GameCult.Caching
             if (projection.Name != null)
                 MapOf(_names, type)[projection.Name] = stored.Key.Value;
             foreach (var (alias, value) in projection.Indexes)
-                AddHolder(_indexes, (type, alias), value, stored.Key.Value);
+                MapOf(_indexes, (type, alias))[value] = stored.Key.Value;
         }
 
         // Documents are mutable, so a name or index value may have changed since it was indexed: drop by key.
@@ -3645,26 +3647,7 @@ namespace GameCult.Caching
             if (_names.TryGetValue(type, out var names))
                 RemoveKey(names, stored.Key.Value);
             foreach (var pair in _indexes.Where(pair => pair.Key.Type == type))
-                RemoveHolder(pair.Value, stored.Key.Value);
-        }
-
-        private static void AddHolder(Dictionary<(Type Type, string Alias), Dictionary<string, List<string>>> indexes, (Type, string) index, string value, string key)
-        {
-            if (!indexes.TryGetValue(index, out var map))
-                indexes[index] = map = new Dictionary<string, List<string>>(StringComparer.Ordinal);
-            if (!map.TryGetValue(value, out var keys))
-                map[value] = keys = new List<string>();
-            keys.Remove(key);
-            keys.Add(key);
-        }
-
-        private static void RemoveHolder(Dictionary<string, List<string>> map, string key)
-        {
-            foreach (var pair in map.ToArray())
-            {
-                if (pair.Value.Remove(key) && pair.Value.Count == 0)
-                    map.Remove(pair.Key);
-            }
+                RemoveKey(pair.Value, stored.Key.Value);
         }
 
         private static Dictionary<string, string> MapOf<TKey>(Dictionary<TKey, Dictionary<string, string>> maps, TKey key)
@@ -4648,13 +4631,17 @@ namespace GameCult.Caching
         /// <param name="holdsIds">Whether the record's payload holds element ids, or null when the caller cannot tell.</param>
         /// <param name="registry">The registry the payload was encoded with. Given, the write decides the header for copied records that registry can read. It never decides ownership: the answer is the same lent or not. <paramref name="catalogEntry"/> alone owns the record at the key when it declares the stored id (its own or one it lists compatible), or when it is the type that reads the stored entry and reads it whole, so an older id of its own schema name it reads whole is its own and is restamped. Everything else is refused with the file left as it was: a record of another registered type included, whatever the registry holds, and a record it would read only by dropping persisted slots. Retyping a key is a removal and an add. It serves this call only: the store keeps no registry.</param>
         /// <remarks>The call holds the store's gate while it runs. User code it runs must not enter a cache or another store; that throws <see cref="InvalidOperationException"/>.</remarks>
-        /// <exception cref="InvalidOperationException">The store is attached to a cache; write through the cache.</exception>
+        /// <exception cref="InvalidOperationException">The store is attached to a cache; write through the cache. Also thrown when the record's type declares a <see cref="CultIndexAttribute"/>, and when the catalog entry declares an index alias and the registry lent for the call does not hold the type (none, or another): the call cannot tell a unique index from a role, so such records are written through a cache.</exception>
         /// <exception cref="CultStoreUnreadableException">The file at the path is not a store this runtime can read.</exception>
         public void WriteRecord(CultPersistedRecord record, CultSchemaCatalogEntry catalogEntry, bool? holdsIds = null, CultDocumentRegistry? registry = null)
         {
             if (record == null) throw new ArgumentNullException(nameof(record));
             if (catalogEntry == null) throw new ArgumentNullException(nameof(catalogEntry));
-            Cacheless(registry, () => WriteOne(record, catalogEntry, holdsIds));
+            Cacheless(registry, () =>
+            {
+                RefuseUniqueIndexedCacheless(AttachedRegistry, catalogEntry);
+                WriteOne(record, catalogEntry, holdsIds);
+            });
         }
 
         /// <summary>
@@ -4671,7 +4658,7 @@ namespace GameCult.Caching
         /// <param name="storedAt">The stored-at stamp, or null for now.</param>
         /// <param name="registry">The registry that describes and encodes the document, or null for <see cref="CultDocumentRegistry.Shared"/>. The document type's entry is taken from it, and the registry decides the header for copied records it can read. It never decides ownership, so the answer is the same for any registry that holds the type: the document's entry owns a record whose id it declares (its own or one it lists compatible), and a record of an older id of its own schema name that it reads whole; everything else is refused, another registered type's record included, and a record it would read only by dropping persisted slots. Retyping a key is a removal and an add. It serves this call only: the store keeps no registry.</param>
         /// <remarks>The call holds the store's gate while it runs. User code it runs (property getters while the document is encoded, constructors while a copied record is read) must not enter a cache or another store; that throws <see cref="InvalidOperationException"/>, carried by the encoder's wrapper when the code ran inside it.</remarks>
-        /// <exception cref="InvalidOperationException">The store is attached to a cache; write through the cache.</exception>
+        /// <exception cref="InvalidOperationException">The store is attached to a cache; write through the cache. Also thrown when the record's type declares a <see cref="CultIndexAttribute"/>, and when the catalog entry declares an index alias and the registry lent for the call does not hold the type (none, or another): the call cannot tell a unique index from a role, so such records are written through a cache.</exception>
         /// <exception cref="CultStoreUnreadableException">The file at the path is not a store this runtime can read.</exception>
         /// <exception cref="CultElementIdException">The document holds an element id or list a cache write refuses.</exception>
         public void WriteDocument<TDocument>(CultRecordKey key, TDocument document, string? storedAt = null, CultDocumentRegistry? registry = null)
@@ -4680,6 +4667,7 @@ namespace GameCult.Caching
             if (document == null) throw new ArgumentNullException(nameof(document));
             var resolvedRegistry = registry ?? CultDocumentRegistry.Shared;
             var catalogEntry = resolvedRegistry.GetRequired<TDocument>().ToCatalogEntry();
+            RefuseUniqueIndexedCacheless(resolvedRegistry, catalogEntry);
             Cacheless(resolvedRegistry, () =>
             {
                 var ids = CultElementIds.Plan(typeof(TDocument), document, key.Value, deterministic: false);
@@ -4705,6 +4693,19 @@ namespace GameCult.Caching
             });
         }
 
+        // A unique index is judged against every held record, which a cacheless write does not hold. A write is refused when the
+        // registry lent for the call holds a type with a [CultIndex] under the schema id, and also when the entry declares an index
+        // alias the call cannot classify (no registry, or one not holding the type): the catalog does not say unique from role.
+        private static void RefuseUniqueIndexedCacheless(CultDocumentRegistry? registry, CultSchemaCatalogEntry entry)
+        {
+            var unique = registry != null && registry.HoldsUniqueIndex(entry.SchemaId);
+            var unclassified = entry.Members.Any(member => member.IndexAlias != null) && (registry == null || !registry.Declared(entry.SchemaId));
+            if (unique || unclassified)
+                throw new InvalidOperationException(
+                    "A record of a type with a unique index is written through a cache; a cacheless write cannot judge uniqueness" +
+                    (unclassified ? " and the registry lent for the call does not say whether this schema's index is unique." : "."));
+        }
+
         private void WriteOne(CultPersistedRecord record, CultSchemaCatalogEntry catalogEntry, bool? holdsIds)
         {
             using (AcquireLock(wait: true))
@@ -4727,7 +4728,7 @@ namespace GameCult.Caching
             RefuseUndeclaredOnDisk(durable, upserts, removals, checks);
             if (upserts.Count == 0 && removals.Count == 0 && (checks.Any() || StagedChecks.Count > 0))
                 return Array.Empty<(CultStagedRecord, string)>();
-            RefuseWriteIntoMovedVariantStore(durable, upserts, removals);
+            RefuseWriteIntoMovedStore(durable, upserts, removals);
             var durableRecords = durable?.Snapshot.Records ?? Array.Empty<CultPersistedRecord>();
             // A record written over one the store holds is stored at a storedAt later than the one it replaces, whoever wrote that.
             var replaced = durableRecords.ToDictionary(record => record.Key, record => record.StoredAt, StringComparer.Ordinal);
@@ -4812,10 +4813,11 @@ namespace GameCult.Caching
             return false;
         }
 
-        private void RefuseWriteIntoMovedVariantStore(Durable? durable, IReadOnlyCollection<CultStagedRecord> upserts, IReadOnlyCollection<string> removals)
+        private void RefuseWriteIntoMovedStore(Durable? durable, IReadOnlyCollection<CultStagedRecord> upserts, IReadOnlyCollection<string> removals)
         {
             var records = durable?.Snapshot.Records ?? Array.Empty<CultPersistedRecord>();
-            if (records.All(record => record.Variant == null) && upserts.All(staged => staged.Record.Variant == null))
+            if (records.All(record => record.Variant == null) && upserts.All(staged => staged.Record.Variant == null) &&
+                !upserts.Any(staged => AttachedRegistry?.HoldsUniqueIndex(staged.Entry.SchemaId) == true))
                 return;
             var changed = new HashSet<string>(StringComparer.Ordinal);
             var versions = records.ToDictionary(record => record.Key, record => durable!.Version(record.Key), StringComparer.Ordinal);
@@ -4852,9 +4854,9 @@ namespace GameCult.Caching
                 },
                 inner => new CultWriteConflictException(
                     Cache == null
-                        ? $"{this} holds a variant and was written by a writer with no CultCache, which cannot resolve variants; nothing was written. " +
+                        ? $"{this} holds a variant or a unique index and was written by a writer with no CultCache, which cannot resolve variants; nothing was written. " +
                           $"Records it would have written or removed: {string.Join(", ", recordKeys.Select(key => $"'{key}'"))}; records that differ from what the writer has read: {string.Join(", ", changedKeys.Select(key => $"'{key}'"))}."
-                        : $"{this} changed since this cache last read it, and it holds a variant, which resolves against other records; nothing was written. " +
+                        : $"{this} changed since this cache last read it, and it holds a variant or a record with a unique index, which resolve against other records; nothing was written. " +
                           $"Records this write would have written or removed: {string.Join(", ", recordKeys.Select(key => $"'{key}'"))}; records that changed: {string.Join(", ", changedKeys.Select(key => $"'{key}'"))}. " +
                           (inner == null
                               ? "The cache reloaded them; retry the write against what the store holds now."

src/GameCult.Caching/CultDocumentContracts.cs

@@ -38,6 +38,7 @@ namespace GameCult.Caching
     {
     }
 
+    // A unique lookup: within one document type, a non-blank value names one record. Also filterable by CultNet selection.
     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = true, AllowMultiple = false)]
     public sealed class CultIndexAttribute : Attribute
     {
@@ -49,6 +50,19 @@ namespace GameCult.Caching
         public string? Alias { get; }
     }
 
+    // Names the member's selection and reference role (the alias, or the member name). Implies nothing about uniqueness:
+    // many records may hold one value, and a role member is never indexed for lookup.
+    [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = true, AllowMultiple = false)]
+    public sealed class CultRoleAttribute : Attribute
+    {
+        public CultRoleAttribute(string? alias = null)
+        {
+            Alias = alias;
+        }
+
+        public string? Alias { get; }
+    }
+
     [AttributeUsage(AttributeTargets.Field | AttributeTargets.Property, Inherited = true)]
     public sealed class CultReferenceAttribute : Attribute
     {

src/GameCult.Caching/README.md

@@ -22,9 +22,12 @@ public sealed class ItemData
 
     [Key(1)]
     [CultIndex]
-    public string Category = string.Empty;
+    public string Sku = string.Empty;
 
     [Key(2)]
+    public string Category = string.Empty;
+
+    [Key(3)]
     public int Value;
 }
 ```
@@ -33,7 +36,8 @@ Available cache attributes:
 
 - `CultDocument(schemaName, schemaVersion)`
 - `CultName`
-- `CultIndex(alias?)`
+- `CultIndex(alias?)`: a unique lookup. Within one document type, a non-blank value names one record; a commit that would leave two records holding one is refused, and a store holding such a pair refuses to load. Uniqueness is judged by a `CultCache` over the single-file store; a cacheless `WriteDocument`/`WriteRecord` of such a type is refused (also when the catalog declares an index alias the call cannot classify), and concurrent writers on a directory store are not covered (`unique-index-directory-store`). A value is culture-invariant, and a number is its canonical decimal (`1.0m` and `1.00m`, `0.0` and `-0.0` are one value).
+- `CultRole(alias?)`: a selection and reference role. Many records may share a value; it is never a lookup.
 - `CultGlobal`
 - `CultReference(targetType?, many: false)`
 
@@ -53,6 +57,7 @@ var cache = new CultCache();
 var handle = await cache.AddAsync(new ItemData
 {
     Name = "Potion",
+    Sku = "POT-1",
     Category = "Consumable",
     Value = 50
 });
@@ -66,7 +71,7 @@ Name and index lookups are driven from attributes, not manual registration.
 
 ```csharp
 var byName = cache.GetByName<ItemData>("Potion");
-var byIndex = cache.GetByIndex<ItemData>("Category", "Consumable");
+var byIndex = cache.GetByIndex<ItemData>("Sku", "POT-1");
 ```
 
 ### Explicit references
@@ -130,6 +135,7 @@ var cache = await CultCacheMessagePack.OpenAsync("Data.msgpack");
 var handle = await cache.UpsertAsync(new ItemData
 {
     Name = "Potion",
+    Sku = "POT-1",
     Category = "Consumable",
     Value = 50
 });

src/GameCult.Geometry/CultGeometryDocuments.cs

@@ -32,7 +32,7 @@ namespace GameCult.Geometry
         public string DomainId { get; set; } = string.Empty;
 
         [Key(1)]
-        [CultIndex]
+        [CultRole]
         public string RootKey { get; set; } = string.Empty;
 
         [Key(2)]
@@ -164,7 +164,7 @@ namespace GameCult.Geometry
         public CultRecordRef<CultGeometryDomainDocument> DomainKey { get; set; }
 
         [Key(2)]
-        [CultIndex]
+        [CultRole]
         public string WorkerGroup { get; set; } = string.Empty;
 
         [Key(3)]
@@ -326,7 +326,7 @@ namespace GameCult.Geometry
         public CultRecordRef<CultGeometrySelectedCutManifest> CutKey { get; set; }
 
         [Key(2)]
-        [CultIndex]
+        [CultRole]
         public string SelectedCutId { get; set; } = string.Empty;
 
         [Key(3)]

src/GameCult.Mesh/CultMeshBodyPublications.cs

@@ -34,7 +34,7 @@ namespace GameCult.Mesh
     public sealed class CultMeshBodyPublicationDocument
     {
         [Key(0), CultName] public string BodyId { get; set; } = string.Empty;
-        [Key(1), CultIndex] public string ProducerId { get; set; } = string.Empty;
+        [Key(1), CultRole] public string ProducerId { get; set; } = string.Empty;
         [Key(2)] public string SchemaId { get; set; } = string.Empty;
         [Key(3)] public int LayoutVersion { get; set; }
         [Key(4)] public long ByteSize { get; set; }

src/GameCult.Mesh/CultMeshCdn.cs

@@ -142,17 +142,17 @@ namespace GameCult.Mesh
 
         /// <summary>Artifact kind, such as asset, build, or package.</summary>
         [Key(1)]
-        [CultIndex]
+        [CultRole]
         public string Kind { get; set; } = CultMeshCdnArtifactKinds.Asset;
 
         /// <summary>Caller-defined artifact version.</summary>
         [Key(2)]
-        [CultIndex]
+        [CultRole]
         public string Version { get; set; } = string.Empty;
 
         /// <summary>SHA-256 hash of the full materialized artifact.</summary>
         [Key(3)]
-        [CultIndex]
+        [CultRole]
         public string ContentHash { get; set; } = string.Empty;
 
         /// <summary>Full materialized artifact size.</summary>

src/GameCult.Mesh/CultMeshEntityPrefabs.cs

@@ -193,12 +193,12 @@ namespace GameCult.Mesh
 
         /// <summary>Caller-defined package version.</summary>
         [Key(1)]
-        [CultIndex]
+        [CultRole]
         public string Version { get; set; } = string.Empty;
 
         /// <summary>Tool that authored the package, such as Brokkr Blender.</summary>
         [Key(2)]
-        [CultIndex]
+        [CultRole]
         public string SourceTool { get; set; } = string.Empty;
 
         /// <summary>Source scene name or path.</summary>
@@ -207,12 +207,12 @@ namespace GameCult.Mesh
 
         /// <summary>Source Blender collection name.</summary>
         [Key(4)]
-        [CultIndex]
+        [CultRole]
         public string SourceCollection { get; set; } = string.Empty;
 
         /// <summary>Stable hash of graph structure and referenced assets.</summary>
         [Key(5)]
-        [CultIndex]
+        [CultRole]
         public string ContentHash { get; set; } = string.Empty;
 
         /// <summary>Package creation timestamp in round-trip UTC format.</summary>

src/GameCult.Mesh/CultMeshSimulationFacts.cs

@@ -20,14 +20,14 @@ namespace GameCult.Mesh
         /// Stable fact identifier.
         /// </summary>
         [Key(0)]
-        [CultIndex]
+        [CultRole]
         public string FactId { get; set; } = string.Empty;
 
         /// <summary>
         /// Shard containing the simulation.
         /// </summary>
         [Key(1)]
-        [CultIndex]
+        [CultRole]
         public string ShardId { get; set; } = string.Empty;
 
         /// <summary>
@@ -40,21 +40,21 @@ namespace GameCult.Mesh
         /// Simulation frame or tick.
         /// </summary>
         [Key(3)]
-        [CultIndex]
+        [CultRole]
         public long Frame { get; set; }
 
         /// <summary>
         /// Subject the fact is about.
         /// </summary>
         [Key(4)]
-        [CultIndex]
+        [CultRole]
         public string SubjectId { get; set; } = string.Empty;
 
         /// <summary>
         /// Fact kind, such as hit, collision, or ownership.
         /// </summary>
         [Key(5)]
-        [CultIndex]
+        [CultRole]
         public string ClaimKind { get; set; } = string.Empty;
 
         /// <summary>

src/GameCult.Mesh/docs/public-api.md

@@ -321,15 +321,16 @@ var bySchema = documents.DocumentBySchema("gamecult.aetheria.station_refit.v1");
 Typed collections use the same one-call style:
 
 ```csharp
-var allies = CultMesh.CollectionByIndex<PlayerShipDocument>(
+// A [CultIndex] value is unique within its type, so the handle holds at most one record.
+var flagship = CultMesh.CollectionByIndex<PlayerShipDocument>(
     node,
-    "Faction",
-    "au");
+    "CallSign",
+    "au-1");
 
-var currentAllies = await allies.LatestAsync();
-using var changes = allies.WatchChanges(change => UpdateRoster(change));
+var currentFlagship = await flagship.LatestAsync();
+using var changes = flagship.WatchChanges(change => UpdateRoster(change));
 
-var collections = CultMesh.Collections(allies);
+var collections = CultMesh.Collections(flagship);
 var roster = await collections.LatestAsync<PlayerShipDocument>();
 using var rosterChanges = collections.WatchChanges<PlayerShipDocument>(RenderRoster);
 ```

src/GameCult.Networking/CultNetDatabase.cs

@@ -315,6 +315,22 @@ namespace GameCult.Networking
         public CultNetSelectionCursorKey? CursorKey { get; set; }
     }
 
+    /// <summary>
+    /// The typed changes (<see cref="CultNetDatabaseChange{T}"/> boxed) one cache commit made, in the order the cache admitted them.
+    /// <see cref="Id"/> is opaque and unique among the commits of one database instance.
+    /// </summary>
+    public sealed class CultNetDatabaseCommit
+    {
+        public CultNetDatabaseCommit(string id, IReadOnlyList<object> changes)
+        {
+            Id = id;
+            Changes = changes;
+        }
+
+        public string Id { get; }
+        public IReadOnlyList<object> Changes { get; }
+    }
+
     /// <summary>
     /// A typed domain change emitted by a CultNet database surface.
     /// </summary>
@@ -587,6 +603,7 @@ namespace GameCult.Networking
         private readonly Dictionary<(string SchemaId, string RecordKey), long> _lastWriteSequence =
             new();
         private readonly Subject<object> _changes = new();
+        private readonly Subject<CultNetDatabaseCommit> _commits = new();
         private readonly IDisposable _cacheChanges;
         private readonly IDisposable _cacheJournal;
         // What a write door of this database knows about the change it is admitting and the cache does not: the wire
@@ -1148,6 +1165,17 @@ namespace GameCult.Networking
             return _changes;
         }
 
+        /// <summary>
+        /// Watches changes as the cache commits that made them: one event per commit, after every change of it was published to
+        /// <see cref="WatchAllChanges"/>. A consumer that forwards changes to a replica forwards a commit as a unit, so the replica
+        /// can judge the result of the commit and not each record's intermediate state.
+        /// </summary>
+        public Observable<CultNetDatabaseCommit> WatchCommits()
+        {
+            ThrowIfDisposed();
+            return _commits;
+        }
+
         /// <summary>
         /// Watches one record.
         /// </summary>
@@ -1215,6 +1243,7 @@ namespace GameCult.Networking
             }
 
             _changes.Dispose();
+            _commits.Dispose();
         }
 
         // The cache is the one owner of "a change was committed"; the journal is this database's one decision point and its
@@ -1231,6 +1260,8 @@ namespace GameCult.Networking
             }
 
             List<Exception>? failures = null;
+            // One journal call is one admission, so one commit; its first Sequence names it.
+            var commit = new CommitGroup(changes.Count == 0 ? "0" : changes[0].Sequence.ToString(System.Globalization.CultureInfo.InvariantCulture));
             List<CultNetBurnedSequence>? burned = null;
             List<Exception>? burnCauses = null;
             foreach (var change in changes)
@@ -1288,7 +1319,10 @@ namespace GameCult.Networking
                 }
 
                 lock (_logGate)
-                    _stash[change.Sequence] = new Publication(documentType, kind, change.Key, descriptor.SchemaId, shard, change.Document, change.PreviousDocument);
+                {
+                    _stash[change.Sequence] = new Publication(documentType, kind, change.Key, descriptor.SchemaId, shard, change.Document, change.PreviousDocument, commit);
+                    commit.Unpublished++;
+                }
             }
 
             // Every change is stashed and will be published; the writer hears of a failed log afterwards, in one exception.
@@ -1321,8 +1355,9 @@ namespace GameCult.Networking
             Publish(publication);
         }
 
-        private void Publish(Publication publication) =>
-            PublishUntyped(
+        private void Publish(Publication publication)
+        {
+            var change = PublishUntyped(
                 publication.DocumentType,
                 publication.Kind,
                 publication.Key,
@@ -1330,6 +1365,19 @@ namespace GameCult.Networking
                 publication.Shard,
                 publication.Document,
                 publication.PreviousDocument);
+            CultNetDatabaseCommit? finished = null;
+            lock (_logGate)
+            {
+                var commit = publication.Commit;
+                if (change != null)
+                    commit.Published.Add(change);
+                if (--commit.Unpublished == 0 && commit.Published.Count > 0)
+                    finished = new CultNetDatabaseCommit(commit.Id, commit.Published.ToArray());
+            }
+
+            if (finished != null)
+                _commits.OnNext(finished);
+        }
 
         private void RecordReplicatedEntry(
             CultNetShardDescriptor shard,
@@ -1467,8 +1515,10 @@ namespace GameCult.Networking
                 string schemaId,
                 CultNetShardDescriptor shard,
                 object? document,
-                object? previousDocument)
+                object? previousDocument,
+                CommitGroup commit)
             {
+                Commit = commit;
                 DocumentType = documentType;
                 Kind = kind;
                 Key = key;
@@ -1485,6 +1535,16 @@ namespace GameCult.Networking
             public CultNetShardDescriptor Shard { get; }
             public object? Document { get; }
             public object? PreviousDocument { get; }
+            public CommitGroup Commit { get; }
+        }
+
+        // The changes of one cache admission, counted down as they are published. Guarded by _logGate.
+        private sealed class CommitGroup
+        {
+            public CommitGroup(string id) => Id = id;
+            public string Id { get; }
+            public int Unpublished { get; set; }
+            public List<object> Published { get; } = new();
         }
 
         private sealed class DoorContext
@@ -1964,7 +2024,7 @@ namespace GameCult.Networking
             return $"{schemaId}:{key.Value}";
         }
 
-        private void PublishUntyped(
+        private object? PublishUntyped(
             Type documentType,
             CultNetDatabaseChangeKind kind,
             CultRecordKey key,
@@ -1987,6 +2047,8 @@ namespace GameCult.Networking
             {
                 _changes.OnNext(change);
             }
+
+            return change;
         }
 
         // No shard owns a schema and key that no descriptor matches, and nothing is written to one: every write path refuses.

src/GameCult.Networking/CultNetDatabaseServer.cs

@@ -765,14 +765,41 @@ namespace GameCult.Networking
         {
             // Keys this subscriber only ever received as a refusal: it was never given them as records.
             var refused = new HashSet<string>(StringComparer.Ordinal);
-            return _database.WatchAllChanges().Subscribe(change =>
+            return _database.WatchCommits().Subscribe(commit =>
             {
-                var outbound = DeliverChange(change, subscriptionId, selection, refused, error => peer.SendCultNet(error));
-                if (outbound != null)
-                    peer.SendCultNet(outbound);
+                foreach (var message in DeliverCommit(commit, subscriptionId, selection, refused, error => peer.SendCultNet(error)))
+                    peer.SendCultNet(message);
             });
         }
 
+        // One subscriber's view of one commit. Its changes go out together, tagged with the commit, so a replica applies them as one.
+        internal IReadOnlyList<CultNetDatabaseChangeRawMessage> DeliverCommit(
+            CultNetDatabaseCommit commit,
+            string subscriptionId,
+            CultNetSelection selection,
+            HashSet<string> refused,
+            Action<CultNetErrorMessage> sendError)
+        {
+            var outbound = new List<CultNetDatabaseChangeRawMessage>();
+            foreach (var change in commit.Changes)
+            {
+                var message = DeliverChange(change, subscriptionId, selection, refused, sendError);
+                if (message != null)
+                    outbound.Add(message);
+            }
+
+            if (outbound.Count > 1)
+            {
+                foreach (var message in outbound)
+                {
+                    message.CommitId = commit.Id;
+                    message.CommitCount = outbound.Count;
+                }
+            }
+
+            return outbound;
+        }
+
         // One subscriber's view of one change. A variant is not a record CultNet can carry (Q6): the subscriber is told, by key, and
         // is not later told the variant was removed, because it never held it.
         internal CultNetDatabaseChangeRawMessage? DeliverChange(

src/GameCult.Networking/CultNetDatabaseSubscriptionClient.cs

@@ -29,6 +29,14 @@ namespace GameCult.Networking
         private readonly ConcurrentDictionary<string, PendingSubscription> _initialSnapshots = new();
         private readonly ConcurrentDictionary<string, CultNetDatabaseSubscriptionDeliveryMode> _deliveryModes =
             new(StringComparer.Ordinal);
+        // Changes of a commit that has not fully arrived, by subscription and commit id.
+        // Guarded by its own lock: the queue fills it, Unsubscribe and Dispose evict. A commit that does not complete is bounded
+        // by MaxPendingCommits and by MaxBufferedChanges, and a violation faults the client.
+        private const int MaxPendingCommits = 64;
+        // Policy: the most changes the incomplete commits may announce between them, the bound on what the buffer can hold. It
+        // sits far above any commit a source makes; a commit that announces more than this could not be held at all.
+        private const int MaxBufferedChanges = 1_000_000;
+        private readonly Dictionary<(string SubscriptionId, string CommitId), PendingCommit> _commits = new();
         private readonly object _queueLock = new();
         private Task _queue = Task.CompletedTask;
         private bool _disposed;
@@ -48,6 +56,15 @@ namespace GameCult.Networking
         /// <summary>Raised after a live change has been applied to the local typed cache.</summary>
         public event Action<CultNetReplicatedDocumentChange>? Changed;
 
+        /// <summary>
+        /// Raised when the local cache refuses a replicated commit. The replica then differs from its source; the client applies
+        /// no further changes and reports <see cref="Fault"/> until it is replaced by a new subscription.
+        /// </summary>
+        public event Action<Exception>? Faulted;
+
+        /// <summary>The refusal that stopped replication, or null while the replica is intact.</summary>
+        public Exception? Fault { get; private set; }
+
         /// <summary>Gets the local reactive cache receiving replicated documents.</summary>
         public CultCache Cache => _cache;
 
@@ -109,6 +126,8 @@ namespace GameCult.Networking
             CultNetDatabaseSubscriptionDeliveryMode deliveryMode = CultNetDatabaseSubscriptionDeliveryMode.ReplicateToCache)
         {
             if (_disposed) throw new ObjectDisposedException(nameof(CultNetDatabaseSubscriptionClient));
+            if (Fault != null)
+                throw new InvalidOperationException("The replica refused a commit and differs from its source; subscribe with a new client.", Fault);
             if (!_client.Connected) throw new InvalidOperationException("CultNet schema client must be connected before subscribing.");
             if (string.IsNullOrWhiteSpace(subscriptionId)) throw new ArgumentException("Subscription id is required.", nameof(subscriptionId));
 
@@ -166,6 +185,9 @@ namespace GameCult.Networking
             if (_disposed) return;
             if (string.IsNullOrWhiteSpace(subscriptionId)) throw new ArgumentException("Subscription id is required.", nameof(subscriptionId));
             _deliveryModes.TryRemove(subscriptionId, out _);
+            lock (_commits)
+                foreach (var held in _commits.Keys.Where(key => key.SubscriptionId == subscriptionId).ToArray())
+                    _commits.Remove(held);
             _client.SendCultNet(new CultNetDatabaseUnsubscribeMessage
             {
                 MessageId = Guid.NewGuid().ToString("N"),
@@ -181,6 +203,8 @@ namespace GameCult.Networking
                 pending.Completion.TrySetException(new ObjectDisposedException(nameof(CultNetDatabaseSubscriptionClient)));
             _initialSnapshots.Clear();
             _deliveryModes.Clear();
+            lock (_commits)
+                _commits.Clear();
             _client.Dispose();
         }
 
@@ -211,48 +235,110 @@ namespace GameCult.Networking
 
         private void HandleChange(CultNetDatabaseChangeRawMessage message)
         {
-            Enqueue(async () =>
+            Enqueue(() =>
             {
                 var deliveryMode = _deliveryModes.TryGetValue(message.SubscriptionId, out var configured)
                     ? configured
                     : CultNetDatabaseSubscriptionDeliveryMode.ReplicateToCache;
-                if (string.Equals(message.ChangeKind, "removed", StringComparison.Ordinal))
+                // Live delivery applies nothing, so there is no commit to judge; each change is reported as it arrives.
+                if (deliveryMode != CultNetDatabaseSubscriptionDeliveryMode.ReplicateToCache || message.CommitId == null || !(message.CommitCount > 1))
+                    return Apply(deliveryMode, new[] { message });
+
+                // The commit's other changes follow on this connection; the replica applies them as one commit.
+                var held = (message.SubscriptionId, message.CommitId);
+                PendingCommit? pending;
+                lock (_commits)
                 {
-                    if (deliveryMode == CultNetDatabaseSubscriptionDeliveryMode.ReplicateToCache)
-                        await DeleteAsync(message).ConfigureAwait(false);
-                    Changed?.Invoke(new CultNetReplicatedDocumentChange(
-                        message.SubscriptionId,
-                        "removed",
-                        message.RecordKey ?? string.Empty,
-                        message.SchemaId ?? string.Empty,
-                        null));
-                    return;
+                    // A straggler of a subscription that was ended, or never made, is not buffered. Judged under the lock that
+                    // Unsubscribe evicts under: a check before it could pass, lose the race to the eviction, and then buffer.
+                    if (Fault != null || !_deliveryModes.ContainsKey(message.SubscriptionId))
+                        return Task.CompletedTask;
+                    var count = message.CommitCount!.Value;
+                    var refusal = !_commits.TryGetValue(held, out pending)
+                            ? (_commits.Count >= MaxPendingCommits
+                                ? $"more than {MaxPendingCommits} commits are incomplete at once"
+                                : (long)count + _commits.Sum(entry => (long)entry.Value.Announced) > MaxBufferedChanges
+                                    ? $"commit '{message.CommitId}' announces {count} changes; the incomplete commits may announce {MaxBufferedChanges} between them"
+                                    : null)
+                            : pending.Announced != count
+                                ? $"commit '{message.CommitId}' announces {pending.Announced} and {count} changes"
+                                : pending.Ids.Contains(message.MessageId)
+                                    ? $"commit '{message.CommitId}' delivered message '{message.MessageId}' twice"
+                                    : null;
+                    if (refusal != null)
+                    {
+                        Break(new InvalidOperationException($"CultNet subscription '{message.SubscriptionId}': {refusal}."));
+                        return Task.CompletedTask;
+                    }
+
+                    if (!_commits.TryGetValue(held, out pending))
+                        _commits[held] = pending = new PendingCommit(count);
+                    pending.Ids.Add(message.MessageId);
+                    pending.Messages.Add(message);
+                    if (pending.Messages.Count < count)
+                        return Task.CompletedTask;
+                    _commits.Remove(held);
                 }
 
-                if (message.Document == null) return;
-                var document = deliveryMode == CultNetDatabaseSubscriptionDeliveryMode.Live
-                    ? _documents.DeserializeRawDocument(message.Document)
-                    : await _documents.ApplyRawDocumentPutMessageAsync(
-                        _cache,
-                        new CultNetDocumentPutRawMessage
-                        {
-                            MessageId = message.MessageId,
-                            Document = message.Document
-                        }).ConfigureAwait(false);
-                Changed?.Invoke(new CultNetReplicatedDocumentChange(
-                    message.SubscriptionId,
-                    message.ChangeKind,
-                    message.Document.RecordKey,
-                    message.Document.SchemaId,
-                    document));
+                return Apply(deliveryMode, pending.Messages);
             });
         }
 
-        private Task DeleteAsync(CultNetDatabaseChangeRawMessage message)
+        private sealed class PendingCommit
         {
-            if (string.IsNullOrWhiteSpace(message.RecordKey) || string.IsNullOrWhiteSpace(message.SchemaId)) return Task.CompletedTask;
-            _documents.ResolveDescriptorForSchemaId(message.SchemaId!);
-            _cache.Remove(new CultRecordKey(message.RecordKey!));
+            public PendingCommit(int announced) => Announced = announced;
+            public int Announced { get; }
+            public List<CultNetDatabaseChangeRawMessage> Messages { get; } = new();
+            public HashSet<string> Ids { get; } = new(StringComparer.Ordinal);
+        }
+
+        // The replica no longer matches its source: say so once, drop what was waiting, and apply nothing more.
+        private void Break(Exception error)
+        {
+            lock (_commits)
+            {
+                if (Fault != null)
+                    return;
+                Fault = error;
+                _commits.Clear();
+            }
+
+            Faulted?.Invoke(error);
+        }
+
+        private Task Apply(CultNetDatabaseSubscriptionDeliveryMode deliveryMode, IReadOnlyList<CultNetDatabaseChangeRawMessage> changes)
+        {
+            // A replica that refused a commit no longer matches its source. Applying later commits on top would hide that, so
+            // nothing more is applied: the fault is surfaced and the replica is rebuilt by subscribing again.
+            if (Fault != null)
+                return Task.CompletedTask;
+            IReadOnlyList<object?> applied;
+            try
+            {
+                applied = deliveryMode == CultNetDatabaseSubscriptionDeliveryMode.Live
+                    ? changes.Select(change => change.Document == null ? null : _documents.DeserializeRawDocument(change.Document)).ToArray()
+                    : _documents.ApplyRawChangesAsOneCommit(_cache, changes);
+            }
+            catch (Exception error)
+            {
+                Break(error);
+                return Task.CompletedTask;
+            }
+
+            for (var index = 0; index < changes.Count; index++)
+            {
+                var change = changes[index];
+                var removed = string.Equals(change.ChangeKind, "removed", StringComparison.Ordinal);
+                if (!removed && change.Document == null)
+                    continue;
+                Changed?.Invoke(new CultNetReplicatedDocumentChange(
+                    change.SubscriptionId,
+                    change.ChangeKind,
+                    removed ? change.RecordKey ?? string.Empty : change.Document!.RecordKey,
+                    removed ? change.SchemaId ?? string.Empty : change.Document!.SchemaId,
+                    removed ? null : applied[index]));
+            }
+
             return Task.CompletedTask;
         }
 

src/GameCult.Networking/CultNetDatabaseSubscriptionServer.cs

@@ -77,7 +77,20 @@ namespace GameCult.Networking
             {
                 if (_disposed) return;
                 foreach (var entry in _requests.ToArray())
-                    Reconcile(entry.Key, entry.Value);
+                {
+                    // Reconcile can run after the cache has admitted a commit and before Watch has seen it, so its diff can carry
+                    // changed values; it is held and sent as one commit of its own, as Watch's is, for the replica to judge whole.
+                    var outbox = _outbox = new CommitOutbox(Guid.NewGuid().ToString("N"));
+                    try
+                    {
+                        Reconcile(entry.Key, entry.Value);
+                    }
+                    finally
+                    {
+                        _outbox = null;
+                        outbox.Send(entry.Key.Peer);
+                    }
+                }
             }
         }
 
@@ -300,50 +313,76 @@ namespace GameCult.Networking
             SubscriptionKey key)
         {
             var legacyRequest = request.ToLegacyShape(subscriptionId);
-            return _database.WatchAllChanges().Subscribe(change =>
+            return _database.WatchCommits().Subscribe(commit =>
             {
                 lock (_lifecycleGate)
                 {
                     if (_disposed || !_requests.ContainsKey(key) || !_projections.TryGetValue(key, out var projection))
                         return;
-                    if (_authorizeRequest?.Invoke(legacyRequest, peer) == false)
-                    {
-                        Reconcile(key, request);
-                        return;
-                    }
-
-                    // D6: cites/cited are set-dependent - a change to row B can change whether row A
-                    // matches - so a hop-bearing selection runs the full diff-against-delivered
-                    // reconcile on every change instead of the single-row fast path.
-                    if (request.Selection.HasHop)
-                    {
-                        Reconcile(key, request);
-                        return;
-                    }
-
-                    var sourceRecordKey = ResolveChangeRecordKey(change);
-                    CultNetRawDocumentRecord? matched;
+                    // What this subscription sends for the commit is held and sent together, tagged with the commit, so the replica
+                    // applies it as one commit and judges the result.
+                    var outbox = _outbox = new CommitOutbox(commit.Id);
                     try
                     {
-                        matched = CreateMatchedRecord(change, request, peer);
+                        ForwardCommit(commit, request, key, projection, legacyRequest, peer, subscriptionId);
                     }
-                    catch (NotSupportedException refusal)
+                    finally
                     {
-                        // Q6: a variant is not a record CultNet can carry; the subscriber that would have received it is told, by key.
-                        peer.SendCultNet(CultNetErrorMessage.ForVariantUnsupported(refusal.Message));
-                        return;
+                        _outbox = null;
+                        outbox.Send(peer);
                     }
-
-                    ApplyProjectedChange(
-                        projection,
-                        sourceRecordKey,
-                        matched,
-                        peer,
-                        subscriptionId);
                 }
             });
         }
 
+        private void ForwardCommit(
+            CultNetDatabaseCommit commit,
+            SubscriptionRequest request,
+            SubscriptionKey key,
+            SubscriptionProjectionState projection,
+            CultNetDatabaseSubscribeMessage legacyRequest,
+            ICultNetSchemaServerPeer peer,
+            string subscriptionId)
+        {
+            if (_authorizeRequest?.Invoke(legacyRequest, peer) == false)
+            {
+                Reconcile(key, request);
+                return;
+            }
+
+            // D6: cites/cited are set-dependent - a change to row B can change whether row A
+            // matches - so a hop-bearing selection runs the full diff-against-delivered
+            // reconcile once per commit instead of the single-row fast path.
+            if (request.Selection.HasHop)
+            {
+                Reconcile(key, request);
+                return;
+            }
+
+            foreach (var change in commit.Changes)
+            {
+                var sourceRecordKey = ResolveChangeRecordKey(change);
+                CultNetRawDocumentRecord? matched;
+                try
+                {
+                    matched = CreateMatchedRecord(change, request, peer);
+                }
+                catch (NotSupportedException refusal)
+                {
+                    // Q6: a variant is not a record CultNet can carry; the subscriber that would have received it is told, by key.
+                    peer.SendCultNet(CultNetErrorMessage.ForVariantUnsupported(refusal.Message));
+                    continue;
+                }
+
+                ApplyProjectedChange(
+                    projection,
+                    sourceRecordKey,
+                    matched,
+                    peer,
+                    subscriptionId);
+            }
+        }
+
         private void Reconcile(SubscriptionKey key, SubscriptionRequest request)
         {
             if (!_projections.TryGetValue(key, out var projection)) return;
@@ -487,12 +526,15 @@ namespace GameCult.Networking
             string.Equals(left.SourceAgentId, right.SourceAgentId, StringComparison.Ordinal) &&
             string.Equals(left.SourceRole, right.SourceRole, StringComparison.Ordinal);
 
-        private static void SendUpsert(
+        // The commit being forwarded, under _lifecycleGate: the change messages it produces are held here, not sent one by one.
+        private CommitOutbox? _outbox;
+
+        private void SendUpsert(
             ICultNetSchemaServerPeer peer,
             string subscriptionId,
             CultNetRawDocumentRecord document,
             bool added) =>
-            peer.SendCultNet(new CultNetDatabaseChangeRawMessage
+            Deliver(peer, new CultNetDatabaseChangeRawMessage
             {
                 MessageId = Guid.NewGuid().ToString("N"),
                 SubscriptionId = subscriptionId,
@@ -500,11 +542,11 @@ namespace GameCult.Networking
                 Document = document
             });
 
-        private static void SendRemoval(
+        private void SendRemoval(
             ICultNetSchemaServerPeer peer,
             string subscriptionId,
             CultNetRawDocumentRecord document) =>
-            peer.SendCultNet(new CultNetDatabaseChangeRawMessage
+            Deliver(peer, new CultNetDatabaseChangeRawMessage
             {
                 MessageId = Guid.NewGuid().ToString("N"),
                 SubscriptionId = subscriptionId,
@@ -513,6 +555,38 @@ namespace GameCult.Networking
                 SchemaId = document.SchemaId
             });
 
+        private void Deliver(ICultNetSchemaServerPeer peer, CultNetDatabaseChangeRawMessage message)
+        {
+            if (_outbox is { } outbox)
+                outbox.Messages.Add(message);
+            else
+                peer.SendCultNet(message);
+        }
+
+        private sealed class CommitOutbox
+        {
+            private readonly string _commitId;
+
+            public CommitOutbox(string commitId) => _commitId = commitId;
+
+            public List<CultNetDatabaseChangeRawMessage> Messages { get; } = new();
+
+            public void Send(ICultNetSchemaServerPeer peer)
+            {
+                if (Messages.Count > 1)
+                {
+                    foreach (var message in Messages)
+                    {
+                        message.CommitId = _commitId;
+                        message.CommitCount = Messages.Count;
+                    }
+                }
+
+                foreach (var message in Messages)
+                    peer.SendCultNet(message);
+            }
+        }
+
         private void Withdraw(SubscriptionKey key, bool sendRemovals, bool forgetRequest)
         {
             if (_subscriptions.TryRemove(key, out var subscription))

src/GameCult.Networking/CultNetDocumentRegistry.cs

@@ -722,6 +722,49 @@ namespace GameCult.Networking
             return document;
         }
 
+        /// <summary>
+        /// Applies change messages to a cache as one commit, so the cache judges the result of the changes together and not the
+        /// state between them. Returns the applied document of each message, null for a removal. A refusal by the cache throws
+        /// and nothing is applied.
+        /// </summary>
+        internal IReadOnlyList<object?> ApplyRawChangesAsOneCommit(
+            CultCache cache,
+            IReadOnlyList<CultNetDatabaseChangeRawMessage> changes)
+        {
+            var applied = new object?[changes.Count];
+            var staged = new List<(Type? Type, object? Document, CultRecordKey Key)>(changes.Count);
+            for (var index = 0; index < changes.Count; index++)
+            {
+                var change = changes[index];
+                if (string.Equals(change.ChangeKind, "removed", StringComparison.Ordinal))
+                {
+                    if (string.IsNullOrWhiteSpace(change.RecordKey) || string.IsNullOrWhiteSpace(change.SchemaId))
+                        continue;
+                    ResolveDescriptorForSchemaId(change.SchemaId!);
+                    staged.Add((null, null, new CultRecordKey(change.RecordKey!)));
+                    continue;
+                }
+
+                if (change.Document == null)
+                    continue;
+                var document = DeserializeRawDocument(change.Document);
+                applied[index] = document;
+                staged.Add((ResolveDescriptorForRawDocument(change.Document).DocumentType, document, new CultRecordKey(change.Document.RecordKey)));
+            }
+
+            cache.Commit(batch =>
+            {
+                foreach (var (type, document, key) in staged)
+                {
+                    if (type == null)
+                        batch.Remove(key);
+                    else
+                        batch.Upsert(type, document!, key);
+                }
+            });
+            return applied;
+        }
+
         /// <summary>
         /// Decodes one validated raw document without materializing it in a CultCache replica.
         /// Use this for ephemeral reactive subscriptions whose callback is the consumer.
@@ -754,25 +797,22 @@ namespace GameCult.Networking
         }
 
         /// <summary>
-        /// Applies all documents from a raw snapshot response.
+        /// Applies all documents from a raw snapshot response as one commit, so a snapshot that moves a unique-index value
+        /// between records is judged on its result.
         /// </summary>
-        public async Task<IReadOnlyList<object>> ApplyRawSnapshotResponseAsync(
+        public Task<IReadOnlyList<object>> ApplyRawSnapshotResponseAsync(
             CultCache cache,
             CultNetSnapshotResponseRawMessage response)
         {
-            var applied = new List<object>(response.Documents.Length);
-            foreach (var document in response.Documents)
-            {
-                applied.Add(await ApplyRawDocumentPutMessageAsync(
-                    cache,
-                    new CultNetDocumentPutRawMessage
-                    {
-                        MessageId = response.MessageId,
-                        Document = document
-                    }).ConfigureAwait(false));
-            }
-
-            return applied;
+            var applied = ApplyRawChangesAsOneCommit(
+                cache,
+                response.Documents.Select(document => new CultNetDatabaseChangeRawMessage
+                {
+                    SubscriptionId = response.MessageId,
+                    ChangeKind = "added",
+                    Document = document
+                }).ToArray());
+            return Task.FromResult<IReadOnlyList<object>>(applied.Select(document => document!).ToArray());
         }
 
         internal CultDocumentDescriptor ResolveDescriptorForRawDocument(CultNetRawDocumentRecord document)

src/GameCult.Networking/CultNetSchemaMessages.cs

@@ -1179,6 +1179,17 @@ namespace GameCult.Networking
         /// Gets or sets the deleted schema id for removed changes.
         /// </summary>
         [Key("schemaId")] public string? SchemaId { get; set; }
+        /// <summary>
+        /// Gets or sets the identity of the cache commit this change belongs to. Optional and additive: a peer that does not
+        /// know the field ignores it and applies the change alone. Opaque to the receiver; equal ids on one subscription
+        /// name changes of one commit.
+        /// </summary>
+        [Key("commitId")] public string? CommitId { get; set; }
+        /// <summary>
+        /// Gets or sets how many change messages of this commit this subscription carries. Set with
+        /// <see cref="CommitId"/> when that is more than one; the receiver applies the commit once all have arrived.
+        /// </summary>
+        [Key("commitCount")] public int? CommitCount { get; set; }
     }
 
     /// <summary>

tests/GameCult.Caching.Tests/CultDocumentSelectionSurfaceTests.cs

@@ -226,8 +226,8 @@ namespace GameCult.Caching.Tests
         public void DuplicateIndexAliasOnTwoDifferentlyNamedMembersIsRefusedByName()
         {
             var type = Document("DupAlias");
-            Field(type, "First", typeof(string), Key(0), IndexAttr("shared"));
-            Field(type, "Second", typeof(string), Key(1), IndexAttr("shared"));
+            Field(type, "First", typeof(string), Key(0), RoleAttr("shared"));
+            Field(type, "Second", typeof(string), Key(1), RoleAttr("shared"));
             var message = Assert.Throws<InvalidOperationException>(() => CultDocumentRegistry.ForTypes(new[] { type.CreateType()! }))!.Message;
 
             Assert.That(message, Does.Contain("DupAlias"));
@@ -236,7 +236,7 @@ namespace GameCult.Caching.Tests
             Assert.That(message, Does.Contain("shared"));
         }
 
-        // R-AL/SM-6: a plain data member's bare name (it declares no [CultIndex], so its role in
+        // R-AL/SM-6: a plain data member's bare name (it declares no [CultRole], so its role in
         // ReferencesOf/ReferenceMembers falls back to its own MemberName) colliding with a reference
         // member's explicit alias. D10 above only groups members that declare an alias and misses
         // this; before the fix this registered without error and then every hop through the
@@ -246,7 +246,7 @@ namespace GameCult.Caching.Tests
         {
             var type = Document("OwnerCollision");
             Field(type, "Owner", typeof(string), Key(0));
-            Field(type, "Ref", typeof(CultRecordRef<FixtureLeafA>), Key(1), IndexAttr("Owner"));
+            Field(type, "Ref", typeof(CultRecordRef<FixtureLeafA>), Key(1), RoleAttr("Owner"));
             var message = Assert.Throws<InvalidOperationException>(() => CultDocumentRegistry.ForTypes(new[] { type.CreateType()! }))!.Message;
 
             Assert.That(message, Does.Contain("OwnerCollision"));
@@ -295,8 +295,8 @@ namespace GameCult.Caching.Tests
         private static CustomAttributeBuilder Key(int slot) =>
             new(typeof(KeyAttribute).GetConstructor(new[] { typeof(int) })!, new object[] { slot });
 
-        private static CustomAttributeBuilder IndexAttr(string alias) =>
-            new(typeof(CultIndexAttribute).GetConstructor(new[] { typeof(string) })!, new object?[] { alias });
+        private static CustomAttributeBuilder RoleAttr(string alias) =>
+            new(typeof(CultRoleAttribute).GetConstructor(new[] { typeof(string) })!, new object?[] { alias });
 
         private static CustomAttributeBuilder ReferenceAttr(Type? targetType, bool many) =>
             new(typeof(CultReferenceAttribute).GetConstructor(new[] { typeof(Type), typeof(bool) })!, new object?[] { targetType, many });
@@ -308,7 +308,7 @@ namespace GameCult.Caching.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("mass")]
+            [CultRole("mass")]
             public float Mass;
         }
 
@@ -325,7 +325,7 @@ namespace GameCult.Caching.Tests
         public sealed class FixtureLeafB : FixtureMiddle
         {
             [Key(2)]
-            [CultIndex("weight")]
+            [CultRole("weight")]
             public decimal? Weight;
         }
 
@@ -341,19 +341,19 @@ namespace GameCult.Caching.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("big_integer")]
+            [CultRole("big_integer")]
             public long BigInteger;
 
             [Key(2)]
-            [CultIndex("trimmed_decimal")]
+            [CultRole("trimmed_decimal")]
             public decimal TrimmedDecimal;
 
             [Key(3)]
-            [CultIndex("wide_double")]
+            [CultRole("wide_double")]
             public double WideDouble;
 
             [Key(4)]
-            [CultIndex("tiny_double")]
+            [CultRole("tiny_double")]
             public double TinyDouble;
         }
 

tests/GameCult.Caching.Tests/DocumentShapeTests.cs

@@ -394,7 +394,7 @@ namespace GameCult.Caching.Tests
         public class Gear
         {
             [Key(0)] [CultName] public string Name { get; set; } = "";
-            [Key(1)] [CultIndex("slot")] public string Slot { get; set; } = "";
+            [Key(1)] [CultRole("slot")] public string Slot { get; set; } = "";
         }
 
         [CultDocument("shape.weapon", "shape.weapon.v1")]

tests/GameCult.Caching.Tests/EmittedDocumentTypes.cs

@@ -12,7 +12,7 @@ namespace GameCult.Caching.Tests
     // two ways), an alias whose resolved type would depend on scan order, or a type a test needs to itself.
     internal static class EmittedDocumentTypes
     {
-        internal readonly record struct Field(string Name, Type Type, int Key, bool IsName = false);
+        internal readonly record struct Field(string Name, Type Type, int Key, bool IsName = false, string? Index = null, string? Role = null);
 
         internal static Type Emit(string typeName, string schemaName, string schemaVersion, Field[]? fields = null, string[]? compatibleSchemaIds = null)
         {
@@ -37,6 +37,10 @@ namespace GameCult.Caching.Tests
                 builder.SetCustomAttribute(new CustomAttributeBuilder(typeof(KeyAttribute).GetConstructor(new[] { typeof(int) })!, new object[] { field.Key }));
                 if (field.IsName)
                     builder.SetCustomAttribute(new CustomAttributeBuilder(typeof(CultNameAttribute).GetConstructor(Type.EmptyTypes)!, Array.Empty<object>()));
+                if (field.Index != null)
+                    builder.SetCustomAttribute(new CustomAttributeBuilder(typeof(CultIndexAttribute).GetConstructor(new[] { typeof(string) })!, new object[] { field.Index }));
+                if (field.Role != null)
+                    builder.SetCustomAttribute(new CustomAttributeBuilder(typeof(CultRoleAttribute).GetConstructor(new[] { typeof(string) })!, new object[] { field.Role }));
             }
 
             return type.CreateType()!;

tests/GameCult.Caching.Tests/FirstCallTests.cs

@@ -14,7 +14,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;
 }
 

tests/GameCult.Caching.Tests/UniqueIndexTests.cs

@@ -0,0 +1,459 @@
+#nullable enable
+using System;
+using System.IO;
+using System.Globalization;
+using System.Linq;
+using System.Threading.Tasks;
+using GameCult.Caching;
+using GameCult.Caching.MessagePack;
+using MessagePack;
+using NUnit.Framework;
+
+namespace GameCult.Caching.Tests
+{
+    // variants:ruling:unique-indexes. Within one document type and one [CultIndex] alias, no two held records hold one
+    // non-blank value; CultCache.Resolve judges every commit and every load, and a refusal never echoes the value.
+    public class UniqueIndexTests
+    {
+        private const string Canary = "CANARY-7f3a";
+
+        private static readonly CultDocumentRegistry Registry = CultDocumentRegistry.ForTypes(new[]
+        {
+            typeof(UqItem), typeof(UqTwin), typeof(UqTagged), typeof(UqDecimal), typeof(UqDouble), typeof(UqStamp)
+        });
+
+        // Emitted, so CultDocumentRegistry.Shared never scans them (one schema declared two ways, and a member Shared would refuse).
+        // The same schema name, version and shape, once as a role and once as a unique index: a role store holds the pair, the index type refuses it.
+        private static readonly Type UqLoadRole = EmittedDocumentTypes.Emit(
+            "UqLoadRole", "tests.uq_load", "tests.uq_load.v1", new[] { new EmittedDocumentTypes.Field("Code", typeof(string), 0, Role: "code") });
+        private static readonly Type UqLoadIndex = EmittedDocumentTypes.Emit(
+            "UqLoadIndex", "tests.uq_load", "tests.uq_load.v1", new[] { new EmittedDocumentTypes.Field("Code", typeof(string), 0, Index: "code") });
+        private static readonly Type UqBoth = EmittedDocumentTypes.Emit(
+            "UqBoth", "tests.uq_both", "tests.uq_both.v1", new[] { new EmittedDocumentTypes.Field("Both", typeof(string), 0, Index: "x", Role: "x") });
+
+        private static object Load(Type type, string code) => EmittedDocumentTypes.New(type, ("Code", code));
+
+        private string _directory = string.Empty;
+
+        [SetUp]
+        public void CreateDirectory()
+        {
+            _directory = Path.Combine(Path.GetTempPath(), $"cultlib-uidx-{Guid.NewGuid():N}");
+            Directory.CreateDirectory(_directory);
+        }
+
+        [TearDown]
+        public void DeleteDirectory()
+        {
+            if (Directory.Exists(_directory))
+                Directory.Delete(_directory, recursive: true);
+        }
+
+        private string PathOf(string name) => Path.Combine(_directory, name);
+
+        private static CultCache Open(string path, CultDocumentRegistry? registry = null) =>
+            CultCacheMessagePack.Create(path, new CultCacheOpenOptions { Registry = registry ?? Registry });
+
+        private static CultRecordKey Key(string name) => new(name);
+
+        private static UqItem Item(string? sku) => new() { Sku = sku };
+
+        private static InvalidOperationException Refused(TestDelegate write) => Assert.Throws<InvalidOperationException>(write)!;
+
+        [Test]
+        public void ABatchLeavingTwoRecordsWithOneValueIsRefusedNamingBothKeysAndTheIndex()
+        {
+            var path = PathOf("items.cc");
+            using var cache = Open(path);
+            cache.Commit(batch => batch.Upsert(typeof(UqItem), Item("keep"), Key("seed")));
+            var before = File.ReadAllBytes(path);
+
+            var refused = Refused(() => cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqItem), Item(Canary), Key("zeta"));
+                batch.Upsert(typeof(UqItem), Item(Canary), Key("alpha"));
+            }));
+
+            Assert.That(refused.Message, Does.Contain("alpha").And.Contain("zeta").And.Contain("sku").And.Contain("tests.uq_item"));
+            Assert.That(refused.Message.IndexOf("alpha", StringComparison.Ordinal), Is.LessThan(refused.Message.IndexOf("zeta", StringComparison.Ordinal)), "keys in ordinal order");
+            Assert.That(refused.Message, Does.Not.Contain(Canary), "the value is never echoed");
+            Assert.That(cache.Get(Key("alpha")), Is.Null);
+            Assert.That(cache.Get(Key("zeta")), Is.Null);
+            Assert.That(File.ReadAllBytes(path), Is.EqualTo(before), "the store is byte-identical");
+            Assert.That(cache.GetByIndex<UqItem>("sku", Canary), Is.Null);
+        }
+
+        [Test]
+        public async Task AWriteOfAHeldValueAtAnotherKeyIsRefused()
+        {
+            using var cache = Open(PathOf("items.cc"));
+            await cache.UpsertAsync(typeof(UqItem), Item(Canary), Key("first"));
+
+            var single = Assert.ThrowsAsync<InvalidOperationException>(() => cache.UpsertAsync(typeof(UqItem), Item(Canary), Key("second")))!;
+            Assert.That(single.Message, Does.Contain("first").And.Contain("second").And.Contain("sku").And.Not.Contain(Canary));
+            var batched = Refused(() => cache.Commit(batch => batch.Upsert(typeof(UqItem), Item(Canary), Key("third"))));
+            Assert.That(batched.Message, Does.Contain("first").And.Contain("third"));
+
+            Assert.That(cache.Get(Key("second")), Is.Null);
+            Assert.That(cache.Get(Key("third")), Is.Null);
+            Assert.That(cache.GetByIndex<UqItem>("sku", Canary), Is.Not.Null);
+
+            await cache.UpsertAsync(typeof(UqItem), Item(Canary), Key("first"));
+        }
+
+        [Test]
+        public void SwappingTwoValuesInOneCommitLandsAndBothAreFound()
+        {
+            var path = PathOf("items.cc");
+            using (var cache = Open(path))
+            {
+                cache.Commit(batch =>
+                {
+                    batch.Upsert(typeof(UqItem), Item("one"), Key("a"));
+                    batch.Upsert(typeof(UqItem), Item("two"), Key("b"));
+                });
+                cache.Commit(batch =>
+                {
+                    batch.Upsert(typeof(UqItem), Item("two"), Key("a"));
+                    batch.Upsert(typeof(UqItem), Item("one"), Key("b"));
+                });
+
+                Assert.That(cache.GetStored(Key("a"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "two")));
+                Assert.That(cache.GetStored(Key("b"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "one")));
+            }
+
+            using var reopened = Open(path);
+            Assert.That(reopened.GetStored(Key("a"))!.Document, Is.SameAs(reopened.GetByIndex<UqItem>("sku", "two")));
+            Assert.That(reopened.GetStored(Key("b"))!.Document, Is.SameAs(reopened.GetByIndex<UqItem>("sku", "one")));
+        }
+
+        [Test]
+        public void AValueMovesWhenItsHolderIsRemovedOrChangedInTheSameCommit()
+        {
+            using var cache = Open(PathOf("items.cc"));
+            cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqItem), Item("one"), Key("a"));
+                batch.Upsert(typeof(UqItem), Item("two"), Key("b"));
+            });
+
+            cache.Commit(batch =>
+            {
+                batch.Remove(Key("a"));
+                batch.Upsert(typeof(UqItem), Item("one"), Key("c"));
+            });
+            Assert.That(cache.GetStored(Key("c"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "one")), "removed holder released its value");
+
+            cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqItem), Item("three"), Key("b"));
+                batch.Upsert(typeof(UqItem), Item("two"), Key("d"));
+            });
+            Assert.That(cache.GetStored(Key("d"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "two")), "changed holder released its value");
+            Assert.That(cache.GetStored(Key("b"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "three")));
+            Assert.That(cache.GetByIndex<UqItem>("sku", "one")!.Sku, Is.EqualTo("one"));
+        }
+
+        [Test]
+        public void BlankValuesNeverConflict()
+        {
+            var path = PathOf("items.cc");
+            using (var cache = Open(path))
+            {
+                cache.Commit(batch =>
+                {
+                    batch.Upsert(typeof(UqItem), Item(null), Key("a"));
+                    batch.Upsert(typeof(UqItem), Item(""), Key("b"));
+                    batch.Upsert(typeof(UqItem), Item("   "), Key("c"));
+                    batch.Upsert(typeof(UqItem), Item(null), Key("d"));
+                });
+                Assert.That(cache.GetByIndex<UqItem>("sku", ""), Is.Null);
+                Assert.That(cache.GetByIndex<UqItem>("sku", "   "), Is.Null);
+            }
+
+            using var reopened = Open(path);
+            Assert.That(reopened.Get(Key("d")), Is.Not.Null, "a store of blank values reopens");
+        }
+
+        [Test]
+        public void TwoTypesMayShareAnAliasAndAValue()
+        {
+            using var cache = Open(PathOf("items.cc"));
+            cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqItem), Item("same"), Key("item"));
+                batch.Upsert(typeof(UqTwin), new UqTwin { Sku = "same" }, Key("twin"));
+            });
+
+            Assert.That(cache.GetByIndex<UqItem>("sku", "same"), Is.Not.Null);
+            Assert.That(cache.GetByIndex<UqTwin>("sku", "same"), Is.Not.Null);
+            Assert.That(Registry.GetRequired<UqItem>().DeclaredMembers.Single().IndexAlias, Is.EqualTo("sku"), "a unique index addresses selection as a role does");
+        }
+
+        [Test]
+        public void RoleMembersMayShareValuesAndStaySelectable()
+        {
+            var path = PathOf("tagged.cc");
+            using (var cache = Open(path))
+            {
+                cache.Commit(batch =>
+                {
+                    batch.Upsert(typeof(UqTagged), new UqTagged { Kind = "weapon" }, Key("a"));
+                    batch.Upsert(typeof(UqTagged), new UqTagged { Kind = "weapon" }, Key("b"));
+                });
+                Assert.That(cache.GetByIndex<UqTagged>("kind", "weapon"), Is.Null, "a role is not a lookup");
+            }
+
+            using var reopened = Open(path);
+            Assert.That(reopened.Get(Key("b")), Is.Not.Null, "a role pair reopens");
+            var member = Registry.GetRequired<UqTagged>().DeclaredMembers.Single(candidate => candidate.MemberName == nameof(UqTagged.Kind));
+            Assert.That(member.IndexAlias, Is.EqualTo("kind"), "the role still supplies the selection address");
+        }
+
+        [Test]
+        public void AStoreHoldingDuplicatesRefusesToOpenNamingBothKeysAndTheIndex()
+        {
+            var path = PathOf("load.cc");
+            var roleRegistry = CultDocumentRegistry.ForTypes(new[] { UqLoadRole });
+            using (var writer = Open(path, roleRegistry))
+            {
+                writer.Commit(batch =>
+                {
+                    batch.Upsert(UqLoadRole, Load(UqLoadRole, Canary), Key("m"));
+                    batch.Upsert(UqLoadRole, Load(UqLoadRole, Canary), Key("k"));
+                });
+            }
+
+            var before = File.ReadAllBytes(path);
+            var indexRegistry = CultDocumentRegistry.ForTypes(new[] { UqLoadIndex });
+            var refused = Refused(() => Open(path, indexRegistry).Dispose());
+
+            Assert.That(refused.Message, Does.Contain("k").And.Contain("m").And.Contain("code").And.Not.Contain(Canary));
+            Assert.That(File.ReadAllBytes(path), Is.EqualTo(before), "the file is untouched");
+
+            using var cache = new CultCache(indexRegistry);
+            var store = new SingleFileMessagePackBackingStore(path);
+            Refused(() => cache.AddBackingStore(store));
+            Assert.That(cache.BackingStores, Is.Empty, "the refused store is not attached");
+            Assert.That(cache.Get(Key("k")), Is.Null);
+        }
+
+        [Test]
+        public void AWriteOntoAMovedFileIsAConflictAndTheRetryIsRefused()
+        {
+            var path = PathOf("items.cc");
+            using var seed = Open(path);
+            seed.Commit(batch => batch.Upsert(typeof(UqItem), Item("base"), Key("a")));
+            using var second = Open(path);
+            using (var first = Open(path))
+                first.Commit(batch => batch.Upsert(typeof(UqItem), Item(Canary), Key("b")));
+
+            var conflict = Assert.Throws<CultWriteConflictException>(
+                () => second.Commit(batch => batch.Upsert(typeof(UqItem), Item(Canary), Key("c"))))!;
+            Assert.That(conflict.Message, Does.Contain("unique index"));
+            Assert.That(second.Get(Key("b")), Is.Not.Null, "the moved record is loaded");
+
+            var retry = Refused(() => second.Commit(batch => batch.Upsert(typeof(UqItem), Item(Canary), Key("c"))));
+            Assert.That(retry.Message, Does.Contain("b").And.Contain("c").And.Not.Contain(Canary));
+
+            using var reopened = Open(path);
+            Assert.That(reopened.Get(Key("c")), Is.Null, "the file never holds the pair");
+            Assert.That(reopened.Get(Key("b")), Is.Not.Null);
+        }
+
+        [Test]
+        public void CachelessWritesOfAUniqueIndexedTypeAreRefused()
+        {
+            var path = PathOf("items.cc");
+            using (var cache = Open(path))
+                cache.Commit(batch => batch.Upsert(typeof(UqItem), Item("a"), Key("a")));
+            var before = File.ReadAllBytes(path);
+            var store = new SingleFileMessagePackBackingStore(path);
+
+            Refused(() => store.WriteDocument(Key("x"), Item(Canary), registry: Registry));
+            var entry = Registry.GetRequired<UqItem>().ToCatalogEntry();
+            Refused(() => store.WriteRecord(
+                new CultPersistedRecord { Key = "y", SchemaId = entry.SchemaId, StoredAt = DateTimeOffset.UtcNow.ToString("O"), Payload = new byte[] { 0x90 } },
+                entry,
+                registry: Registry));
+
+            Refused(() => store.WriteRecord(
+                new CultPersistedRecord { Key = "y", SchemaId = entry.SchemaId, StoredAt = DateTimeOffset.UtcNow.ToString("O"), Payload = new byte[] { 0x90 } },
+                entry));
+            Refused(() => store.WriteRecord(
+                new CultPersistedRecord { Key = "y", SchemaId = entry.SchemaId, StoredAt = DateTimeOffset.UtcNow.ToString("O"), Payload = new byte[] { 0x90 } },
+                entry,
+                registry: CultDocumentRegistry.ForTypes(new[] { typeof(UqTagged) })));
+            Assert.That(File.ReadAllBytes(path), Is.EqualTo(before), "the file is byte-identical, whichever registry (none, another) was lent");
+            store.WriteDocument(Key("t"), new UqTagged { Kind = "k" }, registry: Registry);
+            using var reopened = Open(path);
+            Assert.That(reopened.Get(Key("t")), Is.Not.Null, "a role-only type still writes cacheless");
+        }
+
+
+        // The rule is a function of the whole commit: it must not stop at a prefix, a mixed batch or a small load.
+        [TestCase(0, 1)]
+        [TestCase(0, 6)]
+        [TestCase(2, 5)]
+        [TestCase(5, 6)]
+        public void ADuplicateAnywhereInALargeMixedBatchIsRefused(int first, int second)
+        {
+            using var cache = Open(PathOf("items.cc"));
+
+            var refused = Refused(() => cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqTagged), new UqTagged { Kind = "same" }, Key("tag-a"));
+                for (var i = 0; i < 7; i++)
+                    batch.Upsert(typeof(UqItem), Item(i == first || i == second ? "dup" : "v" + i), Key("item-" + i));
+                batch.Upsert(typeof(UqTagged), new UqTagged { Kind = "same" }, Key("tag-b"));
+            }));
+
+            Assert.That(refused.Message, Does.Contain("item-" + first).And.Contain("item-" + second).And.Not.Contain("dup"));
+            Assert.That(cache.Get(Key("tag-a")), Is.Null, "nothing landed");
+        }
+
+        [Test]
+        public void ADuplicateBesideARecordOfAnotherTypeSharingTheAliasIsStillRefused()
+        {
+            using var cache = Open(PathOf("items.cc"));
+            var refused = Refused(() => cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqTwin), new UqTwin { Sku = "same" }, Key("twin"));
+                batch.Upsert(typeof(UqItem), Item("same"), Key("item-1"));
+                batch.Upsert(typeof(UqItem), Item("same"), Key("item-2"));
+            }));
+            Assert.That(refused.Message, Does.Contain("item-1").And.Contain("item-2").And.Not.Contain("twin"));
+        }
+
+        [Test]
+        public void ValuesDifferingOnlyByCaseAreDifferentValues()
+        {
+            using var cache = Open(PathOf("items.cc"));
+            cache.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqItem), Item("Sku"), Key("a"));
+                batch.Upsert(typeof(UqItem), Item("sku"), Key("b"));
+            });
+            Assert.That(cache.GetStored(Key("a"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "Sku")));
+            Assert.That(cache.GetStored(Key("b"))!.Document, Is.SameAs(cache.GetByIndex<UqItem>("sku", "sku")));
+        }
+
+        [Test]
+        public void ALoadOfManyRecordsRefusesAPairWhereverItSits([Values(0, 3, 6)] int pairAt)
+        {
+            var path = PathOf("load.cc");
+            var roleRegistry = CultDocumentRegistry.ForTypes(new[] { UqLoadRole });
+            using (var writer = Open(path, roleRegistry))
+            {
+                writer.Commit(batch =>
+                {
+                    for (var i = 0; i < 8; i++)
+                        batch.Upsert(UqLoadRole, Load(UqLoadRole, i == pairAt || i == pairAt + 1 ? "dup" : "v" + i), Key("rec-" + i));
+                });
+            }
+
+            var refused = Refused(() => Open(path, CultDocumentRegistry.ForTypes(new[] { UqLoadIndex })).Dispose());
+            Assert.That(refused.Message, Does.Contain("rec-" + pairAt).And.Contain("rec-" + (pairAt + 1)).And.Not.Contain("dup"));
+        }
+
+        [Test]
+        public void AMixedBatchOntoAMovedFileIsAConflictWhateverItsOrder()
+        {
+            var path = PathOf("items.cc");
+            using var seed = Open(path);
+            seed.Commit(batch => batch.Upsert(typeof(UqItem), Item("base"), Key("a")));
+            using var second = Open(path);
+            using (var first = Open(path))
+                first.Commit(batch => batch.Upsert(typeof(UqItem), Item("moved"), Key("b")));
+
+            Assert.Throws<CultWriteConflictException>(() => second.Commit(batch =>
+            {
+                batch.Upsert(typeof(UqTagged), new UqTagged { Kind = "k" }, Key("tag"));
+                batch.Upsert(typeof(UqItem), Item("fresh"), Key("c"));
+            }));
+        }
+
+        [Test]
+        public void ANumericIndexValueIsOneCanonicalValueInEveryCulture()
+        {
+            var culture = (CultureInfo)CultureInfo.InvariantCulture.Clone();
+            culture.NumberFormat.NumberDecimalSeparator = ",";
+            var previous = CultureInfo.CurrentCulture;
+            CultureInfo.CurrentCulture = culture;
+            try
+            {
+                using var cache = Open(PathOf("numbers.cc"));
+                cache.Commit(batch => batch.Upsert(typeof(UqDecimal), new UqDecimal { Price = 1.0m }, Key("d1")));
+                Assert.That(cache.GetByIndex<UqDecimal>("price", "1"), Is.Not.Null, "1.0m is the canonical value 1");
+                var sameDecimal = Refused(() => cache.Commit(batch => batch.Upsert(typeof(UqDecimal), new UqDecimal { Price = 1.00m }, Key("d2"))));
+                Assert.That(sameDecimal.Message, Does.Contain("d1").And.Contain("d2"));
+
+                cache.Commit(batch => batch.Upsert(typeof(UqDecimal), new UqDecimal { Price = 1.5m }, Key("d3")));
+                Assert.That(cache.GetByIndex<UqDecimal>("price", "1.5"), Is.Not.Null, "lookups name the invariant spelling, not the current culture's");
+                Assert.That(cache.GetByIndex<UqDecimal>("price", "1,5"), Is.Null);
+
+                culture.DateTimeFormat.ShortDatePattern = "yyyy.dd.MM";
+                culture.DateTimeFormat.DateSeparator = ".";
+                cache.Commit(batch => batch.Upsert(typeof(UqStamp), new UqStamp { When = new DateTime(2026, 1, 2, 3, 4, 5) }, Key("t1")));
+                Assert.That(cache.GetByIndex<UqStamp>("when", "01/02/2026 03:04:05"), Is.Not.Null, "a date is its invariant spelling");
+
+                cache.Commit(batch => batch.Upsert(typeof(UqDouble), new UqDouble { Level = 0.0 }, Key("z1")));
+                var signedZero = Refused(() => cache.Commit(batch => batch.Upsert(typeof(UqDouble), new UqDouble { Level = -0.0 }, Key("z2"))));
+                Assert.That(signedZero.Message, Does.Contain("z1").And.Contain("z2"));
+            }
+            finally
+            {
+                CultureInfo.CurrentCulture = previous;
+            }
+        }
+
+        [Test]
+        public void AMemberWithBothAttributesIsRefusedAtRegistration()
+        {
+            var refused = Refused(() => CultDocumentRegistry.ForTypes(new[] { UqBoth }));
+            Assert.That(refused.Message, Does.Contain("Both").And.Contain("[CultIndex]").And.Contain("[CultRole]"));
+        }
+
+        [CultDocument("tests.uq_item", "tests.uq_item.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqItem
+        {
+            [Key(0)] [CultIndex("sku")] public string? Sku { get; set; }
+        }
+
+        [CultDocument("tests.uq_twin", "tests.uq_twin.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqTwin
+        {
+            [Key(0)] [CultIndex("sku")] public string? Sku { get; set; }
+        }
+
+        [CultDocument("tests.uq_decimal", "tests.uq_decimal.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqDecimal
+        {
+            [Key(0)] [CultIndex("price")] public decimal Price { get; set; }
+        }
+
+        [CultDocument("tests.uq_stamp", "tests.uq_stamp.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqStamp
+        {
+            [Key(0)] [CultIndex("when")] public DateTime When { get; set; }
+        }
+
+        [CultDocument("tests.uq_double", "tests.uq_double.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqDouble
+        {
+            [Key(0)] [CultIndex("level")] public double Level { get; set; }
+        }
+
+        [CultDocument("tests.uq_tagged", "tests.uq_tagged.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class UqTagged
+        {
+            [Key(0)] [CultRole("kind")] public string? Kind { get; set; }
+        }
+    }
+}

tests/GameCult.Caching.Tests/UniqueIndexVectorTests.cs

@@ -0,0 +1,294 @@
+#nullable enable
+using System;
+using System.Buffers;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using GameCult.Caching;
+using GameCult.Caching.MessagePack;
+using MessagePack;
+using NUnit.Framework;
+
+namespace GameCult.Caching.Tests
+{
+    // variants:ruling:unique-indexes. The canonical index text and the unique-index load verdicts in tests/vectors/unique-index.
+    // The C# reference is the only writer (CULTCACHE_WRITE_VECTORS=1); every other run reads the committed bytes and
+    // compares them byte for byte. Other runtimes are held to the same text and the same verdicts.
+    public class UniqueIndexVectorTests
+    {
+        private const string WriteVariable = "CULTCACHE_WRITE_VECTORS";
+        private static readonly DateTimeOffset StoredAt = new(2026, 1, 1, 0, 0, 0, TimeSpan.Zero);
+        private static bool Writing => Environment.GetEnvironmentVariable(WriteVariable) == "1";
+
+        private static string VectorDirectory()
+        {
+            for (var dir = new DirectoryInfo(TestContext.CurrentContext.TestDirectory); dir != null; dir = dir.Parent)
+            {
+                var vectors = Path.Combine(dir.FullName, "tests", "vectors");
+                if (Directory.Exists(vectors)) return Path.Combine(vectors, "unique-index");
+            }
+
+            throw new DirectoryNotFoundException($"tests/vectors not found above {TestContext.CurrentContext.TestDirectory}.");
+        }
+
+        private static string VectorPath(string name) => Path.Combine(VectorDirectory(), name);
+
+        private static void Check(string name, byte[] reference)
+        {
+            var path = VectorPath(name);
+            if (Writing)
+            {
+                Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+                File.WriteAllBytes(path, reference);
+                return;
+            }
+
+            Assert.That(File.Exists(path), Is.True, $"vector {name} is committed");
+            Assert.That(Convert.ToHexString(reference), Is.EqualTo(Convert.ToHexString(File.ReadAllBytes(path))), $"vector {name}");
+        }
+
+        private static byte[] Committed(string name)
+        {
+            var path = VectorPath(name);
+            Assert.That(File.Exists(path), Is.True, $"vector {name} is committed");
+            return File.ReadAllBytes(path);
+        }
+
+        // ---- values.msgpack: [label, kind, value, text-or-nil] ----
+
+        private sealed record Row(string Label, string Kind, object Value, string? Text);
+
+        private static readonly MethodInfo RenderCanonicalNumber =
+            typeof(CultDocumentRegistry).GetMethod("RenderCanonicalNumber", BindingFlags.NonPublic | BindingFlags.Static)!;
+
+        private static object? ByIndex(CultCache cache, Type type, string alias, string value) =>
+            typeof(CultCache).GetMethod(nameof(CultCache.GetByIndex))!.MakeGenericMethod(type).Invoke(cache, new object[] { alias, value });
+
+        private static string? Number(object raw) => (string?)RenderCanonicalNumber.Invoke(null, new[] { raw });
+
+        // Strings and booleans carry the text the rule states; numbers carry whatever the reference renders, never hand-typed.
+        private static List<Row> Rows() => new()
+        {
+            new("plain", "string", "S-1", "S-1"),
+            new("empty", "string", "", null),
+            new("space", "string", " ", null),
+            new("nel", "string", "\u0085", null),
+            new("nbsp", "string", "\u00A0", null),
+            new("ideographic-space", "string", "\u3000", null),
+            new("vertical-tab", "string", "\u000B", null),
+            new("bom", "string", "\uFEFF", "\uFEFF"),
+            new("unit-separator", "string", "\u001F", "\u001F"),
+            new("padded", "string", " a ", " a "),
+            new("int64-max", "int64", long.MaxValue, Number(long.MaxValue)),
+            new("int64-min", "int64", long.MinValue, Number(long.MinValue)),
+            new("uint64-max", "uint64", ulong.MaxValue, Number(ulong.MaxValue)),
+            new("double-zero", "double", 0.0, Number(0.0)),
+            new("double-negative-zero", "double", -0.0, Number(-0.0)),
+            new("double-tenth", "double", 0.1, Number(0.1)),
+            new("double-1e21", "double", 1e21, Number(1e21)),
+            new("double-2.5e-7", "double", 2.5e-7, Number(2.5e-7)),
+            new("double-nan", "double", double.NaN, Number(double.NaN)),
+            new("double-infinity", "double", double.PositiveInfinity, Number(double.PositiveInfinity)),
+            new("bool-true", "bool", true, "True"),
+            new("bool-false", "bool", false, "False"),
+        };
+
+        private static byte[] ValuesFile()
+        {
+            var buffer = new ArrayBufferWriter<byte>();
+            var writer = new MessagePackWriter(buffer);
+            var rows = Rows();
+            writer.WriteArrayHeader(rows.Count);
+            foreach (var row in rows)
+            {
+                writer.WriteArrayHeader(4);
+                writer.Write(row.Label);
+                writer.Write(row.Kind);
+                switch (row.Value)
+                {
+                    case string s: writer.Write(s); break;
+                    case long l: writer.Write(l); break;
+                    case ulong u: writer.Write(u); break;
+                    case double d: writer.Write(d); break;
+                    case bool b: writer.Write(b); break;
+                    default: throw new InvalidOperationException(row.Kind);
+                }
+
+                if (row.Text == null) writer.WriteNil(); else writer.Write(row.Text);
+            }
+
+            writer.Flush();
+            return buffer.WrittenSpan.ToArray();
+        }
+
+        private static readonly Dictionary<string, Type> KindTypes = new[]
+        {
+            ("string", typeof(string)), ("int64", typeof(long)), ("uint64", typeof(ulong)), ("double", typeof(double)), ("bool", typeof(bool))
+        }.ToDictionary(pair => pair.Item1, pair => EmittedDocumentTypes.Emit(
+            "UqKind" + pair.Item1, "tests.uq_kind_" + pair.Item1, "tests.uq_kind_" + pair.Item1 + ".v1",
+            new[] { new EmittedDocumentTypes.Field("Value", pair.Item2, 0, Index: "v") }));
+
+        [Test]
+        public void ValuesFileIsTheReferencesCanonicalText()
+        {
+            Check("values.msgpack", ValuesFile());
+
+            var reader = new MessagePackReader(Committed("values.msgpack"));
+            var count = reader.ReadArrayHeader();
+            var rows = Rows();
+            Assert.That(count, Is.EqualTo(rows.Count));
+            foreach (var row in rows)
+            {
+                Assert.That(reader.ReadArrayHeader(), Is.EqualTo(4));
+                Assert.That(reader.ReadString(), Is.EqualTo(row.Label));
+                Assert.That(reader.ReadString(), Is.EqualTo(row.Kind));
+                reader.Skip();
+                var text = reader.TryReadNil() ? null : reader.ReadString();
+                Assert.That(text, Is.EqualTo(row.Text), row.Label);
+
+                var type = KindTypes[row.Kind];
+                var registry = CultDocumentRegistry.ForTypes(new[] { type });
+                using var cache = CultCacheMessagePack.Create(Path.Combine(Path.GetTempPath(), $"cultlib-uidxv-{Guid.NewGuid():N}.cc"), new CultCacheOpenOptions { Registry = registry });
+                cache.Commit(batch =>
+                {
+                    batch.Upsert(type, EmittedDocumentTypes.New(type, ("Value", row.Value)), new CultRecordKey("one"));
+                    batch.Upsert(type, EmittedDocumentTypes.New(type, ("Value", row.Value)), new CultRecordKey(text == null ? "two" : "one"));
+                });
+                if (text == null)
+                {
+                    Assert.That(cache.Get(new CultRecordKey("two")), Is.Not.Null, $"{row.Label}: a blank value commits twice");
+                    foreach (var probe in new[] { "", " ", "NaN", "0", "Infinity", "∞" })
+                        Assert.That(ByIndex(cache, type, "v", probe), Is.Null, $"{row.Label}: found by '{probe}'");
+                }
+                else
+                {
+                    Assert.That(ByIndex(cache, type, "v", text), Is.Not.Null, $"{row.Label}: found by its text");
+                }
+            }
+        }
+
+        // ---- the stores: written through a role, judged by an index ----
+
+        private static readonly EmittedDocumentTypes.Field[] RoleFields =
+        {
+            new("Sku", typeof(string), 0, Role: "Sku"), new("Category", typeof(string), 1)
+        };
+
+        private static readonly EmittedDocumentTypes.Field[] IndexFields =
+        {
+            new("Sku", typeof(string), 0, Index: "Sku"), new("Category", typeof(string), 1)
+        };
+
+        private static readonly Type ItemRole = EmittedDocumentTypes.Emit("UqVecItemRole", "tests.unique_item", "tests.unique_item.v1", RoleFields);
+        private static readonly Type ItemIndex = EmittedDocumentTypes.Emit("UqVecItemIndex", "tests.unique_item", "tests.unique_item.v1", IndexFields);
+
+        private static readonly (string Key, string Sku, string Category)[] Items =
+        {
+            ("item:a", "S-1", "tools"), ("item:b", "S-1", "tools"), ("item:c", " ", "parts"), ("item:d", "\u0085", "parts")
+        };
+
+        private static byte[] StoreBytes(string[] keys)
+        {
+            var directory = Path.Combine(Path.GetTempPath(), $"cultlib-uidxs-{Guid.NewGuid():N}");
+            Directory.CreateDirectory(directory);
+            try
+            {
+                var path = Path.Combine(directory, "store.cc");
+                using (var cache = CultCacheMessagePack.Create(path, new CultCacheOpenOptions
+                {
+                    Registry = CultDocumentRegistry.ForTypes(new[] { ItemRole }), StoreFlushOnDispose = true
+                }))
+                {
+                    cache.Clock = () => StoredAt;
+                    foreach (var item in Items.Where(item => keys.Contains(item.Key)))
+                        cache.UpsertAsync(ItemRole, EmittedDocumentTypes.New(ItemRole, ("Sku", item.Sku), ("Category", item.Category)), new CultRecordKey(item.Key)).GetAwaiter().GetResult();
+                    cache.FlushAsync().GetAwaiter().GetResult();
+                }
+
+                return File.ReadAllBytes(path);
+            }
+            finally
+            {
+                Directory.Delete(directory, recursive: true);
+            }
+        }
+
+        private static readonly (string File, string? Alias, string Outcome, string? K1, string? K2)[] Outcomes =
+        {
+            ("duplicate-store.cc", "Sku", "refused", "item:a", "item:b"),
+            ("duplicate-store.cc", null, "open", null, null),
+            ("blank-store.cc", "Sku", "open", null, null),
+        };
+
+        private static byte[] OutcomesFile()
+        {
+            var buffer = new ArrayBufferWriter<byte>();
+            var writer = new MessagePackWriter(buffer);
+            writer.WriteArrayHeader(Outcomes.Length);
+            foreach (var row in Outcomes)
+            {
+                writer.WriteArrayHeader(5);
+                writer.Write(row.File);
+                foreach (var text in new[] { row.Alias, row.Outcome, row.K1, row.K2 })
+                    if (text == null) writer.WriteNil(); else writer.Write(text);
+            }
+
+            writer.Flush();
+            return buffer.WrittenSpan.ToArray();
+        }
+
+        private static string? NextText(ref MessagePackReader reader) => reader.TryReadNil() ? null : reader.ReadString();
+
+        [Test]
+        public void StoreVectorsHoldTheirVerdicts()
+        {
+            Check("duplicate-store.cc", StoreBytes(new[] { "item:a", "item:b", "item:c", "item:d" }));
+            Check("blank-store.cc", StoreBytes(new[] { "item:c", "item:d" }));
+            Check("outcomes.msgpack", OutcomesFile());
+
+            var reader = new MessagePackReader(Committed("outcomes.msgpack"));
+            var count = reader.ReadArrayHeader();
+            Assert.That(count, Is.EqualTo(Outcomes.Length));
+            for (var i = 0; i < count; i++)
+            {
+                Assert.That(reader.ReadArrayHeader(), Is.EqualTo(5));
+                var file = reader.ReadString()!;
+                var alias = NextText(ref reader);
+                var outcome = NextText(ref reader)!;
+                var k1 = NextText(ref reader);
+                var k2 = NextText(ref reader);
+
+                var directory = Path.Combine(Path.GetTempPath(), $"cultlib-uidxo-{Guid.NewGuid():N}");
+                Directory.CreateDirectory(directory);
+                try
+                {
+                    var path = Path.Combine(directory, "store.cc");
+                    File.WriteAllBytes(path, Committed(file));
+                    var before = File.ReadAllBytes(path);
+                    var type = alias == null ? ItemRole : ItemIndex;
+                    var registry = CultDocumentRegistry.ForTypes(new[] { type });
+                    if (outcome == "open")
+                    {
+                        using var cache = CultCacheMessagePack.Create(path, new CultCacheOpenOptions { Registry = registry });
+                        Assert.That(cache.Get(new CultRecordKey("item:c")), Is.Not.Null, file);
+                    }
+                    else
+                    {
+                        var refused = Assert.Throws<InvalidOperationException>(() => CultCacheMessagePack.Create(path, new CultCacheOpenOptions { Registry = registry }).Dispose())!;
+                        Assert.That(refused.Message, Is.EqualTo(
+                            $"Records {k1} and {k2} (tests.unique_item) both hold unique index '{alias}'; an index value names one record."));
+                        Assert.That(refused.Message, Does.Not.Contain("S-1"));
+                    }
+
+                    Assert.That(File.ReadAllBytes(path), Is.EqualTo(before), $"{file} is untouched");
+                }
+                finally
+                {
+                    Directory.Delete(directory, recursive: true);
+                }
+            }
+        }
+    }
+}

tests/GameCult.Caching.Tests/VariantTests.cs

@@ -580,7 +580,7 @@ namespace GameCult.Caching.Tests
             {
                 cache.Override<VariantGear>(nameof(VariantGear.Name), "laser big")
             })));
-            Assert.That(inherited.Message, Does.Contain(BigKey.Value).And.Contain(BaseKey.Value).And.Contain("code").And.Contain("l1"));
+            Assert.That(inherited.Message, Does.Contain(BigKey.Value).And.Contain(BaseKey.Value).And.Contain("code").And.Not.Contain("l1"), "the value is not echoed");
 
             var explicitly = Refused(() => cache.Commit(batch => batch.UpsertVariant(BigKey, BaseKey, new[]
             {
@@ -631,7 +631,7 @@ namespace GameCult.Caching.Tests
                 SeedBig(cache);
 
                 var refused = Refused(() => cache.Commit(batch => batch.Upsert(typeof(VariantGear), Other("laser big"), other)));
-                Assert.That(refused.Message, Does.Contain(other.Value).And.Contain(BigKey.Value).And.Contain("code").And.Contain("laser big"));
+                Assert.That(refused.Message, Does.Contain(other.Value).And.Contain(BigKey.Value).And.Contain("code").And.Not.Contain("laser big"));
 
                 var single = Assert.ThrowsAsync<InvalidOperationException>(
                     () => cache.UpsertAsync(Other("laser big"), new CultRecordHandle<VariantGear>(other)))!;
@@ -660,7 +660,7 @@ namespace GameCult.Caching.Tests
                 cache.Commit(batch => batch.Upsert(typeof(VariantGear), Other("laser big"), other));
 
                 var refused = Refused(() => SeedBig(cache));
-                Assert.That(refused.Message, Does.Contain(BigKey.Value).And.Contain(other.Value).And.Contain("code").And.Contain("laser big"));
+                Assert.That(refused.Message, Does.Contain(BigKey.Value).And.Contain(other.Value).And.Contain("code").And.Not.Contain("laser big"));
                 Assert.That(cache.Get(BigKey), Is.Null, "nothing landed");
 
                 // The same batch, either staging order: the result is what is judged.
@@ -685,8 +685,9 @@ namespace GameCult.Caching.Tests
                 }));
                 Assert.That(sameBatchVariantFirst.Message, Does.Contain(BigKey.Value).And.Contain("taker"));
 
-                // Plain-vs-plain sharing is not this rule's business.
-                Assert.DoesNotThrow(() => cache.Commit(batch => batch.Upsert(typeof(VariantGear), Other("l1"), new CultRecordKey("twin"))));
+                // Plain-vs-plain sharing is the same rule.
+                var plain = Refused(() => cache.Commit(batch => batch.Upsert(typeof(VariantGear), Other("l1"), new CultRecordKey("twin"))));
+                Assert.That(plain.Message, Does.Contain("twin").And.Contain(BaseKey.Value));
             }
 
             using var reopened = Open(path);
@@ -819,7 +820,7 @@ namespace GameCult.Caching.Tests
             using var a = Open(path);
             using (var b = Open(path))
                 b.Commit(batch => batch.Upsert(typeof(VariantGear), Other("zc"), z));
-            a.Commit(batch => batch.Upsert(typeof(VariantGear), Other("yc"), new CultRecordKey("y")));
+            a.Commit(batch => batch.Upsert(typeof(VariantOther), new VariantOther { Name = "yc" }, new CultRecordKey("y")));
 
             var conflict = Assert.Throws<CultWriteConflictException>(() => SeedBig(a))!;
 
@@ -1100,22 +1101,8 @@ namespace GameCult.Caching.Tests
             Assert.That(reloaded.Get<VariantGear>(BigKey)!.Tags, Is.EqualTo(new[] { "beam", "pierce" }));
         }
 
-        // ---- the held index is truthful: every holder of a value, so no rule judges a variant against a lossy view ----
-
         private static VariantGear Named(string name, string code) => new() { Name = name, Power = 1, Code = code };
 
-        private static CultRecordKey[] SharedCodePair(CultCache cache)
-        {
-            var p1 = new CultRecordKey("p1");
-            var p2 = new CultRecordKey("p2");
-            cache.Commit(batch =>
-            {
-                batch.Upsert(typeof(VariantGear), Named("p1", "x"), p1);
-                batch.Upsert(typeof(VariantGear), Named("p2", "x"), p2);
-            });
-            return new[] { p1, p2 };
-        }
-
         private static void VariantOnCode(CultCache cache, string code) =>
             cache.Commit(batch => batch.UpsertVariant(BigKey, BaseKey, new[]
             {
@@ -1123,73 +1110,6 @@ namespace GameCult.Caching.Tests
                 cache.Override<VariantGear>(nameof(VariantGear.Code), code)
             }));
 
-        [Test]
-        public void RemovingTheHolderADuplicateValueFindsLeavesTheOtherFindable()
-        {
-            var path = PathOf("gear.cc");
-            using (var cache = Open(path))
-            {
-                var pair = SharedCodePair(cache);
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p1"), "the smallest key");
-
-                cache.Remove(pair[0]);
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p2"), "removing the holder finds the other one");
-
-                cache.Commit(batch => batch.Upsert(typeof(VariantGear), Named("p1", "x"), pair[0]));
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p1"));
-                cache.Remove(pair[1]);
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p1"), "removing the other changes nothing");
-                cache.Remove(pair[0]);
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x"), Is.Null);
-                cache.BackingStores[0].PushAll();
-            }
-
-            using var reopened = Open(path);
-            Assert.That(reopened.GetByIndex<VariantGear>("code", "x"), Is.Null);
-        }
-
-        [Test]
-        public void AVariantOnAValueAPlainRecordStillHoldsAfterItsTwinWasRemovedIsRefusedAndTheStoreReopens()
-        {
-            var path = PathOf("gear.cc");
-            using (var cache = Open(path))
-            {
-                SeedBase(cache);
-                var pair = SharedCodePair(cache);
-                cache.Remove(pair[1]);
-
-                var refused = Refused(() => VariantOnCode(cache, "x"));
-                Assert.That(refused.Message, Does.Contain(BigKey.Value).And.Contain("p1").And.Contain("code").And.Contain("'x'"));
-                Assert.That(cache.Get(BigKey), Is.Null, "nothing landed");
-                cache.BackingStores[0].PushAll();
-            }
-
-            using var reopened = Open(path);
-            Assert.That(reopened.Get(BigKey), Is.Null);
-            Assert.That(reopened.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p1"));
-        }
-
-        [Test]
-        public void AVariantOnAValueAPlainRecordStillHoldsAfterItsTwinChangedItsValueIsRefusedAndTheStoreReopens()
-        {
-            var path = PathOf("gear.cc");
-            using (var cache = Open(path))
-            {
-                SeedBase(cache);
-                var pair = SharedCodePair(cache);
-                cache.Commit(batch => batch.Upsert(typeof(VariantGear), Named("p2", "y"), pair[1]));
-
-                var refused = Refused(() => VariantOnCode(cache, "x"));
-                Assert.That(refused.Message, Does.Contain(BigKey.Value).And.Contain("p1").And.Contain("'x'"));
-                Assert.DoesNotThrow(() => VariantOnCode(cache, "z"), "an unshared value is fine");
-                cache.BackingStores[0].PushAll();
-            }
-
-            using var reopened = Open(path);
-            Assert.That(reopened.GetByIndex<VariantGear>("code", "z")!.Name, Is.EqualTo("laser big"));
-            Assert.That(reopened.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("p1"));
-        }
-
         // ---- a merge onto the file is judged on the set the file will hold ----
 
         [Test]
@@ -1218,7 +1138,7 @@ namespace GameCult.Caching.Tests
                 var conflict = Assert.Throws<CultWriteConflictException>(Write)!;
                 Assert.That(conflict.ChangedKeys, Does.Contain(BigKey.Value));
                 var refused = Refused(Write);
-                Assert.That(refused.Message, Does.Contain(other.Value).And.Contain(BigKey.Value).And.Contain("code").And.Contain("shared"), "the retry is judged by Resolve");
+                Assert.That(refused.Message, Does.Contain(other.Value).And.Contain(BigKey.Value).And.Contain("code").And.Not.Contain("shared"), "the retry is judged by Resolve");
                 Assert.That(b.Get(other), Is.Null, "nothing landed in memory");
             }
 
@@ -1408,24 +1328,24 @@ namespace GameCult.Caching.Tests
         {
             var path = PathOf("gear.cc");
             var other = new CultRecordKey("other");
-            var narrow = CultDocumentRegistry.ForTypes(new[] { typeof(VariantGear) });
+            var narrow = CultDocumentRegistry.ForTypes(new[] { typeof(VariantOther) });
             using (var seed = Open(path))
                 SeedBase(seed);
 
             using (var a = Open(path))
             using (var b = Open(path, registry: narrow))
             {
-                a.Commit(batch => batch.Upsert(typeof(VariantOther), new VariantOther { Name = "foreign" }, new CultRecordKey("foreign")));
+                a.Commit(batch => batch.Upsert(typeof(VariantGear), Named("foreign", "foreign-code"), new CultRecordKey("foreign")));
                 Assert.That(b.Commit(batch =>
                 {
                     batch.Expect(other, null);
-                    batch.Upsert(typeof(VariantGear), Named("other", "fine"), other);
+                    batch.Upsert(typeof(VariantOther), new VariantOther { Name = "fine" }, other);
                 }), Is.True);
             }
 
             using var reopened = Open(path);
-            Assert.That(reopened.Get<VariantGear>(other), Is.Not.Null);
-            Assert.That(reopened.Get<VariantOther>(new CultRecordKey("foreign")), Is.Not.Null, "the other writer's record survives the merge");
+            Assert.That(reopened.Get<VariantOther>(other), Is.Not.Null);
+            Assert.That(reopened.Get<VariantGear>(new CultRecordKey("foreign")), Is.Not.Null, "the other writer's record survives the merge");
         }
 
         [Test]
@@ -1448,28 +1368,6 @@ namespace GameCult.Caching.Tests
             }
         }
 
-        [Test]
-        public void PlainDuplicatesFindTheSmallestKeyLiveAfterAFlushAndAfterAReopen()
-        {
-            var path = PathOf("gear.cc");
-            using (var cache = Open(path))
-            {
-                cache.Commit(batch => batch.Upsert(typeof(VariantGear), Named("nb", "x"), new CultRecordKey("b")));
-                cache.Commit(batch => batch.Upsert(typeof(VariantGear), Named("na", "x"), new CultRecordKey("a")));
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("na"), "live");
-                cache.BackingStores[0].PushAll();
-                Assert.That(cache.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("na"), "after a flush");
-            }
-
-            using (var reopened = Open(path))
-            {
-                Assert.That(reopened.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("na"), "after a reopen");
-                reopened.Remove(new CultRecordKey("a"));
-                reopened.Commit(batch => batch.Upsert(typeof(VariantGear), Named("na", "x"), new CultRecordKey("a")));
-                Assert.That(reopened.GetByIndex<VariantGear>("code", "x")!.Name, Is.EqualTo("na"), "rewriting the smaller key does not change the choice");
-            }
-        }
-
         [Test]
         public void ADroppedSlotIsReportedOncePerRecord()
         {

tests/GameCult.Networking.Tests/CultNetReplicaCommitTests.cs

@@ -0,0 +1,816 @@
+#nullable enable
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using GameCult.Caching;
+using LiteNetLib;
+using R3;
+using MessagePack;
+using NUnit.Framework;
+
+namespace GameCult.Networking.Tests
+{
+    // variants:ruling:replica-commit-grouped-changes. The authoritative cache judges a commit on its result; a replica applying the
+    // changes one record at a time would judge each intermediate state, where a swap of two [CultIndex] values holds two holders.
+    // The subscription server tags the changes of one cache commit, the client applies them as one commit, and a replica that
+    // refuses a commit says so. No transport: the server and client are joined in memory, and every message crosses MessagePack.
+    public sealed class CultNetReplicaCommitTests
+    {
+        [CultDocument("tests.replica_commit_item", "tests.replica_commit_item.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class ReplicaItem
+        {
+            [Key(0)]
+            [CultIndex("sku")]
+            public string Sku = string.Empty;
+
+            [Key(1)]
+            public string Note = string.Empty;
+        }
+
+        // The change message as a peer from before commit identity knew it.
+        [MessagePackObject]
+        public sealed class LegacyChange
+        {
+            [Key("schemaVersion")] public string SchemaVersion { get; set; } = string.Empty;
+            [Key("messageId")] public string MessageId { get; set; } = string.Empty;
+            [Key("subscriptionId")] public string SubscriptionId { get; set; } = string.Empty;
+            [Key("changeKind")] public string ChangeKind { get; set; } = string.Empty;
+            [Key("document")] public CultNetRawDocumentRecord? Document { get; set; }
+            [Key("recordKey")] public string? RecordKey { get; set; }
+            [Key("schemaId")] public string? SchemaId { get; set; }
+        }
+
+        private sealed class LoopbackServer : ICultNetSchemaServer
+        {
+            private readonly Dictionary<Type, Delegate> _handlers = new();
+            public void OnCultNet<T>(Func<T, ICultNetSchemaServerPeer, Task> callback) where T : ICultNetSchemaMessage => _handlers[typeof(T)] = callback;
+            public void RemoveCultNetMessageListener<T>(Delegate callback) where T : ICultNetSchemaMessage => _handlers.Remove(typeof(T));
+            public Task Dispatch<T>(T message, ICultNetSchemaServerPeer peer) where T : ICultNetSchemaMessage =>
+                ((Func<T, ICultNetSchemaServerPeer, Task>)_handlers[typeof(T)])(message, peer);
+        }
+
+        private sealed class Client : ICultNetSchemaClient
+        {
+            private readonly LoopbackServer _server;
+            private readonly Dictionary<Type, List<Delegate>> _handlers = new();
+            private readonly Peer _peer;
+            public Client(LoopbackServer server, Peer peer) { _server = server; _peer = peer; peer.Client = this; }
+            public bool Connected => true;
+            public void Connect(string host, int port) { }
+            public void SendCultNet<T>(T message) where T : ICultNetSchemaMessage
+            {
+                if (message is CultNetDatabaseSubscribeMessage subscribe)
+                    _server.Dispatch(subscribe, _peer).GetAwaiter().GetResult();
+                else if (message is CultNetDatabaseUnsubscribeMessage unsubscribe)
+                    _server.Dispatch(unsubscribe, _peer).GetAwaiter().GetResult();
+            }
+            public void OnCultNet<T>(Action<T> callback) where T : ICultNetSchemaMessage
+            {
+                if (!_handlers.TryGetValue(typeof(T), out var list)) _handlers[typeof(T)] = list = new List<Delegate>();
+                list.Add(callback);
+            }
+            public void Emit<T>(T message) where T : ICultNetSchemaMessage
+            {
+                if (_handlers.TryGetValue(typeof(T), out var list))
+                    foreach (var handler in list.ToArray()) ((Action<T>)handler)(message);
+            }
+            public void Dispose() { }
+        }
+
+        private sealed class Peer : ICultNetSchemaServerPeer
+        {
+            public Client? Client;
+            public ConcurrentQueue<byte[]> Sent { get; } = new();
+            public void SendCultNet<T>(T message) where T : ICultNetSchemaMessage
+            {
+                // The wire: serialized, then read back as the receiver would.
+                var bytes = CultNetSchemaMessageSerialization.Serialize(message);
+                Sent.Enqueue(bytes);
+                Client!.Emit(CultNetSchemaMessageSerialization.Deserialize<T>(bytes));
+            }
+            public CultNetDatabaseChangeRawMessage[] Changes => Sent
+                .Select(bytes => CultNetSchemaMessageSerialization.Deserialize(bytes))
+                .OfType<CultNetDatabaseChangeRawMessage>().ToArray();
+        }
+
+        private sealed class Replication : IDisposable
+        {
+            public CultCache Source { get; } = new();
+            public CultCache Replica { get; } = new();
+            public Peer Peer { get; } = new();
+            public CultNetDatabaseSubscriptionClient Client { get; }
+            public List<Exception> Faults { get; } = new();
+            public CultNetDatabase Database { get; }
+            private readonly CultNetDatabaseSubscriptionServer _server;
+            public void Reconcile() => _server.Reconcile();
+            public object Gate => typeof(CultNetDatabaseSubscriptionServer)
+                .GetField("_lifecycleGate", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!.GetValue(_server)!;
+
+            public Replication(Action<CultCache>? seedSource = null, Action<CultCache>? seedReplica = null,
+                Func<CultNetDatabaseSubscribeMessage, ICultNetSchemaServerPeer, string, string, bool>? authorizeRecord = null)
+            {
+                seedSource?.Invoke(Source);
+                seedReplica?.Invoke(Replica);
+                Database = new CultNetDatabase(Source);
+                var wire = new LoopbackServer();
+                _server = new CultNetDatabaseSubscriptionServer(wire, Database, authorizeRecord: authorizeRecord);
+                var documents = new CultNetDocumentRegistry(Replica.Registry)
+                    .Register(CultNetDocumentBinding.ForDocument<ReplicaItem>(Replica.Registry));
+                Client = new CultNetDatabaseSubscriptionClient(new Client(wire, Peer), Replica, documents);
+                Client.Faulted += Faults.Add;
+                Client.SubscribeAsync("items", schemaIds: new[] { Source.Registry.GetRequired<ReplicaItem>().SchemaId })
+                    .GetAwaiter().GetResult();
+            }
+
+            public ReplicaItem? ReplicaItem(string key) => Replica.Get<ReplicaItem>(new CultRecordKey(key));
+
+            public void Dispose()
+            {
+                Client.Dispose();
+                _server.Dispose();
+                Database.Dispose();
+            }
+        }
+
+        private static ReplicaItem Item(string sku) => new() { Sku = sku };
+
+        private static void Stage(CultCache cache, params (string Key, string Sku)[] items) =>
+            Assert.That(cache.Commit(batch =>
+            {
+                foreach (var (key, sku) in items)
+                    batch.Upsert(typeof(ReplicaItem), Item(sku), new CultRecordKey(key));
+            }), Is.True);
+
+        private static async Task Until(Func<bool> condition, int seconds = 5)
+        {
+            var deadline = DateTime.UtcNow.AddSeconds(seconds);
+            while (!condition())
+            {
+                if (DateTime.UtcNow > deadline) Assert.Fail("The replica did not reach the expected state.");
+                await Task.Delay(5);
+            }
+        }
+
+        [Test]
+        public async Task ASwapOfTwoIndexValuesReachesTheReplicaIntact()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two")));
+            Assert.That(run.ReplicaItem("a")!.Sku, Is.EqualTo("one"));
+
+            Stage(run.Source, ("a", "two"), ("b", "one"));
+            await Until(() => run.ReplicaItem("a")!.Sku == "two");
+
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("one"));
+            Assert.That(run.Client.Fault, Is.Null);
+            Assert.That(run.Faults, Is.Empty);
+            Assert.That(run.Replica.GetByIndex<ReplicaItem>("sku", "two"), Is.SameAs(run.ReplicaItem("a")));
+            var swap = run.Peer.Changes;
+            Assert.That(swap.Select(change => change.CommitId).Distinct().Single(), Is.Not.Null, "the commit is named on the wire");
+            Assert.That(swap.Select(change => change.CommitCount), Is.All.EqualTo(2));
+        }
+
+        [Test]
+        public async Task AValueMovedToANewRecordWhileItsOldHolderIsRemovedReachesTheReplica()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one")));
+
+            Assert.That(run.Source.Commit(batch =>
+            {
+                batch.Remove(new CultRecordKey("a"));
+                batch.Upsert(typeof(ReplicaItem), Item("one"), new CultRecordKey("c"));
+            }), Is.True);
+            await Until(() => run.ReplicaItem("c") != null);
+
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+            Assert.That(run.Client.Fault, Is.Null);
+            Assert.That(run.Replica.GetByIndex<ReplicaItem>("sku", "one"), Is.SameAs(run.ReplicaItem("c")));
+        }
+
+        [Test]
+        public async Task ACommitOfOneChangeCarriesNoCommitFieldsAndIsApplied()
+        {
+            using var run = new Replication();
+
+            Stage(run.Source, ("a", "one"));
+            await Until(() => run.ReplicaItem("a") != null);
+
+            var change = run.Peer.Changes.Single();
+            Assert.That(change.CommitId, Is.Null);
+            Assert.That(change.CommitCount, Is.Null);
+        }
+
+        [Test]
+        public async Task AReplicaThatRefusesACommitFaultsLoudlyAndAppliesNothingMore()
+        {
+            // The replica holds a record the source does not, under the value the source now gives to another record: a conflict
+            // the replica cannot resolve, not an intermediate state.
+            using var run = new Replication(seedReplica: replica => Stage(replica, ("local", "taken")));
+
+            Stage(run.Source, ("a", "taken"), ("b", "free"));
+            await Until(() => run.Client.Fault != null);
+
+            Assert.That(run.Faults, Has.Count.EqualTo(1));
+            Assert.That(run.Faults[0], Is.SameAs(run.Client.Fault));
+            Assert.That(run.Faults[0].Message, Does.Contain("sku"));
+            Assert.That(run.ReplicaItem("a"), Is.Null, "the refused commit is not partly applied");
+            Assert.That(run.ReplicaItem("b"), Is.Null, "the refused commit is not partly applied");
+
+            Stage(run.Source, ("c", "later"));
+            await Task.Delay(100);
+            Assert.That(run.ReplicaItem("c"), Is.Null, "a replica known to differ takes nothing on top");
+            Assert.That(run.Faults, Has.Count.EqualTo(1));
+        }
+
+        [Test]
+        public void AnOlderPeerReadsTheChangeAndIgnoresTheCommitFields()
+        {
+            var tagged = new CultNetDatabaseChangeRawMessage
+            {
+                MessageId = "m",
+                SubscriptionId = "items",
+                ChangeKind = "removed",
+                RecordKey = "a",
+                SchemaId = "tests.replica_commit_item.v1",
+                CommitId = "7",
+                CommitCount = 2
+            };
+
+            var legacy = MessagePackSerializer.Deserialize<LegacyChange>(
+                CultNetSchemaMessageSerialization.Serialize(tagged), CultNetSchemaMessageSerialization.Options);
+
+            Assert.That(legacy.ChangeKind, Is.EqualTo("removed"));
+            Assert.That(legacy.RecordKey, Is.EqualTo("a"));
+            Assert.That(legacy.SubscriptionId, Is.EqualTo("items"));
+        }
+
+        [Test]
+        public async Task ASwapFromAServerThatDoesNotTagCommitsStillFaultsInsteadOfDiverging()
+        {
+            // An older server sends the two halves of a swap untagged: each is judged alone and refused. The refusal is surfaced.
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two")));
+            var raw = (string key, string sku) => run.Database.Documents.ToRawRecord(
+                run.Source.Registry.GetRequired<ReplicaItem>(), new CultRecordKey(key), Item(sku), "2026-01-01T00:00:00Z");
+
+            run.Peer.Client!.Emit(new CultNetDatabaseChangeRawMessage
+            {
+                MessageId = "x", SubscriptionId = "items", ChangeKind = "updated", Document = raw("a", "two")
+            });
+            await Until(() => run.Client.Fault != null);
+
+            Assert.That(run.ReplicaItem("a")!.Sku, Is.EqualTo("one"));
+        }
+
+        [Test]
+        public async Task ARotationOfThreeValuesReachesTheReplicaIntact()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two"), ("c", "three")));
+
+            Stage(run.Source, ("a", "two"), ("b", "three"), ("c", "one"));
+            await Until(() => run.ReplicaItem("a")!.Sku == "two");
+
+            Assert.That(new[] { "a", "b", "c" }.Select(key => run.ReplicaItem(key)!.Sku), Is.EqualTo(new[] { "two", "three", "one" }));
+            Assert.That(run.Client.Fault, Is.Null);
+            Assert.That(run.Peer.Changes.Select(change => change.CommitCount), Is.All.EqualTo(3));
+        }
+
+        // The database server is the other producer of change messages; it names a commit the same way.
+        [Test]
+        public void TheDatabaseServerTagsTheChangesOfOneCommitAndNotALoneChange()
+        {
+            var cache = new CultCache();
+            Stage(cache, ("a", "one"), ("b", "two"));
+            using var database = new CultNetDatabase(cache);
+            using var server = new Server(cache, ServerSecurityOptions.Development());
+            using var databaseServer = new CultNetDatabaseServer(server, database);
+            var commits = new List<CultNetDatabaseCommit>();
+            using var watch = database.WatchCommits().Subscribe(commits.Add);
+            var selection = new CultNetSelection
+            {
+                Schemas = new[] { cache.Registry.GetRequired<ReplicaItem>().SchemaId },
+                Projection = CultNetSelectionProjections.Document
+            };
+            IReadOnlyList<CultNetDatabaseChangeRawMessage> Deliver(CultNetDatabaseCommit commit) =>
+                (IReadOnlyList<CultNetDatabaseChangeRawMessage>)typeof(CultNetDatabaseServer)
+                    .GetMethod("DeliverCommit", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!
+                    .Invoke(databaseServer, new object[] { commit, "sub", selection, new HashSet<string>(), (Action<CultNetErrorMessage>)(_ => { }) })!;
+
+            Stage(cache, ("a", "two"), ("b", "one"));
+            Stage(cache, ("c", "three"));
+
+            var swap = Deliver(commits[0]);
+            Assert.That(swap, Has.Count.EqualTo(2));
+            Assert.That(swap.Select(change => change.CommitId).Distinct().Single(), Is.EqualTo(commits[0].Id));
+            Assert.That(swap.Select(change => change.CommitCount), Is.All.EqualTo(2));
+            var lone = Deliver(commits[1]).Single();
+            Assert.That(lone.CommitId, Is.Null);
+            Assert.That(lone.CommitCount, Is.Null);
+            Assert.That(commits[0].Id, Is.Not.EqualTo(commits[1].Id));
+        }
+
+        [Test]
+        public void ASnapshotThatSwapsIndexValuesAgainstWhatTheReplicaHoldsIsApplied()
+        {
+            using var run = new Replication(
+                source => Stage(source, ("a", "two"), ("b", "one")),
+                replica => Stage(replica, ("a", "one"), ("b", "two")));
+
+            Assert.That(run.ReplicaItem("a")!.Sku, Is.EqualTo("two"));
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("one"));
+        }
+
+        // Hand-made wire messages: what a peer sends that the real server would not.
+        private static CultNetDatabaseChangeRawMessage Put(Replication run, string subscription, string key, string sku, string? commit, int count, string? id = null) =>
+            new()
+            {
+                MessageId = id ?? Guid.NewGuid().ToString("N"),
+                SubscriptionId = subscription,
+                ChangeKind = "updated",
+                Document = run.Database.Documents.ToRawRecord(
+                    run.Source.Registry.GetRequired<ReplicaItem>(), new CultRecordKey(key), Item(sku), "2026-01-01T00:00:00Z"),
+                CommitId = commit,
+                CommitCount = commit == null ? null : count
+            };
+
+        private static CultNetDatabaseChangeRawMessage Removal(string subscription, string key, string commit, int count) =>
+            new()
+            {
+                MessageId = Guid.NewGuid().ToString("N"),
+                SubscriptionId = subscription,
+                ChangeKind = "removed",
+                RecordKey = key,
+                SchemaId = "tests.replica_commit_item.v1",
+                CommitId = commit,
+                CommitCount = count
+            };
+
+        [Test]
+        public async Task TwoSubscriptionsMayUseOneCommitIdWithoutJoiningTheirCommits()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two")));
+            run.Client.SubscribeAsync("other", recordKeys: new[] { "nothing-matches" }).GetAwaiter().GetResult();
+            var emit = run.Peer.Client!;
+
+            emit.Emit(Put(run, "items", "a", "two", "9", 2));
+            emit.Emit(Put(run, "other", "x", "ex", "9", 2));
+            await Task.Delay(100);
+            Assert.That(run.ReplicaItem("a")!.Sku, Is.EqualTo("one"), "one change of each of two commits is not a commit");
+            Assert.That(run.ReplicaItem("x"), Is.Null);
+
+            emit.Emit(Put(run, "items", "b", "one", "9", 2));
+            await Until(() => run.ReplicaItem("a")!.Sku == "two");
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("one"));
+            Assert.That(run.ReplicaItem("x"), Is.Null);
+            Assert.That(run.Client.Fault, Is.Null);
+        }
+
+        [Test]
+        public async Task ARemovalAfterTheFirstChangeOfACommitIsApplied()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one")));
+            var emit = run.Peer.Client!;
+
+            emit.Emit(Put(run, "items", "c", "one", "5", 2));
+            emit.Emit(Removal("items", "a", "5", 2));
+            await Until(() => run.ReplicaItem("c") != null);
+
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+            Assert.That(run.Client.Fault, Is.Null);
+        }
+
+        [Test]
+        public void ASnapshotOfManyDocumentsAppliesEveryOne()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two"), ("c", "three"), ("d", "four")));
+
+            Assert.That(new[] { "a", "b", "c", "d" }.Select(key => run.ReplicaItem(key)?.Sku), Is.EqualTo(new[] { "one", "two", "three", "four" }));
+        }
+
+        [Test]
+        public async Task ManyCommitsInARowAreNotMistakenForAnUnboundedBuffer()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "s0"), ("b", "s1")));
+
+            for (var round = 1; round <= 80; round++)
+            {
+                var a = "s" + (round % 2);
+                var b = "s" + ((round + 1) % 2);
+                Stage(run.Source, ("a", a), ("b", b));
+            }
+
+            Stage(run.Source, ("a", "last-a"), ("b", "last-b"));
+            await Until(() => run.Client.Fault != null || run.ReplicaItem("a")!.Sku == "last-a");
+            Assert.That(run.Client.Fault, Is.Null, "completed commits leave the buffer");
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("last-b"));
+        }
+
+        [Test]
+        public async Task AMessageDeliveredTwiceInOneCommitFaults()
+        {
+            using var run = new Replication();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "3", 3, id: "same"));
+            run.Peer.Client!.Emit(Put(run, "items", "b", "two", "3", 3, id: "same"));
+            await Until(() => run.Client.Fault != null);
+
+            Assert.That(run.Faults, Has.Count.EqualTo(1));
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+        }
+
+        [Test]
+        public async Task ACommitThatChangesItsAnnouncedSizeFaults()
+        {
+            using var run = new Replication();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "3", 2));
+            run.Peer.Client!.Emit(Put(run, "items", "b", "two", "3", 3));
+            await Until(() => run.Client.Fault != null);
+
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+        }
+
+        [Test]
+        public async Task ACommitAnnouncingMoreChangesThanAReplicaHoldsFaults()
+        {
+            using var run = new Replication();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "3", 1_000_001));
+            await Until(() => run.Client.Fault != null);
+        }
+
+        [Test]
+        public async Task MoreIncompleteCommitsThanTheBoundFault()
+        {
+            using var run = new Replication();
+
+            for (var commit = 0; commit < 64; commit++)
+                run.Peer.Client!.Emit(Put(run, "items", "k" + commit, "v" + commit, "c" + commit, 2));
+            await Task.Delay(200);
+            Assert.That(run.Client.Fault, Is.Null, "64 incomplete commits are within the bound");
+            Assert.That(Pending(run.Client), Is.EqualTo(64));
+
+            run.Peer.Client!.Emit(Put(run, "items", "k64", "v64", "c64", 2));
+            await Until(() => run.Client.Fault != null);
+            Assert.That(Pending(run.Client), Is.Zero, "a fault drops what was waiting");
+        }
+
+        [Test]
+        public async Task UnsubscribingDropsTheCommitsStillWaiting()
+        {
+            using var run = new Replication();
+            var emit = run.Peer.Client!;
+
+            emit.Emit(Put(run, "items", "a", "one", "4", 2));
+            await Task.Delay(50);
+            run.Client.Unsubscribe("items");
+            emit.Emit(Put(run, "items", "b", "two", "4", 2));
+            await Task.Delay(100);
+
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+            Assert.That(run.ReplicaItem("b"), Is.Null, "the second half of a dropped commit is not a commit");
+        }
+
+        [Test]
+        public async Task AFaultedClientRefusesANewSubscription()
+        {
+            using var run = new Replication(seedReplica: replica => Stage(replica, ("local", "taken")));
+            Stage(run.Source, ("a", "taken"));
+            await Until(() => run.Client.Fault != null);
+
+            var refusal = Assert.Throws<InvalidOperationException>(() => run.Client.SubscribeAsync("again"));
+            Assert.That(refusal!.InnerException, Is.SameAs(run.Client.Fault));
+        }
+
+        private static int Pending(CultNetDatabaseSubscriptionClient client)
+        {
+            var commits = (System.Collections.IDictionary)typeof(CultNetDatabaseSubscriptionClient)
+                .GetField("_commits", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!.GetValue(client)!;
+            lock (commits)
+                return commits.Count;
+        }
+
+        [Test]
+        public async Task TheIncompleteCommitsMayAnnounceOneMillionChangesBetweenThem()
+        {
+            using var run = new Replication();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "1", 500_000));
+            run.Peer.Client!.Emit(Put(run, "items", "b", "two", "2", 500_000));
+            await Task.Delay(200);
+            Assert.That(run.Client.Fault, Is.Null, "500k and 500k fit");
+
+            run.Peer.Client!.Emit(Put(run, "items", "c", "three", "3", 2));
+            await Until(() => run.Client.Fault != null);
+        }
+
+        [Test]
+        public async Task ACommitOfOneMillionChangesIsHeldAndOneMillionAndOneIsNot()
+        {
+            using var held = new Replication();
+            held.Peer.Client!.Emit(Put(held, "items", "a", "one", "1", 1_000_000));
+            await Task.Delay(200);
+            Assert.That(held.Client.Fault, Is.Null);
+            Assert.That(Pending(held.Client), Is.EqualTo(1));
+
+            using var over = new Replication();
+            over.Peer.Client!.Emit(Put(over, "items", "a", "one", "1", 1_000_001));
+            await Until(() => over.Client.Fault != null);
+        }
+
+        [Test]
+        public async Task ACommitThatShrinksItsAnnouncedSizeFaults()
+        {
+            using var run = new Replication();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "3", 3));
+            run.Peer.Client!.Emit(Put(run, "items", "b", "two", "3", 2));
+            await Until(() => run.Client.Fault != null);
+        }
+
+        [Test]
+        public async Task UnsubscribingOneSubscriptionKeepsTheCommitsOfAnother()
+        {
+            using var run = new Replication();
+            run.Client.SubscribeAsync("items2", recordKeys: new[] { "nothing-matches" }).GetAwaiter().GetResult();
+            var emit = run.Peer.Client!;
+
+            emit.Emit(Put(run, "items", "a", "one", "4", 2));
+            emit.Emit(Put(run, "items2", "b", "two", "4", 2));
+            await Task.Delay(100);
+            Assert.That(Pending(run.Client), Is.EqualTo(2));
+
+            run.Client.Unsubscribe("items");
+            Assert.That(Pending(run.Client), Is.EqualTo(1), "only the unsubscribed subscription's commits leave");
+            emit.Emit(Put(run, "items2", "c", "three", "4", 2));
+            await Until(() => run.ReplicaItem("b") != null);
+            Assert.That(run.ReplicaItem("c"), Is.Not.Null);
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+        }
+
+        [Test]
+        public async Task AStragglerAfterUnsubscribeOrFromAnUnknownSubscriptionIsNotBuffered()
+        {
+            using var run = new Replication();
+            run.Client.Unsubscribe("items");
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "4", 2));
+            run.Peer.Client!.Emit(Put(run, "never-subscribed", "b", "two", "4", 2));
+            await Task.Delay(150);
+
+            Assert.That(Pending(run.Client), Is.Zero);
+            Assert.That(run.Client.Fault, Is.Null);
+        }
+
+        [Test]
+        public void DisposingTheClientDropsTheCommitsStillWaiting()
+        {
+            var run = new Replication();
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "4", 2));
+            SpinWait.SpinUntil(() => Pending(run.Client) == 1, 2000);
+            Assert.That(Pending(run.Client), Is.EqualTo(1));
+
+            run.Dispose();
+
+            Assert.That(Pending(run.Client), Is.Zero);
+        }
+
+        [Test]
+        public async Task AFaultedClientBuffersNothingMore()
+        {
+            using var run = new Replication();
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "3", 3, id: "same"));
+            run.Peer.Client!.Emit(Put(run, "items", "b", "two", "3", 3, id: "same"));
+            await Until(() => run.Client.Fault != null);
+
+            run.Peer.Client!.Emit(Put(run, "items", "c", "three", "8", 2));
+            run.Peer.Client!.Emit(Put(run, "items", "d", "four", "9", 2));
+            await Task.Delay(150);
+
+            Assert.That(Pending(run.Client), Is.Zero);
+            Assert.That(run.Faults, Has.Count.EqualTo(1), "a fault is reported once");
+        }
+
+        [Test]
+        public void AFaultIsReportedOnceHoweverOftenItIsRaised()
+        {
+            using var run = new Replication();
+            var raise = typeof(CultNetDatabaseSubscriptionClient)
+                .GetMethod("Break", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!;
+
+            raise.Invoke(run.Client, new object[] { new InvalidOperationException("first") });
+            raise.Invoke(run.Client, new object[] { new InvalidOperationException("second") });
+
+            Assert.That(run.Faults, Has.Count.EqualTo(1));
+            Assert.That(run.Client.Fault!.Message, Is.EqualTo("first"));
+        }
+
+        private static object CommitsOf(CultNetDatabaseSubscriptionClient client) =>
+            typeof(CultNetDatabaseSubscriptionClient)
+                .GetField("_commits", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!.GetValue(client)!;
+
+        // The check that a subscription is live belongs to the same lock Unsubscribe evicts under. The test holds that lock (it is
+        // re-entrant), waits until the straggler's handler is contending for it, ends the subscription, and releases: a handler
+        // that had already passed its check by then would buffer a commit nobody will ever finish.
+        [Test]
+        public void AStragglerThatArrivedBeforeUnsubscribeBuffersNothingAfterIt()
+        {
+            using var run = new Replication();
+            Task tail;
+
+            lock (CommitsOf(run.Client))
+            {
+                var contended = Monitor.LockContentionCount;
+                run.Peer.Client!.Emit(Put(run, "items", "a", "one", "4", 2));
+                Assert.That(SpinWait.SpinUntil(() => Monitor.LockContentionCount > contended, 10_000), "the handler never reached the lock");
+                run.Client.Unsubscribe("items");
+                tail = (Task)typeof(CultNetDatabaseSubscriptionClient)
+                    .GetField("_queue", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!.GetValue(run.Client)!;
+            }
+            tail.GetAwaiter().GetResult();
+
+            Assert.That(Pending(run.Client), Is.Zero);
+            Assert.That(run.Client.Fault, Is.Null);
+        }
+
+        // The 1,000,000 budget is the client's, over every subscription's incomplete commits, not each subscription's own.
+        [Test]
+        public async Task TheBudgetIsSharedByAllSubscriptions()
+        {
+            using var run = new Replication();
+            run.Client.SubscribeAsync("items2", recordKeys: new[] { "nothing-matches" }).GetAwaiter().GetResult();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "1", 600_000));
+            run.Peer.Client!.Emit(Put(run, "items2", "b", "two", "2", 400_000));
+            await Task.Delay(200);
+            Assert.That(run.Client.Fault, Is.Null, "600k and 400k fit in one million");
+            Assert.That(Pending(run.Client), Is.EqualTo(2));
+
+            run.Peer.Client!.Emit(Put(run, "items2", "c", "three", "3", 2));
+            await Until(() => run.Client.Fault != null);
+        }
+
+        [Test]
+        public async Task TwoSubscriptionsAnnouncingMoreThanTheBudgetBetweenThemFault()
+        {
+            using var run = new Replication();
+            run.Client.SubscribeAsync("items2", recordKeys: new[] { "nothing-matches" }).GetAwaiter().GetResult();
+
+            run.Peer.Client!.Emit(Put(run, "items", "a", "one", "1", 600_000));
+            run.Peer.Client!.Emit(Put(run, "items2", "b", "two", "2", 600_000));
+            await Until(() => run.Client.Fault != null);
+            Assert.That(Pending(run.Client), Is.Zero);
+        }
+
+        [Test]
+        public async Task AStragglerFromAnUnknownIdIsDroppedWhileAnotherSubscriptionIsLive()
+        {
+            using var run = new Replication();
+            run.Client.SubscribeAsync("items2", recordKeys: new[] { "nothing-matches" }).GetAwaiter().GetResult();
+            run.Peer.Client!.Emit(Put(run, "items2", "b", "two", "4", 2));
+            await Until(() => Pending(run.Client) == 1);
+
+            run.Peer.Client!.Emit(Put(run, "items-ghost", "a", "one", "4", 2));
+            run.Peer.Client!.Emit(Put(run, "items-ghost", "c", "three", "5", 3));
+            run.Peer.Client!.Emit(Put(run, "item", "e", "five", "6", 2));
+            await Task.Delay(200);
+
+            Assert.That(Pending(run.Client), Is.EqualTo(1), "only the live subscription's commit is held");
+            Assert.That(run.Client.Fault, Is.Null);
+            run.Peer.Client!.Emit(Put(run, "items2", "d", "four", "4", 2));
+            await Until(() => run.ReplicaItem("b") != null);
+            Assert.That(run.ReplicaItem("a"), Is.Null);
+        }
+
+        // Reconcile() can run after the cache admitted a commit and before the subscription's Watch has seen it (the observer
+        // runs on the writer's thread after the cache gate opens). Its diff then carries changed values, and a swap sent record by
+        // record faults the replica. The test holds the subscription server's gate to stand in that window.
+        [Test]
+        public async Task AReconcileThatRacesACommitSendsItsSwapAsOneCommit()
+        {
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two")));
+            Task write;
+
+            lock (run.Gate)
+            {
+                write = Task.Run(() => Stage(run.Source, ("a", "two"), ("b", "one")));
+                Assert.That(SpinWait.SpinUntil(() => run.Source.Get<ReplicaItem>(new CultRecordKey("a"))!.Sku == "two", 10_000),
+                    "the source did not take the swap");
+                run.Reconcile();
+            }
+            await write;
+            await Until(() => run.ReplicaItem("a")!.Sku == "two");
+
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("one"));
+            Assert.That(run.Client.Fault, Is.Null);
+            Assert.That(run.Peer.Changes.Select(change => change.CommitCount), Is.All.EqualTo(2));
+        }
+
+        [Test]
+        public async Task ReconcilingAfterAPolicyChangeThatFollowsASwapLeavesTheReplicaIntact()
+        {
+            var hidden = new HashSet<string>();
+            using var run = new Replication(source => Stage(source, ("a", "one"), ("b", "two")),
+                authorizeRecord: (_, _, key, _) => !hidden.Contains(key));
+            hidden.Add("b");
+
+            Stage(run.Source, ("a", "two"), ("b", "one"));
+            await Until(() => run.ReplicaItem("b") == null && run.ReplicaItem("a")!.Sku == "two");
+
+            hidden.Remove("b");
+            hidden.Add("a");
+            run.Reconcile();
+            await Until(() => run.ReplicaItem("b") != null && run.ReplicaItem("a") == null);
+
+            Assert.That(run.ReplicaItem("b")!.Sku, Is.EqualTo("one"));
+            Assert.That(run.Client.Fault, Is.Null);
+        }
+
+        // Source, wire and client all real: a CultNetDatabaseServer behind a Server on a loopback socket, a LiteNetLib client
+        // standing in for the transport of a CultNetDatabaseSubscriptionClient. No handler is called directly.
+        private sealed class SocketClient : ICultNetSchemaClient
+        {
+            private readonly NetManager _manager;
+            private readonly NetPeer _peer;
+            private readonly List<Action<CultNetSnapshotResponseRawMessage>> _snapshots = new();
+            private readonly List<Action<CultNetDatabaseChangeRawMessage>> _changes = new();
+
+            public SocketClient(int port, string key)
+            {
+                var listener = new EventBasedNetListener();
+                var connected = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
+                var decoder = new LiteNetLibTransportConnection();
+                listener.PeerConnectedEvent += _ => connected.TrySetResult(true);
+                listener.NetworkReceiveEvent += (_, reader, _, _) =>
+                {
+                    switch (LiteNetLibTransportConnection.DecodeSchema(decoder.Receive(reader.GetRemainingBytes())))
+                    {
+                        case CultNetSnapshotResponseRawMessage snapshot: foreach (var handler in _snapshots.ToArray()) handler(snapshot); break;
+                        case CultNetDatabaseChangeRawMessage change: foreach (var handler in _changes.ToArray()) handler(change); break;
+                    }
+                };
+                _manager = new NetManager(listener) { UnsyncedEvents = true };
+                _manager.Start(0);
+                _peer = _manager.Connect("127.0.0.1", port, key);
+                if (!connected.Task.Wait(TimeSpan.FromSeconds(10))) Assert.Fail("the client did not connect");
+            }
+
+            public bool Connected => _peer.ConnectionState == ConnectionState.Connected;
+            public void Connect(string host, int port) { }
+            public void SendCultNet<T>(T message) where T : ICultNetSchemaMessage =>
+                _peer.Send(CultNetSchemaMessageSerialization.Serialize(message), DeliveryMethod.ReliableOrdered);
+            public void OnCultNet<T>(Action<T> callback) where T : ICultNetSchemaMessage
+            {
+                if (callback is Action<CultNetSnapshotResponseRawMessage> snapshot) _snapshots.Add(snapshot);
+                else if (callback is Action<CultNetDatabaseChangeRawMessage> change) _changes.Add(change);
+            }
+            public void Dispose() => _manager.Stop();
+        }
+
+        [Test]
+        public async Task ASwapThroughTheRealDatabaseServerReachesTheClientIntact()
+        {
+            var source = new CultCache();
+            Stage(source, ("a", "one"), ("b", "two"));
+            using var database = new CultNetDatabase(source);
+            using var server = new Server(source, ServerSecurityOptions.Development()) { Port = 0 };
+            using var databaseServer = new CultNetDatabaseServer(server, database);
+            server.Start();
+            var replica = new CultCache();
+            var documents = new CultNetDocumentRegistry(replica.Registry)
+                .Register(CultNetDocumentBinding.ForDocument<ReplicaItem>(replica.Registry));
+            using var client = new CultNetDatabaseSubscriptionClient(
+                new SocketClient(server.Port, ServerSecurityOptions.Development().ConnectionKey), replica, documents);
+            var faults = new List<Exception>();
+            client.Faulted += faults.Add;
+            await client.SubscribeAsync("items", schemaIds: new[] { source.Registry.GetRequired<ReplicaItem>().SchemaId });
+            Assert.That(replica.Get<ReplicaItem>(new CultRecordKey("a"))!.Sku, Is.EqualTo("one"));
+
+            Stage(source, ("a", "two"), ("b", "one"));
+            await Until(() => replica.Get<ReplicaItem>(new CultRecordKey("a"))!.Sku == "two");
+
+            Assert.That(replica.Get<ReplicaItem>(new CultRecordKey("b"))!.Sku, Is.EqualTo("one"));
+            Assert.That(replica.GetByIndex<ReplicaItem>("sku", "one"), Is.SameAs(replica.Get<ReplicaItem>(new CultRecordKey("b"))));
+            Assert.That(client.Fault, Is.Null);
+            Assert.That(faults, Is.Empty);
+        }
+
+        [TestCase(5000)]
+        [TestCase(100_000)]
+        public async Task ACommitOfManyChangesThroughTheRealSubscriptionServerAppliesIntact(int size)
+        {
+            using var run = new Replication();
+            var keys = Enumerable.Range(0, size).Select(i => ("k" + i, "s" + i)).ToArray();
+
+            Stage(run.Source, keys);
+            await Until(() => run.ReplicaItem("k" + (size - 1)) != null || run.Client.Fault != null, seconds: 180);
+
+            Assert.That(run.Client.Fault, Is.Null);
+            Assert.That(run.Replica.GetAll<ReplicaItem>().Count(), Is.EqualTo(size));
+            Assert.That(run.Peer.Changes.Select(change => change.CommitCount).Distinct().Single(), Is.EqualTo(size));
+            Assert.That(run.ReplicaItem("k" + (size / 2))!.Sku, Is.EqualTo("s" + (size / 2)));
+        }
+    }
+}

tests/GameCult.Networking.Tests/CultNetSelectionEvaluatorTests.cs

@@ -486,6 +486,39 @@ namespace GameCult.Networking.Tests
             Assert.That(evaluation.Rows.Select(r => r.Key.Value), Is.EqualTo(new[] { "a" }));
         }
 
+        // [CultIndex] means unique and is also a selection address: a unique member filters by equality and by number like a role.
+        [Test]
+        public void AUniqueIndexMemberIsAlsoSelectable()
+        {
+            var registry = CultDocumentRegistry.ForTypes(new[] { typeof(SelUnique) });
+            var rows = new[]
+            {
+                Row(registry, new SelUnique { Sku = "s1", Rank = 1 }, "a", 1),
+                Row(registry, new SelUnique { Sku = "s2", Rank = 7 }, "b", 2)
+            };
+
+            var byValue = CultNetSelectionEvaluator.Select(registry, rows,
+                new CultNetSelection { Fields = new[] { new CultNetFieldPredicate { Index = "sku", Op = "any_of", Values = new[] { "s2" } } } }, asOf: 2);
+            var byNumber = CultNetSelectionEvaluator.Select(registry, rows,
+                new CultNetSelection { Fields = new[] { new CultNetFieldPredicate { Index = "rank", Op = "gt", Number = "3" } } }, asOf: 2);
+
+            Assert.That(byValue.Rows.Select(r => r.Key.Value), Is.EqualTo(new[] { "b" }));
+            Assert.That(byNumber.Rows.Select(r => r.Key.Value), Is.EqualTo(new[] { "b" }));
+        }
+
+        [CultDocument("cultnet.selection-tests.unique", "cultnet.selection-tests.unique.v1")]
+        [MessagePackObject(AllowPrivate = true)]
+        public sealed class SelUnique
+        {
+            [Key(0)]
+            [CultIndex("sku")]
+            public string Sku = string.Empty;
+
+            [Key(1)]
+            [CultIndex("rank")]
+            public int Rank;
+        }
+
         public abstract class SelFixtureMiddle
         {
             [Key(0)]
@@ -493,11 +526,11 @@ namespace GameCult.Networking.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("mass")]
+            [CultRole("mass")]
             public float Mass;
 
             [Key(2)]
-            [CultIndex("kind")]
+            [CultRole("kind")]
             public string Kind = string.Empty;
         }
 

tests/GameCult.Networking.Tests/CultNetSelectionFixBatchTests.cs

@@ -581,7 +581,7 @@ namespace GameCult.Networking.Tests
                 return instance;
             }
 
-            // A plain data member "Owner" with no [CultIndex] (its role falls back to its bare name)
+            // A plain data member "Owner" with no [CultRole] (its role falls back to its bare name)
             // and a reference member whose alias is explicitly "Owner" - the exact shape Soul probed.
             var ownerMember = MakeMember(typeof(GuardProbeShape).GetField(nameof(GuardProbeShape.Owner))!,
                 typeof(string), 0, indexAlias: null, isReference: false, targetType: null);

tests/GameCult.Networking.Tests/CultNetSelectionPageTests.cs

@@ -130,7 +130,7 @@ namespace GameCult.Networking.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("kind")]
+            [CultRole("kind")]
             public string Kind = string.Empty;
         }
 

tests/GameCult.Networking.Tests/CultNetSelectionSurvivorTests.cs

@@ -62,7 +62,7 @@ namespace GameCult.Networking.Tests
         public sealed class SurvivorNumericLeaf
         {
             [Key(0)] [CultName] public string Name = string.Empty;
-            [Key(1)] [CultIndex("level")] public int Level;
+            [Key(1)] [CultRole("level")] public int Level;
         }
 
         [CultDocument("cultnet.selection-tests.survivor_string_leaf", "cultnet.selection-tests.survivor_string_leaf.v1")]
@@ -70,7 +70,7 @@ namespace GameCult.Networking.Tests
         public sealed class SurvivorStringLeaf
         {
             [Key(0)] [CultName] public string Name = string.Empty;
-            [Key(1)] [CultIndex("level")] public string Level = string.Empty;
+            [Key(1)] [CultRole("level")] public string Level = string.Empty;
         }
 
         // ---------------------------------------------------------------------------------------------
@@ -173,7 +173,7 @@ namespace GameCult.Networking.Tests
             // The declared index alias ("linkRole") differs from the member name ("Link") - the exact
             // shape section 2's role-naming rule exists for, and no prior fixture had one.
             [Key(1)]
-            [CultIndex("linkRole")]
+            [CultRole("linkRole")]
             [CultReference(typeof(SurvivorAliasTarget))]
             public CultRecordRef<SurvivorAliasTarget> Link;
         }
@@ -408,7 +408,7 @@ namespace GameCult.Networking.Tests
             [Key(0)] [CultName] public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("hopRole")]
+            [CultRole("hopRole")]
             [CultReference(typeof(SurvivorAliasTarget))]
             public CultRecordRef<SurvivorAliasTarget> Link;
         }
@@ -431,12 +431,12 @@ namespace GameCult.Networking.Tests
             [Key(0)] [CultName] public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("zLastRole")]
+            [CultRole("zLastRole")]
             [CultReference(typeof(SurvivorAliasTarget))]
             public CultRecordRef<SurvivorAliasTarget> RefZ;
 
             [Key(2)]
-            [CultIndex("aFirstRole")]
+            [CultRole("aFirstRole")]
             [CultReference(typeof(SurvivorAliasTarget))]
             public CultRecordRef<SurvivorAliasTarget> RefA;
         }

tests/GameCult.Networking.Tests/GovernanceVectorTests.cs

@@ -0,0 +1,817 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using MessagePack;
+using NUnit.Framework;
+
+namespace GameCult.Networking.Tests
+{
+    // contracts/cultnet/governance: the vote-API and fork-card contracts (vote-api.md, fork-card.md). The vectors are spec-authored
+    // (scripts/gen-governance-vectors.py); this suite re-encodes every message with MessagePack C#, must reproduce the bytes, judges
+    // every negative with the committed schema, and replays the fork scenarios through a reference judge written from fork-card.md.
+    public sealed class GovernanceVectorTests
+    {
+        private const string VoteSchema = "governance/vote-api.schema.json";
+        private const string ForkSchema = "governance/fork-card.schema.json";
+
+        private static string RepoRoot()
+        {
+            var directory = new DirectoryInfo(TestContext.CurrentContext.TestDirectory);
+            while (directory != null && !File.Exists(Path.Combine(directory.FullName, "CultLib.sln")))
+                directory = directory.Parent;
+            return directory?.FullName ?? throw new InvalidOperationException("CultLib.sln was not found above the test directory.");
+        }
+
+        private static JsonNode Load(string name) =>
+            JsonNode.Parse(File.ReadAllText(Path.Combine(RepoRoot(), "contracts", "cultnet", "governance", name)))!;
+
+        private static readonly JsonNode Vote = Load("vote-api-vectors.json");
+        private static readonly JsonNode Fork = Load("fork-card-vectors.json");
+        private static MiniJsonSchemaValidator Validator() => new(Path.Combine(RepoRoot(), "contracts", "cultnet"));
+
+        private static List<string> Errors(string file, string def, JsonNode? value)
+        {
+            var element = JsonSerializer.SerializeToElement(value);
+            return Validator().Validate(element, $"{file}#/$defs/{def}");
+        }
+
+        // MessagePack C# writes the message in the order the keys appear: shortest ints, shortest strings.
+        private static void Write(ref MessagePackWriter w, JsonNode? n)
+        {
+            switch (n)
+            {
+                case null: w.WriteNil(); break;
+                case JsonObject o:
+                    w.WriteMapHeader(o.Count);
+                    foreach (var kv in o) { w.Write(kv.Key); Write(ref w, kv.Value); }
+                    break;
+                case JsonArray a:
+                    w.WriteArrayHeader(a.Count);
+                    foreach (var item in a) Write(ref w, item);
+                    break;
+                case JsonValue v when v.TryGetValue<bool>(out var b): w.Write(b); break;
+                case JsonValue v when v.TryGetValue<int>(out var i): w.Write(i); break;
+                case JsonValue v when v.TryGetValue<long>(out var l): w.Write(l); break;
+                case JsonValue v: w.Write(v.GetValue<string>()); break;
+            }
+        }
+
+        private static string HexOf(JsonNode? message)
+        {
+            var buffer = new System.Buffers.ArrayBufferWriter<byte>();
+            var writer = new MessagePackWriter(buffer);
+            Write(ref writer, message);
+            writer.Flush();
+            return Convert.ToHexString(buffer.WrittenSpan);
+        }
+
+        private static string Sha(byte[] bytes) => Convert.ToHexString(SHA256.HashData(bytes)).ToLowerInvariant();
+        private static string S(JsonNode? n) => n!.GetValue<string>();
+        private static JsonNode? Clone(JsonNode? n) => n is null ? null : JsonNode.Parse(n.ToJsonString());
+
+        // Rules a JSON Schema cannot say: vote-api.md counts a reason in UTF-16 code units (as Bifrost does); maxLength counts code points.
+        private static IEnumerable<string> VoteRuleErrors(string def, JsonNode? message)
+        {
+            if (def == "cast" && message?["ballot"] is JsonNode ballot && S(ballot["reason"]).Length > 280) yield return "reason is over 280 UTF-16 code units";
+        }
+
+        [Test]
+        public void VoteApi_ValidDocuments_ValidateEncodeToTheVectorBytesAndDecodeBack()
+        {
+            foreach (var v in Vote["valid"]!.AsArray())
+            {
+                var name = S(v!["name"]);
+                Assert.That(Errors(VoteSchema, S(v["def"]), v["message"]), Is.Empty, name);
+                Assert.That(VoteRuleErrors(S(v["def"]), v["message"]), Is.Empty, name);
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), name);
+                var decoded = JsonNode.Parse(MessagePackSerializer.ConvertToJson(Convert.FromHexString(S(v["messagePackHex"]))))!;
+                Assert.That(JsonNode.DeepEquals(decoded, v["message"]), Is.True, name);
+            }
+        }
+
+        [Test]
+        public void VoteApi_EveryNegative_IsRefusedBySchemaAndKeepsItsBytes()
+        {
+            foreach (var v in Vote["invalid"]!.AsArray())
+            {
+                var name = S(v!["name"]);
+                Assert.That(Errors(VoteSchema, S(v["def"]), v["message"]).Count > 0 || VoteRuleErrors(S(v["def"]), v["message"]).Any(), Is.True, $"{name}: {S(v["why"])}");
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), name);
+            }
+        }
+
+        private static byte[] CommitmentBytes(JsonNode b, string voter) => Encoding.UTF8.GetBytes(
+            $"gamecult.sealed_ballot.v0\n{S(b["motionId"])}\n{voter}\n{S(b["persona"])}\n{b["round"]!.GetValue<long>()}\n{S(b["candidate"])}\n{S(b["reason"])}\n{S(b["salt"])}");
+
+        [Test]
+        public void VoteApi_Commitment_IsSha256OfTheCanonicalBytes_AndRevealMatchesExactlyWhenItHashesToIt()
+        {
+            foreach (var c in Vote["commitment"]!.AsArray())
+            {
+                var bytes = CommitmentBytes(c!["ballot"]!, S(c["voterUserAccountId"]));
+                Assert.That(Convert.ToHexString(bytes), Is.EqualTo(S(c["canonicalHex"])), S(c["name"]));
+                Assert.That(Sha(bytes), Is.EqualTo(S(c["sha256"])), S(c["name"]));
+            }
+            foreach (var p in Vote["pairs"]!.AsArray())
+            {
+                var digest = Sha(CommitmentBytes(p!["reveal"]!["ballot"]!, S(p["voterUserAccountId"])));
+                Assert.That(digest == S(p["commit"]!["commitment"]), Is.EqualTo(p["matches"]!.GetValue<bool>()), S(p["name"]));
+                Assert.That(Errors(VoteSchema, "cast", p["commit"]), Is.Empty);
+                Assert.That(Errors(VoteSchema, "cast", p["reveal"]), Is.Empty);
+            }
+        }
+
+        [Test]
+        public void VoteApi_EachRefusalCode_HasAVectorAStatusAndTheVectorBytes()
+        {
+            var schema = JsonNode.Parse(File.ReadAllText(Path.Combine(RepoRoot(), "contracts", "cultnet", VoteSchema)))!;
+            var codes = schema["$defs"]!["refusal"]!["properties"]!["code"]!["enum"]!.AsArray().Select(S).OrderBy(x => x, StringComparer.Ordinal);
+            var vectors = Vote["refusals"]!.AsArray();
+            Assert.That(vectors.Select(r => S(r!["message"]!["code"])).OrderBy(x => x, StringComparer.Ordinal), Is.EqualTo(codes));
+            foreach (var r in vectors)
+            {
+                Assert.That(Errors(VoteSchema, "refusal", r!["message"]), Is.Empty, S(r["name"]));
+                Assert.That(HexOf(r["message"]), Is.EqualTo(S(r["messagePackHex"])), S(r["name"]));
+                Assert.That(r["httpStatus"]!.GetValue<int>(), Is.GreaterThanOrEqualTo(400));
+            }
+            Assert.That(vectors.Single(r => S(r!["name"]) == "rate_limited")!["message"]!["retryAfterSeconds"]!.GetValue<int>(), Is.GreaterThanOrEqualTo(1));
+        }
+
+        // ---- fork card (rule source: /opt/commons/handoff/fork-desk-answer-binding-20261110.md) ----
+        private static string Jstr(string s)
+        {
+            var sb = new StringBuilder("\"");
+            foreach (var rune in s.EnumerateRunes())
+            {
+                var o = rune.Value;
+                sb.Append(o switch
+                {
+                    '"' => "\\\"", '\\' => "\\\\", 8 => "\\b", 9 => "\\t", 10 => "\\n", 12 => "\\f", 13 => "\\r",
+                    < 0x20 => "\\u" + o.ToString("x4"),
+                    _ => rune.ToString()
+                });
+            }
+            return sb.Append('"').ToString();
+        }
+
+        // RFC 8785 over the five shown members, every string NFC-normalised first; keys sorted; no numbers in the member set.
+        private static string N(string s) => s.Normalize(NormalizationForm.FormC);
+        private static byte[] Canonical(JsonNode c)
+        {
+            var options = string.Join(",", c["options"]!.AsArray().Select(o => $"{{\"id\":{Jstr(N(S(o!["id"])))},\"text\":{Jstr(N(S(o["text"])))}}}"));
+            var depends = string.Join(",", c["depends"]!.AsArray().Select(d => Jstr(N(S(d)))));
+            return Encoding.UTF8.GetBytes($"{{\"context\":{Jstr(N(S(c["context"])))},\"depends\":[{depends}],\"options\":[{options}],\"recommendation\":{Jstr(N(S(c["recommendation"])))},\"title\":{Jstr(N(S(c["title"])))}}}");
+        }
+        private static string HashOf(JsonNode c) => Sha(Canonical(c));
+
+        private static IEnumerable<string> CardRuleErrors(JsonNode c)
+        {
+            var ids = c["options"]!.AsArray().Select(o => S(o!["id"])).ToList();
+            if (ids.Distinct().Count() != ids.Count) yield return "duplicate option ids";
+            if (!ids.Contains(S(c["recommendation"]))) yield return "recommendation is not an option";
+            if (c["leans"] is not null && !ids.Contains(S(c["leans"]))) yield return "leans is not an option";
+            var deciders = c["deciders"]!.AsArray().Select(S).ToList();
+            if (deciders.Distinct().Count() != deciders.Count) yield return "duplicate deciders";
+            if (c["depends"]!.AsArray().Any(d => Encoding.UTF8.GetByteCount(S(d)) > 1000)) yield return "a depends line is over 1000 UTF-8 bytes";
+            if (S(c["status"]) == "open" && c["ruling"] is not null) yield return "an open card names a ruling";
+            if (c["ruling"] is null && c["ruled_from"]!.AsArray().Count > 0) yield return "ruled_from without a ruling";
+            if (S(c["options_hash"]) != HashOf(c)) yield return "options_hash is not the hash of the shown members";
+        }
+
+        // body_sha256 is Huginn's private "same body" digest, not a wire field: compact JSON, fixed key order, null for missing, the two illegal-form keys only when present.
+        [Test]
+        public void ForkCard_AnAnswerResultWithoutCountedAnswerId_IsRefusedBySchema()
+        {
+            var result = Clone(Fork["scenarios"]!.AsArray().SelectMany(sc => sc!["steps"]!.AsArray()).First(st => st!["response"]?["answer"] is not null)!["response"])!.AsObject();
+            Assert.That(Errors(ForkSchema, "answerResult", result), Is.Empty);
+            result.Remove("counted_answer_id");
+            Assert.That(Errors(ForkSchema, "answerResult", result), Is.Not.Empty);
+        }
+
+        [Test]
+        public void ForkCard_BodyDigest_IsSha256OfTheCompactJsonInTheStatedKeyOrder_AndTheFixedFormsSeparateRetractedTrueFromFalse()
+        {
+            var options = new JsonSerializerOptions { Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
+            var digests = Fork["bodyDigests"]!.AsArray().ToDictionary(d => S(d!["name"]), d => d!);
+            foreach (var d in digests.Values)
+            {
+                var i = d["input"]!;
+                var o = new JsonObject();
+                foreach (var key in new[] { "fork", "options_hash", "answered_at", "choice", "note", "retracts", "illegal_retraction", "retracted" })
+                    if (key is "illegal_retraction" or "retracted" ? i[key] is not null : true) o[key] = Clone(i[key]);
+                var json = o.ToJsonString(options);
+                Assert.That(json, Is.EqualTo(S(d["canonical"])), S(d["name"]));
+                Assert.That(Sha(Encoding.UTF8.GetBytes(json)), Is.EqualTo(S(d["sha256"])), S(d["name"]));
+            }
+            Assert.That(S(digests["plain_answer_choice_A"]["sha256"]), Does.StartWith("8a4d5b2e"));
+            Assert.That(S(digests["legal_retraction"]["sha256"]), Does.StartWith("9f807538"));
+            Assert.That(S(digests["legal_retraction_door_form"]["sha256"]), Does.StartWith("84576840"));
+            Assert.That(digests["legal_retraction_door_form"]["input"]!["retracts"]!.ToString(), Does.EndWith(".n1"), "the door's form: the wire n<seq> converted to the full key");
+            Assert.That(S(digests["illegal_i_retraction_with_an_answer_retracted_true"]["sha256"]), Does.StartWith("935cab1a"));
+            Assert.That(S(digests["illegal_iii_plain_answer_with_a_target_retracted_false"]["sha256"]), Does.StartWith("82b24ccc"));
+            Assert.That(S(digests["illegal_ii_no_answer_no_target_retracted_true"]["sha256"]), Does.StartWith("34ef86ed"));
+            Assert.That(digests.Values.Select(d => S(d["sha256"])).Distinct().Count(), Is.EqualTo(digests.Count), "no two vectors share a digest");
+        }
+
+        [Test]
+        public void ForkCard_OptionsHash_IsSha256OfTheCanonicalJson_ComputedHere_AndEveryShownMemberMovesIt()
+        {
+            foreach (var h in Fork["optionsHash"]!.AsArray())
+            {
+                var bytes = Canonical(h!);
+                Assert.That(Encoding.UTF8.GetString(bytes), Is.EqualTo(S(h["canonical"])), S(h["name"]));
+                Assert.That(Convert.ToHexString(bytes), Is.EqualTo(S(h["canonicalHex"])), S(h["name"]));
+                Assert.That(Sha(bytes), Is.EqualTo(S(h["sha256"])), S(h["name"]));
+            }
+            var byName = Fork["optionsHash"]!.AsArray().ToDictionary(h => S(h!["name"]), h => S(h!["sha256"]));
+            var baseline = byName["heimdall_A_five_members"];
+            Assert.That(byName["hidden_members_do_not_move_it"], Is.EqualTo(baseline));
+            Assert.That(byName["heimdall_E_decomposed_equals_D"], Is.EqualTo(byName["heimdall_D_nfc_escapes_astral"]), "an NFD and an NFC spelling hash alike");
+            foreach (var moved in new[] { "heimdall_B_recommendation_changed", "heimdall_C_option_order_changed", "heimdall_F_option_id_changed", "heimdall_G_depends_emptied",
+                                          "option_text_changed", "title_changed", "context_changed", "depends_order_changed", "depends_order_changed_reversed" })
+                Assert.That(byName[moved], Is.Not.EqualTo(baseline), moved);
+        }
+
+        [Test]
+        public void ForkCard_MutatingAnyShownMember_AnOptionIdIncluded_ChangesTheHash()
+        {
+            var card = Fork["card"]!["valid"]![0]!["message"]!;
+            var baseline = HashOf(card);
+            var mutations = new Action<JsonNode>[]
+            {
+                c => c["title"] = S(c["title"]) + "x", c => c["context"] = S(c["context"]) + "x",
+                c => c["options"]![0]!["id"] = S(c["options"]![0]!["id"]) + "x", c => c["options"]![0]!["text"] = S(c["options"]![0]!["text"]) + "x",
+                c => { var o = c["options"]!.AsArray(); var first = o[0]!; o.RemoveAt(0); o.Add(first); },
+                c => c["recommendation"] = S(c["options"]![0]!["id"]) == S(c["recommendation"]) ? S(c["options"]![1]!["id"]) : S(c["options"]![0]!["id"]),
+                c => c["depends"]!.AsArray().Add("a:b:c"), c => c["depends"]!.AsArray().Clear(),
+            };
+            for (var i = 0; i < mutations.Length; i++)
+            {
+                var copy = Clone(card);
+                mutations[i](copy);
+                Assert.That(HashOf(copy), Is.Not.EqualTo(baseline), $"mutation {i}");
+            }
+            var hidden = Clone(card);
+            hidden["fork_id"] = "other:question:id"; hidden["leans"] = "yes"; hidden["status"] = "closed"; hidden["ruled_from"] = new JsonArray("n1");
+            Assert.That(HashOf(hidden), Is.EqualTo(baseline), "fork_id and the unshown members stay outside the hash");
+        }
+
+        [Test]
+        public void ForkCard_DocumentsValidateAndEncodeToTheVectorBytes()
+        {
+            foreach (var v in Fork["card"]!["valid"]!.AsArray())
+            {
+                Assert.That(Errors(ForkSchema, "card", v!["message"]), Is.Empty, S(v["name"]));
+                Assert.That(CardRuleErrors(v["message"]!), Is.Empty, S(v["name"]));
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+            }
+            foreach (var (section, def) in new[] { ("request", "answerRequest"), ("deskAnswer", "deskAnswer") })
+                foreach (var v in Fork[section]!["valid"]!.AsArray())
+                {
+                    Assert.That(Errors(ForkSchema, def, v!["message"]), Is.Empty, S(v["name"]));
+                    Assert.That(NoteRuleErrors(def, v["message"]), Is.Empty, S(v["name"]));
+                    Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                    var decoded = JsonNode.Parse(MessagePackSerializer.ConvertToJson(Convert.FromHexString(S(v["messagePackHex"]))))!;
+                    Assert.That(JsonNode.DeepEquals(decoded, v["message"]), Is.True, S(v["name"]));
+                }
+            var schema = JsonNode.Parse(File.ReadAllText(Path.Combine(RepoRoot(), "contracts", "cultnet", ForkSchema)))!;
+            IEnumerable<string> codesOfRefusal() => schema["$defs"]!["refusal"]!["properties"]!["code"]!["enum"]!.AsArray().Select(S);
+            IEnumerable<string> Codes(string def) => schema["$defs"]![def]!["properties"]!["code"]!["enum"]!.AsArray().Select(S).OrderBy(x => x, StringComparer.Ordinal);
+            Assert.That(Fork["results"]!.AsArray().Select(r => S(r!["name"])).OrderBy(x => x, StringComparer.Ordinal), Is.EqualTo(Codes("deskAnswerRefused")));
+            foreach (var v in Fork["results"]!.AsArray())
+            {
+                Assert.That(Errors(ForkSchema, "answerResult", v!["message"]), Is.Empty, S(v["name"]));
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                Assert.That(v["message"]!["card"] is not null, Is.EqualTo(S(v["name"]) == "stale_fork"), "only a stale refusal shows the new fork");
+            }
+            Assert.That(Fork["doorRefusals"]!.AsArray().Select(r => S(r!["name"])).OrderBy(x => x, StringComparer.Ordinal), Is.EqualTo(Codes("refusal")));
+            foreach (var v in Fork["unavailable"]!.AsArray())
+            {
+                Assert.That(Errors(ForkSchema, "unavailable", v!["message"]), Is.Empty, S(v["name"]));
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                Assert.That(v["httpStatus"]!.GetValue<int>(), Is.EqualTo(503));
+                Assert.That(codesOfRefusal(), Does.Not.Contain("unavailable"), "unavailable is kept apart from the refusal set");
+            }
+            foreach (var v in Fork["doorRefusals"]!.AsArray())
+            {
+                Assert.That(Errors(ForkSchema, "refusal", v!["message"]), Is.Empty, S(v["name"]));
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+            }
+            Assert.That(Fork["doorRefusals"]!.AsArray().Single(r => S(r!["name"]) == "fork_too_large")!["httpStatus"]!.GetValue<int>(), Is.EqualTo(422));
+        }
+
+        [Test]
+        public void ForkCard_EveryNegative_IsRefusedBySchemaOrAStatedRule()
+        {
+            foreach (var v in Fork["card"]!["invalid"]!.AsArray())
+                Assert.That(Errors(ForkSchema, "card", v!["message"]).Count > 0 || CardRuleErrors(v["message"]!).Any(), Is.True, $"{S(v["name"])}: {S(v["why"])}");
+            foreach (var (section, def) in new[] { ("request", "answerRequest"), ("deskAnswer", "deskAnswer") })
+                foreach (var v in Fork[section]!["invalid"]!.AsArray())
+                {
+                    Assert.That(Errors(ForkSchema, def, v!["message"]).Count > 0 || NoteRuleErrors(def, v["message"]).Any(), Is.True, $"{S(v["name"])}: {S(v["why"])}");
+                    Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                }
+        }
+
+        // Rules a JSON Schema cannot say: a note is at most 4000 UTF-8 bytes (maxLength counts code points and is only the looser bound).
+        private static IEnumerable<string> NoteRuleErrors(string def, JsonNode? message)
+        {
+            var note = def switch { "answerRequest" => message?["answer"]?["note"], "deskAnswer" => message?["note"], _ => null };
+            if (note is not null && Encoding.UTF8.GetByteCount(S(note)) > 4000) yield return "note is over 4000 UTF-8 bytes";
+        }
+
+        private static readonly Dictionary<string, string> Tails = new()
+        {
+            ["unauthenticated"] = "a verified session is required",
+            ["body_forbidden_field"] = "answerer and authority are set by the receiver",
+            ["body_unknown_field"] = "the body is a closed shape",
+            ["body_invalid"] = "the body does not satisfy gamecult.fork.answer_request.v0",
+            ["fork_unknown"] = "no such fork",
+            ["forbidden"] = "only Active members may use the desk",
+            ["request_id_conflict"] = "this request_id was used for a different body",
+        };
+        private static readonly string[] RequestKeys = { "schemaVersion", "fork_id", "options_hash", "answer", "retracted", "retracts", "answered_at", "request_id" };
+
+        private static bool HasKey(JsonNode? n, params string[] names) => n switch
+        {
+            JsonObject o => o.Any(kv => names.Contains(kv.Key) || HasKey(kv.Value, names)),
+            JsonArray a => a.Any(x => HasKey(x, names)),
+            _ => false
+        };
+
+        // The reference judge: Huginn's half behind the second door as fork-card.md states it. Server-set fields come from the step.
+        private static (List<JsonNode?> Responses, JsonNode Record) Judge(JsonNode startCard, JsonArray steps)
+        {
+            var card = startCard;
+            var answers = new JsonArray();
+            var responses = new List<JsonNode?>();
+            var seen = new Dictionary<string, (JsonNode Body, JsonNode Response)>();   // (answerer, request_id) -> the first stored outcome
+            string? Counted()
+            {
+                var hash = HashOf(card);
+                foreach (var a in answers)
+                {
+                    if (S(a!["outcome"]) is not ("Counted" or "Revision") || S(a["options_hash"]) != hash) continue;
+                    if (answers.Any(r => S(r!["outcome"]) == "Retraction" && S(r["retracts"]) == S(a["answer_id"]))) continue;
+                    return S(a["answer_id"]);
+                }
+                return null;
+            }
+            foreach (var step in steps)
+            {
+                var kind = S(step!["kind"]);
+                if (kind == "matrix_event") { responses.Add(null); continue; }   // rule 9: Matrix never changes a decision
+                if (kind == "card") { card = step["card"]!; responses.Add(null); continue; }
+                var s = step["server"]!;
+                var b = step["body"]!.AsObject();
+                JsonNode Door(string code) => new JsonObject { ["schemaVersion"] = "gamecult.fork.refusal.v0", ["code"] = code, ["error"] = $"{code}: {Tails[code]}" };
+                JsonNode Store(string outcome, string? link, string? code)
+                {
+                    var a = b["answer"] as JsonObject;
+                    var doc = new JsonObject
+                    {
+                        ["schemaVersion"] = "gamecult.desk_answer.v0", ["answer_id"] = S(s["answer_id"]), ["fork_id"] = Clone(b["fork_id"]), ["outcome"] = outcome,
+                        ["of"] = outcome == "Revision" ? link : null, ["retracts"] = outcome == "Retraction" ? link : outcome == "Refused" ? Clone(b["retracts"]) : null, ["code"] = outcome == "Refused" ? code : null,
+                        ["options_hash"] = Clone(b["options_hash"]), ["choice"] = Clone(a?["choice"]), ["note"] = Clone(a?["note"]), ["answered_at"] = Clone(b["answered_at"]),
+                        ["received_at"] = Clone(s["received_at"]),
+                        ["claim_in_future"] = (DateTimeOffset.Parse(S(b["answered_at"])) - DateTimeOffset.Parse(S(s["received_at"]))).TotalSeconds > 300,
+                        ["answerer"] = Clone(s["answerer"]), ["authority"] = Clone(s["authority"]), ["request_id"] = Clone(b["request_id"])
+                    };
+                    answers.Add(Clone(doc));
+                    var stored = new JsonObject { ["schemaVersion"] = "gamecult.fork.answer_result.v0", ["answer"] = doc, ["card"] = code == "stale_fork" ? Clone(card) : null, ["counted_answer_id"] = Counted() };
+                    seen[S(s["answerer"]) + "|" + S(b["request_id"])] = (Clone(b)!, Clone(stored)!);
+                    return stored;
+                }
+                JsonNode Refuse(string code) => Store("Refused", null, code);
+                var deciders = card["deciders"]!.AsArray().Select(S).ToList();
+                var retracted = b["retracted"] is JsonValue rv && rv.TryGetValue<bool>(out var rb) && rb;
+                var down = s["door_down"] is not null;          // the second door failed to answer; "stored" says whether Huginn had the request by then
+                var reached = s["stored"] is not null;
+                JsonNode Unavailable() => new JsonObject { ["schemaVersion"] = "gamecult.fork.unavailable.v0", ["code"] = "unavailable", ["error"] = "unavailable: the outcome is not confirmed, try again with the same request_id", ["retryAfterSeconds"] = Clone(s["retry_after_seconds"]) };
+                // a stored desk_answer has no card, so a replayed stale_fork carries the CURRENT card (fork-card.md, request_id)
+                JsonNode Replay(JsonNode stored) { var copy = Clone(stored)!; if (S(copy["answer"]!["code"] ?? "") == "stale_fork") copy["card"] = Clone(card); copy["counted_answer_id"] = Counted(); return copy; }
+                JsonNode response;
+                if (s["answerer"] is null) response = Door("unauthenticated");
+                else if (s["active"] is JsonValue activeValue && !activeValue.GetValue<bool>()) response = Door("forbidden");
+                else if (HasKey(b, "answerer", "authority")) response = Door("body_forbidden_field");
+                else if (b.Any(kv => !RequestKeys.Contains(kv.Key)) || (b["answer"] is JsonObject ao && ao.Any(kv => kv.Key is not ("choice" or "note")))) response = Door("body_unknown_field");
+                else if (Errors(ForkSchema, "answerRequest", b).Count > 0 || NoteRuleErrors("answerRequest", b).Any() || (!retracted && b["answer"] is null)) response = Door("body_invalid");
+                else if (down && !reached) response = Unavailable();
+                else if (seen.TryGetValue(S(s["answerer"]) + "|" + S(b["request_id"]), out var prior)) response = JsonNode.DeepEquals(prior.Body, b) ? Replay(prior.Response) : Door("request_id_conflict");
+                else if (S(b["fork_id"]) != S(card["fork_id"])) response = Door("fork_unknown");
+                else if (S(b["options_hash"]) != HashOf(card)) response = Refuse("stale_fork");
+                else if (!deciders.Contains(S(s["answerer"]))) response = Refuse("not_a_decider");
+                else if (S(card["status"]) == "closed") response = Refuse("fork_closed");
+                else if (retracted || b["retracts"] is not null)
+                {
+                    var target = answers.FirstOrDefault(a => a is not null && b["retracts"] is not null && S(a["answer_id"]) == S(b["retracts"])
+                        && S(a["outcome"]) is "Counted" or "Revision" && S(a["options_hash"]) == S(b["options_hash"]));
+                    if (!retracted || b["answer"] is not null || b["retracts"] is null || target is null) response = Refuse("bad_retraction");
+                    else if (answers.Any(a => S(a!["outcome"]) == "Retraction" && S(a["retracts"]) == S(target["answer_id"]))) response = Refuse("already_retracted");
+                    else response = Store("Retraction", S(target["answer_id"]), null);
+                }
+                else if (b["answer"]!["choice"] is not null && !card["options"]!.AsArray().Any(o => S(o!["id"]) == S(b["answer"]!["choice"]))) response = Refuse("choice_invalid");
+                else
+                {
+                    var first = Counted();
+                    response = first is null ? Store("Counted", null, null) : Store("Revision", first, null);
+                }
+                responses.Add(down && reached ? Unavailable() : response);
+            }
+            var record = new JsonObject
+            {
+                ["schemaVersion"] = "gamecult.fork.record.v0", ["fork_id"] = Clone(card["fork_id"]), ["options_hash"] = HashOf(card), ["counted_answer_id"] = Counted(), ["answers"] = answers
+            };
+            return (responses, record);
+        }
+
+        [Test]
+        public void ForkCard_ARequestIdBelongsToItsAccount_AnotherAccountsIdenticalBodyGetsItsOwnAnswerNeverTheFirstOutcome()
+        {
+            var crossed = 0;
+            foreach (var sc in Fork["scenarios"]!.AsArray())
+            {
+                var first = new Dictionary<string, (string Answerer, JsonNode Result)>();   // request_id -> the account that first got a stored result and what it got
+                foreach (var step in sc!["steps"]!.AsArray())
+                {
+                    if (S(step!["kind"]) != "answer" || step["response"]?["answer"] is null) continue;
+                    var who = S(step["server"]!["answerer"]);
+                    var result = step["response"]!;
+                    Assert.That(S(result["answer"]!["answerer"]), Is.EqualTo(who), $"{S(sc["name"])}: a result is stamped with the account that asked");
+                    var rid = S(step["body"]!["request_id"]);
+                    if (!first.TryGetValue(rid, out var prior)) { first[rid] = (who, result); continue; }
+                    if (prior.Answerer == who) continue;
+                    crossed++;
+                    Assert.That(S(result["answer"]!["answer_id"]), Is.Not.EqualTo(S(prior.Result["answer"]!["answer_id"])), $"{S(sc["name"])}: its own answer id");
+                    Assert.That(JsonNode.DeepEquals(result, prior.Result), Is.False, $"{S(sc["name"])}: the first account's outcome is never returned");
+                }
+            }
+            Assert.That(crossed, Is.GreaterThanOrEqualTo(3), "the vectors carry the cross-account cases");
+        }
+
+        [Test]
+        public void ForkCard_EveryScenario_ReplaysToTheVectorsResponsesAndRecord_BytesIncluded()
+        {
+            var seen = new HashSet<string>();
+            var doorRefusals = 0;
+            var door = new HashSet<string> { "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "forbidden", "request_id_conflict" };
+            foreach (var sc in Fork["scenarios"]!.AsArray())
+            {
+                var name = S(sc!["name"]);
+                Assert.That(HashOf(sc["card"]!), Is.EqualTo(S(sc["optionsHash"])), name);
+                Assert.That(CardRuleErrors(sc["card"]!), Is.Empty, name);
+                var steps = sc["steps"]!.AsArray();
+                var (responses, record) = Judge(sc["card"]!, steps);
+                Assert.That(responses.Count, Is.EqualTo(steps.Count), name);
+                for (var i = 0; i < steps.Count; i++)
+                    Assert.That(JsonNode.DeepEquals(responses[i], steps[i]!["response"]), Is.True, $"{name} step {i}: {responses[i]?.ToJsonString()}");
+                Assert.That(JsonNode.DeepEquals(record, sc["record"]), Is.True, $"{name}: {record.ToJsonString()}");
+                Assert.That(Errors(ForkSchema, "record", record), Is.Empty, name);
+                Assert.That(HexOf(record), Is.EqualTo(S(sc["recordHex"])), name);
+                foreach (var step in steps)
+                {
+                    var r = step!["response"];
+                    if (r is null) continue;
+                    Assert.That(Errors(ForkSchema, "answerResult", r).Count == 0 || Errors(ForkSchema, "refusal", r).Count == 0 || Errors(ForkSchema, "unavailable", r).Count == 0, Is.True, name);
+                    if (r["code"] is not null)
+                    {
+                        seen.Add(S(r["code"]));
+                        // unavailable promises nothing: the outcome is not confirmed, so the answer is stored exactly when Huginn had it
+                        if (S(r["code"]) == "unavailable")
+                            Assert.That(sc["record"]!["answers"]!.AsArray().Any(a => S(a!["answer_id"]) == S(step["server"]!["answer_id"])), Is.EqualTo(step["server"]!["stored"] is not null), $"{name} unavailable");
+                        if (door.Contains(S(r["code"])))
+                        {
+                            doorRefusals++;
+                            Assert.That(sc["record"]!["answers"]!.AsArray().Any(a => S(a!["answer_id"]) == S(step["server"]!["answer_id"])), Is.False, $"{name} stored a door refusal");
+                        }
+                    }
+                    else seen.Add(S(r["answer"]!["code"] ?? r["answer"]!["outcome"]));
+                }
+                foreach (var a in sc["record"]!["answers"]!.AsArray()) seen.Add(S(a!["outcome"]));
+            }
+            Assert.That(doorRefusals, Is.GreaterThanOrEqualTo(8));
+            foreach (var want in new[] { "Counted", "Revision", "Retraction", "Refused", "unauthenticated", "body_forbidden_field", "body_unknown_field", "body_invalid", "fork_unknown", "unavailable", "forbidden", "request_id_conflict", "stale_fork",
+                                         "not_a_decider", "fork_closed", "choice_invalid", "bad_retraction", "already_retracted" })
+                Assert.That(seen, Does.Contain(want));
+        }
+
+        // A ruling may carry authority Operator only if it cites a Counted desk_answer stamped Operator (binding file 1.3d).
+        private static bool AdmitRuling(JsonNode cite, JsonArray answers)
+        {
+            if (S(cite["authority"]) != "Operator") return true;
+            var cited = answers.FirstOrDefault(a => cite["answer_id"] is not null && S(a!["answer_id"]) == S(cite["answer_id"]));
+            return cited is not null && S(cited["outcome"]) == "Counted" && S(cited["authority"]) == "Operator";
+        }
+
+        [Test]
+        public void ForkCard_OperatorAuthority_NeedsACitedCountedAnswerRecord()
+        {
+            foreach (var c in Fork["rulingCites"]!.AsArray())
+            {
+                Assert.That(Errors(ForkSchema, "rulingCite", c!["message"]), Is.Empty, S(c["name"]));
+                Assert.That(HexOf(c["message"]), Is.EqualTo(S(c["messagePackHex"])), S(c["name"]));
+                Assert.That(AdmitRuling(c["message"]!, c["answers"]!.AsArray()), Is.EqualTo(c["admit"]!.GetValue<bool>()), S(c["name"]));
+            }
+        }
+
+        // ---- transport: list, read, auth (fork-card.md "Transport") ----
+        private static IEnumerable<string> EntryRuleErrors(JsonNode e)
+        {
+            var card = e["card"]!; var record = e["record"]!;
+            foreach (var error in CardRuleErrors(card)) yield return error;
+            if (S(record["fork_id"]) != S(card["fork_id"])) yield return "record of another fork";
+            if (S(record["options_hash"]) != S(card["options_hash"])) yield return "record under another hash";
+            var answers = record["answers"]!.AsArray();
+            var counted = answers.Where(a => (S(a!["outcome"]) is "Counted" or "Revision") && S(a["options_hash"]) == S(card["options_hash"])
+                && !answers.Any(r => S(r!["outcome"]) == "Retraction" && S(r["retracts"]) == S(a["answer_id"]))).Select(a => S(a!["answer_id"])).FirstOrDefault();
+            if ((record["counted_answer_id"] is null ? null : S(record["counted_answer_id"])) != counted) yield return "counted_answer_id is not derived";
+        }
+
+        // Order is a unique rank per Mind: the refusal names both fork ids, the first holder and the second.
+        private static List<string> OrderErrors(IEnumerable<JsonNode?> cards)
+        {
+            var holder = new Dictionary<long, string>();
+            var errors = new List<string>();
+            foreach (var c in cards)
+            {
+                var order = c!["order"]!.GetValue<long>();
+                if (holder.TryGetValue(order, out var first)) errors.Add($"order {order} is shared by {first} and {S(c["fork_id"])}");
+                else holder[order] = S(c["fork_id"]);
+            }
+            return errors;
+        }
+
+        // The reference list judge: newest first by card order, status filter, cursor c<N> = cards below order N, a page of limit, counts over the whole set.
+        private static JsonNode JudgeList(JsonArray entries, long ordinal, JsonNode request)
+        {
+            long Order(JsonNode? e) => e!["card"]!["order"]!.GetValue<long>();
+            var rows = entries.OrderByDescending(Order).ToList();
+            var want = rows.Where(e => request["status"] is null || (S(e!["card"]!["status"]) == "open") == (S(request["status"]) == "open")).ToList();
+            if (request["cursor"] is not null) { var below = long.Parse(S(request["cursor"])[1..]); want = want.Where(e => Order(e) < below).ToList(); }
+            var page = want.Take(request["limit"]!.GetValue<int>()).ToList();
+            var more = want.Count > page.Count && page.Count > 0;
+            return new JsonObject
+            {
+                ["schemaVersion"] = "gamecult.fork.list.v0", ["mind"] = Clone(request["mind"]), ["stamp"] = $"s{ordinal}",
+                ["open_count"] = rows.Count(e => S(e!["card"]!["status"]) == "open"), ["recorded_count"] = rows.Count(e => S(e!["card"]!["status"]) == "closed"),
+                ["forks"] = new JsonArray(page.Select(Clone).ToArray()), ["next_cursor"] = more ? JsonValue.Create($"c{Order(page[^1])}") : null
+            };
+        }
+
+        // Bearer, audience, scope, in that order: a votes.* token fails at the audience and a desk token without the route's scope fails at the scope.
+        private static string AuthJudge(string route, JsonNode? token, bool huginnDown)
+        {
+            if (token is null || S(token["audience"]) != "bifrost-desk") return "unauthenticated";
+            var need = route == "answer" ? "desk.answer" : "desk.read";
+            if (!token["scopes"]!.AsArray().Any(x => S(x) == need)) return "insufficient_scope";
+            if (!token["active"]!.GetValue<bool>()) return "forbidden";
+            return huginnDown ? "unavailable" : "ok";
+        }
+
+        private static string PercentDecode(string s)
+        {
+            var bytes = new List<byte>();
+            for (var i = 0; i < s.Length;)
+            {
+                if (s[i] == '%' && i + 2 < s.Length && Uri.IsHexDigit(s[i + 1]) && Uri.IsHexDigit(s[i + 2])) { bytes.Add(Convert.ToByte(s.Substring(i + 1, 2), 16)); i += 3; continue; }
+                var rune = System.Text.Rune.GetRuneAt(s, i);
+                bytes.AddRange(Encoding.UTF8.GetBytes(rune.ToString())); i += rune.Utf16SequenceLength;
+            }
+            return new UTF8Encoding(false, true).GetString(bytes.ToArray());   // throws DecoderFallbackException (an ArgumentException) on invalid UTF-8
+        }
+
+        // The {mind} segment is decoded once and compared, ordinally, only with the configured list; nothing is opened from it (fork-card.md, "The {mind} segment").
+        private static (string Code, string? Opened, string? StoredIn) MindRoute(JsonNode config, string route, string segment, string? fork, JsonNode? token)
+        {
+            var auth = AuthJudge(route, token, false);
+            if (auth != "ok") return (auth, null, null);
+            string mind;
+            try { mind = PercentDecode(segment); } catch (ArgumentException) { return ("fork_unknown", null, null); }   // bytes that are not UTF-8 are a miss
+            var minds = config["minds"]!.AsObject();
+            if (!minds.TryGetPropertyValue(mind, out var socket)) return ("fork_unknown", null, null);
+            if (route != "list" && !config["forks"]![mind]!.AsArray().Any(f => S(f) == fork)) return ("fork_unknown", S(socket), null);
+            return ("ok", S(socket), route == "answer" ? mind : null);
+        }
+
+        [Test]
+        public void ForkTransport_MindSegment_IsOnlyComparedWithTheConfiguredList_AnUnknownMindIsTheUnknownForkRefusal()
+        {
+            var config = Fork["transport"]!["mindRoutes"]!;
+            var refusals = Fork["doorRefusals"]!.AsArray().ToDictionary(r => S(r!["name"]), r => r!);
+            var byName = new Dictionary<string, (string Code, string? Opened, string? StoredIn)>();
+            foreach (var c in config["cases"]!.AsArray())
+            {
+                var got = MindRoute(config, S(c!["route"]), S(c["mind"]), c["fork_id"] is null ? null : S(c["fork_id"]), c["token"]);
+                byName[S(c["name"])] = got;
+                Assert.That(got.Code, Is.EqualTo(S(c["expect"])), S(c["name"]));
+                Assert.That(got.Opened, Is.EqualTo(c["opened"] is null ? null : S(c["opened"])), $"{S(c["name"])}: the socket opened");
+                Assert.That(got.StoredIn, Is.EqualTo(c["stored_in"] is null ? null : S(c["stored_in"])), $"{S(c["name"])}: where an answer was stored");
+                Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(got.Code == "ok" ? 200 : refusals[got.Code]["httpStatus"]!.GetValue<int>()), S(c["name"]));
+                if (got.Code == "fork_unknown")
+                {
+                    var error = S(refusals["fork_unknown"]["message"]!["error"]);
+                    Assert.That(error.Contains(S(c["mind"])), Is.False, $"{S(c["name"])}: the refusal does not name the Mind");
+                    Assert.That(c["fork_id"] is not null && error.Contains(S(c["fork_id"])), Is.False, $"{S(c["name"])}: the refusal does not name the fork");
+                }
+            }
+            foreach (var pair in config["sameResponse"]!.AsArray())
+            {
+                var a = byName[S(pair![0])]; var b = byName[S(pair[1])];
+                Assert.That(a.Code, Is.EqualTo(b.Code));
+                string Built(string code) => HexOf(new JsonObject { ["schemaVersion"] = "gamecult.fork.refusal.v0", ["code"] = code, ["error"] = $"{code}: {Tails[code]}" });
+                Assert.That(Built(a.Code), Is.EqualTo(Built(b.Code)).And.EqualTo(S(refusals[a.Code]["messagePackHex"])), $"{S(pair[0])} and {S(pair[1])} answer with the same bytes, built from the spec's rule");
+            }
+            Assert.That(byName.Values.Count(v => v.Code == "fork_unknown" && v.Opened is null), Is.GreaterThanOrEqualTo(39), "every bad segment opens nothing");
+            Assert.That(byName.Values.Where(v => v.StoredIn is not null).Select(v => v.StoredIn).Distinct().Count(), Is.EqualTo(2), "an answer is stored in the route's Mind only, and both Minds take one");
+        }
+
+        [Test]
+        public void ForkTransport_RequestsAndEntriesValidateEncodeToTheVectorBytes_AndEveryNegativeIsRefused()
+        {
+            var t = Fork["transport"]!;
+            foreach (var (section, def) in new[] { ("listRequest", "listRequest"), ("readRequest", "readRequest"), ("entry", "entry") })
+            {
+                foreach (var v in t[section]!["valid"]!.AsArray())
+                {
+                    Assert.That(Errors(ForkSchema, def, v!["message"]), Is.Empty, S(v["name"]));
+                    if (def == "entry") Assert.That(EntryRuleErrors(v["message"]!), Is.Empty, S(v["name"]));
+                    Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                }
+                foreach (var v in t[section]!["invalid"]!.AsArray())
+                {
+                    Assert.That(Errors(ForkSchema, def, v!["message"]).Count > 0 || (def == "entry" && EntryRuleErrors(v["message"]!).Any()), Is.True, $"{S(v["name"])}: {S(v["why"])}");
+                    Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+                }
+            }
+            foreach (var v in t["listInvalid"]!.AsArray())
+            {
+                var shared = OrderErrors(v!["message"]!["forks"]!.AsArray().Select(f => f!["card"]));
+                Assert.That(Errors(ForkSchema, "list", v["message"]).Count > 0 || shared.Count > 0, Is.True, $"{S(v["name"])}: {S(v["why"])}");
+                if (v["refusal"] is not null) Assert.That(shared, Is.EqualTo(new[] { S(v["refusal"]) }), S(v["name"]));
+                Assert.That(HexOf(v["message"]), Is.EqualTo(S(v["messagePackHex"])), S(v["name"]));
+            }
+        }
+
+        [Test]
+        public void ForkTransport_EveryListRequest_ReplaysToTheVectorsResponse_NewestFirst_PagedByTheCursor()
+        {
+            foreach (var sc in Fork["transport"]!["listScenarios"]!.AsArray())
+            {
+                var name = S(sc!["name"]);
+                var entries = sc["entries"]!.AsArray();
+                foreach (var e in entries) Assert.That(EntryRuleErrors(e!), Is.Empty, name);
+                Assert.That(OrderErrors(entries.Select(e => e!["card"])), Is.Empty, name);
+                JsonNode? previous = null;
+                foreach (var step in sc["steps"]!.AsArray())
+                {
+                    var response = JudgeList(entries, sc["ordinal"]!.GetValue<long>(), step!["request"]!);
+                    Assert.That(JsonNode.DeepEquals(response, step["response"]), Is.True, $"{name}: {response.ToJsonString()}");
+                    Assert.That(Errors(ForkSchema, "list", response), Is.Empty, name);
+                    Assert.That(HexOf(response), Is.EqualTo(S(step["responseHex"])), name);
+                    var orders = response["forks"]!.AsArray().Select(f => f!["card"]!["order"]!.GetValue<long>()).ToList();
+                    Assert.That(orders, Is.Ordered.Descending, name);
+                    if (previous is not null) Assert.That(S(step["request"]!["cursor"]), Is.EqualTo(S(previous["next_cursor"])), $"{name}: the second request follows the first page's cursor");
+                    previous = response;
+                }
+            }
+        }
+
+        [Test]
+        public void ForkTransport_OrderZero_IsLegal_NoCursorNamesIt_AndThePageEndingAtOrderOneHandsOnToIt()
+        {
+            var sc = Fork["transport"]!["listScenarios"]!.AsArray().Single(x => S(x!["name"]) == "order_zero_is_legal_but_no_cursor_names_it")!;
+            var steps = sc["steps"]!.AsArray();
+            Assert.That(S(steps[0]!["response"]!["next_cursor"]), Is.EqualTo("c1"));
+            Assert.That(steps[1]!["response"]!["next_cursor"], Is.Null);
+            Assert.That(steps[1]!["response"]!["forks"]!.AsArray().Select(f => f!["card"]!["order"]!.GetValue<long>()), Is.EqualTo(new[] { 0L }));
+            Assert.That(Errors(ForkSchema, "cursor", JsonValue.Create("c0")), Is.Not.Empty);
+        }
+
+        [Test]
+        public void ForkTransport_AShortPage_AndForkTooLarge422_ContinuedBelowItsOrder()
+        {
+            var sc = Fork["transport"]!["listShortPages"]!.AsArray();
+            Assert.That(sc.Select(x => S(x!["name"])), Is.EqualTo(new[] { "a_short_page_resumes_below_its_last_entry", "a_first_entry_past_the_budget_is_fork_too_large_and_the_client_continues_below_its_order", "fork_too_large_on_order_zero_leaves_nothing_below" }));
+            var schema = JsonNode.Parse(File.ReadAllText(Path.Combine(RepoRoot(), "contracts", "cultnet", ForkSchema)))!;
+            Assert.That(schema["$defs"]!["refusal"]!["properties"]!["code"]!["enum"]!.AsArray().Select(S), Does.Contain("fork_too_large"));
+            var covered = new List<long>();
+            foreach (var s in sc)
+            {
+                var entries = s!["entries"]!.AsArray(); var steps = s["steps"]!.AsArray(); string? last = null; var follow = false;
+                for (var i = 0; i < steps.Count; i++)
+                {
+                    var step = steps[i]!; var name = S(s["name"]);
+                    if (follow) Assert.That(step["request"]!["cursor"] is null ? null : S(step["request"]!["cursor"]), Is.EqualTo(last), name);
+                    var full = JudgeList(entries, s["ordinal"]!.GetValue<long>(), step["request"]!);
+                    var fullForks = full["forks"]!.AsArray();
+                    if (step["response"] is not null)
+                    {
+                        var r = step["response"]!; var forks = r["forks"]!.AsArray(); var n = forks.Count;
+                        Assert.That(Errors(ForkSchema, "list", r), Is.Empty, name);
+                        Assert.That(HexOf(r), Is.EqualTo(S(step["responseHex"])), name);
+                        Assert.That(n, Is.GreaterThanOrEqualTo(1), name);
+                        for (var k = 0; k < n; k++) Assert.That(JsonNode.DeepEquals(forks[k], fullForks[k]), Is.True, $"{name}: a prefix of the unbudgeted page");
+                        var o = forks[n - 1]!["card"]!["order"]!.GetValue<long>();
+                        if (full["next_cursor"] is not null || n < fullForks.Count) Assert.That(S(r["next_cursor"]), Is.EqualTo($"c{o}"), name); else Assert.That(r["next_cursor"], Is.Null, name);
+                        Assert.That(S(r["stamp"]), Is.EqualTo(S(full["stamp"]))); Assert.That(r["open_count"]!.GetValue<int>(), Is.EqualTo(full["open_count"]!.GetValue<int>())); Assert.That(r["recorded_count"]!.GetValue<int>(), Is.EqualTo(full["recorded_count"]!.GetValue<int>()));
+                        covered.AddRange(forks.Select(f => f!["card"]!["order"]!.GetValue<long>()));
+                        last = r["next_cursor"] is null ? null : S(r["next_cursor"]); follow = true;
+                    }
+                    else
+                    {
+                        var r = step["refusal"]!; var first = fullForks[0]!["card"]!;
+                        Assert.That(Errors(ForkSchema, "refusal", r), Is.Empty, name);
+                        Assert.That(HexOf(r), Is.EqualTo(S(step["refusalHex"])), name);
+                        Assert.That(S(r["code"]), Is.EqualTo("fork_too_large")); Assert.That(step["httpStatus"]!.GetValue<int>(), Is.EqualTo(422));
+                        Assert.That(S(step["fork_id"]), Is.EqualTo(S(first["fork_id"]))); Assert.That(step["order"]!.GetValue<long>(), Is.EqualTo(first["order"]!.GetValue<long>()));
+                        Assert.That(S(r["error"]), Does.Contain(S(first["fork_id"])), name);
+                        Assert.That(System.Text.RegularExpressions.Regex.IsMatch(S(r["error"]).Replace(S(first["fork_id"]), ""), $@"\b{first["order"]!.GetValue<long>()}\b"), Is.True, $"{name}: the text names the order");
+                        Assert.That(step["request"]!["limit"]!.GetValue<int>(), Is.GreaterThanOrEqualTo(1));
+                        var order = first["order"]!.GetValue<long>();
+                        if (order >= 1) { Assert.That(i + 1, Is.LessThan(steps.Count), name); last = $"c{order}"; follow = true; Assert.That(Errors(ForkSchema, "cursor", JsonValue.Create(last)), Is.Empty); }
+                        else { Assert.That(i, Is.EqualTo(steps.Count - 1), $"{name}: order 0 is the end"); follow = false; }
+                    }
+                }
+            }
+            Assert.That(covered, Is.EqualTo(new long[] { 3, 2, 1, 0, 2, 1, 0, 1 }));
+            Assert.That(sc[0]!["steps"]!.AsArray().Select(x => x!["response"]!["forks"]!.AsArray().Count), Is.EqualTo(new[] { 2, 2 }));
+        }
+
+        [Test]
+        public void ForkTransport_AReadWhoseEntryIsPastTheCap_IsForkTooLarge422_NamedByForkIdAlone()
+        {
+            var doorStatus = Fork["doorRefusals"]!.AsArray().Single(r => S(r!["name"]) == "fork_too_large")!["httpStatus"]!.GetValue<int>();
+            var cases = Fork["transport"]!["readTooLarge"]!.AsArray();
+            Assert.That(cases.Count, Is.EqualTo(1));
+            foreach (var c in cases)
+            {
+                var held = c!["entries"]!.AsArray().Single(e => S(e!["card"]!["fork_id"]) == S(c["request"]!["fork_id"]))!;
+                Assert.That(Errors(ForkSchema, "readRequest", c["request"]), Is.Empty, S(c["name"]));
+                Assert.That(Errors(ForkSchema, "refusal", c["refusal"]), Is.Empty, S(c["name"]));
+                Assert.That(S(c["refusal"]!["code"]), Is.EqualTo("fork_too_large"));
+                Assert.That(S(c["refusal"]!["error"]), Does.Contain(S(held["card"]!["fork_id"])), "the text names the fork id");
+                Assert.That(HexOf(c["refusal"]), Is.EqualTo(S(c["refusalHex"])), S(c["name"]));
+                Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(422)); Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(doorStatus));
+            }
+        }
+
+        [Test]
+        public void ForkTransport_AStaleAnswerWhoseCardRereadIsPastTheCap_IsTheReadFormForkTooLarge422_OverAStoredStaleRefusal()
+        {
+            var cases = Fork["transport"]!["answerTooLarge"]!.AsArray();
+            Assert.That(cases.Count, Is.EqualTo(1));
+            var read = Fork["transport"]!["readTooLarge"]![0]!;
+            foreach (var c in cases)
+            {
+                var held = c!["entries"]!.AsArray().Single(e => S(e!["card"]!["fork_id"]) == S(c["request"]!["fork_id"]))!;
+                Assert.That(Errors(ForkSchema, "answerRequest", c["request"]), Is.Empty, S(c["name"]));
+                Assert.That(S(c["request"]!["options_hash"]), Is.Not.EqualTo(S(held["card"]!["options_hash"])), "the card moved: the answer is stale");
+                Assert.That(Errors(ForkSchema, "refusal", c["refusal"]), Is.Empty, S(c["name"]));
+                Assert.That(S(c["refusal"]!["code"]), Is.EqualTo("fork_too_large"));
+                Assert.That(S(c["refusal"]!["error"]), Does.Contain(S(held["card"]!["fork_id"])), "the text names the fork id");
+                Assert.That(HexOf(c["refusal"]), Is.EqualTo(S(c["refusalHex"])), S(c["name"]));
+                Assert.That(S(c["refusal"]!["code"]), Is.EqualTo(S(read["refusal"]!["code"])), "the same refusal as the read form");
+                Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(422));
+                Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(Fork["doorRefusals"]!.AsArray().Single(r => S(r!["name"]) == "fork_too_large")!["httpStatus"]!.GetValue<int>()));
+                Assert.That(S(c["outcome"]), Is.EqualTo("Refused")); Assert.That(S(c["code"]), Is.EqualTo("stale_fork")); Assert.That(c["counted"]!.GetValue<bool>(), Is.False);
+            }
+        }
+
+        [Test]
+        public void ForkTransport_ADoorRequestIdConflict_IsAFaultOnReadAndList_AndARefusalOnlyOnTheAnswer()
+        {
+            var cases = Fork["transport"]!["doorFaults"]!.AsArray();
+            Assert.That(cases.Select(c => S(c!["route"])), Is.EqualTo(new[] { "read", "list", "answer" }));
+            foreach (var c in cases)
+            {
+                var source = S(c!["route"]) == "answer" ? Fork["doorRefusals"]!.AsArray().Single(r => S(r!["name"]) == S(c["doorCode"]))! : Fork["unavailable"]![0]!;
+                Assert.That(S(c["responseHex"]), Is.EqualTo(S(source["messagePackHex"])), S(c["name"]));
+                Assert.That(HexOf(c["response"]), Is.EqualTo(S(c["responseHex"])), S(c["name"]));
+                Assert.That(c["httpStatus"]!.GetValue<int>(), Is.EqualTo(source["httpStatus"]!.GetValue<int>()), S(c["name"]));
+                Assert.That(Errors(ForkSchema, S(c["route"]) == "answer" ? "refusal" : "unavailable", c["response"]), Is.Empty, S(c["name"]));
+            }
+        }
+
+        [Test]
+        public void ForkTransport_Auth_BearerThenAudienceThenScope_AVotesTokenTouchesNothing()
+        {
+            var schema = JsonNode.Parse(File.ReadAllText(Path.Combine(RepoRoot(), "contracts", "cultnet", ForkSchema)))!;
+            var codes = schema["$defs"]!["refusal"]!["properties"]!["code"]!["enum"]!.AsArray().Select(S).ToList();
+            var seen = new HashSet<string>();
+            foreach (var c in Fork["transport"]!["authCases"]!.AsArray())
+            {
+                var got = AuthJudge(S(c!["route"]), c["token"], c["huginn_down"]!.GetValue<bool>());
+                Assert.That(got, Is.EqualTo(S(c["expect"])), S(c["name"]));
+                if (got is not ("ok" or "unavailable")) Assert.That(codes, Does.Contain(got), S(c["name"]));
+                seen.Add(S(c["route"]) + ":" + got);
+            }
+            Assert.That(seen, Does.Contain("list:insufficient_scope").And.Contain("answer:insufficient_scope").And.Contain("read:forbidden").And.Contain("list:unavailable").And.Contain("read:unavailable").And.Contain("answer:unavailable").And.Contain("read:unauthenticated").And.Contain("answer:ok"));
+        }
+    }
+}

tests/GameCult.Networking.Tests/MiniJsonSchemaValidator.cs

@@ -180,9 +180,10 @@ namespace GameCult.Networking.Tests
             if (instance.ValueKind == JsonValueKind.String)
             {
                 var value = instance.GetString()!;
-                if (schema.TryGetProperty("minLength", out var minLength) && value.Length < minLength.GetInt32())
+                var length = value.EnumerateRunes().Count();   // JSON Schema counts characters as code points, as Ajv does, not UTF-16 units
+                if (schema.TryGetProperty("minLength", out var minLength) && length < minLength.GetInt32())
                     errors.Add($"{path}: string shorter than minLength {minLength.GetInt32()}");
-                if (schema.TryGetProperty("maxLength", out var maxLength) && value.Length > maxLength.GetInt32())
+                if (schema.TryGetProperty("maxLength", out var maxLength) && length > maxLength.GetInt32())
                     errors.Add($"{path}: string longer than maxLength {maxLength.GetInt32()}");
                 if (schema.TryGetProperty("pattern", out var pattern))
                 {

tests/GameCult.Networking.Tests/SelectionParityVectorTests.cs

@@ -586,11 +586,11 @@ namespace GameCult.Networking.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("kind")]
+            [CultRole("kind")]
             public string Kind = string.Empty;
 
             [Key(2)]
-            [CultIndex("mass")]
+            [CultRole("mass")]
             public float Mass;
         }
 
@@ -631,7 +631,7 @@ namespace GameCult.Networking.Tests
             public string Name = string.Empty;
 
             [Key(1)]
-            [CultIndex("narrow_ref")]
+            [CultRole("narrow_ref")]
             [CultReference(typeof(ParityLeafA))]
             public CultRecordRef<ParityLeafA> NarrowRef;
         }

tests/vectors/unique-index/README.md

@@ -0,0 +1,24 @@
+# unique-index vectors
+
+Written only by the C# reference, `tests/GameCult.Caching.Tests/UniqueIndexVectorTests.cs`, with
+`CULTCACHE_WRITE_VECTORS=1`. Every other run reads these files and compares them byte for byte; a changed vector is a
+reviewed commit. Other runtimes are held to the same canonical text and the same verdicts (`variants:ruling:unique-indexes`).
+
+## Files
+
+- `values.msgpack`: an array of `[label, kind, value, text-or-nil]`, kind one of `string`, `int64`, `uint64`, `double`,
+  `bool` (decode integers 64-bit wide). `text` is the canonical index text of a member holding `value`: a record holding
+  it is found by `GetByIndex(alias, text)`. A nil text is a blank value: no value, never indexed, never judged, found by
+  no text, and two records holding it commit. Strings are as is (never trimmed), blank being empty or only C#
+  `White_Space` characters (U+0009-000D, U+0020, U+0085, U+00A0, U+1680, U+2000-200A, U+2028, U+2029, U+202F, U+205F,
+  U+3000); U+FEFF and U+001F are values. Booleans are `True` and `False`. Integers are their decimal digits. A
+  non-integral finite double is its exact decimal expansion (written by C# `RenderExactDouble`, never hand-typed),
+  `-0.0` is `0`, NaN and infinities are nil.
+- `duplicate-store.cc`: a single-file store, schema `tests.unique_item` v1, slots `[Sku: string, Category: string]`,
+  stored-at pinned to `2026-01-01T00:00:00Z`. Records `item:a` and `item:b` both hold Sku `S-1`; `item:c` holds Sku
+  `" "` and `item:d` holds Sku `U+0085`. Written through a role Sku.
+- `blank-store.cc`: the same, only `item:c` and `item:d`.
+- `outcomes.msgpack`: rows `[file, unique alias or nil, open|refused, k1 or nil, k2 or nil]`. Opening `file` with that
+  alias a unique index (nil: a role, no unique alias) yields the verdict. A refusal reads, byte for byte,
+  `Records <k1> and <k2> (tests.unique_item) both hold unique index '<alias>'; an index value names one record.`
+  with `k1 < k2` ordinal, never contains the value, and leaves the file byte-identical.

tests/vectors/unique-index/outcomes.msgpack

@@ -0,0 +1 @@
+“•˛duplicate-store.ccŁSku§refused¦item:a¦item:b•˛duplicate-store.ccŔ¤openŔŔ•®blank-store.ccŁSku¤openŔŔ

tools/sprite-silhouette/README.md

@@ -0,0 +1,68 @@
+# sprite-silhouette
+
+Turns a sprite's alpha channel into a simplified polygon in percent coordinates, for CSS
+`shape-outside: polygon()`, so text wraps around the figure instead of its rectangle. Zero
+dependencies: Node (tested on 24; `node:zlib` does the PNG inflate). Entry point: `silhouette.mjs`.
+Live and tested; there is no packaging or release for it, it is a repo tool.
+
+## First call
+
+```
+node tools/sprite-silhouette/silhouette.mjs /opt/commons/cast-art/poses --out silhouettes.json
+node --test tools/sprite-silhouette/silhouette.test.mjs
+```
+
+The first argument is a poses directory holding `catalogue.json` (the cast-art catalogue); the
+tool reads it and every PNG it names, and writes nothing there. Output is a JSON object keyed by
+pose id, `mind/label` in catalogue order (`void/neutral`, `eureka/probe`, ...):
+
+```json
+{ "void/neutral": { "width": 605, "height": 461,
+    "points": [[42.98, 6.72], [49.59, 8.24], "..."],
+    "css": "polygon(42.98% 6.72%, 49.59% 8.24%, ...)" } }
+```
+
+Use the `css` string as the value of `shape-outside` on a floated image of the same aspect ratio
+(percentages are of the image's box):
+
+```css
+img.pose { float: left; shape-outside: polygon(42.98% 6.72%, 49.59% 8.24%, ...); shape-margin: 0.5em; }
+```
+
+An empty sprite (nothing at or above the threshold) gets `points: []` and `css: "none"`.
+
+From code: `silhouette(pngBuffer, { threshold, tolerance })` in `silhouette.mjs`.
+
+## Options
+
+- `--threshold 0.35`: a pixel is inside when `alpha/255 >= threshold` (0.35 is the Void mock-up's value).
+- `--tolerance 1.5`: Douglas-Peucker distance in source pixels; the simplified polygon stays within
+  this of the traced edge in both directions (tested). 0 keeps every corner.
+- `--out file`: write there instead of stdout.
+
+## What it does and does not trace
+
+Threshold, then the outer boundary of the largest 8-connected shape, by walking the pixel edges
+(so vertices sit on pixel corners and the walk is exact), then simplification of that closed ring.
+Holes are ignored (wrapping text goes around a figure, not through its gaps), and smaller
+disconnected islands (a floating hand, a stray sparkle) are dropped: `shape-outside` takes one
+polygon. The contour is a staircase of pixel edges, so below about 1 px the tolerance only
+reproduces the staircase; there is no sub-pixel interpolation of the alpha ramp.
+
+Input: 8-bit non-interlaced PNG (RGBA, grey+alpha, palette with tRNS, or opaque RGB/grey, which is
+a rectangle). Anything else is refused with its name.
+
+## Prior art
+
+- **Marching squares** (Lorensen and Cline's cubes, 2D case) interpolates along the alpha ramp for
+  sub-pixel contours and one pass emits every contour, holes included. Not used: the pose art is
+  anti-aliased over a pixel or two, a 1.5 px tolerance swallows that, and we want exactly one outer ring.
+- **Potrace** (Selinger, 2003) fits optimal polygons and then Bezier curves to a bitmap. CSS
+  `polygon()` has no curves, so only its idea of an optimal polygon applies; this tool keeps the
+  simpler greedy Douglas-Peucker and measures its error directly.
+- **Douglas-Peucker** (1973; Ramer 1972) is the simplifier: keep the vertex farthest from the chord
+  if it is beyond the tolerance, recurse. Its guarantee (every dropped vertex within the tolerance
+  of the result) is what the tests assert. It is not topology-preserving; on all 99 current poses at
+  the defaults no output self-intersects (checked when this was written, not asserted by the suite).
+- **Boundary following** (Moore-neighbour / square tracing) is the contour walk, with the
+  8-connected rule so diagonally touching pixels stay one shape.

tools/sprite-silhouette/png.mjs

@@ -0,0 +1,82 @@
+// Minimal PNG reader: the alpha plane only. 8-bit, non-interlaced (every pose in cast-art is RGBA8).
+// Anything else is refused by name, never guessed at.
+import { inflateSync } from "node:zlib";
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+/** @returns {{ width: number, height: number, alpha: Uint8Array }} alpha is row-major, 0..255. */
+export function decodeAlpha(buffer) {
+  if (buffer.length < 8 || !buffer.subarray(0, 8).equals(SIGNATURE)) throw new Error("not a PNG");
+  let header = null;
+  let palette = null;
+  let trns = null;
+  const idat = [];
+  for (let at = 8; at + 8 <= buffer.length; ) {
+    const length = buffer.readUInt32BE(at);
+    const type = buffer.toString("latin1", at + 4, at + 8);
+    const body = buffer.subarray(at + 8, at + 8 + length);
+    if (body.length !== length) throw new Error(`truncated ${type} chunk`);
+    at += 12 + length;
+    if (type === "IHDR") {
+      header = { width: body.readUInt32BE(0), height: body.readUInt32BE(4), depth: body[8], color: body[9], interlace: body[12] };
+    } else if (type === "PLTE") palette = body;
+    else if (type === "tRNS") trns = body;
+    else if (type === "IDAT") idat.push(body);
+    else if (type === "IEND") break;
+  }
+  if (!header) throw new Error("PNG has no IHDR");
+  const { width, height, depth, color, interlace } = header;
+  if (depth !== 8) throw new Error(`unsupported PNG bit depth ${depth} (8 only)`);
+  if (interlace !== 0) throw new Error("unsupported PNG: interlaced");
+  const channels = CHANNELS[color];
+  if (!channels) throw new Error(`unsupported PNG color type ${color}`);
+  if (color === 3 && !palette) throw new Error("indexed PNG has no PLTE");
+
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  if (raw.length !== (stride + 1) * height) throw new Error("PNG pixel data has the wrong length");
+
+  const alpha = new Uint8Array(width * height);
+  let prev = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = Uint8Array.from(raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)));
+    unfilter(filter, line, prev, channels);
+    for (let x = 0; x < width; x++) {
+      const p = x * channels;
+      let a = 255;
+      if (color === 6) a = line[p + 3];
+      else if (color === 4) a = line[p + 1];
+      else if (color === 3) a = trns && line[p] < trns.length ? trns[line[p]] : 255;
+      else if (trns && color === 0 && line[p] === trns.readUInt16BE(0)) a = 0;
+      else if (trns && color === 2 && line[p] === trns.readUInt16BE(0) && line[p + 1] === trns.readUInt16BE(2) && line[p + 2] === trns.readUInt16BE(4)) a = 0;
+      alpha[y * width + x] = a;
+    }
+    prev = line;
+  }
+  return { width, height, alpha };
+}
+
+function unfilter(filter, line, prev, bpp) {
+  for (let i = 0; i < line.length; i++) {
+    const a = i >= bpp ? line[i - bpp] : 0;
+    const b = prev[i];
+    const c = i >= bpp ? prev[i - bpp] : 0;
+    let add;
+    switch (filter) {
+      case 0: add = 0; break;
+      case 1: add = a; break;
+      case 2: add = b; break;
+      case 3: add = (a + b) >> 1; break;
+      case 4: {
+        const p = a + b - c;
+        const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        add = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+        break;
+      }
+      default: throw new Error(`bad PNG filter ${filter}`);
+    }
+    line[i] = (line[i] + add) & 255;
+  }
+}

tools/sprite-silhouette/silhouette.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Sprite alpha silhouette -> simplified polygon in percent coordinates for CSS shape-outside: polygon().
+// First call: node tools/sprite-silhouette/silhouette.mjs /opt/commons/cast-art/poses > silhouettes.json
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { decodeAlpha } from "./png.mjs";
+import { largestContour, mask, simplifyRing } from "./trace.mjs";
+
+export const DEFAULTS = { threshold: 0.35, tolerance: 1.5 };
+
+const pct = (v, total) => Math.round((v / total) * 10000) / 100;
+
+/** @returns {{ width: number, height: number, points: number[][], css: string }} points are [x%, y%]; css is "none" for an empty sprite. */
+export function silhouette(png, { threshold = DEFAULTS.threshold, tolerance = DEFAULTS.tolerance } = {}) {
+  const { width, height, alpha } = decodeAlpha(png);
+  const ring = largestContour(mask(alpha, threshold), width, height);
+  if (!ring) return { width, height, points: [], css: "none" };
+  const points = simplifyRing(ring, tolerance).map(([x, y]) => [pct(x, width), pct(y, height)]);
+  const css = `polygon(${points.map(([x, y]) => `${x}% ${y}%`).join(", ")})`;
+  return { width, height, points, css };
+}
+
+/** Pose ids are `mind/label`, in catalogue order; the value is the path under the poses root. */
+export function poseFiles(catalogue) {
+  const files = {};
+  for (const [mind, entry] of Object.entries(catalogue.minds)) {
+    for (const group of [entry.shared, entry.signatures]) {
+      for (const [label, path] of Object.entries(group ?? {})) files[`${mind}/${label}`] = path;
+    }
+  }
+  return files;
+}
+
+export function silhouettes(root, options) {
+  const catalogue = JSON.parse(readFileSync(join(root, "catalogue.json"), "utf8"));
+  const out = {};
+  for (const [id, path] of Object.entries(poseFiles(catalogue))) out[id] = silhouette(readFileSync(join(root, path)), options);
+  return out;
+}
+
+function main(argv) {
+  const options = { ...DEFAULTS };
+  let out = null, root = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--threshold") options.threshold = Number(argv[++i]);
+    else if (argv[i] === "--tolerance") options.tolerance = Number(argv[++i]);
+    else if (argv[i] === "--out") out = argv[++i];
+    else if (argv[i].startsWith("--")) throw new Error(`unknown option ${argv[i]}`);
+    else root = argv[i];
+  }
+  if (!root || !(options.threshold > 0 && options.threshold <= 1) || !(options.tolerance >= 0)) {
+    console.error("usage: silhouette.mjs <poses-dir> [--threshold 0.35] [--tolerance 1.5] [--out file.json]");
+    process.exit(2);
+  }
+  const text = JSON.stringify(silhouettes(root, options), null, 1) + "\n";
+  if (out) writeFileSync(out, text);
+  else process.stdout.write(text);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main(process.argv.slice(2));

tools/sprite-silhouette/silhouette.test.mjs

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import test from "node:test";
+import { deflateSync } from "node:zlib";
+import { decodeAlpha } from "./png.mjs";
+import { silhouette, silhouettes } from "./silhouette.mjs";
+import { largestContour, mask, maxDistanceToRing, simplifyRing } from "./trace.mjs";
+
+// An RGBA8 PNG built from an alpha function, every row encoded with the given PNG filter.
+function crc32(buf) {
+  let c, crc = ~0;
+  for (let i = 0; i < buf.length; i++) {
+    c = (crc ^ buf[i]) & 255;
+    for (let k = 0; k < 8; k++) c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1;
+    crc = (crc >>> 8) ^ c;
+  }
+  return ~crc >>> 0;
+}
+function chunk(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, "latin1");
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+  return Buffer.concat([head, body, tail]);
+}
+function png(width, height, alphaAt, { filter = 0 } = {}) {
+  const rows = [];
+  let prev = Buffer.alloc(width * 4);
+  for (let y = 0; y < height; y++) {
+    const line = Buffer.alloc(width * 4);
+    for (let x = 0; x < width; x++) line.set([200, 10 * (x % 20), 30, alphaAt(x, y)], x * 4);
+    const out = Buffer.alloc(width * 4 + 1);
+    out[0] = filter;
+    for (let i = 0; i < line.length; i++) {
+      const a = i >= 4 ? line[i - 4] : 0, b = prev[i], c = i >= 4 ? prev[i - 4] : 0;
+      const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+      const pred = [0, a, b, (a + b) >> 1, pa <= pb && pa <= pc ? a : pb <= pc ? b : c][filter];
+      out[i + 1] = (line[i] - pred) & 255;
+    }
+    rows.push(out);
+    prev = line;
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 6;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr), chunk("IDAT", deflateSync(Buffer.concat(rows))), chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+const disc = (cx, cy, r) => (x, y) => ((x + 0.5 - cx) ** 2 + (y + 0.5 - cy) ** 2 <= r * r ? 255 : 0);
+
+test("decodes alpha through every PNG row filter", () => {
+  const f = (x, y) => (x * 7 + y * 13) % 256;
+  for (const filter of [0, 1, 2, 3, 4]) {
+    const { width, height, alpha } = decodeAlpha(png(9, 7, f, { filter }));
+    assert.deepEqual([width, height], [9, 7]);
+    for (let y = 0; y < 7; y++) for (let x = 0; x < 9; x++) assert.equal(alpha[y * 9 + x], f(x, y), `filter ${filter} at ${x},${y}`);
+  }
+});
+
+test("refuses what it cannot read", () => {
+  assert.throws(() => decodeAlpha(Buffer.from("nope")), /not a PNG/);
+  const bad = png(2, 2, () => 255);
+  bad[24] = 16; // IHDR bit depth
+  assert.throws(() => decodeAlpha(bad), /bit depth 16/);
+});
+
+test("a fully transparent sprite has no shape", () => {
+  const s = silhouette(png(8, 8, () => 0));
+  assert.deepEqual(s.points, []);
+  assert.equal(s.css, "none");
+});
+
+test("a fully opaque sprite is its own bounding box", () => {
+  const s = silhouette(png(8, 4, () => 255));
+  assert.deepEqual(s.points, [[0, 0], [100, 0], [100, 100], [0, 100]]);
+  assert.equal(s.css, "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)");
+});
+
+test("threshold is alpha/255 >= 0.35: 89 is out, 90 is in", () => {
+  assert.deepEqual(silhouette(png(4, 4, () => 89)).points, []);
+  assert.equal(silhouette(png(4, 4, () => 90)).points.length, 4);
+  assert.deepEqual(silhouette(png(4, 4, () => 89), { threshold: 0.3 }).points.length, 4);
+});
+
+test("simplified shape stays within tolerance of the traced edge, both ways, and is smaller", () => {
+  const { width, height, alpha } = decodeAlpha(png(120, 100, disc(60, 50, 40)));
+  const ring = largestContour(mask(alpha, 0.35), width, height);
+  for (const tolerance of [0.5, 1.5, 4]) {
+    const simple = simplifyRing(ring, tolerance);
+    assert.ok(simple.length < ring.length && simple.length >= 4);
+    assert.ok(maxDistanceToRing(ring, simple) <= tolerance + 1e-9, `ring to simplified at ${tolerance}`);
+    assert.ok(maxDistanceToRing(simple, ring) <= tolerance + 1e-9, `simplified to ring at ${tolerance}`);
+  }
+  // And the traced edge is the true edge to within a pixel: every ring vertex sits within 1px of the disc's circle.
+  for (const [x, y] of ring) assert.ok(Math.abs(Math.hypot(x - 60, y - 50) - 40) <= 1.0, `${x},${y}`);
+});
+
+test("only the outside is traced: a hole is ignored", () => {
+  const ring = (x, y) => (Math.max(Math.abs(x - 10), Math.abs(y - 10)) <= 8 && Math.max(Math.abs(x - 10), Math.abs(y - 10)) > 3 ? 255 : 0);
+  const s = silhouette(png(20, 20, ring), { tolerance: 0 });
+  const xs = s.points.map((p) => p[0]), ys = s.points.map((p) => p[1]);
+  assert.deepEqual([Math.min(...xs), Math.max(...xs), Math.min(...ys), Math.max(...ys)], [10, 95, 10, 95]);
+  assert.equal(s.points.length, 4);
+});
+
+test("pixels that only touch diagonally are one shape; a smaller island is dropped", () => {
+  const dots = (x, y) => (x === y && x < 4 ? 255 : 0);
+  const diag = silhouette(png(8, 8, dots), { tolerance: 0 });
+  const xs = diag.points.map((p) => p[0]);
+  assert.equal(Math.max(...xs), 50); // x 0..4 of 8
+  const island = (x, y) => ((x < 5 && y < 5) || (x === 8 && y === 8) ? 255 : 0);
+  const s = silhouette(png(10, 10, island));
+  assert.deepEqual(s.points, [[0, 0], [50, 0], [50, 50], [0, 50]]);
+});
+
+test("deterministic: same bytes, same polygon; coordinates are percent within the image", () => {
+  const bytes = png(90, 70, disc(45, 35, 30));
+  const a = silhouette(bytes), b = silhouette(Buffer.from(bytes));
+  assert.deepEqual(a, b);
+  for (const [x, y] of a.points) assert.ok(x >= 0 && x <= 100 && y >= 0 && y <= 100);
+  assert.match(a.css, /^polygon\((\d+(\.\d+)?% \d+(\.\d+)?%)(, \d+(\.\d+)?% \d+(\.\d+)?%){3,}\)$/);
+});
+
+const POSES = "/opt/commons/cast-art/poses";
+test("every pose in the shared cast-art catalogue gets a polygon", { skip: !existsSync(`${POSES}/catalogue.json`) }, () => {
+  const all = silhouettes(POSES);
+  const ids = Object.keys(all);
+  assert.ok(ids.length > 90 && ids.includes("void/neutral"));
+  for (const id of ids) assert.ok(all[id].points.length >= 4 && all[id].points.length < 400, id);
+  assert.deepEqual(silhouettes(POSES), all);
+});

tools/sprite-silhouette/trace.mjs

@@ -0,0 +1,109 @@
+// Silhouette of an alpha plane: threshold -> outer contour of the largest 8-connected shape -> Douglas-Peucker.
+// Coordinates are pixel-corner lattice points: x in 0..width, y in 0..height.
+
+/** A pixel is inside when alpha/255 >= threshold. */
+export function mask(alpha, threshold) {
+  const m = new Uint8Array(alpha.length);
+  for (let i = 0; i < alpha.length; i++) m[i] = alpha[i] / 255 >= threshold ? 1 : 0;
+  return m;
+}
+
+/** Outer contour (lattice vertices at turns, clockwise on screen) of the 8-connected component with the most pixels, or null. */
+export function largestContour(m, width, height) {
+  const seen = new Uint8Array(m.length);
+  let best = null;
+  for (let start = 0; start < m.length; start++) {
+    if (!m[start] || seen[start]) continue;
+    // Raster order: `start` is the component's first pixel, so the pixels above and up-left of it are empty
+    // or belong to another component.
+    let count = 0;
+    const stack = [start];
+    seen[start] = 1;
+    while (stack.length) {
+      const p = stack.pop();
+      count++;
+      const px = p % width, py = (p / width) | 0;
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+        const x = px + dx, y = py + dy;
+        if (x < 0 || y < 0 || x >= width || y >= height) continue;
+        const q = y * width + x;
+        if (m[q] && !seen[q]) { seen[q] = 1; stack.push(q); }
+      }
+    }
+    if (!best || count > best.count) best = { count, start };
+  }
+  return best && traceOuter(m, width, height, best.start % width, (best.start / width) | 0);
+}
+
+// Directions: 0 east, 1 south, 2 west, 3 north. The shape is kept on the walker's right, so an
+// outer boundary comes out clockwise; at each corner a filled left-ahead pixel turns left (which
+// joins pixels that only touch diagonally), else a filled right-ahead pixel goes straight, else right.
+const DX = [1, 0, -1, 0], DY = [0, 1, 0, -1];
+const AHEAD_LEFT = [[0, -1], [0, 0], [-1, 0], [-1, -1]];
+const AHEAD_RIGHT = [[0, 0], [-1, 0], [-1, -1], [0, -1]];
+
+function traceOuter(m, width, height, px, py) {
+  const at = (x, y) => x >= 0 && y >= 0 && x < width && y < height && m[y * width + x] === 1;
+  const vertices = [];
+  let x = px, y = py, dir = 3, first = true; // arrive at the start corner heading north, so it is counted as a turn
+  for (;;) {
+    const left = at(x + AHEAD_LEFT[dir][0], y + AHEAD_LEFT[dir][1]);
+    const right = at(x + AHEAD_RIGHT[dir][0], y + AHEAD_RIGHT[dir][1]);
+    const turn = left ? 3 : right ? 0 : 1;
+    const next = (dir + turn) & 3;
+    // Back at the start corner and about to leave east: the ring is closed.
+    if (!first && x === px && y === py && next === 0) break;
+    first = false;
+    if (turn !== 0) vertices.push([x, y]);
+    dir = next;
+    x += DX[dir]; y += DY[dir];
+  }
+  return vertices;
+}
+
+/** Douglas-Peucker on a closed ring: split at the vertex farthest from the first, simplify both halves. */
+export function simplifyRing(ring, tolerance) {
+  if (ring.length <= 3 || tolerance <= 0) return ring.slice();
+  let far = 0, best = -1;
+  for (let i = 1; i < ring.length; i++) {
+    const d = (ring[i][0] - ring[0][0]) ** 2 + (ring[i][1] - ring[0][1]) ** 2;
+    if (d > best) { best = d; far = i; }
+  }
+  const a = dp(ring.slice(0, far + 1), tolerance);
+  const b = dp(ring.slice(far).concat([ring[0]]), tolerance);
+  return a.slice(0, -1).concat(b.slice(0, -1));
+}
+
+function dp(points, tolerance) {
+  const keep = new Uint8Array(points.length);
+  keep[0] = keep[points.length - 1] = 1;
+  const stack = [[0, points.length - 1]];
+  while (stack.length) {
+    const [lo, hi] = stack.pop();
+    let worst = -1, at = -1;
+    for (let i = lo + 1; i < hi; i++) {
+      const d = distanceToSegment(points[i], points[lo], points[hi]);
+      if (d > worst) { worst = d; at = i; }
+    }
+    if (worst > tolerance) { keep[at] = 1; stack.push([lo, at], [at, hi]); }
+  }
+  return points.filter((_, i) => keep[i]);
+}
+
+export function distanceToSegment(p, a, b) {
+  const vx = b[0] - a[0], vy = b[1] - a[1];
+  const len2 = vx * vx + vy * vy;
+  const t = len2 === 0 ? 0 : Math.max(0, Math.min(1, ((p[0] - a[0]) * vx + (p[1] - a[1]) * vy) / len2));
+  return Math.hypot(p[0] - (a[0] + t * vx), p[1] - (a[1] + t * vy));
+}
+
+/** Largest distance from any point of ring `a`'s edges' vertices to ring `b`'s edges. */
+export function maxDistanceToRing(points, ring) {
+  let worst = 0;
+  for (const p of points) {
+    let d = Infinity;
+    for (let i = 0; i < ring.length; i++) d = Math.min(d, distanceToSegment(p, ring[i], ring[(i + 1) % ring.length]));
+    worst = Math.max(worst, d);
+  }
+  return worst;
+}