agentic-qe 3.11.5 → 3.12.0

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

package/dist/learning/qe-flywheel/receipt-store.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { reconstructLineage } from './generation.js';
+/** Idempotent, additive migration — creates the receipts table if absent. */
+export function ensureReceiptTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS flywheel_receipts (
+      seq                 INTEGER PRIMARY KEY AUTOINCREMENT,
+      generation          INTEGER NOT NULL,
+      rule_version        TEXT NOT NULL,
+      rule_fingerprint    TEXT NOT NULL,
+      sealed_hash         TEXT NOT NULL,
+      sealed_json         TEXT NOT NULL,
+      verdict             TEXT NOT NULL,
+      baseline_policy_id  TEXT NOT NULL,
+      candidate_policy_id TEXT NOT NULL,
+      signer_key_id       TEXT NOT NULL,
+      public_key_pem      TEXT NOT NULL,
+      signature           TEXT NOT NULL,
+      created_at          TEXT DEFAULT (datetime('now'))
+    )
+  `);
+}
+/** Append one receipt (INSERT-only). Returns its assigned seq. */
+export function persistReceipt(db, receipt) {
+    ensureReceiptTable(db);
+    const info = db.prepare(`
+    INSERT INTO flywheel_receipts
+      (generation, rule_version, rule_fingerprint, sealed_hash, sealed_json,
+       verdict, baseline_policy_id, candidate_policy_id, signer_key_id,
+       public_key_pem, signature)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(receipt.generation, receipt.ruleVersion, receipt.ruleFingerprint, receipt.sealedHash, JSON.stringify(receipt.sealed), receipt.verdict, receipt.baselinePolicyId, receipt.candidatePolicyId, receipt.signerKeyId, receipt.publicKeyPem, receipt.signature);
+    return Number(info.lastInsertRowid);
+}
+/** Append many receipts in one transaction (still INSERT-only). */
+export function persistReceipts(db, receipts) {
+    ensureReceiptTable(db);
+    const tx = db.transaction((rs) => {
+        for (const r of rs)
+            persistReceipt(db, r);
+    });
+    tx(receipts);
+    return receipts.length;
+}
+/** Load persisted receipts back into EvolveReceipt objects, ordered by seq. */
+export function loadReceipts(db) {
+    ensureReceiptTable(db);
+    const rows = db.prepare(`
+    SELECT generation, rule_version, rule_fingerprint, sealed_hash, sealed_json,
+           verdict, baseline_policy_id, candidate_policy_id, signer_key_id,
+           public_key_pem, signature
+      FROM flywheel_receipts
+     ORDER BY seq ASC
+  `).all();
+    return rows.map((r) => ({
+        generation: r.generation,
+        ruleVersion: r.rule_version,
+        ruleFingerprint: r.rule_fingerprint,
+        sealed: JSON.parse(r.sealed_json),
+        sealedHash: r.sealed_hash,
+        verdict: r.verdict === 'promote' ? 'promote' : 'reject',
+        baselinePolicyId: r.baseline_policy_id,
+        candidatePolicyId: r.candidate_policy_id,
+        signerKeyId: r.signer_key_id,
+        publicKeyPem: r.public_key_pem,
+        signature: r.signature,
+    }));
+}
+/**
+ * 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 function verifyPersistedLineage(db) {
+    return reconstructLineage(loadReceipts(db));
+}
+//# sourceMappingURL=receipt-store.js.map

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

@@ -0,0 +1,62 @@
+/**
+ * Ed25519-signed evolve receipts for the QE-policy flywheel (ADR-118 §4).
+ *
+ * Every generation — promoted OR rejected — emits a signed receipt into an
+ * append-only lineage. A receipt seals the decision inputs (composing ADR-116 /
+ * ADR-120) and signs the whole body, so a third party can (a) re-execute the
+ * frozen rule on the sealed inputs (ADR-120 verifyPromotion) and (b) verify the
+ * signature — trusting the SIGNATURE and the RE-RUN, not the producer.
+ *
+ * Ed25519 via Node's built-in crypto — dependency-free (ADR-118 §6).
+ */
+import type { SealedInputs, PromotionReceipt } from '../../validation/gate-reexecute.js';
+export interface Signer {
+    /** Stable id for the signing key (hash of the public key). */
+    keyId: string;
+    /** SPKI PEM of the public key — travels in the receipt for verification. */
+    publicKeyPem: string;
+    /** Sign a message, returning a hex signature. */
+    sign(message: string): string;
+}
+/**
+ * Create an Ed25519 signer. With a 32-byte seed (hex or Buffer) the keypair is
+ * DETERMINISTIC — same seed ⇒ same key ⇒ reproducible receipts (useful for
+ * replay bundles and tests). Without a seed, a fresh random keypair is used.
+ */
+export declare function createSigner(seed?: string | Buffer): Signer;
+/** Verify an Ed25519 signature against a public key PEM. Never throws. */
+export declare function verifySignature(publicKeyPem: string, message: string, signatureHex: string): boolean;
+/** A signed evolve receipt — the durable, verifiable record of one generation. */
+export interface EvolveReceipt {
+    generation: number;
+    /** Frozen acceptance rule this decision used (ADR-120). */
+    ruleVersion: string;
+    ruleFingerprint: string;
+    /** Sealed decision inputs + their content hash (ADR-116/120). */
+    sealed: SealedInputs;
+    sealedHash: string;
+    /** The verdict this generation recorded. */
+    verdict: 'promote' | 'reject';
+    /** Lineage links: which policy was the baseline, which the candidate. */
+    baselinePolicyId: string;
+    candidatePolicyId: string;
+    /** Signer identity + public key (for offline verification). */
+    signerKeyId: string;
+    publicKeyPem: string;
+    /** Ed25519 signature over the canonical receipt body. */
+    signature: string;
+}
+/** The signed portion of a receipt (everything except the signature itself). */
+export type ReceiptBody = Omit<EvolveReceipt, 'signature'>;
+/** Canonical serialization of the receipt body for signing/verifying. */
+export declare function receiptBodyString(body: ReceiptBody): string;
+/** Sign a receipt body, producing a complete signed receipt. */
+export declare function signReceipt(body: ReceiptBody, signer: Signer): EvolveReceipt;
+/** Verify a receipt's Ed25519 signature (does NOT re-execute the gate — see ADR-120). */
+export declare function verifyReceiptSignature(receipt: EvolveReceipt): boolean;
+/**
+ * Adapt an EvolveReceipt to the ADR-120 PromotionReceipt shape so it can be
+ * re-verified by `verifyPromotion` (maps `verdict` → `recordedVerdict`).
+ */
+export declare function toPromotionReceipt(receipt: EvolveReceipt): PromotionReceipt;
+//# sourceMappingURL=receipt.d.ts.map

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

@@ -0,0 +1,97 @@
+/**
+ * Ed25519-signed evolve receipts for the QE-policy flywheel (ADR-118 §4).
+ *
+ * Every generation — promoted OR rejected — emits a signed receipt into an
+ * append-only lineage. A receipt seals the decision inputs (composing ADR-116 /
+ * ADR-120) and signs the whole body, so a third party can (a) re-execute the
+ * frozen rule on the sealed inputs (ADR-120 verifyPromotion) and (b) verify the
+ * signature — trusting the SIGNATURE and the RE-RUN, not the producer.
+ *
+ * Ed25519 via Node's built-in crypto — dependency-free (ADR-118 §6).
+ */
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, } from 'node:crypto';
+/** Derive a stable key id from a public key PEM. */
+function keyIdOf(publicKeyPem) {
+    return createHash('sha256').update(publicKeyPem).digest('hex').slice(0, 16);
+}
+/**
+ * Create an Ed25519 signer. With a 32-byte seed (hex or Buffer) the keypair is
+ * DETERMINISTIC — same seed ⇒ same key ⇒ reproducible receipts (useful for
+ * replay bundles and tests). Without a seed, a fresh random keypair is used.
+ */
+export function createSigner(seed) {
+    let privateKey;
+    let publicKey;
+    if (seed !== undefined) {
+        const raw = typeof seed === 'string' ? Buffer.from(seed, 'hex') : seed;
+        if (raw.length !== 32) {
+            throw new Error(`Ed25519 seed must be 32 bytes (got ${raw.length}).`);
+        }
+        // PKCS#8 wrapper for a raw Ed25519 seed: fixed 16-byte prefix + 32-byte seed.
+        const pkcs8 = Buffer.concat([
+            Buffer.from('302e020100300506032b657004220420', 'hex'),
+            raw,
+        ]);
+        privateKey = createPrivateKey({ key: pkcs8, format: 'der', type: 'pkcs8' });
+        publicKey = createPublicKey(privateKey);
+    }
+    else {
+        ({ privateKey, publicKey } = generateKeyPairSync('ed25519'));
+    }
+    const publicKeyPem = publicKey.export({ format: 'pem', type: 'spki' }).toString();
+    return {
+        keyId: keyIdOf(publicKeyPem),
+        publicKeyPem,
+        sign(message) {
+            return edSign(null, Buffer.from(message, 'utf8'), privateKey).toString('hex');
+        },
+    };
+}
+/** Verify an Ed25519 signature against a public key PEM. Never throws. */
+export function verifySignature(publicKeyPem, message, signatureHex) {
+    try {
+        const publicKey = createPublicKey(publicKeyPem);
+        return edVerify(null, Buffer.from(message, 'utf8'), publicKey, Buffer.from(signatureHex, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Canonical serialization of the receipt body for signing/verifying. */
+export function receiptBodyString(body) {
+    // Field order is fixed here (not sorted) so it is explicit and stable.
+    return JSON.stringify({
+        generation: body.generation,
+        ruleVersion: body.ruleVersion,
+        ruleFingerprint: body.ruleFingerprint,
+        sealedHash: body.sealedHash,
+        verdict: body.verdict,
+        baselinePolicyId: body.baselinePolicyId,
+        candidatePolicyId: body.candidatePolicyId,
+        signerKeyId: body.signerKeyId,
+    });
+}
+/** Sign a receipt body, producing a complete signed receipt. */
+export function signReceipt(body, signer) {
+    const signature = signer.sign(receiptBodyString(body));
+    return { ...body, signature };
+}
+/** Verify a receipt's Ed25519 signature (does NOT re-execute the gate — see ADR-120). */
+export function verifyReceiptSignature(receipt) {
+    const { signature, ...body } = receipt;
+    return verifySignature(receipt.publicKeyPem, receiptBodyString(body), signature);
+}
+/**
+ * Adapt an EvolveReceipt to the ADR-120 PromotionReceipt shape so it can be
+ * re-verified by `verifyPromotion` (maps `verdict` → `recordedVerdict`).
+ */
+export function toPromotionReceipt(receipt) {
+    return {
+        ruleVersion: receipt.ruleVersion,
+        ruleFingerprint: receipt.ruleFingerprint,
+        sealedHash: receipt.sealedHash,
+        sealed: receipt.sealed,
+        recordedVerdict: receipt.verdict,
+    };
+}
+//# sourceMappingURL=receipt.js.map