@soleri/core 2.1.0 → 2.5.0

package/src/loop/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Loop system types — iterative validation loop state tracking.
+ *
+ * Loops let agents run validate-fix-validate cycles (e.g. token migration,
+ * contrast fixes, component builds).
+ *
+ * Ported from Salvador's loop.facade.ts with full gate decision system,
+ * output scanning, and completion promise detection.
+ */
+
+/** Supported loop modes — each maps to a different validation strategy. */
+export type LoopMode =
+  | 'token-migration'
+  | 'contrast-fix'
+  | 'component-build'
+  | 'plan-iteration'
+  | 'custom';
+
+/** Configuration for starting a new loop. */
+export interface LoopConfig {
+  mode: LoopMode;
+  prompt: string;
+  maxIterations: number;
+  /** Target validation score for score-based modes (token-migration, component-build). */
+  targetScore?: number;
+  /** Target grade for plan-iteration mode (e.g., 'A', 'A+'). */
+  targetGrade?: string;
+  /** Completion promise text — loop completes when this appears in output. */
+  completionPromise?: string;
+  /** Validation instructions appended to the prompt each iteration. */
+  validationInstructions?: string;
+  /** Detected intent for this loop (e.g., 'BUILD', 'FIX'). Used for brain session recording. */
+  intent?: string;
+}
+
+/** A single iteration result within a loop. */
+export interface LoopIteration {
+  iteration: number;
+  timestamp: string;
+  validationScore?: number;
+  validationResult?: string;
+  passed: boolean;
+  /** Duration of this iteration in milliseconds. */
+  durationMs?: number;
+}
+
+/** Loop lifecycle status. */
+export type LoopStatus = 'active' | 'completed' | 'cancelled' | 'max-iterations';
+
+/**
+ * Knowledge items tracked during loop execution.
+ * Ported from Salvador's loop knowledge tracking for brain session recording.
+ */
+export interface LoopKnowledge {
+  /** Knowledge items discovered during the loop. */
+  items?: string[];
+  /** Patterns successfully applied during the loop. */
+  patternsApplied?: string[];
+  /** Anti-patterns intentionally avoided during the loop. */
+  antiPatternsAvoided?: string[];
+}
+
+/** Full state of a loop (active or historical). */
+export interface LoopState {
+  id: string;
+  config: LoopConfig;
+  iterations: LoopIteration[];
+  status: LoopStatus;
+  startedAt: string;
+  completedAt?: string;
+  /** Knowledge accumulated during the loop. */
+  knowledge?: LoopKnowledge;
+}
+
+/**
+ * Loop history entry — stored after loop completion.
+ * Ported from Salvador's LoopHistoryEntry.
+ */
+export interface LoopHistoryEntry {
+  id: string;
+  mode: LoopMode;
+  intent?: string;
+  prompt: string;
+  iterations: number;
+  outcome: 'completed' | 'cancelled' | 'max_iterations';
+  startedAt: string;
+  completedAt: string;
+}
+
+/**
+ * Gate decision returned by iterateWithGate().
+ * Ported from Salvador's LoopIterateDecision.
+ *
+ * - 'allow': Loop has ended (completed, max_iterations, or error). Exit the loop.
+ * - 'block': Loop continues. The returned prompt and systemMessage are injected
+ *   into the next iteration of the Stop hook.
+ */
+export interface LoopIterateDecision {
+  /** Gate decision: 'allow' to exit loop, 'block' to continue iterating. */
+  decision: 'allow' | 'block';
+  /** Human-readable reason for this decision. */
+  reason: string;
+  /** Full prompt for the next iteration (only when decision = 'block'). */
+  prompt?: string;
+  /** System message for the next iteration (only when decision = 'block'). */
+  systemMessage?: string;
+  /** Current iteration number. */
+  iteration?: number;
+  /** Outcome when loop ends (only when decision = 'allow'). */
+  outcome?: 'completed' | 'max_iterations';
+  /** Whether completion was auto-detected (heuristic, not explicit promise). */
+  autoCompleted?: boolean;
+  /** Warning if anomalous patterns detected in this iteration. */
+  anomalyWarning?: string;
+}

package/src/persistence/index.ts

@@ -0,0 +1,7 @@
+export type {
+  PersistenceProvider,
+  PersistenceParams,
+  RunResult,
+  PersistenceConfig,
+} from './types.js';
+export { SQLitePersistenceProvider } from './sqlite-provider.js';

package/src/persistence/sqlite-provider.ts

@@ -0,0 +1,62 @@
+/**
+ * SQLite persistence provider backed by better-sqlite3.
+ *
+ * Supports both positional (array) and named (object) parameters.
+ * Exposes getDatabase() for backward-compat consumers that need the raw db.
+ */
+
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { PersistenceProvider, PersistenceParams, RunResult } from './types.js';
+
+export class SQLitePersistenceProvider implements PersistenceProvider {
+  private db: Database.Database;
+
+  constructor(path: string = ':memory:') {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path);
+  }
+
+  execSql(sql: string): void {
+    this.db.exec(sql);
+  }
+
+  run(sql: string, params?: PersistenceParams): RunResult {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.run();
+    if (Array.isArray(params)) return stmt.run(...params);
+    return stmt.run(params);
+  }
+
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.get() as T | undefined;
+    if (Array.isArray(params)) return stmt.get(...params) as T | undefined;
+    return stmt.get(params) as T | undefined;
+  }
+
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[] {
+    const stmt = this.db.prepare(sql);
+    if (!params) return stmt.all() as T[];
+    if (Array.isArray(params)) return stmt.all(...params) as T[];
+    return stmt.all(params) as T[];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  /**
+   * Escape hatch: get the raw better-sqlite3 Database.
+   * Used by modules that need direct db access (ProjectRegistry, BrainIntelligence, etc.).
+   * Will be deprecated once those modules migrate to PersistenceProvider.
+   */
+  getDatabase(): Database.Database {
+    return this.db;
+  }
+}

package/src/persistence/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Abstract persistence layer.
+ *
+ * Decouples Vault (and future modules) from any specific database engine.
+ * The default implementation is SQLitePersistenceProvider (better-sqlite3).
+ */
+
+export type PersistenceParams = unknown[] | Record<string, unknown>;
+
+export interface RunResult {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+/**
+ * Minimal database provider interface.
+ *
+ * Supports both positional (`?`) and named (`@param`) parameter styles.
+ * Implementations must handle both array and object params.
+ */
+export interface PersistenceProvider {
+  /** Run raw SQL (DDL, multi-statement). No return value. */
+  execSql(sql: string): void;
+
+  /** Run a parameterized statement (INSERT, UPDATE, DELETE). */
+  run(sql: string, params?: PersistenceParams): RunResult;
+
+  /** Get a single row. Returns undefined if no match. */
+  get<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T | undefined;
+
+  /** Get all matching rows. */
+  all<T = Record<string, unknown>>(sql: string, params?: PersistenceParams): T[];
+
+  /** Run a function inside a transaction. Commits on success, rolls back on error. */
+  transaction<T>(fn: () => T): T;
+
+  /** Close the connection. */
+  close(): void;
+}
+
+export interface PersistenceConfig {
+  type: 'sqlite';
+  path: string;
+}