refactor(importer): use gitsheets transact + slug-keyed paths (closes #59)

[themightychris]

Why

PR #57's importer bypassed gitsheets and wrote raw TOML files under legacyId-keyed paths. The stated reason was "clean diffs across re-runs when slugs rename" — but nothing in the runtime consumes that property, and it cost us:

• a custom toToml() that has to mirror the lib's serializer
• a hand-rolled wipeOwnedDirectories() + writeAllRecords() filesystem layer
• a git cat-file --batch UUID-forward-read pre-pass
• a separate file-rename reconciliation step before legacy-import could merge into fixture/main (#59)

How

Use the library as designed. One store.transact per snapshot:

await store.transact({ message, author, trailers }, async (tx) => {
  for (const sheetName of importerOwnedSheets) {
    await tx[sheetName].clear();
    for (const record of translated[sheetName]) {
      await tx[sheetName].upsert(record);
    }
  }
});

• clear() empties each sheet; everything missing from the new set is gone — deletes captured for free
• upsert() writes via the sheet's path template, producing slug-keyed paths that match the runtime spec
• Zod validation runs on every record (the bare-git version skipped it once translation passed)
• Pre-pass walks the previous snapshot via store.<sheet>.query() to preserve record UUIDs across re-runs. Composite-path sheets (memberships, tag-assignments) recover legacy IDs via uuid→legacyId reverse maps built from the simple-sheet pass.

Closes #59

legacy-import → fixture is now a plain git merge, no rename step. The agent's issue #59 about the runtime-reconciliation hump is obviated.

Upstream issues filed

Found two gitsheets-side perf/semantics gaps along the way:

• JarvusInnovations/gitsheets#178 — Sheet#clear() walks + deleteChild per entry instead of pointing the subtree at git's empty-tree hash
• JarvusInnovations/gitsheets#179 — Transaction#finalize() commits whenever markMutated is set, even when the resulting tree-hash equals the parent's

The importer has a small post-transact workaround for #179 (compare tree-hash to parent, reset the ref if identical). The workaround comes out once gitsheets fixes #179 upstream.

Diff

• Importer: apps/api/scripts/import-laddr/importer.ts (~800 lines deleted, ~400 added) — see the commit body for the full inventory of deletions
• CLI: drops the --no-commit flag (gitsheets transact is atomic; --dry-run is the meaningful preview)
• Tests: 22/22 passing on the rewritten test fixture (full .gitsheets/*.toml matrix instead of just people.toml); the "modified single record" idempotence test now asserts a slug-keyed path

Live verification

Run against codeforphilly.org (--page-size=10000 --delay-ms=0):

tags                   imported=897 skipped=120 errors=0
people                 imported=31440 skipped=6 errors=0
projects               imported=268 skipped=0 errors=0
project-memberships    imported=822 skipped=1 errors=0
project-updates        imported=504 skipped=13 errors=0
project-buzz           imported=32 skipped=81 errors=0
tag-assignments        imported=10114 skipped=184 errors=0

Tree shape on legacy-import (samples):

people/chris.toml
people/a-gemm.toml
projects/transit-tools.toml
tags/topic/transit.toml
tags/tech/javascript.toml
project-memberships/actualizeme/forager.toml
tag-assignments/person/<uuid>/<uuid>.toml

Test plan

• npm run -w apps/api type-check — clean
• npm run -w apps/api test -- tests/import-laddr.test.ts — 22/22
• Full npm run -w apps/api test — running at PR creation; CI will confirm
• End-to-end live run against codeforphilly.org produces a slug-keyed tree on legacy-import
• Idempotent re-run on identical mock data → no new commit (post-transact tree-hash reset)

🤖 Generated with Claude Code