@alvera-ai/platform-sdk 0.17.0 → 0.18.0

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

@@ -1,1044 +0,0 @@
----
-title: Send an A/B marketing campaign across SMS and email
-summary: End-to-end campaign send over a generic-table audience — gate on suppression and reachability, split A/B inside the workflow's decision node, dispatch the chosen variant on both SMS and email in one run, carry a per-recipient short link, and re-attach the customer's reply to the customer who sent it. The gates and the split live in the workflow, not in app code.
-industry: foundation
-slug: marketing-campaign-send
-vitest_source:
-  - integration-tests/tests/foundation/marketing-campaign-send.test.ts
-status: green
----
-
-# Problem
-
-A marketing platform runs campaigns on behalf of the businesses it
-serves. Each business has a roster entry; each business has its own
-end customers. A campaign must contact an end customer only if they
-are **reachable** (a phone and an email on file) and **not
-suppressed** (no do-not-contact flag). Every message must carry a
-link unique to its recipient, so a click is attributable to one
-person. The content is **A/B split**. And when someone replies, the
-reply must attach to the customer who sent it.
-
-The classic implementation puts all four of those in application
-code: a query with a `WHERE NOT suppressed`, an `if` on the phone
-column, a random-number bucket, and a hand-rolled short-link table.
-Every one of them is a place for the campaign to leak — a suppressed
-customer contacted by the one code path that forgot the check.
-
-The Alvera platform keeps all four **inside the workflow**. The
-suppression and reachability gates are the `filter_config`. The A/B
-split is the `decision_config` — a decision node that returns the
-decision keys of the variant it chose. The per-recipient link is
-minted by the platform when it resolves the recipient's MDM subject.
-The reply re-attaches by re-ingesting through a data activation
-client. None of it is application code, and the gates cannot be
-bypassed by a caller who forgot them.
-
-This cookbook walks the whole journey: two generic tables (the
-business roster and the end-customer audience), the ingest that
-resolves each row to its own legal entity, a campaign workflow with
-four channel/variant actions, one run that sends two recipients and
-filters two, the short link resolving per recipient, and the inbound
-reply landing back on its customer.
-
-The scenario is anchored to
-`platform/integration-tests/tests/foundation/marketing-campaign-send.test.ts`
-— a green end-to-end test this cookbook is a prose re-presentation
-of. The setup file `_setup/foundation.md` already provisioned the
-tenant, the datalake, and the tenant-scoped client; this cookbook
-starts from there.
-
-# Composition
-
-| Resource provisioned                         | Owner    |
-|----------------------------------------------|----------|
-| Direct Customers generic table (the roster)   | build    |
-| End Customers generic table (the audience)    | build    |
-| Inbound Messages generic table                | platform |
-| Campaign data source                          | build    |
-| Manual Upload tool                            | build    |
-| Roster contracts + roster activation client   | build    |
-| Audience contracts + audience activation client | build  |
-| SMS tool (SNS-backed)                         | build    |
-| Email tool (`provider: 'mock'`)               | build    |
-| Campaign Booking Form connected app           | build    |
-| Loyalty Campaign workflow                     | build    |
-| Reply contract + reply activation client      | build    |
-
-Two things in that table are worth reading twice.
-
-`alvera_system_inbound_messages` is a **system** generic table. It
-ships with every foundation datalake — you do not create it, and §003
-proves it is already there.
-
-The datalake itself came from `_setup/foundation.md`, which gives it
-`timezone: 'America/New_York'`. The datalake timezone is a **closed
-whitelist of 8 US zones** — `America/New_York`, `America/Chicago`,
-`America/Denver`, `America/Los_Angeles`, `America/Anchorage`,
-`America/Adak`, `Pacific/Honolulu`, `America/Phoenix`. General IANA
-values are rejected, **including `UTC`**. The whitelist is the
-OpenAPI enum, so the generated `timezone` type carries exactly those
-eight and a wrong zone fails to compile rather than 422-ing at
-runtime.
-
-# Walkthrough
-
-## 001 — create the Direct Customers table (the business roster)
-
-The roster is the list of businesses running campaigns. It is a
-generic table because the platform does not model "the business my
-customer is" — that is domain data. The server derives the table
-`name` (`alvera_custom_direct_customers`); you set only the `title`.
-
-Nothing here is PII — a business name and its shared sender identity
-are public record — so every column is `privacy_requirement: 'none'`.
-
-```typescript
-const { data: roster } = await api.genericTables.create(tenantSlug, datalakeSlug, {
-  title: 'Direct Customers',
-  description: 'Direct customers — the businesses running marketing campaigns',
-  columns: [
-    { name: 'direct_customer_id', title: 'Direct Customer ID', type: 'string', description: 'Vendor-supplied unique direct-customer (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 sender number campaigns send SMS from', is_unique: false, privacy_requirement: 'none' },
-    { name: 'sender_domain', title: 'Sender Domain', type: 'string', description: 'Shared sender domain campaigns send email from', is_unique: false, privacy_requirement: 'none' },
-  ],
-})
-ctx.rosterTableId = roster.id!
-ctx.rosterTableName = roster.name!
-
-const deadline = Date.now() + 60_000
-let status: string | undefined
-while (Date.now() < deadline) {
-  const { data: row } = await api.genericTables.get(tenantSlug, datalakeSlug, ctx.rosterTableId)
-  status = row.status
-  if (status === 'deployed') break
-  await new Promise((r) => setTimeout(r, 1_000))
-}
-if (status !== 'deployed') {
-  throw new Error(`Direct Customers did not reach :deployed within 60s (last: ${status})`)
-}
-```
-
-## 002 — create the End Customers table (the audience)
-
-The audience is the people a campaign may contact. Three columns
-carry the whole business rule:
-
-`suppressed` is the do-not-contact flag — the workflow filter reads
-it, so a suppressed customer is unselectable by *any* campaign, not
-merely hidden in a UI. `phone` and `email` are the two channel
-destinations, and their presence is the reachability gate. `bucket`
-is the A/B assignment, an integer 0–99 stamped at ingest (§006) and
-split on by the decision node (§009).
-
-The three PII columns are `tokenize`; `suppressed` and `bucket` are
-`none` — they are campaign mechanics, not personal data, and the
-workflow must read them in the unregulated view.
-
-```typescript
-const { data: audience } = await api.genericTables.create(tenantSlug, datalakeSlug, {
-  title: 'End Customers',
-  description: 'End customers — 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: 'Direct customer (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 — email-channel destination', is_unique: false, privacy_requirement: 'tokenize' },
-    { name: 'phone', title: 'Phone', type: 'string', description: 'Recipient phone — 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' },
-  ],
-})
-ctx.audienceTableId = audience.id!
-ctx.audienceTableName = audience.name!
-
-const deadline = Date.now() + 60_000
-let status: string | undefined
-while (Date.now() < deadline) {
-  const { data: row } = await api.genericTables.get(tenantSlug, datalakeSlug, ctx.audienceTableId)
-  status = row.status
-  if (status === 'deployed') break
-  await new Promise((r) => setTimeout(r, 1_000))
-}
-if (status !== 'deployed') {
-  throw new Error(`End Customers did not reach :deployed within 60s (last: ${status})`)
-}
-```
-
-## 003 — find the Inbound Messages system table
-
-Replies land in `alvera_system_inbound_messages`. It is a **system**
-generic table: it ships with every foundation datalake, its `type` is
-`'system'` rather than `'custom'`, and **nobody creates it**. You find
-it by name in the table list.
-
-Trying to create it is the mistake this step exists to prevent — the
-name is reserved, and the physical table is already there.
-
-```typescript
-const { data: tables } = await api.genericTables.list(tenantSlug, datalakeSlug)
-const inbound = (tables.data ?? []).find((t) => t.name === 'alvera_system_inbound_messages')
-if (!inbound) {
-  throw new Error('alvera_system_inbound_messages must ship with every foundation datalake')
-}
-if (inbound.type !== 'system') {
-  throw new Error(`inbound messages table must be a system table, got type=${inbound.type}`)
-}
-ctx.inboundTableId = inbound.id!
-ctx.inboundTableName = inbound.name!
-```
-
-## 004 — create the campaign data source and the manual-upload tool
-
-Three activation clients follow — roster, audience, reply — and **all
-three share this one data source**. That is not a convenience; it is
-load-bearing.
-
-The data source's `uri` flows into every ingested row as
-`source_uri`, and the contracts render it onto the MDM identifier's
-`system`. The reply (§012) re-attaches by looking up
-`(system, handle)`. If the reply arrived through a *different* data
-source, its `system` would differ, the lookup would miss, and the
-reply would attach to nobody. One capture system, one `uri`, one
-identity namespace.
-
-```typescript
-const { ToolIntent } = await import('@alvera-ai/platform-sdk')
-
-const { data: source } = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Campaign Source ${runSuffix}`,
-  uri: 'crm.example.com',
-  description: 'Campaign CRM — origin of the roster, the audience, and the inbound replies.',
-  status: 'active',
-  is_default: false,
-})
-dataSourceId = source.id!
-
-const { data: uploadTool } = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Manual Upload Tool ${runSuffix}`,
-  description: 'Manual-upload data-exchange tool — backs the roster, audience, and reply clients.',
-  intent: ToolIntent.DATA_EXCHANGE,
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  data_source_id: dataSourceId,
-  body: { tool_body_type: 'manual_upload' },
-})
-ctx.uploadToolId = uploadTool.id!
-```
-
-## 005 — the roster contracts and the roster activation client
-
-Each roster row becomes **two** things: a row in the Direct Customers
-table, and a **business** legal entity in MDM. That takes two
-interoperability contracts on one client.
-
-The `legal_entity` contract shapes the MDM subject
-(`legal_entity_type: 'business'`). The `generic_table` contract shapes
-the table row — and its `mdm_input_config` is what tells the platform
-which subject this row belongs to. The platform then **stamps that
-subject's id onto the row** as `legal_entity_id`. That stamp is the
-whole point: §009's workflow resolves a row's MDM subject from the
-stamped FK, never from the row's own id.
-
-```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 }}"}
-  ],
-  "regulated_legal_entity": {
-    "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": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}", "type": "digital_identifier"}
-  ]
-}`
-
-const { data: rosterLe } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Roster Business LE ${runSuffix}`,
-  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' },
-})
-
-const { data: rosterGt } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Roster GT ${runSuffix}`,
-  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 },
-})
-interopContractId = rosterGt.id!
-
-const { data: rosterDac } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Roster Client ${runSuffix}`,
-  description: 'Business roster ingest — resolves each business to a business LegalEntity.',
-  tool_id: ctx.uploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [rosterLe.id!, rosterGt.id!],
-})
-ctx.rosterDacSlug = rosterDac.slug!
-```
-
-## 006 — the audience contracts and the audience activation client
-
-Same two-contract shape, with two differences that carry the
-campaign.
-
-First, each recipient resolves to an **individual** legal entity —
-their own MDM subject, keyed on their contact handle (phone if
-present, else email). That subject is what the per-recipient short
-link (§011) is minted against.
-
-Second, the generic-table contract assigns the **`bucket`**. It is
-derived from the last two digits of the vendor's own id
-(`| slice: -2, 2 | plus: 0`) — deterministic, not random. Re-ingest
-the same customer tomorrow and they land in the same bucket, so a
-re-ingest never re-rolls someone into the other variant mid-campaign.
-An A/B split that reshuffles on every ingest is not an A/B split.
-
-```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 }}"}
-  ],
-  "regulated_legal_entity": {
-    "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 %}
-    "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": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}", "type": "digital_identifier"}
-  ]
-}`
-
-const { data: audienceLe } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Audience LE ${runSuffix}`,
-  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' },
-})
-
-const { data: audienceGt } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Audience GT ${runSuffix}`,
-  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 },
-})
-
-const { data: audienceDac } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Audience Client ${runSuffix}`,
-  description: 'Audience ingest — resolves each recipient to an end-customer LegalEntity, assigns the A/B bucket.',
-  tool_id: ctx.uploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [audienceLe.id!, audienceGt.id!],
-})
-dacId = audienceDac.id!
-ctx.audienceDacSlug = audienceDac.slug!
-```
-
-## 007 — ingest the roster and the four recipients
-
-One business, four end customers, chosen so that one run exercises
-every branch of the campaign at once:
-
-| Recipient | phone | email | suppressed | bucket | expected |
-|-----------|-------|-------|------------|--------|----------|
-| Ada       | ✓     | ✓     | no         | 10     | sent, variant A |
-| Grace     | ✓     | ✓     | no         | 80     | sent, variant B |
-| Sup       | ✓     | ✓     | **yes**    | 31     | filtered (suppressed) |
-| Nophone   | —     | ✓     | no         | 42     | filtered (unreachable) |
-
-The buckets are not set by hand — they fall out of the ids
-(`…-10`, `…-80`, `…-31`, `…-42`), which is §006's Liquid at work.
-
-The read-back is the proof that MDM ran: every row 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 that pointed at the wrong customer.
-
-```typescript
-const p4 = String(Date.now()).slice(-4)
-ctx.adaPhone = `+1551${p4}`
-
-const rosterRow = {
-  direct_customer_id: `DC-${runSuffix}`,
-  business_name: 'Bloom Salon',
-  sender_phone: '+15550001111',
-  sender_domain: 'bloom-salon.example.com',
-}
-const audienceRows = [
-  { end_customer_id: `EC-${runSuffix}-10`, direct_customer_id: rosterRow.direct_customer_id, name: 'Ada Lovelace', email: `ada-${runSuffix}@example.com`, phone: ctx.adaPhone, suppressed: false },
-  { end_customer_id: `EC-${runSuffix}-80`, direct_customer_id: rosterRow.direct_customer_id, name: 'Grace Hopper', email: `grace-${runSuffix}@example.com`, phone: `+1552${p4}`, suppressed: false },
-  { end_customer_id: `EC-${runSuffix}-31`, direct_customer_id: rosterRow.direct_customer_id, name: 'Sup Pressed', email: `sup-${runSuffix}@example.com`, phone: `+1553${p4}`, suppressed: true },
-  { end_customer_id: `EC-${runSuffix}-42`, direct_customer_id: rosterRow.direct_customer_id, name: 'No Phone', email: `nophone-${runSuffix}@example.com`, phone: '', suppressed: false },
-]
-
-await api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.rosterDacSlug, { data: rosterRow })
-await Promise.all(
-  audienceRows.map((row) =>
-    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.audienceDacSlug, { data: row }),
-  ),
-)
-
-const deadline = Date.now() + 120_000
-let rows: Array<Record<string, unknown>> = []
-while (Date.now() < deadline && rows.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-${runSuffix}-%'`,
-    mode: 'unregulated',
-  })
-  if (typeof result !== 'string') {
-    rows = result.data.map((r) => Object.fromEntries(result.meta.columns.map((c, i) => [c, r[i]])))
-  }
-  if (rows.length < 4) await new Promise((r) => setTimeout(r, 2_000))
-}
-if (rows.length !== 4) {
-  throw new Error(`expected 4 audience rows within 120s, got ${rows.length}`)
-}
-
-const byId = new Map(rows.map((r) => [String(r.end_customer_id), r]))
-if (Number(byId.get(`EC-${runSuffix}-10`)!.bucket) !== 10) throw new Error('Ada must land in bucket 10')
-if (Number(byId.get(`EC-${runSuffix}-80`)!.bucket) !== 80) throw new Error('Grace must land in bucket 80')
-
-for (const row of rows) {
-  if (!row.legal_entity_id) {
-    throw new Error(`${row.end_customer_id} has no stamped subject — MDM did not resolve it`)
-  }
-}
-const subjects = new Set(rows.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(byId.get(`EC-${runSuffix}-10`)!.legal_entity_id)
-```
-
-## 008 — the two sender tools and the connected app
-
-**Two sender tools, not one.** An SMS number and an email identity
-are different assets, provisioned and billed separately, so they are
-separate tools — and §009's actions bind each channel to its own.
-
-The email tool uses `provider: 'mock'`, which delivers in-process to
-the dev mailbox at `/dev/mailbox` — no credentials, no provider
-account. Note **where** that lives: it is a field on the **tool body**,
-which is data on the tool row, not an environment variable. The same
-manifest therefore runs against any server; you are not asking the
-deployment to be in "test mode". Swap `mock` for `ses` and the same
-workflow sends real email.
-
-The connected app is the campaign's booking form. It is registered
-here, and §009's actions deep-link into it.
-
-```typescript
-const { ToolIntent } = await import('@alvera-ai/platform-sdk')
-
-const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Campaign SMS Sender ${runSuffix}`,
-  description: 'SNS-backed SMS dispatcher for the campaign, wired to LocalStack.',
-  intent: ToolIntent.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',
-  },
-})
-toolId = smsTool.id!
-
-const { data: emailTool } = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Campaign Email Sender ${runSuffix}`,
-  description: 'Campaign email dispatcher — the mock provider delivers to the dev mailbox.',
-  intent: ToolIntent.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',
-  },
-})
-ctx.emailToolId = emailTool.id!
-
-const { data: app } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Campaign Booking Form ${runSuffix}`,
-  description: 'Booking form the campaign links to.',
-  mode: 'self_hosted',
-  urls: [{ url: 'https://campaign.example.com', is_primary: true, label: 'production' }],
-})
-connectedAppId = app.id!
-ctx.connectedAppSlug = app.slug!
-```
-
-## 009 — the campaign workflow
-
-This is where all four rules live.
-
-**The gates are the filter.** `{% unless event_dataset.suppressed %}`
-is the suppression gate; the two non-empty checks are the
-reachability gate. A row that fails either is `:filtered` — looked
-at, and deliberately not contacted. There is no code path around it.
-
-**The split is the decision node.** It returns an *array of decision
-keys*, and it returns **both channel keys of the chosen variant**:
-bucket under 50 gets `["sms_variant_a","email_variant_a"]`, otherwise
-the B pair. The four actions each declare a `decision_key`; the
-platform runs the two whose keys came back and marks the other two
-`:skipped`. That is how one run sends one recipient on two channels
-with one variant — the pairing is data, not two workflows.
-
-**`skip_mdm_resolution: false` is set explicitly, and must be.** A
-generic-table row is never its own MDM subject; the subject is the
-one §006 stamped onto the row. 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, the token is never minted, and the link renders empty.
-
-`output_schema` is a JSON-Schema **object**. The string form is
-rejected with a 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 ROUTE = '/forms/campaign'
-const META = '{"end_customer_id":"{{ event_dataset.end_customer_id }}","name":"{{ event_dataset.name }}"}'
-const IDEMPOTENCY = '{{ event_dataset.end_customer_id }}/{{ action_id }}'
-
-const linkage = {
-  trigger_template: 'now',
-  idempotency_template: IDEMPOTENCY,
-  connected_app_id: connectedAppId,
-  connected_app_route: ROUTE,
-  connected_app_metadata_template: META,
-}
-
-const { data: workflow } = await api.workflows.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Loyalty Campaign ${runSuffix}`,
-  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, output_schema: { type: 'boolean' } },
-  decision_config: {
-    type: 'custom',
-    body: AB_DECISION,
-    output_schema: { type: 'array', items: { type: 'string' } },
-  },
-  actions: [
-    {
-      ...linkage,
-      action_type: 'sms', tool_id: toolId, 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: toolId, 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.emailToolId, 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.emailToolId, 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 },
-      },
-    },
-  ],
-})
-workflowId = workflow.id!
-ctx.workflowSlug = workflow.slug!
-
-if (workflow.skip_mdm_resolution !== false) {
-  throw new Error('a generic-table campaign workflow must keep MDM resolution ON')
-}
-if ((workflow.actions ?? []).length !== 4) {
-  throw new Error(`expected 4 actions, got ${(workflow.actions ?? []).length}`)
-}
-```
-
-## 010 — run the campaign once
-
-One pass over all four recipients. Both gates and the split run in
-the same run — the two reachable, un-suppressed recipients send; the
-suppressed one and the unreachable one are `:filtered`.
-
-The per-recipient action logs are the review surface. Each sending
-recipient's execution log carries **four** action logs — one per
-action — of which exactly **two completed and two skipped**, and the
-two that completed are the *same variant on both channels*. That is
-the A/B split and the two-channel send, read straight off the log:
-group the completed logs by `decision_key` and you have per-variant
-performance.
-
-```typescript
-const { data: run } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: `end_customer_id LIKE 'EC-${runSuffix}-%'`,
-  mode: 'live',
-  manual_override: false,
-})
-// run-workflow only SCHEDULES the run. The log id is written when it
-// fires, so read it back via workflowRuns.get.
-const fired = await ctx.waitForFiredRun(datalakeSlug, run.workflow_run_id)
-ctx.runLogId = fired.workflowRunLogId
-
-const deadline = Date.now() + 180_000
-let byStatus: Record<string, number> = {}
-while (Date.now() < deadline) {
-  const { data: log } = await api.workflows.batchLogs.refresh(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
-  if (log.status === 'failed') throw new Error('campaign run reached :failed')
-
-  const { data: batch } = await api.workflows.batchLogs.get(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
-  ctx.runBatchId = (batch as { batch_id?: string }).batch_id ?? ctx.runBatchId
-
-  const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
-  const ours = (wfLogs.data ?? []).filter((w) => (w as { batch_id?: string }).batch_id === ctx.runBatchId)
-  byStatus = {}
-  for (const wel of ours) {
-    const st = (wel as { status?: string }).status ?? 'unknown'
-    byStatus[st] = (byStatus[st] ?? 0) + 1
-  }
-  if ((byStatus.completed ?? 0) >= 2 && (byStatus.filtered ?? 0) >= 2) break
-  await new Promise((r) => setTimeout(r, 3_000))
-}
-if ((byStatus.completed ?? 0) !== 2 || (byStatus.filtered ?? 0) !== 2) {
-  throw new Error(`expected 2 completed + 2 filtered, got ${JSON.stringify(byStatus)}`)
-}
-
-const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
-const sent = (wfLogs.data ?? []).filter((w) => {
-  const wel = w as { batch_id?: string; status?: string }
-  return wel.batch_id === ctx.runBatchId && wel.status === 'completed'
-})
-
-for (const wel of sent) {
-  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 !== 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(', ')}`)
-  }
-}
-```
-
-## 011 — the per-recipient short link
-
-Every message the campaign rendered carries a `/t/<hash>` link. It is
-not one campaign link shared by everyone: the platform minted a page
-token against **this recipient's own MDM subject** — the one §006
-stamped and §009 resolved — so the click is attributable to one
-person.
-
-`resolvePage` exchanges the hash for the page, and
-`updateMessageTracking` stamps `opened_at`. Together they are the
-click: a recipient opened *this* message.
-
-```typescript
-const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
-  search_query: `rm.workflow_id = '${workflowId}'`,
-})
-if (userSearch.status !== 'completed') {
-  throw new Error(`message user-search status=${userSearch.status} error=${userSearch.error_message ?? '(none)'}`)
-}
-
-const deadline = Date.now() + 60_000
-let shortPath: string | undefined
-while (Date.now() < deadline && !shortPath) {
-  const { data: found } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
-    userSearchId: userSearch.id!,
-    dataAccessMode: 'regulated',
-  })
-  const bodies = ((found.data ?? []) as Array<Record<string, unknown>>).map((m) => String(m.body ?? ''))
-  const withLink = bodies.find((b) => b.includes('/t/'))
-  shortPath = withLink?.match(/\/t\/([A-Za-z0-9_-]+)/)?.[1]
-  if (!shortPath) await new Promise((r) => setTimeout(r, 2_000))
-}
-if (!shortPath) {
-  throw new Error('no rendered campaign message carried a /t/ short link within 60s')
-}
-ctx.shortPath = shortPath
-
-const { data: resolved } = await api.connectedApps.resolvePage(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: ctx.shortPath,
-  user_agent: 'cookbook-doctest/marketing-campaign-send',
-})
-if (resolved.route_path !== '/forms/campaign') {
-  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
-}
-
-const { data: tracked } = await api.connectedApps.updateMessageTracking(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: ctx.shortPath,
-  opened_at: new Date().toISOString(),
-})
-if (!tracked.message?.opened_at) {
-  throw new Error('message tracking did not persist opened_at')
-}
-```
-
-## 012 — the reply comes back, and attaches
-
-A reply arrives as an inbound message on the same handle the campaign
-sent to. It re-ingests through a reply activation client into the
-**system** inbound table, and its `mdm_input_config` keys on
-`(system, handle)` — the same namespace §006 wrote — so the platform
-resolves the handle straight back to the customer who replied and
-stamps their subject on the row.
-
-The client carries **only** a generic-table contract. It must not
-carry a legal-entity contract: a reply does not create a person, it
-finds one.
-
-**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 legal entities. The platform attaches the
-reply to one of them — the row always lands, never errors, never
-sits withheld — and marks it **`potential_duplicate`** for a human to
-adjudicate. Flag, don't block: a dropped reply is a lost customer,
-while a flagged one is a two-minute review.
-
-The duplicate is *detectable* rather than guessed at. Tokenization is
-stable per value, so duplicate handles group on the shared token with
-no regulated access at all — this is the query a detection client
-runs on a schedule, and what it finds is what sets the flag:
-
-```sql
-select (lei.id_number).token
-from legal_entity_identifications lei
-group by (lei.id_number).token
-having count(distinct lei.legal_entity_id) > 1
-```
-
-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 of the reply.
-
-```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": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}", "type": "digital_identifier"}
-  ]
-}`
-
-const { data: replyGt } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Reply GT ${runSuffix}`,
-  description: 'Inbound reply → Inbound Messages row, re-attached to the end 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 },
-})
-
-const { data: replyDac } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Reply Client ${runSuffix}`,
-  description: 'Inbound reply ingest — re-attaches the sender handle to its end-customer subject.',
-  tool_id: ctx.uploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [replyGt.id!],
-})
-
-const messageId = `IN-${runSuffix}`
-await api.dataActivationClients.ingest(tenantSlug, datalakeSlug, replyDac.slug!, {
-  data: { message_id: messageId, handle: ctx.adaPhone, channel: 'sms', body: 'Yes! Book me for Friday.' },
-})
-
-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 = '${messageId}'`,
-    mode: 'unregulated',
-  })
-  if (typeof result === 'string' || result.data.length === 0) return undefined
-  return Object.fromEntries(result.meta.columns.map((c, i) => [c, result.data[0][i]]))
-}
-
-const deadline = Date.now() + 120_000
-let reply: Record<string, unknown> | undefined
-while (Date.now() < deadline && !reply) {
-  reply = await readReply()
-  if (!reply) await new Promise((r) => setTimeout(r, 2_000))
-}
-if (!reply) throw new Error('the reply did not land in the inbound messages table within 120s')
-if (String(reply.legal_entity_id) !== ctx.adaSubjectId) {
-  throw new Error('the reply must re-attach to the end customer who sent it')
-}
-
-// Same message_id, flag set — the unique column makes this an upsert.
-await api.dataActivationClients.ingest(tenantSlug, datalakeSlug, replyDac.slug!, {
-  data: {
-    message_id: messageId,
-    handle: ctx.adaPhone,
-    channel: 'sms',
-    body: 'Yes! Book me for Friday.',
-    potential_duplicate: true,
-  },
-})
-
-const flagDeadline = Date.now() + 120_000
-let flagged: Record<string, unknown> | undefined
-while (Date.now() < flagDeadline) {
-  const row = await readReply()
-  if (row && row.potential_duplicate === true) {
-    flagged = row
-    break
-  }
-  await new Promise((r) => setTimeout(r, 2_000))
-}
-if (!flagged) throw new Error('the re-ingest did not flag the reply potential_duplicate within 120s')
-```
-
-## 013 — write the integration test
-
-End the build with a test you keep: re-read the workflow and prove the
-pipeline still executes — without a side effect. `mode: 'dry_run'` with a
-never-matching selection runs the FULL pipeline (selection → filter →
-decision) and intercepts only the final action call, so no message
-leaves, yet the acknowledgement proves the workflow is runnable. This
-block runs live under `make validate-cookbook`.
-
-```typescript
-// Re-GET — the workflow must still be live, or nothing will run.
-const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
-if (wfRow.status !== 'live') {
-  throw new Error(`workflow regressed from live: ${wfRow.status}`)
-}
-// Behavioural probe — a dry run against a selection no row can match:
-// the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the scheduled run id. The
-// clause speaks this workflow's selection dialect: a GENERIC-TABLE
-// audience is addressed by its own columns (no `ra.` dataset alias —
-// that alias exists only for system-dataset selections).
-const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: "end_customer_id = 'test-never-matching-customer'",
-  mode: 'dry_run',
-  manual_override: false,
-})
-// The run-log id does not exist until the run fires — wait, do not read a null.
-const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
-if (probeFired.workflowRunLogId.length === 0) {
-  throw new Error('dry-run probe never produced a workflow_run_log_id')
-}
-```
-
-If the probe fails in production, escalate with the run response as
-evidence — don't flip the workflow's status or rewrite its configs to
-chase the error.
-
-# Branches
-
-- **Suppressed and unreachable are `:filtered`, not `:failed`.** Both
-  are *correct* outcomes: the workflow looked at the row, a gate
-  rendered empty, and the platform recorded a deliberate skip. No
-  action runs for a filtered row, on any channel. The suppression
-  gate lives in workflow selection, so a suppressed customer is
-  unselectable by *any* campaign — not merely filtered out of one
-  UI's list.
-- **The variant pair, not the variant.** The decision node returns two
-  keys, so a recipient gets one variant across both channels. Return
-  one key and you would send SMS but not email. Return all four and
-  you would send both variants to the same person — which is why the
-  decision is a template over `bucket` and not a per-action condition.
-- **A re-ingest does not re-roll the bucket.** The bucket is derived
-  from the vendor id, so a customer re-ingested tomorrow keeps their
-  variant. Had it been random, a mid-campaign re-ingest would move
-  people between arms and the A/B result would be unreadable.
-- **The ambiguous reply attaches and is flagged.** It is never
-  withheld and never an error. §012's detection query is what finds
-  the ambiguity; the flag is what routes it to a human. The platform
-  does not silently pick a "best" match and hide the choice.
-- **`provider: 'mock'` is data, not a deploy mode.** It sits on the
-  tool row, so the same manifest runs anywhere; the tool — not the
-  environment — decides where email goes.
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down created
-resources. `_setup/foundation.md`'s runSuffix-scoped tenant / datalake
-/ user names mean each run is naturally isolated; the seeded local DB
-is cheap to reset (`mix ecto.reset` on the platform repo).
-
-# Outcome
-
-After this cookbook's twelve steps run green:
-
-- A business roster and an end-customer audience exist as generic
-  tables, and the foundation datalake's **system** inbound-messages
-  table was found, not created
-- One data source, one manual-upload tool, and three activation
-  clients (roster, audience, reply) share one identity namespace
-- Four recipients are ingested, each MDM-resolved to their **own**
-  legal entity, each carrying a **stable** A/B bucket derived from
-  their vendor id
-- A campaign workflow holds the suppression gate, the reachability
-  gate, and the A/B split — none of them in application code
-- One run sent two recipients on **both** SMS and email with the
-  variant their bucket chose, and filtered the suppressed and the
-  unreachable in the same pass
-- Every send carried a `/t/` link minted against that recipient's own
-  subject; resolving it and stamping `opened_at` records the click
-- A reply re-ingested on the sender's handle attached back to the
-  customer who sent it, and the duplicate-handle path flags rather
-  than blocks
-
-The business outcome — a compliant, attributable, A/B-split campaign
-that can be replied to — is demonstrated end-to-end, not merely
-provisioned.
-
-# See also
-
-- `_setup/foundation.md` — the inlined bootstrap that provisions the
-  tenant + datalake this cookbook starts from
-- `generic-tables.md` — the capability walk for generic tables:
-  columns, `privacy_requirement`, deploy, read back with SQL
-- `welcome-sms-for-customers.md` — the single-channel, no-split
-  sibling: one SMS action over a built-in dataset
-- `score-leads-with-llm-categorization.md` — a decision node driven by
-  an agent instead of a Liquid template
-- `.agent/workflows.md` — filter, decision node, actions,
-  `skip_mdm_resolution`, `workflows.run`
-- `.agent/tools.md` — SMS (`sns`) and email tool bodies; the email
-  `provider` values including `mock`
-- `.agent/connected_apps.md` — connected-app registration and the
-  resolve-page / message-tracking loop
-- `.agent/interoperability_contracts.md` — `template_config` vs
-  `mdm_input_config`, and how a subject gets stamped on a row
-- `.agent/data_activation_clients.md` — data source → tool → contract
-  → client ingestion chain
-- `.agent/datalakes.md` — the 8-zone timezone whitelist
-- `integration-tests/tests/foundation/marketing-campaign-send.test.ts`
-  — the anchor green test these snippets are lifted from