feat: deterministic investor statement PDF generator with signed hash

[Mhidesav]

What this fixes

Implements #874 — Build investor statement PDF generator with deterministic layout and signed hash.

Investors receive quarterly statements (positions, distributions, fees, tax classifications) as PDFs. This PR adds the full pipeline:

1. DefaultStatementDataProvider assembles statement content from token_balance_snapshots, investments, distributions/distribution_payouts, revenue reports, and immutable investment lots — with deterministic ordering everywhere.
2. renderStatementPdfWithContent renders a byte-deterministic, frozen-layout PDF: the output is a pure function of (job metadata, statement content, watermark state, ledger revision hash). No wall-clock values, random bytes, or locale-dependent formatting are ever embedded, so regenerating a statement yields the same sha256.
3. Persisted hash: the batch worker's checkpoint (pdf_render_jobs row = (statement_id, sha256, generated_at) via id, checksum, updated_at) is the source of truth.
4. GET /statements/:periodId/:investorId re-computes sha256 over the stored bytes on every fetch and serves 200 application/pdf (with X-Statement-Sha256 + ETag) only on a match; a mismatch returns 409 CONFLICT and a security-relevant statement.tamper-detected log.

Root cause

There was no statement generator at all: no content assembly, no deterministic renderer, no persisted artifact hash, and no fetch path that could serve (or verify) a statement. The pre-existing renderStatementPdfDetails (#487 watermark/version-stamp work) renders only job metadata and is not content-aware, and nothing re-verified artifact integrity before serving.

The fix and why

• Determinism by construction, not by convention. Every collection is defensively re-sorted inside the renderer with stable comparators (localeCompare for text, numeric comparison for decimal strings, Date.getTime() for timestamps), so byte-identical output holds even if a provider returns rows in a different order. Dates render via Date.toISOString() (UTC, fixed-width); amounts pass through as decimal strings. generatedAt is never embedded.
• No font/runtime drift ("frozen fonts"). The renderer is text-based with fixed column separators — no external font metrics or engine dependency, so output cannot drift across hosts or OS updates.
• Tamper detection at the boundary. The persisted checksum is compared with a fresh sha256 on every fetch. Bytes are never served without passing that check. A pending/failed render is never served (findCompletedByInvestorAndPeriod returns only completed rows).
• Shared security logic. Watermark suppression (Ed25519 treasury signature verification, audit emission, security-relevant logging) lives in exactly one place (evaluateWatermarkState) used by both the legacy details renderer and the new content renderer, so the security behavior can't diverge.
• Additive, backward-compatible data layer. New repository methods (findByHolderAndPeriod, listByPeriod, listPayoutsByInvestorForPeriod, listPayoutsByPeriod, findCompletedByInvestorAndPeriod) use deterministic ORDER BYs and touch no existing tables. The existing renderStatementPdfDetails / makeStatementRenderFn API is unchanged.

Alternatives considered:

• Embedding generatedAt or a timestamp for versioning — rejected: breaks byte determinism and the archival hash contract.
• Serving bytes with only a stored-hash lookup (no re-verification) — rejected: doesn't detect storage drift or tampering; the issue explicitly requires hash verification at fetch time.
• A heavy headless-browser/HTML renderer — rejected: introduces font/metrics drift, higher attack surface, and violates the "frozen layout" requirement; the text-based layout is fully deterministic and sufficient for archival statements.

Security & failure-mode handling

Scenario	Behaviour
No completed job for (investor, period)	404 NOT_FOUND
Job completed but artifact missing from storage	404 NOT_FOUND
Stored bytes hash ≠ persisted checksum	409 CONFLICT + statement.tamper-detected log (never serves untrusted bytes)
Storage read error	500 — internal message not leaked to the client
Unauthenticated	401 (identity comes only from the verified JWT; headers never trusted)
Investor fetching another investor's statement	403 (IDOR boundary enforced)
Non-privileged, non-investor roles (e.g. startup)	403 — issuers cannot enumerate investor statements
Whitespace-only / oversized path params	400 (validated: non-empty, ≤ 128 chars)
Worker crash mid-render	Row stays processing, reclaimed after stale window; re-render is byte-identical (deterministic storage key)
Transient render failure	Back to pending with backoff; retried render is byte-identical
PDF injection via statement text	Renderer escapes PDF string literals (\, (, )) and collapses newlines in free text
Log leakage	Tamper/audit logs use non-PII fragments; never full artifact contents

Acceptance criteria → code & tests

• Implemented across src/services/balanceSnapshotService.ts / src/db/repositories/distributionRepository.ts with a clear contract — the data lineage is documented in docs/investor-statement-deterministic-pdf.md; content assembly lives in src/services/statementDataProvider.ts, persistence queries in src/db/repositories/{balanceSnapshot,distribution,pdfRenderJob}Repository.ts.
• Security/authorization/validation/integrity enforced + tested — src/routes/statements.test.ts (401/403/IDOR/400/404/409/500, tamper rejection, storage-not-called-on-missing-job).
• Failure/retry/concurrency/boundary behaviour explicit — findCompletedByInvestorAndPeriod serves only completed rows; pdfRenderJobRepository.test.ts covers claim/markCompleted/markFailed/reclaim paths; deterministic re-render keeps crash recovery byte-identical.
• Regression coverage for empty, invalid, duplicate, boundary inputs — zero-distribution periods, mid-period transfers, out-of-window investments, missing revenue/tax-lot data, unsorted provider rows, PDF-unsafe text, empty storage, missing checksum.
• Existing API/storage/deployment compatibility preserved — additive repository methods only; no table changes; legacy render API untouched; storage defaults to InMemoryStatementPdfStorage (fail-safe 404 until an S3-backed adapter is deployed).

How it was tested

• Focused suites (all pass, run repeatedly): statementDataProvider.test.ts, statementPdfService.test.ts, statements.test.ts, pdfRenderJobRepository.test.ts, balanceSnapshotRepository.test.ts, distributionRepository.test.ts — 108 tests, 6 suites.
• Coverage on new code: statements.ts 97.7% lines, statementDataProvider.ts 95.4%, statementPdfService.ts 95.9%, pdfRenderJobRepository.ts 100% (≥ 95% target).
• Determinism tests: identical inputs → identical sha256; mutated content → different sha256; generatedAt never embedded (mutating it does not change bytes); unsorted provider rows → sorted, byte-stable output.
• Tamper tests: corrupted stored bytes vs persisted checksum → 409 CONFLICT; artifact never served on mismatch.
• Type check: tsc --noEmit reports no new errors in any touched file (the repo carries 500+ pre-existing errors in unrelated modules on master).
• Lint: new code is lint-clean (the repo's ESLint 9 vs .eslintrc.cjs config mismatch is pre-existing and fails identically on master; new files were linted in legacy mode).
• CI gates: npm run validate:alert-mappings ✅; npm run audit:ci behaves identically to master.
• Full suite: master itself has 56 pre-existing failing suites / 322 failing tests (unrelated modules, e.g. validateZodParams is not a function, changePassword type drift). Our branch adds exactly 2 new suites (both pass) and no new consistent failures. Running the full suite also exposes a pre-existing ts-jest 29.4.x + Jest 30 incompatibility that intermittently crashes the transformer on random suites (reproduced on master too) — not introduced here.

Compatibility & migration

• No migrations required; no existing tables altered. pdf_render_jobs.checksum continues to be the persisted hash.
• The fetch endpoint is additive and fail-safe: without a deployed storage adapter, requests 404 (no artifacts exist) rather than failing open.
• Follow-up (out of scope): a durable S3-backed StatementPdfStorage adapter so completed renders survive across instances, and wiring the batch worker (already checkpointing pdf_render_jobs) to the content renderer.

Follow-ups worth filing separately

1. S3-backed StatementPdfStorage adapter — required before the fetch endpoint can serve real artifacts in production (currently InMemoryStatementPdfStorage).
2. Fix the ts-jest 29.4.x + Jest 30 transformer incompatibility that makes the full-suite run intermittently crash suites (pre-existing; affects CI determinism repo-wide).
3. Repair the repo's ~500 pre-existing tsc errors and 56 pre-existing failing suites on master (unrelated to statements) so npm test/npm run build can be green gates.

---

Closes #874