fix(P1): soft-archive berths instead of hard-delete — F5

Pre-audit, DELETE /api/v1/berths/[id] called `db.delete()` which
permanently dropped the row, cascade-vanished `interest_berths` links,
broke historical audit references, and could 404 the public feed mid-
customer-inquiry. The `berths.archived_at` column existed in the schema
but was never written.

Changes:
  - `archiveBerth(id, portId, { reason }, meta)` is the new canonical
    soft-archive. Requires a reason (min 5 chars). Blocks when an
    active interest still depends on the berth (forces the rep to
    resolve the deal first). Audit-logs the old status + reason.
  - `restoreBerth(...)` reverses it.
  - DELETE route now accepts `{ reason }` and routes to archiveBerth.
  - New POST /api/v1/berths/[id]/restore.
  - `getBerthOptions` + dashboard occupancy / status-distribution
    queries gain `isNull(berths.archivedAt)` so archived moorings
    don't show up in pickers or skew metrics.
  - Legacy `deleteBerth(...)` kept as a thin wrapper around archiveBerth
    so import sites we haven't migrated still work — labeled @deprecated.

Verified live:
  - DELETE w/o reason       → 400 (validation)
  - DELETE w/ "x"           → 400 "Reason must be ≥ 5 characters"
  - DELETE w/ proper reason → 204, row archived, reason persisted
  - DELETE twice            → 409 "Berth is already archived"
  - POST /restore           → 204, archived_at cleared

Follow-up (deferred): apply isNull(archivedAt) to recommendations.ts,
alert-rules.ts, portal.service.ts, report-generators.ts, berth-rules-
engine.ts. The current set covers the visible surfaces; the rest are
secondary aggregators.

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

src/app/api/v1/berths/[id]/restore/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { restoreBerth } from '@/lib/services/berths.service';
+import { errorResponse } from '@/lib/errors';
+
+// POST /api/v1/berths/[id]/restore
+// Post-audit F5: reverses an archive. No body. Audit-logged.
+export const POST = withAuth(
+  withPermission('berths', 'edit', async (_req, ctx, params) => {
+    try {
+      await restoreBerth(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/berths/[id]/route.ts

@@ -2,8 +2,8 @@ import { NextResponse } from 'next/server';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
-import { updateBerthSchema } from '@/lib/validators/berths';
-import { getBerthById, updateBerth, deleteBerth } from '@/lib/services/berths.service';
+import { updateBerthSchema, archiveBerthSchema } from '@/lib/validators/berths';
+import { getBerthById, updateBerth, archiveBerth } from '@/lib/services/berths.service';
 import { errorResponse } from '@/lib/errors';
 
 // GET /api/v1/berths/[id]
@@ -37,10 +37,14 @@ export const PATCH = withAuth(
 );
 
 // DELETE /api/v1/berths/[id]
+// Post-audit F5: this is a SOFT-ARCHIVE, not a hard delete. The body
+// must carry `{ reason: string (>=5 chars) }`. Use POST /restore to
+// reverse. Archive is blocked when an active interest is still linked.
 export const DELETE = withAuth(
-  withPermission('berths', 'edit', async (_req, ctx, params) => {
+  withPermission('berths', 'edit', async (req, ctx, params) => {
     try {
-      await deleteBerth(params.id!, ctx.portId, {
+      const body = await parseBody(req, archiveBerthSchema);
+      await archiveBerth(params.id!, ctx.portId, body, {
         userId: ctx.userId,
         portId: ctx.portId,
         ipAddress: ctx.ipAddress,