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

package/dist/index.d.ts

@@ -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,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;
@@ -460,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;
@@ -489,6 +635,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 +676,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;
@@ -803,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, 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, 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 };