@fenglimg/fabric-server 2.3.0-rc.2 → 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[];
@@ -530,6 +547,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;
@@ -655,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"];
@@ -949,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, 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, 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 };