principles-disciple 1.133.0 → 1.135.0

package/dist/core/schema/schema-definitions.js

@@ -49,6 +49,8 @@ export const SCHEMAS = {
           empathy_signal_json TEXT NOT NULL,
           blob_ref TEXT,
           raw_excerpt TEXT,
+          stop_reason TEXT,
+          thinking_blocks_count INTEGER,
           created_at TEXT NOT NULL
         )`,
                 indexes: [
@@ -87,6 +89,7 @@ export const SCHEMAS = {
           gfi_before REAL,
           gfi_after REAL,
           params_json TEXT NOT NULL,
+          result_preview TEXT,
           created_at TEXT NOT NULL
         )`,
                 indexes: [

package/dist/core/trajectory-types.d.ts

@@ -28,6 +28,8 @@ export interface TrajectoryAssistantTurnInput {
     sanitizedText: string;
     usageJson: unknown;
     empathySignalJson: unknown;
+    stopReason?: string | null;
+    thinkingBlocksCount?: number | null;
     createdAt?: string;
 }
 export interface TrajectoryUserTurnInput {
@@ -50,6 +52,7 @@ export interface TrajectoryToolCallInput {
     gfiBefore?: number | null;
     gfiAfter?: number | null;
     paramsJson?: unknown;
+    resultPreview?: string | null;
     createdAt?: string;
 }
 export interface TrajectoryPainEventInput {
@@ -190,6 +193,8 @@ export interface AssistantTurnRecord {
     rawText: string;
     sanitizedText: string;
     blobRef: string | null;
+    stopReason: string | null;
+    thinkingBlocksCount: number | null;
     createdAt: string;
 }
 export interface CorrectionSampleRecord {

package/dist/core/trajectory.d.ts

@@ -118,6 +118,7 @@ export declare class TrajectoryDatabase {
         errorMessage: string | null;
         gfiBefore: number | null;
         gfiAfter: number | null;
+        resultPreview: string | null;
         createdAt: string;
     }[];
     /**

package/dist/core/trajectory.js

@@ -93,9 +93,9 @@ export class TrajectoryDatabase {
             const result = this.db.prepare(`
         INSERT INTO assistant_turns (
           session_id, run_id, provider, model, raw_text, sanitized_text, usage_json,
-          empathy_signal_json, blob_ref, raw_excerpt, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(input.sessionId, input.runId, input.provider, input.model, rawStorage.inlineText, input.sanitizedText, safeJson(input.usageJson), safeJson(input.empathySignalJson), rawStorage.blobRef, rawStorage.excerpt, createdAt);
+          empathy_signal_json, blob_ref, raw_excerpt, stop_reason, thinking_blocks_count, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.sessionId, input.runId, input.provider, input.model, rawStorage.inlineText, input.sanitizedText, safeJson(input.usageJson), safeJson(input.empathySignalJson), rawStorage.blobRef, rawStorage.excerpt, input.stopReason ?? null, input.thinkingBlocksCount ?? null, createdAt);
             return Number(result.lastInsertRowid);
         });
     }
@@ -120,9 +120,9 @@ export class TrajectoryDatabase {
             const result = this.db.prepare(`
         INSERT INTO tool_calls (
           session_id, tool_name, outcome, duration_ms, exit_code, error_type, error_message,
-          gfi_before, gfi_after, params_json, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(input.sessionId, input.toolName, input.outcome, input.durationMs ?? null, input.exitCode ?? null, input.errorType ?? null, input.errorMessage ?? null, input.gfiBefore ?? null, input.gfiAfter ?? null, safeJson(input.paramsJson), createdAt);
+          gfi_before, gfi_after, params_json, result_preview, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(input.sessionId, input.toolName, input.outcome, input.durationMs ?? null, input.exitCode ?? null, input.errorType ?? null, input.errorMessage ?? null, input.gfiBefore ?? null, input.gfiAfter ?? null, safeJson(input.paramsJson), input.resultPreview ?? null, createdAt);
             return Number(result.lastInsertRowid);
         });
         if (input.outcome === 'success') {
@@ -548,7 +548,8 @@ export class TrajectoryDatabase {
      */
     listAssistantTurns(sessionId) {
         const rows = this.db.prepare(`
-      SELECT id, session_id, run_id, provider, model, raw_text, sanitized_text, blob_ref, created_at
+      SELECT id, session_id, run_id, provider, model, raw_text, sanitized_text, blob_ref,
+             stop_reason, thinking_blocks_count, created_at
       FROM assistant_turns
       WHERE session_id = ?
       ORDER BY id ASC
@@ -562,6 +563,8 @@ export class TrajectoryDatabase {
             rawText: this.restoreRawText(row.raw_text, row.blob_ref),
             sanitizedText: String(row.sanitized_text ?? ''),
             blobRef: row.blob_ref ? String(row.blob_ref) : null,
+            stopReason: row.stop_reason != null ? String(row.stop_reason) : null,
+            thinkingBlocksCount: row.thinking_blocks_count != null ? Number(row.thinking_blocks_count) : null,
             createdAt: String(row.created_at),
         }));
     }
@@ -574,7 +577,7 @@ export class TrajectoryDatabase {
     listToolCallsForSession(sessionId) {
         const rows = this.db.prepare(`
       SELECT id, tool_name, outcome, params_json, duration_ms, exit_code, error_type, error_message,
-             gfi_before, gfi_after, created_at
+             gfi_before, gfi_after, result_preview, created_at
       FROM tool_calls
       WHERE session_id = ?
       ORDER BY id ASC
@@ -604,6 +607,7 @@ export class TrajectoryDatabase {
                 errorMessage: row.error_message ? String(row.error_message) : null,
                 gfiBefore: row.gfi_before != null ? Number(row.gfi_before) : null,
                 gfiAfter: row.gfi_after != null ? Number(row.gfi_after) : null,
+                resultPreview: row.result_preview != null ? String(row.result_preview) : null,
                 createdAt: String(row.created_at),
             };
         });
@@ -1085,6 +1089,23 @@ export class TrajectoryDatabase {
                 }
             }
         }
+        // Trajectory enhancement: add stop_reason, thinking_blocks_count, result_preview
+        const trajectoryEnhancementColumns = [
+            { table: 'assistant_turns', name: 'stop_reason', type: 'TEXT' },
+            { table: 'assistant_turns', name: 'thinking_blocks_count', type: 'INTEGER' },
+            { table: 'tool_calls', name: 'result_preview', type: 'TEXT' },
+        ];
+        for (const col of trajectoryEnhancementColumns) {
+            try {
+                this.db.exec(`ALTER TABLE ${col.table} ADD COLUMN ${col.name} ${col.type}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (!message.includes('duplicate column name') && !message.includes('no column named')) {
+                    throw err;
+                }
+            }
+        }
         // PRI-406: Partial unique index on canonical_pain_id (non-null only) for dedup
         this.db.exec(`
       CREATE UNIQUE INDEX IF NOT EXISTS idx_pain_events_canonical_pain_id

package/dist/hooks/after-tool-call-helpers.d.ts

@@ -17,6 +17,11 @@ import { type SessionState } from '../core/session-tracker.js';
 import { WorkspaceContext } from '../core/workspace-context.js';
 import type { PluginHookAfterToolCallEvent } from '../openclaw-sdk.js';
 import type { ToolCallOutcome, ToolCallObservation, PainAdmissionDecision } from './after-tool-call-types.js';
+/**
+ * Extract a preview string from tool call result for diagnostic evidence.
+ * Pure function — no I/O, no side effects. ERR-001 / ERR-014 compliant.
+ */
+export declare function extractToolResultPreview(result: unknown): string | null;
 /**
  * Classify the outcome of a tool call event.
  *

package/dist/hooks/after-tool-call-helpers.js

@@ -25,6 +25,68 @@ import { resolveSourceKind, buildToolFailureObservation } from './raw-observatio
 import { evaluateEvidenceTriage } from './triage-adapter.js';
 import { evaluateTriggerController } from '@principles/core/runtime-v2';
 import { buildTrajectoryEvidence } from './trajectory-evidence.js';
+const RESULT_PREVIEW_MAX_LENGTH = 500;
+/**
+ * Extract a preview string from tool call result for diagnostic evidence.
+ * Pure function — no I/O, no side effects. ERR-001 / ERR-014 compliant.
+ */
+export function extractToolResultPreview(result) {
+    if (result === null || result === undefined)
+        return null;
+    try {
+        // String result: truncate directly
+        if (typeof result === 'string') {
+            return result.length > RESULT_PREVIEW_MAX_LENGTH
+                ? `${result.slice(0, RESULT_PREVIEW_MAX_LENGTH - 3)}...`
+                : result;
+        }
+        // Object with content array (e.g., Anthropic content blocks)
+        if (typeof result === 'object' && !Array.isArray(result)) {
+            const obj = result;
+            if (Array.isArray(obj.content)) {
+                const textParts = [];
+                for (const block of obj.content) {
+                    if (block && typeof block === 'object' && !Array.isArray(block)) {
+                        const blockObj = block;
+                        if (blockObj.type === 'text' && typeof blockObj.text === 'string') {
+                            textParts.push(blockObj.text);
+                        }
+                    }
+                }
+                if (textParts.length > 0) {
+                    const joined = textParts.join('\n');
+                    return joined.length > RESULT_PREVIEW_MAX_LENGTH
+                        ? `${joined.slice(0, RESULT_PREVIEW_MAX_LENGTH - 3)}...`
+                        : joined;
+                }
+            }
+            // Object without content array: JSON.stringify with depth limiter (ERR-014)
+            const serialized = JSON.stringify(obj, (_key, value) => {
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    const keys = Object.keys(value);
+                    if (keys.length > 10) {
+                        const truncated = {};
+                        for (const k of keys.slice(0, 10)) {
+                            truncated[k] = value[k];
+                        }
+                        truncated['__truncated__'] = true;
+                        return truncated;
+                    }
+                }
+                return value;
+            }, 2);
+            if (serialized && serialized !== '{}') {
+                return serialized.length > RESULT_PREVIEW_MAX_LENGTH
+                    ? `${serialized.slice(0, RESULT_PREVIEW_MAX_LENGTH - 3)}...`
+                    : serialized;
+            }
+        }
+        return null;
+    }
+    catch {
+        return '[result_preview_extraction_failed]';
+    }
+}
 // ── Stage 1: Classify ───────────────────────────────────────────────────────
 /**
  * Classify the outcome of a tool call event.
@@ -150,6 +212,7 @@ export function handleFrictionTrackingForFailure(sessionId, event, outcome, obse
         gfiBefore,
         gfiAfter: updatedState.currentGfi,
         paramsJson: sanitizeToolParamsForEvidence(event.params, workspaceDir),
+        resultPreview: extractToolResultPreview(event.result),
     });
     return updatedState;
 }
@@ -188,6 +251,7 @@ export function handleFrictionTrackingForSuccess(sessionId, event, outcome, obse
         gfiBefore,
         gfiAfter: resetState.currentGfi,
         paramsJson: sanitizeToolParamsForEvidence(event.params, workspaceDir),
+        resultPreview: extractToolResultPreview(event.result),
     });
     wctx.eventLog.recordToolCall(sessionId, {
         toolName: event.toolName,

package/dist/hooks/llm.d.ts

@@ -8,6 +8,14 @@ export interface EmpathySignal {
 }
 export declare function extractEmpathySignal(text: string): EmpathySignal;
 export declare function isEmpathyAuditPayload(text: string): boolean;
+/**
+ * Extract enhanced fields from lastAssistant (complete AssistantMessage) in hook payload.
+ * Pure function — no I/O, no side effects. ERR-001 compliant.
+ */
+export declare function extractAssistantEnhancedFields(lastAssistant: unknown): {
+    stopReason: string | null;
+    thinkingBlocksCount: number | null;
+};
 export declare function handleLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext & {
     workspaceDir?: string;
 }): void;

package/dist/hooks/llm.js

@@ -124,6 +124,33 @@ export function isEmpathyAuditPayload(text) {
         return true;
     return false;
 }
+/**
+ * Extract enhanced fields from lastAssistant (complete AssistantMessage) in hook payload.
+ * Pure function — no I/O, no side effects. ERR-001 compliant.
+ */
+export function extractAssistantEnhancedFields(lastAssistant) {
+    if (!lastAssistant || typeof lastAssistant !== 'object' || Array.isArray(lastAssistant)) {
+        return { stopReason: null, thinkingBlocksCount: null };
+    }
+    const obj = lastAssistant;
+    // stopReason: typeof guard
+    const stopReason = typeof obj.stopReason === 'string' ? obj.stopReason : null;
+    // thinkingBlocksCount: iterate content array, count thinking/redacted_thinking blocks
+    let thinkingBlocksCount = null;
+    if (Array.isArray(obj.content)) {
+        let count = 0;
+        for (const block of obj.content) {
+            if (block && typeof block === 'object' && !Array.isArray(block)) {
+                const blockType = block.type;
+                if (blockType === 'thinking' || blockType === 'redacted_thinking') {
+                    count++;
+                }
+            }
+        }
+        thinkingBlocksCount = count;
+    }
+    return { stopReason, thinkingBlocksCount };
+}
 export function handleLlmOutput(event, ctx) {
     if (!ctx.workspaceDir || !ctx.sessionId)
         return;
@@ -142,6 +169,7 @@ export function handleLlmOutput(event, ctx) {
         return;
     const text = event.assistantTexts.join('\n');
     const signal = extractEmpathySignal(text);
+    const enhancedFields = extractAssistantEnhancedFields(event.lastAssistant);
     const createdAt = new Date().toISOString();
     let assistantTurnId = null;
     try {
@@ -154,6 +182,8 @@ export function handleLlmOutput(event, ctx) {
             sanitizedText: sanitizeAssistantText(text),
             usageJson: event.usage || {},
             empathySignalJson: signal,
+            stopReason: enhancedFields.stopReason,
+            thinkingBlocksCount: enhancedFields.thinkingBlocksCount,
             createdAt,
         });
     }

package/dist/hooks/trajectory-evidence.js

@@ -41,9 +41,11 @@ export function buildTrajectoryEvidence(wctx, sessionId) {
             if (evidence.length >= MAX_EVIDENCE_ENTRIES)
                 break;
             const sanitizedNote = sanitizeAssistantText((turn.sanitizedText ?? '').slice(0, MAX_EVIDENCE_NOTE_CHARS));
+            // Enhanced: append truncation warning when stop_reason=length
+            const truncationWarning = turn.stopReason === 'length' ? ' [TRUNCATED: output cut off by length limit]' : '';
             evidence.push({
                 sourceRef: `agent_turn:${turn.createdAt}`,
-                note: sanitizedNote,
+                note: sanitizedNote + truncationWarning,
             });
         }
     }
@@ -62,7 +64,9 @@ export function buildTrajectoryEvidence(wctx, sessionId) {
         for (const tc of failedToolCalls) {
             if (evidence.length >= MAX_EVIDENCE_ENTRIES)
                 break;
-            const note = `Tool ${tc.toolName} failed: ${tc.errorType ?? 'unknown'} (exitCode: ${tc.exitCode ?? 'N/A'})`;
+            // Enhanced: append resultPreview when available
+            const previewSuffix = tc.resultPreview ? ` | ${tc.resultPreview.slice(0, 200)}` : '';
+            const note = `Tool ${tc.toolName} failed: ${tc.errorType ?? 'unknown'} (exitCode: ${tc.exitCode ?? 'N/A'})${previewSuffix}`;
             evidence.push({
                 sourceRef: `tool_call_failure:${tc.createdAt}`,
                 note: sanitizeAssistantText(note.slice(0, MAX_EVIDENCE_NOTE_CHARS)),

package/dist/openclaw-sdk.d.ts

@@ -231,6 +231,7 @@ export interface PluginHookLlmOutputEvent {
     usage?: TokenUsage;
     assistantTexts?: string[];
     trigger?: string;
+    lastAssistant?: unknown;
     [key: string]: unknown;
 }
 export interface PluginHookSubagentSpawningEvent {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.133.0",
+  "version": "1.135.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.133.0",
+  "version": "1.135.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/dist/core/external-training-contract.d.ts

@@ -1,276 +0,0 @@
-/**
- * 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
- */
-/**
- * Allowed backend identifiers.
- *
- * - `peft-trl-orpo`: primary reference implementation using PEFT + TRL ORPO
- * - `unsloth-orpo`: compatible accelerated implementation using Unsloth
- * - `dry-run`: validates paths/spec/environment only, no real training
- */
-export type TrainerBackendKind = 'peft-trl-orpo' | 'unsloth-orpo' | 'dry-run';
-/**
- * Hardware tier for training.
- *
- * - `consumer-gpu`: RTX 4090 24GB or equivalent (production target)
- * - `small-gpu`: 8GB-16GB VRAM (compatibility target)
- * - `cpu-experimental`: CPU-only experimental runs (dry-run or tiny models only)
- */
-export type HardwareTier = 'consumer-gpu' | 'small-gpu' | 'cpu-experimental';
-/**
- * Worker profiles supported for training.
- *
- * Phase 7 first rollout: `local-reader` only.
- * `local-editor` requires explicit human approval to enable.
- */
-export type TrainableWorkerProfile = 'local-reader' | 'local-editor';
-/**
- * Training mode — Phase 7 production is ORPO-only.
- */
-export type TrainingMode = 'orpo';
-/**
- * Hyperparameters for ORPO training.
- */
-export interface TrainingHyperparameters {
-    learningRate: number;
-    batchSize: number;
-    gradientAccumulation: number;
-    loraRank: number;
-    loraAlpha: number;
-    loraDropout: number;
-    warmupRatio: number;
-    maxSteps: number;
-    maxSeqLength: number;
-}
-/**
- * Budget constraints for a training experiment.
- */
-export interface TrainingBudget {
-    maxWallClockMinutes: number;
-    maxTrainTokens?: number;
-}
-/**
- * Expected artifact from a successful training run.
- */
-export interface ExpectedArtifact {
-    checkpointName: string;
-    adapterFormat: 'peft-adapter';
-}
-/**
- * The experiment specification sent to an external trainer.
- * This defines WHAT to train, not HOW to train (backend-specific).
- */
-export interface TrainingExperimentSpec {
-    /** Unique identifier for this experiment */
-    experimentId: string;
-    /** Which backend to use */
-    backend: TrainerBackendKind;
-    /** Training mode — only 'orpo' is supported in Phase 7 */
-    trainingMode: TrainingMode;
-    /** Target worker profile for this experiment */
-    targetWorkerProfile: TrainableWorkerProfile;
-    /** Target model family to train */
-    targetModelFamily: string;
-    /** Hardware tier for this experiment */
-    hardwareTier: HardwareTier;
-    /** Reference to the ORPO export providing training data */
-    datasetExportId: string;
-    datasetExportPath: string;
-    /** Fingerprint of the dataset for lineage verification */
-    datasetFingerprint: string;
-    /** Reference to the benchmark export for eval */
-    benchmarkExportId: string;
-    /** Output directory for checkpoint artifacts */
-    outputDir: string;
-    /** Fingerprint of the training configuration */
-    configFingerprint: string;
-    /** Hash of the training code/contract version */
-    codeHash: string;
-    /** Training hyperparameters */
-    hyperparameters: TrainingHyperparameters;
-    /** Budget constraints */
-    budget: TrainingBudget;
-    /** Expected artifact from training */
-    expectedArtifact: ExpectedArtifact;
-}
-/**
- * Training metrics recorded by the backend.
- */
-export interface TrainingMetrics {
-    wallClockMinutes: number;
-    finalLoss?: number;
-    tokensSeen?: number;
-}
-/**
- * Artifact produced by a successful training run.
- */
-export interface TrainingArtifact {
-    adapterFormat: 'peft-adapter';
-    artifactPath: string;
-}
-/**
- * Status of a training experiment.
- */
-export type ExperimentStatus = 'completed' | 'failed' | 'dry_run';
-/**
- * The result returned by an external trainer after execution.
- * This defines the output contract — all backends must return the same shape.
- */
-export interface TrainingExperimentResult {
-    /** Experiment ID (must match the spec's experimentId) */
-    experimentId: string;
-    /** Which backend was used */
-    backend: TrainerBackendKind;
-    /** Final status of the experiment */
-    status: ExperimentStatus;
-    /** Registered training run ID (plugin-side) */
-    trainRunId?: string;
-    /** Registered checkpoint ID (plugin-side) */
-    checkpointId?: string;
-    /** Checkpoint reference string (for lineage) */
-    checkpointRef?: string;
-    /** Target worker profile */
-    targetWorkerProfile: TrainableWorkerProfile;
-    /** Target model family */
-    targetModelFamily: string;
-    /** Dataset fingerprint (for lineage verification) */
-    datasetFingerprint: string;
-    /** Config fingerprint (for lineage verification) */
-    configFingerprint: string;
-    /** Code hash (for lineage verification) */
-    codeHash: string;
-    /** Training metrics */
-    metrics?: TrainingMetrics;
-    /** Produced artifact (only if status === 'completed') */
-    artifact?: TrainingArtifact;
-    /** Failure reason (only if status === 'failed') */
-    failureReason?: string;
-    /** ISO-8601 creation timestamp */
-    createdAt: string;
-}
-/**
- * Validation error for trainer result verification.
- */
-export interface ValidationError {
-    field: string;
-    expected: string;
-    actual: string;
-    reason: string;
-}
-/**
- * Result of validating a trainer result against the experiment spec.
- */
-export interface ValidationResult {
-    valid: boolean;
-    errors: ValidationError[];
-}
-/**
- * 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 declare function validateTrainerResult(spec: TrainingExperimentSpec, result: TrainingExperimentResult): ValidationResult;
-/**
- * Generate a fingerprint for a configuration object.
- * Used for configFingerprint in the experiment spec.
- */
-export declare function computeConfigFingerprint(config: Partial<TrainingHyperparameters>): string;
-/**
- * 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 declare function computeDatasetFingerprint(exportPath: string, sampleCount: number): string;
-/**
- * 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 declare function computeCodeHash(): string;
-/**
- * Generate a new experiment ID.
- */
-export declare function generateExperimentId(): string;
-/**
- * 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 declare function validateHardwareTier(backend: TrainerBackendKind, tier: HardwareTier): void;
-/**
- * Get the default hardware tier for a backend.
- */
-export declare function getDefaultHardwareTier(backend: TrainerBackendKind): HardwareTier;
-/**
- * Valid model family patterns for local-reader profile.
- * Used for family validation in the training contract.
- */
-export declare const READER_FAMILY_PATTERNS: string[];
-/**
- * Valid model family patterns for local-editor profile.
- * Used for family validation in the training contract.
- */
-export declare const EDITOR_FAMILY_PATTERNS: string[];
-/**
- * Check if a model family is valid for a worker profile.
- */
-export declare function isValidModelFamilyForProfile(family: string, profile: TrainableWorkerProfile): boolean;
-/**
- * Phase 7 first rollout is limited to local-reader.
- * This flag controls whether local-editor is allowed.
- */
-export declare const LOCAL_EDITOR_ENABLED = false;

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

@@ -1,269 +0,0 @@
-/**
- * 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;