create-ailk 0.2.0 → 0.4.0

package/templates/apps/api/src/server.ts

@@ -9,53 +9,50 @@
  * - Vercel serverless deployment (api/index.ts)
  * - Local development (src/index.ts)
  */
-import cors from '@fastify/cors';
-import rateLimit from '@fastify/rate-limit';
-import Fastify from 'fastify';
-import type { FastifyPluginAsync, FastifyPluginCallback } from 'fastify';
-
-import { config } from './config/index.js';
-import { isModuleEnabled } from './config/modules.js';
-import { registerErrorSerializer } from './lib/error-serializer.js';
-import { validateLeadCaptureDir } from './lib/lead-capture-store.js';
-import { assertSandboxKey } from './lib/stripe.js';
-import { authPreHandlerPlugin } from './middleware/auth.js';
+import cors from "@fastify/cors";
+import rateLimit from "@fastify/rate-limit";
+import Fastify from "fastify";
+import type { FastifyPluginAsync, FastifyPluginCallback } from "fastify";
+
+import { config } from "./config/index.js";
+import { isModuleEnabled } from "./config/modules.js";
+import { registerErrorSerializer } from "./lib/error-serializer.js";
+import { validateLeadCaptureDir } from "./lib/lead-capture-store.js";
+import { loadSlice } from "./lib/slice-load.js";
+import { authPreHandlerPlugin } from "./middleware/auth.js";
 import {
   rateLimitMiddleware,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
-} from './middleware/rate-limit.js';
-import { openapiRoutes } from './openapi/index.js';
-import { exampleAeoRoute, scoreAeoRoute } from './routes/aeo/index.js';
-import { tokenRoutes } from './routes/auth/tokens.js';
-import { userRoutes } from './routes/auth/user.js';
-import { checkoutRoutes } from './routes/checkout/index.js';
-import { getPageRoute } from './routes/content/get-page.js';
-import { listPagesRoute } from './routes/content/list-pages.js';
-import { listTypesRoute } from './routes/content/list-types.js';
+} from "./middleware/rate-limit.js";
+import { openapiRoutes } from "./openapi/index.js";
+import {
+  deriveRootEndpoints,
+  REGISTERED_ROUTES_DECORATOR,
+  API_VERSION,
+  apiDescription,
+  apiDisplayName,
+  resolveApiIdentity,
+} from "./openapi/spec.js";
+import type { RegisteredRoute } from "./openapi/surface-drift.js";
+import { exampleAeoRoute, scoreAeoRoute } from "./routes/aeo/index.js";
+import { tokenRoutes } from "./routes/auth/tokens.js";
+import { userRoutes } from "./routes/auth/user.js";
+import { getPageRoute } from "./routes/content/get-page.js";
+import { listPagesRoute } from "./routes/content/list-pages.js";
+import { listTypesRoute } from "./routes/content/list-types.js";
 import {
   CONTENT_RATE_LIMIT_UNAUTH,
   CONTENT_RATE_LIMIT_WINDOW,
-} from './routes/content/rate-limit.js';
-import { deliverableDownloadRoute } from './routes/deliverables/index.js';
-import { flowCheckoutRoutes } from './routes/flow-checkouts/index.js';
-import { getFlowAggregateRoute, getFlowRoute, submitFlowStepRoute } from './routes/flows/index.js';
-import { checkoutRecommendationRoute, saveRecommendationRoute } from './routes/flows/recommender.js';
+} from "./routes/content/rate-limit.js";
 import {
   leadCallbackRoute,
   leadSubmitRoute,
   leadSubscribeRoute,
-} from './routes/leads/index.js';
+} from "./routes/leads/index.js";
 import {
-  projectListingDraftPatchRoute,
-  projectListingMeRoute,
-  projectListingPublicRoute,
-  projectListingStartRoute,
-  projectListingSubmitRoute,
-} from './routes/project-listings/index.js';
-import { slackActionsRoute } from './routes/slack/index.js';
-import { registerTestAuthRoute, shouldMountTestAuth } from './routes/test/auth/session.js';
-import { waitlistSignupRoutes } from './routes/waitlist-signups/index.js';
-import { webhooksRoutes } from './routes/webhooks/index.js';
+  registerTestAuthRoute,
+  shouldMountTestAuth,
+} from "./routes/test/auth/session.js";
 
 /**
  * Paid-module SLICE entry points, keyed by the export each branch needs
@@ -70,9 +67,15 @@ import { webhooksRoutes } from './routes/webhooks/index.js';
  * `./middleware/tenant.js` import was an eleventh — measured on a stripped
  * tree, not argued.
  *
- * Reading the specifier from this table is what makes it non-literal at the
- * call site, and that INDIRECTION — not the type of the value — is what defeats
- * resolution. S1's `isModuleEnabled()` gate is unchanged and still decides
+ * Keeping the specifier off the `import()` call site is what defeats that
+ * resolution, and the INDIRECTION — not the type of the value — is what does
+ * the work. WHICH FORM of indirection is not free, and #5304 is the correction:
+ * reading the specifier out of a TABLE, as this file did until then, hid it
+ * from the deploy-time file tracer as well as from `tsc`, so the files were
+ * compiled and never shipped. The form below — a module-level constant
+ * dereferenced into `import()` — is unresolvable to `tsc` and traceable to
+ * `@vercel/nft`, the only pair of properties that satisfies both the strip and
+ * the deployment. S1's `isModuleEnabled()` gate is unchanged and still decides
  * whether the branch runs; `AILK_ENABLED_MODULES` unset still means every
  * module on, so a default build registers exactly what it registered before.
  *
@@ -82,27 +85,210 @@ import { webhooksRoutes } from './routes/webhooks/index.js';
  * with no members, so the module silently fails to load on the tree that HAS
  * it. See the note above the imports in `packages/ui/src/sections/SectionRenderer.tsx`.
  *
- * `./routes/project-listings/index.js` is deliberately absent: that barrel is a
- * MIXED directory that ships (the free anonymous listing routes are registered
- * from it statically at the top of this file), so its dynamic import at the
- * tenant scope is a literal on purpose and resolves fine on both trees.
+ * BUNDLING `apps/api` IS NOT A SUPPORTED DEPLOY PATH, and that is a property of
+ * the analysers rather than a posture (#5334). esbuild bundles a dynamic
+ * `import()` only when its argument is a string literal at the call site —
+ * exactly the predicate `tsc` resolves on, and exactly the one the strip
+ * forbids. So no expression shape can satisfy both, and in a bundled build
+ * these specifiers survive verbatim and resolve against the BUNDLE OUTPUT
+ * directory instead of their source module's: `"./list.js"` in
+ * `routes/project-listings/index.ts` becomes `dist/list.js` and is not there.
+ * esbuild does not warn. `build()` then throws during CONSTRUCTION, so every
+ * route 500s rather than one — measured in production, nine hours of total API
+ * outage on a consuming site. The supported path is what the scaffold ships:
+ * plain `tsc` output traced by `@vercel/node` (`apps/api/vercel.json`,
+ * `framework: null`). If you are syncing this file into a repo that bundles,
+ * that is the constraint you have just inherited; `apps/api/CLAUDE.md`
+ * § Deploy path says what to do instead. Every load site below routes through
+ * `loadSlice()` so a bundled build says so at boot rather than failing mute.
+ *
+ * `./routes/project-listings/index.js` carries two independent load paths on
+ * purpose: its five anonymous-surface exports are reached below through
+ * `PROJECT_LISTINGS_INDEX` / `SLICE_PLUGINS`, now that signal-collectors gates
+ * their registration (D4), while the tenant scope's own `import()` of the same
+ * specifier stays a literal — the file is a MIXED directory that always ships
+ * (multi-tenant's `TENANT_HANDLERS` table lives in the same file), so a literal
+ * there resolves fine on every tree regardless of module selection.
+ */
+/**
+ * One module-level constant per slice module. The call sites below read the
+ * loader out of `SLICE_PLUGINS`; the specifier itself is never written at an
+ * `import()` call site, which is what keeps `tsc` from resolving it (#5182 D1).
+ *
+ * The constant is not a style choice — it is the mechanism (#5304 D3).
+ * `@vercel/nft` constant-propagates a module-level binding into `import()` and
+ * emits the file; it cannot evaluate a table lookup or a for-of destructure,
+ * which is what the previous `Record<string, string>` shape forced it to do.
+ * So the old shape was invisible to the DEPLOY tracer as well as to `tsc`, the
+ * files went untraced and unshipped, and `build()` threw ERR_MODULE_NOT_FOUND
+ * on the first slice it reached — measured in production, nine hours of total
+ * API outage on a consuming site. Both analysers are re-measured on every run
+ * by `scripts/__tests__/enumerate-slice-specifiers.test.ts`, and
+ * `scripts/check-slice-reachability.ts` fails when any specifier here stops
+ * being traced.
+ */
+const WORKSPACES_INDEX = "./routes/workspaces/index.js";
+const WORKSPACES_SESSIONS = "./routes/workspaces/sessions.js";
+const WORKSPACES_CONFIG = "./routes/workspaces/config.js";
+const WORKSPACES_GENERAL = "./routes/workspaces/general.js";
+const WORKSPACES_MEMBERS = "./routes/workspaces/members.js";
+const BILLING_INDEX = "./routes/billing/index.js";
+const WAITLIST_EXPERIMENTS_INDEX = "./routes/waitlist-experiments/index.js";
+const CONTENT_CREATE = "./routes/content/create.js";
+const CONTENT_UPDATE = "./routes/content/update.js";
+const CONTENT_DELETE = "./routes/content/delete.js";
+const SCHEDULE_INDEX = "./routes/schedule/index.js";
+const FLOWS_INDEX = "./routes/flows/index.js";
+const DELIVERABLES_INDEX = "./routes/deliverables/index.js";
+const PROJECT_LISTINGS_INDEX = "./routes/project-listings/index.js";
+const SLACK_INDEX = "./routes/slack/index.js";
+const WAITLIST_SIGNUPS_INDEX = "./routes/waitlist-signups/index.js";
+const CHECKOUT_INDEX = "./routes/checkout/index.js";
+const WEBHOOKS_INDEX = "./routes/webhooks/index.js";
+const FLOW_CHECKOUTS_INDEX = "./routes/flow-checkouts/index.js";
+const RECOMMENDER_INDEX = "./routes/flows/recommender.js";
+
+/**
+ * Paid-module SLICE entry points, keyed by the export each branch needs.
+ *
+ * `specifier` is carried alongside `load` for the drift message below, and both
+ * read the SAME constant, so the two can never disagree. `load` is what runs:
+ * an arrow closing over that constant, which is the only shape both analysers
+ * treat as intended — unresolvable to `tsc`, traceable to `nft`.
  */
-const SLICE_PLUGIN_SPECIFIERS = {
-  workspaceContextRoutes: './routes/workspaces/index.js',
-  workspaceSessionRoutes: './routes/workspaces/index.js',
-  sessionRoutes: './routes/workspaces/sessions.js',
-  workspaceConfigRoutes: './routes/workspaces/config.js',
-  billingRoutes: './routes/billing/index.js',
-  waitlistExperimentRoutes: './routes/waitlist-experiments/index.js',
-  createPageRoute: './routes/content/create.js',
-  updatePageRoute: './routes/content/update.js',
-  deletePageRoute: './routes/content/delete.js',
-  listAvailabilityRoute: './routes/schedule/index.js',
-  getEventMetaRoute: './routes/schedule/index.js',
-  createBookingRoute: './routes/schedule/index.js',
-} satisfies Record<string, string>;
-
-type SlicePluginName = keyof typeof SLICE_PLUGIN_SPECIFIERS;
+const SLICE_PLUGINS = {
+  workspaceContextRoutes: {
+    specifier: WORKSPACES_INDEX,
+    load: () => import(WORKSPACES_INDEX),
+  },
+  workspaceSessionRoutes: {
+    specifier: WORKSPACES_INDEX,
+    load: () => import(WORKSPACES_INDEX),
+  },
+  sessionRoutes: {
+    specifier: WORKSPACES_SESSIONS,
+    load: () => import(WORKSPACES_SESSIONS),
+  },
+  workspaceConfigRoutes: {
+    specifier: WORKSPACES_CONFIG,
+    load: () => import(WORKSPACES_CONFIG),
+  },
+  workspaceGeneralRoutes: {
+    specifier: WORKSPACES_GENERAL,
+    load: () => import(WORKSPACES_GENERAL),
+  },
+  workspaceMembersRoutes: {
+    specifier: WORKSPACES_MEMBERS,
+    load: () => import(WORKSPACES_MEMBERS),
+  },
+  billingRoutes: {
+    specifier: BILLING_INDEX,
+    load: () => import(BILLING_INDEX),
+  },
+  waitlistExperimentRoutes: {
+    specifier: WAITLIST_EXPERIMENTS_INDEX,
+    load: () => import(WAITLIST_EXPERIMENTS_INDEX),
+  },
+  createPageRoute: {
+    specifier: CONTENT_CREATE,
+    load: () => import(CONTENT_CREATE),
+  },
+  updatePageRoute: {
+    specifier: CONTENT_UPDATE,
+    load: () => import(CONTENT_UPDATE),
+  },
+  deletePageRoute: {
+    specifier: CONTENT_DELETE,
+    load: () => import(CONTENT_DELETE),
+  },
+  listAvailabilityRoute: {
+    specifier: SCHEDULE_INDEX,
+    load: () => import(SCHEDULE_INDEX),
+  },
+  getEventMetaRoute: {
+    specifier: SCHEDULE_INDEX,
+    load: () => import(SCHEDULE_INDEX),
+  },
+  createBookingRoute: {
+    specifier: SCHEDULE_INDEX,
+    load: () => import(SCHEDULE_INDEX),
+  },
+  getFlowRoute: {
+    specifier: FLOWS_INDEX,
+    load: () => import(FLOWS_INDEX),
+  },
+  submitFlowStepRoute: {
+    specifier: FLOWS_INDEX,
+    load: () => import(FLOWS_INDEX),
+  },
+  getFlowAggregateRoute: {
+    specifier: FLOWS_INDEX,
+    load: () => import(FLOWS_INDEX),
+  },
+  deliverableDownloadRoute: {
+    specifier: DELIVERABLES_INDEX,
+    load: () => import(DELIVERABLES_INDEX),
+  },
+  projectListingStartRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  projectListingDraftPatchRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  projectListingSubmitRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  // #5407 — the resume link's verification write. Anonymous surface,
+  // module-conditional (signal-collectors, D-48) like its four siblings.
+  projectListingVerifyEmailRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  projectListingPublicRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  projectListingMeRoute: {
+    specifier: PROJECT_LISTINGS_INDEX,
+    load: () => import(PROJECT_LISTINGS_INDEX),
+  },
+  slackActionsRoute: {
+    specifier: SLACK_INDEX,
+    load: () => import(SLACK_INDEX),
+  },
+  waitlistSignupRoutes: {
+    specifier: WAITLIST_SIGNUPS_INDEX,
+    load: () => import(WAITLIST_SIGNUPS_INDEX),
+  },
+  // Commerce (D-47, #5364) — checkout, the Stripe webhook receiver, flow
+  // checkouts and the recommender. Module-conditional (isModuleEnabled
+  // "commerce") like every other paid slice above.
+  checkoutRoutes: {
+    specifier: CHECKOUT_INDEX,
+    load: () => import(CHECKOUT_INDEX),
+  },
+  webhooksRoutes: {
+    specifier: WEBHOOKS_INDEX,
+    load: () => import(WEBHOOKS_INDEX),
+  },
+  flowCheckoutRoutes: {
+    specifier: FLOW_CHECKOUTS_INDEX,
+    load: () => import(FLOW_CHECKOUTS_INDEX),
+  },
+  saveRecommendationRoute: {
+    specifier: RECOMMENDER_INDEX,
+    load: () => import(RECOMMENDER_INDEX),
+  },
+  checkoutRecommendationRoute: {
+    specifier: RECOMMENDER_INDEX,
+    load: () => import(RECOMMENDER_INDEX),
+  },
+} satisfies Record<string, { specifier: string; load: () => Promise<unknown> }>;
+
+type SlicePluginName = keyof typeof SLICE_PLUGINS;
 
 /**
  * Load one slice route plugin. Every entry above is a `FastifyPluginAsync`
@@ -117,8 +303,8 @@ type SlicePluginName = keyof typeof SLICE_PLUGIN_SPECIFIERS;
 async function sliceRoutePlugin(
   name: SlicePluginName,
 ): Promise<FastifyPluginAsync> {
-  const specifier: string = SLICE_PLUGIN_SPECIFIERS[name];
-  const mod = (await import(specifier)) as Record<
+  const { specifier, load } = SLICE_PLUGINS[name];
+  const mod = (await loadSlice(specifier, load)) as Record<
     string,
     FastifyPluginAsync | undefined
   >;
@@ -135,17 +321,40 @@ async function sliceRoutePlugin(
  * (apps/api/src/middleware/tenant.ts:83).
  */
 async function tenantPreHandlerSlicePlugin(): Promise<FastifyPluginCallback> {
-  const specifier: string = './middleware/tenant.js';
-  const mod = (await import(specifier)) as {
+  const specifier: string = "./middleware/tenant.js";
+  const mod = (await loadSlice(specifier, () => import(specifier))) as {
     tenantPreHandlerPlugin?: FastifyPluginCallback;
   };
   const plugin = mod.tenantPreHandlerPlugin;
   if (!plugin) {
-    throw new Error('slice export tenantPreHandlerPlugin missing from ' + specifier);
+    throw new Error(
+      "slice export tenantPreHandlerPlugin missing from " + specifier,
+    );
   }
   return plugin;
 }
 
+/**
+ * The commerce boot-time sandbox guard — the one other slice entry that is
+ * not a route plugin, mirroring `tenantPreHandlerSlicePlugin()` above (D3).
+ * `lib/stripe.ts` is commerce-owned (D5) and its `assertSandboxKey` is the
+ * sole `apps/api` reach into the Stripe SDK wrapper package, so it can no
+ * longer be a static import (spec D1) once the module is stripped. The
+ * widened `const specifier: string` annotation is what defeats `tsc`
+ * resolution, exactly as it does above.
+ */
+async function assertCommerceSandboxKey(key: string): Promise<void> {
+  const specifier: string = "./lib/stripe.js";
+  const mod = (await loadSlice(specifier, () => import(specifier))) as {
+    assertSandboxKey?: (key: string) => void;
+  };
+  const assertSandboxKeyFn = mod.assertSandboxKey;
+  if (!assertSandboxKeyFn) {
+    throw new Error("slice export assertSandboxKey missing from " + specifier);
+  }
+  assertSandboxKeyFn(key);
+}
+
 /**
  * Build Fastify server instance (for serverless or standalone)
  * @returns Configured Fastify instance ready for requests
@@ -156,9 +365,11 @@ export async function build() {
 
   // Runtime sandbox-mode guard: reject live-mode Stripe keys before any
   // webhook or checkout call can exercise them. Idempotent — safe even if
-  // assertSandboxKey is called again inside a route handler.
-  if (config.STRIPE_SECRET_KEY) {
-    assertSandboxKey(config.STRIPE_SECRET_KEY);
+  // assertSandboxKey is called again inside a route handler. Module-
+  // conditional (commerce, D-47/D3): a build without commerce has no
+  // commerce request path to guard, and lib/stripe.ts is stripped with it.
+  if (isModuleEnabled("commerce") && config.STRIPE_SECRET_KEY) {
+    await assertCommerceSandboxKey(config.STRIPE_SECRET_KEY);
   }
 
   // trustProxy: true (#4730) — the Vercel serverless handler
@@ -188,6 +399,32 @@ export async function build() {
     trustProxy: true,
   });
 
+  // Collect the route table this server registers (#5314).
+  //
+  // Installed here — after `Fastify()` and before the first `register()` — so
+  // no route can precede it: a root-instance `onRoute` hook fires for every
+  // route added afterwards in ANY encapsulated child scope, which is what lets
+  // one hook see the auth, tenant, webhooks, leads, flows, aeo and schedule
+  // scopes without touching any of them.
+  //
+  // HEAD is dropped: Fastify synthesises it from every GET, so publishing it
+  // would describe routes no handler declared.
+  //
+  // The table lives on THIS instance, not in module state, so two servers
+  // built concurrently in one process cannot corrupt each other's — see the
+  // note on `readRegisteredRoutes` in openapi/spec.ts for the concrete race.
+  // The decorator holds the array by reference and the hook pushes into it, so
+  // every reader sees the current contents without re-publishing.
+  const registeredRoutes: RegisteredRoute[] = [];
+  server.decorate(REGISTERED_ROUTES_DECORATOR, registeredRoutes);
+  server.addHook("onRoute", (route) => {
+    const methods = Array.isArray(route.method) ? route.method : [route.method];
+    for (const method of methods) {
+      if (method === "HEAD") continue;
+      registeredRoutes.push({ method, url: route.url });
+    }
+  });
+
   // Register error serializer — maps internal exceptions to generic strings
   // so connection strings, hostnames, stack traces, and SDK error details
   // never reach the client. Full detail still goes to pino at error level.
@@ -199,9 +436,32 @@ export async function build() {
   // `credentials: true` would let any website read credentialed responses
   // (security review M1). `false` disables cross-origin access entirely;
   // same-origin and non-browser callers are unaffected.
+  //
+  // `methods` is EXPLICIT because @fastify/cors defaults it to `GET,HEAD,POST`
+  // (its own `defaultOptions`), which is narrower than the surface this server
+  // registers (#5397). With only `origin` + `credentials` passed, the preflight
+  // for `PATCH /v1/project-listings/drafts/:id` answered
+  // `access-control-allow-methods: GET, HEAD, POST`, so a browser refused every
+  // draft save on a split-origin deploy — a site could create a listing draft
+  // and never save one. The list below is the union of the methods the route
+  // table actually serves (GET/POST/PATCH/PUT/DELETE — `/v1/auth/tokens/:id`,
+  // `/v1/content/:type/:slug`, `/v1/user/data/:key`, the workspace-config PUTs),
+  // plus HEAD (Fastify synthesises it from every GET) and OPTIONS (the plugin's
+  // own wildcard preflight route). `cors.test.ts` re-derives that union from the
+  // live route table on every run, so a route added in a NEW method fails there
+  // rather than silently becoming unreachable from a browser.
+  //
+  // This widens WHICH METHODS the allowed origin may use, never WHO is allowed:
+  // `origin` and `credentials` are untouched.
+  //
+  // `allowedHeaders` is deliberately left unset: null means @fastify/cors
+  // reflects the request's `Access-Control-Request-Headers`, so `authorization`
+  // and `content-type` pass without this file having to maintain a list that
+  // silently drops a header a future route needs.
   await server.register(cors, {
-    origin: config.FRONTEND_URL || config.NODE_ENV !== 'production',
+    origin: config.FRONTEND_URL || config.NODE_ENV !== "production",
     credentials: true,
+    methods: ["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"],
   });
 
   // Register rate limiting — applied globally with the unauth ceiling. The
@@ -214,32 +474,35 @@ export async function build() {
   });
 
   // Health check
-  server.get('/health', async () => ({
-    status: 'healthy',
+  server.get("/health", async () => ({
+    status: "healthy",
     timestamp: new Date().toISOString(),
   }));
 
-  // Root endpoint
-  server.get('/', async () => {
+  // Root endpoint — introduces this deployment as the SITE it serves, not as
+  // the kit it was built with (#5307). `_site.mdx` is read once per process;
+  // a site without one degrades to a neutral name, never to the kit's.
+  server.get("/", async () => {
+    const identity = resolveApiIdentity();
     return {
-      name: 'AI Launch Kit API',
-      version: '1.0.0',
-      description: 'Local auth + session backend + public content API',
-      endpoints: {
-        health: 'GET /health',
-        openapi: 'GET /v1/openapi.json',
-        // Auth (local)
-        tokens: 'POST/GET/DELETE /v1/auth/tokens',
-        profile: 'GET/PATCH /v1/user/profile',
-        userData: 'GET/PUT/DELETE /v1/user/data/:key',
-        // Public content (read-only)
-        contentTypes: 'GET /v1/content/types',
-        contentList: 'GET /v1/content/:type',
-        contentPage: 'GET /v1/content/:type/:slug',
-        checkoutSessions: 'POST /v1/checkout/sessions',
-        billing: 'GET /v1/billing',
-        billingPortalSession: 'POST /v1/billing/portal-session',
-      },
+      name: apiDisplayName(identity),
+      version: API_VERSION,
+      description: apiDescription(identity),
+      // Derived from the routes this process actually registered (#5314),
+      // not a hand-maintained literal. The literal listed 11 endpoints against
+      // 68 registered routes, omitted `/v1/project-listings/public` and
+      // `/v1/billing/usage`, advertised `DELETE /v1/auth/tokens` at a path
+      // that 404s (the route is `/v1/auth/tokens/:id`), and named two billing
+      // routes on builds where the multi-tenant module registers neither.
+      // Same mechanism now covers commerce (D-47, #5364): checkout, the
+      // Stripe webhook, the flow-checkouts read and the two recommender
+      // routes are derived exactly like the billing routes above and
+      // disappear from this list on a build where `commerce` is off, rather
+      // than advertising a route that 404s.
+      //
+      // Read at REQUEST time, so `ready()` has fired and the set is complete
+      // even though this handler is registered before most routes.
+      endpoints: deriveRootEndpoints(registeredRoutes),
     };
   });
 
@@ -258,20 +521,30 @@ export async function build() {
     // apply to them; each enforces membership in the service layer.
     // Module-conditional (S1, #5088): without the multi-tenant module there
     // is no workspace concept to switch or inspect.
-    if (isModuleEnabled('multi-tenant')) {
-      await authScope.register(await sliceRoutePlugin('workspaceContextRoutes'));
+    if (isModuleEnabled("multi-tenant")) {
+      await authScope.register(
+        await sliceRoutePlugin("workspaceContextRoutes"),
+      );
     }
 
     // Respondent signup read (#4731) — auth only, NOT tenant-guarded: a
     // respondent has no workspace membership and the tenant guard is
     // default-deny. Identity is request.userId; the service re-checks
-    // User.emailVerified before any Lead read.
-    await authScope.register(waitlistSignupRoutes);
+    // User.emailVerified before any Lead read. Module-conditional
+    // (signal-collectors, D-48): the waitlist instrument's respondent half.
+    if (isModuleEnabled("signal-collectors")) {
+      await authScope.register(await sliceRoutePlugin("waitlistSignupRoutes"));
+    }
 
     // Respondent checkouts read (#4984) — the same posture as the signup
     // read above: auth only, NOT tenant-guarded. Identity is request.userId;
     // the only join is the lead-promotion link (never an email match).
-    await authScope.register(flowCheckoutRoutes);
+    // Module-conditional (commerce, D-47): the `/account` Purchases panel
+    // already degrades to its empty state with no code change when this is
+    // absent (`SKIPPED_STATUSES` covers 404 — spec §4.2).
+    if (isModuleEnabled("commerce")) {
+      await authScope.register(await sliceRoutePlugin("flowCheckoutRoutes"));
+    }
 
     // The founder's OWN listings read (#5295) — the same posture again: auth
     // only, NOT tenant-guarded, because a founder is not a workspace member
@@ -284,7 +557,12 @@ export async function build() {
     // build without the module; the static `/me` path takes router precedence
     // over the tenant scope's parametric `/v1/project-listings/:id`, exactly as
     // the already-shipped static `/v1/project-listings/public` does.
-    await authScope.register(projectListingMeRoute);
+    // Module-conditional (signal-collectors, D-48 / D4): the listing
+    // instrument's founder-read half; not severable from the four anonymous
+    // listing routes below (same static barrel, D4).
+    if (isModuleEnabled("signal-collectors")) {
+      await authScope.register(await sliceRoutePlugin("projectListingMeRoute"));
+    }
 
     // Tenant-guarded domain routes (multi-tenant module) — the tenant
     // preHandler (default-deny guard, see middleware/tenant.ts) runs after
@@ -293,27 +571,63 @@ export async function build() {
     // no tenant concept at all — the whole scope is module-conditional
     // (S1, #5088), so an OSS build that excludes multi-tenant registers
     // none of it.
-    if (isModuleEnabled('multi-tenant')) {
+    if (isModuleEnabled("multi-tenant")) {
       await authScope.register(async (tenantScope) => {
         await tenantScope.register(await tenantPreHandlerSlicePlugin());
-        await tenantScope.register(await sliceRoutePlugin('workspaceSessionRoutes'));
-        await tenantScope.register(await sliceRoutePlugin('sessionRoutes'));
-        await tenantScope.register(await sliceRoutePlugin('workspaceConfigRoutes'));
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceSessionRoutes"),
+        );
+        await tenantScope.register(await sliceRoutePlugin("sessionRoutes"));
         // Org-billing routes (#3701) — org-scoped read + Stripe customer-portal.
-        await tenantScope.register(await sliceRoutePlugin('billingRoutes'));
+        await tenantScope.register(await sliceRoutePlugin("billingRoutes"));
         // Waitlist operator-dashboard read API (#4665 D7, B0) — tenant-scoped
         // list/comparison/signups reads over A1's waitlist-experiment rows.
         await tenantScope.register(
-          await sliceRoutePlugin('waitlistExperimentRoutes'),
+          await sliceRoutePlugin("waitlistExperimentRoutes"),
         );
         // Project-listings dashboard (#4998) — tenant-scoped list/get/patch
         // over the founder's-application-row lifecycle.
-        const { projectListingTenantRoutes } = await import(
-          './routes/project-listings/index.js'
-        );
+        const { projectListingTenantRoutes } =
+          await import("./routes/project-listings/index.js");
         await tenantScope.register(projectListingTenantRoutes);
       });
     }
+
+    // Workspace SETTINGS routes — a sibling tenant scope, gated on EITHER
+    // module (#5371 D2). The site-config routes were registered inside the
+    // multi-tenant scope above, which was too narrow: nothing in their logic
+    // is multi-tenant-specific, and since Phase 2 `resolveActiveTenant`
+    // resolves a single-tenant session's TenantContext from the default
+    // Organization/Workspace exactly like a multi-tenant one. Widening the
+    // gate is the correction; duplicating the route file would encode the
+    // original mis-scoping twice.
+    //
+    // This is a REGISTRATION change, not a tenant-isolation change: the scope
+    // registers its own `tenantPreHandlerSlicePlugin()`, the same default-deny
+    // guard the scope above uses, with the same `resolveActiveTenant` behind
+    // it. Every other route in that scope (workspaceSessionRoutes,
+    // sessionRoutes, billingRoutes, waitlistExperimentRoutes, the
+    // project-listings tenant routes) stays multi-tenant-only.
+    //
+    // A build with BOTH modules enabled registers each of the three route
+    // plugins exactly once: they live here and nowhere else, so the two
+    // scopes cannot collide on a path.
+    if (isModuleEnabled("workspace") || isModuleEnabled("multi-tenant")) {
+      await authScope.register(async (tenantScope) => {
+        await tenantScope.register(await tenantPreHandlerSlicePlugin());
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceConfigRoutes"),
+        );
+        // The Pro workspace module's own two routes (#5371): the workspace
+        // name, and the read-only member roster.
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceGeneralRoutes"),
+        );
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceMembersRoutes"),
+        );
+      });
+    }
   });
 
   // Public routes — no auth required.
@@ -325,22 +639,28 @@ export async function build() {
   // module-conditional at REGISTRATION too (S1, #5088) so an OSS build that
   // excludes the content-write slice never wires the handler in at all. Not
   // a MODULE_SLICES entry — see config/modules.ts.
-  if (isModuleEnabled('content-write')) {
-    await server.register(await sliceRoutePlugin('createPageRoute'));
-    await server.register(await sliceRoutePlugin('updatePageRoute'));
-    await server.register(await sliceRoutePlugin('deletePageRoute'));
+  if (isModuleEnabled("content-write")) {
+    await server.register(await sliceRoutePlugin("createPageRoute"));
+    await server.register(await sliceRoutePlugin("updatePageRoute"));
+    await server.register(await sliceRoutePlugin("deletePageRoute"));
+  }
+  // Module-conditional (commerce, D-47): checkout moved to its own module.
+  if (isModuleEnabled("commerce")) {
+    await server.register(await sliceRoutePlugin("checkoutRoutes"));
   }
-  await server.register(checkoutRoutes);
   // Deliverable download — a capability-token URL (#3961 D5); the token
-  // itself is the sole gate, so no auth preHandler applies.
-  await server.register(deliverableDownloadRoute);
+  // itself is the sole gate, so no auth preHandler applies. Module-conditional
+  // (signal-collectors, D-48): gated PDFs and reports.
+  if (isModuleEnabled("signal-collectors")) {
+    await server.register(await sliceRoutePlugin("deliverableDownloadRoute"));
+  }
 
   // Webhooks routes — raw-body parser scoped to this sub-router only so the
   // global JSON parser on all other routes is unaffected.
   await server.register(async (webhooksScope) => {
     webhooksScope.addContentTypeParser(
-      'application/json',
-      { parseAs: 'buffer' },
+      "application/json",
+      { parseAs: "buffer" },
       (_req, body, done) => {
         done(null, body);
       },
@@ -349,14 +669,24 @@ export async function build() {
     // field (#4999) — raw buffer here too, so the signature is verified over
     // the EXACT bytes Slack signed, never a re-serialized parse.
     webhooksScope.addContentTypeParser(
-      'application/x-www-form-urlencoded',
-      { parseAs: 'buffer' },
+      "application/x-www-form-urlencoded",
+      { parseAs: "buffer" },
       (_req, body, done) => {
         done(null, body);
       },
     );
-    await webhooksScope.register(webhooksRoutes);
-    await webhooksScope.register(slackActionsRoute);
+    // Stripe webhook receiver — module-conditional (commerce, D-47). The
+    // scope wrapper and both raw-body parsers above stay unconditional: the
+    // Slack parser below needs them too (D2).
+    if (isModuleEnabled("commerce")) {
+      await webhooksScope.register(await sliceRoutePlugin("webhooksRoutes"));
+    }
+    // Project-listing operator decision (Slack Approve/Reject) — the "hand an
+    // operator a decision" half of D-48's grouping sentence. Module-conditional
+    // (signal-collectors).
+    if (isModuleEnabled("signal-collectors")) {
+      await webhooksScope.register(await sliceRoutePlugin("slackActionsRoute"));
+    }
   });
 
   // Leads routes — rate-limit middleware scoped to this sub-router. Own
@@ -373,20 +703,43 @@ export async function build() {
     // Project-listings anonymous surface (#4998, reshaped by #5036) — the
     // three-operation draft lifecycle plus the public page-render read, all
     // on the same rate-limited, identity-blind posture as the leads routes
-    // above.
+    // above. Module-conditional (signal-collectors, D-48): the listing
+    // instrument's application-lifecycle half.
     //
     // Do NOT read that rate limit as a bound on anonymous draft creation. It
     // keys on `req.ip`, and `trustProxy` is on (see the note at the top of this
     // file), so a caller reaching the API directly can vary
     // `X-Forwarded-For` and get a fresh budget per request. That is a
     // pre-existing property of the limiter, not of these routes; what these
-    // routes do is keep the cost of an unbounded call small — `start` writes
-    // one row and sends nothing, and the Lead write with its operator
-    // notification waits for `submit` (PR #5042 security review, finding 4).
-    await leadsScope.register(projectListingStartRoute);
-    await leadsScope.register(projectListingDraftPatchRoute);
-    await leadsScope.register(projectListingSubmitRoute);
-    await leadsScope.register(projectListingPublicRoute);
+    // routes do is keep the cost of an unbounded call small — the Lead write
+    // with its operator notification waits for `submit` (PR #5042 security
+    // review, finding 4).
+    //
+    // `start` DOES now send one email (#5406, the founder's resume link), so
+    // the older form of this note — "`start` writes one row and sends
+    // nothing" — no longer holds. That send is opt-in per site, and where it
+    // is on it is bounded in the send path rather than per IP
+    // (`services/project-listing-resume-email.ts`), precisely because this IP
+    // limiter cannot carry the weight of an outbound-mail decision. Two bounds,
+    // both counted in the database so they hold across instances: PER RECIPIENT
+    // (PR #5411 security review, finding 1) and, since #5414, PER SITE across
+    // every recipient — the residual the first one left, and the one that
+    // decides whether a flood can cost the site its sending domain.
+    if (isModuleEnabled("signal-collectors")) {
+      await leadsScope.register(await sliceRoutePlugin("projectListingStartRoute"));
+      await leadsScope.register(
+        await sliceRoutePlugin("projectListingDraftPatchRoute"),
+      );
+      await leadsScope.register(await sliceRoutePlugin("projectListingSubmitRoute"));
+      // #5407 — the resume link's verification write. Anonymous, and gated
+      // on the resume token AND the nonce that only the resume email
+      // carries, so it belongs in the same rate-limited scope as the other
+      // three.
+      await leadsScope.register(
+        await sliceRoutePlugin("projectListingVerifyEmailRoute"),
+      );
+      await leadsScope.register(await sliceRoutePlugin("projectListingPublicRoute"));
+    }
   });
 
   // Flows routes — anonymous surface; rate-limit middleware scoped to this
@@ -397,13 +750,23 @@ export async function build() {
   // scope #4730's bump was actually sized for; unchanged by #5111.
   await server.register(async (flowsScope) => {
     flowsScope.register(rateLimitMiddleware);
-    await flowsScope.register(getFlowRoute);
-    await flowsScope.register(submitFlowStepRoute);
-    await flowsScope.register(getFlowAggregateRoute);
+    // Flow engine reads (#3956) — module-conditional (signal-collectors,
+    // D-48). The scope itself and its rate limiter above stay unconditional
+    // (D2) — commerce's recommender routes below need them too.
+    if (isModuleEnabled("signal-collectors")) {
+      await flowsScope.register(await sliceRoutePlugin("getFlowRoute"));
+      await flowsScope.register(await sliceRoutePlugin("submitFlowStepRoute"));
+      await flowsScope.register(await sliceRoutePlugin("getFlowAggregateRoute"));
+    }
     // The recommender's email-moment routes (#4841) — same anonymous,
-    // rate-limited posture as the three above.
-    await flowsScope.register(saveRecommendationRoute);
-    await flowsScope.register(checkoutRecommendationRoute);
+    // rate-limited posture as the three above. Module-conditional (commerce,
+    // D-47): the recommender leaves Pro flows and moves to commerce whole.
+    if (isModuleEnabled("commerce")) {
+      await flowsScope.register(await sliceRoutePlugin("saveRecommendationRoute"));
+      await flowsScope.register(
+        await sliceRoutePlugin("checkoutRecommendationRoute"),
+      );
+    }
   });
 
   // AEO score routes (#4666) — anonymous surface, same posture as the flows
@@ -428,14 +791,18 @@ export async function build() {
   // (#5111, DEF-004). Module-conditional (S1, #5088): the scheduling module
   // owns this whole route set, so an OSS build that excludes it registers
   // neither the routes nor their imports.
-  if (isModuleEnabled('scheduling')) {
+  if (isModuleEnabled("scheduling")) {
     await server.register(async (scheduleScope) => {
       scheduleScope.register(rateLimitMiddleware, {
         perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
       });
-      await scheduleScope.register(await sliceRoutePlugin('listAvailabilityRoute'));
-      await scheduleScope.register(await sliceRoutePlugin('getEventMetaRoute'));
-      await scheduleScope.register(await sliceRoutePlugin('createBookingRoute'));
+      await scheduleScope.register(
+        await sliceRoutePlugin("listAvailabilityRoute"),
+      );
+      await scheduleScope.register(await sliceRoutePlugin("getEventMetaRoute"));
+      await scheduleScope.register(
+        await sliceRoutePlugin("createBookingRoute"),
+      );
     });
   }
 
@@ -447,7 +814,7 @@ export async function build() {
   if (shouldMountTestAuth()) {
     await server.register(registerTestAuthRoute);
     server.log.warn(
-      'test-auth route MOUNTED — only safe in dev/test environments',
+      "test-auth route MOUNTED — only safe in dev/test environments",
     );
   }