berry-agent 0.1.0-alpha.1

package/dist/persist/paths.js

@@ -0,0 +1,108 @@
+/**
+ * persist — 主库归属与数据目录解析（05 篇 §6.7 三级梯子 + §6.6 权限纪律）。
+ *
+ * 三级梯子：显式 BERRY_AGENT_DATA_DIR > 显式 BERRY_AGENT_DB_PATH > 缺省
+ * ~/.berry-agent/sessions.db。环境变量优先级与命名全表在 07 篇；本文件是
+ * 梯子的唯一实现（宿主各入口共用，禁止散落第二份解析）。
+ */
+import { chmodSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** 数据目录环境变量（整目录覆盖——多数据目录 = 独立实例的正门，05 §6.6） */
+export const DATA_DIR_ENV = 'BERRY_AGENT_DATA_DIR';
+/** 库文件路径环境变量（单文件级覆盖——优先于数据目录拼接位） */
+export const DB_PATH_ENV = 'BERRY_AGENT_DB_PATH';
+/** 缺省数据目录名（家目录下） */
+export const DEFAULT_DATA_DIR_BASENAME = '.berry-agent';
+/** 缺省主库文件名 */
+export const DEFAULT_DB_BASENAME = 'sessions.db';
+/** 内存库哨兵值（CLI 组合诊断形态；better-sqlite3 原生 :memory: 语义） */
+export const MEMORY_DB_PATH = ':memory:';
+/**
+ * 解析数据目录（梯子第 1/3 级）：BERRY_AGENT_DATA_DIR 显式值 > 缺省 ~/.berry-agent。
+ * 注意：不解析 BERRY_AGENT_DB_PATH（那是库文件级覆盖，见 resolveDatabasePath）。
+ */
+export function resolveDataDir() {
+    const override = process.env[DATA_DIR_ENV];
+    if (override && override.trim() !== '')
+        return override;
+    return join(homedir(), DEFAULT_DATA_DIR_BASENAME);
+}
+/**
+ * 解析主库文件路径（三级梯子全序）：
+ * BERRY_AGENT_DB_PATH（完整文件路径，含 ':memory:' 哨兵直通）
+ * > BERRY_AGENT_DATA_DIR 目录下 sessions.db
+ * > 缺省 ~/.berry-agent/sessions.db。
+ */
+export function resolveDatabasePath() {
+    const dbOverride = process.env[DB_PATH_ENV];
+    if (dbOverride && dbOverride.trim() !== '')
+        return dbOverride;
+    return join(resolveDataDir(), DEFAULT_DB_BASENAME);
+}
+/**
+ * 解析主库文件路径（锚定数据目录形——宿主装配根显式 dataDir 位的配套解析）：
+ * BERRY_AGENT_DB_PATH 单文件级覆盖在场恒赢（tier-2 不被目录锚定吞掉）；
+ * 否则库文件 = 传入目录下 sessions.db。
+ *
+ * 为什么需要本形（bug 回归锁的规范位）：resolveDatabasePath() 只看 env 梯子，
+ * 完全无视调用方显式传入的 dataDir——宿主装配根（CLI --data-dir / 测试 rig）
+ * 传了 dataDir 时库仍开在 env/家目录位，secret.key 与库分家（1e3a299 修过
+ * CLI 直开库两处的同病，装配根主路径是漏网的第三处）。参数级语义：
+ * 显式 dataDir > env BERRY_AGENT_DATA_DIR（常识序——显式参数先于 env）。
+ */
+export function resolveDatabasePathIn(dataDir) {
+    const dbOverride = process.env[DB_PATH_ENV];
+    if (dbOverride && dbOverride.trim() !== '')
+        return dbOverride;
+    return join(dataDir, DEFAULT_DB_BASENAME);
+}
+/**
+ * 确保数据目录在场且权限 0700（05 §6.6 自检修复 + warn——凭证是操作者状态
+ * 五样之一，目录权限是第一道面）。幂等：在场且权限已符即静默通过。
+ * @param dir 数据目录路径
+ * @param warn 权限修复告警面（装配根接 logger.warn；缺省 console.error）
+ */
+export function ensureDataDir(dir, warn) {
+    if (!existsSync(dir)) {
+        // mkdir 递归建链（父目录缺省权限随 umask——只执法数据目录自身 0700）
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    repairMode(dir, 0o700, '数据目录', warn);
+}
+/**
+ * 单文件权限自检修复（0600 面——主库文件/secret.key 共用）：不符即 chmod
+ * 修复 + warn（best-effort——chmod 失败也 warn 后继续，权限是加固面不是门禁）。
+ * @param target 目标路径（须已存在）
+ * @param name 告警文案里的目标名
+ */
+export function repairFileMode(target, name, warn) {
+    repairMode(target, 0o600, name, warn);
+}
+/** 权限位自检修复共用腿（目录 0700 / 文件 0600 同式） */
+function repairMode(target, mode, name, warn) {
+    let bits;
+    try {
+        bits = statSync(target).mode & 0o777;
+    }
+    catch {
+        return; // 不存在/不可 stat——创建方负责，此处不越权
+    }
+    if (bits === mode)
+        return;
+    try {
+        chmodSync(target, mode);
+        warn(`[persist] ${name}权限 ${bits.toString(8)} ≠ ${mode.toString(8)}，已修复（${target}）`);
+    }
+    catch (err) {
+        warn(`[persist] ${name}权限 ${bits.toString(8)} ≠ ${mode.toString(8)}，修复失败：${String(err)}`);
+    }
+}
+/** 数据目录派生位（secret.key 等数据目录内文件的定位面） */
+export function dataFilePath(dataDir, basename) {
+    return join(dataDir, basename);
+}
+/** 库文件路径的数据目录推算（备份文件命名等邻接文件定位面） */
+export function databaseDir(dbPath) {
+    return dirname(dbPath);
+}

package/dist/persist/persistence.js

@@ -0,0 +1,229 @@
+/**
+ * persist — Persistence 门面（05 篇 §6 的进程级编排面）。
+ *
+ * 组合 Store（物理读写）与 WriteBehind（批落编舞），向 host 装配根暴露：
+ * 会话创建/装载/种子创建（§5 fork·导入的物理腿）/ flush 屏障 / close 退出序 /
+ * 跨会话查询透传。SessionLog 经 onAppend 回调接入（append 热路径零 I/O——
+ * 落库异步在写队列）。
+ *
+ * 退出钩子（exit 前强制 flush + 失败退出非零码）归 host 装配根（07 篇进程
+ * 模型批接线）——本文件只提供 flush/close 两个编舞原语。
+ */
+import { randomUUID } from 'node:crypto';
+import { BaseError } from '../contracts/index.js';
+import { SessionLog } from '../session/index.js';
+import { resolveDataDir, resolveDatabasePath } from './paths.js';
+import { openStore, } from './store.js';
+import { WriteBehind } from './write-behind.js';
+/**
+ * Persistence——进程级单例门面（05 §6.1 律 2：进程内多会话共用）。
+ *
+ * 会话 id 发放纪律（§5.2「不返回幻影 id」的分层落地）：
+ *  - createSession：新开空会话——id 即刻发放但**零持久化承诺**（行随首事件
+ *    落库；无事件即无行——空会话本就无可读内容）；
+ *  - createSeededSession：fork/导入种子——**先同步落库再返回 id**（调用方
+ *    拿到的 id 必可读——半导入状态不可见，§5.1 flush 前置）。
+ */
+export class Persistence {
+    store;
+    writeBehind;
+    warn;
+    /** durable 事件活体镜像（缺省零回调——纯库形态/测试面） */
+    onDurableEvent;
+    /** 已打开会话的登记快照（onAppend 闭包捕获用——首登身份，与 sessions 行首登同源） */
+    registrations = new Map();
+    closed = false;
+    constructor(store, writeBehind, warn, onDurableEvent) {
+        this.store = store;
+        this.writeBehind = writeBehind;
+        this.warn = warn;
+        this.onDurableEvent = onDurableEvent;
+    }
+    /**
+     * 开库并装配（openStore 门禁序 + 写队列接线）。
+     * 失败面全部 fail-loud（TOO_NEW/UNRECOGNIZED/密钥不可读——半装配不留残）。
+     */
+    static open(options = {}) {
+        const warn = options.warn ?? ((message) => console.error(message));
+        const store = openStore({
+            dbPath: options.dbPath ?? resolveDatabasePath(),
+            dataDir: options.dataDir ?? resolveDataDir(),
+            migrations: options.migrations,
+            warn,
+            clock: options.clock,
+            secretKey: options.secretKey,
+        });
+        const writeBehind = new WriteBehind({
+            target: store,
+            warn,
+            clock: options.clock,
+            ...options.writeBehind,
+        });
+        return new Persistence(store, writeBehind, warn, options.onDurableEvent ?? (() => undefined));
+    }
+    ensureOpen() {
+        if (this.closed)
+            throw new Error('Persistence 已关闭（close 后不得再用——调用序 bug）');
+    }
+    /**
+     * 新会话创建（零 I/O——行随首事件经写队列落库）。
+     * @returns 接好 onAppend 的 SessionLog（append 即入队）
+     */
+    createSession(init) {
+        this.ensureOpen();
+        const sessionId = randomUUID();
+        const registration = {
+            origin: init.origin,
+            parentId: init.parentId,
+            seedLength: init.seedLength ?? 0,
+            workspaceRoot: init.workspaceRoot,
+            title: init.title,
+        };
+        return this.attachSession(sessionId, [], registration);
+    }
+    /**
+     * 会话行在场判定（e-4 操控轴幽灵守卫的判据位——loadSession 的零副作用
+     * 读面：只查行不 attach、不合成 closer、不建驱动）。
+     */
+    hasSession(sessionId) {
+        this.ensureOpen();
+        return this.store.getSessionRow(sessionId) !== undefined;
+    }
+    /**
+     * 装载既有会话（恢复重放面）：events 全量读（撕裂尾 heal 在 Store）→
+     * 种子前缀重建 SessionLog → onAppend 接写队列续写。
+     * closer 合成（孤儿 tool/未闭合 turn 等，§4）归调用方——在返回的 log 上
+     * appendSynthetic 补形即可（合成物同权入日志）。
+     * @throws 会话不存在（fail-loud——读未落库 id 属调用方 bug）
+     */
+    loadSession(sessionId) {
+        this.ensureOpen();
+        const row = this.store.getSessionRow(sessionId);
+        if (!row) {
+            throw new BaseError('PERSIST_DATA_CORRUPT', `会话 ${sessionId} 不存在（读未落库 id 或已删除——调用序检视）`);
+        }
+        const events = this.store.loadEvents(sessionId);
+        const registration = {
+            origin: row.origin,
+            parentId: row.parentId,
+            seedLength: row.seedLength,
+            workspaceRoot: row.workspaceRoot,
+            title: row.title,
+        };
+        const log = this.attachSession(sessionId, events, registration);
+        return {
+            log,
+            lineage: row.parentId !== undefined || row.seedLength > 0 || row.origin !== 'conversation'
+                ? { parentId: row.parentId, seedLength: row.seedLength, origin: row.origin }
+                : undefined,
+            row,
+        };
+    }
+    /**
+     * 种子会话创建（fork/导入的物理腿，§5.0/§5.1）：**同步落库**（种子事件 +
+     * sessions 行单事务——flush 语义内联，返回 id 必可读）后发放接好续写的
+     * SessionLog。
+     * @param seed 种子前缀（须为合法种子——ensureSeeded 校验归 session 侧导入闸；
+     *   此处只保物理写：seq 从 0 连续）
+     * @throws 内存会话（:memory:）→ SESSION_PERSISTENCE_REQUIRED（05 §5.1：
+     *   fork 语义需要物理新会话，静默降级为拷贝 = 语义谎言）
+     */
+    createSeededSession(seed, registration) {
+        this.ensureOpen();
+        if (this.store.inMemory) {
+            throw new BaseError('SESSION_PERSISTENCE_REQUIRED', '内存会话（:memory:）不支持 fork/导入种子——fork 语义需要物理新会话（05 §5.1）');
+        }
+        const sessionId = randomUUID();
+        const full = {
+            origin: registration.origin,
+            parentId: registration.parentId,
+            seedLength: seed.length,
+            workspaceRoot: registration.workspaceRoot,
+            title: registration.title,
+        };
+        // 同步落库（绕过写队列——§5.2「不返回幻影 id」：行未提交前不发放 id）
+        if (seed.length > 0) {
+            this.store.writeEvents(seed.map((event) => ({ sessionId, event, registration: full })));
+        }
+        else {
+            // 空种子（如 slice 出空段）：登记行仍须落（无行 = 幻影 id）
+            this.store.registerSessionRow(sessionId, full);
+        }
+        return this.attachSession(sessionId, seed, full);
+    }
+    /** 统一装订：SessionLog 构造 + onAppend 写队列接线 + 登记快照入册 */
+    attachSession(sessionId, seed, registration) {
+        this.registrations.set(sessionId, registration);
+        const writeBehind = this.writeBehind;
+        const log = new SessionLog({
+            sessionId,
+            seed,
+            lineage: registration.parentId !== undefined || registration.seedLength > 0 || registration.origin !== 'conversation'
+                ? { parentId: registration.parentId, seedLength: registration.seedLength, origin: registration.origin }
+                : undefined,
+            onAppend: (event) => {
+                writeBehind.enqueue({ sessionId, event, registration });
+                // 活体镜像（03 §146——写入后即发；观察者异常隔离不影响提交，append
+                // 热路径零 I/O 律不破坏：观察者是内存分派桥非 I/O 面）
+                try {
+                    this.onDurableEvent({ sessionId, event });
+                }
+                catch {
+                    // 镜像观察者故障不波及会话流（双保险腿——dispatch 桥自身另有
+                    // 监听器互隔离）
+                }
+            },
+            warn: this.warn,
+        });
+        return log;
+    }
+    /** 会话删除（flush 先行——在飞事件落定后再三删同事务，§2.5） */
+    async deleteSession(sessionId) {
+        this.ensureOpen();
+        await this.flush();
+        const gone = this.store.deleteSession(sessionId);
+        this.registrations.delete(sessionId);
+        return gone;
+    }
+    /** flush 屏障透传（05 §4——审批落账/压缩对/turn 收口等关键事务点调用） */
+    async flush() {
+        this.ensureOpen();
+        await this.writeBehind.flush();
+    }
+    /** 跨会话查询透传（05 §3.4——obs/goal/CLI 导出的底层原语） */
+    queryEvents(filter) {
+        this.ensureOpen();
+        return this.store.queryEvents(filter);
+    }
+    /** 标题更新透传（auto-title 面） */
+    updateSessionTitle(sessionId, title) {
+        this.ensureOpen();
+        return this.store.updateSessionTitle(sessionId, title);
+    }
+    /** 会话列表透传（「按 cwd 取最新会话」选取面） */
+    listSessions(options = {}) {
+        this.ensureOpen();
+        return this.store.listSessions(options);
+    }
+    /**
+     * 会话内全文检索透传（05 §9 首发口径：查询面限定 session_id——跨会话检索
+     * 非首发面）。**flush 先行归调用方编排**（write-behind 在飞事件不进 FTS
+     * 索引，检索前须屏障）；命中返回 seq 升序列表（limit 缺省 50）。
+     */
+    searchSessionFts(sessionId, pattern, limit) {
+        this.ensureOpen();
+        return this.store.searchSessionFts(sessionId, pattern, limit);
+    }
+    /** 关库退出序：flush（失败即抛——调用方转非零退出，05 §6.3#6）→ checkpoint → close */
+    async close() {
+        if (this.closed)
+            return;
+        await this.flush();
+        this.closed = true;
+        this.store.close();
+    }
+    /** 只读判别（诊断面） */
+    get inMemory() {
+        return this.store.inMemory;
+    }
+}

package/dist/persist/schema.js

@@ -0,0 +1,99 @@
+/**
+ * persist — v1 基线 schema（05 篇 §9 表清单的 DDL 真源）。
+ *
+ * 七对象：events / sessions / store_state / credentials / model_catalog /
+ * session_fts（FTS5 虚表）/ persist_incidents（毒丸 durable 标记，§6.3）。
+ * 列级以 05 §9 表为准绳；本文件是唯一 DDL 事实源（迁移链增量归 migrations
+ * 注册面，宿主聚合 core: 插件表族声明后并入）。
+ *
+ * 身份印记：application_id 写入恒定值（仅 forensics 用途——门禁走 user_version
+ * 版本链 + 空库判定，05 §6.4；不为它立第二道门）。
+ */
+/** 库身份印记（'bage' ASCII——数据值位非标识符；门禁不消费，仅助外部 forensics） */
+export const APPLICATION_ID = 0x6261_6765;
+/** 基线 schema 版本（迁移链起点——v1 即首版六表 + 毒丸标记表，05 §6.4「从 1 起」） */
+export const SCHEMA_VERSION = 1;
+/**
+ * v1 基线 DDL（全新库单事务一次到位——冷启动原子性，05 §6.5）。
+ * 注释里的中文段说明不参与任何比对（本仓 v1 无指纹比对门禁，版本链即门禁）。
+ */
+export const CANONICAL_DDL = `
+-- ── events：会话事件日志物理表（append-only；主键 = 会话内 seq 连续律载体）──
+-- type 索引服务 eventsOfType 面（05 §9 表注）；时间维查询 v1 不建索引
+-- （单人量级顺序扫毫秒级，真实量级再加——承 berry 同款裁决）。
+CREATE TABLE events (
+  session_id        TEXT    NOT NULL,
+  seq               INTEGER NOT NULL,
+  type              TEXT    NOT NULL,
+  time              INTEGER NOT NULL,
+  data              TEXT    NOT NULL,             -- JSON 快照（写入侧已冻结的拷贝序列化）
+  ignorable         INTEGER NOT NULL DEFAULT 0,   -- 读侧向前兼容位（0/1）
+  surface_op        TEXT,                         -- 遮蔽指令 JSON（仅改历史事件携带）
+  source_event_seqs TEXT,                         -- 溯源 seq 数组 JSON（仅遮蔽指令携带）
+  PRIMARY KEY (session_id, seq)
+) STRICT;
+CREATE INDEX idx_events_type ON events(type);
+
+-- ── sessions：会话登记行（血缘三元组 + 工作区选取键；无归属列——会话直归
+--    agent，05 §0；行由 write-behind 首写登记，血缘首登为准不回改）────────────
+CREATE TABLE sessions (
+  id             TEXT    PRIMARY KEY,
+  title          TEXT,                            -- 标题（缺省 NULL；会话列表呈现面消费）
+  origin         TEXT    NOT NULL,                -- 'conversation' | 'delegation' | 'import' | 'fork' | 'trigger'
+  parent_id      TEXT,                            -- 血缘父会话（根会话 NULL）
+  seed_length    INTEGER NOT NULL DEFAULT 0,      -- 种子前缀长度（fork/导入切片）
+  workspace_root TEXT,                            -- 工作区根（按 cwd 取最新会话的选取键）
+  created_at     INTEGER NOT NULL,                -- 毫秒时间戳
+  updated_at     INTEGER NOT NULL,                -- 最后写批时刻（首写登记、批写推进）
+  last_seq       INTEGER NOT NULL DEFAULT 0       -- 已落库最大 seq（批写推进）
+) STRICT;
+CREATE INDEX idx_sessions_workspace ON sessions(workspace_root);
+
+-- ── store_state：插件持久键值统一面（03 篇受理制写面——受理执法在装载层，
+--    物理层只供表与治理：LRU 256 帽 + ttl 过期清扫，05 §6.2）──────────────────
+CREATE TABLE store_state (
+  key              TEXT    PRIMARY KEY,
+  value            TEXT    NOT NULL,              -- JSON 值
+  expires_at       INTEGER,                       -- ttl 到期时刻（NULL = 永不过期）
+  kind             TEXT    NOT NULL DEFAULT 'kv', -- 值类别标签（消费方自释义）
+  last_accessed_at INTEGER NOT NULL               -- 读写触达即刷新（LRU 逐出依据）
+) STRICT;
+
+-- ── credentials：凭证表（api_key 列 AES-256-GCM 密文；0600 纪律见 openStore）──
+CREATE TABLE credentials (
+  provider   TEXT    PRIMARY KEY,
+  api_key    TEXT    NOT NULL,                    -- v1:<base64(iv|tag|ct)>（secret-box 加密产物）
+  meta       TEXT,                                -- JSON 附加元数据（可空）
+  updated_at INTEGER NOT NULL
+) STRICT;
+
+-- ── model_catalog：模型目录（06/07 篇消费；物理 CRUD 面在本模块）──────────────
+CREATE TABLE model_catalog (
+  id         TEXT PRIMARY KEY,                    -- 模型全名（provider/model 形）
+  provider   TEXT NOT NULL,
+  label      TEXT,                                -- 呈现名（可空）
+  meta       TEXT,                                -- JSON 元数据（上下文窗/定价等，可空）
+  updated_at INTEGER NOT NULL
+) STRICT;
+CREATE INDEX idx_model_catalog_provider ON model_catalog(provider);
+
+-- ── session_fts：全文搜索索引（FTS5；派生索引可整体重建——对账三档，05 §9）──
+-- tokenize=trigram：中英混排 substring 检索；session_id/seq UNINDEXED——MATCH
+-- 只打 body，命中行携带定位（会话内检索查询面限定 session_id 过滤，首发口径）。
+CREATE VIRTUAL TABLE session_fts USING fts5(
+  session_id UNINDEXED,
+  seq       UNINDEXED,
+  body,
+  tokenize='trigram'
+);
+
+-- ── persist_incidents：毒丸隔离 durable 标记（§6.3——物理层自账，只增不删）──
+CREATE TABLE persist_incidents (
+  id         INTEGER PRIMARY KEY,
+  time       INTEGER NOT NULL,
+  session_id TEXT,                                -- 被隔离事件所属会话（可空：非事件类故障）
+  seq        INTEGER,                             -- 被隔离事件 seq
+  type       TEXT,                                -- 被隔离事件类型
+  reason     TEXT    NOT NULL                     -- 违例原因（SQLite 码 + 消息）
+) STRICT;
+`;

package/dist/persist/secret-box.js

@@ -0,0 +1,95 @@
+/**
+ * persist — 凭证密文盒（05 篇 §9 credentials 行加密细则，2026-09-05 persist
+ * 落码批补细则的落码面）。
+ *
+ * AES-256-GCM：
+ *  - 密钥 = 数据目录 secret.key（32 字节随机，0600，缺失自动生成——首启自举）；
+ *  - 密文自描述 `v1:<base64(iv|tag|ct)>`（iv 12 字节随机 / tag 16 字节 / ct 明文等长）；
+ *  - 解密失败（密钥丢失/不匹配/密文损坏）→ fail-loud `PERSIST_SECRET_UNREADABLE`
+ *    ——重录凭证即恢复（旧密文作废，不静默降级为明文存储）。
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { BaseError } from '../contracts/index.js';
+import { dataFilePath, repairFileMode } from './paths.js';
+/** 密钥文件名（数据目录内） */
+export const SECRET_KEY_BASENAME = 'secret.key';
+/** 密钥长度（AES-256 位） */
+const SECRET_KEY_LENGTH = 32;
+/** GCM 推荐 iv 长度（12 字节） */
+const IV_LENGTH = 12;
+/** GCM 认证标签长度（16 字节） */
+const TAG_LENGTH = 16;
+/** 密文版本前缀（自描述格式——未来算法升级走 v2 前缀，v1 读侧永在） */
+const BOX_PREFIX = 'v1:';
+/**
+ * 加载或生成数据密钥（幂等自举）：
+ *  - 在场：读出并校验长度（长度异常 = 密钥文件损坏 → fail-loud，宁拒勿猜）；
+ *  - 缺席：randomBytes(32) 落盘（0600——写入即带权限，勿先宽后收留窗口）。
+ * @param dataDir 数据目录（须已存在——ensureDataDir 前置）
+ * @param warn 权限修复告警面（0600 自检修复 + warn，05 §6.6 同款纪律）
+ * @returns 32 字节密钥
+ */
+export function loadOrCreateSecretKey(dataDir, warn) {
+    const keyPath = dataFilePath(dataDir, SECRET_KEY_BASENAME);
+    if (existsSync(keyPath)) {
+        const key = readFileSync(keyPath);
+        if (key.length !== SECRET_KEY_LENGTH) {
+            throw new BaseError('PERSIST_SECRET_UNREADABLE', `密钥文件 ${keyPath} 长度 ${key.length} ≠ ${SECRET_KEY_LENGTH} 字节（损坏或手编）——移除该文件并重录凭证可恢复（旧密文作废）`);
+        }
+        repairFileMode(keyPath, '密钥文件', warn);
+        return key;
+    }
+    const key = randomBytes(SECRET_KEY_LENGTH);
+    // mode 0600 在创建时即生效（open(2) O_CREAT 权限位——umask 只会收紧不会放宽）
+    writeFileSync(keyPath, key, { mode: 0o600 });
+    return key;
+}
+/**
+ * 明文 → 自描述密文（`v1:<base64(iv|tag|ct)>`）。每次加密随机 iv——同明文
+ * 两次加密密文不同（GCM nonce 复用是灾难，结构性排除）。
+ * @param key 32 字节密钥（loadOrCreateSecretKey 产物）
+ * @param plaintext 凭证明文（api_key 等）
+ */
+export function encryptSecret(key, plaintext) {
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return BOX_PREFIX + Buffer.concat([iv, tag, ciphertext]).toString('base64');
+}
+/**
+ * 自描述密文 → 明文。任何一步失败（前缀不认识/base64 损坏/认证标签不过）
+ * 统一抛 `PERSIST_SECRET_UNREADABLE`——调用方对用户的话术是「重录凭证」。
+ * @param key 32 字节密钥
+ * @param boxed encryptSecret 产物（或其存储态）
+ */
+export function decryptSecret(key, boxed) {
+    const fail = (detail) => new BaseError('PERSIST_SECRET_UNREADABLE', `凭证密文不可解读（${detail}）——密钥丢失或不匹配；重录凭证即恢复`);
+    if (!boxed.startsWith(BOX_PREFIX))
+        throw fail('密文缺 v1: 版本前缀');
+    let packed;
+    try {
+        packed = Buffer.from(boxed.slice(BOX_PREFIX.length), 'base64');
+    }
+    catch {
+        throw fail('base64 损坏');
+    }
+    if (packed.length < IV_LENGTH + TAG_LENGTH + 1)
+        throw fail('密文长度不足');
+    const iv = packed.subarray(0, IV_LENGTH);
+    const tag = packed.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+    const ciphertext = packed.subarray(IV_LENGTH + TAG_LENGTH);
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    }
+    catch (err) {
+        throw fail(`认证失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** 测试/诊断面：生成临时内存密钥（:memory: 形态的凭证面用——库亡密亡） */
+export function ephemeralSecretKey() {
+    return randomBytes(SECRET_KEY_LENGTH);
+}