@unbrained/pm-cli 2026.7.1 → 2026.7.2

package/dist/cli/commands/reindex.js

@@ -4,7 +4,7 @@
  * Implements the pm reindex command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aa59b937-1085-5a08-9ac6-84c64d6b6a8f")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8dd50c77-d026-565f-8f07-e63602a44f09")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -127,6 +127,7 @@ export const _testOnly = {
     collectLedgerOrphanIds,
     resetVectorStoreForReindex,
     pruneReindexOrphanVectors,
+    upsertReindexVectors,
 };
 function resolveExtensionSearchEmbedding(settings) {
     const registrations = getActiveExtensionRegistrations();
@@ -178,16 +179,18 @@ function resolveExtensionVectorAdapter(settings) {
         return null;
     }
     const runtimeDefinition = registration.runtime_definition ?? registration.definition;
-    const name = toOptionalNonEmptyString(runtimeDefinition.name) ??
+    const adapterDisplayName = toOptionalNonEmptyString(runtimeDefinition.name) ??
         toOptionalNonEmptyString(registration.definition.name);
-    const upsert = runtimeDefinition.upsert;
-    const deleteHandler = runtimeDefinition.delete;
-    if (!name || typeof upsert !== "function") {
+    /* c8 ignore start -- resolveRegisteredVectorStoreAdapter only returns registrations with a normalized runtime or definition name */
+    if (!adapterDisplayName) {
         return null;
     }
+    /* c8 ignore stop */
+    const upsert = runtimeDefinition.upsert;
+    const deleteHandler = runtimeDefinition.delete;
     return {
-        name,
-        upsert: upsert,
+        adapterName: adapterDisplayName,
+        ...(typeof upsert === "function" ? { upsert: upsert } : {}),
         ...(typeof deleteHandler === "function" ? { delete: deleteHandler } : {}),
     };
 }
@@ -299,11 +302,11 @@ async function resetVectorStoreForReindex(activeVectorStore, extensionVectorAdap
                 await Promise.resolve(extensionVectorAdapter.delete({ ids: knownIds.sort((left, right) => left.localeCompare(right)), settings }));
             }
             catch (error) {
-                throw new PmCliError(`Extension vector adapter "${extensionVectorAdapter.name}" failed to delete vectors during reindex reset: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
+                throw new PmCliError(`Extension vector adapter "${extensionVectorAdapter.adapterName}" failed to delete vectors during reindex reset: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
             }
         }
         else if (knownIds.length > 0) {
-            semanticWarnings.push(`search_semantic_reindex_reset_skipped:adapter=${extensionVectorAdapter.name}:known_ids=${knownIds.length}`);
+            semanticWarnings.push(`search_semantic_reindex_reset_skipped:adapter=${extensionVectorAdapter.adapterName}:known_ids=${knownIds.length}`);
         }
         if (!activeVectorStore) {
             return;
@@ -323,11 +326,11 @@ async function pruneReindexOrphanVectors(activeVectorStore, extensionVectorAdapt
                 await Promise.resolve(extensionVectorAdapter.delete({ ids: orphanIds, settings }));
             }
             catch (error) {
-                throw new PmCliError(`Extension vector adapter "${extensionVectorAdapter.name}" failed to delete orphan vectors during reindex: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
+                throw new PmCliError(`Extension vector adapter "${extensionVectorAdapter.adapterName}" failed to delete orphan vectors during reindex: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
             }
         }
         else {
-            semanticWarnings.push(`search_semantic_reindex_orphan_prune_skipped:adapter=${extensionVectorAdapter.name}:count=${orphanIds.length}`);
+            semanticWarnings.push(`search_semantic_reindex_orphan_prune_skipped:adapter=${extensionVectorAdapter.adapterName}:count=${orphanIds.length}`);
         }
         if (!activeVectorStore) {
             return;
@@ -337,6 +340,293 @@ async function pruneReindexOrphanVectors(activeVectorStore, extensionVectorAdapt
         await executeVectorDelete(activeVectorStore, orphanIds);
     }
 }
+function createReindexSemanticSummary(mode) {
+    return {
+        enabled: mode !== "keyword",
+        stale_items: 0,
+        unchanged_items: 0,
+        embedded_items: 0,
+        vector_upserted: 0,
+        batches_completed: 0,
+    };
+}
+function buildReindexManifest(mode, generatedAt, metadataDocuments) {
+    return {
+        version: 1,
+        mode,
+        generated_at: generatedAt,
+        total_items: metadataDocuments.length,
+        items: metadataDocuments.map((document) => ({
+            id: document.metadata.id,
+            type: document.metadata.type,
+            status: document.metadata.status,
+            priority: document.metadata.priority,
+            updated_at: document.metadata.updated_at,
+        })),
+    };
+}
+function assertSemanticRuntimeAvailable(params) {
+    if (params.requestedMode === "keyword") {
+        return {
+            activeEmbeddingProvider: null,
+            activeVectorStore: null,
+        };
+    }
+    const providerResolution = resolveEmbeddingProviders(params.settings);
+    if (!providerResolution.active && !params.extensionEmbedding) {
+        throw new PmCliError(`Reindex mode '${params.requestedMode}' requires a configured embedding provider in settings.providers.openai/settings.providers.ollama or an extension provider selected by settings.search.provider`, EXIT_CODE.USAGE);
+    }
+    const vectorResolution = resolveVectorStores(params.settings);
+    if (!vectorResolution.active && !params.extensionVectorAdapter) {
+        throw new PmCliError(`Reindex mode '${params.requestedMode}' requires a configured vector store in settings.vector_store.qdrant/settings.vector_store.lancedb or an extension adapter selected by settings.vector_store.adapter`, EXIT_CODE.USAGE);
+    }
+    return {
+        activeEmbeddingProvider: providerResolution.active,
+        activeVectorStore: vectorResolution.active,
+    };
+}
+async function loadReindexCorpus(params) {
+    const typeRegistry = resolveItemTypeRegistry(params.settings, getActiveExtensionRegistrations());
+    const loadedCandidates = await loadDocumentCandidates(params.pmRoot, params.settings.item_format, typeRegistry.type_to_folder, params.settings.schema);
+    return {
+        documentCandidates: loadedCandidates.candidates,
+        warnings: [...loadedCandidates.warnings],
+        metadataDocuments: loadedCandidates.candidates.map((candidate) => ({
+            metadata: candidate.metadata,
+            body: typeof candidate.body === "string" ? candidate.body : "",
+        })),
+    };
+}
+async function appendKeywordLedgerWarnings(params) {
+    const ledger = await readVectorizationStatusLedger(params.pmRoot);
+    params.reindexWarnings.push(...ledger.warnings);
+    if (params.forceFullSemantic) {
+        params.reindexWarnings.push("search_semantic_reindex_full_ignored:mode_keyword");
+    }
+    if (!ledger.embedding) {
+        return;
+    }
+    const currentEmbeddingIdentity = (() => {
+        try {
+            return resolveReindexEmbeddingIdentity(params.settings, resolveEmbeddingProviders(params.settings).active, params.extensionEmbedding);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (currentEmbeddingIdentity && hasVectorizationEmbeddingIdentityChanged(ledger.embedding, currentEmbeddingIdentity)) {
+        params.reindexWarnings.push("search_semantic_reindex_requires_rebuild:embedding_identity_changed");
+        params.reindexWarnings.push(EMBEDDING_MIGRATION_REINDEX_HINT);
+    }
+}
+async function planSemanticReindex(params) {
+    const ledger = await readVectorizationStatusLedger(params.pmRoot);
+    params.semanticWarnings.push(...ledger.warnings);
+    const embeddingIdentity = resolveReindexEmbeddingIdentity(params.settings, params.activeEmbeddingProvider, params.extensionEmbedding);
+    const currentIds = new Set(params.metadataDocuments.map((document) => document.metadata.id));
+    const orphanIds = collectLedgerOrphanIds(ledger.entries, currentIds);
+    const resetRequired = hasVectorizationEmbeddingIdentityChanged(ledger.embedding, embeddingIdentity);
+    if (params.forceFullSemantic && !resetRequired) {
+        params.semanticWarnings.push("search_semantic_reindex_full_rebuild_forced");
+    }
+    const staleSourceDocuments = params.forceFullSemantic || resetRequired
+        ? params.metadataDocuments
+        : params.metadataDocuments.filter((document) => ledger.entries[document.metadata.id] !== document.metadata.updated_at);
+    const staleIds = new Set(staleSourceDocuments.map((document) => document.metadata.id));
+    const staleDocuments = staleIds.size > 0
+        ? await hydrateDocuments(params.pmRoot, params.documentCandidates, params.settings.schema, params.reindexWarnings, staleIds)
+        : [];
+    return {
+        ledgerEntries: ledger.entries,
+        ledgerEmbedding: ledger.embedding,
+        orphanIds,
+        resetRequired,
+        staleDocuments,
+        freshDocuments: params.metadataDocuments.length - staleDocuments.length,
+    };
+}
+async function rerunSemanticEmbeddingAfterDimensionChange(params) {
+    const staleIds = new Set(params.metadataDocuments.map((document) => document.metadata.id));
+    const staleDocuments = await hydrateDocuments(params.pmRoot, params.documentCandidates, params.settings.schema, params.reindexWarnings, staleIds);
+    params.semanticSummary.stale_items = staleDocuments.length;
+    params.semanticSummary.unchanged_items = 0;
+    emitReindexProgress(params.progressEnabled, `embedding_dimension_changed reset_items=${staleDocuments.length}`);
+    const embeddingResult = await executeReindexEmbedding(params.settings, params.requestedMode, params.activeEmbeddingProvider, params.extensionEmbedding, staleDocuments, params.semanticWarnings, params.semanticSummary, params.progressEnabled);
+    return {
+        ...embeddingResult,
+        staleDocuments,
+        vectorDimension: inferConsistentVectorDimension(embeddingResult.vectors, "Reindex embeddings"),
+    };
+}
+async function resolveSemanticEmbeddingForUpsert(params) {
+    let embeddingResult = await executeReindexEmbedding(params.settings, params.requestedMode, params.activeEmbeddingProvider, params.extensionEmbedding, params.staleDocuments, params.semanticWarnings, params.semanticSummary, params.progressEnabled);
+    let vectors = embeddingResult.vectors;
+    let actualEmbeddingIdentity = embeddingResult.embeddingIdentity;
+    let vectorDimension = inferConsistentVectorDimension(vectors, "Reindex embeddings");
+    const dimensionChanged = !params.resetRequired &&
+        (hasVectorizationEmbeddingIdentityChanged(params.ledgerEmbedding, actualEmbeddingIdentity) ||
+            hasVectorizationVectorDimensionChanged(params.ledgerEmbedding, vectorDimension));
+    if (!dimensionChanged) {
+        return {
+            vectors,
+            embeddingIdentity: actualEmbeddingIdentity,
+            staleDocuments: params.staleDocuments,
+            vectorDimension,
+            resetRequired: params.resetRequired,
+        };
+    }
+    const rerun = await rerunSemanticEmbeddingAfterDimensionChange(params);
+    vectors = rerun.vectors;
+    actualEmbeddingIdentity = rerun.embeddingIdentity;
+    vectorDimension = rerun.vectorDimension;
+    return {
+        vectors,
+        embeddingIdentity: actualEmbeddingIdentity,
+        staleDocuments: rerun.staleDocuments,
+        vectorDimension,
+        resetRequired: true,
+    };
+}
+async function upsertReindexVectors(params) {
+    if (params.extensionVectorAdapter) {
+        try {
+            const adapterName = params.extensionVectorAdapter.adapterName;
+            emitReindexProgress(params.progressEnabled, `vector_upsert_start adapter=${adapterName} points=${params.points.length}`);
+            if (typeof params.extensionVectorAdapter.upsert !== "function") {
+                throw new PmCliError(`Extension vector adapter "${adapterName}" does not support upserting vectors.`, EXIT_CODE.USAGE);
+            }
+            await Promise.resolve(params.extensionVectorAdapter.upsert({ points: params.points, settings: params.settings }));
+            params.semanticSummary.vector_upserted = params.points.length;
+            emitReindexProgress(params.progressEnabled, `vector_upsert_complete adapter=${adapterName}`);
+            return;
+        }
+        catch (error) {
+            if (error instanceof PmCliError) {
+                throw error;
+            }
+            if (!params.activeVectorStore) {
+                throw new PmCliError(`Extension vector adapter "${params.extensionVectorAdapter.adapterName}" failed to upsert vectors: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
+            }
+            params.semanticWarnings.push(`Extension vector adapter "${params.extensionVectorAdapter.adapterName}" failed; falling back to built-in vector store (${error instanceof Error ? error.message : String(error)})`);
+            emitReindexProgress(params.progressEnabled, "vector_upsert_fallback built_in_store");
+        }
+    }
+    if (params.activeVectorStore) {
+        emitReindexProgress(params.progressEnabled, `vector_upsert_start adapter=${params.activeVectorStore.name} points=${params.points.length}`);
+        await executeVectorUpsert(params.activeVectorStore, params.points);
+        params.semanticSummary.vector_upserted = params.points.length;
+        emitReindexProgress(params.progressEnabled, `vector_upsert_complete adapter=${params.activeVectorStore.name}`);
+        return;
+    }
+    /* c8 ignore start -- guarded by semantic-mode provider/vector-store preflight above */
+    throw new PmCliError(`No vector upsert executor available for reindex mode '${params.requestedMode}'`, EXIT_CODE.USAGE);
+    /* c8 ignore stop */
+}
+function buildReindexVectorPoints(staleDocuments, vectors) {
+    return staleDocuments.map((document, index) => ({
+        id: document.metadata.id,
+        vector: assertVector(vectors[index], `reindex embeddings output at index ${index}`),
+        payload: {
+            id: document.metadata.id,
+            type: document.metadata.type,
+            status: document.metadata.status,
+            priority: document.metadata.priority,
+            updated_at: document.metadata.updated_at,
+        },
+    }));
+}
+async function executeSemanticVectorRefresh(params) {
+    emitReindexProgress(params.progressEnabled, `embedding_start items=${params.plan.staleDocuments.length} unchanged_items=${params.plan.freshDocuments}`);
+    const embedding = await resolveSemanticEmbeddingForUpsert({
+        pmRoot: params.pmRoot,
+        settings: params.settings,
+        requestedMode: params.requestedMode,
+        activeEmbeddingProvider: params.activeEmbeddingProvider,
+        extensionEmbedding: params.extensionEmbedding,
+        documentCandidates: params.documentCandidates,
+        metadataDocuments: params.metadataDocuments,
+        staleDocuments: params.plan.staleDocuments,
+        ledgerEmbedding: params.plan.ledgerEmbedding,
+        resetRequired: params.plan.resetRequired,
+        semanticWarnings: params.semanticWarnings,
+        reindexWarnings: params.reindexWarnings,
+        semanticSummary: params.semanticSummary,
+        progressEnabled: params.progressEnabled,
+    });
+    if (embedding.resetRequired) {
+        emitReindexProgress(params.progressEnabled, "vector_reset_start");
+        await resetVectorStoreForReindex(params.activeVectorStore, params.extensionVectorAdapter, params.plan.ledgerEntries, params.settings, params.semanticWarnings, params.plan.ledgerEmbedding ? embedding.vectorDimension : undefined);
+        emitReindexProgress(params.progressEnabled, "vector_reset_complete");
+    }
+    else {
+        await pruneReindexOrphanVectors(params.activeVectorStore, params.extensionVectorAdapter, params.plan.orphanIds, params.settings, params.semanticWarnings);
+    }
+    const points = buildReindexVectorPoints(embedding.staleDocuments, embedding.vectors);
+    params.semanticSummary.embedded_items = embedding.vectors.length;
+    await upsertReindexVectors({
+        requestedMode: params.requestedMode,
+        activeVectorStore: params.activeVectorStore,
+        extensionVectorAdapter: params.extensionVectorAdapter,
+        settings: params.settings,
+        points,
+        semanticWarnings: params.semanticWarnings,
+        semanticSummary: params.semanticSummary,
+        progressEnabled: params.progressEnabled,
+    });
+    return {
+        staleDocuments: embedding.staleDocuments,
+        embeddingMetadata: buildVectorizationEmbeddingMetadata(embedding.embeddingIdentity, embedding.vectorDimension),
+    };
+}
+async function runSemanticReindex(params) {
+    const plan = await planSemanticReindex(params);
+    params.semanticSummary.stale_items = plan.staleDocuments.length;
+    params.semanticSummary.unchanged_items = plan.freshDocuments;
+    const vectorizationLedgerEntries = Object.fromEntries(params.metadataDocuments.map((document) => [document.metadata.id, document.metadata.updated_at]));
+    emitReindexProgress(params.progressEnabled, `semantic_stale_items stale=${plan.staleDocuments.length} total=${params.metadataDocuments.length} unchanged=${plan.freshDocuments} full=${params.forceFullSemantic || plan.resetRequired}`);
+    if (plan.staleDocuments.length === 0) {
+        emitReindexProgress(params.progressEnabled, `embedding_skipped unchanged_items=${plan.freshDocuments}`);
+        params.semanticWarnings.push(`search_semantic_reindex_skipped_unchanged:count=${plan.freshDocuments}`);
+        await pruneReindexOrphanVectors(params.activeVectorStore, params.extensionVectorAdapter, plan.orphanIds, params.settings, params.semanticWarnings);
+        return {
+            documentsForKeywordArtifacts: params.documentsForKeywordArtifacts,
+            vectorizationLedgerEntries,
+            vectorizationEmbeddingMetadata: plan.ledgerEmbedding,
+        };
+    }
+    const refresh = await executeSemanticVectorRefresh({ ...params, plan });
+    if (plan.freshDocuments > 0) {
+        params.semanticWarnings.push(`search_semantic_reindex_skipped_unchanged:count=${plan.freshDocuments}`);
+    }
+    const staleDocumentsById = new Map(refresh.staleDocuments.map((document) => [document.metadata.id, document]));
+    return {
+        documentsForKeywordArtifacts: params.metadataDocuments.map((document) => staleDocumentsById.get(document.metadata.id) ?? document),
+        vectorizationLedgerEntries,
+        vectorizationEmbeddingMetadata: refresh.embeddingMetadata,
+    };
+}
+async function writeReindexArtifacts(params) {
+    const manifestPath = path.join(params.pmRoot, MANIFEST_PATH);
+    const embeddingsPath = path.join(params.pmRoot, EMBEDDINGS_PATH);
+    const keywordCorpusFields = resolveSearchCorpusFields(params.settings);
+    const embeddingsLines = params.documentsForKeywordArtifacts
+        .map((document) => JSON.stringify(buildKeywordRecord(document, params.mode, keywordCorpusFields)))
+        .join("\n");
+    emitReindexProgress(params.progressEnabled, "writing keyword artifacts");
+    await writeFileAtomic(manifestPath, `${JSON.stringify(params.manifest, null, 2)}\n`);
+    await writeFileAtomic(embeddingsPath, `${embeddingsLines}\n`);
+    const vectorizationWarnings = [];
+    if (params.mode !== "keyword") {
+        try {
+            emitReindexProgress(params.progressEnabled, "writing vectorization status ledger");
+            await writeVectorizationStatusLedger(params.pmRoot, params.vectorizationLedgerEntries, params.vectorizationEmbeddingMetadata);
+        }
+        catch (error) {
+            vectorizationWarnings.push(`search_vectorization_status_ledger_write_failed:${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return vectorizationWarnings;
+}
 /**
  * Implements run reindex for the public runtime surface of this module.
  */
@@ -369,216 +659,66 @@ export async function runReindex(options, global) {
         throw error;
     }
     try {
-        const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
         const extensionEmbedding = resolveExtensionSearchEmbedding(settings);
         const extensionVectorAdapter = resolveExtensionVectorAdapter(settings);
-        let activeEmbeddingProvider = null;
-        let activeVectorStore = null;
-        if (requestedMode !== "keyword") {
-            const providerResolution = resolveEmbeddingProviders(settings);
-            if (!providerResolution.active && !extensionEmbedding) {
-                throw new PmCliError(`Reindex mode '${requestedMode}' requires a configured embedding provider in settings.providers.openai/settings.providers.ollama or an extension provider selected by settings.search.provider`, EXIT_CODE.USAGE);
-            }
-            const vectorResolution = resolveVectorStores(settings);
-            if (!vectorResolution.active && !extensionVectorAdapter) {
-                throw new PmCliError(`Reindex mode '${requestedMode}' requires a configured vector store in settings.vector_store.qdrant/settings.vector_store.lancedb or an extension adapter selected by settings.vector_store.adapter`, EXIT_CODE.USAGE);
-            }
-            activeEmbeddingProvider = providerResolution.active;
-            activeVectorStore = vectorResolution.active;
-        }
+        const semanticRuntime = assertSemanticRuntimeAvailable({
+            requestedMode,
+            settings,
+            extensionEmbedding,
+            extensionVectorAdapter,
+        });
         const mode = requestedMode;
         emitReindexProgress(progressEnabled, "loading item corpus");
-        const loadedCandidates = await loadDocumentCandidates(pmRoot, settings.item_format, typeRegistry.type_to_folder, settings.schema);
-        const reindexWarnings = [...loadedCandidates.warnings];
-        const documentCandidates = loadedCandidates.candidates;
-        const metadataDocuments = documentCandidates.map((candidate) => ({
-            metadata: candidate.metadata,
-            body: typeof candidate.body === "string" ? candidate.body : "",
-        }));
+        const corpus = await loadReindexCorpus({ pmRoot, settings });
+        const reindexWarnings = corpus.warnings;
+        const { documentCandidates, metadataDocuments } = corpus;
         emitReindexProgress(progressEnabled, `loaded_items=${metadataDocuments.length}`);
         const generatedAt = nowIso();
-        const manifest = {
-            version: 1,
-            mode,
-            generated_at: generatedAt,
-            total_items: metadataDocuments.length,
-            items: metadataDocuments.map((document) => ({
-                id: document.metadata.id,
-                type: document.metadata.type,
-                status: document.metadata.status,
-                priority: document.metadata.priority,
-                updated_at: document.metadata.updated_at,
-            })),
-        };
+        const manifest = buildReindexManifest(mode, generatedAt, metadataDocuments);
         const manifestPath = path.join(pmRoot, MANIFEST_PATH);
         const embeddingsPath = path.join(pmRoot, EMBEDDINGS_PATH);
         let documentsForKeywordArtifacts = mode === "keyword"
             ? await hydrateDocuments(pmRoot, documentCandidates, settings.schema, reindexWarnings)
             : metadataDocuments;
         const semanticWarnings = [];
-        const vectorizationLedgerEntries = {};
+        let vectorizationLedgerEntries = {};
         let vectorizationEmbeddingMetadata = null;
-        const semanticSummary = {
-            enabled: mode !== "keyword",
-            stale_items: 0,
-            unchanged_items: 0,
-            embedded_items: 0,
-            vector_upserted: 0,
-            batches_completed: 0,
-        };
+        const semanticSummary = createReindexSemanticSummary(mode);
         if (mode === "keyword") {
-            const ledger = await readVectorizationStatusLedger(pmRoot);
-            reindexWarnings.push(...ledger.warnings);
-            if (forceFullSemantic) {
-                reindexWarnings.push("search_semantic_reindex_full_ignored:mode_keyword");
-            }
-            if (ledger.embedding) {
-                const currentEmbeddingIdentity = (() => {
-                    try {
-                        return resolveReindexEmbeddingIdentity(settings, resolveEmbeddingProviders(settings).active, extensionEmbedding);
-                    }
-                    catch {
-                        return null;
-                    }
-                })();
-                if (currentEmbeddingIdentity && hasVectorizationEmbeddingIdentityChanged(ledger.embedding, currentEmbeddingIdentity)) {
-                    reindexWarnings.push("search_semantic_reindex_requires_rebuild:embedding_identity_changed");
-                    reindexWarnings.push(EMBEDDING_MIGRATION_REINDEX_HINT);
-                }
-            }
+            await appendKeywordLedgerWarnings({ pmRoot, settings, forceFullSemantic, extensionEmbedding, reindexWarnings });
         }
-        if (mode !== "keyword" && metadataDocuments.length > 0) {
-            const ledger = await readVectorizationStatusLedger(pmRoot);
-            semanticWarnings.push(...ledger.warnings);
-            const embeddingIdentity = resolveReindexEmbeddingIdentity(settings, activeEmbeddingProvider, extensionEmbedding);
-            const currentIds = new Set(metadataDocuments.map((document) => document.metadata.id));
-            const orphanIds = collectLedgerOrphanIds(ledger.entries, currentIds);
-            let resetRequired = hasVectorizationEmbeddingIdentityChanged(ledger.embedding, embeddingIdentity);
-            if (forceFullSemantic && !resetRequired) {
-                semanticWarnings.push("search_semantic_reindex_full_rebuild_forced");
-            }
-            const staleSourceDocuments = forceFullSemantic || resetRequired
-                ? metadataDocuments
-                : metadataDocuments.filter((document) => ledger.entries[document.metadata.id] !== document.metadata.updated_at);
-            let staleIds = new Set(staleSourceDocuments.map((document) => document.metadata.id));
-            let staleDocuments = staleIds.size > 0
-                ? await hydrateDocuments(pmRoot, documentCandidates, settings.schema, reindexWarnings, staleIds)
-                : [];
-            let freshDocuments = metadataDocuments.length - staleDocuments.length;
-            semanticSummary.stale_items = staleDocuments.length;
-            semanticSummary.unchanged_items = freshDocuments;
-            for (const document of metadataDocuments) {
-                vectorizationLedgerEntries[document.metadata.id] = document.metadata.updated_at;
-            }
-            emitReindexProgress(progressEnabled, `semantic_stale_items stale=${staleDocuments.length} total=${metadataDocuments.length} unchanged=${freshDocuments} full=${forceFullSemantic || resetRequired}`);
-            if (staleDocuments.length === 0) {
-                emitReindexProgress(progressEnabled, `embedding_skipped unchanged_items=${freshDocuments}`);
-                semanticWarnings.push(`search_semantic_reindex_skipped_unchanged:count=${freshDocuments}`);
-            }
-            else {
-                emitReindexProgress(progressEnabled, `embedding_start items=${staleDocuments.length} unchanged_items=${freshDocuments}`);
-                let embeddingResult = await executeReindexEmbedding(settings, requestedMode, activeEmbeddingProvider, extensionEmbedding, staleDocuments, semanticWarnings, semanticSummary, progressEnabled);
-                let vectors = embeddingResult.vectors;
-                let actualEmbeddingIdentity = embeddingResult.embeddingIdentity;
-                let vectorDimension = inferConsistentVectorDimension(vectors, "Reindex embeddings");
-                if (!resetRequired &&
-                    (hasVectorizationEmbeddingIdentityChanged(ledger.embedding, actualEmbeddingIdentity) ||
-                        hasVectorizationVectorDimensionChanged(ledger.embedding, vectorDimension))) {
-                    resetRequired = true;
-                    staleIds = new Set(metadataDocuments.map((document) => document.metadata.id));
-                    staleDocuments = await hydrateDocuments(pmRoot, documentCandidates, settings.schema, reindexWarnings, staleIds);
-                    freshDocuments = 0;
-                    semanticSummary.stale_items = staleDocuments.length;
-                    semanticSummary.unchanged_items = 0;
-                    emitReindexProgress(progressEnabled, `embedding_dimension_changed reset_items=${staleDocuments.length}`);
-                    embeddingResult = await executeReindexEmbedding(settings, requestedMode, activeEmbeddingProvider, extensionEmbedding, staleDocuments, semanticWarnings, semanticSummary, progressEnabled);
-                    vectors = embeddingResult.vectors;
-                    actualEmbeddingIdentity = embeddingResult.embeddingIdentity;
-                    vectorDimension = inferConsistentVectorDimension(vectors, "Reindex embeddings");
-                }
-                if (resetRequired) {
-                    emitReindexProgress(progressEnabled, "vector_reset_start");
-                    await resetVectorStoreForReindex(activeVectorStore, extensionVectorAdapter, ledger.entries, settings, semanticWarnings, ledger.embedding ? vectorDimension : undefined);
-                    emitReindexProgress(progressEnabled, "vector_reset_complete");
-                }
-                else {
-                    await pruneReindexOrphanVectors(activeVectorStore, extensionVectorAdapter, orphanIds, settings, semanticWarnings);
-                }
-                vectorizationEmbeddingMetadata = buildVectorizationEmbeddingMetadata(actualEmbeddingIdentity, vectorDimension);
-                const points = staleDocuments.map((document, index) => ({
-                    id: document.metadata.id,
-                    vector: assertVector(vectors[index], `reindex embeddings output at index ${index}`),
-                    payload: {
-                        id: document.metadata.id,
-                        type: document.metadata.type,
-                        status: document.metadata.status,
-                        priority: document.metadata.priority,
-                        updated_at: document.metadata.updated_at,
-                    },
-                }));
-                semanticSummary.embedded_items = vectors.length;
-                /* c8 ignore start -- semantic preflight guarantees a vector upsert executor path */
-                if (extensionVectorAdapter) {
-                    try {
-                        emitReindexProgress(progressEnabled, `vector_upsert_start adapter=${extensionVectorAdapter.name} points=${points.length}`);
-                        await Promise.resolve(extensionVectorAdapter.upsert({
-                            points,
-                            settings,
-                        }));
-                        semanticSummary.vector_upserted = points.length;
-                        emitReindexProgress(progressEnabled, `vector_upsert_complete adapter=${extensionVectorAdapter.name}`);
-                    }
-                    catch (error) {
-                        if (!activeVectorStore) {
-                            throw new PmCliError(`Extension vector adapter "${extensionVectorAdapter.name}" failed to upsert vectors: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
-                        }
-                        semanticWarnings.push(`Extension vector adapter "${extensionVectorAdapter.name}" failed; falling back to built-in vector store (${error instanceof Error ? error.message : String(error)})`);
-                        emitReindexProgress(progressEnabled, "vector_upsert_fallback built_in_store");
-                        await executeVectorUpsert(activeVectorStore, points);
-                        semanticSummary.vector_upserted = points.length;
-                        emitReindexProgress(progressEnabled, `vector_upsert_complete adapter=${activeVectorStore.name}`);
-                    }
-                }
-                else if (activeVectorStore) {
-                    emitReindexProgress(progressEnabled, `vector_upsert_start adapter=${activeVectorStore.name} points=${points.length}`);
-                    await executeVectorUpsert(activeVectorStore, points);
-                    semanticSummary.vector_upserted = points.length;
-                    emitReindexProgress(progressEnabled, `vector_upsert_complete adapter=${activeVectorStore.name}`);
-                }
-                else {
-                    /* c8 ignore start -- guarded by semantic-mode provider/vector-store preflight above */
-                    throw new PmCliError(`No vector upsert executor available for reindex mode '${requestedMode}'`, EXIT_CODE.USAGE);
-                    /* c8 ignore stop */
-                }
-                /* c8 ignore stop */
-                if (freshDocuments > 0) {
-                    semanticWarnings.push(`search_semantic_reindex_skipped_unchanged:count=${freshDocuments}`);
-                }
-                const staleDocumentsById = new Map(staleDocuments.map((document) => [document.metadata.id, document]));
-                documentsForKeywordArtifacts = metadataDocuments.map((document) => staleDocumentsById.get(document.metadata.id) ?? document);
-            }
-            if (staleDocuments.length === 0) {
-                await pruneReindexOrphanVectors(activeVectorStore, extensionVectorAdapter, orphanIds, settings, semanticWarnings);
-                vectorizationEmbeddingMetadata = ledger.embedding;
-            }
-        }
-        const keywordCorpusFields = resolveSearchCorpusFields(settings);
-        const embeddingsLines = documentsForKeywordArtifacts
-            .map((document) => JSON.stringify(buildKeywordRecord(document, mode, keywordCorpusFields)))
-            .join("\n");
-        emitReindexProgress(progressEnabled, "writing keyword artifacts");
-        await writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-        await writeFileAtomic(embeddingsPath, `${embeddingsLines}\n`);
-        const vectorizationWarnings = [];
         if (mode !== "keyword") {
-            try {
-                emitReindexProgress(progressEnabled, "writing vectorization status ledger");
-                await writeVectorizationStatusLedger(pmRoot, vectorizationLedgerEntries, vectorizationEmbeddingMetadata);
-            }
-            catch (error) {
-                vectorizationWarnings.push(`search_vectorization_status_ledger_write_failed:${error instanceof Error ? error.message : String(error)}`);
-            }
+            const semantic = await runSemanticReindex({
+                pmRoot,
+                settings,
+                requestedMode,
+                activeEmbeddingProvider: semanticRuntime.activeEmbeddingProvider,
+                activeVectorStore: semanticRuntime.activeVectorStore,
+                extensionEmbedding,
+                extensionVectorAdapter,
+                documentCandidates,
+                metadataDocuments,
+                documentsForKeywordArtifacts,
+                forceFullSemantic,
+                reindexWarnings,
+                semanticWarnings,
+                semanticSummary,
+                progressEnabled,
+            });
+            documentsForKeywordArtifacts = semantic.documentsForKeywordArtifacts;
+            vectorizationLedgerEntries = semantic.vectorizationLedgerEntries;
+            vectorizationEmbeddingMetadata = semantic.vectorizationEmbeddingMetadata;
         }
+        const vectorizationWarnings = await writeReindexArtifacts({
+            pmRoot,
+            mode,
+            manifest,
+            documentsForKeywordArtifacts,
+            settings,
+            vectorizationLedgerEntries,
+            vectorizationEmbeddingMetadata,
+            progressEnabled,
+        });
         const hookWarnings = [
             ...(await runActiveOnWriteHooks({
                 path: manifestPath,
@@ -614,4 +754,4 @@ export async function runReindex(options, global) {
     }
 }
 //# sourceMappingURL=reindex.js.map
-//# debugId=aa59b937-1085-5a08-9ac6-84c64d6b6a8f
+//# debugId=8dd50c77-d026-565f-8f07-e63602a44f09