@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -1,661 +0,0 @@
----
-title: Send a KYC-notification SMS when a payment account becomes active
-summary: End-to-end standard workflow — provision a KYC-notification workflow over the payments payment_account dataset, ingest two Atomic FI payment-account rows (one active, one suspended) through a payment_account interop contract, run the workflow so the status filter routes each row, read the rendered SMS back from the message dataset, and close the connected-app reply loop. No agent, no LLM.
-industry: payments
-slug: kyc-notification-on-account-activation
-vitest_source:
-  - integration-tests/tests/payments/standard-workflow.test.ts
-  - integration-tests/tests/payments/interoperability-contracts.test.ts
-  - integration-tests/tests/payments/run-dac-single.test.ts
-  - integration-tests/tests/payments/create-dac.test.ts
-  - integration-tests/tests/payments/tools.test.ts
-  - integration-tests/tests/payments/data-sources.test.ts
-  - integration-tests/tests/payments/bootstrap.test.ts
-status: green
----
-
-# Problem
-
-When a payment account transitions to `active`, the risk-ops team
-wants to send the account holder a notification SMS with a link
-to a self-serve KYC portal — so they can complete or review their
-know-your-customer details. An account that is still `suspended`
-should never trigger that message.
-
-The classic implementation queries the payment-accounts table on
-a status-change hook, branches on the new status, and hands the
-active ones to an SMS sender — with the status gate living in
-application code.
-
-The Alvera platform's standard workflow primitive keeps that gate
-inside the platform. A payments `payment_account` dataset is
-the workflow's event source; a pure-Liquid filter gates on
-`payment_account.status == "active"`; a single SMS action carries
-a deep-link to a connected-app KYC portal. The
-activated-or-not decision is a one-line filter, not a code branch.
-
-This cookbook walks the **whole** scenario, not just the
-provisioning: it creates the workflow, ingests two Atomic FI-shaped
-payment-account rows through the production data-activation chain
-(one active, one suspended), runs the workflow so the filter
-routes each row, reads the rendered notification SMS back out of
-the message dataset, 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/payments/standard-workflow.test.ts`
-— a green end-to-end test (§1–§7) that exercises this exact shape.
-This cookbook is a prose re-presentation of what that test walks.
-The setup file `_setup/payments.md` already provisioned the
-tenant, datalake, and industry-admin client; this cookbook starts
-from there.
-
-# Composition
-
-| Resource provisioned                | Owner       |
-|--------------------------------------|-------------|
-| SMS tool (SNS-backed)                | build       |
-| KYC-portal connected app             | build       |
-| KYC-notification workflow            | build       |
-| Atomic FI data source                | build       |
-| Manual Upload tool                   | build       |
-| Atomic FI Payment Account interop contract | build |
-| Manual-upload DAC                    | build       |
-
-The setup file `_setup/payments.md` already provisioned the
-tenant + datalake + tenant-scoped client; this cookbook starts
-from there.
-
-# Walkthrough
-
-## 001 — create the SMS tool
-
-The KYC-notification 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 KYC-notification 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 KYC-portal connected app
-
-The workflow's SMS action carries a deep-link to a connected-app
-page so the account holder can open the self-serve KYC portal.
-The connected app is a thin registration of the portal'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 §013.
-
-```typescript
-const connectedAppResp = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook KYC Portal ${runSuffix}`,
-  description: 'Self-serve KYC portal linked from the outbound notification SMS.',
-  mode: 'self_hosted',
-  urls: [
-    {
-      url: 'https://kyc.example.local',
-      is_primary: true,
-      label: 'production',
-    },
-  ],
-})
-connectedAppId = connectedAppResp.data.id!
-ctx.connectedAppSlug = connectedAppResp.data.slug!
-```
-
-## 003 — create the KYC-notification workflow
-
-The workflow has the standard shape: a filter (Liquid; passes
-payment accounts whose `status` is `active`), a decision (a
-literal Liquid array naming one decision key), and one SMS
-action. The SMS body references the payment account's external id
-so the recipient knows which account activated, and
-`{{ connected_app_form_url }}` so the platform can bake in the
-`/t/<token>` KYC-portal link.
-
-`dataset_type: 'payment_account'` makes the payments payment
-account dataset the event source; the workflow context injects
-the payment account row under the `payment_account` key, so the
-filter reads `payment_account.status` directly. A
-`context_datasets` entry queries the `message` dataset for any
-KYC-notification SMS already sent to the same legal entity in the
-last six months — the platform's built-in guard against
-re-notifying. On a fresh tenant that lookup returns empty, which
-is harmless. The SMS `to` is a fixed inbox number because a
-payments legal entity's contact fields are tokenized and not
-resolved into the SMS templating context here.
-
-```typescript
-const FILTER_BODY = '{% if payment_account.status == "active" %}true{% endif %}'
-const DECISION_KEY = 'send_pr_notification_sms'
-const DECISION_BODY = `["${DECISION_KEY}"]`
-const DECISION_OUTPUT_SCHEMA = { type: 'array', items: { type: 'string' } }
-const SMS_BODY_TEMPLATE =
-  'Alvera PR notification — payment_account ' +
-  '{{ payment_account.payment_account_external_id }} has been activated. ' +
-  'Manage KYC: {{ connected_app_form_url }}'
-
-const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook KYC Notification Workflow ${runSuffix}`,
-  description: 'Sends a KYC-notification SMS for newly activated payment accounts with a self-serve KYC portal link.',
-  dataset_type: 'payment_account',
-  status: 'live',
-  tags: ['compliance', 'kyc'],
-  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.mdm_subject_id = '{{ payment_account.legal_entity_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: '{{ payment_account.id }}-{{ decision_key }}',
-      connected_app_id: connectedAppId,
-      connected_app_route: '/portal/kyc',
-      connected_app_metadata_template: '{"payment_account_id":"{{ payment_account.id }}"}',
-      tool_call: {
-        tool_call_type: 'sms_request',
-        to: { type: 'custom', body: '+15551234567' },
-        body: { type: 'custom', body: SMS_BODY_TEMPLATE },
-        sms_type: 'transactional',
-      },
-    },
-  ],
-})
-workflowId = workflowResp.data.id!
-ctx.workflowSlug = workflowResp.data.slug!
-```
-
-## 004 — create the Atomic FI 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 payment-account contract carries through to the resource.
-
-```typescript
-const dataSourceResp = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Atomic FI Source ${runSuffix}`,
-  uri: 'api.atomic.fi',
-  description: 'Atomic FI banking API — origin of the payment-account rows the KYC 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 Atomic FI payment-account 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 Atomic FI Payment Account interoperability contract
-
-The interoperability contract is the row-shaping rule: a Liquid
-template that maps an inbound Atomic FI payment-account row into a
-payments `PaymentAccount` upsert. This cookbook loads the
-production Atomic FI payment-account + MDM templates from the
-vendored fixtures directory rather than inlining the Liquid.
-
-Two template slots matter. `template_config` shapes the
-PaymentAccount resource — including PCI-sensitive fields
-(`account_number`, `iban`) the changeset tokenizes automatically.
-`mdm_input_config` shapes the MDM input — the `account_holder_id`
-the platform's master-data resolution keys on to find-or-create
-the LegalEntity + AccountHolder pair the payment account belongs
-to.
-
-```typescript
-const { readFileSync } = await import('node:fs')
-const { join } = await import('node:path')
-const paTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_payment_accounts_payments_payment_account.liquid'),
-  'utf8',
-)
-const mdmTemplate = readFileSync(
-  join(process.env.COOKBOOK_FIXTURES_DIR!, 'payments/_payment_accounts_payments_mdm.liquid'),
-  'utf8',
-)
-
-const contractResp = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
-  name: `Cookbook Atomic FI Payment Account Contract ${runSuffix}`,
-  description: 'Atomic FI payment-accounts → Payments PaymentAccount (custom Liquid + MDM input).',
-  resource_type: 'payment_account',
-  template_config: { type: 'custom', body: paTemplate },
-  mdm_input_config: { type: 'custom', body: mdmTemplate },
-  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 Atomic FI Payment Account DAC ${runSuffix}`,
-  description: 'Manual-upload DAC — ingests Atomic FI payment-account rows into PaymentAccount 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 Atomic FI payment-account rows
-
-Two rows, ingested as inline JSON through the manual-upload DAC.
-They differ in the field the workflow filter cares about:
-`status`. The first row is `active` — the filter will pass it.
-The second is `suspended` — the filter must reject it. Each row
-carries a distinct `account_holder_id` so MDM resolves each to its
-own legal entity. Each ingest call gets its own batch id; both are
-pinned for the run scope in §010.
-
-```typescript
-const activeRow = {
-  payment_account_external_id: `PA-ACTIVE-${runSuffix}`,
-  payment_account_number: `PA-NUM-A-${runSuffix}`,
-  account_holder_id: `AH-KYC-${runSuffix}-active`,
-  status: 'active',
-  account_type: 'bank_account',
-  currency: 'USD',
-  routing_number: '121000358',
-  swift_bic: 'BOFAUS3N',
-  bank_name: 'Bank of America',
-  enabled_regimes: ['us_domestic'],
-  source_uri: 'api.atomic.fi',
-}
-const suspendedRow = {
-  payment_account_external_id: `PA-SUSPENDED-${runSuffix}`,
-  payment_account_number: `PA-NUM-S-${runSuffix}`,
-  account_holder_id: `AH-KYC-${runSuffix}-suspended`,
-  status: 'suspended',
-  account_type: 'bank_account',
-  currency: 'USD',
-  routing_number: '121000358',
-  bank_name: 'Bank of America',
-  enabled_regimes: ['us_domestic'],
-  source_uri: 'api.atomic.fi',
-}
-
-const [activeIngest, suspendedIngest] = await Promise.all([
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: activeRow }),
-  api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dacSlug, { data: suspendedRow }),
-])
-ctx.batchActive = activeIngest.data.batch_id!
-ctx.batchSuspended = suspendedIngest.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 the regulated payment-account
-table. Poll the DAC's activation logs until both batches show a
-row with `rows_ingested >= 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.batchActive, ctx.batchSuspended])
-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 (typeof row.rows_ingested !== 'number' || row.rows_ingested < 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 payment-account 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 `payment_account.status` filter genuinely routes
-each row. The SQL where-clause scopes the run to exactly the two
-batches §008 ingested (`rpa` is the regulated-payment-account
-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: `rpa.batch_id IN ('${ctx.batchActive}', '${ctx.batchSuspended}')`,
-  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')
-}
-```
-
-## 011 — verify the filter routed: active passes, suspended is filtered
-
-Each row produced a Workflow Execution Log. The active payment
-account passes the filter, so its WEL is `:executing` or
-`:completed`. The suspended payment account 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
-`payment_account.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 suspended payment account) — distribution ${JSON.stringify(byStatus)}`,
-  )
-}
-```
-
-## 012 — read the rendered notification SMS back from the message dataset
-
-A `trigger_template: 'now'` action that passed the filter fires
-immediately and persists a row in the regulated `message`
-dataset, carrying the fully-rendered SMS body. Search that
-dataset scoped to this workflow, poll until the row appears, and
-extract the `/t/<token>` shortlink the platform baked into the
-body when it minted the connected-app page token.
-
-```typescript
-const { data: userSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
-  search_query: `rm.workflow_id = '${workflowId}'`,
-})
-if (userSearch.status !== 'completed') {
-  throw new Error(`message user-search status=${userSearch.status} error=${userSearch.error_message ?? '(none)'}`)
-}
-
-const deadline = Date.now() + 45_000
-let messages: Array<Record<string, unknown>> = []
-while (Date.now() < deadline && messages.length === 0) {
-  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
-    userSearchId: userSearch.id!,
-    dataAccessMode: 'regulated',
-  })
-  messages = (data.data ?? []) as Array<Record<string, unknown>>
-  if (messages.length === 0) await new Promise((r) => setTimeout(r, 1_000))
-}
-if (messages.length === 0) {
-  throw new Error('no KYC-notification SMS message persisted for the workflow within 45s')
-}
-
-const withLink = messages
-  .map((m) => String(m.body ?? ''))
-  .find((body) => body.includes('/t/') && body.includes('Alvera PR notification'))
-if (!withLink) {
-  throw new Error(`no rendered notification body with a /t/ link — bodies: ${JSON.stringify(messages.map((m) => m.body))}`)
-}
-const tokenMatch = withLink.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!tokenMatch) {
-  throw new Error(`no /t/<token> in rendered body: ${withLink}`)
-}
-ctx.kycShortPath = tokenMatch[1]!
-```
-
-## 013 — resolve the connected-app deep-link and post tracking
-
-The `/t/<token>` shortlink the SMS carries resolves 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 account holder opens the
-KYC portal, closing the SMS → reply loop end-to-end.
-
-```typescript
-const { data: resolved } = await api.connectedApps.resolvePage(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: ctx.kycShortPath,
-  user_agent: 'cookbook-doctest/kyc-notification',
-})
-if (resolved.route_path !== '/portal/kyc') {
-  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
-}
-if (!(resolved.message?.body ?? '').includes('Alvera PR notification')) {
-  throw new Error('resolved page message body missing the notification copy')
-}
-
-const now = new Date().toISOString()
-const { data: tracked } = await api.connectedApps.updateMessageTracking(tenantSlug, datalakeSlug, ctx.connectedAppSlug, {
-  short_path: ctx.kycShortPath,
-  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')
-}
-```
-
-## 014 — 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 `rpa` here, the same alias the live run above uses.
-const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
-  sql_where_clause: "rpa.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 suspended account is filtered, not failed** — §011
-  asserts the suspended payment account's WEL is `:filtered`, a
-  distinct terminal status from `:failed`. A filtered row is a
-  *correct* outcome: the workflow looked at it, the
-  `payment_account.status == "active"` filter rendered empty, and
-  the platform recorded the row as intentionally skipped. No SMS
-  runs for a filtered row — exactly the business rule (never send
-  a "your account is active" notification for an account that is
-  not).
-- **The bulk-batch variant** — the anchor vitest runs the whole
-  Atomic FI bulk batch in one go (three active rows and one
-  suspended) and asserts the same split: the active WELs route
-  past the filter, the suspended one records `:filtered`. This
-  cookbook walks the minimal two-row version; the polarity is
-  identical.
-- **The six-month recency guard** — §003's `context_datasets`
-  entry queries the `message` dataset for a prior KYC
-  notification to the same legal entity. 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-duplication guard, expressed as a
-  context query rather than application code.
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down created
-resources. The `_setup/payments.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 thirteen steps run green:
-
-- A payments tenant exists with a payments-domain
-  datalake
-- An SMS tool, a KYC-portal connected app, and a KYC-notification
-  standard workflow (status `live`, `payment_account` dataset)
-  are registered
-- An Atomic FI data source, a Manual Upload tool, an Atomic FI
-  Payment Account interop contract, and a manual-upload DAC form
-  a working ingestion chain
-- Two payment accounts have been ingested through that chain —
-  one active, one suspended — each resolved to its own legal
-  entity by MDM
-- Running the workflow routed them correctly: the active account
-  passed the filter and dispatched an SMS; the suspended account
-  was `:filtered`
-- The rendered notification SMS is readable from the `message`
-  dataset, carrying the "Alvera PR notification" copy with the
-  activated account's external id and a `/t/` deep-link
-- The connected-app deep-link the SMS carried resolves, and
-  message tracking records the open + form-submit timestamps
-
-The business outcome — a KYC-notification SMS sent when a payment
-account activates, with a working KYC-portal link — is
-demonstrated end-to-end, not merely provisioned.
-
-# See also
-
-- `_setup/payments.md` — the inlined bootstrap that
-  provisions the tenant + datalake this cookbook starts from
-- `sanctions-screening-with-agent-review.md` — the agent-driven
-  payments cookbook; an LLM agent disambiguates gray-zone
-  sanctions screenings
-- `.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`
-- `.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/payments/` — the vendored Atomic
-  FI payment-account / MDM Liquid templates §006 loads
-- `integration-tests/tests/payments/standard-workflow.test.ts` —
-  the anchor green test (§1–§7) these snippets are lifted from
-- `integration-tests/tests/payments/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–§009 are lifted from