create-ailk 0.14.0 → 0.15.0

package/templates/apps/web/lib/__tests__/site-brand.test.ts

@@ -118,6 +118,58 @@ describe("SITE_NAME / SITE_BASE_URL (#4157)", () => {
   });
 });
 
+/**
+ * `COPYRIGHT_HOLDER` — the footer's holder (#7796): `siteIdentity.legalName`
+ * when declared, else the site name, exactly as before.
+ */
+describe("COPYRIGHT_HOLDER (#7796)", () => {
+  function writeIdentity(identityLines: string): void {
+    writeFileSync(
+      join(tmpRoot, "_site.mdx"),
+      `---\nsiteName: Wendi Henry\nsiteIdentity:\n  kind: Person\n  name: Wendi Henry\n${identityLines}---\n`,
+    );
+    process.env["AILK_CONTENT_ROOT"] = tmpRoot;
+    delete process.env["NEXT_PUBLIC_SITE_NAME"];
+  }
+
+  it("is siteIdentity.legalName when the site declares one", async () => {
+    writeIdentity("  legalName: SalesSmyth LLC\n");
+    const { COPYRIGHT_HOLDER, SITE_NAME } = await loadSiteBrand();
+
+    expect(COPYRIGHT_HOLDER).toBe("SalesSmyth LLC");
+    expect(SITE_NAME).toBe("Wendi Henry");
+  });
+
+  it("falls back to SITE_NAME when no legalName is declared", async () => {
+    writeIdentity("");
+    const { COPYRIGHT_HOLDER, SITE_NAME } = await loadSiteBrand();
+
+    expect(COPYRIGHT_HOLDER).toBe(SITE_NAME);
+  });
+
+  it("falls back to SITE_NAME when legalName is blank or not a string", async () => {
+    writeIdentity('  legalName: "  "\n');
+    expect((await loadSiteBrand()).COPYRIGHT_HOLDER).toBe("Wendi Henry");
+
+    writeIdentity("  legalName: 42\n");
+    expect((await loadSiteBrand()).COPYRIGHT_HOLDER).toBe("Wendi Henry");
+  });
+
+  it("follows the NEXT_PUBLIC_SITE_NAME override when no legalName is declared", async () => {
+    writeIdentity("");
+    process.env["NEXT_PUBLIC_SITE_NAME"] = "Env Override Co";
+    expect((await loadSiteBrand()).COPYRIGHT_HOLDER).toBe("Env Override Co");
+  });
+
+  it("falls back to the neutral default when _site.mdx is absent", async () => {
+    process.env["AILK_CONTENT_ROOT"] = tmpRoot;
+    delete process.env["NEXT_PUBLIC_SITE_NAME"];
+    const { COPYRIGHT_HOLDER, FALLBACK_SITE_NAME } = await loadSiteBrand();
+
+    expect(COPYRIGHT_HOLDER).toBe(FALLBACK_SITE_NAME);
+  });
+});
+
 /**
  * `siteLogo()` — the brand triad's logomark (#6820 D5). No `brand:` renders
  * exactly today's element; a declared mark is the one rendered, with its dark

package/templates/apps/web/lib/closing-footer-path.ts

@@ -0,0 +1,50 @@
+/**
+ * Whether a page ends on the closing footer (#7797).
+ *
+ * The `closingFooterPaths` chrome knob lists route paths as the site writes
+ * them ("/about"). The visitor's pathname arrives as the middleware forwards it, so
+ * it may carry a locale prefix ("/es/about") or a trailing slash ("/about/").
+ * Both sides are reduced to the same form before they are compared, so the
+ * list names a page once however a request spells it.
+ *
+ * No Next.js import — pure functions, asserted directly by their own suite,
+ * in the `profile-back-link.ts` idiom.
+ */
+
+/** `path` without its query or fragment, any enabled-locale prefix, or trailing slashes; "/" for the root. */
+export function normalizeRoutePath(
+  path: string,
+  locales: readonly string[],
+): string {
+  const bare = path.split(/[?#]/)[0] ?? "";
+  // Compare the first segment to the locale list rather than building a
+  // pattern from it, so a locale code is never read as regex syntax.
+  const segments = bare.split("/");
+  const first = segments[1];
+  const unprefixed =
+    first !== undefined && locales.includes(first)
+      ? ["", ...segments.slice(2)].join("/")
+      : bare;
+  const trimmed = unprefixed.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+
+/**
+ * True when `pathname` is one of `paths` and is not the home.
+ *
+ * Fail-safe direction: an absent or empty list, or an absent pathname, answers
+ * `false`, so a site that sets no list renders exactly as before. The home is
+ * never an inner page, so listing "/" has no effect — the home's footer is its
+ * own knobs' (`home`, `chromeStyle`).
+ */
+export function isClosingFooterPath(input: {
+  pathname: string | null | undefined;
+  paths: readonly string[] | undefined;
+  locales: readonly string[];
+}): boolean {
+  const { pathname, paths, locales } = input;
+  if (!pathname || !paths || paths.length === 0) return false;
+  const current = normalizeRoutePath(pathname, locales);
+  if (current === "/") return false;
+  return paths.some((path) => normalizeRoutePath(path, locales) === current);
+}

package/templates/apps/web/lib/relay.ts

@@ -28,9 +28,18 @@
  *   - AN ALLOW-LIST OF HEADERS (D3). Nothing else from the incoming request is
  *     forwarded: no `authorization`, no client-sent `x-ailk-*`, no `host`, and
  *     a `cookie` only on the one session route.
+ *   - A PER-VISITOR BUDGET (#7707, D1-D7). Each visitor gets 8 calls per 10
+ *     minutes across the five visitor routes, and 30 per 10 minutes on the
+ *     session route, counted in this instance's own in-memory store; the
+ *     ninth (31st) gets `429 rate_limited` before any hub call. Per instance,
+ *     and only as strong as the platform: it 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).
  *
  * NO SECRET IS LOGGED. A failure logs `{ path, outcome }` and nothing else.
  */
+import { isIP } from "node:net";
+
 import { relayToApi, visitorForwardHeaders } from "@working-theory/api-client";
 
 type RelayMethod = "GET" | "POST";
@@ -78,11 +87,195 @@ const BASE_RESPONSE_HEADERS = {
   "x-content-type-options": "nosniff",
 } as const;
 
-function refusal(status: number, code: string, message: string): Response {
+function refusal(
+  status: number,
+  code: string,
+  message: string,
+  extraHeaders?: Record<string, string>,
+): Response {
   return Response.json(
     { ok: false, error: { code, message } },
-    { status, headers: BASE_RESPONSE_HEADERS },
+    { status, headers: { ...BASE_RESPONSE_HEADERS, ...extraHeaders } },
+  );
+}
+
+/**
+ * The per-visitor budget (#7707, D1-D2): 8 calls per 10 minutes shared across
+ * the five visitor routes, 30 per 10 minutes on the session route alone, an
+ * in-process store capped at 10,000 entries. No env var tunes these (AC-8).
+ */
+export const RELAY_RATE_LIMIT = Object.freeze({
+  limit: 8,
+  sessionLimit: 30,
+  windowMs: 600_000,
+  maxBuckets: 10_000,
+});
+
+type RateLimitBucket = {
+  count: number;
+  windowStartMs: number;
+};
+
+// Module-scoped store, shared by the visitor (`visitor|<identity>`) and
+// session (`session|<identity>`) budgets (D7: same identity, window and
+// store). Ported from the hub's own limiter
+// (`apps/api/src/middleware/rate-limit.ts`), not imported — `apps/web`
+// cannot import `apps/api`.
+const rateLimitBuckets = new Map<string, RateLimitBucket>();
+let requestsSinceSweep = 0;
+const SWEEP_INTERVAL_REQUESTS = 100;
+
+function evictExpiredBuckets(now: number): void {
+  for (const [key, bucket] of rateLimitBuckets) {
+    if (now - bucket.windowStartMs >= RELAY_RATE_LIMIT.windowMs) {
+      rateLimitBuckets.delete(key);
+    }
+  }
+}
+
+/** Test-only reset (D8). Not reachable over HTTP. */
+export function __resetRelayRateLimit(): void {
+  rateLimitBuckets.clear();
+  requestsSinceSweep = 0;
+}
+
+/** Test-only accessor for the current distinct-bucket count (D8). */
+export function __relayRateLimitBucketCount(): number {
+  return rateLimitBuckets.size;
+}
+
+/**
+ * Count one request against `key`, opening a new window when needed (D6). A
+ * genuinely new identity at capacity evicts the single oldest-inserted entry
+ * first (`Map` iteration order is insertion order) — the hub's own `hit()`.
+ */
+function hit(key: string, now: number): RateLimitBucket {
+  let bucket = rateLimitBuckets.get(key);
+  if (!bucket || now - bucket.windowStartMs >= RELAY_RATE_LIMIT.windowMs) {
+    if (
+      !rateLimitBuckets.has(key) &&
+      rateLimitBuckets.size >= RELAY_RATE_LIMIT.maxBuckets
+    ) {
+      const oldestKey = rateLimitBuckets.keys().next().value;
+      if (oldestKey !== undefined) rateLimitBuckets.delete(oldestKey);
+    }
+    bucket = { count: 0, windowStartMs: now };
+    rateLimitBuckets.set(key, bucket);
+  }
+  bucket.count += 1;
+  return bucket;
+}
+
+/**
+ * The eight hextets of a valid IPv6 address, or `null`. Ported from the
+ * hub's own `expandIpv6` (`apps/api/src/middleware/rate-limit.ts`).
+ */
+function expandIpv6(address: string): number[] | null {
+  let text = address;
+  const tail: number[] = [];
+  const lastColon = text.lastIndexOf(":");
+  const last = text.slice(lastColon + 1);
+  if (last.includes(".")) {
+    const octets = last.split(".").map(Number);
+    tail.push(((octets[0] ?? 0) << 8) | (octets[1] ?? 0));
+    tail.push(((octets[2] ?? 0) << 8) | (octets[3] ?? 0));
+    text = `${text.slice(0, lastColon + 1)}0`;
+  }
+  const halves = text.split("::");
+  const parse = (part: string | undefined): number[] =>
+    part ? part.split(":").map((hextet) => parseInt(hextet, 16)) : [];
+  const head = parse(halves[0]);
+  const rest = parse(halves[1]);
+  if (tail.length > 0) {
+    (halves.length > 1 ? rest : head).pop();
+  }
+  const fill = 8 - head.length - rest.length - tail.length;
+  if (fill < 0 || (halves.length === 1 && fill !== 0)) return null;
+  const hextets = [
+    ...head,
+    ...new Array<number>(fill).fill(0),
+    ...rest,
+    ...tail,
+  ];
+  return hextets.every((h) => Number.isInteger(h) && h >= 0 && h <= 0xffff)
+    ? hextets
+    : null;
+}
+
+const MAX_VISITOR_IP_LENGTH = 45;
+
+/**
+ * Validate and normalise a visitor address (D3): IPv4 as is, an IPv4-mapped
+ * IPv6 address as its IPv4 form, any other IPv6 address as its /64 prefix.
+ * `null` for anything else. Ported from the hub's own `normaliseVisitorIp`.
+ */
+function normaliseVisitorIp(raw: string): string | null {
+  const value = raw.trim().toLowerCase();
+  if (value.length > MAX_VISITOR_IP_LENGTH || value.includes("%")) return null;
+  const family = isIP(value);
+  if (family === 4) return value;
+  if (family !== 6) return null;
+  const hextets = expandIpv6(value);
+  if (!hextets) return null;
+  const isV4Mapped =
+    hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff;
+  if (isV4Mapped) {
+    const high = hextets[6] ?? 0;
+    const low = hextets[7] ?? 0;
+    return [high >> 8, high & 0xff, low >> 8, low & 0xff].join(".");
+  }
+  const prefix = hextets
+    .slice(0, 4)
+    .map((h) => h.toString(16).padStart(4, "0"))
+    .join(":");
+  return `${prefix}::/64`;
+}
+
+/**
+ * The visitor's identity (D3): the first comma-separated value of
+ * `x-forwarded-for` when present (a present-but-empty value does not fall
+ * back to `x-real-ip`), else `x-real-ip`. Anything that does not normalise —
+ * no header, an empty value, or one `normaliseVisitorIp` rejects — shares the
+ * single identity `"unknown"`, never a fresh bucket of its own.
+ */
+function visitorIdentity(request: Request): string {
+  const raw =
+    request.headers.get("x-forwarded-for") ?? request.headers.get("x-real-ip");
+  const first = raw?.split(",")[0]?.trim().toLowerCase();
+  if (!first) return "unknown";
+  return normaliseVisitorIp(first) ?? "unknown";
+}
+
+/**
+ * Count one request against its budget (D1-D7): the visitor budget for every
+ * entry but the session route, which gets its own, wider, independent
+ * budget. Returns whether the call is admitted and the whole seconds (at
+ * least 1) until the tripped bucket's window ends.
+ */
+function checkRateLimit(
+  request: Request,
+  entry: RelayRoute,
+  now: number,
+): { allowed: boolean; retryAfterSeconds: number } {
+  requestsSinceSweep += 1;
+  if (requestsSinceSweep >= SWEEP_INTERVAL_REQUESTS) {
+    evictExpiredBuckets(now);
+    requestsSinceSweep = 0;
+  }
+
+  const identity = visitorIdentity(request);
+  const isSession = entry === SESSION_ROUTE;
+  const key = `${isSession ? "session" : "visitor"}|${identity}`;
+  const limit = isSession
+    ? RELAY_RATE_LIMIT.sessionLimit
+    : RELAY_RATE_LIMIT.limit;
+
+  const bucket = hit(key, now);
+  const retryAfterSeconds = Math.max(
+    1,
+    Math.ceil((bucket.windowStartMs + RELAY_RATE_LIMIT.windowMs - now) / 1000),
   );
+  return { allowed: bucket.count <= limit, retryAfterSeconds };
 }
 
 /**
@@ -220,6 +413,17 @@ export async function handleRelay(request: Request): Promise<Response> {
     return refusal(403, "cross_site", "Cross-site request refused");
   }
 
+  const { allowed, retryAfterSeconds } = checkRateLimit(
+    request,
+    entry,
+    Date.now(),
+  );
+  if (!allowed) {
+    return refusal(429, "rate_limited", "Too many requests", {
+      "retry-after": String(retryAfterSeconds),
+    });
+  }
+
   let body: string | undefined;
   if (entry.method === "POST") {
     if (!isJson(request.headers.get("content-type"))) {

package/templates/apps/web/lib/site-brand.tsx

@@ -47,6 +47,8 @@ interface SiteFrontmatter {
   baseUrl?: string | undefined;
   /** `brand.logomark`, raw — validated by `siteLogo()` when it renders. */
   logomark?: unknown;
+  /** `siteIdentity.legalName`, when declared as a non-empty string. */
+  legalName?: string | undefined;
 }
 
 /**
@@ -84,8 +86,19 @@ function readSiteFrontmatter(): SiteFrontmatter | null {
     const parsed: unknown = parseYaml(match[1] ?? "");
     if (!parsed || typeof parsed !== "object") return null;
 
-    const { siteName, baseUrl, brand } = parsed as Record<string, unknown>;
+    const { siteName, baseUrl, brand, siteIdentity } = parsed as Record<
+      string,
+      unknown
+    >;
+    const legalName =
+      siteIdentity && typeof siteIdentity === "object"
+        ? (siteIdentity as Record<string, unknown>).legalName
+        : undefined;
     return {
+      legalName:
+        typeof legalName === "string" && legalName.trim().length > 0
+          ? legalName.trim()
+          : undefined,
       siteName: typeof siteName === "string" ? siteName : undefined,
       baseUrl: typeof baseUrl === "string" ? baseUrl : undefined,
       logomark:
@@ -112,6 +125,14 @@ export const SITE_NAME =
 export const SITE_BASE_URL =
   process.env.NEXT_PUBLIC_BASE_URL ?? siteFrontmatter?.baseUrl ?? FALLBACK_BASE_URL;
 
+/**
+ * The footer copyright holder (#7796): `siteIdentity.legalName` when the site
+ * declares one (schema.org's `Organization.legalName` — the owning entity,
+ * which often differs from the display name), else `SITE_NAME`. A site that
+ * declares no `legalName` resolves exactly as it did before this existed.
+ */
+export const COPYRIGHT_HOLDER = siteFrontmatter?.legalName ?? SITE_NAME;
+
 /**
  * The raw `brand.logomark` from `_site.mdx`, or `undefined` when none is
  * declared. Unvalidated: `siteLogo()` (`site-logo.tsx`) parses it on the

package/templates/apps/web/lib/site-chrome.ts

@@ -21,6 +21,8 @@
 //   - chromeStyle: "minimal" → the deck's closing slide is the wordmark,
 //     contact lines and one legal line; the consent bar is a hairline bar on
 //     the page ground; the 404 renders in the site's theme.
+//   - closingFooterPaths → each listed inner page ends on the closing footer
+//     (the wordmark, contact lines and legal line) instead of its usual footer.
 
 export interface SiteChrome {
   nav: "full" | "mark-only";
@@ -31,6 +33,7 @@ export interface SiteChrome {
   deckPresentation?: true;
   colorMode?: "light";
   chromeStyle?: "minimal";
+  closingFooterPaths?: readonly string[];
 }
 
 export const siteChrome: SiteChrome = {

package/templates/apps/web/lib/topology.generated.ts

@@ -0,0 +1,23 @@
+// topology.generated.ts — how this site reads a session and registers its stores.
+//
+// GENERATED by create-ailk for this site's topology (#7426). Do not edit:
+// every scaffold rewrites it. A hub reads the session through Better Auth;
+// a spoke (`--topology spoke`) has no sign-in and no database of its own,
+// so its render reads no session and imports nothing.
+import { auth } from "../auth";
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+export const SIGN_IN_ENABLED: boolean = true;
+
+export type SiteSession = {
+  user: { name?: string | null; email: string };
+} | null;
+
+export async function readSession(headers: Headers): Promise<SiteSession> {
+  return auth.api.getSession({ headers });
+}
+
+export async function registerSiteStores(): Promise<void> {
+  const { registerLicenseKeyStore } = await import("./license-key-store");
+  await registerLicenseKeyStore();
+}

package/templates/apps/web/package.json

@@ -37,7 +37,7 @@
     "@working-theory/web-i18n": "workspace:*",
     "better-auth": "1.6.22",
     "lucide-react": "^0.577.0",
-    "next": "^16.3.3",
+    "next": "^16.3.8",
     "next-intl": "^3.26.3",
     "next-mdx-remote": "^6.0.0",
     "pg": "^8.22.0",

package/templates/database/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @working-theory/database
 
+## 0.37.0
+
+### Minor Changes
+
+- [#7821](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/7821) [`878ffc6`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/878ffc61e3c0baad68889e77d4686fdbc88a85c2) Thanks [@samuelhenry](https://github.com/samuelhenry)! - Sign-in lands in the user's last workspace ([#7803](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/7803)), the schema half.
+
+  - `@working-theory/database` — `User` gains `lastWorkspaceId` (`users.last_workspace_id`), a nullable reference to `Workspace` with `ON DELETE SET NULL`, an index and the ADR-0031 `wksp_` format CHECK; `Workspace` gains the back-relation `lastActiveUsers`. The migration `20261008120000_user_last_workspace` is purely additive: one nullable column with no default, so no backfill runs and no existing row changes. Deploy it before the API that reads the column.
+
+- [#7901](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/7901) [`6efec95`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/6efec954914e40acbf42db1e0132569e983c3915) Thanks [@samuelhenry](https://github.com/samuelhenry)! - Agent key grants ([#7864](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/7864)): an owner or admin can grant an agent any of five
+  permissions — content-edit, content-publish, assets-write, magnets-manage and
+  meeting-types-manage. `@working-theory/validation` adds
+  `AGENT_GRANTABLE_PERMISSIONS`, `isAgentGrantable`, `allows` and
+  `setAgentGrantsBodySchema`, and the agent wire row gains `grants`;
+  `@working-theory/database` adds the `agents.grants` column, held to those five
+  by a CHECK. An agent with no grants behaves exactly as before.
+
+- [#7895](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/7895) [`90451af`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/90451afcc7c264a0c5de7d239edcfbdefcf28f64) Thanks [@samuelhenry](https://github.com/samuelhenry)! - A lead write can be retried safely ([#7869](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/7869)), the schema half.
+
+  - `@working-theory/database` — `Lead` gains `idempotencyKey` (`leads.idempotency_key`), a nullable text column with a unique index over `(workspace_id, idempotency_key)`. The migration `20261008130000_lead_idempotency_key` is purely additive: one nullable column with no default and one unique index, so no backfill runs and no existing row changes (NULLs are distinct under the index). Deploy it before the API that writes the column.
+
+### Patch Changes
+
+- Updated dependencies [[`d3f8ac6`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/d3f8ac6bd41959f23a1f5f591e3cccce42895cd0), [`c979e93`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/c979e93a593606bfe47e815f29eef9e17be7e329), [`6efec95`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/6efec954914e40acbf42db1e0132569e983c3915)]:
+  - @working-theory/validation@0.37.0
+
 ## 0.36.0
 
 ### Patch Changes

package/templates/database/__tests__/agents.db.test.ts

@@ -18,11 +18,41 @@
  *   4. Deleting the membership of the person last shown the key sets
  *      `key_issued_to_membership_id` null and keeps the agent.
  *   5. Deleting the creator's user row leaves the agent (no relation).
+ *   6. `grants` (#7864 D2, AC-2) defaults to empty, takes any of the five
+ *      grantable permissions, and the `agents_grants_allowed` CHECK refuses
+ *      anything else.
+ *
+ * One case needs no database and always runs: the migration's CHECK names
+ * exactly `@working-theory/validation`'s `AGENT_GRANTABLE_PERMISSIONS`, so the
+ * SQL and the TypeScript spelling of the list cannot drift (SEC-7864-G).
  */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { AGENT_GRANTABLE_PERMISSIONS } from "@working-theory/validation";
 import { Client } from "pg";
 
 const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
 
+const GRANTS_MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261009120000_agent_grants",
+  "migration.sql",
+);
+
+describe("the agents_grants_allowed CHECK (#7864 D2, AC-2)", () => {
+  it("names exactly AGENT_GRANTABLE_PERMISSIONS", () => {
+    const sql = readFileSync(GRANTS_MIGRATION, "utf8");
+    const check = /CHECK \("grants" <@ ARRAY\[([^\]]*)\]::TEXT\[\]\)/.exec(sql);
+    expect(check).not.toBeNull();
+    const listed = [...check![1]!.matchAll(/'([^']*)'/g)].map((m) => m[1]);
+    expect(new Set(listed)).toEqual(new Set(AGENT_GRANTABLE_PERMISSIONS));
+    expect(listed).toHaveLength(AGENT_GRANTABLE_PERMISSIONS.length);
+  });
+});
+
 const AGENT_ID = /^agent_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 describeDb("the agents table (#3591, live DB)", () => {
@@ -172,6 +202,41 @@ describeDb("the agents table (#3591, live DB)", () => {
     });
   });
 
+  describe("grants (#7864 D2, AC-2)", () => {
+    async function grantsOf(id: string): Promise<string[]> {
+      return (
+        await db.query<{ grants: string[] }>(
+          `SELECT "grants" FROM "agents" WHERE "id" = $1`,
+          [id],
+        )
+      ).rows[0]!.grants;
+    }
+
+    it("a new agent has no grants", async () => {
+      expect(await grantsOf(await insertAgent())).toEqual([]);
+    });
+
+    it("takes grantable permissions", async () => {
+      const id = await insertAgent();
+      await db.query(
+        `UPDATE "agents" SET "grants" = ARRAY['content-edit','magnets-manage']::TEXT[] WHERE "id" = $1`,
+        [id],
+      );
+      expect(await grantsOf(id)).toEqual(["content-edit", "magnets-manage"]);
+    });
+
+    it("refuses any other permission", async () => {
+      const id = await insertAgent();
+      await expect(
+        db.query(
+          `UPDATE "agents" SET "grants" = ARRAY['content-edit','agents-manage']::TEXT[] WHERE "id" = $1`,
+          [id],
+        ),
+      ).rejects.toThrow(/agents_grants_allowed/);
+      expect(await grantsOf(id)).toEqual([]);
+    });
+  });
+
   it("a credential digest is unique", async () => {
     const hash = nextHash();
     await insertAgent({ credential_hash: hash });

package/templates/database/__tests__/lead-idempotency-key.db.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @file lead-idempotency-key.db.test.ts
+ *
+ * LIVE-DATABASE proof of the lead idempotency key (#7869, spec
+ * docs/specs/7869-lead-idempotency-key-spec.md D8, D10 cases 15–17; AC-4).
+ * Requires DATABASE_URL pointing at a Postgres with the migrations applied —
+ * the whole suite SKIPS when DATABASE_URL is unset, keeping the workspace
+ * Jest run DB-free (the repo convention; the `apps/api Route Tests
+ * (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `spoke-registry.db.test.ts` does. What it
+ * proves that a mock cannot — the unique index
+ * `leads_workspace_id_idempotency_key_key` itself:
+ *   15. One key twice in one workspace: the second insert fails (23505).
+ *   16. One key in two workspaces: both inserts succeed.
+ *   17. Two keyless (NULL) leads in one workspace: both succeed.
+ */
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+describeDb("the lead idempotency key (#7869, live DB)", () => {
+  let db: Client;
+  let workspaceA: string;
+  let workspaceB: string;
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+
+    const org = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "organizations" ("name", "slug", "updated_at")
+         VALUES ('Lead Idempotency Org', 'idem7869-org', now()) RETURNING "id"`,
+      )
+    ).rows[0]!;
+    const workspace = async (slug: string) =>
+      (
+        await db.query<{ id: string }>(
+          `INSERT INTO "workspaces" ("organization_id", "name", "slug", "updated_at")
+           VALUES ($1, $2, $2, now()) RETURNING "id"`,
+          [org.id, slug],
+        )
+      ).rows[0]!.id;
+    workspaceA = await workspace("idem7869-ws-a");
+    workspaceB = await workspace("idem7869-ws-b");
+  });
+
+  afterAll(async () => {
+    await db.query(`DELETE FROM "leads" WHERE "source" = 'idem7869'`);
+    await db.query(`DELETE FROM "organizations" WHERE "slug" = 'idem7869-org'`);
+    await db.end();
+  });
+
+  /** Insert one lead; the database mints its id. */
+  const insertLead = (workspaceId: string, idempotencyKey: string | null) =>
+    db.query(
+      `INSERT INTO "leads" ("site_id", "workspace_id", "source", "email", "payload", "idempotency_key")
+       VALUES ($1, $1, 'idem7869', 'visitor@example.com', '{}', $2)`,
+      [workspaceId, idempotencyKey],
+    );
+
+  it("case 15 — one key twice in one workspace: the second insert fails with 23505", async () => {
+    await insertLead(workspaceA, "idem7869-key-same-workspace");
+    await expect(
+      insertLead(workspaceA, "idem7869-key-same-workspace"),
+    ).rejects.toMatchObject({
+      code: "23505",
+      constraint: "leads_workspace_id_idempotency_key_key",
+    });
+  });
+
+  it("case 16 — the same key in two workspaces: both inserts succeed", async () => {
+    await insertLead(workspaceA, "idem7869-key-two-workspaces");
+    await insertLead(workspaceB, "idem7869-key-two-workspaces");
+    const { rows } = await db.query<{ n: string }>(
+      `SELECT count(*) AS n FROM "leads" WHERE "idempotency_key" = 'idem7869-key-two-workspaces'`,
+    );
+    expect(rows[0]!.n).toBe("2");
+  });
+
+  it("case 17 — two keyless leads in one workspace: both succeed (NULLs are distinct)", async () => {
+    await insertLead(workspaceA, null);
+    await insertLead(workspaceA, null);
+    const { rows } = await db.query<{ n: string }>(
+      `SELECT count(*) AS n FROM "leads"
+       WHERE "source" = 'idem7869' AND "workspace_id" = $1 AND "idempotency_key" IS NULL`,
+      [workspaceA],
+    );
+    expect(rows[0]!.n).toBe("2");
+  });
+});