@vibgrate/cli 2026.817.2 → 2026.818.2

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { G as GraphNode, a as GraphEdge, A as Area, R as ResolverKind, V as VgGr
 export { e as AnalysisTier, C as Centrality, D as DerivedBy, f as EpistemicTier, g as FactConfidence, h as FactKind, i as GraphMeta, j as GraphSummaries, H as HubBlastSummary, N as NodeKind, P as Provenance, k as SUPPORTED_SCHEMA_VERSIONS, l as Span, m as SupportedSchemaVersion, T as Toolchain, U as Unknown } from './types-DHqH0XIE.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
-declare const VERSION = "2026.817.2";
+declare const VERSION = "2026.818.2";
 
 /**
  * Analysis stage: importance, centrality, hubs, communities, and surprise.
@@ -699,9 +699,24 @@ interface QueryResult {
 }
 declare function queryGraph(graph: VgGraph, question: string, options?: QueryOptions): QueryResult;
 interface SemanticQueryOptions extends QueryOptions {
-    embedder: Embedder;
+    /** Local embedder. Optional only when {@link semanticRanked} supplies the pass. */
+    embedder?: Embedder;
     /** Precomputed node vectors (from getNodeEmbeddings); falls back to lexical for nodes without one. */
-    nodeVectors: Map<string, number[]>;
+    nodeVectors?: Map<string, number[]>;
+    /**
+     * A semantic pass someone else already ran — vgd ranking the question
+     * against its resident slot index. Supplied instead of `embedder` +
+     * `nodeVectors` so the caller pays neither a model load nor a vector scan,
+     * and no vectors cross the socket.
+     *
+     * Only the ORDER of this list is consumed (RRF fuses rankings, not scores),
+     * so a truncated top-K is not an approximation: a candidate ranked past a
+     * few hundred cannot reach a 12-row answer.
+     */
+    semanticRanked?: Array<{
+        id: string;
+        score: number;
+    }>;
 }
 /**
  * Hybrid lexical + local-embedding retrieval, combined with Reciprocal Rank
@@ -802,6 +817,597 @@ declare class GraphIndex {
     private resolveTargets;
 }
 
+/**
+ * Wire protocol for the lightweight Vibgrate daemon (`vgd`) — Fusion Runtime Phase 2 prototype.
+ *
+ * Line-delimited JSON over a local Unix domain socket (named pipe on Windows).
+ * No credentials leave this process; the socket is local-only.
+ */
+declare const VGD_PROTOCOL_VERSION: "vgd/0";
+interface WorkspaceRecord {
+    /** Stable repository id (same as global store key). */
+    id: string;
+    /** Absolute repository root. */
+    root: string;
+    /** Absolute path to the current graph snapshot (may not exist yet). */
+    graphPath: string;
+    /** ISO timestamp when this workspace was last registered / refreshed. */
+    registeredAt: string;
+    /** Optional federation label. */
+    label?: string;
+    /** Optional federation role. */
+    role?: 'primary' | 'member';
+    /** Git branch or detached SHA at registration (multi-branch ActiveGraph). */
+    gitRef?: string;
+}
+/** Lightweight ActiveGraph slot summary (no full graph payload). */
+interface GraphSlotSummary {
+    repositoryId: string;
+    gitRef: string;
+    loadedAt: number;
+    lastAccessAt: number;
+    nodeCount: number;
+    current: boolean;
+    idleMs: number;
+    evictable: boolean;
+}
+type VgdRequest = {
+    op: 'ping';
+} | {
+    op: 'status';
+}
+/** Ask the daemon to exit cleanly (honoured only by a standalone `vg daemon start`). */
+ | {
+    op: 'shutdown';
+} | {
+    op: 'list';
+} | {
+    op: 'register';
+    root: string;
+    label?: string;
+    role?: 'primary' | 'member';
+} | {
+    op: 'unregister';
+    root: string;
+} | {
+    op: 'register-federation';
+    primaryRoot: string;
+    members: Array<{
+        root: string;
+        label?: string;
+        role?: 'primary' | 'member';
+    }>;
+} | {
+    op: 'list-graph-slots';
+    repositoryId?: string;
+} | {
+    op: 'select-git-ref';
+    repositoryId: string;
+    gitRef: string;
+} | {
+    op: 'put-graph';
+    repositoryId: string;
+    gitRef: string;
+    graph: unknown;
+}
+/**
+ * Load the workspace's on-disk code map into ActiveGraph inside the daemon
+ * (binary snapshot first, JSON fallback). The fast-path alternative to
+ * shipping the whole graph over the socket with put-graph — use it whenever
+ * the map already exists on disk.
+ */
+ | {
+    op: 'load-graph';
+    root: string;
+    gitRef?: string;
+    graphPath?: string;
+}
+/** Lexical/structural query against the ActiveGraph for a repository. */
+ | {
+    op: 'query-graph';
+    repositoryId: string;
+    query: string;
+    limit?: number;
+    gitRef?: string;
+    semantic?: boolean;
+}
+/** Blast-radius impact for a symbol id or qualified name. */
+ | {
+    op: 'impact-of';
+    repositoryId: string;
+    symbol: string;
+    depth?: number;
+    gitRef?: string;
+}
+/** Compact graph meta for the current (or named) slot — not the full graph. */
+ | {
+    op: 'graph-summary';
+    repositoryId: string;
+    gitRef?: string;
+}
+/** Semantic warm (docs/VGD-SEMANTIC-WARM-SPEC.md): worker + per-slot index state. */
+ | {
+    op: 'embed-status';
+    repositoryId?: string;
+}
+/** Embed one string in the daemon's warm worker; the caller ranks locally. */
+ | {
+    op: 'embed-query';
+    text: string;
+}
+/** Ensure the slot's vector index exists, building it if needed. */
+ | {
+    op: 'embed-index';
+    repositoryId: string;
+    gitRef?: string;
+    wait?: boolean;
+} | {
+    op: 'embed-rank';
+    repositoryId: string;
+    gitRef?: string;
+    text: string;
+    limit?: number;
+} | {
+    op: 'dep-context';
+    repositoryId: string;
+}
+/**
+ * Hold this connection open and stream slot changes on it. The only op that
+ * does not answer once and stop — everything else is request/response.
+ */
+ | {
+    op: 'watch-slots';
+    repositoryId?: string;
+}
+/** Approach B host broker: warm model status inside vgd. */
+ | {
+    op: 'host-status';
+} | {
+    op: 'host-load';
+    modelPath: string;
+} | {
+    op: 'host-unload';
+    modelPath?: string;
+} | {
+    op: 'host-generate';
+    modelPath: string;
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    grammar?: string;
+    requireGrammar?: boolean;
+    maxTokens?: number;
+    temperature?: number;
+};
+/** Semantic warm state: the worker, and one row per resident slot index. */
+interface EmbedStatusPayload {
+    worker: 'stopped' | 'starting' | 'ready' | 'unavailable';
+    pid?: number;
+    model?: string;
+    crashes: number;
+    reason?: string;
+    slots: Array<{
+        repositoryId: string;
+        gitRef: string;
+        state: string;
+        vectors: number;
+        nodeCount: number;
+        /** Targets still missing a vector on a slot that is not ready. */
+        pending?: number;
+        builtAt?: number;
+        buildMs?: number;
+        error?: string;
+    }>;
+}
+/** Compact match row for query-graph (no full node payloads). */
+interface VgdQueryMatch {
+    id: string;
+    qualifiedName: string;
+    kind: string;
+    file: string;
+    line: number;
+    score: number;
+    why: string;
+}
+interface VgdImpactItem {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    depth: number;
+    confidence: number;
+}
+type VgdResponse = {
+    ok: true;
+    pong: true;
+    version: typeof VGD_PROTOCOL_VERSION;
+} | {
+    ok: true;
+    pid: number;
+    uptimeMs: number;
+    workspaces: number;
+    /** Resident multi-branch ActiveGraph slots (Fusion §4.1.1). */
+    graphSlots?: number;
+    version: typeof VGD_PROTOCOL_VERSION;
+    socketPath: string;
+    /** Calendar version of the CLI process serving this socket. */
+    cliVersion?: string;
+    /** What the daemon is watching, and what it is mid-rebuild on. */
+    freshness?: Array<{
+        repositoryId: string;
+        root: string;
+        gitRef: string;
+        watching: boolean;
+        pending: number;
+        building: boolean;
+        lastRebuildAt?: number;
+    }>;
+} | {
+    ok: true;
+    workspaces: WorkspaceRecord[];
+} | {
+    ok: true;
+    workspace: WorkspaceRecord;
+} | {
+    ok: true;
+    workspaces: WorkspaceRecord[];
+    federation: true;
+} | {
+    ok: true;
+    removed: boolean;
+} | {
+    ok: true;
+    stopping: true;
+} | {
+    ok: true;
+    slots: GraphSlotSummary[];
+} | {
+    ok: true;
+    watching: true;
+    repositoryId?: string;
+}
+/**
+ * An unsolicited frame on a `watch-slots` connection: this repo's map
+ * changed and the subscriber should reload it. Carries the corpus hash so a
+ * subscriber that already has that map can ignore the event.
+ */
+ | {
+    ok: true;
+    event: 'slot-changed';
+    repositoryId: string;
+    gitRef: string;
+    nodeCount: number;
+    corpusHash: string | null;
+} | {
+    ok: true;
+    semantic: EmbedStatusPayload;
+} | {
+    ok: true;
+    repositoryId: string;
+    /** Digest of every manifest and lockfile in the tree. */
+    manifestHash: string;
+    /** Declared/installed dependency records, as `engine/drift.ts` builds them. */
+    dependencies: Array<{
+        name: string;
+        ecosystem: string;
+        declared: string;
+        installed?: string;
+    }>;
+    builtAt: number;
+} | {
+    ok: true;
+    vector: number[];
+    model?: string;
+} | {
+    ok: true;
+    ranked: Array<{
+        id: string;
+        score: number;
+    }>;
+    repositoryId: string;
+    gitRef: string;
+    state: string;
+    vectors: number;
+    model?: string;
+    rankMs: number;
+} | {
+    ok: true;
+    indexed: true;
+    repositoryId: string;
+    gitRef: string;
+    state: string;
+    vectors: number;
+    buildMs?: number;
+} | {
+    ok: true;
+    selected: true;
+    repositoryId: string;
+    gitRef: string;
+} | {
+    ok: true;
+    stored: true;
+    repositoryId: string;
+    gitRef: string;
+    nodeCount: number;
+} | {
+    ok: true;
+    query: string;
+    repositoryId: string;
+    gitRef: string;
+    /** How the ranking was produced — `lexical` when semantic was not available. */
+    mode?: string;
+    matches: VgdQueryMatch[];
+    tokensEstimate: number;
+} | {
+    ok: true;
+    repositoryId: string;
+    gitRef: string;
+    symbol: string;
+    root: {
+        id: string;
+        name: string;
+    };
+    depth: number;
+    affected: VgdImpactItem[];
+    direct: number;
+    transitive: number;
+} | {
+    ok: true;
+    repositoryId: string;
+    gitRef: string;
+    summary: {
+        nodeCount: number;
+        edgeCount: number;
+        languages: string[];
+        corpusHash: string | null;
+        root: string | null;
+    };
+} | {
+    ok: true;
+    host: {
+        poolSize: number;
+        loadedModels: string[];
+        bindingReady: boolean;
+    };
+} | {
+    ok: true;
+    hostLoaded: true;
+    modelPath: string;
+} | {
+    ok: true;
+    hostUnloaded: true;
+    cleared: number;
+} | {
+    ok: true;
+    hostGenerated: true;
+    text: string;
+    model: string;
+    constrained: boolean;
+    grammarApplied?: boolean;
+    draftAcceptedChars?: number;
+    latencyMs?: number;
+    unknownIdentifiers?: string[];
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+    /** Present when `code` is `semantic_warming` so the client can show progress. */
+    state?: string;
+    vectors?: number;
+    pending?: number;
+    nodeCount?: number;
+};
+
+interface VgdClientOptions {
+    socketPath?: string;
+    /** End-to-end response timeout in ms (default: per-op, see {@link defaultVgdTimeoutMs}). */
+    timeoutMs?: number;
+}
+/**
+ * Send one request to a running vgd and return the parsed response.
+ * Rejects if the daemon is not reachable.
+ */
+declare function vgdRequest(request: VgdRequest, options?: VgdClientOptions): Promise<VgdResponse>;
+/** True when a local vgd answers ping. */
+declare function vgdIsRunning(options?: VgdClientOptions): Promise<boolean>;
+
+type VgdPublishOutcome = {
+    status: 'not-running';
+} | {
+    status: 'failed';
+    error: string;
+}
+/** The daemon already holds this exact map — nothing was sent. */
+ | {
+    status: 'current';
+    repositoryId: string;
+    gitRef: string;
+} | {
+    status: 'published';
+    repositoryId: string;
+    gitRef: string;
+    nodeCount: number;
+    semantic?: string;
+};
+
+/**
+ * The one way an ordinary command joins the local runtime.
+ *
+ * Until now vgd only ever existed because `vg code` or the VS Code extension
+ * started it, so a developer running `vg`, `vg build` and `vg ask` all day
+ * never had a runtime at all — every invocation re-read the map and re-loaded
+ * the embedder from cold. Auto-start makes the daemon the normal case, and
+ * publishing on attach makes it hold the thing it is supposed to accelerate.
+ *
+ * Three rules keep this safe to put in front of every command:
+ *
+ * - **Never blocking.** `ensureVgdSoft` spawns and waits ~1.5s, not the 30s
+ *   `vg daemon ensure` waits. A daemon that is still coming up simply is not
+ *   used this time; the command runs its in-process path and finds a warm
+ *   runtime on the next call.
+ * - **Never fatal.** Every outcome is a value, never a throw. "No daemon" is a
+ *   supported configuration, and it must stay one — the fallbacks are the
+ *   code paths that exist today.
+ * - **Always escapable.** `--no-daemon`, `VG_NO_DAEMON=1`, and `CI` all turn
+ *   auto-start off. A one-shot CI job should not leave a background process
+ *   behind, and a user who does not want one must be able to say so once.
+ */
+type AttachStatus = 'attached' | 'disabled' | 'unavailable';
+interface AttachResult {
+    status: AttachStatus;
+    /** Why, when not attached — safe to show verbatim. */
+    reason?: string;
+    /** True when this call is what started the daemon. */
+    started?: boolean;
+    socketPath?: string;
+    repositoryId?: string;
+    gitRef?: string;
+    /** Outcome of the map publish, when one was requested. */
+    published?: VgdPublishOutcome;
+}
+interface AttachOptions {
+    socketPath?: string;
+    /** Spawn a daemon when none is listening (default true). */
+    autoStart?: boolean;
+    /** How long to wait for a just-spawned daemon before giving up (default 1500ms). */
+    readyBudgetMs?: number;
+    /** Publish this repo's map after attaching (default true). */
+    publish?: boolean;
+    /**
+     * The corpus hash of the map the caller already holds. When the daemon's
+     * slot reports the same hash the publish is skipped entirely.
+     *
+     * This matters more than it looks: `load-graph` runs the registry's slot
+     * funnel, and `onGraphPut` deliberately drops the slot's vectors — so
+     * re-publishing an unchanged map on every `vg ask` invalidated and re-seeded
+     * the semantic index once per command, for nothing.
+     */
+    corpusHash?: string;
+    /** Also wait for the slot's semantic index (default false — warming is background work). */
+    warmSemantic?: boolean;
+    gitRef?: string;
+    /** Custom `--graph` artifact path. */
+    graphPath?: string;
+    /** Explicit opt-out from the caller's parsed flags (`--no-daemon`). */
+    disabled?: boolean;
+    /** Injected (tests). */
+    isRunning?: typeof vgdIsRunning;
+    request?: typeof vgdRequest;
+    ensure?: (socketPath: string, readyBudgetMs: number) => Promise<{
+        running: boolean;
+        started: boolean;
+    }>;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Ensure a local vgd is running and knows about this repository's map.
+ * Resolves to a description of what happened; never throws.
+ */
+declare function attachVgd(root: string, options?: AttachOptions): Promise<AttachResult>;
+
+/**
+ * One way to ask the daemon for a semantic ranking, shared by every surface.
+ *
+ * `vg ask`, `vg serve` and `vg lsp` each grew their own copy of "load the
+ * embedder, embed the corpus, rank" — and `engine/refresh-scheduler.ts` records
+ * what that costs: the per-server copies diverged, and one of them blocked an
+ * editor Ask for ninety seconds. This is the single implementation of the
+ * daemon path so that cannot happen again.
+ *
+ * Long-lived callers (the MCP server, the language server) hold one of these
+ * for the process: it attaches once, remembers the slot, and per request sends
+ * only the question. Short-lived callers get the same behaviour with the attach
+ * folded into the first call.
+ *
+ * Every failure resolves to `null`, never a throw. `null` means "rank it
+ * yourself" — the in-process path each caller already has, which is also what
+ * happens when no daemon is running at all.
+ */
+interface DaemonRanking {
+    ranked: Array<{
+        id: string;
+        score: number;
+    }>;
+    /** How many vectors the slot holds — for logging, not correctness. */
+    vectors: number;
+    model?: string;
+}
+interface SemanticProgress {
+    state: string;
+    vectors: number;
+    pending?: number;
+    nodeCount?: number;
+    model?: string;
+    /** One line for a live status spinner. */
+    detail: string;
+}
+interface RankWaitOptions {
+    /** Called whenever the slot's status is sampled during a wait. */
+    onProgress?: (status: SemanticProgress) => void;
+    /** How often to poll `embed-status` while the index is warming (default 300ms). */
+    pollMs?: number;
+    /** Give up waiting and return null (default 10 minutes). */
+    timeoutMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+interface SemanticSessionOptions extends Omit<AttachOptions, 'corpusHash'> {
+    /** How long to wait before retrying after a failed attach (default 30s). */
+    retryAfterMs?: number;
+    now?: () => number;
+    /** Injected (tests). */
+    attach?: typeof attachVgd;
+    request?: typeof vgdRequest;
+}
+declare class DaemonSemanticSession {
+    private repositoryId;
+    private gitRef;
+    private socketPath;
+    /** The map the daemon was last told about, so an unchanged one is not resent. */
+    private publishedHash;
+    /** Do not re-attach before this time — a down daemon must not cost every request. */
+    private retryAfter;
+    private attaching;
+    private readonly root;
+    private readonly options;
+    private readonly retryAfterMs;
+    private readonly now;
+    private readonly attachImpl;
+    private readonly requestImpl;
+    constructor(root: string, options?: SemanticSessionOptions);
+    /** True once a slot is known — useful for a one-line status log. */
+    get attached(): boolean;
+    /**
+     * Rank `question` against the daemon's index for this repo.
+     * `corpusHash` is the caller's current map: when it differs from what the
+     * daemon holds, the map is republished before ranking, so a locally
+     * refreshed map never ranks against yesterday's vectors.
+     */
+    rank(question: string, corpusHash?: string, wait?: RankWaitOptions): Promise<DaemonRanking | null>;
+    private readProgress;
+    private requestRank;
+    /**
+     * The daemon's shared dependency context for this repo — the manifest digest
+     * and the dependency records — computed once per daemon instead of once per
+     * process. Null whenever the daemon cannot answer, so the caller falls back
+     * to computing it locally.
+     */
+    depContext(): Promise<{
+        manifestHash: string;
+        dependencies: Array<{
+            name: string;
+            ecosystem: string;
+            declared: string;
+            installed?: string;
+        }>;
+    } | null>;
+    private reset;
+    /** Attach once; concurrent callers share the one attempt. */
+    private ensureAttached;
+}
+
 /**
  * The read-only tool set for the LOCAL `vg serve` MCP. Every tool is
  * side-effect-free and `readOnlyHint: true` (auto-approvable), and independent of
@@ -824,6 +1430,12 @@ interface ToolContext {
     seen?: Set<string>;
     /** Path the served graph was loaded from (locates its tags sidecar). */
     graphPath?: string;
+    /**
+     * The local runtime's semantic index, when one is reachable. Held for the
+     * life of the server: attaching once and sending only the question per call
+     * is what removes this process's own model load and vector scan.
+     */
+    semanticSession?: DaemonSemanticSession;
 }
 interface VgTool {
     name: string;
@@ -1121,6 +1733,8 @@ interface ServeOptions {
     dedup?: boolean;
     /** Auto-refresh the map when the working tree drifts (default true). */
     refresh?: boolean;
+    /** `--no-daemon`: never auto-start or use the local runtime. */
+    daemon?: boolean;
     /**
      * Event-driven refresh: recursive fs.watch on the workspace so a save
      * rebuilds in ~400 ms instead of waiting out the freshness poll (default
@@ -1152,6 +1766,12 @@ declare class GraphSource {
     /** Timing / root overrides (production passes `root`; tests may pass more). */
     private readonly tuning;
     private cachedMtimeMs;
+    /**
+     * True while the daemon owns freshness for this workspace. Set only after
+     * the daemon confirms a subscription, cleared the instant it drops — so the
+     * failure mode is "this process watches again", never "nobody watches".
+     */
+    private daemonOwnsFreshness;
     private cached;
     /** Project root used for freshness probes and rebuilds. */
     readonly root: string;
@@ -1170,6 +1790,15 @@ declare class GraphSource {
     constructor(graphPath: string, refresh?: boolean, 
     /** Timing / root overrides (production passes `root`; tests may pass more). */
     tuning?: GraphSourceTuning);
+    /**
+     * Hand freshness to the daemon: stop probing on every call and stop watching.
+     * The daemon pushes `slot-changed` and we reload from disk then.
+     */
+    deferFreshnessToDaemon(): void;
+    /** The daemon went away — resume owning freshness locally. */
+    resumeLocalFreshness(): void;
+    /** The daemon says the map moved; drop the cache so the next get() re-reads. */
+    reloadFromDisk(): void;
     /** Current graph: auto-refreshed if the tree drifted, reloaded if the file changed. */
     get(): Promise<VgGraph>;
     /**
@@ -1411,7 +2040,7 @@ interface DriftNote {
     installed?: string;
     drift: 'current' | 'behind' | 'ahead' | 'unknown';
 }
-declare function driftFor(root: string, entry: LibEntry): DriftNote;
+declare function driftFor(root: string, entry: LibEntry, inv?: DriftInventory): DriftNote;
 interface AddOptions {
     root: string;
     name?: string;