@massa-ai/core 1.14.0 → 1.16.0

package/dist/services/search/index-admin.d.ts

@@ -0,0 +1,130 @@
+/**
+ * index-admin — the index administration capability (design.md §4.1).
+ *
+ * PR-B capability module. Takes `IndexAdminDeps` — the collaborators §2.1 shows
+ * these surfaces read — in place of the facade instance they used to receive as
+ * `rlm` (GMS-03 AC-1). The file has never heard of ContextualSearchRLM, so it
+ * contributes nothing to the root's foreign reach (G-HUB, design.md §3.4).
+ *
+ * `await rlm.ensureInitialized()` is **gone from the three bodies that had it**.
+ * It was the literal first statement of `clearProjectIndex`, `getProjectStats`
+ * and `warmupCache`, and it is now the literal first statement of the three
+ * facade methods that call them — design.md §4.5(b) and the §4.3 sketch. Order is
+ * unchanged: the root awaits init, *then* assembles the deps record, so the
+ * fields this module reads are populated exactly as before. `getAnalytics` never
+ * called it and still does not; adding one would be a behavior change, not a
+ * tidy-up, and it is also the one delegate left with no `await` ahead of it,
+ * which is what makes it this task's blind-recursion mutation subject
+ * (tasks.md, "The mutation shape matters").
+ *
+ * LATE-BIND (design.md §4.3.1): the root assembles this record per call from its
+ * current field values. Nothing here captures a collaborator.
+ *
+ * Behavior is byte-preserved from rlm-admin.ts: the bodies moved verbatim with
+ * `rlm.` → `deps.` and the hoisted init statement removed.
+ */
+import type { SearchResult } from "@massa-ai/shared";
+import { SearchAnalytics } from "./search-analytics.js";
+import type { SearchAnalyticsPg } from "./search-analytics-pg.js";
+import type { FileFilterCache } from "./file-filter-cache.js";
+import type { getKeywordSearch } from "../../data/keyword/keyword-search-factory.js";
+import type { getVectorStore } from "../../data/vector/vector-store-factory.js";
+import type { getSearchCache } from "./cache-factory.js";
+/**
+ * The narrow dependency record for this module (design.md §4.4) — exactly the
+ * collaborators §2.1 shows these surfaces read, minus `ensureInitialized`, which
+ * the root hoisted.
+ *
+ * The three stores are required and carry the root's own field types: their
+ * originals were bare `rlm.<store>.<method>` reads off definite-assigned fields
+ * with no fallback, so an absent store must keep throwing exactly where it did.
+ * They are structural (`Awaited<ReturnType<typeof …>>`), which is why they never
+ * touch the hub metric — see the two nominal fields below, which do not either,
+ * but for reasons that had to be measured rather than assumed.
+ *
+ * **`search` is a re-entrant seam, not a store.** design.md §4.1's "injected
+ * collaborators" column says "six stores + `fileFilterCache`", which is both an
+ * over-count (three stores are read, not six) and an omission: §2.1 records
+ * `warmupCacheImpl` reading the facade's `search` **method**, and §12 item 4
+ * orders index-admin *before* hybrid-search, so at T12 there is no
+ * `hybrid-search.search` to import — the collaborator is the root's own method,
+ * reached back through a per-call arrow wrapper exactly as `IndexerDeps` reaches
+ * `indexFile` / `indexProject` at T10.
+ *
+ * It is load-bearing, and the sensor for it is new rather than pre-existing.
+ * Measured: `rlm.search` is stubbed at **7 instance-method sites** —
+ * `search-facade-admin.test.ts:124,137,148` and
+ * `contextual-search-rlm-coverage.test.ts:382,395,407,416` — as bare assignments
+ * with no `as any` cast, so the established PATCHABLE regex does not find them
+ * (the same shape T10 registered for `indexFile`/`indexProject`, and `git grep
+ * -E` cannot even express the sweep: POSIX ERE has no `\s`, so the first pass
+ * silently reported zero). Every one of those 7 sites is exercised *through*
+ * `warmupCache`, and they are also the *only* 7 calls to `warmupCache` in the
+ * suite — so **no pre-existing test ever runs `warmupCache` against the real
+ * `search`**, and all 7 assign before they call. That makes a bare
+ * `search: this.search` reference or a `.bind(this)` at assembly time invisible
+ * to the entire pre-existing suite: both would still capture the stub, because a
+ * per-call assembly happens after the assignment. `index-admin-late-bind.test.ts`
+ * test 4 is the only thing in the repository that can see the difference.
+ *
+ * **Neither nominal field fires T10's seventh defect, and both reasons are
+ * measured.** That defect — a bare nominal type declared inside
+ * `services/search/` being captured as a binding by `search-hub-metric.ts:139`'s
+ * `([A-Za-z0-9_]+)\s*:\s*<Type>\b` — took `IndexManager`'s `maxForeignReach` from
+ * 0 to 4 at T10. tasks.md T12's row predicts both fields here "will" fire because
+ * they are required rather than optional (T11's `?` guard). Measured, they do not:
+ *
+ * - `analytics` cannot fire at all. `SearchAnalytics` is a **stripped re-export
+ *   alias** (`search-analytics.ts` is one `export … from` line, and
+ *   `stripNonCode` deletes exactly those), so it never enters `declaredIn` and
+ *   never appears in the metric's output. `SearchAnalyticsPg` *is* declared, but
+ *   only ever occurs here after `| `, never in `<name>:` position, so no binding
+ *   is captured. And independently: `getAnalytics` returns `deps.analytics`
+ *   **whole** and never dereferences it, so `perModule` gains nothing either way
+ *   — the same route by which T11's `indexManager` and T7's `_rlm` contributed
+ *   zero. It is therefore **deliberately not `Pick<>`-narrowed**, against the
+ *   row's instruction: narrowing would also break `type-check`, because the value
+ *   is returned through the root's public `getAnalytics(): SearchAnalytics |
+ *   SearchAnalyticsPg`, a compatibility surface for 24 importers. Same reason the
+ *   `Pick<>` decision did not generalise to T11's seam field.
+ * - `fileFilterCache` *is* captured and *is* dereferenced once
+ *   (`invalidateProject`), so un-narrowed it moves `FileFilterCache` from foreign
+ *   0 / reach 0 to foreign 1 / reach **1**. That is under `MAX_FOREIGN_REACH`
+ *   (3), so unlike T10's reach-4 case it produces **no second G-HUB violation**
+ *   and would not have made T14's gate unclosable. The `Pick<>` below is kept
+ *   because §4.4 says a record holds exactly what is read and it is the honest
+ *   type — **not** because a sensor fired. Both variants were measured by scratch
+ *   simulation before this file was applied.
+ */
+export interface IndexAdminDeps {
+    vectorStore: Awaited<ReturnType<typeof getVectorStore>>;
+    keywordSearch: Awaited<ReturnType<typeof getKeywordSearch>>;
+    searchCache: Awaited<ReturnType<typeof getSearchCache>>;
+    fileFilterCache: Pick<FileFilterCache, "invalidateProject">;
+    analytics: SearchAnalytics | SearchAnalyticsPg;
+    /**
+     * The root's own `search`, as a per-call arrow wrapper that re-reads
+     * `this.search` at **call** time. Not `.bind(this)` and not a bare method
+     * reference: both resolve the method at *assembly* time, and see the 7 stub
+     * sites above for why that is the failure this record exists to prevent.
+     * Typed with exactly the options `warmupCache` passes (§4.4), not the facade's
+     * full option bag.
+     */
+    search: (query: string, projectId: string, options?: {
+        maxResults?: number;
+        minScore?: number;
+    }) => Promise<SearchResult[]>;
+}
+export declare function clearProjectIndex(deps: IndexAdminDeps, projectId: string): Promise<{
+    deleted: number;
+}>;
+export declare function getProjectStats(deps: IndexAdminDeps, projectId: string): Promise<{
+    totalDocuments: number;
+    totalSize: number;
+}>;
+export declare function warmupCache(deps: IndexAdminDeps, projectId: string, _projectPath: string, customQueries?: string[]): Promise<{
+    queriesWarmed: number;
+    errors: number;
+}>;
+export declare function getAnalytics(deps: IndexAdminDeps): SearchAnalytics | SearchAnalyticsPg;
+//# sourceMappingURL=index-admin.d.ts.map

package/dist/services/search/index-admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-admin.d.ts","sourceRoot":"","sources":["../../../src/services/search/index-admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IACxD,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC;IAC5D,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IACxD,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAC5D,SAAS,EAAE,eAAe,GAAG,iBAAiB,CAAC;IAC/C;;;;;;;OAOG;IACH,MAAM,EAAE,CACN,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KACjD,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC9B;AAID,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAuB9B;AAID,wBAAsB,eAAe,CACnC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IACT,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAED;AAID,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDpD;AAID,wBAAgB,YAAY,CAC1B,IAAI,EAAE,cAAc,GACnB,eAAe,GAAG,iBAAiB,CAErC"}

package/dist/services/search/{rlm-admin.js → index-admin.js}

@@ -1,21 +1,39 @@
 /**
- * rlm-admin — admin/stats delegates for ContextualSearchRLM.
+ * index-admin — the index administration capability (design.md §4.1).
  *
- * Extracted (M14 Phase 3, T3.3) from contextual-search-rlm.ts. Behavior is
- * byte-preserved: bodies moved verbatim with `this` → `rlm`.
+ * PR-B capability module. Takes `IndexAdminDeps` — the collaborators §2.1 shows
+ * these surfaces read — in place of the facade instance they used to receive as
+ * `rlm` (GMS-03 AC-1). The file has never heard of ContextualSearchRLM, so it
+ * contributes nothing to the root's foreign reach (G-HUB, design.md §3.4).
+ *
+ * `await rlm.ensureInitialized()` is **gone from the three bodies that had it**.
+ * It was the literal first statement of `clearProjectIndex`, `getProjectStats`
+ * and `warmupCache`, and it is now the literal first statement of the three
+ * facade methods that call them — design.md §4.5(b) and the §4.3 sketch. Order is
+ * unchanged: the root awaits init, *then* assembles the deps record, so the
+ * fields this module reads are populated exactly as before. `getAnalytics` never
+ * called it and still does not; adding one would be a behavior change, not a
+ * tidy-up, and it is also the one delegate left with no `await` ahead of it,
+ * which is what makes it this task's blind-recursion mutation subject
+ * (tasks.md, "The mutation shape matters").
+ *
+ * LATE-BIND (design.md §4.3.1): the root assembles this record per call from its
+ * current field values. Nothing here captures a collaborator.
+ *
+ * Behavior is byte-preserved from rlm-admin.ts: the bodies moved verbatim with
+ * `rlm.` → `deps.` and the hoisted init statement removed.
  */
 import { logger } from "@massa-ai/shared";
 // ── clearProjectIndex ────────────────────────────────────────────────────────
-export async function clearProjectIndexImpl(rlm, projectId) {
-    await rlm.ensureInitialized();
+export async function clearProjectIndex(deps, projectId) {
     try {
         const [deleted, keywordDeleted] = await Promise.all([
-            rlm.vectorStore.deleteByProject(projectId),
-            rlm.keywordSearch.deleteByProject(projectId),
+            deps.vectorStore.deleteByProject(projectId),
+            deps.keywordSearch.deleteByProject(projectId),
         ]);
         // Clear associated caches
-        await rlm.searchCache.invalidateProject(projectId);
-        rlm.fileFilterCache.invalidateProject(projectId);
+        await deps.searchCache.invalidateProject(projectId);
+        deps.fileFilterCache.invalidateProject(projectId);
         logger.info("Project index and caches cleared", {
             projectId,
             deleted,
@@ -31,13 +49,11 @@ export async function clearProjectIndexImpl(rlm, projectId) {
     }
 }
 // ── getProjectStats ──────────────────────────────────────────────────────────
-export async function getProjectStatsImpl(rlm, projectId) {
-    await rlm.ensureInitialized();
-    return rlm.vectorStore.getStats(projectId);
+export async function getProjectStats(deps, projectId) {
+    return deps.vectorStore.getStats(projectId);
 }
 // ── warmupCache ──────────────────────────────────────────────────────────────
-export async function warmupCacheImpl(rlm, projectId, _projectPath, customQueries) {
-    await rlm.ensureInitialized();
+export async function warmupCache(deps, projectId, _projectPath, customQueries) {
     logger.info("Starting cache warmup", { projectId });
     // Common search patterns based on file types and structure
     const commonQueries = customQueries || [
@@ -62,7 +78,7 @@ export async function warmupCacheImpl(rlm, projectId, _projectPath, customQuerie
     // Run searches in background to populate cache
     for (const query of commonQueries) {
         try {
-            await rlm.search(query, projectId, {
+            await deps.search(query, projectId, {
                 maxResults: 10,
                 minScore: 0.3,
             });
@@ -86,7 +102,7 @@ export async function warmupCacheImpl(rlm, projectId, _projectPath, customQuerie
     return { queriesWarmed, errors };
 }
 // ── getAnalytics ─────────────────────────────────────────────────────────────
-export function getAnalyticsImpl(rlm) {
-    return rlm.analytics;
+export function getAnalytics(deps) {
+    return deps.analytics;
 }
-//# sourceMappingURL=rlm-admin.js.map
+//# sourceMappingURL=index-admin.js.map

package/dist/services/search/index-admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-admin.js","sourceRoot":"","sources":["../../../src/services/search/index-admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAkG1C,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAoB,EACpB,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAClD,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,SAAS,CAAC;YAC3C,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,SAAS,CAAC;SAC9C,CAAC,CAAC;QAEH,0BAA0B;QAC1B,MAAM,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC,eAAe,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAElD,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE;YAC9C,SAAS;YACT,OAAO;YACP,cAAc;SACf,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAc,EAAE;YAC5D,SAAS;SACV,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACxB,CAAC;AACH,CAAC;AAED,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAoB,EACpB,SAAiB;IAKjB,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC9C,CAAC;AAED,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,SAAiB,EACjB,YAAoB,EACpB,aAAwB;IAExB,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IAEpD,2DAA2D;IAC3D,MAAM,aAAa,GAAG,aAAa,IAAI;QACrC,gBAAgB;QAChB,eAAe;QACf,iBAAiB;QACjB,YAAY;QACZ,OAAO;QACP,eAAe;QACf,QAAQ;QACR,UAAU;QACV,OAAO;QACP,OAAO;QACP,YAAY;QACZ,gBAAgB;QAChB,YAAY;QACZ,YAAY;QACZ,OAAO;KACR,CAAC;IAEF,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,+CAA+C;IAC/C,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE;gBAClC,UAAU,EAAE,EAAE;gBACd,QAAQ,EAAE,GAAG;aACd,CAAC,CAAC;YACH,aAAa,EAAE,CAAC;YAEhB,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAc,EAAE;gBAC7D,KAAK;gBACL,SAAS;aACV,CAAC,CAAC;YACH,MAAM,EAAE,CAAC;QACX,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE;QACpC,SAAS;QACT,aAAa;QACb,MAAM;QACN,YAAY,EAAE,aAAa,CAAC,MAAM;KACnC,CAAC,CAAC;IAEH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC;AAED,gFAAgF;AAEhF,MAAM,UAAU,YAAY,CAC1B,IAAoB;IAEpB,OAAO,IAAI,CAAC,SAAS,CAAC;AACxB,CAAC"}

package/dist/services/search/project-indexer.d.ts

@@ -0,0 +1,159 @@
+/**
+ * project-indexer — the project indexing capability (design.md §4.1).
+ *
+ * PR-B capability module. Takes `IndexerDeps` — the collaborators §2.1 shows
+ * these surfaces read — in place of the facade instance they used to receive as
+ * `rlm` (GMS-03 AC-1). The file has never heard of ContextualSearchRLM, so it
+ * contributes nothing to the root's foreign reach (G-HUB, design.md §3.4).
+ *
+ * `await rlm.ensureInitialized()` is **gone from every body here**. It was the
+ * literal first statement of `checkSearchAdmission`, `indexProjectInternal` and
+ * `ensureFreshIndex`, and it is now the literal first statement of the three
+ * facade methods that call them — design.md §4.5(b) and the §4.3 sketch. Order
+ * is unchanged: the root awaits init, *then* assembles the deps record, so the
+ * fields this module reads are populated exactly as before. `indexFile` never
+ * called it and still does not; its callers init first, as they always did.
+ *
+ * `ensureInitializedImpl` did **not** come here. It read 8 facade members, and
+ * 8 > G-HUB's ceiling of 3, so anywhere outside the root it fails the gate
+ * permanently. Its body is now the content of
+ * `ContextualSearchRLM.ensureInitialized()` (tasks.md T10, design.md §4.1's
+ * omission note). That is why rlm-indexing.ts dies whole rather than surviving
+ * as a one-function husk.
+ *
+ * LATE-BIND (design.md §4.3.1): the root assembles this record per call from its
+ * current field values. Nothing here captures a collaborator.
+ *
+ * Behavior is byte-preserved from rlm-indexing.ts: the bodies moved verbatim
+ * with `rlm.` → `deps.` and the hoisted init statement removed.
+ */
+import type { IndexManager } from "./index-manager.js";
+import type { getKeywordSearch } from "../../data/keyword/keyword-search-factory.js";
+import type { getVectorStore } from "../../data/vector/vector-store-factory.js";
+import type { getSearchCache } from "./cache-factory.js";
+import type { getSymbolRepository } from "../../data/symbol/symbol-repository-factory.js";
+export type IndexProjectOptions = {
+    onProgress?: (current: number, total: number) => void;
+};
+export type IndexProjectResult = {
+    filesIndexed: number;
+    chunksIndexed: number;
+    errors: number;
+};
+export type EnsureFreshIndexOptions = {
+    allowFullReindex?: boolean;
+    maxSyncFiles?: number;
+};
+export type EnsureFreshIndexResult = {
+    wasStale: boolean;
+    reindexed: boolean;
+    reason?: string;
+    deferred?: boolean;
+    filesPending?: number;
+};
+export type SearchAdmissionResult = {
+    admitted: boolean;
+    error?: string;
+    stale?: {
+        reason: string;
+        modifiedFiles?: number;
+        newFiles?: number;
+        deletedFiles?: number;
+    };
+};
+/**
+ * The narrow dependency record for this module (design.md §4.4) — exactly the
+ * collaborators §2.1 shows these surfaces read, minus the three that the root
+ * absorbed (`ensureInitialized` is hoisted; `initialized`, `injectedDeps` and
+ * `analytics` were `ensureInitializedImpl`'s alone).
+ *
+ * The five stores are required and carry the root's own field types: their
+ * originals were bare `rlm.<store>.<method>` reads off definite-assigned fields
+ * with no fallback, so an absent store must keep throwing exactly where it did.
+ * Contrast `SessionBiasDeps`, whose fields are optional because its originals
+ * read `rlm.injectedDeps?.x ?? getFactory()`.
+ *
+ * **`indexFile` and `indexProject` are re-entrant seams, not stores, and they
+ * are the part design.md §4.1's "injected collaborators" column omitted** —
+ * the same class of omission as `ensureInitializedImpl`, and §2.1 lists both
+ * members, so §4.4's rule already places them here. They are load-bearing:
+ * `search-facade-indexing.test.ts` stubs `rlm.indexFile` at :377, :402, :537, :572, :609
+ * and `rlm.indexProject` at :335 — **6 instance-method stub sites** — and every
+ * one is exercised *through* `ensureFreshIndex` or `indexProjectInternal`. A
+ * module-local call would make all six silently ineffective while the suite
+ * stayed green, which is LATE-BIND's exact failure mode. So the root supplies
+ * per-call arrow wrappers whose bodies re-read `this.<method>` at call time.
+ *
+ * `indexProject` is deliberately **not** the module function below. It is the
+ * root's public locked path — `assertParserReadyForIndexing()` then
+ * `runWithIndexLock(ContextualSearchRLM.indexingLocks, …)` — and that lock map
+ * is class state the capability modules may not import. `ensureFreshIndex`'s
+ * full-reindex branch needs the *locked* path, so calling an unlocked
+ * module-local namesake would drop the mutex silently. Hence the module
+ * function is `indexProjectInternal`, one name, one meaning, in one file.
+ */
+export interface IndexerDeps {
+    /**
+     * Narrowed to the four methods this module calls, and the narrowing is
+     * load-bearing rather than tidy. `IndexManager` is declared **inside** the
+     * G-HUB-gated directory, and the metric's annotation pattern is
+     * `([A-Za-z0-9_]+)\s*:\s*<Type>\b` — which matches an *interface field
+     * declaration*, not just a parameter. Typing this `indexManager: IndexManager`
+     * therefore attributed all four `deps.indexManager.<method>` reads to
+     * `IndexManager` and took its `maxForeignReach` from **0 to 4**, a second
+     * G-HUB violation where the tree had exactly one, which would have made T14's
+     * gate unclosable. Measured at T10, not predicted.
+     *
+     * `SessionBiasDeps` and `HybridSearchDeps` never hit this: their fields are
+     * `Pick<…>` / `Awaited<ReturnType<…>>`, and their collaborators are declared
+     * outside this directory. `IndexManager` is the first collaborator that is
+     * both a bare nominal type and declared under `services/search/`.
+     *
+     * **The same trap is waiting at T12 (`fileFilterCache: FileFilterCache`,
+     * `analytics: SearchAnalytics | SearchAnalyticsPg`) and T13
+     * (`queryUnderstanding: QueryUnderstandingService`)** — all three types are
+     * declared in this directory. Narrow those fields the same way.
+     */
+    indexManager: Pick<IndexManager, "getIndexMetadata" | "isIndexStale" | "getFilesToReindex" | "updateIndexMetadata">;
+    symbolRepo: Awaited<ReturnType<typeof getSymbolRepository>>;
+    keywordSearch: Awaited<ReturnType<typeof getKeywordSearch>>;
+    vectorStore: Awaited<ReturnType<typeof getVectorStore>>;
+    searchCache: Awaited<ReturnType<typeof getSearchCache>>;
+    /** The root's `indexFile` method, re-resolved through `this` on every call. */
+    indexFile: (filePath: string, projectId: string, projectRoot: string, centralityMap?: Map<string, number>) => Promise<{
+        chunks: number;
+    }>;
+    /** The root's `indexProject` method — the *locked* path, not the body below. */
+    indexProject: (projectPath: string, projectId: string, options?: IndexProjectOptions) => Promise<IndexProjectResult>;
+}
+/**
+ * Per-project queue mutex: serializes concurrent indexing for the same project.
+ *
+ * Pattern: each caller chains its lock after the current tail, then waits for
+ * the previous lock before proceeding. This guarantees correct ordering for any
+ * number of concurrent callers (3+), unlike a simple check-and-set.
+ *
+ *   A sets map[proj] = lock_A, awaits null  → starts immediately
+ *   B sets map[proj] = lock_B, awaits lock_A → waits for A
+ *   C sets map[proj] = lock_C, awaits lock_B → waits for B
+ *   A finishes → releases lock_A → B starts
+ *   B finishes → releases lock_B → C starts
+ *   C finishes → map[proj] === lock_C, so we clean up the entry
+ *
+ * The `try { await work() } finally { delete-if-still-owner; releaseLock() }`
+ * shape is load-bearing: `releaseLock()` MUST run even when `work` throws, or
+ * the lock leaks and subsequent callers hang (BUG-SYN-4).
+ *
+ * `work` is `() => this._indexProjectInternal(...)` in the caller — a lambda
+ * that captures virtual dispatch through `this`, so test monkey-patches on the
+ * instance still route. Do NOT inline a direct call to a module function here.
+ */
+export declare function runWithIndexLock<T>(lockMap: Map<string, Promise<void>>, projectId: string, work: () => Promise<T>): Promise<T>;
+export declare function indexProjectInternal(deps: IndexerDeps, projectPath: string, projectId: string, options?: IndexProjectOptions): Promise<IndexProjectResult>;
+export declare function ensureFreshIndex(deps: IndexerDeps, projectId: string, projectPath: string, options?: EnsureFreshIndexOptions): Promise<EnsureFreshIndexResult>;
+export declare function checkSearchAdmission(deps: IndexerDeps, projectId: string, projectPath?: string): Promise<SearchAdmissionResult>;
+export declare function indexFile(deps: IndexerDeps, filePath: string, projectId: string, projectRoot: string, centralityMap?: Map<string, number>): Promise<{
+    chunks: number;
+}>;
+export declare function loadGitignore(projectPath: string): Promise<import("ignore").Ignore>;
+//# sourceMappingURL=project-indexer.d.ts.map

package/dist/services/search/project-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-indexer.d.ts","sourceRoot":"","sources":["../../../src/services/search/project-indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAaH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAM1F,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,EAAE,IAAI,CAChB,YAAY,EACZ,kBAAkB,GAAG,cAAc,GAAG,mBAAmB,GAAG,qBAAqB,CAClF,CAAC;IACF,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC;IAC5D,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC;IAC5D,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IACxD,WAAW,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IACxD,+EAA+E;IAC/E,SAAS,EAAE,CACT,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjC,gFAAgF;IAChF,YAAY,EAAE,CACZ,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAID,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAuH7B;AAID,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAoLjC;AAID,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,qBAAqB,CAAC,CA4BhC;AAID,wBAAsB,SAAS,CAC7B,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAyD7B;AAID,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,oCAEhD"}