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

package/dist/src/session-link/session-link.js

@@ -0,0 +1,248 @@
+/**
+ * Session link token 签发/校验(issue #580,Phase E;研究决策见
+ * docs/research/karpo-deck-web-research.md §3 Phase E——one-tap 深链回本地
+ * session,不碰写路径,WriteGate 保持 sealed;消费端注册是 M4 激活)。
+ *
+ * HMAC-SHA256 over base64url(payload-json),签名为 base64url。
+ * Token 形如 `${body}.${sig}`(body = base64url(JSON.stringify(payload)))。
+ *
+ * 与 share-token(Phase C)的差异(刻意,非偶然):
+ *   - **schema 闭集到未知键拒绝**:verify 对 payload 里出现 schema 之外的键
+ *     直接 link_invalid——session link 是「de-identified by construction」面,
+ *     链接只携带引用(link_id/session_ref/wish_id)不携带事实/记忆,闭集
+ *     schema 让这句承诺变成可测试字面真(share token 允许附加键,因为 share
+ *     manifest 本身就需要开放扩展;两者威胁模型不同,不共享校验器);
+ *   - **action 词位闭集 = WriteGate 链接层结构性封死**:`plan_it` | `open`,
+ *     词位里不存在 book/pay/confirm——任何写动词连构造都构造不出来
+ *     (sign 层抛错,不只是 verify 层拒绝);
+ *   - **plan_it ⇔ wish_id 成对**:`plan_it` 必须带非空 wish_id(防「规划
+ *     空 wish」退化),`open` 必须不带(防通用打开链接夹带定向意图);
+ *   - **session_ref 路径护栏**:不透明引用,拒绝含 `/` `\` `..` NUL——
+ *     「不写共享状态」的链接层版:链接永远无法命名 state 路径;
+ *   - 失败闭集只有 2 类(`link_invalid` | `link_expired`)——session link
+ *     无 channel/adapter/consent 维度,不需要 share 的 8 类;
+ *   - token 不进 URL:scheme/宿主是消费端渲染期选择(`formatSessionLink`),
+ *     链接产物跨消费端可移植,签名载荷不含宿主细节。
+ *
+ * 硬化清单与 share-token 同源:恰一个点、timingSafeEqual(先长度)、
+ * ttl 非负整数上限 2^31-1(防 expiresMs 溢出 Infinity 永不过期)、
+ * 时间注入(测试不依赖 wall clock)、secret 缺省且 NODE_ENV=production
+ * 时 fail-closed(绝不静默用仓库里公开的 dev 常量签生产链接)——刻意抛错
+ * 保留在签发面(resolve/sign);verify 面把同样的配置错误收敛为 link_invalid,
+ * 不让异常越出「永不抛错」的校验边界。注入时钟本身失效(getTime 非有限值
+ * 或回调抛错)→ fail-closed link_invalid:NaN 与 expiresMs 比较恒 false,
+ * 曾把过期链接静默判成有效——无效时间上不产生任何接受。verify 期 secret
+ * 为非字符串运行期键(数字/对象/Symbol 等 JS 畸形输入)同样收敛 link_invalid,
+ * HMAC 计算本身也在守卫内——任何调用方/配置输入都无法越出「永不抛错」边界。
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** 行动闭集:`plan_it`(回 session 继续规划某条 wish)| `open`(通用打开)。
+ *  **词位即安全边界**——新增行动先 review;book/pay/confirm 等写动词
+ *  永不入集(WriteGate sealed 在链接层的结构性表达)。 */
+export const SESSION_LINK_ACTIONS = ['plan_it', 'open'];
+/** 显式 dev 默认 secret——生产环境必须由 `SESSION_LINK_HMAC_SECRET` env 覆盖 */
+export const DEFAULT_DEV_SESSION_LINK_SECRET = 'gotry-session-link-dev-secret-DO-NOT-USE-IN-PROD';
+/** ttl 上界(秒):2^31-1,防 created_at + ttl*1000 溢出 Number 上限 */
+export const SESSION_LINK_TTL_MAX_SECONDS = 2_147_483_647;
+/** payload schema 的键闭集(verify 用:未知键 → link_invalid) */
+const PAYLOAD_KEYS = ['link_id', 'session_ref', 'action', 'wish_id', 'created_at', 'ttl_seconds'];
+/** 获取运行期 secret:env 优先;production 缺 env 时 fail-closed */
+export function resolveSessionLinkSecret(env = process.env) {
+    const s = env.SESSION_LINK_HMAC_SECRET;
+    if (typeof s === 'string' && s.length > 0)
+        return s;
+    if (env.NODE_ENV === 'production') {
+        throw new Error('SESSION_LINK_HMAC_SECRET 未设置且 NODE_ENV=production:拒绝回落公开的 dev 默认 secret(fail-closed;任何读到仓库的人都能伪造 session link)');
+    }
+    return DEFAULT_DEV_SESSION_LINK_SECRET;
+}
+/** session_ref 路径护栏:不透明引用——含路径分隔/上跳/NUL 即拒(链接永远无法命名 state 路径) */
+function isSafeSessionRef(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 128
+        && !value.includes('/') && !value.includes('\\') && !value.includes('..')
+        && !value.includes('\0');
+}
+/** 签发:payload 校验(闭集 action / plan_it⇔wish_id 成对 / session_ref 护栏 / ttl 上界)
+ *  不过期检查由 verify 做(签名时刻的时钟是消费端的)。非法 payload 抛错——
+ *  构造层把坏链接挡在签名之前,不是等到校验才发现。 */
+export function signSessionLink(payload, secret = resolveSessionLinkSecret()) {
+    if (typeof payload !== 'object' || payload === null) {
+        throw new Error(`signSessionLink:payload 必须是对象(实测 ${String(payload)})`);
+    }
+    if (typeof payload.link_id !== 'string' || payload.link_id.length === 0) {
+        throw new Error('signSessionLink:link_id 必须是非空字符串');
+    }
+    if (!isSafeSessionRef(payload.session_ref)) {
+        throw new Error(`signSessionLink:session_ref 必须是不含路径分隔符的不透明引用(实测 ${String(payload.session_ref)})`);
+    }
+    if (!SESSION_LINK_ACTIONS.includes(payload.action)) {
+        throw new Error(`signSessionLink:action 不在闭集(实测 ${String(payload.action)};允许:${SESSION_LINK_ACTIONS.join(' / ')})。写动词(book/pay/confirm)永不入集——WriteGate 在链接层结构性封死`);
+    }
+    // plan_it ⇔ wish_id 成对(双向:plan_it 必须有目标;open 必须不夹带定向意图)
+    if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+        throw new Error('signSessionLink:action=plan_it 必须携带非空 wish_id(否则「规划」无对象,是退化链接)');
+    }
+    if (payload.action === 'open' && payload.wish_id !== undefined) {
+        throw new Error('signSessionLink:action=open 必须不携带 wish_id(通用打开链接夹带定向意图 = 混淆行动语义)');
+    }
+    if (typeof payload.created_at !== 'string' || payload.created_at.length === 0 || !Number.isFinite(Date.parse(payload.created_at))) {
+        throw new Error('signSessionLink:created_at 必须是可解析的 ISO 时间字符串');
+    }
+    if (typeof payload.ttl_seconds !== 'number' || !Number.isInteger(payload.ttl_seconds)
+        || payload.ttl_seconds < 0 || payload.ttl_seconds > SESSION_LINK_TTL_MAX_SECONDS) {
+        throw new Error(`signSessionLink:ttl_seconds 必须为 0..${SESSION_LINK_TTL_MAX_SECONDS} 的整数(实测 ${String(payload.ttl_seconds)})`);
+    }
+    // 序列化前剥掉 undefined 键(wish_id 缺省时),保证 body 可复现
+    const clean = {};
+    const raw = payload;
+    for (const k of PAYLOAD_KEYS) {
+        const v = raw[k];
+        if (v !== undefined)
+            clean[k] = v;
+    }
+    const body = Buffer.from(JSON.stringify(clean), 'utf-8').toString('base64url');
+    const sig = createHmac('sha256', secret).update(body).digest('base64url');
+    return `${body}.${sig}`;
+}
+/** 校验:secret 解析(守卫体)→ 格式(恰一个点)→ HMAC 等值(timingSafeEqual)
+ *  → schema 闭集(未知键拒绝)→ 字段形态 → plan_it⇔wish_id 成对 → session_ref
+ *  护栏 → 过期(注入时钟失效 = link_invalid)。**永不抛错**:production 缺 env
+ *  secret 与失效时钟都是操作面错误,收敛进 link_invalid(消费端拿到 link_invalid
+ *  只能 fail-closed 不打开任何 session),刻意的配置/签发异常只保留在 resolve/sign 侧。 */
+export function verifySessionLink(token, secret, now = () => new Date()) {
+    // 运行期 secret 解析放进守卫体:production 缺 env 的配置错在验证面 fail-closed
+    // 为 link_invalid,不抛错(若静默回落公开 dev 常量,伪造链接将被放行);
+    // 非字符串运行期键(数字/对象/Symbol 等 JS 畸形调用方输入)同样收敛
+    // link_invalid——createHmac 对它们会抛 TypeError,绝不让异常越出本函数
+    let hmacSecret;
+    try {
+        const resolved = secret === undefined ? resolveSessionLinkSecret() : secret;
+        if (typeof resolved !== 'string')
+            return { ok: false, reason: 'link_invalid' };
+        hmacSecret = resolved;
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (typeof token !== 'string' || token.length === 0)
+        return { ok: false, reason: 'link_invalid' };
+    const dot = token.indexOf('.');
+    // 恰一个点:多点(base64url 解码器会静默吞非法字符)与无点都拒绝
+    if (dot <= 0 || dot === token.length - 1)
+        return { ok: false, reason: 'link_invalid' };
+    if (token.indexOf('.', dot + 1) !== -1)
+        return { ok: false, reason: 'link_invalid' };
+    const body = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    // HMAC 等值比较(先长度,再 timingSafeEqual;Buffer-vs-Buffer);加密计算
+    // 本身也在守卫内——任何运行期键异常收敛 link_invalid,绝不外泄异常
+    let expected;
+    try {
+        expected = createHmac('sha256', hmacSecret).update(body).digest();
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    let actual;
+    try {
+        actual = Buffer.from(sig, 'base64url');
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // 解析 payload
+    let payload;
+    try {
+        const json = Buffer.from(body, 'base64url').toString('utf-8');
+        payload = JSON.parse(json);
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // schema 闭集:未知键拒绝(de-identified by construction 的可测试形式)
+    for (const key of Object.keys(payload)) {
+        if (!PAYLOAD_KEYS.includes(key))
+            return { ok: false, reason: 'link_invalid' };
+    }
+    // 字段形态
+    if (typeof payload.link_id !== 'string' || payload.link_id.length === 0
+        || !isSafeSessionRef(payload.session_ref)
+        || typeof payload.action !== 'string' || !SESSION_LINK_ACTIONS.includes(payload.action)
+        || typeof payload.created_at !== 'string' || payload.created_at.length === 0) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // plan_it ⇔ wish_id 成对(与 sign 同规则,双向)
+    if (payload.action === 'plan_it' && (typeof payload.wish_id !== 'string' || payload.wish_id.length === 0)) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (payload.action === 'open' && payload.wish_id !== undefined) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    // ttl:非负整数且不溢出(防 created_at + ttl*1000 = Infinity 永不过期)
+    const ttl = payload.ttl_seconds;
+    if (typeof ttl !== 'number' || !Number.isInteger(ttl) || ttl < 0 || ttl > SESSION_LINK_TTL_MAX_SECONDS) {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    const createdMs = Date.parse(payload.created_at);
+    if (!Number.isFinite(createdMs))
+        return { ok: false, reason: 'link_invalid' };
+    const expiresMs = createdMs + ttl * 1000;
+    if (!Number.isFinite(expiresMs))
+        return { ok: false, reason: 'link_invalid' };
+    // 注入时钟失效(抛错/非有限值)fail-closed 为 link_invalid——
+    // NaN 与 expiresMs 比较恒 false,失效时钟不得让任何链接通过
+    let nowMs;
+    try {
+        nowMs = now().getTime();
+    }
+    catch {
+        return { ok: false, reason: 'link_invalid' };
+    }
+    if (!Number.isFinite(nowMs))
+        return { ok: false, reason: 'link_invalid' };
+    if (nowMs > expiresMs)
+        return { ok: false, reason: 'link_expired' };
+    return { ok: true, payload: payload };
+}
+/** 默认深链 base(scheme handler 注册是 M4 激活;消费端可传自己的 base) */
+export const DEFAULT_SESSION_LINK_BASE = 'gotry://session';
+/** 渲染期拼 URL:`${base}/${token}`——token 不进 URL 的签名,宿主是消费端选择 */
+export function formatSessionLink(token, base = DEFAULT_SESSION_LINK_BASE) {
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new Error('formatSessionLink:token 必须是非空字符串');
+    }
+    if (typeof base !== 'string' || base.length === 0 || base.endsWith('/')) {
+        throw new Error(`formatSessionLink:base 必须是非空字符串且不以 '/' 结尾(实测 ${String(base)})`);
+    }
+    if (base.includes('?') || base.includes('#')) {
+        throw new Error('formatSessionLink:base 不得含 query/hash(产出即 parseSessionLink 拒绝的形态,锋利边角)');
+    }
+    return `${base}/${token}`;
+}
+/** 从 URL 严格反解 token:路径最后一段,且段本身须呈 `body.sig` 形态(恰
+ *  一个非空 body、非空 sig;段内多点由 verify 终裁——本函数只保证不把一个
+ *  裸 base(`gotry://session`)的最后一段误当 token)。**拒绝 query/hash**——
+ *  拼接歧义(如 `?x=../../etc`)一律 fail-closed;形态不符返回 null(消费端
+ *  不打开)。 */
+export function parseSessionLink(url) {
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    const q = url.indexOf('?');
+    const h = url.indexOf('#');
+    if (q !== -1 || h !== -1)
+        return null;
+    const segments = url.split('/').filter(s => s.length > 0);
+    const token = segments[segments.length - 1];
+    if (segments.length < 2 || token === undefined || token.length === 0)
+        return null;
+    const dot = token.indexOf('.');
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    return token;
+}

package/dist/src/session-zone-ledger.js

@@ -0,0 +1,312 @@
+/**
+ * 会话双区记忆的账本落点(P4-2,docs/design/session-dual-zone-memory-design.md §2):
+ * 把 P4-1 纯核(session-zones.ts)的六个边界事件落到**既有** events 表上,零新表、
+ * 零 schema 迁移、对内核钉死的 state-ledger.ts 零改动——只走它的公开面
+ * (`db.transaction` / `readEvents` / `insertEvent` / `forgetSubject`)。
+ *
+ *  - 写路径 = 单事务{fold 读当前 revs;守门闸;INSERT}:守门在事务内,拒绝即回滚,
+ *    账本无痕(与 motivation/wish 红线同纪律)。批量写共用一个事务 → 全有或全无。
+ *  - 幂等键 = P4-1 的 `zoneIdemKey`(物理化为 events 表的 UNIQUE 部分索引):同一
+ *    rev 的重放在守门层返回 appended:false,万一绕过守门也会在 UNIQUE 处变成物理
+ *    no-op(insertEvent 返回 null)——两道都保证「同 rev 重放零新行」。
+ *  - 读路径 = `readEvents(kind)` ×6 + P4-1 的确定性 fold(`readTrips`/
+ *    `projectUtilityNow` 同款):无持久投影(P4 v1 单用户量级下读时 fold 够用)。
+ *    过期是读时视图,不是事件——墙钟动作不进 append-only 账本。
+ *  - 删除 = 既有 `forgetSubject`(物理硬删 + 审计一行;红线 6「可删除」);
+ *    会话级遗忘把该会话全部主体放进**一次** forgetSubject 调用 → 仍只留一行审计。
+ *  - 导出 = 从 fold 派生的两个视图(`hot-context.jsonl` / `notebook.json`),
+ *    state-cli export 单向写出;**视图永不是写路径**(导出零新事件)。
+ *
+ * 边界:本模块不接会话捕获缝/persona 读回(P4-3),不做观测与指标(P4-4);
+ * 日志类事件在 state-ledger 的 `foldEvent` default 分支无投影,与
+ * `trip.logged`/`memory_utility.event` 完全同形。
+ */
+import { ZONE_EVENT_KINDS, captureHotNote, dropHotNote, dropNotebookEntry, foldZoneEvents, makeHotNoteId, promoteHotNote, readNotebook, reviseHotNote, reviseNotebookEntry, zoneIdemKey, } from './session-zones.js';
+/** 工作区三事件(forget 的 hot 主体 kinds) */
+export const HOT_ZONE_EVENT_KINDS = [
+    'hotctx.note.captured',
+    'hotctx.note.revised',
+    'hotctx.note.dropped',
+];
+/** 笔记本三事件(forget 的 durable 主体 kinds) */
+export const NOTEBOOK_ZONE_EVENT_KINDS = [
+    'notebook.entry.promoted',
+    'notebook.entry.revised',
+    'notebook.entry.dropped',
+];
+/** 单 kind 读上界:触顶即 fail-closed(截断的日志 fold 出来的 rev 是错的,不许写) */
+export const ZONE_LOG_READ_LIMIT = 20_000;
+/** 默认 actor(P4-3 的工具面会传各自的具名 actor) */
+export const ZONE_DEFAULT_ACTOR = 'tool:gotry_session_zone';
+/** 事件行 → ZoneEvent(形状不合法返回 null:确定性跳过,不猜) */
+function rowToZoneEvent(row) {
+    let payload;
+    try {
+        payload = JSON.parse(row.payload);
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const p = payload;
+    switch (row.kind) {
+        case 'hotctx.note.captured':
+        case 'hotctx.note.revised':
+            return typeof p.note === 'object' && p.note !== null
+                ? { kind: row.kind, ts: row.ts, note: p.note }
+                : null;
+        case 'hotctx.note.dropped':
+            return typeof p.note_id === 'string' && p.note_id.length > 0
+                ? { kind: row.kind, ts: row.ts, note_id: p.note_id }
+                : null;
+        case 'notebook.entry.promoted':
+        case 'notebook.entry.revised':
+            return typeof p.entry === 'object' && p.entry !== null
+                ? { kind: row.kind, ts: row.ts, entry: p.entry }
+                : null;
+        case 'notebook.entry.dropped':
+            return typeof p.entry_id === 'string' && p.entry_id.length > 0
+                ? { kind: row.kind, ts: row.ts, entry_id: p.entry_id }
+                : null;
+        default:
+            return null;
+    }
+}
+/** 事件 → 落账载荷(与 `trip.logged` 的 `{ trip }` 同形:变更后全量文档随事件走) */
+function eventPayload(ev) {
+    switch (ev.kind) {
+        case 'hotctx.note.captured':
+        case 'hotctx.note.revised':
+            return { subjectId: ev.note.note_id, payload: { note: ev.note } };
+        case 'hotctx.note.dropped':
+            return { subjectId: ev.note_id, payload: { note_id: ev.note_id } };
+        case 'notebook.entry.promoted':
+        case 'notebook.entry.revised':
+            return { subjectId: ev.entry.entry_id, payload: { entry: ev.entry } };
+        case 'notebook.entry.dropped':
+            return { subjectId: ev.entry_id, payload: { entry_id: ev.entry_id } };
+    }
+}
+/**
+ * 读分区日志:六个 kind 各自 `readEvents` → 按 seq 升序归并 → P4-1 确定性 fold。
+ * 任一 kind 触到 limit 即 truncated(写路径据此 fail-closed:截断日志的 rev 不可信)。
+ */
+export function readZoneLog(ledger, opts = {}) {
+    const limit = opts.limit ?? ZONE_LOG_READ_LIMIT;
+    const rows = [];
+    let truncated = false;
+    for (const kind of ZONE_EVENT_KINDS) {
+        const batch = ledger.readEvents(kind, limit);
+        if (batch.length >= limit)
+            truncated = true;
+        for (const r of batch)
+            rows.push({ seq: r.seq, ts: r.ts, kind: r.kind, payload: r.payload });
+    }
+    rows.sort((a, b) => a.seq - b.seq);
+    const events = [];
+    let malformed = 0;
+    for (const row of rows) {
+        const ev = rowToZoneEvent(row);
+        if (ev === null)
+            malformed++;
+        else
+            events.push(ev);
+    }
+    return { state: foldZoneEvents(events), events, truncated, malformed };
+}
+/** 单请求过 P4-1 写门(账本层不重写任何算术/闸语义,只转发) */
+function gateRequest(state, req) {
+    switch (req.op) {
+        case 'capture':
+            return captureHotNote(state, req.input);
+        case 'capture_or_touch': {
+            // 先走 capture 的完整闸链(闭集/形状/有界/负面清单/时钟);只有「同 id 已存在」
+            // 这一种拒收(stale_rev)才转成续命写入——其余拒收原样上报,闸语义零放宽。
+            const birth = captureHotNote(state, req.input);
+            if (birth.ok || birth.code !== 'stale_rev')
+                return birth;
+            const noteId = makeHotNoteId({
+                session_ref: req.input.session_ref,
+                tier: req.input.tier,
+                kind: req.input.kind,
+                payload: req.input.payload,
+            });
+            const cur = noteId === null ? undefined : state.hot[noteId];
+            if (!cur)
+                return birth;
+            // 同一写入时刻的同形重放:TTL 已自该时刻起算,再续一次只是空转 rev → 幂等 no-op。
+            // (id 由会话+层+kind+规范载荷派生,所以撞到这里时载荷与 kind 必然相同,只有 ts 可能不同。)
+            if (cur.last_touched_at === req.input.ts) {
+                return {
+                    ok: true,
+                    appended: false,
+                    idemKey: zoneIdemKey({ kind: 'hotctx.note.revised', ts: req.input.ts, note: cur }),
+                    detail: '同写入时刻同形重放:幂等 no-op(TTL 已自该时刻起算)',
+                };
+            }
+            // 同语义片段再次出现 = 续命写入(TTL 自本次写入起算;过期笔记据此复活)
+            return reviseHotNote(state, {
+                note_id: cur.note_id,
+                expected_rev: cur.rev,
+                payload: req.input.payload,
+                kind: req.input.kind,
+                ts: req.input.ts,
+            });
+        }
+        case 'revise':
+            return reviseHotNote(state, req.input);
+        case 'drop':
+            return dropHotNote(state, req.note_id, req.ts);
+        case 'promote':
+            return promoteHotNote(state, req.input);
+        case 'notebook_revise':
+            return reviseNotebookEntry(state, req.input);
+        case 'notebook_drop':
+            return dropNotebookEntry(state, req.entry_id, req.ts);
+    }
+}
+/** 批量写被拒时的回滚载体(事务内抛出 → better-sqlite3 回滚 → 外层取回结果) */
+class ZoneBatchRejected extends Error {
+    results;
+    constructor(results) {
+        super('zone batch rejected');
+        this.results = results;
+    }
+}
+/**
+ * 批量追加(单事务,全有或全无):
+ *  - 事务内先 fold 读一次当前状态,逐请求过闸并把已接受的事件并入在算状态
+ *    (批内自洽:同一事务里 capture→revise 的 rev CAS 成立);
+ *  - 任一请求被拒 → 抛出 → 整个事务回滚 → 账本零新行,返回逐项结果;
+ *  - 日志截断 → 第一项即 `log_truncated`,零写入(不在不全的日志上猜 rev)。
+ */
+export function appendZoneWrites(ledger, requests, opts = {}) {
+    if (requests.length === 0)
+        return [];
+    const actor = opts.actor ?? ZONE_DEFAULT_ACTOR;
+    const run = ledger.db.transaction(() => {
+        const read = readZoneLog(ledger, { limit: opts.limit });
+        if (read.truncated) {
+            throw new ZoneBatchRejected([
+                { ok: false, code: 'log_truncated', detail: `分区事件日志触到读上界(${opts.limit ?? ZONE_LOG_READ_LIMIT});截断日志的 rev 不可信,写路径 fail-closed` },
+            ]);
+        }
+        const events = [...read.events];
+        let state = read.state;
+        const results = [];
+        for (const req of requests) {
+            const gate = gateRequest(state, req);
+            if (!gate.ok) {
+                results.push({ ok: false, code: gate.code, detail: gate.detail });
+                throw new ZoneBatchRejected(results);
+            }
+            if (!gate.appended) {
+                results.push({ ok: true, appended: false, idemKey: gate.idemKey, detail: gate.detail });
+                continue;
+            }
+            const ev = gate.event;
+            const { subjectId, payload } = eventPayload(ev);
+            const seq = ledger.insertEvent({ actor, kind: ev.kind, subjectId, payload, idemKey: gate.idemKey, ts: ev.ts });
+            if (seq === null) {
+                // 守门闸刚说该追加(fold 里没有这条),却撞上既有幂等键 → 生代碰撞:
+                // 同一毫秒内 capture→drop→重捕获会复用 `<id>:<created_at>:1`。这不是幂等重放,
+                // 而是**这次写入没发生**。静默报 appended:false 会骗调用方,所以显式失败、整批回滚。
+                results.push({
+                    ok: false,
+                    code: 'idem_collision',
+                    detail: `幂等键已存在但 fold 中无此主体(生代碰撞:${gate.idemKey});本次写入未发生,请用不同的写入时刻重试`,
+                });
+                throw new ZoneBatchRejected(results);
+            }
+            events.push(ev);
+            state = foldZoneEvents(events);
+            results.push({ ok: true, appended: true, idemKey: gate.idemKey, seq, event: ev });
+        }
+        opts.beforeCommit?.();
+        return results;
+    });
+    try {
+        return run();
+    }
+    catch (e) {
+        if (e instanceof ZoneBatchRejected)
+            return e.results;
+        throw e;
+    }
+}
+/** 单请求追加(批量的 1 元特例) */
+export function appendZoneWrite(ledger, request, opts = {}) {
+    return appendZoneWrites(ledger, [request], opts)[0];
+}
+/** 主体级遗忘:一次 forgetSubject 调用 → 物理删除全部相关事件 + 恰一行审计 */
+export function forgetZoneSubjects(ledger, subjects, actor = 'system:state-cli') {
+    if (subjects.length === 0)
+        return { deleted: 0, subjects: 0 };
+    const specs = subjects.map(s => ({
+        kinds: [...(s.zone === 'hot_context' ? HOT_ZONE_EVENT_KINDS : NOTEBOOK_ZONE_EVENT_KINDS)],
+        subjectId: s.id,
+    }));
+    const r = ledger.forgetSubject(specs, actor);
+    return { deleted: r.deleted, subjects: specs.length };
+}
+/**
+ * 会话级遗忘:该会话的全部工作区笔记 + 血缘指向该会话的全部笔记本条目,
+ * 放进**一次** forgetSubject 调用 → 仍只留一行审计(「删除本身留一行」)。
+ *
+ * 截断即拒(fail-closed):主体集合是从 fold 推出来的,而 `readEvents` 触到读上界时
+ * 丢的是**最老**的事件——在截断日志上做遗忘会静默漏删主体,红线 6「可删除」就
+ * fail-open 了。宁可报错让调用方提高上界/先归档,也不假装删干净了。
+ */
+export function forgetZoneSession(ledger, sessionRef, actor = 'system:state-cli', opts = {}) {
+    const { state, truncated } = readZoneLog(ledger, opts);
+    if (truncated) {
+        return {
+            ok: false,
+            code: 'log_truncated',
+            detail: `分区事件日志触到读上界(${opts.limit ?? ZONE_LOG_READ_LIMIT}):截断日志会漏掉最老的主体,遗忘拒绝在不完整视图上执行`,
+        };
+    }
+    const subjects = [];
+    for (const note of Object.values(state.hot)) {
+        if (note.session_ref === sessionRef)
+            subjects.push({ zone: 'hot_context', id: note.note_id });
+    }
+    for (const entry of Object.values(state.notebook)) {
+        if (entry.origin?.session_ref === sessionRef)
+            subjects.push({ zone: 'trip_notebook', id: entry.entry_id });
+    }
+    const r = forgetZoneSubjects(ledger, subjects, actor);
+    return { ok: true, deleted: r.deleted, subjects: r.subjects };
+}
+// ---- 导出视图(从 fold 派生;单向 DB→文件,永不是写路径) --------------------------
+export const ZONE_EXPORT_HOT_FILE = 'hot-context.jsonl';
+export const ZONE_EXPORT_NOTEBOOK_FILE = 'notebook.json';
+/**
+ * 两个派生视图:直接取 fold 结果渲染,确定性排序。
+ * hot 视图导出的是 fold 里**未被 drop** 的全部笔记(每条自带 ttl_expires_at,
+ * 过期判定留给读者/同一纯函数)——导出不引入第二个过期口径。
+ */
+export function renderZoneExportViews(state) {
+    const notes = Object.values(state.hot).sort((a, b) => (a.note_id < b.note_id ? -1 : 1));
+    return {
+        hotContextJsonl: notes.length ? notes.map(n => JSON.stringify(n)).join('\n') + '\n' : '',
+        notebookJson: JSON.stringify(readNotebook(state), null, 2),
+    };
+}
+/**
+ * 账本 → 导出视图(导出面唯一入口;截断即拒 fail-closed)。
+ * 「可见可导出」同样不能 fail-open:截断日志导出的是**残缺**视图,而读者会把
+ * 它当全量。纯渲染器 `renderZoneExportViews` 留给已确认完整的 state 使用。
+ */
+export function readZoneExportViews(ledger, opts = {}) {
+    const { state, truncated } = readZoneLog(ledger, opts);
+    if (truncated) {
+        return {
+            ok: false,
+            code: 'log_truncated',
+            detail: `分区事件日志触到读上界(${opts.limit ?? ZONE_LOG_READ_LIMIT}):导出拒绝输出残缺视图(读者会把它当全量)`,
+        };
+    }
+    return { ok: true, views: renderZoneExportViews(state) };
+}