principles-disciple 1.146.0 → 1.148.0

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

@@ -1,82 +1,30 @@
-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.
+ * Principle Tree Ledger — plugin adapter (re-export) over @principles/core.
  *
- * 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).
+ * PRI-459: This file WAS a full duplicate implementation of
+ * principle_training_state.json parsing / serialization / mutation (~600
+ * lines of inlined parsers, serializers, mutators, and a parallel codec).
+ * That dual ownership caused two real failure classes:
+ *
+ *   1. Lost updates — core wrote the file UNLOCKED, the plugin wrote it WITH
+ *      a lock, and neither knew the other's lock. Concurrent writers (e.g.
+ *      evolution-worker async + a pd-cli command) could silently drop edits.
+ *   2. Silent field loss — the two codecs parsed the same bytes at different
+ *      strictness; a field one side persisted could be dropped on the next
+ *      load by the other.
+ *
+ * Both are now fixed by converging on a SINGLE source of truth in core:
+ *   - parse/serialize: @principles/core/runtime-v2/principle-tree/ledger-codec
+ *   - mutation (with cross-process file lock): @principles/core/principle-tree-ledger
+ *
+ * This file is now a thin re-export so existing relative imports
+ * (`from './principle-tree-ledger.js'`) keep resolving. Consumers get the
+ * exact same API surface, now backed by the locked core implementation.
+ *
+ * Do NOT reintroduce parsing / serialization / mutation logic here. The
+ * architecture-regression guard "PRI-459: single principle_training_state
+ * ledger implementation" enforces this.
  */
-export declare function findActiveImplementation(stateDir: string, ruleId: string): Implementation | null;
+export { type Principle, type Rule, type Implementation, type PrincipleValueMetrics, type LedgerPrinciple, type LedgerRule, type LedgerTreeStore, type LegacyPrincipleTrainingState, type LegacyPrincipleTrainingStore, type HybridLedgerStore, type ImplementationLifecycleState, type PrincipleSubtree, TREE_NAMESPACE, LockAcquisitionError, loadLedger, saveLedger, saveLedgerAsync, updateTrainingStore, addPrincipleToLedger, createRule, createImplementation, updatePrinciple, updateRule, deleteRule, updateImplementation, deleteImplementation, listImplementationsForRule, getPrincipleSubtree, updatePrincipleValueMetrics, isValidLifecycleTransition, getAllowedTransitions, transitionImplementationState, listRuleImplementationsByState, findActiveImplementation, } from '@principles/core/principle-tree-ledger';
+import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+export declare const getLedgerFilePath: typeof getLedgerFilePathPublic;

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

@@ -1,527 +1,42 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { withLock, withLockAsync } from '../utils/file-lock.js';
-import { atomicWriteFileSync } from '../utils/io.js';
-const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
-export const TREE_NAMESPACE = '_tree';
-const VALID_EVALUABILITIES = ['deterministic', 'weak_heuristic', 'manual_only'];
-const VALID_INTERNALIZATION_STATUSES = [
-    'prompt_only',
-    'needs_training',
-    'in_training',
-    'deployed_pending_eval',
-    'internalized',
-    'regressed',
-];
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function clampFloat(value, min, max, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
-    }
-    return Math.max(min, Math.min(max, value));
-}
-function clampInt(value, min, max, fallback) {
-    if (typeof value !== 'number' || !Number.isFinite(value)) {
-        return fallback;
-    }
-    return Math.max(min, Math.min(max, Math.round(value)));
-}
-function stringArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
-}
-function uniqueStrings(values) {
-    return Array.from(new Set(values));
-}
-function createEmptyTree() {
-    return {
-        principles: {},
-        rules: {},
-        implementations: {},
-        metrics: {},
-        lastUpdated: new Date(0).toISOString(),
-    };
-}
-function parseLegacyTrainingStore(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const result = {};
-    for (const [principleId, candidate] of Object.entries(raw)) {
-        if (principleId === TREE_NAMESPACE || !isRecord(candidate)) {
-            continue;
-        }
-        if (candidate.principleId !== principleId) {
-            continue;
-        }
-        const evaluability = VALID_EVALUABILITIES.includes(candidate.evaluability)
-            ? candidate.evaluability
-            : 'manual_only';
-        const internalizationStatus = VALID_INTERNALIZATION_STATUSES.includes(candidate.internalizationStatus)
-            ? candidate.internalizationStatus
-            : 'prompt_only';
-        const rawLastEvalScore = candidate.lastEvalScore;
-        result[principleId] = {
-            principleId,
-            evaluability,
-            applicableOpportunityCount: clampInt(candidate.applicableOpportunityCount, 0, Number.POSITIVE_INFINITY, 0),
-            observedViolationCount: clampInt(candidate.observedViolationCount, 0, Number.POSITIVE_INFINITY, 0),
-            complianceRate: clampFloat(candidate.complianceRate, 0, 1, 0),
-            violationTrend: clampFloat(candidate.violationTrend, -1, 1, 0),
-            generatedSampleCount: clampInt(candidate.generatedSampleCount, 0, Number.POSITIVE_INFINITY, 0),
-            approvedSampleCount: clampInt(candidate.approvedSampleCount, 0, Number.POSITIVE_INFINITY, 0),
-            includedTrainRunIds: stringArray(candidate.includedTrainRunIds),
-            deployedCheckpointIds: stringArray(candidate.deployedCheckpointIds),
-            lastEvalScore: typeof rawLastEvalScore === 'number' && Number.isFinite(rawLastEvalScore)
-                ? clampFloat(rawLastEvalScore, 0, 1, 0)
-                : undefined,
-            internalizationStatus,
-        };
-    }
-    return result;
-}
-function parsePrinciples(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const principles = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        const suggestedRules = stringArray(value.suggestedRules);
-        principles[id] = {
-            ...value,
-            id,
-            ruleIds: stringArray(value.ruleIds),
-            conflictsWithPrincipleIds: stringArray(value.conflictsWithPrincipleIds),
-            derivedFromPainIds: stringArray(value.derivedFromPainIds),
-            ...(Object.prototype.hasOwnProperty.call(value, 'suggestedRules') ? { suggestedRules } : {}),
-        };
-    }
-    return principles;
-}
-function parseRules(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const rules = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        rules[id] = {
-            ...value,
-            id,
-            principleId: typeof value.principleId === 'string' ? value.principleId : '',
-            implementationIds: stringArray(value.implementationIds),
-        };
-    }
-    return rules;
-}
-function parseImplementations(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const implementations = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value) || typeof value.ruleId !== 'string') {
-            continue;
-        }
-        implementations[id] = {
-            ...value,
-            id,
-            ruleId: value.ruleId,
-        };
-    }
-    return implementations;
-}
-function parseMetrics(raw) {
-    if (!isRecord(raw)) {
-        return {};
-    }
-    const metrics = {};
-    for (const [id, value] of Object.entries(raw)) {
-        if (!isRecord(value)) {
-            continue;
-        }
-        metrics[id] = {
-            ...value,
-            principleId: typeof value.principleId === 'string' ? value.principleId : id,
-        };
-    }
-    return metrics;
-}
-function parseTree(raw) {
-    if (!isRecord(raw)) {
-        return createEmptyTree();
-    }
-    return {
-        principles: parsePrinciples(raw.principles),
-        rules: parseRules(raw.rules),
-        implementations: parseImplementations(raw.implementations),
-        metrics: parseMetrics(raw.metrics),
-        lastUpdated: typeof raw.lastUpdated === 'string' ? raw.lastUpdated : new Date(0).toISOString(),
-    };
-}
-function serializeLedger(store) {
-    return JSON.stringify({
-        ...store.trainingStore,
-        [TREE_NAMESPACE]: {
-            ...store.tree,
-            lastUpdated: new Date().toISOString(),
-        },
-    }, null, 2);
-}
-function ensureParentDir(filePath) {
-    const dir = path.dirname(filePath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-}
-function readLedgerFromFile(filePath) {
-    if (!fs.existsSync(filePath)) {
-        return {
-            trainingStore: {},
-            tree: createEmptyTree(),
-        };
-    }
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        if (!content || content.trim() === '') {
-            return { trainingStore: {}, tree: createEmptyTree() };
-        }
-        const parsed = JSON.parse(content);
-        const raw = isRecord(parsed) ? parsed : {};
-        // #219: Handle both formats:
-        // - New format: { trainingStore: {...}, tree: {...} }
-        // - Legacy format: { P_xxx: {...}, _tree: {...} }
-        const trainingStoreRaw = raw.trainingStore ?? raw;
-        const treeRaw = raw[TREE_NAMESPACE] ?? raw.tree;
-        return {
-            trainingStore: parseLegacyTrainingStore(trainingStoreRaw),
-            tree: parseTree(treeRaw),
-        };
-    }
-    catch (err) {
-        console.error(`[principle-tree-ledger] Failed to load ledger from ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-        return { trainingStore: {}, tree: createEmptyTree() };
-    }
-}
-function writeLedgerUnlocked(filePath, store) {
-    ensureParentDir(filePath);
-    atomicWriteFileSync(filePath, serializeLedger(store));
-}
-function mutateLedger(stateDir, mutate) {
-    const filePath = getLedgerFilePath(stateDir);
-    return withLock(filePath, () => {
-        const store = readLedgerFromFile(filePath);
-        const result = mutate(store);
-        writeLedgerUnlocked(filePath, store);
-        return result;
-    });
-}
-async function mutateLedgerAsync(stateDir, mutate) {
-    const filePath = getLedgerFilePath(stateDir);
-    return withLockAsync(filePath, async () => {
-        const store = readLedgerFromFile(filePath);
-        const result = await mutate(store);
-        writeLedgerUnlocked(filePath, store);
-        return result;
-    });
-}
-export function getLedgerFilePath(stateDir) {
-    return path.join(stateDir, PRINCIPLE_TRAINING_FILE);
-}
-export function loadLedger(stateDir) {
-    return readLedgerFromFile(getLedgerFilePath(stateDir));
-}
-export function saveLedger(stateDir, store) {
-    mutateLedger(stateDir, (current) => {
-        current.trainingStore = store.trainingStore;
-        current.tree = store.tree;
-    });
-}
-export async function saveLedgerAsync(stateDir, store) {
-    await mutateLedgerAsync(stateDir, async (current) => {
-        current.trainingStore = store.trainingStore;
-        current.tree = store.tree;
-    });
-}
-export function updateTrainingStore(stateDir, mutate) {
-    mutateLedger(stateDir, (store) => {
-        mutate(store.trainingStore);
-    });
-}
 /**
- * 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.
+ * Principle Tree Ledger — plugin adapter (re-export) over @principles/core.
  *
- * Idempotent: if the principle already exists, overwrites (update semantics).
- */
-export function addPrincipleToLedger(stateDir, principle) {
-    return mutateLedger(stateDir, (store) => {
-        store.tree.principles[principle.id] = principle;
-        store.tree.lastUpdated = new Date().toISOString();
-        return principle;
-    });
-}
-export function createRule(stateDir, rule) {
-    return mutateLedger(stateDir, (store) => {
-        const principle = store.tree.principles[rule.principleId];
-        if (!principle) {
-            throw new Error(`Cannot create rule "${rule.id}" for missing principle "${rule.principleId}".`);
-        }
-        const nextRule = {
-            ...rule,
-            implementationIds: uniqueStrings(rule.implementationIds),
-        };
-        store.tree.rules[nextRule.id] = nextRule;
-        principle.ruleIds = uniqueStrings([...principle.ruleIds, nextRule.id]);
-        return nextRule;
-    });
-}
-export function createImplementation(stateDir, implementation) {
-    return mutateLedger(stateDir, (store) => {
-        const rule = store.tree.rules[implementation.ruleId];
-        if (!rule) {
-            throw new Error(`Cannot create implementation "${implementation.id}" for missing rule "${implementation.ruleId}".`);
-        }
-        store.tree.implementations[implementation.id] = implementation;
-        rule.implementationIds = uniqueStrings([...rule.implementationIds, implementation.id]);
-        return implementation;
-    });
-}
-export function updatePrinciple(stateDir, principleId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingPrinciple = store.tree.principles[principleId];
-        if (!existingPrinciple) {
-            throw new Error(`Cannot update missing principle "${principleId}".`);
-        }
-        const nextPrinciple = {
-            ...existingPrinciple,
-            ...updates,
-            id: principleId,
-            ruleIds: updates.ruleIds ? uniqueStrings(updates.ruleIds) : existingPrinciple.ruleIds,
-            conflictsWithPrincipleIds: updates.conflictsWithPrincipleIds
-                ? uniqueStrings(updates.conflictsWithPrincipleIds)
-                : existingPrinciple.conflictsWithPrincipleIds,
-            derivedFromPainIds: updates.derivedFromPainIds
-                ? uniqueStrings(updates.derivedFromPainIds)
-                : existingPrinciple.derivedFromPainIds,
-            ...(Object.prototype.hasOwnProperty.call(updates, 'suggestedRules')
-                ? { suggestedRules: uniqueStrings(updates.suggestedRules ?? []) }
-                : Object.prototype.hasOwnProperty.call(existingPrinciple, 'suggestedRules')
-                    ? { suggestedRules: existingPrinciple.suggestedRules }
-                    : {}),
-        };
-        store.tree.principles[principleId] = nextPrinciple;
-        return nextPrinciple;
-    });
-}
-export function updateRule(stateDir, ruleId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingRule = store.tree.rules[ruleId];
-        if (!existingRule) {
-            throw new Error(`Cannot update missing rule "${ruleId}".`);
-        }
-        const nextPrincipleId = updates.principleId ?? existingRule.principleId;
-        const nextPrinciple = store.tree.principles[nextPrincipleId];
-        if (!nextPrinciple) {
-            throw new Error(`Cannot move rule "${ruleId}" to missing principle "${nextPrincipleId}".`);
-        }
-        const nextRule = {
-            ...existingRule,
-            ...updates,
-            id: ruleId,
-            principleId: nextPrincipleId,
-            implementationIds: updates.implementationIds
-                ? uniqueStrings(updates.implementationIds)
-                : existingRule.implementationIds,
-        };
-        if (existingRule.principleId !== nextPrincipleId) {
-            const previousPrinciple = store.tree.principles[existingRule.principleId];
-            if (previousPrinciple) {
-                previousPrinciple.ruleIds = previousPrinciple.ruleIds.filter((candidateId) => candidateId !== ruleId);
-            }
-            nextPrinciple.ruleIds = uniqueStrings([...nextPrinciple.ruleIds, ruleId]);
-        }
-        store.tree.rules[ruleId] = nextRule;
-        return nextRule;
-    });
-}
-export function deleteRule(stateDir, ruleId) {
-    return mutateLedger(stateDir, (store) => {
-        const existingRule = store.tree.rules[ruleId];
-        if (!existingRule) {
-            return undefined;
-        }
-        const parentPrinciple = store.tree.principles[existingRule.principleId];
-        if (parentPrinciple) {
-            parentPrinciple.ruleIds = parentPrinciple.ruleIds.filter((candidateId) => candidateId !== ruleId);
-        }
-        const implementationIds = uniqueStrings([
-            ...existingRule.implementationIds,
-            ...Object.values(store.tree.implementations)
-                .filter((implementation) => implementation.ruleId === ruleId)
-                .map((implementation) => implementation.id),
-        ]);
-        for (const implementationId of implementationIds) {
-            delete store.tree.implementations[implementationId];
-        }
-        delete store.tree.rules[ruleId];
-        return existingRule;
-    });
-}
-export function updateImplementation(stateDir, implementationId, updates) {
-    return mutateLedger(stateDir, (store) => {
-        const existingImplementation = store.tree.implementations[implementationId];
-        if (!existingImplementation) {
-            throw new Error(`Cannot update missing implementation "${implementationId}".`);
-        }
-        const nextRuleId = updates.ruleId ?? existingImplementation.ruleId;
-        const nextRule = store.tree.rules[nextRuleId];
-        if (!nextRule) {
-            throw new Error(`Cannot move implementation "${implementationId}" to missing rule "${nextRuleId}".`);
-        }
-        const nextImplementation = {
-            ...existingImplementation,
-            ...updates,
-            id: implementationId,
-            ruleId: nextRuleId,
-        };
-        if (existingImplementation.ruleId !== nextRuleId) {
-            const previousRule = store.tree.rules[existingImplementation.ruleId];
-            if (previousRule) {
-                previousRule.implementationIds = previousRule.implementationIds.filter((candidateId) => candidateId !== implementationId);
-            }
-            nextRule.implementationIds = uniqueStrings([...nextRule.implementationIds, implementationId]);
-        }
-        store.tree.implementations[implementationId] = nextImplementation;
-        return nextImplementation;
-    });
-}
-export function deleteImplementation(stateDir, implementationId) {
-    return mutateLedger(stateDir, (store) => {
-        const existingImplementation = store.tree.implementations[implementationId];
-        if (!existingImplementation) {
-            return undefined;
-        }
-        const parentRule = store.tree.rules[existingImplementation.ruleId];
-        if (parentRule) {
-            parentRule.implementationIds = parentRule.implementationIds.filter((candidateId) => candidateId !== implementationId);
-        }
-        delete store.tree.implementations[implementationId];
-        return existingImplementation;
-    });
-}
-export function listImplementationsForRule(stateDir, ruleId) {
-    const ledger = loadLedger(stateDir);
-    const rule = ledger.tree.rules[ruleId];
-    if (!rule) {
-        return [];
-    }
-    return rule.implementationIds
-        .map((implementationId) => ledger.tree.implementations[implementationId])
-        .filter((implementation) => implementation !== undefined);
-}
-export function getPrincipleSubtree(stateDir, principleId) {
-    const ledger = loadLedger(stateDir);
-    const principle = ledger.tree.principles[principleId];
-    if (!principle) {
-        return undefined;
-    }
-    return {
-        principle,
-        rules: principle.ruleIds
-            .map((ruleId) => ledger.tree.rules[ruleId])
-            .filter((rule) => rule !== undefined)
-            .map((rule) => ({
-            rule,
-            implementations: rule.implementationIds
-                .map((implementationId) => ledger.tree.implementations[implementationId])
-                .filter((implementation) => implementation !== undefined),
-        })),
-    };
-}
-export function updatePrincipleValueMetrics(stateDir, principleId, metrics) {
-    return mutateLedger(stateDir, (store) => {
-        const nextMetrics = {
-            ...metrics,
-            principleId,
-        };
-        store.tree.metrics[principleId] = nextMetrics;
-        return nextMetrics;
-    });
-}
-// ---------------------------------------------------------------------------
-// Implementation Lifecycle State Transitions
-// ---------------------------------------------------------------------------
-/**
- * Valid lifecycle state transitions (per Phase 13 context D-15):
- *   candidate -> active      (promote)
- *   active -> disabled       (disable)
- *   disabled -> active       (re-enable via promote)
- *   disabled -> archived     (permanent disable)
- *   active -> archived       (direct archive)
- *   candidate -> archived    (rejected candidate cleanup)
- */
-const VALID_LIFECYCLE_TRANSITIONS = {
-    candidate: ['active', 'archived'],
-    active: ['disabled', 'archived'],
-    disabled: ['active', 'archived'],
-    archived: [],
-};
-/**
- * Validate a lifecycle state transition.
- * Returns true if the transition is valid, false otherwise.
- */
-export function isValidLifecycleTransition(from, to) {
-    return VALID_LIFECYCLE_TRANSITIONS[from]?.includes(to) ?? false;
-}
-/**
- * Get allowed transitions for a given lifecycle state.
- */
-export function getAllowedTransitions(from) {
-    return VALID_LIFECYCLE_TRANSITIONS[from] ?? [];
-}
-/**
- * Transition an implementation's lifecycle state with validation.
- * Throws on invalid transitions */
-export function transitionImplementationState(stateDir, implementationId, newState) {
-    return mutateLedger(stateDir, (store) => {
-        const impl = store.tree.implementations[implementationId];
-        if (!impl) {
-            throw new Error(`Implementation not found: ${implementationId}`);
-        }
-        const currentState = impl.lifecycleState ?? 'candidate';
-        if (!isValidLifecycleTransition(currentState, newState)) {
-            const allowed = getAllowedTransitions(currentState);
-            throw new Error(`Invalid lifecycle transition: ${currentState} -> ${newState}. ` +
-                `Allowed: ${allowed.length > 0 ? allowed.join(', ') : 'none (terminal state)'}`);
-        }
-        const updated = {
-            ...impl,
-            lifecycleState: newState,
-            updatedAt: new Date().toISOString(),
-        };
-        store.tree.implementations[implementationId] = updated;
-        return updated;
-    });
-}
-/**
- * Get implementations in a specific lifecycle state for a given rule.
- */
-export function listRuleImplementationsByState(stateDir, ruleId, state) {
-    const implementations = listImplementationsForRule(stateDir, ruleId);
-    return implementations.filter((impl) => impl.lifecycleState === state);
-}
-/**
- * Find active implementation for a rule (helper for rule host lookup).
+ * PRI-459: This file WAS a full duplicate implementation of
+ * principle_training_state.json parsing / serialization / mutation (~600
+ * lines of inlined parsers, serializers, mutators, and a parallel codec).
+ * That dual ownership caused two real failure classes:
+ *
+ *   1. Lost updates — core wrote the file UNLOCKED, the plugin wrote it WITH
+ *      a lock, and neither knew the other's lock. Concurrent writers (e.g.
+ *      evolution-worker async + a pd-cli command) could silently drop edits.
+ *   2. Silent field loss — the two codecs parsed the same bytes at different
+ *      strictness; a field one side persisted could be dropped on the next
+ *      load by the other.
+ *
+ * Both are now fixed by converging on a SINGLE source of truth in core:
+ *   - parse/serialize: @principles/core/runtime-v2/principle-tree/ledger-codec
+ *   - mutation (with cross-process file lock): @principles/core/principle-tree-ledger
+ *
+ * This file is now a thin re-export so existing relative imports
+ * (`from './principle-tree-ledger.js'`) keep resolving. Consumers get the
+ * exact same API surface, now backed by the locked core implementation.
+ *
+ * Do NOT reintroduce parsing / serialization / mutation logic here. The
+ * architecture-regression guard "PRI-459: single principle_training_state
+ * ledger implementation" enforces this.
  */
-export function findActiveImplementation(stateDir, ruleId) {
-    const implementations = listImplementationsForRule(stateDir, ruleId);
-    return implementations.find((impl) => impl.lifecycleState === 'active') ?? null;
-}
+export { 
+// Constants
+TREE_NAMESPACE, 
+// Lock
+LockAcquisitionError, 
+// I/O + mutators
+loadLedger, saveLedger, saveLedgerAsync, updateTrainingStore, addPrincipleToLedger, createRule, createImplementation, updatePrinciple, updateRule, deleteRule, updateImplementation, deleteImplementation, listImplementationsForRule, getPrincipleSubtree, updatePrincipleValueMetrics, 
+// Lifecycle
+isValidLifecycleTransition, getAllowedTransitions, transitionImplementationState, listRuleImplementationsByState, findActiveImplementation, } from '@principles/core/principle-tree-ledger';
+// Back-compat alias: the historical plugin module exported `getLedgerFilePath`
+// (core names it `getLedgerFilePathPublic` for the same path). Keep the old
+// name resolvable for any consumer still on it; both compute
+// path.join(stateDir, 'principle_training_state.json').
+import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+export const getLedgerFilePath = getLedgerFilePathPublic;

package/dist/core/reflection/reflection-context.d.ts

@@ -1,7 +1,7 @@
+import { type LedgerPrinciple } from '../principle-tree-ledger.js';
 import type { TrajectoryDatabase } from '../trajectory.js';
-import type { Principle } from '../../types/principle-tree-schema.js';
 export interface ReflectionContext {
-    principle: Principle;
+    principle: LedgerPrinciple;
     painEvents: Array<{
         source: string;
         score: number;

package/dist/core/workspace-context.d.ts

@@ -6,12 +6,11 @@ import { HygieneTracker } from './hygiene/tracker.js';
 import { EvolutionReducerImpl } from './evolution-reducer.js';
 import type { TrajectoryDatabase } from './trajectory.js';
 import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
-import { type PrincipleSubtree } from './principle-tree-ledger.js';
-import type { Principle, PrincipleValueMetrics } from '../types/principle-tree-schema.js';
+import { type PrincipleSubtree, type LedgerPrinciple, type PrincipleValueMetrics } from './principle-tree-ledger.js';
 import type { Principle as ActivePrinciple } from './evolution-types.js';
 interface PrincipleTreeLedgerAccessor {
     getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
-    updatePrinciple(_principleId: string, updates: Partial<Principle>): Principle;
+    updatePrinciple(_principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
     updatePrincipleValueMetrics(principleId: string, _metrics: PrincipleValueMetrics): PrincipleValueMetrics;
 }
 /**

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.146.0",
+  "version": "1.148.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.146.0",
+  "version": "1.148.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",