@tekyzinc/gsd-t 5.23.10 → 5.24.10

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.24.10] - 2026-09-29
+
+### Added — the code graph indexes Drizzle database tables
+
+"Which code uses this table?" had no graph answer: tables are declared as `const X = pgTable('x', {…})`, which the indexer never recorded, and the graph-search guard then blocked grep with nothing to offer. On hilo-figma-atos the graph now holds all 431 tables and 63 enums, and `who-uses scheduleEvents` agrees with TypeScript findReferences on 179 of 181 users (the gaps are explained in the progress log).
+
+- `bin/gsd-t-graph-edge-extract.cjs`: `table` / `enum` entities (pg / mysql / sqlite), columns, foreign keys (`.references()` and `foreignKey()`), READ / WRITE usage edges (from / joins / `db.query.T.findMany|findFirst` / insert / update / delete) attributed to the enclosing function or route handler.
+- `bin/gsd-t-graph-query-cli.cjs`, `bin/gsd-t.js`: `who-uses <table> [--writes|--reads]`, `table <name>`; `body` and `blast-radius` accept tables; not-found answers say the table is not indexed.
+- `scripts/gsd-t-graph-search-guard.js`: table-shaped searches point at who-uses / table / blast-radius.
+- `bin/gsd-t-graph-index.cjs`, `bin/gsd-t-graph-freshness.cjs`: `graph status` counts every indexed file (hilo: 4,301 → 4,322, matching the index) with per-tier counts and exclude suggestions; freshness no longer applies folder skips to file names (`build-analytics.ts` was dropped on every query); deleted / newly-excluded files leave no stale records.
+- `bin/gsd-t-graph-exclude.cjs`: GSD-T's own copied `bin/` tools are excluded by default outside the GSD-T repo.
+- Tests: `test/graph-drizzle-tables.test.js` (21) + `test/fixtures/drizzle-graph/`.
+
+Known gaps: code that reaches tables through `import { schema }` objects or CommonJS `require` is not seen; an imported non-table sharing a table's name counts as a use. Re-run `gsd-t graph index` to pick up tables.
+
 ## [5.23.10] - 2026-09-29
 
 ### Added — who-calls matches the compiler on route files; graph exclude list; estimate math v2

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.23.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.24.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/bin/gsd-t-graph-edge-extract.cjs

@@ -236,6 +236,262 @@ function isRoutePath(firstArg) {
   return firstArg.text.slice(1).startsWith('/');
 }
 
+// ── Drizzle database tables ──────────────────────────────────────────────────
+//
+// `export const scheduleEvents = pgTable('schedule_events', { ...columns }, (t) => [...])`
+// declares a database table. Before this, it was a constant with no entity, so
+// `body scheduleEvents` said not-found and every table question dead-ended.
+//
+// Now each declaration is a `table` (or `enum`) entity whose meta carries the SQL
+// name and the columns (code name, SQL name, type builder, notNull, primaryKey,
+// foreign key). Every use of a table in code becomes an edge from the function,
+// method or route handler that uses it:
+//   TABLE-READ   .from(T) / .innerJoin(T) / db.query.T.* / a column ref T.col
+//   TABLE-WRITE  .insert(T) / .update(T) / .delete(T) / a column ref inside one
+// dst = `TABLE#<code name>#<operation>@<line>`. The query layer keeps only dsts
+// that name an indexed table. [RULE] drizzle-table-entity-and-usage-edges
+
+const TABLE_BUILDERS = { pgTable: 'pg', mysqlTable: 'mysql', sqliteTable: 'sqlite' };
+const ENUM_BUILDERS = { pgEnum: 'pg' };
+const TABLE_READ_OPS = new Set(['from', 'innerJoin', 'leftJoin', 'rightJoin', 'fullJoin', 'crossJoin']);
+const TABLE_WRITE_OPS = new Set(['insert', 'update', 'delete']);
+const TABLE_OPS = new Set([...TABLE_READ_OPS, ...TABLE_WRITE_OPS]);
+// Identifier positions that declare or re-export a name rather than use it.
+const NON_USE_PARENTS = new Set([
+  'import_specifier', 'export_specifier', 'namespace_import', 'required_parameter', 'optional_parameter',
+]);
+
+function stringValue(node) {
+  if (!node) return null;
+  if (node.type === 'string') return node.text.slice(1, -1);
+  if (node.type === 'template_string' && !node.text.includes('${')) return node.text.slice(1, -1);
+  return null;
+}
+
+function unwrapParens(node) {
+  let n = node;
+  while (n && n.type === 'parenthesized_expression') n = n.namedChild(0);
+  return n;
+}
+
+/** The columns argument: an object literal, or `(t) => ({ ... })`. */
+function columnsObject(node) {
+  if (!node) return null;
+  if (node.type === 'object') return node;
+  if (node.type === 'arrow_function') {
+    const body = unwrapParens(node.childForFieldName('body'));
+    return body && body.type === 'object' ? body : null;
+  }
+  return null;
+}
+
+/** `T` or `schema.T` → "T". Anything else → null. */
+function tableNameOf(node) {
+  const n = unwrapParens(node);
+  if (!n) return null;
+  if (n.type === 'identifier') return n.text;
+  if (n.type === 'member_expression') {
+    const prop = n.childForFieldName('property');
+    const obj = n.childForFieldName('object');
+    if (prop && obj && obj.type === 'identifier') return prop.text;
+  }
+  return null;
+}
+
+/** `() => users.id` (or `(): AnyPgColumn => users.id`) → { table: 'users', column: 'id' }. */
+function referenceTarget(arrow) {
+  if (!arrow || arrow.type !== 'arrow_function') return null;
+  let body = unwrapParens(arrow.childForFieldName('body'));
+  if (body && body.type === 'statement_block') {
+    const ret = body.namedChildren.find((c) => c.type === 'return_statement');
+    body = ret ? unwrapParens(ret.namedChild(0)) : null;
+  }
+  if (!body || body.type !== 'member_expression') return null;
+  const table = tableNameOf(body.childForFieldName('object'));
+  const prop = body.childForFieldName('property');
+  return table && prop ? { table, column: prop.text } : null;
+}
+
+/** One column: `uuid('flight_school_id').notNull().references(() => flightSchools.id)`. */
+function parseColumn(key, value) {
+  const col = { name: key, sqlName: null, type: null, notNull: false, primaryKey: false };
+  let n = value;
+  while (n && n.type === 'call_expression') {
+    const fn = n.childForFieldName('function');
+    const args = n.childForFieldName('arguments');
+    const obj = fn && fn.type === 'member_expression' ? fn.childForFieldName('object') : null;
+    if (obj && obj.type === 'call_expression') {
+      const method = fn.childForFieldName('property').text;
+      if (method === 'notNull') col.notNull = true;
+      else if (method === 'primaryKey') col.primaryKey = true;
+      else if (method === 'unique') col.unique = true;
+      else if (method === 'references') {
+        const ref = referenceTarget(args && args.namedChild(0));
+        if (ref) col.references = ref;
+        else col.unresolved = `references(${(args ? args.text : '').slice(1, 81)}) — target not a plain table.column`;
+      }
+      n = obj;
+      continue;
+    }
+    // The type builder at the root: uuid('x'), t.uuid('x'), statusEnum('x').
+    col.type = fn && fn.type === 'member_expression' ? fn.childForFieldName('property').text : (fn ? fn.text : null);
+    col.sqlName = stringValue(args && args.namedChild(0));
+    break;
+  }
+  if (!col.type) col.unresolved = `column value is a ${value ? value.type : 'missing node'}, not a builder call`;
+  return col;
+}
+
+/** `foreignKey({ columns: [t.a], foreignColumns: [users.id] })` inside the extras argument. */
+function collectForeignKeys(node, out) {
+  if (!node) return;
+  if (node.type === 'call_expression') {
+    const fn = node.childForFieldName('function');
+    const arg = node.childForFieldName('arguments');
+    const obj = arg && arg.namedChild(0);
+    if (fn && fn.text === 'foreignKey' && obj && obj.type === 'object') {
+      const fk = { columns: [], table: null, foreignColumns: [] };
+      for (const pair of obj.namedChildren) {
+        if (pair.type !== 'pair') continue;
+        const k = pair.childForFieldName('key').text;
+        const v = pair.childForFieldName('value');
+        if (!v || v.type !== 'array') continue;
+        for (const el of v.namedChildren) {
+          if (el.type !== 'member_expression') continue;
+          const prop = el.childForFieldName('property').text;
+          if (k === 'columns') fk.columns.push(prop);
+          if (k === 'foreignColumns') { fk.table = tableNameOf(el.childForFieldName('object')); fk.foreignColumns.push(prop); }
+        }
+      }
+      if (fk.table) out.push(fk);
+      return;
+    }
+  }
+  for (let i = 0; i < node.namedChildCount; i++) collectForeignKeys(node.namedChild(i), out);
+}
+
+/** meta for `pgTable('sql_name', { columns }, extras)`. Shape gaps are named in `unresolved`. */
+function tableMeta(builder, args) {
+  const meta = { kind: 'table', dialect: TABLE_BUILDERS[builder], builder, sqlName: stringValue(args.namedChild(0)), columns: [], foreignKeys: [] };
+  const cols = columnsObject(args.namedChild(1));
+  const problems = [];
+  if (!meta.sqlName) problems.push('table name is not a string literal');
+  if (!cols) problems.push('columns argument is not an object literal');
+  for (const child of cols ? cols.namedChildren : []) {
+    if (child.type === 'pair') meta.columns.push(parseColumn(child.childForFieldName('key').text, child.childForFieldName('value')));
+    else if (child.type === 'spread_element') meta.columns.push({ name: child.text, type: 'spread', unresolved: 'spread — columns defined elsewhere' });
+  }
+  collectForeignKeys(args.namedChild(2), meta.foreignKeys);
+  for (const c of meta.columns) if (c.unresolved) problems.push(`column ${c.name}: ${c.unresolved}`);
+  if (problems.length) meta.unresolved = problems;
+  return meta;
+}
+
+function enumMeta(builder, args) {
+  const values = args.namedChild(1);
+  const meta = { kind: 'enum', dialect: ENUM_BUILDERS[builder], builder, sqlName: stringValue(args.namedChild(0)), values: [] };
+  if (values && values.type === 'array') meta.values = values.namedChildren.map(stringValue).filter((v) => v !== null);
+  const problems = [];
+  if (!meta.sqlName) problems.push('enum name is not a string literal');
+  if (!values || values.type !== 'array') problems.push('values argument is not an array literal');
+  if (problems.length) meta.unresolved = problems;
+  return meta;
+}
+
+/**
+ * Names in this file that could be a table: imported names (local → exported
+ * name), namespace imports (`import * as schema`), and tables declared here.
+ */
+function collectTableCandidates(rootNode) {
+  const local = new Map();
+  const namespaces = new Set();
+  for (const stmt of rootNode.namedChildren) {
+    if (stmt.type === 'import_statement') {
+      const clause = stmt.namedChildren.find((c) => c.type === 'import_clause');
+      for (const sub of clause ? clause.namedChildren : []) {
+        if (sub.type === 'identifier') local.set(sub.text, sub.text);
+        if (sub.type === 'namespace_import') { const id = sub.namedChildren.find((c) => c.type === 'identifier'); if (id) namespaces.add(id.text); }
+        if (sub.type === 'named_imports') {
+          for (const spec of sub.namedChildren) {
+            const name = spec.childForFieldName('name');
+            const alias = spec.childForFieldName('alias');
+            if (name) local.set((alias || name).text, name.text);
+          }
+        }
+      }
+    }
+    const decl = stmt.type === 'export_statement' ? stmt.childForFieldName('declaration') : stmt;
+    if (decl && decl.type === 'lexical_declaration') {
+      for (const d of decl.namedChildren) {
+        const value = d.type === 'variable_declarator' ? d.childForFieldName('value') : null;
+        const fn = value && value.type === 'call_expression' ? value.childForFieldName('function') : null;
+        if (fn && (TABLE_BUILDERS[fn.text] || ENUM_BUILDERS[fn.text])) local.set(d.childForFieldName('name').text, d.childForFieldName('name').text);
+      }
+    }
+  }
+  return { local, namespaces };
+}
+
+/**
+ * The table a call chain writes (`db.update(T).set().where(...)` → 'T'), or null.
+ * A chain that reads (`.from(`) before any write is a subquery, not a write.
+ */
+function chainWriteTarget(call) {
+  let n = call;
+  while (n && n.type === 'call_expression') {
+    const fn = n.childForFieldName('function');
+    if (!fn || fn.type !== 'member_expression') return null;
+    const prop = fn.childForFieldName('property').text;
+    if (TABLE_READ_OPS.has(prop)) return null;
+    if (TABLE_WRITE_OPS.has(prop)) {
+      const args = n.childForFieldName('arguments');
+      return args ? tableNameOf(args.namedChild(0)) : null;
+    }
+    n = unwrapParens(fn.childForFieldName('object'));
+  }
+  return null;
+}
+
+const SCOPE_BOUNDARY = /(_statement|_declaration|^arrow_function$|^function$|^function_expression$|^method_definition$|^statement_block$)/;
+
+/**
+ * Is this identifier a USE of the name? Not its declaration, an import/export
+ * specifier, a parameter, a callee, or the receiver of a method call (`logger.info()`).
+ */
+function isUseSite(node) {
+  const parent = node.parent;
+  if (!parent) return false;
+  if (NON_USE_PARENTS.has(parent.type)) return false;
+  const same = (field) => { const f = parent.childForFieldName(field); return f !== null && f.startIndex === node.startIndex && f.type === node.type; };
+  if (parent.type === 'variable_declarator' && same('name')) return false;
+  if (parent.type === 'call_expression' && same('function')) return false;
+  if (parent.type === 'new_expression' && same('constructor')) return false;
+  if (parent.type === 'member_expression' && same('object')) {
+    const grand = parent.parent;
+    const callee = grand && grand.type === 'call_expression' ? grand.childForFieldName('function') : null;
+    if (callee !== null && callee.startIndex === parent.startIndex) return false;
+  }
+  return true;
+}
+
+/**
+ * A ref to table `name` is a WRITE only inside a chain that writes THAT table
+ * (`db.update(T).where(eq(T.id, …))`). A ref to another table inside it
+ * (`.values({ who: users.name })`, a `.from(users)` subquery) is a READ, and so
+ * is `hash.update(users.id)`. The nearest enclosing chain decides.
+ */
+function refAccess(node, name) {
+  for (let p = node.parent; p && !SCOPE_BOUNDARY.test(p.type); p = p.parent) {
+    if (p.type !== 'call_expression') continue;
+    const fn = p.childForFieldName('function');
+    const prop = fn && fn.type === 'member_expression' ? fn.childForFieldName('property').text : null;
+    if (prop !== null && TABLE_READ_OPS.has(prop)) return 'READ';
+    const target = chainWriteTarget(p);
+    if (target !== null) return target === name ? 'WRITE' : 'READ';
+  }
+  return 'READ';
+}
+
 // ── Python-specific extraction ────────────────────────────────────────────────
 
 function walkPython(rootNode, relPath, entities, edges) {
@@ -371,6 +627,38 @@ function walkPython(rootNode, relPath, entities, edges) {
  * a file-qualified source funcId per [RULE] who-calls-function-identity-disambiguated.
  */
 function walkTSJS(rootNode, relPath, entities, edges) {
+  // Drizzle table tracking — see "Drizzle database tables" above.
+  const candidates = collectTableCandidates(rootNode);
+  const consumed = new Set();     // startIndex of table args already recorded as an operation
+  const declRanges = [];          // [start, end] of table declarations (FKs live in meta, not edges)
+  const refSeen = new Set();      // one column-ref edge per (user, access, table)
+  const inDecl = (i) => declRanges.some(([s, e]) => i >= s && i < e);
+  const userOf = (enclosingFuncId) => (enclosingFuncId === null ? `${relPath}#_toplevel` : enclosingFuncId);
+  const tableEdge = (access, src, name, op, node) => edges.push({
+    kind: `TABLE-${access}`,
+    source: src,
+    target: `TABLE#${name}#${op}@${node.startPosition.row + 1}`,
+    line: node.startPosition.row + 1,
+  });
+  /** The exported table name `node` refers to, when it is a candidate (`T`, `alias`, `schema.T`); else null. */
+  function candidateName(node) {
+    if (node.type === 'identifier') return candidates.local.has(node.text) ? candidates.local.get(node.text) : null;
+    if (node.type !== 'member_expression') return null;
+    const obj = node.childForFieldName('object');
+    if (obj.type !== 'identifier' || !candidates.namespaces.has(obj.text)) return null;
+    return node.childForFieldName('property').text;
+  }
+  function tableRef(node, name, enclosingFuncId) {
+    if (consumed.has(node.startIndex)) return;
+    if (inDecl(node.startIndex)) return;
+    const src = userOf(enclosingFuncId);
+    const access = refAccess(node, name);
+    const key = `${src}\u0000${access}\u0000${name}`;
+    if (refSeen.has(key)) return;
+    refSeen.add(key);
+    tableEdge(access, src, name, 'ref', node);
+  }
+
   /**
    * @param {object} node  - tree-sitter ASTNode
    * @param {string|null} enclosingFuncId  - funcId of innermost function containing this node
@@ -432,6 +720,17 @@ function walkTSJS(rootNode, relPath, entities, edges) {
           });
         }
 
+        // Table operation: `.from(T)`, `.innerJoin(T, …)`, `.insert(T)`, `.update(T)`, `.delete(T)`.
+        // [RULE] drizzle-table-entity-and-usage-edges
+        const op = fn.type === 'member_expression' ? fn.childForFieldName('property').text : null;
+        const tableArg = op !== null && TABLE_OPS.has(op) && args ? unwrapParens(args.namedChild(0)) : null;
+        const tableName = tableArg ? candidateName(tableArg) : null;
+        if (tableName !== null) {
+          tableEdge(TABLE_WRITE_OPS.has(op) ? 'WRITE' : 'READ', userOf(enclosingFuncId), tableName, op, fn.childForFieldName('property'));
+          consumed.add(tableArg.startIndex);
+          if (tableArg.type === 'member_expression') consumed.add(tableArg.childForFieldName('property').startIndex);
+        }
+
         // Route registration: the route itself becomes the caller, named by
         // method + path + line — for its anonymous handler AND for every
         // middleware call in its arguments (`requireAuth()`, `requireLocationTenant()`).
@@ -469,6 +768,28 @@ function walkTSJS(rootNode, relPath, entities, edges) {
       // Fall through to walk children (the call_expression can contain more nodes)
     }
 
+    // ── table references: `eq(T.id, …)`, `getTableColumns(T)`, `db.query.T.findMany()` ──
+    // [RULE] drizzle-table-entity-and-usage-edges
+    if (t === 'identifier' || t === 'shorthand_property_identifier') {
+      if (candidates.local.has(node.text) && isUseSite(node)) tableRef(node, candidates.local.get(node.text), enclosingFuncId);
+      return;
+    }
+    if (t === 'member_expression') {
+      const obj = node.childForFieldName('object');
+      const prop = node.childForFieldName('property');
+      // Drizzle's relational API only: `<db>.query.<table>.findMany|findFirst(…)`.
+      // `req.query.page` / `data.query?.pages` are not table reads.
+      const outer = node.parent;
+      const method = outer && outer.type === 'member_expression' ? outer.childForFieldName('property').text : null;
+      const viaQuery = obj.type === 'member_expression' && obj.childForFieldName('property').text === 'query' &&
+        (method === 'findMany' || method === 'findFirst');
+      if (viaQuery && prop.type === 'property_identifier') {
+        tableEdge('READ', userOf(enclosingFuncId), prop.text, 'query', node);
+      } else if (obj.type === 'identifier' && candidates.namespaces.has(obj.text) && isUseSite(node)) {
+        tableRef(node, prop.text, enclosingFuncId);
+      }
+    }
+
     // ── anonymous function with no named scope around it ─────────────────
     // Inside a named function, a callback's calls belong to that function
     // (enclosingFuncId passes through). Outside one, give it a located id.
@@ -573,6 +894,26 @@ function walkTSJS(rootNode, relPath, entities, edges) {
               walk(valueNode.child(j), funcId, enclosingClass);
             }
             walkedValues.add(valueNode.startIndex);
+          } else if (nameNode && valueNode && valueNode.type === 'call_expression') {
+            // `const scheduleEvents = pgTable('schedule_events', {...})` → table entity.
+            // [RULE] drizzle-table-entity-and-usage-edges
+            const builder = valueNode.childForFieldName('function').text;
+            const args = valueNode.childForFieldName('arguments');
+            const isTable = Object.prototype.hasOwnProperty.call(TABLE_BUILDERS, builder);
+            const isEnum = Object.prototype.hasOwnProperty.call(ENUM_BUILDERS, builder);
+            if (args && (isTable || isEnum)) {
+              const meta = isTable ? tableMeta(builder, args) : enumMeta(builder, args);
+              entities.push({
+                id: `${relPath}#${nameNode.text}@${decl.startPosition.row + 1}`,
+                name: nameNode.text,
+                type: meta.kind,
+                line: decl.startPosition.row + 1,
+                endLine: valueNode.endPosition.row + 1,
+                exported: isExp,
+                meta,
+              });
+              declRanges.push([valueNode.startIndex, valueNode.endIndex]);
+            }
           }
         }
       }

package/bin/gsd-t-graph-exclude.cjs

@@ -20,6 +20,13 @@
  *
  * A malformed file HALTS (throws): silently ignoring it would index exactly the
  * trees the user asked to keep out, with nothing saying so.
+ *
+ * DEFAULT exclude (no file needed): GSD-T's own tools, which `gsd-t update-all`
+ * copies into every project's bin/ (PROJECT_BIN_TOOLS in bin/gsd-t.js). They are
+ * not the project's code; indexed, they put GSD-T's functions into its who-calls.
+ * Not applied in GSD-T's own repo, where bin/ IS the application. The pattern is
+ * checked against PROJECT_BIN_TOOLS by test/graph-drizzle-tables.test.js.
+ * [RULE] graph-excludes-gsdt-copied-tools-by-default
  */
 
 const fs = require('fs');
@@ -27,6 +34,18 @@ const path = require('path');
 
 const EXCLUDE_FILE = path.join('.gsd-t', 'graph-exclude.json');
 const REGEX_SPECIALS = /[.+?^${}()|[\]\\]/g;
+const GSDT_TOOL_FILES = /^bin\/(gsd-t-[^/]+|archive-progress|cli-preflight|parallel-cli|parallel-cli-tee)\.cjs$/i;
+const GSDT_TOOL_DEFAULT = "bin/<GSD-T's copied tools: gsd-t-*.cjs, archive-progress.cjs, cli-preflight.cjs, parallel-cli*.cjs>";
+
+/** GSD-T's own source repo — its bin/ is the application, never excluded. */
+function isGsdtSourceRepo(projectRoot) {
+  const pkg = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkg)) return false;
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(pkg, 'utf8')); }
+  catch (e) { throw new Error(`package.json is not valid JSON (${e.message}) — cannot tell whether bin/ holds GSD-T's copied tools`); }
+  return parsed !== null && parsed.name === '@tekyzinc/gsd-t';
+}
 
 function toRegex(pattern) {
   const p = String(pattern).trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
@@ -60,7 +79,12 @@ function validateList(parsed) {
  */
 function loadGraphExcludes(projectRoot) {
   const file = path.join(projectRoot, EXCLUDE_FILE);
-  if (!fs.existsSync(file)) return { patterns: [], source: null, isExcluded: () => false };
+  const toolsExcluded = !isGsdtSourceRepo(projectRoot);
+  const defaults = toolsExcluded ? [GSDT_TOOL_DEFAULT] : [];
+  const isDefault = (rel) => toolsExcluded && GSDT_TOOL_FILES.test(rel);
+  if (!fs.existsSync(file)) {
+    return { patterns: [], defaults, source: null, isExcluded: (relPath) => isDefault(String(relPath).split(path.sep).join('/')) };
+  }
   let parsed;
   try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
   catch (e) { throw new Error(`${EXCLUDE_FILE} is not valid JSON (${e.message}) — fix it or delete it`); }
@@ -70,12 +94,13 @@ function loadGraphExcludes(projectRoot) {
   const regexes = parsed.exclude.map(toRegex).filter(Boolean);
   return {
     patterns: parsed.exclude,
+    defaults,
     source: EXCLUDE_FILE,
     isExcluded: (relPath) => {
       const rel = String(relPath).split(path.sep).join('/');
-      return regexes.some((r) => r.test(rel));
+      return isDefault(rel) || regexes.some((r) => r.test(rel));
     },
   };
 }
 
-module.exports = { loadGraphExcludes, EXCLUDE_FILE, _toRegex: toRegex };
+module.exports = { loadGraphExcludes, EXCLUDE_FILE, GSDT_TOOL_FILES, _toRegex: toRegex };

package/bin/gsd-t-graph-freshness.cjs

@@ -107,12 +107,13 @@ function walkTree(dir, results = []) {
   try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
   catch { return results; }
   for (const e of entries) {
-    if (e.name.startsWith('.') && e.name !== '.claude') {
-      if (shouldExcludeDir(e.name)) continue;
-    }
-    if (shouldExcludeDir(e.name)) continue;
     const full = path.join(dir, e.name);
     if (e.isDirectory()) {
+      // The skip list names DIRECTORIES, as in the indexer. Applied to file names
+      // it dropped `build-analytics.ts` / `build_guides.py` (prefix "build"),
+      // so every query deleted 7 indexed hilo files from the graph as "gone".
+      // [RULE] freshness-excludes-match-indexer-skipdirs
+      if (shouldExcludeDir(e.name)) continue;
       walkTree(full, results);
     } else if (e.isFile() && TRACKED_EXTS.has(path.extname(e.name))) {
       results.push(full);
@@ -290,6 +291,12 @@ function revalidateOneHopImporters(db, fileRel, op) {
       db.prepare(`DELETE FROM nodes WHERE id=? AND kind='FILE'`).run(fileRel);
       // Remove entity nodes belonging to this file
       db.prepare(`DELETE FROM nodes WHERE file=? AND kind != 'FILE'`).run(fileRel);
+      // …its call / table-usage edges (src is `file#fn`, not the bare file) and its
+      // files-table row. Left behind, a deleted or newly-excluded file stayed in
+      // `graph status` and was re-flagged as a DELETE on every query.
+      // [RULE] status-counts-files-table
+      db.prepare(`DELETE FROM edges WHERE src LIKE ?`).run(`${fileRel}#%`);
+      if (hasTable(db, 'files')) db.prepare(`DELETE FROM files WHERE file=?`).run(fileRel);
       return { revalidated: true, op: 'DELETE', file: fileRel };
     }
 

package/bin/gsd-t-graph-index.cjs

@@ -264,7 +264,8 @@ function buildSchema(db) {
       file         TEXT NOT NULL,
       name         TEXT,
       func_id      TEXT,
-      end_line     INTEGER
+      end_line     INTEGER,
+      meta         TEXT
     );
     CREATE TABLE IF NOT EXISTS edges (
       kind    TEXT    NOT NULL,
@@ -278,6 +279,18 @@ function buildSchema(db) {
     CREATE INDEX IF NOT EXISTS nodes_file      ON nodes(file);
   `);
   migrateEndLine(db);
+  migrateMeta(db);
+}
+
+/**
+ * Idempotent migration: add `nodes.meta` (JSON) — a table's SQL name + columns,
+ * an enum's values. NULL for functions/classes. [RULE] drizzle-table-entity-and-usage-edges
+ */
+function migrateMeta(db) {
+  const cols = db.prepare("PRAGMA table_info(nodes)").all();
+  if (!cols.some((c) => c.name === 'meta')) {
+    db.exec('ALTER TABLE nodes ADD COLUMN meta TEXT');
+  }
 }
 
 /**
@@ -313,11 +326,15 @@ function migrateEndLine(db) {
  */
 function getWriteStmts(db) {
   if (db.__m94WriteStmts) return db.__m94WriteStmts;
+  // A handle opened elsewhere (the freshness re-index opens the db without
+  // buildSchema) may point at an older graph — add the columns written below.
+  migrateEndLine(db);
+  migrateMeta(db);
   const stmts = {
     deleteNodes: db.prepare('DELETE FROM nodes WHERE file = ?'),
     deleteEdgesSrc: db.prepare("DELETE FROM edges WHERE src = ? OR src LIKE ? OR src = ?"),
     insFile: db.prepare('INSERT OR REPLACE INTO files (file, content_hash, tier, indexed_at) VALUES (?, ?, ?, ?)'),
-    insNode: db.prepare('INSERT OR REPLACE INTO nodes (id, kind, tier, content_hash, file, name, func_id, end_line) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'),
+    insNode: db.prepare('INSERT OR REPLACE INTO nodes (id, kind, tier, content_hash, file, name, func_id, end_line, meta) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'),
     insEdge: db.prepare('INSERT INTO edges (kind, src, dst, partial) VALUES (?, ?, ?, ?)'),
   };
   // db.transaction() wrapper is also created once (it closes over the stmts).
@@ -327,7 +344,8 @@ function getWriteStmts(db) {
     stmts.deleteEdgesSrc.run(file, `${file}#%`, file);
     stmts.insFile.run(file, hash, tier, now);
     for (const entity of entities) {
-      stmts.insNode.run(entity.id, entity.type || 'function', tier, hash, file, entity.name || null, entity.id, entity.endLine ?? null);
+      stmts.insNode.run(entity.id, entity.type || 'function', tier, hash, file, entity.name || null, entity.id, entity.endLine ?? null,
+        entity.meta === undefined ? null : JSON.stringify(entity.meta));
     }
     for (const edge of edges) {
       stmts.insEdge.run(edge.kind, edge.src, edge.dst, edge.partial ? 1 : 0);
@@ -459,6 +477,7 @@ function parse_and_put(absPath, relPath, options) {
     exported: e.exported,
     parentClass: e.parentClass,
     endLine: e.endLine ?? null,   // M98 — function end line for body-slice
+    ...(e.meta === undefined ? {} : { meta: e.meta }), // table / enum: SQL name, columns, values
   }));
 
   if (db) {
@@ -543,6 +562,9 @@ function build_index(repoRoot, options) {
   let errors = 0;
   const skippedFiles = [];
   const scipMissing = []; // files SCIP ran for but produced no document for
+  let tableCount = 0;
+  let enumCount = 0;
+  const tablesUnresolved = []; // [RULE] drizzle-table-shape-gap-named-never-skipped
 
   // Stream: parse + put each file one at a time (never accumulate the full set)
   for (const { absPath, relPath } of files) {
@@ -560,6 +582,11 @@ function build_index(repoRoot, options) {
         if (String(e.target || e.dst).startsWith('UNRESOLVED#')) callEdgesUnresolved++;
       }
       if (result.tier === 'tree-sitter-floor-SCIP-MISSING') scipMissing.push(relPath);
+      for (const ent of result.entities) {
+        if (ent.type === 'table') tableCount++;
+        if (ent.type === 'enum') enumCount++;
+        if (ent.meta && ent.meta.unresolved) tablesUnresolved.push({ file: relPath, name: ent.name, problems: ent.meta.unresolved });
+      }
       if (typeof onProgress === 'function') {
         onProgress({ file: relPath, tier: result.tier, fileCount, total: files.length });
       }
@@ -570,6 +597,20 @@ function build_index(repoRoot, options) {
     }
   }
 
+  // A full build leaves exactly the enumerated set: rows for a file that is gone
+  // or newly excluded (e.g. GSD-T's copied bin/ tools) are pruned, not kept.
+  // [RULE] status-counts-files-table
+  const enumerated = new Set(files.map((f) => f.relPath));
+  const stale = db.prepare('SELECT file FROM files').all().map((r) => r.file).filter((f) => !enumerated.has(f));
+  if (stale.length) {
+    const w = getWriteStmts(db);
+    const delFile = db.prepare('DELETE FROM files WHERE file = ?');
+    db.transaction(() => {
+      for (const f of stale) { w.deleteNodes.run(f); w.deleteEdgesSrc.run(f, `${f}#%`, f); delFile.run(f); }
+    })();
+    info(`Pruned ${stale.length} file(s) no longer in the project (deleted or excluded)`);
+  }
+
   // Record the skipped set + parse-success-rate so a query whose edges live in a
   // skipped file can return a coverage flag ('result may be incomplete — N files
   // unparsed') instead of a bare empty set that reads as authoritative truth.
@@ -619,8 +660,20 @@ function build_index(repoRoot, options) {
       `(tier tree-sitter-floor-SCIP-MISSING): ${shown}${scipMissing.length > 10 ? ', …' : ''}`);
   }
 
+  // A table whose declaration had a shape the extractor could not read (a
+  // computed name, a spread of columns, a non-literal reference) is still an
+  // entity — but its columns or FKs are incomplete. Named every build, loud.
+  if (tablesUnresolved.length) {
+    warn(`${tablesUnresolved.length} table/enum declaration(s) only partly read — columns or foreign keys incomplete:`);
+    for (const t of tablesUnresolved.slice(0, 20)) warn(`  ${t.file} ${t.name}: ${t.problems.join('; ')}`);
+    if (tablesUnresolved.length > 20) warn(`  … ${tablesUnresolved.length - 20} more`);
+  }
+
   return {
     fileCount,
+    tableCount,
+    enumCount,
+    tablesUnresolved,
     entityCount,
     edgeCount,
     tier: { floor: tierFloor, upgraded: tierUpgraded, partial: tierPartial },
@@ -683,6 +736,7 @@ if (require.main === module) {
     info(`Call edges unresolved: ${result.callEdgesUnresolved} of ${result.callEdges} ` +
       `(${(100 * result.callEdgesUnresolved / result.callEdges).toFixed(1)}% — library calls such as console.log never resolve)`);
   }
+  good(`Database tables: ${result.tableCount}, enums: ${result.enumCount}`);
   if (result.errors > 0) warn(`${result.errors} files had parse errors (skipped)`);
 
   const envelope = {
@@ -695,6 +749,9 @@ if (require.main === module) {
     edgeCount: result.edgeCount,
     tier: result.tier,
     scipMissingCount: result.scipMissing.length,
+    tableCount: result.tableCount,
+    enumCount: result.enumCount,
+    tablesUnresolved: result.tablesUnresolved,
     errors: result.errors,
     durationMs: result.durationMs,
   };

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'}
@@ -380,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;
@@ -395,7 +406,12 @@ function buildIndex(records, skippedFiles) {
     // 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,
@@ -419,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]) });
+          }
         }
       }
     }
@@ -433,6 +456,8 @@ function buildIndex(records, skippedFiles) {
     nameMatchedCallGraph: buildNameMatchedCallGraph(forwardCallEdges, funcEntities, fileTier),
     forwardCallEdges,
     funcEntities,
+    tableEntities,
+    tableUses,
     allFiles,
     fileTier,
     tier: dominantTier,
@@ -546,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();
 
@@ -663,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
@@ -693,10 +726,16 @@ function loadSqliteStore(dbPath) {
     // 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);
-        if (r.tier && byFile.has(f) && !byFile.get(f).tier) byFile.get(f).tier = r.tier;
+        const fr = rec(f);
+        if (r.tier && !fr.tier) fr.tier = r.tier;
       }
     }
     db.close();
@@ -805,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))) };
   }
 }
 
@@ -907,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) {
@@ -922,6 +965,16 @@ function queryWhoCalls(index, identity) {
   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) ────────────────────────────────────────────────────────
 
 /**
@@ -973,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.
@@ -1032,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 ──────────────────────────────────────────────────────
 
 /**
@@ -1067,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)
@@ -1135,6 +1221,171 @@ function queryBlastRadius(index, target) {
   };
 }
 
+// ─── 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 ────────────────────────────────────────────────────────────
 
 /**
@@ -1159,10 +1410,59 @@ function queryStatus(index, storePath) {
     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
@@ -1542,6 +1842,10 @@ module.exports = {
   queryBody,
   queryBlastRadius,
   queryStatus,
+  queryTable,
+  queryWhoUses,
+  resolveTable,
+  suggestExcludes,
   // D9 additions
   queryCluster,
   queryDeadCode,
@@ -1637,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) {
@@ -1705,6 +2010,7 @@ if (require.main === module) {
     }
     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") {
@@ -1755,11 +2061,21 @@ 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, nameMatched } = queryBlastRadius(index, target);
+    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);
     }
@@ -1771,7 +2087,20 @@ if (require.main === module) {
     const statusData = queryStatus(index, storePath);
     // 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 } });
+    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);

package/bin/gsd-t.js

@@ -4766,7 +4766,11 @@ function doGraphStatus() {
     return;
   }
   success(`Graph index: ${envelope.fileCount || 0} files`);
-  if (envelope.tier) info(`Tier: ${envelope.tier}`);
+  // Per-tier file counts (what the build reported), then the worst tier present.
+  const tiers = envelope.tiers ? Object.entries(envelope.tiers).sort((a, b) => b[1] - a[1]) : [];
+  if (tiers.length) info(`Tiers: ${tiers.map(([t, n]) => `${t} ${n}`).join(" · ")}`);
+  if (envelope.tier) info(`Lowest tier present: ${envelope.tier}`);
+  if (envelope.tableCount || envelope.enumCount) info(`Database tables: ${envelope.tableCount}, enums: ${envelope.enumCount} (gsd-t graph table <name> · who-uses <name>)`);
   // [RULE] scip-missing-file-detected-never-silent — files the SCIP indexer never
   // produced a document for: their call edges stay unresolved, so who-calls is blind there.
   const miss = envelope.scipMissing;
@@ -4780,6 +4784,13 @@ function doGraphStatus() {
   } else {
     info("Excludes: none (add folders to .gsd-t/graph-exclude.json — { \"exclude\": [\"design/\"] })");
   }
+  if (ex && ex.defaults && ex.defaults.length) info(`Excluded by default: ${ex.defaults.join(", ")}`);
+  // Suggestions only — a folder is never dropped from the graph without the user listing it.
+  const sug = envelope.excludeSuggestions;
+  if (sug && sug.length) {
+    info(`Folders that may not be the app (${sug[0].reason}) — add to .gsd-t/graph-exclude.json if so:`);
+    for (const x of sug.slice(0, 15)) log(`      ${x.folder}  (${x.files} files)`);
+  }
   if (envelope.storeSize !== undefined) info(`Store size: ${envelope.storeSize} bytes`);
   if (envelope.detail) log(JSON.stringify(envelope, null, 2));
 }
@@ -4793,7 +4804,7 @@ function doGraphQuery(args) {
   const verb = args[0];
   if (!verb) {
     error("Usage: gsd-t graph query <verb> [target]");
-    info("Verbs: status, who-imports, who-calls, blast-radius, cluster, dead-code, orphan, dangling, test-impl");
+    info("Verbs: status, who-imports, who-calls, body, blast-radius, who-uses [--writes|--reads], table, cluster, dead-code, orphan, dangling, test-impl");
     return;
   }
   const envelope = _graphQueryCli([verb].concat(args.slice(1)));
@@ -4818,6 +4829,9 @@ function doGraph(args) {
     case "who-calls":     { const e = _graphQueryCli(["who-calls",   args[1] || ""]); log(JSON.stringify(e, null, 2)); break; }
     case "blast-radius":  { const e = _graphQueryCli(["blast-radius", args[1] || ""]); log(JSON.stringify(e, null, 2)); break; }
     case "body":          { const e = _graphQueryCli(["body",         args[1] || ""]); log(JSON.stringify(e, null, 2)); break; }
+    // Database tables (Drizzle pgTable/mysqlTable/sqliteTable + pgEnum).
+    case "who-uses":      { const e = _graphQueryCli(["who-uses"].concat(args.slice(1))); log(JSON.stringify(e, null, 2)); break; }
+    case "table":         { const e = _graphQueryCli(["table",        args[1] || ""]); log(JSON.stringify(e, null, 2)); break; }
     case "tasks":         doGraphTaskOutput(args[1] || "table"); break;
     case "metrics":       { // M99 D3-T2: append-only arm — rollup the telemetry ledger
       const _metricsRollup = require("./gsd-t-graph-metrics-rollup.cjs");
@@ -4866,7 +4880,7 @@ function doGraph(args) {
     }
     default:
       error(`Unknown graph subcommand: ${sub}`);
-      info("Usage: gsd-t graph [index|status|query|who-imports|who-calls|blast-radius|body|tasks|metrics|wiring-log]");
+      info("Usage: gsd-t graph [index|status|query|who-imports|who-calls|blast-radius|body|who-uses|table|tasks|metrics|wiring-log]");
       info("       gsd-t graph --output json|table   (task DAG)");
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.23.10",
+  "version": "5.24.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code \u2014 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-graph-search-guard.js

@@ -281,8 +281,47 @@ function buildNoGraphReason(found, cls) {
   ].join("\n");
 }
 
+// --- Database-table questions ---------------------------------------------
+//
+// `grep -rn "insert(scheduleEvents"` or `grep pgTable` asks about a database
+// table. The graph indexes Drizzle tables (who-uses / table / blast-radius), so
+// the block names those verbs and the table instead of sending the caller to
+// who-calls, which has no answer for a table. [RULE] search-guard-routes-table-questions
+
+const TABLE_BUILDER_SHAPE = /\b(pgTable|mysqlTable|sqliteTable|pgEnum)\b/;
+const TABLE_OP_SHAPE = /\.?\b(from|innerJoin|leftJoin|rightJoin|fullJoin|insert|update|delete|references)\s*\\?\(\s*(?:\\?\(\s*\\?\)\s*=>\s*)?([A-Za-z_$][\w$]*)/;
+const QUERY_API_SHAPE = /\bquery\\?\.([A-Za-z_$][\w$]*)/;
+
+/** → { table: name|null, why } when the pattern reads as a table question; else null. */
+function tableQuestion(pattern) {
+  const p = String(pattern);
+  const op = TABLE_OP_SHAPE.exec(p);
+  if (op) return { table: op[2], why: "a Drizzle table operation (" + op[1] + ")" };
+  const q = QUERY_API_SHAPE.exec(p);
+  if (q && /\bdb\b|\btx\b/.test(p)) return { table: q[1], why: "a Drizzle relational query (db.query.<table>)" };
+  if (TABLE_BUILDER_SHAPE.test(p)) return { table: null, why: "a Drizzle table declaration" };
+  return null;
+}
+
+function tableRouting(tq) {
+  const t = tq.table === null ? "<table>" : tq.table;
+  return [
+    "This reads as a database-table question (" + tq.why + "). The graph indexes tables:",
+    "",
+    "  gsd-t graph who-uses " + t + "            - every function / route / method that uses it",
+    "  gsd-t graph who-uses " + t + " --writes   - only inserts / updates / deletes (--reads for reads)",
+    "  gsd-t graph table " + t + "               - its columns and foreign keys, both directions",
+    "  gsd-t graph blast-radius " + t + "        - tables that reference it + the code that uses it",
+    "",
+    "A table is found by its code name (scheduleEvents) or its SQL name (schedule_events).",
+    "",
+  ];
+}
+
 function buildStructuralReason(found, cls) {
   const lines = [];
+  const tq = tableQuestion(found.pattern);
+  if (tq !== null) lines.push(...tableRouting(tq));
 
   const symbol = cls.symbol === null ? found.pattern : cls.symbol;
   const verb = cls.verb === null ? "who-calls" : cls.verb;
@@ -298,6 +337,7 @@ function buildStructuralReason(found, cls) {
     "  gsd-t graph " + verb + " " + symbol,
     "",
     "Other verbs: who-imports, who-calls, defines, blast-radius, body.",
+    "A database table (Drizzle)? gsd-t graph who-uses " + symbol + "  /  gsd-t graph table " + symbol,
     "",
     "If this really is a text search - a phrase in prose, a key in config, a string in a",
     "document - scope it to the files the graph does not index, and it will run:",
@@ -308,7 +348,8 @@ function buildStructuralReason(found, cls) {
 }
 
 function buildUnclearReason(found, cls) {
-  return [
+  const tq = tableQuestion(found.pattern);
+  return (tq === null ? [] : tableRouting(tq)).concat([
     "This search could be asking about code structure, and that has to be settled before",
     "it runs - a guess in either direction is how the graph rule stopped having teeth.",
     "",
@@ -320,9 +361,12 @@ function buildUnclearReason(found, cls) {
     "  Structure (who calls, who imports, where defined):",
     "    gsd-t graph who-calls <symbol>",
     "",
+    "  A database table (who reads or writes it, its columns and foreign keys):",
+    "    gsd-t graph who-uses <table>   /   gsd-t graph table <table>",
+    "",
     "  Text in files the graph does not index (.md, .json, .sql, config, prose):",
     "    add --include='*.md' (or the right extensions) and run it again",
-  ].join("\n");
+  ]).join("\n");
 }