cognitive-core 0.2.4 → 0.3.1

package/src/memory/playbook.ts

@@ -1,676 +0,0 @@
-/**
- * Playbook Library - Unified store for adaptive guidance
- * Replaces StrategyBank + SkillStore with a single, evolvable abstraction
- *
- * Uses SqlitePersistence for storage and InvertedIndex
- * for fast candidate narrowing before similarity scoring.
- */
-
-import type {
-  Playbook,
-  PlaybookOrigin,
-  PlaybookComplexity,
-  FailureRecord,
-  Refinement,
-} from '../types/index.js';
-import { createPlaybook, bumpPlaybookVersion } from '../types/index.js';
-import type { SqlitePersistence, PlaybookRow } from '../persistence/index.js';
-import { fromJSON, blobToEmbedding, fromISO } from '../persistence/index.js';
-import { InvertedIndex } from '../embeddings/inverted-index.js';
-import { textSimilarity } from '../utils/similarity.js';
-import { getCandidates, type ItemResolver } from './candidate-retrieval.js';
-
-/**
- * Match result for playbook retrieval
- */
-export interface PlaybookMatch {
-  playbook: Playbook;
-  score: number;
-  matchType: 'situation' | 'trigger' | 'domain';
-}
-
-/**
- * Options for finding matching playbooks
- */
-export interface FindMatchingOptions {
-  k?: number;
-  domains?: string[];
-  minConfidence?: number;
-  excludeAntiPatterns?: boolean;
-  minScore?: number;
-  /** MMR lambda: 0.0 = pure diversity, 1.0 = pure relevance (default: 1.0 — no MMR) */
-  lambda?: number;
-}
-
-/**
- * Build the indexable text for a playbook (situations + triggers concatenated)
- */
-function playbookIndexText(playbook: Playbook): string {
-  return [
-    ...playbook.applicability.situations,
-    ...playbook.applicability.triggers,
-  ].join(' ');
-}
-
-/**
- * Convert a PlaybookRow (SQLite representation) back to a Playbook (domain type).
- */
-function rowToPlaybook(row: PlaybookRow): Playbook {
-  const evolution = fromJSON<Record<string, unknown>>(row.evolution, {});
-  const provenance = fromJSON<Record<string, unknown> | undefined>(row.provenance, undefined);
-
-  return {
-    id: row.id,
-    name: row.name,
-    confidence: row.confidence,
-    complexity: row.complexity as PlaybookComplexity,
-    estimatedEffort: row.estimated_effort,
-    applicability: fromJSON(row.applicability, { situations: [], triggers: [], antiPatterns: [], domains: [] }),
-    guidance: fromJSON(row.guidance, { strategy: '', tactics: [] }),
-    verification: fromJSON(row.verification, { successIndicators: [], failureIndicators: [] }),
-    evolution: {
-      version: (evolution.version ?? row.version ?? '1.0.0') as string,
-      createdFrom: (evolution.createdFrom ?? []) as string[],
-      failures: (evolution.failures ?? []) as FailureRecord[],
-      refinements: (evolution.refinements ?? []) as Refinement[],
-      successCount: (evolution.successCount ?? row.success_count ?? 0) as number,
-      failureCount: (evolution.failureCount ?? row.failure_count ?? 0) as number,
-      lastUsed: evolution.lastUsed ? new Date(evolution.lastUsed as string) : undefined,
-      consolidationStrength: evolution.consolidationStrength as number | undefined,
-      domainBreadth: evolution.domainBreadth as number | undefined,
-    },
-    provenance: (provenance && Object.keys(provenance).length > 0) ? {
-      origin: (provenance.origin ?? row.origin ?? 'extracted') as PlaybookOrigin,
-      sourceFile: provenance.sourceFile as string | undefined,
-      importedFrom: provenance.importedFrom as string | undefined,
-      curatedBy: provenance.curatedBy as string | undefined,
-      recordedAt: provenance.recordedAt ? new Date(provenance.recordedAt as string) : new Date(),
-    } : undefined,
-    embedding: blobToEmbedding(row.embedding),
-    createdAt: fromISO(row.created_at) ?? new Date(),
-    updatedAt: fromISO(row.updated_at) ?? new Date(),
-  };
-}
-
-/**
- * Playbook Library - Store and retrieve adaptive guidance
- */
-export class PlaybookLibrary {
-  private persistence: SqlitePersistence;
-  private _index: InvertedIndex = new InvertedIndex();
-  private initialized = false;
-  private _resolver: ItemResolver<Playbook>;
-
-  constructor(persistence: SqlitePersistence) {
-    this.persistence = persistence;
-    this._resolver = {
-      get: (id: string) => {
-        const row = this.persistence.getPlaybook(id);
-        return row ? rowToPlaybook(row) : undefined;
-      },
-      values: () => this.getAllSync(),
-    };
-  }
-
-  async init(): Promise<void> {
-    if (this.initialized) return;
-
-    // Build inverted index from all playbooks in DB
-    const rows = this.persistence.getPlaybookIds();
-    for (const { id, applicability } of rows) {
-      const app = fromJSON<{ situations?: string[]; triggers?: string[] }>(applicability, {});
-      const text = [...(app.situations ?? []), ...(app.triggers ?? [])].join(' ');
-      this._index.add(id, text);
-    }
-
-    this.initialized = true;
-  }
-
-  // === RETRIEVAL ===
-
-  /**
-   * Find playbooks matching a context
-   * Uses inverted index for candidate narrowing, then weighted scoring
-   * across situations, triggers, and anti-patterns.
-   */
-  async findMatching(
-    context: string,
-    options?: FindMatchingOptions
-  ): Promise<PlaybookMatch[]> {
-    await this.init();
-
-    const k = options?.k ?? 5;
-
-    // Get candidate pool
-    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);
-
-    // 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))
-      );
-    }
-
-    // Filter by minimum confidence
-    if (options?.minConfidence !== undefined) {
-      playbooks = playbooks.filter((p) => p.confidence >= options.minConfidence!);
-    }
-
-    // Score playbooks
-    const scored: PlaybookMatch[] = [];
-
-    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;
-      }
-
-      // 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: 'situation' | 'trigger' =
-        maxTriggerScore > maxSituationScore ? 'trigger' : 'situation';
-
-      if (score > 0) {
-        scored.push({ playbook, score, matchType });
-      }
-    }
-
-    // Apply minimum score filter before ranking
-    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) {
-      return this.applyMMR(filtered, k, lambda);
-    }
-
-    // Pure relevance ranking (default)
-    filtered.sort((a, b) => b.score - a.score);
-    return filtered.slice(0, k);
-  }
-
-  /**
-   * Maximal Marginal Relevance reranking.
-   * Selects top-k items balancing relevance and diversity.
-   */
-  private applyMMR(
-    scored: PlaybookMatch[],
-    k: number,
-    lambda: number
-  ): PlaybookMatch[] {
-    const selected: PlaybookMatch[] = [];
-    const remaining = [...scored];
-
-    for (let i = 0; i < k && remaining.length > 0; i++) {
-      let bestIdx = 0;
-      let bestMMR = -Infinity;
-
-      for (let j = 0; j < remaining.length; j++) {
-        const relevance = remaining[j].score;
-        const maxSim =
-          selected.length === 0
-            ? 0
-            : Math.max(
-                ...selected.map((s) =>
-                  textSimilarity(
-                    remaining[j].playbook.guidance.strategy,
-                    s.playbook.guidance.strategy
-                  )
-                )
-              );
-        const mmr = lambda * relevance - (1 - lambda) * maxSim;
-        if (mmr > bestMMR) {
-          bestMMR = mmr;
-          bestIdx = j;
-        }
-      }
-
-      selected.push(remaining.splice(bestIdx, 1)[0]);
-    }
-
-    return selected;
-  }
-
-  /**
-   * Find by specific trigger (for error messages, etc.)
-   */
-  async findByTrigger(trigger: string, threshold = 0.5): Promise<Playbook[]> {
-    await this.init();
-
-    return this.getAllSync().filter((playbook) =>
-      playbook.applicability.triggers.some(
-        (t) =>
-          t.toLowerCase().includes(trigger.toLowerCase()) ||
-          textSimilarity(trigger, t) >= threshold
-      )
-    );
-  }
-
-  /**
-   * Get playbooks with refinements for a specific context
-   */
-  async findWithRefinements(context: string): Promise<Playbook[]> {
-    await this.init();
-
-    return this.getAllSync().filter((playbook) =>
-      playbook.evolution.refinements.some(
-        (r) => textSimilarity(context, r.context) > 0.6
-      )
-    );
-  }
-
-  // === EVOLUTION ===
-
-  /**
-   * Record successful application.
-   * Applies stability-plasticity damping — consolidated playbooks change more slowly.
-   */
-  async recordSuccess(id: string, _trajectoryId: string, domain?: string): Promise<void> {
-    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 recorded');
-
-    playbook.evolution.successCount++;
-    playbook.evolution.lastUsed = new Date();
-
-    // Stability-plasticity: damped confidence update
-    const cs = playbook.evolution.consolidationStrength ?? 0;
-    const rawDelta = (1 - playbook.confidence) * 0.1;
-    const dampedDelta = rawDelta / (1 + cs * 0.1);
-    playbook.confidence = Math.min(0.99, playbook.confidence + dampedDelta);
-
-    // Grow consolidation strength slowly on success
-    playbook.evolution.consolidationStrength = Math.min(10, cs + 0.05);
-
-    // Track domain breadth
-    if (domain) {
-      const knownDomains = new Set(playbook.applicability.domains);
-      if (!knownDomains.has(domain)) {
-        playbook.evolution.domainBreadth = (playbook.evolution.domainBreadth ?? 0) + 1;
-      }
-    }
-
-    playbook.updatedAt = new Date();
-    this.persistence.insertPlaybook(playbook); // Write-through (INSERT OR REPLACE)
-  }
-
-  /**
-   * Record failure and capture context
-   */
-  async recordFailure(
-    id: string,
-    trajectoryId: string,
-    failureContext: string,
-    failureMode: string
-  ): Promise<void> {
-    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, `Failure recorded: ${failureMode}`);
-
-    playbook.evolution.failureCount++;
-    playbook.evolution.lastUsed = new Date();
-
-    // Add failure record
-    const failure: FailureRecord = {
-      trajectoryId,
-      context: failureContext,
-      failureMode,
-      timestamp: new Date(),
-    };
-    playbook.evolution.failures.push(failure);
-
-    // Keep only last 10 failures
-    if (playbook.evolution.failures.length > 10) {
-      playbook.evolution.failures = playbook.evolution.failures.slice(-10);
-    }
-
-    // Stability-plasticity: damped confidence decrease
-    const cs = playbook.evolution.consolidationStrength ?? 0;
-    const rawDelta = playbook.confidence * 0.15;
-    const dampedDelta = rawDelta / (1 + cs * 0.2);
-    playbook.confidence = Math.max(0.1, playbook.confidence - dampedDelta);
-
-    playbook.updatedAt = new Date();
-    this.persistence.insertPlaybook(playbook); // Write-through
-  }
-
-  /**
-   * Add a context-specific refinement
-   */
-  async addRefinement(
-    id: string,
-    context: string,
-    addition: string,
-    source: 'failure' | 'success' | 'manual'
-  ): Promise<void> {
-    await this.init();
-    const row = this.persistence.getPlaybook(id);
-    if (!row) return;
-
-    const playbook = rowToPlaybook(row);
-
-    // Check if similar refinement exists
-    const exists = playbook.evolution.refinements.some(
-      (r) => textSimilarity(r.context, context) > 0.85
-    );
-    if (exists) return;
-
-    const refinement: Refinement = {
-      context,
-      addition,
-      source,
-      addedAt: new Date(),
-    };
-
-    playbook.evolution.refinements.push(refinement);
-
-    // Bump patch version
-    playbook.evolution.version = bumpPlaybookVersion(playbook, 'patch');
-    playbook.updatedAt = new Date();
-
-    this.persistence.insertPlaybook(playbook); // Write-through
-  }
-
-  /**
-   * Evolve playbook based on accumulated failures
-   */
-  async evolve(
-    id: string,
-    newGuidance?: Partial<Playbook['guidance']>,
-    newAntiPatterns?: string[]
-  ): Promise<Playbook | undefined> {
-    await this.init();
-    const row = this.persistence.getPlaybook(id);
-    if (!row) return undefined;
-
-    const playbook = rowToPlaybook(row);
-
-    // Snapshot before evolution
-    this.persistence.snapshotPlaybookVersion(id, playbook.evolution.version, 'Pre-evolution snapshot');
-
-    // Update guidance if provided
-    if (newGuidance) {
-      playbook.guidance = { ...playbook.guidance, ...newGuidance };
-    }
-
-    // Add new anti-patterns
-    if (newAntiPatterns) {
-      const unique = newAntiPatterns.filter(
-        (ap) => !playbook.applicability.antiPatterns.includes(ap)
-      );
-      playbook.applicability.antiPatterns.push(...unique);
-    }
-
-    // Bump minor version for evolution
-    playbook.evolution.version = bumpPlaybookVersion(playbook, 'minor');
-    playbook.updatedAt = new Date();
-
-    this.persistence.insertPlaybook(playbook); // Write-through
-
-    // Update index since applicability may have changed
-    this._index.add(id, playbookIndexText(playbook));
-
-    return playbook;
-  }
-
-  // === LIFECYCLE ===
-
-  /**
-   * Add a new playbook
-   */
-  async add(playbook: Playbook): Promise<void> {
-    await this.init();
-    this.persistence.insertPlaybook(playbook);
-    this._index.add(playbook.id, playbookIndexText(playbook));
-  }
-
-  /**
-   * Create and add a new playbook
-   */
-  async create(
-    input: Parameters<typeof createPlaybook>[0]
-  ): Promise<Playbook> {
-    const playbook = createPlaybook(input);
-    await this.add(playbook);
-    return playbook;
-  }
-
-  /**
-   * Get a playbook by ID
-   */
-  async get(id: string): Promise<Playbook | undefined> {
-    await this.init();
-    const row = this.persistence.getPlaybook(id);
-    return row ? rowToPlaybook(row) : undefined;
-  }
-
-  /**
-   * Get playbook by name
-   */
-  async getByName(name: string): Promise<Playbook | undefined> {
-    await this.init();
-    return this.getAllSync().find((p) => p.name === name);
-  }
-
-  /**
-   * Check if a similar playbook exists
-   */
-  async exists(
-    description: string,
-    threshold = 0.85
-  ): Promise<Playbook | undefined> {
-    await this.init();
-
-    const all = this.getAllSync();
-
-    // Check by exact name match
-    const byName = all.find(
-      (p) => p.name === description.toLowerCase().replace(/\s+/g, '-')
-    );
-    if (byName) return byName;
-
-    // Check by situation similarity
-    for (const playbook of all) {
-      for (const situation of playbook.applicability.situations) {
-        if (textSimilarity(description, situation) >= threshold) {
-          return playbook;
-        }
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Get playbooks by domain
-   */
-  async getByDomain(domain: string): Promise<Playbook[]> {
-    await this.init();
-    return this.getAllSync().filter((p) =>
-      p.applicability.domains.includes(domain)
-    );
-  }
-
-  /**
-   * Get most effective playbooks (by success rate)
-   */
-  async getMostEffective(k = 10): Promise<Playbook[]> {
-    await this.init();
-    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);
-        return rateB - rateA;
-      })
-      .slice(0, k);
-  }
-
-  /**
-   * Get playbooks by confidence threshold
-   */
-  async getHighConfidence(minConfidence = 0.8): Promise<Playbook[]> {
-    await this.init();
-    return this.getAllSync().filter((p) => p.confidence >= minConfidence);
-  }
-
-  /**
-   * Get all playbooks
-   */
-  async getAll(): Promise<Playbook[]> {
-    await this.init();
-    return this.getAllSync();
-  }
-
-  /**
-   * Delete a playbook
-   */
-  async delete(id: string): Promise<boolean> {
-    await this.init();
-    this._index.remove(id);
-    return this.persistence.deletePlaybook(id);
-  }
-
-  /**
-   * Get count
-   */
-  async count(): Promise<number> {
-    await this.init();
-    return this.persistence.getPlaybookCount();
-  }
-
-  /**
-   * Get all unique domains
-   */
-  async getDomains(): Promise<string[]> {
-    await this.init();
-    const domains = new Set<string>();
-    for (const playbook of this.getAllSync()) {
-      for (const domain of playbook.applicability.domains) {
-        domains.add(domain);
-      }
-    }
-    return Array.from(domains);
-  }
-
-  // === PROVENANCE ===
-
-  /**
-   * Get playbooks by origin type
-   */
-  async getByOrigin(origin: PlaybookOrigin): Promise<Playbook[]> {
-    await this.init();
-    return this.getAllSync().filter((p) => p.provenance?.origin === origin);
-  }
-
-  /**
-   * Delete all playbooks with a specific origin
-   */
-  async deleteByOrigin(origin: PlaybookOrigin): Promise<number> {
-    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);
-    }
-    return toDelete.length;
-  }
-
-  /**
-   * Delete curated playbooks whose provenance.sourceFile starts with the given prefix.
-   * Used by the source resolver to recreate playbooks from a specific source
-   * without affecting other curated sources.
-   */
-  async deleteByCuratedSource(sourcePrefix: string): Promise<number> {
-    await this.init();
-    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);
-    }
-    return toDelete.length;
-  }
-
-  /**
-   * Get provenance summary across all playbooks
-   */
-  async getProvenanceSummary(): Promise<Record<PlaybookOrigin, number>> {
-    await this.init();
-    const summary: Record<string, number> = {
-      extracted: 0,
-      curated: 0,
-      imported: 0,
-      manual: 0,
-    };
-    for (const playbook of this.getAllSync()) {
-      const origin = playbook.provenance?.origin ?? 'extracted';
-      summary[origin] = (summary[origin] ?? 0) + 1;
-    }
-    return summary as Record<PlaybookOrigin, number>;
-  }
-
-  /**
-   * Close the store (no-op — SqlitePersistence lifecycle is managed externally)
-   */
-  async close(): Promise<void> {
-    // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
-  }
-
-  /**
-   * Synchronous helper: get all playbooks from SQLite.
-   */
-  private getAllSync(): Playbook[] {
-    return this.persistence.getAllPlaybooks().map(rowToPlaybook);
-  }
-}
-
-/**
- * Create a playbook library
- */
-export function createPlaybookLibrary(persistence: SqlitePersistence): PlaybookLibrary {
-  return new PlaybookLibrary(persistence);
-}