principles-disciple 1.126.0 → 1.128.0

package/dist/core/local-worker-routing.js

@@ -0,0 +1,216 @@
+/**
+ * Local Worker Routing Policy — Task Classification and Routing Decisions
+ * ======================================================================
+ *
+ * Phase: PRI-74 Routing Guidance Migration (follow-up to PRI-75 Prompt Injection SDK Migration)
+ *
+ * This file is a THIN ADAPTER.
+ * Pure classification logic lives in @principles/core/prompt-builder/routing-guidance.ts.
+ * This file handles I/O (deployment registry, promotion state) and combines
+ * pure classification with deployment checks.
+ *
+ * ARCHITECTURE:
+ *   - Pure: classifyTaskKind, buildReason, buildBlockers, keyword constants → core
+ *   - I/O: getDeployment, isRoutingEnabledForProfile, isCheckpointDeployable, getPromotionState → plugin
+ *
+ * TASK CLASSIFICATION TAXONOMY:
+ *   Pure-classification output from classifyTaskKind() in @principles/core/prompt-builder/routing-guidance.ts:
+ *     reader_eligible      — clearly suitable for local-reader
+ *     editor_eligible     — clearly suitable for local-editor
+ *     high_entropy_disallowed — high-complexity tasks that must stay on main agent
+ *     ambiguous_scope     — tasks that are unclear and need main-agent judgment
+ *   Plugin layer adds I/O-bound categories via deployment checks in classifyTask():
+ *     profile_mismatch    — target profile incompatible with task classification
+ *     deployment_unavailable — no enabled deployment exists for the target profile
+ *
+ * FAIL-CLOSED PRINCIPLE:
+ *   - When in doubt → stay_main
+ *   - Unclear intent → stay_main
+ *   - High complexity → stay_main
+ *   - No enabled deployment → stay_main
+ */
+import { isRoutingEnabledForProfile, getDeployment, } from './model-deployment-registry.js';
+import { isCheckpointDeployable } from './model-training-registry.js';
+import { getPromotionState } from './promotion-gate.js';
+// Core pure functions — migrated to @principles/core/prompt-builder
+import { classifyTaskKind as coreClassifyTaskKind, buildReason as coreBuildReason, buildBlockers as coreBuildBlockers, } from '@principles/core/prompt-builder';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify a task and produce a routing decision.
+ *
+ * This is the main entry point for routing policy evaluation.
+ * It:
+ *   1. Classifies the task kind based on keywords and heuristics (core pure function)
+ *   2. Checks deployment availability for the target profile (plugin I/O)
+ *   3. Returns a fully explainable RoutingDecision
+ *
+ * @param input - The routing input describing the task
+ * @param stateDir - Workspace state directory (for deployment registry lookup)
+ * @returns RoutingDecision with classification, reason, blockers, and routing verdict
+ */
+export function classifyTask(input, stateDir) {
+    // --- Determine the raw task classification (delegated to core pure function) ---
+    const classification = coreClassifyTaskKind(input);
+    // --- Determine the target profile ---
+    // If input specifies a target, use it. Otherwise, pick based on classification.
+    // NOTE: When explicitly specified, we must validate profile-task compatibility below.
+    const targetProfile = input.targetProfile ??
+        (classification === 'reader_eligible'
+            ? 'local-reader'
+            : classification === 'editor_eligible'
+                ? 'local-editor'
+                : null);
+    // --- Profile-task compatibility check ---
+    // Only applies when input.targetProfile is EXPLICITLY set.
+    // When auto-derived (input.targetProfile is null), compatibility is already
+    // guaranteed by the auto-derivation logic above (reader_eligible → local-reader).
+    // This check prevents routing a reader task to an editor profile (or vice versa)
+    // when the caller explicitly requests the wrong profile.
+    const isProfileCompatible = input.targetProfile === undefined
+        ? true // Auto-derived profile is always compatible by construction
+        : targetProfile === 'local-reader'
+            ? classification === 'reader_eligible'
+            : targetProfile === 'local-editor'
+                ? classification === 'editor_eligible'
+                : false;
+    // --- Deployment availability check ---
+    let deploymentCheck = {
+        performed: false,
+        profileAvailable: false,
+        routingEnabled: false,
+        checkpointDeployable: false,
+    };
+    if (targetProfile) {
+        const deployment = getDeployment(stateDir, targetProfile);
+        const activeCheckpointId = deployment?.activeCheckpointId ?? null;
+        // Re-check deployability on every routing decision — a checkpoint may have been revoked
+        const checkpointDeployable = activeCheckpointId
+            ? isCheckpointDeployable(stateDir, activeCheckpointId)
+            : false;
+        deploymentCheck = {
+            performed: true,
+            profileAvailable: deployment !== null,
+            routingEnabled: isRoutingEnabledForProfile(stateDir, targetProfile),
+            checkpointDeployable,
+        };
+    }
+    // --- Build the decision (delegated to core pure functions) ---
+    const blockers = coreBuildBlockers(classification, input);
+    const reason = coreBuildReason(classification, input);
+    // FAIL-CLOSED: route_local only if:
+    //   1. Classification is eligible (reader_eligible or editor_eligible)
+    //   2. A target profile was identified
+    //   3. The task's natural profile is compatible with the target profile
+    //   4. Deployment is available and routing is enabled
+    const isEligibleForRouting = (classification === 'reader_eligible' || classification === 'editor_eligible') &&
+        targetProfile !== null &&
+        isProfileCompatible &&
+        deploymentCheck.routingEnabled;
+    const decision = isEligibleForRouting
+        ? 'route_local'
+        : 'stay_main';
+    // Derive the final classification — preserves the root cause of stay_main:
+    //   - profile_mismatch: task would be eligible but wrong profile requested
+    //   - deployment_unavailable: eligible and compatible but no routing enabled
+    //   - raw classification: blocked by high_entropy / risk / ambiguous
+    const isEligible = classification === 'reader_eligible' || classification === 'editor_eligible';
+    const finalClassification = isEligibleForRouting
+        ? classification
+        : isEligible && targetProfile !== null && !isProfileCompatible
+            ? 'profile_mismatch'
+            : isEligible
+                ? 'deployment_unavailable'
+                : classification;
+    // Build explainability fields specific to the stay_main reason
+    let finalReason = reason;
+    let finalBlockers = blockers;
+    if (decision === 'stay_main') {
+        if (finalClassification === 'profile_mismatch') {
+            const wanted = classification === 'reader_eligible' ? 'local-reader' : 'local-editor';
+            finalReason = `Task is ${classification} but was explicitly targeted at ${targetProfile}. ` +
+                `Routing requires "${wanted}" profile. Ensure the task intent matches the requested profile.`;
+            finalBlockers = [
+                `profile mismatch: task is ${classification} but targetProfile is ${targetProfile}`,
+                `required profile: ${wanted}`,
+            ];
+        }
+        else if (finalClassification === 'deployment_unavailable') {
+            if (!deploymentCheck.performed) {
+                finalReason = reason;
+            }
+            else if (!deploymentCheck.profileAvailable) {
+                finalReason = `Task is ${classification} but no deployment exists for ${targetProfile}. ` +
+                    `Bind a checkpoint via bindCheckpointToWorkerProfile() and enable routing.`;
+                finalBlockers = [`no deployment found for profile: ${targetProfile}`];
+            }
+            else if (!deploymentCheck.checkpointDeployable) {
+                finalReason = `Task is ${classification} but the active checkpoint has been revoked (no longer deployable). ` +
+                    `Re-bind a passing checkpoint or re-evaluate the current one.`;
+                finalBlockers = [
+                    `active checkpoint is no longer deployable: ${targetProfile}`,
+                    'revoked checkpoints must not be used for routing',
+                ];
+            }
+            else if (!deploymentCheck.routingEnabled) {
+                finalReason = `Task is ${classification} and deployment exists for ${targetProfile} but routing is not enabled. ` +
+                    `Enable routing via enableRoutingForProfile() in the deployment registry.`;
+                finalBlockers = [`routing is disabled for profile: ${targetProfile}`];
+            }
+        }
+    }
+    // --- Get active checkpoint ID and state for shadow observation integration ---
+    let activeCheckpointId = null;
+    let activeCheckpointState = null;
+    if (targetProfile && deploymentCheck.performed) {
+        const deployment = getDeployment(stateDir, targetProfile);
+        activeCheckpointId = deployment?.activeCheckpointId ?? null;
+        if (activeCheckpointId) {
+            const promotionState = getPromotionState(stateDir, activeCheckpointId);
+            if (promotionState === 'shadow_ready' || promotionState === 'promotable' || promotionState === 'candidate_only') {
+                activeCheckpointState = promotionState;
+            }
+        }
+    }
+    return {
+        decision,
+        targetProfile: decision === 'route_local' ? targetProfile : null,
+        classification: finalClassification,
+        reason: finalReason,
+        blockers: decision === 'stay_main' ? finalBlockers : [],
+        deploymentCheck,
+        activeCheckpointId,
+        activeCheckpointState: activeCheckpointState ?? undefined,
+        shadowObservationId: undefined,
+    };
+}
+/**
+ * Convenience: check if a specific profile can handle a task.
+ * Equivalent to calling classifyTask with targetProfile set.
+ */
+export function canRouteToProfile(input, stateDir, profile) {
+    const decision = classifyTask({ ...input, targetProfile: profile }, stateDir);
+    return decision.decision === 'route_local';
+}
+// ---------------------------------------------------------------------------
+// Read-Only Query Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Check if any local worker routing is currently enabled for any profile.
+ */
+export function isAnyLocalRoutingEnabled(stateDir) {
+    return isRoutingEnabledForProfile(stateDir, 'local-reader') ||
+        isRoutingEnabledForProfile(stateDir, 'local-editor');
+}
+/**
+ * List all profiles that currently have routing enabled.
+ */
+export function listEnabledProfiles(stateDir) {
+    const enabled = [];
+    if (isRoutingEnabledForProfile(stateDir, 'local-reader'))
+        enabled.push('local-reader');
+    if (isRoutingEnabledForProfile(stateDir, 'local-editor'))
+        enabled.push('local-editor');
+    return enabled;
+}

package/dist/core/migration.d.ts

@@ -0,0 +1,6 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+/**
+ * Handles migration of Principles Disciple files from legacy directories
+ * (docs/ and memory/.state/) to the new hidden directory structure (.principles/ and .state/).
+ */
+export declare function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir: string): void;

package/{src/core/migration.ts → dist/core/migration.js}

@@ -1,20 +1,16 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import type { OpenClawPluginApi } from '../openclaw-sdk.js';
-import type { PD_FILES} from './paths.js';
 import { resolvePdPath } from './paths.js';
-
 /**
  * Handles migration of Principles Disciple files from legacy directories
  * (docs/ and memory/.state/) to the new hidden directory structure (.principles/ and .state/).
  */
-export function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir: string): void {
+export function migrateDirectoryStructure(api, workspaceDir) {
     try {
         const legacyDocsDir = path.join(workspaceDir, 'docs');
         const legacyStateDir = path.join(workspaceDir, 'memory', '.state');
-        
         // Comprehensive migration map covering ALL legacy locations
-        const migrationMap: { legacy: string; newKey: keyof typeof PD_FILES }[] = [
+        const migrationMap = [
             // From docs/
             { legacy: path.join(legacyDocsDir, 'PRINCIPLES.md'), newKey: 'PRINCIPLES' },
             { legacy: path.join(legacyDocsDir, 'THINKING_OS.md'), newKey: 'THINKING_OS' },
@@ -24,7 +20,6 @@ export function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir:
             { legacy: path.join(legacyDocsDir, 'SYSTEM_CAPABILITIES.json'), newKey: 'SYSTEM_CAPABILITIES' },
             { legacy: path.join(legacyDocsDir, 'SYSTEM.log'), newKey: 'SYSTEM_LOG' },
             { legacy: path.join(legacyDocsDir, 'THINKING_OS_CANDIDATES.md'), newKey: 'THINKING_OS_CANDIDATES' },
-
             // From memory/.state/ (The hidden legacy state)
             { legacy: path.join(legacyStateDir, 'pain_dictionary.json'), newKey: 'DICTIONARY' },
             { legacy: path.join(legacyStateDir, 'pain_settings.json'), newKey: 'PAIN_SETTINGS' },
@@ -34,39 +29,35 @@ export function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir:
             { legacy: path.join(legacyStateDir, 'sessions'), newKey: 'SESSION_DIR' },
             { legacy: path.join(legacyStateDir, 'logs', 'events.jsonl'), newKey: 'SYSTEM_LOG' }, // Backup plan for logs
         ];
-
         let migratedCount = 0;
-
         for (const entry of migrationMap) {
             if (fs.existsSync(entry.legacy)) {
                 const newPath = resolvePdPath(workspaceDir, entry.newKey);
                 const newDir = path.dirname(newPath);
-
                 if (!fs.existsSync(newDir)) {
                     fs.mkdirSync(newDir, { recursive: true });
                 }
-
                 // If it's a file, rename it. If it's a directory (sessions), handle carefully.
                 if (!fs.existsSync(newPath)) {
                     try {
                         fs.renameSync(entry.legacy, newPath);
                         api.logger.info(`[PD:Migration] Migrated ${path.basename(entry.legacy)} to ${newPath.replace(workspaceDir, '')}`);
                         migratedCount++;
-                    } catch (renameErr) {
+                    }
+                    catch (renameErr) {
                         api.logger.error(`[PD:Migration] Failed to rename ${entry.legacy}: ${String(renameErr)}`);
                     }
-                } else {
+                }
+                else {
                     // Special case: Log append instead of overwrite if it's SYSTEM_LOG? 
                     // For now, keep it simple and skip if exists to avoid data corruption.
                     api.logger?.warn?.(`[PD:Migration] Skipping ${path.basename(entry.legacy)}: already exists at destination.`);
                 }
             }
         }
-
         if (migratedCount > 0) {
             api.logger.info(`[PD:Migration] Successfully migrated ${migratedCount} files/folders to new architecture.`);
         }
-
         // Final cleanup: Try to remove legacy state dir if empty
         if (fs.existsSync(legacyStateDir)) {
             try {
@@ -83,12 +74,13 @@ export function migrateDirectoryStructure(api: OpenClawPluginApi, workspaceDir:
                         api.logger.info(`[PD:Migration] Cleaned up empty legacy state directory.`);
                     }
                 }
-            } catch (_e) {
+            }
+            catch (_e) {
                 api.logger.debug?.(`[PD:Migration] Failed to cleanup legacy state dir: ${String(_e)}`);
             }
         }
-
-    } catch (err) {
+    }
+    catch (err) {
         api.logger.error(`[PD:Migration] Directory refactor migration failed: ${String(err)}`);
     }
 }

package/dist/core/model-deployment-registry.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Model Deployment Registry — Worker Profile → Checkpoint Binding & Routing Control
+ * ===============================================================================
+ *
+ * PURPOSE: Establish auditable, reversible bindings between worker profiles and
+ * trained model checkpoints so that routing decisions are code-governed and
+ * rollback-safe.
+ *
+ * ARCHITECTURE:
+ *   - Registry file: {stateDir}/.state/nocturnal/deployment-registry.json
+ *   - File locking on all write operations
+ *   - Immutable deployment records — rollback uses previousCheckpointId
+ *   - Tight integration with model-training-registry for checkpoint validation
+ *
+ * PROFILE CONSTRAINTS (Phase 5 only):
+ *   - local-reader  → must bind a checkpoint whose targetModelFamily is a "reader" family
+ *   - local-editor  → must bind a checkpoint whose targetModelFamily is an "editor" family
+ *   - No other profiles are accepted
+ *
+ * BINDING RULES:
+ *   - Only a deployable checkpoint can be bound
+ *   - The checkpoint's targetModelFamily must satisfy the profile's family constraint
+ *   - binding sets routingEnabled = false; enableRoutingForProfile() must be called explicitly
+ *   - rollbackDeployment() returns to previousCheckpointId (if any)
+ *
+ * DESIGN CONSTRAINTS:
+ *   - No actual task routing execution (Phase 5 only)
+ *   - No automatic promotion or failover
+ *   - Registry is append-only for deployments; rollback creates a new binding
+ */
+import type { Checkpoint } from './model-training-registry.js';
+/**
+ * Worker profiles supported in Phase 5.
+ * Only these two profiles may be registered.
+ */
+export type WorkerProfile = 'local-reader' | 'local-editor';
+/**
+ * The set of valid Phase 5 worker profile names.
+ */
+export declare const SUPPORTED_PROFILES: readonly WorkerProfile[];
+/**
+ * A deployment record — binds a worker profile to a specific checkpoint
+ * and controls whether routing is enabled for that profile.
+ */
+export interface Deployment {
+    /** Unique identifier for this deployment record */
+    deploymentId: string;
+    /** Worker profile this deployment targets (local-reader | local-editor) */
+    workerProfile: WorkerProfile;
+    /**
+     * The model family this deployment targets.
+     * Derived from the bound checkpoint at bind time; stored for quick queries.
+     */
+    targetModelFamily: string;
+    /**
+     * The currently active checkpoint for this profile.
+     * null means the profile is bound but no checkpoint is active (e.g., after rollback).
+     */
+    activeCheckpointId: string | null;
+    /**
+     * The previously active checkpoint (before the current activeCheckpointId).
+     * Used for rollback. null if no previous checkpoint exists.
+     */
+    previousCheckpointId: string | null;
+    /**
+     * Whether routing to this worker profile is currently permitted.
+     * Must be explicitly enabled via enableRoutingForProfile().
+     * Cannot be true if activeCheckpointId is null.
+     */
+    routingEnabled: boolean;
+    /** ISO-8601 timestamp — when this binding was first created */
+    deployedAt: string;
+    /** ISO-8601 timestamp — when this binding was last updated (checkpoint change or flag toggle) */
+    updatedAt: string;
+    /**
+     * Optional human-readable note about this deployment.
+     * E.g., "initial deployment", "rollback from eval failure", "promoted after 30-day holdout".
+     */
+    note?: string;
+}
+/**
+ * The complete deployment registry — all deployment records in one store.
+ */
+export interface ModelDeploymentRegistry {
+    deployments: Deployment[];
+}
+/**
+ * Validate that a worker profile name is supported in Phase 5.
+ *
+ * @throws Error if the profile is not in SUPPORTED_PROFILES
+ */
+export declare function assertSupportedProfile(profile: string): asserts profile is WorkerProfile;
+/**
+ * Check if a checkpoint has passed the promotion gate and can be deployed.
+ *
+ * This function checks:
+ * 1. The checkpoint has an eval summary attached (lineage complete)
+ * 2. The promotion state is 'shadow_ready' or 'promotable' (gate passed)
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint to verify
+ * @returns true if the checkpoint can be deployed, false otherwise
+ */
+export declare function hasPassedPromotionGate(stateDir: string, checkpointId: string): boolean;
+/**
+ * Assert that a checkpoint has passed the promotion gate.
+ * Throws if the checkpoint cannot be deployed.
+ *
+ * @param stateDir - Workspace state directory
+ * @param checkpointId - Checkpoint to verify
+ * @throws Error if the checkpoint has not passed the promotion gate
+ */
+export declare function assertPromotionGatePassed(stateDir: string, checkpointId: string): void;
+/**
+ * Bind a checkpoint to a worker profile, creating or updating the deployment record.
+ *
+ * BINDING RULE (fail-closed):
+ *   Only a checkpoint that is marked deployable in the training registry may be bound.
+ *
+ * PROFILE-FAMILY CONSTRAINT:
+ *   The checkpoint's targetModelFamily must satisfy the profile's family keyword constraint.
+ *   See: validateProfileFamilyConstraint()
+ *
+ * @param stateDir - Workspace state directory
+ * @param workerProfile - Target worker profile (local-reader | local-editor)
+ * @param checkpointId - Checkpoint to bind (must be deployable)
+ * @param note - Optional human-readable note
+ * @returns The new or updated Deployment record
+ *
+ * @throws Error if checkpoint is not found or not deployable
+ * @throws Error if checkpoint's targetModelFamily violates profile constraints
+ */
+export declare function bindCheckpointToWorkerProfile(stateDir: string, workerProfile: WorkerProfile, checkpointId: string, note?: string): Deployment;
+/**
+ * Retrieve the deployment record for a worker profile.
+ *
+ * @returns Deployment if found, null otherwise
+ */
+export declare function getDeployment(stateDir: string, workerProfile: WorkerProfile): Deployment | null;
+/**
+ * List all deployments, optionally filtered.
+ *
+ * @param stateDir - Workspace state directory
+ * @param filter - Optional filter criteria
+ */
+export declare function listDeployments(stateDir: string, filter?: {
+    workerProfile?: WorkerProfile;
+    routingEnabled?: boolean;
+}): Deployment[];
+/**
+ * Enable routing for a worker profile.
+ *
+ * PRECONDITIONS (fail-closed):
+ *   1. A deployment record must exist for this profile
+ *   2. activeCheckpointId must not be null
+ *
+ * @throws Error if no deployment exists
+ * @throws Error if activeCheckpointId is null (nothing to route to)
+ */
+export declare function enableRoutingForProfile(stateDir: string, workerProfile: WorkerProfile): Deployment;
+/**
+ * Disable routing for a worker profile.
+ * This is always safe — it does not unbind the checkpoint.
+ *
+ * @throws Error if no deployment exists for the profile
+ */
+export declare function disableRoutingForProfile(stateDir: string, workerProfile: WorkerProfile): Deployment;
+/**
+ * Roll back the deployment for a worker profile to its previous checkpoint.
+ *
+ * ROLLBACK RULE:
+ *   - Can only roll back if previousCheckpointId is not null
+ *   - Sets activeCheckpointId = previousCheckpointId
+ *   - The old activeCheckpointId becomes the new previousCheckpointId
+ *   - routingEnabled is set to false (must be re-enabled explicitly)
+ *
+ * @throws Error if no deployment exists
+ * @throws Error if no previous checkpoint is available
+ */
+export declare function rollbackDeployment(stateDir: string, workerProfile: WorkerProfile, note?: string): Deployment;
+/**
+ * Check whether a worker profile currently has an enabled deployment
+ * with an active checkpoint that is still deployable.
+ *
+ * GOVERNANCE: Even if routing was previously enabled, a checkpoint that
+ * has been revoked (marked non-deployable via markCheckpointDeployable(false))
+ * must not be used for routing. This prevents routing traffic to a
+ * checkpoint that has been superseded or failed re-evaluation.
+ */
+export declare function isRoutingEnabledForProfile(stateDir: string, workerProfile: WorkerProfile): boolean;
+/**
+ * Get the active checkpoint ID for a worker profile.
+ * Returns null if no deployment or no active checkpoint.
+ */
+export declare function getActiveCheckpointForProfile(stateDir: string, workerProfile: WorkerProfile): string | null;
+/**
+ * Get the full deployment record with lineage context.
+ * Returns null if no deployment exists.
+ *
+ * Lineage includes: deployment record, active checkpoint, parent training run, eval summary.
+ */
+export declare function getDeploymentLineage(stateDir: string, workerProfile: WorkerProfile): {
+    deployment: Deployment;
+    activeCheckpoint: Checkpoint | null;
+} | null;
+/**
+ * Get the complete deployment registry (for debugging/admin purposes).
+ */
+export declare function getFullDeploymentRegistry(stateDir: string): ModelDeploymentRegistry;
+/**
+ * Compute stats for the deployment registry.
+ */
+export declare function getDeploymentRegistryStats(stateDir: string): {
+    totalDeployments: number;
+    activeDeployments: number;
+    profilesWithBindings: number;
+    profilesWithRoutingEnabled: number;
+};