feat(errors): platform-wide request ids + error codes + admin inspector

End-to-end error-handling overhaul. A user hitting any failure now sees
a plain-text message + stable error code + reference id. A super admin
can paste the id into /admin/errors/<id> for the full request shape,
sanitized body, error stack, and a heuristic likely-cause hint.

REQUEST CONTEXT (AsyncLocalStorage)
- src/lib/request-context.ts mints a per-request frame carrying
  requestId + portId + userId + method + path + start timestamp.
- withAuth wraps every authenticated handler in runWithRequestContext
  and accepts an upstream X-Request-Id header (validated shape) or
  generates a fresh UUID. The id ALWAYS leaves on the X-Request-Id
  response header, including early-return 401/403/4xx paths.
- Pino logger reads from the same context via mixin — every log
  line emitted during the request automatically carries the ids
  with no per-call threading.

ERROR CODE REGISTRY
- src/lib/error-codes.ts defines stable DOMAIN_REASON codes with
  HTTP status + plain-text user-facing message (no jargon, written
  for the rep on the phone with a customer).
- New CodedError class wraps a registered code + optional
  internalMessage (admin-only — never sent to client).
- Existing AppError subclasses got plain-text default rewrites so
  legacy throw sites improve immediately without migration.
- High-impact services migrated to specific codes:
  expenses (RECEIPT_REQUIRED, INVOICE_LINKED), interest-berths
  (CROSS_PORT_LINK_REJECTED), berth-pdf (PDF_MAGIC_BYTE / PDF_EMPTY /
  PDF_TOO_LARGE / VERSION_ALREADY_CURRENT), recommender
  (INTEREST_PORT_MISMATCH).

ERROR ENVELOPE
- errorResponse always sets X-Request-Id header + requestId field.
- 5xx responses include a "Quote error ID …" friendly line.
- 4xx kept clean (validation, permission, not-found don't pollute
  the inspector — they're already in audit log).

PERSISTENCE (error_events table, migration 0040)
- One row per 5xx, keyed on requestId, with method/path/status/error
  name+message/stack head (4KB cap)/sanitized body excerpt (1KB cap;
  password/token/secret/etc keys redacted)/duration/IP/UA/metadata.
- captureErrorEvent extracts Postgres SQLSTATE/severity/cause.code
  so the classifier can recognize FK / unique / NOT NULL / schema-
  drift violations.
- Failure to persist is logged-not-thrown.

LIKELY-CULPRIT CLASSIFIER (src/lib/error-classifier.ts)
- 4-pass heuristic (first match wins):
  1. Postgres SQLSTATE → human reason (23503 FK, 23505 unique,
     42703 schema drift, 53300 connection limit, …)
  2. Error class name (AbortError, TimeoutError, FetchError,
     ZodError)
  3. Stack-path patterns (/lib/storage/, /lib/email/, documenso,
     openai|claude, /queue/workers/)
  4. Free-text message keywords (econnrefused, rate limit, timeout,
     unauthorized|invalid api key)
- Returns { label, hint, subsystem } for the inspector badge.

CLIENT SIDE
- apiFetch throws structured ApiError with message + code + requestId
  + details + retryAfter.
- toastError() helper renders the standard 3-line toast:
  plain message / Error code: X / Reference ID: Y [Copy ID].

ADMIN INSPECTOR
- /<port>/admin/errors lists captured 5xx with status badge + path +
  likely-culprit badge + truncated message + reference id. Filter by
  status code; auto-refresh via TanStack Query.
- /<port>/admin/errors/<requestId> deep-dive: request shape, full
  error name+message+stack, sanitized body excerpt, raw metadata,
  registered-code lookup (so admin can compare to what user saw),
  likely-culprit hint with subsystem tag.
- /<port>/admin/errors/codes is the in-app code reference page —
  every registered code grouped by domain prefix, searchable, with
  HTTP status + user message inline. Linked from inspector header
  so admins can flip to it while triaging.
- Permission: admin.view_audit_log. Super admins see all ports;
  regular admins port-scoped.
- system-monitoring dashboard now surfaces error_events alongside
  permission_denied audit + queue failed jobs (RecentError gains
  source: 'request' variant).

DOCS
- docs/error-handling.md walks through coded errors, plain-text
  message guidelines, client toasting, admin inspector usage,
  persistence rules, classifier internals, pruning, and the
  legacy → CodedError migration path.

MIGRATION SAFETY
- Audit confirmed all 41 migrations (0000-0040) apply cleanly in
  journal order against an empty DB. 0040 references ports(id)
  which exists from 0000. 0035/0038 don't deadlock under sequential
  psql -f. Removed redundant idx_ds_sent_by from 0038 (created in
  0037).

Tests: 1168/1168 vitest passing. tsc clean.
- security-error-responses tests updated for plain-text messages
  + new optional response keys (code/requestId/message).
- berth-pdf-versions tests assert stable error codes via
  toMatchObject({ code }) rather than message regex.

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

src/app/(dashboard)/[portSlug]/admin/errors/page.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { useParams } from 'next/navigation';
+import { useQuery } from '@tanstack/react-query';
+import { format, formatDistanceToNow } from 'date-fns';
+import { AlertTriangle, BookOpen, Search, Wrench } from 'lucide-react';
+
+import type { Route } from 'next';
+
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Skeleton } from '@/components/ui/skeleton';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { apiFetch } from '@/lib/api/client';
+import { classifyError } from '@/lib/error-classifier';
+import type { ErrorEvent } from '@/lib/db/schema/system';
+
+interface ListResponse {
+  data: ErrorEvent[];
+}
+
+/**
+ * Super-admin error inspector.
+ *
+ * Shows the most recent captured 5xx errors with: when, where (HTTP
+ * method + path), what (error name + message), and a heuristic
+ * "likely culprit" badge driven by `classifyError`. Click into any
+ * row for the full stack + body excerpt + raw metadata.
+ */
+export default function AdminErrorsPage() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const [statusFilter, setStatusFilter] = useState('');
+
+  const query = useQuery<ListResponse>({
+    queryKey: ['admin', 'error-events', { statusFilter }],
+    queryFn: () => {
+      const search = new URLSearchParams();
+      if (statusFilter) search.set('statusCode', statusFilter);
+      return apiFetch<ListResponse>(
+        `/api/v1/admin/error-events${search.toString() ? `?${search.toString()}` : ''}`,
+      );
+    },
+  });
+
+  const events = query.data?.data ?? [];
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Error inspector"
+        description="Captured 5xx errors. Click any row for the full stack, request body excerpt, and likely culprit."
+        actions={
+          <Button variant="outline" size="sm" asChild>
+            <Link href={`/${portSlug}/admin/errors/codes` as Route}>
+              <BookOpen className="mr-1.5 h-4 w-4" />
+              Code reference
+            </Link>
+          </Button>
+        }
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium flex items-center gap-2">
+            <Search className="h-4 w-4" /> Filters
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="flex flex-wrap items-end gap-3">
+          <div className="space-y-1">
+            <label className="text-xs text-muted-foreground" htmlFor="status">
+              Status code
+            </label>
+            <Input
+              id="status"
+              placeholder="e.g. 500"
+              value={statusFilter}
+              onChange={(e) => setStatusFilter(e.target.value.replace(/\D/g, ''))}
+              className="h-8 w-32"
+            />
+          </div>
+          {statusFilter && (
+            <Button variant="ghost" size="sm" className="h-8" onClick={() => setStatusFilter('')}>
+              Clear
+            </Button>
+          )}
+        </CardContent>
+      </Card>
+
+      {query.isLoading ? (
+        <div className="space-y-2">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <Skeleton key={i} className="h-14 w-full" />
+          ))}
+        </div>
+      ) : events.length === 0 ? (
+        <EmptyState
+          icon={AlertTriangle}
+          title="No captured errors"
+          description="Nothing has hit a 5xx in the selected window. That's a good thing."
+        />
+      ) : (
+        <div className="rounded-lg border divide-y">
+          {events.map((event) => {
+            const culprit = classifyError(event);
+            return (
+              <Link
+                key={event.requestId}
+                href={`/${portSlug}/admin/errors/${event.requestId}` as Route}
+                className="flex items-start gap-3 p-3 hover:bg-muted/40"
+              >
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-2">
+                    <Badge
+                      variant="outline"
+                      className={
+                        event.statusCode >= 500
+                          ? 'border-destructive/40 text-destructive'
+                          : 'border-amber-300 text-amber-800'
+                      }
+                    >
+                      {event.statusCode}
+                    </Badge>
+                    <span className="text-xs font-mono uppercase text-muted-foreground">
+                      {event.method}
+                    </span>
+                    <span className="text-sm font-medium truncate">{event.path}</span>
+                    {culprit && (
+                      <Badge variant="secondary" className="gap-1 text-xs">
+                        <Wrench className="h-3 w-3" />
+                        {culprit.label}
+                      </Badge>
+                    )}
+                  </div>
+                  <p className="text-xs text-muted-foreground truncate mt-0.5">
+                    {event.errorName ? `${event.errorName}: ` : ''}
+                    {event.errorMessage ?? '(no message)'}
+                  </p>
+                  <p className="text-xs text-muted-foreground mt-0.5">
+                    {formatDistanceToNow(new Date(event.createdAt), { addSuffix: true })} ·{' '}
+                    {format(new Date(event.createdAt), 'MMM d HH:mm:ss')} · ID{' '}
+                    <code className="font-mono">{event.requestId.slice(0, 12)}…</code>
+                  </p>
+                </div>
+              </Link>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}