principles-disciple 1.126.0 → 1.128.0

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

@@ -0,0 +1,527 @@
+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.
+ *
+ * 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).
+ */
+export function findActiveImplementation(stateDir, ruleId) {
+    const implementations = listImplementationsForRule(stateDir, ruleId);
+    return implementations.find((impl) => impl.lifecycleState === 'active') ?? null;
+}

package/dist/core/profile.d.ts

@@ -0,0 +1,62 @@
+export declare const PROFILE_AUDIT_LEVELS: Set<string>;
+export declare const PROFILE_EVOLUTION_MODES: Set<string>;
+export declare const PROFILE_TEST_LEVELS: Set<string>;
+export declare const PROFILE_DEFAULTS: {
+    audit_level: string;
+    risk_paths: string[];
+    evolution_mode: string;
+    gate: {
+        require_plan_for_risk_paths: boolean;
+        require_audit_before_write: boolean;
+        require_reviewer_after_write: boolean;
+    };
+    tests: {
+        on_change: string;
+        on_risk_change: string;
+        commands: Record<string, string>;
+    };
+    pain: {
+        soft_capture_threshold: number;
+        adaptive: {
+            enabled: boolean;
+            spiral_boost: number;
+            min_threshold: number;
+            max_threshold: number;
+            backlog_trigger: number;
+            hard_failure_trigger: number;
+            low_recent_success_boost: number;
+            high_recent_pain_boost: number;
+        };
+    };
+    lifecycle: {
+        enabled: boolean;
+        heartbeat_stale_hours: number;
+    };
+    progressive_gate: {
+        enabled: boolean;
+        plan_approvals: {
+            enabled: boolean;
+            max_lines_override: number;
+            allowed_patterns: string[];
+            allowed_operations: string[];
+        };
+    };
+    edit_verification: {
+        enabled: boolean;
+        max_file_size_bytes: number;
+        fuzzy_match_enabled: boolean;
+        fuzzy_match_threshold: number;
+        skip_large_file_action: "warn" | "block";
+    };
+    thinking_checkpoint: {
+        enabled: boolean;
+        window_ms: number;
+        high_risk_tools: string[];
+    };
+    custom_guards: {
+        pattern: string;
+        message: string;
+        severity: string;
+    }[];
+};
+export declare function normalizeProfile(rawProfile: any): any;