create-ailk 0.12.0 → 0.13.0

package/templates/apps/api/src/routes/leads/__tests__/spoke.test.ts

@@ -3,12 +3,17 @@
  *
  * `POST /v1/leads/{submit,subscribe,callback}` called by a registered spoke of
  * a multi-workspace hub (#7532, spec
- * docs/specs/7532-a-spoke-s-public-reads-spec.md D3, D4; AC-2, AC-3, AC-5).
+ * docs/specs/7532-a-spoke-s-public-reads-spec.md D3, D4; AC-2, AC-3, AC-5),
+ * and a keyless caller of the same hub, refused with no switch set since #7633
+ * (spec docs/specs/7633-expected-a-keyless-public-read-spec.md D3, D8; AC-1,
+ * AC-5).
  * The three real lead routes run through the real resolver and the real
  * lead-routing service; only the database and the email provider are doubles.
  *
  * Fixture (spec § 5): three workspaces — the sentinel default `F` (the site
  * alias), `W1` and `W2`; spokes `S1` → `W1`, `S1b` → `W1`, `S2` → `W2`.
+ * The registry is non-empty (`db.spoke.findFirst` answers a row), so this is
+ * a hub in the #7633 sense.
  */
 import { createHash } from "node:crypto";
 import { Writable } from "node:stream";
@@ -51,12 +56,14 @@ jest.mock("../../../services/request-confirm.js", () => {
 });
 
 import * as configModule from "../../../config/index.js";
+import type { HubSpokeKeyMode } from "../../../config/index.js";
 import {
   SENTINEL_WORKSPACE_ID,
   mockSentinelWorkspaceExists,
 } from "../../../lib/__mocks__/prisma.js";
 import { prisma } from "../../../lib/prisma.js";
 import { __resetSiteWorkspaceCacheForTests } from "../../../lib/site.js";
+import { __resetHubStatusForTests } from "../../../services/public-site-resolver.js";
 import { sendRequestConfirmLink } from "../../../services/request-confirm.js";
 import { setupLeadFileEnv } from "../../../__tests__/factories/lead-fixture";
 import { leadCallbackRoute, leadSubmitRoute, leadSubscribeRoute } from "../index";
@@ -99,12 +106,14 @@ function seedRegistry(revoked: readonly string[] = []): void {
   }: {
     where: { credentialHash: string };
   }) => rows.get(where.credentialHash) ?? null) as never);
+  // A non-empty registry: this deployment is a hub (#7633 D1).
+  db.spoke.findFirst.mockResolvedValue({ id: S1 } as never);
 }
 
-function setStrictMode(on: boolean): void {
+function setMode(mode: HubSpokeKeyMode): void {
   jest.replaceProperty(configModule, "config", {
     ...configModule.config,
-    AILK_HUB_REQUIRE_SPOKE_KEY: on,
+    AILK_HUB_REQUIRE_SPOKE_KEY: mode,
   });
 }
 
@@ -156,7 +165,8 @@ describe("a spoke calling the lead routes on a multi-workspace hub", () => {
     process.env.DATABASE_URL = "postgres://stub";
     process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
     process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
-    setStrictMode(false);
+    setMode("auto");
+    __resetHubStatusForTests();
     seedRegistry();
     mockSentinelWorkspaceExists(db, W1, W2);
     db.workspace.count.mockResolvedValue(3);
@@ -249,27 +259,77 @@ describe("a spoke calling the lead routes on a multi-workspace hub", () => {
     expect(db.callback.updateMany).not.toHaveBeenCalled();
   });
 
+  // ── #7633 AC-1 — a keyless call on a hub, with no switch set ────────────
+
+  it.each<Kind>(["submit", "subscribe", "callback"])(
+    "a keyless POST /v1/leads/%s naming siteId W1 answers 503 tenant_unresolved — the very body an unknown key gets — with no write (#7633 AC-1)",
+    async (kind) => {
+      const body = { ...BODIES[kind], siteId: W1 };
+      const keyless = await post(kind, {}, body);
+
+      expect(keyless.statusCode).toBe(503);
+      expect(keyless.json().error).toBe("tenant_unresolved");
+      expectNoWrite();
+
+      const unknown = await post(kind, { "x-ailk-spoke-key": KEY_UNKNOWN }, body);
+      expect(keyless.statusCode).toBe(unknown.statusCode);
+      expect(keyless.json()).toEqual(unknown.json());
+      expectNoWrite();
+    },
+  );
+
+  // ── #7633 conductor amendment — lead capture is never lost ──────────────
+
+  it("a cold start whose hub-status read fails still captures a keyless lead (it reaches routeLead), logged at error", async () => {
+    __resetHubStatusForTests();
+    db.spoke.findFirst.mockRejectedValue(new Error("connection reset"));
+
+    const res = await post("submit");
+    expect(res.statusCode).toBe(201);
+    expect(db.lead.create).toHaveBeenCalledTimes(1);
+    const { data } = db.lead.create.mock.calls[0]![0] as { data: { siteId: string } };
+    expect(data.siteId).toBe(F);
+    expect(logLines.join("\n")).toContain('"level":50');
+  });
+
+  it("a process that has seen a hub keeps refusing a keyless lead through the same outage", async () => {
+    expect((await post("submit")).statusCode).toBe(503);
+    db.spoke.findFirst.mockRejectedValue(new Error("connection reset"));
+    expect((await post("submit")).statusCode).toBe(503);
+    expectNoWrite();
+  });
+
   // ── AC-3 ────────────────────────────────────────────────────────────────
 
-  describe.each<[string, Record<string, string>, boolean]>([
-    ["(i) an unregistered key", { "x-ailk-spoke-key": KEY_UNKNOWN }, false],
-    ["(ii) a duplicated header", { "x-ailk-spoke-key": `${KEY_S1}, ${KEY_S2}` }, false],
-    ["(iii) an empty key", { "x-ailk-spoke-key": "" }, false],
+  describe.each<[string, Record<string, string>, HubSpokeKeyMode]>([
+    ["(i) an unregistered key", { "x-ailk-spoke-key": KEY_UNKNOWN }, "auto"],
+    ["(ii) a duplicated header", { "x-ailk-spoke-key": `${KEY_S1}, ${KEY_S2}` }, "auto"],
+    ["(iii) an empty key", { "x-ailk-spoke-key": "" }, "auto"],
+    [
+      "(v) mode \"on\", a header-less request naming W1 every other way",
+      {
+        host: "w1.example",
+        "x-forwarded-host": "w1.example",
+        origin: "https://w1.example",
+        "x-ailk-workspace-id": W1,
+      },
+      "on",
+    ],
     [
-      "(v) strict mode, a header-less request naming W1 every other way",
+      "(v) no switch set, a header-less request naming W1 every other way (#7633)",
       {
         host: "w1.example",
         "x-forwarded-host": "w1.example",
         origin: "https://w1.example",
         "x-ailk-workspace-id": W1,
       },
-      true,
+      "auto",
     ],
-  ])("%s (AC-3)", (_label, headers, strict) => {
+  ])("%s (AC-3)", (_label, headers, mode) => {
     it.each<Kind>(["submit", "subscribe", "callback"])(
       "POST /v1/leads/%s answers 503 tenant_unresolved before any write",
       async (kind) => {
-        setStrictMode(strict);
+        setMode(mode);
         const res = await post(kind, headers, { ...BODIES[kind], siteId: W1 });
 
         expect(res.statusCode).toBe(503);
@@ -311,14 +371,15 @@ describe("a spoke calling the lead routes on a multi-workspace hub", () => {
       expect(otherData.workspaceId).toBe(W2);
     });
 
-    it("in strict mode, S1's header-less retry is refused too", async () => {
-      setStrictMode(true);
+    it.each<HubSpokeKeyMode>(["on", "auto"])("in mode %j, S1's header-less retry is refused too", async (mode) => {
+      setMode(mode);
       const res = await post("submit");
       expect(res.statusCode).toBe(503);
       expectNoWrite();
     });
 
-    it("with strict mode off, S1's header-less retry is anonymous and lands under the alias F, never W1 (SEC-7532-3)", async () => {
+    it("under the emergency opt-out (mode \"off\"), S1's header-less retry is anonymous and lands under the alias F, never W1 (SEC-7532-3)", async () => {
+      setMode("off");
       const res = await post("submit");
       expect(res.statusCode).toBe(201);
       const { data } = db.lead.create.mock.calls[0]![0] as {

package/templates/apps/api/src/routes/leads/index.ts

@@ -34,10 +34,14 @@
  * reads the spoke's key from `x-ailk-spoke-key` through
  * `resolveCallerSite()` (`services/public-site-resolver.ts`) and writes the
  * lead into that spoke's own workspace. A refused key — malformed, unknown or
- * revoked, or no key at all on a hub in strict mode — is the same 503
- * `tenant_unresolved` before any write. A header-less request on a hub
- * without strict mode takes the alias resolution above, unchanged. The body's
- * `siteId` stays ignored on every branch.
+ * revoked, or no key at all on a hub (a deployment whose spoke registry holds
+ * a row, or one whose `AILK_HUB_REQUIRE_SPOKE_KEY` is `true`; #7633) — is the
+ * same 503 `tenant_unresolved` before any write. A header-less request on a
+ * deployment with no registered spoke, or under the emergency opt-out
+ * (`AILK_HUB_REQUIRE_SPOKE_KEY=false`), takes the alias resolution above,
+ * unchanged. So does a keyless request whose hub-status read fails before the
+ * process has any answer: lead capture is never lost (#7633, conductor
+ * amendment to NFR3). The body's `siteId` stays ignored on every branch.
  */
 
 import { track } from "@working-theory/analytics/server";
@@ -143,8 +147,12 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
       };
 
       // #7532 D4 — a registered spoke resolves first, to its own workspace; a
-      // refused key never falls through to the alias below.
-      const caller = await resolveCallerSite(request);
+      // refused key never falls through to the alias below. A keyless lead
+      // whose hub-status read fails on a cold start proceeds as on a non-hub,
+      // so routeLead's outage fallback captures it (#7633 amendment).
+      const caller = await resolveCallerSite(request, {
+        keylessOnRegistryFailure: "anonymous",
+      });
       if (caller.kind === "refused") {
         return reply.status(503).send({
           error: "tenant_unresolved",

package/templates/apps/api/src/routes/project-listings/__tests__/me.test.ts

@@ -16,11 +16,12 @@
  *     (a clause carrying one is treated as a contract violation and returns
  *     nothing, the `flow-checkouts` test's own discipline);
  *   - a signed-in caller who owns nothing gets `200 []`, never a 403;
- *   - `PROJECT_LISTING_ROLES` is untouched and this route never consults it.
+ *   - the tenant routes' permission (`inbox-read`, #7636 D2) is untouched and
+ *     this route never consults it.
  */
 import Fastify from "fastify";
 import type { FastifyInstance } from "fastify";
-import { projectListingMeResponseSchema } from "@working-theory/validation";
+import { PERMISSION_TABLE, projectListingMeResponseSchema } from "@working-theory/validation";
 
 // `services/project-listings.ts` imports `routeLead` from `lead-routing.js` at
 // module scope, which transitively imports `@working-theory/email` and
@@ -55,7 +56,6 @@ jest.mock("../../../lib/prisma.js", () => ({
 
 import { prisma } from "../../../lib/prisma.js";
 import { authPreHandlerPlugin } from "../../../middleware/auth.js";
-import { PROJECT_LISTING_ROLES } from "../../../services/project-listings.js";
 import { projectListingMeRoute } from "../index.js";
 
 const FRONTEND = "https://app.example.com";
@@ -464,9 +464,8 @@ describe("GET /v1/project-listings/me — the read-time verification posture", (
 });
 
 describe("the existing operator role floor is untouched", () => {
-  it("PROJECT_LISTING_ROLES is still exactly owner + admin", () => {
-    expect([...PROJECT_LISTING_ROLES].sort()).toEqual(["admin", "owner"]);
-    expect(PROJECT_LISTING_ROLES.size).toBe(2);
+  it("the tenant routes read the permission table's inbox-read row, which holds every Membership role", () => {
+    expect([...PERMISSION_TABLE["inbox-read"]].sort()).toEqual(["admin", "member", "owner"]);
   });
 
   it("the /me route never consults the tenant context or the role floor", async () => {

package/templates/apps/api/src/routes/project-listings/index.ts

@@ -26,18 +26,23 @@
  * `/me` (#5295) sits between the two scopes: `authScope` only, no tenant guard.
  * A founder is not a workspace member, so the guard's default-deny answers 403
  * for their own submission — and the fix is this ADDITIVE route, joined on the
- * owner link, rather than a relaxed `PROJECT_LISTING_ROLES`. Its static `/me`
+ * owner link, rather than a relaxed `inbox-read` permission. Its static `/me`
  * segment takes router precedence over the parametric `/:id` below, exactly as
  * the already-shipped static `/public` does.
  *
- * API<->MCP parity: no MCP twin. The anonymous set mirrors the leads routes'
- * own identity-blind posture (an applying founder has no account, and the
- * resume token is a per-draft capability rather than an identity); the
- * tenant-scoped set is an identity-bound dashboard surface, the same #3591
- * exception the sibling `/v1/waitlist-experiments/*` routes record. The
- * directory read (#7521) takes the same no-twin posture as `/public`: agents
- * read a directory from its page's JSON-LD, and a `list_directory` tool is a
- * follow-up.
+ * API<->MCP parity: the anonymous set has no MCP twin — it mirrors the leads
+ * routes' own identity-blind posture (an applying founder has no account, and
+ * the resume token is a per-draft capability rather than an identity). Three
+ * tenant-scoped routes have a twin on the signed-in workspace MCP surface,
+ * `/mcp/workspace` (#3591 D13), each parsing with a
+ * `@working-theory/validation` export (D10):
+ * `GET /v1/project-listings` — `list_inbox_applications`,
+ * `GET /v1/project-listings/:id` — `get_inbox_application`,
+ * `PATCH /v1/project-listings/:id` — `decide_inbox_application`. The copy
+ * edit (`PATCH /:id/copy`) keeps the no-twin posture of the sibling
+ * `/v1/waitlist-experiments/*` routes. The directory read (#7521) takes the
+ * same no-twin posture as `/public`: agents read a directory from its page's
+ * JSON-LD, and a `list_directory` tool is a follow-up.
  */
 import type { FastifyPluginAsync } from "fastify";
 

package/templates/apps/api/src/routes/project-listings/me.ts

@@ -18,9 +18,10 @@
  * `tenantScope`): a founder is not a workspace member, and the tenant guard is
  * default-deny, so a founder reaching the tenant-scoped list route gets a 403
  * for their own submission. That is the problem this route exists to solve, and
- * it is solved by ADDING this route rather than by relaxing
- * `PROJECT_LISTING_ROLES` — the operator floor on
- * `GET|PATCH /v1/project-listings[/:id]` is unchanged and still `owner|admin`.
+ * it is solved by ADDING this route rather than by relaxing the tenant
+ * routes' permissions — `GET|PATCH /v1/project-listings[/:id]` stay on the
+ * permission table's `inbox-read` / `applications-decide` rows (#7636 D2),
+ * which a founder, holding no Membership, never reaches.
  *
  * Identity is `request.userId` ONLY. The route declares no query schema and
  * reads no query or body key — an `email` parameter is never parsed and never

package/templates/apps/api/src/routes/project-listings/patch-copy.ts

@@ -19,9 +19,10 @@
  * untouched by this route — it adds no status, no transition and no decision
  * target.
  *
- * Auth, tenant scoping and the error shapes are `patch.ts`'s: the same
- * owner-or-admin floor, the same `siteId` scoping from `request.tenant`, and
- * the same 401 / 403 / 400 / 404 bodies. A foreign or missing id is `404`, so a
+ * Auth, tenant scoping and the error shapes are `patch.ts`'s, with the
+ * `listings-edit` permission (owner, admin — #7636 D2) as the floor, the
+ * same `siteId` scoping from `request.tenant`, and the same 401 / 403 / 400 /
+ * 404 bodies. A foreign or missing id is `404`, so a
  * cross-tenant probe cannot tell "exists but not yours" from "does not exist".
  *
  * `questions` is replaced wholesale, and its `extras` array carries a
@@ -42,13 +43,14 @@
 import { zProjectListingId } from "@working-theory/ids";
 import {
   buildProjectListingDraftPatchSchema,
+  can,
   projectListingSchema,
 } from "@working-theory/validation";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 
 import { listingConfigFor } from "../../services/listing-config.js";
-import { patchListingCopy, PROJECT_LISTING_ROLES } from "../../services/project-listings.js";
+import { patchListingCopy } from "../../services/project-listings.js";
 
 import { sendValidated } from "./respond.js";
 
@@ -158,7 +160,7 @@ export async function patchProjectListingCopyHandler(
 ): Promise<void> {
   const tenant = request.tenant;
   if (!tenant) return unauthorized(reply);
-  if (!PROJECT_LISTING_ROLES.has(tenant.role)) {
+  if (!can(tenant.role, "listings-edit")) {
     request.log.warn(
       { method: request.method, path: request.url, status: 403 },
       "[project-listings] copy patch denied; insufficient role",

package/templates/apps/api/src/routes/workspaces/__tests__/inbox-wire-schemas.test.ts

@@ -0,0 +1,198 @@
+// oss: false
+/**
+ * @file inbox-wire-schemas.test.ts
+ *
+ * The ten inbox routes parse their request with `@working-theory/validation`
+ * exports (#7672, spec 3591 D10), in a form the API ↔ MCP parity guard binds:
+ * `bindArgs` over each route file's LIVE text yields exactly the D10 export
+ * for each of params, query and body, and `argsFromBindings` resolves every
+ * binding to an argument tree — never `unbound`, never `unrepresentable`.
+ *
+ * And the id patterns those exports restate (validation imports nothing, so
+ * it cannot import `@working-theory/ids`) are the registry's own, so a param
+ * the route accepted before the move is the param it accepts after it.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { idRegexSource, UUID_V7_SOURCE } from "@working-theory/ids";
+import * as validation from "@working-theory/validation";
+import { z } from "zod";
+
+import {
+  argsFromBindings,
+  bindArgs,
+  type ArgBinding,
+} from "../../../../../../tests/parity/api-parity/bind-args";
+
+const REPO_ROOT = join(__dirname, "..", "..", "..", "..", "..", "..");
+const routeText = (file: string) => readFileSync(join(REPO_ROOT, file), "utf8");
+
+const MESSAGES = "apps/api/src/routes/workspaces/messages.ts";
+const SUBMISSIONS = "apps/api/src/routes/workspaces/submissions.ts";
+const LISTINGS = "apps/api/src/routes/project-listings";
+
+const ITEM_PARAMS = "<{ Params: { workspaceId: string; leadId: string } }>(\n";
+
+type Row = {
+  route: string;
+  file: string;
+  anchor: string;
+  bindings: ArgBinding[];
+};
+
+/** Spec 3591 D10's table — the ten inbox rows, export by export. */
+const ROWS: Row[] = [
+  {
+    route: "GET /v1/workspaces/:workspaceId/messages",
+    file: MESSAGES,
+    anchor: '"/v1/workspaces/:workspaceId/messages",',
+    bindings: [
+      { exportName: "inboxWorkspaceParamsSchema", target: "params" },
+      { exportName: "inboxMessageListQuerySchema", target: "query" },
+    ],
+  },
+  {
+    route: "GET /v1/workspaces/:workspaceId/messages/:leadId",
+    file: MESSAGES,
+    anchor: `fastify.get${ITEM_PARAMS}    "/v1/workspaces/:workspaceId/messages/:leadId",`,
+    bindings: [{ exportName: "inboxMessageParamsSchema", target: "params" }],
+  },
+  {
+    route: "PATCH /v1/workspaces/:workspaceId/messages/:leadId",
+    file: MESSAGES,
+    anchor: `fastify.patch${ITEM_PARAMS}    "/v1/workspaces/:workspaceId/messages/:leadId",`,
+    bindings: [
+      { exportName: "inboxMessageParamsSchema", target: "params" },
+      { exportName: "inboxHandledBodySchema", target: "body" },
+    ],
+  },
+  {
+    route: "POST /v1/workspaces/:workspaceId/messages/:leadId/accept",
+    file: MESSAGES,
+    anchor: '"/v1/workspaces/:workspaceId/messages/:leadId/accept",',
+    bindings: [
+      { exportName: "inboxMessageParamsSchema", target: "params" },
+      { exportName: "inboxAcceptBodySchema", target: "body" },
+    ],
+  },
+  {
+    route: "GET /v1/workspaces/:workspaceId/submissions",
+    file: SUBMISSIONS,
+    anchor: '"/v1/workspaces/:workspaceId/submissions",',
+    bindings: [
+      { exportName: "inboxWorkspaceParamsSchema", target: "params" },
+      { exportName: "inboxSubmissionListQuerySchema", target: "query" },
+    ],
+  },
+  {
+    route: "GET /v1/workspaces/:workspaceId/submissions/:leadId",
+    file: SUBMISSIONS,
+    anchor: `fastify.get${ITEM_PARAMS}    "/v1/workspaces/:workspaceId/submissions/:leadId",`,
+    bindings: [{ exportName: "inboxSubmissionParamsSchema", target: "params" }],
+  },
+  {
+    route: "PATCH /v1/workspaces/:workspaceId/submissions/:leadId",
+    file: SUBMISSIONS,
+    anchor: `fastify.patch${ITEM_PARAMS}    "/v1/workspaces/:workspaceId/submissions/:leadId",`,
+    bindings: [
+      { exportName: "inboxSubmissionParamsSchema", target: "params" },
+      { exportName: "inboxHandledBodySchema", target: "body" },
+    ],
+  },
+  {
+    route: "GET /v1/project-listings",
+    file: `${LISTINGS}/list.ts`,
+    anchor: "export async function listProjectListingsHandler(",
+    bindings: [
+      { exportName: "projectListingListQuerySchema", target: "query" },
+    ],
+  },
+  {
+    route: "GET /v1/project-listings/:id",
+    file: `${LISTINGS}/get.ts`,
+    anchor: "export async function getProjectListingHandler(",
+    bindings: [{ exportName: "projectListingParamsSchema", target: "params" }],
+  },
+  {
+    route: "PATCH /v1/project-listings/:id",
+    file: `${LISTINGS}/patch.ts`,
+    anchor: "export async function patchProjectListingHandler(",
+    bindings: [
+      { exportName: "projectListingParamsSchema", target: "params" },
+      { exportName: "projectListingPatchSchema", target: "body" },
+    ],
+  },
+];
+
+describe("the inbox routes parse with @working-theory/validation exports (D10)", () => {
+  it("covers the ten inbox rows", () => {
+    expect(ROWS).toHaveLength(10);
+  });
+
+  it.each(ROWS.map((row) => [row.route, row] as const))(
+    "%s binds exactly its D10 exports",
+    (_route, row) => {
+      const bound = bindArgs(routeText(row.file), row.anchor);
+      expect(bound).toEqual({ bindings: row.bindings });
+    },
+  );
+
+  it.each(ROWS.map((row) => [row.route, row] as const))(
+    "%s resolves to an argument tree",
+    (_route, row) => {
+      const args = argsFromBindings(
+        bindArgs(routeText(row.file), row.anchor),
+        validation,
+        z.toJSONSchema as never,
+      );
+      expect(args).not.toHaveProperty("unbound");
+      expect(args).not.toHaveProperty("unrepresentable");
+    },
+  );
+});
+
+describe("the exported id patterns are the registry's", () => {
+  const pattern = (schema: z.ZodType, key: string): unknown =>
+    (
+      z.toJSONSchema(schema) as {
+        properties: Record<string, { pattern?: string }>;
+      }
+    ).properties[key]?.pattern;
+
+  it.each([
+    [
+      "workspaceId",
+      validation.inboxWorkspaceParamsSchema,
+      idRegexSource("workspace"),
+    ],
+    [
+      "workspaceId",
+      validation.inboxMessageParamsSchema,
+      idRegexSource("workspace"),
+    ],
+    ["leadId", validation.inboxMessageParamsSchema, idRegexSource("lead")],
+    [
+      "workspaceId",
+      validation.inboxSubmissionParamsSchema,
+      idRegexSource("workspace"),
+    ],
+    ["leadId", validation.inboxSubmissionParamsSchema, idRegexSource("lead")],
+    [
+      "id",
+      validation.projectListingParamsSchema,
+      idRegexSource("projectListing"),
+    ],
+    // `routes/magnets/index.ts`'s magnet id — `flow_` is not a registry entity.
+    [
+      "magnetId",
+      validation.inboxSubmissionListQuerySchema,
+      `^flow_${UUID_V7_SOURCE}$`,
+    ],
+  ] as const)(
+    "%s pattern equals the @working-theory/ids source",
+    (key, schema, expected) => {
+      expect(pattern(schema, key)).toBe(expected);
+    },
+  );
+});

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

@@ -33,6 +33,7 @@ import { defaultTenantPreHandlerPlugin } from "./middleware/default-tenant.js";
 import {
   rateLimitMiddleware,
   buildTrustedKeyDigests,
+  DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
   resolveRateLimitIdentity,
 } from "./middleware/rate-limit.js";
@@ -216,6 +217,10 @@ const WORKSPACES_MESSAGES = "./routes/workspaces/messages.js";
 // WORKSPACES_MESSAGES in the same workspace/multi-tenant scope.
 const WORKSPACES_SUBMISSIONS = "./routes/workspaces/submissions.js";
 const WORKSPACES_SUBSCRIBERS = "./routes/workspaces/subscribers.js";
+// #3591 PR-B — the agent seat's management routes and an agent's own
+// context, siblings of WORKSPACES_MEMBERS in the same workspace/multi-tenant
+// scope.
+const WORKSPACES_AGENTS = "./routes/workspaces/agents.js";
 // #6183 S9b — a SEPARATE specifier from WORKSPACES_CONFIG: this route is
 // registered under isModuleEnabled("scheduling") alone, never the
 // workspace/multi-tenant scope config.js shares with general.js/members.js
@@ -287,6 +292,11 @@ const SLICE_PLUGINS = {
     specifier: WORKSPACES_SUBSCRIBERS,
     load: () => import(WORKSPACES_SUBSCRIBERS),
   },
+  // #3591 PR-B — the agent seat, the SAME scope.
+  workspaceAgentRoutes: {
+    specifier: WORKSPACES_AGENTS,
+    load: () => import(WORKSPACES_AGENTS),
+  },
   // #6183 S9b — registered in the scheduling scope, not the
   // workspace/multi-tenant scope its siblings above share.
   workspaceMeetingsRoutes: {
@@ -1014,6 +1024,12 @@ export async function build() {
         await tenantScope.register(
           await sliceRoutePlugin("workspaceSubscriberRoutes"),
         );
+        // The agent seat (#3591 PR-B) — the SAME scope and guard: owners and
+        // admins list, add, re-key and switch off agents (`agents-manage`),
+        // and an agent reads its own context at GET /v1/agent/context.
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceAgentRoutes"),
+        );
         // The asset store's MANAGE routes — list, PATCH, DELETE (#6093 D16).
         // Registered HERE, in the plain tenant scope, and NOT inside the
         // upload's own nested strict-rate-limit scope below: a JSON
@@ -1380,10 +1396,21 @@ 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.
+  //
+  // `scope: "schedule"` with `trustedKeyDigests` (#7633, the relay's security
+  // review): a site's same-origin relay sends every visitor's availability
+  // and booking call from its own server, so with the forwarding key each
+  // visitor is counted separately, and the key as a whole is capped at
+  // DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE. The scope's buckets are its own,
+  // and AILK_RATE_LIMIT_SCHEDULE_PER_MINUTE / ..._PER_KEY_PER_MINUTE override
+  // the code values, as the leads scope's do.
   if (isModuleEnabled("scheduling")) {
     await server.register(async (scheduleScope) => {
       scheduleScope.register(rateLimitMiddleware, {
         perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+        scope: "schedule",
+        trustedKeyDigests: visitorForwardKeyDigests,
+        perKeyPerMinute: DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE,
       });
       await scheduleScope.register(
         await sliceRoutePlugin("listAvailabilityRoute"),