@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/payments-compliance.md

@@ -0,0 +1,2180 @@
+---
+title: "Payments compliance: screen, decide, notify — on a tokenized lake"
+summary: The whole payments-compliance surface in one walk. Stand up a tenant and a raw datalake, turn tokenization on because a model is going to read this data, then run two scenarios end to end — an LLM agent disambiguating gray-zone sanctions screenings into a verdict-keyed SMS fan-out, and a KYC notification fired by an account activation. Ends by reading one row back through raw, tokenized and redacted keys to show what each reader actually sees, then inspecting how far the tokenized copy has got and repairing one of its tables.
+use_case: payments-compliance
+slug: payments-compliance
+vitest_source:
+  - integration-tests/tests/payments-compliance/sanctions-review-workflow.test.ts
+  - integration-tests/tests/payments-compliance/kyc-upload-workflow.test.ts
+  - integration-tests/tests/payments-compliance/interoperability-contracts.test.ts
+  - integration-tests/tests/payments-compliance/run-dac-single.test.ts
+  - integration-tests/tests/payments-compliance/create-dac.test.ts
+  - integration-tests/tests/payments-compliance/system-templates.test.ts
+  - integration-tests/tests/payments-compliance/manual-upload-tool.test.ts
+  - integration-tests/tests/payments-compliance/data-sources.test.ts
+  - integration-tests/tests/workspace/bootstrap.test.ts
+status: draft
+---
+
+# Problem
+
+A payments compliance team has two jobs that look like one. Screenings
+arrive from a provider and most of them answer themselves — a clean pass,
+an obvious hit. The ones in the middle are the work, and they are the ones
+a human should not be reading first. Separately, an account activation has
+to reach the holder as a notification, promptly, and not at all if the
+account was suspended instead.
+
+Both are the same shape: rows land, a filter decides which ones matter, and
+something is sent about the ones that do. This walk builds both on one
+tenant, because a compliance team does not run two platforms.
+
+It also turns **tokenization** on, and that is the point of doing this
+surface rather than another one. A gray-zone screening is disambiguated by
+a language model. The model needs the shape of the record — the score, the
+match count, the type — and it does not need the name of the person. The
+tokenized copy of the lake is what makes that distinction enforceable
+rather than a promise, so this walk provisions it in §007 and reads
+through it in §037.
+
+# Composition
+
+| Resource                            | Why it exists here                          |
+|-------------------------------------|---------------------------------------------|
+| Tenant + raw datalake               | The compliance team's own world             |
+| Tokenized + redacted datalakes      | A model reads this data — see §007          |
+| SMS tool, LLM tool, Manual Upload   | Shared by both scenarios                    |
+| Atomic FI data source               | Where both feeds claim to come from         |
+| Sanctions Review AI agent           | Disambiguates the gray zone                 |
+| Two generic tables + contract pairs | Screenings, and payment accounts            |
+| Four Data Activation Clients        | Identity then data, per pair — see §020     |
+| Two agentic workflows               | Verdict fan-out, and activation notice      |
+
+# Walkthrough
+
+This cookbook is **self-reliant**: it stands up everything it uses and
+depends on no other file. It is also **idempotent** — every creating step
+looks first and creates only what is missing, so running it twice costs
+what running it once cost. That is not a nicety. Nothing in the platform
+reclaims an abandoned datalake, and a walk that mints a fresh tenant per
+run leaves every previous run's lakes behind forever.
+
+## 001 — sign in as root, and make sure the admin user exists
+
+Authenticate as the platform's root admin (`admin@dev.local` /
+`devpassword` in local dev) via the tenantless bootstrap login — keyless by
+structural necessity, since no tenant exists yet to scope a key to, and a
+dev/test-only surface.
+
+Then make sure the admin user this walk runs as exists. **The email is
+stable, not per-run**, which is what makes the step idempotent — and it
+means the second run finds the user already signed up. A duplicate signup
+is refused, so the refusal is caught and inspected: if it says the email is
+taken, that is the idempotent path and the walk continues. Any other
+failure is re-raised, because swallowing it would turn a real auth problem
+into a confusing failure three steps later.
+
+```typescript
+ctx.rootSession = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: process.env.ALVERA_ROOT_EMAIL!,
+  password: process.env.ALVERA_ROOT_PASSWORD!,
+})
+ctx.rootApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
+})
+
+ctx.sarahEmail = 'cookbook-payments-compliance@dev.local'
+ctx.sarahPassword = 'CookbookPass1!'
+
+try {
+  const signUpResp = await ctx.rootApi.admin.signUp({
+    email: ctx.sarahEmail,
+    password: ctx.sarahPassword,
+    first_name: 'Cookbook',
+    last_name: 'Compliance',
+  })
+  await ctx.rootApi.admin.confirmUser(signUpResp.data.id!)
+} catch (err) {
+  // Already provisioned by a previous run. Confirm that is what happened
+  // rather than assuming it — a genuine signup failure must not be read as
+  // "already there".
+  const detail = JSON.stringify((err as { errors?: unknown }).errors ?? err)
+  if (!/taken|already|exist/i.test(detail)) throw err
+}
+```
+
+## 002 — the find-or-create helper every later step uses
+
+Idempotence is one question asked over and over: *is this already here?*
+Rather than answer it eleven different ways, the walk defines it once.
+
+`ensure` takes a label, a lookup and a create. It runs the lookup, returns
+what it finds, and only creates when the lookup comes back empty. The label
+is not decoration — when a run reuses something you did not expect it to,
+the log line naming it is how you find out.
+
+The helper lives on `ctx` rather than as a bare function because each
+numbered step compiles into its own `it()` block, so a plain `function`
+here would not be in scope for the steps that call it.
+
+```typescript
+ctx.ensure = async <T>(
+  label: string,
+  find: () => Promise<T | undefined>,
+  create: () => Promise<T>,
+): Promise<T> => {
+  const existing = await find()
+  if (existing !== undefined) {
+    console.log(`  ↻ reusing ${label}`)
+    return existing
+  }
+  console.log(`  + creating ${label}`)
+  return await create()
+}
+```
+
+## 003 — the tenant
+
+Sarah signs in without a tenant scope — she may not belong to one yet — and
+the walk finds or creates the compliance tenant by its stable name. The
+server derives the slug; capture it, because every later call is addressed
+by it.
+
+```typescript
+ctx.sarahTenantlessSession = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+})
+ctx.sarahTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.sarahTenantlessSession.sessionToken,
+  apiKey: '',
+})
+
+const TENANT_NAME = 'Cookbook Payments Compliance'
+
+const tenant = await ctx.ensure(
+  `tenant ${TENANT_NAME}`,
+  async () => {
+    const { data } = await ctx.sarahTenantlessApi.tenants.list()
+    return (data.data ?? []).find((t: { name?: string }) => t.name === TENANT_NAME)
+  },
+  async () => {
+    const { data } = await ctx.sarahTenantlessApi.tenants.create({ name: TENANT_NAME })
+    return data
+  },
+)
+tenantSlug = tenant.slug!
+```
+
+## 004 — the tenant-scoped client
+
+A tenant-scoped login requires `X-API-Key`, so a key has to exist before
+sarah can sign in against the tenant. Mint one through the platform-admin
+side door with the root bearer; in the web console this is
+*Settings → API Keys*.
+
+`data_access_mode: 'raw'` is deliberate. Raw is the superset, and every
+read-back in this walk is a question about **this walk's own data** — not
+about whether replication has caught up. The tokenized and redacted reads
+are a separate subject with their own step and their own keys (§037).
+
+**This is the one step in the walk that is not idempotent**, and it is
+worth knowing why rather than discovering it. There is no endpoint that
+lists a tenant's API keys, so there is nothing to look the existing one up
+with — `ensure` has no lookup to run. Each run therefore mints another key.
+A key row is cheap where a datalake is not, so the walk accepts it; if you
+are counting rows in a shared environment, this is the one to count.
+
+```typescript
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: 'Cookbook Payments Compliance Key',
+  data_access_mode: 'raw',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
+const sarahTenantSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.sarahEmail,
+  password: ctx.sarahPassword,
+  tenantSlug,
+  apiKey: ctx.tenantApiKey,
+})
+api = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: sarahTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
+})
+```
+
+## 005 — the datalake
+
+One datalake, created `raw`. A datalake is one database and one bucket; the
+tokenized and redacted copies are separate rows provisioned in §007 and
+filled by replication, never written to directly.
+
+The lookup filters on `type === 'raw'`, and that matters from the second
+run onwards: once §007 has run, `datalakes.list` returns three rows, and
+two of them are derived copies that must never be mistaken for the primary.
+
+Local-dev defaults match the seeded `dev.exs` setup — `postgres` on
+`localhost:5432`, database `alvera_dev_payments`, LocalStack S3 on
+`localhost:4566` — and the schema name is stable, because a fresh schema
+per run is the same leak as a fresh tenant per run.
+
+```typescript
+const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_payments' }
+const DB_SCHEMA = 'cookbook_payments_compliance'
+const LAKE_NAME = 'Cookbook Payments Compliance Datalake'
+
+const S3 = {
+  cloud_storage_type: 'aws' as const,
+  region: 'us-east-1',
+  access_key_id: 'test',
+  secret_access_key: 'test',
+  endpoint: 'http://localhost:4566',
+}
+
+const datalake = await ctx.ensure(
+  `datalake ${LAKE_NAME}`,
+  async () => {
+    const { data } = await api.datalakes.list(tenantSlug)
+    return (data.data ?? []).find(
+      (l: { name?: string; type?: string }) => l.name === LAKE_NAME && l.type === 'raw',
+    )
+  },
+  async () => {
+    const { data } = await api.datalakes.create(tenantSlug, {
+      name: LAKE_NAME,
+      description: 'Payments compliance datalake provisioned by the cookbook doctest.',
+      timezone: 'America/New_York',
+      pool_size: 3,
+      type: 'raw',
+
+      db_writer_host: DB.host,
+      db_writer_port: DB.port,
+      db_writer_name: DB.name,
+      db_writer_schema: DB_SCHEMA,
+      db_writer_auth_method: 'password',
+      db_writer_user: DB.user,
+      db_writer_pass: DB.pass,
+      db_writer_enable_ssl: false,
+      db_reader_host: DB.host,
+      db_reader_port: DB.port,
+      db_reader_name: DB.name,
+      db_reader_schema: DB_SCHEMA,
+      db_reader_auth_method: 'password',
+      db_reader_user: DB.user,
+      db_reader_pass: DB.pass,
+      db_reader_enable_ssl: false,
+
+      cloud_storage: { ...S3, bucket: 'alvera-platform-dev', base_path: 'cookbook/payments-compliance' },
+    })
+    return data
+  },
+)
+datalakeSlug = datalake.slug!
+ctx.datalakeId = datalake.id!
+```
+
+## 006 — run the migrations, and wait for ready
+
+`datalakes.create` persists the row at `status: 'new'`; it does not run the
+schema DDL. Migration is triggered separately so the operator decides when
+the potentially-slow part happens. `datalakes.migrate` enqueues the job and
+returns immediately with `status: 'enqueued'`; the poll after it is what
+waits for the worker.
+
+Migrating is safe to repeat, which is what lets this step stay unguarded on
+a second run. The wait exits the moment the lake reports `ready`, so the
+five-minute ceiling is only ever paid in failure.
+
+```typescript
+const migrateResp = await api.datalakes.migrate(tenantSlug, datalakeSlug)
+if (migrateResp.data.status !== 'enqueued') {
+  throw new Error(`datalake migration not enqueued (status: ${migrateResp.data.status})`)
+}
+
+const READY_TIMEOUT_MS = 5 * 60_000
+const deadline = Date.now() + READY_TIMEOUT_MS
+let datalakeStatus: string | undefined
+while (Date.now() < deadline) {
+  const { data } = await api.datalakes.get(tenantSlug, ctx.datalakeId)
+  datalakeStatus = data.status
+  if (datalakeStatus === 'ready') break
+  await new Promise((r) => setTimeout(r, 5_000))
+}
+if (datalakeStatus !== 'ready') {
+  throw new Error(`datalake did not reach :ready within ${READY_TIMEOUT_MS}ms (last: ${datalakeStatus})`)
+}
+```
+
+## 007 — turn tokenization on, because a model is going to read this
+
+A datalake is created raw and stays raw. Tokenization is one separate call,
+and it is a decision, not a default: *the tokenized copy is for a machine,
+the redacted copy is for a person*, and you turn them on when one of those
+readers is about to look. Here one is — the agent in §016 reads screenings
+to disambiguate them, and it has no business seeing who was screened.
+
+`provisionTokenization` creates both derived lakes and enqueues a migration
+for each. It is **both-or-neither**: a run that provisions the tokenized
+lake and cannot provision the redacted one reports the failure rather than
+leaving half a pair. It is **idempotent**, so this step needs no `ensure`
+around it — already-provisioned lakes come back as they are.
+
+**Order matters.** The raw lake must be `ready` before this runs. A derived
+lake is provisioned empty and its own migration is what creates its tables
+and starts the copy; provision too early and you get lakes that exist and
+stay empty forever. That is why §006 waits.
+
+```typescript
+const { data: provisioned } = await api.datalakes.provisionTokenization(tenantSlug, datalakeSlug)
+const derivedLakes = provisioned.derived_datalakes ?? []
+if (derivedLakes.length === 0) {
+  throw new Error('provisionTokenization returned no derived datalakes')
+}
+
+// Each derived lake migrates on its own job. Poll the DERIVED ids — the raw
+// lake's own status says nothing about whether its copies are ready.
+const DERIVED_TIMEOUT_MS = 5 * 60_000
+let pendingLakes = derivedLakes.map((d) => d.id!)
+const derivedDeadline = Date.now() + DERIVED_TIMEOUT_MS
+while (Date.now() < derivedDeadline && pendingLakes.length > 0) {
+  const stillPending: string[] = []
+  for (const id of pendingLakes) {
+    const { data } = await api.datalakes.get(tenantSlug, id)
+    if (data.status !== 'ready') stillPending.push(id)
+  }
+  pendingLakes = stillPending
+  if (pendingLakes.length > 0) await new Promise((r) => setTimeout(r, 5_000))
+}
+if (pendingLakes.length > 0) {
+  throw new Error(`derived datalakes did not reach :ready: ${pendingLakes.join(', ')}`)
+}
+```
+
+## 008 — three helpers the scenarios below share
+
+**`waitForFiredRun`.** `workflows.run` only *schedules* a run. It returns
+immediately with a `workflow_run_id`, and the `workflow_run_log_id` and
+`batch_id` a scenario needs are written later, when the run actually fires.
+Two traps live in that gap:
+
+- **Poll until `workflow_run_log_id` is a string — not until `status`
+  leaves `'scheduled'`.** Those are different moments; the run reaches
+  `processing` first and writes the log id a beat later. A predicate on
+  status alone releases you to read a `null`, and because
+  `typeof null === 'object'` the symptom is a baffling *"expected string,
+  got object"* rather than an obvious nil.
+- **Raise on `failed` carrying `failure_reason`** rather than polling to
+  the deadline. A scenario blocked on a run that will never fire should say
+  why on the first read, not thirty seconds later behind a generic timeout.
+
+**`waitForBatches`.** Ingestion is async: `ingest` returns a `batch_id` the
+instant the rows are accepted, and the per-row jobs drain into the lake
+afterwards. This polls a DAC's activation logs until every named batch has
+actually written.
+
+**Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+different questions — received versus written — and a batch whose row is
+refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`
+with the reason in `error`. A gate on `rows_ingested` calls that green, the
+next step then runs against a table with nothing in it, and the failure
+surfaces three steps later as *"expected 2 execution logs, got 0"* — which
+reads like a broken workflow rather than a row that never landed. Raising
+here, where the reason is still attached, costs one line.
+
+**`deployGenericTable`.** Creating a generic table does not deploy it; it
+rests at `status: 'new'` until a migration runs, and `datalakes.migrate`
+enqueues one job per lake so a single call builds the table in all three.
+
+The wait is the part worth getting right, because the obvious one is a
+false green. Polling the derived lakes until they report `ready` returns in
+milliseconds and proves nothing — a derived lake is `ready` whether or not
+any particular table exists in it. Waiting on the table's own
+`status: 'deployed'` is no better; that is the raw lake's answer, and it
+goes true before the copies exist. The only wait that means anything asks
+for the table the same way the next step is about to, and retries until it
+stops erroring.
+
+```typescript
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs = 120_000,
+): Promise<{ workflowRunLogId: string; batchId: string | null }> => {
+  const deadline = Date.now() + timeoutMs
+  let lastStatus: string | undefined
+  while (Date.now() < deadline) {
+    const { data } = await api.workflowRuns.get(tenantSlug, runDatalakeSlug, runId)
+    lastStatus = data.status
+    if (data.status === 'failed') {
+      throw new Error(`workflow run ${runId} failed: ${data.failure_reason ?? 'no failure_reason given'}`)
+    }
+    if (typeof data.workflow_run_log_id === 'string') {
+      return { workflowRunLogId: data.workflow_run_log_id, batchId: data.batch_id ?? null }
+    }
+    await new Promise((r) => setTimeout(r, 1_000))
+  }
+  throw new Error(`workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`)
+}
+
+ctx.waitForBatches = async (
+  dacSlug: string,
+  batchIds: readonly string[],
+  timeoutMs = 90_000,
+): Promise<void> => {
+  const targets = new Set(batchIds)
+  const deadline = Date.now() + timeoutMs
+  let greenCount = 0
+  while (Date.now() < deadline) {
+    const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, 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' || !targets.has(b)) continue
+      if (row.status === 'partial' || row.status === 'failed') {
+        throw new Error(
+          `batch ${b} on ${dacSlug} did not persist its rows (status: ${row.status}): ` +
+            `${String(row.error ?? 'no reason given')}`,
+        )
+      }
+      if (typeof row.dataset_updated !== 'number' || row.dataset_updated < 1) continue
+      const files = row.output_files
+      if (!Array.isArray(files) || files.length === 0) continue
+      green.add(b)
+    }
+    greenCount = green.size
+    if (greenCount === targets.size) return
+    await new Promise((r) => setTimeout(r, 1_000))
+  }
+  throw new Error(`only ${greenCount}/${targets.size} batches on ${dacSlug} persisted within ${timeoutMs}ms`)
+}
+
+ctx.deployGenericTable = async (tableName: string, timeoutMs = 120_000): Promise<void> => {
+  await api.datalakes.migrate(tenantSlug, datalakeSlug)
+  const deadline = Date.now() + timeoutMs
+  let lastError: unknown
+  while (Date.now() < deadline) {
+    try {
+      await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+        sql: `SELECT 1 FROM ${tableName} LIMIT 1`,
+        mode: 'raw',
+      })
+      return
+    } catch (err) {
+      lastError = err
+      await new Promise((r) => setTimeout(r, 1_000))
+    }
+  }
+  throw new Error(
+    `generic table ${tableName} was not readable within ${timeoutMs}ms ` +
+      `(last error: ${lastError instanceof Error ? lastError.message : String(lastError)})`,
+  )
+}
+```
+
+## 009 — the SMS tool
+
+Both scenarios send SMS, so the tool is created once and shared.
+`body.tool_body_type: 'sns'` routes via AWS SNS; local dev points it at
+LocalStack on `http://localhost:4566` through `endpoint_url`, so no real AWS
+credentials are needed. `intent: 'sms'` tags the tool for workflow actions
+that send SMS — as opposed to `data_exchange`, which is what an ingestion
+tool carries.
+
+```typescript
+const smsTool = await ctx.ensure(
+  'SMS tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook Compliance SMS Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Compliance SMS Tool',
+      description: 'SNS-backed SMS dispatcher for both compliance workflows, 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',
+      },
+    })
+    return data
+  },
+)
+toolId = smsTool.id!
+```
+
+## 010 — the LLM tool
+
+The sanctions agent calls a chat-completion endpoint to disambiguate each
+gray-zone screening. `intent: 'llm_enrichment'` distinguishes it from the
+SMS tool.
+
+It is a **provider adapter**, and both halves matter. `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. `response_extractor` maps the provider's envelope
+back to the canonical `{ output_json, … }` the platform reads, and its
+`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": {{ temperature }}, "num_predict": {{ max_tokens }}, "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 llmTool = await ctx.ensure(
+  'LLM tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook Compliance LLM Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Compliance LLM Tool',
+      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 },
+      },
+    })
+    return data
+  },
+)
+ctx.llmToolId = llmTool.id!
+```
+
+## 011 — the Atomic FI data source
+
+A workflow runs on rows, and 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, and it flows into each
+ingested row as `source_uri`, which is also what the MDM template in §019
+reads to build its identifier. Both feeds in this walk claim the same
+origin, so they share one source and converge on one subject.
+
+```typescript
+const dataSource = await ctx.ensure(
+  'Atomic FI data source',
+  async () => {
+    const { data } = await api.dataSources.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Atomic FI Source')
+  },
+  async () => {
+    const { data } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Atomic FI Source',
+      uri: 'api.atomic.fi/compliance',
+      description: 'Atomic FI compliance API — origin of the screening and payment-account rows.',
+      status: 'active',
+      is_default: false,
+    })
+    return data
+  },
+)
+dataSourceId = dataSource.id!
+```
+
+## 012 — the Manual Upload tool
+
+A Data Activation Client needs a tool. For inline-JSON ingest a
+`manual_upload` tool is the minimal choice: `tool_body_type:
+'manual_upload'` needs no endpoint or credential wiring, because the rows
+arrive in the ingest call's body rather than by the tool fetching them.
+
+```typescript
+const manualUploadTool = await ctx.ensure(
+  'Manual Upload tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook Manual Upload Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Manual Upload Tool',
+      description: 'Manual-upload data-exchange tool — backs both DACs in this walk.',
+      intent: 'data_exchange',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: dataSourceId,
+      body: { tool_body_type: 'manual_upload' },
+    })
+    return data
+  },
+)
+ctx.manualUploadToolId = manualUploadTool.id!
+```
+
+## 013 — what the platform already ships: the system-template catalog
+
+Before hand-writing Liquid, look at what is already there. `systemTemplates`
+returns every platform-shipped template visible to this datalake — each with
+a `path`, its Liquid `content`, and an `output_schema` (`null` when the
+template ships no companion schema).
+
+**The catalog is flat.** It used to be filtered by the datalake's data
+domain, so a payments template never appeared in a subscription lake;
+GH-859 removed domains and with them the filter. What one datalake can see,
+every datalake can see. The assertion below is the positive form of that
+fact: no path carries a retired vertical segment.
+
+```typescript
+const { data: templates } = await api.templates.systemTemplates(tenantSlug, datalakeSlug)
+
+const paths = (templates.data ?? []).map((t) => t.path)
+if (paths.length === 0) {
+  throw new Error('expected the platform to ship at least one system template')
+}
+
+const anchor = 'data_activation/interoperability/stripe/customers_stripe_legal_entity'
+if (!paths.some((p) => p.includes(anchor))) {
+  throw new Error(`expected the Stripe customer template (${anchor}) in the list`)
+}
+
+const RETIRED_DOMAINS = ['healthcare', 'payments', 'foundation', 'core_banking', 'service_commerce', 'trading']
+const stale = paths.filter((p) => RETIRED_DOMAINS.some((d) => p.split('/').includes(d)))
+if (stale.length > 0) {
+  throw new Error(`template paths still carry a retired data-domain segment: ${stale.join(', ')}`)
+}
+```
+
+## 014 — the same catalog as markdown, and the page you will forget to read
+
+`metadata` returns the catalog as a markdown document — the form an agent
+reads to choose a template. It inlines each template's full Liquid source,
+so it is long.
+
+**It paginates, and page 1 is not the catalog.** The document opens with
+`Showing page 1 of N — M templates total`, and the template you want is as
+likely to be on page 3. Reading page 1 and concluding a template does not
+exist is the trap, and it used to be hidden: the per-domain filter made the
+list short enough to fit one page, and GH-859 removed that filter.
+
+```typescript
+let found = false
+let page = 1
+let pages = 1
+do {
+  const { data: catalog } = await api.templates.metadata(tenantSlug, datalakeSlug, { page })
+  if (typeof catalog !== 'string' || catalog.length === 0) {
+    throw new Error(`expected a non-empty markdown template catalog on page ${page}`)
+  }
+  const header = catalog.match(/Showing page \d+ of (\d+)/)
+  if (header) pages = Number(header[1])
+  if (catalog.includes('customers_stripe_legal_entity')) found = true
+  page += 1
+} while (!found && page <= pages)
+
+if (!found) {
+  throw new Error(`expected the Stripe customer template in the catalog markdown (searched ${pages} page(s))`)
+}
+```
+
+## 015 — one template's detail, by basename and intent
+
+`metadataDetails` pulls a single template. Address it by its **basename**
+(the template name without the path) and its **intent** (the path prefix
+joined with underscores — here `data_activation_interoperability`), not by
+the full path. The result is a markdown body to show an operator, or to feed
+an agent, before copying the template into a contract's `template_config`.
+
+```typescript
+const { data: detail } = await api.templates.metadataDetails(
+  tenantSlug,
+  datalakeSlug,
+  'customers_stripe_legal_entity',
+  'data_activation_interoperability',
+)
+if (typeof detail !== 'string' || detail.length === 0) {
+  throw new Error('expected a non-empty markdown detail for the Stripe customer template')
+}
+```
+## 016 — the Sanctions Review agent
+
+The agent binds three things: the model, an input schema the workflow's
+context-mapping must satisfy, and a response schema its output must match.
+The response schema's `enum: ['verified','blocked']` is a guard — it stops
+the agent emitting a verdict the workflow has no action for.
+`temperature: 0.0` removes sampling noise so the walk is deterministic.
+
+`data_access: 'raw'` is the interesting decision, and it is deliberately
+the opposite of what §007 might lead you to expect. `screened_entity_name`
+is a `tokenize` column, and this agent's whole job is to judge whether a
+name is a true match or a coincidence — a token tells it nothing. So this
+agent reads raw. §037 shows the reader for whom the tokenized copy is the
+right answer. **Tokenization is a per-reader decision, not a lake-wide
+setting**, and an agent that does not need plaintext should not ask for it.
+
+```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 agent = await ctx.ensure(
+  'Sanctions Review agent',
+  async () => {
+    const { data } = await api.aiAgents.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Sanctions Review Agent')
+  },
+  async () => {
+    const { data } = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Sanctions Review Agent',
+      tool_id: ctx.llmToolId,
+      model: 'qwen3-vl:8b-instruct',
+      data_access: 'raw',
+      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 },
+    })
+    return data
+  },
+)
+aiAgentId = agent.id!
+ctx.agentSlug = agent.slug!
+```
+
+## 017 — the compliance-screenings table
+
+The workflow needs an event source. GH-859 removed the
+`compliance_screening` dataset along with every other per-domain resource,
+so a screening is a table you declare.
+
+Four column decisions carry this walk.
+
+`screening_score` is a **float**, not a string. The gray-zone filter
+compares it with `>=` and `<`; a string column compares lexically and the
+band silently stops meaning anything.
+
+`screened_entity_name` is `tokenize` and `review_notes` is `redact`. That
+declaration **is** the masking policy — there is no changeset doing it on
+the way past any more, and no second schema to write into. `privacy_requirement`
+is a floor, not an instruction: a `tokenize` column is tokenized in the
+tokenized copy and redacted in the redacted one.
+
+`sanctions_matches` is `jsonb` **and `is_array: true`**. The second half is
+not optional and its absence does not look like a type error. `is_array`
+defaults to `false`, which compiles the column's schema as a single map, so
+ingesting a JSON array into it is refused per row —
+`upsert_row_failed %{sanctions_matches: ["is invalid"]}` — while the batch
+still reports a row received.
+
+Do **not** declare a `legal_entity_id` column. The platform stamps it from
+Contract B's MDM resolve in §019, and the name is reserved — declaring it
+does not shadow the stamp silently, it 422s the create.
+
+```typescript
+const screenings = await ctx.ensure(
+  'compliance-screenings table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Compliance Screenings')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Compliance Screenings',
+      description: 'Sanctions/AML screenings loaded from the Atomic FI API',
+      columns: [
+        { name: 'compliance_screening_number', title: 'Screening Number', type: 'string', description: "The provider's screening id — unique per screening", is_unique: true, privacy_requirement: 'none' },
+        { name: 'account_holder_ref', title: 'Account Holder Ref', type: 'string', description: "The provider's account-holder id — the identifier MDM resolves on", is_unique: false, privacy_requirement: 'none' },
+        { name: 'scope', title: 'Scope', type: 'string', description: 'What the screening was run against', is_unique: false, privacy_requirement: 'none' },
+        { name: 'screening_type', title: 'Screening Type', type: 'string', description: 'sanctions / pep / adverse_media', is_unique: false, privacy_requirement: 'none' },
+        { name: 'screening_status', title: 'Screening Status', type: 'string', description: 'pending / pass / fail', is_unique: false, privacy_requirement: 'none' },
+        { name: 'screened_entity_type', title: 'Screened Entity Type', type: 'string', description: 'individual / business', is_unique: false, privacy_requirement: 'none' },
+        { name: 'screening_score', title: 'Screening Score', type: 'float', description: 'Match confidence 0-1 — the gray-zone band compares on it numerically', is_unique: false, privacy_requirement: 'none' },
+        { name: 'match_count', title: 'Match Count', type: 'integer', description: 'How many list entries matched', is_unique: false, privacy_requirement: 'none' },
+        { name: 'sanctions_screening_status', title: 'Sanctions Status', type: 'string', description: 'match / cleared', is_unique: false, privacy_requirement: 'none' },
+        { name: 'screened_entity_name', title: 'Screened Entity Name', type: 'string', description: 'Name that was screened — the agent disambiguates on it', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'review_notes', title: 'Review Notes', type: 'string', description: 'Free-text reviewer narrative', is_unique: false, privacy_requirement: 'redact' },
+        { name: 'pep_list_name', title: 'PEP List Name', type: 'string', description: 'Politically-exposed-person list the entity appears on', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'aml_risk_score', title: 'AML Risk Score', type: 'float', description: 'Analytic AML risk score', is_unique: false, privacy_requirement: 'none' },
+        { name: 'aml_velocity_count', title: 'AML Velocity Count', type: 'integer', description: 'Transaction-velocity signal', is_unique: false, privacy_requirement: 'none' },
+        { name: 'aml_high_risk_country', title: 'AML High Risk Country', type: 'string', description: 'High-risk jurisdiction flag', is_unique: false, privacy_requirement: 'none' },
+        { name: 'sanctions_matches', title: 'Sanctions Matches', type: 'jsonb', description: 'The matched list entries, as a JSON array', is_unique: false, is_array: true, privacy_requirement: 'redact' },
+      ],
+    })
+    return data
+  },
+)
+ctx.screeningsTableId = screenings.id!
+ctx.screeningsTableName = screenings.name!
+
+// Creating a table records it; deploying it is a migration. Called
+// unconditionally rather than only on the create branch, so a run that
+// crashed between the two still converges.
+await ctx.deployGenericTable(ctx.screeningsTableName)
+```
+
+## 018 — the Sanctions Review workflow
+
+Filter, decision, actions — plus the agent **nested** in the create body
+via `workflow_ai_agents` (a `cast_assoc`, not a separate attach call).
+Three pieces are worth stopping on.
+
+The **filter** is the gray-zone band: it passes only screenings scoring at
+least `0.80` and below `0.95`. Below `0.80` is an auto-clear and at or
+above `0.95` is an auto-block — neither needs a model, so the filter
+rejects them before any LLM call is paid for.
+
+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"` fails validation.
+
+The **decision_config** interpolates the agent's `verdict` — read from
+`additional_context["<agent-slug>"]` with bracket access, because the slug
+contains hyphens — 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 and leaves the other `:skipped`.
+
+```typescript
+const VERDICTS = ['verified', 'blocked'] as const
+
+const GRAY_ZONE_FILTER =
+  '{% if event_dataset.screening_score >= 0.80 ' +
+  'and event_dataset.screening_score < 0.95 %}true{% endif %}'
+
+const CONTEXT_MAPPING_BODY =
+  '{' +
+  '"screening_id": "{{ event_dataset.compliance_screening_number }}",' +
+  '"screened_entity_name": "{{ event_dataset.screened_entity_name }}",' +
+  '"match_score": {{ event_dataset.screening_score }}' +
+  '}'
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].verdict }}"]`
+const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
+
+const workflow = await ctx.ensure(
+  'Sanctions Review workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook Sanctions Review Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Sanctions Review Workflow',
+      description: 'Runs an LLM disambiguation pass on gray-zone sanctions matches and fires a verdict-keyed SMS.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.screeningsTableId,
+      status: 'live',
+      tags: ['compliance', 'sanctions'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: GRAY_ZONE_FILTER },
+      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: `{{ event_dataset.compliance_screening_number }}-${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',
+        },
+      })),
+      // Workflow joins omit output_schema — the server pins it from the
+      // agent's own input_schema.
+      workflow_ai_agents: [
+        {
+          ai_agent_id: aiAgentId,
+          position: 0,
+          context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
+        },
+      ],
+    })
+    return data
+  },
+)
+workflowId = workflow.id!
+ctx.workflowSlug = workflow.slug!
+```
+
+## 019 — the Atomic FI contract pair
+
+An inbound screening row becomes two things, so it takes two contracts.
+They are defined together here and deliberately **not** bound to one client
+— §020 is where that matters, and why.
+
+**Contract A** (`resource_type: 'legal_entity'`) writes the account holder
+the screening was run against, keyed on Atomic FI's `account_holder_id`.
+Its `mdm_input_config` is `{ type: 'null' }` — a template that already *is*
+the subject has nothing to resolve.
+
+**Contract B** (`resource_type: 'generic_table'`, pinned to §017's table)
+writes the screening row, and its `mdm_input_config` emits the same
+`(uri, account_holder_id)` pair — collapsing both onto one legal entity and
+stamping `legal_entity_id` onto the screening.
+
+**The identifier shape is where this goes wrong, and there are three of
+them on this platform.** `Platform.MDMInput` — what a contract's
+`mdm_input_config` renders — takes `uri` / `type` / `value`. A LegalEntity
+identification, which is Contract A's own body, takes `id_type` /
+`id_number` / `uri`. And `POST /mdm/verify` takes `system` / `id_type` /
+`value`.
+
+The overlap between them is the trap, and it is not symmetric. `system` is a
+real alias: `MDMInput` casts it and normalises it onto `uri`, so that one
+name is safe in both places. `id_type` and `id_number` are not — an MDM
+identifier casts neither. Unknown keys are dropped rather than refused, so a
+template that reaches for the LegalEntity names on the MDM side resolves
+nothing and fails as a bare `mdm_dispatcher_error` with no field named.
+
+And the reason the two look interchangeable is that **one becomes the
+other**. `MDMInput.to_identification/1` takes `(uri, type, value)` and
+returns `(uri, id_type, id_number)` — the rename happens inside the platform,
+on the way through. So the identifier reads back under names it will not
+accept on the way in, and that asymmetry is invisible from the stored shape
+alone. Do not reach for `/mdm/verify` to check the shape
+either: it requires a `legal_entity_id` and verifies attributes against an
+entity that already exists — it is not a resolver and not a linter.
+
+The templates are loaded from the vendored fixtures rather than inlined.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const read = (f: string) =>
+  readFileSync(join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments-compliance', f), 'utf8')
+
+const leContract = await ctx.ensure(
+  'screening holder LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Screening Holder LE Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Screening Holder LE Contract',
+      description: 'Atomic FI screening → the screened account holder as a LegalEntity.',
+      resource_type: 'legal_entity',
+      type: 'identity',
+      generic_table_id: null,
+      template_config: { type: 'custom', body: read('_compliance_screenings_legal_entity.liquid') },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+ctx.leContractId = leContract.id!
+
+const gtContract = await ctx.ensure(
+  'compliance screening GT contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Compliance Screening GT Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Compliance Screening GT Contract',
+      description: 'Atomic FI screening → compliance_screenings row, stamped with its holder subject.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.screeningsTableId,
+      template_config: { type: 'custom', body: read('_compliance_screenings_generic_table.liquid') },
+      mdm_input_config: { type: 'custom', body: read('_compliance_screenings_mdm.liquid') },
+    })
+    return data
+  },
+)
+interopContractId = gtContract.id!
+```
+
+## 020 — two DACs, because the pair must not run concurrently
+
+The obvious move is one Data Activation Client carrying both contracts.
+**It works on every run but the first, which is the worst way for something
+to be wrong.**
+
+A DAC fans out per `(row, contract)` at enqueue time — one job each — and
+the job key is `"<r2_key>-<index>-<client_id>-<contract_id>"`. The contract
+id is *in* the key, so the pair's two jobs sit in different chains and run
+**at the same instant**: the scheduler staggers by row index, not by
+contract. Contract A writes the holder as a legal entity. Contract B's
+`mdm_input_config` resolves the *same* holder, and resolution is
+find-or-create, so it writes one too. Both miss the dedupe read, both
+insert, and `legal_entity_identifications_uri_type_value_uk` —
+`(uri, id_type, id_number)`, with the legal entity deliberately left out of
+the key — refuses the loser:
+
+```
+upsert_legal_entity_failed %{identifications: [%{uri: ["has already been taken"]}]}
+```
+
+The batch reports `partial`, the row never lands, and the failure surfaces
+several steps later as a missing execution log.
+
+**That index is not a bug you are hitting; it is the guard working.** It
+omits the legal entity from the key precisely so that concurrent workers
+racing to create one subject cannot each succeed and leave duplicates that
+are indistinguishable from two people who genuinely share a handle. One
+writer per subject is the contract, and the second run only looks green
+because the first run's Contract A already created the entity — so nothing
+inserts and nothing collides. Ingest a holder the platform has never seen
+and it fails again.
+
+So the pair is split across two clients over the same tool and data source:
+an **identity** DAC that writes the subject, and a **data** DAC that writes
+the row and resolves the subject that now exists. §021 ingests through them
+in that order, waiting for the first to persist before starting the second.
+That is not a workaround for the index — it is the honest shape of the
+dependency, and it reads as one: an identity feed, then a data feed.
+
+```typescript
+const identityDac = await ctx.ensure(
+  'compliance screening identity DAC',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Compliance Screening Identity DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Compliance Screening Identity DAC',
+      description: 'Manual-upload DAC — writes the screened holder as a legal entity, ahead of the screening row.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [ctx.leContractId],
+    })
+    return data
+  },
+)
+ctx.identityDacSlug = identityDac.slug!
+
+const dac = await ctx.ensure(
+  'compliance screening data DAC',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Compliance Screening Data DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Compliance Screening Data DAC',
+      description: 'Manual-upload DAC — ingests compliance-screening rows, resolving the holder written by the identity DAC.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [interopContractId],
+    })
+    return data
+  },
+)
+dacId = dac.id!
+ctx.dacSlug = dac.slug!
+```
+
+## 021 — ingest two screenings, holders first
+
+Two rows, inline JSON, differing in the one field the filter reads. The
+first scores `0.88` — squarely inside `[0.80, 0.95)`, so the filter passes
+it to the agent. The second scores `0.20`, an auto-clear the filter rejects
+before any agent call.
+
+**The same two rows are ingested twice: through the identity DAC, then
+through the data DAC.** That is the ordering §020 exists for — the holder
+has to be committed before a screening row can resolve it. The first stage
+is waited on before the second starts, and that wait is the whole point;
+firing both stages together reproduces the race the split was made to
+avoid.
+
+Each row carries its own `account_holder_id`, so the two resolve to
+different legal entities and never contend with *each other* — within a
+stage they are independent, and the two `ingest` calls are separate only so
+each row gets its own activation-log row for the gate to key on.
+
+The screening numbers are **stable across runs**, and
+`compliance_screening_number` is the table's unique column — so a second
+run upserts these same two rows rather than adding two more. `source_uri`
+matches the data source's `uri` from §011, which is what both contracts key
+their identifier on.
+
+```typescript
+ctx.grayZoneNumber = 'CS-COOKBOOK-0101'
+ctx.autoClearNumber = 'CS-COOKBOOK-0102'
+// §037 reads this name back through all three lakes.
+ctx.grayZoneName = 'Jane Cookbook-Disambiguating-Doe'
+
+const grayZoneRow = {
+  compliance_screening_number: ctx.grayZoneNumber,
+  account_holder_id: 'AH-COOKBOOK-0101',
+  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: ctx.grayZoneName,
+  source_uri: 'api.atomic.fi/compliance',
+}
+const autoClearRow = {
+  compliance_screening_number: ctx.autoClearNumber,
+  account_holder_id: 'AH-COOKBOOK-0102',
+  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/compliance',
+}
+
+// STAGE 1 — the holders. Contract A writes each screened entity as a legal
+// entity. Nothing resolves anything here, so nothing can collide.
+const holderGray = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.identityDacSlug, { data: grayZoneRow },
+)
+const holderClear = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.identityDacSlug, { data: autoClearRow },
+)
+
+// The wait that makes the split work. Skip it and stage 2 resolves a
+// holder that is still being written, which is the race in a slower shape.
+await ctx.waitForBatches(ctx.identityDacSlug, [
+  holderGray.data.batch_id!,
+  holderClear.data.batch_id!,
+])
+
+// STAGE 2 — the screenings. Contract B resolves the holder that now
+// exists, and the platform stamps `legal_entity_id` onto the row.
+const grayZoneIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.dacSlug, { data: grayZoneRow },
+)
+const autoClearIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.dacSlug, { data: autoClearRow },
+)
+ctx.batchGrayZone = grayZoneIngest.data.batch_id!
+ctx.batchAutoClear = autoClearIngest.data.batch_id!
+```
+
+## 022 — wait for the screening rows to PERSIST, not merely to arrive
+
+The same `waitForBatches` from §008, now on the data DAC. Stage 1 was
+already waited on inside §021; this is the gate on stage 2, and it is what
+stands between a refused row and a workflow that runs against an empty
+table.
+
+```typescript
+await ctx.waitForBatches(ctx.dacSlug, [ctx.batchGrayZone, ctx.batchAutoClear])
+```
+
+## 023 — run the workflow against the two rows
+
+`workflows.run` schedules; it does not fire. The helper from §008 waits for
+the run to actually fire and hands back the log id and batch id the
+verification needs.
+
+```typescript
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: `compliance_screening_number IN ('${ctx.grayZoneNumber}', '${ctx.autoClearNumber}')`,
+  mode: 'live',
+  manual_override: false,
+})
+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')
+}
+```
+
+## 024 — verify the band filtered, 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 band is not actually evaluating the score.
+
+The pass-branch WEL carries exactly **two** action execution logs, one per
+verdict. On the first run exactly one is matched and the other `:skipped`,
+which is the proof the verdict steered the decision rather than every
+action firing.
+
+**On a second run both are `:skipped`, and that is correct.** This is where
+idempotence stops being a property of the walk and becomes a property of
+the product. `idempotency_template` renders
+`{{ event_dataset.compliance_screening_number }}-<verdict>`, the screening
+number is stable, so the key is the key that already fired — and the
+platform refuses to send the same SMS about the same screening twice. That
+is exactly what you want in production, and it means **an assertion on "an
+action fired just now" is wrong**: it tests a transition that only ever
+happens once. Assert the end state instead — the verdict SMS exists for
+this screening — which is what §025 does, and which is true on every run.
+
+```typescript
+const welDeadline = Date.now() + 120_000
+let ourWels: Array<Record<string, unknown>> = []
+let byStatus: Record<string, number> = {}
+while (Date.now() < welDeadline) {
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
+  ourWels = (wfLogs.data ?? [])
+    .map((w) => w as Record<string, unknown>)
+    .filter((w) => w.batch_id === ctx.runBatchId)
+  byStatus = {}
+  for (const w of ourWels) {
+    const st = (w.status as string | undefined) ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const settled = (byStatus.completed ?? 0) + (byStatus.executing ?? 0)
+  if (ourWels.length === 2 && settled === 1 && (byStatus.filtered ?? 0) === 1) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (ourWels.length !== 2) {
+  throw new Error(`expected 2 WELs for the run, got ${ourWels.length}`)
+}
+if ((byStatus.filtered ?? 0) !== 1) {
+  throw new Error(`expected 1 :filtered WEL (the auto-clear) — 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) {
+  // First run for this screening: the verdict picked one action and left
+  // the other alone.
+  if ((aelByStatus.skipped ?? 0) !== 1) {
+    throw new Error(`expected 1 :skipped AEL alongside the matched one — ${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}`)
+  }
+} else if (matched === 0 && (aelByStatus.skipped ?? 0) === aels.length) {
+  // Re-run: this screening's SMS already went out, so the idempotency key
+  // suppressed both actions. §025 is the gate that still has to hold.
+} else {
+  throw new Error(
+    `expected either 1 matched AEL, or all skipped on a repeat run — got ${JSON.stringify(aelByStatus)}`,
+  )
+}
+```
+
+## 025 — confirm the verdict-keyed SMS actually rendered
+
+The matched action fired immediately (`trigger_template: 'now'`) and
+persisted a row in the `message` dataset carrying the fully-rendered body,
+prefixed with the verdict that selected it. For this fixture's entity name
+the agent is prompted toward `verified`, so the persisted SMS reads
+`[verified]`.
+
+**This is the gate, not §024.** It asserts the end state — a verdict SMS
+exists for this screening — which is true on the first run because the
+action just fired, and true on every run after because it fired once and
+the idempotency key has protected it ever since.
+
+**Search on the idempotency key, not on `workflow_id`.** They look
+interchangeable and are not, and the difference only shows up on the run
+you care about most. The key is `<screening number>-<verdict>`, and the
+screening number is stable — so the key names the same SMS forever. A
+workflow *id* is stable only as long as the workflow resource is. Rebuild
+the tenant against a lake that still holds its rows — a reset control
+plane, a restored database, a re-run after `destroy` — and the workflow
+comes back with a new id while the action logs keep the old key. The
+action then correctly refuses to fire, because that key already fired, and
+a search for the new `workflow_id` finds nothing. Green becomes red with
+nothing wrong: the SMS is right there, filed under the identity that did
+not change.
+
+The read answers from **raw**. That is the right tier for this question: it
+asks what this walk wrote, not whether replication has caught up.
+
+```typescript
+const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key LIKE '${ctx.grayZoneNumber}-%'`,
+})
+if (userSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${userSearch.status} error=${userSearch.error_message ?? '(none)'}`)
+}
+
+const msgDeadline = Date.now() + 45_000
+let messages: Array<Record<string, unknown>> = []
+while (Date.now() < msgDeadline && messages.length === 0) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: userSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  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 for screening ${ctx.grayZoneNumber} within 45s — ` +
+      `the action never fired, or it fired under a different idempotency key`,
+  )
+}
+
+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}`)
+}
+```
+
+## 026 — the KYC portal, as a connected app
+
+The second scenario's SMS carries a deep link to a self-serve KYC portal.
+The connected app is a thin registration of that portal's URL and mode —
+the page itself is hosted outside the platform (`mode: 'self_hosted'`). The
+server-derived slug is what §036 resolves the link against.
+
+```typescript
+const connectedApp = await ctx.ensure(
+  'KYC portal connected app',
+  async () => {
+    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook KYC Portal')
+  },
+  async () => {
+    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook KYC Portal',
+      description: 'Self-serve KYC portal linked from the outbound notification SMS.',
+      mode: 'self_hosted',
+      urls: [{ url: 'https://kyc.example.local', is_primary: true, label: 'production' }],
+    })
+    return data
+  },
+)
+connectedAppId = connectedApp.id!
+ctx.connectedAppSlug = connectedApp.slug!
+```
+
+## 027 — the payment-accounts table
+
+`payment_account_external_id` is the unique column. `status` is what the
+filter gates on, and it stays `none` so the workflow can read it in any
+tier.
+
+**`privacy_requirement` is where PCI lives now.** `account_number` and
+`iban` are `tokenize`; the free-text payment narrative is `redact`. That
+declaration is the whole masking policy — there is no second schema to
+write sensitive values into and no changeset quietly tokenizing on the way
+past. The raw value goes in, and the derived lakes decide who sees what.
+
+Again: no `legal_entity_id` column. The platform stamps it from Contract B.
+
+```typescript
+const accounts = await ctx.ensure(
+  'payment-accounts table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Payment Accounts')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Payment Accounts',
+      description: 'Payment accounts loaded from the Atomic FI API',
+      columns: [
+        { name: 'payment_account_external_id', title: 'External ID', type: 'string', description: "The provider's account id — unique per account", is_unique: true, privacy_requirement: 'none' },
+        { name: 'payment_account_number', title: 'Account Ref', type: 'string', description: 'Internal account reference', is_unique: false, privacy_requirement: 'none' },
+        { name: 'account_holder_ref', title: 'Account Holder Ref', type: 'string', description: "The provider's account-holder id — the identifier MDM resolves on", is_unique: false, privacy_requirement: 'none' },
+        { name: 'status', title: 'Status', type: 'string', description: 'active / suspended / pending — the filter gate', is_unique: false, privacy_requirement: 'none' },
+        { name: 'account_type', title: 'Account Type', type: 'string', description: 'bank_account / card / wallet', is_unique: false, privacy_requirement: 'none' },
+        { name: 'currency', title: 'Currency', type: 'string', description: 'Settlement currency', is_unique: false, privacy_requirement: 'none' },
+        { name: 'routing_number', title: 'Routing Number', type: 'string', description: 'Domestic routing number', is_unique: false, privacy_requirement: 'none' },
+        { name: 'swift_bic', title: 'SWIFT/BIC', type: 'string', description: 'ISO 9362 bank identifier', is_unique: false, privacy_requirement: 'none' },
+        { name: 'bank_name', title: 'Bank Name', type: 'string', description: 'Holding institution', is_unique: false, privacy_requirement: 'none' },
+        { name: 'account_number', title: 'Account Number', type: 'string', description: 'PCI-sensitive account number', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'iban', title: 'IBAN', type: 'string', description: 'PCI-sensitive international account number', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'destination_country', title: 'Destination Country', type: 'string', description: 'ISO country derived from the BIC or IBAN, so nothing downstream re-parses it', is_unique: false, privacy_requirement: 'none' },
+        { name: 'purpose_of_payment_detail', title: 'Purpose of Payment', type: 'string', description: 'Free-text payment narrative', is_unique: false, privacy_requirement: 'redact' },
+        { name: 'enabled_regimes', title: 'Enabled Regimes', type: 'string', description: 'Comma-delimited regimes this account may settle under', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
+ctx.accountsTableId = accounts.id!
+ctx.accountsTableName = accounts.name!
+
+await ctx.deployGenericTable(ctx.accountsTableName)
+```
+
+## 028 — the KYC-notification workflow
+
+Standard shape: a filter passing accounts whose `status` is `active`, a
+decision naming one key, and one SMS action. The body references the
+account's external id so the recipient knows which account activated, and
+`{{ connected_app_form_url }}` so the platform bakes in the `/t/<token>`
+portal link.
+
+`skip_mdm_resolution: false` is set explicitly and **must be**. The account
+holder is the subject the portal token is minted against, and it reaches
+the workflow only through the `legal_entity_id` stamped on the row.
+
+A `context_datasets` entry queries the `message` dataset for any
+KYC notification already sent to the same legal entity in the last six
+months — the built-in guard against re-notifying. The join key is
+`legal_entity_id`, and `{{ legal_entity_id }}` is the binding the context
+builder exposes for the resolved subject.
+
+The SMS `to` is a fixed compliance inbox. The holder's own contact fields
+are tokenized, and this workflow deliberately notifies the operator rather
+than the customer.
+
+```typescript
+const FILTER_BODY = '{% if event_dataset.status == "active" %}true{% endif %}'
+const DECISION_KEY = 'send_pr_notification_sms'
+const DECISION_BODY = `["${DECISION_KEY}"]`
+const KYC_DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
+const SMS_BODY_TEMPLATE =
+  'Alvera PR notification — payment_account ' +
+  '{{ event_dataset.payment_account_external_id }} has been activated. ' +
+  'Manage KYC: {{ connected_app_form_url }}'
+
+const kycWorkflow = await ctx.ensure(
+  'KYC notification workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook KYC Notification Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook KYC Notification Workflow',
+      description: 'Sends a KYC-notification SMS for newly activated payment accounts with a self-serve portal link.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.accountsTableId,
+      status: 'live',
+      tags: ['compliance', 'kyc'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: FILTER_BODY },
+      decision_config: {
+        type: 'custom',
+        body: DECISION_BODY,
+        output_schema: KYC_DECISION_OUTPUT_SCHEMA,
+      },
+      context_datasets: [
+        {
+          dataset_type: 'message',
+          where_clause:
+            `m.legal_entity_id = '{{ legal_entity_id }}' ` +
+            `AND m.decision_key = '${DECISION_KEY}' ` +
+            "AND m.sent_at > NOW() - INTERVAL '6 months'",
+          limit: 1,
+          position: 0,
+        },
+      ],
+      actions: [
+        {
+          action_type: 'sms',
+          tool_id: toolId,
+          decision_key: DECISION_KEY,
+          position: 0,
+          trigger_template: 'now',
+          idempotency_template: '{{ event_dataset.payment_account_external_id }}-{{ decision_key }}',
+          connected_app_id: connectedAppId,
+          connected_app_route: '/portal/kyc',
+          connected_app_metadata_template:
+            '{"payment_account_external_id":"{{ event_dataset.payment_account_external_id }}"}',
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '+15551234567' },
+            body: { type: 'custom', body: SMS_BODY_TEMPLATE },
+            sms_type: 'transactional',
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.kycWorkflowId = kycWorkflow.id!
+ctx.kycWorkflowSlug = kycWorkflow.slug!
+
+if (kycWorkflow.skip_mdm_resolution !== false) {
+  throw new Error('a generic-table workflow that mints a per-holder link must keep MDM resolution ON')
+}
+```
+
+## 029 — the payment-account contract pair
+
+Same two-contract shape as §019, over a different table. Contract A writes
+the holder as the subject; Contract B writes the account row and emits the
+same `(uri, account_holder_id)` identifier so both converge and the row is
+stamped.
+
+```typescript
+const { readFileSync: readFileSync2 } = await import('node:fs')
+const { join: join2 } = await import('node:path')
+const read2 = (f: string) =>
+  readFileSync2(join2(process.env.COOKBOOK_FIXTURES_DIR!, 'payments-compliance', f), 'utf8')
+
+const accountLeContract = await ctx.ensure(
+  'payment-account holder LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Atomic FI Holder LE Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Atomic FI Holder LE Contract',
+      description: 'Atomic FI payment-account → the account holder LegalEntity.',
+      resource_type: 'legal_entity',
+      type: 'identity',
+      generic_table_id: null,
+      template_config: { type: 'custom', body: read2('_payment_accounts_legal_entity.liquid') },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+ctx.accountLeContractId = accountLeContract.id!
+
+const accountGtContract = await ctx.ensure(
+  'payment-account GT contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Atomic FI Payment Account GT Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Atomic FI Payment Account GT Contract',
+      description: 'Atomic FI payment-account → payment_accounts row, stamped with its holder subject.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.accountsTableId,
+      template_config: { type: 'custom', body: read2('_payment_accounts_generic_table.liquid') },
+      mdm_input_config: { type: 'custom', body: read2('_payment_accounts_mdm.liquid') },
+    })
+    return data
+  },
+)
+ctx.accountGtContractId = accountGtContract.id!
+```
+
+## 030 — the payment-account DACs, split the same way
+
+The second contract pair gets the same treatment as the first, for the same
+reason — §020 has the full account of why. Both clients reuse the same
+manual-upload tool and the same data source; what differs between any two
+of these ingestion paths is only the contracts, which is the level the
+difference actually lives at.
+
+```typescript
+const accountIdentityDac = await ctx.ensure(
+  'payment-account identity DAC',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Atomic FI Payment Account Identity DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Atomic FI Payment Account Identity DAC',
+      description: 'Manual-upload DAC — writes the account holder as a legal entity, ahead of the account row.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [ctx.accountLeContractId],
+    })
+    return data
+  },
+)
+ctx.accountIdentityDacSlug = accountIdentityDac.slug!
+
+const accountDac = await ctx.ensure(
+  'payment-account data DAC',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Atomic FI Payment Account Data DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Atomic FI Payment Account Data DAC',
+      description: 'Manual-upload DAC — ingests payment-account rows, resolving the holder written by the identity DAC.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [ctx.accountGtContractId],
+    })
+    return data
+  },
+)
+ctx.accountDacSlug = accountDac.slug!
+```
+
+## 031 — ingest one active account and one suspended one
+
+Two rows differing in the field the filter reads. `active` passes;
+`suspended` must be rejected.
+
+Two stages again, holders before accounts, exactly as in §021.
+
+```typescript
+ctx.activeExternalId = 'PA-COOKBOOK-0101'
+ctx.suspendedExternalId = 'PA-COOKBOOK-0102'
+
+const activeRow = {
+  payment_account_external_id: ctx.activeExternalId,
+  payment_account_number: 'PA-NUM-COOKBOOK-0101',
+  account_holder_id: 'AH-COOKBOOK-KYC-0101',
+  account_holder_name: 'Ada Cookbook-Active-Lovelace',
+  status: 'active',
+  account_type: 'bank_account',
+  currency: 'USD',
+  routing_number: '121000358',
+  swift_bic: 'BOFAUS3N',
+  bank_name: 'Bank of America',
+  enabled_regimes: ['us_domestic'],
+  source_uri: 'api.atomic.fi/compliance',
+}
+const suspendedRow = {
+  payment_account_external_id: ctx.suspendedExternalId,
+  payment_account_number: 'PA-NUM-COOKBOOK-0102',
+  account_holder_id: 'AH-COOKBOOK-KYC-0102',
+  account_holder_name: 'Grace Cookbook-Suspended-Hopper',
+  status: 'suspended',
+  account_type: 'bank_account',
+  currency: 'USD',
+  routing_number: '121000358',
+  bank_name: 'Bank of America',
+  enabled_regimes: ['us_domestic'],
+  source_uri: 'api.atomic.fi/compliance',
+}
+
+// STAGE 1 — the account holders.
+const holderActive = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.accountIdentityDacSlug, { data: activeRow },
+)
+const holderSuspended = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.accountIdentityDacSlug, { data: suspendedRow },
+)
+await ctx.waitForBatches(ctx.accountIdentityDacSlug, [
+  holderActive.data.batch_id!,
+  holderSuspended.data.batch_id!,
+])
+
+// STAGE 2 — the accounts themselves.
+const activeIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.accountDacSlug, { data: activeRow },
+)
+const suspendedIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.accountDacSlug, { data: suspendedRow },
+)
+ctx.batchActive = activeIngest.data.batch_id!
+ctx.batchSuspended = suspendedIngest.data.batch_id!
+```
+
+## 032 — wait for both account batches to persist
+
+Same gate as §022, on the account data DAC's logs.
+
+```typescript
+await ctx.waitForBatches(ctx.accountDacSlug, [ctx.batchActive, ctx.batchSuspended])
+```
+
+## 033 — run the KYC workflow
+
+```typescript
+const kycRunResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.kycWorkflowSlug, {
+  sql_where_clause: `payment_account_external_id IN ('${ctx.activeExternalId}', '${ctx.suspendedExternalId}')`,
+  mode: 'live',
+  manual_override: false,
+})
+const kycFired = await ctx.waitForFiredRun(datalakeSlug, kycRunResp.data.workflow_run_id)
+ctx.kycRunLogId = kycFired.workflowRunLogId
+ctx.kycRunBatchId = kycFired.batchId!
+
+const kycDeadline = Date.now() + 240_000
+let kycStatus: string | null = null
+while (Date.now() < kycDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.kycWorkflowSlug, ctx.kycRunLogId,
+  )
+  kycStatus = log.status ?? null
+  if (kycStatus && kycStatus !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (kycStatus === 'failed') throw new Error('KYC workflow run reached :failed')
+if (!kycStatus || kycStatus === 'pending') {
+  throw new Error('KYC workflow run did not leave :pending within 240s')
+}
+```
+
+## 034 — verify the filter routed: active passes, suspended is filtered
+
+The active account passes the filter, so its WEL is `:executing` or
+`:completed`. The suspended one fails it, so its WEL is `:filtered`. Both
+passing — or both filtered — would mean the filter is not reading
+`event_dataset.status` at all.
+
+```typescript
+const kycWelDeadline = Date.now() + 120_000
+let kycWels: Array<Record<string, unknown>> = []
+let kycByStatus: Record<string, number> = {}
+while (Date.now() < kycWelDeadline) {
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.kycWorkflowSlug)
+  kycWels = (wfLogs.data ?? [])
+    .map((w) => w as Record<string, unknown>)
+    .filter((w) => w.batch_id === ctx.kycRunBatchId)
+  kycByStatus = {}
+  for (const w of kycWels) {
+    const st = (w.status as string | undefined) ?? 'unknown'
+    kycByStatus[st] = (kycByStatus[st] ?? 0) + 1
+  }
+  const settled = (kycByStatus.completed ?? 0) + (kycByStatus.executing ?? 0)
+  if (kycWels.length === 2 && settled === 1 && (kycByStatus.filtered ?? 0) === 1) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (kycWels.length !== 2) {
+  throw new Error(`expected 2 KYC WELs for the run, got ${kycWels.length}`)
+}
+const kycPassCount = (kycByStatus.executing ?? 0) + (kycByStatus.completed ?? 0)
+if (kycPassCount !== 1) {
+  throw new Error(`expected 1 pass-branch WEL, got ${kycPassCount} — ${JSON.stringify(kycByStatus)}`)
+}
+if ((kycByStatus.filtered ?? 0) !== 1) {
+  throw new Error(`expected 1 :filtered WEL (the suspended account) — ${JSON.stringify(kycByStatus)}`)
+}
+```
+
+## 035 — read the notification SMS back, and pull its portal token
+
+The passing action fired immediately and persisted a `message` row with
+the fully-rendered body. Extract the `/t/<token>` shortlink the platform
+baked in when it minted the connected-app page token.
+
+End-state assertion again, keyed the same way §025 is and for the same
+reason: on a repeat run the SMS was not re-sent, and the row from the first
+run is still the correct answer to "does this account have a notification
+with a portal link". The account's external id is what makes that row
+findable forever; the workflow's id is not.
+
+```typescript
+const { data: kycSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key LIKE '${ctx.activeExternalId}-%'`,
+})
+if (kycSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${kycSearch.status} error=${kycSearch.error_message ?? '(none)'}`)
+}
+
+const kycMsgDeadline = Date.now() + 45_000
+let kycMessages: Array<Record<string, unknown>> = []
+while (Date.now() < kycMsgDeadline && kycMessages.length === 0) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: kycSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  kycMessages = (data.data ?? []) as Array<Record<string, unknown>>
+  if (kycMessages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (kycMessages.length === 0) {
+  throw new Error(
+    `no KYC-notification SMS for account ${ctx.activeExternalId} within 45s — ` +
+      `the action never fired, or it fired under a different idempotency key`,
+  )
+}
+
+const withLink = kycMessages
+  .map((m) => String(m.body ?? ''))
+  .find((body) => body.includes('/t/') && body.includes('Alvera PR notification'))
+if (!withLink) {
+  throw new Error(`no rendered body with a /t/ link — bodies: ${JSON.stringify(kycMessages.map((m) => m.body))}`)
+}
+const tokenMatch = withLink.match(/\/t\/([A-Za-z0-9_-]+)/)
+if (!tokenMatch) {
+  throw new Error(`no /t/<token> in rendered body: ${withLink}`)
+}
+ctx.kycShortPath = tokenMatch[1]!
+```
+
+## 036 — resolve the deep link, and close the loop with tracking
+
+The `/t/<token>` shortlink resolves through `connectedApps.resolvePage`,
+and the `route_path` must match the action's `connected_app_route`.
+Posting `opened_at` and `form_submitted_at` through
+`updateMessageTracking` then mirrors exactly what the portal frontend does
+when the holder opens it — closing the SMS-to-reply loop end to end.
+
+```typescript
+const { data: resolved } = await api.connectedApps.resolvePage(
+  tenantSlug, datalakeSlug, ctx.connectedAppSlug,
+  { short_path: ctx.kycShortPath, user_agent: 'cookbook-doctest/kyc-notification' },
+)
+if (resolved.route_path !== '/portal/kyc') {
+  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
+}
+if (!(resolved.message?.body ?? '').includes('Alvera PR notification')) {
+  throw new Error('resolved page message body missing the notification copy')
+}
+
+const now = new Date().toISOString()
+const { data: tracked } = await api.connectedApps.updateMessageTracking(
+  tenantSlug, datalakeSlug, ctx.connectedAppSlug,
+  { short_path: ctx.kycShortPath, opened_at: now, form_submitted_at: now },
+)
+if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
+  throw new Error('message tracking did not persist opened_at + form_submitted_at')
+}
+```
+
+
+## 037 — read one row back through all three lakes
+
+This is what §007 was for. The same row, the same SQL, three modes — and
+the difference between them is the whole argument for turning tokenization
+on.
+
+`screened_entity_name` is declared `tokenize`, so the raw lake holds the
+name and neither copy does. `screening_score` and `match_count` are
+`privacy_requirement: 'none'`, so they are **identical in all three** —
+which is the point rather than an aside. The agent in §016 disambiguates on
+score, match count and type; it never needed to know who was screened. A
+masking policy that also destroyed the signal would have made the agent
+useless, and one that preserved the name would have made it a liability.
+
+Note that the mode is a parameter of the read, not a different slug: one
+lake is addressed, and `mode` selects which copy answers. The session's
+`data_access_mode` is a **ceiling**, so this step only works because §004
+built its client at `raw`; a tokenized-ceiling session asking for `raw` is
+refused rather than quietly downgraded.
+
+```typescript
+const maskedReadSql =
+  `SELECT compliance_screening_number, screened_entity_name, screening_score, match_count ` +
+  `FROM ${ctx.screeningsTableName} ` +
+  `WHERE compliance_screening_number = '${ctx.grayZoneNumber}'`
+
+const readAs = async (mode: 'raw' | 'tokenized' | 'redacted') => {
+  const { data } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: maskedReadSql,
+    mode,
+  })
+  const row = (data.data ?? [])[0]
+  if (!row) {
+    throw new Error(`the gray-zone screening was not readable through the ${mode} lake`)
+  }
+  const cell = (column: string): unknown => row[data.meta.columns.indexOf(column)]
+  return {
+    name: cell('screened_entity_name'),
+    score: Number(cell('screening_score')),
+    matchCount: Number(cell('match_count')),
+  }
+}
+
+const rawRead = await readAs('raw')
+const tokenizedRead = await readAs('tokenized')
+const redactedRead = await readAs('redacted')
+
+console.log('  raw       →', JSON.stringify(rawRead))
+console.log('  tokenized →', JSON.stringify(tokenizedRead))
+console.log('  redacted  →', JSON.stringify(redactedRead))
+
+// The identity does NOT survive the copy.
+if (rawRead.name !== ctx.grayZoneName) {
+  throw new Error(`the raw lake should hold the real name, got ${JSON.stringify(rawRead.name)}`)
+}
+if (tokenizedRead.name === ctx.grayZoneName) {
+  throw new Error('the tokenized lake handed back the real name — tokenization is not in force')
+}
+if (redactedRead.name === ctx.grayZoneName) {
+  throw new Error('the redacted lake handed back the real name — redaction is not in force')
+}
+
+// The signal DOES. A masking policy that broke this would break the agent.
+for (const [mode, read] of [['tokenized', tokenizedRead], ['redacted', redactedRead]] as const) {
+  if (read.score !== rawRead.score || read.matchCount !== rawRead.matchCount) {
+    throw new Error(
+      `the ${mode} lake changed a 'none' column: score ${read.score} vs ${rawRead.score}, ` +
+        `match_count ${read.matchCount} vs ${rawRead.matchCount}`,
+    )
+  }
+}
+```
+
+## 038 — how far the tokenized copy actually got
+
+Every masked read above trusted the copy. This asks it directly, and on a
+compliance surface the question is not academic: an agent reading a copy that
+has not caught up is an agent deciding on a partial view of who was screened.
+
+The addressing is the first trap. You name the **primary** lake plus a mode.
+A derived lake does have a slug, but that slug is not an address — the lookup
+resolves primaries only — so the walk asks with the tokenized lake's own slug
+and proves the refusal instead of assuming it.
+
+The second trap is the state names. `finished_copy` has **not** finished: the
+first pass is done, but the changes made during that pass are still
+unapplied. Read `caught_up`, which exists precisely so nobody has to
+pattern-match the word. `label` is the same state in words and is what the
+platform's own Tokenization screen renders — reuse it rather than inventing a
+second vocabulary for the same five states.
+
+`resync_empties` carries a rule worth asserting: `null` when a table is
+already caught up, because the platform will not spend a query per table
+answering a question about tables nobody will repair — and a non-empty array
+otherwise, naming the table itself first. `null` and `[]` are different
+answers here.
+
+```typescript
+const { data: pair } = await api.datalakes.provisionTokenization(tenantSlug, datalakeSlug)
+const tokenizedLake = (pair.derived_datalakes ?? []).find((d) => d.type === 'tokenized')
+if (!tokenizedLake) throw new Error('no tokenized copy on the lake — §007 should have provisioned it')
+
+const { data: tables } = await api.datalakes.derivedLakeTables(
+  tenantSlug, datalakeSlug, 'tokenized',
+)
+if (tables.data.length === 0) throw new Error('the tokenized copy reported no tables at all')
+console.log(`  ${tables.data.length} tables in the tokenized copy`)
+
+for (const t of tables.data) {
+  if (typeof t.caught_up !== 'boolean') {
+    throw new Error(`${t.table}: caught_up is not a boolean, got ${JSON.stringify(t.caught_up)}`)
+  }
+  if (!t.label || t.label.length === 0) {
+    throw new Error(`${t.table}: label is empty — it is what a screen renders`)
+  }
+  // The agreement that makes the boolean trustworthy: `caught_up` is true for
+  // exactly one of the five states. `finished_copy` reading true here would be
+  // the defect the boolean exists to prevent. This cannot be asserted against a
+  // mock — the schema cannot express a cross-field constraint, so Prism draws
+  // the two independently — which is exactly why it is asserted here.
+  if (t.caught_up !== (t.state === 'caught_up')) {
+    throw new Error(
+      `${t.table}: state '${t.state}' disagrees with caught_up=${t.caught_up} — ` +
+        `only 'caught_up' means arrived`,
+    )
+  }
+  if (t.caught_up && t.resync_empties !== null && t.resync_empties !== undefined) {
+    throw new Error(
+      `${t.table} is caught up, so resync_empties should not be computed — got ` +
+        JSON.stringify(t.resync_empties),
+    )
+  }
+  if (!t.caught_up) {
+    if (!Array.isArray(t.resync_empties) || t.resync_empties.length === 0) {
+      throw new Error(`${t.table} is behind, so resync_empties should be a non-empty array`)
+    }
+    if (t.resync_empties[0] !== t.table) {
+      throw new Error(`${t.table}: resync_empties should name the table itself first`)
+    }
+  }
+}
+ctx.copyTables = tables.data.map((t) => t.table)
+
+// The derived lake's own slug is not a second way to name the same thing.
+let refusedDerivedSlug = false
+try {
+  await api.datalakes.derivedLakeTables(tenantSlug, tokenizedLake.slug!, 'tokenized')
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 404) throw err
+  refusedDerivedSlug = true
+}
+if (!refusedDerivedSlug) {
+  throw new Error("the derived lake's own slug was accepted as an address — it should 404")
+}
+```
+
+## 039 — empty one table and wait for it back
+
+`resyncTable` empties a table in the copy and copies it again from the start.
+It is the repair for a table that is stuck or wrong, and two of its properties
+are the kind that bite in production, so both are asserted rather than
+described.
+
+**The blast radius is bigger than the table you name.** Postgres will not
+truncate a table with an inbound foreign key, regardless of whether the
+referencing tables hold any rows, so repairing a parent empties its whole
+dependent closure, transitively, in a single statement — and all of them are
+re-copied by the same run. `legal_entities` is the target here on purpose:
+§029's contract pair resolved every screened subject through it, and
+`legal_entity_identifications` points at it, so `emptied` genuinely names more
+than one table. Any surface offering this button should read `resync_empties`
+and say the count before it is pressed.
+
+**`202` means started.** There is no completion callback, so the walk polls
+`derivedLakeTables` until every emptied table reads `caught_up` again. That
+poll is also what makes this a proof rather than a dispatch.
+
+The gate goes first. `table` is checked against what the copy carries or the
+original can send, and anything else is a `422` with nothing emptied — the
+one thing standing between a typo and an emptied table. Proving it *after*
+running the real repair would be checking the lock from inside the house.
+
+```typescript
+const TARGET = 'legal_entities'
+if (!(ctx.copyTables as string[]).includes(TARGET)) {
+  throw new Error(`${TARGET} is not in the copy; it carries: ${(ctx.copyTables as string[]).join(', ')}`)
+}
+
+let refusedBadTable = false
+try {
+  await api.datalakes.resyncTable(tenantSlug, datalakeSlug, 'tokenized', {
+    table: 'no_such_table_here',
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  refusedBadTable = true
+}
+if (!refusedBadTable) throw new Error('an unknown table name was accepted — the gate is not closed')
+
+const { data: repair } = await api.datalakes.resyncTable(
+  tenantSlug, datalakeSlug, 'tokenized', { table: TARGET },
+)
+if (repair.table !== TARGET) throw new Error(`repaired ${repair.table}, asked for ${TARGET}`)
+if (repair.mode !== 'tokenized') throw new Error(`repaired the ${repair.mode} copy, asked for tokenized`)
+if (repair.status !== 'copying') throw new Error(`expected status 'copying', got ${repair.status}`)
+if (!repair.emptied.includes(TARGET)) {
+  throw new Error(`emptied ${JSON.stringify(repair.emptied)} — the named table is not among them`)
+}
+console.log(`  emptied ${repair.emptied.length} table(s): ${repair.emptied.join(', ')}`)
+
+// Identifications point at legal entities, so the closure cannot be just one.
+if (repair.emptied.length < 2) {
+  throw new Error(
+    `${TARGET} has dependents, so a repair should empty more than itself — got ` +
+      JSON.stringify(repair.emptied),
+  )
+}
+
+const RESYNC_TIMEOUT_MS = 5 * 60_000
+const resyncDeadline = Date.now() + RESYNC_TIMEOUT_MS
+let backOnline = false
+while (Date.now() < resyncDeadline && !backOnline) {
+  const { data: after } = await api.datalakes.derivedLakeTables(
+    tenantSlug, datalakeSlug, 'tokenized',
+  )
+  backOnline = (repair.emptied as string[]).every(
+    (name) => after.data.find((t) => t.table === name)?.caught_up === true,
+  )
+  if (!backOnline) await new Promise((r) => setTimeout(r, 5_000))
+}
+if (!backOnline) {
+  throw new Error(`the repaired tables did not come back within ${RESYNC_TIMEOUT_MS / 1000}s`)
+}
+console.log('  every emptied table is caught up again')
+```
+
+# Outcome
+
+One tenant carries the whole payments-compliance surface: a raw datalake
+with its tokenized and redacted copies, two generic tables, two contract
+pairs split across four Data Activation Clients, and two agentic workflows
+that between them screen, decide, notify and track — plus the copy's own
+arrival state, read back per table and repaired.
+
+Two things are worth carrying out of this walk. **The pair must not run
+concurrently** (§020) — one writer per subject, or the unique index that
+guards against duplicate entities refuses your row on the only run that
+matters, the first. And **assert end states, not transitions** (§024) — an
+idempotency key that has already fired will not fire again, which is the
+product working, not the walk failing.
+
+Running this walk again reuses all of it.
+
+# See also
+
+- `datalakes.md` — the create body, and what the derived pair is for
+- `workflows.md` — scheduling versus firing, and the accessor tables
+- `interoperability_contracts.md` — the contract pair, and the
+  reserved `legal_entity_id` stamp you must not declare