@fenglimg/fabric-server 2.3.0-rc.8 → 2.3.0

package/README.md

@@ -7,7 +7,8 @@ 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_propose` — persist a pending knowledge entry
-- `fab_review` — list / approve / reject / modify / defer pending entries
+- `fab_pending` — read-only browse/search of pending + canonical knowledge (`list` / `search`)
+- `fab_review` — write-only triage of pending knowledge (`approve` / `reject` / `modify` / `modify-content` / `modify-content-batch` / `modify-layer` / `defer` / `retire`)
 
 ## Install
 

package/dist/index.d.ts

@@ -32,6 +32,122 @@ 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;
+
+/**
+ * doctor-types.ts — pure public report/check types for the doctor subsystem.
+ *
+ * Wave W1 extraction from doctor.ts (repo-hygiene-slim). No runtime logic —
+ * only type aliases. doctor.ts re-exports these for backward-compatible
+ * `import type { DoctorCheck } from "./doctor.js"` consumers.
+ */
+
+type DoctorStatus = "ok" | "warn" | "error";
+type DoctorIssueKind = "fixable_error" | "manual_error" | "warning" | "info";
+type DoctorCheck = {
+    name: string;
+    status: DoctorStatus;
+    message: string;
+    kind?: DoctorIssueKind;
+    code?: string;
+    fixable?: boolean;
+    actionHint?: string;
+    audience?: "user" | "maintainer";
+};
+type DoctorIssue = {
+    code: string;
+    name: string;
+    message: string;
+    path?: string;
+    actionHint?: string;
+    audience?: "user" | "maintainer";
+};
+type DoctorPayloadLimits = {
+    warn_bytes: number;
+    hard_bytes: number;
+    source: "default" | "config";
+};
+type DoctorSummary = {
+    target: string;
+    framework: {
+        kind: string;
+        version: string;
+        subkind: string;
+    };
+    entryPoints: Array<{
+        path: string;
+        reason: string;
+    }>;
+    metaRevision: string | null;
+    computedMetaRevision: string | null;
+    ruleCount: number;
+    eventLedgerPath: string;
+    fixableErrorCount: number;
+    manualErrorCount: number;
+    warningCount: number;
+    infoCount: number;
+    targetFiles: Record<string, boolean>;
+    payload_limits: DoctorPayloadLimits;
+    health: DoctorHealth;
+};
+type DoctorReport = {
+    status: DoctorStatus;
+    checks: DoctorCheck[];
+    fixable_errors: DoctorIssue[];
+    manual_errors: DoctorIssue[];
+    warnings: DoctorIssue[];
+    infos: DoctorIssue[];
+    summary: DoctorSummary;
+};
+type DoctorFixReport = {
+    changed: boolean;
+    fixed: DoctorIssue[];
+    remaining_manual_errors: DoctorIssue[];
+    warnings: DoctorIssue[];
+    message: string;
+    report: DoctorReport;
+};
+type DoctorApplyLintMutationKind = "knowledge_session_hints_stale_cleanup" | "store_counter_floor";
+type DoctorApplyLintMutation = {
+    kind: DoctorApplyLintMutationKind;
+    path: string;
+    detail: string;
+    applied: boolean;
+    error?: string;
+};
+type DoctorApplyLintReport = {
+    changed: boolean;
+    mutations: DoctorApplyLintMutation[];
+    warnings: DoctorIssue[];
+    manual_errors: DoctorIssue[];
+    aborted: boolean;
+    abort_reason?: string;
+    message: string;
+    report: DoctorReport;
+};
+type EnrichDescriptionsMode = "auto" | "preview" | "readonly" | "interactive";
+type EnrichDescriptionsCandidate = {
+    path: string;
+    missing: Array<"intent_clues" | "tech_stack" | "impact" | "must_read_if">;
+    modified: boolean;
+    added_fields: Array<"intent_clues" | "tech_stack" | "impact" | "must_read_if">;
+    error?: string;
+};
+type EnrichDescriptionsReport = {
+    mode: EnrichDescriptionsMode;
+    dryRun: boolean;
+    scanned: number;
+    modified: number;
+    skipped: number;
+    candidates: EnrichDescriptionsCandidate[];
+};
 
 declare function extractRuleDescription(source: string): RuleDescription | undefined;
 
@@ -44,7 +160,11 @@ interface AlwaysActiveBody {
     /** description.summary — the overflow-degrade fallback when the body cannot
      *  fit the injection char budget (the budget is enforced hook-side, D10). */
     summary: string;
-    /** frontmatter-stripped markdown body. */
+    /**
+     * ISS-20260713-014 / KT-DEC-0036: SessionStart wire is index-only.
+     * Body is empty on this path; full text via Read/fab_recall.
+     * Field retained for wire compatibility.
+     */
     body: string;
 }
 /**
@@ -80,6 +200,7 @@ interface KnowledgeCensus {
  */
 declare function buildKnowledgeCensus(projectRoot: string): Promise<KnowledgeCensus>;
 declare function buildAlwaysActiveBodies(projectRoot: string): Promise<AlwaysActiveBody[]>;
+declare function computeReadSetRevision(projectRoot: string): Promise<string>;
 interface StoreCanonicalEntry {
     stableId: string;
     qualifiedId: string;
@@ -169,6 +290,7 @@ type MetricsRow = {
  * dual-write allowlist below.
  */
 declare const METRIC_COUNTER_NAMES: {
+    readonly knowledge_body_read: "knowledge_body_read";
     readonly knowledge_consumed: "knowledge_consumed";
     readonly edit_intent_checked: "edit_intent_checked";
     readonly knowledge_context_planned: "knowledge_context_planned";
@@ -253,6 +375,7 @@ declare function runDoctorCiteCoverage(projectRoot: string, options: {
     until?: number;
     recallWindowMs?: number;
 }): Promise<CiteCoverageReport>;
+
 type ArchiveHistoryEntry = {
     session_id_short: string;
     last_attempted_at: string;
@@ -288,109 +411,10 @@ declare function runDoctorHistoryAll(projectRoot: string, options: {
     since: number;
 }): Promise<HistoryAllReport>;
 
-type DoctorStatus = "ok" | "warn" | "error";
-type DoctorIssueKind = "fixable_error" | "manual_error" | "warning" | "info";
-type DoctorCheck = {
-    name: string;
-    status: DoctorStatus;
-    message: string;
-    kind?: DoctorIssueKind;
-    code?: string;
-    fixable?: boolean;
-    actionHint?: string;
-    audience?: "user" | "maintainer";
-};
-type DoctorIssue = {
-    code: string;
-    name: string;
-    message: string;
-    path?: string;
-    actionHint?: string;
-    audience?: "user" | "maintainer";
-};
-type DoctorPayloadLimits = {
-    warn_bytes: number;
-    hard_bytes: number;
-    source: "default" | "config";
-};
-type DoctorSummary = {
-    target: string;
-    framework: {
-        kind: string;
-        version: string;
-        subkind: string;
-    };
-    entryPoints: Array<{
-        path: string;
-        reason: string;
-    }>;
-    metaRevision: string | null;
-    computedMetaRevision: string | null;
-    ruleCount: number;
-    eventLedgerPath: string;
-    fixableErrorCount: number;
-    manualErrorCount: number;
-    warningCount: number;
-    infoCount: number;
-    targetFiles: Record<string, boolean>;
-    payload_limits: DoctorPayloadLimits;
-    health: DoctorHealth;
-};
-type DoctorReport = {
-    status: DoctorStatus;
-    checks: DoctorCheck[];
-    fixable_errors: DoctorIssue[];
-    manual_errors: DoctorIssue[];
-    warnings: DoctorIssue[];
-    infos: DoctorIssue[];
-    summary: DoctorSummary;
-};
-type DoctorFixReport = {
-    changed: boolean;
-    fixed: DoctorIssue[];
-    remaining_manual_errors: DoctorIssue[];
-    warnings: DoctorIssue[];
-    message: string;
-    report: DoctorReport;
-};
-type DoctorApplyLintMutationKind = "knowledge_orphan_demote_required" | "knowledge_stale_archive_required" | "knowledge_index_drift" | "knowledge_pending_auto_archive" | "knowledge_session_hints_stale_cleanup" | "knowledge_relevance_fields_missing";
-type DoctorApplyLintMutation = {
-    kind: DoctorApplyLintMutationKind;
-    path: string;
-    detail: string;
-    applied: boolean;
-    error?: string;
-};
-type DoctorApplyLintReport = {
-    changed: boolean;
-    mutations: DoctorApplyLintMutation[];
-    warnings: DoctorIssue[];
-    manual_errors: DoctorIssue[];
-    aborted: boolean;
-    abort_reason?: string;
-    message: string;
-    report: DoctorReport;
-};
 declare function runDoctorReport(target: string): Promise<DoctorReport>;
 declare function runDoctorFix(target: string): Promise<DoctorFixReport>;
 declare function runDoctorApplyLint(target: string): Promise<DoctorApplyLintReport>;
 
-type EnrichDescriptionsMode = "auto" | "preview" | "readonly" | "interactive";
-type EnrichDescriptionsCandidate = {
-    path: string;
-    missing: Array<"intent_clues" | "tech_stack" | "impact" | "must_read_if">;
-    modified: boolean;
-    added_fields: Array<"intent_clues" | "tech_stack" | "impact" | "must_read_if">;
-    error?: string;
-};
-type EnrichDescriptionsReport = {
-    mode: EnrichDescriptionsMode;
-    dryRun: boolean;
-    scanned: number;
-    modified: number;
-    skipped: number;
-    candidates: EnrichDescriptionsCandidate[];
-};
 declare function enrichDescriptions(projectRoot: string, opts?: {
     auto?: boolean;
     dryRun?: boolean;
@@ -646,6 +670,12 @@ declare function explainWhyNotSurfaced(projectRoot: string, query: string): Prom
  */
 declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledgeInput): Promise<FabExtractKnowledgeOutput>;
 
+/**
+ * fab_review / fab_pending facade (ISS-20260713-013).
+ * Action implementations live in review-write-actions / review-search;
+ * path/sandbox/list helpers in review-shared; frontmatter in review-frontmatter.
+ */
+
 /**
  * v2.0 rc.3 fab_review service (W3-K K2: WRITE-only).
  *
@@ -892,6 +922,26 @@ declare function readEventLedger(projectRoot: string, options?: ReadEventLedgerO
  */
 declare function flushAndSyncEventLedger(projectRoot: string): void;
 
+/**
+ * ISS-20260713-011: selection_token mint / LRU cache for plan-context.
+ */
+type SelectionTokenState = {
+    token: string;
+    revision_hash: string;
+    target_paths: string[];
+    required_stable_ids: string[];
+    ai_selectable_stable_ids: string[];
+    created_at: number;
+    expires_at: number;
+};
+declare function readSelectionToken(token: string, now?: number): SelectionTokenState | undefined;
+
+/**
+ * planContext facade (ISS-20260713-011).
+ * Scoring / BM25 cache / selection-token live in dedicated modules;
+ * this file orchestrates the plan-context pipeline and re-exports the public API.
+ */
+
 type PlanContextInput = {
     paths: string[];
     intent?: string;
@@ -958,17 +1008,7 @@ type PlanContextResult = {
     /** Internal service→tool signal; stripped before MCP output. */
     payload_over_budget?: boolean;
 };
-type SelectionTokenState = {
-    token: string;
-    revision_hash: string;
-    target_paths: string[];
-    required_stable_ids: string[];
-    ai_selectable_stable_ids: string[];
-    created_at: number;
-    expires_at: number;
-};
 declare function planContext(projectRoot: string, input: PlanContextInput): Promise<PlanContextResult>;
-declare function readSelectionToken(token: string, now?: number): SelectionTokenState | undefined;
 
 type RecallInput = PlanContextInput & {
     /**
@@ -987,25 +1027,35 @@ type RecallInput = PlanContextInput & {
      * (W1-3 / KT-DEC-0031: surface the related id, do not fetch its body).
      */
     include_related?: boolean;
+    /**
+     * TASK-006 (KT-PIT-0036 observability opt-in): when true, populate
+     * `entry.score_breakdown` with the numbers-only signal decomposition
+     * (bm25/vector/salience/recency/locality/proximity/credibility → final).
+     * Off by default for wire efficiency. Enable when debugging ranking or tuning
+     * scoring weights. The final===score invariant is enforced at the plan-context
+     * service layer (candidate_scores Map) regardless of this flag.
+     */
+    include_score_breakdown?: boolean;
 };
 type FullRuleDescription = PlanContextResult["candidates"][number]["description"];
-type RecallEntryDescription = Pick<FullRuleDescription, "summary" | "must_read_if" | "intent_clues"> & Partial<Pick<FullRuleDescription, "knowledge_type">>;
+type RecallEntryDescription = Pick<FullRuleDescription, "summary"> & Partial<Pick<FullRuleDescription, "must_read_if" | "impact" | "knowledge_type">>;
 type RecallEntry = {
     stable_id: string;
-    rank: number;
     description: RecallEntryDescription;
     read_path?: string;
-    store?: {
-        alias: 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" | "candidate_scores"> & {
+type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget" | "entries" | "candidates" | "candidate_scores" | "stale" | "intent" | "dropped" | "preflight_diagnostics"> & {
     entries: RecallEntry[];
-    directive: string;
     next_steps?: string[];
+    dropped_ids?: string[];
+    dropped_reasons?: {
+        retrieval_budget?: number;
+        payload_budget?: number;
+    };
+    preflight_diagnostics?: PreflightDiagnostic[];
 };
 declare function recall(projectRoot: string, input: RecallInput): Promise<RecallResult>;
 
@@ -1123,7 +1173,33 @@ declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
 declare function formatPreexistingRootMessage(projectRoot: string): string | null;
 
 declare const FABRIC_SERVER_INSTRUCTIONS: string;
+declare function buildServerInstructions(projectRoot: string): string;
 declare function createFabricServer(tracker?: InFlightTracker): McpServer;
+/**
+ * The slice of the MCP `Server` the roots adoption consumes — injectable so
+ * tests can drive it without a live transport.
+ */
+interface McpRootsSource {
+    getClientCapabilities(): {
+        roots?: unknown;
+    } | undefined;
+    listRoots(): Promise<{
+        roots: Array<{
+            uri?: string;
+        }>;
+    }>;
+}
+/**
+ * ISS werewolf-minigame (rootless MCP spawn, KT-PIT-0046): fetch the client's
+ * workspace roots (when the client declares the `roots` capability) and record
+ * them as project-root candidates via `setMcpRootsHint`. Returns the accepted
+ * absolute paths ([] when the capability is absent or the fetch fails —
+ * best-effort, never sinks startup). Called from `oninitialized`; the
+ * env > CLAUDE_PROJECT_DIR > roots > cwd priority lives in
+ * `resolveProjectRoot`, which every tool call re-runs, so adoption heals
+ * subsequent calls without a restart.
+ */
+declare function adoptMcpClientRoots(source: McpRootsSource): Promise<string[]>;
 declare function startStdioServer(): Promise<void>;
 /**
  * Dependencies for the shutdown handler factory. Tests inject `exit` to assert
@@ -1149,4 +1225,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, 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 };
+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 McpRootsSource, 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, adoptMcpClientRoots, aggregateConsumption, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, buildRelatedGraph, buildServerInstructions, bumpCounter, checkBacklogAge, clearPrecheckCache, collectStoreCanonicalEntries, computeReadSetRevision, 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 };