@zq-silk/yui 0.5.2 → 0.6.0

package/dist/storage/sqliteStore.js

@@ -0,0 +1,1222 @@
+/**
+ * SQLite WAL Store (task-21, work-item-3).
+ *
+ * A `TaskStore` implementation backed by a single SQLite WAL database
+ * (`yui.db`), replacing the aggregate `state.json` read/parse/validate/write
+ * cycle. It implements the replaceable-Store seam from the design (§6) and the
+ * semantic-preservation checklist (§9):
+ *
+ *   - Process write lock .......... single writer connection + BEGIN IMMEDIATE;
+ *                                    busy_timeout absorbs CLI contention.
+ *   - Revision CAS ................ home_meta.revision checked/incremented in
+ *                                    the write transaction; conflict ->
+ *                                    StorageConflictError (transactionWithRevisionCas).
+ *   - Atomic durable write ........ WAL + synchronous=FULL; COMMIT == fsync.
+ *   - Mailbox per-target ordering . mailboxes.next_sequence + mailbox_signals
+ *                                    (mailbox_id, sequence) primary key.
+ *   - Exactly-once terminal state . conditional updates + UNIQUE(request_id)
+ *                                    on outbox / mailbox_signals.
+ *   - Crash recovery .............. WAL rollback of uncommitted transactions;
+ *                                    outbox replay of committed-but-unacked effects.
+ *   - Record family versioning .... full record (incl. schemaVersion) in payload.
+ *   - Upgrade fence ............... assertHomeWritable at the write boundary.
+ *   - Evidence retention .......... events/review_rounds/change_sets/
+ *                                    integration_attempts are never pruned.
+ *
+ * Records are stored as full versioned JSON in `payload` columns, with typed
+ * columns for the fields that are queried/filtered/used-for-CAS (§4). A
+ * high-frequency `runtime.provider-turn-progress` event is a single-row
+ * upsert into `telemetry` scoped by its primary key — it never rewrites global
+ * state and never touches another Task's rows (§4.4).
+ *
+ * The in-process store is phase 1 of §6. It does not re-run the heavy record
+ * validators on write (the domain layer that constructs records already does,
+ * and the design places record validation in the persistence worker, phase 2);
+ * it performs the same cheap structural checks the file store relies on
+ * (identity presence, taskId matching, referential lookups).
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import Database from "better-sqlite3";
+import { mailboxTargetKey } from "../coordination/workMailbox.js";
+import { generateHomeIdentity } from "../repository/homeIdentity.js";
+import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
+import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
+import { assertHomeWritable } from "./upgradeFence.js";
+import { CURRENT_CONFIG_SCHEMA_VERSION, CURRENT_PENDING_WAKEUP_SCHEMA_VERSION, CURRENT_WORK_MAILBOX_SCHEMA_VERSION, executionLaneActiveRunKey, StorageConflictError, StorageCancelledError, StorageRecordError, FileTaskStore } from "./taskStore.js";
+import { migrateSqliteSchema, SQLITE_AGGREGATE_VERSION, SQLITE_LAYOUT_VERSION, TELEMETRY_KEEP_PER_GENERATION, TELEMETRY_RUN_CAP } from "./sqliteSchema.js";
+const DEFAULT_CONFIG = { schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION };
+function numericCompare(left, right) {
+    return left.localeCompare(right, undefined, { numeric: true });
+}
+/** True when the better-sqlite3 error is a UNIQUE/PRIMARY KEY constraint failure. */
+function isUniqueConstraint(error) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === "SQLITE_CONSTRAINT_PRIMARYKEY"
+        || error?.code === "SQLITE_CONSTRAINT_UNIQUE";
+}
+/** Project a leader-role work mailbox's pending batch to a PendingWakeup (mirrors taskStore.ts). */
+function pendingWakeupProjection(mailbox) {
+    if (mailbox === null || mailbox.target.kind !== "role" || mailbox.target.roleName !== "leader"
+        || mailbox.pending === null) {
+        return null;
+    }
+    return {
+        schemaVersion: CURRENT_PENDING_WAKEUP_SCHEMA_VERSION,
+        taskId: mailbox.target.taskId,
+        reasons: [...mailbox.pending.reasons],
+        requestCount: mailbox.pending.requestCount,
+        firstRequestedAt: mailbox.pending.firstQueuedAt,
+        lastRequestedAt: mailbox.pending.lastQueuedAt
+    };
+}
+export class SqliteTaskStore {
+    #db;
+    #rootDir;
+    #migration;
+    #inTransaction = false;
+    #dirty = false;
+    constructor(rootDir, _options = {}) {
+        this.#rootDir = rootDir;
+        this.#migration = _options.migration ?? false;
+        mkdirSync(rootDir, { recursive: true, mode: 0o700 });
+        const filename = _options.databaseFilename ?? "yui.db";
+        this.#db = new Database(join(rootDir, filename));
+        // §4.1 / §9: WAL, no fsync weakening, FKs on, busy timeout for CLI contention.
+        this.#db.pragma("journal_mode = WAL");
+        this.#db.pragma("synchronous = FULL");
+        this.#db.pragma("foreign_keys = ON");
+        this.#db.pragma("busy_timeout = 5000");
+        this.#db.pragma("wal_autocheckpoint = 1000");
+        migrateSqliteSchema(this.#db);
+        this.#seedHomeMeta();
+        this.#seedConfig();
+    }
+    rootDirectory() { return this.#rootDir; }
+    /** Close the underlying database connection. */
+    close() { this.#db.close(); }
+    // -- transaction primitives -------------------------------------------------
+    #seedHomeMeta() {
+        const now = new Date().toISOString();
+        const identity = generateHomeIdentity(new Date());
+        this.#db.prepare(`INSERT OR IGNORE INTO home_meta (id, home_identity, revision, layout_version, aggregate_version, created_at, updated_at)
+       VALUES (1, ?, 0, ?, ?, ?, ?)`).run(JSON.stringify(identity), SQLITE_LAYOUT_VERSION, SQLITE_AGGREGATE_VERSION, now, now);
+    }
+    #seedConfig() {
+        this.#db.prepare(`INSERT OR IGNORE INTO config (id, payload, updated_at) VALUES (1, ?, ?)`).run(JSON.stringify(DEFAULT_CONFIG), new Date().toISOString());
+    }
+    #now() { return new Date().toISOString(); }
+    #json(value) { return JSON.stringify(value); }
+    #parse(text) { return JSON.parse(text); }
+    #begin() {
+        this.#db.exec("BEGIN IMMEDIATE");
+        this.#inTransaction = true;
+        this.#dirty = false;
+    }
+    #commit() {
+        this.#db.exec("COMMIT");
+        this.#inTransaction = false;
+        this.#dirty = false;
+    }
+    #rollback() {
+        try {
+            this.#db.exec("ROLLBACK");
+        }
+        catch { /* already closed */ }
+        this.#inTransaction = false;
+        this.#dirty = false;
+    }
+    /** The upgrade-admission fence, honored at the single write moment (§9). */
+    #prepareWrite() {
+        // The staged migration populates the sidecar database while the upgrade
+        // fence is active (the migration IS the upgrade), so it bypasses the
+        // per-write admission check. Production stores never set migration mode.
+        if (this.#migration)
+            return;
+        assertHomeWritable(this.#rootDir);
+    }
+    #bumpRevision() {
+        this.#db.prepare("UPDATE home_meta SET revision = revision + 1, updated_at = ? WHERE id = 1").run(this.#now());
+    }
+    /**
+     * Run a mutating closure. Inside an outer {@link transaction} it joins that
+     * transaction (single revision bump at the outer commit); standalone it takes
+     * the write lock, checks the fence, bumps the revision, and commits.
+     */
+    #mutate(fn) {
+        if (this.#inTransaction) {
+            const result = fn();
+            this.#dirty = true;
+            return result;
+        }
+        this.#prepareWrite();
+        this.#begin();
+        try {
+            const result = fn();
+            if (!this.#migration) {
+                this.#bumpRevision();
+            }
+            this.#commit();
+            return result;
+        }
+        catch (error) {
+            this.#rollback();
+            throw error;
+        }
+    }
+    /**
+     * The file-store's `transaction(closure)`: a single BEGIN IMMEDIATE … COMMIT.
+     * Nested calls join the outer transaction. The revision is bumped once, at
+     * commit, only when the closure wrote.
+     */
+    transaction(execute, options) {
+        if (this.#inTransaction)
+            return execute(this);
+        this.#begin();
+        try {
+            const result = execute(this);
+            if (this.#dirty) {
+                this.#prepareWrite();
+                if (options?.requestId !== undefined) {
+                    this.#insertOutbox(options.requestId, options.outboxCommand ?? null);
+                }
+                // The staged migration sets the revision explicitly via
+                // migrationSetHomeMeta; the commit must not bump it.
+                if (!this.#migration) {
+                    this.#bumpRevision();
+                }
+            }
+            this.#commit();
+            return result;
+        }
+        catch (error) {
+            this.#rollback();
+            throw error;
+        }
+    }
+    /**
+     * Revision CAS (§5.3): run `execute` only when the global revision is still
+     * `expectedRevision`; otherwise throw {@link StorageConflictError}. The check
+     * and the increment happen in the same write transaction.
+     */
+    transactionWithRevisionCas(expectedRevision, execute, options) {
+        if (this.#inTransaction)
+            return execute(this);
+        this.#begin();
+        try {
+            const current = this.getRevision();
+            if (current !== expectedRevision) {
+                throw new StorageConflictError(`Storage revision conflict (expected ${expectedRevision}, found ${current}).`);
+            }
+            const result = execute(this);
+            if (this.#dirty) {
+                this.#prepareWrite();
+                if (options?.requestId !== undefined) {
+                    this.#insertOutbox(options.requestId, options.outboxCommand ?? null);
+                }
+                // The staged migration sets the revision explicitly via
+                // migrationSetHomeMeta; the commit must not bump it.
+                if (!this.#migration) {
+                    this.#bumpRevision();
+                }
+            }
+            this.#commit();
+            return result;
+        }
+        catch (error) {
+            this.#rollback();
+            if (error instanceof StorageConflictError)
+                throw error;
+            throw error;
+        }
+    }
+    /** The current global revision (the cross-writer CAS token). */
+    getRevision() {
+        const row = this.#db.prepare("SELECT revision FROM home_meta WHERE id = 1").get();
+        return row.revision;
+    }
+    /**
+     * Run an ordered command batch inside one `BEGIN IMMEDIATE … COMMIT`, yielding
+     * to the event loop between commands so a cancellation signal can interrupt
+     * the batch (§3.1). The persistence worker uses this for `transactionAsync`:
+     * a cancelled batch rolls back (the db is unchanged); already-committed
+     * batches are not undone (their effects are idempotent and caller-owned).
+     *
+     * Each command is `{op, args}` where `op` is a `TaskStore` method name. The
+     * batch runs on the single writer connection, so writes are serialized exactly
+     * as the synchronous {@link transaction} (§3.2). The revision is bumped once
+     * at commit when the batch wrote; an optional `requestId` records the effect
+     * in the durable outbox for exactly-once replay (§5.4).
+     */
+    async transactionAsyncBatch(commands, options = {}) {
+        if (this.#inTransaction) {
+            // Nested inside a synchronous transaction: run without yielding (the
+            // caller already holds the write lock).
+            return commands.map((command) => this.#executeCommand(command.op, command.args));
+        }
+        this.#begin();
+        try {
+            // Revision CAS (§5.3): the check and the increment happen in the same
+            // write transaction, exactly as transactionWithRevisionCas.
+            if (options.expectedRevision !== undefined) {
+                const current = this.getRevision();
+                if (current !== options.expectedRevision) {
+                    throw new StorageConflictError(`Storage revision conflict (expected ${options.expectedRevision}, found ${current}).`);
+                }
+            }
+            const results = [];
+            for (const command of commands) {
+                if (options.shouldCancel?.() === true) {
+                    throw new StorageCancelledError(`Storage command batch cancelled before op '${command.op}'.`);
+                }
+                results.push(this.#executeCommand(command.op, command.args));
+                // Yield so the worker's message loop can observe a cancel signal
+                // between statements (§3.1). A single-command batch still yields once
+                // so a cancel that raced the batch start is honoured before commit.
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+            if (options.shouldCancel?.() === true) {
+                throw new StorageCancelledError("Storage command batch cancelled before commit.");
+            }
+            if (this.#dirty) {
+                this.#prepareWrite();
+                if (options.requestId !== undefined) {
+                    this.#insertOutbox(options.requestId, options.outboxCommand ?? commands);
+                }
+                if (!this.#migration) {
+                    this.#bumpRevision();
+                }
+            }
+            this.#commit();
+            return results;
+        }
+        catch (error) {
+            this.#rollback();
+            throw error;
+        }
+    }
+    /** Invoke a TaskStore method by name (used by the worker's command batches). */
+    #executeCommand(op, args) {
+        const method = this[op];
+        if (typeof method !== "function") {
+            throw new StorageRecordError(`Unknown store command: ${op}`);
+        }
+        return method.apply(this, args);
+    }
+    // -- outbox (§5.4) ----------------------------------------------------------
+    #insertOutbox(requestId, command) {
+        try {
+            this.#db.prepare(`INSERT INTO outbox (request_id, command, state, created_at) VALUES (?, ?, 'pending', ?)`).run(requestId, this.#json(command), this.#now());
+        }
+        catch (error) {
+            if (isUniqueConstraint(error)) {
+                throw new StorageConflictError(`Outbox request already applied: ${requestId}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Enqueue an outbox row idempotently. Returns true when a new row was
+     * inserted, false when `requestId` was already present (exactly-once).
+     */
+    enqueueOutbox(requestId, command) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare(`INSERT OR IGNORE INTO outbox (request_id, command, state, created_at) VALUES (?, ?, 'pending', ?)`).run(requestId, this.#json(command), this.#now());
+            return result.changes > 0;
+        });
+    }
+    /** Outbox rows still awaiting acknowledgement (the replay source after a crash). */
+    listPendingOutbox() {
+        const rows = this.#db.prepare("SELECT request_id, command, created_at FROM outbox WHERE state = 'pending' ORDER BY outbox_id").all();
+        return rows.map((row) => ({
+            requestId: row.request_id,
+            command: this.#parse(row.command),
+            createdAt: row.created_at
+        }));
+    }
+    /**
+     * True when an outbox row already exists for `requestId` (the effect committed).
+     * The persistence worker consults this before re-executing a retried write so a
+     * main-thread retry after a worker restart never double-applies (§3.1, §5.4).
+     */
+    hasOutboxEntry(requestId) {
+        const row = this.#db.prepare("SELECT 1 FROM outbox WHERE request_id = ?").get(requestId);
+        return row !== undefined;
+    }
+    /** Mark an outbox row as applied (idempotent). */
+    markOutboxApplied(requestId) {
+        this.#mutate(() => {
+            this.#db.prepare("UPDATE outbox SET state = 'applied', applied_at = ? WHERE request_id = ?").run(this.#now(), requestId);
+        });
+    }
+    // -- ID allocation ----------------------------------------------------------
+    /**
+     * Global IDs (`task-<n>`, `project-<n>`) from `global_sequences` (§5.3). The
+     * file store computes these by scanning existing IDs (a read); the counter is
+     * the design's replacement and is allocated without bumping the revision.
+     */
+    #nextGlobalId(name) {
+        const allocate = this.#db.transaction(() => {
+            const row = this.#db.prepare(`INSERT INTO global_sequences (name, high_water) VALUES (?, 1)
+         ON CONFLICT(name) DO UPDATE SET high_water = high_water + 1
+         RETURNING high_water`).get(name);
+            return `${name}-${row.high_water}`;
+        });
+        return allocate();
+    }
+    /**
+     * Task-record IDs from `id_sequences` (replaces StoredTask.idHighWaterMarks).
+     * Allocating a high-water mark is a durable write, so it bumps the revision
+     * exactly as the file store does.
+     */
+    #nextTaskRecordId(taskId, kind) {
+        this.#requireTask(taskId);
+        return this.#mutate(() => {
+            const row = this.#db.prepare(`INSERT INTO id_sequences (task_id, kind, high_water) VALUES (?, ?, 1)
+         ON CONFLICT(task_id, kind) DO UPDATE SET high_water = high_water + 1
+         RETURNING high_water`).get(taskId, kind);
+            return `${TASK_RECORD_ID_PREFIXES[kind]}-${row.high_water}`;
+        });
+    }
+    #peekTaskRecordId(taskId, kind) {
+        this.#requireTask(taskId);
+        const row = this.#db.prepare("SELECT high_water FROM id_sequences WHERE task_id = ? AND kind = ?").get(taskId, kind);
+        return `${TASK_RECORD_ID_PREFIXES[kind]}-${(row?.high_water ?? 0) + 1}`;
+    }
+    #requireTask(taskId) {
+        const row = this.#db.prepare("SELECT 1 FROM task_records WHERE task_id = ?").get(taskId);
+        if (row === undefined)
+            throw new StorageRecordError(`Task not found: ${taskId}`);
+    }
+    // -- migration bulk-load helpers (state.json -> SQLite, task-21 §8) ----------
+    // These are used only by the staged offline migration, which runs with the
+    // `migration` option (fence bypass). They seed infrastructure tables that the
+    // document owns (home identity/revision, global and per-task ID high-water
+    // marks) so the opened store continues from the same counters.
+    /** Preserve the document's Home identity and revision in `home_meta`. */
+    migrationSetHomeMeta(identity, revision) {
+        this.#mutate(() => {
+            this.#db.prepare(`UPDATE home_meta SET home_identity = ?, revision = ?, updated_at = ? WHERE id = 1`).run(this.#json(identity), revision, this.#now());
+        });
+    }
+    /** Seed a global ID high-water mark (task/project) at least `highWater`. */
+    migrationSeedGlobalSequence(name, highWater) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO global_sequences (name, high_water) VALUES (?, ?)
+         ON CONFLICT(name) DO UPDATE SET high_water = MAX(high_water, ?)`).run(name, highWater, highWater);
+        });
+    }
+    /** Seed a per-task ID high-water mark at least `highWater`. */
+    migrationSeedIdSequence(taskId, kind, highWater) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO id_sequences (task_id, kind, high_water) VALUES (?, ?, ?)
+         ON CONFLICT(task_id, kind) DO UPDATE SET high_water = MAX(high_water, ?)`).run(taskId, kind, highWater, highWater);
+        });
+    }
+    // -- generic payload helpers ------------------------------------------------
+    #getPayload(table, where, params) {
+        const row = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).get(...params);
+        return row === undefined ? null : this.#parse(row.payload);
+    }
+    #listPayload(table, where, params) {
+        const rows = this.#db.prepare(`SELECT payload FROM ${table} WHERE ${where}`).all(...params);
+        return rows.map((row) => this.#parse(row.payload));
+    }
+    #sortById(rows, idOf) {
+        return [...rows].sort((left, right) => numericCompare(idOf(left), idOf(right)));
+    }
+    // -- config / identity ------------------------------------------------------
+    getConfig() {
+        const row = this.#db.prepare("SELECT payload FROM config WHERE id = 1").get();
+        return this.#parse(row.payload);
+    }
+    saveConfig(config) {
+        this.#mutate(() => {
+            this.#db.prepare("UPDATE config SET payload = ?, updated_at = ? WHERE id = 1").run(this.#json(config), this.#now());
+        });
+    }
+    getHomeIdentity() {
+        const row = this.#db.prepare("SELECT home_identity FROM home_meta WHERE id = 1").get();
+        return this.#parse(row.home_identity);
+    }
+    getReviewConfig() {
+        return this.getConfig().review ?? null;
+    }
+    // -- configured agents ------------------------------------------------------
+    saveConfiguredAgent(agent) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO configured_agents (id, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(agent.id, this.#json(agent), this.#now());
+        });
+    }
+    createConfiguredAgentIfAbsent(agent) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("INSERT OR IGNORE INTO configured_agents (id, payload, updated_at) VALUES (?, ?, ?)").run(agent.id, this.#json(agent), this.#now());
+            return result.changes > 0 ? agent : null;
+        });
+    }
+    updateConfiguredAgent(id, patch, now) {
+        return this.transaction((store) => {
+            const existing = store.getConfiguredAgent(id);
+            if (existing === null)
+                return null;
+            const candidate = { ...existing, ...patch, updatedAt: now.toISOString() };
+            const unchanged = isDeepStrictEqual({ ...existing, updatedAt: candidate.updatedAt }, candidate);
+            if (unchanged)
+                return { status: "unchanged", agent: existing };
+            store.saveConfiguredAgent(candidate);
+            return { status: "updated", agent: candidate };
+        });
+    }
+    listConfiguredAgents() {
+        return this.#sortById(this.#listPayload("configured_agents", "1=1", []), (agent) => agent.id);
+    }
+    getConfiguredAgent(id) {
+        return this.#getPayload("configured_agents", "id = ?", [id]);
+    }
+    removeConfiguredAgent(id) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("DELETE FROM configured_agents WHERE id = ?").run(id);
+            return result.changes > 0;
+        });
+    }
+    // -- projects ---------------------------------------------------------------
+    nextProjectId() { return this.#nextGlobalId("project"); }
+    saveProject(project) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO projects (id, name, path, payload, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET name = excluded.name, path = excluded.path, payload = excluded.payload, updated_at = excluded.updated_at`).run(project.id, project.name, project.path, this.#json(project), project.createdAt, project.updatedAt);
+        });
+    }
+    createProjectIfAbsent(project) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("INSERT OR IGNORE INTO projects (id, name, path, payload, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)").run(project.id, project.name, project.path, this.#json(project), project.createdAt, project.updatedAt);
+            return result.changes > 0 ? project : null;
+        });
+    }
+    listProjects() {
+        return this.#sortById(this.#listPayload("projects", "1=1", []), (project) => project.id);
+    }
+    getProject(id) {
+        return this.#getPayload("projects", "id = ?", [id]);
+    }
+    removeProject(id) {
+        return this.#mutate(() => this.#db.prepare("DELETE FROM projects WHERE id = ?").run(id).changes > 0);
+    }
+    // -- agent profiles ---------------------------------------------------------
+    saveAgentProfile(profile) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO agent_profiles (id, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(profile.id, this.#json(profile), this.#now());
+        });
+    }
+    createAgentProfileIfAbsent(profile) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("INSERT OR IGNORE INTO agent_profiles (id, payload, updated_at) VALUES (?, ?, ?)").run(profile.id, this.#json(profile), this.#now());
+            return result.changes > 0 ? profile : null;
+        });
+    }
+    listAgentProfiles() {
+        return this.#sortById(this.#listPayload("agent_profiles", "1=1", []), (profile) => profile.id);
+    }
+    getAgentProfile(id) {
+        return this.#getPayload("agent_profiles", "id = ?", [id]);
+    }
+    removeAgentProfile(id) {
+        return this.#mutate(() => this.#db.prepare("DELETE FROM agent_profiles WHERE id = ?").run(id).changes > 0);
+    }
+    // -- global roles -----------------------------------------------------------
+    saveGlobalRole(role) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO global_roles (name, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(role.name, this.#json(role), this.#now());
+        });
+    }
+    saveGlobalRoleWithSessionSet(role, sessions) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO global_roles (name, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(role.name, this.#json(role), this.#now());
+            if (sessions !== null) {
+                this.#db.prepare(`INSERT INTO global_role_session_sets (name, payload, updated_at) VALUES (?, ?, ?)
+           ON CONFLICT(name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(role.name, this.#json(sessions), this.#now());
+            }
+        });
+    }
+    createGlobalRoleIfAbsent(role) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("INSERT OR IGNORE INTO global_roles (name, payload, updated_at) VALUES (?, ?, ?)").run(role.name, this.#json(role), this.#now());
+            return result.changes > 0 ? role : null;
+        });
+    }
+    listGlobalRoles() {
+        return this.#sortById(this.#listPayload("global_roles", "1=1", []), (role) => role.name);
+    }
+    getGlobalRole(name) {
+        return this.#getPayload("global_roles", "name = ?", [name]);
+    }
+    removeGlobalRole(name) {
+        return this.#mutate(() => this.#db.prepare("DELETE FROM global_roles WHERE name = ?").run(name).changes > 0);
+    }
+    getGlobalRoleSessionSet(name) {
+        return this.#getPayload("global_role_session_sets", "name = ?", [name]);
+    }
+    listGlobalRoleSessionSets() {
+        const rows = this.#listPayload("global_role_session_sets", "1=1", []);
+        return [...rows].sort((left, right) => numericCompare(left.owner.roleName, right.owner.roleName));
+    }
+    saveGlobalRoleSessionSet(sessions) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO global_role_session_sets (name, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(sessions.owner.roleName, this.#json(sessions), this.#now());
+        });
+    }
+    // -- tasks ------------------------------------------------------------------
+    nextTaskId() { return this.#nextGlobalId("task"); }
+    saveTask(task) {
+        if (typeof task.id !== "string" || task.id.length === 0) {
+            throw new StorageRecordError("Task id is required.");
+        }
+        this.#mutate(() => {
+            for (const binding of task.projectBindings) {
+                const found = this.#db.prepare("SELECT 1 FROM projects WHERE id = ?").get(binding.projectId);
+                if (found === undefined)
+                    throw new StorageRecordError(`Task Project not found: ${binding.projectId}`);
+            }
+            const isActive = task.status === "active" ? 1 : 0;
+            // The catalog projection is inserted first because task_records FKs it.
+            this.#db.prepare(`INSERT INTO tasks_catalog (task_id, status, lifecycle, is_active, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id) DO UPDATE SET status = excluded.status, lifecycle = excluded.lifecycle,
+           is_active = excluded.is_active, updated_at = excluded.updated_at`).run(task.id, task.status, task.status, isActive, task.createdAt, task.updatedAt);
+            this.#db.prepare(`INSERT INTO task_records (task_id, payload, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(task_id) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(task.id, this.#json(task), this.#now());
+        });
+    }
+    listTasks() {
+        const tasks = this.#listPayload("task_records", "1=1", []);
+        return this.#sortById(tasks, (task) => task.id);
+    }
+    getTask(id) {
+        return this.#getPayload("task_records", "task_id = ?", [id]);
+    }
+    /** Task ids flagged active in the catalog projection (the global active index). */
+    listActiveTaskIds() {
+        const rows = this.#db.prepare("SELECT task_id FROM tasks_catalog WHERE is_active = 1 ORDER BY task_id").all();
+        return rows.map((row) => row.task_id);
+    }
+    getTaskBrief(taskId) {
+        const row = this.#db.prepare("SELECT brief FROM task_records WHERE task_id = ?").get(taskId);
+        if (row === undefined || row.brief === null)
+            return null;
+        return this.#parse(row.brief);
+    }
+    saveTaskBrief(taskId, brief) {
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare("UPDATE task_records SET brief = ?, updated_at = ? WHERE task_id = ?")
+                .run(this.#json(brief), this.#now(), taskId);
+        });
+    }
+    clearTaskBrief(taskId) {
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare("UPDATE task_records SET brief = NULL, updated_at = ? WHERE task_id = ?").run(this.#now(), taskId);
+        });
+    }
+    // -- change sets ------------------------------------------------------------
+    nextChangeSetId(taskId) { return this.#nextTaskRecordId(taskId, "changeSet"); }
+    saveChangeSet(taskId, changeSet) {
+        if (changeSet.taskId !== taskId)
+            throw new StorageRecordError(`Change set belongs to another Task: ${changeSet.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO change_sets (task_id, change_set_id, project_id, head_sha, payload, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, change_set_id) DO UPDATE SET project_id = excluded.project_id,
+           head_sha = excluded.head_sha, payload = excluded.payload`).run(taskId, changeSet.id, changeSet.projectId, changeSet.headCommit, this.#json(changeSet), changeSet.createdAt);
+        });
+    }
+    listChangeSets(taskId) {
+        return this.#sortById(this.#listPayload("change_sets", "task_id = ?", [taskId]), (changeSet) => changeSet.id);
+    }
+    getChangeSet(taskId, changeSetId) {
+        return this.#getPayload("change_sets", "task_id = ? AND change_set_id = ?", [taskId, changeSetId]);
+    }
+    // -- integration attempts ---------------------------------------------------
+    nextIntegrationAttemptId(taskId) { return this.#nextTaskRecordId(taskId, "integrationAttempt"); }
+    saveIntegrationAttempt(taskId, attempt) {
+        if (attempt.taskId !== taskId)
+            throw new StorageRecordError(`Integration attempt belongs to another Task: ${attempt.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO integration_attempts (task_id, integration_id, status, payload, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, integration_id) DO UPDATE SET status = excluded.status,
+           payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, attempt.id, attempt.status, this.#json(attempt), this.#now());
+        });
+    }
+    listIntegrationAttempts(taskId) {
+        return this.#sortById(this.#listPayload("integration_attempts", "task_id = ?", [taskId]), (attempt) => attempt.id);
+    }
+    getIntegrationAttempt(taskId, integrationId) {
+        return this.#getPayload("integration_attempts", "task_id = ? AND integration_id = ?", [taskId, integrationId]);
+    }
+    // -- task roles -------------------------------------------------------------
+    saveRole(taskId, role) {
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO task_roles (task_id, role_name, payload, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, role.name, this.#json(role), this.#now());
+        });
+    }
+    listRoles(taskId) {
+        return this.#sortById(this.#listPayload("task_roles", "task_id = ?", [taskId]), (role) => role.name);
+    }
+    getRole(taskId, name) {
+        return this.#getPayload("task_roles", "task_id = ? AND role_name = ?", [taskId, name]);
+    }
+    saveTaskRoleWithSessionSet(role, sessions) {
+        this.#requireTask(role.name ? role.taskId : sessions.owner.taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO task_roles (task_id, role_name, payload, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(sessions.owner.taskId, role.name, this.#json(role), this.#now());
+            this.#db.prepare(`INSERT INTO role_session_sets (task_id, role_name, payload, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(sessions.owner.taskId, sessions.owner.roleName, this.#json(sessions), this.#now());
+        });
+    }
+    removeTaskRole(taskId, name) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare("DELETE FROM task_roles WHERE task_id = ? AND role_name = ?").run(taskId, name);
+            return result.changes > 0;
+        });
+    }
+    // -- managed workspaces -----------------------------------------------------
+    saveManagedWorkspace(workspace) {
+        const taskId = workspace.owner.taskId;
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            const ownerId = managedWorkspaceKey(workspace.owner);
+            this.#db.prepare(`INSERT INTO managed_workspaces (owner_kind, owner_id, task_id, path, payload, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(owner_kind, owner_id) DO UPDATE SET task_id = excluded.task_id, path = excluded.path,
+           payload = excluded.payload, status = excluded.status, updated_at = excluded.updated_at`).run(workspace.owner.type, ownerId, taskId, workspace.root, this.#json(workspace), "active", workspace.createdAt, workspace.updatedAt);
+        });
+    }
+    listManagedWorkspaces(taskId) {
+        return this.#sortById(this.#listPayload("managed_workspaces", "task_id = ?", [taskId]), (workspace) => managedWorkspaceKey(workspace.owner));
+    }
+    listManagedWorkspace(taskId) {
+        return this.listManagedWorkspaces(taskId);
+    }
+    getManagedWorkspace(owner) {
+        return this.#getPayload("managed_workspaces", "owner_kind = ? AND owner_id = ?", [owner.type, managedWorkspaceKey(owner)]);
+    }
+    getTaskWorkspace(taskId) {
+        return this.getManagedWorkspace({ type: "task", taskId });
+    }
+    getWorkItemWorkspace(taskId, workItemId) {
+        return this.getManagedWorkspace({ type: "work-item", taskId, workItemId });
+    }
+    getReviewRoundWorkspace(taskId, reviewRoundId) {
+        return this.getManagedWorkspace({ type: "review-round", taskId, reviewRoundId });
+    }
+    getIntegrationWorkspace(taskId, integrationAttemptId) {
+        return this.getManagedWorkspace({ type: "integration-attempt", taskId, integrationAttemptId });
+    }
+    removeManagedWorkspace(owner) {
+        this.#requireTask(owner.taskId);
+        return this.#mutate(() => {
+            const result = this.#db.prepare("DELETE FROM managed_workspaces WHERE owner_kind = ? AND owner_id = ?").run(owner.type, managedWorkspaceKey(owner));
+            return result.changes > 0;
+        });
+    }
+    // -- role session sets ------------------------------------------------------
+    getRoleSessionSet(taskId, roleName) {
+        return this.#getPayload("role_session_sets", "task_id = ? AND role_name = ?", [taskId, roleName]);
+    }
+    getTaskRoleSessionSet(taskId, roleName) {
+        return this.getRoleSessionSet(taskId, roleName);
+    }
+    listRoleSessionSets(taskId) {
+        return this.#sortById(this.#listPayload("role_session_sets", "task_id = ?", [taskId]), (set) => set.owner.roleName);
+    }
+    saveRoleSessionSet(sessions) {
+        const taskId = sessions.owner.taskId;
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO role_session_sets (task_id, role_name, payload, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, sessions.owner.roleName, this.#json(sessions), this.#now());
+        });
+    }
+    saveTaskRoleSessionSet(sessions) {
+        this.saveRoleSessionSet(sessions);
+    }
+    getRoleSession(taskId, roleName) {
+        const set = this.getRoleSessionSet(taskId, roleName);
+        if (set === null)
+            return null;
+        const session = set.sessions[set.activeAgentId];
+        return session === undefined ? null : session;
+    }
+    // -- work items -------------------------------------------------------------
+    nextWorkItemId(taskId) { return this.#nextTaskRecordId(taskId, "workItem"); }
+    getWorkItem(taskId, workItemId) {
+        return this.#getPayload("work_items", "task_id = ? AND work_item_id = ?", [taskId, workItemId]);
+    }
+    listWorkItems(taskId) {
+        return this.#sortById(this.#listPayload("work_items", "task_id = ?", [taskId]), (item) => item.id);
+    }
+    saveWorkItem(taskId, item) {
+        if (item.taskId !== taskId)
+            throw new StorageRecordError(`Work item belongs to another Task: ${item.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO work_items (task_id, work_item_id, status, payload, updated_at) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, work_item_id) DO UPDATE SET status = excluded.status,
+           payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, item.id, item.status, this.#json(item), this.#now());
+        });
+    }
+    // -- agent runs -------------------------------------------------------------
+    nextAgentRunId(taskId) { return this.#nextTaskRecordId(taskId, "agentRun"); }
+    peekNextAgentRunId(taskId) { return this.#peekTaskRecordId(taskId, "agentRun"); }
+    getAgentRun(taskId, runId) {
+        return this.#getPayload("agent_runs", "task_id = ? AND run_id = ?", [taskId, runId]);
+    }
+    listAgentRuns(taskId) {
+        return this.#sortById(this.#listPayload("agent_runs", "task_id = ?", [taskId]), (run) => run.id);
+    }
+    saveAgentRun(run) {
+        if (run.taskId !== undefined)
+            this.#requireTask(run.taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO agent_runs (task_id, run_id, role_name, status, payload, updated_at) VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, run_id) DO UPDATE SET role_name = excluded.role_name, status = excluded.status,
+           payload = excluded.payload, updated_at = excluded.updated_at`).run(run.taskId, run.id, run.roleName, run.status, this.#json(run), this.#now());
+        });
+    }
+    // -- review rounds ----------------------------------------------------------
+    nextReviewRoundId(taskId) { return this.#nextTaskRecordId(taskId, "reviewRound"); }
+    getReviewRound(taskId, reviewRoundId) {
+        return this.#getPayload("review_rounds", "task_id = ? AND review_round_id = ?", [taskId, reviewRoundId]);
+    }
+    listReviewRounds(taskId) {
+        return this.#sortById(this.#listPayload("review_rounds", "task_id = ?", [taskId]), (round) => round.id);
+    }
+    saveReviewRound(taskId, round) {
+        if (round.taskId !== taskId)
+            throw new StorageRecordError(`Review round belongs to another Task: ${round.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO review_rounds (task_id, review_round_id, status, payload, updated_at) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, review_round_id) DO UPDATE SET status = excluded.status,
+           payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, round.id, round.status, this.#json(round), this.#now());
+        });
+    }
+    // -- active runs ------------------------------------------------------------
+    #saveActiveRun(taskId, pointer, runId) {
+        this.#mutate(() => {
+            const payload = this.#json({ schemaVersion: 3, runId });
+            this.#db.prepare(`INSERT INTO active_runs (task_id, pointer, run_id, payload, updated_at) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, pointer) DO UPDATE SET run_id = excluded.run_id, payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, pointer, runId, payload, this.#now());
+        });
+    }
+    #getActiveRun(taskId, pointer) {
+        const row = this.#db.prepare("SELECT run_id FROM active_runs WHERE task_id = ? AND pointer = ?").get(taskId, pointer);
+        if (row === undefined)
+            return null;
+        return this.getAgentRun(taskId, row.run_id);
+    }
+    #clearActiveRun(taskId, pointer) {
+        this.#mutate(() => {
+            this.#db.prepare("DELETE FROM active_runs WHERE task_id = ? AND pointer = ?").run(taskId, pointer);
+        });
+    }
+    getActiveAgentRun(taskId, roleName) {
+        return this.#getActiveRun(taskId, roleName);
+    }
+    saveActiveAgentRun(run) {
+        this.#saveActiveRun(run.taskId, run.roleName, run.id);
+    }
+    clearActiveAgentRun(taskId, roleName) {
+        this.#clearActiveRun(taskId, roleName);
+    }
+    getActiveExecutionLaneRun(taskId, executionGroupId, executionLaneId) {
+        return this.#getActiveRun(taskId, executionLaneActiveRunKey(executionGroupId, executionLaneId));
+    }
+    saveActiveExecutionLaneRun(run) {
+        if (run.executionGroupId === undefined || run.executionLaneId === undefined) {
+            throw new StorageRecordError(`Active execution-lane run requires group and lane ids: ${run.id}`);
+        }
+        this.#saveActiveRun(run.taskId, executionLaneActiveRunKey(run.executionGroupId, run.executionLaneId), run.id);
+    }
+    clearActiveExecutionLaneRun(taskId, executionGroupId, executionLaneId) {
+        this.#clearActiveRun(taskId, executionLaneActiveRunKey(executionGroupId, executionLaneId));
+    }
+    // -- messages ----------------------------------------------------------------
+    nextMessageId(taskId) { return this.#nextTaskRecordId(taskId, "message"); }
+    saveMessage(taskId, message) {
+        if (message.taskId !== taskId)
+            throw new StorageRecordError(`Message belongs to another Task: ${message.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            const seq = this.#idSequence(message.id, "message");
+            this.#db.prepare(`INSERT INTO messages (task_id, message_id, seq, payload, created_at) VALUES (?, ?, ?, ?, ?)`).run(taskId, message.id, seq, this.#json(message), message.createdAt);
+            this.#observeHighWater(taskId, "message", seq);
+        });
+    }
+    listMessages(taskId) {
+        return this.#sortById(this.#listPayload("messages", "task_id = ?", [taskId]), (message) => message.id);
+    }
+    // -- input requests ----------------------------------------------------------
+    nextInputRequestId(taskId) { return this.#nextTaskRecordId(taskId, "inputRequest"); }
+    saveInputRequest(taskId, request) {
+        if (request.taskId !== taskId)
+            throw new StorageRecordError(`Input request belongs to another Task: ${request.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO input_requests (task_id, input_id, status, payload, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, input_id) DO UPDATE SET status = excluded.status, payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, request.id, request.status, this.#json(request), request.createdAt, this.#now());
+        });
+    }
+    getInputRequest(taskId, requestId) {
+        return this.#getPayload("input_requests", "task_id = ? AND input_id = ?", [taskId, requestId]);
+    }
+    listInputRequests(taskId) {
+        return this.#sortById(this.#listPayload("input_requests", "task_id = ?", [taskId]), (request) => request.id);
+    }
+    listAllInputRequests() {
+        return this.#sortById(this.#listPayload("input_requests", "1=1", []), (request) => `${request.taskId}/${request.id}`);
+    }
+    // -- decisions ----------------------------------------------------------------
+    nextDecisionId(taskId) { return this.#nextTaskRecordId(taskId, "decision"); }
+    saveDecision(taskId, decision) {
+        if (decision.taskId !== taskId)
+            throw new StorageRecordError(`Decision belongs to another Task: ${decision.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO decisions (task_id, decision_id, payload, created_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, decision_id) DO UPDATE SET payload = excluded.payload`).run(taskId, decision.id, this.#json(decision), decision.createdAt);
+        });
+    }
+    listDecisions(taskId) {
+        return this.#sortById(this.#listPayload("decisions", "task_id = ?", [taskId]), (decision) => decision.id);
+    }
+    getDecision(taskId, decisionId) {
+        return this.#getPayload("decisions", "task_id = ? AND decision_id = ?", [taskId, decisionId]);
+    }
+    // -- milestones ----------------------------------------------------------------
+    nextMilestoneId(taskId) { return this.#nextTaskRecordId(taskId, "milestone"); }
+    saveMilestone(taskId, milestone) {
+        if (milestone.taskId !== taskId)
+            throw new StorageRecordError(`Milestone belongs to another Task: ${milestone.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO milestones (task_id, milestone_id, payload, created_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, milestone_id) DO UPDATE SET payload = excluded.payload`).run(taskId, milestone.id, this.#json(milestone), milestone.createdAt);
+        });
+    }
+    listMilestones(taskId) {
+        return this.#sortById(this.#listPayload("milestones", "task_id = ?", [taskId]), (milestone) => milestone.id);
+    }
+    getMilestone(taskId, milestoneId) {
+        return this.#getPayload("milestones", "task_id = ? AND milestone_id = ?", [taskId, milestoneId]);
+    }
+    // -- events -------------------------------------------------------------------
+    nextEventId(taskId) { return this.#nextTaskRecordId(taskId, "event"); }
+    saveEvent(taskId, event) {
+        if (event.taskId !== taskId)
+            throw new StorageRecordError(`Task event belongs to another Task: ${event.taskId}`);
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            const seq = this.#idSequence(event.id, "event");
+            // Events are terminal/semantic: retained individually, never pruned (§9).
+            this.#db.prepare(`INSERT INTO events (task_id, event_id, type, occurred_at, payload) VALUES (?, ?, ?, ?, ?)`).run(taskId, event.id, event.type, event.createdAt, this.#json(event));
+            this.#observeHighWater(taskId, "event", seq);
+        });
+    }
+    listEvents(taskId) {
+        return this.#sortById(this.#listPayload("events", "task_id = ?", [taskId]), (event) => event.id);
+    }
+    // -- high-water maintenance ---------------------------------------------------
+    /** Extract the numeric suffix of a `<prefix>-<n>` record id. */
+    #idSequence(id, kind) {
+        const match = new RegExp(`^${TASK_RECORD_ID_PREFIXES[kind]}-(\\d+)$`).exec(id);
+        if (match === null)
+            throw new StorageRecordError(`Task-local ${kind} id is invalid: ${id}.`);
+        return Number.parseInt(match[1], 10);
+    }
+    /** Advance the per-task high-water mark to at least `seq` (mirrors observeTaskRecordId). */
+    #observeHighWater(taskId, kind, seq) {
+        this.#db.prepare(`INSERT INTO id_sequences (task_id, kind, high_water) VALUES (?, ?, ?)
+       ON CONFLICT(task_id, kind) DO UPDATE SET high_water = MAX(high_water, ?)`).run(taskId, kind, seq, seq);
+    }
+    // -- work mailboxes ------------------------------------------------------------
+    #mailboxCols(target) {
+        return {
+            targetKind: target.kind,
+            taskId: "taskId" in target ? target.taskId : null,
+            roleName: "roleName" in target ? target.roleName : null,
+            targetKey: mailboxTargetKey(target)
+        };
+    }
+    #rowToMailbox(row) {
+        const target = this.#targetFromCols(row.target_kind, row.task_id, row.role_name);
+        return {
+            schemaVersion: 1,
+            target,
+            nextSequence: row.next_sequence,
+            processing: row.processing === null ? null : this.#parse(row.processing),
+            pending: row.pending === null ? null : this.#parse(row.pending)
+        };
+    }
+    #targetFromCols(kind, taskId, roleName) {
+        switch (kind) {
+            case "operator": return { kind: "operator" };
+            case "task": return { kind: "task", taskId: taskId };
+            case "role": return { kind: "role", taskId: taskId, roleName: roleName };
+            case "role-runtime": return { kind: "role-runtime", taskId: taskId, roleName: roleName };
+            case "global-role-runtime": return { kind: "global-role-runtime", roleName: roleName };
+            default: throw new StorageRecordError(`Unknown mailbox target kind: ${kind}`);
+        }
+    }
+    getWorkMailbox(target) {
+        const cols = this.#mailboxCols(target);
+        const row = this.#db.prepare("SELECT target_kind, task_id, role_name, next_sequence, processing, pending FROM mailboxes WHERE target_key = ?").get(cols.targetKey);
+        return row === undefined ? null : this.#rowToMailbox(row);
+    }
+    listWorkMailboxes() {
+        const rows = this.#db.prepare("SELECT target_kind, task_id, role_name, next_sequence, processing, pending FROM mailboxes ORDER BY target_key").all();
+        return rows.map((row) => this.#rowToMailbox(row));
+    }
+    saveWorkMailbox(mailbox) {
+        const cols = this.#mailboxCols(mailbox.target);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO mailboxes (target_kind, task_id, role_name, target_key, next_sequence, processing, pending)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(target_key) DO UPDATE SET next_sequence = excluded.next_sequence,
+           processing = excluded.processing, pending = excluded.pending`).run(cols.targetKind, cols.taskId, cols.roleName, cols.targetKey, mailbox.nextSequence, mailbox.processing === null ? null : this.#json(mailbox.processing), mailbox.pending === null ? null : this.#json(mailbox.pending));
+        });
+    }
+    removeWorkMailbox(target) {
+        const cols = this.#mailboxCols(target);
+        return this.#mutate(() => {
+            const result = this.#db.prepare("DELETE FROM mailboxes WHERE target_key = ?").run(cols.targetKey);
+            return result.changes > 0;
+        });
+    }
+    /**
+     * Append a mailbox signal (§4.2). One transaction: insert the signal at the
+     * mailbox's next sequence and advance `next_sequence` on the same row. The
+     * single writer connection serializes enqueues, so sequences stay gapless per
+     * mailbox. `(mailbox_id, sequence)` is the exactly-once key.
+     */
+    enqueueMailboxSignal(target, input) {
+        return this.#mutate(() => {
+            const cols = this.#mailboxCols(target);
+            let mailboxId;
+            let sequence;
+            const existing = this.#db.prepare("SELECT mailbox_id, next_sequence FROM mailboxes WHERE target_key = ?").get(cols.targetKey);
+            if (existing === undefined) {
+                const result = this.#db.prepare(`INSERT INTO mailboxes (target_kind, task_id, role_name, target_key, next_sequence, processing, pending)
+           VALUES (?, ?, ?, ?, 1, NULL, NULL)`).run(cols.targetKind, cols.taskId, cols.roleName, cols.targetKey);
+                mailboxId = Number(result.lastInsertRowid);
+                sequence = 1;
+            }
+            else {
+                mailboxId = existing.mailbox_id;
+                sequence = existing.next_sequence;
+            }
+            this.#db.prepare(`INSERT INTO mailbox_signals (mailbox_id, sequence, reason, ref_type, ref_task_id, ref_id, occurred_at, request_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(mailboxId, sequence, input.reason, input.ref?.type ?? null, input.ref && "taskId" in input.ref ? input.ref.taskId : null, input.ref?.id ?? null, this.#now(), input.requestId);
+            this.#db.prepare("UPDATE mailboxes SET next_sequence = ? WHERE mailbox_id = ?").run(sequence + 1, mailboxId);
+            return sequence;
+        });
+    }
+    // -- scheduler projections -----------------------------------------------------
+    #getProjection(taskId, kind) {
+        const row = this.#db.prepare("SELECT payload FROM task_projections WHERE task_id = ? AND kind = ?").get(taskId, kind);
+        if (row === undefined || row.payload === null)
+            return null;
+        return this.#parse(row.payload);
+    }
+    #saveProjection(taskId, kind, value) {
+        this.#requireTask(taskId);
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO task_projections (task_id, kind, payload, updated_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(task_id, kind) DO UPDATE SET payload = excluded.payload, updated_at = excluded.updated_at`).run(taskId, kind, this.#json(value), this.#now());
+        });
+    }
+    #clearProjection(taskId, kind) {
+        this.#mutate(() => {
+            this.#db.prepare("UPDATE task_projections SET payload = NULL, updated_at = ? WHERE task_id = ? AND kind = ?")
+                .run(this.#now(), taskId, kind);
+        });
+    }
+    getLeaderFailure(taskId) {
+        return this.#getProjection(taskId, "leader-failure");
+    }
+    saveLeaderFailure(failure) {
+        this.#saveProjection(failure.taskId, "leader-failure", failure);
+    }
+    clearLeaderFailure(taskId) {
+        this.#clearProjection(taskId, "leader-failure");
+    }
+    getOperatorNotification(taskId) {
+        return this.#getProjection(taskId, "operator-notification");
+    }
+    saveOperatorNotification(notification) {
+        this.#saveProjection(notification.taskId, "operator-notification", notification);
+    }
+    clearOperatorNotification(taskId) {
+        this.#clearProjection(taskId, "operator-notification");
+    }
+    // -- pending wakeups (leader-role work-mailbox projection, mirrors taskStore.ts) --
+    getPendingWakeup(taskId) {
+        return pendingWakeupProjection(this.getWorkMailbox({ kind: "role", taskId, roleName: "leader" }));
+    }
+    listPendingWakeups() {
+        return this.listWorkMailboxes()
+            .flatMap((mailbox) => {
+            const wakeup = pendingWakeupProjection(mailbox);
+            return wakeup === null ? [] : [wakeup];
+        })
+            .sort((a, b) => numericCompare(a.taskId, b.taskId));
+    }
+    savePendingWakeup(value) {
+        const target = { kind: "role", taskId: value.taskId, roleName: "leader" };
+        this.transaction((store) => {
+            const existing = store.getWorkMailbox(target);
+            if (existing !== null && existing.pending !== null
+                && value.requestCount <= existing.pending.requestCount) {
+                throw new StorageRecordError(`Pending wakeup is stale: ${value.taskId}`);
+            }
+            const fromSequence = existing?.pending?.fromSequence ?? existing?.nextSequence ?? 1;
+            const toSequence = fromSequence + value.requestCount - 1;
+            store.saveWorkMailbox({
+                schemaVersion: CURRENT_WORK_MAILBOX_SCHEMA_VERSION,
+                target,
+                nextSequence: Math.max(existing?.nextSequence ?? 1, toSequence + 1),
+                processing: existing?.processing ?? null,
+                pending: {
+                    ...existing?.pending,
+                    fromSequence,
+                    toSequence,
+                    reasons: [...value.reasons],
+                    refs: existing?.pending?.refs ?? [],
+                    requestCount: value.requestCount,
+                    firstQueuedAt: value.firstRequestedAt,
+                    lastQueuedAt: value.lastRequestedAt
+                }
+            });
+        });
+    }
+    clearPendingWakeup(taskId) {
+        this.removeWorkMailbox({ kind: "role", taskId, roleName: "leader" });
+    }
+    // -- telemetry (§4.4) -----------------------------------------------------------
+    /**
+     * Upsert one progress row. The PK is (task_id, role_name, run_id, generation,
+     * progress_id): a repeated progress id updates in place, so a high-frequency
+     * `runtime.provider-turn-progress` event is a single-row write that never
+     * rewrites global state or another Task's rows.
+     */
+    upsertTelemetryProgress(entry) {
+        this.#mutate(() => {
+            this.#db.prepare(`INSERT INTO telemetry (task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(task_id, role_name, run_id, generation, progress_id)
+         DO UPDATE SET sequence = excluded.sequence, payload = excluded.payload, received_at = excluded.received_at`).run(entry.taskId, entry.roleName, entry.runId, entry.generation, entry.progressId, entry.sequence ?? null, this.#json(entry.payload), entry.receivedAt);
+        });
+    }
+    listTelemetry(taskId, runId) {
+        const rows = runId === undefined
+            ? this.#db.prepare("SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? ORDER BY received_at").all(taskId)
+            : this.#db.prepare("SELECT task_id, role_name, run_id, generation, progress_id, sequence, payload, received_at FROM telemetry WHERE task_id = ? AND run_id = ? ORDER BY received_at").all(taskId, runId);
+        return rows
+            .map((row) => ({
+            taskId: row.task_id,
+            roleName: row.role_name,
+            runId: row.run_id,
+            generation: row.generation,
+            progressId: row.progress_id,
+            sequence: row.sequence ?? undefined,
+            payload: this.#parse(row.payload),
+            receivedAt: row.received_at
+        }));
+    }
+    countTelemetry(taskId, runId) {
+        const row = runId === undefined
+            ? this.#db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ?").get(taskId)
+            : this.#db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE task_id = ? AND run_id = ?").get(taskId, runId);
+        return row.n;
+    }
+    /**
+     * Bounded retention (§4.4): keep the newest `keep` rows per
+     * (task, role, run, generation) and delete older ones. The DELETE is scoped
+     * by task_id; it never rewrites global rows or other Tasks. Returns the number
+     * of rows deleted. Terminal/semantic events go to `events` and are never pruned.
+     */
+    pruneTelemetry(taskId, roleName, runId, generation, keep = TELEMETRY_KEEP_PER_GENERATION) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare(`DELETE FROM telemetry
+         WHERE task_id = ? AND role_name = ? AND run_id = ? AND generation = ?
+           AND (task_id, role_name, run_id, generation, progress_id) NOT IN (
+             SELECT task_id, role_name, run_id, generation, progress_id
+             FROM telemetry
+             WHERE task_id = ? AND role_name = ? AND run_id = ? AND generation = ?
+             ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+             LIMIT ?
+           )`).run(taskId, roleName, runId, generation, taskId, roleName, runId, generation, keep);
+            return result.changes;
+        });
+    }
+    /**
+     * Hard cap for an active run (§4.4): trim oldest rows across the run beyond
+     * `cap` (default 50k). Returns the number of rows deleted.
+     */
+    capTelemetryRun(taskId, runId, cap = TELEMETRY_RUN_CAP) {
+        return this.#mutate(() => {
+            const result = this.#db.prepare(`DELETE FROM telemetry
+         WHERE task_id = ? AND run_id = ?
+           AND (task_id, role_name, run_id, generation, progress_id) NOT IN (
+             SELECT task_id, role_name, run_id, generation, progress_id
+             FROM telemetry
+             WHERE task_id = ? AND run_id = ?
+             ORDER BY COALESCE(sequence, -1) DESC, received_at DESC, progress_id ASC
+             LIMIT ?
+           )`).run(taskId, runId, taskId, runId, cap);
+            return result.changes;
+        });
+    }
+}
+/**
+ * Open a {@link TaskStore} for the given backend. `file` returns the existing
+ * {@link FileTaskStore}; `sqlite` returns the in-process {@link SqliteTaskStore}.
+ * Backend selection is explicit (design §6); the environment switch lives in
+ * {@link resolveTaskStoreBackend}. The file store is not removed — rollback is
+ * a config flip.
+ */
+export function openTaskStore(home, backend, options) {
+    if (backend === "sqlite") {
+        return new SqliteTaskStore(home, options);
+    }
+    return new FileTaskStore(home);
+}
+/**
+ * Resolve the storage backend from `YUI_STORE_BACKEND` (default `file`,
+ * design §6). Only the exact value `sqlite` selects the SQLite store; any
+ * other value (including unset) keeps the file store.
+ */
+export function resolveTaskStoreBackend(env = process.env) {
+    return env.YUI_STORE_BACKEND?.toLowerCase() === "sqlite" ? "sqlite" : "file";
+}
+/**
+ * Convenience: open the store for the backend resolved from the environment
+ * (`YUI_STORE_BACKEND`, default `file`). CLI/controller entry points that want
+ * the env-driven switch call this instead of {@link openTaskStore} directly.
+ */
+export function openConfiguredTaskStore(home, options, env = process.env) {
+    return openTaskStore(home, resolveTaskStoreBackend(env), options);
+}