@sema-agent/server 7.150.0 → 7.151.0

package/dist/stores-sql/file-history-store-sql.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { captureFileBackupViaEnv, applyFileRestoreViaEnv, fileHistoryModeProvenDifferent, worldStillMatchesMint, annulProofFailure, boundaryPublishVerdict, fileHistoryDescribeTrackKey, fileHistoryTrackKeyOf, fileHistoryResolveTrackKey, fileHistoryExportDigest, validateFileHistoryExport, resolveFileHistoryRetention, fileHistoryBoundariesToKeep, } from "@sema-agent/core";
 import { BlobTooLargeError, SqlBlobIndex } from "./blob-index-sql.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
-import { isMissingColumnError, retryOnDeadlock } from "../plugins/sql-errors.js";
+import { isMissingColumnError, retryOnDeadlock, SqlArbitrationLostError } from "../plugins/sql-errors.js";
 import { probedMissingColumnRefusal } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
@@ -12,8 +12,9 @@ const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
 const truthy = (v) => v === true || v === 1 || v === "1";
 class StagedRefGoneError extends Error {
 }
-class ScopeSentinelVanishedError extends Error {
+class ScopeSentinelVanishedError extends SqlArbitrationLostError {
 }
+const FILE_HISTORY_SCOPED_TABLES = ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_scope"];
 function reapedEntryRefusal(entryId) {
     return {
         ok: false,
@@ -67,14 +68,17 @@ export class SqlFileHistoryStore {
                 await conn.begin();
             }
             restart = true;
-            for (const scope of ordered) {
-                await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
-                const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
-                if (!r.rows[0])
-                    throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
-            }
+            await this.lockScopeOn(conn, ordered);
         }, (err) => err instanceof ScopeSentinelVanishedError);
     }
+    async lockScopeOn(conn, scopes) {
+        for (const scope of [...new Set(scopes)].sort()) {
+            await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
+            const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
+            if (!r.rows[0])
+                throw new ScopeSentinelVanishedError(`could not acquire the scope write lock for "${scope}" (sentinel row kept vanishing)`);
+        }
+    }
     async markObserved(scope, keyHash) {
         const r = await this.db.query(this.q("UPDATE file_history_tracked SET observed_later = 1 WHERE scope = ? AND key_hash = ? AND observed_later = 0", "UPDATE file_history_tracked SET observed_later = TRUE WHERE scope = $1 AND key_hash = $2 AND observed_later = FALSE"), [scope, keyHash]);
         return r.affected;
@@ -134,7 +138,7 @@ export class SqlFileHistoryStore {
             return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} kept racing a concurrent retraction — retry` } };
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.trackEdit");
             return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${f.text}`, ...f.fault } };
         }
     }
@@ -201,7 +205,7 @@ export class SqlFileHistoryStore {
             return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} was replaced while this retraction was being proven` } };
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.annulTrack");
             return { ok: false, error: { code: "track_failed", message: `annulling the first-touch record for ${absPath} failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -309,7 +313,7 @@ export class SqlFileHistoryStore {
             }
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
             return { ok: false, error: { code: "snapshot_failed", message: f.text, ...f.fault } };
         }
         this.activeAttempts.add(lease);
@@ -412,7 +416,7 @@ export class SqlFileHistoryStore {
             catch (err) {
                 await conn.rollback().catch(() => undefined);
                 this.spentAttempts.add(lease);
-                const f = foldCaughtFailure(err);
+                const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
                 return { ok: false, error: { code: "snapshot_failed", message: `boundary for entry "${entryId}" could not be committed: ${f.text}`, ...f.fault } };
             }
             finally {
@@ -423,7 +427,7 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             this.spentAttempts.add(lease);
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.snapshot");
             return { ok: false, error: { code: "snapshot_failed", message: f.text, ...f.fault } };
         }
         finally {
@@ -491,7 +495,7 @@ export class SqlFileHistoryStore {
                     });
                 }
                 catch (err) {
-                    applied = { outcome: "failed", reason: foldCaughtFailure(err).text };
+                    applied = { outcome: "failed", reason: foldCaughtFailure(err, "sql-file-history-store.restore").text };
                 }
                 if (applied.outcome === "applied")
                     ledger.filesChanged.push(t.trackKey);
@@ -508,7 +512,7 @@ export class SqlFileHistoryStore {
         }
         catch (err) {
             const touched = empty.filesChanged.length > 0 || empty.identicalSkipped.length > 0 || empty.refused.length > 0 || empty.failed.length > 0;
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.restore");
             return { outcome: touched ? "partial" : "failed", ...empty, error: { code: "restore_failed", message: f.text, ...f.fault } };
         }
     }
@@ -578,11 +582,7 @@ export class SqlFileHistoryStore {
         try {
             await conn.begin();
             await this.lockScope(conn, scope);
-            let total = 0;
-            for (const table of ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_scope"]) {
-                const r = await conn.query(this.q(`DELETE FROM ${table} WHERE scope = ?`, `DELETE FROM ${table} WHERE scope = $1`), [scope]);
-                total += r.affected;
-            }
+            const total = await this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES);
             await conn.commit();
             return total;
         }
@@ -594,6 +594,18 @@ export class SqlFileHistoryStore {
             conn.release();
         }
     }
+    async deleteScopeOn(conn, scope) {
+        await this.lockScopeOn(conn, [scope]);
+        return this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES);
+    }
+    async deleteScopeRowsOn(conn, scope, tables) {
+        let total = 0;
+        for (const table of tables) {
+            const r = await conn.query(this.q(`DELETE FROM ${table} WHERE scope = ?`, `DELETE FROM ${table} WHERE scope = $1`), [scope]);
+            total += r.affected;
+        }
+        return total;
+    }
     async sweepOrphanBlobs() {
         const { rows } = await this.db.query("SELECT blob_hash FROM file_history_blob WHERE blob_hash NOT IN (SELECT blob_hash FROM file_history_version WHERE blob_hash IS NOT NULL)");
         const orphans = rows.map((r) => String(r.blob_hash));
@@ -612,7 +624,7 @@ export class SqlFileHistoryStore {
         catch (err) {
             if (err instanceof BlobTooLargeError)
                 return { ok: false, error: { code: "adopt_failed", message: err.message, permanence: "terminal", blobCap: { wallSource: err.cap.source } } };
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.putExchangedBlob");
             return { ok: false, error: { code: "snapshot_failed", message: `blob ${hash} write/upload failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -650,7 +662,7 @@ export class SqlFileHistoryStore {
             }
         }
         catch (err) {
-            const f = foldCaughtFailure(err);
+            const f = foldCaughtFailure(err, "sql-file-history-store.adoptScope");
             return { ok: false, error: { code: "adopt_failed", message: `adoptScope failed: ${f.text}`, ...f.fault } };
         }
     }
@@ -707,10 +719,10 @@ export class SqlFileHistoryStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            await this.lockScope(conn, scope);
-            const out = await this.exportOf(conn, scope, true);
+            const held = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
+            const history = held.rows[0] === undefined ? null : await this.exportOf(conn, scope, true);
             await conn.commit();
-            return { ok: true, history: out };
+            return { ok: true, history };
         }
         catch (err) {
             await conn.rollback().catch(() => undefined);
@@ -732,7 +744,7 @@ export class SqlFileHistoryStore {
                 bytes = await srcGetBlob(hash);
             }
             catch (err) {
-                const f = foldCaughtFailure(err);
+                const f = foldCaughtFailure(err, "sql-file-history-store.verifySourceBlobs");
                 return { ok: false, error: { code: "adopt_failed", message: `source blob ${hash} fetch failed: ${f.text}`, ...f.fault } };
             }
             if (bytes === undefined)
@@ -745,6 +757,40 @@ export class SqlFileHistoryStore {
         return { ok: true };
     }
     async importHistory(scope, data, srcGetBlob) {
+        const plan = await this.prepareImport(scope, data, srcGetBlob, { replace: false });
+        if (!plan.ok)
+            return plan;
+        if (plan.mode === "same")
+            return { ok: true };
+        try {
+            const conn = await this.db.connect();
+            try {
+                await conn.begin();
+                await this.lockScope(conn, scope);
+                const out = await this.publishImportLockedOn(conn, scope, data, { replace: false });
+                if (out.ok)
+                    await conn.commit();
+                else
+                    await conn.rollback();
+                return out;
+            }
+            catch (err) {
+                await conn.rollback().catch(() => undefined);
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        catch (err) {
+            return { ok: false, error: this.importFailureOf(err) };
+        }
+    }
+    importFailureOf(err) {
+        const f = foldCaughtFailure(err, "sql-file-history-store.importHistory");
+        return { code: "adopt_failed", message: `importHistory failed: ${f.text}`, ...f.fault };
+    }
+    async prepareImport(scope, data, srcGetBlob, opts) {
         try {
             const shaped = validateFileHistoryExport(data);
             if (!shaped.ok)
@@ -762,59 +808,51 @@ export class SqlFileHistoryStore {
                 return exported;
             const existing = exported.history;
             const sameGraph = existing !== null && fileHistoryExportDigest(existing) === fileHistoryExportDigest(data);
-            if (existing !== null && !sameGraph) {
+            if (existing !== null && !sameGraph && !opts.replace) {
                 return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" already holds a DIFFERENT history — a first import requires an empty target and a retry is legal only for the identical envelope (atomic visibility prevents half-graphs; this law prevents publishing the wrong complete graph over locally-grown history)` } };
             }
             const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.put(hash, bytes));
             if (!verified.ok)
                 return verified;
-            if (sameGraph)
-                return { ok: true };
-            const conn = await this.db.connect();
-            try {
-                await conn.begin();
-                await this.lockScope(conn, scope);
-                if (!(await this.scopeEmpty(conn, scope, true))) {
-                    const now = await this.exportOf(conn, scope, true);
-                    if (now !== null && fileHistoryExportDigest(now) === fileHistoryExportDigest(data)) {
-                        await conn.commit();
-                        return { ok: true };
-                    }
-                    await conn.rollback();
-                    return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" gained a DIFFERENT history while this import was fetching blobs — nothing was published` } };
-                }
-                const now = Date.now();
-                for (const t of data.tracked) {
-                    const keyHash = sha256hex(t.relOrAbsPath);
-                    await conn.query(this.q("INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES (?,?,?,?,?,?,0,?)", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6,FALSE,$7)"), [scope, keyHash, t.relOrAbsPath, t.keyKind, t.keyFamily, this.bool(t.baseAvailable), now]);
-                    for (const v of t.versions) {
-                        await conn.query(this.q("INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES (?,?,?,?,?,?,?)", "INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [scope, keyHash, v.version, v.blobHash, v.mode ?? null, v.parentIdent ?? null, v.backupTime]);
-                    }
-                }
-                const seqBase = await conn.query(this.q("SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = ?", "SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = $1"), [scope]);
-                let publishSeq = Number(seqBase.rows[0].s);
-                for (const b of data.boundaries) {
-                    publishSeq += 1;
-                    await conn.query(this.q("INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, now, publishSeq]);
-                    for (const f of b.files) {
-                        await conn.query(this.q("INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, sha256hex(f.relOrAbsPath), f.version]);
-                    }
-                }
-                await conn.commit();
+            return { ok: true, mode: sameGraph ? "same" : "publish" };
+        }
+        catch (err) {
+            return { ok: false, error: this.importFailureOf(err) };
+        }
+    }
+    async publishImportOn(conn, scope, data, plan, opts) {
+        if (plan.mode === "same")
+            return { ok: true };
+        await this.lockScopeOn(conn, [scope]);
+        return this.publishImportLockedOn(conn, scope, data, opts);
+    }
+    async publishImportLockedOn(conn, scope, data, opts) {
+        if (!(await this.scopeEmpty(conn, scope, true))) {
+            const held = await this.exportOf(conn, scope, true);
+            if (held !== null && fileHistoryExportDigest(held) === fileHistoryExportDigest(data))
                 return { ok: true };
-            }
-            catch (err) {
-                await conn.rollback().catch(() => undefined);
-                throw err;
-            }
-            finally {
-                conn.release();
+            if (!opts.replace)
+                return { ok: false, error: { code: "conflict", message: `importHistory target "${scope}" gained a DIFFERENT history while this import was fetching blobs — nothing was published` } };
+            await this.deleteScopeRowsOn(conn, scope, FILE_HISTORY_SCOPED_TABLES.filter((t) => t !== "file_history_scope"));
+        }
+        const now = Date.now();
+        for (const t of data.tracked) {
+            const keyHash = sha256hex(t.relOrAbsPath);
+            await conn.query(this.q("INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES (?,?,?,?,?,?,0,?)", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6,FALSE,$7)"), [scope, keyHash, t.relOrAbsPath, t.keyKind, t.keyFamily, this.bool(t.baseAvailable), now]);
+            for (const v of t.versions) {
+                await conn.query(this.q("INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES (?,?,?,?,?,?,?)", "INSERT INTO file_history_version (scope, key_hash, version, blob_hash, mode, parent_ident, backup_time) VALUES ($1,$2,$3,$4,$5,$6,$7)"), [scope, keyHash, v.version, v.blobHash, v.mode ?? null, v.parentIdent ?? null, v.backupTime]);
             }
         }
-        catch (err) {
-            const f = foldCaughtFailure(err);
-            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${f.text}`, ...f.fault } };
+        const seqBase = await conn.query(this.q("SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = ?", "SELECT COALESCE(MAX(publish_seq), 0) AS s FROM file_history_boundary WHERE scope = $1"), [scope]);
+        let publishSeq = Number(seqBase.rows[0].s);
+        for (const b of data.boundaries) {
+            publishSeq += 1;
+            await conn.query(this.q("INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, now, publishSeq]);
+            for (const f of b.files) {
+                await conn.query(this.q("INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES (?,?,?,?)", "INSERT INTO file_history_boundary_file (scope, entry_id, key_hash, version) VALUES ($1,$2,$3,$4)"), [scope, b.entryId, sha256hex(f.relOrAbsPath), f.version]);
+            }
         }
+        return { ok: true };
     }
 }
 export class TiDBFileHistoryStore extends SqlFileHistoryStore {

package/dist/stores-sql/pg-session-storage.d.ts

@@ -2,9 +2,9 @@ import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type Ses
 import type { Pool, PoolClient } from "pg";
 import { WindowedSessionStorage } from "./windowed-session-storage.js";
 import { type PlacementAcquireOpts } from "../plugins/session-placement.js";
-import { type StagingHandle } from "../session-sync-kernel.js";
+import { type EntriesStreamOptions, type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type RegisterReceipt, type WithdrawOutcome } from "../session-incarnation.js";
+import { type RegisterReceipt, type SessionFace, type WithdrawOutcome } from "../session-incarnation.js";
 import type { SessionWriteHooks } from "./session-write-hooks.js";
 import { type IndexSpec } from "../plugins/ensure-index.js";
 import { type SessionDeleteCondition } from "./tidb-session-store.js";
@@ -78,7 +78,7 @@ export declare class PgSessionStore implements SessionStore {
     /** Idempotently create a session_meta row with an owner (core `SessionStore.register`). Existing owner is never overwritten. */
     register(sessionId: string, owner: string | null): Promise<void>;
     /** 出生回执面(TiDB 孪生 {@link TiDBSessionStore.registerWithReceipt} 同义:候选 = 这一次 INSERT 入参里铸的化身)。 */
-    registerWithReceipt(sessionId: string, owner: string | null): Promise<RegisterReceipt>;
+    registerWithReceipt(sessionId: string, owner: string | null, kind?: string): Promise<RegisterReceipt>;
     /** 条件删除(TiDB 孪生 {@link TiDBSessionStore.deleteSessionIf} 同义)。 */
     deleteSessionIf(sessionId: string, cond: SessionDeleteCondition): Promise<WithdrawOutcome>;
     /** acquire 的建行(唯一一处;placed 会话的属主 = `placement.owner` 原样,core 7.62.0 [ref] 盒义务 7 —— TiDB 孪生同名方法同注)。 */
@@ -86,6 +86,8 @@ export declare class PgSessionStore implements SessionStore {
     /** The one session_meta INSERT. Existing owner is never overwritten.
      *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     private insertMeta;
+    /** {@link insertMeta} 那一句,发在给定的连接上(带种类的登记在自己的事务连接上发)。 */
+    private insertMetaOn;
     /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
@@ -128,10 +130,7 @@ export declare class PgSessionStore implements SessionStore {
      *  held connection across the stream → a slow consumer can't pin one). Start cursor = afterSeq ?? -1 (0-based dense).
      *  Resolves to null (NOT an empty iterable) for a missing session — eager `session_meta` probe (BIGINT seq comes
      *  back as a STRING in node-pg → always Number(...) the cursor advance). */
-    exportEntriesStream(sessionId: string, opts?: {
-        afterSeq?: number;
-        batchSize?: number;
-    }): Promise<AsyncIterable<SessionTreeEntry> | null>;
+    exportEntriesStream(sessionId: string, opts: EntriesStreamOptions): Promise<AsyncIterable<SessionTreeEntry> | null>;
     /** @see TiDBSessionStore.importEntries — 2c session-sync IMPORT: core `validateEntriesForImport` gate FIRST (fail-closed),
      *  then persist its verbatim output (re-seq dense from 0, ids/parents/payload/ts unchanged) in ONE txn, **lock-or-create, meta first**
      *  (占行 → 锁行判是不是本次占下的 → 部署的事务内钩 `import` → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
@@ -160,4 +159,32 @@ export declare class PgSessionStore implements SessionStore {
     get size(): number;
     dispose(): void;
 }
+/**
+ * 2c session-sync P1d-β — the PG twin of {@link TiDBStagingHandle} (behaviourally identical; only the SQL dialect
+ * differs: `$n` placeholders, `$n::jsonb`, `ON CONFLICT (session_id, entry_id) DO NOTHING`, rowCount, FOR UPDATE,
+ * BEGIN/COMMIT handle). Streams entry batches into a shadow session_event partition, then atomically RENAMEs them
+ * onto the real session id in ONE txn; session_meta is locked (or claimed, for a fresh push) first and settled last, COMMIT = the commit point.
+ */
+/** 暂存句柄(会话同步的推送腿逐批写、提交、撤销;由本店的 `stageImport` 交出)。导出只为组合座给它封口(店边界)。 */
+export declare class PgStagingHandle implements StagingHandle {
+    private readonly pool;
+    private readonly hooks;
+    readonly realSessionId: string;
+    readonly stagingId: string;
+    private nextSeq;
+    private readonly seen;
+    constructor(pool: Pool, hooks: SessionWriteHooks, realSessionId: string, stagingId: string);
+    /** @see TiDBStagingHandle.appendBatch — DENSE re-seq (skip already-staged ids), idempotent ON CONFLICT (session_id,
+     *  entry_id) DO NOTHING, one txn/batch. */
+    appendBatch(entries: SessionTreeEntry[]): Promise<void>;
+    /** @see TiDBStagingHandle.commit — the atomic swap: owner CAS first (lock / claim the session_meta row) → in-commit re-classify (FOR UPDATE)
+     *  → purge dst → rename staging→real → settle session_meta. Throws StagedCommitOccupantChangedError when the owner cell is not the judged one,
+     *  SyncConflictError on an unconsented fork/stale flip. */
+    commit(owner: string | null, opts: StagedCommitOptions): Promise<{
+        relation: SyncRelation["relation"];
+        face: SessionFace;
+    }>;
+    /** @see TiDBStagingHandle.abort — DELETE the staging rows. Idempotent. */
+    abort(): Promise<void>;
+}
 //# sourceMappingURL=pg-session-storage.d.ts.map

package/dist/stores-sql/pg-session-storage.js

@@ -8,7 +8,7 @@ import { pgSafeJsonStringify } from "../plugins/pg-safe-json.js";
 import { toIso } from "../plugins/sql-row-helpers.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertCells, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "../plugins/session-placement.js";
 import { contentForkRelation, fastForwardSharedContentDiverged } from "../session-sync-content.js";
-import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
+import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOccupantChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
 import { isPgUniqueViolation } from "../plugins/sql-errors.js";
 import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
 import { SESSION_META_INCARNATION_COLUMN, SESSION_META_LINEAGE_COLUMNS, forkLineageOfRow, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
@@ -224,14 +224,33 @@ export class PgSessionStore {
     async register(sessionId, owner) {
         await this.registerWithReceipt(sessionId, owner);
     }
-    async registerWithReceipt(sessionId, owner) {
+    async registerWithReceipt(sessionId, owner, kind) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
         const incarnation = mintSessionIncarnation();
-        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        if (kind === undefined) {
+            await this.insertMeta(sessionId, owner, undefined, incarnation);
+            return { minted: { sessionId, owner, incarnation } };
+        }
+        const conn = await this.pool.connect();
+        try {
+            await conn.query("BEGIN");
+            await this.insertMetaOn(conn, sessionId, owner, undefined, incarnation);
+            const res = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            if (res.rows[0]?.incarnation === incarnation)
+                await this.hooks.birth.record(statementsOn(conn), { rootSessionId: sessionId, kind });
+            await conn.query("COMMIT");
+        }
+        catch (err) {
+            await conn.query("ROLLBACK").catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
         return { minted: { sessionId, owner, incarnation } };
     }
     async deleteSessionIf(sessionId, cond) {
@@ -254,9 +273,12 @@ export class PgSessionStore {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
     async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
+        await this.insertMetaOn(this.pool, sessionId, owner, placement, incarnation);
+    }
+    async insertMetaOn(on, sessionId, owner, placement, incarnation) {
         const now = new Date();
         const placed = placementInsertCells(placement, now);
-        await this.pool.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
+        await on.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}) ` +
             "VALUES ($1,$2,$3,$4,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, incarnation, ...placed.values]);
     }
     async placementOf(sessionId) {
@@ -318,7 +340,7 @@ export class PgSessionStore {
             }
             throw err instanceof SessionError
                 ? err
-                : new SessionError("storage", `placed session ${sessionId} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
+                : new SessionError("storage", `placed session ${sessionId} could not be deleted`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
@@ -420,11 +442,13 @@ export class PgSessionStore {
         if (metaRes.rows.length === 0)
             return null;
         const pool = this.pool;
-        const batchSize = opts?.batchSize ?? 500;
+        const batchSize = opts.batchSize ?? 500;
         async function* gen() {
-            let cursor = opts?.afterSeq ?? -1;
+            let cursor = opts.afterSeq ?? -1;
             for (;;) {
                 const res = await pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq > $2 ORDER BY seq ASC LIMIT $3`, [sessionId, cursor, batchSize]);
+                if (res.rows.length > 0)
+                    await opts.recheck();
                 for (const r of res.rows)
                     yield decodeSessionEventPayload(r.payload, sessionId, r.seq);
                 if (res.rows.length < batchSize)
@@ -542,7 +566,7 @@ export class PgSessionStore {
         this.pending.clear();
     }
 }
-class PgStagingHandle {
+export class PgStagingHandle {
     pool;
     hooks;
     realSessionId;
@@ -583,11 +607,11 @@ class PgStagingHandle {
             await conn.query("BEGIN");
             const now = new Date();
             const minted = mintSessionIncarnation();
-            if (opts.expectedOwner !== undefined) {
-                const cas = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [this.realSessionId, opts.expectedOwner]);
+            if (opts.expectedOccupant !== undefined) {
+                const cas = await conn.query("UPDATE session_meta SET leaf_seq = leaf_seq + 1 WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND incarnation = $3", [this.realSessionId, opts.expectedOccupant.owner, opts.expectedOccupant.incarnation]);
                 if (cas.rowCount !== 1) {
                     await conn.query("ROLLBACK");
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             else {
@@ -595,7 +619,7 @@ class PgStagingHandle {
                 const claimed = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [this.realSessionId]);
                 if (String(claimed.rows[0]?.incarnation) !== minted) {
                     await conn.query("ROLLBACK");
-                    throw new StagedCommitOwnerChangedError(this.realSessionId);
+                    throw new StagedCommitOccupantChangedError(this.realSessionId);
                 }
             }
             settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
@@ -607,7 +631,7 @@ class PgStagingHandle {
                 throw new SessionError("placement_refused", `session ${this.realSessionId} belongs to the ${dstMeta.rows[0].placement_kind} placement partition — a session-sync staged commit cannot overwrite a delegation transcript`);
             }
             const srcIds = staged.rows.map((r) => String(r.entry_id));
-            const dstIds = opts.expectedOwner !== undefined ? dst.rows.map((r) => String(r.entry_id)) : null;
+            const dstIds = opts.expectedOccupant !== undefined ? dst.rows.map((r) => String(r.entry_id)) : null;
             const rel = classifySyncRelationshipByIds(srcIds, dstIds);
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
                 await conn.query("ROLLBACK");

package/dist/stores-sql/retention-store-sql.d.ts

@@ -301,15 +301,7 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * background-agent 活锚 / checkpoint 的 scope+status+deadline 复合索引)是独立一车,已进交接清单。
      */
     private countPinnedExpiryCandidates;
-    /**
-     * 会话树的**四条活引用腿**的 SQL 谓词(`sm` = session_meta 的别名)。写成一处的理由与 {@link horizonArms}
-     * 相同,而且更重:它同时是「可删候选」的否定谓词与「被保护计数」的肯定谓词,两份手抄必然在某次改动后分家,
-     * 而分家的方向是**多删**(候选放宽、计数收紧,两边都不会有人红)。
-     *
-     * 腿的词表:活跑 claim / 挂起 park / 活着的后台子代(running|parked,三根会话锚)/ 在跑的 workflow
-     * (`originatingSessionId` 住在 run blob 里 ⇒ JSON 提取是真方言分叉)。fork 子代**结构上没有边**,
-     * 理由见 {@link SqlRetentionStore.deleteExpiredSessions} 的头注。
-     */
+    /** 会话树的活引用谓词(`sm` = session_meta 的别名):唯一写法在 `plugins/retention-sql.ts` 的 `sessionLiveReferenceSql`(候选的否定与被保护计数的肯定同读;会话老化的候选面与锁内重判同读)。 */
     private liveReferenceExists;
     /**
      * 本域过视界、**当下被活引用护住**的会话数 = receipt 的 `skipped`。

package/dist/stores-sql/retention-store-sql.js

@@ -1,7 +1,7 @@
 import { peerSessionBoxHandle } from "@sema-agent/core";
 import { incarnationFromCell } from "../session-incarnation.js";
 import { MANAGED_RETENTION } from "../plugins/retention-declaration.js";
-import { retentionDomainWhere, retentionIdSet } from "../plugins/retention-sql.js";
+import { retentionDomainWhere, retentionIdSet, sessionLiveReferenceSql } from "../plugins/retention-sql.js";
 import { dropMailboxBoxOn } from "./mailbox-store-sql.js";
 import { SEALED_EVENT, eraseSessionPolicyRowsOn } from "./session-policy-store-sql.js";
 export const RETENTION_TOMBSTONE_TABLE = "retention_tombstone";
@@ -217,15 +217,7 @@ export class SqlRetentionStore {
         return Number(rows[0]?.n ?? 0);
     }
     liveReferenceExists() {
-        const workflow = this.db.dialect === "mysql"
-            ? `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND JSON_UNQUOTE(JSON_EXTRACT(wr.run, '$.originatingSessionId')) = sm.session_id)`
-            : `EXISTS (SELECT 1 FROM workflow_run wr WHERE wr.status = 'running' AND wr.run::json->>'originatingSessionId' = sm.session_id)`;
-        return (`(sm.placement_kind IS NOT NULL` +
-            ` OR EXISTS (SELECT 1 FROM task_active ta WHERE ta.session_id = sm.session_id)` +
-            ` OR EXISTS (SELECT 1 FROM checkpoint c2 WHERE c2.session_id = sm.session_id AND c2.status = 'pending')` +
-            ` OR EXISTS (SELECT 1 FROM background_agent ba WHERE ba.status IN ('running','parked')` +
-            `   AND (ba.session_id = sm.session_id OR ba.parent_session_id = sm.session_id OR ba.root_session_id = sm.session_id))` +
-            ` OR ${workflow})`);
+        return sessionLiveReferenceSql(this.db.dialect);
     }
     async countProtectedSessions(exec, input) {
         const w = this.domainWhere("sm.owner", input.domain, 1);

package/dist/stores-sql/session-policy-store-sql.d.ts

@@ -59,10 +59,16 @@ export type SessionPolicyStoreLogger = {
     warn(msg: string, fields?: Record<string, unknown>): void;
 };
 /**
- * 一次客户端写的计数(部署的格:会话规则是客户端可见的会话态,提交出口撤回一只刚铸的会话之前读这只计数)。组合座交入;店只在锁住根行、根行在、
- * 所有拒判之后、规则落行之前,同一事务、同一连接调它一次 —— 计数住部署的旁表,店目录不认识那张表。
+ * 会话根行的部署格(组合座交入;店目录不认识 `session_meta` 的列,也不认识客户端写计数住的旁表):
+ *  · `lockRoot` —— 同一连接上锁会话根行(全局锁序首句:根 `session_meta` → 别的表),答行在不在。语句是部署的「锁根行读住客」那一句
+ *    (组合座交 `plugins/session-row-sql.ts` 的 `SQL_SESSION_ROOT_SEAT`,与落定段、行格写原语、执行放置同一句),店不自写第二份;
+ *  · `countClientWrite` —— 一次客户端写的计数(会话规则是客户端可见的会话态,提交出口撤回一只刚铸的会话之前读这只计数)。店只在锁住根行、根行在、
+ *    所有拒判之后、规则落行之前,同一事务、同一连接调它一次。
  */
-export type SessionClientWriteCounter = (conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string) => Promise<void>;
+export interface SessionRootSeat {
+    lockRoot(conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string): Promise<boolean>;
+    countClientWrite(conn: SqlTxConn, dialect: SqlDriver["dialect"], sessionId: string): Promise<void>;
+}
 /**
  * 按会话抹除规则行的**唯一语句源**(店的 `deleteBySession` 在自己的事务里调;会话删除执行体 `retention-store-sql.ts` 在会话树事务里对一批会话调 ——
  * 同一组语句,`session_policy_rev_mark` 的高水位律只写这一处,core 契约 `session_policy.rev_survives_delete`)。调用方持事务。
@@ -73,9 +79,9 @@ export declare function eraseSessionPolicyRowsOn(conn: Pick<SqlTxConn, "query">,
 /** Dual-dialect durable SessionPolicyStore. See the file header for the dialect-delta ledger. */
 export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     private readonly db;
-    private readonly countClientWrite;
+    private readonly root;
     private readonly logger;
-    constructor(db: SqlDriver, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(db: SqlDriver, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
     /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
     /** 判据属主 = `sql-errors.ts`([ref] P1-①;本站点旧形已是并集形,收编后语义不变)。 */
@@ -92,6 +98,19 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
     /** Operator/owner write: CAS + tighten-only (unless operator) + rev bump, atomic in one txn; first-write race retried. */
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
+    /**
+     * 一次规则写的**语句源**(read-check-write 全在调用方的事务里;调用方已锁根行 —— {@link putRules} 自己锁,落定段在段首锁并判过住客):锁读 prior 与记号 →
+     * CAS → 引擎写口判官 → 号 → 计客户端写(`how.count`)→ 写。`how.skip(prior)` 为真 ⇒ 不写、不计,答 `{ skipped: true }`(落定重放的等内容跳过)。
+     * 首写撞主键(并发首写赢了)照旧抛出,由事务主人的重来臂接住({@link retrying} / 落定段的 `alsoRetry` 读同一只 {@link isDupKey})。
+     */
+    putRulesOn(conn: SqlTxConn, sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts: PutRulesOptions | undefined, how: {
+        readonly count: boolean;
+        readonly skip?: (prior: StoredSessionRules | null) => boolean;
+    }): Promise<StoredSessionRules | {
+        readonly skipped: true;
+    }>;
+    /** 判据属主 = `sql-errors.ts`:并发首写撞主键(落定段的重来臂读它)。 */
+    isDupKeyError(e: unknown): boolean;
     /**
      * The store's ONE retry arm: re-run the whole read-check-write transaction while the failure is an engine
      * ARBITRATION artifact rather than an answer. Two such artifacts, and only two:
@@ -164,6 +183,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *  残余(如实):记号里**已有**的世代若被列外改到 BIGINT 上界,冲突臂的 `记号.gen + 1` 在库里溢出 ⇒ 这次抹除响亮失败
      *  (驱动错误;那只记号本来就读不回,`putRules` 同样拒)—— 抹除不读记号,这一形不在本判词射程内。 */
     deleteBySession(sessionId: string): Promise<void>;
+    /** 抹除的语句源(调用方的事务里;落定段的擦除腿与 {@link deleteBySession} 同一只):交回被封的键 —— 提交**之后**经 {@link discloseErased} 报。 */
+    eraseOn(conn: SqlTxConn, sessionId: string): Promise<readonly SealedEraseKey[]>;
+    /** 抹除提交之后的响亮面(封键 ⇒ 一条 warn;无封键 ⇒ 什么都不做)。 */
+    discloseErased(sessionId: string, sealed: readonly SealedEraseKey[]): void;
     /**
      * [ref] 封键的响亮面:一次抹除至多一条 warn。走到这里删除已经提交,一次日志故障不许把它报成失败(E21 会因此 500、
      * overwrite-dst 会因此中止;codex 7.105.0 修复验证轮 [medium] 同形)⇒ 日志座抛不往外抛;**也不吞披露**:同一行落日志出口接缝的
@@ -183,10 +206,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: MySqlPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(pool: MySqlPool, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
 }
 /** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgSessionPolicyStore extends SqlSessionPolicyStore {
-    constructor(pool: PgPool, countClientWrite: SessionClientWriteCounter, logger: SessionPolicyStoreLogger);
+    constructor(pool: PgPool, root: SessionRootSeat, logger: SessionPolicyStoreLogger);
 }
 //# sourceMappingURL=session-policy-store-sql.d.ts.map