akm-cli 0.9.6 → 0.9.8-beta.1

package/dist/indexer/db/graph-db.js

@@ -259,25 +259,20 @@ export function acknowledgeExtractionQueueEntry(db, stashRoot, filePath, bodyHas
 export function loadGraphFilesOnly(stashPath, db) {
     try {
         return withReadableGraphDb(db, (readDb) => {
-            try {
-                const rows = readDb
-                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason
-                FROM graph_files
-                WHERE stash_root = ?
-                ORDER BY file_order`)
-                    .all(stashPath);
-                return rows.map((row) => ({
-                    path: row.file_path,
-                    type: row.file_type,
-                    bodyHash: row.body_hash,
-                    ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
-                    ...(row.status ? { status: row.status } : {}),
-                    ...(row.reason ? { reason: row.reason } : {}),
-                }));
-            }
-            catch {
-                return [];
-            }
+            const rows = readDb
+                .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason
+              FROM graph_files
+              WHERE stash_root = ?
+              ORDER BY file_order`)
+                .all(stashPath);
+            return rows.map((row) => ({
+                path: row.file_path,
+                type: row.file_type,
+                bodyHash: row.body_hash,
+                ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
+                ...(row.status ? { status: row.status } : {}),
+                ...(row.reason ? { reason: row.reason } : {}),
+            }));
         });
     }
     catch (err) {
@@ -292,66 +287,61 @@ export function loadGraphFilesOnly(stashPath, db) {
 export function loadStoredGraphMeta(stashPath, db) {
     try {
         return withReadableGraphDb(db, (readDb) => {
-            try {
-                const row = readDb
-                    .prepare(`SELECT
-               stash_root,
-               schema_version,
-               generated_at,
-               considered_files,
-               extracted_files,
-               entity_count,
-               relation_count,
-               extraction_coverage,
-               density,
-               extractor_id,
-               extraction_run_id,
-               model,
-               prompt_version,
-               batch_size,
-               cache_hits,
-               cache_misses,
-               truncation_count,
-               failure_count
-              FROM graph_meta
-              WHERE stash_root = ?`)
-                    .get(stashPath);
-                if (!row)
-                    return null;
-                return {
-                    stashPath: row.stash_root,
-                    graphPath: getDbPath(),
-                    schemaVersion: row.schema_version,
-                    generatedAt: row.generated_at,
-                    quality: {
-                        consideredFiles: row.considered_files,
-                        extractedFiles: row.extracted_files,
-                        entityCount: row.entity_count,
-                        relationCount: row.relation_count,
-                        extractionCoverage: row.extraction_coverage,
-                        density: row.density,
-                    },
-                    telemetry: {
-                        ...(row.extractor_id ? { extractorId: row.extractor_id } : {}),
-                        ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
-                        ...(row.model ? { model: row.model } : {}),
-                        ...(row.prompt_version ? { promptVersion: row.prompt_version } : {}),
-                        ...(typeof row.batch_size === "number" ? { batchSize: row.batch_size } : {}),
-                        cacheHits: row.cache_hits,
-                        cacheMisses: row.cache_misses,
-                        truncationCount: row.truncation_count,
-                        failureCount: row.failure_count,
-                        // `retry_attempts` is not persisted to the graph-meta table (it is
-                        // surfaced from the run's emitted telemetry into `akm health`, not
-                        // from the reuse cache). Default to 0 so the loaded shape satisfies
-                        // GraphExtractionTelemetry.
-                        retryAttempts: 0,
-                    },
-                };
-            }
-            catch {
+            const row = readDb
+                .prepare(`SELECT
+             stash_root,
+             schema_version,
+             generated_at,
+             considered_files,
+             extracted_files,
+             entity_count,
+             relation_count,
+             extraction_coverage,
+             density,
+             extractor_id,
+             extraction_run_id,
+             model,
+             prompt_version,
+             batch_size,
+             cache_hits,
+             cache_misses,
+             truncation_count,
+             failure_count
+            FROM graph_meta
+            WHERE stash_root = ?`)
+                .get(stashPath);
+            if (!row)
                 return null;
-            }
+            return {
+                stashPath: row.stash_root,
+                graphPath: getDbPath(),
+                schemaVersion: row.schema_version,
+                generatedAt: row.generated_at,
+                quality: {
+                    consideredFiles: row.considered_files,
+                    extractedFiles: row.extracted_files,
+                    entityCount: row.entity_count,
+                    relationCount: row.relation_count,
+                    extractionCoverage: row.extraction_coverage,
+                    density: row.density,
+                },
+                telemetry: {
+                    ...(row.extractor_id ? { extractorId: row.extractor_id } : {}),
+                    ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
+                    ...(row.model ? { model: row.model } : {}),
+                    ...(row.prompt_version ? { promptVersion: row.prompt_version } : {}),
+                    ...(typeof row.batch_size === "number" ? { batchSize: row.batch_size } : {}),
+                    cacheHits: row.cache_hits,
+                    cacheMisses: row.cache_misses,
+                    truncationCount: row.truncation_count,
+                    failureCount: row.failure_count,
+                    // `retry_attempts` is not persisted to the graph-meta table (it is
+                    // surfaced from the run's emitted telemetry into `akm health`, not
+                    // from the reuse cache). Default to 0 so the loaded shape satisfies
+                    // GraphExtractionTelemetry.
+                    retryAttempts: 0,
+                },
+            };
         });
     }
     catch (err) {
@@ -368,85 +358,80 @@ export function loadStoredGraphSnapshot(stashPath, db) {
             const meta = loadStoredGraphMeta(stashPath, readDb);
             if (!meta)
                 return null;
-            try {
-                const fileRows = readDb
-                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
-              FROM graph_files
-              WHERE stash_root = ?
-              ORDER BY file_order`)
-                    .all(stashPath);
-                const entityRows = readDb
-                    .prepare(`SELECT gf.file_path AS file_path, gfe.entity AS entity
-             FROM graph_file_entities gfe
-             JOIN graph_files gf
-               ON gf.stash_root = gfe.stash_root
-              AND gf.file_path = gfe.file_path
-              AND gf.body_hash = gfe.body_hash
-             WHERE gf.stash_root = ?
-             ORDER BY gf.file_order, gfe.entity_order`)
-                    .all(stashPath);
-                const relationRows = readDb
-                    .prepare(`SELECT gf.file_path AS file_path,
-                    gfr.from_entity AS from_entity,
-                    gfr.to_entity AS to_entity,
-                    gfr.relation_type AS relation_type,
-                    gfr.confidence AS confidence
-             FROM graph_file_relations gfr
-             JOIN graph_files gf
-               ON gf.stash_root = gfr.stash_root
-              AND gf.file_path = gfr.file_path
-              AND gf.body_hash = gfr.body_hash
-             WHERE gf.stash_root = ?
-             ORDER BY gf.file_order, gfr.relation_order`)
-                    .all(stashPath);
-                const entitiesByPath = new Map();
-                for (const row of entityRows) {
-                    const bucket = entitiesByPath.get(row.file_path);
-                    if (bucket)
-                        bucket.push(row.entity);
-                    else
-                        entitiesByPath.set(row.file_path, [row.entity]);
-                }
-                const relationsByPath = new Map();
-                for (const row of relationRows) {
-                    const relation = {
-                        from: row.from_entity,
-                        to: row.to_entity,
-                        ...(row.relation_type ? { type: row.relation_type } : {}),
-                        ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
-                    };
-                    const bucket = relationsByPath.get(row.file_path);
-                    if (bucket)
-                        bucket.push(relation);
-                    else
-                        relationsByPath.set(row.file_path, [relation]);
-                }
-                const files = fileRows.map((row) => ({
-                    path: row.file_path,
-                    type: row.file_type,
-                    ...(row.body_hash ? { bodyHash: row.body_hash } : {}),
-                    entities: entitiesByPath.get(row.file_path) ?? [],
-                    relations: relationsByPath.get(row.file_path) ?? [],
+            const fileRows = readDb
+                .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
+            FROM graph_files
+            WHERE stash_root = ?
+            ORDER BY file_order`)
+                .all(stashPath);
+            const entityRows = readDb
+                .prepare(`SELECT gf.file_path AS file_path, gfe.entity AS entity
+           FROM graph_file_entities gfe
+           JOIN graph_files gf
+             ON gf.stash_root = gfe.stash_root
+            AND gf.file_path = gfe.file_path
+            AND gf.body_hash = gfe.body_hash
+           WHERE gf.stash_root = ?
+           ORDER BY gf.file_order, gfe.entity_order`)
+                .all(stashPath);
+            const relationRows = readDb
+                .prepare(`SELECT gf.file_path AS file_path,
+                  gfr.from_entity AS from_entity,
+                  gfr.to_entity AS to_entity,
+                  gfr.relation_type AS relation_type,
+                  gfr.confidence AS confidence
+           FROM graph_file_relations gfr
+           JOIN graph_files gf
+             ON gf.stash_root = gfr.stash_root
+            AND gf.file_path = gfr.file_path
+            AND gf.body_hash = gfr.body_hash
+           WHERE gf.stash_root = ?
+           ORDER BY gf.file_order, gfr.relation_order`)
+                .all(stashPath);
+            const entitiesByPath = new Map();
+            for (const row of entityRows) {
+                const bucket = entitiesByPath.get(row.file_path);
+                if (bucket)
+                    bucket.push(row.entity);
+                else
+                    entitiesByPath.set(row.file_path, [row.entity]);
+            }
+            const relationsByPath = new Map();
+            for (const row of relationRows) {
+                const relation = {
+                    from: row.from_entity,
+                    to: row.to_entity,
+                    ...(row.relation_type ? { type: row.relation_type } : {}),
                     ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
-                    ...(row.status ? { status: row.status } : {}),
-                    ...(row.reason ? { reason: row.reason } : {}),
-                    ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
-                }));
-                return {
-                    stashPath: meta.stashPath,
-                    graphPath: meta.graphPath,
-                    schemaVersion: meta.schemaVersion,
-                    generatedAt: meta.generatedAt,
-                    ...(meta.quality ? { quality: meta.quality } : {}),
-                    ...(meta.telemetry ? { telemetry: meta.telemetry } : {}),
-                    files,
-                    entities: uniqueSorted(files.flatMap((file) => file.entities)),
-                    relations: files.flatMap((file) => file.relations),
                 };
+                const bucket = relationsByPath.get(row.file_path);
+                if (bucket)
+                    bucket.push(relation);
+                else
+                    relationsByPath.set(row.file_path, [relation]);
             }
-            catch {
-                return null;
-            }
+            const files = fileRows.map((row) => ({
+                path: row.file_path,
+                type: row.file_type,
+                ...(row.body_hash ? { bodyHash: row.body_hash } : {}),
+                entities: entitiesByPath.get(row.file_path) ?? [],
+                relations: relationsByPath.get(row.file_path) ?? [],
+                ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
+                ...(row.status ? { status: row.status } : {}),
+                ...(row.reason ? { reason: row.reason } : {}),
+                ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
+            }));
+            return {
+                stashPath: meta.stashPath,
+                graphPath: meta.graphPath,
+                schemaVersion: meta.schemaVersion,
+                generatedAt: meta.generatedAt,
+                ...(meta.quality ? { quality: meta.quality } : {}),
+                ...(meta.telemetry ? { telemetry: meta.telemetry } : {}),
+                files,
+                entities: uniqueSorted(files.flatMap((file) => file.entities)),
+                relations: files.flatMap((file) => file.relations),
+            };
         });
     }
     catch (err) {

package/dist/indexer/ensure-index.js

@@ -24,7 +24,6 @@ import path from "node:path";
 import { placementSpecList } from "../core/asset/asset-placement.js";
 import { classifyPathAccess } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
-import { warn } from "../core/warn.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getEntryCount, getIndexedFilePaths } from "../storage/repositories/index-entries-repository.js";
 import { getMeta } from "../storage/repositories/index-meta-repository.js";
@@ -188,22 +187,14 @@ function indexCanServeStash(stashDir) {
     }
 }
 async function runInlineReindex(stashDir, options = {}) {
-    try {
-        const { akmIndex } = await import("./indexer.js");
-        await akmIndex({
-            stashDir,
-            implicit: true,
-            ...(options.signal ? { signal: options.signal } : {}),
-            ...(options.hydrateSources === false ? { hydrateSources: false } : {}),
-        });
-        return true;
-    }
-    catch (error) {
-        if (options.signal?.aborted)
-            throw error;
-        warn("Auto-index failed, proceeding with existing index:", error instanceof Error ? error.message : String(error));
-        return false;
-    }
+    const { akmIndex } = await import("./indexer.js");
+    await akmIndex({
+        stashDir,
+        implicit: true,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.hydrateSources === false ? { hydrateSources: false } : {}),
+    });
+    return true;
 }
 /**
  * Ensure the local index exists and can serve the caller.
@@ -217,8 +208,9 @@ async function runInlineReindex(stashDir, options = {}) {
  * trigger and waits for it. Use this for callers like `improve` whose
  * planning logic depends on a current `entries` table in the same process.
  *
- * Returns `true` only when an inline index run succeeds.
- * A rebuild attempt that fails (throws) resolves to `false`.
+ * Returns `true` only when an inline index run succeeds; `false` when no
+ * rebuild was needed. A rebuild attempt that fails propagates its error to
+ * the caller rather than silently proceeding with a stale/missing index.
  */
 export async function ensureIndex(stashDir, options = {}) {
     // §11.5: warn (once) if the configured bundle ids drifted from the persisted

package/dist/indexer/graph/graph-boost.js

@@ -257,45 +257,34 @@ export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
     }
     // Confirm the target file has a graph row; without it there is nothing to
     // relate. (Identity is file_path within the stash — one row per path.)
-    try {
-        const row = db
-            .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
-            .get(stashRoot, filePath);
-        if (row === undefined)
-            return [];
-    }
-    catch {
+    const row = db
+        .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+        .get(stashRoot, filePath);
+    if (row === undefined)
         return [];
-    }
     const effectiveLimit = Math.max(1, limit);
     // Shared-entity count per candidate file_path. The target's entities are the
     // rows for `filePath`; candidates are any OTHER file_path in the stash that
     // shares a normalized entity.
-    let candidateRows;
-    try {
-        candidateRows = db
-            .prepare(`SELECT gf.file_path   AS file_path,
-                gf.file_type   AS file_type,
-                COUNT(*)       AS shared
-            FROM graph_file_entities target
-            JOIN graph_file_entities e
-              ON e.stash_root = target.stash_root
-             AND e.entity_norm = target.entity_norm
-             AND e.file_path  != target.file_path
-            JOIN graph_files gf
-              ON gf.stash_root = e.stash_root
-             AND gf.file_path = e.file_path
-             AND gf.body_hash = e.body_hash
-          WHERE target.file_path  = ?
-            AND target.stash_root = ?
-          GROUP BY gf.file_path
-          ORDER BY shared DESC, gf.file_path ASC
-          LIMIT ?`)
-            .all(filePath, stashRoot, effectiveLimit);
-    }
-    catch {
-        return [];
-    }
+    const candidateRows = db
+        .prepare(`SELECT gf.file_path   AS file_path,
+              gf.file_type   AS file_type,
+              COUNT(*)       AS shared
+          FROM graph_file_entities target
+          JOIN graph_file_entities e
+            ON e.stash_root = target.stash_root
+           AND e.entity_norm = target.entity_norm
+           AND e.file_path  != target.file_path
+          JOIN graph_files gf
+            ON gf.stash_root = e.stash_root
+           AND gf.file_path = e.file_path
+           AND gf.body_hash = e.body_hash
+        WHERE target.file_path  = ?
+          AND target.stash_root = ?
+        GROUP BY gf.file_path
+        ORDER BY shared DESC, gf.file_path ASC
+        LIMIT ?`)
+        .all(filePath, stashRoot, effectiveLimit);
     if (candidateRows.length === 0)
         return [];
     const candidatePaths = candidateRows.map((r) => r.file_path);

package/dist/indexer/graph/graph-extraction.js

@@ -971,6 +971,11 @@ async function extractGraphForSingleFileRevision(db, stashRoot, filePath, opts)
         if (err instanceof ConfigError)
             throw err;
         rethrowIfTestIsolationError(err);
+        // A genuine extraction/write failure, distinct from the deliberate
+        // "nothing to do" skips above (missing file, empty body, no model). Warn
+        // so it is visible instead of looking identical to a no-op skip; the
+        // entry stays queued and is retried on the next pass.
+        warn(`graph extraction: failed to extract graph for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
         return { written: false };
     }
     finally {
@@ -1057,12 +1062,17 @@ export function collectEligibleFiles(stashRoot, includeTypes = [...DEFAULT_GRAPH
         const dir = path.join(stashRoot, stashDir);
         if (!fs.existsSync(dir))
             continue;
-        for (const filePath of walkMarkdownFiles(dir)) {
+        const walked = walkMarkdownFiles(dir);
+        if (!walked.complete) {
+            warn(`graph extraction: directory scan under ${dir} is incomplete — some files may be missing`);
+        }
+        for (const filePath of walked.files) {
             let raw;
             try {
                 raw = fs.readFileSync(filePath, "utf8");
             }
-            catch {
+            catch (err) {
+                warn(`graph extraction: failed to read candidate file ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
                 continue;
             }
             const parsed = parseFrontmatter(raw);

package/dist/indexer/indexer.js

@@ -208,7 +208,7 @@ async function runEmbeddingPhase(ctx) {
  * verify event.
  */
 async function runFinalizePhase(ctx, deferredUpdateTransaction) {
-    const { db, config, sources, sourceDirs, isIncremental, stashDir, signal, onProgress } = ctx;
+    const { db, config, sources, sourceDirs, stashDir, signal, onProgress } = ctx;
     ctx.timing.tFinalizeStart = Date.now();
     // `upsertEntry` and every canonical delete own their FTS projection. This is
     // an observation point, not a second materialization pass.

package/dist/indexer/lookup/adapter-concept-owner.js

@@ -4,8 +4,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { adapterForId } from "../../core/adapter/registry.js";
-import { isWithin } from "../../core/common.js";
-import { UsageError } from "../../core/errors.js";
+import { compareCodePoints, hasErrnoCode, isWithin } from "../../core/common.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
 import { resolveUniqueWorkflowSource, workflowNameForConceptId, } from "../../workflows/source-files.js";
 import { buildFileContext } from "../walk/file-context.js";
@@ -14,7 +14,7 @@ export class AdapterConceptOwnershipError extends UsageError {
 }
 export class AdapterConceptCollisionError extends AdapterConceptOwnershipError {
     constructor(adapterId, conceptId, paths) {
-        const sorted = [...paths].sort(comparePaths);
+        const sorted = [...paths].sort(compareCodePoints);
         super(`Adapter "${adapterId}" has multiple physical owners for "${conceptId}": ${sorted.join(", ")}.`, "RESOURCE_ALREADY_EXISTS");
         this.name = "AdapterConceptCollisionError";
         Object.setPrototypeOf(this, new.target.prototype);
@@ -132,8 +132,14 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
     try {
         realRoot = fs.realpathSync(sourcePath);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        // Genuinely absent — "no owner" is correct. Any other failure (e.g.
+        // EACCES) is not "doesn't exist"; treating it as such would report a
+        // legitimate bundle root as owning nothing instead of raising the
+        // unreadable-directory error.
+        if (hasErrnoCode(error, "ENOENT"))
+            return undefined;
+        throw new ConfigError(`Unable to read bundle directory at "${sourcePath}".`, "STASH_DIR_UNREADABLE");
     }
     const component = componentFor(sourcePath, adapterId);
     const ownersByIdentity = new Map();
@@ -165,7 +171,7 @@ export function resolveAdapterConceptOwner(sourcePath, adapterId, conceptId) {
     const inspected = [
         ...new Map(spellings.map((candidate) => [`${path.resolve(candidate.path)}\0${candidate.conceptId}`, candidate])).values(),
     ]
-        .sort((left, right) => comparePaths(left.path, right.path))
+        .sort((left, right) => compareCodePoints(left.path, right.path))
         .flatMap((candidate) => {
         const owner = inspectCandidate(sourcePath, realRoot, adapterId, candidate);
         return owner ? [owner] : [];
@@ -195,6 +201,3 @@ export function indexedPathMatchesOwner(indexedPath, owner) {
         return false;
     }
 }
-function comparePaths(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

package/dist/indexer/passes/memory-inference.js

@@ -353,12 +353,17 @@ export function collectPendingMemories(stashRoot) {
     if (!fs.existsSync(memoriesDir))
         return [];
     const out = [];
-    for (const filePath of walkMarkdownFiles(memoriesDir)) {
+    const walked = walkMarkdownFiles(memoriesDir);
+    if (!walked.complete) {
+        warn(`memory inference: directory scan under ${memoriesDir} is incomplete — some memories may be missing`);
+    }
+    for (const filePath of walked.files) {
         let raw;
         try {
             raw = fs.readFileSync(filePath, "utf8");
         }
-        catch {
+        catch (err) {
+            warn(`memory inference: failed to read candidate memory ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
         const parsed = parseFrontmatter(raw);

package/dist/indexer/scan/drain-dir.js

@@ -28,6 +28,7 @@
  */
 import path from "node:path";
 import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
+import { compareCodePoints } from "../../core/common.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
 import { resolveUniqueWorkflowSource, WorkflowSourceRejectionError, workflowNameForSourcePath, } from "../../workflows/source-files.js";
 import { compileWorkflowSource } from "../../workflows/source-ir/compile.js";
@@ -61,7 +62,7 @@ export function drainDirDocuments(adapter, component, fileContexts) {
                 workflowLookups.set(canonicalName, workflowName);
         }
     }
-    for (const [canonicalName, workflowName] of [...workflowLookups].sort(([left], [right]) => comparePaths(left, right))) {
+    for (const [canonicalName, workflowName] of [...workflowLookups].sort(([left], [right]) => compareCodePoints(left, right))) {
         try {
             resolveUniqueWorkflowSource(component.root, adapter.id, workflowName);
         }
@@ -100,9 +101,6 @@ export function drainDirDocuments(adapter, component, fileContexts) {
     }
     return { entries, warnings, hashByFile, conceptIdByFile, rejectedPaths, rejectedConceptIds };
 }
-function comparePaths(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}
 /**
  * `(stashRoot, files) → StashFile` drop-in for the deleted flat-walk matcher
  * pass (F4a M-core-3): builds a FileContext per file and drains them through the

package/dist/indexer/search/db-search.js

@@ -545,9 +545,9 @@ async function enumerateEntries(opts) {
  * includes structured fields and bounded adapter content), while the
  * enumerate path's pool is `getAllEntries` for the type, independent of query
  * text. A derived twin sharing no indexed token with the query is therefore an
- * enumerate-path candidate but never a scored-path candidate — see
- * tests/fixtures/goldens/filter-behavior/scored-vs-enumerate.json, which pins
- * that (retained) divergence.
+ * enumerate-path candidate but never a scored-path candidate. (A golden
+ * fixture used to pin that divergence; the golden suites were deleted in
+ * 0.9.8, so this comment is now the record of it.)
  *
  * `inheritDerivedTwinBeliefStates` is idempotent, so running it here is safe on
  * the scored path, which must ALSO call it before ranking (the belief-state

package/dist/indexer/search/fts-query.js

@@ -1,17 +1,6 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Pure FTS5 query planning and ref-query helpers.
- *
- * The lexical planner transforms a raw user query into bounded FTS5-safe
- * MATCH expressions. It touches no database state, so it is unit-testable
- * with zero DB setup.
- * `parseRefPrefixQuery` is the one non-FTS helper: it decides whether a raw
- * query should bypass FTS entirely (SPEC-4 ref-prefix enumeration).
- */
-/** Maximum number of distinct lexical terms one query may execute. */
-export const MAX_LEXICAL_QUERY_TOKENS = 16;
 const UNICODE_TOKEN = /[\p{L}\p{N}]+/gu;
 function quoteToken(token) {
     return `"${token}"`;
@@ -24,8 +13,16 @@ function prefixToken(token) {
  *
  * Tokenization follows the useful portion of SQLite FTS5's `unicode61`
  * tokenizer (Unicode letters and numbers). Quoting every term makes FTS
- * operators ordinary searchable words. Tokens are normalized, deduplicated
- * case-insensitively, and capped before any SQL executes.
+ * operators ordinary searchable words. Tokens are normalized and deduplicated
+ * case-insensitively.
+ *
+ * There is deliberately NO cap on token count. `MAX_LEXICAL_QUERY_TOKENS = 16`
+ * used to truncate here, silently: a query past 16 unique tokens searched only
+ * its first 16, dropping the tail — which for natural-language input is
+ * usually where the discriminating words are. It was unexplained in both the
+ * code and the commit that introduced it, unreachable from any flag, config
+ * key, or env var, and the user was never told their query had been altered.
+ * A wrong answer delivered silently is worse than a slow one.
  */
 export function buildLexicalQueryPlan(query) {
     const tokens = [];
@@ -38,8 +35,6 @@ export function buildLexicalQueryPlan(query) {
             continue;
         seen.add(key);
         tokens.push(token);
-        if (tokens.length === MAX_LEXICAL_QUERY_TOKENS)
-            break;
     }
     const exact = tokens.map(quoteToken).join(" ");
     const prefixTokens = tokens.map(prefixToken);