agentic-qe 3.15.17 → 3.15.18

package/dist/integrations/ruvector/brain-rvf-richness.js

@@ -0,0 +1,127 @@
+/**
+ * Richness comparison between an existing RVF mirror and a new export
+ * (#629, ADR-128; #1251 for the checkpoint policy).
+ *
+ * - `strict` (default, manual `aqe brain export`): any mirrored table with
+ *   fewer rows than the existing mirror refuses the export.
+ * - `checkpoint` (the Stop-hook checkpoint): routine retention trims rows
+ *   between turns (routing outcomes, concept edges, q-values, trajectories),
+ *   so only a collapse refuses: a table that lost more than its share in
+ *   CHECKPOINT_MAX_LOSS (half by default), and either at least
+ *   CHECKPOINT_MIN_LOST_ROWS rows or every row of a table that had at least
+ *   CHECKPOINT_MIN_EMPTIED_ROWS. A database recreated from seed data loses
+ *   that much; a retention pass does not. A table the existing mirror does
+ *   not have (added in a later release) held no rows to lose.
+ *
+ * A deliberate shrink (`aqe learning prune --apply`, dream retention) records
+ * a CheckpointShrinkAck. The checkpoint honours it in place of the mirror
+ * comparison only while it is fresh and the export still holds the counts the
+ * shrink left, so it cannot approve a later, unrelated drop.
+ */
+import { TABLE_CONFIGS, countRows } from './brain-shared.js';
+export const RICHNESS_POLICIES = ['strict', 'checkpoint'];
+/** Smallest loss the checkpoint policy refuses, so retention can trim a small table. */
+export const CHECKPOINT_MIN_LOST_ROWS = 10;
+/** A table emptied from at least this many rows is refused even under the minimum loss. */
+export const CHECKPOINT_MIN_EMPTIED_ROWS = 3;
+/**
+ * Largest share of a table the checkpoint policy lets go. Learned patterns
+ * are deduplicated at most 10% at a time (SQLitePatternStore), and captured
+ * experiences are never deleted (v3.9.22), so they get the 10% bound.
+ */
+export const CHECKPOINT_MAX_LOSS = {
+    qe_patterns: 0.1,
+    captured_experiences: 0.1,
+};
+const CHECKPOINT_DEFAULT_MAX_LOSS = 0.5;
+/** Code-intelligence vectors are a regenerable cache, never exported (#1238). */
+export const CODE_INDEX_VECTOR_ID_PREFIX = 'code-intelligence:';
+/** Refusal to replace an existing mirror. The message starts with the code. */
+export class RvfMirrorGuardError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = 'RvfMirrorGuardError';
+    }
+}
+export function isRichnessPolicy(value) {
+    return typeof value === 'string' && RICHNESS_POLICIES.includes(value);
+}
+function isLoss(tableName, existing, candidate, policy) {
+    if (policy === 'strict')
+        return existing > candidate;
+    const lost = existing - candidate;
+    const maxLoss = CHECKPOINT_MAX_LOSS[tableName] ?? CHECKPOINT_DEFAULT_MAX_LOSS;
+    const emptied = candidate === 0 && existing >= CHECKPOINT_MIN_EMPTIED_ROWS;
+    return lost > existing * maxLoss && (lost >= CHECKPOINT_MIN_LOST_ROWS || emptied);
+}
+/**
+ * Throw when replacing a mirror with `existingCounts` by a candidate with
+ * `candidateCounts` would lose rows under `policy`. `existingCounts` is
+ * undefined when the mirror has no table inventory at all: that is ambiguous
+ * under every policy.
+ */
+export function assertNotPoorerThanMirror(tableNames, existingCounts, candidateCounts, policy = 'strict') {
+    const missing = tableNames.filter((tableName) => !existingCounts || !Number.isSafeInteger(existingCounts[tableName]));
+    if (!existingCounts || (policy === 'strict' && missing.length > 0)) {
+        throw new RvfMirrorGuardError('RVF_MIRROR_INSPECTION_AMBIGUOUS', `existing mirror lacks trustworthy counts for ${missing.join(', ')}. Preserve/import it ` +
+            `before retrying, or repeat with --force-overwrite-richer after preserving a backup.`);
+    }
+    const richer = tableNames
+        .map((tableName) => ({
+        tableName,
+        existing: Number.isSafeInteger(existingCounts[tableName]) ? existingCounts[tableName] : 0,
+        candidate: candidateCounts[tableName] ?? 0,
+    }))
+        .filter(({ tableName, existing, candidate }) => isLoss(tableName, existing, candidate, policy));
+    if (richer.length > 0) {
+        const differences = richer
+            .map(({ tableName, existing, candidate }) => `${tableName} ${existing} -> ${candidate}`)
+            .join(', ');
+        throw new RvfMirrorGuardError('RVF_MIRROR_RICHER', `refusing to replace richer mirrored tables: ${differences}. Restore/import the mirror ` +
+            `first, or repeat with --force-overwrite-richer after preserving a backup.`);
+    }
+}
+/** Row counts of every mirrored table, counted the way the RVF export counts them. */
+export function mirroredTableCounts(db) {
+    const counts = {};
+    for (const { tableName } of TABLE_CONFIGS) {
+        counts[tableName] = tableName === 'vectors'
+            ? countRows(db, 'vectors', `(id IS NULL OR substr(id, 1, ?) != ?)`, [CODE_INDEX_VECTOR_ID_PREFIX.length, CODE_INDEX_VECTOR_ID_PREFIX])
+            : countRows(db, tableName);
+    }
+    return counts;
+}
+/** An acknowledgement is honoured for this long after the shrink. */
+export const SHRINK_ACK_MAX_AGE_MS = 24 * 3600_000;
+/** Clock skew tolerated for an acknowledgement dated in the future. */
+const SHRINK_ACK_MAX_SKEW_MS = 5 * 60_000;
+/**
+ * Whether the acknowledgement `raw` (parsed JSON, or anything else) still
+ * vouches for an export with `candidateCounts`: under 24h old, and no table
+ * collapsed since the shrink, under the checkpoint policy. Growth is fine.
+ */
+export function evaluateShrinkAck(raw, tableNames, candidateCounts, now = Date.now()) {
+    const ack = raw;
+    if (!ack || typeof ack !== 'object' || (ack.producer !== 'prune' && ack.producer !== 'dream')
+        || !ack.tableCounts || typeof ack.tableCounts !== 'object') {
+        return { honoured: false, reason: 'malformed acknowledgement' };
+    }
+    const at = Date.parse(String(ack.at));
+    if (!Number.isFinite(at) || at > now + SHRINK_ACK_MAX_SKEW_MS) {
+        return { honoured: false, reason: `invalid time ${String(ack.at)}` };
+    }
+    if (now - at > SHRINK_ACK_MAX_AGE_MS) {
+        return { honoured: false, reason: `older than 24h (${ack.producer} at ${ack.at})` };
+    }
+    try {
+        assertNotPoorerThanMirror(tableNames, ack.tableCounts, candidateCounts, 'checkpoint');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.replace(/^RVF_MIRROR_[A-Z_]+: /, '') : String(error);
+        return { honoured: false, reason: `the brain shrank again since the ${ack.producer}: ${detail.split('.')[0]}` };
+    }
+    return { honoured: true, producer: ack.producer };
+}
+//# sourceMappingURL=brain-rvf-richness.js.map

package/dist/kernel/unified-memory-migration.js

@@ -70,8 +70,8 @@ export async function migrateToUnifiedMemory(options) {
             if (!fs.existsSync(opts.baseDir)) {
                 fs.mkdirSync(opts.baseDir, { recursive: true });
             }
+            // #1164: openDatabase() set the journal mode (retrying contention, honouring AQE_DISABLE_WAL).
             targetDb = openDatabase(memoryDbPath);
-            targetDb.pragma('journal_mode = WAL');
         }
         // Get list of tables to migrate
         const tablesToMigrate = [

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-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

package/dist/learning/embedding-space-registry.d.ts

@@ -37,6 +37,8 @@ export type EmbeddingSpaceResolution =
  | 'matched-cosine'
 /** No registered space matched: the derived space was registered. */
  | 'registered'
+/** No registered space matched; a pre-registry space id was verified and registered (#1302). */
+ | 'adopted-legacy'
 /** No usable registry: the derived space is used as before. */
  | 'unavailable';
 export interface ResolvedEmbeddingSpace {
@@ -72,4 +74,17 @@ export declare function registerEmbeddingSpace(db: EmbeddingSpaceRegistryDb, spa
  * when the registry cannot be read the derived space is used, as before.
  */
 export declare function resolveEmbeddingSpace(db: EmbeddingSpaceRegistryDb | null, derived: EmbeddingSpaceIdentity, canaryText: string, canary: readonly number[]): ResolvedEmbeddingSpace;
+/**
+ * Picks a legacy space id (one with stored vectors but no registry entry) the
+ * runtime belongs to, or null. Throws only on an unexpected failure.
+ */
+export type LegacySpaceAdopter = (derived: EmbeddingSpaceIdentity, registered: readonly RegisteredEmbeddingSpace[]) => Promise<string | null>;
+/**
+ * #1302: like resolveEmbeddingSpace, but before registering a new space the
+ * adopter may name a legacy space id the runtime has been shown to reproduce.
+ * That id is kept and registered with the current canary as its reference.
+ * Its identity carries the current runtime fields: a pre-registry id is a
+ * hash that cannot be reversed into the fields it was minted from.
+ */
+export declare function resolveEmbeddingSpaceAdoptingLegacy(db: EmbeddingSpaceRegistryDb | null, derived: EmbeddingSpaceIdentity, canaryText: string, canary: readonly number[], adoptLegacy: LegacySpaceAdopter): Promise<ResolvedEmbeddingSpace>;
 //# sourceMappingURL=embedding-space-registry.d.ts.map

package/dist/learning/embedding-space-registry.js

@@ -104,11 +104,45 @@ export function registerEmbeddingSpace(db, space) {
  * when the registry cannot be read the derived space is used, as before.
  */
 export function resolveEmbeddingSpace(db, derived, canaryText, canary) {
+    const lookup = lookupEmbeddingSpace(db, derived, canaryText, canary);
+    if (lookup.resolved)
+        return lookup.resolved;
+    return registerResolvedSpace(lookup.db, derived, canaryText, canary, 'registered', lookup.otherSpaces);
+}
+/**
+ * #1302: like resolveEmbeddingSpace, but before registering a new space the
+ * adopter may name a legacy space id the runtime has been shown to reproduce.
+ * That id is kept and registered with the current canary as its reference.
+ * Its identity carries the current runtime fields: a pre-registry id is a
+ * hash that cannot be reversed into the fields it was minted from.
+ */
+export async function resolveEmbeddingSpaceAdoptingLegacy(db, derived, canaryText, canary, adoptLegacy) {
+    const lookup = lookupEmbeddingSpace(db, derived, canaryText, canary);
+    if (lookup.resolved)
+        return lookup.resolved;
+    let legacySpaceId = null;
+    try {
+        legacySpaceId = await adoptLegacy(derived, lookup.entries);
+    }
+    catch (error) {
+        console.warn(`[EmbeddingSpaceRegistry] legacy space check failed (${toErrorMessage(error)}); ` +
+            `registering the derived space id`);
+    }
+    if (legacySpaceId) {
+        const adopted = { ...derived, spaceId: legacySpaceId };
+        return registerResolvedSpace(lookup.db, adopted, canaryText, canary, 'adopted-legacy', 0);
+    }
+    return registerResolvedSpace(lookup.db, derived, canaryText, canary, 'registered', lookup.otherSpaces);
+}
+/** A registered match (or the unavailable fallback), or what is needed to register. */
+function lookupEmbeddingSpace(db, derived, canaryText, canary) {
     const unavailable = () => ({
-        identity: derived,
-        resolution: 'unavailable',
-        otherSpaces: 0,
-        registration: Promise.resolve(),
+        resolved: {
+            identity: derived,
+            resolution: 'unavailable',
+            otherSpaces: 0,
+            registration: Promise.resolve(),
+        },
     });
     if (!db)
         return unavailable();
@@ -124,19 +158,24 @@ export function resolveEmbeddingSpace(db, derived, canaryText, canary) {
     const match = matchRegisteredSpace(derived, canaryText, canary, entries);
     if (match) {
         return {
-            identity: match.entry.identity,
-            resolution: match.exact ? 'matched-exact' : 'matched-cosine',
-            otherSpaces: 0,
-            registration: Promise.resolve(),
+            resolved: {
+                identity: match.entry.identity,
+                resolution: match.exact ? 'matched-exact' : 'matched-cosine',
+                otherSpaces: 0,
+                registration: Promise.resolve(),
+            },
         };
     }
     const otherSpaces = entries.filter((entry) => entry.canaryText === canaryText && sameEmbeddingSpaceConfig(entry.identity, derived)).length;
+    return { db, entries, otherSpaces };
+}
+function registerResolvedSpace(db, identity, canaryText, canary, resolution, otherSpaces) {
     const registration = Promise.resolve()
-        .then(() => registerEmbeddingSpace(db, { identity: derived, canaryText, canary: [...canary] }))
+        .then(() => registerEmbeddingSpace(db, { identity, canaryText, canary: [...canary] }))
         .catch((error) => {
-        console.warn(`[EmbeddingSpaceRegistry] could not register embedding space ${derived.spaceId.slice(0, 12)} ` +
+        console.warn(`[EmbeddingSpaceRegistry] could not register embedding space ${identity.spaceId.slice(0, 12)} ` +
             `(${toErrorMessage(error)}); it is registered at a later start`);
     });
-    return { identity: derived, resolution: 'registered', otherSpaces, registration };
+    return { identity, resolution, otherSpaces, registration };
 }
 //# sourceMappingURL=embedding-space-registry.js.map

package/dist/learning/experience-capture.d.ts

@@ -254,7 +254,9 @@ export declare class ExperienceCaptureService {
     /**
      * Extract pattern from experience
      */
-    extractPattern(experience: TaskExperience): Promise<PatternExtractionResult>;
+    extractPattern(experience: TaskExperience, options?: {
+        createIfMissing?: boolean;
+    }): Promise<PatternExtractionResult>;
     /**
      * Share experience across domains
      */