fix(reliability): migration 064 — forwarder_sent.audit_log_id FK (closes gap #6)

[mastermanas805]

Summary

Closes CLAUDE.md Known Design Gaps #6 — `forwarder_sent.audit_id` has no FK to `audit_log(id)`, so team-deletion cascades drop audit_log rows and leave orphan ledger rows pointing at non-existent IDs.

Migration 063 (live) was an index + COMMENT only — it explicitly documented why a direct FK on `audit_id` is infeasible (TEXT vs UUID type mismatch, NOT NULL PK, legacy placeholder strings like `reminder--` from pre-consolidation emitters).

Approach: add a new nullable column `audit_log_id UUID REFERENCES audit_log(id) ON DELETE SET NULL` alongside the existing TEXT `audit_id`. The new column is the strict-FK breadcrumb; `audit_id` stays as the PK + idempotency key.

• Backfill: existing rows whose `audit_id` is a real UUID AND resolves in `audit_log` get `audit_log_id` populated. Placeholder rows + already-orphan rows leave `audit_log_id` NULL.
• Forward behaviour: future `audit_log` deletes flip `audit_log_id` to NULL via the FK rather than orphan-dangling — the ledger row itself survives (email-truth-surface, CLAUDE.md rule 12).
• Index `idx_forwarder_sent_audit_log_id_not_null` lets the orphan-reconciler join cheaply.

Files changed

• `internal/db/migrations/064_forwarder_sent_audit_fk.sql` — new migration
• `internal/testhelpers/testhelpers.go` — mirror the new column + FK + index into the test bootstrap (anti-drift guard `TestRunMigrationsMirrorsEveryMigrationTable` already iterates the migration registry)
• `internal/testhelpers/migration_064_test.go` — 5 registry-walk tests:
  • column shape (uuid, nullable)
  • FK exists with `confdeltype='n'` (= SET NULL) targeting audit_log
  • partial index exists
  • end-to-end: insert with both `audit_id` + `audit_log_id` → `DELETE FROM audit_log` → ledger row survives, `audit_log_id` is NULL
  • legacy placeholder `audit_id` strings still insert cleanly

Test plan

• `go build ./...` — green
• `go vet ./...` — green
• `go test ./internal/testhelpers/... -run TestMigration064 -v` — 5/5 PASS
• Full gate run — 3 pre-existing master failures (`TestBulkTwin_QuotaPartialFill`, `TestGetExpiredDeployments_ReturnsOnlyExpiredNonPermanent`, `TestLinkGitHubID`) confirmed on `master` baseline (stashed-changes verification); not introduced by this PR
• Operator: apply migration via standard rollout; verify `/healthz` reports `migration_version=064_forwarder_sent_audit_fk.sql`, `migration_count=63`
• Operator: `SELECT count(*) FROM forwarder_sent WHERE audit_log_id IS NOT NULL` should be > 0 after migration (= backfilled real-UUID rows)

Follow-up needed (not blocking this PR)

Worker's `event_email_forwarder.go` must be taught to populate `audit_log_id` alongside `audit_id` on insert when `audit_id` is a real UUID. Until that ships, post-064 rows leave `audit_log_id` NULL even with a valid `audit_log` target. The backfill covers existing rows; this is a forward-only behaviour gap tracked as part of the closing of gap #6.

Worker repo also needs a `worker/sql/064_forwarder_sent_audit_fk.sql` mirror (worker repo is separate; not in this PR — surface that to the next operator).

Why no direct FK on `audit_id`

Three independent blockers, all documented in migration 063 and in 064's header:

1. Type mismatch. `audit_log.id` is UUID, `audit_id` is TEXT.
2. PK NOT NULL. `audit_id` is the table's PRIMARY KEY; ON DELETE SET NULL would violate the PK on every audit_log delete.
3. Legacy placeholders. Several emit sites write synthetic placeholder values like `reminder-<resource_id>-` or `provider-<grace_id>`. A strict FK would reject those rows.

The new nullable `audit_log_id` column sidesteps all three.

🤖 Generated with Claude Code