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

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

@@ -0,0 +1,108 @@
+/**
+ * 本地 Preview 的 View custom state read model。
+ *
+ * 这个模块不拥有文件或 SQLite。Runtime owner 必须把 snapshot/commit 接到同一
+ * runtime SAV envelope 的 projection[viewId]，并复用 runtime 的 head CAS 与
+ * operation receipt；因此不会产生第二个 local save authority。
+ */
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const NAMESPACE = "chatplay.custom-state.v1";
+const MAX_ENTRIES = 256;
+const MAX_AUTHORIZED_USERS = 64;
+/** 单个 view custom-state entry 的真实持久化上限，供 Host capability 投影复用。 */
+export const LOCAL_PREVIEW_CUSTOM_STATE_MAX_BYTES = 64 * 1024;
+function fail(message) { throw new Error(`local_preview_view_state:${message}`); }
+function publicScope(scope) {
+    return Object.freeze({ captureId: scope.captureId, namespace: scope.namespace, saveId: scope.saveId, viewId: scope.viewId });
+}
+function clone(value) { return JSON.parse(JSON.stringify(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 typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every(validJson);
+}
+function assertScope(scope) {
+    if (!ID.test(scope.captureId) || scope.namespace !== NAMESPACE || !ID.test(scope.saveId) || !ID.test(scope.viewId))
+        fail("invalid_scope");
+    if ("principalId" in scope && scope.principalId !== null && !ID.test(scope.principalId))
+        fail("invalid_principal");
+}
+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 (!ID.test(entry.key) || (entry.scope !== "public" && entry.scope !== "protected") || !Number.isSafeInteger(entry.revision) || entry.revision < 0)
+            fail("invalid_entry");
+        if (entry.authorizedUserIds.length > MAX_AUTHORIZED_USERS || new Set(entry.authorizedUserIds).size !== entry.authorizedUserIds.length || entry.authorizedUserIds.some((userId) => !ID.test(userId)))
+            fail("invalid_authorized_users");
+        if (entry.scope === "public" && entry.authorizedUserIds.length !== 0)
+            fail("public_authorized_users");
+        if (entry.scope === "protected" && entry.authorizedUserIds.length === 0)
+            fail("protected_without_authorized_user");
+        if (!validJson(entry.value) || new TextEncoder().encode(JSON.stringify(entry.value)).byteLength > LOCAL_PREVIEW_CUSTOM_STATE_MAX_BYTES)
+            fail("invalid_or_oversize_value");
+    }
+}
+function assertSnapshot(expected, snapshot) {
+    assertScope(snapshot.scope);
+    if (snapshot.scope.captureId !== expected.captureId || snapshot.scope.namespace !== expected.namespace || snapshot.scope.saveId !== expected.saveId || snapshot.scope.viewId !== expected.viewId || !Number.isSafeInteger(snapshot.generation) || snapshot.generation < 0)
+        fail("snapshot_scope_or_generation_mismatch");
+    assertRuntimeHead(snapshot.runtimeHead);
+    assertEntries(snapshot.entries);
+}
+function assertRuntimeHead(head) {
+    if (!ID.test(head.revisionId) || !Number.isSafeInteger(head.revisionSequence) || head.revisionSequence < 0 || (head.ledgerHead !== null && !ID.test(head.ledgerHead)))
+        fail("invalid_runtime_head");
+}
+function authorized(scope, entry) {
+    return entry.scope === "public" || (scope.principalId !== null && entry.authorizedUserIds.includes(scope.principalId));
+}
+function immutableEntries(entries) {
+    return Object.freeze(entries.map((entry) => Object.freeze({ ...entry, value: clone(entry.value), authorizedUserIds: Object.freeze([...entry.authorizedUserIds]) })));
+}
+/** Host-only facade. It deliberately contains no request-selected identity or iframe mutation API. */
+export class LocalPreviewViewStateStore {
+    #scope;
+    #port;
+    constructor(scope, port) { this.#scope = Object.freeze({ ...scope }); this.#port = port; }
+    static async open(scope, port) {
+        assertScope(scope);
+        const publicViewScope = publicScope(scope);
+        const initialized = await port.initialize(publicViewScope);
+        assertSnapshot(publicViewScope, initialized);
+        return new LocalPreviewViewStateStore(scope, port);
+    }
+    async keys() { return (await this.#authorizedSnapshot()).entries.map((entry) => entry.key).sort(); }
+    /** 给 LocalPreviewReadOnlyProjection 的 customState reader 使用，结果已经按 Host principal 过滤。 */
+    async entries() { return (await this.#authorizedSnapshot()).entries; }
+    async get(key) { const entry = await this.getEntry(key); return entry === undefined ? undefined : clone(entry.value); }
+    async getEntry(key) {
+        if (!ID.test(key))
+            fail("invalid_key");
+        const entry = (await this.#authorizedSnapshot()).entries.find((candidate) => candidate.key === key);
+        return entry === undefined ? undefined : immutableEntries([entry])[0];
+    }
+    /** Runtime owner calls this after a formal action output; View RPC never gets this method. */
+    async commitRuntimeOutput(output) {
+        if (output.source !== "runtime-action-output" || !ID.test(output.operationId) || !Number.isSafeInteger(output.expectedGeneration) || output.expectedGeneration < 0)
+            fail("invalid_runtime_output");
+        assertRuntimeHead(output.expectedRuntimeHead);
+        assertEntries(output.entries);
+        const result = await this.#port.commitRuntimeOutput({ scope: publicScope(this.#scope), operationId: output.operationId, expectedRuntimeHead: Object.freeze({ ...output.expectedRuntimeHead }), expectedGeneration: output.expectedGeneration, entries: immutableEntries(output.entries) });
+        assertSnapshot(publicScope(this.#scope), result.snapshot);
+        if (new Set(result.changedKeys).size !== result.changedKeys.length || result.changedKeys.some((key) => !ID.test(key)))
+            fail("invalid_changed_keys");
+        return Object.freeze({ generation: result.snapshot.generation, changedKeys: Object.freeze([...result.changedKeys].sort()), entries: immutableEntries(result.snapshot.entries), replayed: result.replayed });
+    }
+    async #authorizedSnapshot() {
+        const scope = publicScope(this.#scope);
+        const snapshot = await this.#port.read(scope);
+        assertSnapshot(scope, snapshot);
+        return Object.freeze({ generation: snapshot.generation, entries: immutableEntries(snapshot.entries.filter((entry) => authorized(this.#scope, entry))) });
+    }
+}
+export const LOCAL_PREVIEW_VIEW_STATE_NAMESPACE = NAMESPACE;

package/dist/local-preview-vite-config.d.ts

@@ -0,0 +1,6 @@
+export interface LocalPreviewViteConfig {
+    readonly path: string;
+    readonly basePath: string;
+}
+export declare function writeLocalPreviewViteConfig(projectRoot: string, viewRoot: string, port: number, parentOrigin?: string): Promise<LocalPreviewViteConfig>;
+export declare function removeLocalPreviewViteConfig(projectRoot: string, path: string): Promise<void>;

package/dist/local-preview-vite-config.js

@@ -0,0 +1,122 @@
+import { randomBytes } from "node:crypto";
+import { lstat, open, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { LOCAL_GUI_HOST, LOCAL_GUI_ORIGIN } from "./local-gui-contract.js";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory } from "./safe-project-path.js";
+const CONFIG_NAMES = [
+    "vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs",
+    "vite.config.cts", "vite.config.cjs",
+];
+const CONFIG_PREFIX = "preview-vite-";
+function source(userConfigUrl, previewOrigin, parentOrigin, basePath) {
+    return `import userConfig from ${JSON.stringify(userConfigUrl)};
+const PREVIEW_ORIGIN=${JSON.stringify(previewOrigin)};
+const PARENT_ORIGIN=${JSON.stringify(parentOrigin)};
+const BASE_PATH=${JSON.stringify(basePath)};
+const EXPECTED_HOST=new URL(PREVIEW_ORIGIN).host;
+const MODULE_DESTINATIONS=new Set(["script","worker","sharedworker","style","font"]);
+const deny=(response)=>{response.statusCode=403;response.end("Forbidden");};
+const securityPlugin={
+  name:"worldengine-local-preview-security",
+  enforce:"pre",
+  configureServer(server){
+    server.middlewares.use((request,response,next)=>{
+      let url;
+      try{url=new URL(request.url||"/",PREVIEW_ORIGIN);}catch{return deny(response);}
+      if(request.headers.host!==EXPECTED_HOST)return deny(response);
+      if(!url.pathname.startsWith(BASE_PATH))return deny(response);
+      const relativePath="/"+url.pathname.slice(BASE_PATH.length);
+      response.setHeader("Content-Security-Policy","frame-ancestors "+PARENT_ORIGIN);
+      response.setHeader("Cache-Control","no-store");
+      response.setHeader("X-Content-Type-Options","nosniff");
+      response.setHeader("Referrer-Policy","origin");
+      if(relativePath.startsWith("/__chatplay/"))return deny(response);
+      const origin=request.headers.origin;
+      if(origin===undefined){if(request.method!=="GET")return deny(response);return next();}
+      if(origin!=="null"||request.method!=="GET")return deny(response);
+      if(request.headers["sec-fetch-mode"]!=="cors"||!MODULE_DESTINATIONS.has(request.headers["sec-fetch-dest"]||""))return deny(response);
+      response.setHeader("Access-Control-Allow-Origin","null");
+      response.setHeader("Vary","Origin");
+      next();
+    });
+    server.httpServer?.prependListener("upgrade",(request,socket)=>{
+      const protocol=request.headers["sec-websocket-protocol"];
+      if(protocol!=="vite-hmr"&&protocol!=="vite-ping")return;
+      let pathname="";try{pathname=new URL(request.url||"/",PREVIEW_ORIGIN).pathname;}catch{}
+      if(request.headers.host!==EXPECTED_HOST||request.headers.origin!=="null"||pathname!==BASE_PATH)socket.destroy();
+    });
+  },
+};
+export default async(env)=>{
+  const resolved=typeof userConfig==="function"?await userConfig(env):await userConfig;
+  if(!resolved||typeof resolved!=="object")throw new Error("worldengine_preview_vite_config_invalid");
+  const hmr=resolved.server?.hmr;
+  return {...resolved,
+    base:BASE_PATH,
+    legacy:{...(resolved.legacy||{}),skipWebSocketTokenCheck:false},
+    server:{...(resolved.server||{}),cors:false,hmr:{...(hmr&&typeof hmr==="object"?hmr:{}),host:"localhost"}},
+    plugins:[securityPlugin,...(Array.isArray(resolved.plugins)?resolved.plugins:[])],
+  };
+};
+`;
+}
+export async function writeLocalPreviewViteConfig(projectRoot, viewRoot, port, parentOrigin = LOCAL_GUI_ORIGIN) {
+    let parent;
+    try {
+        parent = new URL(parentOrigin);
+    }
+    catch {
+        throw new Error("worldengine_preview_parent_origin_invalid");
+    }
+    if (parent.protocol !== "http:" || parent.hostname !== LOCAL_GUI_HOST || parent.port === "" || parent.pathname !== "/" || parent.search !== "" || parent.hash !== "" || parent.username !== "" || parent.password !== "") {
+        throw new Error("worldengine_preview_parent_origin_invalid");
+    }
+    const matches = [];
+    for (const name of CONFIG_NAMES) {
+        const candidate = join(viewRoot, name);
+        try {
+            const info = await lstat(candidate);
+            if (info.isSymbolicLink() || !info.isFile())
+                throw new Error("unsafe config");
+            matches.push(candidate);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    if (matches.length !== 1)
+        throw new Error("worldengine_preview_vite_config_not_unique");
+    const directory = await ensureSafeProjectDirectory(projectRoot, ".worldengine");
+    const output = join(directory, `${CONFIG_PREFIX}${randomBytes(16).toString("hex")}.config.mjs`);
+    const basePath = `/_worldengine_preview/${randomBytes(16).toString("hex")}/`;
+    const handle = await open(output, "wx", 0o600);
+    try {
+        await handle.writeFile(source(pathToFileURL(matches[0]).href, `http://localhost:${port}`, parent.origin, basePath), "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    return Object.freeze({ path: output, basePath });
+}
+export async function removeLocalPreviewViteConfig(projectRoot, path) {
+    let canonical;
+    try {
+        canonical = await assertSafeExistingProjectPath(projectRoot, path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const name = canonical.slice(canonical.lastIndexOf("\\") + 1).slice(canonical.lastIndexOf("/") + 1);
+    if (!name.startsWith(CONFIG_PREFIX) || !/^[a-f0-9]{32}[.]config[.]mjs$/u.test(name.slice(CONFIG_PREFIX.length))) {
+        throw new Error("worldengine_preview_vite_config_owner_invalid");
+    }
+    const info = await lstat(canonical);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new Error("worldengine_preview_vite_config_owner_invalid");
+    await rm(canonical);
+}

package/dist/local-preview-world-effects.d.ts

@@ -0,0 +1,9 @@
+import { type EffectPlan, type TmwJsonValue } from "@world-engines/tmw";
+export interface LocalPreviewWorldProjection {
+    readonly entities: Readonly<Record<string, TmwJsonValue>>;
+    readonly emitted_events: ReadonlyArray<TmwJsonValue>;
+    readonly [key: string]: unknown;
+}
+export declare function createLocalPreviewWorldProjection(logicalGraph: unknown): LocalPreviewWorldProjection;
+/** 纯 reducer：不写文件、不触发递归事件，只返回待 activation 一并提交的 projection。 */
+export declare function reduceLocalPreviewWorldEffects(current: LocalPreviewWorldProjection, plans: ReadonlyArray<EffectPlan>, maxEvents?: number): LocalPreviewWorldProjection;

package/dist/local-preview-world-effects.js

@@ -0,0 +1,55 @@
+import { canonicalTmwJsonValue } from "@world-engines/tmw";
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error(code);
+    return structuredClone(value);
+}
+export function createLocalPreviewWorldProjection(logicalGraph) {
+    const graph = typeof logicalGraph === "object" && logicalGraph !== null && !Array.isArray(logicalGraph) ? logicalGraph : {};
+    const rows = Array.isArray(graph.entities) ? graph.entities : [];
+    const entities = {};
+    for (const row of rows) {
+        if (typeof row !== "object" || row === null || Array.isArray(row))
+            throw new Error("local_preview_world_entity_invalid");
+        const candidate = row;
+        const id = candidate.entity_id ?? candidate.id;
+        if (typeof id !== "string" || id.length === 0)
+            throw new Error("local_preview_world_entity_id_invalid");
+        if (Object.hasOwn(entities, id))
+            throw new Error("local_preview_world_entity_id_duplicate");
+        entities[id] = canonicalTmwJsonValue({ ...candidate, entity_id: id }, "local_preview_world_entity");
+    }
+    return Object.freeze({ entities: Object.freeze(entities), emitted_events: Object.freeze([]), scenario_runtime_state: Object.freeze({ schema_version: 1, state_revision: "0", progress: 0, unlocked_resource_ids: Object.freeze([]) }), frozen_attribute_resource_refs: Object.freeze([]) });
+}
+/** 纯 reducer：不写文件、不触发递归事件，只返回待 activation 一并提交的 projection。 */
+export function reduceLocalPreviewWorldEffects(current, plans, maxEvents = 64) {
+    const entities = record(current.entities, "local_preview_world_entities_invalid");
+    const emittedEvents = [...current.emitted_events];
+    for (const effect of plans.flatMap((plan) => plan.status === "ready" ? plan.effects : [])) {
+        if (effect.capabilityId === "world.set_attribute") {
+            if (effect.selector?.op !== "entity_id")
+                throw new Error("local_preview_world_entity_id_selector_required");
+            const args = record(effect.input, "local_preview_world_set_attribute_arguments_invalid");
+            if (!Array.isArray(args.path) || args.path.length === 0 || args.path.some((item) => typeof item !== "string" || item.length === 0))
+                throw new Error("local_preview_world_set_attribute_path_invalid");
+            const entity = record(entities[effect.selector.entity_id] ?? {}, "local_preview_world_entity_invalid");
+            let cursor = entity;
+            for (const segment of args.path.slice(0, -1)) {
+                const next = cursor[segment] === undefined ? {} : record(cursor[segment], "local_preview_world_attribute_path_invalid");
+                cursor[segment] = next;
+                cursor = next;
+            }
+            cursor[args.path.at(-1)] = canonicalTmwJsonValue(args.value ?? null, "local_preview_world_attribute_value");
+            entities[effect.selector.entity_id] = entity;
+        }
+        else if (effect.capabilityId === "world.emit_event") {
+            if (emittedEvents.length >= maxEvents)
+                throw new Error("local_preview_world_event_queue_full");
+            emittedEvents.push(canonicalTmwJsonValue(effect.input, "local_preview_world_emitted_event"));
+        }
+        else if (!/^(variable\.|node\.|edge\.|object\.|scene\.)/u.test(effect.capabilityId)) {
+            throw new Error(`local_preview_effect_capability_unsupported:${effect.capabilityId}`);
+        }
+    }
+    return Object.freeze({ ...structuredClone(current), entities: Object.freeze(entities), emitted_events: Object.freeze(emittedEvents) });
+}

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

@@ -0,0 +1,47 @@
+import type { DatabaseSync } from "node:sqlite";
+import { type RuntimeSavPayloadV3 } from "@world-engines/tmw";
+import type { LocalPreviewWorldlineActivateResult, LocalPreviewWorldlineForkResult, LocalPreviewWorldlineListResult, LocalPreviewWorldlineRuntime, LocalPreviewWorldlineScope, LocalPreviewWorldlineSnapshot } from "./local-preview-worldlines.js";
+export interface LocalPreviewActiveWorldlineMessages {
+    readonly activeWorldlineId: string;
+    readonly catalogRevision: number;
+    /** Only IDs sealed by a successful writer checkpoint; message bodies live in LocalPreviewMessageStore. */
+    readonly orderedMessageIds: readonly string[];
+}
+/**
+ * The SQLite-backed half of local Preview worldlines.
+ *
+ * It deliberately receives the Runtime's already-open activation.sqlite
+ * connection.  There is therefore one CAS boundary for SAV, activation head,
+ * message checkpoints and worldline catalog; this is not a JSONL mirror.
+ */
+export declare class LocalPreviewWorldlineStore implements LocalPreviewWorldlineRuntime {
+    #private;
+    constructor(input: Readonly<{
+        database: DatabaseSync;
+        scope: LocalPreviewWorldlineScope;
+    }>);
+    snapshotWorldlines(): Promise<LocalPreviewWorldlineSnapshot>;
+    listWorldlines(scope: LocalPreviewWorldlineScope): Promise<LocalPreviewWorldlineListResult>;
+    /**
+     * Returns one SQLite snapshot of the active catalog row and its authoritative
+     * committed-message order. Accepted user input that has not reached a writer
+     * checkpoint is intentionally absent and must not be promoted here.
+     */
+    readActiveWorldlineMessages(): Promise<LocalPreviewActiveWorldlineMessages>;
+    forkWorldlineAtMessage(scope: LocalPreviewWorldlineScope, input: ForkInput): Promise<LocalPreviewWorldlineForkResult>;
+    activateWorldline(scope: LocalPreviewWorldlineScope, input: ActivateInput): Promise<LocalPreviewWorldlineActivateResult>;
+    /**
+     * Called only by the Runtime's genuine message/SAV commit while that caller
+     * already owns activation.sqlite's transaction.  It does not infer a
+     * checkpoint from JSONL or synthesize one for an uncommitted assistant turn.
+     */
+    recordCommittedMessageCheckpointInTransaction(input: Readonly<{
+        messageId: string;
+        orderedMessageIds: readonly string[];
+        sav: RuntimeSavPayloadV3;
+        createdAtMs: number;
+    }>): void;
+}
+type ForkInput = Parameters<LocalPreviewWorldlineRuntime["forkWorldlineAtMessage"]>[1];
+type ActivateInput = Parameters<LocalPreviewWorldlineRuntime["activateWorldline"]>[1];
+export {};

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

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { canonicalRuntimeSavPayload, canonicalTmwJsonValue } from "@world-engines/tmw";
+/**
+ * The SQLite-backed half of local Preview worldlines.
+ *
+ * It deliberately receives the Runtime's already-open activation.sqlite
+ * connection.  There is therefore one CAS boundary for SAV, activation head,
+ * message checkpoints and worldline catalog; this is not a JSONL mirror.
+ */
+export class LocalPreviewWorldlineStore {
+    #db;
+    #scope;
+    #scopeKey;
+    #savBinding;
+    constructor(input) {
+        assertScope(input.scope);
+        this.#db = input.database;
+        this.#scope = Object.freeze({ ...input.scope });
+        this.#scopeKey = scopeKey(this.#scope);
+        this.#db.exec([
+            "CREATE TABLE IF NOT EXISTS local_preview_worldline_schema (schema_name TEXT PRIMARY KEY, version INTEGER NOT NULL);",
+            "CREATE TABLE IF NOT EXISTS local_preview_worldline_catalog_v2 (scope_key TEXT PRIMARY KEY, active_worldline_id TEXT NOT NULL, root_worldline_id TEXT NOT NULL, revision INTEGER NOT NULL);",
+            "CREATE TABLE IF NOT EXISTS local_preview_worldline_v2 (scope_key TEXT NOT NULL, worldline_id TEXT NOT NULL, title TEXT NOT NULL, parent_worldline_id TEXT, fork_anchor_op_id TEXT, head_op_id TEXT, sav_json TEXT NOT NULL, projection_json TEXT NOT NULL, projection_digest TEXT NOT NULL, message_ids_json TEXT NOT NULL, created_at_ms INTEGER NOT NULL, updated_at_ms INTEGER NOT NULL, revision INTEGER NOT NULL, PRIMARY KEY(scope_key,worldline_id));",
+            "CREATE TABLE IF NOT EXISTS local_preview_worldline_checkpoint_v2 (scope_key TEXT NOT NULL, message_id TEXT NOT NULL, worldline_id TEXT NOT NULL, sav_json TEXT NOT NULL, projection_json TEXT NOT NULL, projection_digest TEXT NOT NULL, message_ids_json TEXT NOT NULL, checkpoint_digest TEXT NOT NULL, created_at_ms INTEGER NOT NULL, PRIMARY KEY(scope_key,message_id));",
+            "CREATE TABLE IF NOT EXISTS local_preview_worldline_request_v2 (scope_key TEXT NOT NULL, idempotency_key TEXT NOT NULL, digest TEXT NOT NULL, result_json TEXT NOT NULL, PRIMARY KEY(scope_key,idempotency_key));",
+        ].join(""));
+        const schema = this.#db.prepare("SELECT version FROM local_preview_worldline_schema WHERE schema_name='local_preview_worldline'").get();
+        if (schema === undefined)
+            this.#db.prepare("INSERT INTO local_preview_worldline_schema(schema_name,version) VALUES ('local_preview_worldline',2)").run();
+        else if (schema.version !== 2)
+            fail("E_OPERATION_UNCERTAIN", "local Preview worldline schema 版本不兼容；拒绝静默丢弃既有分支");
+        const initialSav = readSav(this.#db);
+        this.#savBinding = Object.freeze({ epoch: initialSav.epoch, runtimeGeneration: initialSav.runtimeGeneration, runtimeContractHash: initialSav.runtimeContractHash, artifactDigest: initialSav.artifactDigest, sourceRevision: initialSav.sourceRevision });
+        this.#initializeRoot();
+    }
+    snapshotWorldlines() {
+        const catalog = this.#catalog();
+        return Promise.resolve(Object.freeze({ scope: this.#scope, activeWorldlineId: catalog.active, rootWorldlineId: catalog.root, catalogRevision: catalog.revision }));
+    }
+    listWorldlines(scope) {
+        this.#assertScope(scope);
+        const catalog = this.#catalog();
+        const rows = this.#db.prepare("SELECT worldline_id,title,parent_worldline_id,fork_anchor_op_id,head_op_id,created_at_ms,updated_at_ms,revision FROM local_preview_worldline_v2 WHERE scope_key=? ORDER BY created_at_ms,worldline_id").all(this.#scopeKey);
+        const worldlines = rows.map((row) => summary(row));
+        return Promise.resolve(Object.freeze({ activeWorldlineId: catalog.active, rootWorldlineId: catalog.root, worldlineCount: worldlines.length, worldlines: Object.freeze(worldlines) }));
+    }
+    /**
+     * Returns one SQLite snapshot of the active catalog row and its authoritative
+     * committed-message order. Accepted user input that has not reached a writer
+     * checkpoint is intentionally absent and must not be promoted here.
+     */
+    readActiveWorldlineMessages() {
+        return Promise.resolve(this.#inReadTransaction(() => {
+            const catalog = this.#catalog();
+            const line = this.#line(catalog.active);
+            return Object.freeze({ activeWorldlineId: catalog.active, catalogRevision: catalog.revision, orderedMessageIds: Object.freeze([...parseIds(line.message_ids_json, "active worldline message ids")]) });
+        }));
+    }
+    async forkWorldlineAtMessage(scope, input) {
+        this.#assertScope(scope);
+        assertId(input.messageId, "messageId");
+        assertId(input.expectedActiveWorldlineId, "expectedActiveWorldlineId");
+        assertId(input.idempotencyKey, "idempotencyKey");
+        assertTime(input.createdAtMs, "createdAtMs");
+        if (input.requestedTitle !== null)
+            assertTitle(input.requestedTitle);
+        const digest = sha256(JSON.stringify({ scopeKey: this.#scopeKey, kind: "fork", messageId: input.messageId, title: input.requestedTitle }));
+        return this.#inTransaction(() => {
+            const previous = this.#request(input.idempotencyKey, digest);
+            if (previous !== null)
+                return previous;
+            const catalog = this.#requireCas(input.expectedCatalogRevision, input.expectedActiveWorldlineId);
+            const checkpoint = this.#db.prepare("SELECT worldline_id,sav_json,projection_json,message_ids_json FROM local_preview_worldline_checkpoint_v2 WHERE scope_key=? AND message_id=?").get(this.#scopeKey, input.messageId);
+            if (checkpoint === undefined)
+                fail("E_VALIDATION_FAILED", "只能从真实已提交消息分叉");
+            const source = this.#line(catalog.active);
+            const checkpointMessageIds = parseIds(checkpoint.message_ids_json, "checkpoint message ids");
+            const sourceMessageIds = parseIds(source.message_ids_json, "worldline message ids");
+            if (!hasPrefix(sourceMessageIds, checkpointMessageIds))
+                fail("E_OPERATION_UNCERTAIN", "worldline checkpoint 不再是当前已提交消息前缀");
+            const childId = `line.${sha256(`${this.#scopeKey}:${input.idempotencyKey}`).slice(0, 32)}`;
+            const existingChild = this.#tryLine(childId);
+            if (existingChild !== null)
+                fail("E_OPERATION_ID_CONFLICT", "worldline idempotency target 已被不同请求占用");
+            const childSav = withWorldline(parseSav(checkpoint.sav_json, this.#savBinding), childId, this.#savBinding);
+            const now = input.createdAtMs;
+            const child = Object.freeze({
+                worldlineId: childId, title: input.requestedTitle ?? `分支 ${checkpointMessageIds.length}`,
+                parentWorldlineId: catalog.active, forkAnchorOpId: childSav.ledgerHead, headOpId: childSav.ledgerHead,
+                sav: childSav, projectionJson: checkpoint.projection_json, messageIds: checkpointMessageIds, createdAtMs: now, updatedAtMs: now, revision: 1,
+            });
+            this.#insertLine(child);
+            this.#writeCatalog({ active: childId, root: catalog.root, revision: catalog.revision + 1 });
+            writeSavState(this.#db, childSav, checkpoint.projection_json);
+            const result = Object.freeze({ worldlineId: childId, activeWorldlineId: childId, anchorMessageId: input.messageId, worldlineCount: this.#lineCount(), removedMessageIds: Object.freeze(sourceMessageIds.slice(checkpointMessageIds.length)), deletedEntities: 0, deletedRelations: 0 });
+            this.#writeRequest(input.idempotencyKey, digest, result);
+            return result;
+        });
+    }
+    async activateWorldline(scope, input) {
+        this.#assertScope(scope);
+        assertId(input.worldlineId, "worldlineId");
+        assertId(input.expectedActiveWorldlineId, "expectedActiveWorldlineId");
+        assertId(input.idempotencyKey, "idempotencyKey");
+        assertTime(input.createdAtMs, "createdAtMs");
+        const digest = sha256(JSON.stringify({ scopeKey: this.#scopeKey, kind: "activate", worldlineId: input.worldlineId }));
+        return this.#inTransaction(() => {
+            const previous = this.#request(input.idempotencyKey, digest);
+            if (previous !== null)
+                return previous;
+            const catalog = this.#requireCas(input.expectedCatalogRevision, input.expectedActiveWorldlineId);
+            const line = this.#line(input.worldlineId);
+            const sav = withWorldline(parseSav(line.sav_json, this.#savBinding), input.worldlineId, this.#savBinding);
+            if (catalog.active !== input.worldlineId)
+                this.#writeCatalog({ active: input.worldlineId, root: catalog.root, revision: catalog.revision + 1 });
+            writeSavState(this.#db, sav, line.projection_json);
+            const result = Object.freeze({ worldlineId: input.worldlineId, activeWorldlineId: input.worldlineId, worldlineCount: this.#lineCount(), messageCount: parseIds(line.message_ids_json, "worldline message ids").length });
+            this.#writeRequest(input.idempotencyKey, digest, result);
+            return result;
+        });
+    }
+    /**
+     * Called only by the Runtime's genuine message/SAV commit while that caller
+     * already owns activation.sqlite's transaction.  It does not infer a
+     * checkpoint from JSONL or synthesize one for an uncommitted assistant turn.
+     */
+    recordCommittedMessageCheckpointInTransaction(input) {
+        if (!isTransaction(this.#db))
+            fail("E_OPERATION_UNCERTAIN", "message checkpoint 必须与真实 SAV commit 处于同一 SQLite transaction");
+        assertId(input.messageId, "messageId");
+        assertMessageIds(input.orderedMessageIds);
+        if (input.orderedMessageIds.at(-1) !== input.messageId)
+            fail("E_VALIDATION_FAILED", "message checkpoint 必须锚定最新已提交消息");
+        assertTime(input.createdAtMs, "checkpoint createdAtMs");
+        const catalog = this.#catalog();
+        const line = this.#line(catalog.active);
+        const ids = Object.freeze([...input.orderedMessageIds]);
+        const previous = parseIds(line.message_ids_json, "worldline message ids");
+        if (!hasPrefix(ids, previous))
+            fail("E_OPERATION_UNCERTAIN", "message checkpoint 不能重写既有提交历史");
+        const sav = withWorldline(input.sav, catalog.active, this.#savBinding);
+        const savJson = JSON.stringify(sav);
+        const projectionJson = readProjectionJson(this.#db);
+        const idsJson = JSON.stringify(ids);
+        const projectionDigest = sha256(projectionJson);
+        const checkpointDigest = sha256(JSON.stringify({ messageId: input.messageId, ids, savJson, projectionDigest }));
+        const existing = this.#db.prepare("SELECT checkpoint_digest FROM local_preview_worldline_checkpoint_v2 WHERE scope_key=? AND message_id=?").get(this.#scopeKey, input.messageId);
+        if (existing !== undefined) {
+            if (existing.checkpoint_digest !== checkpointDigest)
+                fail("E_OPERATION_ID_CONFLICT", "已提交消息绑定不同 checkpoint");
+            return;
+        }
+        this.#db.prepare("INSERT INTO local_preview_worldline_checkpoint_v2(scope_key,message_id,worldline_id,sav_json,projection_json,projection_digest,message_ids_json,checkpoint_digest,created_at_ms) VALUES (?,?,?,?,?,?,?,?,?)").run(this.#scopeKey, input.messageId, catalog.active, savJson, projectionJson, projectionDigest, idsJson, checkpointDigest, input.createdAtMs);
+        this.#db.prepare("UPDATE local_preview_worldline_v2 SET sav_json=?, projection_json=?, projection_digest=?, message_ids_json=?, head_op_id=?, updated_at_ms=?, revision=revision+1 WHERE scope_key=? AND worldline_id=?").run(savJson, projectionJson, projectionDigest, idsJson, sav.ledgerHead, input.createdAtMs, this.#scopeKey, catalog.active);
+    }
+    #initializeRoot() {
+        if (this.#db.prepare("SELECT 1 FROM local_preview_worldline_catalog_v2 WHERE scope_key=?").get(this.#scopeKey) !== undefined)
+            return;
+        this.#inTransaction(() => {
+            if (this.#db.prepare("SELECT 1 FROM local_preview_worldline_catalog_v2 WHERE scope_key=?").get(this.#scopeKey) !== undefined)
+                return;
+            const sav = readSav(this.#db, this.#savBinding);
+            const rootId = sav.activeTimeline.worldlineId;
+            assertId(rootId, "root worldline id");
+            const now = 0;
+            this.#db.prepare("INSERT INTO local_preview_worldline_catalog_v2(scope_key,active_worldline_id,root_worldline_id,revision) VALUES (?,?,?,1)").run(this.#scopeKey, rootId, rootId);
+            const projectionJson = readProjectionJson(this.#db);
+            this.#insertLine({ worldlineId: rootId, title: "主线", parentWorldlineId: null, forkAnchorOpId: null, headOpId: sav.ledgerHead, sav: withWorldline(sav, rootId, this.#savBinding), projectionJson, messageIds: Object.freeze([]), createdAtMs: now, updatedAtMs: now, revision: 1 });
+        });
+    }
+    #assertScope(scope) { if (scopeKey(scope) !== this.#scopeKey)
+        fail("E_OPERATION_UNCERTAIN", "worldline scope 不属于当前 Runtime capture"); }
+    #catalog() { const row = this.#db.prepare("SELECT active_worldline_id,root_worldline_id,revision FROM local_preview_worldline_catalog_v2 WHERE scope_key=?").get(this.#scopeKey); if (row === undefined)
+        fail("E_OPERATION_UNCERTAIN", "worldline catalog 缺失"); return Object.freeze({ active: row.active_worldline_id, root: row.root_worldline_id, revision: row.revision }); }
+    #requireCas(revision, active) { const catalog = this.#catalog(); if (!Number.isSafeInteger(revision) || revision < 1 || catalog.revision !== revision || catalog.active !== active)
+        fail("E_OPERATION_UNCERTAIN", "worldline catalog 已改变，请重新读取"); return catalog; }
+    #line(id) { const found = this.#tryLine(id); if (found === null)
+        fail("E_VALIDATION_FAILED", "worldline 不存在"); return found; }
+    #tryLine(id) { const row = this.#db.prepare("SELECT worldline_id,title,parent_worldline_id,fork_anchor_op_id,head_op_id,sav_json,projection_json,projection_digest,message_ids_json,created_at_ms,updated_at_ms,revision FROM local_preview_worldline_v2 WHERE scope_key=? AND worldline_id=?").get(this.#scopeKey, id); return row === undefined ? null : row; }
+    #lineCount() { return this.#db.prepare("SELECT COUNT(*) AS n FROM local_preview_worldline_v2 WHERE scope_key=?").get(this.#scopeKey).n; }
+    #insertLine(line) { const projectionDigest = sha256(line.projectionJson); this.#db.prepare("INSERT INTO local_preview_worldline_v2(scope_key,worldline_id,title,parent_worldline_id,fork_anchor_op_id,head_op_id,sav_json,projection_json,projection_digest,message_ids_json,created_at_ms,updated_at_ms,revision) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)").run(this.#scopeKey, line.worldlineId, line.title, line.parentWorldlineId, line.forkAnchorOpId, line.headOpId, JSON.stringify(line.sav), line.projectionJson, projectionDigest, JSON.stringify(line.messageIds), line.createdAtMs, line.updatedAtMs, line.revision); }
+    #writeCatalog(catalog) { this.#db.prepare("UPDATE local_preview_worldline_catalog_v2 SET active_worldline_id=?,root_worldline_id=?,revision=? WHERE scope_key=?").run(catalog.active, catalog.root, catalog.revision, this.#scopeKey); }
+    #request(key, digest) { const row = this.#db.prepare("SELECT digest,result_json FROM local_preview_worldline_request_v2 WHERE scope_key=? AND idempotency_key=?").get(this.#scopeKey, key); if (row === undefined)
+        return null; if (row.digest !== digest)
+        fail("E_OPERATION_ID_CONFLICT", "worldline request idempotency key 已绑定不同请求"); return JSON.parse(row.result_json); }
+    #writeRequest(key, digest, result) { this.#db.prepare("INSERT INTO local_preview_worldline_request_v2(scope_key,idempotency_key,digest,result_json) VALUES (?,?,?,?)").run(this.#scopeKey, key, digest, JSON.stringify(result)); }
+    #inReadTransaction(work) { if (isTransaction(this.#db))
+        return work(); this.#db.exec("BEGIN"); try {
+        const result = work();
+        this.#db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        try {
+            this.#db.exec("ROLLBACK");
+        }
+        catch { }
+        throw error;
+    } }
+    #inTransaction(work) { if (isTransaction(this.#db))
+        fail("E_OPERATION_UNCERTAIN", "worldline public operation 不能嵌套 activation transaction"); 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 summary(row) { return Object.freeze({ worldlineId: row.worldline_id, title: row.title, parentWorldlineId: row.parent_worldline_id, forkAnchorOpId: row.fork_anchor_op_id, headOpId: row.head_op_id, durableStatus: "durable", createdAtMs: row.created_at_ms, updatedAtMs: row.updated_at_ms, revision: row.revision }); }
+function readSav(db, binding) { const row = db.prepare("SELECT value FROM local_preview_state WHERE key='sav'").get(); if (row === undefined)
+    fail("E_OPERATION_UNCERTAIN", "activation.sqlite 缺少 capture-bound SAV"); return parseSav(row.value, binding); }
+function readProjectionJson(db) { const row = db.prepare("SELECT value FROM local_preview_state WHERE key='projection'").get(); if (row === undefined)
+    fail("E_OPERATION_UNCERTAIN", "activation.sqlite 缺少完整 world projection"); try {
+    const value = JSON.parse(row.value);
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("invalid");
+    canonicalTmwJsonValue(value, "local_preview_worldline_projection");
+    return row.value;
+}
+catch {
+    fail("E_OPERATION_UNCERTAIN", "worldline projection snapshot 损坏");
+} }
+function writeSavState(db, sav, projectionJson) { readProjectionValue(projectionJson); const state = Object.freeze({ head: Object.freeze({ revisionId: sav.activeTimeline.revisionId, revisionSequence: sav.activeTimeline.revisionSequence, ledgerHead: sav.ledgerHead }), sav, ledger: sav.eventLedger, narrative: sav.narrative, intents: sav.durableIntents, presentations: sav.presentationIntents }); for (const [key, value] of Object.entries(state))
+    db.prepare("INSERT OR REPLACE INTO local_preview_state(key,value) VALUES (?,?)").run(key, JSON.stringify(value)); db.prepare("INSERT OR REPLACE INTO local_preview_state(key,value) VALUES ('projection',?)").run(projectionJson); }
+function withWorldline(sav, worldlineId, binding) { const canonical = canonicalRuntimeSavPayload(Object.freeze({ ...structuredClone(sav), activeTimeline: Object.freeze({ ...sav.activeTimeline, worldlineId, active: true }) })); assertBinding(canonical, binding); return canonical; }
+function parseSav(value, binding) { try {
+    const sav = canonicalRuntimeSavPayload(JSON.parse(value));
+    if (binding !== undefined)
+        assertBinding(sav, binding);
+    return sav;
+}
+catch {
+    fail("E_OPERATION_UNCERTAIN", "worldline SAV snapshot 损坏或 runtime binding 不匹配");
+} }
+function readProjectionValue(value) { try {
+    const projection = JSON.parse(value);
+    if (typeof projection !== "object" || projection === null || Array.isArray(projection))
+        throw new Error("invalid");
+    canonicalTmwJsonValue(projection, "local_preview_worldline_projection");
+}
+catch {
+    fail("E_OPERATION_UNCERTAIN", "worldline projection snapshot 损坏");
+} }
+function assertBinding(sav, binding) { if (sav.epoch !== binding.epoch || sav.runtimeGeneration !== binding.runtimeGeneration || sav.runtimeContractHash !== binding.runtimeContractHash || sav.artifactDigest !== binding.artifactDigest || sav.sourceRevision !== binding.sourceRevision)
+    fail("E_OPERATION_UNCERTAIN", "worldline SAV runtime binding 不匹配"); }
+function parseIds(value, label) { try {
+    const ids = JSON.parse(value);
+    if (!Array.isArray(ids))
+        throw new Error("invalid");
+    assertMessageIds(ids);
+    return Object.freeze([...ids]);
+}
+catch (error) {
+    if (error instanceof AuthoringBridgeError)
+        throw error;
+    fail("E_OPERATION_UNCERTAIN", `${label} 损坏`);
+} }
+function assertMessageIds(value) { const known = new Set(); for (const id of value) {
+    assertId(id, "message id");
+    if (known.has(id))
+        fail("E_VALIDATION_FAILED", "message checkpoint 不可有重复 id");
+    known.add(id);
+} }
+function hasPrefix(full, prefix) { return prefix.length <= full.length && prefix.every((id, index) => full[index] === id); }
+function assertScope(scope) { if (scope.authority !== "worldengine.local-preview-worldlines/v1" || !scope.authorNamespace || !scope.projectId || !scope.scenarioId || !scope.saveId || !/^[a-f0-9]{64}$/u.test(scope.captureSha256))
+    fail("E_OPERATION_UNCERTAIN", "worldline scope 无效"); }
+function scopeKey(scope) { assertScope(scope); return sha256(JSON.stringify([scope.authority, scope.authorNamespace, scope.projectId, scope.scenarioId, scope.saveId, scope.captureSha256])); }
+function assertId(value, name) { if (typeof value !== "string" || !/^[A-Za-z0-9._:-]{1,256}$/u.test(value))
+    fail("E_VALIDATION_FAILED", `${name} 无效`); }
+function assertTitle(value) { if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.length > 160)
+    fail("E_VALIDATION_FAILED", "worldline title 无效"); }
+function assertTime(value, label) { if (typeof value !== "number" || !Number.isFinite(value) || !Number.isSafeInteger(value) || value < 0)
+    fail("E_VALIDATION_FAILED", `${label} 无效`); }
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function isTransaction(db) { return db.isTransaction === true; }
+function fail(code, message) { throw new AuthoringBridgeError(code, message); }