principles-disciple 1.126.0 → 1.128.0

package/dist/core/principle-compiler/ledger-registrar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ledger Registrar (Task 4)
+ *
+ * Registers a compiled rule into the principle tree ledger:
+ * 1. Creates a LedgerRule with type 'gate', enforcement 'block', status 'proposed'
+ * 2. Creates an Implementation with type 'code', lifecycleState 'active'
+ *
+ * IDEMPOTENCY: If the rule already exists, returns existing registration.
+ * ROLLBACK: If implementation creation fails after rule creation, attempts cleanup.
+ */
+export interface RegisterInput {
+    principleId: string;
+    codeContent: string;
+    coversCondition: string;
+}
+export interface RegisterResult {
+    success: boolean;
+    ruleId: string;
+    implementationId: string;
+    codePath: string;
+}
+/**
+ * Register a compiled rule for a principle in the ledger.
+ *
+ * Idempotent: if rule already exists, returns existing registration.
+ * Atomic: if implementation creation fails, rolls back the rule.
+ */
+export declare function registerCompiledRule(stateDir: string, input: RegisterInput): RegisterResult;

package/dist/core/principle-compiler/ledger-registrar.js

@@ -0,0 +1,95 @@
+/**
+ * Ledger Registrar (Task 4)
+ *
+ * Registers a compiled rule into the principle tree ledger:
+ * 1. Creates a LedgerRule with type 'gate', enforcement 'block', status 'proposed'
+ * 2. Creates an Implementation with type 'code', lifecycleState 'active'
+ *
+ * IDEMPOTENCY: If the rule already exists, returns existing registration.
+ * ROLLBACK: If implementation creation fails after rule creation, attempts cleanup.
+ */
+import { createRule, createImplementation, loadLedger, deleteRule } from '../principle-tree-ledger.js';
+/**
+ * Register a compiled rule for a principle in the ledger.
+ *
+ * Idempotent: if rule already exists, returns existing registration.
+ * Atomic: if implementation creation fails, rolls back the rule.
+ */
+export function registerCompiledRule(stateDir, input) {
+    const { principleId, codeContent, coversCondition } = input;
+    const ruleId = `R_${principleId}_auto`;
+    const implementationId = `IMPL_${principleId}_auto`;
+    const codePath = `compiled-rules/${principleId}/rule.ts`;
+    // Idempotency: skip if rule already exists
+    const existingLedger = loadLedger(stateDir);
+    if (existingLedger.tree.rules[ruleId]) {
+        const existingRule = existingLedger.tree.rules[ruleId];
+        return {
+            success: true,
+            ruleId,
+            implementationId: existingRule.implementationIds[0] ?? implementationId,
+            codePath,
+        };
+    }
+    const now = new Date().toISOString();
+    // Step 1: Create the rule
+    // FIX: Auto-generated rules default to 'warn' enforcement (not 'block') until:
+    // - replay evaluation passes
+    // - coverage confirmation
+    // - human approval
+    // This prevents P_001-style false positives from blocking normal edits.
+    const rule = {
+        id: ruleId,
+        version: 1,
+        name: `Auto-compiled rule for ${principleId}`,
+        description: `Automatically compiled gate rule generated from principle ${principleId}`,
+        type: 'gate',
+        triggerCondition: coversCondition,
+        enforcement: 'warn',
+        action: codeContent,
+        principleId,
+        status: 'proposed',
+        coverageRate: 0,
+        falsePositiveRate: 0,
+        implementationIds: [],
+        createdAt: now,
+        updatedAt: now,
+    };
+    createRule(stateDir, rule);
+    // Step 2: Create the implementation (with rollback on failure)
+    try {
+        const implementation = {
+            id: implementationId,
+            ruleId,
+            type: 'code',
+            path: codePath,
+            version: '1',
+            coversCondition,
+            coveragePercentage: 100,
+            // FIX: Start as 'candidate' instead of 'active'.
+            // RuleHost only loads lifecycleState='active' implementations.
+            // This means auto-generated rules will NOT block until explicitly
+            // promoted to 'active' after replay evaluation + human approval.
+            lifecycleState: 'candidate',
+            createdAt: now,
+            updatedAt: now,
+        };
+        createImplementation(stateDir, implementation);
+    }
+    catch (implError) {
+        // Rollback: remove the orphaned rule
+        try {
+            deleteRule(stateDir, ruleId);
+        }
+        catch {
+            // Best-effort rollback — log but don't mask the original error
+        }
+        throw implError;
+    }
+    return {
+        success: true,
+        ruleId,
+        implementationId,
+        codePath,
+    };
+}

package/{src/core/principle-compiler/template-generator.ts → dist/core/principle-compiler/template-generator.d.ts}

@@ -4,5 +4,4 @@
  * PRI-44: Pure template generation logic moved to core.
  * This file re-exports for backward compatibility.
  */
-
 export { generateFromTemplate, type PainPattern } from '@principles/core/runtime-v2';

package/dist/core/principle-compiler/template-generator.js

@@ -0,0 +1,7 @@
+/**
+ * Template Generator — Re-export from @principles/core
+ *
+ * PRI-44: Pure template generation logic moved to core.
+ * This file re-exports for backward compatibility.
+ */
+export { generateFromTemplate } from '@principles/core/runtime-v2';

package/{src/core/principle-injection.ts → dist/core/principle-injection.d.ts}

@@ -6,11 +6,5 @@
  * This file is now a thin re-export layer.
  * All pure logic lives in @principles/core/prompt-builder/principle-selection.ts.
  */
-
-// Re-exported from core for backward compatibility with existing imports
-export {
-  formatPrinciple,
-  selectPrinciplesForInjection,
-  DEFAULT_PRINCIPLE_BUDGET,
-} from '@principles/core/prompt-builder';
+export { formatPrinciple, selectPrinciplesForInjection, DEFAULT_PRINCIPLE_BUDGET, } from '@principles/core/prompt-builder';
 export type { InjectablePrinciple, PrincipleSelectionResult } from '@principles/core/prompt-builder';

package/dist/core/principle-injection.js

@@ -0,0 +1,10 @@
+/**
+ * Principle Injection — Budget-Aware Principle Selection
+ *
+ * Phase: PRI-75 Prompt Injection SDK Migration Phase 2
+ *
+ * This file is now a thin re-export layer.
+ * All pure logic lives in @principles/core/prompt-builder/principle-selection.ts.
+ */
+// Re-exported from core for backward compatibility with existing imports
+export { formatPrinciple, selectPrinciplesForInjection, DEFAULT_PRINCIPLE_BUDGET, } from '@principles/core/prompt-builder';

package/dist/core/principle-internalization/filesystem-lifecycle-datasource.d.ts

@@ -0,0 +1,15 @@
+import type { LifecycleDatasource } from '@principles/core/runtime-v2';
+import type { LedgerTreeStore, ReplayReport, ArtifactLineageRecord } from '@principles/core/runtime-v2';
+export declare class LineageSourceRetiredError extends Error {
+    constructor();
+}
+export declare class FilesystemLifecycleDatasource implements LifecycleDatasource {
+    private readonly workspaceDir;
+    private readonly stateDir;
+    private _engine?;
+    constructor(workspaceDir: string, stateDir: string);
+    private get engine();
+    loadLedger(): LedgerTreeStore;
+    listReplayReports(implementationId: string): ReplayReport[];
+    listLineageRecords(_kind: 'behavioral-sample' | 'rule-implementation-candidate'): ArtifactLineageRecord[];
+}

package/dist/core/principle-internalization/filesystem-lifecycle-datasource.js

@@ -0,0 +1,34 @@
+import { loadLedger } from '../principle-tree-ledger.js';
+import { ReplayEngine } from '../replay-engine.js';
+export class LineageSourceRetiredError extends Error {
+    constructor() {
+        super('Artifact lineage source retired in PRI-230. ' +
+            'The nocturnal-artifact-lineage module has been deleted; ' +
+            'this datasource cannot provide lineage records. ' +
+            'Callers must handle this error explicitly rather than interpreting an empty result as "no lineage".');
+        this.name = 'LineageSourceRetiredError';
+    }
+}
+export class FilesystemLifecycleDatasource {
+    workspaceDir;
+    stateDir;
+    _engine;
+    constructor(workspaceDir, stateDir) {
+        this.workspaceDir = workspaceDir;
+        this.stateDir = stateDir;
+    }
+    get engine() {
+        if (!this._engine)
+            this._engine = new ReplayEngine(this.workspaceDir, this.stateDir);
+        return this._engine;
+    }
+    loadLedger() {
+        return loadLedger(this.stateDir).tree;
+    }
+    listReplayReports(implementationId) {
+        return this.engine.listReports(implementationId);
+    }
+    listLineageRecords(_kind) {
+        throw new LineageSourceRetiredError();
+    }
+}

package/dist/core/principle-internalization/lifecycle-read-model.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lifecycle read model — re-export facade (PRI-56).
+ *
+ * All computation lives in @principles/core/runtime-v2.
+ * This file re-exports types, the core builder, and provides
+ * a backward-compatible path-based wrapper for existing consumers.
+ */
+export type { LifecycleClassificationTotals, RuleReplayEvidence, RuleLiveEvidence, RuleLineageEvidence, ImplementationLifecycleEvidence, RuleLifecycleEvidence, PrincipleLifecycleEvidence, LifecycleReadModel, } from '@principles/core/runtime-v2';
+export { buildLifecycleReadModel } from '@principles/core/runtime-v2';
+export type { LifecycleDatasource } from '@principles/core/runtime-v2';
+export { FilesystemLifecycleDatasource, LineageSourceRetiredError } from './filesystem-lifecycle-datasource.js';
+/**
+ * Backward-compatible wrapper — accepts directory paths like the original API.
+ * Existing consumers (lifecycle-refresh, evolution-status, nocturnal-service)
+ * continue using this without changes.
+ */
+export declare function buildLifecycleReadModelFromPaths(workspaceDir: string, stateDir: string): import("@principles/core/runtime-v2").LifecycleReadModel;

package/{src/core/principle-internalization/lifecycle-read-model.ts → dist/core/principle-internalization/lifecycle-read-model.js}

@@ -5,36 +5,17 @@
  * This file re-exports types, the core builder, and provides
  * a backward-compatible path-based wrapper for existing consumers.
  */
-
-// Re-export lifecycle types from core (PRI-51)
-export type {
-  LifecycleClassificationTotals,
-  RuleReplayEvidence,
-  RuleLiveEvidence,
-  RuleLineageEvidence,
-  ImplementationLifecycleEvidence,
-  RuleLifecycleEvidence,
-  PrincipleLifecycleEvidence,
-  LifecycleReadModel,
-} from '@principles/core/runtime-v2';
-
 // Re-export core builder (PRI-56)
 export { buildLifecycleReadModel } from '@principles/core/runtime-v2';
-
-// Re-export adapter interface (PRI-56)
-export type { LifecycleDatasource } from '@principles/core/runtime-v2';
-
 // Re-export filesystem implementation (PRI-56)
 export { FilesystemLifecycleDatasource, LineageSourceRetiredError } from './filesystem-lifecycle-datasource.js';
-
 import { buildLifecycleReadModel } from '@principles/core/runtime-v2';
 import { FilesystemLifecycleDatasource } from './filesystem-lifecycle-datasource.js';
-
 /**
  * Backward-compatible wrapper — accepts directory paths like the original API.
  * Existing consumers (lifecycle-refresh, evolution-status, nocturnal-service)
  * continue using this without changes.
  */
-export function buildLifecycleReadModelFromPaths(workspaceDir: string, stateDir: string) {
-  return buildLifecycleReadModel(new FilesystemLifecycleDatasource(workspaceDir, stateDir));
+export function buildLifecycleReadModelFromPaths(workspaceDir, stateDir) {
+    return buildLifecycleReadModel(new FilesystemLifecycleDatasource(workspaceDir, stateDir));
 }

package/dist/core/principle-internalization/lifecycle-refresh.d.ts

@@ -0,0 +1,2 @@
+import { type RecomputedPrincipleLifecycle } from './principle-lifecycle-service.js';
+export declare function refreshPrincipleLifecycle(workspaceDir: string, stateDir: string): RecomputedPrincipleLifecycle[];

package/dist/core/principle-internalization/lifecycle-refresh.js

@@ -0,0 +1,4 @@
+import { PrincipleLifecycleService, } from './principle-lifecycle-service.js';
+export function refreshPrincipleLifecycle(workspaceDir, stateDir) {
+    return new PrincipleLifecycleService(workspaceDir, stateDir).recomputeAll();
+}

package/dist/core/principle-internalization/principle-lifecycle-service.d.ts

@@ -0,0 +1,28 @@
+import { type LifecycleReadModel, type PrincipleLifecycleEvidence } from './lifecycle-read-model.js';
+import { type PrincipleAdherenceResult, type RuleMetricResult } from '@principles/core/runtime-v2';
+import { type DeprecatedReadinessAssessment } from '@principles/core/runtime-v2';
+import { type LifecycleRouteRecommendation } from '@principles/core/runtime-v2';
+export interface RecomputedPrincipleLifecycle {
+    principleId: string;
+    ruleMetrics: Record<string, RuleMetricResult>;
+    adherence: PrincipleAdherenceResult;
+    deprecatedReadiness: DeprecatedReadinessAssessment;
+    routeRecommendation: LifecycleRouteRecommendation;
+}
+export interface PrincipleLifecycleAssessment {
+    principle: PrincipleLifecycleEvidence['principle'];
+    summary: PrincipleLifecycleEvidence['summary'];
+    ruleMetrics: Record<string, RuleMetricResult>;
+    adherence: PrincipleAdherenceResult;
+    deprecatedReadiness: DeprecatedReadinessAssessment;
+    routeRecommendation: LifecycleRouteRecommendation;
+}
+export declare class PrincipleLifecycleService {
+    private readonly workspaceDir;
+    private readonly stateDir;
+    constructor(workspaceDir: string, stateDir: string);
+    buildReadModel(): LifecycleReadModel;
+    listAssessments(readModel?: LifecycleReadModel): PrincipleLifecycleAssessment[];
+    listRouteRecommendations(readModel?: LifecycleReadModel): LifecycleRouteRecommendation[];
+    recomputeAll(): RecomputedPrincipleLifecycle[];
+}

package/dist/core/principle-internalization/principle-lifecycle-service.js

@@ -0,0 +1,89 @@
+import { loadLedger, updatePrinciple, updatePrincipleValueMetrics, updateRule, } from '../principle-tree-ledger.js';
+import { buildLifecycleReadModel } from './lifecycle-read-model.js';
+import { FilesystemLifecycleDatasource } from './filesystem-lifecycle-datasource.js';
+import { computePrincipleAdherence, computeRuleMetrics, } from '@principles/core/runtime-v2';
+import { assessDeprecatedReadiness, } from '@principles/core/runtime-v2';
+import { recommendLifecycleRoute, } from '@principles/core/runtime-v2';
+function createValueMetrics(principle, adherence, current) {
+    const violatedCount = principle.summary.repeatedErrorSignal;
+    const totalOpportunities = Math.max(violatedCount + principle.summary.replayReportCount, current?.totalOpportunities ?? 0);
+    const adheredCount = Math.max(0, Math.round((adherence.adherenceRate / 100) * totalOpportunities));
+    return {
+        principleId: principle.principle.id,
+        painPreventedCount: current?.painPreventedCount ?? principle.principle.painPreventedCount,
+        avgPainSeverityPrevented: current?.avgPainSeverityPrevented ?? 0,
+        lastPainPreventedAt: current?.lastPainPreventedAt ?? principle.principle.lastPainPreventedAt,
+        totalOpportunities,
+        adheredCount,
+        violatedCount,
+        implementationCost: current?.implementationCost ?? 0,
+        benefitScore: Number(((current?.painPreventedCount ?? principle.principle.painPreventedCount) *
+            Math.max(current?.avgPainSeverityPrevented ?? 0, 1) *
+            (adherence.adherenceRate / 100)).toFixed(2)),
+        calculatedAt: new Date().toISOString(),
+    };
+}
+export class PrincipleLifecycleService {
+    workspaceDir;
+    stateDir;
+    constructor(workspaceDir, stateDir) {
+        this.workspaceDir = workspaceDir;
+        this.stateDir = stateDir;
+    }
+    buildReadModel() {
+        const datasource = new FilesystemLifecycleDatasource(this.workspaceDir, this.stateDir);
+        return buildLifecycleReadModel(datasource);
+    }
+    listAssessments(readModel = this.buildReadModel()) {
+        return readModel.principles.map((principleEvidence) => {
+            const ruleMetrics = Object.fromEntries(principleEvidence.rules.map((ruleEvidence) => [
+                ruleEvidence.rule.id,
+                computeRuleMetrics(ruleEvidence),
+            ]));
+            const adherence = computePrincipleAdherence(principleEvidence, ruleMetrics);
+            const deprecatedReadiness = assessDeprecatedReadiness(principleEvidence, ruleMetrics, adherence);
+            const routeRecommendation = recommendLifecycleRoute(principleEvidence, ruleMetrics, adherence);
+            return {
+                principle: principleEvidence.principle,
+                summary: principleEvidence.summary,
+                ruleMetrics,
+                adherence,
+                deprecatedReadiness,
+                routeRecommendation,
+            };
+        });
+    }
+    listRouteRecommendations(readModel = this.buildReadModel()) {
+        return this.listAssessments(readModel).map((assessment) => assessment.routeRecommendation);
+    }
+    recomputeAll() {
+        const ledger = loadLedger(this.stateDir);
+        const readModel = this.buildReadModel();
+        const assessments = this.listAssessments(readModel);
+        return assessments.map((assessment) => {
+            const principleEvidence = readModel.principles.find((principle) => principle.principle.id === assessment.principle.id);
+            if (!principleEvidence) {
+                throw new Error(`Missing lifecycle evidence for principle "${assessment.principle.id}".`);
+            }
+            for (const [ruleId, metrics] of Object.entries(assessment.ruleMetrics)) {
+                updateRule(this.stateDir, ruleId, {
+                    coverageRate: metrics.coverageRate,
+                    falsePositiveRate: metrics.falsePositiveRate,
+                    updatedAt: readModel.generatedAt,
+                });
+            }
+            updatePrinciple(this.stateDir, principleEvidence.principle.id, {
+                adherenceRate: assessment.adherence.adherenceRate,
+                updatedAt: readModel.generatedAt,
+            });
+            updatePrincipleValueMetrics(this.stateDir, principleEvidence.principle.id, createValueMetrics(principleEvidence, assessment.adherence, ledger.tree.metrics[principleEvidence.principle.id]));
+            return {
+                principleId: principleEvidence.principle.id,
+                ruleMetrics: assessment.ruleMetrics,
+                adherence: assessment.adherence,
+                deprecatedReadiness: assessment.deprecatedReadiness,
+                routeRecommendation: assessment.routeRecommendation,
+            };
+        });
+    }
+}

package/dist/core/principle-training-state.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Principle Training State Store
+ * ================================================================
+ *
+ * Legacy compatibility adapter over the hybrid principle tree ledger file.
+ * Top-level principle training records remain source-compatible for existing
+ * consumers, while `_tree` is reserved for first-class Rule/Implementation
+ * entities managed by principle-tree-ledger.ts.
+ */
+import type { PrincipleEvaluatorLevel } from './evolution-types.js';
+/** File name for principle training state persistence */
+export declare const PRINCIPLE_TRAINING_FILE = "principle_training_state.json";
+export type InternalizationStatus = 'prompt_only' | 'needs_training' | 'in_training' | 'deployed_pending_eval' | 'internalized' | 'regressed';
+export interface PrincipleTrainingState {
+    principleId: string;
+    evaluability: PrincipleEvaluatorLevel;
+    applicableOpportunityCount: number;
+    observedViolationCount: number;
+    complianceRate: number;
+    violationTrend: number;
+    generatedSampleCount: number;
+    approvedSampleCount: number;
+    includedTrainRunIds: string[];
+    deployedCheckpointIds: string[];
+    lastEvalScore?: number;
+    internalizationStatus: InternalizationStatus;
+}
+export type PrincipleTrainingStore = Record<string, PrincipleTrainingState>;
+export declare function createDefaultPrincipleState(principleId: string): PrincipleTrainingState;
+export declare function loadStore(stateDir: string): PrincipleTrainingStore;
+export declare function saveStore(stateDir: string, store: PrincipleTrainingStore): void;
+export declare function loadStoreAsync(stateDir: string): Promise<PrincipleTrainingStore>;
+export declare function saveStoreAsync(stateDir: string, store: PrincipleTrainingStore): Promise<void>;
+export declare function getPrincipleState(stateDir: string, principleId: string): PrincipleTrainingState;
+export declare function setPrincipleState(stateDir: string, state: PrincipleTrainingState): void;
+export declare function removePrincipleState(stateDir: string, principleId: string): void;
+export declare function listPrincipleIds(stateDir: string): string[];
+export declare function listPrinciplesByStatus(stateDir: string, status: InternalizationStatus): PrincipleTrainingState[];
+export declare function listEvaluablePrinciples(stateDir: string): PrincipleTrainingState[];
+/**
+ * Transition a principle's internalization status to the next valid state.
+ * Throws if the transition is not allowed.
+ *
+ * #212: This enables principles created as `prompt_only` to eventually
+ * become `needs_training` and enter the nocturnal evaluation pipeline.
+ */
+export declare function transitionInternalizationStatus(stateDir: string, principleId: string, nextStatus: InternalizationStatus): void;

package/dist/core/principle-training-state.js

@@ -0,0 +1,113 @@
+/**
+ * Principle Training State Store
+ * ================================================================
+ *
+ * Legacy compatibility adapter over the hybrid principle tree ledger file.
+ * Top-level principle training records remain source-compatible for existing
+ * consumers, while `_tree` is reserved for first-class Rule/Implementation
+ * entities managed by principle-tree-ledger.ts.
+ */
+import { loadLedger, saveLedger, saveLedgerAsync, updateTrainingStore, } from './principle-tree-ledger.js';
+/** File name for principle training state persistence */
+export const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
+export function createDefaultPrincipleState(principleId) {
+    return {
+        principleId,
+        evaluability: 'manual_only',
+        applicableOpportunityCount: 0,
+        observedViolationCount: 0,
+        complianceRate: 0,
+        violationTrend: 0,
+        generatedSampleCount: 0,
+        approvedSampleCount: 0,
+        includedTrainRunIds: [],
+        deployedCheckpointIds: [],
+        internalizationStatus: 'prompt_only',
+    };
+}
+export function loadStore(stateDir) {
+    return ledgerTrainingStore(stateDir);
+}
+export function saveStore(stateDir, store) {
+    const ledger = loadLedger(stateDir);
+    saveLedger(stateDir, {
+        ...ledger,
+        trainingStore: store,
+    });
+}
+export async function loadStoreAsync(stateDir) {
+    return ledgerTrainingStore(stateDir);
+}
+export async function saveStoreAsync(stateDir, store) {
+    const ledger = loadLedger(stateDir);
+    await saveLedgerAsync(stateDir, {
+        ...ledger,
+        trainingStore: store,
+    });
+}
+export function getPrincipleState(stateDir, principleId) {
+    const store = loadStore(stateDir);
+    return store[principleId] ?? createDefaultPrincipleState(principleId);
+}
+export function setPrincipleState(stateDir, state) {
+    updateTrainingStore(stateDir, (store) => {
+        store[state.principleId] = state;
+    });
+}
+export function removePrincipleState(stateDir, principleId) {
+    updateTrainingStore(stateDir, (store) => {
+        delete store[principleId];
+    });
+}
+export function listPrincipleIds(stateDir) {
+    return Object.keys(loadStore(stateDir));
+}
+export function listPrinciplesByStatus(stateDir, status) {
+    return Object.values(loadStore(stateDir)).filter((state) => state.internalizationStatus === status);
+}
+export function listEvaluablePrinciples(stateDir) {
+    return Object.values(loadStore(stateDir)).filter((state) => state.evaluability !== 'manual_only' && state.internalizationStatus !== 'prompt_only');
+}
+// ── #212: Status transition mechanism ───────────────────────────────────────
+/**
+ * Valid transitions in the internalization lifecycle:
+ *
+ * prompt_only → needs_training    (after manual validation or detectorMetadata upgrade)
+ * needs_training → in_training    (training run started)
+ * in_training → deployed_pending_eval  (checkpoint deployed for evaluation)
+ * deployed_pending_eval → internalized (evaluation passed)
+ * any → regressed                 (compliance dropped below threshold)
+ * regressed → needs_training      (retraining triggered)
+ */
+const VALID_TRANSITIONS = {
+    prompt_only: ['needs_training', 'regressed'],
+    needs_training: ['in_training', 'regressed'],
+    in_training: ['deployed_pending_eval', 'regressed'],
+    deployed_pending_eval: ['internalized', 'regressed'],
+    internalized: ['regressed'],
+    regressed: ['needs_training'],
+};
+/**
+ * Transition a principle's internalization status to the next valid state.
+ * Throws if the transition is not allowed.
+ *
+ * #212: This enables principles created as `prompt_only` to eventually
+ * become `needs_training` and enter the nocturnal evaluation pipeline.
+ */
+export function transitionInternalizationStatus(stateDir, principleId, nextStatus) {
+    updateTrainingStore(stateDir, (store) => {
+        const state = store[principleId];
+        if (!state) {
+            throw new Error(`Cannot transition: principle ${principleId} not found in training store`);
+        }
+        const allowed = VALID_TRANSITIONS[state.internalizationStatus] ?? [];
+        if (!allowed.includes(nextStatus)) {
+            throw new Error(`Invalid transition: ${state.internalizationStatus} → ${nextStatus}. ` +
+                `Allowed: ${allowed.join(', ') || 'none (terminal state)'}`);
+        }
+        state.internalizationStatus = nextStatus;
+    });
+}
+function ledgerTrainingStore(stateDir) {
+    return loadLedger(stateDir).trainingStore;
+}

package/dist/core/principle-tree-ledger-adapter.d.ts

@@ -0,0 +1,32 @@
+import type { LedgerAdapter, LedgerPrincipleEntry } from '@principles/core/runtime-v2';
+/**
+ * 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 declare class PrincipleTreeLedgerAdapter implements LedgerAdapter {
+    #private;
+    constructor(opts: {
+        stateDir: string;
+    });
+    /**
+     * 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;
+    /**
+     * 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;
+}