@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/schema-drift-sentence.d.ts

@@ -11,7 +11,10 @@ export interface OlderWayOut {
  * 🔴 **没有销毁性的一条**:对带数据的库,任何「删库 / 重建」的指路都是教人销毁数据。
  */
 export declare function schemaWaysOut(older: OlderWayOut): readonly string[];
-/** 缺列方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。 */
+/**
+ * 旧方向的出路段(整库对账与单表探针共用;逐字钉在 `test/schema-consistency.test.ts` ⑤)。「旧」= 缺列,或声明非空而库里仍允许 NULL 的列;
+ * 打印的是语句集,不只是 ADD COLUMN:要值列的值只有部署者知道(回填那一步以注释行给出),所以这一条把「值归部署者」和「打印的语句全部生效之前拒启不松」写明。
+ */
 export declare const SCHEMA_MISMATCH_WAYS_OUT: readonly string[];
 /** 探针读口:一条 SQL → `{ rows }`(各 `assert*Schema` 的 `query` 形)。 */
 export type ProbeQuery = (sql: string) => Promise<{

package/dist/plugins/schema-drift-sentence.js

@@ -8,8 +8,8 @@ export function schemaWaysOut(older) {
     ];
 }
 export const SCHEMA_MISMATCH_WAYS_OUT = schemaWaysOut({
-    when: "missing columns",
-    action: "run the ALTER TABLE … ADD COLUMN statements printed above yourself",
+    when: "missing columns, or columns that allow NULL where this build declares NOT NULL",
+    action: "run the statements printed above yourself (where a column needs a value this build cannot choose for rows already in the table, the printed comment says so and that value is yours; this refusal stays until every printed statement has taken effect)",
 });
 export async function describeProbedTableDrift(query, dialect, tables) {
     const d = dialect === "pg" ? "pg" : "mysql";
@@ -18,9 +18,9 @@ export async function describeProbedTableDrift(query, dialect, tables) {
     try {
         const sc = await import("./schema-consistency.js");
         const diff = sc.diffSchema(await sc.expectedTableShapes(d), await readLiveColumns(read, d));
-        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [] }));
+        const missingOnly = diff.filter((m) => tables.includes(m.table) && m.missing.length > 0).map((m) => ({ ...m, ghost: [], tightened: [] }));
         if (missingOnly.length > 0)
-            return sc.describeMismatchedTables(missingOnly).join("\n");
+            return sc.describeMismatchedTables(d, missingOnly).join("\n");
         why = "this build's table definitions list no column that the database lacks on that table, so the probe and the definitions disagree";
     }
     catch (err) {

package/dist/plugins/schema-ensure-legs.d.ts

@@ -2,11 +2,20 @@ import type { PgQueryFn } from "./pg-query.js";
 import type { SqlDialect } from "./sql-driver.js";
 /** advisory lock 语句 —— 与 schema 无关,录制时跳过(但要答成功,否则 ensure* 走降级告警路径)。 */
 export declare const LOCK_RE: RegExp;
+/**
+ * [ref] `ensureIndex` 的**索引在场**探针(MySQL 臂)。答「在场」——因为**新建库**上这批索引本来就随
+ * `CREATE TABLE` 的内联 `KEY` 一起到货,而基线按定义 =「启动时对一个新库真会执行的东西」。答"零行"会让
+ * 录制里凭空多出 68 条**新建库上永不发生**的 `ALTER TABLE … ADD INDEX`,基线就成了一份撒谎的产物。
+ * ⚠️ 这条特判**只**放行索引探针:任何别的 `information_schema` 探针照旧答零行 ⇒ 残留的「探列→ALTER」
+ * seam 仍会真的发出 ALTER 并被基线生成器的 `SeamViolation`(`scripts/dump-schema.ts`)当场抓住
+ * (SCHEMA POLICY 的那半一个字没松)。
+ */
+export declare const INDEX_PROBE_RE: RegExp;
 /**
  * **「一个新库对 ensure 探针怎么答」的唯一属主**(合并复审 车HB 后收口:此前生成器录制器、`test/ensure-schema.test.ts`
  * 的假池、`test/schema-baseline-generated.test.ts` ③c 的假驱动各抄一份,[ref] 加了索引探针 + PG 锁改 `got === true`
  * 之后三份各漂一处 —— 假池答零行诱发 68 条 ALTER、③c 答 `got: 1` 让 PG 锁永远拿不到)。
- * 返回 `undefined` = 不是探针,由调用方录制 / 执行;三条例外的理由见上面三条正则的注。
+ * 返回 `undefined` = 不是探针,由调用方录制 / 执行;四条例外的理由见上面三条正则与 {@link newDatabaseSessionMetaKeyCollation} 的注。
  */
 export declare function answerEnsureProbe(text: string): {
     rows: Record<string, unknown>[];

package/dist/plugins/schema-ensure-legs.js

@@ -1,4 +1,5 @@
-import { ensureSchema } from "./tidb-pool.js";
+import { SCHEMA_STATEMENTS, ensureSchema } from "./tidb-pool.js";
+import { SESSION_META_KEY_COLLATION_PROBE } from "./session-ext-table.js";
 import { ensurePgSchema } from "./pg-pool.js";
 import { ensureTiDBMemoryEngineSchema } from "./memory-engine-tidb.js";
 import { ensurePgMemoryEngineSchema } from "./memory-engine-pg.js";
@@ -13,8 +14,15 @@ import { ensureTiDBUsageWindowSchema, ensurePgUsageWindowSchema } from "../store
 import { ensureTiDBTaskListSchema, ensurePgTaskListSchema } from "./task-list-store-sql.js";
 import { ensureTiDBDeviceSchema, ensurePgDeviceSchema } from "./device-store-sql.js";
 export const LOCK_RE = /GET_LOCK|RELEASE_LOCK|pg_(try_)?advisory/i;
-const INDEX_PROBE_RE = /FROM information_schema\.statistics\b/i;
+export const INDEX_PROBE_RE = /^\s*SHOW\s+INDEX\s+FROM\b/i;
 const PG_INDEX_VALID_RE = /FROM pg_index i WHERE i\.indexrelid = to_regclass/i;
+function newDatabaseSessionMetaKeyCollation() {
+    const stmt = SCHEMA_STATEMENTS.find((s) => s.includes("CREATE TABLE IF NOT EXISTS session_meta ("));
+    const m = stmt === undefined ? null : /\)\s*COLLATE\s+([A-Za-z0-9_]+)\s*$/.exec(stmt);
+    if (m === null)
+        throw new Error("schema-ensure-legs: the central session_meta statement carries no table-level COLLATE — cannot answer the session_ext key-collation probe for a new database");
+    return { cs: m[1].split("_")[0], coll: m[1] };
+}
 export function answerEnsureProbe(text) {
     if (LOCK_RE.test(text))
         return { rows: [{ got: true }] };
@@ -22,6 +30,8 @@ export function answerEnsureProbe(text) {
         return { rows: [{ present: 1 }] };
     if (PG_INDEX_VALID_RE.test(text))
         return { rows: [{ indisvalid: true }] };
+    if (text === SESSION_META_KEY_COLLATION_PROBE)
+        return { rows: [newDatabaseSessionMetaKeyCollation()] };
     return undefined;
 }
 function recorder() {

package/dist/plugins/schema-indexes.js

@@ -7,6 +7,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "task_active", name: "idx_task_active_task", columns: ["task_id"] },
     { table: "checkpoint", name: "idx_checkpoint_status_deadline", columns: ["status", "deadline"] },
     { table: "checkpoint", name: "idx_checkpoint_session_status", columns: ["session_id", "status"] },
+    { table: "checkpoint", name: "idx_checkpoint_host_session_status", columns: ["host_session_id", "status"] },
     { table: "resume_anchor", name: "idx_resume_anchor_session", columns: ["session_id"] },
     { table: "approval_nonce", name: "idx_approval_nonce_expires", columns: ["expires_at_ms"] },
     { table: "user_input_acceptance", name: "idx_user_input_acceptance_session", columns: ["session_id", "state", "accepted_at_ms"] },
@@ -17,6 +18,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "snapshot_blob", name: "idx_snapshot_blob_created", columns: ["created_at"] },
     { table: "file_history_version", name: "idx_file_history_version_blob", columns: ["blob_hash"] },
     { 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: "workflow_run", name: "idx_wfrun_scope_created", columns: ["scope", "created_at_ms"] },
     { table: "workflow_run", name: "idx_wfrun_scope_status", columns: ["scope", "status"] },
@@ -24,6 +26,7 @@ export const CENTRAL_SCHEMA_INDEXES = [
     { table: "workflow_park_decision", name: "idx_wfparkdec_host", columns: ["host_session_id"] },
     { table: "workflow_park_decision", name: "idx_wfparkdec_run", columns: ["run_id"] },
     { table: "workflow_completion_inbox", name: "idx_wfinbox_session_seq", columns: ["session_id", "seq"] },
+    { table: "workflow_completion_inbox", name: "uq_wfinbox_seq", columns: ["seq"], unique: true },
     { table: "workflow_inbox_fence", name: "idx_wffence_until", columns: ["until_ms"] },
     { table: "workflow_notify_journal", name: "idx_wfnotify_acked", columns: ["acked"] },
     { table: "shared_memory_store", name: "idx_shared_memory_store_scope", columns: ["scope_key", "store_id"] },

package/dist/plugins/schema-live-columns.d.ts

@@ -1,20 +1,29 @@
 /**
- * 库里**实际**的列集 —— 唯一读者([ref] 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
+ * 库里**实际**的列册 —— 唯一读者([ref] 列册探针 `schema-consistency.ts` 的对账读它;`ensure-index.ts` 的索引补建在失败之后判「是不是这张表
  * 缺这条索引的列」也读它)。叶子模块:不值依赖任何模块(列册探针那边经录制驱动 / 建表腿值依赖 `ensure-index.ts`,读者若住在那边,
  * `ensure-index.ts` 读它就是一个运行时环)。方言词是 `ensure-index.ts` 的闭集(类型边,擦除)。
+ *
+ * 一个读者、一次读:同一张目录视图的同一批行同时回答「哪些列在」(键)与「它允许 NULL 吗」(值)。两方言的「读哪张表 / 哪个 schema」
+ * (MySQL 协议 = 连接上的库;PG = `search_path` 次序里的首次命中)只在这里写一遍;只问列在不在的读者(索引补建、退役 schema 判)用 `Map.has`,不看值。
  */
 import type { SqlDialect } from "./sql-driver.js";
 /** 探针读口:一条 SQL → 行数组(两方言由调用方各自绑)。 */
 export type SchemaProbeRead = (sql: string) => Promise<Array<Record<string, unknown>>>;
+/** 库里一列的实况。`nullable` = 目录的 `is_nullable` 是 `YES`(两个目录都是 `YES` / `NO` 的闭集;读数里没有 `n` 或不是 `YES` ⇒ 不算可空,只有目录明说可空的列才被判)。 */
+export interface LiveColumn {
+    readonly nullable: boolean;
+}
+/** 库里实际的列册:表名 → (列名 → 实况)。读者交出的是只读视图(消费方只问 `has` / `get`)。 */
+export type LiveColumns = ReadonlyMap<string, ReadonlyMap<string, LiveColumn>>;
 /**
- * 库里实际的列集(表名 → 列名集合)。
+ * 库里实际的列册(表名 → 列名 → { nullable })。
  *
  * 🔴 **PG 侧读的是「查询真正会解析到的那个关系」,不是 `current_schema()`**(codex 对抗复审本轮 [medium]
  * 采纳):店里的 SQL 全是**不限定 schema** 的裸表名,它按 `search_path` **逐个** schema 解析,命中第一个;
  * 而 `current_schema()` 只是路径的第一段。两者不等的部署是真的存在(角色的 `search_path` 配了多段),那时
  * 只读第一段会让探针对「表其实住在路径后段、而且缺列」这一形**完全沉默**。⇒ 按 `current_schemas(false)`
- * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表。MySQL 协议没有这个概念(库 = 连接上的
- * `DATABASE()`),那条臂一个字不变。
+ * 的**顺序**取每张表的第一次命中 —— 探针于是与执行器看同一张表(列在不在、可不可空对同一张表说话)。MySQL 协议没有这个概念(库 = 连接上的
+ * `DATABASE()`),那条臂只有选择列多一格。
  */
-export declare function readLiveColumns(read: SchemaProbeRead, dialect: SqlDialect): Promise<Map<string, Set<string>>>;
+export declare function readLiveColumns(read: SchemaProbeRead, dialect: SqlDialect): Promise<LiveColumns>;
 //# sourceMappingURL=schema-live-columns.d.ts.map

package/dist/plugins/schema-live-columns.js

@@ -1,8 +1,8 @@
 export async function readLiveColumns(read, dialect) {
     const live = new Map();
     if (dialect !== "pg") {
-        for (const row of await read("SELECT table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = DATABASE()")) {
-            addColumn(live, row["t"], row["c"], "fold");
+        for (const row of await read("SELECT table_name AS t, column_name AS c, is_nullable AS n FROM information_schema.columns WHERE table_schema = DATABASE()")) {
+            addColumn(live, row["t"], row["c"], row["n"], "fold");
         }
         return live;
     }
@@ -13,7 +13,7 @@ export async function readLiveColumns(read, dialect) {
             order.set(s, Number(row["ord"]));
     }
     const winner = new Map();
-    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
+    for (const row of await read("SELECT table_schema AS s, table_name AS t, column_name AS c, is_nullable AS n FROM information_schema.columns WHERE table_schema = ANY (current_schemas(false))")) {
         const t = String(row["t"] ?? "");
         const rank = order.get(String(row["s"] ?? "")) ?? Number.MAX_SAFE_INTEGER;
         const held = winner.get(t);
@@ -23,20 +23,20 @@ export async function readLiveColumns(read, dialect) {
             winner.set(t, rank);
             live.delete(t);
         }
-        addColumn(live, t, row["c"], "verbatim");
+        addColumn(live, t, row["c"], row["n"], "verbatim");
     }
     return live;
 }
-function addColumn(live, table, column, mode) {
+function addColumn(live, table, column, isNullable, mode) {
     const t = mode === "fold" ? String(table ?? "").toLowerCase() : String(table ?? "");
     const c = mode === "fold" ? String(column ?? "").toLowerCase() : String(column ?? "");
     if (t === "" || c === "")
         return;
-    let set = live.get(t);
-    if (set === undefined) {
-        set = new Set();
-        live.set(t, set);
+    let columns = live.get(t);
+    if (columns === undefined) {
+        columns = new Map();
+        live.set(t, columns);
     }
-    set.add(c);
+    columns.set(c, { nullable: String(isNullable ?? "").toUpperCase() === "YES" });
 }
 //# sourceMappingURL=schema-live-columns.js.map

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

@@ -3,6 +3,7 @@ import { uuidv7 } from "@sema-agent/core";
 import { stripControlAndBidi } from "@sema-agent/settings-schema";
 import { presignS3CopyUrl, presignS3Url } from "./s3-presign.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 === "")
@@ -27,7 +28,7 @@ export function sanitizeSendFileName(name) {
     return clean.length > 0 ? clean : "file";
 }
 export function createSendUserFileIssuer(cfg, deps) {
-    const f = deps?.fetchImpl ?? fetch;
+    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) => {

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

@@ -0,0 +1,37 @@
+/**
+ * **会话的出生回执与条件撤回** —— 会话店交给提交出口(`src/submission-exit.ts`)的两张窄面。引擎的 `SessionStore` 接口一个字节不动
+ * (`register(): Promise<void>` 照旧);本服务的店在它旁边各多一只方法,包装 / 转发层逐个转发。
+ *
+ * ## 出生回执({@link SessionBirthFace.registerWithReceipt})
+ * 与 `register` 同一笔写、同一条首写律;**只有这一笔真建了新行**时交回候选化身({@link SessionBirth}:这一次 INSERT 的入参里铸的那一只,
+ * 不是登记之后的复读)。已在的行、并发登记里输的那一只 ⇒ 不交候选。出生事实不在这里判:撤回事务锁住根行之后读到的
+ * 化身**等于**候选,才是「这一次提交铸下了这只会话」(两只同属主的并发登记只有赢家的候选进了行)。
+ *
+ * ## 条件撤回({@link SessionWithdrawFace.withdrawBirth})
+ * 一只事务 / 一把根锁里:锁根行 → 行不在 ⇒ `absent`;化身或属主不是候选那一位 ⇒ `incarnation` → 有可撤集合之外的会话条目 ⇒ `content`
+ * → 认领在(判官 `judgeSessionWrite` 的 `delete` 臂)⇒ `claim` → 客户端写过(计数 > 0)⇒ `client_writes` → 有本次 run 之外的 run 行 ⇒ `runs`
+ * → 撤回出口还没启用(一次性迁移的标记未落)⇒ `upgrade_pending` → 否则删本次 run 的部署行 + 会话行(旁表随外键级联)。每一读都是**锁定读**
+ * (TiDB 悲观事务里普通 SELECT 读的是事务开始时的快照,看不到等锁期间提交的写;两方言一律 `FOR UPDATE`)。
+ */
+import type { SessionTreeEntry } from "@sema-agent/core";
+import type { RegisterReceipt, SessionBirth, WithdrawOutcome } from "../session-incarnation.js";
+/** 出生回执面(会话店的窄面;`register` 的同笔写形)。 */
+export interface SessionBirthFace {
+    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+}
+/** 条件撤回面(会话店的窄面;部署装配在店上,一只事务里判完、删完)。`ownTaskId` = 本次提交认领赢的那条 run(没有 ⇒ 缺)。 */
+export interface SessionWithdrawFace {
+    withdrawBirth(birth: SessionBirth, ownTaskId: string | undefined): Promise<WithdrawOutcome>;
+}
+/** 店上的出生回执面(没有 ⇒ `undefined`:登记照走 `register`,不交候选 ⇒ 这只会话永不撤回)。 */
+export declare function birthFaceOf(store: unknown): SessionBirthFace | undefined;
+/** 店上的条件撤回面(没有 ⇒ `undefined`:候选不交给出口 ⇒ 永不撤回)。 */
+export declare function withdrawFaceOf(store: unknown): SessionWithdrawFace | undefined;
+/**
+ * 可撤集合的 A 组:引擎在受理之前 / 收尾时写下的记账条目(不进模型上下文的那些型)。引擎的条目型闭集逐型判 —— 引擎加一型 ⇒ 这里编译红,
+ * 新型归哪一边由人定。`false` 的五型(消息 / 会进上下文的自定义消息 / 压缩 / 标签 / 会话信息)= 内容:有一条 ⇒ 留(`content`)。
+ */
+export declare function entryTypeWithdrawable(type: SessionTreeEntry["type"]): boolean;
+/** A 组的型名单(SQL 锁定读的 `NOT IN` 参数;由 {@link entryTypeWithdrawable} 派生,不手写第二份)。 */
+export declare const WITHDRAWABLE_ENTRY_TYPES: readonly SessionTreeEntry["type"][];
+//# sourceMappingURL=session-birth.d.ts.map

package/dist/plugins/session-birth.js

@@ -0,0 +1,38 @@
+export function birthFaceOf(store) {
+    const s = store;
+    return typeof s?.registerWithReceipt === "function" ? { registerWithReceipt: s.registerWithReceipt.bind(s) } : undefined;
+}
+export function withdrawFaceOf(store) {
+    const s = store;
+    return typeof s?.withdrawBirth === "function" ? { withdrawBirth: s.withdrawBirth.bind(s) } : undefined;
+}
+export function entryTypeWithdrawable(type) {
+    switch (type) {
+        case "thinking_level_change":
+        case "model_change":
+        case "custom":
+        case "leaf":
+        case "prompt_epoch":
+        case "announced_listing":
+        case "git_announcement":
+        case "workspace_state":
+        case "session_checkout":
+        case "reminder_mark":
+            return true;
+        case "message":
+        case "custom_message":
+        case "compaction":
+        case "label":
+        case "session_info":
+            return false;
+        default: {
+            const unknownType = type;
+            throw new Error(`entryTypeWithdrawable: no entry type ${JSON.stringify(unknownType)}`);
+        }
+    }
+}
+export const WITHDRAWABLE_ENTRY_TYPES = [
+    "message", "thinking_level_change", "model_change", "compaction", "custom", "custom_message", "label", "session_info",
+    "leaf", "prompt_epoch", "announced_listing", "git_announcement", "workspace_state", "session_checkout", "reminder_mark",
+].filter(entryTypeWithdrawable);
+//# sourceMappingURL=session-birth.js.map

package/dist/plugins/session-epoch-anchor.d.ts

@@ -10,30 +10,58 @@
  * storage for the nearest carrier BELOW the floor and reads it itself. The storage returns that record **as stored**:
  *  · a `prompt_epoch` entry ⇒ the whole entry (the engine's branch walk reads the whole entry too);
  *  · a compaction whose `details.promptEpoch` is present ⇒ that restatement;
- *  · a compaction without a restatement carries nothing ⇒ the scan pages past it, to exhaustion (a session that lived
+ *  · a compaction without a restatement carries nothing ⇒ the scan walks past it, to exhaustion (a session that lived
  *    across the release that introduced epochs can hold any number of them between the floor and its pin).
  * The storage never judges the record's shape. The engine answers a current-shape record as a pin and a retired-shape
  * record by name (`legacy`, with whether it pinned a center artifact) — a storage that normalized the record first would
  * turn a session pinned under a retired shape into one with no pin, and the engine would then skip the center source's
  * handling of that pin. A record that is neither is the engine's to read as well (it reads as no record).
  *
- * `floorSeq <= 0` (a full load: the walk already reaches the root) or no carrier below the floor ⇒ `undefined`
- * (a session that predates epochs).
+ * ## "Below the floor" is the branch, not the log
+ * "Nearest below the floor" means nearest on the branch the run reads: the floor entry's parent, its parent, … to the root — the walk the
+ * engine's own `getPathToRoot` makes. The log also holds abandoned branches (a resumeAt moves the leaf in place and the next entries hang
+ * off an earlier entry): a record on one of them is not the run's, however near it is by position. So the scan follows parent links — a
+ * row is read only when it is the next ancestor; every other row is off the branch and passed. A log is append-only, so every ancestor sits
+ * at a lower position than its child: one newest-first pass over the positions below the floor meets the ancestors in order, and the scan
+ * stops at the first carrier on them (or at the root). The three storages share this walk; what they page differs only in where the rows
+ * live — the SQL twins page their `session_event` rows by `seq` (every row below the floor, the payload only on the two carrier types),
+ * the local window pages the branch it was cut from.
  *
- * What "below the floor, newest first" walks is the storage's: the SQL twins page their `session_event` rows by `seq` (their
- * window is cut by `seq` too); the local window pages the branch path it was cut from.
+ * No floor, or a floor at the root (a full load: the walk already reaches the root), or no carrier on the branch below the floor ⇒
+ * `undefined` (a session that predates epochs).
  */
 import type { SessionTreeEntry } from "@sema-agent/core";
-/** One row of a scan: its position (`seq`, the keyset cursor). What else the row holds is the storage's — it reads the entry
- *  out of the row itself ({@link scanEpochAnchor}'s `entryOf`), so a row is read only when the scan reaches it. */
+import type { SqlDialect } from "./sql-driver.js";
+/** One row of a scan: its position (`seq`, the keyset cursor), its entry id, its parent and its type. The entry itself is read out of the row
+ *  by the storage ({@link scanEpochAnchor}'s `entryOf`) only when the row is an ancestor of the floor and of a carrier type. */
 export interface EpochAnchorRow {
     readonly seq: string | number;
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly type: string;
 }
+/** Where the walk starts: the floor's position (rows below it have `seq < floor.seq`) and the floor entry's parent (`null` = the floor is the root). */
+export interface EpochFloor {
+    readonly seq: number;
+    readonly parentId: string | null;
+}
+/** The walk's start, from the window's floor entry and its position (no floor entry = a full load ⇒ no walk) — the one construction all three
+ *  storages use. */
+export declare function epochFloorOf(seq: number, floorEntry: SessionTreeEntry | undefined): EpochFloor | undefined;
+/** Page the rows `seq < beforeSeq`, newest first (an empty page = no older row). Rows off the branch may be in a page — the scan passes them. */
+export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
+/** The nearest epoch carrier on the branch below the floor, as stored; see the file header. */
+export declare function scanEpochAnchor<R extends EpochAnchorRow>(floor: EpochFloor | undefined, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
 /**
- * Page the rows `seq < beforeSeq` that may carry an epoch record, newest first (an empty page = no older row). A page may hold
- * other rows too — they carry nothing and the scan passes them.
+ * The SQL twins' page (one statement, two dialect spellings): every `session_event` row below `?` newest first, 100 a page, keyset on the
+ * primary key `(session_id, seq)`; the payload — projected as text, the one reading of a JSON column — only on the two carrier types
+ * (`carrier_payload`; `NULL` elsewhere), so the walk carries ids and parents and reads a payload only where a record can be.
  */
-export type EpochAnchorPage<R extends EpochAnchorRow> = (beforeSeq: number) => Promise<readonly R[]>;
-/** The nearest epoch carrier below `floorSeq`, as stored; see the file header. */
-export declare function scanEpochAnchor<R extends EpochAnchorRow>(floorSeq: number, page: EpochAnchorPage<R>, entryOf: (row: R) => SessionTreeEntry): Promise<unknown>;
+export declare function epochAnchorPageSql(dialect: SqlDialect): string;
+/** One row of {@link epochAnchorPageSql}, read by both twins (BIGINT `seq` may arrive as a string). */
+export interface SqlEpochAnchorRow extends EpochAnchorRow {
+    readonly payload: unknown;
+}
+/** A driver row of {@link epochAnchorPageSql} → a scan row (the one mapping both twins use). */
+export declare function sqlEpochAnchorRowOf(r: Readonly<Record<string, unknown>>): SqlEpochAnchorRow;
 //# sourceMappingURL=session-epoch-anchor.d.ts.map

package/dist/plugins/session-epoch-anchor.js

@@ -1,22 +1,44 @@
-export async function scanEpochAnchor(floorSeq, page, entryOf) {
-    if (floorSeq <= 0)
+import { jsonColumnTextExpr } from "./sql-json-column.js";
+export function epochFloorOf(seq, floorEntry) {
+    return floorEntry === undefined ? undefined : { seq, parentId: floorEntry.parentId ?? null };
+}
+const CARRIER_TYPES = new Set(["prompt_epoch", "compaction"]);
+export async function scanEpochAnchor(floor, page, entryOf) {
+    if (floor === undefined || floor.seq <= 0)
         return undefined;
-    let cursor = floorSeq;
-    for (;;) {
+    let want = floor.parentId;
+    let cursor = floor.seq;
+    while (want !== null) {
         const rows = await page(cursor);
         if (rows.length === 0)
             return undefined;
         for (const row of rows) {
-            const entry = entryOf(row);
-            if (entry.type === "prompt_epoch")
-                return entry;
-            if (entry.type === "compaction") {
-                const details = entry.details;
-                if (typeof details === "object" && details !== null && "promptEpoch" in details && details.promptEpoch !== undefined)
-                    return details.promptEpoch;
+            if (row.id !== want)
+                continue;
+            if (CARRIER_TYPES.has(row.type)) {
+                const entry = entryOf(row);
+                if (entry.type === "prompt_epoch")
+                    return entry;
+                if (entry.type === "compaction") {
+                    const details = entry.details;
+                    if (typeof details === "object" && details !== null && "promptEpoch" in details && details.promptEpoch !== undefined)
+                        return details.promptEpoch;
+                }
             }
+            want = row.parentId;
+            if (want === null)
+                return undefined;
         }
         cursor = Number(rows[rows.length - 1].seq);
     }
+    return undefined;
+}
+export function epochAnchorPageSql(dialect) {
+    const carrier = `CASE WHEN type IN ('prompt_epoch','compaction') THEN ${jsonColumnTextExpr(dialect, "payload")} END AS carrier_payload`;
+    const [sessionParam, seqParam] = dialect === "pg" ? ["$1", "$2"] : ["?", "?"];
+    return `SELECT seq, entry_id, parent_id, type, ${carrier} FROM session_event WHERE session_id = ${sessionParam} AND seq < ${seqParam} ORDER BY seq DESC LIMIT 100`;
+}
+export function sqlEpochAnchorRowOf(r) {
+    return { seq: r["seq"], id: String(r["entry_id"]), parentId: r["parent_id"] ?? null, type: String(r["type"]), payload: r["carrier_payload"] };
 }
 //# sourceMappingURL=session-epoch-anchor.js.map

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

@@ -0,0 +1,98 @@
+import { StoreBootRefusalError } from "./store-contracts.js";
+import type { SqlDialect, SqlDriver } from "./sql-driver.js";
+/** 表名(建表句、语句模块、迁移同读)。 */
+export declare const SESSION_EXT_TABLE = "session_ext";
+/** 一列:名字 + 两方言定义。 */
+export interface SessionExtColumn {
+    readonly name: string;
+    readonly mysql: string;
+    readonly pg: string;
+}
+/**
+ * 执行放置七列 + `fork_key` —— 宽度:车道词 ≤ 32、设备 id 与 `device` 表同宽 64、属主两列与设备店同宽 190、fork 键 255(服务端拼的不透明串)。
+ * 全部可空:NULL = absent / 非键控 fork。一次性迁移 M32(7.139–7.146 形:这八列在 `session_meta` 上)读同一份定义。
+ */
+export declare const EXECUTION_PLACEMENT_COLUMNS: readonly SessionExtColumn[];
+/**
+ * 客户端写计数(提交出口的撤回判据,`plugins/session-birth.ts`):**客户端可见会话态**的每一个写者(标题 / 置顶、导入、会话规则、附件绑定)在锁住根行之后、
+ * 自己的写之前同一事务 +1。读的是**写过几次**,不是格的当前值 —— 标题改回空、置顶改回 false、规则写了又删,这只会话都已经被人写过。不可空、缺省 0
+ * (行不在与行在而零写同读)。存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`(中央建表句生成)。
+ */
+export declare const CLIENT_WRITES_COLUMN: SessionExtColumn;
+/** 计数 +1 的那一句的 SET 片段(四个写者同读这一份)。 */
+export declare const BUMP_CLIENT_WRITES = "client_writes = client_writes + 1";
+/**
+ * **在删令牌** —— 会话行的三态(活 → 在删 → 没了)在 SQL 上的那一格:`NULL` = 活;非空 = 一次删除已经立了围栏、还没删完,值是那一次删除尝试的令牌(uuidv7,36 字符)。
+ * 只有删除面写它(`plugins/session-store-sql.ts`:围栏写、接管换写;终刀随根行一起删掉 —— 旁表行走外键级联),读者只比等。
+ * 在删对删除门之外的一切读者与写者读作「行不在」(头读 / 列表 / 规则 L 的认领);存量库缺这一列 ⇒ 起服列册对账拒启并给 `ALTER TABLE … ADD COLUMN`。
+ */
+export declare const DELETING_TOKEN_COLUMN: SessionExtColumn;
+/** 本表的全部格(主键之外),按建表句的列序。一次性迁移 M41 逐列从 `session_meta` 搬进来的是产品格与执行放置格(计数格与在删令牌不在 `session_meta` 上出现过,不搬)。 */
+export declare const SESSION_EXT_COLUMNS: readonly SessionExtColumn[];
+/** M41 从 `session_meta` 搬进本表的那一组(计数格之前的全部格)。 */
+export declare const SESSION_EXT_MOVED_COLUMNS: readonly SessionExtColumn[];
+/** 外键约束名(两方言同名;起服探针与迁移的后置条件按名读)。 */
+export declare const SESSION_EXT_FOREIGN_KEY = "fk_session_ext_session";
+/** 被引列 `session_meta.session_id` 的字符集与排序规则(MySQL 协议方言;外键列逐字带上,见顶注「外键列的字符集与排序规则取自被引列」)。 */
+export interface ReferencedKeyCollation {
+    readonly characterSet: string;
+    readonly collation: string;
+}
+/** 读被引列字符集 / 排序规则的那一句(只读;当前库、表 `session_meta`、列 `session_id`)。录制驱动按这一串认它、答新库的真相(`schema-ensure-legs.ts`)。 */
+export declare const SESSION_META_KEY_COLLATION_PROBE = "SELECT CHARACTER_SET_NAME AS cs, COLLATION_NAME AS coll FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'session_meta' AND COLUMN_NAME = 'session_id'";
+/** 探针读数 → 被引列的字符集与排序规则;恰一行、两格都是合形的名字才算读出,否则 `undefined`(调用方拒启,不猜)。 */
+export declare function readReferencedKeyCollation(rows: readonly unknown[]): ReferencedKeyCollation | undefined;
+/**
+ * 建表句(两方言;中央 `ensureSchema` 在 `session_meta` 之后发)。MySQL 协议方言必须给被引列的字符集与排序规则(外键列逐字带上它们);PostgreSQL 一形不收它。
+ */
+export declare function sessionExtDdl(dialect: "pg"): string;
+export declare function sessionExtDdl(dialect: "mysql", referenced: ReferencedKeyCollation): string;
+/** 旁表建不出 —— 起服拒(确定的拒启表态,起服对账一族同一个码 `config.schema_mismatch`):点名表名、外键列按被引列写下的字符集 / 排序规则(读得出时)与库的原句。 */
+export declare class SessionExtTableRefusedError extends StoreBootRefusalError {
+    readonly code = "config.schema_mismatch";
+    constructor(detail: string);
+}
+/**
+ * MySQL 协议方言建旁表(中央 `ensureSchema` 在 `session_meta` 建好之后调):读被引列的字符集 / 排序规则 → 按它铸建表句 → 建。`query` = 那条 DDL 连接上的一次查询(交回行)。
+ * 读不出被引列 ⇒ {@link SessionExtTableRefusedError};「库确定拒了这条建表句」只按本仓唯一判官的闭集认(`sql-errors.ts` 的 `isDeploymentFaultError`:建外键被库确定拒的一族 —— 两侧不相容 / 加不上外键 /
+ * 被引表缺索引、缺唯一键、缺列、打不开(不是 InnoDB)/ 约束名重复 / 选项不成立 —— 与建表被存储引擎拒 / 表级权限拒 …)⇒ 同一只拒,库答的原句与原码(errno / SQLSTATE)随拒句;认不出的错(连接类故障、TiDB 的瞬时错、锁等待超时 …,带不带 SQL 状态码都一样)原样上抛 —— 开库等待窗重试它。
+ * 本模块不自带分类:判官加一码,这里随之。
+ */
+export declare function ensureSessionExtTableMysql(query: (sql: string) => Promise<readonly unknown[]>): Promise<void>;
+/** 一条语句:文本 + 按序的参数。 */
+export interface SessionExtStatement {
+    readonly text: string;
+    readonly values: readonly unknown[];
+}
+/**
+ * 补行(行在 ⇒ 不动):旁表写者在锁住根 `session_meta` 行之后、写格之前发。MySQL 协议方言的重复键臂改一只非键列成它自己(不碰主键 —— 子表主键即外键列,
+ * 改它会让引擎做一次外键检查);PG `ON CONFLICT DO NOTHING`。外键:根行必须在(调用方锁着它)。
+ */
+export declare function ensureSessionExtRowStatement(dialect: SqlDialect, sessionId: string): SessionExtStatement;
+/**
+ * 补行的**一批**形:按一句 SELECT(交回一列 `session_id`)补旁表行,行已在 ⇒ 不动任何格 —— 与 {@link ensureSessionExtRowStatement} 同一只冲突子句。
+ * SELECT 包成派生表 `picked`(只露 `session_id`)⇒ 冲突子句里的列名只可能指本表。只给一次性迁移用(运行期的写者一律按单行补,在锁住根行之后)。
+ */
+export declare function ensureSessionExtRowsStatement(dialect: SqlDialect, selectSessionIds: string): SessionExtStatement;
+/** 旁表的外键级联在这只库上不生效 —— 起服拒的机读码(确定的拒启表态,与 `config.schema_mismatch` 同一族)。 */
+export declare const SESSION_EXT_CASCADE_REFUSED_CODE = "config.session_ext_cascade_absent";
+/** 起服拒:旁表行没有随根行删掉。继承 {@link StoreBootRefusalError}(确定的拒启表态:再等也等不来另一个答案)。 */
+export declare class SessionExtCascadeAbsentError extends StoreBootRefusalError {
+    readonly dialect: SqlDialect;
+    readonly code = "config.session_ext_cascade_absent";
+    constructor(dialect: SqlDialect);
+}
+/**
+ * 起服能力探针(fail-closed):一只事务里插一行根会话 + 一行旁表、删根行、读旁表行,**回滚**(库零写)。旁表行还在 ⇒ {@link SessionExtCascadeAbsentError}。
+ * 读不到 / 写不进 ⇒ 原样上抛(证不出级联 ≠ 通过)。调用点:起服序列在建表之后、一次性迁移之前(`boot/stores.ts`)。
+ */
+export declare function assertSessionExtCascadeOn(db: Pick<SqlDriver, "dialect" | "connect">): Promise<void>;
+/** 一条连接上的行读口(本事务的语句面:SQL 文本 + 参数 → 行)。 */
+export type SessionExtRowsOn = (text: string, values: readonly unknown[]) => Promise<ReadonlyArray<Readonly<Record<string, unknown>>>>;
+/**
+ * 锁定读这一行的在删令牌({@link DELETING_TOKEN_COLUMN};`null` = 活)。只在根 `session_meta` 行已被本事务锁住之后调(写序:根行 → 旁表)。
+ * **先补行、再锁定读**(与执行席的 `readCellOn` 同一条理由:InnoDB 可重复读下锁定读一只不在的键拿间隙锁,两只事务随后各自补行即互等);锁定读 = 最新已提交
+ * (TiDB 悲观事务的普通读读事务起点快照,读不到在本事务取锁之前刚提交的围栏)。读者:删除面的围栏 / 终刀判官、规则 L 的认领事务。
+ */
+export declare function readDeletingTokenOn(conn: SessionExtRowsOn, dialect: SqlDialect, sessionId: string): Promise<string | null>;
+//# sourceMappingURL=session-ext-table.d.ts.map