principles-disciple 1.8.1 → 1.8.3

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;

package/dist/core/focus-history.d.ts

@@ -1,210 +0,0 @@
-/**
- * CURRENT_FOCUS 历史版本管理
- *
- * 功能：
- * - 压缩时备份当前版本到历史目录
- * - 清理过期历史版本
- * - 读取历史版本（用于 full 模式）
- * - 工作记忆提取与合并（压缩后恢复上下文）
- */
-/**
- * 文件输出记录
- */
-export interface FileArtifact {
-    path: string;
-    action: 'created' | 'modified' | 'deleted';
-    description: string;
-}
-/**
- * 工作记忆快照
- */
-export interface WorkingMemorySnapshot {
-    lastUpdated: string;
-    artifacts: FileArtifact[];
-    currentTask?: {
-        description: string;
-        status: 'in_progress' | 'blocked' | 'reviewing' | 'completed';
-        progress: number;
-    };
-    activeProblems: Array<{
-        problem: string;
-        approach?: string;
-    }>;
-    nextActions: string[];
-}
-/**
- * 获取历史目录路径
- */
-export declare function getHistoryDir(focusPath: string): string;
-/**
- * 从 CURRENT_FOCUS.md 提取版本号
- * 支持整数和小数版本（如 v1, v1.1, v1.2）
- */
-export declare function extractVersion(content: string): string;
-/**
- * 从 CURRENT_FOCUS.md 提取更新日期
- */
-export declare function extractDate(content: string): string;
-/**
- * 备份当前版本到历史目录
- *
- * @param focusPath CURRENT_FOCUS.md 的完整路径
- * @param content 当前内容
- * @returns 备份文件路径，失败返回 null
- */
-export declare function backupToHistory(focusPath: string, content: string): string | null;
-/**
- * 清理过期历史版本
- *
- * @param focusPath CURRENT_FOCUS.md 的完整路径
- * @param maxFiles 最大保留数量
- */
-export declare function cleanupHistory(focusPath: string, maxFiles?: number): void;
-/**
- * 获取历史版本列表
- *
- * @param focusPath CURRENT_FOCUS.md 的完整路径
- * @param count 获取数量
- * @returns 历史版本内容数组（按时间倒序）
- */
-export declare function getHistoryVersions(focusPath: string, count?: number): string[];
-/**
- * 压缩 CURRENT_FOCUS.md
- *
- * @param focusPath CURRENT_FOCUS.md 的完整路径
- * @param newContent 新内容
- * @returns 压缩后的信息
- */
-export declare function compressFocus(focusPath: string, newContent: string): {
-    backupPath: string | null;
-    cleanedCount: number;
-};
-/**
- * 智能摘要提取
- *
- * 优先提取关键章节，确保不丢失重要信息
- * 对于非结构化内容，回退到简单的行截取
- *
- * @param content CURRENT_FOCUS.md 内容
- * @param maxLines 最大行数
- */
-export declare function extractSummary(content: string, maxLines?: number): string;
-/**
- * 从会话消息中提取工作记忆
- *
- * @param messages 会话消息数组（OpenClaw 格式）
- * @param workspaceDir 工作区目录（用于生成相对路径）
- * @returns 提取的工作记忆快照
- */
-export declare function extractWorkingMemory(messages: Array<{
-    role?: string;
-    content?: string | unknown[];
-}>, workspaceDir?: string): WorkingMemorySnapshot;
-/**
- * 解析 CURRENT_FOCUS.md 中的 Working Memory 章节
- */
-export declare function parseWorkingMemorySection(content: string): WorkingMemorySnapshot | null;
-/**
- * 将工作记忆合并到 CURRENT_FOCUS.md 内容中
- *
- * @param content 原始内容
- * @param snapshot 工作记忆快照
- * @returns 合并后的内容
- */
-export declare function mergeWorkingMemory(content: string, snapshot: WorkingMemorySnapshot): string;
-/**
- * 生成工作记忆注入字符串（用于 prompt 注入）
- */
-export declare function workingMemoryToInjection(snapshot: WorkingMemorySnapshot | null): string;
-/**
- * 压缩配置接口
- */
-interface CompressionConfig {
-    lineThreshold: number;
-    sizeThreshold: number;
-    intervalMs: number;
-    keepCompletedTasks: number;
-    maxWorkingMemoryArtifacts: number;
-}
-/**
- * 提取已完成任务作为里程碑
- */
-export declare function extractMilestones(content: string): {
-    completedTasks: string[];
-    fileArtifacts: string[];
-};
-/**
- * 归档里程碑到 daily memory 文件
- */
-export declare function archiveMilestonesToDaily(workspaceDir: string, milestones: {
-    completedTasks: string[];
-    fileArtifacts: string[];
-}, version: string): string | null;
-/**
- * 清理过期信息和验证文件引用
- */
-export declare function cleanupStaleInfo(content: string, workspaceDir?: string, config?: CompressionConfig): string;
-/**
- * 自动压缩 CURRENT_FOCUS.md
- *
- * @param focusPath CURRENT_FOCUS.md 的完整路径
- * @param workspaceDir 工作区目录（可选，用于验证文件引用）
- * @param stateDir state 目录路径（可选，用于频率限制）
- * @returns 压缩结果信息，如果不需要压缩则返回 null
- */
-export declare function autoCompressFocus(focusPath: string, workspaceDir?: string, stateDir?: string): {
-    compressed: boolean;
-    oldLines: number;
-    newLines: number;
-    milestonesArchived: boolean;
-    backupPath: string | null;
-    reason: string;
-};
-/**
- * 检查是否需要自动压缩
- */
-export declare function needsAutoCompression(focusPath: string, stateDir?: string): boolean;
-/**
- * 验证 CURRENT_FOCUS.md 格式
- *
- * 仅校验会导致程序崩溃的核心问题，不过度校验
- *
- * @param content 文件内容
- * @returns 验证结果
- */
-export declare function validateCurrentFocus(content: string): {
-    valid: boolean;
-    errors: string[];
-    warnings: string[];
-};
-/**
- * 从模板恢复 CURRENT_FOCUS.md
- *
- * @param focusPath CURRENT_FOCUS.md 路径
- * @param extensionRoot 插件根目录
- * @returns 恢复是否成功
- */
-export declare function recoverFromTemplate(focusPath: string, extensionRoot: string): {
-    success: boolean;
-    error?: string;
-    templatePath?: string;
-};
-/**
- * 安全读取 CURRENT_FOCUS.md（自动验证 + 恢复）
- *
- * 仅在文件为空或损坏时才恢复，其他情况正常使用
- *
- * @param focusPath CURRENT_FOCUS.md 路径
- * @param extensionRoot 插件根目录
- * @param logger 日志记录器
- * @returns 文件内容和恢复状态
- */
-export declare function safeReadCurrentFocus(focusPath: string, extensionRoot: string, logger?: {
-    warn?: (msg: string) => void;
-    info?: (msg: string) => void;
-}): {
-    content: string;
-    recovered: boolean;
-    validationErrors: string[];
-};
-export {};