@alvera-ai/platform-sdk 0.10.0-rc.18 → 0.10.0-rc.19

package/.agent/AGENTS.md

@@ -66,7 +66,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)   | `custom_datasets.md`, `mdm.md`                |
+| Resources             | Datasets (per data domain)   | `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`                                    |
@@ -159,7 +159,7 @@ clobbers earlier instances' auth.
 
    DATA ACTIVATION  (how data flows in)
    ───────────────
-   custom_datasets.md            Schema-on-write tables.
+   generic_tables.md            Schema-on-write tables.
    interoperability_contracts.md Liquid template mappings.
    data_activation_clients.md    Ingestion pipelines — both the
                                   binding row (CRUD) and the
@@ -192,7 +192,7 @@ wire name (snake_case):
     api.actionStatusUpdaters            action_status_updaters.md
     api.connectedApps                   connected_apps.md
     api.mdm                             mdm.md
-    api.genericTables                   custom_datasets.md
+    api.genericTables                   generic_tables.md
     api.interoperabilityContracts       interoperability_contracts.md
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md

package/.agent/cookbook/_setup/accounts_receivable.md

@@ -87,7 +87,7 @@ ctx.sarahTenantlessApi = createIsolatedPlatformApi({
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
   name: `Cookbook Accounts Receivable ${runSuffix}`,
 })
-tenantSlug = tenantResp.data.tenant!.slug!
+tenantSlug = tenantResp.data.slug!
 ```
 
 ## 003 — sarah signs in tenant-scoped — the canonical client

package/.agent/cookbook/_setup/foundation.md

@@ -85,7 +85,7 @@ ctx.sarahTenantlessApi = createIsolatedPlatformApi({
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
   name: `Cookbook Foundation ${runSuffix}`,
 })
-tenantSlug = tenantResp.data.tenant!.slug!
+tenantSlug = tenantResp.data.slug!
 ```
 
 ## 003 — sarah signs in tenant-scoped — the canonical client

package/.agent/cookbook/_setup/healthcare.md

@@ -85,7 +85,7 @@ ctx.sarahTenantlessApi = createIsolatedPlatformApi({
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
   name: `Cookbook Healthcare ${runSuffix}`,
 })
-tenantSlug = tenantResp.data.tenant!.slug!
+tenantSlug = tenantResp.data.slug!
 ```
 
 ## 003 — sarah signs in tenant-scoped — the canonical client

package/.agent/cookbook/_setup/payment_risk.md

@@ -87,7 +87,7 @@ ctx.sarahTenantlessApi = createIsolatedPlatformApi({
 const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
   name: `Cookbook Payment Risk ${runSuffix}`,
 })
-tenantSlug = tenantResp.data.tenant!.slug!
+tenantSlug = tenantResp.data.slug!
 ```
 
 ## 003 — sarah signs in tenant-scoped — the canonical client

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -5,7 +5,7 @@ industry: healthcare
 slug: contact-us-triage-with-llm
 vitest_source:
   - integration-tests/tests/healthcare/agent-driven-workflow.test.ts
-  - integration-tests/tests/healthcare/custom-datasets.test.ts
+  - integration-tests/tests/healthcare/generic-tables.test.ts
   - integration-tests/tests/healthcare/tools.test.ts
   - integration-tests/tests/healthcare/bootstrap.test.ts
 status: green
@@ -34,7 +34,7 @@ Three SMS actions are registered against the workflow, one per
 bucket; the agent's output picks which one runs.
 
 This cookbook walks the **whole** scenario: it provisions the
-custom dataset, agent, and workflow, ingests three contact-us
+generic table, agent, and workflow, ingests three contact-us
 submissions through the generic-table's auto-provisioned default
 DAC, runs the workflow so the agent classifies each row, and
 verifies the routing row-by-row — every Workflow Execution Log
@@ -58,7 +58,7 @@ this cookbook starts from there.
 | Contact Us Triage AI agent          | build       |
 | Contact Us Triage workflow          | build       |
 
-The custom dataset's **default DAC** — auto-provisioned by the
+The generic table's **default DAC** — auto-provisioned by the
 platform when the generic table is created — is reused for
 ingestion; no separate data source / tool / interop contract / DAC
 is created. The setup file `_setup/healthcare.md` already
@@ -67,7 +67,7 @@ cookbook starts from there.
 
 # Walkthrough
 
-## 001 — create the Contact Us submissions custom dataset
+## 001 — create the Contact Us submissions generic table
 
 The agent-driven workflow targets a Generic Table dataset
 (`dataset_type: 'generic_table'`) rather than a regulated domain
@@ -79,7 +79,7 @@ The server-derived `name` is captured — the workflow run in §009
 addresses the regulated table as `regulated_<name>`.
 
 ```typescript
-const customDatasetResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
+const genericTableResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
   title: `Cookbook Contact Us ${runSuffix}`,
   description: 'Inbound contact-us form submissions the Triage agent classifies.',
   columns: [
@@ -125,8 +125,8 @@ const customDatasetResp = await api.genericTables.create(tenantSlug, datalakeSlu
     },
   ],
 })
-customDatasetId = customDatasetResp.data.id!
-ctx.gtName = customDatasetResp.data.name!
+genericTableId = genericTableResp.data.id!
+ctx.gtName = genericTableResp.data.name!
 ```
 
 ## 002 — create the SMS tool
@@ -286,7 +286,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   name: `Cookbook Contact Us Triage Workflow ${runSuffix}`,
   description: 'Triages contact-us submissions into appointment_request/job_inquiry/flag_spam via an LLM agent; one SMS action per bucket.',
   dataset_type: 'generic_table',
-  generic_table_id: customDatasetId,
+  generic_table_id: genericTableId,
   skip_mdm_resolution: true,
   status: 'live',
   filter_config: {
@@ -593,11 +593,11 @@ end-to-end, not merely provisioned.
 - `.agent/workflows.md` — standard and agent-driven workflow
   primitives; `ai_agents`, `context_mapping_config`, and
   agent-output decision interpolation
-- `.agent/custom_datasets.md` — generic-table creation and the
+- `.agent/generic_tables.md` — generic-table creation and the
   auto-provisioned identity contract + default DAC
 - `integration-tests/tests/healthcare/agent-driven-workflow.test.ts` —
   the anchor green test (positive branch §1, §3, §4, §6, §7) these
   snippets are lifted from
-- `integration-tests/tests/healthcare/custom-datasets.test.ts`,
+- `integration-tests/tests/healthcare/generic-tables.test.ts`,
   `tools.test.ts` — the per-resource create snippets are lifted
   from

package/.agent/cookbook/score-leads-with-llm-categorization.md

@@ -5,7 +5,7 @@ industry: foundation
 slug: score-leads-with-llm-categorization
 vitest_source:
   - integration-tests/tests/foundation/agent-driven-workflow.test.ts
-  - integration-tests/tests/foundation/custom-datasets.test.ts
+  - integration-tests/tests/foundation/generic-tables.test.ts
   - integration-tests/tests/foundation/tools.test.ts
   - integration-tests/tests/foundation/bootstrap.test.ts
 status: green
@@ -55,13 +55,13 @@ cookbook starts from there.
 
 | Resource provisioned             | Owner       |
 |----------------------------------|-------------|
-| Lead Submissions custom dataset  | build       |
+| Lead Submissions generic table  | build       |
 | SMS tool (SNS-backed)            | build       |
 | LLM tool (Ollama chat completion)| build       |
 | Score Lead AI agent              | build       |
 | Score Lead workflow              | build       |
 
-The custom dataset's **default DAC** — auto-provisioned by the
+The generic table's **default DAC** — auto-provisioned by the
 platform when the generic table is created — is reused for ingestion;
 no separate data source / tool / interop contract / DAC is created.
 The setup file `_setup/foundation.md` already provisioned the tenant +
@@ -69,7 +69,7 @@ datalake + tenant-scoped client; this cookbook starts from there.
 
 # Walkthrough
 
-## 001 — create the Lead Submissions custom dataset
+## 001 — create the Lead Submissions generic table
 
 The agent-driven workflow targets a Generic Table dataset
 (`dataset_type: 'generic_table'`) rather than a regulated domain
@@ -81,7 +81,7 @@ in production. The server-derived `name` is captured — the workflow
 run in §009 addresses the regulated table as `regulated_<name>`.
 
 ```typescript
-const customDatasetResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
+const genericTableResp = await api.genericTables.create(tenantSlug, datalakeSlug, {
   title: `Cookbook Lead Submissions ${runSuffix}`,
   description: 'Inbound lead-capture form rows the Score Lead agent classifies.',
   columns: [
@@ -135,8 +135,8 @@ const customDatasetResp = await api.genericTables.create(tenantSlug, datalakeSlu
     },
   ],
 })
-customDatasetId = customDatasetResp.data.id!
-ctx.gtName = customDatasetResp.data.name!
+genericTableId = genericTableResp.data.id!
+ctx.gtName = genericTableResp.data.name!
 ```
 
 ## 002 — create the SMS tool
@@ -294,7 +294,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   name: `Cookbook Score Lead Workflow ${runSuffix}`,
   description: 'Classifies lead_submissions into hot/warm/cold/spam via an LLM agent; one SMS action per band.',
   dataset_type: 'generic_table',
-  generic_table_id: customDatasetId,
+  generic_table_id: genericTableId,
   skip_mdm_resolution: true,
   status: 'live',
   filter_config: {
@@ -590,13 +590,13 @@ provisioned.
 - `.agent/workflows.md` — standard and agent-driven workflow
   primitives; `ai_agents`, `context_mapping_config`, and agent-output
   decision interpolation
-- `.agent/custom_datasets.md` — generic-table creation and the
+- `.agent/generic_tables.md` — generic-table creation and the
   auto-provisioned identity contract + default DAC
 - `.agent/ai_sandbox.md` — bounds on the Liquid sandbox the
   context-mapping and decision templates execute inside
 - `integration-tests/tests/foundation/agent-driven-workflow.test.ts` —
   the anchor green test (§1–§5) these snippets are lifted from
-- `integration-tests/tests/foundation/custom-datasets.test.ts` — §2 the
+- `integration-tests/tests/foundation/generic-tables.test.ts` — §2 the
   Generic Table create snippet is lifted from
 - `integration-tests/tests/foundation/tools.test.ts` — the SMS tool
   create snippet is lifted from

package/.agent/data_activation_clients.md

@@ -89,7 +89,7 @@ A single activation client can bind:
 
 - one or more `custom` / `system` contracts (e.g. patient +
   appointment for a multi-resource ingestion), OR
-- a single `identity` contract bound to a custom dataset
+- a single `identity` contract bound to a generic table
   (the auto-created identity contract from
   `interoperability_contracts.md` §5).
 
@@ -489,7 +489,7 @@ first.
    Cross-datalake references return 404 on the offending id.
 
 4. **Custom-dataset identity contracts get their own
-   activation client.** When you ingest into a custom dataset,
+   activation client.** When you ingest into a generic table,
    bind the table's auto-created identity contract (see
    `interoperability_contracts.md` §5) to a dedicated activation
    client. Don't mix it with non-identity contracts on the

package/.agent/data_sources.md

@@ -125,10 +125,10 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/status`                          | value not in the typed enum                      |
 | `/is_default`                      | another source already marked default            |
 
-Client-side: `vDataSourceRequestWritable` catches structural
-issues before submit as `ValiError`. Server-side semantic
-rejections (uniqueness, is_default conflict) come back as
-422 thrown from the SDK on submit. See `errors.md`.
+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`.
 
 ## 5. Lifecycle
 

package/.agent/datalakes.md

@@ -33,11 +33,11 @@ import type {
   DatalakeRequestWritable,
   DatalakeResponse,
 } from '@alvera-ai/platform-sdk'
-import { vDatalakeRequestWritable } from '@alvera-ai/platform-sdk'
 ```
 
-See `type_naming.md` for the `Writable` / `v`-prefix conventions
-and the universal server-derived field set.
+See `type_naming.md` for the `Writable` convention and the
+universal server-derived field set. (The SDK exports types only —
+there is no runtime validator; validation is server-authoritative.)
 
 ### Polymorphic cloud-storage embed
 
@@ -322,10 +322,9 @@ The platform returns a standardized JSON:API envelope — see
 { pointer }, title, detail }, ...] }`) and the two-layer
 validation model (structural cast → server-side semantic check).
 
-Validator-rejected requests throw `ValiError` synchronously,
-before any HTTP round-trip — same envelope shape as the server
-returns. See `errors.md` "Client-side validation" for the typed
-narrowing pattern.
+All validation errors come back from the server as a thrown 422
+`AlveraApiError` (the SDK does not validate client-side). See
+`errors.md` for the typed narrowing pattern.
 
 Datalake-specific common rejections:
 
@@ -451,11 +450,9 @@ instead.
 cloud-storage embeds' `access_key_id` / `secret_access_key` — are
 write-only: present on the request type, absent from the response
 type. A naive spread of `current` into the PUT body is therefore
-missing those 8 required fields. The validator
-(`vDatalakeRequestWritable`) catches this client-side as a
-`ValiError`; submitting without pre-validation throws the
-equivalent envelope from the server (see `errors.md`). Re-supply
-them explicitly from your secret store:
+missing those 8 required fields. The server rejects this with a 422
+`AlveraApiError` pointing at the missing fields (see `errors.md`).
+Re-supply them explicitly from your secret store:
 
 ```typescript
 const { data: current } = await api.datalakes.get(tenantSlug, datalakeId)
@@ -591,7 +588,7 @@ for (const name of catalog.datasets) {
 
 1. **POST does NOT auto-enqueue migration.** The create response
    returns immediately with `status: 'new'`; Datalake-DB-resident
-   downstream resources (tools, AI agents, custom datasets,
+   downstream resources (tools, AI agents, generic tables,
    interoperability contracts, data activation clients,
    workflows) MUST wait for `ready` (see §5 Lifecycle for the
    storage-location split). The canonical sequence:
@@ -656,8 +653,8 @@ for (const name of catalog.datasets) {
    would have hit the conflict.
 
 6. **`iam_role` auth still requires a `*_pass` value structurally.**
-   The TypeScript type and the valibot validator both treat the
-   field as a required string. Supply a sentinel literal (e.g.
+   The TypeScript type (and the server's schema) treat the field as
+   a required string. Supply a sentinel literal (e.g.
    `"unused-iam-role"`); the platform clears it server-side.
 
 7. **`cloud_storage_type` lives inside each embed, not at the

package/.agent/debugging.md

@@ -45,9 +45,9 @@ HTTP traffic at all — nothing to redact.
 
 ## Safety: the load-bearing piece
 
-The SDK never sees secret REFERENCES (`${secrets.X}` syntax
-is a consumer-side convention used by some — CLI manifests,
-for instance). By the time a request body reaches the SDK,
+The SDK never sees secret REFERENCES (`<%= name %>` Eta
+syntax is a consumer-side convention used by some — CLI
+manifests, for instance). By the time a request body reaches the SDK,
 credentials are already substituted to their literal values.
 If you enable debug logging without populating
 `redactStrings`, those literals appear in plaintext in your

package/.agent/errors.md

@@ -1,56 +1,29 @@
 # Errors
 
-When you call an SDK method, three things can happen:
+When you call an SDK method, two things can happen:
 
 1. **Success** — `{ data, meta? }` returned (typed).
-2. **Synchronous `ValiError`** — the SDK's valibot validator
-   rejected your input BEFORE any HTTP call.
-3. **Asynchronous throw** — the SDK threw the server's response
-   body verbatim after the HTTP call returned non-2xx.
+2. **Throw** — the SDK throws the server's response body verbatim after
+   the HTTP call returned a non-2xx status.
 
-Consumers handle (2) and (3) with try/catch. The two cases
-differ in WHEN they fire and what the thrown value looks like.
+The SDK does **not** validate request bodies on the client. Validation is
+server-authoritative: a malformed body is rejected by the platform and
+surfaced to you as a thrown **422** body. There is no synchronous
+client-side validation error to catch — every validation failure comes back
+from the server in the standardized envelope below.
 
-## Client-side: ValiError (no network)
+> Driving the platform through the `alvera` **CLI** instead of the SDK? Then
+> `alvera plan` runs a local pre-flight check against the spec and reports
+> errors *before* any HTTP call. That's a CLI feature (it validates the spec
+> locally); it is not SDK runtime behavior. SDK callers get errors from the
+> server.
 
-Every resource has a generated valibot validator
-(`v<Resource>RequestWritable`). The SDK runs this validator on
-the request body BEFORE issuing the HTTP call. If your input
-fails the validator, the SDK throws a `ValiError` synchronously
-— nothing reaches the platform.
+## The thrown value (post-HTTP)
 
-```typescript
-import { ValiError } from 'valibot'
-
-try {
-  const { data } = await api.tools.create(
-    tenantSlug, datalakeSlug, body,
-  )
-} catch (err) {
-  if (err instanceof ValiError) {
-    // err.issues is an array of valibot issues; each has
-    // .path (a JSON-pointer-like path) and .message
-    for (const issue of err.issues) {
-      // issue.path is an array of path segments;
-      // issue.message is the failure reason.
-    }
-    return
-  }
-  throw err   // re-throw anything not a ValiError
-}
-```
-
-Layer-1 errors (missing required, wrong type, invalid enum,
-format violations) almost always fire here client-side.
-Running the validator client-side avoids wasted HTTP round-
-trips — consumers should NOT bypass it on mutations.
-
-## Server-side: SDK throw (post-HTTP)
-
-When the platform returns a non-2xx status, **the SDK throws the
-parsed response body verbatim** as the thrown value — not an
-`Error` subclass, just the body object. Consumers narrow it with
-a type guard:
+When the platform returns a non-2xx status, **the SDK throws the parsed
+response body verbatim** as the thrown value — not an `Error` subclass, just
+the body object (decorated with an `_httpStatus` field so you can branch on
+the status). Narrow it with a type guard:
 
 ```typescript
 try {
@@ -78,17 +51,13 @@ try {
 }
 ```
 
-This path is reserved for cases the client-side validator
-couldn't catch (layer 2 below): uniqueness, cross-field
-semantic rules, foreign-key constraints. If you see this
-thrown body and the same input passes valibot, the failure
-is a server-side semantic rule the OpenAPI spec can't
-express.
+The thrown body is typed as `AlveraApiError` (exported from the package root)
+for 422s, and the simpler `ErrorResponse` for some other statuses.
 
 ## 422 envelope shape
 
-The platform standardizes ALL 422 response bodies on a single
-shape — regardless of which validation layer fired:
+The platform standardizes ALL 422 response bodies on a single shape —
+regardless of which validation layer fired:
 
 ```json
 {
@@ -103,45 +72,41 @@ shape — regardless of which validation layer fired:
 }
 ```
 
-- `errors` is always an ARRAY of error objects (never a
-  field-keyed map).
-- `source.pointer` is a JSON Pointer (`/field_name` for top-
-  level fields; `/nested/field` for embeds) naming the
-  offending field on the request body.
+- `errors` is always an ARRAY of error objects (never a field-keyed map).
+- `source.pointer` is a JSON Pointer (`/field_name` for top-level fields;
+  `/nested/field` for embeds) naming the offending field on the request body.
 - `detail` is the specific reason; `title` is a brief summary.
-- Multiple errors may share the same `source.pointer` if more
-  than one check fired on the same field.
+- Multiple errors may share the same `source.pointer` if more than one check
+  fired on the same field.
 
 ## Two layers behind the standardized 422
 
-The platform validates a request in two layers; both surface
-through the same envelope above:
+The platform validates a request in two layers; both surface through the
+same envelope above:
 
 **Layer 1 — OpenAPI cast (structural)**
 
-Runs at the plug layer before the controller. Catches: missing
-required fields, wrong types, invalid enums, unknown keys,
-format violations (UUID patterns, etc.). The SDK's valibot
-validator mirrors this layer client-side, so most layer-1
-errors NEVER reach the server.
+Runs at the plug layer (`OpenApiSpex`) before the controller. Catches:
+missing required fields, wrong types, invalid enums, unknown keys, format
+violations (UUID patterns, etc.). This is the *same* OpenAPI schema the SDK's
+types are generated from, so a body that satisfies the TypeScript types
+almost always clears layer 1.
 
 **Layer 2 — server-side semantic validator (post-cast)**
 
-Runs after the structural cast succeeds. Catches: uniqueness,
-cross-field rules (e.g. `auth_method = "iam_role"` combined with
-conflicting credential fields), foreign-key constraints, custom
-platform validations. Layer-2 errors are normalized into the
-same envelope shape as layer 1 — consumers don't distinguish
-layers from the JSON.
+Runs after the structural cast succeeds. Catches: uniqueness, cross-field
+rules (e.g. `auth_method = "iam_role"` combined with conflicting credential
+fields), foreign-key constraints, custom platform validations. Layer-2
+errors are normalized into the same envelope shape as layer 1 — consumers
+don't distinguish layers from the JSON.
 
-Practical consequence: a post-HTTP throw indicates layer-2
-(or a layer-1 case your valibot version doesn't yet
-have — keep the SDK pin fresh).
+Practical consequence: every validation error reaches you as a thrown 422
+body. Read `source.pointer`, fix that field, resubmit.
 
 ## Concrete examples
 
-**Layer 1 — missing required fields** (POST `/agentic-
-workflows` with empty body):
+**Layer 1 — missing required fields** (POST `/agentic-workflows` with empty
+body):
 
 ```json
 {
@@ -154,8 +119,7 @@ workflows` with empty body):
 }
 ```
 
-**Layer 1 — invalid enum value** (`dataset_type:
-"nonexistent_type"`):
+**Layer 1 — invalid enum value** (`dataset_type: "nonexistent_type"`):
 
 ```json
 {
@@ -166,8 +130,8 @@ workflows` with empty body):
 }
 ```
 
-**Layer 2 — semantic rule** (DELETE on a default-flagged data
-activation client):
+**Layer 2 — semantic rule** (DELETE on a default-flagged data activation
+client):
 
 ```json
 {
@@ -178,8 +142,8 @@ activation client):
 }
 ```
 
-**Layer 2 — uniqueness** (POST `/admin/invites` for an
-already-invited email):
+**Layer 2 — uniqueness** (POST `/admin/invites` for an already-invited
+email):
 
 ```json
 {
@@ -192,10 +156,10 @@ already-invited email):
 
 ## HTTP status codes (under the hood)
 
-The SDK abstracts HTTP responses behind typed methods.
-Consumers mostly see typed data or thrown bodies; raw status
-codes are usually visible only via the SDK's `--debug`-style
-interceptor. The platform maps:
+The SDK abstracts HTTP responses behind typed methods. Consumers mostly see
+typed data or thrown bodies; the thrown body carries `_httpStatus`, and raw
+status is also visible via the SDK's `--debug`-style interceptor. The
+platform maps:
 
 | Code | When it fires                                                  |
 |------|----------------------------------------------------------------|
@@ -210,26 +174,23 @@ interceptor. The platform maps:
 
 ## Retry semantics
 
-Treat 5xx as infra noise — retry with exponential backoff.
-Treat 422 as a real consumer-correctable error — fix the body
-and resubmit. **Never retry a 422 with the same body.**
+Treat 5xx as infra noise — retry with exponential backoff. Treat 422 as a
+real consumer-correctable error — fix the body and resubmit. **Never retry a
+422 with the same body.**
 
 ## Mapping `source.pointer` back to your TypeScript type
 
-A `source.pointer` like `/regulated_data_db_reader_user` maps
-directly to the `regulated_data_db_reader_user` field on
-`DatalakeRequestWritable`. For nested embeds, the pointer
-carries the embed path:
+A `source.pointer` like `/regulated_data_db_reader_user` maps directly to the
+`regulated_data_db_reader_user` field on `DatalakeRequestWritable`. For
+nested embeds, the pointer carries the embed path:
 `/unregulated_cloud_storage/access_key_id`.
 
-For polymorphic embeds, check the discriminator field's
-pointer first — if `/tool_body_type` (or
-`/cloud_storage_type`, etc.) is in the errors array, fix that
-BEFORE chasing other fields on the embed. The wrong
-discriminator value cascades into spurious required-list
-failures on the wrong branch's fields. See `mutations.md`
-for the discriminator naming convention.
-
-Each per-resource MD names its `<Resource>RequestWritable`
-TypeScript type — the corpus's resource pages are the source
-of truth for which fields exist on which embed.
+For polymorphic embeds, check the discriminator field's pointer first — if
+`/tool_body_type` (or `/cloud_storage_type`, etc.) is in the errors array,
+fix that BEFORE chasing other fields on the embed. The wrong discriminator
+value cascades into spurious required-list failures on the wrong branch's
+fields. See `mutations.md` for the discriminator naming convention.
+
+Each per-resource MD names its `<Resource>RequestWritable` TypeScript type —
+the corpus's resource pages are the source of truth for which fields exist on
+which embed.