@tansr/serve 0.4.0 → 0.6.0

package/README.md

@@ -1,12 +1,15 @@
-# tansr agent session server
+# tansr Agent 会话引擎(`@tansr/serve`)
 
 > **对外发布名 = `@tansr/serve`(用户拍板 2026-09-01)**。workspace 内恒以
 > `@tansr/server` 引用;发布 tarball 由 `pnpm release:pack-serve` 盖发布名。
 > **license = MIT**(同批拍板;正式协议考察待全部开发完成后进行)。
 
-tansr **Agent 会话服务**的 `/v2` 协议引擎 + **内置真平台装配**(A 案,用户
-拍板 2026-09-01),以 npm 包形态嵌进**你自己的 Node 服务**。wire 契约权威 =
-doc/98(Agent 会话服务 v2 契约冻结件)。
+**定名(doc/118 §八 G1,2026-09-03 用户授权代拍)**:本包是 tansr **Agent 会话引擎**
+——多租 Agent 会话的协议引擎(`/v2` REST + SSE)+ **内置真平台装配**(A 案,用户
+拍板 2026-09-01),以 npm 包形态嵌进**你自己的 Node 服务**。**本包不是网关**:
+「网关」一词在 tansr 体系内只指 tansr-api,鉴权策略/限流/配额/计费归开发者的登录态
+体系与平台侧;引擎自带的准入帽、`rateLimit` 缝与上游治理层是**自保护面**,不是替你
+做网关。wire 契约权威 = doc/98(Agent 会话服务 v2 契约冻结件)。
 
 引擎负责传输与协议机器:11 个 `/v2` 端点路由、SSE 编帧与逐会话事件环形缓冲、
 `Last-Event-ID` 重放、三类桥回执受理(工具/权限/提问)、多会话治理(保留窗/
@@ -70,9 +73,12 @@ const server = await startServer({
 });
 ```
 
-平台内置形当前工具面为最小集(TodoWrite/AskUser + 逐会话远程工具三桥);
-`profile`/`budget` 请求位暂不支持(带上会 400 明告,候后续版本)。一体式
-可跑示例见仓内 `examples/serve-demo/agent-real.ts`。
+平台内置形工具面按应用 bundle 有效能力档**按位装配**(doc/112:TodoWrite /
+AskUser / WebSearch / ImageGen / VideoGen 逐位随控制台「能力面」开关;逐会话远程
+工具三桥受 `customTools` 位——位关而申报 `clientTools` 即 400 明告);应用平台类型
+非「移动应用」时经 `onPlatformWarning` 与 `server.platform.warning` 帧提示
+`app_platform_mismatch`(不拒)。`profile` 请求位不支持(带上会 400 明告)。
+一体式可跑示例见仓内 `examples/serve-demo/agent-real.ts`。
 
 ## 三层鉴权定盘(架构拍板 2026-08-31)
 
@@ -104,8 +110,11 @@ const v2: AgentSessionsOptions = {
 ```
 
 - **载荷**(`TurnEndNotifyPayload` 冻结形,恒不携消息内容恒不携凭据):
-  `{ sessionId, endUserId, turnId?, status: 'completed'|'aborted', lastSeq, ts }`
+  `{ sessionId, endUserId, turnId?, status: 'completed'|'aborted', reason?, lastSeq, ts }`
   ——`lastSeq` 供客户端持水位比对判断是否需要重放追赶,`ts` 供弃过期/防重放;
+  `reason?`(contract-v0.21 / RFC-SC-1)= 终局帧 `TerminalReason` 原值,单帧区分
+  `client_gone`(订阅者离场被策略止损)/ `internal_error`(内核故障)/ 用户中断
+  `aborted_*` 等,接收方按「已知值专项 + 未知值兜底」消费;
 - **签名**:`secret` 在场时携 `x-tansr-signature: sha256=<hex>`
   (`TURN_END_NOTIFY_SIGNATURE_HEADER`),对原始请求体全文 HMAC-SHA256——
   接收端先验签再消费;
@@ -119,7 +128,9 @@ const v2: AgentSessionsOptions = {
 ## 主要出口
 
 - `startServer(options)` / `StartServerOptions`(`v2?: AgentSessionsOptions`;
-  v2 缺席 = `/v2` 面零暴露);
+  v2 缺席 = `/v2` 面零暴露;`v1?: V1SessionsOptions` = `/v1` 终结记录两级逐出
+  `governance.{retentionMs, maxRetainedSessions, sweepIntervalMs}`,**缺席 = 不逐出**
+  ——库形态终结会话永驻可重放,长驻宿主建议 30 min / 10 000,CLI `tansr serve` 即此缺省);
 - `AgentSessionsOptions`:`authenticate`(唯一鉴权缝)、`createSession`
   (`AgentSessionFactory`)、`store`(`AgentStoreReader`)、`governance`、
   `mediaMaxBodyBytes`、`onTurnEndNotify`;
@@ -132,6 +143,9 @@ const v2: AgentSessionsOptions = {
 - 契约持份:`V2_LIMITS` / `V2_ERROR_CODE` / `CONTROL_FRAME` /
   `AGENT_SESSION_CONTRACT_VERSION` / 请求体 zod schema 族 / 控制帧载荷类型;
 - SSE 机器:`encodeSseFrame` / `encodeAgentStreamFrame` / `EventRingBuffer`;
+- 事件日志接口缝(SC-35):`SessionEventLog` / `SessionEventLogRead` /
+  `SessionEventLogFactory` / `MemorySessionEventLog`(缺省实现),经
+  `AgentSessionsOptions.eventLog` 注入(见 Operations「扩展档位」);
 - 轮末通知:`TurnEndNotifier` / `TURN_END_NOTIFY_SIGNATURE_HEADER`;
 - i18n 便携面:`registerBuiltinLocales` / `setLocale` / `negotiateLocale`。
 
@@ -147,3 +161,360 @@ const v2: AgentSessionsOptions = {
   devDeps,打包后守卫复检 manifest/依赖面/文件表/license(MIT + LICENSE 件
   版权行 Tansr)+ **⑥真装配出口断言**(动态 import 验三出口可调 + wire/d.ts
   锚);发布动作恒候用户口令。
+
+## 宿主信号接线(Graceful shutdown)
+
+`@tansr/serve` 以 npm 包嵌进你的 Node 进程,**进程信号归宿主**:引擎恒不在
+`process` 上注册信号监听器(嵌入库不替宿主决定进程何时退出),也就不会替你
+处理 SIGTERM/SIGINT——**宿主必须自己接线**。不接线的后果:编排器常规停机
+(`docker stop` / systemd / Kubernetes 缺省都发 SIGTERM)= 进程被硬杀,全部
+SSE 连接 reset、在飞轮丢、无收口日志。
+
+`startServer` 返回的 `server.drain({ timeoutMs })`(幂等;缺省 30 s)按序做四件事:
+① **拒新**——readiness 翻红(`server.readiness()` 供你的 `/readyz` 读)、新建/resume
+一律 `503 draining` 携 `Retry-After`、全部在场 SSE 下发一帧 `retry:` 长间隔
+(`sse.drainRetryMs`,缺省 10 s,客户端换台后再连);② **等在飞轮**——`/v2` 运行中的
+轮至多等 `timeoutMs` 到终态,到点剩余 `interrupt()`(轮末 store 提交照走,resume 可
+续);③ **flush 落盘**——等全部 fire-and-forget 的 store 提交/建行 settle
+(`createAgentSessionFactory` 的 `flush`);④ **停机**——终结会话、停监听、掐空闲连接、
+有界等待在飞非 SSE 请求答完(≤ 5 s)再掐残余连接。回执
+`{ completedTurns, abortedTurns, flushedCommits, durationMs }` 可入日志。
+`server.close()` 保持**硬收口**语义(立即中止在飞轮、不等落盘;drain 进行中调用则等
+drain 完成);`/v1` 会话无粗态读面,drain 不等其在飞轮。
+
+最小接线——两枚信号共用一个 handler,幂等位防重复进入:
+
+```ts
+let stopping = false;
+const shutdown = (signal: NodeJS.Signals): void => {
+  if (stopping) return;
+  stopping = true;
+  console.error(`[my-service] ${signal} received, draining...`);
+  server
+    .drain({ timeoutMs: 30_000 })
+    .then((report) => {
+      console.error(`[my-service] drained`, report);
+      process.exit(0);
+    })
+    .catch((error: unknown) => {
+      console.error('[my-service] shutdown failed', error);
+      process.exit(1);
+    });
+};
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+```
+
+要点:
+
+- **宽限期 ≥ drain 超时 + 收尾余量**:`drain({ timeoutMs: 30_000 })` 最坏等 30 s 在飞轮
+  + ≤ 5 s 被中止轮收口 + ≤ 5 s 连接收口;容器 `stop_grace_period`(compose 缺省
+  10 s)、Kubernetes `terminationGracePeriodSeconds`、systemd `TimeoutStopSec` 部署件统一
+  **45 s**(doc/118 §八 G10;`deploy/serve-v2/` 与 `deploy/serve/` 已写),或把 `timeoutMs`
+  调小并同步调小宽限。宽限到点编排器 SIGKILL,等价硬杀;
+- **信号要能到达 node**:容器 `CMD`/`ENTRYPOINT` 用 exec 形(JSON 数组)或
+  `--init`(tini 作 PID 1 转发),不要 `sh -c "node …"`(sh 当 PID 1 不转发);
+- **退出码由你定**:引擎恒不调 `process.exit`;示例里 `drain()` 成功 `exit(0)`、
+  失败 `exit(1)`,与你的进程监督器约定一致即可;`tansr serve`(CLI 形态)同走
+  drain,超时经 `TANSR_SERVE_DRAIN_TIMEOUT_MS` 可配(缺省 30 s);
+- **Windows 注记**:`process.on('SIGTERM')` 可注册但系统不会发出;本机开发以
+  Ctrl+C(SIGINT)收束,Linux/容器上两枚都会到;
+- **与 `onTurnEndNotify` 的关系**:优雅关闭期出站通知恒不发(见上文投递纪律),
+  客户端靠回连 `Last-Event-ID` / history / resume 追赶。
+
+完整可跑示例见仓内 `examples/serve-demo/server.ts`(接线封装在 `examples/serve-demo/runtime.ts`)。
+
+## Operations(运维面:指标 / 健康 / 结构化日志 / request-id / 旋钮 / 部署)
+
+以下全部属**运维面**,不属 doc/98 wire 契约(端侧不感知;三观测端点是否入契约候
+G4-g 拍板)。数字口径与 SLO 词表见 `doc/report/serve并发审计-D路-可观测性与横向扩展.md` §七-1。
+
+### 运维旋钮:`TANSR_SERVE_*` 环境变量 → 库选项(SC-32)
+
+引擎的全部运维位都是 **`startServer` / 工厂 / governor 的库选项**;进程形态(容器、CLI
+`tansr serve`)需要一个配置入口,本包给出**单一事实源** `resolveServeRuntimeOptions(env)`
+(纯函数,不读 `process.env`、不写日志;表 `SERVE_RUNTIME_ENV` 与名单 `SERVE_RUNTIME_ENV_NAMES`
+同出口)。宿主拿到结构化结果后各自展开:
+
+```ts
+import { createUpstreamGovernor, resolveServeRuntimeOptions, startServer } from '@tansr/serve';
+
+const runtime = resolveServeRuntimeOptions(process.env);
+for (const w of runtime.warnings) logger.error(`ignoring ${w.name}="${w.value}": expected ${w.expected}`); // 非法值:忽略,恒不拒启
+const governor = createUpstreamGovernor(runtime.upstreamGovernor);          // TANSR_SERVE_UPSTREAM_MAX_INFLIGHT → bulkhead
+const build = createAgentSessionFactory({ cwd, logger, platform: { apiBaseUrl, appId, appKey, governor, ...runtime.session } }); // 分层超时 / 每轮墙钟
+const server = await startServer({
+  host, port, token, createSession, logger: runtime.logFormat === 'json' ? jsonLogger : textLogger, // TANSR_SERVE_LOG_FORMAT
+  governor,
+  ...runtime.server,                                                        // admission / http / sse / observability / eventBufferMaxBytes
+  v2: { authenticate, createSession: build.factory, store: build.storeReader,
+        ...runtime.v2 },                                                    // /v2 治理五键 + 分片码 sessionIdShard(TANSR_SERVE_SESSION_SHARD)
+});
+```
+
+纪律(doc/118 §八 G5/G9 代拍):**任一变量缺席/空串即不落键 → 未设 = 库缺省,行为零漂移**;
+非法值(非整数、越界、枚举外)进 `warnings` 由宿主一行告警后忽略,恒不拒启;`applied` 列出生效
+的变量名,`appliedRuntimeEnvByGroup(runtime, 'governance', 'v2')` 可判某些组是否在场(CLI `tansr serve`
+是 /v1 面,治理五键与分片码在场即提示无效)。全表 23 键(env → 库选项 → 缺省 → 建议值)见
+`deploy/serve-v2/README.md` §三 与 `deploy/serve-v2/.env.example`;分组:`admission`(4)/ `http`(1)/
+`observability`(1)/ `ring`(1)/ `governance`(5)/ `v2`(1,分片码)/ `upstream`(1)/ `session`(4)/
+`sse`(3)/ `log`(1)。不在表内(语义归各自入口):`TANSR_SERVE_TOKEN`(/v1 Bearer)、
+`TANSR_SERVE_DRAIN_TIMEOUT_MS`(drain 超时,缺省 30 s)、`TANSR_SERVE_V1_RETENTION_MS` /
+`TANSR_SERVE_V1_MAX_RETAINED`(SC-18)、`TANSR_SERVE_MCP_CONNECTIONS`(SC-31;缺省 1、上限 16。
+**SC-44 起只是进程级兜底层**:`mcpServers.<name>.pool.connections` 逐台键 > 程序面 `pool` 选项 > 本 env
+> 缺省 1,合并在 kernel `governance.ts` 单点;写了逐台键的服务器不受本 env 影响,有会话态的服务器
+恒保持 1——见 doc/60 §2.5)。
+
+### 部署参考件与优雅关闭时序(SC-32 / SC-32c;doc/118 §八 G1/G2/G10)
+
+`deploy/serve-v2/` 是 /v2 npm 嵌入形态的**参考宿主**部署件(`examples/serve-demo` 两入口打成单
+文件镜像;compose N 副本 + nginx 分片路由/SSE 模板;K8s StatefulSet + 内层 nginx + ingress-nginx 注解 +
+NetworkPolicy);`deploy/serve/` 是 CLI `tansr serve` /v1「一容器一智能体实例」模板。要点:
+
+- **本包不是网关**:TLS 终结 / HTTP2 / IP 级限流 / WAF 归你的边缘(G10 反代前置);nginx 模板只做
+  SSE 直通(`proxy_buffering off`、读超时 ≥ 心跳 15 s × 4、对 `text/event-stream` 不压缩、
+  `proxy_next_upstream off`)与分片前缀路由,`client_max_body_size 20m` 与引擎体帽对齐。
+- **多副本 = 分片前缀路由 + 副本私有存储根**(G2 先 (a) 档;SC-32b/SC-32c):会话运行态在副本内存 +
+  私有 store,`/v2/sessions/<id>/…` 必须回到创建副本。每副本持分片码 `v2.sessionIdShard`(0–255,
+  = 副本序号;env `TANSR_SERVE_SESSION_SHARD`),引擎给**全新会话**生成的 sessionId 前两位十六进制
+  恒 = 分片码(其余 30 位仍是 UUID v4 随机位,形制仍是 UUID;resume/attach 沿用原 id),反代读 id
+  前两位做静态 `map` 路由回创建副本;创建请求(路径无 id)任意副本轮询。**客户端零改动**(sessionId
+  对客户端恒不透明,doc/98 §五-5.5),无 cookie、无端侧头、不按 Authorization 哈希(令牌刷新不
+  漂移)。**不能按路径 sessionId 做一致性哈希**——创建请求没有 sessionId,会话生在随机副本,后续按
+  sid 哈希落别处 → 404 → L3 resume 读不到 → 分叉;前缀路由把「id 决定副本」反过来变成「副本决定 id」。
+  副本序号即分片码:扩缩容不改既有映射;缩容副本上的会话随之丢失(与任何本地态服务同律,先 drain)。
+  自定义 `AgentSessionFactory` 须采用 `init.sessionId`,忽略即失去粘性并收 `session.id_hint_ignored`
+  告警。副本故障 = 其上会话不可迁移(客户端按 404 → 新建)。**恒不共享存储目录**(NFS/EFS/同一卷挂
+  两副本):kernel 会话锁按本机 PID 判活,容器 PID 命名空间下跨副本必然误判——`SESSION_LOCKED` 30 min
+  或并发写同一 journal → `500 store_corrupted`;这是不安全配置而非「慢一点」。
+- **优雅关闭时序**(宽限 45 s):t0 SIGTERM(+ K8s 摘 Endpoints)→ 拒新(`/readyz` 503、新建/resume
+  `503 draining` + `Retry-After`、SSE 下发长 `retry:`)→ 等在飞轮 ≤ `TANSR_SERVE_DRAIN_TIMEOUT_MS`
+  (缺省 30 s,到点 `interrupt()`,轮末 store 提交照走)→ flush 落盘 → 停监听 ≤ 5 s + 连接收口 ≤ 5 s →
+  宿主 `governor.close()` → exit 0;t0+45 s 未退出 → SIGKILL。宽限恒 ≥ drain 超时 + 15 s。
+- **观测端点暴露**:容器绑 `0.0.0.0` 时须 `TANSR_SERVE_EXPOSE_OBSERVABILITY=1`(参考镜像已设),探针
+  与抓取器走内网直连副本;反代恒不把 `/metrics` `/healthz` `/readyz` 转到公网。
+- **容量估算**(本机现状档不外推;doc/118 §一-1.1):单进程 ≈2500 活跃 SSE 连接时 ELD p99 ≈190 ms、
+  5000 连接 ≈250 ms;≈35 KiB 堆/会话(全装配链);企业档参考帽 `maxActiveSessions 5000` /
+  `maxSseConnections 10000` / `maxInflightBodyBytes 256 MiB` / ELD p99 200 ms(G5,仅文档)。
+- **`fetchImpl` 须尊重 `init.signal`**:宿主自带 fetch(代理/埋点)包在 governor 外层或内层都可,但取消
+  传播链在此不得断——drain 到点的 `interrupt()`、每轮墙钟、分层超时都靠 AbortSignal 抵达上游。
+
+### 扩展档位(横向扩展的三级;doc/118 §八 G2 / §11.2)
+
+| 档 | 形态 | 状态 | 重放窗(`Last-Event-ID`)在哪 |
+|---|---|---|---|
+| (a) | 单进程 + 分片粘性:`v2.sessionIdShard` + 反代前缀路由,副本私有存储根,恒不共享目录 | **已落**(SC-32b/c;上节) | 创建副本内存(`MemorySessionEventLog` = 环形缓冲,条数 1024 + 可选字节帽) |
+| (b) | 事件日志外置:`AgentSessionsOptions.eventLog` 注入 `SessionEventLog` 实现(Redis Streams / NATS JetStream 等) | **接口缝已落**(SC-35);实现**另包候需求**,包名属命名面留用户 | 外部日志;任一副本可按 sessionId 重放,会话运行态(驱动/桥/在飞轮)仍在创建副本——分片路由仍需要 |
+| (c) | 会话态外置:驱动/桥/历史随会话迁移到任一副本 | **未立项** | 外部 |
+
+(b) 档的缝:`eventLog: (ctx: { sessionId, endUserId }) => SessionEventLog`,每次纳管一枚;引擎的泵写入
+(`append(event, frameBytes?)` 返回事件自带的 seq)、`Last-Event-ID` 重放与 gap 帧判定(`readAfter(afterSeq)`
+一趟返回 `{ events, oldestRetainedSeq?, dropped, gap }`)、`ringStats` 汇总(`stats()`)、记录离开内存
+(`close()`,保留窗到点 / 数量帽 / resume 让位 / `closeAll` 各恰一次)只经此接口。**缺席 = 内存实现,行为
+逐字节同今**(`eventBufferSize` / `eventBufferMaxBytes` 仍施于缺省实现;传了工厂即由实现定容量与逐出)。
+实现纪律:全部方法同步(泵与订阅的同步原子块依赖此契约,异步后端须在接口之下自做写缓冲/本地镜像);seq
+由句柄分配、随事件携带,日志恒不改写(外部存储的自生成 id 只能作游标);引擎恒不引 zod 之外第三方,任何
+外置实现都在别的包里。
+
+### 分层存储(冷层):会话历史落到 S3 / OSS / KV / 关系库(doc/119 IO-21 / doc/120;IO-32 集成后可用)
+
+会话历史的耐久性地板恒是**本地热层**(轮末 journal 追加,fsync + rename ≈ 13 ms/轮);热层不可能配无限硬盘,
+所以既有 store 工厂加了**可选**冷层:热层达到封段阈值(缺省 16 MiB / 5000 记录)后把这一截封成**不可变的段对象**
+(JSONL + gzip,首尾哈希链)上传到你挂的存储,再以 CAS 重写一份**清单**(唯一提交点);已提交段可被热盘 LRU 逐出,
+读侧按需回源。**不挂冷层 = 今日行为,字节等价**;客户端零感知(`/v2` wire 零改动)。
+
+**五行接入**(`createAgentSessionFactory({ store })` 不改;doc/91 冻结接口不改):
+
+```ts
+import { createServeAgentSessionStore, createAgentSessionFactory } from '@tansr/serve';
+import { createS3BlobStore } from './store-s3.js';           // 你的适配器(参考实现 examples/store-s3,零依赖 fetch + SigV4)
+
+const store = createServeAgentSessionStore({
+  dir: '/var/lib/tansr/hot',                                   // 热层:本地盘,恒不共享
+  cold: createS3BlobStore({ bucket, region, credentials }),   // 一级 SegmentBlobStore(或二级 SessionHistoryStore)
+  policy: { tenant: 'acme', hotRetention: { maxBytes: 20 * 2 ** 30 } },
+  logger,                                                      // 冷层事件 → 结构化日志 store.*
+});
+const build = createAgentSessionFactory({ cwd, store, platform: { ... } });
+```
+
+**两级选择**:一级 `SegmentBlobStore`(5 个字节方法 `put / get / head / list / delete` + 一次能力自述
+`capabilities`;S3 / OSS / COS / MinIO / R2 / GCS / Azure / GridFS / 文件系统皆此级,引擎内置分段、编码、清单 CAS、
+热盘 LRU、重试、指标)——**推荐**;二级 `SessionHistoryStore`(`store / load / listSessions / remove`,自管布局;
+KV / 关系库更贴合)。适配器唯一要遵守的错误约定是 `StoreError.kind` 四类(`transient` / `permanent` /
+`not_found` / `precondition_failed`;其他异常一律按 transient)。一级冷层 `conditionalPut:false` 或 `list:'none'`
+时**必须**再挂 `index: SessionIndexStore`(多副本共享会话元 / CAS 落点),否则构造期 fail-fast(不静默降级为不安全提交)。
+随包实现:`createMemoryBlobStore()`(测试替身)、`createFsBlobStore({ dir })`(目录模拟对象存储;**只可作冷层**)。
+一致性测试套 `runStorageConformance(store)` 认证你的适配器(fs / memory / S3 同一套)。
+
+**旋钮(`policy`)**:
+
+| 键 | 缺省 | 语义 |
+|---|---|---|
+| `codec` | `'jsonl+gzip'` | 段编码;`'jsonl+zstd'` 仅 Node ≥ 22.15 可用 |
+| `hotRetention.maxBytes` | 不设 | 热盘上本地段文件占用帽:**已提交**段先逐出;仍越帽 → `readiness()` 红 + `store.hot_full` 事件;**未上传段恒不删** |
+| `hotRetention.keepRecentSegments` | 引擎缺省 | 逐出时保留的尾段数(压缩后 resume 常只需摘要 + 尾段) |
+| `upload.mode` / `concurrency` | `'async'` / 4 | 热层先 ack 再异步上传;并发受约束(A12) |
+| `upload.retryBudget` | 8 次 / 退避封顶 60 s | transient 重试预算;耗尽 → `store.commit_failed{gaveUp:true}` + `onStoreError` |
+| `restore.prefetchTailSegments` | 1 | 热层全失重建后预取的尾段数 |
+| `transform` | 无 | `encode / decode` 字节流挂点:加密 / 脱敏归你(引擎不做密码学) |
+| `keyMapper` | 恒等 | 规范键 `<tenant>/<endUserKey>/<sessionId>/<volumeId>/…` → 你的键(不得破坏唯一性) |
+| `tenant` | `'default'` | 规范键首段(多租户隔离) |
+
+`metrics` 缺省 kernel `defaultMetrics`(与 `/metrics` 同源);`index` 见上;`onStoreEvent(event)` 原样订阅冷层事件;
+`onStoreError(sessionId, error)` 只在**放弃**时回调(热层已 ack,恒不抛给调用方)。
+
+**失败语义**:上传 / 清单提交失败**恒不回滚热层**(轮末已 ack 的历史耐久不变)——按预算重试,超预算记
+`store.commit_failed` + 积压指标,段留在热盘、下次绑定时对账补传;`precondition_failed`(清单被另一副本接管)本写者
+放弃不重试(A2 / A13)。读侧:回源段篡改 / 截断 / 跳段(`permanent`)→ `500 store_corrupted`,恒不静默续接;冷层
+暂不可达(`transient`)原样上抛 `StoreError`(不冒充损坏)。**热层全失(节点重建,A10)**:同一冷层重开 store,
+`GET /v2/sessions` 列表见会话、resume 经冷清单 → 段 → 重灌成功(只有**已封存**的段可恢复;未越阈值的活段随热层丢失——
+需要更细粒度的耐久点请调小 `segmentation` 阈值)。`delete` 先删冷层再删热层。
+
+**两条告警线**(`/metrics`,`tansr_kernel_store_*` 族:`ops_total{op,result}` / `bytes_total{op}` / `latency_ms{op}` /
+`failures_total{kind}` / `backlog_bytes` / `hot_bytes`):
+① `tansr_kernel_store_backlog_bytes` **持续增长** = 冷层不可达或写失败(热层仍在服务,但保留窗只剩本地盘);
+② `tansr_kernel_store_hot_bytes` **逼近 `hotRetention.maxBytes`** = 即将触顶——触顶后 `/readyz` 503(理由
+`store_hot_full`,`v2.store.readiness` 经工厂 storeReader 转发即自动接线;或把 `store.readiness` 直接挂
+`observability.readinessProbes`),LB 摘流、新建改落别的副本。结构化日志:`store.segment_sealed` /
+`store.segment_committed` / `store.commit_failed{kind,attempts,gaveUp}` / `store.hot_full` / `store.hot_recovered` /
+`store.evicted` / `store.orphan_gc`(字段恒不含消息内容)。
+
+**部署建议**:热层恒**本地盘、恒不共享**(共享盘是不安全配置,见上节);冷层用**生命周期规则**承接保留窗
+(`<tenant>/<endUserKey>/<sessionId>/<volumeId>/` 前缀按 `expiresAt` / 标签过期;压缩换卷 = 新 `volumeId`,旧卷独立
+过期不影响新卷);冷层里的段是**明文 JSONL(压缩)**——加密、密钥管理、驻留地、访问控制归你(`transform` 挂点),
+`endUserKey` 是哈希不是身份,不要把 endUserId 明文放进键或标签;多副本下配 `index`(会话元共享、`list` 便宜),
+`policy.tenant` 按租户隔离前缀。优雅关闭:drain 第三阶段在工厂 flush 之后再 `await store.flush({ timeoutMs })`
+等冷层队列排空(返回 `false` = 超时仍有积压,热层已耐久,重启后对账补传)。
+
+### 三观测端点(免 Bearer;缺省只在回环监听时暴露)
+
+| 端点 | 语义 | 响应 |
+|---|---|---|
+| `GET /healthz` | liveness:进程活着即 200(关闭期亦 200,摘流看 readyz) | `{"status":"ok"}` |
+| `GET /readyz` | readiness:`!closing ∧ 全部就绪探针 ready` | 200 `{"ready":true,"reasons":[]}` / 503 `{"ready":false,"reasons":["closing",…]}` |
+| `GET /metrics` | OpenMetrics 1.0 文本(`application/openmetrics-text; version=1.0.0`) | 内核 + serve 指标一份 exposition,末行 `# EOF` |
+
+暴露纪律:三端点**免 Bearer**,所以暴露面必须显式——`host` 为回环(127.x / localhost /
+::1)时缺省暴露;绑 `0.0.0.0` / 公网地址时缺省**不暴露**,须 `observability: { expose: true }`
+(或分别 `exposeHealth` / `exposeMetrics`)。未暴露时这三条路径**落回既有流程**,与任意
+未知路径响应完全一致(无 Bearer 401 / 有 Bearer 404),不泄漏存在性。容器/K8s 部署把
+它们只发布给探针与抓取器所在网络(反代前置时不要把 `/metrics` 转到公网)。
+
+```ts
+const server = await startServer({
+  // ...
+  observability: {
+    expose: true, // 绑 0.0.0.0 时显式放开
+    readinessProbes: [() => (storeWritable ? true : { ready: false, reason: 'store_unwritable' })],
+    requestLogSampleRate: 0.1, // 高并发下调请求日志采样;错误级事件恒不采样
+  },
+});
+server.stats(); // 结构化快照:sessions{active,byFace,pending?,retainedEnded?} / sse / http / eventLoopDelayMs / memory / notifier? / readiness
+```
+
+### 指标(首批;名恒 `tansr_` 前缀,`process_resident_memory_bytes` 为唯一标准名例外)
+
+内核层(五形态共享,TUI/Headless/serve/acp/SDK 同一份进程级读数;kernel 出口
+`defaultMetrics` / `createMetricsRegistry` / `renderOpenMetrics` 经本包再出口):
+`tansr_kernel_model_calls_total{result}`、`tansr_kernel_model_call_duration_ms`、
+`tansr_kernel_tool_executions_total{result}`、`tansr_kernel_tool_duration_ms`、
+`tansr_kernel_turns_total{reason}`、`tansr_kernel_internal_errors_total`、
+`tansr_kernel_compactions_total{mechanism}`、`tansr_kernel_retries_total{class}`。
+
+serve 层:`tansr_serve_http_requests_total{method,route,status}`(route 恒模板化,如
+`/v2/sessions/:id/events`;`status="0"` = 响应头未发出即断开)、
+`tansr_serve_http_request_duration_ms{route}`、`tansr_serve_rejections_total{code}`
+(401/403/404/405/409/410/413/422/429/4xx/5xx)、`tansr_serve_sessions_active{face=v1|v2}`、
+`tansr_serve_sessions_pending`、`tansr_serve_sessions_retained_ended`、
+`tansr_serve_sse_connections_active`、`tansr_serve_sse_frames_written_total`、
+`tansr_serve_replay_gap_total`、`tansr_serve_ring_evictions_total`、
+`tansr_serve_event_loop_delay_ms{stat=p50|p99|max}`(两次采集之间的窗口)、
+`process_resident_memory_bytes`、`tansr_serve_webhook_deliveries_total{result}`、
+`tansr_serve_store_commit_errors_total` / `tansr_serve_store_create_errors_total`、
+`tansr_serve_token_mint_failures_total`。
+
+纪律:指标标签**恒不含** sessionId / endUserId / 令牌 / 消息内容(高基数与凭据禁令);
+未知路径一律 `route="other"`。同进程起多台 `startServer` 且共享缺省注册表时,gauge 族由最后
+采集者覆写、counter 族累加——需按实例隔离读数时各传 `observability.metrics: createMetricsRegistry()`。
+
+### 结构化日志与 request-id
+
+`ServeLogger` 新增可选 `log(level, event, fields)`(旧 `info/error` 保留)。事件名恒英文
+机器码(`LOG_EVENT` 词表:`request.completed` / `request.unhandled` / `sse.opened` /
+`sse.closed{reason}` / `store.commit_failed` / `store.create_failed` / `notify.delivery_failed` /
+`server.listening` / `server.closed` …;分层存储冷层在场时另有 `store.segment_sealed` /
+`store.segment_committed` / `store.hot_full` / `store.hot_recovered` / `store.evicted` / `store.orphan_gc`,
+见上节),字段恒不含令牌与消息内容(`sessionId` 可在场,
+`endUserId` 仅 /v2 已鉴权时由路由层回填)。只有旧形 `info/error` 的 logger 会收到回落:
+带人读文案的事件(listening/closed/兜底错误)仍是既有 i18n 文案行,其余事件为**一行 JSON**
+`{"level","event",...fields}`。
+
+request-id:每个请求采纳合法入站 `x-request-id`(`^[A-Za-z0-9._-]{1,128}$`),否则取
+W3C `traceparent` 的 trace-id,再否则自铸 UUID;恒回响应头 `x-request-id`(含 401/404),
+并作 `request.completed{requestId, method, route, status, durationMs}` 与
+`request.unhandled` 的关联键。SSE 长连接在连接关闭时发一次 `request.completed`(`sse:true`)。
+`createAgentSessionFactory` 的 `onStoreError` 缺省不再静默:一行结构化 JSON 到 stderr 并计数。
+
+### 容量基线与门禁
+
+`bench/serve/`(A/B/C 路审计脚本)已门禁化:`pnpm bench:serve:gate` 按 `bench/serve/thresholds.json`
+现状档断言(本机数字为参考、不外推;目标档随 G12 回填),详见 `bench/serve/README.md`。
+
+**容量模型**:「挂着的会话数」≠「同时活跃数」——订阅者全部离场 `orphanGraceMs`(60 s)后中止当前轮、再
+`idleAfterGoneMs`(5 min)后落盘退出内存,resume 复活;内存与 CPU 只随同时活跃的会话增长。单进程天花板是
+单事件循环 CPU(几千会话同时流式),准入帽(`admission`)让它有界拒绝而非拖垮,`v2.sessionIdShard` 分片前缀
+路由随时加副本。**部署前置**:每条 SSE 占 1 个文件句柄,Linux 缺省 `nofile 1024` 会把并发订阅者卡在一千出头
+并报 `EMFILE`——按目标并发 ≥ 2× 抬(`deploy/serve-v2` 模板已置 65536,nginx 侧 `worker_connections` 同律)。
+
+### 上游治理(平台内置形:铸令牌闸 / bundle 缓存 / 503 语义 / governor 注入)
+
+平台内置形(`createAgentSessionFactory({ platform })`)的上游链是
+`appid/appkey → POST /v1/app-tokens(per-endUser 令牌)→ GET /t1/config + POST /t1/heartbeat
+(bundle/features)→ POST /t1/exchange(模型)`。Wave 2(SC-22/23/24/30)起这条链有了治理位;
+缺省值全部为建议值(候 G3 拍板),`upstreamStats()` 可读:
+
+```ts
+const build = createAgentSessionFactory({
+  cwd,
+  logger,                          // 缺省提示帧承接经 platform.warning 结构化事件(缺席回落 console.warn)
+  platform: {
+    apiBaseUrl, appId, appKey,
+    tokenMinter: {                 // 铸令牌治理(SC-23/SC-30;全部可选)
+      maxConcurrentMints: 32,      // 全局并发闸:同时出网的 /v1/app-tokens 数(重启惊群从 N 降到闸值)
+      maxQueuedMints: 1024,        // 闸等待队列;满额即刻 503 overloaded(不出网)
+      mintQueueTimeoutMs: 10_000,  // 排队超时 → 503 overloaded
+      expiryJitterRatio: 0.15,     // 令牌 expiresAt 只提前不推后的抖动比(打散 TTL−300 s 的对齐刷新)
+      negativeCacheInitialMs: 5_000, negativeCacheMaxMs: 60_000, // 失败负缓存 5 s 起指数 ×2 至 60 s
+      maxCachedTokens: 100_000,    // 令牌缓存 LRU 帽(过期项读到即删)
+    },
+    bundleCacheTtlMs: 60_000,      // bundle/features 缓存 TTL 上界(SC-24;0 = 每会话拉取)。也可传 bundleCache 实例跨工厂共享
+    governor,                      // SC-22:providers createUpstreamGovernor 产物;三处出站同一枚(见下)
+  },
+});
+build.upstreamStats?.();           // { tokenMinter: { inflight, queued, mints, hits, negativeHits, staleServed, failures{kind}, cached, evicted }, bundleCache?: { hits, misses, revalidations, notModified, inflightDedup, … } }
+```
+
+- **铸令牌闸 / 抖动 / 负缓存**:500 endUser 同时首连时 `/v1/app-tokens` 在飞峰值 = 闸值(此前 500);
+  同批铸出的令牌不再同刻进入刷新窗;某 endUser 铸造失败后窗内不再出网(直接回同一错),
+  刷新失败但旧令牌仍在时效内直接沿用旧令牌;`warm(endUserIds)` 可在启动期预热。
+- **bundle 缓存**:键 `(apiBaseUrl, appId)`,TTL = min(平台 `max-age`, `bundleCacheTtlMs`);过期后
+  `If-None-Match` 条件重拉(304 只续期);features(heartbeat)按 endUser 每 TTL 一次而非每会话。
+  建会话上游往返:冷 endUser 3 → 1(仅铸令牌;首次 +1 config),热 endUser 2 → 0。
+  **一致性 SLA**:控制台改模型授权/别名后在网关生效的延迟上界 = `bundleCacheTtlMs`(缺省 60 s);
+  要更快生效就调小(平台 `max-age` 仍是下界之一),要即时一致传 `0`。
+- **503 `upstream_unavailable`**(候 doc/98 §七 增笔 G4-a):平台铸令牌撞 429 / 5xx / 网络错时建会话
+  回 `503 upstream_unavailable` 并携 `Retry-After`(取平台 `Retry-After`,缺席按 `admission.retryAfterMs`
+  5 s);客户端按 5xx 语义退避重试即可。与 `503 overloaded`(本机闸忙 / 准入帽)分开:一个是「上游坏,
+  加压无益」,一个是「本机忙,稍后再来」。4xx(凭据/入参被拒)维持 `400 create_failed`(重试无益)。
+  指标 `tansr_serve_token_mint_failures_total` 计每次上游铸造失败(负缓存命中不重复计)。
+- **governor 注入(SC-22 serve 半场)**:治理核(显式 `undici.Agent` 连接上限 / per-origin 隔离舱 /
+  熔断 / 重试预算 / 本地令牌桶)落 `@tansr/providers` `createUpstreamGovernor(options)`;serve 只负责把
+  **同一枚**进程级实例的 `fetch` 注入三处出站——`platform.governor`(铸令牌器 + bundle 缓存 + 模型
+  client)与 `startServer({ governor })`(轮末 webhook 通知机)。推荐:一进程一枚,`connections` 按平台
+  连接配额、`keepAliveTimeout ≥ 60 s`;宿主持有其生命周期(`governor.close()` 在 `server.drain()` 之后
+  由宿主调用,serve 恒不代关);宿主自实现 `fetch` 时必须尊重 `init.signal`(取消传播链在此不得断)。
+  未传 governor = 直连 `fetch`(行为零漂移)。
+- **G3 平台限流上报**:平台现行限流键绑 app key(`/t1/exchange` 120/min)+ 源 IP(600/min);网关形态
+  下全部 endUser 共用一把 key、一个出口 IP,本节的闸/缓存只能削峰、不能抬顶——`upstream_unavailable`
+  持续出现且 `Retry-After` 对齐到分钟整点,即触顶信号,应上报平台侧调档(总卷 G3 / C 路 D-1)。