agentic-qe 3.12.3 → 3.13.1

package/dist/init/codex-installer.js

@@ -5,8 +5,9 @@
  *
  * Follows the OpenCode/Kiro installer pattern (ADR-025).
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'fs';
 import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { createPlatformConfigGenerator, } from './platform-config-generator.js';
 // ============================================================================
@@ -28,9 +29,13 @@ export class CodexInstaller {
             success: true,
             mcpConfigured: false,
             agentsMdInstalled: false,
+            hooksConfigured: false,
+            skillsInstalled: 0,
             errors: [],
             configPath: '',
             agentsMdPath: '',
+            hooksPath: join(this.projectRoot, '.codex', 'hooks.json'),
+            skillsPath: join(this.projectRoot, '.agents', 'skills'),
         };
         try {
             // Generate TOML MCP config
@@ -65,6 +70,8 @@ export class CodexInstaller {
                 }
                 result.agentsMdInstalled = true;
             }
+            this.installCodexHooks(result);
+            result.skillsInstalled = this.installCodexSkills();
         }
         catch (error) {
             result.success = false;
@@ -72,6 +79,120 @@ export class CodexInstaller {
         }
         return result;
     }
+    /**
+     * Install Codex-native lifecycle adapters and merge AQE/ruflo hook groups
+     * without removing user-defined hooks.
+     */
+    installCodexHooks(result) {
+        const sourceRoot = this.resolvePackageRoot();
+        if (!sourceRoot)
+            return;
+        const sourceConfig = join(sourceRoot, '.codex', 'hooks.json');
+        const sourceScripts = join(sourceRoot, '.codex', 'hooks');
+        if (!existsSync(sourceConfig) || !existsSync(sourceScripts))
+            return;
+        const targetCodexDir = join(this.projectRoot, '.codex');
+        const targetScripts = join(targetCodexDir, 'hooks');
+        mkdirSync(targetScripts, { recursive: true });
+        for (const file of readdirSync(sourceScripts)) {
+            const source = join(sourceScripts, file);
+            if (!statSync(source).isFile())
+                continue;
+            const target = join(targetScripts, file);
+            if (!existsSync(target) || this.overwrite) {
+                copyFileSync(source, target);
+            }
+        }
+        const runtimes = [
+            {
+                source: join(sourceRoot, '.claude', 'hooks', 'aqe-hook.cjs'),
+                target: join(targetScripts, 'aqe-runtime.cjs'),
+            },
+            {
+                source: join(sourceRoot, '.claude', 'helpers', 'ruflo-hook.cjs'),
+                target: join(targetScripts, 'ruflo-runtime.cjs'),
+            },
+        ];
+        for (const runtime of runtimes) {
+            if (existsSync(runtime.source) && (!existsSync(runtime.target) || this.overwrite)) {
+                copyFileSync(runtime.source, runtime.target);
+            }
+        }
+        const generated = JSON.parse(readFileSync(sourceConfig, 'utf-8'));
+        const targetConfig = join(targetCodexDir, 'hooks.json');
+        if (!existsSync(targetConfig)) {
+            writeFileSync(targetConfig, JSON.stringify(generated, null, 2) + '\n');
+            result.hooksConfigured = true;
+            return;
+        }
+        if (!this.overwrite)
+            return;
+        const existing = JSON.parse(readFileSync(targetConfig, 'utf-8'));
+        const owned = (value) => JSON.stringify(value).includes('/.codex/hooks/aqe-codex-hook.cjs')
+            || JSON.stringify(value).includes('/.codex/hooks/ruflo-codex-hook.cjs');
+        const mergedHooks = {};
+        const events = new Set([
+            ...Object.keys(existing.hooks || {}),
+            ...Object.keys(generated.hooks || {}),
+        ]);
+        for (const event of events) {
+            const userGroups = (existing.hooks?.[event] || []).filter((group) => !owned(group));
+            mergedHooks[event] = [...userGroups, ...(generated.hooks?.[event] || [])];
+        }
+        writeFileSync(targetConfig, JSON.stringify({ ...existing, description: generated.description, hooks: mergedHooks }, null, 2) + '\n');
+        result.hooksConfigured = true;
+    }
+    /** Install the curated repo-scoped AQE skills Codex discovers automatically. */
+    installCodexSkills() {
+        const sourceRoot = this.resolvePackageRoot();
+        if (!sourceRoot)
+            return 0;
+        const sourceSkills = join(sourceRoot, '.agents', 'skills');
+        if (!existsSync(sourceSkills))
+            return 0;
+        const targetSkills = join(this.projectRoot, '.agents', 'skills');
+        mkdirSync(targetSkills, { recursive: true });
+        let installed = 0;
+        for (const skill of readdirSync(sourceSkills)) {
+            if (!skill.startsWith('aqe-'))
+                continue;
+            const source = join(sourceSkills, skill);
+            if (!statSync(source).isDirectory())
+                continue;
+            const target = join(targetSkills, skill);
+            if (existsSync(target) && !this.overwrite)
+                continue;
+            this.copyDirectory(source, target);
+            installed++;
+        }
+        return installed;
+    }
+    copyDirectory(source, target) {
+        mkdirSync(target, { recursive: true });
+        for (const entry of readdirSync(source)) {
+            const from = join(source, entry);
+            const to = join(target, entry);
+            if (statSync(from).isDirectory()) {
+                this.copyDirectory(from, to);
+            }
+            else {
+                copyFileSync(from, to);
+            }
+        }
+    }
+    resolvePackageRoot() {
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            join(moduleDir, '..', '..'),
+            // esbuild bundles this module into dist/cli/bundle.js, so import.meta.url
+            // no longer identifies src/init/codex-installer.ts. Resolve from the
+            // running CLI entrypoint as the authoritative packaged layout.
+            join(dirname(process.argv[1] || ''), '..', '..'),
+            join(this.projectRoot, 'node_modules', 'agentic-qe'),
+        ];
+        return candidates.find((candidate) => existsSync(join(candidate, '.codex', 'hooks.json'))
+            || existsSync(join(candidate, '.agents', 'skills')));
+    }
     /**
      * Merge AQE MCP server config into existing TOML.
      * Simple approach: if [mcp_servers.agentic-qe] already exists, skip.

package/dist/init/phases/09-assets.js

@@ -303,6 +303,10 @@ export class AssetsPhase extends BasePhase {
                 context.services.log(`  Codex MCP: ${res.configPath}`);
             if (res.agentsMdInstalled)
                 context.services.log(`  Codex AGENTS.md: ${res.agentsMdPath}`);
+            if (res.hooksConfigured)
+                context.services.log(`  Codex hooks: ${res.hooksPath}`);
+            if (res.skillsInstalled > 0)
+                context.services.log(`  Codex skills: ${res.skillsInstalled} installed`);
         }
         if (options.withWindsurf || (options.autoMode && existsSync(join(projectRoot, '.windsurf')))) {
             const { createWindsurfInstaller } = await import('../windsurf-installer.js');

package/dist/init/phases/phase-interface.d.ts

@@ -119,7 +119,7 @@ export interface InitOptions {
     withKiloCode?: boolean;
     /** Install Roo Code MCP config and custom mode */
     withRooCode?: boolean;
-    /** Install OpenAI Codex CLI MCP config and AGENTS.md */
+    /** Install OpenAI Codex CLI MCP, AGENTS.md, hooks, and QE skills */
     withCodex?: boolean;
     /** Install Windsurf MCP config and rules */
     withWindsurf?: boolean;

package/dist/init/skills-installer.js

@@ -30,6 +30,7 @@ const V3_DOMAIN_SKILLS = [
     'qe-visual-accessibility', // Visual regression, WCAG
     'qe-chaos-resilience', // Fault injection, resilience
     'qe-learning-optimization', // Transfer learning, self-improvement
+    'qe-court', // Adversarial review court — overturn-gated SHIP/REMAND/BLOCK verdict (ADR-124)
     // V3 utilities
     'qe-iterative-loop', // QE iteration patterns
     // New skills (ADR-086 skill design standards)

package/dist/integrations/embeddings/base/EmbeddingGenerator.js

@@ -11,7 +11,6 @@
  * @module integrations/embeddings/base/EmbeddingGenerator
  */
 import { EmbeddingCache } from '../cache/EmbeddingCache.js';
-import { pipeline } from '@huggingface/transformers';
 import { cosineSimilarity } from '../../../shared/utils/vector-math.js';
 /**
  * Base embedding generator class
@@ -61,6 +60,19 @@ export class EmbeddingGenerator {
             const loadDtype = this.config.quantization === 'none' ? 'fp32' :
                 this.config.quantization === 'fp16' ? 'fp16' :
                     this.config.quantization === 'int8' ? 'int8' : 'q8';
+            // Lazy-load the optional transformers backend (#565). If it isn't
+            // installed, fail with an actionable message pointing at the endpoint path.
+            let pipeline;
+            try {
+                ({ pipeline } = await import('@huggingface/transformers'));
+            }
+            catch (err) {
+                throw new Error('Local (in-process) embeddings require the optional dependency ' +
+                    '"@huggingface/transformers", which is not installed. Either run ' +
+                    '`npm install @huggingface/transformers`, or configure an embedding ' +
+                    'endpoint (e.g. Cognitum /v1/embeddings) so the local backend is not needed. ' +
+                    `Underlying import error: ${err instanceof Error ? err.message : String(err)}`);
+            }
             this.model = await pipeline('feature-extraction', this.config.model, {
                 dtype: loadDtype,
                 // v4 narrowed ProgressInfo to a discriminated union — `progress`

package/dist/kernel/unified-memory.js

@@ -255,6 +255,10 @@ export class UnifiedMemoryManager {
             this.db = openSafeDatabase(this.config.dbPath, {
                 walMode: this.config.walMode,
                 busyTimeout: this.config.busyTimeout,
+                // M3.2: the missing-file case is handled above; this covers the
+                // EXISTS-but-MALFORMED case — auto-restore the newest verified backup and
+                // park the corrupt original (non-destructive) instead of opening a broken DB.
+                autoRestore: true,
             });
             this.db.pragma(`mmap_size = ${this.config.mmapSize}`);
             this.db.pragma(`cache_size = ${this.config.cacheSize}`);

package/dist/learning/qe-flywheel/corpus-scorer.js

@@ -150,11 +150,13 @@ function selectHeldOut(docs, ratio) {
  */
 function scoreHeldOut(docs, policy, ratio) {
     if (docs.length === 0)
-        return 0;
+        return { mean: 0, samples: [] };
     const queries = selectHeldOut(docs, ratio);
     if (queries.length === 0)
-        return 0;
-    let sumReciprocalRank = 0;
+        return { mean: 0, samples: [] };
+    // Per-query reciprocal ranks: the mean is the held-out signal; the vector is
+    // the paired sample the accept/v1+sig significance gate needs (ADR-118).
+    const samples = [];
     for (const queried of queries) {
         const query = queried.bodyTokens; // subject deliberately withheld
         const rels = docs.map((d) => ({ doc: d, rel: relevance(query, d, queried, policy) }));
@@ -177,9 +179,10 @@ function scoreHeldOut(docs, policy, ratio) {
         }
         const ranked = rankMMR(pool, policy.mmrLambda);
         const rank = ranked.indexOf(queried.id) + 1; // 1-based; 0 -> not found
-        sumReciprocalRank += rank > 0 ? 1 / rank : 0;
+        samples.push(rank > 0 ? 1 / rank : 0);
     }
-    return sumReciprocalRank / queries.length;
+    const mean = samples.reduce((a, b) => a + b, 0) / samples.length;
+    return { mean, samples };
 }
 // ---------------------------------------------------------------------------
 // Anchor flat guard (the no-regression floor)
@@ -283,11 +286,11 @@ export function createCorpusScorer(opts) {
     const corpus = loadCorpus(opts.db);
     let anchorMeanCached = null;
     return (policy) => {
-        const heldOut = scoreHeldOut(corpus, policy, ratio);
+        const held = scoreHeldOut(corpus, policy, ratio);
         if (anchorMeanCached === null) {
             anchorMeanCached = gradeAnchor(anchorPath);
         }
-        return { heldOut, anchorMean: anchorMeanCached };
+        return { heldOut: held.mean, anchorMean: anchorMeanCached, heldOutSamples: held.samples };
     };
 }
 //# sourceMappingURL=corpus-scorer.js.map

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

@@ -22,6 +22,13 @@ export interface PolicyScores {
     heldOut: number;
     /** Mean over the ADR-117 frozen anchor items (the no-regression signal). */
     anchorMean: number;
+    /**
+     * Per-held-out-task scores whose mean is `heldOut`. Optional — when present and
+     * paired index-for-index with the baseline's, they enable the accept/v1+sig
+     * paired-bootstrap significance gate (ADR-118). Scorers that don't provide them
+     * simply can't use accept/v1+sig (it fail-closes).
+     */
+    heldOutSamples?: number[];
 }
 /** Injected: evaluate a policy → its held-out + anchor scores. */
 export type PolicyScorer = (policy: RetrievalPolicy) => PolicyScores | Promise<PolicyScores>;

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

@@ -54,6 +54,11 @@ export async function runFlywheelGeneration(input) {
         anchorTol: input.anchorTol,
         provenanceTier,
         allowJudgeTier: input.allowJudgeTier,
+        // ADR-118 accept/v1+sig: seal the paired per-task samples ONLY when the sig
+        // rule is in use. Left undefined for accept/v1 (and thus absent from the
+        // sealed hash), so accept/v1 receipts remain byte-identical to before.
+        candidateHeldOutSamples: ruleVersion === 'accept/v1+sig' ? candidateScores.heldOutSamples : undefined,
+        baselineHeldOutSamples: ruleVersion === 'accept/v1+sig' ? baselineScores.heldOutSamples : undefined,
     };
     const ruleResult = reExecuteGate(ruleVersion, sealed);
     const verdict = ruleResult.promote ? 'promote' : 'reject';

package/dist/learning/qe-flywheel/witness-verify.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cross-side witness verification (ADR-124 M2.2) — the single verifier that
+ * reconciles AQE's flywheel receipts with the Cognitum `qe-harness` witness
+ * bundles so QE evidence signed by the shared platform identity
+ * (fingerprint `f1ac28607da49ec1`) is verifiable on either side.
+ *
+ * WHAT WAS ALREADY ALIGNED (the bridge that exists): both sides use Ed25519,
+ * the same env secret `QE_WITNESS_SIGNING_KEY` (JSON `{publicKey,privateKey}`
+ * PEM), and the SAME key-id/fingerprint scheme `sha256(pem.trim()).slice(0,16)`
+ * — so both can sign AS the platform identity. `keyFingerprint()` here is
+ * byte-identical to `receipt.ts` `keyIdOf` and to qe-harness `witness.ts`.
+ *
+ * WHAT THIS RECONCILES: the two SIGNED ARTIFACTS are not natively
+ * cross-verifiable — AQE signs a fixed-field-order JSON body as HEX; qe-harness
+ * signs a `sha256:`-prefixed digest of a recursively key-sorted `stableStringify`
+ * as BASE64, wrapped in a nested `witness{}`. This module verifies BOTH.
+ *
+ * TWO EXTERNAL DEPENDENCIES (tracked, need the qe-harness owner — see M2.2 notes):
+ *   1. The public key for `f1ac28607da49ec1` is committed to NEITHER repo (it
+ *      lives on meta-llm). Offline verification of platform-signed artifacts
+ *      needs it provisioned via `QE_WITNESS_PUBLIC_KEYS_JSON`. This verifier is
+ *      READY the moment that allowlist is populated.
+ *   2. The qe-harness bundle format here is implemented to the documented
+ *      algorithm; byte-parity must be confirmed against a REAL qe-harness sample
+ *      bundle before it gates anything (see witness-verify.test.ts).
+ *
+ * No new deps — node:crypto only. Reuses receipt.ts for the AQE path.
+ */
+import { type EvolveReceipt } from './receipt.js';
+/** Public-key allowlist: fingerprint (`sha256(pem)[:16]`) → SPKI PEM. */
+export type PublicKeyAllowlist = Map<string, string>;
+/** Byte-identical to receipt.ts `keyIdOf` and qe-harness `witness.ts` fingerprint. */
+export declare function keyFingerprint(publicKeyPem: string): string;
+/**
+ * Load the trusted public-key allowlist from `QE_WITNESS_PUBLIC_KEYS_JSON`
+ * (`{ "<fingerprint>": "<SPKI PEM>", ... }`). Empty map when unset/unparseable —
+ * callers decide whether an empty allowlist means "verify signature only" (AQE
+ * receipts carry their own PEM) or "reject" (platform bundles need a trust root).
+ */
+export declare function loadAllowlist(json?: string | undefined): PublicKeyAllowlist;
+/**
+ * Deterministic serialization matching qe-harness `stableStringify`: recursive
+ * key-sort on objects, array order preserved. This MUST stay byte-identical to
+ * the qe-harness implementation or digests will not match.
+ */
+export declare function stableStringify(value: unknown): string;
+/** qe-harness canonical digest: `sha256:` + sha256(stableStringify(bundle − digest − witness)). */
+export declare function canonicalDigest(bundle: Record<string, unknown>): string;
+/** The qe-harness witness envelope (packages/engine/src/types.ts). */
+export interface HarnessWitness {
+    alg: 'ed25519';
+    digest: string;
+    /** base64 Ed25519 signature over `digest`. */
+    signature: string;
+    publicKeyFingerprint: string;
+    signedAt?: string;
+}
+export type WitnessFormat = 'aqe-receipt' | 'harness-witness' | 'unknown';
+export interface VerifyResult {
+    valid: boolean;
+    format: WitnessFormat;
+    fingerprint?: string;
+    reason?: string;
+}
+/**
+ * Verify an AQE flywheel receipt. When an allowlist is provided and non-empty,
+ * the receipt's embedded public key must be present (by fingerprint) AND match;
+ * an empty allowlist verifies the signature against the receipt's own PEM only.
+ * NOTE: this is signature verification; the full AQE trust model ALSO re-executes
+ * the frozen gate (ADR-120) — do that separately for promotion decisions.
+ */
+export declare function verifyAqeReceipt(receipt: EvolveReceipt, allowlist?: PublicKeyAllowlist, opts?: {
+    allowSelfSigned?: boolean;
+}): VerifyResult;
+/**
+ * Verify a qe-harness witness bundle. Requires the signer's public key in the
+ * allowlist (platform bundles do NOT embed their PEM). Recomputes the canonical
+ * digest to detect payload tampering, then Ed25519-verifies the base64 signature
+ * over the digest string.
+ */
+export declare function verifyHarnessWitness(bundle: Record<string, unknown> & {
+    witness: HarnessWitness;
+}, allowlist: PublicKeyAllowlist): VerifyResult;
+/** Detect the artifact format and dispatch to the right verifier. */
+export declare function verifyWitness(artifact: unknown, allowlist?: PublicKeyAllowlist): VerifyResult;
+//# sourceMappingURL=witness-verify.d.ts.map

package/dist/learning/qe-flywheel/witness-verify.js

@@ -0,0 +1,156 @@
+/**
+ * Cross-side witness verification (ADR-124 M2.2) — the single verifier that
+ * reconciles AQE's flywheel receipts with the Cognitum `qe-harness` witness
+ * bundles so QE evidence signed by the shared platform identity
+ * (fingerprint `f1ac28607da49ec1`) is verifiable on either side.
+ *
+ * WHAT WAS ALREADY ALIGNED (the bridge that exists): both sides use Ed25519,
+ * the same env secret `QE_WITNESS_SIGNING_KEY` (JSON `{publicKey,privateKey}`
+ * PEM), and the SAME key-id/fingerprint scheme `sha256(pem.trim()).slice(0,16)`
+ * — so both can sign AS the platform identity. `keyFingerprint()` here is
+ * byte-identical to `receipt.ts` `keyIdOf` and to qe-harness `witness.ts`.
+ *
+ * WHAT THIS RECONCILES: the two SIGNED ARTIFACTS are not natively
+ * cross-verifiable — AQE signs a fixed-field-order JSON body as HEX; qe-harness
+ * signs a `sha256:`-prefixed digest of a recursively key-sorted `stableStringify`
+ * as BASE64, wrapped in a nested `witness{}`. This module verifies BOTH.
+ *
+ * TWO EXTERNAL DEPENDENCIES (tracked, need the qe-harness owner — see M2.2 notes):
+ *   1. The public key for `f1ac28607da49ec1` is committed to NEITHER repo (it
+ *      lives on meta-llm). Offline verification of platform-signed artifacts
+ *      needs it provisioned via `QE_WITNESS_PUBLIC_KEYS_JSON`. This verifier is
+ *      READY the moment that allowlist is populated.
+ *   2. The qe-harness bundle format here is implemented to the documented
+ *      algorithm; byte-parity must be confirmed against a REAL qe-harness sample
+ *      bundle before it gates anything (see witness-verify.test.ts).
+ *
+ * No new deps — node:crypto only. Reuses receipt.ts for the AQE path.
+ */
+import { createHash, verify as edVerify, createPublicKey } from 'node:crypto';
+import { verifySignature, receiptBodyString } from './receipt.js';
+/** Byte-identical to receipt.ts `keyIdOf` and qe-harness `witness.ts` fingerprint. */
+export function keyFingerprint(publicKeyPem) {
+    return createHash('sha256').update(publicKeyPem.trim()).digest('hex').slice(0, 16);
+}
+/**
+ * Load the trusted public-key allowlist from `QE_WITNESS_PUBLIC_KEYS_JSON`
+ * (`{ "<fingerprint>": "<SPKI PEM>", ... }`). Empty map when unset/unparseable —
+ * callers decide whether an empty allowlist means "verify signature only" (AQE
+ * receipts carry their own PEM) or "reject" (platform bundles need a trust root).
+ */
+export function loadAllowlist(json = process.env.QE_WITNESS_PUBLIC_KEYS_JSON) {
+    const map = new Map();
+    if (!json)
+        return map;
+    try {
+        const obj = JSON.parse(json);
+        for (const [fp, pem] of Object.entries(obj)) {
+            if (typeof pem === 'string')
+                map.set(fp, pem);
+        }
+    }
+    catch {
+        // An unparseable allowlist yields an empty (fail-closed) trust root — but log
+        // it loudly, or a typo'd env var silently disables verification (qe-court finding).
+        console.error('[witness-verify] QE_WITNESS_PUBLIC_KEYS_JSON is set but not valid JSON — ' +
+            'treating the trust root as EMPTY (verification will fail closed).');
+    }
+    return map;
+}
+/**
+ * Deterministic serialization matching qe-harness `stableStringify`: recursive
+ * key-sort on objects, array order preserved. This MUST stay byte-identical to
+ * the qe-harness implementation or digests will not match.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return '[' + value.map(stableStringify).join(',') + ']';
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k])).join(',') + '}';
+}
+/** qe-harness canonical digest: `sha256:` + sha256(stableStringify(bundle − digest − witness)). */
+export function canonicalDigest(bundle) {
+    const rest = {};
+    for (const [k, v] of Object.entries(bundle)) {
+        if (k === 'digest' || k === 'witness')
+            continue;
+        rest[k] = v;
+    }
+    return 'sha256:' + createHash('sha256').update(stableStringify(rest)).digest('hex');
+}
+/**
+ * Verify an AQE flywheel receipt. When an allowlist is provided and non-empty,
+ * the receipt's embedded public key must be present (by fingerprint) AND match;
+ * an empty allowlist verifies the signature against the receipt's own PEM only.
+ * NOTE: this is signature verification; the full AQE trust model ALSO re-executes
+ * the frozen gate (ADR-120) — do that separately for promotion decisions.
+ */
+export function verifyAqeReceipt(receipt, allowlist, opts) {
+    const fingerprint = keyFingerprint(receipt.publicKeyPem);
+    if (allowlist && allowlist.size > 0) {
+        const allowed = allowlist.get(fingerprint);
+        if (!allowed)
+            return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'fingerprint-not-in-allowlist' };
+        if (allowed.trim() !== receipt.publicKeyPem.trim()) {
+            return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'allowlist-pem-mismatch' };
+        }
+    }
+    else if (!opts?.allowSelfSigned) {
+        // FAIL-CLOSED (qe-court finding): with no trust root, verifying against the
+        // receipt's OWN embedded key just proves internal consistency — anyone can
+        // self-sign a forged receipt. A caller must either provide an allowlist or
+        // explicitly opt into self-signed verification (e.g. a consistency check that
+        // is NOT used as authorization).
+        return { valid: false, format: 'aqe-receipt', fingerprint, reason: 'no-trust-root' };
+    }
+    const ok = verifySignature(receipt.publicKeyPem, receiptBodyString(receipt), receipt.signature);
+    return { valid: ok, format: 'aqe-receipt', fingerprint, reason: ok ? undefined : 'bad-signature' };
+}
+/**
+ * Verify a qe-harness witness bundle. Requires the signer's public key in the
+ * allowlist (platform bundles do NOT embed their PEM). Recomputes the canonical
+ * digest to detect payload tampering, then Ed25519-verifies the base64 signature
+ * over the digest string.
+ */
+export function verifyHarnessWitness(bundle, allowlist) {
+    const w = bundle.witness;
+    const fingerprint = w?.publicKeyFingerprint;
+    // Fail closed on an unexpected algorithm — never verify a non-Ed25519-declared
+    // witness as Ed25519 (qe-court finding: ambiguous alg across implementations).
+    if (w?.alg !== 'ed25519') {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'unsupported-alg' };
+    }
+    const pem = fingerprint ? allowlist.get(fingerprint) : undefined;
+    if (!pem)
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'fingerprint-not-in-allowlist' };
+    const recomputed = canonicalDigest(bundle);
+    if (recomputed !== w.digest) {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'digest-mismatch' };
+    }
+    try {
+        const key = createPublicKey(pem);
+        const ok = edVerify(null, Buffer.from(w.digest, 'utf8'), key, Buffer.from(w.signature, 'base64'));
+        return { valid: ok, format: 'harness-witness', fingerprint, reason: ok ? undefined : 'bad-signature' };
+    }
+    catch {
+        return { valid: false, format: 'harness-witness', fingerprint, reason: 'verify-error' };
+    }
+}
+/** Detect the artifact format and dispatch to the right verifier. */
+export function verifyWitness(artifact, allowlist = loadAllowlist()) {
+    if (artifact && typeof artifact === 'object') {
+        const o = artifact;
+        const w = o.witness;
+        if (w && typeof w === 'object' && typeof w.signature === 'string' && typeof w.publicKeyFingerprint === 'string') {
+            return verifyHarnessWitness(o, allowlist);
+        }
+        if (typeof o.signature === 'string' && typeof o.publicKeyPem === 'string' && typeof o.sealedHash === 'string') {
+            return verifyAqeReceipt(o, allowlist);
+        }
+    }
+    return { valid: false, format: 'unknown', reason: 'unrecognized-artifact' };
+}
+//# sourceMappingURL=witness-verify.js.map

package/dist/learning/real-embeddings.js

@@ -125,7 +125,21 @@ async function initializeModel(config = {}) {
                 return;
             }
             // In-process branch — only here do we import the transformers package.
-            const transformers = await import('@huggingface/transformers');
+            // #565: `@huggingface/transformers` is NOT installed automatically (it
+            // transitively pulls onnxruntime-node -> adm-zip <0.6.0, GHSA-xcpc-8h2w-3j85,
+            // which upstream has not fixed). Users who want in-process embeddings opt in
+            // explicitly; everyone else uses an embedding endpoint. Translate the raw
+            // module-resolution failure into actionable guidance.
+            let transformers;
+            try {
+                transformers = await import('@huggingface/transformers');
+            }
+            catch {
+                throw new Error('In-process embeddings require the optional package "@huggingface/transformers", ' +
+                    'which is not installed. Either run `npm install @huggingface/transformers`, or ' +
+                    'configure an embedding endpoint (EmbeddingConfig.endpoint / AQE_EMBEDDING_ENDPOINT) ' +
+                    'so no local model is loaded.');
+            }
             pipeline = transformers.pipeline;
             console.log(`[RealEmbeddings] Loading model: ${fullConfig.modelName}`);
             const startTime = performance.now();