@world-engines/tmw 0.1.0-alpha.0

package/dist/event-lifecycle.js

@@ -0,0 +1,161 @@
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, tmwSha256Hex } from "./runtime-trace.js";
+import { canonicalTmwAuthorViewProjectionV1 } from "./scene-state.js";
+export const TMW_EVENT_MAX_BROADCAST_COUNT = 256;
+export const TMW_EVENT_MAX_CAUSATION_DEPTH = 32;
+export const TMW_EVENT_MAX_VIEW_VISIBLE_FIELDS = 64;
+const ID = Object.freeze({ type: "string", minLength: 1, maxLength: 512 });
+const TARGET = Object.freeze({ eventNodeId: ID });
+const commandSchema = (properties, required) => Object.freeze({ type: "object", additionalProperties: false, properties, required });
+export const TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS = Object.freeze({
+    "event.create": commandSchema(TARGET, ["eventNodeId"]),
+    "event.delete": commandSchema(TARGET, ["eventNodeId"]),
+    "event.stop": commandSchema(TARGET, ["eventNodeId"]),
+    "event.start": commandSchema({ ...TARGET, count: { type: "integer", minimum: 1, maximum: TMW_EVENT_MAX_BROADCAST_COUNT }, delay: { type: "object", additionalProperties: false, required: ["domain", "value"], properties: { domain: { const: "world_time" }, value: { type: "number", minimum: 0 } } }, payload: { type: "object" }, viewVisiblePayload: { type: "object", maxProperties: TMW_EVENT_MAX_VIEW_VISIBLE_FIELDS, additionalProperties: { type: ["string", "number", "boolean", "null"] } } }, ["eventNodeId", "count", "delay", "payload"]),
+    "event.broadcast": commandSchema({ ...TARGET, count: { type: "integer", minimum: 1, maximum: TMW_EVENT_MAX_BROADCAST_COUNT }, payload: { type: "object" }, viewVisiblePayload: { type: "object", maxProperties: TMW_EVENT_MAX_VIEW_VISIBLE_FIELDS, additionalProperties: { type: ["string", "number", "boolean", "null"] } } }, ["eventNodeId", "count", "payload"]),
+});
+function primitiveRecord(value) {
+    if (value === undefined)
+        return null;
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("tmw_event_view_visible_payload_invalid");
+    const output = Object.create(null);
+    if (Object.keys(value).length > TMW_EVENT_MAX_VIEW_VISIBLE_FIELDS)
+        throw new Error("tmw_event_view_visible_payload_limit_exceeded");
+    for (const [key, item] of Object.entries(value)) {
+        requireTmwIdentifier(key, "event_view_visible_payload_key");
+        if (item !== null && typeof item !== "string" && typeof item !== "boolean" && (typeof item !== "number" || !Number.isFinite(item))) {
+            throw new Error("tmw_event_view_visible_payload_invalid");
+        }
+        output[key] = item;
+    }
+    return Object.freeze(output);
+}
+export function canonicalTmwEventViewVisiblePayload(value) {
+    return primitiveRecord(value);
+}
+export function isTmwEventLifecycleCapability(id) {
+    return Object.hasOwn(TMW_EVENT_CAPABILITY_ARGUMENT_SCHEMAS, id);
+}
+function object(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("tmw_event_lifecycle_object_required");
+    return value;
+}
+export function isTmwEventBroadcastSuspension(value) {
+    return object(value.durablePayload).schema === "tmw3.event-broadcast.v1";
+}
+export function isTmwEventDefinitionActive(nodeId, intents) {
+    const state = latestEventState(nodeId, intents);
+    return state === undefined || (object(state.payload).running === true && object(state.payload).deleted !== true);
+}
+function latestEventState(nodeId, intents) {
+    return intents.filter((intent) => isTmwEventLifecycleCapability(intent.capabilityId)
+        && object(intent.payload).schema === "tmw3.event-state.v1"
+        && object(intent.payload).eventNodeId === nodeId)
+        .sort((left, right) => Number(object(right.payload).generation) - Number(object(left.payload).generation))[0];
+}
+/** 事件定义始终来自已编译 world graph；这里只保存运行态与未来投递，不修改事实 ledger。 */
+export async function reduceTmwEventLifecycle(input) {
+    const intents = new Map(input.intents.map((intent) => [intent.intentId, intent]));
+    let pending = input.pending.filter((entry) => entry.eventId !== input.event.eventId);
+    const cancellationKey = (nodeId) => `tmw3:event-flow:${nodeId}`;
+    const stopped = new Set();
+    const origin = () => Object.freeze({ correlationId: input.event.correlationId, causationId: input.event.eventId, depth: requireTmwSafeInteger((object(input.event.payload).runtimeEventDepth ?? 0), "event_causation_depth", 0) + 1 });
+    const enqueue = async (nodeId, eventId, payload, authorViewProjection, emissionOrigin = origin()) => {
+        const node = input.plan.nodes.find((candidate) => candidate.stable_id === nodeId && candidate.kind === "event");
+        if (node === undefined)
+            throw new Error("tmw_event_definition_no_match");
+        if (node.effective_time.domain !== "world_time" || input.event.coordinates.worldTime === null)
+            throw new Error("tmw_event_broadcast_world_clock_required");
+        if (pending.some((entry) => entry.eventId === eventId))
+            return;
+        const depth = requireTmwSafeInteger(emissionOrigin.depth, "event_causation_depth", 1);
+        if (depth > TMW_EVENT_MAX_CAUSATION_DEPTH)
+            throw new Error("tmw_event_causation_depth_exceeded");
+        const body = Object.freeze({ ...object(payload), runtimeEventNodeId: nodeId, runtimeEventDepth: depth, correlationId: emissionOrigin.correlationId, causationId: emissionOrigin.causationId });
+        pending.push(Object.freeze({ eventId, eventType: String(object(node.canonical_payload).event_type), logicalSeq: input.event.coordinates.logicalSeq, worldTime: input.event.coordinates.worldTime, crossingDirection: "forward", payload: body, payloadHash: await tmwSha256Hex(canonicalTmwJson(body)), commitReceiptDigest: input.event.commitReceiptDigest,
+            ...(authorViewProjection === undefined ? {} : { authorViewProjection }),
+        }));
+    };
+    for (const effect of input.effects) {
+        if (!isTmwEventLifecycleCapability(effect.capabilityId))
+            continue;
+        const args = object(effect.input);
+        const nodeId = requireTmwIdentifier(args.eventNodeId, "event_lifecycle_node_id");
+        if (!input.plan.nodes.some((node) => node.kind === "event" && node.stable_id === nodeId))
+            throw new Error("tmw_event_definition_no_match");
+        const key = `tmw3:event-state:${await tmwSha256Hex(canonicalTmwJson([input.event.eventId, effect.effectId]))}`;
+        const prior = latestEventState(nodeId, [...intents.values()]);
+        const deleted = prior !== undefined && object(prior.payload).deleted === true;
+        const saveState = (state, isDeleted) => intents.set(key, Object.freeze({
+            intentId: key, epoch: input.event.epoch, runtimeGeneration: 3, runtimeContractHash: input.event.runtimeContractHash, artifactDigest: input.event.artifactDigest, sourceRevision: input.event.sourceRevision, timelineRevision: input.event.timelineRevision,
+            turnId: input.event.correlationId, operationId: `tmw3:event:${input.event.eventId}`, capabilityId: effect.capabilityId, idempotencyKey: `${input.event.eventId}:${effect.effectId}`, conflictKey: cancellationKey(nodeId), priority: effect.priority, state: "satisfied", selectorSnapshotHash: input.event.payloadHash,
+            payload: Object.freeze({ schema: "tmw3.event-state.v1", eventNodeId: nodeId, deleted: isDeleted, running: state === "active", generation: prior === undefined ? 1 : Number(object(prior.payload).generation) + 1 }), lastReceiptDigest: input.event.commitReceiptDigest, reasonCode: null,
+        }));
+        if (effect.capabilityId === "event.create") {
+            saveState("active", false);
+            continue;
+        }
+        if (effect.capabilityId === "event.stop" || effect.capabilityId === "event.delete") {
+            input.scheduler.cancel(cancellationKey(nodeId));
+            stopped.add(nodeId);
+            pending = pending.filter((entry) => entry.payload.runtimeEventNodeId !== nodeId);
+            saveState("cancelled", effect.capabilityId === "event.delete" || deleted);
+            continue;
+        }
+        if (deleted)
+            throw new Error("tmw_event_definition_deleted");
+        const count = requireTmwSafeInteger(args.count, "event_broadcast_count", 1);
+        if (count > TMW_EVENT_MAX_BROADCAST_COUNT)
+            throw new Error("tmw_event_broadcast_count_exceeded");
+        const payload = canonicalTmwJsonValue(object(args.payload), "event_broadcast_payload");
+        const viewVisiblePayload = primitiveRecord(args.viewVisiblePayload);
+        const authorViewProjection = viewVisiblePayload === null ? undefined : Object.freeze({ schema: "tmw3.author-view-event.v1", saveId: input.event.scope.saveId, artifactDigest: input.event.artifactDigest, sourceEventId: input.event.eventId, sourceCommitReceiptDigest: input.event.commitReceiptDigest, viewVisiblePayload });
+        let delay = 0;
+        if (effect.capabilityId === "event.start") {
+            const temporal = object(args.delay);
+            if (temporal.domain !== "world_time")
+                throw new Error("tmw_event_delay_clock_not_produced");
+            if (typeof temporal.value !== "number" || !Number.isFinite(temporal.value) || temporal.value < 0)
+                throw new Error("tmw_event_delay_invalid");
+            delay = temporal.value;
+        }
+        if (input.event.coordinates.worldTime === null)
+            throw new Error("tmw_event_broadcast_world_clock_required");
+        for (let index = 0; index < count; index++) {
+            const eventId = `tmw3:broadcast:${await tmwSha256Hex(canonicalTmwJson([input.event.eventId, effect.effectId, index]))}`;
+            if (delay === 0) {
+                await enqueue(nodeId, eventId, payload, authorViewProjection);
+                continue;
+            }
+            const due = input.event.coordinates.worldTime + delay * (index + 1);
+            if (!Number.isFinite(due))
+                throw new Error("tmw_event_delay_invalid");
+            input.scheduler.schedule({ suspensionId: eventId, epoch: input.event.epoch, runtimeGeneration: 3, runtimeContractHash: input.event.runtimeContractHash, artifactDigest: input.event.artifactDigest, sourceRevision: input.event.sourceRevision, timelineRevision: input.event.timelineRevision, scope: input.event.scope,
+                effectiveTime: { domain: "world_time", effective_value: input.event.coordinates.worldTime, due_value: due, crossing_policy: "forward_only", real_time_clock: null, wall_clock_policy: null }, resumeNodeId: nodeId, correlationId: input.event.correlationId, cancellationKey: cancellationKey(nodeId), createdSnapshotHash: input.event.payloadHash,
+                durablePayload: { schema: "tmw3.event-broadcast.v1", payload, origin: origin(), ...(authorViewProjection === undefined ? {} : { authorViewProjection }) },
+            });
+        }
+        saveState("active", false);
+    }
+    for (const suspension of input.dueBroadcasts) {
+        if (stopped.has(suspension.resumeNodeId))
+            continue;
+        const durable = object(suspension.durablePayload);
+        const emissionOrigin = object(durable.origin);
+        const payload = durable.payload;
+        const { correlationId, causationId, depth } = emissionOrigin;
+        if (payload === undefined
+            || typeof correlationId !== "string"
+            || typeof causationId !== "string"
+            || typeof depth !== "number") {
+            throw new Error("tmw_event_broadcast_suspension_invalid");
+        }
+        await enqueue(suspension.resumeNodeId, suspension.suspensionId, payload, canonicalTmwAuthorViewProjectionV1(durable.authorViewProjection), {
+            correlationId: requireTmwIdentifier(correlationId, "event_origin_correlation_id"),
+            causationId: requireTmwIdentifier(causationId, "event_origin_causation_id"),
+            depth: requireTmwSafeInteger(depth, "event_causation_depth", 1),
+        });
+    }
+    return Object.freeze({ intents: Object.freeze([...intents.values()]), pending: Object.freeze(pending) });
+}

package/dist/evidence.d.ts

@@ -0,0 +1,37 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type TmwJsonValue } from "./runtime-trace.js";
+export type EvidenceKind = "committed_event" | "recall_readback" | "hard_fact";
+export interface EvidenceItemV3 {
+    readonly evidenceRef: string;
+    readonly kind: EvidenceKind;
+    readonly sourceDigest: string;
+    readonly value: TmwJsonValue;
+}
+export interface EvidenceEnvelopeV3 {
+    readonly schemaVersion: 3;
+    readonly epoch: number;
+    readonly runtimeGeneration: typeof TMW_RUNTIME_GENERATION;
+    readonly runtimeContractHash: string;
+    readonly artifactDigest: string;
+    readonly scenarioId: string;
+    readonly sourceRevision: string;
+    readonly timelineRevision: string;
+    readonly turnId: string;
+    readonly operationId: string;
+    readonly intentId: string;
+    readonly idempotencyKey: string;
+    readonly budgetReceiptDigest: string;
+    readonly predicateKeys: ReadonlyArray<string>;
+    readonly items: ReadonlyArray<EvidenceItemV3>;
+    readonly evidenceSetDigest: string;
+}
+export interface EvidenceAssemblyInput extends Omit<EvidenceEnvelopeV3, "schemaVersion" | "runtimeGeneration" | "items" | "evidenceSetDigest"> {
+    readonly candidates: ReadonlyArray<EvidenceItemV3>;
+    readonly allowedEvidenceRefs: ReadonlyArray<string>;
+    readonly maxItems: number;
+    readonly maxCanonicalBytes: number;
+    readonly evidenceSetDigest: string;
+}
+export declare function assembleEvidenceEnvelope(input: EvidenceAssemblyInput): EvidenceEnvelopeV3;
+export declare function verifyEvidenceEnvelopeDigest(envelope: EvidenceEnvelopeV3): Promise<EvidenceEnvelopeV3>;
+export declare function createEvidenceEnvelope(input: Omit<EvidenceAssemblyInput, "evidenceSetDigest">): Promise<EvidenceEnvelopeV3>;

package/dist/evidence.js

@@ -0,0 +1,92 @@
+import { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { canonicalTmwJson, canonicalTmwJsonValue, requireTmwIdentifier, requireTmwSafeInteger, requireTmwSha256, tmwSha256Hex, } from "./runtime-trace.js";
+function canonicalItem(input) {
+    if (input.kind !== "committed_event"
+        && input.kind !== "recall_readback"
+        && input.kind !== "hard_fact") {
+        throw new Error("tmw_evidence_kind_invalid");
+    }
+    return Object.freeze({
+        evidenceRef: requireTmwIdentifier(input.evidenceRef, "evidence_ref"),
+        kind: input.kind,
+        sourceDigest: requireTmwSha256(input.sourceDigest, "evidence_source_digest"),
+        value: canonicalTmwJsonValue(input.value, "evidence_value"),
+    });
+}
+export function assembleEvidenceEnvelope(input) {
+    const maxItems = requireTmwSafeInteger(input.maxItems, "evidence_max_items", 1);
+    const maxCanonicalBytes = requireTmwSafeInteger(input.maxCanonicalBytes, "evidence_max_bytes", 1);
+    const allowed = new Set(input.allowedEvidenceRefs.map((ref) => requireTmwIdentifier(ref, "evidence_allowed_ref")));
+    const byRef = new Map();
+    for (const candidateInput of input.candidates) {
+        const candidate = canonicalItem(candidateInput);
+        if (!allowed.has(candidate.evidenceRef))
+            continue;
+        const previous = byRef.get(candidate.evidenceRef);
+        if (previous !== undefined && (previous.sourceDigest !== candidate.sourceDigest
+            || canonicalTmwJson(previous.value) !== canonicalTmwJson(candidate.value))) {
+            throw new Error("tmw_evidence_ref_conflict");
+        }
+        byRef.set(candidate.evidenceRef, candidate);
+    }
+    const missing = [...allowed].filter((ref) => !byRef.has(ref));
+    if (missing.length > 0)
+        throw new Error("tmw_evidence_allowed_ref_missing");
+    const items = [...byRef.values()].sort((left, right) => left.evidenceRef < right.evidenceRef ? -1 : left.evidenceRef > right.evidenceRef ? 1 : 0);
+    if (items.length > maxItems)
+        throw new Error("tmw_evidence_item_budget_exhausted");
+    if (new TextEncoder().encode(canonicalTmwJson(items)).byteLength > maxCanonicalBytes) {
+        throw new Error("tmw_evidence_byte_budget_exhausted");
+    }
+    const predicateKeys = Object.freeze([...new Set(input.predicateKeys.map((key) => requireTmwIdentifier(key, "evidence_predicate_key")))].sort());
+    return Object.freeze({
+        schemaVersion: 3,
+        epoch: requireTmwSafeInteger(input.epoch, "evidence_epoch", 1),
+        runtimeGeneration: TMW_RUNTIME_GENERATION,
+        runtimeContractHash: requireTmwSha256(input.runtimeContractHash, "evidence_contract_hash"),
+        artifactDigest: requireTmwSha256(input.artifactDigest, "evidence_artifact_digest"),
+        scenarioId: requireTmwIdentifier(input.scenarioId, "evidence_scenario_id"),
+        sourceRevision: requireTmwIdentifier(input.sourceRevision, "evidence_source_revision"),
+        timelineRevision: requireTmwIdentifier(input.timelineRevision, "evidence_timeline_revision"),
+        turnId: requireTmwIdentifier(input.turnId, "evidence_turn_id"),
+        operationId: requireTmwIdentifier(input.operationId, "evidence_operation_id"),
+        intentId: requireTmwIdentifier(input.intentId, "evidence_intent_id"),
+        idempotencyKey: requireTmwIdentifier(input.idempotencyKey, "evidence_idempotency_key"),
+        budgetReceiptDigest: requireTmwSha256(input.budgetReceiptDigest, "evidence_budget_receipt_digest"),
+        predicateKeys,
+        items: Object.freeze(items),
+        evidenceSetDigest: requireTmwSha256(input.evidenceSetDigest, "evidence_set_digest"),
+    });
+}
+export async function verifyEvidenceEnvelopeDigest(envelope) {
+    const canonical = assembleEvidenceEnvelope({
+        epoch: envelope.epoch,
+        runtimeContractHash: envelope.runtimeContractHash,
+        artifactDigest: envelope.artifactDigest,
+        scenarioId: envelope.scenarioId,
+        sourceRevision: envelope.sourceRevision,
+        timelineRevision: envelope.timelineRevision,
+        turnId: envelope.turnId,
+        operationId: envelope.operationId,
+        intentId: envelope.intentId,
+        idempotencyKey: envelope.idempotencyKey,
+        budgetReceiptDigest: envelope.budgetReceiptDigest,
+        predicateKeys: envelope.predicateKeys,
+        candidates: envelope.items,
+        allowedEvidenceRefs: envelope.items.map((item) => item.evidenceRef),
+        maxItems: envelope.items.length,
+        maxCanonicalBytes: new TextEncoder().encode(canonicalTmwJson(envelope.items)).byteLength,
+        evidenceSetDigest: envelope.evidenceSetDigest,
+    });
+    const { evidenceSetDigest: _claimedDigest, ...digestImage } = canonical;
+    const computed = await tmwSha256Hex(canonicalTmwJson(digestImage));
+    if (computed !== canonical.evidenceSetDigest)
+        throw new Error("tmw_evidence_set_digest_mismatch");
+    return canonical;
+}
+export async function createEvidenceEnvelope(input) {
+    const provisional = assembleEvidenceEnvelope({ ...input, evidenceSetDigest: "0".repeat(64) });
+    const { evidenceSetDigest: _placeholder, ...digestImage } = provisional;
+    const evidenceSetDigest = await tmwSha256Hex(canonicalTmwJson(digestImage));
+    return Object.freeze({ ...provisional, evidenceSetDigest });
+}

package/dist/gameplay-state.d.ts

@@ -0,0 +1,127 @@
+import { type TmwJsonValue } from "./runtime-trace.js";
+import { type TmwValueTypeV1 } from "./value-graph.js";
+export type TmwVariableScope = "save" | "execution";
+export type TmwVariableType = TmwValueTypeV1 | "json";
+export interface TmwVariableV1 {
+    readonly name: string;
+    readonly scope: TmwVariableScope;
+    readonly valueType: TmwVariableType;
+    readonly value: TmwJsonValue;
+}
+/** 对齐 WASM SaveSidecar.EntityStateEntry，不以 view_access 或 enabled 表示玩法解锁。 */
+export interface TmwEntityStateV1 {
+    readonly active_state_id: string;
+    readonly kind: "available" | "unavailable" | "frozen";
+    readonly frozen_stack: readonly Readonly<{
+        source_trigger_id: string;
+        prev_state_id?: string;
+        prev_kind?: "available" | "unavailable";
+    }>[];
+}
+export interface TmwGameplayStateV1 {
+    readonly schemaVersion: 1;
+    readonly variables: readonly TmwVariableV1[];
+    readonly entity_state_stacks: Readonly<Record<string, TmwEntityStateV1>>;
+}
+/** 新统一算子只拥有自己的冻结来源；绝不清除旧算子留下的其它来源。 */
+export declare const TMW_OBJECT_STATE_FREEZE_SOURCE_ID: "tmw.object_state";
+export declare const TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS: Readonly<{
+    "variable.create": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "variable.set": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "variable.delete": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "node.set_unlock": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "edge.set_unlock": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "node.freeze": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "node.unfreeze": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "edge.freeze": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "edge.unfreeze": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "object.set_frozen": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+    "object.set_unlock": {
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+        properties: Record<string, unknown>;
+    };
+}>;
+export declare function emptyTmwGameplayStateV1(): TmwGameplayStateV1;
+/** 作者试玩世界的初始显隐投影；显式玩法状态优先，不从 UI 访问权限或蓝图 enabled 推断。 */
+export declare function initialTmwGameplayStateFromWorldV1(world: Readonly<Record<string, unknown>>): TmwGameplayStateV1;
+export declare function canonicalTmwGameplayStateV1(input: TmwGameplayStateV1): TmwGameplayStateV1;
+export declare function readTmwVariableV1(state: TmwGameplayStateV1, name: string, scope: TmwVariableScope): TmwVariableV1;
+export declare function readTmwEntityStateV1(state: TmwGameplayStateV1, target: "node" | "edge", id: string): TmwEntityStateV1;
+export declare function readTmwUnlockV1(state: TmwGameplayStateV1, target: "node" | "edge", id: string): boolean;
+export declare function persistentTmwGameplayStateV1(state: TmwGameplayStateV1): TmwGameplayStateV1;
+/** 返回 null 表示非玩法状态 capability；冻结期间的写入是成功的 no-op，不延迟重放。 */
+export declare function reduceTmwGameplayEffectV1(current: TmwGameplayStateV1, capabilityId: string, input: unknown): TmwGameplayStateV1 | null;
+export declare function reduceTmwGameplayEffectsV1(current: TmwGameplayStateV1, effects: readonly Readonly<{
+    capabilityId: string;
+    input: unknown;
+}>[]): TmwGameplayStateV1;
+/** 旧属性写入口必须先经过这个门，不能通过属性路径旁路冻结。 */
+export declare function tmwWorldAttributeVisibilityOperationV1(effect: Readonly<{
+    capabilityId: string;
+    input: unknown;
+    selector?: unknown;
+}>): Readonly<{
+    nodeId: string;
+    unlocked: boolean;
+}> | null;
+/** 所有 effect 共享有序暂存态；返回实际执行集合，忽略的冻结写入不进入外部 WAL。 */
+export declare function prepareTmwGameplayEffectsV1<T extends Readonly<{
+    capabilityId: string;
+    input: unknown;
+    selector?: unknown;
+}>>(current: TmwGameplayStateV1, effects: readonly T[]): Readonly<{
+    state: TmwGameplayStateV1;
+    effects: readonly T[];
+}>;

package/dist/gameplay-state.js

@@ -0,0 +1,214 @@
+import { canonicalTmwJsonValue, requireTmwIdentifier } from "./runtime-trace.js";
+import { isTmwObjectRefV1, isTmwTypedValueV1, TMW_VALUE_TYPES } from "./value-graph.js";
+const idSchema = { type: "string", minLength: 1, maxLength: 512 };
+const scopeSchema = { enum: ["save", "execution"] };
+const schema = (properties) => ({ type: "object", additionalProperties: false, required: Object.keys(properties), properties });
+const objectRefSchema = Object.freeze({ type: "object", tmw_value_type: "object_ref", additionalProperties: false, required: ["kind", "id"], properties: { kind: { enum: ["node", "edge"] }, id: idSchema } });
+/** 新统一算子只拥有自己的冻结来源；绝不清除旧算子留下的其它来源。 */
+export const TMW_OBJECT_STATE_FREEZE_SOURCE_ID = "tmw.object_state";
+export const TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS = Object.freeze({
+    "variable.create": schema({ name: idSchema, scope: scopeSchema, valueType: { enum: [...TMW_VALUE_TYPES, "json"] }, value: {} }),
+    "variable.set": schema({ name: idSchema, scope: scopeSchema, value: {} }),
+    "variable.delete": schema({ name: idSchema, scope: scopeSchema }),
+    "node.set_unlock": schema({ nodeId: idSchema, unlocked: { type: "boolean" } }),
+    "edge.set_unlock": schema({ edgeId: idSchema, unlocked: { type: "boolean" } }),
+    "node.freeze": schema({ nodeId: idSchema, sourceId: idSchema }),
+    "node.unfreeze": schema({ nodeId: idSchema, sourceId: idSchema }),
+    "edge.freeze": schema({ edgeId: idSchema, sourceId: idSchema }),
+    "edge.unfreeze": schema({ edgeId: idSchema, sourceId: idSchema }),
+    "object.set_frozen": schema({ object: objectRefSchema, frozen: { type: "boolean" } }),
+    "object.set_unlock": schema({ object: objectRefSchema, unlocked: { type: "boolean" } }),
+});
+function valueForType(type, value) {
+    if (type !== "json" && !TMW_VALUE_TYPES.includes(type))
+        throw new Error("tmw_variable_type_invalid");
+    const canonical = canonicalTmwJsonValue(value, "variable_value");
+    if (type !== "json" && !isTmwTypedValueV1(type, canonical))
+        throw new Error("tmw_variable_value_type_mismatch");
+    return canonical;
+}
+function scopeOf(value) {
+    if (value !== "save" && value !== "execution")
+        throw new Error("tmw_variable_scope_invalid");
+    return value;
+}
+export function emptyTmwGameplayStateV1() {
+    return Object.freeze({ schemaVersion: 1, variables: Object.freeze([]), entity_state_stacks: Object.freeze({}) });
+}
+/** 作者试玩世界的初始显隐投影；显式玩法状态优先，不从 UI 访问权限或蓝图 enabled 推断。 */
+export function initialTmwGameplayStateFromWorldV1(world) {
+    if (world.gameplayState !== undefined)
+        return canonicalTmwGameplayStateV1(world.gameplayState);
+    let state = emptyTmwGameplayStateV1();
+    for (const [field, target] of [["entities", "node"], ["relations", "edge"]]) {
+        const records = world[field];
+        if (!records || typeof records !== "object" || Array.isArray(records))
+            continue;
+        for (const [id, raw] of Object.entries(records)) {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                continue;
+            const record = raw;
+            const initial = record.unlocked ?? record.visible ?? (record.kind === "available" ? true : record.kind === "unavailable" ? false : undefined);
+            if (initial === undefined)
+                continue;
+            if (typeof initial !== "boolean")
+                throw new Error("tmw_initial_visibility_invalid");
+            state = reduceTmwGameplayEffectV1(state, `${target}.set_unlock`, { [target === "node" ? "nodeId" : "edgeId"]: id, unlocked: initial });
+        }
+    }
+    return state;
+}
+export function canonicalTmwGameplayStateV1(input) {
+    if (!input || input.schemaVersion !== 1 || !Array.isArray(input.variables)
+        || !input.entity_state_stacks || typeof input.entity_state_stacks !== "object" || Array.isArray(input.entity_state_stacks))
+        throw new Error("tmw_gameplay_state_invalid");
+    const variables = input.variables.map((variable) => Object.freeze({
+        name: requireTmwIdentifier(variable.name, "variable_name"), scope: scopeOf(variable.scope),
+        valueType: variable.valueType, value: valueForType(variable.valueType, variable.value),
+    })).sort((a, b) => `${a.scope}:${a.name}`.localeCompare(`${b.scope}:${b.name}`));
+    if (new Set(variables.map((v) => `${v.scope}:${v.name}`)).size !== variables.length)
+        throw new Error("tmw_variable_duplicate");
+    const entries = Object.entries(input.entity_state_stacks).sort(([a], [b]) => a.localeCompare(b)).map(([ref, state]) => {
+        if (!/^(node|edge):.+$/u.test(ref) || !state || !["available", "unavailable", "frozen"].includes(state.kind)
+            || typeof state.active_state_id !== "string" || !Array.isArray(state.frozen_stack)
+            || (state.kind === "frozen") !== (state.frozen_stack.length > 0))
+            throw new Error("tmw_entity_state_invalid");
+        const stack = state.frozen_stack.map((entry, index) => {
+            const source_trigger_id = requireTmwIdentifier(entry.source_trigger_id, "freeze_source");
+            if (index === 0 && (entry.prev_kind !== "available" && entry.prev_kind !== "unavailable"))
+                throw new Error("tmw_entity_freeze_preimage_missing");
+            return Object.freeze({ source_trigger_id, ...(entry.prev_state_id === undefined ? {} : { prev_state_id: entry.prev_state_id }), ...(entry.prev_kind === undefined ? {} : { prev_kind: entry.prev_kind }) });
+        });
+        if (new Set(stack.map((s) => s.source_trigger_id)).size !== stack.length)
+            throw new Error("tmw_freeze_source_duplicate");
+        return [ref, Object.freeze({ active_state_id: state.active_state_id, kind: state.kind, frozen_stack: Object.freeze(stack) })];
+    });
+    return Object.freeze({ schemaVersion: 1, variables: Object.freeze(variables), entity_state_stacks: Object.freeze(Object.fromEntries(entries)) });
+}
+export function readTmwVariableV1(state, name, scope) {
+    const result = state.variables.find((item) => item.name === name && item.scope === scopeOf(scope));
+    if (!result)
+        throw new Error("tmw_variable_missing");
+    return result;
+}
+export function readTmwEntityStateV1(state, target, id) {
+    requireTmwIdentifier(id, "entity_state_id");
+    return state.entity_state_stacks[`${target}:${id}`] ?? Object.freeze({ active_state_id: "", kind: "available", frozen_stack: Object.freeze([]) });
+}
+export function readTmwUnlockV1(state, target, id) {
+    const entry = readTmwEntityStateV1(state, target, id);
+    return (entry.kind === "frozen" ? entry.frozen_stack[0]?.prev_kind : entry.kind) === "available";
+}
+function objectRefFromGameplayEffect(value) {
+    if (!isTmwObjectRefV1(value))
+        throw new Error("tmw_object_ref_invalid");
+    return Object.freeze({ kind: value.kind, id: requireTmwIdentifier(value.id, "object_ref_id") });
+}
+export function persistentTmwGameplayStateV1(state) {
+    return canonicalTmwGameplayStateV1({ ...state, variables: state.variables.filter((v) => v.scope === "save") });
+}
+/** 返回 null 表示非玩法状态 capability；冻结期间的写入是成功的 no-op，不延迟重放。 */
+export function reduceTmwGameplayEffectV1(current, capabilityId, input) {
+    if (!Object.hasOwn(TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS, capabilityId))
+        return null;
+    const args = canonicalTmwJsonValue(input, "gameplay_effect");
+    if (!args || typeof args !== "object" || Array.isArray(args))
+        throw new Error("tmw_gameplay_arguments_invalid");
+    const expected = TMW_GAMEPLAY_CAPABILITY_ARGUMENT_SCHEMAS[capabilityId].required;
+    if (Object.keys(args).sort().join() !== [...expected].sort().join())
+        throw new Error("tmw_gameplay_arguments_invalid");
+    const state = canonicalTmwGameplayStateV1(current);
+    if (capabilityId.startsWith("variable.")) {
+        const name = requireTmwIdentifier(args.name, "variable_name");
+        const scope = scopeOf(args.scope);
+        const found = state.variables.find((v) => v.name === name && v.scope === scope);
+        const rest = state.variables.filter((v) => v !== found);
+        if (capabilityId === "variable.create") {
+            if (found)
+                throw new Error("tmw_variable_duplicate");
+            return canonicalTmwGameplayStateV1({ ...state, variables: [...rest, { name, scope, valueType: args.valueType, value: args.value }] });
+        }
+        if (!found)
+            throw new Error("tmw_variable_missing");
+        return canonicalTmwGameplayStateV1({ ...state, variables: capabilityId === "variable.delete" ? rest : [...rest, { ...found, value: valueForType(found.valueType, args.value) }] });
+    }
+    const objectRef = capabilityId.startsWith("object.") ? objectRefFromGameplayEffect(args.object) : null;
+    const target = objectRef?.kind ?? (capabilityId.startsWith("edge.") ? "edge" : "node");
+    const id = objectRef?.id ?? requireTmwIdentifier((target === "node" ? args.nodeId : args.edgeId), "entity_state_id");
+    const entry = readTmwEntityStateV1(state, target, id);
+    let next = entry;
+    if (capabilityId.endsWith("set_unlock")) {
+        if (typeof args.unlocked !== "boolean")
+            throw new Error("tmw_unlock_boolean_required");
+        if (entry.kind === "frozen")
+            return state;
+        next = { ...entry, kind: args.unlocked ? "available" : "unavailable" };
+    }
+    else {
+        const source = capabilityId === "object.set_frozen" ? TMW_OBJECT_STATE_FREEZE_SOURCE_ID : requireTmwIdentifier(args.sourceId, "freeze_source");
+        const freeze = capabilityId === "object.set_frozen" ? args.frozen : capabilityId === "node.freeze" || capabilityId === "edge.freeze";
+        if (typeof freeze !== "boolean")
+            throw new Error("tmw_freeze_boolean_required");
+        if (freeze) {
+            if (entry.frozen_stack.some((item) => item.source_trigger_id === source))
+                return state;
+            next = { ...entry, kind: "frozen", frozen_stack: [...entry.frozen_stack, { source_trigger_id: source, ...(entry.kind === "frozen" ? {} : { prev_kind: entry.kind, prev_state_id: entry.active_state_id }) }] };
+        }
+        else {
+            const index = entry.frozen_stack.findIndex((item) => item.source_trigger_id === source);
+            if (index < 0)
+                return state;
+            const removed = entry.frozen_stack[index];
+            const stack = entry.frozen_stack.filter((_, i) => i !== index);
+            if (stack.length === 0)
+                next = { ...entry, kind: removed.prev_kind, active_state_id: removed.prev_state_id ?? entry.active_state_id, frozen_stack: [] };
+            else {
+                if (index === 0)
+                    stack[0] = { ...stack[0], prev_kind: removed.prev_kind, prev_state_id: removed.prev_state_id ?? "" };
+                next = { ...entry, frozen_stack: stack };
+            }
+        }
+    }
+    return canonicalTmwGameplayStateV1({ ...state, entity_state_stacks: { ...state.entity_state_stacks, [`${target}:${id}`]: next } });
+}
+export function reduceTmwGameplayEffectsV1(current, effects) {
+    return effects.reduce((state, effect) => reduceTmwGameplayEffectV1(state, effect.capabilityId, effect.input) ?? state, current);
+}
+/** 旧属性写入口必须先经过这个门，不能通过属性路径旁路冻结。 */
+export function tmwWorldAttributeVisibilityOperationV1(effect) {
+    if (effect.capabilityId !== "world.set_attribute")
+        return null;
+    const args = effect.input;
+    const selector = effect.selector;
+    const path = Array.isArray(args?.path) ? args.path.join(".") : args?.path;
+    if (path !== "unlocked" && path !== "visible" && path !== "visibility" && path !== "kind")
+        return null;
+    if (selector?.op !== "entity_id")
+        throw new Error("tmw_visibility_entity_selector_required");
+    const nodeId = requireTmwIdentifier(selector.entity_id, "visibility_node_id");
+    if (path === "kind") {
+        if (args.value !== "available" && args.value !== "unavailable")
+            throw new Error("tmw_visibility_kind_invalid");
+        return { nodeId, unlocked: args.value === "available" };
+    }
+    if (typeof args.value !== "boolean")
+        throw new Error("tmw_visibility_boolean_required");
+    return { nodeId, unlocked: args.value };
+}
+/** 所有 effect 共享有序暂存态；返回实际执行集合，忽略的冻结写入不进入外部 WAL。 */
+export function prepareTmwGameplayEffectsV1(current, effects) {
+    let state = current;
+    const accepted = [];
+    for (const effect of effects) {
+        const visibility = tmwWorldAttributeVisibilityOperationV1(effect);
+        if (visibility !== null) {
+            if (readTmwEntityStateV1(state, "node", visibility.nodeId).kind === "frozen")
+                continue;
+            state = reduceTmwGameplayEffectV1(state, "node.set_unlock", visibility);
+        }
+        else
+            state = reduceTmwGameplayEffectV1(state, effect.capabilityId, effect.input) ?? state;
+        accepted.push(effect);
+    }
+    return Object.freeze({ state, effects: Object.freeze(accepted) });
+}