fix(canonical): serialize junction observation_count with KeyedMutex + add removeObservation

[sroussey]

Summary

The four canonical junction repos (CanonicalPersonAddressRepo, CanonicalPersonPhoneRepo, CanonicalCompanyAddressRepo, CanonicalCompanyPhoneRepo) did get(pk) -> mutate observation_count -> put(row) without serialization. Two concurrent EntityObserver.observePerson calls resolving to the same canonical_person_id for the same address/phone raced their increments; one was lost. The reap path introduced in #175 amplifies this: removeObservation decrements race the same code.

The fix

• Wrap recordObservation and removeObservation in a module-scoped KeyedMutex<string> inside each of the four junction repos.
• Key shape: serialized composite PK with \x00 sentinel (never occurs in a UUID / address hash / E.164 number / semver, so distinct PKs can't collide):
  • address junctions -> ${canonical_(person|company)_id}\x00${address_hash_id}\x00${resolver_version}
  • phone junctions -> ${canonical_(person|company)_id}\x00${international_number}\x00${resolver_version}
• Lock scope is get + put only. The resolver call in EntityObserver already sits outside the junction critical section, so no head-of-line blocking of resolves.
• Four separate module-level mutexes (one per repo file) so distinct junction kinds never contend with each other.
• Different composite PKs still run concurrently.

removeObservation

removeObservation(pk) (the inverse of recordObservation) is already present on all four repos and is what the reaper calls. It stays no-op when the row doesn't exist (idempotent replays), decrements when observation_count > 1, and deletes when <= 1. The mutex now serialises it too, so concurrent record + remove for the same PK can't lose an update.

Tests

• Canonical{Person,Company}{Address,Phone}Repo.concurrency.test.ts (4 files):
  • 100 concurrent recordObservation for the same PK -> final observation_count === 100.
  • 50 seeded + interleaved 50 record + 50 remove -> final observation_count === 50 (net zero delta).
  • N concurrent records on distinct PKs -> a barrier-in-put proves no head-of-line blocking across keys.
• Canonical{Person,Company}{Address,Phone}Repo.removeObservation.test.ts (4 files):
  • decrements when > 1; deletes when === 1; no-op when absent.
• EntityObserver.concurrency.test.ts:
  • Two concurrent observePerson calls for the same canonical + same address -> observation_count === 2.

Verification

• bun test src/storage/canonical/ -> 94 pass.
• bun test src/resolver/ -> 66 pass.
• bun test src/task/forms/ProcessAccessionDocFormTask -> 14 pass.
• bunx tsc --noEmit -> clean.
• bun test (full suite) -> 1453 pass, 7 pre-existing network fetch-index test timeouts (FetchQuarterlyIndexTask / FetchDailyIndexTask) unrelated to this change.

Test plan

• CI green
• bun test src/storage/canonical/ locally
• bun test src/resolver/ locally

---

Generated by Claude Code

[sroussey]

Integrated into #176. The four junction repos' KeyedMutex-serialized recordObservation/removeObservation (+ concurrency/removeObservation tests) are carried forward verbatim (clean merge — #176 doesn't touch these repos). Composes correctly with #176's #175-derived reap path; storage/canonical (94), resolver (66), and task/forms (16) all pass. Closing in favor of #176.

---

Generated by Claude Code