principles-disciple 1.7.5 → 1.7.8

package/dist/core/external-training-contract.js

@@ -0,0 +1,269 @@
+/**
+ * External Training Contract — Normalized Experiment Spec and Result Schema
+ * ========================================================================
+ *
+ * PURPOSE: Define the stable contract between the plugin and external trainer
+ * backends. The plugin produces a constrained experiment specification that an
+ * external trainer consumes. The trainer returns a normalized result that the
+ * plugin can register, evaluate, and gate for rollout.
+ *
+ * ARCHITECTURE:
+ *   - Plugin is responsible for creating the experiment spec
+ *   - Plugin is responsible for validating the trainer result
+ *   - Plugin is responsible for registering lineage (train run → checkpoint → eval)
+ *   - Plugin is responsible for invoking benchmark evaluation
+ *   - Plugin is responsible for invoking promotion gate logic
+ *   - Plugin is responsible for binding deployment only after gate approval
+ *
+ * DESIGN CONSTRAINTS:
+ *   - ORPO-first: trainingMode must be 'orpo' for production runs
+ *   - No real training inside the plugin
+ *   - No direct deployment promotion from trainer output
+ *   - No direct trainer writes to review/eval/deployment state
+ *   - Backend-pluggable: same contract works for all backends
+ *
+ * CONTRACT GOALS:
+ *   - support ORPO training for approved nocturnal exports
+ *   - support multiple backend implementations behind one schema
+ *   - preserve dataset / config / checkpoint lineage
+ *   - remain valid on consumer hardware
+ *   - fail closed when inputs are incomplete or inconsistent
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+// ---------------------------------------------------------------------------
+// Contract Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a trainer result matches the experiment spec.
+ *
+ * FAILS CLOSED on any mismatch — a checkpoint with invalid lineage must not
+ * be registered or promoted.
+ *
+ * Validation rules:
+ * 1. experimentId must match
+ * 2. backend must match
+ * 3. targetWorkerProfile must match
+ * 4. targetModelFamily must match
+ * 5. datasetFingerprint must match
+ * 6. configFingerprint must match
+ * 7. codeHash must match
+ * 8. dry-run must not produce a deployable checkpoint
+ *
+ * @param spec - The original experiment spec
+ * @param result - The trainer result to validate
+ * @returns ValidationResult indicating pass/fail and any errors
+ */
+export function validateTrainerResult(spec, result) {
+    const errors = [];
+    // Rule 1: experimentId must match
+    if (spec.experimentId !== result.experimentId) {
+        errors.push({
+            field: 'experimentId',
+            expected: spec.experimentId,
+            actual: result.experimentId,
+            reason: 'Trainer result experimentId does not match the experiment spec',
+        });
+    }
+    // Rule 2: backend must match
+    if (spec.backend !== result.backend) {
+        errors.push({
+            field: 'backend',
+            expected: spec.backend,
+            actual: result.backend,
+            reason: 'Trainer result backend does not match the experiment spec',
+        });
+    }
+    // Rule 3: targetWorkerProfile must match
+    if (spec.targetWorkerProfile !== result.targetWorkerProfile) {
+        errors.push({
+            field: 'targetWorkerProfile',
+            expected: spec.targetWorkerProfile,
+            actual: result.targetWorkerProfile,
+            reason: 'Trainer result targetWorkerProfile does not match the experiment spec',
+        });
+    }
+    // Rule 4: targetModelFamily must match
+    if (spec.targetModelFamily !== result.targetModelFamily) {
+        errors.push({
+            field: 'targetModelFamily',
+            expected: spec.targetModelFamily,
+            actual: result.targetModelFamily,
+            reason: 'Trainer result targetModelFamily does not match the experiment spec',
+        });
+    }
+    // Rule 5: datasetFingerprint must match
+    if (spec.datasetFingerprint !== result.datasetFingerprint) {
+        errors.push({
+            field: 'datasetFingerprint',
+            expected: spec.datasetFingerprint,
+            actual: result.datasetFingerprint,
+            reason: 'Dataset fingerprint mismatch — possible dataset tampering or wrong export used',
+        });
+    }
+    // Rule 6: configFingerprint must match
+    if (spec.configFingerprint !== result.configFingerprint) {
+        errors.push({
+            field: 'configFingerprint',
+            expected: spec.configFingerprint,
+            actual: result.configFingerprint,
+            reason: 'Config fingerprint mismatch — training config may have changed since spec was created',
+        });
+    }
+    // Rule 7: codeHash must match
+    if (spec.codeHash !== result.codeHash) {
+        errors.push({
+            field: 'codeHash',
+            expected: spec.codeHash,
+            actual: result.codeHash,
+            reason: 'Code hash mismatch — training code or contract version may have changed',
+        });
+    }
+    // Rule 8: dry-run must not produce a deployable checkpoint
+    if (spec.backend === 'dry-run') {
+        if (result.status === 'completed' && result.artifact) {
+            errors.push({
+                field: 'artifact',
+                expected: 'no artifact for dry-run',
+                actual: 'artifact present',
+                reason: 'Dry-run backend must not produce a deployable checkpoint',
+            });
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+// ---------------------------------------------------------------------------
+// Spec Creation Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Generate a fingerprint for a configuration object.
+ * Used for configFingerprint in the experiment spec.
+ */
+export function computeConfigFingerprint(config) {
+    const normalized = JSON.stringify(config, Object.keys(config).sort());
+    return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+/**
+ * Generate a fingerprint for a dataset export.
+ * Used for datasetFingerprint in the experiment spec.
+ *
+ * Combines file content hash with sampleCount to detect:
+ * - Content changes (file modified/replaced)
+ * - Sample count changes (different export)
+ *
+ * If the file cannot be read, falls back to path+count hash (legacy behavior).
+ */
+export function computeDatasetFingerprint(exportPath, sampleCount) {
+    let contentHash;
+    try {
+        const content = fs.readFileSync(exportPath, 'utf-8');
+        contentHash = crypto.createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
+    }
+    catch {
+        // Fallback: include path in hash so different paths still differ
+        // (even if files don't exist during spec creation)
+        const fallbackContent = `${exportPath}:${sampleCount}`;
+        return crypto.createHash('sha256').update(fallbackContent).digest('hex').slice(0, 16);
+    }
+    // Combine content hash with sample count for additional safety
+    const combined = `${contentHash}:${sampleCount}`;
+    return crypto.createHash('sha256').update(combined).digest('hex').slice(0, 16);
+}
+/**
+ * Generate a code hash for the training contract version.
+ * Used for codeHash in the experiment spec.
+ *
+ * Hashes the actual contract source file content so any change to the
+ * contract produces a different hash, ensuring lineage integrity.
+ *
+ * Falls back to version string + timestamp if source cannot be read.
+ */
+export function computeCodeHash() {
+    try {
+        // Hash the actual contract source file content using ESM-safe resolution
+        const sourcePath = fileURLToPath(import.meta.url);
+        const sourceContent = fs.readFileSync(sourcePath, 'utf-8');
+        // Include only the relevant contract definitions (first 500 lines)
+        // to avoid hash changes from comments/timestamps
+        const relevantContent = sourceContent.split('\n').slice(0, 500).join('\n');
+        return crypto.createHash('sha256').update(relevantContent).digest('hex').slice(0, 16);
+    }
+    catch {
+        // Fallback if source cannot be read (should not happen in normal operation)
+        // Use a deterministic version string — NOT Date.now() — so the hash is stable
+        const fallback = 'nocturnal-phase7-v1:deterministic-fallback';
+        return crypto.createHash('sha256').update(fallback).digest('hex').slice(0, 16);
+    }
+}
+/**
+ * Generate a new experiment ID.
+ */
+export function generateExperimentId() {
+    return crypto.randomUUID();
+}
+// ---------------------------------------------------------------------------
+// Hardware Tier Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a hardware tier is appropriate for the backend.
+ *
+ * @param backend - The backend being used
+ * @param tier - The hardware tier
+ * @throws Error if the combination is not supported
+ */
+export function validateHardwareTier(backend, tier) {
+    // cpu-experimental is only allowed for dry-run
+    if (tier === 'cpu-experimental' && backend !== 'dry-run') {
+        throw new Error(`Hardware tier 'cpu-experimental' is only allowed for 'dry-run' backend. ` +
+            `For real training on GPU, use 'consumer-gpu' or 'small-gpu'.`);
+    }
+}
+/**
+ * Get the default hardware tier for a backend.
+ */
+export function getDefaultHardwareTier(backend) {
+    if (backend === 'dry-run') {
+        return 'cpu-experimental';
+    }
+    return 'consumer-gpu';
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Valid model family patterns for local-reader profile.
+ * Used for family validation in the training contract.
+ */
+export const READER_FAMILY_PATTERNS = [
+    'reader', 'read', 'claude-haiku', 'qwen-lite', 'phi-mini',
+    'gpt-4o-mini', 'gpt-4o-nano',
+];
+/**
+ * Valid model family patterns for local-editor profile.
+ * Used for family validation in the training contract.
+ */
+export const EDITOR_FAMILY_PATTERNS = [
+    'editor', 'edit', 'code', 'claude-sonnet', 'gpt-4o-mini',
+];
+/**
+ * Check if a model family is valid for a worker profile.
+ */
+export function isValidModelFamilyForProfile(family, profile) {
+    const lower = family.toLowerCase();
+    if (profile === 'local-reader') {
+        return READER_FAMILY_PATTERNS.some((p) => lower.includes(p));
+    }
+    if (profile === 'local-editor') {
+        return EDITOR_FAMILY_PATTERNS.some((p) => lower.includes(p));
+    }
+    return false;
+}
+/**
+ * Phase 7 first rollout is limited to local-reader.
+ * This flag controls whether local-editor is allowed.
+ */
+export const LOCAL_EDITOR_ENABLED = false;

package/dist/core/local-worker-routing.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Local Worker Routing Policy — Task Classification and Routing Decisions
+ * ======================================================================
+ *
+ * PURPOSE: Provide an explainable, testable policy that decides whether a given
+ * task can be delegated to a local-worker profile (local-reader or local-editor)
+ * or must stay on the main agent.
+ *
+ * ARCHITECTURE:
+ *   - This module is POLICY ONLY — it makes routing decisions but does NOT execute them
+ *   - The main agent (or a delegation hook in a future phase) is responsible for
+ *     actually routing the task based on the RoutingDecision returned here
+ *   - All decisions are deterministic and based on structured input fields
+ *   - No model inference, no learning, no dynamic adaptation
+ *
+ * TASK CLASSIFICATION TAXONOMY:
+ *   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
+ *   risk_disallowed     — tasks with destructive or high-risk signals
+ *   ambiguous_scope     — tasks that are unclear and need main-agent judgment
+ *   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
+ *   - Any risk signal → stay_main
+ *   - No enabled deployment → stay_main
+ *
+ * DESIGN CONSTRAINTS:
+ *   - No actual task execution
+ *   - No automatic learning or route optimization
+ *   - No Trinity or adaptive threshold logic
+ *   - Routing decisions are fully explainable (return `reason` + `blockers[]`)
+ */
+import type { WorkerProfile } from './model-deployment-registry.js';
+/**
+ * The input contract for a routing decision.
+ * All fields are optional — the classifier handles missing data gracefully
+ * by treating it as ambiguous (stay_main).
+ */
+export interface RoutingInput {
+    /**
+     * A short label or name for the task intent.
+     * E.g., "read_file", "edit_config", "debug_memory_leak", "design_system"
+     */
+    taskIntent?: string;
+    /**
+     * Natural-language description of the task.
+     * The classifier examines this for keywords indicating complexity/risk.
+     */
+    taskDescription?: string;
+    /**
+     * Specific tools requested or implied by the task.
+     * These are examined for risk signals (e.g., bash, rm, git push).
+     */
+    requestedTools?: string[];
+    /**
+     * Specific files involved or targeted.
+     * Examined for risk-path indicators (e.g., .git/, node_modules, production configs).
+     */
+    requestedFiles?: string[];
+    /**
+     * Shape of expected output.
+     * E.g., "json", "markdown", "one_line", "full_report"
+     */
+    expectedOutputShape?: string;
+    /**
+     * Explicit risk signals detected in the task.
+     * E.g., ["destructive", "production", "irreversible", "large_scale"]
+     * Any non-empty riskSignals → automatic stay_main.
+     */
+    riskSignals?: string[];
+    /**
+     * Complexity hints for the task.
+     * E.g., ["multi_step", "cross_file", "ambiguous", "requires_planning"]
+     */
+    complexityHints?: string[];
+    /**
+     * Target worker profile for routing consideration.
+     * If omitted, both profiles are evaluated and the best match is returned.
+     */
+    targetProfile?: WorkerProfile;
+}
+/**
+ * The result of a routing classification decision.
+ * Always includes a `reason` and a `blockers` list for full explainability.
+ */
+export interface RoutingDecision {
+    /**
+     * The routing verdict.
+     * - `route_local` — the task may be delegated to `targetProfile`
+     * - `stay_main` — the task must remain on the main agent
+     */
+    decision: 'route_local' | 'stay_main';
+    /**
+     * Which profile the task should be routed to (if decision === 'route_local').
+     * Null if decision === 'stay_main'.
+     */
+    targetProfile: WorkerProfile | null;
+    /**
+     * The task classification category that led to this decision.
+     */
+    classification: 'reader_eligible' | 'editor_eligible' | 'high_entropy_disallowed' | 'risk_disallowed' | 'ambiguous_scope' | 'profile_mismatch' | 'deployment_unavailable';
+    /**
+     * Human-readable explanation of the routing decision.
+     * Must be specific enough that a developer can understand why a task was accepted/rejected.
+     */
+    reason: string;
+    /**
+     * List of specific reasons that blocked routing (if decision === 'stay_main').
+     * Empty if decision === 'route_local'.
+     */
+    blockers: string[];
+    /**
+     * Whether a deployment check was performed and whether it passed.
+     * Useful for diagnostics when deployment_unavailable is the classification.
+     */
+    deploymentCheck: {
+        performed: boolean;
+        profileAvailable: boolean;
+        routingEnabled: boolean;
+        /** Whether the active checkpoint is currently marked as deployable in the training registry. */
+        checkpointDeployable: boolean;
+    };
+    /**
+     * The active checkpoint ID that would be used for routing (if decision === 'route_local').
+     * This is the checkpoint from the deployment registry.
+     * Null if decision === 'stay_main' or if no checkpoint is active.
+     *
+     * USE FOR SHADOW OBSERVATIONS:
+     * When routing in shadow mode (checkpoint is in shadow_ready state),
+     * the caller should record a shadow observation using this checkpoint ID.
+     */
+    activeCheckpointId: string | null;
+    /**
+     * The promotion state of the active checkpoint.
+     * Indicates whether this is a regular deployment or a shadow rollout.
+     * Useful for determining whether to record shadow observations.
+     */
+    activeCheckpointState?: 'promotable' | 'shadow_ready' | 'candidate_only';
+    /**
+     * Deprecated: runtime shadow observations are now recorded from real
+     * subagent lifecycle hooks instead of from classifyTask().
+     */
+    shadowObservationId?: string;
+}
+/**
+ * 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
+ *   2. Checks deployment availability for the target profile
+ *   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 declare function classifyTask(input: RoutingInput, stateDir: string): RoutingDecision;
+/**
+ * Convenience: check if a specific profile can handle a task.
+ * Equivalent to calling classifyTask with targetProfile set.
+ */
+export declare function canRouteToProfile(input: RoutingInput, stateDir: string, profile: WorkerProfile): boolean;
+/**
+ * Check if any local worker routing is currently enabled for any profile.
+ */
+export declare function isAnyLocalRoutingEnabled(stateDir: string): boolean;
+/**
+ * List all profiles that currently have routing enabled.
+ */
+export declare function listEnabledProfiles(stateDir: string): WorkerProfile[];