@humwick/server 0.0.0-stage → 0.130.0

package/src/db/context-reset-carry.ts

@@ -0,0 +1,144 @@
+import { isRecord } from "@humwick/sdk";
+import { getDb } from "./connection.ts";
+
+// #3398 (docs/design/self-resume-carry.md) — `context_resets` is the durable record of every observed
+// provider context reset; `context_recovery_obligations` is one row per accepted self-resume boundary.
+export const CONTEXT_RESET_SCHEMA = `CREATE TABLE IF NOT EXISTS context_resets (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  agent_id TEXT NOT NULL,
+  reset_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  command_id TEXT,
+  evidence TEXT NOT NULL DEFAULT '{}',
+  observed_at INTEGER NOT NULL,
+  recorded_at INTEGER NOT NULL,
+  UNIQUE(agent_id, reset_id)
+);
+CREATE TABLE IF NOT EXISTS context_recovery_obligations (
+  agent_id TEXT NOT NULL,
+  generation INTEGER NOT NULL,
+  command_id TEXT,
+  floor_at INTEGER NOT NULL,
+  opened_at INTEGER NOT NULL,
+  closed_at INTEGER,
+  closed_by TEXT,
+  PRIMARY KEY (agent_id, generation)
+);
+CREATE INDEX IF NOT EXISTS idx_context_recovery_open ON context_recovery_obligations(agent_id) WHERE closed_at IS NULL;
+CREATE INDEX IF NOT EXISTS idx_context_resets_uncommanded ON context_resets(observed_at) WHERE command_id IS NULL`;
+
+export type ContextResetKind = "compact" | "clear" | "restart";
+
+export interface ContextResetFact {
+  agentId: string;
+  resetId: string;
+  kind: ContextResetKind;
+  /** The boundary command whose destructive input this reset settled, when the runner could attribute it. */
+  commandId?: string;
+  evidence?: Record<string, unknown>;
+  observedAt: number;
+}
+
+/** A clear/compact reset Relay did not command (operator `/clear`, provider auto-compaction). */
+export type ObservedContextReset = Required<Pick<ContextResetFact, "agentId" | "resetId" | "observedAt">> & { kind: "clear" | "compact" };
+
+/** #3698 — uncommanded clear/compact resets observed since `since`, newest first. */
+export function listUncommandedContextResets(since: number, limit: number, agentId?: string): ObservedContextReset[] {
+  const rows = getDb().query(`
+    SELECT agent_id, reset_id, kind, observed_at FROM context_resets INDEXED BY idx_context_resets_uncommanded
+    WHERE command_id IS NULL AND observed_at >= ?1 AND kind IN ('clear', 'compact') AND (?2 IS NULL OR agent_id = ?2)
+    ORDER BY observed_at DESC LIMIT ?3
+  `).all(since, agentId ?? null, limit) as Array<{ agent_id: string; reset_id: string; kind: "clear" | "compact"; observed_at: number }>;
+  return rows.map((row) => ({ agentId: row.agent_id, resetId: row.reset_id, kind: row.kind, observedAt: row.observed_at }));
+}
+
+export interface RecoveryObligation {
+  agentId: string;
+  generation: number;
+  commandId: string | null;
+  openedAt: number;
+  open: boolean;
+}
+
+/** Appends a reset fact; false when this reset id was already recorded. */
+export function insertContextReset(fact: ContextResetFact, now: number): boolean {
+  const inserted = getDb().query(`
+    INSERT INTO context_resets (agent_id, reset_id, kind, command_id, evidence, observed_at, recorded_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(agent_id, reset_id) DO NOTHING
+  `).run(fact.agentId, fact.resetId, fact.kind, fact.commandId ?? null, JSON.stringify(fact.evidence ?? {}), fact.observedAt, now);
+  return inserted.changes > 0;
+}
+
+/**
+ * Opens the obligation for boundary `generation` at `now`, the capture start. The carry window is derived from
+ * `opened_at` at read time (#3523); `floor_at` is no longer read and only stays because existing databases
+ * declare it NOT NULL.
+ */
+export function openRecoveryObligation(agentId: string, generation: number, now: number): void {
+  getDb().query(`
+    INSERT INTO context_recovery_obligations (agent_id, generation, floor_at, opened_at) VALUES (?1, ?2, ?3, ?3)
+    ON CONFLICT(agent_id, generation) DO NOTHING
+  `).run(agentId, generation, now);
+}
+
+export function attachRecoveryCommand(agentId: string, generation: number, commandId: string): void {
+  getDb().query("UPDATE context_recovery_obligations SET command_id = ? WHERE agent_id = ? AND generation = ?").run(commandId, agentId, generation);
+}
+
+/** The open obligations plus the latest one, closed or not: it keeps re-listing until the next capture. */
+export function carryingRecoveryObligations(agentId: string): RecoveryObligation[] {
+  const rows = getDb().query(`
+    SELECT generation, command_id, opened_at, closed_at FROM context_recovery_obligations
+    WHERE agent_id = ?1 AND (closed_at IS NULL OR generation = (SELECT MAX(generation) FROM context_recovery_obligations WHERE agent_id = ?1))
+    ORDER BY generation
+  `).all(agentId) as Array<{ generation: number; command_id: string | null; opened_at: number; closed_at: number | null }>;
+  return rows.map((row) => ({ agentId, generation: row.generation, commandId: row.command_id, openedAt: row.opened_at, open: row.closed_at === null }));
+}
+
+export function closeRecoveryObligations(agentId: string, generations: number[], closedBy: string, now: number): void {
+  if (!generations.length) return;
+  getDb().query(`
+    UPDATE context_recovery_obligations SET closed_at = ?, closed_by = ?
+    WHERE agent_id = ? AND closed_at IS NULL AND generation IN (${generations.map(() => "?").join(",")})
+  `).run(now, closedBy, agentId, ...generations);
+}
+
+/**
+ * Messages the agent read since `floorAt` and has not visibly handled: never its own, a continuation, a
+ * carry notice, or anything it replied or reacted to (a turn's own output linked to a message is no reply). Ids an
+ * unread recovery list already names are left out, so a second report of one reset adds nothing.
+ */
+export function readsToCarry(agentId: string, floorAt: number): number[] {
+  const rows = getDb().query(`
+    SELECT r.message_id AS id FROM message_reads r
+    JOIN messages m ON m.id = r.message_id
+    WHERE r.agent_id = ?1 AND r.read_at >= ?2
+      AND m.from_agent != ?1
+      AND (m.idempotency_key IS NULL OR (m.idempotency_key NOT LIKE 'self-resume-continuation:%' AND m.idempotency_key NOT LIKE 'self-resume-carry:%'))
+      AND NOT EXISTS (SELECT 1 FROM messages reply WHERE reply.reply_to = m.id AND reply.from_agent = ?1 AND reply.kind != 'session')
+      AND NOT EXISTS (SELECT 1 FROM message_reactions x WHERE x.message_id = m.id AND x.actor_id = ?1)
+      AND NOT EXISTS (
+        SELECT 1 FROM message_reads r2 JOIN messages n ON n.id = r2.message_id
+        WHERE m.from_agent = 'system' AND json_extract(m.payload, '$.kind') LIKE 'workflow.%' AND json_extract(m.payload, '$.runId') IS NOT NULL
+          AND r2.agent_id = ?1 AND r2.read_at >= ?2 AND n.id > m.id AND n.from_agent = 'system'
+          AND json_extract(n.payload, '$.kind') LIKE 'workflow.%' AND json_extract(n.payload, '$.runId') = json_extract(m.payload, '$.runId'))
+    ORDER BY r.message_id
+  `).all(agentId, floorAt) as Array<{ id: number }>;
+  const listed = idsInUnreadCarries(agentId);
+  return rows.map((row) => row.id).filter((id) => !listed.has(id));
+}
+
+function idsInUnreadCarries(agentId: string): Set<number> {
+  const rows = getDb().query(`
+    SELECT m.payload FROM messages m INDEXED BY idx_msg_to_id
+    WHERE m.to_target = ?1 AND m.from_agent = 'system' AND m.idempotency_key LIKE 'self-resume-carry:' || ?1 || ':%'
+      AND NOT EXISTS (SELECT 1 FROM message_reads r WHERE r.message_id = m.id AND r.agent_id = ?1)
+  `).all(agentId) as Array<{ payload: string | null }>;
+  const ids = new Set<number>();
+  for (const row of rows) {
+    const payload: unknown = row.payload ? JSON.parse(row.payload) : undefined;
+    const carry = isRecord(payload) && isRecord(payload.selfResumeCarry) ? payload.selfResumeCarry : undefined;
+    if (Array.isArray(carry?.messageIds)) for (const id of carry.messageIds) if (typeof id === "number") ids.add(id);
+  }
+  return ids;
+}

package/src/db/continuation-archive-purge.ts

@@ -0,0 +1,48 @@
+import { humanAgentIdSql } from "./human-address";
+// #3012 — an agent delete cascades through the FK into its continuation archives (≈45 KB each),
+// and freeing their overflow pages in one statement blocked the hub for 8–60 ms per few hundred rows.
+// This removes them first in short writer transactions, in the maintenance subprocess, so the
+// main-thread agent delete has nothing left to cascade.
+import { getDb, writeTransaction } from "./connection.ts";
+
+export interface ContinuationArchivePurgeInput {
+  agentIds: string[];
+  /** Offline-prune predicate, re-checked in every chunk: an agent seen again keeps its remaining archives. */
+  offlineBefore?: number;
+  timeBudgetMs: number;
+}
+
+export interface ContinuationArchivePurgeResult {
+  purged: number;
+  moreWork: boolean;
+}
+
+const CHUNK_ROWS = 16;
+const YIELD_MS = 2;
+
+/** The ids among `agentIds` that own at least one archive. */
+export function continuationArchiveOwnersAmong(agentIds: string[]): string[] {
+  if (agentIds.length === 0) return [];
+  return (getDb().query(`SELECT DISTINCT agent_id FROM continuation_archives WHERE agent_id IN (${agentIds.map(() => "?").join(",")})`)
+    .all(...agentIds) as Array<{ agent_id: string }>).map((row) => row.agent_id);
+}
+
+export async function purgeContinuationArchives(input: ContinuationArchivePurgeInput): Promise<ContinuationArchivePurgeResult> {
+  if (input.agentIds.length === 0) return { purged: 0, moreWork: false };
+  const owners = input.agentIds.map(() => "?").join(",");
+  const prunable = input.offlineBefore === undefined ? "" : " AND status = 'offline' AND last_seen < ?";
+  const chunk = getDb().query(`DELETE FROM continuation_archives WHERE id IN (
+    SELECT a.id FROM continuation_archives a
+    WHERE a.agent_id IN (SELECT id FROM agents WHERE id IN (${owners}) AND ${humanAgentIdSql("id")} = 0 AND id <> 'system'${prunable})
+    LIMIT ${CHUNK_ROWS})`);
+  const bindings = input.offlineBefore === undefined ? input.agentIds : [...input.agentIds, input.offlineBefore];
+  const deadline = performance.now() + input.timeBudgetMs;
+  let purged = 0;
+  for (;;) {
+    const changes = writeTransaction(() => chunk.run(...bindings).changes);
+    purged += changes;
+    if (changes < CHUNK_ROWS) return { purged, moreWork: false };
+    if (performance.now() >= deadline) return { purged, moreWork: true };
+    await Bun.sleep(YIELD_MS);
+  }
+}

package/src/db/continuation-archive-search.ts

@@ -0,0 +1,249 @@
+// #3012 — the continuation-archive FTS5 index lives in a side SQLite file with its own write lock.
+// Archive writes and the agent-prune cascade on the main DB never touch FTS; the maintenance
+// subprocess catches the side index up (inserts by rowid watermark, deletes by anti-join), and
+// recall reads it through a read-only connection with the side file attached.
+import { statSync } from "node:fs";
+import { continuationArchiveFtsEnabled } from "../config";
+import { getDb, getDbGeneration, getDbPath, openReadOnlyDb } from "./connection.ts";
+
+type Database = ReturnType<typeof getDb>;
+
+export const ARCHIVE_SEARCH_SCHEMA = "archive_fts";
+const SEARCH_INDEX_VERSION = 1;
+const INSERT_CHUNK_ROWS = 16;
+const DELETE_CHUNK_ROWS = 256;
+
+export interface ContinuationArchiveSearchSyncInput {
+  /** Wall-time after which the run stops starting chunks and reports `moreWork`. */
+  timeBudgetMs: number;
+}
+
+export interface ContinuationArchiveSearchSyncResult {
+  indexed: number;
+  removed: number;
+  moreWork: boolean;
+}
+
+export function continuationArchiveSearchPath(dbPath: string): string {
+  return dbPath === ":memory:" ? ":memory:" : `${dbPath}-archive-fts.db`;
+}
+
+function isAttached(db: Database): boolean {
+  return (db.query("PRAGMA database_list").all() as Array<{ name: string }>).some((row) => row.name === ARCHIVE_SEARCH_SCHEMA);
+}
+
+/** Writer side: attach (creating) the side file on `db` and bring its schema to the current version. */
+export function attachContinuationArchiveSearchIndex(db: Database, dbPath: string): void {
+  if (!isAttached(db)) {
+    db.query(`ATTACH DATABASE ? AS ${ARCHIVE_SEARCH_SCHEMA}`).run(continuationArchiveSearchPath(dbPath));
+    if (dbPath !== ":memory:") {
+      db.run(`PRAGMA ${ARCHIVE_SEARCH_SCHEMA}.journal_mode = WAL`);
+      db.run(`PRAGMA ${ARCHIVE_SEARCH_SCHEMA}.synchronous = NORMAL`);
+    }
+  }
+  const { user_version: version } = db.query(`PRAGMA ${ARCHIVE_SEARCH_SCHEMA}.user_version`).get() as { user_version: number };
+  if (version === SEARCH_INDEX_VERSION) return;
+  db.transaction(() => {
+    db.run(`DROP TABLE IF EXISTS ${ARCHIVE_SEARCH_SCHEMA}.segments`);
+    db.run(`DROP TABLE IF EXISTS ${ARCHIVE_SEARCH_SCHEMA}.indexed`);
+    // Contentless: recall joins back to continuation_archives for the text, and deletes skip re-tokenizing.
+    db.run(`CREATE VIRTUAL TABLE ${ARCHIVE_SEARCH_SCHEMA}.segments USING fts5(segment, content='', contentless_delete=1)`);
+    db.run(`CREATE TABLE ${ARCHIVE_SEARCH_SCHEMA}.indexed (id INTEGER PRIMARY KEY)`);
+    db.run(`PRAGMA ${ARCHIVE_SEARCH_SCHEMA}.user_version = ${SEARCH_INDEX_VERSION}`);
+  })();
+}
+
+/**
+ * Catch the side index up with continuation_archives in bounded side-file transactions. The main DB
+ * is only read (deferred transactions take no main write lock). Archive ids are AUTOINCREMENT and
+ * commit in id order, so every id at or below max(indexed.id) is indexed.
+ */
+export async function syncContinuationArchiveSearchIndexOn(
+  db: Database,
+  dbPath: string,
+  input: ContinuationArchiveSearchSyncInput,
+): Promise<ContinuationArchiveSearchSyncResult> {
+  attachContinuationArchiveSearchIndex(db, dbPath);
+  const deadline = performance.now() + input.timeBudgetMs;
+  const result: ContinuationArchiveSearchSyncResult = { indexed: 0, removed: 0, moreWork: false };
+  const gone = (db.query(`SELECT id FROM ${ARCHIVE_SEARCH_SCHEMA}.indexed i
+    WHERE NOT EXISTS (SELECT 1 FROM main.continuation_archives a WHERE a.id = i.id)`).all() as Array<{ id: number }>).map((row) => row.id);
+  const deleteSegment = db.query(`DELETE FROM ${ARCHIVE_SEARCH_SCHEMA}.segments WHERE rowid = ?`);
+  const deleteIndexed = db.query(`DELETE FROM ${ARCHIVE_SEARCH_SCHEMA}.indexed WHERE id = ?`);
+  for (let at = 0; at < gone.length; at += DELETE_CHUNK_ROWS) {
+    if (performance.now() >= deadline) return { ...result, moreWork: true };
+    db.transaction(() => {
+      for (const id of gone.slice(at, at + DELETE_CHUNK_ROWS)) { deleteSegment.run(id); deleteIndexed.run(id); }
+    })();
+    result.removed += Math.min(DELETE_CHUNK_ROWS, gone.length - at);
+    await Bun.sleep(0);
+  }
+  const pending = db.query(`SELECT id, segment FROM main.continuation_archives
+    WHERE id > (SELECT coalesce(max(id), 0) FROM ${ARCHIVE_SEARCH_SCHEMA}.indexed) ORDER BY id LIMIT ${INSERT_CHUNK_ROWS}`);
+  const insertSegment = db.query(`INSERT INTO ${ARCHIVE_SEARCH_SCHEMA}.segments (rowid, segment) VALUES (?, ?)`);
+  const insertIndexed = db.query(`INSERT INTO ${ARCHIVE_SEARCH_SCHEMA}.indexed (id) VALUES (?)`);
+  for (;;) {
+    if (performance.now() >= deadline) return { ...result, moreWork: true };
+    const indexed = db.transaction(() => {
+      const rows = pending.all() as Array<{ id: number; segment: string }>;
+      for (const row of rows) { insertSegment.run(row.id, row.segment); insertIndexed.run(row.id); }
+      return rows.length;
+    })();
+    result.indexed += indexed;
+    if (indexed < INSERT_CHUNK_ROWS) return result;
+    await Bun.sleep(0);
+  }
+}
+
+/** `:memory:` has no second connection: the side index is attached to the one shared handle. */
+export function syncInMemoryContinuationArchiveSearchIndex(input: ContinuationArchiveSearchSyncInput): Promise<ContinuationArchiveSearchSyncResult> {
+  return syncContinuationArchiveSearchIndexOn(getDb(), ":memory:", input);
+}
+
+// Reader side: a dedicated read-only connection with the side file attached. Never the main RW
+// connection: an attached file joins the writer's BEGIN IMMEDIATE, so main writes would wait on the
+// indexer's side lock. `:memory:` (tests) has no second connection, so it attaches in place.
+let searchConn: Database | undefined;
+let searchConnGeneration = -1;
+/** dev:ino of the attached side file: a removed or replaced file is re-attached, never read stale. */
+let attachedSide: string | undefined;
+
+function closeSearchConnection(): void {
+  if (searchConn && searchConn !== getDb()) {
+    try { searchConn.close(); } catch { /* a half-open handle must not wedge the reopen */ }
+  }
+  searchConn = undefined;
+  attachedSide = undefined;
+}
+
+function fileIdentity(path: string): string | undefined {
+  try {
+    const stat = statSync(path);
+    return `${stat.dev}:${stat.ino}`;
+  } catch {
+    return undefined;
+  }
+}
+
+function searchConnection(): { conn: Database; attached: boolean } {
+  if (searchConnGeneration !== getDbGeneration()) {
+    closeSearchConnection();
+    searchConnGeneration = getDbGeneration();
+  }
+  const dbPath = getDbPath();
+  if (!dbPath || dbPath === ":memory:") {
+    attachContinuationArchiveSearchIndex(getDb(), ":memory:");
+    return { conn: (searchConn = getDb()), attached: true };
+  }
+  if (!searchConn) {
+    searchConn = openReadOnlyDb(dbPath);
+    searchConn.run("PRAGMA busy_timeout = 1000");
+    searchConn.run("PRAGMA temp_store = MEMORY");
+  }
+  const sidePath = continuationArchiveSearchPath(dbPath);
+  const side = fileIdentity(sidePath);
+  if (side !== attachedSide) {
+    if (attachedSide) searchConn.run(`DETACH DATABASE ${ARCHIVE_SEARCH_SCHEMA}`);
+    attachedSide = undefined;
+    if (side) {
+      try {
+        searchConn.query(`ATTACH DATABASE ? AS ${ARCHIVE_SEARCH_SCHEMA}`).run(sidePath);
+        attachedSide = side;
+      } catch {
+        // Removed between the stat and the attach: the next call retries.
+      }
+    }
+  }
+  return { conn: searchConn, attached: attachedSide !== undefined };
+}
+
+/** max(indexed.id): every archive id at or below it is indexed. Undefined when the side schema is unusable. */
+function indexWatermark(conn: Database): number | undefined {
+  try {
+    const { user_version: version } = conn.query(`PRAGMA ${ARCHIVE_SEARCH_SCHEMA}.user_version`).get() as { user_version: number };
+    if (version !== SEARCH_INDEX_VERSION) return undefined;
+    return (conn.query(`SELECT coalesce(max(id), 0) AS id FROM ${ARCHIVE_SEARCH_SCHEMA}.indexed`).get() as { id: number }).id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Lock-free probe: the side index is missing, stale or out of date relative to continuation_archives. */
+export function continuationArchiveSearchIndexHasWork(): boolean {
+  if (!continuationArchiveFtsEnabled()) return false;
+  const { conn, attached } = searchConnection();
+  const watermark = attached ? indexWatermark(conn) : undefined;
+  if (watermark === undefined) return Boolean(conn.query("SELECT 1 FROM main.continuation_archives LIMIT 1").get());
+  const row = conn.query(`SELECT
+      (SELECT count(*) FROM main.continuation_archives) AS archives,
+      (SELECT coalesce(max(id), 0) FROM main.continuation_archives) AS maxArchive,
+      (SELECT count(*) FROM ${ARCHIVE_SEARCH_SCHEMA}.indexed) AS indexed`).get() as { archives: number; maxArchive: number; indexed: number };
+  return row.maxArchive > watermark || row.archives !== row.indexed;
+}
+
+export interface ArchiveSearchHit {
+  id: number;
+  agent_id: string;
+  generation: number;
+  segment: string;
+  created_at: number;
+  score: number;
+}
+
+/**
+ * FTS5 recall over two disjoint corpora split at ONE captured watermark W: id <= W from the side index,
+ * id > W through a temp FTS5 table with the same tokenizer. Those newest hits lead, so the sync lag never pushes them out.
+ * Undefined on bad MATCH syntax; the caller then uses LIKE. Rows deleted since the last sync drop out through the join.
+ */
+export function searchContinuationArchivesFts(agentId: string, match: string, limit: number): ArchiveSearchHit[] | undefined {
+  const { conn, attached } = searchConnection();
+  try {
+    const watermark = (attached ? indexWatermark(conn) : undefined) ?? 0;
+    const tail = conn.query("SELECT * FROM main.continuation_archives WHERE agent_id = ? AND id > ? ORDER BY id")
+      .all(agentId, watermark) as Array<Omit<ArchiveSearchHit, "score">>;
+    const tailHits = tail.length > 0 ? matchTail(conn, tail, match, limit) : [];
+    const indexedHits = watermark > 0 ? conn.query(`
+      SELECT a.*, bm25(segments) AS score
+      FROM ${ARCHIVE_SEARCH_SCHEMA}.segments
+      JOIN main.continuation_archives a ON a.id = segments.rowid
+      WHERE segments MATCH ? AND a.agent_id = ? AND a.id <= ?
+      ORDER BY score ASC, a.created_at DESC, a.id DESC
+      LIMIT ?
+    `).all(match, agentId, watermark, limit) as ArchiveSearchHit[] : [];
+    return [...tailHits, ...indexedHits].slice(0, limit);
+  } catch {
+    return undefined;
+  }
+}
+
+function matchTail(conn: Database, rows: Array<Omit<ArchiveSearchHit, "score">>, match: string, limit: number): ArchiveSearchHit[] {
+  conn.run("CREATE VIRTUAL TABLE IF NOT EXISTS temp.archive_tail USING fts5(segment)");
+  try {
+    const insert = conn.query("INSERT INTO temp.archive_tail (rowid, segment) VALUES (?, ?)");
+    for (const row of rows) insert.run(row.id, row.segment);
+    const byId = new Map(rows.map((row) => [row.id, row]));
+    return (conn.query(`SELECT rowid AS id, bm25(archive_tail) AS score FROM temp.archive_tail
+      WHERE archive_tail MATCH ? ORDER BY score ASC, rowid DESC LIMIT ?`).all(match, limit) as Array<{ id: number; score: number }>)
+      .map(({ id, score }) => ({ ...byId.get(id)!, score }));
+  } finally {
+    conn.run("DELETE FROM temp.archive_tail");
+  }
+}
+
+/**
+ * Startup: retire the pre-#3012 in-DB index. Its triggers ran FTS5 inside every main-thread archive
+ * write and prune cascade; the drop runs once, before the server listens.
+ */
+export function dropLegacyContinuationArchiveIndex(): void {
+  const db = getDb();
+  const legacy = db.query(`SELECT count(*) AS n FROM sqlite_master WHERE name IN (
+    'continuation_archive_segments', 'continuation_archives_ai', 'continuation_archives_ad', 'continuation_archives_au'
+  )`).get() as { n: number };
+  if (legacy.n === 0) return;
+  db.transaction(() => {
+    db.run("DROP TRIGGER IF EXISTS continuation_archives_ai");
+    db.run("DROP TRIGGER IF EXISTS continuation_archives_ad");
+    db.run("DROP TRIGGER IF EXISTS continuation_archives_au");
+    db.run("DROP TABLE IF EXISTS continuation_archive_segments");
+  }).immediate();
+}

package/src/db/continuation-archives-async.ts

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { getDbPath, runDbMaintenanceWorker } from "./connection.ts";
+import { purgeContinuationArchives, type ContinuationArchivePurgeInput, type ContinuationArchivePurgeResult } from "./continuation-archive-purge.ts";
+import { syncInMemoryContinuationArchiveSearchIndex, type ContinuationArchiveSearchSyncInput, type ContinuationArchiveSearchSyncResult } from "./continuation-archive-search.ts";
+import { getGateway } from "./gateway.ts";
+import type { archiveAndAdvanceContinuation, archiveContinuationSegment, getContinuationArchiveByRef, searchContinuationArchives } from "./continuation-archives.ts";
+
+// Anything left after the budget is still removed, by the agent delete's cascade.
+const PURGE_TIME_BUDGET_MS = 10_000;
+
+export function getContinuationArchiveByRefAsync(input: Parameters<typeof getContinuationArchiveByRef>[0]): Promise<ReturnType<typeof getContinuationArchiveByRef>> {
+  return getGateway().read("continuationArchives.getByRef", input) as unknown as Promise<ReturnType<typeof getContinuationArchiveByRef>>;
+}
+
+export function searchContinuationArchivesAsync(input: Parameters<typeof searchContinuationArchives>[0]): Promise<ReturnType<typeof searchContinuationArchives>> {
+  return getGateway().read("continuationArchives.search", input) as unknown as Promise<ReturnType<typeof searchContinuationArchives>>;
+}
+
+export function archiveContinuationSegmentAsync(input: Parameters<typeof archiveContinuationSegment>[0]): Promise<ReturnType<typeof archiveContinuationSegment>> {
+  return getGateway().write("continuationArchives.archive", { input }, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof archiveContinuationSegment>>;
+}
+
+export function archiveAndAdvanceContinuationAsync(input: Parameters<typeof archiveAndAdvanceContinuation>[0], requestId = randomUUID()): Promise<ReturnType<typeof archiveAndAdvanceContinuation>> {
+  return getGateway().write("continuationArchives.compact", { input }, { idempotencyKey: requestId }) as unknown as Promise<ReturnType<typeof archiveAndAdvanceContinuation>>;
+}
+
+/**
+ * #3012 — catch the side FTS index up. A lock-free reader probe gates the run; the work runs in the
+ * maintenance subprocess against the side file's own write lock, never on the hub's loop. An
+ * in-memory DB (tests) has no second connection, so it runs inline.
+ */
+export async function syncContinuationArchiveSearchIndexAsync(
+  input: ContinuationArchiveSearchSyncInput,
+  options: { signal?: AbortSignal; markOffThread?: () => void } = {},
+): Promise<ContinuationArchiveSearchSyncResult & { offThread: boolean }> {
+  if (!await getGateway().read("continuationArchives.searchIndexHasWork", undefined)) return { indexed: 0, removed: 0, moreWork: false, offThread: false };
+  const dbPath = getDbPath();
+  if (!dbPath || dbPath === ":memory:") return { ...await syncInMemoryContinuationArchiveSearchIndex(input), offThread: false };
+  options.markOffThread?.();
+  const result = await runDbMaintenanceWorker<ContinuationArchiveSearchSyncResult>("continuation-archive-search-sync", [JSON.stringify(input)], options.signal);
+  return { ...result, offThread: true };
+}
+
+/**
+ * #3012 — remove these agents' archives before their main-thread delete, so its FK cascade frees no
+ * archive pages on the hub's loop. Runs in the maintenance subprocess in short writer transactions.
+ */
+export async function purgeContinuationArchivesAsync(
+  input: Omit<ContinuationArchivePurgeInput, "timeBudgetMs">,
+  options: { signal?: AbortSignal } = {},
+): Promise<ContinuationArchivePurgeResult & { offThread: boolean }> {
+  const agentIds = await getGateway().read("continuationArchives.ownersAmong", { agentIds: input.agentIds }) as unknown as string[];
+  if (agentIds.length === 0) return { purged: 0, moreWork: false, offThread: false };
+  const args: ContinuationArchivePurgeInput = { ...input, agentIds, timeBudgetMs: PURGE_TIME_BUDGET_MS };
+  const dbPath = getDbPath();
+  if (!dbPath || dbPath === ":memory:") return { ...await purgeContinuationArchives(args), offThread: false };
+  const result = await runDbMaintenanceWorker<ContinuationArchivePurgeResult>("continuation-archive-purge", [JSON.stringify(args)], options.signal);
+  return { ...result, offThread: true };
+}

package/src/db/continuation-archives-read-ops.ts

@@ -0,0 +1,10 @@
+import { continuationArchiveOwnersAmong } from "./continuation-archive-purge.ts";
+import { continuationArchiveSearchIndexHasWork } from "./continuation-archive-search.ts";
+import { getContinuationArchiveByRef, searchContinuationArchives } from "./continuation-archives.ts";
+
+export const CONTINUATION_ARCHIVES_READ_OPS = {
+  "continuationArchives.getByRef": (args: Parameters<typeof getContinuationArchiveByRef>[0]) => getContinuationArchiveByRef(args),
+  "continuationArchives.search": (args: Parameters<typeof searchContinuationArchives>[0]) => searchContinuationArchives(args),
+  "continuationArchives.searchIndexHasWork": () => continuationArchiveSearchIndexHasWork(),
+  "continuationArchives.ownersAmong": (args: { agentIds: string[] }) => continuationArchiveOwnersAmong(args.agentIds),
+};

package/src/db/continuation-archives-write-ops.ts

@@ -0,0 +1,15 @@
+import { archiveAndAdvanceContinuation, archiveContinuationSegment } from "./continuation-archives.ts";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
+
+export const CONTINUATION_ARCHIVES_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "continuationArchives.archive": {
+    idempotent: false,
+    fn: (args: { input: Parameters<typeof archiveContinuationSegment>[0] }, ctx: WriterOpContext) =>
+      archiveContinuationSegment({ ...args.input, now: args.input.now ?? ctx.now }),
+  },
+  "continuationArchives.compact": {
+    idempotent: false,
+    fn: (args: { input: Parameters<typeof archiveAndAdvanceContinuation>[0] }, ctx: WriterOpContext) =>
+      archiveAndAdvanceContinuation({ ...args.input, now: args.input.now ?? ctx.now }),
+  },
+});