@fenglimg/fabric-server 2.1.0-rc.2 → 2.2.0-rc.10

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { AgentsMeta, KnowledgeTestIndex, AgentsLayer, AgentsTopologyType, KnowledgeType, Layer, StableId, AgentsMetaCounters, EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem } from '@fenglimg/fabric-shared';
 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,90 +23,147 @@ declare function getLegacyLedgerPath(projectRoot: string): string;
 declare function getEventLedgerPath(projectRoot: string): string;
 declare function getMetricsLedgerPath(projectRoot: string): string;
 
-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;
+type DoctorHealth = {
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    penalties: {
+        manual_errors: number;
+        fixable_errors: number;
+        warnings: number;
     };
-    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;
 };
-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;
+
+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;
+    };
+    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. */
+    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.
+ *
+ * `delta` defaults to 1; callers can pass a positive integer (e.g. fetched
+ * N stable_ids in a single sections call) to fold N bumps into one.
+ */
+declare function bumpCounter(projectRoot: string, name: string, delta?: number): void;
+/**
+ * Snapshot the current counter accumulator and reset it. Returned map is a
+ * frozen copy; the live accumulator starts fresh from zero. Exposed so
+ * flushMetrics + tests + a future fab_metrics manual-flush CLI hook can all
+ * use the same primitive without racing.
+ */
+declare function drainCounters(projectRoot: string): Record<string, number>;
+/**
+ * Drain the current accumulator and append one JSONL row to
+ * `.fabric/metrics.jsonl`. Returns the appended row (or `null` when the
+ * accumulator was empty — no spurious zero rows). fs failures degrade
+ * silently; the next flush will carry the union of the failed-write
+ * interval + the current one.
+ */
+declare function flushMetrics(projectRoot: string, options?: {
+    windowMs?: number;
+    now?: Date;
+}): Promise<MetricsRow | null>;
+/**
+ * Start the background flush timer for a project root. Idempotent — calling
+ * twice on the same root replaces the prior interval. Returns a stop handle
+ * the caller can invoke at shutdown to flush + clear the timer.
+ *
+ * The flush is fire-and-forget (no await on the setInterval callback) so
+ * the timer cadence stays accurate even when fs is slow.
+ */
+declare function startMetricsFlush(projectRoot: string, options?: {
+    intervalMs?: number;
+}): () => Promise<void>;
+/**
+ * Cancel the background flush timer for a project root if one is running.
+ * Does NOT drain the accumulator — callers that want a final flush should
+ * await flushMetrics(projectRoot) afterward.
+ */
+declare function stopMetricsFlush(projectRoot: string): void;
+/**
+ * Read accumulated metrics rows from `.fabric/metrics.jsonl`. Missing file
+ * returns []. Malformed rows are dropped silently (the sidecar is best-
+ * effort observability; a corrupt row never blocks a reader).
+ *
+ * Exposed for the NEW-34 `fab metrics` CLI dashboard + future doctor lints
+ * (e.g. cite-goodhart pattern replay) that need counter trends without
+ * walking events.jsonl.
+ */
+declare function readMetrics(projectRoot: string): Promise<MetricsRow[]>;
+type MetricsRow = {
+    timestamp: string;
+    window: string;
+    counters: Record<string, number>;
 };
-type DoctorApplyLintReport = {
-    changed: boolean;
-    mutations: DoctorApplyLintMutation[];
-    manual_errors: DoctorIssue[];
-    aborted: boolean;
-    abort_reason?: string;
-    message: string;
-    report: DoctorReport;
+/**
+ * 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";
+    readonly edit_intent_checked: "edit_intent_checked";
+    readonly knowledge_context_planned: "knowledge_context_planned";
+    readonly knowledge_sections_fetched: "knowledge_sections_fetched";
 };
-declare function runDoctorReport(target: string): Promise<DoctorReport>;
-declare function runDoctorFix(target: string): Promise<DoctorFixReport>;
-declare function runDoctorApplyLint(target: string): Promise<DoctorApplyLintReport>;
+type MetricCounterName = (typeof METRIC_COUNTER_NAMES)[keyof typeof METRIC_COUNTER_NAMES];
+
 type CiteContractMetrics = {
     decisions_cited: number;
     pitfalls_cited: number;
@@ -124,7 +182,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;
@@ -136,6 +194,25 @@ type CiteCoverageReport = {
         compliant_cites?: number;
         noncompliant_cites?: number;
         uncorrelatable_edits?: number;
+        recall_backed_edits?: number;
+        recall_coverage_rate?: number | null;
+        exposed_and_mutated?: {
+            count: number;
+            ids?: string[];
+        };
+        mutations_observed?: {
+            count: number;
+        };
+        mutation_pool?: {
+            attributed: number;
+            unattributed_workspace_dirty: number;
+        };
+        sessions_closed?: {
+            count: number;
+        };
+        by_store?: Record<string, {
+            qualifying_cites: number;
+        }>;
     };
     per_client?: Record<string, Partial<CiteCoverageReport["metrics"]>>;
     dismissed_reason_histogram?: Record<string, number>;
@@ -154,9 +231,10 @@ 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;
 }): Promise<CiteCoverageReport>;
 type ArchiveHistoryEntry = {
     session_id_short: string;
@@ -192,6 +270,94 @@ type HistoryAllReport = {
 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;
@@ -213,84 +379,131 @@ declare function enrichDescriptions(projectRoot: string, opts?: {
     dryRun?: boolean;
 }): Promise<EnrichDescriptionsReport>;
 
-type KnowledgeMetaBuildSource = "doctor_fix" | "sync_meta";
-type KnowledgeMetaBuildResult = {
-    meta: AgentsMeta;
-    knowledgeTestIndex: KnowledgeTestIndex;
-    changed: boolean;
-};
-type WriteKnowledgeMetaOptions = {
-    source: KnowledgeMetaBuildSource;
-};
+interface Bm25Document {
+    id: string;
+    tokens: 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).
+     */
+    scoreDoc(id: string, queryTerms: string[]): number;
+}
 /**
- * v2.0-rc.24 TASK-07: Load a Map<stable_id, knowledge_type> from the
- * project's `.fabric/agents.meta.json`. Consumed by the doctor cite-coverage
- * routing (TASK-08) to dispatch cites to the correct policy bucket
- * (decision/pitfall = strict contract / model = reference-only /
- * guideline+process = deferred to rc.25 LLM-judge). Cited ids absent from
- * this map fall into the `cite_id_unresolved` bucket.
- *
- * **Plural knowledge_type contract (rc.29 BUG-C1 unification):** the returned
- * map values are the PLURAL `KnowledgeType` enum (`"models" | "decisions" |
- * "guidelines" | "pitfalls" | "processes"`) — matching disk frontmatter,
- * filesystem layout, MCP I/O surface, and the canonical `KnowledgeTypeSchema`
- * exported from `@fenglimg/fabric-shared`. Legacy singular frontmatter is
- * normalized at parse time (see `SINGULAR_TO_PLURAL` in `parseFrontmatter`);
- * downstream callers (TASK-08 doctor) match against the plural enum.
- *
- * Both team (KT-*) and personal (KP-*) entries are included — they live in
- * the same `meta.nodes` map.
- *
- * Graceful on failure: a missing meta file, malformed JSON, or schema
- * validation failure all yield an empty Map (no throw). The doctor will then
- * surface every cite as `cite_id_unresolved`, which is the safe degraded
- * mode.
+ * 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.
  */
-declare function loadKbIdTypeMap(projectRootInput: string): Promise<Map<string, KnowledgeType>>;
-declare function buildKnowledgeMeta(projectRootInput: string): Promise<KnowledgeMetaBuildResult>;
-declare function writeKnowledgeMeta(projectRootInput: string, options: WriteKnowledgeMetaOptions): Promise<KnowledgeMetaBuildResult>;
-declare function computeKnowledgeBasedAgentsMeta(projectRootInput: string, existingMeta?: AgentsMeta): Promise<AgentsMeta>;
-declare function computeKnowledgeTestIndex(projectRootInput: string, computedMeta: AgentsMeta, previousIndex?: KnowledgeTestIndex): Promise<KnowledgeTestIndex>;
-declare function deriveKnowledgeMetaLayer(relativePath: string): AgentsLayer;
-declare function deriveKnowledgeMetaTopologyType(relativePath: string): AgentsTopologyType;
-declare function isSameKnowledgeTestIndex(left: KnowledgeTestIndex, right: KnowledgeTestIndex): boolean;
-declare function stableStringify(value: unknown): string;
+declare function buildBm25Model(docs: Bm25Document[]): Bm25Model;
 
+interface ConflictEntry {
+    stable_id: string;
+    /** Plural knowledge_type ("decisions" | "pitfalls" | "guidelines" | "models" | "processes"). */
+    knowledge_type: string;
+    /** "team" | "personal". Conflicts are only meaningful within one layer. */
+    layer: string;
+    /** Title + body (or any text used for similarity). */
+    text: string;
+}
+type ConflictVerdict = "conflict" | "similar" | "unknown";
+interface ConflictPair {
+    a: string;
+    b: string;
+    knowledge_type: string;
+    layer: string;
+    /** Symmetric normalized bm25 similarity in [0,1]. */
+    similarity: number;
+    /**
+     * "unknown" until a judge classifies it (cheap pass leaves it unknown =
+     * needs-human-review). "conflict" = the judge ruled a real contradiction
+     * (escalates to error). "similar" = judged not-a-conflict (stays a warn /
+     * possible duplicate).
+     */
+    verdict: ConflictVerdict;
+    rationale?: string;
+}
+type ConflictJudge = (a: ConflictEntry, b: ConflictEntry) => Promise<{
+    isConflict: boolean;
+    rationale: string;
+}>;
+declare const DEFAULT_CONFLICT_SIMILARITY_THRESHOLD = 0.5;
 /**
- * v2.0 KnowledgeIdAllocator
- *
- * Wraps the pure `allocateKnowledgeId` allocator with persistence: it reads
- * `agents.meta.json`, advances the counter for the requested (layer, type)
- * pair, and writes the updated meta atomically (write-to-tmp + rename) so
- * concurrent readers always see a consistent file.
+ * Symmetric, [0,1]-normalized bm25 similarity between two docs sharing a model.
+ * For each direction we measure how much of the target doc's self-relevance the
+ * other doc's terms recover (scoreDoc(target, otherTokens) / scoreDoc(target,
+ * targetTokens)), then take the MIN of both directions — conservative: both
+ * entries must strongly overlap, so a short entry incidentally contained in a
+ * long one does not over-fire.
+ */
+declare function pairSimilarity(model: ReturnType<typeof buildBm25Model>, a: {
+    id: string;
+    tokens: string[];
+}, b: {
+    id: string;
+    tokens: string[];
+}): number;
+/**
+ * Cheap deterministic pass: candidate conflicting/duplicate pairs. Compares
+ * only entries sharing (type, layer), via bm25 similarity ≥ threshold. Returns
+ * pairs sorted by similarity descending (stable_id-tie-broken for determinism).
+ * Every returned pair has verdict "unknown" — the cheap pass cannot tell a
+ * conflict from a benign duplicate; that is the judge's job.
  *
- * Counters are MONOTONIC across the lifetime of the meta file: deleting a
- * knowledge entry does NOT free its counter slot, so previously-allocated
- * stable_ids remain unique even after their files are removed.
+ * O(G · n_g²) where G = groups and n_g = entries per group. Conflicts only make
+ * sense within one (type, layer), so the quadratic stays bounded to small
+ * same-bucket sets, not the whole corpus.
+ */
+declare function findConflictCandidates(entries: ConflictEntry[], opts?: {
+    threshold?: number;
+}): ConflictPair[];
+/**
+ * Full lint. Always runs the cheap pass; when `judge` is supplied (deep mode)
+ * each candidate is classified into conflict/similar. A judge throw leaves the
+ * pair as "unknown" (degrade-safe — a flaky judge never crashes doctor).
  *
- * Key invariants:
- *   - Counters envelope is initialized to zeros if absent (v1.x meta compat).
- *   - Each allocate() call performs read → mutate → atomic-write in sequence.
- *   - The returned id is guaranteed to differ from every previously-returned
- *     id for the same meta path.
+ * Entry lookup for the judge is by stable_id from the same `entries` array.
  */
-declare class KnowledgeIdAllocator {
-    private readonly metaPath;
-    constructor(metaPath: string);
-    /**
-     * Allocate the next stable_id for the given (layer, type) pair and persist
-     * the advanced counter to `agents.meta.json`.
-     */
-    allocate(layer: Layer, type: KnowledgeType): Promise<StableId>;
-    /**
-     * Returns the current counters envelope, defaulting to all-zero slots when
-     * the meta file is absent or pre-v2.0 (counters key missing).
-     */
-    getCounters(): Promise<AgentsMetaCounters>;
-    private readMeta;
-    private normalizeCounters;
-    private writeMetaAtomic;
+declare function lintConflicts(entries: ConflictEntry[], opts?: {
+    threshold?: number;
+    judge?: ConflictJudge;
+}): Promise<ConflictPair[]>;
+
+interface ConflictLintReport {
+    status: "ok";
+    threshold: number;
+    deep: boolean;
+    /** Total candidate pairs (similarity ≥ threshold). */
+    candidate_count: number;
+    /** Subset judged a real contradiction (deep mode only). */
+    conflict_count: number;
+    pairs: ConflictPair[];
 }
+/**
+ * v2.2 W5 R6 (读侧 cutover): load canonical knowledge entries with bodies from
+ * the read-set STORES (cross-store on-the-fly) instead of the retired
+ * co-location agents.meta node index. Skips pending/draft staging entries
+ * (conflict detection targets the curated corpus) and any entry missing a
+ * knowledge_type. collectStoreCanonicalEntries already reads each store entry's
+ * body + parsed frontmatter and degrades to [] when no store is in the read-set.
+ */
+declare function loadConflictEntries(projectRoot: string): Promise<ConflictEntry[]>;
+/**
+ * Run the knowledge-conflict lint. Always runs the cheap bm25 candidate pass;
+ * when `deep` is set AND a judge is supplied, escalates candidates to
+ * conflict/similar verdicts via the injected LLM judge.
+ *
+ * threshold resolution: opts.threshold → fabric-config
+ * conflict_lint_similarity_threshold → DEFAULT_CONFLICT_SIMILARITY_THRESHOLD.
+ */
+declare function runDoctorConflictLint(projectRoot: string, opts?: {
+    threshold?: number;
+    deep?: boolean;
+    judge?: ConflictJudge;
+}): Promise<ConflictLintReport>;
 
 /**
  * Append-evidence-on-collision service for fab_extract_knowledge.
@@ -328,8 +541,66 @@ 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"];
+    since?: number;
+    correlation_id?: string;
+    session_id?: string;
+};
+type LedgerWarning = {
+    kind: "partial_write_at_tail";
+    byte_offset: number;
+    byte_length: number;
+    snippet_first_120: string;
+} | {
+    kind: "schema_version_unsupported";
+    line_index: number;
+    schema_version: unknown;
+    snippet_first_120: string;
+} | {
+    kind: "event_type_unknown";
+    line_index: number;
+    event_type: unknown;
+    snippet_first_120: string;
+};
+type ReadEventLedgerResult = {
+    events: StoredEventLedgerEvent[];
+    warnings: LedgerWarning[];
+};
 declare function appendEventLedgerEvent(projectRoot: string, event: EventLedgerEventInput): Promise<StoredEventLedgerEvent>;
+declare function readEventLedger(projectRoot: string, options?: ReadEventLedgerOptions): Promise<ReadEventLedgerResult>;
 /**
  * Synchronously fsync the event ledger file to ensure OS page-cache buffers are
  * flushed to durable storage. Must be called AFTER in-flight drain but BEFORE
@@ -349,11 +620,28 @@ type PlanContextInput = {
     correlation_id?: string;
     session_id?: string;
     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 = {
@@ -372,11 +660,18 @@ type PlanContextResult = {
     stale: boolean;
     selection_token: string;
     entries: PlanContextEntry[];
+    intent?: string;
     candidates: RuleDescriptionIndexItem[];
+    omitted_candidate_count?: number;
     preflight_diagnostics: PreflightDiagnostic[];
     auto_healed?: boolean;
     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;
@@ -392,102 +687,35 @@ 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[];
+    /**
+     * 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 RecallResult = PlanContextResult & {
-    rules: Array<{
-        stable_id: string;
-        level: "L0" | "L1" | "L2";
-        path: string;
-        body: string;
-    }>;
-    selected_stable_ids: string[];
-    diagnostics: Array<{
-        code: "missing_knowledge_metadata";
-        severity: "warn";
-        stable_id: string;
-        message: string;
-    }>;
-};
-declare function recall(projectRoot: string, input: RecallInput): Promise<RecallResult>;
-
-/**
- * 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.
- *
- * `delta` defaults to 1; callers can pass a positive integer (e.g. fetched
- * N stable_ids in a single sections call) to fold N bumps into one.
- */
-declare function bumpCounter(projectRoot: string, name: string, delta?: number): void;
-/**
- * Snapshot the current counter accumulator and reset it. Returned map is a
- * frozen copy; the live accumulator starts fresh from zero. Exposed so
- * flushMetrics + tests + a future fab_metrics manual-flush CLI hook can all
- * use the same primitive without racing.
- */
-declare function drainCounters(projectRoot: string): Record<string, number>;
-/**
- * Drain the current accumulator and append one JSONL row to
- * `.fabric/metrics.jsonl`. Returns the appended row (or `null` when the
- * accumulator was empty — no spurious zero rows). fs failures degrade
- * silently; the next flush will carry the union of the failed-write
- * interval + the current one.
- */
-declare function flushMetrics(projectRoot: string, options?: {
-    windowMs?: number;
-    now?: Date;
-}): Promise<MetricsRow | null>;
-/**
- * Start the background flush timer for a project root. Idempotent — calling
- * twice on the same root replaces the prior interval. Returns a stop handle
- * the caller can invoke at shutdown to flush + clear the timer.
- *
- * The flush is fire-and-forget (no await on the setInterval callback) so
- * the timer cadence stays accurate even when fs is slow.
- */
-declare function startMetricsFlush(projectRoot: string, options?: {
-    intervalMs?: number;
-}): () => Promise<void>;
-/**
- * Cancel the background flush timer for a project root if one is running.
- * Does NOT drain the accumulator — callers that want a final flush should
- * await flushMetrics(projectRoot) afterward.
- */
-declare function stopMetricsFlush(projectRoot: string): void;
-/**
- * Read accumulated metrics rows from `.fabric/metrics.jsonl`. Missing file
- * returns []. Malformed rows are dropped silently (the sidecar is best-
- * effort observability; a corrupt row never blocks a reader).
- *
- * Exposed for the NEW-34 `fab metrics` CLI dashboard + future doctor lints
- * (e.g. cite-goodhart pattern replay) that need counter trends without
- * walking events.jsonl.
- */
-declare function readMetrics(projectRoot: string): Promise<MetricsRow[]>;
-type MetricsRow = {
-    timestamp: string;
-    window: string;
-    counters: Record<string, number>;
+type RecallPath = {
+    stable_id: string;
+    path: string;
+    store?: {
+        alias: string;
+    };
 };
-/**
- * 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.
- */
-declare const METRIC_COUNTER_NAMES: {
-    readonly knowledge_consumed: "knowledge_consumed";
-    readonly edit_intent_checked: "edit_intent_checked";
-    readonly knowledge_context_planned: "knowledge_context_planned";
-    readonly knowledge_sections_fetched: "knowledge_sections_fetched";
+type RecallResult = Omit<PlanContextResult, "selection_token" | "payload_trimmed" | "payload_over_budget"> & {
+    paths: RecallPath[];
+    directive: string;
+    next_steps?: string[];
 };
-type MetricCounterName = (typeof METRIC_COUNTER_NAMES)[keyof typeof METRIC_COUNTER_NAMES];
+declare function recall(projectRoot: string, input: RecallInput): Promise<RecallResult>;
 
 /**
  * Start the background rotation timer for a project root. Idempotent —
@@ -511,90 +739,87 @@ declare function startRotationTick(projectRoot: string, options?: {
 declare function stopRotationTick(projectRoot: string): void;
 
 /**
- * Shared constants used across the server package.
- */
-/** MCP resource URI for the project's bootstrap README (L0 rules) file. */
-declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
-
-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): when true, `ensureKnowledgeFresh`
-     * synchronously follows a drift detection with a `reconcileKnowledge`
-     * call to materialize the auto-heal (rewrite agents.meta.json + emit a
-     * paired `knowledge_meta_auto_healed` event). Default false preserves
-     * the rc.28 hot-path semantics where drift detection never blocks the
-     * MCP read on a meta rebuild. Opt-in is intended for callers that can
-     * tolerate ~tens-of-ms extra latency in exchange for the invariant
-     * "every knowledge_drift_detected has a paired heal event in the same
-     * tail window." Audit (BUG-G1) found 5/72 drifts healed on this repo
-     * (~7%) because the hot path emitted detect-only events.
-     */
-    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[];
-}
-/**
- * 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).
+ * ContextCache — unified hot-path cache for the Fabric server.
+ *
+ * Three logical slots:
+ *   1. "meta"    — agents.meta.json content (TTL-based, default 5 s)
+ *   2. "context" — GetKnowledgeContext per projectRoot (TTL-based, default 5 s)
+ *   3. "audit"   — sliding-window byte-offset cursor for audit.jsonl reads
+ *
+ * Invalidation reasons:
+ *   - "meta_write"  — eager invalidation when a write service mutates agents.meta.json
+ *   - "file_watch"  — chokidar detected an on-disk change
  */
-declare function ensureKnowledgeFresh(projectRoot: string, opts?: KnowledgeSyncOptions): Promise<KnowledgeSyncReport>;
-interface ReconcileKnowledgeOptions {
+type InvalidationReason = "meta_write" | "file_watch";
+type AuditCursor = {
+    offset: number;
+    remainder: string;
+    windowEntries: Array<{
+        ts: number;
+    }>;
+};
+declare class ContextCache {
+    private readonly defaultTtlMs;
+    private readonly metaSlot;
+    private readonly contextSlot;
+    private readonly auditSlot;
+    constructor(defaultTtlMs?: number);
+    get<T>(slot: "meta" | "context", key: string): T | undefined;
+    set<T>(slot: "meta" | "context", key: string, value: T, ttlMs?: number): void;
+    getAuditCursor(projectRoot: string): AuditCursor | undefined;
+    setAuditCursor(projectRoot: string, cursor: AuditCursor): void;
+    resetAuditCursor(projectRoot: string): void;
     /**
-     * Identifies who triggered the reconcile; controls which summary ledger event is written.
+     * Invalidate cache slots based on what changed.
      *
-     * v2.0.0-rc.23 TASK-005 (a-B): `auto-heal-description` added so plan_context
-     * can drive a full reconcile when it detects nodes with `description === undefined`
-     * (legacy meta drift the revision-hash gate cannot detect).
-     *
-     * v2.0.0-rc.27 TASK-001 (§2.9 root): `post-approve` / `post-modify` added so
-     * `fab_review` approve/modify-layer-flip can drive an immediate meta rebuild
-     * — without this the new entry's `nodes[id]` stays empty until the next
-     * plan_context call's auto-heal, which leaves the entry undiscoverable in
-     * the description_index window between approve and the next hint call.
+     * @param reason  "meta_write"  — only the meta slot for this projectRoot
+     *                "file_watch"  — meta + context slots (AGENTS.md may have changed)
+     * @param projectRoot  Optional; if omitted, clears ALL keys in affected slots.
      */
-    trigger?: "startup" | "doctor" | "manual" | "auto-heal-description" | "auto-heal-after-drift" | "post-approve" | "post-modify";
+    invalidate(reason: InvalidationReason, projectRoot?: string): void;
+    private slotStore;
 }
+declare const contextCache: ContextCache;
+
+type LedgerSourceFilter = "ai" | "human";
+type StoredLedgerEntry = LedgerEntry & {
+    id: string;
+};
+type ReadLedgerOptions = {
+    source?: LedgerSourceFilter;
+    since?: number;
+};
+type ResolvedLedgerPaths = {
+    primaryPath: string;
+    legacyPath: string;
+    readPath: string;
+    usingLegacy: boolean;
+};
+declare function resolveLedgerPaths(projectRoot: string): Promise<ResolvedLedgerPaths>;
+declare function readLedger(projectRoot: string, options?: ReadLedgerOptions): Promise<StoredLedgerEntry[]>;
+
+type RehydrateTarget = {
+    ledgerEntryId: string;
+} | {
+    timestamp: number;
+};
+type RehydratedAgentsMetaSnapshot = {
+    meta: AgentsMeta;
+    metadata: {
+        at_ledger_id: string;
+        at_commit: string | null;
+        replayed_count: number;
+        mode: "git-show" | "ledger-fallback";
+    };
+    entries: StoredLedgerEntry[];
+};
+declare function rehydrateAgentsMetaAt(projectRoot: string, target: RehydrateTarget): Promise<RehydratedAgentsMetaSnapshot>;
+
 /**
- * Full scan + rewrites agents.meta.json with ground-truth disk state + emits
- * ledger events. Used by startup (TASK-022) and doctor repair (TASK-023).
- * Returns reconciled_files listing all paths whose meta was updated.
- *
- * When `opts.trigger` is `'startup'`, a `meta_reconciled_on_startup` summary
- * ledger event is appended after per-file drift events. Other trigger values
- * append a `meta_reconciled` event. Omitting the trigger skips the summary.
+ * Shared constants used across the server package.
  */
-declare function reconcileKnowledge(projectRoot: string, opts?: ReconcileKnowledgeOptions): Promise<KnowledgeSyncReport>;
+/** MCP resource URI for the project's bootstrap README (L0 rules) file. */
+declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
 
 /**
  * Returns an info-level startup message when CLAUDE.md or AGENTS.md exist at
@@ -605,6 +830,7 @@ declare function reconcileKnowledge(projectRoot: string, opts?: ReconcileKnowled
  */
 declare function formatPreexistingRootMessage(projectRoot: string): string | null;
 
+declare const FABRIC_SERVER_INSTRUCTIONS: string;
 declare function createFabricServer(tracker?: InFlightTracker): McpServer;
 declare function startStdioServer(): Promise<void>;
 /**
@@ -631,4 +857,4 @@ interface ShutdownHandlerDeps {
  */
 declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 
-export { AGENTS_MD_RESOURCE_URI, type ArchiveHistoryEntry, type ArchiveHistoryReport, type CiteCoverageReport, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, KnowledgeIdAllocator, type KnowledgeMetaBuildResult, type KnowledgeMetaBuildSource, 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 ReconcileKnowledgeOptions, type RequirementProfile, type SelectionTokenState, type ShutdownHandlerDeps, type StructuredWarning, type WriteKnowledgeMetaOptions, appendEventLedgerEvent, buildKnowledgeMeta, bumpCounter, computeKnowledgeBasedAgentsMeta, computeKnowledgeTestIndex, createFabricServer, createInFlightTracker, createShutdownHandler, deriveKnowledgeMetaLayer, deriveKnowledgeMetaTopologyType, drainCounters, enrichDescriptions, ensureKnowledgeFresh, extractKnowledge, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, isSameKnowledgeTestIndex, loadKbIdTypeMap, planContext, readMetrics, readSelectionToken, recall, reconcileKnowledge, reviewKnowledge, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorFix, runDoctorHistoryAll, runDoctorReport, stableStringify, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick, writeKnowledgeMeta };
+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 };