@sema-agent/server 7.139.0 → 7.141.0

package/dist/plugins/local-session-window.d.ts

@@ -16,6 +16,12 @@
  *    branch below the floor — so the record the engine reads is the one the run's walk reaches.
  * Read-only: the log is read once (`exportEntries`, pure), no append log is opened, and the window refuses writes.
  *
+ * ## The metadata is the store's, not the archive's
+ * Both halves come from the local session store ({@link LocalSessionRows}) — this module opens no repo of its own. The metadata is the
+ * store's one projection of the session's row (`LocalSessionStore.sessionMetadataOf`: owner, creation time and fork lineage read from the
+ * session-meta cell, the same projection the store hands the engine), never the archive header's copy — an archive rebuilt by a log swap
+ * keeps the row's creation time. The log is the store's export of the archive.
+ *
  * ## Cost: one linear walk, the engine's
  * The branch is core's own `getPathToRoot` over the whole log (the walk every engine read of a local session makes, with its stop
  * rules: an entry without a parent ends it, a parent the log does not hold is `invalid_session`, an unknown leaf is `not_found`).
@@ -29,7 +35,15 @@
  * by `getPathToRoot` and the run's resume ancestor scan (the two walks core 7.54.1 guards; this module has no walker of its own left).
  * Pinned in `test/session-log-parent-cycle.test.ts`.
  */
-import { BaseSessionStorage } from "@sema-agent/core";
+import { BaseSessionStorage, type SessionMetadata, type SessionTreeEntry } from "@sema-agent/core";
+/**
+ * What the window reads, and from whom: the local session store's row projection and its export of the log (`LocalSessionStore` is the one
+ * implementation; `store-backend.ts#localSessionRowsOf` hands it out). `undefined` / `null` = no such session.
+ */
+export interface LocalSessionRows {
+    sessionMetadataOf(sessionId: string): Promise<SessionMetadata | undefined>;
+    exportEntries(sessionId: string): Promise<SessionTreeEntry[] | null>;
+}
 export declare class LocalSessionWindow extends BaseSessionStorage {
     /** The branch below the floor, root first (empty when the window is the whole branch). */
     private readonly below;
@@ -39,7 +53,7 @@ export declare class LocalSessionWindow extends BaseSessionStorage {
     /** `SessionStorage.getEpochAnchor?()` — the nearest carrier on the branch below the floor, as stored ({@link scanEpochAnchor}).
      *  A row's `seq` is its position on the branch; the whole branch is in memory, so one page holds every row. */
     getEpochAnchor(): Promise<unknown>;
-    /** Wake the window of `sessionId` under the local data root `root`; `null` if there is no such session. */
-    static wake(root: string, sessionId: string): Promise<LocalSessionWindow | null>;
+    /** Wake the window of `sessionId` from the local session store's rows; `null` if there is no such session. */
+    static wake(rows: LocalSessionRows, sessionId: string): Promise<LocalSessionWindow | null>;
 }
 //# sourceMappingURL=local-session-window.d.ts.map

package/dist/plugins/local-session-window.js

@@ -1,5 +1,4 @@
 import { BaseSessionStorage, InMemorySessionStorage, SessionError, boundedTail } from "@sema-agent/core";
-import { createLocalSessionRepo } from "./local-session-store.js";
 import { scanEpochAnchor } from "./session-epoch-anchor.js";
 export class LocalSessionWindow extends BaseSessionStorage {
     below;
@@ -16,18 +15,13 @@ export class LocalSessionWindow extends BaseSessionStorage {
     async getEpochAnchor() {
         return scanEpochAnchor(this.below.length, async (beforeSeq) => this.below.slice(0, beforeSeq).map((entry, seq) => ({ seq, entry })).reverse(), (row) => row.entry);
     }
-    static async wake(root, sessionId) {
-        const repo = createLocalSessionRepo(root);
-        let log;
-        try {
-            log = await repo.exportEntries(sessionId);
-        }
-        catch (e) {
-            if (e.code === "not_found")
-                return null;
-            throw e;
-        }
-        const metadata = (await repo.list()).find((m) => m.id === sessionId) ?? { id: sessionId, createdAt: new Date().toISOString() };
+    static async wake(rows, sessionId) {
+        const log = await rows.exportEntries(sessionId);
+        if (log === null)
+            return null;
+        const metadata = await rows.sessionMetadataOf(sessionId);
+        if (metadata === undefined)
+            return null;
         const whole = new InMemorySessionStorage({ entries: log });
         const leafId = await whole.getLeafId();
         const branch = await whole.getPathToRoot(leafId);

package/dist/plugins/mailbox-store-sql.d.ts

@@ -3,6 +3,7 @@ import type { Pool as PgPool } from "pg";
 import type { MailboxAckResult, MailboxAppendMessage, MailboxDecision, MailboxDecisionOutcome, MailboxLease, MailboxStore } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 import type { MailboxRecipientLifecycle, MailboxRecipientTombstone } from "./mailbox-recipient-lifecycle.js";
+import type { SqlDialect } from "./sql-driver.js";
 export declare const MAILBOX_TABLE = "mailbox";
 export declare const MAILBOX_MSG_TABLE = "mailbox_message";
 /** [ref] 收件人墓碑表(预删除态的**唯一**真源;形与理由见 `mailbox-recipient-lifecycle.ts` 模块头)。
@@ -40,7 +41,7 @@ export declare function storedMailboxKeyless(scopeKey: unknown, handle: unknown)
 export declare const MAILBOX_KEYED_TABLES: readonly ["mailbox", "mailbox_message", "mailbox_tombstone"];
 export type MailboxKeyedTable = (typeof MAILBOX_KEYED_TABLES)[number];
 /** 按键删收件箱表族的一张表(两方言;参数 = [scope_key, handle])。 */
-export declare function mailboxKeyDeleteSql(dialect: "tidb" | "pg", table: MailboxKeyedTable): string;
+export declare function mailboxKeyDeleteSql(dialect: SqlDialect, table: MailboxKeyedTable): string;
 /** 店侧日志座(可选;boot 注入 `Logger`)。7.58.0 合并重扫 [medium]:坏行的 fail-closed 抛必须**响亮**——core 唯一的
  *  claimLease 调用方(peer-session-drain)吞掉该错,店不记这一笔就成了「静默永久卡箱」。抛之前记
  *  `mailbox_message_column_corrupt`(scope/handle/seq/column/code),运维按 seq 修行。

package/dist/plugins/mailbox-store-sql.js

@@ -73,7 +73,7 @@ export function storedMailboxKeyless(scopeKey, handle) {
 }
 export const MAILBOX_KEYED_TABLES = [MAILBOX_TABLE, MAILBOX_MSG_TABLE, MAILBOX_TOMBSTONE_TABLE];
 export function mailboxKeyDeleteSql(dialect, table) {
-    return dialect === "tidb" ? `DELETE FROM ${table} WHERE scope_key = ? AND handle = ?` : `DELETE FROM ${table} WHERE scope_key = $1 AND handle = $2`;
+    return dialect === "mysql" ? `DELETE FROM ${table} WHERE scope_key = ? AND handle = ?` : `DELETE FROM ${table} WHERE scope_key = $1 AND handle = $2`;
 }
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
@@ -298,7 +298,7 @@ export class TiDBMailboxStore {
             if (tomb.length > 0)
                 throw tombstonedRecipientError(scope, handle);
             if (rec.id !== undefined) {
-                const [held] = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND record_id = ? FOR UPDATE`, [scope, handle, rec.id]);
+                const [held] = await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("mysql", "hop_chain")}, ${jsonColumnText("mysql", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND record_id = ? FOR UPDATE`, [scope, handle, rec.id]);
                 const replay = replayedSeq(held, scope, handle, this.logger, { ...rec, content: asUtf8Stored(rec.content), ...(rec.from !== undefined ? { from: asUtf8Stored(rec.from) } : {}) });
                 if (replay !== undefined)
                     return replay;
@@ -323,7 +323,7 @@ export class TiDBMailboxStore {
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
-            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("tidb", "hop_chain")}, ${jsonColumnText("tidb", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
+            const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, ${jsonColumnText("mysql", "hop_chain")}, ${jsonColumnText("mysql", "peer_meta")}, decision, record_id FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
                 return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
@@ -377,7 +377,7 @@ export class TiDBMailboxStore {
             return;
         await this.tx(async (c) => {
             for (const table of MAILBOX_KEYED_TABLES)
-                await c.query(mailboxKeyDeleteSql("tidb", table), [scope, handle]);
+                await c.query(mailboxKeyDeleteSql("mysql", table), [scope, handle]);
         });
     }
     async reap(scope, now, opts) {

package/dist/plugins/memory-engine-tidb.js

@@ -108,14 +108,14 @@ export class TiDBMemoryEngineBackend {
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
-        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("mysql", "frontmatter")}, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
         return rows.map((r) => this.headerFromRow(r));
     }
     async getByIds(ids) {
         const uniq = [...new Set(ids)];
         if (uniq.length === 0)
             return [];
-        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("mysql", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
         return rows.map((r) => this.entryFromRow(r));
     }
     async search(query, scopes, opts) {
@@ -128,7 +128,7 @@ export class TiDBMemoryEngineBackend {
         if (q.size === 0)
             return [];
         const uniq = [...new Set(scopes)];
-        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("tidb", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)})`, uniq);
+        const rows = await this.selectRows(`SELECT id, scope, slug, ${jsonColumnText("mysql", "frontmatter")}, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope IN (${inPlaceholders(uniq.length)})`, uniq);
         const scored = [];
         for (const raw of rows) {
             const r = raw;
@@ -210,7 +210,7 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: "add", id: entry.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
                 return;
             }
-            const prior = await this.selectRows(`SELECT scope, slug, rev, ${jsonColumnText("tidb", "frontmatter")} FROM ${T} WHERE id = ?`, [entry.id]);
+            const prior = await this.selectRows(`SELECT scope, slug, rev, ${jsonColumnText("mysql", "frontmatter")} FROM ${T} WHERE id = ?`, [entry.id]);
             const priorRow = prior.length > 0 ? prior[0] : undefined;
             let existsById = priorRow !== undefined;
             {
@@ -295,7 +295,7 @@ export class TiDBMemoryEngineBackend {
                 slug = `${entry.slug}-${n}`;
             }
         }
-        const cur = await this.selectRows(`SELECT slug, rev, scope, ${jsonColumnText("tidb", "frontmatter")} FROM ${T} WHERE id = ?`, [patch.id]);
+        const cur = await this.selectRows(`SELECT slug, rev, scope, ${jsonColumnText("mysql", "frontmatter")} FROM ${T} WHERE id = ?`, [patch.id]);
         if (cur.length === 0) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
             return;

package/dist/plugins/memory-optout-grant-store-sql.js

@@ -126,7 +126,7 @@ export class SqlMemoryOptOutGrantStore {
 }
 export class TiDBMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {
     constructor(pool, now) {
-        super(mysqlDriver(pool), "tidb", now);
+        super(mysqlDriver(pool), "mysql", now);
     }
 }
 export class PgMemoryOptOutGrantStore extends SqlMemoryOptOutGrantStore {

package/dist/plugins/memory-run-store.d.ts

@@ -1,6 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
-import { type FenceLanded, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
+import { type FenceLanded, type FencedRun, type InProcessClaimFence, type CreateRunOutcome, type NewRunMeta, type RunIdemBinding, type RunListQuery, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
 import { type SpaceCommitClaim, type SpaceCommitReading, type SpaceCommitState } from "../workspace-space-commit.js";
 /**
@@ -83,7 +83,7 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性与 `write` 是同一个同步段。 */
-    whileHoldingClaim(sessionId: string, taskId: string, write: () => FenceLanded): boolean;
+    whileHoldingClaim(sessionId: string, taskId: string, write: (run: FencedRun) => FenceLanded): boolean;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     listRuns(opts: RunListQuery): Promise<RunRecord[]>;

package/dist/plugins/memory-run-store.js

@@ -238,7 +238,7 @@ export class MemoryRunStore {
         if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
             return false;
         r.updatedAt = new Date();
-        write();
+        write({ instanceId: r.instanceId });
         return true;
     }
     async getRun(taskId) {

package/dist/plugins/memory-sync-store-tidb.js

@@ -46,7 +46,7 @@ export class TiDBMemorySyncStore {
         this.claimLeaseMs = lease;
     }
     async getCursor(scope, peer) {
-        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("tidb", "base_revs")}, updated_at_ms FROM ${TIDB_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = ? AND peer = ?`, [scope, peer]);
+        const [rows] = await this.pool.query(`SELECT ${jsonColumnText("mysql", "base_revs")}, updated_at_ms FROM ${TIDB_MEMORY_SYNC_TABLES.syncCursor} WHERE scope = ? AND peer = ?`, [scope, peer]);
         const row = rows[0];
         if (!row)
             return undefined;
@@ -72,7 +72,7 @@ export class TiDBMemorySyncStore {
         if (limit <= 0)
             return [];
         const leasedUntilMs = nowMs + this.claimLeaseMs;
-        const [candidates] = await this.pool.query(`SELECT id, scope, entry_id, ${jsonColumnText("tidb", "payload")}, attempts, next_attempt_at_ms, last_error
+        const [candidates] = await this.pool.query(`SELECT id, scope, entry_id, ${jsonColumnText("mysql", "payload")}, attempts, next_attempt_at_ms, last_error
        FROM ${TIDB_MEMORY_SYNC_TABLES.pushQueue}
        WHERE next_attempt_at_ms <= ?
        ORDER BY next_attempt_at_ms, id
@@ -137,7 +137,7 @@ export class TiDBMemoryHistoryStore {
        ON DUPLICATE KEY UPDATE id = id`, params);
     }
     async historyOf(id) {
-        const [rows] = await this.pool.query(`SELECT id, rev, prev_rev, op, scope, ${jsonColumnText("tidb", "snapshot")}, written_at_ms
+        const [rows] = await this.pool.query(`SELECT id, rev, prev_rev, op, scope, ${jsonColumnText("mysql", "snapshot")}, written_at_ms
        FROM ${TIDB_MEMORY_SYNC_TABLES.history}
        WHERE id = ?
        ORDER BY written_at_ms ASC, rev ASC`, [id]);

package/dist/plugins/one-time-migrations.d.ts

@@ -316,6 +316,18 @@
  *      或 `storage` 时权限 / 磁盘修好)后的下一次起服照常补放置;存档移走则它不再是本服务的会话(不补放置、不再点名;fork 创建的会话例外 —— 它的格还在,读作 fork 未落定,出路是同键重试那次 fork 或删除该会话)。
  *    · **旧版在已切换库上**:≤7.137.x 起服建回空 `device_session`,随后列册对账见执行列为幽灵列拒启、零行写;再起本版 ⇒ ⓪ 删掉那张空表。回滚的唯一支持形 = 恢复切换前的备份。
  *    读数:`executionPlacementColumnsAdded` / `deviceBindingsMoved` / `deviceBindingsOrphaned`(非零 ⇒ 另一行 warn)/ `deviceBindingTablesDropped` / `executionPlacementsBackfilled` / `executionPlacementSessionsUnreadable`(点名数组 `{ sessionId, fault, errno? }`,只 local;一行一条 warn),收据只记起服日志行。
+ *  · **M33 local 存档的行事实搬进行、带戳存档改写成匿名**(7.141.0;local 独有 —— SQL 孪生的行事实本来就只在 `session_meta` 行上)—— local 店的行事实(属主 / 化身 / 执行放置 /
+ *    建档时刻 / fork 谱系)只住在会话元数据边档的那一格,引擎仓是匿名内容仓(`local-session-store.ts` 头注「规则一」):本店交给引擎仓的写一律不交属主,交出的会话元数据是那一格的一只投影。
+ *    ≤7.140.x 写下的存量 ① 格里没有建档时刻 / 谱系(那两样只在存档头上)② 换装 / 导入写下的存档头带着导入者的属主戳(及其 fork 后代 —— fork 抄戳)⇒ **一次性**:
+ *    步 0 恢复先行(上一次被打断留下的快照逐份消化,`LocalSessionStore.settleArchiveSnapshots`;起服 `ensureSchema` 先调,迁移开头再调)· 步 1 枚举(引擎仓列表 ∪ 边档全部键;
+ *    只在边档里、头读不出的 ⇒ 点名 unreadable)· 步 2 行回填(列表里每只存档:格缺 ⇒ 建一格、属主「从没被记下」;格缺建档时刻 / 谱系 ⇒ 从存档头补;一次边档提交 + 文件与目录各 fsync,
+ *    在这之前不碰任何存档)· 步 3 存档归一(每只带戳存档,在它的会话写锁里):整档一次读 → 读时跳过了记录 ⇒ 留着(`records_skipped`)→ 引擎导入闸先验(带发言者归属)不过 ⇒ 留着
+ *    (`invalid`)→ 验后与原日志不逐条相等 ⇒ 留着(`normalizes`;迁移从不改内容)→ 快照记录(core `atomicWriteFile`)→ 以这一代为条件删存档 → 匿名导入 → 删快照。
+ *    留着的存档字节不动、点名(一行一条 warn);它们之后被 fork 拒、改日志的推送答 `conflict`(读、续跑、拉取照常),出路 = 删掉会话后重推。
+ *    **快照目录的常设拒启臂**(`assertNoArchiveSnapshots`,无窗;删码后仍在):起服时数据根下的快照目录非空 ⇒ 拒启(`config.local_archive_snapshot_present`,`StoreBootRefusalError` 族)。
+ *    **回滚**:边档对象形一格是严格形,上一版不认 `createdAt` / `forkedFrom` 两键 ⇒ 读本版写过的边档严格拒启 —— 回滚的唯一支持形 = 恢复升级前的数据根备份(MIGRATION 写了:升级前备份、先停光旧副本)。
+ *    读数:`localArchiveRowFactsBackfilled` / `localArchivesAnonymized` / `localArchivesKeptStamped`(点名数组 `{ sessionId, reason }`)/ `localArchivesUnreadable`(点名数组 `{ sessionId }`)/
+ *    `localArchiveSnapshotsRecovered`;只 local(SQL 恒零 / 空)。
  *
  * ## 收据账(一次起服一只,每一条迁移同一只)
  * 每一步把它**已提交**的改写 / 删除与点名读数当场记进同一只收据账({@link MigrationReceipts}):计数随每次提交累加、行随每次提交追加、形读数在那一步落定时写。走完 ⇒
@@ -333,6 +345,7 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type AllowEntryInertReason, type GateKind } from "@sema-agent/core";
+import { type SqlDialect } from "./sql-driver.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
 import type { SchemaProbeRead } from "./schema-live-columns.js";
@@ -423,6 +436,16 @@ export interface OneTimeMigrationReport {
     /** M32 local 腿:该回填放置、却读不出的会话 —— 有 run、存档读不出(会话头读不出 / 结构走不通 / 读存档文件时抛了别的故障:权限 / 磁盘 I/O / 超大)。一个字节没写,起服不挡:
      *  该会话的请求照旧答存档的故障;存档修好(从留存副本恢复,或权限 / 磁盘修好)后的下一次起服照常补放置。点名行数组(会话 id + 故障词,`storage` 再带 errno),一行一条 warn,每次起服都报直到处置。SQL 独有的反面:SQL 没有这一形(行就是会话);SQL 恒空。 */
     readonly executionPlacementSessionsUnreadable: readonly ExecutionPlacementSessionUnreadable[];
+    /** M33:本次补了行事实(建档时刻 / fork 谱系)的会话元数据格数(含为「有存档、没有格」的会话新建的格)。local 独有;SQL 恒 0。非零 = 真写了存量行。 */
+    readonly localArchiveRowFactsBackfilled: number;
+    /** M33:本次由带属主戳改写成匿名的存档数(条目逐条相等,内容不改)。local 独有;SQL 恒 0。非零 = 真写了存量存档。 */
+    readonly localArchivesAnonymized: number;
+    /** M33:留着带戳的存档(点名 + 原因,一行一条 warn,每次起服都报直到处置)。local 独有;SQL 恒空。 */
+    readonly localArchivesKeptStamped: readonly LocalArchiveKeptStamped[];
+    /** M33:存档读不出的会话(边档里有格而存档头读不出,或整档读抛;点名,一行一条 warn,每次起服都报直到处置)。local 独有;SQL 恒空。 */
+    readonly localArchivesUnreadable: readonly LocalArchiveUnreadable[];
+    /** M33:本次起服消化掉的快照记录数(上一次被打断的改写留下的;补回 / 丢弃)。local 独有;SQL 恒 0。 */
+    readonly localArchiveSnapshotsRecovered: number;
 }
 /** 退役的两只命令桶(引擎 7.51.0 起不是桶;只给 M17 点名认)。 */
 export type RetiredSessionRuleBucket = "commandAllow" | "commandDeny";
@@ -473,6 +496,24 @@ export interface ExecutionPlacementSessionUnreadable {
     /** 仅 `fault === "storage"` 且那只故障带字符串 `code` 时在场(`EACCES` / `EIO` / `ERR_STRING_TOO_LONG` ……)。 */
     readonly errno?: string;
 }
+/**
+ * M33 留着带戳的一只存档的原因(闭集):`invalid` = 引擎导入闸不收这份日志(重导会被拒);`normalizes` = 引擎导入会改写它的内容(重导不再逐条相等);
+ * `records_skipped` = 读这只存档时跳过了读不出的记录(重写会把盘上那几行字节抹掉)。三种都一个字节不动。
+ */
+export type LocalArchiveKeptReason = "invalid" | "normalizes" | "records_skipped";
+/** M33 留着带戳的一只存档:会话 id 是点名坐标 + 原因。日志内容与盘上路径不出店。 */
+export interface LocalArchiveKeptStamped {
+    readonly sessionId: string;
+    readonly reason: LocalArchiveKeptReason;
+    /** `reason: "invalid"` 时在场:引擎导入闸拒的那一句(条目 id + 结构毛病,不含条目内容)—— 运维据它找到挡住改写的那一条。 */
+    readonly detail?: string;
+}
+/** M33 读不出的一只:会话元数据边档里有它的格而存档头读不出(会话头坏),或列表读得出头、整档读抛。一个字节没写;会话的请求照旧答存档的故障。 */
+export interface LocalArchiveUnreadable {
+    readonly sessionId: string;
+    /** 读的时候抛的那只故障带串型 `code` 时在场(`EACCES` / `EIO` / `corrupt_session` …);盘上路径与故障句不出店。 */
+    readonly errno?: string;
+}
 /** 三个形读数(M9 主键 / M17 列名 / M24 scope 列)—— 那一步**落定**之前收据账里缺席(读数行要它们齐;被打断的那一行只带已落定的)。 */
 type ShapeReadingKey = "workflowParkIndexKey" | "sessionRuleColumn" | "workflowJournalScopeColumn";
 /**
@@ -543,8 +584,8 @@ export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow,
  * 还没有日期可写)⇒ 响亮抛,不铸一句带空日期的句子。
  */
 export declare function migrationWindowEnd(id: string): string;
-/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 与 M32 的回填两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
-export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled" | "executionPlacementsBackfilled" | "askExecutionLanesBackfilled" | "executionPlacementSessionsUnreadable">;
+/** local 车道上 SQL 独有的几条(M8 / M9 / M11 / M17 / M18 / M21 / M23 / M24 / M26 / M27 / M29)的读数(M6 与 M32 的回填两车道都有、M33 只在 local,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
+export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "holderDeathCodeRowsBackfilled" | "executionPlacementsBackfilled" | "askExecutionLanesBackfilled" | "executionPlacementSessionsUnreadable" | "localArchiveRowFactsBackfilled" | "localArchivesAnonymized" | "localArchivesKeptStamped" | "localArchivesUnreadable" | "localArchiveSnapshotsRecovered">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
 export interface MigrationLogSink {
     warn(msg: string, meta?: Record<string, unknown>): void;
@@ -577,7 +618,7 @@ export interface MigrationDb {
  * 本函数**不问**退役 schema:带着它的库在更早处就被 `ensureSchema()` 自身拒掉了(起服对账一族 `schema-consistency.ts` 的探针口,先于建表);走公开序列
  * `createStoreBackend()` → `ensureSchema()` → `runOneTimeMigrations()` 的嵌入方与本服务的起服序列一样,有这一问、零动作。
  */
-export declare function runSqlOneTimeMigrations(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<OneTimeMigrationReport>;
+export declare function runSqlOneTimeMigrations(dialect: SqlDialect, pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<OneTimeMigrationReport>;
 /** M32 的起服拒码(确定的拒启表态:再等也等不来另一个答案;不是线上 wire 码,与 `config.schema_mismatch` 同一族)。 */
 export declare const EXECUTION_PLACEMENT_SWITCH_REFUSED_CODE = "config.execution_placement_switch_refused";
 /** 拒因闭集:`fence` = 切换开始之后退役绑定表里又出现了行(旧版副本 / 手工写下的);`backfill_ambiguous` = 车道表不止一项而还有要回填的存量。 */
@@ -599,14 +640,14 @@ export interface ExecutionPlacementSwitchInput {
  * M32 的 **DDL 前只读探针**(与退役 schema 探针同层、同一只调用点:`store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE):围栏与回填前提。
  * 拒在任何 DDL 之前 ⇒ 库零写。全新库(没有 `session_meta`)不判。纯读,不取 schema 锁(与退役 schema 探针同理)。
  */
-export declare function assertExecutionPlacementSwitchAdmissible(read: SchemaProbeRead, dialect: "tidb" | "pg", input: ExecutionPlacementSwitchInput): Promise<void>;
+export declare function assertExecutionPlacementSwitchAdmissible(read: SchemaProbeRead, dialect: SqlDialect, input: ExecutionPlacementSwitchInput): Promise<void>;
 /** 探针口(入参形与本文件的迁移段入口 {@link runSqlOneTimeMigrations} 同:方言 + 它的池;借一条连接,用完即还)。 */
-export declare function assertExecutionPlacementSwitchAdmissibleOnPool(dialect: "tidb" | "pg", pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<void>;
+export declare function assertExecutionPlacementSwitchAdmissibleOnPool(dialect: SqlDialect, pool: MysqlPool | PgPool, input: ExecutionPlacementSwitchInput): Promise<void>;
 /**
  * M32(规则与理由见头注 M32 段):切换已收尾(八列在 ∧ 两张绑定表都不在)⇒ 零动作;否则先复判围栏(探针之后、锁内这一刻又有旧版副本写进行 ⇒ 同一只拒),
  * 再按步骤表逐步收敛。跑在一次性迁移的锁里(与别的迁移步同一条连接)。导出给真库钉驱动「每步中断后续跑」。
  */
-export declare function switchExecutionPlacement(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts, input: ExecutionPlacementSwitchInput): Promise<void>;
+export declare function switchExecutionPlacement(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts, input: ExecutionPlacementSwitchInput): Promise<void>;
 /** {@link backfillLocalExecutionPlacements} 的结果:回填了几只会话 · 读不出而被跳过的会话(点名)。 */
 export interface LocalPlacementBackfill {
     readonly backfilled: number;
@@ -644,7 +685,7 @@ export declare function backfillLocalAskExecutionLanes(store: {
  *  ⑤ **原子换名**:TiDB 一条 `RENAME TABLE 正 TO 待删, 暂存 TO 正`,之后删待删旧表;PG 两条换名、删旧表与主键约束名改回常规名在**同一个事务**里({@link execAtomically})
  *     —— 中途死 = 整段回滚,盘上回到「正表旧形 + 暂存表」,下一次起动从 ① 重来。每一条 DDL 按后置条件收敛({@link execUntil} / {@link execAtomically})。
  */
-export declare function moveWorkflowJournalScope(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+export declare function moveWorkflowJournalScope(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts): Promise<void>;
 /**
  * M17 —— 一份存量规则体带哪几只退役命令桶(纯函数,点名判据):只认**对象上自有**的 `commandAllow` / `commandDeny` 键(不论值形 —— 坏形的退役桶照样是退役桶);
  * 不是对象 / 没有这两个键 / 条目文字里出现同名字样 ⇒ 空。不改写:新文法写不出旧命令桶的拒(头注 M17 段 ③)。
@@ -685,7 +726,7 @@ export declare function oldGrammarEntriesOf(body: unknown, rev: number): OldGram
  * 读数都记在收据账上(`sessionRuleColumn` 在落定时写:表不在(中央 DDL 之前被调到)⇒ `no-table`,不编读数;`renamed` = 本次把终名发布出来(含从进行中的名续判到底的那一次),
  * 终名改名提交之后才写;`current` = 起服时已是终名);点名的行随扫到追加。
  */
-export declare function migrateSessionRuleGrammar(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+export declare function migrateSessionRuleGrammar(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts): Promise<void>;
 /** M8 一行改写的结论:改写后的文本 / 这一行不用动 / 读不懂(解析错误原样交出,调用方计数进读数)。 */
 export type ShadowedRuleRewrite = {
     readonly kind: "rewrite";
@@ -738,7 +779,7 @@ export declare function parkedRowRepairOf(gateKindCell: unknown, gate: unknown,
  *    否则门上加 `approvalCard: "question"`、其余字节原样,经写腿的同一只编码器回写,按原文 CAS(MySQL 协议两边 `CAST(… AS BINARY)`,PG `text` 等值)+ `status = 'pending'`。
  * 每一次提交当场记进收据账。
  */
-export declare function repairParkedRows(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+export declare function repairParkedRows(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts): Promise<void>;
 /**
  * M29 —— 存量停驻行的 `approval_card` 列回填(规则、为什么、够不到的一格见头注 M29 段):列不在 ⇒ 延后(零扫描);只扫 `status = 'pending'` ∧ 列为 NULL ∧ 审批门型的行,
  * 按 `token` 键集分页,每行单独读整只文档、交给写口用的**同一只**判官({@link judgeCheckpointIndexCells} → `buildCheckpointIndexCells`,core `checkpointIndexFacts`):答出词 ⇒
@@ -746,7 +787,7 @@ export declare function repairParkedRows(db: MigrationDb, dialect: "tidb" | "pg"
  * 文档的门不是审批门)⇒ 不写;文档读不出、或派生读不了它(缺门 / 缺寄存行)⇒ 计数不写;答出的词超过列的容量(判官 {@link judgeCheckpointIndexCells} 的 `card_too_long`,
  * MySQL 协议 TEXT 65,535 UTF-8 字节)⇒ 计数 + 点名不写(同一个态度:一行手改数据不许挡整只部署起服)。每一次提交当场记进收据账。
  */
-export declare function backfillParkedApprovalCards(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+export declare function backfillParkedApprovalCards(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts): Promise<void>;
 /**
  * M23 —— 存量 placed 子代行的属主回填,**每次起服单趟、幂等**(规则、为什么、够不到的一格见头注 M23 段):键集分页扫完 placed ∧ 属主 NULL 的行,每一行按唯一判据判
  * (`judgeDelegatedOwner`,建行那一笔与停驻挂点同一只:来源顺序根、父;属主 = 这一读见证到的):
@@ -757,7 +798,7 @@ export declare function backfillParkedApprovalCards(db: MigrationDb, dialect: "t
  *  · 扫到的任何一行化身为空 ⇒ 响亮拒(不论判不判得出属主;来源行同一条律)。
  * 不重扫、不拒启:残余由下一次起服或那一行的下一次停驻定下,期间只对 fleet 调用方放行(头注 M23 段)。
  */
-export declare function inheritPlacedSessionOwners(db: MigrationDb, dialect: "tidb" | "pg", receipts: MigrationReceipts): Promise<void>;
+export declare function inheritPlacedSessionOwners(db: MigrationDb, dialect: SqlDialect, receipts: MigrationReceipts): Promise<void>;
 /**
  * 启动日志的读数行。零命中(第二跑起的常态)也照发 —— 「跑过了、什么都没改」与「压根没跑」必须可分辨。
  *