feat(tenancies-p1): module-enabled gate + admin toggle endpoints

Part of the locked Tenancies module design (docs/tenancies-design.md).
This PR is the gating infrastructure — the actual table rename
(berth_reservations -> tenancies) + self-FKs + perm-rename + sidebar
entry land in subsequent PRs.

What ships:
- `system_settings.tenancies_module_enabled` registry entry (port-scoped
  boolean, default false). Surfaces in the registry-driven admin form
  + the resolveForAdminAPI chain.
- `src/lib/services/tenancies-module.service.ts` with:
  * isTenanciesModuleEnabled(portId) — checks the admin setting AND
    the lazy "any berth_reservations row exists" sentinel
  * enableTenanciesModule / disableTenanciesModule — idempotent
    upserts on the system_settings row
  * assertTenanciesModuleEnabled — throw-on-disabled helper for
    route handlers (NotFoundError -> 404)
- Three admin endpoints under /api/v1/admin/tenancies-module/
  (status / enable / disable), all gated on admin.manage_settings.

Behaviour today: with the module off (default), nothing changes.
Sidebar, entity tabs, top-level page, webhook auto-create branch,
and dashboard widgets all continue to read the same flag and stay
hidden until either an admin toggles it ON or the first auto-create
flips it via the lazy "row exists" sentinel.

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

src/lib/services/tenancies-module.service.ts

@@ -0,0 +1,111 @@
+/**
+ * Tenancies module gate. The entire Tenancies surface (sidebar entry,
+ * entity tabs, top-level page, dashboard widgets, webhook auto-create
+ * branch) is hidden by default and only surfaces when EITHER:
+ *
+ *   (a) at least one `berth_reservations` row exists for the port
+ *       (lazy auto-enable on first creation), OR
+ *   (b) an admin has explicitly enabled the module via
+ *       `system_settings.tenancies_module_enabled` (default false).
+ *
+ * Per the locked decision (2026-05-25): a sold berth stays sold without
+ * any tenancy data — the platform does not assume tenancies exist for
+ * sold berths. The module only surfaces when one of the two conditions
+ * above is true.
+ *
+ * See `docs/tenancies-design.md` for the full rationale + UX flow.
+ */
+
+import { and, eq, isNull, or } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { systemSettings } from '@/lib/db/schema/system';
+import { berthReservations } from '@/lib/db/schema/reservations';
+import { NotFoundError } from '@/lib/errors';
+
+/**
+ * Resolve whether the Tenancies module is currently active for the
+ * given port. Honors both the explicit admin setting AND the lazy
+ * "any row exists" sentinel.
+ *
+ * Performance: two indexed reads; the row-exists check uses `LIMIT 1`
+ * so it stops at the first match. Cached at the service boundary via
+ * react-query in the UI; never called inside tight loops on the server.
+ */
+export async function isTenanciesModuleEnabled(portId: string): Promise<boolean> {
+  // 1. Admin setting check (port-scoped row first, fall back to global).
+  const settingRow = await db
+    .select({ value: systemSettings.value })
+    .from(systemSettings)
+    .where(
+      and(
+        eq(systemSettings.key, 'tenancies_module_enabled'),
+        or(eq(systemSettings.portId, portId), isNull(systemSettings.portId)),
+      ),
+    )
+    .limit(1);
+  if (settingRow[0]?.value === true) return true;
+
+  // 2. Lazy auto-enable: any row in the table flips the module on for
+  //    the rest of the app, even when the admin setting is still false.
+  //    Once any port has a tenancy, the module's UX is justified.
+  const rowCheck = await db
+    .select({ id: berthReservations.id })
+    .from(berthReservations)
+    .where(eq(berthReservations.portId, portId))
+    .limit(1);
+  return rowCheck.length > 0;
+}
+
+/**
+ * Idempotent helper for the webhook auto-create branch + admin-driven
+ * enables to call. Inserts/updates the system_settings row to true.
+ * Safe to call when already enabled (UPSERT on key+port).
+ */
+export async function enableTenanciesModule(portId: string): Promise<void> {
+  await db
+    .insert(systemSettings)
+    .values({
+      key: 'tenancies_module_enabled',
+      portId,
+      value: true,
+    })
+    .onConflictDoUpdate({
+      target: [systemSettings.key, systemSettings.portId],
+      set: { value: true, updatedAt: new Date() },
+    });
+}
+
+/**
+ * Admin-driven disable. Does NOT delete any tenancies rows — those
+ * remain in the database and surface again when the module is re-enabled.
+ * The frontend warns the operator about the row count before calling
+ * this, so by the time it lands here the intent is confirmed.
+ */
+export async function disableTenanciesModule(portId: string): Promise<void> {
+  await db
+    .insert(systemSettings)
+    .values({
+      key: 'tenancies_module_enabled',
+      portId,
+      value: false,
+    })
+    .onConflictDoUpdate({
+      target: [systemSettings.key, systemSettings.portId],
+      set: { value: false, updatedAt: new Date() },
+    });
+}
+
+/**
+ * Convenience throw-on-disabled helper for route handlers and services
+ * that should hard-fail (404 / NotFound) when the module is off. Most
+ * Tenancies-scoped routes wrap their handler body in this.
+ */
+export async function assertTenanciesModuleEnabled(portId: string): Promise<void> {
+  const enabled = await isTenanciesModuleEnabled(portId);
+  if (!enabled) {
+    // Route handlers map NotFoundError to 404; the sidebar + entity tabs
+    // independently gate so the rep never sees a link that would 404.
+    throw new NotFoundError('Tenancies module is not enabled for this port.');
+  }
+}