dsh-continual-evolve 0.1.0

package/lib/render.js

@@ -0,0 +1,83 @@
+import { SOURCE_SESSION_KEY, SOURCE_SEQS_KEY, isArchived } from "./types.js";
+const DEFAULT_MAX_ENTRIES_PER_KIND = 6;
+const DEFAULT_MAX_REFINEMENTS = 5;
+const DEFAULT_MAX_CONTENT_LENGTH = 180;
+export function compactText(text, maxLength) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+export function entryLine(entry, maxContentLength) {
+    const argumentsText = entry.kind === "skill" && Object.keys(entry.arguments).length > 0
+        ? ` args=${compactText(JSON.stringify(entry.arguments), maxContentLength)}`
+        : "";
+    const referenceText = entry.kind === "skill" && Object.keys(entry.reference).length > 0
+        ? ` ref=${compactText(JSON.stringify(entry.reference), maxContentLength)}`
+        : "";
+    const citationText = citationSuffix(entry);
+    const archivedText = isArchived(entry) ? " [archived]" : "";
+    return `- [${entry.scope}:${entry.id}] ${entry.title} (${entry.path}, v${entry.version})${archivedText}${referenceText}${argumentsText}${citationText}: ${compactText(entry.content, maxContentLength)}`;
+}
+/** Trajectory citation suffix (` src=sessionId:1,2`), empty when uncited. */
+function citationSuffix(entry) {
+    const sessionId = entry.metadata[SOURCE_SESSION_KEY];
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        return "";
+    }
+    const seqs = entry.metadata[SOURCE_SEQS_KEY];
+    const seqText = Array.isArray(seqs) && seqs.length > 0 ? `:${seqs.join(",")}` : "";
+    return ` src=${sessionId}${seqText}`;
+}
+/** Render the full merged state as a bounded overview for the system prompt. */
+export function formatHarnessStateForPrompt(state) {
+    const lines = [
+        "# Continual Harness State",
+        "",
+        "Local entries belong to this session. Global entries persist across sessions.",
+        "The base system prompt is immutable; prompt entries are supplemental notes only.",
+        "",
+    ];
+    let total = 0;
+    for (const kind of Object.keys(state.entries)) {
+        const entries = Object.values(state.entries[kind]).sort((a, b) => [a.path, a.title, a.id].join("\0").localeCompare([b.path, b.title, b.id].join("\0")));
+        total += entries.length;
+        lines.push(`${kind}: ${entries.length}`);
+        for (const entry of entries.slice(0, DEFAULT_MAX_ENTRIES_PER_KIND)) {
+            lines.push(entryLine(entry, DEFAULT_MAX_CONTENT_LENGTH));
+        }
+        const overflow = entries.length - Math.min(entries.length, DEFAULT_MAX_ENTRIES_PER_KIND);
+        if (overflow > 0) {
+            lines.push(`- +${overflow} more ${kind} entries`);
+        }
+        lines.push("");
+    }
+    if (total === 0) {
+        lines.push("No saved harness entries yet.", "");
+    }
+    lines.push(`recent refinements: ${state.refinements.length}`);
+    for (const event of state.refinements.slice(-DEFAULT_MAX_REFINEMENTS)) {
+        lines.push(`- [${event.id}] ${compactText(event.trigger, DEFAULT_MAX_CONTENT_LENGTH)}: ${event.changes.join(", ") || "no applied edits"}`);
+    }
+    return lines.join("\n").trim();
+}
+/** Render recent refinement results for the planner. */
+export function historyForPrompt(history) {
+    if (history.length === 0) {
+        return "No prior refinement history.";
+    }
+    return history
+        .slice(-20)
+        .map((item) => {
+        const edits = item.appliedEdits.map((e) => `${e.applied ? "applied" : "failed"} ${e.action} ${e.kind}:${e.id}`).join(", ");
+        const rollback = item.rollbackOf ? ` rollbackOf=${item.rollbackOf}` : "";
+        return `[${item.id}]${rollback} ${item.summary}\n${edits}\nExpected outcome: ${item.expectedOutcome}`;
+    })
+        .join("\n\n");
+}
+/** Serialize a refinement event for persistence (lightweight). */
+export function eventToLine(event) {
+    return JSON.stringify(event);
+}
+//# sourceMappingURL=render.js.map

package/lib/review.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The automatic /evolve review gate: a cheap model call that decides whether
+ * the current trajectory justifies running the planner. Runs on a turn
+ * interval (and, in a later step, at compaction). The gate is deliberately
+ * small (bounded input, small output budget) — it only answers
+ * "should we refine?", never "what should we edit?".
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { HarnessState, RefinementResult } from "./types.js";
+export interface AutoRefineReview {
+    shouldRefine: boolean;
+    rationale: string;
+    instructions?: string;
+}
+export type AutoRefineReason = "turn_interval" | "compact";
+export interface AutoRefineReviewContext {
+    reason: AutoRefineReason;
+    turnsSinceLastReview: number;
+}
+export interface ReviewOptions {
+    agent: Agent;
+    state: HarnessState;
+    history: readonly RefinementResult[];
+    context: AutoRefineReviewContext;
+    /** Serialized trajectory text; when absent the gate is skipped by the caller. */
+    trajectory?: string;
+    signal?: AbortSignal;
+    budgetTokens?: number;
+}
+export declare const AUTO_REVIEW_SYSTEM_PROMPT = "You are the automatic /evolve review gate.\n\nDecide whether this checkpoint should run /evolve. Auto /evolve writes local\nharness state by default, so approve when the trajectory contains evidence\nuseful to this session's future turns: a repeated failure, a reusable tactic,\na repeated delegation role, a durable fact or preference, a user correction\nthat should persist, or a narrow behavioral policy.\n\nThe current harness state below includes GLOBAL entries (scope=global) plus\nthis session's local entries (scope=local). When a topic is already covered\nby a global entry, do NOT approve a local duplicate of it \u2014 decline and say\nin the rationale that the topic is already covered globally.\n\nReject one-off noise, unsupported hypotheses, transient tool outputs, and\nrequests that carry no reusable content.\n\nStale local entries (superseded, long-unused, obsolete facts) are a valid\nrefine target: approve with instructions naming the entry ids, and tell the\nplanner to archive them (archive hides from injection, data stays restorable)\nrather than delete.\n\nReturn JSON only:\n{\n  \"shouldRefine\": true|false,\n  \"rationale\": \"short reason\",\n  \"instructions\": \"optional concise instructions for /evolve if shouldRefine is true\"\n}";
+/** Parse the gate's JSON reply. */
+export declare function parseAutoRefineReview(text: string): AutoRefineReview;
+/** Serialize surface events to bounded role-prefixed text. */
+export declare function serializeSurface(events: readonly unknown[], maxChars: number): string;
+export declare function reviewAutoRefine(ctx: Context, options: ReviewOptions): Promise<AutoRefineReview>;
+//# sourceMappingURL=review.d.ts.map

package/lib/review.js

@@ -0,0 +1,127 @@
+import { BlockAssembler, createUserMessage, ReasoningEffortId } from "@deepseek-ai/dsh-llm";
+import { extractJsonObject } from "./plan.js";
+import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
+export const AUTO_REVIEW_SYSTEM_PROMPT = `You are the automatic /evolve review gate.
+
+Decide whether this checkpoint should run /evolve. Auto /evolve writes local
+harness state by default, so approve when the trajectory contains evidence
+useful to this session's future turns: a repeated failure, a reusable tactic,
+a repeated delegation role, a durable fact or preference, a user correction
+that should persist, or a narrow behavioral policy.
+
+The current harness state below includes GLOBAL entries (scope=global) plus
+this session's local entries (scope=local). When a topic is already covered
+by a global entry, do NOT approve a local duplicate of it — decline and say
+in the rationale that the topic is already covered globally.
+
+Reject one-off noise, unsupported hypotheses, transient tool outputs, and
+requests that carry no reusable content.
+
+Stale local entries (superseded, long-unused, obsolete facts) are a valid
+refine target: approve with instructions naming the entry ids, and tell the
+planner to archive them (archive hides from injection, data stays restorable)
+rather than delete.
+
+Return JSON only:
+{
+  "shouldRefine": true|false,
+  "rationale": "short reason",
+  "instructions": "optional concise instructions for /evolve if shouldRefine is true"
+}`;
+/** Parse the gate's JSON reply. */
+export function parseAutoRefineReview(text) {
+    const value = extractJsonObject(text);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("auto-refine review JSON must be an object");
+    }
+    const record = value;
+    const review = {
+        shouldRefine: record["shouldRefine"] === true,
+        rationale: typeof record["rationale"] === "string" ? record["rationale"] : "No rationale provided.",
+    };
+    if (typeof record["instructions"] === "string" && record["instructions"].length > 0) {
+        review.instructions = record["instructions"];
+    }
+    return review;
+}
+/** Serialize surface events to bounded role-prefixed text. */
+export function serializeSurface(events, maxChars) {
+    const lines = [];
+    for (const raw of events) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const event = raw;
+        const role = event.type === "user/message" ? "user" : event.type === "assistant/message" ? "assistant" : null;
+        if (role === null)
+            continue;
+        const content = event.data?.content;
+        if (!Array.isArray(content))
+            continue;
+        const text = content
+            .filter((block) => typeof block === "object" && block !== null && block.type === "text")
+            .map((block) => block.text ?? "")
+            .filter(Boolean)
+            .join(" ");
+        if (text.length > 0) {
+            lines.push(`${role}: ${text}`);
+        }
+    }
+    const joined = lines.join("\n");
+    return joined.length <= maxChars ? joined : joined.slice(-maxChars);
+}
+export async function reviewAutoRefine(ctx, options) {
+    const { agent, state, history } = options;
+    if (!agent.options.provider || !agent.options.model) {
+        throw new Error("evolve: no provider/model route for the review gate");
+    }
+    if (!options.trajectory || options.trajectory.length === 0) {
+        throw new Error("evolve: review gate has no trajectory to judge");
+    }
+    const userPrompt = [
+        `<trigger>\n${options.context.reason}; ${options.context.turnsSinceLastReview} turns since the last review\n</trigger>`,
+        `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
+        `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
+        `<conversation>\n${options.trajectory}\n</conversation>`,
+        "Return shouldRefine=true when the trajectory contains evidence useful to this session's future turns. Prefer local edits; do not ask for global refinement here.",
+    ].join("\n\n");
+    const assembler = new BlockAssembler();
+    for await (const chunk of ctx.llm.stream({
+        provider: agent.options.provider,
+        model: agent.options.model,
+        system: AUTO_REVIEW_SYSTEM_PROMPT,
+        messages: [
+            createUserMessage({
+                content: [{ type: "text", text: userPrompt }],
+                source: { kind: "plugin", plugin: "dsh-continual-evolve" },
+            }),
+        ],
+        // Force non-reasoning output so the model spends its budget on the JSON
+        // answer, not on visible thinking (reasoning models otherwise produce
+        // zero text blocks — the exact failure recorded in reviews.jsonl).
+        reasoningEffort: ReasoningEffortId("off"),
+        maxTokens: options.budgetTokens ?? 8000,
+        ...(options.signal ? { signal: options.signal } : {}),
+    })) {
+        assembler.push(chunk);
+    }
+    const finish = assembler.finish;
+    if (finish.kind === "error") {
+        throw new Error(`evolve: review gate call failed: ${finish.failure?.message ?? "unknown"}`);
+    }
+    if (finish.kind === "aborted") {
+        throw new Error("evolve: review gate call aborted");
+    }
+    if (finish.kind === "max-tokens") {
+        throw new Error("evolve: review gate output budget exhausted (max-tokens)");
+    }
+    const text = assembler
+        .blocks()
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+    if (text.length === 0) {
+        throw new Error("evolve: review gate produced no text");
+    }
+    return parseAutoRefineReview(text);
+}
+//# sourceMappingURL=review.js.map

package/lib/rollback.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Deterministic rollback: rebuild the inverse edit list from the applied
+ * result, in reverse order. Rollback is pure data transformation — no LLM
+ * is asked to "guess" the previous state.
+ */
+import type { HarnessEntry, RefinementProposal, RefinementResult } from "./types.js";
+/** Build the inverse proposal for an applied refinement. */
+export declare function rollbackProposal(target: RefinementResult): RefinementProposal;
+/** Recreate an entry from a prior snapshot (used when an inverse edit is an update). */
+export declare function restoreEntry(prior: HarnessEntry): HarnessEntry;
+//# sourceMappingURL=rollback.d.ts.map

package/lib/rollback.js

@@ -0,0 +1,69 @@
+/** Build the inverse proposal for an applied refinement. */
+export function rollbackProposal(target) {
+    const edits = [];
+    for (const edit of [...target.appliedEdits].reverse()) {
+        if (!edit.applied)
+            continue;
+        const inverse = inverseEdit(edit, target.id);
+        if (inverse) {
+            edits.push(inverse);
+        }
+    }
+    return {
+        summary: `Rollback refinement ${target.id}`,
+        rationale: `Restores harness state to the snapshot recorded before refinement ${target.id}.`,
+        expectedOutcome: "Faulty refinement edits are reverted.",
+        edits,
+    };
+}
+function inverseEdit(edit, refinementId) {
+    if (edit.before && edit.after) {
+        // Forward action was an update: restore the before snapshot.
+        return {
+            action: "update",
+            kind: edit.kind,
+            id: edit.id,
+            title: edit.before.title,
+            content: edit.before.content,
+            path: edit.before.path,
+            reference: edit.before.reference,
+            arguments: edit.before.arguments,
+            metadata: edit.before.metadata,
+            reason: `Rollback ${refinementId}`,
+        };
+    }
+    if (edit.before) {
+        // Forward action was a delete: re-create the entry from the snapshot.
+        return {
+            action: "create",
+            kind: edit.kind,
+            id: edit.id,
+            title: edit.before.title,
+            content: edit.before.content,
+            path: edit.before.path,
+            reference: edit.before.reference,
+            arguments: edit.before.arguments,
+            metadata: edit.before.metadata,
+            reason: `Rollback ${refinementId}`,
+        };
+    }
+    if (edit.after) {
+        // Forward action was a create: delete the created entry.
+        return {
+            action: "delete",
+            kind: edit.kind,
+            id: edit.id,
+            reason: `Rollback ${refinementId}`,
+        };
+    }
+    return undefined;
+}
+/** Recreate an entry from a prior snapshot (used when an inverse edit is an update). */
+export function restoreEntry(prior) {
+    return {
+        ...prior,
+        updated_at: new Date().toISOString(),
+        version: prior.version + 1,
+    };
+}
+//# sourceMappingURL=rollback.js.map

package/lib/rubric.d.ts

@@ -0,0 +1,29 @@
+/** The development fallback key — reachable only when the local key file is unusable. */
+export declare const DEV_RUBRIC_KEY = "dsh-continual-evolve-dev-key";
+/** Name of the per-installation key file under `<baseDir>/evolve/`. */
+export declare const RUBRIC_KEY_FILE_NAME = "rubric.key";
+/** Full path of the per-installation rubric key file. */
+export declare function rubricKeyFilePath(baseDir: string): string;
+export interface RubricCipher {
+    iv: string;
+    tag: string;
+    data: string;
+}
+export declare const RUBRIC_PREFIX = "v1:";
+/** Derive a 32-byte AES-256 key from any passphrase. */
+export declare function deriveKey(passphrase: string): Buffer;
+/** Resolve the effective rubric key with the documented precedence. */
+export declare function resolveRubricKey(baseDir: string, configKey: string | undefined, env?: NodeJS.ProcessEnv, warn?: (message: string) => void): Buffer;
+/** Encrypt rubric plaintext into the `v1:` envelope (never written raw). */
+export declare function encryptRubric(plaintext: string, key: Buffer): string;
+/**
+ * Decrypt a `v1:` envelope. Legacy plaintext (no prefix) passes through
+ * unchanged so pre-ACL benchmark files keep working. Throws on tampered
+ * data, a wrong key, or a malformed envelope.
+ */
+export declare function decryptRubric(payload: string, key: Buffer): string;
+/** True when a stored rubric is an encrypted envelope rather than legacy plaintext. */
+export declare function isEncryptedRubric(payload: string): boolean;
+/** Shape helper for tests and callers that inspect envelopes. */
+export declare function parseEnvelope(payload: string): RubricCipher | undefined;
+//# sourceMappingURL=rubric.d.ts.map

package/lib/rubric.js

@@ -0,0 +1,119 @@
+/**
+ * Rubric ACL: rubric plaintext never touches the disk. The evaluation runner
+ * is the ONLY consumer that decrypts — the optimizer (planner) and the model
+ * (with its bash tools) can read benchmark files and see ciphertext only, so
+ * rubric isolation is enforced by code, not by prompt construction.
+ *
+ * Format: `v1:<base64(iv) | base64(tag) | base64(ciphertext)>` — each part is
+ * URL-safe base64 without padding, joined by `|`. A value without the `v1:`
+ * prefix is treated as legacy plaintext (pre-ACL files) and passes through.
+ *
+ * Key resolution (first match wins):
+ *   1. plugin config `rubricKey`
+ *   2. environment `DSH_EVOLVE_RUBRIC_KEY`
+ *   3. a per-installation local key file at `<baseDir>/evolve/rubric.key`
+ *      (auto-generated with 0600 permissions on first use — every install
+ *      gets its own random key, so no user setup is needed and no publicly
+ *      known key protects anyone's rubrics)
+ *   4. a fixed development key as a last-resort fallback when the key file
+ *      can neither be read nor written (warns; only reachable in
+ *      pathological environments, since the plugin's stores live under the
+ *      same directory)
+ * The key string is derived to 32 bytes with SHA-256, so any passphrase works.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** The development fallback key — reachable only when the local key file is unusable. */
+export const DEV_RUBRIC_KEY = "dsh-continual-evolve-dev-key";
+/** Name of the per-installation key file under `<baseDir>/evolve/`. */
+export const RUBRIC_KEY_FILE_NAME = "rubric.key";
+/** Full path of the per-installation rubric key file. */
+export function rubricKeyFilePath(baseDir) {
+    return join(baseDir, "evolve", RUBRIC_KEY_FILE_NAME);
+}
+export const RUBRIC_PREFIX = "v1:";
+/** Derive a 32-byte AES-256 key from any passphrase. */
+export function deriveKey(passphrase) {
+    return createHash("sha256").update(passphrase, "utf8").digest();
+}
+/** Resolve the effective rubric key with the documented precedence. */
+export function resolveRubricKey(baseDir, configKey, env = process.env, warn) {
+    if (configKey && configKey.length > 0) {
+        return deriveKey(configKey);
+    }
+    const envKey = env["DSH_EVOLVE_RUBRIC_KEY"];
+    if (envKey && envKey.length > 0) {
+        return deriveKey(envKey);
+    }
+    return loadOrCreateLocalKey(baseDir, warn);
+}
+/**
+ * Load the per-installation key file, generating a fresh random key (0600)
+ * on first use. Falls back to the development key with a warning when the
+ * file can neither be read nor written.
+ */
+function loadOrCreateLocalKey(baseDir, warn) {
+    const path = rubricKeyFilePath(baseDir);
+    try {
+        if (existsSync(path)) {
+            const content = readFileSync(path, "utf8").trim();
+            if (content.length > 0) {
+                return deriveKey(content);
+            }
+        }
+        const key = randomBytes(32).toString("hex");
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${key}\n`, { encoding: "utf8", mode: 0o600 });
+        return deriveKey(key);
+    }
+    catch (cause) {
+        warn?.(`rubric encryption: cannot read/write the local key file (${path}): ${cause instanceof Error ? cause.message : String(cause)} — using the development key`);
+        return deriveKey(DEV_RUBRIC_KEY);
+    }
+}
+/** Encrypt rubric plaintext into the `v1:` envelope (never written raw). */
+export function encryptRubric(plaintext, key) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${RUBRIC_PREFIX}${[iv, tag, data].map((part) => part.toString("base64url")).join("|")}`;
+}
+/**
+ * Decrypt a `v1:` envelope. Legacy plaintext (no prefix) passes through
+ * unchanged so pre-ACL benchmark files keep working. Throws on tampered
+ * data, a wrong key, or a malformed envelope.
+ */
+export function decryptRubric(payload, key) {
+    if (!payload.startsWith(RUBRIC_PREFIX)) {
+        return payload; // legacy plaintext file
+    }
+    const raw = payload.slice(RUBRIC_PREFIX.length);
+    const parts = raw.split("|");
+    if (parts.length !== 3) {
+        throw new Error("rubric: malformed encrypted envelope");
+    }
+    const [ivText, tagText, dataText] = parts;
+    const iv = Buffer.from(ivText, "base64url");
+    const tag = Buffer.from(tagText, "base64url");
+    const data = Buffer.from(dataText, "base64url");
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString("utf8");
+}
+/** True when a stored rubric is an encrypted envelope rather than legacy plaintext. */
+export function isEncryptedRubric(payload) {
+    return payload.startsWith(RUBRIC_PREFIX);
+}
+/** Shape helper for tests and callers that inspect envelopes. */
+export function parseEnvelope(payload) {
+    if (!isEncryptedRubric(payload))
+        return undefined;
+    const parts = payload.slice(RUBRIC_PREFIX.length).split("|");
+    if (parts.length !== 3)
+        return undefined;
+    const [iv, tag, data] = parts;
+    return { iv, tag, data };
+}
+//# sourceMappingURL=rubric.js.map

package/lib/score.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Code-owned scoring: aggregation and acceptance decisions. The model only
+ * produces per-cell raw scores; every average and every accept/reject call
+ * happens here, in deterministic code.
+ */
+import type { CellScore, EvaluationEntry } from "./benchmark.js";
+export interface AggregateOptions {
+    /** A cell is "passed" if its raw score is at least this threshold. */
+    passThreshold: number;
+    /** Per-case regression tolerance: candidate may drop below reference by at most this much. */
+    regressionTolerance: number;
+}
+export declare const DEFAULT_AGGREGATE: AggregateOptions;
+/** Aggregate raw cells into code-owned per-case means + overall mean. */
+export declare function aggregate(cells: readonly CellScore[]): Record<string, number | null> & {
+    overall: number | null;
+};
+export declare function entryFromCells(label: string, cells: readonly CellScore[], refinementId?: string): EvaluationEntry;
+export interface Decision {
+    accepted: boolean;
+    reasons: string[];
+}
+/** Human-readable decision report with per-case before → after deltas. */
+export declare function decisionReport(reference: EvaluationEntry, candidate: EvaluationEntry, decision: Decision): string[];
+/**
+ * Non-regressive acceptance rule (Self-Harness style):
+ * the candidate is accepted iff its overall mean is STRICTLY higher than the
+ * reference AND no case regresses by more than `regressionTolerance` points.
+ */
+export declare function decide(reference: EvaluationEntry, candidate: EvaluationEntry, opts: AggregateOptions): Decision;
+//# sourceMappingURL=score.d.ts.map

package/lib/score.js

@@ -0,0 +1,81 @@
+export const DEFAULT_AGGREGATE = { passThreshold: 60, regressionTolerance: 0 };
+/** Aggregate raw cells into code-owned per-case means + overall mean. */
+export function aggregate(cells) {
+    const byCase = new Map();
+    for (const cell of cells) {
+        const list = byCase.get(cell.caseId) ?? [];
+        list.push(clampScore(cell.score));
+        byCase.set(cell.caseId, list);
+    }
+    const perCase = {};
+    for (const [caseId, scores] of byCase) {
+        perCase[caseId] = mean(scores);
+    }
+    const all = [...byCase.values()].flat();
+    return { ...perCase, overall: all.length > 0 ? mean(all) : null };
+}
+export function entryFromCells(label, cells, refinementId) {
+    const aggr = aggregate(cells);
+    return {
+        label,
+        ...(refinementId ? { refinementId } : {}),
+        createdAt: new Date().toISOString(),
+        cells: [...cells],
+        aggregate: aggr,
+        overall: aggr.overall,
+    };
+}
+/** Human-readable decision report with per-case before → after deltas. */
+export function decisionReport(reference, candidate, decision) {
+    const lines = [`overall: ${reference.overall ?? "?"} → ${candidate.overall ?? "?"}`];
+    for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
+        if (caseId === "overall" || refScore === null)
+            continue;
+        const candScore = candidate.aggregate[caseId];
+        lines.push(`  ${caseId}: ${refScore} → ${candScore ?? "?"}`);
+    }
+    lines.push(decision.accepted
+        ? "DECISION: ACCEPTED — overall improved, no regression"
+        : `DECISION: REJECTED — ${decision.reasons.join("; ")}`);
+    return lines;
+}
+/**
+ * Non-regressive acceptance rule (Self-Harness style):
+ * the candidate is accepted iff its overall mean is STRICTLY higher than the
+ * reference AND no case regresses by more than `regressionTolerance` points.
+ */
+export function decide(reference, candidate, opts) {
+    const reasons = [];
+    if (reference.overall === null || candidate.overall === null) {
+        return { accepted: false, reasons: ["reference or candidate evaluation is incomplete"] };
+    }
+    if (candidate.overall <= reference.overall) {
+        reasons.push(`overall not improved: ${candidate.overall} <= ${reference.overall}`);
+    }
+    for (const [caseId, refScore] of Object.entries(reference.aggregate)) {
+        if (caseId === "overall" || refScore === null)
+            continue;
+        const candScore = candidate.aggregate[caseId];
+        if (candScore === null || candScore === undefined) {
+            reasons.push(`candidate missing case ${caseId}`);
+            continue;
+        }
+        if (candScore < refScore - opts.regressionTolerance) {
+            reasons.push(`case ${caseId} regressed: ${candScore} < ${refScore} - ${opts.regressionTolerance}`);
+        }
+    }
+    return { accepted: reasons.length === 0, reasons };
+}
+function mean(values) {
+    const sum = values.reduce((acc, value) => acc + value, 0);
+    return round2(sum / values.length);
+}
+function clampScore(score) {
+    if (!Number.isFinite(score))
+        return 0;
+    return Math.min(100, Math.max(0, score));
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=score.js.map

package/lib/service.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The evolution engine: the only entry point that mutates harness state.
+ * Every mutation path goes through here so snapshot-before-write, apply
+ * accounting, persistence, and result history are enforced in one place.
+ */
+import type { EntrySource, HarnessScope, RefinementProposal, RefinementResult } from "./types.js";
+import { applyRefinementProposal } from "./apply.js";
+import { storePaths } from "./store.js";
+export interface ApplyContext {
+    scope: HarnessScope;
+    sessionId?: string;
+    /** When set, optimistic-concurrency checks reject edits whose entries changed since this baseline. */
+    baselineState?: Parameters<typeof applyRefinementProposal>[0];
+    /** Trajectory citation stamped into newly created entries (see apply.ts). */
+    source?: EntrySource | undefined;
+}
+export interface EvolutionHooks {
+    /** Called after every applied refinement (side-effect boundary: skills sync, etc.). */
+    onApplied?: (result: RefinementResult) => void;
+}
+export declare function createEvolutionEngine(baseDir: string, hooks?: EvolutionHooks): {
+    load: (scope: HarnessScope, sessionId: string | undefined) => import("./types.js").HarnessState;
+    apply: (scope: HarnessScope, sessionId: string | undefined, proposal: RefinementProposal, context?: ApplyContext) => RefinementResult;
+    rollback: (scope: HarnessScope, sessionId: string | undefined, refinementId: string) => RefinementResult;
+    history: (scope: HarnessScope, sessionId: string | undefined) => RefinementResult[];
+    baseDir: string;
+};
+export type EvolutionEngine = ReturnType<typeof createEvolutionEngine>;
+export { storePaths };
+//# sourceMappingURL=service.d.ts.map

package/lib/service.js

@@ -0,0 +1,42 @@
+import { applyRefinementProposal } from "./apply.js";
+import { rollbackProposal } from "./rollback.js";
+import { loadHarnessState, saveHarnessState } from "./state.js";
+import { appendResult, loadResults, snapshotBefore, storePaths } from "./store.js";
+export function createEvolutionEngine(baseDir, hooks = {}) {
+    function load(scope, sessionId) {
+        return loadHarnessState(storePaths(baseDir, scope, sessionId).stateDir, scope);
+    }
+    function apply(scope, sessionId, proposal, context) {
+        const paths = storePaths(baseDir, scope, sessionId);
+        const state = context?.baselineState ?? load(scope, sessionId);
+        const id = `evolve_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        // Code-enforced snapshot: runs before any mutation, cannot be skipped by the model.
+        snapshotBefore(paths, id);
+        const result = applyRefinementProposal(state, proposal, {
+            id,
+            scope,
+            ...(context?.source ? { source: context.source } : {}),
+            ...(context?.baselineState ? { baselineState: context.baselineState } : {}),
+        });
+        saveHarnessState(paths.stateDir, state);
+        appendResult(paths, result);
+        hooks.onApplied?.(result);
+        return result;
+    }
+    function rollback(scope, sessionId, refinementId) {
+        const paths = storePaths(baseDir, scope, sessionId);
+        const history = loadResults(paths);
+        const target = history.find((item) => item.id === refinementId);
+        if (!target) {
+            throw new Error(`Refinement ${refinementId} not found in ${scope} history`);
+        }
+        const proposal = rollbackProposal(target);
+        return apply(scope, sessionId, proposal);
+    }
+    function history(scope, sessionId) {
+        return loadResults(storePaths(baseDir, scope, sessionId));
+    }
+    return { load, apply, rollback, history, baseDir };
+}
+export { storePaths };
+//# sourceMappingURL=service.js.map