oh-my-second-brain 0.3.0 → 0.6.2

package/dist/kernel/engine/mcp/facade.js

@@ -20,19 +20,18 @@
  * R18: NO import from src/search.
  */
 import path from "node:path";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { resolveBundledAssetPaths } from "../../runtime/assets.js";
+import { loadContract } from "../../contracts/index.js";
 import { retrieve } from "../retrieval/index.js";
-import { syncEngineStore, walkMarkdown } from "../embed/sync.js";
-import { buildGraph, saveCachedGraph, loadCachedGraphMeta, buildNodeIndex, saveNodeIndex, loadNodeIndex, } from "../graph/builder.js";
-import { filterNodesByAxis, searchScore } from "../graph/node.js";
-import { queryOptionsToSubQueries, retrievalResultsToQueryResult, queryResultUnavailable, } from "./query-mapper.js";
+import { acquireEngineStoreWriterLock, syncEngineStore, walkMarkdown, } from "../embed/sync.js";
+import { openEngineStore } from "../embed/store.js";
+import { buildGraph, saveCachedGraph, loadCachedGraphMeta, buildNodeIndex, saveNodeIndex, loadNodeIndex, nodeSourceSignature, } from "../graph/builder.js";
+import { filterNodesByAxis, filterNodesByQueryAxes, queryFacets, searchScore, } from "../graph/node.js";
+import { axisStorePath, collectVaultAxisObservations, openAxisStore, } from "../axes/store.js";
+import { normalizeQueryOptions, retrievalResultsToQueryResult, queryResultUnavailable, } from "./query-mapper.js";
 import { engineSyncResultToMcp, syncResultUnavailable, capsToEngineStatusResult, engineStatusResultToMcp, statusResultUnavailable, engineStatusToCollectionResult, engineStatusToContextResult, cleanupResultUnavailable, graphBuildOptionsToEngineArgs, engineGraphBuildResultToMcp, engineGraphBuildToStatusResult, } from "./op-mappers.js";
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function clamp(n, lo, hi) {
-    return Math.min(Math.max(n, lo), hi);
-}
 function positiveInt(value) {
     if (!value || !/^\d+$/u.test(value))
         return undefined;
@@ -197,11 +196,298 @@ function enrichQueryHits(result, vault) {
         const title = extractDocTitle(raw);
         return { ...hit, snippet: docHeadSnippet(raw), ...(title !== undefined ? { title } : {}) };
     });
-    return { available: true, hits };
+    return { ...result, available: true, hits };
+}
+/** Read folder intent declarations without creating or updating vault state. */
+function folderIntents(vault) {
+    const candidates = [
+        path.join(vault, ".oms", "taxonomy.yaml"),
+        path.join(vault, "taxonomy.yaml"),
+    ];
+    try {
+        candidates.push(path.join(resolveBundledAssetPaths().ontologyDir, "taxonomy.yaml"));
+    }
+    catch {
+        // A package without bundled ontology still serves axis results; intents
+        // remain optional metadata.
+    }
+    for (const candidate of candidates) {
+        try {
+            const parsed = parseYaml(readFileSync(candidate, "utf-8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                continue;
+            const folders = parsed["folders"];
+            if (!folders || typeof folders !== "object" || Array.isArray(folders))
+                continue;
+            const intents = new Map();
+            for (const [folder, value] of Object.entries(folders)) {
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    continue;
+                const intent = value["intent"];
+                if (typeof intent === "string" && intent.trim())
+                    intents.set(folder, intent.trim());
+            }
+            return intents;
+        }
+        catch {
+            // A missing optional taxonomy is not an error; a malformed one simply
+            // contributes no intent and never causes a write.
+        }
+    }
+    return new Map();
+}
+function facetIntent(facet, intents, queryIntent) {
+    if (facet.axis === "folder")
+        return intents.get(facet.value) ?? `Folder axis: ${facet.value}`;
+    if (queryIntent !== undefined && queryIntent.trim().length > 0)
+        return queryIntent.trim();
+    if (facet.axis === "field")
+        return `Frontmatter field axis: ${facet.key ?? "unknown"}`;
+    return `Link axis: ${facet.value}`;
 }
 function isLexOnlySubQueries(subQueries) {
     return subQueries.length > 0 && subQueries.every((subQuery) => subQuery.type === "lex");
 }
+/** Return true when the caller explicitly requested an embedding channel. */
+function hasExplicitEmbeddingSearch(opts) {
+    if (opts.mode === "vsearch")
+        return true;
+    if (typeof opts.vec === "string" && opts.vec.trim().length > 0)
+        return true;
+    if (typeof opts.hyde === "string" && opts.hyde.trim().length > 0)
+        return true;
+    return (opts.searches ?? []).some((search) => search.type === "vec" || search.type === "hyde");
+}
+const UNBOUNDED_CANDIDATE_LIMIT = Number.MAX_SAFE_INTEGER;
+/**
+ * Collection aggregation asks each child query for every candidate and applies
+ * one global page after merging. A direct query without a limit still keeps
+ * the public ten-hit default.
+ */
+function resultPageLimit(opts) {
+    return opts.limit ?? (opts.collectionPath === undefined ? undefined : UNBOUNDED_CANDIDATE_LIMIT);
+}
+/** Read the dedicated EAV snapshot without creating `.oms` state. */
+async function loadAxisSnapshot(vault) {
+    const dbPath = axisStorePath(vault);
+    if (!existsSync(dbPath))
+        return null;
+    const store = openAxisStore(dbPath, { readOnly: true });
+    try {
+        const storedSignature = store.sourceSignature();
+        if (storedSignature === null || storedSignature !== await nodeSourceSignature(vault))
+            return null;
+        return store.list();
+    }
+    finally {
+        store.close();
+    }
+}
+function observationValue(value) {
+    if (value instanceof Date)
+        return value.toISOString().toLowerCase();
+    return String(value).trim().toLowerCase();
+}
+function contractAxisType(type) {
+    switch (type) {
+        case "number":
+            return "number";
+        case "boolean":
+        case "checkbox":
+            return "boolean";
+        case "date":
+        case "datetime":
+            return "date";
+        case "text":
+        case "string":
+        case "select":
+        case "list":
+        case "multitext":
+        case "multi":
+        case "tags":
+        case "aliases":
+        case "file":
+            return "string";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Compare live frontmatter/EAV observations with the tracked JSON contract.
+ * Missing fields are allowed (required-field validation owns that concern);
+ * an observed undeclared key, type, or closed-vocabulary value is drift.
+ */
+function hasContractObservationDrift(contract, nodes, observations) {
+    if (contract === null)
+        return false;
+    const declared = new Set();
+    const types = new Map();
+    const allowed = new Map();
+    const addAllowed = (key, values) => {
+        if (values === undefined)
+            return;
+        const normalizedKey = key.trim().toLowerCase();
+        const target = allowed.get(normalizedKey) ?? new Set();
+        for (const item of values) {
+            const value = typeof item === "string"
+                ? item
+                : item && typeof item === "object" && typeof item.value === "string"
+                    ? item.value
+                    : undefined;
+            if (value !== undefined)
+                target.add(observationValue(value));
+        }
+        allowed.set(normalizedKey, target);
+    };
+    for (const axis of contract.axes) {
+        if (axis.kind !== "field")
+            continue;
+        const key = axis.key.trim().toLowerCase();
+        if (key === "concept")
+            continue;
+        declared.add(key);
+        types.set(key, axis.type);
+        addAllowed(key, axis.allowedValues);
+    }
+    for (const [key, type] of Object.entries(contract.types)) {
+        const normalizedKey = key.trim().toLowerCase();
+        if (normalizedKey === "concept")
+            continue;
+        declared.add(normalizedKey);
+        types.set(normalizedKey, type);
+    }
+    for (const [key, values] of Object.entries(contract.allowedValues)) {
+        const normalizedKey = key.trim().toLowerCase();
+        if (normalizedKey === "concept")
+            continue;
+        declared.add(normalizedKey);
+        addAllowed(normalizedKey, values);
+    }
+    const observedKeys = new Set();
+    const observedValues = [];
+    // Node axes are the live source of truth even when no EAV snapshot exists.
+    for (const node of nodes) {
+        for (const [key, rawValues] of Object.entries(node.axes)) {
+            const normalizedKey = key.trim().toLowerCase();
+            if (normalizedKey === "concept")
+                continue;
+            observedKeys.add(normalizedKey);
+            const values = Array.isArray(rawValues) ? rawValues : [rawValues];
+            for (const value of values) {
+                // String values can also represent YAML dates after node-cache
+                // serialisation, so only infer unambiguous primitive types here.
+                const valueType = typeof value === "number"
+                    ? "number"
+                    : typeof value === "boolean"
+                        ? "boolean"
+                        : undefined;
+                observedValues.push({ key: normalizedKey, value, valueType });
+            }
+        }
+    }
+    for (const row of observations ?? []) {
+        const normalizedKey = row.axisKey.trim().toLowerCase();
+        if (row.axisKind !== "field" || normalizedKey === "concept")
+            continue;
+        observedKeys.add(normalizedKey);
+        observedValues.push({
+            key: normalizedKey,
+            value: row.value,
+            valueType: row.valueType,
+            normalizedValue: row.normalizedValue,
+        });
+    }
+    for (const observed of observedValues) {
+        if (!declared.has(observed.key))
+            return true;
+        const expectedType = contractAxisType(types.get(observed.key) ?? "");
+        if (expectedType !== undefined && observed.valueType !== undefined && expectedType !== observed.valueType) {
+            return true;
+        }
+        const values = allowed.get(observed.key);
+        if (values !== undefined && !values.has(observed.normalizedValue ?? observationValue(observed.value))) {
+            return true;
+        }
+    }
+    for (const key of observedKeys) {
+        if (!declared.has(key))
+            return true;
+    }
+    return false;
+}
+async function contractObservationDrift(vault, nodes, observations) {
+    return hasContractObservationDrift(await loadContract(vault), nodes, observations);
+}
+/** Overlay typed EAV values onto the lexical node snapshot. */
+function applyAxisSnapshot(nodes, observations) {
+    const byNote = new Map();
+    for (const observation of observations) {
+        const rows = byNote.get(observation.notePath) ?? [];
+        rows.push(observation);
+        byNote.set(observation.notePath, rows);
+    }
+    return nodes.map((node) => {
+        const rows = byNote.get(node.path);
+        if (rows === undefined)
+            return node;
+        const fields = {};
+        const links = [];
+        let folder = node.folder;
+        for (const row of rows) {
+            const value = row.value instanceof Date ? row.value.toISOString() : row.value;
+            if (row.axisKind === "folder" && typeof value === "string") {
+                folder = value;
+            }
+            else if (row.axisKind === "link" && typeof value === "string") {
+                links.push(value);
+            }
+            else if (row.axisKind === "field") {
+                const values = fields[row.axisKey] ?? [];
+                values.push(value);
+                fields[row.axisKey] = values;
+            }
+        }
+        return {
+            ...node,
+            folder,
+            // The node DTO keeps its legacy string-array declaration, while this
+            // runtime overlay deliberately carries typed EAV scalars.
+            axes: fields,
+            // An existing snapshot is authoritative: an empty link/field set must
+            // clear stale values from an older JSON node-index cache.
+            wikilinks: [...new Set(links)],
+        };
+    });
+}
+/** Contract field names are the allow-list for public field-axis queries. */
+async function loadContractFieldKeys(vault) {
+    const contract = await loadContract(vault);
+    if (contract === null)
+        return undefined;
+    const keys = new Set();
+    for (const axis of contract.axes) {
+        if (axis.kind === "field")
+            keys.add(axis.key.trim().toLowerCase());
+    }
+    for (const key of Object.keys(contract.types))
+        keys.add(key.trim().toLowerCase());
+    return keys;
+}
+function validateKnownFieldAxes(axes, knownFields) {
+    if (axes === undefined || knownFields === undefined || axes.field === undefined)
+        return;
+    if (axes.field === null || typeof axes.field !== "object" || Array.isArray(axes.field)) {
+        throw new Error("Field axis must be an object mapping field names to values.");
+    }
+    for (const key of Object.keys(axes.field)) {
+        if (key.trim().toLocaleLowerCase() === "concept") {
+            throw new Error('Unknown query field axis "concept".');
+        }
+        if (!knownFields.has(key.trim().toLowerCase())) {
+            throw new Error(`Unknown field axis "${key}" (not declared by the JSON contract).`);
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // Adapter facade
 // ---------------------------------------------------------------------------
@@ -217,6 +503,7 @@ export class McpEngineAdapter {
     config;
     reranker;
     implicitLexicalSync;
+    persistLexicalSync;
     /**
      * @param deps      - Injected backend dependencies (store + embed required).
      * @param vaultPath - Absolute vault root, used by graph / sync / cleanup /
@@ -228,12 +515,13 @@ export class McpEngineAdapter {
      */
     constructor(deps, vaultPath, config, reranker, 
     /** Explicit assembly policy; read-only engines suppress this refresh. */
-    implicitLexicalSync = false) {
+    implicitLexicalSync = false, persistLexicalSync = true) {
         this.deps = deps;
         this.vaultPath = vaultPath;
         this.config = config;
         this.reranker = reranker;
         this.implicitLexicalSync = implicitLexicalSync;
+        this.persistLexicalSync = persistLexicalSync;
     }
     // -------------------------------------------------------------------------
     // Cache-path + node-index helpers
@@ -245,37 +533,167 @@ export class McpEngineAdapter {
         return path.join(vault, ".oms", "cache", "engine", "node-index.json");
     }
     /** Load the node index from cache, building it live on a cache miss. */
-    async loadOrBuildNodes() {
-        const cached = await loadNodeIndex(this.nodeCachePath(this.vaultPath));
+    async loadOrBuildNodes(vault = this.vaultPath) {
+        // A direct adapter caller may supply a store-backed query without a
+        // filesystem vault (for example an MCP transport test). Node enrichment is
+        // optional in that case; never turn a valid retrieval result into an ENOENT.
+        if (!existsSync(vault))
+            return [];
+        const cached = await loadNodeIndex(this.nodeCachePath(vault), await nodeSourceSignature(vault));
         if (cached !== null)
             return cached;
-        return buildNodeIndex({ vaultPath: this.vaultPath });
+        return buildNodeIndex({ vaultPath: vault });
     }
     // -------------------------------------------------------------------------
     // 1. oms_semantic_query (centerpiece)
     // -------------------------------------------------------------------------
+    /**
+     * Evaluate an overview/axis query directly from the read-only node index.
+     * This path is intentionally model-free and does not open the embedding
+     * store, so a query issued outside a vault or against an empty vault cannot
+     * create `.oms/` state as a side effect.
+     */
+    async queryNodeAxes(opts, subQueries) {
+        const vault = opts.vault ?? this.vaultPath;
+        const baseNodes = await this.loadOrBuildNodes(vault);
+        const snapshot = await loadAxisSnapshot(vault);
+        const drift = await contractObservationDrift(vault, baseNodes, snapshot);
+        const observedFields = snapshot === null
+            ? undefined
+            : new Set(snapshot.filter((row) => row.axisKind === "field").map((row) => row.axisKey.toLowerCase()));
+        const liveObservedFields = new Set(baseNodes.flatMap((node) => Object.keys(node.axes).map((key) => key.toLowerCase())));
+        const knownFields = await loadContractFieldKeys(vault)
+            ?? (observedFields === undefined ? liveObservedFields : new Set([...observedFields, ...liveObservedFields]));
+        validateKnownFieldAxes(opts.axes, knownFields);
+        const nodes = snapshot === null ? baseNodes : applyAxisSnapshot(baseNodes, snapshot);
+        const axisFiltered = opts.axes === undefined
+            ? nodes
+            : filterNodesByQueryAxes(nodes, opts.axes);
+        const collection = opts.collectionPath;
+        const filtered = collection === undefined
+            ? axisFiltered
+            : axisFiltered.filter((node) => node.path === collection || node.path.startsWith(`${collection}/`));
+        const query = subQueries.find((subQuery) => subQuery.type === "lex")?.query
+            ?? (subQueries.length === 0 ? opts.query ?? "" : "");
+        const scored = filtered
+            .map((node) => {
+            const score = searchScore(node, query);
+            return {
+                docPath: node.path,
+                score,
+                ...(query.trim().length > 0 ? { perTypeScores: { lex: score } } : {}),
+            };
+        })
+            // An axis constraint narrows the corpus; it is not lexical evidence.
+            // Once a lexical query is supplied, do not return axis-only zero-score
+            // documents as query hits.
+            .filter((result) => query.trim().length === 0 || result.score > 0)
+            .sort((left, right) => right.score - left.score || left.docPath.localeCompare(right.docPath));
+        const facetNodes = opts.minScore === undefined
+            ? filtered
+            : filtered.filter((node) => searchScore(node, query) >= opts.minScore);
+        const intents = folderIntents(vault);
+        const facets = queryFacets(facetNodes).map((facet) => ({
+            ...facet,
+            intent: facetIntent(facet, intents, opts.intent),
+        }));
+        const candidateLimit = opts.candidateLimit ?? UNBOUNDED_CANDIDATE_LIMIT;
+        const candidates = scored.slice(0, candidateLimit);
+        const shouldRerank = opts.rerank === true && opts.noRerank !== true;
+        if (shouldRerank && this.reranker === undefined) {
+            return queryResultUnavailable("reranking requires a configured Reranker; pass one to assembleEngine() or createOMSMcpServer().");
+        }
+        if (shouldRerank && query.trim().length === 0) {
+            return queryResultUnavailable("reranking requires a non-empty natural-language query.");
+        }
+        const reranker = this.reranker;
+        const ranked = shouldRerank
+            ? await reranker.rerank(query, candidates.map((result) => ({
+                docPath: result.docPath,
+                chunkOrdinal: 0,
+                score: result.score,
+            }))).then((reranked) => {
+                const candidateByPath = new Map(candidates.map((candidate) => [candidate.docPath, candidate]));
+                return reranked.flatMap((hit) => {
+                    const candidate = candidateByPath.get(hit.docPath);
+                    return candidate === undefined
+                        ? []
+                        : [{ ...candidate, score: hit.score, perTypeScores: { lex: hit.score } }];
+                });
+            })
+            : candidates;
+        const hasNonLexSearch = subQueries.some((search) => search.type !== "lex");
+        const result = retrievalResultsToQueryResult(ranked, {
+            minScore: opts.minScore,
+            limit: resultPageLimit(opts),
+            cursor: opts.cursor,
+            intent: opts.intent,
+            facetValues: facets,
+            // Axis queries are evaluated by the model-free node matcher. A vector
+            // request is reported as approximated rather than falsely claiming vec
+            // evidence in the receipt.
+            usedChannels: query.trim().length > 0 ? ["lex"] : [],
+            approximated: hasNonLexSearch,
+            drift,
+        });
+        return enrichQueryHits(result, vault);
+    }
     /**
      * Execute a semantic query and return MCP-shaped results.
      * Maps opts → TypedSubQuery[] → dispatch() → McpSemanticQueryResult.
      */
     async semanticQuery(opts) {
-        const subQueries = queryOptionsToSubQueries(opts);
-        if (subQueries.length === 0) {
-            return queryResultUnavailable("No sub-queries derived from options");
+        let normalized;
+        try {
+            normalized = normalizeQueryOptions(opts);
+        }
+        catch (err) {
+            return queryResultUnavailable(err instanceof Error ? err.message : String(err));
+        }
+        const { subQueries } = normalized;
+        if (opts.axes !== undefined && hasExplicitEmbeddingSearch(opts)) {
+            return queryResultUnavailable("Axis queries support lexical matching only; explicit vector/HyDE retrieval requires " +
+                "OMS_EMBEDDING_PROVIDER + OMS_EMBEDDING_MODEL.");
+        }
+        if (opts.axes !== undefined || normalized.overview) {
+            try {
+                return await this.queryNodeAxes(opts, subQueries);
+            }
+            catch (err) {
+                return queryResultUnavailable(err instanceof Error ? err.message : String(err));
+            }
         }
         try {
-            if (this.implicitLexicalSync && isLexOnlySubQueries(subQueries)) {
+            // A core engine has a real lexical store but deliberately no embedding
+            // provider. The default query mode is hybrid for vector-capable engines;
+            // on a model-less engine, retain the useful lexical half unless the
+            // caller explicitly asked for vec/HyDE (which must fail loudly).
+            const vecAvailable = typeof this.deps.store.capabilities === "function"
+                ? this.deps.store.capabilities().vecAvailable
+                : true;
+            const modelLessFallback = !vecAvailable &&
+                !hasExplicitEmbeddingSearch(opts) &&
+                subQueries.some((subQuery) => subQuery.type === "vec");
+            const effectiveSubQueries = modelLessFallback
+                ? subQueries.filter((subQuery) => subQuery.type === "lex")
+                : subQueries;
+            if (this.implicitLexicalSync && isLexOnlySubQueries(effectiveSubQueries)) {
                 const syncResult = await syncEngineStore({
                     vault: opts.vault ?? this.vaultPath,
                     collection: opts.collection,
                     embed: false,
                     store: this.deps.store,
+                    persist: this.persistLexicalSync,
                 });
                 if (!syncResult.available) {
                     return queryResultUnavailable(syncResult.reason ?? "Lexical index sync unavailable");
                 }
             }
-            const k = opts.candidateLimit ?? 20;
+            // Without an explicit candidate limit, retrieve the complete ranked
+            // stream so totalCount and offset cursors remain accurate on pages past
+            // the first 50 results. A caller-supplied candidateLimit remains an
+            // intentional cap (not an implementation truncation).
+            const k = opts.candidateLimit ?? UNBOUNDED_CANDIDATE_LIMIT;
             const shouldRerank = opts.rerank === true && opts.noRerank !== true;
             if (shouldRerank && this.reranker === undefined) {
                 return queryResultUnavailable("reranking requires a configured Reranker; pass one to assembleEngine() or createOMSMcpServer().");
@@ -284,14 +702,38 @@ export class McpEngineAdapter {
                 return queryResultUnavailable("reranking requires a non-empty natural-language query.");
             }
             const results = await retrieve({
-                subQueries,
+                subQueries: [...effectiveSubQueries],
                 deps: this.deps,
                 k,
                 collection: opts.collectionPath,
                 query: opts.query,
                 reranker: shouldRerank ? this.reranker : undefined,
             });
-            const mapped = retrievalResultsToQueryResult(results, opts);
+            let facetValues;
+            const vault = opts.vault ?? this.vaultPath;
+            const baseNodes = await this.loadOrBuildNodes(vault);
+            const snapshot = await loadAxisSnapshot(vault);
+            const nodes = snapshot === null ? baseNodes : applyAxisSnapshot(baseNodes, snapshot);
+            const drift = await contractObservationDrift(vault, baseNodes, snapshot);
+            const scoped = opts.collectionPath === undefined
+                ? nodes
+                : nodes.filter((node) => node.path === opts.collectionPath || node.path.startsWith(`${opts.collectionPath}/`));
+            const intents = folderIntents(vault);
+            facetValues = queryFacets(scoped).map((facet) => ({
+                ...facet,
+                intent: facetIntent(facet, intents, opts.intent),
+            }));
+            const requestedChannels = [...new Set(effectiveSubQueries.map((search) => search.type))]
+                .filter((type) => type === "lex" || type === "vec" || type === "hyde");
+            const mapped = retrievalResultsToQueryResult(results, {
+                ...opts,
+                limit: resultPageLimit(opts),
+                facetValues,
+                usedChannels: requestedChannels,
+                approximated: modelLessFallback ||
+                    effectiveSubQueries.some((search) => search.type !== "lex" && search.type !== "vec"),
+                drift,
+            });
             // Fill title + doc-head snippet from disk so engine hits reach practical
             // parity with the src/search preview (the pure mapper stays text-free).
             return enrichQueryHits(mapped, opts.vault ?? this.vaultPath);
@@ -314,6 +756,9 @@ export class McpEngineAdapter {
      * pool deduplicates by loadPromise per process so this is safe (RISK-1).
      */
     async syncEmbeddings(opts) {
+        const activeDbPath = this.config?.dbPath ??
+            path.join(path.resolve(opts.vault), ".oms", "engine-store.sqlite");
+        let swapHandleClosed = false;
         try {
             const syncResult = await syncEngineStore({
                 vault: opts.vault,
@@ -325,8 +770,31 @@ export class McpEngineAdapter {
                 // resolves the real provider and fails fast (ADR-007) if it is missing.
                 embeddingProvider: this.config?.embeddingProvider,
                 embeddingModel: this.config?.embeddingModel,
+                embeddingDescriptor: this.config?.embeddingDescriptor,
+                embeddingDimensions: this.config?.embeddingDimensions,
+                embeddingContext: this.config?.embeddingContext,
+                embeddingContextLength: this.config?.embeddingContextLength,
+                embeddingContextTokens: this.config?.embeddingContextTokens,
+                embeddingMrlDim: this.config?.embeddingMrlDim,
+                embeddingNormalization: this.config?.embeddingNormalization,
+                embeddingPrefixScheme: this.config?.embeddingPrefixScheme,
+                dbPath: this.config?.dbPath,
                 embed: opts.embed ?? true,
                 force: opts.force ?? false,
+                onGenerationSwapPrepare: () => {
+                    // The adapter's store outlives one sync call. Close it before the
+                    // active WAL/SHM sidecars are removed, not after rename.
+                    swapHandleClosed = true;
+                    this.deps.store.close();
+                },
+                onGenerationSwapComplete: () => {
+                    if (!swapHandleClosed)
+                        return;
+                    const reboundStore = openEngineStore(activeDbPath, this.deps.embed.dimensions);
+                    this.deps.store = reboundStore;
+                    this.config?.onStoreRebind?.(reboundStore);
+                    swapHandleClosed = false;
+                },
             });
             if (!syncResult.available) {
                 return syncResultUnavailable(syncResult.reason ?? "sync unavailable", opts);
@@ -408,7 +876,11 @@ export class McpEngineAdapter {
      * longer exists in the live vault is cleared (meta + vec + FTS).
      */
     async cleanup(_opts) {
+        let releaseLock;
         try {
+            const dbPath = this.config?.dbPath ??
+                path.join(path.resolve(this.vaultPath), ".oms", "engine-store.sqlite");
+            releaseLock = acquireEngineStoreWriterLock(dbPath);
             const store = this.deps.store;
             const livePaths = new Set();
             for await (const rel of walkMarkdown(this.vaultPath, this.vaultPath)) {
@@ -433,6 +905,9 @@ export class McpEngineAdapter {
         catch (err) {
             return cleanupResultUnavailable(err instanceof Error ? err.message : String(err));
         }
+        finally {
+            releaseLock?.();
+        }
     }
     // -------------------------------------------------------------------------
     // 7. oms_graph_build
@@ -463,7 +938,12 @@ export class McpEngineAdapter {
         const edges = await buildGraph({ vaultPath: args.vaultPath });
         await saveCachedGraph(graphCachePath, edges);
         const nodes = await buildNodeIndex({ vaultPath: args.vaultPath });
-        await saveNodeIndex(this.nodeCachePath(args.vaultPath), nodes);
+        const sourceSignature = await nodeSourceSignature(args.vaultPath);
+        await saveNodeIndex(this.nodeCachePath(args.vaultPath), nodes, sourceSignature);
+        // Graph build is the explicit writable refresh boundary for the typed
+        // EAV snapshot. Reconcile it atomically with the current markdown set.
+        const axisStore = await collectVaultAxisObservations(args.vaultPath);
+        axisStore.close();
         const noteSet = new Set(edges.flatMap((e) => [e.from, e.to]));
         return engineGraphBuildResultToMcp({
             notes: noteSet.size,
@@ -497,8 +977,11 @@ export class McpEngineAdapter {
      */
     async retrieveByAxis(filters) {
         try {
-            const nodes = await this.loadOrBuildNodes();
-            const limit = clamp(filters.limit ?? 10, 1, 50);
+            const baseNodes = await this.loadOrBuildNodes();
+            const snapshot = await loadAxisSnapshot(this.vaultPath);
+            const drift = await contractObservationDrift(this.vaultPath, baseNodes, snapshot);
+            const nodes = snapshot === null ? baseNodes : applyAxisSnapshot(baseNodes, snapshot);
+            const limit = Math.max(1, filters.limit ?? 10);
             const filtered = filterNodesByAxis(nodes, {
                 concept: filters.concept,
                 folder: filters.folder,
@@ -525,10 +1008,22 @@ export class McpEngineAdapter {
                 }),
                 evidence: { lexical: true, vector: false },
             }));
-            return { available: true, hits };
+            const intents = folderIntents(this.vaultPath);
+            const facets = queryFacets(filtered).map((facet) => ({
+                ...facet,
+                intent: facetIntent(facet, intents, undefined),
+            }));
+            return {
+                available: true,
+                hits,
+                totalCount: filtered.length,
+                facets,
+                cursor: scored.length < filtered.length ? String(scored.length) : null,
+                receipt: { usedChannels: ["lex"], approximated: false, drift },
+            };
         }
         catch (err) {
-            return { available: false, reason: err instanceof Error ? err.message : String(err), hits: [] };
+            return queryResultUnavailable(err instanceof Error ? err.message : String(err));
         }
     }
     // -------------------------------------------------------------------------