agentic-qe 3.13.12 → 3.14.1

package/dist/learning/sqlite-persistence.js

@@ -16,7 +16,8 @@ import { v4 as uuidv4 } from 'uuid';
 import { safeJsonParse } from '../shared/safe-json.js';
 import { toErrorMessage } from '../shared/error-utils.js';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
-import { computeBatchEmbeddings, getEmbeddingDimension, isUsingEndpoint, } from './real-embeddings.js';
+import { computeBatchEmbeddings, getEmbeddingDimension, isUsingEndpoint, getActiveEmbeddingSpaceIdentity, } from './real-embeddings.js';
+import { EMBEDDING_SPACE_CANARY, inspectEmbeddingSpaceRows, } from './embedding-space.js';
 import { recordPatternUsage } from './pattern-usage-recorder.js';
 export const DEFAULT_SQLITE_CONFIG = {
     // LEGACY: Ignored when useUnified=true (the default). All data goes to memory.db
@@ -106,6 +107,8 @@ export class SQLitePatternStore {
             }
             // Run deduplication migration (one-time, idempotent)
             this.deduplicatePatterns();
+            // Legacy rows remain NULL/unverified; only new writes receive provenance.
+            this.ensureEmbeddingSpaceSchema();
             // Prepare statements
             this.prepareStatements();
             this.initialized = true;
@@ -143,11 +146,12 @@ export class SQLitePatternStore {
       );
 
       -- Pattern embeddings table (BLOB storage for vectors)
-      CREATE TABLE IF NOT EXISTS qe_pattern_embeddings (
+      CREATE TABLE IF NOT EXISTS qe_pattern_embeddings (
         pattern_id TEXT PRIMARY KEY,
         embedding BLOB NOT NULL,
         dimension INTEGER NOT NULL,
-        model TEXT DEFAULT 'all-MiniLM-L6-v2',
+        model TEXT DEFAULT 'all-MiniLM-L6-v2',
+        space_id TEXT,
         created_at TEXT DEFAULT (datetime('now')),
         FOREIGN KEY (pattern_id) REFERENCES qe_patterns(id) ON DELETE CASCADE
       );
@@ -298,6 +302,15 @@ export class SQLitePatternStore {
     /**
      * Prepare commonly used statements
      */
+    ensureEmbeddingSpaceSchema() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const columns = this.db.prepare("PRAGMA table_info('qe_pattern_embeddings')").all();
+        if (!columns.some((column) => column.name === 'space_id')) {
+            this.db.exec('ALTER TABLE qe_pattern_embeddings ADD COLUMN space_id TEXT');
+        }
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_qe_pattern_embeddings_space ON qe_pattern_embeddings(space_id)');
+    }
     prepareStatements() {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -323,14 +336,14 @@ export class SQLitePatternStore {
         updated_at = datetime('now')
     `));
         this.prepared.set('insertEmbedding', this.db.prepare(`
-      INSERT OR REPLACE INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model)
-      VALUES (?, ?, ?, ?)
+      INSERT OR REPLACE INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, space_id)
+      VALUES (?, ?, ?, ?, ?)
     `));
         this.prepared.set('getPattern', this.db.prepare(`
       SELECT * FROM qe_patterns WHERE id = ?
     `));
         this.prepared.set('getPatternWithEmbedding', this.db.prepare(`
-      SELECT p.*, e.embedding, e.dimension
+      SELECT p.*, e.embedding, e.dimension, e.space_id
       FROM qe_patterns p
       LEFT JOIN qe_pattern_embeddings e ON p.id = e.pattern_id
       WHERE p.id = ?
@@ -360,13 +373,13 @@ export class SQLitePatternStore {
       SELECT * FROM qe_patterns WHERE qe_domain = ? ORDER BY quality_score DESC LIMIT ?
     `));
         this.prepared.set('getAllEmbeddings', this.db.prepare(`
-      SELECT pattern_id, embedding, dimension FROM qe_pattern_embeddings
+      SELECT pattern_id, embedding, dimension, space_id FROM qe_pattern_embeddings
     `));
         // Recent-first variant used by the RVF backfill path. Order by
         // qe_patterns.last_used_at (then created_at) so the bounded backfill keeps
         // the most actively-used patterns when the cap is hit.
         this.prepared.set('getRecentEmbeddings', this.db.prepare(`
-      SELECT e.pattern_id, e.embedding, e.dimension
+      SELECT e.pattern_id, e.embedding, e.dimension, e.space_id
         FROM qe_pattern_embeddings e
         LEFT JOIN qe_patterns p ON p.id = e.pattern_id
        ORDER BY COALESCE(p.last_used_at, p.created_at, e.created_at) DESC
@@ -382,7 +395,7 @@ export class SQLitePatternStore {
     /**
      * Store a pattern
      */
-    storePattern(pattern, embedding) {
+    storePattern(pattern, embedding, embeddingSpaceId) {
         if (!this.db)
             throw new Error('Database not initialized');
         const id = pattern.id || uuidv4();
@@ -405,9 +418,13 @@ export class SQLitePatternStore {
                 .get(pattern.name, pattern.qeDomain ?? '', pattern.patternType ?? '');
             actualId = actualRow ? actualRow.id : id;
             if (embedding) {
+                const spaceId = embeddingSpaceId ?? getActiveEmbeddingSpaceIdentity()?.spaceId;
+                if (!spaceId) {
+                    throw new Error('VECTOR_SPACE_UNVERIFIED: refusing to persist an embedding without runtime provenance');
+                }
                 // Store embedding as BLOB (Float32Array)
                 const buffer = Buffer.from(new Float32Array(embedding).buffer);
-                insertEmbedding.run(actualId, buffer, embedding.length, 'all-MiniLM-L6-v2');
+                insertEmbedding.run(actualId, buffer, embedding.length, 'all-MiniLM-L6-v2', spaceId);
             }
         });
         transaction();
@@ -529,6 +546,7 @@ export class SQLitePatternStore {
         return rows.map(row => ({
             patternId: row.pattern_id,
             embedding: Array.from(new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimension)),
+            spaceId: row.space_id,
         }));
     }
     /**
@@ -549,8 +567,15 @@ export class SQLitePatternStore {
         return rows.map(row => ({
             patternId: row.pattern_id,
             embedding: Array.from(new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimension)),
+            spaceId: row.space_id,
         }));
     }
+    getEmbeddingSpaceDiagnostics(activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? null) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const rows = this.db.prepare('SELECT space_id AS spaceId FROM qe_pattern_embeddings').all();
+        return inspectEmbeddingSpaceRows(rows, activeSpaceId);
+    }
     /**
      * Record pattern usage.
      *
@@ -788,7 +813,7 @@ export class SQLitePatternStore {
     /**
      * Store embedding for an existing pattern
      */
-    storePatternEmbedding(patternId, embedding) {
+    storePatternEmbedding(patternId, embedding, embeddingSpaceId) {
         if (!this.db)
             throw new Error('Database not initialized');
         const insertEmbedding = this.prepared.get('insertEmbedding');
@@ -797,7 +822,11 @@ export class SQLitePatternStore {
         }
         // Convert embedding to Buffer for storage
         const buffer = Buffer.from(new Float32Array(embedding).buffer);
-        insertEmbedding.run(patternId, buffer, embedding.length, 'all-MiniLM-L6-v2');
+        const spaceId = embeddingSpaceId ?? getActiveEmbeddingSpaceIdentity()?.spaceId;
+        if (!spaceId) {
+            throw new Error('VECTOR_SPACE_UNVERIFIED: refusing to persist an embedding without runtime provenance');
+        }
+        insertEmbedding.run(patternId, buffer, embedding.length, 'all-MiniLM-L6-v2', spaceId);
     }
     /**
      * Record pattern reuse for metrics tracking (Phase 5.4)
@@ -935,14 +964,22 @@ export class SQLitePatternStore {
         if (!this.db)
             throw new Error('Database not initialized');
         const dimension = getEmbeddingDimension(); // 384
-        // Find patterns without embeddings (skip bench patterns)
-        const patternsWithout = this.db.prepare(`
-      SELECT p.id, p.name, p.description, p.pattern_type, p.qe_domain
-      FROM qe_patterns p
-      WHERE p.id NOT IN (SELECT pattern_id FROM qe_pattern_embeddings)
-        AND p.id NOT LIKE 'bench-%'
-      ORDER BY p.quality_score DESC
-    `).all();
+        // Initialize the executable identity before choosing repair candidates.
+        // The canary is cached by the embedding layer and is never persisted.
+        await computeBatchEmbeddings([EMBEDDING_SPACE_CANARY]);
+        const activeSpaceId = getActiveEmbeddingSpaceIdentity()?.spaceId;
+        if (!activeSpaceId) {
+            throw new Error('VECTOR_SPACE_UNVERIFIED: backfill embedder has no runtime provenance');
+        }
+        // Repair absent, legacy/unverified, and mismatched embeddings.
+        const patternsWithout = this.db.prepare(`
+      SELECT p.id, p.name, p.description, p.pattern_type, p.qe_domain
+      FROM qe_patterns p
+      LEFT JOIN qe_pattern_embeddings e ON e.pattern_id = p.id
+      WHERE (e.pattern_id IS NULL OR e.space_id IS NULL OR e.space_id <> ?)
+        AND p.id NOT LIKE 'bench-%'
+      ORDER BY p.quality_score DESC
+    `).all(activeSpaceId);
         const alreadyHad = this.db.prepare(`
       SELECT COUNT(*) as c FROM qe_pattern_embeddings
     `).get();
@@ -1012,7 +1049,7 @@ export class SQLitePatternStore {
                             continue;
                         }
                         const buffer = Buffer.from(new Float32Array(embedding).buffer);
-                        insertEmbedding.run(textsWithIds[j].id, buffer, dimension, embeddingTag);
+                        insertEmbedding.run(textsWithIds[j].id, buffer, dimension, embeddingTag, activeSpaceId);
                         processed++;
                     }
                     catch (e) {

package/dist/learning/structural-retrieval/corpus.d.ts

@@ -0,0 +1,5 @@
+import type { StructuralRetrievalCorpus, StructuralTransformation } from './types.js';
+export declare function createStructuralRetrievalCorpus(): StructuralRetrievalCorpus;
+export declare const STRUCTURAL_RETRIEVAL_TRANSFORMATIONS: readonly StructuralTransformation[];
+export declare function verifyStructuralRetrievalCorpus(corpus: StructuralRetrievalCorpus): boolean;
+//# sourceMappingURL=corpus.d.ts.map

package/dist/learning/structural-retrieval/corpus.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+const REVISION = 'aqe-structural-transfer-2026-09-06';
+const TRANSFORMATIONS = [
+    'rename', 'framework-transfer', 'reordered-steps',
+    'distractor-terminology', 'cross-domain-transfer',
+];
+const SEEDS = [
+    ['async-race', 'observe completion before assertion', 'await the operation', 'increase the timeout', 'completion probe', 'unit', 'vitest'],
+    ['stale-cache', 'invalidate on every state mutation', 'invalidate the cache', 'retry the read', 'freshness assertion', 'integration', 'redis'],
+    ['transaction-leak', 'rollback isolates each test', 'rollback the transaction', 'truncate a shared table', 'row-count check', 'database', 'postgres'],
+    ['clock-skew', 'compare times in one clock domain', 'inject a monotonic clock', 'widen the time window', 'clock boundary check', 'unit', 'node'],
+    ['event-loss', 'subscribe before publishing', 'register the listener first', 'publish twice', 'delivery assertion', 'events', 'eventemitter'],
+    ['resource-leak', 'release resources on every exit', 'close in a finally block', 'raise the pool limit', 'handle-count check', 'integration', 'playwright'],
+    ['eventual-consistency', 'poll the observable state', 'poll with a bounded deadline', 'sleep for a fixed delay', 'state convergence', 'distributed', 'kubernetes'],
+    ['identity-confusion', 'compare canonical identities', 'normalize the identifier', 'use display names', 'identity equality', 'security', 'oauth'],
+    ['partial-write', 'publish only complete state', 'commit through an atomic swap', 'ignore missing fields', 'atomicity check', 'filesystem', 'node'],
+    ['order-dependence', 'tests start from isolated state', 'reset state in setup', 'force alphabetical order', 'shuffle repeat', 'unit', 'jest'],
+    ['schema-drift', 'validate at the boundary', 'reject the incompatible schema', 'cast the payload', 'schema validator', 'api', 'zod'],
+    ['backpressure-loss', 'producer respects consumer capacity', 'await the drain signal', 'increase buffer memory', 'loss counter', 'performance', 'streams'],
+    ['retry-duplication', 'retries preserve idempotency', 'attach an idempotency key', 'disable all retries', 'duplicate detector', 'api', 'fetch'],
+    ['permission-bypass', 'authorization precedes mutation', 'check permission before write', 'hide the user interface', 'denial assertion', 'security', 'express'],
+    ['encoding-mismatch', 'encode and decode with one charset', 'set UTF-8 explicitly', 'strip non-ASCII text', 'round-trip equality', 'api', 'json'],
+    ['pagination-gap', 'cursor advances from the last item', 'use the returned cursor', 'increase page size', 'set equality', 'api', 'graphql'],
+    ['cancellation-leak', 'cancellation propagates to children', 'forward the abort signal', 'wait for natural completion', 'abort observation', 'integration', 'abortcontroller'],
+    ['floating-point-boundary', 'compare numeric results by tolerance', 'use an error bound', 'round every input', 'relative-error check', 'unit', 'vitest'],
+    ['locale-dependence', 'format under an explicit locale', 'pass the locale explicitly', 'update the snapshot locally', 'multi-locale check', 'ui', 'intl'],
+    ['lock-starvation', 'lock acquisition remains fair', 'queue lock waiters', 'raise retry count', 'bounded-wait check', 'concurrency', 'mutex'],
+].map(([mechanism, invariant, action, wrongAction, oracle, domain, framework]) => ({
+    mechanism, invariant, action, wrongAction, oracle, domain, framework,
+}));
+function splitFor(index) {
+    if (index < 12)
+        return 'train';
+    if (index < 16)
+        return 'calibration';
+    return 'audit';
+}
+function stableHash(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function queryText(seed, transformation, index) {
+    const object = `component-${index + 41}`;
+    switch (transformation) {
+        case 'rename': return `${object} intermittently fails; ensure ${seed.invariant} by applying: ${seed.action}`;
+        case 'framework-transfer': return `In an alternative runtime, ${seed.mechanism} appears. Preserve this rule: ${seed.invariant}`;
+        case 'reordered-steps': return `Verify with ${seed.oracle}; first arrange the fixture, then ${seed.action}; fault: ${seed.mechanism}`;
+        case 'distractor-terminology': return `${seed.wrongAction} is tempting for ${seed.mechanism}, but the required invariant is ${seed.invariant}`;
+        case 'cross-domain-transfer': return `A ${seed.domain} workflow moved to service-${index}; reuse the mechanism ${seed.mechanism} and ${seed.action}`;
+    }
+}
+export function createStructuralRetrievalCorpus() {
+    const patterns = [];
+    const queries = [];
+    SEEDS.forEach((seed, index) => {
+        const familyId = `family-${String(index + 1).padStart(2, '0')}`;
+        const correctId = `${familyId}-structural`;
+        const distractorId = `${familyId}-surface-distractor`;
+        const counterexampleId = `${familyId}-counterexample`;
+        patterns.push({ id: correctId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: seed.mechanism, invariant: seed.invariant, actions: [seed.action], oracle: seed.oracle,
+            text: `${seed.framework} ${seed.domain} ${seed.mechanism}: ${seed.action}; verify ${seed.oracle}` }, { id: distractorId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: `symptom resembling ${seed.mechanism}`, invariant: 'mask the observed symptom',
+            actions: [seed.wrongAction], oracle: 'single rerun',
+            text: `${seed.framework} ${seed.domain} ${seed.mechanism}: ${seed.wrongAction}; quick ${seed.oracle}` }, { id: counterexampleId, familyId, framework: seed.framework, domain: seed.domain,
+            failureMechanism: seed.mechanism, invariant: `environment forbids ${seed.action}`,
+            actions: [`escalate instead of ${seed.action}`], oracle: 'environment constraint check',
+            text: `${seed.mechanism} ${seed.action} ${seed.framework}, but environment forbids the action` });
+        TRANSFORMATIONS.forEach((transformation) => queries.push({
+            id: `${familyId}-${transformation}`,
+            familyId,
+            split: splitFor(index),
+            transformation,
+            text: queryText(seed, transformation, index),
+            relevantPatternIds: [correctId],
+            mustNotRankAbove: [
+                { lowerPatternId: distractorId, higherPatternId: correctId },
+                { lowerPatternId: counterexampleId, higherPatternId: correctId },
+            ],
+        }));
+    });
+    const payload = { schemaVersion: 'aqe-structural-retrieval/v1', corpusRevision: REVISION, patterns, queries };
+    return deepFreeze({ ...payload, lineageHash: stableHash(payload) });
+}
+export const STRUCTURAL_RETRIEVAL_TRANSFORMATIONS = Object.freeze([...TRANSFORMATIONS]);
+export function verifyStructuralRetrievalCorpus(corpus) {
+    const { lineageHash: _lineageHash, ...payload } = corpus;
+    return stableHash(payload) === corpus.lineageHash;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/learning/structural-retrieval/evaluate.d.ts

@@ -0,0 +1,7 @@
+import type { QueryRetrievalResult, RetrievalDiagnostic, StructuralRetrievalCorpus, StructuralRetrievalQuery, StructuralRetrievalReport } from './types.js';
+export declare function diagnoseRetrieval(query: StructuralRetrievalQuery, result: QueryRetrievalResult, k: number): RetrievalDiagnostic;
+export declare function evaluateStructuralRetrieval(corpus: StructuralRetrievalCorpus, results: QueryRetrievalResult[], options: {
+    rankerVersion: string;
+    k?: number;
+}): StructuralRetrievalReport;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/learning/structural-retrieval/evaluate.js

@@ -0,0 +1,124 @@
+import { verifyStructuralRetrievalCorpus } from './corpus.js';
+function queryScores(query, result, k) {
+    const relevant = new Set(query.relevantPatternIds);
+    const rank = result.candidates.findIndex(candidate => relevant.has(candidate.patternId));
+    const topKHits = result.candidates.slice(0, k).filter(candidate => relevant.has(candidate.patternId)).length;
+    const idealCount = Math.min(k, relevant.size);
+    const dcg = result.candidates.slice(0, k).reduce((sum, candidate, index) => sum + (relevant.has(candidate.patternId) ? 1 / Math.log2(index + 2) : 0), 0);
+    const idcg = Array.from({ length: idealCount }, (_, index) => 1 / Math.log2(index + 2)).reduce((a, b) => a + b, 0);
+    const relevantScore = rank >= 0 ? result.candidates[rank].score : 0;
+    const bestWrong = Math.max(0, ...result.candidates.filter(c => !relevant.has(c.patternId)).map(c => c.score));
+    return {
+        recall: relevant.size === 0 ? 0 : topKHits / relevant.size,
+        hit: rank === 0 ? 1 : 0,
+        reciprocalRank: rank < 0 ? 0 : 1 / (rank + 1),
+        ndcg: idcg === 0 ? 0 : dcg / idcg,
+        margin: relevantScore - bestWrong,
+    };
+}
+function mean(values) {
+    return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function estimate(values, seed) {
+    if (values.length === 0)
+        return { value: 0, confidenceInterval: { lower: 0, upper: 0, level: 0.95 } };
+    let state = seed >>> 0;
+    const random = () => ((state = (1664525 * state + 1013904223) >>> 0) / 0x100000000);
+    const bootstraps = Array.from({ length: 1000 }, () => mean(Array.from({ length: values.length }, () => values[Math.floor(random() * values.length)]))).sort((a, b) => a - b);
+    return {
+        value: mean(values),
+        confidenceInterval: {
+            lower: bootstraps[Math.floor(bootstraps.length * 0.025)],
+            upper: bootstraps[Math.floor(bootstraps.length * 0.975)],
+            level: 0.95,
+        },
+    };
+}
+function metricSet(scores) {
+    return {
+        support: scores.length,
+        recallAtK: estimate(scores.map(s => s.recall), 11),
+        hitAt1: estimate(scores.map(s => s.hit), 13),
+        mrr: estimate(scores.map(s => s.reciprocalRank), 17),
+        ndcg: estimate(scores.map(s => s.ndcg), 19),
+        top1Margin: estimate(scores.map(s => s.margin), 23),
+    };
+}
+export function diagnoseRetrieval(query, result, k) {
+    const relevant = new Set(query.relevantPatternIds);
+    const relevantCandidates = result.candidates.slice(0, k).filter(c => relevant.has(c.patternId));
+    if (relevantCandidates.length === 0)
+        return 'not_retrieved';
+    if (!relevant.has(result.candidates[0]?.patternId ?? ''))
+        return 'retrieved_misranked';
+    const applied = result.appliedPatternIds ?? [];
+    if (applied.length === 0 || !applied.some(id => relevant.has(id)))
+        return 'ranked_not_used';
+    if (result.outcomeImproved !== true)
+        return 'used_no_benefit';
+    return 'success';
+}
+export function evaluateStructuralRetrieval(corpus, results, options) {
+    const k = options.k ?? 10;
+    if (!Number.isInteger(k) || k < 1)
+        throw new Error('k must be a positive integer');
+    if (!verifyStructuralRetrievalCorpus(corpus))
+        throw new Error('corpus lineage hash mismatch');
+    if (results.length !== corpus.queries.length) {
+        throw new Error('results must contain exactly one entry for every corpus query');
+    }
+    const byQuery = new Map(results.map(result => [result.queryId, result]));
+    if (byQuery.size !== corpus.queries.length || corpus.queries.some(query => !byQuery.has(query.id))) {
+        throw new Error('results must contain exactly one entry for every corpus query');
+    }
+    const knownPatterns = new Set(corpus.patterns.map(pattern => pattern.id));
+    for (const result of results) {
+        const candidateIds = new Set();
+        for (const candidate of result.candidates) {
+            if (!knownPatterns.has(candidate.patternId))
+                throw new Error(`unknown candidate pattern: ${candidate.patternId}`);
+            if (!Number.isFinite(candidate.score))
+                throw new Error(`candidate score must be finite: ${candidate.patternId}`);
+            if (candidateIds.has(candidate.patternId))
+                throw new Error(`duplicate candidate pattern: ${candidate.patternId}`);
+            candidateIds.add(candidate.patternId);
+        }
+        for (const appliedId of result.appliedPatternIds ?? []) {
+            if (!candidateIds.has(appliedId))
+                throw new Error(`applied pattern was not a candidate: ${appliedId}`);
+        }
+    }
+    const rows = corpus.queries.map(query => {
+        const result = byQuery.get(query.id);
+        return { query, result, scores: queryScores(query, result, k) };
+    });
+    const diagnosticNames = [
+        'success', 'not_retrieved', 'retrieved_misranked', 'ranked_not_used', 'used_no_benefit',
+    ];
+    const diagnostics = Object.fromEntries(diagnosticNames.map(name => [name, 0]));
+    for (const row of rows)
+        diagnostics[diagnoseRetrieval(row.query, row.result, k)] += 1;
+    const relationViolations = rows.reduce((count, { query, result }) => {
+        const ranks = new Map(result.candidates.map((candidate, index) => [candidate.patternId, index]));
+        return count + query.mustNotRankAbove.filter(relation => {
+            const low = ranks.get(relation.lowerPatternId);
+            const high = ranks.get(relation.higherPatternId);
+            return low !== undefined && (high === undefined || low < high);
+        }).length;
+    }, 0);
+    const slices = {};
+    for (const transformation of new Set(corpus.queries.map(query => query.transformation))) {
+        slices[transformation] = metricSet(rows.filter(row => row.query.transformation === transformation).map(row => row.scores));
+    }
+    return {
+        corpusRevision: corpus.corpusRevision,
+        corpusLineageHash: corpus.lineageHash,
+        rankerVersion: options.rankerVersion,
+        k,
+        overall: metricSet(rows.map(row => row.scores)),
+        slices,
+        diagnostics,
+        relationViolations,
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/learning/structural-retrieval/index.d.ts

@@ -0,0 +1,6 @@
+export { createStructuralRetrievalCorpus, verifyStructuralRetrievalCorpus, STRUCTURAL_RETRIEVAL_TRANSFORMATIONS, } from './corpus.js';
+export { diagnoseRetrieval, evaluateStructuralRetrieval } from './evaluate.js';
+export { createRetrievalReceipt } from './receipt.js';
+export type * from './types.js';
+export type { CreateRetrievalReceiptInput } from './receipt.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/learning/structural-retrieval/index.js

@@ -0,0 +1,4 @@
+export { createStructuralRetrievalCorpus, verifyStructuralRetrievalCorpus, STRUCTURAL_RETRIEVAL_TRANSFORMATIONS, } from './corpus.js';
+export { diagnoseRetrieval, evaluateStructuralRetrieval } from './evaluate.js';
+export { createRetrievalReceipt } from './receipt.js';
+//# sourceMappingURL=index.js.map

package/dist/learning/structural-retrieval/receipt.d.ts

@@ -0,0 +1,14 @@
+import type { RankedCandidate, RetrievalReceipt } from './types.js';
+export interface CreateRetrievalReceiptInput {
+    revision: string;
+    queryId: string;
+    queryRepresentationVersion: string;
+    embeddingSpaceId: string;
+    rankerVersion: string;
+    candidates: RankedCandidate[];
+    appliedPatternIds?: string[];
+    outcomeRef?: string | null;
+    outcomeImproved?: boolean | null;
+}
+export declare function createRetrievalReceipt(input: CreateRetrievalReceiptInput): RetrievalReceipt;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/learning/structural-retrieval/receipt.js

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto';
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+export function createRetrievalReceipt(input) {
+    if (!input.revision || !input.queryId || !input.queryRepresentationVersion || !input.embeddingSpaceId || !input.rankerVersion) {
+        throw new Error('retrieval receipt provenance fields must be non-empty');
+    }
+    const candidateIds = new Set(input.candidates.map(candidate => candidate.patternId));
+    if (candidateIds.size !== input.candidates.length || input.candidates.some(candidate => !candidate.patternId || !Number.isFinite(candidate.score))) {
+        throw new Error('retrieval receipt candidates must have an id and finite score');
+    }
+    if ((input.appliedPatternIds ?? []).some(id => !candidateIds.has(id))) {
+        throw new Error('retrieval receipt applied patterns must be present in candidates');
+    }
+    const payload = {
+        schemaVersion: 'aqe-retrieval-receipt/v1',
+        revision: input.revision,
+        queryId: input.queryId,
+        queryRepresentationVersion: input.queryRepresentationVersion,
+        embeddingSpaceId: input.embeddingSpaceId,
+        rankerVersion: input.rankerVersion,
+        candidates: input.candidates.map(candidate => ({ ...candidate })),
+        appliedPatternIds: [...(input.appliedPatternIds ?? [])],
+        outcomeRef: input.outcomeRef ?? null,
+        outcomeImproved: input.outcomeImproved ?? null,
+    };
+    const receiptId = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+    return deepFreeze({ ...payload, receiptId });
+}
+//# sourceMappingURL=receipt.js.map

package/dist/learning/structural-retrieval/types.d.ts

@@ -0,0 +1,83 @@
+export type StructuralTransformation = 'rename' | 'framework-transfer' | 'reordered-steps' | 'distractor-terminology' | 'cross-domain-transfer';
+export type CorpusSplit = 'train' | 'calibration' | 'audit';
+export interface StructuralPattern {
+    id: string;
+    familyId: string;
+    framework: string;
+    domain: string;
+    failureMechanism: string;
+    invariant: string;
+    actions: string[];
+    oracle: string;
+    text: string;
+}
+export interface StructuralRetrievalQuery {
+    id: string;
+    familyId: string;
+    split: CorpusSplit;
+    transformation: StructuralTransformation;
+    text: string;
+    relevantPatternIds: string[];
+    mustNotRankAbove: Array<{
+        lowerPatternId: string;
+        higherPatternId: string;
+    }>;
+}
+export interface StructuralRetrievalCorpus {
+    schemaVersion: 'aqe-structural-retrieval/v1';
+    corpusRevision: string;
+    lineageHash: string;
+    patterns: StructuralPattern[];
+    queries: StructuralRetrievalQuery[];
+}
+export interface RankedCandidate {
+    patternId: string;
+    score: number;
+}
+export type RetrievalDiagnostic = 'success' | 'not_retrieved' | 'retrieved_misranked' | 'ranked_not_used' | 'used_no_benefit';
+export interface QueryRetrievalResult {
+    queryId: string;
+    candidates: RankedCandidate[];
+    appliedPatternIds?: string[];
+    outcomeImproved?: boolean;
+}
+export interface MetricEstimate {
+    value: number;
+    confidenceInterval: {
+        lower: number;
+        upper: number;
+        level: 0.95;
+    };
+}
+export interface RetrievalMetricSet {
+    support: number;
+    recallAtK: MetricEstimate;
+    hitAt1: MetricEstimate;
+    mrr: MetricEstimate;
+    ndcg: MetricEstimate;
+    top1Margin: MetricEstimate;
+}
+export interface StructuralRetrievalReport {
+    corpusRevision: string;
+    corpusLineageHash: string;
+    rankerVersion: string;
+    k: number;
+    overall: RetrievalMetricSet;
+    slices: Partial<Record<StructuralTransformation, RetrievalMetricSet>>;
+    diagnostics: Record<RetrievalDiagnostic, number>;
+    relationViolations: number;
+}
+export interface RetrievalReceipt {
+    schemaVersion: 'aqe-retrieval-receipt/v1';
+    receiptId: string;
+    revision: string;
+    queryId: string;
+    queryRepresentationVersion: string;
+    embeddingSpaceId: string;
+    rankerVersion: string;
+    candidates: RankedCandidate[];
+    appliedPatternIds: string[];
+    outcomeRef: string | null;
+    outcomeImproved: boolean | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/learning/structural-retrieval/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map