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-0021

Decision

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_type names what the notification is about — charge, handover_report, handover_response — and subject_id points at that row.
  • status is the module-wide superset pending | sent | superseded | failed. A slice that never supersedes anything simply never writes superseded.
  • One claim-and-retry worker, owned by Slice 4, drains the table with backoff. A slice contributes kind values and mail bodies, never a second retry loop.
  • There is no foreign key from subject_id to 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:
  1. It has a collision-free natural key: either a one-shot fact about its subject, or an append-only event row to anchor subject_id to.
  2. 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.
Everything else is sent after the transaction commits, fire-and-forget: a failure is logged and never rolls back the command that succeeded. Both tests matter, and the first one is not optional. Consider Slice 4: a landlord rejects a payment record, the tenant resubmits, and the landlord rejects again. Two mails are owed, but both are (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 CASCADE cannot be added retroactively across a polymorphic column.
  • A future notification kind must choose a subject_type value, not add a column.