agentic-qe 3.11.5 → 3.12.1

package/dist/learning/qe-flywheel/coupled-anchor.js

@@ -0,0 +1,181 @@
+/**
+ * Coupled anchor scorer — retrieval → test-gen → anchor (ADR-118 / ADR-117).
+ *
+ * In the retrieval-only wiring the anchor was policy-INDEPENDENT (a flat guard):
+ * the retrieval policy didn't feed test generation, so it couldn't move the
+ * oracle score, and the no-regression guard was inert. This closes that loop:
+ *
+ *   retrieve(inputUnderTest, policy) → few-shot examples
+ *       → generate(inputUnderTest, examples) → a test
+ *           → evaluateOracle(referenceImpl, test) → mutation kill rate
+ *
+ * Now `anchorMean` VARIES with the retrieval policy — a policy that surfaces
+ * more useful examples yields better generated tests and a higher oracle score.
+ * The guard gets teeth: a candidate that games the cheap self-retrieval proxy
+ * but produces WORSE tests drops the anchor mean and is rejected (ADR-117
+ * no-regression), and the promotion is now genuinely oracle:test-exec-backed
+ * (ADR-121) rather than a framing stretch.
+ *
+ * `retrieve` and `generate` are injected seams: fake/deterministic in tests,
+ * a real policy-weighted DB retriever + an LLM test generator in production
+ * (the LLM step is the metered part — bind it deliberately).
+ */
+import { computeRealEmbedding } from '../real-embeddings.js';
+import { evaluateOracle } from '../../validation/oracle-eval.js';
+import { loadAnchorSet, anchorMean as meanOf } from '../../validation/anchor-set.js';
+import { createCorpusScorer } from './corpus-scorer.js';
+const DEFAULT_ANCHOR_PATH = new URL('../../../verification/anchors/qe-anchor-v1.json', import.meta.url).pathname;
+/**
+ * Build the coupled anchorMean scorer: `(policy) => Promise<number>`.
+ * Grades each frozen anchor item by generating a test from policy-retrieved
+ * examples and scoring its mutation kill rate. The anchor now moves with the
+ * policy.
+ */
+export function createCoupledAnchorScorer(opts) {
+    const anchor = loadAnchorSet(opts.anchorPath ?? DEFAULT_ANCHOR_PATH);
+    const threshold = opts.threshold ?? 0.8;
+    return async (policy) => {
+        const scores = [];
+        for (const item of anchor.items) {
+            const examples = await opts.retrieve(item.inputUnderTest, policy);
+            const generatedTest = await opts.generate(item.inputUnderTest, examples);
+            const result = evaluateOracle({
+                moduleName: item.moduleName,
+                referenceImpl: item.referenceImpl,
+                generatedTest,
+                threshold,
+                maxMutants: opts.maxMutants,
+            });
+            scores.push(result.mutationScore);
+        }
+        return meanOf(scores);
+    };
+}
+/**
+ * A full PolicyScorer where `heldOut` is the cheap self-retrieval proxy (train
+ * signal) and `anchorMean` is the COUPLED oracle test-gen quality (the guard
+ * that now moves). The flywheel's accept() then requires a proxy gain WITHOUT an
+ * oracle-quality regression — the proxy-overfitting veto ADR-117 exists for.
+ */
+export function createCoupledScorer(opts) {
+    const heldOutScorer = createCorpusScorer({ db: opts.db, anchorPath: opts.anchorPath, heldOutRatio: opts.heldOutRatio });
+    const anchorScorer = createCoupledAnchorScorer(opts);
+    return async (policy) => {
+        // heldOut comes from the corpus scorer (its own anchorMean is the flat guard
+        // and is discarded here — the coupled anchor replaces it).
+        const heldOut = (await heldOutScorer(policy)).heldOut;
+        const anchorMean = await anchorScorer(policy);
+        return { heldOut, anchorMean };
+    };
+}
+/**
+ * A real policy-weighted DB retriever over `qe_patterns` — token overlap on the
+ * query, scaled by the policy's body/subject weights, top-K by score. Read-only.
+ * Injected as `retrieve` for live runs; tests use a deterministic fake instead.
+ */
+export function createDbRetriever(db, topK = 3) {
+    const rows = db.prepare(`SELECT id, name, COALESCE(description,'') AS body FROM qe_patterns WHERE deprecated_at IS NULL`).all();
+    const toks = (s) => new Set(s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+    const docs = rows.map((r) => ({ ...r, nameToks: toks(r.name), bodyToks: toks(r.body) }));
+    return (query, policy) => {
+        const q = toks(query);
+        const scored = docs.map((d) => {
+            let s = 0;
+            for (const t of q) {
+                if (d.bodyToks.has(t))
+                    s += policy.alpha * policy.bodyWeight;
+                if (d.nameToks.has(t))
+                    s += (1 - policy.alpha) * policy.subjectWeight;
+            }
+            return { d, s };
+        });
+        return scored
+            .sort((a, b) => b.s - a.s || a.d.id.localeCompare(b.d.id))
+            .slice(0, topK)
+            .map(({ d }) => ({ id: d.id, name: d.name, body: d.body }));
+    };
+}
+// ---------------------------------------------------------------------------
+// Semantic retriever — policy-sensitive retrieval over real pattern embeddings
+// ---------------------------------------------------------------------------
+/** Cosine similarity of two equal-length vectors. */
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const d = Math.sqrt(na * nb);
+    return d === 0 ? 0 : dot / d;
+}
+/**
+ * Policy-sensitive SEMANTIC retriever over the pre-computed `qe_pattern_embeddings`
+ * (all-MiniLM-L6-v2). Fixes the lexical retriever's honest-null: the anchor
+ * queries (toy functions) have ~0 lexical overlap with the corpus, so lexical
+ * scores were identical for every policy. Cosine similarity is a real, varying
+ * signal, and the policy re-shapes retrieval three ways:
+ *   - `alpha` blends semantic cosine vs lexical overlap,
+ *   - `subjectWeight`/`bodyWeight` scale the lexical component,
+ *   - `mmrLambda` trades relevance for diversity in a greedy MMR rerank
+ *     (this is the lever that reorders even when lexical overlap is 0).
+ * Query embeddings are cached (same query across policies embeds once).
+ */
+export function createSemanticRetriever(opts) {
+    const embed = opts.embed ?? ((t) => computeRealEmbedding(t));
+    const topK = opts.topK ?? 3;
+    const rows = opts.db.prepare(`SELECT p.id AS id, p.name AS name, COALESCE(p.description,'') AS body,
+            e.embedding AS embedding, e.dimension AS dimension
+       FROM qe_patterns p JOIN qe_pattern_embeddings e ON e.pattern_id = p.id
+      WHERE p.deprecated_at IS NULL`).all();
+    const toks = (s) => new Set(s.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+    const docs = rows.map((r) => ({
+        id: r.id, name: r.name, body: r.body,
+        vec: new Float32Array(r.embedding.buffer, r.embedding.byteOffset, r.dimension),
+        nameToks: toks(r.name), bodyToks: toks(r.body),
+    }));
+    const queryCache = new Map();
+    return async (query, policy) => {
+        if (docs.length === 0)
+            return [];
+        let qv = queryCache.get(query);
+        if (!qv) {
+            qv = new Float32Array(await embed(query));
+            queryCache.set(query, qv);
+        }
+        const q = toks(query);
+        // relevance = alpha * semantic-cosine + (1-alpha) * weighted-lexical-overlap
+        const scored = docs.map((d) => {
+            const sem = cosine(qv, d.vec);
+            let lex = 0;
+            for (const t of q) {
+                if (d.bodyToks.has(t))
+                    lex += policy.bodyWeight;
+                if (d.nameToks.has(t))
+                    lex += policy.subjectWeight;
+            }
+            lex = lex / Math.max(1, q.size); // normalize to a comparable scale
+            return { d, rel: policy.alpha * sem + (1 - policy.alpha) * lex };
+        });
+        // greedy MMR rerank: mmrLambda trades relevance vs diversity (cosine between
+        // candidate embeddings). This reorders retrieval as the policy changes even
+        // when the lexical term is zero.
+        const lambda = policy.mmrLambda;
+        const remaining = scored.slice().sort((a, b) => b.rel - a.rel || a.d.id.localeCompare(b.d.id));
+        const chosen = [];
+        while (remaining.length > 0 && chosen.length < topK) {
+            let bestIdx = 0, bestScore = -Infinity;
+            for (let i = 0; i < remaining.length; i++) {
+                const sim = chosen.length === 0 ? 0 : Math.max(...chosen.map((c) => cosine(remaining[i].d.vec, c.d.vec)));
+                const mmr = lambda * remaining[i].rel - (1 - lambda) * sim;
+                if (mmr > bestScore || (mmr === bestScore && remaining[i].d.id.localeCompare(remaining[bestIdx].d.id) < 0)) {
+                    bestScore = mmr;
+                    bestIdx = i;
+                }
+            }
+            chosen.push(remaining.splice(bestIdx, 1)[0]);
+        }
+        return chosen.map(({ d }) => ({ id: d.id, name: d.name, body: d.body }));
+    };
+}
+//# sourceMappingURL=coupled-anchor.js.map

package/dist/learning/qe-flywheel/generation.d.ts

@@ -0,0 +1,121 @@
+/**
+ * QE-policy flywheel — the generational loop (ADR-118).
+ *
+ * One generation: score the baseline champion and a candidate, seal the decision
+ * inputs, re-execute the FROZEN accept() rule (ADR-120 `accept/v1`: held-out
+ * beats baseline ∧ anchor no-regression (ADR-117) ∧ oracle tier (ADR-121)),
+ * and emit an Ed25519-signed receipt into an append-only lineage. Promotions
+ * compound: each generation re-bases on the previous promoted champion.
+ *
+ * The corpus SCORER is injected — harvesting `qe_patterns` and running retrieval
+ * + grading the anchor is the DB/model-touching part, wired separately. This
+ * keeps the loop, gate, receipts, and lineage fully testable and deterministic.
+ *
+ * Honest-null (ADR-234): a generation — or a whole run — that promotes NOTHING
+ * is a correct, valid, replayable outcome, not a failure.
+ */
+import type { RetrievalPolicy } from './policy.js';
+import { type EvolveReceipt, type Signer } from './receipt.js';
+/** Scores for a policy on the harvested corpus + the frozen anchor. */
+export interface PolicyScores {
+    /** Self-retrieval on the held-out split (the train/serve signal — never the accept signal alone). */
+    heldOut: number;
+    /** Mean over the ADR-117 frozen anchor items (the no-regression signal). */
+    anchorMean: number;
+}
+/** Injected: evaluate a policy → its held-out + anchor scores. */
+export type PolicyScorer = (policy: RetrievalPolicy) => PolicyScores | Promise<PolicyScores>;
+export interface HeadroomResult {
+    hasHeadroom: boolean;
+    baselineHeldOut: number;
+    baselineAnchorMean: number;
+    reason: string;
+}
+/**
+ * ADR-118 §1 headroom precondition. If the baseline already saturates the
+ * held-out signal, the loop must NOT run — it would spend compute for
+ * structurally-zero promotions (the MetaHarness SWE-bench null).
+ */
+export declare function checkHeadroom(baseline: RetrievalPolicy, scorer: PolicyScorer, saturation?: number): Promise<HeadroomResult>;
+export interface GenerationInput {
+    generation: number;
+    baseline: RetrievalPolicy;
+    candidate: RetrievalPolicy;
+    scorer: PolicyScorer;
+    /** ADR-117 frozen anchor content hash (which anchor was graded). */
+    anchorHash: string;
+    /** No-regression tolerance (ADR-117 sign-off: 0.0). */
+    anchorTol: number;
+    /** Provenance tier of the corpus evidence (ADR-121). Only oracle-tier promotes. */
+    provenanceTier?: string;
+    /** Whether judge-tier promotion is explicitly budgeted (ADR-121). */
+    allowJudgeTier?: boolean;
+    signer: Signer;
+    /** Frozen rule version (default 'accept/v1'). */
+    ruleVersion?: string;
+}
+export interface GenerationResult {
+    generation: number;
+    verdict: 'promote' | 'reject';
+    baselinePolicyId: string;
+    candidatePolicyId: string;
+    scores: {
+        baseline: PolicyScores;
+        candidate: PolicyScores;
+    };
+    receipt: EvolveReceipt;
+    /** The champion AFTER this generation: candidate if promoted, else baseline unchanged. */
+    champion: RetrievalPolicy;
+}
+/**
+ * Run one flywheel generation. Deterministic given the scorer and signer seed.
+ * Never mutates fleet state — it returns the verdict + a signed receipt; serving
+ * the champion is a separate, reversible step (serveChampion / rollback).
+ */
+export declare function runFlywheelGeneration(input: GenerationInput): Promise<GenerationResult>;
+export interface LineageResult {
+    /** Number of PROMOTED generations. */
+    promotions: number;
+    /** Every promoted child re-based on its parent's promoted candidate (compounding). */
+    lineageIntact: boolean;
+    /** Every receipt's signature verifies AND its frozen gate re-executes to the recorded verdict. */
+    allReplayable: boolean;
+    reason: string;
+}
+/**
+ * Reconstruct + validate a lineage from an ordered receipt list (ADR-118 §4).
+ * Proves the chain compounds and every step is replayable — the property that
+ * makes a stub unable to launder a regression (a forged promote fails
+ * verifyPromotion; a broken chain fails lineageIntact).
+ */
+export declare function reconstructLineage(receipts: EvolveReceipt[]): LineageResult;
+export interface ActivePolicy {
+    current: RetrievalPolicy;
+    currentId: string;
+    /** Rollback target — the policy served before `current`. */
+    previous: RetrievalPolicy | null;
+    previousId: string | null;
+    generation: number;
+}
+/** Initialize the active pointer at the gen-0 root policy. */
+export declare function initActivePolicy(root: RetrievalPolicy): ActivePolicy;
+/**
+ * Serve a newly-promoted champion, shifting the old current into `previous` as
+ * the rollback target (serve-then-shadow: the new policy is served, the old is
+ * retained one generation for the canary to fall back to).
+ */
+export declare function serveChampion(active: ActivePolicy, champion: RetrievalPolicy, generation: number): ActivePolicy;
+/** Roll the active pointer back to its previous policy (drift-canary auto-rollback). */
+export declare function rollback(active: ActivePolicy): ActivePolicy;
+export interface DriftCanaryResult {
+    drifted: boolean;
+    reason: string;
+}
+/**
+ * Drift canary (ADR-118 §5, ruflo `:259-302`): re-score the served champion
+ * against its predecessor on a FRESH harvest; if EITHER the held-out or the
+ * anchor score drops below the predecessor, the promotion regressed in
+ * production and must be rolled back.
+ */
+export declare function checkDriftCanary(served: PolicyScores, predecessor: PolicyScores, tol?: number): DriftCanaryResult;
+//# sourceMappingURL=generation.d.ts.map

package/dist/learning/qe-flywheel/generation.js

@@ -0,0 +1,167 @@
+/**
+ * QE-policy flywheel — the generational loop (ADR-118).
+ *
+ * One generation: score the baseline champion and a candidate, seal the decision
+ * inputs, re-execute the FROZEN accept() rule (ADR-120 `accept/v1`: held-out
+ * beats baseline ∧ anchor no-regression (ADR-117) ∧ oracle tier (ADR-121)),
+ * and emit an Ed25519-signed receipt into an append-only lineage. Promotions
+ * compound: each generation re-bases on the previous promoted champion.
+ *
+ * The corpus SCORER is injected — harvesting `qe_patterns` and running retrieval
+ * + grading the anchor is the DB/model-touching part, wired separately. This
+ * keeps the loop, gate, receipts, and lineage fully testable and deterministic.
+ *
+ * Honest-null (ADR-234): a generation — or a whole run — that promotes NOTHING
+ * is a correct, valid, replayable outcome, not a failure.
+ */
+import { DEFAULT_PROVENANCE_TIER } from '../provenance-tier.js';
+import { reExecuteGate, gateFingerprint, sealedHash, verifyPromotion, } from '../../validation/gate-reexecute.js';
+import { policyId } from './policy.js';
+import { signReceipt, verifyReceiptSignature, toPromotionReceipt, } from './receipt.js';
+/**
+ * ADR-118 §1 headroom precondition. If the baseline already saturates the
+ * held-out signal, the loop must NOT run — it would spend compute for
+ * structurally-zero promotions (the MetaHarness SWE-bench null).
+ */
+export async function checkHeadroom(baseline, scorer, saturation = 0.999) {
+    const s = await scorer(baseline);
+    const hasHeadroom = s.heldOut < saturation;
+    return {
+        hasHeadroom,
+        baselineHeldOut: s.heldOut,
+        baselineAnchorMean: s.anchorMean,
+        reason: hasHeadroom
+            ? `baseline held-out ${s.heldOut.toFixed(4)} < saturation ${saturation} — headroom exists`
+            : `baseline held-out ${s.heldOut.toFixed(4)} >= saturation ${saturation} — no headroom, loop must not run`,
+    };
+}
+/**
+ * Run one flywheel generation. Deterministic given the scorer and signer seed.
+ * Never mutates fleet state — it returns the verdict + a signed receipt; serving
+ * the champion is a separate, reversible step (serveChampion / rollback).
+ */
+export async function runFlywheelGeneration(input) {
+    const ruleVersion = input.ruleVersion ?? 'accept/v1';
+    const provenanceTier = input.provenanceTier ?? DEFAULT_PROVENANCE_TIER;
+    const baselineScores = await input.scorer(input.baseline);
+    const candidateScores = await input.scorer(input.candidate);
+    const sealed = {
+        candidateHeldOut: candidateScores.heldOut,
+        baselineHeldOut: baselineScores.heldOut,
+        candidateAnchorMean: candidateScores.anchorMean,
+        baselineAnchorMean: baselineScores.anchorMean,
+        anchorHash: input.anchorHash,
+        anchorTol: input.anchorTol,
+        provenanceTier,
+        allowJudgeTier: input.allowJudgeTier,
+    };
+    const ruleResult = reExecuteGate(ruleVersion, sealed);
+    const verdict = ruleResult.promote ? 'promote' : 'reject';
+    const baselinePolicyId = policyId(input.baseline);
+    const candidatePolicyId = policyId(input.candidate);
+    const receipt = signReceipt({
+        generation: input.generation,
+        ruleVersion,
+        ruleFingerprint: gateFingerprint(ruleVersion),
+        sealed,
+        sealedHash: sealedHash(sealed),
+        verdict,
+        baselinePolicyId,
+        candidatePolicyId,
+        signerKeyId: input.signer.keyId,
+        publicKeyPem: input.signer.publicKeyPem,
+    }, input.signer);
+    return {
+        generation: input.generation,
+        verdict,
+        baselinePolicyId,
+        candidatePolicyId,
+        scores: { baseline: baselineScores, candidate: candidateScores },
+        receipt,
+        champion: verdict === 'promote' ? input.candidate : input.baseline,
+    };
+}
+/**
+ * Reconstruct + validate a lineage from an ordered receipt list (ADR-118 §4).
+ * Proves the chain compounds and every step is replayable — the property that
+ * makes a stub unable to launder a regression (a forged promote fails
+ * verifyPromotion; a broken chain fails lineageIntact).
+ */
+export function reconstructLineage(receipts) {
+    let promotions = 0;
+    let lineageIntact = true;
+    let allReplayable = true;
+    let lastPromotedCandidate = null;
+    for (const r of receipts) {
+        // Replayability: signature + frozen-rule re-execution (ADR-120).
+        if (!verifyReceiptSignature(r))
+            allReplayable = false;
+        const replay = verifyPromotion(toPromotionReceipt(r));
+        if (!replay.valid)
+            allReplayable = false;
+        if (r.verdict === 'promote') {
+            // A promoted generation must re-base on the previous promoted champion.
+            if (lastPromotedCandidate !== null && r.baselinePolicyId !== lastPromotedCandidate) {
+                lineageIntact = false;
+            }
+            lastPromotedCandidate = r.candidatePolicyId;
+            promotions++;
+        }
+    }
+    return {
+        promotions,
+        lineageIntact,
+        allReplayable,
+        reason: `${promotions} promotion(s); lineage ${lineageIntact ? 'intact' : 'BROKEN'}; `
+            + `${allReplayable ? 'all replayable' : 'NOT all replayable'}`,
+    };
+}
+/** Initialize the active pointer at the gen-0 root policy. */
+export function initActivePolicy(root) {
+    return { current: root, currentId: policyId(root), previous: null, previousId: null, generation: 0 };
+}
+/**
+ * Serve a newly-promoted champion, shifting the old current into `previous` as
+ * the rollback target (serve-then-shadow: the new policy is served, the old is
+ * retained one generation for the canary to fall back to).
+ */
+export function serveChampion(active, champion, generation) {
+    return {
+        current: champion,
+        currentId: policyId(champion),
+        previous: active.current,
+        previousId: active.currentId,
+        generation,
+    };
+}
+/** Roll the active pointer back to its previous policy (drift-canary auto-rollback). */
+export function rollback(active) {
+    if (active.previous === null)
+        return active; // nothing to roll back to
+    return {
+        current: active.previous,
+        currentId: active.previousId,
+        previous: null,
+        previousId: null,
+        generation: active.generation,
+    };
+}
+/**
+ * Drift canary (ADR-118 §5, ruflo `:259-302`): re-score the served champion
+ * against its predecessor on a FRESH harvest; if EITHER the held-out or the
+ * anchor score drops below the predecessor, the promotion regressed in
+ * production and must be rolled back.
+ */
+export function checkDriftCanary(served, predecessor, tol = 0) {
+    const heldOutDrift = served.heldOut < predecessor.heldOut - tol;
+    const anchorDrift = served.anchorMean < predecessor.anchorMean - tol;
+    const drifted = heldOutDrift || anchorDrift;
+    return {
+        drifted,
+        reason: drifted
+            ? `drift detected: ${heldOutDrift ? `held-out ${served.heldOut.toFixed(4)}<${predecessor.heldOut.toFixed(4)} ` : ''}`
+                + `${anchorDrift ? `anchor ${served.anchorMean.toFixed(4)}<${predecessor.anchorMean.toFixed(4)}` : ''}`.trim()
+            : 'served champion holds vs predecessor — no rollback',
+    };
+}
+//# sourceMappingURL=generation.js.map

package/dist/learning/qe-flywheel/policy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Retrieval policy — the hyperparameters the QE-policy flywheel tunes (ADR-118).
+ *
+ * The flywheel optimizes AQE's hybrid retrieval/selection policy over
+ * `qe_patterns` (the ruflo RetrievalConfig shape), one generation at a time,
+ * behind the frozen accept() gate. This module defines the policy and the
+ * candidate proposal; it does NOT touch the DB or evaluate anything (the scorer
+ * is injected in generation.ts).
+ */
+/** The tunable hybrid-retrieval hyperparameters. */
+export interface RetrievalPolicy {
+    /** Dense/sparse blend weight [0,1]. */
+    alpha: number;
+    /** Weight on subject/title token match. */
+    subjectWeight: number;
+    /** Weight on body/content token match. */
+    bodyWeight: number;
+    /** MMR diversity vs relevance tradeoff [0,1]. */
+    mmrLambda: number;
+    /** Penalty factor for pattern-type mismatch [0,1]. */
+    typePenaltyFactor: number;
+}
+/** ADR-082 defaults — the gen-0 root policy. */
+export declare const DEFAULT_POLICY: RetrievalPolicy;
+/**
+ * Stable id of a policy — canonical (sorted-key, fixed-precision) hash. Two
+ * numerically-equal policies get the same id, so lineage links are exact.
+ */
+export declare function policyId(p: RetrievalPolicy): string;
+/**
+ * Propose candidate policies around a baseline — a coarse ±step grid, one axis
+ * moved at a time (plus a floor of exploration on every axis). Later generations
+ * can bias this toward historically-effective axes (ruflo `biasedGrid`), but the
+ * gate is what makes any proposal safe, so a simple grid is a fine start.
+ */
+export declare function proposeCandidates(baseline: RetrievalPolicy, step?: number): RetrievalPolicy[];
+//# sourceMappingURL=policy.d.ts.map

package/dist/learning/qe-flywheel/policy.js

@@ -0,0 +1,66 @@
+/**
+ * Retrieval policy — the hyperparameters the QE-policy flywheel tunes (ADR-118).
+ *
+ * The flywheel optimizes AQE's hybrid retrieval/selection policy over
+ * `qe_patterns` (the ruflo RetrievalConfig shape), one generation at a time,
+ * behind the frozen accept() gate. This module defines the policy and the
+ * candidate proposal; it does NOT touch the DB or evaluate anything (the scorer
+ * is injected in generation.ts).
+ */
+import { createHash } from 'node:crypto';
+/** ADR-082 defaults — the gen-0 root policy. */
+export const DEFAULT_POLICY = {
+    alpha: 0.5,
+    subjectWeight: 1.0,
+    bodyWeight: 1.0,
+    mmrLambda: 0.5,
+    typePenaltyFactor: 0.1,
+};
+const AXES = ['alpha', 'subjectWeight', 'bodyWeight', 'mmrLambda', 'typePenaltyFactor'];
+/** Clamp helper — keep weights in sane bounds so candidates stay well-formed. */
+function clamp(v, lo, hi) {
+    return Math.min(hi, Math.max(lo, v));
+}
+const BOUNDS = {
+    alpha: [0, 1],
+    subjectWeight: [0, 4],
+    bodyWeight: [0, 4],
+    mmrLambda: [0, 1],
+    typePenaltyFactor: [0, 1],
+};
+/**
+ * Stable id of a policy — canonical (sorted-key, fixed-precision) hash. Two
+ * numerically-equal policies get the same id, so lineage links are exact.
+ */
+export function policyId(p) {
+    const canon = AXES.map((k) => `${k}:${p[k].toFixed(6)}`).join('|');
+    return createHash('sha256').update(canon).digest('hex').slice(0, 16);
+}
+/**
+ * Propose candidate policies around a baseline — a coarse ±step grid, one axis
+ * moved at a time (plus a floor of exploration on every axis). Later generations
+ * can bias this toward historically-effective axes (ruflo `biasedGrid`), but the
+ * gate is what makes any proposal safe, so a simple grid is a fine start.
+ */
+export function proposeCandidates(baseline, step = 0.1) {
+    const out = [];
+    for (const axis of AXES) {
+        for (const dir of [-1, 1]) {
+            const [lo, hi] = BOUNDS[axis];
+            const moved = clamp(baseline[axis] + dir * step, lo, hi);
+            if (moved === baseline[axis])
+                continue; // no-op at a bound
+            out.push({ ...baseline, [axis]: moved });
+        }
+    }
+    // de-dup by id (a bound can collapse two moves)
+    const seen = new Set();
+    return out.filter((p) => {
+        const id = policyId(p);
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+//# sourceMappingURL=policy.js.map

package/dist/learning/qe-flywheel/receipt-store.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Durable, append-only persistence for flywheel evolve receipts (ADR-118 §4).
+ *
+ * The generational lineage is only trustworthy if it survives the process: a
+ * third party must be able to reload the receipts and re-verify each one
+ * (signature + frozen-gate re-execution) offline. This stores every receipt —
+ * promoted OR rejected — in an append-only table in the unified `memory.db`.
+ *
+ * Data safety (unified-memory rule): CREATE TABLE IF NOT EXISTS is additive;
+ * writes are INSERT-only (no UPDATE/DELETE/DROP in this API); the caller opens
+ * the DB and is responsible for backups. The `db` handle is injected so tests
+ * run against an in-memory database.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import { type LineageResult } from './generation.js';
+import type { EvolveReceipt } from './receipt.js';
+/** Idempotent, additive migration — creates the receipts table if absent. */
+export declare function ensureReceiptTable(db: DatabaseType): void;
+/** Append one receipt (INSERT-only). Returns its assigned seq. */
+export declare function persistReceipt(db: DatabaseType, receipt: EvolveReceipt): number;
+/** Append many receipts in one transaction (still INSERT-only). */
+export declare function persistReceipts(db: DatabaseType, receipts: EvolveReceipt[]): number;
+/** Load persisted receipts back into EvolveReceipt objects, ordered by seq. */
+export declare function loadReceipts(db: DatabaseType): EvolveReceipt[];
+/**
+ * Reload the persisted lineage and re-verify it end-to-end (signatures +
+ * frozen-gate re-execution + compounding chain). This is the offline
+ * "trust the re-run, not the log" check applied to what's actually on disk.
+ */
+export declare function verifyPersistedLineage(db: DatabaseType): LineageResult;
+//# sourceMappingURL=receipt-store.d.ts.map