@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/organic-marketing.md

@@ -0,0 +1,2801 @@
+---
+title: "Organic marketing: score, greet, campaign — on one raw lake"
+summary: The whole organic-marketing surface in one walk. Stand up a tenant and a raw datalake, then run the scenarios end to end — an LLM agent banding inbound leads into a four-way SMS fan-out, a pure-Liquid birthday trigger that schedules a greeting a year out and closes the reply loop through a connected app, and an A/B campaign that gates on suppression, splits inside the workflow and dispatches on SMS and email in one run. Ends with delivery reconciliation and a natural-language read of the lake.
+use_case: organic-marketing
+slug: organic-marketing
+vitest_source:
+  - integration-tests/tests/organic-marketing/agent-driven-workflow.test.ts
+  - integration-tests/tests/organic-marketing/generic-tables.test.ts
+  - integration-tests/tests/organic-marketing/manual-upload-tool.test.ts
+  - integration-tests/tests/workspace/bootstrap.test.ts
+status: draft
+---
+
+# Problem
+
+A marketing team's work is three jobs that share one audience. Leads
+arrive from forms and most of them are noise, so something has to read each
+one and decide whether a human should. Contacts have birthdays, and a
+greeting has to be scheduled once and fire a year later without anyone
+remembering. And campaigns go out to a roster of businesses, split A/B, on
+whichever channel the recipient can actually be reached on.
+
+All three are the same shape — rows land, a filter decides which ones
+matter, and something is sent about the ones that do. This walk builds all
+three on one tenant, because a marketing team does not run three platforms.
+
+**This surface stays raw.** No tokenized or redacted copy is provisioned,
+and that is a decision rather than an omission: everything read back here
+is a question about this walk's own rows, and the lead's own message — not
+the lead's name — is what the classifier reads. If you want a model held
+away from identities, that is what `payments-compliance` §007 shows, and it
+is one call away from here.
+
+# Composition
+
+| Resource                            | Why it exists here                          |
+|-------------------------------------|---------------------------------------------|
+| Tenant + raw datalake               | The marketing team's own world               |
+| SMS tool, email tool, LLM tool      | Shared by every scenario below               |
+| Score Lead AI agent                 | Bands inbound leads                          |
+| Three generic tables                | Leads, the roster, and the audience          |
+| Three workflows                     | Band fan-out, birthday greeting, campaign    |
+| Connected app                       | The reply loop, twice                        |
+| Action status updater               | Delivery outcomes, reconciled on a cron      |
+
+# 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.marketerEmail = 'cookbook-organic-marketing@dev.local'
+ctx.marketerPassword = 'CookbookPass1!'
+
+try {
+  const signUpResp = await ctx.rootApi.admin.signUp({
+    email: ctx.marketerEmail,
+    password: ctx.marketerPassword,
+    first_name: 'Cookbook',
+    last_name: 'Marketing',
+  })
+  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 a dozen 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
+
+The marketer signs in without a tenant scope — they may not belong to one
+yet — and the walk finds or creates the marketing tenant by its stable
+name. The server derives the slug; capture it, because every later call is
+addressed by it.
+
+```typescript
+ctx.marketerTenantlessSession = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.marketerEmail,
+  password: ctx.marketerPassword,
+})
+ctx.marketerTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.marketerTenantlessSession.sessionToken,
+  apiKey: '',
+})
+
+const TENANT_NAME = 'Cookbook Organic Marketing'
+
+const tenant = await ctx.ensure(
+  `tenant ${TENANT_NAME}`,
+  async () => {
+    const { data } = await ctx.marketerTenantlessApi.tenants.list()
+    return (data.data ?? []).find((t: { name?: string }) => t.name === TENANT_NAME)
+  },
+  async () => {
+    const { data } = await ctx.marketerTenantlessApi.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
+the marketer 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 the ceiling, and on this surface it is the
+only tier there is — no derived lake is provisioned, so raw is what every
+read answers from.
+
+**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 Organic Marketing Key',
+  data_access_mode: 'raw',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
+const marketerTenantSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.marketerEmail,
+  password: ctx.marketerPassword,
+  tenantSlug,
+  apiKey: ctx.tenantApiKey,
+})
+api = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: marketerTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
+})
+```
+
+## 005 — the datalake
+
+One datalake, created `raw`, and on this surface that is the whole story —
+there is no derived pair to provision and nothing to wait for beyond the
+migration in §006.
+
+The lookup still filters on `type === 'raw'`. That costs nothing here and
+keeps the step correct if anyone ever turns tokenization on: from that
+moment `datalakes.list` returns three rows, two of which are 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_foundation`, 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_foundation' }
+const DB_SCHEMA = 'cookbook_organic_marketing'
+const LAKE_NAME = 'Cookbook Organic Marketing 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: 'Organic marketing 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/organic-marketing' },
+    })
+    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 readyDeadline = Date.now() + READY_TIMEOUT_MS
+let datalakeStatus: string | undefined
+while (Date.now() < readyDeadline) {
+  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 — 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 afterwards. This
+polls a client'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 3 execution logs, got 0"* — which
+reads like a broken workflow rather than a row that never landed.
+
+**`deployGenericTable`.** Creating a generic table does not deploy it; it
+rests at `status: 'new'` until a migration runs. The wait that means
+anything asks for the table the same way the next step is about to, and
+retries until it stops erroring — polling the table's own
+`status: 'deployed'` goes true earlier and proves less.
+
+```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)})`,
+  )
+}
+```
+
+## 008 — the SMS tool
+
+One SMS tool dispatches every outbound message in this walk — four lead
+bands, a birthday greeting and a campaign variant. **The per-message body
+lives on the workflow action, never on the tool**, which is what lets one
+tool serve all of them. `intent: 'sms'` tags it for workflow-action use.
+
+Local dev points at LocalStack's SNS on `:4566`, so nothing leaves the
+machine.
+
+```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 Marketing SMS Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Marketing SMS Tool',
+      description: 'SNS-backed SMS dispatcher for every marketing scenario, 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!
+ctx.smsToolId = smsTool.id!
+```
+
+## 009 — the LLM tool
+
+The Score Lead agent calls a chat-completion endpoint to classify each row.
+`intent: 'llm_enrichment'` distinguishes it from the SMS tool above.
+
+It is a **provider adapter**, and the two halves are the thing to read.
+`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 Marketing LLM Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Marketing LLM Tool',
+      description: 'Ollama-backed chat-completion adapter for Score Lead classification.',
+      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!
+```
+
+## 010 — the Lead Submissions table
+
+Lead-capture rows do not fit any canonical entity, so they are a generic
+table you declare. The columns mirror what a form export or a spreadsheet
+tab actually produces. `message` and `lead_source` are what the agent
+reads; `band` is what a production system writes back.
+
+`name` and `email` are declared `tokenize`. **That declaration is the
+masking policy, and it is correct whether or not a tokenized lake exists
+today** — this walk provisions none, so nothing masks here, and the
+declaration goes live the moment someone calls `provisionTokenization`.
+Declaring it now is how the policy survives that call rather than being
+remembered afterwards.
+
+```typescript
+const leads = await ctx.ensure(
+  'lead-submissions table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Cookbook Lead Submissions')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Cookbook Lead Submissions',
+      description: 'Inbound lead-capture form rows the Score Lead agent classifies.',
+      columns: [
+        { name: 'submission_id', title: 'Submission ID', type: 'string', description: 'Vendor-supplied unique submission id', is_unique: true, privacy_requirement: 'none' },
+        { name: 'name', title: 'Name', type: 'string', description: 'Submitter full name', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'email', title: 'Email', type: 'string', description: 'Submitter email', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'message', title: 'Message', type: 'string', description: 'Free-text lead message — the agent classifies this', is_unique: false, privacy_requirement: 'none' },
+        { name: 'lead_source', title: 'Lead Source', type: 'string', description: 'utm_source / sheet tab id', is_unique: false, privacy_requirement: 'none' },
+        { name: 'band', title: 'Band', type: 'string', description: 'Lead-scoring band assigned by the Score Lead agent', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
+genericTableId = leads.id!
+ctx.leadsTableName = leads.name!
+
+// Called unconditionally rather than only on the create branch, so a run
+// that crashed between recording the table and deploying it still converges.
+await ctx.deployGenericTable(ctx.leadsTableName)
+```
+
+## 011 — the Score Lead agent
+
+The agent binds three things: the model name sent on every inference call,
+an input schema the workflow's context mapping must satisfy, and a response
+schema the output must match.
+
+The response schema's `enum: ['hot','warm','cold','spam']` is the guard that
+matters. It stops the model emitting a band the workflow has no action for
+— without it a creative answer becomes a decision key nothing matches, and
+the row silently fans out to nothing. `temperature: 0.0` removes sampling
+noise so identical inputs classify identically, which is what makes the
+assertion in §016 stable.
+
+`data_access: 'raw'` because this lake has one tier. On a surface that
+provisions the derived pair you would set `'tokenized'` here and the agent
+would never see the name at all.
+
+```typescript
+const SCORE_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    message: { type: 'string' },
+    lead_source: { type: 'string' },
+  },
+  required: ['name', 'message'],
+}
+
+const SCORE_RESPONSE_SCHEMA = {
+  type: 'object',
+  properties: { band: { type: 'string', enum: ['hot', 'warm', 'cold', 'spam'] } },
+  required: ['band'],
+}
+
+const AGENT_PROMPT_BODY = `You are a B2B lead-scoring assistant. Classify the following lead's intent into EXACTLY ONE of these bands:
+
+- "hot"  — clear buying intent, decision maker, ready to engage
+- "warm" — interested but exploratory, requires nurture
+- "cold" — generic/lukewarm interest, low conversion signal
+- "spam" — promotional, irrelevant, or low-quality submission
+
+Lead name: {{ name }}
+Lead message: {{ message }}
+Lead source: {{ lead_source }}
+
+Respond with a JSON object: {"band": "<one of hot|warm|cold|spam>"}`
+
+const agent = await ctx.ensure(
+  'Score Lead agent',
+  async () => {
+    const { data } = await api.aiAgents.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Score Lead Agent')
+  },
+  async () => {
+    const { data } = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Score Lead Agent',
+      tool_id: ctx.llmToolId,
+      model: 'qwen3-vl:8b-instruct',
+      data_access: 'raw',
+      temperature: 0.0,
+      max_tokens: 1024,
+      enabled: true,
+      input_schema: SCORE_INPUT_SCHEMA,
+      llm_response_schema: SCORE_RESPONSE_SCHEMA,
+      prompt_config: { type: 'custom', body: AGENT_PROMPT_BODY },
+    })
+    return data
+  },
+)
+aiAgentId = agent.id!
+ctx.agentSlug = agent.slug!
+```
+
+## 012 — the Score Lead workflow
+
+Standard shape — filter, decision, actions — with two things worth reading
+closely.
+
+The agent is **nested in the create body** (`workflow_ai_agents`, a
+`cast_assoc` rather than a separate attach call), which binds it into the
+workflow's enrichment phase along with a Liquid `context_mapping_config`
+that projects each row into the agent's input schema. A workflow join omits
+`output_schema`; the server pins it from the agent's own `input_schema`.
+
+The `decision_config` body interpolates the agent's `band` into a
+single-element decision array, and the four actions are keyed
+`decision_key: hot|warm|cold|spam`. Whichever band comes back picks one
+action and leaves the other three `:skipped`.
+
+**Bracket access is required**, not stylistic: the agent's slug contains
+hyphens, and Liquid's dot parser would read `additional_context.score-lead`
+as a subtraction.
+
+```typescript
+const BANDS = ['hot', 'warm', 'cold', 'spam'] as const
+
+const CONTEXT_MAPPING_BODY = JSON.stringify({
+  name: '{{ event_dataset.name }}',
+  message: '{{ event_dataset.message }}',
+  lead_source: '{{ event_dataset.lead_source }}',
+})
+
+const DECISION_CONFIG_BODY = `["{{ additional_context["${ctx.agentSlug}"].band }}"]`
+
+const scoreWorkflow = await ctx.ensure(
+  'Score Lead workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook Score Lead Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Score Lead Workflow',
+      description: 'Classifies lead submissions into hot/warm/cold/spam via an LLM agent; one SMS action per band.',
+      dataset_type: 'generic_table',
+      generic_table_id: genericTableId,
+      skip_mdm_resolution: true,
+      status: 'live',
+      tags: ['leads', 'llm'],
+      filter_config: { type: 'custom', body: 'true' },
+      decision_config: {
+        type: 'custom',
+        body: DECISION_CONFIG_BODY,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      actions: BANDS.map((band) => ({
+        decision_key: band,
+        action_type: 'sms',
+        tool_id: ctx.smsToolId,
+        position: 0,
+        trigger_template: 'now',
+        idempotency_template: `{{ event_dataset.submission_id }}-${band}`,
+        tool_call: {
+          tool_call_type: 'sms_request',
+          to: { type: 'custom', body: '+15551234567' },
+          body: { type: 'custom', body: `Lead band [${band}]: {{ event_dataset.message }}` },
+          sms_type: 'transactional',
+        },
+      })),
+      workflow_ai_agents: [
+        {
+          ai_agent_id: aiAgentId,
+          position: 0,
+          context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
+        },
+      ],
+    })
+    return data
+  },
+)
+workflowId = scoreWorkflow.id!
+ctx.scoreWorkflowSlug = scoreWorkflow.slug!
+```
+
+## 013 — the table's own Data Activation Client, which you did not create
+
+Creating a generic table provisions two things for you: an identity
+interoperability contract, and a **default Data Activation Client** bound to
+it, named `<datalake> <table> DataActivationClient` with
+`tool_call: manual_upload`. For plain row ingestion into a table you
+declared, there is nothing to build — no data source, no tool, no contract,
+no client.
+
+**Scope the lookup server-side.** The listing pages at twenty and is not
+newest-first, so a `.find()` over page one starts missing the client you
+want as soon as the lake has a few tables — and the failure looks like the
+client was never provisioned.
+
+```typescript
+const dacDeadline = Date.now() + 120_000
+let defaultDac: { slug?: string | null } | undefined
+while (Date.now() < dacDeadline && !defaultDac) {
+  const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+    filters: [{ field: 'name', op: 'ilike', value: ctx.leadsTableName }],
+  })
+  defaultDac = (data.data ?? [])[0]
+  if (!defaultDac) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (!defaultDac?.slug) {
+  throw new Error(`no default DAC found for table ${ctx.leadsTableName} within 120s`)
+}
+ctx.leadsDacSlug = defaultDac.slug
+```
+
+## 014 — ingest three leads, one obviously each way
+
+Three rows through the default client. Each carries a deliberately
+unambiguous `message` — approved budget and a deadline, an idle browse, and
+obvious promotional spam — so the classification is not a coin toss and the
+assertion in §016 means something. `band` is left unset on ingest; assigning
+it is the agent's job.
+
+The submission ids are **stable across runs**, and `submission_id` is the
+table's unique column, so a second run upserts these same three rows rather
+than adding three more.
+
+```typescript
+ctx.hotLead = 'LEAD-COOKBOOK-0101'
+ctx.coldLead = 'LEAD-COOKBOOK-0102'
+ctx.spamLead = 'LEAD-COOKBOOK-0103'
+
+const leadRows = [
+  {
+    submission_id: ctx.hotLead,
+    name: 'Dana Decisive',
+    email: 'dana@example.com',
+    message:
+      'We have budget approved and need to roll out to 500 seats this quarter — can we start onboarding next week?',
+    lead_source: 'cookbook_score_leads',
+  },
+  {
+    submission_id: ctx.coldLead,
+    name: 'Sam Browsing',
+    email: 'sam@example.com',
+    message: 'Just browsing — found your site via a blog post. No particular need right now.',
+    lead_source: 'cookbook_score_leads',
+  },
+  {
+    submission_id: ctx.spamLead,
+    name: 'Promo Bot',
+    email: 'promo@example.com',
+    message: 'BUY CHEAP FOLLOWERS NOW!!! 90% off SEO backlinks, crypto giveaways, click here click here!!!',
+    lead_source: 'cookbook_score_leads',
+  },
+]
+
+const ingests: string[] = []
+for (const row of leadRows) {
+  const resp = await api.dataActivationClients.ingest(
+    tenantSlug, datalakeSlug, ctx.leadsDacSlug, { data: row },
+  )
+  ingests.push(resp.data.batch_id!)
+}
+ctx.leadBatchIds = ingests
+```
+
+## 015 — wait for all three to persist
+
+```typescript
+await ctx.waitForBatches(ctx.leadsDacSlug, ctx.leadBatchIds)
+```
+
+## 016 — run the workflow across the three leads
+
+`workflows.run` triggers the whole pipeline per row: filter, then agent
+enrichment — a live inference call per row — then the decision, then the
+action fan-out. The where clause scopes the run to exactly the three
+submissions §014 ingested, so rows left by any other walk are untouched.
+
+The window is generous because three real model calls happen inside it.
+
+```typescript
+const submissionList = [ctx.hotLead, ctx.coldLead, ctx.spamLead].map((s) => `'${s}'`).join(', ')
+
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.scoreWorkflowSlug, {
+  sql_where_clause: `submission_id IN (${submissionList})`,
+  mode: 'live',
+  manual_override: true,
+})
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.scoreRunLogId = fired.workflowRunLogId
+ctx.scoreRunBatchId = fired.batchId!
+
+const runDeadline = Date.now() + 240_000
+let runStatus: string | null = null
+while (Date.now() < runDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.scoreWorkflowSlug, ctx.scoreRunLogId,
+  )
+  runStatus = log.status ?? null
+  if (runStatus && runStatus !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (runStatus === 'failed') throw new Error('Score Lead run reached :failed')
+if (!runStatus || runStatus === 'pending') {
+  throw new Error('Score Lead run did not leave :pending within 240s')
+}
+```
+
+## 017 — verify the agent's band actually steered the fan-out
+
+Each lead produced a Workflow Execution Log carrying **four** action
+execution logs, one per band.
+
+On the first run for a given submission, exactly **one** is matched
+(`:pending` or `:completed` — the band the agent chose) and **three** are
+`:skipped`. That one-of-four is the proof the agent's output drove the
+decision rather than every action firing.
+
+**On a later run all four are `:skipped`, and that is correct.** The
+idempotency key is `{{ submission_id }}-<band>`, the submission ids are
+stable, so the key that already fired refuses to fire again — the platform
+will not send the same SMS about the same lead twice. Both shapes are
+accepted here, and anything else is a real failure: two matched actions
+means the decision matched more than one band, and zero matched with zero
+skipped means the fan-out never happened.
+
+```typescript
+const { data: wfLogs } = await api.workflows.workflowLogs.list(
+  tenantSlug, datalakeSlug, ctx.scoreWorkflowSlug,
+)
+const ourWels = (wfLogs.data ?? []).filter(
+  (w) => (w as { batch_id?: string }).batch_id === ctx.scoreRunBatchId,
+)
+if (ourWels.length !== 3) {
+  throw new Error(`expected 3 WELs for the run, got ${ourWels.length}`)
+}
+
+for (const wel of ourWels) {
+  const welId = (wel as { id?: string }).id
+  const aels = (wel as { action_execution_logs?: Array<{ status?: string }> }).action_execution_logs ?? []
+  if (aels.length !== 4) {
+    throw new Error(`WEL ${welId}: expected 4 AELs (one per band), got ${aels.length}`)
+  }
+  const byStatus: Record<string, number> = {}
+  for (const ael of aels) {
+    const st = ael.status ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const matched = (byStatus.pending ?? 0) + (byStatus.completed ?? 0)
+  const skipped = byStatus.skipped ?? 0
+
+  if (matched === 1 && skipped === 3) continue          // first run for this lead
+  if (matched === 0 && skipped === 4) continue          // already fired, correctly refusing
+  throw new Error(
+    `WEL ${welId}: expected 1 matched + 3 skipped, or 4 skipped on a repeat run — got ${JSON.stringify(byStatus)}`,
+  )
+}
+```
+
+## 018 — confirm a band-prefixed SMS actually rendered
+
+§017 proves the fan-out chose one action. This proves something was
+actually *sent*, and it is the assertion that survives every rerun.
+
+Search on the **idempotency key**, never on `workflow_id`. The key is
+`<submission id>-<band>` and the submission id is stable, so it names the
+same SMS forever. A workflow id is stable only as long as the workflow
+resource is: recreate it against a lake that still holds its rows and the
+id changes while the key does not, so the action correctly refuses to fire
+and a search for the new id finds nothing at all.
+
+The hot lead is the one asserted, because it is the only one whose band is
+genuinely unambiguous — approved budget, a seat count and a deadline is
+`hot` to any classifier worth running.
+
+```typescript
+const { data: leadSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key LIKE '${ctx.hotLead}-%'`,
+})
+if (leadSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${leadSearch.status} error=${leadSearch.error_message ?? '(none)'}`)
+}
+
+const leadMsgDeadline = Date.now() + 45_000
+let leadMessages: Array<Record<string, unknown>> = []
+while (Date.now() < leadMsgDeadline && leadMessages.length === 0) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: leadSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  leadMessages = (data.data ?? []) as Array<Record<string, unknown>>
+  if (leadMessages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (leadMessages.length === 0) {
+  throw new Error(
+    `no band SMS for lead ${ctx.hotLead} within 45s — ` +
+      `the action never fired, or it fired under a different idempotency key`,
+  )
+}
+
+const bandBody = leadMessages.map((m) => String(m.body ?? '')).find((b) => b.includes('Lead band ['))
+if (!bandBody) {
+  throw new Error(`no band-prefixed SMS body — bodies: ${JSON.stringify(leadMessages.map((m) => m.body))}`)
+}
+if (!bandBody.includes('[hot]')) {
+  throw new Error(`expected the classifier to band this lead [hot] — got: ${bandBody}`)
+}
+```
+
+## 019 — the Birthday Greeting connected app
+
+The greeting carries a deep link so the recipient can do something with it
+— upload a photo, RSVP, whatever the operator wires up. A connected app is
+a thin registration of that page's URL and mode; the page itself is hosted
+outside the platform (`mode: 'self_hosted'`). Capture the server-derived
+`slug` — §030 resolves a token against it.
+
+```typescript
+const birthdayApp = await ctx.ensure(
+  'Birthday Greeting connected app',
+  async () => {
+    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Birthday Greeting Form')
+  },
+  async () => {
+    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Birthday Greeting Form',
+      description: 'Birthday-greeting form linked from the outbound SMS.',
+      mode: 'self_hosted',
+      urls: [{ url: 'https://birthday.example.local', is_primary: true, label: 'production' }],
+    })
+    return data
+  },
+)
+connectedAppId = birthdayApp.id!
+ctx.birthdayAppSlug = birthdayApp.slug!
+```
+
+## 020 — the Happy Birthday workflow, and the year-roll trigger
+
+No agent here, and that is the point of putting it beside §012: the same
+workflow shape does this job with nothing but Liquid.
+
+**The trigger template is the whole scenario.** It compares today's `MM-DD`
+against the contact's date of birth `MM-DD` and renders either this year's
+birthday or next year's. String comparison works because both sides are
+zero-padded `MM-DD` — the one detail that makes a one-line year-roll
+correct instead of nearly correct.
+
+Two things that look optional and are not. The filter reads
+`mdm_output.legal_entity.date_of_birth`, which requires
+`skip_mdm_resolution: false` — the resolution is what puts the subject in
+scope for the filter at all. And the SMS body must reference
+`{{ connected_app_form_url }}`: the platform mints the page token at action
+time and injects that variable, so a body that never mentions it gets a
+token minted and thrown away, and §031 has no link to resolve.
+
+```typescript
+const DECISION_KEY = 'send_happy_birthday_sms'
+const TRIGGER_TEMPLATE =
+  '{% assign year = "" | now | date: "%Y" %}' +
+  '{% assign today_mmdd = "" | now | date: "%m-%d" %}' +
+  '{% assign dob_mmdd = mdm_output.legal_entity.date_of_birth | date: "%m-%d" %}' +
+  '{% if dob_mmdd >= today_mmdd %}{{ year }}-{{ dob_mmdd }} 00:00:00' +
+  '{% else %}{{ year | plus: 1 }}-{{ dob_mmdd }} 00:00:00{% endif %}'
+
+const birthdayWorkflow = await ctx.ensure(
+  'Happy Birthday workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook Happy Birthday Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Happy Birthday Workflow',
+      description: "Sends a birthday SMS on each contact's next birthday — pure-Liquid trigger does the year-roll math.",
+      dataset_type: 'legal_entity',
+      status: 'live',
+      tags: ['lifecycle', 'birthday'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: '{% if mdm_output.legal_entity.date_of_birth %}true{% endif %}' },
+      decision_config: {
+        type: 'custom',
+        body: `["${DECISION_KEY}"]`,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      actions: [
+        {
+          action_type: 'sms',
+          tool_id: ctx.smsToolId,
+          decision_key: DECISION_KEY,
+          position: 0,
+          trigger_template: TRIGGER_TEMPLATE,
+          idempotency_template: '{{ legal_entity.id }}-birthday-greeting',
+          connected_app_id: connectedAppId,
+          connected_app_route: '/forms/birthday-greeting',
+          connected_app_metadata_template: '{"legal_entity_id":"{{ legal_entity.id }}"}',
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '{{ mdm_output.legal_entity.phone_numbers | first | map: "phone_number" }}' },
+            body: {
+              type: 'custom',
+              body: 'Happy birthday {{ mdm_output.legal_entity.first_name }}! \u{1F382} Share a photo: {{ connected_app_form_url }}',
+            },
+            sms_type: 'transactional',
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.birthdayWorkflowSlug = birthdayWorkflow.slug!
+```
+
+## 021 — the data source, the upload tool, and the contract
+
+Three small pieces, one step, because none of them is interesting alone.
+
+The **data source** registers where rows come from. Its `uri` matters more
+than it looks: the Data Activation Client injects it into every row as
+`source_uri`, and the contract template writes it as the identification's
+`uri` — so it is half of the key the legal-entity dedupe uses. Change it
+and yesterday's contacts stop matching today's.
+
+The **manual-upload tool** is the minimal tool for inline JSON; it needs no
+endpoint or credential because the rows arrive in the ingest call rather
+than being fetched.
+
+The **contract** shapes a row into a legal-entity upsert. Its
+`mdm_input_config` is `{ type: 'null' }` — the row *is* the subject, so
+there is nothing to resolve. The template comes from the vendored fixture
+rather than several hundred inlined lines of Liquid.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const leTemplate = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'organic-marketing', '_lead_submissions_foundation_legal_entity.liquid'),
+  'utf8',
+)
+
+ctx.leadSourceUri = 'https://app.alvera.ai/cookbook-lead-form'
+
+const leadSource = await ctx.ensure(
+  'lead-form data source',
+  async () => {
+    const { data } = await api.dataSources.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((d: { name?: string }) => d.name === 'Cookbook Lead Form Source')
+  },
+  async () => {
+    const { data } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Lead Form Source',
+      uri: ctx.leadSourceUri,
+      description: 'Inbound lead-capture form — origin of the contact rows the birthday workflow runs on.',
+      status: 'active',
+      is_default: false,
+    })
+    return data
+  },
+)
+dataSourceId = leadSource.id!
+
+const uploadTool = 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 the client that ingests contact rows.',
+      intent: 'data_exchange',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: dataSourceId,
+      body: { tool_body_type: 'manual_upload' },
+    })
+    return data
+  },
+)
+ctx.manualUploadToolId = uploadTool.id!
+
+const leContract = await ctx.ensure(
+  'lead-form legal-entity contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Lead Form to LegalEntity')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Lead Form to LegalEntity',
+      description: 'Lead-form row → LegalEntity (custom Liquid, no MDM input).',
+      resource_type: 'legal_entity',
+      template_config: { type: 'custom', body: leTemplate },
+      mdm_input_config: { type: 'null' },
+      generic_table_id: null,
+    })
+    return data
+  },
+)
+interopContractId = leContract.id!
+```
+
+## 022 — the lead-form activation client
+
+One contract on one client, so nothing to sequence here — the trap that
+forces two clients apart only appears when a pair resolves the same
+subject at once.
+
+```typescript
+const leadDac = await ctx.ensure(
+  'lead-form activation client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Lead Form DAC' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Lead Form DAC',
+      description: 'Manual-upload client — ingests lead-form rows as legal entities.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [interopContractId],
+    })
+    return data
+  },
+)
+dacId = leadDac.id!
+ctx.leadFormDacSlug = leadDac.slug!
+```
+
+## 023 — ingest two contacts, one with a birthday and one without
+
+Two rows. One carries a `date_of_birth` so the filter passes it; the other
+omits it entirely so the filter must reject it. A run where both passed, or
+both were filtered, would mean the filter is not evaluating anything — and
+that is exactly the failure a walk that never runs its workflow cannot see.
+
+**The date of birth is tomorrow's month-day, stamped thirty years back.**
+Both halves are deliberate. The past year satisfies the changeset's
+not-in-the-future guard on a date of birth. Tomorrow's month-day makes the
+greeting schedule for the *future*, which is what makes §029's
+fast-forward observable at all — a birthday today renders a time already
+passed and would dispatch on its own, proving nothing about the override.
+
+The emails are stable, and the email is what the identification dedupes on,
+so a second run updates these same two contacts rather than adding two more.
+
+```typescript
+const today = new Date()
+const tomorrow = new Date(today.getTime() + 86_400_000)
+const tomorrowMM = String(tomorrow.getUTCMonth() + 1).padStart(2, '0')
+const tomorrowDD = String(tomorrow.getUTCDate()).padStart(2, '0')
+const dobYear = today.getUTCFullYear() - 30
+
+ctx.birthdayEmail = 'maria-birthday@cookbook.example.com'
+ctx.birthdayPhone = '+15550100101'
+
+const birthdayRow = {
+  submission_id: 'BD-COOKBOOK-0101',
+  name: 'Maria Birthday',
+  email: ctx.birthdayEmail,
+  phone: ctx.birthdayPhone,
+  company: '',
+  message: 'My birthday is tomorrow',
+  lead_source: 'cookbook_birthday',
+  source_uri: ctx.leadSourceUri,
+  date_of_birth: `${dobYear}-${tomorrowMM}-${tomorrowDD}`,
+}
+const noDobRow = {
+  submission_id: 'BD-COOKBOOK-0102',
+  name: 'Priya NoDob',
+  email: 'priya-nodob@cookbook.example.com',
+  phone: '+15550100102',
+  company: '',
+  message: 'I have no date of birth on file',
+  lead_source: 'cookbook_birthday',
+  source_uri: ctx.leadSourceUri,
+  // date_of_birth deliberately absent — the filter must reject this row
+}
+
+const bdIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.leadFormDacSlug, { data: birthdayRow },
+)
+const noDobIngest = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.leadFormDacSlug, { data: noDobRow },
+)
+ctx.batchBirthday = bdIngest.data.batch_id!
+ctx.batchNoDob = noDobIngest.data.batch_id!
+```
+
+## 024 — wait for both contacts to persist
+
+```typescript
+await ctx.waitForBatches(ctx.leadFormDacSlug, [ctx.batchBirthday, ctx.batchNoDob])
+```
+
+## 025 — run the workflow, and wait for the right thing
+
+`manual_override: false` so the filter genuinely evaluates rather than
+being bypassed.
+
+**This run never reaches a terminal status, and waiting for one would hang
+until the deadline.** The birthday row's action is scheduled for a date in
+the future, so its execution log sits at `:executing` for the life of the
+run — correctly. So the wait is on `total_wels`: every row has produced an
+execution log, which is the moment the next step can read them.
+
+```typescript
+const bdRunResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug, {
+  sql_where_clause: `le.batch_id IN ('${ctx.batchBirthday}', '${ctx.batchNoDob}')`,
+  mode: 'live',
+  manual_override: false,
+})
+const bdFired = await ctx.waitForFiredRun(datalakeSlug, bdRunResp.data.workflow_run_id)
+ctx.bdRunLogId = bdFired.workflowRunLogId
+ctx.bdRunBatchId = bdFired.batchId!
+
+const welDeadline = Date.now() + 120_000
+let totalWels = 0
+while (Date.now() < welDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug, ctx.bdRunLogId,
+  )
+  if (log.status === 'failed') throw new Error('birthday workflow run reached :failed')
+  totalWels = typeof log.total_wels === 'number' ? log.total_wels : 0
+  if (totalWels >= 2) break
+  await new Promise((r) => setTimeout(r, 1_500))
+}
+if (totalWels < 2) throw new Error(`birthday run produced only ${totalWels}/2 execution logs within 120s`)
+```
+
+## 026 — verify the filter routed
+
+The contact with a date of birth passes and its log is `:executing` (a
+future action is scheduled) or `:completed`. The contact without one is
+`:filtered` — it never reached the action at all.
+
+```typescript
+const { data: bdLogs } = await api.workflows.workflowLogs.list(
+  tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug,
+)
+const bdWels = (bdLogs.data ?? []).filter(
+  (w) => (w as { batch_id?: string }).batch_id === ctx.bdRunBatchId,
+)
+if (bdWels.length !== 2) {
+  throw new Error(`expected 2 execution logs for the birthday run, got ${bdWels.length}`)
+}
+
+const bdByStatus: Record<string, number> = {}
+for (const w of bdWels) {
+  const st = (w as { status?: string }).status ?? 'unknown'
+  bdByStatus[st] = (bdByStatus[st] ?? 0) + 1
+}
+const bdPassed = (bdByStatus.executing ?? 0) + (bdByStatus.completed ?? 0)
+if (bdPassed !== 1) {
+  throw new Error(`expected 1 pass-branch log, got ${bdPassed} — ${JSON.stringify(bdByStatus)}`)
+}
+if ((bdByStatus.filtered ?? 0) !== 1) {
+  throw new Error(`expected 1 :filtered log (the contact with no date of birth) — ${JSON.stringify(bdByStatus)}`)
+}
+```
+
+## 027 — find the contact the greeting is for
+
+`workflows.execute` is addressed by dataset id, so the birthday contact's
+legal-entity id has to be resolved first. Search scoped to its own batch.
+
+```typescript
+const { data: bdSearchDef } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'legal_entity', {
+  search_query: `le.batch_id = '${ctx.batchBirthday}'`,
+})
+if (bdSearchDef.status !== 'completed') {
+  throw new Error(`legal_entity user-search status=${bdSearchDef.status} error=${bdSearchDef.error_message ?? '(none)'}`)
+}
+const { data: bdSearch } = await api.datasets.search(tenantSlug, datalakeSlug, 'legal_entity', {
+  userSearchId: bdSearchDef.id!,
+  dataAccessMode: 'raw',
+})
+const birthdayLegalEntityId = (bdSearch.data?.[0] as { id?: string } | undefined)?.id
+if (!birthdayLegalEntityId) throw new Error('the birthday contact was not found by search')
+ctx.birthdayLegalEntityId = birthdayLegalEntityId
+```
+
+## 028 — fast-forward the scheduled greeting
+
+The greeting is scheduled for a date that has not arrived, so it will not
+dispatch during this sitting. `trigger_override: true` promotes the queued
+job so it runs now.
+
+**What moves is the job, and only the job.** The execution log still
+records the year-roll-rendered `scheduled_at` it was always going to have,
+which is what keeps the override's blast radius to this one dispatch
+instead of rewriting the schedule.
+
+On a repeat run the greeting has already been sent for this contact and the
+idempotency key refuses to send it again, so the forced log completes with
+nothing dispatched. Both are `:completed`; the assertion that the greeting
+*exists* belongs to §029, where it is true either way.
+
+```typescript
+const { data: execResp } = await api.workflows.execute(tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug, {
+  dataset_id: ctx.birthdayLegalEntityId,
+  decision_key: 'send_happy_birthday_sms',
+  manual_override: true,
+  trigger_override: true,
+})
+ctx.forcedWelId = execResp.workflow_execution_log_id!
+
+const forcedDeadline = Date.now() + 120_000
+let forcedStatus: string | null = null
+while (Date.now() < forcedDeadline) {
+  const { data: wel } = await api.workflows.workflowLogs.get(
+    tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug, ctx.forcedWelId,
+  )
+  forcedStatus = (wel as { status?: string }).status ?? null
+  if (forcedStatus && forcedStatus !== 'pending' && forcedStatus !== 'executing') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (forcedStatus !== 'completed') {
+  throw new Error(`the fast-forwarded log did not reach :completed (last status: ${forcedStatus})`)
+}
+```
+
+## 029 — the greeting exists, and it carries a deep link
+
+The end state: a birthday greeting exists for this contact, with a
+`/t/<token>` link in its body. True on the first run because the action
+just dispatched, and true on every run after because it dispatched once and
+the idempotency key has protected it since.
+
+**Read the durable record, not the run you just made.** The obvious move is
+to pull the rendered body off the execution log from §028 — and that works
+exactly once. On a repeat run that log's action is skipped and carries no
+body at all, so the walk goes red having proved nothing except that
+idempotency works. The `message` row persists in the lake and is the
+answer to "does this contact have a greeting", which is the question worth
+asking. In local dev the publish itself lands in LocalStack's SNS records
+at `/_aws/sns/sms-messages`, keyed by phone number — useful to eyeball, too
+volatile to assert on.
+
+```typescript
+const { data: bdMsgSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key LIKE '${ctx.birthdayLegalEntityId}-%'`,
+})
+if (bdMsgSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${bdMsgSearch.status} error=${bdMsgSearch.error_message ?? '(none)'}`)
+}
+
+const bdMsgDeadline = Date.now() + 45_000
+let bdMessages: Array<Record<string, unknown>> = []
+while (Date.now() < bdMsgDeadline && bdMessages.length === 0) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: bdMsgSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  bdMessages = (data.data ?? []) as Array<Record<string, unknown>>
+  if (bdMessages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (bdMessages.length === 0) {
+  throw new Error(
+    `no birthday greeting for contact ${ctx.birthdayLegalEntityId} within 45s — ` +
+      `the action never fired, or it fired under a different idempotency key`,
+  )
+}
+
+const greeting = bdMessages
+  .map((m) => String(m.body ?? ''))
+  .find((b) => b.includes('Happy birthday') && b.includes('/t/'))
+if (!greeting) {
+  throw new Error(`no greeting body with a /t/ link — bodies: ${JSON.stringify(bdMessages.map((m) => m.body))}`)
+}
+const bdToken = greeting.match(/\/t\/([A-Za-z0-9_-]+)/)
+if (!bdToken) throw new Error(`no /t/<token> in the rendered greeting: ${greeting}`)
+ctx.birthdayShortPath = bdToken[1]!
+```
+
+## 030 — resolve the link, and close the loop
+
+The shortlink resolves through `connectedApps.resolvePage`, and the
+`route_path` that comes back must match the action's `connected_app_route`.
+Posting `opened_at` and `form_submitted_at` then mirrors exactly what the
+form's frontend does when the recipient opens it — which closes the loop
+from a scheduled greeting to a tracked reply.
+
+```typescript
+const { data: bdResolved } = await api.connectedApps.resolvePage(
+  tenantSlug, datalakeSlug, ctx.birthdayAppSlug,
+  { short_path: ctx.birthdayShortPath, user_agent: 'cookbook-doctest/birthday-greeting' },
+)
+if (bdResolved.route_path !== '/forms/birthday-greeting') {
+  throw new Error(`resolvePage route_path mismatch: ${bdResolved.route_path}`)
+}
+
+const bdNow = new Date().toISOString()
+const { data: bdTracked } = await api.connectedApps.updateMessageTracking(
+  tenantSlug, datalakeSlug, ctx.birthdayAppSlug,
+  { short_path: ctx.birthdayShortPath, opened_at: bdNow, form_submitted_at: bdNow },
+)
+if (!bdTracked.message?.opened_at || !bdTracked.message?.form_submitted_at) {
+  throw new Error('message tracking did not persist opened_at + form_submitted_at')
+}
+```
+
+## 031 — the roster and the audience, as two tables
+
+A campaign needs two rosters and they are not the same thing. **Direct
+customers** are the businesses running campaigns; **end customers** are the
+people a campaign may contact. The platform models neither, because which
+businesses you serve is domain data.
+
+Three columns on the audience carry the entire business rule.
+`suppressed` is do-not-contact — the workflow *filter* reads it, so a
+suppressed person is unselectable by any campaign rather than merely hidden
+in some screen. `phone` and `email` are the two channel destinations, and
+their presence is the reachability gate. `bucket` is the A/B assignment,
+stamped at ingest and split on by the decision node.
+
+Note which columns are masked and which are not: the three PII columns are
+`tokenize`, while `suppressed` and `bucket` are `none`. Campaign mechanics
+are not personal data, and the workflow has to read them.
+
+```typescript
+const rosterTable = await ctx.ensure(
+  'Direct Customers table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Cookbook Direct Customers')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Cookbook Direct Customers',
+      description: 'The businesses running marketing campaigns.',
+      columns: [
+        { name: 'direct_customer_id', title: 'Direct Customer ID', type: 'string', description: 'Vendor-supplied unique business id', is_unique: true, privacy_requirement: 'none' },
+        { name: 'business_name', title: 'Business Name', type: 'string', description: 'Business display name (public record, not PII)', is_unique: false, privacy_requirement: 'none' },
+        { name: 'sender_phone', title: 'Sender Phone', type: 'string', description: 'Shared number campaigns send SMS from', is_unique: false, privacy_requirement: 'none' },
+        { name: 'sender_domain', title: 'Sender Domain', type: 'string', description: 'Shared domain campaigns send email from', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
+ctx.rosterTableId = rosterTable.id!
+ctx.rosterTableName = rosterTable.name!
+
+const audienceTable = await ctx.ensure(
+  'End Customers table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Cookbook End Customers')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Cookbook End Customers',
+      description: 'The people a campaign may contact.',
+      columns: [
+        { name: 'end_customer_id', title: 'End Customer ID', type: 'string', description: 'Vendor-supplied unique end-customer id', is_unique: true, privacy_requirement: 'none' },
+        { name: 'direct_customer_id', title: 'Direct Customer ID', type: 'string', description: 'The business this end customer belongs to', is_unique: false, privacy_requirement: 'none' },
+        { name: 'name', title: 'Name', type: 'string', description: 'Recipient full name', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'email', title: 'Email', type: 'string', description: 'Recipient email — the email-channel destination', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'phone', title: 'Phone', type: 'string', description: 'Recipient phone — the SMS-channel destination', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'suppressed', title: 'Suppressed', type: 'boolean', description: 'Do-not-contact flag — a suppressed recipient is never selected', is_unique: false, privacy_requirement: 'none' },
+        { name: 'bucket', title: 'Bucket', type: 'integer', description: 'Stable 0-99 A/B bucket assigned at ingest; the decision node splits on it', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
+ctx.audienceTableId = audienceTable.id!
+ctx.audienceTableName = audienceTable.name!
+
+await ctx.deployGenericTable(ctx.rosterTableName)
+await ctx.deployGenericTable(ctx.audienceTableName)
+```
+
+## 032 — the inbound-messages table, which you must not create
+
+Replies land in `inbound_messages`. It is a **system** table: it ships with
+every datalake, its `type` is `'system'` rather than `'custom'`, and nobody
+creates it. You find it by name.
+
+Trying to create it is the mistake this step exists to prevent — the name is
+reserved and the physical table is already there, so the attempt fails in a
+way that reads like a permissions problem.
+
+```typescript
+const { data: allTables } = await api.genericTables.list(tenantSlug, datalakeSlug)
+const inbound = (allTables.data ?? []).find((t: { name?: string }) => t.name === 'inbound_messages')
+if (!inbound) {
+  throw new Error('inbound_messages must ship with every datalake')
+}
+if (inbound.type !== 'system') {
+  throw new Error(`inbound_messages must be a system table, got type=${inbound.type}`)
+}
+ctx.inboundTableId = inbound.id!
+ctx.inboundTableName = inbound.name!
+```
+
+## 033 — the roster contracts, on two clients
+
+Each roster row becomes two things: a row in the Direct Customers table,
+and a **business** legal entity. That is the contract pair — and the pair
+goes on **two clients**, for the reason §020 of `payments-compliance`
+sets out in full and this step restates because it is the single most
+expensive thing to learn twice.
+
+A client fans out per row × contract and the job key includes the contract
+id, so a pair bound to one client runs both contracts **at the same
+instant**. Both find-or-create the same subject, both miss the dedupe read,
+both insert, and the unique index on `(uri, id_type, id_number)` refuses the
+loser. It works on every run except the first.
+
+**And note the identifier shape in the MDM template**: `uri` / `type` /
+`value` — not `id_type` / `id_number` / `uri`, which is what the legal-entity
+body above takes. Three shapes name one idea on this platform, and they
+overlap unevenly. `system` — what `POST /mdm/verify` takes — is a genuine
+alias here: `MDMInput` casts it and normalises it onto `uri`, so a template
+using it resolves correctly. `id_type` and `id_number` are not cast at all,
+and unknown keys are dropped rather than refused — so borrowing the
+legal-entity names for the MDM side resolves nothing and fails as a bare
+`mdm_dispatcher_error` naming no field.
+
+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.
+
+```typescript
+const ROSTER_LE = `{% assign p = msg %}
+{
+  "legal_entity_type": "business",
+  "role": "direct",
+  "business_name": "{{ p.business_name | json_escape }}",
+  "identifications": [
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}", "id_number": "{{ p.direct_customer_id | json_escape }}"}
+  ]
+}`
+
+const ROSTER_GT = `{% assign p = msg %}
+{
+  "direct_customer_id": "{{ p.direct_customer_id | json_escape }}",
+  "business_name": "{{ p.business_name | json_escape }}",
+  "sender_phone": "{{ p.sender_phone | json_escape }}",
+  "sender_domain": "{{ p.sender_domain | json_escape }}"
+}`
+
+const ROSTER_MDM = `{% assign p = msg %}
+{
+  "legal_entity_type": "business",
+  "business_name": "{{ p.business_name | json_escape }}",
+  "identifiers": [
+    {"uri": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ p.direct_customer_id | json_escape }}"}
+  ]
+}`
+
+const rosterLe = await ctx.ensure(
+  'roster business LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Roster Business LE')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Roster Business LE',
+      description: 'Roster row → business LegalEntity.',
+      resource_type: 'legal_entity',
+      type: 'identity',
+      generic_table_id: null,
+      template_config: { type: 'custom', body: ROSTER_LE },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+
+const rosterGt = await ctx.ensure(
+  'roster generic-table contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Roster GT')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Roster GT',
+      description: 'Roster row → Direct Customers row, stamped with its business subject.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.rosterTableId,
+      template_config: { type: 'custom', body: ROSTER_GT },
+      mdm_input_config: { type: 'custom', body: ROSTER_MDM },
+    })
+    return data
+  },
+)
+
+const rosterIdentityDac = await ctx.ensure(
+  'roster identity client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Roster Identity Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Roster Identity Client',
+      description: 'Writes each business as a legal entity, ahead of its roster row.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [rosterLe.id!],
+    })
+    return data
+  },
+)
+ctx.rosterIdentityDacSlug = rosterIdentityDac.slug!
+
+const rosterDataDac = await ctx.ensure(
+  'roster data client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Roster Data Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Roster Data Client',
+      description: 'Writes the roster row, resolving the business the identity client wrote.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [rosterGt.id!],
+    })
+    return data
+  },
+)
+ctx.rosterDataDacSlug = rosterDataDac.slug!
+```
+
+## 034 — the audience contracts, on two clients
+
+Same shape, two differences that carry the campaign.
+
+Each recipient resolves to an **individual** legal entity keyed on their
+contact handle — phone when there is one, email otherwise. That subject is
+what the per-recipient short link in §039 is minted against, which is what
+makes a click attributable to one person rather than to the campaign.
+
+And the generic-table contract assigns the **bucket**, derived from the last
+two digits of the vendor's own id rather than from a random draw. Re-ingest
+the same customer tomorrow and they land in the same bucket. An A/B split
+that reshuffles on every ingest is not an A/B split — it is noise with a
+report attached.
+
+```typescript
+const AUDIENCE_LE = `{% assign p = msg %}
+{% assign name_parts = p.name | default: "" | split: " " %}
+{% assign first_name = name_parts[0] | default: "" %}
+{% assign last_name_parts = name_parts | slice: 1, 9 %}
+{% assign last_name = last_name_parts | join: " " %}
+{% if p.phone and p.phone != "" %}{% assign handle = p.phone %}{% else %}{% assign handle = p.email %}{% endif %}
+{
+  "legal_entity_type": "individual",
+  "role": "direct",
+  {% if first_name != "" %}"first_name": "{{ first_name | json_escape }}",{% endif %}
+  {% if last_name != "" %}"last_name": "{{ last_name | json_escape }}",{% endif %}
+  {% if p.phone and p.phone != "" %}"phone_numbers": [{ "phone_number": "{{ p.phone | json_escape }}" }],{% endif %}
+  "identifications": [
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}", "id_number": "{{ handle | json_escape }}"}
+  ]
+}`
+
+const AUDIENCE_GT = `{% assign p = msg %}
+{% assign bucket = p.end_customer_id | slice: -2, 2 | plus: 0 %}
+{
+  "end_customer_id": "{{ p.end_customer_id | json_escape }}",
+  "direct_customer_id": "{{ p.direct_customer_id | json_escape }}",
+  "name": "{{ p.name | default: "" | json_escape }}",
+  "email": "{{ p.email | default: "" | json_escape }}",
+  "phone": "{{ p.phone | default: "" | json_escape }}",
+  "suppressed": {% if p.suppressed %}true{% else %}false{% endif %},
+  "bucket": {{ bucket }}
+}`
+
+const AUDIENCE_MDM = `{% assign p = msg %}
+{% assign name_parts = p.name | default: "" | split: " " %}
+{% assign first_name = name_parts[0] | default: "" %}
+{% assign last_name_parts = name_parts | slice: 1, 9 %}
+{% assign last_name = last_name_parts | join: " " %}
+{% if p.phone and p.phone != "" %}{% assign handle = p.phone %}{% else %}{% assign handle = p.email %}{% endif %}
+{
+  "legal_entity_type": "individual",
+  {% if first_name != "" %}"first_name": "{{ first_name | json_escape }}",{% endif %}
+  {% if last_name != "" %}"last_name": "{{ last_name | json_escape }}",{% endif %}
+  "identifiers": [
+    {"uri": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ handle | json_escape }}"}
+  ]
+}`
+
+const audienceLe = await ctx.ensure(
+  'audience LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Audience LE')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Audience LE',
+      description: 'Audience row → end-customer LegalEntity, keyed on the contact handle.',
+      resource_type: 'legal_entity',
+      type: 'identity',
+      generic_table_id: null,
+      template_config: { type: 'custom', body: AUDIENCE_LE },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+
+const audienceGt = await ctx.ensure(
+  'audience generic-table contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Audience GT')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Audience GT',
+      description: 'Audience row → End Customers row, stamped with its subject and its stable A/B bucket.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.audienceTableId,
+      template_config: { type: 'custom', body: AUDIENCE_GT },
+      mdm_input_config: { type: 'custom', body: AUDIENCE_MDM },
+    })
+    return data
+  },
+)
+
+const audienceIdentityDac = await ctx.ensure(
+  'audience identity client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Audience Identity Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Audience Identity Client',
+      description: 'Writes each recipient as a legal entity, ahead of their audience row.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [audienceLe.id!],
+    })
+    return data
+  },
+)
+ctx.audienceIdentityDacSlug = audienceIdentityDac.slug!
+
+const audienceDataDac = await ctx.ensure(
+  'audience data client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Audience Data Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Audience Data Client',
+      description: 'Writes the audience row, resolving the recipient the identity client wrote.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [audienceGt.id!],
+    })
+    return data
+  },
+)
+ctx.audienceDataDacSlug = audienceDataDac.slug!
+```
+
+## 035 — ingest one business and four recipients, identities first
+
+Four recipients chosen so a single run exercises every branch at once:
+
+| Recipient | phone | email | suppressed | bucket | expected |
+|-----------|-------|-------|------------|--------|----------|
+| Ada       | yes   | yes   | no         | 10     | sent, variant A |
+| Grace     | yes   | yes   | no         | 80     | sent, variant B |
+| Sup       | yes   | yes   | **yes**    | 31     | filtered — suppressed |
+| Nophone   | —     | yes   | no         | 42     | filtered — unreachable |
+
+The buckets are not set by hand. They fall out of the ids ending `-10`,
+`-80`, `-31`, `-42`, which is §034's Liquid doing the assignment.
+
+Identities go first and are waited on, then the rows. Within a stage the
+four recipients have four different handles, so they never contend with each
+other — the ordering that matters is between the stages, not inside them.
+
+```typescript
+ctx.rosterId = 'DC-COOKBOOK-01'
+ctx.adaId = 'EC-COOKBOOK-10'
+ctx.graceId = 'EC-COOKBOOK-80'
+ctx.supId = 'EC-COOKBOOK-31'
+ctx.nophoneId = 'EC-COOKBOOK-42'
+ctx.adaPhone = '+15550200010'
+
+const rosterRow = {
+  direct_customer_id: ctx.rosterId,
+  business_name: 'Bloom Salon',
+  sender_phone: '+15550001111',
+  sender_domain: 'bloom-salon.example.com',
+}
+const audienceRows = [
+  { end_customer_id: ctx.adaId, direct_customer_id: ctx.rosterId, name: 'Ada Lovelace', email: 'ada@cookbook.example.com', phone: ctx.adaPhone, suppressed: false },
+  { end_customer_id: ctx.graceId, direct_customer_id: ctx.rosterId, name: 'Grace Hopper', email: 'grace@cookbook.example.com', phone: '+15550200080', suppressed: false },
+  { end_customer_id: ctx.supId, direct_customer_id: ctx.rosterId, name: 'Sup Pressed', email: 'sup@cookbook.example.com', phone: '+15550200031', suppressed: true },
+  { end_customer_id: ctx.nophoneId, direct_customer_id: ctx.rosterId, name: 'No Phone', email: 'nophone@cookbook.example.com', phone: '', suppressed: false },
+]
+
+// Stage 1 — the business, then the people.
+const rosterIdent = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.rosterIdentityDacSlug, { data: rosterRow },
+)
+await ctx.waitForBatches(ctx.rosterIdentityDacSlug, [rosterIdent.data.batch_id!])
+
+const audienceIdentBatches: string[] = []
+for (const row of audienceRows) {
+  const r = await api.dataActivationClients.ingest(
+    tenantSlug, datalakeSlug, ctx.audienceIdentityDacSlug, { data: row },
+  )
+  audienceIdentBatches.push(r.data.batch_id!)
+}
+await ctx.waitForBatches(ctx.audienceIdentityDacSlug, audienceIdentBatches)
+
+// Stage 2 — the rows, which resolve the subjects that now exist.
+const rosterData = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, ctx.rosterDataDacSlug, { data: rosterRow },
+)
+await ctx.waitForBatches(ctx.rosterDataDacSlug, [rosterData.data.batch_id!])
+
+const audienceDataBatches: string[] = []
+for (const row of audienceRows) {
+  const r = await api.dataActivationClients.ingest(
+    tenantSlug, datalakeSlug, ctx.audienceDataDacSlug, { data: row },
+  )
+  audienceDataBatches.push(r.data.batch_id!)
+}
+await ctx.waitForBatches(ctx.audienceDataDacSlug, audienceDataBatches)
+```
+
+## 036 — the stamp is the proof that resolution ran
+
+Read the four rows back. Every one carries a `legal_entity_id`, and the four
+are **distinct** — four recipients, four subjects. A shared subject would
+mean two people collapsed into one, and a short link pointing at the wrong
+customer.
+
+The buckets are checked here too, because a wrong bucket is the kind of
+thing that stays invisible until someone asks why variant A outperformed B
+by a suspiciously round margin.
+
+```typescript
+const rowsDeadline = Date.now() + 120_000
+let audienceRowsRead: Array<Record<string, unknown>> = []
+while (Date.now() < rowsDeadline && audienceRowsRead.length < 4) {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT end_customer_id, bucket, legal_entity_id
+          FROM ${ctx.audienceTableName}
+          WHERE end_customer_id LIKE 'EC-COOKBOOK-%'`,
+    mode: 'raw',
+  })
+  audienceRowsRead = (result.data ?? []).map((r) =>
+    Object.fromEntries(result.meta.columns.map((c, i) => [c, r[i]])),
+  )
+  if (audienceRowsRead.length < 4) await new Promise((r) => setTimeout(r, 2_000))
+}
+if (audienceRowsRead.length !== 4) {
+  throw new Error(`expected 4 audience rows within 120s, got ${audienceRowsRead.length}`)
+}
+
+const byCustomerId = new Map(audienceRowsRead.map((r) => [String(r.end_customer_id), r]))
+if (Number(byCustomerId.get(ctx.adaId)!.bucket) !== 10) throw new Error('Ada must land in bucket 10')
+if (Number(byCustomerId.get(ctx.graceId)!.bucket) !== 80) throw new Error('Grace must land in bucket 80')
+
+for (const row of audienceRowsRead) {
+  if (!row.legal_entity_id) {
+    throw new Error(`${row.end_customer_id} has no stamped subject — resolution did not run`)
+  }
+}
+const subjects = new Set(audienceRowsRead.map((r) => String(r.legal_entity_id)))
+if (subjects.size !== 4) {
+  throw new Error(`four recipients must be four distinct subjects, got ${subjects.size}`)
+}
+ctx.adaSubjectId = String(byCustomerId.get(ctx.adaId)!.legal_entity_id)
+```
+
+## 037 — two sender tools, and the booking form
+
+**Two sender tools, not one.** An SMS number and an email identity are
+different assets, provisioned and billed separately, so §038 binds each
+channel to its own.
+
+The email tool uses `provider: 'mock'`, which delivers in-process to the dev
+mailbox. Note *where* that setting lives: it is a field on the **tool body**
+— data on a row — not an environment variable. So the same manifest runs
+against any server without asking the deployment to be in "test mode", and
+swapping `mock` for a real provider sends real email through the same
+workflow.
+
+```typescript
+const campaignSms = await ctx.ensure(
+  'campaign SMS sender',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook Campaign SMS Sender')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Campaign SMS Sender',
+      description: 'SNS-backed SMS dispatcher for the campaign, 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: '+15550001111',
+        endpoint_url: 'http://localhost:4566',
+        access_key_id: 'test',
+        secret_access_key: 'test',
+      },
+    })
+    return data
+  },
+)
+ctx.campaignSmsToolId = campaignSms.id!
+
+const campaignEmail = await ctx.ensure(
+  'campaign email sender',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook Campaign Email Sender')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Campaign Email Sender',
+      description: 'Campaign email dispatcher — the mock provider delivers to the dev mailbox.',
+      intent: 'email',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      body: {
+        tool_body_type: 'email',
+        provider: 'mock',
+        from_email: 'campaigns@bloom-salon.example.com',
+        from_name: 'Bloom Salon',
+      },
+    })
+    return data
+  },
+)
+ctx.campaignEmailToolId = campaignEmail.id!
+
+const bookingApp = await ctx.ensure(
+  'campaign booking form',
+  async () => {
+    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((a: { name?: string }) => a.name === 'Cookbook Campaign Booking Form')
+  },
+  async () => {
+    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Campaign Booking Form',
+      description: 'The booking form the campaign links to.',
+      mode: 'self_hosted',
+      urls: [{ url: 'https://campaign.example.com', is_primary: true, label: 'production' }],
+    })
+    return data
+  },
+)
+ctx.bookingAppId = bookingApp.id!
+ctx.bookingAppSlug = bookingApp.slug!
+```
+
+## 038 — the campaign workflow: the gates, the split, both channels
+
+All four rules live here, and none of them lives in application code.
+
+**The gates are the filter.** `{% unless event_dataset.suppressed %}` is
+suppression; the two non-empty checks are reachability. A row failing either
+is `:filtered` — looked at, and deliberately not contacted. There is no code
+path around it, which is exactly what you want to be able to say about a
+do-not-contact list.
+
+**The split is the decision node**, and it returns an *array* — both channel
+keys of the chosen variant. Bucket under fifty gets the A pair, otherwise
+the B pair. Four actions declare a `decision_key` each; the platform runs
+the two whose keys came back and skips the other two. That is one recipient,
+one variant, two channels, from one run — and the pairing is data rather
+than two workflows kept in step by hand.
+
+**`skip_mdm_resolution: false` is set explicitly, and must be.** A
+generic-table row is never its own subject; the subject is the one §034
+stamped onto it. With resolution on, the platform loads that subject and
+mints a page token against it, which is what makes
+`{{ connected_app_form_url }}` a *per-recipient* link. Skip it and the
+subject is nil, no token is minted, and the link renders empty — with
+nothing anywhere reporting a problem.
+
+`output_schema` is a JSON-Schema **object**. The string form is refused 422.
+
+```typescript
+const CAMPAIGN_FILTER =
+  '{% unless event_dataset.suppressed %}' +
+  '{% if event_dataset.phone and event_dataset.phone != "" %}' +
+  '{% if event_dataset.email and event_dataset.email != "" %}true{% endif %}' +
+  '{% endif %}{% endunless %}'
+const AB_DECISION =
+  '{% if event_dataset.bucket < 50 %}["sms_variant_a","email_variant_a"]' +
+  '{% else %}["sms_variant_b","email_variant_b"]{% endif %}'
+const VARIANT_A = 'Hi {{ event_dataset.name }} — 20% off your next visit this week only. Book: {{ connected_app_form_url }}'
+const VARIANT_B = 'Hi {{ event_dataset.name }} — your loyalty reward is waiting. Claim: {{ connected_app_form_url }}'
+
+const linkage = {
+  trigger_template: 'now',
+  idempotency_template: '{{ event_dataset.end_customer_id }}/{{ action_id }}',
+  connected_app_id: ctx.bookingAppId,
+  connected_app_route: '/forms/campaign',
+  connected_app_metadata_template:
+    '{"end_customer_id":"{{ event_dataset.end_customer_id }}","name":"{{ event_dataset.name }}"}',
+}
+
+const campaign = await ctx.ensure(
+  'loyalty campaign workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook Loyalty Campaign')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Loyalty Campaign',
+      description: 'Loyalty campaign with A/B content variants across SMS and email.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.audienceTableId,
+      status: 'live',
+      tags: ['marketing', 'loyalty'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: CAMPAIGN_FILTER },
+      decision_config: {
+        type: 'custom',
+        body: AB_DECISION,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      actions: [
+        {
+          ...linkage,
+          action_type: 'sms', tool_id: ctx.campaignSmsToolId, decision_key: 'sms_variant_a', position: 0,
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '{{ event_dataset.phone }}' },
+            body: { type: 'custom', body: VARIANT_A },
+            sms_type: 'transactional',
+          },
+        },
+        {
+          ...linkage,
+          action_type: 'sms', tool_id: ctx.campaignSmsToolId, decision_key: 'sms_variant_b', position: 1,
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '{{ event_dataset.phone }}' },
+            body: { type: 'custom', body: VARIANT_B },
+            sms_type: 'transactional',
+          },
+        },
+        {
+          ...linkage,
+          action_type: 'email', tool_id: ctx.campaignEmailToolId, decision_key: 'email_variant_a', position: 2,
+          tool_call: {
+            tool_call_type: 'email_request',
+            to: { type: 'custom', body: '{{ event_dataset.email }}' },
+            subject: { type: 'custom', body: 'Your 20% off is here' },
+            body: { type: 'custom', body: VARIANT_A },
+          },
+        },
+        {
+          ...linkage,
+          action_type: 'email', tool_id: ctx.campaignEmailToolId, decision_key: 'email_variant_b', position: 3,
+          tool_call: {
+            tool_call_type: 'email_request',
+            to: { type: 'custom', body: '{{ event_dataset.email }}' },
+            subject: { type: 'custom', body: 'Your loyalty reward is waiting' },
+            body: { type: 'custom', body: VARIANT_B },
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.campaignWorkflowSlug = campaign.slug!
+
+if (campaign.skip_mdm_resolution !== false) {
+  throw new Error('a generic-table campaign workflow must keep MDM resolution ON')
+}
+if ((campaign.actions ?? []).length !== 4) {
+  throw new Error(`expected 4 actions, got ${(campaign.actions ?? []).length}`)
+}
+```
+
+## 039 — run the campaign, and read the split off the logs
+
+One pass over all four recipients: both gates and the split in the same run.
+
+The per-recipient action logs are the review surface. Each sending
+recipient's execution log carries four action logs, and the two that ran are
+the **same variant on both channels**. Group the completed ones by
+`decision_key` and you have per-variant performance without building a
+reporting pipeline.
+
+**On a repeat run all four are skipped**, because the idempotency key fired
+the first time — so the assertion accepts either shape, and rejects anything
+else. Two completed from *different* variants would mean the split leaked;
+that is the failure worth catching here.
+
+```typescript
+const { data: campaignRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.campaignWorkflowSlug, {
+  sql_where_clause: `end_customer_id LIKE 'EC-COOKBOOK-%'`,
+  mode: 'live',
+  manual_override: false,
+})
+const campaignFired = await ctx.waitForFiredRun(datalakeSlug, campaignRun.workflow_run_id)
+ctx.campaignRunLogId = campaignFired.workflowRunLogId
+ctx.campaignRunBatchId = campaignFired.batchId!
+
+const campaignDeadline = Date.now() + 180_000
+let campaignByStatus: Record<string, number> = {}
+while (Date.now() < campaignDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.campaignWorkflowSlug, ctx.campaignRunLogId,
+  )
+  if (log.status === 'failed') throw new Error('campaign run reached :failed')
+
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.campaignWorkflowSlug)
+  const ours = (wfLogs.data ?? []).filter(
+    (w) => (w as { batch_id?: string }).batch_id === ctx.campaignRunBatchId,
+  )
+  campaignByStatus = {}
+  for (const wel of ours) {
+    const st = (wel as { status?: string }).status ?? 'unknown'
+    campaignByStatus[st] = (campaignByStatus[st] ?? 0) + 1
+  }
+  if ((campaignByStatus.completed ?? 0) >= 2 && (campaignByStatus.filtered ?? 0) >= 2) break
+  await new Promise((r) => setTimeout(r, 3_000))
+}
+if ((campaignByStatus.completed ?? 0) !== 2 || (campaignByStatus.filtered ?? 0) !== 2) {
+  throw new Error(`expected 2 completed + 2 filtered, got ${JSON.stringify(campaignByStatus)}`)
+}
+
+const { data: campaignLogs } = await api.workflows.workflowLogs.list(
+  tenantSlug, datalakeSlug, ctx.campaignWorkflowSlug,
+)
+const sentWels = (campaignLogs.data ?? []).filter((w) => {
+  const wel = w as { batch_id?: string; status?: string }
+  return wel.batch_id === ctx.campaignRunBatchId && wel.status === 'completed'
+})
+
+for (const wel of sentWels) {
+  const aels = (wel as { action_execution_logs?: Array<{ status?: string; decision_key?: string }> })
+    .action_execution_logs ?? []
+  if (aels.length !== 4) throw new Error(`four actions → four action logs, got ${aels.length}`)
+
+  const completed = aels.filter((a) => a.status === 'completed').map((a) => a.decision_key ?? '').sort()
+  const skipped = aels.filter((a) => a.status === 'skipped')
+
+  if (completed.length === 0 && skipped.length === 4) continue  // already sent on an earlier run
+
+  if (completed.length !== 2 || skipped.length !== 2) {
+    throw new Error(`expected 2 completed + 2 skipped action logs, got ${JSON.stringify(aels)}`)
+  }
+  const isA = completed[0] === 'email_variant_a' && completed[1] === 'sms_variant_a'
+  const isB = completed[0] === 'email_variant_b' && completed[1] === 'sms_variant_b'
+  if (!isA && !isB) {
+    throw new Error(`the completed pair must be one variant on both channels, got ${completed.join(', ')}`)
+  }
+}
+```
+
+## 040 — the short link belongs to one recipient
+
+Every message the campaign rendered carries a `/t/<hash>`. It is **not** one
+campaign link shared by everyone: the token was minted against this
+recipient's own subject — the one §034 stamped and §038 resolved — so a
+click is attributable to a person rather than to a send.
+
+Keyed on the idempotency key again, so this reads the durable record and
+answers on every run rather than only the one that dispatched.
+
+```typescript
+const { data: campaignMsgSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key LIKE '${ctx.adaId}/%'`,
+})
+if (campaignMsgSearch.status !== 'completed') {
+  throw new Error(`message user-search status=${campaignMsgSearch.status} error=${campaignMsgSearch.error_message ?? '(none)'}`)
+}
+
+const linkDeadline = Date.now() + 120_000
+let campaignShortPath: string | undefined
+while (Date.now() < linkDeadline && !campaignShortPath) {
+  const { data: found } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: campaignMsgSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  const bodies = ((found.data ?? []) as Array<Record<string, unknown>>).map((m) => String(m.body ?? ''))
+  campaignShortPath = bodies.find((b) => b.includes('/t/'))?.match(/\/t\/([A-Za-z0-9_-]+)/)?.[1]
+  if (!campaignShortPath) await new Promise((r) => setTimeout(r, 2_000))
+}
+if (!campaignShortPath) {
+  throw new Error(`no campaign message for ${ctx.adaId} carried a /t/ short link within 120s`)
+}
+
+const { data: campaignResolved } = await api.connectedApps.resolvePage(
+  tenantSlug, datalakeSlug, ctx.bookingAppSlug,
+  { short_path: campaignShortPath, user_agent: 'cookbook-doctest/marketing-campaign-send' },
+)
+if (campaignResolved.route_path !== '/forms/campaign') {
+  throw new Error(`resolvePage route_path mismatch: ${campaignResolved.route_path}`)
+}
+
+const { data: campaignTracked } = await api.connectedApps.updateMessageTracking(
+  tenantSlug, datalakeSlug, ctx.bookingAppSlug,
+  { short_path: campaignShortPath, opened_at: new Date().toISOString() },
+)
+if (!campaignTracked.message?.opened_at) {
+  throw new Error('message tracking did not persist opened_at')
+}
+```
+
+## 041 — the reply comes back, and attaches to whoever sent it
+
+A reply arrives on the same handle the campaign sent to. It ingests into the
+**system** inbound table through a client whose `mdm_input_config` keys on
+the same `(uri, value)` namespace §034 wrote — so the platform resolves the
+handle straight back to the customer and stamps their subject on the row.
+
+**This client carries only a generic-table contract**, and that is not an
+oversight: a reply does not create a person, it finds one. Adding a
+legal-entity contract here would mint a second subject for someone who
+already exists — and would put two writers on one subject, which §033
+explains at length.
+
+**When a handle is ambiguous the reply still attaches.** If two capture
+systems each registered a customer under the same phone, that handle maps to
+two entities. The row lands anyway, attached to one of them, and is marked
+`potential_duplicate` for a human to adjudicate. Flag, don't block: a dropped
+reply is a lost customer, a flagged one is a two-minute review.
+
+Below, the reply lands and attaches to Ada; then the same `message_id` is
+re-ingested with the flag set. `message_id` is the table's unique column, so
+the second ingest **upserts** — one row, now flagged, not a second copy.
+
+```typescript
+const REPLY_GT = `{% assign p = msg %}
+{
+  "message_id": "{{ p.message_id | json_escape }}",
+  "handle": "{{ p.handle | json_escape }}",
+  "channel": "{{ p.channel | json_escape }}",
+  "body": "{{ p.body | json_escape }}",
+  "potential_duplicate": {% if p.potential_duplicate %}true{% else %}false{% endif %}
+}`
+
+const REPLY_MDM = `{% assign p = msg %}
+{
+  "legal_entity_type": "individual",
+  "identifiers": [
+    {"uri": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ p.handle | json_escape }}"}
+  ]
+}`
+
+const replyGt = await ctx.ensure(
+  'inbound reply contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Reply GT')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Reply GT',
+      description: 'Inbound reply → Inbound Messages row, re-attached to the customer who sent it.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.inboundTableId,
+      template_config: { type: 'custom', body: REPLY_GT },
+      mdm_input_config: { type: 'custom', body: REPLY_MDM },
+    })
+    return data
+  },
+)
+
+const replyDac = await ctx.ensure(
+  'inbound reply client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Reply Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Reply Client',
+      description: 'Inbound reply ingest — re-attaches the sender handle to its subject.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [replyGt.id!],
+    })
+    return data
+  },
+)
+
+const replyMessageId = 'IN-COOKBOOK-0101'
+
+const readReply = async (): Promise<Record<string, unknown> | undefined> => {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT message_id, legal_entity_id, potential_duplicate
+          FROM ${ctx.inboundTableName}
+          WHERE message_id = '${replyMessageId}'`,
+    mode: 'raw',
+  })
+  if ((result.data ?? []).length === 0) return undefined
+  return Object.fromEntries(result.meta.columns.map((c, i) => [c, result.data[0][i]]))
+}
+
+const firstReply = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, replyDac.slug!,
+  { data: { message_id: replyMessageId, handle: ctx.adaPhone, channel: 'sms', body: 'Yes! Book me for Friday.' } },
+)
+await ctx.waitForBatches(replyDac.slug!, [firstReply.data.batch_id!])
+
+const reply = await readReply()
+if (!reply) throw new Error('the reply did not land in the inbound messages table')
+if (String(reply.legal_entity_id) !== ctx.adaSubjectId) {
+  throw new Error('the reply must re-attach to the customer who sent it')
+}
+
+// Same message_id, flag set — the unique column makes this an upsert.
+const flagReply = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, replyDac.slug!,
+  {
+    data: {
+      message_id: replyMessageId,
+      handle: ctx.adaPhone,
+      channel: 'sms',
+      body: 'Yes! Book me for Friday.',
+      potential_duplicate: true,
+    },
+  },
+)
+await ctx.waitForBatches(replyDac.slug!, [flagReply.data.batch_id!])
+
+const flagged = await readReply()
+if (!flagged || flagged.potential_duplicate !== true) {
+  throw new Error('the re-ingest did not flag the reply potential_duplicate')
+}
+```
+
+## 042 — reconciling what actually got delivered
+
+Everything above ends at *sent*. Sent is not delivered, and the gap between
+them is where a campaign quietly stops working — a number that has been
+disconnected for months keeps reporting `sent` forever.
+
+An **action status updater** closes that gap on a schedule. It names a
+poller tool that reads a delivery log, the sender tools it reconciles for,
+and two Liquid templates that turn each provider event into an update.
+
+Three details that are each a 422 or a silent nothing if you get them wrong.
+
+**`start_time` and `end_time` use `now_msec`, not `now`.** `now_msec` is the
+injected variable holding unix milliseconds, which is what
+`minutes_ago` expects; the bare `now` is a DateTime and raises.
+
+**`message_config` renders once per event, not once per batch.** The event
+itself is the assigns — there is no `events` list to loop over — and it must
+emit a *flat* object: the `external_id` of the message to update, plus the
+fields to set, at the top level.
+
+**`action_log_config` is required alongside it.** Same per-event assigns,
+rendered into the action-log write shape. Omitting it is a 422 that names
+the field: `Missing field: action_log_config`.
+
+```typescript
+const cwTool = await ctx.ensure(
+  'CloudWatch poller tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook CloudWatch Poller')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook CloudWatch Poller',
+      description: 'CloudWatch log-group poller — reads SNS delivery events for reconciliation.',
+      intent: 'status_poller',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: dataSourceId,
+      body: {
+        tool_body_type: 'cloud_watch_log_group',
+        auth_method: 'access_key',
+        region: 'us-east-1',
+        endpoint_url: 'http://localhost:4566',
+        access_key_id: 'test',
+        secret_access_key: 'test',
+      },
+    })
+    return data
+  },
+)
+ctx.cwToolId = cwTool.id!
+
+const deliveryUpdater = await ctx.ensure(
+  'SMS delivery reconciler',
+  async () => {
+    const { data } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((u: { name?: string }) => u.name === 'Cookbook SMS Delivery Updater')
+  },
+  async () => {
+    const { data } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook SMS Delivery Updater',
+      cron_expression: '*/30 * * * *',
+      updater_type: 'cloud_watch',
+      updater_tool_id: ctx.cwToolId,
+      sender_tool_ids: [ctx.smsToolId],
+      datalake_id: ctx.datalakeId,
+      updater_body: {
+        updater_body_type: 'cloud_watch_request',
+        log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
+        start_time: '{{ now_msec | minutes_ago: 45 }}',
+        end_time: '{{ now_msec }}',
+      },
+      message_config: {
+        type: 'custom',
+        body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+      },
+      action_log_config: {
+        type: 'custom',
+        body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+      },
+    })
+    return data
+  },
+)
+actionStatusUpdaterId = deliveryUpdater.id!
+```
+
+## 043 — read it back, and check the checksum
+
+`get` returns the stored row and its fields echo what you sent. `checksum`
+recomputes the fingerprint from a body **without persisting it** — so
+comparing the two is how you detect that a reconciler on the server has
+drifted from the one in your manifest, before it silently reconciles
+against the wrong window.
+
+The catalog reads are worth knowing about for a different reason: they are
+what an agent reads to find out which reconcilers exist at all.
+
+```typescript
+const { data: storedUpdater } = await api.actionStatusUpdaters.get(
+  tenantSlug, datalakeSlug, actionStatusUpdaterId,
+)
+if (storedUpdater.cron_expression !== '*/30 * * * *') {
+  throw new Error(`cron mismatch on read-back: ${storedUpdater.cron_expression}`)
+}
+
+const { data: updaterList } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+if (!(updaterList.data ?? []).some((u) => u.id === actionStatusUpdaterId)) {
+  throw new Error('the created reconciler is not in the list')
+}
+
+const { data: updaterCatalog } = await api.actionStatusUpdaters.metadata(tenantSlug, datalakeSlug)
+if (typeof updaterCatalog !== 'string' || updaterCatalog.length === 0) {
+  throw new Error('expected a non-empty reconciler catalog')
+}
+
+const { data: updaterDetail } = await api.actionStatusUpdaters.metadataDetails(
+  tenantSlug, datalakeSlug, actionStatusUpdaterId,
+)
+if (typeof updaterDetail !== 'string' || updaterDetail.length === 0) {
+  throw new Error('expected non-empty reconciler detail')
+}
+```
+
+## 044 — a poller that cannot advance is refused at create
+
+Not every delivery log is a log group. Pulling outcomes from a provider's
+REST events API means paging, and paging is where this goes wrong in a way
+that looks like it is working.
+
+**The platform refuses a poller whose request can never move.** Below, the
+first create renders a path and params that read neither
+`msg.pagination_context` nor `msg.page` — so page five hundred's request is
+byte-identical to page one's, `has_next` never goes false, and the run
+re-applies the same events forever. That is a 422 at create, and the walk
+catches it deliberately rather than mentioning it.
+
+Then the shape that is accepted: page one renders the plain collection path
+with bounded params, and every later page rides the cursor the pagination
+template captured — dropping the params, because the provider's `next` is a
+complete URL that already carries them.
+
+Two more floors worth stating. `events_output_schema` must be an array of
+**objects that require `external_id`**; a bare `{ type: 'array' }` is
+refused, because an event that does not name the message it reconciles
+cannot reconcile anything. And the provider's own id becomes `external_id`
+in the **events template** — the apply path pops that key to find the row it
+updates, so the render projects each event rather than passing the
+provider's body through untouched.
+
+```typescript
+const restTool = await ctx.ensure(
+  'REST events poller tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook REST Events Poller')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook REST Events Poller',
+      description: 'REST poller — supplies auth for a provider events API.',
+      intent: 'status_poller',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: dataSourceId,
+      body: {
+        tool_body_type: 'rest_api',
+        base_url: 'http://localhost:8080/mailgun/v3',
+        auth_method: 'basic',
+        username: 'api',
+        password: 'key-test',
+        request_type: 'json',
+        response_type: 'json',
+        timeout_ms: 30_000,
+      },
+    })
+    return data
+  },
+)
+ctx.restToolId = restTool.id!
+
+const EVENTS_TEMPLATE =
+  '[{% for item in response.items %}' +
+  '{"external_id": "{{ item.message.headers[\'message-id\'] }}", "event": "{{ item.event }}"}' +
+  '{% unless forloop.last %},{% endunless %}{% endfor %}]'
+const PAGINATION_TEMPLATE =
+  '{"has_next": {% if response.items.size > 0 %}true{% else %}false{% endif %}, ' +
+  '"next": "{{ response.paging.next }}"}'
+const EVENTS_OUTPUT_SCHEMA = {
+  type: 'array',
+  items: {
+    type: 'object',
+    required: ['external_id'],
+    properties: { external_id: { type: 'string' } },
+  },
+}
+const PAGINATION_OUTPUT_SCHEMA = {
+  type: 'object',
+  required: ['has_next'],
+  properties: { has_next: { type: 'boolean' } },
+}
+
+// The guard. A static request is refused — walked, not asserted from docs.
+let refused = false
+try {
+  await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+    name: 'Cookbook Non-Advancing Poller',
+    cron_expression: '*/30 * * * *',
+    updater_type: 'restapi',
+    updater_tool_id: ctx.restToolId,
+    sender_tool_ids: [ctx.smsToolId],
+    datalake_id: ctx.datalakeId,
+    events_output_schema: EVENTS_OUTPUT_SCHEMA,
+    pagination_context_output_schema: PAGINATION_OUTPUT_SCHEMA,
+    updater_body: {
+      updater_body_type: 'restapi_request',
+      method: 'get',
+      // Static on both — the cursor is captured below and never read back.
+      path: { type: 'custom', body: '/wiremock.domain/events' },
+      params: { type: 'custom', body: '{"event": "delivered"}' },
+      events_template: { type: 'custom', body: EVENTS_TEMPLATE },
+      pagination_context_template: { type: 'custom', body: PAGINATION_TEMPLATE },
+    },
+    message_config: { type: 'custom', body: '{"external_id": "{{ external_id }}", "status": "delivered"}' },
+    action_log_config: { type: 'custom', body: '{"external_id": "{{ external_id }}", "status": "delivered"}' },
+  })
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status !== 422) throw err
+  refused = true
+}
+if (!refused) {
+  throw new Error('expected a 422 for a poller whose request never consumes the cursor')
+}
+
+// The accepted shape: the path follows the cursor.
+const advancingPoller = await ctx.ensure(
+  'advancing REST delivery poller',
+  async () => {
+    const { data } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((u: { name?: string }) => u.name === 'Cookbook Advancing Delivery Poller')
+  },
+  async () => {
+    const { data } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Advancing Delivery Poller',
+      cron_expression: '*/30 * * * *',
+      updater_type: 'restapi',
+      updater_tool_id: ctx.restToolId,
+      sender_tool_ids: [ctx.smsToolId],
+      datalake_id: ctx.datalakeId,
+      events_output_schema: EVENTS_OUTPUT_SCHEMA,
+      pagination_context_output_schema: PAGINATION_OUTPUT_SCHEMA,
+      updater_body: {
+        updater_body_type: 'restapi_request',
+        method: 'get',
+        path: {
+          type: 'custom',
+          body:
+            '{% if msg.pagination_context %}{{ msg.pagination_context.next }}' +
+            '{% else %}/wiremock.domain/events{% endif %}',
+        },
+        params: {
+          type: 'custom',
+          body: '{% unless msg.pagination_context %}{"event": "delivered"}{% endunless %}',
+        },
+        events_template: { type: 'custom', body: EVENTS_TEMPLATE },
+        pagination_context_template: { type: 'custom', body: PAGINATION_TEMPLATE },
+      },
+      message_config: { type: 'custom', body: '{"external_id": "{{ external_id }}", "status": "delivered"}' },
+      action_log_config: { type: 'custom', body: '{"external_id": "{{ external_id }}", "status": "delivered"}' },
+    })
+    return data
+  },
+)
+if (advancingPoller.status !== 'active') {
+  throw new Error(`a newly created poller must be free to poll — got status ${advancingPoller.status}`)
+}
+```
+
+## 045 — ask the lake a question in plain language
+
+The last thing a marketing team needs is a way to look at any of this
+without writing SQL.
+
+`textToSql` runs ordered multi-provider failover and hands back the
+generated `sql` along with which model and provider produced it, and a
+best-effort `explanation` (`null` when the explainer is unavailable).
+
+**It does not execute anything.** It returns SQL for a human to read, which
+is the whole design: only the prompt and the datalake's *schema* cross the
+model boundary. No rows leave the trust boundary to answer a question about
+them.
+
+```typescript
+const { data: generated } = await api.datalakes.textToSql(tenantSlug, datalakeSlug, {
+  prompt: 'how many end customers are suppressed?',
+  mode: 'raw',
+})
+if (typeof generated.sql !== 'string' || generated.sql.trim() === '') {
+  throw new Error(`textToSql returned no SQL (got: ${JSON.stringify(generated.sql)})`)
+}
+if (typeof generated.model !== 'string' || typeof generated.provider !== 'string') {
+  throw new Error('textToSql response is missing its model/provider attribution')
+}
+console.log(`  ↳ ${generated.provider}/${generated.model} proposed: ${generated.sql.trim().slice(0, 120)}`)
+```
+
+## 046 — run it read-only, then take the same page as CSV
+
+`executeSql` runs read-only — inserts, updates, deletes and DDL are all
+refused — and returns `{ data, meta }`. **`data` is an array of arrays**,
+positional and aligned to `meta.columns`, because arbitrary SQL can produce
+duplicate or expression column names that object keys would collapse.
+
+The deterministic count below keeps the step independent of whatever the
+model proposed a moment ago, which is what you want in a walk: §045 proves
+the generation, this proves the execution, and neither can mask a failure in
+the other.
+
+Passing `{ format: 'csv' }` returns the same page as a string instead of the
+JSON envelope — the same read, content-negotiated for download. The curated
+return type is a union, so narrow it before reading either shape.
+
+```typescript
+const suppressedCount = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `SELECT count(*) AS n FROM ${ctx.audienceTableName} WHERE suppressed = true`,
+  mode: 'raw',
+})
+if (typeof suppressedCount.data === 'string') {
+  throw new Error('expected the JSON envelope, got a CSV string')
+}
+const countPage = suppressedCount.data
+if (!Array.isArray(countPage.data) || !Array.isArray(countPage.data[0])) {
+  throw new Error('executeSql data is not an array-of-arrays')
+}
+if (countPage.meta.columns[0] !== 'n') {
+  throw new Error(`unexpected column list: ${JSON.stringify(countPage.meta.columns)}`)
+}
+if (Number(countPage.data[0][0]) < 1) {
+  throw new Error('at least one end customer is suppressed — §035 ingested one')
+}
+
+const csvExport = await api.datalakes.executeSql(
+  tenantSlug,
+  datalakeSlug,
+  {
+    sql: `SELECT end_customer_id, bucket, suppressed FROM ${ctx.audienceTableName} ORDER BY end_customer_id`,
+    mode: 'raw',
+  },
+  { format: 'csv' },
+)
+if (typeof csvExport.data !== 'string') {
+  throw new Error('expected a CSV string for { format: "csv" }')
+}
+if (!csvExport.data.includes('end_customer_id') || !csvExport.data.includes(ctx.adaId)) {
+  throw new Error(`unexpected CSV body: ${JSON.stringify(csvExport.data.slice(0, 200))}`)
+}
+```
+
+# Outcome
+
+The marketing tenant exists with one raw datalake, an SMS tool, an LLM
+tool, a lead-submissions table, and an agent-driven workflow that bands
+every inbound lead and fans out to exactly one of four SMS actions.
+
+Running this walk again reuses all of it.
+
+# See also
+
+- `datalakes.md` — the create body, and what a derived pair would add
+- `workflows.md` — scheduling versus firing, and the accessor tables
+- `ai_agents.md` — response schemas, and why the enum is the real guard
+- `generic_tables.md` — the default client you never have to create