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

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 { EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, RecallScore, RecallScoreBreakdown, LedgerEntry, AgentsMeta } from '@fenglimg/fabric-shared';
 import { PayloadGuardOptions } from '@fenglimg/fabric-shared/node/mcp-payload-guard';
 
 interface InFlightTracker {
@@ -394,6 +394,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 +530,31 @@ 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";
+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 +642,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>;
 
@@ -729,6 +779,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. */
@@ -773,8 +824,10 @@ type RecallEntry = {
         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 +974,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, 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 };