@world-engines/dag-flow 0.1.3-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./document.js";
+export * from "./executor.js";
+export * from "./sandbox.js";
+export * from "./tmw-scribe.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./document.js";
+export * from "./executor.js";
+export * from "./sandbox.js";
+export * from "./tmw-scribe.js";

package/dist/sandbox.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 浏览器脚本执行隔离层。
+ *
+ * 不可信源码只会进入 opaque-origin iframe 内创建的 Dedicated Worker。宿主窗口
+ * 宿主窗口永远不解释用户源码，也不会把任何 host API、cookie 或凭据传入。
+ */
+export type SandboxJson = null | boolean | number | string | SandboxJson[] | {
+    readonly [key: string]: SandboxJson;
+};
+export interface SandboxedScriptResult {
+    path: string;
+    body: SandboxJson;
+}
+export interface BrowserScriptRunnerOptions {
+    /** 超时会直接移除 iframe，从而终止其中的 Worker。默认 5 秒。 */
+    timeoutMs?: number;
+    /** 输入 JSON UTF-8 上限。默认 128 KiB。 */
+    maxInputBytes?: number;
+    /** 输出 JSON UTF-8 上限。默认 128 KiB。 */
+    maxOutputBytes?: number;
+    /** 将隐藏 iframe 挂到指定容器；默认 document.body。 */
+    container?: HTMLElement;
+    /** 仅用于测试或嵌入到非全局 document 的页面。 */
+    document?: Document;
+}
+export interface RunSandboxedScriptOptions extends BrowserScriptRunnerOptions {
+    signal?: AbortSignal;
+}
+export interface BrowserScriptRunner {
+    run(source: string, input: unknown, options?: Pick<RunSandboxedScriptOptions, "signal" | "timeoutMs" | "maxInputBytes" | "maxOutputBytes">): Promise<SandboxedScriptResult>;
+    dispose(): void;
+}
+export declare class SandboxScriptError extends Error {
+    readonly code: "aborted" | "timeout" | "protocol" | "validation" | "execution" | "unavailable";
+    constructor(code: SandboxScriptError["code"], message: string);
+}
+/** 创建可复用的执行器；每次 run 仍会创建全新的 iframe 与 Worker。 */
+export declare function createBrowserScriptRunner(baseOptions?: BrowserScriptRunnerOptions): BrowserScriptRunner;
+/**
+ * 在浏览器内执行 `main(input)`。source 必须是一个函数表达式，例如
+ * `async (input) => ({ path: "next", body: input })`。
+ */
+export declare function runSandboxedScript(source: string, input: unknown, options?: RunSandboxedScriptOptions): Promise<SandboxedScriptResult>;

package/dist/sandbox.js

@@ -0,0 +1,379 @@
+/**
+ * 浏览器脚本执行隔离层。
+ *
+ * 不可信源码只会进入 opaque-origin iframe 内创建的 Dedicated Worker。宿主窗口
+ * 宿主窗口永远不解释用户源码，也不会把任何 host API、cookie 或凭据传入。
+ */
+export class SandboxScriptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SandboxScriptError";
+        this.code = code;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_INPUT_BYTES = 128 * 1024;
+const DEFAULT_MAX_OUTPUT_BYTES = 128 * 1024;
+const MAX_SOURCE_BYTES = 512 * 1024;
+const READY_TYPE = "chat.dag-flow.sandbox.ready";
+const BIND_TYPE = "chat.dag-flow.sandbox.bind";
+const RUN_TYPE = "chat.dag-flow.sandbox.run";
+const RESULT_TYPE = "chat.dag-flow.sandbox.result";
+const ERROR_TYPE = "chat.dag-flow.sandbox.error";
+const ABORT_TYPE = "chat.dag-flow.sandbox.abort";
+/** 创建可复用的执行器；每次 run 仍会创建全新的 iframe 与 Worker。 */
+export function createBrowserScriptRunner(baseOptions = {}) {
+    let disposed = false;
+    const active = new Set();
+    return {
+        async run(source, input, options = {}) {
+            if (disposed)
+                throw new SandboxScriptError("unavailable", "浏览器脚本执行器已销毁");
+            const controller = new AbortController();
+            active.add(controller);
+            const forwardAbort = () => controller.abort();
+            if (options.signal?.aborted)
+                controller.abort();
+            else
+                options.signal?.addEventListener("abort", forwardAbort, { once: true });
+            try {
+                return await runSandboxedScript(source, input, {
+                    ...baseOptions,
+                    ...options,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                options.signal?.removeEventListener("abort", forwardAbort);
+                active.delete(controller);
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const controller of active)
+                controller.abort();
+            active.clear();
+        },
+    };
+}
+/**
+ * 在浏览器内执行 `main(input)`。source 必须是一个函数表达式，例如
+ * `async (input) => ({ path: "next", body: input })`。
+ */
+export function runSandboxedScript(source, input, options = {}) {
+    const documentRef = options.document ?? globalThis.document;
+    const windowRef = documentRef?.defaultView ?? globalThis.window;
+    if (!documentRef || !windowRef || typeof MessageChannel === "undefined") {
+        return Promise.reject(new SandboxScriptError("unavailable", "当前环境不支持浏览器 iframe sandbox"));
+    }
+    if (options.signal?.aborted)
+        return Promise.reject(new SandboxScriptError("aborted", "脚本执行已取消"));
+    if (typeof source !== "string")
+        return Promise.reject(new SandboxScriptError("validation", "脚本源码必须是字符串"));
+    if (utf8Length(source) > MAX_SOURCE_BYTES) {
+        return Promise.reject(new SandboxScriptError("validation", `脚本源码超过 ${MAX_SOURCE_BYTES} 字节上限`));
+    }
+    let maxInputBytes;
+    let maxOutputBytes;
+    let timeoutMs;
+    let jsonInput;
+    try {
+        maxInputBytes = checkedLimit(options.maxInputBytes, DEFAULT_MAX_INPUT_BYTES, "输入");
+        maxOutputBytes = checkedLimit(options.maxOutputBytes, DEFAULT_MAX_OUTPUT_BYTES, "输出");
+        timeoutMs = checkedTimeout(options.timeoutMs);
+        jsonInput = normalizeJson(input, maxInputBytes, "输入");
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return new Promise((resolve, reject) => {
+        const nonce = secureNonce();
+        const channel = new MessageChannel();
+        const iframe = documentRef.createElement("iframe");
+        let settled = false;
+        let bound = false;
+        let timeout;
+        iframe.setAttribute("sandbox", "allow-scripts");
+        iframe.setAttribute("referrerpolicy", "no-referrer");
+        iframe.setAttribute("aria-hidden", "true");
+        iframe.tabIndex = -1;
+        iframe.style.display = "none";
+        iframe.srcdoc = createIframeDocument(source, nonce, maxOutputBytes);
+        const cleanup = () => {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            windowRef.removeEventListener("message", onWindowMessage);
+            options.signal?.removeEventListener("abort", onAbort);
+            channel.port1.onmessage = null;
+            channel.port1.onmessageerror = null;
+            channel.port1.close();
+            // 移除 browsing context 会终止 iframe 及其 Dedicated Worker，即使用户代码死循环。
+            iframe.remove();
+        };
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if ("result" in outcome)
+                resolve(outcome.result);
+            else
+                reject(outcome.error);
+        };
+        const fail = (code, message) => finish({ error: new SandboxScriptError(code, message) });
+        const onAbort = () => {
+            if (bound) {
+                try {
+                    channel.port1.postMessage({ type: ABORT_TYPE, nonce });
+                }
+                catch { /* 已销毁的 port 无需处理 */ }
+            }
+            fail("aborted", "脚本执行已取消");
+        };
+        const onWindowMessage = (event) => {
+            // opaque iframe 的 origin 必然为 null；绝不因 origin=null 单独信任消息。
+            if (event.origin !== "null" || event.source !== iframe.contentWindow || !isReadyMessage(event.data, nonce))
+                return;
+            if (bound)
+                return;
+            bound = true;
+            try {
+                iframe.contentWindow?.postMessage({ type: BIND_TYPE, nonce }, "*", [channel.port2]);
+                channel.port1.start();
+                channel.port1.onmessage = onPortMessage;
+                channel.port1.onmessageerror = () => fail("protocol", "sandbox 消息通道损坏");
+                channel.port1.postMessage({ type: RUN_TYPE, nonce, input: jsonInput });
+            }
+            catch {
+                fail("protocol", "无法绑定 sandbox 消息通道");
+            }
+        };
+        const onPortMessage = (event) => {
+            const message = event.data;
+            if (!isRecord(message) || message.nonce !== nonce)
+                return;
+            if (message.type === ERROR_TYPE && typeof message.message === "string") {
+                fail("execution", safeErrorMessage(message.message));
+                return;
+            }
+            if (message.type !== RESULT_TYPE)
+                return;
+            try {
+                finish({ result: normalizeResult(message.result, maxOutputBytes) });
+            }
+            catch (error) {
+                finish({ error: asSandboxError(error) });
+            }
+        };
+        windowRef.addEventListener("message", onWindowMessage);
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        timeout = setTimeout(() => fail("timeout", `脚本执行超过 ${timeoutMs}ms`), timeoutMs);
+        const mount = options.container ?? documentRef.body;
+        if (!mount) {
+            fail("unavailable", "document.body 尚不可用，无法挂载 sandbox iframe");
+            return;
+        }
+        mount.append(iframe);
+    });
+}
+function checkedLimit(value, fallback, name) {
+    const limit = value ?? fallback;
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        throw new SandboxScriptError("validation", `${name}大小上限必须是正整数`);
+    return limit;
+}
+function checkedTimeout(value) {
+    const timeout = value ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeout) || timeout <= 0)
+        throw new SandboxScriptError("validation", "超时必须是正整数毫秒数");
+    return timeout;
+}
+function secureNonce() {
+    const cryptoRef = globalThis.crypto;
+    if (!cryptoRef?.getRandomValues)
+        throw new SandboxScriptError("unavailable", "当前浏览器缺少安全随机数 API");
+    const bytes = new Uint8Array(24);
+    cryptoRef.getRandomValues(bytes);
+    return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+function isReadyMessage(value, nonce) {
+    return isRecord(value) && value.type === READY_TYPE && value.nonce === nonce && Object.keys(value).length === 2;
+}
+function normalizeResult(value, maxBytes) {
+    if (!isRecord(value) || Object.keys(value).length !== 2 || !("path" in value) || !("body" in value)) {
+        throw new SandboxScriptError("validation", "脚本必须返回且只返回 { path, body }");
+    }
+    if (typeof value.path !== "string" || value.path.length === 0) {
+        throw new SandboxScriptError("validation", "脚本返回的 path 必须是非空字符串");
+    }
+    return { path: value.path, body: normalizeJson(value.body, maxBytes, "输出") };
+}
+function normalizeJson(value, maxBytes, label) {
+    const normalized = normalizeJsonValue(value, new Set());
+    const encoded = JSON.stringify(normalized);
+    if (utf8Length(encoded) > maxBytes)
+        throw new SandboxScriptError("validation", `${label}超过 ${maxBytes} 字节上限`);
+    return normalized;
+}
+function normalizeJsonValue(value, seen) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new SandboxScriptError("validation", "JSON 数字必须是有限值");
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new SandboxScriptError("validation", "JSON 不能包含循环引用");
+        seen.add(value);
+        try {
+            return value.map((item) => normalizeJsonValue(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (isRecord(value)) {
+        if (seen.has(value))
+            throw new SandboxScriptError("validation", "JSON 不能包含循环引用");
+        seen.add(value);
+        try {
+            const output = Object.create(null);
+            for (const key of Object.keys(value))
+                output[key] = normalizeJsonValue(value[key], seen);
+            return output;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new SandboxScriptError("validation", "值必须是 JSON 可序列化数据");
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function utf8Length(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+function safeErrorMessage(message) {
+    return message.slice(0, 1_024) || "用户脚本执行失败";
+}
+function asSandboxError(error) {
+    return error instanceof SandboxScriptError ? error : new SandboxScriptError("protocol", "sandbox 返回了无效消息");
+}
+function createIframeDocument(source, nonce, maxOutputBytes) {
+    // `</script` 必须转义，否则用户源码能提前结束可信 bootstrap 的 script 标签。
+    const sourceLiteral = JSON.stringify(source).replaceAll("<", "\\u003c");
+    const nonceLiteral = JSON.stringify(nonce);
+    const maxBytesLiteral = JSON.stringify(maxOutputBytes);
+    return `<!doctype html><html><head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline' blob:; worker-src blob:; child-src blob:; connect-src 'none'; img-src 'none'; media-src 'none'; object-src 'none'; style-src 'none'; font-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'">
+</head><body><script>
+(() => {
+  'use strict';
+  const READY = ${JSON.stringify(READY_TYPE)};
+  const BIND = ${JSON.stringify(BIND_TYPE)};
+  const RUN = ${JSON.stringify(RUN_TYPE)};
+  const RESULT = ${JSON.stringify(RESULT_TYPE)};
+  const ERROR = ${JSON.stringify(ERROR_TYPE)};
+  const ABORT = ${JSON.stringify(ABORT_TYPE)};
+  const nonce = ${nonceLiteral};
+  const source = ${sourceLiteral};
+  const maxOutputBytes = ${maxBytesLiteral};
+  let port = null;
+  let worker = null;
+  const parentPostMessage = window.parent.postMessage.bind(window.parent);
+  const addWindowListener = window.addEventListener.bind(window);
+  const makeBlobUrl = URL.createObjectURL.bind(URL);
+  const revokeBlobUrl = URL.revokeObjectURL.bind(URL);
+
+  const workerPrefix = String.raw\`
+    'use strict';
+    const __post = self.postMessage.bind(self);
+    const __addEventListener = self.addEventListener.bind(self);
+    const __arrayIsArray = Array.isArray.bind(Array);
+    const __getPrototypeOf = Object.getPrototypeOf.bind(Object);
+    const __objectPrototype = Object.prototype;
+    const __objectCreate = Object.create.bind(Object);
+    const __objectKeys = Object.keys.bind(Object);
+    const __hasOwn = Object.prototype.hasOwnProperty.call.bind(Object.prototype.hasOwnProperty);
+    const __isFinite = Number.isFinite.bind(Number);
+    const __Set = Set;
+    const __TextEncoder = TextEncoder;
+    const __arrayMap = Array.prototype.map.call.bind(Array.prototype.map);
+    const __jsonStringify = JSON.stringify.bind(JSON);
+    const __isRecord = (value) => value !== null && typeof value === 'object' && !__arrayIsArray(value) && (__getPrototypeOf(value) === __objectPrototype || __getPrototypeOf(value) === null);
+    const __json = (value, seen = new __Set()) => {
+      if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+      if (typeof value === 'number') { if (!__isFinite(value)) throw new Error('JSON number must be finite'); return value; }
+      if (__arrayIsArray(value)) { if (seen.has(value)) throw new Error('JSON cycle'); seen.add(value); try { return __arrayMap(value, (item) => __json(item, seen)); } finally { seen.delete(value); } }
+      if (__isRecord(value)) { if (seen.has(value)) throw new Error('JSON cycle'); seen.add(value); try { const out = __objectCreate(null); for (const key of __objectKeys(value)) out[key] = __json(value[key], seen); return out; } finally { seen.delete(value); } }
+      throw new Error('value is not JSON serializable');
+    };
+    const __result = (value) => {
+      if (!__isRecord(value) || __objectKeys(value).length !== 2 || !__hasOwn(value, 'path') || !__hasOwn(value, 'body') || typeof value.path !== 'string' || value.path.length === 0) throw new Error('main must return exactly { path, body }');
+      const result = { path: value.path, body: __json(value.body) };
+      if (new __TextEncoder().encode(__jsonStringify(result)).byteLength > ${maxBytesLiteral}) throw new Error('result exceeds output limit');
+      return result;
+    };
+    const __main = (() => {
+  \`;
+  // source 是 JavaScript 源码，但它只会被拼进 iframe 内的 Worker 文件；宿主 window
+  // 从不解释它；源码只作为 Worker 文件的私有作用域内容。
+  const workerSuffix = String.raw\`
+      return typeof main === 'function' ? main : null;
+    })();
+    __addEventListener('message', async (event) => {
+      const message = event.data;
+      if (!message || message.type !== 'run') return;
+      if (typeof __main !== 'function') { __post({ type: 'error', id: message.id, message: 'source must evaluate to a function' }); return; }
+      try { __post({ type: 'result', id: message.id, result: __result(await __main(message.input)) }); }
+      catch (error) { __post({ type: 'error', id: message.id, message: String(error && error.message || error).slice(0, 1024) }); }
+    });
+  \`;
+  const workerSource = workerPrefix + source + workerSuffix;
+
+  const stopWorker = () => {
+    if (worker) worker.terminate();
+    worker = null;
+  };
+  const send = (message) => port && port.postMessage(message);
+  const start = (input) => {
+    stopWorker();
+    const url = makeBlobUrl(new Blob([workerSource], { type: 'text/javascript' }));
+    worker = new Worker(url);
+    revokeBlobUrl(url);
+    const current = worker;
+    current.onmessage = (event) => {
+      const message = event.data;
+      if (!message || (message.type !== 'result' && message.type !== 'error')) return;
+      send({ type: message.type === 'result' ? RESULT : ERROR, nonce, result: message.result, message: message.message });
+      stopWorker();
+    };
+    current.onerror = () => { send({ type: ERROR, nonce, message: '用户脚本执行失败' }); stopWorker(); };
+    current.postMessage({ type: 'run', id: nonce, input });
+  };
+  const bind = (event) => {
+    if (event.source !== window.parent || !event.data || event.data.type !== BIND || event.data.nonce !== nonce || event.ports.length !== 1 || port) return;
+    port = event.ports[0];
+    port.onmessage = (portEvent) => {
+      const message = portEvent.data;
+      if (!message || message.nonce !== nonce) return;
+      if (message.type === ABORT) { stopWorker(); return; }
+      if (message.type === RUN) start(message.input);
+    };
+    port.start();
+  };
+  addWindowListener('message', bind);
+  parentPostMessage({ type: READY, nonce }, '*');
+})();
+</script></body></html>`;
+}

package/dist/tmw-scribe.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Director -> TMW -> Scribe 协调的无副作用边界。
+ *
+ * 该模块不实现数据库或 LLM；调用方通过 ports 注入真实实现。
+ * Scribe 在一次 judge 调用中接收所有自然语言条件，避免逐条件产生 LLM 调用。
+ */
+export interface TmwTriggerForScribe {
+    readonly id: string;
+    readonly naturalLanguage?: string;
+    readonly enabled?: boolean;
+    /** 时间触发器用于在场记提交前做确定性拦截。 */
+    readonly dueAtMs?: number;
+    readonly crossingPolicy?: "forward_only" | "backward_only" | "both_directions";
+}
+export interface TmwTriggerVerdict {
+    readonly id: string;
+    readonly truth: "true" | "false" | "unknown";
+    readonly reason?: string;
+}
+export interface ScribeTriggerInput {
+    readonly manuscript: string;
+    readonly scene?: unknown;
+    readonly worldTimeMs?: number;
+    /** Director 已按剧本历法换算的有符号时间变化。 */
+    readonly timeDeltaMs?: number;
+    readonly triggers: readonly TmwTriggerForScribe[];
+    /** TMW recall 结果；由 production caller 在同一 pass 内缓存并复用。 */
+    readonly recalled?: readonly unknown[];
+}
+/** 真实 TMW 数据库检索边界。实现方应连接 world_search/recall API。 */
+export interface ScribeRecallPort {
+    recall(input: Readonly<{
+        manuscript: string;
+        scene?: unknown;
+        worldTimeMs?: number;
+    }>): Promise<readonly unknown[]>;
+}
+export interface ScribeTriggerJudgePort {
+    judge(input: Readonly<{
+        readonly manuscript: string;
+        readonly scene?: unknown;
+        readonly worldTimeMs?: number;
+        readonly timeDeltaMs?: number;
+        readonly predicates: readonly {
+            readonly id: string;
+            readonly text: string;
+        }[];
+        readonly recalled?: readonly unknown[];
+    }>): Promise<readonly TmwTriggerVerdict[]>;
+}
+export interface ScribeTriggerCommitPort {
+    commit(input: Readonly<{
+        readonly manuscript: string;
+        readonly scene?: unknown;
+        readonly worldTimeMs?: number;
+        readonly timeDeltaMs?: number;
+        readonly verdicts: readonly TmwTriggerVerdict[];
+        readonly recalled?: readonly unknown[];
+    }>): Promise<unknown>;
+}
+export interface ScribeTriggerPassOptions {
+    readonly judge: ScribeTriggerJudgePort;
+    readonly commit: ScribeTriggerCommitPort;
+    readonly maxAttempts?: number;
+    readonly recallCache?: Map<string, readonly TmwTriggerVerdict[]>;
+    readonly recallKey?: string;
+    readonly signal?: AbortSignal;
+    /** Optional real TMW recall. It is called once per recallKey and cached across retries. */
+    readonly recall?: ScribeRecallPort;
+    readonly onRetry?: (event: Readonly<{
+        attempt: number;
+        reason: string;
+    }>) => void | Promise<void>;
+}
+export interface ScribeTriggerPassResult {
+    readonly status: "committed" | "rejected" | "aborted";
+    readonly verdicts: readonly TmwTriggerVerdict[];
+    readonly receipt?: unknown;
+    readonly attempts: number;
+    readonly reason?: string;
+}
+/**
+ * 场记触发器 pass：所有自然语言条件一次性判断；同一 recallKey 的重试复用 verdict。
+ * commit 返回 rejected 时只重试提交/判定流程，不重新召回外部数据库结果。
+ */
+export declare function runScribeTriggerPass(input: ScribeTriggerInput, options: ScribeTriggerPassOptions): Promise<ScribeTriggerPassResult>;
+/** 确定性时间门：手稿造成的世界时间不能跨过最近延迟触发器。 */
+export declare function manuscriptCrossesTimeTrigger(worldTimeMs: number, timeDeltaMs: number, nearestDueAtMs: number | undefined, policy?: "forward_only" | "backward_only" | "both_directions"): boolean;

package/dist/tmw-scribe.js

@@ -0,0 +1,128 @@
+/**
+ * Director -> TMW -> Scribe 协调的无副作用边界。
+ *
+ * 该模块不实现数据库或 LLM；调用方通过 ports 注入真实实现。
+ * Scribe 在一次 judge 调用中接收所有自然语言条件，避免逐条件产生 LLM 调用。
+ */
+/**
+ * 场记触发器 pass：所有自然语言条件一次性判断；同一 recallKey 的重试复用 verdict。
+ * commit 返回 rejected 时只重试提交/判定流程，不重新召回外部数据库结果。
+ */
+export async function runScribeTriggerPass(input, options) {
+    const triggerIds = new Set();
+    for (const trigger of input.triggers) {
+        if (typeof trigger.id !== "string" || !trigger.id.trim() || triggerIds.has(trigger.id)
+            || (trigger.enabled !== undefined && typeof trigger.enabled !== "boolean")
+            || (trigger.naturalLanguage !== undefined && typeof trigger.naturalLanguage !== "string")) {
+            return { status: "rejected", verdicts: [], attempts: 0, reason: "scribe_trigger_definitions_invalid" };
+        }
+        triggerIds.add(trigger.id);
+    }
+    if (options.maxAttempts !== undefined && (!Number.isSafeInteger(options.maxAttempts) || options.maxAttempts < 1)) {
+        return { status: "rejected", verdicts: [], attempts: 0, reason: "scribe_retry_limit_invalid" };
+    }
+    if (input.timeDeltaMs !== undefined) {
+        if (!Number.isFinite(input.timeDeltaMs) || !Number.isFinite(input.worldTimeMs)
+            || !Number.isFinite(input.worldTimeMs + input.timeDeltaMs)) {
+            return { status: "rejected", verdicts: [], attempts: 0, reason: "manuscript_time_invalid" };
+        }
+        for (const trigger of input.triggers) {
+            if (trigger.enabled === false || trigger.dueAtMs === undefined)
+                continue;
+            if (!Number.isFinite(trigger.dueAtMs))
+                return { status: "rejected", verdicts: [], attempts: 0, reason: "trigger_time_invalid" };
+            if (trigger.crossingPolicy !== undefined && !["forward_only", "backward_only", "both_directions"].includes(trigger.crossingPolicy)) {
+                return { status: "rejected", verdicts: [], attempts: 0, reason: "trigger_crossing_policy_invalid" };
+            }
+            if (manuscriptCrossesTimeTrigger(input.worldTimeMs, input.timeDeltaMs, trigger.dueAtMs, trigger.crossingPolicy)) {
+                return { status: "rejected", verdicts: [], attempts: 0, reason: `manuscript_time_trigger_crossed:${trigger.id}` };
+            }
+        }
+    }
+    const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 2));
+    const cache = options.recallCache;
+    // 同一个 turn 的手稿修订或场景变化必须重新判断，不能复用旧真假结果。
+    const key = JSON.stringify([options.recallKey ?? null, input.manuscript, input.worldTimeMs ?? null, input.timeDeltaMs ?? null, input.scene ?? null, input.triggers]);
+    const recallKey = options.recallKey ?? key;
+    let verdicts = cache?.get(key);
+    let recalled = input.recalled;
+    const recallCache = options.recallCache;
+    if (recalled === undefined && recallCache?.__tmwRecall)
+        recalled = recallCache.__tmwRecall.get(recallKey);
+    let attempts = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        attempts = attempt;
+        if (options.signal?.aborted)
+            return { status: "aborted", verdicts: verdicts ?? [], attempts };
+        try {
+            if (verdicts === undefined) {
+                if (recalled === undefined && options.recall) {
+                    recalled = await options.recall.recall({ manuscript: input.manuscript, ...(input.scene === undefined ? {} : { scene: input.scene }), ...(input.worldTimeMs === undefined ? {} : { worldTimeMs: input.worldTimeMs }) });
+                    if (recallCache) {
+                        recallCache.__tmwRecall ??= new Map();
+                        recallCache.__tmwRecall.set(recallKey, recalled);
+                    }
+                }
+                const predicates = input.triggers
+                    .filter((trigger) => trigger.enabled !== false && typeof trigger.naturalLanguage === "string" && trigger.naturalLanguage.length > 0)
+                    .map((trigger) => ({ id: trigger.id, text: trigger.naturalLanguage }));
+                if (options.signal?.aborted)
+                    return { status: "aborted", verdicts: [], attempts };
+                const candidate = await options.judge.judge({ manuscript: input.manuscript, ...(input.scene === undefined ? {} : { scene: input.scene }), ...(input.worldTimeMs === undefined ? {} : { worldTimeMs: input.worldTimeMs }), ...(input.timeDeltaMs === undefined ? {} : { timeDeltaMs: input.timeDeltaMs }), predicates, ...(recalled === undefined ? {} : { recalled }) });
+                if (options.signal?.aborted)
+                    return { status: "aborted", verdicts: [], attempts };
+                const candidateError = validateVerdicts(candidate, input.triggers);
+                if (candidateError !== undefined)
+                    throw new Error(candidateError);
+                verdicts = candidate;
+                if (cache)
+                    cache.set(key, verdicts);
+            }
+            const invalid = validateVerdicts(verdicts, input.triggers);
+            if (invalid !== undefined)
+                throw new Error(invalid);
+            const blocked = verdicts.find((verdict) => verdict.truth === "unknown");
+            if (blocked)
+                return { status: "rejected", verdicts, attempts, reason: blocked.reason ?? `trigger_unknown:${blocked.id}` };
+            if (options.signal?.aborted)
+                return { status: "aborted", verdicts, attempts };
+            const receipt = await options.commit.commit({ manuscript: input.manuscript, ...(input.scene === undefined ? {} : { scene: input.scene }), ...(input.worldTimeMs === undefined ? {} : { worldTimeMs: input.worldTimeMs }), ...(input.timeDeltaMs === undefined ? {} : { timeDeltaMs: input.timeDeltaMs }), verdicts, ...(recalled === undefined ? {} : { recalled }) });
+            if (receipt === null || receipt === undefined || (typeof receipt === "object"
+                && (receipt.ok === false || receipt.status === "rejected"))) {
+                return { status: "rejected", verdicts, attempts, reason: "scribe_commit_not_confirmed" };
+            }
+            return { status: "committed", verdicts, receipt, attempts };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (attempt >= maxAttempts)
+                return { status: "rejected", verdicts: verdicts ?? [], attempts, reason };
+            await options.onRetry?.({ attempt, reason });
+        }
+    }
+    return { status: "rejected", verdicts: verdicts ?? [], attempts, reason: "scribe_trigger_pass_failed" };
+}
+/** 确定性时间门：手稿造成的世界时间不能跨过最近延迟触发器。 */
+export function manuscriptCrossesTimeTrigger(worldTimeMs, timeDeltaMs, nearestDueAtMs, policy = "forward_only") {
+    if (nearestDueAtMs === undefined)
+        return false;
+    return (policy !== "backward_only" && timeDeltaMs > 0 && worldTimeMs < nearestDueAtMs && worldTimeMs + timeDeltaMs >= nearestDueAtMs)
+        || (policy !== "forward_only" && timeDeltaMs < 0 && worldTimeMs > nearestDueAtMs && worldTimeMs + timeDeltaMs <= nearestDueAtMs);
+}
+function validateVerdicts(verdicts, triggers) {
+    const expected = new Set(triggers.filter((trigger) => trigger.enabled !== false && trigger.naturalLanguage).map((trigger) => trigger.id));
+    const seen = new Set();
+    for (const verdict of verdicts) {
+        if (!expected.has(verdict.id))
+            return `trigger_verdict_unexpected:${verdict.id}`;
+        if (seen.has(verdict.id))
+            return `trigger_verdict_duplicate:${verdict.id}`;
+        if (!["true", "false", "unknown"].includes(verdict.truth))
+            return `trigger_verdict_invalid:${verdict.id}`;
+        seen.add(verdict.id);
+    }
+    for (const id of expected)
+        if (!seen.has(id))
+            return `trigger_verdict_missing:${id}`;
+    return undefined;
+}