@sema-agent/server 7.132.0 → 7.133.0

package/dist/plugins/store-backend.d.ts

@@ -10,6 +10,7 @@ import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { type ApprovalExemptionStore } from "./approval-exemption-store.js";
 import { type ApprovalNonceStore } from "./approval-nonce-store.js";
+import { type OrgDeliveryQuotaStore } from "./org-delivery-quota-store.js";
 import { type ApprovalAskStore as ApprovalAskStoreType } from "./approval-ask-store-sql.js";
 import { type MemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js";
 import { type SendFileLedger } from "./send-file-ledger.js";
@@ -59,6 +60,19 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  *  whole-tree `ServiceFileSnapshotStore` ([ref]: the boundary covers the TRACKED set only — files this
  *  session edited; there is no whole-tree manifest anymore). Also the 2c history-transfer store
  *  (exportHistory/importHistory + the blob negotiation faces below). */
+/**
+ * The 2c `putBlob` answer: core's `FileHistoryResult` plus ONE arm — the SQL blob judge refused the blob on the connection that
+ * would have written it ({@link import("./blob-backend.js").BlobTooLargeError}, code `blob_too_large_for_sql`). `PUT /sync/blobs`
+ * answers that arm 413 (the store's sentence, plus the machine-readable `wallSource` = where the cap came from) and every other failure 502 (retryable).
+ */
+export type SyncBlobPutResult = import("@sema-agent/core").FileHistoryResult | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: import("./blob-backend.js").BlobTooLargeError["code"];
+        readonly message: string;
+        readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+    };
+};
 export type ServiceFileHistoryStore = FileHistoryStore & {
     /** 2c sync blob-face marker — see SqlFileHistoryStore.syncBlobFaces (codex R2-high: name-probing
      *  `putBlob` on an arbitrary store collides with the local core store's PRIVATE void helper). */
@@ -70,7 +84,7 @@ export type ServiceFileHistoryStore = FileHistoryStore & {
      *  protected — never a synchronous external-store delete). Reaper-driven; SQL twins only. */
     sweepOrphanBlobs?(): Promise<number>;
     /** 2c blob negotiation: upload one content-addressed blob ahead of importHistory. SQL twins only. */
-    putBlob?(hash: string, bytes: Uint8Array): Promise<import("@sema-agent/core").FileHistoryResult>;
+    putBlob?(hash: string, bytes: Uint8Array): Promise<SyncBlobPutResult>;
     /** 2c blob read face (scope-checked by the route against the session's history graph). SQL twins only. */
     getBlob?(hash: string): Promise<Uint8Array | undefined>;
     /** The subset of `hashes` already present — a cheap SQL INDEX probe (the import presence pre-check,
@@ -163,6 +177,11 @@ export interface StoreBackend {
      *  `approvalExemption` 同姿势:tidb/pg = SQL 双方言(单类双语句),local = File 追加日志 + 压实。
      *  **不能**退化成进程内易失形:一次重启若把记录抹掉,JWT TTL 窗内的重放就复活了,而那正是本店要关的洞。 */
     approvalNonce(): ApprovalNonceStore;
+    /** [ref] §10.2 —— 跨主体投递门的配额店(`org-delivery-quota-store.ts`:一次 take 在同一把锁下判并记对偶界与收件人
+     *  聚合界)。REQUIRED on all backends —— tidb/pg = SQL 双方言(单类双语句,窗按库钟),local = File 整份快照(本进程墙钟;
+     *  数据根锁保证一个进程)。门装配时才取(`PRINCIPAL_INBOX_ASSISTANT` 在场);**不能**退化成进程内易失形:多副本各数各的
+     *  = 额度 × 副本数,一次重启清零 = 窗内额度复活。 */
+    orgDeliveryQuota(): OrgDeliveryQuotaStore;
     /** [ref]([ref] §3.0-§3.2)流内审批协议持久层:每个流内工具调用一行的 ask 状态机 + 批行。
      *  REQUIRED **且持久** on all backends — tidb/pg = SQL 双方言 twin;local = {@link FileApprovalAskStore}。
      *
@@ -287,6 +306,11 @@ export interface StoreBackend {
      *  缺席**是一个真答案**:那里的索引家在 run 店同一间屋子里(`LocalWorkflowAgentSessionIndex`,文件账本
      *  或纯内存),不需要经过 backend。契约与单写者纪律的属主 = orchestration/workflow-agent-session-index.ts。 */
     workflowAgentSessionIndex?(): import("../orchestration/workflow-agent-session-index.js").WorkflowAgentSessionIndex;
+    /** workflow 子代停驻卡的耐久决定行(一张卡一行,键 = 子代 checkpoint 的 token),**绑在本后端的 {@link run} 那只 run 店上**(每一笔写都在它的会话认领栅栏里落)。
+     *  与 `run()` 同形:无参、恒交同一只(三孪生同),所以这只决定店绑的就是部署的 run 店。SQL 后端 = 跨副本表,读写走 run 店的池;`local` 后端 = 进程内,
+     *  账本位置由后端按自己的数据根与 `WORKFLOW_RUN_STORE` 定(`<数据根>/workflows/workflow-park-decisions/decisions.jsonl`;`memory` ⇒ 纯内存)。
+     *  契约与律的属主 = orchestration/workflow-park-decision.ts。 */
+    workflowParkDecisions?(): import("../orchestration/workflow-park-decision.js").WorkflowParkDecisionStore;
     /** Cloud-only stores below are OPTIONAL: the `local` (in-memory/file) backend omits them (it has no core
      *  in-memory twin carrying the service extras, and these are fleet/multi-replica concepts), so a local HTTP
      *  service degrades EXACTLY like today's no-DB env (the consumers gate on `backend?.X?.()`). TiDB/PG provide all. */
@@ -301,6 +325,17 @@ export interface StoreBackend {
     checkpoint?(logger?: {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
+    /**
+     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」就走这一口,不走 {@link checkpoint}。
+     * 区别只有一条:这一口**不牵动任何别的店**。local 车道的 `checkpoint()` 是 durable 停驻面的装配点 —— 它给 run 店接上 [ref] 的收割探针(停驻行的收割从 no-op 变生效),
+     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;留存腿在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失,看不见就会把还能被决的停驻的问删掉),
+     * 所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
+     *
+     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:留存腿读不到这一口的后果在**删除方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删),
+     * 「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端(`checkpoint` 缺席)交一只恒空的读口
+     * (`{ listPendingSessionIds: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
+     */
+    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds">;
     toolResult?(): ToolResultStoreFull;
     imageIndex?(): ImageIndex;
     imageBake?(): ImageBake;

package/dist/plugins/store-backend.js

@@ -7,8 +7,9 @@ import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { fileSessionCaptureRecordStore } from "@sema-agent/core";
 import { TiDBOutcomeLedger, PgOutcomeLedger } from "./outcome-ledger-sql.js";
 import { FileOutcomeSink } from "./file-outcome-sink.js";
-import { TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, TiDBWorkflowAgentSessionIndex, PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore, PgWorkflowAgentSessionIndex } from "./workflow-run-store-sql.js";
+import { TiDBWorkflowRunStore, TiDBWorkflowCompletionInbox, TiDBWorkflowNotifyJournalStore, TiDBWorkflowAgentSessionIndex, SqlWorkflowParkDecisionStore, PgWorkflowRunStore, PgWorkflowCompletionInbox, PgWorkflowNotifyJournalStore, PgWorkflowAgentSessionIndex } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
+import { LocalWorkflowParkDecisionStore } from "../orchestration/workflow-park-decision.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { buildStoreOpenRefusalTail } from "./store-open-refusal.js";
 import { acquireLocalBackendWithWait } from "./store-lock-wait.js";
@@ -19,6 +20,7 @@ import { LocalCheckpointStore } from "./local-checkpoint-store.js";
 import { FileResumeAnchorStore } from "./file-resume-anchor-store.js";
 import { TiDBApprovalExemptionStore, PgApprovalExemptionStore, FileApprovalExemptionStore } from "./approval-exemption-store.js";
 import { TiDBApprovalNonceStore, PgApprovalNonceStore, FileApprovalNonceStore } from "./approval-nonce-store.js";
+import { TiDBOrgDeliveryQuotaStore, PgOrgDeliveryQuotaStore, FileOrgDeliveryQuotaStore } from "./org-delivery-quota-store.js";
 import { TiDBApprovalAskStore, PgApprovalAskStore } from "./approval-ask-store-sql.js";
 import { FileApprovalAskStore } from "./approval-ask-store-file.js";
 import { TiDBMemoryOptOutGrantStore, PgMemoryOptOutGrantStore } from "./memory-optout-grant-store-sql.js";
@@ -61,7 +63,7 @@ import { openWithinWait } from "./store-open-wait.js";
 function historyBlobBackend(config, dialect, pool) {
     const s = config.snapshotBlobStore;
     if (!s)
-        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes, FILE_HISTORY_BLOB_TABLE);
+        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes, FILE_HISTORY_BLOB_TABLE, createLogger(config.logLevel));
     return new MinioBlobBackend({
         endpoint: s.endpoint,
         bucket: s.bucket,
@@ -75,7 +77,7 @@ function historyBlobBackend(config, dialect, pool) {
 function legacyBlobBackend(config, dialect, pool) {
     const s = config.snapshotBlobStore;
     if (!s)
-        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes);
+        return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes, undefined, createLogger(config.logLevel));
     return new MinioBlobBackend({
         endpoint: s.endpoint,
         bucket: s.bucket,
@@ -121,10 +123,12 @@ class TiDBBackend {
     }
     ensureSchema() { return ensureTidbSchema(this.pool); }
     close() { return this.pool.end(); }
-    run() { return new TiDBRunStore(this.pool); }
+    run() { return (this.runStoreInst ??= new TiDBRunStore(this.pool)); }
+    runStoreInst;
     resumeAnchor() { return new TiDBResumeAnchorStore(this.pool); }
     approvalExemption() { return new TiDBApprovalExemptionStore(this.pool); }
     approvalNonce() { return new TiDBApprovalNonceStore(this.pool); }
+    orgDeliveryQuota() { return new TiDBOrgDeliveryQuotaStore(this.pool); }
     approvalAsk() { return new TiDBApprovalAskStore(this.pool); }
     permissionRule() { return createSqlPermissionRuleStores(mysqlDriver(this.pool)); }
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
@@ -142,8 +146,11 @@ class TiDBBackend {
     completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); }
     notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); }
     workflowAgentSessionIndex() { return new TiDBWorkflowAgentSessionIndex(this.pool); }
+    workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
+    parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
     checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
+    checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new TiDBToolResultStore(this.pool); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
     imageBake() { return new TiDBImageBake(this.pool); }
@@ -154,7 +161,7 @@ class TiDBBackend {
     breaker(onWriteFail) { return new TiDBBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new TiDBSessionStore(this.pool); }
+    session() { return new TiDBSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
     adoptionLog() { return new TiDBAdoptionLogStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
@@ -170,10 +177,12 @@ class PgBackend {
     }
     ensureSchema() { return ensurePgSchema(this.pool); }
     close() { return this.pool.end(); }
-    run() { return new PgRunStore(this.pool); }
+    run() { return (this.runStoreInst ??= new PgRunStore(this.pool)); }
+    runStoreInst;
     resumeAnchor() { return new PgResumeAnchorStore(this.pool); }
     approvalExemption() { return new PgApprovalExemptionStore(this.pool); }
     approvalNonce() { return new PgApprovalNonceStore(this.pool); }
+    orgDeliveryQuota() { return new PgOrgDeliveryQuotaStore(this.pool); }
     approvalAsk() { return new PgApprovalAskStore(this.pool); }
     permissionRule() { return createSqlPermissionRuleStores(pgDriver(this.pool)); }
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
@@ -191,8 +200,11 @@ class PgBackend {
     completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); }
     notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); }
     workflowAgentSessionIndex() { return new PgWorkflowAgentSessionIndex(this.pool); }
+    workflowParkDecisions() { return (this.parkDecisionsInst ??= new SqlWorkflowParkDecisionStore(this.run())); }
+    parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
     checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
+    checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new PgToolResultStore(this.pool); }
     imageIndex() { return new PgImageIndex(this.pool); }
     imageBake() { return new PgImageBake(this.pool); }
@@ -203,7 +215,7 @@ class PgBackend {
     breaker(onWriteFail) { return new PgBreakerState(this.pool, onWriteFail); }
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
-    session() { return new PgSessionStore(this.pool); }
+    session() { return new PgSessionStore(this.pool, { log: createLogger(this.config.logLevel) }); }
     adoptionLog() { return new PgAdoptionLogStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
@@ -217,6 +229,7 @@ class LocalBackend {
     resumeAnchorStore;
     approvalExemptionStore;
     approvalNonceStore;
+    orgDeliveryQuotaStore;
     approvalAskStore;
     sendFileLedgerStore;
     userInputLedgerStore;
@@ -225,6 +238,7 @@ class LocalBackend {
     onWarn;
     onError;
     discloseWarn;
+    parkDecisionLedgerRoot;
     constructor(root, config, onWarn, onError) {
         this.onWarn = onWarn;
         this.discloseWarn = onWarn ?? ((msg, meta) => console.warn(msg, meta));
@@ -249,9 +263,11 @@ class LocalBackend {
             strictHydrate: config.runStoreStrictHydrate,
         });
         this.sessionStore = new LocalSessionStore(createLocalSessionRepo(this.fileBackend.root), this.runStore, this.fileBackend.root, { log: createLogger(config.logLevel) });
+        this.parkDecisionLedgerRoot = config.workflowRunStoreBackend === "memory" ? undefined : join(this.fileBackend.root, "workflows");
         this.resumeAnchorStore = new FileResumeAnchorStore(this.fileBackend.root);
         this.approvalExemptionStore = new FileApprovalExemptionStore(this.fileBackend.root, { warn: corruptReadWarn });
         this.approvalNonceStore = new FileApprovalNonceStore(this.fileBackend.root, { warn: corruptReadWarn });
+        this.orgDeliveryQuotaStore = new FileOrgDeliveryQuotaStore(this.fileBackend.root, { warn: corruptReadWarn });
         this.approvalAskStore = new FileApprovalAskStore(this.fileBackend.root);
         this.sendFileLedgerStore = new FileSendFileLedger(this.fileBackend.root);
         this.userInputLedgerStore = new FileUserInputLedgerStore(this.fileBackend.root);
@@ -284,9 +300,14 @@ class LocalBackend {
         await this.fileBackend.dispose();
     }
     run() { return this.runStore; }
+    workflowParkDecisions() {
+        return (this.parkDecisionsInst ??= new LocalWorkflowParkDecisionStore(this.runStore, this.parkDecisionLedgerRoot));
+    }
+    parkDecisionsInst;
     resumeAnchor() { return this.resumeAnchorStore; }
     approvalExemption() { return this.approvalExemptionStore; }
     approvalNonce() { return this.approvalNonceStore; }
+    orgDeliveryQuota() { return this.orgDeliveryQuotaStore; }
     approvalAsk() { return this.approvalAskStore; }
     permissionRule() {
         if (!this.permissionRuleStoresInst) {
@@ -300,20 +321,25 @@ class LocalBackend {
     permissionRuleStoresInst;
     sendFileLedger() { return this.sendFileLedgerStore; }
     userInputLedger() { return this.userInputLedgerStore; }
+    checkpointStoreOf() {
+        return (this.checkpointStoreInst ??= new LocalCheckpointStore(this.fileBackend.root, {
+            getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
+            ownerOf: (sessionId) => this.sessionStore.ownerOf(sessionId),
+        }));
+    }
     checkpoint() {
-        if (!this.checkpointStoreInst) {
-            const cs = new LocalCheckpointStore(this.fileBackend.root, {
-                getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
-                ownerOf: (sessionId) => this.sessionStore.ownerOf(sessionId),
-            });
-            this.checkpointStoreInst = cs;
+        const cs = this.checkpointStoreOf();
+        if (!this.checkpointProbeWired) {
+            this.checkpointProbeWired = true;
             this.runStore.setCheckpointProbe({
                 hasPending: async (sessionId) => (await cs.findPendingTokenBySession(sessionId)) !== null,
                 hasExpired: (sessionId) => cs.hasExpiredBySession(sessionId),
             });
         }
-        return this.checkpointStoreInst;
+        return cs;
     }
+    checkpointReadView() { return this.checkpointStoreOf(); }
+    checkpointProbeWired = false;
     checkpointStoreInst;
     sessionPolicy() { return this.fileBackend.sessionPolicyStore; }
     fileUsageWindowStore() { return this.fileBackend.usageWindowStore; }

package/dist/plugins/store-contracts.d.ts

@@ -183,6 +183,22 @@ export declare function readLegacyHolderDeathCode(row: {
  * 正常失败(别的码 / 无码)/ park 过期收割(`approval.expired`:腿 park 过)都**不是**死亡判决。
  */
 export declare function isHolderDeathVerdict(run: Pick<RunRecord, "status" | "errorCode">): boolean;
+/**
+ * `listRuns` 的查询(三只 run 店同一份形)。过滤都是精确匹配(`""` 是合法的精确值,不是「不滤」—— B10)。
+ * `owner`:串 = 恰这一个主体的 run;`null` = 属主为 null 的 run(不带主体提交的任务:匿名 / 单用户 —— 审批读面的公共 scope `_` 由调用方译成它,店里不认 `_`);
+ * 缺席 = 不按属主过滤。SQL 两方言 `null` ⇒ `owner IS NULL`(`owner = NULL` 恒不为真)。
+ */
+export interface RunListQuery {
+    status?: string;
+    jobId?: string;
+    source?: string;
+    owner?: string | null;
+    cursor?: {
+        createdAt: string;
+        taskId: string;
+    };
+    limit: number;
+}
 export interface RunRecord {
     taskId: string;
     sessionId: string;
@@ -272,6 +288,32 @@ export type CreateRunOutcome = {
     existing?: undefined;
     activeTaskId: string;
 };
+/** SQL 认领栅栏的结局:`held: false` = 认领此刻不是这条 run 的(或它已不在跑),`write` 一次都没调。 */
+export type ClaimFenced<T> = {
+    readonly held: true;
+    readonly value: T;
+} | {
+    readonly held: false;
+};
+/**
+ * 进程内栅栏 `write` 交回的**落定记号**。`write` 的型是 `() => FenceLanded`:只有**同步**交回这只记号的回调编得过 —— async 回调交回的是
+ * `Promise<FenceLanded>`(把真正的写挪到栅栏判完、放开之后的别的微任务里,「判认领与落行同一拍」就不成立了),不是它;栅栏方法没有类型参数,
+ * 显式写宽(`<unknown>` / `<void>` / `<object>`)无处可写,回调把返回标宽也编不过。要带出值,用闭包。
+ */
+export declare const FENCE_LANDED: unique symbol;
+export type FenceLanded = typeof FENCE_LANDED;
+/**
+ * **宿主会话的认领当写栅栏用 —— 进程内那一形**(属主 = run 店;Memory / File 两孪生同律)。认领 = 会话 → 持有它的 taskId,
+ * 由 {@link CreateRunOutcome} 的建行(或续跑腿的 markResuming)取得、终局 / 收割放掉 —— 「这次受理还持有会话吗」只问它,不另记身份。
+ *
+ * `whileHoldingClaim(sessionId, taskId, write)`:**只有** `taskId` 此刻持有 `sessionId` 的认领、且这条 run 是活的(`running`)时才调 `write`、答 `true`,
+ * 同一拍把这条 run 的活性戳刷新(一次栅栏写也是一次心跳);否则一次都不调、答 `false`。整只是**同步**的 —— `write` 也是:判、刷新、`write` 落定是同一个同步段,
+ * 中间没有让出,所以认领在 `write` 落定之前挪不动(这一条由类型担保 —— `write` 必须同步交回 {@link FENCE_LANDED},不靠「这里恰好没有 await」)。
+ * SQL 孪生的栅栏是一个事务(`run-store-sql.ts` `SqlRunStore.whileHoldingClaim`,`write` 收那只事务连接,结局 {@link ClaimFenced}),不是本型。
+ */
+export interface InProcessClaimFence {
+    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
+}
 /**
  * `RunRecord["status"]`(= `"running" | TaskStatus`)的**唯一分类表** —— 词表的属主 = 判据的属主,
  * 与类型定义同住一个文件。四个类:

package/dist/plugins/store-contracts.js

@@ -20,6 +20,7 @@ export function readLegacyHolderDeathCode(row) {
 export function isHolderDeathVerdict(run) {
     return run.status === "failed" && run.errorCode !== null && RUN_HOLDER_DEATH_CODE_WORDS.has(run.errorCode);
 }
+export const FENCE_LANDED = Symbol("in-process-claim-fence.landed");
 export const RUN_STATUS_CLASS = {
     running: "live",
     completed: "succeeded",

package/dist/plugins/tidb-pool.d.ts

@@ -23,7 +23,12 @@ export declare function tidbPoolOptions(tidb: NonNullable<ServiceConfig["tidb"]>
  *   · `lib/base/pool.js` / `lib/promise/pool.js` —— 池层与 promise 包装层都**不**把连接 error 再
  *     emit 到池对象上(池层只 emit acquire/connection/enqueue/release)。
  *  ⇒ 空闲连接被 KILL / 故障切换杀掉 = 库内吞并淘汰,进程不死、池自愈。真 TiDB KILL 钉在
- *  `test/pool-idle-error-db-integration.test.ts` 第③格。升 mysql2 大版时按上面三坐标复核。 */
+ *  `test/pool-idle-error-db-integration.test.ts` 第③格。升 mysql2 大版时按上面三坐标复核。
+ *
+ *  **另一种病不在上面三坐标里 —— 库回完一个错误包随后才关连接**(1153 语句超过 `max_allowed_packet`:库读完包头就拒、回错、关连接):
+ *  mysql2 的 `pool.query` 只看见「这条语句完了」,连接照常归还,库的 FIN / RST 晚一拍才到,紧接着的下一笔借到这条半死的连接、答 `write ECONNRESET`
+ *  (`lib/base/pool.js` 的 `query` 只对只读节点三个错误号销毁连接)。所以交出去的池是 {@link createCloseAwarePool} 包过的:池上的裸语句改为每条租一条连接,
+ *  收到 `isConnectionUnusableError` 一类的错先销毁再抛(借出给店的连接走同一只守卫,`sql-driver.ts` 的 `leaseOf`)。 */
 export declare function createTidbPool(config: ServiceConfig): Pool;
 /**
  * Idempotent schema. `session_event` is the append-only L1 event log (positional slicing by

package/dist/plugins/tidb-pool.js

@@ -9,6 +9,7 @@ import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
+import { PRINCIPAL_MAX_UTF8_BYTES } from "../security.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { CENTRAL_SCHEMA_INDEXES } from "./schema-indexes.js";
 import { SESSION_INDEXES } from "./pg-session-storage.js";
@@ -24,6 +25,7 @@ import { PERMISSION_RULE_INDEXES } from "./permission-rule-store-sql.js";
 import { RETENTION_INDEXES } from "./retention-store-sql.js";
 import { LEADER_RUN_INDEXES } from "./leader-run-store-sql.js";
 import { pollUntilLocked } from "./ensure-schema-lock-policy.js";
+import { createCloseAwarePool } from "./sql-driver.js";
 export function tidbPoolOptions(tidb) {
     const { host, port, user, password, database, connectionLimit } = tidb;
     const limit = connectionLimit ?? 10;
@@ -48,7 +50,7 @@ export function createTidbPool(config) {
         throw new Error("TiDB config missing. Set MYSQL_HOST / MYSQL_USER / MYSQL_DATABASE (and MYSQL_PASSWORD/PORT) " +
             "when SESSION_BACKEND=mysql.");
     }
-    return mysql.createPool(tidbPoolOptions(config.tidb));
+    return createCloseAwarePool(mysql.createPool(tidbPoolOptions(config.tidb)));
 }
 export const SCHEMA_STATEMENTS = [
     `CREATE TABLE IF NOT EXISTS session_meta (
@@ -193,7 +195,7 @@ export const SCHEMA_STATEMENTS = [
      -- ever served an operator's ad-hoc WHERE error_code LIKE 'budget.%', while every task_run write paid its
      -- maintenance cost. If you need that ad-hoc query, build the index temporarily and drop it after.
    ) COLLATE utf8mb4_bin`,
-    `CREATE TABLE IF NOT EXISTS circuit_breaker (
+    `CREATE TABLE IF NOT EXISTS breaker_state (
      breaker_key VARCHAR(190) NOT NULL,
      phase       VARCHAR(16)  NOT NULL,
      failures    INT          NOT NULL DEFAULT 0,
@@ -373,6 +375,25 @@ export const SCHEMA_STATEMENTS = [
      expires_at_ms  BIGINT       NOT NULL,
      PRIMARY KEY (session_id, nonce),
      KEY idx_approval_nonce_expires (expires_at_ms)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_sender_quota (
+     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     window_start_ms BIGINT         NOT NULL,
+     attempts        INT            NOT NULL,
+     PRIMARY KEY (from_scope)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_recipient_quota (
+     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     window_start_ms BIGINT         NOT NULL,
+     delivered       INT            NOT NULL,
+     PRIMARY KEY (to_scope)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS org_delivery_pair_quota (
+     to_scope        VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     from_scope      VARBINARY(${PRINCIPAL_MAX_UTF8_BYTES}) NOT NULL,
+     window_start_ms BIGINT         NOT NULL,
+     delivered       INT            NOT NULL,
+     PRIMARY KEY (to_scope, from_scope)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS user_input_acceptance (
      accept_id         VARCHAR(64)  NOT NULL,
@@ -517,18 +538,19 @@ export const SCHEMA_STATEMENTS = [
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS workflow_journal (
      run_id        VARCHAR(191) NOT NULL,
+     incarnation   VARCHAR(64)  NOT NULL,
      ordinal       INT          NOT NULL,
-     -- scope (SVC-2 / CORE-9 audit BLOCKER): the table predates scope — it was added when the
-     -- WorkflowJournalStore seam grew a scope param for cross-tenant resume isolation. Every new append writes the
-     -- run's REAL scope. EXISTING (pre-migration) rows carry '' = CROSS-SCOPE ORPHANS, harmless by construction: a
-     -- real resume filters WHERE scope = <caller>, so the blank-scope residue never matches a tenant. The
-     -- NOT NULL DEFAULT '' is what let the original ALTER succeed on a table that already had rows — keep the
-     -- default so the "'' = orphan, never a tenant" reading stays true.
-     scope         VARCHAR(190) NOT NULL DEFAULT '',
      call_key      VARCHAR(255) NOT NULL,
      result        MEDIUMTEXT   NOT NULL,
      created_at_ms BIGINT       NOT NULL,
-     PRIMARY KEY (run_id, ordinal)
+     PRIMARY KEY (run_id, incarnation, ordinal)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS workflow_journal_owner (
+     run_id         VARCHAR(191) NOT NULL,
+     scope          VARCHAR(190) NOT NULL,
+     incarnation    VARCHAR(64)  NOT NULL,
+     appended_at_ms BIGINT       NOT NULL,
+     PRIMARY KEY (run_id)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS workflow_resume_claim (
      source_run_id VARCHAR(191) NOT NULL,
@@ -556,6 +578,18 @@ export const SCHEMA_STATEMENTS = [
      scope      VARCHAR(190) NOT NULL,
      PRIMARY KEY (session_id, run_id),
      KEY idx_wfagentsess_run (run_id)
+   ) COLLATE utf8mb4_bin`,
+    `CREATE TABLE IF NOT EXISTS workflow_park_decision (
+     token             VARCHAR(120) NOT NULL,
+     run_id            VARCHAR(191) NOT NULL,
+     host_session_id   VARCHAR(190) NOT NULL,
+     outcome           MEDIUMTEXT   NOT NULL,
+     fingerprint       VARCHAR(64)  NOT NULL,
+     delivered_task_id VARCHAR(191) NOT NULL,
+     accepted_at_ms    BIGINT       NOT NULL,
+     PRIMARY KEY (token),
+     KEY idx_wfparkdec_host (host_session_id),
+     KEY idx_wfparkdec_run (run_id)
    ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS workflow_completion_inbox (
      seq            BIGINT       NOT NULL AUTO_INCREMENT,

package/dist/plugins/tidb-session-storage.d.ts

@@ -27,8 +27,9 @@ export declare class TiDBSessionStorage extends BaseSessionStorage {
      * [ref] S3 [ref] pull seam — `SessionStorage.getEpochAnchor?()`: the nearest prompt-epoch carrier BELOW the
      * bounded-wake floor, AS STORED (engine 7.52.0: `Promise<unknown>`; the engine reads the record, a retired shape
      * included). The engine's `Session.getPromptEpoch()` asks for it only when the in-window branch walk finds no carrier
-     * (a rewind/resumeAt cut inside the kept tail; compactions without a restatement). The one reading of both SQL twins
-     * is {@link scanEpochAnchor}; this backend supplies its page query (keyset-paged to exhaustion).
+     * (a rewind/resumeAt cut inside the kept tail; compactions without a restatement). The one reading of every windowed
+     * storage (both SQL twins, the local leg's view window) is {@link scanEpochAnchor}; this backend supplies its page query
+     * (keyset-paged to exhaustion) and decodes its own rows.
      */
     getEpochAnchor(): Promise<unknown>;
     /**

package/dist/plugins/tidb-session-storage.js

@@ -24,10 +24,10 @@ export class TiDBSessionStorage extends BaseSessionStorage {
         this.floorSeq = floorSeq;
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.sessionId, this.floorSeq, async (beforeSeq) => {
+        return scanEpochAnchor(this.floorSeq, async (beforeSeq) => {
             const [rows] = await this.pool.query(SESSION_EVENT_LATEST_BY_TYPE_SQL.epochAnchor, [this.sessionId, beforeSeq]);
             return rows.map((r) => ({ seq: r.seq, payload: r.payload }));
-        });
+        }, (row) => decodeSessionEventPayload(row.payload, this.sessionId, row.seq));
     }
     static async wake(pool, sessionId) {
         const [metaRows] = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = ?`, [sessionId]);

package/dist/plugins/tidb-session-store.d.ts

@@ -10,12 +10,13 @@
  * Persistence only. **Tenant authorization (who may wake which session) lives in the service layer**
  * (`src/security.ts`), which uses `ownerOf` / `register` below. The store does not infer identity.
  */
-import { type AcquiredSession, type PlacedSessionRow, type SessionPlacement, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type SessionFace } from "../session-incarnation.js";
 import type { SessionSummary } from "./store-contracts.js";
 import type { SessionRowPatch } from "../session-row.js";
+import { type OrphanOwnerLog } from "../delegated-session-owner.js";
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class TiDBSessionStore implements SessionStore {
@@ -33,14 +34,33 @@ export declare class TiDBSessionStore implements SessionStore {
     };
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    constructor(pool: Pool);
+    /** 委派子代孤行那一行 warn 的去处(`delegated-session-owner.ts`;装配给部署的 logger,缺席 ⇒ 缺省 logger,不静默)。 */
+    private readonly log;
+    constructor(pool: Pool, opts?: {
+        readonly log?: OrphanOwnerLog;
+    });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
-    /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
+    /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
+    register(sessionId: string, owner: string | null): Promise<void>;
+    /**
+     * acquire 的建行(唯一一处):普通会话 ⇒ 无主(按 id 首建的既有读法);placed 会话 ⇒ 属主按委派继承律在**这一笔**里写入
+     * (S-1770:根会话的属主,根行不在取父,都不在 ⇒ 孤行哨兵 + warn;属主 = 判断时见证到的,读来源 → 判 → INSERT —— 读法与顺序只住在
+     * `delegated-session-owner.ts` 的 `createPlacedSessionRow`,本店只交既有读写口,PG 孪生同调)。
+     */
+    private createOnAcquire;
+    /**
+     * S-1770 委派继承律的**认领口**:这只会话的那一位住客(判断时读到的化身)仍是无主的 placed 行 ⇒ 写 `owner`,返回是否写成
+     * (句 = `CLAIM_OWNERLESS_PLACED_SQL`,只 CAS 子行自己,与停驻挂点 / M23 同一只;规则在 `delegated-session-owner.ts`)。普通会话行不在射程(placed 判别位)。
+     */
+    claimOwnerless(sessionId: string, incarnation: string, owner: string): Promise<boolean>;
+    /** 若干来源行的会话面(属主 + 化身)一次读回(委派继承律的来源读;本店没有的 id 不在表里;化身经与 {@link sessionFaceOf} 同一只解码,空 ⇒ 响亮拒)。 */
+    private sourceFaces;
+    /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 在场时与行同一条 INSERT 落六列;ON DUPLICATE 臂是 no-op ⇒ 已存在的行的元组
      *  **永不被重写**(first-write 不可变,义务 5 的写侧半场)。
      *  S-790:化身与属主同一条 first-write 律 —— 新行铸一只(`mintSessionIncarnation`),已存在的行 no-op 臂一个字节不动。 */
-    register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
+    private insertMeta;
     /**
      * [ref] 义务 6 的廉价探针 —— 一行 PK SELECT:`undefined` = 普通会话或无此行。
      * (release 的冷缓存腿、包装店的暖命中准入判、诊断面共用这一只。)

package/dist/plugins/tidb-session-store.js

@@ -7,6 +7,8 @@ import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSour
 import { MANAGED_RETENTION } from "./retention-store-sql.js";
 import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
+import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRow } from "../delegated-session-owner.js";
+import { createLogger } from "../observability/logger.js";
 import { assertPlacementAdmission, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 export class TiDBSessionStore {
@@ -14,13 +16,15 @@ export class TiDBSessionStore {
     retention = MANAGED_RETENTION;
     placements = SQL_SESSION_PLACEMENTS;
     pending = new Map();
-    constructor(pool) {
+    log;
+    constructor(pool, opts = {}) {
         this.pool = pool;
+        this.log = opts.log ?? createLogger();
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
             const id = uuidv7();
-            await this.register(id, null, opts?.placement);
+            await this.createOnAcquire(id, opts?.placement);
             return this.load(id, false, opts);
         }
         if (opts?.requireExisting)
@@ -43,7 +47,7 @@ export class TiDBSessionStore {
         }
         if (requireExisting)
             throw new SessionError("not_found", `session ${sessionId} not found`);
-        await this.register(sessionId, null, opts?.placement);
+        await this.createOnAcquire(sessionId, opts?.placement);
         storage = await TiDBSessionStorage.wake(this.pool, sessionId);
         if (!storage) {
             throw new SessionError("storage", `session ${sessionId} vanished between register and wake (a concurrent purge won the race) — retry`);
@@ -51,7 +55,27 @@ export class TiDBSessionStore {
         assertPlacementAdmission(sessionId, (await storage.getMetadata()).placement, opts);
         return { session: new StoredSession(storage), sessionId };
     }
-    async register(sessionId, owner, placement) {
+    async register(sessionId, owner) {
+        await this.insertMeta(sessionId, owner, undefined);
+    }
+    async createOnAcquire(sessionId, placement) {
+        if (placement === undefined)
+            return this.insertMeta(sessionId, null, undefined);
+        await createPlacedSessionRow(sessionId, placement, {
+            readFaces: (ids) => this.sourceFaces(ids),
+            insert: (owner) => this.insertMeta(sessionId, owner, placement),
+            readOwner: () => this.ownerOf(sessionId),
+        }, this.log);
+    }
+    async claimOwnerless(sessionId, incarnation, owner) {
+        const [res] = await this.pool.query(CLAIM_OWNERLESS_PLACED_SQL.tidb, [...claimOwnerlessParams(sessionId, incarnation, owner)]);
+        return res.affectedRows > 0;
+    }
+    async sourceFaces(ids) {
+        const [rows] = await this.pool.query(`SELECT session_id, owner, incarnation FROM session_meta WHERE session_id IN (${ids.map(() => "?").join(", ")})`, [...ids]);
+        return new Map(rows.map((r) => [String(r.session_id), sessionFaceFromRow(String(r.session_id), r.owner ?? null, r.incarnation)]));
+    }
+    async insertMeta(sessionId, owner, placement) {
         const now = new Date();
         await this.pool.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
             "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) " +