Studio grouping Cut 4 is unblocked, not blocked

The provenance schema ruling this cut was waiting on settled two days ago:
Aetheria's schema cut closed at 46efccbe and merged at 9b85211f, and branding
is now derived from the lot ledger rather than stored on the design. The cut
still needs re-mapping against that schema, but "blocked" was no longer true
and is how work quietly stops being picked up.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.github/workflows/cultmesh-portability.yml

@@ -95,3 +95,46 @@ jobs:
           dotnet test tests/GameCult.Mesh.Tests/GameCult.Mesh.Tests.csproj
           --filter FullyQualifiedName~Document_OneHundredThousandDistinctLeaseCyclesLeaveNoResourcesOrCallbacks
           --logger "console;verbosity=minimal"
+
+      # The TypeScript side of the CultMesh authority rules. This job is the
+      # only one that runs on both Windows and Linux for main, codex/** and
+      # pull requests: cultnet-interop.yml is windows-latest and main-only, so
+      # until these steps existed the shared verifier's tests never ran on
+      # Linux at all, and the browser client's never ran in CI on any OS.
+      # packages/cultnet-ts verifies both vector files; cultmesh-browser proves
+      # the browser client reads the shared rules rather than its own.
+      - name: Verify the CultMesh authority rules with the TypeScript verifier
+        run: npm run test --workspace packages/cultnet-ts
+
+      - name: Verify the browser client against the shared TypeScript verifier
+        run: npm run test --workspace packages/cultmesh-browser
+
+      # The realtime frame codec. Its byte parity rests on two vector files,
+      # contracts/cultmesh/realtime-frame-vectors.json written by the C#
+      # reference and decoded by this step, and realtime-frame-vectors.ts-written.json
+      # written by this codec and decoded by the C# step below. Neither half ran
+      # in CI on any OS until these two steps existed, so a codec that agreed
+      # only with itself would have gone green.
+      - name: Verify the realtime frame codec with the TypeScript codec
+        run: npm run test --workspace packages/cultmesh-ts
+
+      # Both directions of the CultMesh authority vectors: the C#-written
+      # file (contracts/cultmesh/authority-route-vectors.json) and the
+      # TypeScript-signed file (authority-route-vectors.ts-signed.json) are
+      # verified by the C# reference here; the TypeScript side verifies both
+      # in the step above. CULTMESH_WRITE_VECTORS is never set in CI: the
+      # committed files are the contract.
+      - name: Verify the CultMesh authority vectors with the C# reference
+        run: >-
+          dotnet test tests/GameCult.Mesh.Tests/GameCult.Mesh.Tests.csproj
+          --filter FullyQualifiedName~AuthorityProof
+          --logger "console;verbosity=minimal"
+
+      # The other half of the frame parity: the C# reference decodes and
+      # re-encodes the vector file the TypeScript codec wrote. A fixture
+      # authored on one side alone would only agree with itself.
+      - name: Verify the realtime frame vectors with the C# reference
+        run: >-
+          dotnet test tests/GameCult.Mesh.Tests/GameCult.Mesh.Tests.csproj
+          --filter FullyQualifiedName~RealtimeWireProtocol
+          --logger "console;verbosity=minimal"

.github/workflows/cultnet-interop.yml

@@ -65,6 +65,32 @@ jobs:
           "KOTLIN_JAVA_HOME=$env:JAVA_HOME" | Out-File -FilePath $env:GITHUB_ENV -Append
           "$kotlinHome\bin" | Out-File -FilePath $env:GITHUB_PATH -Append
 
+      - name: Verify CultNet schema contracts stayed consolidated
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $stray = git ls-files '*.schema.json' | Where-Object { $_ -notmatch '^contracts/cultnet/' }
+          # -I skips binary files: unity/org.gamecult.cultlib/Runtime/Plugins/GameCult.Networking.dll
+          # still embeds the retired namespace until it is rebuilt (REC-032 D4, deferred).
+          $oldNamespace = git grep -I -lE 'GameCult/cultnet-ts/(integration/)?contracts' -- ':!.voidbot'
+          if ($LASTEXITCODE -eq 2) {
+            throw "git grep failed"
+          }
+          if ($stray) {
+            Write-Host "Schema files found outside contracts/cultnet/:"
+            $stray | ForEach-Object { Write-Host "  $_" }
+          }
+          if ($oldNamespace) {
+            Write-Host "Files still referencing the retired GameCult/cultnet-ts contracts namespace:"
+            $oldNamespace | ForEach-Object { Write-Host "  $_" }
+          }
+          if ($stray -or $oldNamespace) {
+            throw "CultNet schema contracts drifted out of contracts/cultnet/ (REC-032). See CultLib/contracts/cultnet/ and rewrite any `$id back to https://github.com/GameCult/CultLib/contracts/cultnet/."
+          }
+          # git grep exits 1 when nothing matches, and the runner's pwsh wrapper
+          # ends the step with that $LASTEXITCODE; a clean tree must pass.
+          exit 0
+
       - name: Install Node dependencies
         run: npm install --no-package-lock
 

contracts/cultmesh/authority-route-vectors.json

@@ -0,0 +1,44 @@
+{
+  "nowUnixMilliseconds": 1800000000000,
+  "odinRoot": {
+    "keyId": "odin-vector",
+    "x": "shJLGtmRrW6D87VQKv0xYQekLIfEkeN7dVawwpmIKWM=",
+    "y": "iR6Gx3aVCghzSyo7TqXqr+1397L73KDNZuzN2cZ55IE="
+  },
+  "route": {
+    "verseId": "aetheria",
+    "authorityRuntimeId": "aetheria-daemon",
+    "endpoint": "wss://provider.example/mesh",
+    "protocolIds": [
+      "cultmesh.content.v1",
+      "cultmesh.documents.v1"
+    ],
+    "priority": 7,
+    "generation": "vector-generation-1",
+    "certificate": {
+      "providerKey": {
+        "keyId": "provider-vector",
+        "x": "6XIvgx3W1q7lJFEV0yYbeKWNFgssq54BHBuh9gCwcH8=",
+        "y": "oi1FiKraueLic+VemzOx18MNwG6thmZMUWeqNw6vNOk="
+      },
+      "odinKeyId": "odin-vector",
+      "issuedAtUnixMilliseconds": 1799999940000,
+      "expiresAtUnixMilliseconds": 1800003600000,
+      "signature": "ZHuELFuCNNfbJt1T2mx1D9ZHXyxBedacDetmryMYhWKQxfROncltymkmL5KXl+1h8tDK6NytJCGy+7mYlb/DMA=="
+    }
+  },
+  "sessionProof": {
+    "request": {
+      "schemaVersion": "cultmesh.session_open.v2",
+      "messageId": "vector-message-1",
+      "sourceRuntimeId": "vector-consumer",
+      "verseId": "aetheria",
+      "authorityRuntimeId": "aetheria-daemon",
+      "protocolId": "cultmesh.documents.v1",
+      "routeGeneration": "vector-generation-1",
+      "clientNonce": "VczqjH8NdBaOb+rh8xb6P0xZjWD1el2ReNB8Vbp52ko="
+    },
+    "providerKeyId": "provider-vector",
+    "providerSignature": "6kGxSu/pwcR4lzh/7Av9nhblVIwIwVFzB7kY34vVvkpaFAbAxt8mWqIyZDTftE28G1g+NL4Ea41C3QsuImmkaA=="
+  }
+}

contracts/cultmesh/authority-route-vectors.ts-signed.json

@@ -0,0 +1,45 @@
+{
+  "nowUnixMilliseconds": 1800000000000,
+  "odinRoot": {
+    "keyId": "odin-ts-vector",
+    "x": "lqw9TE0EyuDU5Ghe8SafIbBBYkhHMUF7HXJQUc0nXsw=",
+    "y": "nUj+Xhakih97JiJcTUNMHM9JIo7MVQaauuAkCXph+tw="
+  },
+  "route": {
+    "verseId": "aetheria",
+    "authorityRuntimeId": "aetheria-daemon",
+    "endpoint": "cultmesh-state+quic://provider.example:4433/?cert-sha256=ABCDEF",
+    "protocolIds": [
+      "cultmesh.documents.v1",
+      "cultmesh.content.v1",
+      "cultmesh.realtime.v1"
+    ],
+    "priority": 13,
+    "generation": "ts-generation-ünïcode-∞-1",
+    "certificate": {
+      "providerKey": {
+        "keyId": "provider-ts-vector",
+        "x": "JKyjtWnoE5fhSWbeqr188SbReQWCjssf5mSMEa5pV+E=",
+        "y": "vtduzojDpbT49sbxBSsBQ+f3PG3rm+CUk/MTy2MM/ws="
+      },
+      "odinKeyId": "odin-ts-vector",
+      "issuedAtUnixMilliseconds": 1799999940000,
+      "expiresAtUnixMilliseconds": 1800003600000,
+      "signature": "NS5a7X8fNqTi1CdpPAcJaMmEsozwFRoygTW4z+JlhHFq7uaZcb4G7NwoEpPqo/Fv+UA7pNl5N+qUMuSD/oAq1Q=="
+    }
+  },
+  "sessionProof": {
+    "request": {
+      "schemaVersion": "cultmesh.session_open.v2",
+      "messageId": "ts-vector-message-1",
+      "sourceRuntimeId": "ts-vector-consumer",
+      "verseId": "aetheria",
+      "authorityRuntimeId": "aetheria-daemon",
+      "protocolId": "cultmesh.documents.v1",
+      "routeGeneration": "ts-generation-ünïcode-∞-1",
+      "clientNonce": "HICtAmV++1MarssY04Tkyn1j9qVEcOMp/P5Ce1M0Yec="
+    },
+    "providerKeyId": "provider-ts-vector",
+    "providerSignature": "OgJHkmw3fhPRS5TXxZm94yZvkWAV5TPDuvG+/zIVlnU7OFENZ0Nn0Pdx0IT/vDfEWXD+8/+sCZVFIFwa4tUjsg=="
+  }
+}

contracts/cultmesh/realtime-frame-vectors.json

@@ -0,0 +1,177 @@
+{
+  "frames": [
+    {
+      "label": "reliable-ordered, small payload",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 1,
+        "sequence": 2,
+        "delivery": "reliable-ordered",
+        "payload": "AH+A/yo="
+      },
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYABQAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03AH+A/yo=",
+      "encodedLength": 83,
+      "sha256OfEncoding": "d04539b99790560e5e570208d92d3ac25f85909a36bfeb190c2080288cc9f1d4"
+    },
+    {
+      "label": "latest-only, small payload",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 3,
+        "sequence": 4,
+        "delivery": "latest-only",
+        "payload": "AQID"
+      },
+      "encoding": "Q1NUMQEDAAAAAAAAAAQAAAAAAAAADwAUAAYAAwAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03AQID",
+      "encodedLength": 81,
+      "sha256OfEncoding": "2c875718cf4968979f3cd4083ba2b279e8c03815ad3447c66037ee4530b2814a"
+    },
+    {
+      "label": "unreliable, small payload",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 5,
+        "sequence": 6,
+        "delivery": "unreliable",
+        "payload": "/g=="
+      },
+      "encoding": "Q1NUMQIFAAAAAAAAAAYAAAAAAAAADwAUAAYAAQAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03/g==",
+      "encodedLength": 79,
+      "sha256OfEncoding": "b932adf333a0ca73d3a9077e15cf9062070a3084a50a3a30c3baa53312d864b1"
+    },
+    {
+      "label": "empty payload",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 0,
+        "sequence": 0,
+        "delivery": "reliable-ordered",
+        "payload": ""
+      },
+      "encoding": "Q1NUMQAAAAAAAAAAAAAAAAAAAAAADwAUAAYAAAAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03",
+      "encodedLength": 78,
+      "sha256OfEncoding": "06c0362f2b395bf7855522190f6a59c45c46947ce7a9a4b8be115cf54a48f419"
+    },
+    {
+      "label": "multi-byte identities",
+      "fields": {
+        "channelId": "aetheria.zöne-∞",
+        "schemaId": "cultmesh.realtime.€1",
+        "bodyId": "bødy-\uD83D\uDD25",
+        "producerEpoch": 11,
+        "sequence": 12,
+        "delivery": "latest-only",
+        "payload": "cGF5bG9hZC3iiJ4="
+      },
+      "encoding": "Q1NUMQELAAAAAAAAAAwAAAAAAAAAEgAWAAoACwAAACUAAAABAGFldGhlcmlhLnrDtm5lLeKInmN1bHRtZXNoLnJlYWx0aW1lLuKCrDFiw7hkeS3wn5SlcGF5bG9hZC3iiJ4=",
+      "encodedLength": 98,
+      "sha256OfEncoding": "90c6ae8f1362d9e000aa57682612bb1d7606cabe2cd0c0969fdd07b816f44b1c"
+    },
+    {
+      "label": "epoch and sequence at long.MaxValue",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 9223372036854775807,
+        "sequence": 9223372036854775807,
+        "delivery": "unreliable",
+        "payload": "Wg=="
+      },
+      "encoding": "Q1NUMQL/////////f/////////9/DwAUAAYAAQAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03Wg==",
+      "encodedLength": 79,
+      "sha256OfEncoding": "208068a668b48dc1abde9b3d7f025e7f7b6de6c480faea25c1383b6de9fd37ca"
+    },
+    {
+      "label": "identities at exactly 65535 UTF-8 bytes",
+      "fields": {
+        "channelId": {
+          "repeat": "ä€",
+          "byteLength": 65535
+        },
+        "schemaId": {
+          "repeat": "ۊ",
+          "byteLength": 65535
+        },
+        "bodyId": {
+          "repeat": "ñ€",
+          "byteLength": 65535
+        },
+        "producerEpoch": 13,
+        "sequence": 14,
+        "delivery": "reliable-ordered",
+        "payload": "ESI="
+      },
+      "encoding": null,
+      "encodedLength": 196644,
+      "sha256OfEncoding": "e3c1a353b606e86b35169efb875e76349dcfcb2d036973ee3bbe3c601fbda3e1"
+    },
+    {
+      "label": "64 MiB payload",
+      "fields": {
+        "channelId": "aetheria.zone-1",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "body-7",
+        "producerEpoch": 15,
+        "sequence": 16,
+        "delivery": "reliable-ordered",
+        "payload": {
+          "ramp": 67108864
+        }
+      },
+      "encoding": null,
+      "encodedLength": 67108942,
+      "sha256OfEncoding": "4d99183bdb450af854d87a81ba86a3a4c92ecc1b208675d916f1b75a9f1e7928"
+    }
+  ],
+  "malformed": [
+    {
+      "label": "truncated header",
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAAB",
+      "message": "Realtime frame header is truncated."
+    },
+    {
+      "label": "wrong magic",
+      "encoding": "vFNUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame magic is invalid."
+    },
+    {
+      "label": "wire version 2",
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAACAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame wire version is unsupported."
+    },
+    {
+      "label": "header size 36",
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACQAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame wire version is unsupported."
+    },
+    {
+      "label": "delivery 3",
+      "encoding": "Q1NUMQMBAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame delivery mode is invalid."
+    },
+    {
+      "label": "delivery 255",
+      "encoding": "Q1NUMf8BAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame delivery mode is invalid."
+    },
+    {
+      "label": "payload length -1",
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAgCUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJ",
+      "message": "Realtime frame length is invalid."
+    },
+    {
+      "label": "length sum off by one",
+      "encoding": "Q1NUMQABAAAAAAAAAAIAAAAAAAAADwAUAAYAAwAAACUAAAABAGFldGhlcmlhLnpvbmUtMWN1bHRtZXNoLnJlYWx0aW1lLnYxYm9keS03CQkJAA==",
+      "message": "Realtime frame length is invalid."
+    }
+  ]
+}

contracts/cultmesh/realtime-frame-vectors.ts-written.json

@@ -0,0 +1,177 @@
+{
+  "frames": [
+    {
+      "label": "ts reliable-ordered, small payload",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 21,
+        "sequence": 22,
+        "delivery": "reliable-ordered",
+        "payload": "AAH+/w=="
+      },
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "encodedLength": 79,
+      "sha256OfEncoding": "68c264a42ce34e540e9dbee31dab5b73dec98c767f0b44591ce6a477cd17fc04"
+    },
+    {
+      "label": "ts latest-only, small payload",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 23,
+        "sequence": 24,
+        "delivery": "latest-only",
+        "payload": "f4A="
+      },
+      "encoding": "Q1NUMQEXAAAAAAAAABgAAAAAAAAACQAUAAkAAgAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xf4A=",
+      "encodedLength": 77,
+      "sha256OfEncoding": "3d4f49f4aa2c1f132c3a09ee83555c13e0bc036d636524a972e2829cf417b959"
+    },
+    {
+      "label": "ts unreliable, small payload",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 25,
+        "sequence": 26,
+        "delivery": "unreliable",
+        "payload": "pQ=="
+      },
+      "encoding": "Q1NUMQIZAAAAAAAAABoAAAAAAAAACQAUAAkAAQAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xpQ==",
+      "encodedLength": 76,
+      "sha256OfEncoding": "2c2faec604850959d44ee65d87d2ea59462b667c5d0db8565a8c159d75301851"
+    },
+    {
+      "label": "ts empty payload",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 0,
+        "sequence": 0,
+        "delivery": "latest-only",
+        "payload": ""
+      },
+      "encoding": "Q1NUMQEAAAAAAAAAAAAAAAAAAAAACQAUAAkAAAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0x",
+      "encodedLength": 75,
+      "sha256OfEncoding": "6d2a04b399f32db4086e728194249b0279330ffa5517cdd82228f691a0f10708"
+    },
+    {
+      "label": "ts multi-byte identities",
+      "fields": {
+        "channelId": "ts.zøne-∂",
+        "schemaId": "cultmesh.realtime.µ1",
+        "bodyId": "ts-bödy-🧊",
+        "producerEpoch": 27,
+        "sequence": 28,
+        "delivery": "unreliable",
+        "payload": "dHMtcGF5bG9hZC3iiII="
+      },
+      "encoding": "Q1NUMQIbAAAAAAAAABwAAAAAAAAADAAVAA0ADgAAACUAAAABAHRzLnrDuG5lLeKIgmN1bHRtZXNoLnJlYWx0aW1lLsK1MXRzLWLDtmR5LfCfp4p0cy1wYXlsb2FkLeKIgg==",
+      "encodedLength": 97,
+      "sha256OfEncoding": "d5d22458bd50a446c7bdce4e2598fe8e5e7bfac3646d8fcd7215363c7c5c8ca1"
+    },
+    {
+      "label": "ts epoch and sequence at long.MaxValue",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 9223372036854775807,
+        "sequence": 9223372036854775807,
+        "delivery": "reliable-ordered",
+        "payload": "Bw=="
+      },
+      "encoding": "Q1NUMQD/////////f/////////9/CQAUAAkAAQAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xBw==",
+      "encodedLength": 76,
+      "sha256OfEncoding": "2abb67a876dc4ed006f33708b4c4dda55a90a6f95da7352749225195b10d45ba"
+    },
+    {
+      "label": "ts identities at exactly 65535 UTF-8 bytes",
+      "fields": {
+        "channelId": {
+          "repeat": "ü☃",
+          "byteLength": 65535
+        },
+        "schemaId": {
+          "repeat": "☃ü",
+          "byteLength": 65535
+        },
+        "bodyId": {
+          "repeat": "ç☃",
+          "byteLength": 65535
+        },
+        "producerEpoch": 29,
+        "sequence": 30,
+        "delivery": "latest-only",
+        "payload": "M0Q="
+      },
+      "encoding": null,
+      "encodedLength": 196644,
+      "sha256OfEncoding": "8bd4cd4c5232339f76b8e394eb93b66e8d14302398ecce2ae5bdb78070ef783a"
+    },
+    {
+      "label": "ts 64 MiB payload",
+      "fields": {
+        "channelId": "ts.zone-a",
+        "schemaId": "cultmesh.realtime.v1",
+        "bodyId": "ts-body-1",
+        "producerEpoch": 31,
+        "sequence": 32,
+        "delivery": "unreliable",
+        "payload": {
+          "ramp": 67108864
+        }
+      },
+      "encoding": null,
+      "encodedLength": 67108939,
+      "sha256OfEncoding": "f2c20e0b47a7681fbaeff6fcba024363542805de4cd95eeb7fa9f125ba646af0"
+    }
+  ],
+  "malformed": [
+    {
+      "label": "ts truncated header",
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAAB",
+      "message": "Realtime frame header is truncated."
+    },
+    {
+      "label": "ts wrong magic",
+      "encoding": "Q1OrMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame magic is invalid."
+    },
+    {
+      "label": "ts wire version 2",
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAACAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame wire version is unsupported."
+    },
+    {
+      "label": "ts header size 38",
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACYAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame wire version is unsupported."
+    },
+    {
+      "label": "ts delivery 3",
+      "encoding": "Q1NUMQMVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame delivery mode is invalid."
+    },
+    {
+      "label": "ts delivery 128",
+      "encoding": "Q1NUMYAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame delivery mode is invalid."
+    },
+    {
+      "label": "ts payload length -1",
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAgCUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/w==",
+      "message": "Realtime frame length is invalid."
+    },
+    {
+      "label": "ts length sum off by one",
+      "encoding": "Q1NUMQAVAAAAAAAAABYAAAAAAAAACQAUAAkABAAAACUAAAABAHRzLnpvbmUtYWN1bHRtZXNoLnJlYWx0aW1lLnYxdHMtYm9keS0xAAH+/wA=",
+      "message": "Realtime frame length is invalid."
+    }
+  ]
+}

contracts/cultnet/cultmesh.session-accepted.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultmesh.session-accepted.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultmesh.session-accepted.schema.json",
   "title": "CultMesh Session Accepted",
   "type": "object",
   "required": ["schemaVersion", "messageId", "accepted", "verseId", "authorityRuntimeId", "protocolId", "routeGeneration", "clientNonce", "providerKeyId", "providerSignature"],

contracts/cultnet/cultmesh.session-open.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultmesh.session-open.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultmesh.session-open.schema.json",
   "title": "CultMesh Session Open",
   "type": "object",
   "required": ["schemaVersion", "messageId", "sourceRuntimeId", "verseId", "authorityRuntimeId", "protocolId", "routeGeneration", "clientNonce"],

contracts/cultnet/cultmesh.verse-catalog-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultmesh.verse-catalog-request.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultmesh.verse-catalog-request.schema.json",
   "title": "CultMesh Verse Catalog Request",
   "type": "object",
   "required": ["schemaVersion", "messageId"],

contracts/cultnet/cultmesh.verse-catalog-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultmesh.verse-catalog-response.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultmesh.verse-catalog-response.schema.json",
   "title": "CultMesh Verse Catalog Response",
   "type": "object",
   "required": ["schemaVersion", "messageId", "verses"],

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-change-raw.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.database-change-raw.schema.json",
   "title": "CultNet Raw Database Change Message",
   "type": "object",
   "required": ["schemaVersion", "messageId", "subscriptionId", "changeKind"],

contracts/cultnet/cultnet.database-subscribe.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-subscribe.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.database-subscribe.schema.json",
   "title": "CultNet Database Subscribe Message",
   "type": "object",
   "required": ["schemaVersion", "messageId", "subscriptionId", "includeSnapshot"],

contracts/cultnet/cultnet.database-unsubscribe.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.database-unsubscribe.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.database-unsubscribe.schema.json",
   "title": "CultNet Database Unsubscribe Message",
   "type": "object",
   "required": ["schemaVersion", "messageId", "subscriptionId"],

contracts/cultnet/cultnet.document-delete.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-delete.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-delete.schema.json",
   "title": "CultNet Document Delete Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.document-mutation-contract.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-mutation-contract.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-mutation-contract.schema.json",
   "title": "CultNet Document Mutation Contract",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.document-put-raw.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-put-raw.schema.json",
   "title": "CultNet Raw Document Put Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.document-put.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-put.schema.json",
   "title": "CultNet Document Put Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.document-record.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-record.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-record.schema.json",
   "title": "CultNet Document Record",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.error.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.error.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.error.schema.json",
   "title": "CultNet Error Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.hello.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.hello.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.hello.schema.json",
   "title": "CultNet Hello Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.login-success.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login-success.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.login-success.schema.json",
   "title": "CultNet Login Success Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.login.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.login.schema.json",
   "title": "CultNet Login Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.operation-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.operation-request.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.operation-request.schema.json",
   "title": "CultNet Operation Request",
   "type": "object",
   "required": ["schemaVersion", "messageId", "serviceId", "operation", "payloadSchema", "payload"],

contracts/cultnet/cultnet.operation-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.operation-response.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.operation-response.schema.json",
   "title": "CultNet Operation Response",
   "type": "object",
   "required": ["schemaVersion", "messageId", "serviceId", "operation", "status", "payloadSchema", "payload"],

contracts/cultnet/cultnet.raw-document-record.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.raw-document-record.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.raw-document-record.schema.json",
   "title": "CultNet Raw Document Record",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.register.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.register.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.register.schema.json",
   "title": "CultNet Register Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.sample-change-name.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-change-name.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.sample-change-name.schema.json",
   "title": "CultNet Sample Change Name Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.sample-chat.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-chat.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.sample-chat.schema.json",
   "title": "CultNet Sample Chat Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.schema-catalog-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-request.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.schema-catalog-request.schema.json",
   "title": "CultNet Schema Catalog Request Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.schema-catalog-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-response.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.schema-catalog-response.schema.json",
   "title": "CultNet Schema Catalog Response Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.schema-descriptor.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-descriptor.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.schema-descriptor.schema.json",
   "title": "CultNet Schema Descriptor",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.shard-catalog-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "cultnet.shard_catalog_request.v0",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.shard-catalog-request.schema.json",
   "type": "object",
   "required": ["schemaVersion", "messageId"],
   "additionalProperties": false,

contracts/cultnet/cultnet.shard-catalog-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "cultnet.shard_catalog_response.v0",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.shard-catalog-response.schema.json",
   "type": "object",
   "required": ["schemaVersion", "messageId", "shards"],
   "additionalProperties": false,

contracts/cultnet/cultnet.snapshot-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-request.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.snapshot-request.schema.json",
   "title": "CultNet Snapshot Request Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.snapshot-response-raw.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response-raw.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.snapshot-response-raw.schema.json",
   "title": "CultNet Raw Snapshot Response Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.snapshot-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.snapshot-response.schema.json",
   "title": "CultNet Snapshot Response Message",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.transport-profile.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json",
   "title": "CultNet Transport Profile",
   "type": "object",
   "required": [

contracts/cultnet/cultnet.verify.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.verify.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.verify.schema.json",
   "title": "CultNet Verify Message",
   "type": "object",
   "required": [

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.witness-artifact-bundle.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.witness-artifact-bundle.schema.json",
   "title": "CultNet Witness Artifact Bundle",
   "type": "object",
   "required": [

contracts/cultnet/interop/cultnet.interop-note.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note.schema.json",
+  "$id": "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note.schema.json",
   "title": "CultNet Interop Note",
   "type": "object",
   "required": [

docs/nuget-packaging.md

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

docs/studio-grouping-cut.md

@@ -0,0 +1,704 @@
+# Studio Record Grouping And Reference Drag-Drop Cut
+
+Date: 2026-09-17 (Imagination pass)
+
+Status: cut map, forks open. The operator rules on forks Q1-Q5 before Hands
+starts. Where a line depends on a fork, it names the fork and follows the
+recommendation. Line references are against CultLib `122c217` and Aetheria
+`515859cf` unless marked otherwise.
+
+CultLib `main` moved during this pass, from `122c217` to `1845301`. The three
+new commits touch only `native/GameCult.Mesh.Quic.Native`,
+`scripts/mutate-cultmesh.mjs` and a QUIC doc. They were live uncommitted edits
+in the main checkout when the pass began. The Q5 audit extends to them
+unchanged. Another agent is actively working on `main`, so Hands works in its
+own worktree.
+
+## Target
+
+### Ends
+
+1. **Declared record grouping.** An attribute on a document type's model
+   declares that the type's records group by one or more member values. Studio's
+   record list becomes a foldout tree for that type. Tree levels nest in the
+   declared order. A declaration on a base type groups the records of every
+   derived type listed under it.
+2. **Create in a group.** Every group node offers `Create`. The new record gets
+   every grouped member on the path to that node set to that node's value, so
+   it appears in that node.
+3. **Reference drag and drop.** You can drag a record row from Studio's record
+   list onto any `CultRecordRef<T>` value the inspector draws (a member, a list
+   element, a dictionary key or value). The drop is accepted exactly when the
+   record is one the ref's picker would offer.
+
+Recovered from the legacy "Database Tools" window (Aetheria `d3db1730`,
+`Assets/Scripts/CultCache/Editor/DatabaseView.cs`, `AetheriaDatabaseView.cs`,
+`Inspectors/DatabaseLinkInspector.cs`). Declaring grouping by selector lambdas
+is rejected by operator ruling (2026-09-17): use attributes.
+
+### Invariants
+
+- **I1. Model owns grouping.** `CultInspectorModel` alone decides:
+  - which members group a listed type, and in what order;
+  - which declarations are invalid, and the notice for each;
+  - the tree's partition, node identity, node order and node labels;
+  - the object that create-in-group makes.
+  The Studio lowers the tree and never reads the attribute, calls
+  `SetValue` for a preset, or computes a label.
+- **I2. The leaves partition the candidates.** Across all leaves, the tree's
+  records are exactly `RecordCandidates(CultRecordRef<listed>, records)`. Each
+  record appears once, and records keep candidate order inside a leaf. Grouping
+  never hides a record, including one whose grouped value is unset, dangling,
+  or an undefined enum value.
+- **I3. The listed type owns the tree's shape.** Grouping comes from the type
+  selected in the type pane, never from each record's runtime type. A
+  `WeaponItemData` listed under `GearData` is grouped by `GearData`'s
+  declaration.
+- **I4. Node identity is value identity, not the label.**
+  - A `CultRecordRef` groups by key.
+  - An enum groups by its underlying value.
+  - Other kinds group by the invariant string of the value.
+  So two factions with the same label are two nodes, and foldout state keys on
+  the node id.
+- **I5. Create-in-group round-trips.** Upsert the object that
+  `CreateInGroup(listed, node)` returns, then regroup: the new record lies in a
+  node with the same id.
+- **I6. One candidate rule.** `IsRecordCandidate(refType, record)` is the only
+  test for "this record may be this ref's value". `RecordCandidates` filters
+  through it, and drop acceptance calls it. No `IsInstanceOfType` appears in
+  `src/GameCult.Unity`.
+- **I7. One ref label.** The model owns the strings `None` and `Missing <key>`.
+  The picker (`DrawRecordRef`) and group labels both use it.
+- **I8. Invalid declarations never break the window.** An invalid declaration
+  gives a flat list plus the model's notice. It never throws in `OnGUI`.
+- **I9. A drop honours the same gates as the picker.** A drop is refused:
+  - in a disabled (read-only) scope;
+  - when the payload came from another store's model;
+  - when the key equals the current key.
+  A dictionary key drop still goes through `ReplaceKey` refusal, because
+  `DrawDictionary` already routes every key change there
+  (`CultCacheStudioDrawers.cs:243-251`).
+
+### Non-consumers and non-goals
+
+- **Sibling runtimes.** There is no port of the inspector model or the
+  inspector attributes.
+  - `packages/cultcache-ts/src/cult-cache-inspector.ts` is a raw
+    `.cc` byte and catalog dumper (`inspectCultCacheBytes`). It has no members,
+    metadata, candidates or grouping.
+  - Rust and Python have neither.
+  No parity work is needed.
+- **Wire and catalog.** Attributes are metadata only. They change no schema id,
+  catalog entry or store byte.
+- **Runtime CultUI panel.** This cut adds none. The model's API is shaped so one
+  could lower it.
+- **Not in scope:** record search (Q4), grouping in the ref picker popup (Q3),
+  drop-to-append on list headers (the legacy `DatabaseLinkListInspector`), and
+  the legacy "entry name `New <Type>`" on create.
+
+## Body findings that shape the cut
+
+Established by reading and by probes in scratch (`probe/`, `studio-compile/`):
+
+- **F1. Legacy grouping by gear hardpoint read a derived property.**
+  - Legacy `GearData` grouping read `HardpointType` and wrote `Hardpoint`.
+  - `EquippableItemData.HardpointType` (`ItemData.cs:401-402`) is an abstract
+    `[IgnoreMember]` property. `GearData.HardpointType => Hardpoint`
+    (`:455`), `CargoBayData` returns `Tool` (`:464`) and `HullData` returns
+    `Hull` (`:533`).
+  - The stored member is `GearData.Hardpoint` (slot 23, `:453`).
+  - The model's member list for `GearData` and `WeaponItemData` includes
+    `Hardpoint#23@GearData`, confirmed by probe. `HardpointType` is not an
+    inspector member.
+  - The declaration names `Hardpoint`. The overriding types have no stored
+    hardpoint, so they have nothing to group.
+- **F2. `Manufacturer` is declared on the abstract `ItemData`** (`ItemData.cs:281`),
+  not on `GearData`. Probe of `GameData/Aetheria.cc` (a copy):
+
+  | Listed type | Records | Manufacturer set | Manufacturer unset |
+  |---|---|---|---|
+  | `GearData` (includes `WeaponItemData`) | 43 | 29 | 14 |
+  | `HullData` | 3 | 3 | 0 |
+  | `CargoBayData` (includes `DockingBayData`) | 5 | 5 | 0 |
+  | `SimpleCommodityData` | 13 | 0 | 13 |
+  | `CompoundCommodityData` | 51 | 0 | 51 |
+
+  `GearData` has 11 distinct manufacturers. A member attribute on
+  `ItemData.Manufacturer` would therefore also wrap all 64 commodity records in
+  one "None" level. Legacy grouped only `GearData` by manufacturer. This drives
+  Q1.
+- **F3. Legacy grouping matched the exact type** (`CanGroup: typeof(T) == type`),
+  and its tables listed exact types. So it never grouped `WeaponItemData`
+  records. Grouping derived records under a base declaration is new behaviour,
+  as the brief asks.
+- **F4. Legacy create-in-group was dead.** `DatabaseEntryGroup<T,K>.Activate`
+  (`DatabaseView.cs:70-75`) throws after invoking. Legacy groups also existed
+  only when occupied (`GroupBy`), and foldouts keyed on the label's hash, so
+  groups with the same label collapsed together.
+- **F5. Existing metadata misses inherited attributes on overriding properties.**
+  - `CultInspectorMetadata` reads `member.GetCustomAttributes(true)`
+    (`CultInspectorModel.cs:36`), and `CultInspectorDrawerClaims.Resolve` reads
+    it too (`:209`).
+  - For a `PropertyInfo`, that overload ignores `inherit`. Probe: a base
+    `[M] abstract int P` is not seen on the override.
+    `Attribute.GetCustomAttributes(member, true)` does see it.
+  - Fields are unaffected. This is a latent defect in every `Inherited = true`
+    inspector attribute.
+- **F6. Studio `Add` creates only the listed type**
+  (`CultCacheStudioWindow.cs:340-347`: `CreateElement(type, type)`), and is
+  disabled when the model cannot create it (`:141`).
+  - Create-in-group therefore never makes a derived type, and every grouped
+    member exists on the created object.
+  - "A preset value is invalid for the created derived type" cannot arise, so it
+    is recorded as a default, not a fork.
+  - An abstract listed type offers no `Create`.
+- **F7. Studio search filters the type pane only** (`:112-120`). No record
+  search exists.
+- **F8. Studio foldouts are not persisted.** The inspector keeps foldouts in an
+  in-memory dictionary (`CultCacheStudioDrawers.cs:33`). The window closes its
+  store on `OnDisable` (`:48-51`), which includes a domain reload. The only
+  `EditorPrefs` key is `LastPathKey` (`:13`).
+- **F9. No drawer claims `CultRecordRef<>`.** This was checked in CultLib Studio
+  and in Aetheria `HEAD:Assets/Scripts/Editor/CultCacheDrawers.cs`. So every
+  ref value reaches `DrawRecordRef` (`:195-221`), and the drop target added
+  there covers all of them. A future claimed ref drawer would bypass it, which
+  is acceptable: a claim owns its widget.
+- **F10. The Studio editor sources compile outside Unity.**
+  - Probe: a netstandard2.1 / C# 9 project compiles
+    `src/GameCult.Unity/Assets/Caching/Editor/*.cs` with 0 errors against:
+    - `Editor/Data/Managed/UnityEngine/*.dll` from Unity 6000.3.24f1 (the
+      `UnityEditor.dll` facade must be left out, because it duplicates the
+      module types);
+    - the tracked `GameCult.Caching*.dll` and `MessagePack*.dll`.
+  - This gives a pre-tag compile gate. The last migration only had
+    post-release Aetheria batchmode.
+- **F11. The Studio source row reads its click in `GUILayout.Toggle`**
+  (`:184`). IMGUI button-like controls take `MouseDrag` while they are the hot
+  control, so the drag start must be handled on a reserved rect *before* the
+  toggle draws. This comes from Unity's IMGUI convention and was not probed
+  here; the operator click-through proves it.
+
+## Identity, lifecycle and authority
+
+| Thing | Identity | Lifecycle | Owner (decides) | Readers | Persisted? |
+|---|---|---|---|---|---|
+| Grouping declaration | Attribute on a document class (Q1-B) or member (Q1-A), in the consumer's engine-free assembly | Compile time; inherited per `AttributeUsage` | Consumer source (Aetheria `ServerShared`) | `CultInspectorModel` only | Source code; no store bytes |
+| Resolved grouping (`CultInspectorGrouping`) | Listed `Type` | Cached per model instance, like `_shapes` (`CultInspectorModel.cs:298-299`); dies with the model at store close | `CultInspectorModel` | Studio window | No |
+| Group tree (`CultInspectorRecordGroup`) | Root per (listed type, records snapshot) | Rebuilt each `OnGUI`, as `RecordCandidates` already is (`CultCacheStudioWindow.cs:167`) | `CultInspectorModel` | Studio window | No |
+| Node id | `<listed schema name>` + `/` + per-level value identity (I4) | Stable while the values exist | `CultInspectorModel` | Studio foldout map | No |
+| Node label | Enum name, `RecordLabel`, `None`, `Missing <key>`, invariant string, `(empty)` | Recomputed with the tree | `CultInspectorModel` | Studio | No |
+| Group foldout state | Node id → bool | Window instance memory; cleared by `CloseStore`; lost on domain reload, which already closes the store (F8) | `CultCacheStudioWindow` | Same | No (default; see Defaults) |
+| Invalid-declaration notice | Listed `Type` | With the resolved grouping | `CultInspectorModel` | Studio shows a warning HelpBox above the list | No |
+| Created-in-group object | New document | Made by the model, upserted by the window through `_cache.UpsertAsync` exactly as `Add` does | Model makes it; `CultCache` admits it | Window selects the key and expands its path | Store, on `Save` |
+| Drag payload | `CultCacheStudioRecordDrag { CultInspectorModel Model; string Key }` under generic data key `"GameCult.CultCacheStudio.Record"` | One drag gesture (Unity `DragAndDrop`) | Studio record list (source) | `CultInspector.DrawRecordRef` (target) | No |
+| Drop acceptance | (ref type, record) | Per `DragUpdated` / `DragPerform` | `CultInspectorModel.IsRecordCandidate` plus the I9 gates | Studio | No |
+
+No persistent state is introduced. No cell is empty.
+
+## Forks
+
+### Q1. Where does the grouping declaration live, and how is nesting ordered? (blocks Cuts 1, 4)
+
+**Ruled B (operator, 2026-09-17):** "I like B". The same ruling reopens the item
+schema: a crafted item's manufacturer belongs to its production lot, not its
+design (see Cut 4).
+
+
+- **A. Member attribute** `[CultInspectorGroup(int order = 0)]` on a field or
+  property.
+  - Levels are ordered by `order`, then by the member's display order
+    (`Metadata.Order ?? Slot`).
+  - Inheritance comes free.
+  - The member can't be scoped: on `ItemData.Manufacturer`, it groups every item
+    type by manufacturer, and all 64 commodity records sit under one `None`
+    level (F2).
+  - Ordering spreads across files: `Hardpoint` on `GearData` with `order: 0`,
+    `Manufacturer` on `ItemData` with `order: 1`.
+- **B. Type attribute** `[CultInspectorGroupBy(nameof(Hardpoint), nameof(Manufacturer))]`
+  on a document class. `AttributeUsage(Class, Inherited = true,
+  AllowMultiple = false)`.
+  - The argument order is the nesting order.
+  - The nearest declaration wins, so a derived type re-declares, and
+    `[CultInspectorGroupBy]` with no arguments opts out.
+  - Names resolve against the listed type's inspector members, so inherited
+    members work.
+  - `nameof` keeps it refactor-safe, and it names data rather than code.
+  - It scopes `Manufacturer` to `GearData` exactly as legacy did.
+- **C. Both forms.** Twice the surface, two ordering rules.
+- **Recommendation: B.**
+  - It is the only form that recovers the legacy grouping without the
+    commodity regression.
+  - Its nesting order sits in one place, readable.
+  - It is still an attribute, not a selector.
+  - It departs from the brief's "member attribute" working name; that is why
+    this is asked.
+- **Depends on it:**
+  - Cut 1's attribute type and its resolution tests.
+  - Cut 4's annotations: under B, four class attributes; under A, four member
+    attributes plus accepting F2.
+
+### Q2. Which group nodes exist? (blocks Cut 1)
+
+- **A. Occupied values only** (legacy parity, F4).
+  - Create into an empty category means creating at the root and then editing
+    the member.
+- **B. Enums show every defined value, including empty nodes**, so
+  create-in-group reaches empty categories. Other kinds show occupied values
+  only.
+  - Refs cannot enumerate every candidate record: 11+ factions per level times
+    the enum levels is too many.
+- **Recommendation: A.**
+  - The trees stay proportional to the data.
+  - The rule is the same for every kind.
+  - B is a small later addition.
+- **Depends on it:** the tree builder and one test.
+
+### Q3. Does grouping also apply to the `CultRecordRef` picker popup? (blocks Cut 2 scope)
+
+- **A. List only.**
+- **B. Also the popup**, as `EditorGUILayout.Popup` submenus using `/` paths
+  built from the ref target type's grouping.
+  - A label containing `/` would split wrongly unless it is escaped.
+  - A target type such as `EquippableItemData` has no declaration, so it still
+    shows flat.
+- **Recommendation: A.**
+  - With drag-drop from the grouped list, the long-popup pain is gone.
+  - B can reuse the model tree later without new model surface.
+
+### Q4. Record search? (blocks nothing if A)
+
+- **A. None in this cut.** The Studio has no record search today (F7).
+- **B. A record search field** that filters tree leaves and auto-expands
+  matching paths.
+- **Recommendation: A.** It is a separate feature, and grouping does not need it.
+
+### Q5. Release base and re-pin scope (blocks Cuts 3, 4)
+
+`git log a0813c6..122c217` (68 commits) touches nothing under:
+
+- `src/GameCult.Caching`
+- `src/GameCult.Caching.MessagePack`
+- `src/GameCult.Unity`
+- `unity/`
+- `packages/cultmath`
+
+It touches:
+
+- the native QUIC bridge, rewritten to a C ABI v2 (`6a091ef`). The v1 exports
+  `cultmesh_quic_open/state/poll` remain at `cultmesh_quic_native.cpp:1360-1392`.
+- OpenSSL MsQuic (`c729dff`).
+- TS CultMesh/CultNet, the QUIC native tests, and docs and CI.
+- `scripts/build-unity-package.ps1`, one message line.
+
+The build script rebuilds and, with `-UpdateTemplate`, replaces
+`unity/org.gamecult.cultlib/Runtime/Plugins/x86_64/gamecult_mesh_quic_native.dll`
+and `msquic.dll`. `19d8d5c` records that the committed native plugin is the
+older 40,448-byte Schannel build and that current source builds to 302,080
+bytes. So a release from main ships a new native bridge and msquic into
+Aetheria's Unity package. Aetheria calls no QUIC (grep `Quic` in `Assets/Scripts`
+hits only a KDTree file).
+
+- **A. Release from main** after the feature merges, and accept the native
+  plugin replacement.
+  - Verify the rebuilt DLL still exports the three v1 entry points the managed
+    `GameCult.Mesh.Quic.Native.dll` imports
+    (`src/GameCult.Mesh.Quic.Native/*.cs:261-275`).
+  - The build host needs MSVC and the pinned MsQuic digests. If the native
+    build fails, stop and return to the operator.
+- **B. Release from a branch off `a0813c6`** carrying only this feature. Tag it
+  there and merge back to main.
+  - The tags sit on a commit whose native plugin stays old.
+  - The next main release takes the drift anyway, so B only defers it.
+- **C. Release from main, but hand-restore the old native plugin** in the
+  release commit.
+  - The byte check then fails by construction. Rejected unless the operator
+    wants it.
+- **Recommendation: A.** The drift is committed, reviewed work that only the
+  release step has held back. Aetheria does not load the bridge, and B leaves
+  the committed plugin already known to be stale (`19d8d5c`).
+- **Depends on it:** Cut 3's base, its verification list, and Cut 4's
+  `CultLibRevision`.
+
+## Defaults (recorded, not asked)
+
+- **Group labels:**
+  - An enum shows `Enum.GetName`. An undefined value shows its number.
+  - A `CultRecordRef<T>` shows `RecordLabel` of the candidate with that key
+    (the target's `[CultName]`), so for Faction that is `Name`, not the
+    legacy `ShortName`.
+  - An unset ref shows `None`, like the picker (`CultCacheStudioDrawers.cs:207`),
+    replacing the legacy `Default`.
+  - A key with no candidate shows `Missing <key>`, as the picker does.
+  - A string shows its value, or `(empty)`.
+  - An integer shows its invariant string.
+  - A bool shows `False`/`True`.
+- **Group order within a level:**
+  - Enums sort by underlying value.
+  - Refs sort `None` first, then by label (`OrdinalIgnoreCase`, then key),
+    with `Missing` last.
+  - Strings sort `OrdinalIgnoreCase`, then ordinal.
+  - Integers sort numerically; bools sort false before true.
+- **Groupable kinds:** String, Integer, Bool, Enum, RecordRef. A grouped member
+  is refused with a notice and a flat list (I8) when:
+  - it is of any other kind, including Float, whose bit-equality makes
+    meaningless groups;
+  - it is `Hidden`;
+  - it is read-only (`IsReadOnly`, so a preset cannot assign it and an edit
+    cannot move the record);
+  - it is named but is not an inspector member of the listed type;
+  - it is named twice.
+- **Global types are never grouped.** They have one record.
+- **Foldouts:**
+  - Window memory, collapsed by default.
+  - `CloseStore` clears them.
+  - Create-in-group, `Add`, and `Duplicate` expand the path to the new
+    selection, so the selection is always visible.
+  - No `EditorPrefs` or `SessionState` (F8: a domain reload already closes the
+    store).
+- **Create-in-group into a `Missing <key>` node** presets the dangling key, which
+  keeps I5. The record joins the node it was created in.
+- **A drop of the current key is rejected** (legacy parity) so that no no-op
+  commit occurs.
+- **F5 is fixed in Cut 1.** The new attribute reads through `MetadataOf`, so
+  that path must honour inheritance on properties; the fix is one call site
+  in each of two places.
+
+## Cuts
+
+### Cut 1. CultLib model: declaration, grouping tree, candidate and label authority
+
+- **Repo and branch:** CultLib `claude/studio-grouping`, in a new worktree
+  `F:\Projects\CultLib-studio-grouping` from `origin/main`. The main checkout
+  is in active use by the QUIC bridge work; do not use or touch it or the other
+  worktrees.
+- **Deletes and collapses first:**
+  - `CultInspectorModel.cs:512-520` `RecordCandidates`: its inline predicate
+    `target.IsInstanceOfType(record.Document) && record.Key.Value.Length > 0`
+    moves into `IsRecordCandidate`, and `RecordCandidates` filters through it
+    (I6).
+  - `CultCacheStudioDrawers.cs:207` builds its `"Missing " + key` / `"None"`
+    label inline. The label moves to the model (I7), and the Studio call site
+    changes in Cut 2.
+  - `CultInspectorModel.cs:36` and `:209` switch from `member.GetCustomAttributes(true)`
+    to `Attribute.GetCustomAttributes(member, true)` (F5).
+- **Adds in `CultInspectorAttributes.cs`:**
+  - Q1-B: `CultInspectorGroupByAttribute(params string[] members)`, with
+    `Class`, `Inherited = true`, `AllowMultiple = false`, and property
+    `Members`.
+  - Q1-A instead: `CultInspectorGroupAttribute(int order = 0)`, with
+    `Field|Property`, `Inherited = true`.
+  - Place it before `CultInspectorDrawerAttribute` (`:80`), with a comment in the
+    file's style stating the nesting and inheritance rules.
+- **Adds in `CultInspectorModel.cs`** (or a sibling `CultInspectorGrouping.cs`
+  in the same namespace; Hands picks, and one file is preferred while it
+  stays under ~800 lines):
+  - `public sealed class CultInspectorGrouping`: `Type ListedType`,
+    `IReadOnlyList<CultInspectorMember> Members` (outermost first), and
+    `string? Notice`. When `Notice` is set, `Members` is empty.
+  - `public sealed class CultInspectorRecordGroup`: `string Id`, `string Label`
+    (empty at the root), `int Depth`, `IReadOnlyList<object?> Values` (root to
+    here), `IReadOnlyList<CultInspectorRecordGroup> Children`,
+    `IReadOnlyList<CultStoredDocument> Records` (non-empty only at leaves), and
+    `int Count` (records beneath).
+  - `CultInspectorModel.GroupingOf(Type listedType)`, cached like `ShapeOf`:
+    - Global types, and types with no declaration, give empty members and no
+      notice.
+    - Q1-B: resolve names against `MembersOf(listedType)`.
+    - Q1-A: take members carrying the attribute, ordered by (order, display
+      order).
+    - Validate the groupable kinds, hidden, read-only and duplicates (Defaults).
+  - `CultInspectorModel.GroupRecords(Type listedType, IEnumerable<CultStoredDocument> records)`:
+    - The input is `RecordCandidates(CultRecordRef<listedType>)`, partitioned
+      level by level by value identity (I4).
+    - Nodes follow the Defaults order and labels. Records stay in candidate
+      order (I2).
+    - With no grouping members, the root holds every record as one leaf.
+  - `CultInspectorModel.CreateInGroup(Type listedType, CultInspectorRecordGroup group, out string? notice)`:
+    - Call `CreateElement(listedType, listedType, out notice)`. On null, return
+      null with that notice.
+    - Otherwise `SetValue` each grouping member with the node's value. A ref is
+      rebuilt with `CreateRecordRef(member type, key)`.
+    - Refuse (`ArgumentException`) a node whose depth or id prefix does not
+      belong to `listedType`'s current grouping.
+  - `public bool IsRecordCandidate(Type recordRefType, CultStoredDocument record)`.
+  - `public string RecordRefLabel(Type recordRefType, object? value, IEnumerable<CultStoredDocument> records)`:
+    - `None` when unset.
+    - Otherwise `RecordLabel` of the candidate with that key.
+    - Otherwise `Missing <key>`.
+- **Keeps:** `RecordLabel` (`:313-317`), `CreateElement` (`:385-396`), and every other API unchanged.
+- **Tests** go in `tests/GameCult.Caching.Tests/CultInspectorModelTests.cs`,
+  with new fixtures near `:380-459`. Fixtures:
+  - an abstract base document class, and a derived `[CultDocument]` pair
+    `GroupBase` / `GroupLeaf : GroupBase`;
+  - an enum member, a `CultRecordRef<InspectOther>` member, a string, a float,
+    a hidden int and a read-only int;
+  - a type re-declaring (Q1-B) and a type opting out.
+
+  Each test names the mutation that must turn it red:
+
+  1. `GroupsNestInDeclaredOrder`. The level order equals the declaration, not
+     slot order. *Mutation:* order members by slot, and the test fails.
+  2. `BaseDeclarationGroupsDerivedRecords`. A `GroupLeaf` record listed under
+     `GroupBase` is grouped by the base declaration (I3). *Mutation:* look up the
+     attribute with `inherit: false`, or take the grouping from
+     `record.Descriptor.DocumentType`.
+  3. `NearestDeclarationWinsAndEmptyOptsOut` (Q1-B only). *Mutation:* merge base
+     and derived name lists.
+  4. `LeavesPartitionTheCandidates`. Over records with unset refs, dangling
+     refs and undefined enum values, the concatenated leaves equal
+     `RecordCandidates` as a multiset in order (I2). *Mutation:* skip records
+     whose value is unset, or dedupe by label.
+  5. `RefNodesAreKeyedByKeyAndLabelledByTheModel`. Two referenced records share
+     one `[CultName]` and give two nodes. Unset gives `None`, first. A dangling
+     key gives `Missing k`, last (I4, I7). *Mutation:* group by label.
+  6. `EnumNodesOrderByValue`. Declare the enum out of alphabetical order.
+     *Mutation:* order nodes by label.
+  7. `CreateInGroupPresetsEveryLevelAndRegroupsInPlace`. Create at depth 2,
+     upsert into a `CultCache` over a temp single-file store, and regroup: the
+     new record's leaf id equals the node id (I5). *Mutation:* preset only the
+     deepest level.
+  8. `InvalidDeclarationsGiveANoticeAndAFlatTree`. Cover an unknown name, a
+     float, a hidden member, a read-only member and a duplicate. Each gives a
+     notice, and `GroupRecords` does not throw (I8). *Mutation:* remove any one
+     validation branch.
+  9. `IsRecordCandidateIsTheRecordCandidatesRule`. A subtype record is
+     accepted; a sibling type and an empty key are refused; `RecordCandidates`
+     equals the records filtered by it (I6). *Mutation:* use an exact-type
+     comparison.
+  10. `InheritedMetadataReachesOverridingProperties`. A base abstract property
+      with `[CultInspectorLabel]` is seen on the override's member metadata
+      (F5). *Mutation:* revert `:36`.
+- **Verification:**
+  - Run `dotnet test tests\GameCult.Caching.Tests\GameCult.Caching.Tests.csproj -c Release`
+    in the worktree. All pass, and the count grows by the tests above.
+  - For each mutation listed, apply it in the worktree, confirm its test fails,
+    then revert. Record the mutation table in the landing commit message.
+- **Ledger:**
+  - Model: about +150 to 190 lines.
+  - Attributes: about +15 lines.
+  - Tests: about +200 lines.
+  - Two predicate and label duplicates deleted (one moved, one
+    collapsed in Cut 2).
+
+### Cut 2. CultLib Studio: lower the tree, create in group, drag source, drop target
+
+- **Repo and branch:** CultLib `claude/studio-grouping` (same worktree), after
+  Cut 1.
+- **Deletes first:**
+  - `CultCacheStudioDrawers.cs:207`: the inline `"Missing " + key : "None"`
+    becomes `Model.RecordRefLabel(type, value, Records)` for `names[0]` when
+    `index == 0`.
+  - `CultCacheStudioWindow.cs:180-185`: the flat `foreach` over records is
+    replaced by tree drawing.
+- **Changes in `CultCacheStudioWindow.cs`:**
+  - Fields (`:13-30`): add `Dictionary<string,bool> _groupFoldouts`
+    (`StringComparer.Ordinal`) and `const string RecordDragKey`.
+    `CloseStore` (`:318-327`) clears the foldouts.
+  - `DrawRecords` (`:135-190`):
+    - Take `_model.GroupingOf(_selectedType)`. When its `Notice` is set, show a
+      `HelpBox` Warning above the list.
+    - Draw `_model.GroupRecords(_selectedType, _records)` recursively. A node
+      is a foldout labelled `Label (Count)` and indented by `Depth`.
+    - An expanded node draws its children, then its leaf records, then a
+      `Create` mini button. The button is enabled under the same
+      `cannotAdd || IsGlobal` gate as `Add` (`:141-147`) and calls
+      `CreateInGroup`.
+    - The root (depth 0) is not drawn as a foldout. `Add` stays the root create.
+  - Record row:
+    - Reserve its rect with `GUILayoutUtility.GetRect` before
+      `GUI.Toggle(rect, ...)` (F11).
+    - On `MouseDrag` inside the rect with a button held, set
+      `DragAndDrop.PrepareStartDrag()`, then `SetGenericData(RecordDragKey,
+      new CultCacheStudioRecordDrag(_model, key))`, set `objectReferences` to
+      empty, call `StartDrag(label)`, and use the event.
+  - `AddInGroup(node)`: mirrors `Add` (`:340-347`) through `Run`. It upserts
+    `CreateInGroup`'s object (null means throw its notice), selects the key, and
+    expands the node's id prefixes. `Add` and `Duplicate` expand the new
+    record's path by looking up its leaf in the next tree; Hands may do that
+    on the next frame through a `_revealKey` field.
+- **Changes in `CultCacheStudioDrawers.cs`:**
+  - Add `internal sealed class CultCacheStudioRecordDrag { Model; Key }`, or
+    put it in the window file (Hands picks; one type, no interface).
+  - `DrawRecordRef` (`:195-221`): capture the `HorizontalScope` rect.
+    - On `DragUpdated` or `DragPerform` inside it, when `GUI.enabled` is true,
+      the payload's `Model == Model`, the payload key is not the current key,
+      the key's record is in `Records`, and `Model.IsRecordCandidate(type,
+      record)` holds, set the visual mode to `Copy`. Otherwise set it to
+      `Rejected` for our payload only (leave foreign drags untouched).
+    - On perform: `AcceptDrag`, `next = key`, `GUI.changed = true`, and use
+      the event.
+    - Return through the existing `next == key ? value : CreateRecordRef`
+      (`:220`).
+- **README** (`src/GameCult.Unity/Assets/Caching/README.md`, after `:36-39`):
+  - Grouping: the attribute, nesting, inheritance, labels, create in group,
+    and the notice.
+  - Drag a record onto a reference field.
+  - Under "Inspection Model", the grouping API and `IsRecordCandidate` /
+    `RecordRefLabel`.
+- **Verification:**
+  - Pre-tag compile gate (F10). Copy the scratch `studio.csproj` pattern:
+    netstandard2.1, `LangVersion 9.0`, compiling the worktree's
+    `Assets/Caching/Editor/*.cs`. Reference Unity 6000.3.24f1
+    `Editor\Data\Managed\UnityEngine\*.dll` (not `UnityEditor.dll`) and the
+    worktree's freshly built `src\GameCult.Caching` and
+    `GameCult.Caching.MessagePack` outputs (`dotnet build -c Release`), plus
+    the tracked `MessagePack*.dll`. Expect 0 errors. Keep the project in
+    scratch, not the repo.
+  - Negative greps in the worktree, each empty:
+    - `rg -n "IsInstanceOfType" src/GameCult.Unity/Assets/Caching` (I6)
+    - `rg -n "\"Missing \"|\"None\"" src/GameCult.Unity/Assets/Caching/Editor` (I7)
+    - `rg -n "SetValue|GetCustomAttribute|CultInspectorGroup" src/GameCult.Unity/Assets/Caching/Editor/CultCacheStudioWindow.cs` (I1)
+    - `rg -n "EditorPrefs" src/GameCult.Unity/Assets/Caching/Editor` shows only
+      `LastPathKey`
+  - Cut 1's tests still pass.
+  - Operator click-through happens after Cut 4, in Aetheria against the tagged
+    package, as in the migration's Cut 6 precedent. See Cut 4.
+- **Ledger:** Window about +70 to 90 lines, drawers about +25 lines, README
+  about +20 lines. Two inline decisions deleted.
+
+### Cut 3. CultLib release: cultlib Unity 1.0.61, Studio 1.5.0
+
+Versions bumped from the original 1.0.60/1.4.0 plan: `codex/asset-guid-attribute`
+took 1.0.60/1.4.0 for its own release (replacing the asset path attribute with
+`CultInspectorAssetGuid`, then adding sub-asset key support, then a built-in
+refusal fix and a stale-value Clear button); it releases first. This branch
+must rebase onto and rebuild after `codex/asset-guid-attribute` before its own
+release: same files (`CultInspectorModel.cs`, the Studio drawers, the plugin
+DLLs/pdbs), so a plain merge reports binary conflicts on the plugin DLLs/pdbs
+rather than silently picking one side; resolve by taking either side's text
+changes as needed and then rebuilding, not by hand-merging the binaries.
+
+- **Repo and branch:** CultLib `main`. Merge `claude/studio-grouping`
+  (fast-forward or merge commit), then create the release commit in the same
+  clean worktree. Q5-A is assumed.
+- **Files:**
+  - `unity/org.gamecult.cultlib/package.json:4`: `1.0.60` → `1.0.61`.
+  - `src/GameCult.Unity/Assets/Caching/package.json:4`: `1.4.0` → `1.5.0`,
+    because this is new user-facing capability. `:13`: `"org.gamecult.cultlib": "1.0.61"`.
+  - `unity/org.gamecult.cultlib/Runtime/Plugins/*.dll|pdb` and
+    `x86_64/*.dll`, via
+    `powershell -File scripts\build-unity-package.ps1 -UpdateTemplate`. The
+    script derives the assembly version from the package.json and checks it
+    (`:152-155` after the rebase onto `codex/asset-guid-attribute`, whose
+    `0c9cb57` inserted two lines above this block for the OpenSSL notice;
+    it is `:150-153` on this branch's own unrebased copy of the script).
+- **Tags on the release commit:** `cultlib-unity-v1.0.61` and
+  `caching-unity-v1.5.0`. That is two tags in one push, under GitHub's
+  three-tag workflow limit (migration cut map header). No `cultmath-unity` tag,
+  because CultMath is unchanged.
+- **Verification:**
+  - **Byte check.** Run the build script again and check that
+    `git status --porcelain unity/` is empty (a reproducible build). This is
+    manual, as recorded in the migration's follow-ups.
+  - **Expected diff.** `git diff --stat HEAD~1 -- unity/` lists
+    `GameCult.Caching.dll/.pdb` changed. Under Q5-A,
+    `x86_64/gamecult_mesh_quic_native.dll` (about 302 KB) and `msquic.dll` also
+    change. An unexpected changed assembly stops the release for review.
+  - **API present.** A throwaway scratch script loads the tracked
+    `GameCult.Caching.dll` by reflection and confirms that
+    `CultInspectorGroupByAttribute`, `CultInspectorModel.GroupRecords`,
+    `CreateInGroup`, `IsRecordCandidate` and `RecordRefLabel` exist.
+  - **Native ABI (Q5-A).** Run `dumpbin /exports` on the tracked
+    `gamecult_mesh_quic_native.dll`. It lists `cultmesh_quic_open`, `_state`,
+    `_poll`, `_error` and `_close`.
+  - **Tags pushed.** `git ls-remote --tags origin` lists both tags.
+- **Ledger:** Versions and binaries only.
+
+### Cut 4. Aetheria: re-pin CultLib and annotate grouping
+
+**Unblocked, needs re-mapping (2026-09-19).** The operator ruled that a crafted
+item's manufacturer and optional branding belong to its production lot, after
+Njordr's lot ontology, so `ItemData.Manufacturer` leaves the design. Grouping
+`GearData` by `Manufacturer` is therefore not the target. That schema ruling has
+now settled: Aetheria's provenance schema cut closed at `46efccbe` and merged to
+master at `9b85211f`, and branding is derived from the lot's `ProvenanceLedger`
+rather than stored on the design. This cut is waiting on a fresh Imagination pass
+against the landed schema, not on the ruling. Cuts 1-3 do not depend on it.
+
+
+- **Repo and branch:** Aetheria `codex/cultcache-cutover`, the current branch.
+  Stage by path only: `Assets/Scripts/Editor/CultCacheDrawers.cs` carries an
+  unrelated uncommitted edit that must stay out of the commit and untouched.
+- **Files:**
+  - `Directory.Build.props:5` `CultLibRevision`: set it to the Cut 3 release
+    commit's full SHA. Note that it lives in props, not targets; the check is in
+    `Directory.Build.targets:2-22`.
+  - `Packages/manifest.json:53`: `#caching-unity-v1.4.0` → `#caching-unity-v1.5.0`.
+    `:54`: `#cultlib-unity-v1.0.60` → `#cultlib-unity-v1.0.61`. `:55`
+    `cultmath-unity-v0.2.3` is unchanged. Unity rewrites
+    `Packages/packages-lock.json`; commit that too.
+  - `Assets/Scripts/ServerShared/ItemData.cs`, under Q1-B:
+    - `SimpleCommodityData` (`:300`): `[CultInspectorGroupBy(nameof(Category))]`
+    - `CompoundCommodityData` (`:330`): `[CultInspectorGroupBy(nameof(Category))]`
+    - `GearData` (`:449`): `[CultInspectorGroupBy(nameof(Hardpoint), nameof(Manufacturer))]`.
+      `WeaponItemData` inherits it.
+    - `HullData` (`:493`): `[CultInspectorGroupBy(nameof(HullType))]`
+  - Under Q1-A instead: `[CultInspectorGroup]` on `SimpleCommodityData.Category`
+    (`:309`), `CompoundCommodityData.Category` (`:337`),
+    `GearData.Hardpoint` (`:453`), `ItemData.Manufacturer` (`:281`, order 1)
+    and `HullData.HullType` (`:503`). Commodity lists then gain the `None`
+    manufacturer level (F2).
+- **Tests** (`tests/Aetheria.Shared.Tests`, new `StudioGroupingTests.cs`, xUnit):
+  - `AnnotatedCatalogTypesGroupAsDeclared`:
+    - Build `CultCacheMessagePack.CreateInspectorModel` over the Aetheria
+      registry, as the probe did with the `[CultDocument]` types of
+      `typeof(GearData).Assembly`.
+    - `GroupingOf` names exactly `Category`, `Category`,
+      `Hardpoint, Manufacturer` and `HullType` for the four types, each with no
+      notice.
+    - `GroupingOf(typeof(WeaponItemData))` equals `GearData`'s.
+    - *Mutation:* remove one annotation, or reorder `GearData`'s names.
+  - `NoGroupedMemberIsRefused`. Every registered document type's `GroupingOf`
+    has a null notice. This guards against a future annotation on a float or
+    hidden member.
+- **Verification:**
+  - **Headless.** Run
+    `dotnet test tests\Aetheria.Shared.Tests -p:CultLibRoot=F:\Projects\CultLib-studio-grouping`,
+    with that worktree checked out clean at the release SHA. The revision check
+    requires a clean root at exactly that SHA, and the main CultLib checkout is
+    shared with live work. All pass.
+  - **Unity batchmode compile.** With the editor closed, run
+    `-batchmode -nographics -quit -projectPath F:\Projects\Aetheria -logFile <scratch>`
+    on Unity 6000.3.24f1. Expect 0 compile errors, and the package cache
+    resolving both new tags.
+  - **Operator click-through** in Aetheria's Studio against
+    `GameData/Aetheria.cc`:
+    - `GearData` shows hardpoint then manufacturer. It includes the
+      `WeaponItemData` records marked `<WeaponItemData>`, and a `None` node
+      holds the 14 unset.
+    - Commodities show categories only. `HullData` shows hull types.
+    - Create in a gear node, then check that the record lands there and is
+      selected.
+    - Drag a faction onto a gear `Manufacturer` and see it accepted. Drag a
+      gear record onto it and see it rejected.
+    - Drag onto a `DemandProfile` dictionary key and see a duplicate refused
+      through the notice.
+    - In a read-only open, every drop is rejected.
+    - Close without edits and confirm that the store bytes are unchanged.
+  - **Negative grep.** `rg -n "HardpointType\)" Assets/Scripts/ServerShared/ItemData.cs`
+    shows no grouping declaration names the derived property.
+- **Ledger:** 4 attribute lines (Q1-B), the pin and manifest lines, and about
+  +40 test lines.
+
+## Subtraction ledger (whole change)
+
+- **Added:**
+  - One attribute type.
+  - Two model types and five model methods.
+  - About 10 CultLib tests and 2 Aetheria tests.
+  - About 100 Studio lines.
+  - 4 annotations.
+- **Removed or collapsed:**
+  - The candidate predicate duplicated at each future call site. It was
+    inline once; now it is one method, reused by drop.
+  - The ref label strings, duplicated between picker and grouping.
+  - The latent attribute-inheritance miss on overriding properties (F5).
+- **Not added:** selectors, registries, `EditorPrefs` keys, sibling-runtime
+  ports, or new packages, targets or daemons.
+- **Build footprint:**
+  - `GameCult.Caching` and its tests.
+  - The Unity package script, which rebuilds every tracked plugin including the
+    native bridge (Q5).
+  - Aetheria's headless shared build and one batchmode compile.
+  - The build host is the Windows workstation, which is also the target
+    platform for both the Unity editor plugin and the win-x64 native bridge.

docs/typescript-quic-realtime-target.md

@@ -0,0 +1,160 @@
+# TypeScript QUIC Realtime Plane Target
+
+Date: 2026-09-16
+
+Status: target accepted by the operator (2026-09-16), ready for Eureka. No cut
+map exists yet. When the pipeline starts, Imagination maps the cut into
+`docs/typescript-quic-realtime-cut.md` against `main` at `a0813c6` or later.
+
+The TypeScript runtime gains the CultMesh QUIC realtime state plane that the C#
+runtime already has: a provider that serves frames and a consumer that receives
+them, byte-compatible with `GameCult.Mesh.Quic` and the native MsQuic connector
+the Unity package ships. This document states the end state and the invariants
+that constrain getting there.
+
+Operator ruling, 2026-09-16, on providing QUIC for a Node service: "Option 2 all
+the way, this is what CultLib is supposed to be, we're not half assing it." A
+separate .NET provider process and a WebSocket shortcut were both rejected.
+
+## Why now
+
+The first consumer is StreamPixels. Its service (Node 24, TypeScript, on
+Yggdrasil) must publish realtime state to a Unity overlay running on a
+streamer's machine. The overlay is a receive-only client using the Unity
+package's `CultMeshNativeQuicRealtimeTransportConnector`. Today no TypeScript
+path exists:
+
+- Node v24.15.0 has no `node:quic`, with or without `--experimental-quic`.
+- `packages/cultmesh-ts` and `packages/cultnet-ts` contain no QUIC code.
+- `GameCult.Mesh.Quic` (.NET 10, `System.Net.Quic`) is the only QUIC provider.
+- The C# TCP control and content connectors are plaintext and restricted to
+  loopback (`src/GameCult.Mesh/docs/transport-planes.md`, "Security and release
+  gate"), so they cannot carry the overlay's remote session either.
+
+## This touches the foundation
+
+- **Wire parity is an invariant.** The C# codec is the reference:
+  `src/GameCult.Mesh/CultMeshRealtimeWireProtocol.cs`. The TypeScript runtime
+  must produce and accept identical bytes:
+  - ALPN `cultmesh-state-v1`; connection close code `0x43554c54`, stream abort
+    code `0x53544154`; reliable stream type `1`, latest-only stream type `2`.
+  - Frame: magic `0x31545343`, then a 37-byte little-endian fixed header
+    (delivery byte, producer epoch i64, sequence i64, channel/schema/body id
+    lengths u16, payload length i32, header size i32 = 37, wire version u16 =
+    1), then UTF-8 channel id, schema id, body id, then payload.
+  - Limits: payload at most 64 MiB; each identity at most 65,535 UTF-8 bytes;
+    decode rejects wrong magic, unknown version, out-of-range delivery, and any
+    length that does not sum exactly.
+- **Delivery semantics are an invariant**
+  (`src/GameCult.Mesh.Quic/README.md`, `CultMeshRealtimeTransports.cs`):
+  - `ReliableOrdered`: one persistent ordered stream; broadcast is
+    completion-bearing.
+  - `LatestOnly`: independent streams; at most one pending frame per
+    `(channel, body)`, replaced by a newer `(producer epoch, sequence)`
+    generation; a keyed coalescing outbox per physical peer, so a slow or
+    departed consumer never backpressures the producer.
+  - `Unreliable`: fails closed until datagrams are exposed, matching the managed
+    C# adapter.
+- **Trust is an invariant.** No remote session comes online without the chain
+  in `transport-planes.md`: an Odin-signed `CultMeshRouteCertificate` (Verse,
+  authority runtime, protocol set, endpoint, generation, validity, provider
+  P-256 key) checked against consumer-pinned Odin roots, TLS 1.3, and the
+  endpoint certificate bound to that route, including the
+  `cultmesh-state+quic://host:port?cert-sha256=<uppercase SHA-256>` pin.
+  Signatures are ECDSA P-256 over SHA-256 with P1363 `r || s` encoding and the
+  length-prefixed canonical transcript. Unsigned traffic exists only under an
+  explicit `LocalDevelopment` policy on loopback.
+- **One implementation of TypeScript route verification.** `cultmesh-browser`
+  already verifies Odin route certificates and provider nonce possession with
+  WebCrypto (`packages/cultmesh-browser/src/index.ts`, `verifyAuthorityRoute`,
+  `canonicalRoute`, `canonicalSession`, `verifyP256`). The Node QUIC path must
+  reuse that owner, not grow a second verifier.
+- **The realtime plane carries state frames only.** Schemas, commands,
+  receipts, manifests, and immutable content do not travel through it
+  (`ICultMeshRealtimeTransport` doc comment). RUDP is never installed
+  implicitly in its place.
+- **Existing consumers survive.** The StreamPixels service already imports
+  `cultcache-ts`, `cultnet-ts`, and `cultmesh-ts` (`verse-state.ts`,
+  `idunn-rudp-health.ts`) for Odin advertisement and Idunn health over RUDP.
+  Imagination audits every other TypeScript consumer across `F:\Projects`
+  before sizing the cut.
+
+## Target state
+
+- `cultmesh-ts` exposes a QUIC realtime provider and a QUIC realtime consumer
+  with the same ergonomic shape as the C# `CultMeshQuicRealtimeServer`
+  (listen, broadcast with an explicit delivery mode) and
+  `ICultMeshRealtimeTransportConnector` (connect by advertised candidate,
+  receive frames), under the branded `CultMesh` entrypoint.
+- QUIC comes from native MsQuic bindings owned by CultLib, not from a Node
+  polyfill or a third-party QUIC stack with different semantics. How the binding
+  is built and shipped is the means (Imagination probes it); what it must
+  deliver is TLS 1.3, ALPN, independent unidirectional or bidirectional streams,
+  certificate validation with a caller hook, and clean close and abort codes.
+- Frame encoding and decoding exist once in TypeScript and are tested against
+  bytes produced by the C# codec.
+- Application code never picks endpoints, ranks routes, or writes reconnect
+  loops; `CultMeshSessionManager`-equivalent route selection owns that, as in C#.
+- The build produces binaries for the hosts that run them: Windows x64 for
+  local development, and Linux x64 for Yggdrasil, built on Linux or the deploy
+  path's builder, not cross-compiled on Starfire.
+
+## Not in this migration
+
+One foundation per pipeline. These are separate, named pipelines or consumer
+work:
+
+- **TypeScript content plane** (a provider in `cultmesh-ts`, a verifying HTTPS
+  reader in `cultmesh-browser`) for exported character artifacts. HTTPS content
+  transport and single-host trust on Yggdrasil were already ruled.
+- **Authenticated remote control plane** (TLS on the TCP schema and content
+  connectors). See Q1.
+- **Browser QUIC** (WebTransport). Browsers keep the verified WebSocket path.
+- **Python, Rust, and Kotlin QUIC.** The parity scope is role-scoped; this
+  migration claims TypeScript and C# only.
+- **StreamPixels integration** (service publication, overlay subscription, and
+  the catalog and scene-intent schemas) is consumer work in StreamPixels after a
+  released `cultmesh-ts` exists.
+
+## Verification the cut must reach
+
+- Golden frame bytes from the C# codec decode in TypeScript, and TypeScript
+  encodings decode in C#, for every delivery mode and at the length limits.
+  Malformed inputs are rejected identically.
+- Separate processes, both directions: a TypeScript provider to the C# native
+  connector (the one Unity uses) and to the managed connector, and a C# managed
+  provider to the TypeScript consumer. Extend the existing parity harnesses
+  (`CULTMESH_NATIVE_EXTERNAL_ENDPOINT`, `packages/cultnet-ts/test/interop`) rather
+  than adding a parallel one.
+- `LatestOnly` coalescing: a stalled consumer does not delay the producer, and
+  the consumer converges on the terminal generation.
+- Trust negatives: an expired or unsigned route, the wrong Odin root, a
+  mismatched `cert-sha256` pin, and a replayed nonce are each refused, with a
+  mutation per rule.
+- The Linux x64 binary runs on the Yggdrasil deploy path, verified on that host.
+
+## Rulings (operator, 2026-09-16)
+
+The operator accepted every recommendation below ("You got it"). Each question
+is kept with its options as the record of what was decided against.
+
+- **Q1. Which remote plane carries the overlay's non-frame data?** The realtime
+  plane forbids schemas, commands, and content, and the TCP planes are
+  loopback-only. A: publish her character, the subathon window, and scene
+  intents as QUIC state frames with their CultCache schema id and payload, and
+  ship the costume catalog as a versioned immutable artifact on the HTTPS
+  content plane; the overlay sends no commands, so it needs no remote control
+  plane. B: add TLS to the TCP schema and content connectors as its own
+  pipeline first. **Recommended: A.** It needs no new plane for M1, matches a
+  receive-only client, and leaves TLS TCP to the first consumer that sends
+  commands.
+- **Q2. Where does shared TypeScript route verification live?** It is inside
+  `cultmesh-browser` today, and `cultmesh-ts` is Node-only. A: move it to a
+  browser-safe shared module that both import (for example beside
+  `cultnet-ts/contracts`). B: have `cultmesh-ts` depend on `cultmesh-browser`.
+  **Recommended: A**, so neither transport package owns the other's trust.
+- **Q3. Which platforms must the native binding support at release?**
+  **Recommended: Windows x64 and Linux x64 only**, the two hosts that run it
+  today.
+- **Q4. Are QUIC datagrams (`Unreliable`) in scope?** **Recommended: no.** Fail
+  closed like the managed C# adapter; no consumer needs them.

native/GameCult.Mesh.Quic.Native/CMakeLists.txt

@@ -1,20 +1,94 @@
 cmake_minimum_required(VERSION 3.24)
 project(gamecult_mesh_quic_native LANGUAGES CXX)
 
-if(NOT WIN32)
-  message(FATAL_ERROR "The current CultMesh native QUIC connector supports Windows desktop only")
-endif()
-if(NOT DEFINED MSQUIC_ROOT)
-  message(FATAL_ERROR "MSQUIC_ROOT must point at the extracted Microsoft.Native.Quic.MsQuic.Schannel package build/native directory")
+# Two platforms, one source. Windows takes MsQuic from the pinned OpenSSL NuGet
+# layout (MSQUIC_ROOT); Linux takes it from the extracted libmsquic deb, whose
+# headers and library land in unrelated places, so they are named separately.
+if(NOT WIN32 AND NOT (CMAKE_SYSTEM_NAME STREQUAL "Linux"))
+  message(FATAL_ERROR "The CultMesh native QUIC bridge supports Windows x64 and Linux x64")
 endif()
 
 add_library(gamecult_mesh_quic_native SHARED cultmesh_quic_native.cpp)
 target_compile_features(gamecult_mesh_quic_native PRIVATE cxx_std_20)
-target_compile_definitions(gamecult_mesh_quic_native PRIVATE GAMECULT_MESH_QUIC_NATIVE_EXPORTS WIN32_LEAN_AND_MEAN NOMINMAX)
-target_include_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_ROOT}/include")
-target_link_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_ROOT}/lib/x64")
-target_link_libraries(gamecult_mesh_quic_native PRIVATE msquic crypt32 bcrypt)
+# include/cultmesh_quic_native.h is the host-facing contract, not an internal
+# detail: the bridge includes it, and so does any consumer that can.
+target_include_directories(gamecult_mesh_quic_native PUBLIC include)
+
+if(WIN32)
+  if(NOT DEFINED MSQUIC_ROOT)
+    message(FATAL_ERROR "MSQUIC_ROOT must point at the extracted Microsoft.Native.Quic.MsQuic.OpenSSL package build/native directory")
+  endif()
+  # Static CRT. A Node or Unity host without the Visual C++ redistributable
+  # installed cannot load a DLL that imports vcruntime140.dll, and the failure
+  # arrives as "the specified module could not be found" with nothing naming the
+  # missing runtime. The bridge carries its own instead.
+  set_property(TARGET gamecult_mesh_quic_native PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded")
+  target_compile_definitions(gamecult_mesh_quic_native PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
+  target_include_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_ROOT}/include")
+  target_link_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_ROOT}/lib/x64")
+  # crypt32 and bcrypt belong to the v1 shim alone: CryptHashCertificate2
+  # compares the Unity pin. Nothing in the v2 path needs them. ntdll carries
+  # RtlIpv4/6StringToAddressEx, which msquic_winuser.h's inline QuicAddrFromString
+  # calls to parse the listener host; the Linux header parses it in-tree instead.
+  target_link_libraries(gamecult_mesh_quic_native PRIVATE msquic crypt32 bcrypt ntdll)
+  # The DLL is committed beside its source, so a rebuild must reproduce it: /Brepro drops the link timestamps.
+  target_compile_options(gamecult_mesh_quic_native PRIVATE /Brepro)
+  target_link_options(gamecult_mesh_quic_native PRIVATE /Brepro)
+else()
+  if(NOT DEFINED MSQUIC_INCLUDE_DIR OR NOT DEFINED MSQUIC_LIB_DIR)
+    message(FATAL_ERROR "MSQUIC_INCLUDE_DIR and MSQUIC_LIB_DIR must point at the msquic v2.5.9 headers and the extracted libmsquic library directory")
+  endif()
+  target_include_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_INCLUDE_DIR}")
+  target_link_directories(gamecult_mesh_quic_native PRIVATE "${MSQUIC_LIB_DIR}")
+  target_link_libraries(gamecult_mesh_quic_native PRIVATE msquic pthread)
+  # Only the CULTMESH_API exports leave the .so; everything else stays internal.
+  target_compile_options(gamecult_mesh_quic_native PRIVATE -fvisibility=hidden -fvisibility-inlines-hidden)
+  # libmsquic.so.2 ships beside the bridge rather than being installed
+  # system-wide, so the loader is pointed at the bridge's own directory.
+  set_target_properties(gamecult_mesh_quic_native PROPERTIES
+    BUILD_WITH_INSTALL_RPATH TRUE
+    INSTALL_RPATH "$ORIGIN")
+endif()
 
 set_target_properties(gamecult_mesh_quic_native PROPERTIES
   OUTPUT_NAME "gamecult_mesh_quic_native"
-  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
+  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+
+# The runtime-lifetime scenarios. Off by default: the shipped artifact is the
+# library alone, and a delivery build has no business producing an executable.
+# CULTMESH_QUIC_DEBUG_ASSERTS goes with them, never into a shipped binary — it
+# makes the bridge state the quiesce invariant instead of leaving it to whatever
+# a sanitizer happens to catch.
+option(CULTMESH_QUIC_BUILD_TESTS "Build the runtime-lifetime scenario runner" OFF)
+option(CULTMESH_QUIC_DEBUG_ASSERTS "Abort the bridge on a violated internal invariant" OFF)
+
+if(CULTMESH_QUIC_DEBUG_ASSERTS)
+  target_compile_definitions(gamecult_mesh_quic_native PRIVATE CULTMESH_QUIC_DEBUG_ASSERTS)
+endif()
+
+if(CULTMESH_QUIC_BUILD_TESTS)
+  add_executable(cultmesh_quic_native_tests tests/cultmesh_quic_native_tests.cpp)
+  target_compile_features(cultmesh_quic_native_tests PRIVATE cxx_std_20)
+  # The header only. The scenarios drive the bridge as a host does, so they get
+  # no more of it than a host has.
+  target_link_libraries(cultmesh_quic_native_tests PRIVATE gamecult_mesh_quic_native)
+  # The scenarios see the development seam (section 7 of the header) exactly when
+  # the library has one, so `holdclose` compiles out of the same builds the
+  # bridge's own assertions compile out of.
+  if(CULTMESH_QUIC_DEBUG_ASSERTS)
+    target_compile_definitions(cultmesh_quic_native_tests PRIVATE CULTMESH_QUIC_DEBUG_ASSERTS)
+  endif()
+  set_target_properties(cultmesh_quic_native_tests PROPERTIES
+    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+  if(NOT WIN32)
+    target_link_libraries(cultmesh_quic_native_tests PRIVATE pthread)
+    # The linker resolves the bridge's own NEEDED libmsquic.so.2 while linking
+    # this executable, and the runtime copy only lands beside the binaries after
+    # the build; point it at the extracted package instead.
+    target_link_options(cultmesh_quic_native_tests PRIVATE "-Wl,-rpath-link,${MSQUIC_LIB_DIR}")
+    set_target_properties(cultmesh_quic_native_tests PROPERTIES
+      BUILD_WITH_INSTALL_RPATH TRUE
+      INSTALL_RPATH "$ORIGIN")
+  endif()
+endif()

native/GameCult.Mesh.Quic.Native/README.md

@@ -1,10 +1,130 @@
 # GameCult.Mesh.Quic.Native
 
-This Windows desktop bridge keeps MsQuic's callback-heavy C API below the
-managed runtime boundary. It accepts a discovery-authorized SHA-256 certificate
-pin, negotiates `cultmesh-state-v1`, and emits complete CultMesh realtime frame
-payloads. It owns transport only; frame meaning remains in `GameCult.Mesh`.
+One MsQuic body for every CultMesh host that is not .NET: two roles (provider
+and consumer), two platforms (Windows x64 and Linux x64), and no callbacks
+across the host boundary.
 
-The build consumes Microsoft's pinned
-`Microsoft.Native.Quic.MsQuic.Schannel` package. It does not contain
-Aetheria-specific code.
+The bridge owns MsQuic registration, configuration, listener, connection and
+stream handles, TLS credential loading, the `cultmesh-state-v1` ALPN, the
+1-byte-kind plus 4-byte-LE-length QUIC stream framing, and one event queue per
+runtime. It owns transport and nothing else: it never decodes a CultMesh frame,
+never decides delivery semantics, never coalesces, never reconnects, and in the
+v2 path never decides whether to trust a certificate. Frame meaning stays in
+`GameCult.Mesh` and in the TypeScript codec; trust stays with the host.
+
+## No host callbacks
+
+Every crossing is the host calling in, including the one blocking wait. MsQuic's
+worker threads only ever push onto the queue and wake that wait, so no host
+runtime is called from a thread it does not own. That is what lets one binary
+serve a Node process through FFI and a Unity player through P/Invoke without
+either one's threading rules leaking into the other.
+
+It is also why nothing here includes a Node header, a Unity header, or a
+JavaScript engine: the bridge does not know what is on the other side.
+
+## Two ABIs
+
+**v2** is the runtime-neutral queue API, and the one new hosts should use. It is
+stated once, in [`include/cultmesh_quic_native.h`](include/cultmesh_quic_native.h):
+the 64-byte event struct with its field order and asserted offsets, the thirteen
+exports with their signatures, the id and return-code conventions, the object
+lifetime rules and the threading rules. That file is the contract. This README
+does not restate it, and where the two ever disagree the header is right.
+
+A host that can include it should. A host that cannot — koffi, Unity's
+P/Invoke — declares the same thing in its own FFI and is checked against the
+header by a test rather than by eye.
+
+Two things worth reading before writing a host, because they are easy to get
+wrong from the outside:
+
+- **Return codes are negative on a bad call, on every platform.** `-1` is a bad
+  call, `-2` a rejected argument, `<= -1000` a MsQuic refusal. `QUIC_STATUS`
+  itself is not portable — a negative HRESULT on Windows, a positive errno on
+  POSIX — so it never reaches a host; `cultmesh_quic_last_status` hands over the
+  raw value for diagnostics and nothing else.
+- **`cultmesh_quic_runtime_close` quiesces.** It marks the runtime closing, wakes
+  every blocked `cultmesh_quic_next_event`, and waits for every in-flight call to
+  return before it frees anything. No host call may begin after it starts.
+
+A client connection defers certificate validation: the bridge indicates the
+certificate, emits event 3 carrying the DER, and answers MsQuic only when the
+host calls `cultmesh_quic_connection_certificate_complete`. If the host never
+answers, MsQuic's 10-second handshake timeout closes the connection and event 4
+reports it. Providers load their certificate as PKCS12; the advertised
+`cert-sha256` pin is computed by the host from that same PKCS12, not here.
+
+**v1** is the five exports the shipped Unity package imports by name
+(`cultmesh_quic_open`, `_state`, `_poll`, `_error`, `_close`). They are Windows
+only, matching `CultMeshNativeQuicRealtimeTransport.CanConnect`, and are
+implemented on top of a private v2 runtime holding one connection. They decide
+nothing the v2 path does not, with one exception: a v1 connection carries a
+SHA-256 pin that is compared here, in C, because that is the contract the
+managed connector was built against. A v2 connection never carries one.
+
+## Building
+
+Windows x64, from the repo root:
+
+    powershell -File scripts/build-quic-native.ps1
+
+MsQuic comes from `Microsoft.Native.Quic.MsQuic.OpenSSL` 2.5.9, pinned twice: the
+NuGet zip by digest and size, and the `msquic.dll` inside it by digest and size,
+because the archive is what the download is checked against and the DLL is what
+actually ships beside the bridge. The OpenSSL flavour rather than Schannel
+because Schannel's MsQuic refuses `QUIC_CREDENTIAL_TYPE_CERTIFICATE_PKCS12`,
+which is the only credential type a provider has on both platforms.
+
+The build uses MSVC with `/Brepro` so that a build reproduces itself: the link
+timestamps are dropped, and building the same source twice gives the same bytes.
+It links the CRT statically (`/MT`), because a Node or Unity host without the
+Visual C++ redistributable cannot load a DLL that imports `vcruntime140.dll`,
+and the failure it reports names no missing runtime; the bridge carries its own.
+
+A rebuild does not reproduce the committed Unity plugin. That plugin
+(`unity/org.gamecult.cultlib/Runtime/Plugins/x86_64/gamecult_mesh_quic_native.dll`,
+40,448 bytes) is the older build — before `/MT` and before the move off
+Schannel — and it still imports `VCRUNTIME140.dll` and `MSVCP140.dll`. The
+current source builds to 302,080 bytes with no CRT import. The committed plugin
+stays the older build until the Unity package build runs and replaces it.
+
+Linux x64, on a Debian 13 host:
+
+    scripts/build-quic-native.sh
+
+MsQuic comes from Microsoft's Debian 13 pool as a pinned `.deb`, and the POSIX
+headers from the msquic source tree at the matching tag; all four downloads are
+verified by SHA-256. The bridge is linked with `-fvisibility=hidden` so only the
+v2 exports leave the `.so`, and with `RPATH $ORIGIN` so the `libmsquic.so.2`
+shipped beside it resolves without being installed system-wide.
+
+A Linux host still needs MsQuic's own runtime dependencies present:
+`libssl3t64`, `libnuma1`, `libxdp1`, `libnl-route-3-200`.
+
+The development loop for it is one committed image,
+[`scripts/quic-native-linux-dev.Dockerfile`](../../scripts/quic-native-linux-dev.Dockerfile),
+pinned to the same `debian:13` digest the release workflow builds in. It carries
+the toolchain, MsQuic's runtime dependencies, `setarch`, and Node, because the
+mutation harness that drives the runtime-lifetime scenarios is a Node script and
+a container that cannot run it cannot check the bridge it just built:
+
+    docker build -t cultlib-quic-native-dev -f scripts/quic-native-linux-dev.Dockerfile scripts
+    docker run --rm --security-opt seccomp=unconfined -v "${PWD}:/src" -w /src `
+        cultlib-quic-native-dev bash -lc "scripts/build-quic-native.sh && node scripts/mutate-cultmesh.mjs native"
+
+Both lines are run from the repository root, and the mount is that root wherever
+it is: `${PWD}` in PowerShell, `$(pwd)` in a POSIX shell.
+
+`--security-opt seccomp=unconfined` is load-bearing, not caution. The
+ThreadSanitizer configuration needs the process's address space where it expects
+it, so `scripts/mutate-cultmesh.mjs` re-executes those runs under `setarch -R`,
+which asks the kernel for `personality(ADDR_NO_RANDOMIZE)`. Docker's default
+seccomp profile denies that call. Without it ThreadSanitizer dies before `main`
+with "unexpected memory mapping" — a configuration that never starts, which a
+mutation harness would otherwise read as every mutant being killed. The harness
+stops with that diagnosis rather than reporting kills it did not earn.
+
+Where an artifact was built is part of what it is. The Linux binary is linked
+against Debian 13's glibc, so a build from anywhere else is a different artifact
+whatever the file name says.

native/GameCult.Mesh.Quic.Native/include/cultmesh_quic_native.h

@@ -0,0 +1,350 @@
+/* GameCult.Mesh.Quic.Native — C ABI v2, the runtime-neutral CultMesh QUIC bridge.
+ *
+ * This header is the contract. It is the single place the event layout, the
+ * exports, the id and return-code conventions, the object lifetime rules and the
+ * threading rules are stated; `cultmesh_quic_native.cpp` includes it, the README
+ * points at it, and a host that cannot include it (koffi, P/Invoke) declares the
+ * same thing in its own FFI and is checked against this file by a test.
+ *
+ * It is C. It includes nothing of MsQuic, nothing of Node, nothing of Unity, and
+ * nothing platform-specific: a host binds these twelve queue exports plus
+ * `cultmesh_quic_last_status` and needs no other build input.
+ *
+ * The v1 Unity exports (`cultmesh_quic_open`, `_state`, `_poll`, `_error`,
+ * `_close`) are deliberately not here. They are a Windows-only shim for a
+ * shipped managed connector, not a contract offered to new hosts.
+ */
+
+#ifndef CULTMESH_QUIC_NATIVE_H
+#define CULTMESH_QUIC_NATIVE_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus)
+#define CULTMESH_QUIC_STATIC_ASSERT(condition, message) static_assert(condition, message)
+#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
+#define CULTMESH_QUIC_STATIC_ASSERT(condition, message) _Static_assert(condition, message)
+#else
+#define CULTMESH_QUIC_STATIC_ASSERT(condition, message)
+#endif
+
+/* `CULTMESH_QUIC_BUILD` is defined by the bridge's own translation unit and by
+ * nothing else. A consumer gets plain declarations and links by name, which is
+ * what every host here does: all three load the library at runtime. */
+#if defined(CULTMESH_QUIC_BUILD)
+#  if defined(_WIN32)
+#    define CULTMESH_QUIC_API __declspec(dllexport)
+#  else
+#    define CULTMESH_QUIC_API __attribute__((visibility("default")))
+#  endif
+#else
+#  define CULTMESH_QUIC_API
+#endif
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/* ---------------------------------------------------------------------------
+ * 1. The event
+ *
+ * Exactly 64 bytes, no implicit padding, field order below is the ABI. A host
+ * that reorders a field reads a different struct; the offsets are asserted here
+ * so a compiler that pads differently fails the build rather than the wire.
+ * --------------------------------------------------------------------------- */
+
+struct cultmesh_quic_event {
+    uint32_t type;           /* offset  0 — one of the cultmesh_quic_event_type values */
+    uint32_t stream_kind;    /* offset  4 — 1 reliable, 2 latest-only; 0 when not a stream event */
+    uint64_t listener_id;    /* offset  8 — 0 for an outbound connection */
+    uint64_t connection_id;  /* offset 16 */
+    uint64_t stream_id;      /* offset 24 */
+    uint64_t code;           /* offset 32 — meaning depends on `type`; see below */
+    int32_t  status;         /* offset 40 — the raw platform QUIC status, diagnostics only */
+    int32_t  payload_length; /* offset 44 — bytes written into the caller's payload buffer */
+    uint8_t  reserved[16];   /* offset 48 — zero today; do not read meaning into it */
+};
+
+CULTMESH_QUIC_STATIC_ASSERT(sizeof(struct cultmesh_quic_event) == 64,
+    "the event struct is a 64-byte ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, type) == 0,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, stream_kind) == 4,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, listener_id) == 8,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, connection_id) == 16,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, stream_id) == 24,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, code) == 32,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, status) == 40,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, payload_length) == 44,
+    "event field offsets are an ABI contract");
+CULTMESH_QUIC_STATIC_ASSERT(offsetof(struct cultmesh_quic_event, reserved) == 48,
+    "event field offsets are an ABI contract");
+
+enum cultmesh_quic_event_type {
+    /* A listener accepted an inbound connection. `listener_id`, `connection_id`. */
+    CULTMESH_QUIC_EVENT_LISTENER_NEW_CONNECTION = 1,
+    /* The handshake completed. `connection_id`. */
+    CULTMESH_QUIC_EVENT_CONNECTION_CONNECTED = 2,
+    /* Payload: the peer's DER certificate. The handshake is blocked until the
+     * host answers with `cultmesh_quic_connection_certificate_complete`. */
+    CULTMESH_QUIC_EVENT_CONNECTION_CERTIFICATE_RECEIVED = 3,
+    /* The connection is gone, whoever ended it, and its id no longer resolves.
+     * Payload: a UTF-8 reason. `code` is the QUIC application error code — the
+     * peer's when the peer ended it, and the code the host passed to
+     * `cultmesh_quic_connection_shutdown` when the host did. Emitted exactly
+     * once per connection id, including for the initiator of a local shutdown:
+     * every connection id's end is observable from the host that owns it. */
+    CULTMESH_QUIC_EVENT_CONNECTION_SHUTDOWN = 4,
+    /* An inbound stream's first byte named its kind. `stream_id`, `stream_kind`. */
+    CULTMESH_QUIC_EVENT_STREAM_STARTED = 5,
+    /* Payload: one whole encoded frame, the 4-byte length prefix stripped. */
+    CULTMESH_QUIC_EVENT_STREAM_FRAME = 6,
+    /* One per `cultmesh_quic_stream_send_frame` call that returned 0, and never
+     * for the bridge's own kind byte. `code` is a cultmesh_quic_send_result. */
+    CULTMESH_QUIC_EVENT_STREAM_SEND_COMPLETE = 7,
+    /* The stream is gone. `stream_id`, `stream_kind`. */
+    CULTMESH_QUIC_EVENT_STREAM_SHUTDOWN = 8,
+    /* The listener stopped. `listener_id`. */
+    CULTMESH_QUIC_EVENT_LISTENER_STOPPED = 9
+};
+
+/* The `code` of event 7. A canceled send is a send MsQuic released without
+ * putting on the wire — the stream was aborted or the connection ended under it.
+ * It is reported, not silently dropped. */
+enum cultmesh_quic_send_result {
+    CULTMESH_QUIC_SEND_COMPLETED = 0,
+    CULTMESH_QUIC_SEND_CANCELED = 1
+};
+
+/* The first byte of every CultMesh QUIC stream. */
+enum cultmesh_quic_stream_kind {
+    CULTMESH_QUIC_STREAM_RELIABLE = 1,
+    CULTMESH_QUIC_STREAM_LATEST_ONLY = 2
+};
+
+/* ---------------------------------------------------------------------------
+ * 2. Ids
+ *
+ * Listeners, connections and streams are named by `uint64_t` ids drawn from one
+ * per-runtime counter that starts at 1 and never repeats. 0 is never a valid id
+ * and is what an out parameter holds when a call fails. An id is the only thing
+ * a host ever holds: there is no host-visible pointer to a connection or stream,
+ * so a host cannot outlive an object it is naming. An id whose object is gone is
+ * a bad call (-1), not undefined behaviour.
+ * --------------------------------------------------------------------------- */
+
+/* ---------------------------------------------------------------------------
+ * 3. Return codes — negative on a bad call, on every platform
+ *
+ * Every int32_t-returning export returns:
+ *
+ *    0                        the call succeeded
+ *    1, 2                     `cultmesh_quic_next_event` only; see its comment
+ *   -1                        a bad call: a null handle, a null out parameter,
+ *                             or an id whose object is gone
+ *   -2                        an argument the bridge rejects on its own terms:
+ *                             an unknown stream kind, an oversized frame, a
+ *                             listener host that is not an IP literal
+ *   <= -1000                  MsQuic refused. The bridge code is
+ *                             -(1000 + (raw_status & 0xffff)); the raw
+ *                             platform status is available from
+ *                             `cultmesh_quic_last_status` and a sentence about
+ *                             it from `cultmesh_quic_last_error`.
+ *
+ * This mapping exists because `QUIC_STATUS` itself is not portable: it is a
+ * negative HRESULT on Windows and a positive errno on POSIX, so a host that
+ * checked for a negative value saw every Linux failure as success.
+ *
+ * What the mapping makes portable is the sign, and only the sign. A failure is
+ * negative everywhere, and that is what a host may branch on. The magnitude of a
+ * <= -1000 code is diagnostic and platform-specific: the same MsQuic failure
+ * carries different numbers on different platforms (a TLS error is -12032 on
+ * win32-x64 and -1126 on linux-x64; an ALPN already in use is -1009 against
+ * -1091), and the 16-bit mask can give two distinct statuses the same code
+ * (`QUIC_STATUS_USER_CANCELED` and `QUIC_STATUS_FILE_NOT_FOUND` are both -1002
+ * on Windows). Switching on a particular code is therefore not portable and not
+ * a reliable identification of the failure. Report it, log it, and read
+ * `cultmesh_quic_last_status` and `cultmesh_quic_last_error` beside it.
+ * --------------------------------------------------------------------------- */
+
+#define CULTMESH_QUIC_RESULT_BAD_CALL (-1)
+#define CULTMESH_QUIC_RESULT_BAD_ARGUMENT (-2)
+#define CULTMESH_QUIC_RESULT_MSQUIC_BASE (-1000)
+
+/* ---------------------------------------------------------------------------
+ * 4. Object lifetime — resolved from an id, kept alive across the call
+ *
+ * The bridge's objects are shared-owned. The runtime's maps hold one reference
+ * each; an export that names an id takes its own reference under the lock and
+ * holds it for the whole MsQuic call, so an object cannot be freed under a host
+ * thread that is using it. MsQuic's worker, on shutdown-complete, removes the
+ * map entry and drops the map's reference only — it never frees an object a host
+ * call is inside.
+ *
+ * The MsQuic handle follows the object: it is closed exactly once, by whichever
+ * holder drops the last reference (or by `cultmesh_quic_runtime_close`), under a
+ * one-shot exchange guard. A handle is therefore valid for as long as any holder
+ * has a reference to its object, which is the property the host thread needs. A
+ * stream holds a reference to its connection, so stream handles are always
+ * closed before the connection handle they belong to.
+ *
+ * `cultmesh_quic_runtime_close` quiesces before it tears anything down. It marks
+ * the runtime closing, wakes every blocked `cultmesh_quic_next_event`, and waits
+ * for every in-flight export to return before it closes a handle or frees a
+ * byte. No host call may begin after `cultmesh_quic_runtime_close` starts. That
+ * ordering is the host's, and it is a prohibition rather than a race the bridge
+ * arbitrates: once the close returns, the handle names freed memory, and a call
+ * made with it has nothing left to refuse it. A call that races the start of the
+ * close, while it is still running, is refused with -1 and touches nothing; that
+ * narrows one mis-ordering and does not make the prohibition optional.
+ * --------------------------------------------------------------------------- */
+
+/* ---------------------------------------------------------------------------
+ * 5. Threading
+ *
+ * There are no host callbacks. Every crossing is the host calling in.
+ *
+ *  - MsQuic's worker threads run inside this library only. They push events onto
+ *    the runtime's queue and wake the one blocking wait. No host code is ever
+ *    called from a thread the host does not own.
+ *  - `cultmesh_quic_next_event` is called from host threads, one or many. It is
+ *    the only blocking export. Concurrent callers each get a distinct event.
+ *  - Every other export may be called from any host thread at any time, except
+ *    during or after `cultmesh_quic_runtime_close`.
+ *  - `cultmesh_quic_runtime_close` is called once, from one thread, and
+ *    quiesces as described above.
+ * --------------------------------------------------------------------------- */
+
+/* ---------------------------------------------------------------------------
+ * 6. The exports
+ * --------------------------------------------------------------------------- */
+
+/* Opens a runtime: one MsQuic registration, one event queue. `app_name` may be
+ * null. `*out_runtime` is the opaque handle every other export takes. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_runtime_open(
+    const char* app_name, void** out_runtime);
+
+/* Quiesces, tears down and frees the runtime. Safe to call with null. After it
+ * returns, the handle is dead; see section 4 for the ordering rule. */
+CULTMESH_QUIC_API void cultmesh_quic_runtime_close(void* runtime);
+
+/* Opens a provider listener on `host`:`port` with a PKCS12 credential. `host`
+ * may be null or empty for any address, otherwise it must be an IP literal.
+ * `port` 0 binds an ephemeral port, which `*out_bound_port` reports. A failure
+ * leaves no listener behind and no id allocated to the host. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_listener_open(
+    void* runtime, const char* host, uint16_t port,
+    const uint8_t* pkcs12, int32_t pkcs12_length, const char* password,
+    uint64_t* out_listener_id, uint16_t* out_bound_port);
+
+/* Stops and closes a listener. Its accepted connections are not affected.
+ * Emits event 9. Unknown ids are ignored. */
+CULTMESH_QUIC_API void cultmesh_quic_listener_close(
+    void* runtime, uint64_t listener_id);
+
+/* Starts an outbound connection. Certificate validation is deferred: the host
+ * gets event 3 and must answer. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_connection_open(
+    void* runtime, const char* host, uint16_t port, uint64_t* out_connection_id);
+
+/* Answers event 3. `accept` non-zero continues the handshake; zero fails it with
+ * a bad-certificate alert. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_connection_certificate_complete(
+    void* runtime, uint64_t connection_id, int32_t accept);
+
+/* Ends a connection with a QUIC application error code. The initiator gets its
+ * own event 4 carrying `code`, as the peer does. Unknown ids are ignored. */
+CULTMESH_QUIC_API void cultmesh_quic_connection_shutdown(
+    void* runtime, uint64_t connection_id, uint64_t code);
+
+/* Opens an outbound unidirectional stream and puts `kind` on the wire as its
+ * first byte. That byte is the bridge's own and never produces an event 7. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_stream_open(
+    void* runtime, uint64_t connection_id, uint8_t kind, uint64_t* out_stream_id);
+
+/* Queues one whole encoded frame, length-prefixed by the bridge. A call that
+ * returns 0 produces exactly one event 7 later, completed or canceled. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_stream_send_frame(
+    void* runtime, uint64_t stream_id,
+    const uint8_t* encoded_frame, int32_t length, int32_t fin);
+
+/* Aborts a stream with a QUIC application error code. Unknown ids are ignored. */
+CULTMESH_QUIC_API void cultmesh_quic_stream_shutdown(
+    void* runtime, uint64_t stream_id, uint64_t code);
+
+/* The one blocking crossing.
+ *
+ *   0   nothing within `timeout_ms`. A poller already blocked here when
+ *       `cultmesh_quic_runtime_close` starts is woken and returns 0. A poll that
+ *       begins after the close starts is forbidden by section 4, and is not a
+ *       case this return code covers.
+ *   1   `*out_event` filled and up to `payload_capacity` payload bytes copied;
+ *       `*out_required` is the payload size
+ *   2   `payload_capacity` is too small. Nothing is consumed and nothing is
+ *       written to `*out_event`; `*out_required` is the size to allocate. Ask
+ *       again with a big enough buffer and the same event is delivered.
+ *  -1   a bad call, including a null `payload` with a non-zero
+ *       `payload_capacity`, which is a lie about the buffer and is refused
+ *       rather than treated as a discard.
+ *
+ * `payload` may be null when `payload_capacity` is 0: that is the two-phase
+ * poll's first ask. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_next_event(
+    void* runtime, int32_t timeout_ms, struct cultmesh_quic_event* out_event,
+    uint8_t* payload, int32_t payload_capacity, int32_t* out_required);
+
+/* The last error sentence, NUL-terminated, truncated to `capacity`. Returns the
+ * number of bytes written, or -1 on a bad call. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_last_error(
+    void* runtime, char* destination, int32_t capacity);
+
+/* The raw platform `QUIC_STATUS` behind the last <= -1000 return, as its own
+ * bits: a negative HRESULT on Windows, a positive errno on POSIX. Diagnostics
+ * only; what is portable about the return code is its sign, not its value. 0
+ * when nothing has failed. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_last_status(void* runtime);
+
+/* ---------------------------------------------------------------------------
+ * 7. The development seam
+ *
+ * Present only in a library configured with `CULTMESH_QUIC_DEBUG_ASSERTS`, which
+ * a shipped build never is. It exists for the runtime-lifetime scenarios: the
+ * quiesce is a promise about host calls that are inside the library, and a
+ * scenario that can only sleep and hope cannot tell a bridge that counts them
+ * from one that does not.
+ *
+ * It is process-wide, not per-runtime, because the numbers outlive the runtime
+ * they describe: `cultmesh_quic_runtime_close` frees the runtime, and the count
+ * it waited on is read afterwards. The scenarios open one runtime at a time.
+ * --------------------------------------------------------------------------- */
+#if defined(CULTMESH_QUIC_DEBUG_ASSERTS)
+
+/* Non-zero arms the hold and resets both counters: every call that reaches the
+ * blocking wait in `cultmesh_quic_next_event` parks inside the library instead
+ * of returning. Zero releases every held call and disarms it. A held call
+ * returns 0 and touches the runtime no further. */
+CULTMESH_QUIC_API void cultmesh_quic_debug_hold_calls(int32_t hold);
+
+/* The high-water mark of host calls counted inside the library since the hold
+ * was armed. Zero means no call was ever counted. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_debug_peak_calls(void);
+
+/* How many host calls were counted inside the library when the last
+ * `cultmesh_quic_runtime_close` began its wait, or -1 if no close has begun one
+ * since the hold was armed. This is the number the wait exists for. */
+CULTMESH_QUIC_API int32_t cultmesh_quic_debug_calls_at_close(void);
+
+#endif /* CULTMESH_QUIC_DEBUG_ASSERTS */
+
+#if defined(__cplusplus)
+}
+#endif
+
+#endif /* CULTMESH_QUIC_NATIVE_H */

native/GameCult.Mesh.Quic.Native/tests/cultmesh_quic_native_tests.cpp

@@ -0,0 +1,615 @@
+// Scenario runner for the bridge's runtime lifetime rules.
+//
+// This is the one part of the bridge a host cannot check by reading: whether
+// `cultmesh_quic_runtime_close` is safe against host threads that are inside the
+// library when it starts. Everything here drives that path and nothing else. It
+// opens a runtime, parks pollers in `cultmesh_quic_next_event`, closes the
+// runtime underneath them, and asserts what the header promises: every parked
+// poller returns, and none of them touches the runtime after it is gone.
+//
+// It consumes the bridge through include/cultmesh_quic_native.h — the same
+// contract a host has — and nothing else. No MsQuic header, no internals.
+//
+// The failures it exists to catch are not visible in the return values, because
+// a use-after-free is not an error code. Two things make them visible instead:
+// a sanitizer build (ThreadSanitizer for the notify/destroy race, AddressSanitizer
+// for the freed-runtime dereference), and `CULTMESH_QUIC_DEBUG_ASSERTS`, which
+// makes the bridge state the quiesce invariant itself rather than leaving it to
+// be caught by an unlucky thread schedule.
+//
+//   cultmesh_quic_native_tests closerace [iterations] [pollers]
+//   cultmesh_quic_native_tests holdclose [iterations] [pollers]
+//   cultmesh_quic_native_tests polltimeout [iterations]
+//   cultmesh_quic_native_tests latecall [iterations]
+//
+// `closerace` hunts the race: many pollers, many iterations, and whatever the
+// schedule gives. `holdclose` takes the guessing out of it — the bridge's
+// development seam (section 7 of the header) holds the pollers inside the
+// library until this scenario releases them, and reports how many host calls the
+// bridge actually counted, so the scenario asserts the quiesce instead of
+// assuming its own fixture worked. It needs CULTMESH_QUIC_DEBUG_ASSERTS.
+//
+// In both of those the wait is ended by the close, so the host's timeout governs
+// nothing either of them can see, and a bridge waiting on a constant of its own
+// passes both. `polltimeout` is the one that lets the timeout govern the return
+// and measures it. `latecall` covers the other half of section 4: a call that
+// races the start of a close is refused rather than counted behind its wait.
+//
+// Exit code 0 means every assertion held. Anything else, including a sanitizer
+// abort or the bridge's own assertion, is a failure. Under ThreadSanitizer run
+// it with `TSAN_OPTIONS=halt_on_error=1`, or a reported race leaves the exit
+// code to the last thing that set it.
+
+#include <cultmesh_quic_native.h>
+
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace {
+
+// Long enough that a poller is still parked when the close begins. The close is
+// what ends the wait; this timeout only bounds the scenario if the close never
+// arrives, which is itself the failure.
+constexpr int32_t kPollTimeoutMs = 5000;
+
+// A poller asks for a payload buffer, so the close races a `next_event` that has
+// somewhere to copy into rather than one that can only ever return 0.
+constexpr int32_t kPayloadCapacity = 4096;
+
+int Fail(const std::string& message) {
+    std::fprintf(stderr, "FAILED: %s\n", message.c_str());
+    return 1;
+}
+
+// One iteration: `pollers` threads parked in `next_event`, then a close under
+// them. Returns an empty string when every promise held.
+//
+// Each poller makes exactly one blocking call and does not call again. Section 5
+// of the header puts the ordering on the host — no call may *begin* during a
+// close — so a scenario that kept re-entering would be testing a shape the
+// bridge declines to support, and its report would be the harness's own fault.
+// A call already inside the library is the case the quiesce exists for, and that
+// is the one run here.
+std::string CloseRaceOnce(int pollers) {
+    void* runtime = nullptr;
+    const int32_t opened = cultmesh_quic_runtime_open("cultmesh-quic-native-tests", &runtime);
+    if (opened != 0 || runtime == nullptr)
+        return "cultmesh_quic_runtime_open returned " + std::to_string(opened);
+
+    // Counts threads about to enter the blocking call. The close waits for all of
+    // them, so the race is run with the pollers actually inside rather than with
+    // threads that have not started yet.
+    std::atomic<int> entering{0};
+    std::atomic<int> returned{0};
+    std::atomic<int> undefined_return{0};
+    std::atomic<int> timed_out{0};
+    // Set just before the close, and read by each poller as it returns. A poller
+    // that is already out by then was never in the race, and a scenario full of
+    // those passes without testing anything: this is what catches a bridge whose
+    // blocking crossing has stopped blocking.
+    std::atomic<bool> closing_started{false};
+    std::atomic<int> left_before_the_close{0};
+
+    std::vector<std::thread> threads;
+    threads.reserve(static_cast<size_t>(pollers));
+    for (int index = 0; index < pollers; ++index) {
+        threads.emplace_back([runtime, &entering, &returned, &undefined_return, &timed_out,
+                              &closing_started, &left_before_the_close] {
+            std::vector<uint8_t> payload(static_cast<size_t>(kPayloadCapacity));
+            cultmesh_quic_event event{};
+            int32_t required = 0;
+
+            entering.fetch_add(1);
+            const auto started = std::chrono::steady_clock::now();
+            // Parked here when the close arrives. `closing` wakes the wait; the
+            // call scope this thread holds is what the close must count out
+            // before it frees anything.
+            const int32_t result = cultmesh_quic_next_event(
+                runtime, kPollTimeoutMs, &event, payload.data(), kPayloadCapacity, &required);
+            const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+                std::chrono::steady_clock::now() - started).count();
+
+            if (result != 0 && result != 1 && result != 2) undefined_return.fetch_add(1);
+            // The close is what ends this wait. Sitting out the whole timeout
+            // instead means the wake never reached it.
+            if (elapsed >= kPollTimeoutMs / 2) timed_out.fetch_add(1);
+            if (!closing_started.load()) left_before_the_close.fetch_add(1);
+            returned.fetch_add(1);
+        });
+    }
+
+    while (entering.load() < pollers) std::this_thread::yield();
+    // Settle so the pollers are inside the blocking wait rather than on their way
+    // to it. A poller that has not entered yet is a call beginning during the
+    // close, which is the host's to avoid, not the bridge's to survive.
+    std::this_thread::sleep_for(std::chrono::milliseconds(50));
+
+    closing_started.store(true);
+    cultmesh_quic_runtime_close(runtime);
+    for (auto& thread : threads) thread.join();
+
+    if (left_before_the_close.load() != 0)
+        return std::to_string(left_before_the_close.load()) + " of " + std::to_string(pollers) +
+            " pollers returned before the close began, so they were never in the race";
+    if (undefined_return.load() != 0)
+        return std::to_string(undefined_return.load()) + " poller(s) saw a return the header does not define";
+    if (timed_out.load() != 0)
+        return std::to_string(timed_out.load()) + " of " + std::to_string(pollers) +
+            " pollers sat out the timeout instead of being woken by the close";
+    if (returned.load() != pollers)
+        return std::to_string(returned.load()) + " of " + std::to_string(pollers) + " pollers returned";
+    return {};
+}
+
+// The two timeouts `polltimeout` asks for. Two, and not one, because a single
+// value cannot tell a bridge that honours the host's timeout from one that waits
+// on that same number of its own: a constant has to satisfy both bands, and no
+// constant is in both.
+constexpr int32_t kShortPollMs = 200;
+constexpr int32_t kLongPollMs = 900;
+
+// How much sooner than the timeout a poll may return. A wait may be late; it may
+// not be early, because returning early is exactly what waiting on a shorter
+// duration looks like. This is scheduler granularity, not slack.
+constexpr int kEarlyToleranceMs = 20;
+
+// How much later than the timeout a poll may return. Wide enough for a loaded
+// machine and a container, and narrower than the gap between the two timeouts,
+// which is what closes the constant off: 200 admits [180, 500] and 900 admits
+// [880, 1200], and nothing is in both.
+constexpr int kLateToleranceMs = 300;
+
+struct TimedPoll {
+    int32_t result;
+    long long elapsed_ms;
+};
+
+TimedPoll PollFor(void* runtime, int32_t timeout_ms) {
+    std::vector<uint8_t> payload(static_cast<size_t>(kPayloadCapacity));
+    cultmesh_quic_event event{};
+    int32_t required = 0;
+    const auto started = std::chrono::steady_clock::now();
+    const int32_t result = cultmesh_quic_next_event(
+        runtime, timeout_ms, &event, payload.data(), kPayloadCapacity, &required);
+    const auto elapsed = std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - started).count();
+    return {result, elapsed};
+}
+
+// The host's timeout, and the only thing it is: how long a poll with nothing to
+// deliver stays inside the library. Nothing else here checks it — `closerace`
+// and `holdclose` both end their waits with a close, so in both of them the
+// bridge could wait on any duration at all and every assertion would still hold.
+// A runtime with no listener and no connection has nothing to deliver, so the
+// timeout is what ends this poll, and the elapsed time is what it waited on.
+std::string PollTimeoutOnce() {
+    void* runtime = nullptr;
+    const int32_t opened = cultmesh_quic_runtime_open("cultmesh-quic-native-tests", &runtime);
+    if (opened != 0 || runtime == nullptr)
+        return "cultmesh_quic_runtime_open returned " + std::to_string(opened);
+
+    std::string failure;
+    for (const int32_t timeout_ms : {kShortPollMs, kLongPollMs}) {
+        const TimedPoll poll = PollFor(runtime, timeout_ms);
+        const std::string asked = "a poll asking for " + std::to_string(timeout_ms) + " ms ";
+        if (poll.result != 0) {
+            failure = asked + "returned " + std::to_string(poll.result) +
+                ", not the 0 an idle runtime owes it";
+            break;
+        }
+        if (poll.elapsed_ms < timeout_ms - kEarlyToleranceMs) {
+            failure = asked + "returned after " + std::to_string(poll.elapsed_ms) +
+                " ms: the wait ended on some shorter duration than the one it was given";
+            break;
+        }
+        if (poll.elapsed_ms > timeout_ms + kLateToleranceMs) {
+            failure = asked + "returned after " + std::to_string(poll.elapsed_ms) +
+                " ms: the wait ended on some longer duration than the one it was given";
+            break;
+        }
+    }
+
+    cultmesh_quic_runtime_close(runtime);
+    return failure;
+}
+
+int PollTimeout(int iterations) {
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const std::string failure = PollTimeoutOnce();
+        if (!failure.empty())
+            return Fail("polltimeout iteration " + std::to_string(iteration) + ": " + failure);
+    }
+    std::printf("polltimeout %dx: ok\n", iterations);
+    return 0;
+}
+
+// Nothing listens on the discard port, so a connection to it fails and the
+// bridge says why. That reason is the payload this scenario needs, and reaching
+// it takes no listener, no credential and no established connection.
+constexpr uint16_t kClosedPort = 9;
+
+// How long the failure is given to arrive. The loopback refusal is immediate;
+// if the refusal is swallowed instead, MsQuic's own handshake timeout ends the
+// connection at 10 seconds and event 4 still arrives, so this only bounds a
+// bridge that reports nothing at all.
+constexpr int kEventDeadlineMs = 20000;
+
+// The bridge writes its own reason sentences and every one of them starts here.
+// Checking the bytes, and not only the length, is what separates a payload
+// copied out of the queued event from one copied out of an event that was popped
+// first: the second reads freed memory, which does not spell this.
+constexpr char kReasonPrefix[] = "CultMesh QUIC connection";
+
+// The two-phase poll, which is the shape every host uses to size its buffer:
+// ask with nothing, be told what it needs, ask again. What makes it work is that
+// the refusal consumes nothing — the event is still queued, payload and all,
+// after a return of 2 — and that the copy happens before the event is popped.
+// Both are section 6 of the header, and nothing committed reached either.
+std::string PayloadFitOnce() {
+    void* runtime = nullptr;
+    const int32_t opened = cultmesh_quic_runtime_open("cultmesh-quic-native-tests", &runtime);
+    if (opened != 0 || runtime == nullptr)
+        return "cultmesh_quic_runtime_open returned " + std::to_string(opened);
+
+    std::string failure;
+    uint64_t connection_id = 0;
+    const int32_t connecting =
+        cultmesh_quic_connection_open(runtime, "127.0.0.1", kClosedPort, &connection_id);
+    if (connecting != 0) {
+        cultmesh_quic_runtime_close(runtime);
+        return "cultmesh_quic_connection_open returned " + std::to_string(connecting);
+    }
+
+    // An out parameter the bridge must not write on a refusal, filled with
+    // something the bridge never writes so that a write is visible.
+    cultmesh_quic_event poisoned{};
+    std::memset(&poisoned, 0xab, sizeof(poisoned));
+    cultmesh_quic_event event = poisoned;
+    int32_t required = 0;
+    int32_t result = 0;
+
+    // Ask with no room at all until the event carrying the failure reason
+    // arrives. An event with no payload fits in nothing, so it is delivered and
+    // polled past rather than mistaken for this one.
+    const auto deadline = std::chrono::steady_clock::now() + std::chrono::milliseconds(kEventDeadlineMs);
+    for (;;) {
+        event = poisoned;
+        required = 0;
+        result = cultmesh_quic_next_event(runtime, 250, &event, nullptr, 0, &required);
+        if (result == 2 && required > 0) break;
+        if (result < 0) {
+            failure = "cultmesh_quic_next_event returned " + std::to_string(result);
+            break;
+        }
+        if (std::chrono::steady_clock::now() >= deadline) {
+            failure = "no event carrying a payload arrived within " +
+                std::to_string(kEventDeadlineMs) + " ms of a connection to a closed port";
+            break;
+        }
+    }
+
+    if (failure.empty() && std::memcmp(&event, &poisoned, sizeof(event)) != 0)
+        failure = "the refusal wrote to *out_event, which the header says it leaves alone";
+
+    // Again, with the same empty buffer: a refusal that consumed the event
+    // leaves nothing to find the second time.
+    if (failure.empty()) {
+        cultmesh_quic_event again = poisoned;
+        int32_t required_again = 0;
+        const int32_t second = cultmesh_quic_next_event(runtime, 0, &again, nullptr, 0, &required_again);
+        if (second != 2 || required_again != required)
+            failure = "the second ask returned " + std::to_string(second) + " needing " +
+                std::to_string(required_again) + ", not the 2 needing " + std::to_string(required) +
+                " the first one did: the refusal consumed the event";
+    }
+
+    // And with room, which is where the copy happens. The tail beyond the
+    // payload is written too, so a copy that ran past what it was told to write
+    // is visible.
+    if (failure.empty()) {
+        constexpr uint8_t kTail = 0x5a;
+        std::vector<uint8_t> payload(static_cast<size_t>(required) + 16, kTail);
+        cultmesh_quic_event delivered = poisoned;
+        int32_t required_delivered = 0;
+        const int32_t third = cultmesh_quic_next_event(
+            runtime, 0, &delivered, payload.data(), static_cast<int32_t>(payload.size()),
+            &required_delivered);
+        const std::string reason(reinterpret_cast<const char*>(payload.data()),
+            static_cast<size_t>(required));
+        if (third != 1 || required_delivered != required)
+            failure = "the ask with room returned " + std::to_string(third) + " needing " +
+                std::to_string(required_delivered) + ", not the 1 needing " +
+                std::to_string(required) + " the refusal promised";
+        else if (delivered.type != CULTMESH_QUIC_EVENT_CONNECTION_SHUTDOWN ||
+                 delivered.connection_id != connection_id ||
+                 delivered.payload_length != required)
+            failure = "the delivered event was type " + std::to_string(delivered.type) +
+                " on connection " + std::to_string(delivered.connection_id) + " carrying " +
+                std::to_string(delivered.payload_length) + " byte(s), not the failed connection's own";
+        else if (reason.rfind(kReasonPrefix, 0) != 0)
+            failure = "the payload delivered was '" + reason + "', not a reason this bridge writes";
+        else if (payload[static_cast<size_t>(required)] != kTail)
+            failure = "the copy wrote past the " + std::to_string(required) + " bytes it reported";
+    }
+
+    // Consumed now, and only now.
+    if (failure.empty()) {
+        cultmesh_quic_event emptied = poisoned;
+        int32_t required_emptied = 0;
+        const int32_t fourth =
+            cultmesh_quic_next_event(runtime, 0, &emptied, nullptr, 0, &required_emptied);
+        if (fourth != 0)
+            failure = "the event was still queued after being delivered: a further ask returned " +
+                std::to_string(fourth);
+    }
+
+    cultmesh_quic_runtime_close(runtime);
+    return failure;
+}
+
+int PayloadFit(int iterations) {
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const std::string failure = PayloadFitOnce();
+        if (!failure.empty())
+            return Fail("payloadfit iteration " + std::to_string(iteration) + ": " + failure);
+    }
+    std::printf("payloadfit %dx: ok\n", iterations);
+    return 0;
+}
+
+#if defined(CULTMESH_QUIC_DEBUG_ASSERTS)
+
+// How long a poll that does not block is given to prove it by returning, after
+// the calls have been counted and before the close begins. A bridge whose
+// blocking wait no longer blocks has emptied itself of host calls by the time
+// the close starts, and `calls_at_close` then says 0.
+constexpr int kSettleMs = 100;
+
+// How long the close is required to stay inside `cultmesh_quic_runtime_close`
+// while the pollers are held. The held calls are what it is waiting for, and
+// nothing releases them until this elapses, so a close that returns first gave
+// up on a call that was still inside. This bounds what the scenario can see: a
+// close that waits for longer than this and then gives up is not distinguished
+// from one that waits properly, which is the honest limit of the check.
+constexpr int kHeldWindowMs = 500;
+
+// How long the pollers are given to be counted inside the library before the
+// close begins. Reaching `pollers` is the normal path; the deadline only stops
+// a bridge that never counts them from hanging the scenario.
+constexpr int kCountedDeadlineMs = 2000;
+
+// One iteration of the quiesce itself, with the guesswork taken out: the pollers
+// are held inside the library by the bridge's own development seam until this
+// scenario lets them go, and the bridge says how many calls it counted rather
+// than the scenario assuming the schedule put them there.
+//
+// Three promises, and a mutation that breaks any one of them is seen here:
+//  - the calls are counted (`peak`), so a blocking crossing outside a call scope
+//    is not merely uncounted-but-lucky, it reads as zero;
+//  - they were still counted when the close began its wait (`calls_at_close`),
+//    so a poll that stopped blocking cannot leave the scenario testing an empty
+//    library;
+//  - the close did not return while they were held, so a wait that gives up
+//    after any interval shorter than the hold is not a wait.
+std::string HoldCloseOnce(int pollers) {
+    cultmesh_quic_debug_hold_calls(1);
+    void* runtime = nullptr;
+    const int32_t opened = cultmesh_quic_runtime_open("cultmesh-quic-native-tests", &runtime);
+    if (opened != 0 || runtime == nullptr) {
+        cultmesh_quic_debug_hold_calls(0);
+        return "cultmesh_quic_runtime_open returned " + std::to_string(opened);
+    }
+
+    std::atomic<int> returned{0};
+    std::atomic<int> undefined_return{0};
+    std::vector<std::thread> threads;
+    threads.reserve(static_cast<size_t>(pollers));
+    for (int index = 0; index < pollers; ++index) {
+        threads.emplace_back([runtime, &returned, &undefined_return] {
+            std::vector<uint8_t> payload(static_cast<size_t>(kPayloadCapacity));
+            cultmesh_quic_event event{};
+            int32_t required = 0;
+            const int32_t result = cultmesh_quic_next_event(
+                runtime, kPollTimeoutMs, &event, payload.data(), kPayloadCapacity, &required);
+            if (result != 0 && result != 1 && result != 2) undefined_return.fetch_add(1);
+            returned.fetch_add(1);
+        });
+    }
+
+    const auto counted_deadline =
+        std::chrono::steady_clock::now() + std::chrono::milliseconds(kCountedDeadlineMs);
+    while (cultmesh_quic_debug_peak_calls() < pollers &&
+           std::chrono::steady_clock::now() < counted_deadline)
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    std::this_thread::sleep_for(std::chrono::milliseconds(kSettleMs));
+
+    std::atomic<bool> closed{false};
+    std::thread closer([runtime, &closed] {
+        cultmesh_quic_runtime_close(runtime);
+        closed.store(true);
+    });
+    const auto held_until =
+        std::chrono::steady_clock::now() + std::chrono::milliseconds(kHeldWindowMs);
+    while (!closed.load() && std::chrono::steady_clock::now() < held_until)
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+
+    const bool closed_while_held = closed.load();
+    const int32_t peak = cultmesh_quic_debug_peak_calls();
+    const int32_t at_close = cultmesh_quic_debug_calls_at_close();
+
+    cultmesh_quic_debug_hold_calls(0);
+    closer.join();
+    for (auto& thread : threads) thread.join();
+
+    if (peak != pollers)
+        return "the library's peak count of host calls inside it was " + std::to_string(peak) + ", not " +
+            std::to_string(pollers) + ": either the blocking crossing is not inside a call scope, or it " +
+            "did not block long enough for the pollers to be inside it together";
+    if (at_close != pollers)
+        return "the close began its wait with " + std::to_string(at_close) +
+            " host call(s) counted inside, not " + std::to_string(pollers) +
+            "; the pollers were not inside the library when the close started";
+    if (closed_while_held)
+        return "the close returned while " + std::to_string(pollers) +
+            " host call(s) were still held inside the library";
+    if (undefined_return.load() != 0)
+        return std::to_string(undefined_return.load()) + " poller(s) saw a return the header does not define";
+    if (returned.load() != pollers)
+        return std::to_string(returned.load()) + " of " + std::to_string(pollers) + " pollers returned";
+    return {};
+}
+
+// One iteration of the other half of section 4: a call made while a close is
+// running is refused, and is not counted behind the close's wait.
+//
+// The prohibition is the host's — no call may begin after the close starts — and
+// the bridge does not make it optional. What it does do is refuse the call that
+// races the start, and that refusal is load-bearing rather than courteous: a
+// call admitted after the closer has begun increments the in-flight count behind
+// a wait that has already read it, and the wait can then be left waiting on a
+// count that reaches zero only when the late caller happens to leave.
+//
+// The seam is what makes the window wide enough to aim at: a held poller keeps
+// the close inside its wait for as long as this scenario wants it there.
+std::string LateCallOnce() {
+    cultmesh_quic_debug_hold_calls(1);
+    void* runtime = nullptr;
+    const int32_t opened = cultmesh_quic_runtime_open("cultmesh-quic-native-tests", &runtime);
+    if (opened != 0 || runtime == nullptr) {
+        cultmesh_quic_debug_hold_calls(0);
+        return "cultmesh_quic_runtime_open returned " + std::to_string(opened);
+    }
+
+    std::thread poller([runtime] {
+        std::vector<uint8_t> payload(static_cast<size_t>(kPayloadCapacity));
+        cultmesh_quic_event event{};
+        int32_t required = 0;
+        cultmesh_quic_next_event(
+            runtime, kPollTimeoutMs, &event, payload.data(), kPayloadCapacity, &required);
+    });
+
+    const auto counted_deadline =
+        std::chrono::steady_clock::now() + std::chrono::milliseconds(kCountedDeadlineMs);
+    while (cultmesh_quic_debug_peak_calls() < 1 &&
+           std::chrono::steady_clock::now() < counted_deadline)
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    std::this_thread::sleep_for(std::chrono::milliseconds(kSettleMs));
+
+    std::thread closer([runtime] { cultmesh_quic_runtime_close(runtime); });
+    // The close has begun its wait once it has read the count, and the held
+    // poller is what keeps it there.
+    const auto started_deadline =
+        std::chrono::steady_clock::now() + std::chrono::milliseconds(kCountedDeadlineMs);
+    while (cultmesh_quic_debug_calls_at_close() < 0 &&
+           std::chrono::steady_clock::now() < started_deadline)
+        std::this_thread::sleep_for(std::chrono::milliseconds(1));
+    const int32_t at_close = cultmesh_quic_debug_calls_at_close();
+
+    // Two calls, from a thread of their own so that a bridge which admits them
+    // cannot park this one: one that does not block, and then the blocking
+    // crossing. That order, because a bridge that admits the blocking one parks
+    // it inside the library until the hold is released, and a call made after
+    // that would be racing the teardown rather than the wait.
+    std::atomic<int32_t> late_poll{0};
+    std::atomic<int32_t> late_error{0};
+    std::thread late([runtime, &late_poll, &late_error] {
+        std::array<char, 256> message{};
+        late_error.store(cultmesh_quic_last_error(runtime, message.data(),
+            static_cast<int32_t>(message.size())));
+        std::vector<uint8_t> payload(static_cast<size_t>(kPayloadCapacity));
+        cultmesh_quic_event event{};
+        int32_t required = 0;
+        late_poll.store(cultmesh_quic_next_event(
+            runtime, kPollTimeoutMs, &event, payload.data(), kPayloadCapacity, &required));
+    });
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(kSettleMs));
+    cultmesh_quic_debug_hold_calls(0);
+    late.join();
+    closer.join();
+    poller.join();
+
+    if (at_close < 1)
+        return "the close did not begin its wait with the poller counted inside, so nothing held it "
+            "open for a call to race";
+    if (late_poll.load() != -1)
+        return "cultmesh_quic_next_event returned " + std::to_string(late_poll.load()) +
+            " to a call made during the close, not the -1 that refuses it";
+    if (late_error.load() != -1)
+        return "cultmesh_quic_last_error returned " + std::to_string(late_error.load()) +
+            " to a call made during the close, not the -1 that refuses it";
+    return {};
+}
+
+int LateCall(int iterations) {
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const std::string failure = LateCallOnce();
+        if (!failure.empty())
+            return Fail("latecall iteration " + std::to_string(iteration) + ": " + failure);
+    }
+    std::printf("latecall %dx: ok\n", iterations);
+    return 0;
+}
+
+int HoldClose(int iterations, int pollers) {
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const std::string failure = HoldCloseOnce(pollers);
+        if (!failure.empty())
+            return Fail("holdclose iteration " + std::to_string(iteration) + ": " + failure);
+    }
+    std::printf("holdclose %dx%d: ok\n", iterations, pollers);
+    return 0;
+}
+
+#endif  // CULTMESH_QUIC_DEBUG_ASSERTS
+
+int CloseRace(int iterations, int pollers) {
+    for (int iteration = 0; iteration < iterations; ++iteration) {
+        const std::string failure = CloseRaceOnce(pollers);
+        if (!failure.empty())
+            return Fail("closerace iteration " + std::to_string(iteration) + ": " + failure);
+    }
+    std::printf("closerace %dx%d: ok\n", iterations, pollers);
+    return 0;
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    if (argc < 2) {
+        std::fprintf(stderr,
+            "usage: %s closerace|holdclose|polltimeout|payloadfit|latecall [iterations] [pollers]\n",
+            argv[0]);
+        return 2;
+    }
+    const std::string scenario = argv[1];
+    const int iterations = argc > 2 ? std::atoi(argv[2]) : 20;
+    const int pollers = argc > 3 ? std::atoi(argv[3]) : 256;
+    if (iterations <= 0 || pollers <= 0) {
+        std::fprintf(stderr, "%s needs a positive iteration and poller count\n", scenario.c_str());
+        return 2;
+    }
+    if (scenario == "closerace") return CloseRace(iterations, pollers);
+    if (scenario == "polltimeout") return PollTimeout(iterations);
+    if (scenario == "payloadfit") return PayloadFit(iterations);
+    if (scenario == "holdclose" || scenario == "latecall") {
+#if defined(CULTMESH_QUIC_DEBUG_ASSERTS)
+        if (scenario == "latecall") return LateCall(iterations);
+        return HoldClose(iterations, pollers);
+#else
+        std::fprintf(stderr,
+            "%s needs the development seam: configure with "
+            "-DCULTMESH_QUIC_DEBUG_ASSERTS=ON\n", scenario.c_str());
+        return 2;
+#endif
+    }
+    std::fprintf(stderr, "unknown scenario '%s'\n", scenario.c_str());
+    return 2;
+}

packages/cultmath/README.md

@@ -31,8 +31,7 @@ shader semantics.
   deterministic value-noise primitives
 - `shaders/CultMath.hlsl`, a canonical HLSL mirror include for shader-side
   parity. HLSL already owns `float2`, `float3`, and `float4`; the include
-  exposes `cultmath_*` functions for shared semantics, including CultMath's
-  safe `normalize` contract.
+  exposes `cultmath_*` functions for shared semantics HLSL does not provide.
 - `Voronoi.SampleTones`, a C# batch surface that calls the Rust
   `cultmath-core` native kernel when `cultmath_core` is available and falls back
   to the managed parity path otherwise.
@@ -59,7 +58,7 @@ float grain = math.value_noise_bicubic(math.float2(12.0f, 3.5f));
 ```hlsl
 #include "CultMath.hlsl"
 
-float3 normal = cultmath_normalize(float3(0.25, 1.0, -0.1));
+float3 normal = normalize(float3(0.25, 1.0, -0.1));
 float rim = cultmath_saturate(1.0 - dot(normal, float3(0.0, 0.0, -1.0)));
 float glow = cultmath_smoothstep(0.2, 1.0, rim);
 float grain = cultmath_value_noise_bicubic(float2(12.0, 3.5));

packages/cultmath/docs/design.md

@@ -52,7 +52,26 @@ That makes these HLSL rules, not options:
   operand returns the other (so `saturate(NaN)` is 0), `clamp(x, a, b)` is
   `min(max(x, a), b)`, and `saturate(x)` is `min(1, max(0, x))`, which maps -0
   to +0; `any`/`all` accept numeric vectors (a component is true when it is
-  not 0); `min`, `max`, and `abs` on int vectors return int vectors.
+  not 0); `min`, `max`, and `abs` on int vectors return int vectors; int
+  `clamp` is `IMin(IMax(x, a), b)`, so inverted bounds return `b`.
+- Same-size vector conversions (`intN(floatN)`, `floatN(intN)`, `boolN(floatN)`,
+  `boolN(intN)`, `floatN(boolN)`, `intN(boolN)`) exist as constructors and
+  `math` functions and follow dxc: float to int is `fptosi`, truncating toward
+  zero; numeric to bool is `!= 0` (`fcmp une`, so NaN is true); bool to numeric
+  is 0 or 1. DXIL leaves float-to-int undefined for NaN and out-of-range values,
+  and so does C#; CultMath does not pin them.
+- `normalize(x)` is `x * Rsqrt(Dot(x, x))`, which is how dxc lowers it, and
+  DXIL.rst defines `Rsqrt` as `1 / sqrt(src)`. A zero vector therefore
+  normalizes to NaN (`0 * inf`), and a NaN component makes every component NaN.
+  (The special-value table under `Rsqrt` in DXIL.rst is a copy of the `Round`
+  table and contradicts that definition, so CultMath follows the definition.)
+  `length` and `distance` are `Sqrt` of the summed squares, so a zero vector
+  gives 0. Callers that can meet zero-length vectors guard them before calling
+  `normalize`.
+- dxc demotes double `frac`, `exp`, `lerp`, and `floor` to float. CultMath's
+  double overloads keep double precision instead: `frac(double)` is
+  `x - floor(x)` in double. That is a deliberate divergence for CPU simulation
+  time, which shaders do not carry.
 
 dxc marks float arithmetic and compares `fast` (no NaNs) unless a value is
 `precise`, so drivers may optimize NaN handling away and NaN results on real
@@ -64,9 +83,7 @@ GPU. Because `min`, `max`, and `saturate` return the non-NaN operand, some
 functions turn NaN or infinity into numbers: `smoothstep(a, a, a)` is 0;
 infinite inputs to `smoothstep` and the intercept helpers give numbers; the
 bezier, `smoothstep01`, and `smootherstep` functions return finite values for
-NaN input; and `normalize((NaN, 2.41))` is `(NaN, 2.41e20)`, because the NaN
-length is clamped to the epsilon and the other component is divided by it.
-Callers that must detect bad data should check `isnan` before calling these
+NaN input. Callers that must detect bad data should check `isnan` before calling these
 functions.
 
 Deferred until a consumer needs them: `float4x4`, `transpose`, `determinant`,
@@ -103,9 +120,20 @@ compiled under `using static CultMath.math;`, so its intrinsics are C# `math`
 itself: the test proves the composition in the text, not the intrinsic rules,
 which only `HlslSemanticsTests` pins.
 
+Integer hashing uses the PCG hashes from Jarzynski and Olano, "Hash Functions
+for GPU Rendering" (JCGT 9(3), 2020): `pcg(uint)` is O'Neill's RXS-M-XS 32/32
+permutation over one LCG step, and `pcg3d`/`pcg4d` are the paper's (3 → 3) and
+(4 → 4) hashes. They use only uint multiply, add, xor, and shifts. dxc wraps
+uint multiply and add modulo 2^32 exactly as C# unchecked arithmetic does, so
+they are integer-exact in HLSL and on the CPU, GPU included, unlike the
+`sin`-based `hash`. CultMath has no uint vectors, so `pcg3d(int3)` and
+`pcg4d(int4)` carry uint bit patterns in int components. The `float2`/`float3`/`float4`
+overloads hash the IEEE-754 bits (`asuint`), so -0 and 0 hash differently.
+`pcg3d(float2)` holds z at 0, which is the paper's route for (2 → N) inputs.
+Seeds and other scalar uses take one output component.
+
 Where HLSL is silent, CultMath keeps its own decisions and does not defer to
-Unity.Mathematics: `normalize` is safe (divides by `max(length, 1e-20)`),
-`hash` returns float, and `Random` is CultMath's own xorshift32. Engine-shaped
+Unity.Mathematics: `hash` returns float, and `Random` is CultMath's own xorshift32. Engine-shaped
 helpers that HLSL lacks (`float2x2.Rotate`, `float3x3.Euler`, `quaternion`,
 `snoise`) enter only when a consumer needs them, with their semantics stated in
 code.

packages/cultmath/shaders/CultMath.hlsl

@@ -11,7 +11,6 @@
 static const float CULTMATH_PI = 3.14159265358979323846;
 static const float CULTMATH_TAU = 6.28318530717958647692;
 static const float CULTMATH_HALF_PI = 1.57079632679489661923;
-static const float CULTMATH_NORMALIZE_EPSILON = 1.0e-20;
 
 float cultmath_radians(float degrees_value) { return degrees_value * (CULTMATH_PI / 180.0); }
 float cultmath_degrees(float radians_value) { return radians_value * (180.0 / CULTMATH_PI); }
@@ -171,10 +170,6 @@ float cultmath_distance(float2 left, float2 right) { return length(left - right)
 float cultmath_distance(float3 left, float3 right) { return length(left - right); }
 float cultmath_distance(float4 left, float4 right) { return length(left - right); }
 
-float2 cultmath_normalize(float2 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-float3 cultmath_normalize(float3 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-float4 cultmath_normalize(float4 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-
 float2 cultmath_reflect(float2 incident, float2 normal_value)
 {
     return incident - 2.0 * dot(normal_value, incident) * normal_value;
@@ -286,6 +281,38 @@ float cultmath_hash(float value) { return cultmath_frac(sin(value) * 43758.5453)
 float cultmath_hash(float2 value) { return cultmath_hash(dot(value, float2(127.1, 311.7))); }
 float cultmath_hash(float3 value) { return cultmath_hash(dot(value, float3(127.1, 311.7, 74.7))); }
 
+// PCG hashes (Jarzynski and Olano, JCGT 2020), written over scalar uints so CultMath's int3/int4 carry the bits.
+uint cultmath_pcg(uint value)
+{
+    uint state = value * 747796405u + 2891336453u;
+    uint word = ((state >> (int)((state >> 28) + 4)) ^ state) * 277803737u;
+    return (word >> 22) ^ word;
+}
+
+int3 cultmath_pcg3d(int3 value)
+{
+    uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u, z = (uint)value.z * 1664525u + 1013904223u;
+    x += y * z; y += z * x; z += x * y;
+    x ^= x >> 16; y ^= y >> 16; z ^= z >> 16;
+    x += y * z; y += z * x; z += x * y;
+    return int3((int)x, (int)y, (int)z);
+}
+
+int3 cultmath_pcg3d(float2 value) { return cultmath_pcg3d(float3(value, 0.0)); }
+int3 cultmath_pcg3d(float3 value) { return cultmath_pcg3d(int3((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z))); }
+
+int4 cultmath_pcg4d(int4 value)
+{
+    uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u;
+    uint z = (uint)value.z * 1664525u + 1013904223u, w = (uint)value.w * 1664525u + 1013904223u;
+    x += y * w; y += z * x; z += x * y; w += y * z;
+    x ^= x >> 16; y ^= y >> 16; z ^= z >> 16; w ^= w >> 16;
+    x += y * w; y += z * x; z += x * y; w += y * z;
+    return int4((int)x, (int)y, (int)z, (int)w);
+}
+
+int4 cultmath_pcg4d(float4 value) { return cultmath_pcg4d(int4((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z), (int)asuint(value.w))); }
+
 float cultmath_value_noise(float2 position)
 {
     float2 cell = floor(position);

packages/cultmath/src/CultMath/CultMath.csproj

@@ -8,7 +8,7 @@
     <RootNamespace>CultMath</RootNamespace>
     <AssemblyName>CultMath</AssemblyName>
     <PackageId>GameCult.Math</PackageId>
-    <Version>0.2.0</Version>
+    <Version>0.2.3</Version>
     <Description>Clean-room C# math shaped for HLSL-style renderer code.</Description>
     <Authors>GameCult</Authors>
     <PackageReadmeFile>README.md</PackageReadmeFile>

packages/cultmath/src/CultMath/Swizzles.g.cs

@@ -7,6 +7,8 @@ namespace CultMath;
 public partial struct float2
 {
     public float2(float2 xy) : this(xy.x, xy.y) { }
+    public float2(int2 value) : this(value.x, value.y) { }
+    public float2(bool2 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f) { }
     public float r { readonly get => x; set => x = value; }
     public float g { readonly get => y; set => y = value; }
     public readonly float2 xx => new(x, x);
@@ -72,6 +74,8 @@ public partial struct float3
     public float3(float x, float2 yz) : this(x, yz.x, yz.y) { }
     public float3(float2 xy, float z) : this(xy.x, xy.y, z) { }
     public float3(float3 xyz) : this(xyz.x, xyz.y, xyz.z) { }
+    public float3(int3 value) : this(value.x, value.y, value.z) { }
+    public float3(bool3 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f, value.z ? 1.0f : 0.0f) { }
     public float r { readonly get => x; set => x = value; }
     public float g { readonly get => y; set => y = value; }
     public float b { readonly get => z; set => z = value; }
@@ -320,6 +324,8 @@ public partial struct float4
     public float4(float2 xy, float2 zw) : this(xy.x, xy.y, zw.x, zw.y) { }
     public float4(float3 xyz, float w) : this(xyz.x, xyz.y, xyz.z, w) { }
     public float4(float4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { }
+    public float4(int4 value) : this(value.x, value.y, value.z, value.w) { }
+    public float4(bool4 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f, value.z ? 1.0f : 0.0f, value.w ? 1.0f : 0.0f) { }
     public float r { readonly get => x; set => x = value; }
     public float g { readonly get => y; set => y = value; }
     public float b { readonly get => z; set => z = value; }
@@ -1001,6 +1007,8 @@ public partial struct float4
 public partial struct int2
 {
     public int2(int2 xy) : this(xy.x, xy.y) { }
+    public int2(float2 value) : this((int)value.x, (int)value.y) { }
+    public int2(bool2 value) : this(value.x ? 1 : 0, value.y ? 1 : 0) { }
     public int r { readonly get => x; set => x = value; }
     public int g { readonly get => y; set => y = value; }
     public readonly int2 xx => new(x, x);
@@ -1066,6 +1074,8 @@ public partial struct int3
     public int3(int x, int2 yz) : this(x, yz.x, yz.y) { }
     public int3(int2 xy, int z) : this(xy.x, xy.y, z) { }
     public int3(int3 xyz) : this(xyz.x, xyz.y, xyz.z) { }
+    public int3(float3 value) : this((int)value.x, (int)value.y, (int)value.z) { }
+    public int3(bool3 value) : this(value.x ? 1 : 0, value.y ? 1 : 0, value.z ? 1 : 0) { }
     public int r { readonly get => x; set => x = value; }
     public int g { readonly get => y; set => y = value; }
     public int b { readonly get => z; set => z = value; }
@@ -1314,6 +1324,8 @@ public partial struct int4
     public int4(int2 xy, int2 zw) : this(xy.x, xy.y, zw.x, zw.y) { }
     public int4(int3 xyz, int w) : this(xyz.x, xyz.y, xyz.z, w) { }
     public int4(int4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { }
+    public int4(float4 value) : this((int)value.x, (int)value.y, (int)value.z, (int)value.w) { }
+    public int4(bool4 value) : this(value.x ? 1 : 0, value.y ? 1 : 0, value.z ? 1 : 0, value.w ? 1 : 0) { }
     public int r { readonly get => x; set => x = value; }
     public int g { readonly get => y; set => y = value; }
     public int b { readonly get => z; set => z = value; }
@@ -1995,6 +2007,8 @@ public partial struct int4
 public partial struct bool2
 {
     public bool2(bool2 xy) : this(xy.x, xy.y) { }
+    public bool2(float2 value) : this(value.x != 0.0f, value.y != 0.0f) { }
+    public bool2(int2 value) : this(value.x != 0, value.y != 0) { }
     public bool r { readonly get => x; set => x = value; }
     public bool g { readonly get => y; set => y = value; }
     public readonly bool2 xx => new(x, x);
@@ -2060,6 +2074,8 @@ public partial struct bool3
     public bool3(bool x, bool2 yz) : this(x, yz.x, yz.y) { }
     public bool3(bool2 xy, bool z) : this(xy.x, xy.y, z) { }
     public bool3(bool3 xyz) : this(xyz.x, xyz.y, xyz.z) { }
+    public bool3(float3 value) : this(value.x != 0.0f, value.y != 0.0f, value.z != 0.0f) { }
+    public bool3(int3 value) : this(value.x != 0, value.y != 0, value.z != 0) { }
     public bool r { readonly get => x; set => x = value; }
     public bool g { readonly get => y; set => y = value; }
     public bool b { readonly get => z; set => z = value; }
@@ -2308,6 +2324,8 @@ public partial struct bool4
     public bool4(bool2 xy, bool2 zw) : this(xy.x, xy.y, zw.x, zw.y) { }
     public bool4(bool3 xyz, bool w) : this(xyz.x, xyz.y, xyz.z, w) { }
     public bool4(bool4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { }
+    public bool4(float4 value) : this(value.x != 0.0f, value.y != 0.0f, value.z != 0.0f, value.w != 0.0f) { }
+    public bool4(int4 value) : this(value.x != 0, value.y != 0, value.z != 0, value.w != 0) { }
     public bool r { readonly get => x; set => x = value; }
     public bool g { readonly get => y; set => y = value; }
     public bool b { readonly get => z; set => z = value; }
@@ -3102,9 +3120,15 @@ public partial struct double3
 public static partial class math
 {
     public static float2 float2(float2 xy) => new(xy);
+    public static float2 float2(int2 value) => new(value);
+    public static float2 float2(bool2 value) => new(value);
+    public static float2 float2(int value) => new(value, value);
     public static float3 float3(float x, float2 yz) => new(x, yz);
     public static float3 float3(float2 xy, float z) => new(xy, z);
     public static float3 float3(float3 xyz) => new(xyz);
+    public static float3 float3(int3 value) => new(value);
+    public static float3 float3(bool3 value) => new(value);
+    public static float3 float3(int value) => new(value, value, value);
     public static float4 float4(float x, float y, float2 zw) => new(x, y, zw);
     public static float4 float4(float x, float2 yz, float w) => new(x, yz, w);
     public static float4 float4(float x, float3 yzw) => new(x, yzw);
@@ -3112,10 +3136,17 @@ public static partial class math
     public static float4 float4(float2 xy, float2 zw) => new(xy, zw);
     public static float4 float4(float3 xyz, float w) => new(xyz, w);
     public static float4 float4(float4 xyzw) => new(xyzw);
+    public static float4 float4(int4 value) => new(value);
+    public static float4 float4(bool4 value) => new(value);
+    public static float4 float4(int value) => new(value, value, value, value);
     public static int2 int2(int2 xy) => new(xy);
+    public static int2 int2(float2 value) => new(value);
+    public static int2 int2(bool2 value) => new(value);
     public static int3 int3(int x, int2 yz) => new(x, yz);
     public static int3 int3(int2 xy, int z) => new(xy, z);
     public static int3 int3(int3 xyz) => new(xyz);
+    public static int3 int3(float3 value) => new(value);
+    public static int3 int3(bool3 value) => new(value);
     public static int4 int4(int x, int y, int2 zw) => new(x, y, zw);
     public static int4 int4(int x, int2 yz, int w) => new(x, yz, w);
     public static int4 int4(int x, int3 yzw) => new(x, yzw);
@@ -3123,10 +3154,16 @@ public static partial class math
     public static int4 int4(int2 xy, int2 zw) => new(xy, zw);
     public static int4 int4(int3 xyz, int w) => new(xyz, w);
     public static int4 int4(int4 xyzw) => new(xyzw);
+    public static int4 int4(float4 value) => new(value);
+    public static int4 int4(bool4 value) => new(value);
     public static bool2 bool2(bool2 xy) => new(xy);
+    public static bool2 bool2(float2 value) => new(value);
+    public static bool2 bool2(int2 value) => new(value);
     public static bool3 bool3(bool x, bool2 yz) => new(x, yz);
     public static bool3 bool3(bool2 xy, bool z) => new(xy, z);
     public static bool3 bool3(bool3 xyz) => new(xyz);
+    public static bool3 bool3(float3 value) => new(value);
+    public static bool3 bool3(int3 value) => new(value);
     public static bool4 bool4(bool x, bool y, bool2 zw) => new(x, y, zw);
     public static bool4 bool4(bool x, bool2 yz, bool w) => new(x, yz, w);
     public static bool4 bool4(bool x, bool3 yzw) => new(x, yzw);
@@ -3134,4 +3171,6 @@ public static partial class math
     public static bool4 bool4(bool2 xy, bool2 zw) => new(xy, zw);
     public static bool4 bool4(bool3 xyz, bool w) => new(xyz, w);
     public static bool4 bool4(bool4 xyzw) => new(xyzw);
+    public static bool4 bool4(float4 value) => new(value);
+    public static bool4 bool4(int4 value) => new(value);
 }

packages/cultmath/src/CultMath/math.cs

@@ -105,6 +105,9 @@ public static partial class math
     public static float2 frac(float2 value) => value - floor(value);
     public static float3 frac(float3 value) => value - floor(value);
     public static float4 frac(float4 value) => value - floor(value);
+    // dxc has no double Frc: it demotes to float, as it does for exp and lerp. CultMath's double
+    // overloads keep double precision instead, so frac(double) is x - floor(x) in double.
+    public static double frac(double value) => value - Math.Floor(value);
 
     // dxc lowers float min/max/clamp to DXIL FMin/FMax (saturate to Saturate, defined as FMin(1, FMax(0, x))).
     // DXIL.rst: FMin(a, b) is a < b ? a : b, FMax(a, b) is a >= b ? a : b, and a NaN operand returns the other.
@@ -130,6 +133,11 @@ public static partial class math
     public static float2 clamp(float2 value, float2 minimum, float2 maximum) => min(max(value, minimum), maximum);
     public static float3 clamp(float3 value, float3 minimum, float3 maximum) => min(max(value, minimum), maximum);
     public static float4 clamp(float4 value, float4 minimum, float4 maximum) => min(max(value, minimum), maximum);
+    // dxc lowers int clamp to IMin(IMax(x, a), b): inverted bounds return b rather than throwing like Math.Clamp.
+    public static int clamp(int value, int minimum, int maximum) => min(max(value, minimum), maximum);
+    public static int2 clamp(int2 value, int2 minimum, int2 maximum) => min(max(value, minimum), maximum);
+    public static int3 clamp(int3 value, int3 minimum, int3 maximum) => min(max(value, minimum), maximum);
+    public static int4 clamp(int4 value, int4 minimum, int4 maximum) => min(max(value, minimum), maximum);
 
     // DXIL Saturate is FMin(1, FMax(0, x)); that operand order, unlike clamp(x, 0, 1), maps -0 to +0.
     public static float saturate(float value) => min(1.0f, max(0.0f, value));
@@ -205,9 +213,10 @@ public static partial class math
     public static float distance(float3 left, float3 right) => length(left - right);
     public static float distance(float4 left, float4 right) => length(left - right);
 
-    public static float2 normalize(float2 value) => value / max(length(value), 1.0e-20f);
-    public static float3 normalize(float3 value) => value / max(length(value), 1.0e-20f);
-    public static float4 normalize(float4 value) => value / max(length(value), 1.0e-20f);
+    // dxc lowers normalize(x) to x * Rsqrt(Dot(x, x)), and DXIL Rsqrt is 1 / sqrt(src): a zero vector is 0 * inf = NaN.
+    public static float2 normalize(float2 value) => value * (1.0f / MathF.Sqrt(dot(value, value)));
+    public static float3 normalize(float3 value) => value * (1.0f / MathF.Sqrt(dot(value, value)));
+    public static float4 normalize(float4 value) => value * (1.0f / MathF.Sqrt(dot(value, value)));
     public static quaternion normalize(quaternion value)
     {
         var length = MathF.Sqrt(value.x * value.x + value.y * value.y + value.z * value.z + value.w * value.w);
@@ -373,6 +382,43 @@ public static partial class math
     public static float hash(float2 value) => hash(dot(value, new float2(127.1f, 311.7f)));
     public static float hash(float3 value) => hash(dot(value, new float3(127.1f, 311.7f, 74.7f)));
 
+    public static uint asuint(float value) => (uint)BitConverter.SingleToInt32Bits(value);
+
+    // PCG hashes from Jarzynski and Olano, "Hash Functions for GPU Rendering" (JCGT 9(3), 2020). Integer-only, so
+    // dxc and C# agree bit for bit. pcg3d/pcg4d carry uint bit patterns in int3/int4; float overloads hash IEEE bits.
+    public static uint pcg(uint value)
+    {
+        var state = value * 747796405u + 2891336453u;
+        var word = ((state >> (int)((state >> 28) + 4)) ^ state) * 277803737u;
+        return (word >> 22) ^ word;
+    }
+
+    public static int3 pcg3d(int3 value)
+    {
+        uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u, z = (uint)value.z * 1664525u + 1013904223u;
+        x += y * z; y += z * x; z += x * y;
+        x ^= x >> 16; y ^= y >> 16; z ^= z >> 16;
+        x += y * z; y += z * x; z += x * y;
+        return new int3((int)x, (int)y, (int)z);
+    }
+
+    // The paper hashes 2 -> N inputs through pcg3d with the unused component held constant.
+    public static int3 pcg3d(float2 value) => pcg3d(new float3(value, 0.0f));
+    public static int3 pcg3d(float3 value) => pcg3d(new int3((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z)));
+
+    public static int4 pcg4d(int4 value)
+    {
+        uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u;
+        uint z = (uint)value.z * 1664525u + 1013904223u, w = (uint)value.w * 1664525u + 1013904223u;
+        x += y * w; y += z * x; z += x * y; w += y * z;
+        x ^= x >> 16; y ^= y >> 16; z ^= z >> 16; w ^= w >> 16;
+        x += y * w; y += z * x; z += x * y; w += y * z;
+        return new int4((int)x, (int)y, (int)z, (int)w);
+    }
+
+    public static int4 pcg4d(float4 value) =>
+        pcg4d(new int4((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z), (int)asuint(value.w)));
+
     public static float log(float value) => MathF.Log(value);
     public static float2 log(float2 value) => new(log(value.x), log(value.y));
     public static float3 log(float3 value) => new(log(value.x), log(value.y), log(value.z));

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

@@ -31,7 +31,6 @@ public sealed class HlslMirrorTests
             "cultmath_smootherstep",
             "cultmath_lengthsq",
             "cultmath_distance",
-            "cultmath_normalize",
             "cultmath_reflect",
             "cultmath_rotate",
             "cultmath_csum",
@@ -41,6 +40,9 @@ public sealed class HlslMirrorTests
             "cultmath_quadratic_bezier",
             "cultmath_cubic_bezier",
             "cultmath_hash",
+            "cultmath_pcg(uint",
+            "cultmath_pcg3d(int3",
+            "cultmath_pcg4d(int4",
             "cultmath_value_noise",
             "cultmath_snoise(float2",
             "cultmath_snoise(float3",
@@ -54,8 +56,8 @@ public sealed class HlslMirrorTests
             Assert.Contains(symbol, include);
         }
 
-        Assert.Contains("CULTMATH_NORMALIZE_EPSILON", include);
-        Assert.Contains("max(length(value), CULTMATH_NORMALIZE_EPSILON)", include);
+        // HLSL's normalize intrinsic is the contract; a mirror copy would only restate it.
+        Assert.DoesNotContain("cultmath_normalize", include);
     }
 
     private static string GetCultMathRoot()

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

@@ -187,6 +187,33 @@ public sealed class HlslSemanticsTests
         Assert.Equal(DoubleBits(-0.0), DoubleBits(math.max(-0.0, 0.0)));
         Assert.Equal(DoubleBits(0.0), DoubleBits(math.min(-0.0, 0.0)));
 
+        // dxc: normalize(x) is x * Rsqrt(Dot(x, x)); length and distance are Sqrt of the summed squares.
+        static bool AllNaN(float4 value) =>
+            float.IsNaN(value.x) && float.IsNaN(value.y) && float.IsNaN(value.z) && float.IsNaN(value.w);
+        var n2 = math.normalize(float2.zero);
+        Assert.True(float.IsNaN(n2.x) && float.IsNaN(n2.y));
+        var n3 = math.normalize(float3.zero);
+        Assert.True(float.IsNaN(n3.x) && float.IsNaN(n3.y) && float.IsNaN(n3.z));
+        Assert.True(AllNaN(math.normalize(float4.zero)));
+        var nanX = math.normalize(new float2(float.NaN, 2.41f));
+        Assert.True(float.IsNaN(nanX.x) && float.IsNaN(nanX.y));
+        Assert.True(AllNaN(math.normalize(new float4(1.0f, float.NaN, 2.41f, 1.0f))));
+        var skew = new float3(0.25f, 1.0f, -0.1f);
+        var inverseLength = 1.0f / MathF.Sqrt(skew.x * skew.x + skew.y * skew.y + skew.z * skew.z);
+        var normalized = math.normalize(skew);
+        Assert.Equal(Bits(skew.x * inverseLength), Bits(normalized.x));
+        Assert.Equal(Bits(skew.y * inverseLength), Bits(normalized.y));
+        Assert.Equal(Bits(skew.z * inverseLength), Bits(normalized.z));
+        Assert.Equal(Bits(0.0f), Bits(math.length(float2.zero)));
+        Assert.Equal(Bits(0.0f), Bits(math.length(float3.zero)));
+        Assert.Equal(Bits(0.0f), Bits(math.length(float4.zero)));
+        Assert.Equal(Bits(0.0f), Bits(math.distance(new float3(1.0f, 2.0f, 3.0f), new float3(1.0f, 2.0f, 3.0f))));
+
+        // asuint(float) reinterprets the IEEE-754 bits.
+        Assert.Equal(0x80000000u, math.asuint(-0.0f));
+        Assert.Equal(0x3FC00000u, math.asuint(1.5f));
+        Assert.Equal(0x7FC00000u, math.asuint(BitConverter.Int32BitsToSingle(0x7FC00000)));
+
         Assert.Equal(0, math.sign(float.NaN));
         Assert.Equal(-1, math.sign(-0.5f));
         Assert.Equal(new int3(-1, 0, 1), math.sign(new float3(-2.0f, 0.0f, 4.0f)));
@@ -311,6 +338,43 @@ public sealed class HlslSemanticsTests
         Assert.Equal(new int4(5, 5, 5, 5), math.int4(5));
     }
 
+    [Fact]
+    public void VectorConversionsFollowDxc()
+    {
+        // fptosi truncates toward zero; NaN and out-of-range inputs are undefined in DXIL and not pinned.
+        Assert.Equal(new int2(-1, 2), math.int2(new float2(-1.7f, 2.9f)));
+        Assert.Equal(new int3(0, 0, 3), new int3(new float3(-0.5f, 0.5f, 3.99f)));
+        Assert.Equal(new float4(1.0f, -2.0f, 3.0f, 0.0f), math.float4(new int4(1, -2, 3, 0)));
+        // Numeric to bool is `!= 0` (fcmp une for float, so NaN is true); bool to numeric is 0 or 1.
+        Assert.Equal(new bool2(true, false), math.bool2(new float2(float.NaN, -0.0f)));
+        Assert.Equal(new bool3(false, true, true), math.bool3(new int3(0, 5, -1)));
+        Assert.Equal(new float2(1.0f, 0.0f), math.float2(new bool2(true, false)));
+        Assert.Equal(new int4(0, 1, 1, 0), math.int4(new bool4(false, true, true, false)));
+        // intN(intN) is exact; it must not promote through float and lose 2^24 + 1.
+        Assert.Equal(new int2(16777217, -16777217), math.int2(new int2(16777217, -16777217)));
+        float2 splat = math.float2(0);
+        Assert.Equal(float2.zero, splat);
+    }
+
+    [Fact]
+    public void FracAndIntegerClampFollowHlsl()
+    {
+        // frac(double) keeps double precision; a float frac of 1e9 + 0.25 would return 0.
+        Assert.Equal(0.25, math.frac(1.0e9 + 0.25));
+        Assert.Equal(0.75, math.frac(-0.25));
+        Assert.Equal(0.5f, math.frac(2.5f));
+
+        // IMin(IMax(x, a), b): the result stays int, and inverted bounds return b.
+        int clamped = math.clamp(7, -1, 3);
+        Assert.Equal(3, clamped);
+        Assert.Equal(-1, math.clamp(-5, -1, 3));
+        Assert.Equal(0, math.clamp(1, 3, 0));
+        Assert.Equal(new int2(0, 3), math.clamp(new int2(-4, 9), 0, 3));
+        Assert.Equal(new int3(1, 2, 3), math.clamp(new int3(1, 2, 3), new int3(0, 0, 0), new int3(5, 5, 5)));
+        Assert.Equal(new int4(2, 2, 4, 4), math.clamp(new int4(1, 2, 5, 4), new int4(2), new int4(4)));
+        Assert.Equal(1.0f, math.clamp(2.0f, -1, 1));
+    }
+
     [Fact]
     public void MatrixMulFollowsHlslRowMajorConvention()
     {

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

@@ -78,26 +78,33 @@ public sealed class HlslSourceCompatibilityTests
             foreach (var input in cases)
             {
                 var slot = 0;
-                var args = types.Select(t => t == typeof(float) ? (object)input(slot++)
-                    : Activator.CreateInstance(t, Enumerable.Range(0, Components(t)).Select(_ => (object)input(slot++)).ToArray())!).ToArray();
-                var expected = Floats(counterpart.Invoke(null, args)!);
-                var actual = Floats(mirror.Invoke(shader, args)!);
-                if (expected.Length != actual.Length || expected.Zip(actual).Any(p => !(float.IsNaN(p.First) && float.IsNaN(p.Second))
-                    && BitConverter.SingleToInt32Bits(p.First) != BitConverter.SingleToInt32Bits(p.Second)))
+                var args = types.Select(t => Scalars.Contains(t) ? Scalar(t, input(slot++))
+                    : Activator.CreateInstance(t, Components(t).Select(f => Scalar(f.FieldType, input(slot++))).ToArray())!).ToArray();
+                var expected = Values(counterpart.Invoke(null, args)!);
+                var actual = Values(mirror.Invoke(shader, args)!);
+                if (expected.Length != actual.Length || expected.Zip(actual).Any(p => p.First is float a && p.Second is float b
+                    ? !(float.IsNaN(a) && float.IsNaN(b)) && BitConverter.SingleToInt32Bits(a) != BitConverter.SingleToInt32Bits(b)
+                    : !p.First.Equals(p.Second)))
                 {
-                    mismatches.Add($"{mirror.Name}({string.Join(", ", args.Select(a => string.Join(" ", Floats(a))))}): C# {string.Join(" ", expected)}, mirror {string.Join(" ", actual)}");
+                    mismatches.Add($"{mirror.Name}({string.Join(", ", args.Select(a => string.Join(" ", Values(a))))}): C# {string.Join(" ", expected)}, mirror {string.Join(" ", actual)}");
                 }
             }
         }
 
         Assert.True(mismatches.Count == 0, $"{mismatches.Count} mismatches:{Environment.NewLine}{string.Join(Environment.NewLine, mismatches.Take(12))}");
-        Assert.Equal(26, compared.Count);
+        Assert.Equal(28, compared.Count);
     }
 
-    private static int Components(Type t) => t.GetFields().Count(f => f.FieldType == typeof(float) && !f.IsStatic);
+    // Integer arguments take the bit pattern of the float input, so specials become 0, 0x80000000, NaN bits, ...
+    private static readonly Type[] Scalars = { typeof(float), typeof(int), typeof(uint) };
 
-    private static float[] Floats(object value) => value is float f ? new[] { f }
-        : value.GetType().GetFields().Where(field => field.FieldType == typeof(float) && !field.IsStatic).Select(field => (float)field.GetValue(value)!).ToArray();
+    private static object Scalar(Type t, float f) => t == typeof(float) ? f
+        : t == typeof(int) ? BitConverter.SingleToInt32Bits(f) : (object)(uint)BitConverter.SingleToInt32Bits(f);
+
+    private static FieldInfo[] Components(Type t) => t.GetFields().Where(f => !f.IsStatic && Scalars.Contains(f.FieldType)).ToArray();
+
+    private static object[] Values(object value) => Scalars.Contains(value.GetType()) ? new[] { value }
+        : Components(value.GetType()).Select(field => field.GetValue(value)!).ToArray();
 
     /// <summary>The documented HLSL-to-C# transformations, and nothing else.</summary>
     internal static string TransformHlslToCSharp(string hlsl)

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

@@ -12,6 +12,41 @@ public sealed class MathTests
         Assert.Equal(0.75f, math.frac(-1.25f));
     }
 
+    // Expected values come from a Python transcription of the paper's pcg3d/pcg4d (JCGT 9(3) 2020, p. 32) and
+    // O'Neill's pcg_output_rxs_m_xs_32_32 with PCG_DEFAULT_MULTIPLIER_32/INCREMENT_32, independent of this code.
+    [Fact]
+    public void PcgHashesMatchReferenceTranscription()
+    {
+        static int3 U3(uint x, uint y, uint z) => new((int)x, (int)y, (int)z);
+        static int4 U4(uint x, uint y, uint z, uint w) => new((int)x, (int)y, (int)z, (int)w);
+
+        Assert.Equal(0x07BB2FE2u, math.pcg(0u));
+        Assert.Equal(0xA8BEEA3Cu, math.pcg(1u));
+        Assert.Equal(0x995312E1u, math.pcg(0x12345678u));
+        Assert.Equal(0xE62A4902u, math.pcg(0xFFFFFFFFu));
+        Assert.Equal(U3(0x9BAFD7C6u, 0xA8E88A6Bu, 0x3F15482Cu), math.pcg3d(new int3(0, 0, 0)));
+        Assert.Equal(U3(0xFA9F79A6u, 0x48F2F44Cu, 0x596F5AB1u), math.pcg3d(new int3(1, 2, 3)));
+        Assert.Equal(U3(0x67DCF282u, 0x49E87E17u, 0x10018917u), math.pcg3d(U3(0xFFFFFFFFu, 0x80000000u, 0x7FFFFFFFu)));
+        Assert.Equal(U4(0x0F02F829u, 0x2D568769u, 0x32B0C43Bu, 0xD32548EAu), math.pcg4d(new int4(0, 0, 0, 0)));
+        Assert.Equal(U4(0x3622CD16u, 0xF11471D8u, 0xE1109B3Fu, 0x02B94C2Fu), math.pcg4d(new int4(1, 2, 3, 4)));
+        Assert.Equal(U4(0x72180037u, 0x81D493E6u, 0xD9BA7226u, 0x14C9ABA7u), math.pcg4d(U4(0xFFFFFFFFu, 0x80000000u, 0x7FFFFFFFu, 0xDEADBEEFu)));
+        Assert.Equal(U3(0xA7B40FEEu, 0x9B70DFC0u, 0x3106C2C5u), math.pcg3d(new float3(1.5f, -2.25f, 1e7f)));
+        Assert.Equal(U3(0x5A09E5C6u, 0x53EC0DABu, 0x4BE4A1ECu), math.pcg3d(new float2(3.0f, 4.0f)));
+        Assert.Equal(U4(0x1849E380u, 0xF199DEE0u, 0x6C6B4934u, 0x34AF16DFu),
+            math.pcg4d(new float4(-0.0f, BitConverter.Int32BitsToSingle(0x7FC00000), 0.5f, 1e-7f)));
+    }
+
+    [Fact]
+    public void Pcg3dSeparatesAPositionGrid()
+    {
+        // A single 32-bit component is subject to birthday collisions (x has one here); the full output is distinct.
+        var hashes = new HashSet<int3>();
+        for (var i = 0; i < 100; i++)
+        for (var j = 0; j < 100; j++)
+            hashes.Add(math.pcg3d(new float2(i * 0.5f - 25.0f, j * 0.5f - 25.0f)));
+        Assert.Equal(10000, hashes.Count);
+    }
+
     [Fact]
     public void VectorOperationsAreComponentWise()
     {

packages/cultmath/tools/generate-swizzles.ps1

@@ -21,6 +21,19 @@ $families = @(
     @{ Scalar = "bool"; Sizes = @(2, 3, 4); Functions = $true },
     @{ Scalar = "double"; Sizes = @(2, 3); Functions = $false }
 )
+# Same-size vector conversions, as dxc lowers them: float to int is fptosi (toward zero; NaN
+# and out-of-range are undefined in DXIL), int to float is sitofp, numeric to bool is `!= 0`
+# (fcmp une, so NaN is true), bool to numeric is 0 or 1. Keyed "target<-source"; {0} is a
+# source component. Identity forms (intN(intN), ...) come from the composition loop, which
+# also keeps an int vector argument off the lossy intN(floatN) overload.
+$conversions = [ordered]@{
+    "float<-int" = "{0}"
+    "float<-bool" = "{0} ? 1.0f : 0.0f"
+    "int<-float" = "(int){0}"
+    "int<-bool" = "{0} ? 1 : 0"
+    "bool<-float" = "{0} != 0.0f"
+    "bool<-int" = "{0} != 0"
+}
 $componentFields = @("x", "y", "z", "w")
 $namings = @(@("x", "y", "z", "w"), @("r", "g", "b", "a"))
 
@@ -86,6 +99,20 @@ foreach ($family in $families) {
             }
         }
 
+        foreach ($source in @("float", "int", "bool")) {
+            $expression = $conversions["$scalar<-$source"]
+            if (-not $expression) { continue }
+            $converted = for ($i = 0; $i -lt $size; $i++) { $expression -f "value.$($componentFields[$i])" }
+            Line "    public $type($source$size value) : this($($converted -join ', ')) { }"
+            if ($family.Functions) {
+                $functionLines.Add("    public static $type $type($source$size value) => new(value);")
+            }
+        }
+        if ($scalar -eq "float" -and $family.Functions) {
+            # floatN(int) splat: without it floatN(0) is ambiguous between floatN(float) and floatN(intN).
+            $functionLines.Add("    public static $type $type(int value) => new($((@('value') * $size) -join ', '));")
+        }
+
         # Single-component color aliases; x/y/z/w are the fields themselves.
         $letters = $namings[1]
         for ($i = 0; $i -lt $size; $i++) {

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

@@ -11,7 +11,6 @@
 static const float CULTMATH_PI = 3.14159265358979323846;
 static const float CULTMATH_TAU = 6.28318530717958647692;
 static const float CULTMATH_HALF_PI = 1.57079632679489661923;
-static const float CULTMATH_NORMALIZE_EPSILON = 1.0e-20;
 
 float cultmath_radians(float degrees_value) { return degrees_value * (CULTMATH_PI / 180.0); }
 float cultmath_degrees(float radians_value) { return radians_value * (180.0 / CULTMATH_PI); }
@@ -171,10 +170,6 @@ float cultmath_distance(float2 left, float2 right) { return length(left - right)
 float cultmath_distance(float3 left, float3 right) { return length(left - right); }
 float cultmath_distance(float4 left, float4 right) { return length(left - right); }
 
-float2 cultmath_normalize(float2 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-float3 cultmath_normalize(float3 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-float4 cultmath_normalize(float4 value) { return value / max(length(value), CULTMATH_NORMALIZE_EPSILON); }
-
 float2 cultmath_reflect(float2 incident, float2 normal_value)
 {
     return incident - 2.0 * dot(normal_value, incident) * normal_value;
@@ -286,6 +281,38 @@ float cultmath_hash(float value) { return cultmath_frac(sin(value) * 43758.5453)
 float cultmath_hash(float2 value) { return cultmath_hash(dot(value, float2(127.1, 311.7))); }
 float cultmath_hash(float3 value) { return cultmath_hash(dot(value, float3(127.1, 311.7, 74.7))); }
 
+// PCG hashes (Jarzynski and Olano, JCGT 2020), written over scalar uints so CultMath's int3/int4 carry the bits.
+uint cultmath_pcg(uint value)
+{
+    uint state = value * 747796405u + 2891336453u;
+    uint word = ((state >> (int)((state >> 28) + 4)) ^ state) * 277803737u;
+    return (word >> 22) ^ word;
+}
+
+int3 cultmath_pcg3d(int3 value)
+{
+    uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u, z = (uint)value.z * 1664525u + 1013904223u;
+    x += y * z; y += z * x; z += x * y;
+    x ^= x >> 16; y ^= y >> 16; z ^= z >> 16;
+    x += y * z; y += z * x; z += x * y;
+    return int3((int)x, (int)y, (int)z);
+}
+
+int3 cultmath_pcg3d(float2 value) { return cultmath_pcg3d(float3(value, 0.0)); }
+int3 cultmath_pcg3d(float3 value) { return cultmath_pcg3d(int3((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z))); }
+
+int4 cultmath_pcg4d(int4 value)
+{
+    uint x = (uint)value.x * 1664525u + 1013904223u, y = (uint)value.y * 1664525u + 1013904223u;
+    uint z = (uint)value.z * 1664525u + 1013904223u, w = (uint)value.w * 1664525u + 1013904223u;
+    x += y * w; y += z * x; z += x * y; w += y * z;
+    x ^= x >> 16; y ^= y >> 16; z ^= z >> 16; w ^= w >> 16;
+    x += y * w; y += z * x; z += x * y; w += y * z;
+    return int4((int)x, (int)y, (int)z, (int)w);
+}
+
+int4 cultmath_pcg4d(float4 value) { return cultmath_pcg4d(int4((int)asuint(value.x), (int)asuint(value.y), (int)asuint(value.z), (int)asuint(value.w))); }
+
 float cultmath_value_noise(float2 position)
 {
     float2 cell = floor(position);

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

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

packages/cultmesh-browser/src/index.ts

@@ -15,42 +15,27 @@ import {
   type CultMeshSessionAcceptedMessage,
   type CultMeshSessionOpenMessage,
 } from "cultnet-ts/contracts";
+import {
+  base64ToBytes,
+  bytesToBase64,
+  isLoopbackEndpoint,
+  isUnsignedCertificate,
+  verifyAuthorityRoute,
+  verifyProviderSessionProof,
+  type CultMeshAuthorityIdentity,
+  type CultMeshAuthorityRouteCertificate,
+  type CultMeshAuthorityRouteView,
+  type CultMeshAuthorityTrustMode,
+  type CultMeshAuthorityTrustPolicy,
+  type CultMeshP256PublicKey,
+} from "cultnet-ts/authority";
 
-export interface CultMeshBrowserIdentity {
-  verseId: string;
-  authorityRuntimeId: string;
-}
-
-export interface CultMeshBrowserRoute extends CultMeshBrowserIdentity {
-  endpoint: string;
-  protocolId?: string;
-  protocolIds?: readonly string[];
-  priority?: number;
-  generation: string;
-  certificate?: CultMeshBrowserRouteCertificate;
-}
-
-export interface CultMeshBrowserP256PublicKey {
-  keyId: string;
-  x: string;
-  y: string;
-}
-
-export interface CultMeshBrowserRouteCertificate {
-  providerKey: CultMeshBrowserP256PublicKey;
-  odinKeyId: string;
-  issuedAtUnixMilliseconds: number;
-  expiresAtUnixMilliseconds: number;
-  signature: string;
-}
-
-export type CultMeshBrowserAuthorityTrustMode = "authenticated-remote" | "local-development";
-
-export interface CultMeshBrowserAuthorityTrustPolicy {
-  mode: CultMeshBrowserAuthorityTrustMode;
-  odinRoots?: readonly CultMeshBrowserP256PublicKey[];
-  now?: () => number;
-}
+export type CultMeshBrowserIdentity = CultMeshAuthorityIdentity;
+export type CultMeshBrowserRoute = CultMeshAuthorityRouteView;
+export type CultMeshBrowserP256PublicKey = CultMeshP256PublicKey;
+export type CultMeshBrowserRouteCertificate = CultMeshAuthorityRouteCertificate;
+export type CultMeshBrowserAuthorityTrustMode = CultMeshAuthorityTrustMode;
+export type CultMeshBrowserAuthorityTrustPolicy = CultMeshAuthorityTrustPolicy;
 
 export interface CultMeshBrowserRendezvous {
   resolve(
@@ -794,19 +779,6 @@ export function decodeCultNetOperationPayload<T>(response: CultNetOperationRespo
   return decode(base64ToBytes(response.payload)) as T;
 }
 
-function bytesToBase64(bytes: Uint8Array): string {
-  let binary = "";
-  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
-    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
-  }
-  return btoa(binary);
-}
-
-function base64ToBytes(value: string): Uint8Array {
-  const binary = atob(value);
-  return Uint8Array.from(binary, character => character.charCodeAt(0));
-}
-
 function requireWebSocketEndpoint(value: string, field: string): URL {
   let endpoint: URL;
   try {
@@ -941,136 +913,26 @@ async function validateSessionAcceptance(
       `expected '${request.verseId}/${request.authorityRuntimeId}/${protocolId}/${route.generation}'.`,
     );
   }
-  if (trust.mode === "local-development" && isLoopbackEndpoint(route.endpoint) && !route.certificate) return undefined;
+  // `CultMeshVerifiedAuthorityRoute.IsLocalDevelopment` in C#: an unsigned
+  // loopback route under local-development needs no provider session proof.
+  if (trust.mode === "local-development" && isLoopbackEndpoint(route.endpoint) && isUnsignedCertificate(route.certificate)) {
+    return undefined;
+  }
   const providerKey = route.certificate?.providerKey;
   if (!providerKey || message.providerKeyId !== providerKey.keyId || !message.providerSignature) {
     return new Error("CultMesh authority did not prove possession of the Odin-certified provider key.");
   }
-  if (!await verifyP256(providerKey, canonicalSession(request, route.endpoint), message.providerSignature)) {
+  if (!await verifyProviderSessionProof(request, route.endpoint, providerKey, message.providerSignature)) {
     return new Error("CultMesh provider session proof is invalid.");
   }
   return undefined;
 }
 
-async function verifyAuthorityRoute(
-  route: CultMeshBrowserRoute,
-  trust: CultMeshBrowserAuthorityTrustPolicy,
-): Promise<void> {
-  const certificate = route.certificate;
-  if (!certificate) {
-    if (trust.mode === "local-development" && isLoopbackEndpoint(route.endpoint)) return;
-    throw new Error("Remote CultMesh routes require an Odin-signed authority certificate.");
-  }
-  const endpoint = new URL(route.endpoint);
-  if (endpoint.protocol !== "wss:" && !(trust.mode === "local-development" && isLoopbackEndpoint(route.endpoint))) {
-    throw new Error("Authenticated remote CultMesh browser routes require wss:// channel protection.");
-  }
-  const now = trust.now?.() ?? Date.now();
-  if (now < certificate.issuedAtUnixMilliseconds || now >= certificate.expiresAtUnixMilliseconds) {
-    throw new Error("The Odin route certificate is not currently valid.");
-  }
-  const root = trust.odinRoots?.find(candidate => candidate.keyId === certificate.odinKeyId);
-  if (!root) throw new Error(`Odin key '${certificate.odinKeyId}' is not trusted by this consumer.`);
-  if (!await verifyP256(root, canonicalRoute(route), certificate.signature)) {
-    throw new Error("The Odin route certificate signature is invalid.");
-  }
-}
-
-function canonicalRoute(route: CultMeshBrowserRoute): Uint8Array {
-  const certificate = route.certificate!;
-  return canonicalFields(
-    "gamecult.cultmesh.route-certificate.v1",
-    route.verseId,
-    route.authorityRuntimeId,
-    route.endpoint,
-    [...(route.protocolIds ?? [route.protocolId ?? "cultmesh.documents.v1"])].sort().join("\u001f"),
-    String(route.priority ?? 0),
-    route.generation,
-    certificate.providerKey.keyId,
-    certificate.providerKey.x,
-    certificate.providerKey.y,
-    certificate.odinKeyId,
-    String(certificate.issuedAtUnixMilliseconds),
-    String(certificate.expiresAtUnixMilliseconds),
-  );
-}
-
-function canonicalSession(request: CultMeshSessionOpenMessage, endpoint: string): Uint8Array {
-  return canonicalFields(
-    "gamecult.cultmesh.session-proof.v1",
-    request.clientNonce,
-    request.messageId,
-    request.sourceRuntimeId,
-    request.verseId,
-    request.authorityRuntimeId,
-    request.protocolId,
-    endpoint,
-    request.routeGeneration,
-  );
-}
-
-function canonicalFields(...values: string[]): Uint8Array {
-  const encoder = new TextEncoder();
-  const encoded = values.map(value => encoder.encode(value));
-  const total = encoded.reduce((sum, value) => sum + 4 + value.byteLength, 0);
-  const result = new Uint8Array(total);
-  const view = new DataView(result.buffer);
-  let offset = 0;
-  for (const value of encoded) {
-    view.setUint32(offset, value.byteLength, false);
-    offset += 4;
-    result.set(value, offset);
-    offset += value.byteLength;
-  }
-  return result;
-}
-
-async function verifyP256(
-  key: CultMeshBrowserP256PublicKey,
-  payload: Uint8Array,
-  signatureBase64: string,
-): Promise<boolean> {
-  try {
-    const x = base64ToBytes(key.x);
-    const y = base64ToBytes(key.y);
-    const signature = base64ToBytes(signatureBase64);
-    if (x.byteLength !== 32 || y.byteLength !== 32 || signature.byteLength !== 64) return false;
-    const raw = new Uint8Array(65);
-    raw[0] = 4;
-    raw.set(x, 1);
-    raw.set(y, 33);
-    const publicKey = await crypto.subtle.importKey(
-      "raw",
-      raw.slice().buffer as ArrayBuffer,
-      { name: "ECDSA", namedCurve: "P-256" },
-      false,
-      ["verify"],
-    );
-    return await crypto.subtle.verify(
-      { name: "ECDSA", hash: "SHA-256" },
-      publicKey,
-      signature.slice().buffer as ArrayBuffer,
-      payload.slice().buffer as ArrayBuffer,
-    );
-  } catch {
-    return false;
-  }
-}
-
 function randomNonce(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(32));
   return bytesToBase64(bytes);
 }
 
-function isLoopbackEndpoint(value: string): boolean {
-  try {
-    const host = new URL(value).hostname.replace(/^\[|\]$/g, "").toLowerCase();
-    return host === "localhost" || host === "127.0.0.1" || host === "::1";
-  } catch {
-    return false;
-  }
-}
-
 function requireText(value: string, field: string): void {
   if (!value || value.trim().length === 0) throw new Error(`CultMesh browser ${field} is required.`);
 }

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

@@ -236,6 +236,54 @@ test("browser client rejects a credential-free authority impersonator", async ()
   );
 });
 
+test("browser client opens an unsigned-certificate loopback session under local-development without a provider proof, as in C#", async () => {
+  const connect = (route: CultMeshBrowserRoute, trust: { mode: "local-development" | "authenticated-remote"; odinRoots: CultMeshBrowserP256PublicKey[] }) =>
+    CultMeshBrowserClient.connect({
+      ...route,
+      runtimeId: "browser-unsigned-certificate-test",
+      rendezvous: { resolve: async () => route },
+      trust,
+      socketFactory: () => handshakeOnlySocket(route),
+    });
+  const blank = (route: CultMeshBrowserRoute, signature: string) =>
+    ({ ...route, certificate: { ...route.certificate!, signature } });
+
+  const loopback = await createSignedRoute("ws://127.0.0.1:4501/mesh");
+  const localTrust = { mode: "local-development" as const, odinRoots: [loopback.odinPublic] };
+  const remote = await createSignedRoute("wss://provider.example/mesh");
+
+  // Empty is the easy case. The whitespace signatures are the ones that catch a
+  // local re-reading of "unsigned" here: an inline `signature === ""` passes
+  // every other test in this file and fails these, and U+0085 also separates
+  // `String.prototype.trim` from the C# `char.IsWhiteSpace` the shared
+  // `isUnsignedCertificate` uses. Both sides of the session check have to read
+  // "unsigned" the same way, or the route verifier accepts a session the
+  // acceptance check then demands a provider proof for.
+  for (const signature of ["", "   ", "\u0085", "\u00a0\t\n"]) {
+    const label = JSON.stringify(signature);
+    const client = await connect(blank(loopback.route, signature), localTrust);
+    assert.equal(client.state, "connected", label);
+    await client.dispose();
+    await assert.rejects(
+      connect(blank(remote.route, signature), { mode: "local-development", odinRoots: [remote.odinPublic] }),
+      /Odin-signed authority certificate/,
+      label,
+    );
+    await assert.rejects(
+      connect(blank(remote.route, signature), { mode: "authenticated-remote", odinRoots: [remote.odinPublic] }),
+      /Odin-signed authority certificate/,
+      label,
+    );
+  }
+  // U+FEFF is whitespace to JavaScript and not to C#, so it is a signature, not
+  // an unsigned route, and the loopback route is refused for its bytes.
+  await assert.rejects(connect(blank(loopback.route, "\ufeff"), localTrust), /not base64|not IEEE P1363/);
+
+  // A signed loopback certificate is an authenticated route even under
+  // local-development; the provider must still prove its key.
+  await assert.rejects(connect(loopback.route, localTrust), /did not prove possession/);
+});
+
 test("browser client rejects a mutated or expired signed route before opening a provider socket", async () => {
   const fixture = await createSignedRoute("wss://provider.example/mesh");
   let opened = false;

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

@@ -1359,7 +1359,7 @@ fun defineCultNetSchemaDescriptor(
     schemaJson = schemaJson,
 )
 
-private const val cultNetSchemaBase = "https://github.com/GameCult/cultnet-ts/contracts"
+private const val cultNetSchemaBase = "https://github.com/GameCult/CultLib/contracts/cultnet"
 
 private data class CultNetBuiltInSchemaSpec(
     val schemaVersion: String,
@@ -1377,58 +1377,58 @@ private val cultNetBuiltInSchemaSpecs = listOf(
         title = "CultNet Hello Message",
         schemaId = "$cultNetSchemaBase/cultnet.hello.schema.json",
         requiredFields = listOf("schemaVersion", "runtimeId", "runtimeKind"),
-        contentHash = "1d2114bf0c92a2dd5e07dd735778ceeb939402c6424550d6d281d9db423f56b3",
+        contentHash = "f660ef803f293e2882650b3981c6eed835bd8e595c9b880d6c6271e0dcbd79e4",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.document_delete.v0",
         title = "CultNet Document Delete Message",
         schemaId = "$cultNetSchemaBase/cultnet.document-delete.schema.json",
         requiredFields = listOf("schemaVersion", "messageId", "schemaId", "recordKey"),
-        contentHash = "037f7cf1b30756904e0bfada6bcff486269378997afbe3c4b6fc5c573fc8a4df",
+        contentHash = "ed7dc202e4f1ebe0d88c5d60c81c53005b44a2557698d3d3c5d2126c01b40f08",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.document_put_raw.v0",
         title = "CultNet Raw Document Put Message",
         schemaId = "$cultNetSchemaBase/cultnet.document-put-raw.schema.json",
-        contentHash = "b61e7e6cce8508653fbeccc4d956ef211c853a174d67c7e1903ce294e15985a2",
+        contentHash = "34b61b14b49cfc887728673f08aa0f33df7ccd401e79c77d3bc324c72e547177",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.snapshot_request.v0",
         title = "CultNet Snapshot Request Message",
         schemaId = "$cultNetSchemaBase/cultnet.snapshot-request.schema.json",
-        contentHash = "9f6546f51a1aab85978554e6908d7a59e96b3329feff7b35022be210495dd721",
+        contentHash = "05267d9b5eb450d4aa8979179f74ba3aec2f3a82fead7ba4a16ab5462c7750fa",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.snapshot_response_raw.v0",
         title = "CultNet Raw Snapshot Response Message",
         schemaId = "$cultNetSchemaBase/cultnet.snapshot-response-raw.schema.json",
-        contentHash = "0dbca3338a3ae5d4011aed2c973c75b9b47b6b9dfc0874459ac56da01fef4582",
+        contentHash = "fdefbdf5d6b0844dd0eabe2c7430d054295d78e41289f96b227dc39f4aab78b9",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.schema_catalog_request.v0",
         title = "CultNet Schema Catalog Request Message",
         schemaId = "$cultNetSchemaBase/cultnet.schema-catalog-request.schema.json",
         wireContracts = listOf("cultnet.schema.v0", "gamecult.networking.v0"),
-        contentHash = "bdd49b44428daf24b514c521e53027ec944aecfebb39ca0d10967661c303e096",
+        contentHash = "ed6d63e29de2d492bb831f030b26ff49ba6883cd2be791ec4936c385f765c76a",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.schema_catalog_response.v0",
         title = "CultNet Schema Catalog Response Message",
         schemaId = "$cultNetSchemaBase/cultnet.schema-catalog-response.schema.json",
         wireContracts = listOf("cultnet.schema.v0", "gamecult.networking.v0"),
-        contentHash = "b158de53d1ca614eacf2e05767122fb4b9e06504c037ad76c649cffdf71dd648",
+        contentHash = "10b4835d33181fe4b93a33e39b63886c5514899e93682de786e298f7e4a213e9",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.shard_catalog_request.v0",
         title = "CultNet Shard Catalog Request Message",
-        schemaId = "cultnet.shard_catalog_request.v0",
-        contentHash = "0abd131a1db12f6731010333b86e104d550160bd58f539b18413a2b61198fa38",
+        schemaId = "$cultNetSchemaBase/cultnet.shard-catalog-request.schema.json",
+        contentHash = "b4edecd8a24f68ebccf0aca9b429d234618ff7e8858a10123d0b328aeae7eb3f",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.shard_catalog_response.v0",
         title = "CultNet Shard Catalog Response Message",
-        schemaId = "cultnet.shard_catalog_response.v0",
-        contentHash = "93a0e90ac81bc6ab21b68925ad25e381edfac8773232333679d3275141cff37b",
+        schemaId = "$cultNetSchemaBase/cultnet.shard-catalog-response.schema.json",
+        contentHash = "d86a94c57d7820483912b8b5cef6214ac951d34cb2641d2d21dcb1f1bc0263c0",
     ),
     CultNetBuiltInSchemaSpec(
         schemaVersion = "cultnet.shard_log_request.v0",
@@ -1468,7 +1468,7 @@ private val cultNetBuiltInSchemaSpecs = listOf(
         schemaId = "$cultNetSchemaBase/cultnet.transport-profile.schema.json",
         kind = "shared_contract",
         requiredFields = listOf("schemaVersion", "runtimeId", "transports"),
-        contentHash = "84473264f543ca3443267999e43d72b7993b61b7b2ac53c642c9cbe8b6de0217",
+        contentHash = "63dfd484e1fd332c167caadf52cb5b4fe12d5ffea4415206c3ef111c196507aa",
     ),
 )
 
@@ -3717,16 +3717,16 @@ private fun cultNetReconnectControllerSchedulesAttemptsAndReset() {
 private const val interopDocumentType = "cultnet.interop-note"
 private const val interopSchemaVersion = "cultnet.interop_note.v0"
 private const val interopMutationIntentType = "cultnet.interop-note-mutation-intent"
-private const val interopMutationIntentSchemaId = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-intent.schema.json"
+private const val interopMutationIntentSchemaId = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-intent.schema.json"
 private const val interopMutationIntentSchemaVersion = "cultnet.interop_note_mutation_intent.v0"
 private const val interopMutationReceiptType = "cultnet.interop-note-mutation-receipt"
-private const val interopMutationReceiptSchemaId = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-receipt.schema.json"
+private const val interopMutationReceiptSchemaId = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-receipt.schema.json"
 private const val interopMutationReceiptSchemaVersion = "cultnet.interop_note_mutation_receipt.v0"
 private const val interopFireCommandType = "cultnet.interop-fire-weapon-command"
-private const val interopFireCommandSchemaId = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-command.schema.json"
+private const val interopFireCommandSchemaId = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-command.schema.json"
 private const val interopFireCommandSchemaVersion = "cultnet.interop_fire_weapon_command.v0"
 private const val interopFireReceiptType = "cultnet.interop-fire-weapon-receipt"
-private const val interopFireReceiptSchemaId = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-receipt.schema.json"
+private const val interopFireReceiptSchemaId = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-receipt.schema.json"
 private const val interopFireReceiptSchemaVersion = "cultnet.interop_fire_weapon_receipt.v0"
 private const val rudpInteropConnectionId = 0x43554c54L
 private const val rudpInteropMaxFragmentBytes = 1024
@@ -4627,11 +4627,11 @@ private fun cultNetBuiltInSchemaCatalogAdvertisesWireContracts() {
     check(schemaCatalogRequest["wireContracts"] == listOf("cultnet.schema.v0", "gamecult.networking.v0"))
     check(!schemaCatalogRequest.containsKey("schemaJson"))
     val shardCatalogRequest = schemas.single { it["schemaVersion"] == "cultnet.shard_catalog_request.v0" }
-    check(shardCatalogRequest["schemaId"] == "cultnet.shard_catalog_request.v0")
+    check(shardCatalogRequest["schemaId"] == "$cultNetSchemaBase/cultnet.shard-catalog-request.schema.json")
     check(shardCatalogRequest["wireContracts"] == listOf("cultnet.schema.v0"))
-    check(shardCatalogRequest["contentHash"] == "0abd131a1db12f6731010333b86e104d550160bd58f539b18413a2b61198fa38")
+    check(shardCatalogRequest["contentHash"] == "b4edecd8a24f68ebccf0aca9b429d234618ff7e8858a10123d0b328aeae7eb3f")
     val shardCatalogResponse = schemas.single { it["schemaVersion"] == "cultnet.shard_catalog_response.v0" }
-    check(shardCatalogResponse["schemaId"] == "cultnet.shard_catalog_response.v0")
+    check(shardCatalogResponse["schemaId"] == "$cultNetSchemaBase/cultnet.shard-catalog-response.schema.json")
     check(shardCatalogResponse["wireContracts"] == listOf("cultnet.schema.v0"))
 
     val inlineCatalog = cultNetBuiltInSchemaCatalog(includeSchemaJson = true)
@@ -4644,7 +4644,7 @@ private fun cultNetBuiltInSchemaCatalogAdvertisesWireContracts() {
     )
     val transportProfile = mapList(transportResponse.body["schemas"]).single()
     check(transportProfile["kind"] == "shared_contract")
-    check(transportProfile["contentHash"] == "84473264f543ca3443267999e43d72b7993b61b7b2ac53c642c9cbe8b6de0217")
+    check(transportProfile["contentHash"] == "63dfd484e1fd332c167caadf52cb5b4fe12d5ffea4415206c3ef111c196507aa")
     check(!transportProfile.containsKey("schemaJson"))
 
     val filteredTransportCatalog = CultMesh.createBuiltInSchemaCatalog(

packages/cultmesh-py/tests/test_cultmesh.py

@@ -1759,11 +1759,11 @@ class CultMeshTests(unittest.TestCase):
             )
             self.assertEqual(
                 builtins.list()[0].schema_id,
-                "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
+                "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json",
             )
             self.assertIsNone(builtins.list()[0].schema_json)
             peer_exchange_schema_id = (
-                "https://github.com/GameCult/cultnet-ts/contracts/cultmesh.peer-exchange-request.schema.json"
+                "https://github.com/GameCult/CultLib/contracts/cultnet/cultmesh.peer-exchange-request.schema.json"
             )
             filtered_builtin = CultMesh.create_builtin_schema_catalog(
                 include_schema_json=True,
@@ -4033,7 +4033,7 @@ class CultMeshTests(unittest.TestCase):
         self.assertIn("cultmesh.peer_exchange_response.v0", wire_descriptors)
         self.assertIn("cultnet.error.v0", {descriptor.schema_version for descriptor in synced_wire_descriptors})
         self.assertIn("cultnet.document_put_raw.v0", {descriptor.schema_version for descriptor in synced_wire_descriptors})
-        self.assertIsNotNone(synced_schema_catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json"))
+        self.assertIsNotNone(synced_schema_catalog.get("https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-put-raw.schema.json"))
         self.assertEqual(snapshot_response["documents"][0]["recordKey"], "note:1")
         self.assertEqual(typed_snapshot_response.documents[0].record_key, "note:1")
         self.assertEqual(typed_snapshot_response.documents[0].schema_id, "mesh.server_note.v1")

packages/cultmesh-ts/src/index.ts

@@ -34,6 +34,7 @@ import {
   type CultNetWireContract,
 } from "cultnet-ts";
 
+export * from "./realtime-wire";
 export * from "./provider-session";
 export * from "./provider-session-wire";
 export * from "./provider-rudp-transport";

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

@@ -0,0 +1,191 @@
+// The one TypeScript encoding of a CultMesh realtime frame.
+//
+// Rule for rule, this is `CultMeshRealtimeWireProtocol` in the C# reference
+// (`src/GameCult.Mesh/CultMeshRealtimeWireProtocol.cs`), over the frame shape
+// `CultMeshRealtimeTransports.cs` defines. QUIC stream framing stays
+// transport-owned; this file owns only the typed frame bytes and never touches
+// a socket.
+//
+// Byte parity is proven both ways, cross-process, by two committed vector files
+// under `contracts/cultmesh/`: `realtime-frame-vectors.json`, which the C# test
+// `CultMeshRealtimeWireProtocolTests` writes under CULTMESH_WRITE_VECTORS=1 and
+// this package's test decodes and re-encodes, and
+// `realtime-frame-vectors.ts-written.json`, which
+// `scripts/write-cultmesh-realtime-frame-vectors.mjs` writes with this codec and
+// the same C# test decodes. A fixture authored on one side alone would only
+// agree with itself.
+
+import { isNullOrWhiteSpaceCSharp } from "cultnet-ts";
+
+/** `CultMeshRealtimeWireProtocol.ApplicationProtocolName`: the QUIC ALPN. */
+export const CULTMESH_REALTIME_ALPN = "cultmesh-state-v1";
+
+/** `ConnectionCloseCode`: ASCII "CULT". A QUIC error code is 62-bit, so bigint. */
+export const CULTMESH_REALTIME_CONNECTION_CLOSE_CODE = 0x43554c54n;
+
+/** `StreamAbortCode`: ASCII "STAT". */
+export const CULTMESH_REALTIME_STREAM_ABORT_CODE = 0x53544154n;
+
+/** `ReliableStream`: the stream kind carrying `reliable-ordered`. */
+export const CULTMESH_REALTIME_RELIABLE_STREAM = 1;
+
+/** `LatestOnlyStream`: the stream kind carrying `latest-only`. */
+export const CULTMESH_REALTIME_LATEST_ONLY_STREAM = 2;
+
+/** `MaximumFrameBytes`: the payload ceiling, 64 MiB. */
+export const CULTMESH_REALTIME_MAX_PAYLOAD_BYTES = 64 * 1024 * 1024;
+
+/** `MaximumEncodedFrameBytes`: the payload ceiling plus the header and three maximal identities. */
+export const CULTMESH_REALTIME_MAX_ENCODED_FRAME_BYTES =
+  CULTMESH_REALTIME_MAX_PAYLOAD_BYTES + 37 + 3 * 0xffff;
+
+/**
+ * `CultMeshRealtimeDelivery`. The wire byte is the C# enum's ordinal, so the
+ * order of these three is the wire contract, not a naming choice.
+ */
+export type CultMeshRealtimeDelivery = "reliable-ordered" | "latest-only" | "unreliable";
+
+const DELIVERY_BYTES: readonly CultMeshRealtimeDelivery[] = ["reliable-ordered", "latest-only", "unreliable"];
+
+/** `CultMeshRealtimeFrame`. `producerEpoch` and `sequence` are `long` in C#, which exceeds `Number.MAX_SAFE_INTEGER`. */
+export interface CultMeshRealtimeFrame {
+  channelId: string;
+  schemaId: string;
+  bodyId: string;
+  producerEpoch: bigint;
+  sequence: bigint;
+  delivery: CultMeshRealtimeDelivery;
+  payload: Uint8Array;
+}
+
+const MAGIC = 0x31545343;
+const FIXED_HEADER_BYTES = 37;
+const WIRE_VERSION = 1;
+const MAX_IDENTITY_BYTES = 0xffff;
+const INT64_MIN = -(2n ** 63n);
+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.
+ *
+ * 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`
+ * from inside the encoder.
+ */
+function validateFrame(frame: CultMeshRealtimeFrame): void {
+  if (isNullOrWhiteSpaceCSharp(frame.channelId)) throw new Error("Realtime channel identity is required.");
+  if (isNullOrWhiteSpaceCSharp(frame.schemaId)) throw new Error("Realtime schema identity is required.");
+  if (isNullOrWhiteSpaceCSharp(frame.bodyId)) throw new Error("Realtime body identity is required.");
+  if (frame.producerEpoch < 0n || frame.sequence < 0n) {
+    throw new Error("Realtime epoch and sequence must be non-negative.");
+  }
+  if (frame.producerEpoch > INT64_MAX || frame.sequence > INT64_MAX || frame.producerEpoch < INT64_MIN || frame.sequence < INT64_MIN) {
+    throw new Error("Realtime epoch and sequence must fit a 64-bit signed integer.");
+  }
+}
+
+/** `CultMeshRealtimeWireProtocol.EncodeFrame`. */
+export function encodeRealtimeFrame(frame: CultMeshRealtimeFrame): Uint8Array {
+  validateFrame(frame);
+  const deliveryByte = DELIVERY_BYTES.indexOf(frame.delivery);
+  // C# reads an enum, which holds any byte; a TypeScript union does not, so the
+  // unspellable value is refused here with the message decode gives it.
+  if (deliveryByte < 0) throw new Error("Realtime frame delivery mode is invalid.");
+  const encoder = new TextEncoder();
+  const channel = encoder.encode(frame.channelId);
+  const schema = encoder.encode(frame.schemaId);
+  const body = encoder.encode(frame.bodyId);
+  if (channel.byteLength > MAX_IDENTITY_BYTES || schema.byteLength > MAX_IDENTITY_BYTES || body.byteLength > MAX_IDENTITY_BYTES) {
+    throw new Error("Realtime frame identity exceeds the QUIC wire limit.");
+  }
+  if (frame.payload.byteLength > CULTMESH_REALTIME_MAX_PAYLOAD_BYTES) {
+    throw new Error("Realtime frame payload exceeds the QUIC wire limit.");
+  }
+
+  const result = new Uint8Array(
+    FIXED_HEADER_BYTES + channel.byteLength + schema.byteLength + body.byteLength + frame.payload.byteLength,
+  );
+  const view = new DataView(result.buffer);
+  view.setUint32(0, MAGIC, true);
+  result[4] = deliveryByte;
+  view.setBigInt64(5, frame.producerEpoch, true);
+  view.setBigInt64(13, frame.sequence, true);
+  view.setUint16(21, channel.byteLength, true);
+  view.setUint16(23, schema.byteLength, true);
+  view.setUint16(25, body.byteLength, true);
+  view.setInt32(27, frame.payload.byteLength, true);
+  view.setInt32(31, FIXED_HEADER_BYTES, true);
+  view.setUint16(35, WIRE_VERSION, true);
+  let offset = FIXED_HEADER_BYTES;
+  result.set(channel, offset); offset += channel.byteLength;
+  result.set(schema, offset); offset += schema.byteLength;
+  result.set(body, offset); offset += body.byteLength;
+  result.set(frame.payload, offset);
+  return result;
+}
+
+/**
+ * `CultMeshRealtimeWireProtocol.DecodeFrame`, refusal for refusal and in the
+ * same order. Like the reference, it does not call `validateFrame`: a frame
+ * whose identities are blank decodes here exactly as it does in C#, and only
+ * encoding refuses it.
+ *
+ * One corner has no C# counterpart. The reference sums the lengths under
+ * `checked`, so a payload length near `int.MaxValue` throws `OverflowException`
+ * there rather than its length refusal; JavaScript numbers do not overflow, so
+ * the sum simply fails to match and the length refusal covers that case too.
+ * No encoder on either side can produce such a frame.
+ */
+export function decodeRealtimeFrame(bytes: Uint8Array): CultMeshRealtimeFrame {
+  if (bytes.byteLength < FIXED_HEADER_BYTES) throw new Error("Realtime frame header is truncated.");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0, true) !== MAGIC) throw new Error("Realtime frame magic is invalid.");
+  if (view.getUint16(35, true) !== WIRE_VERSION || view.getInt32(31, true) !== FIXED_HEADER_BYTES) {
+    throw new Error("Realtime frame wire version is unsupported.");
+  }
+  const delivery = DELIVERY_BYTES[bytes[4]!];
+  if (delivery === undefined) throw new Error("Realtime frame delivery mode is invalid.");
+  const channelLength = view.getUint16(21, true);
+  const schemaLength = view.getUint16(23, true);
+  const bodyLength = view.getUint16(25, true);
+  const payloadLength = view.getInt32(27, true);
+  const expected = FIXED_HEADER_BYTES + channelLength + schemaLength + bodyLength + payloadLength;
+  if (payloadLength < 0 || expected !== bytes.byteLength) throw new Error("Realtime frame length is invalid.");
+  // `Encoding.UTF8.GetString` substitutes U+FFFD for invalid bytes rather than
+  // throwing, which is what a non-fatal `TextDecoder` does. `ignoreBOM` is not
+  // cosmetic: by default `TextDecoder` *deletes* a leading U+FEFF, and
+  // `GetString` keeps it, so an identity starting with a byte-order mark would
+  // decode to a different string on the two sides. U+FEFF is not whitespace to
+  // .NET either, so such an identity passes the transport contract and reaches
+  // the wire.
+  const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+  let offset = FIXED_HEADER_BYTES;
+  const channelId = decoder.decode(bytes.subarray(offset, offset + channelLength)); offset += channelLength;
+  const schemaId = decoder.decode(bytes.subarray(offset, offset + schemaLength)); offset += schemaLength;
+  const bodyId = decoder.decode(bytes.subarray(offset, offset + bodyLength)); offset += bodyLength;
+  return {
+    channelId,
+    schemaId,
+    bodyId,
+    producerEpoch: view.getBigInt64(5, true),
+    sequence: view.getBigInt64(13, true),
+    delivery,
+    // Not `bytes.slice(...)`. Node's `Buffer` overrides `slice` with an alias of
+    // `subarray`, so on a `Buffer` — which is what every socket read hands a Node
+    // caller — that spelling returns a *view* of the frame, and a decoded payload
+    // that changes when the frame buffer is reused.
+    //
+    // Nor `Uint8Array.prototype.slice.call(bytes, ...)`, which does bypass the
+    // override and copy, but takes its result constructor from `@@species`: on a
+    // `Buffer` that is `FastBuffer`, so the payload comes back a `Buffer` from a
+    // `Buffer` frame and a `Uint8Array` from a `Uint8Array` one. The declared
+    // type holds either way, but `deepStrictEqual` does not, so the same frame
+    // would compare equal or not depending on how it reached the decoder.
+    //
+    // The constructor copies and is the one type on both inputs.
+    payload: new Uint8Array(bytes.subarray(offset, offset + payloadLength)),
+  };
+}

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

@@ -2500,16 +2500,20 @@ test("CultMesh TS branded facade exposes schema and shard catalogs", () => {
 
   const builtIns = CultMesh.createBuiltInSchemaCatalog();
   assert.equal(
-    builtIns.get("cultnet.shard_catalog_request.v0")?.schemaVersion,
+    builtIns.get(
+      "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.shard-catalog-request.schema.json",
+    )?.schemaVersion,
     "cultnet.shard_catalog_request.v0",
   );
   assert.equal(
-    builtIns.get("cultnet.shard_catalog_response.v0")?.kind,
+    builtIns.get(
+      "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.shard-catalog-response.schema.json",
+    )?.kind,
     "wire_message",
   );
   assert.equal(
     builtIns.get(
-      "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
+      "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json",
     )?.schemaVersion,
     "cultnet.transport_profile.v0",
   );

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

@@ -0,0 +1,397 @@
+// The realtime frame codec, pinned rule by rule against the C# reference.
+//
+// The bytes themselves are pinned by two committed files under
+// `contracts/cultmesh/`. `realtime-frame-vectors.json` is written by
+// `CultMeshRealtimeWireProtocolTests.RealtimeFrameVectorsAreSharedWithTypeScript`
+// under CULTMESH_WRITE_VECTORS=1: this side decodes it and re-encodes to the
+// same bytes. `realtime-frame-vectors.ts-written.json` is written by
+// `scripts/write-cultmesh-realtime-frame-vectors.mjs` with this codec and
+// decoded by the C# reference, so parity is proven in both directions and in
+// two processes. A fixture authored on one side alone would only agree with
+// itself, which is what the authority vectors already taught.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  CULTMESH_REALTIME_ALPN,
+  CULTMESH_REALTIME_CONNECTION_CLOSE_CODE,
+  CULTMESH_REALTIME_LATEST_ONLY_STREAM,
+  CULTMESH_REALTIME_MAX_ENCODED_FRAME_BYTES,
+  CULTMESH_REALTIME_MAX_PAYLOAD_BYTES,
+  CULTMESH_REALTIME_RELIABLE_STREAM,
+  CULTMESH_REALTIME_STREAM_ABORT_CODE,
+  decodeRealtimeFrame,
+  encodeRealtimeFrame,
+  type CultMeshRealtimeDelivery,
+  type CultMeshRealtimeFrame,
+} from "../src/realtime-wire";
+
+const CONTRACTS = join(__dirname, "..", "..", "..", "..", "contracts", "cultmesh");
+const CSHARP_VECTORS = join(CONTRACTS, "realtime-frame-vectors.json");
+const TS_VECTORS = join(CONTRACTS, "realtime-frame-vectors.ts-written.json");
+
+interface IdentityRule { repeat: string; byteLength: number }
+interface RampRule { ramp: number }
+interface VectorFields {
+  channelId: string | IdentityRule;
+  schemaId: string | IdentityRule;
+  bodyId: string | IdentityRule;
+  producerEpoch: number;
+  sequence: number;
+  delivery: CultMeshRealtimeDelivery;
+  payload: string | RampRule;
+}
+interface Vectors {
+  frames: {
+    label: string;
+    fields: VectorFields;
+    encoding: string | null;
+    encodedLength: number;
+    sha256OfEncoding: string;
+  }[];
+  malformed: { label: string; encoding: string; message: string }[];
+}
+
+/** The repeat unit written whole until the UTF-8 byte length is exactly `byteLength`. */
+function repeatToByteLength(unit: string, byteLength: number): string {
+  const unitBytes = Buffer.byteLength(unit, "utf8");
+  assert.equal(byteLength % unitBytes, 0, `'${unit}' is ${unitBytes} UTF-8 bytes and does not divide ${byteLength}`);
+  return unit.repeat(byteLength / unitBytes);
+}
+
+/** The deterministic payload both runtimes build the same way. */
+function ramp(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  for (let index = 0; index < length; index += 1) bytes[index] = index % 251;
+  return bytes;
+}
+
+function identity(value: string | IdentityRule): string {
+  return typeof value === "string" ? value : repeatToByteLength(value.repeat, value.byteLength);
+}
+
+function payload(value: string | RampRule): Uint8Array {
+  return typeof value === "string" ? new Uint8Array(Buffer.from(value, "base64")) : ramp(value.ramp);
+}
+
+function frameOf(fields: VectorFields): CultMeshRealtimeFrame {
+  return {
+    channelId: identity(fields.channelId),
+    schemaId: identity(fields.schemaId),
+    bodyId: identity(fields.bodyId),
+    // The C# `long` fields are written as JSON integers and can exceed the safe
+    // integer range, so they are read from the raw text, never through
+    // `JSON.parse`'s number.
+    producerEpoch: 0n,
+    sequence: 0n,
+    delivery: fields.delivery,
+    payload: payload(fields.payload),
+  };
+}
+
+// `JSON.parse` would round `long.MaxValue` to 9223372036854775808, which is not
+// a valid i64 and not what either side encoded. The two i64 fields are lifted
+// out of the raw text as bigints before the document is parsed.
+function readVectors(path: string): { doc: Vectors; int64s: Map<string, { producerEpoch: bigint; sequence: bigint }> } {
+  const text = readFileSync(path, "utf8");
+  const int64s = new Map<string, { producerEpoch: bigint; sequence: bigint }>();
+  const pattern = /"label": "(?<label>(?:[^"\\]|\\.)*)"[\s\S]*?"producerEpoch": (?<epoch>-?\d+),\s*"sequence": (?<sequence>-?\d+),/g;
+  for (const match of text.matchAll(pattern)) {
+    const groups = match.groups!;
+    int64s.set(JSON.parse(`"${groups["label"]!}"`) as string, {
+      producerEpoch: BigInt(groups["epoch"]!),
+      sequence: BigInt(groups["sequence"]!),
+    });
+  }
+  return { doc: JSON.parse(text) as Vectors, int64s };
+}
+
+const sha256 = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+for (const [label, path] of [["C# reference", CSHARP_VECTORS], ["TypeScript-written", TS_VECTORS]] as const) {
+  test(`every ${label} frame vector decodes to its recorded fields and re-encodes to its recorded bytes`, () => {
+    const { doc, int64s } = readVectors(path);
+    assert.ok(doc.frames.length >= 8, `${label} carries ${doc.frames.length} frames`);
+    const seen = new Set<CultMeshRealtimeDelivery>();
+    for (const vector of doc.frames) {
+      const int64 = int64s.get(vector.label);
+      assert.ok(int64, `${vector.label}: no i64 pair was lifted from the text`);
+      const frame = { ...frameOf(vector.fields), ...int64 };
+      seen.add(frame.delivery);
+
+      // This side encodes the recorded fields to the recorded bytes.
+      const encoded = encodeRealtimeFrame(frame);
+      assert.equal(encoded.byteLength, vector.encodedLength, vector.label);
+      assert.equal(sha256(encoded), vector.sha256OfEncoding, vector.label);
+      // The two oversized cases carry no literal encoding; the digest above is
+      // the whole of their parity.
+      const recorded = vector.encoding === null ? encoded : new Uint8Array(Buffer.from(vector.encoding, "base64"));
+      assert.deepEqual(recorded, encoded, vector.label);
+
+      // And decodes those bytes back to the recorded fields.
+      const decoded = decodeRealtimeFrame(recorded);
+      assert.equal(decoded.channelId, frame.channelId, vector.label);
+      assert.equal(decoded.schemaId, frame.schemaId, vector.label);
+      assert.equal(decoded.bodyId, frame.bodyId, vector.label);
+      assert.equal(decoded.producerEpoch, frame.producerEpoch, vector.label);
+      assert.equal(decoded.sequence, frame.sequence, vector.label);
+      assert.equal(decoded.delivery, frame.delivery, vector.label);
+      assert.deepEqual(decoded.payload, frame.payload, vector.label);
+    }
+    // One vector per delivery mode, or a mode is unpinned.
+    assert.deepEqual([...seen].sort(), ["latest-only", "reliable-ordered", "unreliable"]);
+  });
+
+  test(`every ${label} malformed vector is refused with the C# reference's exact message`, () => {
+    const { doc } = readVectors(path);
+    assert.ok(doc.malformed.length >= 8, `${label} carries ${doc.malformed.length} malformed frames`);
+    for (const vector of doc.malformed) {
+      const bytes = new Uint8Array(Buffer.from(vector.encoding, "base64"));
+      assert.throws(
+        () => decodeRealtimeFrame(bytes),
+        (error: Error) => error.message === vector.message,
+        `${vector.label}: expected ${JSON.stringify(vector.message)}`,
+      );
+    }
+    // Every refusal the C# decoder can give is exercised by the file.
+    assert.deepEqual([...new Set(doc.malformed.map(vector => vector.message))].sort(), [
+      "Realtime frame delivery mode is invalid.",
+      "Realtime frame header is truncated.",
+      "Realtime frame length is invalid.",
+      "Realtime frame magic is invalid.",
+      "Realtime frame wire version is unsupported.",
+    ]);
+  });
+}
+
+const sample = (overrides: Partial<CultMeshRealtimeFrame> = {}): CultMeshRealtimeFrame => ({
+  channelId: "aetheria.zone-1",
+  schemaId: "cultmesh.realtime.v1",
+  bodyId: "body-7",
+  producerEpoch: 1n,
+  sequence: 2n,
+  delivery: "reliable-ordered",
+  payload: Uint8Array.from([1, 2, 3]),
+  ...overrides,
+});
+
+test("the wire constants are the C# reference's, including the ALPN and the two QUIC error codes", () => {
+  assert.equal(CULTMESH_REALTIME_ALPN, "cultmesh-state-v1");
+  assert.equal(CULTMESH_REALTIME_CONNECTION_CLOSE_CODE, 0x43554c54n);
+  assert.equal(CULTMESH_REALTIME_STREAM_ABORT_CODE, 0x53544154n);
+  assert.equal(CULTMESH_REALTIME_RELIABLE_STREAM, 1);
+  assert.equal(CULTMESH_REALTIME_LATEST_ONLY_STREAM, 2);
+  assert.equal(CULTMESH_REALTIME_MAX_PAYLOAD_BYTES, 64 * 1024 * 1024);
+  assert.equal(CULTMESH_REALTIME_MAX_ENCODED_FRAME_BYTES, 64 * 1024 * 1024 + 37 + 3 * 65535);
+  // The ALPN and the close codes are ASCII the C# side spells as numbers.
+  assert.equal(Buffer.from("CULT", "ascii").readUInt32BE(0), Number(CULTMESH_REALTIME_CONNECTION_CLOSE_CODE));
+  assert.equal(Buffer.from("STAT", "ascii").readUInt32BE(0), Number(CULTMESH_REALTIME_STREAM_ABORT_CODE));
+});
+
+// `CultMeshRealtimeWireProtocol.cs:37-54`, offset by offset. A vector proves the
+// whole layout at once; this says which byte carries which field, so a swap of
+// two same-width fields names itself.
+test("the fixed header is 37 little-endian bytes in the reference's order", () => {
+  const encoded = encodeRealtimeFrame(sample({
+    channelId: "ch", schemaId: "sch", bodyId: "bdy",
+    producerEpoch: 0x0102030405060708n, sequence: 0x1112131415161718n,
+    delivery: "unreliable", payload: Uint8Array.from([0xaa]),
+  }));
+  const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+  assert.equal(view.getUint32(0, true), 0x31545343, "magic, little-endian");
+  assert.deepEqual([...encoded.subarray(0, 4)], [0x43, 0x53, 0x54, 0x31], "magic bytes as written");
+  assert.equal(encoded[4], 2, "delivery");
+  assert.equal(view.getBigInt64(5, true), 0x0102030405060708n, "producer epoch");
+  assert.equal(view.getBigInt64(13, true), 0x1112131415161718n, "sequence");
+  assert.equal(view.getUint16(21, true), 2, "channel length");
+  assert.equal(view.getUint16(23, true), 3, "schema length");
+  assert.equal(view.getUint16(25, true), 3, "body length");
+  assert.equal(view.getInt32(27, true), 1, "payload length");
+  assert.equal(view.getInt32(31, true), 37, "header size");
+  assert.equal(view.getUint16(35, true), 1, "wire version");
+  assert.equal(Buffer.from(encoded.subarray(37, 37 + 2 + 3 + 3)).toString("utf8"), "chschbdy", "identities in order");
+  assert.deepEqual([...encoded.subarray(45)], [0xaa], "payload last");
+  assert.equal(encoded.byteLength, 37 + 2 + 3 + 3 + 1);
+});
+
+test("the delivery byte is the C# enum ordinal: 0, 1, 2 in that order", () => {
+  const bytes: Record<CultMeshRealtimeDelivery, number> = { "reliable-ordered": 0, "latest-only": 1, "unreliable": 2 };
+  for (const [delivery, byte] of Object.entries(bytes) as [CultMeshRealtimeDelivery, number][]) {
+    const encoded = encodeRealtimeFrame(sample({ delivery }));
+    assert.equal(encoded[4], byte, delivery);
+    assert.equal(decodeRealtimeFrame(encoded).delivery, delivery, delivery);
+  }
+  assert.throws(
+    () => encodeRealtimeFrame(sample({ delivery: "at-most-once" as CultMeshRealtimeDelivery })),
+    /delivery mode is invalid/,
+  );
+});
+
+test("identities are UTF-8 and their length prefixes count bytes, not characters", () => {
+  const frame = sample({ channelId: "z\u00f6ne-\u221e", schemaId: "s", bodyId: "b" });
+  const encoded = encodeRealtimeFrame(frame);
+  const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+  assert.equal(frame.channelId.length, 6);
+  assert.equal(view.getUint16(21, true), Buffer.byteLength(frame.channelId, "utf8"));
+  assert.equal(view.getUint16(21, true), 9);
+  assert.equal(decodeRealtimeFrame(encoded).channelId, frame.channelId);
+});
+
+test("an identity of exactly 65535 UTF-8 bytes encodes and one byte more is refused", () => {
+  const wide = repeatToByteLength("\u00e4\u20ac", 65535);
+  assert.equal(Buffer.byteLength(wide, "utf8"), 65535);
+  assert.notEqual(wide.length, 65535);
+  const encoded = encodeRealtimeFrame(sample({ channelId: wide }));
+  assert.equal(new DataView(encoded.buffer, encoded.byteOffset).getUint16(21, true), 65535);
+  assert.equal(decodeRealtimeFrame(encoded).channelId, wide);
+  for (const field of ["channelId", "schemaId", "bodyId"] as const) {
+    assert.throws(
+      () => encodeRealtimeFrame(sample({ [field]: `${wide}a` })),
+      /identity exceeds the QUIC wire limit/,
+      field,
+    );
+  }
+});
+
+test("a payload at the 64 MiB ceiling encodes and one byte more is refused", () => {
+  const encoded = encodeRealtimeFrame(sample({ payload: ramp(CULTMESH_REALTIME_MAX_PAYLOAD_BYTES) }));
+  assert.equal(encoded.byteLength, 37 + 15 + 20 + 6 + CULTMESH_REALTIME_MAX_PAYLOAD_BYTES);
+  assert.equal(decodeRealtimeFrame(encoded).payload.byteLength, CULTMESH_REALTIME_MAX_PAYLOAD_BYTES);
+  assert.throws(
+    () => encodeRealtimeFrame(sample({ payload: new Uint8Array(CULTMESH_REALTIME_MAX_PAYLOAD_BYTES + 1) })),
+    /payload exceeds the QUIC wire limit/,
+  );
+});
+
+// `CultMeshRealtimeTransports.cs:29-39`, message for message. The blank strings
+// are C#'s `IsNullOrWhiteSpace` set, not `String.prototype.trim`'s: U+0085 is
+// whitespace to .NET and not to JavaScript, and U+FEFF the other way round.
+test("encode refuses what the transport contract forbids, in the reference's words", () => {
+  for (const blank of ["", " ", "\t", "\u0085", "\u3000"]) {
+    assert.throws(() => encodeRealtimeFrame(sample({ channelId: blank })), /^Error: Realtime channel identity is required\.$/);
+    assert.throws(() => encodeRealtimeFrame(sample({ schemaId: blank })), /^Error: Realtime schema identity is required\.$/);
+    assert.throws(() => encodeRealtimeFrame(sample({ bodyId: blank })), /^Error: Realtime body identity is required\.$/);
+  }
+  // U+FEFF is not whitespace to .NET, so it is a legal one-character identity.
+  assert.equal(decodeRealtimeFrame(encodeRealtimeFrame(sample({ channelId: "\ufeff" }))).channelId, "\ufeff");
+  assert.throws(() => encodeRealtimeFrame(sample({ producerEpoch: -1n })), /epoch and sequence must be non-negative/);
+  assert.throws(() => encodeRealtimeFrame(sample({ sequence: -1n })), /epoch and sequence must be non-negative/);
+  // C# gets this bound from `long`; a bigint does not.
+  assert.throws(() => encodeRealtimeFrame(sample({ sequence: 2n ** 63n })), /must fit a 64-bit signed integer/);
+  assert.equal(encodeRealtimeFrame(sample({ sequence: 2n ** 63n - 1n })).byteLength, 37 + 15 + 20 + 6 + 3);
+});
+
+// `CultMeshRealtimeWireProtocol.cs:60-76`, refusal for refusal and in the same
+// order: a frame that breaks two rules names the earlier one.
+test("decode refuses every malformed frame the reference refuses, in the reference's order", () => {
+  const good = encodeRealtimeFrame(sample());
+  const spoil = (mutate: (bytes: Uint8Array) => void) => { const copy = Uint8Array.from(good); mutate(copy); return copy; };
+  const cases: readonly (readonly [string, Uint8Array, string])[] = [
+    ["a header one byte short", good.subarray(0, 36), "Realtime frame header is truncated."],
+    ["an empty buffer", new Uint8Array(0), "Realtime frame header is truncated."],
+    ["a wrong magic", spoil(bytes => { bytes[3] = 0x32; }), "Realtime frame magic is invalid."],
+    ["a big-endian magic", spoil(bytes => bytes.set([0x31, 0x54, 0x53, 0x43], 0)), "Realtime frame magic is invalid."],
+    ["wire version 0", spoil(bytes => { bytes[35] = 0; }), "Realtime frame wire version is unsupported."],
+    ["wire version 2", spoil(bytes => { bytes[35] = 2; }), "Realtime frame wire version is unsupported."],
+    ["header size 36", spoil(bytes => { bytes[31] = 36; }), "Realtime frame wire version is unsupported."],
+    ["header size 38", spoil(bytes => { bytes[31] = 38; }), "Realtime frame wire version is unsupported."],
+    ["delivery 3", spoil(bytes => { bytes[4] = 3; }), "Realtime frame delivery mode is invalid."],
+    ["delivery 255", spoil(bytes => { bytes[4] = 255; }), "Realtime frame delivery mode is invalid."],
+    ["a negative payload length", spoil(bytes => { bytes[30] = 0x80; }), "Realtime frame length is invalid."],
+    ["one byte too many", Uint8Array.from([...good, 0]), "Realtime frame length is invalid."],
+    ["one byte too few", good.subarray(0, good.byteLength - 1), "Realtime frame length is invalid."],
+    ["a channel length one too long", spoil(bytes => { bytes[21] += 1; }), "Realtime frame length is invalid."],
+  ];
+  for (const [label, bytes, message] of cases) {
+    assert.throws(() => decodeRealtimeFrame(bytes), (error: Error) => error.message === message, label);
+  }
+  // Order: a frame whose magic and delivery are both wrong is refused for the
+  // magic, and one whose version and delivery are both wrong for the version.
+  assert.throws(
+    () => decodeRealtimeFrame(spoil(bytes => { bytes[3] = 0x32; bytes[4] = 9; })),
+    (error: Error) => error.message === "Realtime frame magic is invalid.",
+  );
+  assert.throws(
+    () => decodeRealtimeFrame(spoil(bytes => { bytes[35] = 3; bytes[4] = 9; })),
+    (error: Error) => error.message === "Realtime frame wire version is unsupported.",
+  );
+  // Like the reference, decode does not re-run the transport contract: a frame
+  // with a blank identity decodes rather than being refused.
+  const blank = spoil(bytes => bytes.set(new Uint8Array(15).fill(0x20), 37));
+  assert.equal(decodeRealtimeFrame(blank).channelId, " ".repeat(15));
+});
+
+// The `payloadLength < 0` clause in the length refusal is not redundant with the
+// sum check beside it, which is what a surviving mutant that dropped it claimed.
+// A negative payload length cancels against the identity lengths, so a frame can
+// be crafted whose sum lands exactly on its own byte length. Without the clause
+// each of these decodes to blank identities and an empty payload where the C#
+// reference (`CultMeshRealtimeWireProtocol.cs:74-76`, same clause) refuses.
+test("decode refuses a negative payload length that the length sum cancels out", () => {
+  const good = encodeRealtimeFrame(sample());
+  // A valid magic, wire version, header size and delivery byte, then the three
+  // identity lengths and the payload length written by hand.
+  const crafted = (channelLength: number, payloadLength: number, totalBytes: number) => {
+    const bytes = new Uint8Array(totalBytes);
+    bytes.set(good.subarray(0, 37), 0);
+    const view = new DataView(bytes.buffer);
+    view.setUint16(21, channelLength, true);
+    view.setUint16(23, 0, true);
+    view.setUint16(25, 0, true);
+    view.setInt32(27, payloadLength, true);
+    // The sum the decoder computes must land exactly on the frame's own length,
+    // or the check beside the clause would refuse it and prove nothing.
+    assert.equal(37 + channelLength + 0 + 0 + payloadLength, totalBytes, "the crafted sum must match");
+    return bytes;
+  };
+  const cases: readonly (readonly [string, Uint8Array])[] = [
+    ["a maximal channel length cancelled by -65535, summing to 37", crafted(0xffff, -0xffff, 37)],
+    ["a channel length of 1 cancelled by -1, summing to 37", crafted(1, -1, 37)],
+    ["a channel length of 2 cancelled by -1, summing to 38", crafted(2, -1, 38)],
+  ];
+  for (const [label, bytes] of cases) {
+    assert.throws(
+      () => decodeRealtimeFrame(bytes),
+      (error: Error) => error.message === "Realtime frame length is invalid.",
+      label,
+    );
+  }
+});
+
+test("decode reads exactly the viewed bytes of an offset view, not the buffer behind it", () => {
+  const good = encodeRealtimeFrame(sample({ payload: Uint8Array.from([9, 8, 7]) }));
+  const pool = new Uint8Array(good.byteLength + 64).fill(0xa5);
+  pool.set(good, 17);
+  const view = pool.subarray(17, 17 + good.byteLength);
+  assert.deepEqual(decodeRealtimeFrame(view).payload, Uint8Array.from([9, 8, 7]));
+  assert.equal(decodeRealtimeFrame(view).channelId, "aetheria.zone-1");
+  // And the decoded payload does not alias the frame it came from.
+  const decoded = decodeRealtimeFrame(good);
+  good[good.byteLength - 1] = 0;
+  assert.deepEqual(decoded.payload, Uint8Array.from([9, 8, 7]));
+});
+
+// The `Uint8Array` case above passes with a plain `bytes.slice(...)`; this one
+// does not. Node's `Buffer` overrides `slice` with an alias of `subarray`, and a
+// `Buffer` is what a socket read hands a Node caller, so the aliasing bug this
+// pins is the one that would actually reach a consumer.
+test("the decoded payload copies out of a Node Buffer too, which overrides slice", () => {
+  const frame = Buffer.from(encodeRealtimeFrame(sample({ payload: Uint8Array.from([9, 8, 7]) })));
+  const decoded = decodeRealtimeFrame(frame);
+  frame[frame.byteLength - 1] = 0;
+  assert.deepEqual(decoded.payload, Uint8Array.from([9, 8, 7]), "payload unchanged by a later write to the frame");
+  assert.equal(Buffer.isBuffer(decoded.payload), false, "the copy is a plain Uint8Array, not a Buffer");
+  assert.notEqual(decoded.payload.buffer, frame.buffer, "the copy has its own backing store");
+  // The three identities need no such check: `TextDecoder` returns strings, which
+  // hold no reference to the bytes they were decoded from.
+  assert.equal(decoded.channelId, "aetheria.zone-1");
+});
+
+test("the codec touches no socket: no node: import in the source", () => {
+  const source = readFileSync(join(__dirname, "..", "..", "src", "realtime-wire.ts"), "utf8");
+  assert.doesNotMatch(source, /from "node:|require\("node:/);
+});

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

@@ -55,19 +55,19 @@ from .transport import (
 INTEROP_DOCUMENT_TYPE = "cultnet.interop-note"
 INTEROP_SCHEMA_VERSION = "cultnet.interop_note.v0"
 INTEROP_MUTATION_INTENT_DOCUMENT_TYPE = "cultnet.interop-note-mutation-intent"
-INTEROP_MUTATION_INTENT_SCHEMA_ID = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-intent.schema.json"
+INTEROP_MUTATION_INTENT_SCHEMA_ID = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-intent.schema.json"
 INTEROP_MUTATION_INTENT_SCHEMA_VERSION = "cultnet.interop_note_mutation_intent.v0"
 INTEROP_MUTATION_RECEIPT_DOCUMENT_TYPE = "cultnet.interop-note-mutation-receipt"
-INTEROP_MUTATION_RECEIPT_SCHEMA_ID = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-receipt.schema.json"
+INTEROP_MUTATION_RECEIPT_SCHEMA_ID = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-receipt.schema.json"
 INTEROP_MUTATION_RECEIPT_SCHEMA_VERSION = "cultnet.interop_note_mutation_receipt.v0"
 INTEROP_FIRE_COMMAND_DOCUMENT_TYPE = "cultnet.interop-fire-weapon-command"
-INTEROP_FIRE_COMMAND_SCHEMA_ID = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-command.schema.json"
+INTEROP_FIRE_COMMAND_SCHEMA_ID = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-command.schema.json"
 INTEROP_FIRE_COMMAND_SCHEMA_VERSION = "cultnet.interop_fire_weapon_command.v0"
 INTEROP_FIRE_RECEIPT_DOCUMENT_TYPE = "cultnet.interop-fire-weapon-receipt"
-INTEROP_FIRE_RECEIPT_SCHEMA_ID = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-receipt.schema.json"
+INTEROP_FIRE_RECEIPT_SCHEMA_ID = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-receipt.schema.json"
 INTEROP_FIRE_RECEIPT_SCHEMA_VERSION = "cultnet.interop_fire_weapon_receipt.v0"
 WITNESS_ARTIFACT_BUNDLE_DOCUMENT_TYPE = "cultnet.witness_artifact_bundle"
-WITNESS_ARTIFACT_BUNDLE_SCHEMA_ID = "https://github.com/GameCult/cultnet-ts/contracts/cultnet.witness-artifact-bundle.schema.json"
+WITNESS_ARTIFACT_BUNDLE_SCHEMA_ID = "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.witness-artifact-bundle.schema.json"
 WITNESS_ARTIFACT_BUNDLE_SCHEMA_VERSION = "cultnet.witness_artifact_bundle.v0"
 SIMULATION_FACT_SCHEMA_ID = simulation_fact_document.catalog_entry().schema_id
 DISCOVERY_PROBE_SCHEMA_VERSION = "cultnet.discovery_probe.v0"

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

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 from typing import Any
 
 INTEROP_WIRE_CONTRACT = "cultnet.schema.v0"
-CULTNET_SCHEMA_BASE = "https://github.com/GameCult/cultnet-ts/contracts"
+CULTNET_SCHEMA_BASE = "https://github.com/GameCult/CultLib/contracts/cultnet"
 VERSE_CATALOG_REQUEST = "cultmesh.verse_catalog_request.v0"
 PEER_EXCHANGE_REQUEST = "cultmesh.peer_exchange_request.v0"
 TRANSPORT_PROFILE_SCHEMA_VERSION = "cultnet.transport_profile.v0"

packages/cultnet-py/tests/test_cultnet.py

@@ -1677,7 +1677,7 @@ class CultNetTests(unittest.TestCase):
         self.assertIn("operations", mutation_contract["properties"])
         self.assertEqual(
             hello_schema["properties"]["transportProfiles"]["items"]["$ref"],
-            "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
+            "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json",
         )
 
         consensus_schema = json.loads(by_version["cultnet.simulation_consensus_candidate.v0"]["schemaJson"])
@@ -1686,7 +1686,7 @@ class CultNetTests(unittest.TestCase):
 
     def test_cultnet_schema_catalog_applies_filters_and_responses(self) -> None:
         catalog = wire_message_schema_catalog(include_schema_json=True)
-        descriptor = catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json")
+        descriptor = catalog.get("https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.document-put-raw.schema.json")
         self.assertIsNotNone(descriptor)
         assert descriptor is not None
         self.assertEqual(descriptor.kind, "wire_message")
@@ -1902,7 +1902,7 @@ class CultNetTests(unittest.TestCase):
             runtime_kind="python",
             display_name="Python Interop Test",
             agent_id="python-interop-test-agent",
-            schema_path=str(Path("packages/cultnet-ts/integration/contracts/cultnet.interop-note.schema.json")),
+            schema_path=str(Path("contracts/cultnet/interop/cultnet.interop-note.schema.json")),
         )
         binding = state.bindings["note"]
         logged_value = {

packages/cultnet-rs/contracts/cultnet.document-mutation-contract.schema.json

@@ -1,40 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-mutation-contract.schema.json",
-  "title": "CultNet Document Mutation Contract",
-  "type": "object",
-  "required": [
-    "documentType",
-    "operations",
-    "authority"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "documentType": { "type": "string", "minLength": 1 },
-    "payloadSchemaVersion": { "type": "string", "minLength": 1 },
-    "operations": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "string",
-        "enum": ["snapshot", "documentPut", "documentDelete", "intentSubmit", "receiptWatch"]
-      }
-    },
-    "authority": {
-      "type": "string",
-      "enum": ["readOnly", "localUser", "coordinator", "runtime", "denied"]
-    },
-    "intentDocumentTypes": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "receiptDocumentTypes": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "notes": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.document-put-raw.schema.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json",
-  "title": "CultNet Raw Document Put Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId",
-    "document"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.document_put_raw.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "document": {
-      "$ref": "./cultnet.raw-document-record.schema.json"
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.document-put.schema.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put.schema.json",
-  "title": "CultNet Document Put Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId",
-    "document"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.document_put.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "document": {
-      "$ref": "./cultnet.document-record.schema.json"
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.document-record.schema.json

@@ -1,26 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-record.schema.json",
-  "title": "CultNet Document Record",
-  "type": "object",
-  "required": [
-    "schemaId",
-    "recordKey",
-    "storedAt",
-    "payload"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaId": { "type": "string", "minLength": 1 },
-    "recordKey": { "type": "string", "minLength": 1 },
-    "storedAt": { "type": "string", "minLength": 1 },
-    "payload": {},
-    "sourceRuntimeId": { "type": "string", "minLength": 1 },
-    "sourceAgentId": { "type": "string", "minLength": 1 },
-    "sourceRole": { "type": "string", "minLength": 1 },
-    "tags": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.error.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.error.schema.json",
-  "title": "CultNet Error Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "error"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.error.v0" },
-    "error": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.hello.schema.json

@@ -1,41 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.hello.schema.json",
-  "title": "CultNet Hello Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "runtimeId",
-    "runtimeKind"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.hello.v0" },
-    "runtimeId": { "type": "string", "minLength": 1 },
-    "runtimeKind": { "type": "string", "minLength": 1 },
-    "agentId": { "type": "string", "minLength": 1 },
-    "role": { "type": "string", "minLength": 1 },
-    "displayName": { "type": "string", "minLength": 1 },
-    "supportedDocumentTypes": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "supportedMutationContracts": {
-      "type": "array",
-      "items": {
-        "$ref": "./cultnet.document-mutation-contract.schema.json"
-      }
-    },
-    "supportedMessageVersions": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "transportProfiles": {
-      "type": "array",
-      "items": {
-        "$ref": "./cultnet.transport-profile.schema.json"
-      }
-    },
-    "supportsSchemaCatalog": { "type": "boolean" }
-  }
-}

packages/cultnet-rs/contracts/cultnet.login.schema.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login.schema.json",
-  "title": "CultNet Login Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "nonce",
-    "auth",
-    "password"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.login.v0" },
-    "nonce": { "type": "string", "minLength": 1 },
-    "auth": { "type": "string", "minLength": 1 },
-    "password": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.raw-document-record.schema.json

@@ -1,32 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.raw-document-record.schema.json",
-  "title": "CultNet Raw Document Record",
-  "type": "object",
-  "required": [
-    "schemaId",
-    "recordKey",
-    "storedAt",
-    "payloadEncoding",
-    "payload"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaId": { "type": "string", "minLength": 1 },
-    "recordKey": { "type": "string", "minLength": 1 },
-    "storedAt": { "type": "string", "minLength": 1 },
-    "payloadEncoding": { "const": "messagepack" },
-    "payload": {
-      "type": "string",
-      "contentEncoding": "base64",
-      "x-cult-runtime-type": "bytes"
-    },
-    "sourceRuntimeId": { "type": "string", "minLength": 1 },
-    "sourceAgentId": { "type": "string", "minLength": 1 },
-    "sourceRole": { "type": "string", "minLength": 1 },
-    "tags": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.register.schema.json

@@ -1,21 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.register.schema.json",
-  "title": "CultNet Register Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "nonce",
-    "email",
-    "password",
-    "name"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.register.v0" },
-    "nonce": { "type": "string", "minLength": 1 },
-    "email": { "type": "string", "minLength": 1 },
-    "password": { "type": "string", "minLength": 1 },
-    "name": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.sample-change-name.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-change-name.schema.json",
-  "title": "CultNet Sample Change Name Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "name"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.sample.change_name.v0" },
-    "name": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.sample-chat.schema.json

@@ -1,15 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-chat.schema.json",
-  "title": "CultNet Sample Chat Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "text"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.sample.chat.v0" },
-    "text": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.schema-catalog-response.schema.json

@@ -1,22 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-response.schema.json",
-  "title": "CultNet Schema Catalog Response Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId",
-    "schemas"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.schema_catalog_response.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "schemas": {
-      "type": "array",
-      "items": {
-        "$ref": "./cultnet.schema-descriptor.schema.json"
-      }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.schema-descriptor.schema.json

@@ -1,39 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-descriptor.schema.json",
-  "title": "CultNet Schema Descriptor",
-  "type": "object",
-  "required": [
-    "schemaId",
-    "kind",
-    "wireContracts",
-    "contentHash"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaId": { "type": "string", "minLength": 1 },
-    "kind": {
-      "type": "string",
-      "enum": [
-        "wire_message",
-        "document_payload",
-        "shared_contract"
-      ]
-    },
-    "schemaVersion": { "type": "string", "minLength": 1 },
-    "documentType": { "type": "string", "minLength": 1 },
-    "title": { "type": "string", "minLength": 1 },
-    "wireContracts": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": [
-          "cultnet.schema.v0",
-          "gamecult.networking.v0"
-        ]
-      }
-    },
-    "contentHash": { "type": "string", "minLength": 1 },
-    "schemaJson": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/contracts/cultnet.shard-catalog-request.schema.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "cultnet.shard_catalog_request.v0",
-  "type": "object",
-  "required": ["schemaVersion", "messageId"],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.shard_catalog_request.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "schemaIds": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "recordKeys": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.snapshot-request.schema.json

@@ -1,23 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-request.schema.json",
-  "title": "CultNet Snapshot Request Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.snapshot_request.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "schemaIds": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    },
-    "recordKeys": {
-      "type": "array",
-      "items": { "type": "string", "minLength": 1 }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.snapshot-response.schema.json

@@ -1,22 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response.schema.json",
-  "title": "CultNet Snapshot Response Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId",
-    "documents"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.snapshot_response.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "documents": {
-      "type": "array",
-      "items": {
-        "$ref": "./cultnet.document-record.schema.json"
-      }
-    }
-  }
-}

packages/cultnet-rs/contracts/cultnet.verify.schema.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.verify.schema.json",
-  "title": "CultNet Verify Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "nonce",
-    "session"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.verify.v0" },
-    "nonce": { "type": "string", "minLength": 1 },
-    "session": { "type": "string", "minLength": 1 }
-  }
-}

packages/cultnet-rs/examples/cultnet_interop_peer.rs

@@ -55,16 +55,16 @@ use std::time::Instant;
 const INTEROP_DOCUMENT_TYPE: &str = "cultnet.interop-note";
 const INTEROP_SCHEMA_VERSION: &str = "cultnet.interop_note.v0";
 const MUTATION_INTENT_TYPE: &str = "cultnet.interop-note-mutation-intent";
-const MUTATION_INTENT_SCHEMA_ID: &str = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-intent.schema.json";
+const MUTATION_INTENT_SCHEMA_ID: &str = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-intent.schema.json";
 const MUTATION_INTENT_SCHEMA_VERSION: &str = "cultnet.interop_note_mutation_intent.v0";
 const MUTATION_RECEIPT_TYPE: &str = "cultnet.interop-note-mutation-receipt";
-const MUTATION_RECEIPT_SCHEMA_ID: &str = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-note-mutation-receipt.schema.json";
+const MUTATION_RECEIPT_SCHEMA_ID: &str = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-note-mutation-receipt.schema.json";
 const MUTATION_RECEIPT_SCHEMA_VERSION: &str = "cultnet.interop_note_mutation_receipt.v0";
 const FIRE_COMMAND_TYPE: &str = "cultnet.interop-fire-weapon-command";
-const FIRE_COMMAND_SCHEMA_ID: &str = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-command.schema.json";
+const FIRE_COMMAND_SCHEMA_ID: &str = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-command.schema.json";
 const FIRE_COMMAND_SCHEMA_VERSION: &str = "cultnet.interop_fire_weapon_command.v0";
 const FIRE_RECEIPT_TYPE: &str = "cultnet.interop-fire-weapon-receipt";
-const FIRE_RECEIPT_SCHEMA_ID: &str = "https://github.com/GameCult/cultnet-ts/integration/contracts/cultnet.interop-fire-weapon-receipt.schema.json";
+const FIRE_RECEIPT_SCHEMA_ID: &str = "https://github.com/GameCult/CultLib/contracts/cultnet/interop/cultnet.interop-fire-weapon-receipt.schema.json";
 const FIRE_RECEIPT_SCHEMA_VERSION: &str = "cultnet.interop_fire_weapon_receipt.v0";
 const DISCOVERY_ANNOUNCE_SCHEMA_VERSION: &str = "cultnet.discovery_announce.v0";
 const RUDP_INTEROP_CONNECTION_ID: u32 = 0x43554C54;

packages/cultnet-rs/src/schema_discovery.rs

@@ -194,28 +194,28 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
 
     for registration in [
         schema_registration(
-            include_str!("../contracts/cultnet.hello.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.hello.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.hello.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.document-mutation-contract.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.document-mutation-contract.schema.json"),
             CultNetSchemaKind::SharedContract,
             vec![CultNetWireContract::CultNetSchemaV0],
             None,
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.transport-profile.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.transport-profile.schema.json"),
             CultNetSchemaKind::SharedContract,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.transport_profile.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.login.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.login.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -225,7 +225,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.register.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.register.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -235,7 +235,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.verify.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.verify.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -245,7 +245,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.login-success.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.login-success.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -255,7 +255,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.error.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.error.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -265,7 +265,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.sample-change-name.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.sample-change-name.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -275,7 +275,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.sample-chat.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.sample-chat.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -285,56 +285,56 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.document-put.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.document-put.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.document_put.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.document-delete.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.document-delete.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.document_delete.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.raw-document-record.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.raw-document-record.schema.json"),
             CultNetSchemaKind::SharedContract,
             vec![CultNetWireContract::CultNetSchemaV0],
             None,
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.document-put-raw.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.document-put-raw.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.document_put_raw.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.snapshot-request.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.snapshot-request.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.snapshot_request.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.snapshot-response.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.snapshot-response.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.snapshot_response.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.snapshot-response-raw.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.snapshot-response-raw.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.snapshot_response_raw.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.schema-catalog-request.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.schema-catalog-request.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -344,7 +344,7 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.schema-catalog-response.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.schema-catalog-response.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![
                 CultNetWireContract::CultNetSchemaV0,
@@ -354,21 +354,21 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.shard-catalog-request.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.shard-catalog-request.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.shard_catalog_request.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/cultnet.shard-catalog-response.schema.json"),
+            include_str!("../../../contracts/cultnet/cultnet.shard-catalog-response.schema.json"),
             CultNetSchemaKind::WireMessage,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("cultnet.shard_catalog_response.v0"),
             None,
         )?,
         schema_registration(
-            include_str!("../contracts/ghostlight.agent-state.schema.json"),
+            include_str!("../../../contracts/cultnet/ghostlight.agent-state.schema.json"),
             CultNetSchemaKind::DocumentPayload,
             vec![CultNetWireContract::CultNetSchemaV0],
             Some("ghostlight.agent_state.v0"),

packages/cultnet-rs/tests/cultnet.rs

@@ -1759,7 +1759,7 @@ fn cultmesh_facade_exposes_schema_registry_and_shard_catalog_owners() -> Result<
     });
     assert!(shared_contracts.iter().any(|schema| {
         schema.schema_id
-            == "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json"
+            == "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json"
             && schema.schema_version.as_deref() == Some("cultnet.transport_profile.v0")
     }));
 
@@ -2285,7 +2285,7 @@ fn builtin_schema_registry_advertises_canonical_ghostlight_schema_without_inline
     assert_eq!(transport_profile.kind, CultNetSchemaKind::SharedContract);
     assert_eq!(
         transport_profile.schema_id,
-        "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json"
+        "https://github.com/GameCult/CultLib/contracts/cultnet/cultnet.transport-profile.schema.json"
     );
     assert_eq!(
         transport_profile.wire_contracts,

packages/cultnet-ts/.gitignore

@@ -2,3 +2,6 @@ node_modules/
 dist/
 dist-test/
 *.tgz
+# Mirrored from CultLib/contracts/cultnet by tools/generate-swarm-contracts.mjs
+# (REC-032). Not tracked: CultLib/contracts/cultnet is the only source.
+contracts/

packages/cultnet-ts/contracts/cultnet.document-delete.schema.json

@@ -1,19 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-delete.schema.json",
-  "title": "CultNet Document Delete Message",
-  "type": "object",
-  "required": [
-    "schemaVersion",
-    "messageId",
-    "schemaId",
-    "recordKey"
-  ],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": "cultnet.document_delete.v0" },
-    "messageId": { "type": "string", "minLength": 1 },
-    "schemaId": { "type": "string", "minLength": 1 },
-    "recordKey": { "type": "string", "minLength": 1 }
-  }
-}