@fenglimg/fabric-server 2.3.0-rc.3 → 2.3.0-rc.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { FabExtractKnowledgeInput, FabExtractKnowledgeOutput, FabReviewInput, FabReviewOutput, FabPendingInput, FabPendingOutput } from '@fenglimg/fabric-shared/schemas/api-contracts';
-import { EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, RecallScore, RecallScoreBreakdown, LedgerEntry, AgentsMeta } from '@fenglimg/fabric-shared';
+import { RuleDescription, EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, RecallScore, RecallScoreBreakdown, LedgerEntry, AgentsMeta } from '@fenglimg/fabric-shared';
 import { PayloadGuardOptions } from '@fenglimg/fabric-shared/node/mcp-payload-guard';
 
 interface InFlightTracker {
@@ -33,6 +33,8 @@ type DoctorHealth = {
     };
 };
 
+declare function extractRuleDescription(source: string): RuleDescription | undefined;
+
 interface AlwaysActiveBody {
     /** store-qualified id (`<alias>:<stableId>`). */
     stable_id: string;
@@ -78,6 +80,16 @@ interface KnowledgeCensus {
  */
 declare function buildKnowledgeCensus(projectRoot: string): Promise<KnowledgeCensus>;
 declare function buildAlwaysActiveBodies(projectRoot: string): Promise<AlwaysActiveBody[]>;
+interface StoreCanonicalEntry {
+    stableId: string;
+    qualifiedId: string;
+    file: string;
+    type: string;
+    layer: "team" | "personal";
+    body: string;
+    description: NonNullable<ReturnType<typeof extractRuleDescription>>;
+}
+declare function collectStoreCanonicalEntries(projectRoot: string): Promise<StoreCanonicalEntry[]>;
 
 interface UnboundProjectViolation {
     /** The store already bound as the active write target. */
@@ -196,6 +208,11 @@ type CiteCoverageReport = {
         uncorrelatable_edits?: number;
         recall_backed_edits?: number;
         recall_coverage_rate?: number | null;
+        recall_diagnostics?: {
+            recalls_in_window: number;
+            recall_sessions: number;
+            recall_sessions_correlated: number;
+        };
         exposed_and_mutated?: {
             count: number;
             ids?: string[];
@@ -541,6 +558,20 @@ interface Embedder {
     embed(texts: string[]): Promise<number[][]>;
 }
 declare const OPTIONAL_EMBED_PACKAGE = "fastembed";
+/**
+ * Is the optional embedder package resolvable FROM THE SERVER'S module location —
+ * i.e. from exactly where `loadEmbedder`'s dynamic `import()` will look for it?
+ *
+ * This is the honest "is fastembed installed?" probe. The naive alternative — a
+ * `createRequire(import.meta.url)` check run inside the CLI package — answers from
+ * the WRONG base: in a pnpm / non-hoisted layout (or a dev-linked global install)
+ * fastembed lives under the SERVER's `node_modules` (it is the server's
+ * optionalDependency), so the CLI cannot resolve it even though the server — the
+ * only code that actually imports it — can. That mismatch made `fabric info
+ * --recall` report "not installed" on a perfectly working setup. Callers that
+ * surface embedder availability MUST use this server-anchored probe.
+ */
+declare function isEmbedderResolvable(): boolean;
 declare function defaultEmbedCacheDir(): string;
 /**
  * Lazy-load the optional fastembed embedder, pinned to CPU + cache-only. Returns
@@ -680,6 +711,148 @@ declare const COLD_EVAL_RUBRIC: string;
  */
 declare function buildColdEvalBatch(candidates: ColdEvalCandidate[]): ColdEvalBatch;
 
+interface RelatedBrokenLink {
+    /** The entry (store-qualified id) that declared the `related` edge. */
+    source: string;
+    /** The unresolvable related value. */
+    target: string;
+}
+interface RelatedHubEntry {
+    stableId: string;
+    inDegree: number;
+}
+interface RelatedGraphInspection {
+    brokenLinks: RelatedBrokenLink[];
+    hubEntries: RelatedHubEntry[];
+    /** Total canonical entries scanned. */
+    totalEntries: number;
+}
+/** A single node fed into the pure graph builder. */
+interface RelatedGraphNode {
+    /** Store-qualified id (`<alias>:<stableId>`). */
+    qualifiedId: string;
+    /** The entry's declared `related` edges (frontmatter), if any. */
+    related?: string[];
+}
+/**
+ * Build the related-edge graph from a list of nodes and report broken links +
+ * hub ranking. Pure — no I/O — so the broken-link / in-degree logic can be
+ * tested with hand-built fixtures.
+ *
+ * A "broken link" is a `related` value that does not appear as any node's
+ * store-qualified id NOR bare stable_id in the corpus. Store-qualified
+ * references (`alias:id`) and bare references (`id`) both resolve, because the
+ * id index carries both forms for every node.
+ */
+declare function buildRelatedGraph(nodes: RelatedGraphNode[]): RelatedGraphInspection;
+/**
+ * Walk the store canonical corpus and build the related graph. Never throws —
+ * collectStoreCanonicalEntries degrades to [] when no store is in the read-set.
+ *
+ * Note: the previous (dead, never-wired) draft of this module re-parsed each
+ * entry's frontmatter via extractRuleDescription(entry.file) — passing a FILE
+ * PATH where a raw-markdown SOURCE was expected, which silently produced no
+ * edges. StoreCanonicalEntry already carries the parsed `description`, so we
+ * read `description.related` directly (the single source the recall path uses).
+ */
+declare function inspectRelatedGraph(projectRoot: string): Promise<RelatedGraphInspection>;
+
+interface StoreReachability {
+    uuid: string;
+    alias: string;
+    reachable: boolean;
+    reason?: string;
+}
+interface PrecheckResult {
+    stores: StoreReachability[];
+    allReachable: boolean;
+}
+declare function clearPrecheckCache(): void;
+/**
+ * Evaluate a single store directory's reachability. A store is reachable when
+ * BOTH hold:
+ *   1. The store directory exists on disk.
+ *   2. The directory contains either a `store.json` (valid JSON, local-only
+ *      store) OR a `.git/` subdirectory (git-cloned store).
+ *
+ * Pure (filesystem-only, no config resolution) so the rule is testable with a
+ * temp directory regardless of the machine's ~/.fabric layout.
+ */
+declare function evaluateStoreDir(storeDir: string, identity: {
+    uuid: string;
+    alias: string;
+}): StoreReachability;
+/**
+ * Check that every store in the project's read-set is reachable on disk.
+ * Results are cached for 60s (CACHE_TTL_MS). Call `clearPrecheckCache()` when a
+ * store mount / unmount operation invalidates the cache.
+ *
+ * `globalRoot` is injectable for hermetic tests; production callers use the
+ * resolved ~/.fabric root.
+ */
+declare function precheckStoreReachability(projectRoot: string, globalRoot?: string, now?: number): Promise<PrecheckResult>;
+
+interface ConsumptionLintConfig {
+    /** Rolling window in days (default 30). */
+    windowDays: number;
+    /** How many top-consumed entries to report (default 10). */
+    topN: number;
+    /** Minimum CORPUS size before the lint runs at all (fresh-install guard). */
+    minTotalEntries: number;
+    /**
+     * Data-maturity gate axis 1: minimum number of metrics windows (rows) that
+     * recorded ≥1 consumption counter before zero-consumed is trustworthy.
+     */
+    minConsumedWindows: number;
+    /**
+     * Data-maturity gate axis 2: minimum total consumption events in the window
+     * before zero-consumed is trustworthy.
+     */
+    minConsumedEvents: number;
+}
+interface ConsumptionEntry {
+    /** Store-qualified id (`<alias>:<stableId>`). */
+    stableId: string;
+    count: number;
+}
+interface ConsumptionInspection {
+    topConsumed: ConsumptionEntry[];
+    /**
+     * Corpus entries never consumed in the window. ALWAYS [] when the data is not
+     * mature (dataMature === false) — the gate suppresses the noisy signal.
+     */
+    zeroConsumed: string[];
+    /** Total corpus entries considered for the zero-consumed denominator. */
+    totalEntries: number;
+    /** Distinct entries with ≥1 consumption in the window. */
+    consumedEntries: number;
+    /** Number of metrics windows (rows) that carried ≥1 consumption counter. */
+    consumedWindows: number;
+    /** Sum of all consumption counts in the window. */
+    totalConsumedEvents: number;
+    /** True when both maturity axes clear their thresholds. */
+    dataMature: boolean;
+    windowDays: number;
+}
+/**
+ * Aggregate consumption from metrics rows against the canonical corpus id list.
+ * Pure — no I/O — so the windowing, prefix parsing, top-N ranking, zero-consumed
+ * computation, and the maturity gate are all testable with fixtures.
+ *
+ * @param rows           metrics.jsonl rows (any window/order)
+ * @param allQualifiedIds store-qualified ids of the canonical corpus
+ * @param now            current epoch ms (injected for deterministic windowing)
+ */
+declare function aggregateConsumption(rows: MetricsRow[], allQualifiedIds: string[], now: number, config?: Partial<ConsumptionLintConfig>): ConsumptionInspection;
+/**
+ * Read metrics.jsonl + the canonical corpus and aggregate consumption. Never
+ * throws — readMetrics returns [] on a missing ledger and collectStoreCanonical
+ * Entries returns [] when no store is in the read-set.
+ *
+ * `now` is injectable for deterministic tests.
+ */
+declare function inspectConsumption(projectRoot: string, config?: Partial<ConsumptionLintConfig>, now?: number): Promise<ConsumptionInspection>;
+
 type StoredEventLedgerEvent = EventLedgerEvent;
 type ReadEventLedgerOptions = {
     event_type?: EventLedgerEvent["event_type"];
@@ -974,4 +1147,4 @@ interface ShutdownHandlerDeps {
  */
 declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 
-export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, COLD_EVAL_RUBRIC, type CiteCoverageReport, type ColdEvalBatch, type ColdEvalCandidate, type ColdEvalVerdict, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type MetricCounterName, type MetricsRow, OPTIONAL_EMBED_PACKAGE, type PlanContextInput, type PlanContextResult, RETIRED_TOKENS, type RecallInput, type RecallResult, type RequirementProfile, type RetiredReferenceHit, type RetiredReferenceInspection, type RetiredToken, type SelectionTokenState, type ShutdownHandlerDeps, type SurfaceVerdict, type UnboundProjectViolation, type WhyNotSurfacedResult, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, bumpCounter, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, defaultEmbedCacheDir, detectUnboundProject, drainCounters, enrichDescriptions, explainWhyNotSurfaced, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, inspectRetiredReferences, lintConflicts, loadConflictEntries, loadEmbedder, pairSimilarity, planContext, readEmbedConfig, readEventLedger, readFusion, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, reviewPending, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };
+export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, COLD_EVAL_RUBRIC, type CiteCoverageReport, type ColdEvalBatch, type ColdEvalCandidate, type ColdEvalVerdict, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, type ConsumptionEntry, type ConsumptionInspection, type ConsumptionLintConfig, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type MetricCounterName, type MetricsRow, OPTIONAL_EMBED_PACKAGE, type PlanContextInput, type PlanContextResult, type PrecheckResult, RETIRED_TOKENS, type RecallInput, type RecallResult, type RelatedBrokenLink, type RelatedGraphInspection, type RelatedGraphNode, type RelatedHubEntry, type RequirementProfile, type RetiredReferenceHit, type RetiredReferenceInspection, type RetiredToken, type SelectionTokenState, type ShutdownHandlerDeps, type StoreCanonicalEntry, type StoreReachability, type SurfaceVerdict, type UnboundProjectViolation, type WhyNotSurfacedResult, aggregateConsumption, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, buildRelatedGraph, bumpCounter, clearPrecheckCache, collectStoreCanonicalEntries, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, defaultEmbedCacheDir, detectUnboundProject, drainCounters, enrichDescriptions, evaluateStoreDir, explainWhyNotSurfaced, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, inspectConsumption, inspectRelatedGraph, inspectRetiredReferences, isEmbedderResolvable, lintConflicts, loadConflictEntries, loadEmbedder, pairSimilarity, planContext, precheckStoreReachability, readEmbedConfig, readEventLedger, readFusion, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, reviewPending, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };

package/dist/index.js

@@ -1,7 +1,7 @@
 // src/index.ts
-import { existsSync as existsSync9 } from "fs";
-import { readFile as readFile20 } from "fs/promises";
-import { join as join25, resolve as resolve4 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { readFile as readFile21 } from "fs/promises";
+import { join as join26, resolve as resolve4 } from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -893,7 +893,7 @@ async function awaitFirstReconcileGate(timeoutMs = 5e3) {
 
 // src/services/extract-knowledge.ts
 import { existsSync as existsSync3 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { join as join7 } from "path";
 import {
   PROPOSED_REASON_DESCRIPTIONS_BY_LOCALE
@@ -901,6 +901,8 @@ import {
 import { hasSecrets, isPersonalScope, redactPii, resolveGlobalLocale } from "@fenglimg/fabric-shared";
 
 // src/services/cross-store-write.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile3 } from "fs/promises";
 import { join as join5 } from "path";
 import {
   STORE_LAYOUT,
@@ -916,6 +918,7 @@ import {
   PersonalScopeLeakError,
   StoreWriteTargetUnresolvedError
 } from "@fenglimg/fabric-shared/errors";
+import { withFileLock as withFileLock2 } from "@fenglimg/fabric-shared/node/atomic-write";
 function writeTargetUnresolved(scope, layer) {
   const actionHint = layer === "personal" ? "run `fabric install --global` to mint your personal store, then retry" : `mount + bind a shared store, then set an explicit route: \`fabric store switch-write <alias> --scope ${scope}\``;
   return new StoreWriteTargetUnresolvedError(
@@ -978,7 +981,7 @@ function resolveWriteScopeMeta(layer, projectRoot, semanticScope) {
 }
 
 // src/services/cross-store-recall.ts
-import { readFile as readFile3, stat } from "fs/promises";
+import { readFile as readFile4, stat } from "fs/promises";
 import { join as join6 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput2,
@@ -1350,7 +1353,7 @@ async function walkReadSetStoresUncached(snapshot) {
   const entries = await Promise.all(snapshot.refs.map(async (ref) => {
     let source;
     try {
-      source = await readFile3(ref.file, "utf8");
+      source = await readFile4(ref.file, "utf8");
     } catch {
       return null;
     }
@@ -1622,6 +1625,144 @@ function serializeBm25Model(model) {
 function rehydrateBm25Model(serialized) {
   return modelFromStats(serialized);
 }
+var SYNONYM_PAIRS = {
+  // Code / engineering actions
+  refactor: ["restructure", "rewrite", "redesign", "reorganize", "clean", "rework"],
+  optimize: ["improve", "speed-up", "tune", "accelerate", "perf", "performance"],
+  debug: ["fix", "troubleshoot", "diagnose", "investigate", "resolve", "correct"],
+  migrate: ["port", "move", "transfer", "upgrade", "transition", "convert"],
+  "set up": ["init", "initialize", "configure", "bootstrap", "install", "onboard"],
+  implement: ["add", "build", "create", "develop", "write", "introduce", "introduce"],
+  // Architecture / design
+  architecture: ["design", "structure", "layout", "organization", "pattern", "system"],
+  "data model": ["schema", "entity", "type", "structure", "contract", "shape"],
+  // Quality / correctness
+  test: ["verify", "validate", "assert", "check", "spec", "coverage"],
+  lint: ["check", "validate", "audit", "inspect", "analyze"],
+  // Communication / impact
+  documentation: ["docs", "readme", "guide", "spec", "explanation", "reference"],
+  decision: ["adr", "rationale", "why", "motivation", "reason", "trade-off"],
+  // Change management
+  release: ["deploy", "ship", "publish", "cut", "version", "tag"],
+  rollback: ["revert", "undo", "back-out", "backout", "restore"],
+  // Containers / infra
+  container: ["docker", "image", "oci", "cri-o"],
+  deploy: ["release", "rollout", "ship", "publish", "promote"],
+  // Project / process
+  on_boarding: ["getting-started", "quickstart", "newcomer", "new-hire", "first-time"],
+  best_practice: ["convention", "guideline", "standard", "rule", "recommendation"],
+  // Tech stacks
+  api: ["endpoint", "route", "service", "interface", "rpc", "rest"],
+  typescript: ["ts", "types", "type-safe"],
+  react: ["jsx", "tsx", "component", "ui"],
+  node: ["nodejs", "runtime", "backend", "server"],
+  database: ["db", "sql", "nosql", "storage", "persistence"]
+};
+var STEMMING_PATTERNS = [
+  { suffix: "e", alternatives: ["es", "ed", "ing", "ation"] },
+  { suffix: "y", alternatives: ["ies", "ied", "ying"] }
+  // Catch-all for non-verb / already-stemmed query terms: no-op by default.
+];
+var DEFAULT_IDF_WEIGHT = 1;
+var COMMON_TERMS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "as",
+  "is",
+  "it",
+  "at",
+  "be",
+  "do",
+  "has",
+  "have",
+  "was",
+  "are",
+  "been",
+  "this",
+  "that",
+  "these",
+  "those",
+  "will",
+  "can",
+  "may",
+  "would",
+  "could",
+  "should",
+  "does",
+  "not",
+  "no",
+  "if",
+  "so",
+  "up",
+  "out",
+  "all",
+  "each",
+  "every",
+  "both",
+  "some",
+  "any",
+  "such",
+  "only",
+  "own",
+  "same",
+  "too",
+  "very",
+  "just",
+  "about",
+  "over",
+  "than",
+  "then",
+  "also"
+]);
+function idfWeight(term) {
+  return COMMON_TERMS.has(term) ? 0.3 : DEFAULT_IDF_WEIGHT;
+}
+function expandQueryTerms(text) {
+  const baseTerms = tokenize(text);
+  const weighted = /* @__PURE__ */ new Map();
+  for (const term of baseTerms) {
+    const lower = term.toLowerCase();
+    const aliases = /* @__PURE__ */ new Set();
+    const syns = SYNONYM_PAIRS[lower];
+    if (syns !== void 0) {
+      for (const s of syns) aliases.add(s);
+    }
+    for (const [key, values] of Object.entries(SYNONYM_PAIRS)) {
+      if (values.includes(lower)) {
+        aliases.add(key);
+      }
+    }
+    for (const { suffix, alternatives } of STEMMING_PATTERNS) {
+      if (lower.endsWith(suffix) && lower.length > suffix.length) {
+        const stem = lower.slice(0, -suffix.length);
+        for (const alt of alternatives) {
+          aliases.add(stem + alt);
+        }
+      }
+    }
+    const originalWeight = idfWeight(lower);
+    weighted.set(term, originalWeight);
+    for (const alias of aliases) {
+      if (!weighted.has(alias)) {
+        weighted.set(alias, originalWeight * 0.5);
+      }
+    }
+  }
+  return weighted;
+}
 function buildQueryTerms(text) {
   return tokenize(text);
 }
@@ -2021,7 +2162,7 @@ async function extractKnowledge(projectRoot, input) {
   const writeScopeMeta = resolveWriteScopeMeta(layer, projectRoot, semanticScope);
   await ensureParentDirectory(absolutePath);
   if (existsSync3(absolutePath)) {
-    const existing = await readFile4(absolutePath, "utf8");
+    const existing = await readFile5(absolutePath, "utf8");
     const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
     if (existingKey === effectiveIdempotencyKey) {
       const fresh2 = renderFreshEntry({
@@ -2154,7 +2295,7 @@ async function resolveDisambiguatedSlugPath(args) {
         idempotencyKey: candidateKey
       };
     }
-    const existing = await readFile4(candidatePath, "utf8");
+    const existing = await readFile5(candidatePath, "utf8");
     const existingKey = readFrontmatterKey(existing, "x-fabric-idempotency-key");
     if (existingKey === candidateKey) {
       return {
@@ -2752,15 +2893,24 @@ var LEDGER_DUAL_WRITE_METRIC_NAMES = {
 };
 
 // src/services/plan-context.ts
-import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile2 } from "fs/promises";
 import { join as join10 } from "path";
 
 // src/services/vector-retrieval.ts
 import { mkdirSync } from "fs";
+import { createRequire } from "module";
 import { join as join9 } from "path";
 import { resolveGlobalRoot as resolveGlobalRoot3 } from "@fenglimg/fabric-shared";
 var embedderLoad;
 var OPTIONAL_EMBED_PACKAGE = "fastembed";
+function isEmbedderResolvable() {
+  try {
+    createRequire(import.meta.url).resolve(OPTIONAL_EMBED_PACKAGE);
+    return true;
+  } catch {
+    return false;
+  }
+}
 var embedderModuleLoader = (name) => import(name);
 var MISSING_EMBEDDER_HINT = "[fabric] vector semantic recall is enabled but the optional 'fastembed' package is unavailable \u2014 falling back to text-only ranking. Install it where the server resolves modules (e.g. `npm i -g fastembed`) to enable embeddings, or set embed_enabled:false to silence this.\n";
 var defaultMissingEmbedderHint = () => {
@@ -3170,7 +3320,7 @@ function bm25CachePath(projectRoot, revision) {
 }
 async function loadBm25ModelFromDisk(projectRoot, revision) {
   try {
-    const raw = await readFile5(bm25CachePath(projectRoot, revision), "utf8");
+    const raw = await readFile6(bm25CachePath(projectRoot, revision), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.version !== 1) return null;
     return rehydrateBm25Model(parsed);
@@ -3283,6 +3433,10 @@ async function buildScoringContext(projectRoot, revision, rawItems, opts) {
   const configuredFusion = readFusion(projectRoot);
   const vectorActive = scoringContext.vectorScores !== void 0 && scoringContext.vectorScores.size > 0;
   scoringContext.fusion = configuredFusion === "auto" ? vectorActive ? "rrf" : "additive" : configuredFusion;
+  let queryTermWeights;
+  if (scoringContext.queryTerms.length > 0) {
+    queryTermWeights = expandQueryTerms(opts.queryText);
+  }
   if (scoringContext.fusion === "rrf" && scoringContext.queryTerms.length > 0 && rawItems.length > 0) {
     const rankIds = rawItems.map((item) => item.stable_id).sort((a, b) => compareStableIds(a, b));
     if (scoringContext.bm25 !== void 0) {
@@ -3294,6 +3448,49 @@ async function buildScoringContext(projectRoot, revision, rawItems, opts) {
   }
   return scoringContext;
 }
+var PROXIMITY_WINDOW = 6;
+var PROXIMITY_BOOST_CAP = 0.15;
+function proximityBoost(item, context, contentScore2) {
+  if (contentScore2 <= 0) return 0;
+  const text = context.docTexts?.get(item.stable_id);
+  if (text === void 0 || text.length === 0) return 0;
+  const tokens = text.toLowerCase().split(/[^a-z0-9_$#]+/u).filter(Boolean);
+  const queryTerms = context.queryTerms;
+  if (queryTerms.length < 2) return 0;
+  const positions = /* @__PURE__ */ new Map();
+  for (const qt of queryTerms) {
+    const qtLower = qt.toLowerCase();
+    const pos = [];
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i] === qtLower) {
+        pos.push(i);
+      }
+    }
+    if (pos.length > 0) {
+      positions.set(qtLower, pos);
+    }
+  }
+  if (positions.size < 2) return 0;
+  const termList = [...positions.entries()];
+  let minDist = Infinity;
+  for (let i = 0; i < termList.length; i++) {
+    const [, posI] = termList[i];
+    for (let j = i + 1; j < termList.length; j++) {
+      const [, posJ] = termList[j];
+      for (const pi of posI) {
+        for (const pj of posJ) {
+          const dist = Math.abs(pi - pj);
+          if (dist < minDist) minDist = dist;
+        }
+      }
+    }
+  }
+  if (!Number.isFinite(minDist)) return 0;
+  if (minDist >= PROXIMITY_WINDOW) return 0;
+  const ratio = 1 - minDist / PROXIMITY_WINDOW;
+  const boost = contentScore2 * PROXIMITY_BOOST_CAP * ratio;
+  return boost;
+}
 function sortDescriptionItems(rawItems, scoringContext) {
   if (scoringContext === void 0) {
     return [...rawItems].sort((left, right) => compareStableIds(left.stable_id, right.stable_id)).map((item) => ({ item, score: 0 }));
@@ -3436,7 +3633,8 @@ function structuralScaleFor(context) {
 function scoreDescriptionItem(item, context) {
   const content = contentScore(item, context);
   const structural = salienceScore(item) + recencyBoost(item, context) + localityBoost(item, context);
-  return content + structuralScaleFor(context) * structural;
+  const proximity = proximityBoost(item, context, content);
+  return content + structuralScaleFor(context) * structural + proximity;
 }
 function scoreBreakdownForItem(item, context) {
   const hasQuery = context.queryTerms.length > 0;
@@ -3918,7 +4116,7 @@ import { enforcePayloadLimit as enforcePayloadLimit4 } from "@fenglimg/fabric-sh
 // src/services/review.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync5 } from "fs";
-import { readFile as readFile7, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
+import { readFile as readFile8, readdir as readdir2, stat as stat2, unlink as unlink2 } from "fs/promises";
 import { homedir } from "os";
 import { basename, isAbsolute, join as join12, relative, resolve as resolve2, sep as sep2 } from "path";
 
@@ -3960,7 +4158,7 @@ import { allocateStoreKnowledgeId, isPersonalScope as isPersonalScope2 } from "@
 
 // src/services/pending-dedupe.ts
 import { existsSync as existsSync4 } from "fs";
-import { readdir, readFile as readFile6, unlink } from "fs/promises";
+import { readdir, readFile as readFile7, unlink } from "fs/promises";
 import { join as join11 } from "path";
 var PENDING_TYPES = ["decisions", "pitfalls", "guidelines", "models", "processes"];
 var DISAMBIGUATION_SUFFIX = /^(.+)-([2-9])\.md$/u;
@@ -4058,7 +4256,7 @@ async function mergePendingTwins(projectRoot) {
           const abs = join11(dir, name);
           let content;
           try {
-            content = await readFile6(abs, "utf8");
+            content = await readFile7(abs, "utf8");
           } catch {
             continue;
           }
@@ -4253,7 +4451,7 @@ async function listPending(projectRoot, filters) {
         const absolutePath = join12(dir, name);
         let content;
         try {
-          content = await readFile7(absolutePath, "utf8");
+          content = await readFile8(absolutePath, "utf8");
         } catch {
           continue;
         }
@@ -4363,7 +4561,7 @@ async function approveOne(projectRoot, pendingPath) {
   let targetAbs;
   let writtenTarget = false;
   try {
-    const content = await readFile7(sourceAbs, "utf8");
+    const content = await readFile8(sourceAbs, "utf8");
     const fm = parseFrontmatter(content);
     const pluralType = fm.type;
     if (pluralType === void 0 || !PLURAL_TYPES.includes(pluralType)) {
@@ -4435,7 +4633,7 @@ async function rejectAll(projectRoot, pendingPaths, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile7(sandboxed.abs, "utf8");
+        const content = await readFile8(sandboxed.abs, "utf8");
         const merged = rewriteFrontmatterMerge(content, { status: "rejected" });
         const rejectedAbs = sandboxed.abs.includes(`${sep2}pending${sep2}`) ? sandboxed.abs.replace(`${sep2}pending${sep2}`, `${sep2}rejected${sep2}`) : null;
         if (rejectedAbs !== null) {
@@ -4462,7 +4660,7 @@ async function modifyEntry(projectRoot, pendingPath, changes) {
   if (target === null) {
     throw new Error(`modify target not found: ${pendingPath}`);
   }
-  const content = await readFile7(target.absPath, "utf8");
+  const content = await readFile8(target.absPath, "utf8");
   const fm = parseFrontmatter(content);
   const currentLayer = fm.layer ?? "team";
   if (fm.maturity === "verified" && changes.maturity === "proven" && fm.id !== void 0) {
@@ -4694,7 +4892,7 @@ async function listIndexedSearchEntries(source, type) {
     }
     let content;
     try {
-      content = await readFile7(absolutePath, "utf8");
+      content = await readFile8(absolutePath, "utf8");
       searchEntryIndexContentReads += 1;
     } catch {
       directoryCache.files.delete(absolutePath);
@@ -4863,7 +5061,7 @@ async function deferAll(projectRoot, pendingPaths, until, reason) {
     try {
       const sandboxed = resolveSandboxedPath(projectRoot, pendingPath, { allowPersonal: true });
       if (existsSync5(sandboxed.abs)) {
-        const content = await readFile7(sandboxed.abs, "utf8");
+        const content = await readFile8(sandboxed.abs, "utf8");
         stableId = parseFrontmatter(content).id;
         const patch = {
           status: "deferred",
@@ -5204,7 +5402,7 @@ function registerPending(server, tracker) {
 }
 
 // src/services/doctor.ts
-import { access as access4, readFile as readFile17, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile4 } from "fs/promises";
+import { access as access4, readFile as readFile18, readdir as readdirAsync, stat as statAsync, unlink as unlink4, writeFile as writeFile4 } from "fs/promises";
 import { constants as constants2 } from "fs";
 import { isAbsolute as isAbsolute2, join as join23, posix as posix5, resolve as resolve3 } from "path";
 import {
@@ -5420,7 +5618,7 @@ function createKnowledgeSummaryOpaqueCheck(t, inspection) {
 }
 
 // src/services/doctor-stable-id-collision.ts
-import { readFile as readFile8 } from "fs/promises";
+import { readFile as readFile9 } from "fs/promises";
 import { basename as basename2, join as join13 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput4,
@@ -5467,7 +5665,7 @@ async function inspectStoreStableIdIntegrity(projectRoot) {
   for (const ref of await readKnowledgeAcrossStores2(resolved.dirs)) {
     let source;
     try {
-      source = await readFile8(ref.file, "utf8");
+      source = await readFile9(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -5788,7 +5986,7 @@ function createNarrowNoPathsCheck(t, inspection) {
 }
 
 // src/services/doctor-broad-index.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { join as join15 } from "path";
 var DEFAULT_BROAD_INDEX_BACKSTOP = 50;
 var BROAD_INDEX_BACKSTOP_MIN = 20;
@@ -5797,7 +5995,7 @@ var BROAD_INDEX_DRIFT_RATIO = 0.8;
 async function readBroadIndexBackstop(projectRoot) {
   const configPath = join15(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile9(configPath, "utf8");
+    const raw = await readFile10(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.broad_index_backstop;
@@ -6114,7 +6312,7 @@ function createBroadReviewRecheckCheck(t, inspection) {
 }
 
 // src/services/doctor-scope-lint.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { join as join16 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput5,
@@ -6182,7 +6380,7 @@ async function lintStoreScopes(projectRoot) {
     }
     let source;
     try {
-      source = await readFile10(ref.file, "utf8");
+      source = await readFile11(ref.file, "utf8");
     } catch {
       continue;
     }
@@ -6626,7 +6824,7 @@ async function inspectEventsJsonlGates(projectRoot, options = {}) {
 }
 
 // src/services/doctor-skill-lints.ts
-import { readdir as readdir3, readFile as readFile11 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile12 } from "fs/promises";
 import { join as join19, posix as posix2 } from "path";
 var FABRIC_SKILL_SLUGS = ["fabric-archive", "fabric-review"];
 var SKILL_MD_FRONTMATTER_ROOTS = [".claude/skills", ".codex/skills"];
@@ -6675,8 +6873,8 @@ async function inspectSkillRefMirror(projectRoot) {
       let codexBody;
       try {
         [claudeBody, codexBody] = await Promise.all([
-          readFile11(join19(claudeRef, fname), "utf8"),
-          readFile11(join19(codexRef, fname), "utf8")
+          readFile12(join19(claudeRef, fname), "utf8"),
+          readFile12(join19(codexRef, fname), "utf8")
         ]);
       } catch {
         continue;
@@ -6698,7 +6896,7 @@ async function inspectSkillTokenBudget(projectRoot) {
     const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile11(skillMdPath, "utf8");
+      body = await readFile12(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6722,7 +6920,7 @@ async function inspectSkillDescription(projectRoot) {
     const skillMdPath = join19(projectRoot, ".claude", "skills", slug, "SKILL.md");
     let body;
     try {
-      body = await readFile11(skillMdPath, "utf8");
+      body = await readFile12(skillMdPath, "utf8");
     } catch {
       continue;
     }
@@ -6765,7 +6963,7 @@ async function inspectSkillMdYamlInvalid(projectRoot) {
       const skillFile = join19(rootAbs, dirEntry.name, "SKILL.md");
       let raw;
       try {
-        raw = await readFile11(skillFile, "utf8");
+        raw = await readFile12(skillFile, "utf8");
       } catch {
         continue;
       }
@@ -6888,7 +7086,7 @@ function createSkillMdYamlInvalidCheck(t, inspection) {
 }
 
 // src/services/doctor-retired-references-lint.ts
-import { readdir as readdir4, readFile as readFile12, stat as stat3 } from "fs/promises";
+import { readdir as readdir4, readFile as readFile13, stat as stat3 } from "fs/promises";
 import { join as join20, posix as posix3, relative as relative2 } from "path";
 var RETIRED_TOKENS = [
   { token: "fab_plan_context", replacement: "fab_recall", reason: "retrieval collapsed to one lean fab_recall (KT-DEC-0026)" },
@@ -6956,7 +7154,7 @@ async function inspectRetiredReferences(projectRoot) {
     try {
       if ((await stat3(abs)).isFile()) {
         scannedFiles += 1;
-        scanText(toRel(abs), await readFile12(abs, "utf8"), false, hits);
+        scanText(toRel(abs), await readFile13(abs, "utf8"), false, hits);
       }
     } catch {
     }
@@ -6965,7 +7163,7 @@ async function inspectRetiredReferences(projectRoot) {
     for (const file of await walkFiles(join20(projectRoot, dir), [".md"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile12(file, "utf8"), false, hits);
+        scanText(toRel(file), await readFile13(file, "utf8"), false, hits);
       } catch {
       }
     }
@@ -6974,7 +7172,7 @@ async function inspectRetiredReferences(projectRoot) {
     for (const file of await walkFiles(join20(projectRoot, dir), [".cjs"])) {
       scannedFiles += 1;
       try {
-        scanText(toRel(file), await readFile12(file, "utf8"), true, hits);
+        scanText(toRel(file), await readFile13(file, "utf8"), true, hits);
       } catch {
       }
     }
@@ -7009,7 +7207,7 @@ function createRetiredReferenceCheck(t, inspection) {
 
 // src/services/doctor-hooks-lints.ts
 import { constants } from "fs";
-import { access, readdir as readdir5, readFile as readFile13, stat as stat4 } from "fs/promises";
+import { access, readdir as readdir5, readFile as readFile14, stat as stat4 } from "fs/promises";
 import { join as join21, posix as posix4 } from "path";
 import { Script } from "vm";
 var HOOKS_RUNTIME_CLIENT_DIRS = [
@@ -7079,7 +7277,7 @@ async function inspectHooksWired(projectRoot) {
   const settingsPath = join21(projectRoot, ".claude", "settings.json");
   let parsed;
   try {
-    parsed = JSON.parse(await readFile13(settingsPath, "utf8"));
+    parsed = JSON.parse(await readFile14(settingsPath, "utf8"));
   } catch {
     return { status: "missing-settings", missingHooks: [] };
   }
@@ -7172,7 +7370,7 @@ async function inspectHooksContentDrift(projectRoot) {
     const hashes = [];
     for (const { client, abs } of copies) {
       try {
-        const body = await readFile13(abs, "utf8");
+        const body = await readFile14(abs, "utf8");
         hashes.push({ client, sha: sha256(body) });
       } catch {
       }
@@ -7205,7 +7403,7 @@ async function inspectHooksRuntime(projectRoot) {
       scanned += 1;
       let body;
       try {
-        body = await readFile13(abs, "utf8");
+        body = await readFile14(abs, "utf8");
       } catch (err) {
         issues.push({
           path: displayPath,
@@ -7342,7 +7540,7 @@ function createHookCacheWritabilityCheck(t, inspection) {
 }
 
 // src/services/doctor-bootstrap-lints.ts
-import { access as access2, readFile as readFile14 } from "fs/promises";
+import { access as access2, readFile as readFile15 } from "fs/promises";
 import { join as join22 } from "path";
 import {
   BOOTSTRAP_MARKER_BEGIN,
@@ -7385,7 +7583,7 @@ async function inspectL1BootstrapSnapshotDrift(target) {
   const canonical = resolveBootstrapCanonical();
   let onDisk;
   try {
-    onDisk = await readFile14(abs, "utf8");
+    onDisk = await readFile15(abs, "utf8");
   } catch {
     return { status: "missing", canonical, onDisk: null };
   }
@@ -7414,14 +7612,14 @@ async function inspectL2ManagedBlockDrift(target) {
   const snapshotPath = join22(target, ".fabric", "AGENTS.md");
   let snapshot;
   try {
-    snapshot = await readFile14(snapshotPath, "utf8");
+    snapshot = await readFile15(snapshotPath, "utf8");
   } catch {
     return { status: "ok", drifted: [] };
   }
   const projectRulesPath = join22(target, ".fabric", "project-rules.md");
   let expectedBody = snapshot;
   try {
-    const projectRules = await readFile14(projectRulesPath, "utf8");
+    const projectRules = await readFile15(projectRulesPath, "utf8");
     expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -7435,7 +7633,7 @@ ${projectRules}`;
   for (const abs of blockTargets) {
     let content;
     try {
-      content = await readFile14(abs, "utf8");
+      content = await readFile15(abs, "utf8");
     } catch {
       continue;
     }
@@ -7460,7 +7658,7 @@ ${projectRules}`;
   }
   const claudeMdPath = join22(target, "CLAUDE.md");
   try {
-    const claudeContent = await readFile14(claudeMdPath, "utf8");
+    const claudeContent = await readFile15(claudeMdPath, "utf8");
     anyManagedBlockFound = true;
     const lines = claudeContent.split(/\r?\n/u);
     const hasAtImport = lines.some((line) => line.trim() === "@.fabric/AGENTS.md");
@@ -7528,7 +7726,7 @@ import { appendFile as appendFile3 } from "fs/promises";
 import { minimatch as minimatch2 } from "minimatch";
 
 // src/services/cite-rollup.ts
-import { readFile as readFile15 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 import { createLedgerWriteQueue as createLedgerWriteQueue3 } from "@fenglimg/fabric-shared/node/atomic-write";
 var citeRollupQueue = createLedgerWriteQueue3();
 async function appendCiteRollupRow(projectRoot, row) {
@@ -7540,7 +7738,7 @@ async function readCiteRollup(projectRoot) {
   const path = getCiteRollupPath(projectRoot);
   let raw;
   try {
-    raw = await readFile15(path, "utf8");
+    raw = await readFile16(path, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") return [];
     throw error;
@@ -8131,6 +8329,18 @@ async function runDoctorCiteCoverage(projectRoot, options) {
       }
     }
   }
+  const editSessionIds = /* @__PURE__ */ new Set();
+  for (const edit of editEvents) {
+    if (typeof edit.session_id === "string" && edit.session_id.length > 0) {
+      editSessionIds.add(edit.session_id);
+    }
+  }
+  let recallsInWindow = 0;
+  for (const list of plannedBySession.values()) recallsInWindow += list.length;
+  let recallSessionsCorrelated = 0;
+  for (const sid of plannedBySession.keys()) {
+    if (editSessionIds.has(sid)) recallSessionsCorrelated += 1;
+  }
   const noneTotal = Object.values(noneHistogram).reduce((a, b) => a + b, 0);
   const compliantCites = qualifyingCites + noneTotal;
   const noncompliantCites = expectedButMissed;
@@ -8198,6 +8408,11 @@ async function runDoctorCiteCoverage(projectRoot, options) {
     uncorrelatable_edits: uncorrelatableEdits,
     recall_backed_edits: recallBackedEdits,
     recall_coverage_rate: recallCoverageRate,
+    recall_diagnostics: {
+      recalls_in_window: recallsInWindow,
+      recall_sessions: plannedBySession.size,
+      recall_sessions_correlated: recallSessionsCorrelated
+    },
     exposed_and_mutated: {
       count: exposedAndMutated.count,
       ...exposedAndMutated.ids.length > 0 ? { ids: exposedAndMutated.ids } : {}
@@ -9091,7 +9306,7 @@ function truncateErrorMessage(error) {
 async function inspectForensic(projectRoot) {
   const path = join23(projectRoot, ".fabric", "forensic.json");
   try {
-    const parsed = forensicReportSchema.parse(JSON.parse(await readFile17(path, "utf8")));
+    const parsed = forensicReportSchema.parse(JSON.parse(await readFile18(path, "utf8")));
     return { present: true, valid: true, report: parsed };
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -9121,7 +9336,7 @@ async function inspectEventLedger(projectRoot) {
   try {
     await access4(path, constants2.W_OK);
     const { warnings } = await readEventLedger(projectRoot);
-    const raw = await readFile17(path, "utf8");
+    const raw = await readFile18(path, "utf8");
     const invalidLine = raw.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).find((line) => !isValidJsonLine(line));
     const partialWarning = warnings.find((w) => w.kind === "partial_write_at_tail");
     const schemaVersionSamples = [];
@@ -9797,7 +10012,7 @@ function inspectStaleServeLock(projectRoot, now) {
 async function readUnderseedThresholdFromConfig(projectRoot) {
   const configPath = join23(projectRoot, ".fabric", "fabric-config.json");
   try {
-    const raw = await readFile17(configPath, "utf8");
+    const raw = await readFile18(configPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const v = parsed.underseed_node_threshold;
@@ -9916,7 +10131,7 @@ async function readOnboardOptedOut(projectRoot) {
   const path = join23(projectRoot, ".fabric", "fabric-config.json");
   let raw;
   try {
-    raw = await readFile17(path, "utf8");
+    raw = await readFile18(path, "utf8");
   } catch {
     return [];
   }
@@ -10024,7 +10239,7 @@ async function rewriteThreeEndManagedBlocks(projectRoot) {
   }
   let snapshot;
   try {
-    snapshot = await readFile17(snapshotPath, "utf8");
+    snapshot = await readFile18(snapshotPath, "utf8");
   } catch {
     return;
   }
@@ -10033,7 +10248,7 @@ async function rewriteThreeEndManagedBlocks(projectRoot) {
   let expectedBody = snapshot;
   if (hasProjectRules) {
     try {
-      const projectRules = await readFile17(projectRulesPath, "utf8");
+      const projectRules = await readFile18(projectRulesPath, "utf8");
       expectedBody = `${snapshot}
 ---
 ${projectRules}`;
@@ -10052,7 +10267,7 @@ ${BOOTSTRAP_MARKER_END2}`;
     }
     let existing;
     try {
-      existing = await readFile17(abs, "utf8");
+      existing = await readFile18(abs, "utf8");
     } catch {
       continue;
     }
@@ -10081,7 +10296,7 @@ ${managedBlock}
   if (await pathExists(claudeMdPath)) {
     let claudeContent;
     try {
-      claudeContent = await readFile17(claudeMdPath, "utf8");
+      claudeContent = await readFile18(claudeMdPath, "utf8");
     } catch {
       return;
     }
@@ -10223,7 +10438,7 @@ async function enrichDescriptions(projectRoot, opts = {}) {
     scanned += 1;
     let source;
     try {
-      source = await readFile17(absPath, "utf8");
+      source = await readFile18(absPath, "utf8");
     } catch {
       continue;
     }
@@ -10361,7 +10576,7 @@ async function runDoctorConflictLint(projectRoot, opts = {}) {
 }
 
 // src/services/why-not-surfaced.ts
-import { readFile as readFile18 } from "fs/promises";
+import { readFile as readFile19 } from "fs/promises";
 import { basename as basename3, join as join24 } from "path";
 import {
   buildStoreResolveInput as buildStoreResolveInput7,
@@ -10411,7 +10626,7 @@ async function explainWhyNotSurfaced(projectRoot, query) {
   }
   let source;
   try {
-    source = await readFile18(candidate.file, "utf8");
+    source = await readFile19(candidate.file, "utf8");
   } catch {
     return base;
   }
@@ -10464,6 +10679,191 @@ function buildColdEvalBatch(candidates) {
   return { rubric: COLD_EVAL_RUBRIC, candidates: judgeable };
 }
 
+// src/services/doctor-related-graph.ts
+function buildRelatedGraph(nodes) {
+  const brokenLinks = [];
+  const inDegree = /* @__PURE__ */ new Map();
+  const allIds = /* @__PURE__ */ new Set();
+  const edgeSources = [];
+  for (const node of nodes) {
+    const bareId = extractBareStableId(node.qualifiedId);
+    allIds.add(node.qualifiedId);
+    if (bareId !== null) {
+      allIds.add(bareId);
+    }
+    const related = node.related;
+    if (related !== void 0 && related.length > 0) {
+      edgeSources.push({ source: node.qualifiedId, related });
+      for (const rel of related) {
+        inDegree.set(rel, (inDegree.get(rel) ?? 0) + 1);
+      }
+    }
+  }
+  for (const { source, related } of edgeSources) {
+    for (const rel of related) {
+      if (!allIds.has(rel)) {
+        brokenLinks.push({ source, target: rel });
+      }
+    }
+  }
+  const hubEntries = [...inDegree.entries()].map(([stableId, degree]) => ({ stableId, inDegree: degree })).sort((a, b) => b.inDegree - a.inDegree || a.stableId.localeCompare(b.stableId));
+  return {
+    brokenLinks,
+    hubEntries,
+    totalEntries: nodes.length
+  };
+}
+function extractBareStableId(qualifiedId) {
+  const colonIdx = qualifiedId.indexOf(":");
+  if (colonIdx > 0 && colonIdx < qualifiedId.length - 1) {
+    return qualifiedId.slice(colonIdx + 1);
+  }
+  return null;
+}
+async function inspectRelatedGraph(projectRoot) {
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  return buildRelatedGraph(
+    entries.map((entry) => ({
+      qualifiedId: entry.qualifiedId,
+      related: entry.description.related
+    }))
+  );
+}
+
+// src/services/store-precheck.ts
+import { existsSync as existsSync9, readFileSync as readFileSync4 } from "fs";
+import { join as join25 } from "path";
+import {
+  buildStoreResolveInput as buildStoreResolveInput8,
+  createStoreResolver as createStoreResolver8,
+  resolveGlobalRoot as resolveGlobalRoot9,
+  storeRelativePathForMount as storeRelativePathForMount7
+} from "@fenglimg/fabric-shared";
+var CACHE_TTL_MS = 6e4;
+var cache = /* @__PURE__ */ new Map();
+function clearPrecheckCache() {
+  cache.clear();
+}
+function evaluateStoreDir(storeDir, identity) {
+  if (!existsSync9(storeDir)) {
+    return {
+      uuid: identity.uuid,
+      alias: identity.alias,
+      reachable: false,
+      reason: `directory not found at ${storeDir}`
+    };
+  }
+  const storeJsonPath = join25(storeDir, "store.json");
+  const gitDirPath = join25(storeDir, ".git");
+  const hasStoreJson = existsSync9(storeJsonPath) && isValidStoreJson(storeJsonPath);
+  const hasGitDir = existsSync9(gitDirPath);
+  if (!hasStoreJson && !hasGitDir) {
+    return {
+      uuid: identity.uuid,
+      alias: identity.alias,
+      reachable: false,
+      reason: `no store.json or .git found in ${storeDir}`
+    };
+  }
+  return { uuid: identity.uuid, alias: identity.alias, reachable: true };
+}
+function isValidStoreJson(path) {
+  try {
+    JSON.parse(readFileSync4(path, "utf8"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function precheckStoreReachability(projectRoot, globalRoot = resolveGlobalRoot9(), now = Date.now()) {
+  const cached = cache.get(projectRoot);
+  if (cached !== void 0 && cached.expiresAt > now) {
+    return cached.result;
+  }
+  const input = buildStoreResolveInput8(projectRoot, globalRoot);
+  if (input === null) {
+    const result2 = { stores: [], allReachable: true };
+    cache.set(projectRoot, { result: result2, expiresAt: now + CACHE_TTL_MS });
+    return result2;
+  }
+  const readSet = createStoreResolver8().resolveReadSet(input);
+  const stores = readSet.stores.map((entry) => {
+    const mounted = input.mountedStores.find((s) => s.store_uuid === entry.store_uuid);
+    const storeDir = join25(
+      globalRoot,
+      storeRelativePathForMount7(mounted ?? { store_uuid: entry.store_uuid })
+    );
+    return evaluateStoreDir(storeDir, { uuid: entry.store_uuid, alias: entry.alias });
+  });
+  const result = {
+    stores,
+    allReachable: stores.every((s) => s.reachable)
+  };
+  cache.set(projectRoot, { result, expiresAt: now + CACHE_TTL_MS });
+  return result;
+}
+
+// src/services/doctor-consumption-lint.ts
+var DEFAULT_WINDOW_DAYS = 30;
+var DEFAULT_TOP_N = 10;
+var DEFAULT_MIN_TOTAL_ENTRIES = 20;
+var DEFAULT_MIN_CONSUMED_WINDOWS = 30;
+var DEFAULT_MIN_CONSUMED_EVENTS = 50;
+var CONSUMED_PREFIX = "knowledge_consumed:";
+var MS_PER_DAY5 = 24 * 60 * 60 * 1e3;
+function resolveConfig(config) {
+  return {
+    windowDays: config?.windowDays ?? DEFAULT_WINDOW_DAYS,
+    topN: config?.topN ?? DEFAULT_TOP_N,
+    minTotalEntries: config?.minTotalEntries ?? DEFAULT_MIN_TOTAL_ENTRIES,
+    minConsumedWindows: config?.minConsumedWindows ?? DEFAULT_MIN_CONSUMED_WINDOWS,
+    minConsumedEvents: config?.minConsumedEvents ?? DEFAULT_MIN_CONSUMED_EVENTS
+  };
+}
+function aggregateConsumption(rows, allQualifiedIds, now, config) {
+  const cfg = resolveConfig(config);
+  const cutoffMs = now - cfg.windowDays * MS_PER_DAY5;
+  const consumed = /* @__PURE__ */ new Map();
+  let consumedWindows = 0;
+  let totalConsumedEvents = 0;
+  for (const row of rows) {
+    const rowTs = Date.parse(row.timestamp);
+    if (!Number.isFinite(rowTs) || rowTs < cutoffMs) continue;
+    if (row.counters === null || typeof row.counters !== "object") continue;
+    let windowHadConsumption = false;
+    for (const [counterName, rawCount] of Object.entries(row.counters)) {
+      if (!counterName.startsWith(CONSUMED_PREFIX)) continue;
+      const count = typeof rawCount === "number" ? rawCount : 0;
+      if (count <= 0) continue;
+      const id = counterName.slice(CONSUMED_PREFIX.length);
+      if (id.length === 0) continue;
+      consumed.set(id, (consumed.get(id) ?? 0) + count);
+      totalConsumedEvents += count;
+      windowHadConsumption = true;
+    }
+    if (windowHadConsumption) consumedWindows += 1;
+  }
+  const topConsumed = [...consumed.entries()].map(([stableId, count]) => ({ stableId, count })).sort((a, b) => b.count - a.count || a.stableId.localeCompare(b.stableId)).slice(0, cfg.topN);
+  const dataMature = consumedWindows >= cfg.minConsumedWindows && totalConsumedEvents >= cfg.minConsumedEvents && allQualifiedIds.length >= cfg.minTotalEntries;
+  const zeroConsumed = dataMature ? allQualifiedIds.filter((id) => !consumed.has(id)).sort((a, b) => a.localeCompare(b)) : [];
+  return {
+    topConsumed,
+    zeroConsumed,
+    totalEntries: allQualifiedIds.length,
+    consumedEntries: consumed.size,
+    consumedWindows,
+    totalConsumedEvents,
+    dataMature,
+    windowDays: cfg.windowDays
+  };
+}
+async function inspectConsumption(projectRoot, config, now = Date.now()) {
+  const rows = await readMetrics(projectRoot);
+  const entries = await collectStoreCanonicalEntries(projectRoot);
+  const allQualifiedIds = entries.map((entry) => entry.qualifiedId);
+  return aggregateConsumption(rows, allQualifiedIds, now, config);
+}
+
 // src/services/rotation-tick.ts
 var DEFAULT_TICK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
 var tickTimers = /* @__PURE__ */ new Map();
@@ -10499,7 +10899,7 @@ import { IOFabricError as IOFabricError2, RuleError } from "@fenglimg/fabric-sha
 
 // src/services/read-ledger.ts
 import { randomUUID as randomUUID7 } from "crypto";
-import { access as access5, copyFile, readFile as readFile19, rm } from "fs/promises";
+import { access as access5, copyFile, readFile as readFile20, rm } from "fs/promises";
 import { ledgerEntrySchema } from "@fenglimg/fabric-shared";
 async function resolveLedgerPaths(projectRoot) {
   const primaryPath = getLedgerPath(projectRoot);
@@ -10527,7 +10927,7 @@ async function readLegacyLedger(projectRoot) {
   const { readPath } = await resolveLedgerPaths(projectRoot);
   let raw;
   try {
-    raw = await readFile19(readPath, "utf8");
+    raw = await readFile20(readPath, "utf8");
   } catch (error) {
     if (isNodeError(error) && error.code === "ENOENT") {
       return [];
@@ -10782,8 +11182,8 @@ function formatError(error) {
 }
 function formatPreexistingRootMessage(projectRoot) {
   const preexisting = [];
-  if (existsSync9(join25(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
-  if (existsSync9(join25(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
+  if (existsSync10(join26(projectRoot, "CLAUDE.md"))) preexisting.push("CLAUDE.md");
+  if (existsSync10(join26(projectRoot, "AGENTS.md"))) preexisting.push("AGENTS.md");
   if (preexisting.length === 0) return null;
   return `[startup] info: detected ${preexisting.join(", ")} at project root. Note: Fabric serves knowledge from mounted stores via MCP \u2014 root markdown files are not auto-loaded into the AI context.`;
 }
@@ -10810,7 +11210,7 @@ function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.3.0-rc.3"
+      version: "2.3.0-rc.4"
     },
     {
       instructions: FABRIC_SERVER_INSTRUCTIONS
@@ -10830,10 +11230,10 @@ function createFabricServer(tracker) {
     },
     async (_uri) => {
       const projectRoot = process.env.FABRIC_PROJECT_ROOT ?? process.cwd();
-      const path = join25(projectRoot, ".fabric", "bootstrap", "README.md");
+      const path = join26(projectRoot, ".fabric", "bootstrap", "README.md");
       let text = "";
-      if (existsSync9(path)) {
-        text = await readFile20(path, "utf8");
+      if (existsSync10(path)) {
+        text = await readFile21(path, "utf8");
       }
       return {
         contents: [
@@ -10933,11 +11333,15 @@ export {
   METRIC_COUNTER_NAMES,
   OPTIONAL_EMBED_PACKAGE,
   RETIRED_TOKENS,
+  aggregateConsumption,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
   buildColdEvalBatch,
   buildKnowledgeCensus,
+  buildRelatedGraph,
   bumpCounter,
+  clearPrecheckCache,
+  collectStoreCanonicalEntries,
   contextCache,
   createFabricServer,
   createInFlightTracker,
@@ -10946,6 +11350,7 @@ export {
   detectUnboundProject,
   drainCounters,
   enrichDescriptions,
+  evaluateStoreDir,
   explainWhyNotSurfaced,
   extractKnowledge,
   findConflictCandidates,
@@ -10956,12 +11361,16 @@ export {
   getLedgerPath,
   getLegacyLedgerPath,
   getMetricsLedgerPath,
+  inspectConsumption,
+  inspectRelatedGraph,
   inspectRetiredReferences,
+  isEmbedderResolvable,
   lintConflicts,
   loadConflictEntries,
   loadEmbedder,
   pairSimilarity,
   planContext,
+  precheckStoreReachability,
   readEmbedConfig,
   readEventLedger,
   readFusion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.3.0-rc.3",
+  "version": "2.3.0-rc.4",
   "description": "Fabric MCP knowledge server — stdio transport for Claude Code / Codex CLI, manages .fabric/ knowledge base + agents.meta.json + event ledger.",
   "license": "MIT",
   "author": "wangzhichao <fenglimg90@gmail.com>",
@@ -37,7 +37,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.3.0-rc.3"
+    "@fenglimg/fabric-shared": "2.3.0-rc.4"
   },
   "optionalDependencies": {
     "fastembed": "^2.0.0"