feat(enrichment-worker): scaffold CDC consumer + claim primitive (BS#892 PR-1)

[jakebromberg]

First PR of BS#892 (Epic C C2). Stands up the apps/enrichment-worker/ package with the log-only CDC dispatcher and the atomic claim primitive that the N×N consumer cardinality depends on. No DB writes; no LML calls — that's PR-2.

Why split

The keystone consumer is too big for one PR (acceptance: package + dispatcher + claim + LML wiring + finalize + SSE broadcast + two-consumer integration test). Splitting lets the dispatch path be verified in prod (deploy this PR, watch the would-enrich logs flow on real CDC traffic) before any write-side risk.

PR-2 (follow-up): swap the log-only handler for claim → @wxyc/lml-client.lookupMetadata → finalize UPDATE → SSE broadcast (also closes #893/#628). The two-consumer integration test from #892 acceptance also lands in PR-2 since it needs the full pipeline.

What's in this PR

• apps/enrichment-worker/claim.ts — claimRowForEnrichment(id). Atomic UPDATE flowsheet SET metadata_status='enriching', enriching_since=now() WHERE id=$1 AND metadata_status='pending'. Race-free across N consumer instances: the first claimer wins, every sibling sees 0 rows and skips. Returns { claimed: true, id } or { claimed: false }.
• apps/enrichment-worker/cdc-subscriber.ts — filterForEnrichment(event) + makeLogOnlyHandler(). The filter is the perimeter for which CDC events the consumer acts on: flowsheet INSERT, entry_type='track', metadata_status='pending', non-empty artist_name, numeric id.
• apps/enrichment-worker/worker.ts — entrypoint. Starts the LISTEN connection via @wxyc/database's shared startCdcListener() and registers the log-only handler. Graceful SIGTERM/SIGINT shutdown closes the LISTEN connection and the DB pool cleanly.
• Package scaffold — package.json (@wxyc/enrichment-worker), tsconfig.json (references shared/database), tsup.config.ts (ESM, node20, single-file output).
• tests/mocks/database.mock.ts — adds metadata_status + enriching_since to the flowsheet mock so the new primitive's .set() typechecks under the existing Drizzle mock moduleNameMapper.
• CLAUDE.md — new package row.

CDC fan-out audit (acceptance pre-condition)

Documented inline in cdc-subscriber.ts's file header so the next reader can trust the dispatch path:

• cdc-listener.ts:43-49 opens a per-process postgres() client — no pool collapse across N BS instances or N workers. Each Node process gets its own LISTEN connection; PG pg_notify broadcasts to every listener.
• cdc-websocket.ts:89-99 is pure fan-out — no upstream dedup or coalescing of events.
• pg_notify is fire-and-forget per docs/cdc.md:25; a worker that drops its LISTEN connection misses events until reconnect with no replay endpoint. The C6 cron is the mandatory complement, not optional safety net.

This validates the N×N cardinality decision in #892's body. No fallback to N×1 leader election needed.

Tests

• tests/unit/apps/enrichment-worker/claim.test.ts — 5 tests pinning the claim contract: pending row claimed; WHERE narrows by id + metadata_status='pending'; sibling-claimed no-op; terminal-state no-op; DB errors propagate.
• tests/unit/apps/enrichment-worker/cdc-subscriber.test.ts — 11 tests pinning the filter perimeter: happy path + every skip case from the documented criteria (non-flowsheet, UPDATE, DELETE, null data, non-track entry_type, already-claimed metadata_status, null/empty artist_name, non-number id, null/undefined album_title/track_title coercion). Plus 1 test for makeLogOnlyHandler behavior.

Pre-flight

• npm run typecheck — clean
• npm run lint — 0 errors, 422 warnings (none new)
• npm run format:check — clean
• npm run build --workspace=@wxyc/enrichment-worker — clean
• npm run test:unit — 2070/2070 pass

Out of scope (PR-2)

• LML wiring + finalize UPDATE
• SSE broadcast (closes #893 / #628)
• Two-consumer integration test ([C2] Build CDC-driven enrichment consumer (separate worker) #892 acceptance)
• Sentry instrumentation
• Backpressure (LML semaphore + token bucket — but @wxyc/lml-client carries its own per BS#906/G4)
• Dockerfile + EC2 cron entry (deployment plumbing)

Related

• Parent: #877 (Epic C)
• Sibling children blocked on the full consumer: #893 (C3 SSE), #894 (C5 drop fire-and-forget), #895 (C6 cron retune), #896 (C7 ETL CDC verification)
• Predecessor: BS#891 / PR #1004 — metadata_status enum column (merged 2026-05-22)
• Spine context: post-launch service hardening project #32