agentic-qe 3.15.16 → 3.15.18

package/dist/learning/checkpoint-shrink-ack.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deliberate-shrink acknowledgement for the brain checkpoint (#1251).
+ *
+ * The Stop-hook checkpoint (`.claude/helpers/brain-checkpoint.cjs export`)
+ * refuses to replace `aqe.rvf` with an export in which a table collapsed, so
+ * a memory.db recreated from seed data cannot overwrite a richer mirror. A
+ * deliberate shrink (`aqe learning prune --apply`, dream retention) is not
+ * that case. It leaves this acknowledgement next to memory.db, with the row
+ * counts it left behind. The export honours it once, within 24h, and only
+ * while the brain still holds those counts (see evaluateShrinkAck).
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+import { type ShrinkProducer } from '../integrations/ruvector/brain-rvf-richness.js';
+import type { RetentionStepResult } from './learning-retention.js';
+/** Read by the checkpoint hook in `.agentic-qe/`; keep the name in sync with it. */
+export declare const CHECKPOINT_SHRINK_ACK_FILE = "brain-checkpoint.accept-shrink.json";
+/** True when a step that ran for real left fewer rows in some table. */
+export declare function removedRows(results: readonly RetentionStepResult[]): boolean;
+/**
+ * Write the acknowledgement next to the file of `db`, after the shrink and
+ * while `db` is still open. Best-effort: returns its path, or undefined when
+ * there is no database file (in-memory) or it failed.
+ */
+export declare function acknowledgeCheckpointShrink(db: DatabaseType, producer: ShrinkProducer): string | undefined;
+//# sourceMappingURL=checkpoint-shrink-ack.d.ts.map

package/dist/learning/checkpoint-shrink-ack.js

@@ -0,0 +1,57 @@
+/**
+ * Deliberate-shrink acknowledgement for the brain checkpoint (#1251).
+ *
+ * The Stop-hook checkpoint (`.claude/helpers/brain-checkpoint.cjs export`)
+ * refuses to replace `aqe.rvf` with an export in which a table collapsed, so
+ * a memory.db recreated from seed data cannot overwrite a richer mirror. A
+ * deliberate shrink (`aqe learning prune --apply`, dream retention) is not
+ * that case. It leaves this acknowledgement next to memory.db, with the row
+ * counts it left behind. The export honours it once, within 24h, and only
+ * while the brain still holds those counts (see evaluateShrinkAck).
+ */
+import { lstatSync, unlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { mirroredTableCounts, } from '../integrations/ruvector/brain-rvf-richness.js';
+/** Read by the checkpoint hook in `.agentic-qe/`; keep the name in sync with it. */
+export const CHECKPOINT_SHRINK_ACK_FILE = 'brain-checkpoint.accept-shrink.json';
+/** True when a step that ran for real left fewer rows in some table. */
+export function removedRows(results) {
+    return results.some((r) => !r.dryRun && r.tables.some((t) => t.after < t.before));
+}
+/**
+ * Write the acknowledgement next to the file of `db`, after the shrink and
+ * while `db` is still open. Best-effort: returns its path, or undefined when
+ * there is no database file (in-memory) or it failed.
+ */
+export function acknowledgeCheckpointShrink(db, producer) {
+    const dbPath = db.name;
+    if (!dbPath || dbPath === ':memory:')
+        return undefined;
+    const dir = path.dirname(path.resolve(dbPath));
+    try {
+        // Same rule as the hook: never write into a symlinked directory.
+        const st = lstatSync(dir);
+        if (!st.isDirectory() || st.isSymbolicLink())
+            return undefined;
+        const ack = {
+            at: new Date().toISOString(),
+            producer,
+            tableCounts: mirroredTableCounts(db),
+        };
+        const ackPath = path.join(dir, CHECKPOINT_SHRINK_ACK_FILE);
+        // Unlink, then 'wx': never write through a planted symlink (#970).
+        try {
+            unlinkSync(ackPath);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        writeFileSync(ackPath, JSON.stringify(ack) + '\n', { flag: 'wx' });
+        return ackPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=checkpoint-shrink-ack.js.map

package/dist/learning/dream/dream-engine.d.ts

@@ -20,13 +20,14 @@
  * gives up quickly instead of using the engine's 60 s commit wait.
  */
 export declare const RETENTION_BUSY_TIMEOUT_MS = 1000;
-import { type ActivationConfig } from './spreading-activation.js';
-import { type InsightConfig, type DreamInsight } from './insight-generator.js';
+import { ConceptGraph } from './concept-graph.js';
+import { type ActivationConfig, type ConceptGraph as SpreadingConceptGraph } from './spreading-activation.js';
+import { type InsightConfig, type DreamInsight, type ConceptGraph as InsightConceptGraph } from './insight-generator.js';
 import { type Branch, type ValidationResult, type ValidationThresholds } from './rvcow-branch-manager.js';
 import { type ComputedDream } from './dream-commit.js';
 import type { WitnessChain } from '../../audit/witness-chain.js';
 import { type DreamRetentionReport } from '../learning-retention.js';
-import type { DreamCycle, PatternImportData, FailureImportData, SuccessImportData } from './types.js';
+import type { DreamCycle, ConceptNode, ConceptEdge, ConceptGraphStats, PatternImportData, FailureImportData, SuccessImportData } from './types.js';
 /**
  * Complete DreamEngine configuration
  */
@@ -115,6 +116,46 @@ export interface ApplyInsightResult {
     indexPending?: boolean;
     error?: string;
 }
+/**
+ * Adapter that bridges the actual ConceptGraph class to the minimal interfaces
+ * expected by SpreadingActivation and InsightGenerator.
+ *
+ * The actual ConceptGraph uses async methods and SQLite persistence,
+ * while the spreading activation expects synchronous in-memory access.
+ * This adapter maintains an in-memory cache for fast access during dreams.
+ * Exported for tests only (#1186).
+ */
+export declare class ConceptGraphAdapter implements SpreadingConceptGraph, InsightConceptGraph {
+    private readonly graph;
+    private nodeCache;
+    private edgeCache;
+    private activationLevels;
+    /** #1060: each node's level when loaded, for the commit's conflict check. */
+    private loadedLevels;
+    constructor(graph: ConceptGraph);
+    /**
+     * Load nodes and edges into memory for fast access.
+     * @param maxNodes - Maximum number of nodes to load (prevents slow loading
+     *   on accumulated concept graphs). Nodes are sorted by activation level
+     *   descending, so the most active concepts are prioritized. Default: no limit.
+     */
+    loadIntoMemory(maxNodes?: number): Promise<void>;
+    /**
+     * Final activation levels with the levels loaded, written by commitDream()
+     * in the cycle's single transaction (#1060) instead of one awaited UPDATE
+     * per node. The loaded level lets the commit skip a node a foreground write
+     * changed during the dream.
+     */
+    activationEntries(): Array<[string, number, number | undefined]>;
+    getConcept(id: string): ConceptNode | undefined;
+    getAllConcepts(minActivation?: number): ConceptNode[];
+    getActiveNodes(threshold: number): ConceptNode[];
+    getEdges(nodeId: string): ConceptEdge[];
+    getEdge(source: string, target: string): ConceptEdge | undefined;
+    setActivation(nodeId: string, level: number): void;
+    decayActivations(factor: number): void;
+    getStats(): ConceptGraphStats;
+}
 /**
  * DreamEngine orchestrates dream-based pattern discovery.
  *

package/dist/learning/dream/dream-engine.js

@@ -37,6 +37,7 @@ import { InsightGenerator, } from './insight-generator.js';
 import { DEFAULT_VALIDATION_THRESHOLDS, } from './rvcow-branch-manager.js';
 import { commitDream, markAbandonedCycles, ABANDONED_CYCLE_GRACE_MS, } from './dream-commit.js';
 import { describeRetention, resolveDefaultRetention, runDreamRetention, } from '../learning-retention.js';
+import { addToCount } from '../../shared/utils/safe-record.js';
 /**
  * Default DreamEngine configuration
  */
@@ -83,8 +84,9 @@ export class DreamAlreadyRunningError extends Error {
  * The actual ConceptGraph uses async methods and SQLite persistence,
  * while the spreading activation expects synchronous in-memory access.
  * This adapter maintains an in-memory cache for fast access during dreams.
+ * Exported for tests only (#1186).
  */
-class ConceptGraphAdapter {
+export class ConceptGraphAdapter {
     graph;
     nodeCache = new Map();
     edgeCache = new Map();
@@ -187,7 +189,9 @@ class ConceptGraphAdapter {
         };
         let totalActivation = 0;
         for (const node of nodes) {
-            byType[node.conceptType] = (byType[node.conceptType] ?? 0) + 1;
+            // #1186: a stored concept type such as `constructor` or `__proto__` is
+            // counted as its own bucket, not added to the inherited member.
+            addToCount(byType, node.conceptType);
             totalActivation += this.activationLevels.get(node.id) ?? node.activationLevel;
         }
         let totalEdges = 0;

package/dist/learning/embedder-endpoint-client.d.ts

@@ -15,6 +15,8 @@
  *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
  *   - Probe + identity fingerprint required before `embed()`; breaker recovery
  *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - The first identity is bound for the client's lifetime: a re-probe that
+ *     finds another model is refused, never adopted (#1282).
  *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
  *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
  */
@@ -64,6 +66,8 @@ export interface EmbedderEndpointClientOptions {
     /** TLS overrides for https transport. Ignored for http/unix. */
     tlsOptions?: EmbedderTlsOptions;
 }
+/** The text every probe embeds; its vector is the endpoint's identity evidence. */
+export declare const ENDPOINT_IDENTITY_CANARY = "AQE embedder endpoint identity canary v1";
 /**
  * Parsed endpoint — either an HTTP(S) URL or a Unix socket path.
  */
@@ -92,6 +96,17 @@ export declare class EmbedderEndpointTimeoutError extends Error {
     readonly limitMs: number;
     constructor(phase: 'connect' | 'request', limitMs: number);
 }
+/**
+ * #1282: a probe found a different endpoint identity than the one the client
+ * bound to. Vectors from the new identity are not comparable with stored ones,
+ * so the client refuses to embed until the endpoint serves the bound identity
+ * again or the process restarts.
+ */
+export declare class EmbedderEndpointIdentityChangedError extends Error {
+    readonly bound: EndpointIdentity;
+    readonly current: EndpointIdentity;
+    constructor(bound: EndpointIdentity, current: EndpointIdentity);
+}
 /**
  * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
  */
@@ -101,6 +116,15 @@ export declare class EmbedderEndpointClient {
     private readonly breaker;
     private readonly opts;
     private cachedIdentity;
+    /**
+     * #1282: the first identity a probe found. Every embedding this client
+     * returns belongs to it; later probes must find it again.
+     */
+    private boundIdentity;
+    /** #1282: the canary vector behind `boundIdentity`. */
+    private boundCanary;
+    /** #1282: set while the endpoint serves an identity other than the bound one. */
+    private identityChange;
     /** True while a probe is in flight — prevents the embed() lazy-probe race. */
     private probeInFlight;
     /**
@@ -146,7 +170,28 @@ export declare class EmbedderEndpointClient {
     probe(): Promise<EndpointIdentity>;
     private ensureProbed;
     private doProbe;
+    /**
+     * #1282: true when a re-probe found the bound model. The int16 fingerprint
+     * flips on noise of about 3e-5 per component, which the same model restarted
+     * on other hardware or kernels can produce, so a changed hash alone is not a
+     * changed model: the canary must also have moved below the ADR-097
+     * round-trip cosine.
+     */
+    private isBoundModel;
+    /**
+     * #1282: the endpoint answers, but as a different model than the one this
+     * client bound to (an endpoint restarted with another model of the same
+     * dimension, typically seen when the breaker recovers). Treat it as down:
+     * open the breaker so every caller fast-fails with this error, and retry
+     * as a half-open trial after each window, in case the bound model returns.
+     * Reported once per new identity.
+     */
+    private refuseIdentityChange;
     getCachedIdentity(): EndpointIdentity | null;
+    /** #1282: the identity every vector from this client belongs to. */
+    getBoundIdentity(): EndpointIdentity | null;
+    /** #1298: the canary vector behind the bound identity (ENDPOINT_IDENTITY_CANARY). */
+    getBoundCanary(): readonly number[] | null;
     getBreakerState(): {
         open: boolean;
         failures: number;

package/dist/learning/embedder-endpoint-client.js

@@ -15,6 +15,8 @@
  *   - Bearer auth from env only; URL userinfo stripped + warned on construct.
  *   - Probe + identity fingerprint required before `embed()`; breaker recovery
  *     invalidates identity so re-probe runs against a fresh endpoint.
+ *   - The first identity is bound for the client's lifetime: a re-probe that
+ *     finds another model is refused, never adopted (#1282).
  *   - True TCP connect timeout via socket-level setTimeout (not req.setTimeout).
  *   - TLS knobs (ca / cert / key / rejectUnauthorized / servername) for self-hosted.
  */
@@ -22,7 +24,8 @@ import * as http from 'node:http';
 import * as https from 'node:https';
 import { createHash } from 'node:crypto';
 import { URL } from 'node:url';
-import { normalize as l2Normalize } from '../shared/utils/vector-math.js';
+import { cosineSimilarity, normalize as l2Normalize } from '../shared/utils/vector-math.js';
+import { EMBEDDING_ROUND_TRIP_MIN_COSINE } from './embedding-space.js';
 const DEFAULT_OPTIONS = {
     model: 'Xenova/all-MiniLM-L6-v2',
     expectedDim: 384,
@@ -31,7 +34,9 @@ const DEFAULT_OPTIONS = {
     failureThreshold: 3,
     failureWindowMs: 60_000,
 };
-const CANARY_TEXT = 'AQE embedder endpoint identity canary v1';
+/** The text every probe embeds; its vector is the endpoint's identity evidence. */
+export const ENDPOINT_IDENTITY_CANARY = 'AQE embedder endpoint identity canary v1';
+const CANARY_TEXT = ENDPOINT_IDENTITY_CANARY;
 const EMBEDDINGS_PATH = '/v1/embeddings';
 /**
  * Strip user:password@ from a URL for safe logging.
@@ -97,6 +102,25 @@ export class EmbedderEndpointTimeoutError extends Error {
         this.name = 'EmbedderEndpointTimeoutError';
     }
 }
+/**
+ * #1282: a probe found a different endpoint identity than the one the client
+ * bound to. Vectors from the new identity are not comparable with stored ones,
+ * so the client refuses to embed until the endpoint serves the bound identity
+ * again or the process restarts.
+ */
+export class EmbedderEndpointIdentityChangedError extends Error {
+    bound;
+    current;
+    constructor(bound, current) {
+        super(`[EmbedderEndpointClient] endpoint identity changed since this process bound to it ` +
+            `(fingerprint ${bound.fingerprint} -> ${current.fingerprint}, ` +
+            `dim ${bound.dim} -> ${current.dim}) at ${current.endpoint}; ` +
+            `restart to use the new embedding space`);
+        this.bound = bound;
+        this.current = current;
+        this.name = 'EmbedderEndpointIdentityChangedError';
+    }
+}
 /**
  * Circuit breaker state.
  *
@@ -160,6 +184,9 @@ class CircuitBreaker {
         return { open: this.isOpen(), failures: this.failures.length, trippedAt: this.trippedAt };
     }
 }
+function sameIdentity(a, b) {
+    return a.fingerprint === b.fingerprint && a.dim === b.dim;
+}
 /**
  * OpenAI-compatible embeddings client with keep-alive, circuit breaker, and identity probe.
  */
@@ -169,6 +196,15 @@ export class EmbedderEndpointClient {
     breaker;
     opts;
     cachedIdentity = null;
+    /**
+     * #1282: the first identity a probe found. Every embedding this client
+     * returns belongs to it; later probes must find it again.
+     */
+    boundIdentity = null;
+    /** #1282: the canary vector behind `boundIdentity`. */
+    boundCanary = null;
+    /** #1282: set while the endpoint serves an identity other than the bound one. */
+    identityChange = null;
     /** True while a probe is in flight — prevents the embed() lazy-probe race. */
     probeInFlight = null;
     /**
@@ -260,6 +296,9 @@ export class EmbedderEndpointClient {
         if (texts.length === 0)
             return [];
         if (this.breaker.isOpen()) {
+            // #1282: say why the breaker is open when the cause is a changed model.
+            if (this.identityChange)
+                throw this.identityChange;
             throw new Error(`[EmbedderEndpointClient] circuit breaker open for ${this.parsed.safeUrl} — fast-failing`);
         }
         // Identity gate: every embed call must have a verified identity behind it.
@@ -328,17 +367,73 @@ export class EmbedderEndpointClient {
             buf.writeInt16LE(q, i * 2);
         }
         const fingerprint = createHash('sha256').update(buf).digest('hex').slice(0, 16);
-        this.cachedIdentity = {
+        const identity = {
             dim: vec.length,
             fingerprint,
             endpoint: this.parsed.safeUrl,
         };
+        if (this.boundIdentity && this.boundCanary) {
+            if (!this.isBoundModel(identity, vec))
+                this.refuseIdentityChange(identity);
+        }
+        else {
+            this.boundIdentity = identity;
+            this.boundCanary = vec;
+        }
+        this.identityChange = null;
+        // The bound identity stays the one callers see, also when fp noise moved
+        // the hash: the embedding space did not change.
+        this.cachedIdentity = this.boundIdentity;
         this.trialPending = false;
         return this.cachedIdentity;
     }
+    /**
+     * #1282: true when a re-probe found the bound model. The int16 fingerprint
+     * flips on noise of about 3e-5 per component, which the same model restarted
+     * on other hardware or kernels can produce, so a changed hash alone is not a
+     * changed model: the canary must also have moved below the ADR-097
+     * round-trip cosine.
+     */
+    isBoundModel(identity, canary) {
+        const bound = this.boundIdentity;
+        if (identity.dim !== bound.dim)
+            return false;
+        if (identity.fingerprint === bound.fingerprint)
+            return true;
+        return (cosineSimilarity(this.boundCanary, canary) >= EMBEDDING_ROUND_TRIP_MIN_COSINE);
+    }
+    /**
+     * #1282: the endpoint answers, but as a different model than the one this
+     * client bound to (an endpoint restarted with another model of the same
+     * dimension, typically seen when the breaker recovers). Treat it as down:
+     * open the breaker so every caller fast-fails with this error, and retry
+     * as a half-open trial after each window, in case the bound model returns.
+     * Reported once per new identity.
+     */
+    refuseIdentityChange(current) {
+        const bound = this.boundIdentity;
+        const previous = this.identityChange;
+        const change = new EmbedderEndpointIdentityChangedError(bound, current);
+        this.identityChange = change;
+        this.cachedIdentity = null;
+        this.trialPending = true;
+        this.breaker.trip();
+        if (!previous || !sameIdentity(previous.current, current)) {
+            console.warn(`${change.message}. Embedding requests are refused.`);
+        }
+        throw change;
+    }
     getCachedIdentity() {
         return this.cachedIdentity;
     }
+    /** #1282: the identity every vector from this client belongs to. */
+    getBoundIdentity() {
+        return this.boundIdentity;
+    }
+    /** #1298: the canary vector behind the bound identity (ENDPOINT_IDENTITY_CANARY). */
+    getBoundCanary() {
+        return this.boundCanary;
+    }
     getBreakerState() {
         return this.breaker.getState();
     }

package/dist/learning/embedder-identity-store.js

@@ -17,6 +17,7 @@ import { join, resolve } from 'node:path';
 import { existsSync, mkdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { findProjectRoot } from '../kernel/project-root.js';
+import { setJournalModeWithRetry } from '../shared/sqlite-journal-mode.js';
 // `require` is unavailable in pure ESM; createRequire gives us synchronous
 // access to CommonJS modules like better-sqlite3 from the ESM build output.
 const nodeRequire = createRequire(import.meta.url);
@@ -56,8 +57,9 @@ function openDb() {
             mkdirSync(dir, { recursive: true });
         }
         const db = new Database(path);
-        db.pragma('journal_mode = WAL');
+        // busy_timeout first; the WAL switch retries within it (#1164).
         db.pragma('busy_timeout = 5000');
+        setJournalModeWithRetry(db, 'WAL', 5000);
         db.exec(`
       CREATE TABLE IF NOT EXISTS kv_store (
         key TEXT NOT NULL,

package/dist/learning/embedding-space-legacy-adoption.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Adopt an embedding space id minted before the registry (#1302).
+ *
+ * A space created before #1298 has stored vectors under its exact-hash id but
+ * no reference canary in the registry. When the first start after upgrading
+ * is already noisy, the derived id differs and no reference can match it, so
+ * those vectors would be left under the old id. Before a new space is
+ * registered, a few captured_experiences rows of each such legacy id are
+ * re-embedded with the #1217 recipe (experience-space-verification). When the
+ * active embedder reproduces a stored vector (cosine >=
+ * EMBEDDING_ROUND_TRIP_MIN_COSINE), the legacy id is the active space: it is
+ * adopted and registered with the current canary as its reference, so later
+ * starts resolve it from the registry and this check does not run again.
+ *
+ * Read-only on stored rows: no vector, id or space id is ever written here.
+ */
+import { type EmbeddingSpaceIdentity } from './embedding-space.js';
+import type { RegisteredEmbeddingSpace } from './embedding-space-registry.js';
+/** Rows re-embedded per legacy space id. */
+export declare const LEGACY_ADOPTION_ROWS_PER_SPACE = 5;
+/** Legacy space ids checked per start, most rows first. */
+export declare const LEGACY_ADOPTION_MAX_SPACES = 3;
+interface ReadableDatabase {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+    };
+}
+export interface LegacySpaceCheck {
+    spaceId: string;
+    /** Rows of this space whose vector was compared. */
+    checked: number;
+    /** Rows whose stored vector the active embedder reproduced. */
+    matched: number;
+    /** Best cosine over the compared rows. */
+    bestCosine: number;
+}
+export interface LegacySpaceAdoption {
+    /** The legacy space id to adopt, or null to register the derived space. */
+    spaceId: string | null;
+    /** Why nothing was adopted, or which id was and on what evidence. */
+    reason: string;
+    checks: LegacySpaceCheck[];
+    embeds: number;
+}
+/**
+ * Find the legacy space id whose stored experience vectors the active
+ * embedder reproduces. `embed` embeds one text with the active runtime and
+ * throws when it fails. Never throws; returns spaceId null with a reason when
+ * nothing can be verified.
+ */
+export declare function findAdoptableLegacySpace(db: ReadableDatabase, derived: EmbeddingSpaceIdentity, registered: readonly RegisteredEmbeddingSpace[], embed: (text: string) => Promise<number[]>): Promise<LegacySpaceAdoption>;
+export {};
+//# sourceMappingURL=embedding-space-legacy-adoption.d.ts.map

package/dist/learning/embedding-space-legacy-adoption.js

@@ -0,0 +1,115 @@
+/**
+ * Adopt an embedding space id minted before the registry (#1302).
+ *
+ * A space created before #1298 has stored vectors under its exact-hash id but
+ * no reference canary in the registry. When the first start after upgrading
+ * is already noisy, the derived id differs and no reference can match it, so
+ * those vectors would be left under the old id. Before a new space is
+ * registered, a few captured_experiences rows of each such legacy id are
+ * re-embedded with the #1217 recipe (experience-space-verification). When the
+ * active embedder reproduces a stored vector (cosine >=
+ * EMBEDDING_ROUND_TRIP_MIN_COSINE), the legacy id is the active space: it is
+ * adopted and registered with the current canary as its reference, so later
+ * starts resolve it from the registry and this check does not run again.
+ *
+ * Read-only on stored rows: no vector, id or space id is ever written here.
+ */
+import { cosineSimilarity } from '../shared/utils/vector-math.js';
+import { toErrorMessage } from '../shared/error-utils.js';
+import { EMBEDDING_ROUND_TRIP_MIN_COSINE } from './embedding-space.js';
+import { legacyExperienceEmbeddingTexts, storedExperienceVector, } from './experience-space-verification.js';
+/** Rows re-embedded per legacy space id. */
+export const LEGACY_ADOPTION_ROWS_PER_SPACE = 5;
+/** Legacy space ids checked per start, most rows first. */
+export const LEGACY_ADOPTION_MAX_SPACES = 3;
+/**
+ * Find the legacy space id whose stored experience vectors the active
+ * embedder reproduces. `embed` embeds one text with the active runtime and
+ * throws when it fails. Never throws; returns spaceId null with a reason when
+ * nothing can be verified.
+ */
+export async function findAdoptableLegacySpace(db, derived, registered, embed) {
+    const none = (reason, checks = [], embeds = 0) => ({ spaceId: null, reason, checks, embeds });
+    let legacyIds;
+    try {
+        legacyIds = legacySpaceIds(db, derived, registered);
+    }
+    catch (error) {
+        return none(`stored experience vectors could not be read (${toErrorMessage(error)})`);
+    }
+    if (legacyIds.length === 0)
+        return none('no stored experience vectors under an unregistered space id');
+    const checks = [];
+    let embeds = 0;
+    try {
+        for (const spaceId of legacyIds) {
+            const rows = db.prepare(`
+        SELECT rowid, id, task, agent, domain, steps_json, source, embedding, embedding_dimension
+        FROM captured_experiences
+        WHERE embedding_space_id = ? AND embedding IS NOT NULL AND embedding_dimension = ?
+        ORDER BY rowid LIMIT ?
+      `).all(spaceId, derived.dimensions, LEGACY_ADOPTION_ROWS_PER_SPACE);
+            const check = { spaceId, checked: 0, matched: 0, bestCosine: -1 };
+            for (const row of rows) {
+                const stored = storedExperienceVector(row);
+                if (!stored)
+                    continue;
+                check.checked++;
+                for (const text of legacyExperienceEmbeddingTexts(row)) {
+                    const recomputed = await embed(text);
+                    embeds++;
+                    if (recomputed.length !== stored.length)
+                        continue;
+                    const cosine = cosineSimilarity(stored, recomputed);
+                    if (cosine > check.bestCosine)
+                        check.bestCosine = cosine;
+                    if (cosine >= EMBEDDING_ROUND_TRIP_MIN_COSINE) {
+                        check.matched++;
+                        break;
+                    }
+                }
+            }
+            checks.push(check);
+        }
+    }
+    catch (error) {
+        return none(`the embedder failed while re-embedding stored experiences (${toErrorMessage(error)})`, checks, embeds);
+    }
+    const matching = checks
+        .filter((check) => check.matched > 0)
+        .sort((a, b) => b.matched - a.matched || b.bestCosine - a.bestCosine);
+    if (matching.length === 0) {
+        const checked = checks.reduce((sum, check) => sum + check.checked, 0);
+        return none(`none of ${checked} re-embedded experiences from ${checks.length} legacy space id(s) ` +
+            `reached cosine ${EMBEDDING_ROUND_TRIP_MIN_COSINE}`, checks, embeds);
+    }
+    const best = matching[0];
+    const others = matching.length > 1
+        ? `; also matching: ${matching.slice(1).map(describeCheck).join(', ')}`
+        : '';
+    return { spaceId: best.spaceId, reason: `${describeCheck(best)}${others}`, checks, embeds };
+}
+function describeCheck(check) {
+    return `${check.spaceId.slice(0, 12)} (${check.matched}/${check.checked} rows, best cosine ${check.bestCosine.toFixed(6)})`;
+}
+/**
+ * Space ids of stored experience vectors of the active dimension that have
+ * no registry entry, most rows first. The derived id is excluded: if rows are
+ * stored under it, registering it already keeps them.
+ */
+function legacySpaceIds(db, derived, registered) {
+    const known = new Set(registered.map((entry) => entry.identity.spaceId));
+    known.add(derived.spaceId);
+    const rows = db.prepare(`
+    SELECT embedding_space_id AS spaceId, COUNT(*) AS n
+    FROM captured_experiences
+    WHERE embedding_space_id IS NOT NULL AND embedding IS NOT NULL AND embedding_dimension = ?
+    GROUP BY embedding_space_id
+    ORDER BY n DESC, embedding_space_id
+  `).all(derived.dimensions);
+    return rows
+        .map((row) => row.spaceId)
+        .filter((spaceId) => !known.has(spaceId))
+        .slice(0, LEGACY_ADOPTION_MAX_SPACES);
+}
+//# sourceMappingURL=embedding-space-legacy-adoption.js.map