@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/birthday-greeting-sms-trigger.md

@@ -1,696 +0,0 @@
----
-title: Send a happy-birthday SMS on each contact's next birthday
-summary: End-to-end standard workflow — provision a pure-Liquid year-roll trigger workflow, ingest legal-entity rows through a manual-upload DAC, run the workflow, fast-forward the scheduled SMS via trigger_override, and close the connected-app reply loop. No agent, no LLM.
-industry: foundation
-slug: birthday-greeting-sms-trigger
-vitest_source:
-  - integration-tests/tests/foundation/standard-workflow.test.ts
-  - integration-tests/tests/foundation/data-sources.test.ts
-  - integration-tests/tests/foundation/tools.test.ts
-  - integration-tests/tests/foundation/interoperability-contracts.test.ts
-  - integration-tests/tests/foundation/create-dac.test.ts
-  - integration-tests/tests/foundation/bootstrap.test.ts
-status: green
----
-
-# Problem
-
-Most outbound customer-engagement systems handle the "send a
-greeting on the customer's birthday" use case with a cron job that
-queries the contacts table every morning and emits one task per
-match. That works but pulls the date-of-birth-matching logic into
-application code, splits scheduling between the cron window and the
-engagement system, and forces the operator to keep the cron in sync
-with timezone and feature-flag changes.
-
-The Alvera platform's standard workflow primitive flips this: the
-workflow declares, in pure Liquid, when each contact's next birthday
-SMS should fire, and the platform schedules the action to dispatch at
-that moment. No cron, no application code computing the birthday
-year-roll, no drift between the source of truth and the scheduler.
-
-This cookbook walks the **whole** scenario, not just the provisioning:
-it creates the workflow, ingests legal-entity rows through the
-production data-activation chain, runs the workflow so the filter
-routes each row, fast-forwards the future-scheduled SMS via
-`trigger_override` so the dispatch is observable inside one sitting,
-and finally resolves the connected-app deep-link the SMS carries —
-closing the SMS → reply loop.
-
-The scenario is anchored to
-`platform/integration-tests/tests/foundation/standard-workflow.test.ts`
-— a green end-to-end test (§1–§12) that exercises this exact shape.
-This cookbook is a prose re-presentation of what that test walks.
-The setup file `_setup/foundation.md` already provisioned the tenant,
-datalake, and industry-admin client; this cookbook starts from there.
-
-# Composition
-
-| Resource provisioned             | Owner       |
-|----------------------------------|-------------|
-| SMS tool (SNS-backed)            | build       |
-| Birthday Greeting connected app  | build       |
-| Happy Birthday workflow          | build       |
-| Lead-form data source            | build       |
-| Manual Upload tool               | build       |
-| LegalEntity interop contract     | build       |
-| Manual-upload DAC                | build       |
-
-The setup file `_setup/foundation.md` already provisioned the tenant +
-datalake + tenant-scoped client; this cookbook starts from there.
-
-# Walkthrough
-
-## 001 — create the SMS tool
-
-The Happy Birthday workflow's scheduled action invokes an SMS tool.
-The tool's `body.tool_body_type: 'sns'` means it routes via AWS SNS;
-local dev points it at LocalStack on `http://localhost:4566` via
-`endpoint_url` so no real AWS credentials are needed. The
-`intent: 'sms'` tags this tool for workflow actions that send SMS
-(versus `data_exchange` for ingestion tools).
-
-```typescript
-const smsToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook SMS Tool ${runSuffix}`,
-  description: 'SNS-backed SMS dispatcher for the Happy Birthday workflow, wired to LocalStack.',
-  intent: 'sms',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  body: {
-    tool_body_type: 'sns',
-    auth_method: 'access_key',
-    region: 'us-east-1',
-    phone_number: '+15551234567',
-    endpoint_url: 'http://localhost:4566',
-    access_key_id: 'test',
-    secret_access_key: 'test',
-  },
-})
-toolId = smsToolResp.data.id!
-```
-
-## 002 — create the Birthday Greeting connected app
-
-The workflow's SMS action carries a deep-link to a connected-app page
-so the recipient can complete a follow-up form (a birthday photo
-upload, an event RSVP — whichever the operator wires up). The
-connected app is a thin registration of the form's URL and mode; the
-actual page is hosted outside the platform (`mode: 'self_hosted'`).
-The server-derived `slug` is captured for the resolve-page call in
-§014.
-
-```typescript
-const connectedAppResp = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Birthday Greeting Form ${runSuffix}`,
-  description: 'Birthday-greeting form linked from outbound SMS — used by the Happy Birthday workflow.',
-  mode: 'self_hosted',
-  urls: [
-    {
-      url: 'https://birthday.example.local',
-      is_primary: true,
-      label: 'production',
-    },
-  ],
-})
-connectedAppId = connectedAppResp.data.id!
-ctx.connectedAppSlug = connectedAppResp.data.slug!
-```
-
-## 003 — create the Happy Birthday workflow
-
-The workflow has the standard shape: a filter (Liquid; passes
-legal entities whose `date_of_birth` is non-null), a decision (a
-literal Liquid array naming one decision key), and one SMS action
-whose `trigger_template` computes the next birthday in pure Liquid via
-year-roll math. The trigger template is the heart of the cookbook —
-by branching on whether today's MM-DD has passed the contact's DoB's
-MM-DD, it always renders the upcoming birthday whether it falls this
-year or next.
-
-The SMS body references `{{ connected_app_form_url }}` — the platform
-injects that variable at action-execution time after minting the
-connected-app page token. Without the reference the `/t/<token>`
-deep-link is minted but never lands in the rendered body, so §014
-(resolve the deep-link) could not close the SMS → reply loop.
-
-```typescript
-const FILTER_BODY =
-  '{% if mdm_output.regulated_legal_entity.date_of_birth %}true{% endif %}'
-const DECISION_KEY = 'send_happy_birthday_sms'
-const DECISION_BODY = `["${DECISION_KEY}"]`
-const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
-const TRIGGER_TEMPLATE =
-  '{% assign year = "" | now | date: "%Y" %}' +
-  '{% assign today_mmdd = "" | now | date: "%m-%d" %}' +
-  '{% assign dob_mmdd = mdm_output.regulated_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 SMS_TO_TEMPLATE =
-  '{{ mdm_output.regulated_legal_entity.phone_numbers | first | map: "phone_number" }}'
-const SMS_BODY_TEMPLATE =
-  'Happy birthday {{ mdm_output.regulated_legal_entity.first_name }}! \u{1F382}' +
-  ' Share a photo: {{ connected_app_form_url }}'
-
-const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Happy Birthday Workflow ${runSuffix}`,
-  description: "Sends a happy-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: FILTER_BODY,
-  },
-  decision_config: {
-    type: 'custom',
-    body: DECISION_BODY,
-    output_schema: DECISION_OUTPUT_SCHEMA,
-  },
-  actions: [
-    {
-      action_type: 'sms',
-      tool_id: toolId,
-      decision_key: DECISION_KEY,
-      position: 0,
-      trigger_template: TRIGGER_TEMPLATE,
-      idempotency_template:
-        '{{ subject_id }}-{{ workflow_id }}-{{ action_id }}',
-      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: SMS_TO_TEMPLATE },
-        body: { type: 'custom', body: SMS_BODY_TEMPLATE },
-        sms_type: 'transactional',
-      },
-    },
-  ],
-})
-workflowId = workflowResp.data.id!
-ctx.workflowSlug = workflowResp.data.slug!
-```
-
-## 004 — create the lead-form data source
-
-A workflow runs on rows; rows arrive through the data-activation
-chain. The chain's first link is a `DataSource` — a registration of
-where the rows originate. The `uri` is the system-of-record address;
-it flows into each ingested row's `source_uri`, which the
-legal-entity dedupe keys on alongside the contact's email.
-
-```typescript
-const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Lead Form Source ${runSuffix}`,
-  uri: 'https://app.alvera.ai',
-  description: 'Inbound lead-capture form — origin of the legal-entity rows the birthday workflow runs on.',
-  status: 'active',
-  is_default: false,
-})
-dataSourceId = dataSourceResp.data.id!
-```
-
-## 005 — create the Manual Upload tool
-
-The Data Activation Client needs a tool. For inline-JSON ingest a
-`manual_upload` tool is the minimal choice — `intent: 'data_exchange'`
-distinguishes it from the SMS tool, and `tool_body_type: 'manual_upload'`
-needs no endpoint or credential wiring (the rows arrive in the ingest
-call body, not by the tool fetching them).
-
-```typescript
-const manualUploadToolResp = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Manual Upload Tool ${runSuffix}`,
-  description: 'Manual-upload data-exchange tool — backs the DAC that ingests legal-entity rows.',
-  intent: 'data_exchange',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  data_source_id: dataSourceId,
-  body: { tool_body_type: 'manual_upload' },
-})
-ctx.manualUploadToolId = manualUploadToolResp.data.id!
-```
-
-## 006 — create the LegalEntity interoperability contract
-
-The interoperability contract is the row-shaping rule: a Liquid
-template that maps an inbound lead-form row into a `LegalEntity`
-upsert. This cookbook loads the production Foundation Airflow
-lead-form template from the vendored fixtures directory rather than
-inlining several hundred lines of Liquid. `mdm_input_config: 'null'`
-means the contract performs no MDM resolution of its own — the
-legal entity is upserted directly, keyed by its email digital
-identifier.
-
-The template renders the optional `date_of_birth` and `phone_numbers`
-fields when the inbound row carries them; that is what lets §003's
-has-DoB filter and the year-roll trigger have something to read.
-
-```typescript
-const { readFileSync } = await import('node:fs')
-const { join } = await import('node:path')
-const leTemplate = readFileSync(
-  join(
-    process.env.COOKBOOK_FIXTURES_DIR!,
-    'foundation/_lead_submissions_foundation_legal_entity.liquid',
-  ),
-  'utf8',
-)
-
-const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Lead Form to LegalEntity ${runSuffix}`,
-  description: 'Foundation Airflow 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,
-})
-interopContractId = contractResp.data.id!
-```
-
-## 007 — create the manual-upload DAC
-
-The Data Activation Client binds the three preceding pieces — the
-manual-upload tool, the data source, and the interop contract — into
-one ingestion endpoint. `tool_call.tool_call_type: 'manual_upload'`
-selects the inline-JSON ingest path. The server-derived `slug` is the
-handle §008 ingests rows against.
-
-```typescript
-const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Lead Form DAC ${runSuffix}`,
-  description: 'Manual-upload DAC — ingests lead-form rows into LegalEntity via the interop contract.',
-  tool_id: ctx.manualUploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [interopContractId],
-})
-dacId = dacResp.data.id!
-ctx.dacSlug = dacResp.data.slug!
-```
-
-## 008 — ingest two legal-entity rows
-
-Two rows, ingested as inline JSON through the manual-upload DAC. One
-carries a `date_of_birth` (MM-DD of tomorrow, year stamped 30 years
-back so the past-date guard on the LegalEntity changeset is
-satisfied) — the workflow filter will pass it. The other omits
-`date_of_birth` entirely — the filter must reject it. Each ingest
-call gets its own batch id; both are pinned for the run scope in
-§010.
-
-Tomorrow's MM-DD is deliberate: §012 fast-forwards the SMS via
-`trigger_override`, and a *future* scheduled time is what makes the
-fast-forward observable (a birthday-today row renders a past time and
-would dispatch regardless).
-
-```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
-const phoneDigits = String(Date.now()).slice(-7).padStart(7, '0')
-ctx.birthdayPhone = `+1555${phoneDigits}`
-
-const birthdayRow = {
-  submission_id: `BD-${runSuffix}`,
-  name: 'Maria Birthday',
-  email: `maria-bd-${runSuffix}@example.com`,
-  phone: ctx.birthdayPhone,
-  company: '',
-  message: 'My birthday is tomorrow',
-  lead_source: 'cookbook_birthday',
-  source_uri: 'https://app.alvera.ai',
-  date_of_birth: `${dobYear}-${tomorrowMM}-${tomorrowDD}`,
-}
-const noDobRow = {
-  submission_id: `NODOB-${runSuffix}`,
-  name: 'Priya NoDob',
-  email: `priya-nodob-${runSuffix}@example.com`,
-  phone: `+1556${phoneDigits}`,
-  company: '',
-  message: 'I have no DoB on file',
-  lead_source: 'cookbook_birthday',
-  source_uri: 'https://app.alvera.ai',
-  // date_of_birth intentionally absent — the workflow filter must reject this row
-}
-
-const [birthdayIngest, noDobIngest] = await Promise.all([
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: birthdayRow }),
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: noDobRow }),
-])
-ctx.batchBirthday = birthdayIngest.data.batch_id!
-ctx.batchNoDob = noDobIngest.data.batch_id!
-```
-
-## 009 — wait for both ingest batches to reach steady-state
-
-Ingestion is async — the DAC enqueues per-row jobs that the
-`BatchMergeWorker` drains into `legal_entities`. Poll the DAC's
-activation logs until both batches show a `legal_entities` row with
-`dataset_updated >= 1` and a non-empty `output_files` array (the
-merged Parquet landed in object storage). Only then is it safe to run
-the workflow against these rows.
-
-```typescript
-const targetBatches = new Set([ctx.batchBirthday, ctx.batchNoDob])
-const deadline = Date.now() + 90_000
-let greenCount = 0
-while (Date.now() < deadline) {
-  const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, ctx.dacSlug)
-  const green = new Set<string>()
-  for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
-    const b = row.batch_id
-    if (typeof b !== 'string' || !targetBatches.has(b)) continue
-    if (row.dataset_table !== 'legal_entities') continue
-    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 === targetBatches.size) break
-  await new Promise((r) => setTimeout(r, 1_000))
-}
-if (greenCount !== targetBatches.size) {
-  throw new Error(`only ${greenCount}/2 lead-row batches reached steady-state within 90s`)
-}
-```
-
-## 010 — run the workflow against the two batches
-
-`workflows.run` with `manual_override: false` evaluates the filter,
-so the has-DoB filter genuinely routes each row. The SQL where-clause
-scopes the run to exactly the two batches §008 ingested (`rle` is the
-regulated-legal-entities alias the run-query exposes).
-
-The batch run-log never reaches a terminal status — the birthday row's
-WEL holds a future-scheduled action and stays `:executing` for the
-life of the run. So this step polls on `total_wels` (every per-row job
-has produced a WEL) rather than waiting for the run to conclude.
-
-```typescript
-const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: `rle.batch_id IN ('${ctx.batchBirthday}', '${ctx.batchNoDob}')`,
-  mode: 'live',
-  manual_override: false,
-})
-// run-workflow only SCHEDULES the run. The log id and batch id are
-// written when it fires, so read them back via workflowRuns.get.
-const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
-ctx.runLogId = fired.workflowRunLogId
-ctx.runBatchId = fired.batchId!
-
-const deadline = Date.now() + 60_000
-let totalWels = 0
-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('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(`workflow run produced only ${totalWels}/2 WELs within 60s`)
-```
-
-## 011 — verify the filter routed: one passes, one is filtered
-
-Each row produced a Workflow Execution Log. The birthday row (has
-DoB) passes the filter, so its WEL is `:executing` (a future SMS
-action is scheduled) or `:completed`. The no-DoB row fails the
-filter, so its WEL is `:filtered`. A run where both passed — or both
-were filtered — would mean the filter is not actually evaluating; the
-old shallow version of this cookbook could never catch that because
-it never ran the workflow at all.
-
-```typescript
-const { data: wfLogs } = await api.workflows.workflowLogs.list(tenantSlug, datalakeSlug, ctx.workflowSlug)
-const ourWels = (wfLogs.data ?? []).filter(
-  (w) => (w as { batch_id?: string }).batch_id === ctx.runBatchId,
-)
-if (ourWels.length !== 2) {
-  throw new Error(`expected 2 WELs for the run, got ${ourWels.length}`)
-}
-
-const byStatus: Record<string, number> = {}
-for (const w of ourWels) {
-  const st = (w as { status?: string }).status ?? 'unknown'
-  byStatus[st] = (byStatus[st] ?? 0) + 1
-}
-const passCount = (byStatus.executing ?? 0) + (byStatus.completed ?? 0)
-if (passCount !== 1) {
-  throw new Error(`expected 1 pass-branch WEL, got ${passCount} — distribution ${JSON.stringify(byStatus)}`)
-}
-if ((byStatus.filtered ?? 0) !== 1) {
-  throw new Error(`expected 1 :filtered WEL (the no-DoB row) — distribution ${JSON.stringify(byStatus)}`)
-}
-```
-
-## 012 — fast-forward the scheduled SMS with trigger_override
-
-The birthday row's SMS action is scheduled for tomorrow 00:00 UTC —
-in the future, so it will not dispatch on its own inside this
-sitting. `workflows.execute` with `trigger_override: true` tells the
-platform to fast-forward the queued Oban job (`Oban.retry_job`
-promotes it to `:available`) so the SMS dispatches now. The
-`ActionExecutionLog` still records the year-roll-rendered
-`scheduled_at` — only the job is moved, which localises the override's
-blast radius.
-
-`workflows.execute` is addressed by `dataset_id` (the unregulated
-legal-entity id), so first resolve the birthday row's id via a
-dataset search scoped to its batch.
-
-```typescript
-const { data: us } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'legal_entity', {
-  search_query: `rle.batch_id = '${ctx.batchBirthday}'`,
-})
-if (us.status !== 'completed') {
-  throw new Error(`legal_entity user-search status=${us.status} error=${us.error_message ?? '(none)'}`)
-}
-const { data: search } = await api.datasets.search(tenantSlug, datalakeSlug, 'legal_entity', {
-  userSearchId: us.id!,
-  dataAccessMode: 'unregulated',
-})
-const birthdayLegalEntityId = (search.data?.[0] as { id?: string } | undefined)?.id
-if (!birthdayLegalEntityId) throw new Error('birthday row legal_entity not found via search')
-
-const { data: execResp } = await api.workflows.execute(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  dataset_id: birthdayLegalEntityId,
-  decision_key: 'send_happy_birthday_sms',
-  manual_override: true,
-  trigger_override: true,
-})
-ctx.forceExecWelId = execResp.workflow_execution_log_id!
-
-const deadline = Date.now() + 60_000
-let welStatus: string | null = null
-while (Date.now() < deadline) {
-  const { data: wel } = await api.workflows.workflowLogs.get(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.forceExecWelId)
-  welStatus = (wel as { status?: string }).status ?? null
-  if (welStatus && welStatus !== 'pending' && welStatus !== 'executing') break
-  await new Promise((r) => setTimeout(r, 2_000))
-}
-if (welStatus !== 'completed') {
-  throw new Error(`fast-forwarded WEL did not reach :completed (last status: ${welStatus})`)
-}
-```
-
-## 013 — confirm the SMS landed in LocalStack SNS
-
-The SMS tool publishes direct-to-phone-number via AWS SNS; LocalStack
-records every direct publish under `/_aws/sns/sms-messages` keyed by
-recipient phone. Poll the birthday row's phone for a record whose body
-carries the rendered greeting — proof the workflow's stated business
-outcome (a birthday SMS) actually happened, not just that the
-resources exist.
-
-```typescript
-const LOCALSTACK = 'http://localhost:4566'
-const deadline = Date.now() + 30_000
-let matched: { Message: string; PhoneNumber: string } | undefined
-while (Date.now() < deadline && !matched) {
-  const resp = await fetch(`${LOCALSTACK}/_aws/sns/sms-messages`)
-  if (resp.ok) {
-    const body = (await resp.json()) as {
-      sms_messages?: Record<string, Array<{ Message: string; PhoneNumber: string }>>
-    }
-    const records = body.sms_messages?.[ctx.birthdayPhone] ?? []
-    matched = records.find(
-      (m) => m.Message.includes('Happy birthday') && m.Message.includes('Maria'),
-    )
-  }
-  if (!matched) await new Promise((r) => setTimeout(r, 500))
-}
-if (!matched) {
-  throw new Error(`no "Happy birthday" SMS landed in LocalStack SNS for ${ctx.birthdayPhone} within 30s`)
-}
-```
-
-## 014 — resolve the connected-app deep-link and post tracking
-
-The dispatched SMS carries a `/t/<token>` shortlink minted from the
-action's `connected_app_id` + `connected_app_route`. Read the executed
-WEL in regulated mode to get the raw rendered `message_body`, extract
-the token, and resolve it via `connectedApps.resolvePage` — the
-`route_path` must match the action's `connected_app_route`. Posting
-`opened_at` + `form_submitted_at` via `updateMessageTracking` then
-mirrors what the connected-app frontend does when the recipient opens
-the page, closing the SMS → reply loop end-to-end.
-
-```typescript
-const { data: regulatedWel } = await api.workflows.workflowLogs.get(
-  tenantSlug,
-  datalakeSlug,
-  ctx.workflowSlug,
-  ctx.forceExecWelId,
-  { dataAccessMode: 'regulated' },
-)
-const aelWithBody = (regulatedWel.action_execution_logs ?? []).find(
-  (ael) => typeof ael.message_body === 'string' && ael.message_body.length > 0,
-)
-if (!aelWithBody?.message_body) {
-  throw new Error('no AEL message_body on the executed WEL')
-}
-const tokenMatch = aelWithBody.message_body.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!tokenMatch) {
-  throw new Error(`no /t/<token> in rendered SMS body: ${aelWithBody.message_body}`)
-}
-const shortPath = tokenMatch[1]!
-
-const { data: resolved } = await api.connectedApps.resolvePage(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: shortPath,
-  user_agent: 'cookbook-doctest/birthday-greeting',
-})
-if (resolved.route_path !== '/forms/birthday-greeting') {
-  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
-}
-
-const now = new Date().toISOString()
-const { data: tracked } = await api.connectedApps.updateMessageTracking(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: shortPath,
-  opened_at: now,
-  form_submitted_at: now,
-})
-if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
-  throw new Error('message tracking did not persist opened_at + form_submitted_at')
-}
-```
-
-## 015 — write the integration test
-
-End the build with a test you keep: re-read the workflow and prove the
-pipeline still executes — without a side effect. `mode: 'dry_run'` with a
-never-matching selection runs the FULL pipeline (selection → filter →
-decision) and intercepts only the final action call, so no message
-leaves, yet the acknowledgement proves the workflow is runnable. This
-block runs live under `make validate-cookbook`.
-
-```typescript
-// Re-GET — the workflow must still be live, or nothing will run.
-const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
-if (wfRow.status !== 'live') {
-  throw new Error(`workflow regressed from live: ${wfRow.status}`)
-}
-// Behavioural probe — a dry run against a selection no row can match:
-// the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the scheduled run id. The
-// clause must speak this workflow's selection dialect — the dataset
-// alias is `rle` here, the same alias the live run above uses.
-const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: "rle.batch_id = 'test-never-matching-batch'",
-  mode: 'dry_run',
-  manual_override: false,
-})
-// The run-log id does not exist until the run fires — wait, do not read a null.
-const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
-if (probeFired.workflowRunLogId.length === 0) {
-  throw new Error('dry-run probe never produced a workflow_run_log_id')
-}
-```
-
-If the probe fails in production, escalate with the run response as
-evidence — don't flip the workflow's status or rewrite its configs to
-chase the error.
-
-# Branches
-
-- **The no-DoB row is filtered, not failed** — §011 asserts the no-DoB
-  row's WEL is `:filtered`, a distinct terminal status from `:failed`.
-  A filtered row is a *correct* outcome: the workflow looked at it,
-  the has-DoB filter rendered empty, and the platform recorded that
-  the row was intentionally skipped. No SMS action is scheduled for a
-  filtered row.
-- **trigger_override deferred vs immediate** — §012 uses
-  `trigger_override: true` to fast-forward the SMS. With
-  `trigger_override: false` (the default) the same action stays
-  queued at its year-roll `scheduled_at` — the WEL settles at
-  `:executing` with a `:pending` action and no SMS dispatches inside
-  the test window. The anchor vitest's §8 covers that deferred branch
-  explicitly.
-- **Trigger fires this calendar year vs next** — the Liquid trigger
-  branches on `dob_mmdd >= today_mmdd`. If the contact's birthday this
-  year has already passed, the trigger renders the same month-day in
-  the next calendar year. Year-roll is implicit in the template;
-  there is no application code to audit.
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down created
-resources. The `_setup/foundation.md` setup file's runSuffix-scoped
-tenant / datalake / user names mean each run is naturally isolated;
-the seeded local DB is cheap to reset (`mix ecto.reset` on the
-platform repo).
-
-# Outcome
-
-After this cookbook's fourteen steps run green:
-
-- A foundation tenant exists with a foundation-domain datalake
-- An SMS tool, a Birthday Greeting connected app, and a Happy Birthday
-  standard workflow (status `live`, year-roll trigger) are registered
-- A data source, a Manual Upload tool, a LegalEntity interop contract,
-  and a manual-upload DAC form a working ingestion chain
-- Two legal entities have been ingested through that chain — one with
-  a date of birth, one without
-- Running the workflow routed them correctly: the dated row passed the
-  filter and scheduled an SMS; the undated row was `:filtered`
-- The scheduled SMS, fast-forwarded via `trigger_override`, **actually
-  dispatched** — it is observable in LocalStack SNS with the rendered
-  "Happy birthday" greeting
-- The connected-app deep-link the SMS carried resolves, and message
-  tracking records the open + form-submit timestamps
-
-The business outcome — a birthday SMS sent to a contact, with a
-working reply link — 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
-- `score-leads-with-llm-categorization.md` — the agent-driven
-  foundation cookbook; same SMS + ingestion shape, LLM in the decision
-- `.agent/tools.md` — SMS (`tool_body_type: sns`) and manual-upload
-  tool body shapes; intent classification
-- `.agent/connected_apps.md` — connected-app registration + the
-  resolve-page / message-tracking reply loop
-- `.agent/data_activation_clients.md` — data source → tool → interop
-  contract → DAC ingestion chain
-- `.agent/workflows.md` — standard workflow primitive (filter +
-  decision + actions), `workflows.run` vs `workflows.execute`, and
-  `trigger_override`
-- `.agent/ai_sandbox.md` — bounds on the Liquid sandbox the filter and
-  trigger templates execute inside
-- `.agent/cookbook/_fixtures/foundation/` — the vendored
-  lead-form LegalEntity Liquid template §006 loads
-- `integration-tests/tests/foundation/standard-workflow.test.ts` — the
-  anchor green test (§1–§12) these snippets are lifted from
-- `integration-tests/tests/foundation/data-sources.test.ts`,
-  `tools.test.ts`, `interoperability-contracts.test.ts`,
-  `create-dac.test.ts` — the per-resource create snippets §004–§007 are
-  lifted from