@sema-agent/server 7.146.0 → 7.147.0

package/dist/{plugins → stores-sql}/file-history-store-sql.js

@@ -1,9 +1,9 @@
 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, SqlBlobBackend } from "./blob-backend.js";
-import { mysqlDriver, pgDriver } from "./sql-driver.js";
-import { isMissingColumnError, retryOnDeadlock } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+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 { describeProbedTableDrift } from "../plugins/schema-drift-sentence.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { foldCaughtFailure } from "../file-history-disclosure.js";
 export const FILE_HISTORY_BLOB_TABLE = "file_history_blob";
@@ -28,17 +28,22 @@ export class SqlFileHistoryStore {
     pool;
     blobExchange = {
         put: (hash, bytes) => this.putExchangedBlob(hash, bytes),
-        get: (hash) => this.blobs.getBlob(hash),
-        has: (hashes) => this.blobs.hasBlobs([...hashes]),
+        get: (hash) => this.blobs.get(hash),
+        has: (hashes) => this.blobs.has([...hashes]),
     };
     blobs;
     spentAttempts = new Set();
     activeAttempts = new Set();
     boundaryKeep;
-    constructor(db, pool, blobBackend, opts) {
+    constructor(db, pool, opts) {
         this.db = db;
         this.pool = pool;
-        this.blobs = blobBackend ?? new SqlBlobBackend(this.db.dialect, this.pool, undefined, FILE_HISTORY_BLOB_TABLE);
+        this.blobs = new SqlBlobIndex(this.db.dialect, this.pool, {
+            table: FILE_HISTORY_BLOB_TABLE,
+            ...(opts?.blobs !== undefined ? { bytes: opts.blobs } : {}),
+            ...(opts?.blobSqlMaxBytes !== undefined ? { maxBytes: opts.blobSqlMaxBytes } : {}),
+            ...(opts?.log !== undefined ? { log: opts.log } : {}),
+        });
         this.boundaryKeep = resolveFileHistoryRetention(this.db.dialect === "mysql" ? "TiDBFileHistoryStore" : "PgFileHistoryStore", opts?.retention);
     }
     q(mysql, pg) {
@@ -95,7 +100,7 @@ export class SqlFileHistoryStore {
                 const baseAvailable = cap.state !== "unreadable";
                 let v1;
                 if (cap.state === "file") {
-                    await this.blobs.putBlob(cap.hash, cap.bytes);
+                    await this.blobs.put(cap.hash, cap.bytes);
                     v1 = { blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) };
                 }
                 else if (cap.state === "absent") {
@@ -344,7 +349,7 @@ export class SqlFileHistoryStore {
                     staged.set(t.keyHash, { kind: "unchanged", version: last.version });
                     continue;
                 }
-                await this.blobs.putBlob(cap.hash, cap.bytes);
+                await this.blobs.put(cap.hash, cap.bytes);
                 staged.set(t.keyHash, { kind: "changed", blobHash: cap.hash, ...(cap.mode !== undefined ? { mode: cap.mode } : {}), ...(cap.parentIdent !== undefined ? { parentIdent: cap.parentIdent } : {}) });
             }
             const verdict = boundaryPublishVerdict({ aborted: signal?.aborted === true });
@@ -471,7 +476,7 @@ export class SqlFileHistoryStore {
                     if (rec.blobHash === null)
                         target = { absent: true };
                     else {
-                        const bytes = await this.blobs.getBlob(rec.blobHash);
+                        const bytes = await this.blobs.get(rec.blobHash);
                         if (bytes === undefined) {
                             ledger.failed.push({ path: t.trackKey, reason: `blob ${rec.blobHash} missing (store integrity)` });
                             continue;
@@ -594,14 +599,14 @@ export class SqlFileHistoryStore {
         const orphans = rows.map((r) => String(r.blob_hash));
         if (orphans.length === 0)
             return 0;
-        return this.blobs.deleteBlobs(orphans);
+        return this.blobs.sweep(orphans);
     }
     async putExchangedBlob(hash, bytes) {
         if (sha256hex(bytes) !== hash) {
             return { ok: false, error: { code: "adopt_failed", message: `blob ${hash}: the bytes do not hash to this address — nothing stored`, permanence: "terminal" } };
         }
         try {
-            await this.blobs.putBlob(hash, bytes);
+            await this.blobs.put(hash, bytes);
             return { ok: true };
         }
         catch (err) {
@@ -760,7 +765,7 @@ export class SqlFileHistoryStore {
             if (existing !== null && !sameGraph) {
                 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.putBlob(hash, bytes));
+            const verified = await this.verifySourceBlobs(data, srcGetBlob, sameGraph ? undefined : (hash, bytes) => this.blobs.put(hash, bytes));
             if (!verified.ok)
                 return verified;
             if (sameGraph)
@@ -813,13 +818,13 @@ export class SqlFileHistoryStore {
     }
 }
 export class TiDBFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(mysqlDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(mysqlDriver(pool), pool, opts);
     }
 }
 export class PgFileHistoryStore extends SqlFileHistoryStore {
-    constructor(pool, blobBackend, opts) {
-        super(pgDriver(pool), pool, blobBackend, opts);
+    constructor(pool, opts) {
+        super(pgDriver(pool), pool, opts);
     }
 }
 export async function assertFileHistorySchema(query, dialect) {

package/dist/{plugins → stores-sql}/pg-session-storage.d.ts

@@ -1,15 +1,12 @@
-import { BaseSessionStorage, type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
+import { type AcquiredSession, type PlacedSessionRow, type SessionHead, type SessionMetadata, type SessionPlacementRecord, type SessionStore, type SessionTreeEntry, type SessionWriteOptions } from "@sema-agent/core";
 import type { Pool, PoolClient } from "pg";
-import type { SessionSummary } from "./store-contracts.js";
-import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
-import { type PlacementAcquireOpts } from "./session-placement.js";
+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 InstructionSourceBaseline } from "../instruction-source-notice.js";
-import type { SessionWorkspace } from "../session-workspace.js";
 import type { RetentionDeclaration } from "@sema-agent/core";
-import { type IndexSpec } from "./ensure-index.js";
-import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
-import { type ExecutionPlacementSeat } from "../execution-placement.js";
+import type { SessionWriteHooks } from "./session-write-hooks.js";
+import { type IndexSpec } from "../plugins/ensure-index.js";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "../plugins/session-fork.js";
 /**
  * PG-dialect DDL for the L1 session log, translated from tidb-pool.ts SCHEMA_STATEMENTS:
  * JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), inline `KEY`/`UNIQUE KEY`→separate CREATE INDEX (UNIQUE for uq_session_event_entry).
@@ -23,12 +20,12 @@ export declare const SESSION_INDEXES: readonly IndexSpec[];
 /** Idempotent schema apply for this store's tables (the test calls this; production aggregation is separate). */
 export declare function ensureSchema(pool: Pool | PoolClient): Promise<void>;
 /**
- * PostgreSQL-backed {@link BaseSessionStorage} — the durable L1 event log for one session.
+ * PostgreSQL-backed session storage — the durable L1 event log for one session (the window view and its reads: {@link WindowedSessionStorage}).
  *
  * Behaviourally identical to {@link TiDBSessionStorage}; see that file's class doc for the F2/F3 seams. The only
  * differences are dialectal (placeholders, `IS NOT DISTINCT FROM`, jsonb, rowCount, transaction handle).
  */
-export declare class PgSessionStorage extends BaseSessionStorage {
+export declare class PgSessionStorage extends WindowedSessionStorage {
     private readonly pool;
     private readonly sessionId;
     private readonly floorSeq;
@@ -40,16 +37,14 @@ export declare class PgSessionStorage extends BaseSessionStorage {
     static wake(pool: Pool, sessionId: string): Promise<PgSessionStorage | null>;
     /** The bounded-window floor = last compaction's firstKeptEntryId (and its seq). @see TiDBSessionStorage.computeFloor */
     private static computeFloor;
-    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — fall back to the durable log. */
-    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
-    appendEntry(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
-    setLeafId(leafId: string | null, opts?: SessionWriteOptions): Promise<void>;
+    /** Sub-floor lookups (e.g. a label target) aren't in the loaded tail — read the durable log. */
+    protected readBelowFloor(id: string): Promise<SessionTreeEntry | undefined>;
     /**
      * Atomically: CAS the meta leaf (+bump leaf_seq), then append the event at the new seq.
      * The `(session_id, seq)` primary key is the backstop — a racing writer that grabbed the same
      * seq makes our INSERT fail with a duplicate-key (23505), which we translate to a conflict too.
      */
-    private persist;
+    protected persist(entry: SessionTreeEntry, opts?: SessionWriteOptions): Promise<void>;
 }
 /**
  * PostgreSQL-backed {@link SessionStore} — the PG twin of {@link TiDBSessionStore}. Maps the
@@ -57,7 +52,7 @@ export declare class PgSessionStorage extends BaseSessionStorage {
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
-    /** 托管留存声明 = 装配交给它的词(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    /** 托管留存声明 = 装配交给它的词(TiDB 孪生同格)。读法见 `retention-declaration.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: RetentionDeclaration;
     /** [ref] C18(core 5.48.0 [ref]):placement 声明(TiDB 孪生同格,义务逐条见
      *  `src/plugins/session-placement.ts` 顶注)。 */
@@ -70,12 +65,11 @@ export declare class PgSessionStore implements SessionStore {
     readonly durability: "durable";
     /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) in one process share one. */
     private readonly pending;
-    /** 执行席(TiDB 孪生同格;实现与语句的唯一属主 = `execution-placement-sql.ts`,本店只交自己的池)。 */
-    readonly executionPlacement: ExecutionPlacementSeat;
-    /** 本店的池包成的 SqlDriver(TiDB 孪生同格):执行席与会话行格写原语的事务都经它借连接。 */
-    private readonly db;
-    constructor(pool: Pool, opts?: {
+    /** 部署的事务内钩(TiDB 孪生同格,`session-write-hooks.ts`)。 */
+    private readonly hooks;
+    constructor(pool: Pool, opts: {
         readonly retention?: RetentionDeclaration;
+        readonly hooks: SessionWriteHooks;
     });
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
@@ -107,53 +101,6 @@ export declare class PgSessionStore implements SessionStore {
     private deletePlacedSession;
     /** [ref]:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
     private assertNotPlaced;
-    /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
-    listSessions(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<SessionSummary[]>;
-    /** @see TiDBSessionStore.listSessionRows — the PG twin. */
-    listSessionRows(opts: {
-        owner?: string;
-        includeUnowned?: boolean;
-        cursor?: {
-            lastActivityAt: string;
-            sessionId: string;
-        };
-        limit: number;
-        q?: string;
-    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
-    /** @see TiDBSessionStore.sessionSummaryOf — the PG twin (same projection, run-preview subqueries scoped to the id). */
-    sessionSummaryOf(sessionId: string): Promise<SessionSummary | undefined>;
-    /** @see TiDBSessionStore.listRowOf — the PG twin. */
-    private listRowOf;
-    /** @see TiDBSessionStore.writeSessionRowCells — the PG twin (the same SQL half, `session-row-sql.ts`; only the statement text differs). */
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ClientSessionRowWrite): Promise<SessionRowWriteOutcome<SessionSummary>>;
-    writeSessionRowCells(sessionId: string, cells: SessionRowPatch, how: ReplaySessionRowWrite): Promise<ReplaySessionRowWriteOutcome<SessionSummary>>;
-    /** @see TiDBSessionStore.selectListRows — the PG twin. `where` already carries `$n` placeholders numbered over `params`;
-     *  the run scope and the LIMIT take the next numbers (PG binds by number, so text order does not matter). */
-    private selectListRows;
-    /** @see TiDBSessionStore.probeTitle — the PG twin. */
-    probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
-    /** @see TiDBSessionStore.setTitleIfNull — the PG twin (the auto-titler's NULL-only write). */
-    setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
-    /** @see TiDBSessionStore.readInstructionSource — the PG twin. */
-    readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
-    /** @see TiDBSessionStore.recordInstructionSource — the PG twin (same CAS predicate, same per-query timeout; node-pg's
-     *  `query_timeout` rejects AND pg-pool destroys that client, so a lock-stuck baseline write does not keep a pooled
-     *  connection). */
-    recordInstructionSource(sessionId: string, expected: InstructionSourceBaseline, source: string | null): Promise<void>;
-    /** @see TiDBSessionStore.readSessionWorkspace — the PG twin (same projection-as-text, same cell owner). */
-    readSessionWorkspace(sessionId: string): Promise<SessionWorkspace | undefined>;
-    /** @see TiDBSessionStore.recordSessionWorkspace — the PG twin (whole-cell overwrite fenced to the occupant; `pgSafeJsonStringify` + `::jsonb`, like every PG JSON write;
-     *  the general query surface — the pool-wide `DB_QUERY_TIMEOUT_MS` server-side `statement_timeout` bounds it, no per-call client timer). */
-    recordSessionWorkspace(sessionId: string, incarnation: string, workspace: SessionWorkspace): Promise<void>;
     /** @see TiDBSessionStore.fork — core 契约 `fork(sourceId, owner?, opts?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只;`opts.placement` 进委派分区)。 */
     fork(sourceId: string, owner?: string | null, opts?: {
         placement?: ForkPlacement;
@@ -181,16 +128,16 @@ export declare class PgSessionStore implements SessionStore {
     }): 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**
-     *  (读写序律:占行 → 锁行判是不是本次占下的 → 锁定读认领 → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
+     *  (占行 → 锁行判是不是本次占下的 → 部署的事务内钩 `import` → 事件);owner = the RE-STAMPED authenticated principal (never the bundle's). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
-    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST
-     *  (fail-closed), then the owner-guarded meta delete (`owner IS NOT DISTINCT FROM $n` = the PG `<=>`, defense-in-depth), then the
-     *  SHARED body (session_meta first, the in-txn claim read, then the old events out and the new ones in), ALL in
-     *  ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry) — unlike importEntries' fresh-only INSERT. */
+    /** @see TiDBSessionStore.replaceEntries — 2c (§7/§8) IDEMPOTENT REPLACE: core `validateEntriesForImport` gate FIRST (fail-closed), then the row
+     *  (absent ⇒ created as a fresh occupant; existing ⇒ rewritten in place only when it is the importer's — `owner IS NOT DISTINCT FROM $n`, the PG
+     *  `<=>` — and not a delegation transcript; the occupant keeps its incarnation and deployment cells), then the SHARED body (the hook, then the old
+     *  events out and the new ones in), ALL in ONE txn. Safe to run OVER an existing session (fast-forward / §8 retry). */
     replaceEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
     /** @see TiDBSessionStore.writeImportedLog — the shared write half of importEntries / replaceEntries (ONE source, no drift):
-     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = plain INSERT after the caller's owner-guarded
-     *  delete), the in-txn claim read on THIS connection (读写序律), then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
+     *  session_meta FIRST (create = occupy the row, an existing one ⇒ refused; replace = owner-guarded in-place rewrite of the locked row),
+     *  the deployment's transaction hook `import` on THIS connection, then the entries re-seq dense from 0 (ids/parents/payload/ts verbatim).
      *  Runs inside the caller's open txn (`conn` already in BEGIN); the caller owns COMMIT/ROLLBACK + the validate gate. */
     private writeImportedLog;
     /** @see TiDBSessionStore.beginImportStaging — 2c P1d-β PUSH staging: stream batches into the shadow id