@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/appointment-review-sms-workflow.md

@@ -1,801 +0,0 @@
----
-title: Send a patient review-request SMS after a fulfilled appointment
-summary: End-to-end standard workflow — provision a Review SMS workflow over the FHIR appointment dataset, ingest two CAHPS appointment rows (one fulfilled, one cancelled) through patient + appointment interop contracts, run the workflow so the status filter routes each row, and close the connected-app reply loop. No agent, no LLM.
-industry: healthcare
-slug: appointment-review-sms-workflow
-vitest_source:
-  - integration-tests/tests/healthcare/standard-workflow.test.ts
-  - integration-tests/tests/healthcare/interoperability-contracts.test.ts
-  - integration-tests/tests/healthcare/run-dac-single.test.ts
-  - integration-tests/tests/healthcare/create-dac.test.ts
-  - integration-tests/tests/healthcare/tools.test.ts
-  - integration-tests/tests/healthcare/data-sources.test.ts
-  - integration-tests/tests/healthcare/bootstrap.test.ts
-status: green
----
-
-# Problem
-
-A clinic wants to ask every patient for feedback after a visit —
-but only after a visit that actually happened. A cancelled
-appointment should never trigger a "how was your visit?" message.
-The classic implementation queries the appointments table on a
-nightly cron, filters on status, and hands each match to an SMS
-sender; the status logic, the scheduling, and the EMR field
-mapping all leak into application code.
-
-The Alvera platform's standard workflow primitive keeps all three
-inside the platform. A FHIR R4 `appointment` dataset is the
-workflow's event source; a pure-Liquid filter gates on
-`appointment.status == "fulfilled"`; a single SMS action carries
-a deep-link to a connected-app feedback form. The EMR-to-FHIR
-mapping is a separate concern owned by the interoperability
-contracts that ingest the rows — the workflow sees only the
-canonical `appointment.status`, never the vendor's raw
-`appt_slot_status` string.
-
-This cookbook walks the **whole** scenario, not just the
-provisioning: it creates the workflow, ingests two CAHPS-shaped
-appointment rows through the production data-activation chain
-(one checked-out, one cancelled), runs the workflow so the filter
-routes each row, 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/healthcare/standard-workflow.test.ts`
-— a green end-to-end test (§1–§6) that exercises this exact shape.
-This cookbook is a prose re-presentation of what that test walks.
-The setup file `_setup/healthcare.md` already provisioned the
-tenant, datalake, and industry-admin client; this cookbook starts
-from there.
-
-# Composition
-
-| Resource provisioned               | Owner       |
-|-------------------------------------|-------------|
-| SMS tool (SNS-backed)               | build       |
-| Review SMS connected app            | build       |
-| Review SMS workflow                 | build       |
-| Athenahealth data source            | build       |
-| Manual Upload tool                  | build       |
-| CAHPS Patient interop contract      | build       |
-| CAHPS Appointment interop contract  | build       |
-| Manual-upload DAC                   | build       |
-
-The setup file `_setup/healthcare.md` already provisioned the
-tenant + datalake + tenant-scoped client; this cookbook starts
-from there.
-
-# Walkthrough
-
-## 001 — create the SMS tool
-
-The Review SMS workflow's 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 Review SMS 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 Review SMS connected app
-
-The workflow's SMS action carries a deep-link to a connected-app
-page so the patient can complete the feedback form. 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 Review SMS Form ${runSuffix}`,
-  description: 'Patient-review form linked from outbound SMS — used by the Review SMS workflow.',
-  mode: 'self_hosted',
-  urls: [
-    {
-      url: 'https://review.example.local',
-      is_primary: true,
-      label: 'production',
-    },
-  ],
-})
-connectedAppId = connectedAppResp.data.id!
-ctx.connectedAppSlug = connectedAppResp.data.slug!
-```
-
-## 003 — create the Review SMS workflow
-
-The workflow has the standard shape: a filter (Liquid; passes
-appointments whose `status` is `fulfilled`), a decision (a literal
-Liquid array naming one decision key), and one SMS action. The SMS
-body references `{{ connected_app_form_url }}` — the platform
-injects that variable at action-execution time after minting the
-connected-app page token, so §014 can resolve the deep-link.
-
-Two details distinguish this workflow from a generic-table one.
-First, `dataset_type: 'appointment'` with `skip_mdm_resolution:
-false` means the workflow resolves each appointment's patient via
-MDM, so the SMS `to` and body templates can read
-`mdm_output.regulated_patient`. Second, a `context_datasets` entry
-queries the `message` dataset for any review SMS already sent to
-this patient in the last six months — the platform's built-in
-guard against re-pestering a patient. On a fresh tenant that
-lookup returns empty, which is harmless.
-
-```typescript
-const FILTER_BODY = '{% if appointment.status == "fulfilled" %}true{% endif %}'
-const DECISION_KEY = 'send_appointment_review_sms'
-const DECISION_BODY = `["${DECISION_KEY}"]`
-const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
-const SMS_TO_TEMPLATE =
-  '{{ mdm_output.regulated_patient.telecom | where: "system", "phone" | first | map: "value" | e164 }}'
-const SMS_BODY_TEMPLATE =
-  'Hi {{ mdm_output.regulated_patient.name | first | map: "given" | first }}, ' +
-  'thank you for your recent visit. ' +
-  'Please share your feedback at {{ connected_app_form_url }}'
-
-const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Review SMS Workflow ${runSuffix}`,
-  description: 'Sends a review-request SMS with a connected-app form link after a fulfilled appointment.',
-  dataset_type: 'appointment',
-  status: 'live',
-  tags: ['appointments', 'review'],
-  skip_mdm_resolution: false,
-  filter_config: {
-    type: 'custom',
-    body: FILTER_BODY,
-    output_schema: { type: 'boolean' },
-  },
-  decision_config: {
-    type: 'custom',
-    body: DECISION_BODY,
-    output_schema: DECISION_OUTPUT_SCHEMA,
-  },
-  context_datasets: [
-    {
-      dataset_type: 'message',
-      where_clause:
-        `rm.patient_id = '{{ patient_id }}' AND rm.decision_key = '${DECISION_KEY}' ` +
-        "AND rm.sent_at > NOW() - INTERVAL '6 months'",
-      limit: 1,
-      position: 0,
-    },
-  ],
-  actions: [
-    {
-      action_type: 'sms',
-      tool_id: toolId,
-      decision_key: DECISION_KEY,
-      position: 0,
-      trigger_template: 'now',
-      idempotency_template:
-        '{{ patient_id }}-{{ appointment.unregulated_appointment_id }}-{{ decision_key }}',
-      connected_app_id: connectedAppId,
-      connected_app_route: '/forms/review',
-      connected_app_metadata_template:
-        '{"appointment_id":"{{ appointment.unregulated_appointment_id }}","patient_id":"{{ mdm_output.patient.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 athenahealth 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
-CAHPS templates render onto the FHIR identifier `system` URN.
-
-```typescript
-const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Athenahealth Source ${runSuffix}`,
-  uri: '12345.athenahealth.com',
-  description: 'Athenahealth EMR — origin of the CAHPS appointment rows the Review SMS 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 CAHPS appointment 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 CAHPS Patient interoperability contract
-
-A CAHPS appointment row carries both patient and appointment
-facts. The patient interoperability contract maps the row into a
-FHIR R4 `Patient` upsert; this cookbook loads the production CAHPS
-patient + MDM templates from the vendored fixtures directory
-rather than inlining several hundred lines of Liquid.
-
-Two template slots matter. `template_config` shapes the FHIR
-Patient resource. `mdm_input_config` shapes the MDM input — the
-identifiers, name, and demographics the platform's master-data
-resolution keys on to decide whether this is a new patient or an
-existing one.
-
-The `filter_template` uses the CAHPS pipeline's parent-row guard.
-Its semantics are inverted from a naive reading: a template that
-renders **empty** means the row **passes**. `{% unless prnt_apptyn
-== 'Y' %}true{% endunless %}` renders empty exactly when
-`prnt_apptyn == 'Y'`, so only parent (canonical) appointment rows
-flow through — the child rows the CAHPS export duplicates are
-skipped.
-
-```typescript
-const { readFileSync } = await import('node:fs')
-const { join } = await import('node:path')
-const patientTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'healthcare/_cahps_appointments_healthcare_patient.liquid'),
-  'utf8',
-)
-const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'healthcare/_cahps_appointments_healthcare_mdm.liquid'),
-  'utf8',
-)
-
-const PARENT_APPOINTMENT_FILTER =
-  "{% unless msg.row.prnt_apptyn == 'Y' or msg.row.prnt_apptyn == 'y' %}true{% endunless %}"
-
-const patientContractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook CAHPS Patient Contract ${runSuffix}`,
-  description: 'CAHPS appointments → FHIR R4 Patient (custom Liquid + MDM input).',
-  resource_type: 'patient',
-  filter_template: PARENT_APPOINTMENT_FILTER,
-  template_config: { type: 'custom', body: patientTemplate },
-  mdm_input_config: { type: 'custom', body: mdmTemplate },
-  generic_table_id: null,
-})
-interopContractId = patientContractResp.data.id!
-```
-
-## 007 — create the CAHPS Appointment interoperability contract
-
-The appointment contract maps the same CAHPS row into a FHIR R4
-`Appointment` upsert. Its `template_config` is the appointment
-template — the one that maps the vendor's `appt_slot_status` string
-(`3 - checked out`, `x - cancelled`, …) onto the canonical FHIR
-`status` enum (`fulfilled`, `cancelled`, …) the workflow filter
-reads. It carries the same `mdm_input_config` as the patient
-contract so the appointment upsert can populate its `patient_id`
-foreign key from the resolved patient.
-
-The generator runs each numbered step as an isolated function, so
-this step re-reads the vendored templates rather than relying on
-§006's local variables.
-
-```typescript
-const { readFileSync } = await import('node:fs')
-const { join } = await import('node:path')
-const appointmentTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'healthcare/_cahps_appointments_healthcare_appointment.liquid'),
-  'utf8',
-)
-const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'healthcare/_cahps_appointments_healthcare_mdm.liquid'),
-  'utf8',
-)
-
-const PARENT_APPOINTMENT_FILTER =
-  "{% unless msg.row.prnt_apptyn == 'Y' or msg.row.prnt_apptyn == 'y' %}true{% endunless %}"
-
-const appointmentContractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook CAHPS Appointment Contract ${runSuffix}`,
-  description: 'CAHPS appointments → FHIR R4 Appointment (custom Liquid + MDM input).',
-  resource_type: 'appointment',
-  filter_template: PARENT_APPOINTMENT_FILTER,
-  template_config: { type: 'custom', body: appointmentTemplate },
-  mdm_input_config: { type: 'custom', body: mdmTemplate },
-  generic_table_id: null,
-})
-ctx.appointmentContractId = appointmentContractResp.data.id!
-```
-
-## 008 — create the manual-upload DAC
-
-The Data Activation Client binds the ingestion pieces — the
-manual-upload tool, the data source, and **both** interop
-contracts — into one ingestion endpoint. A single ingested CAHPS
-row fans out through both contracts: the patient contract upserts
-a `Patient`, the appointment contract upserts an `Appointment`
-linked to it. `tool_call.tool_call_type: 'manual_upload'` selects
-the inline-JSON ingest path. The server-derived `slug` is the
-handle §009 ingests rows against.
-
-```typescript
-const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook CAHPS DAC ${runSuffix}`,
-  description: 'Manual-upload DAC — fans each CAHPS row through the patient + appointment contracts.',
-  tool_id: ctx.manualUploadToolId,
-  data_source_id: dataSourceId,
-  tool_call: { tool_call_type: 'manual_upload' },
-  interoperability_contract_ids: [interopContractId, ctx.appointmentContractId],
-})
-dacId = dacResp.data.id!
-ctx.dacSlug = dacResp.data.slug!
-```
-
-## 009 — ingest two CAHPS appointment rows
-
-Two rows, ingested as inline JSON through the manual-upload DAC.
-Both are parent rows (`prnt_apptyn: 'Y'`) so the contract filter
-passes them. They differ in one field that the workflow cares
-about: `appt_slot_status`. The first row is `3 - checked out`,
-which the appointment template maps to FHIR `status: fulfilled` —
-the workflow filter will pass it. The second is `x - cancelled`,
-mapped to `status: cancelled` — the filter must reject it.
-
-The fulfilled patient's mobile number is per-run unique so §013
-can find the exact SMS in LocalStack SNS. Each ingest call gets
-its own batch id; both are pinned for the run scope in §011.
-
-```typescript
-const phone7 = String(Date.now()).slice(-7).padStart(7, '0')
-ctx.fulfilledPhone = `+1555${phone7}`
-const fulfilledMobile = `555-${phone7.slice(0, 3)}-${phone7.slice(3)}`
-
-const fulfilledRow = {
-  appointment_id: `APPT-FUL-${runSuffix}`,
-  parent_appointment_id: `APPT-FUL-${runSuffix}`,
-  appt_date: '3/12/2026',
-  prnt_apptyn: 'Y',
-  appt_start_time: '2:30 PM',
-  appt_slot_duration: '45',
-  appt_slot_status: '3 - checked out',
-  appt_type: 'Annual wellness visit',
-  patient_id: `PT-FUL-${runSuffix}`,
-  enterprise_id: `PT-FUL-${runSuffix}`,
-  patient_name: 'Elena Rivera',
-  patientdob: '7/22/1950',
-  patient_mobile_no: fulfilledMobile,
-  patient_risk_level: 'medium',
-  svc_department: 'EASTSIDE',
-  rndrng_provider_id: '602',
-  rndrng_provider: 'Dr. Thomas Nguyen',
-}
-const cancelledRow = {
-  appointment_id: `APPT-CAN-${runSuffix}`,
-  parent_appointment_id: `APPT-CAN-${runSuffix}`,
-  appt_date: '3/14/2026',
-  prnt_apptyn: 'Y',
-  appt_start_time: '9:00 AM',
-  appt_slot_duration: '30',
-  appt_slot_status: 'x - cancelled',
-  appt_type: 'Follow-up consultation',
-  patient_id: `PT-CAN-${runSuffix}`,
-  enterprise_id: `PT-CAN-${runSuffix}`,
-  patient_name: 'Marcus Doyle',
-  patientdob: '1/15/1972',
-  patient_mobile_no: '555-100-2000',
-  patient_risk_level: 'low',
-  svc_department: 'WESTSIDE',
-  rndrng_provider_id: '714',
-  rndrng_provider: 'Dr. Aisha Bello',
-}
-
-const [fulfilledIngest, cancelledIngest] = await Promise.all([
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: fulfilledRow }),
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: cancelledRow }),
-])
-ctx.batchFulfilled = fulfilledIngest.data.batch_id!
-ctx.batchCancelled = cancelledIngest.data.batch_id!
-```
-
-## 010 — wait for both ingest batches to reach steady-state
-
-Ingestion is async — the DAC enqueues per-row jobs that drain
-through both contracts and merge into the regulated patient +
-appointment tables. Each CAHPS row produces two top-level DAC log
-rows (one per contract) with `rows_ingested >= 1`; cascade rows
-the appointment template emits for nested resources carry
-`rows_ingested = 0` and are filtered out. Poll the DAC's
-activation logs until both batches show their two top-level rows
-with a non-empty `output_files` array (the merged Parquet landed
-in object storage). Only then is it safe to run the workflow.
-
-```typescript
-const targetBatches = new Set([ctx.batchFulfilled, ctx.batchCancelled])
-const deadline = Date.now() + 120_000
-let greenCount = 0
-while (Date.now() < deadline) {
-  const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, ctx.dacSlug)
-  const ingestedByBatch: Record<string, number> = {}
-  for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
-    const b = row.batch_id
-    if (typeof b !== 'string' || !targetBatches.has(b)) continue
-    if (typeof row.rows_ingested !== 'number' || row.rows_ingested < 1) continue
-    const files = row.output_files
-    if (!Array.isArray(files) || files.length === 0) continue
-    ingestedByBatch[b] = (ingestedByBatch[b] ?? 0) + 1
-  }
-  greenCount = Object.values(ingestedByBatch).filter((n) => n >= 2).length
-  if (greenCount === targetBatches.size) break
-  await new Promise((r) => setTimeout(r, 2_000))
-}
-if (greenCount !== targetBatches.size) {
-  throw new Error(
-    `only ${greenCount}/2 appointment batches reached steady-state ` +
-      '(patient + appointment contracts both merged) within 120s',
-  )
-}
-```
-
-## 011 — run the workflow against the two batches
-
-`workflows.run` with `manual_override: false` evaluates the
-filter, so the `status == "fulfilled"` filter genuinely routes
-each row. The SQL where-clause scopes the run to exactly the two
-batches §009 ingested (`ra` is the regulated-appointments alias
-the run-query exposes).
-
-The SMS action's `trigger_template: 'now'` dispatches the action
-immediately rather than deferring it, so once the run fires it
-reaches a terminal status on its own — poll `batchLogs.refresh`
-until it leaves `:pending`. The run itself is still scheduled:
-`workflows.run` records it and returns, which is why the setup
-file's `ctx.waitForFiredRun` sits between the call and the log id. A `:partial` status is expected and fine here:
-one row passed and one was filtered.
-
-```typescript
-const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: `ra.batch_id IN ('${ctx.batchFulfilled}', '${ctx.batchCancelled}')`,
-  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() + 120_000
-let status: string | null = null
-while (Date.now() < deadline) {
-  const { data: log } = await api.workflows.batchLogs.refresh(tenantSlug, datalakeSlug, ctx.workflowSlug, ctx.runLogId)
-  status = log.status ?? null
-  if (status && status !== 'pending') break
-  await new Promise((r) => setTimeout(r, 2_000))
-}
-if (status === 'failed') throw new Error('workflow run reached :failed')
-if (!status || status === 'pending') {
-  throw new Error('workflow run did not leave :pending within 120s')
-}
-```
-
-## 012 — verify the filter routed: fulfilled passes, cancelled is filtered
-
-Each row produced a Workflow Execution Log. The fulfilled
-appointment passes the filter, so its WEL is `:executing` or
-`:completed`. The cancelled appointment 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
-appointment status.
-
-```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 cancelled appointment) — distribution ${JSON.stringify(byStatus)}`,
-  )
-}
-```
-
-## 013 — confirm the review 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. The SMS `to`
-template resolved the fulfilled patient's `patient_mobile_no`
-through the `e164` Liquid filter, so the recipient is the
-`+1555…` number §009 stamped onto that patient. Poll for a record
-whose body carries the rendered greeting — proof the workflow's
-stated business outcome (a review-request SMS) actually happened.
-
-```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.fulfilledPhone] ?? []
-    matched = records.find(
-      (m) => m.Message.includes('thank you for your recent visit') && m.Message.includes('Elena'),
-    )
-  }
-  if (!matched) await new Promise((r) => setTimeout(r, 500))
-}
-if (!matched) {
-  throw new Error(`no review-request SMS landed in LocalStack SNS for ${ctx.fulfilledPhone} within 30s`)
-}
-```
-
-## 014 — fire the action via workflows.execute for an introspectable WEL
-
-The §011 run dispatched the SMS (§013 proved it landed in SNS),
-but a run-created WEL schedules each action through a datetime
-slot — the rendered `message_body` is not surfaced on its
-action-execution-log. `workflows.execute` is the direct path: it
-fires one named action on one dataset row and the resulting WEL
-carries the fully-rendered message. `manual_override: true` is
-load-bearing — §011 already processed this appointment, so without
-the override the action's idempotency tuple would dedupe the
-re-fire.
-
-`workflows.execute` is addressed by the *unregulated* dataset id,
-so first resolve the fulfilled appointment's id via a dataset
-search scoped to its batch, then poll the execute WEL until it
-reaches `:completed`.
-
-```typescript
-const { data: us } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'appointment', {
-  search_query: `ra.batch_id = '${ctx.batchFulfilled}'`,
-})
-if (us.status !== 'completed') {
-  throw new Error(`appointment user-search status=${us.status} error=${us.error_message ?? '(none)'}`)
-}
-const { data: search } = await api.datasets.search(tenantSlug, datalakeSlug, 'appointment', {
-  userSearchId: us.id!,
-  dataAccessMode: 'unregulated',
-})
-const fulfilledAppointmentId = (search.data?.[0] as { id?: string } | undefined)?.id
-if (!fulfilledAppointmentId) {
-  throw new Error('fulfilled appointment not found via unregulated search')
-}
-
-const { data: execResp } = await api.workflows.execute(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  dataset_id: fulfilledAppointmentId,
-  decision_key: 'send_appointment_review_sms',
-  manual_override: true,
-})
-ctx.execWelId = 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.execWelId)
-  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(`execute WEL did not reach :completed (last status: ${welStatus})`)
-}
-```
-
-## 015 — resolve the connected-app deep-link and post tracking
-
-The action's SMS carries a `/t/<token>` shortlink minted from the
-action's `connected_app_id` + `connected_app_route`. Read the
-execute 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 patient 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.execWelId,
-  { 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/appointment-review',
-})
-if (resolved.route_path !== '/forms/review') {
-  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')
-}
-```
-
-## 016 — 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.
-const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: "ra.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 cancelled appointment is filtered, not failed** — §012
-  asserts the cancelled row's WEL is `:filtered`, a distinct
-  terminal status from `:failed`. A filtered row is a *correct*
-  outcome: the workflow looked at it, the `status == "fulfilled"`
-  filter rendered empty, and the platform recorded that the row
-  was intentionally skipped. No SMS action runs for a filtered row
-  — which is exactly the business rule (never ask for feedback on
-  a visit that did not happen).
-- **The contract filter's inverted semantics** — §006/§007 wire a
-  `filter_template` whose convention is "renders empty ⇒ row
-  passes". The CAHPS export emits both parent and child rows for
-  one logical appointment; `{% unless prnt_apptyn == 'Y' %}…`
-  keeps only the parent. A row with `prnt_apptyn` other than `Y`
-  is dropped at the contract layer and never reaches the
-  appointment table — a different rejection point from the
-  workflow filter in §012.
-- **The six-month recency guard** — §003's `context_datasets`
-  entry queries the `message` dataset for a prior review SMS to
-  the same patient. On this fresh tenant it returns empty, so the
-  action runs. On a tenant with history, a recent prior message
-  would make the action skip — the platform's built-in
-  anti-pestering guard, expressed as a context query rather than
-  application code.
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down created
-resources. The `_setup/healthcare.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 fifteen steps run green:
-
-- A healthcare tenant exists with a healthcare-domain datalake
-- An SMS tool, a Review SMS connected app, and a Review SMS
-  standard workflow (status `live`, `appointment` dataset) are
-  registered
-- An athenahealth data source, a Manual Upload tool, a CAHPS
-  Patient interop contract, a CAHPS Appointment interop contract,
-  and a manual-upload DAC form a working ingestion chain
-- Two appointments have been ingested through that chain — one
-  checked-out, one cancelled — each with its own resolved patient
-- Running the workflow routed them correctly: the fulfilled
-  appointment passed the filter and dispatched an SMS; the
-  cancelled appointment was `:filtered`
-- The dispatched SMS is observable in LocalStack SNS with the
-  rendered "thank you for your recent visit" greeting
-- The connected-app deep-link the SMS carried resolves, and
-  message tracking records the open + form-submit timestamps
-
-The business outcome — a review-request SMS sent to a patient
-after a fulfilled visit, with a working feedback link — is
-demonstrated end-to-end, not merely provisioned.
-
-# See also
-
-- `_setup/healthcare.md` — the inlined bootstrap that provisions
-  the tenant + datalake this cookbook starts from
-- `contact-us-triage-with-llm.md` — the agent-driven healthcare
-  cookbook; same SMS shape, an LLM agent 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/interoperability_contracts.md` — custom contract shape,
-  `template_config` vs `mdm_input_config`, the inverted
-  `filter_template` convention
-- `.agent/data_activation_clients.md` — data source → tool →
-  interop contract → DAC ingestion chain
-- `.agent/workflows.md` — standard workflow primitive (filter +
-  decision + actions), `context_datasets`, `workflows.run`
-- `.agent/cookbook/_fixtures/healthcare/` — the vendored CAHPS
-  patient / appointment / MDM Liquid templates §006–§007 load
-- `integration-tests/tests/healthcare/standard-workflow.test.ts` —
-  the anchor green test (§1–§6) these snippets are lifted from
-- `integration-tests/tests/healthcare/interoperability-contracts.test.ts`,
-  `run-dac-single.test.ts`, `create-dac.test.ts`, `tools.test.ts`,
-  `data-sources.test.ts` — the per-resource create + ingest
-  snippets §004–§010 are lifted from