principles-disciple 1.201.0 → 1.202.0

package/dist/core/path-resolver.d.ts

@@ -0,0 +1,60 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+export interface PathResolverOptions {
+    workspaceDir?: string;
+    normalizeWorkspace?: boolean;
+    logger?: {
+        debug?: (_msg: string) => void;
+        info?: (_msg: string) => void;
+        warn?: (_msg: string) => void;
+        error?: (_msg: string) => void;
+    };
+}
+export declare const PD_ENV_VARS: {
+    readonly WORKSPACE_DIR: 'PD_WORKSPACE_DIR';
+    readonly STATE_DIR: 'PD_STATE_DIR';
+    readonly DEBUG: 'DEBUG';
+};
+export declare const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, {
+    desc: string;
+    example: string;
+}>;
+export declare function printEnvVarHelp(): void;
+export interface PDConfig {
+    workspace?: string;
+    state?: string;
+    debug?: boolean;
+}
+export declare class PathResolver {
+    private static extensionRoot;
+    private workspaceDir;
+    private stateDir;
+    private readonly logger?;
+    private readonly normalizeWorkspace;
+    private initialized;
+    static setExtensionRoot(extensionRootPath: string): void;
+    static getExtensionRoot(): string | null;
+    constructor(options?: PathResolverOptions);
+    private log;
+    private detectWorkspaceDir;
+    private normalizePath;
+    normalizeWorkspacePath(inputPath: string): string;
+    getWorkspaceDir(): string;
+    getStateDir(): string;
+    resolve(key: string): string;
+    ensureStateDir(): void;
+    static createFromHookContext(ctx: Record<string, unknown>): PathResolver;
+}
+export declare function createDefaultConfig(targetPath?: string): string;
+/**
+ * Resolve workspace directory via OpenClaw's official API.
+ *
+ * Replaces the removed `api.workspaceDir` field.
+ *
+ * Priority: api.runtime.agent.resolveAgentWorkspaceDir(agentId)
+ *           → PathResolver.getWorkspaceDir() (PD env vars, config file, default)
+ *
+ * @param api - Plugin API instance
+ * @param agentId - Agent ID (defaults to 'main' if not provided)
+ * @returns Resolved workspace directory, or `undefined` if all resolution paths fail
+ */
+export declare function resolveWorkspaceDirFromApi(api: OpenClawPluginApi | undefined, agentId?: string): string | undefined;

package/dist/core/paths.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Principles Disciple Directory Constants
+ * Establishing a logical separation between Identity, State, and Memory.
+ */
+export declare const PD_DIRS: {
+    IDENTITY: string;
+    MODELS: string;
+    STATE: string;
+    MEMORY: string;
+    OKR: string;
+    LOGS: string;
+    SESSIONS: string;
+    PAIN_SAMPLES: string;
+    LOCKS: string;
+    IMPL_CODE_DIR: string;
+};
+/**
+ * Standard File Path Mappings
+ */
+export declare const PD_FILES: {
+    PROFILE: string;
+    PRINCIPLES: string;
+    THINKING_OS: string;
+    DECISION_POLICY: string;
+    MODELS_DIR: string;
+    STATE_DIR: string;
+    EVOLUTION_QUEUE: string;
+    EVOLUTION_DIRECTIVE: string;
+    WORKBOARD: string;
+    AGENT_SCORECARD: string;
+    PAIN_FLAG: string;
+    SYSTEM_CAPABILITIES: string;
+    PAIN_SETTINGS: string;
+    PAIN_CANDIDATES: string;
+    THINKING_OS_USAGE: string;
+    TRAJECTORY_DB: string;
+    TRAJECTORY_BLOBS_DIR: string;
+    EXPORTS_DIR: string;
+    SESSION_DIR: string;
+    DICTIONARY: string;
+    PRINCIPLE_BLACKLIST: string;
+    WORKFLOWS_YAML: string;
+    IMPL_CODE_DIR: string;
+    MEMORY_MD: string;
+    HEARTBEAT: string;
+    SYSTEM_LOG: string;
+    REFLECTION_LOG: string;
+    USER_CONTEXT: string;
+    OKR_DIR: string;
+    CURRENT_FOCUS: string;
+    WEEK_STATE: string;
+    THINKING_OS_CANDIDATES: string;
+    EVOLUTION_STREAM: string;
+    EVOLUTION_LOCK: string;
+};
+/**
+ * Resolves a PD file path within a given workspace.
+ */
+export declare function resolvePdPath(workspaceDir: string, fileKey: keyof typeof PD_FILES): string;

package/dist/core/pd-config-loader.d.ts

@@ -0,0 +1,96 @@
+/**
+ * PD Config Loader (Plugin I/O boundary) — PRI-307
+ *
+ * Reads `.pd/config.yaml`, validates via core, computes effective config.
+ * Replaces the old `.pd/feature-flags.yaml` and `.state/workflows.yaml` reading
+ * for plugin production paths.
+ *
+ * ADR-0016: PD owns exactly one user config file.
+ * - Missing config → defaults with nextAction
+ * - Malformed config → fail loud with errors and nextAction
+ * - No secrets in output
+ * - Observer disabled → no start / no noisy log cycling
+ * - Observer enabled + missing setup → structured needs_setup + nextAction
+ */
+import type { EffectivePdConfig } from '@principles/core/runtime-v2';
+export declare const PD_CONFIG_DIR = ".pd";
+export declare const PD_CONFIG_FILENAME = "config.yaml";
+export type ObserverReadiness = 'disabled' | 'needs_setup' | 'ready' | 'not_ready' | 'config_malformed';
+export interface ObserverConfigResult {
+    /** Whether the observer feature is enabled in config */
+    enabled: boolean;
+    /** Observer readiness state */
+    readiness: ObserverReadiness;
+    /** Config source: 'defaults' | 'user_config' | 'malformed' */
+    source: string;
+    /** Reason for current state */
+    reason: string;
+    /** What the user should do next */
+    nextAction: string;
+    /** The runtime profile ID for this observer, if configured */
+    runtimeProfileId: string | null;
+    /** The runtime profile type, if configured */
+    runtimeProfileType: string | null;
+    /** The apiKeyEnv for the runtime profile, if applicable */
+    apiKeyEnv: string | null;
+    /** Whether the apiKeyEnv is present in process.env */
+    apiKeyPresent: boolean;
+    /** Provider name from runtime profile */
+    provider: string | null;
+    /** Model name from runtime profile */
+    model: string | null;
+    /** Timeout from runtime profile */
+    timeoutMs: number | null;
+    /** Base URL from runtime profile */
+    baseUrl: string | null;
+    /** Config validation errors (only present when readiness=config_malformed) */
+    configErrors?: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export interface PluginConfigLoadResult {
+    ok: boolean;
+    effective: EffectivePdConfig;
+    source: 'defaults' | 'user_config' | 'malformed';
+    configPath: string;
+    warnings: string[];
+    errors: Array<{
+        path: string;
+        reason: string;
+        nextAction: string;
+    }>;
+}
+export declare function getPdConfigPath(workspaceDir: string): string;
+/**
+ * Load and validate `.pd/config.yaml` from the workspace.
+ * Never throws on malformed input. Always provides a usable fallback.
+ */
+export declare function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult;
+/**
+ * Get a single feature flag's enabled state from .pd/config.yaml.
+ * Replaces the old `loadFeatureFlagFromWorkspace` which read .pd/feature-flags.yaml.
+ */
+export declare function loadFeatureFlagFromConfig(workspaceDir: string, flagId: string, logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+}): {
+    enabled: boolean;
+    source: string;
+};
+/**
+ * Resolve observer configuration from .pd/config.yaml.
+ *
+ * Returns structured state:
+ * - config_malformed: config file is invalid — no guessing, fail loud
+ * - disabled: observer feature flag is off OR agent.enabled=false → no start, no noisy logs
+ * - needs_setup: observer enabled but runtime profile missing, API key not set, or unsupported profile type
+ * - ready: observer enabled and fully configured (pi-ai with key present)
+ * - not_ready: observer enabled, API key present, but runtime availability unknown
+ */
+export declare function resolveObserverConfig(workspaceDir: string, observerFlagId: string, observerAgentName: string, _logger?: {
+    warn?: (msg: string) => void;
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+}): ObserverConfigResult;

package/dist/core/pd-task-reconciler.d.ts

@@ -0,0 +1,89 @@
+import type { PDTaskSpec } from './pd-task-types.js';
+export interface CronJobState {
+    nextRunAtMs?: number;
+    runningAtMs?: number;
+    lastRunAtMs?: number;
+    lastRunStatus?: string;
+    lastStatus?: 'ok' | 'error' | 'skipped';
+    lastError?: string;
+    lastDurationMs?: number;
+    consecutiveErrors?: number;
+}
+export interface CronJob {
+    id: string;
+    name: string;
+    agentId?: string;
+    description?: string;
+    enabled: boolean;
+    deleteAfterRun?: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: {
+        kind: 'every';
+        everyMs: number;
+    } | {
+        kind: 'at';
+        at: string;
+    } | {
+        kind: 'cron';
+        expr: string;
+        tz?: string;
+    };
+    sessionTarget: string;
+    wakeMode: string;
+    payload: {
+        kind: 'systemEvent';
+        text: string;
+    } | {
+        kind: 'agentTurn';
+        message: string;
+        model?: string;
+        thinking?: string;
+        timeoutSeconds?: number;
+        lightContext?: boolean;
+        toolsAllow?: string[];
+    };
+    delivery?: {
+        mode: string;
+        channel?: string;
+        to?: string;
+    };
+    state: CronJobState;
+    metadata?: Record<string, string>;
+}
+export interface CronStoreFile {
+    version: number;
+    jobs: CronJob[];
+}
+export type DiffActionType = 'CREATE' | 'UPDATE' | 'DISABLE' | 'ORPHAN' | 'SKIP';
+export interface DiffAction {
+    type: DiffActionType;
+    task?: PDTaskSpec;
+    job?: CronJob;
+}
+export interface ReconcileError {
+    taskId: string;
+    message: string;
+}
+export interface ReconcileResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    orphaned: string[];
+    errors: ReconcileError[];
+}
+export interface ReconcileOptions {
+    dryRun?: boolean;
+    workspaceDir: string;
+    logger?: {
+        info?: (_: string) => void;
+        warn?: (_: string) => void;
+    };
+}
+export declare function reconcilePDTasks(workspaceDir: string, options?: Partial<ReconcileOptions>): Promise<ReconcileResult>;
+export declare function trigger(taskId: string, workspaceDir: string, options?: {
+    force?: boolean;
+}): Promise<{
+    ok: boolean;
+    error?: string;
+}>;

package/dist/core/pd-task-service.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginService } from '../openclaw-sdk.js';
+export declare const PDTaskService: OpenClawPluginService;

package/dist/core/pd-task-store.d.ts

@@ -0,0 +1,5 @@
+import type { PDTaskSpec } from './pd-task-types.js';
+export declare function readTasks(workspaceDir: string): PDTaskSpec[];
+export declare function writeTasks(workspaceDir: string, tasks: PDTaskSpec[]): Promise<void>;
+export declare function initTaskMeta(task: PDTaskSpec): PDTaskSpec;
+export declare function updateSyncMeta(task: PDTaskSpec, status: 'ok' | 'error', jobId?: string, error?: string): PDTaskSpec;

package/dist/core/pd-task-types.d.ts

@@ -0,0 +1,8 @@
+import type { PDTaskSchedule as CorePDTaskSchedule, PDTaskExecution as CorePDTaskExecution, PDTaskDelivery as CorePDTaskDelivery, PDTaskMeta as CorePDTaskMeta, PDTaskSpec as CorePDTaskSpec } from '@principles/core/runtime-v2';
+export type PDTaskSchedule = CorePDTaskSchedule;
+export type PDTaskExecution = CorePDTaskExecution;
+export type PDTaskDelivery = CorePDTaskDelivery;
+export type PDTaskMeta = CorePDTaskMeta;
+export type PDTaskSpec = CorePDTaskSpec;
+export { PDTaskScheduleSchema, PDTaskExecutionSchema, PDTaskDeliverySchema, PDTaskMetaSchema, PDTaskSpecSchema, } from '@principles/core/runtime-v2';
+export declare const BUILTIN_PD_TASKS: PDTaskSpec[];

package/dist/core/principle-compiler/__tests__/compiler-replay-gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/principle-compiler/code-validator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Code Validator — Validates LLM-generated rule implementation code
+ *
+ * CHECKS:
+ * 1. Syntax: code parses without errors (VM)
+ * 2. Forbidden patterns: delegates to core checkForbiddenPatterns (PRI-44)
+ * 3. Export check: sandbox loads and exports evaluate + meta (VM)
+ * 4. Return shape: evaluate(mockInput) returns { matched: boolean } (VM)
+ *
+ * PRI-44: Forbidden pattern detection extracted to @principles/core.
+ */
+import { type ValidationResult } from '@principles/core/runtime-v2';
+export type { ValidationResult } from '@principles/core/runtime-v2';
+export declare function validateGeneratedCode(code: string): ValidationResult;

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

@@ -0,0 +1,45 @@
+/**
+ * PrincipleCompiler — Orchestrator (Task 5)
+ *
+ * Orchestrates the full compilation flow:
+ *   ReflectionContextCollector.collect() → extract patterns → generateFromTemplate()
+ *   → validateGeneratedCode() → [replay validation] → registerCompiledRule()
+ *
+ * DESIGN DECISIONS:
+ * - extractPatterns infers toolName from pain event reasons and session tool calls
+ * - Groups by toolName into PainPattern objects
+ * - If no patterns can be extracted, returns a 'no patterns' failure
+ * - PRI-115: Replay validation gate runs after code validation, before registration
+ */
+import type { TrajectoryDatabase } from '../trajectory.js';
+import type { CompileResult } from '@principles/core/runtime-v2';
+export type { CompileResult } from '@principles/core/runtime-v2';
+export declare class PrincipleCompiler {
+    private readonly stateDir;
+    private readonly collector;
+    constructor(stateDir: string, trajectory: TrajectoryDatabase);
+    /**
+     * Compile a single principle into an auto-generated rule.
+     *
+     * Flow:
+     * 1. Collect reflection context
+     * 2. Extract pain patterns
+     * 3. Generate code from template
+     * 4. Validate generated code
+     * 4.5. Replay validation against GoldenTrace (PRI-115)
+     * 5. Register in ledger
+     */
+    compileOne(principleId: string): CompileResult;
+    /**
+     * Build GoldenTrace test cases from extracted pain patterns.
+     *
+     * Generates synthetic negative/positive parameter pairs based on whether
+     * the pattern targets commands (commandRegex) or paths (pathRegex).
+     * Returns an empty array when no patterns are available.
+     */
+    private buildGoldenTraceCases;
+    /**
+     * Compile all eligible principles (those with derivedFromPainIds).
+     */
+    compileAll(): CompileResult[];
+}

package/dist/core/principle-compiler/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Principle Compiler — Barrel Export
+ *
+ * Re-exports all principle-compiler components for convenient importing.
+ * PRI-44: Types and pure logic re-exported from @principles/core.
+ */
+export { PrincipleCompiler } from './compiler.js';
+export type { CompileResult } from './compiler.js';
+export { validateGeneratedCode } from './code-validator.js';
+export type { ValidationResult } from './code-validator.js';
+export { generateFromTemplate, type PainPattern } from './template-generator.js';
+export { registerCompiledRule, type RegisterInput, type RegisterResult } from './ledger-registrar.js';

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/template-generator.d.ts

@@ -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, type PainPattern } from '@principles/core/runtime-v2';

package/dist/core/principle-injection.d.ts

@@ -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.
+ */
+export { formatPrinciple, selectPrinciplesForInjection, DEFAULT_PRINCIPLE_BUDGET, } from '@principles/core/prompt-builder';
+export type { InjectablePrinciple, PrincipleSelectionResult } 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/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/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/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-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-tree-ledger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Principle Tree Ledger — plugin adapter (re-export) over @principles/core.
+ *
+ * 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 { 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/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;