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

package/.agent/action_status_updaters.md

@@ -44,13 +44,12 @@ const { data: created } = await api.actionStatusUpdaters.create(
       end_time:   '{{ now }}',
     },
 
-    // Liquid template emitting JSON that maps poll events to message updates
+    // Liquid, rendered ONCE PER EVENT — the event IS the assigns, so there is no
+    // `events` list to loop. Emits a FLAT object: the message to update, plus the
+    // fields to set at the top level.
     message_config: {
       type: 'custom',
-      body:
-        '{% for event in events %}' +
-        '{"external_id": "{{ event.message_id }}", "set_params": {"status": "{{ event.status }}"}}' +
-        '{% endfor %}',
+      body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
     },
   },
 )
@@ -75,29 +74,54 @@ updater_body_type: 'cloud_watch_request'
 follow the same `<verb>_request` naming and carry the fields
 their target API requires.)
 
-`start_time` / `end_time` accept Liquid expressions using the
-`now` variable plus relative-time filters (`minutes_ago: N`,
-`hours_ago: N`, ...). A literal ISO 8601 string also works for
-fixed windows.
+`start_time` / `end_time` are Liquid, and they **must render to
+unix milliseconds** — that is what the poll request takes. On
+these two fields `now` is a **variable already holding unix ms**,
+so pipe it through the relative-time filters:
 
-### `message_config.body` emits a JSON event stream
+```
+start_time: '{{ now | minutes_ago: 45 }}'    // 45 minutes back
+end_time:   '{{ now }}'                       // right now
+```
+
+Also available: `hours_ago: N`.
+
+**Do not use the ISO-8601 `now` filter here.** `{{ "" | now }}` is
+a different thing — it renders a datetime *string*, which is not a
+valid window, and the platform rejects it at create. An ISO 8601
+literal is not valid on these fields either.
+
+### `message_config.body` renders ONCE PER EVENT
+
+The template is rendered **once for each fetched event, with that
+event as the entire assigns**. There is no `events` collection in
+scope — do not loop.
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "delivered"}
+```
 
-The template runs against an `events` array — the parsed
-response from the polling tool. Each iteration must render
-one JSON object with two required fields:
+It must render a **flat** JSON object:
 
 ```
-external_id  string — the message identifier to update (typically
-                       the provider's id, matching the recipient
-                       record's external_id column)
-set_params   object — fields to update on the matching message row
-                       (e.g. { status, delivered_at, error_code })
+external_id  string — the message to update (matches the message row's
+                       external_id, i.e. the provider's id)
+<field>      any    — each remaining TOP-LEVEL key is a field to set:
+                       status, sent_at, delivered_at, read_at, opened_at
 ```
 
-The platform parses the rendered output, joins each event to a
-message row by `external_id`, and applies `set_params` as the
-update. Events that don't match any message are silently
-discarded.
+There is **no `set_params` wrapper**. Every key that is not
+`external_id` *is* the update. Nesting the fields under
+`set_params` renders an object the platform's field allowlist
+drops, so the update silently applies to nothing.
+
+The platform joins each rendered `external_id` to a message row
+and applies the remaining fields. Events that don't match any
+message are silently discarded — a provider poll routinely sees
+events for messages this updater doesn't own.
+
+Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
+available here, as everywhere.
 
 ### `cron_expression` is a standard 5-field cron string
 
@@ -111,7 +135,7 @@ Sub-minute cadences are NOT supported. The minimum interval
 the scheduler honors depends on platform-level configuration;
 default minimum is 5 minutes.
 
-### `updater_type` and `updater_body.updater_body_type` must correspond
+### `updater_type` and `updater_body.updater_body_type` — set them to agree, but only one is load-bearing
 
 The body carries TWO discriminator fields that name the same
 choice from different angles:
@@ -123,25 +147,35 @@ choice from different angles:
                                   body embed
 ```
 
-They must agree according to a fixed mapping:
+The intended pairing is a fixed mapping:
 
 ```
    updater_type: "cloud_watch"   ↔   updater_body_type: "cloud_watch_request"
    updater_type: "restapi"       ↔   updater_body_type: "restapi_request"
 ```
 
-A mismatched pair (e.g. `updater_type: "cloud_watch"` +
-`updater_body_type: "restapi_request"`) returns 422 — typically
-on `/updater_type` with a "type / body type mismatch" message.
-The full mapping is exported by the SDK; the `updater_type` enum
-and the `updater_body_type` enum are kept in lockstep by the
-generated types.
+**But the platform does NOT cross-validate the pair — a mismatch is
+NOT rejected.** The two fields are cast independently; there is no
+create-time check that `updater_type` matches
+`updater_body_type`, so a mismatched-but-well-formed pair (e.g.
+`updater_type: "cloud_watch"` + a `restapi_request` body) **persists
+silently**. At runtime the platform dispatches on the polymorphic
+**body** struct, so `updater_body_type` is the one that matters and
+`updater_type` is effectively informational. Set them to agree
+anyway — a future release may start enforcing it, and a lying
+`updater_type` is a debugging trap — but don't expect a 422 to catch
+a mismatch for you today.
 
 ### `updater_tool_id` and `sender_tool_ids` serve different roles
 
 - `updater_tool_id` (single) — the tool the updater uses to
-  ISSUE the poll. Must be a tool whose `intent` is
-  `status_poller` (e.g. a `cloud_watch_log_group` body type).
+  ISSUE the poll. By convention this is a tool whose `intent` is
+  `status_poller` (e.g. a `cloud_watch_log_group` body type) — but
+  the platform does **not** verify the intent at create time (it
+  checks only that the tool exists and belongs to the tenant). A
+  wrong-intent tool is accepted and only fails later, when the poll
+  actually runs. Wire a `status_poller` tool anyway; just don't rely
+  on a create-time 422 to enforce it.
 - `sender_tool_ids` (array) — the tools whose sent messages
   this updater is responsible for tracking. The match logic
   joins each polled event back to a message row that was
@@ -178,10 +212,9 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `source.pointer`                    | Cause                                              |
 |-------------------------------------|----------------------------------------------------|
 | `/cron_expression`                  | invalid cron syntax or below minimum interval      |
-| `/updater_tool_id`                  | tool's intent isn't `status_poller`                |
+| `/updater_tool_id`                  | tool id doesn't exist or wrong datalake (intent is NOT checked — see §2) |
 | `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
-| `/updater_body/updater_body_type`   | enum mismatch                                      |
-| `/updater_type`                     | mismatch with `updater_body.updater_body_type`     |
+| `/updater_body/updater_body_type`   | value not in the polymorphic embed's type enum     |
 | `/message_config/body`              | empty when `type: 'custom'`                        |
 | `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
 
@@ -204,11 +237,12 @@ branch.
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
-.get(tenantSlug, datalakeSlug, idOrSlug)     One row
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
+.get(tenantSlug, datalakeSlug, id)           One row — UUID only
 .metadata(tenantSlug, datalakeSlug)          Markdown — catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown — one updater
-                  idOrSlug)
+                  id)                         (UUID only)
 ```
 
 ### Update
@@ -232,17 +266,23 @@ check or retry for partial-delete states.
 
 ## 6. Gotchas
 
-1. **The polling tool's `intent` must be `status_poller`.**
-   A tool with `intent: 'sms'` or any other non-poller intent
-   is rejected at create time. The poller intent gates the
-   tool's eligibility as an `updater_tool_id`.
-
-2. **`message_config.body` must emit valid JSON.** The
-   template is rendered against the polling tool's parsed
-   response and the output is then JSON-parsed. A render that
-   produces malformed JSON (e.g. trailing comma, unquoted
-   string) makes the entire poll cycle silently no-op for
-   that updater — events stay unprocessed.
+1. **The polling tool should be `status_poller` — but nothing
+   enforces it at create.** By convention `updater_tool_id` points
+   at a `status_poller`-intent tool, and the runtime poll assumes
+   that shape. The create endpoint, however, does not check the
+   tool's intent (only existence + tenant), so an `intent: 'sms'`
+   tool is accepted and fails only when the poll runs. Wire the
+   right tool; don't count on a create-time rejection to catch a
+   wrong one.
+
+2. **`message_config.body` must render one flat JSON object per
+   event.** The two authoring mistakes that cannot work:
+   looping a `{% for event in events %}` collection (there is
+   none — the event *is* the assigns, so the loop renders
+   nothing), and nesting the fields under a `set_params` key
+   (the platform's allowlist drops them, so the update applies
+   to nothing). Both are now **rejected at create**. A render
+   that fails at run time is reported in `last_run_error`.
 
 3. **`external_id` join is exact-match.** Events whose
    `external_id` doesn't match a message row are discarded
@@ -251,10 +291,11 @@ check or retry for partial-delete states.
    the bare id, transform inside the Liquid template (string
    filters) so the rendered `external_id` matches.
 
-4. **`set_params` keys must be writable columns on the
-   message row.** Unknown keys are silently dropped during
-   the update. Refer to the message dataset's schema to
-   confirm which columns are writable from updater output.
+4. **The fields you set must be writable columns on the
+   message row** — `status`, `sent_at`, `delivered_at`,
+   `read_at`, `opened_at`. Unknown keys are silently dropped
+   during the update. They go at the TOP LEVEL of the rendered
+   object, alongside `external_id`.
 
 5. **Cron windows + polling-window overlap.** Choose
    `start_time` / `end_time` to overlap consecutive cron
@@ -262,3 +303,146 @@ check or retry for partial-delete states.
    transient delivery delays don't fall between two polls.
    The defaults in the wire-shape example illustrate this
    pattern: 30-minute cron, 45-minute window.
+
+6. **Key `has_next` off the page being NON-EMPTY, not off the
+   cursor's presence.** Real providers (Mailgun is one) return a
+   `paging.next` URL on EVERY page — including the final, empty
+   one — so a pagination template that emits `"has_next": true`
+   whenever the cursor exists loops until the runaway cap. The
+   canonical template keys off content instead:
+
+   ```liquid
+   "has_next": {% if items.size > 0 %}true{% else %}false{% endif %}
+   ```
+
+   The poll follows pages while `has_next` is true and stops on
+   the first empty page.
+
+## 7. Manual trigger via `refresh` — 202, and what `last_run_*` means
+
+An action status updater CAN be fired on demand:
+
+```ts
+const { data } = await api.actionStatusUpdaters.refresh(
+  tenantSlug, datalakeSlug, updaterId,
+);
+```
+
+**`refresh` answers `202` with the updater row AS-IS — the poll is
+ENQUEUED, not run.** The `last_run_*` fields on that response are the
+PREVIOUS run's stamps; reading them as the outcome of the refresh you
+just issued is the single most common mistake here. An optional body
+carries a one-shot `updater_body` override (e.g. a widened
+`start_time`/`end_time` window for a backfill) that does not mutate
+the persisted updater. Apply jobs are asynchronous too — observe
+delivery status on the message rows, not in this response.
+(CLI: `alvera refresh-action-status-updater --id <uuid>`, alias
+`refresh-updater`.)
+
+The correct read is baseline-then-advance:
+
+```ts
+const before = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+const baseline = before.data.last_run_at ?? null      // BEFORE refreshing
+
+await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, updaterId)
+
+let row = before.data
+const deadline = Date.now() + 60_000
+while (Date.now() < deadline) {
+  await new Promise((r) => setTimeout(r, 2_000))
+  const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+  if (data.last_run_at && data.last_run_at !== baseline) { row = data; break }
+}
+// row.last_run_status / last_run_error now describe THIS run
+```
+
+What the ASU still does NOT have is a **per-run log** (nothing like
+a data activation client's `logs` or a workflow's `batchLogs`). The
+run-outcome surface is four fields on the row itself, plus the halt
+flag:
+
+```
+last_run_at            when the poll worker last stamped a page
+last_run_status        'ok' | 'error'
+last_run_error         why the last run failed (structured text)
+last_run_events_found  events fetched so far in the current run
+status                 'active' | 'cycle_detected'
+```
+
+**A paginated run stamps `last_run_*` on EVERY page, not only the
+final one.** Two consequences for anything asserting on them:
+
+- `last_run_status: 'ok'` means *a page* succeeded — not that the run
+  completed. Do not treat it as terminal.
+- `last_run_events_found` is a **running total** for the current run,
+  so a mid-run read is legitimately smaller than the final count.
+
+Per-page stamping exists because the alternative hid a real incident:
+an updater that polled continuously for 45 minutes was
+indistinguishable from one that had never started, because only the
+terminal page stamped and no page was ever terminal.
+
+**`status` is the halt flag.** The server sets `'cycle_detected'` when
+a run re-reads events it has already handled — the runtime backstop for
+a poll whose pagination does not advance (a provider cursor that never
+drains, or a one-shot `updater_body` override). Every later job then
+fails without calling the provider, and `last_run_error` carries the
+diagnostic. **Nothing clears it but setting `status` back to
+`'active'`.** It is also the cheapest deterministic failure to assert
+on: a non-advancing config trips it within seconds, no provider
+credential rejection required. Related: a `restapi` updater that
+declares pagination but whose `path`/`params`/`body` never read
+`msg.pagination_context` or `msg.page` is now refused at create/update
+— see §2's template contract.
+
+**If a message's status is not reconciling, do this — in order:**
+
+1. Call `refresh()`, wait for `last_run_at` to advance past the
+   baseline you captured, then read `last_run_status` /
+   `last_run_error` / `status`. They name the failing stage: window
+   render, source fetch, template render, JSON parse — or a halted
+   poll cycle.
+2. Check the config against §2 above. A config that violates the
+   template contract is rejected at create, so a *deployed* updater's
+   templates are structurally sound — the fault is more likely the
+   event shape or the `external_id` join.
+3. **If those don't explain it, ESCALATE TO A HUMAN.** Report the
+   updater id, `last_run_error`, and the event shape you expected.
+
+A wrong config guess is worse than no change: replacing the unix-ms
+poll window with the ISO-8601 `now` filter, for example, stops the
+updater polling at all — verify each `refresh` outcome before
+touching the config again.
+
+## 8. Where delivery truth comes from (consumer view)
+
+If you only READ the platform (an operator UI, a dashboard), this
+is the part that matters:
+
+```
+   dispatch writes:            messages row, status 'sent',
+                               external_id = provider's id
+   THIS updater writes:        'delivered'  or  'failed' +
+                               failure_reason (+ delivered_at)
+   nothing else writes those.
+```
+
+- **No updater configured → no delivery truth.** Rows stay `sent`
+  forever; a delivery-rate number computed from them is fiction.
+  Updaters are created manually (this page §1) — the platform does
+  not auto-create them per sender tool.
+- **The join is `{external_id, set_params}`,** exact-match, silent
+  on misses (gotcha 3). "Eventually honest": a just-sent row is
+  neither delivered nor failed yet — show the in-between state.
+- **Retry is not here.** The updater only reports. Re-sending a
+  failed message is `workflows.execute` for that subject +
+  decision (`mode: 'live'`, `manual_override: true`) — the same
+  call as any manual dispatch; there is no retry endpoint. See
+  `workflows.md` §8.
+- **Engagement is not here either.** `opened_at` /
+  `form_submitted_at` arrive via
+  `connectedApps.updateMessageTracking` (magic-link seam,
+  `connected_apps.md` §6) and never touch `status`.
+- Field-by-field semantics of the rows being updated:
+  `messages.md`, `action_logs.md`.

package/.agent/ai_agents.md

@@ -30,7 +30,7 @@ const { data: created } = await api.aiAgents.create(
 
     tool_id: chatCompletionToolId,                  // see §2 — must be a tool with intent: 'llm_enrichment'
 
-    model: 'llama3.2:3b',                            // provider-specific model identifier
+    model: 'qwen3-vl:8b-instruct',                   // provider-specific model identifier
     data_access: 'unregulated',                      // 'unregulated' | 'regulated' (compliance gate)
     temperature: 0.0,
     max_tokens: 2048,
@@ -139,15 +139,27 @@ data_access: 'regulated'     — the LLM call receives raw values;
                                 screening, manual review, KYC.
 ```
 
-The setting is **immutable post-create**. Flipping the access
-tier requires recreating the agent (delete + create).
-
-### `enabled` gates whether workflows can invoke the agent
-
-A workflow that references a `disabled` agent fails at run time
-with `error_code: 'ai_agent_disabled'` on the workflow execution
-log. `enabled: false` is the operator's kill switch for an agent
-without removing it from the workflow's `ai_agents` array.
+**The platform does NOT enforce `data_access` as immutable — a PUT
+`update()` can change it today.** The field is cast by the same
+changeset that `update()` uses and carries no immutability guard (and
+isn't `readOnly` on the wire), so an update can flip `regulated ↔
+unregulated`, which changes whether the agent sees raw or tokenized
+values. **Treat it as immutable by discipline** — a data source
+built expecting one tier shouldn't be silently re-tiered under it —
+but know the platform won't stop a flip, so guard it in your own
+change-control (or recreate the agent) rather than relying on a
+rejected update.
+
+### `enabled` gates whether a nested agent runs
+
+At enrichment time the workflow filters its `workflow_ai_agents`
+to the enabled ones and runs only those — a `disabled` agent is
+silently **skipped**, not run-and-failed. There is no
+`ai_agent_disabled` error code. `enabled: false` is the
+operator's kill switch: it takes the agent out of the enrichment
+set without detaching it from the parent's `*_ai_agents` array.
+If every nested agent is disabled, the enrichment stage lands
+`{ status: 'skipped' }` (see §7).
 
 ### Numeric clamps on `temperature` and `max_tokens`
 
@@ -166,23 +178,20 @@ value the provider doesn't support (e.g. `temperature: 1.5` on
 a model that caps at 1.0) surfaces later as a provider error in
 the workflow execution log, not at create.
 
-### Name uniqueness is per-tenant, not per-datalake
+### Name uniqueness is per-datalake
 
 The agent's `name` (and the server-derived `slug`) must be
-unique within the tenant — collisions across **different
-datalakes of the same tenant** are rejected with a 422 on
-`/name` or `/slug`. This is unusual: most other resources scoped
-under a datalake (tools, data sources, interoperability
-contracts) carry per-datalake uniqueness. AI agents are the
-exception because their `slug` is the workflow-template
-reference key (`additional_context.<slug>`) and the platform
-needs a stable cross-datalake namespace for it.
-
-Practical consequence: if you want the same logical agent in
-two datalakes (e.g. dev + prod inside one tenant), give them
-distinct names. A naming convention like `"<purpose>-<env>"` or
-including the datalake slug in the agent name keeps the
-namespace clean.
+unique within the **datalake** — the uniqueness scope is
+`[slug, datalake_id]`, and a collision is rejected with a 422 on
+`/name` carrying "name must be unique within a datalake". This
+matches the other datalake-scoped resources (tools, data
+sources, interoperability contracts).
+
+The same logical name can therefore be reused across different
+datalakes of one tenant. A `slug` is only ever dereferenced
+within its own datalake's workflow templates
+(`additional_context.<slug>`), so cross-datalake reuse is safe —
+no environment-suffix naming convention is required.
 
 ## 3. Workflow & contract nesting
 
@@ -319,7 +328,7 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/data_access`                  | value not in enum                                  |
 | `/temperature`                  | outside the inclusive range [0.0, 2.0]             |
 | `/max_tokens`                   | outside the inclusive range [1, 100_000]           |
-| `/name` or `/slug`               | uniqueness collision — scope is per-tenant         |
+| `/name`                         | name/slug collision — unique within the datalake (`[slug, datalake_id]`) |
 
 ## 6. Lifecycle
 
@@ -331,12 +340,15 @@ once `enabled: true`.
 ### Read shapes
 
 ```
-.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.list(tenantSlug, datalakeSlug, query?)      Paged: { data, meta }
+                                              (full Flop query — type_naming.md)
 .get(tenantSlug, datalakeSlug, id)           One row, BY ID (UUID — not slug)
 .metadata(tenantSlug, datalakeSlug)          Markdown catalog
 .metadataDetails(tenantSlug, datalakeSlug,   Markdown for one agent;
-                  id)                         section headings: Model,
-                                              Bound tool, Prompt config
+                  id)                         section headings: Wrapper,
+                                              Model, Bound tool, Prompt
+                                              config, Input schema, LLM
+                                              response schema
 ```
 
 `.get` and `.metadataDetails` accept the agent's UUID `id` as
@@ -354,10 +366,75 @@ Omitting any returns a 422.
 
 ### Delete
 
-`delete()` removes the row. Workflows that still reference the
-agent in their `ai_agents` array fail at run time with
-`error_code: 'ai_agent_not_found'`; clean up workflow
-references first.
+`delete()` removes the row — but only if nothing references it.
+The delete is **blocked** (rejected as a 422) while the agent is
+still nested on any workflow (`workflow_ai_agents`) or
+interoperability contract (`interoperability_contract_ai_agents`),
+or while it has invocation `usage_logs`. Detach it from every
+parent first (re-supply the parent's `*_ai_agents` array without
+it — see §3), then delete. There is no "referenced agent silently
+deleted, workflow fails later" path: the association constraint
+stops the delete up front, so a live workflow never loses an agent
+out from under it.
+
+### Invoke (direct, outside a workflow)
+
+`invoke()` runs the agent once, synchronously, against a
+caller-supplied input map — the direct path for reading an
+uploaded file or doing ad-hoc extraction without nesting the
+agent on a workflow or contract.
+
+```
+.invoke(tenantSlug, datalakeSlug, id, body)   POST .../ai-agents/:id/invoke
+```
+
+The body is `AiAgentInvokeRequest`:
+
+```
+input   required object  — the prompt vars; validated against the
+                           agent's input_schema BEFORE the model is
+                           called (a violation is a 422)
+files   optional array   — [{ key, content_type }] attachments for
+                           multimodal (vision) invocation. `key` is a
+                           storage key from datalakes.createUploadLink;
+                           content_type ∈ application/pdf | image/png |
+                           image/jpeg | image/webp. The platform
+                           downloads each file from the agent's datalake,
+                           Base64-encodes it, and hands it to the model
+                           as a content part.
+```
+
+The response (`AiAgentInvokeResponse`):
+
+```
+output       object  — the parsed LLM JSON, matching llm_response_schema
+explanation  string? — the model's reasoning trace, when the tool's
+                       response_extractor mapped one out; null otherwise
+usage        object  — { model, input_tokens, output_tokens, total_tokens,
+                       latency_ms } telemetry for the call
+```
+
+Invoke passes NO `context_mapping_config` — `input` is validated
+directly against `input_schema` (unlike the nested workflow path,
+which remaps host context first). See the `ai-agent-invoke`
+cookbook for the full upload → tool → agent → invoke walk.
+
+### Drift checksum
+
+`checksum()` computes the SHA-256 drift fingerprint a
+create/update WOULD stamp for a given body, without persisting —
+the stateless plan-time primitive `alvera plan` uses.
+
+```
+.checksum(tenantSlug, datalakeSlug, body)   POST .../ai-agents/checksum
+```
+
+Compare the result against a deployed agent's server-computed
+`checksum` (from `get()`) to detect config drift. The fingerprint
+covers the authored fields only — `name`, `model`, `data_access`,
+`enabled`, `temperature`, `max_tokens`, `tool_id`, `description`,
+`input_schema`, `llm_response_schema`, `prompt_config` — server
+bookkeeping (`slug`, `id`, timestamps, FKs) is excluded.
 
 ## 7. Run-time failure modes
 
@@ -368,26 +445,41 @@ agent-specific codes:
 
 ```
 tool_execution_failed        — the bound chat-completion tool's
-                                HTTP call failed (404, refused,
-                                timeout). error.json carries the
-                                rich detail (URL, status); the
-                                workflow execution log carries
-                                a coarse error_message of the
-                                form "AI enrichment failed: <agent_name>"
-json_decode_failed           — provider returned a response that
-                                didn't parse as JSON (typically
-                                when llm_response_schema wasn't
-                                wired through to the provider's
-                                structured-output mode)
-context_mapping_failed       — context_mapping_config.body
-                                rendered output that didn't
-                                validate against the agent's
-                                input_schema
-ai_agent_disabled            — agent's enabled flag is false
-ai_agent_not_found           — agent was deleted but workflow
-                                still references it
+                                HTTP call failed (non-2xx, refused,
+                                timeout). Returned as a rich
+                                {code, message}: error.json's `detail`
+                                carries the URL + status; the workflow
+                                execution log carries a coarse
+                                error_message of the form
+                                "AI enrichment failed: <agent_name>"
+json_decode_failed           — the model's content didn't parse as
+                                JSON (typically llm_response_schema
+                                wasn't wired through to the provider's
+                                structured-output mode, so the model
+                                wrapped JSON in prose / code fences)
+response_extraction_failed   — the tool's response_extractor template
+                                failed to render/decode the provider
+                                envelope, or its output violated the
+                                extractor's own output_schema
+context_mapping_failed       — the nested join's
+                                context_mapping_config.body failed to
+                                render or JSON-decode
+context_mapping_not_a_map    — context_mapping_config rendered valid
+                                JSON that wasn't an object
+input_schema_validation_failed — the effective prompt vars (post
+                                context-mapping) didn't validate
+                                against the agent's input_schema
+tool_call_type_not_supported_for_llm_enrichment
+                             — the bound tool's body can't host a model
+                                call (only rest_api and aws_lambda
+                                bodies can)
 ```
 
+There is no `ai_agent_disabled` or `ai_agent_not_found` runtime
+code: a disabled agent is silently filtered out of the enrichment
+set and never runs (§2), and an agent still nested on a
+workflow/contract cannot be deleted in the first place (§6, Delete).
+
 The `error.json` shape:
 
 ```
@@ -448,8 +540,12 @@ with `{ status: 'skipped' }` and no per-agent entries.
    partial body silently drops fields and returns 422 on the
    missing required field.
 
-6. **`data_access` is immutable post-create.** Flipping the
-   compliance tier requires delete + recreate.
+6. **`data_access` is immutable by convention only — the platform
+   won't stop a PUT from flipping it.** There's no immutability
+   guard in the changeset, so an `update()` can change the
+   compliance tier (`regulated ↔ unregulated`) and re-tier what the
+   agent sees. Enforce it in your own change-control (or delete +
+   recreate); don't rely on the platform to reject the flip (§2).
 
 7. **`prompt_config.body` field references must resolve in
    `input_schema`.** A `{{ field }}` that isn't declared in