@fenglimg/fabric-server 2.3.0-rc.1 → 2.3.0-rc.11

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, 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 {
@@ -32,6 +32,16 @@ type DoctorHealth = {
         warnings: number;
     };
 };
+type BacklogAgeMetric = {
+    count: number;
+    oldest_days: number | null;
+    median_age_days: number;
+    ages_days: number[];
+};
+declare function checkBacklogAge(projectRoot: string, nowMs?: number): Promise<BacklogAgeMetric>;
+declare function renderBacklogAgeLine(metric: BacklogAgeMetric): string;
+
+declare function extractRuleDescription(source: string): RuleDescription | undefined;
 
 interface AlwaysActiveBody {
     /** store-qualified id (`<alias>:<stableId>`). */
@@ -78,6 +88,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 +216,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[];
@@ -394,6 +419,29 @@ interface Bm25Model {
      * query property).
      */
     scoreDoc(id: string, queryTerms: string[]): number;
+    /**
+     * P1 recall-engine-refactor (TASK-002): the plain JSON-safe snapshot of the
+     * corpus statistics this model scores against, attached so the model can be
+     * serialized to disk (`serializeBm25Model`) and a cold hook can `rehydrate`
+     * an identical scorer without re-tokenizing the corpus.
+     */
+    readonly __serialized: SerializedBm25Model;
+}
+interface SerializedBm25Model {
+    /** Schema/format version — bump on any layout change so a stale on-disk cache
+     *  (different shape) is detected and discarded rather than mis-rehydrated. */
+    version: 1;
+    totalDocs: number;
+    /** term → document frequency (union-of-fields df), as [term, count] pairs. */
+    documentFrequency: [string, number][];
+    /** Per-field corpus average length. */
+    avgFieldLength: Record<Bm25Field, number>;
+    /** Per-doc stats: id → { per-field [term,freq] pairs, per-field length }. */
+    perDoc: {
+        id: string;
+        fieldTermFreq: Record<Bm25Field, [string, number][]>;
+        fieldLength: Record<Bm25Field, number>;
+    }[];
 }
 /**
  * Build a BM25F model over `docs`. Corpus statistics (per-field document
@@ -507,6 +555,45 @@ declare function runDoctorConflictLint(projectRoot: string, opts?: {
     judge?: ConflictJudge;
 }): Promise<ConflictLintReport>;
 
+declare function readEmbedConfig(projectRoot: string): {
+    enabled: boolean;
+    weight: number;
+    model: string;
+};
+declare function readFusion(projectRoot: string): "additive" | "rrf" | "auto";
+
+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
+ * null (cached) when the package is not installed or initialization throws, so
+ * every caller degrades to the text-only path. Never throws.
+ *
+ * v2.1 ③: `modelName` (a fastembed EmbeddingModel enum value) selects the
+ * embedding model — the caller threads `embed_model` config through so the
+ * Chinese-heavy KB no longer embeds against fastembed's English default. The
+ * load is cached per-process; the FIRST model wins (a config change needs a
+ * server restart, already the norm for MCP config changes).
+ */
+declare function loadEmbedder(modelName?: string): Promise<Embedder | null>;
+
 interface RetiredToken {
     /** The exact dead token as it appears in agent-facing text. */
     token: string;
@@ -594,8 +681,10 @@ declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Pr
  * from `reviewKnowledge`. list browses the store-backed pending backlog;
  * search ranges over BOTH pending and canonical knowledge. Neither mutates
  * state — the fab_pending tool is registered readOnlyHint:true / idempotentHint:true.
- * The underlying listPending / searchEntries helpers are unchanged (verbatim
- * relocation), so behavior is identical to the prior fab_review list/search.
+ * P1 recall-engine-refactor (TASK-005): search now routes through `triageSearch`,
+ * which gates on the substring query then RANKS the matches via the shared
+ * rankDescriptionItems('triage') — NO top_k, NO floor, so pending review never
+ * silently drops a match. The old substring-only search machine is gone.
  */
 declare function reviewPending(projectRoot: string, input: FabPendingInput): Promise<FabPendingOutput>;
 
@@ -630,6 +719,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"];
@@ -729,6 +960,7 @@ type PlanContextResult = {
     previous_revision_hash?: string;
     redirects?: Record<string, string>;
     related_appended?: Record<string, string>;
+    candidate_scores?: Map<string, RecallScore>;
     /** Internal service→tool signal; stripped before MCP output. */
     payload_trimmed?: boolean;
     /** Internal service→tool signal; stripped before MCP output. */
@@ -764,17 +996,21 @@ type RecallInput = PlanContextInput & {
      */
     include_related?: boolean;
 };
+type FullRuleDescription = PlanContextResult["candidates"][number]["description"];
+type RecallEntryDescription = Pick<FullRuleDescription, "summary" | "must_read_if" | "intent_clues"> & Partial<Pick<FullRuleDescription, "knowledge_type">>;
 type RecallEntry = {
     stable_id: string;
     rank: number;
-    description: PlanContextResult["candidates"][number]["description"];
+    description: RecallEntryDescription;
     read_path?: string;
     store?: {
         alias: string;
     };
     body_in_context?: boolean;
+    score?: number;
+    score_breakdown?: RecallScoreBreakdown;
 };
-type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget" | "entries" | "candidates"> & {
+type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget" | "entries" | "candidates" | "candidate_scores"> & {
     entries: RecallEntry[];
     directive: string;
     next_steps?: string[];
@@ -921,4 +1157,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, 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, detectUnboundProject, drainCounters, enrichDescriptions, explainWhyNotSurfaced, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, inspectRetiredReferences, lintConflicts, loadConflictEntries, pairSimilarity, planContext, readEventLedger, 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, type BacklogAgeMetric, 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, checkBacklogAge, 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, renderBacklogAgeLine, resolveLedgerPaths, reviewKnowledge, reviewPending, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };