@sema-agent/server 7.150.0 → 7.152.0

package/dist/stores-sql/tidb-session-store.js

@@ -6,7 +6,7 @@ import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-dec
 import { headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertCells, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
-import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOccupantChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.js";
 import { forkRowCells, selectForkRows } from "@sema-agent/core";
 import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf, sameSourceGeneration } from "../plugins/session-fork.js";
@@ -104,14 +104,33 @@ export class TiDBSessionStore {
     async register(sessionId, owner) {
         await this.registerWithReceipt(sessionId, owner);
     }
-    async registerWithReceipt(sessionId, owner) {
+    async registerWithReceipt(sessionId, owner, kind) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
         const incarnation = mintSessionIncarnation();
-        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        if (kind === undefined) {
+            await this.insertMeta(sessionId, owner, undefined, incarnation);
+            return { minted: { sessionId, owner, incarnation } };
+        }
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            await this.insertMetaOn(conn, sessionId, owner, undefined, incarnation);
+            const [rows] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [sessionId]);
+            if (rows[0]?.incarnation === incarnation)
+                await this.hooks.birth.record(statementsOn(conn), { rootSessionId: sessionId, kind });
+            await conn.commit();
+        }
+        catch (err) {
+            await conn.rollback().catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
         return { minted: { sessionId, owner, incarnation } };
     }
     async deleteSessionIf(sessionId, cond) {
@@ -137,9 +156,12 @@ export class TiDBSessionStore {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
     async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
+        await this.insertMetaOn(this.pool, sessionId, owner, placement, incarnation);
+    }
+    async insertMetaOn(on, sessionId, owner, placement, incarnation) {
         const now = new Date();
         const placed = placementInsertCells(placement, now);
-        await this.pool.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
+        await on.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
             "VALUES (?,?,?,?,NULL,0,?,?,?,?,?,?,?) ON DUPLICATE KEY UPDATE leaf_seq = leaf_seq", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
@@ -202,7 +224,7 @@ export class TiDBSessionStore {
             }
             throw err instanceof SessionError
                 ? err
-                : new SessionError("storage", `placed session ${sessionId} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+                : new SessionError("storage", `placed session ${sessionId} could not be deleted`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
@@ -298,11 +320,13 @@ export class TiDBSessionStore {
         if (!metaRows[0])
             return null;
         const pool = this.pool;
-        const batchSize = opts?.batchSize ?? 500;
+        const batchSize = opts.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1;
+            let cursor = opts.afterSeq ?? -1;
             for (;;) {
                 const [rows] = await pool.query(`SELECT seq, ${jsonColumnText("mysql", "payload")} FROM session_event WHERE session_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`, [sessionId, cursor, batchSize]);
+                if (rows.length > 0)
+                    await opts.recheck();
                 for (const r of rows)
                     yield decodeSessionEventPayload(r.payload, sessionId, r.seq);
                 if (rows.length < batchSize)
@@ -426,7 +450,7 @@ export class TiDBSessionStore {
         this.pending.clear();
     }
 }
-class TiDBStagingHandle {
+export class TiDBStagingHandle {
     pool;
     hooks;
     realSessionId;
@@ -466,11 +490,11 @@ class TiDBStagingHandle {
             await conn.beginTransaction();
             const now = new Date();
             const minted = mintSessionIncarnation();
-            if (opts.expectedOwner !== undefined) {
-                const [cas] = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = ? AND owner <=> ?", [this.realSessionId, opts.expectedOwner]);
+            if (opts.expectedOccupant !== undefined) {
+                const [cas] = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = ? AND owner <=> ? AND incarnation = ?", [this.realSessionId, opts.expectedOccupant.owner, opts.expectedOccupant.incarnation]);
                 if (cas.affectedRows !== 1) {
                     await conn.rollback();
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             else {
@@ -478,7 +502,7 @@ class TiDBStagingHandle {
                 const [claimed] = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = ? FOR UPDATE", [this.realSessionId]);
                 if (String(claimed[0]?.incarnation) !== minted) {
                     await conn.rollback();
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
@@ -490,7 +514,7 @@ class TiDBStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${String(dstMeta[0].placement_kind)} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = stagedRows.map((r) => String(r.entry_id));
-            const dstIds = opts.expectedOwner !== undefined ? dstRows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOccupant !== undefined ? dstRows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.rollback();

package/dist/submission-exit.d.ts

@@ -2,6 +2,7 @@ import type { DeploymentShapeInput } from "./deployment-shape.js";
 import type { RunAcceptance } from "./run-acceptance.js";
 import type { SessionWithdrawFace } from "./plugins/session-birth.js";
 import type { SessionBirth, StoreKeptWord } from "./session-incarnation.js";
+import type { BindingReceiptSink } from "./session-bindings.js";
 /** 收场词(闭集;加词 ⇒ {@link SubmissionSeat.close} 的穷尽 switch 编译红)。 */
 export type SubmissionEnd = "accepted" | "record" | "refused";
 /** 「留」的词:店内七词 + 座内四词(`withdraw_failed` = 撤回事务抛了,按留答)。 */
@@ -25,7 +26,7 @@ export interface SubmissionSeatDeps {
     };
 }
 /** 一次提交的出口座(提交门在授权之前铸;三条提交腿只喂它、收它)。 */
-export interface SubmissionSeat {
+export interface SubmissionSeat extends BindingReceiptSink {
     /** 授权器登记新行时交来的候选与店的撤回面(只有新行臂调;调多次以第一次为准)。 */
     noteBirth(birth: SessionBirth, face: SessionWithdrawFace): void;
     /** 提交门铸好 spec 之后挂上受理座(闩的唯一读者在 {@link close})。 */
@@ -36,7 +37,7 @@ export interface SubmissionSeat {
     markRecord(): void;
     /** 执行环境为这次提交留下了按会话键的持久物。 */
     noteEnvWitness(): void;
-    /** 此刻判不判得出「留」而不必走店(闩上 / record / 没有候选 / 有见证)。 */
+    /** 此刻判不判得出「什么都不撤」而不必收场(闩上 / record / 没有候选也没有回执 / 有见证也没有回执)。 */
     readonly keepsWithoutWithdraw: boolean;
     /** 收场(幂等、先到者定;不抛)。 */
     close(): Promise<SubmissionVerdict>;

package/dist/submission-exit.js

@@ -4,6 +4,7 @@ import { retireSessionId } from "./deleted-session-ids.js";
 import { seatText } from "./trace/exit-seat.js";
 export function createSubmissionSeat(deps) {
     let birth;
+    let bindings;
     let acceptance;
     let ownTaskId;
     let recorded = false;
@@ -16,12 +17,15 @@ export function createSubmissionSeat(deps) {
         let verdict;
         switch (end) {
             case "accepted":
+                bindings?.face.settleSessionBindings(bindings.receipt);
                 verdict = "kept_accepted";
                 break;
             case "record":
+                bindings?.face.settleSessionBindings(bindings.receipt);
                 verdict = "kept_record";
                 break;
             case "refused":
+                bindings?.face.withdrawSessionBindings(bindings.receipt);
                 verdict = await withdrawOrKeep();
                 break;
             default: {
@@ -60,6 +64,10 @@ export function createSubmissionSeat(deps) {
             if (birth === undefined)
                 birth = { birth: b, face };
         },
+        noteBindings(receipt, face) {
+            if (bindings === undefined)
+                bindings = { receipt, face };
+        },
         attachAcceptance(a) {
             acceptance = a;
         },
@@ -77,7 +85,7 @@ export function createSubmissionSeat(deps) {
             witnessed = true;
         },
         get keepsWithoutWithdraw() {
-            return birth === undefined || witnessed || endNow() !== "refused";
+            return endNow() !== "refused" || (bindings === undefined && (birth === undefined || witnessed));
         },
         close() {
             if (closing === undefined) {

package/dist/task-cwd.d.ts

@@ -115,8 +115,8 @@ export declare function effectiveHostWorkspace(sessionCwd: string | undefined, c
  * 为什么组合腿要它:梯子的每一级是在引擎**现铸的会话**里冷跑(core `runCascade` 剥掉 spec 的 `sessionId`),验证门的验证器腿的 spec 不带会话 ——
  * 工厂按腿的会话查登记表(第 1 臂)查不到提交登记在根会话上的那一枚,不交就落第 3 臂(临时目录):用户让梯子在项目里改文件,改到了别处;验证器验的是一只空目录。
  * 跑在根会话上的腿(验证门的实现腿 / 修复腿)第 1 臂先命中,同一个值。
- * 没登记(`registeredCwd` 缺席:非 host / device 车道、多租户、根会话的提交从没带过 `cwd`、嵌入方装配器没铸事实)⇒ 空对象 —— 每一条腿照旧落临时目录、收场由托管表删。
- * 登记粘在会话上(`setSessionCwd` 只在请求带 `cwd` 时写):同一会话之前带过、这次不带 ⇒ 交的仍是那一枚 —— 与第 1 臂对同一会话上普通 run 的读法一致。
+ * 没登记(这条腿的会话绑定没有工作目录:非 host / device 车道、多租户、根会话的提交从没带过 `cwd`、嵌入方装配器没铸事实)⇒ 空对象 —— 每一条腿照旧落临时目录、收场由托管表删。
+ * 登记粘在会话上(会话绑定的 `cwd` 一格 = 这条腿跑在的那一枚 —— 请求带的 ?? 项目继承来的 ?? 会话上已登记的 —— 受理之后写回会话,`session-bindings.ts`):同一会话之前带过、这次不带 ⇒ 交的仍是那一枚 —— 与第 1 臂对同一会话上普通 run 的读法一致。
  */
 export declare function compositionLegRoot(registeredCwd: string | undefined): Pick<RunInternals, "parentCwd">;
 /** {@link launchWorkspaceOf} 读到的那一格出自哪里(闭集;起服那一行日志与随包文档的 `workspaceFrom` 词)。 */

package/dist/task-settings.d.ts

@@ -122,11 +122,13 @@ export declare function planReviewDecisionExitsPlan(decision: "approve" | "edit"
  * 新体 `{ ...body, permissionMode: entry.effective }`,调用方的对象不改;bundle 的 `settings.permissions.defaultMode` 不动 —— 顶层赢过它
  * ({@link effectivePermissionMode} 的优先序),再改它就是同一语义的第二个写者。披露这一折的通告(`entry-mode-clamp-notice.ts`)读的也是同一份 `entry`。
  *
- * 调用点一个:提交入口的那一步 `permission-mode-admission.ts` `stampSubmissionEntryMode`(受理判官的入口一步;`http/admission.ts` 的 `prepareSpec` 调它:值形门全部判完之后、`resolveSpec` 之前)。那一份体就是首跑装配读的体,也是
- * `buildCheckpointCtx` 持久化的体 ⇒ 一处盖章同时覆盖首跑与每一次续跑重建;装配腿与续跑腿都不读地板(两处读 = 两个源)。
- * 另外两个写者是 `plan_review` 写回(`http/resume-legs.ts` `drivePlanReview`,判据 {@link planReviewDecisionExitsPlan})与在飞 run 的切档口写回
- * (`http/routes/run-permission-mode.ts`,写的是同一只判官准入的词)。
- * 热改 `AUTONOMY` 只影响之后提交的任务与之后的切档:续跑腿保持存储体里的词。地板的属主是 `runtime-governance.ts` 的 `autonomyModeFloor`。
+ * 调用点一个:提交口 `stampSubmissionEntryMode`(`permission-mode-admission.ts`,受理判官的入口一步 `bodyEntry`;`http/admission.ts` 的 `prepareSpec` 调它:
+ * 值形门全部判完之后、`resolveSpec` 之前 —— 那一份体就是首跑装配读的体,也是 `buildCheckpointCtx` 持久化的体,写据 `submission` 记下它的顶层原值)。
+ * 存储体那一格的其余写者都经同一模块的改写口 `withStoredPermissionMode`(一笔换词、换写据):续跑口(`stampReplayEntryMode`,`http/resume-legs.ts` 的 `replayCtxOf`:
+ * 停驻 run 的存储体被重放之前过一次**现**地板 —— 同一只 `bodyEntry`;写据说那一格是地板的出口写下的且仍是它写下的那一格 ⇒ 原样;钳过的体随 CAS 赢点写回)、
+ * `plan_review` 写回(`http/resume-legs.ts` `drivePlanReview`,判据 {@link planReviewDecisionExitsPlan};plan 地板的出口)与在飞 run 的切档口写回
+ * (`http/routes/run-permission-mode.ts`,写的是同一只判官准入的词)。装配腿不读地板;每一腿读一次地板、写进体,run 的模式词仍只有存储体一个源。
+ * 热改 `AUTONOMY` 对之后的提交、切档与停驻 run 的下一次续跑都生效。地板的属主是 `runtime-governance.ts` 的 `autonomyModeFloor`。
  */
 export declare function stampEntryPermissionMode<B extends {
     permissionMode?: unknown;

package/dist/task-settings.js

@@ -1,7 +1,7 @@
 import { combinePolicies, parseRuleText, resolveReasoningProfile, rankOf, isThinkingLevel, RUN_WORKFLOW_TOOL_NAME, PERMISSION_MODES, isPermissionMode, ruleToolGrammarOf, hostChildEnvProblem, } from "@sema-agent/core";
 import { judgeUnmatchableToolNames } from "./config.js";
 import { NAME_TABLE_BEHAVIOR } from "./namespaced-rule-name.js";
-import { entryProblem } from "./entry-problems.js";
+import { HOME_UNRESOLVABLE, entryProblem } from "./entry-problems.js";
 import { MAX_PERMISSION_RULES_PER_LIST, RULE_ROOTS, allowListEntryOk, createRuleListPolicy, ruleListEntryOk, ruleRootOf, ruleSetsOf, ruleSourceOf, ruleTextOf } from "./permission-rule-list.js";
 import { allowLayerEntryCountIssue, describeAllowLayerOverCap } from "./rule-entry-list.js";
 import { limitRefusal } from "./limit-refusal.js";
@@ -498,7 +498,7 @@ export function rulePolicyBucketsRefusal(permissions, bases) {
                             `the engine never guesses one: without a home base the rule resolves to "unreadable" and every matching call stops to ask, so it guards nothing. ` +
                             `Spell the path absolutely (${"Edit(//abs/path/**)"} form), declare the lane's home with REMOTE_EXEC_HOME_DIR, or run the task on a lane whose home this worker knows.`,
                     };
-                    problems.push(entryProblem(SETTINGS_RULE_REFUSAL_CODE, `settings.${field}`, name, "home_unresolvable"));
+                    problems.push(entryProblem(SETTINGS_RULE_REFUSAL_CODE, `settings.${field}`, name, HOME_UNRESOLVABLE));
                 }
             }
         }
@@ -513,7 +513,7 @@ export function rulePolicyBucketsRefusal(permissions, bases) {
                         `it is the SEMA_CONFIG_DIR forwarded into the sandbox, else .sema under the execution environment's home, and this lane's home is unknown; the engine never guesses one. ` +
                         `Spell the path absolutely (${"Read(//abs/path/**)"} form), forward SEMA_CONFIG_DIR into the sandbox env, declare the lane's home with REMOTE_EXEC_HOME_DIR, or run the task on a lane whose home this worker knows.`,
                 };
-                problems.push(entryProblem(SETTINGS_RULE_REFUSAL_CODE, `settings.${field}`, name, "home_unresolvable"));
+                problems.push(entryProblem(SETTINGS_RULE_REFUSAL_CODE, `settings.${field}`, name, HOME_UNRESOLVABLE));
             }
         }
     }

package/dist/terminal.d.ts

@@ -1,4 +1,5 @@
 import { terminalProjection, type PausedCause, type TaskStatus, type TerminalCause } from "@sema-agent/core";
+import { StoreBoundaryFault, type StoreFaultClass } from "./plugins/store-fault.js";
 /**
  * 这次失败带的**机器码**(`terminal.failed.code`);非失败终局 ⇒ `undefined`。
  *
@@ -129,9 +130,12 @@ export declare function mapPauseSeats<T>(result: T, f: (seat: SeatObject, keys:
  *
  * ── 折码的运维线索:一句定形字段,两只入口各说一只词 ──
  * 字段 `original=<码 | <not-a-code>> outward=<对外词> messageBytes=<n> at=<观看点>`,只有闭集词、数字与码({@link isCodeToken});码形座里装着文字的、长得像码的秘密同理只报 `<not-a-code>`。
- * 失败句(库驱动原句,自由文本:可以有连接串 / 口令 / 库账号 / 表名)**不上 wire**({@link outwardStoreFailure}),只进**写入口**那一行的末尾格 `message=<JSON 串>` ——
- * 经出口座的一句话行(`operator-log-text`:凭据形换记号、剥控制字符、有界),读座的再观看不带(同一行存量行每读一次就重放一次)。`at` 说这是哪一次观看,**一个入口一只词**(类型给定,不靠记得传):
+ * 失败句**不上 wire**({@link outwardStoreFailure});店起源的失败到这里时句子已是店边界换过的对外句({@link storeBoundaryFault}:库驱动原句 —— 自由文本,可以有连接串 / 口令 / 库账号 / 表名 ——
+ * 只进店边界那一行 `at=store`),写入口那一行的末尾格 `message=<JSON 串>` 对它们带的就是对外句;不经店边界的抛出物(fs / 网络 / 第三方码)带的仍是它自己的句子 ——
+ * 都经出口座的一句话行(`operator-log-text`:凭据形换记号、剥控制字符、有界),读座的再观看不带(同一行存量行每读一次就重放一次)。`at` 说这是哪一次观看,**一个入口一只词**(类型给定,不靠记得传):
  *  · 本函数 = 结果**第一次**离开引擎(店的写口 / 出口铸体)⇒ `at=exit`,每折一次一行 `[terminal] outward_failure_code_folded <字段>[ message=<句>]` —— 每次都是一件新的失败;
+ *  · {@link storeBoundaryFault} = 失败**离开本服务的店**(SQL 店的出口)⇒ `at=store`,每次一行,多两格 `site=<店>.<方法> class=<判官词>`,`message=` 是原错与其 `cause` 链各层的句子(逐层过座);
+ *    查库的原话读这一行,按 `original=` 与时间对 `at=exit` / `request_error` 行;
  *  · {@link sealStoredResult} = 存量行的**再观看**(读座必填)⇒ 走 fail-open 纪律(登记 tag `server.terminal.stored-result-code-folded`):
  *    逐读计数 + 逐读探针行 + 每进程一次 warn,detail 即上面那句字段。读面每次轮询 / 每个观看者 / 每次重连都重放同一批行 ——
  *    计数让「旧失败被读了多少次」看得见,一次 warn 让日志不随读次放大;去重归记录器一只,不另造表。
@@ -148,12 +152,39 @@ export declare function sealResultForExit<T extends {
 export declare function sealStoredResult<T extends {
     readonly terminal?: unknown;
 }>(result: T, seat: StoredResultReadSeat): T;
+/**
+ * 一个折掉的码在出口上的对外句(纯函数、无副作用)—— 出口四入口的**唯一**读法:{@link outwardStoreFailure}(封口 / 抛出臂,带运维线索)、{@link outwardPlane}
+ * (投影出口,纯读、不出线索)与 {@link persistedPlaneOf} 的旧形臂。句子已是「某个类别句 + 本码尾注」⇒ 原样(店边界换过的句子,词在原错上判,见 {@link storeBoundaryFault});
+ * 否则 = 判官读 `{ code }` 的类别句 + 尾注(拼法 `outwardStoreSentence`,一只拼法两种输入)。任何一张脸上折过码的 `errorMessage` 都不可能是驱动的原句,不论这条因由封过口没有、存的是哪一代形。
+ * 店边界之前落盘的存量子代句的一次性改写(M53,`store-fault-sentence-m53.ts`)读同一只。
+ */
+export declare function outwardStoreMessageOf(code: string, message: unknown): string;
 /**
  * 腿**抛出**的错落进 run 行 `error` 列时的对外句(没有终局结果、没有因由的那一臂:`runs.ts` 后台腿的兜底腿与它的孪生 `resume-legs.ts` 兜底腿)—— 与终局因由是**同一只**
  * 铸点({@link outwardStoreFailure}):抛出物自带的 `code`({@link errorCodeOf},字符串)出了本仓词法 ⇒ 同码同句;没有码 / 码在词法内(本仓与引擎自己的错、普通 `Error`)⇒ 文本逐字,非库错误照旧。
  * `message` 是调用方已取出的抛出文本({@link errorText} 的产物,不抛);本函数不抛(读码口不抛)。
  */
 export declare function outwardThrownMessage(err: unknown, message: string): string;
+/**
+ * 🔴 **店边界 —— 驱动原句越出 SQL 店的唯一读者**。律:一只 SQL 店的任何出口(抛出值、包装错误的 `cause`、抛出或返回值里的失败文本、交给调用方的可调用对象)
+ * 只带「原码 + 稳定句」({@link StoreBoundaryFault});驱动的原句在这里记一次运维日志,不随错误走。店的出口在 `plugins/store-boundary.ts` 封口(逐生产者、编译期穷尽的出口表),
+ * 店里自己拼句 / 拼值 / 包 `cause` 的地方先读本函数、再用它交回的形。交回:
+ *  · 已是边界形 ⇒ 同一引用(嵌套店:最里层出口换过、记过,外层同一引用放行、不再记);
+ *  · typed 失败(顶层自带词法内的码:`SessionError("storage")`、`store.row_too_large` …)⇒ 同一引用,它的类、码与句子原样;它 `cause` 链上的驱动错**就地**换成边界形
+ *    (typed 层往下走,第一只不是 typed 而带驱动证据的那一段整只换;那一段的原句照样记一行 `at=store`);
+ *  · 调用方出身(`error-origin.ts` 的 `caller`:店把调用方钩子的抛出物原样还给调用方)⇒ 同一引用、不记 —— 它不是店的失败;
+ *  · 不触发扳机 ⇒ 同一引用(不带码 / 码在词法内、不带驱动出身记号的错照旧);
+ *  · 触发 ⇒ 一行运维日志(`at=store site=<店>.<方法> class=<判官词>`,`message=` 是原错与其 `cause` 链各层的句子,逐层过出口座)+ 计数,交回新铸的边界形。
+ * 扳机两条(任一):① **码出词法**:码在场且 {@link outwardFailureCode} 折它 —— fail-closed,词法外的码一律换句(驱动、套接字、对象存储、fs 都算);
+ *  ② **驱动出身**:原错或其 `cause` 链上任一层带池座打的记号(`plugins/error-origin.ts` 的 `driver`)—— 补词法看不见的无码驱动错。
+ * 链读法一律深 ≤ {@link CAUSE_CHAIN_DEPTH};链比这更深 ⇒ 当作带驱动证据(fail-closed:看不到底的链不放行)。
+ * 码的读法({@link driverCodeOf}):沿 `cause` 链(深 ≤ 8)取第一个非空串 `code`,`"unknown"` 只作兜底(与 core 的码链读法同读);一条串码都没有、而某一层带整数 `errno`
+ * ⇒ 码 = 那个 `errno` 的十进制串 —— 这是本仓的规则(引擎不读 errno):只带 errno 的驱动错(TiDB 自有号,mysql2 的码表里没有符号)于是进同一只扳机、说同一句,出口照折。
+ * 判官(`storeFaultClassOf`)在**原错**上判一次(连接类整句、errno 臂、1005 内层号都只在原错上读得到),词随形带走。不抛。
+ * `site` = 封口调用点的字面店词 + 方法名(源码里的标识符,不是外部输入)。
+ */
+export declare function storeBoundaryFault<E>(err: E, site: string): E | StoreBoundaryFault;
+export declare function setStoreBoundaryObserver(fn: ((site: string, faultClass: StoreFaultClass) => void) | undefined): void;
 /**
  * **投影出口的唯一属主**([ref])—— core 的 `terminalProjection` + 对外码归一,一次。
  *

package/dist/terminal.js

@@ -1,10 +1,11 @@
 import { writeLogText } from "./observability/logger.js";
 import { terminalProjection } from "@sema-agent/core";
-import { errorCodeOf } from "./observability/err-text.js";
+import { errorCodeOf, errorMemberOf } from "./observability/err-text.js";
 import { recordFailOpen } from "./observability/fail-open.js";
 import { redactSecrets } from "./trace/redact.js";
 import { seatText } from "./trace/exit-seat.js";
-import { storeFaultSentenceOfCode } from "./plugins/store-fault.js";
+import { STORE_FAULT_CLASSES, StoreBoundaryFault, outwardStoreSentence, storeFaultClassOf } from "./plugins/store-fault.js";
+import { errorOriginOf } from "./plugins/error-origin.js";
 import { readDenyFloorRefusalMessage, readDenyFloorSummaryOf } from "./read-deny-floor-notice.js";
 export function failureCodeOf(terminal) {
     return terminal.kind === "failed" ? terminal.code : undefined;
@@ -93,10 +94,13 @@ function foldCauseCode(terminal, at) {
 function outwardStoreFailure(code, message, at) {
     const outward = outwardFailureCode(code);
     reportFold(code, outward, message, at);
-    return { code: outward, message: outwardStoreMessage(code) };
+    return { code: outward, message: outwardStoreMessageOf(code, message) };
 }
-function outwardStoreMessage(code) {
-    return `${storeFaultSentenceOfCode(code)} [original code: ${code}]`;
+export function outwardStoreMessageOf(code, message) {
+    return isOutwardStoreSentence(message, code) ? message : outwardStoreSentence(storeFaultClassOf({ code }), code);
+}
+function isOutwardStoreSentence(message, code) {
+    return typeof message === "string" && STORE_FAULT_CLASSES.some((cls) => message === outwardStoreSentence(cls, code));
 }
 export function outwardThrownMessage(err, message) {
     const code = errorCodeOf(err);
@@ -104,6 +108,123 @@ export function outwardThrownMessage(err, message) {
         return message;
     return outwardStoreFailure(code, message, "exit").message;
 }
+export function storeBoundaryFault(err, site) {
+    if (err instanceof StoreBoundaryFault)
+        return err;
+    const origin = errorOriginOf(err);
+    switch (origin) {
+        case "caller":
+            return err;
+        case "driver":
+        case undefined:
+            break;
+        default: {
+            const unhandled = origin;
+            throw new Error(`store boundary: unknown error origin ${String(unhandled)}`);
+        }
+    }
+    if (isTypedFailure(err))
+        return rewriteDriverCause(err, site) ? err : reportedBoundaryForm(err, site);
+    if (!carriesDriverFault(err))
+        return err;
+    return reportedBoundaryForm(err, site);
+}
+const CAUSE_CHAIN_DEPTH = 8;
+function boundaryFormOf(err) {
+    const coded = driverCodeOf(err);
+    return new StoreBoundaryFault(storeFaultClassOf(err), coded.code, coded.errno);
+}
+function reportBoundary(err, fault, site) {
+    reportFold(fault.code, fault.code === undefined ? "-" : outwardFailureCode(fault.code), errorMemberOf(err, "message"), { at: "store", site, faultClass: fault.faultClass, layers: chainSentences(err) });
+}
+function reportedBoundaryForm(err, site) {
+    const fault = boundaryFormOf(err);
+    reportBoundary(err, fault, site);
+    return fault;
+}
+function isTypedFailure(err) {
+    const code = errorMemberOf(err, "code");
+    return typeof code === "string" && code !== "" && outwardFailureCode(code) === code && errorOriginOf(err) !== "driver";
+}
+function carriesDriverFault(err) {
+    const coded = driverCodeOf(err);
+    return (coded.code !== undefined && outwardFailureCode(coded.code) !== coded.code) || driverOriginOnChain(err) || causeChainBeyondDepth(err);
+}
+function causeChainBeyondDepth(err) {
+    let cur = err;
+    for (let depth = 0; depth < CAUSE_CHAIN_DEPTH; depth++) {
+        if (cur === null || typeof cur !== "object")
+            return false;
+        cur = errorMemberOf(cur, "cause");
+    }
+    return cur !== null && typeof cur === "object";
+}
+function rewriteDriverCause(top, site) {
+    let parent = top;
+    for (let depth = 0; depth < CAUSE_CHAIN_DEPTH; depth++) {
+        const cur = errorMemberOf(parent, "cause");
+        if (cur === null || typeof cur !== "object" || cur instanceof StoreBoundaryFault || errorOriginOf(cur) === "caller")
+            return true;
+        if (isTypedFailure(cur)) {
+            parent = cur;
+            continue;
+        }
+        if (!carriesDriverFault(cur))
+            return true;
+        const fault = boundaryFormOf(cur);
+        if (!Reflect.defineProperty(parent, "cause", { value: fault, writable: true, configurable: true, enumerable: false }))
+            return false;
+        reportBoundary(cur, fault, site);
+        return true;
+    }
+    return false;
+}
+let storeBoundaryObserver;
+export function setStoreBoundaryObserver(fn) {
+    storeBoundaryObserver = fn;
+}
+function driverCodeOf(err) {
+    let cur = err;
+    let fallback;
+    let errnoLink;
+    for (let depth = 0; cur !== null && typeof cur === "object" && depth < CAUSE_CHAIN_DEPTH; depth++) {
+        const code = errorMemberOf(cur, "code");
+        const errno = errorMemberOf(cur, "errno");
+        const integerErrno = typeof errno === "number" && Number.isInteger(errno) ? errno : undefined;
+        if (typeof code === "string" && code !== "") {
+            const link = { code, ...(integerErrno !== undefined ? { errno: integerErrno } : {}) };
+            if (code !== "unknown")
+                return link;
+            fallback ??= link;
+        }
+        if (integerErrno !== undefined)
+            errnoLink ??= { code: String(integerErrno), errno: integerErrno };
+        cur = errorMemberOf(cur, "cause");
+    }
+    return fallback ?? errnoLink ?? {};
+}
+function driverOriginOnChain(err) {
+    let cur = err;
+    for (let depth = 0; cur !== null && typeof cur === "object" && depth < CAUSE_CHAIN_DEPTH; depth++) {
+        if (errorOriginOf(cur) === "driver")
+            return true;
+        cur = errorMemberOf(cur, "cause");
+    }
+    return false;
+}
+function chainSentences(err) {
+    const layers = [];
+    let cur = err;
+    for (let depth = 0; cur !== null && typeof cur === "object" && depth < CAUSE_CHAIN_DEPTH; depth++) {
+        const message = errorMemberOf(cur, "message");
+        if (typeof message === "string" && message !== "")
+            layers.push(seatText("operator-log-text", message));
+        cur = errorMemberOf(cur, "cause");
+    }
+    if (layers.length === 0 && typeof err === "string" && err !== "")
+        layers.push(seatText("operator-log-text", err));
+    return layers.join(" | cause: ");
+}
 function foldAttemptCodes(attempts, at) {
     if (!Array.isArray(attempts))
         return attempts;
@@ -123,15 +244,24 @@ function foldAttemptCodes(attempts, at) {
     return folded ?? attempts;
 }
 const STORED_RESULT_FOLD_TAG = "server.terminal.stored-result-code-folded";
-function reportFold(code, outward, message, at) {
+function reportFold(code, outward, message, sighting) {
     const messageBytes = typeof message === "string" ? Buffer.byteLength(message, "utf8") : 0;
-    const fields = `original=${isCodeToken(code) ? code : "<not-a-code>"} outward=${outward} messageBytes=${messageBytes} at=${at}`;
+    const at = typeof sighting === "string" ? sighting : sighting.at;
+    const original = code === undefined ? "<uncoded>" : isCodeToken(code) ? code : "<not-a-code>";
+    const fields = `original=${original} outward=${outward} messageBytes=${messageBytes} at=${at}`;
     switch (at) {
         case "exit": {
             const sentence = typeof message === "string" && message !== "" ? ` message=${JSON.stringify(seatText("operator-log-text", message))}` : "";
             writeLogText("stderr", `[terminal] outward_failure_code_folded ${fields}${sentence}`);
             return;
         }
+        case "store": {
+            const where = sighting;
+            const layers = where.layers !== "" ? ` message=${JSON.stringify(where.layers)}` : "";
+            writeLogText("stderr", `[terminal] outward_failure_code_folded ${fields} site=${where.site} class=${where.faultClass}${layers}`);
+            storeBoundaryObserver?.(where.site, where.faultClass);
+            return;
+        }
         case "run.result":
         case "ev.done.result":
             recordFailOpen(STORED_RESULT_FOLD_TAG, fields);
@@ -160,7 +290,7 @@ function outwardProjection(terminal, at) {
         const presented = at === "exit" && plane.status === "failed" ? readDenyFloorRefusalMessage(plane.errorCode) : undefined;
         return presented === undefined ? plane : { ...plane, errorMessage: presented };
     }
-    return plane.status === "failed" ? { ...plane, errorCode: outward, errorMessage: outwardStoreMessage(plane.errorCode) } : { ...plane, errorCode: outward };
+    return plane.status === "failed" ? { ...plane, errorCode: outward, errorMessage: outwardStoreMessageOf(plane.errorCode, plane.errorMessage) } : { ...plane, errorCode: outward };
 }
 export function nestedPauseOf(terminal) {
     return terminal.kind === "failed" ? terminal.nestedPause : undefined;
@@ -200,7 +330,7 @@ export function persistedPlaneOf(result) {
     return {
         ...(typeof r.status === "string" ? { status: r.status } : {}),
         ...(typeof r.errorCode === "string" ? { errorCode: outwardFailureCode(r.errorCode) } : {}),
-        ...(typeof r.errorMessage === "string" ? { errorMessage: flatFolded && typeof r.errorCode === "string" ? outwardStoreMessage(r.errorCode) : r.errorMessage } : {}),
+        ...(typeof r.errorMessage === "string" ? { errorMessage: flatFolded && typeof r.errorCode === "string" ? outwardStoreMessageOf(r.errorCode, r.errorMessage) : r.errorMessage } : {}),
         ...(typeof r.blockedReason === "string" ? { blockedReason: r.blockedReason } : {}),
     };
 }