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

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

@@ -0,0 +1,95 @@
+/**
+ * Local Preview 的 worldline 命令边界。
+ *
+ * 这个 facade 故意不读取 local-preview-session JSONL，也不保有 catalog、op
+ * 或 blob 的副本。它只把 SDK 的三个 FAB 意图送到拥有 capture、SAV 和
+ * activation.sqlite 的 Runtime primitive。该 primitive 必须在同一 SQLite CAS
+ * 事务中复用正式 SameSaveWorldlineService 的 catalog/DAG/blob 语义，并在
+ * activate 时完成所有 state section 的 checkout 后才返回成功。
+ */
+export interface LocalPreviewWorldlineScope {
+    readonly authority: "worldengine.local-preview-worldlines/v1";
+    readonly authorNamespace: string;
+    readonly projectId: string;
+    readonly scenarioId: string;
+    readonly saveId: string;
+    readonly captureSha256: string;
+}
+export interface LocalPreviewWorldlineSnapshot {
+    readonly scope: LocalPreviewWorldlineScope;
+    readonly activeWorldlineId: string;
+    readonly rootWorldlineId: string;
+    readonly catalogRevision: number;
+}
+export interface LocalPreviewWorldlineSummary {
+    readonly worldlineId: string;
+    readonly title: string;
+    readonly parentWorldlineId: string | null;
+    readonly forkAnchorOpId: string | null;
+    readonly headOpId: string | null;
+    readonly durableStatus: "durable";
+    readonly createdAtMs: number;
+    readonly updatedAtMs: number;
+    readonly revision: number;
+}
+export interface LocalPreviewWorldlineListResult {
+    readonly activeWorldlineId: string;
+    readonly rootWorldlineId: string;
+    readonly worldlineCount: number;
+    readonly worldlines: readonly LocalPreviewWorldlineSummary[];
+}
+export interface LocalPreviewWorldlineForkResult {
+    readonly worldlineId: string;
+    readonly activeWorldlineId: string;
+    readonly anchorMessageId: string;
+    readonly worldlineCount: number;
+    readonly removedMessageIds: readonly string[];
+    readonly deletedEntities: number;
+    readonly deletedRelations: number;
+}
+export interface LocalPreviewWorldlineActivateResult {
+    readonly worldlineId: string;
+    readonly activeWorldlineId: string;
+    readonly worldlineCount: number;
+    readonly messageCount: number;
+}
+/** A trusted GUI/server request identity; it never comes from View params. */
+export interface LocalPreviewWorldlineRequestContext {
+    readonly requestId: string;
+    readonly createdAtMs: number;
+}
+/**
+ * Required LocalPreviewRuntime seam. The Runtime owner implements this against
+ * its capture-bound SAV + activation.sqlite authority; a session message log is
+ * not an acceptable implementation.
+ */
+export interface LocalPreviewWorldlineRuntime {
+    snapshotWorldlines(): Promise<LocalPreviewWorldlineSnapshot | null>;
+    listWorldlines(scope: LocalPreviewWorldlineScope): Promise<LocalPreviewWorldlineListResult>;
+    forkWorldlineAtMessage(scope: LocalPreviewWorldlineScope, input: Readonly<{
+        messageId: string;
+        requestedTitle: string | null;
+        expectedCatalogRevision: number;
+        expectedActiveWorldlineId: string;
+        idempotencyKey: string;
+        createdAtMs: number;
+    }>): Promise<LocalPreviewWorldlineForkResult>;
+    activateWorldline(scope: LocalPreviewWorldlineScope, input: Readonly<{
+        worldlineId: string;
+        expectedCatalogRevision: number;
+        expectedActiveWorldlineId: string;
+        idempotencyKey: string;
+        createdAtMs: number;
+    }>): Promise<LocalPreviewWorldlineActivateResult>;
+}
+/**
+ * Host-side implementation target for worldline.list / fork / activate.
+ * It derives the only permissible save scope from the Runtime snapshot and
+ * rejects both missing authority and any response that claims an impossible
+ * success. `trim` deliberately is not in this Local Preview FAB surface.
+ */
+export declare class LocalPreviewWorldlineFacade {
+    #private;
+    constructor(runtime: LocalPreviewWorldlineRuntime);
+    handle(method: "worldline.list" | "worldline.fork" | "worldline.activate", params: unknown, context: LocalPreviewWorldlineRequestContext): Promise<LocalPreviewWorldlineListResult | LocalPreviewWorldlineForkResult | LocalPreviewWorldlineActivateResult>;
+}

package/dist/local-preview-worldlines.js

@@ -0,0 +1,136 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const SHA256 = /^[a-f0-9]{64}$/u;
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function record(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("EINVAL", "worldline params 无效");
+    return value;
+}
+function assertOnlyKeys(value, allowed) {
+    const permitted = new Set(allowed);
+    if (Object.keys(value).some((key) => !permitted.has(key)))
+        fail("EPERM", "worldline scope 或参数未授权");
+}
+function identifier(value, label) {
+    if (!isIdentifier(value))
+        fail("EINVAL", `${label} 无效`);
+    return value;
+}
+function hasControl(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function isIdentifier(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 256 && !/\s/u.test(value) && !hasControl(value);
+}
+function isTitle(value) {
+    return typeof value === "string" && value.trim() === value && value.length > 0 && value.length <= 160 && !hasControl(value);
+}
+function title(value) {
+    if (value === undefined)
+        return null;
+    if (!isTitle(value))
+        fail("EINVAL", "worldline title 无效");
+    return value;
+}
+function requestContext(value) {
+    const requestId = identifier(value.requestId, "worldline requestId");
+    if (!Number.isSafeInteger(value.createdAtMs) || value.createdAtMs < 0)
+        fail("EINVAL", "worldline createdAtMs 无效");
+    return Object.freeze({ requestId, createdAtMs: value.createdAtMs });
+}
+function idempotencyKey(kind, context, target) {
+    return `local-preview-worldline:${kind}:${context.requestId}:${target}`;
+}
+function assertScope(value) {
+    if (value.authority !== "worldengine.local-preview-worldlines/v1"
+        || !isIdentifier(value.authorNamespace) || !isIdentifier(value.projectId) || !isIdentifier(value.scenarioId)
+        || !isIdentifier(value.saveId) || !SHA256.test(value.captureSha256)) {
+        fail("E_OPERATION_UNCERTAIN", "local Preview worldline authority snapshot 无效");
+    }
+}
+function assertList(snapshot, value) {
+    if (!Array.isArray(value.worldlines) || value.worldlineCount !== value.worldlines.length || value.worldlineCount < 1
+        || value.activeWorldlineId !== snapshot.activeWorldlineId || value.rootWorldlineId !== snapshot.rootWorldlineId) {
+        fail("E_OPERATION_UNCERTAIN", "local Preview worldline list 与 authority snapshot 不一致");
+    }
+    const ids = new Set();
+    for (const line of value.worldlines) {
+        if (!isIdentifier(line.worldlineId) || ids.has(line.worldlineId) || !isTitle(line.title)
+            || (line.parentWorldlineId !== null && !isIdentifier(line.parentWorldlineId))
+            || (line.forkAnchorOpId !== null && !SHA256.test(line.forkAnchorOpId))
+            || (line.headOpId !== null && !SHA256.test(line.headOpId))
+            || line.durableStatus !== "durable" || !Number.isSafeInteger(line.createdAtMs)
+            || !Number.isSafeInteger(line.updatedAtMs) || line.updatedAtMs < line.createdAtMs
+            || !Number.isSafeInteger(line.revision) || line.revision < 1) {
+            fail("E_OPERATION_UNCERTAIN", "local Preview worldline descriptor 无效");
+        }
+        ids.add(line.worldlineId);
+    }
+    if (!ids.has(value.activeWorldlineId) || !ids.has(value.rootWorldlineId))
+        fail("E_OPERATION_UNCERTAIN", "local Preview worldline catalog 缺少 active/root");
+    return Object.freeze({ ...value, worldlines: Object.freeze([...value.worldlines]) });
+}
+/**
+ * Host-side implementation target for worldline.list / fork / activate.
+ * It derives the only permissible save scope from the Runtime snapshot and
+ * rejects both missing authority and any response that claims an impossible
+ * success. `trim` deliberately is not in this Local Preview FAB surface.
+ */
+export class LocalPreviewWorldlineFacade {
+    #runtime;
+    constructor(runtime) { this.#runtime = runtime; }
+    async handle(method, params, context) {
+        const trustedContext = requestContext(context);
+        const snapshot = await this.#runtime.snapshotWorldlines();
+        if (snapshot === null)
+            fail("E_CAPABILITY_UNAVAILABLE", "本地 Preview Runtime 尚未提供 capture 绑定的 worldline snapshot");
+        assertScope(snapshot.scope);
+        identifier(snapshot.activeWorldlineId, "active worldline id");
+        identifier(snapshot.rootWorldlineId, "root worldline id");
+        if (!Number.isSafeInteger(snapshot.catalogRevision) || snapshot.catalogRevision < 1)
+            fail("E_OPERATION_UNCERTAIN", "local Preview worldline catalog revision 无效");
+        const p = record(params);
+        if (method === "worldline.list") {
+            assertOnlyKeys(p, []);
+            return assertList(snapshot, await this.#runtime.listWorldlines(snapshot.scope));
+        }
+        if (method === "worldline.fork") {
+            assertOnlyKeys(p, ["messageId", "title"]);
+            const messageId = identifier(p.messageId, "fork message id");
+            const result = await this.#runtime.forkWorldlineAtMessage(snapshot.scope, Object.freeze({
+                messageId, requestedTitle: title(p.title), expectedCatalogRevision: snapshot.catalogRevision,
+                expectedActiveWorldlineId: snapshot.activeWorldlineId,
+                idempotencyKey: idempotencyKey("fork", trustedContext, messageId), createdAtMs: trustedContext.createdAtMs,
+            }));
+            if (result.anchorMessageId !== messageId || result.worldlineId !== result.activeWorldlineId
+                || !isIdentifier(result.worldlineId) || !Number.isSafeInteger(result.worldlineCount)
+                || result.worldlineCount < 2 || !Array.isArray(result.removedMessageIds)
+                || !result.removedMessageIds.every((id) => isIdentifier(id))
+                || !Number.isSafeInteger(result.deletedEntities) || result.deletedEntities < 0
+                || !Number.isSafeInteger(result.deletedRelations) || result.deletedRelations < 0) {
+                fail("E_OPERATION_UNCERTAIN", "local Preview fork 未提交同一 authority 的有效结果");
+            }
+            return Object.freeze({ ...result, removedMessageIds: Object.freeze([...result.removedMessageIds]) });
+        }
+        assertOnlyKeys(p, ["worldlineId"]);
+        const worldlineId = identifier(p.worldlineId, "worldline id");
+        const result = await this.#runtime.activateWorldline(snapshot.scope, Object.freeze({
+            worldlineId, expectedCatalogRevision: snapshot.catalogRevision,
+            expectedActiveWorldlineId: snapshot.activeWorldlineId,
+            idempotencyKey: idempotencyKey("activate", trustedContext, worldlineId), createdAtMs: trustedContext.createdAtMs,
+        }));
+        if (result.worldlineId !== worldlineId || result.activeWorldlineId !== worldlineId
+            || !Number.isSafeInteger(result.worldlineCount) || result.worldlineCount < 1
+            || !Number.isSafeInteger(result.messageCount) || result.messageCount < 0) {
+            fail("E_OPERATION_UNCERTAIN", "local Preview activate 未完成完整 state checkout");
+        }
+        return Object.freeze({ ...result });
+    }
+}

package/dist/mcp-async-dispatcher.d.ts

@@ -0,0 +1,3 @@
+import { LocalProjectHost, type LocalProjectHostOptions } from "./project-host.js";
+/** 内部异步写入 dispatcher；不经 package exports 暴露。 */
+export declare function runAsyncProjectHostMcp(cwd: string, lines: AsyncIterable<string>, write: (line: string) => Promise<void>, writeError: (line: string) => void, onReady: (() => void) | undefined, handle: (host: LocalProjectHost, request: unknown) => Promise<unknown | undefined>, hostOptions?: LocalProjectHostOptions): Promise<number>;

package/dist/mcp-async-dispatcher.js

@@ -0,0 +1,129 @@
+import { LocalProjectHost } from "./project-host.js";
+import { toPublicError } from "./public-error.js";
+const MCP_MAX_CONCURRENT_REQUESTS = 8;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requestId(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = value.id;
+    return id === null || typeof id === "string" || (typeof id === "number" && Number.isFinite(id))
+        ? id
+        : undefined;
+}
+function cancellationTarget(value) {
+    if (!isRecord(value) || value.jsonrpc !== "2.0" || value.id !== undefined || value.method !== "notifications/cancelled")
+        return undefined;
+    if (!isRecord(value.params))
+        return undefined;
+    const id = value.params.requestId;
+    return id === null || typeof id === "string" || (typeof id === "number" && Number.isFinite(id))
+        ? id
+        : undefined;
+}
+function requestKey(id) {
+    return `${typeof id}:${String(id)}`;
+}
+function cancelledResponse(id) {
+    return { jsonrpc: "2.0", id, error: { code: -32800, message: "Request cancelled" } };
+}
+/** 内部异步写入 dispatcher；不经 package exports 暴露。 */
+export async function runAsyncProjectHostMcp(cwd, lines, write, writeError, onReady, handle, hostOptions = {}) {
+    let host;
+    try {
+        host = await LocalProjectHost.open(cwd, hostOptions);
+    }
+    catch (error) {
+        const publicError = toPublicError(error, "E_PROJECT_NOT_OPEN");
+        writeError(`${publicError.code}: 请求失败\n`);
+        return 1;
+    }
+    try {
+        onReady?.();
+        const pending = [];
+        const requestsById = new Map();
+        const active = new Set();
+        let outputTail = Promise.resolve();
+        let outputPending = 0;
+        let firstFailure;
+        const writeResponse = (response) => {
+            outputPending += 1;
+            const previous = outputTail;
+            const current = previous.then(() => write(`${JSON.stringify(response)}\n`));
+            // 后一个 response 仍需等待前一个 write，但不能让已观察的 rejection
+            // 变成 outputTail 的永久 rejected 链。
+            outputTail = current.catch(() => undefined).finally(() => { outputPending -= 1; });
+            return current;
+        };
+        const launch = () => {
+            while (active.size < MCP_MAX_CONCURRENT_REQUESTS) {
+                const item = pending.shift();
+                if (item === undefined)
+                    return;
+                item.started = true;
+                const task = (async () => {
+                    if (item.cancelled && item.requestId !== undefined) {
+                        await writeResponse(cancelledResponse(item.requestId));
+                        return;
+                    }
+                    const response = await handle(host, item.request);
+                    if (response !== undefined)
+                        await writeResponse(response);
+                })().catch((error) => {
+                    firstFailure ??= error;
+                }).finally(() => {
+                    if (item.requestId !== undefined)
+                        requestsById.delete(requestKey(item.requestId));
+                    active.delete(task);
+                    launch();
+                });
+                active.add(task);
+            }
+        };
+        for await (const line of lines) {
+            if (line.trim() === "")
+                continue;
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                await writeResponse({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+                continue;
+            }
+            const cancelId = cancellationTarget(request);
+            if (cancelId !== undefined) {
+                const target = requestsById.get(requestKey(cancelId));
+                // 已开始的 effect 必须完成并返回 authoritative receipt；只有尚未
+                // dispatch 的请求能安全取消，避免“客户端看到 cancelled、磁盘已写入”。
+                if (target !== undefined && !target.started)
+                    target.cancelled = true;
+                continue;
+            }
+            const id = requestId(request);
+            const item = { request, requestId: id, cancelled: false, started: false };
+            if (id !== undefined)
+                requestsById.set(requestKey(id), item);
+            pending.push(item);
+            launch();
+            // 快速请求已经进入 response backpressure 时，先停止拉取更多输入；
+            // 慢请求尚未产生输出时仍可继续填充最多八个并发槽。
+            await Promise.resolve();
+            if (outputPending > 0)
+                await outputTail;
+        }
+        while (active.size > 0 || pending.length > 0) {
+            launch();
+            if (active.size > 0)
+                await Promise.race(active);
+        }
+        await outputTail;
+        if (firstFailure !== undefined)
+            throw firstFailure;
+        return 0;
+    }
+    finally {
+        await host.close();
+    }
+}

package/dist/mcp-line-queue.d.ts

@@ -0,0 +1,14 @@
+import type { Readable } from "node:stream";
+export declare const MCP_MAX_LINE_BYTES: number;
+/**
+ * MCP 原始字节分帧与有界队列。partial line 在追加前受 12MiB 上限约束，
+ * 因此没有换行的输入不能绕过 readline 的 line 级限制并持续累积内存。
+ * 此模块不经 package exports 暴露；仅 MCP 入口和同包测试使用。
+ */
+export declare function createBoundedMcpLineQueue(input: Readable): {
+    readonly lines: AsyncIterable<string>;
+    readonly close: () => void;
+    readonly pause: () => void;
+    readonly resume: () => void;
+    readonly bufferedBytes: number;
+};

package/dist/mcp-line-queue.js

@@ -0,0 +1,184 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+export const MCP_MAX_LINE_BYTES = 12 * 1024 * 1024;
+const MAX_QUEUED_BYTES = 16 * 1024 * 1024;
+const MAX_QUEUED_LINES = 128;
+const PAUSE_QUEUED_BYTES = 12 * 1024 * 1024;
+const PAUSE_QUEUED_LINES = 96;
+const RESUME_QUEUED_BYTES = 8 * 1024 * 1024;
+const RESUME_QUEUED_LINES = 64;
+/**
+ * MCP 原始字节分帧与有界队列。partial line 在追加前受 12MiB 上限约束，
+ * 因此没有换行的输入不能绕过 readline 的 line 级限制并持续累积内存。
+ * 此模块不经 package exports 暴露；仅 MCP 入口和同包测试使用。
+ */
+export function createBoundedMcpLineQueue(input) {
+    const buffered = [];
+    const partial = [];
+    let head = 0;
+    let queuedBytes = 0;
+    let partialBytes = 0;
+    let previousWasCarriageReturn = false;
+    let inputPaused = false;
+    let closed = false;
+    let failure;
+    let wake;
+    const bufferedBytes = () => queuedBytes + partialBytes;
+    const notify = () => {
+        const current = wake;
+        wake = undefined;
+        current?.();
+    };
+    const pauseInput = () => {
+        if (inputPaused)
+            return;
+        input.pause();
+        inputPaused = true;
+    };
+    const resumeInput = () => {
+        if (!inputPaused || closed)
+            return;
+        input.resume();
+        inputPaused = false;
+    };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        pauseInput();
+        notify();
+    };
+    const fail = (error) => {
+        if (closed || failure !== undefined)
+            return;
+        failure = error;
+        partial.length = 0;
+        partialBytes = 0;
+        close();
+        input.destroy();
+    };
+    const enqueue = (rawLine) => {
+        let line;
+        try {
+            line = new TextDecoder("utf-8", { fatal: true }).decode(rawLine);
+        }
+        catch {
+            fail(new AuthoringBridgeError("E_SCHEMA_INVALID", "MCP 行不是有效 UTF-8"));
+            return;
+        }
+        const bytes = rawLine.length;
+        const queuedLines = buffered.length - head;
+        if (queuedLines >= MAX_QUEUED_LINES || queuedBytes + bytes > MAX_QUEUED_BYTES) {
+            fail(new AuthoringBridgeError("E_SCHEMA_INVALID", "MCP 请求队列超过上限"));
+            return;
+        }
+        buffered.push({ line, bytes });
+        queuedBytes += bytes;
+        if (queuedLines + 1 >= PAUSE_QUEUED_LINES || queuedBytes >= PAUSE_QUEUED_BYTES)
+            pauseInput();
+        notify();
+    };
+    const completeLine = () => {
+        const onlyPartial = partial[0];
+        const line = partial.length === 0
+            ? Buffer.alloc(0)
+            : partial.length === 1 && onlyPartial !== undefined
+                ? onlyPartial
+                : Buffer.concat(partial, partialBytes);
+        partial.length = 0;
+        partialBytes = 0;
+        enqueue(line);
+    };
+    const appendPartial = (segment) => {
+        if (partialBytes + segment.length > MCP_MAX_LINE_BYTES) {
+            fail(new AuthoringBridgeError("E_SCHEMA_INVALID", "MCP 单行超过上限"));
+            return;
+        }
+        if (queuedBytes + partialBytes + segment.length > MAX_QUEUED_BYTES) {
+            fail(new AuthoringBridgeError("E_SCHEMA_INVALID", "MCP 缓存超过上限"));
+            return;
+        }
+        if (segment.length === 0)
+            return;
+        partial.push(segment);
+        partialBytes += segment.length;
+    };
+    const onData = (chunk) => {
+        if (closed)
+            return;
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let start = 0;
+        if (previousWasCarriageReturn && bytes.length > 0) {
+            if (bytes[0] === 0x0a)
+                start = 1;
+            previousWasCarriageReturn = false;
+        }
+        while (start < bytes.length && !closed) {
+            let delimiter = start;
+            while (delimiter < bytes.length && bytes[delimiter] !== 0x0a && bytes[delimiter] !== 0x0d)
+                delimiter += 1;
+            appendPartial(bytes.subarray(start, delimiter));
+            if (closed)
+                return;
+            if (delimiter === bytes.length)
+                return;
+            if (bytes[delimiter] === 0x0a) {
+                completeLine();
+                start = delimiter + 1;
+                continue;
+            }
+            if (delimiter + 1 === bytes.length) {
+                completeLine();
+                previousWasCarriageReturn = true;
+                return;
+            }
+            completeLine();
+            previousWasCarriageReturn = true;
+            start = delimiter + 1;
+            if (bytes[start] === 0x0a) {
+                previousWasCarriageReturn = false;
+                start += 1;
+            }
+            else {
+                previousWasCarriageReturn = false;
+            }
+        }
+    };
+    const onEnd = () => {
+        if (closed)
+            return;
+        if (partialBytes > 0)
+            completeLine();
+        if (closed)
+            return;
+        closed = true;
+        notify();
+    };
+    const onError = () => fail(new AuthoringBridgeError("E_SCHEMA_INVALID", "MCP input 失败"));
+    input.on("data", onData);
+    input.once("end", onEnd);
+    input.once("close", onEnd);
+    input.on("error", onError);
+    const lines = (async function* () {
+        while (true) {
+            if (failure !== undefined)
+                throw failure;
+            const entry = buffered[head];
+            if (entry !== undefined) {
+                head += 1;
+                queuedBytes -= entry.bytes;
+                if (head === buffered.length) {
+                    buffered.length = 0;
+                    head = 0;
+                }
+                if (inputPaused && queuedBytes <= RESUME_QUEUED_BYTES && buffered.length - head <= RESUME_QUEUED_LINES)
+                    resumeInput();
+                yield entry.line;
+                continue;
+            }
+            if (closed)
+                return;
+            await new Promise((resolvePromise) => { wake = resolvePromise; });
+        }
+    })();
+    return { lines, close, pause: pauseInput, resume: resumeInput, get bufferedBytes() { return bufferedBytes(); } };
+}

package/dist/mcp-pipe-internal.d.ts

@@ -0,0 +1,6 @@
+import { type Server, type Socket } from "node:net";
+export interface ProjectHostMcpPipeRuntime {
+    readonly createServer?: (connectionListener: (socket: Socket) => void) => Server;
+}
+/** T027 的 inherited-capability 内部入口；不由公开 package export 或 CLI 暴露。 */
+export declare function runProjectHostMcpPipe(cwd: string, pipe: string, challenge: string, runtime?: ProjectHostMcpPipeRuntime): Promise<number>;