create-ailk 0.14.0 → 0.15.0

package/templates/apps/api/src/services/default-tenant.ts

@@ -43,7 +43,12 @@ import {
   resolveDefaultWorkspaceRow as resolveDefaultWorkspaceRowShared,
 } from "@working-theory/database/tenancy";
 import type { Id } from "@working-theory/ids";
-import { lowerRole } from "@working-theory/validation";
+import {
+  AGENT_GRANTABLE_PERMISSIONS,
+  can,
+  lowerRole,
+  type AgentGrantablePermission,
+} from "@working-theory/validation";
 
 import type { AgentGrant } from "../lib/agent-store.js";
 import { prisma } from "../lib/prisma.js";
@@ -62,6 +67,13 @@ export interface TenantContext {
   organizationId: Id<"organization">;
   workspaceId: Id<"workspace">;
   role: MembershipRole;
+  /**
+   * Set ONLY on an agent's tenant (#7864 D3), and only when at least one of
+   * its grants survives the clamp: the grantable permissions it holds on top
+   * of its role. A person's tenant never carries it. Read through
+   * `@working-theory/validation`'s `allows`.
+   */
+  grants?: readonly AgentGrantablePermission[];
 }
 
 export type TenantErrorKind = "forbidden" | "not_found" | "conflict";
@@ -206,14 +218,39 @@ export async function resolveDefaultTenantForOperator(
   return (await isPinnedOperator(userId)) ? resolveDefaultTenant(userId) : null;
 }
 
+/**
+ * An agent's tenant (#3591 D5, #7864): its person's tenant with the role
+ * clamped to the agent's ceiling and, when any survive, the agent's grants
+ * that its person's own role holds. `grants` is omitted when none survive,
+ * so an agent with no effective grant is the same shape as before.
+ *
+ * The one clamp both tenant guards apply — `resolveAgentTenant` (multi-tenant)
+ * and `resolveDefaultTenantForAgent` (base build) — so the two builds cannot
+ * hold an agent to different rules.
+ */
+export function agentTenant(
+  personTenant: TenantContext,
+  agent: AgentGrant,
+): TenantContext {
+  const role = lowerRole(personTenant.role, agent.permissionLevel);
+  // D1 order, no duplicates, only the five, and only what the person holds.
+  const grants = AGENT_GRANTABLE_PERMISSIONS.filter(
+    (p) => agent.grants.includes(p) && can(personTenant.role, p),
+  );
+  return grants.length > 0
+    ? { ...personTenant, role, grants }
+    : { ...personTenant, role };
+}
+
 /**
  * The base-build grant for an AGENT (#3591 spec D5, D7). The same steps as
  * `resolveDefaultTenantForOperator` — the pin check, then the default
  * resolution and its one Membership read — so an agent and its person's
  * session drive the same reads. On top of them: the resolved workspace must
  * be the one the agent is bound to, and the Membership the read found must be
- * the one the agent was created under. The role is then clamped to the
- * agent's ceiling (`lowerRole`), so the operator's agent acts as a member.
+ * the one the agent was created under. The tenant is then clamped
+ * (`agentTenant`), so the operator's agent acts as a member plus the grants
+ * the operator holds.
  *
  * The membership id is compared here rather than carried on `TenantContext`,
  * which stays one shape for every caller. On a base build only the pinned,
@@ -234,10 +271,7 @@ export async function resolveDefaultTenantForAgent(
   ) {
     return null;
   }
-  return {
-    ...granted.tenant,
-    role: lowerRole(granted.tenant.role, agent.permissionLevel),
-  };
+  return agentTenant(granted.tenant, agent);
 }
 
 /**

package/templates/apps/api/src/services/lead-routing.ts

@@ -27,9 +27,23 @@
  * under it already contradicted it.) The one READ in this file — the
  * duplicate-subscriber lookup on the P2002 arm — is scoped by it too
  * (#6257).
+ *
+ * IDEMPOTENCY KEY (#7869, roadmap D5). A `submit` may carry a caller's
+ * `Idempotency-Key` (`routes/leads/index.ts` reads and validates the header;
+ * it travels beside the input as `routeLead`'s third argument, never inside
+ * the `.strict()` input). On `inbox` delivery only, a key already stored on a
+ * `Lead` of THIS workspace short-circuits the write: the same `email`,
+ * `source` and `payload` is a replay (the first lead's id, nothing written,
+ * no capture record, no notification); anything else is an
+ * `idempotency_conflict` (nothing written). The two reads — the lookup
+ * before the write and the re-read after a `P2002` race — are both keyed on
+ * `(workspaceId, idempotencyKey)`, so a key can never reach another tenant's
+ * row. `email`, `local` and `none` deliveries ignore the key: there is no
+ * row to dedupe against. The key itself is never logged.
  */
 
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 
 import type { Prisma } from "@working-theory/database";
 import { sendLeadNotification } from "@working-theory/email";
@@ -79,9 +93,21 @@ export type SourceMeta = {
 /** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
 export type Persisted = "db" | "file" | "email";
 
+/** Per-call options carried beside the input (#7869 D2). */
+export type RouteLeadOptions = {
+  /** The caller's validated `Idempotency-Key`; honoured for `submit` only. */
+  idempotencyKey?: string;
+};
+
 export type RouteLeadResult =
   | {
       ok: true;
+      /**
+       * The answer to a repeat of an already-stored idempotency key (#7869
+       * D4): nothing was written. Never on the wire — the route builds its
+       * 201 body from `id`, `persisted` and `email` only.
+       */
+      replayed?: true;
       id: string;
       persisted: Persisted;
       email:
@@ -96,7 +122,8 @@ export type RouteLeadResult =
           | "invalid_input"
           | "persist_failed"
           | "config_missing"
-          | "delivery_failed";
+          | "delivery_failed"
+          | "idempotency_conflict";
         message: string;
       };
     };
@@ -116,6 +143,64 @@ function validateInput(
   return { ok: true };
 }
 
+// ─── Idempotency key (#7869) ─────────────────────────────────────────────────
+
+type SubmitInput = Extract<RouteLeadInput, { kind: "submit" }>;
+type KeyedRow = { id: string; email: string; source: string; payload: unknown };
+/** What a stored key means for this request (#7869 D4). */
+type KeyedOutcome = { kind: "replay"; id: string } | { kind: "conflict" };
+
+/**
+ * The one read of `Lead.idempotencyKey` (#7869 D3, reused by D5's re-read).
+ * The compound unique carries `workspaceId`, so the lookup can only ever
+ * reach this workspace's rows.
+ */
+async function findLeadByKey(
+  workspaceId: string,
+  idempotencyKey: string,
+): Promise<KeyedRow | null> {
+  return (await prisma.lead.findUnique({
+    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey } },
+    select: { id: true, email: true, source: true, payload: true },
+  })) as KeyedRow | null;
+}
+
+/**
+ * A stored row is a replay only when it carries this request's exact `email`
+ * and `source` and a deep-equal `payload` (key order ignored, SEC-7869-3);
+ * any other row is a conflict (#7869 D4).
+ */
+function classifyKeyedRow(row: KeyedRow, input: SubmitInput): KeyedOutcome {
+  return row.email === input.email &&
+    row.source === input.source &&
+    isDeepStrictEqual(row.payload, input.payload)
+    ? { kind: "replay", id: row.id }
+    : { kind: "conflict" };
+}
+
+function keyedResult(outcome: KeyedOutcome): RouteLeadResult {
+  if (outcome.kind === "conflict") {
+    return {
+      ok: false,
+      error: { kind: "idempotency_conflict", message: "idempotency key reused" },
+    };
+  }
+  return {
+    ok: true,
+    replayed: true,
+    id: outcome.id,
+    persisted: "db",
+    email: { skipped: true, reason: "idempotent_replay" },
+  };
+}
+
+/** The structural `P2002` test `recommender-capture.ts` already uses. */
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    typeof err === "object" && err !== null && (err as { code?: unknown }).code === "P2002"
+  );
+}
+
 // ─── DB persist ───────────────────────────────────────────────────────────────
 
 type DbRow = { id: string };
@@ -127,36 +212,55 @@ type PersistResult =
       skipEmail: boolean;
       skipReason?: string;
     }
+  // #7869 D5 — a keyed create lost a race to a row it now answers with.
+  | { ok: "keyed"; outcome: KeyedOutcome }
   | { ok: false; error: string };
 
-async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
+async function persistToDb(
+  input: RouteLeadInput,
+  idempotencyKey?: string,
+): Promise<PersistResult> {
   if (input.kind === "submit") {
-    const row = (await prisma.lead.create({
-      data: {
-        siteId: input.siteId,
-        // #6203/#6254 — the isolation key, equal to `siteId` by
-        // construction. `input.siteId` is the RESOLVED workspace id at
-        // EVERY `routeLead(kind: "submit")` caller now — the primary route
-        // (`routes/leads/index.ts`, never reads it from the body — see that
-        // file's header) and the three service-layer callers
-        // (`flow-engine.ts`'s `completeSubmission`,
-        // `recommender-capture.ts`'s `captureRecommenderChoice`,
-        // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
-        // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
-        // is NOT NULL as of
-        // database/migrations/20260922120000_tenancy_fence, so this can no
-        // longer stamp `null` for an unresolved alias the way it once did
-        // (spec D2's old rule) — a caller that somehow still passed one
-        // would instead hit the pre-existing `<table>_workspace_id_format`
-        // CHECK loudly, via the AC-11 re-raise below, rather than landing a
-        // silently-unfenced row.
-        workspaceId: input.siteId,
-        source: input.source,
-        email: input.email,
-        payload: input.payload as Prisma.InputJsonValue,
-      },
-      select: { id: true },
-    })) as DbRow;
+    let row: DbRow;
+    try {
+      row = (await prisma.lead.create({
+        data: {
+          siteId: input.siteId,
+          // #6203/#6254 — the isolation key, equal to `siteId` by
+          // construction. `input.siteId` is the RESOLVED workspace id at
+          // EVERY `routeLead(kind: "submit")` caller now — the primary route
+          // (`routes/leads/index.ts`, never reads it from the body — see that
+          // file's header) and the three service-layer callers
+          // (`flow-engine.ts`'s `completeSubmission`,
+          // `recommender-capture.ts`'s `captureRecommenderChoice`,
+          // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
+          // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
+          // is NOT NULL as of
+          // database/migrations/20260922120000_tenancy_fence, so this can no
+          // longer stamp `null` for an unresolved alias the way it once did
+          // (spec D2's old rule) — a caller that somehow still passed one
+          // would instead hit the pre-existing `<table>_workspace_id_format`
+          // CHECK loudly, via the AC-11 re-raise below, rather than landing a
+          // silently-unfenced row.
+          workspaceId: input.siteId,
+          source: input.source,
+          email: input.email,
+          payload: input.payload as Prisma.InputJsonValue,
+          ...(idempotencyKey !== undefined && { idempotencyKey }),
+        },
+        select: { id: true },
+      })) as DbRow;
+    } catch (err) {
+      // #7869 D5 — two keyed requests both missed the lookup and both
+      // created; the unique index refused the second. Answer with the
+      // winner. Anything else — no key, another error, a winner that cannot
+      // be read back — is rethrown untouched, so `routeLead`'s existing
+      // constraint and outage handling decide it exactly as before.
+      if (idempotencyKey === undefined || !isUniqueViolation(err)) throw err;
+      const winner = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
+      if (!winner) throw err;
+      return { ok: "keyed", outcome: classifyKeyedRow(winner, input) };
+    }
     return { ok: true, id: row.id, source: "db", skipEmail: false };
   }
 
@@ -426,6 +530,7 @@ function captureRecordFor(input: RouteLeadInput, id: string, sourceMeta: SourceM
 export async function routeLead(
   input: RouteLeadInput,
   sourceMeta: SourceMeta,
+  options: RouteLeadOptions = {},
 ): Promise<RouteLeadResult> {
   // 1. Validate
   const validation = validateInput(input);
@@ -452,6 +557,17 @@ export async function routeLead(
     };
   }
 
+  // 2a. Idempotency key (#7869 D3/D7) — submit, a key, and a database to
+  // dedupe against. A stored key answers before any enrichment or write. A
+  // failed read is not an answer: the create below meets the same database
+  // and takes the existing outage path.
+  const idempotencyKey =
+    input.kind === "submit" && delivery === "inbox" ? options.idempotencyKey : undefined;
+  if (idempotencyKey !== undefined && input.kind === "submit") {
+    const stored = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
+    if (stored) return keyedResult(classifyKeyedRow(stored, input));
+  }
+
   // 3. Enrich (reserved for Phase 3 — today returns lead unchanged).
   // Cast via unknown: enrichLead accepts CreateLead (B3 shim type) but the
   // pass-through contract means RouteLeadInput is safe here until Phase 3 wires
@@ -484,7 +600,10 @@ export async function routeLead(
   let skipReason: string | undefined;
 
   try {
-    const dbResult = await persistToDb(input);
+    const dbResult = await persistToDb(input, idempotencyKey);
+    // #7869 D5 — a lost race answers like the lookup above: no capture
+    // record, no notification.
+    if (dbResult.ok === "keyed") return keyedResult(dbResult.outcome);
     if (!dbResult.ok) {
       // persistToDb returned ok:false — defensive guard; current impl doesn't reach this
       return {

package/templates/apps/api/src/services/public-site-resolver.ts

@@ -60,6 +60,15 @@
  * NO SECRET IS LOGGED. A refusal reaches `request.log.warn` as `{ reason }`
  * (plus `spokeId` for a matched row) — never the key, its digest or its
  * prefix — and never reaches the wire.
+ *
+ * THE FLOWS ROUTES' WORKSPACE (#7844 D1). `resolveCallerWorkspace` below is
+ * the one function the five `/v1/flows` routes resolve their workspace with:
+ * a spoke resolves to its own workspace (`viaSpoke: true`), a keyless call to
+ * the `AILK_SITE_ID` alias exactly as before, and anything else to
+ * `unresolved` with one of two reasons, `spoke-refused` or `alias-unresolved`.
+ * The reasons are for `request.log` only; the routes answer both the same
+ * way. It lives here rather than under `routes/flows/` because the two flows
+ * route files sit in different module slices, and this file is base tree.
  */
 import {
   resolvedAdapterKind,
@@ -232,6 +241,45 @@ export async function resolveCallerSite(
   return { kind: "spoke", spokeId: row.id, workspaceId: row.workspaceId };
 }
 
+/**
+ * The workspace a `/v1/flows` request serves (#7844 D1). `reason` is for
+ * `request.log` only; the routes answer both reasons the same way.
+ */
+export type CallerWorkspace =
+  | { kind: "resolved"; workspaceId: string; viaSpoke: boolean }
+  | { kind: "unresolved"; reason: "spoke-refused" | "alias-unresolved" };
+
+/**
+ * Resolve the workspace a `/v1/flows` request serves. A spoke resolves to its
+ * own workspace; a keyless call to the `AILK_SITE_ID` alias, exactly as the
+ * flows routes did before #7844; a refused caller to nothing. There is no
+ * fallback: a spoke never reaches the alias workspace (D5).
+ *
+ * Calls `resolveCallerSite` with no options, so a failed hub-status read on a
+ * keyless call rejects (#7844 C1).
+ */
+export async function resolveCallerWorkspace(
+  request: FastifyRequest,
+): Promise<CallerWorkspace> {
+  const caller = await resolveCallerSite(request);
+  if (caller.kind === "refused") {
+    return { kind: "unresolved", reason: "spoke-refused" };
+  }
+  if (caller.kind === "spoke") {
+    return {
+      kind: "resolved",
+      workspaceId: caller.workspaceId,
+      viaSpoke: true,
+    };
+  }
+  // Deferred, like every database import in this file.
+  const { resolveSiteWorkspaceId } = await import("../lib/site.js");
+  const workspaceId = await resolveSiteWorkspaceId();
+  return workspaceId === null
+    ? { kind: "unresolved", reason: "alias-unresolved" }
+    : { kind: "resolved", workspaceId, viaSpoke: false };
+}
+
 /**
  * The three answers a public read can get. `reason` exists for `request.log`
  * only: the route decides its response from `kind` alone, so no resolution

package/templates/apps/mcp/__tests__/index.test.ts

@@ -16,12 +16,12 @@ import * as ts from "typescript";
 describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
   const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
 
-  it("awaits initMcpPublicWorkspace()", () => {
-    expect(src).toMatch(/await initMcpPublicWorkspace\(\)/);
+  it("awaits initPublicWorkspace()", () => {
+    expect(src).toMatch(/await initPublicWorkspace\(\)/);
   });
 
-  it("awaits initMcpPublicWorkspace() before either transport branch", () => {
-    const initIdx = src.indexOf("await initMcpPublicWorkspace()");
+  it("awaits initPublicWorkspace() before either transport branch", () => {
+    const initIdx = src.indexOf("await initPublicWorkspace()");
     const transportBranchIdx = src.indexOf('if (transport === "http")');
 
     expect(initIdx).toBeGreaterThan(-1);
@@ -31,7 +31,7 @@ describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
 
   it("wraps the await in try/catch — a rejection (DB down at boot) must not crash the whole server (code review, #5876)", () => {
     const tryIdx = src.indexOf("try {");
-    const initIdx = src.indexOf("await initMcpPublicWorkspace()");
+    const initIdx = src.indexOf("await initPublicWorkspace()");
     const catchIdx = src.indexOf("} catch");
 
     expect(tryIdx).toBeGreaterThan(-1);

package/templates/apps/mcp/src/index.ts

@@ -25,8 +25,10 @@ import {
   initMcpCommerceClaim,
   startMcpClaimRefresh,
 } from "./lib/commerce-claim.js";
-import { registerLicenseKeyStore } from "./lib/license-key-store.js";
-import { initMcpPublicWorkspace } from "./lib/public-workspace.js";
+import {
+  initPublicWorkspace,
+  registerLicenseKeyStore,
+} from "./lib/topology.generated.js";
 
 // Resolves the MCP server's own workspace ONCE, before either transport
 // branch below — a no-op unless CONTENT_ADAPTER=database (#5876 spec D4/D6).
@@ -42,10 +44,10 @@ import { initMcpPublicWorkspace } from "./lib/public-workspace.js";
 // (D5) — so content tools serve their empty/not-found shape rather than the
 // whole server going dark over one adapter's connectivity.
 try {
-  await initMcpPublicWorkspace();
+  await initPublicWorkspace();
 } catch (err) {
   console.error(
-    "[mcp] initMcpPublicWorkspace() failed — content tools will serve their " +
+    "[mcp] initPublicWorkspace() failed — content tools will serve their " +
       "fail-closed empty shape under CONTENT_ADAPTER=database until this " +
       "resolves; every other tool is unaffected:",
     err,

package/templates/apps/mcp/src/lib/content-adapter.ts

@@ -43,7 +43,7 @@ import {
   emptyContentAdapter,
   readOnlyContentAdapter,
 } from "./empty-content-adapter.js";
-import { mcpPublicWorkspace } from "./public-workspace.js";
+import { publicWorkspace } from "./topology.generated.js";
 
 export interface McpContentAdapterOptions {
   /** Filesystem content root. Defaults to `<cwd>/content` — the tools' prior default. */
@@ -67,7 +67,7 @@ export function getMcpContentAdapter(
     return resolveContentAdapter({ contentRoot, defaultLocale });
   }
 
-  const workspace = mcpPublicWorkspace();
+  const workspace = publicWorkspace();
   if (workspace.kind !== "resolved") {
     return emptyContentAdapter();
   }

package/templates/apps/mcp/src/lib/topology.generated.ts

@@ -0,0 +1,24 @@
+// topology.generated.ts — how this MCP server resolves its workspace store.
+//
+// GENERATED by create-ailk for this site's topology (#7426). Do not edit:
+// every scaffold rewrites it. A hub resolves its workspace through the
+// database; a spoke (`--topology spoke`) has none, so its content tools
+// read the spoke's own MDX and its writes go to the hub at AILK_API_URL.
+import {
+  initMcpPublicWorkspace,
+  mcpPublicWorkspace,
+  type McpWorkspaceResolution,
+} from "./public-workspace.js";
+
+export { registerLicenseKeyStore } from "./license-key-store.js";
+export type { McpWorkspaceResolution };
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+
+export async function initPublicWorkspace(): Promise<void> {
+  await initMcpPublicWorkspace();
+}
+
+export function publicWorkspace(): McpWorkspaceResolution {
+  return mcpPublicWorkspace();
+}

package/templates/apps/web/CLAUDE.md

@@ -139,6 +139,7 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - **Only the list.** `RELAY_ROUTES` is the fixed set of (method, path) pairs: `POST /v1/leads/{submit,subscribe,callback}`, `GET /v1/schedule/availability`, `POST /v1/schedule/book`, `POST /v1/commerce/invoices`. Anything else is a 404 with no hub call. Adding a route is a reviewed change to that list, its test and `.env.example`.
 - **No cross-site POST.** A `Sec-Fetch-Site` other than `same-origin`, or an `Origin` not on this site's own host, is refused 403 before the hub is called.
 - **Headers are an allow-list.** The visitor's `x-forwarded-for` (else `x-real-ip`) and `user-agent` pass through so per-visitor rate limits still count each visitor; no `authorization`, client-sent `x-ailk-*` or `host` is forwarded, and a `cookie` goes only on `POST /v1/commerce/invoices`, the one session route.
+- **The relay has its own per-visitor budget (#7707).** Each visitor gets 8 calls per 10 minutes across the five visitor routes, and the session route (`POST /v1/commerce/invoices`) gets its own, wider budget of 30 per 10 minutes; the call that exceeds either gets `429 rate_limited` before any hub call. The budget is held in this instance's own process (no shared store, no env variable) and holds only where the site's edge overwrites `x-forwarded-for` and `x-real-ip` — Vercel does; a bare self-hosted Next server does not.
 - `/v1` is exempt from next-intl's locale rewrite in `middleware.ts`, as `/api` is.
 
 ## AEO & performance

package/templates/apps/web/app/[locale]/[slug]/[detail]/__tests__/page.test.tsx

@@ -51,6 +51,9 @@ jest.mock("../../../../../lib/paid-sections.generated", () => {
 });
 
 jest.mock("@working-theory/ui", () => ({
+  // #7789: renderPage's fallback page head renders inside the section Container.
+  Container: ({ children }: { children?: React.ReactNode }) =>
+    React.createElement("div", null, children),
   // #7521 — the rest of the real barrel, so the listing extension finds
   // `localeHref`; the two below still override.
   ...jest.requireActual("@working-theory/ui"),

package/templates/apps/web/app/[locale]/[slug]/__tests__/page.test.tsx

@@ -24,6 +24,9 @@ jest.mock("next/navigation", () => ({
 }));
 
 jest.mock("@working-theory/ui", () => ({
+  // #7789: renderPage's fallback page head renders inside the section Container.
+  Container: ({ children }: { children?: React.ReactNode }) =>
+    React.createElement("div", null, children),
   Heading: ({
     children,
     level,