agentic-qe 3.13.11 → 3.14.0

package/dist/mcp/handlers/memory-handlers.js

@@ -75,12 +75,16 @@ export async function handleMemoryStore(params) {
         }
         catch {
             // Non-critical — KV store succeeded, vector indexing is best-effort
-            console.warn('[MemoryHandler] VECTOR_INDEX_UNAVAILABLE: Semantic vector indexing is unavailable for this entry.');
+            const vectorUnavailableMessage = 'Semantic vector indexing is unavailable for this entry. Configure AQE_EMBEDDER_ENDPOINT ' +
+                'for the recommended remote backend. The compatible local @huggingface/transformers@4.2.0 ' +
+                'dependency chain currently has unresolved HIGH advisories ' +
+                'GHSA-xcpc-8h2w-3j85 and GHSA-f88m-g3jw-g9cj.';
+            console.warn(`[MemoryHandler] VECTOR_INDEX_UNAVAILABLE: ${vectorUnavailableMessage}`);
             vectorIndex = {
                 status: 'failed',
                 error: {
                     code: 'VECTOR_INDEX_UNAVAILABLE',
-                    message: 'Semantic vector indexing is unavailable for this entry.',
+                    message: vectorUnavailableMessage,
                 },
             };
         }

package/dist/migrations/20260830_add_learning_evidence_tables.d.ts

@@ -0,0 +1,7 @@
+import type { Database as DatabaseType } from 'better-sqlite3';
+export declare const MIGRATION_VERSION = "20260830_add_learning_evidence_tables";
+export declare const LEARNING_EVIDENCE_SCHEMA = "\n  CREATE TABLE IF NOT EXISTS learning_evidence_manifests (\n    id TEXT PRIMARY KEY,\n    trajectory_id TEXT,\n    trajectory_hash TEXT,\n    manifest_hash TEXT NOT NULL UNIQUE,\n    task_family TEXT NOT NULL,\n    task_identity TEXT,\n    run_identity TEXT,\n    correlation_group TEXT,\n    dedupe_fingerprint TEXT,\n    revision TEXT,\n    environment TEXT,\n    outcome TEXT NOT NULL CHECK (outcome IN ('verified-success','verified-failure','unknown')),\n    oracle_refs_json TEXT NOT NULL DEFAULT '[]',\n    source_kind TEXT NOT NULL CHECK (source_kind IN ('executed','static','human-reviewed','inferred')),\n    process_signals_json TEXT NOT NULL DEFAULT '{}',\n    manifest_version INTEGER NOT NULL DEFAULT 1,\n    created_at TEXT NOT NULL DEFAULT (datetime('now'))\n  );\n\n  CREATE TABLE IF NOT EXISTS learning_evidence_segments (\n    id TEXT NOT NULL,\n    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,\n    segment_order INTEGER NOT NULL,\n    kind TEXT NOT NULL CHECK (kind IN ('observe','decide','act','verify','recover','other')),\n    contribution TEXT NOT NULL CHECK (contribution IN ('causal','supporting','irrelevant','harmful','unknown')),\n    evidence_refs_json TEXT NOT NULL DEFAULT '[]',\n    admit_for_learning INTEGER NOT NULL CHECK (admit_for_learning IN (0,1)),\n    reasons_json TEXT NOT NULL DEFAULT '[]',\n    content_hash TEXT,\n    PRIMARY KEY (manifest_id, id),\n    UNIQUE (manifest_id, segment_order)\n  );\n\n  CREATE TABLE IF NOT EXISTS learning_segment_edges (\n    manifest_id TEXT NOT NULL,\n    parent_segment_id TEXT NOT NULL,\n    child_segment_id TEXT NOT NULL,\n    edge_kind TEXT NOT NULL DEFAULT 'depends-on',\n    PRIMARY KEY (manifest_id, parent_segment_id, child_segment_id, edge_kind),\n    FOREIGN KEY (manifest_id, parent_segment_id)\n      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT,\n    FOREIGN KEY (manifest_id, child_segment_id)\n      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT,\n    CHECK (parent_segment_id <> child_segment_id)\n  );\n\n  CREATE TABLE IF NOT EXISTS learning_evidence_admissions (\n    id TEXT PRIMARY KEY,\n    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,\n    decision_seq INTEGER NOT NULL CHECK (decision_seq > 0),\n    disposition TEXT NOT NULL CHECK (disposition IN ('admitted','rejected','review-required','legacy-unknown')),\n    reason_codes_json TEXT NOT NULL DEFAULT '[]',\n    assessor_kind TEXT NOT NULL CHECK (assessor_kind IN ('executed','static','human-reviewed','inferred')),\n    evidence_class TEXT NOT NULL CHECK (evidence_class IN ('EXECUTED','STATIC','INFERRED','CONJECTURE')),\n    policy_version TEXT,\n    policy_hash TEXT,\n    created_at TEXT NOT NULL DEFAULT (datetime('now')),\n    UNIQUE (manifest_id, decision_seq)\n  );\n\n  CREATE TABLE IF NOT EXISTS pattern_manifest_lineage (\n    pattern_id TEXT NOT NULL REFERENCES qe_patterns(id) ON DELETE RESTRICT,\n    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,\n    pattern_version_id TEXT,\n    use_kind TEXT NOT NULL CHECK (use_kind IN ('candidate-source','promotion-support','rejection','rollback','legacy-context')),\n    created_at TEXT NOT NULL DEFAULT (datetime('now')),\n    PRIMARY KEY (pattern_id, manifest_id, use_kind)\n  );\n\n  CREATE TABLE IF NOT EXISTS pattern_segment_lineage (\n    pattern_id TEXT NOT NULL REFERENCES qe_patterns(id) ON DELETE RESTRICT,\n    manifest_id TEXT NOT NULL,\n    segment_id TEXT NOT NULL,\n    pattern_version_id TEXT,\n    use_kind TEXT NOT NULL CHECK (use_kind IN ('candidate-source','promotion-support','rejection','rollback')),\n    created_at TEXT NOT NULL DEFAULT (datetime('now')),\n    PRIMARY KEY (pattern_id, manifest_id, segment_id, use_kind),\n    FOREIGN KEY (manifest_id, segment_id)\n      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT\n  );\n\n  CREATE INDEX IF NOT EXISTS idx_learning_manifest_trajectory ON learning_evidence_manifests(trajectory_id);\n  CREATE INDEX IF NOT EXISTS idx_learning_manifest_task ON learning_evidence_manifests(task_family);\n  CREATE INDEX IF NOT EXISTS idx_learning_manifest_dedupe ON learning_evidence_manifests(dedupe_fingerprint);\n  CREATE INDEX IF NOT EXISTS idx_learning_manifest_correlation ON learning_evidence_manifests(correlation_group);\n  CREATE INDEX IF NOT EXISTS idx_learning_manifest_outcome ON learning_evidence_manifests(outcome, source_kind);\n  CREATE INDEX IF NOT EXISTS idx_learning_admission_manifest ON learning_evidence_admissions(manifest_id, decision_seq DESC);\n  CREATE INDEX IF NOT EXISTS idx_pattern_manifest_lineage_manifest ON pattern_manifest_lineage(manifest_id);\n  CREATE INDEX IF NOT EXISTS idx_pattern_segment_lineage_manifest ON pattern_segment_lineage(manifest_id, segment_id);\n\n  CREATE TRIGGER IF NOT EXISTS learning_manifests_no_update BEFORE UPDATE ON learning_evidence_manifests\n  BEGIN SELECT RAISE(ABORT, 'learning evidence manifests are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_manifests_no_delete BEFORE DELETE ON learning_evidence_manifests\n  BEGIN SELECT RAISE(ABORT, 'learning evidence manifests are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_segments_no_update BEFORE UPDATE ON learning_evidence_segments\n  BEGIN SELECT RAISE(ABORT, 'learning evidence segments are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_segments_no_delete BEFORE DELETE ON learning_evidence_segments\n  BEGIN SELECT RAISE(ABORT, 'learning evidence segments are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_edges_no_update BEFORE UPDATE ON learning_segment_edges\n  BEGIN SELECT RAISE(ABORT, 'learning evidence edges are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_edges_no_delete BEFORE DELETE ON learning_segment_edges\n  BEGIN SELECT RAISE(ABORT, 'learning evidence edges are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_admissions_no_update BEFORE UPDATE ON learning_evidence_admissions\n  BEGIN SELECT RAISE(ABORT, 'learning evidence admissions are append-only'); END;\n  CREATE TRIGGER IF NOT EXISTS learning_admissions_no_delete BEFORE DELETE ON learning_evidence_admissions\n  BEGIN SELECT RAISE(ABORT, 'learning evidence admissions are append-only'); END;\n";
+export declare function applyMigration(db: DatabaseType): void;
+export declare function isMigrationApplied(db: DatabaseType): boolean;
+export declare function rollbackMigration(db: DatabaseType): void;
+//# sourceMappingURL=20260830_add_learning_evidence_tables.d.ts.map

package/dist/migrations/20260830_add_learning_evidence_tables.js

@@ -0,0 +1,173 @@
+export const MIGRATION_VERSION = '20260830_add_learning_evidence_tables';
+export const LEARNING_EVIDENCE_SCHEMA = `
+  CREATE TABLE IF NOT EXISTS learning_evidence_manifests (
+    id TEXT PRIMARY KEY,
+    trajectory_id TEXT,
+    trajectory_hash TEXT,
+    manifest_hash TEXT NOT NULL UNIQUE,
+    task_family TEXT NOT NULL,
+    task_identity TEXT,
+    run_identity TEXT,
+    correlation_group TEXT,
+    dedupe_fingerprint TEXT,
+    revision TEXT,
+    environment TEXT,
+    outcome TEXT NOT NULL CHECK (outcome IN ('verified-success','verified-failure','unknown')),
+    oracle_refs_json TEXT NOT NULL DEFAULT '[]',
+    source_kind TEXT NOT NULL CHECK (source_kind IN ('executed','static','human-reviewed','inferred')),
+    process_signals_json TEXT NOT NULL DEFAULT '{}',
+    manifest_version INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE TABLE IF NOT EXISTS learning_evidence_segments (
+    id TEXT NOT NULL,
+    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,
+    segment_order INTEGER NOT NULL,
+    kind TEXT NOT NULL CHECK (kind IN ('observe','decide','act','verify','recover','other')),
+    contribution TEXT NOT NULL CHECK (contribution IN ('causal','supporting','irrelevant','harmful','unknown')),
+    evidence_refs_json TEXT NOT NULL DEFAULT '[]',
+    admit_for_learning INTEGER NOT NULL CHECK (admit_for_learning IN (0,1)),
+    reasons_json TEXT NOT NULL DEFAULT '[]',
+    content_hash TEXT,
+    PRIMARY KEY (manifest_id, id),
+    UNIQUE (manifest_id, segment_order)
+  );
+
+  CREATE TABLE IF NOT EXISTS learning_segment_edges (
+    manifest_id TEXT NOT NULL,
+    parent_segment_id TEXT NOT NULL,
+    child_segment_id TEXT NOT NULL,
+    edge_kind TEXT NOT NULL DEFAULT 'depends-on',
+    PRIMARY KEY (manifest_id, parent_segment_id, child_segment_id, edge_kind),
+    FOREIGN KEY (manifest_id, parent_segment_id)
+      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT,
+    FOREIGN KEY (manifest_id, child_segment_id)
+      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT,
+    CHECK (parent_segment_id <> child_segment_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS learning_evidence_admissions (
+    id TEXT PRIMARY KEY,
+    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,
+    decision_seq INTEGER NOT NULL CHECK (decision_seq > 0),
+    disposition TEXT NOT NULL CHECK (disposition IN ('admitted','rejected','review-required','legacy-unknown')),
+    reason_codes_json TEXT NOT NULL DEFAULT '[]',
+    assessor_kind TEXT NOT NULL CHECK (assessor_kind IN ('executed','static','human-reviewed','inferred')),
+    evidence_class TEXT NOT NULL CHECK (evidence_class IN ('EXECUTED','STATIC','INFERRED','CONJECTURE')),
+    policy_version TEXT,
+    policy_hash TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE (manifest_id, decision_seq)
+  );
+
+  CREATE TABLE IF NOT EXISTS pattern_manifest_lineage (
+    pattern_id TEXT NOT NULL REFERENCES qe_patterns(id) ON DELETE RESTRICT,
+    manifest_id TEXT NOT NULL REFERENCES learning_evidence_manifests(id) ON DELETE RESTRICT,
+    pattern_version_id TEXT,
+    use_kind TEXT NOT NULL CHECK (use_kind IN ('candidate-source','promotion-support','rejection','rollback','legacy-context')),
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (pattern_id, manifest_id, use_kind)
+  );
+
+  CREATE TABLE IF NOT EXISTS pattern_segment_lineage (
+    pattern_id TEXT NOT NULL REFERENCES qe_patterns(id) ON DELETE RESTRICT,
+    manifest_id TEXT NOT NULL,
+    segment_id TEXT NOT NULL,
+    pattern_version_id TEXT,
+    use_kind TEXT NOT NULL CHECK (use_kind IN ('candidate-source','promotion-support','rejection','rollback')),
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (pattern_id, manifest_id, segment_id, use_kind),
+    FOREIGN KEY (manifest_id, segment_id)
+      REFERENCES learning_evidence_segments(manifest_id, id) ON DELETE RESTRICT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_learning_manifest_trajectory ON learning_evidence_manifests(trajectory_id);
+  CREATE INDEX IF NOT EXISTS idx_learning_manifest_task ON learning_evidence_manifests(task_family);
+  CREATE INDEX IF NOT EXISTS idx_learning_manifest_dedupe ON learning_evidence_manifests(dedupe_fingerprint);
+  CREATE INDEX IF NOT EXISTS idx_learning_manifest_correlation ON learning_evidence_manifests(correlation_group);
+  CREATE INDEX IF NOT EXISTS idx_learning_manifest_outcome ON learning_evidence_manifests(outcome, source_kind);
+  CREATE INDEX IF NOT EXISTS idx_learning_admission_manifest ON learning_evidence_admissions(manifest_id, decision_seq DESC);
+  CREATE INDEX IF NOT EXISTS idx_pattern_manifest_lineage_manifest ON pattern_manifest_lineage(manifest_id);
+  CREATE INDEX IF NOT EXISTS idx_pattern_segment_lineage_manifest ON pattern_segment_lineage(manifest_id, segment_id);
+
+  CREATE TRIGGER IF NOT EXISTS learning_manifests_no_update BEFORE UPDATE ON learning_evidence_manifests
+  BEGIN SELECT RAISE(ABORT, 'learning evidence manifests are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_manifests_no_delete BEFORE DELETE ON learning_evidence_manifests
+  BEGIN SELECT RAISE(ABORT, 'learning evidence manifests are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_segments_no_update BEFORE UPDATE ON learning_evidence_segments
+  BEGIN SELECT RAISE(ABORT, 'learning evidence segments are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_segments_no_delete BEFORE DELETE ON learning_evidence_segments
+  BEGIN SELECT RAISE(ABORT, 'learning evidence segments are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_edges_no_update BEFORE UPDATE ON learning_segment_edges
+  BEGIN SELECT RAISE(ABORT, 'learning evidence edges are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_edges_no_delete BEFORE DELETE ON learning_segment_edges
+  BEGIN SELECT RAISE(ABORT, 'learning evidence edges are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_admissions_no_update BEFORE UPDATE ON learning_evidence_admissions
+  BEGIN SELECT RAISE(ABORT, 'learning evidence admissions are append-only'); END;
+  CREATE TRIGGER IF NOT EXISTS learning_admissions_no_delete BEFORE DELETE ON learning_evidence_admissions
+  BEGIN SELECT RAISE(ABORT, 'learning evidence admissions are append-only'); END;
+`;
+export function applyMigration(db) {
+    db.exec(LEARNING_EVIDENCE_SCHEMA);
+    db.exec(`
+    INSERT OR IGNORE INTO learning_evidence_manifests (
+      id, trajectory_id, trajectory_hash, manifest_hash, task_family,
+      outcome, oracle_refs_json, source_kind, process_signals_json
+    )
+    SELECT
+      'legacy-pattern:' || id, NULL, NULL, 'legacy-pattern:' || id,
+      COALESCE(NULLIF(qe_domain, ''), NULLIF(domain, ''), 'unknown'),
+      'unknown', '[]', 'inferred', '{"legacy":true,"unassessed":true}'
+    FROM qe_patterns;
+
+    INSERT OR IGNORE INTO learning_evidence_admissions (
+      id, manifest_id, decision_seq, disposition, reason_codes_json,
+      assessor_kind, evidence_class
+    )
+    SELECT
+      'legacy-admission:' || id, 'legacy-pattern:' || id, 1, 'legacy-unknown',
+      '["legacy-pattern-without-qualified-trajectory"]', 'inferred', 'INFERRED'
+    FROM qe_patterns;
+
+    INSERT OR IGNORE INTO pattern_manifest_lineage (
+      pattern_id, manifest_id, use_kind
+    )
+    SELECT id, 'legacy-pattern:' || id, 'legacy-context' FROM qe_patterns;
+  `);
+}
+export function isMigrationApplied(db) {
+    const required = [
+        'learning_evidence_manifests', 'learning_evidence_segments',
+        'learning_segment_edges', 'learning_evidence_admissions',
+        'pattern_manifest_lineage', 'pattern_segment_lineage',
+    ];
+    const rows = db.prepare(`
+    SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${required.map(() => '?').join(',')})
+  `).all(...required);
+    return rows.length === required.length;
+}
+export function rollbackMigration(db) {
+    const tables = [
+        'learning_evidence_manifests', 'learning_evidence_segments',
+        'learning_segment_edges', 'learning_evidence_admissions',
+        'pattern_manifest_lineage', 'pattern_segment_lineage',
+    ];
+    for (const table of tables) {
+        const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table);
+        if (!exists)
+            continue;
+        const count = db.prepare(`SELECT COUNT(*) AS count FROM ${table}`).get().count;
+        if (count > 0)
+            throw new Error(`REFUSING rollback: ${table} contains ${count} learning evidence row(s)`);
+    }
+    db.exec(`
+    DROP TABLE IF EXISTS pattern_segment_lineage;
+    DROP TABLE IF EXISTS pattern_manifest_lineage;
+    DROP TABLE IF EXISTS learning_evidence_admissions;
+    DROP TABLE IF EXISTS learning_segment_edges;
+    DROP TABLE IF EXISTS learning_evidence_segments;
+    DROP TABLE IF EXISTS learning_evidence_manifests;
+  `);
+}
+//# sourceMappingURL=20260830_add_learning_evidence_tables.js.map

package/dist/persistence/rvf-migration-adapter.d.ts

@@ -26,6 +26,8 @@ export interface MigrationAdapterConfig {
     dimensions: number;
     /** Enable fallback on RVF read failure in stage 3+ */
     enableFallback: boolean;
+    /** Runtime provenance for injected embedding pipelines. */
+    embeddingSpaceId?: string;
 }
 export interface WriteResult {
     sqliteSuccess: boolean;

package/dist/persistence/rvf-migration-adapter.js

@@ -14,6 +14,7 @@
  *
  * @module persistence/rvf-migration-adapter
  */
+import { getActiveEmbeddingSpaceIdentity } from '../learning/real-embeddings.js';
 export const STAGE_NAMES = {
     0: 'sqlite-only',
     1: 'hybrid',
@@ -80,6 +81,12 @@ export class RvfMigrationAdapter {
             stage: this.config.stage,
             fallbackUsed: false,
         };
+        const hasSpaceContract = this.db
+            ? this.db.prepare("PRAGMA table_info('qe_pattern_embeddings')").all().some((row) => row.name === 'space_id')
+            : false;
+        const spaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId;
+        if (!hasSpaceContract || !spaceId)
+            return result;
         const shouldWriteSqlite = this.config.stage < 4;
         const shouldWriteRvf = this.config.stage >= 2;
         // Write to SQLite
@@ -87,12 +94,23 @@ export class RvfMigrationAdapter {
             const start = performance.now();
             try {
                 const blob = Buffer.from(vector instanceof Float32Array ? vector.buffer : new Float32Array(vector).buffer);
-                this.db.prepare(`
-          INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
-          VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
-          ON CONFLICT(pattern_id) DO UPDATE SET
-            embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
-        `).run(id, blob, vector.length);
+                if (hasSpaceContract) {
+                    this.db.prepare(`
+            INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, space_id, created_at)
+            VALUES (?, ?, ?, 'all-MiniLM-L6-v2', ?, datetime('now'))
+            ON CONFLICT(pattern_id) DO UPDATE SET
+              embedding = excluded.embedding, dimension = excluded.dimension,
+              space_id = excluded.space_id, created_at = datetime('now')
+          `).run(id, blob, vector.length, spaceId);
+                }
+                else {
+                    this.db.prepare(`
+            INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
+            VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
+            ON CONFLICT(pattern_id) DO UPDATE SET
+              embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
+          `).run(id, blob, vector.length);
+                }
                 result.sqliteSuccess = true;
                 this.sqliteWriteLatencies.push(performance.now() - start);
             }
@@ -120,12 +138,23 @@ export class RvfMigrationAdapter {
         if (this.config.stage === 4 && !result.rvfSuccess && this.config.enableFallback && this.db) {
             try {
                 const blob = Buffer.from(vector instanceof Float32Array ? vector.buffer : new Float32Array(vector).buffer);
-                this.db.prepare(`
-          INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
-          VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
-          ON CONFLICT(pattern_id) DO UPDATE SET
-            embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
-        `).run(id, blob, vector.length);
+                if (hasSpaceContract) {
+                    this.db.prepare(`
+            INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, space_id, created_at)
+            VALUES (?, ?, ?, 'all-MiniLM-L6-v2', ?, datetime('now'))
+            ON CONFLICT(pattern_id) DO UPDATE SET
+              embedding = excluded.embedding, dimension = excluded.dimension,
+              space_id = excluded.space_id, created_at = datetime('now')
+          `).run(id, blob, vector.length, spaceId);
+                }
+                else {
+                    this.db.prepare(`
+            INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
+            VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
+            ON CONFLICT(pattern_id) DO UPDATE SET
+              embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
+          `).run(id, blob, vector.length);
+                }
                 result.sqliteSuccess = true;
                 result.fallbackUsed = true;
                 this.fallbacksUsed++;
@@ -177,6 +206,21 @@ export class RvfMigrationAdapter {
     search(query, k) {
         this.totalReads++;
         const useRvf = this.config.stage >= 3;
+        if (this.db) {
+            const hasSpaceContract = this.db.prepare("PRAGMA table_info('qe_pattern_embeddings')").all().some((row) => row.name === 'space_id');
+            if (!hasSpaceContract) {
+                return { data: null, source: useRvf ? 'rvf' : 'sqlite', latencyMs: 0, stage: this.config.stage };
+            }
+            {
+                const spaceId = getActiveEmbeddingSpaceIdentity()?.spaceId ?? this.config.embeddingSpaceId;
+                const incompatible = spaceId
+                    ? this.db.prepare('SELECT COUNT(*) AS count FROM qe_pattern_embeddings WHERE space_id IS NULL OR space_id <> ?').get(spaceId).count
+                    : 1;
+                if (incompatible > 0) {
+                    return { data: null, source: useRvf ? 'rvf' : 'sqlite', latencyMs: 0, stage: this.config.stage };
+                }
+            }
+        }
         if (useRvf && this.rvfStore) {
             const start = performance.now();
             try {

package/dist/shared/llm/billing-modes.d.ts

@@ -11,6 +11,11 @@ import type { BillingMode, LLMProvider, LLMProviderType } from './interfaces';
  * Resolve a provider's billing mode: the instance's own `billingMode` wins,
  * else the per-type default, else `metered-api` (the safe, cap-requiring
  * assumption for an unknown provider).
+ *
+ * ADR-127: an external provider is expected to declare `billingMode` on the
+ * instance, which is why the instance's own value is consulted first. When it
+ * declares nothing it lands on `metered-api` and therefore requires a budget,
+ * rather than being silently treated as free.
  */
 export declare function resolveBillingMode(provider: Pick<LLMProvider, 'type' | 'billingMode'>): BillingMode;
 /** Resolve a billing mode from a bare provider type. */

package/dist/shared/llm/billing-modes.js

@@ -6,7 +6,19 @@
  * kernel, `aqe health`) can resolve a billing mode without constructing a
  * provider, and so a provider that doesn't set `billingMode` still resolves.
  */
-/** Default billing mode per provider type. */
+import { isBuiltinProviderType } from './interfaces.js';
+import { registeredBillingDeclaration } from './provider-registry.js';
+/**
+ * Default billing mode per built-in provider type.
+ *
+ * ADR-127: keyed on `BuiltinProviderType`, not `LLMProviderType`, for two
+ * reasons: adding a built-in provider must still fail the build until this map
+ * is updated, and a lookup by an open `LLMProviderType` must type as
+ * `BillingMode | undefined` so the `?? 'metered-api'` fallback below is
+ * actually forced rather than merely present. An external provider registered
+ * per ADR-127 has no entry here and therefore falls through to `metered-api` —
+ * the conservative, cap-requiring assumption.
+ */
 const BILLING_MODE_BY_TYPE = {
     claude: 'metered-api',
     'claude-code': 'subscription',
@@ -19,17 +31,29 @@ const BILLING_MODE_BY_TYPE = {
     cognitum: 'metered-capped',
     ollama: 'local',
 };
+/**
+ * Look up the built-in default for a provider type, or `undefined` when the
+ * type is not one AQE ships (ADR-127: an externally registered provider).
+ */
+function builtinBillingMode(type) {
+    return isBuiltinProviderType(type) ? BILLING_MODE_BY_TYPE[type] : undefined;
+}
 /**
  * Resolve a provider's billing mode: the instance's own `billingMode` wins,
  * else the per-type default, else `metered-api` (the safe, cap-requiring
  * assumption for an unknown provider).
+ *
+ * ADR-127: an external provider is expected to declare `billingMode` on the
+ * instance, which is why the instance's own value is consulted first. When it
+ * declares nothing it lands on `metered-api` and therefore requires a budget,
+ * rather than being silently treated as free.
  */
 export function resolveBillingMode(provider) {
-    return provider.billingMode ?? BILLING_MODE_BY_TYPE[provider.type] ?? 'metered-api';
+    return provider.billingMode ?? builtinBillingMode(provider.type) ?? 'metered-api';
 }
 /** Resolve a billing mode from a bare provider type. */
 export function billingModeForType(type) {
-    return BILLING_MODE_BY_TYPE[type] ?? 'metered-api';
+    return builtinBillingMode(type) ?? 'metered-api';
 }
 /**
  * One-line notice shown at startup / in `aqe health` describing how the
@@ -47,6 +71,21 @@ export function billingNotice(provider, mode) {
             return (`ℹ️  LLM provider "${provider}" bills per-token but enforces a server-side ` +
                 `hard spend cap; it will pause at the cap rather than overspend.`);
         case 'subscription': {
+            // ADR-127: only a built-in may be named as drawing on a specific
+            // vendor's plan. An external provider that declares `subscription` is
+            // asserting something AQE cannot verify, and naming Claude Code or
+            // ChatGPT here would attribute the spend to a vendor that is not
+            // serving the work — the exact misrepresentation issue #628 refused to
+            // perform. Say what was declared, and say who declared it.
+            const declaration = registeredBillingDeclaration(provider);
+            if (declaration) {
+                const by = declaration.detail
+                    ? `declared by ${declaration.detail}`
+                    : `declared by ${declaration.source === 'config' ? 'config' : 'the registering caller'}`;
+                return (`ℹ️  LLM provider "${provider}" is an external provider that reports ` +
+                    `subscription billing (${by}) — AQE does not verify this. It draws on ` +
+                    `that host's own plan, not on your Claude Code or ChatGPT subscription.`);
+            }
             const sub = provider === 'codex' ? 'ChatGPT' : 'Claude Code';
             return (`ℹ️  LLM provider "${provider}" runs on your ${sub} subscription ` +
                 `(shared plan usage). Worst case is hitting your plan's rate limit and pausing — ` +

package/dist/shared/llm/index.d.ts

@@ -41,11 +41,14 @@
  * const costs = manager.getCostSummary('day');
  * ```
  */
-export { type LLMProviderType, type MessageRole, type Message, type TokenUsage, type CostInfo, type LLMResponse, type EmbeddingResponse, type CompletionResponse, type LLMConfig, type ClaudeConfig, type OpenAIConfig, type OllamaConfig, type OpenRouterConfig, type GeminiConfig, type AzureOpenAIConfig, type BedrockConfig, type ProviderManagerConfig, type GenerateOptions, type EmbedOptions, type CompleteOptions, type LLMProvider, type HealthCheckResult, type CircuitBreakerState, type CircuitBreakerConfig, type CircuitBreakerStats, type CostPeriod, type CostSummary, type CostAlert, type CacheEntry, type LLMCacheConfig, type LLMCacheStats, type ProviderSelection, type ProviderMetrics, type LLMErrorCode, type LLMError, createLLMError, isLLMError, } from './interfaces';
+export { type LLMProviderType, type MessageRole, type Message, type TokenUsage, type CostInfo, type LLMResponse, type EmbeddingResponse, type CompletionResponse, type LLMConfig, type ClaudeConfig, type OpenAIConfig, type OllamaConfig, type OpenRouterConfig, type GeminiConfig, type AzureOpenAIConfig, type BedrockConfig, type ProviderManagerConfig, type GenerateOptions, type EmbedOptions, type CompleteOptions, type BuiltinProviderType, BUILTIN_PROVIDER_TYPES, isBuiltinProviderType, type LLMProvider, type HealthCheckResult, type CircuitBreakerState, type CircuitBreakerConfig, type CircuitBreakerStats, type CostPeriod, type CostSummary, type CostAlert, type CacheEntry, type LLMCacheConfig, type LLMCacheStats, type ProviderSelection, type ProviderMetrics, type LLMErrorCode, type LLMError, createLLMError, isLLMError, } from './interfaces';
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG, OpenAIProvider, DEFAULT_OPENAI_CONFIG, OllamaProvider, DEFAULT_OLLAMA_CONFIG, OpenRouterProvider, DEFAULT_OPENROUTER_CONFIG, GeminiProvider, DEFAULT_GEMINI_CONFIG, AzureOpenAIProvider, DEFAULT_AZURE_OPENAI_CONFIG, BedrockProvider, DEFAULT_BEDROCK_CONFIG, } from './providers';
 export { CircuitBreaker, CircuitBreakerManager, DEFAULT_CIRCUIT_BREAKER_CONFIG, } from './circuit-breaker';
 export { LLMCache, LLMResponseCache, DEFAULT_CACHE_CONFIG, type CacheableResponse, } from './cache';
 export { CostTracker, MODEL_PRICING, getGlobalCostTracker, resetGlobalCostTracker, } from './cost-tracker';
+export { registerProvider, tryRegisterProvider, unregisterProvider, resetProviderRegistry, isRegisteredProvider, getRegisteredProvider, listRegisteredProviders, registeredProviderTypes, createRegisteredProvider, registeredBillingDeclaration, validateProviderType, validateProviderInstance, type ProviderFactory, type ProviderRegistrationOptions, type ProviderRegistrationSource, type RegisteredProvider, } from './provider-registry';
+export { ExternalCliProvider, validateExternalCliConfig, resolvesOnPath, DEFAULT_EXTERNAL_CLI_TIMEOUT_MS, DEFAULT_EXTERNAL_CLI_CONCURRENCY, EXTERNAL_CLI_DEFAULT_MODEL, type ExternalCliProviderConfig, } from './providers/external-cli';
+export { registerExternalProviders, sanitizeExternalProviders, type ExternalProviderRegistrationResult, } from './router/external-provider-config';
 export { ProviderManager, createProviderManager, createQEProviderManager, DEFAULT_PROVIDER_MANAGER_CONFIG, } from './provider-manager';
 export { mapModelId, normalizeModelId, getCanonicalName, getModelFamily, getModelTier, isModelAvailableOnProvider, getSupportedProviders, listCanonicalModels, listModelsByProvider, listModelsByFamily, listModelsByTier, getModelMapping, MODEL_MAPPINGS, type ProviderType, type ModelMapping, } from './model-mapping';
 export { getModelCapabilities, getModelCost, getModelInfo, listModels, findModelsByCapability, findModelsByCost, findCheapestModel, findBestModelInBudget, getRecommendedModels, getDeprecationStatus, estimateRequestCost, compareModels, MODEL_REGISTRY, type ModelCapabilities, type ModelCostInfo, type ModelInfo, } from './model-registry';

package/dist/shared/llm/index.js

@@ -42,7 +42,7 @@
  * ```
  */
 // Core interfaces
-export { createLLMError, isLLMError, } from './interfaces.js';
+export { BUILTIN_PROVIDER_TYPES, isBuiltinProviderType, createLLMError, isLLMError, } from './interfaces.js';
 // Providers (ADR-043: All 7 provider types)
 export { ClaudeProvider, DEFAULT_CLAUDE_CONFIG, OpenAIProvider, DEFAULT_OPENAI_CONFIG, OllamaProvider, DEFAULT_OLLAMA_CONFIG, 
 // ADR-043 New Providers
@@ -53,6 +53,10 @@ export { CircuitBreaker, CircuitBreakerManager, DEFAULT_CIRCUIT_BREAKER_CONFIG,
 export { LLMCache, LLMResponseCache, DEFAULT_CACHE_CONFIG, } from './cache.js';
 // Cost tracker
 export { CostTracker, MODEL_PRICING, getGlobalCostTracker, resetGlobalCostTracker, } from './cost-tracker.js';
+// External provider registration (ADR-127 / issue #628)
+export { registerProvider, tryRegisterProvider, unregisterProvider, resetProviderRegistry, isRegisteredProvider, getRegisteredProvider, listRegisteredProviders, registeredProviderTypes, createRegisteredProvider, registeredBillingDeclaration, validateProviderType, validateProviderInstance, } from './provider-registry.js';
+export { ExternalCliProvider, validateExternalCliConfig, resolvesOnPath, DEFAULT_EXTERNAL_CLI_TIMEOUT_MS, DEFAULT_EXTERNAL_CLI_CONCURRENCY, EXTERNAL_CLI_DEFAULT_MODEL, } from './providers/external-cli.js';
+export { registerExternalProviders, sanitizeExternalProviders, } from './router/external-provider-config.js';
 // Provider manager
 export { ProviderManager, createProviderManager, createQEProviderManager, DEFAULT_PROVIDER_MANAGER_CONFIG, } from './provider-manager.js';
 // Model mapping (ADR-043)

package/dist/shared/llm/interfaces.d.ts

@@ -9,9 +9,32 @@
  * - Response caching
  */
 /**
- * Supported LLM provider types
+ * Provider types AQE ships built in. Exhaustive — safe to key a `Record` on.
+ *
+ * ADR-127: this is the closed half of the provider identity space. Anything
+ * that must be exhaustively handled (billing defaults, env-key maps, prompt
+ * translation strategies) keys on THIS type, not on `LLMProviderType`.
  */
-export type LLMProviderType = 'claude' | 'claude-code' | 'codex' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
+export type BuiltinProviderType = 'claude' | 'claude-code' | 'codex' | 'openai' | 'ollama' | 'openrouter' | 'bedrock' | 'azure-openai' | 'gemini' | 'cognitum';
+/**
+ * Supported LLM provider types.
+ *
+ * ADR-127: open. A downstream integrator may register an additional provider
+ * identity (via `registerProvider()` or an `externalProviders` entry in
+ * `.agentic-qe/llm-config.json`) so `AQE_LLM_PROVIDER=<their-host>` resolves to
+ * a provider they supply, instead of forking this union or misrepresenting
+ * their host as an unrelated vendor (issue #628).
+ *
+ * The `(string & {})` arm keeps editor autocomplete on the built-ins while
+ * admitting registered identities. Because this type is no longer exhaustive,
+ * a `Record` keyed on it can no longer be checked by the compiler — use
+ * `BuiltinProviderType` for those and read through a fallback.
+ */
+export type LLMProviderType = BuiltinProviderType | (string & {});
+/** The built-in provider types, as a runtime array. ADR-127. */
+export declare const BUILTIN_PROVIDER_TYPES: readonly BuiltinProviderType[];
+/** Type guard: is this one of the provider types AQE ships? */
+export declare function isBuiltinProviderType(type: string): type is BuiltinProviderType;
 /**
  * Message role in a conversation
  */
@@ -629,7 +652,15 @@ export interface ProviderMetrics {
 /**
  * LLM-specific error codes
  */
-export type LLMErrorCode = 'API_KEY_INVALID' | 'API_KEY_MISSING' | 'RATE_LIMITED' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'MODEL_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'CIRCUIT_OPEN' | 'TIMEOUT' | 'NETWORK_ERROR' | 'COST_LIMIT_EXCEEDED' | 'UNKNOWN';
+export type LLMErrorCode = 'API_KEY_INVALID' | 'API_KEY_MISSING' | 'RATE_LIMITED' | 'CONTEXT_LENGTH_EXCEEDED' | 'CONTENT_FILTERED' | 'MODEL_NOT_FOUND' | 'PROVIDER_UNAVAILABLE' | 'CIRCUIT_OPEN' | 'TIMEOUT' | 'NETWORK_ERROR' | 'COST_LIMIT_EXCEEDED'
+/** ADR-127: a provider registration or its produced instance was malformed. */
+ | 'INVALID_REGISTRATION'
+/**
+ * ADR-127: this provider has no embeddings endpoint. Distinct from a
+ * failure — the caller should fall back to another provider rather than
+ * retry, and must never receive a fabricated vector.
+ */
+ | 'EMBEDDING_UNSUPPORTED' | 'UNKNOWN';
 /**
  * LLM error with rich context
  */

package/dist/shared/llm/interfaces.js

@@ -8,6 +8,23 @@
  * - Circuit breaker support for resilience
  * - Response caching
  */
+/** The built-in provider types, as a runtime array. ADR-127. */
+export const BUILTIN_PROVIDER_TYPES = [
+    'claude',
+    'claude-code',
+    'codex',
+    'openai',
+    'ollama',
+    'openrouter',
+    'bedrock',
+    'azure-openai',
+    'gemini',
+    'cognitum',
+];
+/** Type guard: is this one of the provider types AQE ships? */
+export function isBuiltinProviderType(type) {
+    return BUILTIN_PROVIDER_TYPES.includes(type);
+}
 /**
  * Create an LLM error
  */

package/dist/shared/llm/llm-router-service.d.ts

@@ -22,6 +22,7 @@
 import { ProviderManager } from './provider-manager.js';
 import { HybridRouter } from './router/hybrid-router.js';
 import type { RouterConfig, ExtendedProviderType } from './router/types.js';
+import type { ProviderManagerConfig } from './interfaces.js';
 /**
  * Options accepted by createLLMRouterService(). All optional — defaults
  * produce a router suitable for kernel boot when at least one provider
@@ -39,6 +40,8 @@ export interface LLMRouterServiceOptions {
      * When supplied, config loading and provider construction is skipped.
      */
     providerManager?: ProviderManager;
+    /** Ignore project-controlled network endpoints before attaching ambient credentials. */
+    allowProjectProviderEndpoints?: boolean;
 }
 /**
  * Result of building a router. Carries the router plus the resolved
@@ -74,4 +77,9 @@ export declare function pickPrimaryAndFallbacks(config: RouterConfig, enabled: E
     primary: ExtendedProviderType;
     fallbacks: ExtendedProviderType[];
 };
+/**
+ * Extract only the provider configs for the enabled set, so
+ * ProviderManager doesn't try to construct providers we don't need.
+ */
+export declare function extractProviderConfigs(config: RouterConfig, enabled: ExtendedProviderType[], allowProjectProviderEndpoints?: boolean): ProviderManagerConfig['providers'];
 //# sourceMappingURL=llm-router-service.d.ts.map

package/dist/shared/llm/llm-router-service.js

@@ -21,6 +21,7 @@
  */
 import { ProviderManager } from './provider-manager.js';
 import { HybridRouter } from './router/hybrid-router.js';
+import { ALL_PROVIDER_TYPES } from './router/types.js';
 import { loadRouterConfig, shouldEnableRouter, detectAvailableProvidersFromEnv, } from './router/config-store.js';
 import { setAgentProviderOverrides, createOverrideRoutingRules, } from './router/agent-router-config.js';
 import { DEFAULT_QE_ROUTING_RULES } from './router/routing-rules.js';
@@ -131,7 +132,7 @@ export async function createLLMRouterService(options = {}) {
     const providerManagerConfig = {
         primary: primary,
         fallbacks: fallbacks,
-        providers: extractProviderConfigs(config, enabled),
+        providers: extractProviderConfigs(config, enabled, options.allowProjectProviderEndpoints ?? true),
         loadBalancing: 'round-robin',
         global: { enableCostTracking: true, enableMetrics: true },
     };
@@ -175,6 +176,14 @@ export function pickEnabledProviders(config, env = process.env) {
     for (const p of FALLBACK_PRIORITY) {
         consider(p);
     }
+    // Finally, every AQE-shipped provider. The fixed priority list is an ordering
+    // policy, not an allowlist: treating it as one made enabled subscription
+    // hosts (`codex`, `claude-code`) unreachable unless repeated in fallbackChain.
+    // Do not implicitly activate project-declared external commands here: a
+    // checkout must not gain code execution merely through `enabled: true`.
+    for (const p of ALL_PROVIDER_TYPES) {
+        consider(p);
+    }
     return result;
 }
 /**
@@ -208,12 +217,21 @@ export function pickPrimaryAndFallbacks(config, enabled) {
  * Extract only the provider configs for the enabled set, so
  * ProviderManager doesn't try to construct providers we don't need.
  */
-function extractProviderConfigs(config, enabled) {
+export function extractProviderConfigs(config, enabled, allowProjectProviderEndpoints = true) {
     const out = {};
     for (const p of enabled) {
         const cfg = config.providers?.[p];
         if (cfg) {
-            out[p] = cfg;
+            // The kernel reads project-local config. Never let a checkout replace a
+            // trusted subscription CLI with an arbitrary executable. Callers that
+            // intentionally need a custom binary can still construct ProviderManager
+            // directly with an explicit config.
+            const sanitized = { ...cfg };
+            if (p === 'codex' || p === 'claude-code')
+                delete sanitized.binaryPath;
+            if (!allowProjectProviderEndpoints)
+                delete sanitized.baseUrl;
+            out[p] = sanitized;
         }
     }
     return out;

package/dist/shared/llm/provider-manager.js

@@ -27,6 +27,7 @@ import { GeminiProvider } from './providers/gemini.js';
 import { AzureOpenAIProvider } from './providers/azure-openai.js';
 import { BedrockProvider } from './providers/bedrock.js';
 import { toError } from '../error-utils.js';
+import { createRegisteredProvider } from './provider-registry.js';
 /**
  * Default provider manager configuration
  */
@@ -441,7 +442,13 @@ export class ProviderManager {
             case 'bedrock':
                 return new BedrockProvider(this.config.providers.bedrock);
             default:
-                throw new Error(`Unknown provider type: ${type}`);
+                // ADR-127: not a built-in. Fall through to the external provider
+                // registry, which throws PROVIDER_UNAVAILABLE when nothing is
+                // registered under this type — preserving the previous behavior for a
+                // genuinely unknown type while letting a downstream integrator supply
+                // one. Built-in cases are matched first, so a registration can never
+                // shadow a provider AQE ships.
+                return createRegisteredProvider(type);
         }
     }
     /**