@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/capabilities/incident-log.js

@@ -1,100 +1,170 @@
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+/**
+ * 进程级事故日志(D-NEW):同步、durable 的 JSONL 诊断记录。
+ *
+ * `uncaughtExceptionMonitor` 只观察 fatal 事故并留下证据；宿主仍决定
+ * 是否退出。GoTry 不吞掉 fatal 事件、不调用 process.exit、也不隐式重启。
+ * 工具 execute 的业务失败仍由 guardToolExecute 转成结构化失败返回。
+ *
+ * §11 状态面同步:事故日志是 gotry-state/incidents.jsonl,
+ * 用户可见、可清理。
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { pathToFileURL } from 'node:url';
+/** 解析 gotry-state 绝对路径(stateRoot 可相对也可绝对) */
 export function resolveIncidentsPath(stateRoot, filename = 'incidents.jsonl') {
-    const root = isAbsolute(stateRoot) ? stateRoot : join(process.cwd(), stateRoot);
+    const root = isAbsolute(stateRoot)
+        ? stateRoot
+        : join(process.cwd(), stateRoot);
     return join(root, 'gotry-state', filename);
 }
 function ensureDir(path) {
     const dir = dirname(path);
-    if (!existsSync(dir)) mkdirSync(dir, {
-        recursive: true
-    });
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
 }
 let installed = false;
 let logPath = null;
+let activeMonitor = null;
+function safeErrorMessage(value) {
+    try {
+        if (value instanceof Error)
+            return typeof value.message === 'string' ? value.message : '[error-without-message]';
+        if (typeof value === 'string')
+            return value;
+        if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol')
+            return String(value);
+        const json = JSON.stringify(value);
+        return typeof json === 'string' ? json : '[unprintable-error]';
+    }
+    catch {
+        return '[unprintable-error]';
+    }
+}
+function safeErrorStack(value) {
+    try {
+        const stack = value?.stack;
+        return typeof stack === 'string' ? stack : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 写入一条事故并 fsync。整个 append 使用同一个 fd，并保证所有失败路径
+ * 都尝试 close；返回 true 只表示写入、fsync、close 全部成功。
+ */
 export function recordIncident(inc, stateRoot) {
-    const target = stateRoot ? resolveIncidentsPath(stateRoot) : logPath ?? resolveIncidentsPath('.');
+    const target = stateRoot ? resolveIncidentsPath(stateRoot) : (logPath ?? resolveIncidentsPath('.'));
+    let fd;
+    let closeAttempted = false;
     try {
         ensureDir(target);
-        appendFileSync(target, JSON.stringify(inc) + '\n', {
-            flag: 'a'
-        });
-        const fd = require('node:fs').openSync(target, 'a');
-        require('node:fs').fsyncSync(fd);
-        require('node:fs').closeSync(fd);
+        fd = openSync(target, 'a');
+        writeFileSync(fd, JSON.stringify(inc) + '\n', { encoding: 'utf8' });
+        fsyncSync(fd);
+        closeAttempted = true;
+        closeSync(fd);
+        fd = undefined;
         return true;
-    } catch  {
+    }
+    catch {
+        // 事故处理中的诊断失败绝不能再次抛出。
         return false;
     }
+    finally {
+        if (fd !== undefined && !closeAttempted) {
+            closeAttempted = true;
+            try {
+                closeSync(fd);
+            }
+            catch { /* best effort close on a failed write */ }
+        }
+    }
 }
+/**
+ * 安装进程级事故观察器。只挂 monitor，不改变 Node/dsh 的 fatal 行为。
+ * 进程整个生命周期仅生效一次；disposer 供宿主卸载和测试使用。
+ */
 export function installProcessGuards(stateRoot, labels) {
-    if (installed) return ()=>{};
+    if (installed)
+        return () => { };
     installed = true;
     logPath = resolveIncidentsPath(stateRoot);
-    const uncaughtHandler = (err, origin)=>{
-        recordIncident({
-            ts: new Date().toISOString(),
-            kind: 'uncaughtException',
-            message: (err?.message ?? String(err)).slice(0, 2000),
-            stack: (err?.stack ?? '').slice(0, 4000),
-            source: labels?.uncaughtException ?? String(origin)
-        }, stateRoot);
-    };
-    const rejectionHandler = (reason, promise)=>{
-        const msg = reason instanceof Error ? reason.message : String(reason);
-        const stack = reason instanceof Error ? reason.stack ?? '' : '';
-        recordIncident({
-            ts: new Date().toISOString(),
-            kind: 'unhandledRejection',
-            message: msg.slice(0, 2000),
-            stack: stack.slice(0, 4000),
-            source: labels?.unhandledRejection ?? 'promise'
-        }, stateRoot);
+    const monitor = (err, origin) => {
+        try {
+            const kind = origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException';
+            const source = kind === 'unhandledRejection'
+                ? (labels?.unhandledRejection ?? 'promise')
+                : (labels?.uncaughtException ?? origin);
+            recordIncident({
+                ts: new Date().toISOString(),
+                kind,
+                message: safeErrorMessage(err).slice(0, 2000),
+                stack: safeErrorStack(err).slice(0, 4000),
+                source,
+            }, stateRoot);
+        }
+        catch {
+            // Formatting must never replace the original fatal event. Keep a final
+            // plain fallback attempt for diagnostics, while the host retains control.
+            try {
+                recordIncident({
+                    ts: new Date().toISOString(),
+                    kind: origin === 'unhandledRejection' ? 'unhandledRejection' : 'uncaughtException',
+                    message: '[incident-observer-fallback]',
+                    source: 'incident-observer',
+                }, stateRoot);
+            }
+            catch { /* observer is strictly best effort */ }
+        }
     };
-    process.on('uncaughtException', uncaughtHandler);
-    process.on('unhandledRejection', rejectionHandler);
-    return ()=>{
-        process.off('uncaughtException', uncaughtHandler);
-        process.off('unhandledRejection', rejectionHandler);
+    process.on('uncaughtExceptionMonitor', monitor);
+    activeMonitor = monitor;
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        if (activeMonitor !== monitor)
+            return;
+        process.off('uncaughtExceptionMonitor', monitor);
         installed = false;
+        logPath = null;
+        activeMonitor = null;
     };
 }
+/**
+ * 工具执行面异常隔离(D-NEW gotry 侧收尾):dsh 的一个工具 execute 抛错/拒绝
+ * 会沿 cordis 传到主循环,拖垮整个会话。包装后:降级为结构化错误返回给 LLM、
+ * 事故落盘,永不向上抛。落盘失败也不抛(双保险,仍返回结构化错误)。
+ */
 export function guardToolExecute(name, stateRoot, execute) {
-    return async (args, exec)=>{
+    return async (args, exec) => {
         try {
             return await execute(args, exec);
-        } catch (e) {
-            const err = e instanceof Error ? e : new Error(String(e));
+        }
+        catch (e) {
+            const message = safeErrorMessage(e);
             recordIncident({
                 ts: new Date().toISOString(),
                 kind: 'tool_execute_error',
-                message: `${name}: ${err.message}`.slice(0, 2000),
-                stack: (err.stack ?? '').slice(0, 4000),
-                source: name
+                message: `${name}: ${message}`.slice(0, 2000),
+                stack: safeErrorStack(e).slice(0, 4000),
+                source: name,
             }, stateRoot);
             const failure = {
                 ok: false,
-                summary: `gotry_${name} 内部错误(已隔离,会话继续): ${err.message.slice(0, 300)}`,
-                evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`
+                summary: `gotry_${name} 内部错误(已隔离,会话继续): ${message.slice(0, 300)}`,
+                evidence: `[incident:tool_execute_error@${new Date().toISOString()}]`,
             };
             return failure;
         }
     };
 }
-if (import.meta.url === `file://${fileURLToPath(import.meta.url)}` && process.argv[2] === '--smoke') {
+/** CLI 调试:最小 fatal 子进程会留下事故证据并按 Node 原生语义非零退出。 */
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url && process.argv[2] === '--smoke') {
     const stateRoot = process.argv[3] ?? '.';
-    installProcessGuards(stateRoot, {
-        uncaughtException: 'smoke',
-        unhandledRejection: 'smoke'
-    });
-    writeFileSync(resolveIncidentsPath(stateRoot) + '.smoke', 'ok');
-    setTimeout(()=>Promise.reject(new Error('intentional smoke-rejection')), 50);
-    setTimeout(()=>{
-        console.log('SMOKE OK');
-        process.exit(0);
-    }, 500);
+    installProcessGuards(stateRoot, { uncaughtException: 'smoke', unhandledRejection: 'smoke' });
+    setTimeout(() => { throw new Error('intentional smoke-uncaught'); }, 50);
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/incident-log.ts

package/dist/capabilities/itinerary-artifact.js

@@ -0,0 +1,190 @@
+/**
+ * 行程 HTML 产物生成入口(issue #442,父 #438)。
+ *
+ * 与纯渲染器(ts/src/itinerary-html.ts)的分工:渲染器只把「显式行程 + 已选事实」
+ * 投影成单文件 HTML;本模块是**唯一的产品生成路径**——从当前配置状态根的
+ * 事实注册表按 id 选事实、跑渲染器、把产物独占落盘到会话工作目录。
+ *
+ * 三条硬纪律:
+ *   1. 事实只从 <stateRoot>/gotry-state/bookable-facts.jsonl 注册表取:入参只收
+ *      fact_ids,调用方自带的事实对象一律不接收;未知/重复/超量 id 显式拒绝,
+ *      登记行畸形则由渲染器的运行时校验拒绝(不静默丢弃后仍宣称成功);
+ *   2. 只新建文件:basename 限定 gotry-itinerary-<ASCII 安全 token>.html,父目录必须是宿主
+ *      显式给出的**绝对**会话工作目录(缺失/空白/相对一律拒绝,绝不回落 `.` 或进程 cwd),
+ *      realpath 化并排除 .git/node_modules 后,再以 O_CREAT|O_EXCL('wx')独占创建,
+ *      绝不覆盖既有文件、绝不跟随符号链接改写其目标;
+ *   3. 失败即拒绝、零写入:输入非法/事实未注册/渲染被拒/文件名被占用都返回结构化
+ *      错误,不落任何字节(校验全部发生在打开文件之前)。
+ */
+import { randomBytes } from 'node:crypto';
+import { open, realpath, stat, unlink } from 'node:fs/promises';
+import { isAbsolute, join, sep } from 'node:path';
+import { loadFactRegistry } from './fact-log.js';
+import { ITINERARY_HTML_LIMITS, renderItineraryHtml } from '../src/itinerary-html.js';
+/** 产物文件名契约:固定前缀 + ASCII 安全 token + .html(无路径分隔符、无前导点) */
+export const ITINERARY_ARTIFACT_BASENAME_RE = /^gotry-itinerary-[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.html$/;
+/** 随机默认名(仅 crypto 十六进制;显式 basename 优先) */
+export const ITINERARY_ARTIFACT_RANDOM_BYTES = 8;
+const RANDOM_ATTEMPTS = 3;
+const DIR_DENY = ['.git', 'node_modules'];
+const ID_SAMPLE = 3;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasDeniedSegment(p) {
+    return p.split(sep).some(seg => DIR_DENY.includes(seg));
+}
+function fsErrorText(err) {
+    const code = err?.code;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM': return '无写入权限';
+        case 'ENOSPC': return '磁盘空间不足';
+        case 'EROFS': return '只读文件系统';
+        case 'ENOTDIR': return '路径中某段不是目录';
+        case 'ENOENT': return '目录不存在';
+        case 'ENAMETOOLONG': return '文件名过长';
+        default: return typeof code === 'string' ? `文件系统错误 ${code}` : '文件系统错误';
+    }
+}
+/** fact_ids 输入收窄:必填数组、逐条非空短字符串、无重复、不超渲染器容量 */
+function takeFactIds(value) {
+    if (value === undefined || value === null) {
+        return { error: 'fact_ids 必填(字符串数组,可为空数组)', hint: 'id 来自本次会话 exact-date 工具结果记录的注册表;不接受调用方自带事实' };
+    }
+    if (!Array.isArray(value))
+        return { error: 'fact_ids 必须是字符串数组' };
+    if (value.length > ITINERARY_HTML_LIMITS.facts) {
+        return { error: `fact_ids 超出容量上限(${ITINERARY_HTML_LIMITS.facts} 条,实测 ${value.length} 条)` };
+    }
+    const ids = [];
+    const seen = new Set();
+    const duplicates = [];
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            return { error: `fact_ids[${i}] 必须是非空字符串` };
+        if (raw.length > ITINERARY_HTML_LIMITS.factIdChars) {
+            return { error: `fact_ids[${i}] 超出 id 长度上限(${ITINERARY_HTML_LIMITS.factIdChars} 字符)` };
+        }
+        if (seen.has(raw)) {
+            duplicates.push(raw);
+            continue;
+        }
+        seen.add(raw);
+        ids.push(raw);
+    }
+    if (duplicates.length > 0) {
+        return { error: `fact_ids 有重复 id:${duplicates.slice(0, ID_SAMPLE).join('、')}${duplicates.length > ID_SAMPLE ? ` 等 ${duplicates.length} 条` : ''}`, hint: '同一条事实只能选一次;重复选择说明调用方对证据面不确定' };
+    }
+    return { ids };
+}
+function takeBasename(value) {
+    if (value === undefined || value === null)
+        return { basename: `gotry-itinerary-${randomBytes(ITINERARY_ARTIFACT_RANDOM_BYTES).toString('hex')}.html` };
+    if (typeof value !== 'string' || value.length === 0)
+        return { error: 'basename 必须是字符串' };
+    if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+        return { error: 'basename 只能是文件名,不能含路径分隔符或 ..', hint: '形如 gotry-itinerary-2027-thailand.html' };
+    }
+    if (!ITINERARY_ARTIFACT_BASENAME_RE.test(value)) {
+        return { error: 'basename 不符合命名契约', hint: '必须是 gotry-itinerary-<ASCII 字母/数字/._->.html(前缀后 1-64 字符)' };
+    }
+    return { basename: value };
+}
+/** 会话工作目录:必须显式且为绝对路径(缺失/空白/相对一律拒绝,绝不回落 '.' 或 process.cwd()),
+ *  按宿主原值解析(trim 只判全空白、绝不归一化路径),已存在、可 realpath、是目录,且不含 .git/node_modules 段 */
+async function resolveWritableDir(cwd) {
+    if (typeof cwd !== 'string' || cwd.trim() === '') {
+        return { error: '会话工作目录缺失:拒绝在未知目录写产物', hint: '写产物必须有宿主显式给出的绝对会话工作目录,不做任何猜测性回落' };
+    }
+    // trim 只用于「是否全空白」判定:真实路径一律按宿主原值使用,绝不归一化——
+    // 尾随空格可能是真实目录名的一部分,归一化会写到同名兄弟目录
+    if (!isAbsolute(cwd)) {
+        return { error: `会话工作目录必须是绝对路径:${cwd}`, hint: '相对路径会随进程工作目录漂移,拒绝写入' };
+    }
+    const canonical = await realpath(cwd).catch(() => null);
+    if (!canonical)
+        return { error: `会话工作目录不存在或无法解析:${cwd}`, hint: '本工具只在真实存在的会话工作目录顶层新建文件' };
+    if (hasDeniedSegment(canonical)) {
+        return { error: '会话工作目录位于受限段(.git/node_modules)内,拒绝写入', hint: `解析后:${canonical}` };
+    }
+    const st = await stat(canonical).catch(() => null);
+    if (!st?.isDirectory())
+        return { error: `会话工作目录不是目录:${canonical}` };
+    return { dir: canonical };
+}
+/** 独占创建:wx(O_CREAT|O_EXCL)既拒绝覆盖既有文件,也拒绝落在指向别处的符号链接上 */
+async function writeExclusive(dir, basename, html) {
+    const target = join(dir, basename);
+    const bytes = Buffer.byteLength(html, 'utf8');
+    let handle;
+    try {
+        handle = await open(target, 'wx', 0o644);
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST') {
+            return { error: `目标文件已存在,拒绝覆盖:${basename}`, hint: '换一个 basename(不传则自动生成随机名);本工具永不覆盖既有产物' };
+        }
+        return { error: `无法在会话工作目录新建文件:${fsErrorText(err)}`, hint: `目标目录:${dir}` };
+    }
+    try {
+        await handle.writeFile(html, 'utf-8');
+    }
+    catch (err) {
+        await handle.close().catch(() => { });
+        await unlink(target).catch(() => { });
+        return { error: `写入产物失败:${fsErrorText(err)}`, hint: `目标文件已清理:${target}` };
+    }
+    await handle.close();
+    const finalPath = await realpath(target).catch(() => target);
+    return { path: finalPath, bytes };
+}
+/**
+ * 生成一份行程 HTML 产物。写入唯一目标 = 会话工作目录顶层的新文件;
+ * 事实唯一来源 = deps.stateRoot 的事实注册表。
+ */
+export async function generateItineraryArtifact(input, deps) {
+    if (!isRecord(input))
+        return { ok: false, error: 'input 必须是对象 {title, itinerary, fact_ids, basename?}' };
+    const ids = takeFactIds(input.fact_ids);
+    if ('error' in ids)
+        return { ok: false, error: ids.error, hint: ids.hint };
+    const named = takeBasename(input.basename);
+    if ('error' in named)
+        return { ok: false, error: named.error, hint: named.hint };
+    const registry = await loadFactRegistry(deps.stateRoot);
+    const byId = new Map(registry.map(f => [f.fact_id, f]));
+    const missing = ids.ids.filter(id => !byId.has(id));
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            error: `事实 id 未在当前注册表:${missing.slice(0, ID_SAMPLE).join('、')}${missing.length > ID_SAMPLE ? ` 等 ${missing.length} 条` : ''}`,
+            hint: 'fact_ids 只能取自本会话 exact-date 工具结果的注册表;不接受调用方自带事实对象,也不从 Markdown 猜事实',
+        };
+    }
+    // 顺序保留调用方选择;登记行畸形不在选择阶段放宽——交给渲染器运行时校验显式拒绝
+    const selected = ids.ids.map(id => byId.get(id));
+    const rendered = renderItineraryHtml({ title: input.title, itinerary: input.itinerary, facts: selected });
+    if (!rendered.ok) {
+        return {
+            ok: false,
+            error: '渲染被拒:行程或事实不满足渲染契约,未写入任何文件',
+            errors: rendered.errors,
+            hint: '按 errors 修正显式行程结构或换用合法登记的事实;本工具不会静默截断核心行程',
+        };
+    }
+    const dir = await resolveWritableDir(deps.cwd);
+    if ('error' in dir)
+        return { ok: false, error: dir.error, hint: dir.hint };
+    for (let attempt = 0; attempt < (input.basename === undefined || input.basename === null ? RANDOM_ATTEMPTS : 1); attempt++) {
+        const basename = attempt === 0 ? named.basename : `gotry-itinerary-${randomBytes(ITINERARY_ARTIFACT_RANDOM_BYTES).toString('hex')}.html`;
+        const written = await writeExclusive(dir.dir, basename, rendered.html);
+        if ('error' in written) {
+            if (attempt + 1 < RANDOM_ATTEMPTS && input.basename === undefined)
+                continue; // 随机名撞车:换名重试
+            return { ok: false, error: written.error, hint: written.hint };
+        }
+        return { ok: true, path: written.path, basename, bytes: written.bytes, fact_ids: ids.ids, overall_verified: false };
+    }
+    return { ok: false, error: '随机文件名多次撞车,未写入文件' };
+}

package/dist/capabilities/itinerary-deck-artifact.js

@@ -0,0 +1,194 @@
+/**
+ * 行程 deck 产物生成入口(issue #566,Phase B 切片 2;研究决策见
+ * docs/research/karpo-deck-web-research.md 决策 #1;deck 渲染契约见
+ * docs/design/itinerary-deck-renderer.md)。
+ *
+ * 与单页入口 itinerary-artifact.ts 完全对称的产品路径:渲染器只把「显式行程
+ * + 已选事实」投影成单文件 deck HTML;本模块是 deck 形态的**唯一产品生成
+ * 路径**——从当前配置状态根的事实注册表按 id 选事实、跑 deck 渲染器、把
+ * 产物独占落盘到会话工作目录。
+ *
+ * 三条硬纪律(继承自单页入口,verbatim):
+ *   1. 事实只从 <stateRoot>/gotry-state/bookable-facts.jsonl 注册表取:入参只收
+ *      fact_ids,调用方自带的事实对象一律不接收;未知/重复/超量 id 显式拒绝,
+ *      登记行畸形则由 deck 渲染器的运行时校验拒绝(不静默丢弃后仍宣称成功);
+ *   2. 只新建文件:basename 限定 gotry-deck-<ASCII 安全 token>.html,父目录必须是宿主
+ *      显式给出的**绝对**会话工作目录(缺失/空白/相对一律拒绝,绝不回落 `.` 或进程 cwd),
+ *      realpath 化并排除 .git/node_modules 后,再以 O_CREAT|O_EXCL('wx')独占创建,
+ *      绝不覆盖既有文件、绝不跟随符号链接改写其目标;
+ *   3. 失败即拒绝、零写入:输入非法/事实未注册/渲染被拒/文件名被占用都返回结构化
+ *      错误,不落任何字节(校验全部发生在打开文件之前)。
+ */
+import { randomBytes } from 'node:crypto';
+import { open, realpath, stat, unlink } from 'node:fs/promises';
+import { isAbsolute, join, sep } from 'node:path';
+import { loadFactRegistry } from './fact-log.js';
+import { ITINERARY_DOC_LIMITS } from '../src/itinerary-doc-shared.js';
+import { renderItineraryDeck } from '../src/itinerary-deck.js';
+/** 产物文件名契约:固定前缀 + ASCII 安全 token + .html(无路径分隔符、无前导点) */
+export const ITINERARY_DECK_ARTIFACT_BASENAME_RE = /^gotry-deck-[A-Za-z0-9][A-Za-z0-9._-]{0,63}\.html$/;
+/** 随机默认名(仅 crypto 十六进制;显式 basename 优先) */
+export const ITINERARY_DECK_ARTIFACT_RANDOM_BYTES = 8;
+const RANDOM_ATTEMPTS = 3;
+const DIR_DENY = ['.git', 'node_modules'];
+const ID_SAMPLE = 3;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasDeniedSegment(p) {
+    return p.split(sep).some(seg => DIR_DENY.includes(seg));
+}
+function fsErrorText(err) {
+    const code = err?.code;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM': return '无写入权限';
+        case 'ENOSPC': return '磁盘空间不足';
+        case 'EROFS': return '只读文件系统';
+        case 'ENOTDIR': return '路径中某段不是目录';
+        case 'ENOENT': return '目录不存在';
+        case 'ENAMETOOLONG': return '文件名过长';
+        default: return typeof code === 'string' ? `文件系统错误 ${code}` : '文件系统错误';
+    }
+}
+/** fact_ids 输入收窄:必填数组、逐条非空短字符串、无重复、不超渲染器容量 */
+function takeFactIds(value) {
+    if (value === undefined || value === null) {
+        return { error: 'fact_ids 必填(字符串数组,可为空数组)', hint: 'id 来自本次会话 exact-date 工具结果记录的注册表;不接受调用方自带事实' };
+    }
+    if (!Array.isArray(value))
+        return { error: 'fact_ids 必须是字符串数组' };
+    if (value.length > ITINERARY_DOC_LIMITS.facts) {
+        return { error: `fact_ids 超出容量上限(${ITINERARY_DOC_LIMITS.facts} 条,实测 ${value.length} 条)` };
+    }
+    const ids = [];
+    const seen = new Set();
+    const duplicates = [];
+    for (const [i, raw] of value.entries()) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            return { error: `fact_ids[${i}] 必须是非空字符串` };
+        if (raw.length > ITINERARY_DOC_LIMITS.factIdChars) {
+            return { error: `fact_ids[${i}] 超出 id 长度上限(${ITINERARY_DOC_LIMITS.factIdChars} 字符)` };
+        }
+        if (seen.has(raw)) {
+            duplicates.push(raw);
+            continue;
+        }
+        seen.add(raw);
+        ids.push(raw);
+    }
+    if (duplicates.length > 0) {
+        return { error: `fact_ids 有重复 id:${duplicates.slice(0, ID_SAMPLE).join('、')}${duplicates.length > ID_SAMPLE ? ` 等 ${duplicates.length} 条` : ''}`, hint: '同一条事实只能选一次;重复选择说明调用方对证据面不确定' };
+    }
+    return { ids };
+}
+function takeBasename(value) {
+    if (value === undefined || value === null)
+        return { basename: `gotry-deck-${randomBytes(ITINERARY_DECK_ARTIFACT_RANDOM_BYTES).toString('hex')}.html` };
+    if (typeof value !== 'string' || value.length === 0)
+        return { error: 'basename 必须是字符串' };
+    if (value.includes('/') || value.includes('\\') || value.includes('..')) {
+        return { error: 'basename 只能是文件名,不能含路径分隔符或 ..', hint: '形如 gotry-deck-2027-thailand.html' };
+    }
+    if (!ITINERARY_DECK_ARTIFACT_BASENAME_RE.test(value)) {
+        return { error: 'basename 不符合命名契约', hint: '必须是 gotry-deck-<ASCII 字母/数字/._->.html(前缀后 1-64 字符)' };
+    }
+    return { basename: value };
+}
+/** 会话工作目录:必须显式且为绝对路径(缺失/空白/相对一律拒绝,绝不回落 '.' 或 process.cwd()),
+ *  按宿主原值解析(trim 只判全空白、绝不归一化路径),已存在、可 realpath、是目录,且不含 .git/node_modules 段 */
+async function resolveWritableDir(cwd) {
+    if (typeof cwd !== 'string' || cwd.trim() === '') {
+        return { error: '会话工作目录缺失:拒绝在未知目录写产物', hint: '写产物必须有宿主显式给出的绝对会话工作目录,不做任何猜测性回落' };
+    }
+    // trim 只用于「是否全空白」判定:真实路径一律按宿主原值使用,绝不归一化——
+    // 尾随空格可能是真实目录名的一部分,归一化会写到同名兄弟目录
+    if (!isAbsolute(cwd)) {
+        return { error: `会话工作目录必须是绝对路径:${cwd}`, hint: '相对路径会随进程工作目录漂移,拒绝写入' };
+    }
+    const canonical = await realpath(cwd).catch(() => null);
+    if (!canonical)
+        return { error: `会话工作目录不存在或无法解析:${cwd}`, hint: '本工具只在真实存在的会话工作目录顶层新建文件' };
+    if (hasDeniedSegment(canonical)) {
+        return { error: '会话工作目录位于受限段(.git/node_modules)内,拒绝写入', hint: `解析后:${canonical}` };
+    }
+    const st = await stat(canonical).catch(() => null);
+    if (!st?.isDirectory())
+        return { error: `会话工作目录不是目录:${canonical}` };
+    return { dir: canonical };
+}
+/** 独占创建:wx(O_CREAT|O_EXCL)既拒绝覆盖既有文件,也拒绝落在指向别处的符号链接上 */
+async function writeExclusive(dir, basename, html) {
+    const target = join(dir, basename);
+    const bytes = Buffer.byteLength(html, 'utf8');
+    let handle;
+    try {
+        handle = await open(target, 'wx', 0o644);
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST') {
+            return { error: `目标文件已存在,拒绝覆盖:${basename}`, hint: '换一个 basename(不传则自动生成随机名);本工具永不覆盖既有产物' };
+        }
+        return { error: `无法在会话工作目录新建文件:${fsErrorText(err)}`, hint: `目标目录:${dir}` };
+    }
+    try {
+        await handle.writeFile(html, 'utf-8');
+    }
+    catch (err) {
+        await handle.close().catch(() => { });
+        await unlink(target).catch(() => { });
+        return { error: `写入产物失败:${fsErrorText(err)}`, hint: `目标文件已清理:${target}` };
+    }
+    await handle.close();
+    const finalPath = await realpath(target).catch(() => target);
+    return { path: finalPath, bytes };
+}
+/**
+ * 生成一份行程 deck HTML 产物。写入唯一目标 = 会话工作目录顶层的新文件;
+ * 事实唯一来源 = deps.stateRoot 的事实注册表。
+ */
+export async function generateItineraryDeckArtifact(input, deps) {
+    if (!isRecord(input))
+        return { ok: false, error: 'input 必须是对象 {title, itinerary, fact_ids, basename?}' };
+    const ids = takeFactIds(input.fact_ids);
+    if ('error' in ids)
+        return { ok: false, error: ids.error, hint: ids.hint };
+    const named = takeBasename(input.basename);
+    if ('error' in named)
+        return { ok: false, error: named.error, hint: named.hint };
+    const registry = await loadFactRegistry(deps.stateRoot);
+    const byId = new Map(registry.map(f => [f.fact_id, f]));
+    const missing = ids.ids.filter(id => !byId.has(id));
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            error: `事实 id 未在当前注册表:${missing.slice(0, ID_SAMPLE).join('、')}${missing.length > ID_SAMPLE ? ` 等 ${missing.length} 条` : ''}`,
+            hint: 'fact_ids 只能取自本会话 exact-date 工具结果的注册表;不接受调用方自带事实对象,也不从 Markdown 猜事实',
+        };
+    }
+    // 顺序保留调用方选择;登记行畸形不在选择阶段放宽——交给 deck 渲染器运行时校验显式拒绝
+    const selected = ids.ids.map(id => byId.get(id));
+    const rendered = renderItineraryDeck({ title: input.title, itinerary: input.itinerary, facts: selected });
+    if (!rendered.ok) {
+        return {
+            ok: false,
+            error: '渲染被拒:行程或事实不满足渲染契约,未写入任何文件',
+            errors: rendered.errors,
+            hint: '按 errors 修正显式行程结构或换用合法登记的事实;本工具不会静默截断核心行程',
+        };
+    }
+    const dir = await resolveWritableDir(deps.cwd);
+    if ('error' in dir)
+        return { ok: false, error: dir.error, hint: dir.hint };
+    for (let attempt = 0; attempt < (input.basename === undefined || input.basename === null ? RANDOM_ATTEMPTS : 1); attempt++) {
+        const basename = attempt === 0 ? named.basename : `gotry-deck-${randomBytes(ITINERARY_DECK_ARTIFACT_RANDOM_BYTES).toString('hex')}.html`;
+        const written = await writeExclusive(dir.dir, basename, rendered.html);
+        if ('error' in written) {
+            if (attempt + 1 < RANDOM_ATTEMPTS && input.basename === undefined)
+                continue; // 随机名撞车:换名重试
+            return { ok: false, error: written.error, hint: written.hint };
+        }
+        return { ok: true, path: written.path, basename, bytes: written.bytes, fact_ids: ids.ids, overall_verified: false };
+    }
+    return { ok: false, error: '随机文件名多次撞车,未写入文件' };
+}