feat(sync): re-enrich stale detail content — --re-enrich + enrich.invalidateOn (v1.53.0)

[siddharth-bhansali]

Fixes #174 · INT-4394

Problem

For a profile that declares enrich, each record's detail endpoint was fetched exactly once, ever. Phase 2 selects only never-enriched rows (WHERE "<tsField>" IS NULL) and phase 1's upsert deliberately preserves _enriched_at, so nothing in the codebase ever cleared it.

--full-refresh did not help: it re-pulls every record from the list endpoint and reconciles deletions, but surviving rows keep their stamp — so phase 2 saw zero unenriched rows and made zero detail calls. Stale detail content was permanent, and the documented workaround was to delete .one/sync/data/<platform>.db.

Approach

@ayushsingh82's sequencing note on the issue argued for fingerprint invalidation as the default with the manual flag as the escape hatch, and that both share the same underlying "clear the stamp" path. That is what this implements — both halves, since the shared path is the bulk of the work either way.

enrich.invalidateOn — automatic, the common case. Name a list-endpoint field that moves when the detail changes (historyId for Gmail threads, updated_at for Fathom meetings). The value observed at enrich time is recorded in a _enrich_fp column; on the next sync, invalidateStaleEnrichments() clears the stamp for rows whose fingerprint moved, and phase 2 re-fetches exactly those. Records that did not change upstream cost nothing.

--re-enrich — manual, the escape hatch. clearEnrichmentStamps() unstamps everything for the model and phase 2 re-fetches all detail endpoints. One detail call per record, so it is opt-in per run and deliberately not implied by --full-refresh. For profiles with no sensible fingerprint field, or when the detail shape changed.

Additive by design. Rows with no recorded fingerprint are never auto-invalidated (_enrich_fp IS NOT NULL guard). Without it, adding invalidateOn to a built-in profile would re-enrich the user's entire table the first time they upgraded. Profiles that omit invalidateOn keep today's exact behaviour.

Also fixed

--no-memory leaked through phase 2. Phase 1 gates its memory write on options.toMemory !== false; the enrich phase's mirror ignored it and wrote anyway. This is the gap pinned by the test literally named PRE-EXISTING GAP: --no-memory does not stop phase 2 mirroring into memory, which the issue folded in as a secondary ask.

While editing the same doc section, corrected the documented enrich concurrency default from 3 to 5 — it did not match DEFAULT_CONCURRENCY.

Docs

Updated all four mandated surfaces: guide-content.ts (new "Re-enriching" section replacing the "Known gap" text, plus invalidateOn in the enrich config reference and the sync run flag row), skills/one/SKILL.md, and README.md. The "delete the mirror to force it" advice is gone from all three.

Tests

12 new tests in enrich-invalidation.test.ts, including the two guards most likely to regress: never invalidating never-fingerprinted rows, and degrading to a no-op when invalidateOn names a field the list endpoint does not return.

They drive a fake driver rather than the real one — better-sqlite3 is an optionalDependency and will not install on Node 24, so a test needing it would silently skip on the machines most likely to run it. They therefore assert the emitted SQL and the guard decisions, not SQLite's execution of them; the IS NOT null-safety and CAST(... AS TEXT) comparison are unexercised against a real database and are worth a look during review.

Verification notes

• npx tsc --noEmit passes; new suite 12/12.
• I did not run the full npm test suite: on Windows it reads and writes the developer's real ~/.one (tests sandbox process.env.HOME, which os.homedir() ignores on win32).
• Version bumped 1.52.1 → 1.53.0 (minor: new flag + new profile config key). package-lock.json version fields hand-edited rather than regenerated, since npm install on Node 24 drops the pg optional dependency from the lockfile.
• Stacks alongside fix(sync): never destroy a healthy database on a driver fault (v1.52.3) #179 (INT-4393); both branch from main and touch sync/index.ts in different places. Whichever merges second will need its version bump rebased.

🤖 Generated with Claude Code

[linear]

INT-4394