Add TS document prediction submissions

This commit is contained in:
Meta Vens 2026-06-27 16:24:08 +01:00
commit cb6301e1cf
3 changed files with 130 additions and 0 deletions

View file

@ -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:

View file

@ -111,6 +111,11 @@ export type CultMeshDocumentReplacer<TDocument> = (
value: TDocument,
) => Promise<void>;
export type CultMeshDocumentPredictionSubmitter<TDocument> = (
context: CultMeshQueryContext,
value: TDocument,
) => Promise<void>;
export type CultMeshCollectionSnapshot<TDocument> = readonly TDocument[];
export type CultMeshCollectionChangeKind = "added" | "updated" | "removed" | "reset";
@ -724,6 +729,7 @@ export class CultMeshDocumentHandle<TDocument> {
routeHint?: CultMeshRouteHint;
watchDocument?: CultMeshDocumentWatcher<TDocument>;
replaceDocument?: CultMeshDocumentReplacer<TDocument>;
submitPrediction?: CultMeshDocumentPredictionSubmitter<TDocument>;
} = {},
) {
requireNonEmpty(documentId, "documentId");
@ -732,15 +738,23 @@ export class CultMeshDocumentHandle<TDocument> {
this.routeHint = options.routeHint ?? cultMeshRouteHint();
this.watchDocument = options.watchDocument;
this.replaceDocument = options.replaceDocument;
this.submitPredictionDocument = options.submitPrediction;
}
private readonly watchDocument: CultMeshDocumentWatcher<TDocument> | undefined;
private readonly replaceDocument: CultMeshDocumentReplacer<TDocument> | undefined;
private readonly submitPredictionDocument:
| CultMeshDocumentPredictionSubmitter<TDocument>
| undefined;
public get canReplace(): boolean {
return this.replaceDocument !== undefined;
}
public get canSubmitPrediction(): boolean {
return this.submitPredictionDocument !== undefined;
}
public latest(context: CultMeshQueryContext | string = "local"): Promise<TDocument> {
return this.snapshotDocument(
this.resolveContext(typeof context === "string" ? cultMeshQueryContext(context) : context),
@ -802,6 +816,31 @@ export class CultMeshDocumentHandle<TDocument> {
return this.replaceDocument(this.resolveContext(context), value);
}
public submitPrediction(value: TDocument): Promise<void>;
public submitPrediction(context: CultMeshQueryContext | string, value: TDocument): Promise<void>;
public submitPrediction(
contextOrValue: CultMeshQueryContext | string | TDocument,
maybeValue?: TDocument,
): Promise<void> {
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<TAlias>(
schema: CultMeshDocumentSchemaDescriptor,
options: { parse?: (value: unknown) => TAlias } = {},
@ -827,6 +866,9 @@ export class CultMeshDocumentHandle<TDocument> {
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<TDocument> {
return this.document.canReplace;
}
public get canSubmitPrediction(): boolean {
return this.document.canSubmitPrediction;
}
public latest(): Promise<TDocument> {
return this.document.latest(cultMeshQueryContextFromVerse(this.verse));
}
@ -880,6 +926,10 @@ export class CultMeshBoundDocumentHandle<TDocument> {
return this.document.replace(cultMeshQueryContextFromVerse(this.verse), value);
}
public submitPrediction(value: TDocument): Promise<void> {
return this.document.submitPrediction(cultMeshQueryContextFromVerse(this.verse), value);
}
public asSchemaAlias<TAlias>(
schema: CultMeshDocumentSchemaDescriptor,
options: { parse?: (value: unknown) => TAlias } = {},
@ -1794,6 +1844,7 @@ export function cultMeshDocument<TDocument>(
routeHint?: CultMeshRouteHint;
watchDocument?: CultMeshDocumentWatcher<TDocument>;
replaceDocument?: CultMeshDocumentReplacer<TDocument>;
submitPrediction?: CultMeshDocumentPredictionSubmitter<TDocument>;
} = {},
): CultMeshDocumentHandle<TDocument> {
return new CultMeshDocumentHandle(documentId, schema, snapshotDocument, options);
@ -3592,6 +3643,7 @@ export class CultMesh {
routeHint?: CultMeshRouteHint;
watchDocument?: CultMeshDocumentWatcher<TDocument>;
replaceDocument?: CultMeshDocumentReplacer<TDocument>;
submitPrediction?: CultMeshDocumentPredictionSubmitter<TDocument>;
} = {},
): CultMeshDocumentHandle<TDocument> {
return cultMeshDocument(documentId, schema, snapshotDocument, options);

View file

@ -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, {