@dogfood-lab/findings 1.2.1

package/lib/file-lock.js

@@ -0,0 +1,359 @@
+/**
+ * Cross-process advisory file lock built on `openSync(path, 'wx')` exclusive-create.
+ *
+ * Why this exists: `appendEvent` in review/event-log.js does a read-modify-write
+ * of a YAML array (read existing events → push new → atomic-rename whole file).
+ * Two concurrent appends both read N events, both push, both rename — second
+ * rename wins, dropping the first event. The atomic rename eliminates partial-
+ * file corruption (worst case before wave 9), but cannot eliminate the lost-
+ * event window. F-PIPELINE-011 (W3-PIPE-001) closes that window at the choke
+ * point so the bug class is impossible to recur — Pattern #4 from the
+ * swarm-evidence catalog.
+ *
+ * Why an O_EXCL lock FILE (not a lock DIR): an early implementation used
+ * `mkdirSync` then a follow-up `writeFileSync(.../pid)` — but those are two
+ * separate fs ops, so a process that's mid-acquisition is in a state where
+ * the dir exists but the pid file does NOT. A racing acquirer sees the dir,
+ * tries to read pid, gets ENOENT, classifies as stale, removes the dir, and
+ * the original acquirer's pid write later trips on the dir being gone.
+ * Lock-FILE-with-O_EXCL avoids that: the `open(path, 'wx')` call returns a
+ * file descriptor in one syscall, and we write the pid through that fd —
+ * any racing acquirer that sees the file knows it's fully formed.
+ *
+ * Why not `proper-lockfile`: that package isn't a dep of this monorepo
+ * (verified at the start of wave 30). `open(path, 'wx')` is atomic on POSIX
+ * and Windows — the kernel guarantees exactly one creator wins, the loser
+ * sees `EEXIST`. The pattern has been in use for decades and works the same
+ * on every fs Node supports (NTFS, ext4, APFS, tmpfs, nfsv4).
+ *
+ * Why not `O_APPEND`: the format here is a YAML array, not JSONL. `O_APPEND`
+ * makes byte-append atomic for sub-`PIPE_BUF` writes on POSIX, but the
+ * read-modify-write of the whole array bypasses that — even with `O_APPEND`
+ * the events would not be a valid YAML array. Switching the format to JSONL
+ * is a bigger compat break than this contract should make. Lock instead.
+ *
+ * Stale lock recovery: a process that crashes while holding the lock leaves
+ * the file behind. We detect "stale" by reading the holder PID and using
+ * `process.kill(pid, 0)` to test liveness — `ESRCH` means the holder is
+ * gone and the lock is reclaimable. The reclaim itself is best-effort:
+ * another fresh acquirer might race the cleanup, but the worst case is an
+ * extra retry, never lost data. To prevent two reclaimers from both believing
+ * they won, the reclaim sequence is `unlink → open(wx)`; the second
+ * reclaimer's `open(wx)` will fail because the first reclaimer already
+ * created it.
+ *
+ * Concurrency caveat — out of scope: this is a *single-machine* lock. NFS or
+ * other distributed filesystems expose `open(wx)` semantics that may not be
+ * truly atomic across nodes. The dogfood pipeline runs on a single GitHub
+ * runner per dispatch, so this is sufficient. A multi-runner sharded ingest
+ * would need a real consensus lock — flagged in the JSDoc above
+ * `withFileLock` so the limitation is visible at the use site.
+ */
+
+import { mkdirSync, openSync, closeSync, writeSync, writeFileSync, readFileSync, existsSync, unlinkSync, linkSync, renameSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+// 30s default timeout: appendEvent's critical section is small (~ms), but
+// 50-way parallel ingests serializing through the lock can take a few seconds
+// in aggregate. 30s leaves comfortable headroom for the dogfood pipeline's
+// realistic concurrency (~10 parallel jobs per dispatch wave) without making
+// CI hang on a runaway holder.
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_INTERVAL_MS = 15;
+const DEFAULT_STALE_AFTER_MS = 30_000;
+
+/**
+ * Compute the lock file path for a given target file.
+ * Co-locates with the target so a permission-restricted directory still works.
+ *
+ * Kept named `lockDirFor` for back-compat with the wave-30 design draft —
+ * the path now points at a regular file, not a directory, but the call sites
+ * don't care about the kind.
+ *
+ * @param {string} targetPath
+ * @returns {string}
+ */
+export function lockDirFor(targetPath) {
+  return `${targetPath}.lock`;
+}
+
+/**
+ * Test whether a process is alive. Returns false if `pid` is missing,
+ * non-numeric, or `process.kill(pid, 0)` rejects with `ESRCH`. Any other
+ * error (e.g. `EPERM` on a foreign-user pid) is treated as "alive" — better
+ * to wait out the lock than to steal a live one.
+ *
+ * @param {number|string|null|undefined} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  const n = typeof pid === 'number' ? pid : Number(pid);
+  if (!Number.isFinite(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'ESRCH') return false;
+    return true;
+  }
+}
+
+/**
+ * Atomically create the lock file with the holder's PID as content.
+ *
+ * Two-step pattern: write a temp file (containing this process's pid) in the
+ * same parent dir, then `linkSync(temp, lockPath)`. `link` is atomic on every
+ * fs Node supports — it either creates the link or fails with EEXIST; there
+ * is no observable intermediate state where the lock file exists but is
+ * empty. This closes the race that an earlier `open(wx)+write` design left
+ * open: a racing acquirer could read the lock file in the window between
+ * `open` and `write` and see it as empty (= stale) before the holder's pid
+ * was recorded.
+ *
+ * @param {string} lockPath
+ * @returns {boolean} true on success; false if the lock already exists.
+ */
+function atomicCreateLock(lockPath) {
+  const tmpPath = `${lockPath}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  // Write the temp file atomically (truncates if it somehow exists, which
+  // it never should given the pid+random suffix). Content is the holder pid.
+  writeFileSync(tmpPath, String(process.pid), 'utf-8');
+  try {
+    linkSync(tmpPath, lockPath);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'EEXIST') return false;
+    throw err;
+  } finally {
+    // The temp file is no longer needed regardless of link outcome — the
+    // hardlink (on success) keeps the inode alive at lockPath; on failure
+    // the temp file is just garbage to clean up.
+    try { unlinkSync(tmpPath); } catch { /* best effort */ }
+  }
+}
+
+/**
+ * Attempt to acquire an exclusive file-lock on `lockPath`. Returns true if
+ * the lock was acquired; false if it is held by another live process OR
+ * by a process whose lock file is unreadable / pid-empty (treated as live
+ * with bounded mtime patience — see below).
+ *
+ * Stale recovery: a holder's PID file remains until its release `unlink`
+ * runs. If the holder PROCESS is gone (process.kill ESRCH), the lock is
+ * reclaimable. We do NOT treat empty/missing pid content as stale on its
+ * own — that was the wave-30 first-pass bug. Even with `linkSync` for
+ * atomic creation, on Windows a racing reader can land on a brief window
+ * where the pid file's content has not yet been committed to the dirent
+ * cache from the other process. Empty content + bounded-stale-mtime is the
+ * safer guard: we only reclaim if the lock file is ALSO older than
+ * `staleAfterMs`, the same boundary `proper-lockfile` uses.
+ *
+ * @param {string} lockPath
+ * @param {{ staleAfterMs?: number }} opts
+ * @returns {boolean}
+ */
+function tryAcquire(lockPath, opts = {}) {
+  const { staleAfterMs = DEFAULT_STALE_AFTER_MS } = opts;
+
+  if (atomicCreateLock(lockPath)) return true;
+
+  // Lock exists — test for staleness.
+  let pidRaw = null;
+  let mtimeMs = NaN;
+  try {
+    pidRaw = readFileSync(lockPath, 'utf-8').trim();
+  } catch {
+    // Read failed — fall through to the mtime check below; if we can't
+    // even stat it, treat as live.
+  }
+  try {
+    const st = statSync(lockPath);
+    mtimeMs = st.mtimeMs;
+  } catch { /* will be NaN, treated as live */ }
+
+  // PID-known case: trust process.kill to decide alive-vs-dead. This is the
+  // common case and gives fast crash recovery (sub-100ms typical).
+  if (pidRaw && pidRaw !== '') {
+    if (isProcessAlive(pidRaw)) return false;
+
+    // PID-dead reclaim via "rename to graveyard" — atomic claim that exactly
+    // one reclaimer wins. Without this, a sequence like:
+    //   1. A holds lock; A releases (unlinks); A's pid becomes dead
+    //   2. C atomicCreateLock succeeds — C owns lock with pid=C
+    //   3. B (had read pidRaw=A above) confirms A dead, calls unlinkSync — but
+    //      the file is now C's lock! Now B and C both think they own it.
+    // produces a double-owner. The graveyard rename is the atomic CAS step:
+    // exactly one process can rename a given file at a given moment. We
+    // verify the rename succeeded AND the file we renamed still has the
+    // dead PID we expected; if the content shifted (someone else just
+    // re-acquired), put the file back.
+    return reclaimViaGraveyard(lockPath, pidRaw);
+  }
+
+  // PID-unknown case (empty/unreadable content). DO NOT treat as stale on
+  // content alone — Windows can present a brief window where the holder's
+  // file content is still flushing. Only reclaim if the lock is also older
+  // than `staleAfterMs`. With the default 30s staleAfterMs, fast appenders
+  // never trip this; only a true crash window does.
+  if (Number.isFinite(mtimeMs) && Date.now() - mtimeMs > staleAfterMs) {
+    if (process.env.FILE_LOCK_DEBUG) {
+      process.stderr.write(`[file-lock][pid=${process.pid}] STALE-RECLAIM (mtime-old) lockPath=${lockPath} ageMs=${Date.now() - mtimeMs}\n`);
+    }
+    // Use the same graveyard-rename CAS for the mtime-stale path. The PID
+    // is unknown so we use empty string as the "expected" content — the
+    // graveyard verification will accept whatever it reads (the put-back
+    // branch only triggers when actualPid is non-empty AND differs).
+    return reclaimViaGraveyard(lockPath, pidRaw || '');
+  }
+
+  // Treat as live; the holder owns the lock and will release it.
+  return false;
+}
+
+/**
+ * Release a lock acquired via `tryAcquire`. Best-effort — a missing lock file
+ * is not an error (it means stale-lock recovery already cleaned it).
+ *
+ * @param {string} lockPath
+ */
+function release(lockPath) {
+  try { unlinkSync(lockPath); } catch { /* may already be gone */ }
+}
+
+/**
+ * Reclaim a stale lock via "rename to graveyard." Atomic CAS step: exactly
+ * one reclaimer can rename a file at a time. The winner verifies the renamed
+ * file still has the dead PID it expected (defending against the case where
+ * the lock content shifted between the read-pid step and the rename); if so,
+ * the winner unlinks the graveyard file and creates a fresh lock. If the
+ * content shifted, the winner puts the file back so the new owner is
+ * unaffected.
+ *
+ * @param {string} lockPath
+ * @param {string} expectedDeadPid - The PID we observed and confirmed dead.
+ * @returns {boolean}
+ */
+function reclaimViaGraveyard(lockPath, expectedDeadPid) {
+  const graveyardPath = `${lockPath}.gy.${process.pid}.${randomBytes(4).toString('hex')}`;
+  try {
+    renameSync(lockPath, graveyardPath);
+  } catch (err) {
+    // Another reclaimer beat us — let the retry loop sort it out.
+    return false;
+  }
+
+  // We won the rename. Verify content.
+  let actualPid = null;
+  try {
+    actualPid = readFileSync(graveyardPath, 'utf-8').trim();
+  } catch { /* unreadable — treat as confirmation */ }
+
+  if (actualPid && actualPid !== expectedDeadPid) {
+    // Content shifted between our read and our rename. The "stale" lock
+    // we grabbed is actually a fresh acquisition by someone else.
+    // Put it back. If put-back fails (e.g., another reclaimer raced and
+    // already created a new lock at lockPath), discard the graveyard copy.
+    try {
+      renameSync(graveyardPath, lockPath);
+      if (process.env.FILE_LOCK_DEBUG) {
+        process.stderr.write(`[file-lock][pid=${process.pid}] CAS-FAIL-PUTBACK lockPath=${lockPath} expected=${expectedDeadPid} found=${actualPid}\n`);
+      }
+    } catch {
+      try { unlinkSync(graveyardPath); } catch { /* drop */ }
+    }
+    return false;
+  }
+
+  if (process.env.FILE_LOCK_DEBUG) {
+    process.stderr.write(`[file-lock][pid=${process.pid}] STALE-RECLAIM (dead-pid) lockPath=${lockPath} pid=${expectedDeadPid}\n`);
+  }
+
+  try { unlinkSync(graveyardPath); } catch { /* drop */ }
+  return atomicCreateLock(lockPath);
+}
+
+/**
+ * Sleep synchronously for `ms` milliseconds via `Atomics.wait` on a tiny
+ * SharedArrayBuffer. We can't `await` here because the callers
+ * (`appendEvent`, `rebuildIndexes`) are sync APIs — the whole pipeline
+ * is sync from `ingest()` down to fs I/O, so introducing async here would
+ * cascade through six callers and break the back-compat contract on
+ * `appendEvent` that review-engine relies on.
+ *
+ * @param {number} ms
+ */
+function sleepSync(ms) {
+  const sab = new SharedArrayBuffer(4);
+  const view = new Int32Array(sab);
+  Atomics.wait(view, 0, 0, ms);
+}
+
+/**
+ * Run `fn` while holding an exclusive lock on `targetPath`. The lock is a
+ * sibling directory at `<targetPath>.lock` — see file header for the
+ * full design rationale.
+ *
+ * The lock is per-target, so two unrelated `appendEvent` calls writing to
+ * different daily log files do NOT serialize against each other.
+ *
+ * @template T
+ * @param {string} targetPath - The file being mutated; the lock dir is `<targetPath>.lock`.
+ * @param {() => T} fn - The critical section. Runs synchronously.
+ * @param {{
+ *   timeoutMs?: number,
+ *   retryIntervalMs?: number,
+ *   staleAfterMs?: number
+ * }} [options]
+ * @returns {T}
+ */
+export function withFileLock(targetPath, fn, options = {}) {
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS,
+    staleAfterMs = DEFAULT_STALE_AFTER_MS,
+  } = options;
+
+  const lockPath = lockDirFor(targetPath);
+
+  // Ensure the parent dir exists — otherwise mkdirSync(lockPath) fails with
+  // ENOENT and we mis-classify the lock as held.
+  try { mkdirSync(dirname(lockPath), { recursive: true }); } catch { /* may already exist */ }
+
+  const deadline = Date.now() + timeoutMs;
+  let acquired = false;
+  let lastErrCtx = null;
+
+  while (Date.now() < deadline) {
+    if (tryAcquire(lockPath, { staleAfterMs })) {
+      acquired = true;
+      break;
+    }
+    sleepSync(retryIntervalMs);
+  }
+
+  if (!acquired) {
+    const err = new Error(
+      `withFileLock: timed out after ${timeoutMs}ms waiting for ${lockPath}` +
+      (lastErrCtx ? ` (last error: ${lastErrCtx})` : '')
+    );
+    err.code = 'ELOCKTIMEOUT';
+    err.lockPath = lockPath;
+    throw err;
+  }
+
+  try {
+    return fn();
+  } finally {
+    release(lockPath);
+  }
+}
+
+/**
+ * Test-only: probe whether a lock is currently held without acquiring it.
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isLocked(targetPath) {
+  return existsSync(lockDirFor(targetPath));
+}

package/lib/rename-with-retry.js

@@ -0,0 +1,43 @@
+/**
+ * renameWithRetry — Windows-tolerant atomic rename.
+ *
+ * On Windows NTFS, `renameSync(tmp, target)` can throw EPERM (or EBUSY) even
+ * when the calling process holds the file lock. The most common cause is a
+ * transient handle held by a sibling — antivirus scanning the freshly-written
+ * temp, Search Indexer, Defender, a backup agent — across the rename window.
+ * The handle releases on its own within milliseconds, but the bare renameSync
+ * is unforgiving and surfaces the error to the operator.
+ *
+ * The fix is a bounded exponential-backoff retry. The W3-PIPE-001 wave-30
+ * receipt documents the 50/50 multi-process race-test outcome with this
+ * mitigation in place; without it, that test fails reliably on Windows CI.
+ *
+ * Synchronous-on-purpose: the call sites here (atomic-write helpers, event-log
+ * appender) are themselves synchronous, and Promise-based retries would
+ * leak the async boundary into otherwise-deterministic flush paths.
+ *
+ * @param {string} tmp - Source path (the just-written temp file).
+ * @param {string} dest - Destination path (the canonical artifact).
+ * @param {object} [opts]
+ * @param {number} [opts.retries=10] - Max retry attempts after the first failure.
+ * @param {number} [opts.baseMs=15]  - Initial backoff in ms (doubles each step).
+ * @param {number} [opts.maxMs=200]  - Cap on per-step backoff.
+ */
+import { renameSync } from 'node:fs';
+
+export function renameWithRetry(tmp, dest, { retries = 10, baseMs = 15, maxMs = 200 } = {}) {
+  for (let i = 0; i <= retries; i++) {
+    try {
+      renameSync(tmp, dest);
+      return;
+    } catch (err) {
+      if ((err.code !== 'EPERM' && err.code !== 'EBUSY') || i === retries) throw err;
+      const delay = Math.min(baseMs * (1 << i), maxMs);
+      // Synchronous sleep — the public API is sync (matches renameSync), so
+      // setTimeout would change the contract. Spin-wait is acceptable here
+      // because the delays are bounded (≤200ms) and the failure mode is rare.
+      const until = Date.now() + delay;
+      while (Date.now() < until) { /* spin */ }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@dogfood-lab/findings",
+  "version": "1.2.1",
+  "type": "module",
+  "description": "Finding contract spine for testing-os. Validates, reads, lists, and queries evidence-bound findings — the fourth contract alongside record, scenario, and policy.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./reader.js": "./reader.js",
+    "./validate.js": "./validate.js",
+    "./derive/*": "./derive/*",
+    "./review/*": "./review/*",
+    "./synthesis/*": "./synthesis/*",
+    "./advise/*": "./advise/*",
+    "./lib/*": "./lib/*"
+  },
+  "bin": {
+    "findings": "./cli.js"
+  },
+  "scripts": {
+    "test": "node --test findings.test.js derive/derive.test.js review/review.test.js synthesis/synthesis.test.js advise/advise.test.js lib/atomic-write.test.js"
+  },
+  "files": [
+    "index.js",
+    "cli.js",
+    "reader.js",
+    "validate.js",
+    "advise/",
+    "derive/",
+    "lib/",
+    "review/",
+    "synthesis/",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.js",
+    "!**/*.test.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dogfood-lab/ingest": "^1.2.0",
+    "@dogfood-lab/schemas": "^1.2.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogfood-lab/testing-os.git",
+    "directory": "packages/findings"
+  },
+  "homepage": "https://github.com/dogfood-lab/testing-os",
+  "bugs": {
+    "url": "https://github.com/dogfood-lab/testing-os/issues"
+  },
+  "keywords": [
+    "testing-os",
+    "dogfood-lab",
+    "findings",
+    "evidence",
+    "audit",
+    "review"
+  ]
+}

package/reader.js

@@ -0,0 +1,156 @@
+/**
+ * Finding reader/lister.
+ * Discovers findings from the filesystem, supports filtering and lookup.
+ */
+
+import { readdirSync, existsSync, statSync } from 'node:fs';
+import { resolve, join, basename, extname } from 'node:path';
+import { parseFinding, validateFinding } from './validate.js';
+
+/**
+ * Discover all .yaml finding files under a root directory.
+ * Walks findings/<org>/<repo>/*.yaml
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @returns {string[]} Array of absolute paths to finding files.
+ */
+export function discoverFindings(rootDir) {
+  const findingsDir = resolve(rootDir, 'findings');
+  if (!existsSync(findingsDir)) return [];
+
+  const paths = [];
+
+  // Walk: findings/<org>/<repo>/*.yaml
+  for (const org of listDirs(findingsDir)) {
+    const orgDir = join(findingsDir, org);
+    for (const repo of listDirs(orgDir)) {
+      const repoDir = join(orgDir, repo);
+      for (const file of readdirSync(repoDir)) {
+        if (extname(file) === '.yaml') {
+          paths.push(resolve(repoDir, file));
+        }
+      }
+    }
+  }
+
+  return paths.sort();
+}
+
+/**
+ * Discover finding files from fixtures directory.
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {'valid' | 'invalid'} kind - Which fixture set.
+ * @returns {string[]} Array of absolute paths.
+ */
+export function discoverFixtures(rootDir, kind) {
+  const dir = resolve(rootDir, 'fixtures', 'findings', kind);
+  if (!existsSync(dir)) return [];
+
+  return readdirSync(dir)
+    .filter(f => extname(f) === '.yaml')
+    .map(f => resolve(dir, f))
+    .sort();
+}
+
+/**
+ * Load all findings from disk (real or fixtures).
+ * Returns parsed + validated findings.
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {{ fixtures?: boolean, fixtureKind?: 'valid' | 'invalid' }} opts
+ * @returns {Array<{ path: string, data: object | null, valid: boolean, errors: Array }>}
+ */
+export function loadFindings(rootDir, opts = {}) {
+  const paths = opts.fixtures
+    ? discoverFixtures(rootDir, opts.fixtureKind || 'valid')
+    : discoverFindings(rootDir);
+
+  return paths.map(filePath => {
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      return { path: filePath, data: null, valid: false, errors: [{ path: '/', message: error }] };
+    }
+    const result = validateFinding(data);
+    return { path: filePath, data, ...result };
+  });
+}
+
+/**
+ * Find a single finding by its finding_id.
+ * Searches real findings first, then fixtures.
+ *
+ * @param {string} rootDir - The dogfood-labs repo root.
+ * @param {string} findingId - The finding_id to look up.
+ * @returns {{ path: string, data: object, valid: boolean, errors: Array } | null}
+ */
+export function findById(rootDir, findingId) {
+  // Search real findings
+  for (const filePath of discoverFindings(rootDir)) {
+    const { data } = parseFinding(filePath);
+    if (data && data.finding_id === findingId) {
+      const result = validateFinding(data);
+      return { path: filePath, data, ...result };
+    }
+  }
+
+  // Search valid fixtures
+  for (const filePath of discoverFixtures(rootDir, 'valid')) {
+    const { data } = parseFinding(filePath);
+    if (data && data.finding_id === findingId) {
+      const result = validateFinding(data);
+      return { path: filePath, data, ...result };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Filter a list of loaded findings.
+ *
+ * @param {Array<{ data: object }>} findings - Loaded findings.
+ * @param {{ repo?: string, status?: string, surface?: string, issueKind?: string, transferScope?: string }} filters
+ * @returns {Array}
+ */
+export function filterFindings(findings, filters = {}) {
+  return findings.filter(f => {
+    if (!f.data) return false;
+    if (filters.repo && f.data.repo !== filters.repo) return false;
+    if (filters.status && f.data.status !== filters.status) return false;
+    if (filters.surface && f.data.product_surface !== filters.surface) return false;
+    if (filters.issueKind && f.data.issue_kind !== filters.issueKind) return false;
+    if (filters.transferScope && f.data.transfer_scope !== filters.transferScope) return false;
+    return true;
+  });
+}
+
+/**
+ * Check for duplicate finding_ids across all findings.
+ * @param {Array<{ data: object, path: string }>} findings
+ * @returns {Array<{ findingId: string, paths: string[] }>}
+ */
+export function findDuplicates(findings) {
+  const seen = new Map();
+  for (const f of findings) {
+    if (!f.data || !f.data.finding_id) continue;
+    const id = f.data.finding_id;
+    if (!seen.has(id)) seen.set(id, []);
+    seen.get(id).push(f.path);
+  }
+
+  return Array.from(seen.entries())
+    .filter(([, paths]) => paths.length > 1)
+    .map(([findingId, paths]) => ({ findingId, paths }));
+}
+
+/** List subdirectories of a directory. */
+function listDirs(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter(name => {
+    try {
+      return statSync(join(dir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}