@sema-agent/server 7.150.0 → 7.152.0

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/serving-requirement.d.ts

@@ -2,25 +2,30 @@
  * **起服准入**(SQL 两方言;常设)—— 「这只库要求每一只服务者有哪些能力」一张表,与本构建的能力名单比:库上记着本构建没有的能力 ⇒ 拒启,本构建不迁移、不服务。
  *
  * ## 律
- *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 两词闭集
- *    {@link SERVING_REQUIREMENT_STATES}:`pending`(要求方已认领、还没做任何不兼容写)/ `in_force`(不兼容写已开始或已完成)。两态都要求;读出词表外的词 ⇒ 当作 `in_force`,拒句点名那一行。
+ *  · 一行一能力:`migration_id` = 能力名(= 一次性迁移名,`replica-registration.ts` 的 {@link REPLICA_CAPABILITIES} 同一词表),`state` 一词闭集
+ *    {@link SERVING_REQUIREMENT_STATES}:`in_force` = 一只带能力 M 的构建在这只库上放行了 M,M 的不兼容写已开始或马上开始。读出词表外的词(含 7.150.0 闭集里
+ *    从无写者的 `pending`)⇒ 当作 `in_force`,拒句点名那一行与原词。
  *  · 判据 = `knows(本构建, M)`(`knowsCapability`,与停-迁-起证据读法同一只谓词);发布线不进判据(同版本串的构建可以能力不同)。
  *  · 两次读,同一判据:SQL 一次性迁移段头、取迁移锁之前读一次(锁外预读);取到迁移锁之后、第一步迁移之前在锁连接上再读一次(锁内复核)——
  *    在本进程等锁时握着锁的那一只若写下了要求,锁内复核读得到。拒 ⇒ 本构建不迁移;库上只留本进程的登记行(段头第一步)。
  *  · 表不在(跳过了 `ensureSchema()` 的嵌入方)⇒ 拒:证不出「没有要求」不是「没有要求」。
- *  · 本构建不写本表(没有写者;写者随之后的停-迁-起迁移来)—— 表空 ⇒ 准入恒过。装早一版:从本版起的每一只构建都读它,之后写下的要求挡得住它们重启开服。
+ *  · 写者一只({@link recordServingRequirement}):每一条停-迁-起迁移(`stop-then-start.ts`;三类围栏同记)在守卫段放行之后、它**自己的**第一笔不兼容写之前,
+ *    在锁连接上落 `(M, in_force)`(缺席才落;已在的行 —— 含词表外的词 —— 一个字节不动)。只在还欠那一条的库上写(起过那一条的库不写)。
+ *    表空 ⇒ 准入恒过。7.150.0 起的每一只构建都读它,之后写下的要求挡得住缺这项能力的构建重启开服。
+ *  · 读法一只({@link unmetServingRequirements}):准入(非空即拒)与起服拒句的升级清单(点名本构建缺的在力能力)同读,不各写一句。
  *
  * ## 射程(如实)
  * 挡的是**起服者**:已在服务的副本不再读本表;准入与开服之间的停顿也不在它的射程里。早于本表那一版的构建不读本表。
  */
 import { StoreBootRefusalError } from "./store-contracts.js";
-import { type ReplicaRegistration } from "./replica-registration.js";
+import { type ReplicaCapability, type ReplicaRegistration } from "./replica-registration.js";
 import { type UnmetServingRequirement } from "./stop-then-start-sentence.js";
+import type { SchemaProbeRead } from "./schema-live-columns.js";
 import type { SqlDialect, SqlExec } from "./sql-driver.js";
 /** 表名。 */
 export declare const SERVING_REQUIREMENT_TABLE = "serving_requirement";
-/** 要求行的状态词(闭集)。 */
-export declare const SERVING_REQUIREMENT_STATES: readonly ["pending", "in_force"];
+/** 要求行的状态词(闭集;一态 —— 本构建没有「认领了、还没写」的中间态:要求紧跟在本条第一笔不兼容写之前落)。 */
+export declare const SERVING_REQUIREMENT_STATES: readonly ["in_force"];
 export type ServingRequirementState = (typeof SERVING_REQUIREMENT_STATES)[number];
 /** 拒启码(确定的拒启表态;继承 {@link StoreBootRefusalError}:开库等待窗不重试、降级臂不吞)。 */
 export declare const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
@@ -44,6 +49,20 @@ export declare class ServingRequirementUnmetError extends StoreBootRefusalError
 }
 /** 准入读的两张表(本表与段头写的登记表)都在库里;不在 ⇒ 拒(`table_absent`),点名公开序列。 */
 export declare function assertReplicaTablesPresent(db: SqlExec, dialect: SqlDialect, me: ReplicaRegistration): Promise<void>;
-/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。纯读;两方言同一句(无占位符)。 */
+/**
+ * **要求的唯一读法**:库上记着、本构建(`me` 的能力名单)没有的那几行,按能力名排序。纯读;两方言同一句(无占位符,读口 = 列册对账同一只无参读口)。
+ * 读者两只:准入({@link assertServingRequirementsMet},非空即拒)与起服拒句的升级清单(`schema-consistency.ts` 的 `describeUpgradeChecklist`,点名这几项能力)。
+ */
+export declare function unmetServingRequirements(read: SchemaProbeRead, me: Pick<ReplicaRegistration, "capabilities">): Promise<readonly UnmetServingRequirement[]>;
+/** 准入:库上每一行要求的能力本构建都有 ⇒ 过;否则拒(`capability_missing`,点名每一行)。读法 = {@link unmetServingRequirements}。 */
 export declare function assertServingRequirementsMet(db: SqlExec, me: ReplicaRegistration): Promise<void>;
+/**
+ * **要求的唯一写口**:一条停-迁-起迁移放行之后、它自己的第一笔不兼容写之前,在迁移段的锁连接上落 `(migrationId, in_force)`。缺席才落(MySQL 协议
+ * `ON DUPLICATE KEY UPDATE migration_id = migration_id` / PG `ON CONFLICT DO NOTHING`,与副本登记句同形):已在的行 —— 含手写的词表外词 —— 一个字节不动。
+ * 记下之后缺这项能力的构建起服即拒(准入);记下之后、那一笔写之前进程崩 ⇒ 行留着(保守:缺能力的构建拒启,带能力的构建下次起服照常续)。
+ * 读写权限 7.150.0 起已是部署前提(`docs/DEPLOY-PREREQS.md` 7.150.0 节)。`migrationId` 在型上就要在能力名单里。
+ */
+export declare function recordServingRequirement(db: {
+    exec(sql: string, params?: readonly unknown[]): Promise<number>;
+}, dialect: SqlDialect, migrationId: ReplicaCapability, nowMs: number): Promise<void>;
 //# sourceMappingURL=serving-requirement.d.ts.map

package/dist/plugins/serving-requirement.js

@@ -2,7 +2,7 @@ import { StoreBootRefusalError } from "./store-contracts.js";
 import { REPLICA_REGISTRATION_TABLE, knowsCapability } from "./replica-registration.js";
 import { servingRequirementUnmetSentence } from "./stop-then-start-sentence.js";
 export const SERVING_REQUIREMENT_TABLE = "serving_requirement";
-export const SERVING_REQUIREMENT_STATES = ["pending", "in_force"];
+export const SERVING_REQUIREMENT_STATES = ["in_force"];
 export const SERVING_REQUIREMENT_UNMET_CODE = "config.serving_requirement_unmet";
 export function servingRequirementDdl(dialect) {
     return dialect === "mysql"
@@ -37,17 +37,24 @@ function stateOf(cell) {
     const word = String(cell);
     return SERVING_REQUIREMENT_STATES.includes(word) ? { state: word, word } : { state: "in_force", word };
 }
-export async function assertServingRequirementsMet(db, me) {
-    const { rows } = await db.query(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`);
+export async function unmetServingRequirements(read, me) {
     const unmet = [];
-    for (const r of rows) {
+    for (const r of await read(`SELECT migration_id, state FROM ${SERVING_REQUIREMENT_TABLE} ORDER BY migration_id`)) {
         const migration = String(r["migration_id"]);
         if (knowsCapability(me.capabilities, migration))
             continue;
         const { state, word } = stateOf(r["state"]);
         unmet.push({ migration, state, word });
     }
+    return unmet;
+}
+export async function assertServingRequirementsMet(db, me) {
+    const unmet = await unmetServingRequirements(async (sql) => (await db.query(sql)).rows, me);
     if (unmet.length > 0)
         throw new ServingRequirementUnmetError("capability_missing", unmet, [], me.releaseLine);
 }
+export async function recordServingRequirement(db, dialect, migrationId, nowMs) {
+    const insert = `INSERT INTO ${SERVING_REQUIREMENT_TABLE} (migration_id, state, required_at_ms) VALUES (${dialect === "mysql" ? "?, 'in_force', ?" : "$1, 'in_force', $2"})`;
+    await db.exec(dialect === "mysql" ? `${insert} ON DUPLICATE KEY UPDATE migration_id = migration_id` : `${insert} ON CONFLICT (migration_id) DO NOTHING`, [migrationId, nowMs]);
+}
 //# sourceMappingURL=serving-requirement.js.map

package/dist/plugins/session-birth.d.ts

@@ -14,10 +14,14 @@
  * (TiDB 悲观事务里普通 SELECT 读的是事务开始时的快照,看不到等锁期间提交的写;两方言一律 `FOR UPDATE`)。
  */
 import type { SessionTreeEntry } from "@sema-agent/core";
+import type { SessionKind } from "../session-kind.js";
 import type { RegisterReceipt, SessionBirth, WithdrawOutcome } from "../session-incarnation.js";
-/** 出生回执面(会话店的窄面;`register` 的同笔写形)。 */
+/**
+ * 出生回执面(会话店的窄面;`register` 的同笔写形)。`kind` = 这只会话的种类(律 `session-kind.ts`):**只在这一笔真建了新行时**写下,写在建行的同一笔里
+ * (SQL = 建行事务里的建行钩;local = 建行那一笔格写);已在的行 ⇒ 零写(种类终身不改)。缺席 = 顶层对话,逐字今形。
+ */
 export interface SessionBirthFace {
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: SessionKind): Promise<RegisterReceipt>;
 }
 /** 条件撤回面(会话店的窄面;部署装配在店上,一只事务里判完、删完)。`ownTaskId` = 本次提交认领赢的那条 run(没有 ⇒ 缺)。 */
 export interface SessionWithdrawFace {

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

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/session-capture-record-store-sql.js

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
+import { sealStoreClass } from "./store-boundary.js";
 export const SESSION_CAPTURE_OPTOUT_TABLE = "session_capture_optout";
 const UNREADABLE_RECORD_REASON = "capture opt-out record present but unreadable (kept fail-closed)";
 export const SESSION_CAPTURE_KEY_WIDTH = 255;
@@ -81,6 +82,7 @@ export class SqlSessionCaptureRecordStore {
         return out;
     }
 }
+sealStoreClass(SqlSessionCaptureRecordStore, "sql-session-capture-record-store", { mark: "exit", read: "exit", list: "exit" });
 export class TiDBSessionCaptureRecordStore extends SqlSessionCaptureRecordStore {
     constructor(pool) {
         super(mysqlDriver(pool), "mysql");

package/dist/plugins/session-ext-table.d.ts

@@ -1,5 +1,6 @@
 import { StoreBootRefusalError } from "./store-contracts.js";
 import type { SqlDialect, SqlDriver } from "./sql-driver.js";
+import type { IndexSpec } from "./ensure-index.js";
 /** 表名(建表句、语句模块、迁移同读)。 */
 export declare const SESSION_EXT_TABLE = "session_ext";
 /** 一列:名字 + 两方言定义。 */
@@ -27,8 +28,20 @@ export declare const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
  * 在删对删除门之外的一切读者与写者读作「行不在」(头读 / 列表 / 规则 L 的认领);存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`。
  */
 export declare const DELETING_TOKEN_COLUMN: SessionExtColumn;
-/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格与在删令牌不在 `session_meta` 上出现过,不搬)。 */
+/**
+ * **会话种类**(律 `src/session-kind.ts`):`NULL` = 顶层对话(存量行与老壳建的行恒为 NULL —— 无回填、无一次性迁移);非空 = 闭集里的一个词。
+ * 唯一写者 = 建行事务里的建行钩(`plugins/session-store-sql.ts` 的 `birth.record`,本事务刚建下的这一行);此后无写口(终身不改)。宽度 32 = 词表的余量。
+ * 存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`(中央建表句生成)。
+ */
+export declare const SESSION_KIND_COLUMN: SessionExtColumn;
+/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格、在删令牌与种类不在 `session_meta` 上出现过,不搬)。 */
 export declare const SESSION_EXT_COLUMNS: readonly SessionExtColumn[];
+/**
+ * 本表的索引声明(两方言共用一份;MySQL 协议方言另以内联 `KEY` 随建表句到货,存量库缺谁补谁 —— `ensure-index.ts`):种类那一列给老化候选面
+ * (`listIdleOfKind`:只读带种类的行,不扫整表)。
+ */
+export declare const SESSION_EXT_KIND_INDEX = "idx_session_ext_kind";
+export declare const SESSION_EXT_INDEXES: readonly IndexSpec[];
 /** M41 从 `session_meta` 搬进本表的那一组(计数格之前的全部格)。 */
 export declare const SESSION_EXT_MOVED_COLUMNS: readonly SessionExtColumn[];
 /** 外键约束名(两方言同名;起服探针与迁移的后置条件按名读)。 */