create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/bin/stripe-connections-rekey.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; rekeyStripeConnections and
+   formatRekeyReport are unit-tested in
+   services/offerings/__tests__/connection.test.ts. */
+/**
+ * Re-encrypt every Organization Stripe connection under the current
+ * STRIPE_CONNECTION_KEY (#8907 D13, contract C10).
+ *
+ * Dev: `pnpm --filter @working-theory/api stripe-connections:rekey` (tsx,
+ * this file). Production: `node dist/bin/stripe-connections-rekey.js`.
+ *
+ * The rotation: set STRIPE_CONNECTION_KEY_PREVIOUS to the old key and the new
+ * key as STRIPE_CONNECTION_KEY, redeploy, run this, and unset _PREVIOUS once
+ * it prints `remaining=0`. A row counted `unreadable` decrypts under neither
+ * key; its owner reconnects or disconnects. A second run rekeys nothing.
+ *
+ * Run it with the production environment — `VERCEL_ENV=production`, or
+ * `NODE_ENV=production` off Vercel — the same predicate the API goes live on;
+ * anywhere else it prints `not_production`, reads nothing and exits 1.
+ *
+ * Prints one line of counts only — never a key, a value or a row id — and
+ * exits 1 when the key is not configured, off production, or the walk fails.
+ */
+import {
+  formatRekeyReport,
+  rekeyStripeConnections,
+} from "../services/offerings/connection.js";
+
+async function main(): Promise<void> {
+  const result = await rekeyStripeConnections();
+  if (!result.ok) {
+    console.error(formatRekeyReport(result));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(formatRekeyReport(result));
+}
+
+main().catch((err: unknown) => {
+  // The class name only: a store error's message is fixed, but nothing else
+  // a failure carries is printed.
+  const name = err instanceof Error ? err.name : "unknown";
+  console.error(`[stripe-connections-rekey] failed: ${name}`);
+  process.exitCode = 1;
+});

package/templates/apps/api/src/config/__tests__/stripe-connection-key.test.ts

@@ -0,0 +1,185 @@
+/**
+ * @file stripe-connection-key.test.ts
+ * @description STRIPE_CONNECTION_KEY and STRIPE_CONNECTION_KEY_PREVIOUS — the
+ * keys an Organization's Stripe connection is encrypted under (#8907 D3,
+ * AC-9; contract C3, C10).
+ *
+ * `resolveStripeConnectionKeys` reads both with the scheduling key's shape
+ * rule (canonical standard base64 of exactly 32 bytes), refuses a previous
+ * key with no current one or equal to it, and refuses either when it is the
+ * scheduling key — so one key never guards calendars and money. A refused
+ * key stops the API at startup; a refusal names the variable and the reason
+ * kind, never any part of the value. Unset is a supported state.
+ */
+
+// Mock dotenv so a developer's local .env never leaks into the config module.
+jest.mock("dotenv", () => ({
+  config: jest.fn(),
+}));
+
+const mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveStripeConnectionKeys } from "../index";
+
+const A = randomBytes(32);
+const B = randomBytes(32);
+const S = randomBytes(32);
+const b64 = (bytes: Buffer) => bytes.toString("base64");
+
+/** 32 bytes whose base64 differs from its base64url, so the url form is refused. */
+function urlOnlyKey(): string {
+  let bytes = randomBytes(32);
+  while (!/[+/]/.test(bytes.toString("base64"))) bytes = randomBytes(32);
+  return bytes.toString("base64url");
+}
+
+describe("resolveStripeConnectionKeys (#8907 D3)", () => {
+  it("answers both buffers for two distinct canonical 32-byte keys", () => {
+    const result = resolveStripeConnectionKeys({ current: b64(A), previous: b64(B), scheduling: S });
+    expect(result.kind).toBe("ok");
+    if (result.kind !== "ok") throw new Error("expected ok");
+    expect(result.current?.equals(A)).toBe(true);
+    expect(result.previous?.equals(B)).toBe(true);
+  });
+
+  it("answers ok with nothing when both are unset or empty", () => {
+    expect(resolveStripeConnectionKeys({ current: undefined, previous: "", scheduling: S })).toEqual({
+      kind: "ok",
+    });
+  });
+
+  it("answers the current key alone with no previous", () => {
+    const result = resolveStripeConnectionKeys({ current: b64(A), previous: undefined, scheduling: undefined });
+    expect(result).toEqual({ kind: "ok", current: A });
+  });
+
+  const urlKey = urlOnlyKey();
+  const shortKey = b64(randomBytes(16));
+  it.each([
+    ["a base64url current key", { current: urlKey }, "STRIPE_CONNECTION_KEY", "not-canonical-base64", urlKey],
+    ["a 16-byte current key", { current: shortKey }, "STRIPE_CONNECTION_KEY", "length", shortKey],
+    [
+      "a 16-byte previous key",
+      { current: b64(A), previous: shortKey },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "length",
+      shortKey,
+    ],
+    [
+      "a previous key with no current",
+      { previous: b64(B) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "previous_without_current",
+      b64(B),
+    ],
+    [
+      "equal current and previous",
+      { current: b64(A), previous: b64(A) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "previous_equals_current",
+      b64(A),
+    ],
+    [
+      "a current key equal to the scheduling key",
+      { current: b64(S) },
+      "STRIPE_CONNECTION_KEY",
+      "shared_with_scheduling",
+      b64(S),
+    ],
+    [
+      "a previous key equal to the scheduling key",
+      { current: b64(A), previous: b64(S) },
+      "STRIPE_CONNECTION_KEY_PREVIOUS",
+      "shared_with_scheduling",
+      b64(S),
+    ],
+  ])("refuses %s, naming the variable and the reason only", (_label, raw, variable, reason, value) => {
+    const result = resolveStripeConnectionKeys({
+      current: (raw as { current?: string }).current,
+      previous: (raw as { previous?: string }).previous,
+      scheduling: S,
+    });
+    expect(result).toEqual({ kind: "refused", variable, reason });
+    expect(JSON.stringify(result)).not.toContain(value.slice(0, 8));
+  });
+});
+
+describe("config.STRIPE_CONNECTION_KEY at startup (#8907 D3)", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+    delete process.env.AILK_ENABLED_MODULES;
+    delete process.env.AILK_TRUSTED_ORIGINS;
+    delete process.env.SCHEDULING_CREDENTIAL_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY_PREVIOUS;
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    jest.restoreAllMocks();
+  });
+
+  it("exposes the decoded keys when they are valid, and nothing when unset", () => {
+    process.env.STRIPE_CONNECTION_KEY = b64(A);
+    process.env.STRIPE_CONNECTION_KEY_PREVIOUS = b64(B);
+    const { config } = require("../index");
+    expect(config.STRIPE_CONNECTION_KEY.equals(A)).toBe(true);
+    expect(config.STRIPE_CONNECTION_KEY_PREVIOUS.equals(B)).toBe(true);
+
+    jest.resetModules();
+    delete process.env.STRIPE_CONNECTION_KEY;
+    delete process.env.STRIPE_CONNECTION_KEY_PREVIOUS;
+    const { config: unset } = require("../index");
+    expect(unset.STRIPE_CONNECTION_KEY).toBeUndefined();
+    expect(unset.STRIPE_CONNECTION_KEY_PREVIOUS).toBeUndefined();
+  });
+
+  it.each([
+    ["a 31-byte key", { STRIPE_CONNECTION_KEY: b64(randomBytes(31)) }],
+    ["the scheduling key", { STRIPE_CONNECTION_KEY: b64(S), SCHEDULING_CREDENTIAL_KEY: b64(S) }],
+    ["a previous key alone", { STRIPE_CONNECTION_KEY_PREVIOUS: b64(B) }],
+  ])("exits on a refused value (%s), logging the variable but never the value", (_label, env) => {
+    Object.assign(process.env, env);
+    const exitSpy = jest.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("Process exit called");
+    });
+    const consoleError = jest.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(() => require("../index")).toThrow("Process exit called");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(mockLoggerError).toHaveBeenCalledTimes(1);
+
+    const logged = JSON.stringify([mockLoggerError.mock.calls, consoleError.mock.calls]);
+    expect(logged).toContain("STRIPE_CONNECTION_KEY");
+    for (const value of Object.values(env)) {
+      expect(logged).not.toContain(value);
+      expect(logged).not.toContain(value.slice(0, 12));
+    }
+  });
+});
+
+describe("the .env.example files (#8907 D3)", () => {
+  const REPO_ROOT = join(__dirname, "..", "..", "..", "..", "..");
+
+  it.each([".env.example", "apps/api/.env.example"])("%s documents both variables, commented out", (file) => {
+    const text = readFileSync(join(REPO_ROOT, file), "utf8");
+    expect(text).toMatch(/^# STRIPE_CONNECTION_KEY=$/m);
+    expect(text).toMatch(/^# STRIPE_CONNECTION_KEY_PREVIOUS=$/m);
+  });
+});

package/templates/apps/api/src/config/index.ts

@@ -112,6 +112,15 @@ export interface Config {
   // env-configured CAL_API_KEY path works exactly as before. Held decoded,
   // never as the raw string, and never logged.
   SCHEDULING_CREDENTIAL_KEY?: Buffer;
+  // An Organization's Stripe connection (#8907 D3, contract C3, C10) — the
+  // AES-256-GCM key services/offerings/connection.ts encrypts each
+  // connection's restricted key and webhook secret under, and the key it
+  // replaced during a rotation. The SCHEDULING_CREDENTIAL_KEY shape rule,
+  // checked at startup by resolveStripeConnectionKeys() below; a refused
+  // value stops the API. Optional: unset (or empty) means a connection can be
+  // read and removed but not written. Held decoded, never logged.
+  STRIPE_CONNECTION_KEY?: Buffer;
+  STRIPE_CONNECTION_KEY_PREVIOUS?: Buffer;
   // What a hub does with a request to a spoke-aware public surface (meeting
   // types, the three lead writes, booking, availability, event meta, the
   // public content reads) that carries no `x-ailk-spoke-key` (#7532 D7,
@@ -258,6 +267,82 @@ export function resolveSchedulingCredentialKey(
   return { kind: 'ok', key };
 }
 
+/** The two variables an Organization's Stripe connection key is read from (#8907 D3). */
+export type StripeConnectionKeyVariable =
+  | 'STRIPE_CONNECTION_KEY'
+  | 'STRIPE_CONNECTION_KEY_PREVIOUS';
+
+/** Why a Stripe connection key was refused (#8907 D3). */
+export type StripeConnectionKeyRefusal =
+  | SchedulingCredentialKeyRefusal
+  | 'previous_without_current'
+  | 'previous_equals_current'
+  | 'shared_with_scheduling';
+
+/**
+ * The Stripe connection keys (#8907 D3, contract C3, C10). Pure;
+ * `validateConfig()` calls it once.
+ *
+ * Each raw value is read with `resolveSchedulingCredentialKey`, the one shape
+ * rule. A previous key needs a current one, may not equal it, and neither may
+ * equal the scheduling key (`Buffer.equals`), so one key never guards both
+ * calendars and money. A refusal names the variable and the reason kind only,
+ * never any part of a value.
+ */
+export function resolveStripeConnectionKeys(input: {
+  current: string | undefined;
+  previous: string | undefined;
+  scheduling: Buffer | undefined;
+}):
+  | { kind: 'ok'; current?: Buffer; previous?: Buffer }
+  | {
+      kind: 'refused';
+      variable: StripeConnectionKeyVariable;
+      reason: StripeConnectionKeyRefusal;
+    } {
+  const current = resolveSchedulingCredentialKey(input.current);
+  if (current.kind === 'refused') {
+    return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY', reason: current.reason };
+  }
+  const previous = resolveSchedulingCredentialKey(input.previous);
+  if (previous.kind === 'refused') {
+    return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY_PREVIOUS', reason: previous.reason };
+  }
+  const currentKey = current.kind === 'ok' ? current.key : undefined;
+  const previousKey = previous.kind === 'ok' ? previous.key : undefined;
+  if (previousKey && !currentKey) {
+    return {
+      kind: 'refused',
+      variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+      reason: 'previous_without_current',
+    };
+  }
+  if (previousKey && currentKey?.equals(previousKey)) {
+    return {
+      kind: 'refused',
+      variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+      reason: 'previous_equals_current',
+    };
+  }
+  if (input.scheduling) {
+    if (currentKey?.equals(input.scheduling)) {
+      return { kind: 'refused', variable: 'STRIPE_CONNECTION_KEY', reason: 'shared_with_scheduling' };
+    }
+    if (previousKey?.equals(input.scheduling)) {
+      return {
+        kind: 'refused',
+        variable: 'STRIPE_CONNECTION_KEY_PREVIOUS',
+        reason: 'shared_with_scheduling',
+      };
+    }
+  }
+  return {
+    kind: 'ok',
+    ...(currentKey && { current: currentKey }),
+    ...(previousKey && { previous: previousKey }),
+  };
+}
+
 /**
  * `AILK_HUB_REQUIRE_SPOKE_KEY` (#7532 D7, #7633 D2): unset, empty or blank →
  * `"auto"`; `true`/`1` → `"on"`; `false`/`0` → `"off"` — case-insensitive,
@@ -364,6 +449,24 @@ function validateConfig(): Config {
     process.exit(1);
   }
 
+  // #8907 D3 — a set-but-refused Stripe connection key stops the API in every
+  // environment, for the scheduling key's reason; so does a key shared with
+  // the scheduling key or a previous key that could never be rotated away.
+  // The variable and the reason kind only, never a value.
+  const stripeConnectionKeys = resolveStripeConnectionKeys({
+    current: process.env.STRIPE_CONNECTION_KEY,
+    previous: process.env.STRIPE_CONNECTION_KEY_PREVIOUS,
+    scheduling: schedulingKey.kind === 'ok' ? schedulingKey.key : undefined,
+  });
+  if (stripeConnectionKeys.kind === 'refused') {
+    const { variable, reason } = stripeConnectionKeys;
+    const message =
+      '❌ STRIPE_CONNECTION_KEY and STRIPE_CONNECTION_KEY_PREVIOUS must each be canonical standard base64 of exactly 32 bytes (openssl rand -base64 32), distinct from each other and from SCHEDULING_CREDENTIAL_KEY, and a previous key needs a current one';
+    logger.error({ variable, reason }, message);
+    console.error(message, JSON.stringify({ variable, reason }));
+    process.exit(1);
+  }
+
   // #7532 D7, #7633 D2 — the hub's spoke-key mode. An unparseable value stops
   // the API: a typo read as "off" would silently leave the hub open to
   // header-less callers. The message names the variable, never its value.
@@ -479,6 +582,12 @@ function validateConfig(): Config {
     ...(schedulingKey.kind === 'ok' && {
       SCHEDULING_CREDENTIAL_KEY: schedulingKey.key,
     }),
+    ...(stripeConnectionKeys.current && {
+      STRIPE_CONNECTION_KEY: stripeConnectionKeys.current,
+    }),
+    ...(stripeConnectionKeys.previous && {
+      STRIPE_CONNECTION_KEY_PREVIOUS: stripeConnectionKeys.previous,
+    }),
     AILK_HUB_REQUIRE_SPOKE_KEY: hubRequireSpokeKey,
     AILK_SPOKE_FLOW_SEED: spokeFlowSeed,
   };

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -203,6 +203,9 @@ export const prisma = {
     findFirst: jest.fn(),
     findMany: jest.fn(),
     updateMany: jest.fn(),
+    // `count` — the flow engine's completion-email caps (#8847 security
+    // review). Unarranged it resolves undefined, which caps nothing.
+    count: jest.fn(),
   },
   subscriber: {
     create: jest.fn(),

package/templates/apps/api/src/lib/__tests__/consent-store.test.ts

@@ -135,6 +135,25 @@ describe("the two readings (SEC-8438-1)", () => {
     ).toBe(true);
   });
 
+  it("a checkout row is unverified: in the Person's any-source reading, never their own (#8765 D13, C10)", async () => {
+    expect(isUnverifiedSource("checkout")).toBe(true);
+    double.ledger.push(
+      row({
+        purposeId: "data",
+        granted: true,
+        source: "checkout",
+        sourceRef: "cs_live_abc123",
+      }),
+    );
+    const own = await ownConsentState(WS, PERSON, CONFIG);
+    const any = await anySourceConsentState(WS, PERSON, CONFIG);
+    expect(own.find((s) => s.purposeId === "data")?.row).toBeNull();
+    expect(any.find((s) => s.purposeId === "data")?.row).toMatchObject({
+      source: "checkout",
+      sourceRef: "cs_live_abc123",
+    });
+  });
+
   it("another workspace's rows and another Person's rows never show", async () => {
     double.ledger.push(
       row({ workspaceId: OTHER_WS, purposeId: "data", granted: true }),

package/templates/apps/api/src/lib/__tests__/flow-completion-store.test.ts

@@ -0,0 +1,149 @@
+/**
+ * @file flow-completion-store.test.ts
+ *
+ * A magnet's completion setting — its data boundary (#8757, spec
+ * docs/specs/8757-a-per-magnet-completion-setting-spec.md D3, AC-3): every
+ * statement is scoped by the workspace it is given, so a write naming another
+ * workspace's magnet answers `not_found` and changes nothing, a draft magnet
+ * is never a live completion, and the invite caps count only this magnet's
+ * leads of this workspace in their window.
+ *
+ * The world is the in-memory Prisma double (`__tests__/factories/in-memory-prisma`),
+ * which refuses a filter it does not model — so scoping that rides on one
+ * cannot pass silently.
+ */
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../prisma.js", () =>
+  jest
+    .requireActual<typeof import("../../__tests__/factories/in-memory-prisma")>(
+      "../../__tests__/factories/in-memory-prisma",
+    )
+    .createInMemoryPrisma(),
+);
+
+import { prisma } from "../prisma.js";
+import {
+  completionOf,
+  completionsFor,
+  inviteSendCounts,
+  liveCompletionBySlug,
+  setCompletion,
+} from "../flow-completion-store.js";
+
+type Row = Record<string, unknown>;
+// eslint-disable-next-line no-restricted-syntax -- the in-memory double exposes its store on keys the real client type does not declare
+const fake = prisma as unknown as { __db: Record<string, Row[]> };
+
+const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
+const WS_A2 = "wksp_00000000-0000-7000-8000-0000000000a2";
+const M1 = "flow_00000000-0000-7000-8000-000000000001";
+const M2 = "flow_00000000-0000-7000-8000-000000000002";
+const DRAFT = "flow_00000000-0000-7000-8000-000000000003";
+const NOW = new Date("2026-10-15T12:00:00.000Z");
+
+function magnet(id: string, ws: string, slug: string, status: string, extra: Row = {}): Row {
+  return { id, siteId: ws, workspaceId: ws, slug, title: `Magnet ${slug}`, status, ...extra };
+}
+
+function lead(ws: string, n: number, source: string, email: string, ago: number): Row {
+  return {
+    id: `lead_00000000-0000-7000-8000-${String(n).padStart(12, "0")}`,
+    siteId: ws,
+    workspaceId: ws,
+    source,
+    email,
+    createdAt: new Date(NOW.getTime() - ago),
+  };
+}
+
+beforeEach(() => {
+  const db = fake.__db;
+  for (const key of Object.keys(db)) delete db[key];
+  db.flowDefinition = [
+    magnet(M1, WS_A1, "contact", "live", { completion: "invite", checkoutOffering: null }),
+    magnet(M2, WS_A2, "contact", "live", { completion: "lead", checkoutOffering: null }),
+    magnet(DRAFT, WS_A1, "request-quote", "draft", { completion: "invite", checkoutOffering: null }),
+  ];
+  db.lead = [];
+});
+
+describe("completionsFor (D3)", () => {
+  it("reads only the given workspace's rows; an id absent from it reads as lead", async () => {
+    const settings = await completionsFor(WS_A1, [M1, M2]);
+    expect(completionOf(settings, M1)).toEqual({ completion: "invite", checkoutOffering: null });
+    expect(settings.has(M2)).toBe(false);
+    expect(completionOf(settings, M2)).toEqual({ completion: "lead", checkoutOffering: null });
+  });
+
+  it("reads a row with neither column as lead", async () => {
+    fake.__db.flowDefinition!.push(
+      magnet("flow_00000000-0000-7000-8000-000000000009", WS_A1, "bare", "live"),
+    );
+    const settings = await completionsFor(WS_A1, ["flow_00000000-0000-7000-8000-000000000009"]);
+    expect(completionOf(settings, "flow_00000000-0000-7000-8000-000000000009")).toEqual({
+      completion: "lead",
+      checkoutOffering: null,
+    });
+  });
+});
+
+describe("setCompletion (D3, AC-3)", () => {
+  it("writes exactly the pair onto the workspace's own magnet", async () => {
+    expect(
+      await setCompletion(WS_A1, M1, { completion: "checkout", checkoutOffering: "retainer" }),
+    ).toBe("set");
+    const row = fake.__db.flowDefinition!.find((r) => r.id === M1)!;
+    // `updatedAt` is Prisma-managed (`@updatedAt`); every other column is as it was.
+    expect(row).toEqual({
+      ...magnet(M1, WS_A1, "contact", "live", {
+        completion: "checkout",
+        checkoutOffering: "retainer",
+      }),
+      updatedAt: expect.any(Date),
+    });
+  });
+
+  it("answers not_found for another workspace's magnet and changes nothing", async () => {
+    const before = structuredClone(fake.__db.flowDefinition);
+    expect(await setCompletion(WS_A1, M2, { completion: "invite", checkoutOffering: null })).toBe(
+      "not_found",
+    );
+    expect(fake.__db.flowDefinition).toEqual(before);
+  });
+});
+
+describe("liveCompletionBySlug (D3, AC-3)", () => {
+  it("answers a live magnet's setting and title", async () => {
+    expect(await liveCompletionBySlug(WS_A1, "contact")).toEqual({
+      completion: "invite",
+      checkoutOffering: null,
+      title: "Magnet contact",
+      config: undefined,
+    });
+  });
+
+  it("answers null for a draft row, an absent slug and another workspace's magnet", async () => {
+    expect(await liveCompletionBySlug(WS_A1, "request-quote")).toBeNull();
+    expect(await liveCompletionBySlug(WS_A1, "missing")).toBeNull();
+    fake.__db.flowDefinition = fake.__db.flowDefinition!.filter((r) => r.id !== M1);
+    expect(await liveCompletionBySlug(WS_A1, "contact")).toBeNull();
+  });
+});
+
+describe("inviteSendCounts (D6)", () => {
+  it("counts this magnet's leads of this workspace: the recipient's over a day, all over an hour", async () => {
+    const HOUR = 60 * 60 * 1000;
+    fake.__db.lead = [
+      lead(WS_A1, 1, "flow:contact", "a@b.example", 5 * 60 * 1000),
+      lead(WS_A1, 2, "flow:contact", "a@b.example", 20 * HOUR),
+      lead(WS_A1, 3, "flow:contact", "a@b.example", 25 * HOUR),
+      lead(WS_A1, 4, "flow:contact", "c@d.example", 10 * 60 * 1000),
+      lead(WS_A1, 5, "flow:other", "a@b.example", 60 * 1000),
+      lead(WS_A2, 6, "flow:contact", "a@b.example", 60 * 1000),
+    ];
+    expect(await inviteSendCounts(WS_A1, "contact", "a@b.example", NOW)).toEqual({
+      recipientDay: 2,
+      siteHour: 2,
+    });
+  });
+});

package/templates/apps/api/src/lib/__tests__/flow-rename-race.db.test.ts

@@ -0,0 +1,116 @@
+/**
+ * @file flow-rename-race.db.test.ts
+ *
+ * LIVE-DATABASE proof of #8734 AC-5 (spec
+ * docs/specs/8734-magnet-slug-renames-an-anonymous-spec.md D4): two renames
+ * racing for one free slug are serialized by `flow_definitions`'
+ * `(site_id, slug)` unique key. `flows.rename`'s first write is the
+ * definition row, so the second transaction's write waits on the first's
+ * uncommitted index entry and, once the first commits, fails with `23505` —
+ * which Prisma reports as `P2002` and `rename` answers `conflict`. The pre-
+ * checks run at READ COMMITTED and guarantee nothing here; the key does.
+ *
+ * Runs only when `AILK_TEST_LIVE_DATABASE === "1"` (set beside a real
+ * `DATABASE_URL` by `.github/workflows/api-postgres-compat.yml`), and uses the
+ * `pg` driver directly, the same reason `rate-limit-cross-isolate.db.test.ts`
+ * does: the generated Prisma client is ESM-only and cannot load under this
+ * package's CJS ts-jest transform.
+ */
+import { Client } from "pg";
+
+const describeDb =
+  process.env.AILK_TEST_LIVE_DATABASE === "1" ? describe : describe.skip;
+
+describeDb("flow_definitions' (site_id, slug) key serializes two renames to one slug (live, #8734 AC-5)", () => {
+  let first: Client;
+  let second: Client;
+  let workspaceId = "";
+  let rowA = "";
+  let rowB = "";
+
+  async function insertRow(slug: string): Promise<string> {
+    const res = await first.query<{ id: string }>(
+      `INSERT INTO "flow_definitions"
+         ("site_id", "workspace_id", "slug", "config", "kind", "title", "status", "customers_enabled", "updated_at")
+       VALUES ($1, $1, $2, '{}'::jsonb, 'contact', $2, 'draft', false, now())
+       RETURNING "id"`,
+      [workspaceId, slug],
+    );
+    return res.rows[0]!.id;
+  }
+
+  /** Until `pid`'s statement is blocked on a lock — the wait the key imposes. */
+  async function waitUntilBlocked(pid: number): Promise<void> {
+    for (let attempt = 0; attempt < 100; attempt++) {
+      const res = await first.query<{ wait_event_type: string | null }>(
+        `SELECT "wait_event_type" FROM pg_stat_activity WHERE "pid" = $1`,
+        [pid],
+      );
+      if (res.rows[0]?.wait_event_type === "Lock") return;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error("the second rename never waited on the first");
+  }
+
+  beforeAll(async () => {
+    first = new Client({ connectionString: process.env.DATABASE_URL });
+    second = new Client({ connectionString: process.env.DATABASE_URL });
+    await first.connect();
+    await second.connect();
+    const ws = await first.query<{ id: string }>(
+      `SELECT 'wksp_' || uuidv7()::text AS "id"`,
+    );
+    workspaceId = ws.rows[0]!.id;
+    rowA = await insertRow("race-a");
+    rowB = await insertRow("race-b");
+  });
+
+  afterAll(async () => {
+    await first.query(`DELETE FROM "flow_definitions" WHERE "workspace_id" = $1`, [
+      workspaceId,
+    ]);
+    await first.end();
+    await second.end();
+  });
+
+  it("the second rename to one slug waits on the first, then fails 23505 on flow_definitions_site_id_slug_key; one row holds the slug", async () => {
+    const rename = `UPDATE "flow_definitions" SET "slug" = 'race-x' WHERE "id" = $1`;
+    const secondPid = (await second.query<{ pid: number }>("SELECT pg_backend_pid() AS pid"))
+      .rows[0]!.pid;
+
+    let error: { code?: string; constraint?: string } | null | undefined;
+    try {
+      await first.query("BEGIN");
+      await first.query(rename, [rowA]);
+
+      await second.query("BEGIN");
+      // Not awaited: it blocks on the first transaction's uncommitted entry.
+      const loser = second.query(rename, [rowB]).then(
+        () => null,
+        (failure: unknown) => failure as { code?: string; constraint?: string },
+      );
+      await waitUntilBlocked(secondPid);
+
+      await first.query("COMMIT");
+      error = await loser;
+    } finally {
+      await first.query("ROLLBACK");
+      await second.query("ROLLBACK");
+    }
+
+    expect(error).toMatchObject({
+      code: "23505",
+      constraint: "flow_definitions_site_id_slug_key",
+    });
+    const atSlug = await first.query<{ count: string }>(
+      `SELECT count(*) AS "count" FROM "flow_definitions" WHERE "workspace_id" = $1 AND "slug" = 'race-x'`,
+      [workspaceId],
+    );
+    expect(atSlug.rows[0]!.count).toBe("1");
+    const b = await first.query<{ slug: string }>(
+      `SELECT "slug" FROM "flow_definitions" WHERE "id" = $1`,
+      [rowB],
+    );
+    expect(b.rows[0]!.slug).toBe("race-b");
+  });
+});