Reconcile BusinessEvent and the trail (C1–C6)

[bagnier]

Reconciles the BusinessEvent type with the append-only trail it is persisted to and delivered off, following the six-chantier plan. One PR, one commit per chantier (+ CI fix-ups).

Status — all six landed

• C1 — one serialized shape, closed by a round-trip. Four hand-kept field lists derive from one LIFTED_COLUMNS source; a parametrised round-trip test closes the property; dispatched_at's off-model status made explicit.
• C2 — the delivered event is self-descriptive and correlated. created_at (the fact's own instant, DB-assigned) rebuilds onto the delivered event; request_id + the fact's event_id bind onto the reaction's structlog context.
• C3 — a secret can't enter a fact. Refused at __init_subclass__ with an alternative in the message; broader underscore-insensitive denylist; api_key_id pk-references carved out; removed the old token: uuid.UUID type-lie.
• C4 — the trail's only writer is a controlled function; raw INSERT retired. See note.
• C5 — no fact lost in silence. Unroutable kind and unrebuildable spread facts surface as console Issues (log.exception → capture seam); the cursor still advances.
• C6 — truth hygiene. BusinessEventLog → BusinessEventRecord; dead _FALLBACK_ICON removed; models.py docstring made true.

On C4

The plan said "revoke the grant, the only writer is the admin session" — impossible as written: the request path records the fact on the caller's own RLS (authenticated) session, atomically with the mutation, and PostgREST uses that same authenticated role, so the grant can't be denied to PostgREST without breaking legitimate emit.

C4 realizes the goal — the trail's arbitrary-write capability is retired — with a SECURITY DEFINER writer function record_business_event(...):

• It inserts as its owner, so the request session needs no table INSERT grant and still writes inside its own transaction (atomicity kept).
• The raw grant insert + the self-attributed policy are dropped, so authenticated (hence PostgREST) can no longer POST /rest/v1/business_events — the arbitrary-row capability the plan set out to remove.
• The function does not re-check user_id = auth.uid(). That invariant can't live in the DB: a business event is a durable fact whose legitimate emitters routinely attribute it to an actor other than the calling session's identity (a durable consumer re-emitting on behalf of the original actor, a detached emit with no session, seeders attributing to an org's members). The session identity and the fact's actor are decoupled by design — attribution is the emitter's responsibility (each emit names the actor), and the DB's job here is to be the single writer.
• Clone-safe: it lives in public and targets public.business_events, so provision_schema.py rewrites it into each worktree schema exactly like the signup trigger.

CI journey (drive-to-green)

1. First red: ty only (tests passed) — C2's created_at broke todo's **scope splat → made explicit.
2. Second red: 18 e2e failures — an early self-attribution check in the writer function rejected legit background/durable emits.
3. Third red: 7 left after a first attempt (clearing the admin worker's RLS context) — same root cause on the as_actor consumer path.
4. Resolved by dropping the self-attribution check entirely (above) and reverting the worker change.

The local sandbox only had Python 3.14.0rc2 (pyproject pins ~=3.14.6), so DB/e2e tests run in make ci, not locally.

🤖 Generated with Claude Code