@world-engines/tmw 0.1.0-alpha.0

package/dist/scene-author-source.d.ts

@@ -0,0 +1,13 @@
+import { type TmwSceneStateV1 } from "./scene-state.js";
+/** 初始 Scene 只属于现有 metadata section；运行后唯一 authority 是 SAV.scene。 */
+export declare function initialTmwSceneFromMetadata(metadata: Readonly<Record<string, unknown>>): TmwSceneStateV1 | null;
+export interface TmwSceneSourceReferencesV1 {
+    readonly entityNodeIds: readonly string[];
+    readonly spatialWorld: null | Readonly<{
+        worldId: string;
+        revision: number;
+        spatialIds: readonly string[];
+    }>;
+}
+/** 引用校验消费作者源快照，不使用 project revision 代替地图自身 revision。 */
+export declare function validateTmwSceneSourceReferencesV1(scene: TmwSceneStateV1 | null, source: TmwSceneSourceReferencesV1): void;

package/dist/scene-author-source.js

@@ -0,0 +1,25 @@
+import { canonicalTmwSceneStateV1 } from "./scene-state.js";
+/** 初始 Scene 只属于现有 metadata section；运行后唯一 authority 是 SAV.scene。 */
+export function initialTmwSceneFromMetadata(metadata) {
+    const value = metadata.initial_scene;
+    return value === undefined || value === null ? null : canonicalTmwSceneStateV1(value);
+}
+/** 引用校验消费作者源快照，不使用 project revision 代替地图自身 revision。 */
+export function validateTmwSceneSourceReferencesV1(scene, source) {
+    if (scene === null)
+        return;
+    const entities = new Set(source.entityNodeIds);
+    for (const id of scene.presentEntityNodeIds) {
+        if (!entities.has(id))
+            throw new Error(`tmw_scene_entity_missing:${id}`);
+    }
+    if (scene.spatialRef === null)
+        return;
+    const world = source.spatialWorld;
+    if (world === null || world.worldId !== scene.spatialRef.worldId)
+        throw new Error("tmw_scene_spatial_world_missing");
+    if (world.revision !== scene.spatialRef.sourceRevision)
+        throw new Error("tmw_scene_spatial_revision_mismatch");
+    if (!world.spatialIds.includes(scene.spatialRef.spatialId))
+        throw new Error("tmw_scene_spatial_id_missing");
+}

package/dist/scene-state.d.ts

@@ -0,0 +1,275 @@
+import { TMW_SCENE_SEMANTICS_REVISION } from "./runtime-contract.js";
+export declare const TMW_SCENE_SCHEMA_VERSION: 1;
+export { TMW_SCENE_SEMANTICS_REVISION };
+export declare const TMW_SCENE_MAX_PRESENT_ENTITIES: 4096;
+export declare const TMW_SCENE_MAX_NOTES: 256;
+export declare const TMW_SCENE_MAX_NOTE_TEXT_LENGTH: 32768;
+/** Registry/UI/authoring consume this single closed schema authority. */
+export declare const TMW_SCENE_CAPABILITY_ARGUMENT_SCHEMAS: Readonly<{
+    "scene.begin": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            sceneId: Readonly<{
+                type: "string";
+                minLength: 1;
+                maxLength: 512;
+            }>;
+            worldTime: Readonly<{
+                type: readonly string[];
+            }>;
+            presentEntityNodeIds: Readonly<{
+                type: "array";
+                maxItems: 4096;
+                uniqueItems: true;
+                items: Readonly<{
+                    type: "string";
+                    minLength: 1;
+                    maxLength: 512;
+                }>;
+            }>;
+            spatialRef: Readonly<{
+                anyOf: readonly (Readonly<{
+                    type: "null";
+                }> | Readonly<{
+                    type: "object";
+                    additionalProperties: false;
+                    required: readonly string[];
+                    properties: Readonly<{
+                        worldId: Readonly<{
+                            type: "string";
+                            minLength: 1;
+                            maxLength: 512;
+                        }>;
+                        sourceRevision: Readonly<{
+                            type: "integer";
+                            minimum: 0;
+                        }>;
+                        spatialId: Readonly<{
+                            type: "string";
+                            minLength: 1;
+                            maxLength: 512;
+                        }>;
+                    }>;
+                }>)[];
+            }>;
+        }>;
+    }>;
+    "scene.end": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        maxProperties: 0;
+    }>;
+    "scene.present.add": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            entityNodeId: Readonly<{
+                type: "string";
+                minLength: 1;
+                maxLength: 512;
+            }>;
+        }>;
+    }>;
+    "scene.present.remove": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            entityNodeId: Readonly<{
+                type: "string";
+                minLength: 1;
+                maxLength: 512;
+            }>;
+        }>;
+    }>;
+    "scene.present.replace": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            entityNodeIds: Readonly<{
+                type: "array";
+                maxItems: 4096;
+                uniqueItems: true;
+                items: Readonly<{
+                    type: "string";
+                    minLength: 1;
+                    maxLength: 512;
+                }>;
+            }>;
+        }>;
+    }>;
+    "scene.time.set": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            worldTime: Readonly<{
+                type: readonly string[];
+            }>;
+        }>;
+    }>;
+    "scene.location.set": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            spatialRef: Readonly<{
+                anyOf: readonly (Readonly<{
+                    type: "null";
+                }> | Readonly<{
+                    type: "object";
+                    additionalProperties: false;
+                    required: readonly string[];
+                    properties: Readonly<{
+                        worldId: Readonly<{
+                            type: "string";
+                            minLength: 1;
+                            maxLength: 512;
+                        }>;
+                        sourceRevision: Readonly<{
+                            type: "integer";
+                            minimum: 0;
+                        }>;
+                        spatialId: Readonly<{
+                            type: "string";
+                            minLength: 1;
+                            maxLength: 512;
+                        }>;
+                    }>;
+                }>)[];
+            }>;
+        }>;
+    }>;
+    "scene.note.add": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            noteId: Readonly<{
+                type: "string";
+                minLength: 1;
+                maxLength: 512;
+            }>;
+            text: Readonly<{
+                type: "string";
+                maxLength: 32768;
+            }>;
+            lifetime: Readonly<{
+                enum: readonly string[];
+            }>;
+        }>;
+    }>;
+    "scene.note.remove": Readonly<{
+        type: "object";
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Readonly<{
+            noteId: Readonly<{
+                type: "string";
+                minLength: 1;
+                maxLength: 512;
+            }>;
+        }>;
+    }>;
+}>;
+export type TmwSceneNoteLifetime = "once" | "scene_end";
+export interface TmwSceneSpatialRefV1 {
+    readonly worldId: string;
+    readonly sourceRevision: number;
+    readonly spatialId: string;
+}
+export interface TmwSceneManuscriptNoteV1 {
+    readonly noteId: string;
+    /** Writer-facing manuscript, preserved verbatim (including whitespace). */
+    readonly text: string;
+    readonly lifetime: TmwSceneNoteLifetime;
+    readonly createdOperationId: string;
+}
+export interface TmwSceneStateV1 {
+    readonly schemaVersion: typeof TMW_SCENE_SCHEMA_VERSION;
+    readonly sceneId: string;
+    readonly revision: number;
+    readonly worldTime: number | null;
+    readonly presentEntityNodeIds: ReadonlyArray<string>;
+    readonly spatialRef: TmwSceneSpatialRefV1 | null;
+    readonly manuscriptNotes: ReadonlyArray<TmwSceneManuscriptNoteV1>;
+}
+export type TmwSceneOperationV1 = Readonly<{
+    kind: "scene.begin";
+    sceneId: string;
+    worldTime: number | null;
+    presentEntityNodeIds: ReadonlyArray<string>;
+    spatialRef: TmwSceneSpatialRefV1 | null;
+}> | Readonly<{
+    kind: "scene.end";
+}> | Readonly<{
+    kind: "scene.present.add";
+    entityNodeId: string;
+}> | Readonly<{
+    kind: "scene.present.remove";
+    entityNodeId: string;
+}> | Readonly<{
+    kind: "scene.present.replace";
+    entityNodeIds: ReadonlyArray<string>;
+}> | Readonly<{
+    kind: "scene.time.set";
+    worldTime: number | null;
+}> | Readonly<{
+    kind: "scene.location.set";
+    spatialRef: TmwSceneSpatialRefV1 | null;
+}> | Readonly<{
+    kind: "scene.note.add";
+    noteId: string;
+    text: string;
+    lifetime: TmwSceneNoteLifetime;
+}> | Readonly<{
+    kind: "scene.note.remove";
+    noteId: string;
+}>;
+export interface TmwCommittedWriterNoteConsumptionV1 {
+    readonly sceneRevision: number;
+    readonly noteIds: ReadonlyArray<string>;
+    readonly writerReceiptDigest: string;
+}
+/** Writer commit 与后续 authored event 之间的 crash-resume 描述；不预写未来 timeline binding。 */
+export interface TmwPendingSceneClockCrossingV1 {
+    readonly eventId: string;
+    readonly eventType: string;
+    readonly logicalSeq: number;
+    readonly worldTime: number | null;
+    readonly crossingDirection: "forward" | "backward";
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly payloadHash: string;
+    readonly commitReceiptDigest: string;
+    /** 仅由 Runtime3 已接受 author lifecycle capability 写入；缺席即不允许 View 投递。 */
+    readonly authorViewProjection?: Readonly<{
+        readonly schema: "tmw3.author-view-event.v1";
+        readonly saveId: string;
+        readonly artifactDigest: string;
+        readonly sourceEventId: string;
+        readonly sourceCommitReceiptDigest: string;
+        readonly viewVisiblePayload: Readonly<Record<string, null | boolean | number | string>>;
+    }>;
+}
+export declare function canonicalTmwAuthorViewProjectionV1(value: unknown): TmwPendingSceneClockCrossingV1["authorViewProjection"];
+export declare function canonicalTmwPendingSceneClockCrossingV1(value: TmwPendingSceneClockCrossingV1): TmwPendingSceneClockCrossingV1;
+export declare function canonicalTmwSceneSpatialRefV1(value: TmwSceneSpatialRefV1): TmwSceneSpatialRefV1;
+export declare function canonicalTmwSceneStateV1(value: TmwSceneStateV1): TmwSceneStateV1;
+/** Converts a registered scene capability plus its arguments to the one reducer interface. */
+export declare function tmwSceneOperationFromEffect(capabilityId: string, argumentsValue: unknown): TmwSceneOperationV1 | null;
+/** Pure reducer. Persist its result only as part of the successful Runtime activation commit. */
+export declare function reduceTmwSceneV1(current: TmwSceneStateV1 | null, operation: TmwSceneOperationV1, operationId: string): TmwSceneStateV1 | null;
+/** Internal-only consume gate: callers must bind exact note ids to the successful writer receipt. */
+export declare function consumeCommittedTmwSceneNotesV1(current: TmwSceneStateV1, consumption: TmwCommittedWriterNoteConsumptionV1, committedWriterReceiptDigest: string): TmwSceneStateV1;
+export declare function reduceTmwSceneEffectsV1(current: TmwSceneStateV1 | null, effects: ReadonlyArray<Readonly<{
+    capabilityId: string;
+    input: unknown;
+    effectId: string;
+}>>, operationId: string): TmwSceneStateV1 | null;
+/** Single clock authority adapter: scheduler observes Scene; it never owns an independently writable world clock. */
+export declare function projectTmwSceneWorldTimeV1(scene: TmwSceneStateV1 | null): number | null;
+export declare function setTmwSceneWorldTimeV1(scene: TmwSceneStateV1 | null, worldTime: number | null): TmwSceneStateV1 | null;

package/dist/scene-state.js

@@ -0,0 +1,334 @@
+import { canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, } from "./runtime-trace.js";
+import { TMW_SCENE_SEMANTICS_REVISION } from "./runtime-contract.js";
+export const TMW_SCENE_SCHEMA_VERSION = 1;
+export { TMW_SCENE_SEMANTICS_REVISION };
+export const TMW_SCENE_MAX_PRESENT_ENTITIES = 4096;
+export const TMW_SCENE_MAX_NOTES = 256;
+export const TMW_SCENE_MAX_NOTE_TEXT_LENGTH = 32768;
+const IDENTIFIER_SCHEMA = Object.freeze({ type: "string", minLength: 1, maxLength: 512 });
+const WORLD_TIME_SCHEMA = Object.freeze({ type: Object.freeze(["number", "null"]) });
+const SPATIAL_REF_SCHEMA = Object.freeze({
+    anyOf: Object.freeze([
+        Object.freeze({ type: "null" }),
+        Object.freeze({
+            type: "object",
+            additionalProperties: false,
+            required: Object.freeze(["worldId", "sourceRevision", "spatialId"]),
+            properties: Object.freeze({
+                worldId: IDENTIFIER_SCHEMA,
+                sourceRevision: Object.freeze({ type: "integer", minimum: 0 }),
+                spatialId: IDENTIFIER_SCHEMA,
+            }),
+        }),
+    ]),
+});
+/** Registry/UI/authoring consume this single closed schema authority. */
+export const TMW_SCENE_CAPABILITY_ARGUMENT_SCHEMAS = Object.freeze({
+    "scene.begin": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["sceneId", "worldTime", "presentEntityNodeIds", "spatialRef"]), properties: Object.freeze({ sceneId: IDENTIFIER_SCHEMA, worldTime: WORLD_TIME_SCHEMA, presentEntityNodeIds: Object.freeze({ type: "array", maxItems: TMW_SCENE_MAX_PRESENT_ENTITIES, uniqueItems: true, items: IDENTIFIER_SCHEMA }), spatialRef: SPATIAL_REF_SCHEMA }) }),
+    "scene.end": Object.freeze({ type: "object", additionalProperties: false, maxProperties: 0 }),
+    "scene.present.add": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["entityNodeId"]), properties: Object.freeze({ entityNodeId: IDENTIFIER_SCHEMA }) }),
+    "scene.present.remove": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["entityNodeId"]), properties: Object.freeze({ entityNodeId: IDENTIFIER_SCHEMA }) }),
+    "scene.present.replace": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["entityNodeIds"]), properties: Object.freeze({ entityNodeIds: Object.freeze({ type: "array", maxItems: TMW_SCENE_MAX_PRESENT_ENTITIES, uniqueItems: true, items: IDENTIFIER_SCHEMA }) }) }),
+    "scene.time.set": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["worldTime"]), properties: Object.freeze({ worldTime: WORLD_TIME_SCHEMA }) }),
+    "scene.location.set": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["spatialRef"]), properties: Object.freeze({ spatialRef: SPATIAL_REF_SCHEMA }) }),
+    "scene.note.add": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["noteId", "text", "lifetime"]), properties: Object.freeze({ noteId: IDENTIFIER_SCHEMA, text: Object.freeze({ type: "string", maxLength: TMW_SCENE_MAX_NOTE_TEXT_LENGTH }), lifetime: Object.freeze({ enum: Object.freeze(["once", "scene_end"]) }) }) }),
+    "scene.note.remove": Object.freeze({ type: "object", additionalProperties: false, required: Object.freeze(["noteId"]), properties: Object.freeze({ noteId: IDENTIFIER_SCHEMA }) }),
+});
+export function canonicalTmwAuthorViewProjectionV1(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)
+        || Object.keys(value).sort().join(",") !== "artifactDigest,saveId,schema,sourceCommitReceiptDigest,sourceEventId,viewVisiblePayload") {
+        throw new Error("tmw_scene_pending_crossing_author_view_projection_invalid");
+    }
+    const projection = record(value);
+    const { schema, saveId, artifactDigest, sourceEventId, sourceCommitReceiptDigest, viewVisiblePayload: rawViewVisiblePayload } = projection;
+    if (schema !== "tmw3.author-view-event.v1"
+        || typeof saveId !== "string"
+        || typeof artifactDigest !== "string"
+        || typeof sourceEventId !== "string"
+        || typeof sourceCommitReceiptDigest !== "string"
+        || typeof rawViewVisiblePayload !== "object"
+        || rawViewVisiblePayload === null
+        || Array.isArray(rawViewVisiblePayload)) {
+        throw new Error("tmw_scene_pending_crossing_author_view_projection_invalid");
+    }
+    const viewVisiblePayload = Object.create(null);
+    for (const [key, item] of Object.entries(rawViewVisiblePayload)) {
+        requireTmwIdentifier(key, "scene_pending_crossing_author_view_payload_key");
+        if (item !== null && typeof item !== "boolean" && typeof item !== "string" && (typeof item !== "number" || !Number.isFinite(item))) {
+            throw new Error("tmw_scene_pending_crossing_author_view_projection_invalid");
+        }
+        viewVisiblePayload[key] = item;
+    }
+    return Object.freeze({
+        schema: "tmw3.author-view-event.v1",
+        saveId: requireTmwIdentifier(saveId, "scene_pending_crossing_author_view_save_id"),
+        artifactDigest: requireTmwSha256(artifactDigest, "scene_pending_crossing_author_view_artifact_digest"),
+        sourceEventId: requireTmwIdentifier(sourceEventId, "scene_pending_crossing_author_view_event_id"),
+        sourceCommitReceiptDigest: requireTmwSha256(sourceCommitReceiptDigest, "scene_pending_crossing_author_view_receipt_digest"),
+        viewVisiblePayload: Object.freeze(viewVisiblePayload),
+    });
+}
+export function canonicalTmwPendingSceneClockCrossingV1(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)
+        || !["commitReceiptDigest,crossingDirection,eventId,eventType,logicalSeq,payload,payloadHash,worldTime", "authorViewProjection,commitReceiptDigest,crossingDirection,eventId,eventType,logicalSeq,payload,payloadHash,worldTime"].includes(Object.keys(value).sort().join(","))
+        || (value.crossingDirection !== "forward" && value.crossingDirection !== "backward")) {
+        throw new Error("tmw_scene_pending_crossing_invalid");
+    }
+    const worldTime = canonicalSceneWorldTime(value.worldTime);
+    const authorViewProjection = value.authorViewProjection === undefined
+        ? undefined
+        : canonicalTmwAuthorViewProjectionV1(value.authorViewProjection);
+    return Object.freeze({
+        eventId: requireTmwIdentifier(value.eventId, "scene_pending_crossing_event_id"),
+        eventType: requireTmwIdentifier(value.eventType, "scene_pending_crossing_event_type"),
+        logicalSeq: requireTmwSafeInteger(value.logicalSeq, "scene_pending_crossing_logical_seq", 0),
+        worldTime,
+        crossingDirection: value.crossingDirection,
+        payload: record(value.payload),
+        payloadHash: requireTmwSha256(value.payloadHash, "scene_pending_crossing_payload_hash"),
+        commitReceiptDigest: requireTmwSha256(value.commitReceiptDigest, "scene_pending_crossing_receipt_digest"),
+        ...(authorViewProjection === undefined ? {} : { authorViewProjection }),
+    });
+}
+function canonicalIds(values, label) {
+    if (!Array.isArray(values))
+        throw new Error(`tmw_${label}_invalid`);
+    const ids = values.map((value) => requireTmwIdentifier(value, label));
+    if (new Set(ids).size !== ids.length)
+        throw new Error(`tmw_${label}_duplicate`);
+    if (ids.length > TMW_SCENE_MAX_PRESENT_ENTITIES)
+        throw new Error(`tmw_${label}_limit_exceeded`);
+    return Object.freeze([...ids].sort());
+}
+export function canonicalTmwSceneSpatialRefV1(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("tmw_scene_spatial_ref_invalid");
+    }
+    if (Object.keys(value).sort().join(",") !== "sourceRevision,spatialId,worldId") {
+        throw new Error("tmw_scene_spatial_ref_invalid");
+    }
+    return Object.freeze({
+        worldId: requireTmwIdentifier(value.worldId, "scene_world_id"),
+        sourceRevision: requireTmwSafeInteger(value.sourceRevision, "scene_spatial_source_revision", 0),
+        spatialId: requireTmwIdentifier(value.spatialId, "scene_spatial_id"),
+    });
+}
+export function canonicalTmwSceneStateV1(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("tmw_scene_invalid");
+    }
+    if (Object.keys(value).sort().join(",") !== "manuscriptNotes,presentEntityNodeIds,revision,sceneId,schemaVersion,spatialRef,worldTime"
+        || !Array.isArray(value.manuscriptNotes)) {
+        throw new Error("tmw_scene_invalid");
+    }
+    if (value.schemaVersion !== TMW_SCENE_SCHEMA_VERSION)
+        throw new Error("tmw_scene_schema_unsupported");
+    if (value.manuscriptNotes.length > TMW_SCENE_MAX_NOTES)
+        throw new Error("tmw_scene_note_limit_exceeded");
+    const notes = value.manuscriptNotes.map((note) => {
+        if (typeof note !== "object" || note === null || Array.isArray(note)
+            || Object.keys(note).sort().join(",") !== "createdOperationId,lifetime,noteId,text"
+            || typeof note.text !== "string"
+            || note.text.length > TMW_SCENE_MAX_NOTE_TEXT_LENGTH
+            || (note.lifetime !== "once" && note.lifetime !== "scene_end")) {
+            throw new Error("tmw_scene_note_invalid");
+        }
+        return Object.freeze({
+            noteId: requireTmwIdentifier(note.noteId, "scene_note_id"),
+            text: note.text,
+            lifetime: note.lifetime,
+            createdOperationId: requireTmwIdentifier(note.createdOperationId, "scene_note_operation_id"),
+        });
+    });
+    if (new Set(notes.map((note) => note.noteId)).size !== notes.length) {
+        throw new Error("tmw_scene_note_duplicate");
+    }
+    return Object.freeze({
+        schemaVersion: TMW_SCENE_SCHEMA_VERSION,
+        sceneId: requireTmwIdentifier(value.sceneId, "scene_id"),
+        revision: requireTmwSafeInteger(value.revision, "scene_revision", 0),
+        worldTime: canonicalSceneWorldTime(value.worldTime),
+        presentEntityNodeIds: canonicalIds(value.presentEntityNodeIds, "scene_present_entity_node_id"),
+        spatialRef: value.spatialRef === null ? null : canonicalTmwSceneSpatialRefV1(value.spatialRef),
+        manuscriptNotes: Object.freeze(notes),
+    });
+}
+function record(value) {
+    const canonical = canonicalTmwJsonValue(value, "scene_operation_arguments");
+    if (typeof canonical !== "object" || canonical === null || Array.isArray(canonical)) {
+        throw new Error("tmw_scene_operation_arguments_invalid");
+    }
+    return canonical;
+}
+function canonicalSceneWorldTime(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new Error("tmw_scene_world_time_invalid");
+    return value;
+}
+function requireExactKeys(value, keys) {
+    if (Object.keys(value).sort().join(",") !== [...keys].sort().join(",")) {
+        throw new Error("tmw_scene_operation_arguments_invalid");
+    }
+}
+/** Converts a registered scene capability plus its arguments to the one reducer interface. */
+export function tmwSceneOperationFromEffect(capabilityId, argumentsValue) {
+    if (!capabilityId.startsWith("scene."))
+        return null;
+    const args = record(argumentsValue);
+    switch (capabilityId) {
+        case "scene.begin": {
+            requireExactKeys(args, ["sceneId", "worldTime", "presentEntityNodeIds", "spatialRef"]);
+            return Object.freeze({
+                kind: capabilityId,
+                sceneId: requireTmwIdentifier(args.sceneId, "scene_id"),
+                worldTime: canonicalSceneWorldTime(args.worldTime),
+                presentEntityNodeIds: canonicalIds(args.presentEntityNodeIds, "scene_present_entity_node_id"),
+                spatialRef: args.spatialRef === null ? null : canonicalTmwSceneSpatialRefV1(args.spatialRef),
+            });
+        }
+        case "scene.end": {
+            requireExactKeys(args, []);
+            return Object.freeze({ kind: capabilityId });
+        }
+        case "scene.present.add": {
+            requireExactKeys(args, ["entityNodeId"]);
+            return Object.freeze({ kind: capabilityId, entityNodeId: requireTmwIdentifier(args.entityNodeId, "scene_entity_node_id") });
+        }
+        case "scene.present.remove": {
+            requireExactKeys(args, ["entityNodeId"]);
+            return Object.freeze({ kind: capabilityId, entityNodeId: requireTmwIdentifier(args.entityNodeId, "scene_entity_node_id") });
+        }
+        case "scene.present.replace": {
+            requireExactKeys(args, ["entityNodeIds"]);
+            return Object.freeze({ kind: capabilityId, entityNodeIds: canonicalIds(args.entityNodeIds, "scene_present_entity_node_id") });
+        }
+        case "scene.time.set": {
+            requireExactKeys(args, ["worldTime"]);
+            return Object.freeze({ kind: capabilityId, worldTime: canonicalSceneWorldTime(args.worldTime) });
+        }
+        case "scene.location.set": {
+            requireExactKeys(args, ["spatialRef"]);
+            return Object.freeze({ kind: capabilityId, spatialRef: args.spatialRef === null ? null : canonicalTmwSceneSpatialRefV1(args.spatialRef) });
+        }
+        case "scene.note.add": {
+            requireExactKeys(args, ["noteId", "text", "lifetime"]);
+            if (typeof args.text !== "string" || args.text.length > TMW_SCENE_MAX_NOTE_TEXT_LENGTH
+                || (args.lifetime !== "once" && args.lifetime !== "scene_end"))
+                throw new Error("tmw_scene_note_invalid");
+            return Object.freeze({ kind: capabilityId, noteId: requireTmwIdentifier(args.noteId, "scene_note_id"), text: args.text, lifetime: args.lifetime });
+        }
+        case "scene.note.remove": {
+            requireExactKeys(args, ["noteId"]);
+            return Object.freeze({ kind: capabilityId, noteId: requireTmwIdentifier(args.noteId, "scene_note_id") });
+        }
+        default: throw new Error("tmw_scene_capability_unknown");
+    }
+}
+/** Pure reducer. Persist its result only as part of the successful Runtime activation commit. */
+export function reduceTmwSceneV1(current, operation, operationId) {
+    const canonicalOperationId = requireTmwIdentifier(operationId, "scene_operation_id");
+    if (operation.kind === "scene.begin")
+        return canonicalTmwSceneStateV1({
+            schemaVersion: 1,
+            sceneId: operation.sceneId,
+            revision: 0,
+            worldTime: operation.worldTime,
+            presentEntityNodeIds: operation.presentEntityNodeIds,
+            spatialRef: operation.spatialRef,
+            manuscriptNotes: Object.freeze([]),
+        });
+    if (operation.kind === "scene.end")
+        return null;
+    if (current === null)
+        throw new Error("tmw_scene_not_active");
+    const base = canonicalTmwSceneStateV1(current);
+    let present = base.presentEntityNodeIds;
+    let spatialRef = base.spatialRef;
+    let worldTime = base.worldTime;
+    let notes = base.manuscriptNotes;
+    if (operation.kind === "scene.present.add")
+        present = canonicalIds([...present, operation.entityNodeId], "scene_present_entity_node_id");
+    else if (operation.kind === "scene.present.remove")
+        present = Object.freeze(present.filter((id) => id !== operation.entityNodeId));
+    else if (operation.kind === "scene.present.replace")
+        present = operation.entityNodeIds;
+    else if (operation.kind === "scene.time.set")
+        worldTime = operation.worldTime;
+    else if (operation.kind === "scene.location.set")
+        spatialRef = operation.spatialRef;
+    else if (operation.kind === "scene.note.add") {
+        if (notes.some((note) => note.noteId === operation.noteId))
+            throw new Error("tmw_scene_note_duplicate");
+        if (notes.length >= TMW_SCENE_MAX_NOTES)
+            throw new Error("tmw_scene_note_limit_exceeded");
+        notes = Object.freeze([...notes, Object.freeze({
+                noteId: operation.noteId,
+                text: operation.text,
+                lifetime: operation.lifetime,
+                createdOperationId: canonicalOperationId,
+            })]);
+    }
+    else {
+        const note = notes.find((candidate) => candidate.noteId === operation.noteId);
+        if (note === undefined)
+            throw new Error("tmw_scene_note_missing");
+        notes = Object.freeze(notes.filter((candidate) => candidate.noteId !== operation.noteId));
+    }
+    return canonicalTmwSceneStateV1({ ...base, revision: base.revision + 1, worldTime, presentEntityNodeIds: present, spatialRef, manuscriptNotes: notes });
+}
+/** Internal-only consume gate: callers must bind exact note ids to the successful writer receipt. */
+export function consumeCommittedTmwSceneNotesV1(current, consumption, committedWriterReceiptDigest) {
+    const base = canonicalTmwSceneStateV1(current);
+    if (consumption.sceneRevision !== base.revision)
+        throw new Error("tmw_scene_note_consumption_revision_mismatch");
+    if (consumption.writerReceiptDigest !== committedWriterReceiptDigest) {
+        throw new Error("tmw_scene_note_consumption_receipt_mismatch");
+    }
+    const noteIds = canonicalIds(consumption.noteIds, "scene_consumed_note_id");
+    const byId = new Map(base.manuscriptNotes.map((note) => [note.noteId, note]));
+    for (const noteId of noteIds) {
+        const note = byId.get(noteId);
+        if (note === undefined)
+            throw new Error("tmw_scene_note_missing");
+        if (note.lifetime !== "once")
+            throw new Error("tmw_scene_note_not_once");
+    }
+    if (noteIds.length === 0)
+        return base;
+    const consumed = new Set(noteIds);
+    return canonicalTmwSceneStateV1({
+        ...base,
+        revision: base.revision + 1,
+        manuscriptNotes: Object.freeze(base.manuscriptNotes.filter((note) => !consumed.has(note.noteId))),
+    });
+}
+export function reduceTmwSceneEffectsV1(current, effects, operationId) {
+    return effects.reduce((scene, effect) => {
+        const operation = tmwSceneOperationFromEffect(effect.capabilityId, effect.input);
+        return operation === null ? scene : reduceTmwSceneV1(scene, operation, `${operationId}:${effect.effectId}`);
+    }, current);
+}
+/** Single clock authority adapter: scheduler observes Scene; it never owns an independently writable world clock. */
+export function projectTmwSceneWorldTimeV1(scene) {
+    return scene?.worldTime ?? null;
+}
+export function setTmwSceneWorldTimeV1(scene, worldTime) {
+    const canonicalWorldTime = canonicalSceneWorldTime(worldTime);
+    if (scene === null) {
+        if (canonicalWorldTime !== null)
+            throw new Error("tmw_scene_not_active");
+        return null;
+    }
+    if (scene.worldTime === canonicalWorldTime)
+        return canonicalTmwSceneStateV1(scene);
+    const base = canonicalTmwSceneStateV1(scene);
+    return canonicalTmwSceneStateV1({
+        ...base,
+        revision: base.revision + 1,
+        worldTime: canonicalWorldTime,
+    });
+}