diff --git a/packages/cultmesh-ts/src/index.ts b/packages/cultmesh-ts/src/index.ts index b6147ce2..810e6919 100644 --- a/packages/cultmesh-ts/src/index.ts +++ b/packages/cultmesh-ts/src/index.ts @@ -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 { binding: CultNetDocumentBinding; @@ -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 }), }; } diff --git a/packages/cultmesh-ts/test/codec-documents.test.ts b/packages/cultmesh-ts/test/codec-documents.test.ts index 3a2fd90c..eec87133 100644 --- a/packages/cultmesh-ts/test/codec-documents.test.ts +++ b/packages/cultmesh-ts/test/codec-documents.test.ts @@ -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 }); +}); diff --git a/packages/cultmesh-ts/test/cultmesh.test.ts b/packages/cultmesh-ts/test/cultmesh.test.ts index 52e6760f..611492a3 100644 --- a/packages/cultmesh-ts/test/cultmesh.test.ts +++ b/packages/cultmesh-ts/test/cultmesh.test.ts @@ -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, }; }, diff --git a/packages/cultmesh-ts/test/payload-type.test.ts b/packages/cultmesh-ts/test/payload-type.test.ts index 21ee2787..cdba3505 100644 --- a/packages/cultmesh-ts/test/payload-type.test.ts +++ b/packages/cultmesh-ts/test/payload-type.test.ts @@ -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 = {