synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/episode-store.js

@@ -0,0 +1,573 @@
+/**
+ * 磁盘 DISK episode store（transcripts ×双臂）— loop v2 (self-evolution as
+ * in-context RL).
+ *
+ * This module is DUMB STORAGE plus a stage machine — it never spawns an agent
+ * and never computes a skeleton; callers pass objects in. One episode = one
+ * synergyspec-selfevolving change run through the loop, recorded under:
+ *
+ *     <repoRoot>/.synergyspec-selfevolving/self-evolution/episodes/<episodeId>/
+ *       episode.json     // the state-machine record (this module owns it)
+ *       main-arm/        // 主智能体 MAIN AGENT (frozen actor; the user's host
+ *                        // agent running the current policy vN+1):
+ *                        //   transcript.jsonl + skeleton.json + objective.json
+ *       baseline-arm/    // CRITIC AGENT（基线智能体 baseline agent）output — an
+ *                        // AGENT with the same input/output as the main agent
+ *                        // that reruns LAST episode's policy vN on the SAME
+ *                        // change. This dir is the ONLY artifact that survives
+ *                        // its worktree (产物即弃 — worktree artifacts
+ *                        // discarded): same three files, except the transcript
+ *                        // may be `stdout.txt` when the harness exposes no
+ *                        // session file.
+ *       diagnosis.json   // written LATER by the 奖励智能体 REWARD AGENT via
+ *                        // {@link writeDiagnosis} — LLM as judge; CALCULATES
+ *                        // 算分 reward(主臂)＆reward(基线臂); advantage ＝
+ *                        // reward(主臂) − reward(基线臂); 文本梯度 textual
+ *                        // gradient; never edits; 弃权 abstains when no
+ *                        // nameable gap. {@link createEpisode} never creates
+ *                        // this file; this module only stores its content.
+ *
+ * The 5 artifacts + test-report stay in the change dir
+ * (`synergyspec-selfevolving/changes/<name>/`) — `episode.json` records that
+ * path (`changeDirPath`), never copies.
+ *
+ * 策略 POLICY ＝ design template（主智能体的「权重」）· CLI 持有版本:
+ * `policyVersionMain` / `policyVersionBaseline` record WHICH version each arm
+ * ran. The versions themselves live in the 版本账本 ledger (a sibling module);
+ * 单一血统 single lineage and the 否决缓冲 reject-buffer are enforced there,
+ * not here. The 演进智能体 EVOLVING AGENT (optimizer.step; ONE bounded edit ≤L;
+ * never scores) runs after scoring; its outcome lands in this store only as a
+ * stage (`evolved` | `evolution-refused`).
+ *
+ * Hard rules (matching candidates.ts):
+ *   - This module ONLY reads/writes inside the episodes base dir.
+ *   - All writes use a tmp + rename pattern so a half-written record never
+ *     appears under its final name.
+ *   - Stage changes go through a validated MONOTONIC state machine —
+ *     advancing to a stage not reachable from the current one throws.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+/**
+ * Iterable list of every legal {@link EpisodeStage} value. Order follows the
+ * documented state machine for readability, not behavior.
+ */
+export const EPISODE_STAGES = [
+    'created',
+    'main-arm-captured',
+    'baseline-arm-captured',
+    'baseline-skipped',
+    'scored',
+    'rolled-back',
+    'kept',
+    'evolved',
+    'evolution-refused',
+    'abstained',
+    'closed',
+];
+const EPISODES_SUBDIR = path.join('.synergyspec-selfevolving', 'self-evolution', 'episodes');
+const EPISODE_JSON_FILE = 'episode.json';
+const DIAGNOSIS_JSON_FILE = 'diagnosis.json';
+const SKELETON_JSON_FILE = 'skeleton.json';
+const OBJECTIVE_JSON_FILE = 'objective.json';
+const EPISODE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const LEGAL_STAGE_TRANSITIONS = new Map([
+    ['created', new Set(['main-arm-captured'])],
+    [
+        'main-arm-captured',
+        new Set(['baseline-arm-captured', 'baseline-skipped']),
+    ],
+    ['baseline-arm-captured', new Set(['scored'])],
+    ['baseline-skipped', new Set(['scored'])],
+    // 'abstained' directly from 'scored': the 奖励智能体 REWARD AGENT 弃权
+    // abstained, so no rollback decision is needed and the 演进智能体
+    // EVOLVING AGENT is never spawned.
+    ['scored', new Set(['rolled-back', 'kept', 'abstained'])],
+    [
+        'rolled-back',
+        new Set(['evolved', 'evolution-refused', 'abstained']),
+    ],
+    ['kept', new Set(['evolved', 'evolution-refused', 'abstained'])],
+    ['evolved', new Set(['closed'])],
+    ['evolution-refused', new Set(['closed'])],
+    ['abstained', new Set(['closed'])],
+    ['closed', new Set()],
+]);
+/**
+ * True iff `(from -> to)` is a legal transition in the episode stage machine.
+ * See the type-level doc on {@link EpisodeStage} for the full table.
+ *
+ * Pure function; safe to call from validators, tests, and UIs.
+ */
+export function isLegalEpisodeStageTransition(from, to) {
+    const allowed = LEGAL_STAGE_TRANSITIONS.get(from);
+    if (!allowed)
+        return false;
+    return allowed.has(to);
+}
+/** Computed: `<repoRoot>/.synergyspec-selfevolving/self-evolution/episodes`. */
+function episodesBaseDir(repoRoot) {
+    return path.join(repoRoot, EPISODES_SUBDIR);
+}
+/**
+ * Absolute path of one episode's directory. No I/O; the dir may not exist yet.
+ * Throws on an unsafe id so this can never be used for path traversal.
+ */
+export function episodeDir(repoRoot, episodeId) {
+    assertSafeEpisodeId(episodeId);
+    return path.join(episodesBaseDir(repoRoot), episodeId);
+}
+/**
+ * Throws if `episodeId` is unsafe to use as a directory name. Episode ids are
+ * sanitized at creation to `[a-z0-9-]`, so anything else (separators, parent
+ * traversal, uppercase, dots) is rejected. Called from every reader/writer
+ * before touching disk.
+ */
+function assertSafeEpisodeId(episodeId) {
+    if (typeof episodeId !== 'string' || episodeId.length === 0) {
+        throw new Error(`Invalid episode id (empty): ${JSON.stringify(episodeId)}`);
+    }
+    if (!EPISODE_ID_PATTERN.test(episodeId)) {
+        throw new Error(`Episode id must match [a-z0-9-] (lowercase, no separators): ${JSON.stringify(episodeId)}`);
+    }
+}
+/**
+ * Throws if `target` resolves to a path outside the episodes base dir. This is
+ * the sole sandbox enforcement for write operations (mirrors candidates.ts).
+ */
+function assertWithinEpisodesBaseDir(repoRoot, target) {
+    const normalizedBase = path.resolve(episodesBaseDir(repoRoot));
+    const normalizedTarget = path.resolve(target);
+    const rel = path.relative(normalizedBase, normalizedTarget);
+    if (rel === '' || rel === '.') {
+        return; // target is exactly the base dir
+    }
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`Refusing to write outside episodes base dir. base=${normalizedBase} target=${normalizedTarget}`);
+    }
+}
+/**
+ * Local atomic-write helper modeled on the candidates.ts idiom: write to a
+ * sibling `.<name>.tmp-<rand>` file, then rename in-place; on a rename failure
+ * remove the tmp file so the original error surfaces with nothing half-written.
+ *
+ * Deliberately NOT imported from `./policy/` — a parallel changeset is creating
+ * that module right now; a later integration step may consolidate the helpers.
+ */
+async function atomicWriteFile(repoRoot, dir, fileName, body) {
+    const finalPath = path.join(dir, fileName);
+    assertWithinEpisodesBaseDir(repoRoot, finalPath);
+    const tmpPath = path.join(dir, `.${fileName}.tmp-${crypto.randomBytes(4).toString('hex')}`);
+    assertWithinEpisodesBaseDir(repoRoot, tmpPath);
+    await fs.writeFile(tmpPath, body, 'utf8');
+    try {
+        await fs.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        try {
+            await fs.rm(tmpPath, { force: true });
+        }
+        catch {
+            // ignore — surface the original failure
+        }
+        throw err;
+    }
+    return finalPath;
+}
+/** Serialize a JSON payload the way every sibling store does (2-space + trailing \n). */
+function jsonBody(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+/**
+ * Sanitize a raw id seed to `[a-z0-9-]`: lowercase, collapse every illegal run
+ * to a single `-`, trim leading/trailing `-`. Note the compact UTC timestamp's
+ * `T` separator comes out lowercase (`20260612t153045`).
+ */
+function sanitizeEpisodeId(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** Compact UTC timestamp `yyyyMMddTHHmmss` (pre-sanitization). */
+function compactUtcTimestamp(now) {
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    return (`${pad(now.getUTCFullYear(), 4)}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}` +
+        `T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`);
+}
+/**
+ * Create a new episode directory with its `episode.json` at stage `created`
+ * (plus empty `main-arm/` and `baseline-arm/` dirs so the on-disk layout is
+ * self-describing). `diagnosis.json` is deliberately NOT created here — the
+ * 奖励智能体 REWARD AGENT writes it later via {@link writeDiagnosis}.
+ *
+ * Atomic: the whole episode dir is staged in a sibling tmp dir and renamed
+ * into place, so a half-written episode never appears under its final id.
+ *
+ * @returns The created record and the absolute episode directory. Callers must
+ *   read `episode.episodeId` back — a collision may have suffixed it.
+ */
+export async function createEpisode(opts) {
+    const { repoRoot, changeName, changeDirPath, targetId, policyVersionMain } = opts;
+    if (typeof changeName !== 'string' || changeName.length === 0) {
+        throw new Error(`Invalid changeName (empty): ${JSON.stringify(changeName)}`);
+    }
+    if (typeof changeDirPath !== 'string' || changeDirPath.length === 0) {
+        throw new Error(`Invalid changeDirPath (empty): ${JSON.stringify(changeDirPath)}`);
+    }
+    if (typeof targetId !== 'string' || targetId.length === 0) {
+        throw new Error(`Invalid targetId (empty): ${JSON.stringify(targetId)}`);
+    }
+    if (policyVersionMain !== null && !Number.isFinite(policyVersionMain)) {
+        throw new Error(`Invalid policyVersionMain (must be a finite number or null): ${JSON.stringify(policyVersionMain)}`);
+    }
+    const now = opts.now ?? new Date();
+    let baseId;
+    if (opts.episodeId !== undefined) {
+        assertSafeEpisodeId(opts.episodeId);
+        baseId = opts.episodeId;
+    }
+    else {
+        baseId = sanitizeEpisodeId(`${changeName}-${compactUtcTimestamp(now)}`);
+    }
+    const baseDir = episodesBaseDir(repoRoot);
+    // Collision suffixing: first free of <baseId>, <baseId>-2, <baseId>-3, …
+    let id = baseId;
+    for (let n = 2;; n++) {
+        const candidateDir = path.join(baseDir, id);
+        try {
+            await fs.stat(candidateDir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                break;
+            throw err;
+        }
+        id = `${baseId}-${n}`;
+    }
+    const at = now.toISOString();
+    const episode = {
+        schemaVersion: 1,
+        episodeId: id,
+        changeName,
+        changeDirPath,
+        targetId,
+        policyVersionMain,
+        policyVersionBaseline: null,
+        stage: 'created',
+        stageHistory: [{ stage: 'created', at }],
+        createdAt: at,
+        updatedAt: at,
+    };
+    await fs.mkdir(baseDir, { recursive: true });
+    const finalDir = path.join(baseDir, id);
+    assertWithinEpisodesBaseDir(repoRoot, finalDir);
+    // mkdtemp returns the actual path used (handles os-suffix). Prefix with id.
+    const tmpDir = await fs.mkdtemp(path.join(baseDir, `${id}.tmp-`));
+    assertWithinEpisodesBaseDir(repoRoot, tmpDir);
+    try {
+        await fs.writeFile(path.join(tmpDir, EPISODE_JSON_FILE), jsonBody(episode), 'utf8');
+        await fs.mkdir(path.join(tmpDir, 'main-arm'));
+        await fs.mkdir(path.join(tmpDir, 'baseline-arm'));
+        await fs.rename(tmpDir, finalDir);
+    }
+    catch (err) {
+        // Best-effort cleanup; surface the original failure.
+        try {
+            await fs.rm(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+    return { episode, episodeDir: finalDir };
+}
+/**
+ * Parse an `episode.json` payload with light runtime validation (mirrors
+ * `parseCandidateJson` in candidates.ts): obvious shape violations are
+ * rejected at the read boundary while additive future fields pass through.
+ */
+function parseEpisodeJson(jsonRaw, episodeId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonRaw);
+    }
+    catch (err) {
+        throw new Error(`Invalid episode.json for ${episodeId}: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error(`Invalid episode.json for ${episodeId}: expected object, got ${typeof parsed}`);
+    }
+    const o = parsed;
+    if (o.schemaVersion !== 1) {
+        throw new Error(`Invalid episode.json for ${episodeId}: unsupported schemaVersion ${JSON.stringify(o.schemaVersion)}`);
+    }
+    const requiredString = (key) => {
+        const v = o[key];
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new Error(`Invalid episode.json for ${episodeId}: missing/empty string field "${key}"`);
+        }
+        return v;
+    };
+    const numberOrNull = (key) => {
+        const v = o[key];
+        if (v === null)
+            return null;
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new Error(`Invalid episode.json for ${episodeId}: field "${key}" must be a finite number or null`);
+        }
+        return v;
+    };
+    requiredString('episodeId');
+    requiredString('changeName');
+    requiredString('changeDirPath');
+    requiredString('targetId');
+    requiredString('createdAt');
+    requiredString('updatedAt');
+    numberOrNull('policyVersionMain');
+    numberOrNull('policyVersionBaseline');
+    const stage = requiredString('stage');
+    if (!EPISODE_STAGES.includes(stage)) {
+        throw new Error(`Invalid episode.json for ${episodeId}: stage "${stage}" is not a known EpisodeStage`);
+    }
+    const history = o.stageHistory;
+    if (!Array.isArray(history)) {
+        throw new Error(`Invalid episode.json for ${episodeId}: field "stageHistory" must be an array`);
+    }
+    for (const entry of history) {
+        const entryStage = entry?.stage;
+        const entryAt = entry?.at;
+        if (typeof entryStage !== 'string' ||
+            !EPISODE_STAGES.includes(entryStage) ||
+            typeof entryAt !== 'string') {
+            throw new Error(`Invalid episode.json for ${episodeId}: stageHistory entries need a known stage and a string "at"`);
+        }
+    }
+    return o;
+}
+/**
+ * Read one episode's `episode.json`. Throws a deterministic `Error` when the
+ * episode does not exist.
+ */
+export async function readEpisode(repoRoot, episodeId) {
+    const dir = episodeDir(repoRoot, episodeId);
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(dir, EPISODE_JSON_FILE), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`Episode not found: ${episodeId} (looked under ${dir})`);
+        }
+        throw err;
+    }
+    return parseEpisodeJson(raw, episodeId);
+}
+const ALLOWED_PATCH_KEYS = new Set([
+    'policyVersionBaseline',
+    'baselineSkippedReason',
+    'advantage',
+]);
+/** Validate an {@link EpisodeStagePatch} fail-closed; returns the merge slice. */
+function validateStagePatch(patch, episodeId) {
+    const merge = {};
+    for (const key of Object.keys(patch)) {
+        if (!ALLOWED_PATCH_KEYS.has(key)) {
+            throw new Error(`Illegal episode patch field for ${episodeId}: "${key}" ` +
+                `(allowed: policyVersionBaseline, baselineSkippedReason, advantage)`);
+        }
+    }
+    if ('policyVersionBaseline' in patch) {
+        const v = patch.policyVersionBaseline;
+        if (v !== null && !Number.isFinite(v)) {
+            throw new Error(`Invalid patch for ${episodeId}: policyVersionBaseline must be a finite number or null`);
+        }
+        merge.policyVersionBaseline = v ?? null;
+    }
+    if ('baselineSkippedReason' in patch) {
+        const v = patch.baselineSkippedReason;
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new Error(`Invalid patch for ${episodeId}: baselineSkippedReason must be a non-empty string`);
+        }
+        merge.baselineSkippedReason = v;
+    }
+    if ('advantage' in patch) {
+        const v = patch.advantage;
+        if (v !== null && !Number.isFinite(v)) {
+            throw new Error(`Invalid patch for ${episodeId}: advantage must be a finite number or null`);
+        }
+        merge.advantage = v ?? null;
+    }
+    return merge;
+}
+/**
+ * Advance an episode to its next stage — atomic read-modify-write of
+ * `episode.json` (sibling tmp file + rename, so a half-written advance is
+ * never observed).
+ *
+ * - Validates the transition via {@link isLegalEpisodeStageTransition};
+ *   advancing to a stage not reachable from the current one throws.
+ * - Appends `{stage, at}` to `stageHistory`.
+ * - Merges the allowlisted `patch` fields (`policyVersionBaseline`,
+ *   `baselineSkippedReason`, `advantage`) in the same write.
+ * - Bumps `updatedAt`.
+ */
+export async function advanceEpisodeStage(opts) {
+    const { repoRoot, episodeId, stage, patch } = opts;
+    if (!EPISODE_STAGES.includes(stage)) {
+        throw new Error(`Unknown episode stage: ${JSON.stringify(stage)}`);
+    }
+    const current = await readEpisode(repoRoot, episodeId);
+    if (!isLegalEpisodeStageTransition(current.stage, stage)) {
+        throw new Error(`Illegal episode stage transition for ${episodeId}: ${current.stage} -> ${stage}`);
+    }
+    const merge = patch ? validateStagePatch(patch, episodeId) : {};
+    const at = new Date().toISOString();
+    const updated = {
+        ...current,
+        ...merge,
+        stage,
+        stageHistory: [...current.stageHistory, { stage, at }],
+        updatedAt: at,
+    };
+    const dir = episodeDir(repoRoot, episodeId);
+    await atomicWriteFile(repoRoot, dir, EPISODE_JSON_FILE, jsonBody(updated));
+    return updated;
+}
+/**
+ * List every episode (newest first by `createdAt`; ties resolve by id for
+ * determinism, matching `listCandidates`).
+ *
+ * - Returns `[]` cleanly when the episodes base dir does not exist.
+ * - Skips in-flight `.tmp-` dirs from a previous interrupted create.
+ * - Skips directories without a readable, valid `episode.json` (prints a
+ *   warning to stderr so corrupted episodes are surfaced).
+ */
+export async function listEpisodes(repoRoot) {
+    const baseDir = episodesBaseDir(repoRoot);
+    let entries;
+    try {
+        entries = await fs.readdir(baseDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        // Skip in-flight tmp dirs from a previous interrupted create.
+        if (entry.name.includes('.tmp-'))
+            continue;
+        let raw;
+        try {
+            raw = await fs.readFile(path.join(baseDir, entry.name, EPISODE_JSON_FILE), 'utf8');
+        }
+        catch {
+            // eslint-disable-next-line no-console
+            console.warn(`[episode-store] skipping ${entry.name}: missing or unreadable ${EPISODE_JSON_FILE}`);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseEpisodeJson(raw, entry.name);
+        }
+        catch {
+            // eslint-disable-next-line no-console
+            console.warn(`[episode-store] skipping ${entry.name}: invalid ${EPISODE_JSON_FILE}`);
+            continue;
+        }
+        results.push(parsed);
+    }
+    results.sort((a, b) => {
+        // Descending createdAt; ties resolve by id for determinism.
+        if (a.createdAt === b.createdAt) {
+            return a.episodeId < b.episodeId ? 1 : a.episodeId > b.episodeId ? -1 : 0;
+        }
+        return a.createdAt < b.createdAt ? 1 : -1;
+    });
+    return results;
+}
+/**
+ * Throws if `fileName` is unsafe to write inside an arm dir (path separators,
+ * traversal, hidden tmp collisions, NUL).
+ */
+function assertSafeArmFileName(fileName) {
+    if (typeof fileName !== 'string' || fileName.length === 0) {
+        throw new Error(`Invalid transcript fileName (empty): ${JSON.stringify(fileName)}`);
+    }
+    if (fileName.includes('/') ||
+        fileName.includes('\\') ||
+        fileName.includes('..') ||
+        fileName.includes('\x00') ||
+        fileName.startsWith('.')) {
+        throw new Error(`Refusing to write transcript with unsafe fileName: ${JSON.stringify(fileName)}`);
+    }
+}
+/**
+ * Persist one arm's capture into `<episodeDir>/<arm>/`. DUMB STORAGE: callers
+ * pass the transcript/skeleton/objective in; this module never spawns the
+ * 主智能体 MAIN AGENT or the CRITIC AGENT（基线智能体 baseline agent）and never
+ * computes a skeleton. Each file is written atomically (tmp + rename);
+ * re-capturing overwrites (last write wins). Stage advancement is the
+ * caller's job via {@link advanceEpisodeStage} — storage and state machine
+ * stay decoupled.
+ *
+ * @returns The absolute arm dir and the absolute paths written.
+ */
+export async function writeArmCapture(opts) {
+    const { repoRoot, episodeId, arm, transcript, skeleton, objective } = opts;
+    if (arm !== 'main-arm' && arm !== 'baseline-arm') {
+        throw new Error(`Invalid arm (expected 'main-arm' | 'baseline-arm'): ${JSON.stringify(arm)}`);
+    }
+    if (typeof objective !== 'object' || objective === null) {
+        throw new Error(`Invalid objective for ${episodeId}: expected an object`);
+    }
+    if (skeleton !== undefined && (typeof skeleton !== 'object' || skeleton === null)) {
+        throw new Error(`Invalid skeleton for ${episodeId}: expected an object`);
+    }
+    if (transcript !== undefined) {
+        assertSafeArmFileName(transcript.fileName);
+        if (typeof transcript.content !== 'string') {
+            throw new Error(`Invalid transcript content for ${episodeId}: expected a string`);
+        }
+    }
+    // Fail closed when the episode record does not exist.
+    await readEpisode(repoRoot, episodeId);
+    const armDir = path.join(episodeDir(repoRoot, episodeId), arm);
+    assertWithinEpisodesBaseDir(repoRoot, armDir);
+    await fs.mkdir(armDir, { recursive: true });
+    const writtenFiles = [];
+    if (transcript !== undefined) {
+        writtenFiles.push(await atomicWriteFile(repoRoot, armDir, transcript.fileName, transcript.content));
+    }
+    if (skeleton !== undefined) {
+        writtenFiles.push(await atomicWriteFile(repoRoot, armDir, SKELETON_JSON_FILE, jsonBody(skeleton)));
+    }
+    writtenFiles.push(await atomicWriteFile(repoRoot, armDir, OBJECTIVE_JSON_FILE, jsonBody(objective)));
+    return { armDir, writtenFiles };
+}
+/**
+ * Atomic write of `<episodeDir>/diagnosis.json`. Last write wins (an episode
+ * has exactly ONE current diagnosis; the audit trail is `stageHistory`).
+ * Throws deterministically when the episode does not exist.
+ *
+ * @returns The absolute path of the written `diagnosis.json`.
+ */
+export async function writeDiagnosis(opts) {
+    const { repoRoot, episodeId, diagnosis } = opts;
+    if (typeof diagnosis !== 'object' || diagnosis === null) {
+        throw new Error(`Invalid diagnosis for ${episodeId}: expected an object`);
+    }
+    // Fail closed when the episode record does not exist.
+    await readEpisode(repoRoot, episodeId);
+    const dir = episodeDir(repoRoot, episodeId);
+    return atomicWriteFile(repoRoot, dir, DIAGNOSIS_JSON_FILE, jsonBody(diagnosis));
+}
+//# sourceMappingURL=episode-store.js.map

package/dist/core/self-evolution/evolution-switches.d.ts

@@ -1,4 +1,4 @@
-export declare const EVOLVABLE_PARTS: readonly ["template-variants", "archive-memory", "task-decomposition", "alignment-verifier", "tool-evolution-guard", "runtime-memory", "dgm-harness"];
+export declare const EVOLVABLE_PARTS: readonly ["artifact-templates", "archive-memory", "task-decomposition", "alignment-verifier", "tool-evolution-guard", "runtime-memory"];
 export type EvolvablePart = (typeof EVOLVABLE_PARTS)[number];
 export interface EvolutionSwitches {
     enabled: EvolvablePart[];

package/dist/core/self-evolution/evolution-switches.js

@@ -1,26 +1,24 @@
 export const EVOLVABLE_PARTS = [
-    'template-variants',
+    'artifact-templates',
     'archive-memory',
     'task-decomposition',
     'alignment-verifier',
     'tool-evolution-guard',
     'runtime-memory',
-    'dgm-harness',
 ];
 export const EVOLVABLE_PART_DESCRIPTIONS = {
-    'template-variants': 'Project-local template variant selection and lifecycle feedback',
+    'artifact-templates': 'Artifact and workflow-prompt template contracts (the user-facing template surface)',
     'archive-memory': 'Archived change experience retrieval and prompt injection',
     'task-decomposition': 'Task breakdown scoring and strategy feedback',
     'alignment-verifier': 'No-reference spec-code alignment verification',
     'tool-evolution-guard': 'Guard for schema, CLI, and tool self-modifications',
     'runtime-memory': 'Persistent runtime memory retrieval, extraction, feedback, and writing',
-    'dgm-harness': 'Outer-loop variant proposal, benchmark selection, and lineage evolution',
 };
 const PART_SET = new Set(EVOLVABLE_PARTS);
 const PART_ALIASES = new Map([
-    ['templates', 'template-variants'],
-    ['template', 'template-variants'],
-    ['template-variant', 'template-variants'],
+    ['templates', 'artifact-templates'],
+    ['template', 'artifact-templates'],
+    ['artifact-template', 'artifact-templates'],
     ['archive', 'archive-memory'],
     ['archive-experience', 'archive-memory'],
     ['task', 'task-decomposition'],
@@ -35,9 +33,6 @@ const PART_ALIASES = new Map([
     ['tool-evolution', 'tool-evolution-guard'],
     ['memory', 'runtime-memory'],
     ['runtime', 'runtime-memory'],
-    ['dgm', 'dgm-harness'],
-    ['outer-loop', 'dgm-harness'],
-    ['harness', 'dgm-harness'],
 ]);
 export function resolveEvolutionSwitches(input = {}) {
     const env = input.env ?? process.env;