create-ailk 0.14.0 → 0.16.0

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

@@ -28,11 +28,22 @@
  *   - 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";
 
+import { browserApiOrigin } from "./api-origin.generated";
+
 type RelayMethod = "GET" | "POST";
 
 /** One relayed (method, path) pair. */
@@ -78,13 +89,197 @@ 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 };
+}
+
 /**
  * True when the site has an API address to forward to. `getApiBase()` falls
  * back to `http://localhost:3001` for local development; a production site
@@ -94,7 +289,7 @@ function hubConfigured(): boolean {
   if (process.env.NODE_ENV !== "production") return true;
   return Boolean(
     process.env.AILK_API_URL ||
-      process.env.NEXT_PUBLIC_AILK_API_URL ||
+      browserApiOrigin() ||
       process.env.NEXT_PUBLIC_API_URL,
   );
 }
@@ -220,6 +415,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/server-api.ts

@@ -24,6 +24,9 @@
 
 import { cookies, headers } from "next/headers";
 
+import { hubSessionInit } from "./hub-session/session";
+import { SIGN_IN_PROVIDER } from "./topology.generated";
+
 /**
  * Structural mirror of `@working-theory/api-client`'s `ApiResult<T>`
  * (`packages/api-client/src/http.ts`) — not imported, because that type is
@@ -75,10 +78,17 @@ interface ErrorBody {
  * pass the check exactly as a browser-originated one would. RSC `GET`s are
  * unaffected: `isOriginAllowed` short-circuits `true` for safe methods before
  * it ever inspects the header.
+ *
+ * On a spoke that signs in through its hub (`SIGN_IN_PROVIDER === "hub"`,
+ * #7894 D12) this is the ONE request-init re-target: it returns the hub
+ * credential as `Authorization: Bearer` (`hubSessionInit`), and no header at
+ * all signed out — the hub has no cookie session for this site's visitor.
+ * Every caller passes the result straight to the api-client unchanged.
  */
 export async function forwardedCookieInit(): Promise<{
-  headers: { cookie: string; origin?: string };
+  headers: Record<string, string>;
 }> {
+  if (SIGN_IN_PROVIDER === "hub") return hubSessionInit();
   const cookieHeader = (await cookies()).toString();
   const origin = (await headers()).get("origin");
   return { headers: { cookie: cookieHeader, ...(origin ? { origin } : {}) } };

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,33 @@
+// 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 database of its own: by default it
+// has no sign-in, so its render reads no session and imports nothing; with
+// `--hub-sign-in` (#7894) it reads the sealed hub-session cookie.
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+export const SIGN_IN_ENABLED: boolean = true;
+export const SIGN_IN_PROVIDER: "site" | "hub" | "none" = "site";
+export const SIGN_IN_PATH: string | null = "/sign-in";
+export const SIGN_UP_PATH: string | null = "/sign-up";
+export const SIGN_OUT_ENDPOINT: string | null = null;
+
+export type SiteSession = {
+  user: {
+    name?: string | null;
+    email: string;
+    emailVerified: boolean;
+    createdAt?: Date | string | null;
+  };
+} | null;
+
+export async function readSession(headers: Headers): Promise<SiteSession> {
+  const { auth } = await import("../auth");
+  return auth.api.getSession({ headers });
+}
+
+export async function registerSiteStores(): Promise<void> {
+  const { registerLicenseKeyStore } = await import("./license-key-store");
+  await registerLicenseKeyStore();
+}

package/templates/apps/web/messages/en.json

@@ -303,6 +303,16 @@
       "ctaLabel": "Back to services"
     }
   },
+  "checkoutThankYou": {
+    "title": "Thank you",
+    "body": "Your payment went through. We'll email you a receipt and the next steps."
+  },
+  "checkoutUnavailable": {
+    "title": "Checkout isn't available right now",
+    "body": "Nothing was charged. Please try again in a few minutes.",
+    "ctaHeadline": "Need a hand?",
+    "ctaLabel": "Contact us"
+  },
   "resources": {
     "heading": "Resources",
     "emptyState": "Resources listing coming soon."
@@ -649,7 +659,8 @@
         "unsaved": "Unsaved changes",
         "clean": "No unsaved changes",
         "nameRequired": "Enter your name.",
-        "saveError": "We couldn't save your name. Try again."
+        "saveError": "We couldn't save your name. Try again.",
+        "manageOnHub": "Manage your account on our main site"
       },
       "security": {
         "title": "Security",
@@ -660,7 +671,8 @@
         "magicLink": "Email sign-in link",
         "password": "Password",
         "available": "Available",
-        "none": "No sign-in method is configured."
+        "none": "No sign-in method is configured.",
+        "viaHub": "You sign in through our main site. Your sign-in methods are managed there."
       },
       "notifications": {
         "title": "Notifications",
@@ -696,7 +708,10 @@
       "emptyHeadline": "Sign-in isn't available yet",
       "emptyDescription": "This site hasn't turned on sign-in for members yet. Check back soon, or contact the site owner.",
       "signInLink": "Go to the sign-in page",
-      "homeLink": "Back to the site"
+      "homeLink": "Back to the site",
+      "hubHeadline": "Sign in to your account",
+      "hubDescription": "You sign in on our main site, then come straight back here.",
+      "hubSignIn": "Sign in"
     },
     "profile": {
       "email": "Email",
@@ -718,6 +733,20 @@
       "period": "Period",
       "date": "Date"
     },
+    "pieces": {
+      "heading": "My pieces",
+      "type": "Piece",
+      "stage": "Stage",
+      "createdAt": "Started",
+      "updatedAt": "Updated",
+      "needsClient": "This piece is waiting on you."
+    },
+    "messages": {
+      "heading": "My messages",
+      "sentAt": "Sent",
+      "file": "File",
+      "download": "Download {filename}"
+    },
     "subscription": {
       "headline": "Your payment didn't go through",
       "action": "Update payment method"

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,56 @@
 # @working-theory/database
 
+## 0.38.0
+
+### Minor Changes
+
+- [#8037](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8037) [`89eba8c`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/89eba8c2bab16766a68284f52c872aae86f59fde) Thanks [@samuelhenry](https://github.com/samuelhenry)! - The member area contract ([#7877](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/7877)): a client's pieces, plan and messages.
+
+  - `@working-theory/database` — `Piece` and `Interaction` on Person (a composite `(person_id, workspace_id)` foreign key to `people`) and `WorkspacePieceStages`, a workspace's declared piece stages; migration `20261011120000_member_area`.
+  - `@working-theory/ids` — the `piece_`, `intx_` and `pstages_` prefixes; `zPieceId` and `zInteractionId`.
+  - `@working-theory/validation` — the member-area wire schemas (`pieces.ts`, `member.ts`), the Person timeline's `message` kind, the `people-write` permission (owner, admin; not agent-grantable) and the attachment helpers (`ATTACHABLE_CONTENT_TYPES`, `attachmentFilename`).
+  - `@working-theory/api-client` — `member.pieces`, `member.messages` and `member.messageFile` (with `getRaw`), the reads a spoke's server makes for its signed-in client. A spoke that re-serves a file sends its five response headers unchanged.
+  - `create-ailk` — the member-area files are co-owned by the `workspace` and `multi-tenant` slices.
+
+- [#8049](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8049) [`6a2a120`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/6a2a120765c423303716d5e3ebf216c9c10e118b) Thanks [@samuelhenry](https://github.com/samuelhenry)! - An agent key may be granted `member-pieces-manage` ([#7878](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/7878)).
+
+  `@working-theory/validation`: the `member-pieces-manage` permission (owner, admin), the seventh entry of `AGENT_GRANTABLE_PERMISSIONS`. The member area's operator writes — a client's pieces, plan and outbound messages — check it through `allows`, so an agent granted it keeps them in its one workspace; `people-write` stays never-grantable. `@working-theory/database`: the `agents_grants_allowed` CHECK widened to admit it (additive).
+
+- [#8004](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8004) [`d9ba65f`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/d9ba65f6334681b17bd77b64bb7ca9e069b1980f) Thanks [@claudio-planck](https://github.com/claudio-planck)! - Person — the per-workspace client record ([#852](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/852)).
+
+  `@working-theory/database`: a `Person` model (one client per normalized email per workspace), `personId` on `Lead` and `Appointment`, the schema and set-based backfill migrations, the post-cutover re-run script `scripts/person-backfill.sql`, the agent-grant CHECK widened to admit `people-read`, and the timeline's email-fallback SQL constants on the `tenancy` subpath. `@working-theory/ids`: the `person_` prefix and `zPersonId`. `@working-theory/validation`: the `people-read` permission (owner, admin; agent-grantable) and the People wire schemas. `@working-theory/api-client`: `people.list` and `people.get` for an agent key granted `people-read`.
+
+### Patch Changes
+
+- Updated dependencies [[`89eba8c`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/89eba8c2bab16766a68284f52c872aae86f59fde), [`6a2a120`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/6a2a120765c423303716d5e3ebf216c9c10e118b), [`6d38b1a`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/6d38b1a5362b36e56d6bce79fdf96c878020cb18), [`d9ba65f`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/d9ba65f6334681b17bd77b64bb7ca9e069b1980f)]:
+  - @working-theory/validation@0.38.0
+  - @working-theory/ids@0.11.0
+
+## 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,43 @@
  *   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 seven
+ *      grantable permissions (`people-read` since #852 D9,
+ *      `member-pieces-manage` since #7878), and the `agents_grants_allowed`
+ *      CHECK refuses anything else.
+ *
+ * One case needs no database and always runs: the latest 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;
 
+// #7878 — the CHECK as it stands now: the latest migration that re-adds it.
+const GRANTS_MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261011130000_agent_grants_member_pieces_manage",
+  "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 +204,59 @@ 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("takes people-read (#852 D9)", async () => {
+      const id = await insertAgent();
+      await db.query(
+        `UPDATE "agents" SET "grants" = ARRAY['people-read']::TEXT[] WHERE "id" = $1`,
+        [id],
+      );
+      expect(await grantsOf(id)).toEqual(["people-read"]);
+    });
+
+    it("takes member-pieces-manage (#7878)", async () => {
+      const id = await insertAgent();
+      await db.query(
+        `UPDATE "agents" SET "grants" = ARRAY['member-pieces-manage','people-read']::TEXT[] WHERE "id" = $1`,
+        [id],
+      );
+      expect(await grantsOf(id)).toEqual(["member-pieces-manage", "people-read"]);
+    });
+
+    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 });