cognitive-core 0.2.5 → 0.3.1

package/dist/memory/playbook.js

@@ -8,16 +8,52 @@
 import { createPlaybook, bumpPlaybookVersion } from '../types/index.js';
 import { fromJSON, blobToEmbedding, fromISO } from '../persistence/index.js';
 import { InvertedIndex } from '../embeddings/inverted-index.js';
-import { textSimilarity } from '../utils/similarity.js';
+import { textSimilarity, cosineSimilarity } from '../utils/similarity.js';
+import { playbookHash } from '../utils/playbook-hash.js';
+import { rowToExperience } from './experience.js';
 import { getCandidates } from './candidate-retrieval.js';
+import { convertPlaybookToSkill } from '../surfacing/skill-publisher.js';
+import { scoreSkillsHybrid, } from 'skill-tree';
 /**
  * Build the indexable text for a playbook (situations + triggers concatenated)
  */
 function playbookIndexText(playbook) {
-    return [
-        ...playbook.applicability.situations,
-        ...playbook.applicability.triggers,
-    ].join(' ');
+    return [...playbook.applicability.situations, ...playbook.applicability.triggers].join(' ');
+}
+/**
+ * ADDITIVE LEARNING — over-merge guard. Two playbooks are domain-compatible
+ * when they share at least one (case-insensitive) domain, OR when at least one
+ * declares no domains (so we can't gate and fall back to similarity alone).
+ * Distinct, fully-declared, non-overlapping domains are NEVER merged.
+ */
+function domainsCompatible(a, b) {
+    const da = a.applicability.domains.map((d) => d.toLowerCase().trim()).filter(Boolean);
+    const db = b.applicability.domains.map((d) => d.toLowerCase().trim()).filter(Boolean);
+    if (da.length === 0 || db.length === 0)
+        return true;
+    const setA = new Set(da);
+    return db.some((d) => setA.has(d));
+}
+/**
+ * ADDITIVE LEARNING — embeddings-optional similarity used to decide whether a
+ * freshly distilled playbook should REFINE an existing one instead of minting a
+ * new row. Cosine over embeddings when BOTH have them (semantic); otherwise a
+ * lexical blend of 0.6 * best situation textSimilarity + 0.4 * strategy
+ * textSimilarity (mirrors PlaybookExtractor.consolidate). The lexical branch is
+ * the one the eval path exercises, since it defaults to embedProvider:'none'.
+ */
+function playbookRefineSimilarity(a, b) {
+    if (a.embedding && b.embedding) {
+        return cosineSimilarity(a.embedding, b.embedding);
+    }
+    let maxSituationSim = 0;
+    for (const sA of a.applicability.situations) {
+        for (const sB of b.applicability.situations) {
+            maxSituationSim = Math.max(maxSituationSim, textSimilarity(sA, sB));
+        }
+    }
+    const strategySim = textSimilarity(a.guidance.strategy, b.guidance.strategy);
+    return maxSituationSim * 0.6 + strategySim * 0.4;
 }
 /**
  * Convert a PlaybookRow (SQLite representation) back to a Playbook (domain type).
@@ -31,7 +67,12 @@ function rowToPlaybook(row) {
         confidence: row.confidence,
         complexity: row.complexity,
         estimatedEffort: row.estimated_effort,
-        applicability: fromJSON(row.applicability, { situations: [], triggers: [], antiPatterns: [], domains: [] }),
+        applicability: fromJSON(row.applicability, {
+            situations: [],
+            triggers: [],
+            antiPatterns: [],
+            domains: [],
+        }),
         guidance: fromJSON(row.guidance, { strategy: '', tactics: [] }),
         verification: fromJSON(row.verification, { successIndicators: [], failureIndicators: [] }),
         evolution: {
@@ -45,16 +86,41 @@ function rowToPlaybook(row) {
             consolidationStrength: evolution.consolidationStrength,
             domainBreadth: evolution.domainBreadth,
         },
-        provenance: (provenance && Object.keys(provenance).length > 0) ? {
-            origin: (provenance.origin ?? row.origin ?? 'extracted'),
-            sourceFile: provenance.sourceFile,
-            importedFrom: provenance.importedFrom,
-            curatedBy: provenance.curatedBy,
-            recordedAt: provenance.recordedAt ? new Date(provenance.recordedAt) : new Date(),
-        } : undefined,
+        provenance: provenance && Object.keys(provenance).length > 0
+            ? {
+                origin: (provenance.origin ?? row.origin ?? 'extracted'),
+                extractionMethod: provenance.extractionMethod,
+                fallbackReason: provenance.fallbackReason,
+                template: provenance.template,
+                templateVersion: provenance.templateVersion,
+                sourceFile: provenance.sourceFile,
+                importedFrom: provenance.importedFrom,
+                curatedBy: provenance.curatedBy,
+                recordedAt: provenance.recordedAt
+                    ? new Date(provenance.recordedAt)
+                    : new Date(),
+                creationCostUsd: provenance.creationCostUsd,
+            }
+            : undefined,
         embedding: blobToEmbedding(row.embedding),
         createdAt: fromISO(row.created_at) ?? new Date(),
         updatedAt: fromISO(row.updated_at) ?? new Date(),
+        parentPlaybookId: row.parent_playbook_id ?? undefined,
+    };
+}
+/**
+ * Text to embed for a playbook (situations + triggers concatenated — same as the index key).
+ */
+function playbookEmbedText(playbook) {
+    return [...playbook.applicability.situations, ...playbook.applicability.triggers].join(' ');
+}
+function skillTreeEmbedderFrom(provider) {
+    if (!provider)
+        return undefined;
+    return {
+        async embed(texts) {
+            return provider.embedBatch(texts);
+        },
     };
 }
 /**
@@ -65,6 +131,40 @@ export class PlaybookLibrary {
     _index = new InvertedIndex();
     initialized = false;
     _resolver;
+    /** Optional embedding provider — when set, findMatching scores by vector cosine
+     * (semantic) instead of lexical textSimilarity. Embed on add so the vector is
+     * stored alongside the playbook row. Pass null to revert to lexical. */
+    embedder = null;
+    /** When true, force lexical scoring even if an embedder is attached (ablation). */
+    _forceLexical = false;
+    /** Near-dup merge threshold (cosine). 0 = disabled. */
+    _mergeThreshold = 0.92;
+    /** Whether write-time curation (near-dup merge) is enabled. */
+    _curationEnabled = true;
+    /** Minimum evidence (successCount+failureCount) before prune eligibility. */
+    _pruneMinEvidence = 3;
+    /**
+     * F2: When true and an embedder is attached, anti-pattern exclusion uses
+     * embedding cosine similarity instead of lexical textSimilarity.
+     * Default true.  Set false to revert to old lexical guard (ablation).
+     */
+    _semanticAntiPatterns = true;
+    /** Optional Phase 3 writer for stable procedural-memory SKILL.md files. */
+    _structuralWriter = null;
+    /**
+     * F2: Cosine threshold above which a query is considered to match an
+     * anti-pattern (and the playbook is excluded).  Default 0.6.
+     * Semantic cosine scores are denser than lexical textSimilarity scores,
+     * so the threshold is lower than the lexical 0.7 guard.
+     */
+    _semanticAntiPatternThreshold = 0.6;
+    /**
+     * F2: In-memory cache of anti-pattern embeddings keyed by playbook id.
+     * Populated lazily on first retrieval and reused across queries.
+     * Key: `${playbookId}::${antiPatternIndex}` → embedding vector.
+     * Avoids re-embedding the same anti-pattern strings on every query.
+     */
+    _antiPatternEmbeddingCache = new Map();
     constructor(persistence) {
         this.persistence = persistence;
         this._resolver = {
@@ -75,6 +175,93 @@ export class PlaybookLibrary {
             values: () => this.getAllSync(),
         };
     }
+    /**
+     * Attach a semantic embedding provider. When set, `findMatching` scores
+     * candidates by vector cosine instead of lexical textSimilarity, and new
+     * playbooks are embedded on `add()`.  Pass null to revert to lexical.
+     */
+    setEmbeddingProvider(provider) {
+        this.embedder = provider;
+    }
+    /**
+     * When true, force lexical scoring (Jaccard+trigram) even when an embedder
+     * is attached — corresponds to the `features.lexicalRetrieval` ablation flag.
+     */
+    setForceLexical(force) {
+        this._forceLexical = force;
+    }
+    /**
+     * True when retrieval scores candidates by embedding cosine (an embedder is
+     * attached and lexical scoring is not forced). Callers use this to pick the
+     * right relevance floor — semantic cosine scores are denser than lexical, so
+     * they tolerate (and require) a higher minScore. See PlaybookRetrievalConfig.
+     */
+    isSemanticScoring() {
+        return this.embedder !== null && !this._forceLexical;
+    }
+    /**
+     * F2: Configure semantic anti-pattern exclusion.
+     *
+     * @param enabled - When true (default), anti-pattern exclusion uses embedding
+     *   cosine similarity when an embedder is attached.  When false, falls back to
+     *   lexical textSimilarity > 0.7 (old behavior, ablation arm).
+     * @param threshold - Cosine similarity threshold above which a query matches
+     *   an anti-pattern and the playbook is excluded.  Default 0.6.  Lower than
+     *   the lexical 0.7 guard because semantic cosine scores are denser.
+     */
+    setSemanticAntiPatterns(enabled, threshold) {
+        this._semanticAntiPatterns = enabled;
+        if (threshold !== undefined)
+            this._semanticAntiPatternThreshold = threshold;
+        // Clear the embedding cache when settings change so stale vectors are dropped.
+        this._antiPatternEmbeddingCache.clear();
+    }
+    setStructuralWriter(writer) {
+        this._structuralWriter = writer;
+    }
+    async writeStructural(playbook) {
+        if (!this._structuralWriter)
+            return;
+        await this._structuralWriter.write(playbook);
+        await this._structuralWriter.writeState(playbook);
+    }
+    /**
+     * Persist the rebuildable operational-state sidecar after a counter/confidence
+     * mutation (recordSuccess/Failure/recordApplicationOutcome). Non-fatal: SQLite
+     * stays canonical for ops state until the next reindex. No-op outside
+     * filesystem/dual-write mode (no structural writer attached).
+     */
+    async writeStateStructural(playbook) {
+        if (!this._structuralWriter)
+            return;
+        try {
+            await this._structuralWriter.writeState(playbook);
+        }
+        catch {
+            // Sidecar write failed — SQLite remains the source of truth for ops state.
+        }
+    }
+    async deleteStructural(playbook) {
+        if (!this._structuralWriter)
+            return;
+        await this._structuralWriter.delete(playbook);
+    }
+    /**
+     * Configure write-time curation (PR-D2).
+     *
+     * @param enabled - When false, add() always appends (append-only ablation).
+     * @param mergeThreshold - Cosine similarity above which two playbooks are
+     *   treated as near-duplicates and merged (default 0.92).
+     * @param pruneMinEvidence - Minimum (successCount + failureCount) before a
+     *   playbook is eligible for harm-pruning (default 3).
+     */
+    setCurationConfig(opts) {
+        this._curationEnabled = opts.enabled;
+        if (opts.mergeThreshold !== undefined)
+            this._mergeThreshold = opts.mergeThreshold;
+        if (opts.pruneMinEvidence !== undefined)
+            this._pruneMinEvidence = opts.pruneMinEvidence;
+    }
     async init() {
         if (this.initialized)
             return;
@@ -89,21 +276,41 @@ export class PlaybookLibrary {
     }
     // === RETRIEVAL ===
     /**
-     * Find playbooks matching a context
-     * Uses inverted index for candidate narrowing, then weighted scoring
-     * across situations, triggers, and anti-patterns.
+     * Find playbooks matching a context.
+     *
+     * Scoring path:
+     *   - When an embedding provider is attached AND `_forceLexical` is false
+     *     (the semantic path): embed the query + lazily embed any playbook that
+     *     lacks a stored vector, then score by cosine similarity. The InvertedIndex
+     *     is used only as a pre-filter candidate-narrowing step; when it returns
+     *     nothing a full-scan fallback is used so semantic retrieval is never
+     *     blocked by lexical index misses.
+     *   - Otherwise (lexical path): score by Jaccard+trigram textSimilarity as
+     *     before. This is the ablation path (`features.lexicalRetrieval: true`)
+     *     and the no-provider fallback.
      */
     async findMatching(context, options) {
         await this.init();
         const k = options?.k ?? 5;
-        // Get candidate pool
-        const domainFallback = (options?.domains && options.domains.length > 0)
+        const useEmbedding = this.embedder !== null && !this._forceLexical;
+        // Get candidate pool.
+        // Semantic path: do NOT let the lexical InvertedIndex cap candidates — we
+        // need the full set so cosine can find semantically-near items even when
+        // they share no tokens with the query. Use domain fallback or full scan.
+        const domainFallback = options?.domains && options.domains.length > 0
             ? [
                 ...options.domains.flatMap((d) => this.persistence.getPlaybooksByDomain(d).map(rowToPlaybook)),
                 ...this.persistence.getPlaybooksByDomain('_global').map(rowToPlaybook),
             ]
             : undefined;
-        let playbooks = getCandidates(context, this._index, this._resolver, { k }, domainFallback);
+        let playbooks;
+        if (useEmbedding) {
+            // Full scan (or domain slice) so semantic retrieval can reach any playbook.
+            playbooks = domainFallback ?? this.getAllSync();
+        }
+        else {
+            playbooks = getCandidates(context, this._index, this._resolver, { k }, domainFallback);
+        }
         // Filter by domains if specified (for cases where index returned cross-domain)
         if (options?.domains && options.domains.length > 0) {
             playbooks = playbooks.filter((p) => p.applicability.domains.some((d) => options.domains.includes(d)));
@@ -112,32 +319,80 @@ export class PlaybookLibrary {
         if (options?.minConfidence !== undefined) {
             playbooks = playbooks.filter((p) => p.confidence >= options.minConfidence);
         }
+        // Embed the query once (semantic path only).
+        let queryVec;
+        if (useEmbedding && this.embedder) {
+            queryVec = await this.embedder.embed(context);
+        }
         // Score playbooks
         const scored = [];
         for (const playbook of playbooks) {
-            // Check anti-patterns first (if enabled)
-            if (options?.excludeAntiPatterns !== false) {
-                const antiPatternMatch = playbook.applicability.antiPatterns.some((ap) => textSimilarity(context, ap) > 0.7);
-                if (antiPatternMatch)
-                    continue;
+            let score;
+            let matchType = 'situation';
+            if (useEmbedding && queryVec && this.embedder) {
+                // F2: Anti-pattern exclusion via embedding cosine when semantic mode is on.
+                if (options?.excludeAntiPatterns !== false &&
+                    playbook.applicability.antiPatterns.length > 0) {
+                    if (this._semanticAntiPatterns && this.embedder) {
+                        // Lazily embed each anti-pattern string and cache by playbook+index.
+                        let excluded = false;
+                        for (let apIdx = 0; apIdx < playbook.applicability.antiPatterns.length; apIdx++) {
+                            const cacheKey = `${playbook.id}::${apIdx}`;
+                            let apVec = this._antiPatternEmbeddingCache.get(cacheKey);
+                            if (!apVec) {
+                                apVec = await this.embedder.embed(playbook.applicability.antiPatterns[apIdx]);
+                                this._antiPatternEmbeddingCache.set(cacheKey, apVec);
+                            }
+                            if (cosineSimilarity(queryVec, apVec) > this._semanticAntiPatternThreshold) {
+                                excluded = true;
+                                break;
+                            }
+                        }
+                        if (excluded)
+                            continue;
+                    }
+                    else {
+                        // Lexical fallback (old behavior / ablation when semanticAntiPatterns=false).
+                        const antiPatternMatch = playbook.applicability.antiPatterns.some((ap) => textSimilarity(context, ap) > 0.7);
+                        if (antiPatternMatch)
+                            continue;
+                    }
+                }
+                // Lazily embed any playbook that was stored before the provider was
+                // attached (so we don't block init, only pay on first access).
+                if (!playbook.embedding) {
+                    playbook.embedding = await this.embedder.embed(playbookEmbedText(playbook));
+                    // Persist the newly-computed embedding for future runs.
+                    this.persistence.insertPlaybook(playbook);
+                }
+                score = playbook.embedding.length > 0 ? cosineSimilarity(queryVec, playbook.embedding) : 0;
+                if (score > 0) {
+                    scored.push({ playbook, score, matchType: 'situation', retrievalMethod: 'legacy' });
+                }
             }
-            // Score against situations
-            const situationScores = playbook.applicability.situations.map((s) => textSimilarity(context, s));
-            const maxSituationScore = situationScores.length > 0 ? Math.max(...situationScores) : 0;
-            // Score against triggers (weighted higher for exact matches)
-            const triggerScores = playbook.applicability.triggers.map((t) => textSimilarity(context, t));
-            const maxTriggerScore = triggerScores.length > 0 ? Math.max(...triggerScores) * 1.2 : 0;
-            // Combine scores
-            const score = Math.max(maxSituationScore, maxTriggerScore);
-            const matchType = maxTriggerScore > maxSituationScore ? 'trigger' : 'situation';
-            if (score > 0) {
-                scored.push({ playbook, score, matchType });
+            else {
+                // Lexical path (original behavior).
+                // Check anti-patterns first (if enabled)
+                if (options?.excludeAntiPatterns !== false) {
+                    const antiPatternMatch = playbook.applicability.antiPatterns.some((ap) => textSimilarity(context, ap) > 0.7);
+                    if (antiPatternMatch)
+                        continue;
+                }
+                // Score against situations
+                const situationScores = playbook.applicability.situations.map((s) => textSimilarity(context, s));
+                const maxSituationScore = situationScores.length > 0 ? Math.max(...situationScores) : 0;
+                // Score against triggers (weighted higher for exact matches)
+                const triggerScores = playbook.applicability.triggers.map((t) => textSimilarity(context, t));
+                const maxTriggerScore = triggerScores.length > 0 ? Math.max(...triggerScores) * 1.2 : 0;
+                score = Math.max(maxSituationScore, maxTriggerScore);
+                matchType = maxTriggerScore > maxSituationScore ? 'trigger' : 'situation';
+                if (score > 0) {
+                    scored.push({ playbook, score, matchType, retrievalMethod: 'legacy' });
+                }
             }
         }
         // Apply minimum score filter before ranking
-        const filtered = options?.minScore !== undefined
-            ? scored.filter((r) => r.score >= options.minScore)
-            : scored;
+        const filtered = options?.minScore !== undefined ? scored.filter((r) => r.score >= options.minScore) : scored;
         // Apply MMR diversity reranking or simple sort
         const lambda = options?.lambda;
         if (lambda !== undefined && lambda < 1.0) {
@@ -147,6 +402,54 @@ export class PlaybookLibrary {
         filtered.sort((a, b) => b.score - a.score);
         return filtered.slice(0, k);
     }
+    /**
+     * Find playbooks using skill-tree's tuned hybrid skill scorer.
+     *
+     * This treats playbooks as skill-tree Skills at retrieval time, without
+     * requiring playbooks to be published into skill-tree storage first. It gives
+     * the serving path access to skill-tree's body-indexed BM25 scorer, optional
+     * dense fusion, and calibrated [0,1] relevance scores.
+     */
+    async findMatchingSkillTreeHybrid(context, options) {
+        await this.init();
+        const k = options?.k ?? 5;
+        let playbooks = options?.domains && options.domains.length > 0
+            ? options.domains.flatMap((d) => this.persistence.getPlaybooksByDomain(d).map(rowToPlaybook))
+            : this.getAllSync();
+        if (options?.domains && options.domains.length > 0) {
+            playbooks = playbooks.filter((p) => p.applicability.domains.some((d) => options.domains.includes(d)));
+        }
+        if (options?.minConfidence !== undefined) {
+            playbooks = playbooks.filter((p) => p.confidence >= options.minConfidence);
+        }
+        if (options?.excludeAntiPatterns !== false) {
+            playbooks = playbooks.filter((p) => !p.applicability.antiPatterns.some((ap) => textSimilarity(context, ap) > 0.7));
+        }
+        if (playbooks.length === 0)
+            return [];
+        const playbookById = new Map(playbooks.map((p) => [p.id, p]));
+        const skills = playbooks.map(convertPlaybookToSkill);
+        const scored = await scoreSkillsHybrid(context, skills, {
+            embedder: skillTreeEmbedderFrom(this.embedder),
+            fusion: options?.fusion ?? 'rrf',
+        });
+        const filtered = options?.minScore !== undefined
+            ? scored.filter((r) => r.relevanceScore >= options.minScore)
+            : scored;
+        return filtered.slice(0, k).flatMap((item) => {
+            const playbook = playbookById.get(item.skill.id);
+            if (!playbook)
+                return [];
+            return [
+                {
+                    playbook,
+                    score: item.relevanceScore,
+                    matchType: 'situation',
+                    retrievalMethod: 'skill-tree-hybrid',
+                },
+            ];
+        });
+    }
     /**
      * Maximal Marginal Relevance reranking.
      * Selects top-k items balancing relevance and diversity.
@@ -218,6 +521,7 @@ export class PlaybookLibrary {
         }
         playbook.updatedAt = new Date();
         this.persistence.insertPlaybook(playbook); // Write-through (INSERT OR REPLACE)
+        await this.writeStateStructural(playbook);
     }
     /**
      * Record failure and capture context
@@ -251,6 +555,72 @@ export class PlaybookLibrary {
         playbook.confidence = Math.max(0.1, playbook.confidence - dampedDelta);
         playbook.updatedAt = new Date();
         this.persistence.insertPlaybook(playbook); // Write-through
+        await this.writeStateStructural(playbook);
+    }
+    /**
+     * F6: Injection-presence credit — update counters by INJECTION-PRESENCE +
+     * TASK OUTCOME, not by lexical usage detection.
+     *
+     * Instead of waiting for usage-inference to confirm a playbook was "used"
+     * (which fails for distilled playbooks whose abstract tactics never lexically
+     * match concrete actions), we attribute a fractional share of each task's
+     * outcome to every playbook that was injected, weighted by its retrieval
+     * score. Weights across all injected playbooks sum to 1 per task, so total
+     * credit per task = 1 distributed by relevance.
+     *
+     * Fractional counts interact correctly with downstream consumers:
+     *   - helpfulnessPrior: (successCount+1)/(successCount+failureCount+2) —
+     *     fractional inputs produce a valid probability; Laplace smoothing (+2)
+     *     keeps it out of the 0/1 corners even for tiny weights.
+     *   - pruneHarmful: failureCount >= successCount + minEvidence — fractional
+     *     threshold means a playbook accumulates evidence gradually; a
+     *     minEvidence=3 threshold needs ~3 tasks worth of failure-weight before
+     *     pruning fires, which is correct (3 fractional tasks = 3 real tasks at
+     *     weight 1).
+     *   - Confidence grows via weight-scaled damped delta (same formula as
+     *     recordSuccess / recordFailure but multiplied by weight), completing
+     *     F3: distilled playbooks born at 0.6-0.7 climb past the 0.7 router
+     *     gate after a few attributed successes.
+     *
+     * @param id - Playbook id
+     * @param success - Whether the task succeeded
+     * @param weight - Relevance share [0,1]; weights over all injected playbooks
+     *   should sum to 1. When weight = 0 this is a no-op.
+     */
+    async recordApplicationOutcome(id, success, weight) {
+        if (weight <= 0)
+            return;
+        await this.init();
+        const row = this.persistence.getPlaybook(id);
+        if (!row)
+            return;
+        const playbook = rowToPlaybook(row);
+        // Snapshot before mutation for version history
+        this.persistence.snapshotPlaybookVersion(id, playbook.evolution.version, success
+            ? `Injection-presence credit (success, weight=${weight.toFixed(3)})`
+            : `Injection-presence credit (failure, weight=${weight.toFixed(3)})`);
+        if (success) {
+            playbook.evolution.successCount += weight;
+            // Stability-plasticity: damped confidence increase, scaled by weight
+            const cs = playbook.evolution.consolidationStrength ?? 0;
+            const rawDelta = (1 - playbook.confidence) * 0.1;
+            const dampedDelta = (rawDelta / (1 + cs * 0.1)) * weight;
+            playbook.confidence = Math.min(0.99, playbook.confidence + dampedDelta);
+            // Grow consolidation strength (weight-scaled, same direction as recordSuccess)
+            playbook.evolution.consolidationStrength = Math.min(10, cs + 0.05 * weight);
+        }
+        else {
+            playbook.evolution.failureCount += weight;
+            // Stability-plasticity: damped confidence decrease, scaled by weight
+            const cs = playbook.evolution.consolidationStrength ?? 0;
+            const rawDelta = playbook.confidence * 0.15;
+            const dampedDelta = (rawDelta / (1 + cs * 0.2)) * weight;
+            playbook.confidence = Math.max(0.1, playbook.confidence - dampedDelta);
+        }
+        playbook.evolution.lastUsed = new Date();
+        playbook.updatedAt = new Date();
+        this.persistence.insertPlaybook(playbook); // Write-through (INSERT OR REPLACE)
+        await this.writeStateStructural(playbook);
     }
     /**
      * Add a context-specific refinement
@@ -276,6 +646,7 @@ export class PlaybookLibrary {
         playbook.evolution.version = bumpPlaybookVersion(playbook, 'patch');
         playbook.updatedAt = new Date();
         this.persistence.insertPlaybook(playbook); // Write-through
+        await this.writeStructural(playbook);
     }
     /**
      * Evolve playbook based on accumulated failures
@@ -303,16 +674,705 @@ export class PlaybookLibrary {
         this.persistence.insertPlaybook(playbook); // Write-through
         // Update index since applicability may have changed
         this._index.add(id, playbookIndexText(playbook));
+        await this.writeStructural(playbook);
         return playbook;
     }
+    // === FRONTIER (per-(signature, experience, playbook) Pareto bookkeeping) ===
+    /**
+     * Record an outcome on the Pareto frontier.
+     *
+     * For each (taskSignature, experienceId), the frontier tracks each
+     * playbook's *best* observed score. Multiple playbooks coexist on the
+     * frontier for the same (sig, exp) when they tie. The router uses this
+     * to preserve specialist playbooks that are good on a subset of work
+     * but mediocre on average.
+     */
+    async recordOutcomeOnSignature(playbookId, taskSignature, experienceId, score) {
+        await this.init();
+        this.persistence.upsertFrontierRow(taskSignature, experienceId, playbookId, score);
+    }
+    /**
+     * Record a live outcome: stamps both the Pareto frontier AND the eval
+     * cache (as `judged_by = 'live'`). Live writes take priority over
+     * llm-judge predictions, so any prior judge guess for this
+     * (playbook, experience) pair is superseded by ground truth.
+     *
+     * Use this from the hot path (instant loop) so the cache and frontier
+     * accumulate ground-truth observations as solves happen. Phase 2's
+     * acceptance gate will read from the cache without paying for judge
+     * calls when live data already exists.
+     *
+     * If `objectives` is provided, also writes one row per objective into
+     * the cartesian frontier (multi-objective Pareto). Caller-supplied
+     * objectives must follow the higher-is-better convention.
+     */
+    async recordLiveOutcome(playbookId, taskSignature, experienceId, score, objectives) {
+        await this.init();
+        this.persistence.upsertFrontierRow(taskSignature, experienceId, playbookId, score);
+        // Also write to the eval cache as a live observation. Needs the
+        // playbook's content hash, so we fetch and hash. Cheap (DB hit + SHA-256).
+        const row = this.persistence.getPlaybook(playbookId);
+        if (row) {
+            const hash = playbookHash(rowToPlaybook(row));
+            this.persistence.upsertEvalCache(hash, experienceId, score, 'live');
+        }
+        // Multi-objective frontier rows.
+        if (objectives) {
+            for (const [objective, objScore] of Object.entries(objectives)) {
+                this.persistence.upsertFrontierCartesianRow(taskSignature, experienceId, objective, playbookId, objScore);
+            }
+        }
+    }
+    /**
+     * Get all frontier rows for a signature.
+     */
+    async getFrontierForSignature(taskSignature) {
+        await this.init();
+        return this.persistence.getFrontierBySignature(taskSignature);
+    }
+    /**
+     * Get all frontier rows for a playbook, across every signature it
+     * participates in. An empty result means the playbook has no live
+     * frontier history yet (freshly-extracted or never-served) — callers
+     * that gate on dominance must treat "no frontier" as non-dominated to
+     * avoid deadlocking first-ever promotions.
+     */
+    async getFrontierForPlaybook(playbookId) {
+        await this.init();
+        return this.persistence.getFrontierByPlaybook(playbookId);
+    }
+    /**
+     * Get the dominator set: playbooks that survive Pareto dominance pruning
+     * across the (experience -> best playbooks) frontier for a signature.
+     *
+     * A playbook P is *dominated* if every (sig, exp) where P is on the
+     * frontier also has at least one non-dominated other playbook on the
+     * same frontier — i.e., P is never *uniquely* needed. Direct port of
+     * GEPA's `remove_dominated_programs` (gepa_utils.py:35-72), specialized
+     * to a single signature scope.
+     *
+     * Returns playbooks ranked by win frequency (descending). Used by the
+     * router to sample frontier members.
+     */
+    async getDominatorPlaybooks(opts) {
+        await this.init();
+        if (!opts.taskSignature) {
+            return [];
+        }
+        const rows = this.persistence.getFrontierBySignature(opts.taskSignature);
+        if (rows.length === 0)
+            return [];
+        // Build per-experience frontiers: experience_id -> set of playbook_ids
+        // at the top score on that experience.
+        const frontierByExp = new Map();
+        const topScoreByExp = new Map();
+        for (const row of rows) {
+            const prev = topScoreByExp.get(row.experience_id);
+            if (prev === undefined || row.score > prev) {
+                topScoreByExp.set(row.experience_id, row.score);
+                frontierByExp.set(row.experience_id, new Set([row.playbook_id]));
+            }
+            else if (row.score === prev) {
+                frontierByExp.get(row.experience_id).add(row.playbook_id);
+            }
+        }
+        const survivors = pruneDominated(frontierByExp);
+        return resolveFrontierMembers(survivors, frontierByExp, this.persistence, opts.domain);
+    }
+    /**
+     * Multi-objective variant of `getDominatorPlaybooks`. Computes
+     * dominance over the cartesian frontier (per-(exp, objective)) for
+     * a signature, restricted to a caller-supplied set of objectives.
+     *
+     * A playbook survives if, for some (experience, objective) pair, it
+     * is uniquely on the frontier OR no other surviving playbook covers
+     * all the pairs where it dominates. Direct port of
+     * `remove_dominated_programs` applied to the cartesian key space.
+     *
+     * `objectives` defaults to all objectives present in the cartesian
+     * frontier for this signature. Passing a subset narrows the dominance
+     * computation (e.g., `['cost']` for cost-only selection).
+     *
+     * Returns playbooks ranked by total (exp, objective) wins across the
+     * requested objectives.
+     */
+    async getDominatorPlaybooksMultiObjective(opts) {
+        await this.init();
+        const rows = this.persistence.getFrontierCartesianBySignature(opts.taskSignature);
+        if (rows.length === 0)
+            return [];
+        // Filter by requested objectives if specified.
+        const filtered = opts.objectives
+            ? rows.filter((r) => opts.objectives.includes(r.objective))
+            : rows;
+        if (filtered.length === 0)
+            return [];
+        // Build per-(exp, objective) frontier: key -> set of top-scoring playbooks
+        const frontierByKey = new Map();
+        const topScoreByKey = new Map();
+        for (const row of filtered) {
+            const key = `${row.experience_id}::${row.objective}`;
+            const prev = topScoreByKey.get(key);
+            if (prev === undefined || row.score > prev) {
+                topScoreByKey.set(key, row.score);
+                frontierByKey.set(key, new Set([row.playbook_id]));
+            }
+            else if (row.score === prev) {
+                frontierByKey.get(key).add(row.playbook_id);
+            }
+        }
+        const survivors = pruneDominated(frontierByKey);
+        return resolveFrontierMembers(survivors, frontierByKey, this.persistence, opts.domain);
+    }
+    /**
+     * How many (sig, exp) pairs does this playbook currently dominate?
+     * Deletion paths (consolidation, GC) should check this before removing
+     * a playbook — a playbook with `uniqueWins > 0` is a specialist that
+     * can't be reproduced by the surviving playbooks.
+     */
+    async getFrontierContribution(playbookId) {
+        await this.init();
+        return this.persistence.getFrontierContribution(playbookId);
+    }
+    /**
+     * Sample a minibatch of experiences for replay-based evaluation of
+     * a candidate mutation against this playbook.
+     *
+     * Two-stage strategy:
+     *   1. Frontier-first: take the most recent experiences where this
+     *      playbook has actually been scored (from `playbook_frontier`,
+     *      ranked by `recorded_at` desc). This is the GEPA-style "same
+     *      minibatch as the parent" semantics — the candidate is judged
+     *      on the workload the parent was already serving.
+     *   2. Fallback: if the playbook has no frontier history yet (typical
+     *      for freshly-extracted playbooks), use experiences linked to
+     *      its `evolution.createdFrom` trajectories.
+     *
+     * If `taskSignature` is provided, restricts stage 1 to rows on that
+     * signature only — the proper "same workload" semantics. Without it,
+     * stage 1 mixes signatures, which corrupts comparison.
+     *
+     * `poolAcrossSignatures` overrides that filter: when true, stage 1 uses
+     * the playbook's recent frontier rows ACROSS all `{domain}:{intent}`
+     * signatures even if `taskSignature` is supplied. This is the mutation
+     * GATE path (see MutationGate.propose): the frontier rows returned by
+     * `getFrontierByPlaybook` are ALREADY per-playbook, so every row is an
+     * application of THIS playbook and is inherently relevant regardless of
+     * task domain. A domain-general playbook's failure evidence otherwise
+     * shatters into ~1-per-signature buckets on real benchmarks (families
+     * like SkillFlow Cross-Format-Data-Reconciliation span retail-operations,
+     * cloud-finops, it-operations, … — many domains), which is always below
+     * `minMinibatchSize`, so the gate can never reach a real parent-vs-child
+     * comparison and always takes the sparse-minibatch auto-accept bypass.
+     * Pooling across signatures lets a playbook applied to ≥3 tasks reach a
+     * non-sparse minibatch. The recency sort keeps the newest applications,
+     * so pooling doesn't drag in stale evidence.
+     *
+     * Returns up to `k` experiences. Empty result means the caller should
+     * accept the mutation without a gate (no evidence either way).
+     */
+    async sampleMinibatchForPlaybook(playbookId, k = 5, taskSignature, poolAcrossSignatures = false) {
+        await this.init();
+        // Stage 1: recent frontier history (signature-filtered when provided,
+        // unless the caller opts into cross-signature pooling for the gate).
+        let frontierRows = this.persistence.getFrontierByPlaybook(playbookId);
+        if (taskSignature && !poolAcrossSignatures) {
+            frontierRows = frontierRows.filter((r) => r.task_signature === taskSignature);
+        }
+        if (frontierRows.length > 0) {
+            const sortedByRecency = [...frontierRows]
+                .sort((a, b) => b.recorded_at.localeCompare(a.recorded_at))
+                .slice(0, k);
+            const seen = new Set();
+            const experiences = [];
+            for (const row of sortedByRecency) {
+                if (seen.has(row.experience_id))
+                    continue;
+                seen.add(row.experience_id);
+                const expRow = this.persistence.getExperience(row.experience_id);
+                if (expRow)
+                    experiences.push(rowToExperience(expRow));
+                if (experiences.length >= k)
+                    break;
+            }
+            if (experiences.length > 0)
+                return experiences;
+        }
+        // Stage 2: fallback to createdFrom trajectories
+        const playbookRow = this.persistence.getPlaybook(playbookId);
+        if (!playbookRow)
+            return [];
+        const playbook = rowToPlaybook(playbookRow);
+        const trajectoryIds = playbook.evolution.createdFrom ?? [];
+        if (trajectoryIds.length === 0)
+            return [];
+        const seen = new Set();
+        const experiences = [];
+        for (const trajId of trajectoryIds) {
+            const expRows = this.persistence.getExperiencesByTrajectory(trajId);
+            for (const expRow of expRows) {
+                if (seen.has(expRow.id))
+                    continue;
+                seen.add(expRow.id);
+                experiences.push(rowToExperience(expRow));
+                if (experiences.length >= k)
+                    return experiences;
+            }
+        }
+        return experiences;
+    }
+    /**
+     * Sample a stratified minibatch for two-parent merge acceptance.
+     *
+     * GEPA's merge acceptance (proposer/merge.py:258-288) samples from
+     * three buckets where the two parents disagreed: where A scored
+     * higher, where B scored higher, and where they tied. This tests
+     * the merged child specifically on the workloads that motivated the
+     * merge — the disjoint wins that each parent uniquely had.
+     *
+     * Stratification considers ONLY experiences where both parents have
+     * recorded scores on `taskSignature` — head-to-head pairs. Lopsided
+     * experiences (only one parent scored) are excluded; without both
+     * scores there's no comparison to bucket on.
+     *
+     * Returns the picked experiences plus the parents' scores on each
+     * (so the caller doesn't need to re-look them up — they are ground
+     * truth from the frontier, no judge call needed).
+     */
+    async sampleMergeMinibatch(parentAId, parentBId, taskSignature, k = 6, rng = Math.random) {
+        await this.init();
+        const rows = this.persistence.getFrontierBySignature(taskSignature);
+        // Build (playbook, experience) -> score for both parents.
+        const aScores = new Map();
+        const bScores = new Map();
+        for (const r of rows) {
+            if (r.playbook_id === parentAId)
+                aScores.set(r.experience_id, r.score);
+            else if (r.playbook_id === parentBId)
+                bScores.set(r.experience_id, r.score);
+        }
+        // Bucket experiences scored by BOTH parents.
+        const aWins = [];
+        const bWins = [];
+        const tied = [];
+        for (const [expId, aScore] of aScores) {
+            const bScore = bScores.get(expId);
+            if (bScore === undefined)
+                continue;
+            if (aScore > bScore)
+                aWins.push(expId);
+            else if (bScore > aScore)
+                bWins.push(expId);
+            else
+                tied.push(expId);
+        }
+        // Shuffle each bucket so the picker doesn't deterministically take
+        // the head every cycle. Matches GEPA's random within-bucket sampling
+        // (merge.py:270-278) and gives variety to the minibatch when the
+        // merge proposer revisits the same triplet.
+        const shuffled = (xs) => fisherYatesShuffled(xs, rng);
+        const aShuf = shuffled(aWins);
+        const bShuf = shuffled(bWins);
+        const tShuf = shuffled(tied);
+        // Even share per bucket. Use ceil(k/3) to match GEPA's per-bucket
+        // count (merge.py:264-268) — the initial pick may exceed k, then
+        // the spillover loop trims excess.
+        const perBucket = Math.max(1, Math.ceil(k / 3));
+        const picked = new Set();
+        const pickFrom = (bucket, n) => {
+            for (const id of bucket.slice(0, n)) {
+                if (picked.size >= k)
+                    return;
+                picked.add(id);
+            }
+        };
+        pickFrom(aShuf, perBucket);
+        pickFrom(bShuf, perBucket);
+        pickFrom(tShuf, perBucket);
+        // Spillover: if any bucket was short, top up from the others until k.
+        // Bounded iteration count handles the case where all buckets are
+        // exhausted before reaching k.
+        const allBuckets = [aShuf, bShuf, tShuf];
+        let idx = 0;
+        let lastSize = picked.size;
+        while (picked.size < k && idx < allBuckets.length * 10) {
+            const bucket = allBuckets[idx % allBuckets.length];
+            for (const id of bucket) {
+                if (picked.size >= k)
+                    break;
+                picked.add(id);
+            }
+            idx++;
+            if (picked.size === lastSize && idx % allBuckets.length === 0)
+                break;
+            lastSize = picked.size;
+        }
+        const experiences = [];
+        for (const expId of picked) {
+            const expRow = this.persistence.getExperience(expId);
+            if (expRow)
+                experiences.push(rowToExperience(expRow));
+        }
+        const pickedSet = picked;
+        return {
+            experiences,
+            parentAScoreByExp: aScores,
+            parentBScoreByExp: bScores,
+            buckets: {
+                aWins: aWins.filter((id) => pickedSet.has(id)),
+                bWins: bWins.filter((id) => pickedSet.has(id)),
+                tied: tied.filter((id) => pickedSet.has(id)),
+            },
+        };
+    }
+    /**
+     * Get the content hash for a playbook (used as the eval-cache key).
+     * Convenience wrapper around `playbookHash()` for callers that don't
+     * want to import the utility directly.
+     */
+    hashOf(playbook) {
+        return playbookHash(playbook);
+    }
+    /**
+     * Frontier-aware variant of `findMatching`.
+     *
+     * When the task's signature has recorded outcomes, ranks dominator
+     * playbooks by their per-signature win count (Pareto sampling — direct
+     * port of GEPA's `select_program_candidate_from_pareto_front`,
+     * gepa_utils.py:90-117). Otherwise falls back to text-similarity
+     * matching (cold-start path).
+     *
+     * Returns a list of matches: the sampled dominator first, then other
+     * dominators by descending wins, then text-similarity matches to fill
+     * to `k`. Score is normalized so the sampled dominator gets 1.0.
+     */
+    async findMatchingFrontierAware(context, taskSignature, options) {
+        await this.init();
+        const k = options?.k ?? 5;
+        const prefer = options?.prefer ?? 'best';
+        const dominators = prefer === 'best'
+            ? await this.getDominatorPlaybooks({
+                taskSignature,
+                domain: options?.domains?.[0],
+            })
+            : await this.getDominatorPlaybooksMultiObjective({
+                taskSignature,
+                objectives: resolvePreferenceObjectives(prefer),
+                domain: options?.domains?.[0],
+            });
+        if (dominators.length === 0) {
+            return this.findMatching(context, options);
+        }
+        // Weighted sample by totalWins. Mirrors gepa_utils.py:103-117:
+        // build a multiset where each dominator appears `totalWins` times,
+        // pick one uniformly at random. Equivalent to weighted sampling.
+        const rng = options?.rng ?? Math.random;
+        const totalWeight = dominators.reduce((s, m) => s + m.totalWins, 0);
+        const target = rng() * totalWeight;
+        let acc = 0;
+        let sampled = dominators[0];
+        for (const m of dominators) {
+            acc += m.totalWins;
+            if (acc >= target) {
+                sampled = m;
+                break;
+            }
+        }
+        const out = [];
+        const includedIds = new Set();
+        // Sampled dominator gets full score.
+        out.push({
+            playbook: sampled.playbook,
+            score: 1.0,
+            matchType: 'situation',
+            retrievalMethod: 'frontier',
+        });
+        includedIds.add(sampled.playbook.id);
+        // Other dominators ranked by wins (already sorted in getDominatorPlaybooks).
+        const sampledWins = sampled.totalWins || 1;
+        for (const m of dominators) {
+            if (includedIds.has(m.playbook.id))
+                continue;
+            if (out.length >= k)
+                break;
+            out.push({
+                playbook: m.playbook,
+                // Clamp below the sampled dominator's 1.0 — when a non-sampled
+                // dominator has more wins than the sampled one, the raw ratio
+                // exceeds 1.0 and corrupts downstream score-threshold checks.
+                score: Math.min(0.95, 0.7 * (m.totalWins / sampledWins)),
+                matchType: 'situation',
+                retrievalMethod: 'frontier',
+            });
+            includedIds.add(m.playbook.id);
+        }
+        // Fill remaining slots with text-similarity matches not already included.
+        if (out.length < k) {
+            const fillerOpts = {
+                ...options,
+                k: k + dominators.length, // overdraw to filter
+            };
+            const filler = await this.findMatching(context, fillerOpts);
+            for (const m of filler) {
+                if (includedIds.has(m.playbook.id))
+                    continue;
+                if (out.length >= k)
+                    break;
+                // Filler scores are lower than dominators by construction.
+                out.push({ ...m, score: Math.min(m.score, 0.5) });
+                includedIds.add(m.playbook.id);
+            }
+        }
+        return out.slice(0, k);
+    }
     // === LIFECYCLE ===
     /**
-     * Add a new playbook
+     * Add a new playbook. When curation is enabled and an embedding provider is
+     * attached, checks for a near-duplicate first (cosine > _mergeThreshold).
+     * If found, merges the incoming playbook into the existing one (union of
+     * triggers/tactics, higher-confidence strategy, appends createdFrom id) and
+     * returns the existing id. Otherwise inserts as normal.
+     *
+     * When curation is disabled (features.curation = false), always appends.
+     *
+     * Returns the id of the playbook that was ultimately stored (existing or new).
      */
     async add(playbook) {
         await this.init();
+        // Embed on store when a provider is attached and no embedding exists yet.
+        if (this.embedder && !playbook.embedding) {
+            playbook.embedding = await this.embedder.embed(playbookEmbedText(playbook));
+        }
+        // Near-dup merge (curation path).
+        if (this._curationEnabled && playbook.embedding && this.embedder) {
+            const dupId = await this._findNearDup(playbook);
+            if (dupId) {
+                await this._mergeInto(dupId, playbook);
+                return dupId;
+            }
+        }
+        await this.writeStructural(playbook);
+        this.persistence.insertPlaybook(playbook);
+        this._index.add(playbook.id, playbookIndexText(playbook));
+        return playbook.id;
+    }
+    /**
+     * Upsert a playbook parsed from a canonical procedural-memory file.
+     *
+     * This intentionally bypasses near-duplicate curation: reindexing from the
+     * filesystem must reproduce the canonical files, not reinterpret them as new
+     * learned candidates that may be merged away.
+     */
+    async upsertCanonical(playbook) {
+        await this.init();
+        if (this.embedder && !playbook.embedding) {
+            playbook.embedding = await this.embedder.embed(playbookEmbedText(playbook));
+        }
         this.persistence.insertPlaybook(playbook);
         this._index.add(playbook.id, playbookIndexText(playbook));
+        return playbook.id;
+    }
+    /**
+     * Drop a playbook's derived rows only — the delete-side counterpart of
+     * {@link upsertCanonical}. Unlike {@link delete}, this does NOT call the
+     * structural writer, so it is safe to invoke from a file-event handler
+     * reacting to a SKILL.md that was already removed on disk (the filesystem
+     * cascade): it removes the SQLite row + inverted-index entry without trying
+     * to re-delete the canonical file.
+     */
+    async removeCanonical(id) {
+        await this.init();
+        this._index.remove(id);
+        return this.persistence.deletePlaybook(id);
+    }
+    /**
+     * Scan for an existing playbook whose embedding cosine similarity to the
+     * candidate exceeds _mergeThreshold. Returns the best match id or null.
+     *
+     * Lexical fallback when no embedder: use textSimilarity on index text.
+     * The lexical threshold is scaled down proportionally (~0.80) since
+     * textSimilarity scores are sparser.
+     */
+    async _findNearDup(candidate) {
+        const candidateText = playbookIndexText(candidate);
+        const all = this.getAllSync();
+        let bestScore = 0;
+        let bestId = null;
+        for (const existing of all) {
+            if (existing.id === candidate.id)
+                continue;
+            let score;
+            if (candidate.embedding && existing.embedding) {
+                score = cosineSimilarity(candidate.embedding, existing.embedding);
+            }
+            else {
+                // Lexical fallback: adjust threshold to ~86% of cosine threshold
+                const lexicalThreshold = this._mergeThreshold * 0.86;
+                score = textSimilarity(candidateText, playbookIndexText(existing));
+                if (score < lexicalThreshold)
+                    continue;
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestId = existing.id;
+                }
+                continue;
+            }
+            if (score >= this._mergeThreshold && score > bestScore) {
+                bestScore = score;
+                bestId = existing.id;
+            }
+        }
+        return bestId;
+    }
+    /**
+     * Merge a new playbook's content into an existing one in-place:
+     *   - Union applicability.triggers (dedup)
+     *   - Union guidance.tactics (dedup)
+     *   - Keep the higher-confidence strategy
+     *   - Append the new playbook's first createdFrom id (if any)
+     *
+     * Does NOT bump successCount/failureCount — those are updated via
+     * recordSuccess/recordFailure from the usage-inference path.
+     */
+    async _mergeInto(existingId, incoming) {
+        const row = this.persistence.getPlaybook(existingId);
+        if (!row)
+            return;
+        const existing = rowToPlaybook(row);
+        // Union triggers
+        const mergedTriggers = Array.from(new Set([...existing.applicability.triggers, ...incoming.applicability.triggers]));
+        // Union tactics
+        const mergedTactics = Array.from(new Set([...existing.guidance.tactics, ...incoming.guidance.tactics]));
+        // Keep higher-confidence strategy
+        const strategy = incoming.confidence > existing.confidence
+            ? incoming.guidance.strategy
+            : existing.guidance.strategy;
+        // Append createdFrom ids (dedup)
+        const existingCreatedFrom = new Set(existing.evolution.createdFrom);
+        for (const srcId of incoming.evolution.createdFrom) {
+            existingCreatedFrom.add(srcId);
+        }
+        existing.applicability.triggers = mergedTriggers;
+        existing.guidance.tactics = mergedTactics;
+        existing.guidance.strategy = strategy;
+        existing.evolution.createdFrom = Array.from(existingCreatedFrom);
+        existing.updatedAt = new Date();
+        this.persistence.insertPlaybook(existing);
+        // Re-index with merged triggers
+        this._index.add(existing.id, playbookIndexText(existing));
+        await this.writeStructural(existing);
+    }
+    /**
+     * ADDITIVE LEARNING (flag-gated by callers) — find an existing playbook
+     * similar enough to `candidate` to REFINE INTO, WITHOUT requiring an
+     * embedding provider. Similarity is embeddings-optional (cosine when both
+     * embeddings exist, else lexical strategy+situation blend). A non-empty
+     * domain intersection is REQUIRED whenever both declare domains, guarding
+     * against cross-domain over-merge. Returns the best matching existing id
+     * with similarity ≥ `threshold`, or null.
+     *
+     * `opts.candidates` overrides the search pool (e.g. to also scan playbooks
+     * distilled earlier in the same batch that aren't in the library yet);
+     * `opts.excludeId` skips a specific id.
+     */
+    async findRefineTarget(candidate, threshold, opts) {
+        await this.init();
+        const pool = opts?.candidates ?? this.getAllSync();
+        let bestScore = 0;
+        let bestId = null;
+        for (const existing of pool) {
+            if (existing.id === candidate.id)
+                continue;
+            if (opts?.excludeId && existing.id === opts.excludeId)
+                continue;
+            if (!domainsCompatible(candidate, existing))
+                continue;
+            const score = playbookRefineSimilarity(candidate, existing);
+            if (score >= threshold && score > bestScore) {
+                bestScore = score;
+                bestId = existing.id;
+            }
+        }
+        return bestId;
+    }
+    /**
+     * ADDITIVE LEARNING — refine an existing playbook IN PLACE with a freshly
+     * distilled `incoming` one, instead of adding `incoming` as a new
+     * `distilled-<uuid>` row. This is how evidence COMPOUNDS onto one playbook:
+     *   - union situations / triggers / anti-patterns / domains / tactics
+     *   - keep the existing strategy (stable identity) + append a refinement note
+     *   - append incoming.createdFrom (dedup) — the compounding trajectory evidence
+     *   - accumulate success/failure counters
+     *   - BOUNDED confidence nudge (fraction of remaining headroom, capped 0.95),
+     *     never a raw max() — guards runaway inflation across repeated merges
+     *   - bump minor version; snapshot the prior version for history
+     * Returns the refined playbook, or undefined when `existingId` is unknown.
+     */
+    async refineWithDistilled(existingId, incoming) {
+        await this.init();
+        const row = this.persistence.getPlaybook(existingId);
+        if (!row)
+            return undefined;
+        const existing = rowToPlaybook(row);
+        this.persistence.snapshotPlaybookVersion(existingId, existing.evolution.version, 'Pre-additive-refine snapshot');
+        const union = (a, b) => Array.from(new Set([...a, ...b]));
+        existing.applicability.situations = union(existing.applicability.situations, incoming.applicability.situations);
+        existing.applicability.triggers = union(existing.applicability.triggers, incoming.applicability.triggers);
+        existing.applicability.antiPatterns = union(existing.applicability.antiPatterns, incoming.applicability.antiPatterns);
+        existing.applicability.domains = union(existing.applicability.domains, incoming.applicability.domains);
+        existing.guidance.tactics = union(existing.guidance.tactics, incoming.guidance.tactics);
+        existing.evolution.createdFrom = union(existing.evolution.createdFrom, incoming.evolution.createdFrom);
+        existing.evolution.successCount += incoming.evolution.successCount;
+        existing.evolution.failureCount += incoming.evolution.failureCount;
+        const positive = incoming.evolution.successCount >= incoming.evolution.failureCount;
+        existing.evolution.refinements = [
+            ...existing.evolution.refinements,
+            {
+                context: 'additive-consolidation',
+                addition: `Merged distilled trajectory(s): ${incoming.evolution.createdFrom.join(', ') || '(none)'}`,
+                source: positive ? 'success' : 'failure',
+                addedAt: new Date(),
+            },
+        ];
+        // Bounded confidence update — see docstring. Positive evidence moves 5% of
+        // the remaining headroom toward 1 (capped 0.95); failure-only nudges down.
+        if (positive) {
+            existing.confidence = Math.min(0.95, existing.confidence + 0.05 * (1 - existing.confidence));
+        }
+        else {
+            existing.confidence = Math.max(0, existing.confidence - 0.05 * existing.confidence);
+        }
+        existing.evolution.version = bumpPlaybookVersion(existing, 'minor');
+        existing.updatedAt = new Date();
+        this.persistence.insertPlaybook(existing);
+        this._index.add(existing.id, playbookIndexText(existing));
+        await this.writeStructural(existing);
+        return existing;
+    }
+    /**
+     * Prune (delete) playbooks where failureCount >= successCount + minEvidence,
+     * ensuring at least minEvidence observations exist so zero/low-count noise
+     * never triggers pruning. Gated on features.curation.
+     *
+     * Returns the ids of pruned playbooks.
+     */
+    async pruneHarmful(minEvidence) {
+        await this.init();
+        if (!this._curationEnabled)
+            return [];
+        const threshold = minEvidence ?? this._pruneMinEvidence;
+        const pruned = [];
+        for (const playbook of this.getAllSync()) {
+            const { successCount, failureCount } = playbook.evolution;
+            const total = successCount + failureCount;
+            if (total < threshold)
+                continue; // insufficient evidence
+            if (failureCount >= successCount + threshold) {
+                await this.delete(playbook.id);
+                pruned.push(playbook.id);
+            }
+        }
+        return pruned;
     }
     /**
      * Create and add a new playbook
@@ -372,10 +1432,8 @@ export class PlaybookLibrary {
         return this.getAllSync()
             .filter((p) => p.evolution.successCount + p.evolution.failureCount >= 3)
             .sort((a, b) => {
-            const rateA = a.evolution.successCount /
-                (a.evolution.successCount + a.evolution.failureCount);
-            const rateB = b.evolution.successCount /
-                (b.evolution.successCount + b.evolution.failureCount);
+            const rateA = a.evolution.successCount / (a.evolution.successCount + a.evolution.failureCount);
+            const rateB = b.evolution.successCount / (b.evolution.successCount + b.evolution.failureCount);
             return rateB - rateA;
         })
             .slice(0, k);
@@ -399,8 +1457,14 @@ export class PlaybookLibrary {
      */
     async delete(id) {
         await this.init();
+        const row = this.persistence.getPlaybook(id);
+        const playbook = row ? rowToPlaybook(row) : undefined;
         this._index.remove(id);
-        return this.persistence.deletePlaybook(id);
+        const deleted = this.persistence.deletePlaybook(id);
+        if (deleted && playbook) {
+            await this.deleteStructural(playbook);
+        }
+        return deleted;
     }
     /**
      * Get count
@@ -437,8 +1501,7 @@ export class PlaybookLibrary {
         await this.init();
         const toDelete = this.getAllSync().filter((p) => p.provenance?.origin === origin);
         for (const playbook of toDelete) {
-            this.persistence.deletePlaybook(playbook.id);
-            this._index.remove(playbook.id);
+            await this.delete(playbook.id);
         }
         return toDelete.length;
     }
@@ -449,11 +1512,9 @@ export class PlaybookLibrary {
      */
     async deleteByCuratedSource(sourcePrefix) {
         await this.init();
-        const toDelete = this.getAllSync().filter((p) => p.provenance?.origin === 'curated' &&
-            p.provenance.sourceFile?.startsWith(sourcePrefix));
+        const toDelete = this.getAllSync().filter((p) => p.provenance?.origin === 'curated' && p.provenance.sourceFile?.startsWith(sourcePrefix));
         for (const playbook of toDelete) {
-            this.persistence.deletePlaybook(playbook.id);
-            this._index.remove(playbook.id);
+            await this.delete(playbook.id);
         }
         return toDelete.length;
     }
@@ -487,6 +1548,126 @@ export class PlaybookLibrary {
         return this.persistence.getAllPlaybooks().map(rowToPlaybook);
     }
 }
+/**
+ * Pure Fisher-Yates shuffle returning a new array. Caller supplies an
+ * `rng` (typically `Math.random` in production, a deterministic source
+ * in tests).
+ *
+ * Robust to `rng()` returning 1.0: `Math.random()` is documented as
+ * `[0, 1)` so production is safe, but the public `rng` type accepts any
+ * `() => number` and tests/users could supply 1.0. Without the clamp,
+ * `floor(1.0 * (i + 1)) = i + 1` would index out of bounds, writing
+ * `undefined` into the array.
+ */
+/**
+ * Shared dominance pruning + member resolution. Both `getDominatorPlaybooks`
+ * and `getDominatorPlaybooksMultiObjective` use the same algorithm over
+ * different frontier key spaces.
+ *
+ * `frontierSets`: map from an opaque key to the set of playbook IDs that
+ * are at the top score for that key.
+ *
+ * Returns the surviving (non-dominated) playbook IDs.
+ */
+function pruneDominated(frontierSets) {
+    const winCounts = new Map();
+    for (const set of frontierSets.values()) {
+        for (const id of set) {
+            winCounts.set(id, (winCounts.get(id) ?? 0) + 1);
+        }
+    }
+    const candidates = Array.from(winCounts.keys());
+    const dominated = new Set();
+    const isDominated = (target, alive) => {
+        for (const set of frontierSets.values()) {
+            if (!set.has(target))
+                continue;
+            let other = false;
+            for (const id of set) {
+                if (id !== target && alive.has(id)) {
+                    other = true;
+                    break;
+                }
+            }
+            if (!other)
+                return false;
+        }
+        return true;
+    };
+    // Sort low-win first so we drop weak dominators preferentially —
+    // matches gepa_utils.py:47 ordering.
+    candidates.sort((a, b) => winCounts.get(a) - winCounts.get(b));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const c of candidates) {
+            if (dominated.has(c))
+                continue;
+            const alive = new Set(candidates.filter((x) => x !== c && !dominated.has(x)));
+            if (isDominated(c, alive)) {
+                dominated.add(c);
+                changed = true;
+                break;
+            }
+        }
+    }
+    return new Set(candidates.filter((c) => !dominated.has(c)));
+}
+/**
+ * Resolve surviving playbook IDs into ranked FrontierMember objects.
+ * Shared by both single- and multi-objective dominator methods.
+ */
+function resolveFrontierMembers(survivors, frontierSets, persistence, domain) {
+    const members = [];
+    for (const id of survivors) {
+        const row = persistence.getPlaybook(id);
+        if (!row)
+            continue;
+        const playbook = rowToPlaybook(row);
+        if (domain && !playbook.applicability.domains.includes(domain))
+            continue;
+        let total = 0;
+        let unique = 0;
+        for (const set of frontierSets.values()) {
+            if (set.has(id)) {
+                total++;
+                if (set.size === 1)
+                    unique++;
+            }
+        }
+        members.push({ playbook, totalWins: total, uniqueWins: unique });
+    }
+    members.sort((a, b) => {
+        if (b.totalWins !== a.totalWins)
+            return b.totalWins - a.totalWins;
+        return b.playbook.confidence - a.playbook.confidence;
+    });
+    return members;
+}
+function fisherYatesShuffled(xs, rng) {
+    const out = [...xs];
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.min(i, Math.floor(rng() * (i + 1)));
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+}
+/**
+ * Resolve an `ObjectivePreference` into the list of objective keys that
+ * the cartesian dominator computation should consider.
+ */
+function resolvePreferenceObjectives(prefer) {
+    switch (prefer) {
+        case 'best':
+            return ['quality'];
+        case 'cheap':
+            return ['cost'];
+        case 'fast':
+            return ['latency'];
+        default:
+            return prefer.objectives;
+    }
+}
 /**
  * Create a playbook library
  */