npm - carto-md - Versions diffs - 2.0.8 → 2.0.9 - Mend

carto-md 2.0.8 → 2.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +149 -9
package/docs/anci/v0.1-DRAFT.md +420 -0
package/docs/scale.md +129 -0
package/package.json +4 -3
package/scripts/postinstall.js +391 -24
package/src/agents/leiden.js +4 -4
package/src/agents/scan-structure.js +1 -1
package/src/anci/consumer.js +305 -0
package/src/anci/deserialize.js +160 -0
package/src/anci/emit.js +85 -0
package/src/anci/serialize.js +264 -0
package/src/anci/yaml.js +401 -0
package/src/cli/anci.js +237 -0
package/src/cli/index.js +14 -0
package/src/cli/init.js +1 -1
package/src/cli/inspect.js +1 -1
package/src/cli/pr-impact.js +497 -0
package/src/extractors/languages/javascript.js +3 -3
package/src/mcp/change-plan.js +8 -8
package/src/store/sync-v2.js +52 -3

package/src/cli/pr-impact.js ADDED Viewed

@@ -0,0 +1,497 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * `carto pr-impact` — pull-request-shaped impact report.
+ *
+ * Computes the impact of a pull request's diff against the current
+ * project graph and renders either:
+ *   - Markdown wrapped in a `<!-- carto-impact-report -->` HTML marker
+ *     so the GitHub Action can detect-and-update sticky comments.
+ *   - JSON for programmatic consumers (CI dashboards, custom workflows).
+ *
+ * Composition:
+ *   1. `git diff --unified=3 <base>...<head>` → unified diff text.
+ *   2. `validateDiff(store, sidecar, diff)` → violations, blast radius,
+ *      risk roll-up. (Same engine the MCP `validate_diff` tool uses.)
+ *   3. Per-file `StoreAdapter.getBlastRadius(file)` → routes affected,
+ *      domains impacted (validateDiff returns counts; the comment
+ *      template wants the actual route list).
+ *   4. Render.
+ *
+ * Exit code:
+ *   - 0 by default (the comment surfaces the risk; failing the build
+ *     is opt-in).
+ *   - Non-zero when `--fail-on HIGH|MEDIUM` is supplied AND the rolled-up
+ *     risk meets or exceeds the threshold.
+ *
+ * The command is read-only: it does not write to the SQLite store and
+ * does not record episodic-memory rows — those persistence concerns
+ * belong to the MCP `validate_diff` tool, not the CI surface.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { SQLiteStore } = require('../store/sqlite-store');
+const { StoreAdapter } = require('../store/store-adapter');
+const { ensureBitmapFresh } = require('../bitmap/index');
+const { validateDiff } = require('../mcp/validate');
+const MARKER = '<!-- carto-impact-report -->';
+function parseArgs(argv) {
+  const args = {
+    base: null,
+    head: 'HEAD',
+    format: 'markdown',
+    failOn: null,           // null | 'HIGH' | 'MEDIUM' | 'LOW'
+    diffFile: null,         // for tests: read diff from a file instead of git
+    projectRoot: process.cwd(),
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--base':       args.base = argv[++i]; break;
+      case '--head':       args.head = argv[++i]; break;
+      case '--format':     args.format = argv[++i]; break;
+      case '--fail-on':    args.failOn = (argv[++i] || '').toUpperCase(); break;
+      case '--diff-file':  args.diffFile = argv[++i]; break;
+      case '--project':    args.projectRoot = path.resolve(argv[++i]); break;
+      case '--help':
+      case '-h':           args.help = true; break;
+      default:
+        // Unknown flag — fail loudly so typos in CI are visible.
+        if (a.startsWith('--')) {
+          throw new Error(`unknown flag: ${a}`);
+        }
+    }
+  }
+  if (!['markdown', 'json'].includes(args.format)) {
+    throw new Error(`--format must be 'markdown' or 'json' (got '${args.format}')`);
+  }
+  if (args.failOn && !['HIGH', 'MEDIUM', 'LOW'].includes(args.failOn)) {
+    throw new Error(`--fail-on must be HIGH | MEDIUM | LOW (got '${args.failOn}')`);
+  }
+  return args;
+}
+function printUsage() {
+  process.stdout.write(`
+Usage: carto pr-impact [options]
+Computes the impact of a PR's diff against the current carto index and
+renders a markdown or JSON report. Designed for the carto GitHub Action
+but usable standalone.
+Options:
+  --base <ref>          Git ref the PR branched from (e.g. origin/main)
+  --head <ref>          Git ref of the PR head (default: HEAD)
+  --format <fmt>        markdown (default) | json
+  --fail-on <severity>  Exit non-zero if risk >= severity (HIGH | MEDIUM | LOW)
+  --diff-file <path>    Read diff text from a file instead of running git diff
+                        (primarily for testing)
+  --project <path>      Project root (default: cwd)
+  --help, -h            Show this help
+Exit codes:
+  0  Normal — comment rendered.
+  1  Misuse, missing index, or git failure.
+  2  --fail-on threshold tripped.
+`);
+}
+/**
+ * runGitDiff(projectRoot, base, head) → diffText
+ *
+ * Captures the unified diff between two refs. Three-dot syntax (`base...head`)
+ * matches what GitHub uses for PR diffs — only the changes introduced on
+ * the head branch since it diverged from base, not changes that landed on
+ * base in the meantime.
+ */
+function runGitDiff(projectRoot, base, head) {
+  if (!base) {
+    throw new Error('--base is required (or use --diff-file to supply a diff manually)');
+  }
+  let out;
+  try {
+    out = execFileSync('git', ['diff', '--unified=3', `${base}...${head}`], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024, // 64 MB — large PRs are rare but real
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    throw new Error(
+      `git diff ${base}...${head} failed${stderr ? `: ${stderr}` : ''}`
+    );
+  }
+  return out;
+}
+const RISK_BADGE = {
+  HIGH:   '🔴 HIGH',
+  MEDIUM: '🟡 MEDIUM',
+  LOW:    '🟢 LOW',
+  SAFE:   '✅ SAFE',
+};
+const RISK_RANK = { SAFE: 0, LOW: 1, MEDIUM: 2, HIGH: 3 };
+/**
+ * collectImpact(projectRoot, diffText) → { result, perFile, domains, highImpact }
+ *
+ * - `result`     — full validateDiff(...) output (violations + blast
+ *                  radius + risk).
+ * - `perFile`    — Map<path, { blastRadius, routes, domains }> for files
+ *                  in the diff. Skipped for files not in the index
+ *                  (pure adds, renames where the new path didn't exist
+ *                  at sync time).
+ * - `domains`    — sorted Array<string> of all domains touched by the
+ *                  changed files (used for the headline sentence).
+ * - `highImpact` — { file, dependents } for the changed file with the
+ *                  most direct dependents, or null if all are 0.
+ */
+function collectImpact(projectRoot, diffText) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(
+      `No carto index at ${dbPath}. Run \`carto init\` (or \`carto sync\` ` +
+      `if the index already exists) before \`carto pr-impact\`.`
+    );
+  }
+  const store = new SQLiteStore(projectRoot);
+  store.open({ readonly: true });
+  let sidecar = null;
+  try {
+    sidecar = ensureBitmapFresh(cartoDir, store);
+  } catch (err) {
+    process.stderr.write(
+      `[CARTO] bitmap unavailable, validation will use SQLite-only path: ` +
+      `${err.message || err}\n`
+    );
+  }
+  const result = validateDiff(store, sidecar, diffText);
+  // Per-file rich detail via StoreAdapter (matches what `carto impact <file>`
+  // returns — routes, domain). We open a second adapter pointed at the same
+  // DB rather than re-implementing the formatter here.
+  const adapter = new StoreAdapter();
+  // Skip the indexer — we know the DB exists. Open the store directly.
+  adapter._store = store;
+  adapter._projectRoot = projectRoot;
+  const perFile = new Map();
+  const domainSet = new Set();
+  let highImpact = null;
+  for (const f of result.diff) {
+    if (f.kind === 'delete') continue;
+    let br = null;
+    try {
+      br = adapter.getBlastRadius(f.path);
+    } catch {
+      // File not in index — most often a pure add. Leave perFile entry
+      // off the map; renderer skips files it doesn't have detail for.
+    }
+    if (!br) continue;
+    perFile.set(f.path, {
+      blastRadius: br.dependentFiles.length,
+      directlyAffected: br.directlyAffected.files,
+      routes: br.routesImpacted,
+      domains: br.domainsImpacted,
+    });
+    for (const d of br.domainsImpacted) domainSet.add(d);
+    if (
+      !highImpact ||
+      br.directlyAffected.files > highImpact.dependents
+    ) {
+      highImpact = {
+        file: f.path,
+        dependents: br.directlyAffected.files,
+      };
+    }
+  }
+  store.close();
+  return {
+    result,
+    perFile,
+    domains: [...domainSet].sort(),
+    highImpact: highImpact && highImpact.dependents > 0 ? highImpact : null,
+  };
+}
+/**
+ * renderMarkdown(impact) → string
+ *
+ * Renders the PR comment body. Wraps the entire body in a
+ * `<!-- carto-impact-report -->` HTML comment marker so the GitHub
+ * Action can find-and-update its previous comment instead of posting
+ * a duplicate every commit.
+ *
+ * Sections:
+ *   - Headline sentence ("This PR touches X and Y domains.")
+ *   - Metric table (Risk · Blast radius · Files changed · Violations
+ *     introduced · High-impact file)
+ *   - Affected routes (collapsible) — only if any
+ *   - Cross-domain violations (collapsible) — only if any
+ *   - Suggestions (collapsible) — only if any
+ */
+function renderMarkdown(impact) {
+  const { result, perFile, domains, highImpact } = impact;
+  const out = [];
+  out.push(MARKER);
+  out.push('## 🗺️ Carto Impact Report');
+  out.push('');
+  if (result.diff.length === 0) {
+    out.push('_No file changes detected in this diff._');
+    out.push('');
+    return out.join('\n');
+  }
+  // Headline sentence.
+  if (domains.length === 0) {
+    out.push(`This PR touches **${result.diff.length} file(s)** in unmapped domains.`);
+  } else if (domains.length === 1) {
+    out.push(`This PR touches the **${domains[0]}** domain.`);
+  } else if (domains.length === 2) {
+    out.push(`This PR touches **${domains[0]}** and **${domains[1]}** domains.`);
+  } else {
+    const head = domains.slice(0, -1).map((d) => `**${d}**`).join(', ');
+    const tail = `**${domains[domains.length - 1]}**`;
+    out.push(`This PR touches ${head}, and ${tail} domains.`);
+  }
+  out.push('');
+  // Metric table.
+  const crossDomainCount = result.violations.filter(
+    (v) => v.kind === 'cross_domain'
+  ).length;
+  out.push('| Metric | Value |');
+  out.push('|--------|-------|');
+  out.push(`| **Risk** | ${RISK_BADGE[result.risk] || result.risk} |`);
+  out.push(`| Blast radius (union) | ${result.blast_radius.union} files |`);
+  out.push(`| Files changed | ${result.diff.length} |`);
+  out.push(`| Cross-domain violations introduced | ${crossDomainCount} |`);
+  if (highImpact) {
+    out.push(
+      `| High-impact file changed | \`${highImpact.file}\` (${highImpact.dependents} direct dependents) |`
+    );
+  }
+  out.push('');
+  // Routes section — flatten per-file routes, dedupe by method+path.
+  const routeRows = [];
+  const seenRoutes = new Set();
+  for (const detail of perFile.values()) {
+    for (const r of detail.routes || []) {
+      const key = `${r.method} ${r.path}`;
+      if (seenRoutes.has(key)) continue;
+      seenRoutes.add(key);
+      routeRows.push(r);
+    }
+  }
+  if (routeRows.length > 0) {
+    out.push(`<details>`);
+    out.push(`<summary>Affected routes (${routeRows.length})</summary>`);
+    out.push('');
+    for (const r of routeRows) {
+      out.push(`- \`${r.method} ${r.path}\` — risk: ${r.risk}`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // Cross-domain violations.
+  const crossViolations = result.violations.filter(
+    (v) => v.kind === 'cross_domain'
+  );
+  if (crossViolations.length > 0) {
+    out.push(`<details>`);
+    out.push(
+      `<summary>Cross-domain violations (${crossViolations.length})</summary>`
+    );
+    out.push('');
+    for (const v of crossViolations) {
+      out.push(
+        `- \`${v.file}\` now imports from \`${v.toFile}\` (${v.fromDomain}→${v.toDomain})`
+      );
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // High-blast violations as a separate section so reviewers see them
+  // even when no cross-domain edges exist.
+  const blastViolations = result.violations.filter(
+    (v) => v.kind === 'high_blast'
+  );
+  if (blastViolations.length > 0) {
+    out.push(`<details>`);
+    out.push(
+      `<summary>High-blast files modified (${blastViolations.length})</summary>`
+    );
+    out.push('');
+    for (const v of blastViolations) {
+      out.push(`- \`${v.file}\` — ${v.blast_radius} dependents (${v.severity})`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // Suggestions.
+  if (result.suggestions.length > 0) {
+    out.push(`<details>`);
+    out.push(`<summary>Suggestions (${result.suggestions.length})</summary>`);
+    out.push('');
+    for (const s of result.suggestions) {
+      out.push(`- ${s.message}`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  out.push(`<sub>Generated by [carto-md](https://www.npmjs.com/package/carto-md).</sub>`);
+  return out.join('\n');
+}
+/**
+ * renderJson(impact) → object
+ *
+ * Stable contract for programmatic consumers. Locked-in shape (any
+ * additions go at the end of the object, no key removals before a
+ * major version bump):
+ *
+ *   {
+ *     marker:                 string,
+ *     risk:                   'SAFE' | 'LOW' | 'MEDIUM' | 'HIGH',
+ *     files_changed:          number,
+ *     blast_radius_union:     number,
+ *     domains_touched:        string[],
+ *     high_impact_file:       { file, dependents } | null,
+ *     violations:             [{ kind, severity, file, message, ... }],
+ *     suggestions:            [{ kind, file, message, ... }],
+ *     per_file: {
+ *       [path]: {
+ *         blast_radius:        number,
+ *         directly_affected:   number,
+ *         domains:             string[],
+ *         routes:              [{ method, path, risk }],
+ *       }
+ *     }
+ *   }
+ */
+function renderJson(impact) {
+  const { result, perFile, domains, highImpact } = impact;
+  const per_file = {};
+  for (const [path_, detail] of perFile) {
+    per_file[path_] = {
+      blast_radius: detail.blastRadius,
+      directly_affected: detail.directlyAffected,
+      domains: detail.domains,
+      routes: detail.routes,
+    };
+  }
+  return {
+    marker: MARKER,
+    risk: result.risk,
+    files_changed: result.diff.length,
+    blast_radius_union: result.blast_radius.union,
+    domains_touched: domains,
+    high_impact_file: highImpact,
+    violations: result.violations,
+    suggestions: result.suggestions,
+    per_file,
+  };
+}
+/**
+ * Decide exit code based on --fail-on threshold.
+ *   - failOn null → always 0
+ *   - failOn set  → 2 if risk >= threshold, else 0
+ */
+function decideExitCode(risk, failOn) {
+  if (!failOn) return 0;
+  return RISK_RANK[risk] >= RISK_RANK[failOn] ? 2 : 0;
+}
+/**
+ * run({ argv, stdout, stderr }) → exitCode
+ *
+ * Pure function — no side effects on `process`. Tests pass an in-memory
+ * argv + capture stdout via a writable stream.
+ */
+function run({ argv, stdout, stderr } = {}) {
+  argv = argv || process.argv.slice(3);
+  stdout = stdout || process.stdout;
+  stderr = stderr || process.stderr;
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  if (args.help) {
+    printUsage();
+    return 0;
+  }
+  let diffText;
+  try {
+    if (args.diffFile) {
+      diffText = fs.readFileSync(args.diffFile, 'utf8');
+    } else {
+      diffText = runGitDiff(args.projectRoot, args.base, args.head);
+    }
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  let impact;
+  try {
+    impact = collectImpact(args.projectRoot, diffText);
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  if (args.format === 'json') {
+    stdout.write(JSON.stringify(renderJson(impact), null, 2) + '\n');
+  } else {
+    stdout.write(renderMarkdown(impact) + '\n');
+  }
+  return decideExitCode(impact.result.risk, args.failOn);
+}
+module.exports = {
+  run,
+  // Exported for tests:
+  parseArgs,
+  collectImpact,
+  renderMarkdown,
+  renderJson,
+  decideExitCode,
+  MARKER,
+};
+// CLI entry — when invoked directly (not required for tests):
+if (require.main === module) {
+  process.exit(run());
+}

package/src/extractors/languages/javascript.js CHANGED Viewed

@@ -95,9 +95,9 @@ module.exports = {
         _tsImports:  tsImports,
         _tsSymbols:  tsSymbols,
         // Surface the parse failure as a breadcrumb so the
-        // caller can record it in extraction_errors. Pre-Spec-11 this
-        // warning only hit stderr and the file lost all of its routes
-        // and models silently.
+        // caller can record it in extraction_errors. Before this hook,
+        // the warning only hit stderr and the file lost all of its
+        // routes and models silently.
         _errors:     [{ phase: 'parse', message: `Babel parse: ${err.message}` }],
       };
     }

package/src/mcp/change-plan.js CHANGED Viewed

@@ -8,7 +8,7 @@
  *
  *   tokenize(intent) ──► tokens { content, verbs, paths }
  *                  └──► IDF over indexed corpus (basenames + symbol names)
- *                  └──► 4-tier anchor selection
+ *                  └──► 4-stage anchor selection
  *                          A. route path/method        (searchRoutes)
  *                          B. file path tokens         (pathTokens × IDF)
  *                          C. exported symbol names    (camelTokens × IDF)
@@ -169,9 +169,9 @@ function computeIdf(store) {
  *       symbols: [{ name, path, tokenSet }] }
  *
  * Memoized on the store object. On a 5K-file repo this saves ~30ms per
- * `planChange` call (without it, p95 on cal.com sat at 60ms — over the
- * spec's 50ms target). Re-indexing creates a new store instance, so
- * the cache lives only as long as the index it was built from.
+ * `planChange` call (without it, p95 on cal.com sat at 60ms, over the
+ * 50ms target). Re-indexing creates a new store instance, so the cache
+ * lives only as long as the index it was built from.
  */
 const CACHE_KEY = '__cartoChangePlanCache';
@@ -257,7 +257,7 @@ function selectAnchors(store, tokens, idf, maxAnchors = 8) {
   // Reuse the cached corpus index — saves ~30ms p95 on cal.com.
   const corpus = buildCorpusIndex(store);
-  // ── Tier A — route path/method ────────────────────────────────────
+  // ── Stage A — route path/method ───────────────────────────────────
   // Use searchRoutes for each detected URL-path-like token. Filter by
   // verb when one was extracted.
   const routesSeen = new Set();
@@ -304,7 +304,7 @@ function selectAnchors(store, tokens, idf, maxAnchors = 8) {
     }
   }
-  // ── Tier B — file path tokens (IDF-weighted) ──────────────────────
+  // ── Stage B — file path tokens (IDF-weighted) ─────────────────────
   for (const f of corpus.files) {
     let score = 0;
     const hits = [];
@@ -339,7 +339,7 @@ function selectAnchors(store, tokens, idf, maxAnchors = 8) {
     }
   }
-  // ── Tier C — exported symbol names (camelCase split + IDF) ────────
+  // ── Stage C — exported symbol names (camelCase split + IDF) ───────
   for (const s of corpus.symbols) {
     let score = 0;
     const hits = [];
@@ -360,7 +360,7 @@ function selectAnchors(store, tokens, idf, maxAnchors = 8) {
     }
   }
-  // ── Tier D — domain name match ────────────────────────────────────
+  // ── Stage D — domain name match ───────────────────────────────────
   let domains = [];
   try { domains = store.getDomainsList() || []; } catch { domains = []; }
   for (const d of domains) {

package/src/store/sync-v2.js CHANGED Viewed

@@ -43,7 +43,7 @@ const CODE_EXTS = new Set([
 const JS_LIKE_EXTS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
 /**
- * isTestFile(relPath) → true if the file is a test/spec/stories file
+ * isTestFile(relPath) → true if the file is a test or stories file.
  * Ported from V1 detector/files.js exclusion patterns.
  *   R:      test_*, test-*, *_test.r (case-insensitive)
  *   Python: test_*.py, *_test.py
@@ -461,10 +461,16 @@ async function runSyncV2(config) {
   //    `.carto/bitmap.bin` aligned with the SQLite source of truth.
   //    Best-effort: a build/persist failure is logged but never fails the
   //    sync (MCP tools fall back to SQLite when bitmap is unavailable).
+  //
+  //    The same `sidecar` object is reused below to emit the public
+  //    ANCI v0.1 export (`.carto/anci.{yaml,bin}`) — building it twice
+  //    would be wasteful, so the build/save sequence shares scope.
+  let sidecarForAnci = null;
   try {
     const cartoDir = path.join(projectRoot, '.carto');
     const sidecar = buildBitmap(store);
     saveBitmap(cartoDir, sidecar);
+    sidecarForAnci = sidecar;
     // Drop any in-memory cache held by the same Node process — e.g. when
     // sync runs from inside `carto serve`'s lazy reparse path. Next MCP
     // query loads the freshly-saved file.
@@ -476,6 +482,22 @@ async function runSyncV2(config) {
     );
   }
+  // Emit ANCI v0.1 public export.
+  // Best-effort: failure logs to stderr, never fails the sync.
+  // Skipped when the bitmap build above failed (no sidecar to emit).
+  if (sidecarForAnci) {
+    try {
+      const cartoDir = path.join(projectRoot, '.carto');
+      const { emitToCartoDir } = require('../anci/emit');
+      emitToCartoDir({ cartoDir, sidecar: sidecarForAnci, store });
+    } catch (err) {
+      process.stderr.write(
+        `[CARTO] ANCI publish failed (anci.{yaml,bin} not written): ` +
+        `${err && err.message ? err.message : err}\n`
+      );
+    }
+  }
   console.log(`[CARTO] Indexed ${toProcess.length} files (${cached} cached) in ${elapsed}ms`);
   console.log(`[CARTO] Total: ${allFiles.length} files, ${structure.meta.totalRoutes} routes, ${structure.meta.totalImportEdges} import edges`);
@@ -487,6 +509,33 @@ async function runSyncV2(config) {
   }
   store.close();
+  // store.close() runs `PRAGMA wal_checkpoint(TRUNCATE)` which bumps
+  // carto.db's mtime to *after* we wrote bitmap.bin and anci.{yaml,bin}.
+  // bitmapIsFresh() (src/bitmap/index.js) and `carto inspect` both rely
+  // on the invariant `bitmapMtime >= dbMtime` to decide whether the
+  // sidecar can be reused or has to be rebuilt — so re-stamp the
+  // derived files explicitly past the DB's now-final mtime. Without
+  // this, every cold MCP query after a sync sees the bitmap as "stale"
+  // and pays an unnecessary rebuild from SQLite.
+  //
+  // We stat the DB and stamp bitmap/ANCI to (dbMtime + 1ms) rather than
+  // using `new Date()` because the wall clock + filesystem timestamp
+  // pipeline has sub-millisecond jitter on APFS that can leave the
+  // explicit-set mtime *just* under the DB's real mtime. Reading the
+  // DB's actual mtime and adding a fixed offset is race-free.
+  try {
+    const cartoDir = path.join(projectRoot, '.carto');
+    const dbPath = path.join(cartoDir, 'carto.db');
+    const dbStat = fs.statSync(dbPath);
+    const bumpedMs = dbStat.mtimeMs + 1;
+    const bumpedDate = new Date(bumpedMs);
+    for (const name of ['bitmap.bin', 'anci.bin', 'anci.yaml']) {
+      const p = path.join(cartoDir, name);
+      try { fs.utimesSync(p, bumpedDate, bumpedDate); } catch {}
+    }
+  } catch {}
   return { filesProcessed: toProcess.length, totalFiles: allFiles.length, elapsed, extractionErrorCount };
 }
@@ -544,8 +593,8 @@ function runKeywordClustering(store, importGraph) {
 /**
  * computeDomainStability(store, fileAssignments)
- * Compares current assignments to previous snapshot, stores drift %.
- * Warns if total>=10 && drift>5%.
+ * Compares current assignments to previous snapshot, stores reassignment %.
+ * Warns if total>=10 and the reassignment rate exceeds 5%.
  */
 function computeDomainStability(store, fileAssignments) {
   const prevRaw = store.getMeta('previous_domain_snapshot');