@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/cookbook/subscription-saas.md

@@ -0,0 +1,2403 @@
+---
+title: "Subscription SaaS: one customer spine, three workflows, three ways in"
+summary: "The whole subscription-billing surface in one walk. Stand up a tenant and a raw datalake, declare one customers table, and run three workflows over it — a welcome SMS gated on reachability, a dunning reminder gated on reachability and KYC, and an LLM agent that bands accounts by priority and fans out one SMS per band. Then fill the same table three more ways — a bulk CSV upload, a pull-based REST fetch, and finally a teammate invited onto the tenant."
+use_case: subscription-saas
+slug: subscription-saas
+vitest_source:
+  - integration-tests/tests/subscription-saas/standard-workflow.test.ts
+  - integration-tests/tests/subscription-saas/dunning-sms-workflow.test.ts
+  - integration-tests/tests/subscription-saas/agent-lead-triage.test.ts
+  - integration-tests/tests/subscription-saas/run-dac-bulk.test.ts
+  - integration-tests/tests/subscription-saas/run-dac-fetch.test.ts
+  - integration-tests/tests/subscription-saas/invite-team.test.ts
+  - integration-tests/tests/workspace/bootstrap.test.ts
+status: draft
+---
+
+# Problem
+
+A subscription business talks to its customers on a schedule set by the
+billing system. A contract is signed and a welcome message goes out with a
+link to the self-serve portal. An invoice goes unpaid and a reminder goes
+out with a link to pay. An account needs chasing and *how* it is chased
+depends on what kind of account it is — a white-glove note to an enterprise,
+a standard nudge to a self-serve individual.
+
+Three jobs, one audience. The classic implementation is three services that
+each query a customers table and each carry their own copy of the
+reachability rule, the KYC rule and the account-tier rule. This walk builds
+all three on **one customers table**, because the customer is the same
+customer in all three and the rules belong to the platform rather than to
+three codebases.
+
+The last three scenarios are about how rows get *in*. A row can arrive
+one at a time through an inline ingest, four thousand at a time through a
+file upload, or be pulled from someone else's API on demand — and all three
+land in the same table through the same contract pair. The walk ends by
+inviting a second person onto the tenant, because a billing team is rarely
+one person.
+
+**This surface stays raw.** No tokenized or redacted copy is provisioned.
+Every read-back here is a question about this walk's own rows, and the
+priority agent classifies on account type rather than on anyone's name. The
+PII columns are still declared `tokenize` — that declaration is the policy,
+and it goes live the moment someone provisions the pair. If you want a model
+held away from identities today, that is what `payments-compliance` §007
+shows.
+
+# Composition
+
+| Resource                          | Why it exists here                        |
+|-----------------------------------|-------------------------------------------|
+| Tenant + raw datalake             | The billing team's own world              |
+| One customers generic table       | The spine all six scenarios write to      |
+| SMS tool, LLM tool                | Shared by every workflow below            |
+| Contract pair, on two clients     | Identity and table row, deliberately split|
+| Three workflows                   | Welcome, dunning, priority triage         |
+| Two connected apps                | The portal link, and the pay link         |
+| Manual-upload, bulk and REST paths| Three ways into the same table            |
+| An invitation                     | A second person on the tenant             |
+
+# Walkthrough
+
+This cookbook is **self-reliant**: it stands up everything it uses and
+depends on no other file. It is also **idempotent** — every creating step
+looks first and creates only what is missing, so running it twice costs what
+running it once cost. That is not a nicety. Nothing in the platform reclaims
+an abandoned datalake, and a walk that mints a fresh tenant per run leaves
+every previous run's lakes behind forever.
+
+## 001 — sign in as root, and make sure the admin user exists
+
+Authenticate as the platform's root admin (`admin@dev.local` /
+`devpassword` in local dev) via the tenantless bootstrap login — keyless by
+structural necessity, since no tenant exists yet to scope a key to, and a
+dev/test-only surface.
+
+Then make sure the admin user this walk runs as exists. **The email is
+stable, not per-run**, which is what makes the step idempotent — and it means
+the second run finds the user already signed up. A duplicate signup is
+refused, so the refusal is caught and inspected: if it says the email is
+taken, that is the idempotent path and the walk continues. Any other failure
+is re-raised, because swallowing it would turn a real auth problem into a
+confusing failure three steps later.
+
+```typescript
+ctx.rootSession = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: process.env.ALVERA_ROOT_EMAIL!,
+  password: process.env.ALVERA_ROOT_PASSWORD!,
+})
+ctx.rootApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.rootSession.sessionToken,
+  apiKey: '',
+})
+
+ctx.billingEmail = 'cookbook-subscription-saas@dev.local'
+ctx.billingPassword = 'CookbookPass1!'
+
+try {
+  const signUpResp = await ctx.rootApi.admin.signUp({
+    email: ctx.billingEmail,
+    password: ctx.billingPassword,
+    first_name: 'Cookbook',
+    last_name: 'Billing',
+  })
+  await ctx.rootApi.admin.confirmUser(signUpResp.data.id!)
+} catch (err) {
+  // Already provisioned by a previous run. Confirm that is what happened
+  // rather than assuming it — a genuine signup failure must not be read as
+  // "already there".
+  const detail = JSON.stringify((err as { errors?: unknown }).errors ?? err)
+  if (!/taken|already|exist/i.test(detail)) throw err
+}
+```
+
+## 002 — the find-or-create helper every later step uses
+
+Idempotence is one question asked over and over: *is this already here?*
+Rather than answer it a dozen different ways, the walk defines it once.
+
+`ensure` takes a label, a lookup and a create. It runs the lookup, returns
+what it finds, and only creates when the lookup comes back empty. The label
+is not decoration — when a run reuses something you did not expect it to, the
+log line naming it is how you find out.
+
+Alongside it, `firstNamed` — the lookup half, written once. **A list endpoint
+pages at twenty and is not newest-first**, so a `.find()` over the default
+page silently stops finding things as soon as a lake has a few of them, and
+the failure looks like the resource was never created. Passing
+`page_size: 100` is the cheap fix, and this walk creates enough tools,
+contracts and clients on one lake to need it.
+
+Both live on `ctx` rather than as bare functions because each numbered step
+compiles into its own `it()` block, so a plain `function` here would not be
+in scope for the steps that call it.
+
+```typescript
+ctx.ensure = async <T>(
+  label: string,
+  find: () => Promise<T | undefined>,
+  create: () => Promise<T>,
+): Promise<T> => {
+  const existing = await find()
+  if (existing !== undefined) {
+    console.log(`  ↻ reusing ${label}`)
+    return existing
+  }
+  console.log(`  + creating ${label}`)
+  return await create()
+}
+
+// Look one resource up by name across the WHOLE listing, not page one.
+ctx.firstNamed = <T extends { name?: string }>(
+  rows: readonly T[] | undefined,
+  name: string,
+): T | undefined => (rows ?? []).find((r) => r.name === name)
+```
+
+## 003 — the tenant
+
+The billing admin signs in without a tenant scope — they may not belong to
+one yet — and the walk finds or creates the tenant by its stable name. The
+server derives the slug; capture it, because every later call is addressed by
+it.
+
+```typescript
+ctx.billingTenantlessSession = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.billingEmail,
+  password: ctx.billingPassword,
+})
+ctx.billingTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: ctx.billingTenantlessSession.sessionToken,
+  apiKey: '',
+})
+
+const TENANT_NAME = 'Cookbook Subscription SaaS'
+
+const tenant = await ctx.ensure(
+  `tenant ${TENANT_NAME}`,
+  async () => {
+    const { data } = await ctx.billingTenantlessApi.tenants.list()
+    return (data.data ?? []).find((t: { name?: string }) => t.name === TENANT_NAME)
+  },
+  async () => {
+    const { data } = await ctx.billingTenantlessApi.tenants.create({ name: TENANT_NAME })
+    return data
+  },
+)
+tenantSlug = tenant.slug!
+```
+
+## 004 — the tenant-scoped client
+
+A tenant-scoped login requires `X-API-Key`, so a key has to exist before the
+admin can sign in against the tenant. Mint one through the platform-admin
+side door with the root bearer; in the web console this is *Settings → API
+Keys*.
+
+`data_access_mode: 'raw'` is the ceiling, and on this surface it is the only
+tier there is — no derived lake is provisioned, so raw is what every read
+answers from.
+
+**This is the one step in the walk that is not idempotent**, and it is worth
+knowing why rather than discovering it. There is no endpoint that lists a
+tenant's API keys, so there is nothing to look the existing one up with —
+`ensure` has no lookup to run. Each run therefore mints another key. A key
+row is cheap where a datalake is not, so the walk accepts it; if you are
+counting rows in a shared environment, this is the one to count.
+
+```typescript
+const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: 'Cookbook Subscription SaaS Key',
+  data_access_mode: 'raw',
+})
+ctx.tenantApiKey = mintedKey.api_key
+
+const billingTenantSession = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.billingEmail,
+  password: ctx.billingPassword,
+  tenantSlug,
+  apiKey: ctx.tenantApiKey,
+})
+api = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: billingTenantSession.sessionToken,
+  apiKey: ctx.tenantApiKey,
+})
+```
+
+## 005 — the datalake
+
+One datalake, created `raw`, and on this surface that is the whole story —
+there is no derived pair to provision and nothing to wait for beyond the
+migration in §006.
+
+The lookup still filters on `type === 'raw'`. That costs nothing here and
+keeps the step correct if anyone ever turns tokenization on: from that moment
+`datalakes.list` returns three rows, two of which are copies that must never
+be mistaken for the primary.
+
+Local-dev defaults match the seeded `dev.exs` setup — `postgres` on
+`localhost:5432`, database `alvera_dev_foundation`, LocalStack S3 on
+`localhost:4566` — and the schema name is stable, because a fresh schema per
+run is the same leak as a fresh tenant per run.
+
+```typescript
+const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_foundation' }
+const DB_SCHEMA = 'cookbook_subscription_saas'
+const LAKE_NAME = 'Cookbook Subscription SaaS Datalake'
+
+const S3 = {
+  cloud_storage_type: 'aws' as const,
+  region: 'us-east-1',
+  access_key_id: 'test',
+  secret_access_key: 'test',
+  endpoint: 'http://localhost:4566',
+}
+
+const datalake = await ctx.ensure(
+  `datalake ${LAKE_NAME}`,
+  async () => {
+    const { data } = await api.datalakes.list(tenantSlug)
+    return (data.data ?? []).find(
+      (l: { name?: string; type?: string }) => l.name === LAKE_NAME && l.type === 'raw',
+    )
+  },
+  async () => {
+    const { data } = await api.datalakes.create(tenantSlug, {
+      name: LAKE_NAME,
+      description: 'Subscription SaaS datalake provisioned by the cookbook doctest.',
+      timezone: 'America/New_York',
+      pool_size: 3,
+      type: 'raw',
+
+      db_writer_host: DB.host,
+      db_writer_port: DB.port,
+      db_writer_name: DB.name,
+      db_writer_schema: DB_SCHEMA,
+      db_writer_auth_method: 'password',
+      db_writer_user: DB.user,
+      db_writer_pass: DB.pass,
+      db_writer_enable_ssl: false,
+      db_reader_host: DB.host,
+      db_reader_port: DB.port,
+      db_reader_name: DB.name,
+      db_reader_schema: DB_SCHEMA,
+      db_reader_auth_method: 'password',
+      db_reader_user: DB.user,
+      db_reader_pass: DB.pass,
+      db_reader_enable_ssl: false,
+
+      cloud_storage: { ...S3, bucket: 'alvera-platform-dev', base_path: 'cookbook/subscription-saas' },
+    })
+    return data
+  },
+)
+datalakeSlug = datalake.slug!
+ctx.datalakeId = datalake.id!
+```
+
+## 006 — run the migrations, and wait for ready
+
+`datalakes.create` persists the row at `status: 'new'`; it does not run the
+schema DDL. Migration is triggered separately so the operator decides when
+the potentially-slow part happens. `datalakes.migrate` enqueues the job and
+returns immediately with `status: 'enqueued'`; the poll after it is what
+waits for the worker.
+
+Migrating is safe to repeat, which is what lets this step stay unguarded on a
+second run. The wait exits the moment the lake reports `ready`, so the
+five-minute ceiling is only ever paid in failure.
+
+```typescript
+const migrateResp = await api.datalakes.migrate(tenantSlug, datalakeSlug)
+if (migrateResp.data.status !== 'enqueued') {
+  throw new Error(`datalake migration not enqueued (status: ${migrateResp.data.status})`)
+}
+
+const READY_TIMEOUT_MS = 5 * 60_000
+const readyDeadline = Date.now() + READY_TIMEOUT_MS
+let datalakeStatus: string | undefined
+while (Date.now() < readyDeadline) {
+  const { data } = await api.datalakes.get(tenantSlug, ctx.datalakeId)
+  datalakeStatus = data.status
+  if (datalakeStatus === 'ready') break
+  await new Promise((r) => setTimeout(r, 5_000))
+}
+if (datalakeStatus !== 'ready') {
+  throw new Error(`datalake did not reach :ready within ${READY_TIMEOUT_MS}ms (last: ${datalakeStatus})`)
+}
+```
+
+## 007 — three helpers the scenarios below share
+
+**`waitForFiredRun`.** `workflows.run` only *schedules* a run. It returns
+immediately with a `workflow_run_id`, and the `workflow_run_log_id` and
+`batch_id` a scenario needs are written later, when the run actually fires.
+Two traps live in that gap:
+
+- **Poll until `workflow_run_log_id` is a string — not until `status` leaves
+  `'scheduled'`.** Those are different moments; the run reaches `processing`
+  first and writes the log id a beat later. A predicate on status alone
+  releases you to read a `null`, and because `typeof null === 'object'` the
+  symptom is a baffling *"expected string, got object"* rather than an
+  obvious nil.
+- **Raise on `failed` carrying `failure_reason`** rather than polling to the
+  deadline. A scenario blocked on a run that will never fire should say why
+  on the first read, not thirty seconds later behind a generic timeout.
+
+**`waitForBatches`.** Ingestion is async: `ingest` returns a `batch_id` the
+instant the rows are accepted, and the per-row jobs drain afterwards. This
+polls a client's activation logs until every named batch has actually
+written.
+
+**Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+different questions — received versus written — and a batch whose row is
+refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`
+with the reason in `error`. A gate on `rows_ingested` calls that green, the
+next step then runs against a table with nothing in it, and the failure
+surfaces three steps later as *"expected 2 execution logs, got 0"* — which
+reads like a broken workflow rather than a row that never landed.
+
+**`deployGenericTable`.** Creating a generic table does not deploy it; it
+rests at `status: 'new'` until a migration runs. The wait that means anything
+asks for the table the same way the next step is about to, and retries until
+it stops erroring — polling the table's own `status: 'deployed'` goes true
+earlier and proves less.
+
+```typescript
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs = 120_000,
+): Promise<{ workflowRunLogId: string; batchId: string | null }> => {
+  const deadline = Date.now() + timeoutMs
+  let lastStatus: string | undefined
+  while (Date.now() < deadline) {
+    const { data } = await api.workflowRuns.get(tenantSlug, runDatalakeSlug, runId)
+    lastStatus = data.status
+    if (data.status === 'failed') {
+      throw new Error(`workflow run ${runId} failed: ${data.failure_reason ?? 'no failure_reason given'}`)
+    }
+    if (typeof data.workflow_run_log_id === 'string') {
+      return { workflowRunLogId: data.workflow_run_log_id, batchId: data.batch_id ?? null }
+    }
+    await new Promise((r) => setTimeout(r, 1_000))
+  }
+  throw new Error(`workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`)
+}
+
+ctx.waitForBatches = async (
+  dacSlug: string,
+  batchIds: readonly string[],
+  timeoutMs = 90_000,
+): Promise<void> => {
+  const targets = new Set(batchIds)
+  const deadline = Date.now() + timeoutMs
+  let greenCount = 0
+  while (Date.now() < deadline) {
+    const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, 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' || !targets.has(b)) continue
+      if (row.status === 'partial' || row.status === 'failed') {
+        throw new Error(
+          `batch ${b} on ${dacSlug} did not persist its rows (status: ${row.status}): ` +
+            `${String(row.error ?? 'no reason given')}`,
+        )
+      }
+      if (typeof row.dataset_updated !== 'number' || row.dataset_updated < 1) continue
+      const files = row.output_files
+      if (!Array.isArray(files) || files.length === 0) continue
+      green.add(b)
+    }
+    greenCount = green.size
+    if (greenCount === targets.size) return
+    await new Promise((r) => setTimeout(r, 1_000))
+  }
+  throw new Error(`only ${greenCount}/${targets.size} batches on ${dacSlug} persisted within ${timeoutMs}ms`)
+}
+
+ctx.deployGenericTable = async (tableName: string, timeoutMs = 120_000): Promise<void> => {
+  await api.datalakes.migrate(tenantSlug, datalakeSlug)
+  const deadline = Date.now() + timeoutMs
+  let lastError: unknown
+  while (Date.now() < deadline) {
+    try {
+      await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+        sql: `SELECT 1 FROM ${tableName} LIMIT 1`,
+        mode: 'raw',
+      })
+      return
+    } catch (err) {
+      lastError = err
+      await new Promise((r) => setTimeout(r, 1_000))
+    }
+  }
+  throw new Error(
+    `generic table ${tableName} was not readable within ${timeoutMs}ms ` +
+      `(last error: ${lastError instanceof Error ? lastError.message : String(lastError)})`,
+  )
+}
+```
+
+## 008 — the SMS tool
+
+One SMS tool dispatches every outbound message in this walk — a welcome, a
+dunning reminder and three priority bands. **The per-message body lives on
+the workflow action, never on the tool**, which is what lets one tool serve
+all of them. `intent: 'sms'` tags it for workflow-action use.
+
+Local dev points at LocalStack's SNS on `:4566`, so nothing leaves the
+machine.
+
+```typescript
+const smsTool = await ctx.ensure(
+  'SMS tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Billing SMS Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Billing SMS Tool',
+      description: 'SNS-backed SMS dispatcher for every billing scenario, 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',
+      },
+    })
+    return data
+  },
+)
+toolId = smsTool.id!
+ctx.smsToolId = smsTool.id!
+```
+
+## 009 — the customers table, which all three workflows share
+
+A customer is not one of the datasets the platform ships. The platform models
+exactly one identity — the legal entity — and everything else a build needs
+is a generic table you declare, plus the legal entity the rows resolve to.
+There is no `customer` dataset to reach for.
+
+**One table serves all three workflows**, and the column list is the union of
+what they gate on rather than three near-identical tables. `phone` is the
+welcome workflow's reachability gate. `tax_id` is the dunning workflow's KYC
+gate. `customer_type` is what the priority agent bands on. `status` is what
+makes a customer newly contracted.
+
+The PII columns are declared `tokenize` and the rest `none`. **That
+declaration is the masking policy, and it is correct whether or not a
+tokenized lake exists today** — this walk provisions none, so nothing masks
+here, and the declaration goes live the moment someone calls
+`provisionTokenization`. Declaring it now is how the policy survives that
+call rather than being remembered afterwards.
+
+Do **not** declare a `legal_entity_id` column. The platform stamps it from
+the MDM resolve in §012, and the name is reserved — declaring it does not
+shadow the stamp, it 422s the create, so you lose the table until you drop it.
+
+```typescript
+const customers = await ctx.ensure(
+  'customers table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Cookbook Customers')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Cookbook Customers',
+      description: 'Stripe customers the welcome, dunning and triage workflows all run on.',
+      columns: [
+        { name: 'customer_number', title: 'Customer Number', type: 'string', description: 'Stripe customer id — unique per customer', is_unique: true, privacy_requirement: 'none' },
+        { name: 'customer_type', title: 'Customer Type', type: 'string', description: 'individual / enterprise — the legal-entity branch, and what the priority agent bands on', is_unique: false, privacy_requirement: 'none' },
+        { name: 'status', title: 'Status', type: 'string', description: 'Commercial state — contracted is what earns a welcome', is_unique: false, privacy_requirement: 'none' },
+        { name: 'name', title: 'Name', type: 'string', description: 'Customer display name', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'email', title: 'Email', type: 'string', description: 'Billing email', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'phone', title: 'Phone', type: 'string', description: 'Billing phone — the SMS destination and the reachability gate', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'tax_id', title: 'Tax ID', type: 'string', description: 'Tax identifier — its presence is the KYC gate', is_unique: false, privacy_requirement: 'tokenize' },
+        { name: 'currency', title: 'Currency', type: 'string', description: 'Settlement currency', is_unique: false, privacy_requirement: 'none' },
+        { name: 'delinquent', title: 'Delinquent', type: 'boolean', description: 'Whether the latest invoice is past due', is_unique: false, privacy_requirement: 'none' },
+        { name: 'address_city', title: 'Address City', type: 'string', description: 'Billing city', is_unique: false, privacy_requirement: 'none' },
+        { name: 'address_country', title: 'Address Country', type: 'string', description: 'Billing country', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
+genericTableId = customers.id!
+ctx.customersTableId = customers.id!
+ctx.customersTableName = customers.name!
+
+// Creating the table records it; it is not deployed until a migration runs.
+await ctx.deployGenericTable(ctx.customersTableName)
+```
+
+## 010 — the Stripe data source and the manual-upload tool
+
+A workflow runs on rows, and rows arrive through the data-activation chain.
+The chain's first link is a **data source** — a registration of where the
+rows originate. Its `uri` is the system-of-record address, and it matters
+more than it looks: the client injects it into every ingested row as
+`source_uri`, and both contracts below render it onto the identifier. It is
+half of the key that collapses two contracts onto one legal entity.
+
+The **manual-upload tool** is the minimal data-exchange tool. It needs no
+endpoint and no credentials, because the rows arrive in the ingest call's own
+body rather than being fetched. `intent: 'data_exchange'` is what
+distinguishes it from the SMS tool above.
+
+```typescript
+const dataSource = await ctx.ensure(
+  'Stripe data source',
+  async () => {
+    const { data } = await api.dataSources.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Stripe Source')
+  },
+  async () => {
+    const { data } = await api.dataSources.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Stripe Source',
+      uri: 'stripe.example.com/cookbook-subscription-saas',
+      description: 'Stripe billing system — origin of every customer row in this walk.',
+      status: 'active',
+      is_default: false,
+    })
+    return data
+  },
+)
+dataSourceId = dataSource.id!
+ctx.dataSourceId = dataSource.id!
+
+const manualUploadTool = await ctx.ensure(
+  'manual-upload tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Manual Upload Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Manual Upload Tool',
+      description: 'Manual-upload data-exchange tool — backs the inline and bulk ingest paths.',
+      intent: 'data_exchange',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: dataSourceId,
+      body: { tool_body_type: 'manual_upload' },
+    })
+    return data
+  },
+)
+ctx.manualUploadToolId = manualUploadTool.id!
+```
+
+## 011 — the contract pair
+
+One inbound Stripe row becomes two things, so it takes two contracts.
+
+**Contract A** (`resource_type: 'legal_entity'`) writes the identity — the
+name, the type, the identification triple. Its `mdm_input_config` is
+`{ type: 'null' }`, because a template that already *is* the subject has
+nothing to resolve.
+
+**Contract B** (`resource_type: 'generic_table'`, pinned to §009's table)
+writes the table row, and its `mdm_input_config` emits the same
+`(uri, customer_number)` pair. That is what collapses both onto one legal
+entity per customer, and what earns the row the `legal_entity_id` stamp every
+connected-app link is minted against.
+
+**The identifier shape is where this goes wrong, and there are three of them
+on this platform.** `Platform.MDMInput` — what a `mdm_input_config` renders —
+takes `uri` / `type` / `value`. A legal-entity identification, which is
+Contract A's own body, takes `id_type` / `id_number` / `uri`. And
+`POST /mdm/verify` takes `system` / `id_type` / `value`. The overlap is
+uneven: `system` is a genuine alias on the MDM side — it is cast and
+normalised onto `uri` — but `id_type` and `id_number` are not cast at all.
+Unknown keys are dropped rather than refused, so borrowing the legal-entity
+names for the MDM template resolves nothing and fails as a bare
+`mdm_dispatcher_error` naming no field.
+
+And the reason the two look interchangeable is that **one becomes the
+other**. `MDMInput.to_identification/1` takes `(uri, type, value)` and
+returns `(uri, id_type, id_number)` — the rename happens inside the platform,
+on the way through. So the identifier reads back under names it will not
+accept on the way in, and that asymmetry is invisible from the stored shape
+alone.
+
+The templates are loaded from the vendored fixtures rather than inlined; they
+are long, and a reader who wants them can open the file.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const read = (f: string) =>
+  readFileSync(join(process.env.COOKBOOK_FIXTURES_DIR!, 'subscription-saas', f), 'utf8')
+
+const leContract = await ctx.ensure(
+  'legal-entity contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Customer LE Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Customer LE Contract',
+      description: 'Stripe customer → LegalEntity (individual or business).',
+      resource_type: 'legal_entity',
+      type: 'identity',
+      generic_table_id: null,
+      template_config: { type: 'custom', body: read('_customers_subscription_legal_entity.liquid') },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+ctx.leContractId = leContract.id!
+
+const gtContract = await ctx.ensure(
+  'generic-table contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Customer GT Contract')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Customer GT Contract',
+      description: 'Stripe customer → customers table row, stamped with its subject.',
+      resource_type: 'generic_table',
+      type: 'identity',
+      generic_table_id: ctx.customersTableId,
+      template_config: { type: 'custom', body: read('_customers_subscription_generic_table.liquid') },
+      mdm_input_config: { type: 'custom', body: read('_customers_subscription_mdm.liquid') },
+    })
+    return data
+  },
+)
+interopContractId = gtContract.id!
+ctx.gtContractId = gtContract.id!
+```
+
+## 012 — two clients, because the pair must not share one
+
+Here is the trap, and it is the most expensive one in this file.
+
+The obvious move is to bind both contracts to a single client and ingest
+once. **Do not.** A client fans out per `(row, contract)` at enqueue time,
+and the job key is staggered by *row* — so a pair bound to one client runs
+both contracts on the same row **at the same instant**. Both resolve the same
+subject, both find-or-create it, both miss the other's uncommitted write, and
+the unique index on `(uri, id_type, id_number)` refuses the loser. The legal
+entity is deliberately not part of that key, which is what makes the refusal
+correct rather than a bug: two writers, one subject, one winner.
+
+The stagger is the platform's designed guard, and it only helps when the two
+contracts are on different *rows*. So split them across two clients and
+sequence the ingest: identity first, wait, then the table row. Contract B's
+resolve then finds the subject Contract A already committed, and stamps it.
+
+Both clients share the tool and the data source. Only the contract list
+differs.
+
+```typescript
+const identityDac = await ctx.ensure(
+  'identity activation client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Customer Identity DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Customer Identity DAC',
+      description: 'Writes the legal entity for each Stripe customer. Runs FIRST.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [ctx.leContractId],
+    })
+    return data
+  },
+)
+ctx.identityDacSlug = identityDac.slug!
+
+const dataDac = await ctx.ensure(
+  'data activation client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Customer Data DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Customer Data DAC',
+      description: 'Writes the customers table row and stamps it with the subject. Runs SECOND.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [ctx.gtContractId],
+    })
+    return data
+  },
+)
+dacId = dataDac.id!
+ctx.dataDacSlug = dataDac.slug!
+```
+
+## 013 — four customers, identities first
+
+Four rows, chosen so that each of the three workflows below can be scoped to
+a pair that splits cleanly:
+
+| customer          | phone | tax_id | type       | proves                       |
+|-------------------|-------|--------|------------|------------------------------|
+| `CUS-SS-REACH`    | yes   | yes    | individual | passes all three filters     |
+| `CUS-SS-NOPHONE`  | —     | yes    | individual | welcome filters it out       |
+| `CUS-SS-NOKYC`    | yes   | —      | individual | dunning filters it out       |
+| `CUS-SS-ENTERPRISE`| yes  | yes    | enterprise | the agent bands it high      |
+
+The customer numbers are **stable, not per-run**. That is what makes the walk
+idempotent — a second run upserts the same four rows on `customer_number`
+rather than adding four more — and it is also what makes the outbound
+messages idempotent, since the action keys are built from these ids.
+
+The ingest is **staged**, per §012. Every identity row goes through the
+identity client and is waited on to completion; only then do the table rows
+go through the data client.
+
+```typescript
+ctx.reachNumber = 'CUS-SS-REACH'
+ctx.noPhoneNumber = 'CUS-SS-NOPHONE'
+ctx.noKycNumber = 'CUS-SS-NOKYC'
+ctx.enterpriseNumber = 'CUS-SS-ENTERPRISE'
+
+ctx.customerRows = [
+  {
+    customer_number: ctx.reachNumber,
+    customer_type: 'individual',
+    status: 'contracted',
+    name: 'Olivia Hartmann',
+    email: 'olivia.hartmann@example.com',
+    phone: '+12025553101',
+    tax_id: '311-22-7890',
+    currency: 'USD',
+    delinquent: 'true',
+    address_city: 'Boston',
+    address_country: 'US',
+  },
+  {
+    customer_number: ctx.noPhoneNumber,
+    customer_type: 'individual',
+    status: 'contracted',
+    name: 'Noah Pemberton',
+    email: 'noah.pemberton@example.com',
+    tax_id: '412-88-1200',
+    currency: 'USD',
+    delinquent: 'false',
+    address_city: 'Denver',
+    address_country: 'US',
+    // phone deliberately absent — the welcome filter must reject this row
+  },
+  {
+    customer_number: ctx.noKycNumber,
+    customer_type: 'individual',
+    status: 'contracted',
+    name: 'Priya Raghunathan',
+    email: 'priya.raghunathan@example.com',
+    phone: '+12025553103',
+    currency: 'USD',
+    delinquent: 'true',
+    address_city: 'Austin',
+    address_country: 'US',
+    // tax_id deliberately absent — the dunning filter must reject this row
+  },
+  {
+    customer_number: ctx.enterpriseNumber,
+    customer_type: 'enterprise',
+    status: 'contracted',
+    name: 'Pinnacle Financial Group',
+    email: 'ap@pinnaclefg.example.com',
+    phone: '+12125559100',
+    tax_id: '84-2156789',
+    currency: 'USD',
+    delinquent: 'true',
+    address_city: 'New York',
+    address_country: 'US',
+  },
+]
+
+// Stage one — the identities.
+const identityIngests = await Promise.all(
+  ctx.customerRows.map((row: Record<string, unknown>) =>
+    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.identityDacSlug, { data: row }),
+  ),
+)
+await ctx.waitForBatches(
+  ctx.identityDacSlug,
+  identityIngests.map((r: { data: { batch_id?: string } }) => r.data.batch_id!),
+)
+
+// Stage two — the table rows, now that every subject exists.
+const dataIngests = await Promise.all(
+  ctx.customerRows.map((row: Record<string, unknown>) =>
+    api.dataActivationClients.ingest(tenantSlug, datalakeSlug, ctx.dataDacSlug, { data: row }),
+  ),
+)
+ctx.customerBatchIds = dataIngests.map((r: { data: { batch_id?: string } }) => r.data.batch_id!)
+await ctx.waitForBatches(ctx.dataDacSlug, ctx.customerBatchIds)
+```
+
+## 014 — the stamp is the proof that resolution ran
+
+The activation log said the rows were written. This asks the table itself,
+which is the independent answer, and it asks for the one column no contract
+writes: `legal_entity_id`.
+
+A row present with a null stamp is the failure this step exists to catch. It
+means Contract B's template landed but its `mdm_input_config` resolved
+nothing — the wrong identifier shape, or a subject that was not there yet —
+and every link minted from that row afterwards would point at nobody.
+
+```typescript
+const stampDeadline = Date.now() + 90_000
+let stamped: unknown[][] = []
+while (Date.now() < stampDeadline && stamped.length < 4) {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT customer_number, legal_entity_id
+          FROM ${ctx.customersTableName}
+          WHERE customer_number IN (
+            '${ctx.reachNumber}', '${ctx.noPhoneNumber}',
+            '${ctx.noKycNumber}', '${ctx.enterpriseNumber}'
+          )
+          ORDER BY customer_number`,
+    mode: 'raw',
+  })
+  if (typeof result !== 'string') stamped = result.data
+  if (stamped.length < 4) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (stamped.length !== 4) {
+  throw new Error(`expected 4 customer rows, found ${stamped.length} within 90s`)
+}
+const unstamped = stamped.filter((row) => !row[1]).map((row) => String(row[0]))
+if (unstamped.length > 0) {
+  throw new Error(
+    `these rows landed with no legal_entity_id stamp — the MDM resolve did not run: ${unstamped.join(', ')}`,
+  )
+}
+```
+
+## 015 — the billing-portal connected app
+
+The welcome SMS carries a deep link to the self-serve billing portal. A
+connected app is a thin registration of that page's URL and hosting mode; the
+page itself lives outside the platform (`mode: 'self_hosted'`). Capture the
+server-derived slug — resolving the link in §019 is addressed by it.
+
+```typescript
+const portalApp = await ctx.ensure(
+  'billing-portal connected app',
+  async () => {
+    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Billing Portal')
+  },
+  async () => {
+    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Billing Portal',
+      description: 'Self-serve billing portal linked from the outbound welcome SMS.',
+      mode: 'self_hosted',
+      urls: [{ url: 'https://billing.example.local', is_primary: true, label: 'production' }],
+    })
+    return data
+  },
+)
+connectedAppId = portalApp.id!
+ctx.portalAppId = portalApp.id!
+ctx.portalAppSlug = portalApp.slug!
+```
+
+## 016 — the Welcome SMS workflow
+
+Standard shape — a filter, a decision, one action — with three things worth
+reading closely.
+
+`dataset_type: 'generic_table'` with `generic_table_id` makes §009's table
+the event source. The row is injected under the `event_dataset` key, so the
+filter reads `event_dataset.phone` directly.
+
+`skip_mdm_resolution: false` is set explicitly, and must be. A generic-table
+row is never its own subject — the subject is the legal entity §011's pair
+stamped onto it. With resolution on, the platform loads that subject and
+mints a page token against it, which is what makes
+`{{ connected_app_form_url }}` a *per-customer* link. Skip it and the token
+is never minted and the link renders empty.
+
+The `context_datasets` entry queries the `message` dataset for a welcome
+already sent to this legal entity in the last six months — the platform's
+built-in guard against welcoming someone twice, expressed as a context query
+rather than as application code. On a fresh lake it returns empty, which is
+harmless; on the second run of this walk it is one of two guards that stop a
+duplicate message, the other being the idempotency key on the action.
+
+```typescript
+const WELCOME_KEY = 'send_welcome_sms'
+
+const welcomeWorkflow = await ctx.ensure(
+  'Welcome SMS workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Welcome SMS Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Welcome SMS Workflow',
+      description: 'Sends a welcome SMS to newly contracted customers with a self-serve billing link.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.customersTableId,
+      status: 'live',
+      tags: ['lifecycle', 'welcome'],
+      skip_mdm_resolution: false,
+      filter_config: {
+        type: 'custom',
+        body:
+          '{% if event_dataset.status == "contracted" %}' +
+          '{% if event_dataset.phone and event_dataset.phone != "" %}true{% endif %}' +
+          '{% endif %}',
+      },
+      decision_config: {
+        type: 'custom',
+        body: `["${WELCOME_KEY}"]`,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      context_datasets: [
+        {
+          dataset_type: 'message',
+          where_clause:
+            `m.legal_entity_id = '{{ legal_entity_id }}' AND m.decision_key = '${WELCOME_KEY}' ` +
+            "AND m.sent_at > NOW() - INTERVAL '6 months'",
+          limit: 1,
+          position: 0,
+        },
+      ],
+      actions: [
+        {
+          action_type: 'sms',
+          tool_id: ctx.smsToolId,
+          decision_key: WELCOME_KEY,
+          position: 0,
+          trigger_template: 'now',
+          idempotency_template: `{{ event_dataset.customer_number }}-${WELCOME_KEY}`,
+          connected_app_id: ctx.portalAppId,
+          connected_app_route: '/portal/welcome',
+          connected_app_metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '{{ event_dataset.phone }}' },
+            body: {
+              type: 'custom',
+              body:
+                'Hi {{ event_dataset.name }}, welcome to Alvera Billing. ' +
+                'Self-serve billing portal: {{ connected_app_form_url }}',
+            },
+            sms_type: 'transactional',
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+workflowId = welcomeWorkflow.id!
+ctx.welcomeWorkflowId = welcomeWorkflow.id!
+ctx.welcomeWorkflowSlug = welcomeWorkflow.slug!
+
+if (welcomeWorkflow.skip_mdm_resolution !== false) {
+  throw new Error('a generic-table workflow that mints a per-customer link must keep MDM resolution ON')
+}
+```
+
+## 017 — run it across the reachable and unreachable pair
+
+`manual_override: false` is what makes this a real test — the filter is
+evaluated, so the `event_dataset.phone` gate genuinely routes each row. With
+`true` the filter is bypassed and both rows would pass, which proves nothing.
+
+The where-clause scopes the run to exactly two of the four rows. A
+generic-table run selects on the table's own columns, so it reads
+`customer_number` with no alias to prefix.
+
+A `:partial` batch status is the expected outcome here, not a warning: one
+row passed and one was filtered, which is precisely the split this scenario
+is about.
+
+```typescript
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.welcomeWorkflowSlug, {
+  sql_where_clause: `customer_number IN ('${ctx.reachNumber}', '${ctx.noPhoneNumber}')`,
+  mode: 'live',
+  manual_override: false,
+})
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.welcomeRunLogId = fired.workflowRunLogId
+ctx.welcomeRunBatchId = 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.welcomeWorkflowSlug, ctx.welcomeRunLogId,
+  )
+  status = log.status ?? null
+  if (status && status !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (status === 'failed') throw new Error('welcome run reached :failed')
+if (!status || status === 'pending') {
+  throw new Error('welcome run did not leave :pending within 120s')
+}
+```
+
+## 018 — the filter routed, and that is asserted at the log level
+
+Each row produced a Workflow Execution Log. The reachable customer passed, so
+its log is `:executing` or `:completed`. The customer with no phone failed the
+filter, so its log is `:filtered` — a distinct terminal status, and a
+*correct* outcome rather than an error. The platform looked at the row, the
+gate rendered empty, and it recorded that the row was intentionally skipped.
+
+A run where both passed, or both were filtered, would mean the filter is not
+actually reading `event_dataset.phone`.
+
+**This assertion is at the execution-log level on purpose, and that is what
+makes it survive a rerun.** The action inside the passing row's log will
+refuse to fire a second time — its idempotency key already fired — but the
+row still passes the filter, so the one-passed-one-filtered split is the same
+on every run. An assertion written against the action instead would go red on
+run two for a reason that is not a defect.
+
+```typescript
+const deadline = Date.now() + 90_000
+let ourLogs: Array<Record<string, unknown>> = []
+let byStatus: Record<string, number> = {}
+while (Date.now() < deadline) {
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(
+    tenantSlug, datalakeSlug, ctx.welcomeWorkflowSlug, { page_size: 100 },
+  )
+  ourLogs = (wfLogs.data ?? [])
+    .map((w) => w as Record<string, unknown>)
+    .filter((w) => w.batch_id === ctx.welcomeRunBatchId)
+  byStatus = {}
+  for (const w of ourLogs) {
+    const st = (w.status as string | undefined) ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const settled = (byStatus.completed ?? 0) + (byStatus.executing ?? 0)
+  if (ourLogs.length === 2 && settled === 1 && (byStatus.filtered ?? 0) === 1) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (ourLogs.length !== 2) {
+  throw new Error(`expected 2 execution logs for the run, got ${ourLogs.length}`)
+}
+const passed = (byStatus.executing ?? 0) + (byStatus.completed ?? 0)
+if (passed !== 1) {
+  throw new Error(`expected 1 row past the filter, got ${passed} — distribution ${JSON.stringify(byStatus)}`)
+}
+if ((byStatus.filtered ?? 0) !== 1) {
+  throw new Error(
+    `expected the no-phone customer to be :filtered — distribution ${JSON.stringify(byStatus)}`,
+  )
+}
+```
+
+## 019 — the welcome SMS exists, and it carries a working link
+
+§018 proved the routing. This proves something was actually *sent*, and it is
+the assertion that survives every rerun.
+
+**Search on the idempotency key, never on `workflow_id`.** The key is
+`<customer number>-send_welcome_sms` and the customer number is stable, so it
+names the same message forever. A workflow id is stable only as long as the
+workflow resource is: recreate it against a lake that still holds its rows
+and the id changes while the key does not — the action then correctly refuses
+to fire, and a search for the new id finds nothing at all.
+
+Then resolve the `/t/<token>` the platform baked into the body when it minted
+the page token, and post the tracking a connected-app frontend would post
+when the customer opens the portal. That closes the loop: the message went
+out, the link in it resolves to this customer's page, and the open was
+recorded.
+
+```typescript
+const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key = '${ctx.reachNumber}-send_welcome_sms'`,
+})
+if (search.status !== 'completed') {
+  throw new Error(`message user-search status=${search.status} error=${search.error_message ?? '(none)'}`)
+}
+
+const msgDeadline = Date.now() + 90_000
+let welcomeBody: string | undefined
+while (Date.now() < msgDeadline && !welcomeBody) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: search.id!,
+    dataAccessMode: 'raw',
+  })
+  welcomeBody = ((data.data ?? []) as Array<Record<string, unknown>>)
+    .map((m) => String(m.body ?? ''))
+    .find((body) => body.includes('/t/') && body.includes('welcome to Alvera Billing'))
+  if (!welcomeBody) await new Promise((r) => setTimeout(r, 2_000))
+}
+if (!welcomeBody) {
+  throw new Error(
+    `no rendered welcome SMS for ${ctx.reachNumber} within 90s — ` +
+      'the action never fired, or it fired under a different idempotency key',
+  )
+}
+const tokenMatch = welcomeBody.match(/\/t\/([A-Za-z0-9_-]+)/)
+if (!tokenMatch) throw new Error(`no /t/<token> in the rendered body: ${welcomeBody}`)
+
+const { data: resolved } = await api.connectedApps.resolvePage(
+  tenantSlug, datalakeSlug, ctx.portalAppSlug,
+  { short_path: tokenMatch[1]!, user_agent: 'cookbook-doctest/subscription-saas' },
+)
+if (resolved.route_path !== '/portal/welcome') {
+  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
+}
+if (!(resolved.message?.body ?? '').includes('welcome to Alvera Billing')) {
+  throw new Error('the resolved page carries the wrong message')
+}
+
+const now = new Date().toISOString()
+const { data: tracked } = await api.connectedApps.updateMessageTracking(
+  tenantSlug, datalakeSlug, ctx.portalAppSlug,
+  { short_path: tokenMatch[1]!, 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')
+}
+```
+
+## 020 — the pay-portal connected app
+
+The dunning SMS carries a different link to a different page: not the
+welcome portal but the one where an overdue invoice gets paid. A second
+connected app, registered the same way.
+
+Two apps rather than two routes on one app is a deliberate choice worth
+naming. A connected app is the unit a page token is minted against, so
+separating them means a token issued for a payment page cannot be replayed
+against the welcome page, and revoking one does not take the other down.
+
+```typescript
+const payApp = await ctx.ensure(
+  'pay-portal connected app',
+  async () => {
+    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Payment Portal')
+  },
+  async () => {
+    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Payment Portal',
+      description: 'Self-serve payment page linked from the outbound dunning SMS.',
+      mode: 'self_hosted',
+      urls: [{ url: 'https://pay.example.local', is_primary: true, label: 'production' }],
+    })
+    return data
+  },
+)
+ctx.payAppId = payApp.id!
+ctx.payAppSlug = payApp.slug!
+```
+
+## 021 — the Dunning SMS workflow: two gates, not one
+
+Same table, same shape, one more gate. The welcome workflow asks whether the
+platform *can* reach this customer. The dunning workflow asks that and
+whether it is *allowed* to: a customer whose KYC is incomplete — no tax
+identifier on file — is not chased, however overdue the invoice.
+
+Both gates are one Liquid filter. That is the whole point of the primitive:
+the reachability rule and the KYC rule live next to each other on the
+workflow, where a compliance reviewer can read them, rather than in two
+branches of a service nobody reviews.
+
+The recency guard is thirty days rather than the welcome's six months,
+because that is the shape of the business rule — one reminder per billing
+cycle, not one reminder per lifetime.
+
+```typescript
+const DUNNING_KEY = 'send_dunning_sms'
+
+const dunningWorkflow = await ctx.ensure(
+  'Dunning SMS workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Dunning SMS Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Dunning SMS Workflow',
+      description: 'Sends a payment reminder to reachable, KYC-complete customers with a self-serve pay link.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.customersTableId,
+      status: 'live',
+      tags: ['billing', 'dunning'],
+      skip_mdm_resolution: false,
+      filter_config: {
+        type: 'custom',
+        body:
+          '{% if event_dataset.phone and event_dataset.phone != "" %}' +
+          '{% if event_dataset.tax_id and event_dataset.tax_id != "" %}true{% endif %}' +
+          '{% endif %}',
+      },
+      decision_config: {
+        type: 'custom',
+        body: `["${DUNNING_KEY}"]`,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      context_datasets: [
+        {
+          dataset_type: 'message',
+          where_clause:
+            `m.legal_entity_id = '{{ legal_entity_id }}' AND m.decision_key = '${DUNNING_KEY}' ` +
+            "AND m.sent_at > NOW() - INTERVAL '30 days'",
+          limit: 1,
+          position: 0,
+        },
+      ],
+      actions: [
+        {
+          action_type: 'sms',
+          tool_id: ctx.smsToolId,
+          decision_key: DUNNING_KEY,
+          position: 0,
+          trigger_template: 'now',
+          idempotency_template: `{{ event_dataset.customer_number }}-${DUNNING_KEY}`,
+          connected_app_id: ctx.payAppId,
+          connected_app_route: '/portal/pay',
+          connected_app_metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
+          tool_call: {
+            tool_call_type: 'sms_request',
+            to: { type: 'custom', body: '{{ event_dataset.phone }}' },
+            body: {
+              type: 'custom',
+              body:
+                'Hi {{ event_dataset.name }}, an invoice on account ' +
+                '{{ event_dataset.customer_number }} needs your attention. ' +
+                'Pay now: {{ connected_app_form_url }}',
+            },
+            sms_type: 'transactional',
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.dunningWorkflowSlug = dunningWorkflow.slug!
+```
+
+## 022 — run it, and prove the KYC gate is the one that bit
+
+The scope is the reachable customer and the one missing a tax identifier.
+**Both have a phone**, which is what makes this run prove something the
+welcome run could not: the row that gets filtered here is filtered by the
+second gate, not the first. Had the scope reused the no-phone customer, a
+filter that ignored `tax_id` entirely would still have produced the same
+one-passed-one-filtered split and looked green.
+
+That is the general lesson about filter tests. A pass/fail split only proves
+the gate you meant to test if the two rows differ in exactly that field.
+
+```typescript
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.dunningWorkflowSlug, {
+  sql_where_clause: `customer_number IN ('${ctx.reachNumber}', '${ctx.noKycNumber}')`,
+  mode: 'live',
+  manual_override: false,
+})
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.dunningRunBatchId = fired.batchId!
+
+const refreshDeadline = Date.now() + 120_000
+let status: string | null = null
+while (Date.now() < refreshDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.dunningWorkflowSlug, fired.workflowRunLogId,
+  )
+  status = log.status ?? null
+  if (status && status !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (status === 'failed') throw new Error('dunning run reached :failed')
+if (!status || status === 'pending') throw new Error('dunning run did not leave :pending within 120s')
+
+const welDeadline = Date.now() + 90_000
+let ourLogs: Array<Record<string, unknown>> = []
+let byStatus: Record<string, number> = {}
+while (Date.now() < welDeadline) {
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(
+    tenantSlug, datalakeSlug, ctx.dunningWorkflowSlug, { page_size: 100 },
+  )
+  ourLogs = (wfLogs.data ?? [])
+    .map((w) => w as Record<string, unknown>)
+    .filter((w) => w.batch_id === ctx.dunningRunBatchId)
+  byStatus = {}
+  for (const w of ourLogs) {
+    const st = (w.status as string | undefined) ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const settled = (byStatus.completed ?? 0) + (byStatus.executing ?? 0)
+  if (ourLogs.length === 2 && settled === 1 && (byStatus.filtered ?? 0) === 1) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (ourLogs.length !== 2) {
+  throw new Error(`expected 2 execution logs for the dunning run, got ${ourLogs.length}`)
+}
+if ((byStatus.executing ?? 0) + (byStatus.completed ?? 0) !== 1) {
+  throw new Error(`expected 1 row past the KYC gate — distribution ${JSON.stringify(byStatus)}`)
+}
+if ((byStatus.filtered ?? 0) !== 1) {
+  throw new Error(
+    `expected the customer with no tax_id to be :filtered — distribution ${JSON.stringify(byStatus)}`,
+  )
+}
+```
+
+## 023 — the reminder went out, and it is a different message on a different app
+
+Same read-back idiom as §019, and worth doing twice for one reason: it proves
+the two workflows are genuinely independent. The same customer received two
+messages, under two idempotency keys, carrying two links that resolve against
+two connected apps and two routes.
+
+The key here is `<customer number>-send_dunning_sms`, and it names a row that
+persists in the lake long after the run that made it. That is what a
+read-back should ask for — the durable record, not the run.
+
+```typescript
+const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key = '${ctx.reachNumber}-send_dunning_sms'`,
+})
+if (search.status !== 'completed') {
+  throw new Error(`message user-search status=${search.status} error=${search.error_message ?? '(none)'}`)
+}
+
+const msgDeadline = Date.now() + 90_000
+let dunningBody: string | undefined
+while (Date.now() < msgDeadline && !dunningBody) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: search.id!,
+    dataAccessMode: 'raw',
+  })
+  dunningBody = ((data.data ?? []) as Array<Record<string, unknown>>)
+    .map((m) => String(m.body ?? ''))
+    .find((body) => body.includes('/t/') && body.includes('needs your attention'))
+  if (!dunningBody) await new Promise((r) => setTimeout(r, 2_000))
+}
+if (!dunningBody) {
+  throw new Error(`no rendered dunning SMS for ${ctx.reachNumber} within 90s`)
+}
+if (!dunningBody.includes(ctx.reachNumber)) {
+  throw new Error(`the dunning body does not name the overdue account: ${dunningBody}`)
+}
+
+const token = dunningBody.match(/\/t\/([A-Za-z0-9_-]+)/)
+if (!token) throw new Error(`no /t/<token> in the dunning body: ${dunningBody}`)
+
+const { data: resolved } = await api.connectedApps.resolvePage(
+  tenantSlug, datalakeSlug, ctx.payAppSlug,
+  { short_path: token[1]!, user_agent: 'cookbook-doctest/subscription-saas' },
+)
+if (resolved.route_path !== '/portal/pay') {
+  throw new Error(`the dunning link resolved to the wrong route: ${resolved.route_path}`)
+}
+```
+
+## 024 — the LLM tool
+
+The welcome and dunning workflows fire the *same* action for everything that
+passes their filter. The third scenario is the opposite shape: which message
+goes out depends on what kind of account it is, and that is a judgement over
+the row rather than a rule about it.
+
+That judgement needs a model, and a model needs a tool. This one is a
+**provider adapter**, and the two halves are the thing to read. `base_body`
+authors the provider's own request — here Ollama's native `/api/chat` shape,
+with `think: false` and a `format` schema so the model returns
+schema-constrained JSON instead of prose with JSON in it. `response_extractor`
+maps the provider's reply back onto the canonical
+`{ output_json, input_tokens, … }` the platform expects, and its
+`output_schema` is required for an `llm_enrichment` tool.
+
+Swapping providers is a matter of rewriting those two templates. Nothing
+downstream — not the agent, not the workflow — knows which model answered.
+
+```typescript
+const ENRICHMENT_OUTPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    output_json: {},
+    input_tokens: { type: ['integer', 'null'] },
+    output_tokens: { type: ['integer', 'null'] },
+    total_tokens: { type: ['integer', 'null'] },
+    explanation: { type: ['string', 'null'] },
+  },
+  required: ['output_json'],
+}
+
+const OLLAMA_BASE_BODY =
+  '{"model": "{{ model }}", "messages": [{"role": "user", "content": "{{ rendered_prompt | json_escape }}", ' +
+  '"images": [{% for img in images %}{% unless forloop.first %}, {% endunless %}"{{ img.data }}"{% endfor %}]}], ' +
+  '"stream": false, "think": false, "options": {"temperature": {{ temperature }}, "num_predict": {{ max_tokens }}, "num_ctx": 40960}, "format": {{ schema | to_json }}}'
+
+const OLLAMA_EXTRACTOR =
+  '{"output_json": "{{ msg.message.content | json_escape }}", ' +
+  '"explanation": "{{ msg.message.thinking | json_escape }}", ' +
+  '"input_tokens": {{ msg.prompt_eval_count | default: 0 }}, ' +
+  '"output_tokens": {{ msg.eval_count | default: 0 }}, ' +
+  '"total_tokens": {{ msg.prompt_eval_count | default: 0 | plus: msg.eval_count }}}'
+
+const llmTool = await ctx.ensure(
+  'LLM tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Billing LLM Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Billing LLM Tool',
+      description: 'Ollama-backed chat-completion adapter for account-priority triage.',
+      intent: 'llm_enrichment',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      response_extractor: { type: 'custom', body: OLLAMA_EXTRACTOR, output_schema: ENRICHMENT_OUTPUT_SCHEMA },
+      body: {
+        tool_body_type: 'rest_api',
+        base_url: 'http://localhost:11434',
+        base_path: { type: 'custom', body: '/api/chat' },
+        auth_method: 'api_key',
+        api_key: 'stub-key',
+        api_key_name: 'Authorization',
+        api_key_location: 'header',
+        request_type: 'json',
+        response_type: 'json',
+        timeout_ms: 60_000,
+        base_body: { type: 'custom', body: OLLAMA_BASE_BODY },
+      },
+    })
+    return data
+  },
+)
+ctx.llmToolId = llmTool.id!
+```
+
+## 025 — the Priority Triage agent
+
+The agent binds three things the workflow cannot supply for itself: the
+model, an `input_schema` the workflow's context mapping must satisfy, and an
+`llm_response_schema` whose `enum` pins the vocabulary.
+
+**The enum is the load-bearing part.** The workflow interpolates the band
+straight into its decision array, so a model that answers `"high priority"`
+instead of `priority_high` would produce a decision key no action is
+registered for, and the row would silently do nothing. Constraining the
+schema means the failure happens at the model boundary where it is legible,
+not three layers down as an empty result.
+
+`temperature: 0.0` makes identical inputs classify identically, which is what
+lets §027 assert on the outcome at all.
+
+`data_access: 'raw'` is the right call **on this surface and only on this
+surface**. There is no derived lake here to read from, and the agent's prompt
+takes the account number and the account type — no name, no email, no phone.
+On `payments-compliance` the equivalent agent runs `tokenized`, because there
+the model is reading a record that carries identity and the point is that it
+never sees it. The tier follows what the prompt actually contains.
+
+```typescript
+const TRIAGE_PROMPT_BODY = `You are an account-priority triage assistant for a subscription billing team. Classify the customer into EXACTLY ONE band by account type:
+
+- "priority_high"   — enterprise (large account, high balance, white-glove outreach)
+- "priority_medium" — individual (standard self-serve account)
+- "priority_low"    — government (long payment cycles, low urgency)
+
+Customer number: {{ customer_number }}
+Customer type: {{ customer_type }}
+
+Respond with JSON: {"priority_band": "<one of priority_high|priority_medium|priority_low>"}`
+
+const triageAgent = await ctx.ensure(
+  'Priority Triage agent',
+  async () => {
+    const { data } = await api.aiAgents.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Priority Triage Agent')
+  },
+  async () => {
+    const { data } = await api.aiAgents.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Priority Triage Agent',
+      tool_id: ctx.llmToolId,
+      model: 'qwen3-vl:8b-instruct',
+      data_access: 'raw',
+      temperature: 0.0,
+      max_tokens: 1024,
+      enabled: true,
+      input_schema: {
+        type: 'object',
+        properties: {
+          customer_number: { type: 'string' },
+          customer_type: { type: 'string' },
+        },
+        required: ['customer_number', 'customer_type'],
+      },
+      llm_response_schema: {
+        type: 'object',
+        properties: {
+          priority_band: {
+            type: 'string',
+            enum: ['priority_high', 'priority_medium', 'priority_low'],
+          },
+        },
+        required: ['priority_band'],
+      },
+      prompt_config: { type: 'custom', body: TRIAGE_PROMPT_BODY },
+    })
+    return data
+  },
+)
+aiAgentId = triageAgent.id!
+ctx.triageAgentSlug = triageAgent.slug!
+```
+
+## 026 — the Priority Triage workflow
+
+Two things make this workflow agent-driven rather than rule-driven.
+
+The agent is **nested in the create body** — `workflow_ai_agents` is a
+`cast_assoc`, not a separate attach call — together with a Liquid
+`context_mapping_config` that projects each row into the agent's input
+schema. A workflow join omits `output_schema`; the server pins it from the
+agent's own `input_schema`, so the two cannot drift apart.
+
+The `decision_config` then interpolates the agent's answer into a
+single-element decision array, and three actions are registered, one per
+band. Whichever band comes back picks one and leaves the other two
+`:skipped`.
+
+**Bracket access is required, not stylistic.** The agent's slug contains
+hyphens, and Liquid's dot parser would read
+`additional_context.cookbook-priority-triage-agent` as a subtraction.
+
+```typescript
+const BANDS = ['priority_high', 'priority_medium', 'priority_low'] as const
+
+const CONTEXT_MAPPING_BODY = JSON.stringify({
+  customer_number: '{{ event_dataset.customer_number }}',
+  customer_type: '{{ event_dataset.customer_type }}',
+})
+
+const triageWorkflow = await ctx.ensure(
+  'Priority Triage workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Priority Triage Workflow')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Priority Triage Workflow',
+      description: 'Bands accounts high/medium/low via an LLM agent; one SMS action per band.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.customersTableId,
+      status: 'live',
+      tags: ['billing', 'triage'],
+      skip_mdm_resolution: false,
+      filter_config: {
+        type: 'custom',
+        body:
+          '{% if event_dataset.phone and event_dataset.phone != "" %}' +
+          '{% if event_dataset.tax_id and event_dataset.tax_id != "" %}true{% endif %}' +
+          '{% endif %}',
+      },
+      decision_config: {
+        type: 'custom',
+        body: `["{{ additional_context["${ctx.triageAgentSlug}"].priority_band }}"]`,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      actions: BANDS.map((band) => ({
+        decision_key: band,
+        action_type: 'sms' as const,
+        tool_id: ctx.smsToolId,
+        position: 0,
+        trigger_template: 'now',
+        idempotency_template: `{{ event_dataset.customer_number }}-${band}`,
+        tool_call: {
+          tool_call_type: 'sms_request' as const,
+          to: { type: 'custom' as const, body: '{{ event_dataset.phone }}' },
+          body: {
+            type: 'custom' as const,
+            body: `[${band}] {{ event_dataset.name }}, a note about account {{ event_dataset.customer_number }}.`,
+          },
+          sms_type: 'transactional' as const,
+        },
+      })),
+      workflow_ai_agents: [
+        {
+          ai_agent_id: aiAgentId,
+          position: 0,
+          context_mapping_config: { type: 'custom', body: CONTEXT_MAPPING_BODY },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.triageWorkflowSlug = triageWorkflow.slug!
+```
+
+## 027 — the agent's band steered the fan-out
+
+The scope is the individual and the enterprise account — both reachable, both
+KYC-complete, so both clear the filter and reach the agent. They differ only
+in `customer_type`, which is the one thing the agent is asked about.
+
+Each row produces an execution log carrying **three** action logs, one per
+band. On the first run for a given customer exactly **one** is matched
+(`:pending` or `:completed` — the band the agent chose) and **two** are
+`:skipped`. That one-of-three is the proof the model's output drove the
+decision rather than every action firing.
+
+**On a later run all three are `:skipped`, and that is correct.** The
+idempotency key is `<customer number>-<band>`, the customer numbers are
+stable, so the key that already fired refuses to fire again — the platform
+will not send the same message about the same account twice. Both shapes are
+accepted here; anything else is a real failure. Two matched means the
+decision matched more than one band. Zero matched with zero skipped means the
+fan-out never happened at all.
+
+```typescript
+const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.triageWorkflowSlug, {
+  sql_where_clause: `customer_number IN ('${ctx.reachNumber}', '${ctx.enterpriseNumber}')`,
+  mode: 'live',
+  manual_override: false,
+})
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.triageRunBatchId = fired.batchId!
+
+const refreshDeadline = Date.now() + 180_000
+let status: string | null = null
+while (Date.now() < refreshDeadline) {
+  const { data: log } = await api.workflows.batchLogs.refresh(
+    tenantSlug, datalakeSlug, ctx.triageWorkflowSlug, fired.workflowRunLogId,
+  )
+  status = log.status ?? null
+  if (status && status !== 'pending') break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (status === 'failed') throw new Error('triage run reached :failed')
+if (!status || status === 'pending') throw new Error('triage run did not leave :pending within 180s')
+
+const welDeadline = Date.now() + 180_000
+let ourLogs: Array<Record<string, unknown>> = []
+while (Date.now() < welDeadline) {
+  const { data: wfLogs } = await api.workflows.workflowLogs.list(
+    tenantSlug, datalakeSlug, ctx.triageWorkflowSlug, { page_size: 100 },
+  )
+  ourLogs = (wfLogs.data ?? [])
+    .map((w) => w as Record<string, unknown>)
+    .filter((w) => w.batch_id === ctx.triageRunBatchId)
+  const settled = ourLogs.filter(
+    (w) => ((w.action_execution_logs as unknown[] | undefined) ?? []).length === 3,
+  )
+  if (ourLogs.length === 2 && settled.length === 2) break
+  await new Promise((r) => setTimeout(r, 2_000))
+}
+if (ourLogs.length !== 2) {
+  throw new Error(`expected 2 execution logs for the triage run, got ${ourLogs.length}`)
+}
+
+for (const wel of ourLogs) {
+  const welId = (wel as { id?: string }).id
+  const aels = (wel as { action_execution_logs?: Array<{ status?: string }> }).action_execution_logs ?? []
+  if (aels.length !== 3) {
+    throw new Error(`log ${welId}: expected 3 action logs (one per band), got ${aels.length}`)
+  }
+  const byStatus: Record<string, number> = {}
+  for (const ael of aels) {
+    const st = ael.status ?? 'unknown'
+    byStatus[st] = (byStatus[st] ?? 0) + 1
+  }
+  const matched = (byStatus.pending ?? 0) + (byStatus.completed ?? 0)
+  const skipped = byStatus.skipped ?? 0
+  if (matched === 1 && skipped === 2) continue   // first run for this account
+  if (matched === 0 && skipped === 3) continue   // already fired, correctly refusing
+  throw new Error(
+    `log ${welId}: expected 1 matched + 2 skipped, or 3 skipped on a repeat run — got ${JSON.stringify(byStatus)}`,
+  )
+}
+```
+
+## 028 — the enterprise account was banded high, and the SMS says so
+
+§027 proved the fan-out chose one action per row. This proves *which* one,
+and it is the assertion that survives every rerun because it reads the
+durable message rather than the run that made it.
+
+The enterprise account is the one asserted, because it is the only row whose
+band is genuinely unambiguous — the prompt says enterprise means
+`priority_high` in as many words, and a model that gets this wrong at
+temperature zero is a model worth knowing about.
+
+The search is on the idempotency key, as always. Note the shape of it here:
+`<customer number>-priority_high` names the message the *high* action would
+have sent, so finding it is itself the band assertion. There is no need to
+parse the band back out of the body — though the body is checked too, since a
+message under the right key carrying the wrong copy would mean the actions
+are mis-wired to each other's templates.
+
+```typescript
+const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+  search_query: `m.idempotency_key = '${ctx.enterpriseNumber}-priority_high'`,
+})
+if (search.status !== 'completed') {
+  throw new Error(`message user-search status=${search.status} error=${search.error_message ?? '(none)'}`)
+}
+
+const msgDeadline = Date.now() + 90_000
+let bandBody: string | undefined
+while (Date.now() < msgDeadline && !bandBody) {
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: search.id!,
+    dataAccessMode: 'raw',
+  })
+  bandBody = ((data.data ?? []) as Array<Record<string, unknown>>)
+    .map((m) => String(m.body ?? ''))
+    .find((body) => body.includes('[priority_high]'))
+  if (!bandBody) await new Promise((r) => setTimeout(r, 2_000))
+}
+if (!bandBody) {
+  throw new Error(
+    `no priority_high SMS for ${ctx.enterpriseNumber} within 90s — ` +
+      'the agent banded the enterprise account somewhere else, or the action never fired',
+  )
+}
+if (!bandBody.includes(ctx.enterpriseNumber)) {
+  throw new Error(`the banded SMS does not name the account: ${bandBody}`)
+}
+```
+
+## 029 — a whole file at once: mint an upload link and PUT the CSV
+
+Everything so far arrived one row at a time in an ingest call's body. That is
+the wrong shape for a backfill or a nightly export, where the file already
+exists and has four thousand rows in it.
+
+The bulk path is three calls plus a discovery step:
+
+1. `datalakes.createUploadLink` returns a presigned PUT `url` and the storage
+   `key` the platform will reference.
+2. A **raw `fetch`** PUTs the bytes to that URL. This one goes straight to
+   object storage and is deliberately not an SDK call — the SDK talks to the
+   platform, and the platform is not in this hop.
+3. `dataActivationClients.ingestFile` enqueues a job against the key.
+4. The worker reads the file, allocates a **fresh `batch_id` it does not
+   return**, and fans out per-row jobs. You discover that id by diffing the
+   client's logs.
+
+The file is the vendored four-row Stripe export. Its customer numbers are
+`CUS-10001`–`CUS-10004`, disjoint from the four inline rows, so this scenario
+adds rows rather than colliding with them.
+
+```typescript
+const { readFileSync } = await import('node:fs')
+const { join } = await import('node:path')
+const csvBody = readFileSync(
+  join(process.env.COOKBOOK_FIXTURES_DIR!, 'subscription-saas', 'stripe_customers_batch1.csv'),
+  'utf8',
+)
+
+const { data: link } = await api.datalakes.createUploadLink(tenantSlug, datalakeSlug, {
+  content_type: 'text/csv',
+  filename: 'stripe_customers_batch1.csv',
+})
+ctx.uploadKey = link.key!
+
+const put = await fetch(link.url!, {
+  method: 'PUT',
+  headers: { 'Content-Type': 'text/csv' },
+  body: csvBody,
+})
+if (put.status !== 200) {
+  throw new Error(`presigned PUT failed: ${put.status}`)
+}
+```
+
+## 030 — enqueue the same file twice, identity first
+
+The split from §012 applies here too, and the file makes it cheaper rather
+than more expensive: **one upload, two enqueues**. The key names an object in
+storage, and nothing about it is bound to a client, so the identity client and
+the data client can each be pointed at the same bytes.
+
+The order is the whole point. The identity enqueue runs and is waited on to
+completion; only then does the data enqueue go, and by that time every subject
+the second pass will resolve is already committed.
+
+`ingestFile` returns a `job_id` and no `batch_id`, so each pass snapshots the
+client's existing batch ids first and then watches for the new one. The gate
+is `dataset_updated`, not `rows_ingested` — a file whose rows were all read
+and none written reports the former and not the latter.
+
+```typescript
+ctx.ingestFileAndWait = async (dacSlug: string, expectRows: number): Promise<string> => {
+  const { data: pre } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, dacSlug)
+  const seen = new Set(
+    (pre.data ?? [])
+      .map((r) => (r as { batch_id?: string }).batch_id)
+      .filter((b): b is string => typeof b === 'string'),
+  )
+
+  const { data: job } = await api.dataActivationClients.ingestFile(tenantSlug, datalakeSlug, dacSlug, {
+    key: ctx.uploadKey,
+  })
+  if (!job.job_id) throw new Error(`ingestFile on ${dacSlug} did not return a job_id`)
+
+  const deadline = Date.now() + 180_000
+  while (Date.now() < deadline) {
+    const { data } = await api.dataActivationClients.logs.list(tenantSlug, datalakeSlug, dacSlug)
+    for (const row of (data.data ?? []) as Array<Record<string, unknown>>) {
+      const b = row.batch_id
+      if (typeof b !== 'string' || seen.has(b)) continue
+      if (row.status === 'partial' || row.status === 'failed') {
+        throw new Error(
+          `bulk batch ${b} on ${dacSlug} did not persist its rows (status: ${row.status}): ` +
+            `${String(row.error ?? 'no reason given')}`,
+        )
+      }
+      if (typeof row.dataset_updated !== 'number' || row.dataset_updated < expectRows) continue
+      if (!Array.isArray(row.output_files) || row.output_files.length === 0) continue
+      return b
+    }
+    await new Promise((r) => setTimeout(r, 1_000))
+  }
+  throw new Error(`no new fully-merged batch appeared on ${dacSlug} within 180s`)
+}
+
+// Stage one — four legal entities.
+await ctx.ingestFileAndWait(ctx.identityDacSlug, 4)
+// Stage two — four table rows, stamped with the subjects stage one wrote.
+ctx.bulkBatchId = await ctx.ingestFileAndWait(ctx.dataDacSlug, 4)
+```
+
+## 031 — every uploaded row landed, and every one is stamped
+
+Both halves, scoped to the batch the worker allocated. The table side is read
+through read-only SQL; the identity side through the dataset search, where
+`le` is the legal-entity alias the query compiler expects.
+
+The stamp check is the one that matters, and it is the same check §014 ran on
+the inline rows. Whether a row arrived in a JSON body or in a CSV, it is the
+same contract pair on the far side, and the proof that both contracts ran is a
+non-null `legal_entity_id` on a column no contract writes.
+
+Note what is *not* asserted: an exact legal-entity count. This lake already
+holds subjects from the inline rows, and a fresh-tenant assumption is exactly
+the kind that goes red on the second run. The query is scoped to this batch,
+and four is the floor.
+
+```typescript
+const sqlDeadline = Date.now() + 120_000
+let tableRows: unknown[][] = []
+while (Date.now() < sqlDeadline && tableRows.length < 4) {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT customer_number, legal_entity_id
+          FROM ${ctx.customersTableName}
+          WHERE customer_number IN ('CUS-10001', 'CUS-10002', 'CUS-10003', 'CUS-10004')
+          ORDER BY customer_number`,
+    mode: 'raw',
+  })
+  if (typeof result !== 'string') tableRows = result.data
+  if (tableRows.length < 4) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (tableRows.length !== 4) {
+  throw new Error(`expected the 4 uploaded rows in the table, found ${tableRows.length} within 120s`)
+}
+const unstamped = tableRows.filter((row) => !row[1]).map((row) => String(row[0]))
+if (unstamped.length > 0) {
+  throw new Error(`uploaded rows landed with no legal_entity_id stamp: ${unstamped.join(', ')}`)
+}
+
+const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'legal_entity', {
+  search_query: `le.batch_id = '${ctx.bulkBatchId}'`,
+})
+if (search.status !== 'completed') {
+  throw new Error(`legal_entity user-search did not compile: ${search.status}`)
+}
+const { data: page } = await api.datasets.search(tenantSlug, datalakeSlug, 'legal_entity', {
+  userSearchId: search.id!,
+  dataAccessMode: 'raw',
+})
+if (!Array.isArray(page.data)) {
+  throw new Error('legal_entity search returned no rows array')
+}
+```
+
+## 032 — the REST tool: let the platform do the fetching
+
+The third way in does not wait for a file or a call. A **pull-based** client
+goes and gets the rows itself, on a schedule or on demand, and the platform
+holds the credential rather than your code.
+
+The tool carries the API's base URL and its auth. `auth_method: 'bearer'`
+with a static token is the simplest case; the OAuth2 shape is §036.
+`status: 'active'` is not decoration — a draft tool is skipped at fetch time,
+and the symptom is a run that reports success and ingests nothing.
+
+Locally the target is the integration stack's WireMock on `:8080`, which
+answers `GET /stripe/v1/customers` with three customers: two individuals and
+one enterprise, numbered `CUS-20001`–`CUS-20003`.
+
+```typescript
+const restTool = await ctx.ensure(
+  'Stripe REST tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Stripe REST Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Stripe REST Tool',
+      description: 'Mocked Stripe REST API — the pull-based customer fetch.',
+      intent: 'data_exchange',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: ctx.dataSourceId,
+      body: {
+        tool_body_type: 'rest_api',
+        auth_method: 'bearer',
+        base_url: 'http://localhost:8080/stripe',
+        bearer_token: 'sk_test_vitest_stripe_token',
+        request_type: 'json',
+        response_type: 'json',
+        timeout_ms: 30_000,
+      },
+    })
+    return data
+  },
+)
+ctx.restToolId = restTool.id!
+```
+
+## 033 — two fetch clients, for the same reason as before
+
+The client's `tool_call` is what turns a REST tool into a fetch: the HTTP
+`method` and the `path` to append to the tool's `base_url`, plus a
+`pagination_context_template` declaring whether there is more to get. This
+endpoint answers in one page, so it declares `has_next: false`.
+
+The `response_extractor` unwraps the API's envelope. Stripe answers
+`{ object: "list", data: [...] }`, and each element of that array has to
+become one row — `{{ msg.data | to_json }}` is the whole of it.
+
+And the pair is split across two clients again. Nothing about the fetch
+changes the reason: two contracts on one client resolve the same subject at
+the same instant, and one of them loses. Both clients hit the same endpoint
+and get the same three customers; they differ only in what they do with them.
+
+```typescript
+const restFetchCall = {
+  tool_call_type: 'restapi_request' as const,
+  method: 'get' as const,
+  path: { type: 'custom' as const, body: '/v1/customers' },
+  pagination_context_template: { type: 'custom' as const, body: '{"has_next": false}' },
+}
+const restExtractor = { type: 'custom' as const, body: '{{ msg.data | to_json }}' }
+
+const restIdentityDac = await ctx.ensure(
+  'REST identity client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Stripe REST Identity DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Stripe REST Identity DAC',
+      description: 'Fetches Stripe customers and writes their legal entities. Runs FIRST.',
+      tool_id: ctx.restToolId,
+      data_source_id: ctx.dataSourceId,
+      tool_call: restFetchCall,
+      response_extractor: restExtractor,
+      interoperability_contract_ids: [ctx.leContractId],
+    })
+    return data
+  },
+)
+ctx.restIdentityDacSlug = restIdentityDac.slug!
+
+const restDataDac = await ctx.ensure(
+  'REST data client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Stripe REST Data DAC')
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Stripe REST Data DAC',
+      description: 'Fetches the same customers and writes the table rows. Runs SECOND.',
+      tool_id: ctx.restToolId,
+      data_source_id: ctx.dataSourceId,
+      tool_call: restFetchCall,
+      response_extractor: restExtractor,
+      interoperability_contract_ids: [ctx.gtContractId],
+    })
+    return data
+  },
+)
+ctx.restDataDacSlug = restDataDac.slug!
+```
+
+## 034 — trigger both fetches, in order
+
+`runManually` differs from `ingest` and `ingestFile` in a useful way: it
+returns the `batch_id` immediately, because the platform allocates it when it
+schedules the fetch rather than when a worker opens a file. The HTTP call and
+the ingestion still happen in the background.
+
+Same staging, same reason. The identity fetch is waited on to completion
+before the data fetch is triggered.
+
+```typescript
+const { data: identityRun } = await api.dataActivationClients.runManually(
+  tenantSlug, datalakeSlug, ctx.restIdentityDacSlug,
+)
+if (!identityRun.batch_id) throw new Error('the identity fetch did not return a batch_id')
+await ctx.waitForBatches(ctx.restIdentityDacSlug, [identityRun.batch_id], 180_000)
+
+const { data: dataRun } = await api.dataActivationClients.runManually(
+  tenantSlug, datalakeSlug, ctx.restDataDacSlug,
+)
+if (!dataRun.batch_id) throw new Error('the data fetch did not return a batch_id')
+ctx.restBatchId = dataRun.batch_id
+await ctx.waitForBatches(ctx.restDataDacSlug, [ctx.restBatchId], 180_000)
+```
+
+## 035 — three fetched customers, in the same table as everything else
+
+This is the point of the whole scenario, and it is worth saying plainly:
+these three rows are indistinguishable from the four that arrived inline and
+the four that arrived in a CSV. Same table, same contracts, same stamp. The
+entry point is the only thing that differed, and it stopped mattering the
+moment the row was extracted.
+
+The read filters on `customer_number`, a `none` column. The tokenized columns
+would answer here too — this lake has no derived copy, so raw is all there is
+— but filtering on a column declared `tokenize` is a habit that breaks the day
+someone provisions the pair.
+
+```typescript
+const sqlDeadline = Date.now() + 120_000
+let fetched: unknown[][] = []
+while (Date.now() < sqlDeadline && fetched.length < 3) {
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT customer_number, customer_type, legal_entity_id
+          FROM ${ctx.customersTableName}
+          WHERE customer_number IN ('CUS-20001', 'CUS-20002', 'CUS-20003')
+          ORDER BY customer_number`,
+    mode: 'raw',
+  })
+  if (typeof result !== 'string') fetched = result.data
+  if (fetched.length < 3) await new Promise((r) => setTimeout(r, 1_000))
+}
+if (fetched.length !== 3) {
+  throw new Error(`expected the 3 fetched rows in the table, found ${fetched.length} within 120s`)
+}
+const unstamped = fetched.filter((row) => !row[2]).map((row) => String(row[0]))
+if (unstamped.length > 0) {
+  throw new Error(`fetched rows landed with no legal_entity_id stamp: ${unstamped.join(', ')}`)
+}
+const enterprise = fetched.find((row) => String(row[1]) === 'enterprise')
+if (!enterprise) {
+  throw new Error('the fetch did not produce the enterprise customer the endpoint returns')
+}
+```
+
+## 036 — the OAuth2 variant, for an API that will not take a static token
+
+Most real APIs will not. When the credential is an OAuth2 grant, the tool
+carries the whole grant config instead of a token, and **the platform
+exchanges the stored refresh token for an access token server-side before
+each fetch**. Your code never holds one, never refreshes one, never logs one.
+
+`oauth2_grant_type` names the flow the credential came from —
+`authorization_code` here, the ordinary three-legged flow whose long-lived
+refresh token you keep. It is not `refresh_token`: the enum is
+`client_credentials | authorization_code`, and refreshing is what the
+platform does with the grant rather than a grant of its own.
+
+Everything else is unchanged — the client, its `tool_call`, the contracts,
+the table. Swapping auth is a tool-level edit.
+
+This step creates the tool to show the shape and stops there; the mock
+endpoint has no OAuth2 server behind it, and a fetch that cannot succeed
+proves less than a create that validates.
+
+```typescript
+const oauthTool = await ctx.ensure(
+  'OAuth2 REST tool',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug, { page_size: 100 })
+    return ctx.firstNamed(data.data, 'Cookbook Stripe OAuth2 Tool')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Stripe OAuth2 Tool',
+      description: 'Shape reference — the same fetch behind an OAuth2 refresh-token grant.',
+      intent: 'data_exchange',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      data_source_id: ctx.dataSourceId,
+      body: {
+        tool_body_type: 'rest_api',
+        auth_method: 'oauth2',
+        base_url: 'http://localhost:8080/stripe',
+        oauth2_grant_type: 'authorization_code',
+        oauth2_token_url: 'http://localhost:8080/oauth/token',
+        oauth2_client_id: 'cookbook-client',
+        oauth2_client_secret: 'cookbook-secret',
+        oauth2_refresh_token: 'cookbook-refresh-token',
+        oauth2_token_ttl: 3300,
+        request_type: 'json',
+        response_type: 'json',
+        timeout_ms: 30_000,
+      },
+    })
+    return data
+  },
+)
+if (!oauthTool.id) {
+  throw new Error('the OAuth2 tool was not persisted')
+}
+```
+
+## 037 — a billing team is not one person
+
+Everything so far ran as one admin. The last scenario adds a second person to
+the tenant, entirely through the SDK — no console, no out-of-band step.
+
+The flow touches all three session scopes, and mixing them up is the single
+most common mistake here:
+
+- **tenant-scoped** — the admin creates the invitation. Only an admin can.
+- **root** — signs the new user up and confirms them. A tenant admin can
+  invite, but only root can create the underlying account.
+- **tenantless** — the invitee, who belongs to no tenant yet, lists the
+  invitations waiting for them and accepts one.
+
+Start by confirming the current session really is a tenant-scoped admin of
+the expected tenant. `sessions.verify` echoes both.
+
+```typescript
+const { data: who } = await api.sessions.verify()
+if (who.tenant?.slug !== tenantSlug) {
+  throw new Error(`expected an admin session on ${tenantSlug}, got ${who.tenant?.slug}`)
+}
+if (!/admin/i.test(who.role?.name ?? '')) {
+  throw new Error(`expected an admin role, got ${who.role?.name}`)
+}
+```
+
+## 038 — the teammate's account, created by root
+
+The invitee needs an account before they can accept anything. Signup and
+confirmation are root-scoped, so this runs on the root client from §001 —
+`confirmUser` is what activates the account so they can sign in at all.
+
+The email is stable, like every other name in this walk, so the second run
+finds the account already there. Same catch-and-inspect as §001: a refusal
+that says the address is taken is the idempotent path, and anything else is
+re-raised.
+
+```typescript
+ctx.teammateEmail = 'cookbook-subscription-teammate@dev.local'
+ctx.teammatePassword = 'CookbookPass1!'
+
+try {
+  const { data: teammate } = await ctx.rootApi.admin.signUp({
+    email: ctx.teammateEmail,
+    password: ctx.teammatePassword,
+    first_name: 'Emma',
+    last_name: 'Wilson',
+  })
+  await ctx.rootApi.admin.confirmUser(teammate.id!)
+} catch (err) {
+  const detail = JSON.stringify((err as { errors?: unknown }).errors ?? err)
+  if (!/taken|already|exist/i.test(detail)) throw err
+}
+```
+
+## 039 — the invitation
+
+The admin invites by email and role. The invite is keyed on
+`(tenant, email)`, so a re-invitation is refused — and it is refused with
+**two different messages depending on how far the first run got**. While the
+invitation is still pending, `/email` says *"already invited"*. Once it has
+been accepted and consumed, the same call says *"already in this
+organization"*, because at that point the address does not belong to a
+pending invite but to a member.
+
+Both are the idempotent path and both are caught. What is **not** caught is
+anything else, and that distinction is the whole reason this is a `try`
+rather than a bare call: an invitation that fails because the tenant is
+misconfigured must not be read as "already there".
+
+```typescript
+try {
+  const { data: invite } = await api.invitations.create(tenantSlug, {
+    email: ctx.teammateEmail,
+    role: 'member',
+  })
+  if (invite.email !== ctx.teammateEmail || invite.role !== 'member') {
+    throw new Error(`unexpected invitation: ${JSON.stringify(invite)}`)
+  }
+} catch (err) {
+  const detail = JSON.stringify((err as { errors?: unknown }).errors ?? err)
+  // Both refusals, verbatim from the server. Matching loosely here is how a
+  // real failure gets swallowed, so the two known messages are named.
+  if (!/already invited|already in this organization/i.test(detail)) throw err
+}
+```
+
+## 040 — the teammate signs in with no tenant, and accepts
+
+The invitee has an account and belongs nowhere, so they sign in **tenantless**
+— `createBootstrapSession`, not `createSession`, which is tenant-login only.
+The resulting session carries `tenant: null`, and that is the assertion worth
+making: a client that quietly came back tenant-scoped would list the wrong
+invitations.
+
+Then the branch that makes this step idempotent. On the first run there is a
+pending invitation for this tenant and it is accepted. On every run after, the
+invitation has already been consumed and the list is empty — which is not a
+failure but the same end state reached earlier. **The proof is deferred to
+§041**, which asserts the end state directly rather than trusting either
+branch.
+
+Note that accepting does not upgrade the tenantless session in place. It
+creates the membership; the session that uses it is minted fresh in the next
+step.
+
+```typescript
+const teammateTenantless = await createBootstrapSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.teammateEmail,
+  password: ctx.teammatePassword,
+})
+if (teammateTenantless.tenant !== null) {
+  throw new Error('expected a tenantless session — tenant should be null')
+}
+const teammateTenantlessApi = createIsolatedPlatformApi({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  sessionToken: teammateTenantless.sessionToken,
+  apiKey: '',
+})
+
+const { data: invites } = await teammateTenantlessApi.invitations.list()
+const pending = (invites.data ?? []).find(
+  (i: { tenant?: { slug?: string } }) => i.tenant?.slug === tenantSlug,
+)
+
+if (pending?.id) {
+  const { data: membership } = await teammateTenantlessApi.invitations.accept(pending.id)
+  if (membership.tenant?.slug !== tenantSlug || membership.role !== 'member') {
+    throw new Error(`unexpected membership: ${JSON.stringify(membership)}`)
+  }
+} else {
+  console.log('  ↻ no pending invitation — already accepted on an earlier run')
+}
+```
+
+## 041 — the teammate signs in tenant-scoped, and is a member
+
+This is the assertion the whole scenario is for, and it is written against the
+end state rather than against the path taken to reach it — which is what makes
+it identical on run one and run fifty.
+
+The tenant-scoped sign-in needs the tenant's API key, the one minted in §004.
+Tenant login without a resolvable `X-API-Key` is a 401 regardless of how good
+the password is; the key identifies the tenant before the credentials
+identify the person.
+
+The role is the other half. A session that came back with an admin role would
+mean the invitation's `role: 'member'` was ignored, and everything downstream
+that trusts the platform to enforce a role would be resting on nothing.
+
+```typescript
+const teammateScoped = await createSession({
+  baseUrl: process.env.ALVERA_BASE_URL!,
+  email: ctx.teammateEmail,
+  password: ctx.teammatePassword,
+  tenantSlug,
+  apiKey: ctx.tenantApiKey,
+})
+if (teammateScoped.tenant?.slug !== tenantSlug) {
+  throw new Error(`expected a tenant-scoped session on ${tenantSlug}, got ${teammateScoped.tenant?.slug}`)
+}
+if (!/member/i.test(teammateScoped.role?.name ?? '')) {
+  throw new Error(`expected a member role, got ${teammateScoped.role?.name}`)
+}
+```
+
+# Outcome
+
+After all forty-one steps run green, on one tenant and **one raw datalake**:
+
+- **One customers table** holds eleven rows that arrived three different
+  ways — four inline through an ingest call, four from a CSV through a
+  presigned upload, three pulled from a REST API — and every one of them
+  carries a `legal_entity_id` stamp written by a contract that never
+  declares the column.
+- **Three workflows** run over that one table and disagree about which rows
+  matter. The welcome workflow gates on reachability, the dunning workflow on
+  reachability *and* KYC, and the triage workflow hands the question to a
+  model and fans out on its answer.
+- **Three outbound messages** are readable from the `message` dataset, each
+  under its own idempotency key, two carrying deep links that resolve against
+  two separate connected apps on two separate routes.
+- **A second person** is on the tenant with a `member` role, invited and
+  accepted entirely through the SDK.
+
+Four things this walk teaches that are easy to learn the expensive way:
+
+1. **Never bind a contract pair to one activation client.** The fan-out
+   staggers by row, so a pair on one client resolves the same subject twice
+   at the same instant and the unique index refuses the loser. Split them and
+   sequence them — §012, and again at §030 and §033.
+2. **Gate on `dataset_updated`, not `rows_ingested`.** Received is not
+   written. A refused row reports the first and not the second, and a walk
+   gated on the wrong one goes green over an empty table.
+3. **Search the idempotency key, never the workflow id.** The key is built
+   from a stable business id and names the same message forever; a workflow
+   id changes the moment the resource is recreated.
+4. **Assert the end state, not the transition.** An idempotency key fires
+   once ever, so every assertion here accepts both the first run's shape and
+   the repeat run's — §027 spells that out, and §040 defers its proof to
+   §041 for the same reason.
+
+# See also
+
+- `payments-compliance.md` — the same contract-pair shape on a tokenized
+  surface, with the derived lakes provisioned
+- `organic-marketing.md` — three scenarios on one raw lake, the sibling of
+  this walk
+- `../workflows.md` — the standard workflow primitive, `context_datasets`,
+  and `workflows.run`
+- `../data_activation_clients.md` — data source → tool → contract → client
+- `../interoperability_contracts.md` — `template_config` vs `mdm_input_config`
+- `../connected_apps.md` — registration, `resolvePage`, message tracking