@sema-agent/server 7.151.0 → 7.152.0

package/dist/plugins/s3-presign.d.ts

@@ -1,4 +1,14 @@
+import { type ObjectStoreOp } from "../object-store-buckets.js";
+/** The signed URL's lifetime under row `op` — the ONE reading of the table's TTL column. A row with no `knob` has a fixed TTL: the table's number, and a
+ *  call that brings one is refused (its number would be a second source). A knob row takes `requested` (the configured value the call brings) clamped to
+ *  the row's `maxSec` (the row's policy cap) — a call that brings none, or a value that is not a positive number of seconds (`0` is no lifetime at all),
+ *  takes the row's `defaultSec` — the reading the `SESSION_SNAPSHOT_TTL_SEC` loader gives its `0` (any other non-positive spelling no longer loads: the configuration is refused) — and a row with no default needs a positive one.
+ *  Every row, one answer for the SigV4 ceiling ({@link SIGV4_PRESIGN_MAX_SEC}): a lifetime over it is refused, never clamped (the knobs are refused above it
+ *  when the configuration loads, so a call that gets here is a defect). */
+export declare function rowTtlSec(op: ObjectStoreOp, requested: number | undefined): number;
 export interface S3PresignParams {
+    /** The object-store action table row this request is (its action must be `method`). */
+    op: ObjectStoreOp;
     /** Base endpoint, e.g. `http://minio.minio.svc.cluster.local:9000` (the host the SANDBOX will reach). */
     endpoint: string;
     bucket: string;
@@ -8,6 +18,7 @@ export interface S3PresignParams {
     accessKey: string;
     secretKey: string;
     region?: string;
+    /** The configured TTL (seconds) of a knob row; a fixed-TTL row takes none (see {@link rowTtlSec}). */
     expiresSec?: number;
     /** Override the signing clock (tests). Defaults to now. */
     now?: Date;
@@ -33,6 +44,8 @@ export declare function presignS3BucketUrl(p: S3BucketPresignParams): string;
 /** ListObjectsV2 presign(D-1 孤儿对象 GC,clay 拍 2026-07-28):GET `/<bucket>/?list-type=2&prefix=…`。
  *  bucket 级 GET 是**列举能力**——只给 server 端 sweep 用,URL 绝不外发(与 copy 面同纪律)。 */
 export declare function presignS3ListUrl(p: {
+    /** The object-store action table row this listing is (a LIST row). */
+    op: ObjectStoreOp;
     endpoint: string;
     bucket: string;
     prefix: string;
@@ -45,6 +58,8 @@ export declare function presignS3ListUrl(p: {
     now?: Date;
 }): string;
 export interface S3CopyPresignParams {
+    /** The object-store action table row this copy is (a COPY row). */
+    op: ObjectStoreOp;
     /** INTERNAL endpoint — CopyObject is a SERVER-side request with adapter creds; never hand this URL out. */
     endpoint: string;
     /** Destination coordinates (the PUT target). */
@@ -69,4 +84,12 @@ export declare function presignS3CopyUrl(p: S3CopyPresignParams): {
     url: string;
     headers: Record<string, string>;
 };
+/** The URL of an object on an anonymous-read bucket (no signature, no expiry): `<endpoint>/<bucket>/<key>`, each key segment URI-encoded. `op` names
+ *  the table's anonymous GET row; any other row is refused. */
+export declare function buildPublicObjectUrl(p: {
+    op: ObjectStoreOp;
+    endpoint: string;
+    bucket: string;
+    key: string;
+}): string;
 //# sourceMappingURL=s3-presign.d.ts.map

package/dist/plugins/s3-presign.js

@@ -1,4 +1,30 @@
 import { createHash, createHmac } from "node:crypto";
+import { SIGV4_PRESIGN_MAX_SEC, objectStoreActionOf } from "../object-store-buckets.js";
+function assertRow(op, verb, signing) {
+    const row = objectStoreActionOf(op);
+    if (row.action !== verb)
+        throw new Error(`object-store seat: ${op} is a ${row.action} row — refusing to build a ${verb} request under it`);
+    if ((row.ttl === "unsigned") !== (signing === "anonymous")) {
+        throw new Error(`object-store seat: ${op} is ${row.ttl === "unsigned" ? "an anonymous" : "a signed"} row — refusing to build ${signing === "anonymous" ? "an anonymous" : "a signed"} URL under it`);
+    }
+}
+export function rowTtlSec(op, requested) {
+    const ttl = objectStoreActionOf(op).ttl;
+    if (ttl === "unsigned")
+        throw new Error(`object-store seat: ${op} is unsigned — it has no URL lifetime`);
+    if (ttl.knob === undefined) {
+        if (requested !== undefined)
+            throw new Error(`object-store seat: ${op} has a fixed TTL (${ttl.defaultSec} s, the table's) — refusing a call-site TTL of ${requested} s`);
+        return ttl.defaultSec;
+    }
+    const sec = requested !== undefined && requested > 0 ? requested : ttl.defaultSec;
+    if (sec === undefined)
+        throw new Error(`object-store seat: ${op} takes its TTL from ${ttl.knob} or its call — none was given`);
+    if (sec > SIGV4_PRESIGN_MAX_SEC) {
+        throw new Error(`object-store seat: ${op} was asked for a ${sec} s URL — a SigV4 presigned URL lives at most ${SIGV4_PRESIGN_MAX_SEC} s (7 days); ${ttl.knob} is refused above that when the configuration loads`);
+    }
+    return ttl.maxSec !== undefined ? Math.min(sec, ttl.maxSec) : sec;
+}
 function uriEncode(s, encodeSlash) {
     let out = "";
     for (const ch of Buffer.from(s, "utf8")) {
@@ -57,18 +83,21 @@ function presignCanonical(p) {
     return `${url.origin}${canonicalUri}?${canonicalQuery}&X-Amz-Signature=${signature}`;
 }
 export function presignS3Url(p) {
+    assertRow(p.op, p.method, "signed");
+    const expiresSec = rowTtlSec(p.op, p.expiresSec);
     if (p.key === "") {
         throw new Error("presignS3Url: refusing to sign an empty key (single-object contract) — use presignS3BucketUrl for bucket-level operations");
     }
     if (p.key.startsWith("/") || p.key.split("/").some((seg) => seg === "." || seg === "..")) {
         throw new Error(`presignS3Url: refusing to sign a key with a traversal segment: ${p.key}`);
     }
-    return presignCanonical({ ...p, canonicalUri: `/${uriEncode(p.bucket, true)}/${uriEncode(p.key, false)}` });
+    return presignCanonical({ ...p, expiresSec, canonicalUri: `/${uriEncode(p.bucket, true)}/${uriEncode(p.key, false)}` });
 }
 export function presignS3BucketUrl(p) {
     return presignCanonical({ ...p, canonicalUri: `/${uriEncode(p.bucket, true)}/` });
 }
 export function presignS3ListUrl(p) {
+    assertRow(p.op, "LIST", "signed");
     return presignCanonical({
         endpoint: p.endpoint,
         canonicalUri: `/${uriEncode(p.bucket, true)}/`,
@@ -76,7 +105,7 @@ export function presignS3ListUrl(p) {
         accessKey: p.accessKey,
         secretKey: p.secretKey,
         ...(p.region ? { region: p.region } : {}),
-        ...(p.expiresSec ? { expiresSec: p.expiresSec } : {}),
+        expiresSec: rowTtlSec(p.op, p.expiresSec),
         ...(p.now ? { now: p.now } : {}),
         extraQuery: {
             "list-type": "2",
@@ -87,6 +116,7 @@ export function presignS3ListUrl(p) {
     });
 }
 export function presignS3CopyUrl(p) {
+    assertRow(p.op, "COPY", "signed");
     for (const [label, key] of [
         ["destination", p.key],
         ["source", p.sourceKey],
@@ -105,10 +135,14 @@ export function presignS3CopyUrl(p) {
         accessKey: p.accessKey,
         secretKey: p.secretKey,
         ...(p.region !== undefined ? { region: p.region } : {}),
-        ...(p.expiresSec !== undefined ? { expiresSec: p.expiresSec } : {}),
+        expiresSec: rowTtlSec(p.op, p.expiresSec),
         ...(p.now !== undefined ? { now: p.now } : {}),
         signedHeaders: { "x-amz-copy-source": copySource },
     });
     return { url, headers: { "x-amz-copy-source": copySource } };
 }
+export function buildPublicObjectUrl(p) {
+    assertRow(p.op, "GET", "anonymous");
+    return `${p.endpoint.replace(/\/+$/, "")}/${p.bucket}/${p.key.split("/").map(encodeURIComponent).join("/")}`;
+}
 //# sourceMappingURL=s3-presign.js.map

package/dist/plugins/scheduler-support.d.ts

@@ -47,8 +47,8 @@ export interface SchedulerStoreLog {
  * 的 `record` 可能是任意内容 —— 只报下标):
  *  · `unreadable-file` ⇒ warn(整份文件不是 JSON 数组:读成零条,写者一律不写 —— 见 `mutateSchedulerStore`);
  *  · `malformed-record` ⇒ warn(这一条读不懂、被跳过;下一个写者落盘时它就没了);
- *  · `stale-session-record` ⇒ info(会话链上过期 ≥ 7 天的记录,读时丢、下一个写者落盘);
- *  · `one-time-migration` ⇒ info(SS-M3 的读时改写收据:durable 记录换上新键,下一个写者落盘)。
+ *  · `stale-session-record` ⇒ info(会话链上过期 ≥ 7 天的记录,读时丢、下一个写者落盘)。
+ * (settings-schema 26.0.0 删了调度店的读时重铸一步与它的收据臂:仍按会话链键存的 durable 记录逐字读出、不告警 —— 没有日志可写。)
  */
 export declare function logSchedulerWarnings(log: SchedulerStoreLog, path: string, warnings: readonly SchedulerParseWarning[]): void;
 /**

package/dist/plugins/scheduler-support.js

@@ -75,9 +75,6 @@ export function logSchedulerWarnings(log, path, warnings) {
             case "stale-session-record":
                 log.info("scheduler_store_record_stale", { path, index: w.index, id: w.id, note: "a session-chained record whose next run is ≥ 7 days past — dropped on read (the next write persists the drop)" });
                 break;
-            case "one-time-migration":
-                log.info("scheduler_store_record_migrated", { path, index: w.index, migration: w.receipt.migration, appliedAs: w.receipt.appliedAs, note: "settings-schema one-time migration rewrote this record on read (the next write persists it)" });
-                break;
             default: {
                 const unhandled = w;
                 throw new Error(`scheduler store: unknown read warning ${JSON.stringify(unhandled)}`);

package/dist/plugins/schema-indexes.js

@@ -20,6 +20,8 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "file_history_boundary_file", name: "idx_file_history_bf_key", columns: ["scope", "key_hash"] },
     { table: "file_history_boundary", name: "uq_file_history_boundary_seq", columns: ["scope", "publish_seq"], unique: true },
     { table: "file_history_blob", name: "idx_file_history_blob_created", columns: ["created_at"] },
+    { table: "file_history_blob_grant", name: "idx_file_history_blob_grant_granted", columns: ["granted_at"] },
+    { table: "file_history_blob_grant", name: "idx_file_history_blob_grant_blob", columns: ["blob_hash"] },
     { table: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
     { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
     { table: "workflow_agent_session", name: "idx_wfagentsess_run", columns: ["run_id"] },

package/dist/plugins/send-file-ledger.d.ts

@@ -55,8 +55,8 @@ export declare class FileSendFileLedger implements SendFileLedger {
 }
 export interface LedgerRecordingDeps {
     ledger: SendFileLedger;
-    /** Best-effort reclaim of the uploaded object when the record fails (issuer.deleteObject). */
-    deleteObject: (bucket: string, key: string) => Promise<void>;
+    /** Best-effort reclaim of the uploaded object when the record fails (issuer.deleteObject; `track` = the link's track). */
+    deleteObject: (bucket: string, key: string, track: IssuedFileLink["track"]) => Promise<void>;
     warn?: (msg: string, meta?: Record<string, unknown>) => void;
     now?: () => number;
     newId?: () => string;

package/dist/plugins/send-file-ledger.js

@@ -130,10 +130,10 @@ export function withLedgerRecording(send, deps) {
             let reclaimed = true;
             try {
                 try {
-                    await deps.deleteObject(link.bucket, link.key);
+                    await deps.deleteObject(link.bucket, link.key, link.track);
                 }
                 catch {
-                    await deps.deleteObject(link.bucket, link.key);
+                    await deps.deleteObject(link.bucket, link.key, link.track);
                 }
             }
             catch (de) {

package/dist/plugins/send-user-file.d.ts

@@ -1,5 +1,3 @@
-/** SigV4 physical ceiling (AWS: X-Amz-Expires max 604800s = 7 days). */
-export declare const PRESIGN_MAX_TTL_SEC = 604800;
 /**
  * Multi-tenant governance (clay ruling 2026-07-14, blackboard [ref]② variant a with a HASHED segment): every
  * object key carries a per-tenant SCOPE SEGMENT so tenants can be listed/revoked by prefix on the store itself,
@@ -102,8 +100,9 @@ export interface SendUserFileIssuer {
      *  semantics as issue() — prepare and finalize share ONE key, so the segment is fixed at prepare time. */
     prepareDirectUpload(filename: string | undefined, ttlSec?: number, scope?: string): PreparedDirectUpload;
     /** Best-effort object reclaim (ledger fail-loud path: an uploaded object whose ledger record failed would be
-     *  an unmanageable orphan — delete it). Signed DELETE against the INTERNAL endpoint with adapter creds. */
-    deleteObject(bucket: string, key: string): Promise<void>;
+     *  an unmanageable orphan — delete it). Signed DELETE against the INTERNAL endpoint with adapter creds. `track` = the link's track
+     *  (which object-store action row the delete is: the permanent track's bucket or the private one). */
+    deleteObject(bucket: string, key: string, track: IssuedFileLink["track"]): Promise<void>;
     /** The public endpoint web clients need for rendering context (bootstrap/capabilities透出). */
     readonly publicEndpoint: string | undefined;
 }

package/dist/plugins/send-user-file.js

@@ -1,10 +1,10 @@
 import { createHmac } from "node:crypto";
 import { uuidv7 } from "@sema-agent/core";
 import { stripControlAndBidi } from "@sema-agent/settings-schema";
-import { presignS3CopyUrl, presignS3Url } from "./s3-presign.js";
+import { buildPublicObjectUrl, presignS3CopyUrl, presignS3Url, rowTtlSec } from "./s3-presign.js";
+import { SENDFILE_STAGING_SEGMENT } from "../object-store-buckets.js";
 import { OBJECT_STORE_IO_TIMEOUT_MS } from "./blob-backend.js";
 import { createEgressFetch } from "../egress-redirect.js";
-export const PRESIGN_MAX_TTL_SEC = 604_800;
 export function scopeSegment(secretKey, scope) {
     if (scope === undefined || scope === "")
         return "_";
@@ -30,23 +30,27 @@ export function sanitizeSendFileName(name) {
 export function createSendUserFileIssuer(cfg, deps) {
     const f = createEgressFetch("declare the final object-store address as MINIO_ENDPOINT / S3_ENDPOINT", deps?.fetchImpl);
     const bounded = () => ({ signal: AbortSignal.timeout(OBJECT_STORE_IO_TIMEOUT_MS) });
-    const upload = deps?.upload ??
-        (async (bucket, key, bytes) => {
-            const url = presignS3Url({
-                endpoint: cfg.endpoint,
-                bucket,
-                key,
-                method: "PUT",
-                accessKey: cfg.accessKey,
-                secretKey: cfg.secretKey,
-                ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-                expiresSec: 600,
-                ...(deps?.now !== undefined ? { now: deps.now() } : {}),
-            });
-            const res = await f(url, { method: "PUT", body: Buffer.from(bytes), ...bounded() });
-            if (!res.ok)
-                throw new Error(`SendUserFile upload failed: ${res.status} ${res.statusText} (bucket=${bucket})`);
+    const trackOps = (track) => track === "public"
+        ? { put: "sendfile/public:PUT", copy: "sendfile/public:COPY", head: "sendfile/public:HEAD", delete: "sendfile/public:DELETE" }
+        : { put: "sendfile/private:PUT", copy: "sendfile/private:COPY", head: "sendfile/private:HEAD", delete: "sendfile/private:DELETE" };
+    const upload = async (op, bucket, key, bytes) => {
+        if (deps?.upload)
+            return deps.upload(bucket, key, bytes);
+        const url = presignS3Url({
+            op,
+            endpoint: cfg.endpoint,
+            bucket,
+            key,
+            method: "PUT",
+            accessKey: cfg.accessKey,
+            secretKey: cfg.secretKey,
+            ...(cfg.region !== undefined ? { region: cfg.region } : {}),
+            ...(deps?.now !== undefined ? { now: deps.now() } : {}),
         });
+        const res = await f(url, { method: "PUT", body: Buffer.from(bytes), ...bounded() });
+        if (!res.ok)
+            throw new Error(`SendUserFile upload failed: ${res.status} ${res.statusText} (bucket=${bucket})`);
+    };
     const issue = async (bytes, filename, ttlSec, scope) => {
         if (cfg.publicEndpoint === undefined) {
             throw new Error("SendUserFile is not configured for public links: set S3_PUBLIC_ENDPOINT (the S3/MinIO base URL users can reach; falls back to S3_ENDPOINT when that is already public)");
@@ -60,16 +64,15 @@ export function createSendUserFileIssuer(cfg, deps) {
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         if (ttl === 0) {
             const key = `${seg}/${uuidv7()}/${name}`;
-            await upload(cfg.publicBucket, key, bytes);
-            const url = `${publicBase}/${cfg.publicBucket}/${key.split("/").map(encodeURIComponent).join("/")}`;
+            await upload(trackOps("public").put, cfg.publicBucket, key, bytes);
+            const url = buildPublicObjectUrl({ op: "sendfile/public:GET", endpoint: publicBase, bucket: cfg.publicBucket, key });
             return { url, filename: name, size: bytes.byteLength, ttlSec: 0, track: "public", bucket: cfg.publicBucket, key, ...scopeField };
         }
-        if (ttl > PRESIGN_MAX_TTL_SEC) {
-            throw new Error(`SendUserFile ttl ${ttl}s exceeds the SigV4 presign ceiling (${PRESIGN_MAX_TTL_SEC}s = 7 days) — use ttl=0 for a permanent link`);
-        }
+        const expiresSec = rowTtlSec("sendfile/private:GET", ttl);
         const key = `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
-        await upload(cfg.privateBucket, key, bytes);
+        await upload(trackOps("presigned").put, cfg.privateBucket, key, bytes);
         const url = presignS3Url({
+            op: "sendfile/private:GET",
             endpoint: publicBase,
             bucket: cfg.privateBucket,
             key,
@@ -77,10 +80,10 @@ export function createSendUserFileIssuer(cfg, deps) {
             accessKey: cfg.accessKey,
             secretKey: cfg.secretKey,
             ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-            expiresSec: ttl,
+            expiresSec,
             ...(deps?.now !== undefined ? { now: deps.now() } : {}),
         });
-        return { url, filename: name, size: bytes.byteLength, ttlSec: ttl, track: "presigned", bucket: cfg.privateBucket, key, ...scopeField };
+        return { url, filename: name, size: bytes.byteLength, ttlSec: expiresSec, track: "presigned", bucket: cfg.privateBucket, key, ...scopeField };
     };
     const prepareDirectUpload = (filename, ttlSec, scope) => {
         if (cfg.publicEndpoint === undefined) {
@@ -89,19 +92,20 @@ export function createSendUserFileIssuer(cfg, deps) {
         const ttl = ttlSec ?? cfg.defaultTtlSec;
         if (!Number.isInteger(ttl) || ttl < 0)
             throw new Error(`SendUserFile ttl must be a non-negative INTEGER of seconds (0 = permanent; SigV4 X-Amz-Expires is integer-only); got ${ttl}`);
-        if (ttl > PRESIGN_MAX_TTL_SEC) {
-            throw new Error(`SendUserFile ttl ${ttl}s exceeds the SigV4 presign ceiling (${PRESIGN_MAX_TTL_SEC}s = 7 days) — use ttl=0 for a permanent link`);
-        }
+        if (ttl > 0)
+            rowTtlSec("sendfile/private:GET", ttl);
         const name = sanitizeSendFileName(filename);
         const publicBase = cfg.publicEndpoint.replace(/\/+$/, "");
         const putBase = (cfg.sandboxPutEndpoint ?? cfg.publicEndpoint).replace(/\/+$/, "");
         const bucket = ttl === 0 ? cfg.publicBucket : cfg.privateBucket;
+        const finalOps = trackOps(ttl === 0 ? "public" : "presigned");
         const seg = scopeSegment(cfg.secretKey, scope);
         const scopeField = scope !== undefined && scope !== "" ? { scope } : {};
         const key = ttl === 0 ? `${seg}/${uuidv7()}/${name}` : `${cfg.privateKeyPrefix}${seg}/${uuidv7()}/${name}`;
         const stagingBucket = cfg.privateBucket;
-        const stagingKey = `${cfg.privateKeyPrefix}staging/${seg}/${uuidv7()}`;
+        const stagingKey = `${cfg.privateKeyPrefix}${SENDFILE_STAGING_SEGMENT}${seg}/${uuidv7()}`;
         const putUrl = presignS3Url({
+            op: "sendfile/staging:PUT",
             endpoint: putBase,
             bucket: stagingBucket,
             key: stagingKey,
@@ -109,13 +113,13 @@ export function createSendUserFileIssuer(cfg, deps) {
             accessKey: cfg.accessKey,
             secretKey: cfg.secretKey,
             ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-            expiresSec: 120,
             ...(deps?.now !== undefined ? { now: deps.now() } : {}),
         });
         const verifySize = async (maxBytes) => {
             if (deps?.verify)
                 return deps.verify(bucket, key, maxBytes);
-            const sign = (method, b, k) => presignS3Url({
+            const sign = (op, method, b, k) => presignS3Url({
+                op,
                 endpoint: cfg.endpoint,
                 bucket: b,
                 key: k,
@@ -123,11 +127,10 @@ export function createSendUserFileIssuer(cfg, deps) {
                 accessKey: cfg.accessKey,
                 secretKey: cfg.secretKey,
                 ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-                expiresSec: 60,
             });
-            const reclaim = async (b, k) => {
+            const reclaim = async (op, b, k) => {
                 try {
-                    const r = await f(sign("DELETE", b, k), { method: "DELETE", ...bounded() });
+                    const r = await f(sign(op, "DELETE", b, k), { method: "DELETE", ...bounded() });
                     return r.ok || r.status === 404;
                 }
                 catch {
@@ -137,28 +140,29 @@ export function createSendUserFileIssuer(cfg, deps) {
             const outcome = (ok, what) => (ok ? `${what} reclaimed` : `${what} reclaim FAILED (orphan; operator cleanup needed)`);
             let head;
             try {
-                head = await f(sign("HEAD", stagingBucket, stagingKey), { method: "HEAD", ...bounded() });
+                head = await f(sign("sendfile/staging:HEAD", "HEAD", stagingBucket, stagingKey), { method: "HEAD", ...bounded() });
             }
             catch (e) {
-                const r = await reclaim(stagingBucket, stagingKey);
+                const r = await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
                 throw new Error(`SendUserFile upload verification failed: store unreachable during HEAD (${e instanceof Error ? e.message : String(e)}) — ${outcome(r, "staged object")}`);
             }
             if (head.status === 404)
                 throw new Error("SendUserFile upload verification failed: object not found after upload (HEAD 404)");
             if (!head.ok) {
-                const r = await reclaim(stagingBucket, stagingKey);
+                const r = await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
                 throw new Error(`SendUserFile upload verification failed: store error (HEAD ${head.status}) — ${outcome(r, "staged object")}`);
             }
             const staged = Number.parseInt(head.headers.get("content-length") ?? "", 10);
             if (!Number.isFinite(staged) || staged < 0) {
-                const r = await reclaim(stagingBucket, stagingKey);
+                const r = await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
                 throw new Error(`SendUserFile upload verification failed: store returned no content-length — ${outcome(r, "staged object")}`);
             }
             if (staged > maxBytes) {
-                await reclaim(stagingBucket, stagingKey);
+                await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
                 throw new Error(`file exceeds the ${maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / (1024 * 1024))} MiB` : `${maxBytes} byte`} per-file cap (uploaded object was ${staged} bytes — deleted)`);
             }
             const copy = presignS3CopyUrl({
+                op: finalOps.copy,
                 endpoint: cfg.endpoint,
                 bucket,
                 key,
@@ -167,7 +171,6 @@ export function createSendUserFileIssuer(cfg, deps) {
                 accessKey: cfg.accessKey,
                 secretKey: cfg.secretKey,
                 ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-                expiresSec: 60,
                 ...(deps?.now !== undefined ? { now: deps.now() } : {}),
             });
             try {
@@ -177,40 +180,41 @@ export function createSendUserFileIssuer(cfg, deps) {
                     throw new Error(`copy returned ${res.status}`);
             }
             catch (e) {
-                const r1 = await reclaim(stagingBucket, stagingKey);
-                const r2 = await reclaim(bucket, key);
+                const r1 = await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
+                const r2 = await reclaim(finalOps.delete, bucket, key);
                 throw new Error(`SendUserFile upload verification failed: staging promotion failed (${e instanceof Error ? e.message : String(e)}) — ${outcome(r1 && r2, "uploaded object")}`);
             }
-            await reclaim(stagingBucket, stagingKey);
+            await reclaim("sendfile/staging:DELETE", stagingBucket, stagingKey);
             let fin;
             try {
-                fin = await f(sign("HEAD", bucket, key), { method: "HEAD", ...bounded() });
+                fin = await f(sign(finalOps.head, "HEAD", bucket, key), { method: "HEAD", ...bounded() });
             }
             catch (e) {
-                const r = await reclaim(bucket, key);
+                const r = await reclaim(finalOps.delete, bucket, key);
                 throw new Error(`SendUserFile upload verification failed: store unreachable during final HEAD (${e instanceof Error ? e.message : String(e)}) — ${outcome(r, "object")}`);
             }
             if (!fin.ok) {
-                const r = await reclaim(bucket, key);
+                const r = await reclaim(finalOps.delete, bucket, key);
                 throw new Error(`SendUserFile upload verification failed: final object HEAD ${fin.status} — ${outcome(r, "object")}`);
             }
             const size = Number.parseInt(fin.headers.get("content-length") ?? "", 10);
             if (!Number.isFinite(size) || size < 0) {
-                const r = await reclaim(bucket, key);
+                const r = await reclaim(finalOps.delete, bucket, key);
                 throw new Error(`SendUserFile upload verification failed: store returned no content-length — ${outcome(r, "object")}`);
             }
             if (size > maxBytes) {
-                await reclaim(bucket, key);
+                await reclaim(finalOps.delete, bucket, key);
                 throw new Error(`file exceeds the ${maxBytes >= 1024 * 1024 ? `${Math.floor(maxBytes / (1024 * 1024))} MiB` : `${maxBytes} byte`} per-file cap (uploaded object was ${size} bytes — deleted)`);
             }
             return size;
         };
         const finalize = (size) => {
             if (ttl === 0) {
-                const url = `${publicBase}/${bucket}/${key.split("/").map(encodeURIComponent).join("/")}`;
+                const url = buildPublicObjectUrl({ op: "sendfile/public:GET", endpoint: publicBase, bucket, key });
                 return { url, filename: name, size, ttlSec: 0, track: "public", bucket, key, ...scopeField };
             }
             const url = presignS3Url({
+                op: "sendfile/private:GET",
                 endpoint: publicBase,
                 bucket,
                 key,
@@ -225,10 +229,11 @@ export function createSendUserFileIssuer(cfg, deps) {
         };
         return { putUrl, verifySize, finalize };
     };
-    const deleteObject = async (bucket, key) => {
+    const deleteObject = async (bucket, key, track) => {
         if (deps?.remove)
             return deps.remove(bucket, key);
         const url = presignS3Url({
+            op: trackOps(track).delete,
             endpoint: cfg.endpoint,
             bucket,
             key,
@@ -236,7 +241,6 @@ export function createSendUserFileIssuer(cfg, deps) {
             accessKey: cfg.accessKey,
             secretKey: cfg.secretKey,
             ...(cfg.region !== undefined ? { region: cfg.region } : {}),
-            expiresSec: 60,
             ...(deps?.now !== undefined ? { now: deps.now() } : {}),
         });
         const res = await f(url, { method: "DELETE", ...bounded() });

package/dist/plugins/session-blob-claim-token.d.ts

@@ -0,0 +1,15 @@
+/**
+ * This database's claim token on the session blob namespace (`session-blob-namespace.ts`): one row, minted once per database (absent ⇒ the first writer's
+ * stays; every replica of the database reads the same), never rewritten. The store's open reads it (`StoreBackend.ensureSchema()`) and hands it to the
+ * namespace's claim; nothing else reads or writes the table.
+ */
+import type { SqlDialect, SqlExec } from "./sql-driver.js";
+/** The table that keeps this database's claim token (one row, `id = 1`). */
+export declare const SESSION_BLOB_NAMESPACE_CLAIM_TABLE = "blob_namespace_claim";
+/** The create statement (both dialects; idempotent). The central schema statements read it (`tidb-pool.ts` / `pg-pool.ts`). */
+export declare function sessionBlobNamespaceClaimDdl(dialect: SqlDialect): string;
+/** This database's claim token: minted if absent, then read (the store's open; a failure is the open's failure). */
+export declare function ensureSessionBlobClaimToken(db: SqlExec & {
+    readonly dialect: SqlDialect;
+}): Promise<string>;
+//# sourceMappingURL=session-blob-claim-token.d.ts.map

package/dist/plugins/session-blob-claim-token.js

@@ -0,0 +1,20 @@
+import { randomUUID } from "node:crypto";
+export const SESSION_BLOB_NAMESPACE_CLAIM_TABLE = "blob_namespace_claim";
+export function sessionBlobNamespaceClaimDdl(dialect) {
+    return dialect === "mysql"
+        ? `CREATE TABLE IF NOT EXISTS ${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} (id SMALLINT NOT NULL PRIMARY KEY, claim_token VARCHAR(64) NOT NULL, minted_at_ms BIGINT NOT NULL) COLLATE utf8mb4_bin`
+        : `CREATE TABLE IF NOT EXISTS ${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} (id SMALLINT NOT NULL PRIMARY KEY, claim_token VARCHAR(64) COLLATE "C" NOT NULL, minted_at_ms BIGINT NOT NULL)`;
+}
+const MINT_SQL = {
+    mysql: `INSERT INTO ${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} (id, claim_token, minted_at_ms) VALUES (1, ?, ?) ON DUPLICATE KEY UPDATE id = id`,
+    pg: `INSERT INTO ${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} (id, claim_token, minted_at_ms) VALUES (1, $1, $2) ON CONFLICT (id) DO NOTHING`,
+};
+export async function ensureSessionBlobClaimToken(db) {
+    await db.query(MINT_SQL[db.dialect], [randomUUID(), Date.now()]);
+    const { rows } = await db.query(`SELECT claim_token FROM ${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} WHERE id = 1`);
+    const token = rows[0]?.claim_token;
+    if (typeof token !== "string" || token === "")
+        throw new Error(`${SESSION_BLOB_NAMESPACE_CLAIM_TABLE} holds no claim token after the mint`);
+    return token;
+}
+//# sourceMappingURL=session-blob-claim-token.js.map

package/dist/plugins/session-blob-namespace.d.ts

@@ -0,0 +1,46 @@
+import { type SessionBlobStoreConfig } from "./blob-backend.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+/** After a create-only write, how long to wait before reading the claim back (once per namespace, on its first claim). */
+export declare const SESSION_BLOB_CLAIM_SETTLE_MS = 1000;
+/** One attempt's reading (closed set). */
+export type SessionBlobClaimReading = {
+    readonly state: "mine";
+} | {
+    readonly state: "foreign";
+    readonly holder: string;
+} | {
+    readonly state: "unproven";
+    readonly detail: string;
+};
+/** The store open's refusal: the namespace is another database's (or the store was opened without binding this database's token). */
+export declare class SessionBlobNamespaceRefusedError extends StoreBootRefusalError {
+    constructor(message: string);
+}
+/** The live namespace seat of one database over one bucket × prefix. */
+export interface SessionBlobNamespace {
+    /** The bucket config the namespace's ports are built from (`createSessionBlobBackend`). */
+    readonly store: SessionBlobStoreConfig;
+    /** Bind this database's claim token (`ensureSessionBlobClaimToken`, read by the store's `ensureSchema()`). */
+    bind(token: string): void;
+    /** One attempt of the claim under `token` (no retry). */
+    claimOnce(token: string): Promise<SessionBlobClaimReading>;
+    /** Boot, under the bound token, one attempt: `mine` ⇒ resolves; `foreign` ⇒ refuses; `unproven` ⇒ resolves through the registered F-class arm
+     *  (deletes stay refused until a later reading is `mine`: {@link assertOwned}). */
+    establish(): Promise<void>;
+    /** Every delete's gate: reads the claim afresh (never remembered) and resolves only when it names this database; rejects otherwise — a namespace with no
+     *  bound token (the store's `ensureSchema()` never ran) has nothing to prove with. */
+    assertOwned(): Promise<void>;
+}
+export interface SessionBlobNamespaceOptions {
+    /** Test seam; production = the global fetch (through the egress-redirect rule). */
+    readonly fetchImpl?: typeof fetch;
+    /** Test seam for the settle wait; production = a timer. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** The refusal when another database holds the namespace (the one sentence; the boot refusal and a refused delete both say it). */
+export declare function buildSessionBlobNamespaceForeignText(store: SessionBlobStoreConfig, holder: string, mine: string): string;
+/** A delete's refusal when the claim could not be read or written (the delete is retried by its sweep / release on its next call, and goes through once
+ *  the claim reads as this database's). */
+export declare function buildSessionBlobNamespaceUnprovenText(store: SessionBlobStoreConfig, detail: string): string;
+export declare function createSessionBlobNamespace(store: SessionBlobStoreConfig, opts?: SessionBlobNamespaceOptions): SessionBlobNamespace;
+//# sourceMappingURL=session-blob-namespace.d.ts.map