principles-disciple 1.126.0 → 1.128.0

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

@@ -1,170 +0,0 @@
-import {
-  loadLedger,
-  updatePrinciple,
-  updatePrincipleValueMetrics,
-  updateRule,
-} 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 '@principles/core/runtime-v2';
-import {
-  assessDeprecatedReadiness,
-  type DeprecatedReadinessAssessment,
-} from '@principles/core/runtime-v2';
-import {
-  recommendLifecycleRoute,
-  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;
-}
-
-     
-function createValueMetrics(
-  principle: PrincipleLifecycleEvidence,
-  adherence: PrincipleAdherenceResult,
-  current: PrincipleValueMetrics | undefined,
-): PrincipleValueMetrics {
-  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 {
-  private readonly workspaceDir: string;
-  private readonly stateDir: string;
-  constructor(
-    workspaceDir: string,
-    stateDir: string,
-  ) {
-    this.workspaceDir = workspaceDir;
-    this.stateDir = stateDir;
-  }
-
-  buildReadModel(): LifecycleReadModel {
-    const datasource = new FilesystemLifecycleDatasource(this.workspaceDir, this.stateDir);
-    return buildLifecycleReadModel(datasource);
-  }
-
-  listAssessments(readModel = this.buildReadModel()): PrincipleLifecycleAssessment[] {
-    return readModel.principles.map((principleEvidence) => {
-      const ruleMetrics = Object.fromEntries(
-        principleEvidence.rules.map((ruleEvidence) => [
-          ruleEvidence.rule.id,
-          computeRuleMetrics(ruleEvidence),
-        ]),
-      ) as Record<string, RuleMetricResult>;
-      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()): LifecycleRouteRecommendation[] {
-    return this.listAssessments(readModel).map((assessment) => assessment.routeRecommendation);
-  }
-
-  recomputeAll(): RecomputedPrincipleLifecycle[] {
-    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/src/core/principle-training-state.ts

@@ -1,177 +0,0 @@
-/**
- * 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,
-  type LegacyPrincipleTrainingStore,
-} from './principle-tree-ledger.js';
-import type { PrincipleEvaluatorLevel } from './evolution-types.js';
-
-/** File name for principle training state persistence */
-export 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 function createDefaultPrincipleState(principleId: string): PrincipleTrainingState {
-  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: string): PrincipleTrainingStore {
-   
-   
-  return ledgerTrainingStore(stateDir);
-}
-
-export function saveStore(stateDir: string, store: PrincipleTrainingStore): void {
-  const ledger = loadLedger(stateDir);
-  saveLedger(stateDir, {
-    ...ledger,
-    trainingStore: store as LegacyPrincipleTrainingStore,
-  });
-}
-
-export async function loadStoreAsync(stateDir: string): Promise<PrincipleTrainingStore> {
-   
-   
-  return ledgerTrainingStore(stateDir);
-}
-
-export async function saveStoreAsync(stateDir: string, store: PrincipleTrainingStore): Promise<void> {
-  const ledger = loadLedger(stateDir);
-  await saveLedgerAsync(stateDir, {
-    ...ledger,
-    trainingStore: store as LegacyPrincipleTrainingStore,
-  });
-}
-
-export function getPrincipleState(stateDir: string, principleId: string): PrincipleTrainingState {
-  const store = loadStore(stateDir);
-  return store[principleId] ?? createDefaultPrincipleState(principleId);
-}
-
-export function setPrincipleState(stateDir: string, state: PrincipleTrainingState): void {
-  updateTrainingStore(stateDir, (store) => {
-    store[state.principleId] = state;
-  });
-}
-
-export function removePrincipleState(stateDir: string, principleId: string): void {
-  updateTrainingStore(stateDir, (store) => {
-    delete store[principleId];
-  });
-}
-
-export function listPrincipleIds(stateDir: string): string[] {
-  return Object.keys(loadStore(stateDir));
-}
-
-export function listPrinciplesByStatus(
-  stateDir: string,
-  status: InternalizationStatus,
-): PrincipleTrainingState[] {
-  return Object.values(loadStore(stateDir)).filter((state) => state.internalizationStatus === status);
-}
-
-export function listEvaluablePrinciples(stateDir: string): PrincipleTrainingState[] {
-  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: Record<InternalizationStatus, InternalizationStatus[]> = {
-  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: string,
-  principleId: string,
-  nextStatus: InternalizationStatus,
-): void {
-  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: string): PrincipleTrainingStore {
-  return loadLedger(stateDir).trainingStore as PrincipleTrainingStore;
-}

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

@@ -1,145 +0,0 @@
-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;
-  }
-}