cognitive-core 0.2.4 → 0.3.1

package/dist/persistence/sqlite-persistence.js

@@ -11,7 +11,9 @@
 import Database from 'better-sqlite3';
 import { join } from 'node:path';
 import { mkdirSync, existsSync } from 'node:fs';
-import { toISO, toJSON, fromJSON, toInt, fromInt, embeddingToBlob, blobToEmbedding, fromISO } from './serializers.js';
+import { randomUUID } from 'node:crypto';
+import { toISO, toJSON, fromJSON, toInt, fromInt, embeddingToBlob, blobToEmbedding, fromISO, } from './serializers.js';
+import { signatureFor, SIGNATURE_SCHEME_VERSION } from '../utils/task-signature.js';
 // Re-export serializers for use by consumers
 export { toISO, toJSON, fromJSON, toInt, fromInt, embeddingToBlob, blobToEmbedding, fromISO };
 const DEFAULT_CONFIG = {
@@ -20,6 +22,20 @@ const DEFAULT_CONFIG = {
     enableWAL: true,
     vectorDimension: 0,
 };
+/**
+ * Sort two parent ids into canonical (lo, hi) order so the merge_attempts
+ * table records (A, B, ancestor) and (B, A, ancestor) as the same row.
+ * Lexicographic string comparison.
+ */
+export function canonicalizeParentPair(a, b) {
+    return a < b ? [a, b] : [b, a];
+}
+/** Eval cache priority: live observations supersede LLM judgments. */
+const JUDGED_BY_PRIORITY = {
+    live: 3,
+    verifier: 2,
+    'llm-judge': 1,
+};
 // ============================================================================
 // SqlitePersistence class
 // ============================================================================
@@ -62,34 +78,47 @@ export class SqlitePersistence {
         return this.db;
     }
     /**
-     * Run a function inside a transaction.
+     * Run a function inside a transaction (default DEFERRED — read snapshot taken
+     * at first read; write lock at first write).
      */
     transaction(fn) {
         const tx = this.db.transaction(fn);
         return tx();
     }
+    /**
+     * Run a function inside an IMMEDIATE transaction (`BEGIN IMMEDIATE` — takes
+     * the write lock up front). Required for read-then-write compare-and-set logic
+     * that must serialize across processes under WAL (queue claiming, the dream
+     * lock); DEFERRED's snapshot isolation would let two processes both pass the
+     * pre-check.
+     */
+    transactionImmediate(fn) {
+        return this.db.transaction(fn).immediate();
+    }
     // ==========================================================================
     // Schema DDL
     // ==========================================================================
     createSchema() {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS experiences (
-        id               TEXT PRIMARY KEY,
-        task_input       TEXT NOT NULL,
-        solution_output  TEXT NOT NULL,
-        feedback         TEXT NOT NULL,
-        success          INTEGER NOT NULL,
-        domain           TEXT NOT NULL,
-        embedding        BLOB,
-        trajectory_id    TEXT NOT NULL,
-        usage_count      INTEGER NOT NULL DEFAULT 0,
-        access_score     REAL NOT NULL DEFAULT 0,
-        retrieval_count  INTEGER NOT NULL DEFAULT 0,
-        tier             TEXT NOT NULL DEFAULT 'hot',
-        compressed       TEXT,
-        metadata         TEXT NOT NULL DEFAULT '{}',
-        created_at       TEXT NOT NULL,
-        last_accessed_at TEXT
+        id                       TEXT PRIMARY KEY,
+        task_input               TEXT NOT NULL,
+        solution_output          TEXT NOT NULL,
+        feedback                 TEXT NOT NULL,
+        success                  INTEGER NOT NULL,
+        domain                   TEXT NOT NULL,
+        embedding                BLOB,
+        trajectory_id            TEXT NOT NULL,
+        usage_count              INTEGER NOT NULL DEFAULT 0,
+        access_score             REAL NOT NULL DEFAULT 0,
+        retrieval_count          INTEGER NOT NULL DEFAULT 0,
+        tier                     TEXT NOT NULL DEFAULT 'hot',
+        compressed               TEXT,
+        metadata                 TEXT NOT NULL DEFAULT '{}',
+        created_at               TEXT NOT NULL,
+        last_accessed_at         TEXT,
+        task_signature           TEXT,
+        signature_scheme_version INTEGER
       );
 
       CREATE INDEX IF NOT EXISTS idx_experiences_domain ON experiences(domain);
@@ -98,32 +127,156 @@ export class SqlitePersistence {
       CREATE INDEX IF NOT EXISTS idx_experiences_tier ON experiences(tier);
       CREATE INDEX IF NOT EXISTS idx_experiences_access_score ON experiences(access_score);
       CREATE INDEX IF NOT EXISTS idx_experiences_created_at ON experiences(created_at);
+      CREATE INDEX IF NOT EXISTS idx_experiences_task_signature ON experiences(task_signature);
 
       CREATE TABLE IF NOT EXISTS playbooks (
-        id                TEXT PRIMARY KEY,
-        name              TEXT NOT NULL,
-        confidence        REAL NOT NULL DEFAULT 0.3,
-        complexity        TEXT NOT NULL DEFAULT 'moderate',
-        estimated_effort  INTEGER NOT NULL DEFAULT 3,
-        primary_domain    TEXT,
-        success_count     INTEGER NOT NULL DEFAULT 0,
-        failure_count     INTEGER NOT NULL DEFAULT 0,
-        version           TEXT NOT NULL DEFAULT '1.0.0',
-        origin            TEXT,
-        applicability     TEXT NOT NULL,
-        guidance          TEXT NOT NULL,
-        verification      TEXT NOT NULL DEFAULT '{}',
-        evolution         TEXT NOT NULL DEFAULT '{}',
-        provenance        TEXT,
-        embedding         BLOB,
-        created_at        TEXT NOT NULL,
-        updated_at        TEXT NOT NULL
+        id                  TEXT PRIMARY KEY,
+        name                TEXT NOT NULL,
+        confidence          REAL NOT NULL DEFAULT 0.3,
+        complexity          TEXT NOT NULL DEFAULT 'moderate',
+        estimated_effort    INTEGER NOT NULL DEFAULT 3,
+        primary_domain      TEXT,
+        success_count       INTEGER NOT NULL DEFAULT 0,
+        failure_count       INTEGER NOT NULL DEFAULT 0,
+        version             TEXT NOT NULL DEFAULT '1.0.0',
+        origin              TEXT,
+        applicability       TEXT NOT NULL,
+        guidance            TEXT NOT NULL,
+        verification        TEXT NOT NULL DEFAULT '{}',
+        evolution           TEXT NOT NULL DEFAULT '{}',
+        provenance          TEXT,
+        embedding           BLOB,
+        created_at          TEXT NOT NULL,
+        updated_at          TEXT NOT NULL,
+        parent_playbook_id  TEXT,
+        FOREIGN KEY (parent_playbook_id) REFERENCES playbooks(id) ON DELETE SET NULL
       );
 
       CREATE INDEX IF NOT EXISTS idx_playbooks_name ON playbooks(name);
       CREATE INDEX IF NOT EXISTS idx_playbooks_confidence ON playbooks(confidence);
       CREATE INDEX IF NOT EXISTS idx_playbooks_primary_domain ON playbooks(primary_domain);
       CREATE INDEX IF NOT EXISTS idx_playbooks_origin ON playbooks(origin);
+      CREATE INDEX IF NOT EXISTS idx_playbooks_parent ON playbooks(parent_playbook_id);
+
+      CREATE TABLE IF NOT EXISTS playbook_frontier (
+        task_signature TEXT NOT NULL,
+        experience_id  TEXT NOT NULL,
+        playbook_id    TEXT NOT NULL,
+        score          REAL NOT NULL,
+        recorded_at    TEXT NOT NULL,
+        PRIMARY KEY (task_signature, experience_id, playbook_id),
+        FOREIGN KEY (playbook_id)   REFERENCES playbooks(id)   ON DELETE CASCADE,
+        FOREIGN KEY (experience_id) REFERENCES experiences(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_frontier_sig_exp_score
+        ON playbook_frontier(task_signature, experience_id, score DESC);
+      CREATE INDEX IF NOT EXISTS idx_frontier_playbook
+        ON playbook_frontier(playbook_id);
+
+      CREATE TABLE IF NOT EXISTS playbook_eval_cache (
+        playbook_hash TEXT NOT NULL,
+        experience_id TEXT NOT NULL,
+        score         REAL NOT NULL,
+        judged_by     TEXT NOT NULL,
+        details       TEXT,
+        created_at    TEXT NOT NULL,
+        PRIMARY KEY (playbook_hash, experience_id),
+        FOREIGN KEY (experience_id) REFERENCES experiences(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_eval_cache_judged
+        ON playbook_eval_cache(playbook_hash, judged_by);
+
+      -- Merge attempt dedup: records (canonical_pair, ancestor) -> result so the
+      -- maintenance loop doesn't re-judge the same triplet every cycle. Only
+      -- "real" gate decisions ('accepted' | 'regression') are recorded —
+      -- sparse/empty-minibatch outcomes get retried because more data may
+      -- accumulate by the next cycle.
+      CREATE TABLE IF NOT EXISTS merge_attempts (
+        parent_lo_id  TEXT NOT NULL,
+        parent_hi_id  TEXT NOT NULL,
+        ancestor_id   TEXT NOT NULL,
+        result        TEXT NOT NULL,
+        attempted_at  TEXT NOT NULL,
+        PRIMARY KEY (parent_lo_id, parent_hi_id, ancestor_id),
+        FOREIGN KEY (parent_lo_id) REFERENCES playbooks(id) ON DELETE CASCADE,
+        FOREIGN KEY (parent_hi_id) REFERENCES playbooks(id) ON DELETE CASCADE,
+        FOREIGN KEY (ancestor_id)  REFERENCES playbooks(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_merge_attempts_attempted
+        ON merge_attempts(attempted_at);
+
+      -- Reflective-mutation attempt dedup: records (parent, failure_fingerprint)
+      -- -> result so the maintenance loop doesn't re-reflect the same playbook
+      -- on the same set of failing experiences every cycle. The fingerprint is
+      -- a hash of the failing experience IDs the proposer reflected on, so a
+      -- new attempt is only triggered once new failures accumulate. As with
+      -- merges, only definitive gate decisions ('accepted' | 'regression') are
+      -- recorded — sparse outcomes get retried.
+      CREATE TABLE IF NOT EXISTS reflection_attempts (
+        parent_id           TEXT NOT NULL,
+        failure_fingerprint TEXT NOT NULL,
+        result              TEXT NOT NULL,
+        attempted_at        TEXT NOT NULL,
+        PRIMARY KEY (parent_id, failure_fingerprint),
+        FOREIGN KEY (parent_id) REFERENCES playbooks(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_reflection_attempts_attempted
+        ON reflection_attempts(attempted_at);
+
+      -- Mutation optimization journal: unlike reflection_attempts (a hash+result
+      -- dedup guard that carries no learning content), this records the LEARNING
+      -- CONTENT of every mutation the gate considered — the candidate direction,
+      -- the gate's decision reason, the score delta (child_sum - parent_sum), and
+      -- a short rationale. The ReflectiveMutationProposer reads a parent's recent
+      -- entries back into its prompt so it proposes a MEANINGFULLY DIFFERENT edit
+      -- rather than re-treading rejected directions (GEPA-style "reflect on the
+      -- trajectory of prior attempts"). Append-only; keyed by autoincrement id so
+      -- the same parent accumulates a history rather than overwriting.
+      CREATE TABLE IF NOT EXISTS mutation_journal (
+        id             INTEGER PRIMARY KEY AUTOINCREMENT,
+        parent_id      TEXT NOT NULL,
+        task_signature TEXT,
+        mutation_type  TEXT NOT NULL,
+        candidate_id   TEXT,
+        candidate_name TEXT,
+        guidance_after TEXT,
+        reason         TEXT NOT NULL,
+        accepted       INTEGER NOT NULL,
+        parent_sum     REAL NOT NULL,
+        child_sum      REAL NOT NULL,
+        score_delta    REAL NOT NULL,
+        rationale      TEXT,
+        attempted_at   TEXT NOT NULL,
+        FOREIGN KEY (parent_id) REFERENCES playbooks(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_mutation_journal_parent
+        ON mutation_journal(parent_id, attempted_at DESC);
+
+      -- Cartesian frontier: per-(signature, experience, objective, playbook)
+      -- Used for multi-objective Pareto routing. Coexists with playbook_frontier
+      -- which tracks the single-objective (quality) frontier — same data shape,
+      -- just one row per objective instead of one total.
+      CREATE TABLE IF NOT EXISTS playbook_frontier_cartesian (
+        task_signature TEXT NOT NULL,
+        experience_id  TEXT NOT NULL,
+        objective      TEXT NOT NULL,
+        playbook_id    TEXT NOT NULL,
+        score          REAL NOT NULL,
+        recorded_at    TEXT NOT NULL,
+        PRIMARY KEY (task_signature, experience_id, objective, playbook_id),
+        FOREIGN KEY (playbook_id)   REFERENCES playbooks(id)   ON DELETE CASCADE,
+        FOREIGN KEY (experience_id) REFERENCES experiences(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_frontier_cart_sig_obj_score
+        ON playbook_frontier_cartesian(task_signature, objective, score DESC);
+      CREATE INDEX IF NOT EXISTS idx_frontier_cart_playbook
+        ON playbook_frontier_cartesian(playbook_id);
 
       CREATE TABLE IF NOT EXISTS playbook_versions (
         playbook_id   TEXT NOT NULL,
@@ -208,6 +361,96 @@ export class SqlitePersistence {
         version    INTEGER NOT NULL,
         applied_at TEXT NOT NULL
       );
+
+      -- Dream queue (Phase A of the dreaming refactor): durable, source-agnostic
+      -- backlog of trajectories awaiting offline consolidation. Replaces the
+      -- in-memory, per-process accumulator so a separate process can drain it.
+      -- Phase A is write-only (dual-write alongside the inline path); the
+      -- claim/lease/reclaim consumer arrives in later phases. The lease columns
+      -- exist now so those phases need no migration. trajectory_id is UNIQUE
+      -- so enqueue is idempotent (INSERT OR IGNORE).
+      CREATE TABLE IF NOT EXISTS dream_queue (
+        id               TEXT PRIMARY KEY,
+        trajectory_id    TEXT NOT NULL UNIQUE,
+        trajectory_json  TEXT NOT NULL,
+        routing_json     TEXT,
+        source           TEXT NOT NULL DEFAULT 'pipeline',
+        status           TEXT NOT NULL DEFAULT 'pending',
+        enqueued_at      TEXT NOT NULL,
+        lease_owner      TEXT,
+        lease_expires_at TEXT,
+        attempts         INTEGER NOT NULL DEFAULT 0
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_dream_queue_status   ON dream_queue(status);
+      CREATE INDEX IF NOT EXISTS idx_dream_queue_enqueued ON dream_queue(enqueued_at);
+
+      -- Distillation cache (PR-D1): keyed by sha256(canonical-trajectory-form +
+      -- PROMPT_VERSION). Cache hits skip the LLM call entirely so re-runs are
+      -- fully reproducible and cost-free after the first distillation.
+      CREATE TABLE IF NOT EXISTS distillation_cache (
+        cache_key    TEXT PRIMARY KEY,
+        playbook_json TEXT NOT NULL,
+        created_at   TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_distillation_cache_created
+        ON distillation_cache(created_at);
+
+      -- Filesystem cascade (section 6.2): durable change queue + content-hash
+      -- index. The watcher enqueues canonical-file edits here; a worker drains
+      -- them to reindex derived rows. Durable so a change detected mid-session
+      -- survives a crash (startup full-reindex is the backstop). path is UNIQUE
+      -- so re-enqueuing the same file coalesces to a single pending row (last op
+      -- wins). This is part of the rebuildable cache: deleting cognitive-core.db
+      -- drops the queue + hashes and a cold boot full-reindexes from files.
+      CREATE TABLE IF NOT EXISTS md_change_queue (
+        id           TEXT PRIMARY KEY,
+        path         TEXT NOT NULL UNIQUE,
+        kind         TEXT NOT NULL,                    -- 'playbook'
+        op           TEXT NOT NULL,                    -- 'upsert' | 'delete'
+        status       TEXT NOT NULL DEFAULT 'pending',  -- 'pending' | 'error'
+        enqueued_at  TEXT NOT NULL,
+        attempts     INTEGER NOT NULL DEFAULT 0,
+        last_error   TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_md_change_queue_status ON md_change_queue(status);
+
+      -- Content-hash index: what each canonical file looked like the last time
+      -- its derived rows were written. The drain (and, later, startup) skip files
+      -- whose hash is unchanged, so an unchanged file never re-embeds/re-indexes.
+      CREATE TABLE IF NOT EXISTS md_file_index (
+        path         TEXT PRIMARY KEY,
+        content_hash TEXT NOT NULL,
+        entity_id    TEXT,                             -- indexed playbook id
+        indexed_at   TEXT NOT NULL
+      );
+
+      -- Lift registry (production side): per-(scope, family, solver) treatment
+      -- effect of memory injection, rolled up at dream time from effectiveness
+      -- annotations. scope is always 'production' here; eval-side cells live in
+      -- the standalone eval registry DB (src/eval/live/registry-store.ts —
+      -- SCHEMA MUST STAY IN SYNC with LIFT_CELLS_DDL there). The difficulty
+      -- registry answers "how hard is family X" (base rate); this table answers
+      -- "does memory injection change outcomes on family X with solver Y"
+      -- (treatment effect). Cells never pool across solvers or across
+      -- eval/production populations. Write-only from the pipeline (no core
+      -- consumers); read by "cogcore eval lift-report".
+      -- TODO(recency): runs is a raw counter; EMA/window decay is deferred —
+      -- see DESIGN-meta-learning-validation.md §10 (lift registry).
+      CREATE TABLE IF NOT EXISTS lift_cells (
+        scope              TEXT NOT NULL,
+        family             TEXT NOT NULL,
+        solver             TEXT NOT NULL,
+        guided_attempts    INTEGER NOT NULL DEFAULT 0,
+        guided_successes   INTEGER NOT NULL DEFAULT 0,
+        unguided_attempts  INTEGER NOT NULL DEFAULT 0,
+        unguided_successes INTEGER NOT NULL DEFAULT 0,
+        runs               INTEGER NOT NULL DEFAULT 0,
+        updated_at         TEXT NOT NULL,
+        PRIMARY KEY (scope, family, solver)
+      );
     `);
     }
     // ==========================================================================
@@ -233,13 +476,52 @@ export class SqlitePersistence {
     // Experiences CRUD
     // ==========================================================================
     insertExperience(exp) {
+        // Auto-stamp signature if caller didn't provide one. The signature is
+        // derived from (domain, taskInput) so it's always recomputable, but
+        // stamping at write time avoids per-query recompute and lets the
+        // index serve grouping/lookup directly.
+        let signature = exp.taskSignature;
+        let schemeVersion = exp.signatureSchemeVersion;
+        if (!signature) {
+            signature = signatureFor(exp.domain, exp.taskInput);
+            schemeVersion = SIGNATURE_SCHEME_VERSION;
+        }
+        else if (schemeVersion === undefined) {
+            schemeVersion = SIGNATURE_SCHEME_VERSION;
+        }
+        // UPSERT (not REPLACE): preserves row identity so cascade-delete-dependent
+        // rows (playbook_frontier, playbook_eval_cache via experience_id) survive
+        // experience metadata updates (access counter bumps, tier changes, etc).
         this.stmt('insert_experience', `
-      INSERT OR REPLACE INTO experiences
+      INSERT INTO experiences
         (id, task_input, solution_output, feedback, success, domain, embedding,
          trajectory_id, usage_count, access_score, retrieval_count, tier,
-         compressed, metadata, created_at, last_accessed_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(exp.id, exp.taskInput, exp.solutionOutput, exp.feedback, toInt(exp.success), exp.domain, embeddingToBlob(exp.embedding), exp.trajectoryId, exp.usageCount, exp.accessScore, exp.retrievalCount, exp.tier ?? 'hot', toJSON(exp.compressed), toJSON(exp.metadata), toISO(exp.createdAt), toISO(exp.lastAccessedAt));
+         compressed, metadata, created_at, last_accessed_at,
+         task_signature, signature_scheme_version)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        task_input               = excluded.task_input,
+        solution_output          = excluded.solution_output,
+        feedback                 = excluded.feedback,
+        success                  = excluded.success,
+        domain                   = excluded.domain,
+        embedding                = excluded.embedding,
+        trajectory_id            = excluded.trajectory_id,
+        usage_count              = excluded.usage_count,
+        access_score             = excluded.access_score,
+        retrieval_count          = excluded.retrieval_count,
+        tier                     = excluded.tier,
+        compressed               = excluded.compressed,
+        metadata                 = excluded.metadata,
+        last_accessed_at         = excluded.last_accessed_at,
+        task_signature           = excluded.task_signature,
+        signature_scheme_version = excluded.signature_scheme_version
+    `).run(exp.id, exp.taskInput, exp.solutionOutput, exp.feedback, toInt(exp.success), exp.domain, embeddingToBlob(exp.embedding), exp.trajectoryId, 
+        // Coalesce defaulted columns. UPSERT (unlike INSERT OR REPLACE) does
+        // NOT substitute column DEFAULTs for NULL binds, so callers passing
+        // undefined would hit NOT NULL constraints. Mirror the Zod schema
+        // defaults from src/types/memory.ts.
+        exp.usageCount ?? 0, exp.accessScore ?? 0, exp.retrievalCount ?? 0, exp.tier ?? 'hot', toJSON(exp.compressed), toJSON(exp.metadata ?? {}), toISO(exp.createdAt ?? new Date()), toISO(exp.lastAccessedAt), signature, schemeVersion);
     }
     getExperience(id) {
         return this.stmt('get_experience', 'SELECT * FROM experiences WHERE id = ?').get(id);
@@ -300,14 +582,38 @@ export class SqlitePersistence {
     // Playbooks CRUD
     // ==========================================================================
     insertPlaybook(pb) {
+        // UPSERT (not REPLACE): preserves the row's identity on conflict, so
+        // cascade-delete-dependent rows (playbook_frontier, playbook_eval_cache
+        // via experience_id, playbook_versions) are not wiped on every
+        // confidence bump or evolution edit.
         this.stmt('insert_playbook', `
-      INSERT OR REPLACE INTO playbooks
+      INSERT INTO playbooks
         (id, name, confidence, complexity, estimated_effort, primary_domain,
          success_count, failure_count, version, origin,
          applicability, guidance, verification, evolution, provenance,
-         embedding, created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(pb.id, pb.name, pb.confidence, pb.complexity, pb.estimatedEffort, pb.applicability.domains?.[0] ?? null, pb.evolution.successCount, pb.evolution.failureCount, pb.evolution.version, pb.provenance?.origin ?? null, toJSON(pb.applicability), toJSON(pb.guidance), toJSON(pb.verification), toJSON(pb.evolution), pb.provenance ? toJSON(pb.provenance) : null, embeddingToBlob(pb.embedding), toISO(pb.createdAt), toISO(pb.updatedAt));
+         embedding, created_at, updated_at, parent_playbook_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        name             = excluded.name,
+        confidence       = excluded.confidence,
+        complexity       = excluded.complexity,
+        estimated_effort = excluded.estimated_effort,
+        primary_domain   = excluded.primary_domain,
+        success_count    = excluded.success_count,
+        failure_count    = excluded.failure_count,
+        version          = excluded.version,
+        origin           = excluded.origin,
+        applicability    = excluded.applicability,
+        guidance         = excluded.guidance,
+        verification     = excluded.verification,
+        evolution        = excluded.evolution,
+        provenance       = excluded.provenance,
+        embedding        = excluded.embedding,
+        updated_at       = excluded.updated_at,
+        parent_playbook_id = excluded.parent_playbook_id
+    `).run(pb.id, pb.name, 
+        // Coalesce defaulted columns — see insertExperience for rationale.
+        pb.confidence ?? 0.3, pb.complexity ?? 'moderate', pb.estimatedEffort ?? 3, pb.applicability.domains?.[0] ?? null, pb.evolution.successCount ?? 0, pb.evolution.failureCount ?? 0, pb.evolution.version ?? '1.0.0', pb.provenance?.origin ?? null, toJSON(pb.applicability), toJSON(pb.guidance), toJSON(pb.verification ?? {}), toJSON(pb.evolution ?? {}), pb.provenance ? toJSON(pb.provenance) : null, embeddingToBlob(pb.embedding), toISO(pb.createdAt ?? new Date()), toISO(pb.updatedAt ?? new Date()), pb.parentPlaybookId ?? null);
     }
     getPlaybook(id) {
         return this.stmt('get_playbook', 'SELECT * FROM playbooks WHERE id = ?').get(id);
@@ -353,6 +659,30 @@ export class SqlitePersistence {
         const row = this.stmt('count_playbooks', 'SELECT COUNT(*) as count FROM playbooks').get();
         return row.count;
     }
+    /**
+     * Get the playbook id chain from this playbook up to its root ancestor.
+     * Result includes the starting id and walks `parent_playbook_id` until
+     * null. Used by the merge proposer to find common ancestors. Returns
+     * an empty array if the playbook doesn't exist.
+     *
+     * Safety: caps walk at 64 to avoid pathological cycles.
+     */
+    getAncestryChain(playbookId) {
+        const chain = [];
+        const seen = new Set();
+        let current = playbookId;
+        let depth = 0;
+        while (current && !seen.has(current) && depth < 64) {
+            const row = this.getPlaybook(current);
+            if (!row)
+                break;
+            chain.push(current);
+            seen.add(current);
+            current = row.parent_playbook_id;
+            depth++;
+        }
+        return chain;
+    }
     /** Snapshot current playbook state for version history. */
     snapshotPlaybookVersion(playbookId, version, changelog = '') {
         const pb = this.getPlaybook(playbookId);
@@ -368,6 +698,292 @@ export class SqlitePersistence {
         return this.stmt('get_playbook_versions', 'SELECT * FROM playbook_versions WHERE playbook_id = ? ORDER BY created_at ASC').all(playbookId);
     }
     // ==========================================================================
+    // Playbook frontier CRUD
+    //
+    // One row per (task_signature, experience_id, playbook_id). The best score
+    // for a (signature, experience) pair across all playbooks defines the
+    // per-example Pareto frontier — used for specialist preservation.
+    // ==========================================================================
+    /**
+     * Upsert a frontier row. If a row already exists for
+     * (task_signature, experience_id, playbook_id), keep the higher score
+     * (frontier records each playbook's *best* score on each example).
+     */
+    upsertFrontierRow(taskSignature, experienceId, playbookId, score, recordedAt = new Date()) {
+        this.stmt('upsert_frontier', `
+      INSERT INTO playbook_frontier
+        (task_signature, experience_id, playbook_id, score, recorded_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(task_signature, experience_id, playbook_id) DO UPDATE SET
+        score = MAX(playbook_frontier.score, excluded.score),
+        recorded_at = excluded.recorded_at
+    `).run(taskSignature, experienceId, playbookId, score, toISO(recordedAt));
+    }
+    /**
+     * Get all frontier rows for a signature. Sorted by experience then score.
+     */
+    getFrontierBySignature(taskSignature) {
+        return this.stmt('get_frontier_by_signature', `
+      SELECT * FROM playbook_frontier
+      WHERE task_signature = ?
+      ORDER BY experience_id, score DESC
+    `).all(taskSignature);
+    }
+    /**
+     * Get all frontier rows for a playbook (across all signatures).
+     * Used by `getFrontierContribution` to gate deletion of specialists.
+     */
+    getFrontierByPlaybook(playbookId) {
+        return this.stmt('get_frontier_by_playbook', `
+      SELECT * FROM playbook_frontier
+      WHERE playbook_id = ?
+    `).all(playbookId);
+    }
+    /**
+     * Compute the frontier contribution of a playbook: how many
+     * (sig, experience) pairs it is at the top of (totalWins), and how many
+     * of those are *uniquely* held by it (uniqueWins, no other playbook ties).
+     *
+     * Deletion paths (consolidation, GC, pruning) should refuse to delete
+     * a playbook with `uniqueWins > 0` without an explicit replay-replace.
+     */
+    getFrontierContribution(playbookId) {
+        // total wins: this playbook's score is the max for its (sig, exp)
+        const total = this.stmt('frontier_total_wins', `
+      SELECT COUNT(*) AS n FROM playbook_frontier pf
+      WHERE pf.playbook_id = ?
+        AND pf.score = (
+          SELECT MAX(score) FROM playbook_frontier
+          WHERE task_signature = pf.task_signature
+            AND experience_id = pf.experience_id
+        )
+    `).get(playbookId);
+        // unique wins: this playbook is the only one with the max score for its (sig, exp)
+        const unique = this.stmt('frontier_unique_wins', `
+      SELECT COUNT(*) AS n FROM playbook_frontier pf
+      WHERE pf.playbook_id = ?
+        AND pf.score = (
+          SELECT MAX(score) FROM playbook_frontier
+          WHERE task_signature = pf.task_signature
+            AND experience_id = pf.experience_id
+        )
+        AND NOT EXISTS (
+          SELECT 1 FROM playbook_frontier other
+          WHERE other.task_signature = pf.task_signature
+            AND other.experience_id  = pf.experience_id
+            AND other.playbook_id   != pf.playbook_id
+            AND other.score          = pf.score
+        )
+    `).get(playbookId);
+        return { uniqueWins: unique.n, totalWins: total.n };
+    }
+    /**
+     * Distinct task signatures present in the frontier, ordered by most
+     * recent activity. Used by the maintenance loop to pick signatures
+     * that have actually accumulated evidence and are worth re-scanning
+     * for merge candidates.
+     */
+    getActiveSignatures(limit = 20) {
+        return this.stmt('active_signatures', `
+      SELECT task_signature, MAX(recorded_at) AS latest
+      FROM playbook_frontier
+      GROUP BY task_signature
+      ORDER BY latest DESC
+      LIMIT ?
+    `).all(limit).map((r) => r.task_signature);
+    }
+    /**
+     * Delete all frontier rows for a playbook. Idempotent.
+     * Normally not called directly — cascades from `DELETE FROM playbooks`.
+     */
+    deleteFrontierForPlaybook(playbookId) {
+        const r = this.stmt('delete_frontier_for_playbook', 'DELETE FROM playbook_frontier WHERE playbook_id = ?').run(playbookId);
+        return r.changes;
+    }
+    // ==========================================================================
+    // Playbook cartesian frontier CRUD
+    //
+    // One row per (sig, exp, objective, playbook). The best score for a
+    // (sig, exp, objective) tuple across all playbooks defines the
+    // per-(example, objective) Pareto frontier.
+    // ==========================================================================
+    /**
+     * Upsert a cartesian frontier row, keeping the higher score on conflict.
+     * For an outcome with multiple objectives, call once per objective.
+     */
+    upsertFrontierCartesianRow(taskSignature, experienceId, objective, playbookId, score, recordedAt = new Date()) {
+        this.stmt('upsert_frontier_cartesian', `
+      INSERT INTO playbook_frontier_cartesian
+        (task_signature, experience_id, objective, playbook_id, score, recorded_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(task_signature, experience_id, objective, playbook_id) DO UPDATE SET
+        score = MAX(playbook_frontier_cartesian.score, excluded.score),
+        recorded_at = excluded.recorded_at
+    `).run(taskSignature, experienceId, objective, playbookId, score, toISO(recordedAt));
+    }
+    /**
+     * Get all cartesian frontier rows for a signature. Sorted by
+     * (experience, objective, score DESC).
+     */
+    getFrontierCartesianBySignature(taskSignature) {
+        return this.stmt('get_frontier_cart_by_signature', `
+      SELECT * FROM playbook_frontier_cartesian
+      WHERE task_signature = ?
+      ORDER BY experience_id, objective, score DESC
+    `).all(taskSignature);
+    }
+    /**
+     * Get all cartesian frontier rows for a signature filtered to a
+     * specific objective. Useful when the router wants a single-objective
+     * frontier (e.g., "best by cost only").
+     */
+    getFrontierCartesianBySignatureAndObjective(taskSignature, objective) {
+        return this.stmt('get_frontier_cart_by_sig_obj', `
+      SELECT * FROM playbook_frontier_cartesian
+      WHERE task_signature = ? AND objective = ?
+      ORDER BY experience_id, score DESC
+    `).all(taskSignature, objective);
+    }
+    /**
+     * Distinct objective keys currently recorded in the cartesian frontier.
+     * Lets callers introspect what objectives have been observed.
+     */
+    getCartesianObjectives() {
+        return this.stmt('cart_distinct_objectives', `
+      SELECT DISTINCT objective FROM playbook_frontier_cartesian ORDER BY objective
+    `).all().map((r) => r.objective);
+    }
+    // ==========================================================================
+    // Merge attempts dedup
+    //
+    // Records (canonicalized parent pair, ancestor) -> result so the
+    // maintenance loop doesn't re-judge the same triplet every cycle.
+    // ==========================================================================
+    /**
+     * Record a merge attempt outcome. The parent ids are sorted into
+     * lo/hi canonical form so (A, B) and (B, A) hash to the same row.
+     */
+    recordMergeAttempt(parentAId, parentBId, ancestorId, result, attemptedAt = new Date()) {
+        const [lo, hi] = canonicalizeParentPair(parentAId, parentBId);
+        this.stmt('record_merge_attempt', `
+      INSERT INTO merge_attempts
+        (parent_lo_id, parent_hi_id, ancestor_id, result, attempted_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(parent_lo_id, parent_hi_id, ancestor_id) DO UPDATE SET
+        result       = excluded.result,
+        attempted_at = excluded.attempted_at
+    `).run(lo, hi, ancestorId, result, toISO(attemptedAt));
+    }
+    /**
+     * Look up the most recent merge attempt for a (parent pair, ancestor)
+     * triplet. Parent IDs are canonicalized before lookup.
+     */
+    getMergeAttempt(parentAId, parentBId, ancestorId) {
+        const [lo, hi] = canonicalizeParentPair(parentAId, parentBId);
+        return this.stmt('get_merge_attempt', `
+      SELECT * FROM merge_attempts
+      WHERE parent_lo_id = ? AND parent_hi_id = ? AND ancestor_id = ?
+    `).get(lo, hi, ancestorId);
+    }
+    /**
+     * Record a reflective-mutation attempt outcome, keyed on the parent
+     * playbook and a fingerprint of the failing experiences reflected on.
+     */
+    recordReflectionAttempt(parentId, failureFingerprint, result, attemptedAt = new Date()) {
+        this.stmt('record_reflection_attempt', `
+      INSERT INTO reflection_attempts
+        (parent_id, failure_fingerprint, result, attempted_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(parent_id, failure_fingerprint) DO UPDATE SET
+        result       = excluded.result,
+        attempted_at = excluded.attempted_at
+    `).run(parentId, failureFingerprint, result, toISO(attemptedAt));
+    }
+    /**
+     * Look up the most recent reflective-mutation attempt for a
+     * (parent, failure_fingerprint) pair.
+     */
+    getReflectionAttempt(parentId, failureFingerprint) {
+        return this.stmt('get_reflection_attempt', `
+      SELECT * FROM reflection_attempts
+      WHERE parent_id = ? AND failure_fingerprint = ?
+    `).get(parentId, failureFingerprint);
+    }
+    // ==========================================================================
+    // Mutation journal CRUD
+    //
+    // Append-only log of the learning content of every mutation the gate
+    // considered. Read back by the ReflectiveMutationProposer to reflect on the
+    // trajectory of prior attempts (see the `mutation_journal` DDL).
+    // ==========================================================================
+    /**
+     * Append a mutation-decision entry to the journal for `parentId`. Never
+     * overwrites — each considered proposal adds a row, so a parent accumulates
+     * its optimization history.
+     */
+    recordMutationJournalEntry(entry, attemptedAt = new Date()) {
+        this.stmt('record_mutation_journal_entry', `
+      INSERT INTO mutation_journal
+        (parent_id, task_signature, mutation_type, candidate_id, candidate_name,
+         guidance_after, reason, accepted, parent_sum, child_sum, score_delta,
+         rationale, attempted_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(entry.parentId, entry.taskSignature ?? null, entry.mutationType, entry.candidateId ?? null, entry.candidateName ?? null, entry.guidanceAfter ?? null, entry.reason, entry.accepted ? 1 : 0, entry.parentSum, entry.childSum, entry.scoreDelta, entry.rationale ?? null, toISO(attemptedAt));
+    }
+    /**
+     * Most recent journal entries for a parent playbook, newest first, capped
+     * at `limit` (default 5). Empty when the parent has no recorded attempts.
+     */
+    getMutationJournal(parentId, limit = 5) {
+        return this.stmt('get_mutation_journal', `
+      SELECT * FROM mutation_journal
+      WHERE parent_id = ?
+      ORDER BY attempted_at DESC, id DESC
+      LIMIT ?
+    `).all(parentId, limit);
+    }
+    // ==========================================================================
+    // Playbook eval cache CRUD
+    //
+    // Caches (playbook_hash, experience_id) -> score for replay-based
+    // acceptance gates. Live scores supersede LLM-judge scores via the
+    // `judged_by` priority ordering in `getCachedEval`.
+    // ==========================================================================
+    /**
+     * Upsert a cache entry, respecting priority: a write only succeeds if
+     * the incoming `judgedBy` has equal or higher priority than the existing
+     * row's `judgedBy`. Priority order: live > verifier > llm-judge.
+     *
+     * Returns true if the row was written, false if it was rejected because
+     * a higher-priority entry already exists.
+     */
+    upsertEvalCache(playbookHash, experienceId, score, judgedBy, details, createdAt = new Date()) {
+        const newPri = JUDGED_BY_PRIORITY[judgedBy];
+        const existing = this.getCachedEval(playbookHash, experienceId);
+        if (existing) {
+            const existingPri = JUDGED_BY_PRIORITY[existing.judged_by] ?? 0;
+            if (newPri < existingPri) {
+                return false;
+            }
+        }
+        this.stmt('upsert_eval_cache', `
+      INSERT OR REPLACE INTO playbook_eval_cache
+        (playbook_hash, experience_id, score, judged_by, details, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(playbookHash, experienceId, score, judgedBy, details ?? null, toISO(createdAt));
+        return true;
+    }
+    /**
+     * Get the highest-priority cached eval for a (hash, experience) pair.
+     * Priority: live > verifier > llm-judge.
+     */
+    getCachedEval(playbookHash, experienceId) {
+        return this.stmt('get_cached_eval', `
+      SELECT * FROM playbook_eval_cache
+      WHERE playbook_hash = ? AND experience_id = ?
+    `).get(playbookHash, experienceId);
+    }
+    // ==========================================================================
     // Reflexion Episodes CRUD
     // ==========================================================================
     insertReflexionEpisode(ep) {
@@ -481,11 +1097,13 @@ export class SqlitePersistence {
     }
     /** Aggregate routing effectiveness: { decision: { total, successful } } */
     aggregateRoutingEffectiveness() {
-        const rows = this.db.prepare(`
+        const rows = this.db
+            .prepare(`
       SELECT routing_decision, COUNT(*) as total, SUM(outcome_success) as successful
       FROM meta_observations
       GROUP BY routing_decision
-    `).all();
+    `)
+            .all();
         const result = {};
         for (const row of rows) {
             result[row.routing_decision] = { total: row.total, successful: row.successful };
@@ -531,13 +1149,386 @@ export class SqlitePersistence {
         if (setClauses.length === 0)
             return;
         values.push(id);
-        this.db.prepare(`UPDATE meta_strategies SET ${setClauses.join(', ')} WHERE id = ?`).run(...values);
+        this.db
+            .prepare(`UPDATE meta_strategies SET ${setClauses.join(', ')} WHERE id = ?`)
+            .run(...values);
     }
     deleteMetaStrategy(id) {
         const result = this.stmt('delete_meta_strategy', 'DELETE FROM meta_strategies WHERE id = ?').run(id);
         return result.changes > 0;
     }
     // ==========================================================================
+    // Dream queue (Phase A: durable backlog for offline consolidation)
+    //
+    // Write + inspect only. The claim/lease/reclaim consumer is added in a later
+    // phase; for now this dual-writes alongside the in-memory accumulator.
+    // ==========================================================================
+    /**
+     * Enqueue a trajectory for offline consolidation. Idempotent by
+     * `trajectory_id` (INSERT OR IGNORE against the UNIQUE constraint), so
+     * enqueuing the same trajectory twice is a no-op. Returns the generated
+     * row id (a fresh uuid even when the insert is ignored).
+     */
+    enqueueDreamRow(entry) {
+        const id = randomUUID();
+        const res = this.stmt('enqueue_dream_row', `
+      INSERT OR IGNORE INTO dream_queue
+        (id, trajectory_id, trajectory_json, routing_json, source, status, enqueued_at)
+      VALUES (?, ?, ?, ?, ?, 'pending', ?)
+    `).run(id, entry.trajectoryId, entry.trajectoryJson, entry.routingJson ?? null, entry.source ?? 'pipeline', new Date().toISOString());
+        // On a dedup conflict (existing trajectory_id) nothing is inserted — return
+        // the EXISTING row's id, not the unused one we generated, so the returned id
+        // always names a real row.
+        if (res.changes === 1)
+            return id;
+        const existing = this.stmt('dream_row_id_by_trajectory', `SELECT id FROM dream_queue WHERE trajectory_id = ?`).get(entry.trajectoryId);
+        return existing?.id ?? id;
+    }
+    /** Count rows still awaiting consolidation. */
+    countPendingDreamRows() {
+        const row = this.stmt('count_pending_dream_rows', `SELECT COUNT(*) AS n FROM dream_queue WHERE status = 'pending'`).get();
+        return row.n;
+    }
+    /**
+     * Enqueue time of the oldest pending row — the staleness signal a cadence
+     * policy uses to decide when a dream is overdue. Undefined when empty.
+     */
+    getOldestPendingDreamEnqueuedAt() {
+        const row = this.stmt('oldest_pending_dream', `SELECT MIN(enqueued_at) AS oldest FROM dream_queue WHERE status = 'pending'`).get();
+        return fromISO(row.oldest);
+    }
+    /**
+     * Pending rows in enqueue order (oldest first). Ties on `enqueued_at`
+     * (same-millisecond inserts) break on `rowid`, which SQLite increments in
+     * insertion order — so the order is the true chronological enqueue order
+     * the drain consumer needs, not uuid-random.
+     */
+    peekPendingDreamRows(limit = 100) {
+        return this.stmt('peek_pending_dream_rows', `
+      SELECT * FROM dream_queue
+      WHERE status = 'pending'
+      ORDER BY rowid ASC
+      LIMIT ?
+    `).all(limit);
+    }
+    /**
+     * Atomically claim up to `limit` pending rows for consolidation: flip them
+     * `pending → processing`, stamp the lease (owner + expiry), and bump
+     * `attempts`. Runs in a transaction so a concurrent claimer can't hand out
+     * the same row twice. Rows are claimed oldest-first (chronological drain).
+     */
+    claimDreamRows(limit, leaseOwner, leaseTtlMs) {
+        return this.transactionImmediate(() => {
+            const rows = this.stmt('claim_select', `
+        SELECT * FROM dream_queue
+        WHERE status = 'pending'
+        ORDER BY rowid ASC
+        LIMIT ?
+      `).all(limit);
+            if (rows.length === 0)
+                return [];
+            const expiresAt = new Date(Date.now() + leaseTtlMs).toISOString();
+            const upd = this.stmt('claim_update', `
+        UPDATE dream_queue
+        SET status = 'processing', lease_owner = ?, lease_expires_at = ?, attempts = attempts + 1
+        WHERE id = ? AND status = 'pending'
+      `);
+            const claimed = [];
+            for (const r of rows) {
+                if (upd.run(leaseOwner, expiresAt, r.id).changes === 1) {
+                    claimed.push({
+                        ...r,
+                        status: 'processing',
+                        lease_owner: leaseOwner,
+                        lease_expires_at: expiresAt,
+                        attempts: r.attempts + 1,
+                    });
+                }
+            }
+            return claimed;
+        });
+    }
+    /** Delete claimed rows after a successful dream. Returns rows removed. */
+    completeDreamRows(ids) {
+        if (ids.length === 0)
+            return 0;
+        const del = this.stmt('complete_dream_row', 'DELETE FROM dream_queue WHERE id = ?');
+        return this.transaction(() => {
+            let n = 0;
+            for (const id of ids)
+                n += del.run(id).changes;
+            return n;
+        });
+    }
+    /**
+     * Park rows as `failed` directly (e.g. corrupt/unparseable payloads that will
+     * never succeed on retry). Observable via getDreamQueueStats and excluded from
+     * future claims. Unlike releaseDreamRows, does NOT requeue.
+     */
+    failDreamRows(ids) {
+        if (ids.length === 0)
+            return 0;
+        const upd = this.stmt('fail_dream_row', `
+      UPDATE dream_queue
+      SET status = 'failed', lease_owner = NULL, lease_expires_at = NULL
+      WHERE id = ?
+    `);
+        return this.transaction(() => {
+            let n = 0;
+            for (const id of ids)
+                n += upd.run(id).changes;
+            return n;
+        });
+    }
+    /** Return claimed rows to `pending` after a recoverable error. */
+    releaseDreamRows(ids) {
+        if (ids.length === 0)
+            return 0;
+        const upd = this.stmt('release_dream_row', `
+      UPDATE dream_queue
+      SET status = 'pending', lease_owner = NULL, lease_expires_at = NULL
+      WHERE id = ?
+    `);
+        return this.transaction(() => {
+            let n = 0;
+            for (const id of ids)
+                n += upd.run(id).changes;
+            return n;
+        });
+    }
+    /**
+     * Recover rows orphaned by a crashed dreamer: `processing` rows whose lease
+     * has expired go back to `pending`, unless they have already been attempted
+     * `maxAttempts` times — those move to `failed` (poison-row guard). Returns
+     * counts of each.
+     */
+    reclaimExpiredDreamRows(maxAttempts = 3, now = new Date()) {
+        const iso = now.toISOString();
+        // Both updates in one IMMEDIATE transaction so a concurrent claimer can't
+        // slip a row in between the fail and reclaim passes.
+        return this.transactionImmediate(() => {
+            const failed = this.stmt('reclaim_fail', `
+        UPDATE dream_queue
+        SET status = 'failed', lease_owner = NULL, lease_expires_at = NULL
+        WHERE status = 'processing' AND lease_expires_at < ? AND attempts >= ?
+      `).run(iso, maxAttempts).changes;
+            const reclaimed = this.stmt('reclaim_pending', `
+        UPDATE dream_queue
+        SET status = 'pending', lease_owner = NULL, lease_expires_at = NULL
+        WHERE status = 'processing' AND lease_expires_at < ? AND attempts < ?
+      `).run(iso, maxAttempts).changes;
+            return { reclaimed, failed };
+        });
+    }
+    // ==========================================================================
+    // Filesystem cascade (§6.2): md change queue + content-hash index
+    //
+    // Durable backlog for reindex-on-edit. The watcher enqueues; FilesystemCascade
+    // drains. Single-process/single-drainer, so no lease/claim dance — pending
+    // rows are read, processed, then deleted (success) or parked 'error'.
+    // ==========================================================================
+    /**
+     * Enqueue a canonical-file change. Idempotent per `path`: re-enqueuing the
+     * same file overwrites the pending row (last op wins) and re-arms it to
+     * `pending`, so a burst of editor writes coalesces to one drain unit.
+     */
+    enqueueMdChange(entry) {
+        const id = randomUUID();
+        this.stmt('enqueue_md_change', `
+      INSERT INTO md_change_queue (id, path, kind, op, status, enqueued_at, attempts)
+      VALUES (?, ?, ?, ?, 'pending', ?, 0)
+      ON CONFLICT(path) DO UPDATE SET
+        op          = excluded.op,
+        kind        = excluded.kind,
+        status      = 'pending',
+        enqueued_at = excluded.enqueued_at
+    `).run(id, entry.path, entry.kind, entry.op, new Date().toISOString());
+        const row = this.stmt('md_change_id_by_path', `SELECT id FROM md_change_queue WHERE path = ?`).get(entry.path);
+        return row?.id ?? id;
+    }
+    /** Pending change rows in enqueue order (oldest first). */
+    peekPendingMdChanges(limit = 500) {
+        return this.stmt('peek_pending_md_changes', `
+      SELECT * FROM md_change_queue
+      WHERE status = 'pending'
+      ORDER BY rowid ASC
+      LIMIT ?
+    `).all(limit);
+    }
+    countPendingMdChanges() {
+        const row = this.stmt('count_pending_md_changes', `SELECT COUNT(*) AS n FROM md_change_queue WHERE status = 'pending'`).get();
+        return row.n;
+    }
+    /** Delete a change row after it drains successfully (or is a no-op). */
+    completeMdChange(id) {
+        this.stmt('complete_md_change', 'DELETE FROM md_change_queue WHERE id = ?').run(id);
+    }
+    /**
+     * Record a drain failure. Increments `attempts`; parks the row as terminal
+     * `error` once it has been tried `maxAttempts` times (poison-file guard),
+     * otherwise leaves it `pending` for the next event-triggered drain.
+     */
+    failMdChange(id, error, maxAttempts = 5) {
+        this.stmt('fail_md_change', `
+      UPDATE md_change_queue
+      SET attempts   = attempts + 1,
+          last_error = ?,
+          status     = CASE WHEN attempts + 1 >= ? THEN 'error' ELSE 'pending' END
+      WHERE id = ?
+    `).run(error, maxAttempts, id);
+    }
+    getMdFileIndex(path) {
+        return this.stmt('get_md_file_index', `SELECT * FROM md_file_index WHERE path = ?`).get(path);
+    }
+    setMdFileIndex(entry) {
+        this.stmt('set_md_file_index', `
+      INSERT INTO md_file_index (path, content_hash, entity_id, indexed_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET
+        content_hash = excluded.content_hash,
+        entity_id    = excluded.entity_id,
+        indexed_at   = excluded.indexed_at
+    `).run(entry.path, entry.contentHash, entry.entityId ?? null, new Date().toISOString());
+    }
+    deleteMdFileIndex(path) {
+        this.stmt('delete_md_file_index', 'DELETE FROM md_file_index WHERE path = ?').run(path);
+    }
+    /** Row counts by status, for observability. */
+    getDreamQueueStats() {
+        const row = this.stmt('dream_queue_stats', `
+      SELECT
+        SUM(CASE WHEN status = 'pending'    THEN 1 ELSE 0 END) AS pending,
+        SUM(CASE WHEN status = 'processing' THEN 1 ELSE 0 END) AS processing,
+        SUM(CASE WHEN status = 'failed'     THEN 1 ELSE 0 END) AS failed
+      FROM dream_queue
+    `).get();
+        return {
+            pending: row.pending ?? 0,
+            processing: row.processing ?? 0,
+            failed: row.failed ?? 0,
+        };
+    }
+    // ── Dead-letter: inspect / requeue / purge `failed` rows ──────────────────
+    /** List parked (`failed`) rows for inspection, oldest first. */
+    getFailedDreamRows(limit = 100) {
+        return this.stmt('failed_dream_rows', `
+      SELECT * FROM dream_queue
+      WHERE status = 'failed'
+      ORDER BY rowid ASC
+      LIMIT ?
+    `).all(limit);
+    }
+    /**
+     * Requeue all `failed` rows back to `pending` with a fresh attempts counter —
+     * for retrying transient failures after the underlying cause is fixed. (Rows
+     * that fail deterministically, e.g. corrupt JSON, will simply re-park on the
+     * next dream; use `purgeFailedDreamRows` for those.) Returns rows requeued.
+     */
+    requeueFailedDreamRows() {
+        return this.stmt('requeue_failed_dream', `
+      UPDATE dream_queue
+      SET status = 'pending', attempts = 0, lease_owner = NULL, lease_expires_at = NULL
+      WHERE status = 'failed'
+    `).run().changes;
+    }
+    /** Permanently delete all `failed` rows (corrupt/unrecoverable). Returns count. */
+    purgeFailedDreamRows() {
+        return this.stmt('purge_failed_dream', `
+      DELETE FROM dream_queue WHERE status = 'failed'
+    `).run().changes;
+    }
+    /**
+     * Try to acquire the singleton cross-process dream lock. Returns true if the
+     * caller now holds it (no current holder, or the prior lease expired). Lets an
+     * in-process scheduler and a separate `dream` process avoid dreaming at once.
+     * The row-claim transaction already prevents two dreamers from claiming the
+     * same rows; this additionally avoids wasteful concurrent dreams and
+     * maintenance races. Compare-and-set runs in a transaction for atomicity.
+     */
+    acquireDreamLock(owner, ttlMs, now = new Date()) {
+        return this.transactionImmediate(() => {
+            const cur = this.getSystemState('dream_lock');
+            // Blocked only by a *different* owner whose lease is still live; the
+            // current holder may re-acquire to refresh its lease (heartbeat).
+            if (cur && cur.owner !== owner && new Date(cur.expiresAt).getTime() > now.getTime()) {
+                return false;
+            }
+            this.setSystemState('dream_lock', {
+                owner,
+                expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+            });
+            return true;
+        });
+    }
+    /**
+     * Release the dream lock if held by `owner` (no-op otherwise). Single atomic
+     * conditional DELETE so a late releaser can't stomp a successor's lock that
+     * was acquired after this owner's lease expired.
+     */
+    releaseDreamLock(owner) {
+        this.stmt('release_dream_lock', `
+      DELETE FROM system_state
+      WHERE key = 'dream_lock' AND json_extract(value, '$.owner') = ?
+    `).run(owner);
+    }
+    // ==========================================================================
+    // Distillation Cache (PR-D1)
+    // ==========================================================================
+    /**
+     * Look up a cached distillation result by cache_key.
+     * Returns undefined on miss or when persistence is not initialized.
+     */
+    getDistillationCache(cacheKey) {
+        const row = this.stmt('get_distillation_cache', 'SELECT cache_key, playbook_json, created_at FROM distillation_cache WHERE cache_key = ?').get(cacheKey);
+        return row ?? undefined;
+    }
+    /**
+     * Store a distillation result. INSERT OR REPLACE so a re-distillation
+     * (e.g. after a prompt-version bump invalidating a stale entry) wins.
+     */
+    setDistillationCache(entry) {
+        this.stmt('set_distillation_cache', `INSERT OR REPLACE INTO distillation_cache (cache_key, playbook_json, created_at)
+       VALUES (?, ?, ?)`).run(entry.cache_key, entry.playbook_json, entry.created_at);
+    }
+    // ==========================================================================
+    // Lift registry (production rollup — dream-time, write-only)
+    // ==========================================================================
+    /**
+     * Fold one trajectory's outcome into its lift cell. One call = one
+     * observation, so counters (and `runs`) increment by 1 — in the production
+     * scope `runs` therefore equals total observations, unlike eval scopes
+     * where a run is an ingested artifact. Cheap single upsert: safe for the
+     * dream path.
+     */
+    recordLiftOutcome(input) {
+        this.stmt('record_lift_outcome', `
+      INSERT INTO lift_cells
+        (scope, family, solver, guided_attempts, guided_successes,
+         unguided_attempts, unguided_successes, runs, updated_at)
+      VALUES (@scope, @family, @solver, @ga, @gs, @ua, @us, 1, @now)
+      ON CONFLICT(scope, family, solver) DO UPDATE SET
+        guided_attempts    = guided_attempts + @ga,
+        guided_successes   = guided_successes + @gs,
+        unguided_attempts  = unguided_attempts + @ua,
+        unguided_successes = unguided_successes + @us,
+        runs               = runs + 1,
+        updated_at         = @now
+    `).run({
+            scope: input.scope,
+            family: input.family,
+            solver: input.solver,
+            ga: input.guided ? 1 : 0,
+            gs: input.guided && input.success ? 1 : 0,
+            ua: input.guided ? 0 : 1,
+            us: !input.guided && input.success ? 1 : 0,
+            now: new Date().toISOString(),
+        });
+    }
+    /** All lift cells (for the lift report / tests). */
+    getLiftCells() {
+        return this.stmt('get_lift_cells', 'SELECT * FROM lift_cells ORDER BY scope, family, solver').all();
+    }
+    // ==========================================================================
     // System State (key-value store for singleton blobs)
     // ==========================================================================
     getSystemState(key) {