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/lib/validators/berths.ts

@@ -91,6 +91,17 @@ export const updateBerthStatusSchema = z.object({
 
 export type UpdateBerthStatusInput = z.infer<typeof updateBerthStatusSchema>;
 
+// ─── Archive Berth ────────────────────────────────────────────────────────────
+
+// Post-audit F5: archive replaces hard-delete. A `reason` is required so
+// the audit trail captures intent — "decommissioned 2026", "duplicate of
+// A3", etc. min(5) blocks one-letter throwaways.
+export const archiveBerthSchema = z.object({
+  reason: z.string().trim().min(5, 'Reason must be at least 5 characters'),
+});
+
+export type ArchiveBerthInput = z.infer<typeof archiveBerthSchema>;
+
 // ─── List Berths ──────────────────────────────────────────────────────────────
 
 export const listBerthsSchema = baseListQuerySchema.extend({