feat(modules): venue-module registry — entitled ∩ activated, requireModule, Setup panel

Groundwork for the Car Wash pilot (wiki/decisions/venue-modules.md, build-order
steps 1 + 3). No Car Wash code yet; validation is the first module behind the
seam, unchanged in behaviour.

- @parking/shared: MODULE_IDS, ModuleManifest, MODULES (parking required;
  validation dependsOn parking), parseEntitledModules / resolveModuleActivation
  / effectiveModules as pure functions.
- DB: site_config.modules_json (migration 0026, hand-written + journal;
  additive, nullable = everything entitled).
- Server: modules.ts (entitledModules from MODULES_ENTITLED env, activated
  from site_config, effective set, requireModule preHandler → 403
  module_disabled); modules/index.ts registers folder-based modules by
  iterating the registry (modules/validation); site-config GET exposes
  modules/modulesEntitled/modulesActivated, PUT takes the full desired set,
  enforces entitlement + dependency rules (400 with reason) and signs one
  config_change per module that actually flips; /api/auth/me carries the
  effective set; validation routes guarded requireModule → requirePermission.
- Web: lib/modules.ts + modules/{index,validation}; router.tsx spreads
  WEB_MODULES into nav + route tree (validate route no longer named there);
  Setup → Site "Modules" panel (required shown disabled, dependencies as
  hints, server refusal shown verbatim); validation sections + programs fetch
  gated on the module; App invalidates the router whenever the session
  changes (route-context consumers only re-read on navigation — the nav was
  stale after a flip, and after every other setUser too).
- Lavazh validation station retired (STATIONS = ["bar"]; rows untouched).
- Deploy: MODULES_ENTITLED=parking,validation explicit in both booth stacks;
  documented in .env.example.
- Tests: modules.test.ts (7); suite 329/329; web build clean; Playwright
  round-trip on /setup/site verified live.

Claude-Session: https://claude.ai/code/session_01FWncR69HgGPuei1dLrW3cU

apps/server/src/routes/auth.ts

@@ -1,6 +1,7 @@
 import bcrypt from "bcrypt";
 import type { FastifyInstance } from "fastify";
 import { eq, roles, users, type Db } from "@parking/db";
+import { effectiveModulesFor } from "../modules.js";
 import {
   clearAuthCookies,
   newCsrfToken,
@@ -107,6 +108,9 @@ function sessionView(
     fontScale: user.fontScale,
     fullName: user.fullName ?? null,
     email: user.email ?? null,
+    // Effective venue modules (entitled ∩ activated) so the SPA can hide nav/routes
+    // on first paint. The server still enforces via requireModule — this is display.
+    modules: effectiveModulesFor(db),
     ...(csrf ? { csrfToken: csrf } : {}),
   };
 }

apps/server/src/routes/site.ts

@@ -1,7 +1,9 @@
 import type { FastifyInstance } from "fastify";
 import { eq, siteConfig, type Db } from "@parking/db";
+import { MODULES, effectiveModules, isModuleId, resolveModuleActivation, type ModuleId } from "@parking/shared";
 import { requirePermission } from "../auth.js";
 import type { EventLog } from "../event-log.js";
+import { activatedModulesOf, entitledModules } from "../modules.js";
 import { getOccupancy } from "../occupancy.js";
 
 // Site config (capacity) + live occupancy. Occupancy is a fold over the signed
@@ -36,6 +38,10 @@ interface SiteConfigBody extends Partial<Record<TextField, string | null>> {
   /** Master switch for the ANPR subscriber-entry bridge (auto-open on a subscriber's
    *  plate read). OFF → subscribers fall back to card/QR; advisory ANPR still records. */
   anprEntryEnabled?: boolean;
+  /** Venue modules to ACTIVATE (full desired set). Validated against the entitlement
+   *  and the registry's dependency rules; required modules are always included. Each
+   *  module that actually flips signs a config_change. See wiki/decisions/venue-modules.md. */
+  modules?: unknown;
 }
 
 /** Shape returned by GET/PUT: capacity + the booth flag + the subscription default
@@ -48,6 +54,13 @@ type SiteConfig = {
   anprEntryEnabled: boolean;
   bypassPresenceRadar: boolean;
   bypassPresenceCamera: boolean;
+  /** Effective venue modules = entitled ∩ activated (what the server enforces). */
+  modules: ModuleId[];
+  /** What this deployment is entitled to (MODULES_ENTITLED env) — the Setup → Site
+   *  panel offers exactly these to toggle. */
+  modulesEntitled: ModuleId[];
+  /** What the site admin has activated (null in storage = everything entitled). */
+  modulesActivated: ModuleId[];
 } & Record<TextField, string | null>;
 
 function toSiteConfig(row: typeof siteConfig.$inferSelect | undefined): SiteConfig {
@@ -59,11 +72,22 @@ function toSiteConfig(row: typeof siteConfig.$inferSelect | undefined): SiteConf
     anprEntryEnabled: row?.anprEntryEnabled ?? true,
     bypassPresenceRadar: row?.bypassPresenceRadar ?? false,
     bypassPresenceCamera: row?.bypassPresenceCamera ?? false,
+    ...moduleView(row),
   } as SiteConfig;
   for (const f of TEXT_FIELDS) out[f] = row?.[f] ?? null;
   return out;
 }
 
+function moduleView(row: typeof siteConfig.$inferSelect | undefined) {
+  const entitled = entitledModules();
+  const activated = activatedModulesOf(row) ?? entitled;
+  return {
+    modules: effectiveModules(entitled, activated),
+    modulesEntitled: entitled,
+    modulesActivated: activated,
+  };
+}
+
 /** Trim a text field; empty string becomes null so blank input clears it. */
 function normText(v: unknown): string | null {
   if (v == null) return null;
@@ -136,6 +160,40 @@ export async function siteRoutes(app: FastifyInstance, db: Db, eventLog?: EventL
     }
 
     const existing = db.select().from(siteConfig).where(eq(siteConfig.id, 1)).get();
+
+    // Venue-module activation. The body carries the full DESIRED set; the shared rules
+    // (required always on, must be entitled, dependencies effective) decide, and every
+    // module whose effective state actually flips is signed as a config_change — the
+    // same attribution pattern as the presence-bypass endpoint below. Disabling never
+    // deletes anything: tables/history/grants stay, routes 403, UI hides.
+    if ("modules" in body) {
+      const requested = body.modules;
+      if (!Array.isArray(requested) || !requested.every(isModuleId)) {
+        return reply.code(400).send({
+          error: `modules must be an array of module ids (${MODULES.map((m) => m.id).join(", ")})`,
+        });
+      }
+      const entitled = entitledModules();
+      const result = resolveModuleActivation(entitled, requested);
+      if (!result.ok) return reply.code(400).send({ error: result.error });
+      const prevEffective = new Set(effectiveModules(entitled, activatedModulesOf(existing) ?? entitled));
+      const nextEffective = new Set(effectiveModules(entitled, result.modules));
+      const operator = req.user?.username ?? "unknown";
+      for (const m of MODULES) {
+        const was = prevEffective.has(m.id);
+        const now = nextEffective.has(m.id);
+        if (was !== now) {
+          await eventLog?.append({
+            type: "config_change",
+            source: "manual",
+            identity: `module:${m.id}`,
+            payload: { setting: `modules.${m.id}`, value: now, prev: was, operator },
+          });
+        }
+      }
+      patch.modulesJson = JSON.stringify(result.modules);
+    }
+
     const updatedAt = new Date().toISOString();
     if (existing) {
       db.update(siteConfig).set({ ...patch, updatedAt }).where(eq(siteConfig.id, 1)).run();

apps/server/src/routes/validations.ts

@@ -12,6 +12,7 @@ import {
 } from "@parking/db";
 import { VALIDATION_MODES, type ValidationMode } from "@parking/shared";
 import { requirePermission } from "../auth.js";
+import { requireModule } from "../modules.js";
 import type { EventLog } from "../event-log.js";
 import { liveValidations, sessionValidations } from "../validations.js";
 
@@ -75,9 +76,12 @@ function validateProgram(b: ProgramBody): string | null {
 }
 
 export async function validationRoutes(app: FastifyInstance, db: Db, eventLog: EventLog): Promise<void> {
-  const siteRead = requirePermission("site:read");
-  const siteWrite = requirePermission("site:update");
-  const applyGuard = requirePermission("validation:create");
+  // Every route is behind the venue-module gate FIRST (403 module_disabled when the
+  // site has validation off — see ../modules.ts), then the usual permission guard.
+  const moduleOn = requireModule(db, "validation");
+  const siteRead = [moduleOn, requirePermission("site:read")];
+  const siteWrite = [moduleOn, requirePermission("site:update")];
+  const applyGuard = [moduleOn, requirePermission("validation:create")];
 
   const liveProgram = (id: string) =>
     db