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

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 };

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

@@ -0,0 +1,57 @@
+import type Database from "better-sqlite3";
+import type { EvolutionEvaluation, EvolutionEvaluationInput, EvolutionProposal, EvolutionProposalInput, EvolutionTargetKind, EvolutionVerdict } from "./evolution-types.js";
+/**
+ * Re-apply the evolution_evaluation table migration against an
+ * already-open database. Used by tests that build their own DB
+ * without the openStateDb pipeline. Idempotent.
+ */
+export declare function ensureEvolutionEvaluationTable(db: Database.Database): void;
+/**
+ * Compute the score_delta from before/after scores. Exported for
+ * the service layer to use during proposal evaluation.
+ */
+export declare function computeScoreDelta(before: number, after: number): number;
+/**
+ * Build a persisted EvolutionProposal from the input. The service
+ * layer is responsible for enforcing AC-8 (single object / single
+ * dimension) BEFORE calling this; the persisted shape always has
+ * `target_count = 1` and `dimensions.length = 1`.
+ */
+export declare function buildProposal(id: string, input: EvolutionProposalInput, createdAt?: string): EvolutionProposal;
+/**
+ * Insert a full EvolutionEvaluation row. The row's
+ * `schema_version` is taken from the input (must equal
+ * `peaks.evolution/1`); `created_at` is stamped from the server
+ * clock here, so callers cannot backdate a row.
+ */
+export declare function insertEvolutionEvaluation(db: Database.Database, evalRow: EvolutionEvaluationInput): void;
+/**
+ * Read a single EvolutionEvaluation row by id; returns undefined if
+ * absent.
+ */
+export declare function getEvolutionEvaluation(db: Database.Database, id: string): EvolutionEvaluation | undefined;
+/**
+ * List EvolutionEvaluation rows for a specific target. Filter by
+ * `verdict` to scope the listing.
+ */
+export declare function listEvolutionEvaluationsByTarget(db: Database.Database, opts: {
+    target_kind: EvolutionTargetKind;
+    target_release_id: string;
+    verdict?: EvolutionVerdict;
+}): EvolutionEvaluation[];
+/**
+ * Update the verdict (and optional user_confirmation_pointer) of
+ * an existing EvolutionEvaluation row. Returns the updated row, or
+ * undefined if the id is absent.
+ *
+ * The service layer is responsible for enforcing that the
+ * transition `revert` is always allowed and `keep` requires
+ * `user_confirmation_pointer` set (AC-15).
+ */
+export declare function updateEvolutionVerdict(db: Database.Database, id: string, verdict: EvolutionVerdict, userConfirmationPointer?: string): EvolutionEvaluation | undefined;
+/**
+ * Test seam: produce a fresh id for an EvolutionEvaluation row.
+ * Format: `eval-<hex>` (lowercase, 12 hex chars). Matches the Zod
+ * `^eval-[0-9a-f-]{8,}$` pattern in EvolutionProposalSchema.
+ */
+export declare function newEvaluationId(): string;

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

@@ -0,0 +1,232 @@
+/**
+ * Low-level SQLite access for the `evolution_evaluation` table. The
+ * migration is registered with the existing `openStateDb()` pipeline
+ * via `src/services/skillhub/migrations/005-evolution-evaluation.sql`
+ * and is applied in lexicographic order alongside the other
+ * skillhub migrations. The function `ensureEvolutionEvaluationTable`
+ * below is a belt-and-suspenders re-applier for callers that pass a
+ * database they built themselves (e.g. tests).
+ *
+ * Defense in depth:
+ *   - All JSON columns are stored as TEXT and parsed at the boundary.
+ *     No big JSON BLOB at the SQLite layer — the row stays small and
+ *     queryable.
+ *   - The migration is idempotent (CREATE TABLE IF NOT EXISTS, CREATE
+ *     INDEX IF NOT EXISTS) so re-running it is safe.
+ *   - The single-object / single-dimension / self-score / delta
+ *     rules are enforced at the SERVICE layer (not the DB); the DB
+ *     stores the persisted, validated row.
+ */
+const SCHEMA_VERSION = "peaks.evolution/1";
+/**
+ * Re-apply the evolution_evaluation table migration against an
+ * already-open database. Used by tests that build their own DB
+ * without the openStateDb pipeline. Idempotent.
+ */
+export function ensureEvolutionEvaluationTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS evolution_evaluation (
+      id                          TEXT PRIMARY KEY,
+      target_kind                 TEXT NOT NULL CHECK (target_kind IN ('loop','bee','policy','gate','evaluator')),
+      target_release_id           TEXT NOT NULL,
+      optimization_dimensions_json TEXT NOT NULL,
+      target_count                INTEGER NOT NULL DEFAULT 1 CHECK (target_count = 1),
+      before_snapshot_json        TEXT NOT NULL DEFAULT '{}',
+      after_snapshot_json         TEXT NOT NULL DEFAULT '{}',
+      diff_json                   TEXT NOT NULL DEFAULT '{}',
+      before_score                REAL NOT NULL,
+      after_score                 REAL NOT NULL,
+      score_delta_min             REAL NOT NULL DEFAULT 1.0 CHECK (score_delta_min >= 0),
+      score_delta                 REAL NOT NULL,
+      author_id                   TEXT NOT NULL,
+      evaluator_id                TEXT NOT NULL,
+      skeptic_id                  TEXT NOT NULL,
+      verdict                     TEXT NOT NULL CHECK (verdict IN ('keep','revert','needs-user-decision')),
+      user_confirmation_pointer   TEXT,
+      brief_pointer               TEXT,
+      rubric_json                 TEXT NOT NULL DEFAULT '{}',
+      red_lines_json              TEXT NOT NULL DEFAULT '[]',
+      source_traces_json          TEXT NOT NULL DEFAULT '[]',
+      schema_version              TEXT NOT NULL CHECK (schema_version = 'peaks.evolution/1'),
+      created_at                  TEXT NOT NULL,
+      CHECK (length(id) > 0)
+    );
+    CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_target
+      ON evolution_evaluation(target_kind, target_release_id);
+    CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_verdict
+      ON evolution_evaluation(verdict);
+    CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_author
+      ON evolution_evaluation(author_id);
+    CREATE INDEX IF NOT EXISTS idx_evolution_evaluation_evaluator
+      ON evolution_evaluation(evaluator_id);
+  `);
+}
+/**
+ * Compute the score_delta from before/after scores. Exported for
+ * the service layer to use during proposal evaluation.
+ */
+export function computeScoreDelta(before, after) {
+    // Round to 6 decimals to avoid floating-point noise.
+    return Math.round((after - before) * 1_000_000) / 1_000_000;
+}
+/**
+ * Build a persisted EvolutionProposal from the input. The service
+ * layer is responsible for enforcing AC-8 (single object / single
+ * dimension) BEFORE calling this; the persisted shape always has
+ * `target_count = 1` and `dimensions.length = 1`.
+ */
+export function buildProposal(id, input, createdAt) {
+    const before = input.before_score;
+    const after = input.after_score;
+    return {
+        id,
+        target_kind: input.target_kind,
+        target_release_id: input.target_release_id,
+        optimization_dimension: input.optimization_dimension,
+        dimensions: [input.optimization_dimension],
+        target_count: 1,
+        single_object: true,
+        single_optimization_dimension: true,
+        before_snapshot: input.before_snapshot ?? {},
+        after_snapshot: input.after_snapshot ?? {},
+        diff: input.diff ?? {},
+        before_score: before,
+        after_score: after,
+        score_delta_min: input.score_delta_min ?? 1,
+        score_delta: computeScoreDelta(before, after),
+        author_id: input.author_id,
+        rubric: input.rubric ?? {},
+        red_lines: input.red_lines ?? [],
+        source_traces: input.source_traces ?? [],
+        schema_version: SCHEMA_VERSION,
+        created_at: createdAt ?? new Date().toISOString(),
+    };
+}
+function rowToEvaluation(row) {
+    return {
+        id: row.id,
+        proposal: {
+            id: row.id,
+            target_kind: row.target_kind,
+            target_release_id: row.target_release_id,
+            optimization_dimension: JSON.parse(row.optimization_dimensions_json)[0],
+            dimensions: JSON.parse(row.optimization_dimensions_json),
+            target_count: row.target_count,
+            single_object: true,
+            single_optimization_dimension: true,
+            before_snapshot: JSON.parse(row.before_snapshot_json),
+            after_snapshot: JSON.parse(row.after_snapshot_json),
+            diff: JSON.parse(row.diff_json),
+            before_score: row.before_score,
+            after_score: row.after_score,
+            score_delta_min: row.score_delta_min,
+            score_delta: row.score_delta,
+            author_id: row.author_id,
+            rubric: JSON.parse(row.rubric_json),
+            red_lines: JSON.parse(row.red_lines_json),
+            source_traces: JSON.parse(row.source_traces_json),
+            schema_version: row.schema_version,
+            created_at: row.created_at,
+        },
+        evaluator_id: row.evaluator_id,
+        skeptic_id: row.skeptic_id,
+        evaluator_result: {
+            // We persist the final post-skeptic row only; the raw
+            // evaluator_result is not part of the row. Tests can verify
+            // the verdict derivation via the service layer.
+            score: row.after_score,
+            riskTags: [],
+            refuteParagraph: "",
+        },
+        skeptic_result: {
+            driftRisks: [],
+            overfitRisks: [],
+            safetyRegressionRisks: [],
+        },
+        verdict: row.verdict,
+        user_confirmation_pointer: row.user_confirmation_pointer ?? undefined,
+        brief_pointer: row.brief_pointer ?? undefined,
+        schema_version: row.schema_version,
+        created_at: row.created_at,
+        score_delta: row.score_delta,
+    };
+}
+/**
+ * Insert a full EvolutionEvaluation row. The row's
+ * `schema_version` is taken from the input (must equal
+ * `peaks.evolution/1`); `created_at` is stamped from the server
+ * clock here, so callers cannot backdate a row.
+ */
+export function insertEvolutionEvaluation(db, evalRow) {
+    const stmt = db.prepare(`INSERT INTO evolution_evaluation (
+       id, target_kind, target_release_id, optimization_dimensions_json,
+       target_count, before_snapshot_json, after_snapshot_json, diff_json,
+       before_score, after_score, score_delta_min, score_delta,
+       author_id, evaluator_id, skeptic_id, verdict,
+       user_confirmation_pointer, brief_pointer,
+       rubric_json, red_lines_json, source_traces_json,
+       schema_version, created_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    stmt.run(evalRow.id, evalRow.proposal.target_kind, evalRow.proposal.target_release_id, JSON.stringify(evalRow.proposal.dimensions), evalRow.proposal.target_count, JSON.stringify(evalRow.proposal.before_snapshot), JSON.stringify(evalRow.proposal.after_snapshot), JSON.stringify(evalRow.proposal.diff), evalRow.proposal.before_score, evalRow.proposal.after_score, evalRow.proposal.score_delta_min, computeScoreDelta(evalRow.proposal.before_score, evalRow.proposal.after_score), evalRow.proposal.author_id, evalRow.evaluator_id, evalRow.skeptic_id, evalRow.verdict, evalRow.user_confirmation_pointer ?? null, evalRow.brief_pointer ?? null, JSON.stringify(evalRow.proposal.rubric), JSON.stringify(evalRow.proposal.red_lines), JSON.stringify(evalRow.proposal.source_traces), evalRow.schema_version, evalRow.created_at);
+}
+/**
+ * Read a single EvolutionEvaluation row by id; returns undefined if
+ * absent.
+ */
+export function getEvolutionEvaluation(db, id) {
+    const row = db
+        .prepare("SELECT * FROM evolution_evaluation WHERE id = ?")
+        .get(id);
+    if (!row)
+        return undefined;
+    return rowToEvaluation(row);
+}
+/**
+ * List EvolutionEvaluation rows for a specific target. Filter by
+ * `verdict` to scope the listing.
+ */
+export function listEvolutionEvaluationsByTarget(db, opts) {
+    const params = [opts.target_kind, opts.target_release_id];
+    let sql = "SELECT * FROM evolution_evaluation WHERE target_kind = ? AND target_release_id = ?";
+    if (opts.verdict) {
+        sql += " AND verdict = ?";
+        params.push(opts.verdict);
+    }
+    sql += " ORDER BY created_at DESC, id ASC";
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToEvaluation);
+}
+/**
+ * Update the verdict (and optional user_confirmation_pointer) of
+ * an existing EvolutionEvaluation row. Returns the updated row, or
+ * undefined if the id is absent.
+ *
+ * The service layer is responsible for enforcing that the
+ * transition `revert` is always allowed and `keep` requires
+ * `user_confirmation_pointer` set (AC-15).
+ */
+export function updateEvolutionVerdict(db, id, verdict, userConfirmationPointer) {
+    const existing = getEvolutionEvaluation(db, id);
+    if (!existing)
+        return undefined;
+    const stmt = db.prepare(`UPDATE evolution_evaluation
+       SET verdict = ?,
+           user_confirmation_pointer = ?
+     WHERE id = ?`);
+    stmt.run(verdict, userConfirmationPointer ?? null, id);
+    return getEvolutionEvaluation(db, id);
+}
+/**
+ * Test seam: produce a fresh id for an EvolutionEvaluation row.
+ * Format: `eval-<hex>` (lowercase, 12 hex chars). Matches the Zod
+ * `^eval-[0-9a-f-]{8,}$` pattern in EvolutionProposalSchema.
+ */
+export function newEvaluationId() {
+    // 12-char hex, lowercase, no dashes — the regex allows '-' so
+    // 12-char hex is fine. We avoid UUID's dashes to keep ids
+    // grep-friendly.
+    const hex = Math.floor(Math.random() * 0x1_000_000_000_000)
+        .toString(16)
+        .padStart(12, "0");
+    return `eval-${hex}`;
+}