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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/.agent/AGENTS.md +121 -19
  2. package/.agent/account_management.md +79 -38
  3. package/.agent/action_logs.md +144 -0
  4. package/.agent/action_status_updaters.md +237 -53
  5. package/.agent/ai_agents.md +149 -53
  6. package/.agent/ai_sandbox.md +11 -4
  7. package/.agent/async.md +16 -6
  8. package/.agent/connected_apps.md +116 -4
  9. package/.agent/cookbook/_fixtures/README.md +9 -9
  10. package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_compliance_screening.liquid → payments/_compliance_screenings_payments_compliance_screening.liquid} +1 -1
  11. package/.agent/cookbook/_fixtures/{payment_risk/_compliance_screenings_payment_risk_mdm.liquid → payments/_compliance_screenings_payments_mdm.liquid} +1 -1
  12. package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_mdm.liquid → payments/_payment_accounts_payments_mdm.liquid} +1 -1
  13. package/.agent/cookbook/_fixtures/{payment_risk/_payment_accounts_payment_risk_payment_account.liquid → payments/_payment_accounts_payments_payment_account.liquid} +1 -1
  14. package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_customer.liquid → subscription/_customers_subscription_customer.liquid} +1 -1
  15. package/.agent/cookbook/_fixtures/{accounts_receivable/_customers_accounts_receivable_mdm.liquid → subscription/_customers_subscription_mdm.liquid} +1 -1
  16. package/.agent/cookbook/_setup/foundation.md +24 -4
  17. package/.agent/cookbook/_setup/healthcare.md +24 -4
  18. package/.agent/cookbook/_setup/{payment_risk.md → payments.md} +51 -31
  19. package/.agent/cookbook/_setup/{accounts_receivable.md → subscription.md} +51 -31
  20. package/.agent/cookbook/action-status-updaters.md +25 -18
  21. package/.agent/cookbook/bulk-ingest.md +15 -15
  22. package/.agent/cookbook/dunning-sms-for-delinquent.md +21 -21
  23. package/.agent/cookbook/{custom-tables.md → generic-tables.md} +44 -41
  24. package/.agent/cookbook/invite-team.md +19 -13
  25. package/.agent/cookbook/kyc-notification-on-account-activation.md +26 -26
  26. package/.agent/cookbook/marketing-campaign-send.md +1003 -0
  27. package/.agent/cookbook/rest-fetch.md +9 -9
  28. package/.agent/cookbook/sanctions-screening-with-agent-review.md +22 -22
  29. package/.agent/cookbook/system-templates.md +15 -15
  30. package/.agent/cookbook/triage-prospects-by-priority.md +17 -17
  31. package/.agent/cookbook/welcome-sms-for-customers.md +21 -21
  32. package/.agent/data_activation_clients.md +177 -42
  33. package/.agent/data_sources.md +55 -37
  34. package/.agent/datalakes.md +30 -17
  35. package/.agent/debugging.md +48 -14
  36. package/.agent/errors.md +39 -17
  37. package/.agent/generic_tables.md +150 -51
  38. package/.agent/interoperability_contracts.md +114 -15
  39. package/.agent/mdm.md +171 -93
  40. package/.agent/messages.md +252 -0
  41. package/.agent/templates.md +21 -4
  42. package/.agent/tool-call-configs.md +1 -1
  43. package/.agent/tools.md +150 -60
  44. package/.agent/type_naming.md +79 -18
  45. package/.agent/workflows.md +408 -62
  46. package/LICENSE +21 -93
  47. package/README.md +2 -2
  48. package/dist/bin/platform-sdk.mjs +53 -1
  49. package/dist/bin/platform-sdk.mjs.map +1 -1
  50. package/dist/index.d.mts +582 -66
  51. package/dist/index.d.mts.map +1 -1
  52. package/dist/index.mjs +654 -105
  53. package/dist/index.mjs.map +1 -1
  54. package/package.json +10 -6
  55. /package/.agent/cookbook/_fixtures/{accounts_receivable → subscription}/stripe_customers_batch1.csv +0 -0
@@ -28,6 +28,7 @@ const debugConfig: ApiDebugConfig = {
28
28
  const api = createIsolatedPlatformApi({
29
29
  baseUrl,
30
30
  sessionToken,
31
+ apiKey, // the tenant's publishable key (X-API-Key)
31
32
  debug: debugConfig,
32
33
  })
33
34
  ```
@@ -69,8 +70,9 @@ type ApiDebugConfig = {
69
70
  ```
70
71
 
71
72
  - `log` is the sink. The SDK emits formatted log messages
72
- (request method + URL + body, response status + body) as
73
- a single string per HTTP exchange.
73
+ (request method + URL + body, response status + URL + body)
74
+ — one call per request and one per response, so TWO calls
75
+ per HTTP exchange, each a separate string.
74
76
  - `redactStrings` is an array of LITERAL values the SDK
75
77
  should scrub from log output. Empty / absent = no
76
78
  redaction (use only when no secrets are in the request
@@ -87,10 +89,14 @@ consumers wrap the `log` callback with their own emitter.
87
89
  error-rendering path includes the offending request body,
88
90
  redact it yourself before rendering. See `errors.md` for
89
91
  the throw mechanism.
90
- - **Response bodies that legitimately contain secrets**.
91
- Server-derived fields that are credentials (rare but
92
- possible) come back un-redacted in the response; the
93
- consumer is responsible for not logging them.
92
+ - **Secrets the server MINTS that you never installed**.
93
+ Response bodies ARE filtered through `redactStrings` — the
94
+ same scrub the request gets — so any literal in your redact
95
+ list is masked whichever direction it travels. But a
96
+ credential the server generates and returns (rare but
97
+ possible) is by definition not in `redactStrings`, so it
98
+ passes through un-masked; the consumer is responsible for
99
+ not logging it.
94
100
  - **Anything OUTSIDE the SDK's HTTP path**. `redactStrings`
95
101
  only filters what the SDK itself writes to `log`. Your own
96
102
  log statements that touch request/response data must
@@ -123,15 +129,43 @@ guarantee a fresh snapshot.
123
129
 
124
130
  ## What's in the log line
125
131
 
126
- A typical log message the SDK emits looks roughly like:
132
+ The SDK fires `log` TWICE per exchange — once for the request
133
+ (prefixed `→`), once for the response (prefixed `←`) — not once
134
+ per round-trip. Each is a separate string. The request line
135
+ carries method + URL; a body, if present, follows on the next
136
+ lines indented four spaces. The response line carries status +
137
+ URL, then its body the same way. A pair looks roughly like:
127
138
 
128
139
  ```
129
- [platform-sdk] POST /api/v1/tenants/acme/datalakes/main/tools
130
- request body: {"name":"...","intent":"data_exchange",
131
- "body":{"tool_body_type":"s3","access_key_id":"********",
132
- "secret_access_key":"********",...}}
133
- response 201: {"id":"...","slug":"...","name":"...",...}
140
+ → POST https://demo.example.com/api/v1/tenants/acme/datalakes/main/tools
141
+ {
142
+ "name": "...",
143
+ "intent": "data_exchange",
144
+ "body": {
145
+ "tool_body_type": "s3",
146
+ "access_key_id": "********",
147
+ "secret_access_key": "********"
148
+ }
149
+ }
150
+ ← 201 https://demo.example.com/api/v1/tenants/acme/datalakes/main/tools
151
+ {
152
+ "id": "...",
153
+ "slug": "...",
154
+ "name": "..."
155
+ }
134
156
  ```
135
157
 
136
- (Format is plain-string; exact prefix and field ordering are
137
- SDK-internal and may evolve.)
158
+ The URL is **absolute** — origin included — by design, not
159
+ path-only. The origin is the only thing distinguishing one
160
+ environment from another: a path-only line reads identically
161
+ whether the call hit localhost or a demo server, which defeats
162
+ the question the log is most often asked, *where did this
163
+ actually go?*. The query string is deliberately omitted (it
164
+ carries filter values, not routing; the body is where those
165
+ are read). Only the request/response BODY is logged — never
166
+ headers, so the `Authorization: Bearer …` and `X-API-Key`
167
+ credentials (see `AGENTS.md` for the two-credentials model)
168
+ never reach the log at all.
169
+
170
+ (Format is plain-string; the `→`/`←` prefixes and field
171
+ ordering are SDK-internal and may evolve.)
package/.agent/errors.md CHANGED
@@ -46,19 +46,23 @@ try {
46
46
  ```
47
47
 
48
48
  The thrown body is typed as `AlveraApiError` (exported from the package root)
49
- for 422s, and the simpler `ErrorResponse` for some other statuses.
49
+ — the JSON:API `errors[]` envelope the platform returns on 4xx. **Both 422
50
+ and 409 carry it** (same shape, different status). A few endpoints declare the
51
+ older field-keyed `ErrorResponse` map (`{ errors: { field: string[] } }`) for a
52
+ 500 instead.
50
53
 
51
- ## 422 envelope shape
54
+ ## The error envelope shape (422 and 409)
52
55
 
53
56
  The platform standardizes ALL 422 response bodies on a single shape —
54
- regardless of which validation layer fired:
57
+ regardless of which validation layer fired — and **409 Conflict bodies use the
58
+ identical shape** (see below for which failures are 409, not 422):
55
59
 
56
60
  ```json
57
61
  {
58
62
  "errors": [
59
63
  {
60
64
  "source": { "pointer": "/<field_path>" },
61
- "title": "<human-readable summary>",
65
+ "title": "Invalid value",
62
66
  "detail": "<specific reason this field failed>"
63
67
  },
64
68
  ...
@@ -67,13 +71,19 @@ regardless of which validation layer fired:
67
71
  ```
68
72
 
69
73
  - `errors` is always an ARRAY of error objects (never a field-keyed map).
70
- - `source.pointer` is a JSON Pointer (`/field_name` for top-level fields;
71
- `/nested/field` for embeds) naming the offending field on the request body.
72
- - `detail` is the specific reason; `title` is a brief summary.
74
+ - `source.pointer` is an RFC 6901 JSON Pointer (`/field_name` for top-level
75
+ fields; `/nested/field` for embeds) naming the offending field on the request
76
+ body.
77
+ - `detail` is the human-readable reason. `title` is a **machine-readable
78
+ category, not a per-field summary**: the constant `"Invalid value"` for every
79
+ validation error (422 and the 409 conflict cases), the status reason phrase
80
+ (`"Conflict"`, `"Not Found"`, …) for status-only errors, and a stage code
81
+ (`"transform_failed"`, `"template_body_missing"`, …) for `/run` pipeline
82
+ errors. Pattern-match on `title` for dispatch; show `detail` to a human.
73
83
  - Multiple errors may share the same `source.pointer` if more than one check
74
84
  fired on the same field.
75
85
 
76
- ## Two layers behind the standardized 422
86
+ ## Two layers behind the standardized envelope
77
87
 
78
88
  The platform validates a request in two layers; both surface through the
79
89
  same envelope above:
@@ -94,8 +104,15 @@ fields), foreign-key constraints, custom platform validations. Layer-2
94
104
  errors are normalized into the same envelope shape as layer 1 — consumers
95
105
  don't distinguish layers from the JSON.
96
106
 
97
- Practical consequence: every validation error reaches you as a thrown 422
98
- body. Read `source.pointer`, fix that field, resubmit.
107
+ **But layer 2 is not always a 422.** The envelope is identical; the *status*
108
+ depends on the failure. Ordinary field validation (`"can't be blank"`,
109
+ `"is invalid"`, a custom `add_error` rule) is **422**. A failure that collides
110
+ with the current state of the resource is **409 Conflict**: a **uniqueness
111
+ collision** (`unique_constraint` / `unsafe_validate_unique`) or a **delete
112
+ blocked by dependants** (a foreign-key/assoc constraint firing on delete). So
113
+ do not assume every semantic conflict is a tidy 422 — read `_httpStatus`, not
114
+ just the body. Read `source.pointer`, fix the field (or resolve the collision),
115
+ resubmit.
99
116
 
100
117
  ## Concrete examples
101
118
 
@@ -124,8 +141,9 @@ body):
124
141
  }
125
142
  ```
126
143
 
127
- **Layer 2 — semantic rule** (`delete()` on a default-flagged data activation
128
- client):
144
+ **Layer 2 — semantic rule → 422** (`delete()` on a default-flagged data
145
+ activation client). A custom `add_error` rule (not a uniqueness/FK constraint)
146
+ stays a **422**, unlike the uniqueness case below:
129
147
 
130
148
  ```json
131
149
  {
@@ -136,13 +154,15 @@ client):
136
154
  }
137
155
  ```
138
156
 
139
- **Layer 2 — uniqueness** (`invitations.create()` for an already-invited
140
- email):
157
+ **Layer 2 — uniqueness → 409, not 422** (`invitations.create()` for an
158
+ already-invited email). Same `errors[]` envelope, but a uniqueness collision
159
+ comes back as a **409 Conflict** (`_httpStatus === 409`):
141
160
 
142
161
  ```json
143
162
  {
144
163
  "errors": [
145
164
  { "source": { "pointer": "/email" },
165
+ "title": "Invalid value",
146
166
  "detail": "is already invited" }
147
167
  ]
148
168
  }
@@ -163,14 +183,16 @@ platform maps:
163
183
  | 401 | Missing or invalid Bearer / `x-api-key` |
164
184
  | 403 | Authenticated but role lacks permission |
165
185
  | 404 | Resource doesn't exist OR cross-tenant access (404, not 403) |
186
+ | 409 | Uniqueness collision, delete blocked by dependants, or URL/body id mismatch — same `errors[]` envelope |
166
187
  | 422 | Validation failed; envelope above is the thrown body |
167
188
  | 5xx | Platform-internal failure; safe to retry with backoff |
168
189
 
169
190
  ## Retry semantics
170
191
 
171
- Treat 5xx as infra noise — retry with exponential backoff. Treat 422 as a
172
- real consumer-correctable error — fix the body and resubmit. **Never retry a
173
- 422 with the same body.**
192
+ Treat 5xx as infra noise — retry with exponential backoff. Treat 422 (and the
193
+ 409 conflict cases) as a real consumer-correctable error — fix the body, or
194
+ resolve the collision, then resubmit. **Never retry a 422 or 409 with the same
195
+ body** — the failure won't clear on its own.
174
196
 
175
197
  ## Mapping `source.pointer` back to your TypeScript type
176
198
 
@@ -11,6 +11,29 @@ in the datalake's schema. The parent datalake MUST be
11
11
  `status: 'ready'` before the job can run end-to-end — see
12
12
  `datalakes.md` §5 Lifecycle.
13
13
 
14
+ > ## ⚠ `api.genericTables` manages table DEFINITIONS, never rows
15
+ >
16
+ > This namespace is DDL, not DML. It creates, updates (see §2), reads,
17
+ > and deletes the *table* — its schema. **It does not write rows.**
18
+ > There is **no** `POST /generic-tables/:id/rows`, no `insertRow`, no
19
+ > `updateRow` — the endpoint an agent reaches for does not exist.
20
+ >
21
+ > **Rows are written by exactly one path: a bound data activation
22
+ > client's `.ingest` / `.ingestFile`** (see `data_activation_clients.md`).
23
+ > Ingest is asynchronous — it returns **`202` + a batch id, NOT the
24
+ > saved row.** Every "Save" you see in a CRUD-looking UI over a generic
25
+ > table is an ingest under the hood, and it lands eventually, not
26
+ > inline.
27
+ >
28
+ > - To **seed / add rows**: `.ingest` through the table's default
29
+ > manual-upload DAC (gotcha 7).
30
+ > - To **edit a row**: re-ingest it with the same unique-column value —
31
+ > ingest is an **upsert** (full-row replace on the unique key), so
32
+ > "update row X" is just "ingest X again with new values". There is
33
+ > no partial row patch.
34
+ > - To **read rows**: `api.datasets.search` (paged) or
35
+ > `api.datalakes.executeSql` (SQL) — never a `genericTables` verb.
36
+
14
37
  ## 1. Wire shape
15
38
 
16
39
  ```typescript
@@ -46,15 +69,31 @@ const { data: created } = await api.genericTables.create(
46
69
 
47
70
  The response returns immediately — the row exists in Platform-DB,
48
71
  but the *physical* Postgres table does not yet. Consumers MUST
49
- poll `.get(name)` until `status === 'deployed'` before treating
50
- the table as queryable. See §5 Lifecycle.
72
+ poll `.get(id)` until `status === 'deployed'` before treating
73
+ the table as queryable. See §5 Lifecycle. (**`.get` keys on the
74
+ UUID `id`, not `name`** — see §2.)
51
75
 
52
76
  ## 2. Rules the type cannot encode
53
77
 
54
- ### `name` is server-derived from `title`
78
+ ### Two identifiers: the UUID `id` (API key) vs the `name` (SQL table)
79
+
80
+ A created generic table carries **two** server-derived identifiers,
81
+ and they are used in different places — mixing them up is the most
82
+ common mistake against this resource:
83
+
84
+ ```
85
+ id server-derived UUID — the API path key AND the FK.
86
+ .get(id) / .update(id) / .delete(id) all
87
+ take it, and workflows / DACs / contracts
88
+ reference the table via generic_table_id = id.
89
+ name 'alvera_custom_<slug>' — the PHYSICAL Postgres table name.
90
+ Used in executeSql (`FROM alvera_custom_…`)
91
+ and to recognise the table's auto-provisioned
92
+ DAC by name. NOT an API path key.
93
+ ```
55
94
 
56
- Caller supplies `title` (free-form, human-readable);
57
- server slugifies it and prefixes `alvera_custom_`:
95
+ `name` is server-derived from `title` — slugify + `alvera_custom_`
96
+ prefix:
58
97
 
59
98
  ```
60
99
  title: 'Contact Us Submissions'
@@ -62,13 +101,13 @@ title: 'Contact Us Submissions'
62
101
  name: 'alvera_custom_contact_us_submissions'
63
102
  ```
64
103
 
65
- The `name` is what every downstream resource references —
66
- `.get(name)`, `generic_table_id` foreign keys via the resolved
67
- row, `datasets.metadataDetails(tenantSlug, datalakeSlug, 'generic_table', { genericTableId })`,
68
- etc. Never pre-compute `name` client-side; read it back from
69
- the create response. A server-side slugifier change would flip
70
- every downstream binding, so specs assert the derived `name`
71
- directly.
104
+ **`.get` / `.update` / `.delete` key on the UUID `id`, NOT `name`.**
105
+ Passing `name` (or any non-UUID) to `.get` 422s with `Invalid format.
106
+ Expected :uuid` — the same id/slug trap as other resources. To go from
107
+ a known `name` back to its `id`, `list()` with a `handle` filter and
108
+ read the row's `id`. Never pre-compute either identifier client-side —
109
+ read both back from the create response and pass `id` to CRUD,
110
+ `name` to `executeSql`.
72
111
 
73
112
  ### `columns` is operator-authored schema
74
113
 
@@ -121,11 +160,14 @@ for the tier split):
121
160
 
122
161
  Two type-level restrictions the typed validator does not encode:
123
162
 
124
- - **`type: 'jsonb'` rejects `privacy_requirement: 'tokenize'`.**
125
- The platform can't tokenize an arbitrary JSON document — there
126
- is no canonical "identity" to tokenize. Valid privacy values
127
- for jsonb are `'none'` and `'redact_only'` only. Submitting
128
- `{ type: 'jsonb', privacy_requirement: 'tokenize' }` returns
163
+ - **`type: 'jsonb'` REQUIRES `privacy_requirement: 'redact_only'` —
164
+ `'none'` is rejected too, not just `'tokenize'`.** The platform
165
+ can't tokenize an arbitrary JSON document (no canonical
166
+ "identity" to tokenize), and it won't let an unredacted JSON
167
+ blob flow into the unregulated tier either. `'redact_only'` is
168
+ the ONLY valid privacy value for a jsonb column — submitting
169
+ `{ type: 'jsonb', privacy_requirement: 'tokenize' }` OR
170
+ `{ type: 'jsonb', privacy_requirement: 'none' }` both return
129
171
  422 on `/columns/N/privacy_requirement`.
130
172
  - **Tokenize widens primitive types at the schema layer.** A
131
173
  `{ type: 'integer', privacy_requirement: 'tokenize' }` column
@@ -136,8 +178,10 @@ Two type-level restrictions the typed validator does not encode:
136
178
  This affects `integer`, `float`, `boolean`, `is_array string`,
137
179
  `date`, `datetime`, and `time`.
138
180
 
139
- The privacy choice is **immutable post-create** — there is no
140
- SDK mutation surface for column-level privacy changes.
181
+ The privacy choice is **immutable post-create** — `update()` exists
182
+ but its migration is additive-only and never re-privacy's an existing
183
+ column (see §2 update note), so the only way to change a column's
184
+ `privacy_requirement` is `delete()` + `create()`.
141
185
 
142
186
  **Privacy is operator-decided per column, not implied by name.**
143
187
  A field called `message` can be `redact_only` in one tenant and
@@ -168,7 +212,7 @@ in `columns[N].name`:
168
212
  ```
169
213
  healthcare patient_id
170
214
  core_banking party_id
171
- accounts_receivable customer_id
215
+ subscription customer_id
172
216
  (other domains as they land)
173
217
  ```
174
218
 
@@ -187,13 +231,30 @@ create with 422 on `/title`. Pick a title that slugifies to
187
231
  something else (e.g. avoid leading "Alvera System" in the title
188
232
  text).
189
233
 
190
- ### No update surface
191
-
192
- There is **no `update()`** for generic tables.
193
- Generic tables are schema-immutable post-create — to change
194
- columns, `delete()` and `create()` fresh. This is a deliberate
195
- constraint: mutating a deployed schema mid-ingestion would race
196
- the data activation client.
234
+ ### `update()` exists — but the schema migration is ADDITIVE-only
235
+
236
+ There **is** an `update()` (`PUT /generic-tables/:id`, full-replace —
237
+ the same body shape as `create`, all fields required). It exists so a
238
+ declarative `alvera apply` can resend a table's full manifest and
239
+ reconcile drift. On update the platform re-runs the schema migration
240
+ for the new column set — but the migration is **strictly additive**:
241
+
242
+ - **New columns in the body are added** to the physical table
243
+ (test-pinned) and to the regulated mirror.
244
+ - **Columns you omit are NOT dropped.** The migration never
245
+ auto-drops a column ("keep down as noop to avoid destructive
246
+ change"), so a shrunken `columns` array does not remove storage.
247
+ - **Existing columns are NOT retyped or re-privacy'd.** The additive
248
+ migration only adds; it does not `ALTER` an existing column's type
249
+ or `privacy_requirement`.
250
+
251
+ So `update()` is the right tool to **add a column** to a live table
252
+ without losing data. To **drop or retype** a column you still
253
+ `delete()` + `create()` fresh — the additive migration won't do it,
254
+ and column `privacy_requirement` remains immutable in place (§2 privacy
255
+ note). One validation guardrail: an update that would leave the table
256
+ with **zero** `is_unique` columns is rejected (422), same rule as
257
+ create.
197
258
 
198
259
  ## 3. Field ownership
199
260
 
@@ -202,7 +263,9 @@ the data activation client.
202
263
 
203
264
  ```
204
265
  name string — `alvera_custom_<slugified-title>`
205
- status enum — 'new' | 'processing' | 'deployed' | 'failed'
266
+ status enum — 'new' | 'processing' | 'deployed' | 'stale'
267
+ (no 'failed' — a failed migration just never
268
+ reaches 'deployed'; 'stale' = drifted definition)
206
269
  ```
207
270
 
208
271
  **Caller-supplied (round-trip).**
@@ -252,29 +315,37 @@ const { data: created } = await api.genericTables.create(
252
315
  )
253
316
  // created.status === 'new' (or 'processing' if worker raced)
254
317
 
255
- while (true) {
318
+ const deadline = Date.now() + 60_000
319
+ while (Date.now() < deadline) {
256
320
  const { data: row } = await api.genericTables.get(
257
- tenantSlug, datalakeSlug, created.name,
321
+ tenantSlug, datalakeSlug, created.id, // UUID id, NOT created.name
258
322
  )
259
323
  if (row.status === 'deployed') break
260
- if (row.status === 'failed') throw new Error('migration failed')
261
324
  await new Promise((r) => setTimeout(r, 1_000))
262
325
  }
263
326
  ```
264
327
 
265
- `.get(name)` distinguishes "row never created" (404) from
266
- "deployment in progress" (200 with status sub-`deployed`) —
267
- two distinct signals on the same endpoint. Use the 404 to
268
- short-circuit retry loops; use the 200+status to drive the
269
- poll above.
328
+ **The status enum has no terminal-failure value** — it is `new →
329
+ processing → deployed` (plus `stale`, an already-deployed table whose
330
+ definition drifted; never a fresh-create state). A migration that
331
+ fails does not flip to a `failed` status; the row simply never reaches
332
+ `deployed`, so bound the poll with a **timeout** (as above) rather than
333
+ watching for a failure value. (This is the same timeout-bounded idiom
334
+ the validated `cookbook/generic-tables.md` runs, passing the UUID
335
+ `id`.) `.get(id)` distinguishes "row never
336
+ created" (404) from "deployment in progress" (200 with a
337
+ sub-`deployed` status) — two distinct signals on the same endpoint.
338
+ Use the 404 to short-circuit retry loops; use the 200+status to drive
339
+ the poll above.
270
340
 
271
341
  ### Read shapes
272
342
 
273
343
  ```
274
- .list(tenantSlug, datalakeSlug) Paged: { data, meta }
275
- .get(tenantSlug, datalakeSlug, name) One row, by name
276
- (NOT slug — generic
277
- tables expose `name`)
344
+ .list(tenantSlug, datalakeSlug, query?) Paged: { data, meta }
345
+ (full Flop query — type_naming.md)
346
+ .get(tenantSlug, datalakeSlug, id) One row, by UUID id
347
+ (NOT name/slug; resolve a
348
+ name → id via list + handle filter)
278
349
  ```
279
350
 
280
351
  Plus the polymorphic dataset surface for per-table markdown:
@@ -298,6 +369,18 @@ See `datalakes.md` §5 `.systemDatasets` for the system-dataset
298
369
  sibling of this verb; the `'generic_table'` kind is the entry
299
370
  point for generic-table metadata.
300
371
 
372
+ ### Update
373
+
374
+ `update(tenantSlug, datalakeSlug, id, body)` — `PUT`, full-replace
375
+ (same body shape as `create`, addressed by **UUID `id`**, not `name`).
376
+ Re-runs the schema migration for the new column set, **additively**:
377
+ new columns are added; omitted columns are not dropped; existing
378
+ columns are not retyped (see §2). Its intended use is declarative
379
+ drift reconciliation (`alvera apply` resends the whole manifest) and
380
+ adding a column to a live table without data loss. Rejected (422) if
381
+ the new column set has no `is_unique` column. It writes the schema, not
382
+ rows (rows still flow through the DAC — see the box at the top).
383
+
301
384
  ### Delete
302
385
 
303
386
  `delete()` removes the row and drops the physical table. Tables
@@ -307,12 +390,15 @@ dependency. Detach dependents first.
307
390
 
308
391
  ## 6. Gotchas
309
392
 
310
- 1. **`.get` takes `name`, not `slug`.** Generic tables expose
311
- `name` as the canonical reference; the `slug` field — if
312
- present on `GenericTableResponse` — is incidental and
313
- currently unused by downstream resources. Stash `data.name`
314
- from create; pass it to `.get` and to every downstream
315
- `generic_table` binding.
393
+ 1. **`.get` / `.update` / `.delete` take the UUID `id`, not `name`.**
394
+ The API path key is the UUID `id`, and downstream bindings
395
+ (`generic_table_id` on workflows / DACs / contracts) are that same
396
+ `id`. The `name` (`alvera_custom_<slug>`) is the *physical SQL table
397
+ name* — for `executeSql` and for recognising the table's
398
+ auto-provisioned DAC — not an API key. Stash **both** `data.id` and
399
+ `data.name` from create: `id` for CRUD + bindings, `name` for SQL.
400
+ Passing `name` to `.get` 422s (`Invalid format. Expected :uuid`);
401
+ resolve `name → id` via `list()` with a `handle` filter (§2).
316
402
 
317
403
  2. **`status` reaches `deployed` asynchronously.** A bare
318
404
  `.create` response with `status: 'new'` is NOT yet bindable.
@@ -325,8 +411,9 @@ dependency. Detach dependents first.
325
411
  `tokenize` columns surface as an opaque stable token in the
326
412
  unregulated tier; `redact_only` strips the value from that
327
413
  tier entirely; `none` keeps the raw value only in the
328
- regulated tier. There is no update surface to flip this —
329
- recreate the table to change.
414
+ regulated tier. `update()`'s additive migration never re-privacy's
415
+ an existing column, so recreate the table to change a column's
416
+ privacy.
330
417
 
331
418
  4. **System-dataset enumeration EXCLUDES generic tables.**
332
419
  `api.datalakes.systemDatasets(...)` returns only the
@@ -346,6 +433,18 @@ dependency. Detach dependents first.
346
433
  `submission_id`, `name`, `email`) sit alongside columns
347
434
  reserved for downstream resources to update (e.g. a reply
348
435
  column written by a workflow, or a scoring column written
349
- by an agent). Plan the column set for the full lifecycle,
350
- not just the inbound shape — adding columns later requires
351
- delete + recreate.
436
+ by an agent). Plan the column set for the full lifecycle —
437
+ though you CAN **add** a forgotten column later via `update()`'s
438
+ additive migration (§2), without losing data. Dropping or
439
+ retyping still needs delete + recreate.
440
+
441
+ 7. **A new generic table auto-provisions a default manual-upload
442
+ DAC — ingest through it, don't create one.** Alongside the
443
+ identity contract (see `interoperability_contracts.md` §5), the
444
+ platform stands up a default data activation client named
445
+ `"<Datalake Name> <table> DataActivationClient"` (`is_default:
446
+ true`) for every generic table, so a table is immediately
447
+ ingestable with no extra declaration. To seed rows, discover
448
+ that default DAC by name/`is_default` and `.ingest` through it —
449
+ never hand-create a second DAC (untracked, non-idempotent,
450
+ collides on re-run). See `data_activation_clients.md` §2.