synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/critic-agent.js

@@ -0,0 +1,487 @@
+/**
+ * CRITIC AGENT（基线智能体 baseline agent）runner — loop v2 (self-evolution as
+ * in-context RL).
+ *
+ * The CRITIC AGENT is an AGENT with the SAME input/output as the 主智能体 MAIN
+ * AGENT (frozen actor; the user's host agent running the current 策略 policy
+ * vN+1). It reruns LAST episode's 策略 policy vN on the SAME change in an
+ * ISOLATED worktree, so the 奖励智能体 REWARD AGENT can later 算分 calculate
+ * reward(主臂)＆reward(基线臂) and advantage ＝ reward(主臂) − reward(基线臂).
+ * Only its baseline trajectory survives — 产物即弃 (worktree artifacts
+ * discarded): the worktree is torn down in `finally`, and the single durable
+ * output is the `baseline-arm/` capture in the episode store.
+ *
+ * This module orchestrates ONE baseline arm:
+ *   1. create an isolated worktree OUTSIDE the repo (git worktree, else a
+ *      recursive file copy fallback),
+ *   2. make it runnable (node_modules junction/symlink + the untracked surfaces
+ *      the rerun reads),
+ *   3. INSTALL 策略 policy vN into the worktree from the byte-for-byte version
+ *      snapshot, so the baseline arm reruns the PRIOR policy and not the live
+ *      templates,
+ *   4. rerun headlessly via the host-aware {@link runHeadlessAgent} with
+ *      cwd = worktree, measurement only, never editing canonical files,
+ *   5. persist the baseline arm (stdout always; the claude session transcript +
+ *      action skeleton when discoverable; an `objective.json` shaped IDENTICALLY
+ *      to the main arm's), and
+ *   6. ALWAYS tear the worktree down.
+ *
+ * Honesty contract: a pass rate is parse-or-throw — when the rerun's stdout
+ * carries no parseable test summary the objective records `passRate: null`
+ * rather than fabricating one. The agent is RUN, never asked to edit; the prompt
+ * strips every arm/candidate word.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parseTestMetrics, computePerChangeLoss, measureHealthPenalty, resolveMetricSource, } from '../fitness/index.js';
+import { readProjectConfig } from '../project-config.js';
+import { claudeProjectsDir } from '../learn/trajectory-discovery.js';
+import { claudeSourceFactory } from '../trajectory/adapters/claude.js';
+import { toActionSkeleton } from '../trajectory/skeleton.js';
+import { runHeadlessAgent } from './host-harness.js';
+import { currentPolicyVersion, readPolicyLedger, readPolicySnapshotFiles, } from './policy/index.js';
+import { advanceEpisodeStage, writeArmCapture } from './episode-store.js';
+/** Error thrown when the worktree could not be created (git AND copy fallback failed). */
+export class CriticWorktreeError extends Error {
+    constructor(message) {
+        super(`critic worktree failed: ${message}`);
+        this.name = 'CriticWorktreeError';
+    }
+}
+/**
+ * Decide whether the CRITIC AGENT（基线智能体 baseline agent）should run for the
+ * NEXT episode.
+ *
+ * Skip (`run: false`) when:
+ *   - the 单一血统 single lineage has < 2 versions — there is no PRIOR policy to
+ *     rerun (v0 is the only point; the 主智能体 MAIN AGENT IS v0), OR
+ *   - the head 版本账本 ledger entry's action is 'refused' — the 演进智能体
+ *     EVOLVING AGENT refused last episode, so vN+1 ≡ vN and rerunning the
+ *     baseline would compare a policy against ITSELF (no advantage to measure).
+ *
+ * Otherwise run, rerunning the head version (vN, the policy the LAST episode
+ * settled on, which the current 主智能体 MAIN AGENT also runs as vN+1 unless an
+ * evolve happened — the comparison the 奖励智能体 REWARD AGENT scores).
+ *
+ * Pure read of the ledger via {@link readPolicyLedger}/{@link currentPolicyVersion};
+ * this function NEVER writes episode state. The skip path's
+ * {@link advanceEpisodeStage} to 'baseline-skipped' is the CALLER's job.
+ */
+export async function shouldRunCriticAgent(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const ledger = await readPolicyLedger(repoRoot, opts.targetId);
+    if (ledger.length === 0) {
+        return {
+            run: false,
+            reason: `policy lineage for ${opts.targetId} is not initialized (no versions to rerun)`,
+            baselineVersion: null,
+        };
+    }
+    // A lineage with a single distinct version (only v0) has no PRIOR policy to
+    // compare against. The lineage head is monotonic, so "< 2 versions" is "head
+    // version is 0" — 'init' alone, or 'init' followed only by 'refused' entries
+    // (refused does not bump the version).
+    const head = ledger[ledger.length - 1];
+    const baselineVersion = await currentPolicyVersion(repoRoot, opts.targetId);
+    if (baselineVersion === null || baselineVersion < 1) {
+        return {
+            run: false,
+            reason: `policy lineage for ${opts.targetId} has < 2 versions (head v${baselineVersion ?? 0}); no prior policy to rerun`,
+            baselineVersion: null,
+        };
+    }
+    if (head.action === 'refused') {
+        return {
+            run: false,
+            reason: `last episode refused to evolve ${opts.targetId} (vN+1 ≡ vN); rerunning the baseline would compare a policy against itself`,
+            baselineVersion: null,
+        };
+    }
+    return {
+        run: true,
+        reason: `policy lineage for ${opts.targetId} head v${baselineVersion} (last action '${head.action}'); rerunning the baseline arm`,
+        baselineVersion,
+    };
+}
+/**
+ * Assemble the CRITIC AGENT（基线智能体 baseline agent）rerun prompt. STRIPPED
+ * of every arm/candidate word: the agent is simply told to re-run change
+ * <changeName> end-to-end (apply → gen-test → run-test) under the templates
+ * already installed in its working directory, measurement only, never editing
+ * canonical files, and to print the runner summary line verbatim as its final
+ * line.
+ */
+export function assembleCriticPrompt(changeName) {
+    return [
+        `You are RE-RUNNING an existing SynergySpec change end-to-end to measure its`,
+        `test outcome under the artifact templates already installed in your working`,
+        `directory. This is a measurement run only — do NOT modify any canonical`,
+        `workflow prompt, artifact template, or schema, and do NOT edit the frozen`,
+        `gen-test/run-test oracle.`,
+        ``,
+        `Change name: ${changeName}`,
+        ``,
+        `Run the change's tests (apply → gen-test → run-test) and output the test`,
+        `runner's SUMMARY LINE verbatim as the final line of your response, e.g.`,
+        `"Tests  12 passed | 1 failed (13)" or "5 passed, 0 failed in 0.4s".`,
+    ].join('\n');
+}
+const NODE_MODULES = 'node_modules';
+const CONFIG_DIR = '.synergyspec-selfevolving';
+const SCHEMAS_REL = path.join('synergyspec-selfevolving', 'schemas');
+/**
+ * Run the CRITIC AGENT（基线智能体 baseline agent）'s full baseline arm and
+ * persist its capture. ALWAYS tears the worktree down (产物即弃). On success it
+ * advances the episode to 'baseline-arm-captured' (patch
+ * `{policyVersionBaseline}`). The SKIP path is the caller's job (see
+ * {@link shouldRunCriticAgent}).
+ */
+export async function runCriticAgent(opts) {
+    const repoRoot = path.resolve(opts.repoRoot);
+    const spawnImpl = opts.spawn ?? nodeSpawn;
+    const timeoutMs = opts.timeoutMs ?? 600000;
+    const homeDir = opts.homeDir ?? os.homedir();
+    if (!Number.isInteger(opts.baselineVersion) || opts.baselineVersion < 0) {
+        throw new Error(`runCriticAgent requires a non-negative integer baselineVersion, got ${JSON.stringify(opts.baselineVersion)}`);
+    }
+    const worktreeName = `synergyspec-critic-${opts.episodeId}`;
+    const worktreePath = path.join(os.tmpdir(), worktreeName);
+    // The run window opens just before the spawn; the claude transcript discovery
+    // selects the newest session file written after this instant.
+    const runStart = (opts.now ?? new Date()).getTime();
+    let worktreeMode = 'git-worktree';
+    try {
+        // 1) Isolated worktree OUTSIDE the repo (git worktree --detach, else copy).
+        worktreeMode = await createIsolatedWorktree(repoRoot, worktreePath, spawnImpl);
+        // 2) Make it runnable: node_modules junction/symlink + untracked surfaces.
+        await makeWorktreeRunnable(repoRoot, worktreePath, opts.changeName);
+        // 3) INSTALL 策略 policy vN (byte-for-byte snapshot files) — the fidelity
+        //    fix the old GA replay never performed.
+        await installPolicyVersion(repoRoot, worktreePath, opts.targetId, opts.baselineVersion);
+        // 4) Rerun headlessly with cwd = worktree (measurement only).
+        const prompt = assembleCriticPrompt(opts.changeName);
+        const run = await runHeadlessAgent(prompt, {
+            cwd: worktreePath,
+            spawn: spawnImpl,
+            timeoutMs,
+        });
+        // 5) Build + persist the baseline arm.
+        const measuredAt = new Date().toISOString();
+        const metrics = parseTestMetrics(run.stdout);
+        // Discover + normalize the claude session transcript for the WORKTREE path
+        // (newest session file written after `runStart`). Yields the observed
+        // verdict + the action skeleton; absent on non-claude harnesses or a miss.
+        const trajectory = await discoverWorktreeTrajectory({
+            worktreePath,
+            changeName: opts.changeName,
+            homeDir,
+            runStartMs: runStart,
+        });
+        const facts = trajectory
+            ? // Local import keeps the facts derivation in one place (learn uses the
+                // same function); imported lazily to avoid a top-level cycle hazard.
+                (await import('../trajectory/facts.js')).toTrajectoryFacts(trajectory, opts.changeName)
+            : null;
+        // Honesty: prefer the OBSERVED pass rate (a real runner ran), else the
+        // stdout-parsed summary; null when neither parsed (never fabricated).
+        const observedPassRate = facts?.testRunObserved && facts.observedPassRate !== null
+            ? facts.observedPassRate
+            : null;
+        const passRate = observedPassRate ?? metrics?.passRate ?? null;
+        const verified = facts ? facts.verified : false;
+        const observedStatus = facts ? facts.observedStatus : null;
+        // Health measured against the WORKTREE produced code, via the project's
+        // configured source (resolved from the worktree's copied config). No signal
+        // ⇒ null, exactly like the main arm.
+        const metricSource = resolveMetricSource(readProjectConfig(worktreePath));
+        const healthPenalty = (await measureHealthPenalty(metricSource, worktreePath)) ?? null;
+        const loss = passRate !== null
+            ? computePerChangeLoss({
+                passRate,
+                healthPenalty: healthPenalty ?? undefined,
+                verified: facts ? facts.verified : undefined,
+            }).loss
+            : null;
+        const objective = {
+            passRate,
+            ...(metrics ? { testsTotal: metrics.total, testsFailed: metrics.failed } : {}),
+            healthPenalty,
+            loss,
+            verified,
+            observedStatus,
+            measuredAt,
+        };
+        // Transcript: the claude session `.jsonl` when discovered, else stdout.
+        let transcriptDiscovered = false;
+        let transcript;
+        let skeleton;
+        const sessionPath = trajectory?.sourcePaths[0];
+        if (trajectory && sessionPath) {
+            try {
+                const content = await fs.readFile(sessionPath, 'utf8');
+                transcript = { fileName: 'transcript.jsonl', content };
+                transcriptDiscovered = true;
+                const actionSkeleton = toActionSkeleton(trajectory);
+                if (actionSkeleton)
+                    skeleton = actionSkeleton;
+            }
+            catch {
+                // Unreadable session file — fall back to stdout below.
+                transcript = { fileName: 'stdout.txt', content: run.stdout };
+            }
+        }
+        else {
+            transcript = { fileName: 'stdout.txt', content: run.stdout };
+        }
+        const { armDir } = await writeArmCapture({
+            repoRoot,
+            episodeId: opts.episodeId,
+            arm: 'baseline-arm',
+            transcript,
+            ...(skeleton ? { skeleton } : {}),
+            objective,
+        });
+        // Record the arm landed (monotonic stage advance + which version reran).
+        await advanceEpisodeStage({
+            repoRoot,
+            episodeId: opts.episodeId,
+            stage: 'baseline-arm-captured',
+            patch: { policyVersionBaseline: opts.baselineVersion },
+        });
+        return {
+            armDir,
+            objective,
+            transcriptDiscovered,
+            worktreePath,
+            worktreeMode,
+        };
+    }
+    finally {
+        // 6) 产物即弃: ALWAYS tear the worktree down — even when a step above threw.
+        await teardownWorktree(repoRoot, worktreePath, worktreeMode, spawnImpl);
+    }
+}
+// ---------------------------------------------------------------------------
+// Worktree lifecycle
+// ---------------------------------------------------------------------------
+/**
+ * Create an isolated worktree at `worktreePath` OUTSIDE the repo. Tries
+ * `git worktree add --detach <worktreePath> HEAD` first; on ANY git failure
+ * (not a repo, git missing, etc.) falls back to a recursive file copy of the
+ * repo excluding `node_modules` and `.git`. Returns which mode succeeded.
+ */
+async function createIsolatedWorktree(repoRoot, worktreePath, spawnImpl) {
+    // Best-effort: a stale worktree dir from an interrupted run would make both
+    // git-add and copy fail; clear it first (产物即弃 — nothing here is durable).
+    await fs.rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+    try {
+        await runGit(repoRoot, ['worktree', 'add', '--detach', worktreePath, 'HEAD'], spawnImpl);
+        return 'git-worktree';
+    }
+    catch {
+        // Fall through to the copy fallback (not a git repo, git unavailable, …).
+    }
+    try {
+        await copyRepoTree(repoRoot, worktreePath);
+        return 'copy-fallback';
+    }
+    catch (err) {
+        throw new CriticWorktreeError(`git worktree add failed and the copy fallback failed too: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Tear down the worktree. For a git worktree: `git worktree remove --force` then
+ * `git worktree prune` (both best-effort), and an explicit rmdir to be sure.
+ * For the copy fallback: recursive rmdir. Never throws — teardown failures must
+ * not mask a real error from the run.
+ */
+async function teardownWorktree(repoRoot, worktreePath, mode, spawnImpl) {
+    if (mode === 'git-worktree') {
+        await runGit(repoRoot, ['worktree', 'remove', '--force', worktreePath], spawnImpl).catch(() => { });
+        await runGit(repoRoot, ['worktree', 'prune'], spawnImpl).catch(() => { });
+    }
+    // The node_modules entry is a junction/symlink; `rm -rf` removes the link, not
+    // the real tree behind it. Belt-and-suspenders rmdir for both modes.
+    await fs.rm(worktreePath, { recursive: true, force: true }).catch(() => { });
+}
+/** Run a git subcommand in `repoRoot`; rejects on a non-zero exit or spawn error. */
+async function runGit(repoRoot, args, spawnImpl) {
+    await new Promise((resolve, reject) => {
+        const child = spawnImpl('git', args, { cwd: repoRoot, shell: false });
+        const err = [];
+        child.stderr?.on('data', (c) => err.push(Buffer.from(c)));
+        child.on('error', (e) => reject(e));
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`git ${args[0]} exited ${code}: ${Buffer.concat(err).toString('utf8')}`));
+        });
+    });
+}
+/**
+ * Recursive copy of the repo tree into `dest`, excluding `node_modules` and
+ * `.git` (the two directories that are huge and/or meaningless in an isolated
+ * checkout — node_modules is re-linked separately, .git is the worktree's
+ * parent's concern).
+ */
+async function copyRepoTree(src, dest) {
+    await fs.cp(src, dest, {
+        recursive: true,
+        filter: (source) => {
+            const base = path.basename(source);
+            return base !== NODE_MODULES && base !== '.git';
+        },
+    });
+}
+/**
+ * Make the worktree runnable:
+ *   - junction/symlink `node_modules` into the worktree (junction on Windows so
+ *     no admin/dev-mode is needed; a plain dir symlink elsewhere), and
+ *   - copy the untracked surfaces the rerun reads that git worktree / the copy
+ *     filter do not bring: the change dir, the project-local schemas dir (if
+ *     present), and the `.synergyspec-selfevolving/` config EXCLUDING its
+ *     `self-evolution/` subdir (the loop's own state must NOT leak into the
+ *     isolated rerun).
+ */
+async function makeWorktreeRunnable(repoRoot, worktreePath, changeName) {
+    // node_modules link.
+    const srcNodeModules = path.join(repoRoot, NODE_MODULES);
+    if (await pathExists(srcNodeModules)) {
+        const destNodeModules = path.join(worktreePath, NODE_MODULES);
+        // A git worktree starts empty of node_modules; the copy fallback excluded
+        // it. Either way the dest should not exist — clear a stray one to be safe.
+        await fs.rm(destNodeModules, { recursive: true, force: true }).catch(() => { });
+        const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+        try {
+            await fs.symlink(srcNodeModules, destNodeModules, linkType);
+        }
+        catch {
+            // Symlink/junction unavailable (rare) — leave it absent; the rerun may
+            // still resolve the linked CLI from the parent install. Non-fatal.
+        }
+    }
+    // Untracked change dir (git tracks it once committed, but a fresh change is
+    // untracked; the copy fallback already brought it — copying is idempotent).
+    await copyDirInto(path.join(repoRoot, 'synergyspec-selfevolving', 'changes', changeName), path.join(worktreePath, 'synergyspec-selfevolving', 'changes', changeName));
+    // Project-local schemas dir, when present.
+    await copyDirInto(path.join(repoRoot, SCHEMAS_REL), path.join(worktreePath, SCHEMAS_REL));
+    // `.synergyspec-selfevolving/` config, EXCLUDING the self-evolution/ subdir.
+    const srcConfig = path.join(repoRoot, CONFIG_DIR);
+    if (await pathExists(srcConfig)) {
+        await fs.cp(srcConfig, path.join(worktreePath, CONFIG_DIR), {
+            recursive: true,
+            force: true,
+            filter: (source) => {
+                const rel = path.relative(srcConfig, source);
+                // Drop the loop's own state dir and everything under it.
+                return rel !== 'self-evolution' && !rel.startsWith(`self-evolution${path.sep}`);
+            },
+        });
+    }
+}
+/**
+ * INSTALL the byte-for-byte 策略 policy vN snapshot files into the worktree at
+ * their repo-relative paths. This is the fidelity fix: the baseline arm runs the
+ * SAME policy the LAST episode settled on, not whatever happens to be live.
+ * Snapshot reads are sha256-verified by {@link readPolicySnapshotFiles}, so a
+ * corrupt snapshot throws here rather than silently installing wrong bytes.
+ */
+async function installPolicyVersion(repoRoot, worktreePath, targetId, version) {
+    const files = await readPolicySnapshotFiles(repoRoot, targetId, version);
+    for (const f of files) {
+        const abs = path.join(worktreePath, ...f.relPath.split('/'));
+        // Defense-in-depth: snapshot relPaths are repo-relative POSIX paths; refuse
+        // anything that escapes the worktree.
+        const rel = path.relative(worktreePath, abs);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            throw new Error(`Refusing to install policy file outside the worktree: ${f.relPath}`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, f.content, 'utf8');
+    }
+}
+/**
+ * Discover + normalize the claude session transcript produced by the rerun, by
+ * computing the claude project-dir path-hash FOR THE WORKTREE PATH (the rerun's
+ * cwd) and picking the newest `.jsonl` written after the run started, then
+ * reusing the claude adapter to normalize it. Returns `null` on a non-claude
+ * harness, no projects dir, or no session file in the window — exactly the
+ * "no trajectory ⇒ stdout only" fallback the caller relies on.
+ *
+ * Reuses {@link claudeProjectsDir} (the path-hash encoding) and the public
+ * {@link claudeSourceFactory} (the per-line transcript parser + subagent
+ * stitching) so this never reimplements either; full reuse, no new exports.
+ */
+async function discoverWorktreeTrajectory(opts) {
+    const projectsDir = claudeProjectsDir(opts.worktreePath, opts.homeDir);
+    // No projects dir for the worktree ⇒ the host harness is not claude (or never
+    // wrote a session). Skip cleanly.
+    let entries;
+    try {
+        entries = await fs.readdir(projectsDir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    // Newest `.jsonl` whose mtime is within the run window (>= runStart). Picking
+    // the newest matches trajectory-discovery's window intent: the rerun's own
+    // session is the most-recently-written one under the worktree's project dir.
+    let newest = null;
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
+            continue;
+        const full = path.join(projectsDir, entry.name);
+        let mtimeMs;
+        try {
+            mtimeMs = (await fs.stat(full)).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (mtimeMs < opts.runStartMs)
+            continue;
+        if (!newest || mtimeMs > newest.mtimeMs)
+            newest = { path: full, mtimeMs };
+    }
+    if (!newest)
+        return null;
+    // Normalize via the claude adapter. The source's getTrajectory re-discovers
+    // through findTranscriptsForChange against the WORKTREE root: with no
+    // events.ndjson it uses the mtime-overlap fallback over this same projects
+    // dir, so the session we just selected is the one normalized (main session +
+    // its subagents stitched). Detect against the worktree so the source is
+    // pinned to the worktree's project hash.
+    try {
+        const source = await claudeSourceFactory.detect(opts.worktreePath, {
+            homeDir: opts.homeDir,
+        });
+        if (!source)
+            return null;
+        return await source.getTrajectory(opts.changeName);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Small fs helpers (match the neighbor idiom: no throw on probe)
+// ---------------------------------------------------------------------------
+async function pathExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursive copy of `src` into `dest` when `src` exists; idempotent, no throw on a missing src. */
+async function copyDirInto(src, dest) {
+    if (!(await pathExists(src)))
+        return;
+    await fs.cp(src, dest, { recursive: true, force: true });
+}
+//# sourceMappingURL=critic-agent.js.map

package/dist/core/self-evolution/edits-contract.d.ts

@@ -0,0 +1,53 @@
+export declare class CanonicalProposerOutputInvalid extends Error {
+    constructor(message: string);
+}
+/** The model declined to edit anything (empty edits). Not an error — a no-op. */
+export declare class CanonicalProposerNoOp extends Error {
+    constructor();
+}
+/** The headless agent invocation itself failed (crash / empty output). */
+export declare class CanonicalProposerInvocationError extends Error {
+    constructor(stderr: string);
+}
+/**
+ * The packaged result of one validated candidate edit set: the human-readable
+ * unified diff, the POSIX paths actually edited (a subset of the target's
+ * declared files), a non-empty rationale, and the parsed full-file-replacement
+ * edits. Produced by the manual host-authored channel (`packageHostEdits`).
+ */
+export interface CanonicalProposeOutput {
+    targetId: string;
+    /** A unified-diff rendering of the edits (opaque to the gate; readable by a human). */
+    diffPatch: string;
+    /** POSIX paths actually edited — always a subset of the target's declared files. */
+    changedFiles: string[];
+    /** Non-empty rationale (the static gate requires one). */
+    rationale: string;
+    /** The parsed full-file-replacement edits. */
+    edits: {
+        relPath: string;
+        content: string;
+    }[];
+}
+/**
+ * Validate already-structured candidate edits against the allowed (target-
+ * scoped) file set and the frozen gate-defining files. Author-agnostic: this is
+ * the SINGLE place that enforces, at propose time, that every edit (a) is a
+ * well-formed `{relPath, content}` object, (b) does not touch a
+ * `GATE_DEFINING_FILES` entry (the frozen oracle/gate files), and (c) stays
+ * inside `allowedFiles`. Both the manual host-authored (`--from-edits`) path and
+ * the loop-v2 演进智能体 EVOLVING AGENT call this so their safety contract is
+ * byte-identical. relPaths are normalized to POSIX separators.
+ *
+ * Throws {@link CanonicalProposerNoOp} when `rawEdits` is empty and
+ * {@link CanonicalProposerOutputInvalid} for any shape / frozen / scope
+ * violation. Path traversal and absolute paths are rejected transitively: they
+ * can never be a member of `allowedFiles`, so they fail the scope check.
+ */
+export declare function validateCandidateEdits(rawEdits: readonly unknown[], allowedFiles: readonly string[]): {
+    relPath: string;
+    content: string;
+}[];
+/** Render a whole-file-replacement unified diff (human-readable; git-apply friendly). */
+export declare function renderUnifiedDiff(relPath: string, oldContent: string, newContent: string): string;
+//# sourceMappingURL=edits-contract.d.ts.map

package/dist/core/self-evolution/edits-contract.js

@@ -0,0 +1,89 @@
+/**
+ * Shared candidate-EDITS contract.
+ *
+ * The single place that (a) defines the no-op / invalid-output error classes the
+ * manual host-authored channel raises, (b) validates already-structured
+ * candidate edits against the target-scoped file set + the frozen gate-defining
+ * files, and (c) renders a whole-file-replacement unified diff. Both surviving
+ * edit channels share it byte-for-byte:
+ *   - the manual `--from-edits` / `--from-learn` host-authored path
+ *     (`commands/self-evolution.ts` → `packageHostEdits`, `promote.ts`), and
+ *   - the loop-v2 演进智能体 EVOLVING AGENT (`evolving-agent.ts`).
+ *
+ * Pure (no I/O, no spawn): this module never applies, promotes, or mutates any
+ * canonical file.
+ */
+import { GATE_DEFINING_FILES } from './candidate-gates.js';
+export class CanonicalProposerOutputInvalid extends Error {
+    constructor(message) {
+        super(`canonical proposer output invalid: ${message}`);
+        this.name = 'CanonicalProposerOutputInvalid';
+    }
+}
+/** The model declined to edit anything (empty edits). Not an error — a no-op. */
+export class CanonicalProposerNoOp extends Error {
+    constructor() {
+        super('canonical proposer returned no edits');
+        this.name = 'CanonicalProposerNoOp';
+    }
+}
+/** The headless agent invocation itself failed (crash / empty output). */
+export class CanonicalProposerInvocationError extends Error {
+    constructor(stderr) {
+        super(`canonical proposer invocation failed: ${stderr}`);
+        this.name = 'CanonicalProposerInvocationError';
+    }
+}
+/**
+ * Validate already-structured candidate edits against the allowed (target-
+ * scoped) file set and the frozen gate-defining files. Author-agnostic: this is
+ * the SINGLE place that enforces, at propose time, that every edit (a) is a
+ * well-formed `{relPath, content}` object, (b) does not touch a
+ * `GATE_DEFINING_FILES` entry (the frozen oracle/gate files), and (c) stays
+ * inside `allowedFiles`. Both the manual host-authored (`--from-edits`) path and
+ * the loop-v2 演进智能体 EVOLVING AGENT call this so their safety contract is
+ * byte-identical. relPaths are normalized to POSIX separators.
+ *
+ * Throws {@link CanonicalProposerNoOp} when `rawEdits` is empty and
+ * {@link CanonicalProposerOutputInvalid} for any shape / frozen / scope
+ * violation. Path traversal and absolute paths are rejected transitively: they
+ * can never be a member of `allowedFiles`, so they fail the scope check.
+ */
+export function validateCandidateEdits(rawEdits, allowedFiles) {
+    if (rawEdits.length === 0) {
+        throw new CanonicalProposerNoOp();
+    }
+    const allowed = new Set(allowedFiles.map((p) => p.replace(/\\/g, '/')));
+    const frozen = new Set(GATE_DEFINING_FILES.map((p) => p.replace(/\\/g, '/')));
+    const validated = [];
+    for (const e of rawEdits) {
+        if (!e || typeof e !== 'object') {
+            throw new CanonicalProposerOutputInvalid('edit entry must be an object');
+        }
+        const relPath = e.relPath;
+        const content = e.content;
+        if (typeof relPath !== 'string' || typeof content !== 'string') {
+            throw new CanonicalProposerOutputInvalid('edit must have string relPath and string content');
+        }
+        const norm = relPath.replace(/\\/g, '/');
+        if (frozen.has(norm)) {
+            throw new CanonicalProposerOutputInvalid(`edit relPath "${relPath}" is a gate-defining/frozen file and may never be proposed`);
+        }
+        if (!allowed.has(norm)) {
+            throw new CanonicalProposerOutputInvalid(`edit relPath "${relPath}" is outside the target's declared files`);
+        }
+        validated.push({ relPath: norm, content });
+    }
+    return validated;
+}
+/** Render a whole-file-replacement unified diff (human-readable; git-apply friendly). */
+export function renderUnifiedDiff(relPath, oldContent, newContent) {
+    const oldLines = oldContent.length === 0 ? [] : oldContent.replace(/\n$/, '').split('\n');
+    const newLines = newContent.replace(/\n$/, '').split('\n');
+    const oldStart = oldLines.length === 0 ? 0 : 1;
+    const header = `--- a/${relPath}\n+++ b/${relPath}\n` +
+        `@@ -${oldStart},${oldLines.length} +1,${newLines.length} @@`;
+    const body = [...oldLines.map((l) => `-${l}`), ...newLines.map((l) => `+${l}`)].join('\n');
+    return `${header}\n${body}`;
+}
+//# sourceMappingURL=edits-contract.js.map