knosky 0.6.3 → 0.7.0

package/core/cross-repo.mjs

@@ -1,111 +1,111 @@
-// Cross-repo graph utilities (SAT-448): edge detection, boundary extraction, and rendering metadata.
-// Pure logic — no filesystem access, no new deps. Works on the in-memory city/byId structures
-// produced by retrieve.load() or any equivalent.
-//
-// A node's *repo* identity is determined by provenance.repo when present, falling back to
-// provenance.store (e.g. "fs", "gh:owner/repo") so existing city data stays fully compatible —
-// single-repo graphs have no cross-repo edges because every node shares the same store value.
-
-// ---------------------------------------------------------------------------
-// repoOf
-// ---------------------------------------------------------------------------
-
-/**
- * Return the repository identity of a node.
- * Preference order:
- *   1. node.provenance.repo  — explicit multi-repo label (new field, optional)
- *   2. node.provenance.store — always present; used as the identity when repo is absent
- *      (works correctly for single-repo graphs: all nodes share one store → no cross edges)
- *
- * Returns null if provenance is absent or malformed.
- *
- * @param {object} node
- * @returns {string|null}
- */
-export function repoOf(node) {
-  if (!node || typeof node !== 'object') return null;
-  const prov = node.provenance;
-  if (!prov || typeof prov !== 'object') return null;
-  if (typeof prov.repo === 'string' && prov.repo.length > 0) return prov.repo;
-  if (typeof prov.store === 'string' && prov.store.length > 0) return prov.store;
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// isCrossRepoEdge
-// ---------------------------------------------------------------------------
-
-/**
- * Return true when the edge (fromId → toId) crosses a repo boundary.
- * An edge is cross-repo when repoOf(fromNode) !== repoOf(toNode) AND both are non-null.
- * Edges where either endpoint is missing or has no repo identity are treated as same-repo
- * (conservative: no false positives).
- *
- * @param {Map<string, object>} byId   — node map from retrieve.load()
- * @param {string}              fromId
- * @param {string}              toId
- * @returns {boolean}
- */
-export function isCrossRepoEdge(byId, fromId, toId) {
-  const src = byId.get(fromId);
-  const dst = byId.get(toId);
-  if (!src || !dst) return false;
-  const r1 = repoOf(src);
-  const r2 = repoOf(dst);
-  if (r1 === null || r2 === null) return false;
-  return r1 !== r2;
-}
-
-// ---------------------------------------------------------------------------
-// getCrossRepoEdges
-// ---------------------------------------------------------------------------
-
-/**
- * Walk every node's `links` array and return all edges that cross a repo boundary.
- *
- * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
- * @returns {Array<{ from: string, to: string, fromRepo: string, toRepo: string }>}
- */
-export function getCrossRepoEdges(ctx) {
-  const edges = [];
-  for (const node of (ctx.city.nodes || [])) {
-    if (!Array.isArray(node.links)) continue;
-    const fromRepo = repoOf(node);
-    if (fromRepo === null) continue;
-    for (const toId of node.links) {
-      const dst = ctx.byId.get(toId);
-      if (!dst) continue;
-      const toRepo = repoOf(dst);
-      if (toRepo === null) continue;
-      if (fromRepo !== toRepo) {
-        edges.push({ from: node.id, to: toId, fromRepo, toRepo });
-      }
-    }
-  }
-  return edges;
-}
-
-// ---------------------------------------------------------------------------
-// getRepoBoundaries
-// ---------------------------------------------------------------------------
-
-/**
- * Return a summary of every distinct repo present in the graph and its node membership.
- *
- * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
- * @returns {Array<{ repo: string, nodeIds: string[], count: number }>}
- *            Sorted by count desc, then repo asc.
- */
-export function getRepoBoundaries(ctx) {
-  /** @type {Map<string, string[]>} */
-  const byRepo = new Map();
-  for (const node of (ctx.city.nodes || [])) {
-    const r = repoOf(node);
-    if (r === null) continue;
-    if (!byRepo.has(r)) byRepo.set(r, []);
-    byRepo.get(r).push(node.id);
-  }
-  return [...byRepo.entries()]
-    .map(([repo, nodeIds]) => ({ repo, nodeIds, count: nodeIds.length }))
-    .sort((a, b) => b.count - a.count || String(a.repo).localeCompare(String(b.repo)));
-}
+// Cross-repo graph utilities (SAT-448): edge detection, boundary extraction, and rendering metadata.
+// Pure logic — no filesystem access, no new deps. Works on the in-memory city/byId structures
+// produced by retrieve.load() or any equivalent.
+//
+// A node's *repo* identity is determined by provenance.repo when present, falling back to
+// provenance.store (e.g. "fs", "gh:owner/repo") so existing city data stays fully compatible —
+// single-repo graphs have no cross-repo edges because every node shares the same store value.
+
+// ---------------------------------------------------------------------------
+// repoOf
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the repository identity of a node.
+ * Preference order:
+ *   1. node.provenance.repo  — explicit multi-repo label (new field, optional)
+ *   2. node.provenance.store — always present; used as the identity when repo is absent
+ *      (works correctly for single-repo graphs: all nodes share one store → no cross edges)
+ *
+ * Returns null if provenance is absent or malformed.
+ *
+ * @param {object} node
+ * @returns {string|null}
+ */
+export function repoOf(node) {
+  if (!node || typeof node !== 'object') return null;
+  const prov = node.provenance;
+  if (!prov || typeof prov !== 'object') return null;
+  if (typeof prov.repo === 'string' && prov.repo.length > 0) return prov.repo;
+  if (typeof prov.store === 'string' && prov.store.length > 0) return prov.store;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// isCrossRepoEdge
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when the edge (fromId → toId) crosses a repo boundary.
+ * An edge is cross-repo when repoOf(fromNode) !== repoOf(toNode) AND both are non-null.
+ * Edges where either endpoint is missing or has no repo identity are treated as same-repo
+ * (conservative: no false positives).
+ *
+ * @param {Map<string, object>} byId   — node map from retrieve.load()
+ * @param {string}              fromId
+ * @param {string}              toId
+ * @returns {boolean}
+ */
+export function isCrossRepoEdge(byId, fromId, toId) {
+  const src = byId.get(fromId);
+  const dst = byId.get(toId);
+  if (!src || !dst) return false;
+  const r1 = repoOf(src);
+  const r2 = repoOf(dst);
+  if (r1 === null || r2 === null) return false;
+  return r1 !== r2;
+}
+
+// ---------------------------------------------------------------------------
+// getCrossRepoEdges
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk every node's `links` array and return all edges that cross a repo boundary.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ from: string, to: string, fromRepo: string, toRepo: string }>}
+ */
+export function getCrossRepoEdges(ctx) {
+  const edges = [];
+  for (const node of (ctx.city.nodes || [])) {
+    if (!Array.isArray(node.links)) continue;
+    const fromRepo = repoOf(node);
+    if (fromRepo === null) continue;
+    for (const toId of node.links) {
+      const dst = ctx.byId.get(toId);
+      if (!dst) continue;
+      const toRepo = repoOf(dst);
+      if (toRepo === null) continue;
+      if (fromRepo !== toRepo) {
+        edges.push({ from: node.id, to: toId, fromRepo, toRepo });
+      }
+    }
+  }
+  return edges;
+}
+
+// ---------------------------------------------------------------------------
+// getRepoBoundaries
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a summary of every distinct repo present in the graph and its node membership.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ repo: string, nodeIds: string[], count: number }>}
+ *            Sorted by count desc, then repo asc.
+ */
+export function getRepoBoundaries(ctx) {
+  /** @type {Map<string, string[]>} */
+  const byRepo = new Map();
+  for (const node of (ctx.city.nodes || [])) {
+    const r = repoOf(node);
+    if (r === null) continue;
+    if (!byRepo.has(r)) byRepo.set(r, []);
+    byRepo.get(r).push(node.id);
+  }
+  return [...byRepo.entries()]
+    .map(([repo, nodeIds]) => ({ repo, nodeIds, count: nodeIds.length }))
+    .sort((a, b) => b.count - a.count || String(a.repo).localeCompare(String(b.repo)));
+}

package/core/decision-codes.mjs

@@ -0,0 +1,92 @@
+// KnoSky DEC-108 closed decision-code set (loaded from ssot/decision-codes.json).
+// ESM, Node stdlib only. Fail-closed closed set — no open-string codes on the wire.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SSOT_PATH = join(HERE, '..', 'ssot', 'decision-codes.json');
+
+let _doc;
+function doc() {
+  if (!_doc) {
+    _doc = JSON.parse(readFileSync(SSOT_PATH, 'utf8'));
+  }
+  return _doc;
+}
+
+/** @returns {readonly string[]} */
+export function closedSet() {
+  return Object.freeze([...(doc().closed_set || [])]);
+}
+
+/** @param {string} code */
+export function isKnownCode(code) {
+  return closedSet().includes(code);
+}
+
+/**
+ * @param {string} code
+ * @returns {object|null}
+ */
+export function codeMeta(code) {
+  const hit = (doc().codes || []).find((c) => c.code === code);
+  return hit || null;
+}
+
+/**
+ * Build a wire-safe decision envelope.
+ * DENY* never attach restricted structures.
+ *
+ * @param {object} opts
+ * @param {string} opts.code
+ * @param {'A'|'B'} [opts.mode]
+ * @param {string} [opts.receipt_id]
+ * @param {string} [opts.next_action]
+ * @param {string} [opts.request_id]
+ * @param {object} [opts.payload] only attached when code is ALLOW or ADVISORY_UNAUTH
+ */
+export function envelope({
+  code,
+  mode,
+  receipt_id,
+  next_action,
+  request_id,
+  payload,
+} = {}) {
+  if (!isKnownCode(code)) {
+    throw new Error(`unknown decision code: ${code}`);
+  }
+  const meta = codeMeta(code) || {};
+  const resolvedMode = mode || (Array.isArray(meta.mode) ? meta.mode[0] : meta.mode) || 'B';
+  const out = {
+    decision_code: code,
+    mode: resolvedMode,
+    metadata_disclosed: !!meta.metadata_disclosed,
+    authorizing: !!meta.authorizing,
+  };
+  if (request_id) out.request_id = request_id;
+  if (receipt_id) out.receipt_id = receipt_id;
+  if (next_action) out.next_action = next_action;
+  else if (meta.client_hint) out.next_action = meta.client_hint;
+
+  const allowPayload = code === 'ALLOW' || code === 'ADVISORY_UNAUTH';
+  if (allowPayload && payload && typeof payload === 'object') {
+    out.payload = payload;
+  }
+  return out;
+}
+
+export const CODES = Object.freeze({
+  ALLOW: 'ALLOW',
+  DENY: 'DENY',
+  DENY_IDENTITY: 'DENY_IDENTITY',
+  DENY_POLICY: 'DENY_POLICY',
+  DENY_AUDIT: 'DENY_AUDIT',
+  DENY_FRESHNESS: 'DENY_FRESHNESS',
+  DENY_EVIDENCE: 'DENY_EVIDENCE',
+  ERROR_INVALID_INPUT: 'ERROR_INVALID_INPUT',
+  ERROR_INDEX: 'ERROR_INDEX',
+  ADVISORY_UNAUTH: 'ADVISORY_UNAUTH',
+});

package/core/destination.mjs

@@ -1,161 +1,161 @@
-// KnoSky destination parser (KSV2-R2) — extended prefix set for kc_route.
-// Pure Node stdlib + internal imports only. ESM. No new deps.
-import { search } from './retrieve.mjs';
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve a single node by id "fs:<rest>" OR by provenance.ref === <rest>.
- * Also accepts a fully-qualified id (already has "fs:" prefix).
- * @param {object} ctx
- * @param {string} idOrRef
- * @returns {object|null}
- */
-function resolveOne(ctx, idOrRef) {
-  // Try constructing the canonical node id
-  const byConstructed = ctx.byId.get('fs:' + idOrRef);
-  if (byConstructed) return byConstructed;
-  // Try the raw string as-is (already fully qualified, e.g. "fs:src/a.js")
-  const byRaw = ctx.byId.get(idOrRef);
-  if (byRaw) return byRaw;
-  // Fallback: linear scan for provenance.ref match
-  return ctx.city.nodes.find(n => n.provenance && n.provenance.ref === idOrRef) || null;
-}
-
-// ---------------------------------------------------------------------------
-// parseDestination — main export
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the destination string to an initial set of matching nodes.
- * Returns { matched: Node[], matchStrength: 'direct'|'folder'|'district'|'edges'|'chain'|'keyword' }
- *
- * Supported prefixes (ALL metadata-only, no filesystem access):
- *   file:<idOrRef>   — node by id "fs:<rest>" OR by provenance.ref === rest; 'direct'
- *   folder:<prefix>  — nodes whose provenance.ref starts with prefix; 'folder'
- *   district:<name>  — nodes whose category equals name (case-insensitive) or
- *                      whose category label matches; 'district'
- *   importsOf:<idOrRef> — out-edge targets of that node (node.links through ctx.byId); 'edges'
- *   depChainTo:<idOrRef> — nodes that TRANSITIVELY import/reach the target via
- *                          reverse-edge BFS; bounded (max depth 6, max 500 visited,
- *                          visited-set prevents cycles); 'chain'
- *   <anything else>  — keyword fallback via search(); 'keyword'
- *
- * @param {object} ctx         — retrieve context {city:{nodes,categories}, byId:Map}
- * @param {string} destination
- * @param {number} limit       — passed through to keyword search
- * @returns {{ matched: object[], matchStrength: string }}
- */
-export function parseDestination(ctx, destination, limit) {
-  const dest = String(destination || '').trim();
-
-  // ------------------------------------------------------------------
-  // file:<idOrRef>
-  // ------------------------------------------------------------------
-  if (dest.startsWith('file:')) {
-    const rest = dest.slice('file:'.length);
-    const node = resolveOne(ctx, rest);
-    return { matched: node ? [node] : [], matchStrength: 'direct' };
-  }
-
-  // ------------------------------------------------------------------
-  // folder:<prefix>
-  // ------------------------------------------------------------------
-  if (dest.startsWith('folder:')) {
-    const rest = dest.slice('folder:'.length);
-    // Normalise: ensure trailing slash for prefix match (unless rest already ends with /)
-    const prefix = rest.endsWith('/') ? rest : rest + '/';
-    const matched = ctx.city.nodes.filter(n => {
-      const ref = n.provenance && n.provenance.ref;
-      return typeof ref === 'string' && (ref.startsWith(prefix) || ref === rest);
-    });
-    return { matched, matchStrength: 'folder' };
-  }
-
-  // ------------------------------------------------------------------
-  // district:<name>
-  // ------------------------------------------------------------------
-  if (dest.startsWith('district:')) {
-    const name = dest.slice('district:'.length).toLowerCase();
-    // Build label->id map from city.categories
-    const labelToId = new Map();
-    for (const cat of (ctx.city.categories || [])) {
-      if (cat.label) labelToId.set(String(cat.label).toLowerCase(), String(cat.id).toLowerCase());
-    }
-    const resolvedCatId = labelToId.get(name) || null;
-    const matched = ctx.city.nodes.filter(n => {
-      const cat = String(n.category || '').toLowerCase();
-      return cat === name || (resolvedCatId !== null && cat === resolvedCatId);
-    });
-    return { matched, matchStrength: 'district' };
-  }
-
-  // ------------------------------------------------------------------
-  // importsOf:<idOrRef>
-  // ------------------------------------------------------------------
-  if (dest.startsWith('importsOf:')) {
-    const rest = dest.slice('importsOf:'.length);
-    const node = resolveOne(ctx, rest);
-    if (!node) return { matched: [], matchStrength: 'edges' };
-    const matched = (node.links || []).map(tid => ctx.byId.get(tid)).filter(Boolean);
-    return { matched, matchStrength: 'edges' };
-  }
-
-  // ------------------------------------------------------------------
-  // depChainTo:<idOrRef>
-  // Bounded reverse-edge BFS: finds all nodes that transitively import the target.
-  // Safety invariants:
-  //   - visited Set prevents revisiting nodes (handles cycles A→B→A)
-  //   - max depth 6 per BFS level
-  //   - hard cap of 500 nodes visited (includes the target seed)
-  // ------------------------------------------------------------------
-  if (dest.startsWith('depChainTo:')) {
-    const rest = dest.slice('depChainTo:'.length);
-    const target = resolveOne(ctx, rest);
-    if (!target) return { matched: [], matchStrength: 'chain' };
-    const targetId = target.id;
-
-    // Build reverse-edge index: nodeId -> Set<callerId>
-    // (which nodes have this id in their links)
-    const importedBy = new Map();
-    for (const n of ctx.city.nodes) {
-      for (const link of (n.links || [])) {
-        if (!importedBy.has(link)) importedBy.set(link, new Set());
-        importedBy.get(link).add(n.id);
-      }
-    }
-
-    // BFS — each queue entry carries { id, depth }
-    const visited = new Set();
-    visited.add(targetId);
-    const queue = [{ id: targetId, depth: 0 }];
-
-    while (queue.length > 0 && visited.size < 500) {
-      const { id, depth } = queue.shift();
-      if (depth >= 6) continue;
-      const parents = importedBy.get(id);
-      if (!parents) continue;
-      for (const pid of parents) {
-        if (!visited.has(pid)) {
-          visited.add(pid);
-          queue.push({ id: pid, depth: depth + 1 });
-          if (visited.size >= 500) break;
-        }
-      }
-    }
-
-    // Return callers of target, not the target itself
-    visited.delete(targetId);
-    const matched = [...visited].map(id => ctx.byId.get(id)).filter(Boolean);
-    return { matched, matchStrength: 'chain' };
-  }
-
-  // ------------------------------------------------------------------
-  // no recognized prefix — keyword fallback
-  // ------------------------------------------------------------------
-  const hits = search(ctx, dest, { limit });
-  const matched = hits.map(h => ctx.byId.get(h.id)).filter(Boolean);
-  return { matched, matchStrength: 'keyword' };
-}
+// KnoSky destination parser (KSV2-R2) — extended prefix set for kc_route.
+// Pure Node stdlib + internal imports only. ESM. No new deps.
+import { search } from './retrieve.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a single node by id "fs:<rest>" OR by provenance.ref === <rest>.
+ * Also accepts a fully-qualified id (already has "fs:" prefix).
+ * @param {object} ctx
+ * @param {string} idOrRef
+ * @returns {object|null}
+ */
+function resolveOne(ctx, idOrRef) {
+  // Try constructing the canonical node id
+  const byConstructed = ctx.byId.get('fs:' + idOrRef);
+  if (byConstructed) return byConstructed;
+  // Try the raw string as-is (already fully qualified, e.g. "fs:src/a.js")
+  const byRaw = ctx.byId.get(idOrRef);
+  if (byRaw) return byRaw;
+  // Fallback: linear scan for provenance.ref match
+  return ctx.city.nodes.find(n => n.provenance && n.provenance.ref === idOrRef) || null;
+}
+
+// ---------------------------------------------------------------------------
+// parseDestination — main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the destination string to an initial set of matching nodes.
+ * Returns { matched: Node[], matchStrength: 'direct'|'folder'|'district'|'edges'|'chain'|'keyword' }
+ *
+ * Supported prefixes (ALL metadata-only, no filesystem access):
+ *   file:<idOrRef>   — node by id "fs:<rest>" OR by provenance.ref === rest; 'direct'
+ *   folder:<prefix>  — nodes whose provenance.ref starts with prefix; 'folder'
+ *   district:<name>  — nodes whose category equals name (case-insensitive) or
+ *                      whose category label matches; 'district'
+ *   importsOf:<idOrRef> — out-edge targets of that node (node.links through ctx.byId); 'edges'
+ *   depChainTo:<idOrRef> — nodes that TRANSITIVELY import/reach the target via
+ *                          reverse-edge BFS; bounded (max depth 6, max 500 visited,
+ *                          visited-set prevents cycles); 'chain'
+ *   <anything else>  — keyword fallback via search(); 'keyword'
+ *
+ * @param {object} ctx         — retrieve context {city:{nodes,categories}, byId:Map}
+ * @param {string} destination
+ * @param {number} limit       — passed through to keyword search
+ * @returns {{ matched: object[], matchStrength: string }}
+ */
+export function parseDestination(ctx, destination, limit) {
+  const dest = String(destination || '').trim();
+
+  // ------------------------------------------------------------------
+  // file:<idOrRef>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('file:')) {
+    const rest = dest.slice('file:'.length);
+    const node = resolveOne(ctx, rest);
+    return { matched: node ? [node] : [], matchStrength: 'direct' };
+  }
+
+  // ------------------------------------------------------------------
+  // folder:<prefix>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('folder:')) {
+    const rest = dest.slice('folder:'.length);
+    // Normalise: ensure trailing slash for prefix match (unless rest already ends with /)
+    const prefix = rest.endsWith('/') ? rest : rest + '/';
+    const matched = ctx.city.nodes.filter(n => {
+      const ref = n.provenance && n.provenance.ref;
+      return typeof ref === 'string' && (ref.startsWith(prefix) || ref === rest);
+    });
+    return { matched, matchStrength: 'folder' };
+  }
+
+  // ------------------------------------------------------------------
+  // district:<name>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('district:')) {
+    const name = dest.slice('district:'.length).toLowerCase();
+    // Build label->id map from city.categories
+    const labelToId = new Map();
+    for (const cat of (ctx.city.categories || [])) {
+      if (cat.label) labelToId.set(String(cat.label).toLowerCase(), String(cat.id).toLowerCase());
+    }
+    const resolvedCatId = labelToId.get(name) || null;
+    const matched = ctx.city.nodes.filter(n => {
+      const cat = String(n.category || '').toLowerCase();
+      return cat === name || (resolvedCatId !== null && cat === resolvedCatId);
+    });
+    return { matched, matchStrength: 'district' };
+  }
+
+  // ------------------------------------------------------------------
+  // importsOf:<idOrRef>
+  // ------------------------------------------------------------------
+  if (dest.startsWith('importsOf:')) {
+    const rest = dest.slice('importsOf:'.length);
+    const node = resolveOne(ctx, rest);
+    if (!node) return { matched: [], matchStrength: 'edges' };
+    const matched = (node.links || []).map(tid => ctx.byId.get(tid)).filter(Boolean);
+    return { matched, matchStrength: 'edges' };
+  }
+
+  // ------------------------------------------------------------------
+  // depChainTo:<idOrRef>
+  // Bounded reverse-edge BFS: finds all nodes that transitively import the target.
+  // Safety invariants:
+  //   - visited Set prevents revisiting nodes (handles cycles A→B→A)
+  //   - max depth 6 per BFS level
+  //   - hard cap of 500 nodes visited (includes the target seed)
+  // ------------------------------------------------------------------
+  if (dest.startsWith('depChainTo:')) {
+    const rest = dest.slice('depChainTo:'.length);
+    const target = resolveOne(ctx, rest);
+    if (!target) return { matched: [], matchStrength: 'chain' };
+    const targetId = target.id;
+
+    // Build reverse-edge index: nodeId -> Set<callerId>
+    // (which nodes have this id in their links)
+    const importedBy = new Map();
+    for (const n of ctx.city.nodes) {
+      for (const link of (n.links || [])) {
+        if (!importedBy.has(link)) importedBy.set(link, new Set());
+        importedBy.get(link).add(n.id);
+      }
+    }
+
+    // BFS — each queue entry carries { id, depth }
+    const visited = new Set();
+    visited.add(targetId);
+    const queue = [{ id: targetId, depth: 0 }];
+
+    while (queue.length > 0 && visited.size < 500) {
+      const { id, depth } = queue.shift();
+      if (depth >= 6) continue;
+      const parents = importedBy.get(id);
+      if (!parents) continue;
+      for (const pid of parents) {
+        if (!visited.has(pid)) {
+          visited.add(pid);
+          queue.push({ id: pid, depth: depth + 1 });
+          if (visited.size >= 500) break;
+        }
+      }
+    }
+
+    // Return callers of target, not the target itself
+    visited.delete(targetId);
+    const matched = [...visited].map(id => ctx.byId.get(id)).filter(Boolean);
+    return { matched, matchStrength: 'chain' };
+  }
+
+  // ------------------------------------------------------------------
+  // no recognized prefix — keyword fallback
+  // ------------------------------------------------------------------
+  const hits = search(ctx, dest, { limit });
+  const matched = hits.map(h => ctx.byId.get(h.id)).filter(Boolean);
+  return { matched, matchStrength: 'keyword' };
+}