CultMeshRudpDocumentPut discriminates a decoded document from an undecoded payload; the store read's schema-matched find is pinned

The put is a union on `decoded`: true carries the document read through the registry's definition, false carries the
opaque DocumentPayload, so the owner read on the undecoded branch compiles without a cast (compile fixture in
payload-type.test.ts) and the three test casts are gone. A store holding a foreign parsing record, a matched record that
does not parse and a matched record that parses must return the last, which kills the survivors on the schema-matched
second find in resolveCultMeshStoreDocumentRecord.

All commits build.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-11 20:37:29 +02:00
commit a6478a9cab
4 changed files with 66 additions and 18 deletions

View file

@ -8,6 +8,7 @@ import {
type CacheBackingStore,
type CultCacheEnvelope,
type CultCacheDocumentValue,
type DocumentPayload,
decodeDocumentPayload,
} from "@gamecult/cultcache-ts";
import {
@ -4104,16 +4105,16 @@ export interface CultMeshPeerCard {
authorityLeaseId?: string;
}
export interface CultMeshRudpDocumentPut {
/**
* A document put as `onDocumentPutRaw` receives it. `decoded` says which read the payload is ready for: `true` when the
* registry held a definition for `schemaId` and `payload` is the document read through it; `false` when it did not, and
* `payload` is the opaque `DocumentPayload`, untouched, for a handler that holds the definition itself to read with
* `decodeDocumentPayload`. Narrowing on `decoded` needs no cast in either branch.
*/
export type CultMeshRudpDocumentPut = {
schemaId: string;
recordKey: string;
storedAt: string;
/**
* The document, read through the definition `documents` holds for `schemaId`. A schema the registry has no definition
* for is not decoded at all: the payload arrives untouched as the opaque `DocumentPayload`, for a handler that holds
* the definition itself to read with `decodeDocumentPayload`.
*/
payload: unknown;
sourceRuntimeId: string | null;
sourceAgentId: string | null;
sourceRole: string | null;
@ -4123,7 +4124,10 @@ export interface CultMeshRudpDocumentPut {
family: string;
port: number;
};
}
} & (
| { readonly decoded: true; readonly payload: unknown }
| { readonly decoded: false; readonly payload: DocumentPayload }
);
export interface CultMeshRudpDocumentReceipt<TDefinition extends AnyCultCacheDocumentDefinition = AnyCultCacheDocumentDefinition> {
binding: CultNetDocumentBinding<TDefinition>;
@ -6426,12 +6430,14 @@ function normalizeRudpDocumentPut(
schemaId: document.schemaId,
recordKey: document.recordKey,
storedAt: document.storedAt ?? new Date().toISOString(),
payload: definition ? decodeDocumentPayload(definition, document.payload) : document.payload,
sourceRuntimeId: document.sourceRuntimeId ?? null,
sourceAgentId: document.sourceAgentId ?? null,
sourceRole: document.sourceRole ?? null,
tags: Array.isArray(document.tags) ? document.tags : [],
remote,
...(definition
? { decoded: true, payload: decodeDocumentPayload(definition, document.payload) }
: { decoded: false, payload: document.payload }),
};
}

View file

@ -10,14 +10,14 @@ import {
defineDocumentType,
documentPayloadBytes,
encodeDocumentPayload,
type DocumentPayload,
} from "@gamecult/cultcache-ts";
import type { CacheBackingStore, CultCacheEnvelope } from "@gamecult/cultcache-ts";
import {
CultNetDocumentRegistry,
defineCultNetDocumentBinding,
type CultNetPeer,
} from "cultnet-ts";
import { CultMesh, cultMeshDocumentFromSingleFile } from "../src/index";
import { CultMesh, cultMeshDocumentFromSingleFile, cultMeshDocumentFromStore, type CultMeshRudpDocumentPut } from "../src/index";
// A document written in the reference's positional shape, and a plain map document beside it. Every mesh reader of a
// payload reads it the way the cache does, so both read through the mesh.
@ -156,12 +156,12 @@ test("a RUDP put naming a schema the server has no definition for reaches the ha
const strayBinding = defineCultNetDocumentBinding({ definition: stray });
const known = defineCultNetDocumentBinding({ definition: plainNote });
const errors: Error[] = [];
const puts: Array<{ schemaId: string; payload: unknown }> = [];
const puts: CultMeshRudpDocumentPut[] = [];
const server = CultMesh.createRudpDocumentServer("cultmesh-ts-unregistered-server", connectionId, {
documents: new CultNetDocumentRegistry([known]),
bindHost: "127.0.0.1", bindPort: 0, resendDelayMs: 25, resendPollMs: 5,
onError: (error) => errors.push(error),
onDocumentPutRaw: async (document) => { puts.push({ schemaId: document.schemaId, payload: document.payload }); },
onDocumentPutRaw: async (document) => { puts.push(document); },
});
let peer: CultNetPeer | undefined;
try {
@ -176,7 +176,9 @@ test("a RUDP put naming a schema the server has no definition for reaches the ha
assert.equal(puts.length, 1);
// Not read as plain msgpack: the bytes are the codec's slot record, handed over opaque, and the definition that reads
// them is the handler's to hold.
const payload = puts[0]!.payload as DocumentPayload;
const put = puts[0]!;
assert.ok(!put.decoded, "the registry holds no definition for this schema");
const payload = put.payload;
assert.equal(Buffer.from(documentPayloadBytes(payload)).toString("hex"), "91a16b", "a one-slot codec record, not a map");
assert.deepEqual(Buffer.from(documentPayloadBytes(payload)), Buffer.from(documentPayloadBytes(encodeDocumentPayload(stray, { noteId: "k" }))));
assert.deepEqual(decodeDocumentPayload(stray, payload), { noteId: "k" });
@ -185,3 +187,24 @@ test("a RUDP put naming a schema the server has no definition for reaches the ha
server.close();
}
});
test("a store read takes the record the catalog matches to the schema and the definition parses, not the first that merely parses", async () => {
const target = defineDocumentType({ type: "cultmesh.pick", schemaId: "cultmesh.pick.v1", schema: z.object({ n: z.number() }) });
const lenient = defineDocumentType({ type: "cultmesh.pick", schemaId: "cultmesh.pick.v1", schema: { parse: (value: unknown) => value } });
const entry = (schemaId: string, compatibleSchemaIds?: readonly string[]) => ({
schemaId, schemaName: schemaId, schemaVersion: `${schemaId}.v1`, contentHash: "h", canonicalSchemaJson: "{}", compatibleSchemaIds,
});
const envelope = (key: string, schemaId: string, value: unknown, compatibleSchemaIds?: readonly string[]): CultCacheEnvelope => ({
key, type: "cultmesh.pick", schemaId, storedAt: "2026-10-11T00:00:00.000Z",
payload: encodeDocumentPayload(lenient, value), catalogEntry: entry(schemaId, compatibleSchemaIds),
});
// None carries the definition's own schema id, so the exact-id find misses. The first parses and is foreign; the
// second is matched by the catalog and does not parse; the third is matched and parses.
const records = [
envelope("a", "foreign.v1", { n: 1 }),
envelope("b", "alias-bad.v1", { n: "x" }, ["cultmesh.pick.v1"]),
envelope("c", "alias-good.v1", { n: 2 }, ["cultmesh.pick.v1"]),
];
const store: CacheBackingStore = { pullAll: async () => records, push: async () => undefined, delete: async () => undefined };
assert.deepEqual(await cultMeshDocumentFromStore(store, target).latest(), { n: 2 });
});

View file

@ -6,7 +6,7 @@ import test from "node:test";
import assert from "node:assert/strict";
import { decodeWireValue, encodeWireValue } from "cultnet-ts/wire";
import { z } from "zod";
import { defineDocumentType, documentPayloadBytes, documentPayloadFromBytes, type DocumentPayload } from "@gamecult/cultcache-ts";
import { defineDocumentType, documentPayloadBytes, documentPayloadFromBytes } from "@gamecult/cultcache-ts";
import {
CultNetDocumentRegistry,
CultNetPeer,
@ -2782,7 +2782,8 @@ test("CultMesh TS RUDP document server accepts raw document puts from multiple p
maxPendingReliablePackets: 16,
onDocumentPutRaw: (document) => {
// The registry holds no definition, so the payload arrives untouched and is read here by name.
received.push(`${document.sourceRuntimeId}:${document.recordKey}:${decodeWireValue(documentPayloadBytes(document.payload as DocumentPayload))}`);
if (document.decoded) throw new Error("the registry holds no definition, so the put must arrive undecoded");
received.push(`${document.sourceRuntimeId}:${document.recordKey}:${decodeWireValue(documentPayloadBytes(document.payload))}`);
},
},
);
@ -2868,10 +2869,11 @@ test("CultMesh TS publishes one registered document to a RUDP catalog", async ()
maxFragmentBytes: 1024,
maxPendingReliablePackets: 16,
onDocumentPutRaw: (document) => {
if (document.decoded) throw new Error("the registry holds no definition, so the put must arrive undecoded");
received = {
schemaId: document.schemaId,
recordKey: document.recordKey,
payload: decodeWireValue(documentPayloadBytes(document.payload as DocumentPayload)),
payload: decodeWireValue(documentPayloadBytes(document.payload)),
sourceRuntimeId: document.sourceRuntimeId,
};
},

View file

@ -1,10 +1,17 @@
import assert from "node:assert/strict";
import test from "node:test";
import { documentPayloadBytes, documentPayloadFromBytes, type DocumentPayload } from "@gamecult/cultcache-ts";
import {
decodeDocumentPayload,
defineDocumentType,
documentPayloadBytes,
documentPayloadFromBytes,
type DocumentPayload,
} from "@gamecult/cultcache-ts";
import { decodeWireValue } from "cultnet-ts/wire";
import type { CultNetRawDocumentRecord } from "cultnet-ts";
import type { CultMeshRudpDocumentPut } from "../src/index";
import { decodeRealtimeFrame, encodeRealtimeFrame, type CultMeshRealtimeFrame } from "../src/realtime-wire";
// The rule: a document payload is read only through its definition. Every payload this package touches (a CultNet
@ -22,6 +29,16 @@ export function refusedReaders(record: CultNetRawDocumentRecord, frame: CultMesh
void [bytes, forged];
}
// The one seam where a DocumentPayload reaches a consumer: a put for a schema the registry holds no definition for. The
// owner read of the undecoded branch needs no cast, and the decoded branch is not a DocumentPayload.
const noteDefinition = defineDocumentType({ type: "t.note", schemaId: "t.note.v0", schema: { parse: (value: unknown) => value } });
export function readPut(put: CultMeshRudpDocumentPut): unknown {
if (!put.decoded) return decodeDocumentPayload(noteDefinition, put.payload);
// @ts-expect-error a decoded put's payload is the document, not a DocumentPayload
decodeDocumentPayload(noteDefinition, put.payload);
return put.payload;
}
test("a realtime frame carries its payload as the same bytes it was given by name", () => {
const bytes = Uint8Array.from([1, 2, 3]);
const frame: CultMeshRealtimeFrame = {