From cb6301e1cf7d6904cc15d53654b22b62e0fed443 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 27 Jun 2026 16:24:08 +0100 Subject: [PATCH] Add TS document prediction submissions --- packages/cultmesh-ts/README.md | 20 ++++++++ packages/cultmesh-ts/src/index.ts | 52 +++++++++++++++++++ packages/cultmesh-ts/test/cultmesh.test.ts | 58 ++++++++++++++++++++++ 3 files changed, 130 insertions(+) diff --git a/packages/cultmesh-ts/README.md b/packages/cultmesh-ts/README.md index 9a210f33..b3ebbf8a 100644 --- a/packages/cultmesh-ts/README.md +++ b/packages/cultmesh-ts/README.md @@ -67,6 +67,26 @@ const stop = objects.watch( ); ``` +Typed document handles use the same shape for local cache reads, network +snapshots, replacement, and client prediction. Authority-specific code plugs in +the submitter once; gameplay callers keep using the document: + +```ts +const input = CultMesh.document( + "input:pilot-a:thermal", + pilotInputDocument, + async (context) => readInput(context), + { + routeHint: CultMesh.routeHint("network", "Starbridge Verse"), + watchDocument: watchInput, + submitPrediction: async (context, value) => submitPredictedInput(context, value), + }, +); + +await input.submitPrediction("pilot-a", predictedInput); +const stop = input.watch("pilot-a", latest => reconcileInput(latest)); +``` + State pointers are the same kind of managed surface for UI and tools. They can advertise source documents, inherit a Verse route when bound, and resolve through that Verse without caller-side context plumbing: diff --git a/packages/cultmesh-ts/src/index.ts b/packages/cultmesh-ts/src/index.ts index 31cb0e07..1e8b6477 100644 --- a/packages/cultmesh-ts/src/index.ts +++ b/packages/cultmesh-ts/src/index.ts @@ -111,6 +111,11 @@ export type CultMeshDocumentReplacer = ( value: TDocument, ) => Promise; +export type CultMeshDocumentPredictionSubmitter = ( + context: CultMeshQueryContext, + value: TDocument, +) => Promise; + export type CultMeshCollectionSnapshot = readonly TDocument[]; export type CultMeshCollectionChangeKind = "added" | "updated" | "removed" | "reset"; @@ -724,6 +729,7 @@ export class CultMeshDocumentHandle { routeHint?: CultMeshRouteHint; watchDocument?: CultMeshDocumentWatcher; replaceDocument?: CultMeshDocumentReplacer; + submitPrediction?: CultMeshDocumentPredictionSubmitter; } = {}, ) { requireNonEmpty(documentId, "documentId"); @@ -732,15 +738,23 @@ export class CultMeshDocumentHandle { this.routeHint = options.routeHint ?? cultMeshRouteHint(); this.watchDocument = options.watchDocument; this.replaceDocument = options.replaceDocument; + this.submitPredictionDocument = options.submitPrediction; } private readonly watchDocument: CultMeshDocumentWatcher | undefined; private readonly replaceDocument: CultMeshDocumentReplacer | undefined; + private readonly submitPredictionDocument: + | CultMeshDocumentPredictionSubmitter + | undefined; public get canReplace(): boolean { return this.replaceDocument !== undefined; } + public get canSubmitPrediction(): boolean { + return this.submitPredictionDocument !== undefined; + } + public latest(context: CultMeshQueryContext | string = "local"): Promise { return this.snapshotDocument( this.resolveContext(typeof context === "string" ? cultMeshQueryContext(context) : context), @@ -802,6 +816,31 @@ export class CultMeshDocumentHandle { return this.replaceDocument(this.resolveContext(context), value); } + public submitPrediction(value: TDocument): Promise; + public submitPrediction(context: CultMeshQueryContext | string, value: TDocument): Promise; + public submitPrediction( + contextOrValue: CultMeshQueryContext | string | TDocument, + maybeValue?: TDocument, + ): Promise { + if (!this.submitPredictionDocument) { + throw new Error(`Document '${this.documentId}' does not support prediction submission.`); + } + + const hasContext = + typeof contextOrValue === "string" || isCultMeshQueryContext(contextOrValue); + const context = hasContext + ? typeof contextOrValue === "string" + ? cultMeshQueryContext(contextOrValue) + : contextOrValue as CultMeshQueryContext + : cultMeshQueryContext("local"); + const value = hasContext ? maybeValue : contextOrValue as TDocument; + if (value === undefined) { + throw new Error(`Document '${this.documentId}' requires a prediction value.`); + } + + return this.submitPredictionDocument(this.resolveContext(context), value); + } + public asSchemaAlias( schema: CultMeshDocumentSchemaDescriptor, options: { parse?: (value: unknown) => TAlias } = {}, @@ -827,6 +866,9 @@ export class CultMeshDocumentHandle { replaceDocument: this.replaceDocument ? (context, value) => this.replace(context, value as unknown as TDocument) : undefined, + submitPrediction: this.submitPredictionDocument + ? (context, value) => this.submitPrediction(context, value as unknown as TDocument) + : undefined, }, ); } @@ -864,6 +906,10 @@ export class CultMeshBoundDocumentHandle { return this.document.canReplace; } + public get canSubmitPrediction(): boolean { + return this.document.canSubmitPrediction; + } + public latest(): Promise { return this.document.latest(cultMeshQueryContextFromVerse(this.verse)); } @@ -880,6 +926,10 @@ export class CultMeshBoundDocumentHandle { return this.document.replace(cultMeshQueryContextFromVerse(this.verse), value); } + public submitPrediction(value: TDocument): Promise { + return this.document.submitPrediction(cultMeshQueryContextFromVerse(this.verse), value); + } + public asSchemaAlias( schema: CultMeshDocumentSchemaDescriptor, options: { parse?: (value: unknown) => TAlias } = {}, @@ -1794,6 +1844,7 @@ export function cultMeshDocument( routeHint?: CultMeshRouteHint; watchDocument?: CultMeshDocumentWatcher; replaceDocument?: CultMeshDocumentReplacer; + submitPrediction?: CultMeshDocumentPredictionSubmitter; } = {}, ): CultMeshDocumentHandle { return new CultMeshDocumentHandle(documentId, schema, snapshotDocument, options); @@ -3592,6 +3643,7 @@ export class CultMesh { routeHint?: CultMeshRouteHint; watchDocument?: CultMeshDocumentWatcher; replaceDocument?: CultMeshDocumentReplacer; + submitPrediction?: CultMeshDocumentPredictionSubmitter; } = {}, ): CultMeshDocumentHandle { return cultMeshDocument(documentId, schema, snapshotDocument, options); diff --git a/packages/cultmesh-ts/test/cultmesh.test.ts b/packages/cultmesh-ts/test/cultmesh.test.ts index 48fd7dd7..b467f9ba 100644 --- a/packages/cultmesh-ts/test/cultmesh.test.ts +++ b/packages/cultmesh-ts/test/cultmesh.test.ts @@ -88,6 +88,7 @@ test("CultMesh TS document handles hide local cache plumbing behind typed reacti assert.equal(document.documentId, "cultmesh.note:note:1"); assert.equal(document.canReplace, true); + assert.equal(document.canSubmitPrediction, false); assert.equal((await bound.latest()).body, "initial"); await bound.replace({ @@ -115,6 +116,63 @@ test("CultMesh TS document handles hide local cache plumbing behind typed reacti ); }); +test("CultMesh TS document handles submit predictions through configured authority hooks", async () => { + let current = { + noteId: "note:prediction", + body: "initial", + }; + const predictions: string[] = []; + const contexts: string[] = []; + const document = CultMesh.document( + "cultmesh.note:prediction", + noteDocument, + async () => current, + { + routeHint: CultMesh.routeHint("network", "CultNet prediction"), + submitPrediction: async (context, value) => { + contexts.push(`${context.runtimeId}:${context.routeHint.kind}`); + predictions.push(value.body); + current = value; + }, + }, + ); + const verse = CultMesh.verse("starbridge", "pilot-a"); + const bound = document.bind(verse); + + assert.equal(document.canReplace, false); + assert.equal(document.canSubmitPrediction, true); + assert.equal(bound.canSubmitPrediction, true); + + await bound.submitPrediction({ + noteId: "note:prediction", + body: "predicted", + }); + + assert.deepEqual(contexts, ["pilot-a:network"]); + assert.deepEqual(predictions, ["predicted"]); + assert.equal((await bound.latest()).body, "predicted"); + + const alias = bound.asSchemaAlias(noteAliasDocument, { + parse: value => noteAliasDocument.schema.parse(value), + }); + assert.equal(alias.canSubmitPrediction, true); + await alias.submitPrediction({ + noteId: "note:prediction", + body: "alias-predicted", + }); + + assert.deepEqual(predictions, ["predicted", "alias-predicted"]); + assert.equal((await document.latest("pilot-a")).body, "alias-predicted"); + + assert.throws( + () => document.replace({ + noteId: "note:prediction", + body: "not-authoritative", + }), + /does not support replacement/, + ); +}); + test("CultMesh TS document handles read schema publications from single-file stores", async () => { const filePath = join(await mkdtemp(join(tmpdir(), "cultmesh-ts-publication-")), "publication.ccmp"); const node = await CultMesh.startNode(filePath, {