fix(audit): non-Documenso backlog sweep — port-binding, NULLS NOT DISTINCT, custom merge tokens, company docs

Wave through the remaining audit-final-deferred items that aren't blocked
on the back-burnered Documenso work.

Multi-tenant isolation:
- Storage proxy ProxyTokenPayload gains optional `p` (port slug) claim;
  verifier asserts `key.startsWith(${p}/)`. Defense-in-depth against a
  buggy issuer in some future code path that mixes port scopes — every
  storage key generated by generateStorageKey() already prefixes the
  slug. document-sends opts in for 24h emailed download links; other
  callers continue working unchanged via the optional field.

DB schema reconciliation:
- Migration 0047 rebuilds system_settings unique index with NULLS NOT
  DISTINCT (Postgres 15+) so global settings (port_id IS NULL) are
  uniquely keyed by `key` alone. Surfaced + dedupe'd 65 duplicate
  (storage_backend, NULL) rows that had accumulated from race-prone
  delete-then-insert patterns in ocr-config / settings / residential-
  stages / ai-budget services. All four services converted to true
  onConflictDoUpdate upserts so the race window is closed.

API uniformity:
- Response shape standardization: 16 routes converted from
  `{ success: true }` to 204 No Content. CLAUDE.md documents the
  convention (`{ data: <T> }` for content, 204 for empty mutations,
  portal-auth retains `{ success: true }` for the frontend's auth chain).
- req.json() → parseBody() migration across 9 admin/CRM routes
  (custom-fields, expenses/export ×3, currency convert,
  search/recently-viewed, admin/duplicates, berths/pdf-{upload-url,
  versions, parse-results}). Uniform 400 error shapes for
  ZodError-flagged bodies.

Custom-fields merge tokens (shipped end-to-end):
- merge-fields.ts gains CUSTOM_MERGE_TOKEN_RE + helpers for the
  `{{custom.<fieldName>}}` shape.
- document-templates validator accepts the dynamic shape alongside
  the static catalog tokens.
- document-sends.service mergeCustomFieldValues resolver fetches
  per-port custom_field_definitions for client/interest/berth contexts
  and substitutes stored values keyed by `{{custom.fieldName}}`.
- custom-fields-manager amber banner updated to reflect that merge
  tokens now expand (search index + entity-diff remain documented
  design limitations).

/api/v1/files cross-entity filtering:
- Validator + listFiles + uploadFile accept companyId AND yachtId
  alongside clientId. file-upload-zone propagates both.
- New CompanyFilesTab component mirrors ClientFilesTab; restored as a
  visible Documents tab in company-tabs.tsx (was a hidden stub).

Inline TODOs:
- Reviewed remaining two TODOs (per-user reminder schedule, import
  worker handlers). Both are placeholders for future feature surfaces,
  not bugs — per-port digest works for every customer; nothing
  currently enqueues import jobs (verified). Annotated in BACKLOG.

BACKLOG.md updated to reflect what landed and what's still pending
(Documenso-related items still bundled with the back-burnered phases).

Tests: 1185/1185 vitest, tsc clean.

src/lib/db/migrations/0047_system_settings_nulls_not_distinct.sql

@@ -0,0 +1,34 @@
+-- Reconcile the system_settings unique-index drift surfaced in the
+-- final-deferred audit. The Drizzle schema declares a uniqueIndex on
+-- (key, port_id), but Postgres treats NULL values as distinct by default.
+-- That means two rows with `(same_key, NULL)` would BOTH be allowed —
+-- a global-setting collision the index claims to prevent.
+--
+-- This was not just theoretical: the dev DB had 60+ duplicate
+-- `(storage_backend, NULL)` rows from buggy non-upsert call sites that
+-- predated the upsert hardening. Those rows accumulated invisibly because
+-- the index allowed them. Step 1 dedupes (keeps the most recent row per
+-- `(key, port_id)` group); step 2 rebuilds the unique index with
+-- `NULLS NOT DISTINCT` (Postgres 15+) so future inserts can't recreate the
+-- ambiguity.
+
+-- Step 1: dedupe duplicate rows, keeping the row with the latest updated_at.
+-- Uses a CTE + ROW_NUMBER() so the keeper is deterministic across reruns.
+WITH ranked AS (
+  SELECT ctid,
+         ROW_NUMBER() OVER (
+           PARTITION BY "key", "port_id"
+           ORDER BY "updated_at" DESC, ctid DESC
+         ) AS rn
+  FROM "system_settings"
+)
+DELETE FROM "system_settings"
+USING ranked
+WHERE "system_settings".ctid = ranked.ctid AND ranked.rn > 1;
+
+-- Step 2: replace the unique index with one that treats NULLs as equal,
+-- so global settings (port_id IS NULL) are unique by key alone.
+DROP INDEX IF EXISTS "system_settings_key_port_idx";
+CREATE UNIQUE INDEX "system_settings_key_port_idx"
+  ON "system_settings" ("key", "port_id")
+  NULLS NOT DISTINCT;

src/lib/db/schema/system.ts

@@ -135,9 +135,14 @@ export const systemSettings = pgTable(
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
   },
   (table) => [
+    // Migration 0047 rebuilds this index with `NULLS NOT DISTINCT` so a
+    // global setting (port_id IS NULL) is unique by key alone — the
+    // default `NULLS DISTINCT` semantics let duplicates accumulate.
+    // Drizzle's `uniqueIndex` builder doesn't surface NULLS NOT DISTINCT,
+    // so the migration is the source of truth for that flag and
+    // `db:push` against an empty DB would skip it (matches the
+    // documented limitation for `berths.current_pdf_version_id`).
     uniqueIndex('system_settings_key_port_idx').on(table.key, table.portId),
-    // Note: the PRIMARY KEY is `key` alone based on schema, but unique on (key, port_id)
-    // We use key as primary key per SQL schema
   ],
 );