@sema-agent/server 7.52.1 → 7.54.0

package/dist/memory-operator-faces.d.ts

@@ -1,6 +1,6 @@
 /**
- * design/316 件③ —— `GET /v1/memory/entries/:entryId/provenance` · `POST /v1/memory/erase` 两口的
- * **引擎接线**(core 5.57.0 `MemoryEngine.provenanceOf` / `eraseMemoryEntries`,design/178 v2-a/v2-b)。
+ * [ref] 件③ —— `GET /v1/memory/entries/:entryId/provenance` · `POST /v1/memory/erase` 两口的
+ * **引擎接线**(core 5.57.0 `MemoryEngine.provenanceOf` / `eraseMemoryEntries`,[ref] v2-a/v2-b)。
  *
  * ## 为什么是一个模块而不是 main.ts 里直接 new
  *
@@ -25,7 +25,7 @@
  * ⇒ 裁:`controlPlaneRoot` 缺席 ⇒ 本工厂返回 **undefined**,两口整个不挂载,HTTP 面诚实 501。今天满足这一
  * 条的只有 core 自带的 `FileMemoryEngineBackend`(它把控制面写死在 config-root 一侧);本仓两只 SQL 记忆
  * 孪生(`plugins/memory-engine-{pg,tidb}.ts`)没有这个面 ⇒ 在那些部署上两口不挂。SQL 控制面是 core 的候升件
- * (design/316 §0b-4 咨询单),**绝不**在本层为它们现造一个「够用的」控制面 —— 那是把一个 core 拒绝生产的
+ * ([ref] §0b-4 咨询单),**绝不**在本层为它们现造一个「够用的」控制面 —— 那是把一个 core 拒绝生产的
  * 半吊子治理面自己造出来,与 bundle 那条「a governance-less export is the laundering shape」同族。
  *
  * 🔴 这条判断是承重的,所以它有**机器钉**而不是只有这段注释:`test/memory-operator-faces.test.ts` 用一只
@@ -36,16 +36,16 @@
  *
  * 判据是一次**属性检查**、boot 期就判得出、而且是**永久**缺席(换后端才会变)——不是瞬时状态。照旧挂着
  * 就成了「能力位说 yes、每一次调用都确定性失败」,而本仓「says yes ⟺ route works」是结构性承诺。
- * (这条纪律是 #264 提货批被 codex 交叉复审驳倒后立的,见 memory-bundle-engine.ts 头注。)
+ * (这条纪律是 [ref] 提货批被 codex 交叉复审驳倒后立的,见 memory-bundle-engine.ts 头注。)
  *
  * ⚠️ **刻意不把审计/托管/证据三个可选面编进构造判定**:`committedSnapshotOf` / `custodyOf` 缺席时 core
  * 明写要诚实答 `binding:"unknown"` / `contentState:"capability-absent"` / `custody:"capability-absent"`
- * (#196 absence-reports-not-silent-green,engine.d.ts:748 逐字),那是一个**答得出话**的部署;把它们编进
+ * ([ref] absence-reports-not-silent-green,engine.d.ts:748 逐字),那是一个**答得出话**的部署;把它们编进
  * 构造判定会让这种部署整口消失,把 core 的诚实答案换成一句 501 谎话。`eraseWithEvidence` 同理:缺它时
  * core 自己响亮拒(`memory.erasure_evidence_unavailable`),那是**运行期**的诚实拒,与「换部署形态才行」
  * 不是一回事(附录 A 两条分列)。
  */
-import { type EntryProvenanceAccount, type MemoryBackend, type MemoryEntryOrigin, type MemoryErasureAttestation, type OriginClearanceRow } from "@sema-agent/core";
+import { type EntryProvenanceAccount, type MemoryBackend, type MemoryEntryOrigin, type MemoryErasureAttestation, type OriginClearanceRow, type SessionCaptureRecordStore, type SessionMemoryStatus } from "@sema-agent/core";
 /**
  * 控制面归属判据 —— 三个记忆操作面(合规两口 / 外源标记三口 / consolidation 阀门的 D1 拒启门)共用的
  * **同一只**谓词:backend 的面上带**非空** `controlPlaneRoot` 才算归属在案。空串与缺席同判「不归属」:
@@ -128,6 +128,7 @@ opts?: {
     onIncident?: (err: Error & {
         code?: string;
     }) => void;
+    captureRecordStore?: SessionCaptureRecordStore;
 }): MemoryComplianceFaces | undefined;
 /** 件② 三口 HTTP 面消费的窄能力面(`ServiceDeps.memoryOriginFace` 的实参来源)。 */
 export interface MemoryOriginFaces {
@@ -135,7 +136,7 @@ export interface MemoryOriginFaces {
      * §13-4① 视图面:点名 scope 里**每一条**带外源标记的条目 + 它的出处账。
      *
      * 🔴 `scopes` 由**调用方**给,本层不发明默认值:v1 本仓没有任何 scope 枚举读面(core 5.59.0 的
-     * `listMemoryScopes` 已到 File 腿、SQL 腿是 core 候升件 #437④,本仓尚未接线),而「空 scope 名单」
+     * `listMemoryScopes` 已到 File 腿、SQL 腿是 core 候升件 [ref]④,本仓尚未接线),而「空 scope 名单」
      * 与「查全店」在这条路上是两件事 —— 猜一个默认名单会让审计的**不完备变成静默的**(空数组与
      * 「这些 scope 干净」同形)。缺参时路由那侧 400 并指路,理由与文案同源于此。
      */
@@ -161,8 +162,8 @@ export interface MemoryOriginFaces {
     }>;
 }
 /**
- * design/316 件② —— 外源标记人面的**引擎接线**(core 5.59.0 `MemoryEngine.listExternalOriginEntries` /
- * `listOriginClearances` / `clearEntryOrigin`,design/336 §13-4①②)。
+ * [ref] 件② —— 外源标记人面的**引擎接线**(core 5.59.0 `MemoryEngine.listExternalOriginEntries` /
+ * `listOriginClearances` / `clearEntryOrigin`,[ref] §13-4①②)。
  *
  * ## 控制面归属:判据与合规两口**逐字同一条**(§1 F-9 裁),但理由更硬
  *
@@ -182,11 +183,11 @@ export interface MemoryOriginFaces {
  * 而且下一次 resume 调用大概率落到另一台副本、读不到那行 ⇒ 一条被清标的记忆连同它的托管字节一起消失。
  * 本仓是 stateless replicas(CLAUDE.md 首段)。所以判在**构造期**:工厂返 undefined、三口整个不挂、
  * HTTP 面诚实 501,与 `createMemoryComplianceFaces` 同形同码不同文案(要查的旋钮不是同一个)。
- * SQL 控制面是 core 的候升件(design/316 §0b-4 / #437④),**绝不**在本层为它现造一个。
+ * SQL 控制面是 core 的候升件([ref] §0b-4 / [ref]④),**绝不**在本层为它现造一个。
  *
  * ## 刻意不做的两件事
  *
- * ⚠️ **不把 `listScopes` 编进构造判定**:core 5.59.0 长出了 `listMemoryScopes`(#437③,File 腿在场、
+ * ⚠️ **不把 `listScopes` 编进构造判定**:core 5.59.0 长出了 `listMemoryScopes`([ref]③,File 腿在场、
  *    SQL 腿候升),但那是**发现链**的面,不是本族三口的执行前提 —— 把它编进来会让一个「scope 名由运维
  *    自己拿着」的部署整口消失。发现链的不完备由 `GET …/external` 缺参时的 400 文案如实说出来。
  * ⚠️ **不在 seam 里翻译拒因码**:core 的 origin-clear 族是**闭集**,翻译点只有一个(路由的 switch),
@@ -207,5 +208,34 @@ opts?: {
     onIncident?: (err: Error & {
         code?: string;
     }) => void;
+    captureRecordStore?: SessionCaptureRecordStore;
 }): MemoryOriginFaces | undefined;
+/** [ref] seam① 的窄能力面(`ServiceDeps.sessionMemoryStatus` 的实参来源)。 */
+export interface SessionMemoryStatusFace {
+    status: (sessionId: string) => Promise<SessionMemoryStatus>;
+}
+/**
+ * [ref] seam①([ref] §S-7,core 7.0.2 [ref] 件1)—— `GET /v1/sessions/:id/memory-status` 的引擎面。
+ * 命名照 CLAUDE.md 工厂律:返回带行为的活对象 ⇒ `create*`。
+ *
+ * 挂载判据与合规/清标两族**同一条 F-9 裁**(`backendOwnsControlPlane`,理由见文件头):
+ * `committedCount` / `foldedCount` / `lastCaptureAt` 读的是引擎控制面的 lineage 台账 ——
+ * 控制面归属缺席的部署上(两只 SQL 记忆孪生),core 会把控制面落到**副本本地盘**,一个「可读的空目录」
+ * 让 core 面答出 `committedCount: 0`(readLineageRecord 对空目录**不抛**,亲读 engine.js)——
+ * 那是**说谎的 0**,比缺席更坏(S-7 的诚实键律:可读零必须是真零)。⇒ 归属缺席 ⇒ 工厂返 undefined,
+ * HTTP 面诚实 501,与 erase/origin 同码同分支。
+ *
+ * `captureRecordStore` = [ref]② 的 SQL 载体(main.ts 单实例,与 Runner/其余引擎同源 —— 全站同批注入律,
+ * 机器钉 capture-optout-lane ②):`captureOptedOut` / `optOutSource` 两键经它读,多副本部署上答的才是
+ * 跨副本的真记录。缺席(local 车道)⇒ core 文件三腿,单机字节不变。
+ *
+ * 面**不抛**(core 契约:sessionMemoryStatus never throws —— 每个事实源各自 catch 折缺席键);
+ * 不接 onIncident:这条只读路径上今天零 sink 站点,而且缺席键本身就是它的披露形。
+ */
+export declare function createSessionMemoryStatusFace(store: {
+    backend: MemoryBackend;
+    root: string;
+}, opts?: {
+    captureRecordStore?: SessionCaptureRecordStore;
+}): SessionMemoryStatusFace | undefined;
 //# sourceMappingURL=memory-operator-faces.d.ts.map

package/dist/memory-operator-faces.js

@@ -43,6 +43,7 @@ export function createMemoryComplianceFaces(store, opts) {
         backend: store.backend,
         memoryDir: store.root,
         ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
+        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
     });
     return {
         provenanceOf: (entryId) => engine.provenanceOf(entryId),
@@ -66,6 +67,7 @@ export function createMemoryOriginFaces(store, opts) {
         backend: store.backend,
         memoryDir: store.root,
         ...(opts?.onIncident !== undefined ? { onIncident: opts.onIncident } : {}),
+        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
     });
     return {
         listExternal: (scopes) => engine.listExternalOriginEntries(scopes),
@@ -73,4 +75,14 @@ export function createMemoryOriginFaces(store, opts) {
         clear: (entryId, input) => engine.clearEntryOrigin(entryId, input),
     };
 }
+export function createSessionMemoryStatusFace(store, opts) {
+    if (!backendOwnsControlPlane(store.backend))
+        return undefined;
+    const engine = new MemoryEngine({
+        backend: store.backend,
+        memoryDir: store.root,
+        ...(opts?.captureRecordStore !== undefined ? { captureRecordStore: opts.captureRecordStore } : {}),
+    });
+    return { status: (sessionId) => engine.sessionMemoryStatus(sessionId) };
+}
 //# sourceMappingURL=memory-operator-faces.js.map

package/dist/memory-origin-fence.d.ts

@@ -3,7 +3,7 @@ import { type MemoryExportBundle } from "@sema-agent/core";
 export declare const ORIGIN_AWARE_QUERY = "originAware";
 /** 从 `URLSearchParams` 读能力位:`originAware=1` ⇒ true;缺席/其它值 ⇒ false(老客户端假定)。 */
 export declare function readOriginAware(params: URLSearchParams): boolean;
-/** 「这条条目带 origin 标吗」—— 载体三形(G53 [5778] + codex R1-high 后齐):
+/** 「这条条目带 origin 标吗」—— 载体三形(G53 [ref] + codex R1-high 后齐):
  *  ① 顶层 `origin`(listExternal 投影行)—— own 键在场且非 undefined 即带标(不读形;typed null/坏形也算:
  *    core 读取器对 null 会抛,围栏对读不出的载体只许扣留不许放行);
  *  ② `frontmatter.origin`(core `MemoryEntry`,138 S3)—— 同 own 键判;

package/dist/memory-origin-fence.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { committedOriginOf } from "@sema-agent/core";
+import { canonicalJson } from "./canonical-json.js";
 export const ORIGIN_AWARE_QUERY = "originAware";
 export function readOriginAware(params) {
     return params.get(ORIGIN_AWARE_QUERY) === "1";
@@ -33,18 +34,6 @@ export function buildOriginFence(entries, originAware) {
 function sha256Line(text) {
     return createHash("sha256").update(`${text}\n`, "utf8").digest("hex");
 }
-function canonicalJsonStringify(value) {
-    if (Array.isArray(value))
-        return `[${value.map((v) => (v === undefined || typeof v === "function" || typeof v === "symbol" ? "null" : canonicalJsonStringify(v))).join(",")}]`;
-    if (value !== null && typeof value === "object") {
-        const rec = value;
-        const keys = Object.keys(rec)
-            .filter((k) => rec[k] !== undefined)
-            .sort();
-        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJsonStringify(rec[k])}`).join(",")}}`;
-    }
-    return JSON.stringify(value);
-}
 export function buildOriginFencedBundle(bundle, originAware) {
     if (originAware)
         return bundle;
@@ -58,7 +47,7 @@ export function buildOriginFencedBundle(bundle, originAware) {
         integrity: {
             entryCount: kept.length,
             revs: Object.fromEntries(kept.map((e) => [e.id, e.rev])),
-            sectionHashes: { ...bundle.integrity.sectionHashes, entries: sha256Line(canonicalJsonStringify(kept)) },
+            sectionHashes: { ...bundle.integrity.sectionHashes, entries: sha256Line(canonicalJson(kept)) },
         },
         withheldOriginTagged: withheld,
     };

package/dist/memory-posture.d.ts

@@ -1,5 +1,5 @@
 /**
- * #252 件2/件3 —— 记忆面**姿态**的单一推导点。
+ * [ref] 件2/件3 —— 记忆面**姿态**的单一推导点。
  *
  * ## 病
  *
@@ -16,7 +16,7 @@
  *
  * ## 两条诚实纪律
  *
- * ① **档位取实例真值,不按后端推断**([3590] 裁①/[3606]①的延续):`vectorMode` 是「后端上限 × embedder
+ * ① **档位取实例真值,不按后端推断**([ref] 裁①/[ref]①的延续):`vectorMode` 是「后端上限 × embedder
  *    在场」的推断结果,两支 SQL 后端各自的实例 getter 才是真值;file 引擎**根本没有**这个指示面
  *    (core 的 `MemoryBackend` 契约里没有 `vectorMode`,亲验),所以它报 `null` —— 「没有这个指示面」与
  *    「档位是词面」是两件事,折成一件就是编一个数出来。
@@ -51,20 +51,20 @@ export interface MemoryPosture {
         dimensions: number;
     } | null;
     /**
-     * #299(core 5.45.0 design/324):本部署给委派臂设的**证据标准**(`MEMORY_DELEGATION_EVIDENCE`)。
+     * [ref](core 5.45.0 [ref]):本部署给委派臂设的**证据标准**(`MEMORY_DELEGATION_EVIDENCE`)。
      *
      * 🔴 `null` = **本部署没设这个键** ⇒ 引擎按它自己的缺省跑。**不是**「等于 static-face」—— 那句话是
      *    关于 core 缺省的知识声明,本读面不替 core 宣布它(`vectorMode: null` 同一条诚实纪律:
      *    「没有这个指示面」与「档位是词面」是两件事)。运维要知道「实际生效的是哪一档」,读这一位 +
      *    实装 core 的契约,两件事分开摆。
      *
-     * 受众 = **operator 面独占**:与 `darkReason`/`multiTenant`/embedder 身份同判(#252 件3 的分界),
+     * 受众 = **operator 面独占**:与 `darkReason`/`multiTenant`/embedder 身份同判([ref] 件3 的分界),
      * 刻意**不**进 `GET /v1/capabilities` 的窄投影 —— 证据标准回答的是「这台机器怎么判污染」,是运维
      * 诊断料,不是任何持凭证调用方该读的位。
      */
     delegationEvidence: "static-face" | "attested-only" | null;
     /**
-     * #307 件4(core 5.46.0 design/336 §13-3):本部署的 **provenance 姿态**(`MEMORY_PROVENANCE`)——
+     * [ref] 件4(core 5.46.0 [ref] §13-3):本部署的 **provenance 姿态**(`MEMORY_PROVENANCE`)——
      * 一个会话被判为已暴露之后,它的记忆写是**带标收录**(`carry`)还是**整体隔离**(`off`)。
      *
      * 🔴 `null` = **本部署没设这个键** ⇒ 引擎按它自己的缺省跑。**不是**「等于 carry」——
@@ -75,7 +75,7 @@ export interface MemoryPosture {
      */
     provenance: "off" | "carry" | null;
     /**
-     * design/383 §3.1(core 7.0.0 片3,S-49 S-1b):本部署的 **capture 姿态**(`MEMORY_CAPTURE_POLICY`)——
+     * [ref] §3.1(core 7.0.0 片3,[ref] S-1b):本部署的 **capture 姿态**(`MEMORY_CAPTURE_POLICY`)——
      * per-principal `allowMemoryOptOut` verdict 被读进的那个框(`open` fail-safe / `governed` fail-closed /
      * `capture-required` 全拒)。
      *

package/dist/memory-scope.d.ts

@@ -11,7 +11,7 @@ export declare const V2_SCOPE_PREFIXES: readonly string[];
  * 校验点 fail-loud。
  */
 export declare function isV2ScopeKey(key: string): boolean;
-/** Resolve the memory scope for a request (design/138 S1 — the file-based memory engine is the only plane).
+/** Resolve the memory scope for a request ([ref] S1 — the file-based memory engine is the only plane).
  *
  *  SINGLE-USER (REQUIRE_PRINCIPAL !== "true"): ONE shared scope — `config.memoryScope` (default "local"),
  *  regardless of any principal label the caller self-reports (a single-user worker's `anon:*` / ad-hoc
@@ -26,12 +26,12 @@ export declare function isV2ScopeKey(key: string): boolean;
  *  security.ts 把身份轴守住了,但 `formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
  *  **膨胀**——非 ASCII principal 编码后可超列宽,此前落裸 SQL 错。产出处响亮拒,错误可分类。
  *
- *  #271 件1:定义**搬去** `plugins/memory-key-guards.ts`(列宽与 store 写口同源单一属主),此处
+ *  [ref] 件1:定义**搬去** `plugins/memory-key-guards.ts`(列宽与 store 写口同源单一属主),此处
  *  只再导出——旧 import 路径(本文件)逐字不变,`memoryScopeFor` 的产出处消费点也不变。 */
 export { MEMORY_SCOPE_COLUMN_CHARS, assertMemoryScopeWidth } from "./plugins/memory-key-guards.js";
 export declare function memoryScopeFor(config: ServiceConfig, principal?: string, projectId?: string): string | undefined;
 /**
- * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core design/138) materializes and
+ * N0 (通宵测试 2026-07-09,三重坐实 e2b+kata+代码): the file memory engine (core [ref]) materializes and
  * harvests via `node:fs` on the WORKER's local fs, while a remote exec lane routes the model's file tools to
  * the SANDBOX fs — the planes never meet: materialized memory is invisible inside the sandbox (the injected
  * instructions burn failing Write turns) and sandbox writes are never harvested (add=0). Until core defines
@@ -67,7 +67,7 @@ engineWired: boolean): {
     effect: string;
 } | undefined;
 /**
- * design/138 S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
+ * [ref] S1 wiring gate (pure — unit-testable without booting main): build the file-based memory-engine
  * backend for this deployment, or `undefined` when memory must stay dark.
  *
  *  - SINGLE-USER TURNKEY ONLY (`requirePrincipal !== true`): the engine's file basement
@@ -91,13 +91,13 @@ export declare function memoryEngineBackendFor(config: ServiceConfig, fallbackRo
 /**
  * MF-30 memory PAUSE (option B, per-request — clay 2026-06-27): build the `TaskSpec.memory` spec for ONE run from
  * the resolved memory `scope` + the request's `memoryWrite` toggle. `memoryWrite === false` ⇒ `writeScope: null`
- * (design/138 engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
+ * ([ref] engine read-only: normalizeMemorySpec's writeScope:null — materialize/read still works, harvest
  * commits nothing). Absent/true ⇒ normal read+write. No scope (engine off / multi-tenant dark) ⇒ undefined
  * (memory feature off for this run). Pure (testable in isolation) — main.ts's resolveSpec composes it with the
  * engine-backend presence guard.
  */
 export declare function memorySpecForRequest(scope: string | undefined, memoryWrite: boolean | undefined, defaultScopes?: string[], 
-/** design/170 件A(#148 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
+/** [ref] 件A([ref] 件3④):origin 盖章的部署形态维(N2)。`multiTenant=true`(requirePrincipal)
  *  ⇒ 登记簿 defaultScopes 的 org 键按 **request** 盖章(条目由调用方 projectId 选定=caller 可影响的
  *  选择器,core 准入门据此过目录判决);单用户 ⇒ 一律 deployment(operator 登记簿条目归 deployment,
  *  否则单用户部署被自家规则整拒——v4 §0 伤害①的成立前提)。缺参=旧调用形,不盖章(整键缺席=
@@ -105,7 +105,7 @@ export declare function memorySpecForRequest(scope: string | undefined, memoryWr
 originPolicy?: {
     multiTenant: boolean;
 }, 
-/** design/383 §2.1(S-49):请求的 `memoryCapture:"off"` 声明 ⇒ `TaskSpec.memory.capture:"off"`(单成员闭集,
+/** [ref] §2.1([ref]):请求的 `memoryCapture:"off"` 声明 ⇒ `TaskSpec.memory.capture:"off"`(单成员闭集,
  *  拼写门在 prepareSpec 的 400 门 + core 的 `config.memory_capture_spelling`)。缺席 ⇒ 键不铸(缺席就是照常采集
  *  的唯一形)。与 `memoryWrite` 正交:那是「本 run 只读平面」,这是「本会话永远不进长期记忆」。 */
 memoryCapture?: "off"): {

package/dist/model-select.d.ts

@@ -10,7 +10,7 @@
  * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
  * only ever returns an allow-listed catalog name).
  *
- * [865]②(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个):
+ * [ref]②(生产实锤:面板上选了 A 模型,实际跑的是目录里的另一个):
  *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
  *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
  *    上下文污染路径)。
@@ -29,7 +29,7 @@ export declare function resolveTaskModel(bodyModel: unknown, objective: string,
     unknownExplicit?: string;
     notAllowed?: ModelNotAllowed;
 };
-/** #233 判别式拒因:名单在场且这次**用户选择**落在名单外。`resolved` 已是目录 name 形(归一后)。 */
+/** [ref] 判别式拒因:名单在场且这次**用户选择**落在名单外。`resolved` 已是目录 name 形(归一后)。 */
 export interface ModelNotAllowed {
     /** 调用方发来的原始 ref(name / 档位词 / 别名 / id / `@name`),已做过日志安全的 repr 归一。 */
     requested: string;
@@ -39,7 +39,7 @@ export interface ModelNotAllowed {
     source: "explicit" | "mention";
 }
 /**
- * #233 / A-002.8 —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
+ * [ref] / [ref] —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
  *
  * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
  * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 跳过一张按 name 写的名单
@@ -62,7 +62,7 @@ export interface ModelNotAllowed {
  */
 export declare function isModelAllowlisted(ref: string, catalog: Record<string, unknown>, allowlist: readonly string[] | undefined): boolean;
 /**
- * #233 —— ref → **终端 catalog name**(拒因/日志的可读形)。
+ * [ref] —— ref → **终端 catalog name**(拒因/日志的可读形)。
  *
  * 为什么不是 `matchCatalogModel` 的返回值:增广目录里 `pro`/`opus`/`default` 都是**真实存在的键**,
  * 于是 `matchCatalogModel("pro")` 回的就是 `"pro"` —— 那是用户点的那个别名,不是他真会跑的模型。
@@ -71,7 +71,7 @@ export declare function isModelAllowlisted(ref: string, catalog: Record<string,
  */
 export declare function terminalCatalogName(ref: string, catalog: Record<string, unknown>): string | undefined;
 /**
- * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
+ * [ref]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
  *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸
  *    索引下是真值,会跳过 allow-list——沿袭原实现的纪律)。
  *  - id 命中扫目录值(`Model.id`),跳过 "default" 别名键(它与其指向的真身共享 id,解析到别名会让 /model

package/dist/observability/cost-quota.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-principal CUMULATIVE cost quota (design/21/27 follow-up). The per-task `maxCostUsd` gate caps a
+ * Per-principal CUMULATIVE cost quota ([ref]/27 follow-up). The per-task `maxCostUsd` gate caps a
  * SINGLE task; this caps a principal's spend ACROSS tasks within a rolling fixed window. Spend is the
  * authoritative integer `costMicroUsd` accumulated by the tracer (so it includes council/team
  * sub-tasks, via the principal ALS context). A new task is REFUSED once the window's accumulated cost
@@ -19,8 +19,8 @@ export interface QuotaDecision {
 }
 /** The hot-path surface shared by the in-memory {@link CostQuota} (single replica) and the cross-replica
  *  {@link import("../plugins/tidb-cost-quota.js").TiDBCostQuota}. `key` is opaque (principal today;
- *  principal/team/feature later — design/30 N3), so both stores are key-based. */
-/** #322 批1:配额的**值换代**入参(四实现类同一形;单位与构造参数一致 —— USD/秒 → micro/ms 的换算
+ *  principal/team/feature later — [ref] N3), so both stores are key-based. */
+/** [ref] 批1:配额的**值换代**入参(四实现类同一形;单位与构造参数一致 —— USD/秒 → micro/ms 的换算
  *  只有一处,`boot/limit-sync.ts` 的 `buildQuotaBounds`)。`limitMicroUsd <= 0` = **关断哨兵**。 */
 export interface QuotaLimits {
     limitMicroUsd: number;
@@ -29,20 +29,20 @@ export interface QuotaLimits {
 export interface QuotaTracker {
     check(key: string): QuotaDecision;
     add(key: string, micro: number): void;
-    /** #322:值换代座位。**接口级**声明——新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
+    /** [ref]:值换代座位。**接口级**声明——新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
     setLimits(next: QuotaLimits): void;
 }
 export declare class CostQuota implements QuotaTracker {
     private readonly now;
     private windows;
-    /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动(design/322 §5)。 */
+    /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动([ref] §5)。 */
     private limitMicroUsd;
     private windowMs;
     /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs rolling window. */
     constructor(limitMicroUsd: number, windowMs: number, now?: () => number);
     /**
      * 值换代。两件事**语义不同**,别混:
-     *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动(design/322 §5 定案:调小当场更严)。
+     *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动([ref] §5 定案:调小当场更严)。
      *  · **窗长**换代 = 换**记账周期** ⇒ 当代累计重开。
      *
      * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(`floor(now/windowMs)`),

package/dist/observability/cost-taxonomy.d.ts

@@ -1,8 +1,8 @@
 /**
- * design/80 b (item 3) — the INFRA cost axes the SERVICE owns, composed with core's LLM-family `costBreakdown`
+ * [ref] b (item 3) — the INFRA cost axes the SERVICE owns, composed with core's LLM-family `costBreakdown`
  * for the supervisor cost surface.
  *
- * (design/158 N24: moved here from the single-file `src/finance/` directory — lens4 §4.4 flagged the "cost"
+ * ([ref] N24: moved here from the single-file `src/finance/` directory — lens4 §4.4 flagged the "cost"
  * concept as split across `finance/cost-taxonomy.ts` + `observability/cost-quota.ts` + `budget.ts`. Chose
  * "dissolve finance/, fold into observability/" over "collect all three into finance/": this module + the
  * quota tracker are both cost REPORT/GUARD layers that feed metrics/decisions (observability's existing

package/dist/observability/fail-open.d.ts

@@ -81,10 +81,6 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "P-DEBT";
         readonly note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。";
     };
-    readonly "server.hitl.row-derived-approve-drops-updated-input": {
-        readonly cls: "P-DEBT";
-        readonly note: "A-054.15:一条**持久 ask 行**上的 `DECIDED=approve` 被回放成裸 `true` 交给 core —— 而人当时可能是带 **ctrl+g 编辑**批的(`updatedInput`)。持久层没有该列(`AskRow`/`DecideAskInput` 皆无),行读不出「这次批准是否改写过实参」,于是 core 的 `d.updatedInput === undefined` 分支落回**原始未改写**实参执行:人批的是改写后的命令,真跑的是原命令 —— 一次**执行面宽于人所批准**的扩权,方向错的一侧,故记债不当合法兜底。四个同形站点全部计在本 tag 下(只在真把 `true` 交出去时计,不在读到行时计):`replayTerminalAskRow` 的三个消费点(`ensureAsk` 幂等回放 / `convergeFromDurableState` / 店报错臂的 `readDecidedForRecovery`)与 `runs.ts` 的 `syncLiveFromDecidedRow`(settled>0 才算)。⚠️ 计数是**上限**不是实数:分不出这次 approve 原本带没带编辑(能分出来就不用记债了),真丢的是其中带编辑的那一部分。补偿:回体在这条路上**省略** `updatedInputForwarded`(从不发 false = 成文的否定信号)。终局收口 = 给 ask 行加 `updated_input` 列(店语义级,须本模块属主立件),届时本 tag 同批销。";
-    };
     readonly "server.e2b.orphan-skip-unknown": {
         readonly cls: "F";
         readonly note: "#242 E2B 孤儿回收对一只沙盒**判不了属主/活性**(metadata 缺 taskId 的病态形 / run 行状态词在 LIVE 与 TERMINAL 两表之外 / getRun 抛错)⇒ 恒不杀,本轮跳过。方向纪律:回收是清理型能力,缺席判据=不动作——误杀是杀活任务的手,漏杀只是钱;但每次跳过必须计数,否则「回收在跑却总有几只杀不掉」的病灶(店故障/新状态词未收编/别家部署共用 key)永不显形。";
@@ -153,6 +149,22 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "S-15 twin 保留条款(core 7.0.0 design/381 §片2 的 SQL 孪生):boundary 提交后的自剪 pass(core 共享选择函数 `fileHistoryBoundariesToKeep` + 既有 `reap` 级联)失败 ⇒ 本轮 boundary **已提交**、rewind 座照常,只是这一轮没剪。放行的是「GC 失败不失败用户这一轮」(core InMemory/File 参照同形 `reap(...).catch(() => {})`,但参照是无声吞,本仓走留痕三件套);最坏后果 = 该 scope 暂时超上限一个 boundary,下一次提交的 pass 按**当前全集**重算、连它一起剪(不累积欠账)。detail 带 scope / entry / 异常文案。";
     };
+    readonly "server.approval.ambiguous-cas.expire": {
+        readonly cls: "P-DEBT";
+        readonly note: "S-25(设计件 2026-08-31 §3 步骤 3;DEBTS S-25 / #290):流内 ask 的**窗到期臂**打 `expireAsk` CAS 抛错或超墙钟(不知道做没做成)之后,恢复读口 6 格退避 7 次读(≈3.1s;末格睡后仍再读一次,末格不是盲窗 —— codex R1-F1)都读不出行 ⇒ 按本臂意图投影结算 = park 路由(`\"unavailable\"`;`deny` 政策下 `{allow:false,settledBy:\"timeout\"}`)并留 park 墓碑。方向 fail-closed(无 DECIDED=approve 行绝不执行工具),但行**可能**已被另一副本判成 DECIDED(approve) 而本腿没兑现 —— 人批了、工具不跑、run 再挂起要人再批一次 = 丢一次人类决议,故记债不当合法兜底。补偿:core 侧仍 pending 的 checkpoint(人再批一次就走)+ 跨副本收敛器兜底(它落地后本 tag 降 F)。**不计**的形:行读得出、只是仍 STREAM_PENDING / 行不在 —— 那是本臂的期望态(K1),零退避直接投影(codex-R2-2 / R3-1 钉;throw 类 K2 的 pending 投影前重打一把本臂幂等 CAS 换持久背书,R3-F2);编辑在飞标记在场 ⇒ 有界让路、用尽走 park 路由(标记的事不是店的债,codex R1-F2/R2-F2;负终态与带载荷 approve 不受标记压制,R2-F1/R3-F1);行读出 DECIDED ⇒ 按人的决议结算,也不计。detail 带 askId 与读次数。";
+    };
+    readonly "server.approval.ambiguous-cas.cancel": {
+        readonly cls: "P-DEBT";
+        readonly note: "S-25 同族第二员:**取消臂**(task signal abort / 连接全灭同路)打 `transitionAsk(STREAM_PENDING→VOID)` CAS 抛错或超墙钟之后,恢复读口 7 次读都读不出行 ⇒ 按本臂意图投影结算 = 裸 `settle(false,\"expired\")`(D1 纯进程内语义,不留墓碑:run 已拆,迟到的 Yes 无处兑)。S-25 之前这条 catch **不读行**直接 fail-open —— 行已 DECIDED(approve) 时把人的批准翻成拒绝、回决端点只能如实 404(round6 钉曾把这一形记成「局部竞态残影」);现在只有店持续读不出才走到这里,债的语义与 expire 员同(行可能已 DECIDED 而本腿没兑现),按臂分计是为了让「哪条臂在丢决议」在遥测里读得出。";
+    };
+    readonly "server.approval.ambiguous-cas.unreachable": {
+        readonly cls: "P-DEBT";
+        readonly note: "S-25 同族第三员:**emit 全灭臂**(开卡帧两族都没送到任何连接)打 `expireAsk` CAS 抛错或超墙钟之后,恢复读口 7 次读都读不出行 ⇒ 按本臂意图投影结算 = `emitFailed` ⇒ `\"unavailable\"`(park 路由;`deny` 政策下 deny),不留墓碑(卡没到任何人手上,无人持有这把 approvalId)。S-25 之前这条 catch 不读行直接强改 —— 正是 round2 finding A「durable 行已批准、活终局被 emit 全灭强改成 unavailable」的 catch 同形缺口;现在行读出 DECIDED ⇒ 按人的决议结算,只有店持续读不出才计数。";
+    };
+    readonly "server.pg-pool.idle-client-error": {
+        readonly cls: "F";
+        readonly note: "S-55(test [5864] 独立复现):pg 连接池里一条连接被外部终止(pg_terminate_backend / 云端故障切换 / LB 空闲回收)或自身网络错误。**两态一 tag,detail 判别**(`state=idle` / `state=checked-out`;先例=park 墓碑行的两臂 detail 判别):①idle 态 —— node-postgres 语义(pg-pool@3.14.0 makeIdleListener):池在 emit 'error' **之前**已 `_remove` 掉该 client,坏连接自然淘汰,下次 acquire 发新连接,在飞查询零影响;修前 Pool 上无 'error' 监听 ⇒ EventEmitter 把事件转 throw ⇒ uncaughtException ⇒ 整进程 exit 1。②checked-out 态(codex R1-[high] 补,同批修)—— pg-pool 借出时摘 idle 监听(index.js:344),`pool.connect()` 显式持有的连接(事务)在 checkout 期死时 client 直接 emit 'error' 同样打死进程;守卫只观察:中毒 client 的后续查询由 pg 以 `_queryable=false` 响亮拒,归还时池淘汰;同一次 checkout 的死可能双发事件(FATAL 消息 + socket end),warn 逐枚、计数按 checkout 去重。放行的最坏后果 = 下一次 acquire 多付一次建连,故 F 类。必须留痕:「连接不断被外部杀」(故障切换风暴 / 回收策略过激 / 有人在库上清连接)与「一切正常」在服务面同形;每次事件另有逐次结构化 warn(`pg_pool_idle_client_error` / `pg_pool_checked_out_client_error`,含 code/severity),本计数让频率曲线可读。`pool.query()` 快路不在洞内(pg-pool 自带 checkout 期 once('error') 守卫)。mysql2 孪生(tidb-pool)**不同病**:PoolConnection 构造器恒挂 once('error') 库内吞并淘汰、借出期同在(坐标成文在 createTidbPool 头注),故无同族 tag。";
+    };
 };
 /** 词表键推导的闭集类型——未登记的 tag 传不进 {@link recordFailOpen}(编译期拒)。 */
 export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;
@@ -163,7 +175,7 @@ export type FailOpenTag = keyof typeof FAIL_OPEN_TAGS;
  * 断连会让保护型计数涨两次(open 一次、complete 又一次),真正的 open 失败率被面包屑的假阳性盖住。
  * 只有 open 帧是"人在环这道门被跳过"的证据,其余都是体验损失。
  *
- * ⚠️ **两条 question 臂在生产上已不可达**(#173 之后,2026-08-07):本函数唯一的生产调用点是
+ * ⚠️ **两条 question 臂在生产上已不可达**([ref] 之后,2026-08-07):本函数唯一的生产调用点是
  * `routes/tasks.ts` 的 `emitAsk` 断流臂,而 question 与 question_complete 两型帧都先过同文件
  * `emitQuestion` 的断流守卫(两道守卫同步相邻、其间无 await)并在断流时 throw,永不抵达这里;另一条
  * question 路(`runs.ts` 的 durable append)根本不经 emitAsk。在产的只剩 elicitation 族与 default。

package/dist/observability/fail-open.js

@@ -72,10 +72,6 @@ export const FAIL_OPEN_TAGS = {
         cls: "P-DEBT",
         note: "跨副本赎回 parked 审批时,祖先层在 park 时是 **auto-mode 武装**的,但那只分类器是祖先任务上的活闭包(绑着它自己的转写窗+brain),跨进程重建不出来 ⇒ 本仓交一只如实拒答的 decider,core 收到 `unavailable` 后**不产生任何自动裁决**、原样落到祖先冻结审批席那条链(本腿的席位又是无 ALS 的降级形 ⇒ 再 park 给人)。方向:分类器本会 allow 的改成问人(更严),本会 block 的也改成问人(**不是自动放行**,但比自动拒松一档)⇒ 记债不当合法兜底。计数 = 「丢了祖先分类器判决的继承 ask」次数。收口件二选一:core 把分类器判据持久进链条目,或让祖先 decider 有可跨进程重建的形。",
     },
-    "server.hitl.row-derived-approve-drops-updated-input": {
-        cls: "P-DEBT",
-        note: "A-054.15:一条**持久 ask 行**上的 `DECIDED=approve` 被回放成裸 `true` 交给 core —— 而人当时可能是带 **ctrl+g 编辑**批的(`updatedInput`)。持久层没有该列(`AskRow`/`DecideAskInput` 皆无),行读不出「这次批准是否改写过实参」,于是 core 的 `d.updatedInput === undefined` 分支落回**原始未改写**实参执行:人批的是改写后的命令,真跑的是原命令 —— 一次**执行面宽于人所批准**的扩权,方向错的一侧,故记债不当合法兜底。四个同形站点全部计在本 tag 下(只在真把 `true` 交出去时计,不在读到行时计):`replayTerminalAskRow` 的三个消费点(`ensureAsk` 幂等回放 / `convergeFromDurableState` / 店报错臂的 `readDecidedForRecovery`)与 `runs.ts` 的 `syncLiveFromDecidedRow`(settled>0 才算)。⚠️ 计数是**上限**不是实数:分不出这次 approve 原本带没带编辑(能分出来就不用记债了),真丢的是其中带编辑的那一部分。补偿:回体在这条路上**省略** `updatedInputForwarded`(从不发 false = 成文的否定信号)。终局收口 = 给 ask 行加 `updated_input` 列(店语义级,须本模块属主立件),届时本 tag 同批销。",
-    },
     "server.e2b.orphan-skip-unknown": {
         cls: "F",
         note: "#242 E2B 孤儿回收对一只沙盒**判不了属主/活性**(metadata 缺 taskId 的病态形 / run 行状态词在 LIVE 与 TERMINAL 两表之外 / getRun 抛错)⇒ 恒不杀,本轮跳过。方向纪律:回收是清理型能力,缺席判据=不动作——误杀是杀活任务的手,漏杀只是钱;但每次跳过必须计数,否则「回收在跑却总有几只杀不掉」的病灶(店故障/新状态词未收编/别家部署共用 key)永不显形。",
@@ -144,6 +140,22 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "S-15 twin 保留条款(core 7.0.0 design/381 §片2 的 SQL 孪生):boundary 提交后的自剪 pass(core 共享选择函数 `fileHistoryBoundariesToKeep` + 既有 `reap` 级联)失败 ⇒ 本轮 boundary **已提交**、rewind 座照常,只是这一轮没剪。放行的是「GC 失败不失败用户这一轮」(core InMemory/File 参照同形 `reap(...).catch(() => {})`,但参照是无声吞,本仓走留痕三件套);最坏后果 = 该 scope 暂时超上限一个 boundary,下一次提交的 pass 按**当前全集**重算、连它一起剪(不累积欠账)。detail 带 scope / entry / 异常文案。",
     },
+    "server.approval.ambiguous-cas.expire": {
+        cls: "P-DEBT",
+        note: "S-25(设计件 2026-08-31 §3 步骤 3;DEBTS S-25 / #290):流内 ask 的**窗到期臂**打 `expireAsk` CAS 抛错或超墙钟(不知道做没做成)之后,恢复读口 6 格退避 7 次读(≈3.1s;末格睡后仍再读一次,末格不是盲窗 —— codex R1-F1)都读不出行 ⇒ 按本臂意图投影结算 = park 路由(`\"unavailable\"`;`deny` 政策下 `{allow:false,settledBy:\"timeout\"}`)并留 park 墓碑。方向 fail-closed(无 DECIDED=approve 行绝不执行工具),但行**可能**已被另一副本判成 DECIDED(approve) 而本腿没兑现 —— 人批了、工具不跑、run 再挂起要人再批一次 = 丢一次人类决议,故记债不当合法兜底。补偿:core 侧仍 pending 的 checkpoint(人再批一次就走)+ 跨副本收敛器兜底(它落地后本 tag 降 F)。**不计**的形:行读得出、只是仍 STREAM_PENDING / 行不在 —— 那是本臂的期望态(K1),零退避直接投影(codex-R2-2 / R3-1 钉;throw 类 K2 的 pending 投影前重打一把本臂幂等 CAS 换持久背书,R3-F2);编辑在飞标记在场 ⇒ 有界让路、用尽走 park 路由(标记的事不是店的债,codex R1-F2/R2-F2;负终态与带载荷 approve 不受标记压制,R2-F1/R3-F1);行读出 DECIDED ⇒ 按人的决议结算,也不计。detail 带 askId 与读次数。",
+    },
+    "server.approval.ambiguous-cas.cancel": {
+        cls: "P-DEBT",
+        note: "S-25 同族第二员:**取消臂**(task signal abort / 连接全灭同路)打 `transitionAsk(STREAM_PENDING→VOID)` CAS 抛错或超墙钟之后,恢复读口 7 次读都读不出行 ⇒ 按本臂意图投影结算 = 裸 `settle(false,\"expired\")`(D1 纯进程内语义,不留墓碑:run 已拆,迟到的 Yes 无处兑)。S-25 之前这条 catch **不读行**直接 fail-open —— 行已 DECIDED(approve) 时把人的批准翻成拒绝、回决端点只能如实 404(round6 钉曾把这一形记成「局部竞态残影」);现在只有店持续读不出才走到这里,债的语义与 expire 员同(行可能已 DECIDED 而本腿没兑现),按臂分计是为了让「哪条臂在丢决议」在遥测里读得出。",
+    },
+    "server.approval.ambiguous-cas.unreachable": {
+        cls: "P-DEBT",
+        note: "S-25 同族第三员:**emit 全灭臂**(开卡帧两族都没送到任何连接)打 `expireAsk` CAS 抛错或超墙钟之后,恢复读口 7 次读都读不出行 ⇒ 按本臂意图投影结算 = `emitFailed` ⇒ `\"unavailable\"`(park 路由;`deny` 政策下 deny),不留墓碑(卡没到任何人手上,无人持有这把 approvalId)。S-25 之前这条 catch 不读行直接强改 —— 正是 round2 finding A「durable 行已批准、活终局被 emit 全灭强改成 unavailable」的 catch 同形缺口;现在行读出 DECIDED ⇒ 按人的决议结算,只有店持续读不出才计数。",
+    },
+    "server.pg-pool.idle-client-error": {
+        cls: "F",
+        note: "S-55(test [5864] 独立复现):pg 连接池里一条连接被外部终止(pg_terminate_backend / 云端故障切换 / LB 空闲回收)或自身网络错误。**两态一 tag,detail 判别**(`state=idle` / `state=checked-out`;先例=park 墓碑行的两臂 detail 判别):①idle 态 —— node-postgres 语义(pg-pool@3.14.0 makeIdleListener):池在 emit 'error' **之前**已 `_remove` 掉该 client,坏连接自然淘汰,下次 acquire 发新连接,在飞查询零影响;修前 Pool 上无 'error' 监听 ⇒ EventEmitter 把事件转 throw ⇒ uncaughtException ⇒ 整进程 exit 1。②checked-out 态(codex R1-[high] 补,同批修)—— pg-pool 借出时摘 idle 监听(index.js:344),`pool.connect()` 显式持有的连接(事务)在 checkout 期死时 client 直接 emit 'error' 同样打死进程;守卫只观察:中毒 client 的后续查询由 pg 以 `_queryable=false` 响亮拒,归还时池淘汰;同一次 checkout 的死可能双发事件(FATAL 消息 + socket end),warn 逐枚、计数按 checkout 去重。放行的最坏后果 = 下一次 acquire 多付一次建连,故 F 类。必须留痕:「连接不断被外部杀」(故障切换风暴 / 回收策略过激 / 有人在库上清连接)与「一切正常」在服务面同形;每次事件另有逐次结构化 warn(`pg_pool_idle_client_error` / `pg_pool_checked_out_client_error`,含 code/severity),本计数让频率曲线可读。`pool.query()` 快路不在洞内(pg-pool 自带 checkout 期 once('error') 守卫)。mysql2 孪生(tidb-pool)**不同病**:PoolConnection 构造器恒挂 once('error') 库内吞并淘汰、借出期同在(坐标成文在 createTidbPool 头注),故无同族 tag。",
+    },
 };
 export function failOpenTagForDroppedFrame(frameType) {
     switch (frameType) {

package/dist/observability/metrics.d.ts

@@ -18,7 +18,7 @@ export declare class Metrics {
     setGauge(name: string, value: number, labels?: Labels): void;
     addGauge(name: string, delta: number, labels?: Labels): void;
     observe(name: string, value: number, labels?: Labels): void;
-    /** [2557] 2-j:dynamic gauge 求值抛错不再折成 0 —— 0 是该 gauge 的合法读数,折 0 让故障态与真实 0
+    /** [ref] 2-j:dynamic gauge 求值抛错不再折成 0 —— 0 是该 gauge 的合法读数,折 0 让故障态与真实 0
      *  在 wire 上逐字节不可区分(与上方 inc 静默 no-op 同族:观测面的 fail-silent 正是观测要消灭的东西)。
      *  披露方向:错帧**不发样本行**(缺席=读数未知,面板显示 no data 而非假 0)+ 计
      *  `metric_gauge_eval_errors_total{name}`(响亮、可告警)。每次求值(每次刮取/snapshot)错一次计一次;

package/dist/observability/prompt-manifest.d.ts

@@ -1,4 +1,4 @@
-/** The whitelisted projection of core's `prompt.assembled` trace event ([998]② web observability slice A:
+/** The whitelisted projection of core's `prompt.assembled` trace event ([ref]② web observability slice A:
  *  the manifest reaches the durable run event log + turns/stream). Built FIELD-BY-FIELD at record time
  *  (never a spread — the 1.72 task_progress lesson: a future core field must not ride the durable wire raw).
  *  Carries ONLY ids/digests/counts by core's manifest contract (no prompt bodies; hashes are core-salted) —
@@ -10,7 +10,7 @@ export interface PromptManifestRecord {
         chars: number;
         hash: string;
     }>;
-    /** `contentHash`(core 1.315 [1062]①):operator 声明 section 的**非盐化**对账锚(core 已对 text 校验
+    /** `contentHash`(core 1.315 [ref]①):operator 声明 section 的**非盐化**对账锚(core 已对 text 校验
      *  后透传)——盐化 `hash` 恒在旁;端到端对账链(center 发布→manifest)经本投影,必须透传不可吞。 */
     sections?: Array<{
         id: string;
@@ -31,7 +31,7 @@ export interface PromptManifestRecord {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
-    /** core 5.15.0(#181):deferred 披露策略自证三键(诊断值,零内容)。缺席=core <5.15 或无 deferred。 */
+    /** core 5.15.0([ref]):deferred 披露策略自证三键(诊断值,零内容)。缺席=core <5.15 或无 deferred。 */
     toolDisclosure?: {
         deferredTools: number;
         strategy: string;
@@ -67,7 +67,7 @@ export declare function promptManifestRecordOf(e: {
         shapeDigest: string;
         wireSchemaDigest: string;
     }>;
-    /** core 5.15.0(#181,[2872] 提货②):deferred 工具的披露策略自证——{deferredTools(数), strategy
+    /** core 5.15.0([ref],[ref] 提货②):deferred 工具的披露策略自证——{deferredTools(数), strategy
      *  ("static"|"swap"), source(四值:`spec` / `env` / `default` / `degraded_no_direct_lane`)}。
      *  诊断三键(数 + 两闭集词,零内容)。词表属主是 core(`core/trace.d.ts` 的 `source` 联合),本仓宽收
      *  ⇒ 词错不会红,所以照抄时务必对表:`degraded_no_direct_lane` = 直呼车道联锁把 `static` 请求收窄成
@@ -81,7 +81,7 @@ export declare function promptManifestRecordOf(e: {
     totalChars: number;
 }): PromptManifestRecord;
 /**
- * [998]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
+ * [ref]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
  * `prompt.assembled` tracer hook is SYNC/no-IO, so it cannot persist; it RECORDS here (registered
  * top-level runs only — the same leak fence: sub-task manifests are never registered, never leak), and
  * the durable run lifecycle DRAINS the pending records into `prompt_assembled` events. Two departures
@@ -95,7 +95,7 @@ export declare function promptManifestRecordOf(e: {
  *    delete the NEW leg's registration/pending manifest. Identity-guarded like the sibling
  *    inflight/steerable teardowns.
  */
-/** [1301]③ — `config.assembled` 的白名单投影(core 1.346 trace:catalogVersion/fields[来源标注]/
+/** [ref]③ — `config.assembled` 的白名单投影(core 1.346 trace:catalogVersion/fields[来源标注]/
  *  overrideReasons)。fields 已是 core 精选的观测形(digest-free、有界);32KiB 罩防未来膨胀。 */
 export declare function configAssembledRecordOf(e: {
     catalogVersion?: unknown;
@@ -105,7 +105,7 @@ export declare function configAssembledRecordOf(e: {
 }): Record<string, unknown> | undefined;
 export declare class PromptManifestTracker {
     private readonly byTask;
-    /** [1301]③:config.assembled 的同生命周期伴随记录(register 同门、drainConfig 同拍)。队列形
+    /** [ref]③:config.assembled 的同生命周期伴随记录(register 同门、drainConfig 同拍)。队列形
      *  (codex F2):cascade 每 rung 独立解析配置,后到覆盖会把先前已计费 rung 的生效配置抹掉——与
      *  prompt manifests 同姿势逐条保序。 */
     private readonly configByTask;
@@ -116,7 +116,7 @@ export declare class PromptManifestTracker {
     register(taskId: string): number;
     /** Queue this prepare's manifest — ONLY for a registered top-level run (else a no-op). Sync, never throws. */
     record(taskId: string, m: PromptManifestRecord): void;
-    /** [1301]③:队一条 config.assembled 投影(同 register 门;逐条保序——cascade 每 rung 各留其形)。 */
+    /** [ref]③:队一条 config.assembled 投影(同 register 门;逐条保序——cascade 每 rung 各留其形)。 */
     recordConfig(taskId: string, rec: Record<string, unknown>): void;
     /** Return-and-clear ALL pending config records in emission order; `undefined` when none. */
     drainConfig(taskId: string): Array<Record<string, unknown>> | undefined;

package/dist/observability/rate-limit.d.ts

@@ -10,7 +10,7 @@ export interface RateDecision {
     retryAfterSec: number;
     remaining: number;
 }
-/** #322 批1:限额的**值换代**入参(六实现类同一形)。语义定案(design/322 §5):窗口内计数**不清零**,
+/** [ref] 批1:限额的**值换代**入参(六实现类同一形)。语义定案([ref] §5):窗口内计数**不清零**,
  *  新限额即时用于比较 —— 调小 = 窗内立刻更严(可能当场 429,符合运营意图),调大 = 立刻放宽。 */
 export interface RateLimits {
     /** 每窗请求上限;`<= 0` = **关断哨兵**(恒放行、不记账、SQL 腿不起刷新环)。 */
@@ -21,7 +21,7 @@ export interface RateLimits {
 export interface RateGate {
     check(key: string): RateDecision;
     sweep(now?: number): void;
-    /** #322:值换代座位。**接口级**声明(不是各类自选):新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
+    /** [ref]:值换代座位。**接口级**声明(不是各类自选):新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
     setLimits(next: RateLimits): void;
 }
 export declare class RateLimiter implements RateGate {

package/dist/observability/secret-env-scrub.d.ts

@@ -1,5 +1,5 @@
 /**
- * A-033.3(#256)—— **密钥形 env 剥除的留痕面**(core D1 `scrubSecretEnv` 的可观测半场)。
+ * [ref]([ref])—— **密钥形 env 剥除的留痕面**(core D1 `scrubSecretEnv` 的可观测半场)。
  *
  * ## 它解决的问题
  * `scrubSecretEnv` 是本仓两条 shell/子进程腿的**安全默认**:模型可驱动的 shell(`inheritEnv:"scrub"`)与

package/dist/observability/tool-trace.d.ts

@@ -16,7 +16,7 @@ export declare function isKnownDenySource(v: unknown): v is PermissionDeniedSour
  */
 export declare function createPermissionDeniedMeter(metrics: Pick<Metrics, "inc">): Hooks;
 /**
- * prove-before-scale stopgap (design/50): a no-op observer hook that logs every tool call (pre + post)
+ * prove-before-scale stopgap ([ref]): a no-op observer hook that logs every tool call (pre + post)
  * to the worker log — INCLUDING resumed legs that `GET /v1/runs/:id/events` does NOT surface (the
  * streaming-resume observability gap, service[15] API request #2). Gated by `TOOL_TRACE=true`; OFF by
  * default (no prod noise).