@vibgrate/cli 2026.722.2 → 2026.727.1

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { G as GraphNode, a as GraphEdge, A as Area, R as ResolverKind, V as VgGraph, F as FileParse, E as EdgeKind, b as Fact, c as GroundingKind, d as GroundingEdge } from './types-Jl6RJ175.js';
-export { C as Centrality, D as DerivedBy, e as EpistemicTier, f as FactConfidence, g as FactKind, h as GraphMeta, N as NodeKind, P as Provenance, S as SCHEMA_VERSION, i as Span, T as Toolchain, U as Unknown } from './types-Jl6RJ175.js';
+import { G as GraphNode, a as GraphEdge, A as Area, R as ResolverKind, V as VgGraph, F as FileParse, E as EdgeKind, b as Fact, c as GroundingKind, d as GroundingEdge } from './types-ZMg1mSuu.js';
+export { C as Centrality, D as DerivedBy, e as EpistemicTier, f as FactConfidence, g as FactKind, h as GraphMeta, N as NodeKind, P as Provenance, S as SCHEMA_VERSION, i as Span, T as Toolchain, U as Unknown } from './types-ZMg1mSuu.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
-declare const VERSION = "2026.722.2";
+declare const VERSION = "2026.727.1";
 
 /**
  * Analysis stage: importance, centrality, hubs, communities, and surprise.
@@ -214,7 +214,13 @@ interface BuildResult {
 }
 declare function buildGraph(options: BuildOptions): Promise<BuildResult>;
 
-/** Load a committed `graph.json`. Returns null if none exists at the path. */
+/**
+ * Load the code map for a repository.
+ *
+ * When `graphPath` is omitted, prefers an existing global-store snapshot, then
+ * the legacy `.vibgrate/graph.json`, matching {@link resolveGraphPath}.
+ * Returns null if none exists at the resolved path.
+ */
 declare function loadGraph(root: string, graphPath?: string): VgGraph | null;
 
 /**
@@ -231,9 +237,19 @@ declare function stableStringify(value: unknown, indent?: number): string;
 declare function parseGraph(json: string): VgGraph;
 
 /**
- * Write the build artifacts under `.vibgrate/`. `graph.json` is the committable
- * map; `GRAPH_REPORT.md` and `graph.html` are convenience artifacts (volatile —
- * gitignored by default via `vg share`).
+ * Graph artifact layout (Fusion Runtime Phase 1).
+ *
+ * By default the code map lives in the **global** application store
+ * (XDG / Application Support), keyed by repository id — not inside the repo.
+ * That keeps `vg` / `vg serve` / auto-refresh from dirtying the working tree.
+ *
+ * Legacy in-repo path `.vibgrate/graph.json` is still **read** when present
+ * (migration), and is still the write target when:
+ *   - `VIBGRATE_GRAPH_IN_REPO=1` (or true/yes), or
+ *   - callers pass an explicit `graphPath` / `--graph`.
+ *
+ * `vg share` continues to opt into a committed in-repo map by writing under
+ * `.vibgrate/` (and rewriting its gitignore).
  */
 interface WriteOptions {
     root: string;
@@ -248,7 +264,31 @@ interface WrittenArtifacts {
     factsPath?: string;
 }
 declare function vibgrateDir(root: string): string;
-declare function defaultGraphPath(root: string): string;
+/** Historical in-repo map path (still read as a fallback). */
+declare function legacyGraphPath(root: string): string;
+/**
+ * When true, default writes go to `.vibgrate/graph.json` (pre–Phase-1 layout).
+ * Useful for CI that asserts in-repo artifacts, and for `vg share` workflows.
+ */
+declare function preferInRepoGraph(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Default **write** path for the map. Global store unless the operator opts
+ * into the legacy in-repo layout. When git is available, prefer a
+ * branch-keyed snapshot (Fusion §4.1.1) so switching branches does not
+ * overwrite another ref's on-disk map.
+ */
+declare function defaultGraphPath(root: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Resolve where to **read** the map from.
+ * Order: explicit override → legacy in-repo when `VIBGRATE_GRAPH_IN_REPO` is set
+ * → branch-keyed global (if on a git ref) → `current` global snapshot →
+ * legacy in-repo → default write path.
+ *
+ * The in-repo env short-circuit matters for CI and the release benchmark: they
+ * force portable `.vibgrate/graph.json` artifacts and must not pay a synchronous
+ * `git rev-parse` (or prefer a leftover global snapshot) on every resolve.
+ */
+declare function resolveGraphPath(root: string, override?: string, env?: NodeJS.ProcessEnv): string;
 declare function writeArtifacts(graph: VgGraph, options: WriteOptions): WrittenArtifacts;
 
 interface VerifyResult {
@@ -432,8 +472,10 @@ declare function loadEmbedder(options?: LoadEmbedderOptions): Promise<Embedder |
  * strongest available signal — the node's **doc-comment / docstring** summary —
  * plus lightweight context already on the graph (file-path words, area label), so
  * a tersely-named symbol (`Table`, `NotificationJob`) a concept query can reach.
- * Only the short, truncated doc summary is used (captured at build time); no full
- * file bodies, so the graph artifact stays deterministic.
+ *
+ * `document` nodes (markdown, manifests, Docker, CI, OpenAPI, …) put the
+ * scrubbed body in `doc` — that body is the primary embed signal so `vg ask`
+ * can answer project-context questions, not only code symbols.
  */
 declare function nodeEmbedText(node: GraphNode, areaLabel?: string): string;
 declare function cosine(a: number[], b: number[]): number;
@@ -605,6 +647,121 @@ interface VgTool {
 }
 declare const TOOLS: VgTool[];
 
+/** The graph-affecting discovery/build scope, replayed verbatim on refresh. */
+interface BuildScope {
+    only?: string[];
+    exclude?: string[];
+    paths?: string[];
+    deep?: boolean;
+    noGround?: boolean;
+    scip?: string;
+    noScip?: boolean;
+    noTsc?: boolean;
+    cluster?: string;
+    grammarsDir?: string;
+}
+interface SnapshotFile {
+    version: string;
+    /** corpusHash of the build this snapshot belongs to. */
+    corpusHash: string;
+    scope: BuildScope;
+    files: Record<string, {
+        size: number;
+        mtimeMs: number;
+        hash: string;
+    }>;
+}
+interface Drift {
+    /** Files whose *content* changed (stat moved AND hash differs). */
+    changed: string[];
+    /** Files present now but absent from the snapshot. */
+    added: string[];
+    /** Snapshot files no longer present. */
+    removed: string[];
+}
+interface ProbeResult {
+    drift: Drift;
+    /** The recorded build scope — what a refresh must replay. */
+    scope: BuildScope;
+    /** corpusHash the current map was built from. */
+    corpusHash: string;
+}
+/** Persist the snapshot after a successful build. Best-effort (cache-only). */
+declare function writeSnapshot(root: string, corpusHash: string, fileStats: FileStat[], scope?: BuildScope): void;
+declare function loadSnapshot(root: string): SnapshotFile | null;
+declare function hasDrift(drift: Drift): boolean;
+/** Total drifted files — the number shown to humans. */
+declare function driftCount(drift: Drift): number;
+/**
+ * Compare the working tree to the snapshot. Returns null when no snapshot
+ * exists (nothing was ever built on this machine — auto-refresh stays off
+ * rather than guessing the build scope). Stat-only except for files whose
+ * stat moved; touch-only moves are absorbed back into the snapshot.
+ */
+declare function probeFreshness(root: string): ProbeResult | null;
+
+/**
+ * Auto-refresh: bring the code map back in sync with the working tree when the
+ * freshness probe says it drifted. The rebuild is the ordinary incremental
+ * `buildGraph` (warm parse cache → only changed files re-parse), replaying the
+ * scope recorded at the last explicit build, guarded by a cross-process lock
+ * so a serving MCP process and a foreground command never write at once.
+ *
+ * Two properties keep this safe to run implicitly:
+ * - **No git churn**: if the rebuilt corpusHash equals the snapshot's (e.g. a
+ *   drift that reverted itself), `graph.json` is left untouched — the artifact
+ *   stays byte-identical.
+ * - **No surprise artifacts**: `GRAPH_REPORT.md`/`graph.html` are rewritten
+ *   only if they already exist; a refresh never adds files a user's explicit
+ *   build chose not to produce.
+ */
+interface RefreshOptions {
+    /** Force single-threaded parsing (tests / constrained hosts). */
+    inline?: boolean;
+    /** Worker count for the parse pool. */
+    jobs?: number;
+    /**
+     * The map path already resolved by the caller (e.g. `vg serve`'s startup
+     * resolution). Passed straight through to `writeArtifacts` so a refresh
+     * never re-resolves it: `defaultGraphPath` shells out to `git rev-parse`
+     * (Fusion §4.1.1 branch keying), and re-running that on every drift-driven
+     * refresh put a synchronous git spawn back on the hot tool-call path this
+     * function exists to keep off of. Omit only when no caller-known path
+     * exists (falls back to a fresh `defaultGraphPath` resolution).
+     */
+    graphPath?: string;
+}
+type RefreshOutcome = 
+/** Map already matches the working tree. */
+{
+    status: 'fresh';
+}
+/** No freshness snapshot — no build ever ran here, so scope is unknown. */
+ | {
+    status: 'no-snapshot';
+}
+/** Another vg process is rebuilding right now; its write will land shortly. */
+ | {
+    status: 'locked';
+}
+/** Rebuilt. `wrote` is false when the corpus turned out unchanged. */
+ | {
+    status: 'refreshed';
+    drift: Drift;
+    ms: number;
+    reparsed: number;
+    totalFiles: number;
+    wrote: boolean;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Probe, and rebuild incrementally if the tree drifted from the map.
+ * Silent (no output) — callers own the messaging for their surface.
+ */
+declare function refreshIfStale(root: string, opts?: RefreshOptions): Promise<RefreshOutcome>;
+
 /**
  * How a navigation call reached the map:
  *  - `mcp` — a tool call over the local `vg serve` MCP server;
@@ -732,6 +889,19 @@ declare class SessionStats {
     private rowFor;
 }
 
+type RefreshImpl = typeof refreshIfStale;
+interface GraphSourceTuning {
+    probeIntervalMs?: number;
+    refreshBudgetMs?: number;
+    /**
+     * Workspace root for freshness probes. Prefer passing this explicitly —
+     * deriving it from `graphPath` via `dirname` twice only works for the legacy
+     * `root/.vibgrate/graph.json` layout, not the global branch-keyed store.
+     */
+    root?: string;
+    /** Tests only: inject a slow/fake refresh to assert the micro-budget. */
+    refreshImpl?: RefreshImpl;
+}
 interface ServeOptions {
     /** Record local, counts-only usage savings (opt-in). */
     savings?: boolean;
@@ -748,6 +918,11 @@ interface ServeOptions {
     dedup?: boolean;
     /** Auto-refresh the map when the working tree drifts (default true). */
     refresh?: boolean;
+    /**
+     * Workspace root (project directory). When set, freshness probes and tools
+     * use this instead of inferring root from the graph path.
+     */
+    root?: string;
     /**
      * In-memory session stats behind the live `vg serve` status display. Always
      * safe to pass: nothing recorded here is persisted or uploaded — it dies with
@@ -758,22 +933,21 @@ interface ServeOptions {
 declare class GraphSource {
     readonly graphPath: string;
     private readonly refresh;
-    /** Timing overrides (tests only). */
+    /** Timing / root overrides (production passes `root`; tests may pass more). */
     private readonly tuning;
     private cachedMtimeMs;
     private cached;
-    private readonly root;
+    /** Project root used for freshness probes and rebuilds. */
+    readonly root: string;
     private lastProbeAt;
     private failedUntil;
     private inflight;
-    /** Self-tuned: grows with measured probe cost so huge repos aren't penalized. */
+    /** Self-tuned: grows with measured probe/rebuild cost so huge repos aren't penalized. */
     private probeIntervalMs;
+    private readonly refreshImpl;
     constructor(graphPath: string, refresh?: boolean, 
-    /** Timing overrides (tests only). */
-    tuning?: {
-        probeIntervalMs?: number;
-        refreshBudgetMs?: number;
-    });
+    /** Timing / root overrides (production passes `root`; tests may pass more). */
+    tuning?: GraphSourceTuning);
     /** Current graph: auto-refreshed if the tree drifted, reloaded if the file changed. */
     get(): Promise<VgGraph>;
     /**
@@ -785,111 +959,6 @@ declare class GraphSource {
 declare function createServer(source: GraphSource, opts?: ServeOptions): Server;
 declare function serveStdio(graphPath: string, opts?: ServeOptions): Promise<void>;
 
-/** The graph-affecting discovery/build scope, replayed verbatim on refresh. */
-interface BuildScope {
-    only?: string[];
-    exclude?: string[];
-    paths?: string[];
-    deep?: boolean;
-    noGround?: boolean;
-    scip?: string;
-    noScip?: boolean;
-    noTsc?: boolean;
-    cluster?: string;
-    grammarsDir?: string;
-}
-interface SnapshotFile {
-    version: string;
-    /** corpusHash of the build this snapshot belongs to. */
-    corpusHash: string;
-    scope: BuildScope;
-    files: Record<string, {
-        size: number;
-        mtimeMs: number;
-        hash: string;
-    }>;
-}
-interface Drift {
-    /** Files whose *content* changed (stat moved AND hash differs). */
-    changed: string[];
-    /** Files present now but absent from the snapshot. */
-    added: string[];
-    /** Snapshot files no longer present. */
-    removed: string[];
-}
-interface ProbeResult {
-    drift: Drift;
-    /** The recorded build scope — what a refresh must replay. */
-    scope: BuildScope;
-    /** corpusHash the current map was built from. */
-    corpusHash: string;
-}
-/** Persist the snapshot after a successful build. Best-effort (cache-only). */
-declare function writeSnapshot(root: string, corpusHash: string, fileStats: FileStat[], scope?: BuildScope): void;
-declare function loadSnapshot(root: string): SnapshotFile | null;
-declare function hasDrift(drift: Drift): boolean;
-/** Total drifted files — the number shown to humans. */
-declare function driftCount(drift: Drift): number;
-/**
- * Compare the working tree to the snapshot. Returns null when no snapshot
- * exists (nothing was ever built on this machine — auto-refresh stays off
- * rather than guessing the build scope). Stat-only except for files whose
- * stat moved; touch-only moves are absorbed back into the snapshot.
- */
-declare function probeFreshness(root: string): ProbeResult | null;
-
-/**
- * Auto-refresh: bring the code map back in sync with the working tree when the
- * freshness probe says it drifted. The rebuild is the ordinary incremental
- * `buildGraph` (warm parse cache → only changed files re-parse), replaying the
- * scope recorded at the last explicit build, guarded by a cross-process lock
- * so a serving MCP process and a foreground command never write at once.
- *
- * Two properties keep this safe to run implicitly:
- * - **No git churn**: if the rebuilt corpusHash equals the snapshot's (e.g. a
- *   drift that reverted itself), `graph.json` is left untouched — the artifact
- *   stays byte-identical.
- * - **No surprise artifacts**: `GRAPH_REPORT.md`/`graph.html` are rewritten
- *   only if they already exist; a refresh never adds files a user's explicit
- *   build chose not to produce.
- */
-interface RefreshOptions {
-    /** Force single-threaded parsing (tests / constrained hosts). */
-    inline?: boolean;
-    /** Worker count for the parse pool. */
-    jobs?: number;
-}
-type RefreshOutcome = 
-/** Map already matches the working tree. */
-{
-    status: 'fresh';
-}
-/** No freshness snapshot — no build ever ran here, so scope is unknown. */
- | {
-    status: 'no-snapshot';
-}
-/** Another vg process is rebuilding right now; its write will land shortly. */
- | {
-    status: 'locked';
-}
-/** Rebuilt. `wrote` is false when the corpus turned out unchanged. */
- | {
-    status: 'refreshed';
-    drift: Drift;
-    ms: number;
-    reparsed: number;
-    totalFiles: number;
-    wrote: boolean;
-} | {
-    status: 'error';
-    message: string;
-};
-/**
- * Probe, and rebuild incrementally if the tree drifted from the map.
- * Silent (no output) — callers own the messaging for their surface.
- */
-declare function refreshIfStale(root: string, opts?: RefreshOptions): Promise<RefreshOutcome>;
-
 /**
  * Test-awareness (VG-ENGINE-TEARDOWN §3.6) — the wedge Graphify has no answer to.
  *
@@ -1042,8 +1111,8 @@ declare function enrichOnline(records: DepRecord[], fetchImpl?: typeof fetch): P
 /**
  * Local-model discovery (VG-LOCAL-MODELS §9.2) — be a no-key *consumer* of the
  * developer's local model fleet. Fully offline and deterministic: inspect the
- * on-disk layouts of Ollama / LM Studio / llama.cpp, never the network. No
- * runtime is built or launched.
+ * on-disk layouts of Ollama / LM Studio / llama.cpp / the Vibgrate weight store,
+ * never the network. No runtime is built or launched.
  */
 interface LocalModel {
     runtime: 'ollama' | 'lm-studio' | 'gguf';
@@ -1211,4 +1280,241 @@ declare function redactGraph(graph: VgGraph): VgGraph;
  */
 declare function grammarsSourceDir(): string | null;
 
-export { ASSISTANTS, type AnalyzeOptions, type AnalyzeResult, Area, type Assistant, type BuildOptions, type BuildResult, type BuildScope, type ClusterMode, type DepRecord, type DiscoverOptions, type DiscoveredFile, type Drift, type DriftInventory, type DriftNote, EdgeKind, type Embedder, type ExportContext, type ExportFormat, FREE_PACK, Fact, FileParse, GraphEdge, GraphIndex, GraphNode, GraphSource, type GraphUploadEnvelope, GroundingEdge, GroundingKind, type ImpactItem, type ImpactResult, type KnowledgePack, LANGUAGES, type LanguageDef, type LibCatalog, type LibEntry, type LibSource, type LoadEmbedderOptions, type LocalModel, type ModuleResolver, type PackEntry, type PathResult, type ProbeResult, type QueryMatch, type QueryOptions, type QueryResult, type RefreshOptions, type RefreshOutcome, ResolverKind, ResourceLimitError, type ResourceLimits, SKIP_DIRS, SKIP_FILES, type SavingsReport, type ScipDocument, type ScipIndex, type ScipOccurrence, type SemanticQueryOptions, type ServeOptions, TOOLS, UsageError, VERSION, type VerifyResult, VgGraph, type VgTool, type WriteOptions, type WrittenArtifacts, addLibrary, allLanguageIds, analyze, applyCoverage, applyStaticTestLinkage, assistantById, buildEnvelope, buildFacts, buildGraph, buildModuleResolver, cosine, coveringTests, createServer, decodeScipIndex, defaultGraphPath, inventory as dependencyInventory, detectRunner, discover, discoverModels, driftCount, driftFor, enrichOnline, exportGraph, findNodes, formatForExt, getNodeEmbeddings, grammarsSourceDir, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, isTestFile, langById, langForExtension, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, nodeById, nodeEmbedText, parseGraph, parseJsonc, parseSource, probeFreshness, queryGraph, queryGraphSemantic, readDoc, readSavings, recordSaving, redactGraph, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveLib, resolveLimits, resolveOne, saveCatalog, savingsRecorded, scipEdges, serializeGraph, serveStdio, shortestPath, stableStringify, testsToRun, uninstallAssistant, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot };
+/** The graph-grounded context handed to the model, plus what fed it. */
+interface CodeContext {
+    instruction: string;
+    /** Symbols the retrieval surfaced as most relevant, with their relations. */
+    seeds: {
+        node: GraphNode;
+        why: string;
+    }[];
+    /** Files the edit is expected to touch, in stable order. */
+    targetFiles: string[];
+    /** Blast radius: symbols that call/depend on the seeds (impact-aware review). */
+    impacted: {
+        node: GraphNode;
+        via: string;
+    }[];
+    /** Hard constraints (declared facts) pinned so compaction can't drop them. */
+    pinnedFacts: string[];
+    /** The rendered, budget-bounded prompt block. */
+    rendered: string;
+    tokensEstimate: number;
+}
+
+/**
+ * Graph-grounded context assembly for `vg code` (VG-CLI-CODE §3).
+ *
+ * A generic coding agent starts blind and reconstructs structure by grepping and
+ * reading whole files — which is exactly what blows the context window and
+ * degrades the model. This module instead uses the deterministic code graph to
+ * hand the planner a *small, high-signal, budget-bounded* context: the symbols
+ * most relevant to the instruction, their immediate relations, the blast radius
+ * of changing them, and any declared facts (hard constraints) that must not be
+ * dropped by later compaction. Deterministic given a graph + instruction, so it
+ * is fully offline-testable and benchmarkable.
+ */
+
+interface BuildContextOptions {
+    /** Approx token budget for the rendered block (default 3000). */
+    budget?: number;
+    /** How many retrieval seeds to expand (default 8). */
+    seeds?: number;
+    /** Impact BFS depth for the blast radius (default 2). */
+    impactDepth?: number;
+    /** Restrict the edit surface to these files (from `--file`), if given. */
+    files?: string[];
+}
+/**
+ * Build the context block for a coding instruction. The ordering is
+ * cache-stable by design (see router.ts): the invariant, repo-derived material
+ * (facts, symbols, relations) comes first and the volatile instruction is
+ * echoed last, so a provider's prompt cache can reuse the stable prefix across
+ * turns.
+ */
+declare function buildCodeContext(graph: VgGraph, instruction: string, options?: BuildContextOptions): CodeContext;
+
+/**
+ * Source-bearing Task Capsule compiler (Fusion Runtime Phase 0).
+ *
+ * Today's {@link buildCodeContext} pays for graph metadata, then the model still
+ * calls `read_file` — double payment. This module compiles a Task Capsule that
+ * includes exact source ranges (from Tree-sitter spans already on graph nodes)
+ * so the first inference can solve without navigation tool calls (ZNS@1 path).
+ *
+ * Deterministic given (graph, instruction, file contents, options). Injectable
+ * `readFile` keeps unit tests offline and pure.
+ *
+ * Schema: docs/fusion/task-capsule-v0.schema.json
+ */
+
+declare const TASK_CAPSULE_SCHEMA_VERSION: "task-capsule/0";
+/** Frozen ranking policy id — bump when the heuristic changes (benchmark gate). */
+declare const CAPSULE_RANKING_VERSION: "capsule-rank@2026.07.0";
+declare const CAPSULE_COMPILER_ID: "vg-task-capsule/0";
+interface BuildCapsuleOptions extends BuildContextOptions {
+    /**
+     * Read file contents relative to the repository root. Required for source
+     * slices; when omitted, the capsule still builds metadata + empty slices
+     * (useful for schema/shape tests).
+     */
+    readFile?: (relativePath: string) => string | null;
+    /** Extra lines of context around each symbol span (default 1). */
+    padding?: number;
+    /** Max source slices after merge (default 12). */
+    maxSlices?: number;
+    repositoryId?: string | null;
+    /** Optional provenance from the Model Execution Profile / security ladder. */
+    provenance?: CapsuleProvenanceExtras;
+    /**
+     * Extra pinned facts (e.g. high-confidence federation bridge edges) appended
+     * after graph-derived facts. Secret-free, short strings only.
+     */
+    extraPinnedFacts?: string[];
+}
+interface CapsuleSymbolRef {
+    id: string;
+    qualifiedName: string;
+    kind: string;
+    file: string;
+    span: {
+        start: number;
+        end: number;
+    };
+    signature?: string | null;
+    why: string;
+    importance: number;
+}
+interface SourceSlice {
+    file: string;
+    start: number;
+    end: number;
+    content: string;
+    contentHash: string;
+    symbolIds: string[];
+}
+interface CapsuleRelationship {
+    kind: 'calls' | 'called-by' | 'impacts' | 'contains' | 'other';
+    from: string;
+    to: string;
+}
+interface VerificationPlan {
+    syntaxFiles: string[];
+    suggestedTests: string[];
+    notes: string[];
+}
+interface TaskCapsule {
+    schemaVersion: typeof TASK_CAPSULE_SCHEMA_VERSION;
+    instruction: string;
+    primary: CapsuleSymbolRef[];
+    supporting: CapsuleSymbolRef[];
+    sourceSlices: SourceSlice[];
+    relationships: CapsuleRelationship[];
+    pinnedFacts: string[];
+    targetFiles: string[];
+    verificationPlan: VerificationPlan;
+    rendered: string;
+    tokensEstimate: number;
+    provenance: {
+        compiler: string;
+        rankingVersion: string;
+        graphCorpusHash: string | null;
+        repositoryId: string | null;
+        /** Model Execution Profile id when resolved (Fusion Phase 4/7). */
+        modelProfileId?: string | null;
+        /** Security tier for shell during this task. */
+        securityTier?: string | null;
+        /** Frozen policy / ranking patch id if any. */
+        policyVersion?: string | null;
+    };
+}
+interface CapsuleProvenanceExtras {
+    modelProfileId?: string | null;
+    securityTier?: string | null;
+    policyVersion?: string | null;
+}
+/** Host-safe capsule summary for VS Code / stream-json capsule transparency. */
+interface CapsuleSummary {
+    schemaVersion: string;
+    instruction: string;
+    primary: Array<{
+        qualifiedName: string;
+        file: string;
+        kind: string;
+    }>;
+    supporting: Array<{
+        qualifiedName: string;
+        file: string;
+        kind: string;
+    }>;
+    sourceSliceCount: number;
+    sourceFiles: string[];
+    tokensEstimate: number;
+    rankingVersion: string;
+    /** Truncated rendered capsule for display (not the full prompt dump). */
+    preview: string;
+}
+/** Host-safe capsule summary (capsule transparency UI / stream-json). */
+declare function summarizeCapsule(capsule: TaskCapsule): CapsuleSummary;
+/**
+ * Compile a source-bearing Task Capsule. Reuses the same seed / impact /
+ * fact-pinning path as {@link buildCodeContext}, then attaches exact source
+ * slices and a verification sketch.
+ */
+declare function buildTaskCapsule(graph: VgGraph, instruction: string, options?: BuildCapsuleOptions): TaskCapsule;
+/**
+ * Project a capsule into the legacy {@link CodeContext} shape so the existing
+ * agent prompt path can consume it without a full rewrite (A/B flag).
+ */
+declare function capsuleToCodeContext(capsule: TaskCapsule): CodeContext;
+
+/**
+ * `search_symbols` — the hybrid flashlight next to the map
+ * (docs/graph/VG-GRAPH-OPTIMIZATION-PLAN.md P1).
+ *
+ * Two passes, both bounded and deterministic:
+ *   1. symbol pass — the graph's own name index via findNodes (exact id /
+ *      qualified name / short name / case-insensitive / substring), ranked;
+ *   2. literal pass — a repo-root-jailed substring scan over source files for
+ *      strings the graph does not model (config keys, log messages, comments),
+ *      only run when the symbol pass has spare result budget.
+ *
+ * Rows are tiny by contract ({kind, name, file, line, score|preview}) — this
+ * tool exists to make "I know the name" discovery one cheap call, so the model
+ * never flails through graph queries for a plain string lookup.
+ */
+interface SymbolHit {
+    kind: string;
+    name: string;
+    file: string;
+    line: number;
+    score: number;
+}
+interface TextHit {
+    kind: 'text';
+    file: string;
+    line: number;
+    preview: string;
+}
+interface SearchResult {
+    matches: (SymbolHit | TextHit)[];
+    moreAvailable: boolean;
+    /**
+     * Total literal (text) matches across the scanned tree, reported when a
+     * literal sweep ran (a whitespace/phrase query). Lets a caller doing a "find
+     * every occurrence" sweep know whether the shown text rows are the complete
+     * set (`totalTextMatches` === shown text rows) or a page of a larger set
+     * (`totalTextMatches` > shown) — so it never mistakes a truncated list for a
+     * complete one, and never has to fall back to grep to be sure. A trailing `+`
+     * intent is signalled via `moreAvailable`; absent for single-name lookups.
+     */
+    totalTextMatches?: number;
+    /**
+     * Present when nothing matched (the pivot to take) or when a literal sweep was
+     * truncated (how to get the rest).
+     */
+    hint?: string;
+}
+declare function searchSymbols(graph: VgGraph, root: string, query: string, limit: number): Promise<SearchResult>;
+
+export { ASSISTANTS, type AnalyzeOptions, type AnalyzeResult, Area, type Assistant, type BuildCapsuleOptions, type BuildContextOptions, type BuildOptions, type BuildResult, type BuildScope, CAPSULE_COMPILER_ID, CAPSULE_RANKING_VERSION, type CapsuleSummary, type CapsuleSymbolRef, type ClusterMode, type DepRecord, type DiscoverOptions, type DiscoveredFile, type Drift, type DriftInventory, type DriftNote, EdgeKind, type Embedder, type ExportContext, type ExportFormat, FREE_PACK, Fact, FileParse, GraphEdge, GraphIndex, GraphNode, GraphSource, type GraphUploadEnvelope, GroundingEdge, GroundingKind, type ImpactItem, type ImpactResult, type KnowledgePack, LANGUAGES, type LanguageDef, type LibCatalog, type LibEntry, type LibSource, type LoadEmbedderOptions, type LocalModel, type ModuleResolver, type PackEntry, type PathResult, type ProbeResult, type QueryMatch, type QueryOptions, type QueryResult, type RefreshOptions, type RefreshOutcome, ResolverKind, ResourceLimitError, type ResourceLimits, SKIP_DIRS, SKIP_FILES, type SavingsReport, type ScipDocument, type ScipIndex, type ScipOccurrence, type SearchResult, type SemanticQueryOptions, type ServeOptions, type SourceSlice, type SymbolHit, TASK_CAPSULE_SCHEMA_VERSION, TOOLS, type TaskCapsule, type TextHit, UsageError, VERSION, type VerifyResult, VgGraph, type VgTool, type WriteOptions, type WrittenArtifacts, addLibrary, allLanguageIds, analyze, applyCoverage, applyStaticTestLinkage, assistantById, buildCodeContext, buildEnvelope, buildFacts, buildGraph, buildModuleResolver, buildTaskCapsule, capsuleToCodeContext, cosine, coveringTests, createServer, decodeScipIndex, defaultGraphPath, inventory as dependencyInventory, detectRunner, discover, discoverModels, driftCount, driftFor, enrichOnline, exportGraph, findNodes, formatForExt, getNodeEmbeddings, grammarsSourceDir, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, isTestFile, langById, langForExtension, legacyGraphPath, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, nodeById, nodeEmbedText, parseGraph, parseJsonc, parseSource, preferInRepoGraph, probeFreshness, queryGraph, queryGraphSemantic, readDoc, readSavings, recordSaving, redactGraph, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveGraphPath, resolveLib, resolveLimits, resolveOne, saveCatalog, savingsRecorded, scipEdges, searchSymbols, serializeGraph, serveStdio, shortestPath, stableStringify, summarizeCapsule, testsToRun, uninstallAssistant, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot };

package/dist/index.js

@@ -1,13 +1,20 @@
-export { GraphSource, createServer, exportGraph, formatForExt, serveStdio } from './chunk-2O5YZVZV.js';
-export { ASSISTANTS, FREE_PACK, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, analyze, applyCoverage, applyStaticTestLinkage, assistantById, buildFacts, buildGraph, buildModuleResolver, coveringTests, decodeScipIndex, defaultGraphPath, detectRunner, discover, discoverModels, driftCount, groundGraph, hasDrift, installAssistant, isTestFile, loadCoverage, loadGraph, loadSnapshot, parseJsonc, probeFreshness, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveLimits, scipEdges, shortestPath, testsToRun, uninstallAssistant, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot } from './chunk-3MXNNBLI.js';
-export { addLibrary, inventory as dependencyInventory, driftFor, enrichOnline, findNodes, libId, loadCatalog, nodeById, readDoc, resolveLib, resolveOne, saveCatalog } from './chunk-GGJZA3Q6.js';
-export { VERSION } from './chunk-5BDHQ7DD.js';
-export { LANGUAGES, allLanguageIds, grammarsSourceDir, langById, langForExtension, parseSource } from './chunk-PY3DNX5H.js';
+export { GraphSource, createServer, exportGraph, formatForExt, serveStdio } from './chunk-65MEOA4E.js';
+export { ASSISTANTS, FREE_PACK, ResourceLimitError, SCHEMA_VERSION, SKIP_DIRS, SKIP_FILES, TOOLS, UsageError, analyze, applyCoverage, assistantById, buildFacts, buildGraph, coveringTests, decodeScipIndex, detectRunner, discover, driftCount, groundGraph, hasDrift, installAssistant, loadCoverage, loadSnapshot, probeFreshness, refreshIfStale, resolveLimits, scipEdges, searchSymbols, shortestPath, testsToRun, uninstallAssistant, verifyDeterminism, writeSnapshot } from './chunk-S6CYDZEW.js';
+export { VERSION } from './chunk-WLETRGAC.js';
+export { addLibrary, applyStaticTestLinkage, buildModuleResolver, inventory as dependencyInventory, driftFor, enrichOnline, isTestFile, libId, loadCatalog, parseJsonc, readDoc, relativeResolver, resolveLib, saveCatalog } from './chunk-C4CKTAZP.js';
+export { findNodes, nodeById, resolveOne } from './chunk-J7LKEB2R.js';
+export { discoverModels } from './chunk-OOIG3RUM.js';
+export { CAPSULE_COMPILER_ID, CAPSULE_RANKING_VERSION, TASK_CAPSULE_SCHEMA_VERSION, buildCodeContext, buildTaskCapsule, capsuleToCodeContext, readSavings, recordSaving, savingsRecorded, summarizeCapsule } from './chunk-EDAAG7BL.js';
+export { GraphIndex, cosine, getNodeEmbeddings, identifierParts, impactOf, loadEmbedder, nodeEmbedText, queryGraph, queryGraphSemantic } from './chunk-6IOQJGFT.js';
+export { LANGUAGES, allLanguageIds, grammarsSourceDir, langById, langForExtension, parseSource } from './chunk-3Q7QBWFW.js';
 import { redactUrlCredentials, redactSecrets } from './chunk-RXP66R2E.js';
+export { defaultGraphPath, legacyGraphPath, loadGraph, preferInRepoGraph, renderHtml, renderReport, resolveGraphPath, vibgrateDir, writeArtifacts } from './chunk-HABUT7HW.js';
+export { parseGraph, serializeGraph, stableStringify } from './chunk-5Q54GEHM.js';
+import './chunk-BWPBB45M.js';
+import './chunk-JFGYT6BI.js';
+import './chunk-BPF3YX2U.js';
 import './chunk-GI6W53LM.js';
 import './chunk-CRAMOEBE.js';
-export { GraphIndex, cosine, getNodeEmbeddings, identifierParts, impactOf, loadEmbedder, nodeEmbedText, parseGraph, queryGraph, queryGraphSemantic, readSavings, recordSaving, savingsRecorded, serializeGraph, stableStringify } from './chunk-WNIIKCNF.js';
-import './chunk-JFGYT6BI.js';
 import { execFileSync } from 'child_process';
 
 function buildEnvelope(root, graph, scanIngestId) {