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

package/dist/local-preview-view-events.d.ts

@@ -0,0 +1,101 @@
+import { type TmwAuthorViewEventV1, type ViewEventDeliveryMessageV1, type ViewInteractionEventV3 } from "@world-engines/tmw";
+export interface LocalPreviewViewRuntimeBinding {
+    /** LocalPreviewRuntime.readViewInteractionBinding() 的 Host-only 原始 layout。 */
+    readonly source: unknown;
+    readonly epoch: number;
+    readonly artifact_digest: string;
+    readonly runtime_contract_hash: string;
+}
+export type LocalPreviewViewSurface = "pc" | "mobile";
+export interface LocalPreviewViewFrameContext {
+    readonly content_window: object;
+    readonly opaque_origin: "null";
+    readonly capture_sha256: string;
+}
+export interface LocalPreviewViewMessage {
+    readonly source: unknown;
+    readonly origin: string;
+    readonly data: unknown;
+}
+export interface LocalPreviewViewExecutionContext {
+    readonly operation_id: string;
+    readonly turn_id: string;
+    readonly world_time?: number | null;
+}
+export interface LocalPreviewViewEventExecutionInput extends LocalPreviewViewExecutionContext {
+    readonly event_type: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * Runtime owner 必须从已持久化的 executeCommittedEvent receipt 返回这些字段。
+ * 只有 status 不足以安全生成 tmw.delivery。
+ */
+export interface LocalPreviewViewDurableExecutionReceipt {
+    readonly status: "committed" | "already_committed";
+    readonly operation_id: string;
+    readonly author_view_events: ReadonlyArray<TmwAuthorViewEventV1>;
+}
+export type LocalPreviewViewEventResult = Readonly<{
+    ok: true;
+    status: LocalPreviewViewDurableExecutionReceipt["status"];
+    operation_id: string;
+    deliveries: ReadonlyArray<ViewEventDeliveryMessageV1>;
+}> | Readonly<{
+    ok: false;
+    code: string;
+    player_message: string;
+    committed: boolean;
+    delivered_count: number;
+}>;
+/** 可交给 iframe SDK 的最小配置；不包含 payload schema、capability、delivery 或 source 内容。 */
+export interface LocalPreviewViewInteractionConfigV3 {
+    readonly schema: "view-interaction-config.v3";
+    readonly generation: 3;
+    readonly manifest_digest: string;
+    readonly epoch: number;
+    readonly artifact_digest: string;
+    readonly runtime_contract_hash: string;
+    readonly events: ReadonlyArray<Readonly<{
+        event_id: string;
+        event_type: string;
+    }>>;
+}
+export interface LocalPreviewViewEventIngress {
+    handle(message: LocalPreviewViewMessage): Promise<LocalPreviewViewEventResult>;
+    /** 仅供已在浏览器父窗口完成 source/origin/capture gate 的同源 Host receiver 使用。 */
+    handleTrustedOpaqueFrameData(data: unknown): Promise<LocalPreviewViewEventResult>;
+    clearReplayWindow(): void;
+}
+export interface CreateLocalPreviewViewEventIngressOptions {
+    readonly capture_sha256: string;
+    readonly binding: LocalPreviewViewRuntimeBinding;
+    /** 本地 GUI 当前只打开 PC View；surface 必须由 Host 选择，不能由 iframe 声称。 */
+    readonly surface: LocalPreviewViewSurface;
+    readonly readCurrentFrame: () => LocalPreviewViewFrameContext | null;
+    /** Host 从当前 turn/session context 派生身份；iframe 不能提供 operation_id/turn_id。 */
+    readonly deriveExecutionContext: (event: ViewInteractionEventV3) => LocalPreviewViewExecutionContext | Promise<LocalPreviewViewExecutionContext>;
+    readonly executeEvent: (input: LocalPreviewViewEventExecutionInput) => Promise<LocalPreviewViewDurableExecutionReceipt>;
+    /** Browser bridge 可提供此回调直接发送通知；server receiver 留空并把 deliveries 回传 bridge。 */
+    readonly publishDelivery?: (topic: "tmw.delivery", delivery: ViewEventDeliveryMessageV1) => void | Promise<void>;
+    readonly maxReplayNonces?: number;
+}
+export declare class LocalPreviewViewEventConfigurationError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare function readLocalPreviewViewInteractionConfig(input: Readonly<{
+    capture_sha256: string;
+    binding: LocalPreviewViewRuntimeBinding;
+    surface: LocalPreviewViewSurface;
+}>): Promise<LocalPreviewViewInteractionConfigV3>;
+export declare function projectLocalPreviewAuthorViewEvents(input: Readonly<{
+    capture_sha256: string;
+    binding: LocalPreviewViewRuntimeBinding;
+    surface: LocalPreviewViewSurface;
+    author_view_events: ReadonlyArray<TmwAuthorViewEventV1>;
+}>): Promise<ReadonlyArray<ViewEventDeliveryMessageV1>>;
+/**
+ * 把 opaque View 的 declared action 接入真实 local TMW commit；所有下行消息均来自
+ * committed receipt 的 authorViewEvents 与 manifest view_deliveries 的交集。
+ */
+export declare function createLocalPreviewViewEventIngress(options: CreateLocalPreviewViewEventIngressOptions): Promise<LocalPreviewViewEventIngress>;

package/dist/local-preview-view-events.js

@@ -0,0 +1,179 @@
+import { createViewInteractionEventGateV3, digestViewInteractionManifestV3, parseViewInteractionSourceV3, projectAuthorViewEventToViewDeliveries, } from "@world-engines/tmw";
+const SHA256 = /^[a-f0-9]{64}$/u;
+const STABLE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+export class LocalPreviewViewEventConfigurationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "LocalPreviewViewEventConfigurationError";
+        this.code = code;
+    }
+}
+const invalid = (code, playerMessage, committed = false, deliveredCount = 0) => Object.freeze({
+    ok: false,
+    code,
+    player_message: playerMessage,
+    committed,
+    delivered_count: deliveredCount,
+});
+const isExecutionContext = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (!STABLE_ID.test(String(candidate.operation_id ?? "")) || !STABLE_ID.test(String(candidate.turn_id ?? ""))) {
+        return false;
+    }
+    return candidate.world_time === undefined
+        || candidate.world_time === null
+        || (typeof candidate.world_time === "number" && Number.isFinite(candidate.world_time));
+};
+const isDurableReceipt = (value, operationId) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return (receipt.status === "committed" || receipt.status === "already_committed")
+        && receipt.operation_id === operationId
+        && Array.isArray(receipt.author_view_events);
+};
+const publicExecutionCode = (error) => {
+    if (typeof error !== "object" || error === null)
+        return "E_OPERATION_UNCERTAIN";
+    const code = error.code;
+    return typeof code === "string" && /^E_[A-Z0-9_]{1,63}$/u.test(code)
+        ? code
+        : "E_OPERATION_UNCERTAIN";
+};
+const assertBoundSource = async (binding, surface, captureSha256) => {
+    if (!SHA256.test(captureSha256)) {
+        throw new LocalPreviewViewEventConfigurationError("local_preview_capture_digest_invalid");
+    }
+    if (typeof binding.source !== "object" || binding.source === null || Array.isArray(binding.source)) {
+        throw new LocalPreviewViewEventConfigurationError("local_preview_view_interaction_layout_missing");
+    }
+    const layout = binding.source;
+    const source = parseViewInteractionSourceV3(layout[`view_interaction_${surface}`]);
+    if (source === null) {
+        throw new LocalPreviewViewEventConfigurationError("local_preview_view_interaction_source_missing");
+    }
+    const digest = await digestViewInteractionManifestV3(source.manifest);
+    if (digest !== source.manifest_digest) {
+        throw new LocalPreviewViewEventConfigurationError("local_preview_view_manifest_digest_mismatch");
+    }
+    if (source.manifest.epoch !== binding.epoch
+        || source.manifest.artifact_digest !== binding.artifact_digest
+        || source.manifest.runtime_contract_hash !== binding.runtime_contract_hash) {
+        throw new LocalPreviewViewEventConfigurationError("local_preview_view_runtime_binding_mismatch");
+    }
+    return source;
+};
+export async function readLocalPreviewViewInteractionConfig(input) {
+    const source = await assertBoundSource(input.binding, input.surface, input.capture_sha256);
+    return Object.freeze({
+        schema: "view-interaction-config.v3",
+        generation: 3,
+        manifest_digest: source.manifest_digest,
+        epoch: source.manifest.epoch,
+        artifact_digest: source.manifest.artifact_digest,
+        runtime_contract_hash: source.manifest.runtime_contract_hash,
+        events: Object.freeze(source.manifest.events.map((event) => Object.freeze({
+            event_id: event.event_id,
+            event_type: event.event_type,
+        }))),
+    });
+}
+export async function projectLocalPreviewAuthorViewEvents(input) {
+    const source = await assertBoundSource(input.binding, input.surface, input.capture_sha256);
+    const deliveries = [];
+    for (const event of input.author_view_events) {
+        const projected = await projectAuthorViewEventToViewDeliveries(event, source.manifest.view_deliveries ?? []);
+        if (!projected.ok)
+            throw new LocalPreviewViewEventConfigurationError(projected.code);
+        deliveries.push(...projected.deliveries);
+    }
+    return Object.freeze(deliveries);
+}
+/**
+ * 把 opaque View 的 declared action 接入真实 local TMW commit；所有下行消息均来自
+ * committed receipt 的 authorViewEvents 与 manifest view_deliveries 的交集。
+ */
+export async function createLocalPreviewViewEventIngress(options) {
+    const source = await assertBoundSource(options.binding, options.surface, options.capture_sha256);
+    const gate = createViewInteractionEventGateV3(source.manifest, source.manifest_digest, options.maxReplayNonces);
+    const handleTrustedOpaqueFrameData = async (data) => {
+        const parsed = gate.parse(data);
+        if (!parsed.ok)
+            return invalid(parsed.code, "此操作无效或已过期，请刷新后重试");
+        let context;
+        try {
+            context = await options.deriveExecutionContext(parsed.event);
+        }
+        catch {
+            return invalid("view_event_execution_context_unavailable", "当前回合尚未准备好，请稍后重试");
+        }
+        if (!isExecutionContext(context)) {
+            return invalid("view_event_execution_context_invalid", "当前回合尚未准备好，请稍后重试");
+        }
+        const executionInput = Object.freeze({
+            event_type: parsed.event.event_type,
+            payload: parsed.event.payload,
+            operation_id: context.operation_id,
+            turn_id: context.turn_id,
+            ...(context.world_time === undefined ? {} : { world_time: context.world_time }),
+        });
+        let receipt;
+        try {
+            const executed = await options.executeEvent(executionInput);
+            if (!isDurableReceipt(executed, context.operation_id)) {
+                return invalid("view_event_durable_receipt_invalid", "操作结果未能确认，请检查预览状态");
+            }
+            receipt = executed;
+        }
+        catch (error) {
+            return invalid(publicExecutionCode(error), "操作未提交，请检查预览状态后重试");
+        }
+        const deliveries = [];
+        for (const authorViewEvent of receipt.author_view_events) {
+            const projected = await projectAuthorViewEventToViewDeliveries(authorViewEvent, source.manifest.view_deliveries ?? []);
+            if (!projected.ok)
+                return invalid(projected.code, "操作已提交，但界面更新数据无效", true, deliveries.length);
+            deliveries.push(...projected.deliveries);
+        }
+        let deliveredCount = 0;
+        if (options.publishDelivery !== undefined) {
+            try {
+                for (const delivery of deliveries) {
+                    await options.publishDelivery("tmw.delivery", delivery);
+                    deliveredCount += 1;
+                }
+            }
+            catch {
+                return invalid("view_delivery_publish_failed", "操作已提交，但界面更新失败，请刷新查看结果", true, deliveredCount);
+            }
+        }
+        return Object.freeze({
+            ok: true,
+            status: receipt.status,
+            operation_id: receipt.operation_id,
+            deliveries: Object.freeze([...deliveries]),
+        });
+    };
+    return Object.freeze({
+        async handle(message) {
+            const frame = options.readCurrentFrame();
+            if (frame === null
+                || message.source !== frame.content_window
+                || message.origin !== frame.opaque_origin
+                || frame.opaque_origin !== "null") {
+                return invalid("view_event_frame_authority_denied", "此操作不属于当前预览页面");
+            }
+            if (frame.capture_sha256 !== options.capture_sha256) {
+                return invalid("stale_content_capture", "预览内容已更新，请刷新后重试");
+            }
+            return await handleTrustedOpaqueFrameData(message.data);
+        },
+        handleTrustedOpaqueFrameData,
+        clearReplayWindow() {
+            gate.clear();
+        },
+    });
+}

package/dist/local-preview-view-state-sqlite.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { LocalPreviewCustomStateEntry, LocalPreviewRuntimeHead, LocalPreviewViewStateRuntimePort, LocalPreviewViewStateScope, LocalPreviewViewStateSnapshot } from "./local-preview-view-state.js";
+type PublicScope = Omit<LocalPreviewViewStateScope, "principalId">;
+export declare class LocalPreviewViewStateSqlitePort implements LocalPreviewViewStateRuntimePort {
+    #private;
+    constructor(input: Readonly<{
+        database: DatabaseSync;
+        scope: PublicScope;
+    }>);
+    initialize(scope: PublicScope): Promise<LocalPreviewViewStateSnapshot>;
+    read(scope: PublicScope): Promise<LocalPreviewViewStateSnapshot>;
+    commitRuntimeOutput(input: Readonly<{
+        scope: PublicScope;
+        operationId: string;
+        expectedRuntimeHead: LocalPreviewRuntimeHead;
+        expectedGeneration: number;
+        entries: readonly LocalPreviewCustomStateEntry[];
+    }>): Promise<Readonly<{
+        snapshot: LocalPreviewViewStateSnapshot;
+        changedKeys: readonly string[];
+        replayed: boolean;
+    }>>;
+}
+export {};

package/dist/local-preview-view-state-sqlite.js

@@ -0,0 +1,263 @@
+import { createHash } from "node:crypto";
+/**
+ * The durable local Preview implementation of the View-state Runtime port.
+ *
+ * It intentionally owns neither an SQLite file nor a runtime head.  The
+ * Runtime passes its already-open activation.sqlite connection and this port
+ * stores its small, capture-bound read model inside `projection.views`.  A
+ * worldline checkout consequently brings the exact same projection (including
+ * custom state) along with the SAV instead of creating a second authority.
+ */
+const NAMESPACE = "chatplay.custom-state.v1";
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const MAX_ENTRIES = 256;
+const MAX_AUTHORIZED_USERS = 64;
+const MAX_ENTRY_JSON_BYTES = 64 * 1024;
+const MAX_VIEW_SNAPSHOT_JSON_BYTES = 16 * 1024 * 1024;
+export class LocalPreviewViewStateSqlitePort {
+    #db;
+    #scope;
+    constructor(input) {
+        assertScope(input.scope);
+        this.#db = input.database;
+        this.#scope = Object.freeze({ ...input.scope });
+        // Kept separate from the TMW activation receipts: operation ids share a
+        // caller namespace only within this View-state protocol, not across TMW.
+        this.#db.exec("CREATE TABLE IF NOT EXISTS local_preview_view_state_receipt (scope_key TEXT NOT NULL, operation_id TEXT NOT NULL, request_digest TEXT NOT NULL, result_json TEXT NOT NULL, PRIMARY KEY(scope_key,operation_id));");
+    }
+    async initialize(scope) {
+        this.#assertScope(scope);
+        return this.#transaction(() => {
+            const head = this.#readHead();
+            const projection = this.#readProjection();
+            const stored = this.#storedSnapshot(projection);
+            if (stored !== null)
+                return snapshot(this.#scope, head, stored);
+            const initialized = Object.freeze({ scope: this.#scope, generation: 0, entries: Object.freeze([]) });
+            this.#writeProjection(withStoredSnapshot(projection, initialized));
+            return snapshot(this.#scope, head, initialized);
+        });
+    }
+    async read(scope) {
+        this.#assertScope(scope);
+        const stored = this.#storedSnapshot(this.#readProjection());
+        if (stored === null)
+            fail("reader_missing");
+        return snapshot(this.#scope, this.#readHead(), stored);
+    }
+    async commitRuntimeOutput(input) {
+        this.#assertScope(input.scope);
+        assertId(input.operationId, "operation_id");
+        assertHead(input.expectedRuntimeHead);
+        if (!Number.isSafeInteger(input.expectedGeneration) || input.expectedGeneration < 0)
+            fail("invalid_generation");
+        assertEntries(input.entries);
+        const requestDigest = digest({ scope: this.#scope, operationId: input.operationId, expectedRuntimeHead: input.expectedRuntimeHead, expectedGeneration: input.expectedGeneration, entries: input.entries });
+        return this.#transaction(() => {
+            const prior = this.#receipt(input.operationId);
+            if (prior !== null) {
+                if (prior.requestDigest !== requestDigest)
+                    fail("operation_id_conflict");
+                return Object.freeze({ snapshot: clone(prior.snapshot), changedKeys: Object.freeze([...prior.changedKeys]), replayed: true });
+            }
+            const head = this.#readHead();
+            if (!sameHead(head, input.expectedRuntimeHead))
+                fail("cas_conflict");
+            const projection = this.#readProjection();
+            const current = this.#storedSnapshot(projection);
+            if (current === null)
+                fail("reader_missing");
+            if (current.generation !== input.expectedGeneration)
+                fail("cas_conflict");
+            const changedKeys = changed(current.entries, input.entries);
+            const next = changedKeys.length === 0
+                ? current
+                : Object.freeze({ scope: this.#scope, generation: current.generation + 1, entries: freezeEntries(input.entries) });
+            const nextSnapshot = snapshot(this.#scope, head, next);
+            // A no-op deliberately records its receipt but does not advance the view
+            // generation nor rewrite projection.  This keeps next formal outputs
+            // correctly fenced while making retries deterministic.
+            if (changedKeys.length > 0)
+                this.#writeProjection(withStoredSnapshot(projection, next));
+            const receipt = Object.freeze({ requestDigest, snapshot: nextSnapshot, changedKeys: Object.freeze(changedKeys) });
+            this.#db.prepare("INSERT INTO local_preview_view_state_receipt(scope_key,operation_id,request_digest,result_json) VALUES (?,?,?,?)").run(scopeKey(this.#scope), input.operationId, requestDigest, JSON.stringify(receipt));
+            return Object.freeze({ snapshot: clone(nextSnapshot), changedKeys: Object.freeze(changedKeys), replayed: false });
+        });
+    }
+    #assertScope(scope) {
+        assertScope(scope);
+        if (scope.captureId !== this.#scope.captureId || scope.namespace !== this.#scope.namespace || scope.saveId !== this.#scope.saveId || scope.viewId !== this.#scope.viewId)
+            fail("scope_mismatch");
+    }
+    #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 });
+    }
+    #readProjection() {
+        const row = this.#db.prepare("SELECT value FROM local_preview_state WHERE key='projection'").get();
+        if (row === undefined)
+            fail("projection_missing");
+        let value;
+        try {
+            value = JSON.parse(row.value);
+        }
+        catch {
+            fail("projection_invalid");
+        }
+        if (!isRecord(value) || !isRecord(value.entities) || !Array.isArray(value.emitted_events))
+            fail("projection_invalid");
+        if (value.views !== undefined && !isRecord(value.views))
+            fail("projection_invalid");
+        return value;
+    }
+    #storedSnapshot(projection) {
+        const namespaced = projection.views?.[NAMESPACE];
+        if (namespaced === undefined)
+            return null;
+        if (!isRecord(namespaced))
+            fail("projection_view_namespace_invalid");
+        const candidate = namespaced[this.#scope.viewId];
+        if (candidate === undefined)
+            return null;
+        return parseStoredSnapshot(candidate, this.#scope);
+    }
+    #writeProjection(projection) {
+        const serialized = JSON.stringify(projection);
+        if (new TextEncoder().encode(serialized).byteLength > MAX_VIEW_SNAPSHOT_JSON_BYTES + 64 * 1024 * 1024)
+            fail("projection_oversize");
+        this.#db.prepare("INSERT OR REPLACE INTO local_preview_state(key,value) VALUES ('projection',?)").run(serialized);
+    }
+    #receipt(operationId) {
+        const row = this.#db.prepare("SELECT request_digest,result_json FROM local_preview_view_state_receipt WHERE scope_key=? AND operation_id=?").get(scopeKey(this.#scope), operationId);
+        if (row === undefined)
+            return null;
+        let stored;
+        try {
+            stored = JSON.parse(row.result_json);
+        }
+        catch {
+            fail("receipt_invalid");
+        }
+        if (!isRecord(stored) || typeof stored.requestDigest !== "string" || !Array.isArray(stored.changedKeys) || !isRecord(stored.snapshot))
+            fail("receipt_invalid");
+        if (stored.requestDigest !== row.request_digest || stored.changedKeys.some((key) => typeof key !== "string" || !ID.test(key)) || new Set(stored.changedKeys).size !== stored.changedKeys.length)
+            fail("receipt_invalid");
+        const result = Object.freeze({ requestDigest: stored.requestDigest, snapshot: parseSnapshot(stored.snapshot, this.#scope), changedKeys: Object.freeze([...stored.changedKeys]) });
+        return result;
+    }
+    #transaction(work) {
+        if (this.#db.isTransaction === true)
+            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 withStoredSnapshot(projection, stored) {
+    const copy = clone(projection);
+    const views = isRecord(copy.views) ? copy.views : {};
+    const namespaced = isRecord(views[NAMESPACE]) ? views[NAMESPACE] : {};
+    namespaced[stored.scope.viewId] = clone(stored);
+    views[NAMESPACE] = namespaced;
+    copy.views = views;
+    return copy;
+}
+function parseStoredSnapshot(value, scope) {
+    if (!isRecord(value) || !isRecord(value.scope) || typeof value.generation !== "number" || !Number.isSafeInteger(value.generation) || value.generation < 0 || !Array.isArray(value.entries))
+        fail("stored_snapshot_invalid");
+    const storedScope = value.scope;
+    const generation = value.generation;
+    const entries = value.entries;
+    assertScope(storedScope);
+    if (!sameScope(storedScope, scope))
+        fail("stored_scope_mismatch");
+    assertEntries(entries);
+    const stored = Object.freeze({ scope: Object.freeze({ ...scope }), generation, entries: freezeEntries(entries) });
+    if (new TextEncoder().encode(JSON.stringify(stored)).byteLength > MAX_VIEW_SNAPSHOT_JSON_BYTES)
+        fail("stored_snapshot_oversize");
+    return stored;
+}
+function parseSnapshot(value, scope) {
+    if (!isRecord(value.scope) || !isRecord(value.runtimeHead) || typeof value.generation !== "number" || !Number.isSafeInteger(value.generation) || value.generation < 0 || !Array.isArray(value.entries))
+        fail("receipt_invalid");
+    const storedScope = value.scope;
+    const storedHead = value.runtimeHead;
+    const generation = value.generation;
+    const entries = value.entries;
+    assertScope(storedScope);
+    if (!sameScope(storedScope, scope))
+        fail("receipt_invalid");
+    assertHead(storedHead);
+    assertEntries(entries);
+    return Object.freeze({ scope: Object.freeze({ ...scope }), runtimeHead: Object.freeze({ ...storedHead }), generation, entries: freezeEntries(entries) });
+}
+function snapshot(scope, runtimeHead, stored) {
+    return Object.freeze({ scope: Object.freeze({ ...scope }), runtimeHead: Object.freeze({ ...runtimeHead }), generation: stored.generation, entries: freezeEntries(stored.entries) });
+}
+function assertScope(scope) {
+    if (!isRecord(scope) || !ID.test(scope.captureId) || scope.namespace !== NAMESPACE || !ID.test(scope.saveId) || !ID.test(scope.viewId))
+        fail("invalid_scope");
+}
+function assertId(value, label) { if (typeof value !== "string" || !ID.test(value))
+    fail(`invalid_${label}`); }
+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 assertEntries(entries) {
+    if (entries.length > MAX_ENTRIES || new Set(entries.map((entry) => entry.key)).size !== entries.length)
+        fail("invalid_entries");
+    for (const entry of entries) {
+        if (!isRecord(entry) || !ID.test(entry.key) || (entry.scope !== "public" && entry.scope !== "protected") || !Number.isSafeInteger(entry.revision) || entry.revision < 0)
+            fail("invalid_entry");
+        if (!Array.isArray(entry.authorizedUserIds) || entry.authorizedUserIds.length > MAX_AUTHORIZED_USERS || new Set(entry.authorizedUserIds).size !== entry.authorizedUserIds.length || entry.authorizedUserIds.some((id) => !ID.test(id)))
+            fail("invalid_authorized_users");
+        if ((entry.scope === "public" && entry.authorizedUserIds.length !== 0) || (entry.scope === "protected" && entry.authorizedUserIds.length === 0))
+            fail("invalid_authorized_users");
+        if (!validJson(entry.value) || new TextEncoder().encode(JSON.stringify(entry.value)).byteLength > MAX_ENTRY_JSON_BYTES)
+            fail("invalid_or_oversize_value");
+    }
+}
+function validJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(validJson);
+    return isRecord(value) && Object.values(value).every(validJson);
+}
+function freezeEntries(entries) { return Object.freeze(entries.map((entry) => Object.freeze({ ...entry, value: clone(entry.value), authorizedUserIds: Object.freeze([...entry.authorizedUserIds]) }))); }
+function changed(before, after) {
+    const keys = new Set([...before.map((entry) => entry.key), ...after.map((entry) => entry.key)]);
+    return [...keys].filter((key) => JSON.stringify(before.find((entry) => entry.key === key)) !== JSON.stringify(after.find((entry) => entry.key === key))).sort();
+}
+function sameScope(left, right) { return left.captureId === right.captureId && left.namespace === right.namespace && left.saveId === right.saveId && left.viewId === right.viewId; }
+function sameHead(left, right) { return left.revisionId === right.revisionId && left.revisionSequence === right.revisionSequence && left.ledgerHead === right.ledgerHead; }
+function scopeKey(scope) { return digest(scope); }
+function digest(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+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_view_state_sqlite:${code}`); }

package/dist/local-preview-view-state.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 本地 Preview 的 View custom state read model。
+ *
+ * 这个模块不拥有文件或 SQLite。Runtime owner 必须把 snapshot/commit 接到同一
+ * runtime SAV envelope 的 projection[viewId]，并复用 runtime 的 head CAS 与
+ * operation receipt；因此不会产生第二个 local save authority。
+ */
+declare const NAMESPACE = "chatplay.custom-state.v1";
+/** 单个 view custom-state entry 的真实持久化上限，供 Host capability 投影复用。 */
+export declare const LOCAL_PREVIEW_CUSTOM_STATE_MAX_BYTES: number;
+export type LocalPreviewCustomStateScope = "public" | "protected";
+export type LocalPreviewJsonValue = null | boolean | number | string | readonly LocalPreviewJsonValue[] | {
+    readonly [key: string]: LocalPreviewJsonValue;
+};
+export interface LocalPreviewViewStateScope {
+    /** Host capture 的 immutable identity；不可来自 iframe request。 */
+    readonly captureId: string;
+    readonly namespace: typeof NAMESPACE;
+    readonly saveId: string;
+    readonly viewId: string;
+    /** Host 已认证的 principal；null 时只允许 public entry。 */
+    readonly principalId: string | null;
+}
+export interface LocalPreviewCustomStateEntry {
+    readonly key: string;
+    readonly value: LocalPreviewJsonValue;
+    readonly scope: LocalPreviewCustomStateScope;
+    readonly authorizedUserIds: readonly string[];
+    readonly revision: number;
+}
+/** 与 LocalPreviewActivationStore activeHead 同一份 runtime authority。 */
+export interface LocalPreviewRuntimeHead {
+    readonly revisionId: string;
+    readonly revisionSequence: number;
+    readonly ledgerHead: string | null;
+}
+/** 已持久化且已绑定本 Host scope 的 view projection。空 entries 是新 save 的合法状态。 */
+export interface LocalPreviewViewStateSnapshot {
+    readonly scope: Omit<LocalPreviewViewStateScope, "principalId">;
+    readonly runtimeHead: LocalPreviewRuntimeHead;
+    readonly generation: number;
+    readonly entries: readonly LocalPreviewCustomStateEntry[];
+}
+export interface LocalPreviewRuntimeStateOutput {
+    /** 只有 Runtime commit 或正式 action output 可构造并调用这个输入。 */
+    readonly source: "runtime-action-output";
+    readonly operationId: string;
+    readonly expectedRuntimeHead: LocalPreviewRuntimeHead;
+    readonly expectedGeneration: number;
+    readonly entries: readonly LocalPreviewCustomStateEntry[];
+}
+/**
+ * Runtime owner 的唯一 persistence seam。
+ * initialize 必须真实创建 envelope projection 中的空 view store；read 不得把
+ * 缺少 reader/snapshot 伪装成空数组。commit 必须在 runtime 同一 SQLite transaction
+ * 中检查 head/generation、保存 operation receipt，并返回 replayed receipt。
+ */
+export interface LocalPreviewViewStateRuntimePort {
+    initialize(scope: Omit<LocalPreviewViewStateScope, "principalId">): Promise<LocalPreviewViewStateSnapshot>;
+    read(scope: Omit<LocalPreviewViewStateScope, "principalId">): Promise<LocalPreviewViewStateSnapshot>;
+    commitRuntimeOutput(input: Readonly<{
+        scope: Omit<LocalPreviewViewStateScope, "principalId">;
+        operationId: string;
+        expectedRuntimeHead: LocalPreviewRuntimeHead;
+        expectedGeneration: number;
+        entries: readonly LocalPreviewCustomStateEntry[];
+    }>): Promise<Readonly<{
+        snapshot: LocalPreviewViewStateSnapshot;
+        changedKeys: readonly string[];
+        replayed: boolean;
+    }>>;
+}
+export interface LocalPreviewCustomStateCommitResult {
+    readonly generation: number;
+    readonly changedKeys: readonly string[];
+    readonly entries: readonly LocalPreviewCustomStateEntry[];
+    readonly replayed: boolean;
+}
+/** Host-only facade. It deliberately contains no request-selected identity or iframe mutation API. */
+export declare class LocalPreviewViewStateStore {
+    #private;
+    private constructor();
+    static open(scope: LocalPreviewViewStateScope, port: LocalPreviewViewStateRuntimePort): Promise<LocalPreviewViewStateStore>;
+    keys(): Promise<readonly string[]>;
+    /** 给 LocalPreviewReadOnlyProjection 的 customState reader 使用，结果已经按 Host principal 过滤。 */
+    entries(): Promise<readonly LocalPreviewCustomStateEntry[]>;
+    get(key: string): Promise<LocalPreviewJsonValue | undefined>;
+    getEntry(key: string): Promise<LocalPreviewCustomStateEntry | undefined>;
+    /** Runtime owner calls this after a formal action output; View RPC never gets this method. */
+    commitRuntimeOutput(output: LocalPreviewRuntimeStateOutput): Promise<LocalPreviewCustomStateCommitResult>;
+}
+export declare const LOCAL_PREVIEW_VIEW_STATE_NAMESPACE = "chatplay.custom-state.v1";
+export {};