@elvisw/dsh-magic-context 0.0.0-stage → 0.14.0

package/lib/core/stores.js

@@ -0,0 +1,1021 @@
+/**
+ * The adapter's own SQLite stores, on `node:sqlite` (no native addons: the
+ * DSH desktop host is an Electron RunAsNode process where ABI-compiled
+ * modules are not portable; node:sqlite is built in on Node >= 22.19).
+ *
+ * Schema discipline mirrors Magic Context's storage layer: a version fence
+ * that fails closed when the database is newer than this build knows, and a
+ * forward-only migration chain. (The Phase 1+ plan of moving these rows into
+ * the shared context.db was superseded 2026-10-13: the corpus became the
+ * plugin's own memories.db, and this store stays the adapter's runtime side.)
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { parseShareCategories, serializeShareCategories } from "./domains.js";
+export const SCHEMA_VERSION = 11;
+export function defaultDataDir() {
+    return join(homedir(), '.local', 'share', 'cortexkit', 'magic-context-dsh-poc');
+}
+const MIGRATIONS = [
+    {
+        version: 1,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE meta(
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        );
+        CREATE TABLE tags(
+          session_id TEXT NOT NULL,
+          target_kind TEXT NOT NULL,
+          target_id TEXT NOT NULL,
+          tag_number INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY(session_id, target_kind, target_id)
+        );
+        CREATE TABLE tag_counters(
+          session_id TEXT PRIMARY KEY,
+          next_tag INTEGER NOT NULL
+        );
+        CREATE TABLE usage_records(
+          session_id TEXT NOT NULL,
+          seq INTEGER NOT NULL,
+          turn INTEGER NOT NULL,
+          step INTEGER NOT NULL,
+          provider TEXT NOT NULL,
+          model TEXT NOT NULL,
+          input_tokens INTEGER,
+          output_tokens INTEGER,
+          cache_read_tokens INTEGER,
+          cache_write_tokens INTEGER,
+          recorded_at INTEGER NOT NULL,
+          PRIMARY KEY(session_id, seq)
+        );
+      `);
+        },
+    },
+    {
+        // v2: the agent-facing drop queue (ctx_reduce marks, the execute band
+        // lands) — Magic Context's pending_ops vocabulary on the DSH adapter.
+        version: 2,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE pending_drops(
+          session_id TEXT NOT NULL,
+          tag_number INTEGER NOT NULL,
+          queued_at INTEGER NOT NULL,
+          landed_event_seq INTEGER,
+          PRIMARY KEY(session_id, tag_number)
+        );
+      `);
+        },
+    },
+    {
+        // v3: the historian's compartments and the m[0]/m[1] baseline identity.
+        // A compartment is a durable digest of a covered surface span; it lands
+        // as a `[compacted §C<n>§]` placeholder on the next execute band, and its
+        // text is injected through the composed baseline node.
+        version: 3,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE compartments(
+          session_id TEXT NOT NULL,
+          compartment_id INTEGER NOT NULL,
+          created_at INTEGER NOT NULL,
+          covered_start_seq INTEGER NOT NULL,
+          covered_end_seq INTEGER NOT NULL,
+          covered_seqs TEXT NOT NULL,
+          covered_tokens INTEGER NOT NULL,
+          importance INTEGER NOT NULL,
+          tier_p1 TEXT NOT NULL,
+          tier_p2 TEXT NOT NULL,
+          tier_p3 TEXT NOT NULL,
+          tier_p4 TEXT NOT NULL,
+          facts TEXT NOT NULL,
+          events TEXT NOT NULL,
+          baseline_epoch INTEGER NOT NULL,
+          landed_event_seq INTEGER,
+          PRIMARY KEY(session_id, compartment_id)
+        );
+        CREATE TABLE compartment_counters(
+          session_id TEXT PRIMARY KEY,
+          next_compartment INTEGER NOT NULL
+        );
+        CREATE TABLE baseline_state(
+          session_id TEXT PRIMARY KEY,
+          epoch INTEGER NOT NULL,
+          node_seq INTEGER,
+          provider TEXT,
+          model TEXT,
+          frozen_at INTEGER NOT NULL,
+          memories_digest TEXT,
+          updated_at INTEGER NOT NULL
+        );
+      `);
+        },
+    },
+    {
+        // v4: the activity journal — the validation-period audit trail. The
+        // harness logger is not persisted by the Desktop app, so decisions and
+        // outcomes get their own append-only table (see core/journal.ts).
+        version: 4,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE journal(
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          at INTEGER NOT NULL,
+          level TEXT NOT NULL,
+          kind TEXT NOT NULL,
+          session_id TEXT,
+          summary TEXT NOT NULL,
+          data TEXT
+        );
+        CREATE INDEX journal_at ON journal(at);
+        CREATE INDEX journal_kind ON journal(kind);
+        CREATE INDEX journal_session ON journal(session_id, at);
+      `);
+        },
+    },
+    {
+        // v5: the additive-memory watermark (Magic Context's `maxMemoryId`), so a
+        // newly written memory surfaces in m[1] `<new-memories>` instead of
+        // changing the recall digest and forcing a HARD rebuild of m[0].
+        version: 5,
+        up: (db) => {
+            db.exec('ALTER TABLE baseline_state ADD COLUMN max_memory_id INTEGER');
+        },
+    },
+    {
+        // v6: the m[1] *mutation* delta lane. `max_memory_mutation_id` is Magic
+        // Context's `cached_m0_max_memory_mutation_id` (watermark into the shared
+        // `memory_mutation_log`); `project_epoch_fingerprint` is the
+        // `project_state.project_memory_epoch` identity the baseline was built
+        // against. Both are additive columns: an existing v5 database is upgraded
+        // in place, and rows written before this version simply have NULL there
+        // (the pass folds them once, see management-pass.ts).
+        version: 6,
+        up: (db) => {
+            db.exec(`
+        ALTER TABLE baseline_state ADD COLUMN max_memory_mutation_id INTEGER;
+        ALTER TABLE baseline_state ADD COLUMN project_epoch_fingerprint TEXT;
+      `);
+        },
+    },
+    {
+        // v7: the fusion additions (borrowed from mon3stera/dsh-magic-context
+        // @0.1.0, audited 2026-10-09; see docs/ for the fusion plan).
+        //  - compartments.landed_reason: a TERMINAL non-publish outcome.
+        //    `not-shrinkable`: the publish guard proved the digest does not pay
+        //    for its own baseline render. `superseded-entrants`: substantive
+        //    nodes entered the positional range after drafting. A reasoned row
+        //    is never published and never retried (listUnlandedCompartments
+        //    excludes it), ending the old rejected-draft-retried-forever shape.
+        //  - compartments.superseded: retires a drifted draft AND RELEASES its
+        //    covered-seq claims, so the next historian run re-digests the whole
+        //    span (originals plus the entrants) instead of leaking it.
+        //    NOTE (2026-10-16): the publish guard that called these two was
+        //    RETIRED (0 hits in its whole window); the column and both store APIs
+        //    remain for schema-v7 compatibility, historical rows and tests.
+        //  - memory_stats: the S(t) scoring sidecar. Hits/injections for rows of
+        //    the SHARED memory store are tracked HERE, adapter-local — the
+        //    shared store is never written for scoring (writer-contract
+        //    discipline: only the bridge's contract actions touch it).
+        version: 7,
+        up: (db) => {
+            db.exec(`
+        ALTER TABLE compartments ADD COLUMN landed_reason TEXT;
+        ALTER TABLE compartments ADD COLUMN superseded INTEGER NOT NULL DEFAULT 0;
+        CREATE TABLE memory_stats(
+          project_identity TEXT NOT NULL,
+          memory_id INTEGER NOT NULL,
+          hits INTEGER NOT NULL DEFAULT 0,
+          last_hit_at INTEGER,
+          injections INTEGER NOT NULL DEFAULT 0,
+          last_injected_at INTEGER,
+          local_archived INTEGER NOT NULL DEFAULT 0,
+          updated_at INTEGER NOT NULL,
+          PRIMARY KEY(project_identity, memory_id)
+        );
+        CREATE INDEX memory_stats_archived ON memory_stats(project_identity, local_archived);
+      `);
+        },
+    },
+    {
+        // v8: the global-domain substrate (docs/dsh-plugin-execution-plan-2026-10-09.md,
+        // WP1). Magic Context, its dashboard and every other host are being removed,
+        // so the adapter becomes the sole owner of: which global domains exist, which
+        // project identities activate them, the cross-project candidate pool for
+        // org/machine, and the confirmation queue that directive-shaped profile
+        // candidates must pass through. All of it lives HERE (the adapter's own
+        // store) — the own corpus (memories.db) deliberately carries none of it.
+        //
+        //  - domains: one row per global domain. `cap` is DERIVED from a token
+        //    target by the caller, so the admission limit and the budget cannot
+        //    drift apart.
+        //  - domain_members: the activation rule (the only sharing membership
+        //    since the 2026-10-13 corpus cutover).
+        //  - global_candidates / global_candidate_observations: the cross-project
+        //    recurrence gate — a fact promoted to a global domain must have been
+        //    observed independently by at least two DIFFERENT project identities.
+        //  - profile_confirmations: the human gate for directive-shaped content.
+        //    Unconfirmed entries never enter the injected pool.
+        //  - baseline_state.profile_watermark / profile_m0_digest: the additive
+        //    watermark and the m[0] content digest for the profile, so a new
+        //    profile row rides the m[1] delta while a rewritten or retired one
+        //    forces a HARD rebuild (deliberately unlike Magic Context, which kept
+        //    serving a stale m[0] profile block).
+        version: 8,
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE domains(
+          domain_id TEXT PRIMARY KEY,
+          kind TEXT NOT NULL CHECK(kind IN ('user','org','machine')),
+          enabled INTEGER NOT NULL DEFAULT 0,
+          budget_tokens INTEGER NOT NULL,
+          cap INTEGER NOT NULL,
+          share_categories TEXT NOT NULL DEFAULT '["CONSTRAINTS"]',
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE TABLE domain_members(
+          domain_id TEXT NOT NULL REFERENCES domains(domain_id) ON DELETE CASCADE,
+          identity TEXT NOT NULL,
+          added_at INTEGER NOT NULL,
+          PRIMARY KEY(domain_id, identity)
+        );
+        CREATE INDEX domain_members_identity ON domain_members(identity);
+        CREATE TABLE global_candidates(
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          domain_id TEXT NOT NULL,
+          content TEXT NOT NULL,
+          normalized_hash TEXT NOT NULL,
+          first_identity TEXT NOT NULL,
+          session_id TEXT,
+          compartment_start INTEGER,
+          compartment_end INTEGER,
+          distinct_identities INTEGER NOT NULL DEFAULT 1,
+          observation_count INTEGER NOT NULL DEFAULT 1,
+          state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','approved','rejected','expired')),
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+        CREATE UNIQUE INDEX global_candidates_domain_hash ON global_candidates(domain_id, normalized_hash);
+        CREATE INDEX global_candidates_state ON global_candidates(domain_id, state);
+        CREATE TABLE global_candidate_observations(
+          candidate_id INTEGER NOT NULL REFERENCES global_candidates(id) ON DELETE CASCADE,
+          identity TEXT NOT NULL,
+          session_id TEXT NOT NULL,
+          compartment_start INTEGER,
+          compartment_end INTEGER,
+          observations INTEGER NOT NULL DEFAULT 1,
+          first_seen_at INTEGER NOT NULL,
+          last_seen_at INTEGER NOT NULL,
+          PRIMARY KEY(candidate_id, identity, session_id)
+        );
+        CREATE INDEX global_observations_identity ON global_candidate_observations(identity);
+        CREATE TABLE profile_confirmations(
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          contract_candidate_id INTEGER NOT NULL,
+          question TEXT NOT NULL,
+          content TEXT NOT NULL,
+          state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','approved','rejected')),
+          created_at INTEGER NOT NULL,
+          decided_at INTEGER
+        );
+        CREATE INDEX profile_confirmations_state ON profile_confirmations(state);
+        ALTER TABLE baseline_state ADD COLUMN profile_watermark INTEGER;
+        ALTER TABLE baseline_state ADD COLUMN profile_m0_digest TEXT;
+      `);
+        },
+    },
+    {
+        // v9: what a global candidate will be published AS.
+        //
+        // v8 stored a candidate's content and hash but not its category, because the
+        // only intended source was the historian's recurrence scan. Naming the
+        // category up front matters for two reasons: the category decides whether
+        // the row will be visible at all once published (per-domain allowlist), and
+        // `source_memory_id` keeps the provenance so a reviewer can see which
+        // project memory a candidate came from. Both are nullable: a candidate
+        // created by the recurrence scan has no single source memory, and a human
+        // promotion always has one.
+        version: 9,
+        up: (db) => {
+            db.exec(`
+        ALTER TABLE global_candidates ADD COLUMN category TEXT;
+        ALTER TABLE global_candidates ADD COLUMN source_memory_id INTEGER;
+      `);
+        },
+    },
+    {
+        // v10: the LLM domain classification that routes an auto-staged candidate
+        // into machine or org — and, when classification fails, leaves the memory
+        // at PROJECT level (nothing staged). `suggested_domain` and
+        // `suggestion_reason` ride the candidate row so the review card can show
+        // the classifier's verdict and the operator can overrule it (the card's
+        // "publish to another domain" option). Both nullable: a human promotion or
+        // a pre-v10 auto-stage has no suggestion.
+        version: 10,
+        up: (db) => {
+            db.exec(`
+        ALTER TABLE global_candidates ADD COLUMN suggested_domain TEXT;
+        ALTER TABLE global_candidates ADD COLUMN suggestion_reason TEXT;
+      `);
+        },
+    },
+    {
+        // v11: the manual `/ctx-flush` marker. It is deliberately on the queue
+        // row, not on a tag: only an already-pending drop can be forced, and the
+        // marker must survive a process restart until the next preStep.
+        version: 11,
+        up: (db) => {
+            db.exec(`
+        ALTER TABLE pending_drops ADD COLUMN flush_requested INTEGER NOT NULL DEFAULT 0;
+      `);
+        },
+    },
+];
+export class StoreAheadOfAdapterError extends Error {
+    // Declared explicitly rather than as constructor parameter properties: the
+    // scripts in scripts/ load this module with plain Node (type stripping), and
+    // parameter properties are not erasable syntax. Keeping the class erasable
+    // lets migration tooling reuse the real store instead of re-implementing its
+    // SQL — one source of truth for the adapter schema.
+    dbVersion;
+    adapterVersion;
+    constructor(dbVersion, adapterVersion) {
+        super(`magic-context dsh adapter: store schema v${dbVersion} is newer than this build supports (v${adapterVersion}); `
+            + 'update the adapter (or roll it back together with its database) before continuing');
+        this.name = 'StoreAheadOfAdapterError';
+        this.dbVersion = dbVersion;
+        this.adapterVersion = adapterVersion;
+    }
+}
+function targetKey(target) {
+    return target.kind === 'user-message'
+        ? { kind: 'user-message', id: target.messageId }
+        : { kind: 'tool-result', id: target.callId };
+}
+export function openStores(dataDir) {
+    const dbPath = join(dataDir, 'dsh-magic-context.db');
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA journal_mode = WAL');
+    let closed = false;
+    let persisted = 0;
+    const hasMetaTable = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'meta'").get();
+    if (hasMetaTable !== undefined) {
+        const row = db.prepare('SELECT value FROM meta WHERE key = ?').get('schema_version');
+        persisted = row === undefined ? 0 : Number(row.value);
+        if (!Number.isInteger(persisted) || persisted < 0) {
+            db.close();
+            throw new Error(`magic-context dsh adapter: invalid persisted schema version ${String(row?.value)}`);
+        }
+    }
+    if (persisted > SCHEMA_VERSION) {
+        db.close();
+        throw new StoreAheadOfAdapterError(persisted, SCHEMA_VERSION);
+    }
+    for (const migration of MIGRATIONS) {
+        if (migration.version <= persisted)
+            continue;
+        db.exec('BEGIN');
+        try {
+            migration.up(db);
+            db.prepare('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+                .run('schema_version', String(migration.version));
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            db.close();
+            throw error;
+        }
+    }
+    const allocateTag = (sessionId, target, now) => {
+        const { kind, id } = targetKey(target);
+        const existing = db
+            .prepare('SELECT tag_number FROM tags WHERE session_id = ? AND target_kind = ? AND target_id = ?')
+            .get(sessionId, kind, id);
+        if (existing !== undefined)
+            return existing.tag_number;
+        const insert = db.prepare('INSERT INTO tags(session_id, target_kind, target_id, tag_number, created_at) VALUES(?, ?, ?, ?, ?)');
+        const bump = db.prepare('INSERT INTO tag_counters(session_id, next_tag) VALUES(?, 2) ON CONFLICT(session_id) DO UPDATE SET next_tag = next_tag + 1 RETURNING next_tag - 1');
+        db.exec('BEGIN');
+        try {
+            const allocated = bump.get(sessionId);
+            const tagNumber = allocated === undefined ? 1 : allocated['next_tag - 1'];
+            insert.run(sessionId, kind, id, tagNumber, now);
+            db.exec('COMMIT');
+            return tagNumber;
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    const getTag = (sessionId, target) => {
+        const { kind, id } = targetKey(target);
+        const row = db
+            .prepare('SELECT tag_number FROM tags WHERE session_id = ? AND target_kind = ? AND target_id = ?')
+            .get(sessionId, kind, id);
+        return row?.tag_number;
+    };
+    const usageColumns = 'session_id, seq, turn, step, provider, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, recorded_at';
+    const recordUsage = (record) => {
+        db.exec('BEGIN');
+        try {
+            db.prepare(`INSERT OR IGNORE INTO usage_records(${usageColumns}) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(record.sessionId, record.seq, record.turn, record.step, record.provider, record.model, record.inputTokens ?? null, record.outputTokens ?? null, record.cacheReadTokens ?? null, record.cacheWriteTokens ?? null, record.recordedAt);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    const listUsage = (sessionId) => db.prepare(`SELECT * FROM usage_records WHERE session_id = ? ORDER BY seq`).all(sessionId).map(row => ({
+        sessionId: row.session_id,
+        seq: row.seq,
+        turn: row.turn,
+        step: row.step,
+        provider: row.provider,
+        model: row.model,
+        inputTokens: row.input_tokens ?? undefined,
+        outputTokens: row.output_tokens ?? undefined,
+        cacheReadTokens: row.cache_read_tokens ?? undefined,
+        cacheWriteTokens: row.cache_write_tokens ?? undefined,
+        recordedAt: row.recorded_at,
+    }));
+    const listTags = (sessionId) => db.prepare('SELECT * FROM tags WHERE session_id = ? ORDER BY tag_number').all(sessionId).map(row => ({
+        sessionId: row.session_id,
+        tagNumber: row.tag_number,
+        target: row.target_kind === 'user-message'
+            ? { kind: 'user-message', messageId: row.target_id }
+            : { kind: 'tool-result', callId: row.target_id },
+        createdAt: row.created_at,
+    }));
+    const latestUsage = (sessionId) => {
+        const row = db.prepare('SELECT * FROM usage_records WHERE session_id = ? ORDER BY seq DESC LIMIT 1').get(sessionId);
+        if (row === undefined)
+            return undefined;
+        return {
+            sessionId: row.session_id,
+            seq: row.seq,
+            turn: row.turn,
+            step: row.step,
+            provider: row.provider,
+            model: row.model,
+            inputTokens: row.input_tokens ?? undefined,
+            outputTokens: row.output_tokens ?? undefined,
+            cacheReadTokens: row.cache_read_tokens ?? undefined,
+            cacheWriteTokens: row.cache_write_tokens ?? undefined,
+            recordedAt: row.recorded_at,
+        };
+    };
+    /**
+     * Newest history change (compartment stored / baseline re-frozen) for the
+     * session. Both stamps are metadata about the SAME injected surface, so a
+     * reading older than either one describes bytes the provider will not see
+     * again.
+     *
+     * Deliberately not extended to drop landings: `pending_drops` carries no
+     * landing timestamp, and a drop-only mutation is already followed by the same
+     * pass's baseline refresh in every path that refreshes one. The compaction
+     * case — the one that loses content — is covered.
+     */
+    const latestHistoryChangeAt = (sessionId) => {
+        try {
+            const row = db.prepare('SELECT MAX(t) AS t FROM ('
+                + 'SELECT MAX(created_at) AS t FROM compartments WHERE session_id = ?'
+                + ' UNION ALL SELECT MAX(updated_at) AS t FROM baseline_state WHERE session_id = ?)').get(sessionId, sessionId);
+            const value = row?.t;
+            return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+        }
+        catch {
+            // A freshness probe must never fail the turn that asked for it.
+            return undefined;
+        }
+    };
+    const queueDrop = (sessionId, tagNumber, now) => {
+        db.prepare('INSERT INTO pending_drops(session_id, tag_number, queued_at) VALUES(?, ?, ?) '
+            + 'ON CONFLICT(session_id, tag_number) DO UPDATE SET queued_at = excluded.queued_at, flush_requested = 0 '
+            + 'WHERE landed_event_seq IS NOT NULL').run(sessionId, tagNumber, now);
+    };
+    const listPendingDrops = (sessionId) => db.prepare('SELECT tag_number FROM pending_drops WHERE session_id = ? AND landed_event_seq IS NULL ORDER BY queued_at, tag_number').all(sessionId).map(row => row.tag_number);
+    const requestFlush = (sessionId) => {
+        const result = db.prepare('UPDATE pending_drops SET flush_requested = 1 '
+            + 'WHERE session_id = ? AND landed_event_seq IS NULL AND flush_requested = 0').run(sessionId);
+        return result.changes ?? 0;
+    };
+    const listFlushRequestedDrops = (sessionId) => db.prepare('SELECT tag_number FROM pending_drops WHERE session_id = ? AND landed_event_seq IS NULL AND flush_requested = 1 '
+        + 'ORDER BY queued_at, tag_number').all(sessionId).map(row => row.tag_number);
+    const clearFlushRequests = (sessionId, tags) => {
+        if (tags.length === 0)
+            return;
+        const clear = db.prepare('UPDATE pending_drops SET flush_requested = 0 WHERE session_id = ? AND tag_number = ?');
+        db.exec('BEGIN');
+        try {
+            for (const tag of tags)
+                clear.run(sessionId, tag);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    const markDropLanded = (sessionId, tagNumber, landedEventSeq) => {
+        db.prepare('UPDATE pending_drops SET landed_event_seq = ?, flush_requested = 0 WHERE session_id = ? AND tag_number = ?').run(landedEventSeq, sessionId, tagNumber);
+    };
+    const dropState = (sessionId, tagNumber) => {
+        const row = db.prepare('SELECT landed_event_seq FROM pending_drops WHERE session_id = ? AND tag_number = ?').get(sessionId, tagNumber);
+        if (row === undefined)
+            return 'none';
+        return row.landed_event_seq === null ? 'pending' : 'landed';
+    };
+    const tagSessions = (tagNumber) => db.prepare('SELECT DISTINCT session_id FROM tags WHERE tag_number = ? ORDER BY session_id').all(tagNumber).map(row => row.session_id);
+    const toCompartment = (row) => ({
+        sessionId: row.session_id,
+        compartmentId: row.compartment_id,
+        createdAt: row.created_at,
+        coveredStartSeq: row.covered_start_seq,
+        coveredEndSeq: row.covered_end_seq,
+        coveredSeqs: JSON.parse(row.covered_seqs),
+        coveredTokens: row.covered_tokens,
+        importance: row.importance,
+        tiers: { p1: row.tier_p1, p2: row.tier_p2, p3: row.tier_p3, p4: row.tier_p4 },
+        facts: JSON.parse(row.facts),
+        events: JSON.parse(row.events),
+        baselineEpoch: row.baseline_epoch,
+        ...row.landed_event_seq === null ? {} : { landedEventSeq: row.landed_event_seq },
+        ...row.landed_reason === null ? {} : { landedReason: row.landed_reason },
+    });
+    const allocateCompartment = (sessionId, draft, covered, baselineEpoch, now) => {
+        db.exec('BEGIN');
+        try {
+            const bumped = db.prepare('INSERT INTO compartment_counters(session_id, next_compartment) VALUES(?, 2) '
+                + 'ON CONFLICT(session_id) DO UPDATE SET next_compartment = next_compartment + 1 '
+                + 'RETURNING next_compartment - 1').get(sessionId);
+            const compartmentId = bumped === undefined ? 1 : bumped['next_compartment - 1'];
+            db.prepare('INSERT INTO compartments(session_id, compartment_id, created_at, covered_start_seq, covered_end_seq, '
+                + 'covered_seqs, covered_tokens, importance, tier_p1, tier_p2, tier_p3, tier_p4, facts, events, baseline_epoch) '
+                + 'VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(sessionId, compartmentId, now, covered.startSeq, covered.endSeq, JSON.stringify([...covered.seqs]), covered.tokens, draft.importance, draft.tiers.p1, draft.tiers.p2, draft.tiers.p3, draft.tiers.p4, JSON.stringify([...draft.facts]), JSON.stringify([...draft.events]), baselineEpoch);
+            db.exec('COMMIT');
+            return {
+                sessionId,
+                compartmentId,
+                createdAt: now,
+                coveredStartSeq: covered.startSeq,
+                coveredEndSeq: covered.endSeq,
+                coveredSeqs: [...covered.seqs],
+                coveredTokens: covered.tokens,
+                importance: draft.importance,
+                tiers: draft.tiers,
+                facts: [...draft.facts],
+                events: [...draft.events],
+                baselineEpoch,
+            };
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    const listCompartments = (sessionId) => db.prepare('SELECT * FROM compartments WHERE session_id = ? ORDER BY compartment_id')
+        .all(sessionId).map(toCompartment);
+    const listUnlandedCompartments = (sessionId) => db.prepare('SELECT * FROM compartments WHERE session_id = ? AND landed_event_seq IS NULL '
+        + 'AND superseded = 0 AND landed_reason IS NULL ORDER BY compartment_id')
+        .all(sessionId).map(toCompartment);
+    const markCompartmentLanded = (sessionId, compartmentId, landedEventSeq) => {
+        db.prepare('UPDATE compartments SET landed_event_seq = ? WHERE session_id = ? AND compartment_id = ?').run(landedEventSeq, sessionId, compartmentId);
+    };
+    const markCompartmentRejected = (sessionId, compartmentId, reason) => {
+        db.prepare('UPDATE compartments SET landed_reason = ? WHERE session_id = ? AND compartment_id = ? '
+            + 'AND landed_event_seq IS NULL').run(reason, sessionId, compartmentId);
+    };
+    const supersedeCompartment = (sessionId, compartmentId, reason) => {
+        db.prepare('UPDATE compartments SET superseded = 1, landed_reason = ? WHERE session_id = ? AND compartment_id = ?').run(reason, sessionId, compartmentId);
+    };
+    const replaceCompartmentDraft = (sessionId, compartmentId, draft) => {
+        db.prepare('UPDATE compartments SET importance = ?, tier_p1 = ?, tier_p2 = ?, tier_p3 = ?, tier_p4 = ?, facts = ?, events = ? '
+            + 'WHERE session_id = ? AND compartment_id = ?').run(draft.importance, draft.tiers.p1, draft.tiers.p2, draft.tiers.p3, draft.tiers.p4, JSON.stringify([...draft.facts]), JSON.stringify([...draft.events]), sessionId, compartmentId);
+    };
+    const coveredSeqs = (sessionId) => {
+        // Superseded drafts release their claims: their span (originals plus the
+        // nodes that drifted in) goes back into the historian's eligibility pool.
+        const rows = db.prepare('SELECT covered_seqs FROM compartments WHERE session_id = ? AND superseded = 0')
+            .all(sessionId);
+        const seqs = new Set();
+        for (const row of rows) {
+            for (const seq of JSON.parse(row.covered_seqs))
+                seqs.add(seq);
+        }
+        return seqs;
+    };
+    const baselineState = (sessionId) => {
+        const row = db.prepare('SELECT * FROM baseline_state WHERE session_id = ?').get(sessionId);
+        if (row === undefined)
+            return undefined;
+        return {
+            sessionId: row.session_id,
+            epoch: row.epoch,
+            ...row.node_seq === null ? {} : { nodeSeq: row.node_seq },
+            ...row.provider === null ? {} : { provider: row.provider },
+            ...row.model === null ? {} : { model: row.model },
+            frozenAt: row.frozen_at,
+            ...row.memories_digest === null ? {} : { memoriesDigest: row.memories_digest },
+            ...row.max_memory_id === null ? {} : { maxMemoryId: row.max_memory_id },
+            ...row.max_memory_mutation_id === null ? {} : { maxMemoryMutationId: row.max_memory_mutation_id },
+            ...row.project_epoch_fingerprint === null ? {} : { projectEpochFingerprint: row.project_epoch_fingerprint },
+            ...row.profile_watermark === null ? {} : { profileWatermark: row.profile_watermark },
+            ...row.profile_m0_digest === null ? {} : { profileM0Digest: row.profile_m0_digest },
+            updatedAt: row.updated_at,
+        };
+    };
+    const saveBaselineState = (state) => {
+        db.prepare('INSERT INTO baseline_state(session_id, epoch, node_seq, provider, model, frozen_at, memories_digest, '
+            + 'max_memory_id, max_memory_mutation_id, project_epoch_fingerprint, profile_watermark, profile_m0_digest, updated_at) '
+            + 'VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) '
+            + 'ON CONFLICT(session_id) DO UPDATE SET epoch = excluded.epoch, node_seq = excluded.node_seq, '
+            + 'provider = excluded.provider, model = excluded.model, frozen_at = excluded.frozen_at, '
+            + 'memories_digest = excluded.memories_digest, max_memory_id = excluded.max_memory_id, '
+            + 'max_memory_mutation_id = excluded.max_memory_mutation_id, '
+            + 'project_epoch_fingerprint = excluded.project_epoch_fingerprint, '
+            + 'profile_watermark = excluded.profile_watermark, '
+            + 'profile_m0_digest = excluded.profile_m0_digest, '
+            + 'updated_at = excluded.updated_at').run(state.sessionId, state.epoch, state.nodeSeq ?? null, state.provider ?? null, state.model ?? null, state.frozenAt, state.memoriesDigest ?? null, state.maxMemoryId ?? null, state.maxMemoryMutationId ?? null, state.projectEpochFingerprint ?? null, state.profileWatermark ?? null, state.profileM0Digest ?? null, state.updatedAt);
+    };
+    const toDomain = (row) => ({
+        domainId: row.domain_id,
+        kind: row.kind,
+        enabled: row.enabled !== 0,
+        budgetTokens: row.budget_tokens,
+        cap: row.cap,
+        shareCategories: parseShareCategories(row.share_categories),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    });
+    const upsertDomain = (domain, now) => {
+        // serializeShareCategories rejects an unknown category here, at the write,
+        // rather than letting a row become permanently invisible later.
+        const shareCategories = serializeShareCategories(domain.shareCategories);
+        db.prepare('INSERT INTO domains(domain_id, kind, enabled, budget_tokens, cap, share_categories, created_at, updated_at) '
+            + 'VALUES(?, ?, ?, ?, ?, ?, ?, ?) '
+            + 'ON CONFLICT(domain_id) DO UPDATE SET kind = excluded.kind, enabled = excluded.enabled, '
+            + 'budget_tokens = excluded.budget_tokens, cap = excluded.cap, '
+            + 'share_categories = excluded.share_categories, updated_at = excluded.updated_at').run(domain.domainId, domain.kind, domain.enabled ? 1 : 0, domain.budgetTokens, domain.cap, shareCategories, now, now);
+    };
+    const listDomains = () => db.prepare('SELECT * FROM domains ORDER BY kind, domain_id').all().map(toDomain);
+    const getDomain = (domainId) => {
+        const row = db.prepare('SELECT * FROM domains WHERE domain_id = ?').get(domainId);
+        return row === undefined ? undefined : toDomain(row);
+    };
+    const setDomainEnabled = (domainId, enabled, now) => {
+        db.prepare('UPDATE domains SET enabled = ?, updated_at = ? WHERE domain_id = ?').run(enabled ? 1 : 0, now, domainId);
+    };
+    const addDomainMember = (domainId, identity, now) => {
+        db.prepare('INSERT INTO domain_members(domain_id, identity, added_at) VALUES(?, ?, ?) '
+            + 'ON CONFLICT(domain_id, identity) DO NOTHING').run(domainId, identity, now);
+    };
+    const removeDomainMember = (domainId, identity) => {
+        db.prepare('DELETE FROM domain_members WHERE domain_id = ? AND identity = ?').run(domainId, identity);
+    };
+    const listDomainMembers = (domainId) => {
+        const rows = (domainId === undefined
+            ? db.prepare('SELECT * FROM domain_members ORDER BY domain_id, identity').all()
+            : db.prepare('SELECT * FROM domain_members WHERE domain_id = ? ORDER BY identity').all(domainId));
+        return rows.map(row => ({ domainId: row.domain_id, identity: row.identity, addedAt: row.added_at }));
+    };
+    const activeDomainIdentities = (identity) => {
+        const rows = db.prepare('SELECT d.domain_id AS domain_id, d.kind AS kind FROM domain_members m '
+            + 'JOIN domains d ON d.domain_id = m.domain_id '
+            + 'WHERE m.identity = ? AND d.enabled = 1 ORDER BY d.kind, d.domain_id').all(identity);
+        return rows.map(row => ({ domainId: row.domain_id, kind: row.kind, identity: row.domain_id }));
+    };
+    const toGlobalCandidate = (row) => ({
+        id: row.id,
+        domainId: row.domain_id,
+        content: row.content,
+        normalizedHash: row.normalized_hash,
+        firstIdentity: row.first_identity,
+        ...row.session_id === null ? {} : { sessionId: row.session_id },
+        ...row.compartment_start === null ? {} : { compartmentStart: row.compartment_start },
+        ...row.compartment_end === null ? {} : { compartmentEnd: row.compartment_end },
+        distinctIdentities: row.distinct_identities,
+        observationCount: row.observation_count,
+        ...row.category === null ? {} : { category: row.category },
+        ...row.source_memory_id === null ? {} : { sourceMemoryId: row.source_memory_id },
+        ...row.suggested_domain === null ? {} : { suggestedDomain: row.suggested_domain },
+        ...row.suggestion_reason === null ? {} : { suggestionReason: row.suggestion_reason },
+        state: row.state,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    });
+    const getGlobalCandidateByHash = (domainId, normalizedHash) => {
+        const row = db
+            .prepare('SELECT * FROM global_candidates WHERE domain_id = ? AND normalized_hash = ?')
+            .get(domainId, normalizedHash);
+        return row === undefined ? undefined : toGlobalCandidate(row);
+    };
+    /** Recompute the recurrence weight from the observation rows (never from a counter the caller passes). */
+    const refreshCandidateWeight = (candidateId, now) => {
+        db.prepare('UPDATE global_candidates SET '
+            + 'distinct_identities = (SELECT COUNT(*) FROM global_candidate_observations WHERE candidate_id = ?), '
+            + 'observation_count = (SELECT COALESCE(SUM(observations), 0) FROM global_candidate_observations WHERE candidate_id = ?), '
+            + 'updated_at = ? WHERE id = ?').run(candidateId, candidateId, now, candidateId);
+    };
+    const upsertGlobalCandidate = (candidate, now) => {
+        db.prepare('INSERT INTO global_candidates(domain_id, content, normalized_hash, first_identity, session_id, '
+            + 'compartment_start, compartment_end, distinct_identities, observation_count, category, source_memory_id, '
+            + 'suggested_domain, suggestion_reason, '
+            + "state, created_at, updated_at) VALUES(?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?, ?, 'pending', ?, ?) "
+            + 'ON CONFLICT(domain_id, normalized_hash) DO UPDATE SET content = excluded.content, '
+            // A later sighting that does not carry the metadata must not erase it.
+            + 'category = COALESCE(excluded.category, global_candidates.category), '
+            + 'source_memory_id = COALESCE(excluded.source_memory_id, global_candidates.source_memory_id), '
+            + 'suggested_domain = COALESCE(excluded.suggested_domain, global_candidates.suggested_domain), '
+            + 'suggestion_reason = COALESCE(excluded.suggestion_reason, global_candidates.suggestion_reason), '
+            + 'updated_at = excluded.updated_at, '
+            + "state = CASE WHEN global_candidates.state = 'expired' THEN 'pending' ELSE global_candidates.state END").run(candidate.domainId, candidate.content, candidate.normalizedHash, candidate.firstIdentity, candidate.sessionId ?? null, candidate.compartmentStart ?? null, candidate.compartmentEnd ?? null, candidate.category ?? null, candidate.sourceMemoryId ?? null, candidate.suggestedDomain ?? null, candidate.suggestionReason ?? null, now, now);
+        const row = getGlobalCandidateByHash(candidate.domainId, candidate.normalizedHash);
+        if (row === undefined)
+            throw new Error('magic-context dsh adapter: global candidate upsert did not land');
+        return row;
+    };
+    const getGlobalCandidate = (id) => {
+        const row = db.prepare('SELECT * FROM global_candidates WHERE id = ?').get(id);
+        return row === undefined ? undefined : toGlobalCandidate(row);
+    };
+    const listGlobalCandidates = (filter) => {
+        const where = [];
+        const params = [];
+        if (filter?.domainId !== undefined) {
+            where.push('domain_id = ?');
+            params.push(filter.domainId);
+        }
+        if (filter?.state !== undefined) {
+            where.push('state = ?');
+            params.push(filter.state);
+        }
+        const clause = where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`;
+        const rows = db
+            .prepare(`SELECT * FROM global_candidates${clause} ORDER BY updated_at DESC, id DESC`)
+            .all(...params);
+        return rows.map(toGlobalCandidate);
+    };
+    const setGlobalCandidateState = (id, state, now) => {
+        db.prepare('UPDATE global_candidates SET state = ?, updated_at = ? WHERE id = ?').run(state, now, id);
+    };
+    const recordCandidateObservation = (observation, now) => {
+        db.exec('BEGIN');
+        try {
+            db.prepare('INSERT INTO global_candidate_observations(candidate_id, identity, session_id, compartment_start, '
+                + 'compartment_end, observations, first_seen_at, last_seen_at) VALUES(?, ?, ?, ?, ?, 1, ?, ?) '
+                + 'ON CONFLICT(candidate_id, identity, session_id) DO UPDATE SET observations = observations + 1, '
+                + 'last_seen_at = excluded.last_seen_at').run(observation.candidateId, observation.identity, observation.sessionId, observation.compartmentStart ?? null, observation.compartmentEnd ?? null, now, now);
+            refreshCandidateWeight(observation.candidateId, now);
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    };
+    const listCandidateObservations = (candidateId) => db.prepare('SELECT * FROM global_candidate_observations WHERE candidate_id = ? ORDER BY identity, session_id').all(candidateId).map(row => ({
+        candidateId: row.candidate_id,
+        identity: row.identity,
+        sessionId: row.session_id,
+        ...row.compartment_start === null ? {} : { compartmentStart: row.compartment_start },
+        ...row.compartment_end === null ? {} : { compartmentEnd: row.compartment_end },
+        observations: row.observations,
+        firstSeenAt: row.first_seen_at,
+        lastSeenAt: row.last_seen_at,
+    }));
+    const toProfileConfirmation = (row) => ({
+        id: row.id,
+        contractCandidateId: row.contract_candidate_id,
+        question: row.question,
+        content: row.content,
+        state: row.state,
+        createdAt: row.created_at,
+        ...row.decided_at === null ? {} : { decidedAt: row.decided_at },
+    });
+    const enqueueProfileConfirmation = (input, now) => {
+        // Idempotent per pending candidate: a retried historian pass must not
+        // produce a second question for the same observation.
+        const existing = db.prepare("SELECT * FROM profile_confirmations WHERE contract_candidate_id = ? AND state = 'pending'").get(input.contractCandidateId);
+        if (existing !== undefined)
+            return toProfileConfirmation(existing);
+        const inserted = db.prepare("INSERT INTO profile_confirmations(contract_candidate_id, question, content, state, created_at) "
+            + "VALUES(?, ?, ?, 'pending', ?) RETURNING *").get(input.contractCandidateId, input.question, input.content, now);
+        return toProfileConfirmation(inserted);
+    };
+    const listProfileConfirmations = (state) => {
+        const rows = (state === undefined
+            ? db.prepare('SELECT * FROM profile_confirmations ORDER BY created_at, id').all()
+            : db.prepare('SELECT * FROM profile_confirmations WHERE state = ? ORDER BY created_at, id').all(state));
+        return rows.map(toProfileConfirmation);
+    };
+    const decideProfileConfirmation = (id, state, now) => {
+        db.prepare('UPDATE profile_confirmations SET state = ?, decided_at = ? WHERE id = ?').run(state, now, id);
+    };
+    return {
+        dbPath,
+        upsertDomain,
+        listDomains,
+        getDomain,
+        setDomainEnabled,
+        addDomainMember,
+        removeDomainMember,
+        listDomainMembers,
+        activeDomainIdentities,
+        upsertGlobalCandidate,
+        getGlobalCandidate,
+        listGlobalCandidates,
+        setGlobalCandidateState,
+        recordCandidateObservation,
+        listCandidateObservations,
+        enqueueProfileConfirmation,
+        listProfileConfirmations,
+        decideProfileConfirmation,
+        allocateTag,
+        getTag,
+        listTags,
+        recordUsage,
+        listUsage,
+        latestUsage,
+        latestHistoryChangeAt,
+        queueDrop,
+        listPendingDrops,
+        requestFlush,
+        listFlushRequestedDrops,
+        clearFlushRequests,
+        markDropLanded,
+        dropState,
+        tagSessions,
+        allocateCompartment,
+        listCompartments,
+        listUnlandedCompartments,
+        markCompartmentLanded,
+        markCompartmentRejected,
+        supersedeCompartment,
+        replaceCompartmentDraft,
+        coveredSeqs,
+        baselineState,
+        saveBaselineState,
+        setMeta: (key, value) => {
+            db.prepare('INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+                .run(key, value);
+        },
+        getMeta: (key) => {
+            const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+            return row?.value;
+        },
+        appendJournal: (entry) => {
+            db.prepare('INSERT INTO journal(at, level, kind, session_id, summary, data) VALUES(?, ?, ?, ?, ?, ?)')
+                .run(entry.at, entry.level, entry.kind, entry.sessionId ?? null, entry.summary, entry.data === undefined ? null : JSON.stringify(entry.data));
+        },
+        listJournal: (filter = {}) => {
+            const clauses = [];
+            const parameters = [];
+            if (filter.since !== undefined) {
+                clauses.push('at >= ?');
+                parameters.push(filter.since);
+            }
+            if (filter.until !== undefined) {
+                clauses.push('at <= ?');
+                parameters.push(filter.until);
+            }
+            if (filter.sessionId !== undefined) {
+                clauses.push('session_id = ?');
+                parameters.push(filter.sessionId);
+            }
+            if (filter.kinds !== undefined && filter.kinds.length > 0) {
+                clauses.push(`kind IN (${filter.kinds.map(() => '?').join(', ')})`);
+                parameters.push(...filter.kinds);
+            }
+            if (filter.levels !== undefined && filter.levels.length > 0) {
+                clauses.push(`level IN (${filter.levels.map(() => '?').join(', ')})`);
+                parameters.push(...filter.levels);
+            }
+            const where = clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`;
+            const limit = filter.limit === undefined ? '' : ` LIMIT ${String(Math.max(1, Math.floor(filter.limit)))}`;
+            const rows = db.prepare(`SELECT * FROM journal${where} ORDER BY id DESC${limit}`)
+                .all(...parameters);
+            return rows.map((row) => {
+                let data;
+                if (row.data !== null) {
+                    try {
+                        data = JSON.parse(row.data);
+                    }
+                    catch {
+                        data = { unparsable: true };
+                    }
+                }
+                return {
+                    at: row.at,
+                    level: row.level,
+                    kind: row.kind,
+                    summary: row.summary,
+                    ...row.session_id === null ? {} : { sessionId: row.session_id },
+                    ...data === undefined ? {} : { data },
+                };
+            });
+        },
+        journalByKind: (since, sessionId) => {
+            const clauses = [];
+            const parameters = [];
+            if (since !== undefined) {
+                clauses.push('at >= ?');
+                parameters.push(since);
+            }
+            if (sessionId !== undefined) {
+                clauses.push('session_id = ?');
+                parameters.push(sessionId);
+            }
+            const where = clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`;
+            return db.prepare(`SELECT kind, level, COUNT(*) AS count FROM journal${where} GROUP BY kind, level ORDER BY count DESC`).all(...parameters);
+        },
+        pruneJournal: (before) => {
+            const result = db.prepare('DELETE FROM journal WHERE at < ?').run(before);
+            return Number(result.changes);
+        },
+        recordMemoryEvent: (projectIdentity, memoryId, kind, now) => {
+            // Two statements on purpose: the upsert seeds the row, the bump applies
+            // the one counter the event names. ≤ ~46 events per pass (memoryLimit +
+            // search rows), so the extra prepare is noise next to correctness.
+            db.prepare('INSERT INTO memory_stats(project_identity, memory_id, updated_at) VALUES(?, ?, ?) '
+                + 'ON CONFLICT(project_identity, memory_id) DO NOTHING').run(projectIdentity, memoryId, now);
+            if (kind === 'hit') {
+                db.prepare('UPDATE memory_stats SET hits = hits + 1, last_hit_at = ?, updated_at = ? '
+                    + 'WHERE project_identity = ? AND memory_id = ?').run(now, now, projectIdentity, memoryId);
+            }
+            else {
+                db.prepare('UPDATE memory_stats SET injections = injections + 1, last_injected_at = ?, updated_at = ? '
+                    + 'WHERE project_identity = ? AND memory_id = ?').run(now, now, projectIdentity, memoryId);
+            }
+        },
+        listMemoryStats: (projectIdentity, memoryIds) => {
+            const toStat = (row) => ({
+                projectIdentity: row.project_identity,
+                memoryId: row.memory_id,
+                hits: row.hits,
+                ...row.last_hit_at === null ? {} : { lastHitAt: row.last_hit_at },
+                injections: row.injections,
+                ...row.last_injected_at === null ? {} : { lastInjectedAt: row.last_injected_at },
+                localArchived: row.local_archived !== 0,
+                updatedAt: row.updated_at,
+            });
+            if (memoryIds !== undefined && memoryIds.length === 0)
+                return [];
+            if (memoryIds === undefined) {
+                return db.prepare('SELECT * FROM memory_stats WHERE project_identity = ?')
+                    .all(projectIdentity).map(toStat);
+            }
+            const out = [];
+            // Chunked IN lists stay under SQLite's bound-parameter ceiling.
+            for (let index = 0; index < memoryIds.length; index += 500) {
+                const chunk = memoryIds.slice(index, index + 500);
+                const placeholders = chunk.map(() => '?').join(', ');
+                const rows = db.prepare(`SELECT * FROM memory_stats WHERE project_identity = ? AND memory_id IN (${placeholders})`).all(projectIdentity, ...chunk);
+                out.push(...rows.map(toStat));
+            }
+            return out;
+        },
+        // NOTE: no setter for `local_archived` any more — it had zero production
+        // callers from birth (2026-10-10 TTL 排查定案), and S(t) retirement is
+        // computed live at recall (memory-bridge pick) and live in the report
+        // meter. The column + the read in pick() stay as a manual-retire hook.
+        pruneMemoryStats: (projectIdentity, keepIds) => {
+            // One statement: orphans are rows whose memory_id left the known pool.
+            // keepIds is the project's whole visible pool (memoryLimit-bounded
+            // rendering aside, pools stay in the hundreds — well under SQLite's
+            // bound-parameter ceiling).
+            if (keepIds.length === 0) {
+                const result = db.prepare('DELETE FROM memory_stats WHERE project_identity = ?').run(projectIdentity);
+                return Number(result.changes);
+            }
+            const placeholders = keepIds.map(() => '?').join(', ');
+            const result = db.prepare(`DELETE FROM memory_stats WHERE project_identity = ? AND memory_id NOT IN (${placeholders})`).run(projectIdentity, ...keepIds);
+            return Number(result.changes);
+        },
+        journalBounds: () => {
+            const row = db.prepare('SELECT COUNT(*) AS rows, MIN(at) AS oldest, MAX(at) AS newest FROM journal')
+                .get();
+            return {
+                rows: row.rows,
+                ...row.oldest === null ? {} : { oldest: row.oldest },
+                ...row.newest === null ? {} : { newest: row.newest },
+            };
+        },
+        get closed() {
+            return closed;
+        },
+        close: () => {
+            closed = true;
+            db.close();
+        },
+    };
+}