@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/storage.ts

@@ -0,0 +1,159 @@
+// F074.3 — Lens artifact storage adapter.
+//
+// Screenshots + diff PNGs are bytes; they don't belong in SQLite. This
+// adapter abstracts "put / get / delete bytes by key" behind two backends:
+//
+//   - local  (default) : a directory on the daemon machine. Zero config —
+//                        the MVP + dev reality (the daemon is on Christian's
+//                        Mac; the SPA fetches artifact bytes from the daemon's
+//                        own HTTP, the same way FleetTemplatesSection already
+//                        talks to 127.0.0.1:7475).
+//   - tigris (opt-in)  : S3-compatible durable storage via Bun's native
+//                        S3Client. Enabled when LENS_TIGRIS_BUCKET + creds are
+//                        in the daemon env. Region is 'auto' (Tigris is global;
+//                        the bucket itself is created in arn per project policy).
+//
+// Keys are POSIX-style paths, e.g. "<project>/runs/<id>.png". The backend is
+// chosen once at construction from env; callers never branch on it.
+
+import { S3Client } from 'bun';
+import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export interface LensStorage {
+  readonly backend: 'local' | 'tigris';
+  put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+  get(key: string): Promise<Buffer | null>;
+  delete(key: string): Promise<void>;
+}
+
+class LocalDirStorage implements LensStorage {
+  readonly backend = 'local' as const;
+  constructor(private readonly root: string) {}
+
+  private path(key: string): string {
+    return join(this.root, key);
+  }
+
+  async put(key: string, bytes: Buffer): Promise<void> {
+    const p = this.path(key);
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, bytes);
+  }
+
+  async get(key: string): Promise<Buffer | null> {
+    try {
+      return await readFile(this.path(key));
+    } catch {
+      return null;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await rm(this.path(key), { force: true });
+  }
+}
+
+class TigrisStorage implements LensStorage {
+  readonly backend = 'tigris' as const;
+  constructor(private readonly client: S3Client) {}
+
+  async put(key: string, bytes: Buffer, contentType = 'image/png'): Promise<void> {
+    await this.client.write(key, bytes, { type: contentType });
+  }
+
+  async get(key: string): Promise<Buffer | null> {
+    try {
+      const buf = await this.client.file(key).arrayBuffer();
+      return Buffer.from(buf);
+    } catch {
+      return null;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.delete(key);
+  }
+}
+
+export interface StorageEnv {
+  LENS_TIGRIS_BUCKET?: string;
+  LENS_TIGRIS_ENDPOINT?: string;
+  AWS_ACCESS_KEY_ID?: string;
+  AWS_SECRET_ACCESS_KEY?: string;
+}
+
+/** Build the storage backend. Tigris when a bucket + creds are present in
+ *  env; otherwise a local directory under the daemon's app-support dir. */
+export function createStorage(localRoot: string, env: StorageEnv = process.env as unknown as StorageEnv): LensStorage {
+  const bucket = env.LENS_TIGRIS_BUCKET;
+  const accessKeyId = env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+  if (bucket && accessKeyId && secretAccessKey) {
+    const client = new S3Client({
+      bucket,
+      accessKeyId,
+      secretAccessKey,
+      // Fly Tigris default endpoint; overridable for other S3-compatible stores.
+      endpoint: env.LENS_TIGRIS_ENDPOINT ?? 'https://fly.storage.tigris.dev',
+      region: 'auto',
+    });
+    return new TigrisStorage(client);
+  }
+  return new LocalDirStorage(localRoot);
+}
+
+/** Conventional artifact keys — one place so runs + baselines + the HTTP
+ *  surface never disagree on layout. */
+export const artifactKeys = {
+  run: (project: string, runId: string) => `${project}/runs/${runId}.png`,
+  diff: (project: string, runId: string) => `${project}/runs/${runId}.diff.png`,
+  baseline: (project: string, baselineKey: string) =>
+    `${project}/baselines/${encodeURIComponent(baselineKey)}.png`,
+  // F094.3 — content-addressed per-version baseline artifact (never overwritten).
+  baselineVersion: (project: string, baselineKey: string, versionNo: number) =>
+    `${project}/baselines/${encodeURIComponent(baselineKey)}/v${versionNo}.png`,
+  // F082 — per-step screenshot of a flow run.
+  flowStep: (project: string, flowRunId: string, stepIndex: number) =>
+    `${project}/flows/${flowRunId}/step-${stepIndex}.png`,
+  // F255.5 — the whole driven run as a video, alongside its step stills.
+  flowVideo: (project: string, flowRunId: string) => `${project}/flows/${flowRunId}/run.webm`,
+  // F074.63 — a vector export (PDF). Its own prefix, not runs/: an export is not
+  // a capture, carries no baseline and must never be diffed against one.
+  exportDoc: (project: string, exportId: string, ext: string) =>
+    `${project}/exports/${exportId}.${ext}`,
+};
+
+/** F074.63 — what to serve a stored artifact as.
+ *
+ *  This map replaces a two-branch guess that defaulted everything-not-.webm to
+ *  image/png. That default was already wrong once (F255.5, video) and would be
+ *  wrong again for every format added after — and the failure is silent: the
+ *  browser gets a PDF labelled as a PNG and simply cannot open it. For an export
+ *  whose entire purpose is to be handed to a customer's graphic designer, an
+ *  un-openable file is indistinguishable from no feature at all. */
+export function artifactContentType(key: string): string {
+  const ext = key.toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? '';
+  switch (ext) {
+    case 'pdf':
+      return 'application/pdf';
+    case 'webm':
+      return 'video/webm';
+    // NO 'svg' BRANCH, and its absence is the point. /lens/artifact is
+    // un-authenticated on loopback, so a file served as image/svg+xml executes
+    // its own script in the daemon's origin the moment anyone opens it directly
+    // — and that origin can drive the browser, read the project store and reach
+    // every other /lens route. Nothing in Lens writes an .svg today, so the
+    // branch bought nothing and widened that. An .svg falls through to
+    // octet-stream below: it downloads intact and runs nothing.
+    case 'jpg':
+    case 'jpeg':
+      return 'image/jpeg';
+    case 'png':
+      return 'image/png';
+    default:
+      // Not a guess dressed as a fact: an unknown type is served as opaque bytes
+      // so a browser downloads it intact rather than mis-rendering it as an image.
+      return 'application/octet-stream';
+  }
+}

package/src/store.ts

@@ -0,0 +1,267 @@
+// F074.3 — Lens runs + baselines data layer.
+//
+// Ties a verify result to persistence: screenshot/diff BYTES go to the
+// storage adapter; the run METADATA goes to the daemon's SQLite. Baseline
+// approval promotes a stored run screenshot into the baseline slot for its
+// surface key (one baseline per project_slug + baseline_key).
+//
+// Everything is hard-scoped to project_slug — a project's runs/baselines are
+// never visible to another project.
+
+import type { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+import type { LensRunRow, LensBaselineRow, LensBaselineVersionRow } from './schema.ts';
+import { artifactKeys, type LensStorage } from './storage.ts';
+import { enqueueArtifacts } from './artifact-uploads.ts';
+import type { VerifyResult } from './verify.ts';
+
+export interface RecordRunInput {
+  project_slug: string;
+  surface_key?: string | null;
+}
+
+/** Persist a verify run: store screenshot (+ diff PNG) bytes, insert the
+ *  metadata row. Returns the new run id. */
+export async function recordRun(
+  db: Database,
+  storage: LensStorage,
+  result: VerifyResult,
+  input: RecordRunInput,
+): Promise<LensRunRow> {
+  const id = randomUUID();
+  const now = Date.now();
+  const project = input.project_slug;
+
+  let artifactKey: string | null = null;
+  let diffArtifactKey: string | null = null;
+  if (result.screenshot) {
+    artifactKey = artifactKeys.run(project, id);
+    await storage.put(artifactKey, result.screenshot);
+  }
+  if (result.diff?.diffPng) {
+    diffArtifactKey = artifactKeys.diff(project, id);
+    await storage.put(diffArtifactKey, result.diff.diffPng);
+  }
+  // F276.1 — the capture path needs this as much as the flow path. Christian's
+  // complaint was about Lens images generally, and 2410 of the 6588 files on disk
+  // are capture runs; hooking only flows would have fixed the half I happened to
+  // be working on and left the other half invisible on his phone.
+  enqueueArtifacts(db, project, [artifactKey, diffArtifactKey]);
+
+  const row: LensRunRow = {
+    id,
+    project_slug: project,
+    surface_key: input.surface_key ?? result.selector ?? null,
+    url: result.url,
+    mode: result.mode,
+    selector: result.selector,
+    status: result.status,
+    reason: result.reason,
+    diff_ratio: result.diff?.diffRatio ?? null,
+    artifact_key: artifactKey,
+    diff_artifact_key: diffArtifactKey,
+    dom_hash: result.domHash,
+    assert_pass: result.assertResult ? (result.assertResult.pass ? 1 : 0) : null,
+    assert_detail_json: result.assertResult ? JSON.stringify(result.assertResult.detail ?? null) : null,
+    console_json: JSON.stringify(result.console),
+    network_json: JSON.stringify(result.network),
+    page_errors_json: JSON.stringify(result.pageErrors),
+    width: result.width,
+    height: result.height,
+    duration_ms: result.durationMs,
+    critic_json: result.critic ? JSON.stringify(result.critic) : null,
+    created_at: now,
+    build: result.build ?? null,
+  };
+
+  db.prepare(
+    `INSERT INTO lens_runs (
+      id, project_slug, surface_key, url, mode, selector, status, reason,
+      diff_ratio, artifact_key, diff_artifact_key, dom_hash, assert_pass,
+      assert_detail_json, console_json, network_json, page_errors_json,
+      width, height, duration_ms, critic_json, created_at, build
+    ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+  ).run(
+    row.id, row.project_slug, row.surface_key, row.url, row.mode, row.selector,
+    row.status, row.reason, row.diff_ratio, row.artifact_key, row.diff_artifact_key,
+    row.dom_hash, row.assert_pass, row.assert_detail_json, row.console_json,
+    row.network_json, row.page_errors_json, row.width, row.height, row.duration_ms,
+    row.critic_json, row.created_at, row.build ?? null,
+  );
+
+  return row;
+}
+
+export interface ListRunsFilter {
+  status?: string;
+  surface_key?: string;
+  limit?: number;
+}
+
+export function listRuns(db: Database, projectSlug: string, filter: ListRunsFilter = {}): LensRunRow[] {
+  const clauses = ['project_slug = ?'];
+  const params: (string | number)[] = [projectSlug];
+  if (filter.status) {
+    clauses.push('status = ?');
+    params.push(filter.status);
+  }
+  if (filter.surface_key) {
+    clauses.push('surface_key = ?');
+    params.push(filter.surface_key);
+  }
+  const limit = Math.min(Math.max(filter.limit ?? 50, 1), 500);
+  params.push(limit);
+  return db
+    .query(`SELECT * FROM lens_runs WHERE ${clauses.join(' AND ')} ORDER BY created_at DESC LIMIT ?`)
+    .all(...params) as LensRunRow[];
+}
+
+export function getRun(db: Database, id: string): LensRunRow | null {
+  return (db.query('SELECT * FROM lens_runs WHERE id = ?').get(id) as LensRunRow | null) ?? null;
+}
+
+export function getBaseline(db: Database, projectSlug: string, baselineKey: string): LensBaselineRow | null {
+  return (
+    (db
+      .query('SELECT * FROM lens_baselines WHERE project_slug = ? AND baseline_key = ?')
+      .get(projectSlug, baselineKey) as LensBaselineRow | null) ?? null
+  );
+}
+
+export function listBaselines(db: Database, projectSlug: string): LensBaselineRow[] {
+  return db
+    .query('SELECT * FROM lens_baselines WHERE project_slug = ? ORDER BY baseline_key')
+    .all(projectSlug) as LensBaselineRow[];
+}
+
+/** F089 — unapprove: drop a baseline (row + artifact bytes) so its surface goes
+ *  back to no-baseline (smoke). Lets a data-drift surface that was wrongly
+ *  approved stop diffing — approve was previously one-way. Idempotent. */
+export async function deleteBaseline(
+  db: Database,
+  storage: LensStorage,
+  projectSlug: string,
+  baselineKey: string,
+): Promise<boolean> {
+  const row = getBaseline(db, projectSlug, baselineKey);
+  if (!row) return false;
+  await storage.delete(row.artifact_key).catch(() => {});
+  db.prepare('DELETE FROM lens_baselines WHERE id = ?').run(row.id);
+  return true;
+}
+
+/** Load the baseline PNG bytes for a surface, if a baseline is approved.
+ *  verify() calls this to auto-supply `baseline` when only a key is given. */
+export async function getBaselineBytes(
+  db: Database,
+  storage: LensStorage,
+  projectSlug: string,
+  baselineKey: string,
+): Promise<Buffer | null> {
+  const row = getBaseline(db, projectSlug, baselineKey);
+  if (!row) return null;
+  return storage.get(row.artifact_key);
+}
+
+export async function getArtifact(storage: LensStorage, key: string): Promise<Buffer | null> {
+  return storage.get(key);
+}
+
+/** F094.3 — list a surface's approved baseline versions, newest first. */
+export function listBaselineVersions(
+  db: Database,
+  projectSlug: string,
+  baselineKey: string,
+): LensBaselineVersionRow[] {
+  return db
+    .query(
+      'SELECT * FROM lens_baseline_versions WHERE project_slug = ? AND baseline_key = ? ORDER BY version_no DESC',
+    )
+    .all(projectSlug, baselineKey) as LensBaselineVersionRow[];
+}
+
+/** Promote a run's screenshot to the baseline for its surface. F094.3: this is
+ *  now APPEND-ONLY — each approve writes a NEW content-addressed version
+ *  (baselines/<key>/v<n>.png) and advances lens_baselines.current_version_id; the
+ *  previous version's bytes are never overwritten, so the visual history (+ revert)
+ *  survives. lens_baselines.artifact_key always mirrors the current version, so
+ *  verify()/getBaselineBytes() are unchanged. One baseline row per (project, key). */
+export async function promoteBaseline(
+  db: Database,
+  storage: LensStorage,
+  runId: string,
+  baselineKeyOverride?: string,
+): Promise<LensBaselineRow> {
+  const run = getRun(db, runId);
+  if (!run) throw new Error(`run not found: ${runId}`);
+  if (!run.artifact_key) throw new Error(`run ${runId} has no screenshot to promote`);
+  const baselineKey = baselineKeyOverride ?? run.surface_key;
+  if (!baselineKey) {
+    throw new Error(`run ${runId} has no surface_key — pass an explicit baseline key`);
+  }
+
+  const bytes = await storage.get(run.artifact_key);
+  if (!bytes) throw new Error(`run ${runId} artifact missing in storage: ${run.artifact_key}`);
+
+  const now = Date.now();
+  // Next version number for this surface (1 for a brand-new baseline).
+  const maxRow = db
+    .query(
+      'SELECT MAX(version_no) AS n FROM lens_baseline_versions WHERE project_slug = ? AND baseline_key = ?',
+    )
+    .get(run.project_slug, baselineKey) as { n: number | null };
+  const versionNo = (maxRow?.n ?? 0) + 1;
+
+  // Content-addressed per-version artifact — never overwrites a prior version.
+  const versionKey = artifactKeys.baselineVersion(run.project_slug, baselineKey, versionNo);
+  await storage.put(versionKey, bytes);
+
+  const versionId = randomUUID();
+  db.prepare(
+    `INSERT INTO lens_baseline_versions
+      (id, project_slug, baseline_key, version_no, artifact_key, width, height,
+       approved_from_run_id, commit_sha, note, approved_at)
+     VALUES (?,?,?,?,?,?,?,?,NULL,NULL,?)`,
+  ).run(versionId, run.project_slug, baselineKey, versionNo, versionKey, run.width, run.height, run.id, now);
+
+  // Point the baseline at the new version (current artifact = this version).
+  const existing = getBaseline(db, run.project_slug, baselineKey);
+  if (existing) {
+    db.prepare(
+      `UPDATE lens_baselines SET artifact_key = ?, width = ?, height = ?,
+        approved_from_run_id = ?, current_version_id = ?, updated_at = ? WHERE id = ?`,
+    ).run(versionKey, run.width, run.height, run.id, versionId, now, existing.id);
+  } else {
+    db.prepare(
+      `INSERT INTO lens_baselines (
+        id, project_slug, baseline_key, artifact_key, width, height,
+        approved_from_run_id, current_version_id, created_at, updated_at
+      ) VALUES (?,?,?,?,?,?,?,?,?,?)`,
+    ).run(randomUUID(), run.project_slug, baselineKey, versionKey, run.width, run.height, run.id, versionId, now, now);
+  }
+  return getBaseline(db, run.project_slug, baselineKey)!;
+}
+
+/** F094.3 — revert a surface's active baseline to a prior version. Re-points
+ *  lens_baselines at that version's artifact WITHOUT creating a new version or
+ *  deleting any history. Throws if the version doesn't exist. */
+export function revertBaseline(
+  db: Database,
+  projectSlug: string,
+  baselineKey: string,
+  versionNo: number,
+): LensBaselineRow {
+  const version = db
+    .query(
+      'SELECT * FROM lens_baseline_versions WHERE project_slug = ? AND baseline_key = ? AND version_no = ?',
+    )
+    .get(projectSlug, baselineKey, versionNo) as LensBaselineVersionRow | null;
+  if (!version) throw new Error(`no version ${versionNo} for baseline "${baselineKey}"`);
+  const baseline = getBaseline(db, projectSlug, baselineKey);
+  if (!baseline) throw new Error(`no baseline "${baselineKey}" to revert`);
+  db.prepare(
+    `UPDATE lens_baselines SET artifact_key = ?, width = ?, height = ?,
+      approved_from_run_id = ?, current_version_id = ?, updated_at = ? WHERE id = ?`,
+  ).run(version.artifact_key, version.width, version.height, version.approved_from_run_id, version.id, Date.now(), baseline.id);
+  return getBaseline(db, projectSlug, baselineKey)!;
+}

package/src/swallowed-errors.ts

@@ -0,0 +1,252 @@
+// F074.32 — find code that takes the data and throws the error away.
+//
+// The bug it exists for (fd-sundhed, 2026-08-04, production): a query asked for
+// three columns that did not exist in prod, the database returned an error, the
+// code destructured only `{ data }` and dropped `error`, `data` came back null,
+// and the page answered notFound(). A TECHNICAL FAILURE DISGUISED ITSELF AS AN
+// ACCESS DENIAL — and the one user who should have had access got a 404.
+// Typecheck could not see it: the generated types file claimed the columns
+// existed. A generated types file is not truth about production.
+//
+// WHY IT CALIBRATES INSTEAD OF MATCHING A LIST. The naive rule — flag every
+// `const { data } = await …` with no `error` — is unusable: axios and friends
+// legitimately return `{ data }` and nothing else, so it would flag most of a
+// codebase. The tempting fix is a hardcoded list of clients that DO return
+// `{ data, error }`. That is the exact anti-pattern fd-sundhed named the same
+// day, after their own guard missed 6 of 10 mail paths: "a list of the field
+// names you thought of is a list of what you already knew."
+//
+// So the repo's OWN dominant usage is the specification. Group call sites by the
+// callee they await; a site that drops `error` is only a finding when other
+// sites awaiting THE SAME callee do read it. That is evidence from the codebase
+// in front of us, not a guess about the world — it needs no maintenance, and it
+// works on a repo we have never seen.
+//
+// Deliberately NOT required: that the same function then returns null/404. The
+// null branch and the notFound() lived in DIFFERENT functions in the real bug,
+// so a rule spanning both finds nothing. Taking the data and discarding the
+// error is the defect on its own, whatever the caller does with it.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { resolveSandboxedPath } from './sandbox.ts';
+
+const SOURCE_EXTS = new Set(['.tsx', '.jsx', '.ts', '.js', '.vue', '.svelte', '.astro']);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', '.turbo', 'coverage', '.cache',
+  // `.claude/worktrees` holds full COPIES of the repo, one per agent worktree.
+  // Scanning them counted the same file up to a dozen times and turned a real
+  // answer into an unusable number (measured on fd-sundhed: 468 findings, most
+  // of them the same lines over and over).
+  '.claude',
+]);
+
+/** `const { … } = await <expr>` — the destructuring and the awaited expression.
+ *  `let`/`var` count too; a bare `({ data } = await …)` reassignment is rare
+ *  enough to skip rather than complicate the pattern.
+ *
+ *  The expression window crosses NEWLINES on purpose. A fluent client is almost
+ *  always wrapped:
+ *
+ *      const { data: profile } = await supabase
+ *        .from('profiles')
+ *        .select('*')
+ *
+ *  Stopping at the newline made every one of those group under the bare
+ *  identifier `supabase`, which collapsed 98 unrelated call sites into one
+ *  bucket and made the calibration meaningless (measured on fd-sundhed). Only
+ *  the HEAD of the window is ever read, so the generous bound is harmless. */
+const DESTRUCTURE_AWAIT_RE = /\b(?:const|let|var)\s*\{([^}]*)\}\s*=\s*await\s+/g;
+
+/** How far past `await` we look for the callee. Read from the source AFTER the
+ *  match rather than captured by it — a capture that wide consumes the next
+ *  statements, so consecutive call sites vanish (they did, in the first cut). */
+const EXPR_WINDOW = 200;
+
+export interface SwallowedErrorSite {
+  file: string;
+  line: number;
+  /** Normalised head of the awaited expression, e.g. `supabase.from`. */
+  callee: string;
+  binds_error: boolean;
+  snippet: string;
+}
+
+export interface SwallowedErrorFinding extends SwallowedErrorSite {
+  /** How many sites awaiting the SAME callee DO read the error — the evidence
+   *  that the field exists and that this site is the odd one out. */
+  peers_reading_error: number;
+}
+
+/**
+ * Property names bound by a destructuring pattern, by PROPERTY not by local name.
+ *
+ * `{ data: roster, error }` → ['data', 'error']. Matching the bound name instead
+ * would miss the real bug, which was written `const { data: roster } = await …`
+ * (fd-sundhed's first sharpening). Nested/rest patterns are ignored; this only
+ * needs the top level.
+ */
+export function boundProps(inner: string): string[] {
+  const props: string[] = [];
+  // Split on commas that are not inside nested braces/brackets/parens.
+  let depth = 0;
+  let cur = '';
+  for (const ch of inner) {
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') depth--;
+    if (ch === ',' && depth === 0) {
+      props.push(cur);
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  props.push(cur);
+  return props
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => {
+      if (p.startsWith('...')) return '';
+      // `data: roster` / `data : roster` → data ; `data = fallback` → data
+      const name = p.split(':')[0]!.split('=')[0]!.trim();
+      return /^[A-Za-z_$][\w$]*$/.test(name) ? name : '';
+    })
+    .filter(Boolean);
+}
+
+/**
+ * The awaited expression's identity, so sites can be grouped.
+ *
+ * `supabase.from('x').select('y').single()` → `supabase.from`
+ * `db.query(...)`                          → `db.query`
+ * `fetchRoster(id)`                        → `fetchRoster`
+ *
+ * Two segments is the sweet spot: one segment lumps every method on a client
+ * together, three splits `.select()` from `.single()` and destroys the grouping
+ * that makes the calibration work.
+ */
+export function calleeKey(expr: string): string {
+  // Whitespace-tolerant: the dot is routinely on the next line.
+  const m = expr
+    .trim()
+    .match(/^([A-Za-z_$][\w$]*)\s*(?:(\??\.)\s*([A-Za-z_$][\w$]*))?/);
+  if (!m) return '';
+  return m[3] ? `${m[1]}.${m[3]}` : m[1]!;
+}
+
+/** Every `const {…} = await …` site in one file. */
+export function sitesInFile(content: string, rel: string): SwallowedErrorSite[] {
+  const out: SwallowedErrorSite[] = [];
+  for (const m of content.matchAll(DESTRUCTURE_AWAIT_RE)) {
+    const props = boundProps(m[1] ?? '');
+    if (!props.includes('data')) continue;
+    const start = m.index ?? 0;
+    const expr = content.slice(start + m[0].length, start + m[0].length + EXPR_WINDOW);
+    const callee = calleeKey(expr);
+    if (!callee) continue;
+    out.push({
+      file: rel,
+      line: content.slice(0, start).split('\n').length,
+      callee,
+      binds_error: props.includes('error'),
+      snippet: `${m[0]}${expr.slice(0, 60)}`.replace(/\s+/g, ' ').trim().slice(0, 120),
+    });
+  }
+  return out;
+}
+
+/**
+ * Decide which sites are findings, given every site in the repo.
+ *
+ * A site is flagged only when another site awaiting the same callee reads the
+ * error — the codebase itself is the evidence that the field exists. A callee
+ * nobody ever reads `error` from produces nothing: there is no reason to believe
+ * it has one, and inventing that belief is how a scanner becomes noise.
+ */
+export function findingsFrom(sites: SwallowedErrorSite[]): SwallowedErrorFinding[] {
+  const readsErrorByCallee = new Map<string, number>();
+  for (const s of sites) {
+    if (s.binds_error) readsErrorByCallee.set(s.callee, (readsErrorByCallee.get(s.callee) ?? 0) + 1);
+  }
+  return sites
+    .filter((s) => !s.binds_error && (readsErrorByCallee.get(s.callee) ?? 0) > 0)
+    .map((s) => ({ ...s, peers_reading_error: readsErrorByCallee.get(s.callee)! }));
+}
+
+export function inventorySwallowedErrors(
+  localPathInput: string,
+  sandboxRoots: string[],
+  maxFiles = 5000,
+): {
+  total_findings: number;
+  files_scanned: number;
+  sites_seen: number;
+  /** Per-callee shape: "87 of 111 supabase.from sites drop the error". A bare
+   *  total is not actionable on a codebase where the pattern is widespread —
+   *  the RATIO is what tells you whether you are looking at a few slips or a
+   *  house style, and those are different conversations. */
+  by_callee: Array<{ callee: string; dropping: number; reading: number }>;
+  findings: SwallowedErrorFinding[];
+} {
+  const root = resolveSandboxedPath(localPathInput, sandboxRoots);
+  const sites: SwallowedErrorSite[] = [];
+  const budget = { left: maxFiles };
+  let scanned = 0;
+
+  const walk = (dir: string): void => {
+    if (budget.left <= 0) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (budget.left <= 0) return;
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (SOURCE_EXTS.has(extname(name))) {
+        budget.left -= 1;
+        scanned += 1;
+        try {
+          sites.push(...sitesInFile(readFileSync(full, 'utf-8'), full.slice(root.length + 1)));
+        } catch {
+          // unreadable — skip
+        }
+      }
+    }
+  };
+  walk(root);
+
+  const findings = findingsFrom(sites).sort(
+    (a, b) => a.file.localeCompare(b.file) || a.line - b.line,
+  );
+
+  const tally = new Map<string, { dropping: number; reading: number }>();
+  for (const s of sites) {
+    const e = tally.get(s.callee) ?? { dropping: 0, reading: 0 };
+    if (s.binds_error) e.reading += 1;
+    else e.dropping += 1;
+    tally.set(s.callee, e);
+  }
+  const by_callee = [...tally.entries()]
+    .filter(([, v]) => v.reading > 0 && v.dropping > 0)
+    .map(([callee, v]) => ({ callee, ...v }))
+    .sort((a, b) => b.dropping - a.dropping);
+
+  return {
+    total_findings: findings.length,
+    files_scanned: scanned,
+    sites_seen: sites.length,
+    by_callee,
+    findings,
+  };
+}