@sema-agent/server 7.109.0 → 7.111.0

package/dist/user-input-ledger.d.ts

@@ -0,0 +1,349 @@
+/**
+ * S-928 —— **「已受理、未消费」的用户输入账本**(user-input acceptance ledger)的唯一属主:行形、判据、收敛、通告、读面投影。
+ * 设计稿 = sema-internal `server/design/` 的 S-928 稿(fable 主会话 2026-10-02);本文件是那份稿在代码里的**一处成文**。
+ *
+ * ## 病
+ * `POST /v1/runs/:id/steer` 对本副本的活 run 回 **200 `delivery:"applied"`**:输入只进了 core `TaskStream` 的**进程内**队列,
+ * 本服务此前不落任何字节。「你的输入丢了」今天唯一的告知是 core 在**腿终局**铸的 `task.user_steer_undrained`(`cause:"leg_end"`)——
+ * 进程被 SIGKILL / 崩溃时那个终局席跑不到 ⇒ **零告知**:壳手里只有一张 200 回执,重启后主请求与转录里都没有它。
+ * core 7.38.0 #1233 给了词:`detail.cause` 闭集 {@link USER_STEER_UNDRAINED_CAUSES} = `leg_end` / `crashed`,`crashed` 由**服务层**在
+ * 该会话下一条 run 之前铸。本文件 = 那个服务层。
+ *
+ * ## 对象(一只账本,一类输入,一句规则)
+ * 「本服务以回执向调用方承诺已交给引擎、而消费只发生在进程内存里的用户输入」,**且承载它的那只 `TaskStream` 活在本服务的一条 run 腿里**(S-966)——
+ * 后半句是收敛判词成立的前提:证据面是那条 run 行(下文「收敛判据」)。行的 `taskId` = 回执上的 run、`sessionId` = 那条 run 的会话(人看的那一只),
+ * run 里是哪一只流(run 自己的 / 同步子代的)**不是**账本的事实:告知按 run 并帧(`steer` = 条数),读面行同形。今天只有 steer 一族(`kind:"steer"` =
+ * core 的车道词:引擎把这些输入记在 steer 车道),三个入口同一个引擎动词 `TaskStream.steer`:
+ *  · `POST /v1/runs/:id/steer` 的 live 腿(200 applied);
+ *  · `POST /v1/runs/:id/interrupt` 的带 text 形(202 queued-immediate,档位 now;设计稿把它划在病面外,车 SW 亲核它进的是同一只进程内队列 ⇒ 同类同修);
+ *  · `POST /v1/runs/:id/subagents/:target/steer`(200 applied,S-966)—— 投进**同步子代**自己的流(core `createSteerHandle` → `stream.steer`)。子代由父腿
+ *    await,父腿收场时 core 撤掉在飞的复活(`subagentRetain.disposeAll`),所以它活在父 run 的腿里;腿 = 子代句柄,`handle.settled` 兑现 ⇒ 结清。
+ * 规则的反面(不是例外表):workflow agent steer(`POST /v1/workflows/:id/agents/:label/steer`,200 applied)不在本账 —— workflow 是会话锚定的后台件
+ * (core `WorkflowTaskHandle.sessionScoped`),活得比发起它的 run 腿长,没有一条 run 行约束它,而 workflow run 行上没有持有者列 ⇒ 判不出写者死没死(另票);
+ * 子代 resume(`…/subagents/:target/resume`)不往在飞的队列里投,起的是一条新的子代腿;follow-up 在本仓**没有**进程内受理口(`src/http/routes` 零
+ * follow-up 入口;steer 路由不下传 `priority`,core 缺省 `next` = steer 车道)⇒ 闭集一词,不预留第二词。
+ *
+ * ## 五形行(append-only;行序 = 语义序;File 孪生的盘上形 = 下面的 {@link UserInputLedgerRecord},SQL 孪生 = 一行一受理 + CAS 列 + 删行,同义)
+ *  · `accepted`  —— 受理点(`routes/runs.ts` 的 live 腿,**调 `TaskStream.steer` 之前**、回 200 之前)写;写不进 ⇒ 503
+ *                   `steering.ledger_unavailable`,引擎一个字节都没收到(fail-closed:没账的 200 是空头承诺)。身份 = `acceptId`
+ *                   (每次受理一枚;同 Idempotency-Key 的重放共享 `messageId`,但各是一次受理)。`writer` = 受理进程的 `instanceId`。
+ *  · `settled`   —— 本进程对这次受理的守护**正常结束**:`leg_end`(承载它的腿在本进程收场 —— done / suspended / needs_review / failed
+ *                   一律,未消费的那一半 core 已用 `leg_end` 自己告知,本仓不重算「消费了没有」)或 `not_applied`(`TaskStream.steer`
+ *                   抛了,这次受理没有变成 200;路由随即落这一行)。⚠️ 子代腿的 `leg_end` 由 core 铸在**子代自己的**会话上(`taskId` / `sessionId` /
+ *                   `runId` 全是子代的),本服务没有那只会话的口 ⇒ 今天到不了人(S-966 core 请托;🚧 钉在 `test/engine-notice-wire.test.ts`)。
+ *  · `converged` —— 收敛器判「受理它的进程已经不在、而它从没 settle」⇒ `cause:"crashed"`(core 闭集里服务层那一臂)。
+ *  · `announced` —— 通告**落进新 run 的事件账之后**写(`taskId` = 告知它的那条**新** run;`EngineNoticeRouter.routeConfirmed` 等口的落账结果,
+ *                   codex r1-F2):落账失败 ⇒ 不写,下一条 run 再说;重启再重启不重复。唯一的重复形 = 帧已落账而这一行没写成(写失败 / 进程死在两步之间)
+ *                   —— run 事件账与本账是两只店、没有共同事务,两害取「多说一遍」,不取「声称说过」。
+ * 转移只有四条(open → settled | converged;converged → announced),两只孪生都按 CAS 守它们(File 单进程 = 内存判;SQL = `WHERE state=…`)。
+ *  · `erased`    —— (S-965)**会话树删除**:该会话此前的每一次受理(不论状态)离开账本。行随会话走 —— 账本行的唯一归属键就是 `sessionId`,
+ *                   所以两条删会话树的级联(在线删除协调器 `boot/session-faces.ts` 的 `purgeSession`、托管留存的事务化孪生
+ *                   `retention-store-sql.ts` 的 `purgeSessionTrees`)各有一臂删它,谓词同一只(`session_id` 单键,店动词 `deleteBySession`)。
+ *                   File 孪生的盘上形 = 一行会话级墓碑 `{ kind:"erased", sessionId, at }`(与 workflow 完成信箱 `drain{sessionId}` 同形),
+ *                   只擦它**之前**的同会话行 —— 会话 id 删后可被重新登记,之后的受理属于下一位住客;SQL 孪生 = 真删行。被删受理上迟到的转移全输
+ *                   (行不在了,与「未知 acceptId」同一条守卫)。
+ *
+ * ## 收敛判据(一条:**受理它的进程已经不在,而承载它的腿没有正常收场**)—— 两车道同一只判词({@link judgeOpen},S-969 L8 合一)
+ * 证据面只有一个:承载它的 **run 行**(run 店;行上的 `instanceId` = 当前持有者,createRun 铸、markResuming 接管)。
+ *  · 行在、持有者是写者、仍 `running` ⇒ 腿没收场;写者在不在由车道答(下一段)—— 不在 ⇒ `crashed`,可能在 ⇒ `live`(不动,等 reaper)。
+ *  · 行在、持有者是写者、`failed` 且落款是 run 店的**死亡判决**({@link isHolderDeathVerdict}:`reapStale` 的 `RUN_STALLED_ERROR` /
+ *    File 车道孤儿回收与 claim 接管的 `RUN_ORPHANED_ERROR`)⇒ 写者死在腿收场之前 ⇒ `crashed`。判决落盘之后才收(codex r1-F1 / r3-F1:
+ *    读到的旧心跳不算 —— 读后写者可能恢复;收敛与 reap 的先后因此不承重)。维护 tick 里收敛排在 reapStale **之后**(同一条腿串行)。
+ *  · 其余 —— 行正常翻面(完成 / 失败 / 取消)、已 park(suspended / needs_review:引擎把未消费的 steer 迁进检查点,续跑重投)、易手(续跑被别的
+ *    进程接走)⇒ 腿正常收场了,只是没人替它落 settle ⇒ 补落 `settled{leg_end}`(判词 `leg_over`,见 {@link OpenVerdict}),不告知。
+ *  · 行**不在**(`getRun` 答 undefined)⇒ 由车道答(下一段 ②):local `crashed`、SQL `leg_over`。
+ * 车道只回答事实表 {@link LANE_FACTS} 的**两问**({@link WriterGoneEvidence}):① 外来写者仍持有的 `running` 行,写者可能还活着吗;
+ * ② run 行不在,这条腿怎么了(local ⇒ `crashed`:File 店藏读不出的行、写者已证死;SQL ⇒ `leg_over`:店不藏行,不在 = 真删了)—— ① 按车道:
+ *  · `exclusive_data_root`(local / File):不可能。数据根 `LOCK` 证明本进程之前的每一个写者都已死(`FileRunStore.reclaimOrphanedAtBoot` 的同一条论证)。
+ *    boot 序是先孤儿回收(把这样的行翻成 `failed` + `RUN_ORPHANED_ERROR`)再收敛,所以 local 上最常见的崩溃形读到的是落款;仍 `running`
+ *    的只剩回收因续跑中的检查点刻意跳过的行(写者死、腿没收场 ⇒ 同样 `crashed`)。
+ *  · `run_store_verdict`(SQL,多副本):可能。「本进程启动前写的」不证明写者已死(滚动发布 / 三副本)⇒ 等 reaper 把判决落在行上。
+ * S-969 L8 之前 local 臂不读 run 店、一律 `crashed`:进程恰死在 park 已提交、收场 settle 之前 ⇒ 那次 steer 已迁进检查点、续跑会重投,却被按崩溃
+ * 告知一次;settle 写丢后再崩的正常收场同理。两车道读同一只判词之后,「正常收场 / 已 park ⇒ 不告知」不再随车道变。
+ * 本进程写的行不读 run 店(活着的进程的受理归它自己的腿 settle,见 judgeOpen 首行)。触发 = boot 一次 + 每个维护 tick 一次;local 上 boot 之后
+ * open 集里不再有外来写者的行(每一行要么收敛要么结清,恒不判 `live`),维护 tick 的 local 臂恒空。一趟收敛对同一 taskId 只读一次 run 店(S-969 L9,
+ * 趟内备忘:同一条 run 上的受理在同一趟里得同一个判词)。
+ *
+ * ## 两张脸
+ *  · **通告**(user 受众)—— 该会话**下一条 run 的首拍**(三条腿开通告口那一拍、模型调用之前;{@link UserInputLedger.announceUndrained}):
+ *    每条**旧 run** 一帧 `task.user_steer_undrained`,`detail` 逐字合 core 契约 `{ steer, cause, taskId?, sessionId?, runId? }`:
+ *    `steer` = 那条旧 run 丢掉的**条数**(按 `messageId` 去重),`cause:"crashed"`,`taskId` = 旧 run 的句柄(core 自己的 `leg_end` 臂在本仓
+ *    腿上铸的也是它:`spec.taskId` = 本服务的 run id),`sessionId` 同会话;`runId`(引擎 per-leg 身份)**缺席** —— 死掉那条腿的引擎 run id
+ *    服务层没有记录,core 契约原句「omitted when the caller has none, never fabricated」。经既有 `route()`(白名单 / 归属 / 消毒 / 隔离四件)。
+ *  · **读面**(session)—— `GET /v1/sessions/:id` 的 additive 键 `userInputUndrained`({@link UndrainedUserInputRow}),只列 `converged`
+ *    的受理;**缺席 = 这一次读没有可报的条目**:零条(不铸 `[]`),或账本这一次读不出(F 类留痕,视图照常 200 —— codex r2-F3 部分采:
+ *    契约改说真话;不另起「不可用」态,理由见收车档)。
+ *
+ * ## 不做
+ * 不开旋钮(没有「关掉告知」的正当需求)· 不改 steer 的 200 体(回执仍是「已交付」,账本是它的影子)· 不重放丢失的输入(core 明写
+ * NOT redelivered;本账只告知,不替人决定重发)· 不存输入正文(行里只有身份与时刻)。
+ */
+import { type EngineNoticeCode, type UserSteerUndrainedCause } from "@sema-agent/core";
+import { type RunRecord } from "./plugins/store-contracts.js";
+import { type EngineNoticeRouter } from "./trace/engine-notice-wire.js";
+/** local 数据根下的子目录(File 孪生;与 `approval-ask-audit/` 同层同形)。 */
+export declare const USER_INPUT_LEDGER_DIR = "user-input-ledger";
+/** 账本收的输入族(闭集)。follow-up 结论见顶注「对象」段。 */
+export type UserInputKind = "steer";
+/** 读盘词表(`satisfies Record<…, true>` ⇒ 闭集加词而本表没跟 = 编译红;判定走 `Object.hasOwn`)。 */
+export declare const USER_INPUT_KIND_WORDS: {
+    readonly steer: true;
+};
+/** `settled` 的两种收场(闭集,见顶注)。 */
+export type SettleHow = "leg_end" | "not_applied";
+export declare const SETTLE_HOW_WORDS: {
+    readonly leg_end: true;
+    readonly not_applied: true;
+};
+/** 本服务铸的那一臂(core 删掉这个词 ⇒ `Extract` 得 `never` ⇒ 下面的常量编译红)。 */
+export type CrashedCause = Extract<UserSteerUndrainedCause, "crashed">;
+export declare const CRASHED_CAUSE: CrashedCause;
+/** 盘上 / 行上的 cause 词判:必须是 core 闭集的成员,**且**铸者是服务层(词表外 / 引擎臂 ⇒ 不是本账能写的行)。 */
+export declare function isServingLayerUndrainedCause(v: unknown): v is CrashedCause;
+/** 一次受理此刻的状态(四形行的折叠结果)。 */
+export type UserInputAcceptanceState = {
+    readonly kind: "open";
+} | {
+    readonly kind: "settled";
+    readonly how: SettleHow;
+    readonly atMs: number;
+} | {
+    readonly kind: "converged";
+    readonly cause: CrashedCause;
+    readonly atMs: number;
+};
+/** 一次受理 + 它此刻的状态(两只孪生的读口都交这个形)。 */
+export interface UserInputAcceptance {
+    readonly acceptId: string;
+    readonly input: UserInputKind;
+    /** 调用方手里那张 200 回执上的 `messageId`(带 Idempotency-Key 时重放同值)。 */
+    readonly messageId: string;
+    readonly sessionId: string;
+    /** 受理时承载它的 run(本服务的 run 句柄 = `/v1/runs/:taskId`,steer 回执上的 `taskId`)。 */
+    readonly taskId: string;
+    /** 受理进程的 `instanceId`(收敛判据的「写者」)。 */
+    readonly writer: string;
+    readonly acceptedAtMs: number;
+    readonly state: UserInputAcceptanceState;
+    /** 已在哪条 run 上告知过(只在 `converged` 之后才可能在场)。 */
+    readonly announced?: {
+        readonly atMs: number;
+        readonly taskId: string;
+    };
+}
+/** `accept` 的入参(新受理恒 open、恒未告知)。 */
+export type NewUserInputAcceptance = Omit<UserInputAcceptance, "state" | "announced">;
+/**
+ * 五形行(closed set,`kind` 判别)—— File 孪生的盘上形,也是本账语义的成文形。SQL 孪生把同一组转移落在一行的列上(`erased` = 删行)。
+ * 键 `at` = 这件事发生的时刻(ms epoch,写者的墙钟)。前四形以 `acceptId` 为键(一次受理);`erased` 以 `sessionId` 为键(一棵会话树)。
+ */
+export type UserInputLedgerRecord = {
+    readonly kind: "accepted";
+    readonly acceptId: string;
+    readonly input: UserInputKind;
+    readonly messageId: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly writer: string;
+    readonly at: number;
+} | {
+    readonly kind: "settled";
+    readonly acceptId: string;
+    readonly how: SettleHow;
+    readonly at: number;
+} | {
+    readonly kind: "converged";
+    readonly acceptId: string;
+    readonly cause: CrashedCause;
+    readonly at: number;
+} | {
+    readonly kind: "announced";
+    readonly acceptId: string;
+    readonly taskId: string;
+    readonly at: number;
+} | {
+    readonly kind: "erased";
+    readonly sessionId: string;
+    readonly at: number;
+};
+/**
+ * 四条转移 + 会话树删除的**唯一**成文实现(纯内存折叠)。File 孪生用它重放盘、也用它判运行期 CAS;Memory 孪生就是它本身。
+ * SQL 孪生不调它,但它的 `WHERE state = …` 谓词逐条对应这里的四个守卫、`DELETE … WHERE session_id = ?` 对应 `erased` —— 两边同一套断言见
+ * 试剂盒格(`test/helpers/user-input-ledger-kit.ts`)。
+ */
+export declare class UserInputLedgerFold {
+    private readonly byId;
+    private readonly bySession;
+    has(acceptId: string): boolean;
+    get(acceptId: string): UserInputAcceptance | undefined;
+    /** 本会话此刻在账的受理条数(`erased` 删掉的就是这么多)。 */
+    sessionSize(sessionId: string): number;
+    /** 这一行能不能落(守卫判;**不**改状态)。重放与运行期写同用 —— 不能落的行在运行期不写,在重放里被忽略。 */
+    admits(rec: UserInputLedgerRecord): boolean;
+    /** 落一行(守卫不过 ⇒ 返回 false、状态不动)。 */
+    apply(rec: UserInputLedgerRecord): boolean;
+    /** open 受理的键集分页:按 (受理时刻, acceptId) 升序,严格在 `after` 之后,至多 `limit` 条(SQL 腿同一个谓词);`next` 与 SQL 腿同一条规则
+     *  (页满 ⇒ 页末行的键,否则缺席)。折叠里没有读不出的行(盘上坏行在重放时就跳过了),所以页末行就是原始末行。 */
+    listOpen(after: OpenScanCursor | undefined, limit: number): OpenScanPage;
+    /** 一个会话里收敛过的受理:按受理时刻升序,至多**最新**的 `limit` 条(SQL 腿 `ORDER BY … DESC LIMIT` 后翻转,同义)—— 读面的窗。 */
+    listCrashed(sessionId: string, limit: number): UserInputAcceptance[];
+    /** 一个会话里收敛且**未告知**的受理:按受理时刻升序,从**最旧**起至多 `limit` 条(SQL 腿 `ORDER BY … ASC LIMIT`,同义)—— 通告的待办。
+     *  与读面的窗分开([ref] gpt-6 腿 [medium]):读面窗是「最新 N 条、含已告知」,已告知的行会把窗外更旧的未告知行永远挤在外面;
+     *  待办只看未告知、告知过的让位 ⇒ 每拍至少前进一页,窗外的最终可达。 */
+    listUnannounced(sessionId: string, limit: number): UserInputAcceptance[];
+}
+/** 两只读口(`listOpen` / `listUnannounced`)、两只孪生共用的页长校验:非正整数一律抛(SQL 腿把它插进 `LIMIT`,夹值 / 静默空页都是把坏参数吞掉)。 */
+export declare function assertPageLimit(op: string, limit: number): number;
+/** 两只孪生共用的排序(受理时刻,同刻按 acceptId)—— SQL 腿的 `ORDER BY accepted_at_ms, accept_id` 与它逐字同义。 */
+export declare function sortAcceptances(list: UserInputAcceptance[]): UserInputAcceptance[];
+/** open 受理的键集分页游标:上一页**原始**末行的 (受理时刻, acceptId);下一页从严格之后开始。 */
+export interface OpenScanCursor {
+    readonly acceptedAtMs: number;
+    readonly acceptId: string;
+}
+/**
+ * `listOpen` 的一页(S-969 L6):`open` = 这一页里**读得出**的 open 受理(读不出形的行已逐行跳过 + 计 F 类 tag);`next` = 续翻游标 =
+ * 这一页**原始**末行的键(被跳过的坏行也算 —— 断点不许卡在坏行上,也不许因为页里少了一行就被当成「扫到底」),缺席 = 原始行不满一页(扫到底)。
+ * 游标属于店(只有店见过原始行),收敛扫描只照着它翻,不从交回的行反推。
+ */
+export interface OpenScanPage {
+    readonly open: readonly UserInputAcceptance[];
+    readonly next?: OpenScanCursor;
+}
+/** 收敛扫描的页长(open = 活腿上的受理 + 等收敛的孤儿,量级是人的手速)。 */
+export declare const USER_INPUT_OPEN_SCAN_MAX = 1000;
+/** 一趟收敛至多翻多少页(预算:十万条 open 行;到顶 ⇒ 断点留下,下一趟从断点续翻、扫到底再回绕 —— codex r3-F2)。
+ *  一趟的上界(S-969 L9 成文):至多 `PAGES` 次页读 × `OPEN_SCAN_MAX` 行;run 店读 = 外来写者行里**不同 taskId** 的个数(趟内备忘,本进程写的行不读);
+ *  转移写 = 判出 crashed / leg_over 的行数。boot 那一趟在 stage-07 被 await(协调面开服之前收完 —— 时机不变),所以它的墙钟也受这个上界约束。 */
+export declare const USER_INPUT_OPEN_SCAN_PAGES = 100;
+/** 一个会话的「收敛过的受理」读口上限(读面 / 通告都经它;有界 wire)。收敛行 = 崩溃丢失,量级远小于受理总数;超出时取最新的这么多条。 */
+export declare const USER_INPUT_SESSION_READ_MAX = 500;
+/**
+ * **存储孪生契约**(Memory / File / TiDB / Pg 四只实现同一组断言,试剂盒格见 `test/helpers/user-input-ledger-kit.ts`)。
+ * 转移方法返回「这一次是不是我转的」(CAS 赢者):守卫不过 ⇒ `false`、零写。`accept` 写不进 ⇒ **抛**(调用方据此回 503)。
+ */
+export interface UserInputLedgerStore {
+    accept(a: NewUserInputAcceptance): Promise<void>;
+    settle(acceptId: string, how: SettleHow, atMs: number): Promise<boolean>;
+    converge(acceptId: string, atMs: number): Promise<boolean>;
+    announce(acceptId: string, taskId: string, atMs: number): Promise<boolean>;
+    /** open 受理的一页 —— 收敛扫描的读口。键集分页:按 (受理时刻, acceptId) 升序,严格在 `after` 之后(缺席 = 从头),至多 `limit` 条**原始行**
+     *  (缺席 = {@link USER_INPUT_OPEN_SCAN_MAX});读不出形的行逐行跳过、续翻游标按原始行推进({@link OpenScanPage})。收敛逐页翻到底
+     *  (codex r2-F2:固定最旧一页会让活腿占满窗口时后面的崩溃丢失永远轮不到)。三只读口对读不出的行同一处置:跳过 + F 类 tag
+     *  `server.user-input-ledger.corrupt-record-skipped`,不整页抛(S-969 L6)。 */
+    listOpen(after?: OpenScanCursor, limit?: number): Promise<OpenScanPage>;
+    /** 一个会话里**收敛过**(崩溃丢失)的受理,含已告知的(按受理时刻升序,至多最新的 {@link USER_INPUT_SESSION_READ_MAX} 条)—— **读面**的读口。
+     *  只读收敛行是刻意的:一个长会话可以有成千上万条正常收场的受理,读口若按「会话的全部受理」截断,新的丢失会被旧的正常行挤出窗外。 */
+    listCrashed(sessionId: string): Promise<UserInputAcceptance[]>;
+    /** 一个会话里收敛且**未告知**的受理,从最旧起至多 `limit` 条(按受理时刻升序)—— **通告**的待办读口([ref] gpt-6 腿 [medium]:
+     *  通告若读读面那只「最新 N 条含已告知」的窗,已告知行占窗 ⇒ 窗外更旧的未告知行永远不被说;待办只看未告知,说过的让位,窗外的最终可达)。 */
+    listUnannounced(sessionId: string, limit: number): Promise<UserInputAcceptance[]>;
+    /** S-965 —— **会话树删除**:删掉该会话**每一种状态**的受理,回删除条数(没有可删的 ⇒ 0、零写;幂等)。按 `session_id` 单键:行上没有属主列,
+     *  会话所有权由调用方证过(在线删除 = 路由的 DELETE 门;留存 = 候选集本身出自本域加锁读的 `session_meta`),与 anchors / exemptions /
+     *  attachments 同律。调用方 = 在线删除协调器(`boot/session-faces.ts` `purgeSession` 的一腿);托管留存的事务化孪生不调店、在自己的事务里
+     *  发**同一只谓词**(`retention-store-sql.ts` `purgeSessionTrees` ④)。写不进 ⇒ 抛(协调器据此不删会话本体,幂等重试收敛)。 */
+    deleteBySession(sessionId: string): Promise<number>;
+}
+/** 收敛判词读的 run 店面(只读一只动词)。 */
+export interface RunStoreReader {
+    getRun(taskId: string): Promise<RunRecord | null | undefined>;
+}
+/**
+ * 「受理它的进程已经不在」的证据(S-969 L8 合一):两车道读**同一只** run 店判词(见顶注「收敛判据」),`kind` 只回答车道事实表
+ * {@link LANE_FACTS} 里的两问(闭集穷举,判词本身不随车道变):
+ *  ① 外来写者仍持有的 `running` 行,写者可能还活着吗 —— `exclusive_data_root`(local):不可能(数据根 LOCK:本进程之前的写者都已死);
+ *    `run_store_verdict`(SQL,多副本):可能(等 reaper 把死亡判决落在行上)。
+ *  ② run 行不在(`getRun` 答 undefined),这条腿怎么了(7.111.0 [ref] gpt-6 腿 X2)—— local:File 店 `hydrate` 跳过坏 / 缺时间戳的
+ *    `run.json`(S-582 F 座)也答不在 ⇒ 读不出腿怎么收场、写者又已证死 ⇒ `crashed`(告知;= v7.110.0);SQL:店不藏行(读失败是响的
+ *    Error,走 read-failed),不在 = 真删了 ⇒ 腿既不可能还活着也不可能续跑、没有可对照的 run ⇒ `leg_over`(结清;= v7.110.0)。S-965 起
+ *    删会话 / 留存级联连账本行一起删,SQL 的这一形只剩级联半拍里的竞态与旧副本混版窗删的会话。
+ */
+export interface WriterGoneEvidence {
+    readonly kind: "exclusive_data_root" | "run_store_verdict";
+    readonly runs: RunStoreReader;
+}
+/** 受理回执(路由持有;`withdraw` 凭它撤)。 */
+export interface UserInputAcceptReceipt {
+    readonly acceptId: string;
+    readonly leg: object;
+}
+/** `GET /v1/sessions/:id` 的 `userInputUndrained[]` 行(wire 形;时刻为 ISO,与同一应答体的 `createdAt` 同形)。 */
+export interface UndrainedUserInputRow {
+    readonly messageId: string;
+    readonly kind: UserInputKind;
+    /** 丢输入的那条旧 run(steer 回执上的 `taskId`)。 */
+    readonly taskId: string;
+    readonly acceptedAt: string;
+    readonly cause: CrashedCause;
+    /** 已在哪条 run 上告知过;缺席 = 还没有下一条 run 打开过这个会话。 */
+    readonly announced?: {
+        readonly at: string;
+        readonly taskId: string;
+    };
+}
+/** 账本的活对象(单写者:本进程对账本的一切写都经它)。 */
+export interface UserInputLedger {
+    /** 受理点:落 `accepted`(fsync / 提交之后才返回)。写不进 ⇒ 抛(路由回 503,不调引擎)。`leg` = 承载它的活 `TaskStream`。 */
+    accept(input: {
+        input: UserInputKind;
+        messageId: string;
+        sessionId: string;
+        taskId: string;
+        leg: object;
+    }): Promise<UserInputAcceptReceipt>;
+    /** 引擎没收下(`TaskStream.steer` 抛)⇒ 落 `settled{not_applied}`。不抛(失败留痕,受理仍挂在腿上,腿收场时照常 settle)。 */
+    withdraw(receipt: UserInputAcceptReceipt): Promise<void>;
+    /** 腿在本进程收场 ⇒ 这条腿上的每一次受理落 `settled{leg_end}`。不抛。 */
+    settleLeg(leg: object): Promise<void>;
+    /** 收敛扫描(boot 一次 + 每个维护 tick;判据见顶注)。不抛;返回本次收敛条数。 */
+    converge(): Promise<number>;
+    /** 新 run 首拍:把本会话已收敛、未告知的受理按旧 run 分组铸通告、投出后落 `announced`。不抛。 */
+    announceUndrained(at: {
+        sessionId: string;
+        taskId: string;
+    }, router?: EngineNoticeRouter): Promise<void>;
+    /** 读面投影;`undefined` = 零条(键缺席)。读失败 ⇒ 抛(调用方按读面纪律处置)。 */
+    readSession(sessionId: string): Promise<UndrainedUserInputRow[] | undefined>;
+}
+/**
+ * 一条旧 run 的 `crashed` 通告(纯数据)。`detail` 键集 = core 契约 `{ steer, cause, taskId?, sessionId?, runId? }` 的子集(`runId` 缺席,理由见顶注)。
+ * `message` 只是 fallback 展示(core 同族句的形,只换成因);消费端按 `code` + `detail.cause` 分支。
+ */
+export declare function buildCrashedSteerNotice(input: {
+    steer: number;
+    taskId: string;
+    sessionId: string;
+}): {
+    code: EngineNoticeCode;
+    message: string;
+    detail: Record<string, unknown>;
+    sessionId: string;
+};
+/**
+ * `create*`:账本活对象。`writer` = 本进程 `instanceId`;`evidence` 由装配层按车道给(run 店 + 车道词;local ⇒ `exclusive_data_root`,SQL ⇒ `run_store_verdict`)。
+ * 腿 → 受理的追踪是**进程内**的(`WeakMap` 以活 `TaskStream` 为键):收场 settle 只需要本进程自己受理过的那些,崩溃时它随进程消失 —— 那正是收敛要接的那一半。
+ */
+export declare function createUserInputLedger(opts: {
+    store: UserInputLedgerStore;
+    writer: string;
+    evidence: WriterGoneEvidence;
+    now?: () => number;
+    newId: () => string;
+    scanBudget?: {
+        pageSize: number;
+        maxPages: number;
+    };
+}): UserInputLedger;
+/** boot 装配点:造活对象并跑一次 boot 收敛(协调面开始服务之前)。收敛读数交给调用方的启动日志。 */
+export declare function createUserInputLedgerAtBoot(opts: Parameters<typeof createUserInputLedger>[0]): Promise<{
+    ledger: UserInputLedger;
+    converged: number;
+}>;
+/**
+ * 装配层按**车道**给证据(闭集穷举:`StoreBackend.kind` 加一个词而这里没跟 ⇒ 编译红)。两臂都带 run 店(S-969 L8:判词同一只),车道词只答
+ * 「外来写者仍持有的 running 行」那一问:
+ *  · `local` —— 数据根 LOCK 保证单进程 ⇒ `exclusive_data_root`(外来写者都已死);
+ *  · `mysql` / `pg` —— 多副本共享一张表,「我启动之前写的」证明不了写者已死 ⇒ `run_store_verdict`(等 reaper 落款)。
+ */
+export declare function writerGoneEvidenceFor(backendKind: "mysql" | "pg" | "local", runs: RunStoreReader): WriterGoneEvidence;
+//# sourceMappingURL=user-input-ledger.d.ts.map