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

package/.agent/account_management.md

@@ -102,6 +102,37 @@ app authenticates **tenant-scoped against exactly one tenant**,
 with that tenant's publishable key; connected apps in particular
 are single-tenant by construction (`connected_apps.md`).
 
+### Key-only clients — machine-to-machine on the publishable key
+
+`sessionToken` is optional on the client config. A deployed
+connected app that authenticates purely on its tenant's publishable
+key constructs with just the key — no session mint, no fabricated
+empty token:
+
+```typescript
+const api = createIsolatedPlatformApi({ baseUrl, apiKey })
+```
+
+Such a client sends `X-API-Key` and **no `Authorization` header**,
+and reaches exactly the `public_api` (publishable-key) allowlist —
+five calls:
+
+```
+   api.connectedApps.resolvePage             mint/read a delivered page
+   api.connectedApps.updateMessageTracking   opened_at / form_submitted_at
+   api.dataActivationClients.ingest          submit rows
+   api.dataActivationClients.ingestFile      submit a file
+   api.mdm.verify                            resolve an identity
+```
+
+(The same allowlist `connected_apps.md` documents — that guide owns
+the runtime-call details.) Every call outside these five returns
+401; that ceiling is the point, not an error to work around.
+Minting a session and passing `sessionToken` unlocks the full
+tenant-scoped API exactly as before — the two credentials are
+complementary (the key identifies the client; the Bearer
+authorizes), never substitutes.
+
 ### Explicit teardown — `revokeSession`
 
 The inverse of `createSession`. Revokes the current Bearer on

package/.agent/action_status_updaters.md

@@ -40,8 +40,8 @@ const { data: created } = await api.actionStatusUpdaters.create(
     updater_body: {
       updater_body_type: 'cloud_watch_request',
       log_group_name: 'sns/us-east-1/...',
-      start_time: '{{ now | minutes_ago: 45 }}',     // Liquid window
-      end_time:   '{{ now }}',
+      start_time: '{{ now_msec | minutes_ago: 45 }}', // Liquid window
+      end_time:   '{{ now_msec }}',
     },
 
     // Liquid, rendered ONCE PER EVENT — the event IS the assigns, so there is no
@@ -51,6 +51,14 @@ const { data: created } = await api.actionStatusUpdaters.create(
       type: 'custom',
       body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
     },
+
+    // REQUIRED on every updater, both types, on create AND update. Same
+    // per-event rendering contract as `message_config`, but targets the
+    // action_log row instead of the message row.
+    action_log_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+    },
   },
 )
 ```
@@ -74,22 +82,30 @@ updater_body_type: 'cloud_watch_request'
 follow the same `<verb>_request` naming and carry the fields
 their target API requires.)
 
+`updater_body_type: 'restapi_request'` additionally **requires an
+`events_template` field**. Without it the REST poll fails with
+`missing_events_template`. `events_template` is specific to the REST
+poll's event-list extraction — it is not read by data-activation
+fetches.
+
 `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:
+unix milliseconds** — that is what the poll request takes. Use the
+**`now_msec`** variable (unix ms) and pipe it through the
+relative-time filters. **Not the bare `now`** — that is a DateTime,
+and feeding it a millisecond filter now raises at render:
 
 ```
-start_time: '{{ now | minutes_ago: 45 }}'    // 45 minutes back
-end_time:   '{{ now }}'                       // right now
+start_time: '{{ now_msec | minutes_ago: 45 }}'    // 45 minutes back
+end_time:   '{{ now_msec }}'                       // 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.
+**Do not use the bare `now` variable or the ISO-8601 `now` filter
+here.** The `now` variable is a DateTime and `{{ "" | now }}`
+renders a datetime *string* — neither is a valid unix-ms window,
+and the platform rejects both. An ISO 8601 literal is not valid on
+these fields either.
 
 ### `message_config.body` renders ONCE PER EVENT
 
@@ -123,6 +139,79 @@ events for messages this updater doesn't own.
 Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
 available here, as everywhere.
 
+### MMS delivery tracking uses a system `message_config` template
+
+MMS delivery tracking is wired as a `cloud_watch` updater whose
+`message_config` points at a system-defined template rather than a
+hand-authored `custom` body — the system template lives at
+`status_poller/end_user_messaging/mms_delivery_status`. Everything
+else about the updater is ordinary: it still needs an
+`action_log_config` like every other updater (see below) — the
+system template covers `message_config` only.
+
+### Carrier information is available for SMS, not MMS
+
+The recipient's mobile carrier is present on SMS delivery events but
+not MMS. This is AWS behavior — verified against real delivery
+events — not something the platform chooses to drop:
+
+- **SMS via Amazon SNS** — the delivery-status log
+  (`sns/<region>/<account>/DirectPublishToPhoneNumber`) nests carrier
+  under `delivery.phoneCarrier` (e.g. `"T-mobile USA Inc."`, with
+  numeric `mcc`/`mnc`). The SNS status template maps it to
+  `sms_carrier`.
+- **MMS via AWS End User Messaging (`sms-voice`)** — the delivery
+  event has no carrier field. Verified on **both** a config-set
+  CloudWatch destination and the EventBridge path: the terminal
+  `MEDIA_DELIVERED` event exposes only `totalCarrierFee` (a cost),
+  never `carrierName`/`mcc`/`mnc`. So `sms_carrier` stays unset for
+  MMS.
+
+AWS's Nov-2024 EventBridge-integration announcement states MMS
+delivery events carry carrier information in EventBridge, but the
+real events do not — a documented doc-vs-behavior discrepancy. For
+per-number US carrier, use `PhoneNumberValidate` (returns `Carrier` +
+`PhoneType`) at enrollment and join on destination/`messageId`; it is
+not in the delivery stream.
+
+### `action_log_config` is required — same rendering contract as `message_config`
+
+`action_log_config` is a **required** field on every action status
+updater — `cloud_watch` and `restapi` alike — on **both `create()` and
+`update()`**. There is no updater for which it is optional and no way
+to omit it on a PUT.
+
+It follows the same per-event rendering contract as `message_config`
+(§2 above), but targets the **action_log** row instead of the message
+row: it must render a JSON object containing `external_id` plus at
+least one updatable action-log field — one of `status`, `sent_at`, or
+`metadata`. A minimal valid value:
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "delivered"}
+```
+
+Two distinct rejections come off this field, and they read differently:
+
+- **Missing entirely** — omitting `action_log_config` on create or
+  update is a 422 with `Missing field: action_log_config` at
+  `source.pointer: /action_log_config`.
+- **Present but renders nothing** — a value that passes shallow
+  validation but renders `null` or an empty result at run time (e.g.
+  a `{"type": "null"}` config) is refused with a 422 whose detail
+  begins `must render a JSON object containing external_id`.
+
+**Response nullability is lazy, not retroactive.** Updaters created
+before this became required still read back `action_log_config: null`
+— the platform does not backfill a template onto old rows. That
+`null` persists until the row's **next edit** forces a real template
+through, and "next edit" is broader than a plain field change: it
+also includes resuming a halted updater by setting `status` back to
+`'active'` (§7) and issuing a `refresh()` call with a one-shot
+`updater_body` override (§7) — both now require `action_log_config`
+to be present too, which is what completes the migration for an old
+row.
+
 ### `cron_expression` is a standard 5-field cron string
 
 ```
@@ -201,6 +290,7 @@ sender_tool_ids       required UUID[] — tools whose messages this updater trac
 datalake_id           required UUID
 updater_body          required embed  — { updater_body_type, ... }
 message_config        required embed  — { type, body }
+action_log_config     required embed  — { type, body } (required on create AND update)
 ```
 
 **Write-only (Request-only).** None.
@@ -216,6 +306,8 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
 | `/updater_body/updater_body_type`   | value not in the polymorphic embed's type enum     |
 | `/message_config/body`              | empty when `type: 'custom'`                        |
+| `/action_log_config`                | missing entirely — `Missing field: action_log_config` (create AND update) |
+| (detail, not pointer)               | `action_log_config` present but renders `null`/empty — detail begins `must render a JSON object containing external_id` |
 | `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
 
 ## 5. Lifecycle
@@ -363,25 +455,29 @@ 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_at            when the poll worker last made progress
+last_run_status        'ok' | 'partial' | 'error'
+last_run_error         why the last run failed, or why a partial run was truncated
 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.
+**A poll run has three outcomes, and only `'ok'` means it reconciled its
+whole time window:**
+
+- `'ok'` — the run completed and read its entire window. This is the only
+  value that proves the reconciliation is complete.
+- `'partial'` — the run completed but its provider fetch was **truncated**:
+  the window was not fully read, and the events it missed are the **newest**
+  ones. `last_run_error` carries the detail (it is **not** null on a
+  `partial` run). A client that treats `last_run_status !== 'error'` as
+  healthy silently accepts this incomplete reconciliation — check
+  `last_run_status === 'ok'` instead.
+- `'error'` — the run failed; `last_run_error` says why.
+
+`last_run_events_found` is the event count for the current run; because
+`refresh` is asynchronous (below), a read taken before the run finishes can
+legitimately show a smaller, in-progress figure than the final count.
 
 **`status` is the halt flag.** The server sets `'cycle_detected'` when
 a run re-reads events it has already handled — the runtime backstop for

package/.agent/ai_sandbox.md

@@ -103,10 +103,12 @@ consumers cannot extend the set:
 
    minutes_ago   Unix ms N minutes before a unix-ms input. Bounds
                  the start of an ActionStatusUpdater poll window.
-                 Example:  {{ now | minutes_ago: 45 }}  →  1773585000000
+                 `now_msec` is the injected unix-ms variable (the
+                 bare `now` is a DateTime — feeding it here raises).
+                 Example:  {{ now_msec | minutes_ago: 45 }}  →  1773585000000
 
    hours_ago     Unix ms N hours before a unix-ms input.
-                 Example:  {{ now | hours_ago: 2 }}  →  1773578400000
+                 Example:  {{ now_msec | hours_ago: 2 }}  →  1773578400000
 
    uuid          Generate a new v4 UUID.
                  Example:  {{ '' | uuid }}  →  a1b2c3d4-…

package/.agent/connected_apps.md

@@ -64,7 +64,8 @@ const { data: created } = await api.connectedApps.create(
 )
 // created.id, created.slug         — server-derived
 // created.status                   === 'pending' (transient) → 'synced' after route fetch
-// created.api_key_id               — auto-provisioned M2M key id (see §2)
+// (an M2M key IS auto-provisioned at create (see §2), but its id is NOT
+//  echoed on the resource — no response carries an api_key_id field)
 // created.routes                   — array populated from .well-known/routes.json
 //                                     (empty until first sync)
 // created.last_synced_at           — set when routes successfully validated
@@ -191,9 +192,13 @@ last_synced_at    string — ISO 8601; set at successful route sync
 error             string — populated when status === 'error'
 routes            array  — discovered from .well-known/routes.json
                             (each: { name, path, description? })
-api_key_id        UUID   — id of the auto-provisioned M2M key
 ```
 
+(The auto-provisioned M2M key's id is **not** among these — neither
+`.get` nor `get-metadata` returns an `api_key_id`. Don't assert on it
+in a contract hook; the key itself reaches the deployment as
+`ALVERA_API_KEY`, §2.)
+
 **Caller-supplied (round-trip).**
 
 ```

package/.agent/cookbook/action-status-updaters.md

@@ -105,11 +105,16 @@ ctx.cwToolId = cwTool.id!
 
 The ASU ties it together: a `cron_expression` schedule, the `updater_tool_id`
 (the poller), the `sender_tool_ids` it reconciles for, and an `updater_body`
-naming the log group + the time window. On `start_time`/`end_time`, `now` is a
-variable holding unix milliseconds — pipe it through `minutes_ago`. The
+naming the log group + the time window. On `start_time`/`end_time`, use
+`now_msec` — the injected variable holding unix milliseconds — piped through
+`minutes_ago`; the bare `now` is a DateTime and raises here. The
 `message_config` Liquid is rendered ONCE PER EVENT, with the event itself as the
 assigns (there is no `events` list to loop), and emits a FLAT object: the
 `external_id` of the message to update plus the fields to set at the top level.
+`action_log_config` is REQUIRED alongside it — same per-event assigns, rendered
+into the action-log write shape: a JSON object with `external_id` plus at least
+one of `status` / `sent_at` / `metadata`. Omitting it is a 422 (`Missing field:
+action_log_config`).
 
 ```typescript
 const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
@@ -122,13 +127,17 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
   updater_body: {
     updater_body_type: 'cloud_watch_request',
     log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now | minutes_ago: 45 }}',
-    end_time: '{{ now }}',
+    start_time: '{{ now_msec | minutes_ago: 45 }}',
+    end_time: '{{ now_msec }}',
   },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
   },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
 })
 actionStatusUpdaterId = asu.id!
 ```
@@ -155,13 +164,17 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
   updater_body: {
     updater_body_type: 'cloud_watch_request',
     log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now | minutes_ago: 45 }}',
-    end_time: '{{ now }}',
+    start_time: '{{ now_msec | minutes_ago: 45 }}',
+    end_time: '{{ now_msec }}',
   },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
   },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
 })
 if (typeof ck.checksum !== 'string' || ck.checksum.length === 0) {
   throw new Error('expected a checksum for the ASU body')
@@ -190,6 +203,35 @@ if (typeof detail !== 'string' || detail.length === 0) {
 }
 ```
 
+## 007 — write the integration test
+
+End the build with a test you keep: one block that re-reads the reconciler
+and asserts the facts the scenario depends on. This block runs live under
+`make validate-cookbook`.
+
+```typescript
+// Re-GET — the stored row echoes what was authored.
+const { data: asuRow } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (asuRow.cron_expression !== '*/30 * * * *') {
+  throw new Error(`cron mismatch on read-back: ${asuRow.cron_expression}`)
+}
+// last_run_* is the ONLY run surface (there is no per-run log). On a
+// fresh create it is legitimately null — assert the field EXISTS on the
+// wire, never a value.
+if (!('last_run_status' in asuRow)) {
+  throw new Error('ASU response carries no last_run_status field')
+}
+// Behavioural probe — the metadata surface an agent reads must render.
+const { data: asuDetail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (typeof asuDetail !== 'string' || asuDetail.length === 0) {
+  throw new Error('ASU metadataDetails came back empty')
+}
+```
+
+If the test fails in production, escalate with the failing read's
+evidence (the response body, `last_run_error`) — don't rewrite the config
+blind.
+
 # Gotchas
 
 - **The poller tool's intent is `status_poller`, not the sender's intent.** The
@@ -199,14 +241,31 @@ if (typeof detail !== 'string' || detail.length === 0) {
   is the assigns — there is no `events` list to loop — and every top-level key
   that is not `external_id` IS the update (`status`, `delivered_at`, …). There is
   no `set_params` wrapper. Both mistakes are rejected at create.
-- **The schedule is a cron, evaluated platform-side, and you CANNOT trigger it.**
-  Creating the ASU registers the schedule. The `updater_body` window
-  (`{{ now | minutes_ago: 45 }}` … `{{ now }}`) bounds each run's log query, and
-  must render to unix milliseconds — `now` is a variable here, not the ISO-8601
-  `now` filter.
-- **If it doesn't reconcile, read `last_run_error` and then ESCALATE.** There is
-  no manual trigger and no per-run log (known limitation). Don't rewrite the
-  config and wait for another cron tick — see `action_status_updaters.md` §7.
+- **`action_log_config` is REQUIRED on both create and update (PUT), same as
+  `message_config`.** Omitting it is a 422 (`Missing field: action_log_config`).
+  It renders the same per-event assigns into the action-log write shape:
+  `external_id` plus at least one of `status` / `sent_at` / `metadata`.
+- **The schedule is a cron, evaluated platform-side — and one poll cycle can
+  be fired on demand.** Creating the ASU registers the schedule. The
+  `updater_body` window (`{{ now_msec | minutes_ago: 45 }}` … `{{ now_msec }}`)
+  bounds each run's log query, and must render to unix milliseconds — `now_msec`
+  is the unix-ms variable, not the bare `now` (a DateTime) or the ISO-8601 `now`
+  filter. To trigger a cycle without
+  waiting for the cron tick, `api.actionStatusUpdaters.refresh(tenantSlug,
+  datalakeSlug, id)` answers `202` with the updater row AS-IS (the poll runs
+  async — the row still shows the PREVIOUS run's stamps; re-read later for
+  the outcome). See `action_status_updaters.md` §7.
+- **If it doesn't reconcile, read `last_run_error` — refresh, don't guess.**
+  There is no per-run log (known limitation): the run surface is the
+  read-only `last_run_*` fields. Fire a `refresh`, re-read `last_run_status`
+  / `last_run_events_found` / `last_run_error`, and escalate with that
+  evidence — don't rewrite the config blind between cron ticks.
+- **`last_run_status` has three values — only `'ok'` means done.** `'ok'`
+  is the run that read its whole time window; `'partial'` completed but its
+  provider fetch was truncated, so the newest events may be missing and
+  `last_run_error` says so (it is not null on a `partial`); `'error'` failed.
+  Check `last_run_status === 'ok'` — a `!== 'error'` check silently accepts
+  a truncated `partial` as if it had reconciled.
 - **`checksum` parity is your drift signal.** The fingerprint of the desired body
   must match the stored row's; a mismatch means the resource drifted.
 

package/.agent/cookbook/ai-agent-invoke.md

@@ -214,6 +214,42 @@ if (!rejected) {
 }
 ```
 
+## 006 — write the integration test
+
+End the build with a test you keep: re-read the agent and probe the one
+behaviour that is provable deterministically — the input gate. A real
+extraction (§004) needs a live provider behind the tool; the schema gate
+does not, which is exactly what makes it the durable test. This block
+runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the agent must be enabled, or every invoke will refuse.
+const { data: agentRow } = await api.aiAgents.get(tenantSlug, datalakeSlug, aiAgentId)
+if (agentRow.enabled !== true) {
+  throw new Error('expected enabled=true on agent read-back')
+}
+// Behavioural probe — the input_schema gate fires BEFORE the model:
+// a malformed input must 422 even with no working provider.
+let gateFired = false
+try {
+  await api.aiAgents.invoke(tenantSlug, datalakeSlug, aiAgentId, {
+    input: { wrong_field: 'test — no instructions here' },
+    files: [],
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  gateFired = true
+}
+if (!gateFired) {
+  throw new Error('agent accepted input that violates its input_schema (expected 422)')
+}
+```
+
+If the gate stops firing in production, escalate with the
+accepted-payload evidence — don't loosen the `input_schema` to make the
+error go away.
+
 # Gotchas
 
 - **Uploading a file is not ingesting it.** The upload + `invoke` here makes the

package/.agent/cookbook/appointment-review-sms-workflow.md

@@ -675,6 +675,38 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 016 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The cancelled appointment is filtered, not failed** — §012

package/.agent/cookbook/birthday-greeting-sms-trigger.md

@@ -577,6 +577,40 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 015 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause must speak this workflow's selection dialect — the dataset
+// alias is `rle` here, the same alias the live run above uses.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "rle.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The no-DoB row is filtered, not failed** — §011 asserts the no-DoB

package/.agent/cookbook/bulk-ingest.md

@@ -229,6 +229,54 @@ if (rows.length < 4) {
 }
 ```
 
+## 009 — write the integration test
+
+End the build with a test you keep: run the bulk path in miniature —
+mint a link, PUT a tiny inline CSV, enqueue it — and assert each call's
+own acknowledgement. The probe rows are `test-`-prefixed so they are
+unmistakably synthetic wherever they surface, and the test asserts the
+enqueue ack (`job_id`), never synchronous merge completion — the worker
+owns that. This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the client must still be there and carry its ingest slug.
+const { data: dacRow } = await api.dataActivationClients.get(tenantSlug, datalakeSlug, dacId)
+if (dacRow.slug !== ctx.dacSlug) {
+  throw new Error(`DAC slug drifted on read-back: ${dacRow.slug}`)
+}
+// Behavioural probe — the three-step bulk path, each step asserted on
+// its own response.
+const probeCsv =
+  'customer_number,customer_type,status,name,email,currency\n' +
+  `test-PROBE-1-${runSuffix},individual,contracted,test-Grace Hopper,test-grace-${runSuffix}@example.com,USD\n`
+const { data: probeLink } = await api.datalakes.createUploadLink(tenantSlug, datalakeSlug, {
+  content_type: 'text/csv',
+  filename: `test-bulk-probe-${runSuffix}.csv`,
+})
+if (!probeLink.url || !probeLink.key) {
+  throw new Error('createUploadLink returned no url/key')
+}
+const probePut = await fetch(probeLink.url, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'text/csv' },
+  body: probeCsv,
+})
+if (probePut.status !== 200) {
+  throw new Error(`presigned PUT failed: ${probePut.status}`)
+}
+const { data: probeJob } = await api.dataActivationClients.ingestFile(tenantSlug, datalakeSlug, ctx.dacSlug, {
+  key: probeLink.key,
+})
+// job_id is a NUMBER on the wire (an Oban job id), status "scheduled".
+if (probeJob.job_id === undefined || probeJob.job_id === null) {
+  throw new Error('ingestFile probe returned no job_id')
+}
+```
+
+If the probe fails in production, escalate with the failing call's
+response — don't retry the enqueue in a loop or reach into the worker's
+storage to "help it along".
+
 # Gotchas
 
 - **The file PUT is raw HTTP, not the SDK.** `createUploadLink` and `ingestFile`

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

@@ -543,6 +543,41 @@ for (const wel of ourWels) {
 }
 ```
 
+## 011 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id. The
+// clause speaks this workflow's selection dialect: a GENERIC-TABLE
+// dataset is addressed by its own columns (no `ra.` dataset alias —
+// that alias exists only for system-dataset selections).
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "submission_id = 'test-never-matching-submission'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The filter is permissive** — `filter_config.body: 'true'`