@world-engines/project-host 0.1.0-alpha.0

package/dist/local-preview-bound-resources.d.ts

@@ -0,0 +1,12 @@
+import { type LocalPreviewFrozenAttributeResourceRef } from "./local-preview-player-read-models.js";
+export interface LocalPreviewBoundResourceProjection {
+    /** 全部引用都必须由当前 committed SAV 的 stable ID 再做可见性过滤。 */
+    readonly frozen_attribute_resource_refs: readonly LocalPreviewFrozenAttributeResourceRef[];
+    /** 只允许在没有恢复资源 checkpoint 的新存档初始化时消费。 */
+    readonly initial_unlocked_resource_ids: readonly string[];
+}
+/**
+ * 从 immutable logical_graph capture 投影 Player 资源读模型。
+ * 本函数只解析正式 `_bound_attr_media.value`；不会读取或推断 Gallery 路径。
+ */
+export declare function localPreviewBoundResourcesFromLogicalGraph(logicalGraph: unknown): LocalPreviewBoundResourceProjection;

package/dist/local-preview-bound-resources.js

@@ -0,0 +1,80 @@
+import { localPreviewOwnedResourceStableId, } from "./local-preview-player-read-models.js";
+const BOUND_ATTR_MEDIA_PROP_KEY = "_bound_attr_media";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * 与 wasm-core `parse_bound_attr_media` 对齐：包装或数组任一字段不合法时，
+ * 整个实体的绑定资源都视为空；serde 未声明的字段会被忽略。
+ */
+function parseBoundAttrMedia(props) {
+    const propsRecord = record(props);
+    const wrapper = propsRecord === null ? null : record(propsRecord[BOUND_ATTR_MEDIA_PROP_KEY]);
+    const serialized = wrapper?.value;
+    if (typeof serialized !== "string")
+        return Object.freeze([]);
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(parsed))
+        return Object.freeze([]);
+    const entries = [];
+    for (const candidate of parsed) {
+        const entry = record(candidate);
+        if (entry === null
+            || typeof entry.attr_key !== "string"
+            || typeof entry.r2_uri !== "string"
+            || typeof entry.kind !== "string"
+            || (entry.media_name !== undefined && typeof entry.media_name !== "string")
+            || (entry.trigger_desc !== undefined && typeof entry.trigger_desc !== "string")
+            || (entry.default_unlocked !== undefined && typeof entry.default_unlocked !== "boolean")) {
+            return Object.freeze([]);
+        }
+        entries.push(Object.freeze({
+            attr_key: entry.attr_key,
+            r2_uri: entry.r2_uri,
+            kind: entry.kind,
+            default_unlocked: entry.default_unlocked === true,
+        }));
+    }
+    return Object.freeze(entries);
+}
+/**
+ * 从 immutable logical_graph capture 投影 Player 资源读模型。
+ * 本函数只解析正式 `_bound_attr_media.value`；不会读取或推断 Gallery 路径。
+ */
+export function localPreviewBoundResourcesFromLogicalGraph(logicalGraph) {
+    const graph = record(logicalGraph);
+    const entities = graph === null || !Array.isArray(graph.entities) ? [] : graph.entities;
+    const refs = [];
+    const initialUnlocked = new Set();
+    for (const candidate of entities) {
+        const entity = record(candidate);
+        if (entity === null)
+            continue;
+        const nodeId = entity.entity_id ?? entity.id;
+        if (typeof nodeId !== "string")
+            continue;
+        for (const entry of parseBoundAttrMedia(entity.props)) {
+            refs.push(Object.freeze({
+                node_id: nodeId,
+                attr_key: entry.attr_key,
+                type: entry.kind,
+                uri: entry.r2_uri,
+            }));
+            if (entry.default_unlocked) {
+                initialUnlocked.add(localPreviewOwnedResourceStableId(nodeId, entry.attr_key));
+            }
+        }
+    }
+    return Object.freeze({
+        frozen_attribute_resource_refs: Object.freeze(refs),
+        initial_unlocked_resource_ids: Object.freeze([...initialUnlocked]),
+    });
+}

package/dist/local-preview-message-store.d.ts

@@ -0,0 +1,63 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { LocalPreviewWorldlineScope } from "./local-preview-worldlines.js";
+export interface LocalPreviewMessageScope {
+    readonly captureId: string;
+    readonly saveId: string;
+    /** Full scope is required to derive the same DB-owned worldline authority key. */
+    readonly worldlineScope: LocalPreviewWorldlineScope;
+}
+export interface LocalPreviewMessageHead {
+    readonly revisionId: string;
+    readonly revisionSequence: number;
+    readonly ledgerHead: string | null;
+}
+export interface LocalPreviewCommittedMessage {
+    readonly messageId: string;
+    readonly operationId: string;
+    readonly turnId: string;
+    readonly worldlineId: string;
+    readonly role: "user" | "assistant";
+    readonly text: string;
+}
+export declare class LocalPreviewMessageStore {
+    #private;
+    constructor(input: Readonly<{
+        database: DatabaseSync;
+        scope: LocalPreviewMessageScope;
+    }>);
+    /**
+     * Records the accepted Player message.  It does not create a worldline
+     * checkpoint or pretend that an assistant turn succeeded; Runtime commits
+     * the later assistant message together with the actual SAV activation.
+     */
+    appendAcceptedUserMessage(input: Readonly<{
+        operationId: string;
+        turnId: string;
+        messageId: string;
+        text: string;
+        activeWorldlineId: string;
+        expectedRuntimeHead: LocalPreviewMessageHead;
+    }>): Promise<Readonly<{
+        message: LocalPreviewCommittedMessage;
+        replayed: boolean;
+    }>>;
+    /**
+     * The Runtime's successful activation transaction is the only caller.  A
+     * caller cannot synthesize an assistant answer: this method refuses to open
+     * its own transaction, validates every prior ordered ID, and rolls back with
+     * the enclosing SAV activation if anything fails.
+     */
+    recordCommittedAssistantInTransaction(input: Readonly<{
+        operationId: string;
+        turnId: string;
+        messageId: string;
+        text: string;
+        activeWorldlineId: string;
+        orderedMessageIds: readonly string[];
+    }>): Readonly<{
+        message: LocalPreviewCommittedMessage;
+        replayed: boolean;
+    }>;
+    /** Reads the active line's DB-owned checkpoint plus its durable pending-user tail. */
+    listCurrentWorldline(): readonly LocalPreviewCommittedMessage[];
+}

package/dist/local-preview-message-store.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+/**
+ * Capture-bound, SQLite-backed message bodies for the local Player Preview.
+ *
+ * This is deliberately not a session JSONL replacement and it does not decide
+ * a worldline's message order.  `LocalPreviewWorldlineStore` remains the
+ * authority for the active line and checkpointed ordered message IDs.  This
+ * store merely keeps the bodies for those IDs in the Runtime's existing
+ * activation.sqlite connection.
+ */
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const MAX_TEXT_BYTES = 64 * 1024;
+export class LocalPreviewMessageStore {
+    #db;
+    #scope;
+    #worldlineScopeKey;
+    constructor(input) {
+        assertScope(input.scope);
+        this.#db = input.database;
+        this.#scope = Object.freeze({ ...input.scope });
+        this.#worldlineScopeKey = worldlineScopeKey(input.scope.worldlineScope);
+        this.#migrateLegacyAssistantRows();
+    }
+    /**
+     * Records the accepted Player message.  It does not create a worldline
+     * checkpoint or pretend that an assistant turn succeeded; Runtime commits
+     * the later assistant message together with the actual SAV activation.
+     */
+    async appendAcceptedUserMessage(input) {
+        assertMessageInput(input, "user");
+        const requestDigest = digest({ scope: this.#scope, role: "user", ...input });
+        return this.#transaction(() => {
+            const existing = this.#byOperation(input.operationId);
+            if (existing !== null) {
+                if (existing.request_digest !== requestDigest)
+                    fail("operation_id_conflict");
+                return Object.freeze({ message: toMessage(existing), replayed: true });
+            }
+            const sameId = this.#byMessage(input.messageId);
+            if (sameId !== null)
+                fail("message_id_conflict");
+            if (!sameHead(this.#readHead(), input.expectedRuntimeHead))
+                fail("cas_conflict");
+            const current = this.#currentLine();
+            if (current.activeWorldlineId !== input.activeWorldlineId)
+                fail("active_worldline_mismatch");
+            const row = makeRow(input, "user", requestDigest, input.expectedRuntimeHead, this.#nextSequence());
+            this.#insert(row);
+            return Object.freeze({ message: toMessage(row), replayed: false });
+        });
+    }
+    /**
+     * The Runtime's successful activation transaction is the only caller.  A
+     * caller cannot synthesize an assistant answer: this method refuses to open
+     * its own transaction, validates every prior ordered ID, and rolls back with
+     * the enclosing SAV activation if anything fails.
+     */
+    recordCommittedAssistantInTransaction(input) {
+        if (!inTransaction(this.#db))
+            fail("assistant_requires_activation_transaction");
+        assertMessageInput(input, "assistant");
+        assertOrderedIds(input.orderedMessageIds);
+        if (input.orderedMessageIds.at(-1) !== input.messageId)
+            fail("assistant_not_order_tail");
+        const head = this.#readHead();
+        const requestDigest = digest({ scope: this.#scope, role: "assistant", ...input, committedRuntimeHead: head });
+        const existing = this.#byOperation(input.operationId);
+        if (existing !== null) {
+            if (existing.request_digest !== requestDigest)
+                fail("operation_id_conflict");
+            return Object.freeze({ message: toMessage(existing), replayed: true });
+        }
+        if (this.#byMessage(input.messageId) !== null)
+            fail("message_id_conflict");
+        const current = this.#currentLine();
+        if (current.activeWorldlineId !== input.activeWorldlineId)
+            fail("active_worldline_mismatch");
+        const expectedOrdered = Object.freeze([...current.checkpointIds, ...this.#pendingUserIds(current.activeWorldlineId, current.checkpointIds), input.messageId]);
+        if (!sameIds(input.orderedMessageIds, expectedOrdered))
+            fail("assistant_order_not_current_worldline");
+        this.#assertExistingMessages(expectedOrdered.slice(0, -1));
+        const row = makeRow(input, "assistant", requestDigest, head, this.#nextSequence());
+        this.#insert(row);
+        return Object.freeze({ message: toMessage(row), replayed: false });
+    }
+    /** Reads the active line's DB-owned checkpoint plus its durable pending-user tail. */
+    listCurrentWorldline() {
+        const current = this.#currentLine();
+        const ids = Object.freeze([...current.checkpointIds, ...this.#pendingUserIds(current.activeWorldlineId, current.checkpointIds)]);
+        return Object.freeze(ids.map((messageId) => {
+            const row = this.#byMessage(messageId);
+            if (row === null)
+                fail("ordered_message_missing");
+            return toMessage(row);
+        }));
+    }
+    #migrateLegacyAssistantRows() {
+        this.#db.exec("CREATE TABLE IF NOT EXISTS local_preview_message_v2 (message_id TEXT PRIMARY KEY, operation_id TEXT UNIQUE NOT NULL, turn_id TEXT NOT NULL, worldline_id TEXT NOT NULL, role TEXT NOT NULL CHECK(role IN ('user','assistant')), text TEXT NOT NULL, request_digest TEXT NOT NULL, head_json TEXT NOT NULL, sequence INTEGER NOT NULL UNIQUE);");
+        const old = this.#db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='local_preview_message'").get();
+        if (old === undefined)
+            return;
+        const rows = this.#db.prepare("SELECT message_id,operation_id,role,text FROM local_preview_message").all();
+        if (rows.length === 0)
+            return;
+        this.#transaction(() => {
+            for (const oldRow of rows) {
+                if (typeof oldRow.message_id !== "string" || typeof oldRow.operation_id !== "string" || oldRow.role !== "assistant" || typeof oldRow.text !== "string")
+                    fail("legacy_message_invalid");
+                const existing = this.#byMessage(oldRow.message_id);
+                if (existing !== null)
+                    continue;
+                const row = Object.freeze({ message_id: oldRow.message_id, operation_id: oldRow.operation_id, turn_id: "legacy", worldline_id: "legacy", role: "assistant", text: oldRow.text, request_digest: digest({ legacy: true, operationId: oldRow.operation_id, messageId: oldRow.message_id, text: oldRow.text }), head_json: JSON.stringify({ revisionId: "legacy", revisionSequence: 0, ledgerHead: null }), sequence: this.#nextSequence() });
+                this.#insert(row);
+            }
+        });
+    }
+    #readHead() {
+        const row = this.#db.prepare("SELECT value FROM local_preview_state WHERE key='head'").get();
+        if (row === undefined)
+            fail("runtime_head_missing");
+        let value;
+        try {
+            value = JSON.parse(row.value);
+        }
+        catch {
+            fail("runtime_head_invalid");
+        }
+        assertHead(value);
+        return Object.freeze({ ...value });
+    }
+    #byOperation(operationId) { const row = this.#db.prepare("SELECT message_id,operation_id,turn_id,worldline_id,role,text,request_digest,head_json,sequence FROM local_preview_message_v2 WHERE operation_id=?").get(operationId); return row === undefined ? null : validateRow(row); }
+    #byMessage(messageId) { const row = this.#db.prepare("SELECT message_id,operation_id,turn_id,worldline_id,role,text,request_digest,head_json,sequence FROM local_preview_message_v2 WHERE message_id=?").get(messageId); return row === undefined ? null : validateRow(row); }
+    #insert(row) { this.#db.prepare("INSERT INTO local_preview_message_v2(message_id,operation_id,turn_id,worldline_id,role,text,request_digest,head_json,sequence) VALUES (?,?,?,?,?,?,?,?,?)").run(row.message_id, row.operation_id, row.turn_id, row.worldline_id, row.role, row.text, row.request_digest, row.head_json, row.sequence); }
+    #nextSequence() { return (this.#db.prepare("SELECT COALESCE(MAX(sequence),0) AS n FROM local_preview_message_v2").get().n) + 1; }
+    #currentLine() {
+        const catalog = this.#db.prepare("SELECT active_worldline_id FROM local_preview_worldline_catalog_v2 WHERE scope_key=?").get(this.#worldlineScopeKey);
+        if (catalog === undefined)
+            fail("worldline_catalog_missing");
+        assertId(catalog.active_worldline_id, "active_worldline_id");
+        const line = this.#db.prepare("SELECT message_ids_json FROM local_preview_worldline_v2 WHERE scope_key=? AND worldline_id=?").get(this.#worldlineScopeKey, catalog.active_worldline_id);
+        if (line === undefined)
+            fail("active_worldline_missing");
+        return Object.freeze({ activeWorldlineId: catalog.active_worldline_id, checkpointIds: parseIds(line.message_ids_json) });
+    }
+    #pendingUserIds(activeWorldlineId, checkpointIds) {
+        const rows = this.#db.prepare("SELECT message_id FROM local_preview_message_v2 WHERE role='user' AND worldline_id=? ORDER BY sequence").all(activeWorldlineId);
+        const checkpoint = new Set(checkpointIds);
+        const pending = [];
+        for (const row of rows) {
+            assertId(row.message_id, "pending_message_id");
+            if (!checkpoint.has(row.message_id))
+                pending.push(row.message_id);
+        }
+        return Object.freeze(pending);
+    }
+    #assertExistingMessages(ids) { for (const id of ids)
+        if (this.#byMessage(id) === null)
+            fail("ordered_message_missing"); }
+    #transaction(work) { if (inTransaction(this.#db))
+        return work(); this.#db.exec("BEGIN IMMEDIATE"); try {
+        const result = work();
+        this.#db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        try {
+            this.#db.exec("ROLLBACK");
+        }
+        catch { }
+        throw error;
+    } }
+}
+function makeRow(input, role, requestDigest, head, sequence) { return Object.freeze({ message_id: input.messageId, operation_id: input.operationId, turn_id: input.turnId, worldline_id: input.activeWorldlineId, role, text: input.text, request_digest: requestDigest, head_json: JSON.stringify(head), sequence }); }
+function toMessage(row) { return Object.freeze({ messageId: row.message_id, operationId: row.operation_id, turnId: row.turn_id, worldlineId: row.worldline_id, role: row.role, text: row.text }); }
+function validateRow(row) { assertId(row.message_id, "message_id"); assertId(row.operation_id, "operation_id"); assertId(row.turn_id, "turn_id"); assertId(row.worldline_id, "worldline_id"); if (row.role !== "user" && row.role !== "assistant")
+    fail("stored_role_invalid"); assertText(row.text); if (!/^[a-f0-9]{64}$/u.test(row.request_digest))
+    fail("stored_digest_invalid"); if (!Number.isSafeInteger(row.sequence) || row.sequence < 1)
+    fail("stored_sequence_invalid"); let head; try {
+    head = JSON.parse(row.head_json);
+}
+catch {
+    fail("stored_head_invalid");
+} assertHead(head); return Object.freeze({ ...row }); }
+function assertMessageInput(input, _role) { assertId(input.operationId, "operation_id"); assertId(input.turnId, "turn_id"); assertId(input.messageId, "message_id"); assertId(input.activeWorldlineId, "active_worldline_id"); assertText(input.text); }
+function assertScope(scope) {
+    if (!isRecord(scope) || !ID.test(scope.captureId) || !ID.test(scope.saveId) || !isRecord(scope.worldlineScope))
+        fail("invalid_scope");
+    const line = scope.worldlineScope;
+    if (line.authority !== "worldengine.local-preview-worldlines/v1" || !ID.test(line.authorNamespace) || !ID.test(line.projectId) || !ID.test(line.scenarioId) || !ID.test(line.saveId) || !/^[a-f0-9]{64}$/u.test(line.captureSha256) || line.captureSha256 !== scope.captureId || line.saveId !== scope.saveId)
+        fail("invalid_worldline_scope");
+}
+function assertId(value, label) { if (typeof value !== "string" || !ID.test(value))
+    fail(`invalid_${label}`); }
+function assertText(value) { if (typeof value !== "string" || value.length === 0 || new TextEncoder().encode(value).byteLength > MAX_TEXT_BYTES)
+    fail("invalid_text"); }
+function assertHead(value) { if (!isRecord(value) || typeof value.revisionId !== "string" || !ID.test(value.revisionId) || typeof value.revisionSequence !== "number" || !Number.isSafeInteger(value.revisionSequence) || value.revisionSequence < 0 || (value.ledgerHead !== null && (typeof value.ledgerHead !== "string" || !ID.test(value.ledgerHead))))
+    fail("invalid_runtime_head"); }
+function assertOrderedIds(ids) { if (!Array.isArray(ids) || new Set(ids).size !== ids.length)
+    fail("invalid_ordered_message_ids"); for (const id of ids)
+    assertId(id, "ordered_message_id"); }
+function sameHead(left, right) { return left.revisionId === right.revisionId && left.revisionSequence === right.revisionSequence && left.ledgerHead === right.ledgerHead; }
+function sameIds(left, right) { return left.length === right.length && left.every((id, index) => id === right[index]); }
+function parseIds(value) { let parsed; try {
+    parsed = JSON.parse(value);
+}
+catch {
+    fail("checkpoint_ids_invalid");
+} if (!Array.isArray(parsed))
+    fail("checkpoint_ids_invalid"); assertOrderedIds(parsed); return Object.freeze([...parsed]); }
+function worldlineScopeKey(scope) { return digest([scope.authority, scope.authorNamespace, scope.projectId, scope.scenarioId, scope.saveId, scope.captureSha256]); }
+function digest(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function inTransaction(db) { return db.isTransaction === true; }
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; }
+function fail(code) { throw new Error(`local_preview_message_store:${code}`); }

package/dist/local-preview-player-read-models.d.ts

@@ -0,0 +1,47 @@
+export interface LocalPreviewScenarioRuntimeCheckpoint {
+    readonly schema_version: 1;
+    /** 与同一 activation head 一起提交的正式 ScenarioRuntimeState.state_revision。 */
+    readonly state_revision: string;
+    readonly progress: number;
+    readonly unlocked_resource_ids: readonly string[];
+}
+/**
+ * Runtime 在 immutable source capture 解析出的属性资源引用。
+ * stable_id 不由调用者声明：始终从 node_id + attr_key 重新推导，避免跨节点借用 unlock。
+ */
+export interface LocalPreviewFrozenAttributeResourceRef {
+    readonly node_id: string;
+    readonly attr_key: string;
+    readonly type: string;
+    readonly uri: string;
+}
+export interface LocalPreviewPlayerReadModelSnapshot {
+    /** Runtime 的同 head SAV 投影，不接受 View/bridge 写入。 */
+    readonly scenario_runtime_state: LocalPreviewScenarioRuntimeCheckpoint;
+    /** 同一个 immutable source capture 的 logical_graph 属性资源引用。 */
+    readonly frozen_attribute_resource_refs: readonly LocalPreviewFrozenAttributeResourceRef[];
+}
+/** Runtime owner 以 activation.sqlite 的 current head 构造这一窄快照。 */
+export interface LocalPreviewPlayerReadModelPort {
+    readCommittedPlayerReadModel(): Promise<LocalPreviewPlayerReadModelSnapshot>;
+}
+export interface LocalPreviewOwnedResourceGroup {
+    readonly node_id: string;
+    readonly attr_key: string;
+    readonly resources: readonly Readonly<{
+        type: string;
+        uri: string;
+    }>[];
+}
+/** `world-engines-resource:v1` 的唯一 stable ID 公式，供 runtime 写 checkpoint 与测试共享。 */
+export declare function localPreviewOwnedResourceStableId(nodeId: string, attrKey: string): string;
+/**
+ * 给 LocalPreviewReadOnlyProjection 注入的真实 producer。
+ * 每次读取均从 Runtime 的 committed head 取 checkpoint，因此缺 checkpoint、过期/错 shape 都 fail closed。
+ */
+export declare class LocalPreviewPlayerReadModels {
+    #private;
+    constructor(port: LocalPreviewPlayerReadModelPort);
+    progress(): Promise<number>;
+    ownedResources(): Promise<readonly LocalPreviewOwnedResourceGroup[]>;
+}

package/dist/local-preview-player-read-models.js

@@ -0,0 +1,90 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const STATE_REVISION = /^(?:0|[1-9][0-9]*)$/u;
+function fail(message) {
+    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+}
+function anchor(value, field) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 512 || value.includes("\u0000"))
+        fail(`local Preview ${field} 无效`);
+    return value;
+}
+function stableId(nodeId, attrKey) {
+    return `world-engines-resource:v1:${encodeURIComponent(nodeId)}:${encodeURIComponent(attrKey)}`;
+}
+function validateCheckpoint(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail("local Preview ScenarioRuntimeState checkpoint 无效");
+    const checkpoint = value;
+    if (checkpoint.schema_version !== 1 || !STATE_REVISION.test(checkpoint.state_revision)
+        || !Number.isFinite(checkpoint.progress) || checkpoint.progress < 0 || checkpoint.progress > 1
+        || !Array.isArray(checkpoint.unlocked_resource_ids)) {
+        fail("local Preview ScenarioRuntimeState checkpoint 无效");
+    }
+    const unlocked = checkpoint.unlocked_resource_ids.map((resourceId) => {
+        if (typeof resourceId !== "string" || resourceId.length === 0 || resourceId.length > 512)
+            fail("local Preview unlocked_resource_ids 无效");
+        return resourceId;
+    });
+    if (new Set(unlocked).size !== unlocked.length)
+        fail("local Preview unlocked_resource_ids 重复");
+    return Object.freeze({ schema_version: 1, state_revision: checkpoint.state_revision, progress: checkpoint.progress, unlocked_resource_ids: Object.freeze(unlocked) });
+}
+function validateResource(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail("local Preview frozen attribute resource ref 无效");
+    const ref = value;
+    const nodeId = anchor(ref.node_id, "resource node_id");
+    const attrKey = anchor(ref.attr_key, "resource attr_key");
+    if (typeof ref.type !== "string" || ref.type.length === 0 || ref.type.length > 128
+        || typeof ref.uri !== "string" || ref.uri.length === 0 || ref.uri.length > 4096) {
+        fail("local Preview frozen attribute resource ref 无效");
+    }
+    return Object.freeze({ node_id: nodeId, attr_key: attrKey, type: ref.type, uri: ref.uri });
+}
+/** `world-engines-resource:v1` 的唯一 stable ID 公式，供 runtime 写 checkpoint 与测试共享。 */
+export function localPreviewOwnedResourceStableId(nodeId, attrKey) {
+    return stableId(anchor(nodeId, "resource node_id"), anchor(attrKey, "resource attr_key"));
+}
+/**
+ * 给 LocalPreviewReadOnlyProjection 注入的真实 producer。
+ * 每次读取均从 Runtime 的 committed head 取 checkpoint，因此缺 checkpoint、过期/错 shape 都 fail closed。
+ */
+export class LocalPreviewPlayerReadModels {
+    #port;
+    constructor(port) {
+        this.#port = port;
+    }
+    async progress() {
+        return (await this.#snapshot()).scenario_runtime_state.progress;
+    }
+    async ownedResources() {
+        const snapshot = await this.#snapshot();
+        const unlocked = new Set(snapshot.scenario_runtime_state.unlocked_resource_ids);
+        const groups = new Map();
+        const seen = new Set();
+        for (const ref of snapshot.frozen_attribute_resource_refs) {
+            const resource = validateResource(ref);
+            const resourceStableId = stableId(resource.node_id, resource.attr_key);
+            if (!unlocked.has(resourceStableId))
+                continue;
+            const duplicate = `${resourceStableId}\u0000${resource.type}\u0000${resource.uri}`;
+            if (seen.has(duplicate))
+                fail("local Preview frozen attribute resource 重复");
+            seen.add(duplicate);
+            const group = groups.get(resourceStableId) ?? { node_id: resource.node_id, attr_key: resource.attr_key, resources: [] };
+            group.resources.push(Object.freeze({ type: resource.type, uri: resource.uri }));
+            groups.set(resourceStableId, group);
+        }
+        return Object.freeze([...groups.values()]
+            .sort((left, right) => left.node_id.localeCompare(right.node_id) || left.attr_key.localeCompare(right.attr_key))
+            .map((group) => Object.freeze({ node_id: group.node_id, attr_key: group.attr_key, resources: Object.freeze([...group.resources].sort((left, right) => left.type.localeCompare(right.type) || left.uri.localeCompare(right.uri))) })));
+    }
+    async #snapshot() {
+        const snapshot = await this.#port.readCommittedPlayerReadModel();
+        if (snapshot === null || typeof snapshot !== "object" || !Array.isArray(snapshot.frozen_attribute_resource_refs)) {
+            fail("local Preview committed player read model 缺失");
+        }
+        const checkpoint = validateCheckpoint(snapshot.scenario_runtime_state);
+        return Object.freeze({ scenario_runtime_state: checkpoint, frozen_attribute_resource_refs: Object.freeze(snapshot.frozen_attribute_resource_refs.map((ref) => validateResource(ref))) });
+    }
+}

package/dist/local-preview-projections.d.ts

@@ -0,0 +1,61 @@
+export interface LocalPreviewCustomStateEntry {
+    readonly key: string;
+    readonly value: unknown;
+    readonly scope: "public" | "protected";
+    readonly authorizedUserIds: readonly string[];
+    readonly revision: number;
+}
+export interface LocalPreviewAsset {
+    readonly id: string;
+    readonly filename: string;
+    readonly mime: string;
+    readonly size: number; /** 同一 immutable capture 的 manifest snapshot 时间。 */
+    readonly createdTs: number;
+    readonly source: "capture"; /** 仅在 host→top-window 传递 hash fence；bridge 不会转发给 iframe。 */
+    readonly sha256: string;
+}
+export interface LocalPreviewOwnedResourceGroup {
+    readonly node_id: string;
+    readonly attr_key: string;
+    readonly resources: readonly Readonly<{
+        type: string;
+        uri: string;
+    }>[];
+}
+export interface LocalPreviewCoreSnapshot {
+    readonly scriptId: string;
+    readonly scenarioId: string; /** 合法新剧本可尚未命名，SDK 返回空字符串而非伪造 scriptId。 */
+    readonly title: string;
+    readonly saveVariables: readonly Readonly<{
+        name: string;
+        scope: "save";
+        valueType: string;
+        value: unknown;
+    }>[];
+    readonly unlocks: Readonly<Record<string, boolean>>;
+}
+export interface LocalPreviewReadOnlyReaders {
+    readonly progress?: () => Promise<number>;
+    /** Host 已按当前 principal 过滤的 View custom state；不能传入 iframe 声明的身份。 */
+    readonly customState?: () => Promise<readonly LocalPreviewCustomStateEntry[]>;
+    readonly ownedResources?: () => Promise<readonly LocalPreviewOwnedResourceGroup[]>;
+    readonly assets?: Readonly<{
+        list: () => Promise<readonly LocalPreviewAsset[]>;
+        getUrl: (asset: LocalPreviewAsset) => Promise<string>;
+    }>;
+}
+/** 从 LocalPreviewRuntime.readProjectionSnapshot 的窄 Host snapshot 读取已有真值。 */
+export declare function localPreviewCoreFromRuntimeSnapshot(value: unknown): LocalPreviewCoreSnapshot;
+/** SDK 只读 dispatcher。扩展读取面各自接入，缺真值不会阻断已可用的 SAV 读取。 */
+export declare class LocalPreviewReadOnlyProjection {
+    #private;
+    constructor(core: LocalPreviewCoreSnapshot, readers?: LocalPreviewReadOnlyReaders);
+    capabilities(): Readonly<{
+        customStateMaxBytes: number;
+        assetMaxBytes: 0;
+        supportsAssets: boolean;
+        supportsEdit: false;
+        supportsDelete: false;
+    }>;
+    handle(method: string, params: unknown): Promise<unknown>;
+}