@hmharness/evolution 0.14.19 → 0.14.21

package/dist/context-evolution.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @hmharness/evolution - Context Ranker Evolution (P2-04)
+ *
+ * The audit called for: "让 context policy 进入 Evolution"
+ *
+ * Makes the context ranker's weights evolvable: they can be registered
+ * as candidates, A/B tested, and promoted/rolled back via the same
+ * evolution machinery that handles skills and routing policies.
+ *
+ * The existing ContextRanker uses fixed RANK_WEIGHTS; this module wraps
+ * those weights in an experimentable policy.
+ */
+export interface ContextWeights {
+    /** relevance to current task */
+    relevance: number;
+    /** recency (newer = higher) */
+    recency: number;
+    /** frequency of access */
+    frequency: number;
+    /** token cost penalty (lower cost = higher rank) */
+    costEfficiency: number;
+    /** source trust (insights > generic) */
+    source: number;
+}
+export declare const DEFAULT_CONTEXT_WEIGHTS: ContextWeights;
+export interface ContextPolicy {
+    id: string;
+    name: string;
+    weights: ContextWeights;
+    description: string;
+}
+export interface ContextEvolutionExperiment {
+    id: string;
+    challenger: ContextPolicy;
+    incumbent: ContextPolicy;
+    /** A/B results */
+    controlScores: number[];
+    treatmentScores: number[];
+    status: 'running' | 'promoted' | 'rolled-back' | 'inconclusive';
+    startedAt: string;
+}
+/**
+ * Validate that context weights are reasonable (sum to ~1, all non-negative).
+ * Pure - testable.
+ */
+export declare function validateWeights(w: ContextWeights): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Score a context item given weights and features.
+ * Pure - testable.
+ */
+export declare function scoreContextItem(weights: ContextWeights, features: {
+    relevance: number;
+    recency: number;
+    frequency: number;
+    tokenCost: number;
+    sourceTrust: number;
+}): number;
+/**
+ * Rank context items by score (highest first).
+ * Pure - testable.
+ */
+export declare function rankItems(weights: ContextWeights, items: Array<{
+    id: string;
+    features: Parameters<typeof scoreContextItem>[1];
+}>): Array<{
+    id: string;
+    score: number;
+}>;
+/**
+ * Evaluate a context evolution experiment.
+ * Simple paired comparison of mean scores.
+ * Pure - testable.
+ */
+export declare function evaluateContextExperiment(exp: ContextEvolutionExperiment): {
+    decision: 'continue' | 'promote' | 'rollback';
+    reason: string;
+};
+/**
+ * Registry for context policies (similar to RoutingPolicyRegistry).
+ */
+export declare class ContextPolicyRegistry {
+    private policies;
+    private activeId;
+    register(policy: ContextPolicy): {
+        ok: boolean;
+        reason?: string;
+    };
+    get(id: string): ContextPolicy | undefined;
+    list(): ContextPolicy[];
+    getActive(): ContextPolicy | undefined;
+    get activePolicyId(): string;
+    promote(id: string): boolean;
+    rollback(): void;
+}

package/dist/context-evolution.js

@@ -0,0 +1,105 @@
+/**
+ * @hmharness/evolution - Context Ranker Evolution (P2-04)
+ *
+ * The audit called for: "让 context policy 进入 Evolution"
+ *
+ * Makes the context ranker's weights evolvable: they can be registered
+ * as candidates, A/B tested, and promoted/rolled back via the same
+ * evolution machinery that handles skills and routing policies.
+ *
+ * The existing ContextRanker uses fixed RANK_WEIGHTS; this module wraps
+ * those weights in an experimentable policy.
+ */
+export const DEFAULT_CONTEXT_WEIGHTS = {
+    relevance: 0.40,
+    recency: 0.20,
+    frequency: 0.15,
+    costEfficiency: 0.10,
+    source: 0.15,
+};
+/**
+ * Validate that context weights are reasonable (sum to ~1, all non-negative).
+ * Pure - testable.
+ */
+export function validateWeights(w) {
+    const errors = [];
+    const entries = Object.entries(w);
+    for (const [k, v] of entries) {
+        if (v < 0)
+            errors.push(`${k} must be >= 0, got ${v}`);
+        if (v > 1)
+            errors.push(`${k} must be <= 1, got ${v}`);
+    }
+    const sum = entries.reduce((a, [, v]) => a + v, 0);
+    if (Math.abs(sum - 1) > 0.05)
+        errors.push(`weights sum to ${sum.toFixed(2)}, expected ~1.0`);
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Score a context item given weights and features.
+ * Pure - testable.
+ */
+export function scoreContextItem(weights, features) {
+    const costEff = features.tokenCost > 0 ? 1 / (1 + features.tokenCost / 1000) : 1;
+    return (weights.relevance * features.relevance +
+        weights.recency * features.recency +
+        weights.frequency * features.frequency +
+        weights.costEfficiency * costEff +
+        weights.source * features.sourceTrust);
+}
+/**
+ * Rank context items by score (highest first).
+ * Pure - testable.
+ */
+export function rankItems(weights, items) {
+    return items
+        .map(item => ({ id: item.id, score: scoreContextItem(weights, item.features) }))
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Evaluate a context evolution experiment.
+ * Simple paired comparison of mean scores.
+ * Pure - testable.
+ */
+export function evaluateContextExperiment(exp) {
+    const minN = 10;
+    if (exp.controlScores.length < minN || exp.treatmentScores.length < minN) {
+        return { decision: 'continue', reason: `insufficient samples (control ${exp.controlScores.length}/${minN}, treatment ${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;
+    // promote if challenger is meaningfully better
+    if (diff > 0.02)
+        return { decision: 'promote', reason: `treatment ${trtMean.toFixed(3)} vs control ${ctrlMean.toFixed(3)} (+${diff.toFixed(3)})` };
+    if (diff < -0.02)
+        return { decision: 'rollback', reason: `treatment ${trtMean.toFixed(3)} vs control ${ctrlMean.toFixed(3)} (${diff.toFixed(3)})` };
+    return { decision: 'continue', reason: `diff ${diff.toFixed(3)} within noise` };
+}
+/**
+ * Registry for context policies (similar to RoutingPolicyRegistry).
+ */
+export class ContextPolicyRegistry {
+    policies = new Map();
+    activeId = 'default';
+    register(policy) {
+        const v = validateWeights(policy.weights);
+        if (!v.valid)
+            return { ok: false, reason: v.errors.join('; ') };
+        if (this.policies.has(policy.id))
+            return { ok: false, reason: `policy ${policy.id} already registered` };
+        this.policies.set(policy.id, policy);
+        return { ok: true };
+    }
+    get(id) { return this.policies.get(id); }
+    list() { return [...this.policies.values()]; }
+    getActive() { return this.policies.get(this.activeId); }
+    get activePolicyId() { return this.activeId; }
+    promote(id) {
+        if (!this.policies.has(id))
+            return false;
+        this.activeId = id;
+        return true;
+    }
+    rollback() { this.activeId = 'default'; }
+}

package/dist/index.d.ts

@@ -19,3 +19,5 @@ export * from './knowledge.ts';
 export * from './radar.ts';
 export * from './external.ts';
 export * from './knowledge-graph.ts';
+export * from './router-evolution.ts';
+export * from './context-evolution.ts';

package/dist/index.js

@@ -19,3 +19,5 @@ export * from "./knowledge.js";
 export * from "./radar.js";
 export * from "./external.js";
 export * from "./knowledge-graph.js";
+export * from "./router-evolution.js";
+export * from "./context-evolution.js";

package/dist/router-evolution.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @hmharness/evolution - Router Evolution (P2-05)
+ *
+ * The audit called for: "让 model routing 本身成为可实验、可回滚策略"
+ *
+ * Makes routing decisions experimentable: a routing policy can be registered
+ * as a candidate, A/B tested against the current policy, and promoted or
+ * rolled back based on SPRT results.
+ */
+import type { RouteHistoryEntry } from '@hmharness/kernel';
+export interface RoutingPolicy {
+    id: string;
+    name: string;
+    description: string;
+    /** the routing function */
+    decide: (history: RouteHistoryEntry[], taskType: string, candidates: string[]) => string;
+}
+export interface RoutingExperiment {
+    id: string;
+    /** the challenger policy */
+    challenger: RoutingPolicy;
+    /** incumbent policy (or 'default' for current behavior) */
+    incumbent: string;
+    /** control arm results */
+    controlSuccesses: number;
+    controlTotal: number;
+    /** treatment arm results */
+    treatmentSuccesses: number;
+    treatmentTotal: number;
+    status: 'running' | 'promoted' | 'rolled-back' | 'inconclusive';
+    startedAt: string;
+}
+/**
+ * Evaluate a routing experiment using simple SPRT logic.
+ * Pure - testable.
+ */
+export declare function evaluateExperiment(exp: RoutingExperiment): {
+    decision: 'continue' | 'promote' | 'rollback';
+    reason: string;
+};
+/**
+ * The routing policy registry - manages candidate and active policies.
+ */
+export declare class RoutingPolicyRegistry {
+    private policies;
+    private activePolicyId;
+    register(policy: RoutingPolicy): {
+        ok: boolean;
+        reason?: string;
+    };
+    get(id: string): RoutingPolicy | undefined;
+    list(): RoutingPolicy[];
+    /** Get the currently active policy */
+    getActive(): RoutingPolicy | undefined;
+    /** Promote a policy to active (rollback = set back to 'default') */
+    promote(policyId: string): boolean;
+    /** Rollback to default policy */
+    rollback(): void;
+    get activeId(): string;
+}

package/dist/router-evolution.js

@@ -0,0 +1,67 @@
+/**
+ * @hmharness/evolution - Router Evolution (P2-05)
+ *
+ * The audit called for: "让 model routing 本身成为可实验、可回滚策略"
+ *
+ * Makes routing decisions experimentable: a routing policy can be registered
+ * as a candidate, A/B tested against the current policy, and promoted or
+ * rolled back based on SPRT results.
+ */
+/**
+ * Evaluate a routing experiment using simple SPRT logic.
+ * Pure - testable.
+ */
+export function evaluateExperiment(exp) {
+    const minN = 20; // minimum samples per arm
+    if (exp.controlTotal < minN || exp.treatmentTotal < minN) {
+        return { decision: 'continue', reason: `insufficient samples (control ${exp.controlTotal}/${minN}, treatment ${exp.treatmentTotal}/${minN})` };
+    }
+    const controlRate = exp.controlSuccesses / exp.controlTotal;
+    const treatmentRate = exp.treatmentSuccesses / exp.treatmentTotal;
+    const diff = treatmentRate - controlRate;
+    // promote if treatment is 5pp better, rollback if 5pp worse
+    if (diff >= 0.05) {
+        return { decision: 'promote', reason: `treatment ${treatmentRate.toFixed(2)} vs control ${controlRate.toFixed(2)} (+${(diff * 100).toFixed(1)}pp)` };
+    }
+    if (diff <= -0.05) {
+        return { decision: 'rollback', reason: `treatment ${treatmentRate.toFixed(2)} vs control ${controlRate.toFixed(2)} (${(diff * 100).toFixed(1)}pp)` };
+    }
+    return { decision: 'continue', reason: `diff ${(diff * 100).toFixed(1)}pp within noise band` };
+}
+/**
+ * The routing policy registry - manages candidate and active policies.
+ */
+export class RoutingPolicyRegistry {
+    policies = new Map();
+    activePolicyId = 'default';
+    register(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 };
+    }
+    get(id) {
+        return this.policies.get(id);
+    }
+    list() {
+        return [...this.policies.values()];
+    }
+    /** Get the currently active policy */
+    getActive() {
+        return this.policies.get(this.activePolicyId);
+    }
+    /** Promote a policy to active (rollback = set back to 'default') */
+    promote(policyId) {
+        if (!this.policies.has(policyId))
+            return false;
+        this.activePolicyId = policyId;
+        return true;
+    }
+    /** Rollback to default policy */
+    rollback() {
+        this.activePolicyId = 'default';
+    }
+    get activeId() {
+        return this.activePolicyId;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.14.19",
+  "version": "0.14.21",
   "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",