create-ailk 0.14.0 → 0.16.0

package/templates/database/migrations/20261011120000_member_area/migration.sql

@@ -0,0 +1,158 @@
+-- #7877 — the member area contract (spec
+-- docs/specs/7877-the-member-area-contract-a-spec.md D1, D2, D3).
+--
+--   pieces (inbox)       — one deliverable for one client: a title, a stage
+--                          drawn from the workspace's declared list, a
+--                          needs-client flag. Written only through
+--                          apps/api's tenantDb(tenant).memberArea.
+--   interactions (inbox) — one outbound message on the 'member' channel to
+--                          one client, optionally carrying a workspace
+--                          library asset. The original CRM spec's
+--                          Interaction table cut to one channel and one
+--                          direction; an inbound reply is a later second
+--                          direction value on this table.
+--   workspace_piece_stages (config) — a workspace's declared piece stages,
+--                          in order, one row per workspace. No row means the
+--                          product default, which lives in apps/api only.
+--   people_id_workspace_id_key — a unique index over a pair the PK already
+--                          makes unique: the target of the composite
+--                          (person_id, workspace_id) foreign keys, so "a
+--                          Person of the same workspace" is a database fact.
+--
+-- Both foreign keys stay inside the inbox namespace (ADR 0009 invariant 1).
+-- workspace_id, asset_id, created_by and updated_by name rows of other
+-- namespaces: plain columns with format CHECKs, no foreign key. Neither new
+-- inbox table carries an email.
+--
+-- PURELY ADDITIVE, DDL ONLY: three new tables and one unique index on
+-- "people". No existing row changes. The unique index builds under the
+-- file's transaction, holding a SHARE lock on "people" (writes wait, reads do
+-- not) for one scan of a table that is one row per client.
+--
+-- Rollout: deploy this migration BEFORE the API code that reads or writes
+-- these tables; code without them fails every member-area read and write.
+--
+-- Rollback: DROP TABLE "interactions"; DROP TABLE "pieces"; DROP TABLE
+-- "workspace_piece_stages"; DROP INDEX "people_id_workspace_id_key"; (the
+-- indexes, foreign keys and CHECKs go with them). Safe while nothing but
+-- #7877's own code reads them.
+
+-- CreateTable
+CREATE TABLE "workspace_piece_stages" (
+    "id" TEXT NOT NULL DEFAULT ('pstages_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "stages" TEXT[],
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "workspace_piece_stages_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "pieces" (
+    "id" TEXT NOT NULL DEFAULT ('piece_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "title" VARCHAR(200) NOT NULL,
+    "stage" VARCHAR(40) NOT NULL,
+    "needs_client" BOOLEAN NOT NULL DEFAULT false,
+    "updated_by" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "pieces_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "interactions" (
+    "id" TEXT NOT NULL DEFAULT ('intx_'::text || (uuidv7())::text),
+    "workspace_id" TEXT NOT NULL,
+    "person_id" TEXT NOT NULL,
+    "channel" VARCHAR(16) NOT NULL,
+    "direction" VARCHAR(16) NOT NULL,
+    "subject" VARCHAR(200) NOT NULL,
+    "body" TEXT NOT NULL,
+    "asset_id" TEXT,
+    "created_by" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "read_at" TIMESTAMP(3),
+
+    CONSTRAINT "interactions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- One stage list per workspace — the WorkspaceMeetings shape.
+CREATE UNIQUE INDEX "workspace_piece_stages_workspace_id_key" ON "workspace_piece_stages"("workspace_id");
+
+-- CreateIndex
+-- A client's pieces: workspace_id = $1 AND person_id = $2 ORDER BY created_at DESC.
+CREATE INDEX "pieces_workspace_id_person_id_created_at_idx" ON "pieces"("workspace_id", "person_id", "created_at");
+
+-- CreateIndex
+-- A client's messages, the same read shape as pieces.
+CREATE INDEX "interactions_workspace_id_person_id_created_at_idx" ON "interactions"("workspace_id", "person_id", "created_at");
+
+-- CreateIndex
+-- The public asset read's "is this asset attached to any message" count (D18).
+CREATE INDEX "interactions_asset_id_idx" ON "interactions"("asset_id");
+
+-- CreateIndex
+-- Redundant with the PK; the composite foreign keys below need it as their target.
+CREATE UNIQUE INDEX "people_id_workspace_id_key" ON "people"("id", "workspace_id");
+
+-- AddForeignKey
+-- A piece names a Person of ITS OWN workspace; deleting a Person with a piece is refused.
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+-- The same rule for a message.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_person_fk" FOREIGN KEY ("person_id", "workspace_id") REFERENCES "people"("id", "workspace_id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- ADR-0031 rule 3 — pieces: piece_, interactions: intx_,
+-- workspace_piece_stages: pstages_ (registered in
+-- packages/ids/src/registry.ts; this migration's path is added to
+-- migration-sync.test.ts's PK_CHECK_MIGRATIONS). Each reference column
+-- carries the format CHECK of the entity it names, in the person-migration
+-- shape.
+ALTER TABLE "pieces" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "pieces" ALTER COLUMN "id" SET DEFAULT ('piece_'::text || (uuidv7())::text);
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_id_format" CHECK ("id" ~ '^piece_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_workspace_id_format" CHECK ("workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_person_id_format" CHECK ("person_id" ~ '^person_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_updated_by_format" CHECK ("updated_by" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+ALTER TABLE "interactions" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "interactions" ALTER COLUMN "id" SET DEFAULT ('intx_'::text || (uuidv7())::text);
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_id_format" CHECK ("id" ~ '^intx_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_workspace_id_format" CHECK ("workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_person_id_format" CHECK ("person_id" ~ '^person_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_created_by_format" CHECK ("created_by" ~ '^user_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_asset_id_format" CHECK ("asset_id" ~ '^asset_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+ALTER TABLE "workspace_piece_stages" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "workspace_piece_stages" ALTER COLUMN "id" SET DEFAULT ('pstages_'::text || (uuidv7())::text);
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_id_format" CHECK ("id" ~ '^pstages_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_workspace_id_format" CHECK ("workspace_id" ~ '^wksp_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+-- A piece's title is 1–200 characters once trimmed; a stage is a slug. Which
+-- slugs a workspace accepts is its declared list, checked at write time by
+-- the API — never an enum here or in packages/validation.
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_title_length"
+  CHECK (char_length(btrim("title")) BETWEEN 1 AND 200);
+ALTER TABLE "pieces" ADD CONSTRAINT "pieces_stage_format"
+  CHECK ("stage" ~ '^[a-z0-9][a-z0-9-]{0,39}$');
+
+-- One channel and one direction in this slice. An inbound reply widens
+-- interactions_direction_allowed in its own migration.
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_channel_allowed"
+  CHECK ("channel" = 'member');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_direction_allowed"
+  CHECK ("direction" = 'outbound');
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_subject_length"
+  CHECK (char_length(btrim("subject")) BETWEEN 1 AND 200);
+ALTER TABLE "interactions" ADD CONSTRAINT "interactions_body_length"
+  CHECK (char_length(btrim("body")) BETWEEN 1 AND 10000);
+
+-- A declared list holds 1–20 stages (never NULL: no row is the default).
+ALTER TABLE "workspace_piece_stages" ADD CONSTRAINT "workspace_piece_stages_count"
+  CHECK ("stages" IS NOT NULL AND cardinality("stages") BETWEEN 1 AND 20);

package/templates/database/migrations/20261011130000_agent_grants_member_pieces_manage/migration.sql

@@ -0,0 +1,21 @@
+-- #7878 — an agent key may be granted member-pieces-manage: a client's
+-- pieces, plan and outbound messages (#7877's operator writes).
+--
+-- Widens the agents_grants_allowed CHECK from the six #852 permissions to
+-- seven. The CHECK names the same seven as @working-theory/validation's
+-- AGENT_GRANTABLE_PERMISSIONS; database/__tests__/agents.db.test.ts reads
+-- this file and fails if the two lists differ (SEC-7864-G).
+--
+-- PURELY ADDITIVE in effect: the new CHECK admits every row the old one
+-- admitted, so re-adding it cannot fail on existing data. No row changes.
+--
+-- Rollback: ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+-- then re-add the six-id CHECK from 20261010130000_agent_grants_people_read.
+-- That re-add FAILS while any row holds member-pieces-manage — remove those
+-- grants first.
+
+ALTER TABLE "agents" DROP CONSTRAINT "agents_grants_allowed";
+
+-- Only the seven grantable permissions may be stored.
+ALTER TABLE "agents" ADD CONSTRAINT "agents_grants_allowed"
+  CHECK ("grants" <@ ARRAY['content-edit','content-publish','assets-write','magnets-manage','meeting-types-manage','people-read','member-pieces-manage']::TEXT[]);

package/templates/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@working-theory/database",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/templates/database/scripts/person-backfill.sql

@@ -0,0 +1,132 @@
+-- #852 — the Person backfill (spec
+-- docs/specs/852-person-the-per-workspace-client-spec.md D2, D4).
+--
+-- Fills "people" from the rows the hub already holds and stamps
+-- leads.person_id and appointments.person_id, so the People list is not
+-- empty on the day it ships. Set-based and idempotent: every insert is
+-- ON CONFLICT DO NOTHING and every update is guarded by IS NULL, so running
+-- this text twice changes nothing the first run wrote.
+--
+-- THE SAME TEXT, byte for byte, is database/scripts/person-backfill.sql. The
+-- previous deployment keeps writing leads and appointments without a
+-- person_id between this migration and the cutover to the new code; run
+-- that script ONCE against the hub database after the cutover to stamp them.
+-- database/__tests__/person.db.test.ts asserts the two files are identical
+-- and that a second run changes no row.
+--
+-- Normalization — the SQL twin of apps/api/src/services/person.ts's
+-- normalizePersonEmail / isStorablePersonEmail:
+--   N(x)     = lower(btrim(x, E' \t\n\r\f\x0B') COLLATE "C")
+--              (\x0B is vertical tab; an E-string has no \v escape — E'\v'
+--              is the letter v, which would strip the v of every .dev)
+--   VALID(e) = e ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(e) <= 254
+--   NAME(x)  = C0/C1 controls and bidi controls removed, trimmed, cut to
+--              200 characters; empty → NULL
+-- A row whose email is not VALID makes no Person and keeps person_id NULL.
+--
+-- Sources, in order: leads (oldest first), then completed hub FlowCheckouts
+-- through their lead (the customer id, first writer wins), then appointments
+-- by attendee email. Subscriber is NOT a source; FlowSession, ProjectListing
+-- and DeliverableGrant reach a Person through their lead at read time.
+-- The join to "users" reads the auth namespace inside this one-off
+-- statement only; it adds no foreign key (ADR 0009 invariant 1).
+--
+-- Rollback: nothing to undo on its own — dropping 20261010120000_person's
+-- table and columns removes everything this wrote.
+
+-- 1. Leads, oldest first: one Person per (workspace, normalized email). The
+--    name is the oldest lead's payload.name when it is a JSON string.
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+       l."workspace_id",
+       lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+       CASE WHEN jsonb_typeof(l."payload" -> 'name') = 'string'
+            THEN NULLIF(left(btrim(regexp_replace(l."payload" ->> 'name', '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), '')
+       END,
+       l."created_at",
+       now()
+FROM "leads" l
+WHERE lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"), l."created_at" ASC, l."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 2. Hub FlowCheckouts, through their lead (same workspace): the oldest
+--    completed checkout with a customer id writes it onto a Person that has
+--    none. First writer wins — oldest by completed_at, then created_at, then id.
+UPDATE "people" p
+SET "billing_provider" = 'stripe',
+    "billing_customer_id" = c."stripe_customer_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         fc."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         fc."stripe_customer_id"
+  FROM "flow_checkouts" fc
+  JOIN "leads" l ON l."id" = fc."lead_id" AND l."workspace_id" = fc."workspace_id"
+  WHERE fc."status" = 'completed'
+    AND fc."stripe_customer_id" IS NOT NULL
+    AND fc."stripe_customer_id" <> ''
+    AND length(fc."stripe_customer_id") <= 255
+  ORDER BY fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           fc."completed_at" ASC NULLS LAST, fc."created_at" ASC, fc."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."billing_customer_id" IS NULL;
+
+-- 3. Appointments, by attendee email: a Person a lead already made keeps its
+--    lead-derived name and created_at (ON CONFLICT DO NOTHING).
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"))
+       a."workspace_id",
+       lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"),
+       NULLIF(left(btrim(regexp_replace(a."attendee_name", '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), ''),
+       a."created_at",
+       now()
+FROM "appointments" a
+WHERE lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"), a."created_at" ASC, a."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 4. Stamps: every lead and appointment with a storable email points at its
+--    workspace's Person; a row already stamped is left alone.
+UPDATE "leads"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "leads"."person_id" IS NULL
+  AND p."workspace_id" = "leads"."workspace_id"
+  AND p."email" = lower(btrim("leads"."email", E' \t\n\r\f\x0B') COLLATE "C");
+
+UPDATE "appointments"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "appointments"."person_id" IS NULL
+  AND p."workspace_id" = "appointments"."workspace_id"
+  AND p."email" = lower(btrim("appointments"."attendee_email", E' \t\n\r\f\x0B') COLLATE "C");
+
+-- 5. user_id, verified only: the oldest promoted lead (by promoted_at, then
+--    created_at, then id) whose user is email-verified and whose verified
+--    address normalizes to the Person's. An unverified or differing user is
+--    never copied — the rule stampPersonUser applies to new rows.
+UPDATE "people" p
+SET "user_id" = c."user_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         l."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         l."promoted_user_id" AS "user_id"
+  FROM "leads" l
+  JOIN "users" u ON u."id" = l."promoted_user_id"
+  WHERE l."promoted_user_id" IS NOT NULL
+    AND u."email_verified" = true
+    AND lower(btrim(u."email", E' \t\n\r\f\x0B') COLLATE "C") = lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")
+  ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           l."promoted_at" ASC NULLS LAST, l."created_at" ASC, l."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."user_id" IS NULL;

package/templates/database/tenancy.ts

@@ -128,3 +128,56 @@ export async function resolveSentinelWorkspaceRow(
   }
   return { id: DEFAULT_WORKSPACE_ID, organizationId: workspace.organizationId };
 }
+
+// ---------------------------------------------------------------------------
+// #852 D7 — the Person timeline's pre-migration email fallback.
+//
+// A FlowSession or ProjectListing written before the Person backfill and
+// never tied to a lead (`lead_id IS NULL`) reaches its Person only by email.
+// These three SQL texts are the ONLY way that match is made: run by
+// `apps/api/src/lib/tenant-db.ts`'s `people.timeline` through
+// `$queryRawUnsafe(SQL, email, workspaceId, cutoff)`, and executed verbatim
+// against live Postgres by `database/__tests__/person.db.test.ts` — one
+// string, proven where it runs. `$n` placeholders only, never interpolation.
+//
+// The match is EXACT equality of the normalized column against the Person's
+// stored (already-normalized) email — never Prisma's `mode: "insensitive"`,
+// which compiles to ILIKE: `_`/`%` would act as wildcards and non-ASCII case
+// would fold, joining another client's rows (SEC-852-B). The normalization is
+// the backfill's N(x) (database/migrations/20261010121000_person_backfill).
+//
+// `$3` is the cutoff: `finished_at` of the backfill migration's
+// `_prisma_migrations` row (`PERSON_CUTOFF_SQL`). That column is timestamptz;
+// the inbox `created_at` columns are timestamp(3) holding UTC (Prisma's
+// convention), so the comparison converts the cutoff to UTC wall time. Only
+// rows strictly older than the cutoff qualify. Each returns ids only, at most
+// 50, newest first; the caller re-reads them through its scoped findMany.
+// ---------------------------------------------------------------------------
+
+/** The `_prisma_migrations` key whose `finished_at` is the fallback cutoff. */
+export const PERSON_BACKFILL_MIGRATION = "20261010121000_person_backfill";
+
+/** `$1` = the Person's email, `$2` = workspace id, `$3` = the cutoff. */
+export const PERSON_FALLBACK_FLOW_SESSIONS_SQL = String.raw`SELECT "id" FROM "flow_sessions"
+WHERE "workspace_id" = $2::text
+  AND "lead_id" IS NULL
+  AND "created_at" < ($3::timestamptz AT TIME ZONE 'UTC')
+  AND lower(btrim("email", E' \t\n\r\f\x0B') COLLATE "C") = $1::text
+ORDER BY "created_at" DESC, "id" DESC
+LIMIT 50`;
+
+/** `$1` = the Person's email, `$2` = workspace id, `$3` = the cutoff. */
+export const PERSON_FALLBACK_PROJECT_LISTINGS_SQL = String.raw`SELECT "id" FROM "project_listings"
+WHERE "workspace_id" = $2::text
+  AND "lead_id" IS NULL
+  AND "created_at" < ($3::timestamptz AT TIME ZONE 'UTC')
+  AND lower(btrim("founder_email", E' \t\n\r\f\x0B') COLLATE "C") = $1::text
+ORDER BY "created_at" DESC, "id" DESC
+LIMIT 50`;
+
+/** The cutoff read: the backfill's `finished_at`, or no row when it has not run. */
+export const PERSON_CUTOFF_SQL = `SELECT "finished_at" FROM "_prisma_migrations"
+WHERE "migration_name" = '20261010121000_person_backfill'
+  AND "finished_at" IS NOT NULL
+  AND "rolled_back_at" IS NULL
+LIMIT 1`;

package/templates/tools/check-declared-env.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env tsx
+/**
+ * Declared-env check — fails when this site's code reads an environment
+ * variable that `project.yaml` does not declare.
+ *
+ * Every literal `process.env` read in the site's source (tests, stories and
+ * this `tools/` directory excepted) needs a row in `project.yaml`'s
+ * `env_contract` block: a `name`, a one-line `description`, and
+ * `secret: true` or `false`. Platform names (`NODE_ENV`, `CI`, `VERCEL_*`, …)
+ * need none. On a spoke (`.ailk-site-manifest.json` records
+ * `"topology": "spoke"`), `NEXT_PUBLIC_AILK_API_URL` is refused outright:
+ * a spoke's hub origin is server-only, so read `AILK_API_URL` instead.
+ *
+ * The scanner is `tools/declared-env.ts`, a copy of create-ailk's own, which
+ * writes this site's rows when it adds a module or a route. Add a row by hand
+ * for a variable you add; create-ailk never edits or removes one.
+ *
+ * Usage:
+ *   pnpm env:declared          # or: tsx tools/check-declared-env.ts
+ *
+ * Exit codes:
+ *   0 — every read is declared
+ *   1 — an undeclared read, a malformed row, a refused name, or a missing file
+ */
+
+import { dirname, resolve } from "node:path";
+
+import { checkDeclaredEnv } from "./declared-env";
+
+const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
+
+const { findings, summary } = checkDeclaredEnv(ROOT);
+if (findings.length > 0) {
+  for (const finding of findings) console.error(finding);
+  process.exit(1);
+}
+console.log(summary);