@alvera-ai/platform-sdk 0.12.1 → 0.13.0-next.gf3d2a4a

package/.agent/data_activation_clients.md

@@ -51,6 +51,43 @@ const { data: created } = await api.dataActivationClients.create(
 
 ## 2. Rules the type cannot encode
 
+### Every dataset already has a default manual-upload DAC — reuse it, never create one
+
+Datalake provisioning auto-creates, for **every dataset** — the built-in resource
+types (`customer`, `patient`, `legal_entity`, …) **and every generic table you add** —
+a default manual-upload Data Activation Client, alongside the default data source +
+manual-upload tool and a default identity interoperability template. The plumbing to
+push rows into any dataset **already exists**; you do not create a DAC to seed test
+data or ingest a handful of rows.
+
+Reinventing it — e.g. calling `dataActivationClients.create(...)` inside a contract
+hook — is an anti-pattern. That DAC then lives **outside** `infra.toml`: untracked,
+never shown in `plan`, and not idempotent. Because DAC names are unique per datalake,
+it **collides on the second run** — any drift or update verdict re-fires the hook,
+which re-creates the same-named DAC and 409s (`name must be unique` — uniqueness
+collisions are 409 Conflict, see `errors.md`), halting the apply.
+
+The default DAC name is deterministic — `"<Datalake Name> <resource> DataActivationClient"`
+with `is_default: true` (e.g. `"Subscription Lake customer DataActivationClient"`).
+Discover it and ingest through it:
+
+```typescript
+const { data: clients } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+// `list` returns the paged envelope { data, meta } — the DAC array is clients.data
+const seedDac = (clients.data ?? []).find(
+  (c) => c.is_default && c.name.endsWith('customer DataActivationClient'),
+)
+// ingest is SLUG-keyed (see §6) — pass seedDac.slug, not seedDac.id
+await api.dataActivationClients.ingest(tenantSlug, datalakeSlug, seedDac.slug, { data: row })
+```
+
+`ingest` is safe to re-run — MDM dedupe collapses repeat rows on the identifier
+triple — so a hook that *ingests through the default DAC* stays idempotent across
+re-applies. **Declare your own DAC in `infra.toml` only for a real pipeline** (an
+SFTP/REST fetch, a cron schedule, a custom-contract binding) — never merely to push
+a few rows in. See `interoperability_contracts.md` (born-red cures: prove the mapping
+with `.run(...)`, seed through the default DAC).
+
 ### `tool_call.tool_call_type` must align with the bound tool's `tool_body_type`
 
 The activation client's `tool_call` discriminator selects which
@@ -60,15 +97,22 @@ call shape will be sent to the tool at run time. The valid
 
 ```
 tool_body_type: 'manual_upload'  → tool_call_type: 'manual_upload'
-tool_body_type: 'sftp'           → tool_call_type: 'sftp_fetch' | ...
-tool_body_type: 'rest_api'       → tool_call_type: 'rest_api_request'
-tool_body_type: 'sns'            → tool_call_type: 'sms_request'
+tool_body_type: 'rest_api'       → tool_call_type: 'restapi_request'
+tool_body_type: 'sftp'           → tool_call_type: 'sftp_request'
+tool_body_type: 's3'             → tool_call_type: 's3_request'
+tool_body_type: 'sql_database'   → tool_call_type: 'sql_query'
+tool_body_type: 'sharepoint'     → tool_call_type: 'microsoft_share_point_excel_request'
+tool_body_type: 'aws_lambda'     → tool_call_type: 'aws_lambda_request'
 ```
 
-(See `tools.md` §5 for the polymorphic call shape per tool body
-type.) A mismatch — e.g. a `manual_upload` tool bound with an
-`sftp_fetch` call — is rejected at create time as a 422 on
-`/tool_call/tool_call_type`.
+The complete `tool_call_type` discriminator set is exactly those
+seven values (`data_activation_client.ex` polymorphic embed) — there
+is no `sms`/`sns` call shape here, because a DAC only ever binds a
+tool whose `intent` is `data_exchange` (enforced in the changeset's
+`validate_tool_intent`). (See `tools.md` §5 for the polymorphic call
+shape per tool body type.) A mismatch — e.g. a `manual_upload` tool
+bound with an `sftp_request` call — is rejected at create time as a
+422 on `/tool_call/tool_call_type`.
 
 ### `interoperability_contract_ids` is a virtual many-to-many array
 
@@ -152,11 +196,22 @@ row_filter                      optional string — Liquid pre-filter; see §2
                                   for inverted semantics
 downstream_connection_ids       optional UUID[] — DACs triggered after this
                                   one completes; cycles rejected at create
+filter_config                   optional embed — TemplateConfig; server-pinned
+                                  output_schema (enum ["true","false"]). A row-
+                                  level filter evaluated per fetched row
+response_extractor              optional embed — TemplateConfig ({ type, body });
+                                  a Liquid template that unwraps a nested API
+                                  envelope into the row array (e.g.
+                                  `{{ msg.data | to_json }}`). Load-bearing for
+                                  `rest_api` fetch DACs; see `rest-fetch.md` §004
 ```
 
 **Write-only (Request-only).** None — every caller-supplied
 field round-trips on the response (the virtual array
 round-trips under `interoperability_contracts` on response).
+`filter_config` / `response_extractor` come back under the read-only
+`SimpleTemplateConfigResponse` shape (their `output_schema` is
+server-pinned and not echoed).
 
 ## 4. Error envelopes
 
@@ -165,6 +220,7 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `source.pointer`                          | Cause                                              |
 |-------------------------------------------|----------------------------------------------------|
 | `/tool_id` / `/data_source_id`            | resource doesn't exist (or wrong datalake)         |
+| `/data_source_id`                         | does not match the bound tool's `data_source_id` — a DAC's source must equal its tool's source (source-match) |
 | `/tool_call/tool_call_type`               | mismatch with the tool's `tool_body_type`          |
 | `/interoperability_contract_ids/0`        | contract id doesn't exist or wrong datalake        |
 | `/name`                                   | uniqueness within datalake (POST and PUT — rename can collide) |
@@ -182,11 +238,24 @@ of the runtime verbs in §6.
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
-.get(tenantSlug, datalakeSlug, slug)         One row, by slug
-.metadata(tenantSlug, datalakeSlug, slug)    Agent-facing metadata
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
+.get(tenantSlug, datalakeSlug, id)           One row, by the UUID id (NOT slug)
+.metadata(tenantSlug, datalakeSlug, query?)  Markdown catalog page of the
+                                              datalake's DACs (Flop-paged)
+.metadataDetails(tenantSlug, datalakeSlug, id)
+                                              Markdown of one DAC's connected-
+                                              dataset field docs, by UUID id
 ```
 
+**`.get` takes the UUID `id`, not the slug.** The CRUD reads/writes
+(`.get` / `.update` / `.delete` / `.metadataDetails`) are id-keyed —
+the controller resolves them through the `fetch_client_by_id` plug
+(`get_client_by_id_for_datalake!`). Only the *runtime* verbs (§6:
+`.ingest` / `.ingestFile` / `.runManually` / `.logs.*`) are slug-keyed
+(`fetch_client_by_slug`). To go from a name/slug to an id, `list()`
+and match on `.slug` (or `.name`), then use the row's `id`.
+
 ### Update
 
 `update()` replaces the whole resource — resupply the full
@@ -194,25 +263,27 @@ body; there's no partial update. Pointer fields
 (`tool_id`, `data_source_id`, `interoperability_contract_ids`)
 can be re-pointed.
 
-**The `slug` regenerates from `name` on every `update()`.** The
-lookup key you pass is the OLD slug (so the update call resolves),
-but the response body carries the NEW slug derived from the
-updated `name`. Examples:
+**The `update()` lookup key is the UUID `id`, which never changes.**
+But **the `slug` regenerates from `name` whenever `name` changes** —
+the changeset re-derives it (`SlugGenerator.name_to_slug`), so the
+response body carries a NEW slug after a rename even though you
+addressed the row by its stable `id`. Examples:
 
 ```
-   pre-update:   name: 'Original',   slug: 'original'
+   pre-update:   name: 'Original',   slug: 'original',   id: <uuid>
    PUT body:     name: 'Renamed', ...
-   PUT URL:      .../data-activation-clients/original   ← old slug works for lookup
-   PUT response: name: 'Renamed',    slug: 'renamed'    ← new slug derived
+   PUT URL:      .../data-activation-clients/<uuid>   ← id is stable, addressable throughout
+   PUT response: name: 'Renamed',    slug: 'renamed'  ← new slug derived from the new name
 ```
 
-**Consequence**: any downstream resource that references the
-DAC by slug (workflow templates, action bodies referencing
-`{{ ... }}` paths derived from the DAC slug, monitoring
-dashboards, etc.) breaks the moment the DAC is renamed.
-Capture the post-update slug from the response, NOT the lookup
-key you passed. If you rename a DAC mid-deployment,
-update every binding that references it.
+**Consequence**: because the runtime verbs (§6) are slug-keyed,
+a rename moves the ingest / run / logs endpoints to the new slug —
+and any downstream resource that references the DAC by slug
+(workflow templates, action bodies referencing `{{ ... }}` paths
+derived from the DAC slug, monitoring dashboards, etc.) breaks the
+moment the DAC is renamed. Capture the post-update slug from the
+response body. If you rename a DAC mid-deployment, update every
+binding that references it.
 
 An `update()` that keeps `name` unchanged regenerates to the
 same slug (slugification is deterministic), so cosmetic-only
@@ -220,9 +291,13 @@ updates don't break bindings.
 
 ### Delete
 
-`delete()` removes the activation client. In-flight runs
-decouple their lifecycle from the activation client row;
-deleting one mid-run is generally rejected with a 422.
+`delete()` removes the activation client (by UUID `id`). Two
+rejections: a **default DAC** (`is_default: true`) is refused with a
+**422** on `/is_default` ("Default data activation clients cannot be
+deleted"), and a DAC still **referenced by another resource** is
+refused with a **409**. Otherwise it deletes; a run already in flight
+keeps its own lifecycle (its `batch_id` is already stamped on the
+enqueued jobs) and completes independently of the deleted row.
 
 ## 6. Runtime
 
@@ -292,6 +367,7 @@ const { data: job } = await api.dataActivationClients.ingestFile(
 )
 // job.key    — echoes link.key
 // job.job_id — numeric id of the enqueued background job
+// job.status — initial Oban job state (e.g. 'scheduled' / 'available')
 ```
 
 This path is **fully async** — the response acknowledges that
@@ -312,11 +388,14 @@ verb:
 const { data } = await api.dataActivationClients.runManually(
   tenantSlug, datalakeSlug, activationClientSlug,
 )
+// data.batch_id — UUID; returned immediately (202), the batch stamped on this run's jobs
 ```
 
-Returns an acknowledgement; the actual fetch runs
-asynchronously in the background. As with `.ingestFile`,
-discover the assigned `batch_id` by polling the logs.
+Unlike `.ingestFile`, `.runManually` **returns the `batch_id`
+directly** (`202` + `{ batch_id }` — `RunManuallyResponse`); you do
+NOT have to diff the logs to find it. The actual fetch still runs
+asynchronously in the background, so poll the logs (§6.4) with that
+`batch_id` to know when rows have landed.
 
 #### One-shot `tool_call` override
 
@@ -349,14 +428,21 @@ rows_ingested       number — count of top-level rows the contract emitted
                               (cascade rows carry 0)
 dataset_updated     number — count of dataset rows whose batch_id this run wrote
                               (load-bearing: see Gotcha 7)
-output_files        string[] — merged ndjson archive paths
-                                (empty until the post-batch merge worker commits)
+output_files        { object_key, mode }[] — merged ndjson archive refs, one per
+                                bucket; mode is 'regulated' | 'unregulated'
+                                (empty until the post-batch merge worker commits).
+                                NOT a string[] — each entry is an embed object;
+                                use /logs/:id/download to fetch a presigned URL
 ```
 
 ```typescript
-// Paginated list of log rows for an activation client.
+// Paginated list of log rows for an activation client. Takes the full
+// Flop query (page / page_size / order_by / order_directions / filters
+// — type_naming.md); without it, page 1 only, and a busy client's older
+// batches drop out of view.
 const { data } = await api.dataActivationClients.logs.list(
   tenantSlug, datalakeSlug, activationClientSlug,
+  { page: 1, page_size: 50, order_by: ['inserted_at'], order_directions: ['desc'] },
 )
 // data.data — array of log rows; filter by batch_id to find this run
 
@@ -386,6 +472,30 @@ durable" signal — not just the presence of the log row.
 
 ### 6.5 Verifying ingestion: the two-step dataset search
 
+> **Simplest landing check — `executeSql`.** Ingestion is async (the row
+> commits a moment after the `202`). When you just need to know a row
+> *landed*, poll `datalakes.executeSql` with a read-only `SELECT … WHERE
+> batch_id = '…'`: **each call is a fresh read, so there is no stale
+> snapshot to recover from** — unlike a `createUserSearch` created before
+> the row commits, which captures nothing and never updates. Gate on it,
+> then run the two-step `createUserSearch` below **once** (race-free) only
+> if you need the dataset's alias-join + tokenization semantics.
+>
+> ```typescript
+> const { data: probe } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+>   sql: `SELECT 1 FROM patients WHERE batch_id = '${batchId}' LIMIT 1`,
+>   mode: 'unregulated',
+> })
+> // `data` is an array-of-arrays (a `string` only for { format: 'csv' });
+> // a non-empty page proves the batch landed. Reference the unregulated
+> // table by its base name — `mode: 'regulated'` uses the `regulated_` prefix.
+> const landed = typeof probe !== 'string' && probe.data.length > 0
+> ```
+>
+> `createUserSearch` is the heavier, workflow-oriented surface — reach for
+> it when you need its alias joins (`ri.value`, tokenized read-back), not
+> for a plain "did it land" check.
+
 The canonical way to **prove a row landed in the datalake** is
 to query the dataset directly. This is a two-step pattern:
 
@@ -432,20 +542,25 @@ const { data: page } = await api.datasets.search(
 #### SQL aliases
 
 `createUserSearch` accepts a WHERE-clause fragment against a
-fixed set of table aliases. Each dataset has a canonical base
-alias for its regulated table, plus `ri` for the
-regulated_identifiers join:
+fixed set of table aliases. Each dataset has a base alias for its
+primary regulated table, plus `ri` for the regulated_identifiers
+join. **The base alias is assigned by that dataset's server-side
+decomposed query — it is NOT derivable from the dataset name, and
+different datasets reuse the same letters.** Verified examples:
 
 ```
-patient        → rp  (regulated_patients) + ri
+patient        → rp  (regulated_patients)  + ri
 appointment    → ra  (regulated_appointments) + ri
-customer       → rc  (regulated_customers) + ri
-...            (one alias per regulated dataset)
+customer       → ra  (regulated_customers)  + ri   ← 'ra', NOT 'rc'
 ```
 
-The `ri.value` predicate filters on external identifiers (the
-values your inbound rows carried); the `<base_alias>.batch_id`
-predicate scopes the search to one run.
+`customer` is a live trap: its primary table is aliased `ra`, not
+`rc` (both `rest-fetch.md` §006 and `bulk-ingest.md` §008 query it as
+`ra.batch_id`). Don't guess the alias from the dataset name — confirm
+it from the dataset's green cookbook/test before writing the fragment.
+The `ri.value` predicate filters on external identifiers (the values
+your inbound rows carried); the `<base_alias>.batch_id` predicate
+scopes the search to one run.
 
 #### Tokenized vs plain column shape
 
@@ -557,3 +672,23 @@ first.
     migration time) are protected. Filter them out
     (`!d.is_default`) when listing for management purposes; you
     can still PUT-update them (e.g. to bind additional contracts).
+
+14. **A never-landing ingest (`dataset_updated` never flips)
+    fails silently — diagnose UPSTREAM, at the extractor, not the
+    merge.** Distinct from the trigger *lag* in §7.7: here the row
+    is *received* but never *persists*. The per-row `DataExtractor`
+    is where it dies; the later `BatchMergeWorker` "No files found
+    … *.ndjson" is a DOWNSTREAM SYMPTOM (the extractor never wrote
+    the ndjson) — don't stop there. Usual extractor causes: (a)
+    **MDM subject not resolved** — `:mdm_output_required` /
+    "upsert_dataset called without %MDMOutput{}": the contract's
+    `mdm_input_config` rendered nil (a `null`/misprovisioned
+    identity contract, or missing MDM identity fields), so a
+    domain that requires entity resolution rejects the row; (b) a
+    **per-row changeset rejection** — most often an out-of-set
+    enum (see `interoperability_contracts.md` §7). The caller sees
+    only `rows_ingested`. Diagnose with the platform's Oban error
+    logs (isolate by `batch_id`/`datalake_slug` metadata) + an
+    `execute-sql` probe of the DAC log's `dataset_updated`; the
+    CLI's `run-dac --json` + `execute-sql` verbs reproduce and
+    probe it without building an app.

package/.agent/data_sources.md

@@ -42,8 +42,11 @@ const { data: created } = await api.dataSources.create(
 ```
 
 The body is flat — no discriminator. Every data source carries
-the same five caller-supplied fields plus the universal server-
-derived set (`id`, `slug`, `created_at`, `updated_at`).
+the same caller-supplied fields — four required (`name`, `uri`,
+`status`, `is_default`) plus two optional (`description`,
+`image_url`) — and the universal server-derived set (`id`,
+`slug`, `created_at`, `updated_at`). The cookbooks omit
+`image_url` (a five-field body is the common shape).
 
 ## 2. Rules the type cannot encode
 
@@ -98,7 +101,8 @@ multi-step UI flows.
 ```
 name           required string — agent-facing label
 uri            required string — endpoint identifier (free-form)
-description    optional string — narrative
+description    optional string — narrative (nullable)
+image_url      optional string — icon/image URL for the source (nullable)
 status         required enum   — lifecycle state
 is_default     required bool   — at most one true per datalake
 ```
@@ -123,12 +127,22 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/uri`                             | empty/structurally invalid OR uniqueness within  |
 |                                    | datalake (uri collision)                          |
 | `/status`                          | value not in the typed enum                      |
-| `/is_default`                      | another source already marked default            |
 
-All of these come back as a 422 `AlveraApiError` thrown from the
-SDK on submit — both structural failures (Layer 1) and semantic
-rejections like uniqueness / is_default conflict (Layer 2). The
-SDK does not validate client-side. See `errors.md`.
+A structurally invalid `/name` or `/uri` (Layer 1) is a 422; a
+`/name` or `/uri` **uniqueness collision** (Layer 2, mapped via
+`unique_constraint`) comes back as a **409 Conflict** — same
+`AlveraApiError` envelope, different status (see `errors.md` for the
+422-vs-409 split). The SDK does not validate client-side.
+
+**The `is_default` "one default per datalake" rule is the
+exception — it is NOT a clean 422.** The rule is enforced only by a
+Postgres partial unique index; the changeset has no matching
+`unique_constraint` and the controller has no `Ecto.ConstraintError`
+rescue, so creating a second `is_default: true` source raises an
+**unhandled 500**, not a `/is_default` 422. Don't rely on a tidy
+envelope here — read back the datalake's existing default first (§2)
+and pass `is_default: false` unless you intend to be the one default.
+(The distinct *delete*-the-default guard IS a real 422 — see §5.)
 
 ## 5. Lifecycle
 
@@ -150,12 +164,13 @@ const { data: source } = await api.dataSources.create(
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged list:
+.list(tenantSlug, datalakeSlug, query?)      Paged list:
                                               { data: DataSourceResponse[], meta }
-.get(tenantSlug, datalakeSlug, idOrSlug)     One row
+                                              (full Flop query — type_naming.md)
+.get(tenantSlug, datalakeSlug, id)           One row — UUID only
 .metadata(tenantSlug, datalakeSlug)           Markdown string — catalog
 .metadataDetails(tenantSlug, datalakeSlug,    Markdown string — one source
-                 idOrSlug)
+                 id)                          (UUID only)
 ```
 
 The two `metadata` methods return `string` — agent-facing
@@ -179,34 +194,34 @@ const { data: updated } = await api.dataSources.update(
 )
 ```
 
-### Delete (operator-only — no SDK surface)
+### Delete
 
-There is **no delete operation** for data sources, and
-correspondingly no `api.dataSources.delete(...)` method on the
-typed client. Removal is operator-driven via the platform's
-admin console.
+```typescript
+await api.dataSources.delete(tenantSlug, datalakeSlug, sourceId)
+```
 
-For completeness, when an operator does remove a data source
-the platform applies asymmetric cascade behavior by dependent
-resource:
+`delete()` removes the row and returns `204 No Content` (UUID
+`id` only, like `.get` / `.update`). The platform applies
+asymmetric cascade behavior by dependent resource:
 
 - All data activation clients bound via `data_source_id`
-  cascade-delete with the source.
-- Workflow actions referencing the data source REJECT the
-  delete with a 422 — the operator must detach those actions
-  first.
+  cascade-delete with the source (FK `on_delete: :delete_all`).
+- Workflow actions referencing the data source have a
+  restricting FK (`on_delete: :restrict`), so the delete is
+  **rejected** while any action still points at the source —
+  detach those actions first.
 
 The auto-created default Manual Upload source (see §2 "A
 default Manual Upload data source is auto-created per
-datalake") is **not removable** — even operator-driven deletes
-reject it. The default exists for the lifetime of its parent
-datalake.
+datalake") is **not removable**: `delete_data_source` guards
+`is_default` and returns a 422 with `is_default` → "Default data
+sources cannot be deleted". The default exists for the lifetime
+of its parent datalake.
 
-Consumer-side, treat data sources as monotonically-growing
-within a datalake. If your code path conceptually "removes" a
-source (e.g. an integration test cleaning up), the only
-SDK-visible option is to mark it `status: 'inactive'` via PUT —
-the source row stays in the datalake.
+If you want to retire a source without deleting it (e.g. the
+default, or one a workflow action still references), mark it
+`status: 'inactive'` via PUT — the row stays in the datalake but
+is short-circuited from new ingestion runs.
 
 ## 6. Gotchas
 
@@ -219,12 +234,15 @@ the source row stays in the datalake.
    multiple datalakes, iterate by datalake or use cross-datalake
    discovery via a higher-level surface.
 
-2. **`is_default` collisions surface at create time.** Creating
-   a source with `is_default: true` against a datalake that
-   already has a default returns a 422. The SDK does NOT
-   silently demote the existing default. Either pass
-   `is_default: false` and promote separately via operator
-   action, or coordinate with the existing default's owner.
+2. **`is_default` collisions raise a 500, not a clean 422.** The
+   "one default per datalake" rule lives only in a Postgres partial
+   unique index — unmapped by the changeset and unrescued by the
+   controller (see §4) — so creating a second `is_default: true`
+   source currently surfaces as an unhandled 500. The SDK does NOT
+   silently demote the existing default either. Check the datalake's
+   current default and pass `is_default: false` unless you mean to
+   own it; don't branch on a `/is_default` error envelope that
+   doesn't arrive cleanly.
 
 3. **Data sources don't carry credentials.** A source is a
    *named endpoint*, not an authenticated connection.

package/.agent/datalakes.md

@@ -11,7 +11,7 @@ two databases under one roof:
 Every other resource in the platform (data sources, tools, AI
 agents, workflows, etc.) scopes under a datalake. A tenant can own
 many datalakes; the canonical pattern is one per data domain (e.g.
-`healthcare`, `foundation`, `payment_risk`).
+`healthcare`, `foundation`, `payments`).
 
 ```typescript
 import type { PlatformApi } from '@alvera-ai/platform-sdk'
@@ -123,7 +123,7 @@ import type { DatalakeRequestWritable } from '@alvera-ai/platform-sdk'
 // identical across them; only `data_domain` and the names it
 // interpolates differ.
 const dataDomain = 'healthcare'
-//                  ^ swap to 'foundation' | 'accounts_receivable' | 'payment_risk'
+//                  ^ swap to 'foundation' | 'subscription' | 'payments'
 
 // Secrets resolved upstream by your code (secret store, config loader, etc.)
 const pgHost = '...'
@@ -340,7 +340,7 @@ Datalake-specific common rejections:
 | `/unregulated_cloud_storage`                    | synchronous probe could not reach the bucket with the supplied credentials |
 | `/unregulated_cloud_storage/access_key_id`      | supplied under `auth_method: "iam_role"` (must be omitted) |
 | `/pool_size`                                    | out of the inclusive range 1–50                      |
-| `/timezone`                                     | not a valid IANA timezone identifier                 |
+| `/timezone`                                     | not in the closed 8-zone US whitelist (valid IANA values like `UTC` are also rejected — see gotcha 11) |
 
 For polymorphic embeds, the `cloud_storage_type` value is the
 first thing to inspect — it routes downstream field validation to
@@ -400,15 +400,20 @@ the datalake row — it carries `job_id` + `datalake_id` +
 separately:
 
 ```typescript
-const { data: dl } = await api.datalakes.get(tenantSlug, created.slug)
+const { data: dl } = await api.datalakes.get(tenantSlug, created.id)
 // dl.status === 'new' | 'processing' | 'ready'
 ```
 
+**`datalakes.get` keys on the UUID `id`, not the slug** (the facade
+signature is `get(tenantSlug, id)`, and the validated setup cookbooks
+poll with `ctx.datalakeId`). Passing the slug 422s with `Invalid
+format. Expected :uuid`. Stash `created.id` from the create response.
+
 Use the canonical `waitUntilReady` from `async.md`:
 
 ```typescript
 const dl = await waitUntilReady(
-  () => api.datalakes.get(tenantSlug, created.slug),
+  () => api.datalakes.get(tenantSlug, created.id),
   (status) => status === 'ready' ? 'ready' : 'pending',
   { intervalMs: 15_000, timeoutMs: 5 * 60_000 },
 )
@@ -539,8 +544,8 @@ returning a different shape:
 
 | Method                               | Returns                                                     |
 |--------------------------------------|-------------------------------------------------------------|
-| `.list(tenantSlug)`                  | Paged list: `{ data: DatalakeResponse[], meta }`            |
-| `.get(tenantSlug, idOrSlug)`         | One row: `DatalakeResponse`                                 |
+| `.list(tenantSlug, query?)`          | Paged list: `{ data: DatalakeResponse[], meta }` — full Flop query (type_naming.md) |
+| `.get(tenantSlug, id)`               | One row: `DatalakeResponse` — UUID only (slug 422s)         |
 | `.metadata(tenantSlug, slug)`        | **Markdown string** describing the lake                     |
 | `.indexMetadata(tenantSlug)`         | **Markdown string** listing every lake                      |
 | `.systemDatasets(tenantSlug, slug)`  | `{ datasets: string[] }` — industry-built dataset names     |
@@ -602,7 +607,11 @@ the SQL between the two calls.
   returns the generated `sql`, the winning `model` + `provider`, and a best-effort
   `explanation` (`null` when the explainer is unavailable). **Only the prompt + the
   schema cross the LLM boundary — never datalake rows**, so it is safe in both modes.
-  It returns SQL for review; it does **not** execute it.
+  It returns SQL for review; it does **not** execute it. The review step is
+  load-bearing, not ceremony: the model can emit SQL that parses but fails
+  live — e.g. `WHERE some_boolean = 1` 422s on Postgres (booleans compare to
+  `true`/`false`, never `1`). Surface the SQL to a human (or a checking step)
+  and expect to edit before `executeSql`.
 - **`executeSql`** body is `{ sql, mode, page?, page_size? }`. It runs the SQL
   **read-only** (INSERT/UPDATE/DELETE/DDL are rejected) on the mode-appropriate
   schema, with Flop-inspired pagination (`page_size` capped server-side). The JSON
@@ -645,10 +654,10 @@ const { data: csv } = await api.datalakes.executeSql(
    const { data: created } = await api.datalakes.create(tenantSlug, body)
    // created.status === 'new'
 
-   await api.datalakes.migrate(tenantSlug, created.slug)
+   await api.datalakes.migrate(tenantSlug, created.slug)   // migrate is slug-keyed
 
    const ready = await waitUntilReady(
-     () => api.datalakes.get(tenantSlug, created.slug),
+     () => api.datalakes.get(tenantSlug, created.id),      // get is UUID-id-keyed
      (s) => s === 'ready' ? 'ready' : 'pending',
      { intervalMs: 15_000, timeoutMs: 5 * 60_000 },
    )
@@ -745,13 +754,17 @@ const { data: csv } = await api.datalakes.executeSql(
     mentions a `greater_than: 0` or `less_than_or_equal_to: 50`
     constraint depending on which side was crossed.
 
-11. **`timezone` is a closed IANA enum.** Submit a non-IANA string
-    (e.g. `"Bad/Timezone"` or `"EST"`) and the platform rejects
-    with `is not a valid IANA timezone` on `/timezone`. The set of
-    valid identifiers is not exposed over the SDK as a discovery
-    surface — consumers must source IANA tz database names
-    externally (e.g. JavaScript's `Intl.supportedValuesOf('timeZone')`,
-    or the IANA tz data directly).
+11. **`timezone` is a closed whitelist of 8 US timezones — NOT the
+    general IANA set.** Exactly: `America/New_York`, `America/Chicago`,
+    `America/Denver`, `America/Los_Angeles`, `America/Anchorage`,
+    `America/Adak`, `Pacific/Honolulu`, `America/Phoenix`. Everything
+    else is rejected on `/timezone` with `must be one of the supported
+    US timezones: …` — including values that ARE valid IANA zones
+    (`UTC`, `Etc/UTC`, `Africa/Abidjan`). Do NOT source candidates from
+    `Intl.supportedValuesOf('timeZone')`; almost all of its ~400 values
+    are rejected. The whitelist is projected as the `timezone` enum in
+    the OpenAPI schema, so the generated `DatalakeRequest` type carries
+    the legal values and TypeScript consumers get them at compile time.
 
 12. **`auth_method` defaults to `"password"` on every DB profile.**
     Omitting `*_auth_method` or supplying `null` is equivalent to