ADR-0058: Tenancy agreement PDFs are frozen at issue, not rendered on demand
Status
Accepted (2026-08-26)Tags
rental, legal, pdf, immutability, audit-trail, data-model, storage, adr-0055, adr-0059Decision
When a landlord accepts an offer, the tenancy agreement PDF is rendered once, stored, and hashed. That object never changes, and both parties sign that exact file.- The terms are snapshotted.
rental_tenancy_agreements.terms(jsonb) holds rent, dates, deposit months, special conditions, and both parties’ full name, NRIC, and address as they were at the moment of issue. Later edits torental_contactsdo not reach an issued agreement. - The document is content-addressed. The storage key is the SHA-256 of the rendered
bytes (
rental/agreements/<sha256>.pdf). Rendering and upload happen before the database transaction, so a rollback leaves no half-issued agreement and a retry writes the same key rather than an orphan object. - The renderer is byte-deterministic. Every source of drift is pinned: dates render in
a fixed
Asia/Kuala_Lumpur, the PDF creation date comes fromissued_at(and fromcompleted_atfor the composite), the font is a file committed to the repo rather than a system font, and signatures are ordered bysigned_atwithsigner_roleas the tie-break. - Each signature stores the hash it saw.
rental_agreement_signatures.document_sha256is recorded per signature, not only on the agreement row. - There is no edit. Changing an issued agreement means voiding it and issuing a new one, which is also how paper works.
template_versionis metadata. It records which reviewed form produced the document and which snapshot shapetermsuses. Nothing reads it to decide behaviour, because an old version never needs re-rendering.
Why
The cheaper design is to keep the agreement as data and render it fresh on every view. It has a hole that only shows up in the one situation the whole feature exists for. Two parties sign at different times — that is the normal case, not an edge case. If the template wording or the rendering code changes between the first signature and the second, the two parties signed different documents, and the question “what exactly did I sign?” has no reliable answer. The freeze is what makes the audit trail worth anything; without it, the trail records signatures against a moving target. Storing the hash per signature rather than once on the agreement is the same argument one level down. If the two ever disagree, the document moved, and that becomes detectable rather than deniable. Determinism is not a nicety here, because the hash is the storage key. A non-deterministic renderer would scatter the same agreement across multiple keys and make the golden test flap on CI.gofpdf stamps the current time by default, which alone would do it.
Considered options
- Render on demand from
terms— rejected. Cheaper and one less stored object, but loses the guarantee above the moment the renderer or template changes. - Render on demand and version the template in a registry — rejected. Fixes the correctness hole by keeping every historical template renderable, at the cost of a registry, a migration path for old templates, and rendering code that must stay bug-compatible with its own past. The freeze gets the same guarantee for one stored file.
- Store the PDF under a random or row-id key — rejected. Needs an orphan-cleanup path when the issue transaction rolls back, and cannot deduplicate a retry.
- Render and upload inside the database transaction — rejected. Holds a Postgres transaction open across a network upload, and a rollback still leaves the uploaded object behind, so it buys atomicity it does not actually deliver.
Consequences
- Two objects per agreement. The frozen unsigned document (
document_key) and the final composite with its signature page (signed_document_key). The composite is generated lazily on first download and is also content-addressed, so simultaneous downloads by both parties converge on one object instead of racing. - A typo is expensive. A wrong NRIC or name frozen into
termscannot be edited; the only fix is void and re-issue. This is why NRIC is normalized and validated at write time onrental_contacts, and why signing compares normalized values rather than raw strings. - Storage grows monotonically. Agreement objects are legal records and are never deleted, including when a user deletes their account.
- The golden test must render twice under two different
TZvalues and assert one SHA-256. A single-render test would not exercise the thing most likely to break.