@alvera-ai/platform-sdk 0.13.0 → 0.14.0

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

package/.agent/cookbook/marketing-campaign-send.md

@@ -918,6 +918,41 @@ while (Date.now() < flagDeadline) {
 if (!flagged) throw new Error('the re-ingest did not flag the reply potential_duplicate within 120s')
 ```
 
+## 013 — 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
+// audience 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: "end_customer_id = 'test-never-matching-customer'",
+  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
 
 - **Suppressed and unreachable are `:filtered`, not `:failed`.** Both

package/.agent/cookbook/paginated-restapi-poller.md

@@ -0,0 +1,329 @@
+---
+title: "Capability: poll a paginated provider API for delivery status (Mailgun-style)"
+summary: A capability walk for restapi action status updaters. Register a REST poller tool against a provider's paginated events API (Mailgun-shaped here) and an action status updater whose request templates FOLLOW the pagination cursor — page 1 renders the collection path, later pages ride `msg.pagination_context.next`. The platform refuses a poller whose request can never advance (`api.actionStatusUpdaters.create` 422), so the guard is walked first, then the accepted shape.
+industry: foundation
+slug: paginated-restapi-poller
+vitest_source:
+  - integration-tests/tests/foundation/action-status-updaters.test.ts
+  - integration-tests/tests/foundation/bootstrap.test.ts
+status: green
+---
+
+# Capability
+
+**What you get:** delivery outcomes pulled from a provider's REST events API —
+paginated, cursor-driven — written back onto the messages you sent, on a cron,
+with the platform enforcing that your poll can actually terminate.
+
+A **restapi action status updater** polls an HTTP events endpoint instead of a
+log group:
+
+- a **REST poller tool** (`intent: 'status_poller'`, `tool_body_type:
+  'rest_api'`) supplies the base URL + auth,
+- the ASU's `updater_body` renders the request per page: `path`, `params`,
+  an `events_template` that extracts the page's events as a JSON array, and a
+  `pagination_context_template` that captures `has_next` + the provider's
+  cursor,
+- on every page after the first, the driver binds what your pagination
+  template captured as `msg.pagination_context` (and the page number as
+  `msg.page`) into your `path`/`params` — **your templates must read one of
+  them, or the request is byte-identical for every page and the poll can
+  never advance. The platform rejects that config at create.**
+
+Mailgun's events API is the shape walked here (`GET /v3/<domain>/events` with
+a `paging.next` cursor link), but any cursor- or page-numbered API fits. See
+`action_status_updaters.md` §7 for the wire reference.
+
+# Walkthrough
+
+The `_setup/foundation.md` bootstrap left `api`, `tenantSlug`, `datalakeSlug`,
+and `ctx.datalakeId` populated.
+
+## 001 — register a data source for the tools
+
+Both the sender and the poller attach to a data source — the origin
+registration for the messaging provider.
+
+```typescript
+const { data: ds } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+  name: `Poller Source ${runSuffix}`,
+  uri: 'mailgun.local',
+  description: 'Messaging-provider origin for the paginated delivery poller.',
+  status: 'active',
+  is_default: false,
+})
+dataSourceId = ds.id!
+```
+
+## 002 — create the sender tool whose messages get reconciled
+
+The ASU updates messages a sender produced; `sender_tool_ids` will point here.
+An SNS-backed SMS sender (LocalStack locally) plays that role.
+
+```typescript
+const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Poller SMS Sender ${runSuffix}`,
+  description: 'Sender whose delivery status the paginated poller reconciles.',
+  intent: 'sms',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  body: {
+    tool_body_type: 'sns',
+    auth_method: 'access_key',
+    region: 'us-east-1',
+    phone_number: '+15551234567',
+    endpoint_url: 'http://localhost:4566',
+    access_key_id: 'test',
+    secret_access_key: 'test',
+  },
+})
+ctx.senderToolId = smsTool.id!
+```
+
+## 003 — create the REST poller tool
+
+The poller supplies base URL + auth for the provider's events API —
+Mailgun-shaped here (basic auth, `api` / API key). `intent:
+'status_poller'` tags it as a reconciler source, `tool_body_type: 'rest_api'`
+makes the ASU's requests ride this tool's HTTP client.
+
+```typescript
+const { data: restTool } = await api.tools.create(tenantSlug, datalakeSlug, {
+  name: `Mailgun Events Poller ${runSuffix}`,
+  description: 'REST poller — supplies auth for restapi ActionStatusUpdater delivery polling',
+  intent: 'status_poller',
+  status: 'active',
+  datalake_id: ctx.datalakeId,
+  data_source_id: dataSourceId,
+  body: {
+    tool_body_type: 'rest_api',
+    base_url: 'http://localhost:8080/mailgun/v3',
+    auth_method: 'basic',
+    username: 'api',
+    password: 'key-test',
+    request_type: 'json',
+    response_type: 'json',
+    timeout_ms: 30000,
+  },
+})
+ctx.restToolId = restTool.id!
+```
+
+## 004 — the pagination guard: a static request is refused at create
+
+First, the shape that does NOT work — and why the platform refuses it. This
+`path`/`params` pair reads neither `msg.pagination_context` nor `msg.page`,
+so page 500's request would be byte-identical to page 1's: the window never
+moves, `has_next` never goes false, and the run would re-apply the same
+events forever. The create is a 422; the walk catches it to prove the gate.
+
+```typescript
+let rejected = false
+try {
+  await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+    name: `Mailgun Delivery Poller ${runSuffix} non-advancing`,
+    cron_expression: '*/30 * * * *',
+    updater_type: 'restapi',
+    updater_tool_id: ctx.restToolId,
+    sender_tool_ids: [ctx.senderToolId],
+    datalake_id: ctx.datalakeId,
+    events_output_schema: { type: 'array' },
+    pagination_context_output_schema: {
+      type: 'object',
+      required: ['has_next'],
+      properties: { has_next: { type: 'boolean' } },
+    },
+    updater_body: {
+      updater_body_type: 'restapi_request',
+      method: 'get',
+      // Static on both — the cursor is captured below and never read back.
+      path: { type: 'custom', body: '/wiremock.domain/events' },
+      params: { type: 'custom', body: '{"event": "delivered"}' },
+      events_template: { type: 'custom', body: '{{ response.items | to_json }}' },
+      pagination_context_template: {
+        type: 'custom',
+        body:
+          '{"has_next": {% if response.items.size > 0 %}true{% else %}false{% endif %}, ' +
+          '"next": "{{ response.paging.next }}"}',
+      },
+    },
+    message_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ message.headers.message-id }}", "status": "delivered"}',
+    },
+    action_log_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ message.headers.message-id }}", "status": "delivered"}',
+    },
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  rejected = true
+}
+if (!rejected) {
+  throw new Error('expected a 422 for a poller whose request never consumes the cursor')
+}
+```
+
+## 005 — the accepted shape: the path follows the cursor
+
+Page 1 (`msg.pagination_context` is falsy) renders the plain collection path
+with bounded query params; every later page rides the cursor link the
+pagination template captured — and drops the params, because Mailgun's
+`paging.next` is a complete URL that already carries them.
+
+```typescript
+const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+  name: `Mailgun Delivery Poller ${runSuffix} advancing`,
+  cron_expression: '*/30 * * * *',
+  updater_type: 'restapi',
+  updater_tool_id: ctx.restToolId,
+  sender_tool_ids: [ctx.senderToolId],
+  datalake_id: ctx.datalakeId,
+  events_output_schema: { type: 'array' },
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
+  updater_body: {
+    updater_body_type: 'restapi_request',
+    method: 'get',
+    path: {
+      type: 'custom',
+      body:
+        '{% if msg.pagination_context %}{{ msg.pagination_context.next }}' +
+        '{% else %}/wiremock.domain/events{% endif %}',
+    },
+    params: {
+      type: 'custom',
+      body: '{% unless msg.pagination_context %}{"event": "delivered"}{% endunless %}',
+    },
+    events_template: { type: 'custom', body: '{{ response.items | to_json }}' },
+    pagination_context_template: {
+      type: 'custom',
+      body:
+        '{"has_next": {% if response.items.size > 0 %}true{% else %}false{% endif %}, ' +
+        '"next": "{{ response.paging.next }}"}',
+    },
+  },
+  message_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ message.headers.message-id }}", "status": "delivered"}',
+  },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ message.headers.message-id }}", "status": "delivered"}',
+  },
+})
+actionStatusUpdaterId = asu.id!
+if (asu.status !== 'active') {
+  throw new Error(`a newly created poller must be free to poll — got status ${asu.status}`)
+}
+```
+
+## 006 — discover it (list + metadata)
+
+The poller shows up in the paginated ASU list, and `metadataDetails` renders
+the markdown an agent reads to understand the reconciler.
+
+```typescript
+const { data: list } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+if (!(list.data ?? []).some((u) => u.id === actionStatusUpdaterId)) {
+  throw new Error('created restapi ASU not found in the list')
+}
+
+const { data: detail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (typeof detail !== 'string' || detail.length === 0) {
+  throw new Error('expected non-empty ASU metadata details')
+}
+```
+
+## 007 — write the integration test
+
+End the build with a test you keep: re-read the poller and assert the
+facts the scenario depends on — the create was accepted (so the
+pagination guard passed), the row is free to poll, and the run surface is
+on the wire. This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the stored row echoes the authored cron.
+const { data: poller } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (poller.cron_expression !== '*/30 * * * *') {
+  throw new Error(`cron mismatch on read-back: ${poller.cron_expression}`)
+}
+// cycle_detected is only ever set at runtime by the poll driver —
+// a fresh create MUST read active.
+if (poller.status !== 'active') {
+  throw new Error(`a fresh poller must be free to poll — got status ${poller.status}`)
+}
+// last_run_* is the ONLY run surface (no per-run log); fresh create ⇒
+// legitimately null. Assert the field EXISTS, never a value.
+if (!('last_run_status' in poller)) {
+  throw new Error('poller response carries no last_run_status field')
+}
+// Behavioural probe — the metadata surface an agent reads must render.
+const { data: pollerDetail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
+if (typeof pollerDetail !== 'string' || pollerDetail.length === 0) {
+  throw new Error('poller metadataDetails came back empty')
+}
+```
+
+If the poller stops reconciling in production, refresh once, re-read
+`last_run_error`, and escalate with that evidence — don't rewrite the
+config and wait for another tick.
+
+# Gotchas
+
+- **The pagination guard is create-time and non-negotiable.** If neither
+  `path` nor `params` reads `msg.pagination_context` / `msg.page`, the create
+  is a 422 — the request could never advance past page 1. The guard reads
+  your template SOURCE, so a dead `{% if false %}{{ msg.page }}{% endif %}`
+  won't fool a reviewer even where it fools a regex; write the real cursor
+  read.
+- **Page 1 is the falsy-context branch.** `msg.pagination_context` is unset
+  on the first page — `{% if msg.pagination_context %}…{% else %}<collection
+  path>{% endif %}` is the canonical shape. Bound page 1's `params`
+  with `{% unless msg.pagination_context %}` when the cursor link already
+  carries the query (Mailgun's `paging.next` does).
+- **`has_next` decides termination — prefer the full-page heuristic in
+  production.** The walked shape (`response.items.size > 0`) terminates on
+  the first empty page, costing one extra request. Where the provider
+  documents a page size, `has_next: {% if response.items.size == 300 %}` (a
+  full page implies more) saves that call; a `paging.next` link that is
+  absent on the last page is an even stronger signal.
+- **`events_template` must render a JSON ARRAY**, validated against
+  `events_output_schema` on every cycle; the pagination render is validated
+  against `pagination_context_output_schema` (which must require `has_next`).
+  Both schemas are REQUIRED for `restapi` updaters — blank is a 422.
+- **A newly created poller is `status: 'active'`.** `cycle_detected` is only
+  ever set at runtime by the poll driver — never by a caller; you cannot
+  create your way into it.
+- **`action_log_config` is REQUIRED alongside `message_config`** on create
+  AND update (PUT) — same per-event assigns, rendered into the action-log
+  write shape (`external_id` + at least one of `status` / `sent_at` /
+  `metadata`).
+- **One poll cycle can be fired on demand.**
+  `api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, id)` runs the
+  cycle the cron would — `202` with the updater row AS-IS (the poll is
+  async; re-read `last_run_status` / `last_run_events_found` /
+  `last_run_error` for the outcome) — a day-two operate surface, not a
+  build step. That outcome has three values: `'ok'` (the whole window was
+  read), `'partial'` (the fetch was truncated — the newest events may be
+  missing, with `last_run_error` explaining), and `'error'` (the run
+  failed). Treat only `last_run_status === 'ok'` as a complete
+  reconciliation; a `!== 'error'` check silently accepts a truncated
+  `partial`.
+
+# See also
+
+- `action_status_updaters.md` §7 — restapi wire shape, the two output
+  schemas, `msg.*` assigns
+- `tools.md` — `rest_api` poller body, `status_poller` intent
+- `cookbook/action-status-updaters.md` — the CloudWatch-flavoured sibling
+  (log-group polling instead of HTTP pagination)
+- `_setup/foundation.md` — the bootstrap this walk starts from
+- `integration-tests/tests/foundation/action-status-updaters.test.ts` —
+  the green test these calls are lifted from (§3d–§3f)

package/.agent/cookbook/rest-fetch.md

@@ -220,6 +220,33 @@ if (!oauthTool.id) {
 }
 ```
 
+## 008 — write the integration test
+
+End the build with a test you keep: trigger one pull and assert the
+enqueue acknowledgement. `runManually` answers with the allocated
+`batch_id` BEFORE the fetch runs — the HTTP call and the ingestion drain
+on a background worker — so the durable test asserts on the call's own
+response, never on polling the merge (that diagnosis walk lives in §006).
+This block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the client must still be bound to the REST tool.
+const { data: fetchDac } = await api.dataActivationClients.get(tenantSlug, datalakeSlug, dacId)
+if (fetchDac.tool_id !== ctx.restToolId) {
+  throw new Error('DAC is no longer bound to the REST fetch tool')
+}
+// Behavioural probe — one manual pull; the ack carries the batch_id
+// the worker will report under.
+const { data: probePull } = await api.dataActivationClients.runManually(tenantSlug, datalakeSlug, ctx.dacSlug)
+if (typeof probePull.batch_id !== 'string' || probePull.batch_id.length === 0) {
+  throw new Error('runManually probe returned no batch_id')
+}
+```
+
+If the probe fails in production, escalate with the response — and if
+the enqueue succeeds but rows never land, the evidence to escalate with
+is the batch's log row (§006's read), not a re-run storm.
+
 # Gotchas
 
 - **A draft tool is silently skipped at fetch time.** The worker only fetches

package/.agent/cookbook/sanctions-screening-with-agent-review.md

@@ -641,6 +641,40 @@ if (!verdictBody.includes('[verified]')) {
 }
 ```
 
+## 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 `rcs` here, the same alias the live run above uses.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "rcs.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 auto-clear screening is filtered, not failed** — §012