@sema-agent/server 7.151.0 → 7.152.0

package/dist/plugins/session-blob-namespace.js

@@ -0,0 +1,116 @@
+import { presignS3Url } from "./s3-presign.js";
+import { createEgressFetch } from "../egress-redirect.js";
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { SESSION_BLOB_CLAIM_KEY } from "../object-store-buckets.js";
+import { sessionBlobKeyPrefixOf } from "./blob-backend.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+import { SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS } from "./snapshot-bucket-presence.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+export const SESSION_BLOB_CLAIM_SETTLE_MS = 1_000;
+export class SessionBlobNamespaceRefusedError extends StoreBootRefusalError {
+    constructor(message) {
+        super(message);
+        this.name = "SessionBlobNamespaceRefusedError";
+    }
+}
+function namespaceText(store) {
+    const prefix = store.keyPrefix === undefined || store.keyPrefix === "" ? "unset" : JSON.stringify(store.keyPrefix);
+    return `bucket "${store.bucket}" under SESSION_SNAPSHOT_PREFIX (${prefix}) at MINIO_ENDPOINT → ${buildDisplaySafeUrl(store.endpoint)}`;
+}
+function shownToken(body) {
+    const t = body.trim();
+    return /^[A-Za-z0-9._-]{1,64}$/.test(t) ? t : `${JSON.stringify(t.slice(0, 64))} (not a claim token)`;
+}
+export function buildSessionBlobNamespaceForeignText(store, holder, mine) {
+    const claim = `${store.bucket}/${sessionBlobKeyPrefixOf(store, "claim")}`;
+    return (`The session blob namespace — ${namespaceText(store)} — belongs to another database: its claim object ${claim} names ${shownToken(holder)}, this database is ${mine}. ` +
+        `Attachments and file history keep their bytes there under content addresses, and each engine deletes the ones its own database no longer references, so two databases on one namespace delete each other's bytes. ` +
+        `Next: give this engine its own SESSION_SNAPSHOT_PREFIX (to keep the bytes this database already references, copy the objects under the current prefix to the new one first); ` +
+        `if the database named in the claim no longer uses this bucket, delete ${claim} and start again.`);
+}
+export function buildSessionBlobNamespaceUnprovenText(store, detail) {
+    const claim = `${store.bucket}/${sessionBlobKeyPrefixOf(store, "claim")}`;
+    return (`Could not prove that the session blob namespace — ${namespaceText(store)} — belongs to this database (${detail}): without that proof the attachment and file-history sweeps could delete another database's bytes, so nothing there is deleted until it is proven. ` +
+        `Next: check that MINIO_ENDPOINT answers and that the engine's key may GetObject and PutObject ${claim}.`);
+}
+class ClaimUnproven extends Error {
+    detail;
+    constructor(detail) {
+        super(detail);
+        this.detail = detail;
+    }
+}
+export function createSessionBlobNamespace(store, opts = {}) {
+    const egressFetch = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", opts.fetchImpl);
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const key = sessionBlobKeyPrefixOf(store, "claim");
+    let opened;
+    let inFlight;
+    const url = (op, method) => presignS3Url({ op, endpoint: store.endpoint, bucket: store.bucket, key, method, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}) });
+    const readClaim = async () => {
+        const res = await egressFetch(url("blob-claim/claim:GET", "GET"), { method: "GET", signal: AbortSignal.timeout(SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS) });
+        if (res.status === 404)
+            return undefined;
+        if (!res.ok)
+            throw new ClaimUnproven(`claim read answered HTTP ${res.status}`);
+        return (await res.text()).trim();
+    };
+    const attempt = async (mine) => {
+        try {
+            let holder = await readClaim();
+            if (holder === undefined) {
+                const res = await egressFetch(url("blob-claim/claim:PUT", "PUT"), { method: "PUT", body: mine, headers: { "if-none-match": "*" }, signal: AbortSignal.timeout(SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS) });
+                if (!res.ok && res.status !== 412)
+                    return { state: "unproven", detail: `claim write answered HTTP ${res.status}` };
+                await sleep(SESSION_BLOB_CLAIM_SETTLE_MS);
+                holder = await readClaim();
+                if (holder === undefined)
+                    return { state: "unproven", detail: "the claim just written does not read back" };
+            }
+            return holder === mine ? { state: "mine" } : { state: "foreign", holder };
+        }
+        catch (err) {
+            return { state: "unproven", detail: err instanceof ClaimUnproven ? err.detail : `claim request failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    };
+    const claimOnce = (token) => (inFlight ??= attempt(token).finally(() => {
+        inFlight = undefined;
+    }));
+    return {
+        store,
+        claimOnce,
+        bind(token) {
+            opened = token;
+        },
+        async establish() {
+            const token = opened;
+            if (token === undefined)
+                throw new SessionBlobNamespaceRefusedError(`the session blob namespace — ${namespaceText(store)} — has no claim token bound (StoreBackend.ensureSchema() binds it) — refusing to open`);
+            const r = await claimOnce(token);
+            switch (r.state) {
+                case "mine":
+                    return;
+                case "foreign":
+                    throw new SessionBlobNamespaceRefusedError(buildSessionBlobNamespaceForeignText(store, r.holder, token));
+                case "unproven":
+                    recordFailOpen("server.session-blob-namespace.claim-unproven", `bucket=${store.bucket} prefix=${store.keyPrefix === undefined || store.keyPrefix === "" ? "unset" : JSON.stringify(store.keyPrefix)} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${r.detail}`);
+                    return;
+                default: {
+                    const unknown = r;
+                    throw new Error(`unknown claim reading ${JSON.stringify(unknown)}`);
+                }
+            }
+        },
+        async assertOwned() {
+            if (opened === undefined)
+                throw new Error(`refusing to delete: the session blob namespace — ${namespaceText(store)} — has no claim token (the store was not opened: StoreBackend.ensureSchema() binds this database's)`);
+            const r = await claimOnce(opened);
+            if (r.state === "mine")
+                return;
+            throw new Error(r.state === "foreign"
+                ? `refusing to delete: ${buildSessionBlobNamespaceForeignText(store, r.holder, opened)}`
+                : `refusing to delete: ${buildSessionBlobNamespaceUnprovenText(store, r.detail)}`);
+        },
+    };
+}
+//# sourceMappingURL=session-blob-namespace.js.map

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -9,7 +9,9 @@
  * 被读成「这个空间头一回」,从空目录起;run 末的保存虽失败,报的却是一条不点名桶的 curl 404,没有一行说「桶没建」。
  *
  * ## 形(一条规则,不加特例)
- *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
+ *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`,列举前缀 = 角色行的 `probePrefix`:会话桶 = 退役快照纪元的根 `{legacyBlobRoot}`,
+ *    工作区桶 = 适配器写入的那只前缀 `<WORKSPACE_SNAPSHOT_PREFIX>/`,与适配器同一读 `workspaceSnapshotPrefixOf` —— 按前缀授列举的最小权限凭据对探针与对适配器同答;
+ *    两行各是对象存储动作表的一行 `boot-probe/*:LIST`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
  *    NoSuchBucket 的 404)⇒ **不拒**、照常起服,走登记过的 F 类兜底口 `recordFailOpen("server.snapshot-bucket.presence-unproven")`(计数 + 探针行 + 记录器的一次性 warn;
  *    三问写在该 tag 的 note 里)—— 拒启要有证据,没有证据只留痕;
  *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
@@ -36,6 +38,16 @@ export declare const SNAPSHOT_BUCKET_ROLES: {
         readonly defaultName: "session-snapshots";
         readonly consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)";
         readonly createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment";
+        readonly probeOp: "boot-probe/session:LIST";
+        readonly probePrefix: (store: {
+            endpoint: string;
+            bucket: string;
+            accessKey: string;
+            secretKey: string;
+            region?: string;
+            keyPrefix?: string;
+            presignTtlSec?: number;
+        }) => string;
     };
     readonly workspace: {
         readonly noun: "workspace snapshot bucket";
@@ -43,9 +55,20 @@ export declare const SNAPSHOT_BUCKET_ROLES: {
         readonly defaultName: "workspaces";
         readonly consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing";
         readonly createHint: "";
+        readonly probeOp: "boot-probe/workspace:LIST";
+        readonly probePrefix: (store: {
+            endpoint: string;
+            bucket: string;
+            accessKey: string;
+            secretKey: string;
+            region?: string;
+            keyPrefix?: string;
+            presignTtlSec?: number;
+        }) => string;
     };
 };
-/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
+/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。
+ *  会话 blob 命名空间的认领请求(`session-blob-namespace.ts`,起服的那一次与每次删除前的重读)读同一只数:起服对快照桶的探针只有这一个上界。 */
 export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
 /** 缺桶的拒启句(唯一铸点)。 */
 /** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */

package/dist/plugins/snapshot-bucket-presence.js

@@ -1,5 +1,6 @@
 import { buildDisplaySafeUrl } from "../trace/redact.js";
-import { MinioBlobBackend } from "./blob-backend.js";
+import { MinioBlobBackend, sessionBlobKeyPrefixOf } from "./blob-backend.js";
+import { workspaceSnapshotPrefixOf } from "../workspace-space.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
@@ -10,6 +11,8 @@ export const SNAPSHOT_BUCKET_ROLES = {
         defaultName: SESSION_SNAPSHOT_BUCKET_DEFAULT,
         consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)",
         createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment",
+        probeOp: "boot-probe/session:LIST",
+        probePrefix: (store) => sessionBlobKeyPrefixOf(store, "legacy-blobs"),
     },
     workspace: {
         noun: "workspace snapshot bucket",
@@ -17,6 +20,8 @@ export const SNAPSHOT_BUCKET_ROLES = {
         defaultName: WORKSPACE_SNAPSHOT_BUCKET_DEFAULT,
         consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing",
         createHint: "",
+        probeOp: "boot-probe/workspace:LIST",
+        probePrefix: (store) => `${workspaceSnapshotPrefixOf(store)}/`,
     },
 };
 export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
@@ -34,7 +39,8 @@ export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs, role = "s
 }
 export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
 export async function ensureSnapshotBucket(store, waitMs, logger, clock, role = "session") {
-    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
+    const roleRow = SNAPSHOT_BUCKET_ROLES[role];
+    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), keyPrefix: roleRow.probePrefix(store), ops: { list: roleRow.probeOp } });
     let verdict;
     try {
         verdict = await openWithinWait(async () => {

package/dist/plugins/sql-json-column.d.ts

@@ -347,7 +347,7 @@ export declare const readNonNullJsonValueColumn: JsonColumnReader<unknown>;
  * **一只 JSON 数组**的承载形读者(内容判据归各列自己的既有属主,这里只判承载形)。
  *
  * 🔴 为什么在属主里而不是各店各写一遍([ref] 车③a 把车② 的店内私有形上收):今天有三个消费方
- * (checkpoint 的 `rule_suggestions` / `pending_steer_queue`、memory-engine 的 `embedding`),判据逐字
+ * (checkpoint 的 `pending_steer_queue`、image-index 的 `bands`、memory-engine 的 `embedding`),判据逐字
  * 相同,而「这一格是不是一只数组」恰好是坏体四形的落点 —— 三份拷贝迟早有一份忘了判 `null` 字面。
  */
 export declare const readJsonArrayColumn: JsonColumnReader<unknown[]>;

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

@@ -27,6 +27,7 @@ import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-stor
 import { SqlSessionPolicyStore } from "../stores-sql/session-policy-store-sql.js";
 import { SqlFileHistoryStore } from "../stores-sql/file-history-store-sql.js";
 import { type LandedAttendantSeat } from "./landed-attendants.js";
+import { type SessionBlobNamespace } from "./session-blob-namespace.js";
 import type { ServiceConfig } from "../config-types.js";
 import { TiDBRunStore, PgRunStore } from "./run-store-sql.js";
 import { TiDBCheckpointStore, PgCheckpointStore } from "../stores-sql/checkpoint-store-sql.js";
@@ -112,9 +113,32 @@ export type SqlBlobPutResult = {
 export interface ServiceBlobExchange extends FileHistoryBlobExchange {
     put(hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
 }
+/**
+ * 一次会话同步推送 / 拉取**落在哪一格**(落点):会话 id + 落点属主格 + 门读时这只 id 有没有住客。路由在门判之后经 `landingOf`(`http/routes/session-sync.ts`)铸一次,
+ * 导入租约、blob 授予、blob 可见性三处读同一只;店不解释属主(只按字节存比,无主格记域键 `""`)。
+ *  · `occupied` = 门读时这只 id 被占着(活行 ∪ 在删行,「被占着」的唯一读法)。只有被占着的 id,它的历史图才是来历:空闲 id 上残留的图(删后残留 / 迟到的重放落下的)
+ *    不是任何一位调用方持有过字节的证明,所以空闲落点的可见集只读授予。
+ */
+export interface SyncLanding {
+    readonly sessionId: string;
+    readonly owner: string | null;
+    readonly occupied: boolean;
+}
+/**
+ * blob 的**按落点来历**面(SQL 两孪生有;与 {@link ServiceBlobExchange} 并列,不塞进 core 的交换组 —— core 判官只交回组的三员)。律:一枚 blob 对一个落点可见
+ * ⇔ (落点被占着 ∧ 这只会话的图引用它) ∨ 这个落点自己上传过它(授予),且字节在场;字节仍全局去重一份,可见性另表 —— 两个事实两张表。
+ *  · `putAt`:先核内容地址 → 再写字节(交换组同一写路径)→ **字节写成才**写授予(`granted_at = now`,单调)。答形 = {@link SqlBlobPutResult}(413 / 400 / 502 三臂不变);授予写失败 ⇒ 写失败臂。
+ *  · `visibleAt`:`hashes` 里对这个落点可见的那几枚。先算候选(图项 ∪ 授予项)、只对候选问字节在不在 —— 耗时只随这个落点自己的状态变,不随别人存过什么变。
+ */
+export interface ServiceBlobLanding {
+    putAt(landing: SyncLanding, hash: string, bytes: Uint8Array): Promise<SqlBlobPutResult>;
+    visibleAt(landing: SyncLanding, hashes: readonly string[]): Promise<ReadonlySet<string>>;
+}
 export type ServiceFileHistoryStore = FileHistoryStore & {
     /** The blob exchange (SQL twins only; core's local File store carries none). Narrowed per {@link ServiceBlobExchange}. */
     readonly blobExchange?: ServiceBlobExchange;
+    /** The per-landing provenance face over the same blob domain (SQL twins only) — see {@link ServiceBlobLanding}. The sync routes read blobs only through it. */
+    readonly blobLanding?: ServiceBlobLanding;
     /** 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>;
@@ -225,8 +249,8 @@ export interface StoreBackend {
      *  (它承诺的是「稍后还能批、崩了行还在」)。机器钉 = `wiring-governance-operator.test.ts` 的
      *  「三腿 approvalAsk 全持久」格。
      *
-     *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 协调器拿到 undefined askStore ⇒ 车2 的
-     *  D1 逐字现行为(store 缺席 = 现行 `tool_approval` 活卡腿一字不变)。 */
+     *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 呈卡协议不上场 ⇒ 起服不构造审批协调器(没有「无账协调器」这一形,
+     *  `boot/coordinators.ts`)。 */
     approvalAsk(): ApprovalAskStoreType;
     /**
      * [ref] 车二(core 5.18.0 [ref] + 5.22.0 [ref]):**持久化权限规则店**(「不再询问」车道)
@@ -303,6 +327,10 @@ export interface StoreBackend {
      *  epoch is gone (its manifest index table retired with it), so EVERY row in that domain is an orphan and its
      *  BYTES (incl. MinIO objects) would otherwise outlive the epoch forever. SQL backends only; reaper-driven. */
     legacySnapshotBlobSweep?(): Promise<number>;
+    /** The session blob namespace this backend's database holds (`session-blob-namespace.ts`): `ensureSchema()` proves it (another database's ⇒ refuse to open),
+     *  and every session blob port of this deployment is built from it (file history and the retired epoch here, attachments at boot). SQL backends with object
+     *  storage configured; absent otherwise (no object storage, or the local backend — its bytes are on its own disk). */
+    sessionBlobNamespace?(): SessionBlobNamespace | undefined;
     /** 🔴 **一次性迁移** —— 落在已写进库里的字节上的退役,升一次级改完、兼容臂当场删干净(硬 breaking 纪律:持久数据面 =
      *  响亮拒 + 一次性迁移,窗过即删,永不长期双读)。逐条语义、幂等与拒启臂见该模块头注。
      *
@@ -449,11 +477,23 @@ export interface StoreBackend {
     fileUsageWindowStore?(): UsageWindowStore;
     /** **local 后端专有**:构造时交给两半店(会话店顶层、检查点店)的那一份声明(唯一读者 `localStoreDeclarationOf`)—— 装配值从这里读回,不重算。SQL 后端省略。 */
     localStoreDeclaration?(): LocalStoreDeclaration;
+    /**
+     * **本进程此刻持锁独占的物理数据根**(正读数;本机控制 socket 开不开口只读它 —— `control-socket.ts` 的前提律):打开成功的 local 后端 ⇒ 引擎 File 后端取锁的那只根
+     * (绝对物理路径,`dataDirLayout.physicalRoot` 同一只),`close()` 之后 ⇒ `undefined`;打开那一刻被拒的 local 后端 ⇒ `undefined`(它的 `kind` 也是 `"local"`,所以判「独占」不读 `kind`)。
+     * SQL 后端省略(省略 = 不独占任何数据根,同 `undefined`)。
+     */
+    exclusiveDataRoot?(): string | undefined;
     /**
      * 会话店活引用判的 workflow 那一腿(会话种类的老化;`local-session-live-reference.ts`):本后端的会话店读不到 workflow run 店时(local:那只店在 boot 第 6 段才铸),
      * 第 6 段把这台部署的 workflow run 店交过来(不起 workflow ⇒ `"none"`);绑一次。SQL 两孪生不实现(它们的判是一句 SQL,读 `workflow_run` 表)。
      */
     bindWorkflowRunReader?(reader: LocalWorkflowRunsReader | "none"): void;
+    /**
+     * 「不再询问」规则 project root 的铸卡快照读法(跑这条 run 的副本的会话 cwd 登记;与活卡铸点同一只函数)—— 第 6 段绑一次,本后端的 checkpoint 店写口 `put`
+     * 在停驻那一刻读它落快照(SQL 列 `card_scope_root` / local 快照索引)。未绑 / 不实现(嵌入方的替身后端)⇒ 不可知 ⇒ 不落快照(兑付答 `scope-unresolved`:只会拒)。
+     * 本仓三只后端都实现;形同 {@link bindWorkflowRunReader} 的晚绑。
+     */
+    bindCardScopeRoot?(read: (sessionId: string) => string | undefined): void;
 }
 /**
  * 托管留存执行器的**组合**:引擎座表那一半(`SqlRetentionStore`,事务属主)+ 部署那一半(hold / 审计 / 认领判 / 十三张部署表,
@@ -554,6 +594,8 @@ export interface LocalStoreBackend extends StoreBackend {
     localStoreDeclaration(): LocalStoreDeclaration;
     /** local 后端恒有(会话店活引用判的 workflow 晚绑座;接口上可选的那一口在这里必在)。 */
     bindWorkflowRunReader(reader: LocalWorkflowRunsReader | "none"): void;
+    /** local 后端恒有这一口(接口上可选的那一口在这里必在);答 `undefined` 的是拒启的那一只与关过的那一只(见 {@link StoreBackend.exclusiveDataRoot})。 */
+    exclusiveDataRoot(): string | undefined;
 }
 /** 引擎 File 后端上会话店之外、本仓没有自己一份口的店(run-local 的 Runner 接它们;工具结果 / 用量窗 / 会话规则走既有的 `toolResult()` / `fileUsageWindowStore()` / `sessionPolicy()` 口)。 */
 export type LocalEngineFileStores = Pick<FileStorageBackend, "checkpointStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore">;

package/dist/plugins/store-backend.js

@@ -44,10 +44,12 @@ import { TiDBResumeAnchorStore, PgResumeAnchorStore } from "./resume-anchor-stor
 import { TiDBSessionPolicyStore, PgSessionPolicyStore, SqlSessionPolicyStore } from "../stores-sql/session-policy-store-sql.js";
 import { SQL_SESSION_ROOT_SEAT } from "./session-row-sql.js";
 import { TiDBWorkflowJournalStore, PgWorkflowJournalStore, SqlWorkflowJournalStore } from "../stores-sql/workflow-journal-store-sql.js";
-import { TiDBFileHistoryStore, PgFileHistoryStore, FILE_HISTORY_BLOB_KEY_PREFIX, SqlFileHistoryStore } from "../stores-sql/file-history-store-sql.js";
+import { TiDBFileHistoryStore, PgFileHistoryStore, SqlFileHistoryStore, SqlBlobExchange, SqlBlobLanding } from "../stores-sql/file-history-store-sql.js";
 import { createLocalLandedAttendantSeat, createSqlLandedAttendantSeat } from "./landed-attendants.js";
-import { SqlBlobIndex } from "../stores-sql/blob-index-sql.js";
-import { MinioBlobBackend } from "./blob-backend.js";
+import { SqlBlobIndex, blobGcCutoffAt } from "../stores-sql/blob-index-sql.js";
+import { createSessionBlobBackend } from "./blob-backend.js";
+import { createSessionBlobNamespace } from "./session-blob-namespace.js";
+import { ensureSessionBlobClaimToken } from "./session-blob-claim-token.js";
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { fileMemoryControlDirFor, memoryEngineRootFor } from "../memory-scope.js";
 import { createTidbPool, ensureSchema as ensureTidbSchema } from "./tidb-pool.js";
@@ -92,6 +94,7 @@ import { PgMailboxStore, TiDBMailboxStore } from "../stores-sql/mailbox-store-sq
 import { PgRosterStore, TiDBRosterStore } from "../stores-sql/roster-store-sql.js";
 import { TiDBSessionStorage } from "../stores-sql/tidb-session-storage.js";
 import { PgUsageWindowStore, TiDBUsageWindowStore } from "../stores-sql/usage-window-store-sql.js";
+import { createCardScopeRootSeat } from "./checkpoint-store-face.js";
 export function createRunStallWiring(config, observers) {
     const count = observers?.runStallVerdicts;
     return { windowMs: () => config.runStaleSec * 1000, onVerdicts: (landed) => count?.(landed) };
@@ -99,19 +102,10 @@ export function createRunStallWiring(config, observers) {
 export function workflowJournalOf(config, backend) {
     return config.selfOrchestrationEnabled && backend ? backend.workflowJournal() : undefined;
 }
-function fileHistoryOptions(config) {
-    const s = config.snapshotBlobStore;
-    const placement = s
+function fileHistoryOptions(config, namespace) {
+    const placement = namespace
         ? {
-            blobs: new MinioBlobBackend({
-                endpoint: s.endpoint,
-                bucket: s.bucket,
-                accessKey: s.accessKey,
-                secretKey: s.secretKey,
-                ...(s.region ? { region: s.region } : {}),
-                keyPrefix: `${s.keyPrefix ?? ""}${FILE_HISTORY_BLOB_KEY_PREFIX}`,
-                ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
-            }),
+            blobs: createSessionBlobBackend(namespace, "file-history"),
         }
         : {
             ...(config.snapshotBlobSqlMaxBytes !== undefined ? { blobSqlMaxBytes: config.snapshotBlobSqlMaxBytes } : {}),
@@ -119,35 +113,21 @@ function fileHistoryOptions(config) {
         };
     return { ...config.fileHistory, ...placement };
 }
-function legacyBlobIndex(config, dialect, pool) {
-    const s = config.snapshotBlobStore;
-    const bytes = s
-        ? new MinioBlobBackend({
-            endpoint: s.endpoint,
-            bucket: s.bucket,
-            accessKey: s.accessKey,
-            secretKey: s.secretKey,
-            ...(s.region ? { region: s.region } : {}),
-            ...(s.keyPrefix ? { keyPrefix: s.keyPrefix } : {}),
-            ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
-        })
-        : undefined;
+function legacyBlobIndex(config, dialect, pool, namespace) {
+    const bytes = namespace ? createSessionBlobBackend(namespace, "legacy-blobs") : undefined;
     return new SqlBlobIndex(dialect, pool, { table: "snapshot_blob", ...(bytes !== undefined ? { bytes } : {}), log: createLogger(config.logLevel) });
 }
-async function legacySweepImpl(config, dialect, pool) {
+async function legacySweepImpl(config, dialect, pool, namespace) {
     const sql = "SELECT blob_hash FROM snapshot_blob";
-    let orphans;
-    if (dialect === "mysql") {
-        const [rows] = await pool.query(sql);
-        orphans = rows.map((r) => String(r.blob_hash));
-    }
-    else {
+    const collect = async () => {
+        if (dialect === "mysql") {
+            const [rows] = await pool.query(sql);
+            return rows.map((r) => String(r.blob_hash));
+        }
         const r = await pool.query(sql);
-        orphans = r.rows.map((row) => row.blob_hash);
-    }
-    if (orphans.length === 0)
-        return 0;
-    return legacyBlobIndex(config, dialect, pool).sweep(orphans);
+        return r.rows.map((row) => row.blob_hash);
+    };
+    return legacyBlobIndex(config, dialect, pool, namespace).sweep(collect, blobGcCutoffAt(Date.now()));
 }
 export function createSqlRetentionCallHooks(db, opts, input) {
     const deployment = createRetentionDeploymentHooks(db.dialect, opts, input);
@@ -264,9 +244,16 @@ class TiDBBackend {
         this.config = config;
         this.observers = observers;
         this.onWarn = onWarn;
+        this.blobNamespaceInst = config.snapshotBlobStore ? createSessionBlobNamespace(config.snapshotBlobStore) : undefined;
+    }
+    async ensureSchema() {
+        await ensureTidbSchema(this.pool);
+        if (this.blobNamespaceInst)
+            this.blobNamespaceInst.bind(await ensureSessionBlobClaimToken(mysqlDriver(this.pool)));
     }
-    ensureSchema() { return ensureTidbSchema(this.pool); }
     close() { return this.pool.end(); }
+    sessionBlobNamespace() { return this.blobNamespaceInst; }
+    blobNamespaceInst;
     run() { return (this.runStoreInst ??= new TiDBRunStore(this.pool, createRunStallWiring(this.config, this.observers))); }
     runStoreInst;
     resumeAnchor() { return (this.resumeAnchorInst ??= new TiDBResumeAnchorStore(this.pool)); }
@@ -280,14 +267,14 @@ class TiDBBackend {
     userInputLedger() { return new TiDBUserInputLedgerStore(this.pool); }
     sessionPolicy() { return (this.sessionPolicyInst ??= new TiDBSessionPolicyStore(this.pool, SQL_SESSION_ROOT_SEAT, policyStoreLoggerOf(this.onWarn))); }
     sessionPolicyInst;
-    fileHistory() { return (this.fileHistoryInst ??= new TiDBFileHistoryStore(this.pool, fileHistoryOptions(this.config))); }
+    fileHistory() { return (this.fileHistoryInst ??= new TiDBFileHistoryStore(this.pool, fileHistoryOptions(this.config, this.sessionBlobNamespace()))); }
     fileHistoryInst;
     landedAttendants() { return (this.landedAttendantsInst ??= sqlLandedAttendantsOf(mysqlDriver(this.pool), this.fileHistory(), this.sessionPolicy())); }
     landedAttendantsInst;
     memoryOptOutGrant() { return new TiDBMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new TiDBSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
-    legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "mysql", this.pool); }
+    legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "mysql", this.pool, this.sessionBlobNamespace()); }
     runOneTimeMigrations() { return runSqlOneTimeMigrations("mysql", this.pool, buildSqlOneTimeMigrationInput(this.config)); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
     outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
@@ -298,7 +285,9 @@ class TiDBBackend {
     workflowParkDecisions(records) { return (this.parkDecisionsInst = decisionStoreBoundOnce(this.parkDecisionsInst, records, () => new SqlWorkflowParkDecisionStore(this.run(), sqlRecordFenceOf(records)))); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    cardScopeRootSeat = createCardScopeRootSeat();
+    bindCardScopeRoot(read) { this.cardScopeRootSeat.bind(read); }
+    checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep), cardScopeRoot: this.cardScopeRootSeat }); }
     checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new TiDBToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
@@ -318,13 +307,13 @@ class TiDBBackend {
     async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); }
 }
 sealStoreClass(TiDBBackend, "tidb-backend", {
-    ensureSchema: "boot", close: "boot", run: "exit", resumeAnchor: "exit", approvalExemption: "exit", approvalNonce: "exit", orgDeliveryQuota: "exit",
+    ensureSchema: "boot", close: "boot", sessionBlobNamespace: "exit", run: "exit", resumeAnchor: "exit", approvalExemption: "exit", approvalNonce: "exit", orgDeliveryQuota: "exit",
     approvalAsk: "exit", permissionRule: "exit", sendFileLedger: "exit", userInputLedger: "exit", sessionPolicy: "exit", fileHistory: "exit",
     memoryOptOutGrant: "exit", sessionCaptureRecords: "exit", legacySnapshotBlobSweep: "exit", runOneTimeMigrations: "boot", workflowJournal: "exit",
     outcomeSink: "exit", workflowRun: "exit", completionInbox: "exit", notifyJournal: "exit", workflowAgentSessionIndex: "exit", workflowParkDecisions: "exit",
     sharedMemoryStore: "exit", checkpoint: "exit", checkpointReadView: "exit", toolResult: "exit", imageIndex: "exit", imageBake: "exit", leaderRun: "exit",
     device: "exit", retention: "exit", sessionEraser: "exit", retentionLane: "exit", breaker: "exit", costQuota: "exit", rateLimiter: "exit", session: "exit",
-    adoptionLog: "exit", mysqlPool: "boot", pgPool: "boot", dbNowMs: "exit", landedAttendants: "exit",
+    adoptionLog: "exit", mysqlPool: "boot", pgPool: "boot", dbNowMs: "exit", landedAttendants: "exit", bindCardScopeRoot: "exit",
 });
 class PgBackend {
     pool;
@@ -337,9 +326,16 @@ class PgBackend {
         this.config = config;
         this.observers = observers;
         this.onWarn = onWarn;
+        this.blobNamespaceInst = config.snapshotBlobStore ? createSessionBlobNamespace(config.snapshotBlobStore) : undefined;
+    }
+    async ensureSchema() {
+        await ensurePgSchema(this.pool);
+        if (this.blobNamespaceInst)
+            this.blobNamespaceInst.bind(await ensureSessionBlobClaimToken(pgDriver(this.pool)));
     }
-    ensureSchema() { return ensurePgSchema(this.pool); }
     close() { return this.pool.end(); }
+    sessionBlobNamespace() { return this.blobNamespaceInst; }
+    blobNamespaceInst;
     run() { return (this.runStoreInst ??= new PgRunStore(this.pool, createRunStallWiring(this.config, this.observers))); }
     runStoreInst;
     resumeAnchor() { return (this.resumeAnchorInst ??= new PgResumeAnchorStore(this.pool)); }
@@ -353,14 +349,14 @@ class PgBackend {
     userInputLedger() { return new PgUserInputLedgerStore(this.pool); }
     sessionPolicy() { return (this.sessionPolicyInst ??= new PgSessionPolicyStore(this.pool, SQL_SESSION_ROOT_SEAT, policyStoreLoggerOf(this.onWarn))); }
     sessionPolicyInst;
-    fileHistory() { return (this.fileHistoryInst ??= new PgFileHistoryStore(this.pool, fileHistoryOptions(this.config))); }
+    fileHistory() { return (this.fileHistoryInst ??= new PgFileHistoryStore(this.pool, fileHistoryOptions(this.config, this.sessionBlobNamespace()))); }
     fileHistoryInst;
     landedAttendants() { return (this.landedAttendantsInst ??= sqlLandedAttendantsOf(pgDriver(this.pool), this.fileHistory(), this.sessionPolicy())); }
     landedAttendantsInst;
     memoryOptOutGrant() { return new PgMemoryOptOutGrantStore(this.pool); }
     sessionCaptureRecords() { return () => (this.captureRecordsInst ??= new PgSessionCaptureRecordStore(this.pool)); }
     captureRecordsInst;
-    legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "pg", this.pool); }
+    legacySnapshotBlobSweep() { return legacySweepImpl(this.config, "pg", this.pool, this.sessionBlobNamespace()); }
     runOneTimeMigrations() { return runSqlOneTimeMigrations("pg", this.pool, buildSqlOneTimeMigrationInput(this.config)); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
     outcomeSink() { return new PgOutcomeLedger(this.pool); }
@@ -371,7 +367,9 @@ class PgBackend {
     workflowParkDecisions(records) { return (this.parkDecisionsInst = decisionStoreBoundOnce(this.parkDecisionsInst, records, () => new SqlWorkflowParkDecisionStore(this.run(), sqlRecordFenceOf(records)))); }
     parkDecisionsInst;
     sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); }
-    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
+    cardScopeRootSeat = createCardScopeRootSeat();
+    bindCardScopeRoot(read) { this.cardScopeRootSeat.bind(read); }
+    checkpoint(logger) { return new PgCheckpointStore(this.pool, logger, { retention: sqlStoreRetention(this.config.retentionSweep), cardScopeRoot: this.cardScopeRootSeat }); }
     checkpointReadView() { return this.checkpoint(); }
     toolResult() { return new PgToolResultStore(this.pool, { retention: sqlStoreRetention(this.config.retentionSweep) }); }
     imageIndex() { return new PgImageIndex(this.pool); }
@@ -391,13 +389,13 @@ class PgBackend {
     async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); }
 }
 sealStoreClass(PgBackend, "pg-backend", {
-    ensureSchema: "boot", close: "boot", run: "exit", resumeAnchor: "exit", approvalExemption: "exit", approvalNonce: "exit", orgDeliveryQuota: "exit",
+    ensureSchema: "boot", close: "boot", sessionBlobNamespace: "exit", run: "exit", resumeAnchor: "exit", approvalExemption: "exit", approvalNonce: "exit", orgDeliveryQuota: "exit",
     approvalAsk: "exit", permissionRule: "exit", sendFileLedger: "exit", userInputLedger: "exit", sessionPolicy: "exit", fileHistory: "exit",
     memoryOptOutGrant: "exit", sessionCaptureRecords: "exit", legacySnapshotBlobSweep: "exit", runOneTimeMigrations: "boot", workflowJournal: "exit",
     outcomeSink: "exit", workflowRun: "exit", completionInbox: "exit", notifyJournal: "exit", workflowAgentSessionIndex: "exit", workflowParkDecisions: "exit",
     sharedMemoryStore: "exit", checkpoint: "exit", checkpointReadView: "exit", toolResult: "exit", imageIndex: "exit", imageBake: "exit", leaderRun: "exit",
     device: "exit", retention: "exit", sessionEraser: "exit", retentionLane: "exit", breaker: "exit", costQuota: "exit", rateLimiter: "exit", session: "exit",
-    adoptionLog: "exit", mysqlPool: "boot", pgPool: "boot", dbNowMs: "exit", landedAttendants: "exit",
+    adoptionLog: "exit", mysqlPool: "boot", pgPool: "boot", dbNowMs: "exit", landedAttendants: "exit", bindCardScopeRoot: "exit",
 });
 export function localSessionRowsOf(backend) {
     return backend instanceof LocalBackend ? backend.session() : undefined;
@@ -568,7 +566,12 @@ class LocalBackend {
             ...importedLayerRoot,
         };
     }
+    closing = false;
+    exclusiveDataRoot() {
+        return this.closing ? undefined : this.fileBackend.root;
+    }
     async close() {
+        this.closing = true;
         await this.sessionStore.dispose();
         this.runStore.dispose();
         this.resumeAnchorStore.dispose();
@@ -612,8 +615,11 @@ class LocalBackend {
             durability: this.storeDeclaration.durability,
             getActiveTaskId: (sessionId) => this.runStore.getActiveTaskId(sessionId),
             readSessionOwner: async (sessionId) => (await this.sessionStore.headOf(sessionId))?.owner,
+            cardScopeRoot: this.cardScopeRootSeat,
         }));
     }
+    cardScopeRootSeat = createCardScopeRootSeat();
+    bindCardScopeRoot(read) { this.cardScopeRootSeat.bind(read); }
     checkpoint() {
         const cs = this.checkpointStoreOf();
         if (!this.checkpointProbeWired) {
@@ -709,6 +715,9 @@ class RefusedLocalBackend {
     async close() {
         await this.release();
     }
+    exclusiveDataRoot() {
+        return undefined;
+    }
     run() { return this.refused(); }
     resumeAnchor() { return this.refused(); }
     approvalExemption() { return this.refused(); }
@@ -732,6 +741,7 @@ class RefusedLocalBackend {
     fileUsageWindowStore() { return this.refused(); }
     localStoreDeclaration() { return this.refused(); }
     bindWorkflowRunReader() { this.refused(); }
+    bindCardScopeRoot() { this.refused(); }
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
@@ -802,6 +812,16 @@ export async function openStoreBackendWithFallback(config, logger, observers, lo
             sqlEngine === undefined
                 ? await attempt()
                 : await openWithinWait(attempt, config.storeLockWaitMs, (w) => logger.warn("store_sql_open_wait", { engine: sqlEngine, endpoint: buildDisplaySafeUrl(sqlStoreCoordinatesAsUrl(config)), waitMs: w.waitMs, error: w.error }));
+        const namespace = backend?.sessionBlobNamespace?.();
+        if (namespace !== undefined) {
+            try {
+                await namespace.establish();
+            }
+            catch (refusal) {
+                await backend?.close().catch(() => undefined);
+                throw refusal;
+            }
+        }
     }
     catch (err) {
         void inFlight?.close().catch(() => undefined);
@@ -859,13 +879,15 @@ sealStoreClass(SqlCheckpointStore, "sql-checkpoint-store", {
     reap: "exit", reapExpired: "exit", listExpiredApprovalGates: "exit", listPending: "exit", listByScope: "exit", listPendingSessionIds: "exit",
     findPendingTokenBySession: "exit", findCheckpointCandidatesForAsk: "exit", findDecidedApprovalsForBinding: "exit", peekScopeByToken: "exit",
     peekPendingScope: "exit", hostSessionOfCard: "exit", putCtx: "exit", getCtx: "exit", rewriteCtxWhileClaimed: "exit", rewriteCtxRows: "exit", reapCtx: "exit",
-    deleteBySession: "exit",
+    deleteBySession: "exit", cardScopeRootOf: "exit",
 });
 sealStoreClass(SqlFileHistoryStore, "sql-file-history-store", {
     trackEdit: "exit", annulTrack: "exit", snapshot: "exit", restore: "exit", canRestore: "exit", reap: "exit", deleteBySession: "exit", sweepOrphanBlobs: "exit",
     adoptScope: "exit", exportHistory: "exit", importHistory: "exit", importFailureOf: "exit", prepareImport: "exit",
     lockScopeOn: "in-store", publishImportOn: "in-store", deleteScopeOn: "in-store",
 });
+sealStoreClass(SqlBlobExchange, "sql-blob-exchange", { put: "exit", get: "exit", has: "exit" });
+sealStoreClass(SqlBlobLanding, "sql-blob-landing", { putAt: "exit", visibleAt: "exit" });
 sealStoreClass(TiDBMailboxStore, "tidb-mailbox-store", {
     append: "exit", claimLease: "exit", ack: "exit", moveDecision: "exit", releaseLease: "exit", peekCount: "exit", drop: "exit", reap: "exit",
     retireRecipient: "exit", listRetiredRecipients: "exit",

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

@@ -83,7 +83,8 @@ export interface TaskAttachmentStore {
     deleteBySession(sessionId: string): Promise<number>;
     /** TTL 收割:未绑定且 created_at_ms < olderThanMs 的行。返回删除数。 */
     reapUnbound(olderThanMs: number): Promise<number>;
-    /** D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):列举对象存储 × meta 行对账,零行且过 grace 的对象删。
+    /** D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):列举对象存储 × meta 行对账,零行且过 grace 的对象删。只看本域写得出的名(内容地址);
+     *  「零行」只对本库成立 ⇒ 命名空间必须只属本库(字节口的删除等命名空间归属证明,`session-blob-namespace.ts`)。
      *  可选——local 店(meta+bytes 同盘同步删)无此孤儿类。 */
     sweepOrphanObjects?(graceMs: number, nowMs?: number): Promise<number>;
 }