@world-engines/tmw 0.1.0-alpha.0

package/dist/value-graph.js

@@ -0,0 +1,318 @@
+import { canonicalTmwJson } from "./runtime-contract.js";
+export const TMW_VALUE_GRAPH_SCHEMA_VERSION = 1;
+export const TMW_VALUE_TYPES = ["number", "string", "boolean", "int32", "world_time", "real_timestamp", "duration", "spatial_ref", "string_list", "object_ref"];
+/** 变量身份包含 scope，避免执行局部值遮蔽存档变量。 */
+export function tmwValueContextFromSavV1(sav) {
+    const variables = Object.create(null);
+    for (const variable of sav.gameplayState?.variables ?? []) {
+        if (type(variable.valueType))
+            variables[`${variable.scope}:${variable.name}`] = { value_type: variable.valueType, value: variable.value };
+    }
+    return Object.freeze({ scene: sav.scene, variables: Object.freeze(variables), ...(sav.gameplayState?.entity_state_stacks === undefined ? {} : { entity_states: sav.gameplayState.entity_state_stacks }) });
+}
+export function resolveTmwEffectValueArgumentsV1(graph, targetId, args, context, capabilityId) {
+    const resolved = resolveTmwValueGraphInputsV1(graph, targetId, context);
+    const output = { ...args };
+    for (const [port, value] of Object.entries(resolved)) {
+        if (value === undefined)
+            throw new Error("tmw_value_effect_input_unavailable");
+        if (capabilityId === "variable.set" && port === "value") {
+            const variable = context.variables?.[`${args.scope}:${args.name}`];
+            if (!variable || variable.value_type !== value.value_type)
+                throw new Error("tmw_value_variable_type_mismatch");
+        }
+        if (Object.hasOwn(output, port))
+            throw new Error("tmw_value_input_inline_conflict");
+        output[port] = value.value;
+    }
+    return Object.freeze(output);
+}
+export function tmwEffectValuePortTypeV1(capabilityId, port, args, schema) {
+    if (capabilityId.startsWith("scene.") && port === "worldTime")
+        return "world_time";
+    if (capabilityId.startsWith("scene.") && port === "spatialRef")
+        return "spatial_ref";
+    if (port === "value" && type(args.valueType))
+        return args.valueType;
+    const properties = obj(schema) && obj(schema.properties) ? schema.properties : {};
+    const property = properties[port];
+    if (!obj(property))
+        return undefined;
+    if (type(property.tmw_value_type))
+        return property.tmw_value_type;
+    if (property.type === "string" || property.type === "number" || property.type === "boolean")
+        return property.type;
+    if (property.type === "integer")
+        return "int32";
+    if (property.type === "array" && obj(property.items) && property.items.type === "string")
+        return "string_list";
+    return undefined;
+}
+/** 绑定输入占据声明参数槽；其余 inline 参数仍须通过原 capability schema。 */
+export function validateTmwBoundEffectArgumentsV1(args, boundPorts, schema) {
+    if (!obj(schema) || !obj(schema.properties))
+        throw new Error("tmw_value_effect_schema_required");
+    const names = [...Object.keys(args), ...boundPorts];
+    if (schema.additionalProperties === false && names.some((name) => !Object.hasOwn(schema.properties, name)))
+        throw new Error("tmw_value_effect_argument_unknown");
+    if (Array.isArray(schema.required) && schema.required.some((name) => !names.includes(String(name))))
+        throw new Error("tmw_value_effect_argument_missing");
+    const matches = (value, rule) => {
+        if (!obj(rule))
+            return false;
+        if (Array.isArray(rule.anyOf))
+            return rule.anyOf.some((r) => matches(value, r));
+        if (Array.isArray(rule.enum) && !rule.enum.some((v) => canonicalTmwJson(v) === canonicalTmwJson(value)))
+            return false;
+        const acceptsType = (t) => t === "null" ? value === null : t === "integer" ? Number.isSafeInteger(value) : t === "array" ? Array.isArray(value) : t === "object" ? obj(value) : typeof value === t;
+        if (rule.type !== undefined && !(Array.isArray(rule.type) ? rule.type.some(acceptsType) : acceptsType(rule.type)))
+            return false;
+        if (typeof value === "number" && (!Number.isFinite(value) || typeof rule.minimum === "number" && value < rule.minimum || typeof rule.maximum === "number" && value > rule.maximum))
+            return false;
+        if (typeof value === "string" && (typeof rule.minLength === "number" && value.length < rule.minLength || typeof rule.maxLength === "number" && value.length > rule.maxLength))
+            return false;
+        if (Array.isArray(value)) {
+            if (typeof rule.maxItems === "number" && value.length > rule.maxItems || typeof rule.minItems === "number" && value.length < rule.minItems)
+                return false;
+            if (rule.uniqueItems === true && new Set(value.map((v) => canonicalTmwJson(v))).size !== value.length)
+                return false;
+            if (rule.items !== undefined && !value.every((v) => matches(v, rule.items)))
+                return false;
+        }
+        if (obj(value)) {
+            if (typeof rule.maxProperties === "number" && Object.keys(value).length > rule.maxProperties)
+                return false;
+            const properties = obj(rule.properties) ? rule.properties : {};
+            if (rule.additionalProperties === false && Object.keys(value).some((key) => !Object.hasOwn(properties, key)))
+                return false;
+            if (Array.isArray(rule.required) && rule.required.some((key) => !Object.hasOwn(value, String(key))))
+                return false;
+            if (Object.entries(value).some(([key, v]) => Object.hasOwn(properties, key) && !matches(v, properties[key])))
+                return false;
+            if (obj(rule.additionalProperties) && Object.entries(value).some(([key, v]) => !Object.hasOwn(properties, key) && !matches(v, rule.additionalProperties)))
+                return false;
+        }
+        return true;
+    };
+    for (const [name, value] of Object.entries(args))
+        if (!matches(value, schema.properties[name]))
+            throw new Error("tmw_value_effect_argument_invalid");
+}
+const sceneTypes = Object.freeze({ world_time: "world_time", location: "spatial_ref", scene_id: "string", present_entity_ids: "string_list" });
+const id = (v) => typeof v === "string" && /^[a-z0-9][a-z0-9._:-]{0,127}$/u.test(v);
+const objectRefId = (v) => typeof v === "string" && /^[^\0\r\n]{1,512}$/u.test(v);
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const keys = (v, names) => Object.keys(v).sort().join(",") === names.sort().join(",");
+const type = (v) => TMW_VALUE_TYPES.includes(v);
+export function isTmwTypedValueV1(valueType, value) {
+    switch (valueType) {
+        case "boolean": return typeof value === "boolean";
+        case "string": return typeof value === "string";
+        case "int32": return typeof value === "number" && Number.isInteger(value) && value >= -2147483648 && value <= 2147483647;
+        case "number":
+        case "world_time": return typeof value === "number" && Number.isFinite(value);
+        case "real_timestamp": return typeof value === "number" && Number.isSafeInteger(value);
+        case "duration": return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+        case "string_list": return Array.isArray(value) && value.every((v) => typeof v === "string");
+        case "spatial_ref": return obj(value) && keys(value, ["worldId", "sourceRevision", "spatialId"]) && typeof value.worldId === "string" && value.worldId.length > 0 && typeof value.spatialId === "string" && value.spatialId.length > 0 && Number.isSafeInteger(value.sourceRevision) && value.sourceRevision >= 0;
+        case "object_ref": return isTmwObjectRefV1(value);
+    }
+}
+export function isTmwObjectRefV1(value) {
+    return obj(value) && keys(value, ["id", "kind"])
+        && (value.kind === "node" || value.kind === "edge")
+        && objectRefId(value.id);
+}
+export function tmwValueNodePortsV1(node) {
+    const inputs = {};
+    if (node.op === "compare") {
+        inputs.left = node.value_type;
+        inputs.right = node.value_type;
+    }
+    if (node.op === "bitwise") {
+        inputs.left = "int32";
+        if (node.operator !== "not")
+            inputs.right = "int32";
+    }
+    const output = node.op === "compare" || node.op === "state_read" ? "boolean" : node.op === "bitwise" ? "int32" : node.op === "scene_read" ? sceneTypes[node.field] : node.value_type;
+    return Object.freeze({ inputs: Object.freeze(inputs), outputs: Object.freeze({ value: output }) });
+}
+export function parseTmwValueGraphV1(value) {
+    if (!obj(value) || !keys(value, ["schema_version", "nodes", "edges"]) || value.schema_version !== 1 || !Array.isArray(value.nodes) || !Array.isArray(value.edges) || value.nodes.length > 4096 || value.edges.length > 16384)
+        throw new Error("tmw_value_graph_invalid");
+    const nodes = value.nodes.map((n) => {
+        if (!obj(n) || n.kind !== "value" || !id(n.stable_id))
+            throw new Error("tmw_value_node_invalid");
+        const base = ["kind", "stable_id", "op"];
+        if (n.op === "constant") {
+            if (!keys(n, [...base, "value_type", "value"]) || !type(n.value_type) || !isTmwTypedValueV1(n.value_type, n.value))
+                throw new Error("tmw_value_constant_invalid");
+        }
+        else if (n.op === "variable_read") {
+            if (!keys(n, [...base, "variable_id", "value_type"]) || !id(n.variable_id) || !type(n.value_type))
+                throw new Error("tmw_value_variable_invalid");
+        }
+        else if (n.op === "state_read") {
+            if (!keys(n, [...base, "target", "entity_id", "field"]) || !["node", "edge"].includes(String(n.target)) || !id(n.entity_id) || !["unlocked", "frozen"].includes(String(n.field)))
+                throw new Error("tmw_value_state_read_invalid");
+        }
+        else if (n.op === "scene_read") {
+            if (!keys(n, [...base, "field"]) || typeof n.field !== "string" || !Object.hasOwn(sceneTypes, n.field))
+                throw new Error("tmw_value_scene_field_invalid");
+        }
+        else if (n.op === "compare") {
+            if (!keys(n, [...base, "value_type", "comparison"]) || !type(n.value_type) || !["eq", "neq", "gt", "gte", "lt", "lte"].includes(String(n.comparison)) || (!["eq", "neq"].includes(String(n.comparison)) && ["boolean", "spatial_ref", "string_list", "object_ref"].includes(n.value_type)))
+                throw new Error("tmw_value_compare_invalid");
+        }
+        else if (n.op === "bitwise") {
+            if (!keys(n, [...base, "operator"]) || !["and", "or", "xor", "not", "shl", "shr", "ushr"].includes(String(n.operator)))
+                throw new Error("tmw_value_bitwise_invalid");
+        }
+        else
+            throw new Error("tmw_value_node_op_invalid");
+        return Object.freeze(JSON.parse(canonicalTmwJson(n)));
+    });
+    const edges = value.edges.map((e) => {
+        if (!obj(e) || !keys(e, ["from_node", "from_port", "to_node", "to_port", "value_type"]) || !id(e.from_node) || !id(e.to_node) || typeof e.to_port !== "string" || !/^[a-z][a-zA-Z0-9_]{0,127}$/u.test(e.to_port) || e.from_port !== "value" || !type(e.value_type))
+            throw new Error("tmw_value_edge_invalid");
+        return Object.freeze({ ...e });
+    });
+    return Object.freeze({ schema_version: 1, nodes: Object.freeze(nodes), edges: Object.freeze(edges) });
+}
+export function validateTmwValueGraphV1(graph, consumers = []) {
+    const nodes = new Map(graph.nodes.map((n) => [n.stable_id, n]));
+    if (nodes.size !== graph.nodes.length)
+        throw new Error("tmw_value_node_duplicate");
+    const ports = new Map(consumers.map((n) => [n.stable_id, n.inputs]));
+    for (const n of graph.nodes) {
+        if (ports.has(n.stable_id))
+            throw new Error("tmw_value_node_identity_collision");
+        ports.set(n.stable_id, tmwValueNodePortsV1(n).inputs);
+    }
+    const inputs = new Set();
+    const parents = new Map();
+    for (const edge of graph.edges) {
+        const source = nodes.get(edge.from_node);
+        if (!source || tmwValueNodePortsV1(source).outputs[edge.from_port] !== edge.value_type || ports.get(edge.to_node)?.[edge.to_port] !== edge.value_type)
+            throw new Error("tmw_value_edge_type_mismatch");
+        const input = `${edge.to_node}\0${edge.to_port}`;
+        if (inputs.has(input))
+            throw new Error("tmw_value_input_multiple_sources");
+        inputs.add(input);
+        parents.set(edge.to_node, [...(parents.get(edge.to_node) ?? []), edge.from_node]);
+    }
+    for (const [node, p] of ports)
+        for (const port of Object.keys(p))
+            if (!inputs.has(`${node}\0${port}`))
+                throw new Error("tmw_value_input_missing");
+    const visited = new Set(), active = new Set();
+    const visit = (n, depth) => {
+        if (depth > 128)
+            throw new Error("tmw_value_graph_depth_exceeded");
+        if (active.has(n))
+            throw new Error("tmw_value_graph_cycle");
+        if (visited.has(n))
+            return;
+        active.add(n);
+        for (const p of parents.get(n) ?? [])
+            visit(p, depth + 1);
+        active.delete(n);
+        visited.add(n);
+    };
+    for (const n of nodes.keys())
+        visit(n, 0);
+}
+export function readTmwSceneValueV1(scene, field) {
+    if (!scene)
+        return undefined;
+    const value = field === "world_time" ? scene.worldTime : field === "location" ? scene.spatialRef : field === "scene_id" ? scene.sceneId : scene.presentEntityNodeIds;
+    if (value === null)
+        return undefined;
+    return Object.freeze({ value_type: sceneTypes[field], value: value });
+}
+export function compareTmwValuesV1(left, right, comparison) {
+    if (comparison === "eq" || comparison === "neq")
+        return (canonicalTmwJson(left) === canonicalTmwJson(right)) === (comparison === "eq");
+    if (comparison === "contains")
+        return typeof left === "string" && typeof right === "string" ? left.includes(right) : Array.isArray(left) ? left.some((v) => canonicalTmwJson(v) === canonicalTmwJson(right)) : undefined;
+    if (!(typeof left === "number" && typeof right === "number") && !(typeof left === "string" && typeof right === "string"))
+        return undefined;
+    if (comparison === "gt")
+        return left > right;
+    if (comparison === "gte")
+        return left >= right;
+    if (comparison === "lt")
+        return left < right;
+    return left <= right;
+}
+export function evaluateTmwValueGraphV1(graph, context = {}, roots = graph.nodes.map((n) => n.stable_id)) {
+    const nodes = new Map(graph.nodes.map((n) => [n.stable_id, n]));
+    const result = new Map(), active = new Set();
+    const visit = (nodeId) => {
+        if (result.has(nodeId))
+            return result.get(nodeId);
+        if (active.has(nodeId) || active.size > 128)
+            throw new Error("tmw_value_graph_cycle");
+        const node = nodes.get(nodeId);
+        if (!node)
+            throw new Error("tmw_value_node_missing");
+        active.add(nodeId);
+        const input = (port) => {
+            const edge = graph.edges.find((e) => e.to_node === nodeId && e.to_port === port);
+            return edge ? visit(edge.from_node) : undefined;
+        };
+        let out;
+        if (node.op === "constant")
+            out = { value_type: node.value_type, value: node.value };
+        else if (node.op === "variable_read") {
+            out = context.variables?.[node.variable_id];
+            if (out && out.value_type !== node.value_type)
+                throw new Error("tmw_value_variable_type_mismatch");
+        }
+        else if (node.op === "scene_read")
+            out = readTmwSceneValueV1(context.scene, node.field);
+        else if (node.op === "state_read") {
+            if (context.entity_states !== undefined) {
+                const state = context.entity_states[`${node.target}:${node.entity_id}`];
+                const kind = state?.kind ?? "available";
+                out = { value_type: "boolean", value: node.field === "frozen" ? kind === "frozen" : (kind === "frozen" ? state?.frozen_stack[0]?.prev_kind : kind) === "available" };
+            }
+        }
+        else {
+            const left = input("left"), right = input("right");
+            const expectedType = node.op === "compare" ? node.value_type : "int32";
+            if (left && left.value_type !== expectedType || right && right.value_type !== expectedType)
+                throw new Error("tmw_value_runtime_type_mismatch");
+            if (left && (right || (node.op === "bitwise" && node.operator === "not"))) {
+                if (node.op === "compare") {
+                    const value = compareTmwValuesV1(left.value, right.value, node.comparison);
+                    if (value !== undefined)
+                        out = { value_type: "boolean", value };
+                }
+                else {
+                    const a = left.value, b = right?.value;
+                    if (["shl", "shr", "ushr"].includes(node.operator) && (!Number.isInteger(b) || b < 0 || b > 31))
+                        throw new Error("tmw_value_shift_count_invalid");
+                    // 位运算采用 32 位二补数；无符号右移的 bit pattern 仍以 int32 输出。
+                    const value = node.operator === "and" ? a & b : node.operator === "or" ? a | b : node.operator === "xor" ? a ^ b : node.operator === "not" ? ~a : node.operator === "shl" ? a << b : node.operator === "shr" ? a >> b : (a >>> b) | 0;
+                    out = { value_type: "int32", value };
+                }
+            }
+        }
+        if (out && !isTmwTypedValueV1(out.value_type, out.value))
+            throw new Error("tmw_value_runtime_type_mismatch");
+        active.delete(nodeId);
+        result.set(nodeId, out && Object.freeze(out));
+        return result.get(nodeId);
+    };
+    for (const nodeId of roots)
+        visit(nodeId);
+    return result;
+}
+export function resolveTmwValueGraphInputsV1(graph, targetId, context = {}) {
+    if (!graph)
+        return Object.freeze({});
+    const edges = graph.edges.filter((e) => e.to_node === targetId);
+    const values = evaluateTmwValueGraphV1(graph, context, edges.map((e) => e.from_node));
+    return Object.freeze(Object.fromEntries(edges.map((e) => [e.to_port, values.get(e.from_node)])));
+}

package/dist/view-event-delivery.d.ts

@@ -0,0 +1,47 @@
+import type { TmwCommittedEventExecutionReceipt } from "./runtime.js";
+import { type TmwJsonPrimitive } from "./runtime-contract.js";
+import { type ViewPayloadSchemaV3 } from "./view-payload-schema.js";
+export interface ViewEventDeliveryPayloadPathV1 {
+    readonly from: "viewVisiblePayload";
+    readonly path: ReadonlyArray<string>;
+}
+export interface ViewEventDeliveryLiteralV1 {
+    readonly literal: TmwJsonPrimitive;
+}
+export type ViewEventDeliveryFieldSourceV1 = ViewEventDeliveryPayloadPathV1 | ViewEventDeliveryLiteralV1;
+export interface ViewEventDeliveryDeclarationV1 {
+    readonly deliveryId: string;
+    readonly eventType: string;
+    readonly payloadSchema: ViewPayloadSchemaV3;
+    readonly fields: Readonly<Record<string, ViewEventDeliveryFieldSourceV1>>;
+}
+export interface ViewEventDeliveryMessageV1 {
+    readonly deliveryId: string;
+    readonly eventType: string;
+    readonly payload: Readonly<Record<string, TmwJsonPrimitive>>;
+    /** 仅在此交付合同内稳定；UI 只能将其作为不透明去重键。 */
+    readonly opaqueId: string;
+}
+export type ViewEventDeliveryDeclarationParseResult = {
+    readonly ok: true;
+    readonly declarations: ReadonlyArray<ViewEventDeliveryDeclarationV1>;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+export type ViewEventDeliveryProjectionResult = {
+    readonly ok: true;
+    readonly deliveries: ReadonlyArray<ViewEventDeliveryMessageV1>;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+/** 在读取 Runtime authorViewEvents 前 fail-closed 地解析声明。 */
+export declare const parseViewEventDeliveryDeclarations: (value: unknown) => ViewEventDeliveryDeclarationParseResult;
+/** Runtime 成功 activation receipt 的可信下行项；本模块不自行伪造它。 */
+export type TmwAuthorViewEventV1 = TmwCommittedEventExecutionReceipt["authorViewEvents"][number];
+/**
+ * 仅将 Runtime 成功 activation receipt 内的 verified authorViewEvent 投影为
+ * 显式声明的 SDK 消息。绝不读取 committed event 或其 generic payload。
+ */
+export declare const projectAuthorViewEventToViewDeliveries: (authorViewEvent: TmwAuthorViewEventV1, declarationInput: unknown) => Promise<ViewEventDeliveryProjectionResult>;

package/dist/view-event-delivery.js

@@ -0,0 +1,197 @@
+import { canonicalTmwJson, tmwSha256Hex } from "./runtime-contract.js";
+import { parseViewPayloadSchemaV3, viewPayloadMatchesSchemaV3, } from "./view-payload-schema.js";
+/**
+ * Trigger committed event 是私有运行时事实。本模块只暴露显式声明的、
+ * 更小的 View SDK 下行面。
+ */
+const DELIVERY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const DELIVERY_EVENT_TYPE = /^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$/;
+const MAX_DECLARATIONS = 128;
+const MAX_MAPPINGS = 128;
+const MAX_DELIVERY_BYTES = 32 * 1024;
+const isRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const ownData = (record, key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    return descriptor !== undefined && descriptor.enumerable && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+};
+const hasExactKeys = (record, keys) => {
+    const ownKeys = Reflect.ownKeys(record);
+    return ownKeys.length === keys.length
+        && ownKeys.every((key) => typeof key === "string" && keys.includes(key))
+        && keys.every((key) => ownData(record, key) !== undefined || Object.hasOwn(record, key));
+};
+const isPrimitive = (value) => value === null
+    || typeof value === "string"
+    || typeof value === "boolean"
+    || (typeof value === "number" && Number.isFinite(value));
+const isDeliveryIdentifier = (value) => typeof value === "string" && DELIVERY_ID.test(value);
+const parseFieldSource = (value) => {
+    if (!isRecord(value))
+        return null;
+    if (hasExactKeys(value, ["literal"])) {
+        const literal = ownData(value, "literal");
+        return isPrimitive(literal) ? Object.freeze({ literal }) : null;
+    }
+    if (!hasExactKeys(value, ["from", "path"]))
+        return null;
+    const from = ownData(value, "from");
+    const path = ownData(value, "path");
+    if (from !== "viewVisiblePayload"
+        || !Array.isArray(path)
+        || path.length !== 1
+        || !path.every(isDeliveryIdentifier))
+        return null;
+    return Object.freeze({ from, path: Object.freeze([...path]) });
+};
+const parseDeclaration = (value) => {
+    if (!isRecord(value) || !hasExactKeys(value, ["deliveryId", "eventType", "payloadSchema", "fields"])) {
+        return null;
+    }
+    const deliveryId = ownData(value, "deliveryId");
+    const eventType = ownData(value, "eventType");
+    const payloadSchema = ownData(value, "payloadSchema");
+    const fields = ownData(value, "fields");
+    if (!isDeliveryIdentifier(deliveryId) || typeof eventType !== "string" || !DELIVERY_EVENT_TYPE.test(eventType)) {
+        return null;
+    }
+    const schema = parseViewPayloadSchemaV3(payloadSchema);
+    if (schema === null || !isRecord(fields))
+        return null;
+    const schemaKeys = Object.keys(schema.properties).sort();
+    const fieldKeys = Object.keys(fields).sort();
+    if (fieldKeys.length > MAX_MAPPINGS || fieldKeys.some((key) => !Object.hasOwn(schema.properties, key))) {
+        return null;
+    }
+    const parsedFields = Object.create(null);
+    for (const key of fieldKeys) {
+        const field = parseFieldSource(ownData(fields, key));
+        if (field === null)
+            return null;
+        parsedFields[key] = field;
+    }
+    if (schemaKeys.some((key) => schema.properties[key].required && !Object.hasOwn(parsedFields, key))) {
+        return null;
+    }
+    return Object.freeze({
+        deliveryId,
+        eventType,
+        payloadSchema: schema,
+        fields: Object.freeze(parsedFields),
+    });
+};
+/** 在读取 Runtime authorViewEvents 前 fail-closed 地解析声明。 */
+export const parseViewEventDeliveryDeclarations = (value) => {
+    if (!Array.isArray(value) || value.length > MAX_DECLARATIONS) {
+        return { ok: false, code: "view_delivery_declarations_invalid" };
+    }
+    const declarations = [];
+    const deliveryIds = new Set();
+    for (const item of value) {
+        const parsed = parseDeclaration(item);
+        if (parsed === null || deliveryIds.has(parsed.deliveryId)) {
+            return { ok: false, code: "view_delivery_declaration_invalid" };
+        }
+        deliveryIds.add(parsed.deliveryId);
+        declarations.push(parsed);
+    }
+    return { ok: true, declarations: Object.freeze(declarations) };
+};
+const sourceAuthorViewEvent = (value) => {
+    if (!isRecord(value))
+        return null;
+    const eventId = ownData(value, "eventId");
+    const eventType = ownData(value, "eventType");
+    const viewVisiblePayload = ownData(value, "viewVisiblePayload");
+    if (!isDeliveryIdentifier(eventId)
+        || typeof eventType !== "string"
+        || !DELIVERY_EVENT_TYPE.test(eventType)
+        || !isRecord(viewVisiblePayload)
+        || !Object.values(viewVisiblePayload).every(isPrimitive)) {
+        return null;
+    }
+    const primitivePayload = Object.create(null);
+    for (const [key, item] of Object.entries(viewVisiblePayload)) {
+        if (!isPrimitive(item))
+            return null;
+        primitivePayload[key] = item;
+    }
+    return Object.freeze({
+        eventId,
+        eventType,
+        viewVisiblePayload: Object.freeze(primitivePayload),
+    });
+};
+const valueAtPath = (payload, path) => {
+    let cursor = payload;
+    for (const segment of path) {
+        if (!isRecord(cursor))
+            return undefined;
+        const value = ownData(cursor, segment);
+        if (value === undefined && !Object.hasOwn(cursor, segment))
+            return undefined;
+        cursor = value;
+    }
+    return isPrimitive(cursor) ? cursor : undefined;
+};
+/**
+ * 去重身份覆盖完整声明（包括字段来源），但不进入下行消息本体。字段按
+ * canonicalTmwJson 的键排序稳定编码，声明调整必然得到新的不透明键空间。
+ */
+const canonicalDeclarationIdentity = (declaration) => canonicalTmwJson({
+    deliveryId: declaration.deliveryId,
+    eventType: declaration.eventType,
+    payloadSchema: declaration.payloadSchema,
+    fields: declaration.fields,
+});
+const opaqueDeliveryId = async (declaration, eventId) => await tmwSha256Hex(new TextEncoder().encode(canonicalTmwJson({
+    declaration: canonicalDeclarationIdentity(declaration),
+    eventId,
+})));
+/**
+ * 仅将 Runtime 成功 activation receipt 内的 verified authorViewEvent 投影为
+ * 显式声明的 SDK 消息。绝不读取 committed event 或其 generic payload。
+ */
+export const projectAuthorViewEventToViewDeliveries = async (authorViewEvent, declarationInput) => {
+    const parsed = parseViewEventDeliveryDeclarations(declarationInput);
+    if (!parsed.ok)
+        return parsed;
+    const source = sourceAuthorViewEvent(authorViewEvent);
+    if (source === null)
+        return { ok: false, code: "view_delivery_event_identity_invalid" };
+    const deliveries = [];
+    for (const declaration of parsed.declarations) {
+        if (declaration.eventType !== source.eventType)
+            continue;
+        const payload = Object.create(null);
+        for (const key of Object.keys(declaration.fields).sort()) {
+            const sourceField = declaration.fields[key];
+            const value = "literal" in sourceField
+                ? sourceField.literal
+                : valueAtPath(source.viewVisiblePayload, sourceField.path);
+            if (value === undefined)
+                return { ok: false, code: "view_delivery_source_value_invalid" };
+            payload[key] = value;
+        }
+        const frozenPayload = Object.freeze(payload);
+        if (!viewPayloadMatchesSchemaV3(frozenPayload, declaration.payloadSchema)) {
+            return { ok: false, code: "view_delivery_payload_invalid" };
+        }
+        if (new TextEncoder().encode(canonicalTmwJson(frozenPayload)).byteLength > MAX_DELIVERY_BYTES) {
+            return { ok: false, code: "view_delivery_payload_too_large" };
+        }
+        deliveries.push(Object.freeze({
+            deliveryId: declaration.deliveryId,
+            eventType: declaration.eventType,
+            payload: frozenPayload,
+            opaqueId: await opaqueDeliveryId(declaration, source.eventId),
+        }));
+    }
+    return { ok: true, deliveries: Object.freeze(deliveries) };
+};

package/dist/view-interaction-manifest-v3.d.ts

@@ -0,0 +1,60 @@
+import type { TMW_RUNTIME_GENERATION } from "./runtime-contract.js";
+import { type TmwJsonValue } from "./runtime-contract.js";
+import { type ViewPayloadSchemaV3 } from "./view-payload-schema.js";
+import { type ViewEventDeliveryDeclarationV1 } from "./view-event-delivery.js";
+export { parseViewPayloadSchemaV3, viewPayloadMatchesSchemaV3, type ViewPayloadPrimitiveKind, type ViewPayloadPropertyV3, type ViewPayloadSchemaV3, } from "./view-payload-schema.js";
+export interface ViewInteractionEventDeclarationV3 {
+    readonly event_id: string;
+    readonly event_type: string;
+    readonly capability: string;
+    readonly payload_schema: ViewPayloadSchemaV3;
+}
+export interface ViewInteractionManifestV3 {
+    readonly schema: "view-interaction-manifest.v3";
+    readonly generation: typeof TMW_RUNTIME_GENERATION;
+    readonly epoch: number;
+    readonly artifact_digest: string;
+    readonly runtime_contract_hash: string;
+    readonly bootstrap_url: string;
+    readonly capabilities: ReadonlyArray<string>;
+    readonly events: ReadonlyArray<ViewInteractionEventDeclarationV3>;
+    /** 可选的 committed-event 到 View SDK 下行投影；缺席时绝不下行。 */
+    readonly view_deliveries?: ReadonlyArray<ViewEventDeliveryDeclarationV1>;
+}
+/** ArtifactV5 编译器消费的唯一 view interaction source。 */
+export interface ViewInteractionSourceV3 {
+    readonly schema: "view-interaction-source.v3";
+    readonly generation: typeof TMW_RUNTIME_GENERATION;
+    readonly manifest: ViewInteractionManifestV3;
+    readonly manifest_digest: string;
+}
+export interface ViewInteractionEventV3 {
+    readonly schema: "view-interaction-event.v3";
+    readonly generation: typeof TMW_RUNTIME_GENERATION;
+    readonly event_id: string;
+    readonly event_type: string;
+    readonly payload: Readonly<Record<string, TmwJsonValue>>;
+    readonly interaction_id: string;
+    readonly manifest_digest: string;
+    readonly epoch: number;
+    readonly artifact_digest: string;
+    readonly nonce: string;
+}
+export type ViewInteractionParseResult = {
+    readonly ok: true;
+    readonly event: ViewInteractionEventV3;
+} | {
+    readonly ok: false;
+    readonly code: string;
+};
+export interface ViewInteractionEventGateV3 {
+    parse(value: unknown): ViewInteractionParseResult;
+    clear(): void;
+}
+export declare const parseViewInteractionManifestV3: (value: unknown) => ViewInteractionManifestV3 | null;
+export declare const parseViewInteractionSourceV3: (value: unknown) => ViewInteractionSourceV3 | null;
+export declare const canonicalViewInteractionManifestV3: (manifest: ViewInteractionManifestV3) => string;
+export declare const digestViewInteractionManifestV3: (manifest: ViewInteractionManifestV3) => Promise<string>;
+export declare const parseViewInteractionEventV3: (value: unknown, manifest: ViewInteractionManifestV3, manifestDigest: string) => ViewInteractionParseResult;
+/** Pure stateful replay gate; the Player/preview host remains the sole listener. */
+export declare const createViewInteractionEventGateV3: (manifest: ViewInteractionManifestV3, manifestDigest: string, maxReplayNonces?: number) => ViewInteractionEventGateV3;