peaks-loop 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/src/services/crystallization/evidence-brief-builder.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { EvidenceBriefSchema, } from "./crystallization-types.js";
+/**
+ * EvidenceBriefBuilder — spec §4.7 / §10 RL-7.
+ *
+ * The brief is a 4-section natural-language projection that MUST
+ * accompany every user-facing recommendation. The shape guard is
+ * encoded in `EvidenceBriefSchema` (see crystallization-types.ts);
+ * this module is the LLM-side entry point that PRODUCES the brief
+ * from a finished trace + evaluator summary and the validator that
+ * REFUSES to render a recommendation payload without all 4 sections.
+ *
+ * Hard rules (mirrored from spec):
+ *
+ *   1. Every section must be a non-empty NL string (1-2 sentences
+ *      for what_happened / why_it_matters / what_learned; 1
+ *      sentence for what_action). An empty section is a hard
+ *      `MISSING_BRIEF_SECTION` error.
+ *
+ *   2. The build path is lenient on raw prose and strict on the
+ *      final shape — `buildEvidenceBrief` calls
+ *      `EvidenceBriefSchema.parse(...)` so a partial brief throws
+ *      before reaching the database.
+ *
+ *   3. `renderRecommendationPayload` refuses to return a
+ *      recommendation envelope unless the brief passes the 4-section
+ *      guard. This is the CLI's single source of truth for "may I
+ *      show this to the user?".
+ *
+ *   4. The `evaluator_summary` is a separate field on the
+ *      crystallization_event row (spec §4.5) and is NOT part of the
+ *      brief. It feeds the broader recommendation envelope.
+ *
+ * Out of scope (deferred to later slices):
+ *   - LLM-authored brief generation from live trace evidence (M8 dogfood).
+ *   - brief rewrite-on-update semantics.
+ */
+/* ---------------------------------------------------------------------- */
+/* Input shapes — the builder is the only place these normalize.          */
+/* ---------------------------------------------------------------------- */
+/**
+ * The minimum viable trace shape that the builder needs to render
+ * a brief. The trace is the EVIDENCE; the builder is format-stable
+ * so a future slice can swap in a richer trace source without
+ * editing every caller.
+ */
+export const BriefTraceInputSchema = z.object({
+    trace_id: z.string().trim().min(1).max(256),
+    /**
+     * The full NL recap of the run. Required for what_happened.
+     * 1-2 sentences is the spec guidance; the builder does not
+     * truncate, but tests passing multi-paragraph input will be
+     * warned at the Zod boundary (max 4000 chars per section).
+     */
+    what_happened: z.string().trim().min(1).max(4000),
+    /**
+     * The "why this matters" recap. Required for why_it_matters.
+     */
+    why_it_matters: z.string().trim().min(1).max(4000),
+    /**
+     * Failure-mode and preference-extraction recap. Required for
+     * what_learned.
+     */
+    what_learned: z.string().trim().min(1).max(4000),
+    /**
+     * The recommended action. Required for what_action (1
+     * sentence per spec).
+     */
+    what_action: z.string().trim().min(1).max(4000),
+    /**
+     * Optional structured bullets (e.g. "4 phases, 3 gates passed,
+     * 1 evaluator verdict"). Counts are allowed at this layer; the
+     * brief section is the NL primary (RL-7).
+     */
+    bullets: z.array(z.string().trim().min(1).max(1000)).default([]),
+    /**
+     * Source trace ids backing the brief (the column on
+     * crystallization_event spec §4.5).
+     */
+    source_trace_pointers: z
+        .array(z.string().trim().min(1).max(256))
+        .default([]),
+});
+/**
+ * The summary emitted by the independent evaluators (spec §4.5
+ * `evaluator_summary` field). Optional for the brief builder — the
+ * brief can be built without it, but a filled evaluator_summary
+ * flows into the recommendation envelope.
+ */
+export const EvaluatorSummarySchema = z.object({
+    one_liner: z.string().trim().max(1000).default(""),
+    risk_tags: z.array(z.string().trim().min(1).max(200)).default([]),
+});
+/* ---------------------------------------------------------------------- */
+/* Recommendation envelope — the CLI renders this.                       */
+/* ---------------------------------------------------------------------- */
+export const RecommendationPayloadSchema = z.object({
+    brief: EvidenceBriefSchema,
+    bullets: z.array(z.string().trim().min(1).max(1000)).default([]),
+    source_trace_pointers: z
+        .array(z.string().trim().min(1).max(256))
+        .default([]),
+    evaluator_summary: EvaluatorSummarySchema.default({
+        one_liner: "",
+        risk_tags: [],
+    }),
+});
+/* ---------------------------------------------------------------------- */
+/* Errors                                                                 */
+/* ---------------------------------------------------------------------- */
+export class BriefSectionError extends Error {
+    code = "MISSING_BRIEF_SECTION";
+    findings;
+    constructor(message, findings = []) {
+        super(message);
+        this.name = "BriefSectionError";
+        this.findings = findings;
+    }
+}
+/* ---------------------------------------------------------------------- */
+/* Builder                                                                */
+/* ---------------------------------------------------------------------- */
+/**
+ * Build a 4-section EvidenceBrief from a finished trace recap.
+ *
+ * The function is STRICT: it parses the input trace through
+ * `BriefTraceInputSchema`, then parses the assembled brief through
+ * `EvidenceBriefSchema`. Any missing section throws
+ * `BriefSectionError(MISSING_BRIEF_SECTION)` — the same code that
+ * `safeParseEvidenceBrief` returns — so a single error code is the
+ * user-facing signal for "brief incomplete, do not render".
+ *
+ * Brief-section related ZodErrors (e.g. `min(1)` on a section) are
+ * translated to `BriefSectionError` so callers only handle one
+ * shape of failure. Non-section ZodErrors (e.g. invalid `trace_id`)
+ * are re-raised unchanged.
+ *
+ * NOTE: callers who already have raw NL strings can also call
+ * `parseEvidenceBrief` directly; this function is the opinionated
+ * shape for trace -> brief.
+ */
+export function buildEvidenceBrief(trace, evaluatorSummary) {
+    let parsedTrace;
+    try {
+        parsedTrace = BriefTraceInputSchema.parse(trace);
+    }
+    catch (err) {
+        throw translateBriefZodError(err);
+    }
+    // Assemble the 4 sections verbatim from the trace recap. The Zod
+    // parser below re-asserts the 4-section guard.
+    const candidate = {
+        what_happened: parsedTrace.what_happened,
+        why_it_matters: parsedTrace.why_it_matters,
+        what_learned: parsedTrace.what_learned,
+        what_action: parsedTrace.what_action,
+    };
+    const result = EvidenceBriefSchema.safeParse(candidate);
+    if (!result.success) {
+        const findings = result.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        }));
+        throw new BriefSectionError("evidence_brief must contain all 4 sections (what_happened, why_it_matters, what_learned, what_action) with non-empty content (spec §4.7 / RL-7)", findings);
+    }
+    // Silence the unused-var lint on evaluatorSummary at this layer —
+    // the builder currently does not consume it (the brief is NL
+    // primary), but the surface is preserved for callers via
+    // `renderRecommendationPayload` below.
+    void evaluatorSummary;
+    return result.data;
+}
+/**
+ * Translate a ZodError raised on a brief-section path into a
+ * `BriefSectionError`. Non-brief errors are re-raised.
+ */
+function translateBriefZodError(err) {
+    if (err instanceof z.ZodError) {
+        const issues = err.issues;
+        const allBrief = issues.every((i) => BRIEF_SECTION_KEYS.has(i.path.join(".")));
+        if (allBrief) {
+            const findings = issues.map((i) => ({
+                path: i.path.join("."),
+                message: i.message,
+            }));
+            throw new BriefSectionError("evidence_brief must contain all 4 sections (what_happened, why_it_matters, what_learned, what_action) with non-empty content (spec §4.7 / RL-7)", findings);
+        }
+    }
+    throw err;
+}
+const BRIEF_SECTION_KEYS = new Set([
+    "what_happened",
+    "why_it_matters",
+    "what_learned",
+    "what_action",
+]);
+/**
+ * Render the user-facing recommendation envelope (brief + bullets +
+ * trace pointers + evaluator summary). The function refuses to
+ * return a payload unless ALL 4 brief sections are present — this
+ * is the single CLI-facing gate per spec §10 RL-7.
+ *
+ * On success, returns the validated `RecommendationPayload`. On a
+ * missing-section brief, throws `BriefSectionError`.
+ */
+export function renderRecommendationPayload(trace, evaluatorSummary = { one_liner: "", risk_tags: [] }) {
+    const brief = buildEvidenceBrief(trace, evaluatorSummary);
+    const payload = RecommendationPayloadSchema.parse({
+        brief,
+        bullets: trace.bullets ?? [],
+        source_trace_pointers: trace.source_trace_pointers ?? [],
+        evaluator_summary: evaluatorSummary,
+    });
+    return payload;
+}
+/**
+ * Convenience: validate an arbitrary unknown payload AS IF it were a
+ * recommendation envelope. Returns a Result-like shape so the CLI can
+ * render a structured MISSING_BRIEF_SECTION error without try/catch
+ * noise.
+ */
+export function safeRenderRecommendationPayload(input) {
+    const r = RecommendationPayloadSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, payload: r.data };
+    const findings = r.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    // Map brief failures to MISSING_BRIEF_SECTION. A failure is
+    // recognized as brief iff (a) every issue points at the brief or
+    // its sections, OR (b) the explicit refine message is present.
+    const isBrief = r.error.issues.every((i) => i.message.includes("evidence_brief must contain all 4 sections") ||
+        BRIEF_SECTION_KEYS.has(i.path.join(".")) ||
+        i.path[0] === "brief" ||
+        (i.path.length >= 2 && i.path[0] === "brief"));
+    return isBrief
+        ? { ok: false, code: "MISSING_BRIEF_SECTION", findings }
+        : { ok: false, findings };
+}

package/dist/src/services/evolution/evolution-service.d.ts

@@ -0,0 +1,137 @@
+import type Database from "better-sqlite3";
+import { ZodError } from "zod";
+import { EVOLUTION_DEFAULT_DELTA_MIN, type EvolutionEvaluation, type EvolutionProposal, type EvolutionProposalInput, type EvolutionTargetKind, type EvolutionVerdict } from "./evolution-types.js";
+/**
+ * EvolutionService — Darwin-style ratchet enforcement.
+ *
+ * Hard rules enforced at THIS layer (not just the Zod schema) so
+ * the ratchet cannot be bypassed by a malformed input:
+ *
+ *   - AC-8:  exactly one target (target_count === 1) AND
+ *            exactly one optimization dimension per round.
+ *            Code:  EVOLUTION_MULTI_OBJECT, EVOLUTION_MULTI_DIMENSION.
+ *   - AC-10: the scorer (evaluator) MUST NOT be the author.
+ *            Code:  EVOLUTION_SELF_SCORE.
+ *   - AC-11: a `keep` verdict is BLOCKED when
+ *            score_delta < score_delta_min (default 1.0).
+ *            Code:  EVOLUTION_DELTA_BELOW_THRESHOLD.
+ *   - AC-12: evaluator_id MUST be a separate agent from
+ *            author_id and skeptic_id.
+ *   - AC-14: skeptic_id MUST be a separate agent from
+ *            author_id and evaluator_id.
+ *
+ * The service is intentionally narrow: createProposal / score /
+ * markVerdict / list / get. The actual scoring agents
+ * (IndependentEvaluatorRunner, RegressionSkepticRunner) live in
+ * separate files so the author reasoning is NEVER imported into
+ * the evaluator's process boundary.
+ */
+export type EvolutionIntegrityErrorCode = "EVOLUTION_MULTI_OBJECT" | "EVOLUTION_MULTI_DIMENSION" | "EVOLUTION_SELF_SCORE" | "EVOLUTION_DELTA_BELOW_THRESHOLD" | "EVOLUTION_MISSING_USER_CONFIRMATION" | "EVOLUTION_BELOW_RUBRIC";
+export declare class EvolutionIntegrityError extends Error {
+    readonly code: EvolutionIntegrityErrorCode;
+    readonly findings: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+    constructor(code: EvolutionIntegrityErrorCode, message: string, findings?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>);
+}
+export declare class EvolutionService {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Persist a new EvolutionProposal. Enforces AC-8 (single object /
+     * single dimension) BEFORE writing the row.
+     *
+     * The proposal id is auto-generated (`eval-<hex>`); callers supply
+     * the proposal content only. The proposal's `verdict` is set to
+     * `needs-user-decision` until the score + skeptic step lands.
+     *
+     * Throws:
+     *   - ZodError if the input fails schema validation.
+     *   - EvolutionIntegrityError(EVOLUTION_MULTI_OBJECT) if
+     *     single_object !== true.
+     *   - EvolutionIntegrityError(EVOLUTION_MULTI_DIMENSION) if
+     *     single_optimization_dimension !== true.
+     */
+    createProposal(input: EvolutionProposalInput): EvolutionProposal;
+    /**
+     * Score an existing proposal. Enforces AC-10 (no self-score:
+     * `evaluator_id !== proposal.author_id`) and AC-11 (delta
+     * threshold: cannot mark `keep` when `score_delta <
+     * score_delta_min`).
+     *
+     * Returns the FINAL evaluation row with verdict derived from the
+     * evaluator + skeptic results:
+     *   - `verdict = 'revert'` if the skeptic returned a blocker.
+     *   - `verdict = 'revert'` if the score delta is below threshold.
+     *   - `verdict = 'needs-user-decision'` otherwise; the CLI
+     *     (`peaks evolution evaluate`) surfaces this to the user for
+     *     a `keep` / `revert` choice.
+     *
+     * Throws:
+     *   - EvolutionIntegrityError(EVOLUTION_SELF_SCORE) if
+     *     evaluator_id === proposal.author_id.
+     *   - EvolutionIntegrityError(EVOLUTION_DELTA_BELOW_THRESHOLD) if
+     *     a `verdict = 'keep'` is requested and the delta is below
+     *     the proposal's `score_delta_min`.
+     */
+    score(proposalId: string, args: {
+        evaluator_id: string;
+        skeptic_id: string;
+        evaluator_result: import("./evolution-types.js").IndependentEvaluatorResult;
+        skeptic_result: import("./evolution-types.js").RegressionSkepticResult;
+        brief_pointer?: string;
+        user_confirmation_pointer?: string;
+    }): EvolutionEvaluation;
+    /**
+     * Mark a verdict explicitly (after the user has confirmed via
+     * natural-language or a pick). Enforces:
+     *   - AC-11: cannot mark `keep` when score_delta <
+     *     score_delta_min.
+     *   - AC-15: `keep` requires a user_confirmation_pointer.
+     *
+     * Throws:
+     *   - EvolutionIntegrityError(EVOLUTION_DELTA_BELOW_THRESHOLD)
+     *     when `verdict = 'keep'` and the delta is below threshold.
+     *   - EvolutionIntegrityError(EVOLUTION_MISSING_USER_CONFIRMATION)
+     *     when `verdict = 'keep'` and no user_confirmation_pointer
+     *     is supplied.
+     */
+    markVerdict(proposalId: string, verdict: EvolutionVerdict, userConfirmationPointer?: string): EvolutionEvaluation | undefined;
+    /** Revert a proposal (universal recovery). Always allowed. */
+    revert(proposalId: string, userConfirmationPointer?: string): EvolutionEvaluation | undefined;
+    /** Read an evolution evaluation by id. */
+    read(proposalId: string): EvolutionEvaluation | undefined;
+    /** List evaluations for a given target. */
+    listByTarget(opts: {
+        target_kind: EvolutionTargetKind;
+        target_release_id: string;
+        verdict?: EvolutionVerdict;
+    }): EvolutionEvaluation[];
+    /**
+     * Status snapshot for `peaks evolution status`. Returns counts of
+     * evaluations by verdict for the given target, plus the latest
+     * evaluation id (if any).
+     */
+    status(target: {
+        target_kind: EvolutionTargetKind;
+        target_release_id: string;
+    }): {
+        target_kind: EvolutionTargetKind;
+        target_release_id: string;
+        total: number;
+        byVerdict: Record<EvolutionVerdict, number>;
+        latest: EvolutionEvaluation | undefined;
+    };
+}
+/**
+ * Convenience: re-export the Zod error guard.
+ */
+export declare function isZodError(err: unknown): err is ZodError;
+/**
+ * Convenience: get the default `score_delta_min` from the spec.
+ */
+export { EVOLUTION_DEFAULT_DELTA_MIN };

package/dist/src/services/evolution/evolution-service.js

@@ -0,0 +1,281 @@
+import { ZodError } from "zod";
+import { EvolutionEvaluationSchema, EvolutionProposalInputSchema, EVOLUTION_DEFAULT_DELTA_MIN, } from "./evolution-types.js";
+import { buildProposal, computeScoreDelta, ensureEvolutionEvaluationTable, getEvolutionEvaluation, insertEvolutionEvaluation, listEvolutionEvaluationsByTarget, newEvaluationId, updateEvolutionVerdict, } from "./evolution-store.js";
+export class EvolutionIntegrityError extends Error {
+    code;
+    findings;
+    constructor(code, message, findings = []) {
+        super(message);
+        this.name = "EvolutionIntegrityError";
+        this.code = code;
+        this.findings = findings;
+    }
+}
+/* ---------------------------------------------------------------------- */
+/* Service                                                                 */
+/* ---------------------------------------------------------------------- */
+export class EvolutionService {
+    db;
+    constructor(db) {
+        this.db = db;
+        // Idempotent — safe to call on every constructor invocation; the
+        // openStateDb pipeline already applied the SQL migration, but a
+        // caller-built DB (e.g. tests) needs this.
+        ensureEvolutionEvaluationTable(this.db);
+    }
+    /**
+     * Persist a new EvolutionProposal. Enforces AC-8 (single object /
+     * single dimension) BEFORE writing the row.
+     *
+     * The proposal id is auto-generated (`eval-<hex>`); callers supply
+     * the proposal content only. The proposal's `verdict` is set to
+     * `needs-user-decision` until the score + skeptic step lands.
+     *
+     * Throws:
+     *   - ZodError if the input fails schema validation.
+     *   - EvolutionIntegrityError(EVOLUTION_MULTI_OBJECT) if
+     *     single_object !== true.
+     *   - EvolutionIntegrityError(EVOLUTION_MULTI_DIMENSION) if
+     *     single_optimization_dimension !== true.
+     */
+    createProposal(input) {
+        // Parse with the input schema first (so we get defaults applied).
+        // The input schema already enforces `single_object: literal(true)`
+        // and `single_optimization_dimension: literal(true)`; we map
+        // the ZodError to EvolutionIntegrityError so the CLI / tests
+        // can assert on a single error code.
+        let parsedInput;
+        try {
+            parsedInput =
+                EvolutionProposalInputSchema.parse(input);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                const issue = err.issues[0];
+                if (issue?.path[0] === "single_object") {
+                    throw new EvolutionIntegrityError("EVOLUTION_MULTI_OBJECT", "proposal must target exactly one object (single_object=true); split multi-object changes into multiple rounds", [
+                        {
+                            path: "single_object",
+                            message: issue.message,
+                        },
+                    ]);
+                }
+                if (issue?.path[0] === "single_optimization_dimension") {
+                    throw new EvolutionIntegrityError("EVOLUTION_MULTI_DIMENSION", "proposal must declare exactly one optimization dimension (single_optimization_dimension=true); split multi-dimension changes into multiple rounds", [
+                        {
+                            path: "single_optimization_dimension",
+                            message: issue.message,
+                        },
+                    ]);
+                }
+            }
+            throw err;
+        }
+        // AC-8 defense in depth: in case a future schema version relaxes
+        // the literal(true), still enforce at the service boundary.
+        if (parsedInput.single_object !== true) {
+            throw new EvolutionIntegrityError("EVOLUTION_MULTI_OBJECT", "proposal must target exactly one object (single_object=true); split multi-object changes into multiple rounds", [{ path: "single_object", message: "must be true (AC-8)" }]);
+        }
+        if (parsedInput.single_optimization_dimension !== true) {
+            throw new EvolutionIntegrityError("EVOLUTION_MULTI_DIMENSION", "proposal must declare exactly one optimization dimension (single_optimization_dimension=true); split multi-dimension changes into multiple rounds", [
+                {
+                    path: "single_optimization_dimension",
+                    message: "must be true (AC-8)",
+                },
+            ]);
+        }
+        const id = newEvaluationId();
+        const proposal = buildProposal(id, parsedInput);
+        // Persist a stub evaluation row with verdict='needs-user-decision';
+        // the actual scoring happens in `score()` below.
+        const stub = {
+            id,
+            proposal,
+            evaluator_id: "pending",
+            skeptic_id: "pending",
+            evaluator_result: { score: parsedInput.before_score, riskTags: [], refuteParagraph: "pending" },
+            skeptic_result: {
+                driftRisks: [],
+                overfitRisks: [],
+                safetyRegressionRisks: [],
+            },
+            verdict: "needs-user-decision",
+            schema_version: "peaks.evolution/1",
+            created_at: proposal.created_at,
+        };
+        insertEvolutionEvaluation(this.db, stub);
+        return proposal;
+    }
+    /**
+     * Score an existing proposal. Enforces AC-10 (no self-score:
+     * `evaluator_id !== proposal.author_id`) and AC-11 (delta
+     * threshold: cannot mark `keep` when `score_delta <
+     * score_delta_min`).
+     *
+     * Returns the FINAL evaluation row with verdict derived from the
+     * evaluator + skeptic results:
+     *   - `verdict = 'revert'` if the skeptic returned a blocker.
+     *   - `verdict = 'revert'` if the score delta is below threshold.
+     *   - `verdict = 'needs-user-decision'` otherwise; the CLI
+     *     (`peaks evolution evaluate`) surfaces this to the user for
+     *     a `keep` / `revert` choice.
+     *
+     * Throws:
+     *   - EvolutionIntegrityError(EVOLUTION_SELF_SCORE) if
+     *     evaluator_id === proposal.author_id.
+     *   - EvolutionIntegrityError(EVOLUTION_DELTA_BELOW_THRESHOLD) if
+     *     a `verdict = 'keep'` is requested and the delta is below
+     *     the proposal's `score_delta_min`.
+     */
+    score(proposalId, args) {
+        const existing = getEvolutionEvaluation(this.db, proposalId);
+        if (!existing) {
+            throw new EvolutionIntegrityError("EVOLUTION_BELOW_RUBRIC", `evolution_evaluation row '${proposalId}' not found`, [{ path: "id", message: "row not found" }]);
+        }
+        // AC-10: scorer MUST NOT be the author.
+        if (args.evaluator_id === existing.proposal.author_id) {
+            throw new EvolutionIntegrityError("EVOLUTION_SELF_SCORE", `evaluator_id '${args.evaluator_id}' equals author_id '${existing.proposal.author_id}'; self-scoring is forbidden (AC-10)`, [{ path: "evaluator_id", message: "must differ from author_id" }]);
+        }
+        // AC-12 / AC-14: skeptic and evaluator are SEPARATE agents.
+        if (args.skeptic_id === existing.proposal.author_id) {
+            throw new EvolutionIntegrityError("EVOLUTION_SELF_SCORE", `skeptic_id '${args.skeptic_id}' equals author_id '${existing.proposal.author_id}'; the skeptic must be a separate agent (AC-14)`, [{ path: "skeptic_id", message: "must differ from author_id" }]);
+        }
+        if (args.skeptic_id === args.evaluator_id) {
+            throw new EvolutionIntegrityError("EVOLUTION_SELF_SCORE", `skeptic_id '${args.skeptic_id}' equals evaluator_id '${args.evaluator_id}'; the skeptic must be a separate agent from the evaluator (AC-12/AC-14)`, [{ path: "skeptic_id", message: "must differ from evaluator_id" }]);
+        }
+        const after_score = args.evaluator_result.score;
+        const score_delta = computeScoreDelta(existing.proposal.before_score, after_score);
+        const min = existing.proposal.score_delta_min;
+        // Derive verdict. The skeptic's `blocker` is a hard revert.
+        let verdict = "needs-user-decision";
+        if (args.skeptic_result.blocker !== undefined) {
+            verdict = "revert";
+        }
+        else if (score_delta < min) {
+            verdict = "revert";
+        }
+        const next = {
+            id: existing.id,
+            proposal: {
+                ...existing.proposal,
+                after_score,
+                score_delta,
+            },
+            evaluator_id: args.evaluator_id,
+            skeptic_id: args.skeptic_id,
+            evaluator_result: args.evaluator_result,
+            skeptic_result: args.skeptic_result,
+            verdict,
+            ...(args.brief_pointer !== undefined ? { brief_pointer: args.brief_pointer } : {}),
+            ...(args.user_confirmation_pointer !== undefined
+                ? { user_confirmation_pointer: args.user_confirmation_pointer }
+                : {}),
+            schema_version: "peaks.evolution/1",
+            created_at: new Date().toISOString(),
+        };
+        // AC-11 (delta threshold) explicit guard: if the caller
+        // explicitly asks to mark `keep` but delta < min, throw.
+        if (verdict === "needs-user-decision" && score_delta < min) {
+            // The auto-derivation already pinned verdict to `revert`; the
+            // guard is for the explicit `markVerdict('keep')` path below.
+        }
+        // Re-validate before persisting.
+        const validated = EvolutionEvaluationSchema.parse({
+            ...next,
+            score_delta,
+        });
+        // Delete + re-insert keeps the row simple; volume is tiny.
+        this.db
+            .prepare("DELETE FROM evolution_evaluation WHERE id = ?")
+            .run(existing.id);
+        insertEvolutionEvaluation(this.db, validated);
+        return validated;
+    }
+    /**
+     * Mark a verdict explicitly (after the user has confirmed via
+     * natural-language or a pick). Enforces:
+     *   - AC-11: cannot mark `keep` when score_delta <
+     *     score_delta_min.
+     *   - AC-15: `keep` requires a user_confirmation_pointer.
+     *
+     * Throws:
+     *   - EvolutionIntegrityError(EVOLUTION_DELTA_BELOW_THRESHOLD)
+     *     when `verdict = 'keep'` and the delta is below threshold.
+     *   - EvolutionIntegrityError(EVOLUTION_MISSING_USER_CONFIRMATION)
+     *     when `verdict = 'keep'` and no user_confirmation_pointer
+     *     is supplied.
+     */
+    markVerdict(proposalId, verdict, userConfirmationPointer) {
+        const existing = getEvolutionEvaluation(this.db, proposalId);
+        if (!existing)
+            return undefined;
+        if (verdict === "keep") {
+            if (existing.proposal.score_delta < existing.proposal.score_delta_min) {
+                throw new EvolutionIntegrityError("EVOLUTION_DELTA_BELOW_THRESHOLD", `score_delta ${existing.proposal.score_delta} is below score_delta_min ${existing.proposal.score_delta_min}; cannot mark keep (AC-11)`, [
+                    {
+                        path: "verdict",
+                        message: "score_delta below score_delta_min; revert instead or raise the score",
+                    },
+                ]);
+            }
+            if (userConfirmationPointer === undefined ||
+                userConfirmationPointer.trim().length === 0) {
+                throw new EvolutionIntegrityError("EVOLUTION_MISSING_USER_CONFIRMATION", "marking verdict='keep' requires a user_confirmation_pointer (AC-15)", [
+                    {
+                        path: "user_confirmation_pointer",
+                        message: "required for verdict='keep'",
+                    },
+                ]);
+            }
+        }
+        return updateEvolutionVerdict(this.db, proposalId, verdict, userConfirmationPointer);
+    }
+    /** Revert a proposal (universal recovery). Always allowed. */
+    revert(proposalId, userConfirmationPointer) {
+        return updateEvolutionVerdict(this.db, proposalId, "revert", userConfirmationPointer);
+    }
+    /** Read an evolution evaluation by id. */
+    read(proposalId) {
+        return getEvolutionEvaluation(this.db, proposalId);
+    }
+    /** List evaluations for a given target. */
+    listByTarget(opts) {
+        return listEvolutionEvaluationsByTarget(this.db, opts);
+    }
+    /**
+     * Status snapshot for `peaks evolution status`. Returns counts of
+     * evaluations by verdict for the given target, plus the latest
+     * evaluation id (if any).
+     */
+    status(target) {
+        const all = listEvolutionEvaluationsByTarget(this.db, {
+            target_kind: target.target_kind,
+            target_release_id: target.target_release_id,
+        });
+        const byVerdict = {
+            keep: 0,
+            revert: 0,
+            "needs-user-decision": 0,
+        };
+        for (const row of all)
+            byVerdict[row.verdict] += 1;
+        const latest = all.length > 0 ? all[0] : undefined;
+        return {
+            target_kind: target.target_kind,
+            target_release_id: target.target_release_id,
+            total: all.length,
+            byVerdict,
+            latest,
+        };
+    }
+}
+/**
+ * Convenience: re-export the Zod error guard.
+ */
+export function isZodError(err) {
+    return err instanceof ZodError;
+}
+/**
+ * Convenience: get the default `score_delta_min` from the spec.
+ */
+export { EVOLUTION_DEFAULT_DELTA_MIN };