@neuralis/brain-core 0.1.0 → 0.2.0

package/dist/src/usecases/vector/rebuildGeneration.js

@@ -1,8 +1,12 @@
 import { indexEligibilityReader, recoveryPayload } from './indexEligibility.js';
+import { randomUUID } from 'node:crypto';
+import { computeContentHash } from '../../domain/contentHash.js';
+import { mediaEmbeddingInput } from '../syncPointWrites.js';
+import { VECTOR_WRITE_REQUEST_BYTES } from '../../vector/types.js';
 import { getActiveLock, mutateLock, sameVectorSpace, generationOf, } from '../../embeddings/lock.js';
 import { embedModelMarker, supportsEmbedInput } from '../../embeddings/models.js';
-import { invalidateEmbedders } from '../../embeddings/factory.js';
-import { generationFor, getBrainConfigBoolean, getBrainConfigNumber, resolveEmbeddingModel, resolveTargetEmbeddingShape, } from '../../config/env.js';
+import { embeddingUnavailableReason, invalidateEmbedders } from '../../embeddings/factory.js';
+import { generationFor, getBrainConfigBoolean, getBrainConfigNumber, resolveEmbeddingModel, resolveTargetEmbeddingShape, embeddingEnabled, } from '../../config/env.js';
 import { buildEmbedderFor } from '../../embeddings/factory.js';
 import { readHealContent } from '../syncPointWrites.js';
 import { readMediaInputForPoint } from '../mediaLane.js';
@@ -39,6 +43,9 @@ export class RebuildError extends Error {
         this.name = 'RebuildError';
     }
 }
+function hasWriteBoundary(vector) {
+    return typeof vector.exclusive === 'function';
+}
 /**
  * The text a point's vector is built from — the ONE rule the scan and the
  * mirror share: a chunk embeds its own `content`; a document embeds its
@@ -62,7 +69,7 @@ export function embedTextForPoint(payload) {
  * content-less text point's stored text through the same text rule, a media
  * point's bytes or page. `undefined` = unreadable.
  */
-async function inputFor(deps, payload) {
+export async function inputFor(deps, payload) {
     const inline = embedTextForPoint(payload);
     if (inline !== undefined)
         return { kind: 'text', text: inline };
@@ -77,7 +84,7 @@ async function inputFor(deps, payload) {
  * one call each. A media input the target cannot take (`supportsEmbedInput`
  * over its `modalities`) answers `null` — the caller leaves it out.
  */
-async function embedInputs(embedder, inputs, signal) {
+export async function embedInputs(embedder, inputs, signal) {
     const out = new Array(inputs.length).fill(null);
     const textAt = [];
     for (let i = 0; i < inputs.length; i += 1)
@@ -101,10 +108,13 @@ async function embedInputs(embedder, inputs, signal) {
 }
 /** Eligibility handles recovery state; compare content/provenance independently of index markers. */
 function samePayload(a, b) {
+    if (a.embedding_status !== 'current' || typeof a.embedding_generation !== 'number'
+        || typeof a.embedding_input_hash !== 'string' || typeof a.embed_model !== 'string')
+        return false;
     return stableStringify(withoutMarker(a)) === stableStringify(withoutMarker(b));
 }
 function withoutMarker(payload) {
-    const { embed_model: _marker, recovery_only: _recovery, ...rest } = payload;
+    const { embed_model: _marker, recovery_only: _recovery, embedding_status: _status, embedding_generation: _generation, embedding_input_hash: _hash, embedding_updated_at: _updated, ...rest } = payload;
     return rest;
 }
 function stableStringify(value) {
@@ -134,6 +144,7 @@ export class GenerationMirror {
     #shadow;
     #embedder;
     #marker;
+    generation;
     #queue = [];
     #queueBytes = 0;
     #dirty = new Set();
@@ -150,6 +161,7 @@ export class GenerationMirror {
         this.#shadow = shadow;
         this.#embedder = embedder;
         this.#marker = embedModelMarker(target.modelId, target.dimension, target.embedRecipe);
+        this.generation = seed.generation;
         for (const id of seed.dirty)
             this.#dirty.add(id);
         for (const filter of seed.failedDeletes)
@@ -194,6 +206,17 @@ export class GenerationMirror {
     afterRetention(point) {
         this.#enqueue({ kind: 'retention', id: point.id, payload: point.payload });
     }
+    /** A native multi-operation failure may have committed a prefix; re-read before swap. */
+    afterUncertainWrite(ids) {
+        for (const id of ids)
+            this.#dirty.add(id);
+        this.#persistDirty();
+    }
+    /** A failed primary delete is reconciliation intent, never a destructive replay. */
+    afterUncertainDelete(filter) {
+        this.#failedDeletes.push(filter);
+        this.#persistDirty();
+    }
     afterDelete(filter) {
         this.#enqueue({ kind: 'delete', filter });
     }
@@ -250,8 +273,18 @@ export class GenerationMirror {
                 window.touched.add(item.id);
             return;
         }
-        const payload = searchablePayload(item.payload, this.#marker);
+        const input = await inputFor(this.#deps, item.payload);
+        if (!input)
+            throw new RebuildError('classification_unresolved', 'source-input-unavailable');
+        const payload = searchablePayload(item.payload, this.#marker, this.generation, input);
         if (item.kind === 'payload' && !item.payload.recovery_only) {
+            const previous = (await this.#deps.generations.payloads(this.#shadow, [item.id])).get(item.id);
+            if (!previous || previous.embedding_status !== 'current' || previous.embedding_generation !== this.generation
+                || previous.embed_model !== this.#marker || previous.embedding_input_hash !== payload.embedding_input_hash) {
+                payload.embedding_status = 'stale';
+                this.#dirty.add(item.id);
+                this.#persistDirty();
+            }
             if (!(await this.#deps.generations.overwritePayload(this.#shadow, item.id, payload))) {
                 // Not in the shadow yet: the scan may already hold an OLDER read of
                 // it, so the point is re-processed from the active one before the swap.
@@ -261,7 +294,6 @@ export class GenerationMirror {
             }
         }
         else {
-            const input = await inputFor(this.#deps, item.payload);
             const [embedding] = input ? await embedInputs(this.#embedder, [input]) : [null];
             if (!embedding) {
                 throw new RebuildError('classification_unresolved', 'source-input-unavailable');
@@ -345,6 +377,8 @@ let runningLoop = null;
 export function getGenerationMirror() {
     return installedMirror;
 }
+/** Cancellation cannot take over maintenance admission while setup is still awaiting creation. */
+export function isRebuildRunning() { return runningLoop !== null; }
 /** Test seam: drop the process state between cases. */
 export function resetRebuildStateForTesting() {
     installedMirror = null;
@@ -373,14 +407,18 @@ export async function pauseInterruptedRebuild(appRoot, logger) {
  * Start a rebuild toward the configured target, or resume a paused one.
  * Returns once the run is set up (shadow created, mirror installed); the scan
  * continues in the background and calls `release` when it ends — the caller's
- * latch is held until then.
+ * latch is held until then. `onEnd` hears how the background run ended
+ * (`completed` = swapped to the new generation, `paused` = dirty or failed); a
+ * cancel reports nothing. It lives in this process only (never in the lock).
  */
-export async function startRebuild(deps, release) {
+export async function startRebuild(deps, release, onEnd) {
     if (runningLoop)
         throw new RebuildError('rebuild_running', 'A rebuild is already running in this process');
+    if (!embeddingEnabled())
+        throw new RebuildError('target_unavailable', 'embedding_disabled');
     const lock = await getActiveLock(deps.appRoot);
     if (!lock)
-        throw new RebuildError('no_active_generation', 'There is no active vector index to rebuild yet');
+        throw new RebuildError('no_active_generation', 'Initialize the serving data index before starting a rebuild');
     let rebuild = lock.rebuild;
     const resumed = Boolean(rebuild);
     if (!rebuild) {
@@ -388,15 +426,18 @@ export async function startRebuild(deps, release) {
         if ('error' in resolved)
             throw new RebuildError('target_unavailable', resolved.error);
         const target = generationFor(resolved.info, resolved.dimension);
-        if (sameVectorSpace(generationOf(lock), target)) {
+        if (lock.mode === 'dense' && sameVectorSpace(generationOf(lock), target)) {
             throw new RebuildError('no_switch_pending', 'The configured model already is the active one — nothing to rebuild');
         }
-        const generation = lock.generation + 1;
+        const generation = lock.mode === 'dense' ? lock.generation + 1 : 1;
         rebuild = {
             target,
             generation,
-            shadowCollection: deps.generations.collectionName(generation),
+            shadowCollection: lock.mode === 'metadata'
+                ? `${deps.generations.collectionName(generation)}__shadow_${randomUUID()}`
+                : deps.generations.collectionName(generation),
             state: 'running',
+            phase: 'prepared',
             startedAt: now(deps),
             processed: 0,
             dirty: [],
@@ -411,36 +452,68 @@ export async function startRebuild(deps, release) {
         embedder = await deps.buildTargetEmbedder(rebuild.target);
     }
     catch (error) {
-        throw new RebuildError('target_unavailable', error instanceof Error ? error.message : String(error));
+        const reason = embeddingUnavailableReason(error);
+        if (!reason)
+            throw error;
+        throw new RebuildError('target_unavailable', reason);
+    }
+    if (!resumed && await deps.generations.exists(rebuild.shadowCollection)) {
+        throw new RebuildError('target_unavailable', 'unrecorded_shadow_exists');
     }
-    if (!(await deps.generations.exists(rebuild.shadowCollection))) {
-        await deps.generations.create(rebuild.shadowCollection, rebuild.target.dimension);
-        // A shadow that vanished while paused is rebuilt from nothing.
-        if (resumed)
-            rebuild = { ...rebuild, processed: 0, dirty: [], failedDeletes: [] };
+    // Record ownership before creating a shadow; restart/cancel never guesses.
+    await mutateLock(deps.appRoot, current => current ? { ...current, rebuild } : null);
+    try {
+        if (!(await deps.generations.exists(rebuild.shadowCollection))) {
+            await deps.generations.create(rebuild.shadowCollection, rebuild.target.dimension);
+            // A shadow that vanished while paused is rebuilt from nothing.
+            if (resumed)
+                rebuild = { ...rebuild, processed: 0, dirty: [], failedDeletes: [] };
+        }
+        await deps.generations.validate(rebuild.shadowCollection, rebuild.target.dimension);
     }
-    else if (!resumed) {
-        // Debris of an earlier run nobody recorded — never build on it.
-        await deps.generations.drop(rebuild.shadowCollection);
-        await deps.generations.create(rebuild.shadowCollection, rebuild.target.dimension);
+    catch (error) {
+        await pause(deps, 'error', error instanceof Error ? error.message : String(error));
+        throw error;
     }
     // A resume re-verifies from the start (see the module doc).
     const running = {
         ...rebuild,
         state: 'running',
+        phase: 'copying',
         cursor: undefined,
         scanDone: false,
         updatedAt: now(deps),
     };
     delete running.pausedReason;
     delete running.lastError;
-    await mutateLock(deps.appRoot, (current) => current ? { ...current, rebuild: running } : null);
     const mirror = new GenerationMirror(deps, running.shadowCollection, embedder, running.target, running);
-    installedMirror = mirror;
+    const install = async () => {
+        await mutateLock(deps.appRoot, current => current ? { ...current, rebuild: running } : null);
+        installedMirror = mirror;
+    };
+    try {
+        await deps.vector.exclusive(install);
+    }
+    catch (error) {
+        await pause(deps, 'error', error instanceof Error ? error.message : String(error));
+        throw error;
+    }
     const abort = new AbortController();
     const done = runLoop(deps, mirror, embedder, abort.signal)
         .catch(async (error) => {
         await pause(deps, 'error', error instanceof Error ? error.message : String(error));
+    })
+        .then(async () => {
+        if (!onEnd)
+            return;
+        const after = await getActiveLock(deps.appRoot).catch(() => null);
+        try {
+            if (after?.mode === 'dense' && !after.rebuild && after.generation === running.generation)
+                onEnd('completed');
+            else if (after?.rebuild?.state === 'paused')
+                onEnd('paused');
+        }
+        catch { /* a notification never changes the run */ }
     })
         .finally(() => {
         runningLoop = null;
@@ -478,6 +551,24 @@ async function runLoop(deps, mirror, embedder, signal) {
         const ids = page.points.map((p) => p.id);
         const inShadow = await deps.generations.payloads(shadow, ids);
         const work = [];
+        let inputBytes = 0;
+        const flush = async () => {
+            if (!work.length)
+                return;
+            const vectors = await embedInputs(embedder, work.map(w => w.input), signal);
+            const points = work.flatMap((w, i) => {
+                if (!vectors[i])
+                    throw new RebuildError('classification_unresolved', 'unsupported-input-kind');
+                if (window.touched.has(w.id))
+                    return [];
+                return [{ id: w.id, vector: vectors[i], payload: searchablePayload(w.payload, mirror.marker, mirror.generation, w.input) }];
+            });
+            if (points.length)
+                await deps.generations.upsert(shadow, points, { signal });
+            processed += points.length;
+            work.length = 0;
+            inputBytes = 0;
+        };
         const leaveOut = (uri) => {
             unreadable.count += 1;
             if (unreadable.sample.length < UNREADABLE_SAMPLE && typeof uri === 'string')
@@ -488,30 +579,25 @@ async function runLoop(deps, mirror, embedder, signal) {
             const copy = inShadow.get(point.id);
             if (!(await carryEligibility(deps, shadow, point.id, point.payload)))
                 continue;
-            if (copy && !copy.recovery_only && samePayload(copy, payload))
-                continue;
             const input = await inputFor(deps, point.payload);
             if (input === undefined) {
                 leaveOut(point.payload.uri);
                 throw new RebuildError('classification_unresolved', 'source-input-unavailable');
             }
+            const proof = searchablePayload(payload, mirror.marker, mirror.generation, input);
+            if (copy && !copy.recovery_only && samePayload(copy, payload) && copy.embedding_status === 'current'
+                && copy.embedding_generation === mirror.generation && copy.embed_model === mirror.marker
+                && copy.embedding_input_hash === proof.embedding_input_hash)
+                continue;
+            const bytes = input.kind === 'text' ? Buffer.byteLength(input.text, 'utf8') : input.bytes.length;
+            if (work.length && inputBytes + bytes > VECTOR_WRITE_REQUEST_BYTES)
+                await flush();
             work.push({ id: point.id, input, payload });
+            inputBytes += bytes;
+            if (inputBytes >= VECTOR_WRITE_REQUEST_BYTES)
+                await flush();
         }
-        if (work.length > 0) {
-            const vectors = await embedInputs(embedder, work.map((w) => w.input), signal);
-            const points = [];
-            work.forEach((w, i) => {
-                // A media point the target model cannot embed is left out and named.
-                if (!vectors[i])
-                    throw new RebuildError('classification_unresolved', 'unsupported-input-kind');
-                // A mirror write that landed after this page was read is newer — keep it.
-                if (window.touched.has(w.id))
-                    return;
-                points.push({ id: w.id, vector: vectors[i], payload: searchablePayload(w.payload, mirror.marker) });
-            });
-            await deps.generations.upsert(shadow, points, { signal });
-            processed += points.length;
-        }
+        await flush();
         // Retained payloads can overwrite newer mirror writes too; keep the window
         // open through every page write and re-process raced IDs from the active store.
         const touched = mirror.closeWindow(window);
@@ -519,7 +605,7 @@ async function runLoop(deps, mirror, embedder, signal) {
         if (raced.length > 0)
             mirror.restoreDirty(raced, []);
         for (const filter of touched.deletes)
-            await deps.generations.deleteByFilter(shadow, filter);
+            mirror.afterUncertainDelete(filter);
         cursor = page.nextCursor;
         await mutateLock(deps.appRoot, (current) => current?.rebuild
             ? { ...current, rebuild: { ...current.rebuild, cursor, processed, unreadable, updatedAt: now(deps) } }
@@ -594,19 +680,25 @@ async function runLoop(deps, mirror, embedder, signal) {
                 mirror.restoreDirty(dirty, []);
                 return false;
             }
+            await mutateLock(deps.appRoot, current => current?.rebuild
+                ? { ...current, rebuild: { ...current.rebuild, phase: 'ready', updatedAt: now(deps) } }
+                : null);
             await swap(deps, shadow);
             deps.mutations?.clear(changed);
             return true;
         };
-        const swapped = await mirror.trySwap(() => deps.mutations ? deps.mutations.exclusive(finish) : finish());
+        const finishSwap = () => mirror.trySwap(() => deps.mutations ? deps.mutations.exclusive(finish) : finish());
+        const swapped = await deps.vector.exclusive(finishSwap);
         if (swapped)
             return;
     }
     await pause(deps, 'dirty', `${mirror.dirtyCount} point(s) still differ after ${MAX_DIRTY_ROUNDS} rounds`);
 }
-function searchablePayload(payload, marker) {
+function searchablePayload(payload, marker, generation, input) {
     const { recovery_only: ignored, ...rest } = payload;
-    return { ...rest, embed_model: marker };
+    return { ...rest, embed_model: marker, embedding_status: 'current', embedding_generation: generation,
+        embedding_input_hash: computeContentHash(input.kind === 'text' ? input.text : mediaEmbeddingInput(payload)),
+        embedding_updated_at: new Date().toISOString(), };
 }
 async function carryEligibility(deps, shadow, id, payload) {
     const classification = await deps.classify(payload);
@@ -634,8 +726,28 @@ async function embedAll(embedder, texts, signal) {
     return out;
 }
 async function reprocess(deps, mirror, embedder, shadow, ids, deletes, signal) {
-    for (const filter of deletes)
-        await deps.generations.deleteByFilter(shadow, filter);
+    // The existing id-only shadow port has no filter projection. On uncertain
+    // deletion, reconcile bounded pages against the primary rather than replay
+    // a filter that could destroy a surviving or newly written point.
+    if (deletes.length) {
+        let cursor;
+        do {
+            signal.throwIfAborted();
+            const scanned = await deps.generations.scanIds(shadow, { limit: DIRTY_BATCH, ...(cursor ? { cursor } : {}) });
+            if (scanned.ids.length) {
+                const primary = await deps.vector.scroll({ filter: { mustMatchAny: [{ field: 'id', values: scanned.ids }] }, limit: scanned.ids.length });
+                const alive = new Map(primary.points.map(point => [point.id, point.payload]));
+                const copies = await deps.generations.payloads(shadow, scanned.ids);
+                const absent = scanned.ids.filter(id => !alive.has(id));
+                if (absent.length)
+                    await deps.generations.deleteByFilter(shadow, { mustMatchAny: [{ field: 'id', values: absent }] });
+                const changed = primary.points.filter(point => !samePayload(copies.get(point.id) ?? {}, point.payload)).map(point => point.id);
+                if (changed.length)
+                    await reprocess(deps, mirror, embedder, shadow, changed, [], signal);
+            }
+            cursor = scanned.nextCursor;
+        } while (cursor);
+    }
     for (let i = 0; i < ids.length; i += DIRTY_BATCH) {
         const batch = ids.slice(i, i + DIRTY_BATCH);
         const page = await deps.vector.scroll({ filter: { mustMatchAny: [{ field: 'id', values: batch }] }, limit: batch.length });
@@ -644,24 +756,35 @@ async function reprocess(deps, mirror, embedder, shadow, ids, deletes, signal) {
         if (gone.length > 0)
             await deps.generations.deleteByFilter(shadow, { mustMatchAny: [{ field: 'id', values: gone }] });
         const work = [];
+        let inputBytes = 0;
+        const flush = async () => {
+            if (!work.length)
+                return;
+            const vectors = await embedInputs(embedder, work.map(w => w.input), signal);
+            const points = work.map((w, j) => {
+                if (!vectors[j])
+                    throw new RebuildError('classification_unresolved', 'unsupported-input-kind');
+                return { id: w.id, vector: vectors[j], payload: searchablePayload(w.payload, mirror.marker, mirror.generation, w.input) };
+            });
+            await deps.generations.upsert(shadow, points, { signal });
+            work.length = 0;
+            inputBytes = 0;
+        };
         for (const [id, payload] of alive) {
             if (!(await carryEligibility(deps, shadow, id, payload)))
                 continue;
             const input = await inputFor(deps, payload);
             if (input === undefined)
                 throw new RebuildError('classification_unresolved', 'source-input-unavailable');
+            const bytes = input.kind === 'text' ? Buffer.byteLength(input.text, 'utf8') : input.bytes.length;
+            if (work.length && inputBytes + bytes > VECTOR_WRITE_REQUEST_BYTES)
+                await flush();
             work.push({ id, input, payload: payload });
+            inputBytes += bytes;
+            if (inputBytes >= VECTOR_WRITE_REQUEST_BYTES)
+                await flush();
         }
-        if (work.length === 0)
-            continue;
-        const vectors = await embedInputs(embedder, work.map((w) => w.input), signal);
-        if (vectors.some(vector => !vector))
-            throw new RebuildError('classification_unresolved', 'unsupported-input-kind');
-        const points = work.flatMap((w, j) => (vectors[j]
-            ? [{ id: w.id, vector: vectors[j], payload: searchablePayload(w.payload, mirror.marker) }]
-            : []));
-        if (points.length > 0)
-            await deps.generations.upsert(shadow, points, { signal });
+        await flush();
     }
 }
 async function swap(deps, shadow) {
@@ -672,7 +795,8 @@ async function swap(deps, shadow) {
         previous = lock.collection;
         const { target, generation } = lock.rebuild;
         return {
-            version: 2,
+            version: 3,
+            mode: 'dense',
             generation,
             collection: shadow,
             ...target,
@@ -709,19 +833,32 @@ export async function cancelRebuild(deps) {
         await loop.done;
     }
     const shadow = lock.rebuild.shadowCollection;
-    await mutateLock(deps.appRoot, (current) => {
-        if (!current?.rebuild)
-            return null;
-        const { rebuild: _dropped, ...rest } = current;
-        return rest;
-    });
-    let dropped;
-    if (await deps.generations.exists(shadow)) {
-        await deps.generations.drop(shadow);
-        dropped = shadow;
-    }
-    deps.logger?.info('vector.rebuild.cancelled', { shadow });
-    return { cancelled: true, ...(dropped ? { dropped } : {}) };
+    const remove = async () => {
+        const current = await getActiveLock(deps.appRoot);
+        if (current?.collection === shadow || current?.rebuild?.shadowCollection !== shadow) {
+            throw new RebuildError('no_rebuild', 'The recorded rebuild changed before cancellation');
+        }
+        let dropped;
+        try {
+            if (await deps.generations.exists(shadow)) {
+                await deps.generations.drop(shadow);
+                dropped = shadow;
+            }
+        }
+        catch (error) {
+            await pause(deps, 'error', error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        await mutateLock(deps.appRoot, current => {
+            if (!current?.rebuild || current.rebuild.shadowCollection !== shadow)
+                return null;
+            const { rebuild: _dropped, ...rest } = current;
+            return rest;
+        });
+        deps.logger?.info('vector.rebuild.cancelled', { shadow });
+        return { cancelled: true, ...(dropped ? { dropped } : {}) };
+    };
+    return deps.vector.exclusive(remove);
 }
 /** Wait for a running loop (tests; a swap/cancel is observable through the lock). */
 export async function awaitRebuildLoop() {
@@ -775,24 +912,26 @@ export async function describeEmbeddingState(deps, pointsTotal = null) {
     const lock = await getActiveLock(deps.appRoot);
     const resolved = deps.resolveTarget();
     const target = 'error' in resolved ? null : generationFor(resolved.info, resolved.dimension);
-    const active = lock ? generationOf(lock) : null;
-    const marker = lock ? embedModelMarker(lock.modelId, lock.dimension, lock.embedRecipe) : null;
+    const dense = lock?.mode === 'dense' ? lock : null;
+    const active = dense ? generationOf(dense) : null;
+    const marker = dense ? embedModelMarker(dense.modelId, dense.dimension, dense.embedRecipe) : null;
     let points = null;
-    if (lock && deps.vector.countByFilter) {
+    if (dense && deps.vector.countByFilter) {
         const total = pointsTotal ?? await deps.vector.countByFilter({});
         const stampedActive = await deps.vector.countByFilter({ must: [{ field: 'embed_model', equals: marker }] });
         points = { total, stampedActive, unstamped: Math.max(0, total - stampedActive) };
     }
     const targetInfo = 'error' in resolved ? null : resolved.info;
     return {
-        active: lock
+        active: dense
             ? {
                 ...active,
-                generation: lock.generation,
-                collection: lock.collection,
-                createdAt: lock.createdAt,
-                ...(lock.backfilledAt ? { backfilledAt: lock.backfilledAt } : {}),
-                resolvable: Boolean(resolveEmbeddingModel(lock.modelId)),
+                mode: 'dense',
+                generation: dense.generation,
+                collection: dense.collection,
+                createdAt: dense.createdAt,
+                ...(dense.backfilledAt ? { backfilledAt: dense.backfilledAt } : {}),
+                resolvable: Boolean(resolveEmbeddingModel(dense.modelId)),
             }
             : null,
         target: target
@@ -800,6 +939,7 @@ export async function describeEmbeddingState(deps, pointsTotal = null) {
             : { error: resolved.error },
         switchPending: Boolean(active && target && !sameVectorSpace(active, target)),
         points,
+        serving: lock ? { mode: lock.mode, collection: lock.collection } : null,
         rebuild: describeRebuild(lock?.rebuild),
         lastEstimate: currentTargetEstimate(target?.modelId),
         spend: getEmbeddingUsageMeter()?.snapshot() ?? null,
@@ -847,6 +987,8 @@ export async function primeEmbeddingState(opts) {
  * through ITS project's connector (only bytes that still hash to the point).
  */
 export function buildRebuildDeps(opts) {
+    if (!hasWriteBoundary(opts.vector))
+        throw new Error('FILESYSTEM_WRITE_BOUNDARY_REQUIRED');
     return {
         appRoot: opts.appRoot,
         classify: indexEligibilityReader(opts.sourceConfigs),
@@ -916,7 +1058,7 @@ export async function bootEmbeddingGeneration(opts) {
     }
     await opts.vector.ensureAgentCollection('');
     const lock = await getActiveLock(opts.appRoot).catch(() => null);
-    if (lock && !resolveEmbeddingModel(lock.modelId)) {
+    if (lock?.mode === 'dense' && !resolveEmbeddingModel(lock.modelId)) {
         opts.logger.warn('vector.active_model_unresolvable', {
             modelId: lock.modelId,
             impact: 'semantic search falls back to full-text; writes are stored unembedded until the model is defined again or the index is rebuilt',