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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-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';
+import { EventLedgerEventInput, EventLedgerEvent, RuleDescriptionIndexItem, LedgerEntry, AgentsMeta } from '@fenglimg/fabric-shared';
 
 interface InFlightTracker {
     enter(requestId: string): void;
@@ -125,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>;
@@ -146,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;
@@ -297,84 +317,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.
@@ -460,6 +527,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;
@@ -489,6 +558,7 @@ type PlanContextResult = {
     auto_healed?: boolean;
     previous_revision_hash?: string;
     redirects?: Record<string, string>;
+    related_appended?: Record<string, string>;
 };
 type SelectionTokenState = {
     token: string;
@@ -529,10 +599,13 @@ 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;
@@ -612,16 +685,15 @@ interface KnowledgeSyncOptions {
     /** 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.
+     * 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;
 }
@@ -666,32 +738,6 @@ declare function invalidateKnowledgeSyncCooldown(projectRoot: string): void;
  * hot-path consumers (MCP tools).
  */
 declare function ensureKnowledgeFresh(projectRoot: string, opts?: KnowledgeSyncOptions): Promise<KnowledgeSyncReport>;
-interface ReconcileKnowledgeOptions {
-    /**
-     * Identifies who triggered the reconcile; controls which summary ledger event is written.
-     *
-     * 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.
-     */
-    trigger?: "startup" | "doctor" | "manual" | "auto-heal-description" | "auto-heal-after-drift" | "post-approve" | "post-modify";
-}
-/**
- * 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.
- */
-declare function reconcileKnowledge(projectRoot: string, opts?: ReconcileKnowledgeOptions): Promise<KnowledgeSyncReport>;
 
 type LedgerSourceFilter = "ai" | "human";
 type StoredLedgerEntry = LedgerEntry & {
@@ -727,40 +773,6 @@ type RehydratedAgentsMetaSnapshot = {
 };
 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.
  */
@@ -803,4 +815,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, 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, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getKnowledge, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, invalidateKnowledgeSyncCooldown, isSameKnowledgeTestIndex, loadKbIdTypeMap, planContext, readAgentsMeta, readEventLedger, readLedger, readMetrics, readSelectionToken, recall, reconcileKnowledge, rehydrateAgentsMetaAt, resolveLedgerPaths, 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, 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 };