synergyspec-selfevolving 1.3.0 → 2.0.0

package/dist/core/self-evolution/policy/reject-buffer.d.ts

@@ -0,0 +1,48 @@
+/** Why the attempted evolve step was rejected. */
+export type RejectBufferReason = 'bad-advantage' | 'human-reject';
+/** Compact description of the rejected edit (the files themselves rolled back). */
+export interface RejectBufferEditSummary {
+    /** Repo-relative POSIX paths the rejected edit touched. */
+    files: string[];
+    linesAdded: number;
+    linesRemoved: number;
+    /** Short excerpt of the edit's rationale, for the next episode's context. */
+    rationaleExcerpt: string;
+}
+/** One line of the 否决缓冲 (`reject-buffer.ndjson`). */
+export interface RejectBufferEntry {
+    schemaVersion: 1;
+    /** ISO-8601 UTC timestamp the rejection was recorded. */
+    at: string;
+    episodeId: string;
+    targetId: string;
+    /** The lineage version the rejected edit was based on. */
+    fromVersion: number;
+    /** The (now rolled-back) version the rejected edit had advanced to. */
+    toVersion: number;
+    /** advantage ＝ reward(主臂) − reward(基线臂); null when not measured. */
+    advantage: number | null;
+    rewardMain: number | null;
+    rewardBaseline: number | null;
+    /** The 文本梯度 textual gradient the rejected edit was acting on. */
+    textualGradientTried: string;
+    editSummary: RejectBufferEditSummary;
+    reason: RejectBufferReason;
+}
+/**
+ * Append one rejection to the 否决缓冲. Fail-closed: an invalid entry throws
+ * and nothing is written. Returns the buffer's path.
+ */
+export declare function appendRejectBufferEntry(repoRoot: string, entry: RejectBufferEntry): Promise<string>;
+/**
+ * Read one target's rejections, newest LAST (file/append order). `limit`
+ * returns only the most recent N (still newest last). Returns `[]` when the
+ * buffer does not exist; malformed lines are skipped best-effort.
+ */
+export declare function readRejectBuffer(repoRoot: string, targetId: string, limit?: number): Promise<RejectBufferEntry[]>;
+/**
+ * Read EVERY target's rejections, newest LAST (file/append order). Returns
+ * `[]` when the buffer does not exist; malformed lines are skipped best-effort.
+ */
+export declare function readRejectBufferAll(repoRoot: string): Promise<RejectBufferEntry[]>;
+//# sourceMappingURL=reject-buffer.d.ts.map

package/dist/core/self-evolution/policy/reject-buffer.js

@@ -0,0 +1,168 @@
+/**
+ * 否决缓冲 reject-buffer — the append-only record of evolve attempts the loop
+ * said NO to: a bad advantage measured by the 奖励智能体 REWARD AGENT
+ * (advantage ＝ reward(主臂) − reward(基线臂) came back non-positive), or a
+ * human reject. The 演进智能体 EVOLVING AGENT reads this before
+ * optimizer.step so it does not retry a 文本梯度 textual gradient that
+ * already lost — the rejected edit's summary stays as evidence instead of
+ * being silently discarded with the rolled-back files.
+ *
+ * One NDJSON line per rejection in
+ * `<repoRoot>/.synergyspec-selfevolving/self-evolution/policy/reject-buffer.ndjson`,
+ * newest last. Appends are fail-closed (an invalid entry throws and writes
+ * nothing); reads skip malformed lines best-effort, matching the repo's other
+ * ndjson readers.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { resolvePolicyLayout } from './policy-store.js';
+import { appendFileDurable } from './fs-safe.js';
+function isFiniteNumberOrNull(value) {
+    return value === null || (typeof value === 'number' && Number.isFinite(value));
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+/**
+ * Describe the FIRST shape problem of a would-be entry, or `null` when it is
+ * a valid {@link RejectBufferEntry}. Shared by the fail-closed append and the
+ * skip-corrupt-lines read.
+ */
+function rejectBufferEntryProblem(value) {
+    if (!value || typeof value !== 'object')
+        return 'entry must be an object';
+    const e = value;
+    if (e.schemaVersion !== 1)
+        return 'schemaVersion must be 1';
+    if (typeof e.at !== 'string' || e.at.length === 0)
+        return 'at must be an ISO-8601 string';
+    if (typeof e.episodeId !== 'string' || e.episodeId.length === 0) {
+        return 'episodeId must be a non-empty string';
+    }
+    if (typeof e.targetId !== 'string' || e.targetId.length === 0) {
+        return 'targetId must be a non-empty string';
+    }
+    if (!isNonNegativeInteger(e.fromVersion))
+        return 'fromVersion must be a non-negative integer';
+    if (!isNonNegativeInteger(e.toVersion))
+        return 'toVersion must be a non-negative integer';
+    if (!isFiniteNumberOrNull(e.advantage))
+        return 'advantage must be a finite number or null';
+    if (!isFiniteNumberOrNull(e.rewardMain))
+        return 'rewardMain must be a finite number or null';
+    if (!isFiniteNumberOrNull(e.rewardBaseline)) {
+        return 'rewardBaseline must be a finite number or null';
+    }
+    if (typeof e.textualGradientTried !== 'string') {
+        return 'textualGradientTried must be a string (the 文本梯度 textual gradient that was attempted)';
+    }
+    const summary = e.editSummary;
+    if (!summary || typeof summary !== 'object')
+        return 'editSummary must be an object';
+    if (!Array.isArray(summary.files) || summary.files.some((f) => typeof f !== 'string')) {
+        return 'editSummary.files must be string[]';
+    }
+    if (!isNonNegativeInteger(summary.linesAdded)) {
+        return 'editSummary.linesAdded must be a non-negative integer';
+    }
+    if (!isNonNegativeInteger(summary.linesRemoved)) {
+        return 'editSummary.linesRemoved must be a non-negative integer';
+    }
+    if (typeof summary.rationaleExcerpt !== 'string') {
+        return 'editSummary.rationaleExcerpt must be a string';
+    }
+    if (e.reason !== 'bad-advantage' && e.reason !== 'human-reject') {
+        return "reason must be 'bad-advantage' or 'human-reject'";
+    }
+    return null;
+}
+/**
+ * Append one rejection to the 否决缓冲. Fail-closed: an invalid entry throws
+ * and nothing is written. Returns the buffer's path.
+ */
+export async function appendRejectBufferEntry(repoRoot, entry) {
+    const problem = rejectBufferEntryProblem(entry);
+    if (problem !== null) {
+        throw new Error(`Invalid 否决缓冲 reject-buffer entry: ${problem}`);
+    }
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    await fs.mkdir(layout.baseDir, { recursive: true });
+    // Durable append: fsync the fd so a host crash cannot lose a rollback's
+    // reject-buffer record a later separate process (resumeEpisode) relies on.
+    await appendFileDurable(layout.rejectBufferPath, `${JSON.stringify(entry)}\n`);
+    return layout.rejectBufferPath;
+}
+/**
+ * Read one target's rejections, newest LAST (file/append order). `limit`
+ * returns only the most recent N (still newest last). Returns `[]` when the
+ * buffer does not exist; malformed lines are skipped best-effort.
+ */
+export async function readRejectBuffer(repoRoot, targetId, limit) {
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    let raw;
+    try {
+        raw = await fs.readFile(layout.rejectBufferPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (rejectBufferEntryProblem(parsed) !== null)
+            continue;
+        const entry = parsed;
+        if (entry.targetId === targetId)
+            entries.push(entry);
+    }
+    if (limit === undefined)
+        return entries;
+    if (limit <= 0)
+        return [];
+    return entries.slice(-limit);
+}
+/**
+ * Read EVERY target's rejections, newest LAST (file/append order). Returns
+ * `[]` when the buffer does not exist; malformed lines are skipped best-effort.
+ */
+export async function readRejectBufferAll(repoRoot) {
+    const layout = resolvePolicyLayout(path.resolve(repoRoot));
+    let raw;
+    try {
+        raw = await fs.readFile(layout.rejectBufferPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (rejectBufferEntryProblem(parsed) !== null)
+            continue;
+        entries.push(parsed);
+    }
+    return entries;
+}
+//# sourceMappingURL=reject-buffer.js.map

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

@@ -99,7 +99,7 @@ export interface AutoPromoteDecision {
     reason: string;
 }
 /**
- * Pure auto-promote predicate for one-button auto-evolve. The static gate +
+ * Pure auto-promote predicate for one-button promote. The static gate +
  * per-target switch are hard prerequisites; the fitness comparison is the
  * regression guard.
  *

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

@@ -23,8 +23,8 @@
  */
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
-import * as crypto from 'node:crypto';
 import { GATE_DEFINING_FILES } from './candidate-gates.js';
+import { assertWithinRepo, writeFileAtomic } from './policy/fs-safe.js';
 import { resolveTargetLocalFiles } from './local-targets.js';
 import { isCanonicalTargetEvolvable, } from './target-evolution.js';
 import { readCandidatePackage, updateCandidateStatus, } from './candidates.js';
@@ -88,7 +88,7 @@ export async function applyCandidatePromotion(layout, candidateId, opts) {
         assertWithinRepo(repoRoot, abs);
         if (!(await fileExists(abs))) {
             throw new Error(`Refusing to promote ${candidateId}: target file does not exist on disk: ${rel} ` +
-                `(auto-evolve only edits existing local files).`);
+                `(self-evolution only edits existing local files).`);
         }
         resolved.push({ rel, abs, content: edit.content });
     }
@@ -143,11 +143,11 @@ export async function applyCandidatePromotion(layout, candidateId, opts) {
         // Lifecycle bridge: ready-for-eval -> eval-passed -> promoted.
         if (startStatus === 'ready-for-eval') {
             await updateStatus(layout, candidateId, 'eval-passed', {
-                rationale: 'auto-evolve: static gate stands in for the full eval suite (MVP)',
+                rationale: 'promote: static gate stands in for the full eval suite (MVP)',
             });
         }
         promoted = await updateStatus(layout, candidateId, 'promoted', {
-            rationale: `auto-evolve: applied ${appliedFiles.length} file(s) to canonical targets [${candidate.targetIds.join(', ')}]`,
+            rationale: `promote: applied ${appliedFiles.length} file(s) to canonical targets [${candidate.targetIds.join(', ')}]`,
         });
     }
     catch (err) {
@@ -194,7 +194,7 @@ export async function rollbackCandidatePromotion(layout, candidateId, opts) {
         restoredFiles.push(entry.relPath);
     }
     const rolled = await updateCandidateStatus(layout, candidateId, 'rolled-back', {
-        rationale: 'auto-evolve: restored pre-promotion snapshot',
+        rationale: 'rollback: restored pre-promotion snapshot',
     });
     return { candidateId, status: rolled.status, restoredFiles };
 }
@@ -205,7 +205,7 @@ export async function rollbackCandidatePromotion(layout, candidateId, opts) {
  */
 export const DEFAULT_HEALTH_REGRESSION_MARGIN = 0.05;
 /**
- * Pure auto-promote predicate for one-button auto-evolve. The static gate +
+ * Pure auto-promote predicate for one-button promote. The static gate +
  * per-target switch are hard prerequisites; the fitness comparison is the
  * regression guard.
  *
@@ -377,31 +377,4 @@ async function fileExists(abs) {
         return false;
     }
 }
-/** Throw if `abs` resolves outside `repoRoot`. */
-function assertWithinRepo(repoRoot, abs) {
-    const base = path.resolve(repoRoot);
-    const target = path.resolve(abs);
-    const rel = path.relative(base, target);
-    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-        throw new Error(`Refusing to write outside repo root. root=${base} target=${target}`);
-    }
-}
-/** Atomic write via sibling tmp file + rename; cleans up on rename failure. */
-async function writeFileAtomic(abs, content) {
-    const dir = path.dirname(abs);
-    const tmp = path.join(dir, `.${path.basename(abs)}.tmp-${crypto.randomBytes(4).toString('hex')}`);
-    await fs.writeFile(tmp, content, 'utf8');
-    try {
-        await fs.rename(tmp, abs);
-    }
-    catch (err) {
-        try {
-            await fs.rm(tmp, { force: true });
-        }
-        catch {
-            // ignore
-        }
-        throw err;
-    }
-}
 //# sourceMappingURL=promote.js.map

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

@@ -28,8 +28,7 @@ import * as crypto from 'node:crypto';
 import { readCandidatePackage, setCandidateArtifactPath, } from './candidates.js';
 import { lookupCanonicalTarget, } from './canonical-targets.js';
 import { candidateEvalReportSchema } from './eval-report.js';
-import { readCandidateFitness, } from './candidate-fitness.js';
-import { readPromotedBaselineLoss } from './ga-selection.js';
+import { readCandidateFitness, readPromotedBaselineLoss, } from './candidate-fitness.js';
 import { DEFAULT_LOSS_REGRESSION_MARGIN } from './promote.js';
 /** Risk tier ordering used when comparing candidate risk to target risk. */
 const RISK_ORDER = {

package/dist/core/self-evolution/proposer-agent.d.ts

@@ -61,6 +61,26 @@ export interface CanonicalProposeInput {
      * sibling variants drafted from the same evidence diverge. Omitted when absent.
      */
     variantAngle?: string;
+    /**
+     * Pre-rendered DO-NOT-PRUNE block from the SUCCESS CHANNEL (see
+     * {@link import('./success-channel.js').renderDoNotPruneBlock}): target
+     * sections implicated in verified-PASSING runs. Rendered between EVIDENCE and
+     * the improvement angle so the constraint is read BEFORE the angle commits the
+     * model to (e.g.) pruning. Omitted when empty.
+     */
+    doNotPrune?: string;
+    /**
+     * Bounded REAL excerpts from the success-channel exemplar files (what the
+     * protected sections actually look like in passing changes). Omitted when empty.
+     */
+    exemplarsContext?: string;
+    /**
+     * Pre-rendered CREDIT-PATH SLICE (see {@link import('./proposer-slice.js')}):
+     * the REAL artifact text along each failing signal's credit path (matrix row,
+     * task block, design section), so the proposer reads the actual documents —
+     * not just quotes about them. Rendered right after EVIDENCE; omitted when empty.
+     */
+    sliceContext?: string;
     /** Injected for tests; defaults to node's spawn. */
     spawn?: typeof nodeSpawn;
     /** Override the agent binary; defaults to env or 'claude'. */
@@ -137,5 +157,26 @@ export declare function renderUnifiedDiff(relPath: string, oldContent: string, n
  * the CLI catches these and falls back to the placeholder candidate.
  */
 export declare function runCanonicalProposerAgent(input: CanonicalProposeInput): Promise<CanonicalProposeOutput>;
+/**
+ * Repair-loop variant of {@link runCanonicalProposerAgent}, used by the opt-in
+ * `--agent` path (the unidecode run's real defect: the headless proposer can
+ * fail to wrap a large markdown file as valid JSON inside the ```json:patch
+ * block, and the old blind same-prompt retry could only fail the same way).
+ *
+ * On a VALIDATION failure (`CanonicalProposerOutputInvalid` — malformed JSON,
+ * wrong block count, scope/frozen violations) it re-prompts with the concrete
+ * validation error appended, up to `maxRepairAttempts` repairs (default 2 ⇒ at
+ * most 3 parse attempts). After a successful parse it runs the cheap
+ * deterministic in-loop checks (the scope/frozen validation already ran inside
+ * the parser; a no-op diff — every edit byte-identical to the current file —
+ * is fed back as a repairable failure too, since an "edit" that changes
+ * nothing cannot drive loss down). Exhaustion throws the last error, so the
+ * CLI's existing placeholder fallback and skip-recording stay the terminal
+ * state. Invocation errors (agent crash) are NOT repaired — they propagate as
+ * before. The default `--from-edits` path never reaches this function.
+ */
+export declare function runCanonicalProposerAgentWithRepair(input: CanonicalProposeInput, opts?: {
+    maxRepairAttempts?: number;
+}): Promise<CanonicalProposeOutput>;
 export {};
 //# sourceMappingURL=proposer-agent.d.ts.map

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

@@ -98,6 +98,28 @@ export function assembleCanonicalProposerPrompt(input) {
         for (const b of benefits)
             parts.push(`- ${b}`);
     }
+    // CREDIT-PATH SLICE directly after EVIDENCE: the real artifact text along the
+    // failing path, so the evidence lines above are readable in their actual
+    // context. Omitted-when-empty (legacy hints carry no credit paths).
+    const slice = (input.sliceContext ?? '').trim();
+    if (slice.length > 0) {
+        parts.push('', '# CREDIT-PATH SLICE (real artifact text along the failing path)');
+        parts.push('Each path traces a failing signal back toward the artifact that plausibly', 'produced it (SUSPECT framing — recurrence is the confirmer). The excerpts', 'are the REAL current text at each hop.', slice);
+    }
+    // SUCCESS-CHANNEL constraints sit between EVIDENCE and the IMPROVEMENT ANGLE:
+    // the model must read what is load-bearing BEFORE an angle (especially PRUNE)
+    // commits it to deleting things. Both omitted-when-empty so prompts on runs
+    // with no green history stay byte-identical.
+    const doNotPrune = (input.doNotPrune ?? '').trim();
+    if (doNotPrune.length > 0) {
+        parts.push('', '# DO-NOT-PRUNE (load-bearing — implicated in passing runs)');
+        parts.push('The sections below are implicated in verified-PASSING runs. They must not be', 'deleted or hollowed out EVEN UNDER the PRUNE improvement angle — prune elsewhere.', doNotPrune);
+    }
+    const exemplars = (input.exemplarsContext ?? '').trim();
+    if (exemplars.length > 0) {
+        parts.push('', '# EXEMPLARS (from passing runs)');
+        parts.push(exemplars);
+    }
     const angle = (input.variantAngle ?? '').trim();
     if (angle.length > 0) {
         parts.push('', '# IMPROVEMENT ANGLE (this variant)');
@@ -215,19 +237,8 @@ async function invokeCanonicalProposer(opts) {
         return second.stdout;
     throw new CanonicalProposerInvocationError(second.stderr || first.stderr);
 }
-/**
- * Top-level: prompt the agent, parse + validate its edits, and synthesize a
- * candidate diff. Throws CanonicalProposerNoOp / *Invalid / *InvocationError —
- * the CLI catches these and falls back to the placeholder candidate.
- */
-export async function runCanonicalProposerAgent(input) {
-    const prompt = assembleCanonicalProposerPrompt(input);
-    const stdout = await invokeCanonicalProposer({
-        prompt,
-        spawn: input.spawn,
-        binary: input.binary,
-    });
-    const parsed = parseCanonicalProposerResponse(stdout, input.target.files);
+/** Shared output synthesis for the single-shot and repair-loop entry points. */
+function buildProposeOutput(input, parsed) {
     const oldByPath = new Map(input.currentFiles.map((f) => [f.relPath.replace(/\\/g, '/'), f.content]));
     const diffPatch = parsed.edits
         .map((e) => renderUnifiedDiff(e.relPath, oldByPath.get(e.relPath) ?? '', e.content))
@@ -242,4 +253,74 @@ export async function runCanonicalProposerAgent(input) {
         edits: parsed.edits,
     };
 }
+/** True when every parsed edit is byte-identical to the current on-disk file. */
+function isNoOpDiff(input, parsed) {
+    const oldByPath = new Map(input.currentFiles.map((f) => [f.relPath.replace(/\\/g, '/'), f.content]));
+    return parsed.edits.every((e) => oldByPath.get(e.relPath) === e.content);
+}
+/**
+ * Top-level: prompt the agent, parse + validate its edits, and synthesize a
+ * candidate diff. Throws CanonicalProposerNoOp / *Invalid / *InvocationError —
+ * the CLI catches these and falls back to the placeholder candidate.
+ */
+export async function runCanonicalProposerAgent(input) {
+    const prompt = assembleCanonicalProposerPrompt(input);
+    const stdout = await invokeCanonicalProposer({
+        prompt,
+        spawn: input.spawn,
+        binary: input.binary,
+    });
+    const parsed = parseCanonicalProposerResponse(stdout, input.target.files);
+    return buildProposeOutput(input, parsed);
+}
+/**
+ * Repair-loop variant of {@link runCanonicalProposerAgent}, used by the opt-in
+ * `--agent` path (the unidecode run's real defect: the headless proposer can
+ * fail to wrap a large markdown file as valid JSON inside the ```json:patch
+ * block, and the old blind same-prompt retry could only fail the same way).
+ *
+ * On a VALIDATION failure (`CanonicalProposerOutputInvalid` — malformed JSON,
+ * wrong block count, scope/frozen violations) it re-prompts with the concrete
+ * validation error appended, up to `maxRepairAttempts` repairs (default 2 ⇒ at
+ * most 3 parse attempts). After a successful parse it runs the cheap
+ * deterministic in-loop checks (the scope/frozen validation already ran inside
+ * the parser; a no-op diff — every edit byte-identical to the current file —
+ * is fed back as a repairable failure too, since an "edit" that changes
+ * nothing cannot drive loss down). Exhaustion throws the last error, so the
+ * CLI's existing placeholder fallback and skip-recording stay the terminal
+ * state. Invocation errors (agent crash) are NOT repaired — they propagate as
+ * before. The default `--from-edits` path never reaches this function.
+ */
+export async function runCanonicalProposerAgentWithRepair(input, opts = {}) {
+    const maxRepairAttempts = Math.max(0, opts.maxRepairAttempts ?? 2);
+    const basePrompt = assembleCanonicalProposerPrompt(input);
+    let feedback = null;
+    for (let attempt = 0;; attempt++) {
+        const prompt = feedback === null
+            ? basePrompt
+            : `${basePrompt}\n\n# PREVIOUS ATTEMPT FAILED VALIDATION\n${feedback}\n` +
+                'Re-emit EXACTLY ONE ```json:patch fenced block of the form ' +
+                '{"rationale": string, "edits": [{"relPath", "content"}]} — each `content` ' +
+                'is the COMPLETE new file as a single valid JSON string (escape newlines and quotes).';
+        const stdout = await invokeCanonicalProposer({
+            prompt,
+            spawn: input.spawn,
+            binary: input.binary,
+        });
+        try {
+            const parsed = parseCanonicalProposerResponse(stdout, input.target.files);
+            if (isNoOpDiff(input, parsed)) {
+                throw new CanonicalProposerOutputInvalid('every edit is byte-identical to the current file (no-op diff) — change something the evidence implicates, or return an empty edits array to decline');
+            }
+            return buildProposeOutput(input, parsed);
+        }
+        catch (err) {
+            if (err instanceof CanonicalProposerOutputInvalid && attempt < maxRepairAttempts) {
+                feedback = err.message;
+                continue;
+            }
+            throw err;
+        }
+    }
+}
 //# sourceMappingURL=proposer-agent.js.map

package/dist/core/self-evolution/proposer-slice.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Credit-path slice builder (R6): turn the hints' `creditPaths` — the neutral
+ * walker's hops with their bounded REAL artifact excerpts — into the
+ * `# CREDIT-PATH SLICE` text the proposer reads. The proposer thereby sees the
+ * actual design-section / task / matrix-row text along the failing path,
+ * instead of only quotes about it.
+ *
+ * Deterministic: hints ordered by id, hops in path order; bounded by a
+ * per-excerpt cap and a total cap so a pathological corpus cannot flood the
+ * prompt. Pure; '' when there is nothing to render (callers omit the section
+ * entirely then, matching the prompt's omitted-when-empty convention).
+ */
+import type { LearnEvolutionHint } from './learn-hints.js';
+export interface ProposerSliceCaps {
+    /** Per-excerpt character cap (default 1500). */
+    perExcerptChars: number;
+    /** Total slice character cap (default 6000). */
+    totalChars: number;
+}
+/**
+ * Build the slice text from a group's hints. Deduplicates identical paths
+ * (same node ids in the same order) across hints so recurring failures don't
+ * repeat the same design section.
+ */
+export declare function buildProposerSlice(hints: readonly LearnEvolutionHint[], caps?: Partial<ProposerSliceCaps>): string;
+//# sourceMappingURL=proposer-slice.d.ts.map

package/dist/core/self-evolution/proposer-slice.js

@@ -0,0 +1,54 @@
+const DEFAULT_CAPS = { perExcerptChars: 1500, totalChars: 6000 };
+function nodeLabel(node) {
+    const where = node.file ? ` (${node.file}${node.line ? `:${node.line}` : ''})` : '';
+    return `${node.kind} ${node.id}${where}`;
+}
+function capText(text, max) {
+    const t = text.trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+/**
+ * Render the slice for one hint's credit paths. Each hop that carries a real
+ * excerpt becomes a labeled block; hops without excerpts are listed inline.
+ */
+function renderPath(path, caps) {
+    const lines = [];
+    lines.push(`path: ${path.nodes.map(nodeLabel).join(' → ')}${path.truncatedAt ? ` [truncated: ${path.truncatedAt}]` : ''}`);
+    for (const node of path.nodes) {
+        if (!node.excerpt)
+            continue;
+        lines.push(`<<${nodeLabel(node)}>>`);
+        lines.push(capText(node.excerpt, caps.perExcerptChars));
+        lines.push('<<end>>');
+    }
+    return lines.join('\n');
+}
+/**
+ * Build the slice text from a group's hints. Deduplicates identical paths
+ * (same node ids in the same order) across hints so recurring failures don't
+ * repeat the same design section.
+ */
+export function buildProposerSlice(hints, caps = {}) {
+    const resolved = { ...DEFAULT_CAPS, ...caps };
+    const ordered = [...hints].sort((a, b) => a.id.localeCompare(b.id));
+    const seen = new Set();
+    const blocks = [];
+    let total = 0;
+    for (const hint of ordered) {
+        for (const path of hint.creditPaths ?? []) {
+            const key = path.nodes.map((n) => `${n.kind}:${n.id}`).join('→');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const block = renderPath(path, resolved);
+            if (total + block.length > resolved.totalChars) {
+                blocks.push(`(slice truncated: total cap ${resolved.totalChars} chars reached)`);
+                return blocks.join('\n\n');
+            }
+            total += block.length;
+            blocks.push(block);
+        }
+    }
+    return blocks.join('\n\n');
+}
+//# sourceMappingURL=proposer-slice.js.map