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

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { AgentsMeta, KnowledgeTestIndex, AgentsLayer, AgentsTopologyType, KnowledgeType, Layer, StableId, AgentsMetaCounters, EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, LedgerEntry } from '@fenglimg/fabric-shared';
 import { FabExtractKnowledgeInput, FabExtractKnowledgeOutput, FabReviewInput, FabReviewOutput } from '@fenglimg/fabric-shared/schemas/api-contracts';
 
 interface InFlightTracker {
@@ -22,90 +22,79 @@ 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;
-    };
-    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;
+/**
+ * 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 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";
 };
-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;
@@ -136,6 +125,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>;
@@ -157,6 +165,7 @@ declare function runDoctorCiteCoverage(projectRoot: string, options: {
     client: "cc" | "codex" | "cursor" | "all";
     layer?: "team" | "personal" | "all";
     until?: number;
+    recallWindowMs?: number;
 }): Promise<CiteCoverageReport>;
 type ArchiveHistoryEntry = {
     session_id_short: string;
@@ -192,6 +201,101 @@ 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 DoctorHealth = {
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+    penalties: {
+        manual_errors: number;
+        fixable_errors: number;
+        warnings: number;
+    };
+};
+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[];
+    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,6 +317,130 @@ declare function enrichDescriptions(projectRoot: string, opts?: {
     dryRun?: boolean;
 }): Promise<EnrichDescriptionsReport>;
 
+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;
+}
+/**
+ * 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 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;
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * Entry lookup for the judge is by stable_id from the same `entries` array.
+ */
+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[];
+}
+/**
+ * Load canonical knowledge entries with bodies from the agents.meta node index.
+ * Skips pending/draft staging entries (conflict detection targets the curated
+ * corpus) and any node missing a stable_id or knowledge_type. Bodies are read
+ * best-effort — an unreadable file contributes no entry.
+ */
+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>;
+
 type KnowledgeMetaBuildSource = "doctor_fix" | "sync_meta";
 type KnowledgeMetaBuildResult = {
     meta: AgentsMeta;
@@ -329,7 +557,34 @@ declare function extractKnowledge(projectRoot: string, input: FabExtractKnowledg
 declare function reviewKnowledge(projectRoot: string, input: FabReviewInput): Promise<FabReviewOutput>;
 
 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,6 +604,8 @@ type PlanContextInput = {
     correlation_id?: string;
     session_id?: string;
     target_paths?: string[];
+    layer_filter?: "team" | "personal" | "both";
+    include_related?: boolean;
 };
 type RequirementProfile = {
     target_path: string;
@@ -373,10 +630,12 @@ type PlanContextResult = {
     selection_token: string;
     entries: PlanContextEntry[];
     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>;
 };
 type SelectionTokenState = {
     token: string;
@@ -398,6 +657,18 @@ type RecallInput = PlanContextInput & {
      * provided, filters the fetched body set to this intersection.
      */
     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.
+     */
+    include_related?: boolean;
+};
+type RecallTruncation = {
+    omitted_candidate_count: number;
+    returned_candidate_count: number;
 };
 type RecallResult = PlanContextResult & {
     rules: Array<{
@@ -405,90 +676,23 @@ type RecallResult = PlanContextResult & {
         level: "L0" | "L1" | "L2";
         path: string;
         body: string;
+        store?: {
+            alias: string;
+        };
     }>;
     selected_stable_ids: string[];
     diagnostics: Array<{
-        code: "missing_knowledge_metadata";
+        code: "missing_knowledge_metadata" | "unresolved_selected_id";
         severity: "warn";
         stable_id: string;
         message: string;
     }>;
+    directive: string;
+    next_steps?: string[];
+    truncation?: RecallTruncation;
 };
 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>;
-};
-/**
- * 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 MetricCounterName = (typeof METRIC_COUNTER_NAMES)[keyof typeof METRIC_COUNTER_NAMES];
-
 /**
  * Start the background rotation timer for a project root. Idempotent —
  * calling twice on the same root replaces the prior interval. Returns a
@@ -511,10 +715,47 @@ declare function startRotationTick(projectRoot: string, options?: {
 declare function stopRotationTick(projectRoot: string): void;
 
 /**
- * Shared constants used across the server package.
+ * 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
  */
-/** MCP resource URI for the project's bootstrap README (L0 rules) file. */
-declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
+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;
+    /**
+     * Invalidate cache slots based on what changed.
+     *
+     * @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.
+     */
+    invalidate(reason: InvalidationReason, projectRoot?: string): void;
+    private slotStore;
+}
+declare const contextCache: ContextCache;
 
 interface KnowledgeSyncOptions {
     mode?: "incremental" | "full";
@@ -563,6 +804,12 @@ interface KnowledgeSyncReport {
     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
@@ -596,6 +843,80 @@ interface ReconcileKnowledgeOptions {
  */
 declare function reconcileKnowledge(projectRoot: string, opts?: ReconcileKnowledgeOptions): Promise<KnowledgeSyncReport>;
 
+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>;
+
+declare function readAgentsMeta(projectRoot: string): Promise<AgentsMeta>;
+
+type KnowledgeEntryItem = {
+    path: string;
+    content: string;
+};
+type DescriptionStub = {
+    path: string;
+    description: string;
+};
+type HumanLockedNearby = {
+    file: string;
+    excerpt: string;
+};
+type KnowledgePayload = {
+    L0: string;
+    L1: KnowledgeEntryItem[];
+    L2: KnowledgeEntryItem[];
+    human_locked_nearby: HumanLockedNearby[];
+    description_stubs?: DescriptionStub[];
+};
+type GetKnowledgeInput = {
+    path: string;
+    client_hash?: string;
+    correlation_id?: string;
+    session_id?: string;
+};
+type GetKnowledgeResult = {
+    revision_hash: string;
+    stale: boolean;
+    rules: KnowledgePayload;
+};
+declare function getKnowledge(projectRoot: string, input: GetKnowledgeInput): Promise<GetKnowledgeResult>;
+
+/**
+ * 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";
+
 /**
  * Returns an info-level startup message when CLAUDE.md or AGENTS.md exist at
  * the project root, or null when neither is present.
@@ -605,6 +926,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 +953,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 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, 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, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, deriveKnowledgeMetaLayer, deriveKnowledgeMetaTopologyType, drainCounters, enrichDescriptions, ensureKnowledgeFresh, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getKnowledge, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, invalidateKnowledgeSyncCooldown, isSameKnowledgeTestIndex, lintConflicts, loadConflictEntries, loadKbIdTypeMap, pairSimilarity, planContext, readAgentsMeta, readEventLedger, readLedger, readMetrics, readSelectionToken, recall, reconcileKnowledge, rehydrateAgentsMetaAt, resolveLedgerPaths, reviewKnowledge, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, stableStringify, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick, writeKnowledgeMeta };