@fenglimg/fabric-server 2.2.0-rc.4 → 2.2.0-rc.9

package/README.md

@@ -1,12 +1,11 @@
 # @fenglimg/fabric-server
 
-Fabric MCP knowledge server. Runs over stdio transport and serves Claude Code, Cursor, and Codex CLI from a single `.fabric/` directory.
+Fabric MCP knowledge server. Runs over stdio transport and serves Claude Code and Codex CLI from a single `.fabric/` directory.
 
 ## Tools exposed
 
-- `fab_plan_context` — neutral rule description index + selection token
-- `fab_get_knowledge_sections` — fetch full markdown bodies by stable_id
-- `fab_recall` — combined one-call recall (plan + sections), the rc.37+ default
+- `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_review` — list / approve / reject / modify / defer pending entries
 

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 { PayloadGuardOptions } from '@fenglimg/fabric-shared/node/mcp-payload-guard';
 
 interface InFlightTracker {
     enter(requestId: string): void;
@@ -22,6 +23,67 @@ declare function getLegacyLedgerPath(projectRoot: string): string;
 declare function getEventLedgerPath(projectRoot: string): string;
 declare function getMetricsLedgerPath(projectRoot: string): string;
 
+type DoctorHealth = {
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    penalties: {
+        manual_errors: number;
+        fixable_errors: number;
+        warnings: number;
+    };
+};
+
+interface AlwaysActiveBody {
+    /** store-qualified id (`<alias>:<stableId>`). */
+    stable_id: string;
+    /** knowledge_type — one of ALWAYS_ACTIVE_TYPES. */
+    type: string;
+    layer: "team" | "personal";
+    /** 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. */
+    body: string;
+}
+/**
+ * Collect the always-active (guidelines + models) entries from the project's
+ * read-set, project-filtered identically to recall (filterByActiveProject), with
+ * their frontmatter-stripped bodies. The SessionStart hook injects these bodies
+ * into the AI context and renders category counts for the on-demand remainder.
+ *
+ * Returns [] (never throws) on any read-set resolution failure — the SessionStart
+ * banner must degrade gracefully, never crash session start.
+ */
+interface KnowledgeCensus {
+    /** knowledge_type → count (decisions/pitfalls/guidelines/models/processes). */
+    by_type: Record<string, number>;
+    by_layer: {
+        team: number;
+        personal: number;
+        project: number;
+    };
+    /** entries专属 to OTHER projects that filterByActiveProject removed. */
+    dropped_other_project: number;
+    /** kept (post-filter) total. */
+    total: number;
+}
+/**
+ * Build the read-set census (project-filtered counts + dropped-other-project).
+ * Reuses the cached read-set walk, so calling alongside buildAlwaysActiveBodies
+ * in one SessionStart fire costs a single walk. Never throws — degrades to an
+ * all-zero census so the banner stays renderable.
+ */
+declare function buildKnowledgeCensus(projectRoot: string): Promise<KnowledgeCensus>;
+declare function buildAlwaysActiveBodies(projectRoot: string): Promise<AlwaysActiveBody[]>;
+
+interface UnboundProjectViolation {
+    /** The store already bound as the active write target. */
+    alias: string;
+    /** Which project-scope fields are absent: `project_id` and/or `active_project`. */
+    missing: string[];
+}
+declare function detectUnboundProject(projectRoot: string): UnboundProjectViolation | null;
+
 /**
  * O(1) in-memory increment for a named counter. Safe to call from any MCP
  * tool handler; no I/O happens until the next `flushMetrics()` call.
@@ -81,11 +143,15 @@ type MetricsRow = {
     counters: Record<string, number>;
 };
 /**
- * Canonical metric counter names used by the high-frequency emitters that
- * left events.jsonl as part of the rc.37 Wave B clean-slate. Centralized
- * here so the B5 hard-gate (`metric_event_in_jsonl`) can grep for these
- * exact strings and fail when one accidentally re-appears in the audit
- * ledger emit path.
+ * Canonical metric counter names. rc.37 Wave B added a metrics.jsonl counter
+ * rollup for each (the forward-compatible signal), but — contrary to the
+ * original "these left events.jsonl" plan — every one is ALSO still appended to
+ * the audit ledger as a structured event, because a doctor lint consumes its
+ * per-id / per-path payload (see LEDGER_DUAL_WRITE_METRIC_NAMES below). The
+ * promised counter-only cutover (rc.38+; tracked by the G11 invariant test) has
+ * not happened. Centralized here so the B5 hard-gate (`metric_event_in_jsonl`)
+ * can grep for these exact strings; the gate only flags names NOT in the
+ * dual-write allowlist below.
  */
 declare const METRIC_COUNTER_NAMES: {
     readonly knowledge_consumed: "knowledge_consumed";
@@ -113,7 +179,7 @@ type CiteCoverageReport = {
     marker_ts: number;
     marker_emitted_now: boolean;
     since_ts: number;
-    client_filter: "cc" | "codex" | "cursor" | "all";
+    client_filter: "cc" | "codex" | "all";
     layer_filter?: "team" | "personal" | "all";
     metrics: {
         edits_touched: number;
@@ -162,7 +228,7 @@ type CiteCoverageReport = {
 };
 declare function runDoctorCiteCoverage(projectRoot: string, options: {
     since: number;
-    client: "cc" | "codex" | "cursor" | "all";
+    client: "cc" | "codex" | "all";
     layer?: "team" | "personal" | "all";
     until?: number;
     recallWindowMs?: number;
@@ -250,15 +316,6 @@ type DoctorSummary = {
     payload_limits: DoctorPayloadLimits;
     health: DoctorHealth;
 };
-type DoctorHealth = {
-    score: number;
-    grade: "A" | "B" | "C" | "D" | "F";
-    penalties: {
-        manual_errors: number;
-        fixable_errors: number;
-        warnings: number;
-    };
-};
 type DoctorReport = {
     status: DoctorStatus;
     checks: DoctorCheck[];
@@ -287,6 +344,7 @@ type DoctorApplyLintMutation = {
 type DoctorApplyLintReport = {
     changed: boolean;
     mutations: DoctorApplyLintMutation[];
+    warnings: DoctorIssue[];
     manual_errors: DoctorIssue[];
     aborted: boolean;
     abort_reason?: string;
@@ -296,6 +354,7 @@ type DoctorApplyLintReport = {
 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;
@@ -479,6 +538,37 @@ declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledg
  */
 declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Promise<FabReviewOutput>;
 
+/** A summary to be cold-judged, keyed by its stable_id. */
+interface ColdEvalCandidate {
+    stable_id: string;
+    summary: string;
+}
+/** The verdict the external cold-eval judge returns per candidate. */
+interface ColdEvalVerdict {
+    stable_id: string;
+    /** true when the summary alone is act-on sufficient without the body. */
+    self_sufficient: boolean;
+    /** When not self-sufficient, the judge's suggested act-on rewrite. */
+    suggested_summary?: string;
+    /** Short rationale (pointer-vs-thesis) for the verdict. */
+    reason?: string;
+}
+/** The batch request handed to the external (maestro delegate) cold-eval judge. */
+interface ColdEvalBatch {
+    rubric: string;
+    candidates: ColdEvalCandidate[];
+}
+declare const COLD_EVAL_RUBRIC: string;
+/**
+ * Build the cold-eval batch request for the external judge. Pure + deterministic:
+ * drops blank summaries (nothing to judge) and pairs the candidates with the
+ * zero-context rubric. The fabric-review skill hands the result to
+ * `maestro delegate` and applies the returned {@link ColdEvalVerdict}[] via
+ * fab_review modify. Returns a batch with an empty candidate list when nothing is
+ * judgeable, so callers can short-circuit without a delegate round-trip.
+ */
+declare function buildColdEvalBatch(candidates: ColdEvalCandidate[]): ColdEvalBatch;
+
 type StoredEventLedgerEvent = EventLedgerEvent;
 type ReadEventLedgerOptions = {
     event_type?: EventLedgerEvent["event_type"];
@@ -529,11 +619,26 @@ type PlanContextInput = {
     target_paths?: string[];
     layer_filter?: "team" | "personal" | "both";
     include_related?: boolean;
+    /**
+     * Internal MCP presentation budget. When supplied by the tool layer,
+     * candidates are byte-trimmed before the selection token is cached so the
+     * token cannot reference candidates omitted from the response.
+     */
+    payload_budget?: PlanContextPayloadBudget;
+};
+type PlanContextPayloadWarning = {
+    code: string;
+    file?: string;
+    action_hint?: string;
+};
+type PlanContextPayloadBudget = {
+    limits?: PayloadGuardOptions;
+    warnings?: PlanContextPayloadWarning[];
+    trim_warning?: PlanContextPayloadWarning;
 };
 type RequirementProfile = {
     target_path: string;
     known_tech: string[];
-    user_intent: string;
     detected_entities: string[];
 };
 type PlanContextEntry = {
@@ -552,6 +657,7 @@ type PlanContextResult = {
     stale: boolean;
     selection_token: string;
     entries: PlanContextEntry[];
+    intent?: string;
     candidates: RuleDescriptionIndexItem[];
     omitted_candidate_count?: number;
     preflight_diagnostics: PreflightDiagnostic[];
@@ -559,6 +665,10 @@ type PlanContextResult = {
     previous_revision_hash?: string;
     redirects?: Record<string, string>;
     related_appended?: Record<string, string>;
+    /** Internal service→tool signal; stripped before MCP output. */
+    payload_trimmed?: boolean;
+    /** Internal service→tool signal; stripped before MCP output. */
+    payload_over_budget?: boolean;
 };
 type SelectionTokenState = {
     token: string;
@@ -574,45 +684,33 @@ declare function readSelectionToken(token: string, now?: number): SelectionToken
 
 type RecallInput = PlanContextInput & {
     /**
-     * Optional explicit set of stable_ids to fetch bodies for. When omitted,
-     * fab_recall picks up every stable_id surfaced in the shared description
-     * index (the common case after rc.37 selectable-filter removal). When
-     * provided, filters the fetched body set to this intersection.
+     * Optional explicit set of stable_ids to SCOPE the returned read paths to.
+     * When omitted, `paths` carries one entry per surfaced candidate. The candidate
+     * DESCRIPTION index is always returned in full for discovery — `ids` only narrows
+     * which read paths are surfaced (e.g. `recall(ids)` when the agent already knows
+     * which entries it wants to Read). Stale (pre layer-flip) ids are redirect-rewritten
+     * before the match.
      */
     ids?: string[];
     /**
-     * v2.2 MC1-recall-pack (W2-T4): when true, expand the fetched set with the
-     * one-hop `related` graph neighbours (H2) of the selected entries that are
-     * also present in the candidate index. Lets a scoped `ids` recall pull in the
-     * connected knowledge without a second round-trip. No-op when `ids` is omitted
-     * (every candidate is already fetched) or no related edges resolve in-corpus.
+     * When true, forwarded to planContext, which appends the one-hop `related` graph
+     * neighbours (H2) of the surfaced set to the candidate index (descriptions only —
+     * NO body). Their read paths are included in `paths` like any other candidate
+     * (W1-3 / KT-DEC-0031: surface the related id, do not fetch its body).
      */
     include_related?: boolean;
 };
-type RecallTruncation = {
-    omitted_candidate_count: number;
-    returned_candidate_count: number;
+type RecallPath = {
+    stable_id: string;
+    path: string;
+    store?: {
+        alias: string;
+    };
 };
-type RecallResult = PlanContextResult & {
-    rules: Array<{
-        stable_id: string;
-        level: "L0" | "L1" | "L2";
-        path: string;
-        body: string;
-        store?: {
-            alias: string;
-        };
-    }>;
-    selected_stable_ids: string[];
-    diagnostics: Array<{
-        code: "missing_knowledge_metadata" | "unresolved_selected_id";
-        severity: "warn";
-        stable_id: string;
-        message: string;
-    }>;
+type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget"> & {
+    paths: RecallPath[];
     directive: string;
     next_steps?: string[];
-    truncation?: RecallTruncation;
 };
 declare function recall(projectRoot: string, input: RecallInput): Promise<RecallResult>;
 
@@ -680,65 +778,6 @@ declare class ContextCache {
 }
 declare const contextCache: ContextCache;
 
-interface KnowledgeSyncOptions {
-    mode?: "incremental" | "full";
-    /** When true, invalid frontmatter throws RuleValidationError (default: false — collect as warning). */
-    throwOnInvalidFrontmatter?: boolean;
-    /**
-     * v2.0.0-rc.29 TASK-005 (BUG-G1): originally opted the hot path into a
-     * follow-up `reconcileKnowledge` (rewrite agents.meta.json) so every
-     * detected drift got a paired heal event.
-     *
-     * v2.2 W5 R2 (agents.meta decolo): retained as a NO-OP for backward
-     * compatibility — the co-location agents.meta.json it used to rebuild no
-     * longer exists (knowledge lives in stores; read paths cut over to the
-     * cross-store model). MCP tool call sites still pass `autoHealOnDrift: true`;
-     * it is now ignored.
-     */
-    autoHealOnDrift?: boolean;
-}
-interface StructuredWarning {
-    code: string;
-    file: string;
-    line?: number;
-    action_hint: string;
-}
-/**
- * Granular ledger event shape for knowledge-sync operations.
- * These are returned in KnowledgeSyncReport and also appended to the event ledger
- * using the nearest available ledger event type (knowledge_drift_detected).
- * The shape below is what callers receive in `.events`.
- */
-interface KnowledgeSyncLedgerEvent {
-    type: "rule_content_changed" | "rule_added" | "rule_removed";
-    stable_id: string;
-    path: string;
-    prev_hash: string | null;
-    new_hash: string | null;
-    changed_fields: string[];
-    source: "ensureKnowledgeFresh" | "reconcileKnowledge";
-}
-/** Alias so the public API says LedgerEvent (as documented). */
-type LedgerEvent = KnowledgeSyncLedgerEvent;
-interface KnowledgeSyncReport {
-    status: "fresh" | "reconciled" | "errors";
-    events: LedgerEvent[];
-    warnings: StructuredWarning[];
-    reconciled_files?: string[];
-}
-/**
- * Clear the knowledge-sync cooldown for a projectRoot so the next ensureKnowledgeFresh
- * call performs a real I/O scan. Called by the chokidar watcher when a rule
- * file changes (see http.ts handleCacheWatcherEvent).
- */
-declare function invalidateKnowledgeSyncCooldown(projectRoot: string): void;
-/**
- * Detects drift between disk and agents.meta.json, emits ledger events, and
- * invalidates the cache. Does NOT rewrite agents.meta.json. Optimised for
- * hot-path consumers (MCP tools).
- */
-declare function ensureKnowledgeFresh(projectRoot: string, opts?: KnowledgeSyncOptions): Promise<KnowledgeSyncReport>;
-
 type LedgerSourceFilter = "ai" | "human";
 type StoredLedgerEntry = LedgerEntry & {
     id: string;
@@ -815,4 +854,4 @@ interface ShutdownHandlerDeps {
  */
 declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 
-export { AGENTS_MD_RESOURCE_URI, type ArchiveHistoryEntry, type ArchiveHistoryReport, type CiteCoverageReport, 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 KnowledgeSyncLedgerEvent, type KnowledgeSyncOptions, type KnowledgeSyncReport, LEDGER_PATH, LEGACY_LEDGER_PATH, type LedgerEvent, 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 StructuredWarning, appendEventLedgerEvent, bumpCounter, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, drainCounters, enrichDescriptions, ensureKnowledgeFresh, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, invalidateKnowledgeSyncCooldown, 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, 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 };