@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,33 +1,39 @@
 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 { epochAnchorPageSql, epochFloorOf, scanEpochAnchor, sqlEpochAnchorRowOf } 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, 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 { 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 { 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 { 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";
+import { ensureIndexes } from "../plugins/ensure-index.js";
+import { withdrawSessionOn } from "./tidb-session-store.js";
+import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue, placedSessionOwnerOf } from "../plugins/session-ownership.js";
+import { forkRowCells, selectForkRows } from "@sema-agent/core";
+import { FORK_LOG_ROW_SHAPE, ForkTargetUnsettledError, classifyForkTarget, forkByFreshId, forkPointOf, sameSourceGeneration } 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 +42,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 +57,8 @@ 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")},
+     -- fork 谱系(TiDB 孪生同名同义;列定义唯一属主 = src/session-incarnation.ts 的 SESSION_META_LINEAGE_COLUMNS):NULL = 不是 fork 建的行 / 两列落地之前建的 fork(不回填)。
+     ${SESSION_META_LINEAGE_COLUMNS.pg},
      PRIMARY KEY (session_id)
    )`,
     `CREATE TABLE IF NOT EXISTS session_event (
@@ -85,24 +83,24 @@ 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;
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.floorSeq, async (beforeSeq) => {
-            const res = await this.pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq < $2 AND type IN ('prompt_epoch','compaction') ORDER BY seq DESC LIMIT 100`, [this.sessionId, beforeSeq]);
-            return res.rows;
+        return scanEpochAnchor(epochFloorOf(this.floorSeq, await this.windowFloorEntry()), async (beforeSeq) => {
+            const res = await this.pool.query(epochAnchorPageSql("pg"), [this.sessionId, beforeSeq]);
+            return res.rows.map(sqlEpochAnchorRowOf);
         }, (row) => decodeSessionEventPayload(row.payload, this.sessionId, row.seq));
     }
     static async wake(pool, sessionId) {
-        const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
+        const metaRes = await pool.query(`SELECT created_at, leaf_id, leaf_seq, incarnation, ${PLACEMENT_SELECT_COLUMNS}, forked_from, forked_from_incarnation FROM session_meta WHERE session_id = $1`, [sessionId]);
         const meta = metaRes.rows[0];
         if (!meta)
             return null;
@@ -110,7 +108,13 @@ export class PgSessionStorage extends BaseSessionStorage {
         const eventRes = await pool.query(`SELECT seq, ${jsonColumnText("pg", "payload")} FROM session_event WHERE session_id = $1 AND seq >= $2 ORDER BY seq ASC`, [sessionId, floorSeq]);
         const entries = eventRes.rows.map((r) => decodeSessionEventPayload(r.payload, sessionId, r.seq));
         const placement = placementFromRow(meta);
-        const metadata = { id: sessionId, createdAt: toIso(meta.created_at), incarnation: incarnationFromCell(sessionId, meta.incarnation), ...(placement !== undefined ? { placement } : {}) };
+        const metadata = {
+            id: sessionId,
+            createdAt: toIso(meta.created_at),
+            incarnation: incarnationFromCell(sessionId, meta.incarnation),
+            ...(placement !== undefined ? { placement } : {}),
+            ...forkLineageOfRow(sessionId, meta.forked_from, meta.forked_from_incarnation),
+        };
         return new PgSessionStorage(pool, sessionId, metadata, entries, meta.leaf_id ?? null, floorEntryId, floorSeq);
     }
     static async computeFloor(pool, sessionId) {
@@ -126,24 +130,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 +181,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) {
@@ -232,21 +222,42 @@ export class PgSessionStore {
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
+        await this.registerWithReceipt(sessionId, owner);
+    }
+    async registerWithReceipt(sessionId, owner) {
         if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
-                return;
+                return {};
             assertFirstOwnerWritable(sessionId, owner);
         }
-        await this.insertMeta(sessionId, owner, undefined);
+        const incarnation = mintSessionIncarnation();
+        await this.insertMeta(sessionId, owner, undefined, incarnation);
+        return { minted: { sessionId, owner, incarnation } };
+    }
+    async deleteSessionIf(sessionId, cond) {
+        const conn = await this.pool.connect();
+        try {
+            await conn.query("BEGIN");
+            const outcome = await withdrawSessionOn(statementsOn(conn), "pg", this.hooks, sessionId, cond);
+            await conn.query(outcome.withdrawn ? "COMMIT" : "ROLLBACK");
+            return outcome;
+        }
+        catch (err) {
+            await conn.query("ROLLBACK").catch(() => undefined);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
     }
     async createOnAcquire(sessionId, placement) {
         await this.insertMeta(sessionId, placement === undefined ? null : placedSessionOwnerOf(sessionId, placement), placement);
     }
-    async insertMeta(sessionId, owner, placement) {
+    async insertMeta(sessionId, owner, placement, incarnation = mintSessionIncarnation()) {
         const now = new Date();
-        await this.pool.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,NULL,0,$5,$6,$7,$8,$9,$10,$11) ON CONFLICT (session_id) DO NOTHING", [sessionId, owner, now, now, mintSessionIncarnation(), ...placementInsertValues(placement, now)]);
+        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}) ` +
+            "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) {
         const res = await this.pool.query(`SELECT ${PLACEMENT_SELECT_COLUMNS} FROM session_meta WHERE session_id = $1`, [sessionId]);
@@ -319,109 +330,6 @@ 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) {
-        return (await this.listSessionRows(opts)).map((a) => a.row);
-    }
-    async listSessionRows(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 this.selectListRows({ where, params, limit: opts.limit });
-    }
-    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, opts) {
         return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner, opts);
     }
@@ -434,7 +342,8 @@ export class PgSessionStore {
         throw new ForkTargetUnsettledError(target.id);
     }
     async forkToOnce(sourceId, owner, target) {
-        const metaRes = await this.pool.query("SELECT leaf_id, owner FROM session_meta WHERE session_id = $1", [sourceId]);
+        const sourceRow = "SELECT leaf_id, owner, incarnation FROM session_meta WHERE session_id = $1";
+        const metaRes = await this.pool.query(sourceRow, [sourceId]);
         if (!metaRes.rows[0])
             return null;
         const leafId = metaRes.rows[0].leaf_id ?? null;
@@ -443,16 +352,20 @@ export class PgSessionStore {
         if (storage === null)
             return null;
         const point = await forkPointOf(storage);
+        const cells = forkRowCells(await storage.getMetadata());
         const eventRes = await this.pool.query(`SELECT entry_id, parent_id, type, ${jsonColumnText("pg", "payload")}, ts FROM session_event WHERE session_id = $1 ORDER BY seq ASC`, [sourceId]);
+        const afterRes = await this.pool.query(sourceRow, [sourceId]);
+        if (!sameSourceGeneration(cells.forkedFromIncarnation, metaRes.rows[0].incarnation, afterRes.rows[0]?.incarnation))
+            return null;
         const { rows, leafId: forkLeafId } = selectForkRows(eventRes.rows, leafId, point, FORK_LOG_ROW_SHAPE);
         const now = new Date();
         const conn = await this.pool.connect();
         let collided = false;
         try {
             await conn.query("BEGIN");
+            const placed = placementInsertCells(target.placement, now);
             try {
-                await conn.query("INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, fork_key, " +
-                    "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,$14)", [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), target.key ?? null, ...placementInsertValues(target.placement, now)]);
+                await conn.query(`INSERT INTO session_meta (session_id, owner, created_at, updated_at, leaf_id, leaf_seq, incarnation, ${placed.columns}, forked_from, forked_from_incarnation) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)`, [target.id, forkOwner, now, now, forkLeafId, rows.length, mintSessionIncarnation(), ...placed.values, cells.forkedFrom, cells.forkedFromIncarnation ?? null]);
             }
             catch (err) {
                 if (!isDupKey(err))
@@ -460,6 +373,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);
@@ -476,14 +391,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]);
@@ -523,7 +439,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) {
@@ -532,7 +448,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);
         }
@@ -546,21 +464,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) {
@@ -569,7 +479,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);
         }
@@ -577,23 +489,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++) {
@@ -602,7 +517,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,33 +535,6 @@ export class PgSessionStore {
         }
         return removed;
     }
-    async deleteSession(sessionId, owner) {
-        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 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]);
-            await conn.query("COMMIT");
-            return (metaRes.rowCount ?? 0) > 0;
-        }
-        catch (err) {
-            try {
-                await conn.query("ROLLBACK");
-            }
-            catch {
-            }
-            throw err;
-        }
-        finally {
-            conn.release();
-        }
-    }
     get size() {
         return this.pending.size;
     }
@@ -656,12 +544,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;
     }
@@ -708,11 +598,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]);
@@ -745,16 +631,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");
@@ -769,7 +646,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);
         }