@bragi-gmbh/codebus 1.2.0

package/dist/graph-remote.js

@@ -0,0 +1,889 @@
+/**
+ * A6 — remote mode for ask/MCP.
+ *
+ * graph.ts stays offline-pure (no supabase import); this file is the ONLY
+ * place the CLI's graph-consuming commands touch the network. It adapts the
+ * hub's query RPCs (graph_search/graph_subgraph/graph_blast_radius/
+ * graph_gaps, 0063_graph_content.sql) into the exact GraphSnapshot shape
+ * graph.ts's rankByRelevance/formatNodeCitation already consume, so those
+ * two functions are reused UNCHANGED for a remote slice.
+ *
+ * Every one of the four query RPCs takes an additive p_workspace_slug
+ * parameter (Known Defect #2's fix, 0063). Round-2 review finding 8
+ * (CONFIRMED) requires this repo pass it EXPLICITLY on every single call —
+ * ctx.workspaceSlug is always available and always passed. Leaving it
+ * omitted still fails safe (a strict `into strict` raises on a genuine
+ * cross-workspace slug collision rather than answering wrong) but fails
+ * LOUD for the ordinary, non-buggy case of a caller who belongs to two
+ * workspaces that each connected a same-slug repo — passing p_workspace_slug
+ * turns that recurring hard failure into the correct, disambiguated answer
+ * the parameter exists to support.
+ */
+import { execSync } from "node:child_process";
+import { makeCtx, workspaceId } from "./client.js";
+import { resolveConfig } from "./config.js";
+import { CodebusError } from "./errors.js";
+import { parseOwnerRepo } from "./commands/plan-gh.js";
+import { checkStaleness, loadLastGoodSnapshot, loadLocalSnapshot, } from "./graph.js";
+// ── git remote discovery (local-only, no network) ──────────────────────────
+/** Reads `git remote get-url origin` in repoRoot. Returns null (never
+ * throws) when not a git repo, no `origin` remote, or git is unavailable —
+ * the same "genuinely unknown, not an error" posture graph.ts's checkStaleness
+ * already uses for git failures. */
+export function getGitRemoteUrl(repoRoot) {
+    try {
+        const cwd = repoRoot || process.cwd();
+        const url = execSync("git remote get-url origin", { cwd, encoding: "utf-8" }).trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+function localHeadSha(repoRoot) {
+    try {
+        const cwd = repoRoot || process.cwd();
+        return execSync("git rev-parse HEAD", { cwd, encoding: "utf-8" }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+// ── credential resolution (must degrade silently) ───────────────────────────
+/** Attempts to build an authenticated Ctx from ambient config (flags are not
+ * available here — this is the lazy, best-effort path used only when local
+ * data is unavailable or an explicit --repo asks for something else). Never
+ * throws: missing token/url, or a failed auth handshake, both come back as
+ * null so callers can fall through to the next precedence tier instead of
+ * surfacing a raw credentials error. */
+export async function tryMakeCtx() {
+    try {
+        const cfg = resolveConfig({});
+        return await makeCtx(cfg);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Matches a git remote URL against repos.remote_url within ctx's OWN
+ * workspace — sidesteps Known Defect #2 client-side by never looking outside
+ * ctx.workspaceSlug in the first place (rather than relying solely on a
+ * server-side disambiguation parameter). Reuses parseOwnerRepo
+ * (commands/plan-gh.ts) for normalization on both sides rather than calling
+ * 0049's plan_repo_from_remote_url — that SQL helper carries no grant to
+ * `authenticated` (internal-only, invoked from inside other SECURITY DEFINER
+ * functions).
+ *
+ * A null/unparseable remote_url is a non-match, never an error — A4 (which
+ * populates remote_url via `codebus repo connect`) has not shipped yet, so
+ * today most repos rows simply have no remote_url at all.
+ */
+export async function matchRepoByRemote(ctx, remoteUrl) {
+    const normalized = parseOwnerRepo(remoteUrl);
+    if (!normalized)
+        return null;
+    const ws = await workspaceId(ctx);
+    const { data, error } = await ctx.supabase
+        .from("repos")
+        .select("id, slug, remote_url")
+        .eq("workspace_id", ws);
+    if (error || !data)
+        return null;
+    for (const row of data) {
+        if (!row.remote_url)
+            continue; // null remote_url is a non-match, not an error
+        if (parseOwnerRepo(row.remote_url) === normalized) {
+            return { id: row.id, slug: row.slug, remoteUrl: row.remote_url };
+        }
+    }
+    return null;
+}
+/** Resolves the repo slug a remote call should target: the explicit repo if
+ * given, else whatever this directory's git origin auto-matches to within
+ * ctx's own workspace. Throws (caller decides how to surface) when neither
+ * is available. */
+export async function resolveRemoteRepoSlug(ctx, repoRoot, explicitRepo) {
+    if (explicitRepo)
+        return explicitRepo;
+    const remoteUrl = getGitRemoteUrl(repoRoot);
+    const match = remoteUrl ? await matchRepoByRemote(ctx, remoteUrl) : null;
+    if (!match) {
+        throw new CodebusError("could not determine which connected repo to query (no --repo/repo given and this directory's git remote doesn't auto-match a connected repo) — pass repo explicitly");
+    }
+    return match.slug;
+}
+// ── query tokenization (mirrors rankByRelevance's own term selection) ─────
+/** graph_search takes ONE string, but questions are sentences — tokenize the
+ * same way rankByRelevance does (longest terms first, ≥3 chars) and fan out
+ * one graph_search call per term. Falls back to the whole trimmed query as a
+ * single term when nothing survives the length filter (a bare 1-2 char
+ * query), since graph_search rejects an empty p_q. */
+export function tokenizeForRemoteSearch(query, max = 4) {
+    const terms = query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length >= 3);
+    const unique = [...new Set(terms)].sort((a, b) => b.length - a.length).slice(0, max);
+    if (unique.length > 0)
+        return unique;
+    const trimmed = query.trim();
+    return trimmed ? [trimmed] : [];
+}
+/** Best-effort read of the graph_status view (0050 B.2.5a) for one repo id.
+ * Returns null on any failure — this is a freshness/status AMENITY, never
+ * allowed to fail the underlying search/subgraph/status call it accompanies. */
+async function readGraphStatus(ctx, repoId) {
+    try {
+        const { data, error } = await ctx.supabase
+            .from("graph_status")
+            .select("attachment_state, grade, freshness, stale, no_graph, serving_sha, head_sha")
+            .eq("project_id", repoId)
+            .maybeSingle();
+        if (error || !data)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort remote attachment-state + freshness lookup for `codebus graph
+ * status`. Degrades to null (never throws) on any failure — missing
+ * credentials, no git remote to auto-match, an unconnected repo, or an RPC
+ * error are all treated the same way: "nothing remote to report", not an
+ * error the command should fail on.
+ */
+export async function fetchRemoteStatus(repoRoot, explicitRepo, ctxOverride) {
+    try {
+        let ctx = ctxOverride ?? null;
+        let repoSlug = explicitRepo;
+        if (!repoSlug) {
+            const remoteUrl = getGitRemoteUrl(repoRoot);
+            if (!remoteUrl)
+                return null;
+            ctx = ctx ?? (await tryMakeCtx());
+            if (!ctx)
+                return null;
+            const match = await matchRepoByRemote(ctx, remoteUrl);
+            if (!match)
+                return null;
+            repoSlug = match.slug;
+        }
+        else {
+            ctx = ctx ?? (await tryMakeCtx());
+            if (!ctx)
+                return null;
+        }
+        const { data: repoId, error: ridError } = await ctx.supabase.rpc("graph_resolve_repo_id", {
+            p_caller: "codebus-graph-status",
+            p_repo_slug: repoSlug,
+            p_workspace_slug: ctx.workspaceSlug,
+        });
+        if (ridError || !repoId)
+            return null;
+        const row = await readGraphStatus(ctx, repoId);
+        if (!row)
+            return null;
+        return {
+            repoSlug,
+            repoId: repoId,
+            attachmentState: row.attachment_state,
+            grade: row.grade,
+            freshness: row.freshness,
+            stale: row.stale,
+            noGraph: row.no_graph,
+            servingSha7: row.serving_sha ? String(row.serving_sha).slice(0, 7) : null,
+            headSha7: row.head_sha ? String(row.head_sha).slice(0, 7) : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function fetchRemoteSlice(ctx, repoSlug, query, opts = {}) {
+    const terms = tokenizeForRemoteSearch(query);
+    const limit = opts.limit ?? 20;
+    const seedCap = opts.seedCap ?? 20;
+    // Resolve the repo id the SAME way the RPCs themselves do (graph_resolve_repo_id,
+    // 0063) rather than a separate client-side lookup — this is the one path that
+    // gets the exact ambiguous-slug error the RPCs raise, and is already granted
+    // to `authenticated`.
+    const { data: repoId, error: ridError } = await ctx.supabase.rpc("graph_resolve_repo_id", {
+        p_caller: "codebus-cli",
+        p_repo_slug: repoSlug,
+        p_workspace_slug: ctx.workspaceSlug,
+    });
+    if (ridError || !repoId) {
+        throw new CodebusError(`could not resolve repo '${repoSlug}': ${ridError?.message ?? "not found"}`);
+    }
+    const searchResults = terms.length > 0
+        ? await Promise.all(terms.map((term) => ctx.supabase.rpc("graph_search", {
+            p_repo_slug: repoSlug,
+            p_q: term,
+            p_limit: limit,
+            p_workspace_slug: ctx.workspaceSlug,
+        })))
+        : [];
+    for (const r of searchResults) {
+        if (r.error)
+            throw new CodebusError(`graph_search failed: ${r.error.message}`);
+    }
+    // Union by node_id, keeping the max similarity seen across terms.
+    const bestByNode = new Map();
+    for (const r of searchResults) {
+        for (const row of (r.data ?? [])) {
+            const existing = bestByNode.get(row.node_id);
+            if (!existing || row.similarity > existing.similarity)
+                bestByNode.set(row.node_id, row);
+        }
+    }
+    const searchHitRows = [...bestByNode.values()].sort((a, b) => b.similarity - a.similarity);
+    const searchHits = searchHitRows.map((r) => ({
+        id: r.node_id,
+        label: r.label,
+        source_file: r.source_file ?? "",
+        file_type: r.file_type ?? undefined,
+    }));
+    const seeds = searchHitRows.slice(0, seedCap).map((r) => r.node_id);
+    let nodes = [];
+    let links = [];
+    let hyperedges = [];
+    let truncated = false;
+    if (seeds.length > 0) {
+        const { data: subgraph, error: subErr } = await ctx.supabase.rpc("graph_subgraph", {
+            p_repo_slug: repoSlug,
+            p_seed_node_ids: seeds,
+            p_depth: opts.depth ?? 2,
+            p_max_nodes: opts.maxNodes ?? 200,
+            p_workspace_slug: ctx.workspaceSlug,
+        });
+        if (subErr)
+            throw new CodebusError(`graph_subgraph failed: ${subErr.message}`);
+        const subgraphNodes = (subgraph?.nodes ?? []);
+        const subgraphEdges = (subgraph?.edges ?? []);
+        nodes = subgraphNodes.map((n) => ({
+            id: n.node_id,
+            label: n.label,
+            source_file: n.source_file ?? "",
+            file_type: n.file_type ?? undefined,
+        }));
+        links = subgraphEdges.map((e) => ({ source: e.src, target: e.dst, relation: e.relation }));
+        hyperedges = subgraphEdges.map((e) => ({
+            id: `${e.src}->${e.dst}:${e.relation}`,
+            label: e.relation,
+            nodes: [e.src, e.dst],
+            relation: e.relation,
+            confidence: e.confidence,
+        }));
+        truncated = subgraph?.truncated === true;
+    }
+    // Optional graph_status read for the citation sha (best-effort; never fails the call).
+    const status = await readGraphStatus(ctx, repoId);
+    const remoteSha7 = status?.serving_sha ? String(status.serving_sha).slice(0, 7) : undefined;
+    const snapshot = {
+        built_at_commit: status?.serving_sha ?? "",
+        nodes,
+        hyperedges,
+        links,
+    };
+    return { snapshot, searchHits, truncated, repoId: repoId, repoSlug, remoteSha7 };
+}
+export async function graphSearchRpc(ctx, repoSlug, q, limit = 20) {
+    const { data, error } = await ctx.supabase.rpc("graph_search", {
+        p_repo_slug: repoSlug,
+        p_q: q,
+        p_limit: limit,
+        p_workspace_slug: ctx.workspaceSlug,
+    });
+    if (error)
+        throw new CodebusError(`graph_search failed: ${error.message}`);
+    return (data ?? []);
+}
+/** Truncates to ~200 rows client-side, per spec — graph_gaps itself has no
+ * server-side row cap. */
+export async function graphGapsRpc(ctx, repoSlug, limit = 200) {
+    const { data, error } = await ctx.supabase.rpc("graph_gaps", {
+        p_repo_slug: repoSlug,
+        p_workspace_slug: ctx.workspaceSlug,
+    });
+    if (error)
+        throw new CodebusError(`graph_gaps failed: ${error.message}`);
+    return (data ?? []).slice(0, limit);
+}
+/**
+ * remoteStalenessNote: reuses local checkStaleness when repoRoot is itself a
+ * checkout of the SAME repo (git origin matches repoSlug within ctx's
+ * workspace) — the precise SHA-identity comparison graph.ts already has —
+ * even when that checkout has no graphify-out/ snapshot of its own. Falls
+ * back to the hub's own freshness verdict (graph_status) otherwise. Never
+ * reports "fresh" when both sides are unknown (0050's 3-state contract:
+ * no_graph -> stale -> head_differs_within_grace -> no_head_report -> current).
+ */
+export async function remoteStalenessNote(ctx, repoId, repoSlug, repoRoot) {
+    const status = await readGraphStatus(ctx, repoId);
+    // Is repoRoot itself a checkout of this same repo? If so, compare its real
+    // HEAD to the hub's serving sha directly — more precise than trusting the
+    // hub's own (possibly stale) head-report.
+    const remoteUrl = getGitRemoteUrl(repoRoot);
+    const sameCheckout = remoteUrl ? (await matchRepoByRemote(ctx, remoteUrl))?.slug === repoSlug : false;
+    if (sameCheckout) {
+        const head = localHeadSha(repoRoot);
+        if (head && status?.serving_sha) {
+            const fakeSnapshot = { built_at_commit: status.serving_sha, nodes: [] };
+            // Reuse graph.ts's own SHA-identity + dirty-tree comparison verbatim.
+            return await checkStaleness(fakeSnapshot, repoRoot, "dirty-only");
+        }
+    }
+    // No usable local checkout signal — fall back to the hub's own verdict.
+    if (!status) {
+        return { isStale: false, isDirty: false, unknown: true, note: "(staleness unknown: no graph_status row for this repo)" };
+    }
+    if (status.no_graph) {
+        return { isStale: true, isDirty: false, note: "(remote: no graph attached to this repo yet)" };
+    }
+    if (status.freshness === "no_head_report") {
+        return {
+            isStale: false,
+            isDirty: false,
+            unknown: true,
+            note: "(staleness unknown: hub has no HEAD report for this repo)",
+        };
+    }
+    const sha7 = status.serving_sha ? String(status.serving_sha).slice(0, 7) : "unknown";
+    if (status.stale) {
+        return { isStale: true, isDirty: false, note: `(remote graph at ${sha7}; hub reports stale — ${status.freshness})` };
+    }
+    return { isStale: false, isDirty: false, note: `(remote graph at ${sha7}, hub reports ${status.freshness})` };
+}
+/**
+ * F2 fix: mirrors graph_blast_radius's own `p_relations` default verbatim
+ * (0063_graph_content.sql:1108 — `default array['imports','imports_from',
+ * 'calls','contains','references','implements']`). MUST stay in sync with
+ * that SQL default so local and remote blast radius agree on which edges
+ * count when the caller doesn't specify relations explicitly — previously
+ * localBlastRadius followed EVERY relation by default, giving local and
+ * remote different answers for the identical query.
+ */
+export const DEFAULT_BLAST_RADIUS_RELATIONS = [
+    "imports",
+    "imports_from",
+    "calls",
+    "contains",
+    "references",
+    "implements",
+];
+// ── trigram similarity (approximates pg_trgm's `similarity()`) ─────────────
+/**
+ * Character trigrams of `s`, case-folded to match pg_trgm's typical
+ * case-insensitive usage here.
+ *
+ * F3 fix: pg_trgm tokenizes per WORD, not per whole string — it splits the
+ * input into maximal runs of alphanumeric characters, pads EACH word with
+ * two leading spaces + one trailing space, and trigrams each padded word
+ * independently, so no trigram ever spans a word boundary. The previous
+ * implementation padded the entire string once (two spaces on both ends)
+ * and trigrammed straight through, retaining cross-word trigrams pg_trgm
+ * never produces (e.g. it invented an "o o" trigram for "fo o" — no such
+ * trigram exists for real pg_trgm, which only ever sees "fo" and "o" as
+ * two separate, independently-padded words). That divergence is not
+ * cosmetic: it can flip which of two candidate labels ranks as more
+ * similar to a seed. Worked example (see also graph-remote.test.ts):
+ * for seed "foo", real pg_trgm's similarity() ranks "foobar" above
+ * "fo o" (trigram overlap {"  f"," fo","foo"} vs {"  f"," fo"} — "foobar"
+ * shares the true 3-gram "foo", which "fo o" — split into "fo" and "o" —
+ * never can). The previous whole-string padding reversed this ranking by
+ * manufacturing a fake shared "o  " trigram between "foo" and "fo o".
+ */
+function trigramsOf(s) {
+    const grams = new Set();
+    const words = s.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    for (const word of words) {
+        const padded = `  ${word} `;
+        for (let i = 0; i + 3 <= padded.length; i++)
+            grams.add(padded.slice(i, i + 3));
+    }
+    return grams;
+}
+/**
+ * Approximates PostgreSQL pg_trgm's `similarity(a, b)` — Jaccard similarity
+ * over each string's set of character trigrams (|A ∩ B| / |A ∪ B|) — closely
+ * enough to rank graph_blast_radius's label-fallback seed candidates the
+ * same way the SQL function does in the common case.
+ *
+ * Documented divergence from the real pg_trgm implementation (called out
+ * rather than silently assumed away): pg_trgm's trigram extraction has its
+ * own locale-specific edge cases around non-alphanumeric runs, and the SQL
+ * callsite (`order by similarity(...) desc limit 1`, no secondary ORDER BY)
+ * makes Postgres's own tie-break plan-dependent when two labels score
+ * exactly equally — this function breaks such ties deterministically by
+ * lowest node id instead, so our result is stable but is not guaranteed to
+ * match whichever row Postgres's planner happens to return that day. This
+ * only matters when two candidate labels are EQUALLY similar to the seed,
+ * which is rare for the intended use (resolving a human-typed --seed label
+ * to the closest node).
+ */
+function trigramSimilarity(a, b) {
+    const ta = trigramsOf(a);
+    const tb = trigramsOf(b);
+    if (ta.size === 0 && tb.size === 0)
+        return 1;
+    if (ta.size === 0 || tb.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const g of ta)
+        if (tb.has(g))
+            intersection++;
+    const union = ta.size + tb.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * The local counterpart to graph_blast_radius (0063_graph_content.sql):
+ * same direction contract ('out' = what the seed depends on, following
+ * src->dst; 'in' = what depends on the seed / "what breaks if I change
+ * this", following dst->src in reverse; 'both' = the union), same seed
+ * resolution priority (exact node_id -> exact source_file -> best label
+ * match), same via_relation convention (a 'seed:*' tag on the distance-0
+ * row instead of an edge relation). Runs over an in-memory GraphSnapshot's
+ * `links` array — pure, offline, and the SAME traversal blast_radius (MCP)
+ * uses when serving a local snapshot instead of an RPC call.
+ */
+export function localBlastRadius(snapshot, seed, opts = {}) {
+    const direction = opts.direction ?? "in";
+    const depth = Math.max(0, Math.min(opts.depth ?? 3, 6));
+    // F2 fix: default to the SAME relation set graph_blast_radius defaults to
+    // (DEFAULT_BLAST_RADIUS_RELATIONS) rather than following every relation —
+    // "parameterized like the RPC" means an explicit override still wins. The
+    // SQL only substitutes its default when p_relations is OMITTED — an
+    // explicit `relations: []` means "follow no edges" and must stay empty,
+    // not silently widen back out to the default set. So this distinguishes
+    // undefined (apply the default) from an explicit, possibly-empty array
+    // (use exactly what was given) instead of collapsing both to "falsy or
+    // empty -> default".
+    const relations = opts.relations !== undefined ? opts.relations : DEFAULT_BLAST_RADIUS_RELATIONS;
+    const relationsFilter = new Set(relations);
+    const nodes = snapshot.nodes || [];
+    const nodesById = new Map();
+    for (const n of nodes)
+        nodesById.set(n.id, n);
+    let seedId = null;
+    let seedVia = "seed:exact_node_id";
+    if (nodesById.has(seed)) {
+        seedId = seed;
+    }
+    else {
+        // F3 fix: SQL step 2 (`order by gn.node_id limit 1`) breaks a
+        // source_file tie by the LOWEST node id, not by whichever node happens
+        // to appear first in the snapshot's own array order.
+        const sourceMatches = nodes.filter((n) => n.source_file === seed);
+        if (sourceMatches.length > 0) {
+            const bySourceFile = [...sourceMatches].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))[0];
+            seedId = bySourceFile.id;
+            seedVia = "seed:source_file";
+        }
+        else if (nodes.length > 0) {
+            // F3 fix: SQL step 3 is `order by similarity(gn.label, p_seed) desc
+            // limit 1` — pg_trgm's best TRIGRAM match over every node, always
+            // resolving to something as long as the repo has any nodes at all.
+            // The previous `.includes()` substring check could match nothing
+            // (returning no seed at all) where the RPC would still pick a node.
+            // trigramSimilarity below approximates pg_trgm's scoring; see its own
+            // comment for the acknowledged, documented divergences.
+            const ranked = [...nodes].sort((a, b) => {
+                const diff = trigramSimilarity(b.label, seed) - trigramSimilarity(a.label, seed);
+                if (diff !== 0)
+                    return diff;
+                // Not a real SQL guarantee (a bare `similarity() desc` with no
+                // secondary ORDER BY is plan-dependent on ties) — deterministic
+                // tie-break by lowest node id so at least OUR result is stable.
+                return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+            });
+            seedId = ranked[0].id;
+            seedVia = "seed:trigram_label";
+        }
+    }
+    if (!seedId)
+        return [];
+    const links = (Array.isArray(snapshot.links) ? snapshot.links : [])
+        .filter((l) => !!l && typeof l === "object" && "source" in l && "target" in l);
+    const distances = new Map([[seedId, 0]]);
+    const via = new Map([[seedId, seedVia]]);
+    let frontier = [seedId];
+    for (let level = 0; level < depth && frontier.length > 0; level++) {
+        const frontierSet = new Set(frontier);
+        const next = [];
+        for (const link of links) {
+            if (link.relation && !relationsFilter.has(link.relation))
+                continue;
+            const rel = link.relation ?? "link";
+            if ((direction === "out" || direction === "both") && frontierSet.has(link.source) && !distances.has(link.target)) {
+                distances.set(link.target, level + 1);
+                via.set(link.target, rel);
+                next.push(link.target);
+            }
+            if ((direction === "in" || direction === "both") && frontierSet.has(link.target) && !distances.has(link.source)) {
+                distances.set(link.source, level + 1);
+                via.set(link.source, rel);
+                next.push(link.source);
+            }
+        }
+        frontier = [...new Set(next)];
+    }
+    const rows = [];
+    for (const [nodeId, distance] of distances) {
+        const node = nodesById.get(nodeId);
+        rows.push({
+            node_id: nodeId,
+            label: node?.label ?? nodeId,
+            file_type: node?.file_type,
+            source_file: node?.source_file,
+            distance,
+            via_relation: via.get(nodeId) ?? "link",
+        });
+    }
+    return rows.sort((a, b) => a.distance - b.distance || a.node_id.localeCompare(b.node_id));
+}
+/**
+ * Same source precedence as resolveGraphSource (local wins ONLY when no
+ * explicit --repo is given, or an explicit --repo is POSITIVELY confirmed to
+ * name the SAME repo as this checkout -> otherwise remote is attempted, and
+ * a remote failure throws rather than silently falling back to local -> none
+ * — blast radius has no "last-good" tier since a stale cached slice for the
+ * WRONG seed would be actively misleading rather than merely stale), but
+ * dispatches to localBlastRadius instead of rankByRelevance/fetchRemoteSlice:
+ * this is the "shared local traversal, RPC when remote" split the MCP
+ * blast_radius tool and (in principle) any future local-blast-radius CLI
+ * surface both use.
+ */
+export async function resolveBlastRadius(seed, opts = {}) {
+    const repoRoot = opts.repoRoot || process.cwd();
+    const explicitRepo = opts.repo;
+    const local = loadLocalSnapshot(repoRoot);
+    const localOpts = { direction: opts.direction, depth: opts.depth, relations: opts.relations };
+    let ctx = opts.ctx ?? null;
+    let useRemote = !!explicitRepo;
+    // Set whenever an explicit --repo is paired with a local snapshot and the
+    // local checkout could NOT be POSITIVELY confirmed to be the SAME repo —
+    // this covers both a confirmed DIFFERENT repo and a merely unconfirmed
+    // match (no remote_url row, an unparseable origin, or credentials that
+    // were unavailable to even ask). In every one of those cases the local
+    // snapshot must not silently answer an explicit --repo query it can't be
+    // vouched for: remote must be attempted, and a remote failure must fail
+    // honestly rather than fall back to a local graph that might be wrong.
+    let mustNotFallBackToLocal = false;
+    // True only for the strict subset of the above where matchRepoByRemote
+    // positively proved local names a DIFFERENT repo — used to sharpen the
+    // thrown error message when we actually have that proof.
+    let confirmedDifferentRepo = false;
+    let confirmedLocalSlug;
+    if (explicitRepo && local) {
+        let localMatch = null;
+        try {
+            ctx = ctx ?? (await tryMakeCtx());
+            if (ctx) {
+                const remoteUrl = getGitRemoteUrl(repoRoot);
+                localMatch = remoteUrl ? await matchRepoByRemote(ctx, remoteUrl) : null;
+            }
+        }
+        catch {
+            localMatch = null;
+        }
+        if (localMatch && localMatch.slug === explicitRepo) {
+            // Positively confirmed same repo as this checkout — local-first is honest.
+            useRemote = false;
+        }
+        else {
+            // F1/round-4 fix: an unknown/null match (no repo row's remote_url
+            // could be confirmed against this checkout's origin — the common case
+            // before A4 populates remote_url — or credentials were unavailable to
+            // even try) must NOT silently keep serving local for an explicit
+            // --repo. Only a POSITIVELY confirmed match whose slug agrees with
+            // --repo may do that; every other outcome here — including a
+            // positively confirmed DIFFERENT repo — must attempt remote and, on
+            // failure, fail loudly instead of serving the unverified local graph.
+            useRemote = true;
+            mustNotFallBackToLocal = true;
+            confirmedLocalSlug = localMatch?.slug;
+            if (localMatch)
+                confirmedDifferentRepo = true;
+        }
+    }
+    if (local && !useRemote) {
+        return { rows: localBlastRadius(local, seed, localOpts), source: "local" };
+    }
+    let repoSlug = explicitRepo;
+    if (!repoSlug && !local) {
+        const remoteUrl = getGitRemoteUrl(repoRoot);
+        if (remoteUrl) {
+            try {
+                ctx = ctx ?? (await tryMakeCtx());
+                if (ctx) {
+                    const match = await matchRepoByRemote(ctx, remoteUrl);
+                    repoSlug = match?.slug;
+                }
+            }
+            catch {
+                // degrade silently
+            }
+        }
+    }
+    if (repoSlug) {
+        ctx = ctx ?? (await tryMakeCtx());
+        if (!ctx) {
+            if (mustNotFallBackToLocal) {
+                throw new CodebusError(`--repo '${repoSlug}' could not be confirmed to match this checkout's own repo` +
+                    (confirmedLocalSlug ? ` (this checkout resolves to '${confirmedLocalSlug}')` : "") +
+                    `, and no hub credentials are available to query '${repoSlug}' directly. Refusing to silently serve ` +
+                    `the local blast radius, which may belong to a different repo. Configure credentials (e.g. run ` +
+                    `'codebus login') or drop --repo to use this checkout's own local graph.`);
+            }
+            // Remote unavailable — fall through to local (if any) below.
+        }
+        else {
+            try {
+                const params = {
+                    p_repo_slug: repoSlug,
+                    p_seed: seed,
+                    p_direction: opts.direction ?? "in",
+                    p_depth: opts.depth ?? 3,
+                    p_workspace_slug: ctx.workspaceSlug,
+                };
+                // Omit p_relations entirely when opts.relations is undefined so the
+                // SQL default applies. F2 fix: an explicit `relations: []` is NOT
+                // "absent" — the SQL only substitutes its default when p_relations
+                // is omitted from the call altogether, so a caller-supplied empty
+                // array must still be forwarded (as [] — "follow no edges"), not
+                // collapsed into the same case as omission the way a truthiness/
+                // length check would.
+                if (opts.relations !== undefined)
+                    params.p_relations = opts.relations;
+                const { data, error } = await ctx.supabase.rpc("graph_blast_radius", params);
+                if (error)
+                    throw new CodebusError(`graph_blast_radius failed: ${error.message}`);
+                const rows = (data ?? []);
+                const truncated = rows.some((r) => r.truncated === true);
+                return { rows, source: "remote", repoSlug, truncated };
+            }
+            catch (err) {
+                // Local could not be vouched for as the repo --repo asked for
+                // (mustNotFallBackToLocal — either proven different, or simply
+                // unconfirmed). Falling back to it here would silently serve
+                // (possibly) the wrong repo's blast radius as if it answered the
+                // question asked. Fail honestly instead of degrading to local in
+                // this case. (This block is unreachable when local was positively
+                // confirmed to be the SAME repo, since that case never sets
+                // useRemote and returns local well before reaching here.)
+                if (mustNotFallBackToLocal) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new CodebusError(confirmedDifferentRepo
+                        ? `--repo '${repoSlug}' was confirmed different from this checkout's own repo ` +
+                            `('${confirmedLocalSlug}'), and the remote fetch for '${repoSlug}' failed (${detail}). ` +
+                            `Refusing to fall back to the local graph of a different repo.`
+                        : `--repo '${repoSlug}' could not be confirmed to match this checkout's own repo, and the remote ` +
+                            `fetch for '${repoSlug}' failed (${detail}). Refusing to silently fall back to the local graph, ` +
+                            `which may belong to a different repo.`);
+                }
+                // Remote unavailable for any other reason (no local snapshot to
+                // protect, so nothing to silently mis-serve) — fall through to
+                // local (if any) below.
+            }
+        }
+    }
+    if (local)
+        return { rows: localBlastRadius(local, seed, localOpts), source: "local" };
+    return { rows: [], source: "none" };
+}
+/**
+ * Precedence: local wins when no explicit `repo` is given (implicit path,
+ * unchanged) -> remote -> last-good -> none. When an explicit `repo` IS
+ * given alongside a local snapshot, local wins ONLY if `repo` is POSITIVELY
+ * confirmed (via matchRepoByRemote) to name this checkout's own repo;
+ * otherwise remote is attempted, and if the remote fetch can't even be
+ * attempted (no credentials) or fails outright, this throws rather than
+ * silently substituting the local snapshot for a repo it was never
+ * confirmed to belong to. Credentials-missing still degrades silently on the
+ * IMPLICIT (no --repo) path (never a raw error there) — ask_graph is the
+ * only zero-credential MCP tool today and must stay that way when local data
+ * is available. Never calls saveLastGoodSnapshot for remote data: that cache
+ * is machine-wide, not per-repo, and a partial remote slice would poison it
+ * for every other repo's local-only usage.
+ */
+export async function resolveGraphSource(query, opts = {}) {
+    const repoRoot = opts.repoRoot || process.cwd();
+    const explicitRepo = opts.repo;
+    const local = loadLocalSnapshot(repoRoot);
+    let ctx = opts.ctx ?? null;
+    let remoteRepoSlug = explicitRepo;
+    let attemptRemote = false;
+    // Set whenever an explicit --repo is paired with a local snapshot and the
+    // local checkout could NOT be POSITIVELY confirmed to be the SAME repo —
+    // covers both a confirmed DIFFERENT repo and a merely unconfirmed match
+    // (no remote_url row, an unparseable origin, or credentials that were
+    // unavailable to even ask). In every one of those cases the local
+    // snapshot must not silently answer an explicit --repo query it can't be
+    // vouched for: remote must be attempted, and a remote failure must fail
+    // honestly rather than fall back to a local graph that might be wrong.
+    let mustNotFallBackToLocal = false;
+    // True only for the strict subset of the above where matchRepoByRemote
+    // positively proved local names a DIFFERENT repo — used to sharpen the
+    // thrown error message when we actually have that proof.
+    let confirmedDifferentRepo = false;
+    let confirmedLocalSlug;
+    if (explicitRepo) {
+        attemptRemote = true;
+        if (local) {
+            // Local wins ONLY when the explicit repo is positively confirmed to
+            // name the SAME repo as this checkout's own — every other outcome
+            // (confirmed different, or simply unconfirmed) must attempt remote.
+            let localMatch = null;
+            try {
+                ctx = ctx ?? (await tryMakeCtx());
+                if (ctx) {
+                    const remoteUrl = getGitRemoteUrl(repoRoot);
+                    localMatch = remoteUrl ? await matchRepoByRemote(ctx, remoteUrl) : null;
+                }
+            }
+            catch {
+                localMatch = null;
+            }
+            if (localMatch && localMatch.slug === explicitRepo) {
+                // Positively confirmed same repo as this checkout — local-first is honest.
+                attemptRemote = false;
+            }
+            else {
+                // F1/round-4 fix: an unknown/null match (no repo row's remote_url
+                // could be confirmed against this checkout's origin — the common
+                // case before A4 populates remote_url — or credentials were
+                // unavailable to even try) must NOT silently keep serving local for
+                // an explicit --repo. Only a POSITIVELY confirmed match whose slug
+                // agrees with --repo may do that; every other outcome here —
+                // including a positively confirmed DIFFERENT repo — must attempt
+                // remote and, on failure, fail loudly instead of serving the
+                // unverified local snapshot.
+                attemptRemote = true;
+                mustNotFallBackToLocal = true;
+                confirmedLocalSlug = localMatch?.slug;
+                if (localMatch)
+                    confirmedDifferentRepo = true;
+            }
+        }
+    }
+    else if (!local) {
+        // No explicit repo and nothing local: only worth reaching for credentials
+        // at all if this directory even LOOKS like a connected repo (has an
+        // origin remote) — avoids an auth round-trip for every plain "no graph
+        // here" case, which is by far the common one before A4 populates
+        // remote_url for anyone.
+        const remoteUrl = getGitRemoteUrl(repoRoot);
+        if (remoteUrl) {
+            try {
+                ctx = ctx ?? (await tryMakeCtx());
+                if (ctx) {
+                    const match = await matchRepoByRemote(ctx, remoteUrl);
+                    if (match) {
+                        remoteRepoSlug = match.slug;
+                        attemptRemote = true;
+                    }
+                }
+            }
+            catch {
+                // degrade silently
+            }
+        }
+    }
+    if (attemptRemote && remoteRepoSlug) {
+        ctx = ctx ?? (await tryMakeCtx());
+        if (!ctx) {
+            if (mustNotFallBackToLocal) {
+                throw new CodebusError(`--repo '${remoteRepoSlug}' could not be confirmed to match this checkout's own repo` +
+                    (confirmedLocalSlug ? ` (this checkout resolves to '${confirmedLocalSlug}')` : "") +
+                    `, and no hub credentials are available to query '${remoteRepoSlug}' directly. Refusing to silently ` +
+                    `serve the local graph, which may belong to a different repo. Configure credentials (e.g. run ` +
+                    `'codebus login') or drop --repo to use this checkout's own local graph.`);
+            }
+            if (explicitRepo) {
+                // No local snapshot to protect (mustNotFallBackToLocal is false here),
+                // but --repo was still requested explicitly and there are no
+                // credentials to even attempt the remote query. Falling through to
+                // the machine-wide last-good cache below would risk silently
+                // answering from a totally different repo's stale snapshot — that
+                // cache carries no repo identity to verify against. Fail honestly
+                // instead (round-5 review finding).
+                throw new CodebusError(`--repo '${remoteRepoSlug}' was requested explicitly, but no hub credentials are available to query ` +
+                    `it directly, and this checkout has no local graph to fall back to. Refusing to silently answer from ` +
+                    `the machine-wide last-good cache, which is not scoped to any repo and may belong to a different ` +
+                    `one. Configure credentials (e.g. run 'codebus login').`);
+            }
+            // Remote unavailable — degrade silently and fall through below (the
+            // implicit no-repo path only).
+        }
+        else {
+            try {
+                const slice = await fetchRemoteSlice(ctx, remoteRepoSlug, query);
+                const staleness = await remoteStalenessNote(ctx, slice.repoId, remoteRepoSlug, repoRoot).catch(() => undefined);
+                return {
+                    snapshot: slice.snapshot,
+                    source: "remote",
+                    repoSlug: remoteRepoSlug,
+                    repoId: slice.repoId,
+                    remoteSha7: slice.remoteSha7,
+                    truncated: slice.truncated,
+                    searchHits: slice.searchHits,
+                    staleness,
+                };
+            }
+            catch (err) {
+                // Local could not be vouched for as the repo --repo asked for
+                // (mustNotFallBackToLocal — either proven different, or simply
+                // unconfirmed). Falling back to it here would silently answer with
+                // a possibly-different repo's graph as if it answered the question
+                // asked. Fail honestly instead of degrading to local in this case.
+                // (This block is unreachable when local was positively confirmed to
+                // be the SAME repo, since that case never sets attemptRemote and
+                // returns local well before reaching here.)
+                if (mustNotFallBackToLocal) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new CodebusError(confirmedDifferentRepo
+                        ? `--repo '${remoteRepoSlug}' was confirmed different from this checkout's own repo ` +
+                            `('${confirmedLocalSlug}'), and the remote fetch for '${remoteRepoSlug}' failed (${detail}). ` +
+                            `Refusing to fall back to the local graph of a different repo.`
+                        : `--repo '${remoteRepoSlug}' could not be confirmed to match this checkout's own repo, and the ` +
+                            `remote fetch for '${remoteRepoSlug}' failed (${detail}). Refusing to silently fall back to the ` +
+                            `local graph, which may belong to a different repo.`);
+                }
+                if (explicitRepo) {
+                    // No local snapshot to protect, but --repo was still requested
+                    // explicitly and the remote fetch failed. Falling through to the
+                    // machine-wide last-good cache below would risk silently
+                    // answering from a totally different repo's stale snapshot — that
+                    // cache carries no repo identity to verify against (round-5
+                    // review finding). Fail honestly instead.
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new CodebusError(`--repo '${remoteRepoSlug}' was requested explicitly, and the remote fetch failed (${detail}). This ` +
+                        `checkout has no local graph to fall back to. Refusing to silently answer from the machine-wide ` +
+                        `last-good cache, which is not scoped to any repo and may belong to a different one.`);
+                }
+                // Remote unavailable for any other reason (implicit no-repo path,
+                // nothing to silently mis-serve) — degrade silently and fall
+                // through below.
+            }
+        }
+    }
+    if (local)
+        return { snapshot: local, source: "local" };
+    // The last-good cache (~/.codebus/last-good-graph.json) is machine-wide
+    // and carries no repo identity of its own (GraphSnapshot has no repo/slug
+    // field) — it is only a safe fallback for the IMPLICIT (no --repo) path.
+    // Every explicit --repo failure above already throws before reaching
+    // here; this guard is a defense-in-depth backstop against ever silently
+    // answering an explicit --repo request from a possibly-different repo's
+    // cached snapshot (round-5 review finding).
+    if (!explicitRepo) {
+        const lastGood = loadLastGoodSnapshot();
+        if (lastGood)
+            return { snapshot: lastGood, source: "last-good" };
+    }
+    return { snapshot: null, source: "none" };
+}
+//# sourceMappingURL=graph-remote.js.map