@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/core/search/cache.js

@@ -1,535 +1,3 @@
-/**
- * @module core/search/cache
- *
- * Powers search, embeddings, and semantic retrieval behavior for Cache.
- */
-
-!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]="7939a590-3662-5c66-99aa-3835a0dbaecc")}catch(e){}}();
-import path from "node:path";
-import { getActiveExtensionRegistrations } from "../extensions/index.js";
-import { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../fs/fs-utils.js";
-import { resolveItemTypeRegistry } from "../item/type-registry.js";
-import { toErrorMessage } from "../shared/primitives.js";
-import { locateItem, readLocatedItem } from "../store/item-store.js";
-import { getSettingsPath } from "../store/paths.js";
-import { readSettingsWithMetadata, } from "../store/settings.js";
-import { executeEmbeddingBatchesWithRetry } from "./embedding-batches.js";
-import { buildSemanticCorpusInput, resolveSearchCorpusFields, resolveSemanticCorpusCharacterLimit, } from "./corpus.js";
-import { resolveEmbeddingProviders } from "./providers.js";
-import { resolveSettingsWithSemanticRuntimeDefaults } from "./semantic-defaults.js";
-import { scheduleBackgroundSemanticRefresh } from "./background-refresh.js";
-import { executeVectorDelete, executeVectorReset, executeVectorUpsert, resolveVectorStores, } from "./vector-stores.js";
-import { buildVectorizationEmbeddingIdentity, buildVectorizationEmbeddingMetadata, hasVectorizationEmbeddingIdentityChanged, hasVectorizationVectorDimensionChanged, inferConsistentVectorDimension, normalizeVectorizationEmbeddingMetadata, } from "./vectorization-metadata.js";
-import { nowIso } from "../shared/time.js";
-/** Public contract for search cache artifact paths, shared by SDK and presentation-layer consumers. */
-export const SEARCH_CACHE_ARTIFACT_PATHS = [
-    "index/manifest.json",
-    "search/embeddings.jsonl",
-];
-/** Filesystem path used for vectorization status ledger resolution. */
-export const VECTORIZATION_STATUS_LEDGER_PATH = "search/vectorization-status.json";
-function formatInvalidationWarning(relativePath, error) {
-    return `search_cache_invalidation_failed:${relativePath}:${String(error)}`;
-}
-function toUniqueSorted(values) {
-    return [
-        ...new Set([...values]
-            .map((value) => value.trim())
-            .filter((value) => value.length > 0)),
-    ].sort((left, right) => left.localeCompare(right));
-}
-function isValidUpdatedAt(value) {
-    return (typeof value === "string" &&
-        value.trim().length > 0 &&
-        Number.isFinite(Date.parse(value)));
-}
-function normalizeVectorizationLedgerEntries(entries) {
-    const normalized = new Map();
-    for (const [rawId, rawUpdatedAt] of Object.entries(entries)) {
-        const id = rawId.trim();
-        if (id.length === 0 || !isValidUpdatedAt(rawUpdatedAt)) {
-            continue;
-        }
-        normalized.set(id, rawUpdatedAt);
-    }
-    return Object.fromEntries([...normalized.entries()].sort((left, right) => left[0].localeCompare(right[0])));
-}
-/** Implements read vectorization status ledger for the public runtime surface of this module. */
-export async function readVectorizationStatusLedger(pmRoot) {
-    const ledgerPath = path.join(pmRoot, VECTORIZATION_STATUS_LEDGER_PATH);
-    const raw = await readFileIfExists(ledgerPath);
-    if (raw === null || raw.trim().length === 0) {
-        return {
-            entries: {},
-            embedding: null,
-            warnings: [],
-        };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return {
-            entries: {},
-            embedding: null,
-            warnings: ["search_vectorization_status_ledger_invalid"],
-        };
-    }
-    if (typeof parsed !== "object" ||
-        parsed === null ||
-        parsed.version !== 1 ||
-        !Array.isArray(parsed.items)) {
-        return {
-            entries: {},
-            embedding: null,
-            warnings: ["search_vectorization_status_ledger_invalid"],
-        };
-    }
-    const mapped = new Map();
-    for (const entry of parsed.items) {
-        if (typeof entry !== "object" || entry === null) {
-            return {
-                entries: {},
-                embedding: null,
-                warnings: ["search_vectorization_status_ledger_invalid"],
-            };
-        }
-        const id = entry.id;
-        const updatedAt = entry.updated_at;
-        if (typeof id !== "string" ||
-            id.trim().length === 0 ||
-            !isValidUpdatedAt(updatedAt)) {
-            return {
-                entries: {},
-                embedding: null,
-                warnings: ["search_vectorization_status_ledger_invalid"],
-            };
-        }
-        mapped.set(id.trim(), updatedAt);
-    }
-    let embedding = null;
-    try {
-        embedding = normalizeVectorizationEmbeddingMetadata(parsed.embedding);
-    }
-    catch {
-        return {
-            entries: {},
-            embedding: null,
-            warnings: ["search_vectorization_status_ledger_invalid"],
-        };
-    }
-    return {
-        entries: Object.fromEntries([...mapped.entries()].sort((left, right) => left[0].localeCompare(right[0]))),
-        embedding,
-        warnings: [],
-    };
-}
-/** Implements write vectorization status ledger for the public runtime surface of this module. */
-export async function writeVectorizationStatusLedger(pmRoot, entries, embedding) {
-    const normalizedEntries = normalizeVectorizationLedgerEntries(entries);
-    const ledgerPath = path.join(pmRoot, VECTORIZATION_STATUS_LEDGER_PATH);
-    const serialized = `${JSON.stringify({
-        version: 1,
-        generated_at: nowIso(),
-        ...(embedding ? { embedding } : {}),
-        items: Object.entries(normalizedEntries).map(([id, updated_at]) => ({
-            id,
-            updated_at,
-        })),
-    }, null, 2)}\n`;
-    await writeFileAtomic(ledgerPath, serialized);
-}
-function buildVectorPayload(item) {
-    return {
-        id: item.id,
-        type: item.type,
-        status: item.status,
-        priority: item.priority,
-        updated_at: item.updated_at,
-    };
-}
-function buildVectorizationIdentityForProvider(provider) {
-    const identity = buildVectorizationEmbeddingIdentity(provider.name, provider.model);
-    if (!identity) {
-        throw new Error("Embedding provider must include a provider name and model");
-    }
-    return identity;
-}
-function buildSkippedSemanticRefreshResult(itemIds, warning) {
-    return {
-        refreshed: [],
-        skipped: itemIds,
-        warnings: [warning],
-    };
-}
-async function resolveSemanticRefreshRuntimeContext(pmRoot, normalizedItemIds, options) {
-    if (!options.settings && !(await pathExists(getSettingsPath(pmRoot)))) {
-        return buildSkippedSemanticRefreshResult(normalizedItemIds, "search_semantic_refresh_skipped:settings_not_initialized");
-    }
-    let settings;
-    try {
-        if (options.settings) {
-            settings = options.settings;
-        }
-        else {
-            const settingsRead = await readSettingsWithMetadata(pmRoot);
-            const readFailure = settingsRead.warnings.find((warning) => warning.startsWith("settings_read_"));
-            if (readFailure) {
-                return buildSkippedSemanticRefreshResult(normalizedItemIds, `search_semantic_refresh_skipped:settings_read_failed:${readFailure}`);
-            }
-            settings = settingsRead.settings;
-        }
-    }
-    catch (error) {
-        return buildSkippedSemanticRefreshResult(normalizedItemIds, `search_semantic_refresh_skipped:settings_read_failed:${toErrorMessage(error)}`);
-    }
-    const effectiveSettings = options.apply_runtime_defaults
-        ? resolveSettingsWithSemanticRuntimeDefaults(settings).settings
-        : settings;
-    const provider = resolveEmbeddingProviders(effectiveSettings).active;
-    if (!provider) {
-        return buildSkippedSemanticRefreshResult(normalizedItemIds, "search_semantic_refresh_skipped:provider_unconfigured");
-    }
-    const vectorStore = resolveVectorStores(effectiveSettings, pmRoot).active;
-    if (!vectorStore) {
-        return buildSkippedSemanticRefreshResult(normalizedItemIds, "search_semantic_refresh_skipped:vector_store_unconfigured");
-    }
-    return {
-        settings: effectiveSettings,
-        provider,
-        vectorStore,
-    };
-}
-async function collectSemanticRefreshWorkload(pmRoot, idPrefix, preferredFormat, normalizedItemIds, typeToFolder, schema) {
-    const warnings = [];
-    const skipped = new Set();
-    const missing = new Set();
-    const documents = [];
-    for (const itemId of normalizedItemIds) {
-        const located = await locateItem(pmRoot, itemId, idPrefix, preferredFormat, typeToFolder);
-        if (!located) {
-            missing.add(itemId);
-            continue;
-        }
-        try {
-            const loaded = await readLocatedItem(located, { schema });
-            documents.push({
-                id: loaded.document.metadata.id,
-                document: loaded.document,
-            });
-        }
-        catch (error) {
-            skipped.add(located.id);
-            warnings.push(`search_semantic_refresh_item_read_failed:${located.id}:${toErrorMessage(error)}`);
-        }
-    }
-    documents.sort((left, right) => left.id.localeCompare(right.id));
-    return {
-        documents,
-        missingIds: toUniqueSorted(missing),
-        skippedIds: toUniqueSorted(skipped),
-        warnings,
-    };
-}
-async function embedLocatedSemanticVectors(settings, provider, documents) {
-    const corpusCharacterLimit = resolveSemanticCorpusCharacterLimit(provider.name, settings.search.embedding_corpus_max_characters).maxCharacters;
-    const corpusFields = resolveSearchCorpusFields(settings);
-    const corpusInputs = documents.map((entry) => buildSemanticCorpusInput(entry.document, {
-        providerName: provider.name,
-        maxCharacters: corpusCharacterLimit,
-        fields: corpusFields,
-    }));
-    const embeddingResult = await executeEmbeddingBatchesWithRetry(provider, settings, corpusInputs);
-    return {
-        vectors: embeddingResult.vectors,
-        vector_dimension: inferConsistentVectorDimension(embeddingResult.vectors, "Semantic refresh embedding"),
-        warnings: embeddingResult.warnings,
-    };
-}
-async function upsertLocatedSemanticVectors(vectorStore, documents, vectors) {
-    await executeVectorUpsert(vectorStore, documents.map((entry, index) => ({
-        id: entry.id,
-        vector: vectors[index],
-        payload: buildVectorPayload(entry.document.metadata),
-    })));
-    return {
-        refreshed: documents.map((entry) => entry.id),
-        skipped: [],
-        warnings: [],
-    };
-}
-async function resetSemanticVectorStore(vectorStore, ledgerEntries) {
-    try {
-        await executeVectorReset(vectorStore, Object.keys(ledgerEntries));
-        return { refreshed: [], skipped: [], warnings: [] };
-    }
-    catch (error) {
-        return {
-            refreshed: [],
-            skipped: [],
-            warnings: [
-                `search_semantic_refresh_reset_failed:${toErrorMessage(error)}`,
-            ],
-        };
-    }
-}
-async function pruneMissingSemanticVectors(vectorStore, missingIds) {
-    if (missingIds.length === 0) {
-        return { refreshed: [], skipped: [], warnings: [] };
-    }
-    try {
-        await executeVectorDelete(vectorStore, missingIds);
-        return {
-            refreshed: [],
-            skipped: [],
-            warnings: [],
-        };
-    }
-    catch (error) {
-        return {
-            refreshed: [],
-            skipped: missingIds,
-            warnings: [
-                `search_semantic_refresh_delete_failed:${toErrorMessage(error)}`,
-            ],
-        };
-    }
-}
-/** Implements invalidate search cache artifacts for the public runtime surface of this module. */
-export async function invalidateSearchCacheArtifacts(pmRoot) {
-    const invalidated = [];
-    const warnings = [];
-    for (const relativePath of SEARCH_CACHE_ARTIFACT_PATHS) {
-        const artifactPath = path.join(pmRoot, relativePath);
-        try {
-            if (!(await pathExists(artifactPath))) {
-                continue;
-            }
-            await removeFileIfExists(artifactPath);
-            invalidated.push(relativePath);
-        }
-        catch (error) {
-            warnings.push(formatInvalidationWarning(relativePath, error));
-        }
-    }
-    return {
-        invalidated,
-        warnings,
-    };
-}
-/** Implements refresh semantic embeddings for mutated items for the public runtime surface of this module. */
-export async function refreshSemanticEmbeddingsForMutatedItems(pmRoot, itemIds, options = {}) {
-    const normalizedItemIds = toUniqueSorted(itemIds);
-    if (normalizedItemIds.length === 0) {
-        return {
-            refreshed: [],
-            skipped: [],
-            warnings: [],
-        };
-    }
-    const runtimeContext = await resolveSemanticRefreshRuntimeContext(pmRoot, normalizedItemIds, options);
-    if (!("settings" in runtimeContext)) {
-        return runtimeContext;
-    }
-    const typeRegistry = resolveItemTypeRegistry(runtimeContext.settings, getActiveExtensionRegistrations());
-    const workload = await collectSemanticRefreshWorkload(pmRoot, runtimeContext.settings.id_prefix, runtimeContext.settings.item_format, normalizedItemIds, typeRegistry.type_to_folder, runtimeContext.settings.schema);
-    const ledgerRead = workload.documents.length > 0 || workload.missingIds.length > 0
-        ? await readVectorizationStatusLedger(pmRoot)
-        : { entries: {}, embedding: null, warnings: [] };
-    const embeddingIdentity = buildVectorizationIdentityForProvider(runtimeContext.provider);
-    const nextLedgerBaseEntries = ledgerRead.entries;
-    let refreshedResult = {
-        refreshed: [],
-        skipped: [],
-        warnings: [],
-    };
-    let nextEmbeddingMetadata = ledgerRead.embedding;
-    if (workload.documents.length > 0) {
-        if (ledgerRead.embedding &&
-            hasVectorizationEmbeddingIdentityChanged(ledgerRead.embedding, embeddingIdentity)) {
-            refreshedResult = {
-                refreshed: [],
-                skipped: workload.documents.map((entry) => entry.id),
-                warnings: [
-                    "search_semantic_refresh_requires_reindex:embedding_identity_changed",
-                ],
-            };
-        }
-        else {
-            try {
-                const embedded = await embedLocatedSemanticVectors(runtimeContext.settings, runtimeContext.provider, workload.documents);
-                if (hasVectorizationVectorDimensionChanged(ledgerRead.embedding, embedded.vector_dimension)) {
-                    refreshedResult = {
-                        refreshed: [],
-                        skipped: workload.documents.map((entry) => entry.id),
-                        warnings: [
-                            ...embedded.warnings,
-                            "search_semantic_refresh_requires_reindex:vector_dimension_changed",
-                        ],
-                    };
-                }
-                else {
-                    nextEmbeddingMetadata = buildVectorizationEmbeddingMetadata(embeddingIdentity, embedded.vector_dimension);
-                    const upserted = await upsertLocatedSemanticVectors(runtimeContext.vectorStore, workload.documents, embedded.vectors);
-                    refreshedResult = {
-                        refreshed: upserted.refreshed,
-                        skipped: upserted.skipped,
-                        warnings: [...embedded.warnings, ...upserted.warnings],
-                    };
-                }
-            }
-            catch (error) {
-                refreshedResult = {
-                    refreshed: [],
-                    skipped: workload.documents.map((entry) => entry.id),
-                    warnings: [`search_semantic_refresh_failed:${toErrorMessage(error)}`],
-                };
-            }
-        }
-    }
-    const pruneResult = await pruneMissingSemanticVectors(runtimeContext.vectorStore, workload.missingIds);
-    const refreshedIdSet = new Set(refreshedResult.refreshed);
-    const refreshedEntries = Object.fromEntries(workload.documents
-        .filter((entry) => refreshedIdSet.has(entry.id))
-        .map((entry) => [entry.id, entry.document.metadata.updated_at]));
-    const ledgerWarnings = [];
-    if (Object.keys(refreshedEntries).length > 0 ||
-        workload.missingIds.length > 0) {
-        const nextEntries = {
-            ...nextLedgerBaseEntries,
-            ...normalizeVectorizationLedgerEntries(refreshedEntries),
-        };
-        for (const missingId of workload.missingIds) {
-            delete nextEntries[missingId];
-        }
-        try {
-            await writeVectorizationStatusLedger(pmRoot, nextEntries, nextEmbeddingMetadata);
-        }
-        catch (error) {
-            ledgerWarnings.push(`search_vectorization_status_ledger_write_failed:${toErrorMessage(error)}`);
-        }
-        ledgerWarnings.push(...ledgerRead.warnings);
-    }
-    return {
-        refreshed: toUniqueSorted([
-            ...refreshedResult.refreshed,
-            ...pruneResult.refreshed,
-        ]),
-        skipped: toUniqueSorted([
-            ...workload.skippedIds,
-            ...refreshedResult.skipped,
-            ...pruneResult.skipped,
-        ]),
-        warnings: [
-            ...workload.warnings,
-            ...refreshedResult.warnings,
-            ...pruneResult.warnings,
-            ...ledgerWarnings,
-        ],
-    };
-}
-/** Returns true when a semantic embedding refresh would do real work for these settings (an embedding provider AND a vector store both resolve). Used to decide whether a mutation's refresh is worth dispatching to a background worker — when semantic search is not configured the inline path is already a fast no-op and no child is spawned. */
-export function isSemanticRefreshActive(settings, applyRuntimeDefaults) {
-    const effectiveSettings = applyRuntimeDefaults
-        ? resolveSettingsWithSemanticRuntimeDefaults(settings).settings
-        : settings;
-    return Boolean(resolveEmbeddingProviders(effectiveSettings).active &&
-        resolveVectorStores(effectiveSettings).active);
-}
-/** Implements refresh search artifacts for mutation for the public runtime surface of this module. */
-export async function refreshSearchArtifactsForMutation(pmRoot, itemIds, options = {}) {
-    const invalidation = await invalidateSearchCacheArtifacts(pmRoot);
-    const normalizedItemIds = toUniqueSorted(itemIds);
-    if (normalizedItemIds.length === 0) {
-        return {
-            invalidated: invalidation.invalidated,
-            refreshed: [],
-            skipped: [],
-            warnings: invalidation.warnings,
-        };
-    }
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        const semanticRefresh = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, normalizedItemIds);
-        return {
-            invalidated: invalidation.invalidated,
-            refreshed: semanticRefresh.refreshed,
-            skipped: semanticRefresh.skipped,
-            warnings: [...invalidation.warnings, ...semanticRefresh.warnings],
-        };
-    }
-    let settings;
-    try {
-        const settingsRead = await readSettingsWithMetadata(pmRoot);
-        const readFailure = settingsRead.warnings.find((warning) => warning.startsWith("settings_read_"));
-        if (readFailure) {
-            return {
-                invalidated: invalidation.invalidated,
-                refreshed: [],
-                skipped: normalizedItemIds,
-                warnings: [
-                    ...invalidation.warnings,
-                    `search_semantic_refresh_skipped:settings_read_failed:${readFailure}`,
-                ],
-            };
-        }
-        settings = settingsRead.settings;
-    }
-    catch (error) {
-        return {
-            invalidated: invalidation.invalidated,
-            refreshed: [],
-            skipped: normalizedItemIds,
-            warnings: [
-                ...invalidation.warnings,
-                `search_semantic_refresh_skipped:settings_read_failed:${toErrorMessage(error)}`,
-            ],
-        };
-    }
-    if (settings.search.mutation_refresh_policy === "cache_only") {
-        return {
-            invalidated: invalidation.invalidated,
-            refreshed: [],
-            skipped: normalizedItemIds,
-            warnings: invalidation.warnings,
-        };
-    }
-    const applyRuntimeDefaults = settings.search.mutation_refresh_policy === "semantic_auto";
-    // Keyword cache is already invalidated synchronously above (so keyword search
-    // stays immediately correct). When requested, dispatch the slow embedding
-    // refresh to a detached worker so the mutation returns instantly; the
-    // vector_index_stale health/search warning covers the catch-up window.
-    if (options.background &&
-        isSemanticRefreshActive(settings, applyRuntimeDefaults)) {
-        await scheduleBackgroundSemanticRefresh(pmRoot, normalizedItemIds);
-        return {
-            invalidated: invalidation.invalidated,
-            refreshed: [],
-            skipped: [],
-            warnings: [
-                ...invalidation.warnings,
-                "search_semantic_refresh_scheduled_background",
-            ],
-            scheduled: true,
-        };
-    }
-    const semanticRefresh = await refreshSemanticEmbeddingsForMutatedItems(pmRoot, normalizedItemIds, {
-        settings,
-        apply_runtime_defaults: applyRuntimeDefaults,
-    });
-    return {
-        invalidated: invalidation.invalidated,
-        refreshed: semanticRefresh.refreshed,
-        skipped: semanticRefresh.skipped,
-        warnings: [...invalidation.warnings, ...semanticRefresh.warnings],
-    };
-}
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    buildSkippedSemanticRefreshResult,
-    buildVectorizationIdentityForProvider,
-    normalizeVectorizationLedgerEntries,
-    resetSemanticVectorStore,
-};
+!(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]="b382ab50-682e-5e53-a32d-277c5ccf8bef")}catch(e2){}})();import path from"node:path";import{getActiveExtensionRegistrations}from"../extensions/index.js";import{pathExists,readFileIfExists,removeFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{resolveItemTypeRegistry}from"../item/type-registry.js";import{toErrorMessage}from"../shared/primitives.js";import{locateItem,readLocatedItem}from"../store/item-store.js";import{getSettingsPath}from"../store/paths.js";import{readSettingsWithMetadata}from"../store/settings.js";import{executeEmbeddingBatchesWithRetry}from"./embedding-batches.js";import{buildSemanticCorpusInput,resolveSearchCorpusFields,resolveSemanticCorpusCharacterLimit}from"./corpus.js";import{resolveEmbeddingProviders}from"./providers.js";import{resolveSettingsWithSemanticRuntimeDefaults}from"./semantic-defaults.js";import{scheduleBackgroundSemanticRefresh}from"./background-refresh.js";import{executeVectorDelete,executeVectorReset,executeVectorUpsert,resolveVectorStores}from"./vector-stores.js";import{buildVectorizationEmbeddingIdentity,buildVectorizationEmbeddingMetadata,hasVectorizationEmbeddingIdentityChanged,hasVectorizationVectorDimensionChanged,inferConsistentVectorDimension,normalizeVectorizationEmbeddingMetadata}from"./vectorization-metadata.js";import{nowIso}from"../shared/time.js";const SEARCH_CACHE_ARTIFACT_PATHS=["index/manifest.json","search/embeddings.jsonl"];const VECTORIZATION_STATUS_LEDGER_PATH="search/vectorization-status.json";function formatInvalidationWarning(relativePath,error){return`search_cache_invalidation_failed:${relativePath}:${String(error)}`}function toUniqueSorted(values){return[...new Set([...values].map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right))}function isValidUpdatedAt(value){return typeof value==="string"&&value.trim().length>0&&Number.isFinite(Date.parse(value))}function normalizeVectorizationLedgerEntries(entries){const normalized=new Map;for(const[rawId,rawUpdatedAt]of Object.entries(entries)){const id=rawId.trim();if(id.length===0||!isValidUpdatedAt(rawUpdatedAt)){continue}normalized.set(id,rawUpdatedAt)}return Object.fromEntries([...normalized.entries()].sort((left,right)=>left[0].localeCompare(right[0])))}async function readVectorizationStatusLedger(pmRoot){const ledgerPath=path.join(pmRoot,VECTORIZATION_STATUS_LEDGER_PATH);const raw=await readFileIfExists(ledgerPath);if(raw===null||raw.trim().length===0){return{entries:{},embedding:null,warnings:[]}}let parsed;try{parsed=JSON.parse(raw)}catch{return{entries:{},embedding:null,warnings:["search_vectorization_status_ledger_invalid"]}}if(typeof parsed!=="object"||parsed===null||parsed.version!==1||!Array.isArray(parsed.items)){return{entries:{},embedding:null,warnings:["search_vectorization_status_ledger_invalid"]}}const mapped=new Map;for(const entry of parsed.items){if(typeof entry!=="object"||entry===null){return{entries:{},embedding:null,warnings:["search_vectorization_status_ledger_invalid"]}}const id=entry.id;const updatedAt=entry.updated_at;if(typeof id!=="string"||id.trim().length===0||!isValidUpdatedAt(updatedAt)){return{entries:{},embedding:null,warnings:["search_vectorization_status_ledger_invalid"]}}mapped.set(id.trim(),updatedAt)}let embedding=null;try{embedding=normalizeVectorizationEmbeddingMetadata(parsed.embedding)}catch{return{entries:{},embedding:null,warnings:["search_vectorization_status_ledger_invalid"]}}return{entries:Object.fromEntries([...mapped.entries()].sort((left,right)=>left[0].localeCompare(right[0]))),embedding,warnings:[]}}async function writeVectorizationStatusLedger(pmRoot,entries,embedding){const normalizedEntries=normalizeVectorizationLedgerEntries(entries);const ledgerPath=path.join(pmRoot,VECTORIZATION_STATUS_LEDGER_PATH);const serialized=`${JSON.stringify({version:1,generated_at:nowIso(),...embedding?{embedding}:{},items:Object.entries(normalizedEntries).map(([id,updated_at])=>({id,updated_at}))},null,2)}
+`;await writeFileAtomic(ledgerPath,serialized)}function buildVectorPayload(item){return{id:item.id,type:item.type,status:item.status,priority:item.priority,updated_at:item.updated_at}}function buildVectorizationIdentityForProvider(provider){const identity=buildVectorizationEmbeddingIdentity(provider.name,provider.model);if(!identity){throw new Error("Embedding provider must include a provider name and model")}return identity}function buildSkippedSemanticRefreshResult(itemIds,warning){return{refreshed:[],skipped:itemIds,warnings:[warning]}}async function resolveSemanticRefreshRuntimeContext(pmRoot,normalizedItemIds,options){if(!options.settings&&!await pathExists(getSettingsPath(pmRoot))){return buildSkippedSemanticRefreshResult(normalizedItemIds,"search_semantic_refresh_skipped:settings_not_initialized")}let settings;try{if(options.settings){settings=options.settings}else{const settingsRead=await readSettingsWithMetadata(pmRoot);const readFailure=settingsRead.warnings.find(warning=>warning.startsWith("settings_read_"));if(readFailure){return buildSkippedSemanticRefreshResult(normalizedItemIds,`search_semantic_refresh_skipped:settings_read_failed:${readFailure}`)}settings=settingsRead.settings}}catch(error){return buildSkippedSemanticRefreshResult(normalizedItemIds,`search_semantic_refresh_skipped:settings_read_failed:${toErrorMessage(error)}`)}const effectiveSettings=options.apply_runtime_defaults?resolveSettingsWithSemanticRuntimeDefaults(settings).settings:settings;const provider=resolveEmbeddingProviders(effectiveSettings).active;if(!provider){return buildSkippedSemanticRefreshResult(normalizedItemIds,"search_semantic_refresh_skipped:provider_unconfigured")}const vectorStore=resolveVectorStores(effectiveSettings,pmRoot).active;if(!vectorStore){return buildSkippedSemanticRefreshResult(normalizedItemIds,"search_semantic_refresh_skipped:vector_store_unconfigured")}return{settings:effectiveSettings,provider,vectorStore}}async function collectSemanticRefreshWorkload(pmRoot,idPrefix,preferredFormat,normalizedItemIds,typeToFolder,schema){const warnings=[];const skipped=new Set;const missing=new Set;const documents=[];for(const itemId of normalizedItemIds){const located=await locateItem(pmRoot,itemId,idPrefix,preferredFormat,typeToFolder);if(!located){missing.add(itemId);continue}try{const loaded=await readLocatedItem(located,{schema});documents.push({id:loaded.document.metadata.id,document:loaded.document})}catch(error){skipped.add(located.id);warnings.push(`search_semantic_refresh_item_read_failed:${located.id}:${toErrorMessage(error)}`)}}documents.sort((left,right)=>left.id.localeCompare(right.id));return{documents,missingIds:toUniqueSorted(missing),skippedIds:toUniqueSorted(skipped),warnings}}async function embedLocatedSemanticVectors(settings,provider,documents){const corpusCharacterLimit=resolveSemanticCorpusCharacterLimit(provider.name,settings.search.embedding_corpus_max_characters).maxCharacters;const corpusFields=resolveSearchCorpusFields(settings);const corpusInputs=documents.map(entry=>buildSemanticCorpusInput(entry.document,{providerName:provider.name,maxCharacters:corpusCharacterLimit,fields:corpusFields}));const embeddingResult=await executeEmbeddingBatchesWithRetry(provider,settings,corpusInputs);return{vectors:embeddingResult.vectors,vector_dimension:inferConsistentVectorDimension(embeddingResult.vectors,"Semantic refresh embedding"),warnings:embeddingResult.warnings}}async function upsertLocatedSemanticVectors(vectorStore,documents,vectors){await executeVectorUpsert(vectorStore,documents.map((entry,index)=>({id:entry.id,vector:vectors[index],payload:buildVectorPayload(entry.document.metadata)})));return{refreshed:documents.map(entry=>entry.id),skipped:[],warnings:[]}}async function resetSemanticVectorStore(vectorStore,ledgerEntries){try{await executeVectorReset(vectorStore,Object.keys(ledgerEntries));return{refreshed:[],skipped:[],warnings:[]}}catch(error){return{refreshed:[],skipped:[],warnings:[`search_semantic_refresh_reset_failed:${toErrorMessage(error)}`]}}}async function pruneMissingSemanticVectors(vectorStore,missingIds){if(missingIds.length===0){return{refreshed:[],skipped:[],warnings:[]}}try{await executeVectorDelete(vectorStore,missingIds);return{refreshed:[],skipped:[],warnings:[]}}catch(error){return{refreshed:[],skipped:missingIds,warnings:[`search_semantic_refresh_delete_failed:${toErrorMessage(error)}`]}}}async function invalidateSearchCacheArtifacts(pmRoot){const invalidated=[];const warnings=[];for(const relativePath of SEARCH_CACHE_ARTIFACT_PATHS){const artifactPath=path.join(pmRoot,relativePath);try{if(!await pathExists(artifactPath)){continue}await removeFileIfExists(artifactPath);invalidated.push(relativePath)}catch(error){warnings.push(formatInvalidationWarning(relativePath,error))}}return{invalidated,warnings}}async function refreshSemanticEmbeddingsForMutatedItems(pmRoot,itemIds,options={}){const normalizedItemIds=toUniqueSorted(itemIds);if(normalizedItemIds.length===0){return{refreshed:[],skipped:[],warnings:[]}}const runtimeContext=await resolveSemanticRefreshRuntimeContext(pmRoot,normalizedItemIds,options);if(!("settings"in runtimeContext)){return runtimeContext}const typeRegistry=resolveItemTypeRegistry(runtimeContext.settings,getActiveExtensionRegistrations());const workload=await collectSemanticRefreshWorkload(pmRoot,runtimeContext.settings.id_prefix,runtimeContext.settings.item_format,normalizedItemIds,typeRegistry.type_to_folder,runtimeContext.settings.schema);const ledgerRead=workload.documents.length>0||workload.missingIds.length>0?await readVectorizationStatusLedger(pmRoot):{entries:{},embedding:null,warnings:[]};const embeddingIdentity=buildVectorizationIdentityForProvider(runtimeContext.provider);const nextLedgerBaseEntries=ledgerRead.entries;let refreshedResult={refreshed:[],skipped:[],warnings:[]};let nextEmbeddingMetadata=ledgerRead.embedding;if(workload.documents.length>0){if(ledgerRead.embedding&&hasVectorizationEmbeddingIdentityChanged(ledgerRead.embedding,embeddingIdentity)){refreshedResult={refreshed:[],skipped:workload.documents.map(entry=>entry.id),warnings:["search_semantic_refresh_requires_reindex:embedding_identity_changed"]}}else{try{const embedded=await embedLocatedSemanticVectors(runtimeContext.settings,runtimeContext.provider,workload.documents);if(hasVectorizationVectorDimensionChanged(ledgerRead.embedding,embedded.vector_dimension)){refreshedResult={refreshed:[],skipped:workload.documents.map(entry=>entry.id),warnings:[...embedded.warnings,"search_semantic_refresh_requires_reindex:vector_dimension_changed"]}}else{nextEmbeddingMetadata=buildVectorizationEmbeddingMetadata(embeddingIdentity,embedded.vector_dimension);const upserted=await upsertLocatedSemanticVectors(runtimeContext.vectorStore,workload.documents,embedded.vectors);refreshedResult={refreshed:upserted.refreshed,skipped:upserted.skipped,warnings:[...embedded.warnings,...upserted.warnings]}}}catch(error){refreshedResult={refreshed:[],skipped:workload.documents.map(entry=>entry.id),warnings:[`search_semantic_refresh_failed:${toErrorMessage(error)}`]}}}}const pruneResult=await pruneMissingSemanticVectors(runtimeContext.vectorStore,workload.missingIds);const refreshedIdSet=new Set(refreshedResult.refreshed);const refreshedEntries=Object.fromEntries(workload.documents.filter(entry=>refreshedIdSet.has(entry.id)).map(entry=>[entry.id,entry.document.metadata.updated_at]));const ledgerWarnings=[];if(Object.keys(refreshedEntries).length>0||workload.missingIds.length>0){const nextEntries={...nextLedgerBaseEntries,...normalizeVectorizationLedgerEntries(refreshedEntries)};for(const missingId of workload.missingIds){delete nextEntries[missingId]}try{await writeVectorizationStatusLedger(pmRoot,nextEntries,nextEmbeddingMetadata)}catch(error){ledgerWarnings.push(`search_vectorization_status_ledger_write_failed:${toErrorMessage(error)}`)}ledgerWarnings.push(...ledgerRead.warnings)}return{refreshed:toUniqueSorted([...refreshedResult.refreshed,...pruneResult.refreshed]),skipped:toUniqueSorted([...workload.skippedIds,...refreshedResult.skipped,...pruneResult.skipped]),warnings:[...workload.warnings,...refreshedResult.warnings,...pruneResult.warnings,...ledgerWarnings]}}function isSemanticRefreshActive(settings,applyRuntimeDefaults){const effectiveSettings=applyRuntimeDefaults?resolveSettingsWithSemanticRuntimeDefaults(settings).settings:settings;return Boolean(resolveEmbeddingProviders(effectiveSettings).active&&resolveVectorStores(effectiveSettings).active)}async function refreshSearchArtifactsForMutation(pmRoot,itemIds,options={}){const invalidation=await invalidateSearchCacheArtifacts(pmRoot);const normalizedItemIds=toUniqueSorted(itemIds);if(normalizedItemIds.length===0){return{invalidated:invalidation.invalidated,refreshed:[],skipped:[],warnings:invalidation.warnings}}if(!await pathExists(getSettingsPath(pmRoot))){const semanticRefresh2=await refreshSemanticEmbeddingsForMutatedItems(pmRoot,normalizedItemIds);return{invalidated:invalidation.invalidated,refreshed:semanticRefresh2.refreshed,skipped:semanticRefresh2.skipped,warnings:[...invalidation.warnings,...semanticRefresh2.warnings]}}let settings;try{const settingsRead=await readSettingsWithMetadata(pmRoot);const readFailure=settingsRead.warnings.find(warning=>warning.startsWith("settings_read_"));if(readFailure){return{invalidated:invalidation.invalidated,refreshed:[],skipped:normalizedItemIds,warnings:[...invalidation.warnings,`search_semantic_refresh_skipped:settings_read_failed:${readFailure}`]}}settings=settingsRead.settings}catch(error){return{invalidated:invalidation.invalidated,refreshed:[],skipped:normalizedItemIds,warnings:[...invalidation.warnings,`search_semantic_refresh_skipped:settings_read_failed:${toErrorMessage(error)}`]}}if(settings.search.mutation_refresh_policy==="cache_only"){return{invalidated:invalidation.invalidated,refreshed:[],skipped:normalizedItemIds,warnings:invalidation.warnings}}const applyRuntimeDefaults=settings.search.mutation_refresh_policy==="semantic_auto";if(options.background&&isSemanticRefreshActive(settings,applyRuntimeDefaults)){await scheduleBackgroundSemanticRefresh(pmRoot,normalizedItemIds);return{invalidated:invalidation.invalidated,refreshed:[],skipped:[],warnings:[...invalidation.warnings,"search_semantic_refresh_scheduled_background"],scheduled:true}}const semanticRefresh=await refreshSemanticEmbeddingsForMutatedItems(pmRoot,normalizedItemIds,{settings,apply_runtime_defaults:applyRuntimeDefaults});return{invalidated:invalidation.invalidated,refreshed:semanticRefresh.refreshed,skipped:semanticRefresh.skipped,warnings:[...invalidation.warnings,...semanticRefresh.warnings]}}const _testOnly={buildSkippedSemanticRefreshResult,buildVectorizationIdentityForProvider,normalizeVectorizationLedgerEntries,resetSemanticVectorStore};export{SEARCH_CACHE_ARTIFACT_PATHS,VECTORIZATION_STATUS_LEDGER_PATH,_testOnly,invalidateSearchCacheArtifacts,isSemanticRefreshActive,readVectorizationStatusLedger,refreshSearchArtifactsForMutation,refreshSemanticEmbeddingsForMutatedItems,writeVectorizationStatusLedger};
 //# sourceMappingURL=cache.js.map
-//# debugId=7939a590-3662-5c66-99aa-3835a0dbaecc