@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

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

@@ -0,0 +1,761 @@
+---
+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',
+  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 scheduling it, so the run reaches a
+terminal status on its own — poll `batchLogs.refresh` until it
+leaves `:pending`. 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,
+})
+ctx.runLogId = runResp.data.workflow_run_log_id!
+ctx.runBatchId = runResp.data.batch_id!
+
+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')
+}
+```
+
+# 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