principles-disciple 1.107.0 → 1.108.0

package/src/core/pain-signal.ts

@@ -1,22 +0,0 @@
-import {
-  type PainSeverity as CorePainSeverity,
-  type PainSignal as CorePainSignal,
-  type PainSignalValidationResult as CorePainSignalValidationResult,
-  PainSeveritySchema,
-  PainSignalSchema,
-  deriveSeverity,
-  validatePainSignal,
-} from '@principles/core/runtime-v2';
-
-export type PainSeverity = CorePainSeverity;
-export const PainSeverity = PainSeveritySchema;
-
-export type PainSignal = CorePainSignal;
-export type PainSignalValidationResult = CorePainSignalValidationResult;
-
-export {
-  PainSignalSchema,
-  deriveSeverity,
-  validatePainSignal,
-};
-

package/src/core/principle-injector.ts

@@ -1,84 +0,0 @@
-/**
- * PrincipleInjector interface for the Evolution SDK.
- *
- * Wraps the existing principle injection logic into a framework-agnostic
- * contract. Per D-05, this delegates to selectPrinciplesForInjection and
- * formatPrinciple without any behavioral changes.
- *
- * Per D-06, InjectionContext contains only generic fields (domain, sessionId,
- * budgetChars) -- no framework-specific fields.
- */
-import type { InjectablePrinciple } from './principle-injection.js';
-import { selectPrinciplesForInjection, formatPrinciple } from './principle-injection.js';
-
-// ---------------------------------------------------------------------------
-// InjectionContext
-// ---------------------------------------------------------------------------
-
-/** Generic injection context -- no framework-specific fields. */
-export interface InjectionContext {
-  /** Domain context (e.g., 'coding', 'writing', 'analysis') */
-  domain: string;
-  /** Session identifier */
-  sessionId: string;
-  /** Maximum characters allowed for injected principles */
-  budgetChars: number;
-}
-
-// ---------------------------------------------------------------------------
-// PrincipleInjector Interface
-// ---------------------------------------------------------------------------
-
-/**
- * Framework-agnostic principle injection interface.
- *
- * Wraps the existing budget-aware selection and formatting logic.
- * Framework adapters convert their context to InjectionContext before calling.
- */
-export interface PrincipleInjector {
-  /**
-   * Select principles relevant for injection within a character budget.
-   * Delegates to selectPrinciplesForInjection from principle-injection.ts.
-   *
-   * @param principles - All available principles to select from
-   * @param context - Generic injection context with budget constraint
-   * @returns Selected principles in injection order
-   */
-  getRelevantPrinciples(
-    principles: InjectablePrinciple[],
-    context: InjectionContext,
-  ): InjectablePrinciple[];
-
-  /**
-   * Format a single principle for prompt injection.
-   * Delegates to formatPrinciple from principle-injection.ts.
-   *
-   * Format: "- [ID] text"
-   *
-   * @param principle - The principle to format
-   * @returns Formatted string for prompt injection
-   */
-  formatForInjection(principle: InjectablePrinciple): string;
-}
-
-// ---------------------------------------------------------------------------
-// Default Implementation
-// ---------------------------------------------------------------------------
-
-/**
- * Default implementation that delegates to existing functions.
- * Zero rewrite risk -- behavior is identical to calling the functions directly.
- */
-export class DefaultPrincipleInjector implements PrincipleInjector {
-  getRelevantPrinciples(
-    principles: InjectablePrinciple[],
-    context: InjectionContext,
-  ): InjectablePrinciple[] {
-    const result = selectPrinciplesForInjection(principles, context.budgetChars);
-    return result.selected;
-  }
-
-  formatForInjection(principle: InjectablePrinciple): string {
-    return formatPrinciple(principle);
-  }
-}

package/src/core/principle-tree-migration.ts

@@ -1,196 +0,0 @@
-/**
- * Principle Tree Migration — Migrates trainingStore to tree.principles
- *
- * This migration handles the Phase 11 gap: existing principles in trainingStore
- * were never written to tree.principles, blocking the Rule/Implementation layer.
- *
- * Usage:
- *   - Called automatically by migratePrincipleTree() during plugin initialization
- *   - Or run manually: node scripts/migrate-principle-tree.mjs <workspace-dir>
- */
-
-import {
-  loadLedger,
-  saveLedger,
-  type LedgerPrinciple,
-} from './principle-tree-ledger.js';
-import type { LegacyPrincipleTrainingState } from './principle-tree-ledger.js';
-import { SystemLogger } from './system-logger.js';
-
-export interface PrincipleTreeMigrationResult {
-  migratedCount: number;
-  skippedCount: number;
-  errorCount: number;
-  details: {
-    principleId: string;
-    status: 'migrated' | 'skipped' | 'error';
-    reason?: string;
-  }[];
-}
-
-/**
- * Check if migration is needed by comparing trainingStore and tree.principles
- */
-export function needsMigration(stateDir: string): boolean {
-  const ledger = loadLedger(stateDir);
-  return Object.keys(ledger.trainingStore).some((principleId) => !ledger.tree.principles[principleId]);
-}
-
-/**
- * Create a minimal LedgerPrinciple from LegacyPrincipleTrainingState
- */
-function trainingStateToTreePrinciple(
-  principleId: string,
-  state: LegacyPrincipleTrainingState,
-  now: string
-): LedgerPrinciple {
-  return {
-    id: principleId,
-    version: 1,
-    text: `Principle ${principleId}`, // Minimal text, will be enriched from PRINCIPLES.md if available
-    triggerPattern: '', // Unknown from legacy data
-    action: '', // Unknown from legacy data
-     
-    status: mapInternalizationStatusToPrincipleStatus(state.internalizationStatus),
-    priority: 'P1', // Default priority
-    scope: 'general',
-    evaluability: state.evaluability,
-    valueScore: 0,
-    adherenceRate: state.complianceRate * 100, // Convert 0-1 to 0-100
-    painPreventedCount: 0,
-    derivedFromPainIds: [],
-    ruleIds: [],
-    conflictsWithPrincipleIds: [],
-    createdAt: now,
-    updatedAt: now,
-  };
-}
-
-/**
- * Map internalization status to principle status
- */
-function mapInternalizationStatusToPrincipleStatus(
-  status: LegacyPrincipleTrainingState['internalizationStatus']
-): 'candidate' | 'active' | 'deprecated' {
-  switch (status) {
-    case 'internalized':
-    case 'deployed_pending_eval':
-      return 'active';
-    case 'regressed':
-    case 'needs_training':
-      return 'candidate';
-    case 'prompt_only':
-    case 'in_training':
-      return 'candidate';
-    default:
-      return 'candidate';
-  }
-}
-
-/**
- * Migrate trainingStore principles to tree.principles
- *
- * This function is idempotent: it only migrates principles that don't exist
- * in tree.principles yet.
- */
-     
-export function migratePrincipleTree(
-  stateDir: string,
-  workspaceDir?: string
-): PrincipleTreeMigrationResult {
-  const result: PrincipleTreeMigrationResult = {
-    migratedCount: 0,
-    skippedCount: 0,
-    errorCount: 0,
-    details: [],
-  };
-
-  try {
-    const ledger = loadLedger(stateDir);
-    const now = new Date().toISOString();
-
-    for (const [principleId, state] of Object.entries(ledger.trainingStore)) {
-      // Skip if already exists in tree.principles
-      if (ledger.tree.principles[principleId]) {
-        result.skippedCount++;
-        result.details.push({
-          principleId,
-          status: 'skipped',
-          reason: 'Already exists in tree.principles',
-        });
-        continue;
-      }
-
-      try {
-        const treePrinciple = trainingStateToTreePrinciple(principleId, state, now);
-        const nextLedger = loadLedger(stateDir);
-        if (!nextLedger.tree.principles[principleId]) {
-          nextLedger.tree.principles[principleId] = treePrinciple;
-          nextLedger.tree.lastUpdated = now;
-          saveLedger(stateDir, nextLedger);
-        }
-
-        result.migratedCount++;
-        result.details.push({
-          principleId,
-          status: 'migrated',
-        });
-
-        if (workspaceDir) {
-          SystemLogger.log(
-            workspaceDir,
-            'PRINCIPLE_TREE_MIGRATED',
-            `Migrated ${principleId} from trainingStore to tree.principles`
-          );
-        }
-      } catch (err) {
-        result.errorCount++;
-        result.details.push({
-          principleId,
-          status: 'error',
-          reason: String(err),
-        });
-
-        if (workspaceDir) {
-          SystemLogger.log(
-            workspaceDir,
-            'PRINCIPLE_TREE_MIGRATION_ERROR',
-            `Failed to migrate ${principleId}: ${String(err)}`
-          );
-        }
-      }
-    }
-
-    if (workspaceDir && result.migratedCount > 0) {
-      SystemLogger.log(
-        workspaceDir,
-        'PRINCIPLE_TREE_MIGRATION_COMPLETE',
-        `Migrated ${result.migratedCount} principles to tree.principles (${result.skippedCount} skipped, ${result.errorCount} errors)`
-      );
-    }
-  } catch (err) {
-    if (workspaceDir) {
-      SystemLogger.log(
-        workspaceDir,
-        'PRINCIPLE_TREE_MIGRATION_FAILED',
-        `Migration failed: ${String(err)}`
-      );
-    }
-  }
-
-  return result;
-}
-
-/**
- * Run migration if needed (called during plugin initialization)
- */
-export function runMigrationIfNeeded(
-  stateDir: string,
-  workspaceDir?: string
-): PrincipleTreeMigrationResult | null {
-  if (!needsMigration(stateDir)) {
-    return null;
-  }
-
-  return migratePrincipleTree(stateDir, workspaceDir);
-}

package/src/core/storage-adapter.ts

@@ -1,65 +0,0 @@
-/**
- * StorageAdapter interface for the Evolution SDK.
- *
- * This interface decouples the evolution engine from specific persistence
- * implementations (file system, SQLite, remote API). All higher-level
- * modules that need to read or mutate the principle ledger should depend
- * on this interface rather than importing principle-tree-ledger directly.
- *
- * The interface uses HybridLedgerStore from principle-tree-ledger as the
- * canonical store shape, but future adapters can map alternative backends
- * to this shape.
- */
-import type { HybridLedgerStore } from './principle-tree-ledger.js';
-
-// ---------------------------------------------------------------------------
-// StorageAdapter Interface
-// ---------------------------------------------------------------------------
-
-/**
- * Abstract storage adapter for the principle ledger.
- *
- * Implementations must guarantee:
- * - Atomic writes (no partial/corrupted state on crash)
- * - Thread-safe concurrent access (locking or equivalent)
- * - Consistent read-after-write visibility
- *
- * The `mutateLedger` method is the preferred way to perform read-modify-write
- * cycles. It encapsulates locking so callers never need to manage it.
- */
-export interface StorageAdapter {
-  /**
-   * Load the current ledger state from persistence.
-   *
-   * If no persisted state exists (first run), returns an empty store.
-   */
-  loadLedger(): Promise<HybridLedgerStore>;
-
-  /**
-   * Persist the full ledger state.
-   *
-   * Must be atomic — partial writes must never be visible to readers.
-   */
-  saveLedger(store: HybridLedgerStore): Promise<void>;
-
-  /**
-   * Perform a read-modify-write cycle with automatic locking.
-   *
-   * The `mutate` function receives the current store and may return a
-   * value synchronously or via Promise. The store is persisted after
-   * the mutate function resolves, regardless of its return value.
-   *
-   * If two concurrent `mutateLedger` calls overlap, one must wait for
-   * the other to complete (pessimistic locking) or retry on conflict
-   * (optimistic locking). The choice is left to the implementation.
-   *
-   * @example
-   * ```ts
-   * const count = await adapter.mutateLedger((store) => {
-   *   store.tree.principles['p-1'] = newPrinciple;
-   *   return Object.keys(store.tree.principles).length;
-   * });
-   * ```
-   */
-  mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T>;
-}

package/src/core/telemetry-event.ts

@@ -1,109 +0,0 @@
-/**
- * TelemetryEvent schema for the Evolution SDK.
- *
- * TypeBox schema describing the shape of in-process evolution events.
- * Per D-07, this is a documentation artifact -- the existing EvolutionLogger
- * output should conform to this schema. No new TelemetryService is created.
- *
- * Per D-08, covers the 3 core events aligned with EvolutionHook:
- * - pain_detected (maps to EvolutionStage 'pain_detected')
- * - principle_candidate_created (maps to EvolutionStage 'principle_generated')
- * - principle_promoted (maps to EvolutionStage 'completed')
- *
- * Injection and storage events are out of scope for this phase.
- */
-import { Type, type Static } from '@sinclair/typebox';
-import { Value } from '@sinclair/typebox/value';
-
-// ---------------------------------------------------------------------------
-// Event Type Union
-// ---------------------------------------------------------------------------
-
-/**
- * The 3 core telemetry event types, aligned with EvolutionHook methods.
- *
- * Mapping to existing EvolutionLogger stages:
- * - pain_detected -> EvolutionStage 'pain_detected'
- * - principle_candidate_created -> EvolutionStage 'principle_generated'
- * - principle_promoted -> EvolutionStage 'completed'
- */
-export const TelemetryEventType = Type.Union([
-  Type.Literal('pain_detected'),
-  Type.Literal('principle_candidate_created'),
-  Type.Literal('principle_promoted'),
-]);
-
-export type TelemetryEventType = Static<typeof TelemetryEventType>;
-
-// ---------------------------------------------------------------------------
-// TelemetryEvent Schema
-// ---------------------------------------------------------------------------
-
-/**
- * Schema for an in-process telemetry event.
- *
- * Fields align with existing EvolutionLogEntry:
- * - traceId <-> EvolutionLogEntry.traceId
- * - timestamp <-> EvolutionLogEntry.timestamp
- * - sessionId <-> EvolutionLogEntry.sessionId
- * - payload <-> EvolutionLogEntry.metadata
- *
- * No PII fields. The agentId field is optional and contains only
- * system identifiers (e.g., 'main', 'builder'), never user data.
- */
-export const TelemetryEventSchema = Type.Object({
-  /** Event type (one of the 3 core types) */
-  eventType: TelemetryEventType,
-  /** Correlation trace ID for linking events across the pipeline */
-  traceId: Type.String({ minLength: 1 }),
-  /** ISO 8601 timestamp */
-  timestamp: Type.String({ minLength: 1 }),
-  /** Session identifier */
-  sessionId: Type.String(),
-  /** Agent identifier (system identifier only, no PII) */
-  agentId: Type.Optional(Type.String()),
-  /** Event-specific payload */
-  payload: Type.Record(Type.String(), Type.Unknown()),
-});
-
-export type TelemetryEvent = Static<typeof TelemetryEventSchema>;
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-export interface TelemetryEventValidationResult {
-  valid: boolean;
-  errors: string[];
-  event?: TelemetryEvent;
-}
-
-/**
- * Validates an arbitrary object against the TelemetryEvent schema.
- *
- * Returns a structured result with:
- * - `valid`: whether the input conforms to the schema
- * - `errors`: human-readable list of validation failures
- * - `event`: the typed event (only present when valid)
- */
-export function validateTelemetryEvent(input: unknown): TelemetryEventValidationResult {
-  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-    return { valid: false, errors: ['Input must be a non-null object'] };
-  }
-
-  const errors = [...Value.Errors(TelemetryEventSchema, input)];
-  if (errors.length > 0) {
-    return {
-      valid: false,
-      errors: errors.map(
-        (e) => `${e.path ? `${e.path}: ` : ''}${e.message}`,
-      ),
-    };
-  }
-
-  return {
-    valid: true,
-    errors: [],
-    event: Value.Cast(TelemetryEventSchema, input) as TelemetryEvent,
-  };
-}