create-ailk 0.13.0 → 0.15.0

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

@@ -747,3 +747,202 @@ describe("#6730 — routeLead delivery modes", () => {
     });
   });
 });
+
+// ── #7869 — the Idempotency-Key on submit (spec D3–D5, D10 cases 9–14) ──────
+//
+// Cases 9–13 run on `inbox` delivery (DATABASE_URL set), where the key is
+// honoured; case 14 drops DATABASE_URL to prove a non-inbox delivery ignores
+// it. A keyed create that loses the race throws P2002 and is answered from a
+// re-read of the winner.
+describe("#7869 — routeLead with an idempotency key", () => {
+  const KEY = "fixture-retry-0000-0000-0001";
+  const WINNER_ID = "lead_00000000-0000-7000-8000-00000000f001";
+  const ENV_KEYS = [
+    "DATABASE_URL",
+    "NODE_ENV",
+    "AILK_INBOX_FALLBACK_DIR",
+    "LEAD_CAPTURE_FILE",
+    "AILK_LEAD_NOTIFICATION_TO",
+    "AILK_LEAD_NOTIFICATION_FROM",
+  ] as const;
+  let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+  let tmpDir: string;
+
+  const p2002 = () =>
+    Object.assign(
+      new Error(
+        "Unique constraint failed on the fields: (`workspace_id`,`idempotency_key`)",
+      ),
+      { code: "P2002" },
+    );
+  const keyWhere = (workspaceId: string) => ({
+    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey: KEY } },
+    select: { id: true, email: true, source: true, payload: true },
+  });
+  const createData = () =>
+    jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data as Record<
+      string,
+      unknown
+    >;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    saved = {};
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    for (const k of ENV_KEYS) delete process.env[k];
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "ailk-idem-test-"));
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+    process.env.DATABASE_URL = "postgres://stub";
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "lead_db_new" });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+    mockSendLeadNotification.mockResolvedValue({
+      ok: true,
+      messageId: "msg-1",
+    });
+  });
+
+  afterEach(async () => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("case 9 — a P2002 race whose winner matches answers the winner's id: no fallback, no persist_failed, no notification, no capture record", async () => {
+    // Positive control first: a keyed create with no race writes exactly one
+    // line to the capture file, so the negative assertion below is load-bearing.
+    const controlFile = path.join(tmpDir, "control.jsonl");
+    process.env.LEAD_CAPTURE_FILE = controlFile;
+    const control = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+    expect(control).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+    expect(
+      (await fs.readFile(controlFile, "utf8")).trim().split("\n"),
+    ).toHaveLength(1);
+    expect(createData()).toMatchObject({ idempotencyKey: KEY });
+
+    jest.clearAllMocks();
+    const raceFile = path.join(tmpDir, "race.jsonl");
+    process.env.LEAD_CAPTURE_FILE = raceFile;
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null) // the pre-write lookup misses
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: leadInput.email,
+        source: leadInput.source,
+        payload: { ...leadInput.payload },
+      });
+    const before = await fs.readdir(tmpDir);
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      replayed: true,
+      id: WINNER_ID,
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expect(prisma.lead.findUnique).toHaveBeenNthCalledWith(
+      2,
+      keyWhere(leadInput.siteId),
+    );
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+    await expect(fs.access(raceFile)).rejects.toThrow();
+    expect(await fs.readdir(tmpDir)).toEqual(before); // no file fallback
+  });
+
+  it("case 10 — a P2002 race whose winner carries a different email is idempotency_conflict", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: "someone-else@example.com",
+        source: leadInput.source,
+        payload: leadInput.payload,
+      });
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        kind: "idempotency_conflict",
+        message: "idempotency key reused",
+      },
+    });
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+  });
+
+  it("case 11 — a P2002 race whose re-read finds nothing takes the existing persist_failed path", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    })) as Extract<RouteLeadResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).toHaveBeenCalledTimes(2);
+  });
+
+  it("case 12 — a P2002 with no key passed is persist_failed, as today, with no key lookup", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+  });
+
+  it("case 13 — a lookup that throws still reaches the create (the existing path)", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+  });
+
+  it("case 14 — a non-inbox delivery ignores the key: no lookup, no key on the create, the existing file path", async () => {
+    delete process.env.DATABASE_URL; // `local` delivery outside production
+    (prisma.lead.create as jest.Mock).mockRejectedValue(
+      new Error("connection refused"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+    expect(result).toMatchObject({ ok: true, persisted: "file" });
+  });
+});

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/package.json

@@ -18,7 +18,7 @@
   "dependencies": {
     "@fastify/cors": "^11.2.0",
     "@fastify/rate-limit": "^10.3.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.31.0",
     "@prisma/adapter-pg": "^7.8.0",
     "@working-theory/aeo": "workspace:*",
     "@working-theory/api-client": "workspace:*",

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();
   }