@hmharness/evolution 0.14.21 → 0.14.23

package/dist/cloud-finetune.d.ts

@@ -0,0 +1,126 @@
+import type { DpoPair } from './reward-model.ts';
+/** A fine-tunable model + how its jobs are priced. Prices change - the
+ * caller renders the estimate, the catalog only carries what we verified. */
+export interface FineTuneModelInfo {
+    id: string;
+    dpo: boolean;
+    note: string;
+}
+/** Models verified as fine-tunable (guide + live probe 2026-09-25: bare
+ * glm-4-air 404s "微调模型不存在", glm-4-flash passes model validation). */
+export declare const FINE_TUNE_CATALOG: FineTuneModelInfo[];
+export declare const DEFAULT_FINE_TUNE_MODEL = "glm-4-flash";
+/**
+ * Model auto-selection (user direction 2026-09-25: novices must never pick
+ * a fine-tune base). Candidates: the user's MAIN model first - if the API
+ * rejects it (live probe 2026-09-25: glm-5.3 answers "微调功能未开放") the
+ * ladder silently falls to the next documented fine-tunable base. The probe
+ * POSTs {model, training_file:"file-probe-invalid"} - model validation runs
+ * BEFORE file binding, so the request always fails without creating
+ * anything, and the error text tells us whether the model is usable.
+ */
+export declare function fineTuneModelLadder(mainModel: string): string[];
+/** Zero-side-effect model probe (the request can never create a job - the
+ * training_file id is invalid on purpose). "model rejected" vs "reached
+ * file validation" is distinguishable in the error text. */
+export declare function probeFineTuneModel(opts: {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    usable: boolean;
+    reason?: string;
+}>;
+/** Walk the ladder, return the first usable model plus why earlier ones
+ * were skipped (surfaced as one Chinese line - the backend adapts, the
+ * user reads, never chooses). */
+export declare function pickFineTuneModel(opts: {
+    apiKey: string;
+    baseUrl: string;
+    mainModel: string;
+    log?: (line: string) => void;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+/**
+ * Fine-tuning does not live on the coding endpoint: config.json points the
+ * chat route at /api/coding/paas/v4, but the fine_tuning/file APIs sit on
+ * /api/paas/v4. Strip the coding segment so the user's existing glm provider
+ * entry works unchanged (zero new configuration).
+ */
+export declare function normalizeFineTuneBase(baseUrl: string): string;
+/** Serialize pairs into the provider DPO JSONL row format (pure). Accepts
+ * the slim {prompt,chosen,rejected} rows the CLI persists - provenance
+ * fields never leave the machine. */
+export declare function toDpoJsonl(pairs: Array<Pick<DpoPair, 'prompt' | 'chosen' | 'rejected'>>): string;
+/** Rough token estimate for a cost preview before upload (chars/4 heuristic;
+ * the upload response returns exact per-tokenizer stats which the UI shows
+ * alongside - this is only the pre-flight number). */
+export declare function estimateTokens(jsonl: string): number;
+/** Training cost = tokens × epochs × unit price. Pure math, price supplied
+ * by the caller (it changes; we never bake it in as truth). */
+export declare function estimateTrainingCost(tokens: number, epochs: number, pricePerKTokens: number): number;
+export interface UploadedFile {
+    id: string;
+    bytes: number;
+    samples: number;
+    /** tokens counted by the provider tokenizer (max of the reported stats). */
+    tokens: number;
+}
+/** Upload a training/validation JSONL (free operation, verified live). */
+export declare function uploadFineTuneFile(opts: {
+    apiKey: string;
+    baseUrl: string;
+    filename: string;
+    jsonl: string;
+    fetchImpl?: typeof fetch;
+}): Promise<UploadedFile>;
+export interface FineTuneJob {
+    id: string;
+    model?: string;
+    status?: string;
+    fine_tuned_model?: string;
+    training_file?: string;
+    created_at?: number;
+    [k: string]: unknown;
+}
+/** Create a fine-tuning job (PAID - callers must gate behind explicit
+ * submit consent; uploads alone are free). */
+export declare function createFineTuneJob(opts: {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    trainingFile: string;
+    validationFile?: string;
+    suffix?: string;
+    hyperparameters?: {
+        batch_size?: number | 'auto';
+        learning_rate_multiplier?: number | 'auto';
+        n_epochs?: number | 'auto';
+    };
+    fetchImpl?: typeof fetch;
+}): Promise<FineTuneJob>;
+export declare function listFineTuneJobs(opts: {
+    apiKey: string;
+    baseUrl: string;
+    limit?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<FineTuneJob[]>;
+export declare function retrieveFineTuneJob(opts: {
+    apiKey: string;
+    baseUrl: string;
+    jobId: string;
+    fetchImpl?: typeof fetch;
+}): Promise<FineTuneJob>;
+export declare function cancelFineTuneJob(opts: {
+    apiKey: string;
+    baseUrl: string;
+    jobId: string;
+    fetchImpl?: typeof fetch;
+}): Promise<FineTuneJob>;
+/** Append-only record of jobs this machine submitted (audit trail: what was
+ * trained, on which file, when - survives provider console churn). */
+export declare function recordFineTuneJob(home: string, job: FineTuneJob, extra?: Record<string, unknown>): Promise<void>;
+export declare function readLocalFineTuneJobs(home: string): Promise<Array<FineTuneJob & {
+    time: string;
+}>>;

package/dist/cloud-finetune.js

@@ -0,0 +1,200 @@
+/**
+ * Cloud fine-tuning client (2026-09-25, closes the auto-finetune loop).
+ *
+ * Direction (user, 2026-09-24): users configure ONE api key, the backend
+ * adapts everything else; local-GPU training was a developer experiment.
+ * This module submits the accumulated DPO preference pairs to the provider's
+ * fine-tuning API so "gets smarter as you use it" needs no local stack.
+ *
+ * Endpoint surface verified live 2026-09-25 against open.bigmodel.cn with a
+ * real key (read-only probes + one 85-byte purpose=fine-tune upload):
+ *   POST /api/paas/v4/files                     multipart file + purpose=fine-tune
+ *   POST /api/paas/v4/fine_tuning/jobs          {model, training_file, ...}
+ *   GET  /api/paas/v4/fine_tuning/jobs          list
+ *   GET  /api/paas/v4/fine_tuning/jobs/{id}     retrieve
+ *   POST /api/paas/v4/fine_tuning/jobs/{id}/cancel
+ *   GET  /api/paas/v4/fine_tuning/jobs/{id}/events
+ * Cross-checked field names against zhipuai SDK 2.1.5 source
+ * (api_resource/fine_tuning/jobs/jobs.py). The DPO row format follows the
+ * official guide: {"input":{messages,tools,parallel_tool_calls},
+ * "preferred_output":[...],"non_preferred_output":[...]}.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Models verified as fine-tunable (guide + live probe 2026-09-25: bare
+ * glm-4-air 404s "微调模型不存在", glm-4-flash passes model validation). */
+export const FINE_TUNE_CATALOG = [
+    { id: 'glm-4-flash', dpo: true, note: '最便宜，LoRA 需开发者 Pro 权益' },
+    { id: 'glm-4.5-air', dpo: false, note: '全参微调，对所有用户开放（SFT）' },
+    { id: 'glm-4-air-250414', dpo: true, note: '全参微调' },
+    { id: 'glm-4-air-x', dpo: true, note: '全参微调' },
+];
+export const DEFAULT_FINE_TUNE_MODEL = 'glm-4-flash';
+/**
+ * Model auto-selection (user direction 2026-09-25: novices must never pick
+ * a fine-tune base). Candidates: the user's MAIN model first - if the API
+ * rejects it (live probe 2026-09-25: glm-5.3 answers "微调功能未开放") the
+ * ladder silently falls to the next documented fine-tunable base. The probe
+ * POSTs {model, training_file:"file-probe-invalid"} - model validation runs
+ * BEFORE file binding, so the request always fails without creating
+ * anything, and the error text tells us whether the model is usable.
+ */
+export function fineTuneModelLadder(mainModel) {
+    const ladder = [mainModel, DEFAULT_FINE_TUNE_MODEL, 'glm-4.5-air'];
+    return [...new Set(ladder.filter(Boolean))];
+}
+/** Zero-side-effect model probe (the request can never create a job - the
+ * training_file id is invalid on purpose). "model rejected" vs "reached
+ * file validation" is distinguishable in the error text. */
+export async function probeFineTuneModel(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + '/fine_tuning/jobs';
+    const res = await (opts.fetchImpl ?? fetch)(url, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${opts.apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: opts.model, training_file: 'file-probe-invalid' }),
+    });
+    const text = await res.text();
+    if (res.ok)
+        return { usable: true }; // unreachable in practice; harmless
+    const rejected = /微调模型不存在|微调功能未开放|无权限|not found/i.test(text);
+    return { usable: !rejected, reason: rejected ? text.slice(0, 160) : undefined };
+}
+/** Walk the ladder, return the first usable model plus why earlier ones
+ * were skipped (surfaced as one Chinese line - the backend adapts, the
+ * user reads, never chooses). */
+export async function pickFineTuneModel(opts) {
+    for (const m of fineTuneModelLadder(opts.mainModel)) {
+        const r = await probeFineTuneModel({ apiKey: opts.apiKey, baseUrl: opts.baseUrl, model: m, fetchImpl: opts.fetchImpl });
+        if (r.usable)
+            return m;
+        opts.log?.(`微调候选 ${m} 不可用（${(r.reason ?? '').replace(/^.*"message":"([^"]*)".*$/, '$1').slice(0, 60) || 'API 拒绝'}），自动改试下一个`);
+    }
+    throw new Error('所有微调候选模型均不可用——请在智谱控制台确认微调权限（可能需联系客服开放），或用 --model= 指定其他可微调模型');
+}
+/**
+ * Fine-tuning does not live on the coding endpoint: config.json points the
+ * chat route at /api/coding/paas/v4, but the fine_tuning/file APIs sit on
+ * /api/paas/v4. Strip the coding segment so the user's existing glm provider
+ * entry works unchanged (zero new configuration).
+ */
+export function normalizeFineTuneBase(baseUrl) {
+    let u = baseUrl.trim().replace(/\/+$/, '');
+    u = u.replace(/\/coding\/paas\/v4$/, '/paas/v4');
+    if (!/\/api\/paas\/v4$/.test(u)) {
+        const m = u.match(/^(https?:\/\/[^/]+)/);
+        if (!m)
+            throw new Error('baseUrl 需以 http(s):// 开头: ' + baseUrl);
+        u = m[1] + '/api/paas/v4';
+    }
+    return u;
+}
+/** Serialize pairs into the provider DPO JSONL row format (pure). Accepts
+ * the slim {prompt,chosen,rejected} rows the CLI persists - provenance
+ * fields never leave the machine. */
+export function toDpoJsonl(pairs) {
+    const lines = [];
+    for (const p of pairs) {
+        if (!p.prompt.trim() || !p.chosen.trim() || !p.rejected.trim())
+            continue; // quality gate mirrors rl-governance
+        const row = {
+            input: {
+                messages: [{ role: 'user', content: p.prompt }],
+                tools: [],
+                parallel_tool_calls: false,
+            },
+            preferred_output: [{ role: 'assistant', content: p.chosen }],
+            non_preferred_output: [{ role: 'assistant', content: p.rejected }],
+        };
+        lines.push(JSON.stringify(row));
+    }
+    return lines.join('\n') + (lines.length ? '\n' : '');
+}
+/** Rough token estimate for a cost preview before upload (chars/4 heuristic;
+ * the upload response returns exact per-tokenizer stats which the UI shows
+ * alongside - this is only the pre-flight number). */
+export function estimateTokens(jsonl) {
+    return Math.ceil(jsonl.length / 4);
+}
+/** Training cost = tokens × epochs × unit price. Pure math, price supplied
+ * by the caller (it changes; we never bake it in as truth). */
+export function estimateTrainingCost(tokens, epochs, pricePerKTokens) {
+    return Math.round(((tokens / 1000) * epochs * pricePerKTokens) * 100) / 100;
+}
+async function zhipuFetch(url, apiKey, init, fetchImpl) {
+    const res = await fetchImpl(url, {
+        ...init,
+        headers: { Authorization: `Bearer ${apiKey}`, ...init.headers },
+    });
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    if (!res.ok) {
+        const err = body;
+        throw new Error(`HTTP ${res.status}: ${err?.error?.message ?? String(body).slice(0, 200)}`);
+    }
+    return body;
+}
+/** Upload a training/validation JSONL (free operation, verified live). */
+export async function uploadFineTuneFile(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + '/files';
+    const form = new FormData();
+    form.append('purpose', 'fine-tune');
+    form.append('file', new Blob([opts.jsonl], { type: 'application/jsonl' }), opts.filename);
+    const body = await zhipuFetch(url, opts.apiKey, { method: 'POST', body: form }, opts.fetchImpl ?? fetch);
+    const o = body;
+    const tokens = Math.max(0, ...(o.text_stats ?? []).map((t) => t.tokens ?? 0));
+    return { id: o.id, bytes: o.bytes, samples: o.samples ?? 0, tokens };
+}
+/** Create a fine-tuning job (PAID - callers must gate behind explicit
+ * submit consent; uploads alone are free). */
+export async function createFineTuneJob(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + '/fine_tuning/jobs';
+    const payload = { model: opts.model, training_file: opts.trainingFile };
+    if (opts.validationFile)
+        payload.validation_file = opts.validationFile;
+    if (opts.suffix)
+        payload.suffix = opts.suffix;
+    if (opts.hyperparameters)
+        payload.hyperparameters = opts.hyperparameters;
+    return (await zhipuFetch(url, opts.apiKey, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    }, opts.fetchImpl ?? fetch));
+}
+export async function listFineTuneJobs(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + `/fine_tuning/jobs?limit=${opts.limit ?? 10}`;
+    const body = await zhipuFetch(url, opts.apiKey, { method: 'GET' }, opts.fetchImpl ?? fetch);
+    return (body.data ?? []);
+}
+export async function retrieveFineTuneJob(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + `/fine_tuning/jobs/${opts.jobId}`;
+    return (await zhipuFetch(url, opts.apiKey, { method: 'GET' }, opts.fetchImpl ?? fetch));
+}
+export async function cancelFineTuneJob(opts) {
+    const url = normalizeFineTuneBase(opts.baseUrl) + `/fine_tuning/jobs/${opts.jobId}/cancel`;
+    return (await zhipuFetch(url, opts.apiKey, { method: 'POST' }, opts.fetchImpl ?? fetch));
+}
+/* ---------------- local job ledger ---------------- */
+/** Append-only record of jobs this machine submitted (audit trail: what was
+ * trained, on which file, when - survives provider console churn). */
+export async function recordFineTuneJob(home, job, extra = {}) {
+    const dir = join(home, 'evolution');
+    await mkdir(dir, { recursive: true });
+    const row = { time: new Date().toISOString(), ...job, ...extra };
+    await appendFile(join(dir, 'finetune-jobs.jsonl'), JSON.stringify(row) + '\n', 'utf8');
+}
+export async function readLocalFineTuneJobs(home) {
+    try {
+        const text = await readFile(join(home, 'evolution', 'finetune-jobs.jsonl'), 'utf8');
+        return text.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/index.d.ts

@@ -21,3 +21,6 @@ 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';
+export * from './cloud-finetune.ts';

package/dist/index.js

@@ -21,3 +21,6 @@ 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";
+export * from "./cloud-finetune.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.23",
   "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",