@alvera-ai/platform-sdk 0.17.0 → 0.18.0

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

@@ -1,773 +0,0 @@
----
-title: Disambiguate gray-zone sanctions screenings via an LLM agent
-summary: End-to-end agent-driven workflow — a chat-completion LLM agent disambiguates gray-zone-scored sanctions screenings into a verified/blocked verdict, the workflow's decision interpolates that verdict, two SMS actions (one per verdict) fan out, and the run is verified row-by-row. A clearly-clear screening is filtered out before the agent ever sees it.
-industry: payments
-slug: sanctions-screening-with-agent-review
-vitest_source:
-  - integration-tests/tests/payments/sanctions-review-workflow.test.ts
-  - integration-tests/tests/payments/interoperability-contracts.test.ts
-  - integration-tests/tests/payments/run-dac-single.test.ts
-  - integration-tests/tests/payments/create-dac.test.ts
-  - integration-tests/tests/payments/tools.test.ts
-  - integration-tests/tests/payments/data-sources.test.ts
-  - integration-tests/tests/payments/bootstrap.test.ts
-status: green
----
-
-# Problem
-
-A sanctions-screening provider returns a match score for every
-name it checks against a watchlist. The extremes are easy: a
-score near zero is a clean pass, a score near one is a confirmed
-hit. The middle band — a name close enough to a sanctioned entity
-to be plausible, different enough to be a likely false positive —
-is where a compliance analyst spends their day.
-
-A fixed threshold cannot resolve the gray zone: set it low and
-every near-miss blocks a legitimate customer; set it high and a
-real match slips through. The disambiguation is a judgement call
-on the specific name, not a number comparison.
-
-The Alvera platform's agent-driven workflow primitive turns that
-judgement call into an LLM enrichment plus a Liquid
-interpolation. A filter narrows the workflow to *only* gray-zone
-scores; an AI agent receives the screening's entity name and
-score via a context-mapping template, returns a JSON object whose
-`verdict` field is `verified` or `blocked`; and the workflow's
-decision_config interpolates that verdict into a one-element
-decision array. Two SMS actions are registered against the
-workflow, one per verdict; the agent's output picks which one
-runs. Auto-clear and auto-block screenings never reach the agent
-— the filter rejects them.
-
-This cookbook walks the **whole** scenario: it provisions the
-agent and workflow, ingests two compliance-screening events
-through the production data-activation chain (one gray-zone, one
-clearly clear), runs the workflow so the gray-zone filter routes
-each row, and verifies the routing — the gray-zone screening
-reaches the agent and fans out to a verdict-keyed SMS, the
-clearly-clear screening is filtered out before any agent call.
-
-The scenario is anchored to
-`platform/integration-tests/tests/payments/sanctions-review-workflow.test.ts`
-— a green end-to-end test. The setup file `_setup/payments.md`
-already provisioned the tenant + datalake + tenant-scoped client;
-this cookbook starts from there.
-
-# Composition
-
-| Resource provisioned               | Owner       |
-|-------------------------------------|-------------|
-| SMS tool (SNS-backed)               | build       |
-| LLM tool (Ollama chat completion)   | build       |
-| Sanctions Review AI agent           | build       |
-| Sanctions Review workflow           | build       |
-| Atomic FI data source                | build       |
-| Manual Upload tool                  | build       |
-| Compliance Screening interop contract | build     |
-| Manual-upload DAC                   | build       |
-
-The setup file `_setup/payments.md` already provisioned the
-tenant + datalake + tenant-scoped client; this cookbook starts
-from there.
-
-# Walkthrough
-
-## 001 — create the SMS tool
-
-The Sanctions Review workflow's actions invoke an SMS tool. The
-tool's `body.tool_body_type: 'sns'` means it routes via AWS SNS;
-local dev points it at LocalStack on `http://localhost:4566` via
-`endpoint_url` so no real AWS credentials are needed. The
-`intent: 'sms'` tags this tool for workflow actions that send SMS
-(versus `data_exchange` for ingestion tools).
-
-```typescript
-const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook SMS Tool ${runSuffix}`,
-  description: 'SNS-backed SMS dispatcher for the Sanctions Review workflow, wired to LocalStack.',
-  intent: 'sms',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  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',
-  },
-})
-toolId = smsToolResp.data.id!
-```
-
-## 002 — create the LLM tool
-
-The Sanctions Review agent calls a chat-completion endpoint to
-disambiguate each gray-zone screening. The tool's
-`intent: 'llm_enrichment'` distinguishes it from the SMS tool above.
-It is a **provider adapter**: `base_body` authors the provider's
-request — here Ollama's native `/api/chat` shape with `think: false`
-and a `format` schema so the model returns clean, schema-constrained
-JSON — and `response_extractor` maps the provider's envelope back to
-the canonical `{ output_json, … }` the platform reads. The extractor's
-`output_schema` is required for an `llm_enrichment` tool. The
-`api_key`/`auth_method` pair satisfies the REST tool's schema even
-though Ollama ignores the header.
-
-```typescript
-const ENRICHMENT_OUTPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    output_json: {},
-    input_tokens: { type: ['integer', 'null'] },
-    output_tokens: { type: ['integer', 'null'] },
-    total_tokens: { type: ['integer', 'null'] },
-    explanation: { type: ['string', 'null'] },
-  },
-  required: ['output_json'],
-}
-
-const OLLAMA_BASE_BODY =
-  '{"model": "{{ model }}", "messages": [{"role": "user", "content": "{{ rendered_prompt | json_escape }}", "images": [{% for img in images %}{% unless forloop.first %}, {% endunless %}"{{ img.data }}"{% endfor %}]}], "stream": false, "think": false, "options": {"temperature": 0, "num_ctx": 40960}, "format": {{ schema | to_json }}}'
-
-const OLLAMA_EXTRACTOR =
-  '{"output_json": "{{ msg.message.content | json_escape }}", "explanation": "{{ msg.message.thinking | json_escape }}", "input_tokens": {{ msg.prompt_eval_count | default: 0 }}, "output_tokens": {{ msg.eval_count | default: 0 }}, "total_tokens": {{ msg.prompt_eval_count | default: 0 | plus: msg.eval_count }}}'
-
-const llmToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook LLM Tool ${runSuffix}`,
-  description: 'Ollama-backed chat-completion adapter for sanctions-screening disambiguation.',
-  intent: 'llm_enrichment',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
-  body: {
-    tool_body_type: 'rest_api',
-    base_url: 'http://localhost:11434',
-    base_path: { type: 'custom', body: '/api/chat' },
-    auth_method: 'api_key',
-    api_key: 'stub-key',
-    api_key_name: 'Authorization',
-    api_key_location: 'header',
-    request_type: 'json',
-    response_type: 'json',
-    timeout_ms: 60_000,
-    base_body: { type: 'custom', body: OLLAMA_BASE_BODY },
-  },
-})
-ctx.llmToolId = llmToolResp.data.id!
-```
-
-## 003 — create the Sanctions Review AI agent
-
-The agent binds three things: the model name, an input schema the
-workflow's context-mapping must satisfy, and a response schema the
-agent's output must match. The response schema's
-`enum: ['verified','blocked']` constraint guards the downstream
-decision interpolation from emitting a verdict the workflow has no
-SMS action for. `temperature: 0.0` removes sampling noise.
-
-`data_access: 'regulated'` is load-bearing here: the screened
-entity's name is a `TokenizedDataType` field — tokenized on the
-unregulated side. The agent needs the plaintext name to make a
-judgement call, so it reads the *regulated* projection of the
-compliance-screening row.
-
-```typescript
-const AGENT_INPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    screening_id: { type: 'string' },
-    screened_entity_name: { type: 'string' },
-    match_score: { type: 'number' },
-  },
-  required: ['screening_id', 'screened_entity_name', 'match_score'],
-}
-
-const AGENT_RESPONSE_SCHEMA = {
-  type: 'object',
-  properties: {
-    verdict: { type: 'string', enum: ['verified', 'blocked'] },
-    comments: { type: 'string' },
-  },
-  required: ['verdict', 'comments'],
-}
-
-const AGENT_PROMPT_BODY = `You are a sanctions-review disambiguation assistant. A name-match against a sanctions list has come in with a gray-zone score (close enough to be plausible, ambiguous enough to need a human-style judgement call). Decide whether this is a true match ("blocked") or a false positive on a similar name ("verified").
-
-Screening id: {{ screening_id }}
-Screened entity name: {{ screened_entity_name }}
-Match score: {{ match_score }}
-
-Respond with JSON: {"verdict": "verified" | "blocked", "comments": "<one-sentence rationale>"}
-
-For this cookbook fixture, the entity name is a deliberately disambiguating non-sanctioned identity — respond with "verified".`
-
-const agentResp = await api.aiAgents.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Sanctions Review Agent ${runSuffix}`,
-  tool_id: ctx.llmToolId,
-  model: 'qwen3-vl:8b-instruct',
-  data_access: 'regulated',
-  temperature: 0.0,
-  max_tokens: 256,
-  enabled: true,
-  input_schema: AGENT_INPUT_SCHEMA,
-  llm_response_schema: AGENT_RESPONSE_SCHEMA,
-  prompt_config: { type: 'custom', body: AGENT_PROMPT_BODY },
-})
-aiAgentId = agentResp.data.id!
-ctx.agentSlug = agentResp.data.slug!
-```
-
-## 004 — create the Sanctions Review workflow
-
-The workflow has the standard shape — filter, decision, actions —
-plus the Sanctions Review agent **nested** in the create body (the
-`workflow_ai_agents` array — a `cast_assoc`, not a separate attach
-call) to bind it into the enrichment phase. Three pieces are worth
-noting.
-
-The **filter** is the gray-zone band: it passes only screenings
-whose `screening_score` is at least `0.80` and below `0.95`. A
-score below `0.80` is an auto-clear and a score at/above `0.95` is
-an auto-block — neither needs the agent, so the filter rejects
-them before any LLM call.
-
-The **context_mapping** projects each screening into the agent's
-input schema. `match_score` is interpolated *without* surrounding
-quotes so it renders as a raw JSON number — the input schema
-declares it `number`, and a quoted `"0.88"` would fail schema
-validation. `screened_entity_name` is read from the regulated
-projection so the agent sees the plaintext name.
-
-The **decision_config** interpolates the agent's `verdict` (read
-from `additional_context["<agent-slug>"].verdict`) into a
-single-element decision array. The two `actions` are keyed
-`decision_key: verified|blocked`; whichever verdict the agent
-emits picks the action that fires, leaving the other `:skipped`.
-Bracket access is used because the agent slug contains hyphens.
-
-```typescript
-const VERDICTS = ['verified', 'blocked'] as const
-
-const GRAY_ZONE_FILTER =
-  '{% if compliance_screening.screening_score >= 0.80 ' +
-  'and compliance_screening.screening_score < 0.95 %}true{% endif %}'
-
-const CONTEXT_MAPPING_BODY =
-  '{' +
-  '"screening_id": "{{ compliance_screening.id }}",' +
-  '"screened_entity_name": "{{ regulated_compliance_screening.screened_entity_name }}",' +
-  '"match_score": {{ compliance_screening.screening_score }}' +
-  '}'
-
-const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].verdict }}"]`
-const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
-
-const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Sanctions Review Workflow ${runSuffix}`,
-  description: 'Runs an LLM disambiguation pass on gray-zone-scored sanctions matches and fires a verdict-keyed SMS.',
-  dataset_type: 'compliance_screening',
-  status: 'live',
-  tags: ['compliance', 'sanctions'],
-  filter_config: {
-    type: 'custom',
-    body: GRAY_ZONE_FILTER,
-    output_schema: { type: 'boolean' },
-  },
-  decision_config: {
-    type: 'custom',
-    body: DECISION_CONFIG_BODY,
-    output_schema: DECISION_OUTPUT_SCHEMA,
-  },
-  actions: VERDICTS.map((verdict) => ({
-    decision_key: verdict,
-    action_type: 'sms',
-    tool_id: toolId,
-    position: 0,
-    trigger_template: 'now',
-    idempotency_template: `{{ compliance_screening.id }}-${verdict}`,
-    tool_call: {
-      tool_call_type: 'sms_request',
-      to: { type: 'custom', body: '+15550000000' },
-      body: {
-        type: 'custom',
-        body: `[${verdict}] {{ additional_context["${ctx.agentSlug}"].comments }}`,
-      },
-      sms_type: 'transactional',
-    },
-  })),
-  // Nest the sanctions-review agent inline. Workflow joins omit
-  // output_schema — the server pins it from the agent's input_schema.
-  workflow_ai_agents: [
-    {
-      ai_agent_id: aiAgentId,
-      position: 0,
-      context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
-    },
-  ],
-})
-workflowId = workflowResp.data.id!
-ctx.workflowSlug = workflowResp.data.slug!
-```
-
-## 005 — create the Atomic FI data source
-
-A workflow runs on rows; rows arrive through the data-activation
-chain. The chain's first link is a `DataSource` — a registration
-of where the rows originate. The `uri` is the system-of-record
-address; it flows into each ingested row's `source_uri`.
-
-```typescript
-const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Atomic FI Source ${runSuffix}`,
-  uri: 'api.atomic.fi',
-  description: 'Atomic FI compliance API — origin of the compliance-screening rows the workflow runs on.',
-  status: 'active',
-  is_default: false,
-})
-dataSourceId = dataSourceResp.data.id!
-```
-
-## 006 — create the Manual Upload tool
-
-The Data Activation Client needs a tool. For inline-JSON ingest a
-`manual_upload` tool is the minimal choice — `intent:
-'data_exchange'` distinguishes it from the SMS tool, and
-`tool_body_type: 'manual_upload'` needs no endpoint or credential
-wiring (the rows arrive in the ingest call body, not by the tool
-fetching them).
-
-```typescript
-const manualUploadToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Manual Upload Tool ${runSuffix}`,
-  description: 'Manual-upload data-exchange tool — backs the DAC that ingests compliance-screening rows.',
-  intent: 'data_exchange',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  data_source_id: dataSourceId,
-  body: { tool_body_type: 'manual_upload' },
-})
-ctx.manualUploadToolId = manualUploadToolResp.data.id!
-```
-
-## 007 — create the Compliance Screening interoperability contract
-
-The interoperability contract is the row-shaping rule: a Liquid
-template that maps an inbound Atomic FI compliance-screening row
-into a payments `ComplianceScreening` upsert. This cookbook
-loads the production Atomic FI compliance-screening + MDM
-templates from the vendored fixtures directory.
-
-`template_config` shapes the ComplianceScreening resource —
-including the `screened_entity_name` field the changeset
-tokenizes automatically. `mdm_input_config` shapes the MDM input
-— the `account_holder_id` plus the entity name the platform's
-master-data resolution keys on to find-or-create the LegalEntity
-+ AccountHolder pair the screening belongs to.
-
-```typescript
-const { readFileSync } = await import('node:fs')
-const { join } = await import('node:path')
-const csTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_compliance_screenings_payments_compliance_screening.liquid'),
-  'utf8',
-)
-const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_compliance_screenings_payments_mdm.liquid'),
-  'utf8',
-)
-
-const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Atomic FI Compliance Screening Contract ${runSuffix}`,
-  description: 'Atomic FI compliance-screenings → Payments ComplianceScreening (custom Liquid + MDM input).',
-  resource_type: 'compliance_screening',
-  template_config: { type: 'custom', body: csTemplate },
-  mdm_input_config: { type: 'custom', body: mdmTemplate },
-  generic_table_id: null,
-})
-interopContractId = contractResp.data.id!
-```
-
-## 008 — create the manual-upload DAC
-
-The Data Activation Client binds the three preceding pieces — the
-manual-upload tool, the data source, and the interop contract —
-into one ingestion endpoint. `tool_call.tool_call_type:
-'manual_upload'` selects the inline-JSON ingest path. The
-server-derived `slug` is the handle §009 ingests rows against.
-
-```typescript
-const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Compliance Screening DAC ${runSuffix}`,
-  description: 'Manual-upload DAC — ingests compliance-screening events into ComplianceScreening via the interop contract.',
-  tool_id: ctx.manualUploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [interopContractId],
-})
-dacId = dacResp.data.id!
-ctx.dacSlug = dacResp.data.slug!
-```
-
-## 009 — ingest two compliance-screening events
-
-Two rows, ingested as inline JSON through the manual-upload DAC.
-They differ in the field the workflow filter cares about:
-`screening_score`. The first row scores `0.88` — squarely in the
-gray zone `[0.80, 0.95)`, so the filter passes it to the agent.
-The second scores `0.20` — an auto-clear, so the filter rejects
-it before any agent call. Each row carries a distinct
-`account_holder_id` so MDM resolves each to its own legal entity.
-Each ingest call gets its own batch id; both are pinned for the
-run scope in §011.
-
-```typescript
-const grayZoneRow = {
-  compliance_screening_number: `CS-GRAY-${runSuffix}`,
-  account_holder_id: `AH-SR-${runSuffix}-gray`,
-  scope: 'account_holder',
-  screening_type: 'sanctions',
-  screening_status: 'pending',
-  screened_entity_type: 'individual',
-  sanctions_screening_status: 'match',
-  screening_score: 0.88,
-  match_count: 1,
-  screened_entity_name: 'Jane Cookbook-Disambiguating-Doe',
-  source_uri: 'api.atomic.fi',
-}
-const autoClearRow = {
-  compliance_screening_number: `CS-CLEAR-${runSuffix}`,
-  account_holder_id: `AH-SR-${runSuffix}-clear`,
-  scope: 'account_holder',
-  screening_type: 'sanctions',
-  screening_status: 'pass',
-  screened_entity_type: 'individual',
-  sanctions_screening_status: 'cleared',
-  screening_score: 0.2,
-  match_count: 0,
-  screened_entity_name: 'John Cookbook-Clear-Smith',
-  source_uri: 'api.atomic.fi',
-}
-
-const [grayZoneIngest, autoClearIngest] = await Promise.all([
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: grayZoneRow }),
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: autoClearRow }),
-])
-ctx.batchGrayZone = grayZoneIngest.data.batch_id!
-ctx.batchAutoClear = autoClearIngest.data.batch_id!
-```
-
-## 010 — wait for both ingest batches to reach steady-state
-
-Ingestion is async — the DAC enqueues per-row jobs that the
-`BatchMergeWorker` drains into the regulated compliance-screening
-table. Poll the DAC's activation logs until both batches show a
-row with `rows_ingested >= 1` and a non-empty `output_files`
-array (the merged Parquet landed in object storage). Only then is
-it safe to run the workflow against these rows.
-
-```typescript
-const targetBatches = new Set([ctx.batchGrayZone, ctx.batchAutoClear])
-const deadline = Date.now() + 90_000
-let greenCount = 0
-while (Date.now() < deadline) {
-  const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, ctx.dacSlug)
-  const green = new Set<string>()
-  for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
-    const b = row.batch_id
-    if (typeof b !== 'string' || !targetBatches.has(b)) continue
-    if (typeof row.rows_ingested !== 'number' || row.rows_ingested < 1) continue
-    const files = row.output_files
-    if (!Array.isArray(files) || files.length === 0) continue
-    green.add(b)
-  }
-  greenCount = green.size
-  if (greenCount === targetBatches.size) break
-  await new Promise((r) => setTimeout(r, 1_000))
-}
-if (greenCount !== targetBatches.size) {
-  throw new Error(`only ${greenCount}/2 compliance-screening batches reached steady-state within 90s`)
-}
-```
-
-## 011 — run the workflow against the two batches
-
-`workflows.run` with `manual_override: false` evaluates the
-filter, so the gray-zone filter genuinely routes each row. The
-SQL where-clause scopes the run to exactly the two batches §009
-ingested (`rcs` is the regulated-compliance-screening alias the
-run-query exposes).
-
-For the gray-zone row the run drives the full agent-driven
-pipeline: filter → agent enrichment (the Ollama call that returns
-the verdict) → decision (the verdict interpolated into the
-decision array) → action fan-out. The auto-clear row is rejected
-at the filter and never reaches the agent. Poll
-`batchLogs.refresh` until the run leaves `:pending`; the window
-is generous because the gray-zone row's enrichment is a live LLM
-inference call.
-
-```typescript
-const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: `rcs.batch_id IN ('${ctx.batchGrayZone}', '${ctx.batchAutoClear}')`,
-  mode: 'live',
-  manual_override: false,
-})
-// run-workflow only SCHEDULES the run. The log id and batch id are
-// written when it fires, so read them back via workflowRuns.get.
-const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
-ctx.runLogId = fired.workflowRunLogId
-ctx.runBatchId = fired.batchId!
-
-const deadline = Date.now() + 240_000
-let status: string | null = null
-while (Date.now() < deadline) {
-  const { data: log } = await api.workflows.batchLogs.refresh(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
-  status = log.status ?? null
-  if (status && status !== 'pending') break
-  await new Promise((r) => setTimeout(r, 2_000))
-}
-if (status === 'failed') throw new Error('agent-driven workflow run reached :failed')
-if (!status || status === 'pending') {
-  throw new Error('workflow run did not leave :pending within 240s')
-}
-```
-
-## 012 — verify the gray-zone filter routed and the agent steered the fan-out
-
-Each row produced a Workflow Execution Log. The gray-zone
-screening passes the filter, reaches the agent, and its WEL is
-`:executing` or `:completed`. The auto-clear screening fails the
-filter, so its WEL is `:filtered` — it never reached the agent. A
-run where both passed — or both were filtered — would mean the
-gray-zone band filter is not actually evaluating the score.
-
-The pass-branch WEL carries exactly **two** action execution logs
-— one per verdict — and exactly **one** is matched (`:pending` or
-`:completed`, the verdict the agent emitted) while the other is
-`:skipped`. That is the proof the agent's verdict actually steered
-the decision rather than firing every action.
-
-```typescript
-const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
-const ourWels = (wfLogs.data ?? []).filter(
-  (w) => (w as { batch_id?: string }).batch_id === ctx.runBatchId,
-)
-if (ourWels.length !== 2) {
-  throw new Error(`expected 2 WELs for the run, got ${ourWels.length}`)
-}
-
-const byStatus: Record<string, number> = {}
-for (const w of ourWels) {
-  const st = (w as { status?: string }).status ?? 'unknown'
-  byStatus[st] = (byStatus[st] ?? 0) + 1
-}
-if ((byStatus.filtered ?? 0) !== 1) {
-  throw new Error(
-    `expected 1 :filtered WEL (the auto-clear screening) — distribution ${JSON.stringify(byStatus)}`,
-  )
-}
-const passWel = ourWels.find((w) => {
-  const st = (w as { status?: string }).status
-  return st === 'executing' || st === 'completed'
-})
-if (!passWel) {
-  throw new Error(`no pass-branch WEL — distribution ${JSON.stringify(byStatus)}`)
-}
-
-const aels =
-  (passWel as { action_execution_logs?: Array<{ status?: string; decision_key?: string }> })
-    .action_execution_logs ?? []
-if (aels.length !== 2) {
-  throw new Error(`expected 2 AELs (one per verdict) on the gray-zone WEL, got ${aels.length}`)
-}
-const aelByStatus: Record<string, number> = {}
-for (const ael of aels) {
-  const st = ael.status ?? 'unknown'
-  aelByStatus[st] = (aelByStatus[st] ?? 0) + 1
-}
-const matched = (aelByStatus.pending ?? 0) + (aelByStatus.completed ?? 0)
-if (matched !== 1) {
-  throw new Error(`expected exactly 1 matched AEL, got ${matched} — ${JSON.stringify(aelByStatus)}`)
-}
-if ((aelByStatus.skipped ?? 0) !== 1) {
-  throw new Error(`expected 1 :skipped AEL — ${JSON.stringify(aelByStatus)}`)
-}
-const routed = aels.find((a) => a.status === 'pending' || a.status === 'completed')
-if (!routed?.decision_key || !/^(verified|blocked)$/.test(routed.decision_key)) {
-  throw new Error(`matched AEL has unexpected decision_key ${routed?.decision_key}`)
-}
-```
-
-## 013 — confirm the verdict-keyed SMS rendered
-
-The matched action fired immediately (`trigger_template: 'now'`)
-and persisted a row in the regulated `message` dataset, carrying
-the fully-rendered SMS body. The body is prefixed with the
-verdict decision_key — `[verified]` or `[blocked]` — followed by
-the agent's free-text `comments`. For this cookbook's fixture
-entity name the agent is prompted toward `verified`, so the
-persisted SMS is prefixed `[verified]`. Search the message
-dataset scoped to this workflow and assert the prefix.
-
-```typescript
-const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
-  search_query: `rm.workflow_id = '${workflowId}'`,
-})
-if (userSearch.status !== 'completed') {
-  throw new Error(`message user-search status=${userSearch.status} error=${userSearch.error_message ?? '(none)'}`)
-}
-
-const deadline = Date.now() + 45_000
-let messages: Array<Record<string, unknown>> = []
-while (Date.now() < deadline && messages.length === 0) {
-  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
-    userSearchId: userSearch.id!,
-    dataAccessMode: 'regulated',
-  })
-  messages = (data.data ?? []) as Array<Record<string, unknown>>
-  if (messages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
-}
-if (messages.length === 0) {
-  throw new Error('no verdict SMS message persisted for the workflow within 45s')
-}
-
-const verdictBody = messages
-  .map((m) => String(m.body ?? ''))
-  .find((body) => body.includes('[verified]') || body.includes('[blocked]'))
-if (!verdictBody) {
-  throw new Error(`no verdict-prefixed SMS body — bodies: ${JSON.stringify(messages.map((m) => m.body))}`)
-}
-if (!verdictBody.includes('[verified]')) {
-  throw new Error(`expected the agent verdict to render [verified] — got: ${verdictBody}`)
-}
-```
-
-## 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 scheduled run 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,
-})
-// The run-log id does not exist until the run fires — wait, do not read a null.
-const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
-if (probeFired.workflowRunLogId.length === 0) {
-  throw new Error('dry-run probe never produced a 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
-  asserts the `0.20`-scored screening's WEL is `:filtered`, a
-  distinct terminal status from `:failed`. A filtered row is a
-  *correct* outcome: the workflow looked at it, the gray-zone
-  filter rendered empty because the score was below `0.80`, and
-  the platform recorded the row as intentionally skipped. The
-  agent is never called for a filtered row — which is the whole
-  point of the band filter: do not spend an LLM inference on a
-  screening a threshold already settles.
-- **The blocked verdict** — the agent's response schema admits
-  `blocked` as well as `verified`. A gray-zone screening on a
-  genuinely sanctioned entity would have the agent emit `blocked`,
-  the decision interpolate `["blocked"]`, and the blocked-keyed
-  SMS fire instead. This cookbook's fixture entity name is
-  deliberately disambiguating so the run is deterministic; a
-  production deployment lets the model's judgement pick the
-  branch.
-- **Agent emits an out-of-enum verdict** — the LLM response
-  schema's `enum` constraint guards the decision interpolation.
-  If the model returned an unexpected string the workflow row's
-  execution log would land `:failed`. Production deployments
-  either tighten the prompt or add a fallback action.
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down created
-resources. The `_setup/payments.md` setup file's
-runSuffix-scoped tenant / datalake / user names mean each run is
-naturally isolated; the seeded local DB is cheap to reset
-(`mix ecto.reset` on the platform repo).
-
-# Outcome
-
-After this cookbook's thirteen steps run green:
-
-- A payments tenant exists with a payments-domain
-  datalake
-- An SMS tool, a chat-completion LLM tool, a Sanctions Review AI
-  agent (qwen3-vl:8b-instruct, verified/blocked response schema), and a
-  Sanctions Review agent-driven workflow are all registered
-- An Atomic FI data source, a Manual Upload tool, a Compliance
-  Screening interop contract, and a manual-upload DAC form a
-  working ingestion chain
-- Two compliance screenings have been ingested through that chain
-  — one gray-zone-scored, one auto-clear
-- Running the workflow routed them correctly: the gray-zone
-  screening passed the band filter, reached the agent, and fanned
-  out to a verdict-keyed SMS; the auto-clear screening was
-  `:filtered` before any agent call
-- The pass-branch WEL is verified row-by-row — two AELs, exactly
-  one matched and one `:skipped`, proving the agent's verdict
-  steered the decision
-- The rendered SMS in the `message` dataset carries the
-  `[verified]` verdict prefix
-
-The business outcome — gray-zone sanctions screenings
-disambiguated by an LLM and routed to a verdict-specific SMS,
-with clear-cut screenings filtered out of the agent path
-entirely — is demonstrated end-to-end, not merely provisioned.
-
-# See also
-
-- `_setup/payments.md` — the inlined bootstrap that
-  provisions the tenant + datalake this cookbook starts from
-- `kyc-notification-on-account-activation.md` — the
-  static-decision payments cookbook; same SMS wiring, full
-  data-activation chain, no agent
-- `score-leads-with-llm-categorization.md`,
-  `contact-us-triage-with-llm.md` — the foundation and healthcare
-  agent-driven cookbooks; same agent + decision-interpolation
-  shape
-- `.agent/tools.md` — SMS and chat-completion tool body shapes;
-  intent classification
-- `.agent/ai_agents.md` — AI agent registration shape; input +
-  response schemas; `data_access` regulated vs unregulated
-- `.agent/workflows.md` — standard and agent-driven workflow
-  primitives; `ai_agents`, `context_mapping_config`, and
-  agent-output decision interpolation
-- `.agent/interoperability_contracts.md` — custom contract shape,
-  `template_config` vs `mdm_input_config`
-- `.agent/cookbook/_fixtures/payments/` — the vendored Atomic
-  FI compliance-screening / MDM Liquid templates §007 loads
-- `integration-tests/tests/payments/sanctions-review-workflow.test.ts` —
-  the anchor green test these snippets are lifted from
-- `integration-tests/tests/payments/interoperability-contracts.test.ts`,
-  `run-dac-single.test.ts`, `create-dac.test.ts`, `tools.test.ts`,
-  `data-sources.test.ts` — the per-resource create + ingest
-  snippets §005–§010 are lifted from