chore(river): modularity + readability cleanup across the River systems

[jiashuoz]

Readability/modularity pass across the River job systems, driven by three parallel code-review agents (cross-system interface audit + two per-package reviews). No behavior change — pure cleanup, verified by each package's existing tests. Net −124 lines.

The reviews' headline conclusion: the River systems are already well-disciplined and consistent (uniform Registrar + two-phase SetEnqueuer, principled queue routing, consumer-side narrow interfaces). These are the polish items that survived scrutiny.

1. Hoist the copy-pasted reconciler → jobs.ReconcilePending (biggest win)

The stranded-row reconciler was duplicated across 5 packages (~240 lines) with byte-identical control flow — scan WHERE <pred> AND <job_col> IS NULL → per-row FOR UPDATE re-check → enqueue → stamp. Only the table/predicate/job-column/log-prefix varied. Extracted a single jobs.ReconcilePending(pool, spec, enqueueTx) + ReconcileSpec + DefaultReconcileBatch; each package collapses to a spec literal + one call. Behavior-identical (the two store-method stampers did the exact same UPDATE the helper now inlines; those methods stay for the accept-tx path). Domain method signatures unchanged, so every caller is untouched. The reconcile invariants now live in one hot-path-tested place instead of five.

2. webhookpub dead code + docstring drift

• Deleted committed AI-scratchpad text + 3 no-op var _ compile-guards in worker.go (and the 3 imports they alone kept), the unused nowUTC, and dead oldest telemetry scaffolding.
• Fixed docstring drift: writeOutboxRow's "(eventually) PublishBestEffortTx" (already wired) + the pg_notify block now notes it's a harmless no-op in river mode; PublishBestEffortTx's reference to a webhook_publish_failures table that was never built + a "legacy-fallback" line contradicting the file itself.
• Rewrote the event.go package header (it still described the retired in-process goroutine publisher) to the current three-layer outbox→fan-out→River pipeline.
• Dropped stale internal "slice-N" markers; standardized the fan-out Kind() webhook_fan_out → webhook_fanout (safe — flag defaults legacy, no such jobs in prod yet).

3. Timeout documentation + small consistency polish

• Documented the deliberate reliance on River's 60s default JobTimeout on the workers that don't override Timeout() — so the omission reads as a decision, not an oversight (the repo has an explicit "JobTimeout trap" lesson). InboundProcessWorker notes the content screen is bounded by piguard's 5s per-detector timeout.
• jobs.New: defaultQueueConfig(cfg) instead of six positional ints (transposition hazard).
• RegisterJobs now calls the NewMaintenanceWorker constructors instead of rebuilding the struct literal (they exist precisely so tests build an identical worker).
• Named the markFailed terminal-write retry magic numbers; "legacy publisher" → "webhook publisher" in hitlworker.

Explicitly left alone (reviews confirmed these are correct, not gaps)

• The three enqueuer seams (EnqueueSendTx/EnqueueDeliveryTx/EnqueueFanOutTx) stay separate — domain-meaningful names, textbook consumer-side ISP.
• Fan-out co-located in webhookpub (shares fanOutEventCore with the outbox), delivery in webhookdelivery — the split tracks real coupling.
• Two-phase wiring, live-reconcile-vs-cutover split, queue routing — all uniform and principled.

Noted follow-ups (not in this PR)

• Post-cutover: delete the legacy OutboxWorker + webhook_events_new NOTIFY trigger (the file organization now makes this a clean delete).
• inboundprocess retention uses an unbounded DELETE (same pattern perf(janitor): batch the retention DELETEs on prod-sized tables #397 batched for the janitor) — documented, batching deferred.

🤖 Generated with Claude Code