principles-disciple 1.11.0 → 1.13.0

package/src/core/rule-host-types.ts

@@ -0,0 +1,82 @@
+/**
+ * Rule Host Types — Execution contracts for hosted code implementations
+ *
+ * PURPOSE: Define the constrained interface through which active code
+ * implementations are executed. Implementations receive a frozen snapshot
+ * of context and return one of three decisions.
+ *
+ * TRUST BOUNDARY:
+ *   - RuleHostInput is a frozen snapshot — no live workspace handles
+ *   - Implementations execute in a constrained vm context with minimal helpers
+ *   - No filesystem, process, require, dynamic import, eval, or network access
+ */
+
+// ---------------------------------------------------------------------------
+// Input: Frozen snapshot provided to implementations
+// ---------------------------------------------------------------------------
+
+export interface RuleHostInput {
+  action: {
+    toolName: string;
+    normalizedPath: string | null;
+    paramsSummary: Record<string, unknown>;
+  };
+  workspace: {
+    isRiskPath: boolean;
+    planStatus: 'NONE' | 'DRAFT' | 'READY' | 'UNKNOWN';
+    hasPlanFile: boolean;
+  };
+  session: {
+    sessionId?: string;
+    currentGfi: number;
+    recentThinking: boolean;
+  };
+  evolution: {
+    epTier: number;
+  };
+  derived: {
+    estimatedLineChanges: number;
+    bashRisk: 'safe' | 'normal' | 'dangerous' | 'unknown';
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Decision: Limited to three outcomes
+// ---------------------------------------------------------------------------
+
+export type RuleHostDecision = 'allow' | 'block' | 'requireApproval';
+
+// ---------------------------------------------------------------------------
+// Meta: Exported by each implementation for identification
+// ---------------------------------------------------------------------------
+
+export interface RuleHostMeta {
+  name: string;
+  version: string;
+  ruleId: string;
+  coversCondition: string;
+}
+
+// ---------------------------------------------------------------------------
+// Result: Structured output from a single implementation evaluation
+// ---------------------------------------------------------------------------
+
+export interface RuleHostResult {
+  decision: RuleHostDecision;
+  matched: boolean;
+  reason: string;
+  diagnostics?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// LoadedImplementation: A successfully loaded active implementation
+// ---------------------------------------------------------------------------
+
+export interface LoadedImplementation {
+  implId: string;
+  ruleId: string;
+  meta: RuleHostMeta;
+  /* eslint-disable no-unused-vars -- Reason: _input parameter name in interface type definition intentionally unused - actual implementation uses different param names */
+  evaluate: (_input: RuleHostInput) => RuleHostResult;
+  /* eslint-enable no-unused-vars */
+}

package/src/core/rule-host.ts

@@ -0,0 +1,245 @@
+/**
+ * Rule Host — Constrained execution layer for active code implementations
+ *
+ * PURPOSE: Load active code implementations from the principle-tree ledger,
+ * execute them in a constrained node:vm context, and merge their decisions.
+ *
+ * ARCHITECTURE:
+ *   - Constructor takes stateDir to access the principle-tree ledger
+ *   - evaluate(input) loads active code implementations and runs them
+ *   - Each implementation executes in an isolated vm context with minimal helpers
+ *   - Decision merge: block short-circuits, requireApproval collects, allow is implicit
+ *
+ * SECURITY CONSTRAINTS (T-12-01, T-12-04):
+ *   - Candidate code loads through a dedicated vm context, not the host realm
+ *   - No importModuleDynamically callback
+ *   - Helpers are a frozen object — implementations cannot modify the helper surface
+ *
+ * CONSERVATIVE DEGRADATION (T-12-02, D-08):
+ *   - On ANY host error (load failure, eval error, vm error): return undefined
+ *   - Never throw, never bypass downstream gates (Progressive Gate, Edit Verification)
+ */
+
+import * as fs from 'fs';
+import {
+  listImplementationsByLifecycleState,
+} from './principle-tree-ledger.js';
+import { loadEntrySource } from './code-implementation-storage.js';
+import { createRuleHostHelpers } from './rule-host-helpers.js';
+import { loadRuleImplementationModule } from './rule-implementation-runtime.js';
+import type {
+  RuleHostInput,
+  RuleHostResult,
+  RuleHostMeta,
+  LoadedImplementation,
+} from './rule-host-types.js';
+import type { Implementation } from '../types/principle-tree-schema.js';
+
+export interface RuleHostLogger {
+  /* eslint-disable no-unused-vars -- Reason: logger callback param name intentionally unused - callback only invoked for side effects */
+  warn?: (_message: string) => void;
+  /* eslint-enable no-unused-vars */
+}
+
+export class RuleHost {
+  private readonly stateDir: string;
+  private readonly logger: RuleHostLogger;
+
+  constructor(stateDir: string, logger: RuleHostLogger = console) {
+    this.stateDir = stateDir;
+    this.logger = logger;
+  }
+
+  /**
+   * Evaluate the input against all active code implementations.
+   *
+   * Returns:
+   *   - undefined when no active code implementations exist (no opinion)
+   *   - undefined when all implementations return allow or matched=false
+   *   - { decision: 'block', ... } when any implementation returns block (short-circuits)
+   *   - { decision: 'requireApproval', ... } when any implementation returns requireApproval
+   */
+  evaluate(input: RuleHostInput): RuleHostResult | undefined {
+    try {
+      // Load active code implementations from the ledger
+      const activeImpls = this._loadActiveCodeImplementations();
+
+      if (activeImpls.length === 0) {
+        return undefined;
+      }
+
+      // Merge decisions from all active implementations
+      // eslint-disable-next-line @typescript-eslint/init-declarations -- undefined is valid zero value, checked before use
+      let blocked: RuleHostResult | undefined;
+      const approvals: RuleHostResult[] = [];
+
+      for (const impl of activeImpls) {
+        try {
+          const result = impl.evaluate(input);
+
+          if (!result.matched) {
+            continue;
+          }
+
+          if (result.decision === 'block') {
+            blocked = result;
+            break; // Short-circuit on block
+          }
+
+          if (result.decision === 'requireApproval') {
+            approvals.push(result);
+          }
+          // 'allow' is implicit — no action needed
+        } catch (evalError: unknown) {
+          // Individual implementation error: log and continue (D-08)
+          this.logger.warn?.(
+            `[RuleHost] Implementation ${impl.implId} evaluation failed: ${String(evalError)}`
+          );
+        }
+      }
+
+      if (blocked) {
+        return blocked;
+      }
+
+      if (approvals.length > 0) {
+        // Merge multiple requireApproval results
+        return {
+          decision: 'requireApproval',
+          matched: true,
+          reason: approvals.map((a) => a.reason).join('; '),
+          diagnostics: approvals.reduce<Record<string, unknown>>(
+            (acc, a) => ({ ...acc, ...a.diagnostics }),
+            {}
+          ),
+        };
+      }
+
+      // All implementations returned allow or matched=false — no opinion
+      return undefined;
+    } catch (hostError: unknown) {
+      // Conservative degradation: log and return undefined (D-08)
+      this.logger.warn?.(
+        `[RuleHost] Host evaluation failed, degrading conservatively: ${String(hostError)}`
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * Load active code implementations from the ledger.
+   * Filters by type=code and lifecycleState=active, then attempts to
+   * compile each implementation's code asset via node:vm.
+   */
+  private _loadActiveCodeImplementations(): LoadedImplementation[] {
+    try {
+      const activeAllTypes = listImplementationsByLifecycleState(
+        this.stateDir,
+        'active'
+      );
+
+      // Filter to code-type implementations only
+      const codeImpls = activeAllTypes.filter((impl) => impl.type === 'code');
+
+      if (codeImpls.length === 0) {
+        return [];
+      }
+
+      const loaded: LoadedImplementation[] = [];
+
+      for (const impl of codeImpls) {
+        try {
+          const loadedImpl = this._loadSingleImplementation(impl);
+          if (loadedImpl) {
+            loaded.push(loadedImpl);
+          }
+        } catch (loadError: unknown) {
+          // Individual load failure: log and skip
+          this.logger.warn?.(
+            `[RuleHost] Failed to load implementation ${impl.id}: ${String(loadError)}`
+          );
+        }
+      }
+
+      return loaded;
+    } catch (ledgerError: unknown) {
+      // Ledger access failure: log and return empty
+      this.logger.warn?.(
+        `[RuleHost] Failed to access ledger: ${String(ledgerError)}`
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Load and compile a single implementation from its code asset path.
+   *
+   * The implementation file is expected to export:
+   *   - meta: { name, version, ruleId, coversCondition }
+   *   - evaluate(input: RuleHostInput): RuleHostResult
+   *
+   * Uses the shared isolated runtime loader so candidate code does not execute
+   * in the host global realm.
+   */
+  private _loadSingleImplementation(
+    impl: Implementation
+  ): LoadedImplementation | null {
+    let sourceCode = loadEntrySource(this.stateDir, impl.id);
+    if (!sourceCode) {
+      const assetPath = impl.path;
+      if (!assetPath || !fs.existsSync(assetPath)) {
+        return null;
+      }
+
+      try {
+        sourceCode = fs.readFileSync(assetPath, 'utf-8');
+      } catch {
+        return null;
+      }
+    }
+
+    try {
+      const moduleExports = loadRuleImplementationModule(sourceCode, impl.id);
+
+      if (!moduleExports || typeof moduleExports.evaluate !== 'function') {
+        return null;
+      }
+
+      const fallbackMeta: RuleHostMeta = {
+        name: impl.id,
+        version: impl.version,
+        ruleId: impl.ruleId,
+        coversCondition: impl.coversCondition,
+      };
+      const meta: RuleHostMeta =
+        moduleExports.meta && typeof moduleExports.meta === 'object'
+          ? (moduleExports.meta as RuleHostMeta)
+          : fallbackMeta;
+
+      // Return a loaded implementation that wraps the compiled evaluate
+      // with the actual helpers from the input at evaluation time
+      /* eslint-disable no-unused-vars -- Reason: type cast params intentionally unused - they're just type annotations, actual function uses different params */
+      const rawEvaluate = moduleExports.evaluate as (
+        _input: RuleHostInput,
+        _helpers: ReturnType<typeof createRuleHostHelpers>
+      ) => RuleHostResult;
+      /* eslint-enable no-unused-vars */
+
+      return {
+        implId: impl.id,
+        ruleId: impl.ruleId,
+        meta,
+        evaluate: (input: RuleHostInput): RuleHostResult => {
+          const frozenHelpers = createRuleHostHelpers(input);
+          return rawEvaluate(input, frozenHelpers);
+        },
+      };
+    } catch (compileError: unknown) {
+      // Compilation failure: log and skip
+      this.logger.warn?.(
+        `[RuleHost] Failed to compile implementation ${impl.id}: ${String(compileError)}`
+      );
+      return null;
+    }
+  }
+}

package/src/core/rule-implementation-runtime.ts

@@ -0,0 +1,38 @@
+import { nodeVm } from '../utils/node-vm-polyfill.js';
+
+export interface RuleImplementationModuleExports {
+  meta?: unknown;
+  evaluate?: unknown;
+}
+
+function normalizeImplementationSource(sourceCode: string): string {
+  const withoutExports = sourceCode
+    .replace(/export\s+const\s+meta\s*=/, 'const meta =')
+    .replace(/export\s+function\s+evaluate\s*\(/, 'function evaluate(');
+
+  return `${withoutExports}
+globalThis.__pdRuleModule = {
+  meta: typeof meta === 'undefined' ? undefined : meta,
+  evaluate: typeof evaluate === 'undefined' ? undefined : evaluate,
+};`;
+}
+
+export function loadRuleImplementationModule(
+  sourceCode: string,
+  filename: string,
+): RuleImplementationModuleExports {
+  const context = nodeVm.createContext(Object.create(null));
+  const script = new nodeVm.Script(normalizeImplementationSource(sourceCode), {
+    filename,
+  });
+
+  script.runInContext(context, {
+    timeout: 1000,
+    displayErrors: true,
+  });
+
+  const moduleExports = (context as { __pdRuleModule?: RuleImplementationModuleExports }).__pdRuleModule;
+  delete (context as { __pdRuleModule?: RuleImplementationModuleExports }).__pdRuleModule;
+
+  return moduleExports ?? {};
+}

package/src/core/schema/db-types.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared type definitions for database operations.
+ * Kept separate to avoid circular dependencies between schema-definitions and migration-runner.
+ */
+
+/* eslint-disable no-unused-vars -- Reason: interface method param names are part of type signature */
+
+/** Minimal interface for better-sqlite3 Database instances. */
+export interface Db {
+  exec(_sql: string): unknown;
+
+  get<T = unknown>(_sql: string, ..._params: unknown[]): T | undefined;
+
+  run(_sql: string, ..._params: unknown[]): unknown;
+  close(): void;
+}

package/src/core/schema/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Schema Management — Unified database schema definitions and migrations.
+ *
+ * Usage:
+ *   // In a database class constructor:
+ *   import { ensureDatabaseSchema } from './schema';
+ *   ensureDatabaseSchema(db, 'trajectory.db');
+ *
+ * CLI:
+ *   node scripts/db-migrate.mjs status
+ *   node scripts/db-migrate.mjs run
+ */
+
+export { MigrationRunner, ensureDatabaseSchema } from './migration-runner.js';
+export { SCHEMAS, getCatalog, DB_TYPES } from './schema-definitions.js';
+export { ALL_MIGRATIONS } from './migrations/index.js';
+
+export type { Db } from './db-types.js';
+export type {
+  Migration,
+  DbType,
+  TableDefinition,
+  ViewDefinition,
+  FtsDefinition,
+  SchemaCatalog,
+} from './migration-runner.js';

package/src/core/schema/migration-runner.ts

@@ -0,0 +1,207 @@
+/**
+ * Migration Runner — Executes and tracks schema migrations.
+ *
+ * Each migration is versioned. The runner reads the current version from
+ * the `schema_version` table and only executes migrations with higher IDs.
+ *
+ * Usage:
+ *   const runner = new MigrationRunner(db);
+ *   runner.run(allMigrations.filter(m => m.db === 'trajectory.db'));
+ */
+
+import type { Migration } from './schema-definitions.js';
+import { getCatalog, type DbType } from './schema-definitions.js';
+import type { Db } from './db-types.js';
+
+export class MigrationRunner {
+  private readonly db: Db;
+
+  constructor(db: Db) {
+    this.db = db;
+  }
+
+  /**
+   * Run all pending migrations for a given database type.
+   * @returns Array of migration names that were applied
+   */
+  runMigrations(migrations: Migration[], _dbType: DbType): string[] {
+    // NOTE: _dbType is kept for API signature compatibility but migrations are pre-filtered by caller
+    void _dbType;
+    // Ensure schema_version table exists before anything else
+    this.ensureVersionTable();
+
+    const currentVersion = this.getCurrentVersion();
+    const applied: string[] = [];
+
+    // Filter to pending migrations (higher ID than current)
+    const pending = migrations
+      .filter(m => m.id > currentVersion)
+      .sort((a, b) => a.id.localeCompare(b.id));
+
+    for (const migration of pending) {
+       
+      console.log(`[MigrationRunner] Applying ${migration.id}-${migration.name}...`);
+      try {
+        migration.up(this.db);
+        this.setVersion(migration.id);
+        applied.push(`${migration.id}-${migration.name}`);
+      } catch (err) {
+        throw new Error(
+          `Migration ${migration.id}-${migration.name} failed: ${String(err)}`,
+          { cause: err }
+        );
+      }
+    }
+
+    if (applied.length > 0) {
+       
+      console.log(`[MigrationRunner] Applied ${applied.length} migration(s): ${applied.join(', ')}`);
+    }
+
+    return applied;
+  }
+
+  /**
+   * Apply all schema definitions (tables, indexes, views, FTS) for a database.
+   * This is a convenience method that creates everything from the schema catalog.
+   * Used for initial setup when no migrations exist yet.
+   */
+  applySchemaCatalog(dbType: DbType): void {
+    this.ensureVersionTable();
+
+    const catalog = getCatalog(dbType);
+
+    // Tables
+    for (const [key, table] of Object.entries(catalog.tables)) {
+      try {
+        this.db.exec(table.ddl);
+      } catch (err) {
+        throw new Error(`Failed to create table ${key}: ${String(err)}`, { cause: err });
+      }
+      // Indexes
+      for (const indexDdl of table.indexes ?? []) {
+        try {
+          this.db.exec(indexDdl);
+        } catch (err) {
+          throw new Error(`Failed to create index for ${key}: ${String(err)}`, { cause: err });
+        }
+      }
+    }
+
+    // Views
+    for (const [key, view] of Object.entries(catalog.views)) {
+      try {
+        this.db.exec(view.ddl);
+      } catch (err) {
+        throw new Error(`Failed to create view ${key}: ${String(err)}`, { cause: err });
+      }
+    }
+
+    // FTS5 virtual tables
+    for (const [key, fts] of Object.entries(catalog.fts)) {
+      try {
+        this.db.exec(fts.ddl);
+      } catch (err) {
+        throw new Error(`Failed to create FTS table ${key}: ${String(err)}`, { cause: err });
+      }
+    }
+  }
+
+  /**
+   * Get the current migration version.
+   * Returns '000' if no version is set (fresh database).
+   */
+  getCurrentVersion(): string {
+    try {
+      const row = this.db.get<{ version: string }>(
+        'SELECT version FROM schema_version ORDER BY version DESC LIMIT 1'
+      );
+      return row?.version ?? '000';
+    } catch {
+      return '000';
+    }
+  }
+
+  /**
+   * Get all available migration info for a database type.
+   */
+  getMigrationInfo(migrations: Migration[], dbType: DbType): {
+    id: string;
+    name: string;
+    applied: boolean;
+  }[] {
+    const currentVersion = this.getCurrentVersion();
+    return migrations
+      .filter(m => m.db === dbType)
+      .sort((a, b) => a.id.localeCompare(b.id))
+      .map(m => ({
+        id: m.id,
+        name: m.name,
+        applied: m.id <= currentVersion,
+      }));
+  }
+
+  /**
+   * Rollback the latest migration (if down migration is defined).
+   */
+  rollback(migrations: Migration[], dbType: DbType): string | null {
+    const currentVersion = this.getCurrentVersion();
+    if (currentVersion === '000') return null;
+
+    const migration = migrations.find(
+      m => m.db === dbType && m.id === currentVersion
+    );
+    if (!migration) return null;
+    if (!migration.down) {
+      throw new Error(`Migration ${migration.id}-${migration.name} has no down migration`);
+    }
+
+     
+    console.log(`[MigrationRunner] Rolling back ${migration.id}-${migration.name}...`);
+    migration.down(this.db);
+
+    // Set version to previous migration
+    const previousMigrations = migrations
+      .filter(m => m.db === dbType && m.id < currentVersion)
+      .sort((a, b) => b.id.localeCompare(a.id));
+    const newVersion = previousMigrations[0]?.id ?? '000';
+    this.setVersion(newVersion);
+
+     
+    console.log(`[MigrationRunner] Rolled back to ${newVersion}`);
+    return migration.id;
+  }
+
+  // -----------------------------------------------------------------------
+  // Private helpers
+  // -----------------------------------------------------------------------
+
+  private ensureVersionTable(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version TEXT NOT NULL DEFAULT '000'
+      )
+    `);
+    // Ensure at least one row exists
+    const count = this.db.get<{ cnt: number }>('SELECT COUNT(*) as cnt FROM schema_version');
+    if (!count || count.cnt === 0) {
+      this.db.exec("INSERT INTO schema_version (version) VALUES ('000')");
+    }
+  }
+
+  private setVersion(version: string): void {
+    this.db.exec(`UPDATE schema_version SET version = '${version}'`);
+  }
+}
+
+/**
+ * Factory: create a MigrationRunner and apply schema catalog for a given database.
+ * This is the main entry point for database classes.
+ */
+export function ensureDatabaseSchema(db: Db, dbType: DbType): void {
+  const runner = new MigrationRunner(db);
+  runner.applySchemaCatalog(dbType);
+}
+
+// Re-export types
+export type { Migration, DbType, TableDefinition, ViewDefinition, FtsDefinition, SchemaCatalog } from './schema-definitions.js';