@alvera-ai/platform-sdk 0.13.0-next.g4d91b45 → 0.13.0-next.gbe3581f

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

@@ -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,6 +82,12 @@ 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**,
@@ -123,6 +137,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 +288,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 +304,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

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

@@ -110,6 +110,10 @@ variable holding unix milliseconds — pipe it through `minutes_ago`. 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, {
@@ -129,6 +133,10 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
   },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
 })
 actionStatusUpdaterId = asu.id!
 ```
@@ -162,6 +170,10 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
     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 +202,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 +240,24 @@ 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 | 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. 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.
 - **`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'`

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -533,6 +533,38 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 014 — 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 unverified customer is filtered, not failed** — §011

package/.agent/cookbook/generic-tables.md

@@ -175,6 +175,46 @@ if (!row || row.submission_id !== ctx.submissionId) {
 }
 ```
 
+## 007 — write the integration test
+
+End the build with a test you keep: re-read the table and prove the two
+facts every consumer of it depends on — the deploy completed (with the
+server-derived physical name), and the ingest path accepts a row. The
+probe row is `test-`-prefixed so it is unmistakably synthetic wherever it
+surfaces. This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — deployed, with the server-derived alvera_custom_ name.
+const { data: tableRow } = await api.genericTables.get(tenantSlug, datalakeSlug, genericTableId)
+if (tableRow.status !== 'deployed') {
+  throw new Error(`generic table regressed from deployed: ${tableRow.status}`)
+}
+if (tableRow.name !== ctx.tableName) {
+  throw new Error(`physical name drifted on read-back: ${tableRow.name}`)
+}
+// Behavioural probe — one synthetic row through the auto-provisioned
+// default client; ingest is async (202), so assert the batch
+// acknowledgement, never synchronous row completion.
+const { data: probeAck } = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.defaultDacSlug,
+  {
+    data: {
+      submission_id: `test-CDS-probe-${runSuffix}`,
+      customer_name: 'test-Ada Lovelace',
+      email: 'test-ada@example.test',
+      message: 'test: integration-test probe row.',
+      source_channel: 'portal',
+    },
+  },
+)
+if (typeof probeAck.batch_id !== 'string' || probeAck.batch_id.length === 0) {
+  throw new Error('default-client ingest did not enqueue a batch')
+}
+```
+
+If the probe fails in production, escalate with the failing response —
+don't re-create the table or hand-edit the physical schema.
+
 # Gotchas
 
 - **`privacy_requirement` is load-bearing.** It drives the regulated/unregulated

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -531,6 +531,40 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 014 — 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 `rpa` here, the same alias the live run above uses.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "rpa.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 suspended account is filtered, not failed** — §011