fix(audit-wave-9): PDF correctness + brand asset hardening (pdf-auditor)

Address the pdf-auditor findings that survived the 2026-05-12 PDF stack
overhaul (pdfme → react-pdf). Items C-2/C-3 (tiptap-to-pdfme bugs) were
resolved when that 571-LOC bridge was deleted; remaining items:

- **M-7 wrong-port brand fallback** — replace `'Port Nimara'` defaults
  in PDF-rendering services. `reports.service` and `expense-export`
  throw when the port row is missing (the job is FK-keyed on a real
  port, so absence = broken state, must not stamp a competitor brand).
  `record-export` uses `'(port)'` as the visible placeholder.

- **M-2 silent field drift in fill-eoi-form** — promote the
  always-silent catch in `setText` / `setCheckbox` to log a structured
  warning per missing field (mirroring the existing `setBerthRange`
  pattern). A re-cut template with drifted AcroForm field names now
  surfaces in ops logs instead of shipping with empty values.

- **M-3 form not flattened** — `fillEoiFormFields` now flattens the
  AcroForm before save. Documenso pathway flattens server-side; this
  brings the in-app pathway to parity, so the signer can't edit
  pre-filled yacht dimensions / address / berth number after the fact.

- **M-1 PDF metadata** — set Title / Author / Subject / Lang / Producer
  / Creator on the generated EOI PDF for downstream readers and a11y
  tooling.

- **M-4 noisy berth-range warnings** — downgrade per-mooring warn to
  debug; emit a single summary warn per call when any passthrough
  occurred. Multi-berth EOIs with archived/legacy moorings no longer
  spam the log on every render.

- **M-6 source PDF sha pinning** — pin
  `assets/eoi-template.pdf` sha256 via `EXPECTED_EOI_SHA256` (exported
  for tests); `loadEoiTemplatePdf` warns once per process when the
  bytes drift without an explicit hash bump. Documented the
  intentional-update workflow in `assets/README.md`.

Tests updated in `tests/unit/pdf/fill-eoi-form.test.ts` to reflect
flatten + metadata (form fields are gone after flatten; pdf-lib has no
getLanguage so we assert the other setters round-trip).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/pdf/fill-eoi-form.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
@@ -6,6 +7,17 @@ import { PDFDocument } from 'pdf-lib';
 import type { EoiContext } from '@/lib/services/eoi-context';
 import { logger } from '@/lib/logger';
 
+/**
+ * Pinned sha256 of `assets/eoi-template.pdf`. Bump this AND the README
+ * checksum in lockstep when the template is intentionally re-cut. A
+ * mismatch only logs a warning (we don't want a malformed swap to take
+ * the EOI flow offline at boot), but ops monitoring will surface it.
+ */
+export const EXPECTED_EOI_SHA256 =
+  'ba495fd88d99ebe4b7f61acbe397fb2f1cd116e1e1f1b217de93106915c7c44b';
+
+let shaCheckPerformed = false;
+
 /**
  * Source PDF for the in-app EOI pathway. Must contain AcroForm fields whose
  * names match the Documenso template's `formValues` keys exactly:
@@ -25,13 +37,32 @@ function eoiTemplatePath(): string {
 
 export async function loadEoiTemplatePdf(): Promise<Uint8Array> {
   const filePath = eoiTemplatePath();
+  let bytes: Buffer;
   try {
-    return await fs.readFile(filePath);
+    bytes = await fs.readFile(filePath);
   } catch (err) {
     throw new Error(
       `EOI source PDF not found at ${filePath}. Drop the same PDF used by the Documenso template (with AcroForm fields: Name, Email, Address, Yacht Name, Length, Width, Draft, Berth Number, Lease_10, Purchase) at this path, or override via EOI_TEMPLATE_PDF_PATH. Original error: ${(err as Error).message}`,
     );
   }
+
+  // SHA-pin check (M-6): warn once per process when the template's bytes
+  // don't match the committed hash. Skipped entirely when the override
+  // env var is in play (fixture / dev workflows are expected to use
+  // arbitrary PDFs). Only checks the default path so test setups stay
+  // unconstrained.
+  if (!shaCheckPerformed && !process.env.EOI_TEMPLATE_PDF_PATH) {
+    shaCheckPerformed = true;
+    const actual = createHash('sha256').update(bytes).digest('hex');
+    if (actual !== EXPECTED_EOI_SHA256) {
+      logger.warn(
+        { expected: EXPECTED_EOI_SHA256, actual },
+        'EOI source PDF sha256 mismatch — template was modified without an EXPECTED_EOI_SHA256 bump. Update assets/README.md + EXPECTED_EOI_SHA256 in lockstep if this was intentional.',
+      );
+    }
+  }
+
+  return bytes;
 }
 
 function formatAddress(address: EoiContext['client']['address']): string {
@@ -43,9 +74,18 @@ function setText(form: ReturnType<PDFDocument['getForm']>, name: string, value:
   try {
     form.getTextField(name).setText(value);
   } catch {
-    // Field absent or wrong type - skip silently so a slightly different PDF
-    // template still produces output. Missing field issues surface in QA, not
-    // at runtime as a 500.
+    // Field absent or wrong type - skip so a slightly different PDF
+    // template still produces output, but surface a warning so a re-cut
+    // template with drifted field names is observable in ops logs
+    // instead of shipping silently with empty values. Only warn when
+    // there's a real value to render; an empty value would be a no-op
+    // even if the field existed.
+    if (value && value.trim().length > 0) {
+      logger.warn(
+        { field: name },
+        `EOI in-app PDF template is missing AcroForm field "${name}" — value was dropped. Update the source template.`,
+      );
+    }
   }
 }
 
@@ -81,7 +121,10 @@ function setCheckbox(
     if (checked) cb.check();
     else cb.uncheck();
   } catch {
-    // See comment in setText.
+    logger.warn(
+      { field: name, checked },
+      `EOI in-app PDF template is missing checkbox AcroForm field "${name}" — checkbox state was dropped. Update the source template.`,
+    );
   }
 }
 
@@ -90,8 +133,11 @@ function setCheckbox(
  * EoiContext. Field names mirror the Documenso template `formValues` keys so
  * a single source PDF can serve both pathways.
  *
- * The form is left interactive (not flattened) so a recipient can still tweak
- * fields if needed before signing.
+ * The form is **flattened** after filling so the recipient can't edit
+ * pre-filled values (yacht dimensions, address, berth number) after the
+ * fact. Documenso pathway flattens server-side; this brings the in-app
+ * pathway to parity. Set metadata so the artifact carries Title/Author/
+ * Lang for downstream readers and a11y tooling.
  */
 export async function fillEoiFormFields(
   pdfBytes: Uint8Array,
@@ -121,6 +167,17 @@ export async function fillEoiFormFields(
   setCheckbox(form, 'Purchase', true);
   setCheckbox(form, 'Lease_10', false);
 
+  // PDF metadata so the artifact carries Title/Author/Lang downstream.
+  doc.setTitle(`EOI – ${context.client.fullName}`);
+  doc.setAuthor(context.port.name);
+  doc.setSubject('Expression of Interest');
+  doc.setLanguage('en-GB');
+  doc.setProducer('Port CRM');
+  doc.setCreator('Port CRM');
+
+  // Flatten so the signer can't edit pre-filled values after the fact.
+  form.flatten();
+
   return doc.save();
 }