agentic-qe 3.11.5 → 3.12.1

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