@danceiny/gotry 0.2.0-rc.27 → 0.2.0-rc.28

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) };
+}

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

@@ -0,0 +1,354 @@
+/**
+ * 会话双区记忆的观测面与可否证指标(P4-4,docs/design/session-dual-zone-memory-design.md §4/§5)。
+ *
+ * 立场:**价值要么可否证,要么不算**。「记得更多」过不了这里任何一关:
+ *   ① 晋升信号质量 = owner 确认率(提议里被确认的比例);
+ *   ② 工作区收益 = intent TTL 内回访的免重问率(配对口径,借 #20);
+ *   ③ 失效命中率 = 被 owner 更正的分区供述 / 分区供述总数(上界,越低越好)。
+ * 三个阈值在**见到任何数据之前**冻结在本文件的 metric contract 里(#20 阈值冻结纪律),
+ * 输入不得改阈值:夹具声明与冻结值不一致即 `contract_invalid` fail-closed。
+ *
+ * 诚实边界(设计 §4 + #20 证据分级):
+ *  - 夹具只证明**契约与算法**:`synthetic_fixture` 的 `exit_evidence_eligible`
+ *    恒 false,`value_claimed` 恒 false;
+ *  - 真实私有 cohort(`observed_private`)同样只到 **candidate**:本模块永不生成
+ *    reviewer/attestation 字段,自证不算证据(与 #228 收集器同纪律);
+ *  - 计数**只有形状**:每层的捕获/修订/弃用计数、晋升提议 vs 确认 vs 否决、
+ *    过期年龄分桶、工作区读命中/未命中——**零 id、零载荷、零时间戳**;
+ *  - 观测路径零定时器、零网络、零驻留服务;计数接收器须显式 opt-in
+ *    (`GOTRY_SESSION_ZONE_OBSERVE=1`),默认不记任何东西;
+ *  - 导出引用全部 HMAC 假名化(复用 #228 收集器的 `pseudonymousRef`)。
+ *
+ * 本模块不碰 #20 scorer 里冻结的 `p4` 闸:那道闸按它自己的证据规则走。
+ */
+import { MemoryLifecycleError, canonicalJson, pseudonymousRef, sha256Hex, } from './memory-lifecycle.js';
+import { HOT_TIERS } from './session-zones.js';
+// ---- 冻结的指标契约(见数据之前钉死;输入不得改) ----------------------------------
+export const SESSION_ZONE_METRIC_CONTRACT_SCHEMA = 'session_zone_metric_contract.v1';
+export const SESSION_ZONE_FIXTURE_SCHEMA = 'session_zone_metric_fixture.v1';
+export const SESSION_ZONE_REPORT_SCHEMA = 'session_zone_metric_report.v1';
+export const SESSION_ZONE_COUNTERS_SCHEMA = 'session_zone_counters.v1';
+export const SESSION_ZONE_EXPORT_SCHEMA = 'session_zone_observation_export.v1';
+/**
+ * 阈值冻结(2026-10-04,P4-4 PR 时,先于任何真实数据):
+ *  - `minimum_sample_count = 5`:沿用 #20 已冻结的 `minimum_pair_count_for_exit = 5`。
+ *    不另发明第二条样本线;低于它比值只是噪声,判定一律 insufficient_sample。
+ *  - `min_confirm_rate = 0.5`:多数提议被 owner 否决的提议器按定义就是调错了。
+ *    0.5 = 「对的比错的多」,是最弱可辩护下界,刻意不设成期望值。
+ *  - `min_reask_avoidance_ratio = 0.5`:与 #20 的 `target_median_reduction_ratio = 0.5`
+ *    同一个数。工作区的收益线就用 M4 Exit 已经冻结的那条线——另发明一条会让 P4
+ *    过一条 M4 过不了的线。
+ *  - `max_stale_hit_rate = 0.1`:被 owner 更正的供述是用户**看得见**的记忆失败。
+ *    十分之一是 TTL 分层被否证的上界(被否证的是分层,不是功能);0.1 是常规误差
+ *    上界,是天花板不是目标。
+ */
+export const SESSION_ZONE_METRIC_CONTRACT = {
+    schema: SESSION_ZONE_METRIC_CONTRACT_SCHEMA,
+    frozen_at: '2026-10-04',
+    frozen_before_any_data: true,
+    minimum_sample_count: 5,
+    min_confirm_rate: 0.5,
+    min_reask_avoidance_ratio: 0.5,
+    max_stale_hit_rate: 0.1,
+};
+export const SESSION_ZONE_METRIC_IDS = [
+    'promotion_signal_quality',
+    'working_zone_payoff',
+    'stale_hit_rate',
+];
+export const SESSION_ZONE_VERDICTS = ['pass', 'below_threshold', 'insufficient_sample'];
+function err(code, detail) {
+    return { ok: false, code, detail };
+}
+// ---- 形状计数(从账本事件确定性投影;零 id、零载荷、零时间戳) ----------------------
+export const ZONE_EXPIRY_BUCKETS = ['lt_1h', 'lt_24h', 'lt_7d', 'gte_7d'];
+function zeroByTier() {
+    return { resource: 0, intent: 0 };
+}
+function bucketOf(ageMs) {
+    if (ageMs < 3_600_000)
+        return 'lt_1h';
+    if (ageMs < 86_400_000)
+        return 'lt_24h';
+    if (ageMs < 7 * 86_400_000)
+        return 'lt_7d';
+    return 'gte_7d';
+}
+/**
+ * 形状计数投影(纯函数,只读):
+ *  - drop 事件只带 note_id,tier 由同一日志里先前的 capture 事件解析(确定性);
+ *  - 过期分桶按注入时钟对 fold 后仍在的笔记判定(过期是读时视图,不是事件);
+ *  - 输出里没有任何 id / 载荷 / 时间戳——只有整数计数。
+ */
+export function projectZoneCounters(events, now) {
+    const counters = {
+        schema: SESSION_ZONE_COUNTERS_SCHEMA,
+        captures: zeroByTier(),
+        revisions: zeroByTier(),
+        drops: zeroByTier(),
+        notebook: { promoted: 0, revised: 0, dropped: 0 },
+        expired: { lt_1h: 0, lt_24h: 0, lt_7d: 0, gte_7d: 0 },
+        live: zeroByTier(),
+    };
+    const tierOf = new Map();
+    const alive = new Map();
+    for (const ev of events) {
+        switch (ev.kind) {
+            case 'hotctx.note.captured':
+                tierOf.set(ev.note.note_id, ev.note.tier);
+                counters.captures[ev.note.tier]++;
+                alive.set(ev.note.note_id, { tier: ev.note.tier, expiresAt: ev.note.ttl_expires_at });
+                break;
+            case 'hotctx.note.revised':
+                tierOf.set(ev.note.note_id, ev.note.tier);
+                counters.revisions[ev.note.tier]++;
+                alive.set(ev.note.note_id, { tier: ev.note.tier, expiresAt: ev.note.ttl_expires_at });
+                break;
+            case 'hotctx.note.dropped': {
+                const tier = tierOf.get(ev.note_id);
+                if (tier)
+                    counters.drops[tier]++;
+                alive.delete(ev.note_id);
+                break;
+            }
+            case 'notebook.entry.promoted':
+                counters.notebook.promoted++;
+                break;
+            case 'notebook.entry.revised':
+                counters.notebook.revised++;
+                break;
+            case 'notebook.entry.dropped':
+                counters.notebook.dropped++;
+                break;
+        }
+    }
+    const nowMs = Date.parse(now);
+    for (const { tier, expiresAt } of alive.values()) {
+        const expMs = Date.parse(expiresAt);
+        if (Number.isNaN(nowMs) || Number.isNaN(expMs))
+            continue; // 坏时钟不猜:既不算活也不算过期
+        if (nowMs < expMs)
+            counters.live[tier]++;
+        else
+            counters.expired[bucketOf(nowMs - expMs)]++;
+    }
+    return counters;
+}
+// ---- 非账本信号的 opt-in 计数接收器(进程内、零持久化、零定时器) -------------------
+export const ZONE_SIGNALS = ['proposal', 'confirm', 'deny', 'read_hit', 'read_miss'];
+export const ZONE_OBSERVE_ENV = 'GOTRY_SESSION_ZONE_OBSERVE';
+export function zeroSignalCounts() {
+    return { proposal: 0, confirm: 0, deny: 0, read_hit: 0, read_miss: 0 };
+}
+/** 显式 opt-in:只有环境里明示 '1' 才记;默认永不记(「无驻留服务、无自动遥测」) */
+export function isZoneObservationOptIn(env = process.env) {
+    return env[ZONE_OBSERVE_ENV] === '1';
+}
+/**
+ * 计数接收器(纯内存):opt-in 关闭时 note() 恒为 no-op(snapshot 全 0)。
+ * 没有定时器、没有 IO、没有网络——它只是五个整数。
+ */
+export function createZoneCounterSink(optIn) {
+    let counts = zeroSignalCounts();
+    return {
+        note(signal) {
+            if (!optIn)
+                return;
+            if (!ZONE_SIGNALS.includes(signal))
+                return;
+            counts[signal]++;
+        },
+        snapshot: () => ({ ...counts }),
+        reset: () => { counts = zeroSignalCounts(); },
+    };
+}
+/**
+ * 进程默认接收器(接线面调用 `noteZoneSignal`):构造时读一次 opt-in 环境,
+ * 默认关 = 五个 0。`configureZoneObservation` 显式重建(测试与显式 CLI opt-in 用)。
+ */
+let defaultSink = createZoneCounterSink(isZoneObservationOptIn());
+export function configureZoneObservation(optIn) {
+    defaultSink = createZoneCounterSink(optIn);
+}
+export function noteZoneSignal(signal) {
+    defaultSink.note(signal);
+}
+export function zoneSignalSnapshot() {
+    return defaultSink.snapshot();
+}
+function verdictOf(sample, value, threshold, direction) {
+    if (sample < SESSION_ZONE_METRIC_CONTRACT.minimum_sample_count || value === null)
+        return 'insufficient_sample';
+    if (direction === 'higher_is_better')
+        return value >= threshold ? 'pass' : 'below_threshold';
+    return value <= threshold ? 'pass' : 'below_threshold';
+}
+function nonNegInt(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0;
+}
+/**
+ * 只读指标投影:
+ *  - schema/evidence_kind 闭集;
+ *  - 夹具声明的 metric_contract 必须逐字段等于冻结契约(输入不得改阈值 → contract_invalid);
+ *  - 样本形状非法即 bad_sample(不猜、不截断);
+ *  - 样本不足即 insufficient_sample(永不因为「只有一两条」就宣布通过)。
+ */
+export function projectZoneMetrics(fixture) {
+    if (typeof fixture !== 'object' || fixture === null || Array.isArray(fixture)) {
+        return err('bad_schema', '夹具必须是对象');
+    }
+    const f = fixture;
+    if (f.schema !== SESSION_ZONE_FIXTURE_SCHEMA) {
+        return err('bad_schema', `未知 schema:${String(f.schema)}(闭集 ${SESSION_ZONE_FIXTURE_SCHEMA})`);
+    }
+    if (f.evidence_kind !== 'synthetic_fixture' && f.evidence_kind !== 'observed_private') {
+        return err('bad_schema', `未知 evidence_kind:${String(f.evidence_kind)}(闭集 synthetic_fixture|observed_private)`);
+    }
+    const declared = f.metric_contract;
+    if (typeof declared !== 'object' || declared === null)
+        return err('contract_invalid', '夹具必须显式声明 metric_contract(阈值冻结纪律)');
+    for (const [key, frozen] of Object.entries(SESSION_ZONE_METRIC_CONTRACT)) {
+        if (declared[key] !== frozen) {
+            return err('contract_invalid', `阈值冻结:${key} 声明值 ${JSON.stringify(declared[key])} ≠ 冻结值 ${JSON.stringify(frozen)}(输入不得改阈值)`);
+        }
+    }
+    if (!Array.isArray(f.promotion_decisions) || !Array.isArray(f.reask_pairs) || !Array.isArray(f.zone_served_facts)) {
+        return err('bad_sample', 'promotion_decisions / reask_pairs / zone_served_facts 必须都是数组');
+    }
+    // ① 晋升信号质量:确认 / (确认 + 否决)
+    let confirmed = 0;
+    let denied = 0;
+    for (const d of f.promotion_decisions) {
+        if (d?.decision === 'confirmed')
+            confirmed++;
+        else if (d?.decision === 'denied')
+            denied++;
+        else
+            return err('bad_sample', `promotion_decisions.decision 闭集 confirmed|denied,实测 ${JSON.stringify(d?.decision)}`);
+    }
+    const decisions = confirmed + denied;
+    const confirmRate = decisions > 0 ? confirmed / decisions : null;
+    // ② 工作区收益:intent TTL 内回访的免重问率
+    let askedTotal = 0;
+    let reaskedTotal = 0;
+    let pairs = 0;
+    for (const p of f.reask_pairs) {
+        if (typeof p?.within_intent_ttl !== 'boolean')
+            return err('bad_sample', 'reask_pairs.within_intent_ttl 必须是布尔');
+        if (!nonNegInt(p.first_visit_asked_fields) || !nonNegInt(p.returning_reasked_fields)) {
+            return err('bad_sample', 'reask_pairs 的字段计数必须是非负整数');
+        }
+        if (p.returning_reasked_fields > p.first_visit_asked_fields) {
+            return err('bad_sample', '回访重问字段数不得大于首访询问字段数(配对口径,不猜)');
+        }
+        if (!p.within_intent_ttl)
+            continue; // TTL 外的回访不是工作区该负责的窗口
+        pairs++;
+        askedTotal += p.first_visit_asked_fields;
+        reaskedTotal += p.returning_reasked_fields;
+    }
+    const avoidance = askedTotal > 0 ? (askedTotal - reaskedTotal) / askedTotal : null;
+    // ③ 失效命中率:被更正的供述 / 供述总数
+    let corrected = 0;
+    for (const s of f.zone_served_facts) {
+        if (typeof s?.corrected !== 'boolean')
+            return err('bad_sample', 'zone_served_facts.corrected 必须是布尔');
+        if (s.corrected)
+            corrected++;
+    }
+    const served = f.zone_served_facts.length;
+    const staleRate = served > 0 ? corrected / served : null;
+    const metrics = [
+        {
+            id: 'promotion_signal_quality',
+            direction: 'higher_is_better',
+            threshold: SESSION_ZONE_METRIC_CONTRACT.min_confirm_rate,
+            sample_count: decisions,
+            value: confirmRate,
+            verdict: verdictOf(decisions, confirmRate, SESSION_ZONE_METRIC_CONTRACT.min_confirm_rate, 'higher_is_better'),
+        },
+        {
+            id: 'working_zone_payoff',
+            direction: 'higher_is_better',
+            threshold: SESSION_ZONE_METRIC_CONTRACT.min_reask_avoidance_ratio,
+            sample_count: pairs,
+            value: avoidance,
+            verdict: verdictOf(pairs, avoidance, SESSION_ZONE_METRIC_CONTRACT.min_reask_avoidance_ratio, 'higher_is_better'),
+        },
+        {
+            id: 'stale_hit_rate',
+            direction: 'lower_is_better',
+            threshold: SESSION_ZONE_METRIC_CONTRACT.max_stale_hit_rate,
+            sample_count: served,
+            value: staleRate,
+            verdict: verdictOf(served, staleRate, SESSION_ZONE_METRIC_CONTRACT.max_stale_hit_rate, 'lower_is_better'),
+        },
+    ];
+    return {
+        ok: true,
+        report: {
+            schema: SESSION_ZONE_REPORT_SCHEMA,
+            evidence_kind: f.evidence_kind,
+            metric_contract: SESSION_ZONE_METRIC_CONTRACT,
+            exit_evidence_eligible: false,
+            value_claimed: false,
+            source_review: {
+                state: f.evidence_kind === 'synthetic_fixture' ? 'not_required_for_synthetic' : 'candidate',
+                reviewer_ref: null,
+                attestation_ref: null,
+            },
+            metrics,
+        },
+    };
+}
+/**
+ * 候选级导出:只带**计数与假名引用**,不带任何内容字段
+ * (无 id、无载荷、无原话、无 session_ref 原文、无时间戳——`generated_at` 除外)。
+ * `source_review` 永远停在 candidate:自证不算证据。
+ */
+export function buildZoneObservationExport(input) {
+    if (typeof input.consent !== 'string' || input.consent.trim().length === 0) {
+        return err('missing_consent', '导出需要显式同意声明(opt-in 收集纪律)');
+    }
+    let datasetRef;
+    let consentRef;
+    try {
+        datasetRef = pseudonymousRef(input.hmacKey ?? '', 'session_zone_dataset', [input.dataset]);
+        consentRef = pseudonymousRef(input.hmacKey ?? '', 'session_zone_consent', [input.consent.trim()]);
+    }
+    catch (e) {
+        const code = e instanceof MemoryLifecycleError && e.code === 'missing_hmac_key' ? 'missing_hmac_key' : 'invalid_hmac_key';
+        return err(code, `HMAC 假名化失败(${code}):引用必须假名化后才可导出`);
+    }
+    const body = {
+        schema: SESSION_ZONE_EXPORT_SCHEMA,
+        evidence_kind: input.evidenceKind,
+        generated_at: input.generatedAt,
+        dataset_ref: datasetRef,
+        consent_ref: consentRef,
+        counters: input.counters,
+        signals: input.signals,
+        observation_opt_in: input.observationOptIn,
+        report: input.report,
+    };
+    return {
+        ok: true,
+        export: { ...body, payload_digest_sha256: sha256Hex(canonicalJson(body)) },
+    };
+}
+/** 导出里允许出现的键闭集(测试据此断言「只有计数与引用,零内容字段」) */
+export const ZONE_EXPORT_ALLOWED_KEYS = [
+    'schema', 'evidence_kind', 'generated_at', 'dataset_ref', 'consent_ref',
+    'counters', 'signals', 'observation_opt_in', 'report', 'payload_digest_sha256',
+    // counters
+    'captures', 'revisions', 'drops', 'notebook', 'expired', 'live',
+    ...HOT_TIERS, 'promoted', 'revised', 'dropped', ...ZONE_EXPIRY_BUCKETS,
+    // signals
+    ...ZONE_SIGNALS,
+    // report
+    'metric_contract', 'exit_evidence_eligible', 'value_claimed', 'source_review', 'metrics',
+    'frozen_at', 'frozen_before_any_data', 'minimum_sample_count', 'min_confirm_rate',
+    'min_reask_avoidance_ratio', 'max_stale_hit_rate',
+    'state', 'reviewer_ref', 'attestation_ref',
+    'id', 'direction', 'threshold', 'sample_count', 'value', 'verdict',
+];