principles-disciple 1.126.0 → 1.128.0

package/dist/core/principle-tree-ledger-adapter.js

@@ -0,0 +1,125 @@
+import { CandidateIntakeError, INTAKE_ERROR_CODES } from '@principles/core/runtime-v2';
+import { addPrincipleToLedger, loadLedger } from './principle-tree-ledger.js';
+const VALID_EVALUABILITIES = ['deterministic', 'weak_heuristic', 'manual_only'];
+/**
+ * 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 {
+    #stateDir;
+    #entryMap = new Map();
+    constructor(opts) {
+        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) {
+        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) {
+        // 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',
+            sourceRef: `candidate://${candidateId}`,
+            artifactRef: '',
+            taskRef: '',
+            text: found.text,
+            triggerPattern: found.triggerPattern,
+            action: found.action,
+            evaluability: 'weak_heuristic',
+            createdAt: found.createdAt,
+        };
+    }
+    /**
+     * Extract candidateId from sourceRef by stripping the 'candidate://' prefix.
+     *
+     * @internal
+     */
+    #extractCandidateId(sourceRef) {
+        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, candidateId) {
+        if (!VALID_EVALUABILITIES.includes(entry.evaluability)) {
+            throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, `Invalid evaluability value: ${entry.evaluability}. Must be one of: ${VALID_EVALUABILITIES.join(', ')}`);
+        }
+        const result = {
+            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/dist/core/principle-tree-ledger.d.ts

@@ -0,0 +1,82 @@
+import type { Implementation, ImplementationLifecycleState, Principle, PrincipleTreeStore, PrincipleValueMetrics, Rule } from '../types/principle-tree-schema.js';
+export declare const TREE_NAMESPACE = "_tree";
+export interface LegacyPrincipleTrainingState {
+    principleId: string;
+    evaluability: 'deterministic' | 'weak_heuristic' | 'manual_only';
+    applicableOpportunityCount: number;
+    observedViolationCount: number;
+    complianceRate: number;
+    violationTrend: number;
+    generatedSampleCount: number;
+    approvedSampleCount: number;
+    includedTrainRunIds: string[];
+    deployedCheckpointIds: string[];
+    lastEvalScore?: number;
+    internalizationStatus: 'prompt_only' | 'needs_training' | 'in_training' | 'deployed_pending_eval' | 'internalized' | 'regressed';
+}
+export type LegacyPrincipleTrainingStore = Record<string, LegacyPrincipleTrainingState>;
+export interface LedgerPrinciple extends Principle {
+    suggestedRules?: string[];
+}
+export interface LedgerRule extends Rule {
+    implementationIds: string[];
+}
+export interface LedgerTreeStore extends Omit<PrincipleTreeStore, 'principles' | 'rules'> {
+    principles: Record<string, LedgerPrinciple>;
+    rules: Record<string, LedgerRule>;
+}
+export interface HybridLedgerStore {
+    trainingStore: LegacyPrincipleTrainingStore;
+    tree: LedgerTreeStore;
+}
+export interface PrincipleSubtree {
+    principle: LedgerPrinciple;
+    rules: {
+        rule: LedgerRule;
+        implementations: Implementation[];
+    }[];
+}
+export declare function getLedgerFilePath(stateDir: string): string;
+export declare function loadLedger(stateDir: string): HybridLedgerStore;
+export declare function saveLedger(stateDir: string, store: HybridLedgerStore): void;
+export declare function saveLedgerAsync(stateDir: string, store: HybridLedgerStore): Promise<void>;
+export declare function updateTrainingStore(stateDir: string, mutate: (store: LegacyPrincipleTrainingStore) => void): void;
+/**
+ * Add a new principle directly to the ledger tree.
+ * This is the companion to updatePrinciple() — use this when creating a NEW
+ * principle so the compiler can find it in tree.principles.
+ *
+ * Idempotent: if the principle already exists, overwrites (update semantics).
+ */
+export declare function addPrincipleToLedger(stateDir: string, principle: LedgerPrinciple): LedgerPrinciple;
+export declare function createRule(stateDir: string, rule: LedgerRule): LedgerRule;
+export declare function createImplementation(stateDir: string, implementation: Implementation): Implementation;
+export declare function updatePrinciple(stateDir: string, principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
+export declare function updateRule(stateDir: string, ruleId: string, updates: Partial<LedgerRule>): LedgerRule;
+export declare function deleteRule(stateDir: string, ruleId: string): LedgerRule | undefined;
+export declare function updateImplementation(stateDir: string, implementationId: string, updates: Partial<Implementation>): Implementation;
+export declare function deleteImplementation(stateDir: string, implementationId: string): Implementation | undefined;
+export declare function listImplementationsForRule(stateDir: string, ruleId: string): Implementation[];
+export declare function getPrincipleSubtree(stateDir: string, principleId: string): PrincipleSubtree | undefined;
+export declare function updatePrincipleValueMetrics(stateDir: string, principleId: string, metrics: PrincipleValueMetrics): PrincipleValueMetrics;
+/**
+ * Validate a lifecycle state transition.
+ * Returns true if the transition is valid, false otherwise.
+ */
+export declare function isValidLifecycleTransition(from: ImplementationLifecycleState, to: ImplementationLifecycleState): boolean;
+/**
+ * Get allowed transitions for a given lifecycle state.
+ */
+export declare function getAllowedTransitions(from: ImplementationLifecycleState): ImplementationLifecycleState[];
+/**
+ * Transition an implementation's lifecycle state with validation.
+ * Throws on invalid transitions */
+export declare function transitionImplementationState(stateDir: string, implementationId: string, newState: ImplementationLifecycleState): Implementation;
+/**
+ * Get implementations in a specific lifecycle state for a given rule.
+ */
+export declare function listRuleImplementationsByState(stateDir: string, ruleId: string, state: ImplementationLifecycleState): Implementation[];
+/**
+ * Find active implementation for a rule (helper for rule host lookup).
+ */
+export declare function findActiveImplementation(stateDir: string, ruleId: string): Implementation | null;