@world-engines/tmw 0.1.0-alpha.0

package/dist/turn-commit.js

@@ -0,0 +1,190 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJson, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+function canonicalIdentity(input) {
+    if (input.runtimeGeneration !== 3)
+        throw new Error("unsupported_runtime_generation");
+    return Object.freeze({
+        operationId: requireTmwIdentifier(input.operationId, "turn_commit_operation_id"),
+        turnId: requireTmwIdentifier(input.turnId, "turn_commit_turn_id"),
+        epoch: requireTmwSafeInteger(input.epoch, "turn_commit_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "turn_commit_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "turn_commit_artifact_digest"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "turn_commit_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "turn_commit_timeline_revision"),
+        leaseId: requireTmwIdentifier(input.leaseId, "turn_commit_lease_id"),
+    });
+}
+function canonicalStageDigests(input) {
+    const result = Object.create(null);
+    for (const [stage, digest] of [...input.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
+        result[requireTmwIdentifier(stage, "turn_commit_stage")] = requireTmwSha256(digest, "turn_commit_stage_digest");
+    }
+    return Object.freeze(result);
+}
+async function preActivationTerminalDigest(receipt) {
+    // Break the terminal <-> activation receipt hash cycle. The terminal body
+    // digest is fixed before activation; the final receipt then records the
+    // activation receipt digest and is compared in full on durable readback.
+    const { activationReceiptDigest: _activationReceiptDigest, ...preActivationBody } = receipt;
+    return await tmwSha256Hex(canonicalTmwJson(preActivationBody));
+}
+function sameIdentity(left, right) {
+    return left.operationId === right.operationId
+        && left.turnId === right.turnId
+        && left.epoch === right.epoch
+        && left.runtimeGeneration === right.runtimeGeneration
+        && left.runtimeContractHash === right.runtimeContractHash
+        && left.artifactDigest === right.artifactDigest
+        && left.sourceRevision === right.sourceRevision
+        && left.timelineRevision === right.timelineRevision
+        && left.leaseId === right.leaseId;
+}
+export class DurableTurnCommitOperation {
+    #identity;
+    #operationDigest;
+    #store;
+    #stages = new Map();
+    #terminal;
+    constructor(identity, operationDigest, store, terminal) {
+        this.#identity = identity;
+        this.#operationDigest = operationDigest;
+        this.#store = store;
+        this.#terminal = terminal;
+        if (terminal !== null) {
+            for (const [stage, digest] of Object.entries(terminal.stageDigests)) {
+                this.#stages.set(stage, digest);
+            }
+        }
+    }
+    static async open(input) {
+        const identity = canonicalIdentity(input.identity);
+        const operationDigest = await tmwSha256Hex(canonicalTmwJson({
+            identity,
+            operation: input.operation,
+        }));
+        const terminal = await input.store.read(identity.operationId);
+        if (terminal !== null) {
+            if (!sameIdentity(identity, terminal) || terminal.operationDigest !== operationDigest) {
+                throw new Error("tmw_turn_commit_operation_identity_conflict");
+            }
+        }
+        return new DurableTurnCommitOperation(identity, operationDigest, input.store, terminal);
+    }
+    recordStage(stageInput, digestInput) {
+        if (this.#terminal !== null)
+            throw new Error("tmw_turn_commit_terminal_sealed");
+        const stage = requireTmwIdentifier(stageInput, "turn_commit_stage");
+        const digest = requireTmwSha256(digestInput, "turn_commit_stage_digest");
+        const previous = this.#stages.get(stage);
+        if (previous !== undefined && previous !== digest) {
+            throw new Error("tmw_turn_commit_stage_digest_conflict");
+        }
+        this.#stages.set(stage, digest);
+    }
+    async commit(input) {
+        return await this.#finalize({
+            terminal: "committed",
+            reasonCode: null,
+            budgetReceiptDigest: input.budgetReceiptDigest,
+            activationReceiptDigest: input.activationReceiptDigest,
+        });
+    }
+    async fail(reasonCode, budgetReceiptDigest) {
+        return await this.#finalize({
+            terminal: "failed",
+            reasonCode,
+            budgetReceiptDigest,
+            activationReceiptDigest: null,
+        });
+    }
+    async abort(reasonCode, budgetReceiptDigest) {
+        return await this.#finalize({
+            terminal: "aborted",
+            reasonCode,
+            budgetReceiptDigest,
+            activationReceiptDigest: null,
+        });
+    }
+    async dispose(reasonCode, budgetReceiptDigest) {
+        return await this.#finalize({
+            terminal: "disposed",
+            reasonCode,
+            budgetReceiptDigest,
+            activationReceiptDigest: null,
+        });
+    }
+    snapshot() {
+        return Object.freeze({
+            identity: this.#identity,
+            operationDigest: this.#operationDigest,
+            stageDigests: canonicalStageDigests(this.#stages),
+            terminal: this.#terminal,
+        });
+    }
+    async previewCommittedTerminalDigest(budgetReceiptDigestInput) {
+        const budgetReceiptDigest = requireTmwSha256(budgetReceiptDigestInput, "turn_commit_budget_receipt_digest");
+        if (this.#terminal !== null) {
+            if (this.#terminal.terminal !== "committed"
+                || this.#terminal.budgetReceiptDigest !== budgetReceiptDigest) {
+                throw new Error("tmw_turn_commit_terminal_rewrite_forbidden");
+            }
+            return this.#terminal.preActivationTerminalDigest;
+        }
+        return await preActivationTerminalDigest(Object.freeze({
+            schemaVersion: 3,
+            ...this.#identity,
+            terminal: "committed",
+            reasonCode: null,
+            operationDigest: this.#operationDigest,
+            budgetReceiptDigest,
+            stageDigests: canonicalStageDigests(this.#stages),
+            activationReceiptDigest: null,
+        }));
+    }
+    async #finalize(input) {
+        const reasonCode = input.reasonCode === null
+            ? null
+            : requireTmwIdentifier(input.reasonCode, "turn_commit_reason_code");
+        const budgetReceiptDigest = requireTmwSha256(input.budgetReceiptDigest, "turn_commit_budget_receipt_digest");
+        const activationReceiptDigest = input.activationReceiptDigest === null
+            ? null
+            : requireTmwSha256(input.activationReceiptDigest, "turn_commit_activation_receipt_digest");
+        if (input.terminal === "committed" && activationReceiptDigest === null) {
+            throw new Error("tmw_turn_commit_activation_receipt_required");
+        }
+        if (this.#terminal !== null) {
+            if (this.#terminal.terminal !== input.terminal
+                || this.#terminal.reasonCode !== reasonCode
+                || this.#terminal.budgetReceiptDigest !== budgetReceiptDigest
+                || this.#terminal.activationReceiptDigest !== activationReceiptDigest) {
+                throw new Error("tmw_turn_commit_terminal_rewrite_forbidden");
+            }
+            return this.#terminal;
+        }
+        const body = Object.freeze({
+            schemaVersion: 3,
+            ...this.#identity,
+            terminal: input.terminal,
+            reasonCode,
+            operationDigest: this.#operationDigest,
+            budgetReceiptDigest,
+            stageDigests: canonicalStageDigests(this.#stages),
+            activationReceiptDigest,
+        });
+        const candidate = Object.freeze({
+            ...body,
+            preActivationTerminalDigest: await preActivationTerminalDigest(body),
+        });
+        const outcome = await this.#store.putIfAbsent(this.#identity.operationId, candidate);
+        const stored = outcome.receipt;
+        if (!sameIdentity(this.#identity, stored) || stored.operationDigest !== this.#operationDigest) {
+            throw new Error("tmw_turn_commit_terminal_store_identity_conflict");
+        }
+        if (canonicalTmwJson(stored) !== canonicalTmwJson(candidate)) {
+            throw new Error("tmw_turn_commit_terminal_rewrite_forbidden");
+        }
+        this.#terminal = stored;
+        return stored;
+    }
+}

package/dist/validator.d.ts

@@ -0,0 +1,7 @@
+import { type CanonicalTmwCapabilityRegistryV3 } from "./capability-registry.js";
+import { type TmwResult } from "./diagnostics.js";
+import { type TriggerDocumentV3 } from "./trigger-document-v3.js";
+export interface ValidateTmw3Options {
+    readonly expected_runtime_contract_hash?: string;
+}
+export declare function validateTmw3(value: unknown, registry: CanonicalTmwCapabilityRegistryV3, options?: ValidateTmw3Options): Promise<TmwResult<TriggerDocumentV3>>;

package/dist/validator.js

@@ -0,0 +1,142 @@
+import { capabilityRegistryIndex, isCanonicalTmwCapabilityRegistryV3, } from "./capability-registry.js";
+import { orderTmwDiagnostics, tmwDiagnostic, tmwFailure, tmwSuccess } from "./diagnostics.js";
+import { runtimeContractHashV3 } from "./runtime-contract.js";
+import { allTriggerNodesV3, parseTriggerDocumentV3 } from "./trigger-document-v3.js";
+import { tmwSceneOperationFromEffect } from "./scene-state.js";
+import { isTmwEventLifecycleCapability } from "./event-lifecycle.js";
+import { validateTmwValueGraphV1, validateTmwBoundEffectArgumentsV1, tmwEffectValuePortTypeV1 } from "./value-graph.js";
+export async function validateTmw3(value, registry, options = {}) {
+    const parsed = parseTriggerDocumentV3(value);
+    if (!parsed.ok)
+        return parsed;
+    const document = parsed.value;
+    const diagnostics = [...parsed.diagnostics];
+    if (!isCanonicalTmwCapabilityRegistryV3(registry))
+        return tmwFailure([
+            tmwDiagnostic("capability_registry_untrusted", "$registry", "canonical registry provider required"),
+        ]);
+    const expectedHash = options.expected_runtime_contract_hash ?? await runtimeContractHashV3();
+    if (document.runtime_contract_hash !== expectedHash)
+        diagnostics.push(tmwDiagnostic("runtime_contract_hash_mismatch", "$/runtime_contract_hash", "document runtime contract hash does not match Runtime3"));
+    if (document.registry_version !== registry.registry_version)
+        diagnostics.push(tmwDiagnostic("capability_registry_version_mismatch", "$/registry_version", "document registry version does not match supplied registry"));
+    const capabilityIds = new Set();
+    for (const [index, capability] of registry.capabilities.entries()) {
+        const path = `$registry/capabilities/${index}`;
+        if (capabilityIds.has(capability.capability_id))
+            diagnostics.push(tmwDiagnostic("duplicate_capability_id", `${path}/capability_id`, "capability id must be unique", [capability.capability_id]));
+        capabilityIds.add(capability.capability_id);
+        if (!Number.isSafeInteger(capability.max_invocations_per_turn) || capability.max_invocations_per_turn < 1)
+            diagnostics.push(tmwDiagnostic("capability_budget_invalid", `${path}/max_invocations_per_turn`, "capability budget must be a positive safe integer", [capability.capability_id]));
+    }
+    const nodes = allTriggerNodesV3(document);
+    const nodeIds = new Set();
+    for (const node of nodes) {
+        if (nodeIds.has(node.stable_id))
+            diagnostics.push(tmwDiagnostic("duplicate_stable_id", "$/nodes", "stable_id must be unique across all node kinds", [node.stable_id]));
+        nodeIds.add(node.stable_id);
+    }
+    const registryIndex = capabilityRegistryIndex(registry);
+    const usesValueInput = (expression) => expression.op === "value_input" || (expression.op === "not" ? usesValueInput(expression.value) : (expression.op === "all" || expression.op === "any") && expression.values.some(usesValueInput));
+    const consumers = nodes.map((node) => {
+        const inputs = {};
+        if (node.kind === "condition" && usesValueInput(node.expression))
+            inputs.value = "boolean";
+        if (node.kind === "effect")
+            for (const edge of document.value_graph?.edges.filter((e) => e.to_node === node.stable_id) ?? []) {
+                const capability = registryIndex.get(node.capability_id);
+                const portType = node.capability_id === "variable.set" && edge.to_port === "value" ? edge.value_type : capability && tmwEffectValuePortTypeV1(node.capability_id, edge.to_port, node.arguments, capability.argument_schema);
+                if (portType)
+                    inputs[edge.to_port] = portType;
+                if (Object.hasOwn(node.arguments, edge.to_port))
+                    diagnostics.push(tmwDiagnostic("value_input_inline_conflict", `$/effects/${node.stable_id}/arguments/${edge.to_port}`, "bound value input cannot also have an inline argument"));
+            }
+        return { stable_id: node.stable_id, inputs };
+    });
+    try {
+        validateTmwValueGraphV1(document.value_graph ?? { schema_version: 1, nodes: [], edges: [] }, consumers);
+    }
+    catch (error) {
+        diagnostics.push(tmwDiagnostic("value_graph_invalid", "$/value_graph", error instanceof Error ? error.message : "invalid value graph"));
+    }
+    const effectIdempotencyKeys = new Set();
+    const effectCountsByCapability = new Map();
+    for (const [index, effect] of document.effects.entries()) {
+        const capability = registryIndex.get(effect.capability_id);
+        if (capability === undefined)
+            diagnostics.push(tmwDiagnostic("unknown_capability", `$/effects/${index}/capability_id`, "effect capability is not registered", [effect.stable_id, effect.capability_id]));
+        else if (capability.selector_required && effect.selector === null)
+            diagnostics.push(tmwDiagnostic("capability_selector_required", `$/effects/${index}/selector`, "registered capability requires a selector", [effect.stable_id, effect.capability_id]));
+        const boundPorts = document.value_graph?.edges.filter((edge) => edge.to_node === effect.stable_id).map((edge) => edge.to_port) ?? [];
+        if (capability && (boundPorts.length > 0 || isTmwEventLifecycleCapability(effect.capability_id))) {
+            try {
+                validateTmwBoundEffectArgumentsV1(effect.arguments, boundPorts, capability.argument_schema);
+            }
+            catch (error) {
+                diagnostics.push(tmwDiagnostic("value_effect_arguments_invalid", `$/effects/${index}/arguments`, error instanceof Error ? error.message : "invalid arguments"));
+            }
+        }
+        // 只有未被 value graph 绑定的 eventNodeId 才是编译时可判定的 literal。
+        // 绑定值在运行时求值后仍由 event-lifecycle 检查，因此不能把数据边误判成常量引用。
+        const eventNodeId = effect.arguments.eventNodeId;
+        if (isTmwEventLifecycleCapability(effect.capability_id)
+            && !boundPorts.includes("eventNodeId")
+            && typeof eventNodeId === "string"
+            && !document.events.some((event) => event.stable_id === eventNodeId))
+            diagnostics.push(tmwDiagnostic("event_lifecycle_target_missing", `$/effects/${index}/arguments/eventNodeId`, "event lifecycle effect must reference an event definition in this document", [effect.stable_id, effect.capability_id, eventNodeId]));
+        if (effect.capability_id.startsWith("scene.") && !document.value_graph?.edges.some((edge) => edge.to_node === effect.stable_id)) {
+            try {
+                tmwSceneOperationFromEffect(effect.capability_id, effect.arguments);
+            }
+            catch {
+                diagnostics.push(tmwDiagnostic("scene_effect_arguments_invalid", `$/effects/${index}/arguments`, "scene effect arguments do not satisfy the canonical Scene operation", [effect.stable_id, effect.capability_id]));
+            }
+        }
+        if (effectIdempotencyKeys.has(effect.idempotency_key))
+            diagnostics.push(tmwDiagnostic("duplicate_effect_idempotency_key", `$/effects/${index}/idempotency_key`, "effect idempotency_key must be unique", [effect.stable_id, effect.idempotency_key]));
+        effectIdempotencyKeys.add(effect.idempotency_key);
+        const invocationCount = (effectCountsByCapability.get(effect.capability_id) ?? 0) + 1;
+        effectCountsByCapability.set(effect.capability_id, invocationCount);
+        if (capability !== undefined && invocationCount > capability.max_invocations_per_turn)
+            diagnostics.push(tmwDiagnostic("capability_budget_exceeded", `$/effects/${index}/capability_id`, "document effect count exceeds capability budget", [effect.stable_id, effect.capability_id]));
+        if (capability?.policy === "presentation_only" && effect.execution_policy === "ensure_until")
+            diagnostics.push(tmwDiagnostic("effect_execution_policy_invalid", `$/effects/${index}/execution_policy`, "presentation-only effects cannot use ensure_until", [effect.stable_id]));
+    }
+    const adjacency = new Map();
+    for (const id of nodeIds)
+        adjacency.set(id, []);
+    const edgeIds = new Set();
+    for (const [index, edge] of document.edges.entries()) {
+        const path = `$/edges/${index}`;
+        if (!nodeIds.has(edge.from_stable_id))
+            diagnostics.push(tmwDiagnostic("dangling_edge_source", `${path}/from_stable_id`, "edge source does not exist", [edge.from_stable_id]));
+        if (!nodeIds.has(edge.to_stable_id))
+            diagnostics.push(tmwDiagnostic("dangling_edge_target", `${path}/to_stable_id`, "edge target does not exist", [edge.to_stable_id]));
+        const identity = `${edge.from_stable_id}\0${edge.to_stable_id}`;
+        if (edgeIds.has(identity))
+            diagnostics.push(tmwDiagnostic("duplicate_edge", path, "edge must be unique", [edge.from_stable_id, edge.to_stable_id]));
+        edgeIds.add(identity);
+        adjacency.get(edge.from_stable_id)?.push(edge.to_stable_id);
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            diagnostics.push(tmwDiagnostic("trigger_cycle", "$/edges", "trigger graph must be acyclic", [id]));
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const next of [...(adjacency.get(id) ?? [])].sort())
+            visit(next);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const id of [...nodeIds].sort())
+        visit(id);
+    const ordered = orderTmwDiagnostics(diagnostics);
+    return ordered.some((diagnostic) => diagnostic.severity === "error")
+        ? tmwFailure(ordered)
+        : tmwSuccess(document, ordered);
+}

package/dist/value-graph.d.ts

@@ -0,0 +1,98 @@
+import type { TmwJsonValue } from "./runtime-contract.js";
+import type { TmwSceneStateV1 } from "./scene-state.js";
+export declare const TMW_VALUE_GRAPH_SCHEMA_VERSION: 1;
+export declare const TMW_VALUE_TYPES: readonly ["number", "string", "boolean", "int32", "world_time", "real_timestamp", "duration", "spatial_ref", "string_list", "object_ref"];
+export type TmwValueTypeV1 = typeof TMW_VALUE_TYPES[number];
+/** 可连线的统一玩法对象身份；不允许把 node / edge 的同名 id 混用。 */
+export interface TmwObjectRefV1 {
+    readonly kind: "node" | "edge";
+    readonly id: string;
+}
+export type TmwSceneValueFieldV1 = "world_time" | "location" | "scene_id" | "present_entity_ids";
+export type TmwValueComparisonV1 = "eq" | "neq" | "gt" | "gte" | "lt" | "lte";
+export type TmwValueNodeV1 = Readonly<{
+    kind: "value";
+    stable_id: string;
+}> & (Readonly<{
+    op: "constant";
+    value_type: TmwValueTypeV1;
+    value: TmwJsonValue;
+}> | Readonly<{
+    op: "variable_read";
+    variable_id: string;
+    value_type: TmwValueTypeV1;
+}> | Readonly<{
+    op: "scene_read";
+    field: TmwSceneValueFieldV1;
+}> | Readonly<{
+    op: "state_read";
+    target: "node" | "edge";
+    entity_id: string;
+    field: "unlocked" | "frozen";
+}> | Readonly<{
+    op: "compare";
+    value_type: TmwValueTypeV1;
+    comparison: TmwValueComparisonV1;
+}> | Readonly<{
+    op: "bitwise";
+    operator: "and" | "or" | "xor" | "not" | "shl" | "shr" | "ushr";
+}>);
+export interface TmwValueDataEdgeV1 {
+    readonly from_node: string;
+    readonly from_port: "value";
+    readonly to_node: string;
+    readonly to_port: string;
+    readonly value_type: TmwValueTypeV1;
+}
+export interface TmwValueGraphV1 {
+    readonly schema_version: 1;
+    readonly nodes: readonly TmwValueNodeV1[];
+    readonly edges: readonly TmwValueDataEdgeV1[];
+}
+export interface TmwTypedValueV1 {
+    readonly value_type: TmwValueTypeV1;
+    readonly value: TmwJsonValue;
+}
+export interface TmwValueContextV1 {
+    readonly scene?: TmwSceneStateV1 | null;
+    readonly variables?: Readonly<Record<string, TmwTypedValueV1>>;
+    readonly entity_states?: Readonly<Record<string, Readonly<{
+        kind: "available" | "unavailable" | "frozen";
+        frozen_stack: readonly Readonly<{
+            prev_kind?: "available" | "unavailable";
+        }>[];
+    }>>>;
+}
+export interface TmwValueConsumerV1 {
+    readonly stable_id: string;
+    readonly inputs: Readonly<Record<string, TmwValueTypeV1>>;
+}
+/** 变量身份包含 scope，避免执行局部值遮蔽存档变量。 */
+export declare function tmwValueContextFromSavV1(sav: Readonly<{
+    scene: TmwSceneStateV1 | null;
+    gameplayState?: Readonly<{
+        variables: readonly Readonly<{
+            name: string;
+            scope: string;
+            valueType: string;
+            value: TmwJsonValue;
+        }>[];
+        entity_state_stacks?: TmwValueContextV1["entity_states"];
+    }>;
+}>): TmwValueContextV1;
+export declare function resolveTmwEffectValueArgumentsV1(graph: TmwValueGraphV1 | undefined, targetId: string, args: Readonly<Record<string, TmwJsonValue>>, context: TmwValueContextV1, capabilityId?: string): Readonly<Record<string, TmwJsonValue>>;
+export declare function tmwEffectValuePortTypeV1(capabilityId: string, port: string, args: Readonly<Record<string, TmwJsonValue>>, schema: TmwJsonValue): TmwValueTypeV1 | undefined;
+/** 绑定输入占据声明参数槽；其余 inline 参数仍须通过原 capability schema。 */
+export declare function validateTmwBoundEffectArgumentsV1(args: Readonly<Record<string, TmwJsonValue>>, boundPorts: readonly string[], schema: TmwJsonValue): void;
+export declare function isTmwTypedValueV1(valueType: TmwValueTypeV1, value: unknown): value is TmwJsonValue;
+export declare function isTmwObjectRefV1(value: unknown): value is TmwObjectRefV1 & TmwJsonValue;
+export declare function tmwValueNodePortsV1(node: TmwValueNodeV1): Readonly<{
+    inputs: Readonly<Record<string, TmwValueTypeV1>>;
+    outputs: Readonly<Record<string, TmwValueTypeV1>>;
+}>;
+export declare function parseTmwValueGraphV1(value: unknown): TmwValueGraphV1;
+export declare function validateTmwValueGraphV1(graph: TmwValueGraphV1, consumers?: readonly TmwValueConsumerV1[]): void;
+export declare function readTmwSceneValueV1(scene: TmwSceneStateV1 | null | undefined, field: TmwSceneValueFieldV1): TmwTypedValueV1 | undefined;
+export declare function compareTmwValuesV1(left: TmwJsonValue, right: TmwJsonValue, comparison: TmwValueComparisonV1 | "contains"): boolean | undefined;
+export declare function evaluateTmwValueGraphV1(graph: TmwValueGraphV1, context?: TmwValueContextV1, roots?: readonly string[]): ReadonlyMap<string, TmwTypedValueV1 | undefined>;
+export declare function resolveTmwValueGraphInputsV1(graph: TmwValueGraphV1 | undefined, targetId: string, context?: TmwValueContextV1): Readonly<Record<string, TmwTypedValueV1 | undefined>>;