@alvera-ai/platform-sdk 0.17.0 → 0.18.0-next.g49897f5

package/.agent/AGENTS.md

@@ -88,7 +88,7 @@ corpus page documents the surface you already know:
 | Host                  | The platform itself          | This corpus + `account_management.md`         |
 | Client                | Data Activation Client       | `data_activation_clients.md`                  |
 | Server                | Agentic Workflow             | `workflows.md`                                |
-| Resources             | Datasets (per data domain)   | `generic_tables.md`, `mdm.md`                |
+| Resources             | Datasets + generic tables    | `generic_tables.md`, `mdm.md`                |
 | Prompts               | Interoperability Contracts   | `interoperability_contracts.md`, `templates.md` |
 | Sampling              | Dataset event triggers       | `data_activation_clients.md` §6.4 logs        |
 | Tools                 | Tool Calls (polymorphic body)| `tools.md`                                    |
@@ -231,17 +231,16 @@ What changes between them is only *where you put the calls* (a component
 handler vs. a test body), never the calls themselves. The cookbooks under
 `cookbook/` read as test-style sequences because that is how they are
 validated, but every step is a plain `api.*` call you can lift into an app
-unchanged. The per-capability docs (e.g. `bulk-ingest.md`, `ai-agent-invoke.md`)
-show one capability at a time; the cookbooks weave capabilities into a
-business outcome.
+unchanged. Capabilities are not documented separately — each lives as
+numbered steps inside the cookbook whose use case motivates it.
 
 ## Resources
 
 ```
    INFRASTRUCTURE  (stood up before data flows)
    ──────────────
-   datalakes.md                  Storage layer; regulated +
-                                  unregulated tiers.
+   datalakes.md                  Storage layer; the raw lake and
+                                  its tokenized + redacted copies.
    data_sources.md               External ingestion endpoints.
    tools.md                      Authenticated connections for
                                   action execution.
@@ -260,6 +259,10 @@ business outcome.
    DATA ACTIVATION  (how data flows in)
    ───────────────
    generic_tables.md            Schema-on-write tables.
+   advanced_migrations.md       Hand-written DDL for one lake —
+                                  indexes, foreign keys, anything
+                                  past the CREATE TABLE / ADD COLUMN
+                                  the platform writes for itself.
    interoperability_contracts.md Liquid template mappings.
    data_activation_clients.md    Ingestion pipelines — both the
                                   binding row (CRUD) and the
@@ -299,6 +302,7 @@ wire name (snake_case):
     api.connectedApps                   connected_apps.md
     api.mdm                             mdm.md
     api.genericTables                   generic_tables.md
+    api.advancedMigrations              advanced_migrations.md
     api.interoperabilityContracts       interoperability_contracts.md
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md
@@ -323,12 +327,17 @@ at runtime.
 
 Each cookbook structure:
 
-- **Front matter** — `title`, `summary`, `industry`, `slug`,
+- **Front matter** — `title`, `summary`, `use_case`, `slug`,
   `vitest_source` (list of integration-test files the snippets
-  are lifted from, anchor file first), `status`. The `industry:`
-  field also drives automatic discovery of the per-industry
-  bootstrap setup file at `_setup/<industry>.md` — see
-  "Industry-derived setup files" below.
+  are lifted from, anchor file first), `status`. `use_case` is one
+  of the four surfaces — `organic-marketing`,
+  `subscription-saas`, `payments-compliance`,
+  `primary-care-feedback` — and there is exactly one cookbook per use
+  case. Three are at `cookbook/<use-case>.md`; the fourth is at
+  `cookbook/primary-care.md`, because `use_case` tracks the integration
+  suite it is lifted from (`integration-tests/tests/primary-care-feedback/`)
+  and the filename does not. Read `use_case` from the front matter rather
+  than deriving it from the filename.
 - **Problem** — the business-outcome statement in domain terms,
   sourced from the anchor vitest's behaviour (not from
   customer-narrative documentation).
@@ -349,44 +358,33 @@ Each cookbook structure:
 - **See also** — links to relevant per-resource reference MDs
   and to the anchor + ancillary vitest files.
 
-### Industry-derived setup files
-
-Cookbook authoring uses per-industry bootstrap setup files
-under `.agent/cookbook/_setup/<industry>.md` to DRY out the
-auth + tenant + datalake + dataset-seeding steps every
-scenario in an industry shares. The convention matches the
-markdown-doctest ecosystem pattern — setup belongs to a
-scope (the industry), and any cookbook in that scope
-inherits the setup by being there. No per-cookbook opt-in
-field is required.
-
-- Setup files live under `_setup/`. The leading underscore on
-  the directory marks them as fragments (not standalone
-  scenarios); the validator's discovery walk skips them and
-  the corpus index does not list them under "Available
-  cookbooks."
-- The validator reads each scenario cookbook's existing
-  `industry:` front-matter field and auto-discovers the
-  setup file at `_setup/<industry>.md`. A cookbook in an
-  industry that has no setup file gets nothing inlined; the
-  validator does not fail if the setup file is absent.
-  Cookbook authors write no additional front-matter for
-  setup inclusion — the relationship is implicit, by
-  convention.
-- The validator inlines the setup file's numbered `it()`
-  blocks BEFORE the scenario's own numbered `it()` blocks
-  inside the same `describe(...)`. Each `it()` label is
-  prefixed with its source slug so failure output
-  unambiguously points at the file to open (e.g.
-  `_setup/foundation §001 — auth` versus
-  `birthday-greeting-sms-trigger §001 — create workflow`).
-  Cookbook authors keep clean local §001-§00N numbering
-  inside their own markdown.
-- An agent reading a scenario cookbook discovers the matching
-  setup file at the predictable conventional path
-  `_setup/<industry>.md` — one extra file open at a
-  fixed-by-convention location, not via cookbook-specific
-  metadata the agent has to learn.
+### Every cookbook is self-reliant, and repeats what it needs
+
+A cookbook stands up **its own** tenant, datalake and resources in
+its own numbered steps. There is no shared setup file, no setup
+group and no bootstrap phase: everything the walk depends on is
+in the walk.
+
+That means the auth + tenant + datalake preamble is **duplicated
+across all four cookbooks, deliberately.** This corpus is read by
+someone — or something — that opens one file and works through it,
+and for that reader a shared setup is not a saving. It is a second
+file to find, a second convention to learn, and a hidden dependency
+on steps they never see. Four documents repeating a preamble is the
+cheaper trade, and it is the trade this corpus makes. Do not
+re-factor it out.
+
+Two consequences worth stating plainly:
+
+- **Write for idempotence, not just for a clean run.** Use stable
+  names and create-or-reuse: look the resource up, create it only
+  if it is absent, and assert the end state either way. A step that
+  mints a fresh random name works once and litters forever —
+  nothing in the product reclaims an abandoned datalake. Ask of
+  every creating step: what does this do on run two?
+- **Label numbering is local and clean.** Each cookbook numbers its
+  own steps `§001…§00N` from the top, and a failure names the file
+  and the step directly.
 
 ### Vendored fixtures (Liquid templates, CSV bodies)
 
@@ -417,7 +415,7 @@ repo's own integration tests use.
   const LE_TEMPLATE = fs.readFileSync(
     path.join(
       process.env.COOKBOOK_FIXTURES_DIR!,
-      'foundation/_lead_submissions_foundation_legal_entity.liquid',
+      'organic-marketing/_lead_submissions_foundation_legal_entity.liquid',
     ),
     'utf8',
   )
@@ -439,109 +437,58 @@ repo's own integration tests use.
   template plus the cookbooks that depend on it. No need to
   read cookbook code first to know what fixtures exist.
 
-### Two kinds of doc here: business cookbooks vs. capability docs
+### The four cookbooks
 
-The `cookbook/` directory holds two kinds of recipe, both validated by
-`make validate-cookbook`:
+`cookbook/` holds **four files, one per use case**, and nothing else that
+runs. Each is self-reliant: it stands up its own tenant, datalake and
+resources in its own numbered steps and shares nothing with its siblings.
+A reader reads one file end to end and needs no second one. The
+duplicated bootstrap across them is deliberate — four repeated preambles
+are cheaper than one shared setup every reader must go and understand
+first.
 
-- **Business cookbooks** (`<use-case>.md`) — one real business outcome each,
-  told as a numbered API-call sequence (e.g. `welcome-sms-for-customers`,
-  `dunning-sms-for-delinquent`). Read these to see how resources compose into
-  an outcome.
-- **Capability docs** (`<capability>.md`) — one platform capability each,
-  shown as the minimal call sequence that proves it (e.g. `bulk-ingest`,
-  `ai-agent-invoke`, `generic-tables`, `invite-team`). Read these to learn one
-  capability in isolation; cookbooks weave them into outcomes.
+There is no separate per-capability file. Bulk upload, REST fetch, team
+invitations, action status updaters, paginated pollers, text-to-SQL and
+agent file-invocation each live as numbered steps inside the cookbook
+whose use case motivates them, because a capability shown without a
+reason to use it is the thing readers skip.
 
-### Available cookbooks
-
-The ten business-cookbook scenarios. Each is anchored to a green
-end-to-end vitest scenario in the platform's integration-tests suite and is
-verified at dev time by `make validate-cookbook` at the platform-sdk repo root.
-This index is mirrored into the managed block `alvera llm-export` writes to
-consumer `AGENTS.md` files (`buildManagedBlock` in both the SDK and CLI
-packages — kept in sync by hand; the llm-export test suites pin the shipped
-copy, so a dropped entry breaks a test).
+All four are verified at dev time by `make validate-cookbook` at the
+repo root; every numbered step is one test.
 
 <!-- BEGIN:cookbook-index -->
 
-**Healthcare**
-
-- [appointment-review-sms-workflow](./cookbook/appointment-review-sms-workflow.md)
-  — Send a patient review-request SMS after a fulfilled
-  appointment, deep-linked to a connected-app feedback form.
-- [contact-us-triage-with-llm](./cookbook/contact-us-triage-with-llm.md)
-  — Triage inbound contact-us messages into three priority
-  buckets (appointment / job-application / spam) via an LLM
-  agent, route each to a tailored SMS action.
-
-**Subscription**
-
-- [welcome-sms-for-customers](./cookbook/welcome-sms-for-customers.md)
-  — Send a welcome SMS to newly contracted customers with a
-  self-serve billing-portal link.
-- [dunning-sms-for-delinquent](./cookbook/dunning-sms-for-delinquent.md)
-  — Send a payment-reminder SMS to delinquent customers
-  (filtered on phone-on-file and tax-id-verified) with a
-  pay-invoice link.
-- [triage-prospects-by-priority](./cookbook/triage-prospects-by-priority.md)
-  — Triage inbound AR customers into priority bands
-  (high / medium / low) via an LLM agent, route each band to a
-  tailored SMS action.
-
-**Payments**
-
-- [kyc-notification-on-account-activation](./cookbook/kyc-notification-on-account-activation.md)
-  — Send a KYC-notification SMS when a payment account
-  transitions to active status.
-- [sanctions-screening-with-agent-review](./cookbook/sanctions-screening-with-agent-review.md)
-  — Disambiguate gray-zone sanctions screenings via an LLM
-  agent, route confirmed-clean and confirmed-block outcomes to
-  distinct SMS actions.
-
-**Foundation**
-
-- [birthday-greeting-sms-trigger](./cookbook/birthday-greeting-sms-trigger.md)
-  — Send a happy-birthday SMS on each contact's next birthday
-  using a pure-Liquid trigger (year-roll math).
-- [score-leads-with-llm-categorization](./cookbook/score-leads-with-llm-categorization.md)
-  — Score inbound leads into four bands
-  (hot / warm / cold / spam) via an LLM agent, route each band
-  to a tailored SMS action.
-- [marketing-campaign-send](./cookbook/marketing-campaign-send.md)
-  — Send an A/B marketing campaign across SMS and email: the
-  suppression and reachability gates and the A/B split all live
-  in the workflow, each send carries a per-recipient short link,
-  and the reply re-attaches to the customer who sent it.
+- [organic-marketing](./cookbook/organic-marketing.md) — score inbound
+  leads into four bands with an LLM agent, schedule a birthday greeting a
+  year out with a pure-Liquid trigger, and run an A/B campaign whose
+  suppression gates and split live in the workflow. Ends with delivery
+  reconciliation and a natural-language read of the lake. One raw
+  datalake.
+- [payments-compliance](./cookbook/payments-compliance.md) —
+  disambiguate gray-zone sanctions screenings with an LLM agent that
+  never sees who was screened, and fire a KYC notification on account
+  activation. Ends by reading one row through raw, tokenized and redacted
+  to show what each reader gets. Three datalakes.
+- [subscription-saas](./cookbook/subscription-saas.md) — one customers
+  table and three workflows over it: a welcome SMS gated on
+  reachability, a dunning reminder gated on reachability AND KYC, and an
+  LLM agent banding accounts by priority. Then the same table filled
+  three more ways — inline, bulk CSV, REST fetch — and a teammate invited
+  onto the tenant. One raw datalake.
+- [primary-care](./cookbook/primary-care.md) — a review request that
+  only reaches patients whose visit actually happened, an LLM agent
+  triaging inbound messages off the tokenized projection, and a vision
+  agent reading a scanned document. Three datalakes.
 
 <!-- END:cookbook-index -->
 
-### Capability docs
-
-One platform capability each — the minimal call sequence that proves it,
-anchored to a green vitest scenario. Read the matching reference MD for the
-full wire shape.
-
-- [bulk-ingest](./cookbook/bulk-ingest.md) — load a whole file of records in
-  one upload (presigned link → PUT → `ingestFile` → search by batch).
-- [rest-fetch](./cookbook/rest-fetch.md) — pull records from a third-party REST
-  API on demand (Bearer + OAuth2), no file upload.
-- [ai-agent-invoke](./cookbook/ai-agent-invoke.md) — read an uploaded
-  document/image and pull structured JSON out of it (`aiAgents.invoke` with
-  files). The correct file-vision path — the agent reads the file; the DAC
-  ingests it.
-- [generic-tables](./cookbook/generic-tables.md) — stand up a generic table the
-  built-in datasets don't model; deploy → ingest → read back via executeSql.
-- [action-status-updaters](./cookbook/action-status-updaters.md) — reconcile
-  the delivery status of messages you send, on a schedule.
-- [system-templates](./cookbook/system-templates.md) — discover the platform's
-  built-in row-mapping Liquid templates.
-- [invite-team](./cookbook/invite-team.md) — invite a teammate into your tenant
-  (root / tenantless / tenant-scoped sessions in one flow).
-- [talk-to-data](./cookbook/talk-to-data.md) — turn a datalake conversational:
-  natural language → reviewable SQL (`datalakes.textToSql`, data-free by
-  construction) → read-only execution returning a `{ data, meta }` row page or a
-  CSV export (`datalakes.executeSql`).
+This index is mirrored into the managed block `alvera llm-export` writes
+to consumer `AGENTS.md` files — `buildManagedBlock`, duplicated in both
+the SDK and CLI packages and kept in sync by hand. **Both suites now
+assert every cookbook named in the block exists on disk, and that every
+cookbook on disk is named.** They previously pinned names against the
+block string alone, which is how the index went on advertising four
+deleted files without a single test failing.
 
 ## Utility namespaces
 

package/.agent/account_management.md

@@ -86,7 +86,7 @@ platform-admin side door (a root Bearer):
 ```typescript
 const { data: minted } = await rootApi.admin.createTenantApiKey(tenantSlug, {
   name: 'Bootstrap Key',
-  data_access_mode: 'unregulated',
+  data_access_mode: 'raw',
 })
 // minted.api_key — the publishable key value (thread into createSession)
 ```
@@ -329,7 +329,7 @@ What you SUBMIT when creating an invitation. The
 | Invitation `role` | Result on accept                       |
 |-------------------|----------------------------------------|
 | `'member'`        | Standard tenant user                   |
-| `'researcher'`    | Tokenized-only access; blocked from regulated schema |
+| `'researcher'`    | Ceiling of `tokenized`; cannot read the raw lake |
 | `'admin'`         | Full tenant management                 |
 
 ```typescript

package/.agent/action_logs.md

@@ -39,7 +39,7 @@ batch_id            — the run this outcome belongs to; THE
 decision_key        — which action fired
 context_key         — companion string key; like decision_key, it is
                       SQL-lane only (neither is Flop-filterable, §5)
-mdm_subject_id, subject_name, session_id
+legal_entity_id, subject_name, session_id
 action_type ('sms'|'email'|'voice'|'data_exchange'), channel,
 classification
 status              — see §3
@@ -92,17 +92,17 @@ message.
 // dataset type is SINGULAR 'action_log' (the table is plural)
 const { data: search } = await api.datasets.createUserSearch(
   tenantSlug, datalakeSlug, 'action_log',
-  { search_query: `ral.batch_id = '${batchId}'` },
+  { search_query: `al.batch_id = '${batchId}'` },
 )
 const { data: page } = await api.datasets.search(
   tenantSlug, datalakeSlug, 'action_log',
-  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+  { userSearchId: search.id, dataAccessMode: 'tokenized' },
 )
 ```
 
 Filterable columns (Flop, the full set): `id`, `inserted_at`,
 `action_type`, `channel`, `status`, `batch_id`, `classification`,
-`workflow_id`, `sent_at`, `external_id`, `mdm_subject_id`. Note
+`workflow_id`, `sent_at`, `external_id`, `legal_entity_id`. Note
 there is **no `global_search`** here (unlike the message dataset) —
 `decision_key`/`context_key` are not in this set either; scope them
 via the `search_query` SQL fragment above.

package/.agent/advanced_migrations.md

@@ -0,0 +1,202 @@
+# Advanced migrations
+
+SQL a person wrote by hand for one datalake.
+
+The platform writes its own DDL when a generic table is created or gains a
+column — `CREATE TABLE` and `ALTER TABLE … ADD COLUMN`, and nothing else.
+Everything past that is yours to write here: an index, a foreign key, a column
+rename, a type change, a drop. The same migrator runs both.
+
+**One name, two spellings.** Outwardly these are *advanced migrations*, which is
+what the API path and this guide call them. The platform stores them in
+`datalake_migrations`, and its own logs and internals use that name. Both are
+correct; do not coin a third.
+
+    api.advancedMigrations        →  this guide
+    /datalakes/{slug}/advanced-migrations
+
+## 1. Wire shape
+
+```typescript
+const { data: created } = await api.advancedMigrations.create(
+  tenantSlug,
+  datalakeSlug,          // scope comes from the PATH — see below
+  {
+    name: 'AddEmailIndexToContactSubmissions',
+    up_statement:
+      'CREATE INDEX IF NOT EXISTS idx_contact_submissions_email ' +
+      'ON alvera_custom_contact_submissions (email)',
+    down_statement:
+      'DROP INDEX IF EXISTS idx_contact_submissions_email',
+  },
+)
+// created.id           — server-derived UUID
+// created.version      — server-assigned from a sequence; orders execution
+// created.datalake_id  — server-derived from the path
+// created.checksum     — server-computed; the drift fingerprint
+```
+
+Three fields, all required, all strings:
+
+```
+name             required string — capitalized identifier, unique per datalake
+up_statement     required string — the DDL to run
+down_statement   required string — the DDL that reverses it
+```
+
+**`datalake_id` is NOT a body field.** This is the one place the shape departs
+from every other datalake-scoped kind. Elsewhere — tools, workflows, generic
+tables — you send `datalake_id` in the body. Here it is `readOnly`: the scope
+comes from `datalakeSlug` in the path, and the server fills the field in. Sending
+it is not how you say which lake this belongs to.
+
+**`version` is server-assigned and orders execution.** It comes from a sequence,
+not from you, and it is the thing that decides what runs first — not the name,
+and not the order you declared them in. Generated migrations carry a year-style
+prefix in their names to read well beside yours; that prefix is cosmetic.
+
+## 2. Rules the type cannot encode
+
+### An applied migration is frozen — update and delete both refuse
+
+Once a migration has run successfully, `update()` and `delete()` each answer
+**409 Conflict**. The reasons differ and both are worth knowing.
+
+**Update** is refused because a statement that has already executed cannot be
+rewritten after the fact: the new text would no longer describe what happened.
+
+**Delete** is refused because the run log cascades on delete, so removing an
+applied migration would also erase the record of it having run.
+
+So a migration has exactly two lives. Before it runs it is ordinary and
+editable. After it runs it is history. **Changing applied DDL means writing a
+NEW migration that alters what the old one built** — the same shape as changing
+a generic table column's `privacy_requirement`, which is delete-and-recreate
+rather than an edit.
+
+"Applied" means precisely: a run log row exists for this migration with
+direction `up` and status `success`. A failed run does not freeze it.
+
+### Write the statement to be safe on a second run
+
+The platform tracks what it has applied and will not run an applied migration
+twice, so you do not need `IF NOT EXISTS` for that. You need it for the other
+case: a run that failed **partway**. The applied-migrations record stops a second
+run; it does not undo a first one that got halfway.
+
+```sql
+-- safe to meet again
+CREATE INDEX IF NOT EXISTS idx_submissions_email ON … (email)
+
+-- Postgres has no ADD CONSTRAINT IF NOT EXISTS, so guard it yourself
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'fk_submissions_lead'
+  ) THEN
+    ALTER TABLE alvera_custom_contact_submissions
+      ADD CONSTRAINT fk_submissions_lead
+      FOREIGN KEY (lead_id) REFERENCES alvera_custom_leads (id);
+  END IF;
+END $$;
+```
+
+The same applies to `down_statement`, which is likelier to be run against a
+database that is not in the state you assumed.
+
+### The table names are the platform's, not yours
+
+A generic table you declared as `contact_submissions` is physically
+`alvera_custom_contact_submissions`. Read the name back from the created table
+rather than composing it — see `generic_tables.md` — because your migration
+statement has to name the physical table, and getting it wrong is a runtime
+failure inside DDL rather than a validation error.
+
+### Ordering is real, and it is the version's job
+
+Adding an index and then a foreign key that depends on it are two migrations,
+and the sequence decides which runs first. Two migrations created in one session
+run in creation order because the sequence is monotonic — but if you need B
+after A, that is a fact about your two `version` values, not about how you
+listed them.
+
+## 3. Field ownership
+
+**Caller-authored (Request).** `name`, `up_statement`, `down_statement`. That is
+the whole writable surface.
+
+**Server-derived (Response-only).** `id`, `datalake_id`, `version`, `checksum`,
+`inserted_at`, `updated_at`. None may be sent; see `type_naming.md` for why the
+Writable types exclude them.
+
+`name` is unique per datalake, so two lakes may each carry a
+`AddEmailIndex` and neither collides.
+
+## 4. Error envelopes
+
+Standard JSON:API envelope throughout — see `errors.md`.
+
+| Status | When |
+|---|---|
+| 422 | a required field is missing, or `name` collides within this datalake |
+| 409 | the migration has already been applied — `update` and `delete` both |
+| 404 | the id belongs to a different datalake (deliberately not "403": its existence is not leaked) |
+
+A 409 here is not a retryable condition. It is telling you the migration is
+history and you want a new one.
+
+## 5. Lifecycle
+
+```
+create      →  the row exists; nothing has run yet
+migrate     →  the datalake's migrator runs it, in version order
+              (POST /datalakes/{slug}/migrate — asynchronous, 202)
+applied     →  a run log row: direction up, status success
+              from here: update 409, delete 409
+```
+
+Creating a migration does **not** run it. The datalake's migrate call does, and
+it is asynchronous — it answers 202 as soon as the job is enqueued. Poll the
+datalake for `status: ready` the way you would after creating one; see
+`datalakes.md`.
+
+## 6. Gotchas
+
+**A created migration that never ran is invisible in the database.** The row
+exists, `list()` returns it, and nothing has happened to any table. Reading the
+catalog is the only way to know whether it took effect — the migration record
+says what you asked for, not what is true.
+
+**Proving one worked means asking the database, not the API.** The response
+carries `checksum`, `datalake_id`, `down_statement`, `id`, `inserted_at`,
+`name`, `up_statement`, `updated_at` and `version` — no status, no applied
+flag, and `version` is execution ORDER rather than proof of execution. So the
+honest check is a query against the catalog for the object the statement was
+supposed to create:
+
+```typescript
+// an index
+const { data: indexRows } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `select 1 from pg_indexes
+         where tablename = 'alvera_custom_contact_submissions'
+           and indexname = 'idx_contact_submissions_email'`,
+  mode: 'raw',
+})
+
+// a foreign key
+const { data: fkRows } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `select 1 from information_schema.table_constraints
+         where constraint_type = 'FOREIGN KEY'
+           and table_name      = 'alvera_custom_contact_submissions'
+           and constraint_name = 'fk_submissions_lead'`,
+  mode: 'raw',
+})
+```
+
+**`down_statement` is required and is rarely exercised.** Nothing makes you
+prove it works, and it is the statement you will want on your worst day. Write
+it as carefully as the `up`.
+
+**A migration belongs to exactly one datalake.** There is no shared or
+tenant-level migration. Three lakes needing the same index need three
+migrations — which is also why `name` only has to be unique per lake.