@alvera-ai/platform-sdk 0.15.0 → 0.16.0

package/.agent/ai_agents.md

@@ -210,6 +210,7 @@ const { data: workflow } = await api.workflows.create(
   {
     name: 'Contact-Us Triage',
     dataset_type: 'generic_table',
+    tags: [],
     // …other workflow fields…
     workflow_ai_agents: [
       {

package/.agent/cookbook/_setup/foundation.md

@@ -256,6 +256,63 @@ if (datalakeStatus !== 'ready') {
 }
 ```
 
+## 007 — a reusable "wait until the run has fired" helper
+
+`workflows.run` only **schedules** a run. It records it and returns
+immediately with `workflow_run_id` / `status` / `scheduled_at`; the
+`workflow_run_log_id` and `batch_id` a scenario needs are written
+later, when the run actually fires, and are read back from
+`workflowRuns.get`.
+
+Two traps live in that gap, so every foundation scenario shares one
+helper rather than re-deriving it:
+
+- **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.
+
+The helper is stored on the shared `ctx` bag rather than declared as a
+plain function because each numbered step compiles into its own `it()`
+block — a bare `function` here would not be in scope for the steps that
+call it.
+
+```typescript
+const FIRED_TIMEOUT_MS = 60_000
+const FIRED_POLL_MS = 1_000
+
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs: number = FIRED_TIMEOUT_MS,
+): 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, FIRED_POLL_MS))
+  }
+  throw new Error(
+    `workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`,
+  )
+}
+```
+
 # Rollback
 
 The cookbook doctest harness does not currently tear down the
@@ -282,6 +339,11 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.tenantApiKey` — the tenant's publishable API key (minted in
   setup via `admin.createTenantApiKey`); thread it into any
   additional tenant-scoped `createSession` a scenario performs
+- `ctx.waitForFiredRun(datalakeSlug, runId)` — polls `workflowRuns.get`
+  until a scheduled run has actually fired, then returns its
+  `{ workflowRunLogId, batchId }`. Use it after every `workflows.run`;
+  reading `workflow_run_log_id` off the run response returns `null`
+  because run-workflow only schedules (see §007)
 
 Scenario cookbooks under `industry: foundation` start at their own
 `§001` with these slots already populated.

package/.agent/cookbook/_setup/healthcare.md

@@ -257,6 +257,63 @@ if (datalakeStatus !== 'ready') {
 }
 ```
 
+## 007 — a reusable "wait until the run has fired" helper
+
+`workflows.run` only **schedules** a run. It records it and returns
+immediately with `workflow_run_id` / `status` / `scheduled_at`; the
+`workflow_run_log_id` and `batch_id` a scenario needs are written
+later, when the run actually fires, and are read back from
+`workflowRuns.get`.
+
+Two traps live in that gap, so every healthcare scenario shares one
+helper rather than re-deriving it:
+
+- **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.
+
+The helper is stored on the shared `ctx` bag rather than declared as a
+plain function because each numbered step compiles into its own `it()`
+block — a bare `function` here would not be in scope for the steps that
+call it.
+
+```typescript
+const FIRED_TIMEOUT_MS = 60_000
+const FIRED_POLL_MS = 1_000
+
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs: number = FIRED_TIMEOUT_MS,
+): 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, FIRED_POLL_MS))
+  }
+  throw new Error(
+    `workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`,
+  )
+}
+```
+
 # Rollback
 
 The cookbook doctest harness does not currently tear down the
@@ -283,6 +340,11 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.tenantApiKey` — the tenant's publishable API key (minted in
   setup via `admin.createTenantApiKey`); thread it into any
   additional tenant-scoped `createSession` a scenario performs
+- `ctx.waitForFiredRun(datalakeSlug, runId)` — polls `workflowRuns.get`
+  until a scheduled run has actually fired, then returns its
+  `{ workflowRunLogId, batchId }`. Use it after every `workflows.run`;
+  reading `workflow_run_log_id` off the run response returns `null`
+  because run-workflow only schedules (see §007)
 
 Scenario cookbooks under `industry: healthcare` start at their own
 `§001` with these slots already populated.

package/.agent/cookbook/_setup/payments.md

@@ -261,6 +261,63 @@ if (datalakeStatus !== 'ready') {
 }
 ```
 
+## 007 — a reusable "wait until the run has fired" helper
+
+`workflows.run` only **schedules** a run. It records it and returns
+immediately with `workflow_run_id` / `status` / `scheduled_at`; the
+`workflow_run_log_id` and `batch_id` a scenario needs are written
+later, when the run actually fires, and are read back from
+`workflowRuns.get`.
+
+Two traps live in that gap, so every payments scenario shares one
+helper rather than re-deriving it:
+
+- **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.
+
+The helper is stored on the shared `ctx` bag rather than declared as a
+plain function because each numbered step compiles into its own `it()`
+block — a bare `function` here would not be in scope for the steps that
+call it.
+
+```typescript
+const FIRED_TIMEOUT_MS = 60_000
+const FIRED_POLL_MS = 1_000
+
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs: number = FIRED_TIMEOUT_MS,
+): 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, FIRED_POLL_MS))
+  }
+  throw new Error(
+    `workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`,
+  )
+}
+```
+
 # Rollback
 
 The cookbook doctest harness does not currently tear down the
@@ -287,6 +344,11 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.tenantApiKey` — the tenant's publishable API key (minted in
   setup via `admin.createTenantApiKey`); thread it into any
   additional tenant-scoped `createSession` a scenario performs
+- `ctx.waitForFiredRun(datalakeSlug, runId)` — polls `workflowRuns.get`
+  until a scheduled run has actually fired, then returns its
+  `{ workflowRunLogId, batchId }`. Use it after every `workflows.run`;
+  reading `workflow_run_log_id` off the run response returns `null`
+  because run-workflow only schedules (see §007)
 
 Scenario cookbooks under `industry: payments` start at their
 own `§001` with these slots already populated.

package/.agent/cookbook/_setup/subscription.md

@@ -260,6 +260,63 @@ if (datalakeStatus !== 'ready') {
 }
 ```
 
+## 007 — a reusable "wait until the run has fired" helper
+
+`workflows.run` only **schedules** a run. It records it and returns
+immediately with `workflow_run_id` / `status` / `scheduled_at`; the
+`workflow_run_log_id` and `batch_id` a scenario needs are written
+later, when the run actually fires, and are read back from
+`workflowRuns.get`.
+
+Two traps live in that gap, so every subscription scenario shares one
+helper rather than re-deriving it:
+
+- **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.
+
+The helper is stored on the shared `ctx` bag rather than declared as a
+plain function because each numbered step compiles into its own `it()`
+block — a bare `function` here would not be in scope for the steps that
+call it.
+
+```typescript
+const FIRED_TIMEOUT_MS = 60_000
+const FIRED_POLL_MS = 1_000
+
+ctx.waitForFiredRun = async (
+  runDatalakeSlug: string,
+  runId: string,
+  timeoutMs: number = FIRED_TIMEOUT_MS,
+): 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, FIRED_POLL_MS))
+  }
+  throw new Error(
+    `workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`,
+  )
+}
+```
+
 # Rollback
 
 The cookbook doctest harness does not currently tear down the
@@ -286,6 +343,11 @@ After this setup runs, the closure-scoped slots are populated as:
 - `ctx.tenantApiKey` — the tenant's publishable API key (minted in
   setup via `admin.createTenantApiKey`); thread it into any
   additional tenant-scoped `createSession` a scenario performs
+- `ctx.waitForFiredRun(datalakeSlug, runId)` — polls `workflowRuns.get`
+  until a scheduled run has actually fired, then returns its
+  `{ workflowRunLogId, batchId }`. Use it after every `workflows.run`;
+  reading `workflow_run_log_id` off the run response returns `null`
+  because run-workflow only schedules (see §007)
 
 Scenario cookbooks under `industry: subscription` start at
 their own `§001` with these slots already populated.

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

@@ -159,6 +159,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Sends a review-request SMS with a connected-app form link after a fulfilled appointment.',
   dataset_type: 'appointment',
   status: 'live',
+  tags: ['appointments', 'review'],
   skip_mdm_resolution: false,
   filter_config: {
     type: 'custom',
@@ -476,9 +477,11 @@ batches §009 ingested (`ra` is the regulated-appointments alias
 the run-query exposes).
 
 The SMS action's `trigger_template: 'now'` dispatches the action
-immediately rather than scheduling it, so the run reaches a
-terminal status on its own — poll `batchLogs.refresh` until it
-leaves `:pending`. A `:partial` status is expected and fine here:
+immediately rather than deferring it, so once the run fires it
+reaches a terminal status on its own — poll `batchLogs.refresh`
+until it leaves `:pending`. The run itself is still scheduled:
+`workflows.run` records it and returns, which is why the setup
+file's `ctx.waitForFiredRun` sits between the call and the log id. A `:partial` status is expected and fine here:
 one row passed and one was filtered.
 
 ```typescript
@@ -487,8 +490,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 120_000
 let status: string | null = null
@@ -692,14 +698,16 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id.
+// intercepted, and the acknowledgement carries the scheduled run id.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
   sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

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

@@ -157,6 +157,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: "Sends a happy-birthday SMS on each contact's next birthday — pure-Liquid trigger does the year-roll math.",
   dataset_type: 'legal_entity',
   status: 'live',
+  tags: ['lifecycle', 'birthday'],
   skip_mdm_resolution: false,
   filter_config: {
     type: 'custom',
@@ -398,8 +399,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 60_000
 let totalWels = 0
@@ -594,7 +598,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause must speak this workflow's selection dialect — the dataset
 // alias is `rle` here, the same alias the live run above uses.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
@@ -602,8 +606,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -310,6 +310,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   generic_table_id: genericTableId,
   skip_mdm_resolution: true,
   status: 'live',
+  tags: ['support', 'triage'],
   filter_config: {
     type: 'custom',
     body: 'true',
@@ -478,8 +479,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: true,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 240_000
 let status: string | null = null
@@ -560,7 +564,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause speaks this workflow's selection dialect: a GENERIC-TABLE
 // dataset is addressed by its own columns (no `ra.` dataset alias —
 // that alias exists only for system-dataset selections).
@@ -569,8 +573,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -162,6 +162,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Sends a payment-reminder SMS to delinquent contracted customers with a self-serve pay link.',
   dataset_type: 'customer',
   status: 'live',
+  tags: ['billing', 'dunning'],
   filter_config: {
     type: 'custom',
     body: FILTER_BODY,
@@ -395,9 +396,11 @@ exactly the two batches §008 ingested (`ra` is the
 regulated-customer alias the run-query exposes).
 
 The SMS action's `trigger_template: 'now'` dispatches the action
-immediately rather than scheduling it, so the run reaches a
-terminal status on its own — poll `batchLogs.refresh` until it
-leaves `:pending`. A `:partial` status is expected and fine here:
+immediately rather than deferring it, so once the run fires it
+reaches a terminal status on its own — poll `batchLogs.refresh`
+until it leaves `:pending`. The run itself is still scheduled:
+`workflows.run` records it and returns, which is why the setup
+file's `ctx.waitForFiredRun` sits between the call and the log id. A `:partial` status is expected and fine here:
 one row passed and one was filtered.
 
 ```typescript
@@ -406,8 +409,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 120_000
 let status: string | null = null
@@ -550,14 +556,16 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id.
+// intercepted, and the acknowledgement carries the scheduled run id.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
   sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

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

@@ -160,6 +160,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Sends a KYC-notification SMS for newly activated payment accounts with a self-serve KYC portal link.',
   dataset_type: 'payment_account',
   status: 'live',
+  tags: ['compliance', 'kyc'],
   filter_config: {
     type: 'custom',
     body: FILTER_BODY,
@@ -393,9 +394,11 @@ batches §008 ingested (`rpa` is the regulated-payment-account
 alias the run-query exposes).
 
 The SMS action's `trigger_template: 'now'` dispatches the action
-immediately rather than scheduling it, so the run reaches a
-terminal status on its own — poll `batchLogs.refresh` until it
-leaves `:pending`. A `:partial` status is expected and fine here:
+immediately rather than deferring it, so once the run fires it
+reaches a terminal status on its own — poll `batchLogs.refresh`
+until it leaves `:pending`. The run itself is still scheduled:
+`workflows.run` records it and returns, which is why the setup
+file's `ctx.waitForFiredRun` sits between the call and the log id. A `:partial` status is expected and fine here:
 one row passed and one was filtered.
 
 ```typescript
@@ -404,8 +407,11 @@ const runResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSl
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = runResp.data.workflow_run_log_id!
-ctx.runBatchId = runResp.data.batch_id!
+// run-workflow only SCHEDULES the run. The log id and batch id are
+// written when it fires, so read them back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, runResp.data.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
+ctx.runBatchId = fired.batchId!
 
 const deadline = Date.now() + 120_000
 let status: string | null = null
@@ -548,7 +554,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause must speak this workflow's selection dialect — the dataset
 // alias is `rpa` here, the same alias the live run above uses.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
@@ -556,8 +562,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```
 

package/.agent/cookbook/marketing-campaign-send.md

@@ -273,7 +273,7 @@ const ROSTER_MDM = `{% assign p = msg %}
   "legal_entity_type": "business",
   "business_name": "{{ p.business_name | json_escape }}",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -376,7 +376,7 @@ const AUDIENCE_MDM = `{% assign p = msg %}
   {% if first_name != "" %}"first_name": "{{ first_name | json_escape }}",{% endif %}
   {% if last_name != "" %}"last_name": "{{ last_name | json_escape }}",{% endif %}
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -609,6 +609,7 @@ const { data: workflow } = await api.workflows.create(tenantSlug, datalakeSlug,
   dataset_type: 'generic_table',
   generic_table_id: ctx.audienceTableId,
   status: 'live',
+  tags: ['marketing', 'loyalty'],
   skip_mdm_resolution: false,
   filter_config: { type: 'custom', body: CAMPAIGN_FILTER, output_schema: { type: 'boolean' } },
   decision_config: {
@@ -690,7 +691,10 @@ const { data: run } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.work
   mode: 'live',
   manual_override: false,
 })
-ctx.runLogId = run.workflow_run_log_id!
+// run-workflow only SCHEDULES the run. The log id is written when it
+// fires, so read it back via workflowRuns.get.
+const fired = await ctx.waitForFiredRun(datalakeSlug, run.workflow_run_id)
+ctx.runLogId = fired.workflowRunLogId
 
 const deadline = Date.now() + 180_000
 let byStatus: Record<string, number> = {}
@@ -844,7 +848,7 @@ const REPLY_MDM = `{% assign p = msg %}
 {
   "legal_entity_type": "individual",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}", "type": "digital_identifier"}
   ]
 }`
 
@@ -935,7 +939,7 @@ if (wfRow.status !== 'live') {
 }
 // Behavioural probe — a dry run against a selection no row can match:
 // the pipeline executes end-to-end, the final action call is
-// intercepted, and the acknowledgement carries the run-log id. The
+// intercepted, and the acknowledgement carries the scheduled run id. The
 // clause speaks this workflow's selection dialect: a GENERIC-TABLE
 // audience is addressed by its own columns (no `ra.` dataset alias —
 // that alias exists only for system-dataset selections).
@@ -944,8 +948,10 @@ const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx
   mode: 'dry_run',
   manual_override: false,
 })
-if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
-  throw new Error('dry-run probe returned no workflow_run_log_id')
+// The run-log id does not exist until the run fires — wait, do not read a null.
+const probeFired = await ctx.waitForFiredRun(datalakeSlug, probeRun.workflow_run_id)
+if (probeFired.workflowRunLogId.length === 0) {
+  throw new Error('dry-run probe never produced a workflow_run_log_id')
 }
 ```