create-ailk 0.2.0 → 0.4.0

package/templates/apps/api/src/lib/slice-load.ts

@@ -0,0 +1,90 @@
+/**
+ * Slice-module load boundary (#5334 D4).
+ *
+ * Every paid-module SLICE in `apps/api` is reached through an indirect dynamic
+ * `import()` — a specifier the call site never writes as a literal, because
+ * `tsc` would then resolve it and the OSS strip would break (#5182 D1). #5304
+ * moved those specifiers onto module-level constants, the one shape that is
+ * simultaneously unresolvable to `tsc` and traceable to `@vercel/nft`, so the
+ * files reach a Vercel deployment.
+ *
+ * WHAT THIS FILE IS FOR. That shape is correct for the deploy path the scaffold
+ * ships, and it cannot be made to work under a BUNDLER. esbuild bundles a
+ * dynamic `import()` iff its argument is a string literal at the call site —
+ * exactly the predicate `tsc` resolves on, and exactly the one #5182 D1
+ * requires be false. So in a bundled build the specifier survives verbatim and
+ * Node resolves it against the BUNDLE OUTPUT directory rather than the source
+ * module's: `"./list.js"`, written in `routes/project-listings/index.ts`,
+ * becomes `dist/list.js` and does not exist. `build()` throws during
+ * CONSTRUCTION, so every route 500s rather than one.
+ *
+ * The failure is otherwise silent on every channel: esbuild emits no warning
+ * for the imports it declines to bundle, and a consuming frontend degrades to
+ * an empty list and still answers 200. `salessmyth/samhenry` spent nine hours
+ * on it. This boundary is what turns that into a one-line diagnosis — it does
+ * not make bundling work, because nothing in this file could.
+ *
+ * WHY IT TAKES A THUNK AND NOT A SPECIFIER. `loadSlice("./list.js")` doing the
+ * `import()` in here would be the obvious signature and would silently undo
+ * #5304. `enumerateSliceSpecifiers()` treats a file as an "indirect file" only
+ * if it carries a dynamic `import()` with a non-literal argument; move the call
+ * out of the callers and they stop qualifying, their specifier constants stop
+ * being candidates, and `check-slice-reachability.ts` passes vacuously over an
+ * empty set. Worse, `@vercel/nft` constant-propagates `WORKSPACES_INDEX` into
+ * `import(WORKSPACES_INDEX)` only because the constant and the call sit in one
+ * module — hoist the call and there is nothing to propagate, so every slice
+ * file goes untraced and #5304's outage returns with its own gate green.
+ *
+ * So the `import()` stays at the call site, in the caller's module, and this
+ * function only awaits the thunk and interprets the failure.
+ *
+ * Gated by `scripts/check-bundled-build-diagnoses.ts`, which bundles `apps/api`
+ * and asserts that the boot fails WITH this diagnostic rather than without one.
+ */
+
+/**
+ * Node reports an unresolvable ESM specifier as `ERR_MODULE_NOT_FOUND` and an
+ * unresolvable CJS one as `MODULE_NOT_FOUND`. A bundle can produce either,
+ * since a bundled graph mixes both.
+ */
+const MODULE_NOT_FOUND_CODES = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
+
+function isModuleNotFound(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  return typeof code === "string" && MODULE_NOT_FOUND_CODES.has(code);
+}
+
+/**
+ * Await a slice module's loader thunk, turning an unresolvable module into a
+ * diagnosis instead of a bare `ERR_MODULE_NOT_FOUND` on a path that never
+ * existed.
+ *
+ * Anything that is not a module-resolution failure is rethrown UNTOUCHED — the
+ * same object, not a wrapper. A slice that throws while evaluating is a real
+ * bug in the slice and must keep its own stack and type.
+ *
+ * @param specifier the module specifier the thunk imports, for the message.
+ *   Every call site already has it in scope, so nothing is enumerated here.
+ * @param load the caller's own `() => import(CONST)` thunk. Must close over a
+ *   constant in the CALLER's module — see the file header.
+ */
+export async function loadSlice(
+  specifier: string,
+  load: () => Promise<unknown>,
+): Promise<unknown> {
+  try {
+    return await load();
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error;
+    throw new Error(
+      `AILK slice module '${specifier}' could not be resolved at runtime. ` +
+        `This throws during server construction, so every route fails, not one. Two causes produce it:\n` +
+        `  1. The module was compiled but not SHIPPED — the deploy-time file tracer did not emit it (#5304). ` +
+        `Check with \`pnpm slice-reachability:check\`.\n` +
+        `  2. This build was BUNDLED. apps/api does not support bundling (#5334): a bundler resolves this ` +
+        `specifier against the bundle's own output directory rather than its source module's, and esbuild ` +
+        `leaves it unbundled without a warning. See apps/api/CLAUDE.md § Deploy path.`,
+      { cause: error },
+    );
+  }
+}

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -28,10 +28,10 @@ describe("GET /api/openapi.json", () => {
 
     const spec = JSON.parse(res.body);
     expect(spec.openapi).toBe("3.1.0");
-    expect(spec.info).toMatchObject({
-      title: "AI Launch Kit — Public Content API",
-      version: "1.0.0",
-    });
+    // The title is resolved from the serving site's own `_site.mdx` (#5307),
+    // so assert its SHAPE rather than a literal site name — the same build
+    // serves a different title on every consuming site.
+    expect(spec.info.title).toMatch(/Public Content API$/);
     expect(spec.info.version).toBe("1.0.0");
     expect(typeof spec.paths).toBe("object");
   });
@@ -54,39 +54,59 @@ describe("GET /api/openapi.json", () => {
     );
   });
 
-  it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
+  // The checkout path's OpenAPI documentation is module-conditional (commerce,
+  // D-47 / #5364) — mirroring the route's own registration gate in server.ts —
+  // so these two assertions need the module enabled, exactly as a real
+  // commerce-installed deployment would have it.
+  describe("checkout endpoint (commerce module enabled)", () => {
+    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
+
+    beforeEach(() => {
+      process.env.AILK_ENABLED_MODULES = "commerce";
     });
 
-    const spec = JSON.parse(res.body);
-    expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
-      "createCheckoutSession",
-    );
-  });
+    afterEach(() => {
+      if (PRIOR_ENABLED_MODULES === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
+      }
+    });
 
-  it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
+    it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
+        "createCheckoutSession",
+      );
     });
 
-    const spec = JSON.parse(res.body);
-    const responses = spec.paths["/v1/checkout/sessions"].post.responses;
-    expect(responses["201"].description).toBe("Checkout session created");
-    expect(responses["400"].description).toBe(
-      "Validation error — invalid request body",
-    );
-    expect(responses["404"].description).toBe(
-      "Unknown product code — no active Stripe price for the given productCode",
-    );
-    expect(responses["500"].description).toBe(
-      "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
-    );
-    expect(responses["502"].description).toBe(
-      "Checkout unavailable — Stripe returned an unexpected error",
-    );
+    it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/openapi.json",
+      });
+
+      const spec = JSON.parse(res.body);
+      const responses = spec.paths["/v1/checkout/sessions"].post.responses;
+      expect(responses["201"].description).toBe("Checkout session created");
+      expect(responses["400"].description).toBe(
+        "Validation error — invalid request body",
+      );
+      expect(responses["404"].description).toBe(
+        "Unknown product code — no active Stripe price for the given productCode",
+      );
+      expect(responses["500"].description).toBe(
+        "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
+      );
+      expect(responses["502"].description).toBe(
+        "Checkout unavailable — Stripe returned an unexpected error",
+      );
+    });
   });
 
   it("declares query and path parameters for content endpoints", async () => {

package/templates/apps/api/src/openapi/__tests__/spec-identity.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @file spec-identity.test.ts
+ *
+ * The served API's self-description (#5307) and the `servers` block (#5306).
+ *
+ * These assert the BUILDER's output given a config rather than a deployed
+ * response: the defect is that a deployed site serves the kit's identity and
+ * the kit's host, and the builder is the only place that can be proved
+ * without deploying.
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  API_VERSION,
+  apiDescription,
+  apiDisplayName,
+  buildOpenApiSpec,
+  resetApiIdentity,
+  resolveApiIdentity,
+} from "../spec";
+
+/** Write a throwaway content root carrying the given `_site.mdx` frontmatter. */
+function withContentRoot(frontmatter: string): string {
+  const root = mkdtempSync(join(tmpdir(), "ailk-site-"));
+  mkdirSync(root, { recursive: true });
+  writeFileSync(join(root, "_site.mdx"), `---\n${frontmatter}\n---\n\nbody\n`);
+  return root;
+}
+
+describe("buildOpenApiSpec — site identity (#5307)", () => {
+  it("titles the spec after the site, not after the kit", () => {
+    const spec = buildOpenApiSpec({ siteName: "Sam Henry" });
+
+    expect(spec.info.title).toBe("Sam Henry — Public Content API");
+    expect(JSON.stringify(spec.info)).not.toMatch(/AI Launch Kit|AILK/i);
+  });
+
+  it("degrades to a named neutral title when no site name is resolvable", () => {
+    const spec = buildOpenApiSpec({});
+
+    expect(spec.info.title).toBe("Public Content API");
+    expect(spec.info.title).not.toMatch(/AI Launch Kit|AILK/i);
+  });
+
+  it("asserts no licence over a deployment that has not chosen one", () => {
+    expect(buildOpenApiSpec({ siteName: "Sam Henry" }).info).not.toHaveProperty(
+      "license",
+    );
+  });
+
+  it("keeps API_VERSION as the /v1 contract version", () => {
+    expect(API_VERSION).toBe("1.0.0");
+    expect(buildOpenApiSpec({}).info.version).toBe(API_VERSION);
+  });
+});
+
+describe("buildOpenApiSpec — servers block (#5306)", () => {
+  it("names the deployment's own API origin", () => {
+    const spec = buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org" });
+
+    expect(spec.servers).toEqual([
+      { url: "https://api.samhenry.org", description: expect.any(String) },
+    ]);
+  });
+
+  it("never serves the kit's own host", () => {
+    const spec = buildOpenApiSpec({
+      siteName: "Sam Henry",
+      publicApiUrl: "https://api.samhenry.org",
+    });
+
+    expect(JSON.stringify(spec)).not.toContain("ailaunchkit.ai");
+  });
+
+  it("normalises a trailing slash", () => {
+    expect(
+      buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org/" }).servers[0]
+        ?.url,
+    ).toBe("https://api.samhenry.org");
+  });
+
+  it("degrades to a document-relative origin when the value is unset", () => {
+    const spec = buildOpenApiSpec({});
+
+    expect(spec.servers).toHaveLength(1);
+    expect(spec.servers[0]?.url).toBe("/");
+    // The degradation is named in the served document itself, so an agent
+    // reading the spec learns why rather than following a wrong absolute URL.
+    expect(spec.servers[0]?.description).toMatch(/AILK_PUBLIC_API_URL/);
+  });
+
+  it("degrades rather than serving a malformed origin", () => {
+    expect(buildOpenApiSpec({ publicApiUrl: "not-a-url" }).servers[0]?.url).toBe(
+      "/",
+    );
+    expect(
+      buildOpenApiSpec({ publicApiUrl: "ftp://api.example.com" }).servers[0]
+        ?.url,
+    ).toBe("/");
+  });
+});
+
+describe("resolveApiIdentity — reads _site.mdx", () => {
+  const originalContentRoot = process.env.CONTENT_ROOT;
+  let root: string | undefined;
+
+  afterEach(() => {
+    if (originalContentRoot === undefined) delete process.env.CONTENT_ROOT;
+    else process.env.CONTENT_ROOT = originalContentRoot;
+    if (root) rmSync(root, { recursive: true, force: true });
+    root = undefined;
+    resetApiIdentity();
+  });
+
+  it("sources the site name and description from _site.mdx", () => {
+    root = withContentRoot(
+      [
+        'version: "1"',
+        "siteName: Sam Henry",
+        "baseUrl: https://samhenry.org",
+        "siteIdentity:",
+        "  kind: Person",
+        "  name: Sam Henry",
+        "  description: Independent software consultant.",
+      ].join("\n"),
+    );
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+
+    expect(identity.siteName).toBe("Sam Henry");
+    expect(identity.siteDescription).toBe("Independent software consultant.");
+    expect(apiDisplayName(identity)).toBe("Sam Henry API");
+    expect(apiDescription(identity)).toBe("Independent software consultant.");
+  });
+
+  // #5306 AC-3 — the trap this card exists to refuse.
+  it("does NOT use _site.mdx baseUrl as the API origin", () => {
+    root = withContentRoot(
+      [
+        'version: "1"',
+        "siteName: Sam Henry",
+        // The SITE origin. The API is deployed on a different host
+        // (api.samhenry.org), so this value must never reach `servers`.
+        "baseUrl: https://samhenry.org",
+      ].join("\n"),
+    );
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+    expect(identity.publicApiUrl).not.toBe("https://samhenry.org");
+
+    const spec = buildOpenApiSpec({ ...identity, publicApiUrl: undefined });
+    expect(JSON.stringify(spec.servers)).not.toContain("samhenry.org");
+  });
+
+  it("degrades to a named neutral default when _site.mdx is unreadable", () => {
+    root = mkdtempSync(join(tmpdir(), "ailk-empty-"));
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    const identity = resolveApiIdentity();
+
+    expect(identity.siteName).toBeUndefined();
+    expect(apiDisplayName(identity)).toBe("Content API");
+    expect(apiDisplayName(identity)).not.toMatch(/AI Launch Kit|AILK/i);
+    expect(buildOpenApiSpec(identity).info.title).toBe("Public Content API");
+  });
+
+  it("degrades when _site.mdx frontmatter is malformed", () => {
+    root = withContentRoot("siteName: [unclosed");
+    process.env.CONTENT_ROOT = root;
+    resetApiIdentity();
+
+    expect(resolveApiIdentity().siteName).toBeUndefined();
+    expect(apiDisplayName(resolveApiIdentity())).toBe("Content API");
+  });
+});

package/templates/apps/api/src/openapi/__tests__/surface-drift.test.ts

@@ -0,0 +1,293 @@
+/**
+ * @file surface-drift.test.ts
+ * @description The self-description drift gate (#5314).
+ *
+ * Builds the REAL server, takes the route table Fastify actually registered,
+ * and diffs it against both surfaces that claim to describe it — the root
+ * index `endpoints` object and the served OpenAPI `paths` object.
+ *
+ * Both surfaces are read over `inject`, i.e. exactly what an agent would
+ * fetch, never the object the builder returned.
+ *
+ * This gate was RED before the derivation landed: 61 registered routes were
+ * missing from `paths` and 53 from `endpoints`. Two of its five concerns
+ * (AC-1 coverage on each surface) are unfailable now that both surfaces
+ * derive from the same registry they are compared against — that is the
+ * inherent consequence of AC-2's "derived" branch, and the spec's D5 says so.
+ * What stays live is the overlay join (a hand-authored entry whose route no
+ * longer registers — the concern that caught `DELETE /v1/auth/tokens`, whose
+ * real path is `/v1/auth/tokens/:id`), the anti-vacuity floor (an empty or
+ * stale registry would pass a coverage check trivially, so it is asserted
+ * against directly), and the module-agreement case's non-empty guard, which
+ * fails if module gating ever collapses so both configs register identically.
+ *
+ * Mirrors `src/__tests__/module-exclusion.test.ts`'s external-boundary mocks
+ * (CORS, rate-limit, email) — see that file's header for why each is mocked.
+ */
+
+jest.mock("@fastify/cors", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@fastify/rate-limit", () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import { build } from "../../server";
+import { readRegisteredRoutes } from "../spec";
+import {
+  compareSurfaces,
+  formatSurfaceDrift,
+  hasDrift,
+  openApiSurfaceKeys,
+  rootIndexSurfaceKeys,
+  routeKey,
+  toOpenApiPath,
+  type RegisteredRoute,
+} from "../surface-drift";
+
+/** A route every build registers, outside every module conditional. */
+const FLOOR_ROUTE = routeKey("GET", "/v1/content/types");
+
+interface Surfaces {
+  registered: RegisteredRoute[];
+  paths: Record<string, Record<string, unknown>>;
+  endpoints: Record<string, string>;
+}
+
+/**
+ * Build the server under one module configuration and read both surfaces back
+ * over the wire. `undefined` means "leave AILK_ENABLED_MODULES unset", which
+ * is now the default deployment shape (no paid module, D-44 / #5368).
+ */
+async function surfacesFor(enabled: string | undefined): Promise<Surfaces> {
+  const prior = process.env.AILK_ENABLED_MODULES;
+  if (enabled === undefined) {
+    delete process.env.AILK_ENABLED_MODULES;
+  } else {
+    process.env.AILK_ENABLED_MODULES = enabled;
+  }
+
+  try {
+    const app = await build();
+    await app.ready();
+
+    const registered = [...readRegisteredRoutes(app)];
+
+    const rootRes = await app.inject({ method: "GET", url: "/" });
+    const specRes = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    await app.close();
+
+    expect(rootRes.statusCode).toBe(200);
+    expect(specRes.statusCode).toBe(200);
+
+    return {
+      registered,
+      paths: JSON.parse(specRes.body).paths,
+      endpoints: JSON.parse(rootRes.body).endpoints,
+    };
+  } finally {
+    if (prior === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = prior;
+    }
+  }
+}
+
+// The module configurations every claim below is asserted under. Unset is now
+// the default deployment (no paid module, D-44 / #5368), the same as an
+// explicit "" (the OSS-strip build target); a full allowlist is the
+// every-module-on case. A slice route absent under "" must be absent from
+// BOTH surfaces there, which is what makes its absence agreement rather than
+// drift.
+const ALL_PAID_MODULES =
+  "docs,multi-tenant,scheduling,content-write,signal-collectors";
+const CONFIGS: Array<[string, string | undefined]> = [
+  ["AILK_ENABLED_MODULES unset (no paid module, the default)", undefined],
+  ['AILK_ENABLED_MODULES="" (no paid module)', ""],
+  [
+    `AILK_ENABLED_MODULES="${ALL_PAID_MODULES}" (every paid module on)`,
+    ALL_PAID_MODULES,
+  ],
+];
+
+describe("API self-description drift (#5314)", () => {
+  describe.each(CONFIGS)("%s", (_label, enabled) => {
+    let surfaces: Surfaces;
+
+    beforeAll(async () => {
+      surfaces = await surfacesFor(enabled);
+    }, 60000);
+
+    // Anti-vacuity floor. A coverage assertion over an empty registry passes
+    // trivially, so an empty or stale registry is failed directly — the most
+    // likely way a derivation gate silently stops testing anything.
+    it("registers a non-empty route table including the floor route", () => {
+      expect(surfaces.registered.length).toBeGreaterThan(0);
+      const keys = surfaces.registered.map((r) => routeKey(r.method, r.url));
+      expect(keys).toContain(FLOOR_ROUTE);
+      expect(new Set(keys).size).toBe(keys.length);
+    });
+
+    it("publishes no surface entry for a route the server does not register", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      const orphaned = diffs.filter((d) => d.orphanedInSurface.length > 0);
+      expect(formatSurfaceDrift(orphaned)).toBe("");
+    });
+
+    it("describes every registered route on both surfaces", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      expect(formatSurfaceDrift(diffs)).toBe("");
+      expect(hasDrift(diffs)).toBe(false);
+    });
+
+    // AC-1 names this endpoint specifically: it returns 200 and is what the
+    // consuming site depends on, and before #5314 both surfaces omitted it.
+    // #5366 (D-48) moved it to signal-collectors: the no-drift half
+    // (`missingFromSurface`) holds regardless of whether the route
+    // registers at all, but the route itself now only registers when
+    // signal-collectors is one of the enabled modules for this config.
+    it("describes GET /v1/project-listings/public on both surfaces when registered", () => {
+      const diffs = compareSurfaces(
+        surfaces.registered,
+        surfaces.paths,
+        surfaces.endpoints,
+      );
+      for (const d of diffs) {
+        expect(d.missingFromSurface).not.toContain(
+          routeKey("GET", "/v1/project-listings/public"),
+        );
+      }
+      const signalCollectorsEnabled = (enabled ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .includes("signal-collectors");
+      expect(
+        surfaces.registered.some(
+          (r) => r.url === "/v1/project-listings/public" && r.method === "GET",
+        ),
+      ).toBe(signalCollectorsEnabled);
+    });
+  });
+
+  // Regression: the route table is per-instance, not module state.
+  //
+  // `vercel-handler.ts`'s `getServer()` is a check-then-set — it tests
+  // `!serverInstance`, then awaits twice before assigning — so two concurrent
+  // invocations can both call `build()`. With a module-level table, one
+  // build's reset would land mid-fill of the other and leave a truncated or
+  // doubled set, and both surfaces would silently misreport. Building two
+  // servers under DIFFERENT module configs and asserting each keeps its own
+  // table is what makes that unreachable rather than merely unlikely.
+  it("keeps each server's route table on its own instance", async () => {
+    const prior = process.env.AILK_ENABLED_MODULES;
+    try {
+      process.env.AILK_ENABLED_MODULES = ALL_PAID_MODULES;
+      const allOn = await build();
+      await allOn.ready();
+
+      process.env.AILK_ENABLED_MODULES = "";
+      const noneOn = await build();
+      await noneOn.ready();
+
+      const allKeys = readRegisteredRoutes(allOn).map((r) =>
+        routeKey(r.method, r.url),
+      );
+      const noneKeys = readRegisteredRoutes(noneOn).map((r) =>
+        routeKey(r.method, r.url),
+      );
+
+      // The second build must not have emptied, truncated or doubled the
+      // first — the exact corruption a shared table would produce.
+      expect(allKeys.length).toBeGreaterThan(noneKeys.length);
+      expect(new Set(allKeys).size).toBe(allKeys.length);
+      expect(new Set(noneKeys).size).toBe(noneKeys.length);
+      expect(allKeys).toContain(FLOOR_ROUTE);
+      expect(noneKeys).toContain(FLOOR_ROUTE);
+
+      // And each server's own OpenAPI document still matches its own table.
+      for (const app of [allOn, noneOn]) {
+        const paths = JSON.parse(
+          (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
+        ).paths;
+        const endpoints = JSON.parse(
+          (await app.inject({ method: "GET", url: "/" })).body,
+        ).endpoints;
+        expect(
+          formatSurfaceDrift(
+            compareSurfaces(readRegisteredRoutes(app), paths, endpoints),
+          ),
+        ).toBe("");
+      }
+
+      await allOn.close();
+      await noneOn.close();
+    } finally {
+      if (prior === undefined) {
+        delete process.env.AILK_ENABLED_MODULES;
+      } else {
+        process.env.AILK_ENABLED_MODULES = prior;
+      }
+    }
+  }, 60000);
+
+  // AC-4. Asserted as agreement rather than as an exemption list: a disabled
+  // module's routes vanish from the registered set and from both surfaces at
+  // once, so there is nothing for the gate to forgive.
+  it("drops a disabled module's routes from the route table AND both surfaces together", async () => {
+    const allOn = await surfacesFor(ALL_PAID_MODULES);
+    const noneOn = await surfacesFor("");
+
+    const noneKeys = new Set(
+      noneOn.registered.map((r) => routeKey(r.method, r.url)),
+    );
+    const moduleOnly = allOn.registered.filter(
+      (r) => !noneKeys.has(routeKey(r.method, r.url)),
+    );
+
+    // The configurations must actually differ, or this asserts nothing.
+    expect(moduleOnly.length).toBeGreaterThan(0);
+
+    // Every module-only route is described when its module is on...
+    expect(
+      formatSurfaceDrift(
+        compareSurfaces(allOn.registered, allOn.paths, allOn.endpoints),
+      ),
+    ).toBe("");
+
+    // ...and named by neither surface when it is off, which is agreement.
+    //
+    // Each surface is parsed by the instrument's own reader, and each route is
+    // compared in that surface's vocabulary — OpenAPI-templated for `paths`,
+    // Fastify-shaped for `endpoints`. Comparing raw values instead would make
+    // this assertion quietly weaker than it reads: `paths` keys `{id}` where a
+    // registered route says `:id`, so every parametric route would "pass" on a
+    // vocabulary mismatch, and `endpoints` groups methods into one value
+    // (`"GET/PUT/DELETE /v1/user/data/:key"`), which never equals a
+    // single-method key. Both halves would then be vacuous for exactly the
+    // routes most likely to regress.
+    const offPathKeys = openApiSurfaceKeys(noneOn.paths);
+    const offEndpointKeys = rootIndexSurfaceKeys(noneOn.endpoints);
+    for (const { method, url } of moduleOnly) {
+      expect(offPathKeys).not.toContain(routeKey(method, toOpenApiPath(url)));
+      expect(offEndpointKeys).not.toContain(routeKey(method, url));
+    }
+  }, 60000);
+});