@fenglimg/fabric-server 2.2.0-rc.9 → 2.3.0-rc.1

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,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { FabExtractKnowledgeInput, FabExtractKnowledgeOutput, FabReviewInput, FabReviewOutput } from '@fenglimg/fabric-shared/schemas/api-contracts';
+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 { PayloadGuardOptions } from '@fenglimg/fabric-shared/node/mcp-payload-guard';
 
@@ -62,6 +62,9 @@ interface KnowledgeCensus {
         personal: number;
         project: number;
     };
+    broad_by_type: Record<string, number>;
+    /** count of narrow-scope kept entries (file-specific; only合计, not per-type). */
+    narrow_total: number;
     /** entries专属 to OTHER projects that filterByActiveProject removed. */
     dropped_other_project: number;
     /** kept (post-filter) total. */
@@ -376,24 +379,26 @@ 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;
 }
 /**
- * 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;
 
@@ -502,8 +507,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
@@ -520,10 +568,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
@@ -537,6 +587,17 @@ 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.
+ * The underlying listPending / searchEntries helpers are unchanged (verbatim
+ * relocation), so behavior is identical to the prior fab_review list/search.
+ */
+declare function reviewPending(projectRoot: string, input: FabPendingInput): Promise<FabPendingOutput>;
 
 /** A summary to be cold-judged, keyed by its stable_id. */
 interface ColdEvalCandidate {
@@ -659,7 +720,10 @@ 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;
@@ -700,15 +764,18 @@ 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;
 };
-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"> & {
+    entries: RecallEntry[];
     directive: string;
     next_steps?: string[];
 };
@@ -854,4 +921,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 };