@hmharness/evolution 0.14.21 → 0.14.22

package/dist/index.d.ts

@@ -21,3 +21,5 @@ export * from './external.ts';
 export * from './knowledge-graph.ts';
 export * from './router-evolution.ts';
 export * from './context-evolution.ts';
+export * from './rl-governance.ts';
+export * from './policy-optimizer.ts';

package/dist/index.js

@@ -21,3 +21,5 @@ export * from "./external.js";
 export * from "./knowledge-graph.js";
 export * from "./router-evolution.js";
 export * from "./context-evolution.js";
+export * from "./rl-governance.js";
+export * from "./policy-optimizer.js";

package/dist/policy-optimizer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @hmharness/evolution - Policy Optimization (P3-02)
+ *
+ * The audit: "把 prompt、skill、tool policy、routing、workflow 全部视为可优化 policy"
+ *
+ * Provides a unified optimization framework where every configurable aspect
+ * of the harness (prompts, skills, tool policies, routing, workflows) is
+ * a first-class "Policy" that can be experimented on and improved.
+ */
+export type PolicyKind = 'prompt' | 'skill' | 'tool-policy' | 'routing' | 'workflow' | 'context' | 'model';
+export interface OptimizablePolicy {
+    id: string;
+    kind: PolicyKind;
+    name: string;
+    /** current value/configuration */
+    value: unknown;
+    /** human-readable description of what this policy controls */
+    description: string;
+    /** how changes to this policy are tested */
+    evaluationMethod: string;
+}
+export interface PolicyExperiment {
+    id: string;
+    policy: OptimizablePolicy;
+    /** proposed new value */
+    challenger: unknown;
+    /** A/B arm results */
+    controlScores: number[];
+    treatmentScores: number[];
+    status: 'proposed' | 'running' | 'promoted' | 'rolled-back' | 'rejected';
+    createdAt: string;
+}
+export interface PolicyOptimizationReport {
+    totalPolicies: number;
+    activeExperiments: number;
+    promotedCount: number;
+    rolledBackCount: number;
+    byKind: Record<PolicyKind, number>;
+}
+/**
+ * The policy registry - all optimizable policies in one place.
+ */
+export declare class PolicyOptimizer {
+    private policies;
+    private experiments;
+    registerPolicy(policy: OptimizablePolicy): {
+        ok: boolean;
+        reason?: string;
+    };
+    getPolicy(id: string): OptimizablePolicy | undefined;
+    listPolicies(kind?: PolicyKind): OptimizablePolicy[];
+    /**
+     * Propose an experiment: change a policy's value.
+     */
+    proposeExperiment(policyId: string, challenger: unknown): {
+        ok: boolean;
+        experimentId?: string;
+        reason?: string;
+    };
+    /**
+     * Record a result for an experiment arm.
+     */
+    recordResult(experimentId: string, arm: 'control' | 'treatment', score: number): boolean;
+    /**
+     * Evaluate an experiment (simple mean comparison).
+     * Pure logic within the method.
+     */
+    evaluateExperiment(experimentId: string): {
+        decision: string;
+        reason: string;
+    } | undefined;
+    /**
+     * Generate a summary report.
+     */
+    report(): PolicyOptimizationReport;
+}

package/dist/policy-optimizer.js

@@ -0,0 +1,101 @@
+/**
+ * @hmharness/evolution - Policy Optimization (P3-02)
+ *
+ * The audit: "把 prompt、skill、tool policy、routing、workflow 全部视为可优化 policy"
+ *
+ * Provides a unified optimization framework where every configurable aspect
+ * of the harness (prompts, skills, tool policies, routing, workflows) is
+ * a first-class "Policy" that can be experimented on and improved.
+ */
+/**
+ * The policy registry - all optimizable policies in one place.
+ */
+export class PolicyOptimizer {
+    policies = new Map();
+    experiments = new Map();
+    registerPolicy(policy) {
+        if (this.policies.has(policy.id))
+            return { ok: false, reason: `policy ${policy.id} already registered` };
+        this.policies.set(policy.id, policy);
+        return { ok: true };
+    }
+    getPolicy(id) {
+        return this.policies.get(id);
+    }
+    listPolicies(kind) {
+        const all = [...this.policies.values()];
+        return kind ? all.filter(p => p.kind === kind) : all;
+    }
+    /**
+     * Propose an experiment: change a policy's value.
+     */
+    proposeExperiment(policyId, challenger) {
+        const policy = this.policies.get(policyId);
+        if (!policy)
+            return { ok: false, reason: `policy ${policyId} not found` };
+        const expId = `exp-${Date.now().toString(36)}`;
+        this.experiments.set(expId, {
+            id: expId, policy, challenger,
+            controlScores: [], treatmentScores: [],
+            status: 'proposed', createdAt: new Date().toISOString(),
+        });
+        return { ok: true, experimentId: expId };
+    }
+    /**
+     * Record a result for an experiment arm.
+     */
+    recordResult(experimentId, arm, score) {
+        const exp = this.experiments.get(experimentId);
+        if (!exp)
+            return false;
+        if (arm === 'control')
+            exp.controlScores.push(score);
+        else
+            exp.treatmentScores.push(score);
+        exp.status = 'running';
+        return true;
+    }
+    /**
+     * Evaluate an experiment (simple mean comparison).
+     * Pure logic within the method.
+     */
+    evaluateExperiment(experimentId) {
+        const exp = this.experiments.get(experimentId);
+        if (!exp)
+            return undefined;
+        const minN = 10;
+        if (exp.controlScores.length < minN || exp.treatmentScores.length < minN) {
+            return { decision: 'continue', reason: `insufficient samples (ctrl ${exp.controlScores.length}/${minN}, trt ${exp.treatmentScores.length}/${minN})` };
+        }
+        const ctrlMean = exp.controlScores.reduce((a, b) => a + b, 0) / exp.controlScores.length;
+        const trtMean = exp.treatmentScores.reduce((a, b) => a + b, 0) / exp.treatmentScores.length;
+        const diff = trtMean - ctrlMean;
+        if (diff > 0.02) {
+            exp.status = 'promoted';
+            exp.policy.value = exp.challenger;
+            return { decision: 'promote', reason: `treatment +${diff.toFixed(3)}` };
+        }
+        if (diff < -0.02) {
+            exp.status = 'rolled-back';
+            return { decision: 'rollback', reason: `treatment ${diff.toFixed(3)}` };
+        }
+        return { decision: 'continue', reason: `diff ${diff.toFixed(3)} within noise` };
+    }
+    /**
+     * Generate a summary report.
+     */
+    report() {
+        const all = [...this.policies.values()];
+        const exps = [...this.experiments.values()];
+        const byKind = {};
+        for (const p of all)
+            byKind[p.kind] = (byKind[p.kind] ?? 0) + 1;
+        return {
+            totalPolicies: all.length,
+            activeExperiments: exps.filter(e => e.status === 'running').length,
+            promotedCount: exps.filter(e => e.status === 'promoted').length,
+            rolledBackCount: exps.filter(e => e.status === 'rolled-back').length,
+            byKind: byKind,
+        };
+    }
+}

package/dist/rl-governance.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @hmharness/evolution - RL Governance (P3-01 + P3-05)
+ *
+ * The audit: "只有 trajectory 数据经过过滤、去污染、去泄漏、holdout 后再考虑"
+ *
+ * Formalizes the governance pipeline that ALL training data must pass
+ * before entering model fine-tuning. This is the data quality gate.
+ */
+export type DecontaminationAction = 'pass' | 'quarantine' | 'reject';
+export interface TrajectoryRecord {
+    id: string;
+    taskId: string;
+    prompt: string;
+    output: string;
+    outcome: 'ok' | 'degraded' | 'timeout' | 'error';
+    tokens: number;
+    turns: number;
+    /** whether this trajectory came from an external task */
+    isExternal: boolean;
+    /** whether this trajectory is in the holdout set */
+    isHoldout: boolean;
+}
+export interface DecontaminationResult {
+    recordId: string;
+    action: DecontaminationAction;
+    reasons: string[];
+    checks: Array<{
+        name: string;
+        passed: boolean;
+        detail: string;
+    }>;
+}
+/** Types of leakage to check for */
+export type LeakageType = 'holdout-in-train' | 'self-eval' | 'prompt-duplication' | 'external-in-train';
+export interface LeakageCheck {
+    type: LeakageType;
+    detected: boolean;
+    details: string[];
+}
+/**
+ * Filter trajectories by quality before training.
+ * Pure - testable.
+ */
+export declare function filterForTraining(records: TrajectoryRecord[]): {
+    eligible: TrajectoryRecord[];
+    rejected: Array<{
+        record: TrajectoryRecord;
+        reason: string;
+    }>;
+};
+/**
+ * Detect leakage between training and holdout sets.
+ * Pure - testable.
+ */
+export declare function detectLeakage(trainingRecords: TrajectoryRecord[], holdoutRecords: TrajectoryRecord[]): LeakageCheck[];
+/**
+ * Full decontamination pipeline: run all checks and decide action.
+ * Pure - testable.
+ */
+export declare function decontaminate(record: TrajectoryRecord, holdoutPrompts: string[]): DecontaminationResult;
+/**
+ * Generate an RL readiness report.
+ * Pure - testable.
+ */
+export declare function rlReadinessReport(params: {
+    totalTrajectories: number;
+    eligibleForTraining: number;
+    holdoutSize: number;
+    leakageChecks: LeakageCheck[];
+}): {
+    ready: boolean;
+    score: number;
+    blockers: string[];
+    warnings: string[];
+};

package/dist/rl-governance.js

@@ -0,0 +1,136 @@
+/**
+ * @hmharness/evolution - RL Governance (P3-01 + P3-05)
+ *
+ * The audit: "只有 trajectory 数据经过过滤、去污染、去泄漏、holdout 后再考虑"
+ *
+ * Formalizes the governance pipeline that ALL training data must pass
+ * before entering model fine-tuning. This is the data quality gate.
+ */
+/**
+ * Filter trajectories by quality before training.
+ * Pure - testable.
+ */
+export function filterForTraining(records) {
+    const eligible = [];
+    const rejected = [];
+    for (const r of records) {
+        if (r.isHoldout) {
+            rejected.push({ record: r, reason: 'holdout record must never enter training' });
+            continue;
+        }
+        if (r.isExternal) {
+            rejected.push({ record: r, reason: 'external task must stay in holdout' });
+            continue;
+        }
+        if (!r.prompt.trim()) {
+            rejected.push({ record: r, reason: 'empty prompt' });
+            continue;
+        }
+        if (!r.output.trim()) {
+            rejected.push({ record: r, reason: 'empty output' });
+            continue;
+        }
+        if (r.outcome === 'error') {
+            rejected.push({ record: r, reason: 'error outcome not suitable for training' });
+            continue;
+        }
+        eligible.push(r);
+    }
+    return { eligible, rejected };
+}
+/**
+ * Detect leakage between training and holdout sets.
+ * Pure - testable.
+ */
+export function detectLeakage(trainingRecords, holdoutRecords) {
+    const checks = [];
+    // 1. holdout-in-train: any holdout record's prompt appears in training
+    const holdoutPrompts = new Set(holdoutRecords.map(r => r.prompt.trim().toLowerCase().slice(0, 100)));
+    const holdoutInTrain = trainingRecords.filter(r => holdoutPrompts.has(r.prompt.trim().toLowerCase().slice(0, 100)));
+    checks.push({
+        type: 'holdout-in-train',
+        detected: holdoutInTrain.length > 0,
+        details: holdoutInTrain.map(r => `training record ${r.id} matches holdout prompt`),
+    });
+    // 2. self-eval: check if evaluator score correlates suspiciously with self-report
+    const selfEval = trainingRecords.filter(r => r.outcome === 'ok' && r.turns <= 1 && r.tokens < 50);
+    checks.push({
+        type: 'self-eval',
+        detected: selfEval.length > 0 && trainingRecords.length > 0 && selfEval.length / trainingRecords.length > 0.8,
+        details: selfEval.length > 0 && selfEval.length / trainingRecords.length > 0.8
+            ? [`${selfEval.length}/${trainingRecords.length} records are trivially self-reported (1 turn, <50 tokens)`]
+            : [],
+    });
+    // 3. prompt-duplication within training set
+    const promptCounts = new Map();
+    for (const r of trainingRecords) {
+        const key = r.prompt.trim().toLowerCase().slice(0, 100);
+        promptCounts.set(key, (promptCounts.get(key) ?? 0) + 1);
+    }
+    const dupes = [...promptCounts.entries()].filter(([, n]) => n > 5);
+    checks.push({
+        type: 'prompt-duplication',
+        detected: dupes.length > 0,
+        details: dupes.map(([k, n]) => `prompt "${k.slice(0, 40)}..." appears ${n} times`),
+    });
+    // 4. external-in-train
+    const externalInTrain = trainingRecords.filter(r => r.isExternal);
+    checks.push({
+        type: 'external-in-train',
+        detected: externalInTrain.length > 0,
+        details: externalInTrain.map(r => `external record ${r.id} found in training set`),
+    });
+    return checks;
+}
+/**
+ * Full decontamination pipeline: run all checks and decide action.
+ * Pure - testable.
+ */
+export function decontaminate(record, holdoutPrompts) {
+    const checks = [];
+    const reasons = [];
+    // holdout check
+    const promptKey = record.prompt.trim().toLowerCase().slice(0, 100);
+    const inHoldout = holdoutPrompts.some(p => p.trim().toLowerCase().slice(0, 100) === promptKey);
+    checks.push({ name: 'holdout-overlap', passed: !inHoldout, detail: inHoldout ? 'prompt matches holdout' : 'clear' });
+    if (inHoldout)
+        reasons.push('record overlaps with holdout set');
+    // quality check
+    const qualityOk = record.prompt.trim().length > 0 && record.output.trim().length > 0;
+    checks.push({ name: 'quality', passed: qualityOk, detail: qualityOk ? 'non-empty' : 'empty prompt/output' });
+    if (!qualityOk)
+        reasons.push('empty prompt or output');
+    // outcome check
+    const outcomeOk = record.outcome !== 'error';
+    checks.push({ name: 'outcome', passed: outcomeOk, detail: `outcome=${record.outcome}` });
+    if (!outcomeOk)
+        reasons.push('error outcome');
+    // external check
+    const externalOk = !record.isExternal;
+    checks.push({ name: 'external', passed: externalOk, detail: record.isExternal ? 'is external' : 'internal' });
+    if (!externalOk)
+        reasons.push('external record must stay in holdout');
+    const action = reasons.length === 0 ? 'pass' : reasons.some(r => r.includes('holdout') || r.includes('external')) ? 'reject' : 'quarantine';
+    return { recordId: record.id, action, reasons, checks };
+}
+/**
+ * Generate an RL readiness report.
+ * Pure - testable.
+ */
+export function rlReadinessReport(params) {
+    const blockers = [];
+    const warnings = [];
+    if (params.eligibleForTraining < 100)
+        blockers.push(`only ${params.eligibleForTraining} eligible trajectories (need >=100)`);
+    if (params.holdoutSize < 10)
+        blockers.push(`holdout too small (${params.holdoutSize}, need >=10)`);
+    const criticalLeakage = params.leakageChecks.filter(c => c.detected && (c.type === 'holdout-in-train' || c.type === 'external-in-train'));
+    if (criticalLeakage.length > 0)
+        blockers.push(`critical leakage detected: ${criticalLeakage.map(c => c.type).join(', ')}`);
+    for (const c of params.leakageChecks) {
+        if (c.detected && !blockers.some(b => b.includes(c.type)))
+            warnings.push(`${c.type}: ${c.details.join('; ')}`);
+    }
+    const score = Math.max(0, 100 - blockers.length * 30 - warnings.length * 10);
+    return { ready: blockers.length === 0, score, blockers, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.14.21",
+  "version": "0.14.22",
   "description": "hmharness evolution subsystem: persistent memory, insight capture, skill library, and the bench that gives evolution its fitness signal. First-class kernel citizen, not a plugin.",
   "type": "module",
   "main": "dist/index.js",