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

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

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

.github/workflows/cultmesh-portability.yml

@@ -9,44 +9,6 @@ on:
   workflow_dispatch:
 
 jobs:
-  getting-started:
-    name: ${{ matrix.os }} one-command multiplayer onboarding
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [windows-latest, ubuntu-latest]
-
-    steps:
-      - name: Check out CultLib
-        uses: actions/checkout@v4
-        with:
-          path: CultLib
-
-      - name: Check out the matching Eve contract
-        uses: actions/checkout@v4
-        with:
-          repository: GameCult/Eve
-          # Eve main is the contract this sample is written against; the codex
-          # branch this used to pin was never merged and stopped on 2026-08-25.
-          ref: ${{ vars.EVE_INTEGRATION_REF || 'main' }}
-          path: Eve
-
-      - name: Set up .NET
-        uses: actions/setup-dotnet@v4
-        with:
-          dotnet-version: 10.0.x
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-
-      - name: Run the documented one-command checkpoint
-        shell: pwsh
-        run: ./CultLib/scripts/verify-eve-getting-started.ps1 -EveRoot ./Eve
-
   reactive-and-resource-lifetime:
     name: ${{ matrix.os }} reactive semantics and leases
     runs-on: ${{ matrix.os }}
@@ -54,7 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [windows-latest, ubuntu-latest]
+        # The forge runner is Ubuntu-only: Windows legs run on workflow_dispatch (GitHub or a Windows runner), Ubuntu gates push and PR.
+        os: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '["windows-latest", "ubuntu-latest"]' || '["ubuntu-latest"]') }}
 
     steps:
       - name: Check out CultLib

.github/workflows/cultnet-interop.yml

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

.github/workflows/publish-packages.yml

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

.gitignore

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

CultLib.sln

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

README.md

@@ -1,5 +1,7 @@
 # CultLib
 
+**New here? Start at [`docs/start`](docs/start/README.md)**: a language x package matrix with tested first-call snippets.
+
 CultLib is GameCult's shared state, transport, and runtime substrate. It started
 as reusable C# game infrastructure, but the useful thing now is larger: typed
 `.cc` persistence, schema-stable wire formats, ergonomic reliable-UDP
@@ -96,7 +98,8 @@ start with the maintained
 series. Its first executable package-consumer checkpoint is
 [`samples/eve-two-runtime`](samples/eve-two-runtime/README.md).
 The real-process browser continuation is
-[`samples/eve-browser-network`](samples/eve-browser-network/README.md).
+[`samples/eve-browser-network`](samples/eve-browser-network/README.md); it
+needs a sibling Eve checkout (`--eve-root`) and is not in `CultLib.sln`.
 One documented command runs both layers:
 
 ```powershell

contracts/cultnet/cultnet-distributed-database.md

@@ -112,8 +112,9 @@ not guess. Adding a code is therefore a coordinated change across every runtime,
 copies), the C# `CultNetErrorMessage` factory, the Rust `CultNetErrorCode`, and a captured-bytes case in
 `packages/cultnet-rs/tests/error_message.rs` for it. TypeScript reads the schema. The current codes are
 `selection_invalid`, `cursor_stale`, `cursor_invalid`, `reference_outside_target`, `variant_unsupported`,
-`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns) and
-`write_not_authorized` (a peer's put or delete its server's remote write authority did not grant).
+`unowned_schema` (a write, or a remote put or delete, for a schema and key no shard owns),
+`write_not_authorized` (a peer's put or delete its server's remote write authority did not grant) and
+`unsupported_schema_version` (a message whose `schemaVersion` the peer does not speak; `details` names `schemaVersion` and the offered value).
 
 ## Live Invariants
 

contracts/cultnet/cultnet.error.schema.json

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

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

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

contracts/cultnet/interop/error-vectors.json

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

docs/cultmesh-ts-content-map.md

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

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

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

docs/semver-policy.md

@@ -352,10 +352,21 @@ own path into the DLL. No `global.json` pins the .NET SDK, so the same refusal
 at unchanged source and CRLF checkout means this SDK or host differs from the
 one that built the tracked DLL.
 
+### Before pushing a tag
+
+A tag run uses the workflow files at the tagged commit, not the ones on main, and
+the forge's GitHub mirror forwards the tag. Read `.github/workflows/publish-packages.yml`
+(and any workflow that triggers on tags) at the tagged sha before pushing any tag:
+a guard merged after that commit does not protect a tag that points before it.
+`cultcache-ts-v0.15.0` sits on `7d292085`, which predates the guard, and its push
+started a publish run (it failed; nothing reached npm).
+
 ### Coverage gaps
 
-`publish-packages.yml` only triggers on `cultcache-ts-v*`, `cultcache-py-v*`,
-`cultnet-py-v*`, and `cultmesh-py-v*` tag pushes — it does not build or gate
+`publish-packages.yml` only triggers on `cultcache-py-v*`, `cultnet-py-v*`, and
+`cultmesh-py-v*` tag pushes (`cultcache-ts-v*` is deliberately not a trigger: npm
+publishing is off until ruled on, and the cultcache-ts job runs from
+`workflow_dispatch` only, publishing nothing) — it does not build or gate
 the Unity UPM packages at all; those are consumed directly by git tag
 (`unity/org.gamecult.cultlib`, `packages/cultmath/unity/org.gamecult.cultmath`,
 `src/GameCult.Unity/Assets/Caching`), so a workflow trigger on their tags

docs/start/README.md

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

docs/start/io-game.md

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

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

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

docs/start/io-game/browser.ts

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

docs/start/io-game/client.ts

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

docs/start/io-game/index.html

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

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

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

docs/start/io-game/package.json

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

docs/start/io-game/schema.ts

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

docs/start/io-game/serve.ts

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

docs/start/io-game/server.ts

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

package-lock.json

@@ -482,6 +482,18 @@
       "resolved": "packages/cultcache-ts",
       "link": true
     },
+    "node_modules/@gamecult/cultmesh-browser": {
+      "resolved": "packages/cultmesh-browser",
+      "link": true
+    },
+    "node_modules/@gamecult/cultmesh-ts": {
+      "resolved": "packages/cultmesh-ts",
+      "link": true
+    },
+    "node_modules/@gamecult/cultnet-ts": {
+      "resolved": "packages/cultnet-ts",
+      "link": true
+    },
     "node_modules/@jsdevtools/ono": {
       "version": "7.1.3",
       "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz",
@@ -865,18 +877,6 @@
       "dev": true,
       "license": "Python-2.0"
     },
-    "node_modules/cultmesh-browser": {
-      "resolved": "packages/cultmesh-browser",
-      "link": true
-    },
-    "node_modules/cultmesh-ts": {
-      "resolved": "packages/cultmesh-ts",
-      "link": true
-    },
-    "node_modules/cultnet-ts": {
-      "resolved": "packages/cultnet-ts",
-      "link": true
-    },
     "node_modules/esbuild": {
       "version": "0.28.1",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
@@ -1184,7 +1184,7 @@
     },
     "packages/cultcache-ts": {
       "name": "@gamecult/cultcache-ts",
-      "version": "0.14.2",
+      "version": "0.15.0",
       "license": "MIT",
       "dependencies": {
         "@msgpack/msgpack": "^3.1.3",
@@ -1200,15 +1200,16 @@
       }
     },
     "packages/cultmesh-browser": {
+      "name": "@gamecult/cultmesh-browser",
       "version": "0.4.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.3.0"
+        "@gamecult/cultcache-ts": "^0.15.0",
+        "@gamecult/cultnet-ts": "^0.3.0"
       },
       "devDependencies": {
+        "@gamecult/cultmesh-ts": "^0.2.0",
         "@types/node": "^24.0.0",
-        "cultmesh-ts": "^0.2.0",
         "typescript": "^5.9.0"
       },
       "engines": {
@@ -1216,11 +1217,12 @@
       }
     },
     "packages/cultmesh-ts": {
+      "name": "@gamecult/cultmesh-ts",
       "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.0",
-        "cultnet-ts": "^0.3.0",
+        "@gamecult/cultcache-ts": "^0.15.0",
+        "@gamecult/cultnet-ts": "^0.3.0",
         "koffi": "3.3.0"
       },
       "devDependencies": {
@@ -1233,10 +1235,11 @@
       }
     },
     "packages/cultnet-ts": {
+      "name": "@gamecult/cultnet-ts",
       "version": "0.3.0",
       "license": "MIT",
       "dependencies": {
-        "@gamecult/cultcache-ts": "^0.14.1",
+        "@gamecult/cultcache-ts": "^0.15.0",
         "@msgpack/msgpack": "^3.1.3",
         "ajv": "^8.17.1"
       },

packages/cultcache-py/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Changed
+
+- `msgpack` is a hard dependency, as `pyproject.toml` declared it. The optional-import fallbacks and the `cultcache-py[msgpack]` extra they named (which never existed) are gone: a missing msgpack is an `ImportError` at import.
+- The single-file store's `push`, `push_all` and `delete` take the cross-process lock on `<path>.lock` (flock; LockFileEx over the whole file on Windows) across the read and the replace, waiting up to `lock_timeout` seconds (30 by default, `TimeoutError` after), and exclude the C#, Rust and TypeScript runtimes' writers. The staged file is `<path>.tmp-<pid>-<uuid>`, fsynced before the replace, with a directory fsync after it off Windows. A fixed `<path>.tmp` is no longer used.
+
 ### Breaking
 
 - A single-file store written as `cultcache.store.v3` is read and written: a record that holds an element id (an owned list element with an `[CultElementId]` member, carried through every write) marks the store v3, and a v3 store is carried through a rewrite with its ids. A runtime from before this change refuses a v3 store by name.

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

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

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

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

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

@@ -3,9 +3,15 @@
 import base64
 import json
 import os
+import sys
 import threading
+import time
+import uuid
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Callable, TypeVar
+from typing import Any, Callable, Iterator, TypeVar
+
+import msgpack
 
 from .backing_store import (
     CultCacheEnvelope,
@@ -21,6 +27,8 @@ STORE_FORMAT_ELEMENT_IDS = "cultcache.store.v3"
 _READABLE_STORE_FORMATS = (STORE_FORMAT_VERSION, STORE_FORMAT_ELEMENT_IDS)
 _STORE_FORMAT_PREFIX = "cultcache.store."
 _PERSISTED_RECORD_SLOTS = 4
+_LOCK_POLL_SECONDS = 0.01
+LOCK_TIMEOUT_SECONDS = 30.0
 _Contents = TypeVar("_Contents")
 
 
@@ -114,14 +122,14 @@ class JsonLinesBackingStore:
 
 
 class SingleFileMessagePackBackingStore:
-    def __init__(self, path: str | os.PathLike[str]) -> None:
+    def __init__(self, path: str | os.PathLike[str], lock_timeout: float = LOCK_TIMEOUT_SECONDS) -> None:
         self.path = Path(path)
+        self.lock_timeout = lock_timeout
         self._lock = threading.RLock()
         # The header this store read; a rewrite keeps it, so a store that holds element ids never sheds its marker.
         self._format = STORE_FORMAT_VERSION
 
     def pull_all(self) -> list[CultCacheEnvelope]:
-        msgpack = self._msgpack()
         with self._lock:
             # An empty file is not a store (no writer leaves one), so it is decoded and refused.
             # The disk decides the header: a file that is gone is not marked.
@@ -135,39 +143,34 @@ class SingleFileMessagePackBackingStore:
                 if snapshot is not None:
                     self._format, envelopes = snapshot
                     return envelopes
-                return _decode_legacy_envelopes(decoded, msgpack)
+                return _decode_legacy_envelopes(decoded)
             except Exception as exc:
                 raise StoreUnreadableError(self.path, exc) from exc
 
     def push(self, envelope: CultCacheEnvelope) -> None:
-        with self._lock:
+        with self._write_transaction():
             self._replace_all([envelope], self.pull_all())
 
     def push_all(self, envelopes: list[CultCacheEnvelope]) -> None:
-        with self._lock:
+        with self._write_transaction():
             self._replace_all(list(envelopes), self.pull_all())
 
     def delete(self, type: str, key: str) -> None:
-        with self._lock:
+        with self._write_transaction():
             self._replace_all([], [item for item in self.pull_all() if not (item.type == type and item.key == key)])
 
-    def _replace_all(self, supplied: list[CultCacheEnvelope], arrived: list[CultCacheEnvelope]) -> None:
-        msgpack = self._msgpack()
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        temp = self.path.with_suffix(self.path.suffix + ".tmp")
-        temp.write_bytes(msgpack.packb(_encode_snapshot(supplied, arrived, self._format), use_bin_type=True))
-        temp.replace(self.path)
+    @contextmanager
+    def _write_transaction(self) -> Iterator[None]:
+        """The thread lock, then the cross-process lock on `<path>.lock`, held across the read and the replace so two
+        processes never rewrite from the same stale read."""
+        with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with store_write_lock(self.path, self.lock_timeout):
+                yield
+
+    def _replace_all(self, supplied: list[CultCacheEnvelope], arrived: list[CultCacheEnvelope]) -> None:
+        commit_store_file(self.path, msgpack.packb(_encode_snapshot(supplied, arrived, self._format), use_bin_type=True))
 
-    @staticmethod
-    def _msgpack() -> Any:
-        try:
-            import msgpack  # type: ignore
-        except ModuleNotFoundError as exc:
-            raise RuntimeError(
-                "SingleFileMessagePackBackingStore requires the optional 'msgpack' dependency. "
-                "Install with: python -m pip install cultcache-py[msgpack]"
-            ) from exc
-        return msgpack
 
 
 def canonical(candidates: Any) -> list[CultCacheSchemaCatalogEntry]:
@@ -261,6 +264,85 @@ def _encode_snapshot(
     ]
     return [format_version, catalog, records]
 
+def commit_store_file(path: Path, data: bytes) -> None:
+    """Writes `data` to a unique staged file beside the store, fsyncs it, replaces the store with it and, off Windows,
+    fsyncs the directory so the replace is durable. A failure before the replace removes the staged file and leaves the
+    store untouched. The caller holds the store lock."""
+    staged = path.with_name(f"{path.name}.tmp-{os.getpid()}-{uuid.uuid4().hex}")
+    try:
+        fd = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o666)
+        try:
+            view = memoryview(data)
+            while view:
+                view = view[os.write(fd, view):]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(staged, path)
+    except BaseException:
+        try:
+            os.unlink(staged)
+        except OSError:
+            pass
+        raise
+    if sys.platform != "win32":
+        directory = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+
+
+@contextmanager
+def store_write_lock(path: Path, timeout: float = LOCK_TIMEOUT_SECONDS) -> Iterator[None]:
+    """Holds the exclusive store lock on `<path>.lock`, the lock the C#, Rust and TypeScript runtimes take: flock on Unix,
+    LockFileEx over the whole file on Windows, polled every 10 ms with no handle held between polls. The lock file is
+    created if absent and never written or deleted."""
+    lock_path = path.with_name(path.name + ".lock")
+    deadline = time.monotonic() + timeout
+    while True:
+        release = _try_lock(lock_path)
+        if release is not None:
+            break
+        if time.monotonic() >= deadline:
+            raise TimeoutError(f"CultCache timed out after {timeout} s waiting for the store lock {lock_path}.")
+        time.sleep(_LOCK_POLL_SECONDS)
+    try:
+        yield
+    finally:
+        release()
+
+
+def _try_lock(lock_path: Path) -> Callable[[], None] | None:
+    if sys.platform == "win32":
+        return _try_lock_windows(lock_path)
+    import fcntl
+
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o666)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        os.close(fd)
+        return None
+    return lambda: os.close(fd)  # closing drops the flock
+
+
+def _try_lock_windows(lock_path: Path) -> Callable[[], None] | None:
+    import ctypes
+    import msvcrt
+    from ctypes import wintypes
+
+    kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+    kernel.LockFileEx.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD, ctypes.c_void_p]
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT | os.O_BINARY, 0o666)
+    handle = msvcrt.get_osfhandle(fd)
+    overlapped = ctypes.create_string_buffer(32)
+    # LOCKFILE_EXCLUSIVE_LOCK | LOCKFILE_FAIL_IMMEDIATELY over the whole range, as the TypeScript runtime takes it.
+    if not kernel.LockFileEx(handle, 0x3, 0, 0xFFFFFFFF, 0xFFFFFFFF, overlapped):
+        os.close(fd)
+        return None
+    return lambda: os.close(fd)  # closing drops the lock
+
 
 def _read_store(path: Path, read: Callable[[Path], _Contents]) -> _Contents | None:
     """Reads a store file, or returns None when nothing is at its path.
@@ -351,7 +433,7 @@ def _decode_snapshot(decoded: Any) -> tuple[str, list[CultCacheEnvelope]] | None
     return decoded[0], envelopes
 
 
-def _decode_legacy_envelopes(decoded: Any, msgpack: Any) -> list[CultCacheEnvelope]:
+def _decode_legacy_envelopes(decoded: Any) -> list[CultCacheEnvelope]:
     if not isinstance(decoded, list):
         raise ValueError("CultCache MessagePack store is not a recognized snapshot")
     envelopes: list[CultCacheEnvelope] = []

packages/cultcache-py/tests/test_first_call.py

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

packages/cultcache-py/tests/test_slot_nil.py

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

packages/cultcache-py/tests/test_store_lock.py

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

packages/cultcache-rs/CHANGELOG.md

@@ -13,6 +13,7 @@ only in git history.
 
 ### Added
 
+- Lookups, matching the C# `GetByName`, `GetByIndex` and `GetGlobal`. `#[cultcache(name)]` and `#[cultcache(index)]` / `#[cultcache(index = "alias")]` on `DatabaseEntry` fields and `#[cultcache(global)]` on the struct give `CultCache::get_by_name`, `get_by_index` and `get_global`. An empty name and a blank index value are not found; records of one type sharing a name or value find the one with the smallest key. A second record of a global type under another key is refused on every write path and on load with `CultCacheSecondGlobal`. Two `name` members, or two members with one index alias, are refused at compile time. A member's text comes from `CultLookupValue` (`String`, `Option` of one, integers, `bool`, `char`).
 - `SchemaConflictError`, the typed refusal of a write the catalog cannot describe: records of different types under one schema id, or an arrived schema and a registered one that share an id and disagree on the schema name. A whole-store write (`push_all`) refuses with it, names the schema id, the names involved and a record key, writes nothing and leaves the file as it is. A caller tells it apart with `error.downcast_ref::<SchemaConflictError>()`.
 
 ## [0.3.1]

packages/cultcache-rs/README.md

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

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

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

packages/cultcache-rs/src/lib.rs

@@ -162,8 +162,68 @@ pub use cultcache_rs_derive::DatabaseEntry;
 pub trait DatabaseEntry: Serialize + DeserializeOwned + Clone + Send + 'static {
     const TYPE: &'static str;
     const SCHEMA_NAME: &'static str = "DatabaseEntry";
+    /// `#[cultcache(global)]`: the cache holds at most one record of this type, found by `get_global`.
+    const GLOBAL: bool = false;
+    /// The `#[cultcache(name)]` member's value, which `get_by_name` finds the record by. `None` is no name.
+    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()
+    }
 }
 
+/// 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 {
+    fn lookup_value(&self) -> Option<String>;
+}
+
+impl CultLookupValue for String {
+    fn lookup_value(&self) -> Option<String> {
+        Some(self.clone())
+    }
+}
+
+impl<T: CultLookupValue> CultLookupValue for Option<T> {
+    fn lookup_value(&self) -> Option<String> {
+        self.as_ref().and_then(CultLookupValue::lookup_value)
+    }
+}
+
+macro_rules! lookup_value_by_display {
+    ($($ty:ty),* $(,)?) => {$(
+        impl CultLookupValue for $ty {
+            fn lookup_value(&self) -> Option<String> {
+                Some(self.to_string())
+            }
+        }
+    )*};
+}
+
+lookup_value_by_display!(bool, 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)]
+pub struct CultCacheSecondGlobal {
+    pub schema_name: String,
+    pub existing_key: String,
+    pub key: String,
+}
+
+impl std::fmt::Display for CultCacheSecondGlobal {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            formatter,
+            "{} is a global and already has record {}; {} would be a second.",
+            self.schema_name, self.existing_key, self.key
+        )
+    }
+}
+
+impl std::error::Error for CultCacheSecondGlobal {}
+
 /// A type written as a positional slots array: what the `CultSlots` and `DatabaseEntry`
 /// derives implement, and what a `CultUnion` arm must carry.
 #[diagnostic::on_unimplemented(
@@ -2655,6 +2715,8 @@ struct CultCacheStoreRegistration {
 
 pub struct CultCache {
     definitions: BTreeMap<String, &'static str>,
+    /// The registered types declared `#[cultcache(global)]`.
+    globals: BTreeSet<String>,
     schema_name_definitions: BTreeMap<String, String>,
     entries: BTreeMap<(String, String), CultCacheEnvelope>,
     stores: Vec<CultCacheStoreRegistration>,
@@ -2664,6 +2726,7 @@ impl CultCache {
     pub fn new() -> Self {
         Self {
             definitions: BTreeMap::new(),
+            globals: BTreeSet::new(),
             schema_name_definitions: BTreeMap::new(),
             entries: BTreeMap::new(),
             stores: Vec::new(),
@@ -2694,6 +2757,11 @@ impl CultCache {
             ));
         }
         self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME);
+        if T::GLOBAL {
+            self.globals.insert(T::TYPE.to_string());
+        } else {
+            self.globals.remove(T::TYPE);
+        }
         self.schema_name_definitions
             .insert(T::SCHEMA_NAME.to_string(), T::TYPE.to_string());
         Ok(())
@@ -2800,6 +2868,7 @@ impl CultCache {
                 loaded.insert(entry_id(&entry), entry);
             }
         }
+        self.refuse_second_globals(&loaded)?;
         self.entries = loaded;
         Ok(())
     }
@@ -2883,6 +2952,65 @@ impl CultCache {
         Ok(values)
     }
 
+    /// The one record of a `#[cultcache(global)]` type, or `None` before it is written (and for a type that is
+    /// not a global).
+    pub fn get_global<T: DatabaseEntry>(&self) -> Result<Option<T>> {
+        self.require_entry_type::<T>()?;
+        if !T::GLOBAL {
+            return Ok(None);
+        }
+        self.find_record::<T>(|_| true)
+    }
+
+    /// The record whose `#[cultcache(name)]` member is `name`. An empty name is no name, so it finds nothing. Records
+    /// of one type sharing a name find the one with the smallest key (ordinal), whatever order they were written or
+    /// loaded in; removing it finds the next.
+    pub fn get_by_name<T: DatabaseEntry>(&self, name: &str) -> Result<Option<T>> {
+        self.require_entry_type::<T>()?;
+        if name.is_empty() {
+            return Ok(None);
+        }
+        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.
+    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() {
+            return Ok(None);
+        }
+        self.find_record::<T>(|document| {
+            document
+                .cult_indexes()
+                .iter()
+                .any(|(held_alias, held_value)| *held_alias == alias && held_value == value)
+        })
+    }
+
+    /// The first record of `T`, in key order, that `matches`.
+    fn find_record<T: DatabaseEntry>(&self, matches: impl Fn(&T) -> bool) -> Result<Option<T>> {
+        let held = self
+            .entries
+            .range((T::TYPE.to_string(), String::new())..)
+            .take_while(|((held_type, _), _)| held_type == T::TYPE);
+        for (_, entry) in held {
+            let document: T = decode_payload(&entry.payload).with_context(|| {
+                format!(
+                    "failed to decode CultCache entry {:?} at key {:?} as {}",
+                    T::TYPE,
+                    entry.key,
+                    T::SCHEMA_NAME
+                )
+            })?;
+            if matches(&document) {
+                return Ok(Some(document));
+            }
+        }
+        Ok(None)
+    }
+
     pub fn soa<T: SoaDocument>(&self) -> Result<CultSoaTable<T>> {
         let keyed_rows = self.get_all_with_keys::<T>()?;
         let (keys, documents): (Vec<_>, Vec<_>) = keyed_rows.into_iter().unzip();
@@ -2900,6 +3028,7 @@ 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)?;
         if let Some(home) = self.home_index(T::TYPE)? {
             self.stores[home].store.push(&entry)?;
         }
@@ -3011,6 +3140,7 @@ impl CultCache {
         for entry in &staged {
             next.insert(entry_id(entry), entry.clone());
         }
+        self.refuse_second_globals(&next)?;
         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.
@@ -3029,6 +3159,7 @@ impl CultCache {
 
     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)?;
         if let Some(home) = self.home_index(T::TYPE)? {
             self.stores[home].store.push(&entry)?;
         }
@@ -3061,6 +3192,7 @@ impl CultCache {
             ));
         }
         require_payload_depth(&entry)?;
+        self.refuse_second_global(&self.entries, &entry.r#type, &entry.key)?;
         if let Some(home) = self.home_index(&entry.r#type)? {
             self.stores[home].store.push(&entry)?;
         }
@@ -3146,10 +3278,43 @@ impl CultCache {
             self.home_index(&entry.r#type)?;
             loaded.insert(entry_id(&entry), entry);
         }
+        self.refuse_second_globals(&loaded)?;
         self.entries = loaded;
         Ok(())
     }
 
+    fn refuse_second_global(
+        &self,
+        entries: &BTreeMap<(String, String), CultCacheEnvelope>,
+        type_id: &str,
+        key: &str,
+    ) -> Result<()> {
+        if !self.globals.contains(type_id) {
+            return Ok(());
+        }
+        let held_other = entries
+            .range((type_id.to_string(), String::new())..)
+            .take_while(|((held_type, _), _)| held_type == type_id)
+            .map(|((_, held_key), _)| held_key)
+            .find(|held_key| held_key.as_str() != key);
+        match held_other {
+            Some(existing_key) => Err(CultCacheSecondGlobal {
+                schema_name: self.definitions.get(type_id).copied().unwrap_or(type_id).to_string(),
+                existing_key: existing_key.clone(),
+                key: key.to_string(),
+            }
+            .into()),
+            None => Ok(()),
+        }
+    }
+
+    fn refuse_second_globals(&self, entries: &BTreeMap<(String, String), CultCacheEnvelope>) -> Result<()> {
+        for (type_id, key) in entries.keys() {
+            self.refuse_second_global(entries, type_id, key)?;
+        }
+        Ok(())
+    }
+
     fn require_entry_type<T: DatabaseEntry>(&self) -> Result<()> {
         match self.definitions.get(T::TYPE) {
             Some(schema_name) if *schema_name == T::SCHEMA_NAME => Ok(()),

packages/cultcache-rs/tests/first_call.rs

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

packages/cultcache-rs/tests/lookups.rs

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

packages/cultcache-ts/CHANGELOG.md

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

packages/cultcache-ts/README.md

@@ -61,7 +61,7 @@ const note = decodeDocumentPayload(noteDocument, envelope.payload); // parsed No
 const payload = encodeDocumentPayload(noteDocument, note); // DocumentPayload
 ```
 
-Browsers import the same names from `@gamecult/cultcache-ts/document`, which holds no Node built-ins.
+Browsers import the same names from `@gamecult/cultcache-ts/document`, which holds no Node built-ins. The whole cache without the single-file store is `@gamecult/cultcache-ts/browser`, which is also what bundlers resolve for the package root (`browser` condition); bring your own `CacheBackingStore`.
 
 ## `.cc` Inspection
 

packages/cultcache-ts/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@gamecult/cultcache-ts",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "CultCache-style typed persistence for TypeScript with schema-backed polymorphic MessagePack storage.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "browser": "./dist/browser.js",
       "require": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "require": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
     "./document": {
       "types": "./dist/document.d.ts",
       "require": "./dist/document.js",
@@ -25,6 +31,9 @@
     "*": {
       "document": [
         "dist/document.d.ts"
+      ],
+      "browser": [
+        "dist/browser.d.ts"
       ]
     }
   },

packages/cultcache-ts/src/browser.ts

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

packages/cultcache-ts/src/index.ts

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

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

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

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

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

packages/cultmath/README.md

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

packages/cultmath/docs/design.md

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

packages/cultmath/shaders/CultMath.glsl

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

packages/cultmath/shaders/CultMath.hlsl

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

packages/cultmath/src/CultMath/math.cs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -5,6 +5,14 @@ All notable changes to this package are documented in this file.
 Earlier releases (0.2.0-0.2.3) predate this package's changelog and are not
 backfilled here; see `docs/semver-policy.md` for why.
 
+## [Unreleased]
+
+### Added
+
+- `math.fbm(float3 p, int octaves, float lacunarity, float gain)` and `math.fbm(float3 p)` (four octaves,
+  lacunarity 2, gain 0.5): the value-only octave sum of `snoise`, the cost of `fbm_grad` without the gradient.
+  The shaders carry `cultmath_fbm` in HLSL and GLSL; octaves clamp to [0, 16] as `fbm_grad`'s do.
+
 ## [0.5.0]
 
 ### Breaking

packages/cultmath/unity/org.gamecult.cultmath/Shaders/CultMath.hlsl

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

packages/cultmesh-browser/CHANGELOG.md

@@ -1,8 +1,14 @@
 # Changelog
 
-All notable changes to `cultmesh-browser` are recorded here, following
+All notable changes to `@gamecult/cultmesh-browser` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## Unreleased
+
+### Breaking
+
+- The package is renamed `cultmesh-browser` to `@gamecult/cultmesh-browser` (the repo already scopes `@gamecult/cultcache-ts`), so the unscoped name cannot be claimed by someone else. Import from `@gamecult/cultmesh-browser` and its subpaths; the API is unchanged. Depends on `@gamecult/cultnet-ts`; the interop test uses `@gamecult/cultmesh-ts`.
+
 ## [0.4.0]
 
 ### Added

packages/cultmesh-browser/README.md

@@ -1,6 +1,6 @@
 # CultMesh Browser
 
-`cultmesh-browser` is the browser-safe CultMesh client boundary. It owns one
+`@gamecult/cultmesh-browser` is the browser-safe CultMesh client boundary. It owns one
 WebSocket session for a stable Verse/authority-runtime target, retains explicit raw
 document leases across route replacement, and correlates typed CultNet
 operations with provider receipts.
@@ -95,7 +95,7 @@ WebCrypto `crypto.subtle`; without WebCrypto it fails with
 endpoint CultMesh resolved is the only host the reader trusts.
 
 ```ts
-import { fetchVerifiedContent } from "cultmesh-browser";
+import { fetchVerifiedContent } from "@gamecult/cultmesh-browser";
 
 const bytes = await fetchVerifiedContent(endpoint, manifest, {
   signal: AbortSignal.timeout(30_000),

packages/cultmesh-browser/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "cultmesh-browser",
+  "name": "@gamecult/cultmesh-browser",
   "version": "0.4.0",
   "description": "Browser-safe CultMesh document leases and typed operations over CultNet WebSocket transport.",
   "type": "module",
@@ -41,12 +41,12 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@gamecult/cultcache-ts": "^0.14.0",
-    "cultnet-ts": "^0.3.0"
+    "@gamecult/cultcache-ts": "^0.15.0",
+    "@gamecult/cultnet-ts": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "cultmesh-ts": "^0.2.0",
+    "@gamecult/cultmesh-ts": "^0.2.0",
     "typescript": "^5.9.0"
   }
 }

packages/cultmesh-browser/src/content.ts

@@ -3,8 +3,8 @@
 // The response's declared length and coding are never consulted (Fetch decodes codings; the bytes received are the evidence).
 // Hashing, hex rules, record keys, the loopback rule and manifest validation belong to cultnet-ts and are only called here.
 
-import { EMPTY_SHA256, chunkRecordKey, parseSha256Hex, sha256Hex, validateManifest, type CultMeshCdnArtifactManifest } from "cultnet-ts/content";
-import { isLoopbackEndpoint } from "cultnet-ts/authority";
+import { EMPTY_SHA256, chunkRecordKey, parseSha256Hex, sha256Hex, validateManifest, type CultMeshCdnArtifactManifest } from "@gamecult/cultnet-ts/content";
+import { isLoopbackEndpoint } from "@gamecult/cultnet-ts/authority";
 
 export type CultMeshContentErrorCode =
   | "manifest-invalid" | "too-large" | "insecure-endpoint" | "webcrypto-unavailable" | "network"

packages/cultmesh-browser/src/index.ts

@@ -1,6 +1,6 @@
 import { decodeDocumentPayload } from "@gamecult/cultcache-ts/document";
 import type { AnyCultCacheDocumentDefinition, CultCacheDocumentValue } from "@gamecult/cultcache-ts";
-import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
 import {
   encodeCultNetMessageForWire,
   parseCultNetMessage,
@@ -16,7 +16,7 @@ import {
   type CultMeshVerseCatalogResponseMessage,
   type CultMeshSessionAcceptedMessage,
   type CultMeshSessionOpenMessage,
-} from "cultnet-ts/contracts";
+} from "@gamecult/cultnet-ts/contracts";
 import {
   base64ToBytes,
   bytesToBase64,
@@ -31,7 +31,7 @@ import {
   type CultMeshAuthorityTrustMode,
   type CultMeshAuthorityTrustPolicy,
   type CultMeshP256PublicKey,
-} from "cultnet-ts/authority";
+} from "@gamecult/cultnet-ts/authority";
 export * from "./content.js";
 
 export type CultMeshBrowserIdentity = CultMeshAuthorityIdentity;

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

@@ -11,7 +11,7 @@ import { gzipSync } from "node:zlib";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { build } from "esbuild";
-import { EMPTY_SHA256, packContent, sha256Hex, type CultMeshCdnArtifactManifest } from "cultnet-ts/content";
+import { EMPTY_SHA256, packContent, sha256Hex, type CultMeshCdnArtifactManifest } from "@gamecult/cultnet-ts/content";
 
 import { CultMeshContentError, fetchVerifiedChunk, fetchVerifiedContent, type CultMeshContentErrorCode } from "../src/content.js";
 

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

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { codecs, defineDocumentType, documentPayloadFromBytes } from "@gamecult/cultcache-ts";
-import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
 import {
   encodeCultNetMessageForWire,
   parseCultNetMessage,
@@ -12,7 +12,7 @@ import {
   type CultNetRawDocumentRecord,
   type CultMeshVerseCatalogResponseMessage,
   type CultMeshSessionOpenMessage,
-} from "cultnet-ts/contracts";
+} from "@gamecult/cultnet-ts/contracts";
 
 import {
   CultMeshBrowserClient,

packages/cultmesh-browser/test/interop/content-https-provider.ts

@@ -5,8 +5,8 @@ import { readFileSync } from "node:fs";
 import { createServer } from "node:https";
 import type { AddressInfo } from "node:net";
 import { createInterface } from "node:readline";
-import { chunkRecordKey } from "cultnet-ts/content";
-import { createContentChunkHandler, createDirectoryChunkStore, toNodeListener, type ContentChunkAnswer, type ContentChunkRequest } from "cultmesh-ts/content";
+import { chunkRecordKey } from "@gamecult/cultnet-ts/content";
+import { createContentChunkHandler, createDirectoryChunkStore, toNodeListener, type ContentChunkAnswer, type ContentChunkRequest } from "@gamecult/cultmesh-ts/content";
 
 const [storeDir, corruptDir, keyPem, certPem, escapeKey] = process.argv.slice(2) as [string, string, string, string, string];
 const say = (line: object): void => { process.stdout.write(`${JSON.stringify(line)}\n`); };

packages/cultmesh-browser/test/interop/content-https-reader.ts

@@ -3,7 +3,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { decodeManifest } from "cultnet-ts/content";
+import { decodeManifest } from "@gamecult/cultnet-ts/content";
 import { fetchVerifiedChunk, fetchVerifiedContent, CultMeshContentError } from "../../src/content.js";
 
 const [endpointsJson, manifestsDir, only] = process.argv.slice(2) as [string, string, string | undefined];

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

@@ -12,7 +12,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { EMPTY_SHA256, encodeManifest, packContent } from "cultnet-ts/content";
+import { EMPTY_SHA256, encodeManifest, packContent } from "@gamecult/cultnet-ts/content";
 
 const execFileAsync = promisify(execFile);
 const here = dirname(fileURLToPath(import.meta.url)); // dist-test/test/interop

packages/cultmesh-browser/test/payload-type.test.ts

@@ -2,8 +2,8 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { documentPayloadBytes, documentPayloadFromBytes, type DocumentPayload } from "@gamecult/cultcache-ts";
-import { decodeWireValue } from "cultnet-ts/wire";
-import type { CultNetRawDocumentRecord } from "cultnet-ts/contracts";
+import { decodeWireValue } from "@gamecult/cultnet-ts/wire";
+import type { CultNetRawDocumentRecord } from "@gamecult/cultnet-ts/contracts";
 
 import { decodeCultNetPayload } from "../src/index.js";
 

packages/cultmesh-py/README.md

@@ -7,7 +7,7 @@ game sessions with prediction reconciliation, committed simulation facts, the
 local TCP/RUDP server, and a package daemon.
 
 It depends on `cultcache-py` and `cultnet-py`, mirroring `cultmesh-rs` and
-`cultmesh-ts`. The Verse catalog, peer exchange, authority lease, stream
+`@gamecult/cultmesh-ts`. The Verse catalog, peer exchange, authority lease, stream
 negotiation, and simulation fact contracts are defined in
 `cultnet_py.cultmesh_contracts` and re-exported here.
 
@@ -228,6 +228,17 @@ prediction = session.predict(note_doc, "input:python:move", {"body": "predicted
 unsubscribe()
 ```
 
+## Authority route verification
+
+`cultmesh_py.authority` ports the C# reference
+(`src/GameCult.Mesh/CultMeshAuthorityProof.cs`): `AuthorityTrustPolicy.validate`
+judges an Odin-signed ECDSA P-256 route (channel protection, trusted root,
+validity window, IEEE P1363 signature over the canonical bytes) and
+`verify_session_proof` checks the provider nonce proof. Refusals raise
+`AuthorityRouteRefusal` with the C# message text. It needs `cryptography`.
+`tests/test_authority_route_vectors.py` judges
+`contracts/cultmesh/authority-route-vectors*.json`.
+
 ## Verify
 
 `cultmesh_py.verify` checks the public exports and `py.typed` markers of all

packages/cultmesh-py/pyproject.toml

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

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

@@ -0,0 +1,338 @@
+"""CultMesh authority route verification.
+
+Port of `src/GameCult.Mesh/CultMeshAuthorityProof.cs` (the reference) and of the
+route constructors in `CultMeshVerse.cs`. Rule for rule, in the same order, the
+same input yields the same refusal text as `CultMeshAuthorityTrustPolicy.Verify`:
+unsigned, channel protection, root lookup, validity window, signature.
+
+Shared vectors: `contracts/cultmesh/authority-route-vectors.json` (C# written).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+import struct
+from dataclasses import dataclass
+from typing import Iterable, Mapping, Sequence
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+
+ROUTE_DOMAIN = "gamecult.cultmesh.route-certificate.v1"
+SESSION_DOMAIN = "gamecult.cultmesh.session-proof.v1"
+
+AUTHENTICATED_REMOTE = "authenticated-remote"
+LOCAL_DEVELOPMENT = "local-development"
+
+# .NET `char.IsWhiteSpace`: Unicode Zs, Zl, Zp, U+0009-U+000D and U+0085.
+# `str.strip()` is a different set (it also strips U+001C-U+001F).
+_CSHARP_WHITESPACE = (
+    "\u0009\u000a\u000b\u000c\u000d \u0085  "
+    "           "
+    "

  　"
+)
+
+
+def trim_csharp(value: str) -> str:
+    return value.strip(_CSHARP_WHITESPACE)
+
+
+def is_blank_csharp(value: str | None) -> bool:
+    return value is None or trim_csharp(value) == ""
+
+
+def _require(value: str | None, name: str) -> str:
+    if is_blank_csharp(value):
+        raise ValueError(f"Value must be non-empty. (Parameter '{name}')")
+    return trim_csharp(value)  # type: ignore[arg-type]
+
+
+class AuthorityRouteRefusal(Exception):
+    """A route or proof the consumer's trust policy refuses.
+
+    Mirrors `CultMeshSessionException` carrying a `CultMeshSessionFailure` with
+    reason `Authentication`: `reason` is always "authentication".
+    """
+
+    reason = "authentication"
+
+    def __init__(self, message: str, endpoint: str = "") -> None:
+        super().__init__(message)
+        self.message = message
+        self.endpoint = endpoint
+
+
+def _b64_strict(value: str) -> bytes:
+    # `Convert.FromBase64String`: standard alphabet, padded, whitespace ignored.
+    stripped = re.sub(r"[ \t\r\n]", "", value)
+    return base64.b64decode(stripped, validate=True)
+
+
+@dataclass(frozen=True)
+class P256PublicKey:
+    key_id: str
+    x: str
+    y: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "key_id", _require(self.key_id, "keyId"))
+        for name in ("x", "y"):
+            value = _require(getattr(self, name), name)
+            try:
+                _b64_strict(value)
+            except (binascii.Error, ValueError) as error:
+                raise ValueError(f"Coordinate must be base64. (Parameter '{name}')") from error
+            object.__setattr__(self, name, value)
+
+    def verify(self, payload: bytes, signature_base64: str) -> bool:
+        """IEEE P1363 (r || s) ECDSA-SHA256 verification; False on any malformation."""
+        try:
+            x, y = _b64_strict(self.x), _b64_strict(self.y)
+            signature = _b64_strict(signature_base64)
+            if len(x) != 32 or len(y) != 32 or len(signature) != 64:
+                return False
+            key = ec.EllipticCurvePublicNumbers(
+                int.from_bytes(x, "big"), int.from_bytes(y, "big"), ec.SECP256R1()
+            ).public_key()
+            der = encode_dss_signature(
+                int.from_bytes(signature[:32], "big"), int.from_bytes(signature[32:], "big")
+            )
+            key.verify(der, payload, ec.ECDSA(hashes.SHA256()))
+            return True
+        except (InvalidSignature, ValueError, binascii.Error):
+            return False
+
+
+@dataclass(frozen=True)
+class RouteCertificate:
+    provider_key: P256PublicKey
+    odin_key_id: str
+    issued_at_unix_milliseconds: int
+    expires_at_unix_milliseconds: int
+    signature: str = ""
+
+    def __post_init__(self) -> None:
+        if is_blank_csharp(self.odin_key_id):
+            raise ValueError("Odin key identity is required. (Parameter 'odinKeyId')")
+        object.__setattr__(self, "odin_key_id", trim_csharp(self.odin_key_id))
+        if self.issued_at_unix_milliseconds < 0:
+            raise ValueError("issuedAtUnixMilliseconds must not be negative.")
+        if self.expires_at_unix_milliseconds <= self.issued_at_unix_milliseconds:
+            raise ValueError("expiresAtUnixMilliseconds must be after issuedAtUnixMilliseconds.")
+        object.__setattr__(self, "signature", trim_csharp(self.signature or ""))
+
+
+@dataclass(frozen=True)
+class AuthorityRoute:
+    """`CultMeshAuthorityRoute`: construction cleans every field as the C# does."""
+
+    authority_runtime_id: str
+    endpoint: str
+    protocol_ids: Sequence[str] = ()
+    priority: int = 0
+    generation: str | None = None
+    certificate: RouteCertificate | None = None
+
+    def __post_init__(self) -> None:
+        runtime_id = _require(self.authority_runtime_id, "authorityRuntimeId")
+        endpoint = _require(self.endpoint, "endpoint")
+        if self.priority < 0:
+            raise ValueError("priority must not be negative.")
+        object.__setattr__(self, "authority_runtime_id", runtime_id)
+        object.__setattr__(self, "endpoint", endpoint)
+        object.__setattr__(
+            self,
+            "protocol_ids",
+            tuple(
+                sorted(
+                    {trim_csharp(v) for v in self.protocol_ids if not is_blank_csharp(v)},
+                    key=lambda v: v.encode("utf-16-be"),  # StringComparer.Ordinal is UTF-16 code-unit order
+                )
+            ),
+        )
+        object.__setattr__(
+            self,
+            "generation",
+            f"{runtime_id}@{endpoint}" if is_blank_csharp(self.generation) else trim_csharp(self.generation),  # type: ignore[arg-type]
+        )
+
+
+@dataclass(frozen=True)
+class SessionOpen:
+    """The fields of `CultMeshSessionOpenMessage` the session proof covers."""
+
+    client_nonce: str | None = None
+    message_id: str | None = None
+    source_runtime_id: str | None = None
+    verse_id: str | None = None
+    authority_runtime_id: str | None = None
+    protocol_id: str | None = None
+    route_generation: str | None = None
+
+
+@dataclass(frozen=True)
+class SessionAccepted:
+    client_nonce: str | None
+    provider_key_id: str | None
+    provider_signature: str | None
+
+
+@dataclass(frozen=True)
+class VerifiedRoute:
+    route: AuthorityRoute
+    provider_key: P256PublicKey | None
+    is_local_development: bool
+
+
+def canonical_fields(*values: str | None) -> bytes:
+    out = bytearray()
+    for value in values:
+        encoded = (value or "").encode("utf-8")
+        out += struct.pack(">I", len(encoded)) + encoded
+    return bytes(out)
+
+
+def canonical_route(verse_id: str, route: AuthorityRoute) -> bytes:
+    certificate = route.certificate
+    if certificate is None:
+        raise ValueError("Route certificate is required.")
+    return canonical_fields(
+        ROUTE_DOMAIN,
+        verse_id,
+        route.authority_runtime_id,
+        route.endpoint,
+        "\u001f".join(route.protocol_ids),  # already ordinally sorted; Python sorts by code point
+        str(route.priority),
+        route.generation,
+        certificate.provider_key.key_id,
+        certificate.provider_key.x,
+        certificate.provider_key.y,
+        certificate.odin_key_id,
+        str(certificate.issued_at_unix_milliseconds),
+        str(certificate.expires_at_unix_milliseconds),
+    )
+
+
+def canonical_session(request: SessionOpen, endpoint: str) -> bytes:
+    return canonical_fields(
+        SESSION_DOMAIN,
+        request.client_nonce,
+        request.message_id,
+        request.source_runtime_id,
+        request.verse_id,
+        request.authority_runtime_id,
+        request.protocol_id,
+        endpoint,
+        request.route_generation,
+    )
+
+
+# `System.Uri` refuses spellings WHATWG parsers repair; a lenient parse could call
+# a refused endpoint loopback or protected. Same shape rule as the TypeScript port.
+_AUTHORITY = re.compile(r"^[A-Za-z][A-Za-z0-9+\-.]*://([^/?#]+)")
+
+
+def _split_endpoint(value: str) -> tuple[str, str] | None:
+    """Return (scheme, lowercase host) or None where System.Uri would refuse."""
+    raw = re.sub(r"^[\x00-\x20]+|[\x00-\x20]+$", "", value)
+    if "\\" in raw:
+        return None
+    shape = _AUTHORITY.match(raw)
+    if not shape:
+        return None
+    authority = shape.group(1)
+    after_user = authority[authority.rfind("@") + 1 :]
+    if after_user.startswith("["):
+        host = after_user[: after_user.find("]") + 1]
+    else:
+        host = after_user.split(":")[0]
+    if not host or re.search(r"[^!-~]", host) or host.endswith("."):
+        return None
+    return raw.split("://", 1)[0].lower(), host.strip("[]").lower()
+
+
+def is_loopback_endpoint(endpoint: str) -> bool:
+    parts = _split_endpoint(endpoint)
+    if parts is None:
+        return False
+    host = parts[1]
+    return host in ("localhost", "loopback", "::1", "::ffff:127.0.0.1") or bool(
+        re.fullmatch(r"127\.\d{1,3}\.\d{1,3}\.\d{1,3}", host)
+    )
+
+
+def is_protected_endpoint(endpoint: str) -> bool:
+    parts = _split_endpoint(endpoint)
+    return parts is not None and (parts[0] in ("wss", "https") or "quic" in parts[0])
+
+
+class AuthorityTrustPolicy:
+    """Consumer-owned policy. Fails closed unless a route is valid under it."""
+
+    def __init__(self, mode: str, odin_roots: Iterable[P256PublicKey] = ()) -> None:
+        if mode not in (AUTHENTICATED_REMOTE, LOCAL_DEVELOPMENT):
+            raise ValueError(f"Unknown trust mode '{mode}'.")
+        self.mode = mode
+        self._roots: dict[str, P256PublicKey] = {}
+        for root in odin_roots:
+            if root.key_id in self._roots:
+                raise ValueError(f"Odin root key id '{root.key_id}' is listed more than once in the trust policy.")
+            self._roots[root.key_id] = root
+
+    def validate(self, verse_id: str, route: AuthorityRoute, now_unix_milliseconds: int) -> None:
+        self.verify(verse_id, route, now_unix_milliseconds)
+
+    def verify(self, verse_id: str, route: AuthorityRoute, now_unix_milliseconds: int) -> VerifiedRoute:
+        local = self.mode == LOCAL_DEVELOPMENT and is_loopback_endpoint(route.endpoint)
+
+        def refuse(message: str) -> AuthorityRouteRefusal:
+            return AuthorityRouteRefusal(message, route.endpoint)
+
+        certificate = route.certificate
+        if certificate is None or is_blank_csharp(certificate.signature):
+            if local:
+                return VerifiedRoute(route, None, True)
+            raise refuse("Remote CultMesh routes require an Odin-signed authority certificate.")
+        if not is_protected_endpoint(route.endpoint) and not local:
+            raise refuse("Authenticated remote CultMesh routes require TLS or QUIC channel protection.")
+        root = self._roots.get(certificate.odin_key_id)
+        if root is None:
+            raise refuse(f"Odin key '{certificate.odin_key_id}' is not trusted by this consumer.")
+        if not (certificate.issued_at_unix_milliseconds <= now_unix_milliseconds < certificate.expires_at_unix_milliseconds):
+            raise refuse("The Odin route certificate is not currently valid.")
+        try:
+            signature = _b64_strict(certificate.signature)
+        except (binascii.Error, ValueError):
+            raise refuse("The Odin route signature is not base64.") from None
+        if len(signature) != 64:
+            raise refuse("The Odin route signature is not IEEE P1363 P-256.")
+        if not root.verify(canonical_route(verse_id, route), certificate.signature):
+            raise refuse("The Odin route certificate signature is invalid.")
+        return VerifiedRoute(route, certificate.provider_key, False)
+
+
+def verify_session_proof(
+    request: SessionOpen,
+    response: SessionAccepted,
+    verse_id: str,
+    route: AuthorityRoute,
+    trust: AuthorityTrustPolicy,
+    now_unix_milliseconds: int,
+) -> bool:
+    """Verifies the Odin route certificate (raising) and the provider nonce proof."""
+    verified = trust.verify(verse_id, route, now_unix_milliseconds)
+    if verified.is_local_development:
+        return True
+    key = verified.provider_key
+    if (
+        key is None
+        or response.provider_key_id != key.key_id
+        or response.client_nonce != request.client_nonce
+        or is_blank_csharp(response.provider_signature)
+    ):
+        return False
+    return key.verify(canonical_session(request, route.endpoint), response.provider_signature)  # type: ignore[arg-type]

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

@@ -10,6 +10,7 @@ from typing import Any
 import msgpack
 
 from cultnet_py import (
+    unsupported_schema_version_error,
     CultNetRawSnapshotResponse,
     CultNetSimulationObservationHub,
     CultNetRudpPacket,
@@ -229,12 +230,7 @@ class CultMeshLocalServer:
         if schema_version == "cultnet.simulation_observation.v0":
             candidates = self._candidate_responses(message)
             return candidates[0] if candidates else None
-        return self._error_response(
-            f"Unsupported CultNet message schema: {schema_version!r}.",
-            message_id=str(message.get("messageId") or ""),
-            code="unsupported_schema_version",
-            details={"schemaVersion": schema_version},
-        )
+        return unsupported_schema_version_error(schema_version).to_wire()
 
     def _accept_loop(self) -> None:
         while not self._stop.is_set():

packages/cultmesh-py/tests/test_authority_route_vectors.py

@@ -0,0 +1,217 @@
+"""Judges `contracts/cultmesh/authority-route-vectors*.json` in Python.
+
+`authority-route-vectors.json` is written by the C# reference (signatures are
+captured C# bytes); the `.ts-signed.json` file is signed by TypeScript over awkward
+inputs. Each negative case fails when the matching check is removed from
+`cultmesh_py.authority`.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import unittest
+from dataclasses import replace
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from cultmesh_py.authority import (
+    AUTHENTICATED_REMOTE,
+    LOCAL_DEVELOPMENT,
+    AuthorityRoute,
+    AuthorityRouteRefusal,
+    AuthorityTrustPolicy,
+    P256PublicKey,
+    RouteCertificate,
+    SessionAccepted,
+    SessionOpen,
+    canonical_route,
+    verify_session_proof,
+)
+
+CONTRACTS = Path(__file__).resolve().parents[3] / "contracts" / "cultmesh"
+
+
+def _key(element: dict) -> P256PublicKey:
+    return P256PublicKey(element["keyId"], element["x"], element["y"])
+
+
+class Vector:
+    def __init__(self, name: str) -> None:
+        doc = json.loads((CONTRACTS / name).read_text(encoding="utf-8"))
+        self.now = doc["nowUnixMilliseconds"]
+        self.root = _key(doc["odinRoot"])
+        r = doc["route"]
+        self.verse_id = r["verseId"]
+        c = r["certificate"]
+        self.certificate = RouteCertificate(
+            _key(c["providerKey"]), c["odinKeyId"], c["issuedAtUnixMilliseconds"],
+            c["expiresAtUnixMilliseconds"], c["signature"],
+        )
+        self.route = AuthorityRoute(
+            r["authorityRuntimeId"], r["endpoint"], r["protocolIds"], r["priority"],
+            r["generation"], self.certificate,
+        )
+        p = doc["sessionProof"]
+        q = p["request"]
+        self.request = SessionOpen(
+            q["clientNonce"], q["messageId"], q["sourceRuntimeId"], q["verseId"],
+            q["authorityRuntimeId"], q["protocolId"], q["routeGeneration"],
+        )
+        self.accepted = SessionAccepted(q["clientNonce"], p["providerKeyId"], p["providerSignature"])
+        self.trust = AuthorityTrustPolicy(AUTHENTICATED_REMOTE, [self.root])
+
+    def with_certificate(self, **changes) -> AuthorityRoute:
+        return replace(self.route, certificate=replace(self.certificate, **changes))
+
+
+def refusal(test: unittest.TestCase, fn) -> str:
+    with test.assertRaises(AuthorityRouteRefusal) as raised:
+        fn()
+    test.assertEqual("authentication", raised.exception.reason)
+    return raised.exception.message
+
+
+class AuthorityRouteVectorTests(unittest.TestCase):
+    def test_cs_written_vector_verifies_route_and_session_proof(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        v.trust.validate(v.verse_id, v.route, v.now)
+        self.assertTrue(verify_session_proof(v.request, v.accepted, v.verse_id, v.route, v.trust, v.now))
+
+    def test_ts_signed_vector_verifies_and_tamper_is_refused(self) -> None:
+        v = Vector("authority-route-vectors.ts-signed.json")
+        v.trust.validate(v.verse_id, v.route, v.now)
+        self.assertTrue(verify_session_proof(v.request, v.accepted, v.verse_id, v.route, v.trust, v.now))
+        tampered = replace(v.route, priority=v.route.priority + 1)
+        self.assertEqual(
+            "The Odin route certificate signature is invalid.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, tampered, v.now)),
+        )
+
+    def test_canonical_route_is_length_prefixed_and_sorted(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        data = canonical_route(v.verse_id, v.route)
+        self.assertTrue(data.startswith(b"\x00\x00\x00\x26gamecult.cultmesh.route-certificate.v1\x00\x00\x00\x08aetheria"))
+        self.assertIn(b"cultmesh.content.v1\x1fcultmesh.documents.v1", data)
+
+    def test_tampered_payload_fields_are_refused(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        invalid = "The Odin route certificate signature is invalid."
+        for tampered, verse in (
+            (replace(v.route, priority=8), v.verse_id),
+            (replace(v.route, endpoint="wss://evil.example/mesh"), v.verse_id),
+            (replace(v.route, protocol_ids=("cultmesh.documents.v1",)), v.verse_id),
+            (replace(v.route, generation="other"), v.verse_id),
+            (v.with_certificate(expires_at_unix_milliseconds=v.certificate.expires_at_unix_milliseconds + 1), v.verse_id),
+            (v.route, "other-verse"),
+        ):
+            self.assertEqual(invalid, refusal(self, lambda: v.trust.validate(verse, tampered, v.now)))
+
+    def test_wrong_root_key_is_refused(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        numbers = ec.generate_private_key(ec.SECP256R1()).public_key().public_numbers()
+        impostor = P256PublicKey(
+            v.root.key_id,
+            base64.b64encode(numbers.x.to_bytes(32, "big")).decode(),
+            base64.b64encode(numbers.y.to_bytes(32, "big")).decode(),
+        )
+        trust = AuthorityTrustPolicy(AUTHENTICATED_REMOTE, [impostor])
+        self.assertEqual(
+            "The Odin route certificate signature is invalid.",
+            refusal(self, lambda: trust.validate(v.verse_id, v.route, v.now)),
+        )
+
+    def test_untrusted_odin_key_id_is_refused(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        trust = AuthorityTrustPolicy(AUTHENTICATED_REMOTE, [replace(v.root, key_id="someone-else")])
+        self.assertEqual(
+            "Odin key 'odin-vector' is not trusted by this consumer.",
+            refusal(self, lambda: trust.validate(v.verse_id, v.route, v.now)),
+        )
+
+    def test_expired_and_not_yet_valid_are_refused(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        window = "The Odin route certificate is not currently valid."
+        expires = v.certificate.expires_at_unix_milliseconds
+        issued = v.certificate.issued_at_unix_milliseconds
+        v.trust.validate(v.verse_id, v.route, expires - 1)
+        v.trust.validate(v.verse_id, v.route, issued)
+        self.assertEqual(window, refusal(self, lambda: v.trust.validate(v.verse_id, v.route, expires)))
+        self.assertEqual(window, refusal(self, lambda: v.trust.validate(v.verse_id, v.route, issued - 1)))
+
+    def test_unsigned_and_unprotected_routes_are_refused(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        unsigned = replace(v.route, certificate=None)
+        self.assertEqual(
+            "Remote CultMesh routes require an Odin-signed authority certificate.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, unsigned, v.now)),
+        )
+        blank = v.with_certificate(signature="  ")
+        self.assertEqual(
+            "Remote CultMesh routes require an Odin-signed authority certificate.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, blank, v.now)),
+        )
+        plain = replace(v.route, endpoint="ws://provider.example/mesh")
+        self.assertEqual(
+            "Authenticated remote CultMesh routes require TLS or QUIC channel protection.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, plain, v.now)),
+        )
+
+    def test_local_development_admits_only_unsigned_loopback(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        dev = AuthorityTrustPolicy(LOCAL_DEVELOPMENT, [])
+        loop = AuthorityRoute("a", "ws://127.0.0.1:9/mesh")
+        dev.validate(v.verse_id, loop, v.now)
+        self.assertTrue(verify_session_proof(v.request, v.accepted, v.verse_id, loop, dev, v.now))
+        for endpoint in ("ws://provider.example/mesh", "ws://127.0.0.1./mesh", "ws:127.0.0.1"):
+            refusal(self, lambda e=endpoint: dev.validate(v.verse_id, AuthorityRoute("a", e), v.now))
+        authenticated = AuthorityTrustPolicy(AUTHENTICATED_REMOTE, [])
+        refusal(self, lambda: authenticated.validate(v.verse_id, loop, v.now))
+
+    def test_malformed_signatures_get_their_own_refusals(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        not_base64 = v.with_certificate(signature="!!not base64!!")
+        self.assertEqual(
+            "The Odin route signature is not base64.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, not_base64, v.now)),
+        )
+        short = v.with_certificate(signature=base64.b64encode(b"x" * 63).decode())
+        self.assertEqual(
+            "The Odin route signature is not IEEE P1363 P-256.",
+            refusal(self, lambda: v.trust.validate(v.verse_id, short, v.now)),
+        )
+
+    def test_high_s_signature_verifies_as_it_does_in_dotnet(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        order = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551
+        raw = base64.b64decode(v.certificate.signature)
+        s = int.from_bytes(raw[32:], "big")
+        flipped = raw[:32] + (order - s).to_bytes(32, "big")
+        high = v.with_certificate(signature=base64.b64encode(flipped).decode())
+        v.trust.validate(v.verse_id, high, v.now)
+
+    def test_session_proof_rejects_replay_wrong_key_and_forgery(self) -> None:
+        v = Vector("authority-route-vectors.json")
+        replayed = replace(v.request, client_nonce="replayed")
+        accepted = replace(v.accepted, client_nonce="replayed")
+        self.assertFalse(verify_session_proof(replayed, accepted, v.verse_id, v.route, v.trust, v.now))
+        self.assertFalse(verify_session_proof(
+            v.request, replace(v.accepted, provider_key_id="other"), v.verse_id, v.route, v.trust, v.now))
+        self.assertFalse(verify_session_proof(
+            v.request, replace(v.accepted, client_nonce="other"), v.verse_id, v.route, v.trust, v.now))
+        self.assertFalse(verify_session_proof(
+            v.request, replace(v.accepted, provider_signature=""), v.verse_id, v.route, v.trust, v.now))
+        raw = bytearray(base64.b64decode(v.accepted.provider_signature))
+        raw[0] ^= 1
+        forged = replace(v.accepted, provider_signature=base64.b64encode(bytes(raw)).decode())
+        self.assertFalse(verify_session_proof(v.request, forged, v.verse_id, v.route, v.trust, v.now))
+        moved = replace(v.request, protocol_id="cultmesh.content.v1")
+        self.assertFalse(verify_session_proof(moved, v.accepted, v.verse_id, v.route, v.trust, v.now))
+        # An expired route fails closed even with a good proof.
+        refusal(self, lambda: verify_session_proof(
+            v.request, v.accepted, v.verse_id, v.route, v.trust, v.certificate.expires_at_unix_milliseconds))
+
+
+if __name__ == "__main__":
+    unittest.main()

packages/cultmesh-py/tests/test_cultmesh.py

@@ -5048,17 +5048,16 @@ class CultMeshTests(unittest.TestCase):
         finally:
             server.stop()
 
-        self.assertEqual(unsupported["messageId"], "bad-schema")
         self.assertEqual(unsupported["code"], "unsupported_schema_version")
-        self.assertEqual(unsupported["details"]["schemaVersion"], "cultnet.nope.v0")
-        self.assertIn("Unsupported CultNet message schema", unsupported["error"])
+        self.assertEqual(unsupported["details"]["field"], "schemaVersion")
+        self.assertEqual(unsupported["details"]["value"], "cultnet.nope.v0")
+        self.assertIn("unsupported_schema_version", unsupported["error"])
         self.assertEqual(malformed_put["messageId"], "bad-put")
         self.assertEqual(malformed_put["code"], "malformed_document_put")
         self.assertEqual(malformed_delete["messageId"], "bad-delete")
         self.assertEqual(malformed_delete["code"], "malformed_document_delete")
-        self.assertEqual(unsupported_v1["messageId"], "bad-v1-selection")
         self.assertEqual(unsupported_v1["code"], "unsupported_schema_version")
-        self.assertEqual(unsupported_v1["details"]["schemaVersion"], "cultnet.snapshot_request.v1")
+        self.assertEqual(unsupported_v1["details"]["value"], "cultnet.snapshot_request.v1")
 
     def test_cultmesh_authority_lease_requires_live_matching_lease(self) -> None:
         peer = CultMeshPeerCard(

packages/cultmesh-rs/Cargo.lock

@@ -52,12 +52,27 @@ version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 
+[[package]]
+name = "ar_archive_writer"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73cd58deff2140a0a8eae87e417bd01db68a33e148aa93d1e8cd837e55e312b6"
+dependencies = [
+ "object",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
+[[package]]
+name = "base16ct"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c7f02d4ea65f2c1853089ffd8d2787bdbc63de2f0d29dedbcf8ccdfa0ccd4cf"
+
 [[package]]
 name = "base64"
 version = "0.22.1"
@@ -152,6 +167,18 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "crypto-bigint"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0dc92fb57ca44df6db8059111ab3af99a63d5d0f8375d9972e319a379c6bab76"
+dependencies = [
+ "generic-array",
+ "rand_core 0.6.4",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -174,7 +201,7 @@ dependencies = [
 
 [[package]]
 name = "cultcache-rs"
-version = "0.2.0"
+version = "0.3.1"
 dependencies = [
  "anyhow",
  "chrono",
@@ -185,13 +212,15 @@ dependencies = [
  "serde",
  "serde_bytes",
  "serde_json",
+ "serde_stacker",
+ "stacker",
  "uuid",
  "windows-sys 0.59.0",
 ]
 
 [[package]]
 name = "cultcache-rs-derive"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -203,17 +232,20 @@ name = "cultmesh-rs"
 version = "0.2.0"
 dependencies = [
  "anyhow",
+ "base64",
  "cultcache-rs",
  "cultnet-rs",
+ "p256",
  "pretty_assertions",
  "rmp-serde",
  "serde",
+ "serde_json",
  "tempfile",
 ]
 
 [[package]]
 name = "cultnet-rs"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "aes-gcm",
  "anyhow",
@@ -221,7 +253,9 @@ dependencies = [
  "chrono",
  "cultcache-rs",
  "ed25519-dalek",
+ "fs2",
  "hmac",
+ "libc",
  "rand",
  "rmp-serde",
  "rmpv",
@@ -285,10 +319,25 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
  "block-buffer",
+ "const-oid",
  "crypto-common",
  "subtle",
 ]
 
+[[package]]
+name = "ecdsa"
+version = "0.16.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee27f32b5c5292967d2d4a9d7f1e0b0aed2c15daded5a60300e4abb9d8020bca"
+dependencies = [
+ "der",
+ "digest",
+ "elliptic-curve",
+ "rfc6979",
+ "signature",
+ "spki",
+]
+
 [[package]]
 name = "ed25519"
 version = "2.2.3"
@@ -313,6 +362,25 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "elliptic-curve"
+version = "0.13.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5e6043086bf7973472e0c7dff2142ea0b680d30e18d9cc40f267efbf222bd47"
+dependencies = [
+ "base16ct",
+ "crypto-bigint",
+ "digest",
+ "ff",
+ "generic-array",
+ "group",
+ "pkcs8",
+ "rand_core 0.6.4",
+ "sec1",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "errno"
 version = "0.3.14"
@@ -329,6 +397,16 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
+[[package]]
+name = "ff"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0b50bfb653653f9ca9095b427bed08ab8d75a137839d9ad64eb11810d5b6393"
+dependencies = [
+ "rand_core 0.6.4",
+ "subtle",
+]
+
 [[package]]
 name = "fiat-crypto"
 version = "0.2.9"
@@ -383,6 +461,7 @@ checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
 dependencies = [
  "typenum",
  "version_check",
+ "zeroize",
 ]
 
 [[package]]
@@ -429,6 +508,17 @@ dependencies = [
  "polyval",
 ]
 
+[[package]]
+name = "group"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0f9ef7462f7c099f518d754361858f86d8a07af53ba9af0fe635bbccb151a63"
+dependencies = [
+ "ff",
+ "rand_core 0.6.4",
+ "subtle",
+]
+
 [[package]]
 name = "hmac"
 version = "0.12.1"
@@ -521,6 +611,15 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "object"
+version = "0.39.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e5a6c098c7a3b6547378093f5cc30bc54fd361ce711e05293a5cc589562739b"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -533,6 +632,18 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
+[[package]]
+name = "p256"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9863ad85fa8f4460f9c48cb909d38a0d689dba1f6f6988a5e3e0d31071bcd4b"
+dependencies = [
+ "ecdsa",
+ "elliptic-curve",
+ "primeorder",
+ "sha2",
+]
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -580,6 +691,15 @@ dependencies = [
  "yansi",
 ]
 
+[[package]]
+name = "primeorder"
+version = "0.13.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "353e1ca18966c16d9deb1c69278edbc5f194139612772bd9537af60ac231e1e6"
+dependencies = [
+ "elliptic-curve",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -589,6 +709,16 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "psm"
+version = "0.1.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4dcd034599e63b970727f70d79e02d62390a4a84f7c6b827c27c46d5ac3fa622"
+dependencies = [
+ "ar_archive_writer",
+ "cc",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.47"
@@ -657,6 +787,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "rfc6979"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dd2a808d456c4a54e300a23e9f5a67e122c3024119acbfd73e3bf664491cb2"
+dependencies = [
+ "hmac",
+ "subtle",
+]
+
 [[package]]
 name = "rmp"
 version = "0.8.15"
@@ -715,6 +855,20 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
+[[package]]
+name = "sec1"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3e97a565f76233a6003f9f5c54be1d9c5bdfa3eccfb189469f11ec4901c47dc"
+dependencies = [
+ "base16ct",
+ "der",
+ "generic-array",
+ "pkcs8",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -774,6 +928,17 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "serde_stacker"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4936375d50c4be7eff22293a9344f8e46f323ed2b3c243e52f89138d9bb0f4a"
+dependencies = [
+ "serde",
+ "serde_core",
+ "stacker",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -797,6 +962,7 @@ version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
+ "digest",
  "rand_core 0.6.4",
 ]
 
@@ -826,6 +992,19 @@ dependencies = [
  "der",
 ]
 
+[[package]]
+name = "stacker"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "707f49d46706bacf8a2b00d51dace3f9de527c13eec3778f570c411f89e69967"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "libc",
+ "psm",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "subtle"
 version = "2.6.1"

packages/cultmesh-rs/Cargo.toml

@@ -13,9 +13,12 @@ path = "src/lib.rs"
 anyhow = "1"
 cultcache-rs = { path = "../cultcache-rs" }
 cultnet-rs = { path = "../cultnet-rs" }
+base64 = "0.22"
+p256 = { version = "0.13", default-features = false, features = ["ecdsa", "std"] }
 serde = { version = "1", features = ["derive"] }
 
 [dev-dependencies]
 pretty_assertions = "1.4.1"
 rmp-serde = "1"
+serde_json = "1"
 tempfile = "3"

packages/cultmesh-rs/src/authority.rs

@@ -0,0 +1,424 @@
+//! CultMesh authority route verification.
+//!
+//! Port of `src/GameCult.Mesh/CultMeshAuthorityProof.cs` (the reference) and of
+//! the route constructors in `CultMeshVerse.cs`. Rule for rule, in the same
+//! order, the same input yields the same refusal text as
+//! `CultMeshAuthorityTrustPolicy.Verify`: unsigned, channel protection, root
+//! lookup, validity window, signature.
+//!
+//! Shared vectors: `contracts/cultmesh/authority-route-vectors.json` (C# written).
+
+use base64::alphabet::STANDARD as STANDARD_ALPHABET;
+use base64::engine::{DecodePaddingMode, GeneralPurpose, GeneralPurposeConfig};
+use base64::Engine;
+use p256::ecdsa::signature::Verifier;
+use p256::ecdsa::{Signature, VerifyingKey};
+use std::collections::BTreeMap;
+use std::fmt;
+
+const ROUTE_DOMAIN: &str = "gamecult.cultmesh.route-certificate.v1";
+const SESSION_DOMAIN: &str = "gamecult.cultmesh.session-proof.v1";
+
+// `Convert.FromBase64String`: standard alphabet, padded, tolerant of trailing bits.
+const DOTNET_BASE64: GeneralPurpose = GeneralPurpose::new(
+    &STANDARD_ALPHABET,
+    GeneralPurposeConfig::new()
+        .with_decode_padding_mode(DecodePaddingMode::RequireCanonical)
+        .with_decode_allow_trailing_bits(true),
+);
+
+fn base64_decode(value: &str) -> Option<Vec<u8>> {
+    let stripped: String = value.chars().filter(|c| !matches!(c, ' ' | '\t' | '\r' | '\n')).collect();
+    DOTNET_BASE64.decode(stripped).ok()
+}
+
+/// .NET `char.IsWhiteSpace` is the Unicode White_Space property, as is `char::is_whitespace`.
+fn trim(value: &str) -> &str {
+    value.trim_matches(char::is_whitespace)
+}
+
+fn is_blank(value: &str) -> bool {
+    trim(value).is_empty()
+}
+
+fn require(value: &str, name: &str) -> Result<String, String> {
+    if is_blank(value) {
+        Err(format!("Value must be non-empty. (Parameter '{name}')"))
+    } else {
+        Ok(trim(value).to_owned())
+    }
+}
+
+/// A route or proof the consumer's trust policy refuses. Mirrors
+/// `CultMeshSessionFailure` with reason `Authentication`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthorityRouteRefusal {
+    pub message: String,
+    pub endpoint: String,
+}
+
+impl AuthorityRouteRefusal {
+    pub const REASON: &'static str = "authentication";
+}
+
+impl fmt::Display for AuthorityRouteRefusal {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.message)
+    }
+}
+
+impl std::error::Error for AuthorityRouteRefusal {}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct P256PublicKey {
+    pub key_id: String,
+    pub x: String,
+    pub y: String,
+}
+
+impl P256PublicKey {
+    pub fn new(key_id: &str, x: &str, y: &str) -> Result<Self, String> {
+        let key = Self {
+            key_id: require(key_id, "keyId")?,
+            x: require(x, "x")?,
+            y: require(y, "y")?,
+        };
+        for (name, value) in [("x", &key.x), ("y", &key.y)] {
+            if base64_decode(value).is_none() {
+                return Err(format!("Coordinate must be base64. (Parameter '{name}')"));
+            }
+        }
+        Ok(key)
+    }
+
+    /// IEEE P1363 (r || s) ECDSA-SHA256 verification; false on any malformation.
+    pub fn verify(&self, payload: &[u8], signature_base64: &str) -> bool {
+        let (Some(x), Some(y), Some(signature)) = (
+            base64_decode(&self.x),
+            base64_decode(&self.y),
+            base64_decode(signature_base64),
+        ) else {
+            return false;
+        };
+        if x.len() != 32 || y.len() != 32 || signature.len() != 64 {
+            return false;
+        }
+        let mut sec1 = Vec::with_capacity(65);
+        sec1.push(4);
+        sec1.extend_from_slice(&x);
+        sec1.extend_from_slice(&y);
+        let (Ok(key), Ok(signature)) = (
+            VerifyingKey::from_sec1_bytes(&sec1),
+            Signature::from_slice(&signature),
+        ) else {
+            return false;
+        };
+        key.verify(payload, &signature).is_ok()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RouteCertificate {
+    pub provider_key: P256PublicKey,
+    pub odin_key_id: String,
+    pub issued_at_unix_milliseconds: i64,
+    pub expires_at_unix_milliseconds: i64,
+    pub signature: String,
+}
+
+impl RouteCertificate {
+    pub fn new(
+        provider_key: P256PublicKey,
+        odin_key_id: &str,
+        issued_at_unix_milliseconds: i64,
+        expires_at_unix_milliseconds: i64,
+        signature: &str,
+    ) -> Result<Self, String> {
+        if is_blank(odin_key_id) {
+            return Err("Odin key identity is required. (Parameter 'odinKeyId')".into());
+        }
+        if issued_at_unix_milliseconds < 0 {
+            return Err("issuedAtUnixMilliseconds must not be negative.".into());
+        }
+        if expires_at_unix_milliseconds <= issued_at_unix_milliseconds {
+            return Err("expiresAtUnixMilliseconds must be after issuedAtUnixMilliseconds.".into());
+        }
+        Ok(Self {
+            provider_key,
+            odin_key_id: trim(odin_key_id).to_owned(),
+            issued_at_unix_milliseconds,
+            expires_at_unix_milliseconds,
+            signature: trim(signature).to_owned(),
+        })
+    }
+}
+
+/// `CultMeshAuthorityRoute`: construction cleans every field as the C# does.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthorityRoute {
+    pub authority_runtime_id: String,
+    pub endpoint: String,
+    pub protocol_ids: Vec<String>,
+    pub priority: i32,
+    pub generation: String,
+    pub certificate: Option<RouteCertificate>,
+}
+
+impl AuthorityRoute {
+    pub fn new(
+        authority_runtime_id: &str,
+        endpoint: &str,
+        protocol_ids: &[&str],
+        priority: i32,
+        generation: Option<&str>,
+        certificate: Option<RouteCertificate>,
+    ) -> Result<Self, String> {
+        let authority_runtime_id = require(authority_runtime_id, "authorityRuntimeId")?;
+        let endpoint = require(endpoint, "endpoint")?;
+        if priority < 0 {
+            return Err("priority must not be negative.".into());
+        }
+        let mut protocols: Vec<String> = protocol_ids
+            .iter()
+            .filter(|value| !is_blank(value))
+            .map(|value| trim(value).to_owned())
+            .collect();
+        // StringComparer.Ordinal is UTF-16 code-unit order.
+        protocols.sort_by_key(|value| value.encode_utf16().collect::<Vec<u16>>());
+        protocols.dedup();
+        let generation = match generation {
+            Some(value) if !is_blank(value) => trim(value).to_owned(),
+            _ => format!("{authority_runtime_id}@{endpoint}"),
+        };
+        Ok(Self {
+            authority_runtime_id,
+            endpoint,
+            protocol_ids: protocols,
+            priority,
+            generation,
+            certificate,
+        })
+    }
+}
+
+/// The fields of `CultMeshSessionOpenMessage` the session proof covers.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct SessionOpen {
+    pub client_nonce: String,
+    pub message_id: String,
+    pub source_runtime_id: String,
+    pub verse_id: String,
+    pub authority_runtime_id: String,
+    pub protocol_id: String,
+    pub route_generation: String,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct SessionAccepted {
+    pub client_nonce: String,
+    pub provider_key_id: String,
+    pub provider_signature: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TrustMode {
+    AuthenticatedRemote,
+    LocalDevelopment,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VerifiedRoute {
+    pub route: AuthorityRoute,
+    pub provider_key: Option<P256PublicKey>,
+    pub is_local_development: bool,
+}
+
+pub fn canonical_fields(values: &[&str]) -> Vec<u8> {
+    let mut out = Vec::new();
+    for value in values {
+        out.extend_from_slice(&(value.len() as u32).to_be_bytes());
+        out.extend_from_slice(value.as_bytes());
+    }
+    out
+}
+
+pub fn canonical_route(verse_id: &str, route: &AuthorityRoute) -> Result<Vec<u8>, String> {
+    let certificate = route.certificate.as_ref().ok_or("Route certificate is required.")?;
+    let protocols = route.protocol_ids.join("\u{1f}");
+    let priority = route.priority.to_string();
+    let issued = certificate.issued_at_unix_milliseconds.to_string();
+    let expires = certificate.expires_at_unix_milliseconds.to_string();
+    Ok(canonical_fields(&[
+        ROUTE_DOMAIN,
+        verse_id,
+        &route.authority_runtime_id,
+        &route.endpoint,
+        &protocols,
+        &priority,
+        &route.generation,
+        &certificate.provider_key.key_id,
+        &certificate.provider_key.x,
+        &certificate.provider_key.y,
+        &certificate.odin_key_id,
+        &issued,
+        &expires,
+    ]))
+}
+
+pub fn canonical_session(request: &SessionOpen, endpoint: &str) -> Vec<u8> {
+    canonical_fields(&[
+        SESSION_DOMAIN,
+        &request.client_nonce,
+        &request.message_id,
+        &request.source_runtime_id,
+        &request.verse_id,
+        &request.authority_runtime_id,
+        &request.protocol_id,
+        endpoint,
+        &request.route_generation,
+    ])
+}
+
+/// `(scheme, lowercase host)`, or `None` where `System.Uri` refuses the spelling.
+/// A lenient parse could call a refused endpoint loopback or protected, so the
+/// shape rule is the same strict one the TypeScript port applies.
+fn split_endpoint(value: &str) -> Option<(String, String)> {
+    let raw = value.trim_matches(|c: char| c <= ' ');
+    if raw.contains('\\') {
+        return None;
+    }
+    let (scheme, rest) = raw.split_once("://")?;
+    let mut scheme_chars = scheme.chars();
+    if !scheme_chars.next()?.is_ascii_alphabetic()
+        || !scheme_chars.all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.'))
+    {
+        return None;
+    }
+    let authority = &rest[..rest.find(['/', '?', '#']).unwrap_or(rest.len())];
+    if authority.is_empty() {
+        return None;
+    }
+    let after_user = &authority[authority.rfind('@').map_or(0, |i| i + 1)..];
+    let host = if after_user.starts_with('[') {
+        &after_user[..after_user.find(']').map_or(after_user.len(), |i| i + 1)]
+    } else {
+        after_user.split(':').next().unwrap_or("")
+    };
+    if host.is_empty() || host.chars().any(|c| !('\u{21}'..='\u{7e}').contains(&c)) || host.ends_with('.') {
+        return None;
+    }
+    Some((
+        scheme.to_ascii_lowercase(),
+        host.trim_matches(['[', ']']).to_ascii_lowercase(),
+    ))
+}
+
+pub fn is_loopback_endpoint(endpoint: &str) -> bool {
+    let Some((_, host)) = split_endpoint(endpoint) else {
+        return false;
+    };
+    let octets: Vec<&str> = host.split('.').collect();
+    matches!(host.as_str(), "localhost" | "loopback" | "::1" | "::ffff:127.0.0.1")
+        || (octets.len() == 4
+            && octets[0] == "127"
+            && octets[1..].iter().all(|o| (1..=3).contains(&o.len()) && o.bytes().all(|b| b.is_ascii_digit())))
+}
+
+pub fn is_protected_endpoint(endpoint: &str) -> bool {
+    split_endpoint(endpoint)
+        .is_some_and(|(scheme, _)| scheme == "wss" || scheme == "https" || scheme.contains("quic"))
+}
+
+/// Consumer-owned policy. Fails closed unless a route is valid under it.
+pub struct AuthorityTrustPolicy {
+    mode: TrustMode,
+    roots: BTreeMap<String, P256PublicKey>,
+}
+
+impl AuthorityTrustPolicy {
+    pub fn new(mode: TrustMode, odin_roots: Vec<P256PublicKey>) -> Result<Self, String> {
+        let mut roots = BTreeMap::new();
+        for root in odin_roots {
+            let key_id = root.key_id.clone();
+            if roots.insert(key_id.clone(), root).is_some() {
+                return Err(format!(
+                    "Odin root key id '{key_id}' is listed more than once in the trust policy."
+                ));
+            }
+        }
+        Ok(Self { mode, roots })
+    }
+
+    pub fn validate(&self, verse_id: &str, route: &AuthorityRoute, now_unix_milliseconds: i64) -> Result<(), AuthorityRouteRefusal> {
+        self.verify(verse_id, route, now_unix_milliseconds).map(|_| ())
+    }
+
+    pub fn verify(&self, verse_id: &str, route: &AuthorityRoute, now_unix_milliseconds: i64) -> Result<VerifiedRoute, AuthorityRouteRefusal> {
+        let refuse = |message: &str| AuthorityRouteRefusal {
+            message: message.to_owned(),
+            endpoint: route.endpoint.clone(),
+        };
+        let local = self.mode == TrustMode::LocalDevelopment && is_loopback_endpoint(&route.endpoint);
+        let certificate = match &route.certificate {
+            Some(certificate) if !is_blank(&certificate.signature) => certificate,
+            _ if local => {
+                return Ok(VerifiedRoute { route: route.clone(), provider_key: None, is_local_development: true });
+            }
+            _ => return Err(refuse("Remote CultMesh routes require an Odin-signed authority certificate.")),
+        };
+        if !is_protected_endpoint(&route.endpoint) && !local {
+            return Err(refuse("Authenticated remote CultMesh routes require TLS or QUIC channel protection."));
+        }
+        let Some(root) = self.roots.get(&certificate.odin_key_id) else {
+            return Err(refuse(&format!(
+                "Odin key '{}' is not trusted by this consumer.",
+                certificate.odin_key_id
+            )));
+        };
+        if now_unix_milliseconds < certificate.issued_at_unix_milliseconds
+            || now_unix_milliseconds >= certificate.expires_at_unix_milliseconds
+        {
+            return Err(refuse("The Odin route certificate is not currently valid."));
+        }
+        let Some(signature) = base64_decode(&certificate.signature) else {
+            return Err(refuse("The Odin route signature is not base64."));
+        };
+        if signature.len() != 64 {
+            return Err(refuse("The Odin route signature is not IEEE P1363 P-256."));
+        }
+        let canonical = canonical_route(verse_id, route).map_err(|message| refuse(&message))?;
+        if !root.verify(&canonical, &certificate.signature) {
+            return Err(refuse("The Odin route certificate signature is invalid."));
+        }
+        Ok(VerifiedRoute {
+            route: route.clone(),
+            provider_key: Some(certificate.provider_key.clone()),
+            is_local_development: false,
+        })
+    }
+}
+
+/// Verifies the Odin route certificate (refusing) and the provider nonce proof.
+pub fn verify_session_proof(
+    request: &SessionOpen,
+    response: &SessionAccepted,
+    verse_id: &str,
+    route: &AuthorityRoute,
+    trust: &AuthorityTrustPolicy,
+    now_unix_milliseconds: i64,
+) -> Result<bool, AuthorityRouteRefusal> {
+    let verified = trust.verify(verse_id, route, now_unix_milliseconds)?;
+    if verified.is_local_development {
+        return Ok(true);
+    }
+    let Some(key) = verified.provider_key else {
+        return Ok(false);
+    };
+    if response.provider_key_id != key.key_id
+        || response.client_nonce != request.client_nonce
+        || is_blank(&response.provider_signature)
+    {
+        return Ok(false);
+    }
+    Ok(key.verify(&canonical_session(request, &route.endpoint), &response.provider_signature))
+}

packages/cultmesh-rs/src/lib.rs

@@ -25,6 +25,7 @@ use std::time::Duration;
 use std::time::Instant;
 
 mod rudp_document_server;
+pub mod authority;
 
 pub use rudp_document_server::*;
 

packages/cultmesh-rs/tests/authority_route_vectors.rs

@@ -0,0 +1,261 @@
+//! Judges `contracts/cultmesh/authority-route-vectors*.json` in Rust.
+//!
+//! `authority-route-vectors.json` is written by the C# reference (its signatures
+//! are captured C# bytes); the `.ts-signed.json` file is signed by TypeScript
+//! over awkward inputs. Each negative case fails when the matching check is
+//! removed from `cultmesh_rs::authority`.
+
+use base64::Engine;
+use base64::engine::general_purpose::STANDARD;
+use cultmesh_rs::authority::*;
+use p256::ecdsa::Signature;
+use serde_json::Value;
+use std::path::PathBuf;
+
+struct Vector {
+    now: i64,
+    root: P256PublicKey,
+    verse_id: String,
+    route: AuthorityRoute,
+    request: SessionOpen,
+    accepted: SessionAccepted,
+    trust: AuthorityTrustPolicy,
+}
+
+fn s<'a>(value: &'a Value, key: &str) -> &'a str {
+    value[key].as_str().unwrap_or_else(|| panic!("missing string {key}"))
+}
+
+fn key(value: &Value) -> P256PublicKey {
+    P256PublicKey::new(s(value, "keyId"), s(value, "x"), s(value, "y")).unwrap()
+}
+
+fn load(name: &str) -> Vector {
+    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("../../contracts/cultmesh")
+        .join(name);
+    let doc: Value = serde_json::from_str(&std::fs::read_to_string(path).unwrap()).unwrap();
+    let r = &doc["route"];
+    let c = &r["certificate"];
+    let certificate = RouteCertificate::new(
+        key(&c["providerKey"]),
+        s(c, "odinKeyId"),
+        c["issuedAtUnixMilliseconds"].as_i64().unwrap(),
+        c["expiresAtUnixMilliseconds"].as_i64().unwrap(),
+        s(c, "signature"),
+    )
+    .unwrap();
+    let protocols: Vec<&str> = r["protocolIds"].as_array().unwrap().iter().map(|v| v.as_str().unwrap()).collect();
+    let route = AuthorityRoute::new(
+        s(r, "authorityRuntimeId"),
+        s(r, "endpoint"),
+        &protocols,
+        r["priority"].as_i64().unwrap() as i32,
+        Some(s(r, "generation")),
+        Some(certificate),
+    )
+    .unwrap();
+    let p = &doc["sessionProof"];
+    let q = &p["request"];
+    let root = key(&doc["odinRoot"]);
+    Vector {
+        now: doc["nowUnixMilliseconds"].as_i64().unwrap(),
+        verse_id: s(r, "verseId").to_owned(),
+        route,
+        request: SessionOpen {
+            client_nonce: s(q, "clientNonce").into(),
+            message_id: s(q, "messageId").into(),
+            source_runtime_id: s(q, "sourceRuntimeId").into(),
+            verse_id: s(q, "verseId").into(),
+            authority_runtime_id: s(q, "authorityRuntimeId").into(),
+            protocol_id: s(q, "protocolId").into(),
+            route_generation: s(q, "routeGeneration").into(),
+        },
+        accepted: SessionAccepted {
+            client_nonce: s(q, "clientNonce").into(),
+            provider_key_id: s(p, "providerKeyId").into(),
+            provider_signature: s(p, "providerSignature").into(),
+        },
+        trust: AuthorityTrustPolicy::new(TrustMode::AuthenticatedRemote, vec![root.clone()]).unwrap(),
+        root,
+    }
+}
+
+impl Vector {
+    fn certificate(&self) -> &RouteCertificate {
+        self.route.certificate.as_ref().unwrap()
+    }
+    fn with_certificate(&self, edit: impl FnOnce(&mut RouteCertificate)) -> AuthorityRoute {
+        let mut route = self.route.clone();
+        edit(route.certificate.as_mut().unwrap());
+        route
+    }
+    fn refusal(&self, route: &AuthorityRoute, now: i64) -> String {
+        let error = self.trust.validate(&self.verse_id, route, now).expect_err("route must be refused");
+        assert_eq!(AuthorityRouteRefusal::REASON, "authentication");
+        assert_eq!(route.endpoint, error.endpoint);
+        error.message
+    }
+    fn proof(&self, request: &SessionOpen, accepted: &SessionAccepted) -> bool {
+        verify_session_proof(request, accepted, &self.verse_id, &self.route, &self.trust, self.now).unwrap()
+    }
+}
+
+const INVALID: &str = "The Odin route certificate signature is invalid.";
+
+#[test]
+fn cs_written_vector_verifies_route_and_session_proof() {
+    let v = load("authority-route-vectors.json");
+    v.trust.validate(&v.verse_id, &v.route, v.now).unwrap();
+    assert!(v.proof(&v.request, &v.accepted));
+}
+
+#[test]
+fn ts_signed_vector_verifies_and_tamper_is_refused() {
+    let v = load("authority-route-vectors.ts-signed.json");
+    v.trust.validate(&v.verse_id, &v.route, v.now).unwrap();
+    assert!(v.proof(&v.request, &v.accepted));
+    let mut tampered = v.route.clone();
+    tampered.priority += 1;
+    assert_eq!(INVALID, v.refusal(&tampered, v.now));
+}
+
+#[test]
+fn canonical_route_is_length_prefixed_and_sorted() {
+    let v = load("authority-route-vectors.json");
+    let bytes = canonical_route(&v.verse_id, &v.route).unwrap();
+    assert!(bytes.starts_with(b"\x00\x00\x00\x26gamecult.cultmesh.route-certificate.v1\x00\x00\x00\x08aetheria"));
+    let needle = b"cultmesh.content.v1\x1fcultmesh.documents.v1";
+    assert!(bytes.windows(needle.len()).any(|w| w == needle));
+}
+
+#[test]
+fn tampered_payload_fields_are_refused() {
+    let v = load("authority-route-vectors.json");
+    let edits: Vec<Box<dyn Fn(&mut AuthorityRoute)>> = vec![
+        Box::new(|r| r.priority = 8),
+        Box::new(|r| r.endpoint = "wss://evil.example/mesh".into()),
+        Box::new(|r| r.protocol_ids = vec!["cultmesh.documents.v1".into()]),
+        Box::new(|r| r.generation = "other".into()),
+        Box::new(|r| r.certificate.as_mut().unwrap().expires_at_unix_milliseconds += 1),
+    ];
+    for edit in edits {
+        let mut route = v.route.clone();
+        edit(&mut route);
+        assert_eq!(INVALID, v.refusal(&route, v.now));
+    }
+    let error = v.trust.validate("other-verse", &v.route, v.now).unwrap_err();
+    assert_eq!(INVALID, error.message);
+}
+
+#[test]
+fn wrong_root_key_is_refused() {
+    let v = load("authority-route-vectors.json");
+    // The provider's key is a real P-256 key that did not sign this route.
+    let provider = &v.certificate().provider_key;
+    let impostor = P256PublicKey::new(&v.root.key_id, &provider.x, &provider.y).unwrap();
+    let trust = AuthorityTrustPolicy::new(TrustMode::AuthenticatedRemote, vec![impostor]).unwrap();
+    assert_eq!(INVALID, trust.validate(&v.verse_id, &v.route, v.now).unwrap_err().message);
+}
+
+#[test]
+fn untrusted_odin_key_id_is_refused() {
+    let v = load("authority-route-vectors.json");
+    let other = P256PublicKey::new("someone-else", &v.root.x, &v.root.y).unwrap();
+    let trust = AuthorityTrustPolicy::new(TrustMode::AuthenticatedRemote, vec![other]).unwrap();
+    assert_eq!(
+        "Odin key 'odin-vector' is not trusted by this consumer.",
+        trust.validate(&v.verse_id, &v.route, v.now).unwrap_err().message
+    );
+}
+
+#[test]
+fn expired_and_not_yet_valid_are_refused() {
+    let v = load("authority-route-vectors.json");
+    let window = "The Odin route certificate is not currently valid.";
+    let (issued, expires) = (v.certificate().issued_at_unix_milliseconds, v.certificate().expires_at_unix_milliseconds);
+    v.trust.validate(&v.verse_id, &v.route, expires - 1).unwrap();
+    v.trust.validate(&v.verse_id, &v.route, issued).unwrap();
+    assert_eq!(window, v.refusal(&v.route, expires));
+    assert_eq!(window, v.refusal(&v.route, issued - 1));
+}
+
+#[test]
+fn unsigned_and_unprotected_routes_are_refused() {
+    let v = load("authority-route-vectors.json");
+    let unsigned_message = "Remote CultMesh routes require an Odin-signed authority certificate.";
+    let mut unsigned = v.route.clone();
+    unsigned.certificate = None;
+    assert_eq!(unsigned_message, v.refusal(&unsigned, v.now));
+    let blank = v.with_certificate(|c| c.signature = "  ".into());
+    assert_eq!(unsigned_message, v.refusal(&blank, v.now));
+    let mut plain = v.route.clone();
+    plain.endpoint = "ws://provider.example/mesh".into();
+    assert_eq!(
+        "Authenticated remote CultMesh routes require TLS or QUIC channel protection.",
+        v.refusal(&plain, v.now)
+    );
+}
+
+#[test]
+fn local_development_admits_only_unsigned_loopback() {
+    let v = load("authority-route-vectors.json");
+    let dev = AuthorityTrustPolicy::new(TrustMode::LocalDevelopment, vec![]).unwrap();
+    let route = |endpoint: &str| AuthorityRoute::new("a", endpoint, &[], 0, None, None).unwrap();
+    let loopback = route("ws://127.0.0.1:9/mesh");
+    dev.validate(&v.verse_id, &loopback, v.now).unwrap();
+    assert!(verify_session_proof(&v.request, &v.accepted, &v.verse_id, &loopback, &dev, v.now).unwrap());
+    for endpoint in ["ws://provider.example/mesh", "ws://127.0.0.1./mesh", "ws:127.0.0.1"] {
+        assert!(dev.validate(&v.verse_id, &route(endpoint), v.now).is_err(), "{endpoint}");
+    }
+    let remote = AuthorityTrustPolicy::new(TrustMode::AuthenticatedRemote, vec![]).unwrap();
+    assert!(remote.validate(&v.verse_id, &loopback, v.now).is_err());
+}
+
+#[test]
+fn malformed_signatures_get_their_own_refusals() {
+    let v = load("authority-route-vectors.json");
+    let not_base64 = v.with_certificate(|c| c.signature = "!!not base64!!".into());
+    assert_eq!("The Odin route signature is not base64.", v.refusal(&not_base64, v.now));
+    let short = v.with_certificate(|c| c.signature = STANDARD.encode([b'x'; 63]));
+    assert_eq!("The Odin route signature is not IEEE P1363 P-256.", v.refusal(&short, v.now));
+}
+
+#[test]
+fn high_s_signature_verifies_as_it_does_in_dotnet() {
+    let v = load("authority-route-vectors.json");
+    let raw = STANDARD.decode(&v.certificate().signature).unwrap();
+    let signature = Signature::from_slice(&raw).unwrap();
+    let flipped = Signature::from_scalars(*signature.r().as_ref(), -*signature.s().as_ref()).unwrap();
+    let high = v.with_certificate(|c| c.signature = STANDARD.encode(flipped.to_bytes()));
+    v.trust.validate(&v.verse_id, &high, v.now).unwrap();
+}
+
+#[test]
+fn session_proof_rejects_replay_wrong_key_and_forgery() {
+    let v = load("authority-route-vectors.json");
+    let mut replayed = v.request.clone();
+    replayed.client_nonce = "replayed".into();
+    let mut accepted = v.accepted.clone();
+    accepted.client_nonce = "replayed".into();
+    assert!(!v.proof(&replayed, &accepted));
+    let mut wrong_id = v.accepted.clone();
+    wrong_id.provider_key_id = "other".into();
+    assert!(!v.proof(&v.request, &wrong_id));
+    let mut wrong_nonce = v.accepted.clone();
+    wrong_nonce.client_nonce = "other".into();
+    assert!(!v.proof(&v.request, &wrong_nonce));
+    let mut empty = v.accepted.clone();
+    empty.provider_signature = String::new();
+    assert!(!v.proof(&v.request, &empty));
+    let mut raw = STANDARD.decode(&v.accepted.provider_signature).unwrap();
+    raw[0] ^= 1;
+    let mut forged = v.accepted.clone();
+    forged.provider_signature = STANDARD.encode(raw);
+    assert!(!v.proof(&v.request, &forged));
+    let mut moved = v.request.clone();
+    moved.protocol_id = "cultmesh.content.v1".into();
+    assert!(!v.proof(&moved, &v.accepted));
+    let expires = v.certificate().expires_at_unix_milliseconds;
+    assert!(verify_session_proof(&v.request, &v.accepted, &v.verse_id, &v.route, &v.trust, expires).is_err());
+}

packages/cultmesh-ts/CHANGELOG.md

@@ -1,12 +1,13 @@
 # Changelog
 
-All notable changes to `cultmesh-ts` are recorded here, following
+All notable changes to `@gamecult/cultmesh-ts` are recorded here, following
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## Unreleased
 
 ### Breaking
 
+- The package is renamed `cultmesh-ts` to `@gamecult/cultmesh-ts` (the repo already scopes `@gamecult/cultcache-ts`), so the unscoped name cannot be claimed by someone else. Import from `@gamecult/cultmesh-ts` and its subpaths; the API is unchanged. Depends on `@gamecult/cultnet-ts`.
 - `asSchemaAlias` is removed from `CultMeshDocumentHandle`, `CultMeshCollectionHandle` and their bound forms. Read the handle by the schema you mean.
 - `CultMeshDocumentCatalog` (`document`, `tryDocument`, `latest`, `replace`, `submitPrediction`, `authoritativeWriter`, `predictionWriter`, `watch`) and `CultMeshCollectionCatalog` (`collection`, `tryCollection`, `latest`, `watchChanges`) take `<TDocument = never, TSchema>` and yield `CultMeshCatalogValue<TDocument, TSchema>`: an explicit type argument wins, a CultCache document definition names its own value type, and a bare schema descriptor yields `unknown`. A value type is no longer inferred from a value or an expected result. The `parse` option is removed from these calls, and a lookup by type answers with that type's handle or none, not an alias of a compatible schema.
 - Adding a document or collection to a catalog under a schema id or schema name another type already holds is refused with `SchemaConflictError`.

packages/cultmesh-ts/README.md

@@ -1,6 +1,6 @@
 # CultMesh TS
 
-`cultmesh-ts` is the TypeScript projection of CultMesh contracts for local
+`@gamecult/cultmesh-ts` is the TypeScript projection of CultMesh contracts for local
 tools and browser-adjacent runtimes. The C# `GameCult.Mesh` package owns the
 native CultMesh stream implementation used by Mimir and Fensalir; this package
 mirrors the typed declaration and negotiation shapes without owning the hot
@@ -21,7 +21,7 @@ WASM route. Runtime code can ask for a whole XY rect, then adapt it to the
 current wire schema at the edge:
 
 ```ts
-import { CultMesh } from "cultmesh-ts";
+import { CultMesh } from "@gamecult/cultmesh-ts";
 
 const viewport = CultMesh.rectFromBounds(-500, -300, 500, 300);
 const request = CultMesh.viewportRequest(viewport, [3, 8]);
@@ -215,7 +215,7 @@ const stopFeed = viewportFeed.watch(request, "browser-starfire", render);
 ```
 
 ```ts
-import { CultMesh } from "cultmesh-ts";
+import { CultMesh } from "@gamecult/cultmesh-ts";
 
 const verses = CultMesh.createVerseCatalog<{ verseId: string; label: string }>();
 const stopWatching = verses.watch((verse) => {
@@ -274,7 +274,7 @@ const noteShards = shards.list({
 });
 ```
 
-Schema and shard catalog factories delegate to `cultnet-ts`; the branded
+Schema and shard catalog factories delegate to `@gamecult/cultnet-ts`; the branded
 `CultMesh` entrypoint does not create a second owner for schema discovery or
 topology truth.
 
@@ -290,7 +290,7 @@ command transactions; the injected transport owns CultNet wire details.
 import {
   CultMeshProviderRudpTransport,
   CultMeshProviderSession,
-} from "cultmesh-ts";
+} from "@gamecult/cultmesh-ts";
 
 const odinTransport = new CultMeshProviderRudpTransport({
   endpoint: "rudp://127.0.0.1:17871",
@@ -347,7 +347,7 @@ evidence for the requested provider identity.
 
 Node runtimes can build the shared CultNet reliable-UDP transport from the
 branded CultMesh entrypoint while the transport semantics stay owned by
-`cultnet-ts`:
+`@gamecult/cultnet-ts`:
 
 ```ts
 const server = await CultMesh.createRudpServer("ts-server", 0x1020_3040);
@@ -472,7 +472,7 @@ The split is deliberate:
 The mirrored API shape is `CultMeshStreamCatalog`:
 
 ```ts
-import { CultMesh } from "cultmesh-ts";
+import { CultMesh } from "@gamecult/cultmesh-ts";
 
 const streams = CultMesh.createStreamCatalog();
 const stopWatchingStreams = streams.watch((stream) => {
@@ -533,7 +533,7 @@ nonlocal fallback.
 
 ## Content Chunks over HTTP(S)
 
-`cultmesh-ts/content` answers the C# HTTPS connector's request, `GET` or `HEAD`
+`@gamecult/cultmesh-ts/content` answers the C# HTTPS connector's request, `GET` or `HEAD`
 `<mount>?chunkHash=<hex>&recordKey=<key>`. The mount path is the host's; the
 handler reads only the query. Every chunk is hashed against its name before a
 byte is sent, so a corrupt or swapped file answers 500 and never leaves the
@@ -550,7 +550,7 @@ host store may reuse its buffer). `onServerFault` reports every 500 (`hash-misma
 ```ts
 import { readFileSync } from "node:fs";
 import { createServer } from "node:https";
-import { createContentChunkHandler, createDirectoryChunkStore, toNodeListener } from "cultmesh-ts/content";
+import { createContentChunkHandler, createDirectoryChunkStore, toNodeListener } from "@gamecult/cultmesh-ts/content";
 
 const handler = createContentChunkHandler(createDirectoryChunkStore("/srv/content"), {
   onServerFault: fault => console.error("chunk fault", fault.kind, fault.chunkHash),

packages/cultmesh-ts/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "cultmesh-ts",
+  "name": "@gamecult/cultmesh-ts",
   "version": "0.2.0",
   "description": "CultMesh local typed state and mesh catalog primitives for TypeScript runtimes.",
   "main": "dist/index.js",
@@ -48,8 +48,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@gamecult/cultcache-ts": "^0.14.0",
-    "cultnet-ts": "^0.3.0",
+    "@gamecult/cultcache-ts": "^0.15.0",
+    "@gamecult/cultnet-ts": "^0.3.0",
     "koffi": "3.3.0"
   },
   "devDependencies": {

packages/cultmesh-ts/src/content.ts

@@ -2,7 +2,7 @@ import { constants } from "node:fs";
 import { open } from "node:fs/promises";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { join } from "node:path";
-import { DEFAULT_CHUNK_SIZE_BYTES, EMPTY_SHA256, chunkRecordKey, isNullOrWhiteSpaceCSharp, parseSha256Hex, sha256Hex } from "cultnet-ts/content";
+import { DEFAULT_CHUNK_SIZE_BYTES, EMPTY_SHA256, chunkRecordKey, isNullOrWhiteSpaceCSharp, parseSha256Hex, sha256Hex } from "@gamecult/cultnet-ts/content";
 
 /** What the provider reads of a request. The path and the headers are never read: the route is the query alone. */
 export interface ContentChunkRequest { method: string; url: string; }

packages/cultmesh-ts/src/index.ts

@@ -1,5 +1,5 @@
 import { createSocket, type Socket } from "node:dgram";
-import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
 
 import {
   CultCache,
@@ -20,6 +20,7 @@ import {
   CultNetRudpSocketTransportConnection,
   rudpClientBindHost,
   CultNetSchemaCatalog,
+  cultNetTextError,
   CultNetShardCatalog,
   cultNetBuiltinSchemaRegistry,
   decodeRudpPacket,
@@ -40,7 +41,7 @@ import {
   type CultNetSchemaCatalogOptions,
   type CultNetSnapshotResponseRawMessage,
   type CultNetWireContract,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 
 import {
   CultMeshQuicRealtimeConnector,
@@ -5577,10 +5578,7 @@ export class CultMesh {
       switch (message.schemaVersion) {
         case "cultnet.snapshot_request.v0": {
           if (!options.getCache) {
-            sendSchemaMessage(record, {
-              schemaVersion: "cultnet.error.v0",
-              error: "CultMesh RUDP document server has no cache for snapshot requests.",
-            });
+            sendSchemaMessage(record, cultNetTextError("CultMesh RUDP document server has no cache for snapshot requests."));
             return;
           }
           let reply: CultNetMessage;
@@ -5613,7 +5611,7 @@ export class CultMesh {
             const unservable = unservablePut(message);
             if (unservable) {
               reportError(unservable);
-              sendSchemaMessage(record, { schemaVersion: "cultnet.error.v0", error: unservable.message });
+              sendSchemaMessage(record, cultNetTextError(unservable.message));
               return;
             }
             const receipt = await options.onDocumentPutRaw(normalizeRudpDocumentPut(message, record.remote, options.documents));
@@ -5623,29 +5621,20 @@ export class CultMesh {
               } catch (error) {
                 // The put is stored: the peer must hear that its receipt is not coming.
                 reportError(error);
-                sendSchemaMessage(record, {
-                  schemaVersion: "cultnet.error.v0",
-                  error: `CultMesh RUDP document server stored a put but could not send its receipt.`,
-                });
+                sendSchemaMessage(record, cultNetTextError(`CultMesh RUDP document server stored a put but could not send its receipt.`));
               }
             }
           }
           return;
         case "cultnet.operation_request.v0":
           if (!options.onOperationRequest) {
-            sendSchemaMessage(record, {
-              schemaVersion: "cultnet.error.v0",
-              error: "CultMesh RUDP document server has no operation handler.",
-            });
+            sendSchemaMessage(record, cultNetTextError("CultMesh RUDP document server has no operation handler."));
             return;
           }
           sendSchemaMessage(record, await options.onOperationRequest(message, publicSession(record)));
           return;
         default:
-          sendSchemaMessage(record, {
-            schemaVersion: "cultnet.error.v0",
-            error: `Unsupported CultMesh RUDP document request ${message.schemaVersion}.`,
-          });
+          sendSchemaMessage(record, cultNetTextError(`Unsupported CultMesh RUDP document request ${message.schemaVersion}.`));
       }
     }
 
@@ -5741,7 +5730,7 @@ export class CultMesh {
      */
     function refuse(record: SessionRecord, text: string): void {
       if (record.closed) return;
-      const payload = encodeSchemaMessage({ schemaVersion: "cultnet.error.v0", error: text });
+      const payload = encodeSchemaMessage(cultNetTextError(text));
       for (const packet of record.session.sendMany("schema", payload, {
         reliable: false,
         ordered: false,

packages/cultmesh-ts/src/provider-rudp-transport.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { createSocket, type Socket } from "node:dgram";
 import { documentPayloadFromBytes } from "@gamecult/cultcache-ts";
-import { encodeWireValue } from "cultnet-ts/wire";
+import { encodeWireValue } from "@gamecult/cultnet-ts/wire";
 import {
   CultNetPeer,
   CultNetRudpSocketTransportConnection,
@@ -9,7 +9,7 @@ import {
   type CultNetOperationRequestMessage,
   type CultNetOperationResponseMessage,
   type CultNetRawDocumentRecord,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 
 import type {
   CultMeshProviderCommand,

packages/cultmesh-ts/src/provider-session-broker.ts

@@ -1,11 +1,11 @@
 import { encodeDocumentPayload } from "@gamecult/cultcache-ts";
-import { encodeWireValue } from "cultnet-ts/wire";
+import { encodeWireValue } from "@gamecult/cultnet-ts/wire";
 import type {
   CultNetDocumentPutRawMessage,
   CultNetOperationRequestMessage,
   CultNetOperationResponseMessage,
   CultNetRawDocumentRecord,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 
 import type { CultMeshRudpServerSession } from "./index";
 import {

packages/cultmesh-ts/src/provider-session-wire.ts

@@ -1,6 +1,6 @@
 import { decodeDocumentPayload, defineDocumentType } from "@gamecult/cultcache-ts";
-import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
-import type { CultNetRawDocumentRecord } from "cultnet-ts";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
+import type { CultNetRawDocumentRecord } from "@gamecult/cultnet-ts";
 
 export const CULTMESH_PROVIDER_SESSION_SERVICE_ID = "gamecult.mesh.provider_session";
 

packages/cultmesh-ts/src/realtime-quic.ts

@@ -21,8 +21,8 @@ import {
   trimCSharp,
   verifyAuthorityRoute,
   type CultMeshAuthorityTrustPolicy,
-} from "cultnet-ts";
-import type { CultMeshVerseDescriptorMessage } from "cultnet-ts/contracts";
+} from "@gamecult/cultnet-ts";
+import type { CultMeshVerseDescriptorMessage } from "@gamecult/cultnet-ts/contracts";
 
 import {
   decodeRealtimeFrame,

packages/cultmesh-ts/src/realtime-wire.ts

@@ -16,7 +16,7 @@
 // agree with itself.
 
 import { documentPayloadBytes, documentPayloadFromBytes, type DocumentPayload } from "@gamecult/cultcache-ts";
-import { isNullOrWhiteSpaceCSharp } from "cultnet-ts";
+import { isNullOrWhiteSpaceCSharp } from "@gamecult/cultnet-ts";
 
 /** `CultMeshRealtimeWireProtocol.ApplicationProtocolName`: the QUIC ALPN. */
 export const CULTMESH_REALTIME_ALPN = "cultmesh-state-v1";
@@ -70,7 +70,7 @@ const INT64_MAX = 2n ** 63n - 1n;
  * `CultMeshRealtimeFrame.Validate`. The C# reading of "non-empty" is
  * `string.IsNullOrWhiteSpace`, whose whitespace set is not
  * `String.prototype.trim`'s, so this borrows the one TypeScript implementation
- * of that set from `cultnet-ts` rather than keeping a second reading here.
+ * of that set from `@gamecult/cultnet-ts` rather than keeping a second reading here.
  *
  * The range check has no C# counterpart because `long` gives it for free; a
  * `bigint` does not, and a `DataView` would otherwise throw a bare `RangeError`

packages/cultmesh-ts/test/codec-documents.test.ts

@@ -19,7 +19,7 @@ import {
   CultNetDocumentRegistry,
   defineCultNetDocumentBinding,
   type CultNetPeer,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 import { CultMesh, cultMeshDocumentFromSingleFile, type CultMeshRudpDocumentPut } from "../src/index";
 
 // A document written in the reference's positional shape, and a plain map document beside it. Every mesh reader of a

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

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import test, { mock } from "node:test";
 import { execFileSync } from "node:child_process";
 
-import { EMPTY_SHA256, chunkRecordKey, packContent, sha256Hex } from "cultnet-ts/content";
+import { EMPTY_SHA256, chunkRecordKey, packContent, sha256Hex } from "@gamecult/cultnet-ts/content";
 import { closeSync, constants as fsConstants, openSync, symlinkSync } from "node:fs";
 
 import {

packages/cultmesh-ts/test/cultmesh.test.ts

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import assert from "node:assert/strict";
-import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
+import { decodeWireValue, encodeWireValue } from "@gamecult/cultnet-ts/wire";
 import { z } from "zod";
 import { SchemaConflictError, defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "@gamecult/cultcache-ts";
 import {
@@ -12,6 +12,7 @@ import {
   CultNetPeer,
   CultNetRudpSession,
   cultNetBuiltinSchemaRegistry,
+  cultNetTextError,
   decodeRudpPacket,
   defineCultNetDocumentBinding,
   encodeRudpPacket,
@@ -19,7 +20,7 @@ import {
   type CultNetRudpPacket,
   type CultNetMessage,
   type CultNetSnapshotResponseRawMessage,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 import { CultMesh, CultMeshRudpUnservableDocumentError } from "../src/index";
 
 // A record's payload as the bytes a peer would put on the wire.
@@ -3708,7 +3709,7 @@ test("CultMesh TS RUDP document server answers a peer whose reliable queue is fu
     while (!refusalIn(rig.inbox) && Date.now() - startedAt < 3_000) await delay(5);
     const refusal = refusalIn(rig.inbox);
     assert.ok(refusal, "the refusal reaches the peer");
-    assert.deepEqual(refusal.message, { schemaVersion: "cultnet.error.v0", error: "the snapshot response could not be queued" });
+    assert.deepEqual(refusal.message, cultNetTextError("the snapshot response could not be queued"));
     for (const part of refusal.parts) {
       assert.ok(refused.every((sequence) => !acknowledges(part, sequence)), `ack ${part.ack} mask ${part.ackMask}`);
     }
@@ -3725,7 +3726,7 @@ test("CultMesh TS RUDP document server refuses a snapshot with fixed text, never
     while (!refusalIn(rig.inbox) && Date.now() - startedAt < 3_000) await delay(5);
     const refusal = refusalIn(rig.inbox);
     assert.ok(refusal, "the refusal reaches the peer");
-    assert.deepEqual(refusal.message, { schemaVersion: "cultnet.error.v0", error: "the snapshot source failed" });
+    assert.deepEqual(refusal.message, cultNetTextError("the snapshot source failed"));
     assert.match(rig.errors[0]?.message ?? "", /CANARY-7f3a/);
   });
 });

packages/cultmesh-ts/test/interop/cultmesh-quic-peer.ts

@@ -18,8 +18,8 @@
 // harness can dial a peer late and exercise Cut C's retained-state seed
 // instead of the provider always tearing down the moment it is done sending.
 //
-// Neither mode imports `cultmesh-ts` itself (the harness drives processes,
-// and the dependency direction is `cultmesh-ts` -> `cultnet-ts`, never the
+// Neither mode imports `@gamecult/cultmesh-ts` itself (the harness drives processes,
+// and the dependency direction is `@gamecult/cultmesh-ts` -> `@gamecult/cultnet-ts`, never the
 // reverse); this script reaches the provider/connector through its own
 // package's `src/`.
 

packages/cultmesh-ts/test/payload-type.test.ts

@@ -8,8 +8,8 @@ import {
   documentPayloadFromBytes,
   type DocumentPayload,
 } from "@gamecult/cultcache-ts";
-import { decodeWireValue } from "cultnet-ts/wire";
-import type { CultNetRawDocumentRecord } from "cultnet-ts";
+import { decodeWireValue } from "@gamecult/cultnet-ts/wire";
+import type { CultNetRawDocumentRecord } from "@gamecult/cultnet-ts";
 
 import type { CultMeshRudpDocumentPut } from "../src/index";
 import { decodeRealtimeFrame, encodeRealtimeFrame, type CultMeshRealtimeFrame } from "../src/realtime-wire";

packages/cultmesh-ts/test/provider-rudp-transport.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { createSocket } from "node:dgram";
 import { documentPayloadBytes } from "@gamecult/cultcache-ts";
-import { decodeWireValue } from "cultnet-ts/wire";
+import { decodeWireValue } from "@gamecult/cultnet-ts/wire";
 import {
   CultNetDocumentRegistry,
   CultNetRudpSession,
@@ -10,7 +10,7 @@ import {
   encodeRudpPacket,
   type CultNetOperationRequestMessage,
   type CultNetRudpPacket,
-} from "cultnet-ts";
+} from "@gamecult/cultnet-ts";
 
 import {
   CultMesh,