@fenglimg/fabric-server 2.2.0 → 2.3.0-rc.2

package/README.md

@@ -6,7 +6,7 @@ Fabric MCP knowledge server. Runs over stdio transport and serves Claude Code an
 
 - `fab_recall` — single-step recall: returns candidate descriptions + native read paths (no body delivery over MCP; read a body on demand via a native Read of the returned path)
 - `fab_archive_scan` — scan recent work for archive-worthy knowledge candidates
-- `fab_extract_knowledge` — persist a pending knowledge entry
+- `fab_propose` — persist a pending knowledge entry
 - `fab_review` — list / approve / reject / modify / defer pending entries
 
 ## Install

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { FabExtractKnowledgeInput, FabExtractKnowledgeOutput, FabReviewInput, FabReviewOutput } from '@fenglimg/fabric-shared/schemas/api-contracts';
-import { EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, LedgerEntry, AgentsMeta } from '@fenglimg/fabric-shared';
+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 { PayloadGuardOptions } from '@fenglimg/fabric-shared/node/mcp-payload-guard';
 
 interface InFlightTracker {
@@ -379,24 +379,49 @@ declare function enrichDescriptions(projectRoot: string, opts?: {
     dryRun?: boolean;
 }): Promise<EnrichDescriptionsReport>;
 
+type Bm25Field = "title" | "summary" | "tags" | "body";
 interface Bm25Document {
     id: string;
-    tokens: string[];
+    /** Pre-tokenized terms per field. Omitted/empty fields contribute nothing. */
+    fields: Record<Bm25Field, string[]>;
 }
 interface Bm25Model {
     /**
-     * BM25 score of document `id` against the (pre-tokenized) query terms.
-     * Returns 0 for an unknown id, an empty document, no query terms, or no
-     * term overlap. Query-term duplicates are collapsed — repeating a term in
-     * the query does not inflate the score (term frequency is a document
-     * property, not a query property).
+     * BM25F score of document `id` against the (pre-tokenized) query terms.
+     * Returns 0 for an unknown id, no query terms, or no term overlap in any
+     * field. Query-term duplicates are collapsed — repeating a term in the query
+     * does not inflate the score (term frequency is a document property, not a
+     * 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 BM25 model over `docs`. The corpus statistics (document frequency,
- * average document length) are computed once here; `scoreDoc` is then O(query
- * terms) per call.
+ * Build a BM25F model over `docs`. Corpus statistics (per-field document
+ * frequency over the union of fields, per-field average length) are computed
+ * once here; `scoreDoc` is then O(query terms × fields) per call.
  */
 declare function buildBm25Model(docs: Bm25Document[]): Bm25Model;
 
@@ -505,8 +530,51 @@ declare function runDoctorConflictLint(projectRoot: string, opts?: {
     judge?: ConflictJudge;
 }): Promise<ConflictLintReport>;
 
+interface RetiredToken {
+    /** The exact dead token as it appears in agent-facing text. */
+    token: string;
+    /** What replaced it (shown in the remediation), or null when simply removed. */
+    replacement: string | null;
+    /** Short why-retired note. */
+    reason: string;
+}
+declare const RETIRED_TOKENS: readonly RetiredToken[];
+interface RetiredReferenceHit {
+    /** Project-relative POSIX path of the offending file. */
+    path: string;
+    token: string;
+    line: number;
+    replacement: string | null;
+}
+interface RetiredReferenceInspection {
+    status: "ok" | "warn" | "skipped";
+    scannedFiles: number;
+    hits: RetiredReferenceHit[];
+}
+declare function inspectRetiredReferences(projectRoot: string): Promise<RetiredReferenceInspection>;
+
+type SurfaceVerdict = "not_found" | "store_unbound" | "project_mismatch" | "narrow_timing" | "should_surface";
+interface WhyNotSurfacedResult {
+    /** The id exactly as queried. */
+    query: string;
+    /** Normalized LOCAL stable id (store-qualified `alias:ID` → `ID`). */
+    localId: string;
+    verdict: SurfaceVerdict;
+    /** Store the entry physically lives in, or null when not found. */
+    storeAlias: string | null;
+    /** Whether that store is in this project's read-set (null when not found). */
+    storeBound: boolean | null;
+    /** Entry's semantic_scope coordinate (audience axis), or null. */
+    semanticScope: string | null;
+    /** This repo's bound project coordinate segment, or null when unbound. */
+    activeProject: string | null;
+    /** Entry's relevance_scope (timing axis); defaults to "broad" when absent. */
+    relevanceScope: "broad" | "narrow" | null;
+}
+declare function explainWhyNotSurfaced(projectRoot: string, query: string): Promise<WhyNotSurfacedResult>;
+
 /**
- * Append-evidence-on-collision service for fab_extract_knowledge.
+ * Append-evidence-on-collision service for fab_propose.
  *
  * Idempotency_key = sha256({source_session: source_sessions[0], type, slug}).
  * The `source_session` key inside the hash payload is FROZEN for backward
@@ -523,10 +591,12 @@ declare function runDoctorConflictLint(projectRoot: string, opts?: {
 declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledgeInput): Promise<FabExtractKnowledgeOutput>;
 
 /**
- * v2.0 rc.3 fab_review service.
+ * v2.0 rc.3 fab_review service (W3-K K2: WRITE-only).
  *
- * Pure async dispatcher over a discriminated union of 6 actions (list, approve,
- * reject, modify, search, defer). All branches are implemented as of TASK-002.
+ * Pure async dispatcher over a discriminated union of 6 WRITE actions (approve,
+ * reject, modify, modify-content, modify-layer, defer). The two READ actions
+ * (list / search) were lifted out into `reviewPending` (the fab_pending tool) —
+ * pure relocation, ZERO behavior change.
  *
  * Approve performs late-bind id allocation (KP-/KT- + type-code + monotonic
  * counter via KnowledgeIdAllocator), emits 2-phase events (knowledge_promote_started
@@ -540,6 +610,19 @@ declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledg
  * the file across layer roots, emits knowledge_layer_changed.
  */
 declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Promise<FabReviewOutput>;
+/**
+ * fab_pending service (W3-K K2: READ-only).
+ *
+ * Pure async dispatcher over the two READ actions (list / search) relocated
+ * 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.
+ * 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>;
 
 /** A summary to be cold-judged, keyed by its stable_id. */
 interface ColdEvalCandidate {
@@ -662,12 +745,16 @@ type PlanContextResult = {
     entries: PlanContextEntry[];
     intent?: string;
     candidates: RuleDescriptionIndexItem[];
-    omitted_candidate_count?: number;
+    dropped?: {
+        id: string;
+        reason: "retrieval_budget" | "payload_budget";
+    }[];
     preflight_diagnostics: PreflightDiagnostic[];
     auto_healed?: boolean;
     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. */
@@ -703,15 +790,20 @@ type RecallInput = PlanContextInput & {
      */
     include_related?: boolean;
 };
-type RecallPath = {
+type RecallEntry = {
     stable_id: string;
-    path: string;
+    rank: number;
+    description: PlanContextResult["candidates"][number]["description"];
+    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"> & {
-    paths: RecallPath[];
+type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget" | "entries" | "candidates" | "candidate_scores"> & {
+    entries: RecallEntry[];
     directive: string;
     next_steps?: string[];
 };
@@ -857,4 +949,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, type RecallInput, type RecallResult, type RequirementProfile, type SelectionTokenState, type ShutdownHandlerDeps, type UnboundProjectViolation, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, bumpCounter, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, detectUnboundProject, drainCounters, enrichDescriptions, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, lintConflicts, loadConflictEntries, pairSimilarity, planContext, readEventLedger, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, 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, 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 };