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

Decision

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 to rental_contacts do 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 from issued_at (and from completed_at for the composite), the font is a file committed to the repo rather than a system font, and signatures are ordered by signed_at with signer_role as the tie-break.
  • Each signature stores the hash it saw. rental_agreement_signatures.document_sha256 is 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_version is metadata. It records which reviewed form produced the document and which snapshot shape terms uses. 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 terms cannot be edited; the only fix is void and re-issue. This is why NRIC is normalized and validated at write time on rental_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 TZ values and assert one SHA-256. A single-render test would not exercise the thing most likely to break.