principles-disciple 1.7.6 → 1.7.8

package/dist/core/paths.d.ts

@@ -12,6 +12,9 @@ export declare const PD_DIRS: {
     SESSIONS: string;
     PAIN_SAMPLES: string;
     LOCKS: string;
+    NOCTURNAL_SAMPLES: string;
+    NOCTURNAL_MEMORY: string;
+    NOCTURNAL_EXPORTS: string;
 };
 /**
  * Standard File Path Mappings
@@ -39,6 +42,9 @@ export declare const PD_FILES: {
     SESSION_DIR: string;
     DICTIONARY: string;
     PRINCIPLE_BLACKLIST: string;
+    NOCTURNAL_SAMPLES_DIR: string;
+    NOCTURNAL_MEMORY_DIR: string;
+    NOCTURNAL_EXPORTS_DIR: string;
     PLAN: string;
     MEMORY_MD: string;
     HEARTBEAT: string;

package/dist/core/paths.js

@@ -26,6 +26,9 @@ export const PD_DIRS = {
     SESSIONS: posixJoin('.state', 'sessions'),
     PAIN_SAMPLES: posixJoin('memory', 'pain'),
     LOCKS: posixJoin('memory', '.locks'),
+    NOCTURNAL_SAMPLES: posixJoin('.state', 'nocturnal', 'samples'),
+    NOCTURNAL_MEMORY: posixJoin('.state', 'nocturnal', 'memory'),
+    NOCTURNAL_EXPORTS: posixJoin('.state', 'exports', 'orpo'),
 };
 /**
  * Standard File Path Mappings
@@ -53,6 +56,9 @@ export const PD_FILES = {
     SESSION_DIR: PD_DIRS.SESSIONS,
     DICTIONARY: posixJoin(PD_DIRS.STATE, 'pain_dictionary.json'),
     PRINCIPLE_BLACKLIST: posixJoin(PD_DIRS.STATE, 'principle_blacklist.json'),
+    NOCTURNAL_SAMPLES_DIR: PD_DIRS.NOCTURNAL_SAMPLES,
+    NOCTURNAL_MEMORY_DIR: PD_DIRS.NOCTURNAL_MEMORY,
+    NOCTURNAL_EXPORTS_DIR: PD_DIRS.NOCTURNAL_EXPORTS,
     PLAN: 'PLAN.md',
     MEMORY_MD: 'MEMORY.md',
     HEARTBEAT: 'HEARTBEAT.md',

package/dist/core/principle-training-state.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Principle Training State Store
+ * ================================================================
+ *
+ * Independent persistence layer for principle internalization tracking.
+ * Clearly separates the four truth states defined in the architecture:
+ *   1. sample_generated       — reflection pair produced and passed arbiter
+ *   2. sample_included_in_train_run — training run consumed the sample
+ *   3. checkpoint_deployed    — adapter/checkpoint is routable in OpenClaw
+ *   4. behavior_internalized — deployed worker improves on holdout eval
+ *
+ * DESIGN CONSTRAINTS (Phase 1):
+ * - No runtime target selection (Task 1.2 scope)
+ * - No training logic (Phase 2+ scope)
+ * - No evolution-reducer modifications
+ *
+ * FILE: {stateDir}/principle_training_state.json
+ */
+import type { PrincipleEvaluatorLevel } from './evolution-types.js';
+/** File name for principle training state persistence */
+export declare const PRINCIPLE_TRAINING_FILE = "principle_training_state.json";
+/**
+ * Internalization status — tracks progress through the four truth states:
+ *   sample_generated → sample_included_in_train_run → checkpoint_deployed → behavior_internalized
+ */
+export type InternalizationStatus = 'prompt_only' | 'needs_training' | 'in_training' | 'deployed_pending_eval' | 'internalized' | 'regressed';
+/**
+ * Per-principle training state record.
+ * Tracks the full lineage from sample generation through deployment.
+ */
+export interface PrincipleTrainingState {
+    /** Principle identifier (e.g., "T-01", "P_write_before_delete") */
+    principleId: string;
+    /** Evaluability classification — controls whether automatic targeting is allowed */
+    evaluability: PrincipleEvaluatorLevel;
+    /** Number of applicable decision-point opportunities observed */
+    applicableOpportunityCount: number;
+    /** Number of violations of this principle observed */
+    observedViolationCount: number;
+    /** Observed compliance rate (0.0 – 1.0) */
+    complianceRate: number;
+    /** Trend direction for violations (+1 = improving, 0 = stable, -1 = worsening) */
+    violationTrend: number;
+    /** Number of reflection samples generated for this principle */
+    generatedSampleCount: number;
+    /** Number of generated samples approved by arbiter */
+    approvedSampleCount: number;
+    /** Training run IDs that included samples from this principle */
+    includedTrainRunIds: string[];
+    /** Deployed checkpoint IDs for this principle */
+    deployedCheckpointIds: string[];
+    /** Last holdout evaluation score (0.0 – 1.0), if available */
+    lastEvalScore?: number;
+    /** Current internalization status */
+    internalizationStatus: InternalizationStatus;
+}
+/**
+ * The full principle training store — a map of principleId -> state.
+ * Stored as a single JSON object in principle_training_state.json.
+ */
+export type PrincipleTrainingStore = Record<string, PrincipleTrainingState>;
+/**
+ * Creates a default principle training state for a newly tracked principle.
+ * Safe defaults: evaluability='manual_only' (requires explicit upgrade to auto-training),
+ * internalizationStatus='prompt_only' (starts as prompt-only, not eligible for
+ * automatic training until upgraded).
+ */
+export declare function createDefaultPrincipleState(principleId: string): PrincipleTrainingState;
+/**
+ * Loads the full principle training store from disk.
+ * Returns an empty store if the file does not exist or is corrupted.
+ */
+export declare function loadStore(stateDir: string): PrincipleTrainingStore;
+/**
+ * Synchronously saves the full principle training store to disk.
+ * Uses file locking to prevent concurrent write corruption.
+ */
+export declare function saveStore(stateDir: string, store: PrincipleTrainingStore): void;
+/**
+ * Asynchronously loads the full principle training store from disk.
+ * Returns an empty store if the file does not exist or is corrupted.
+ */
+export declare function loadStoreAsync(stateDir: string): Promise<PrincipleTrainingStore>;
+/**
+ * Asynchronously saves the full principle training store to disk.
+ * Uses file locking to prevent concurrent write corruption.
+ */
+export declare function saveStoreAsync(stateDir: string, store: PrincipleTrainingStore): Promise<void>;
+/**
+ * Gets the training state for a single principle.
+ * Returns a default state if the principle is not yet tracked.
+ */
+export declare function getPrincipleState(stateDir: string, principleId: string): PrincipleTrainingState;
+/**
+ * Updates or inserts the training state for a single principle.
+ * Persists the full store after the update.
+ *
+ * Uses file locking around the entire read-modify-write sequence to prevent
+ * concurrent updates from causing lost writes.
+ */
+export declare function setPrincipleState(stateDir: string, state: PrincipleTrainingState): void;
+/**
+ * Removes a principle from the training store.
+ * Does nothing if the principle is not tracked.
+ *
+ * Uses file locking around the entire read-modify-write sequence.
+ */
+export declare function removePrincipleState(stateDir: string, principleId: string): void;
+/**
+ * Returns all principles currently tracked in the store.
+ */
+export declare function listPrincipleIds(stateDir: string): string[];
+/**
+ * Returns all principles matching a given internalization status.
+ */
+export declare function listPrinciplesByStatus(stateDir: string, status: InternalizationStatus): PrincipleTrainingState[];
+/**
+ * Returns all principles with 'deterministic' or 'weak_heuristic' evaluability
+ * that are eligible for automatic nocturnal targeting.
+ */
+export declare function listEvaluablePrinciples(stateDir: string): PrincipleTrainingState[];

package/dist/core/principle-training-state.js

@@ -0,0 +1,321 @@
+/**
+ * Principle Training State Store
+ * ================================================================
+ *
+ * Independent persistence layer for principle internalization tracking.
+ * Clearly separates the four truth states defined in the architecture:
+ *   1. sample_generated       — reflection pair produced and passed arbiter
+ *   2. sample_included_in_train_run — training run consumed the sample
+ *   3. checkpoint_deployed    — adapter/checkpoint is routable in OpenClaw
+ *   4. behavior_internalized — deployed worker improves on holdout eval
+ *
+ * DESIGN CONSTRAINTS (Phase 1):
+ * - No runtime target selection (Task 1.2 scope)
+ * - No training logic (Phase 2+ scope)
+ * - No evolution-reducer modifications
+ *
+ * FILE: {stateDir}/principle_training_state.json
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { withLock, withLockAsync } from '../utils/file-lock.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** File name for principle training state persistence */
+export const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
+// ---------------------------------------------------------------------------
+// Valid Status Values (for validation)
+// ---------------------------------------------------------------------------
+const VALID_EVALUABILITIES = ['deterministic', 'weak_heuristic', 'manual_only'];
+const VALID_INTERNALIZATION_STATUSES = [
+    'prompt_only',
+    'needs_training',
+    'in_training',
+    'deployed_pending_eval',
+    'internalized',
+    'regressed',
+];
+// ---------------------------------------------------------------------------
+// Schema Version
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates a default principle training state for a newly tracked principle.
+ * Safe defaults: evaluability='manual_only' (requires explicit upgrade to auto-training),
+ * internalizationStatus='prompt_only' (starts as prompt-only, not eligible for
+ * automatic training until upgraded).
+ */
+export function createDefaultPrincipleState(principleId) {
+    return {
+        principleId,
+        evaluability: 'manual_only', // Safe default: requires explicit upgrade
+        applicableOpportunityCount: 0,
+        observedViolationCount: 0,
+        complianceRate: 0,
+        violationTrend: 0,
+        generatedSampleCount: 0,
+        approvedSampleCount: 0,
+        includedTrainRunIds: [],
+        deployedCheckpointIds: [],
+        internalizationStatus: 'prompt_only', // Safe default: starts as prompt-only
+    };
+}
+// ---------------------------------------------------------------------------
+// File Operations
+// ---------------------------------------------------------------------------
+function getFilePath(stateDir) {
+    return path.join(stateDir, PRINCIPLE_TRAINING_FILE);
+}
+/**
+ * Applies migration-safe defaults to a raw parsed store.
+ * Handles:
+ * - Missing top-level entries (principles added since last load)
+ * - Missing fields on existing entries (schema evolution)
+ * - Invalid enum values (falls back to safe defaults)
+ * - NaN / out-of-range numeric values (clamped or defaulted)
+ */
+function applyMigrationDefaults(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return {};
+    }
+    const store = raw;
+    const result = {};
+    for (const [principleId, state] of Object.entries(store)) {
+        if (!state || typeof state !== 'object') {
+            // Corrupted entry — skip
+            continue;
+        }
+        const s = state;
+        // evaluability — validate enum
+        const rawEval = s.evaluability;
+        const evaluability = VALID_EVALUABILITIES.includes(rawEval)
+            ? rawEval
+            : 'manual_only';
+        // internalizationStatus — validate enum
+        const rawStatus = s.internalizationStatus;
+        const internalizationStatus = VALID_INTERNALIZATION_STATUSES.includes(rawStatus)
+            ? rawStatus
+            : 'prompt_only';
+        // Numeric fields — clamp to valid ranges
+        const applicableOpportunityCount = clampInt(s.applicableOpportunityCount, 0, Infinity, 0);
+        const observedViolationCount = clampInt(s.observedViolationCount, 0, Infinity, 0);
+        const complianceRate = clampFloat(s.complianceRate, 0, 1, 0);
+        const violationTrend = clampFloat(s.violationTrend, -1, 1, 0);
+        const generatedSampleCount = clampInt(s.generatedSampleCount, 0, Infinity, 0);
+        const approvedSampleCount = clampInt(s.approvedSampleCount, 0, Infinity, 0);
+        // Optional float — only set if in range [0, 1]
+        const rawLastEval = s.lastEvalScore;
+        let lastEvalScore;
+        if (rawLastEval != null && typeof rawLastEval === 'number') {
+            const clamped = Math.max(0, Math.min(1, rawLastEval));
+            if (Number.isFinite(clamped)) {
+                lastEvalScore = clamped;
+            }
+        }
+        // Arrays — ensure always arrays
+        const includedTrainRunIds = Array.isArray(s.includedTrainRunIds)
+            ? s.includedTrainRunIds.filter((id) => typeof id === 'string')
+            : [];
+        const deployedCheckpointIds = Array.isArray(s.deployedCheckpointIds)
+            ? s.deployedCheckpointIds.filter((id) => typeof id === 'string')
+            : [];
+        // Skip entries where the stored principleId doesn't match the map key.
+        // This indicates a corrupted or tampered entry.
+        const storedPrincipleId = s.principleId;
+        if (typeof storedPrincipleId !== 'string' || storedPrincipleId !== principleId) {
+            continue;
+        }
+        result[principleId] = {
+            principleId,
+            evaluability,
+            applicableOpportunityCount,
+            observedViolationCount,
+            complianceRate,
+            violationTrend,
+            generatedSampleCount,
+            approvedSampleCount,
+            includedTrainRunIds,
+            deployedCheckpointIds,
+            lastEvalScore,
+            internalizationStatus,
+        };
+    }
+    return result;
+}
+/** Clamp an unknown value to a float range, returning default if invalid */
+function clampFloat(value, min, max, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, value));
+}
+/** Clamp an unknown value to an integer range, returning default if invalid */
+function clampInt(value, min, max, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const rounded = Math.round(value);
+    return Math.max(min, Math.min(max, rounded));
+}
+// ---------------------------------------------------------------------------
+// Synchronous Read/Write
+// ---------------------------------------------------------------------------
+/**
+ * Loads the full principle training store from disk.
+ * Returns an empty store if the file does not exist or is corrupted.
+ */
+export function loadStore(stateDir) {
+    const filePath = getFilePath(stateDir);
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return applyMigrationDefaults(parsed);
+    }
+    catch (err) {
+        // Corrupted file — fail-safe, return empty store
+        console.warn(`[principle-training-state] Failed to load store from "${filePath}": ${err instanceof Error ? err.message : String(err)}. Returning empty store.`);
+        return {};
+    }
+}
+/**
+ * Synchronously saves the full principle training store to disk.
+ * Uses file locking to prevent concurrent write corruption.
+ */
+export function saveStore(stateDir, store) {
+    const filePath = getFilePath(stateDir);
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    withLock(filePath, () => {
+        fs.writeFileSync(filePath, JSON.stringify(store, null, 2), 'utf-8');
+    });
+}
+// ---------------------------------------------------------------------------
+// Async Read/Write (for use in async contexts)
+// ---------------------------------------------------------------------------
+/**
+ * Asynchronously loads the full principle training store from disk.
+ * Returns an empty store if the file does not exist or is corrupted.
+ */
+export async function loadStoreAsync(stateDir) {
+    const filePath = getFilePath(stateDir);
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = await fs.promises.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return applyMigrationDefaults(parsed);
+    }
+    catch (err) {
+        console.warn(`[principle-training-state] Failed to load store asynchronously from "${filePath}": ${err instanceof Error ? err.message : String(err)}. Returning empty store.`);
+        return {};
+    }
+}
+/**
+ * Asynchronously saves the full principle training store to disk.
+ * Uses file locking to prevent concurrent write corruption.
+ */
+export async function saveStoreAsync(stateDir, store) {
+    const filePath = getFilePath(stateDir);
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        await fs.promises.mkdir(dir, { recursive: true });
+    }
+    await withLockAsync(filePath, async () => {
+        await fs.promises.writeFile(filePath, JSON.stringify(store, null, 2), 'utf-8');
+    });
+}
+// ---------------------------------------------------------------------------
+// Single-Principle Accessors
+// ---------------------------------------------------------------------------
+/**
+ * Gets the training state for a single principle.
+ * Returns a default state if the principle is not yet tracked.
+ */
+export function getPrincipleState(stateDir, principleId) {
+    const store = loadStore(stateDir);
+    return store[principleId] ?? createDefaultPrincipleState(principleId);
+}
+/**
+ * Updates or inserts the training state for a single principle.
+ * Persists the full store after the update.
+ *
+ * Uses file locking around the entire read-modify-write sequence to prevent
+ * concurrent updates from causing lost writes.
+ */
+export function setPrincipleState(stateDir, state) {
+    const filePath = getFilePath(stateDir);
+    withLock(filePath, () => {
+        // Read current store while holding the lock
+        const store = loadStoreUnlocked(filePath);
+        store[state.principleId] = state;
+        // Write directly — no nested lock needed (we hold the outer lock)
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(store, null, 2), 'utf-8');
+    });
+}
+/**
+ * Internal: loads store from a specific file path without acquiring a lock.
+ * Caller must hold the lock. Use only inside locked sections.
+ */
+function loadStoreUnlocked(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return {};
+    }
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        return applyMigrationDefaults(JSON.parse(raw));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Removes a principle from the training store.
+ * Does nothing if the principle is not tracked.
+ *
+ * Uses file locking around the entire read-modify-write sequence.
+ */
+export function removePrincipleState(stateDir, principleId) {
+    const filePath = getFilePath(stateDir);
+    withLock(filePath, () => {
+        const store = loadStoreUnlocked(filePath);
+        if (Object.prototype.hasOwnProperty.call(store, principleId)) {
+            delete store[principleId];
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(filePath, JSON.stringify(store, null, 2), 'utf-8');
+        }
+    });
+}
+/**
+ * Returns all principles currently tracked in the store.
+ */
+export function listPrincipleIds(stateDir) {
+    return Object.keys(loadStore(stateDir));
+}
+/**
+ * Returns all principles matching a given internalization status.
+ */
+export function listPrinciplesByStatus(stateDir, status) {
+    const store = loadStore(stateDir);
+    return Object.values(store).filter((s) => s.internalizationStatus === status);
+}
+/**
+ * Returns all principles with 'deterministic' or 'weak_heuristic' evaluability
+ * that are eligible for automatic nocturnal targeting.
+ */
+export function listEvaluablePrinciples(stateDir) {
+    const store = loadStore(stateDir);
+    return Object.values(store).filter((s) => s.evaluability !== 'manual_only' && s.internalizationStatus !== 'prompt_only');
+}