ADR-0062: One Rental-wide rental_notification_events table with a polymorphic subject
Status
Accepted (2026-09-01)Tags
rental, notifications, email, retry, idempotency, data-model, schema, foreign-keys, duplication, adr-0055, adr-0021Decision
Every durable Rental notification — payment reminders, the day 7 late-notice signal, and the move-in Handover Report’s review and finalization mails — lives in one table, defined by Slice 4 and reused unchanged by Slice 5 and later slices:subject_typenames what the notification is about —charge,handover_report,handover_response— andsubject_idpoints at that row.statusis the module-wide supersetpending | sent | superseded | failed. A slice that never supersedes anything simply never writessuperseded.- One claim-and-retry worker, owned by Slice 4, drains the table with backoff. A slice
contributes
kindvalues and mail bodies, never a second retry loop. - There is no foreign key from
subject_idto its parent. This is the one table in an otherwise FK-enforced Rental schema without one.
Why
Slice 4 and Slice 5 independently designed the same twelve columns —attempt_count, next_attempt_at, last_error, provider_message_id, sent_at, and the
rest — around different anchor columns. Keeping both would have meant two migrations, two
repositories, two claim-with-backoff queries, two retry workers, and two sets of retry
tests for one behaviour. Retry-with-backoff is exactly the case where an abstraction earns
its keep: delete it and the complexity does not vanish, it reappears in every slice that
sends mail nobody is watching.
The polymorphic subject also removed a wart rather than adding one. Slice 5’s private table
carried report_id and source_response_id side by side, which forced two partial unique
indexes because report-grain rows and response-grain rows shared one table. A single
(subject_type, subject_id) pair gives the whole module one uniform natural key.
The missing foreign key is the price and is accepted knowingly. It is safe here because
nothing in Rental hard-deletes a parent — a cancelled charge keeps its row and a finalized
report is immutable, so both are status and snapshot facts rather than deletes — and
because these rows are inserted and then updated in place, never joined for referential
integrity. The repository carries a ponytail: comment naming the absent FK so the next
reader recognises a decision rather than an oversight.
Which notifications belong in this table
A notification is durable — a row here, retried with backoff — only when both hold:- It has a collision-free natural key: either a one-shot fact about its subject, or an
append-only event row to anchor
subject_idto. - Losing it costs the recipient something they cannot recover by opening the app — typically because a clock is running that they have no reason to go and look at.
(payment_record, <same id>, payment_rejected, tenant) — the unique key
collapses them and the second rejection never sends. Slice 4 keeps payment-record state in
columns (§6.3) and has no append-only event row to anchor a second occurrence to, so its ten
action-triggered mails stay fire-and-forget. Adding an events table in order to send email
was rejected: that is a table serving the transport, not the domain, and each of those mails
follows a click the recipient’s counterparty has just made in a shared ledger.
Slice 5’s four handover kinds satisfy both tests, which is why they are all durable.
review_opened, review_due_soon, and report_finalized are one-shot per report, and
landlord_response anchors on the append-only response row so a second reply in the same
thread is a second row. review_opened also fails test 2 loudly if lost: it starts the
tenant review deadline against a tenant who has no reason to log in, and the report would
finalize as “no tenant response” for someone who was never told.
Considered alternatives
Two feature-owned tables (rental_payment_reminder_events,
rental_handover_notification_events), each with a real foreign key. Rejected: it buys FK
integrity on rows that are never joined, and pays for it with a duplicated retry worker
that will drift — the second copy is where the backoff bug lives that the first copy
already fixed.
A platform-wide notification table outside Rental. Rejected as premature. Nothing
outside Rental needs it today, and ADR-0021’s rental_ prefix keeps module isolation at
the table level. If a second module ever wants this shape, that is the moment to promote
it, not now.
Consequences
- Slice 4 must define the table in its generalised form before Slice 5 begins; doing this after either slice ships means a data migration instead of a paragraph.
- Orphan rows are possible in principle. If a parent ever becomes deletable, this table
needs an explicit cleanup path — a
DELETE CASCADEcannot be added retroactively across a polymorphic column. - A future notification kind must choose a
subject_typevalue, not add a column.