@hmharness/evolution 0.14.18 → 0.14.20

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/knowledge-graph.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @hmharness/evolution - Project Knowledge Graph (P1-04)
+ *
+ * The audit called for: "Project/Module/API/Bug/Decision/Skill/SDK/Device 关系"
+ *
+ * A lightweight in-memory graph with typed nodes and edges, persisted as JSONL.
+ * Query by node type, edge type, or traversal.
+ */
+export type KGNodeType = 'project' | 'module' | 'api' | 'bug' | 'decision' | 'skill' | 'sdk' | 'device' | 'person';
+export type KGEdgeType = 'contains' | 'depends_on' | 'uses' | 'fixes' | 'decided_by' | 'built_with' | 'runs_on' | 'authored_by' | 'relates_to';
+export interface KGNode {
+    id: string;
+    type: KGNodeType;
+    label: string;
+    properties?: Record<string, unknown>;
+}
+export interface KGEdge {
+    from: string;
+    to: string;
+    type: KGEdgeType;
+    properties?: Record<string, unknown>;
+}
+export interface KnowledgeGraph {
+    nodes: KGNode[];
+    edges: KGEdge[];
+}
+export declare function emptyGraph(): KnowledgeGraph;
+export declare function addNode(g: KnowledgeGraph, node: KGNode): KnowledgeGraph;
+export declare function addEdge(g: KnowledgeGraph, edge: KGEdge): KnowledgeGraph;
+export declare function findNode(g: KnowledgeGraph, id: string): KGNode | undefined;
+export declare function nodesByType(g: KnowledgeGraph, type: KGNodeType): KGNode[];
+export declare function edgesByType(g: KnowledgeGraph, type: KGEdgeType): KGEdge[];
+/** Get all nodes connected to a given node (either direction) */
+export declare function neighbors(g: KnowledgeGraph, nodeId: string): KGNode[];
+/** Get all nodes reachable from a starting node via specific edge types */
+export declare function traverse(g: KnowledgeGraph, startId: string, edgeTypes: KGEdgeType[]): KGNode[];
+/** Serialize to JSONL for persistence */
+export declare function tojsonl(g: KnowledgeGraph): string;
+/** Deserialize from JSONL */
+export declare function fromjsonl(text: string): KnowledgeGraph;
+/** Count nodes and edges by type for a summary */
+export declare function graphStats(g: KnowledgeGraph): {
+    nodes: number;
+    edges: number;
+    byNodeType: Record<string, number>;
+    byEdgeType: Record<string, number>;
+};

package/dist/knowledge-graph.js

@@ -0,0 +1,85 @@
+/**
+ * @hmharness/evolution - Project Knowledge Graph (P1-04)
+ *
+ * The audit called for: "Project/Module/API/Bug/Decision/Skill/SDK/Device 关系"
+ *
+ * A lightweight in-memory graph with typed nodes and edges, persisted as JSONL.
+ * Query by node type, edge type, or traversal.
+ */
+export function emptyGraph() {
+    return { nodes: [], edges: [] };
+}
+export function addNode(g, node) {
+    if (g.nodes.some(n => n.id === node.id))
+        return g;
+    return { ...g, nodes: [...g.nodes, node] };
+}
+export function addEdge(g, edge) {
+    return { ...g, edges: [...g.edges, edge] };
+}
+export function findNode(g, id) {
+    return g.nodes.find(n => n.id === id);
+}
+export function nodesByType(g, type) {
+    return g.nodes.filter(n => n.type === type);
+}
+export function edgesByType(g, type) {
+    return g.edges.filter(e => e.type === type);
+}
+/** Get all nodes connected to a given node (either direction) */
+export function neighbors(g, nodeId) {
+    const ids = new Set();
+    for (const e of g.edges) {
+        if (e.from === nodeId)
+            ids.add(e.to);
+        if (e.to === nodeId)
+            ids.add(e.from);
+    }
+    return g.nodes.filter(n => ids.has(n.id));
+}
+/** Get all nodes reachable from a starting node via specific edge types */
+export function traverse(g, startId, edgeTypes) {
+    const visited = new Set([startId]);
+    const queue = [startId];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const e of g.edges) {
+            if (e.from === current && edgeTypes.includes(e.type) && !visited.has(e.to)) {
+                visited.add(e.to);
+                queue.push(e.to);
+            }
+        }
+    }
+    return g.nodes.filter(n => visited.has(n.id));
+}
+/** Serialize to JSONL for persistence */
+export function tojsonl(g) {
+    const lines = g.nodes.map(n => JSON.stringify({ _t: 'node', ...n }));
+    lines.push(...g.edges.map(e => JSON.stringify({ _t: 'edge', ...e })));
+    return lines.join('\n') + '\n';
+}
+/** Deserialize from JSONL */
+export function fromjsonl(text) {
+    const g = emptyGraph();
+    for (const line of text.split('\n').filter(Boolean)) {
+        try {
+            const obj = JSON.parse(line);
+            if (obj._t === 'node')
+                g.nodes.push(obj);
+            else if (obj._t === 'edge')
+                g.edges.push(obj);
+        }
+        catch { /* skip malformed */ }
+    }
+    return g;
+}
+/** Count nodes and edges by type for a summary */
+export function graphStats(g) {
+    const byNodeType = {};
+    for (const n of g.nodes)
+        byNodeType[n.type] = (byNodeType[n.type] ?? 0) + 1;
+    const byEdgeType = {};
+    for (const e of g.edges)
+        byEdgeType[e.type] = (byEdgeType[e.type] ?? 0) + 1;
+    return { nodes: g.nodes.length, edges: g.edges.length, byNodeType, byEdgeType };
+}

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.18",
+  "version": "0.14.20",
   "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",