The PDF Looked Correct Because the Template Was Wrong

The first FZE letterhead looked fine.

That was the problem.

The rendered PDF had the right legal name, the right registration label, the right address, the right contact line, and the right visual structure. It passed the visual check because every value in the template matched the entity I was testing with. Then I looked at what would happen if the same bundle rendered an LLC document.

It would still say FZE.

That failure is more dangerous than a crash. A crash stops the send path. A wrong legal identity in a PDF can leave the system looking healthy while the document is unusable. The template authoring lane had hardcoded FZE identity strings because the snapshot did not expose the fields the template needed. The implementation had chosen the fastest path to a green render instead of stopping at the missing data contract.

I was wrong to treat the template as the place where legal identity could be finished. The template is presentation. The entity row is state. The document snapshot is the contract between them.

The fix started by widening the entity surface. captureEntitySnapshot() now freezes address, registration, contact, legal names, country code, VAT identifier, officer data, brand, banking config, retention posture, and document policy into the document row. It also redacts fields that should not land on PDFs, like private tax identifiers and operational banking rollout notes.

The load-bearing part is that the snapshot always returns stable shapes. Handlebars runs in strict mode. If a template asks for entity.address.single_line, the address path must exist even when the row is old. Empty object is better than undefined because an old document can still render through the same code path.

The function is blunt about that boundary:

export function captureEntitySnapshot(row: EntityRowForSnapshot): EntitySnapshot {
  if (typeof row.id !== 'string' || row.id.length === 0) {
    throw new ValidationError('entity_snapshot_invalid', { reason: 'id missing' });
  }

  return {
    id: row.id,
    entity_id: row.entity_id,
    name: row.name,
    type: row.type,
    brand: cloneJsonLike(row.brand),
    banking_config: redactBankingConfigForDocuments(row.banking_config),
    address: cloneJsonObject(row.address),
    registration: redactRegistrationForDocuments(row.registration),
    contact: cloneJsonObject(row.contact),
    legal_name: toNullableString(row.legal_name),
    country_code: toNullableString(row.country_code),
    vat_identifier: toNullableString(row.vat_identifier),
    officers: cloneJsonObjectArray(pickOfficers(row)),
  };
}

That code does not look dramatic. It is the reason a document can be re-rendered later without asking the live entities row what the company looks like today.

The surprise was CSS. The HTML literals were obvious once I started searching. The comments in the stylesheet were not. The composer injects CSS directly into a <style> block and hashes the full rendered HTML. A comment like Klevar FZE primary is still rendered output. It becomes part of the document hash. It can leak into the PDF byte stream. It can fail an entity-neutral regression even if the visible page looks correct.

That changed the template rule: anything inside the bundle is document output. Body HTML, shared partials, stylesheet comments, labels, helper inputs. None of it gets to carry entity identity unless it comes from the snapshot or the body payload.

The renderer also became stricter in a different direction. composeHtml() uses a private Handlebars instance for each render, not the global singleton. Helpers like formatCurrency, formatDate, markdown, eq, and officerRoleLabel live inside that private instance. That prevents a test, module, or future template family from registering a helper globally and changing another document type by accident.

The snapshot fix did not end at source code. The regression had to prove the failure could not return. The gate renders every authored bundle against multiple seeded entities and searches for identity strings from the wrong entity. If an LLC render contains an FZE registration value, the test fails. If a stylesheet comment leaks a company name, the test fails. If someone adds a new bundle and hardcodes a legal name because it is faster, the gate catches it.

The deeper lesson is that PDF generation is not the domain. Legal attribution is the domain.

A renderer that accepts a body and returns bytes is easy to build. A renderer that can explain where every legal identity field came from is the system. Once I saw that, the architecture became clearer: templates do not own identity, live rows do not own old documents, and snapshots do not carry private operational fields just because the database has them.

That distinction now runs through the rest of Klevar Docs. Factur-X builder data comes from the snapshot. Board resolution officer data can default from the snapshot. Payment details freeze at issue time. Hash-chain verification depends on content hashes that include the rendered output. If a lower layer cheats, every upper layer can look correct while proving the wrong thing.

The PDF looking correct was the warning. The system only became correct when the source of correctness moved out of the template.