@sema-agent/server 7.145.0 → 7.147.0

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 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 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,44 +101,10 @@ 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.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?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只)。 */
-    fork(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** @see TiDBSessionStore.fork — core 契约 `fork(sourceId, owner?, opts?)` = {@link forkTo} 的投影(新铸 uuidv7 目标,`forkByFreshId`;三店同一只;`opts.placement` 进委派分区)。 */
+    fork(sourceId: string, owner?: string | null, opts?: {
+        placement?: ForkPlacement;
+    }): Promise<string | null>;
     /** @see TiDBSessionStore.forkTo — fork 续写的店契约(PG 孪生逐字同义):目标行 meta 先、主键排他;撞已在 ⇒ 回滚后在新视图读目标按属主与 fork 键分类;
      *  读不到 ⇒ 整笔重跑一次,再不行 ⇒ {@link ForkTargetUnsettledError}。 */
     forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
@@ -168,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

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

@@ -1,33 +1,38 @@
 import { emitLeafAdvance } from "../session-leaf-bus.js";
-import { BaseSessionStorage, StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement, } from "@sema-agent/core";
-import { SESSION_TITLE_MAX_CHARS, sessionRowTagKey } from "../session-row.js";
-import { writeSessionRowCellsSql } from "./session-row-sql.js";
-import { escapeLike } from "./sql-escape.js";
+import { StoredSession, SessionError, uuidv7, validateEntriesForImport, leafIdAfterEntry, admitSessionPlacement, } from "@sema-agent/core";
 import { decodeSessionEventPayload } from "./session-event-payload.js";
-import { scanEpochAnchor } from "./session-epoch-anchor.js";
-import { jsonColumnText } from "./sql-json-column.js";
-import { pgSafeJsonStringify } from "./pg-safe-json.js";
-import { toIso } from "./sql-row-helpers.js";
-import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SESSION_DURABILITY, SESSION_PLACEMENTS, } from "./session-placement.js";
+import { WindowedSessionStorage } from "./windowed-session-storage.js";
+import { scanEpochAnchor } from "../plugins/session-epoch-anchor.js";
+import { jsonColumnText } from "../plugins/sql-json-column.js";
+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, placementInsertValues, 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 { isPgUniqueViolation } from "./sql-errors.js";
-import { BASELINE_IO_DEADLINE_MS, decodeInstructionSource, encodeInstructionSource } from "../instruction-source-notice.js";
-import { SESSION_META_WORKSPACE_COLUMN, decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
-import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "./retention-store-sql.js";
-import { SESSION_META_INCARNATION_COLUMN, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
-import { ensureIndexes } from "./ensure-index.js";
-import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "./session-ownership.js";
+import { isPgUniqueViolation } from "../plugins/sql-errors.js";
+import { MANAGED_RETENTION, UNMANAGED_RETENTION } from "../plugins/retention-declaration.js";
+import { SESSION_META_INCARNATION_COLUMN, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { ensureIndexes } from "../plugins/ensure-index.js";
+import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.js";
 import { selectForkRows } from "@sema-agent/core";
-import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "./session-fork.js";
-import { pgDriver } from "./sql-driver.js";
-import { MIRROR_ON_COMMIT_GUARD, MIRROR_ON_COMMIT_SET, SESSION_META_PLACEMENT_READ_COLUMNS, createSqlExecutionPlacementSeat, importedRowCells, lockRootAndReadClaim, placementCellFromRow, readPlacementRowStatement, sessionMetaPlacementColumnsDdl } from "./execution-placement-sql.js";
-import { SessionActiveRunError, SessionWriterPresentError } from "../execution-placement.js";
-const rowsOnClient = (conn) => async (sql, values) => (await conn.query(sql, [...values])).rows;
-const isDupKey = isPgUniqueViolation;
-function baselineQuery(text, values) {
-    return { text, values, query_timeout: BASELINE_IO_DEADLINE_MS };
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf } from "../plugins/session-fork.js";
+const statementsOn = (conn) => ({
+    async query(sql, params) {
+        const res = await conn.query(sql, params ?? []);
+        return { rows: res.rows, affected: res.rowCount ?? 0 };
+    },
+});
+class HookRefusal {
+    refuse;
+    constructor(refuse) {
+        this.refuse = refuse;
+    }
+}
+function settleHookVerdict(verdict) {
+    if (verdict !== "proceed")
+        throw new HookRefusal(verdict.refuse);
 }
+const isDupKey = isPgUniqueViolation;
 export const PG_SESSION_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS session_meta (
      session_id  VARCHAR(64) COLLATE "C"  NOT NULL,
@@ -36,16 +41,8 @@ export const PG_SESSION_SCHEMA = [
      updated_at  TIMESTAMPTZ(3) NOT NULL,
      leaf_id     VARCHAR(64) COLLATE "C",
      leaf_seq    BIGINT       NOT NULL DEFAULT 0,
-     -- title: one column, two writers (TiDB twin, same name / width; law in src/session-row.ts): the user's write
-     -- (writeSessionRowCells, unconditional unless the PATCH carries expectedRowTag; null = cleared back to automatic) and the auto-titler (setTitleIfNull / probeTitle
-     -- — fills NULL only; NULL = "untitled", the three-state probe distinguishes it from "no such session").
-     title       VARCHAR(${SESSION_TITLE_MAX_CHARS}) COLLATE "C",
-     -- pinned: the user's pin (TiDB twin); every list row carries it, false by default.
-     pinned      BOOLEAN      NOT NULL DEFAULT FALSE,
-     -- instruction_source(S-690):换源通告的基线 —— TiDB 孪生同名同宽,三态读法(NULL / '' / 链成员相对路径)见那里的列注。
-     instruction_source VARCHAR(64) COLLATE "C",
-     -- workspace:本会话上一条腿自己的最后一帧 workspace_changed —— TiDB 孪生同名同义(列注与唯一属主见那里:src/plugins/session-workspace-cell.ts)。
-     ${SESSION_META_WORKSPACE_COLUMN.pg},
+     -- 引擎座表只带引擎的列;本服务记在会话上的格(标题 / 置顶 / 指令基线 / 位置与项目 / 执行放置 / fork 键)住部署旁表 session_ext
+     -- (外键级联随本行走;唯一属主 src/plugins/session-ext-table.ts)。
      -- #292 C18(core 5.48.0 design/323)subagent 转录持久化 —— placement 元组(TiDB 孪生同名同宽,
      -- 语义与六条义务见 src/plugins/session-placement.ts 顶注):创建时一次落行、first-write 不可变;
      -- placement_kind 在场 ⇒ 住在 placement 分区(不上宿主枚举 / claim 形 acquire 恒拒 / release=真删除 /
@@ -59,8 +56,6 @@ export const PG_SESSION_SCHEMA = [
      placed_at                   TIMESTAMPTZ(3),
      -- S-790 / S-506:会话化身(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN)。
      ${SESSION_META_INCARNATION_COLUMN.pg},
-     -- 执行放置(根会话行上这一位住客的一格:execution_* 七列)+ fork 键(fork_key)—— TiDB 孪生同名同义;列定义与语句的唯一属主 = src/plugins/execution-placement-sql.ts。
-     ${sessionMetaPlacementColumnsDdl("pg")},
      PRIMARY KEY (session_id)
    )`,
     `CREATE TABLE IF NOT EXISTS session_event (
@@ -85,12 +80,12 @@ export async function ensureSchema(pool) {
         await pool.query(stmt);
     await ensureIndexes((t, p) => pool.query(t, p), "pg", SESSION_INDEXES);
 }
-export class PgSessionStorage extends BaseSessionStorage {
+export class PgSessionStorage extends WindowedSessionStorage {
     pool;
     sessionId;
     floorSeq;
     constructor(pool, sessionId, metadata, entries, leafId, floorEntryId = null, floorSeq = 0) {
-        super(metadata, entries, leafId, { floorEntryId });
+        super(metadata, entries, leafId, floorEntryId);
         this.pool = pool;
         this.sessionId = sessionId;
         this.floorSeq = floorSeq;
@@ -126,24 +121,12 @@ export class PgSessionStorage extends BaseSessionStorage {
             return { floorEntryId: null, floorSeq: 0 };
         return { floorEntryId: fk, floorSeq: Number(seqRes.rows[0].seq) };
     }
-    async getEntry(id) {
-        const inMem = await super.getEntry(id);
-        if (inMem)
-            return inMem;
+    async readBelowFloor(id) {
         const res = await this.pool.query(`SELECT ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND entry_id = $2`, [this.sessionId, id]);
         if (res.rows[0] === undefined)
             return undefined;
         return decodeSessionEventPayload(res.rows[0].payload, this.sessionId, id);
     }
-    async appendEntry(entry, opts) {
-        await this.persist(entry, opts);
-        this.recordEntry(entry);
-    }
-    async setLeafId(leafId, opts) {
-        const leafEntry = this.createLeafEntry(leafId);
-        await this.persist(leafEntry, opts);
-        this.recordEntry(leafEntry);
-    }
     async persist(entry, opts) {
         const newLeaf = leafIdAfterEntry(entry);
         const conditional = opts !== undefined && opts.expectedLeafId !== undefined;
@@ -189,13 +172,11 @@ export class PgSessionStore {
     placements = SESSION_PLACEMENTS;
     durability = SESSION_DURABILITY;
     pending = new Map();
-    executionPlacement;
-    db;
-    constructor(pool, opts = {}) {
+    hooks;
+    constructor(pool, opts) {
         this.pool = pool;
         this.retention = opts.retention ?? UNMANAGED_RETENTION;
-        this.db = pgDriver(pool);
-        this.executionPlacement = createSqlExecutionPlacementSeat(this.db);
+        this.hooks = opts.hooks;
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
@@ -319,108 +300,8 @@ export class PgSessionStore {
             throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition — a session-sync ${what} cannot overwrite a delegation transcript`);
         }
     }
-    async listSessions(opts) {
-        const params = [];
-        const ph = (v) => {
-            params.push(v);
-            return `$${params.length}`;
-        };
-        const where = ["sm.placement_kind IS NULL"];
-        if (opts.owner !== undefined)
-            where.push(opts.includeUnowned ? `(sm.owner = ${ph(opts.owner)} OR sm.owner IS NULL)` : `sm.owner = ${ph(opts.owner)}`);
-        if (opts.q)
-            where.push(`EXISTS (SELECT 1 FROM task_run tr WHERE tr.session_id = sm.session_id AND LOWER(tr.objective_preview) LIKE LOWER(${ph(`%${escapeLike(opts.q)}%`)}) ESCAPE '\\')`);
-        if (opts.cursor) {
-            const a = ph(new Date(opts.cursor.lastActivityAt));
-            const b = ph(new Date(opts.cursor.lastActivityAt));
-            const sid = ph(opts.cursor.sessionId);
-            where.push(`(sm.updated_at < ${a} OR (sm.updated_at = ${b} AND sm.session_id < ${sid}))`);
-        }
-        return (await this.selectListRows({ where, params, limit: opts.limit })).map((a) => a.row);
-    }
-    async sessionSummaryOf(sessionId) {
-        return (await this.listRowOf(sessionId))?.row;
-    }
-    async listRowOf(sessionId) {
-        return (await this.selectListRows({ where: ["sm.placement_kind IS NULL", "sm.session_id = $1"], params: [sessionId], limit: 1, runSessionId: sessionId }))[0];
-    }
-    async writeSessionRowCells(sessionId, cells, how) {
-        return writeSessionRowCellsSql(this.db, sessionId, cells, how, (id) => this.listRowOf(id));
-    }
-    async selectListRows(q) {
-        const params = [...q.params];
-        const ph = (v) => {
-            params.push(v);
-            return `$${params.length}`;
-        };
-        const runWhere = q.runSessionId !== undefined ? ` WHERE session_id = ${ph(q.runSessionId)}` : "";
-        const sql = "SELECT sm.session_id, sm.owner, sm.incarnation, sm.updated_at AS last_activity, sm.created_at AS first_activity, sm.title, sm.pinned, " +
-            "  COALESCE(r.run_count, 0) AS run_count, latest.objective_preview, latest.status, latest.task_id AS last_run_id, latest.last_task_run_id " +
-            "FROM session_meta sm " +
-            "LEFT JOIN (SELECT session_id, COUNT(*) AS run_count FROM task_run" + runWhere + " GROUP BY session_id) r ON r.session_id = sm.session_id " +
-            "LEFT JOIN (SELECT DISTINCT ON (session_id) session_id, objective_preview, status, task_id, result ->> 'runId' AS last_task_run_id FROM task_run" + runWhere +
-            "  ORDER BY session_id, created_at DESC, task_id DESC) latest ON latest.session_id = sm.session_id " +
-            (q.where.length ? "WHERE " + q.where.join(" AND ") + " " : "") +
-            `ORDER BY sm.updated_at DESC, sm.session_id DESC LIMIT ${ph(q.limit)}`;
-        const res = await this.pool.query(sql, params);
-        return res.rows.map((r) => {
-            const runId = r.last_task_run_id;
-            const sessionId = String(r.session_id);
-            const owner = r.owner ?? null;
-            const incarnation = incarnationFromCell(sessionId, r.incarnation, "absent");
-            const title = r.title ?? null;
-            const pinned = r.pinned === true;
-            const row = {
-                sessionId,
-                owner,
-                lastActivityAt: r.last_activity instanceof Date ? r.last_activity.toISOString() : String(r.last_activity),
-                firstActivityAt: r.first_activity instanceof Date ? r.first_activity.toISOString() : String(r.first_activity),
-                runCount: Number(r.run_count),
-                objectivePreview: r.objective_preview ?? null,
-                lastStatus: r.status == null ? "" : String(r.status),
-                lastRunId: r.last_run_id ?? null,
-                ...(typeof runId === "string" && runId !== "" ? { lastTaskRunId: runId } : {}),
-                title,
-                pinned,
-                ...sessionRowTagKey({ sessionId, owner, incarnation, cells: { title, pinned } }),
-            };
-            return { row, occupant: { owner, incarnation } };
-        });
-    }
-    async probeTitle(sessionId) {
-        const res = await this.pool.query("SELECT title FROM session_meta WHERE session_id = $1", [sessionId]);
-        const row = res.rows[0];
-        if (!row)
-            return "none";
-        return row.title == null ? "untitled" : "titled";
-    }
-    async setTitleIfNull(sessionId, title) {
-        const res = await this.pool.query("UPDATE session_meta SET title = $1 WHERE session_id = $2 AND title IS NULL", [title, sessionId]);
-        return (res.rowCount ?? 0) > 0;
-    }
-    async readInstructionSource(sessionId) {
-        const res = await this.pool.query(baselineQuery("SELECT instruction_source FROM session_meta WHERE session_id = $1", [sessionId]));
-        return decodeInstructionSource(res.rows[0]?.instruction_source);
-    }
-    async recordInstructionSource(sessionId, expected, source) {
-        const next = encodeInstructionSource(source);
-        if (expected.recorded) {
-            await this.pool.query(baselineQuery("UPDATE session_meta SET instruction_source = $1 WHERE session_id = $2 AND instruction_source = $3", [next, sessionId, encodeInstructionSource(expected.source)]));
-        }
-        else {
-            await this.pool.query(baselineQuery("UPDATE session_meta SET instruction_source = $1 WHERE session_id = $2 AND instruction_source IS NULL", [next, sessionId]));
-        }
-    }
-    async readSessionWorkspace(sessionId) {
-        const res = await this.pool.query(`SELECT ${jsonColumnText("pg", "workspace")} FROM session_meta WHERE session_id = $1`, [sessionId]);
-        const row = res.rows[0];
-        return row === undefined ? undefined : decodeSessionWorkspaceCell(row.workspace, sessionId);
-    }
-    async recordSessionWorkspace(sessionId, incarnation, workspace) {
-        await this.pool.query("UPDATE session_meta SET workspace = $1::jsonb WHERE session_id = $2 AND incarnation = $3", [encodeSessionWorkspaceCell(workspace, pgSafeJsonStringify, sessionId), sessionId, incarnation]);
-    }
-    async fork(sourceId, owner) {
-        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    async fork(sourceId, owner, opts) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
     async forkTo(sourceId, owner, target) {
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -448,7 +329,8 @@ export class PgSessionStore {
         try {
             await conn.query("BEGIN");
             try {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, fork_key) VALUES ($1,$2,$3,$4,$5,$6,$7,$8)", [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), target.key ?? null]);
+                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, " +
+                    "placement_kind, placement_scope, placement_parent_session_id, placement_root_session_id, placement_handle, placed_at) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)", [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), ...placementInsertValues(target.placement, now)]);
             }
             catch (err) {
                 if (!isDupKey(err))
@@ -456,6 +338,8 @@ export class PgSessionStore {
                 collided = true;
             }
             if (!collided) {
+                if (target.key !== undefined)
+                    await this.hooks.keyedFork.record(statementsOn(conn), { rootSessionId: target.id, forkKey: target.key });
                 for (let seq = 0; seq < rows.length; seq++) {
                     const r = rows[seq];
                     const payload = String(r.payload);
@@ -472,14 +356,15 @@ export class PgSessionStore {
             }
             catch {
             }
+            if (err instanceof HookRefusal)
+                throw err.refuse;
             throw err instanceof SessionError ? err : new SessionError("storage", `fork of session ${sourceId} failed`, err instanceof Error ? err : undefined);
         }
         finally {
             conn.release();
         }
-        const existing = await this.pool.query("SELECT owner, fork_key FROM session_meta WHERE session_id = $1", [target.id]);
-        const row = existing.rows[0];
-        return row === undefined ? "unsettled" : classifyForkTarget(target, { owner: row.owner ?? null, forkKey: row.fork_key ?? null }, forkOwner);
+        const existing = await this.hooks.keyedFork.targetOf(target.id);
+        return existing === undefined ? "unsettled" : classifyForkTarget(target, existing, forkOwner);
     }
     async exportEntries(sessionId) {
         const metaRes = await this.pool.query("SELECT 1 FROM session_meta WHERE session_id = $1", [sessionId]);
@@ -519,7 +404,7 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            await this.writeImportedLog(conn, sessionId, owner, validated, { incarnation: mintSessionIncarnation(), forkKey: null }, "create");
+            await this.writeImportedLog(conn, sessionId, owner, validated, "create");
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -528,7 +413,9 @@ export class PgSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `import of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -542,21 +429,13 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            const placedRes = await conn.query(`SELECT ${SESSION_META_PLACEMENT_READ_COLUMNS}, fork_key FROM session_meta WHERE session_id = $1 FOR UPDATE`, [sessionId]);
-            const prior = placedRes.rows[0];
+            const lockedRes = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            const prior = lockedRes.rows[0];
             if (prior?.placement_kind != null) {
                 await conn.query("ROLLBACK");
                 throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${String(prior.placement_kind)} placement partition — a session-sync replace cannot overwrite a delegation transcript`);
             }
-            const purged = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2 AND placement_kind IS NULL", [sessionId, owner]);
-            const swapped = (purged.rowCount ?? 0) === 1 ? prior : undefined;
-            const cells = carriedRowCells(sessionId, swapped === undefined ? undefined : { incarnation: swapped.incarnation, forkKey: swapped.fork_key });
-            const priorCell = swapped === undefined ? undefined : placementCellFromRow(sessionId, swapped);
-            if (priorCell?.role === "writer") {
-                await conn.query("ROLLBACK");
-                throw new SessionWriterPresentError(sessionId, priorCell.lane);
-            }
-            await this.writeImportedLog(conn, sessionId, owner, validated, cells, "replace");
+            await this.writeImportedLog(conn, sessionId, owner, validated, prior === undefined ? "create" : "replace");
             await conn.query("COMMIT");
         }
         catch (err) {
@@ -565,7 +444,9 @@ export class PgSessionStore {
             }
             catch {
             }
-            if (err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `replace of session ${sessionId} failed`, err instanceof Error ? err : undefined);
         }
@@ -573,23 +454,26 @@ export class PgSessionStore {
             conn.release();
         }
     }
-    async writeImportedLog(conn, sessionId, owner, validated, cells, mode) {
+    async writeImportedLog(conn, sessionId, owner, validated, mode) {
         let leafId = null;
         for (const e of validated)
             leafId = leafIdAfterEntry(e);
         const now = new Date();
-        const imported = importedRowCells(cells.forkKey);
-        await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${imported.columns}) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)` +
-            (mode === "create" ? " ON CONFLICT (session_id) DO NOTHING" : ""), [sessionId, owner, now, now, leafId, validated.length, cells.incarnation, ...imported.values]);
         if (mode === "create") {
+            const minted = mintSessionIncarnation();
+            await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, leafId, validated.length, minted]);
             const held = await conn.query("SELECT incarnation FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
-            if (String(held.rows[0]?.incarnation) !== cells.incarnation) {
+            if (String(held.rows[0]?.incarnation) !== minted) {
                 throw new SessionError("storage", `import of session ${sessionId} failed`, new Error(`session ${sessionId} already exists — importEntries only creates a session (replaceEntries rewrites one); nothing was written`));
             }
         }
-        const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", sessionId);
-        if (claim.activeTaskId !== null)
-            throw new SessionActiveRunError(sessionId, claim.activeTaskId);
+        else {
+            const rewritten = await conn.query("UPDATE session_meta SET owner = $1, created_at = $2, updated_at = $3, leaf_id = $4, leaf_seq = $5 WHERE session_id = $6 AND owner IS NOT DISTINCT FROM $1 AND placement_kind IS NULL", [owner, now, now, leafId, validated.length, sessionId]);
+            if ((rewritten.rowCount ?? 0) !== 1) {
+                throw new SessionError("storage", `replace of session ${sessionId} failed`, new Error(`session ${sessionId} belongs to another owner — a replace rewrites only the importer's own session; nothing was written`));
+            }
+        }
+        settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: sessionId }));
         if (mode === "replace")
             await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
         for (let seq = 0; seq < validated.length; seq++) {
@@ -598,7 +482,7 @@ export class PgSessionStore {
         }
     }
     beginImportStaging(realSessionId, token) {
-        return new PgStagingHandle(this.pool, realSessionId, stagingIdFor(realSessionId, token));
+        return new PgStagingHandle(this.pool, this.hooks, realSessionId, stagingIdFor(realSessionId, token));
     }
     async readStagedEntries(stagingId) {
         const res = await this.pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [stagingId]);
@@ -620,11 +504,9 @@ export class PgSessionStore {
         const conn = await this.pool.connect();
         try {
             await conn.query("BEGIN");
-            const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", sessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.query("ROLLBACK");
-                throw new SessionActiveRunError(sessionId, claim.activeTaskId);
-            }
+            const locked = await conn.query("SELECT session_id FROM session_meta WHERE session_id = $1 FOR UPDATE", [sessionId]);
+            if (locked.rows.length > 0)
+                settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "delete", rootSessionId: sessionId }));
             const metaRes = await conn.query("DELETE FROM session_meta WHERE session_id = $1 AND owner IS NOT DISTINCT FROM $2", [sessionId, owner]);
             if ((metaRes.rowCount ?? 0) > 0)
                 await conn.query("DELETE FROM session_event WHERE session_id = $1", [sessionId]);
@@ -637,6 +519,8 @@ export class PgSessionStore {
             }
             catch {
             }
+            if (err instanceof HookRefusal)
+                throw err.refuse;
             throw err;
         }
         finally {
@@ -652,12 +536,14 @@ export class PgSessionStore {
 }
 class PgStagingHandle {
     pool;
+    hooks;
     realSessionId;
     stagingId;
     nextSeq = 0;
     seen = new Set();
-    constructor(pool, realSessionId, stagingId) {
+    constructor(pool, hooks, realSessionId, stagingId) {
         this.pool = pool;
+        this.hooks = hooks;
         this.realSessionId = realSessionId;
         this.stagingId = stagingId;
     }
@@ -704,11 +590,7 @@ class PgStagingHandle {
                     throw new StagedCommitOwnerChangedError(this.realSessionId);
                 }
             }
-            const claim = await lockRootAndReadClaim(rowsOnClient(conn), "pg", this.realSessionId);
-            if (claim.activeTaskId !== null) {
-                await conn.query("ROLLBACK");
-                throw new SessionActiveRunError(this.realSessionId, claim.activeTaskId);
-            }
+            settleHookVerdict(await this.hooks.beforeCommit(statementsOn(conn), { op: "import", rootSessionId: this.realSessionId }));
             const staged = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.stagingId]);
             const dst = await conn.query("SELECT entry_id FROM session_event WHERE session_id = $1 ORDER BY seq ASC FOR UPDATE", [this.realSessionId]);
             const dstMeta = await conn.query("SELECT placement_kind FROM session_meta WHERE session_id = $1", [this.realSessionId]);
@@ -741,16 +623,7 @@ class PgStagingHandle {
             let leafId = null;
             if (lastRes.rows[0])
                 leafId = leafIdAfterEntry(decodeSessionEventPayload(lastRes.rows[0].payload, this.realSessionId, "last staged row"));
-            const settle = await conn.query(`UPDATE session_meta SET owner = $1, updated_at = $2, leaf_id = $3, leaf_seq = $4, ${MIRROR_ON_COMMIT_SET} WHERE session_id = $5 AND ${MIRROR_ON_COMMIT_GUARD}`, [owner, now, leafId, srcIds.length, this.realSessionId]);
-            if ((settle.rowCount ?? 0) !== 1) {
-                const locked = readPlacementRowStatement("pg", this.realSessionId, { lock: true });
-                const lockedRow = (await conn.query(locked.text, [...locked.values])).rows[0];
-                const cell = lockedRow === undefined ? undefined : placementCellFromRow(this.realSessionId, lockedRow);
-                await conn.query("ROLLBACK");
-                if (cell?.role === "writer")
-                    throw new SessionWriterPresentError(this.realSessionId, cell.lane);
-                throw new SessionError("storage", `staged commit for ${this.realSessionId}: the commit point matched no row under a held row lock and the row is not a writer — refusing to guess`);
-            }
+            await conn.query("UPDATE session_meta SET owner = $1, updated_at = $2, leaf_id = $3, leaf_seq = $4 WHERE session_id = $5", [owner, now, leafId, srcIds.length, this.realSessionId]);
             const afterMeta = await conn.query("SELECT placement_kind, owner, incarnation FROM session_meta WHERE session_id = $1", [this.realSessionId]);
             if (afterMeta.rows[0]?.placement_kind != null) {
                 await conn.query("ROLLBACK");
@@ -765,7 +638,9 @@ class PgStagingHandle {
                 await conn.query("ROLLBACK");
             }
             catch { }
-            if (err instanceof SyncConflictError || err instanceof SessionError || err instanceof SessionWriterPresentError || err instanceof SessionActiveRunError)
+            if (err instanceof HookRefusal)
+                throw err.refuse;
+            if (err instanceof SyncConflictError || err instanceof SessionError)
                 throw err;
             throw new SessionError("storage", `staged commit for ${this.realSessionId} failed`, err instanceof Error ? err : undefined);
         }