@sema-agent/server 7.141.0 → 7.143.0

package/dist/plugins/sql-errors.js

@@ -45,6 +45,19 @@ export function isDeadlockError(dialect, err) {
         return keyOf(err, "code") === PG_DEADLOCK_DETECTED_SQLSTATE;
     return keyOf(err, "errno") === MYSQL_ER_LOCK_DEADLOCK_ERRNO || keyOf(err, "code") === MYSQL_ER_LOCK_DEADLOCK_CODE;
 }
+export const DEADLOCK_RETRY_LIMIT = 8;
+export async function retryOnDeadlock(dialect, attempt, alsoArbitrated) {
+    for (let tries = 0;; tries++) {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (tries < DEADLOCK_RETRY_LIMIT && (isDeadlockError(dialect, err) || alsoArbitrated?.(err) === true))
+                continue;
+            throw err;
+        }
+    }
+}
 export const TIDB_ER_ENTRY_TOO_LARGE_ERRNO = 8025;
 export const MYSQL_ER_NET_PACKET_TOO_LARGE_ERRNO = 1153;
 export const MYSQL_ER_NET_PACKET_TOO_LARGE_CODE = "ER_NET_PACKET_TOO_LARGE";

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

@@ -1,6 +1,6 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
-import type { SessionStore, SessionPolicyStore, FileHistoryStore, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
+import type { SessionStore, SessionPolicyStore, FileHistoryStore, FileHistoryBlobExchange, FileHistoryError, WorkflowJournalStore, ToolResultStore, SessionCaptureRecordStore, UsageWindowStore } from "@sema-agent/core";
 import { type OutcomeSink } from "./file-outcome-sink.js";
 import { type InboxWarn } from "./workflow-run-store-sql.js";
 import { FileRunStore } from "./file-run-store.js";
@@ -60,37 +60,37 @@ export type ServiceSessionPolicyStore = SessionPolicyStore;
  *  carry (optional so the local lane's core `FileFileHistoryStore` still fits). Replaces the retired E19
  *  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). */
+ *  (exportHistory/importHistory + the blob exchange 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).
+ * The SQL twins' blob exchange — core's {@link FileHistoryBlobExchange} group (`put` / `get` / `has`, all three or none, read only
+ * through `blobExchangeOf` in `session-sync.ts`, which defers to core's judge) with ONE narrowing: a `put` refusal may carry
+ * `blobCap`, the SQL blob judge's refusal on the connection that would have written the blob
+ * ({@link import("./blob-backend.js").BlobTooLargeError}). Present ⟺ that refusal; `PUT /sync/blobs` answers it 413
+ * `blob_too_large_for_sql` (the judge's sentence, plus the machine-readable `wallSource` = where the cap came from). The content-address
+ * refusal is core's own (`adopt_failed`, `permanence: "terminal"`, nothing stored); every other failure is a write fault the route answers 502.
  */
-export type SyncBlobPutResult = import("@sema-agent/core").FileHistoryResult | {
+export type SqlBlobPutResult = {
+    readonly ok: true;
+} | {
     readonly ok: false;
-    readonly error: {
-        readonly code: import("./blob-backend.js").BlobTooLargeError["code"];
-        readonly message: string;
-        readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+    readonly error: FileHistoryError & {
+        readonly blobCap?: {
+            readonly wallSource: import("./blob-backend.js").SqlBlobCapReading["source"];
+        };
     };
 };
+export interface ServiceBlobExchange extends FileHistoryBlobExchange {
+    put(hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+}
 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). */
-    syncBlobFaces?: true;
+    /** The blob exchange (SQL twins only; core's local File store carries none). Narrowed per {@link ServiceBlobExchange}. */
+    readonly blobExchange?: ServiceBlobExchange;
     /** E21 purge / overwrite-dst sync wipe: drop the WHOLE scope incl. v1 baselines + DV-14 markers
      *  (`reap(scope, [])` deliberately retains those while the scope lives — not a purge). SQL twins only. */
     deleteBySession?(scope: string): Promise<number>;
     /** Async byte-GC for the file_history_blob domain (orphans left by reap/purge/lost mint races; grace-window
      *  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<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,
-     *  never N full getBlob GETs). SQL twins only. */
-    hasBlobs?(hashes: string[]): Promise<Set<string>>;
 };
 /** SVC-2 (core CORE-7) WorkflowJournalStore — core's interface PLUS the service `deleteByRun` (GC extra). tidb/pg =
  *  durable SQL twins (cross-replica resume journal); local = the service {@link FileWorkflowJournalStore}
@@ -128,15 +128,10 @@ export type CheckpointStoreFull = TiDBCheckpointStore | PgCheckpointStore | Loca
 /** The full tool-result store: core `ToolResultStore` + the service maintenance extras. The SQL twins carry
  *  both extras; the LOCAL lane returns core's `FileToolResultStore` (core 1.219 — durable across a
  *  process restart, the TOC "ReadToolResult(ref) 恒空" fix) which since core 5.28.0 carries `deleteBySession`
- *  (owner sidecar 判属主,无边车存量计 unattributable 不删)but still NOT `reapOlderThan` — consumers must
- *  optional-call (`store.reapOlderThan?.()`,local 上恒 no-op)。(R5 复扫纠:旧句「carries NEITHER」自
- *  core 5.28 起半假——本类型注是消费方第一落点,与 LocalBackend 内部注必须同真。)
+ *  (owner sidecar 判属主,无边车存量计 unattributable 不删)and since core 7.61.0 the age bound `reap(now, { maxAgeMs })`
+ *  — both are core `ToolResultStore`'s own optional members, so consumers optional-call them (`store.reap?.(…)`).
  *  Structural (not a nominal union) so all three backends flow through one seam. */
-export type ToolResultStoreFull = ToolResultStore & {
-    /** TTL sweep (SQL twins only): purge rows older than the cutoff. Local file store omits it (CC posture:
-     *  a single user's tool-result files persist like transcripts; bounded by being text previews). */
-    reapOlderThan?(cutoffMs: number): Promise<number>;
-};
+export type ToolResultStoreFull = ToolResultStore & {};
 /** Cross-replica counter twins expose the write-behind lifecycle (startRefresh/stop) main.ts drives. */
 export type BreakerStateStore = TiDBBreakerState | PgBreakerState;
 export type CostQuotaStore = TiDBCostQuota | PgCostQuota;
@@ -326,16 +321,19 @@ export interface StoreBackend {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
     /**
-     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」就走这一口,不走 {@link checkpoint}。
+     * 待决 checkpoint 的**只读**读口(**必选**成员)—— 「前世 / 别的副本留下的停驻」的读法,不走 {@link checkpoint}。两个读者:
+     *  · 审批账本留存律(`approval-ask-retention.ts` 的挂靠集)读「还有哪些会话停驻着」(`listPendingSessionIds`);
+     *  · local 车道起服收敛(`approval-crash-convergence.ts`)对审计判为孤儿的前世 `PARKING` 问跑对账器判据 ① 的候选读口(`findCheckpointCandidatesForAsk`:
+     *    停车行其实已提交 ⇒ `PARKED`,不收 `VOID`)。
      * 区别只有一条:这一口**不牵动任何别的店**。local 车道的 `checkpoint()` 是 durable 停驻面的装配点 —— 它给 run 店接上 [ref] 的收割探针(停驻行的收割从 no-op 变生效),
-     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;留存腿在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失,看不见就会把还能被决的停驻的问删掉),
-     * 所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
+     * 那是开了 `DURABLE_APPROVAL` 的部署才该发生的事;两个读者在没开它的部署上同样要读(前世 / 别的副本留下的停驻不因这一世的开关消失:留存腿看不见就会把还能被决的停驻的问删掉,
+     * 起服收敛看不见就会把前世已提交的停驻的问收成 `VOID`),所以读和接线必须分口。SQL 孪生本来无状态(接线靠 JOIN),两口同一只。
      *
-     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:留存腿读不到这一口的后果在**删除方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删),
-     * 「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端(`checkpoint` 缺席)交一只恒空的读口
-     * (`{ listPendingSessionIds: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
+     * 🔴 为什么必选而不是跟着 {@link checkpoint} 一起可选:读不到这一口的后果都在**不可逆方向**(挂靠集里少了待决停驻 ⇒ 还能被决的停驻的问按龄被删;判据 ① 恒不命中 ⇒
+     * 已提交的停驻的问被收成终态),「有 checkpoint 店却没交读口」若只是运行期的 `undefined`,就是一次静默少保护;必选 ⇒ 漏实现是**编译红**。没有 checkpoint 店的后端
+     * (`checkpoint` 缺席)交一只恒空的读口(`{ listPendingSessionIds: async () => [], findCheckpointCandidatesForAsk: async () => [] }` —— 没有店 ⇒ 没有停驻,这是事实不是缺省)。
      */
-    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds">;
+    checkpointReadView(): Pick<CheckpointStoreFull, "listPendingSessionIds" | "findCheckpointCandidatesForAsk">;
     toolResult?(): ToolResultStoreFull;
     imageIndex?(): ImageIndex;
     imageBake?(): ImageBake;

package/dist/plugins/store-backend.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { createCorruptReadSeat, createDurableAbsenceSeat } from "../observability/corrupt-read-seat.js";
 import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
+import { existsSync } from "node:fs";
 import { AdoptionError, FileStorageBackend } from "@sema-agent/core";
 import { FileWorkflowJournalStore } from "@sema-agent/core";
 import { fileSessionCaptureRecordStore } from "@sema-agent/core";
@@ -58,7 +59,8 @@ import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js"
 import { TiDBRetentionStore, PgRetentionStore, sqlStoreRetention } from "./retention-store-sql.js";
 import { TiDBRetentionLaneStore, PgRetentionLaneStore } from "./retention-lane-store-sql.js";
 import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
-import { createFilePermissionRuleStores } from "./permission-rule-store-file.js";
+import { FILE_PERMISSION_RULE_DIR, createFilePermissionRuleStores } from "./permission-rule-store-file.js";
+import { retireImportedLayerRootAllows } from "./imported-layer-root-retirement.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { storeDegradedReasonFor } from "../store-posture.js";
 import { openWithinWait } from "./store-open-wait.js";
@@ -298,17 +300,24 @@ class LocalBackend {
         const holderDeathCodeRowsBackfilled = this.runStore.migrateLegacyHolderDeathCodes();
         const archives = await this.sessionStore.migrateLocalArchives();
         const placements = await backfillLocalExecutionPlacements(this.runStore.sessionIdsWithRuns(), this.sessionStore.executionPlacementBackfill, { lanes: this.executionLanes });
+        const importedLayerRoot = { importedLayerRootAllowsRetired: [], importedLayerRootBucketsSkipped: [] };
+        if (existsSync(join(this.fileBackend.root, FILE_PERMISSION_RULE_DIR))) {
+            const rules = this.permissionRule();
+            await retireImportedLayerRootAllows({ candidateOwners: () => rules.approvals.importRecordOwners(), durable: rules.durable, isWholeBucketRefusal: () => false, isVanishedBucket: () => false }, importedLayerRoot);
+        }
         return {
             ...NO_SQL_MIGRATIONS,
             holderDeathCodeRowsBackfilled,
             executionPlacementsBackfilled: placements.backfilled,
             executionPlacementSessionsUnreadable: placements.unreadable,
             askExecutionLanesBackfilled: backfillLocalAskExecutionLanes(this.approvalAskStore, { lanes: this.executionLanes }),
+            askJournalRecordsUpgraded: this.approvalAskStore.upgradeJournalEnvelope(),
             localArchiveRowFactsBackfilled: archives.rowFactsBackfilled,
             localArchivesAnonymized: archives.anonymized,
             localArchivesKeptStamped: archives.keptStamped,
             localArchivesUnreadable: archives.unreadable,
             localArchiveSnapshotsRecovered: archives.snapshotsRecovered,
+            ...importedLayerRoot,
         };
     }
     async close() {

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

@@ -20,6 +20,7 @@
  */
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunIdentity } from "../identity-source.js";
+import type { SessionUnreadable } from "../session-error-wire.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -443,7 +444,7 @@ export declare function isUnsuccessfulRunStatus(status: RunRecord["status"]): bo
  * 未知词的方向与 {@link isTerminalRunStatus} 同向保守:判**不是** park。理由是消费点会据此做**不可逆**
  * 动作(cancel 的恢复把手会 CAS-expire 一张 checkpoint);对一个本进程读不懂的状态,少动一次远好过错杀。
  */
-export declare function isParkedRunStatus(status: RunRecord["status"]): boolean;
+export declare function isParkedRunStatus(status: RunRecord["status"]): status is ParkedRunStatus;
 /**
  * 会话的**活动词**(core `PeerSessionTempo`)——「这条会话现在在忙还是闲」的**唯一**一张表([ref])。
  *
@@ -531,6 +532,9 @@ export interface SessionSummary {
     /** 行标签(`src/session-row.ts` 的 `sessionRowTagOf`):这一位住客「PATCH 能写的每一格」的单向摘要,present-iff 这一行可被条件写(店有行格写原语 ∧ 行上有化身);
      *  只经店的列表行映射铸(`sessionRowTagKey`)。没有会话行的 lister(legacy task_run 聚合 / 内存孪生)缺席。wire 半场见 `security.ts SessionListItem.rowTag`(同名同义)。 */
     rowTag?: string;
+    /** 这只会话的存档读不出:present-iff 头的叶子读不出(唯一铸点 `session-error-wire.ts` 的 `sessionUnreadableOf`;码与读口同表)。叶子是行上一列的店(SQL 孪生)
+     *  与没有会话行的 lister 恒缺席。wire 半场见 `security.ts SessionListItem.unreadable`(同名同义)。 */
+    unreadable?: SessionUnreadable;
 }
 /**
  * [ref] —— 会话**枚举面**读 run 账里「每会话的 run 投影」的窄读面:`runCount` / `lastStatus` / `lastRunId` / `lastTaskRunId` 四位,
@@ -572,6 +576,51 @@ export interface LatestRunRef {
     owner: string | null;
     createdAt: string;
 }
+/** 引擎对一条腿实际挂上的记忆读集的观测(core `TaskResult.effectiveMemoryScopes` 的值;core 包根不单独导出这只型,从结果型取)。 */
+export type EffectiveMemoryScopes = NonNullable<PersistedTaskResult["effectiveMemoryScopes"]>;
+/**
+ * [ref] —— **空观测**的因由(闭集;词表属主 = 本文件,唯一铸点 = {@link settledLegObservationOf})。两词都只说**那条已结腿的记录里有什么**,不猜它为什么停 ——
+ * 停因的真源是那一条 run 自己的终局(`GET /v1/runs/:id` 的 `status` / `errorCode`),这里不复述第二份:
+ *  · `run_result_missing`    —— 记录里**没有结果**:本服务结算它时手里没有引擎的结果(持有它的实例丢了被收割、腿在引擎答出之前抛),或收割时写空了它(停驻过期被收割 ——
+ *    [ref] 律:收割把停驻结果写空,停驻时那份结果里的观测随之不在;本读口不另存一份);
+ *  · `run_result_unobserved` —— 记录里**有结果、结果里没有观测**:引擎的律是「缺席 ⇔ prepare 没走完」(引擎在准备阶段拒了 / 失败了它),
+ *    另两形同答 —— 引擎答出之前就被取消、由本服务铸的取消终局,与比这一观测更早的引擎写下的结果。
+ * 自铸 wire 值登记 = `trace/self-minted-wire.ts` 的 `sessionMemoryUnobservedReason`(`satisfies Record<…>`:加 / 删一个词而登记没跟 ⇒ tsc 红)。
+ */
+export declare const MEMORY_OBSERVATION_ABSENT_REASONS: readonly ["run_result_missing", "run_result_unobserved"];
+export type MemoryObservationAbsentReason = (typeof MEMORY_OBSERVATION_ABSENT_REASONS)[number];
+/** [ref] —— 空观测记号:与引擎三态同一只字段、同一个判别位 `state`(闭集加一词 `absent`;引擎哪天自己长出同名一态 ⇒ `trace/core-keyset-guard.ts` 的跨界钉当场红)。 */
+export interface AbsentMemoryObservation {
+    readonly state: "absent";
+    readonly reason: MemoryObservationAbsentReason;
+}
+/** 一条已结腿的记忆观测 —— 四态闭集:引擎铸的三态原样(`mounted` / `memoryless` / `none`)∪ 空观测({@link AbsentMemoryObservation})。消费方按 `state` 穷举分支。 */
+export type LegMemoryObservation = EffectiveMemoryScopes | AbsentMemoryObservation;
+/**
+ * 「这个会话**最近一条已结腿**与它的记忆观测」的窄读面(run 店的 `latestMemoryObservationForSession` 的回值)—— 会话记忆同步触发口
+ * (`POST /v1/sessions/:id/memory/sync`)的**会话读集**只读这一只:读集 = 最近一条已结腿结果里引擎铸的观测(引擎一处铸、随 run 行持久;路由不重铸 spec)。
+ *
+ * 一条规则,三只实现同答:
+ *  · 已结 = {@link isTerminalRunStatus}(成功 / 非成功终局;在飞与停在门上的腿还占着会话的认领,不算;读不懂的词同向保守判「未结」)。两孪生调这只谓词;
+ *    SQL 两方言按本文件的惯例写字面词集 `status IN ('completed','failed','blocked')`,与谓词的同源由 `test/source-hygiene-gate.test.ts` 的方言对 parity 门钉;
+ *    取最近一条(排序口径与 {@link LatestRunRef} 逐字同一句:`created_at DESC, task_id DESC`);
+ *  · `observation` = 那一条腿的观测,**恒在场**,四态之一({@link LegMemoryObservation}):结果里有引擎的观测 ⇒ 原样;没有 ⇒ 空观测记号,因由说记录里有什么
+ *    ({@link MemoryObservationAbsentReason})。**不往更早的腿找**:读集是「最近一条已结腿」的,不是「最近一条有观测的腿」的 —— 空观测是那一条的值,不是去找下一条的信号。
+ * 空观测**不落盘**:它是行上已有事实(结果列、结果里那一键的缺席)的一只纯函数,铸在读口({@link settledLegObservationOf},三店共用);落一份 = 第二真源
+ * (与引擎「缺席 ⇔ prepare 没走完」那条律并存、两份要对得上),且终局写口二十余处、收割器整行写空结果的 SQL 两方言语句与存量行都得各补一份。
+ * 结果列读不出 ⇒ 抛(与 `getRun` 同一个失败方向:不把一条结了的腿当成没有结果)。
+ */
+export interface SettledLegMemoryObservation {
+    readonly taskId: string;
+    readonly observation: LegMemoryObservation;
+}
+/** {@link SettledLegMemoryObservation} 的**唯一铸点**(三只实现共用):一条已结腿的结果 → 读口的回值(空观测记号只在这里铸)。 */
+export declare function settledLegObservationOf(taskId: string, result: PersistedTaskResult | null): SettledLegMemoryObservation;
+/**
+ * run 店账本的一条事件 —— 三只孪生的 `getEvents` 都交出写口收下的那一形(按 seq 升序、每读一份新拷贝)。存形是孪生的私事、读者看不见:
+ * File 孪生把 `wiring_manifest` 行的容器段按会话存成块(`<root>/run-blobs/<会话>.jsonl`,律与唯一编解码 = `wiring-section-codec.ts`),行里只留引用,
+ * 读口装回整帧;装不回的那一帧不交出(F 类留痕),绝不交出缺段的清单。SQL / Memory 孪生整帧存。
+ */
 export interface RunEvent {
     seq: number;
     type: string;

package/dist/plugins/store-contracts.js

@@ -56,4 +56,10 @@ export function sessionTempoOfRunStatus(lastStatus) {
 export function runProvenElsewhere(run, thisInstanceId) {
     return typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId;
 }
+export const MEMORY_OBSERVATION_ABSENT_REASONS = ["run_result_missing", "run_result_unobserved"];
+export function settledLegObservationOf(taskId, result) {
+    if (result === null)
+        return { taskId, observation: { state: "absent", reason: "run_result_missing" } };
+    return { taskId, observation: result.effectiveMemoryScopes ?? { state: "absent", reason: "run_result_unobserved" } };
+}
 //# sourceMappingURL=store-contracts.js.map

package/dist/plugins/task-attachment-store.d.ts

@@ -21,12 +21,16 @@
  *  - 隔离键排序规则:TiDB 表级 utf8mb4_bin / PG owner 列 COLLATE "C"(bga F2 同姿,'=' 字节等价)。
  *    owner 值恒为 server 端从凭据推导(非用户输入),PAD SPACE 近撞面不可达,VARBINARY 键列不必要。
  *  - 布尔列:无(遵 1.287.0 归一约定,若未来加,PG 用 SMALLINT 0/1)。
- *  - 绑定:`bind` 把行钉到 sessionId(重复绑定=改绑,同 owner 内 last-wins;同 session 多 task 共享
- *    自然成立——listBySession 是物化输入)。未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
+ *  - 绑定:`bind` 把行钉到 sessionId,两条律都在店里、都不是先读后写(契约见 {@link TaskAttachmentStore.bind}):
+ *    **一经绑定不再改绑**(UPDATE 谓词只放行未绑的行与已绑本会话的行,行级原子;同会话重绑 —— 首交重试、续跑腿重放存量体 —— 不改 `bound_at_ms`);
+ *    **一只会话一只种子**(未绑的项目包只在这只会话还没有项目包时绑上:SQL 两方言是表上的唯一键 —— 种子键 `seed_session_id`(项目包行的会话,由引擎从 `mime` 与 `session_id` 推导)上的 `uq_att_seed`,第二只项目包的绑定被引擎拒;进程内的店是一段不被打断的判与改:内存店同一段同步,local 店的变更口同排一条串行段、bind 判在副本上、落成的行才合回)。
+ *    同 session 多 task 共享自然成立(listBySession 是物化输入)。
+ *    未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
  */
 import { z } from "zod";
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
+import type { Pool as PgPool } from "pg";
 import { type IndexSpec } from "./ensure-index.js";
 /**
  * 一条附件 meta 的**形属主**(整仓唯一那份键集)。
@@ -55,8 +59,14 @@ export interface TaskAttachmentStore {
     /** meta(不带 bytes);owner 不匹配/不存在 → null(无 oracle)。 */
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
-    /** 把 ids 钉到 sessionId(owner 门在 WHERE);返回真绑到的行数——调用方以 count===ids.length 判全成。 */
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    /**
+     * 把 ids(请求序)钉到 sessionId。绑定的两条律都在店里判,判与写对这只会话的其它绑定是原子的(不是先读后写):
+     *  · **一经绑定不再改绑** —— 已绑别的会话的行 ⇒ `bound_elsewhere`(行不动);已绑本会话的行命中、不改 `boundAtMs`;
+     *  · **一只会话一只种子** —— 一只**未绑的项目包**只在这只会话此刻没有项目包时绑上,否则 ⇒ `bundle_seed_fixed`(同一次调用里请求序靠前的那只先占);
+     *    两次并发绑定各带一只新项目包到同一会话 ⇒ 恰一只绑上。
+     * 属主门在店里(owner 不匹配 / 不存在的 id 两边都不出现,无 oracle)。`bound` 按请求序、不重复。
+     */
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     /** 物化输入(env 建立时)——按 session 单键查(绑定时已 owner 验过;session uuid 不可枚举)。 */
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
@@ -89,22 +99,108 @@ export interface AttachmentBytesStore {
  *  (created_at_ms, id)分配 `attachments/<name>`;同名撞车时后者前缀 id 头 8 位。名字在上传时已
  *  消毒为安全 basename([A-Za-z0-9._-]),拼接后仍是安全相对路径。 */
 export declare function materializedRelPaths(atts: TaskAttachmentRecord[]): Map<string, string>;
-/** 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → throw(mapTo400));
- *  resume 腿降级(warn+跳过——4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。
- *  notice 路径从**绑定后的全 session 集**推导(与物化共用 materializedRelPaths),只罗列本次引用的文件。 */
+/**
+ * 提交体 `attachmentIds` 绑定时的拒(闭集;码与状态的唯一映射 = {@link attachmentBindRefusalAnswer})。
+ *  · `bound_elsewhere` —— 这只附件已绑在别的会话上(一经绑定不再改绑;每个会话各上传一次);
+ *  · `bundle_lane_not_isolated` —— 项目包只交给 OS 隔离边界内的车道(`laneIsolated`),这条腿的车道不是;
+ *  · `bundle_seed_fixed` —— 本会话的种子已定(最早绑定的那只项目包),第二只项目包不收。
+ */
+export type AttachmentBindRefusal = {
+    readonly kind: "bound_elsewhere";
+    readonly id: string;
+} | {
+    readonly kind: "bundle_lane_not_isolated";
+    readonly id: string;
+    readonly lane: string;
+} | {
+    readonly kind: "bundle_seed_fixed";
+    readonly id: string;
+};
+/** 店在一次绑定里答的拒(闭集的子集:车道那一只是提交侧对这条腿的判,店不判)。 */
+export type AttachmentStoreBindRefusal = Extract<AttachmentBindRefusal, {
+    readonly kind: "bound_elsewhere" | "bundle_seed_fixed";
+}>;
+/** 一次 {@link TaskAttachmentStore.bind} 的答:此刻绑在这只会话上的 id(请求序)与店拒掉的 id;两边都不在的 id = 不在 / 他人的。 */
+export interface AttachmentStoreBindOutcome {
+    readonly bound: readonly string[];
+    readonly refused: readonly AttachmentStoreBindRefusal[];
+}
+/**
+ * 进程内的店(local 文件店、测试内存店)的绑定律 —— {@link TaskAttachmentStore.bind} 那一条律在进程内的**唯一**写法:判与改在**同一段同步**里
+ * (本函数不 await),于是调用方只要不在本函数前后放开(内存店:整条 `bind` 就是这一段;local 店:`bind` 与店的其它变更口同排一条串行段),
+ * 同一进程里两次并发绑定不可能都读到「这只会话还没有种子」(local 契约本就是单进程,`local-task-attachment-store.ts` 头注)。
+ * 改的是传进来的 `rows` 里的行对象本身 —— 内存店传自己的索引;需要落盘的店传**副本**,只把落盘落成的那些 `claimed` 行合回自己的索引
+ * (`claimed` = 这一次新绑上的行,即副本里被改的那些行对象;索引只反映盘上已有的)。
+ */
+export declare function bindRowsInProcess(rows: ReadonlyMap<string, TaskAttachmentRecord>, owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): {
+    readonly outcome: AttachmentStoreBindOutcome;
+    readonly claimed: readonly TaskAttachmentRecord[];
+};
+/** 绑定拒的码 → 状态:唯一属主表(一个码在本服务上只有一个状态;`<名>_HTTP_STATUS` 是本仓这类表的名形,码目录门按名形读它的键)。 */
+export declare const ATTACHMENT_BIND_HTTP_STATUS: {
+    readonly "attachment.bound_elsewhere": 409;
+    readonly "attachment.bundle_lane_not_isolated": 409;
+    readonly "attachment.bundle_seed_fixed": 409;
+};
+export type AttachmentBindCode = keyof typeof ATTACHMENT_BIND_HTTP_STATUS;
+/** 一只绑定拒在 wire 上的答(状态取自 {@link ATTACHMENT_BIND_HTTP_STATUS} + 码 + 句 + 体键);穷举 switch —— 闭集多一种而这里没跟 ⇒ 编译红。 */
+export declare function attachmentBindRefusalAnswer(r: AttachmentBindRefusal): {
+    readonly status: number;
+    readonly errorCode: AttachmentBindCode;
+    readonly message: string;
+    readonly extra: Record<string, string>;
+};
+/** 会话里**附件**那一类的行(项目包行不在其中)—— 告知的路径分配与物化读的唯一过滤读口:过滤在路径分配之前(种子行不挤动附件的撞名前缀)。 */
+export declare function listAttachmentsBySession(store: TaskAttachmentStore, sessionId: string): Promise<TaskAttachmentRecord[]>;
+/**
+ * 会话种子的读口:最早绑定的项目包行 + 它的字节,字节**必核**行上的 `sha256` 与 `sizeBytes`(种子身份 = 上传那一刻的摘要;local 店读侧不核,这里核)。
+ * 三种答:没有种子 ⇒ `undefined`;种子在、字节在、摘要对 ⇒ `{ record, bytes }`;店里的定局坏了(行在、字节没了 / 摘要不符)⇒ `{ record, broken }`。
+ * 店读本身抛(连接断、超时)⇒ 原样抛:那是一时的失败,不是这只会话的定答 —— 调用方据此分「换一次恢复点重读」与「这只环境此后同一个拒」。
+ */
+export declare function seedOfSession(store: TaskAttachmentStore, sessionId: string): Promise<{
+    readonly record: TaskAttachmentRecord;
+    readonly bytes: Uint8Array;
+} | {
+    readonly record: TaskAttachmentRecord;
+    readonly broken: string;
+} | undefined>;
+/**
+ * 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → `onMissing` throw;拒 → `onRefused` throw);
+ * resume 腿降级(warn+跳过 —— 4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。判序:
+ *  ① 行在不在(属主门);② 已绑别的会话 ⇒ `bound_elsewhere`;③ 项目包 × 车道不隔离 ⇒ `bundle_lane_not_isolated`;
+ *  ④ 本次提交体里第二只新项目包 ⇒ `bundle_seed_fixed`(只看提交体本身,不读店);
+ *  ⑤ 绑定 —— 「本会话已有种子」与「不改绑」两条律只在店里判({@link TaskAttachmentStore.bind},判与写原子:并发的两次提交在那里分胜负,这里不先读):
+ *    提交体那只新项目包先**单独**绑,店拒了它 ⇒ `onRefused` 在体里其余 id 绑上之前就到(新提交腿上,店拒了种子候选的提交,体里其余 id 一只都不绑;读与绑之间才被别的会话抢走的附件不在此列 —— 先绑上的不回滚,请求仍 409);其余 id 随后一次绑。
+ * notice 只罗列本次引用的**附件**(项目包是工作区本身,不进告知),路径从绑定后的全会话附件集推导(与物化共用 {@link materializedRelPaths})。
+ */
 export declare function bindAttachmentsForTask(opts: {
     store: TaskAttachmentStore;
     owner: string;
     ids: string[];
     sessionId: string;
+    /** 这条腿的执行车道(执行上下文那一读)与它是否在 OS 隔离边界内(`laneIsolated` 那一判,调用方判一次交进来)。 */
+    lane: {
+        readonly word: string;
+        readonly isolated: boolean;
+    };
     leg: "fresh" | "resume";
     nowMs: number;
     onMissing: (id: string) => void | never;
+    onRefused: (refusal: AttachmentBindRefusal) => void | never;
 }): Promise<{
     notice: string | undefined;
 }>;
-/** 半场③(env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
- *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建沙箱/resume 重写同路径同字节。 */
+/** 会话绑定的附件按工作区收它们的样子:行 + 物化相对路径(与 objective 告知同一份推导 {@link materializedRelPaths})。
+ *  两只物化座(没有恢复点的车道 = 执行环境建立时 {@link materializeAttachmentsInto};隔离车道 = 恢复点的填充 `workspace-fill.ts`)读的是这一份。 */
+export interface AttachmentPlacement {
+    readonly record: TaskAttachmentRecord;
+    readonly relPath: string;
+}
+export declare function attachmentPlacementsOf(store: TaskAttachmentStore, sessionId: string): Promise<AttachmentPlacement[]>;
+/** 一只要放进工作区的附件的字节;读不到 ⇒ 抛(fail-loud:objective 已宣告它在场)。 */
+export declare function attachmentBytesOf(store: TaskAttachmentStore, rec: TaskAttachmentRecord): Promise<Uint8Array>;
+/** 半场③(没有恢复点的车道:env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
+ *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建 env / resume 重写同路径同字节。 */
 export declare function materializeAttachmentsInto(env: {
     createDir(path: string, options?: {
         recursive?: boolean;
@@ -129,10 +225,10 @@ export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void
 /** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgTaskAttachmentSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const TASK_ATTACHMENT_INDEXES: readonly IndexSpec[];
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
-/** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     private readonly pool;
     private readonly bytes;
+    private readonly db;
     constructor(pool: Pool, bytes: AttachmentBytesStore);
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
@@ -143,7 +239,7 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
      *  失败只吞不抛——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
      *  经 API 不可达,彻底清收敛记 follow-up。 */
     private deleteBytesIfUnreferenced;
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
@@ -160,16 +256,18 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     private filterStillOrphan;
 }
 export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
-    private readonly q;
     private readonly bytes;
-    constructor(q: PgQueryFn, bytes: AttachmentBytesStore);
+    private readonly db;
+    private readonly q;
+    /** 收池:绑定({@link bindOnSql})走与 TiDB 孪生同一只驱动形({@link pgDriver})。 */
+    constructor(pool: PgPool, bytes: AttachmentBytesStore);
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
     }): Promise<void>;
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     private deleteBytesIfUnreferenced;
-    bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;