@alvera-ai/platform-sdk 0.13.0 → 0.15.0

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

@@ -0,0 +1,383 @@
+---
+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,
+    // FLOOR the platform enforces: an array whose items are objects listing
+    // `external_id` in `required`. A bare `{ type: 'array' }` is a 422 at
+    // create — every event has to name the message it reconciles.
+    events_output_schema: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['external_id'],
+        properties: { external_id: { type: 'string' } },
+      },
+    },
+    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"}' },
+      // Providers name their own id — `message-id` here, `messageId` / `sid`
+      // elsewhere. The events_template is where that becomes `external_id`:
+      // the apply path POPS that key off every rendered event to find the row
+      // it updates, so the render PROJECTS each event rather than passing the
+      // provider body through untouched.
+      events_template: {
+        type: 'custom',
+        body:
+          '[{% for item in response.items %}' +
+          '{"external_id": "{{ item.message.headers[\'message-id\'] }}", "event": "{{ item.event }}"}' +
+          '{% unless forloop.last %},{% endunless %}{% endfor %}]',
+      },
+      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": "{{ external_id }}", "status": "delivered"}',
+    },
+    action_log_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ external_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',
+    items: {
+      type: 'object',
+      required: ['external_id'],
+      properties: { external_id: { type: 'string' } },
+    },
+  },
+  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 %}',
+    },
+    // The provider's own id (`message-id`) becomes `external_id` HERE — the
+    // apply path pops that key to find the row it reconciles, so project each
+    // event instead of passing the provider body through untouched.
+    events_template: {
+      type: 'custom',
+      body:
+        '[{% for item in response.items %}' +
+        '{"external_id": "{{ item.message.headers[\'message-id\'] }}", "event": "{{ item.event }}"}' +
+        '{% unless forloop.last %},{% endunless %}{% endfor %}]',
+    },
+    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": "{{ external_id }}", "status": "delivered"}',
+  },
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ external_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.
+- **Each schema has a FLOOR the platform enforces, above which the contract is
+  yours.** `events_output_schema` must describe an **array whose `items` are
+  objects listing `external_id` in `required`**; a bare `{ type: 'array' }` is a
+  422 at create. `pagination_context_output_schema` must be an **object listing
+  `has_next` in `required`** — that key is what ends the page loop. Demand more
+  of your provider on top if you like; only the floor is checked.
+- **The floor exists because `external_id` is how reconciliation finds the row.**
+  `apply_status_update` pops that key off every rendered event, so mapping the
+  provider's own id (`message-id` / `messageId` / `sid`) into `external_id` is
+  the **`events_template`'s job** — project each event, never pass the provider
+  body through untouched. A schema that satisfies the floor while the template
+  emits raw provider rows creates cleanly and then reconciles nothing on every
+  cycle. `message_config` / `action_log_config` then read the **mapped**
+  `{{ external_id }}`, not the provider's original key.
+- **`action_log_config` is required alongside `message_config`** for every
+  updater type, and both are cast against the *same* pinned reconciliation
+  schema — so one template body satisfies both.
+- **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

@@ -286,7 +286,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     tool_id: toolId,
     position: 0,
     trigger_template: 'now',
-    idempotency_template: `{{ compliance_screening.id }}-${verdict}-{{ "" | uuid }}`,
+    idempotency_template: `{{ compliance_screening.id }}-${verdict}`,
     tool_call: {
       tool_call_type: 'sms_request',
       to: { type: 'custom', body: '+15550000000' },
@@ -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

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

@@ -337,7 +337,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     tool_id: toolId,
     position: 0,
     trigger_template: 'now',
-    idempotency_template: `{{ subject_id }}-{{ action_id }}-${band}-{{ "" | uuid }}`,
+    idempotency_template: `{{ subject_id }}-{{ action_id }}-${band}`,
     tool_call: {
       tool_call_type: 'sms_request',
       to: { type: 'custom', body: '+15551234567' },
@@ -547,6 +547,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'` passes

package/.agent/cookbook/system-templates.md

@@ -103,6 +103,42 @@ if (typeof detail !== 'string' || detail.length === 0) {
 }
 ```
 
+## 004 — write the integration test
+
+End the walk with a test you keep: anything that references a system
+template by path (`template_config: { type: 'system', path: … }`) depends
+on that path staying in this datalake's scope — so the durable test
+re-asserts the anchor is listed, the domain filter holds, and the detail
+surface renders. This block runs live under `make validate-cookbook`.
+
+```typescript
+const { data: tplList } = await api.templates.systemTemplates(tenantSlug, datalakeSlug)
+const tplPaths = (tplList.data ?? []).map((t) => t.path)
+const anchor = 'data_activation/interoperability/subscription/stripe/customers_subscription_customer'
+if (!tplPaths.some((p) => p.includes(anchor))) {
+  throw new Error(`anchor template ${anchor} vanished from the domain-scoped list`)
+}
+const foreign = ['healthcare', 'payments', 'foundation', 'core_banking', 'service_commerce', 'trading']
+const leakedPaths = tplPaths.filter((p) => foreign.some((d) => p.split('/').includes(d)))
+if (leakedPaths.length > 0) {
+  throw new Error(`cross-domain templates leaked: ${leakedPaths.join(', ')}`)
+}
+// Behavioural probe — the detail surface must render for the anchor.
+const { data: anchorDetail } = await api.templates.metadataDetails(
+  tenantSlug,
+  datalakeSlug,
+  'customers_subscription_customer',
+  'data_activation_interoperability',
+)
+if (typeof anchorDetail !== 'string' || anchorDetail.length === 0) {
+  throw new Error('anchor template metadataDetails came back empty')
+}
+```
+
+If the anchor disappears in production, escalate with the listing
+evidence — a `type: system` reference that stops resolving is a platform
+regression, not something to paper over by inlining the template body.
+
 # Gotchas
 
 - **The list is domain-scoped, not global.** `systemTemplates` only returns

package/.agent/cookbook/talk-to-data.md

@@ -103,6 +103,45 @@ if (!/\bn\b/.test(csv) || !csv.includes('1')) {
 }
 ```
 
+## 004 — write the integration test
+
+End the walk with a test you keep: both surfaces are read-only, so the
+durable test is the pair of deterministic boundary probes — the
+round-trip works, and the read-only wall holds. Neither depends on an
+LLM provider or seeded data, which is what makes the test durable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Round-trip probe — deterministic, data-independent.
+const probe = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: 'SELECT 1 AS ok',
+  mode: 'unregulated',
+})
+if (typeof probe.data === 'string' || probe.data.data[0]?.[0] !== 1) {
+  throw new Error('executeSql round-trip probe failed')
+}
+// Boundary probe — write SQL must be rejected with a 422; the
+// read-only wall is the security property this capability rests on.
+let walled = false
+try {
+  await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: "INSERT INTO legal_entities (legal_name) VALUES ('test-should-never-land')",
+    mode: 'unregulated',
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  walled = true
+}
+if (!walled) {
+  throw new Error('executeSql accepted a write statement — the read-only wall is down')
+}
+```
+
+If the write probe ever lands in production, stop and escalate
+immediately with the accepted statement as evidence — a read-only
+boundary failure is a security regression, never a config problem.
+
 # Branches
 
 - **Generation failure.** If every configured LLM provider fails, `textToSql`

package/.agent/cookbook/triage-prospects-by-priority.md

@@ -309,7 +309,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     tool_id: toolId,
     position: 0,
     trigger_template: 'now',
-    idempotency_template: `{{ customer_id }}-${band}-{{ "" | uuid }}`,
+    idempotency_template: `{{ customer_id }}-${band}`,
     tool_call: {
       tool_call_type: 'sms_request',
       to: { type: 'custom', body: '{{ mdm_output.regulated_customer.phone }}' },
@@ -480,6 +480,38 @@ for (const wel of ourWels) {
 }
 ```
 
+## 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.
+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
 
 - **Agent emits an out-of-enum band** — the response schema's