@tekyzinc/gsd-t 5.22.10 → 5.24.10

package/bin/gsd-t-graph-query-cli.cjs

@@ -20,6 +20,11 @@
  *   gsd-t graph dangling                       — edges whose dst is a missing node (delete/rename residue)
  *   gsd-t graph test-impl [--inverse]          — test→impl call coverage (--inverse = untested-impl)
  *
+ * Verbs (database tables — Drizzle pgTable/mysqlTable/sqliteTable + pgEnum):
+ *   gsd-t graph who-uses <table> [--writes|--reads] — functions / methods / route handlers using a table
+ *   gsd-t graph table <table>                   — columns + foreign keys in both directions
+ *   (blast-radius <table> and body <table> also accept a table)
+ *
  * Invariants (all verified by keystone tests):
  *   [RULE] query-cli-never-greps       — NO directive-driven grep fallback in any code path
  *   [RULE] parser-fail-disables-loud-never-silent — genuine parser/store failure → {ok:false, reason:'graph-unavailable'}
@@ -204,6 +209,16 @@ function isTestFile(funcId, patterns) {
 // in the implFuncs coverage set.
 
 const UNRESOLVED_PREFIX = "UNRESOLVED#";
+// A file the SCIP indexer ran for but never produced a document for (see
+// gsd-t-graph-scip-upgrade.cjs). [RULE] scip-missing-file-detected-never-silent
+const SCIP_MISSING_TIER = "tree-sitter-floor-SCIP-MISSING";
+// A file SCIP indexed but where too few repo-resolvable calls resolved to call it
+// compiler-accurate. [RULE] scip-tier-proportional
+const COMPILER_PARTIAL_TIER = "compiler-partial";
+// Tiers whose call edges SCIP actually looked at. An UNRESOLVED call in one of
+// these files is SCIP saying "not a repo function" (a local, a mock, a library),
+// so it is never name-matched. [RULE] name-match-only-where-scip-never-looked
+const SCIP_BACKED_TIERS = new Set(["compiler-accurate", COMPILER_PARTIAL_TIER]);
 
 /**
  * Load records from a JSONL store directory.
@@ -370,6 +385,12 @@ function buildIndex(records, skippedFiles) {
   /** @type {Map<string,string>} file → tier (M114: who-calls needs the TARGET
    * file's tier, not just the repo-wide dominant one). */
   const fileTier = new Map();
+  /** @type {Map<string,{name:string,file:string,tier:string,endLine:?number,kind:string,meta:object}>}
+   * Drizzle tables + enums, kept OUT of funcEntities so dead-code / test-impl /
+   * who-calls never mistake a table for a function. [RULE] drizzle-table-entity-and-usage-edges */
+  const tableEntities = new Map();
+  /** @type {Map<string,Array<{src:string,access:string,op:string,line:number}>>} table code name → uses */
+  const tableUses = new Map();
 
   let dominantTier = "compiler-accurate";
   let hasFloor = false;
@@ -379,13 +400,18 @@ function buildIndex(records, skippedFiles) {
     allFiles.add(rec.file);
     if (rec.tier) fileTier.set(rec.file, rec.tier);
 
-    if (rec.tier === "tree-sitter-floor") hasFloor = true;
+    if (rec.tier === "tree-sitter-floor" || rec.tier === SCIP_MISSING_TIER || rec.tier === COMPILER_PARTIAL_TIER) hasFloor = true;
     if (rec.tier === "tree-sitter-floor-STALE-SCIP") hasStaleScip = true;
 
     // Index entities for bare-name disambiguation + tier labeling
     if (Array.isArray(rec.entities)) {
       for (const ent of rec.entities) {
-        if (ent.funcId) {
+        if (ent.funcId && (ent.kind === "table" || ent.kind === "enum")) {
+          tableEntities.set(ent.funcId, {
+            name: ent.name, file: ent.file || rec.file, tier: ent.tier || rec.tier,
+            endLine: ent.endLine ?? null, kind: ent.kind, meta: ent.meta || {},
+          });
+        } else if (ent.funcId) {
           funcEntities.set(ent.funcId, {
             name: ent.name,
             file: ent.file || rec.file,
@@ -409,6 +435,13 @@ function buildIndex(records, skippedFiles) {
           callGraph.get(edge.dst).add(edge.src);
           // Forward: collect ALL call edges for dangling + test-impl verbs
           forwardCallEdges.push({ src: edge.src, dst: edge.dst, kind: "CALL" });
+        } else if (edge.kind === "TABLE-READ" || edge.kind === "TABLE-WRITE") {
+          // dst = TABLE#<name>#<operation>@<line>
+          const m = /^TABLE#([^#]+)#([^@]+)@(\d+)$/.exec(edge.dst);
+          if (m) {
+            if (!tableUses.has(m[1])) tableUses.set(m[1], []);
+            tableUses.get(m[1]).push({ src: edge.src, access: edge.kind.slice(6), op: m[2], line: Number(m[3]) });
+          }
         }
       }
     }
@@ -420,8 +453,11 @@ function buildIndex(records, skippedFiles) {
   return {
     importGraph,
     callGraph,
+    nameMatchedCallGraph: buildNameMatchedCallGraph(forwardCallEdges, funcEntities, fileTier),
     forwardCallEdges,
     funcEntities,
+    tableEntities,
+    tableUses,
     allFiles,
     fileTier,
     tier: dominantTier,
@@ -429,6 +465,76 @@ function buildIndex(records, skippedFiles) {
   };
 }
 
+/**
+ * Name-matched reverse call edges: `UNRESOLVED#<name>` → the ONE function in the
+ * repo named <name>, for callers in files SCIP never resolved (no SCIP document,
+ * floor, stale). A labelled answer, never a compiler one: who-calls reports these
+ * callers under `nameMatched` with `resolution: "name-matched"`.
+ * A name defined 2+ times is never matched — it stays in
+ * coverage.unresolvedCallSites. [RULE] unique-name-unresolved-call-name-matched
+ * [RULE] name-match-only-where-scip-never-looked
+ *
+ * @returns {Map<string,Set<string>>} dstFuncId (both `file#name@line` and `file#name`) → callers
+ */
+function buildNameMatchedCallGraph(forwardCallEdges, funcEntities, fileTier) {
+  const byName = new Map(); // name → [funcId, ...]
+  for (const [funcId, meta] of funcEntities) {
+    if (!byName.has(meta.name)) byName.set(meta.name, []);
+    byName.get(meta.name).push(funcId);
+  }
+  const graph = new Map();
+  for (const { src, dst } of forwardCallEdges) {
+    if (!dst.startsWith(UNRESOLVED_PREFIX)) continue;
+    const defs = byName.get(dst.slice(UNRESOLVED_PREFIX.length));
+    if (!defs || defs.length !== 1) continue;
+    // [RULE] name-match-only-where-scip-never-looked: include a caller ONLY if its
+    // file was NOT SCIP-backed (not compiler-accurate or compiler-partial). Files
+    // missing from fileTier default to tree-sitter-floor (SCIP never looked), so
+    // they are included. [ISSUE] M119: files outside tsconfig have no fileTier entry
+    // yet contribute valid UNRESOLVED edges → include them.
+    const callerFile = src.split("#")[0];
+    const callerTier = fileTier.get(callerFile);
+    // A missing tier → never SCIP-backed → include it (tree-sitter-floor by default)
+    if (callerTier !== undefined && SCIP_BACKED_TIERS.has(callerTier)) continue;
+    for (const key of new Set([defs[0], defs[0].replace(/@\d+$/, "")])) {
+      if (!graph.has(key)) graph.set(key, new Set());
+      graph.get(key).add(src);
+    }
+  }
+  return graph;
+}
+
+/**
+ * Callers of `funcId` found only by name match (not already compiler callers).
+ * @returns {string[]}
+ */
+function nameMatchedCallersOf(index, funcId, compilerCallers) {
+  if (!index.nameMatchedCallGraph) return [];
+  const set = index.nameMatchedCallGraph.get(funcId) || index.nameMatchedCallGraph.get(funcId.replace(/@\d+$/, ""));
+  if (!set) return [];
+  return Array.from(set).filter((c) => !compilerCallers.has(c)).sort();
+}
+
+/**
+ * who-calls envelope: compiler callers + labelled name-matched callers. A
+ * name-matched caller leaves coverage.unresolvedCallSites (it is accounted for).
+ */
+function whoCallsResult(index, funcId, baseCoverage, identity) {
+  const compiler = index.callGraph.get(funcId) || index.callGraph.get(funcId.replace(/@\d+$/, "")) || new Set();
+  const matched = nameMatchedCallersOf(index, funcId, compiler);
+  const results = Array.from(compiler).concat(matched).sort();
+  const coverage = withUnresolvedSites(baseCoverage, index, identity, matched);
+  if (!matched.length) return { results, tier: index.tier, coverage };
+  const out = { results, tier: index.tier, coverage };
+  out.nameMatched = {
+    resolution: "name-matched",
+    note: "unresolved call sites naming the only function in the repo with this name, in files SCIP never resolved — name-matched, not compiler-resolved",
+    count: matched.length,
+    callers: matched,
+  };
+  return out;
+}
+
 // ─── Load store + build index (fail-loud on any failure) ─────────────────────
 
 /**
@@ -465,9 +571,12 @@ function loadSqliteStore(dbPath) {
     // M98: end_line is a post-M98 column; a pre-M98 graph (read-only here, so the
     // write-path migration can't run) lacks it. Detect and select conditionally so
     // an older index still loads (end_line just comes back null → body re-indexes).
-    const hasEndLine = db.prepare("PRAGMA table_info(nodes)").all().some((c) => c.name === "end_line");
+    const nodeCols = db.prepare("PRAGMA table_info(nodes)").all().map((c) => c.name);
+    const hasEndLine = nodeCols.includes("end_line");
+    // meta (table columns / enum values) is newer still — same conditional select.
+    const hasMeta = nodeCols.includes("meta");
     const nodes = db.prepare(
-      `SELECT id, kind, tier, file, name, func_id, ${hasEndLine ? "end_line" : "NULL AS end_line"} FROM nodes`
+      `SELECT id, kind, tier, file, name, func_id, ${hasEndLine ? "end_line" : "NULL AS end_line"}, ${hasMeta ? "meta" : "NULL AS meta"} FROM nodes`
     ).all();
     const edges = db.prepare("SELECT kind, src, dst FROM edges").all();
 
@@ -582,7 +691,12 @@ function loadSqliteStore(dbPath) {
       return byFile.get(file);
     };
     for (const n of nodes) {
-      if (n.func_id) rec(n.file).entities.push({ funcId: n.func_id, name: n.name, file: n.file, tier: n.tier, endLine: n.end_line });
+      if (n.func_id) {
+        rec(n.file).entities.push({
+          funcId: n.func_id, name: n.name, file: n.file, tier: n.tier, endLine: n.end_line, kind: n.kind,
+          ...(n.meta === null ? {} : { meta: JSON.parse(n.meta) }),
+        });
+      }
     }
     // M114 — carry each file's TIER onto its record. Without this the record is
     // {file, entities, edges} with no tier, so the query layer cannot tell a
@@ -595,6 +709,13 @@ function loadSqliteStore(dbPath) {
       if (n.tier && n.tier !== 'compiler-accurate') r.tier = n.tier;
       else if (!r.tier) r.tier = n.tier || 'compiler-accurate';
     }
+    // The files table is where a SCIP-MISSING label lives even for a file that
+    // declares no function — so `graph status` can list every one of them.
+    if (hasFilesTable) {
+      for (const r of db.prepare("SELECT file, tier FROM files WHERE tier IN (?, ?)").all(SCIP_MISSING_TIER, COMPILER_PARTIAL_TIER)) {
+        rec(norm(r.file)).tier = r.tier;
+      }
+    }
     for (const e of edges) {
       // src for an IMPORT edge is the source FILE; for a CALL edge it's a funcId
       // (file#fn@line). The owning file record is the src's file part.
@@ -602,6 +723,21 @@ function loadSqliteStore(dbPath) {
       const dst = e.kind === "IMPORT" ? resolveDst(srcFile, e.dst) : e.dst;
       rec(srcFile).edges.push({ kind: e.kind, src: e.src, dst });
     }
+    // A file with call edges but no function node (top-level code only) got no
+    // tier from the node pass. Name matching needs to know whether SCIP looked
+    // at it, so take its tier from the files table. [RULE] name-match-only-where-scip-never-looked
+    //
+    // Every file in the files table is a record, even one with no function and
+    // no edge (a types-only or constants-only file). Building records only from
+    // nodes/edges left those out, so `graph status` reported 4,301 files right
+    // after an index of 4,373 (hilo-figma-atos). [RULE] status-counts-files-table
+    if (hasFilesTable) {
+      for (const r of db.prepare("SELECT file, tier FROM files").all()) {
+        const f = norm(r.file);
+        const fr = rec(f);
+        if (r.tier && !fr.tier) fr.tier = r.tier;
+      }
+    }
     db.close();
     return { records: Array.from(byFile.values()) };
   } catch (_e) {
@@ -708,7 +844,8 @@ function runFreshnessCheck(storePath) {
     };
   } catch (_e) {
     // Parse/corrupt/other freshness error → BROKEN, carry the cause code.
-    return { ok: false, reason: "graph-broken", detail: _e && _e.code ? _e.code : "freshness-failed" };
+    // Carry the message: "package.json is not valid JSON" must reach the user, not "freshness-failed".
+    return { ok: false, reason: "graph-broken", detail: _e && _e.code ? _e.code : ("freshness-failed: " + (_e && _e.message ? _e.message : String(_e))) };
   }
 }
 
@@ -733,6 +870,42 @@ function queryWhoImports(index, target) {
   return { results, tier: index.tier, coverage };
 }
 
+// ─── Unresolved call sites that name the target ──────────────────────────────
+//
+// When coverage is incomplete, the calls the graph could not resolve are still
+// in it — as `UNRESOLVED#<name>` edges from a known caller. They are NOT results
+// (a name match is not a resolved call), so they are reported inside `coverage`,
+// labelled, with the files to open. That turns "[] and incomplete" into a named
+// place to look. [RULE] incomplete-empty-answer-names-a-path-forward
+
+function unresolvedCallSitesFor(index, identity, accounted) {
+  const name = identity.split("#").pop().replace(/@\d+$/, "");
+  if (!name) return null;
+  const exact = UNRESOLVED_PREFIX + name;
+  const member = "." + name;
+  const callers = new Set();
+  for (const { src, dst } of index.forwardCallEdges) {
+    if (dst === exact || (dst.startsWith(UNRESOLVED_PREFIX) && dst.endsWith(member))) callers.add(src);
+  }
+  // A caller already reported as name-matched is accounted for, not unknown.
+  if (accounted) for (const c of accounted) callers.delete(c);
+  if (callers.size === 0) return null;
+  const sorted = Array.from(callers).sort();
+  const files = Array.from(new Set(sorted.map((c) => c.split("#")[0]))).sort();
+  return {
+    count: sorted.length,
+    note: "name-match only — these callers call something named '" + name + "' that the graph could not resolve; open these files to confirm",
+    callers: sorted.slice(0, 100),
+    files: files.slice(0, 50),
+  };
+}
+
+function withUnresolvedSites(coverage, index, identity, accounted) {
+  if (!coverage || coverage.complete !== false) return coverage;
+  const sites = unresolvedCallSitesFor(index, identity, accounted);
+  return sites ? { ...coverage, unresolvedCallSites: sites } : coverage;
+}
+
 // ─── Query: who-calls ─────────────────────────────────────────────────────────
 
 /**
@@ -755,14 +928,13 @@ function queryWhoImports(index, target) {
  */
 function queryWhoCalls(index, identity) {
   const isFuncId = identity.includes("#");
-  const coverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
+  const baseCoverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
+  const coverage = withUnresolvedSites(baseCoverage, index, identity);
 
   if (isFuncId) {
     // File-qualified identity — exact funcId lookup (tolerate @line suffix:
     // callGraph keys on `file#name`, callers may pass `file#name@line`).
-    const callers = index.callGraph.get(identity) || index.callGraph.get(identity.replace(/@\d+$/, ''));
-    const results = callers ? Array.from(callers).sort() : [];
-    return { results, tier: index.tier, coverage };
+    return whoCallsResult(index, identity, baseCoverage, identity);
   }
 
   // Bare name — disambiguate against all funcIds
@@ -775,7 +947,10 @@ function queryWhoCalls(index, identity) {
   }
 
   if (matchingFuncIds.length === 0) {
-    return { results: [], tier: index.tier, coverage };
+    const out = { results: [], tier: index.tier, coverage };
+    const hint = tableHint(index, bareName);
+    if (hint) out.hint = hint;
+    return out;
   }
 
   if (matchingFuncIds.length === 1) {
@@ -783,17 +958,23 @@ function queryWhoCalls(index, identity) {
     // funcEntities key as `file#name@line`, but call edges (and thus callGraph)
     // key as `file#name` (no @line) — try both so the @line-suffix difference
     // doesn't drop real callers. [RULE] who-calls-funcid-line-suffix-tolerant
-    const fid = matchingFuncIds[0];
-    const fidNoLine = fid.replace(/@\d+$/, '');
-    const callers = index.callGraph.get(fid) || index.callGraph.get(fidNoLine);
-    const results = callers ? Array.from(callers).sort() : [];
-    return { results, tier: index.tier, coverage };
+    return whoCallsResult(index, matchingFuncIds[0], baseCoverage, identity);
   }
 
   // Multiple matches — ambiguous, NEVER merge
   return { ambiguous: true, candidates: matchingFuncIds.sort() };
 }
 
+/** A who-calls on a table name (or a table builder) is a table question — say which verbs answer it. */
+function tableHint(index, name) {
+  if (name === "pgTable" || name === "mysqlTable" || name === "sqliteTable" || name === "pgEnum") {
+    return `${name} declares database tables — the graph records each one: gsd-t graph table <name>, gsd-t graph who-uses <name>`;
+  }
+  const r = resolveTable(index, name);
+  if (r.notFound) return null;
+  return `'${name}' is a database ${r.table ? r.table.kind : "table"} — ask: gsd-t graph who-uses ${name}  |  gsd-t graph table ${name}  |  gsd-t graph blast-radius ${name}`;
+}
+
 // ─── Query: body (M98) ────────────────────────────────────────────────────────
 
 /**
@@ -845,7 +1026,13 @@ function queryBody(index, identity, projectRoot) {
     else if (matches.length > 1) return { ambiguous: true, candidates: matches.sort() };
   }
 
-  if (!funcId) return { notFound: true };
+  if (!funcId) {
+    // Not a function — a database table or enum? [RULE] drizzle-table-entity-and-usage-edges
+    const tr = resolveTable(index, identity);
+    if (tr.ambiguous) return tr;
+    if (!tr.table) return { notFound: true };
+    return tableBody(index, tr.table, projectRoot);
+  }
 
   const meta = index.funcEntities.get(funcId);
   // Start line is encoded in the funcId suffix `@<line>`; end_line from the node.
@@ -904,6 +1091,27 @@ function queryBody(index, identity, projectRoot) {
   };
 }
 
+/** body of a table: its declaration sliced live from disk + columns + FKs both ways. */
+function tableBody(index, t, projectRoot) {
+  const startLine = parseInt(/@(\d+)$/.exec(t.id)[1], 10);
+  const absFile = path.isAbsolute(t.file) ? t.file : path.join(projectRoot, t.file);
+  let lines;
+  try { lines = fs.readFileSync(absFile, "utf8").split("\n"); }
+  catch (_e) { return { notFound: true, file: t.file }; }
+  return {
+    ok: true,
+    funcId: t.id,
+    file: t.file,
+    lineRange: [startLine, t.endLine],
+    tier: t.tier,
+    imports: [],
+    classHeader: null,
+    source: lines.slice(startLine - 1, t.endLine).join("\n"),
+    callers: [],
+    table: tableDetail(index, t),
+  };
+}
+
 // ─── Query: blast-radius ──────────────────────────────────────────────────────
 
 /**
@@ -939,6 +1147,12 @@ function queryBody(index, identity, projectRoot) {
  * @returns {{ results: string[], tier: string }}
  */
 function queryBlastRadius(index, target) {
+  // A database table (by code name, SQL name, or id) — not a file, not a function.
+  if (!index.allFiles.has(target) && !index.funcEntities.has(target)) {
+    const tr = resolveTable(index, target);
+    if (tr.table) return queryTableBlastRadius(index, tr.table);
+    if (tr.ambiguous) return tr;
+  }
   const isFilePath = !target.includes("#");
 
   // Build the initial frontier (multi-root if file-path: include owned funcIds)
@@ -951,12 +1165,17 @@ function queryBlastRadius(index, target) {
     for (const [funcId, meta] of index.funcEntities) {
       if (meta.file === target) {
         initialFrontier.add(funcId);
+        // SCIP-resolved call edges key on `file#name` (no @line) — seed that
+        // form too, or a file's callers never enter the radius.
+        // [RULE] who-calls-funcid-line-suffix-tolerant
+        initialFrontier.add(funcId.replace(/@\d+$/, ""));
       }
     }
   }
 
   // BFS over the UNION of reverse import + call edges, transitive closure
   const visited = new Set();
+  const nameMatchedReached = new Set();
   const queue = Array.from(initialFrontier);
 
   while (queue.length > 0) {
@@ -972,10 +1191,13 @@ function queryBlastRadius(index, target) {
       }
     }
 
-    // Reverse call edges: who calls this function node?
-    const callers = index.callGraph.get(node);
-    if (callers) {
+    // Reverse call edges: who calls this function node? (compiler + name-matched;
+    // name-matched ones are listed separately below) [RULE] unique-name-unresolved-call-name-matched
+    for (const graph of [index.callGraph, index.nameMatchedCallGraph]) {
+      const callers = graph && graph.get(node);
+      if (!callers) continue;
       for (const caller of callers) {
+        if (graph !== index.callGraph && !(index.callGraph.get(node) || new Set()).has(caller)) nameMatchedReached.add(caller);
         if (!visited.has(caller)) queue.push(caller);
       }
     }
@@ -988,8 +1210,180 @@ function queryBlastRadius(index, target) {
   }
 
   const results = Array.from(visited).sort();
-  const coverage = computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) });
-  return { results, tier: index.tier, coverage };
+  const matched = Array.from(nameMatchedReached).filter((c) => visited.has(c)).sort();
+  const coverage = withUnresolvedSites(
+    computeCoverage(index.skippedFiles, { callEdgesUnresolved: true, unresolvedFiles: countUnresolvedFiles(index) }),
+    index, target, matched);
+  if (!matched.length) return { results, tier: index.tier, coverage };
+  return {
+    results, tier: index.tier, coverage,
+    nameMatched: { resolution: "name-matched", count: matched.length, callers: matched.slice(0, 100) },
+  };
+}
+
+// ─── Database tables (Drizzle) ────────────────────────────────────────────────
+//
+// Verbs: `table <name>`, `who-uses <table> [--writes|--reads]`, and table mode of
+// `blast-radius` and `body`. A table is found by its code name (scheduleEvents)
+// or its SQL name (schedule_events, case-insensitive — a domain value).
+// Uses are matched by the table's exported name as written at the use site
+// (syntactic, not compiler-resolved): an import alias is followed, a table passed
+// through a function parameter is not. [RULE] drizzle-table-entity-and-usage-edges
+// [RULE] table-not-indexed-distinct-from-no-users
+
+/** → { table: {id, ...meta} } | { ambiguous, candidates } | { notFound } */
+function resolveTable(index, target) {
+  if (!index.tableEntities) return { notFound: true };
+  if (target.includes("#")) {
+    const noLine = target.replace(/@\d+$/, "");
+    for (const [id, t] of index.tableEntities) {
+      if (id === target || id.replace(/@\d+$/, "") === noLine) return { table: { id, ...t } };
+    }
+    return { notFound: true };
+  }
+  const byCode = [];
+  const bySql = [];
+  const lower = target.toLowerCase();
+  for (const [id, t] of index.tableEntities) {
+    if (t.name === target) byCode.push(id);
+    else if (typeof t.meta.sqlName === "string" && t.meta.sqlName.toLowerCase() === lower) bySql.push(id);
+  }
+  const ids = byCode.length ? byCode : bySql;
+  if (ids.length === 0) return { notFound: true };
+  if (ids.length > 1) return { ambiguous: true, candidates: ids.sort() };
+  return { table: { id: ids[0], ...index.tableEntities.get(ids[0]) } };
+}
+
+function notIndexedDetail(index, target) {
+  const n = index.tableEntities ? index.tableEntities.size : 0;
+  return `no table or enum named '${target}' is indexed (${n} tables/enums in the graph, found by code name or SQL name) — ` +
+    `check the name; if it was declared since the last build, run: gsd-t graph index`;
+}
+
+/** Table ids declared under a code name (FK targets are written as code names). */
+function tableIdsNamed(index, name) {
+  const ids = [];
+  for (const [id, t] of index.tableEntities) if (t.name === name) ids.push(id);
+  return ids.sort();
+}
+
+/** Foreign keys out of `t` (column-level references + table-level foreignKey()). */
+function foreignKeysOut(index, t) {
+  const out = [];
+  for (const c of t.meta.columns ? t.meta.columns : []) {
+    if (!c.references) continue;
+    out.push({ column: c.name, sqlColumn: c.sqlName, table: c.references.table, targetColumn: c.references.column, tableIds: tableIdsNamed(index, c.references.table) });
+  }
+  for (const fk of t.meta.foreignKeys ? t.meta.foreignKeys : []) {
+    out.push({ column: fk.columns.join(", "), table: fk.table, targetColumn: fk.foreignColumns.join(", "), tableIds: tableIdsNamed(index, fk.table) });
+  }
+  return out;
+}
+
+/** Foreign keys INTO `t` from every other indexed table. */
+function foreignKeysIn(index, t) {
+  const refs = [];
+  for (const [id, other] of index.tableEntities) {
+    if (other.kind !== "table") continue;
+    for (const fk of foreignKeysOut(index, other)) {
+      if (fk.table === t.name) refs.push({ table: other.name, tableId: id, column: fk.column, sqlColumn: fk.sqlColumn, targetColumn: fk.targetColumn });
+    }
+  }
+  return refs.sort((a, b) => (a.tableId + a.column < b.tableId + b.column ? -1 : 1));
+}
+
+function tableDetail(index, t) {
+  const detail = {
+    id: t.id, kind: t.kind, name: t.name, sqlName: t.meta.sqlName, dialect: t.meta.dialect, file: t.file,
+  };
+  if (t.kind === "enum") {
+    detail.values = t.meta.values;
+    // Tables whose columns are built from this enum (`statusEnum('status')`).
+    detail.usedByColumns = [];
+    for (const [id, other] of index.tableEntities) {
+      for (const c of other.meta.columns ? other.meta.columns : []) {
+        if (c.type === t.name) detail.usedByColumns.push({ table: other.name, tableId: id, column: c.name, sqlColumn: c.sqlName });
+      }
+    }
+  } else {
+    detail.columns = t.meta.columns;
+    detail.references = foreignKeysOut(index, t);
+    detail.referencedBy = foreignKeysIn(index, t);
+  }
+  if (t.meta.unresolved) detail.unresolved = t.meta.unresolved;
+  return detail;
+}
+
+/** `table <name>` → columns + foreign keys in both directions. */
+function queryTable(index, target) {
+  const r = resolveTable(index, target);
+  if (!r.table) return r.ambiguous ? r : { notFound: true, detail: notIndexedDetail(index, target) };
+  return { table: tableDetail(index, r.table), tier: index.tier };
+}
+
+/** `who-uses <table> [--writes|--reads]` → the functions / methods / route handlers that use it. */
+function queryWhoUses(index, target, options) {
+  const mode = options && options.mode ? options.mode : "all";
+  const r = resolveTable(index, target);
+  if (!r.table) return r.ambiguous ? r : { notFound: true, detail: notIndexedDetail(index, target) };
+  const t = r.table;
+  const all = index.tableUses.has(t.name) ? index.tableUses.get(t.name) : [];
+  const uses = all.filter((u) => mode === "all" || (mode === "writes" ? u.access === "WRITE" : u.access === "READ"));
+  const byUser = new Map();
+  const byOperation = {};
+  for (const u of uses) {
+    if (!byUser.has(u.src)) byUser.set(u.src, { user: u.src, file: u.src.split("#")[0], access: [], operations: {} });
+    const row = byUser.get(u.src);
+    if (!row.access.includes(u.access)) row.access.push(u.access);
+    if (!row.operations[u.op]) row.operations[u.op] = [];
+    row.operations[u.op].push(u.line);
+    byOperation[u.op] = (byOperation[u.op] ? byOperation[u.op] : 0) + 1;
+  }
+  const results = Array.from(byUser.values()).sort((a, b) => (a.user < b.user ? -1 : 1));
+  for (const row of results) row.access.sort();
+  const out = {
+    table: { id: t.id, name: t.name, sqlName: t.meta.sqlName, kind: t.kind },
+    mode,
+    results,
+    summary: { users: results.length, files: new Set(results.map((x) => x.file)).size, byOperation },
+    resolution: "syntactic — uses matched by the table's imported name; a table passed through a function parameter or alias() is not followed",
+    coverage: computeCoverage(index.skippedFiles),
+    tier: index.tier,
+  };
+  const sharing = tableIdsNamed(index, t.name);
+  if (sharing.length > 1) out.sharedName = { note: `${sharing.length} tables share the code name '${t.name}' — uses cannot be split between them`, tables: sharing };
+  if (results.length === 0) {
+    out.note = mode === "all"
+      ? `'${t.name}' is indexed; no code in the index uses it`
+      : `'${t.name}' is indexed; no code in the index ${mode === "writes" ? "writes" : "reads"} it`;
+  }
+  return out;
+}
+
+/** blast-radius of a table: tables that reference it by FK (transitively) + the code that uses it. */
+function queryTableBlastRadius(index, t) {
+  const tables = [];
+  const seen = new Set([t.id]);
+  const queue = [{ table: t, depth: 1 }];
+  while (queue.length) {
+    const { table, depth } = queue.shift();
+    for (const ref of foreignKeysIn(index, table)) {
+      if (seen.has(ref.tableId)) continue;
+      seen.add(ref.tableId);
+      tables.push({ id: ref.tableId, via: `${ref.table}.${ref.column} → ${table.name}.${ref.targetColumn}`, depth });
+      queue.push({ table: { id: ref.tableId, ...index.tableEntities.get(ref.tableId) }, depth: depth + 1 });
+    }
+  }
+  const users = (index.tableUses.has(t.name) ? index.tableUses.get(t.name) : []).map((u) => u.src);
+  const code = Array.from(new Set(users)).sort();
+  return {
+    results: tables.map((x) => x.id).concat(code),
+    table: { id: t.id, name: t.name, sqlName: t.meta.sqlName },
+    referencingTables: tables,
+    users: code,
+    tier: index.tier,
+    coverage: computeCoverage(index.skippedFiles),
+  };
 }
 
 // ─── Query: status ────────────────────────────────────────────────────────────
@@ -1004,17 +1398,71 @@ function queryBlastRadius(index, target) {
  * @returns {object}
  */
 function queryStatus(index, storePath) {
+  // [RULE] scip-missing-file-detected-never-silent — status names them.
+  const scipMissing = [];
+  for (const [file, tier] of index.fileTier || []) if (tier === SCIP_MISSING_TIER) scipMissing.push(file);
+  scipMissing.sort();
   return {
+    scipMissing: { count: scipMissing.length, files: scipMissing.slice(0, 50) },
     queryable: true,
     storePath,
     fileCount: index.allFiles.size,
     funcCount: index.funcEntities.size,
     importEdgeCount: Array.from(index.importGraph.values()).reduce((s, v) => s + v.size, 0),
     callEdgeCount: Array.from(index.callGraph.values()).reduce((s, v) => s + v.size, 0),
+    // `tier` is the WORST tier present (one floor file makes it floor). The per-tier
+    // counts are what a build reports, so status shows them too. [RULE] status-counts-files-table
     tier: index.tier,
+    tiers: tierCounts(index),
+    tableCount: countKind(index, "table"),
+    enumCount: countKind(index, "enum"),
+    excludeSuggestions: suggestExcludes(index),
   };
 }
 
+function tierCounts(index) {
+  const counts = {};
+  for (const tier of (index.fileTier ? index.fileTier.values() : [])) counts[tier] = (counts[tier] ? counts[tier] : 0) + 1;
+  return counts;
+}
+
+function countKind(index, kind) {
+  let n = 0;
+  for (const t of (index.tableEntities ? index.tableEntities.values() : [])) if (t.kind === kind) n++;
+  return n;
+}
+
+/**
+ * Top-level folders that look like they are not the application: no file in them
+ * imports, or is imported by, a file in the project's largest folder (the app).
+ * A SUGGESTION for .gsd-t/graph-exclude.json — never applied automatically, since
+ * guessing wrong would silently drop app code from the graph.
+ */
+function suggestExcludes(index) {
+  const top = (f) => (f.includes("/") ? f.split("/")[0] : null);
+  const sizes = new Map();
+  for (const f of index.allFiles) {
+    const t = top(f);
+    if (t !== null) sizes.set(t, (sizes.has(t) ? sizes.get(t) : 0) + 1);
+  }
+  if (sizes.size < 2) return [];
+  const main = Array.from(sizes.entries()).sort((a, b) => b[1] - a[1])[0][0];
+  const linked = new Set([main]);
+  for (const [dst, srcs] of index.importGraph) {
+    if (!index.allFiles.has(dst)) continue;
+    const d = top(dst);
+    for (const src of srcs) {
+      const sTop = top(src);
+      if (d === main && sTop !== null) linked.add(sTop);
+      if (sTop === main && d !== null) linked.add(d);
+    }
+  }
+  return Array.from(sizes.entries())
+    .filter(([folder]) => !linked.has(folder))
+    .sort((a, b) => b[1] - a[1])
+    .map(([folder, files]) => ({ folder: folder + "/", files, reason: `no import edges to or from ${main}/` }));
+}
+
 // ─── D9-T1: Query: cluster (tightly-coupled file groups) ─────────────────────
 //
 // [RULE] cluster-verb-deterministic-coupling
@@ -1203,7 +1651,7 @@ function queryDeadCode(index) {
     // [RULE] orphan-tier-labeled-candidate-not-certainty:
     // Floor-tier results are CANDIDATE (a missed unresolved call could explain the absence).
     const tier = meta.tier || index.tier;
-    const isFloor = tier === "tree-sitter-floor" || tier === "tree-sitter-floor-STALE-SCIP";
+    const isFloor = tier === "tree-sitter-floor" || tier === "tree-sitter-floor-STALE-SCIP" || tier === SCIP_MISSING_TIER;
     const candidateLabel = isFloor ? "CANDIDATE" : null;
 
     results.push({ funcId, file: meta.file, tier, candidateLabel });
@@ -1346,6 +1794,32 @@ function queryTestImpl(index, options) {
   return { results: untested, tier: index.tier, mode: "untested-impl" };
 }
 
+// ─── Incomplete-empty marker (read by the M117 search guard) ──────────────────
+//
+// The search guard runs BEFORE a grep and cannot see what the graph just said.
+// When who-calls / blast-radius answers [] with coverage incomplete, record it,
+// so the guard's block message can name a path forward (the files to open, the
+// re-index) instead of leaving none. A write failure is said on stderr.
+// [RULE] incomplete-empty-answer-names-a-path-forward
+
+const INCOMPLETE_MARKER_NAME = "last-incomplete-answer.json";
+
+function writeIncompleteAnswerMarker(projectRoot, verb, target, coverage) {
+  const file = path.join(projectRoot, ".gsd-t", "graphDB", INCOMPLETE_MARKER_NAME);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({
+      ts: new Date().toISOString(),
+      verb,
+      target,
+      note: coverage.note || null,
+      unresolvedCallSites: coverage.unresolvedCallSites || null,
+    }, null, 2));
+  } catch (e) {
+    process.stderr.write("[graph] could not record the incomplete answer for the search guard (" + e.message + ")\n");
+  }
+}
+
 // ─── Public API (for tests to import directly) ────────────────────────────────
 // Tests build an index from fixture records, then call these pure functions.
 // The query CLI is the only caller of runFreshnessCheck (integration seam).
@@ -1368,6 +1842,10 @@ module.exports = {
   queryBody,
   queryBlastRadius,
   queryStatus,
+  queryTable,
+  queryWhoUses,
+  resolveTable,
+  suggestExcludes,
   // D9 additions
   queryCluster,
   queryDeadCode,
@@ -1384,6 +1862,10 @@ module.exports = {
   COUPLING_THRESHOLD,
   DEFAULT_TEST_PATTERNS,
   UNRESOLVED_PREFIX,
+  SCIP_MISSING_TIER,
+  unresolvedCallSitesFor,
+  writeIncompleteAnswerMarker,
+  INCOMPLETE_MARKER_NAME,
   getTestPatterns,
   isTestFile,
 };
@@ -1459,6 +1941,7 @@ if (require.main === module) {
   const ALL_VERBS = [
     "who-imports", "who-calls", "body", "blast-radius", "status",
     "cluster", "dead-code", "orphan", "dangling", "test-impl",
+    "who-uses", "table",
   ];
 
   if (!verb) {
@@ -1522,7 +2005,13 @@ if (require.main === module) {
       });
       process.exit(2);
     }
-    emit({ ok: true, verb, target, results: queryResult.results, tier: queryResult.tier, coverage: queryResult.coverage });
+    if (queryResult.results.length === 0 && queryResult.coverage && queryResult.coverage.complete === false) {
+      writeIncompleteAnswerMarker(_resolver.deriveProjectRoot(storePath), verb, target, queryResult.coverage);
+    }
+    const env = { ok: true, verb, target, results: queryResult.results, tier: queryResult.tier, coverage: queryResult.coverage };
+    if (queryResult.nameMatched) env.nameMatched = queryResult.nameMatched; // [RULE] unique-name-unresolved-call-name-matched
+    if (queryResult.hint) env.hint = queryResult.hint; // a table name asked of who-calls
+    emit(env);
 
   } else if (verb === "body") {
     if (!target) fail({ ok: false, reason: "missing-target", verb });
@@ -1572,16 +2061,46 @@ if (require.main === module) {
       lineRange: bodyResult.lineRange, tier: bodyResult.tier,
       imports: bodyResult.imports, classHeader: bodyResult.classHeader,
       source: bodyResult.source, callers: bodyResult.callers,
+      ...(bodyResult.table ? { table: bodyResult.table } : {}),
     });
 
   } else if (verb === "blast-radius") {
     if (!target) fail({ ok: false, reason: "missing-target", verb });
-    const { results, tier, coverage } = queryBlastRadius(index, target);
-    emit({ ok: true, verb, target, results, tier, coverage });
+    const br = queryBlastRadius(index, target);
+    if (br.ambiguous) {
+      emit({ ok: false, reason: "ambiguous-table", verb, target, candidates: br.candidates });
+      process.exit(2);
+    }
+    if (br.table) {
+      emit({ ok: true, verb, target, results: br.results, table: br.table, referencingTables: br.referencingTables, users: br.users, tier: br.tier, coverage: br.coverage });
+      process.exit(0);
+    }
+    const { results, tier, coverage, nameMatched } = br;
+    if (results.length === 0 && coverage && coverage.complete === false) {
+      writeIncompleteAnswerMarker(_resolver.deriveProjectRoot(storePath), verb, target, coverage);
+    }
+    const env = { ok: true, verb, target, results, tier, coverage };
+    if (nameMatched) env.nameMatched = nameMatched; // [RULE] unique-name-unresolved-call-name-matched
+    emit(env);
 
   } else if (verb === "status") {
     const statusData = queryStatus(index, storePath);
-    emit({ ok: true, verb: "status", ...statusData });
+    // Name the project exclude list so a missing folder is never a mystery.
+    const ex = require("./gsd-t-graph-exclude.cjs").loadGraphExcludes(_resolver.deriveProjectRoot(storePath));
+    emit({ ok: true, verb: "status", ...statusData, excludes: { source: ex.source, patterns: ex.patterns, defaults: ex.defaults } });
+
+  } else if (verb === "who-uses" || verb === "table") {
+    // [RULE] table-not-indexed-distinct-from-no-users — not-found (reason + detail)
+    // is a different envelope from an indexed table with no users (ok, results []).
+    if (!target) fail({ ok: false, reason: "missing-target", verb });
+    const mode = args.includes("--writes") ? "writes" : (args.includes("--reads") ? "reads" : "all");
+    const r = verb === "table" ? queryTable(index, target) : queryWhoUses(index, target, { mode });
+    if (r.ambiguous) {
+      emit({ ok: false, reason: "ambiguous-table", verb, target, candidates: r.candidates });
+      process.exit(2);
+    }
+    if (r.notFound) fail({ ok: false, reason: "not-found", verb, target, detail: r.detail });
+    emit({ ok: true, verb, target, ...r });
 
   } else if (verb === "cluster") {
     const { results, tier } = queryCluster(index);