@swarmvaultai/engine 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -51,6 +51,17 @@ declare const agentTypeSchema: z.ZodEnum<{
 type AgentType = z.infer<typeof agentTypeSchema>;
 type PageKind = "index" | "source" | "module" | "concept" | "entity" | "output" | "insight" | "graph_report" | "community_summary";
 type Freshness = "fresh" | "stale";
+/**
+ * Consolidation tier for insight pages (LLM Wiki v2 memory model).
+ *  - `working`: raw recent observations from ad-hoc query/explore output.
+ *  - `episodic`: session-scoped digest rolled up from multiple working pages.
+ *  - `semantic`: cross-session durable facts repeated across episodic pages.
+ *  - `procedural`: how-to workflows inferred from repeated sequences.
+ * Non-insight pages (sources, modules, concepts, entities, outputs) leave
+ * `tier` undefined. Pages without a `tier` field default to `working` when
+ * loaded so 0.9.0 vaults require no migration.
+ */
+type MemoryTier = "working" | "episodic" | "semantic" | "procedural";
 type ClaimStatus = "extracted" | "inferred" | "conflicted" | "stale";
 type EvidenceClass = "extracted" | "inferred" | "ambiguous";
 type Polarity = "positive" | "negative" | "neutral";
@@ -228,11 +239,36 @@ interface VaultConfig {
     };
     graph?: {
         communityResolution?: number;
+        /**
+         * Minimum IDF weight a similarity feature must carry to contribute to an
+         * inferred `semantically_similar_to` edge. Features below the floor are
+         * dropped entirely. Defaults to 0.5.
+         */
+        similarityIdfFloor?: number;
+        /**
+         * Hard cap on the number of inferred similarity edges emitted. Defaults
+         * to `min(5 * nodeCount, 20000)` so very large repos do not produce
+         * O(n²) similarity fan-out.
+         */
+        similarityEdgeCap?: number;
+        /**
+         * Upper bound on god-node entries surfaced in the graph report and
+         * tooling. Defaults to 20 for small repos and 10 for large ones.
+         */
+        godNodeLimit?: number;
+        /**
+         * Report rollup threshold: communities with fewer members than this are
+         * folded into the fragmented-community rollup instead of listed
+         * individually. Defaults to `max(3, ceil(totalCommunities / 50))`.
+         */
+        foldCommunitiesBelow?: number;
     };
     webSearch?: {
         providers: Record<string, WebSearchProviderConfig>;
         tasks: {
             deepLintProvider: string;
+            queryProvider?: string;
+            exploreProvider?: string;
         };
     };
     search?: {
@@ -243,6 +279,81 @@ interface VaultConfig {
     candidate?: {
         autoPromote?: CandidatePromotionConfig;
     };
+    redaction?: RedactionSettings;
+    freshness?: FreshnessConfig;
+    consolidation?: ConsolidationConfig;
+    watch?: WatchConfig;
+}
+/**
+ * Explicit user control over which repository roots `swarmvault watch --repo` tracks.
+ * Absent config preserves the existing auto-discovery behavior over managed sources and manifests.
+ */
+interface WatchConfig {
+    repoRoots?: string[];
+    excludeRepoRoots?: string[];
+}
+/**
+ * Heuristic configuration for the LLM Wiki v2 consolidation tier rollup.
+ *
+ * Defaults are baked in so 0.9.0 configs keep working without migration:
+ *   - enabled: true
+ *   - workingToEpisodic: { minPages: 3, sessionWindowHours: 24, minSharedNodeRatio: 0.3 }
+ *   - episodicToSemantic: { minOccurrences: 3 }
+ *   - semanticToProcedural: { minWorkflowSteps: 3 }
+ */
+interface ConsolidationConfig {
+    enabled?: boolean;
+    workingToEpisodic?: {
+        minPages?: number;
+        sessionWindowHours?: number;
+        minSharedNodeRatio?: number;
+    };
+    episodicToSemantic?: {
+        minOccurrences?: number;
+    };
+    semanticToProcedural?: {
+        minWorkflowSteps?: number;
+    };
+}
+interface ConsolidationPromotion {
+    pageId: string;
+    fromTier: MemoryTier;
+    toTier: MemoryTier;
+}
+interface ConsolidationResult {
+    promoted: ConsolidationPromotion[];
+    newPages: GraphPage[];
+    decisions: string[];
+}
+interface FreshnessConfig {
+    /** Default half-life in days when the page's source class is unknown. Defaults to 365. */
+    defaultHalfLifeDays?: number;
+    /** Below this score a page is considered stale. Defaults to 0.3. */
+    staleThreshold?: number;
+    /** Per-source-class half-life overrides in days. */
+    halfLifeDaysBySourceClass?: Partial<Record<SourceClass, number>>;
+}
+interface RedactionPatternConfig {
+    id: string;
+    pattern: string;
+    flags?: string;
+    placeholder?: string;
+    description?: string;
+}
+interface RedactionSettings {
+    enabled?: boolean;
+    placeholder?: string;
+    useDefaults?: boolean;
+    patterns?: RedactionPatternConfig[];
+}
+interface RedactionMatchSummary {
+    patternId: string;
+    count: number;
+}
+interface RedactionSummary {
+    sourceId: string;
+    title: string;
+    matches: RedactionMatchSummary[];
 }
 interface CandidatePromotionConfig {
     enabled: boolean;
@@ -362,6 +473,13 @@ interface IngestOptions {
     gitignore?: boolean;
     extractClasses?: SourceClass[];
     resume?: string;
+    /**
+     * Override the config-level redaction flag for this run. Defaults to the
+     * effective value in `VaultConfig.redaction.enabled` (which itself defaults
+     * to `true` when the config block is absent). Pass `false` to skip
+     * redaction entirely for this run.
+     */
+    redact?: boolean;
 }
 interface DirectoryIngestSkip {
     path: string;
@@ -382,6 +500,11 @@ interface DirectoryIngestResult {
     failed?: DirectoryIngestFailure[];
     runId?: string;
     statePath?: string;
+    /**
+     * Per-source redaction counts surfaced to CLI/MCP callers. Empty when
+     * redaction was disabled or no matches were found on the ingested inputs.
+     */
+    redactions?: RedactionSummary[];
 }
 interface InputIngestResult {
     input: string;
@@ -391,6 +514,11 @@ interface InputIngestResult {
     unchanged: SourceManifest[];
     removed: SourceManifest[];
     skipped: DirectoryIngestSkip[];
+    /**
+     * Per-source redaction counts surfaced to CLI/MCP callers. Empty when
+     * redaction was disabled or no matches were found on the ingested inputs.
+     */
+    redactions?: RedactionSummary[];
 }
 interface SourceManifest {
     sourceId: string;
@@ -506,7 +634,14 @@ interface SourceRationale {
     id: string;
     text: string;
     citation: string;
-    kind: "docstring" | "comment" | "marker";
+    /**
+     * Structural kind for code rationales (`docstring`, `comment`, `marker`) or
+     * the lowercased fixed-prefix marker for non-code rationales (`note`,
+     * `why`, `hack`, `important`, `rationale`, `todo`, `fixme`, `warning`,
+     * `warn`). Non-code kinds are parser-selected from markdown blockquotes /
+     * list items and plain-text paragraphs, never swept from whole files.
+     */
+    kind: "docstring" | "comment" | "marker" | "note" | "why" | "hack" | "important" | "rationale" | "todo" | "fixme" | "warning" | "warn";
     symbolName?: string;
 }
 interface CodeIndexEntry {
@@ -560,8 +695,24 @@ interface GraphNode {
     degree?: number;
     bridgeScore?: number;
     isGodNode?: boolean;
+    /**
+     * Human-readable explanation of why this node was flagged as a god-node
+     * (high-degree hub). Populated for god nodes only. Deterministic.
+     */
+    surpriseReason?: string;
     tags?: string[];
 }
+/**
+ * Graph edges use an open-string `relation` so new semantics can land
+ * without churning every consumer. Commonly produced relations include:
+ *   - `mentions`, `contains_code`, `defines`, `exports`, `imports`,
+ *     `contradicts`, `supports`, `builds_on`.
+ *   - `superseded_by`: the source node/page has been replaced by the
+ *     target. The older page is expected to carry `freshness: "stale"`
+ *     and `supersededBy` pointing at the target page id. Compile,
+ *     ingest, and human review can all produce this relation; lint
+ *     surfaces broken supersession links.
+ */
 interface GraphEdge {
     id: string;
     source: string;
@@ -595,6 +746,26 @@ interface GraphPage {
     projectIds: string[];
     nodeIds: string[];
     freshness: Freshness;
+    /**
+     * Numeric freshness score in [0, 1] that decays over time based on the
+     * source-class half-life. `1` means fully fresh (just confirmed), `0`
+     * means fully decayed. Pages that predate decay tracking are treated as
+     * `1` so old vaults are not penalized. See `freshness.ts` for the decay
+     * function and thresholds.
+     */
+    decayScore?: number;
+    /**
+     * ISO timestamp of the last time compile or ingest confirmed this page
+     * against a live source/claim. Missing on pages that existed before
+     * decay tracking landed.
+     */
+    lastConfirmedAt?: string;
+    /**
+     * If set, this page has been superseded by another page. The value is
+     * the replacement page id. A matching `superseded_by` relation edge
+     * connects the old page's node to the replacement in the graph.
+     */
+    supersededBy?: string;
     status: PageStatus;
     confidence: number;
     backlinks: string[];
@@ -612,6 +783,24 @@ interface GraphPage {
     question?: string;
     outputFormat?: OutputFormat;
     outputAssets?: OutputAsset[];
+    /**
+     * Memory-tier assignment for insight pages. Undefined on non-insight
+     * pages. When an insight page on disk is missing this field, callers
+     * default it to `"working"` in memory; no on-disk migration happens.
+     */
+    tier?: MemoryTier;
+    /**
+     * Lower-tier page ids that were rolled up into this page during a
+     * consolidation pass. Populated only on pages produced by
+     * `runConsolidation` (episodic/semantic/procedural). Empty/undefined on
+     * working-tier or non-insight pages.
+     */
+    consolidatedFromPageIds?: string[];
+    /**
+     * Heuristic confidence (0..1) that the consolidation rollup is
+     * meaningful. Missing when the page was not produced by consolidation.
+     */
+    consolidationConfidence?: number;
 }
 interface GraphArtifact {
     generatedAt: string;
@@ -860,6 +1049,7 @@ interface QueryOptions {
     save?: boolean;
     format?: OutputFormat;
     review?: boolean;
+    gapFill?: boolean;
 }
 interface QueryResult {
     answer: string;
@@ -903,6 +1093,7 @@ interface WatchOptions {
     debounceMs?: number;
     repo?: boolean;
     codeOnly?: boolean;
+    overrideRoots?: string[];
 }
 interface PendingSemanticRefreshEntry {
     id: string;
@@ -1074,12 +1265,24 @@ interface LintOptions {
     deep?: boolean;
     web?: boolean;
     conflicts?: boolean;
+    /**
+     * When true, only decay-related lint rules run
+     * (`decayed-pages`, `broken_supersession`, `inconsistent_decay`).
+     */
+    decay?: boolean;
+    /**
+     * When true, only consolidation-tier lint rules run
+     * (`stale_working_tier`, `broken_consolidation_basis`,
+     * `semantic_without_episodic_basis`).
+     */
+    tiers?: boolean;
 }
 interface ExploreOptions {
     question: string;
     steps?: number;
     format?: OutputFormat;
     review?: boolean;
+    gapFill?: boolean;
 }
 interface ExploreStepResult {
     step: number;
@@ -1224,6 +1427,27 @@ interface BenchmarkSummary {
     avgReduction: number;
     reductionRatio: number;
 }
+/**
+ * Per-source-class slice of a benchmark run. The graph-guided tokens are
+ * computed against the same traversal seeds that produced the corpus-wide
+ * numbers, then narrowed to nodes/edges/pages whose `sourceClass` matches
+ * this class. The naive tokens come from manifests whose
+ * {@link SourceManifest.sourceClass} matches this class. Empty classes are
+ * represented as zeroed entries rather than being omitted so downstream
+ * consumers never have to branch on `undefined`.
+ */
+interface BenchmarkByClassEntry {
+    sourceClass: SourceClass;
+    sourceCount: number;
+    pageCount: number;
+    nodeCount: number;
+    godNodeCount: number;
+    corpusWords: number;
+    corpusTokens: number;
+    finalContextTokens: number;
+    reductionRatio: number;
+    perQuestion: BenchmarkQuestionResult[];
+}
 interface BenchmarkArtifact {
     generatedAt: string;
     graphHash: string;
@@ -1236,6 +1460,7 @@ interface BenchmarkArtifact {
     sampleQuestions: string[];
     perQuestion: BenchmarkQuestionResult[];
     summary: BenchmarkSummary;
+    byClass: Record<SourceClass, BenchmarkByClassEntry>;
 }
 interface EmbeddingCacheEntry {
     itemId: string;
@@ -1281,6 +1506,21 @@ interface GraphReportArtifact {
         stale: boolean;
         summary: BenchmarkSummary;
         questionCount: number;
+        /**
+         * Compact per-source-class mirror of the benchmark summary. Populated
+         * from {@link BenchmarkArtifact.byClass} whenever the benchmark artifact
+         * is available at report build time. Kept optional so older benchmark
+         * files without a `byClass` field still produce a valid report.
+         */
+        byClass?: Record<SourceClass, {
+            sourceCount: number;
+            pageCount: number;
+            nodeCount: number;
+            godNodeCount: number;
+            finalContextTokens: number;
+            naiveCorpusTokens: number;
+            reductionRatio: number;
+        }>;
     };
     godNodes: Array<{
         nodeId: string;
@@ -1288,6 +1528,12 @@ interface GraphReportArtifact {
         pageId?: string;
         degree?: number;
         bridgeScore?: number;
+        /**
+         * Deterministic one-line explanation of why the node is surfaced as a
+         * god-node — e.g. "degree 42 across 7 communities" or
+         * "degree 38 (2.1σ above mean)". Omitted when no degree signal exists.
+         */
+        surpriseReason?: string;
     }>;
     bridgeNodes: Array<{
         nodeId: string;
@@ -1386,7 +1632,11 @@ interface ScheduledExploreTask {
     steps?: number;
     format?: OutputFormat;
 }
-type ScheduledTaskConfig = ScheduledCompileTask | ScheduledLintTask | ScheduledQueryTask | ScheduledExploreTask;
+interface ScheduledConsolidateTask {
+    type: "consolidate";
+    dryRun?: boolean;
+}
+type ScheduledTaskConfig = ScheduledCompileTask | ScheduledLintTask | ScheduledQueryTask | ScheduledExploreTask | ScheduledConsolidateTask;
 interface ScheduleTriggerConfig {
     cron?: string;
     every?: string;
@@ -1484,6 +1734,202 @@ declare function initWorkspace(rootDir: string, options?: {
     paths: ResolvedPaths;
 }>;
 
+/**
+ * LLM Wiki v2 consolidation tiers. This pass is a lightweight deterministic
+ * rollup that groups working-tier insight pages into episodic digests and
+ * episodic pages into semantic/procedural pages. The LLM provider (if any)
+ * is only consulted for nicer titles and summaries — promotion decisions
+ * themselves are heuristic so the pass works without any provider access.
+ *
+ * The function never deletes pages. Lower-tier pages that are rolled up get
+ * a `supersededBy` pointer to the new higher-tier page. Consumers use
+ * `tier` and `consolidatedFromPageIds` on the generated page to trace the
+ * basis of every rollup.
+ */
+declare const DEFAULT_CONSOLIDATION_CONFIG: Required<{
+    enabled: boolean;
+    workingToEpisodic: Required<NonNullable<ConsolidationConfig["workingToEpisodic"]>>;
+    episodicToSemantic: Required<NonNullable<ConsolidationConfig["episodicToSemantic"]>>;
+    semanticToProcedural: Required<NonNullable<ConsolidationConfig["semanticToProcedural"]>>;
+}>;
+interface RunConsolidationOptions {
+    /** When true, compute decisions and return them without writing any files. */
+    dryRun?: boolean;
+    /** Fixed clock for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Resolve the default-backed consolidation config. Missing/partial config
+ * objects are treated as "use all defaults".
+ */
+declare function resolveConsolidationConfig(config?: ConsolidationConfig): {
+    enabled: boolean;
+    workingToEpisodic: Required<NonNullable<ConsolidationConfig["workingToEpisodic"]>>;
+    episodicToSemantic: Required<NonNullable<ConsolidationConfig["episodicToSemantic"]>>;
+    semanticToProcedural: Required<NonNullable<ConsolidationConfig["semanticToProcedural"]>>;
+};
+declare function runConsolidation(rootDir: string, config?: ConsolidationConfig, provider?: ProviderAdapter, options?: RunConsolidationOptions): Promise<ConsolidationResult>;
+
+/**
+ * Decay and supersession helpers for the LLM Wiki v2 lifecycle layer.
+ *
+ * Pages accumulate a numeric `decayScore` (0..1) that ticks down over time
+ * based on the elapsed days since `lastConfirmedAt`, controlled by a
+ * source-class half-life. Decay never deletes or hides pages — it informs
+ * ranking, lint, and UI prioritization. Callers are expected to:
+ *
+ *   1. Call `resetDecay` whenever compile or ingest confirms a page still
+ *      matches a live source/claim (e.g. same semantic hash reappears).
+ *   2. Call `applyDecayToPages` at the end of a compile pass to recompute
+ *      `decayScore` and downgrade `freshness` below the threshold.
+ *   3. Call `markSuperseded` when a newer page replaces an older one,
+ *      emitting a `superseded_by` edge alongside.
+ *
+ * Defaults (matching the A.3 feature spec):
+ *   - defaultHalfLifeDays = 365
+ *   - staleThreshold      = 0.3
+ *   - halfLifeDaysBySourceClass = {
+ *       first_party: 365   (slow decay)
+ *       third_party: 90    (fast — deps churn)
+ *       resource:    730   (slowest — assets)
+ *       generated:   30    (fastest — build output)
+ *     }
+ */
+declare const DEFAULT_HALF_LIFE_DAYS = 365;
+declare const DEFAULT_STALE_THRESHOLD = 0.3;
+declare const DEFAULT_HALF_LIFE_DAYS_BY_SOURCE_CLASS: Record<SourceClass, number>;
+interface DecayConfig {
+    halfLifeDaysBySourceClass?: Partial<Record<SourceClass, number>>;
+    defaultHalfLifeDays?: number;
+    staleThreshold?: number;
+}
+interface ApplyDecayResult {
+    updated: GraphPage[];
+    markedStale: string[];
+}
+/**
+ * Compute a numeric decay score using a straight exponential half-life model.
+ *
+ * score = 0.5 ^ (ageDays / halfLifeDays)
+ *
+ * `lastConfirmedAt` missing returns 1 so pages from pre-decay vaults are
+ * not penalized until they are next reconfirmed. Future timestamps (clock
+ * skew) also return 1.
+ */
+declare function computeDecayScore(lastConfirmedAt: string | undefined, sourceClass: SourceClass | undefined, config: DecayConfig, now?: Date): number;
+/**
+ * Recompute `decayScore` and `freshness` for the supplied pages. Pure
+ * function: returns a new array and does not mutate the inputs. Pages
+ * with `supersededBy` set stay `"stale"` regardless of score. Pages
+ * above the threshold are upgraded back to `"fresh"` so re-confirmation
+ * outside of compile (e.g. human review) can take effect.
+ */
+declare function applyDecayToPages(pages: GraphPage[], config: DecayConfig, now?: Date): ApplyDecayResult;
+/**
+ * Reset decay for a single page. Typically invoked when compile or
+ * ingest observes the same source/claim signature as before, confirming
+ * the page is still anchored in live evidence. Does not touch
+ * `supersededBy`: if the page has been superseded it remains stale.
+ */
+declare function resetDecay(page: GraphPage, now?: Date): GraphPage;
+/**
+ * Mark an older page as superseded by a replacement. The caller is
+ * responsible for emitting the `superseded_by` graph edge separately.
+ */
+declare function markSuperseded(oldPage: GraphPage, newPageId: string, now?: Date): GraphPage;
+/**
+ * Build a DecayConfig from the user-facing FreshnessConfig. Missing
+ * fields fall back to defaults.
+ */
+declare function resolveDecayConfig(config?: FreshnessConfig): DecayConfig;
+/**
+ * Write decay/supersession frontmatter into every page's markdown file
+ * on disk. Pages that do not live under `wikiDir` (e.g. ephemeral or
+ * missing files) are skipped silently.
+ */
+declare function persistDecayFrontmatter(wikiDir: string, pages: GraphPage[]): Promise<string[]>;
+/**
+ * Full compile-time decay pass. For each live page:
+ *   - If the page was just produced by compile, reset decay to 1 and
+ *     stamp `lastConfirmedAt = now` (it has been re-confirmed by a
+ *     live analysis).
+ *   - Otherwise, recompute decay from the existing `lastConfirmedAt`.
+ *   - Downgrade freshness to "stale" when the score falls below the
+ *     configured threshold, upgrade it back to "fresh" when the score
+ *     recovers and the page is not superseded.
+ *
+ * Returns the updated pages so callers can update `graph.json`, plus
+ * the paths of any page files whose frontmatter was rewritten on disk.
+ */
+declare function runDecayPass(input: {
+    wikiDir: string;
+    graphPath: string;
+    pages: GraphPage[];
+    /** Pages (by id) that compile confirmed in this run. Their decay resets to 1. */
+    confirmedPageIds: Iterable<string>;
+    config?: FreshnessConfig;
+    now?: Date;
+}): Promise<{
+    pages: GraphPage[];
+    updatedPaths: string[];
+    markedStale: string[];
+}>;
+
+/**
+ * Viewer-only hub node synthesized from a group-pattern hyperedge. Hubs are
+ * never written back to `state/graph.json` — callers can treat them as
+ * transient UI scaffolding that turns a single `GraphHyperedge` into a tiny
+ * star of pairwise edges that Cytoscape (or vis.js) can render natively.
+ */
+type SynthesizedHubNode = {
+    id: string;
+    hyperedgeId: string;
+    label: string;
+    relation: string;
+    participantIds: string[];
+    confidence: number;
+    evidenceClass: string;
+    why: string;
+};
+/**
+ * Viewer-only edge that connects a synthesized hub to one of the hyperedge
+ * participants. IDs are stable across renders so Cytoscape can reuse them and
+ * tests can assert their presence.
+ */
+type SynthesizedHubEdge = {
+    id: string;
+    hyperedgeId: string;
+    source: string;
+    target: string;
+    relation: string;
+    confidence: number;
+    evidenceClass: string;
+};
+type SynthesizedHyperedgeHubs = {
+    hubNodes: SynthesizedHubNode[];
+    hubEdges: SynthesizedHubEdge[];
+};
+type MinimalHyperedge = {
+    id: string;
+    label: string;
+    relation: string;
+    nodeIds: string[];
+    confidence?: number;
+    evidenceClass?: string;
+    why?: string;
+};
+type MinimalNode = {
+    id: string;
+};
+/**
+ * Turn every group-pattern hyperedge with `>= 2` participants into a star:
+ * one synthetic hub node plus a pairwise edge to each participant. Degenerate
+ * hyperedges (zero or one participant) are skipped because a hub with no
+ * "group" to anchor is noisy and contributes nothing to the layout. Nothing
+ * here mutates `state/graph.json`; the caller layers hubs on top of the real
+ * graph for rendering only.
+ */
+declare function synthesizeHyperedgeHubs(hyperedges: ReadonlyArray<MinimalHyperedge>, nodes: ReadonlyArray<MinimalNode>): SynthesizedHyperedgeHubs;
 declare function exportGraphFormat(rootDir: string, format: Exclude<GraphExportFormat, "html" | "report" | "obsidian" | "canvas">, outputPath: string): Promise<GraphExportResult>;
 declare function exportGraphReportHtml(rootDir: string, outputPath: string): Promise<GraphExportResult>;
 declare function exportObsidianVault(rootDir: string, outputDir: string): Promise<GraphExportResult>;
@@ -1530,6 +1976,49 @@ declare function importInbox(rootDir: string, inputDir?: string): Promise<InboxI
 declare function listManifests(rootDir: string): Promise<SourceManifest[]>;
 declare function readExtractedText(rootDir: string, manifest: SourceManifest): Promise<string | undefined>;
 
+/**
+ * Effective tuning thresholds for graph output. These knobs keep report and
+ * similarity surfaces readable on large repositories while preserving
+ * friendly defaults on small ones. Every caller that picks a graph limit
+ * should route through {@link resolveLargeRepoDefaults} so user-provided
+ * overrides stay authoritative and defaults adjust automatically based on
+ * node count.
+ */
+interface ResolvedLargeRepoDefaults {
+    /** Upper bound on god-node entries surfaced in the report/tooling. */
+    godNodeLimit: number;
+    /**
+     * Community rollup threshold: any community with fewer than this many
+     * members is folded into the rollup summary in the report. Defaults to
+     * `max(3, ceil(totalCommunities / 50))` when `totalCommunities` is
+     * provided, otherwise to 3.
+     */
+    foldCommunitiesBelow: number;
+    /**
+     * Hard cap on the number of inferred similarity edges emitted per graph.
+     * Prevents degenerate O(n²) fan-out on very large repos.
+     */
+    similarityEdgeCap: number;
+    /**
+     * Minimum IDF weight a similarity feature must carry to contribute to an
+     * edge score. Features below the floor are dropped entirely.
+     */
+    similarityIdfFloor: number;
+}
+/** Node count at which tighter defaults begin firing. */
+declare const LARGE_REPO_NODE_THRESHOLD = 1000;
+/**
+ * Resolve effective numeric thresholds for a graph of `nodeCount` nodes.
+ * User-configured values on `config.graph` always win — defaults only fire
+ * when the caller has left the knob unset. Pass `totalCommunities` when the
+ * community rollup threshold needs to scale with the community count.
+ */
+declare function resolveLargeRepoDefaults(input: {
+    nodeCount: number;
+    totalCommunities?: number;
+    config?: VaultConfig | null;
+}): ResolvedLargeRepoDefaults;
+
 declare function createMcpServer(rootDir: string): Promise<McpServer>;
 declare function startMcpServer(rootDir: string, stdin?: Readable, stdout?: Writable): Promise<{
     close: () => Promise<void>;
@@ -1539,6 +2028,70 @@ declare function createProvider(id: string, config: ProviderConfig, rootDir: str
 declare function getProviderForTask(rootDir: string, task: keyof Awaited<ReturnType<typeof loadVaultConfig>>["config"]["tasks"]): Promise<ProviderAdapter>;
 declare function assertProviderCapability(provider: ProviderAdapter, capability: ProviderCapability): void;
 
+interface RedactionPattern {
+    id: string;
+    pattern: RegExp | string;
+    placeholder?: string;
+    description?: string;
+}
+interface RedactionMatch {
+    patternId: string;
+    count: number;
+}
+interface Redactor {
+    redact(text: string): {
+        text: string;
+        matches: RedactionMatch[];
+    };
+}
+/**
+ * Built-in safety-by-default patterns. These cover common cloud, SaaS, and
+ * cryptographic credentials that should never be captured verbatim into the
+ * immutable `raw/` store or compiled wiki pages. Each pattern is expressed as
+ * a named regex literal so readability is preserved when auditing what gets
+ * scrubbed.
+ */
+declare const DEFAULT_REDACTION_PATTERNS: RedactionPattern[];
+/**
+ * Build a redactor from a list of patterns. Callers should construct this
+ * once per ingest run and reuse it across prepared inputs so regex compilation
+ * and global-flag normalization happen only once.
+ */
+declare function buildRedactor(patterns: RedactionPattern[], defaultPlaceholder?: string): Redactor;
+interface ConfiguredRedactionPattern {
+    id: string;
+    pattern: string;
+    flags?: string;
+    placeholder?: string;
+    description?: string;
+}
+interface RedactionConfig {
+    enabled?: boolean;
+    placeholder?: string;
+    useDefaults?: boolean;
+    patterns?: ConfiguredRedactionPattern[];
+}
+/**
+ * Compile a possibly-absent `redaction` config block into a concrete
+ * pattern list. Missing config means "enabled with defaults" — this is
+ * safety-by-default so a fresh 0.9.0 vault upgrades without silently losing
+ * redaction coverage.
+ *
+ * Invalid user-supplied regex sources throw eagerly with a helpful message
+ * so the failure is surfaced at ingest start instead of silently skipped.
+ */
+declare function resolveRedactionPatterns(config?: RedactionConfig | null): {
+    enabled: boolean;
+    placeholder: string;
+    patterns: RedactionPattern[];
+};
+/**
+ * Convenience helper used by the ingest pipeline: build the redactor once
+ * from config, or return `null` if redaction is disabled. Returning `null`
+ * makes the caller's fast-path trivial (skip bytes/string work entirely).
+ */
+declare function buildConfiguredRedactor(config?: RedactionConfig | null): Redactor | null;
+
 declare function listSchedules(rootDir: string): Promise<ScheduleStateRecord[]>;
 declare function runSchedule(rootDir: string, jobId: string): Promise<ScheduledRunResult>;
 declare function serveSchedules(rootDir: string, pollMs?: number): Promise<ScheduleController>;
@@ -1653,6 +2206,20 @@ declare function runAutoPromotion(rootDir: string, options?: {
     dryRun?: boolean;
 }): Promise<PromotionSession>;
 declare function previewCandidatePromotions(rootDir: string): Promise<PromotionDecision[]>;
+/**
+ * Human-in-the-loop supersession: wire up a `superseded_by` edge between
+ * two existing pages and flip the older page's frontmatter to stale. The
+ * edge is written into `state/graph.json` and the older page's markdown
+ * file is updated via `markSuperseded`. Caller supplies either page ids
+ * or page paths for resolution convenience.
+ */
+declare function createSupersessionEdge(rootDir: string, oldPageIdOrPath: string, newPageIdOrPath: string): Promise<{
+    oldPageId: string;
+    newPageId: string;
+    edgeId: string;
+    graphPath: string;
+    updatedPagePath: string;
+}>;
 declare function archiveCandidate(rootDir: string, target: string): Promise<CandidateRecord>;
 declare function initVault(rootDir: string, options?: InitOptions): Promise<void>;
 declare function compileVault(rootDir: string, options?: CompileOptions): Promise<CompileResult>;
@@ -1696,6 +2263,14 @@ declare function bootstrapDemo(rootDir: string, input?: string): Promise<{
     manifestId?: string;
     compile?: CompileResult;
 }>;
+/**
+ * Vault-level wrapper around the consolidation engine so the CLI, MCP,
+ * and schedule callers all go through a single entry point. The provider
+ * is optional; the rollup is purely heuristic otherwise.
+ */
+declare function consolidateVault(rootDir: string, options?: {
+    dryRun?: boolean;
+}): Promise<ConsolidationResult>;
 
 declare function startGraphServer(rootDir: string, port?: number, options?: {
     full?: boolean;
@@ -1721,11 +2296,41 @@ type WatchCycleResult = {
     changedPages: string[];
     lintFindingCount?: number;
 };
+/**
+ * Compute the effective list of repository roots that `swarmvault watch --repo` should track.
+ * Resolution order (highest wins):
+ *   1. `options.overrideRoots` (CLI `--root <path>`) — used verbatim, config and discovery skipped.
+ *   2. Explicit `config.watch.repoRoots` — skips auto-discovery but still honors `excludeRepoRoots`.
+ *   3. Auto-discovery via `listTrackedRepoRoots` — preserves pre-0.11 behavior.
+ * `config.watch.excludeRepoRoots` always applies as a deny list (unless `overrideRoots` is set).
+ */
+declare function resolveWatchedRepoRoots(rootDir: string, options?: {
+    overrideRoots?: string[];
+    config?: VaultConfig;
+}): Promise<string[]>;
+/**
+ * Public helper mirroring `resolveWatchedRepoRoots` for CLI and MCP callers that only need the
+ * final list without the full watch cycle machinery.
+ */
+declare function listWatchedRoots(rootDir: string, options?: {
+    overrideRoots?: string[];
+}): Promise<string[]>;
+/**
+ * Add a repo root to the persisted `watch.repoRoots` list in `swarmvault.config.json`.
+ * Returns the resolved absolute path that was added (or already present). Dedupes on resolved path.
+ */
+declare function addWatchedRoot(rootDir: string, candidate: string): Promise<string>;
+/**
+ * Remove a repo root from the persisted `watch.repoRoots` list. Missing path is a no-op.
+ * Returns `true` when the path was removed, `false` when it was absent.
+ */
+declare function removeWatchedRoot(rootDir: string, candidate: string): Promise<boolean>;
 declare function runWatchCycle(rootDir: string, options?: WatchOptions): Promise<WatchCycleResult>;
 declare function watchVault(rootDir: string, options?: WatchOptions): Promise<WatchController>;
 declare function getWatchStatus(rootDir: string): Promise<WatchStatusResult>;
 
 declare function createWebSearchAdapter(id: string, config: WebSearchProviderConfig, rootDir: string): Promise<WebSearchAdapter>;
-declare function getWebSearchAdapterForTask(rootDir: string, task: "deepLintProvider"): Promise<WebSearchAdapter>;
+type WebSearchTaskId = "deepLintProvider" | "queryProvider" | "exploreProvider";
+declare function getWebSearchAdapterForTask(rootDir: string, task: WebSearchTaskId): Promise<WebSearchAdapter>;
 
-export { type AddOptions, type AddResult, type AgentType, type AnalyzedTerm, type ApprovalBundleType, type ApprovalChangeType, type ApprovalDetail, type ApprovalDiffHunk, type ApprovalDiffLine, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryLabel, type ApprovalEntryStatus, type ApprovalFrontmatterChange, type ApprovalManifest, type ApprovalStructuredDiff, type ApprovalSummary, type AudioTranscriptionRequest, type AudioTranscriptionResponse, type BenchmarkArtifact, type BenchmarkOptions, type BenchmarkQuestionResult, type BenchmarkSummary, type BlastRadiusResult, type CandidatePromotionConfig, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, DEFAULT_PROMOTION_CONFIG, type DirectoryIngestFailure, type DirectoryIngestResult, type DirectoryIngestSkip, type EmbeddingCacheArtifact, type EmbeddingCacheEntry, type EvidenceClass, type ExploreOptions, type ExploreResult, type ExploreStepResult, type ExtractionClaim, type ExtractionKind, type ExtractionTerm, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GitHookStatus, type GraphArtifact, type GraphDiffResult, type GraphEdge, type GraphExplainNeighbor, type GraphExplainResult, type GraphExportFormat, type GraphExportResult, type GraphHyperedge, type GraphNode, type GraphPage, type GraphPathResult, type GraphPushCounts, type GraphPushNeo4jOptions, type GraphPushResult, type GraphQueryMatch, type GraphQueryResult, type GraphReportArtifact, type GuidedSessionMode, type GuidedSourceSessionAnswers, type GuidedSourceSessionQuestion, type GuidedSourceSessionRecord, type GuidedSourceSessionStatus, type ImageGenerationRequest, type ImageGenerationResponse, type ImageVisionExtraction, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type InputIngestResult, type InstallAgentOptions, type InstallAgentResult, type LintFinding, type LintOptions, type ManagedSourceAddOptions, type ManagedSourceAddResult, type ManagedSourceDeleteResult, type ManagedSourceKind, type ManagedSourceRecord, type ManagedSourceReloadOptions, type ManagedSourceReloadResult, type ManagedSourceStatus, type ManagedSourceSyncCounts, type ManagedSourcesArtifact, type Neo4jGraphSinkConfig, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type PendingSemanticRefreshEntry, type Polarity, type PromotionDecision, type PromotionGateKind, type PromotionGateResult, type PromotionSession, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type RepoSyncResult, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceCaptureType, type SourceClaim, type SourceClass, type SourceExtractionArtifact, type SourceGuideResult, type SourceKind, type SourceManifest, type SourceRationale, type SourceReviewResult, type VaultConfig, type VaultDashboardPack, type VaultProfileConfig, type VaultProfilePreset, type WatchController, type WatchOptions, type WatchRepoSyncResult, type WatchRunRecord, type WatchStatusResult, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, addInput, addManagedSource, agentTypeSchema, archiveCandidate, assertProviderCapability, autoCommitWikiChanges, benchmarkVault, blastRadius, blastRadiusVault, bootstrapDemo, compileVault, createMcpServer, createProvider, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, deleteManagedSource, estimatePageTokens, estimateTokens, evaluateCandidateForPromotion, explainGraphVault, exploreVault, exportGraphFormat, exportGraphHtml, exportGraphReportHtml, exportObsidianCanvas, exportObsidianVault, getGitHookStatus, getProviderForTask, getWatchStatus, getWebSearchAdapterForTask, getWorkspaceInfo, graphDiff, guideManagedSource, guideSourceScope, importInbox, ingestDirectory, ingestInput, ingestInputDetailed, initVault, initWorkspace, installAgent, installConfiguredAgents, installGitHooks, lintVault, listApprovals, listCandidates, listGodNodes, listGraphHyperedges, listManagedSourceRecords, listManifests, listPages, listSchedules, listTrackedRepoRoots, loadVaultConfig, loadVaultSchema, loadVaultSchemas, pathGraphVault, previewCandidatePromotions, promoteCandidate, providerCapabilitySchema, providerTypeSchema, pushGraphNeo4j, queryGraphVault, queryVault, readApproval, readExtractedText, readGraphReport, readPage, rejectApproval, reloadManagedSources, resolvePaths, resumeSourceSession, reviewManagedSource, reviewSourceScope, runAutoPromotion, runSchedule, runWatchCycle, searchVault, serveSchedules, stageGeneratedOutputPages, startGraphServer, startMcpServer, syncTrackedRepos, syncTrackedReposForWatch, trimToTokenBudget, uninstallGitHooks, watchVault, webSearchProviderTypeSchema };
+export { type AddOptions, type AddResult, type AgentType, type AnalyzedTerm, type ApprovalBundleType, type ApprovalChangeType, type ApprovalDetail, type ApprovalDiffHunk, type ApprovalDiffLine, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryLabel, type ApprovalEntryStatus, type ApprovalFrontmatterChange, type ApprovalManifest, type ApprovalStructuredDiff, type ApprovalSummary, type AudioTranscriptionRequest, type AudioTranscriptionResponse, type BenchmarkArtifact, type BenchmarkByClassEntry, type BenchmarkOptions, type BenchmarkQuestionResult, type BenchmarkSummary, type BlastRadiusResult, type CandidatePromotionConfig, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, type ConsolidationConfig, type ConsolidationPromotion, type ConsolidationResult, DEFAULT_CONSOLIDATION_CONFIG, DEFAULT_HALF_LIFE_DAYS, DEFAULT_HALF_LIFE_DAYS_BY_SOURCE_CLASS, DEFAULT_PROMOTION_CONFIG, DEFAULT_REDACTION_PATTERNS, DEFAULT_STALE_THRESHOLD, type DirectoryIngestFailure, type DirectoryIngestResult, type DirectoryIngestSkip, type EmbeddingCacheArtifact, type EmbeddingCacheEntry, type EvidenceClass, type ExploreOptions, type ExploreResult, type ExploreStepResult, type ExtractionClaim, type ExtractionKind, type ExtractionTerm, type Freshness, type FreshnessConfig, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GitHookStatus, type GraphArtifact, type GraphDiffResult, type GraphEdge, type GraphExplainNeighbor, type GraphExplainResult, type GraphExportFormat, type GraphExportResult, type GraphHyperedge, type GraphNode, type GraphPage, type GraphPathResult, type GraphPushCounts, type GraphPushNeo4jOptions, type GraphPushResult, type GraphQueryMatch, type GraphQueryResult, type GraphReportArtifact, type GuidedSessionMode, type GuidedSourceSessionAnswers, type GuidedSourceSessionQuestion, type GuidedSourceSessionRecord, type GuidedSourceSessionStatus, type ImageGenerationRequest, type ImageGenerationResponse, type ImageVisionExtraction, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type InputIngestResult, type InstallAgentOptions, type InstallAgentResult, LARGE_REPO_NODE_THRESHOLD, type LintFinding, type LintOptions, type ManagedSourceAddOptions, type ManagedSourceAddResult, type ManagedSourceDeleteResult, type ManagedSourceKind, type ManagedSourceRecord, type ManagedSourceReloadOptions, type ManagedSourceReloadResult, type ManagedSourceStatus, type ManagedSourceSyncCounts, type ManagedSourcesArtifact, type MemoryTier, type Neo4jGraphSinkConfig, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type PendingSemanticRefreshEntry, type Polarity, type PromotionDecision, type PromotionGateKind, type PromotionGateResult, type PromotionSession, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type RedactionMatchSummary, type RedactionPatternConfig, type RedactionSettings, type RedactionSummary, type RepoSyncResult, type ResolvedLargeRepoDefaults, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledConsolidateTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceCaptureType, type SourceClaim, type SourceClass, type SourceExtractionArtifact, type SourceGuideResult, type SourceKind, type SourceManifest, type SourceRationale, type SourceReviewResult, type SynthesizedHubEdge, type SynthesizedHubNode, type SynthesizedHyperedgeHubs, type VaultConfig, type VaultDashboardPack, type VaultProfileConfig, type VaultProfilePreset, type WatchConfig, type WatchController, type WatchOptions, type WatchRepoSyncResult, type WatchRunRecord, type WatchStatusResult, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, addInput, addManagedSource, addWatchedRoot, agentTypeSchema, applyDecayToPages, archiveCandidate, assertProviderCapability, autoCommitWikiChanges, benchmarkVault, blastRadius, blastRadiusVault, bootstrapDemo, buildConfiguredRedactor, buildRedactor, compileVault, computeDecayScore, consolidateVault, createMcpServer, createProvider, createSupersessionEdge, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, deleteManagedSource, estimatePageTokens, estimateTokens, evaluateCandidateForPromotion, explainGraphVault, exploreVault, exportGraphFormat, exportGraphHtml, exportGraphReportHtml, exportObsidianCanvas, exportObsidianVault, getGitHookStatus, getProviderForTask, getWatchStatus, getWebSearchAdapterForTask, getWorkspaceInfo, graphDiff, guideManagedSource, guideSourceScope, importInbox, ingestDirectory, ingestInput, ingestInputDetailed, initVault, initWorkspace, installAgent, installConfiguredAgents, installGitHooks, lintVault, listApprovals, listCandidates, listGodNodes, listGraphHyperedges, listManagedSourceRecords, listManifests, listPages, listSchedules, listTrackedRepoRoots, listWatchedRoots, loadVaultConfig, loadVaultSchema, loadVaultSchemas, markSuperseded, pathGraphVault, persistDecayFrontmatter, previewCandidatePromotions, promoteCandidate, providerCapabilitySchema, providerTypeSchema, pushGraphNeo4j, queryGraphVault, queryVault, readApproval, readExtractedText, readGraphReport, readPage, rejectApproval, reloadManagedSources, removeWatchedRoot, resetDecay, resolveConsolidationConfig, resolveDecayConfig, resolveLargeRepoDefaults, resolvePaths, resolveRedactionPatterns, resolveWatchedRepoRoots, resumeSourceSession, reviewManagedSource, reviewSourceScope, runAutoPromotion, runConsolidation, runDecayPass, runSchedule, runWatchCycle, searchVault, serveSchedules, stageGeneratedOutputPages, startGraphServer, startMcpServer, syncTrackedRepos, syncTrackedReposForWatch, synthesizeHyperedgeHubs, trimToTokenBudget, uninstallGitHooks, watchVault, webSearchProviderTypeSchema };