principles-disciple 1.71.0 → 1.73.0

package/src/core/principle-internalization/principle-lifecycle-service.ts

@@ -6,27 +6,28 @@ import {
 } from '../principle-tree-ledger.js';
 import type { PrincipleValueMetrics } from '../../types/principle-tree-schema.js';
 import { buildLifecycleReadModel, type LifecycleReadModel, type PrincipleLifecycleEvidence } from './lifecycle-read-model.js';
+import { FilesystemLifecycleDatasource } from './filesystem-lifecycle-datasource.js';
 import {
   computePrincipleAdherence,
   computeRuleMetrics,
   type PrincipleAdherenceResult,
   type RuleMetricResult,
-} from './lifecycle-metrics.js';
+} from '@principles/core/runtime-v2';
 import {
   assessDeprecatedReadiness,
   type DeprecatedReadinessAssessment,
-} from './deprecated-readiness.js';
+} from '@principles/core/runtime-v2';
 import {
-  recommendInternalizationRoute,
-  type InternalizationRouteRecommendation,
-} from './internalization-routing-policy.js';
+  recommendLifecycleRoute,
+  type LifecycleRouteRecommendation,
+} from '@principles/core/runtime-v2';
 
 export interface RecomputedPrincipleLifecycle {
   principleId: string;
   ruleMetrics: Record<string, RuleMetricResult>;
   adherence: PrincipleAdherenceResult;
   deprecatedReadiness: DeprecatedReadinessAssessment;
-  routeRecommendation: InternalizationRouteRecommendation;
+  routeRecommendation: LifecycleRouteRecommendation;
 }
 
 export interface PrincipleLifecycleAssessment {
@@ -35,7 +36,7 @@ export interface PrincipleLifecycleAssessment {
   ruleMetrics: Record<string, RuleMetricResult>;
   adherence: PrincipleAdherenceResult;
   deprecatedReadiness: DeprecatedReadinessAssessment;
-  routeRecommendation: InternalizationRouteRecommendation;
+  routeRecommendation: LifecycleRouteRecommendation;
 }
 
      
@@ -83,7 +84,8 @@ export class PrincipleLifecycleService {
   }
 
   buildReadModel(): LifecycleReadModel {
-    return buildLifecycleReadModel(this.workspaceDir, this.stateDir);
+    const datasource = new FilesystemLifecycleDatasource(this.workspaceDir, this.stateDir);
+    return buildLifecycleReadModel(datasource);
   }
 
   listAssessments(readModel = this.buildReadModel()): PrincipleLifecycleAssessment[] {
@@ -100,7 +102,7 @@ export class PrincipleLifecycleService {
         ruleMetrics,
         adherence,
       );
-      const routeRecommendation = recommendInternalizationRoute(
+      const routeRecommendation = recommendLifecycleRoute(
         principleEvidence,
         ruleMetrics,
         adherence,
@@ -117,7 +119,7 @@ export class PrincipleLifecycleService {
     });
   }
 
-  listRouteRecommendations(readModel = this.buildReadModel()): InternalizationRouteRecommendation[] {
+  listRouteRecommendations(readModel = this.buildReadModel()): LifecycleRouteRecommendation[] {
     return this.listAssessments(readModel).map((assessment) => assessment.routeRecommendation);
   }
 

package/src/core/principle-tree-ledger-adapter.ts

@@ -0,0 +1,145 @@
+import { CandidateIntakeError, INTAKE_ERROR_CODES } from '@principles/core/runtime-v2';
+import type { LedgerAdapter, LedgerPrincipleEntry } from '@principles/core/runtime-v2';
+import { addPrincipleToLedger, loadLedger } from './principle-tree-ledger.js';
+import type { LedgerPrinciple } from './principle-tree-ledger.js';
+
+const VALID_EVALUABILITIES = ['deterministic', 'weak_heuristic', 'manual_only'] as const;
+
+/**
+ * PrincipleTreeLedgerAdapter — bridges 11-field LedgerPrincipleEntry to 18+ field LedgerPrinciple.
+ *
+ * This adapter maintains an in-memory idempotency map. Create once and reuse
+ * across calls within the same process lifetime. Do not create a new instance
+ * per intake call.
+ */
+export class PrincipleTreeLedgerAdapter implements LedgerAdapter {
+  #stateDir: string;
+  #entryMap = new Map<string, LedgerPrincipleEntry>();
+
+  constructor(opts: { stateDir: string }) {
+    this.#stateDir = opts.stateDir;
+  }
+
+  /**
+   * Write a probation entry to the ledger.
+   *
+   * Idempotency: if the same candidateId was already written, returns the
+   * existing entry without writing again.
+   *
+   * @throws CandidateIntakeError with code LEDGER_WRITE_FAILED on write failure.
+   */
+  writeProbationEntry(entry: LedgerPrincipleEntry): LedgerPrincipleEntry {
+    const candidateId = this.#extractCandidateId(entry.sourceRef);
+    const existing = this.#entryMap.get(candidateId);
+    if (existing) return existing;
+
+    const ledgerPrinciple = this.#expandToLedgerPrinciple(entry, candidateId);
+
+    try {
+      addPrincipleToLedger(this.#stateDir, ledgerPrinciple);
+    } catch (err) {
+      throw new CandidateIntakeError(
+        INTAKE_ERROR_CODES.LEDGER_WRITE_FAILED,
+        `Failed to write principle ${entry.id} to ledger: ${String(err)}`,
+        { cause: err },
+      );
+    }
+
+    this.#entryMap.set(candidateId, entry);
+    return entry;
+  }
+
+  /**
+   * Check if a ledger entry already exists for a given candidate.
+   *
+   * Queries both the in-memory Map (fast path for same-process repeat calls)
+   * and the ledger file (for cross-process idempotency across CLI invocations).
+   *
+   * @returns The existing LedgerPrincipleEntry if found, null otherwise.
+   */
+  existsForCandidate(candidateId: string): LedgerPrincipleEntry | null {
+    // Fast path: check in-memory Map (covers same-process repeat calls)
+    const cached = this.#entryMap.get(candidateId);
+    if (cached) return cached;
+
+    // Cross-process path: check ledger file by derivedFromPainIds
+    const ledger = loadLedger(this.#stateDir);
+    const found = Object.values(ledger.tree.principles).find((p) =>
+      p.derivedFromPainIds.includes(candidateId),
+    );
+    if (!found) return null;
+
+    // Reconstruct LedgerPrincipleEntry from LedgerPrinciple fields
+    // Note: sourceRef, artifactRef, taskRef are not stored in LedgerPrinciple,
+    // so we cannot fully reconstruct the original LedgerPrincipleEntry.
+    // Return minimal entry sufficient for idempotency signaling.
+    return {
+      id: found.id,
+      title: '',
+      status: 'probation' as const,
+      sourceRef: `candidate://${candidateId}`,
+      artifactRef: '',
+      taskRef: '',
+      text: found.text,
+      triggerPattern: found.triggerPattern,
+      action: found.action,
+      evaluability: 'weak_heuristic' as const,
+      createdAt: found.createdAt,
+    } as LedgerPrincipleEntry;
+  }
+
+  /**
+   * Extract candidateId from sourceRef by stripping the 'candidate://' prefix.
+   *
+   * @internal
+   */
+  #extractCandidateId(sourceRef: string): string {
+    if (sourceRef.startsWith('candidate://')) {
+      return sourceRef.slice('candidate://'.length);
+    }
+    return sourceRef;
+  }
+
+  /**
+   * Expand an 11-field LedgerPrincipleEntry to an 18+ field LedgerPrinciple.
+   *
+   * Applies the field expansion table from CONTEXT.md:
+   * - status: 'probation' → 'candidate'
+   * - triggerPattern/action: pass through (empty string if absent)
+   * - All defaults applied per CONTEXT.md expansion table
+   * - sourceRef/artifactRef/taskRef are NOT written to LedgerPrinciple (not stored)
+   * - title is NOT written to LedgerPrinciple — intentionally excluded; title
+   *   is available in LedgerPrincipleEntry but LedgerPrinciple has no title field
+   *
+   * @internal
+   */
+  #expandToLedgerPrinciple(entry: LedgerPrincipleEntry, candidateId: string): LedgerPrinciple {
+    if (!VALID_EVALUABILITIES.includes(entry.evaluability as (typeof VALID_EVALUABILITIES)[number])) {
+      throw new CandidateIntakeError(
+        INTAKE_ERROR_CODES.INPUT_INVALID,
+        `Invalid evaluability value: ${entry.evaluability}. Must be one of: ${VALID_EVALUABILITIES.join(', ')}`,
+      );
+    }
+
+    const result: LedgerPrinciple = {
+      id: entry.id,
+      version: 1,
+      text: entry.text,
+      triggerPattern: entry.triggerPattern ?? '',
+      action: entry.action ?? '',
+      status: 'candidate',
+      evaluability: entry.evaluability,
+      priority: 'P1',
+      scope: 'general',
+      valueScore: 0,
+      adherenceRate: 0,
+      painPreventedCount: 0,
+      derivedFromPainIds: [candidateId],
+      ruleIds: [],
+      conflictsWithPrincipleIds: [],
+      createdAt: entry.createdAt,
+      updatedAt: entry.createdAt,
+    };
+    return result;
+  }
+}

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

@@ -294,7 +294,11 @@ function readLedgerFromFile(filePath: string): HybridLedgerStore {
   }
 
   try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as unknown;
+    const content = fs.readFileSync(filePath, 'utf-8');
+    if (!content || content.trim() === '') {
+      return { trainingStore: {}, tree: createEmptyTree() };
+    }
+    const parsed = JSON.parse(content) as unknown;
     const raw = isRecord(parsed) ? parsed : {};
     // #219: Handle both formats:
     // - New format: { trainingStore: {...}, tree: {...} }
@@ -305,11 +309,9 @@ function readLedgerFromFile(filePath: string): HybridLedgerStore {
       trainingStore: parseLegacyTrainingStore(trainingStoreRaw),
       tree: parseTree(treeRaw),
     };
-  } catch {
-    return {
-      trainingStore: {},
-      tree: createEmptyTree(),
-    };
+  } catch (err) {
+    console.error(`[principle-tree-ledger] Failed to load ledger from ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    return { trainingStore: {}, tree: createEmptyTree() };
   }
 }
 

package/src/core/reflection/reflection-context.ts

@@ -1,62 +1,20 @@
-/**
- * ReflectionContextCollector — Unified Pipeline Input
- * ====================================================
- *
- * PURPOSE: Collect all grounding context for a principle into a single
- * ReflectionContext object. This is the input to the nocturnal reflection
- * pipeline: principle + painEvents + sessionSnapshot + lineage.
- *
- * DESIGN DECISIONS:
- * - If a principle has no derivedFromPainIds, collect() returns null
- *   (nothing to ground code on).
- * - painId -> sessionId resolution is a known gap. For now, we attempt
- *   best-effort lookup but return what we have with sessionSnapshot = null
- *   if we can't resolve.
- *
- * REUSES:
- * - principle-tree-ledger: loadLedger() for principle lookup
- * - nocturnal-trajectory-extractor: for session snapshots
- * - trajectory: TrajectoryDatabase for pain event queries
- */
-
 import { loadLedger, type LedgerPrinciple } from '../principle-tree-ledger.js';
-import {
-  NocturnalTrajectoryExtractor,
-  type NocturnalPainEvent,
-  type NocturnalSessionSnapshot,
-} from '../nocturnal-trajectory-extractor.js';
 import type { TrajectoryDatabase } from '../trajectory.js';
 import type { Principle } from '../../types/principle-tree-schema.js';
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * Unified reflection context for the nocturnal pipeline.
- */
 export interface ReflectionContext {
-  /** The principle being reflected upon */
   principle: Principle;
-  /** Pain events associated with this principle (via derivedFromPainIds) */
-  painEvents: NocturnalPainEvent[];
-  /** Session snapshot if resolvable, null otherwise */
-  sessionSnapshot: NocturnalSessionSnapshot | null;
-  /** Lineage metadata connecting principle to source pain signals */
-  lineage: {
-    sourcePainIds: string[];
-    sessionId: string | null;
-  };
+  painEvents: Array<{ source: string; score: number; severity: string | null; reason: string | null; createdAt: string }>;
+  sessionSnapshot: {
+    toolCalls: Array<{
+      toolName: string;
+      outcome: string;
+      filePath: string | null;
+      errorType: string | null;
+    }>;
+  } | null;
 }
 
-// ---------------------------------------------------------------------------
-// Collector
-// ---------------------------------------------------------------------------
-
-/**
- * Collects ReflectionContext for principles by joining ledger data with
- * trajectory data.
- */
 export class ReflectionContextCollector {
   private readonly stateDir: string;
   private readonly trajectory: TrajectoryDatabase;
@@ -66,13 +24,6 @@ export class ReflectionContextCollector {
     this.trajectory = trajectory;
   }
 
-  /**
-   * Collect full reflection context for a single principle.
-   *
-   * Returns null if:
-   * - The principle is not found in the ledger
-   * - The principle has no derivedFromPainIds (nothing to ground on)
-   */
   collect(principleId: string): ReflectionContext | null {
     const ledger = loadLedger(this.stateDir);
     const principle = ledger.tree.principles[principleId];
@@ -88,11 +39,6 @@ export class ReflectionContextCollector {
     return this.buildContext(principle);
   }
 
-  /**
-   * Collect reflection contexts for multiple principles, optionally filtered.
-   *
-   * Skips principles without derivedFromPainIds.
-   */
   collectBatch(filter?: { status?: string }): ReflectionContext[] {
     const ledger = loadLedger(this.stateDir);
     const principles = Object.values(ledger.tree.principles);
@@ -100,12 +46,10 @@ export class ReflectionContextCollector {
     const results: ReflectionContext[] = [];
 
     for (const principle of principles) {
-      // Apply status filter if provided
       if (filter?.status && principle.status !== filter.status) {
         continue;
       }
 
-      // Skip principles without pain grounding
       if (!principle.derivedFromPainIds || principle.derivedFromPainIds.length === 0) {
         continue;
       }
@@ -119,62 +63,26 @@ export class ReflectionContextCollector {
     return results;
   }
 
-  // -----------------------------------------------------------------------
-  // Private helpers
-  // -----------------------------------------------------------------------
-
-  /**
-   * Build a ReflectionContext from a principle.
-   *
-   * Attempts to resolve painIds to sessions via best-effort lookup.
-   * Since painId -> sessionId mapping is a known gap, we may return
-   * empty painEvents and null sessionSnapshot.
-   */
   private buildContext(principle: LedgerPrinciple): ReflectionContext {
     const sourcePainIds = principle.derivedFromPainIds;
-
-    // Best-effort: try to find a session containing pain events related to this principle.
-    // The pain_events table uses auto-increment IDs, not the string painIds stored in
-    // derivedFromPainIds. This is the known gap — for now we attempt session resolution
-    // but gracefully handle the case where we can't match.
-    const { painEvents, sessionId } = this.resolvePainEvents(sourcePainIds);
-
-    // If we found a session, get the snapshot
-    let sessionSnapshot: NocturnalSessionSnapshot | null = null;
-    if (sessionId) {
-      const extractor = new NocturnalTrajectoryExtractor(this.trajectory);
-      sessionSnapshot = extractor.getNocturnalSessionSnapshot(sessionId);
-    }
+    const { painEvents } = this.resolvePainEvents(sourcePainIds);
 
     return {
       principle,
       painEvents,
-      sessionSnapshot,
-      lineage: {
-        sourcePainIds,
-        sessionId,
-      },
+      sessionSnapshot: null,
     };
   }
 
-  /**
-   * Attempt to resolve painIds to actual pain events and a session.
-   *
-   * Two-phase strategy:
-   * 1. Exact ID match: sourcePainIds are stringified pain_events row IDs.
-   *    If any match String(pe.id) exactly, use those and stop.
-   * 2. Heuristic fallback: substring match on reason/origin fields.
-   *    Only used when no exact matches are found.
-   */
   private resolvePainEvents(sourcePainIds: string[]): {
-    painEvents: NocturnalPainEvent[];
+    painEvents: Array<{ source: string; score: number; severity: string | null; reason: string | null; createdAt: string }>;
     sessionId: string | null;
   } {
     const sessions = this.trajectory.listRecentSessions({ limit: 100 });
     const sourcePainIdSet = new Set(sourcePainIds);
 
-    const exactMatches: NocturnalPainEvent[] = [];
-    const heuristicMatches: NocturnalPainEvent[] = [];
+    const exactMatches: Array<{ source: string; score: number; severity: string | null; reason: string | null; createdAt: string }> = [];
+    const heuristicMatches: Array<{ source: string; score: number; severity: string | null; reason: string | null; createdAt: string }> = [];
     let exactSessionId: string | null = null;
     let heuristicSessionId: string | null = null;
 
@@ -182,7 +90,6 @@ export class ReflectionContextCollector {
       const sessionPainEvents = this.trajectory.listPainEventsForSession(session.sessionId);
 
       for (const pe of sessionPainEvents) {
-        // Phase 1: exact ID match
         if (sourcePainIdSet.has(String(pe.id))) {
           exactMatches.push({
             source: pe.source,
@@ -197,7 +104,6 @@ export class ReflectionContextCollector {
           continue;
         }
 
-        // Phase 2: heuristic substring match on reason/origin only
         const peText = [pe.reason, pe.origin].filter(Boolean);
         const isMatch = sourcePainIds.some((painId) =>
           peText.some((field) => field?.includes(painId)),
@@ -218,7 +124,6 @@ export class ReflectionContextCollector {
       }
     }
 
-    // Prefer exact matches over heuristic matches
     if (exactMatches.length > 0) {
       return { painEvents: exactMatches, sessionId: exactSessionId };
     }