@alvera-ai/platform-sdk 0.15.0 → 0.16.0

package/.agent/cookbook/sanctions-screening-with-agent-review.md

@@ -270,6 +270,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Runs an LLM disambiguation pass on gray-zone-scored sanctions matches and fires a verdict-keyed SMS.',
   dataset_type: 'compliance_screening',
   status: 'live',
+  tags: ['compliance', 'sanctions'],
   filter_config: {
     type: 'custom',
     body: GRAY_ZONE_FILTER,
@@ -514,8 +515,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() + 240_000
 let status: string | null = null
@@ -658,7 +662,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 `rcs` here, the same alias the live run above uses.
 const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
@@ -666,8 +670,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/score-leads-with-llm-categorization.md

@@ -321,6 +321,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   generic_table_id: genericTableId,
   skip_mdm_resolution: true,
   status: 'live',
+  tags: ['leads', 'llm'],
   filter_config: {
     type: 'custom',
     body: 'true',
@@ -486,8 +487,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
@@ -564,7 +568,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).
@@ -573,8 +577,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/triage-prospects-by-priority.md

@@ -293,6 +293,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Bands AR customers into priority_high/medium/low via an LLM agent; one SMS action per band.',
   dataset_type: 'customer',
   status: 'live',
+  tags: ['ar', 'triage'],
   filter_config: {
     type: 'custom',
     body: '{% if customer.phone and customer.tax_id %}true{% endif %}',
@@ -422,8 +423,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
@@ -497,14 +501,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/welcome-sms-for-customers.md

@@ -155,6 +155,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
   description: 'Sends a welcome SMS to newly contracted customers with a self-serve billing link.',
   dataset_type: 'customer',
   status: 'live',
+  tags: ['lifecycle', 'welcome'],
   filter_config: {
     type: 'custom',
     body: FILTER_BODY,
@@ -382,9 +383,11 @@ The SQL where-clause scopes the run to exactly the two batches
 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
@@ -393,8 +396,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
@@ -537,14 +543,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/errors.md

@@ -125,11 +125,17 @@ body):
     { "source": { "pointer": "/name" },
       "detail": "Missing field: name" },
     { "source": { "pointer": "/dataset_type" },
-      "detail": "Missing field: dataset_type" }
+      "detail": "Missing field: dataset_type" },
+    { "source": { "pointer": "/tags" },
+      "detail": "Missing field: tags" }
   ]
 }
 ```
 
+`tags` is the easy one to miss: it is required with no default, so
+omitting it 422s even though an empty list is a perfectly ordinary
+workflow. Send `tags: []` (see `workflows.md` §2).
+
 **Layer 1 — invalid enum value** (`dataset_type: "nonexistent_type"`):
 
 ```json

package/.agent/interoperability_contracts.md

@@ -168,6 +168,63 @@ generic_table_id  required UUID|null — required iff resource_type='generic_tab
 **Write-only (Request-only).** None — every caller-supplied field
 round-trips on the response.
 
+### What `mdm_input_config` must render — and the field that is easy to miss
+
+The body renders a JSON object describing the **subject** the row belongs
+to, so MDM can resolve it. The one part with a hard requirement that is not
+obvious from the shape is `identifiers`:
+
+```
+identifiers[]     uri       REQUIRED — the identifier's namespace
+                  type      REQUIRED — what kind of identifier it is
+                  value     REQUIRED — the identifier itself
+                  system    accepted, and NORMALISES ONTO `uri`
+                  country   optional — issuing country
+```
+
+**`type` is required and has no default.** An identifier with no type
+cannot be matched against anything, so MDM rejects the whole row:
+
+```
+MDM input validation failed
+reject_reason: %{identifiers: [%{type: ["can't be blank"]}]}
+```
+
+That rejection fails the contract at the `:mdm` stage, which means **the
+row never persists and the ingest looks silently empty** — you poll the
+dataset table and see zero rows, with nothing in the response to say why.
+Read the contract-stage failure to see the reason.
+
+`system` is accepted as an alias and normalises onto `uri`, so
+`{system, type, value}` and `{uri, type, value}` are both fine. What is
+never fine is omitting `type`.
+
+A worked example, from a green cookbook:
+
+```liquid
+{
+  "legal_entity_type": "individual",
+  "identifiers": [
+    {"system": "{{ p.source_uri }}", "value": "{{ handle }}", "type": "digital_identifier"}
+  ]
+}
+```
+
+**Do not confuse this with `identifications`,** which some `legal_entity`
+templates render into the record itself. That is a different embed with
+different keys (`id_type`, `uri`, `id_number`) — the two look alike and are
+not interchangeable.
+
+Two related shapes worth keeping straight:
+
+- **`mdm.verify`** (see `mdm.md`) takes looser input — it asks "is this
+  really you?" about an already-known subject, so it needs `value` plus a
+  `uri` **or** a `type`, not both. Its example is not a template for this
+  one.
+- **payments** additionally requires `id_type` on each entry of its own
+  verify payload. Per-domain differences are real; check the domain you are
+  writing for.
+
 ## 4. Error envelopes
 
 Standard JSON:API envelopes per `errors.md`. Common rejections:
@@ -178,6 +235,7 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/template_config/type`      | enum mismatch                                    |
 | `/template_config/body`      | empty when `type === 'custom'`                   |
 | `/mdm_input_config/type`     | enum mismatch                                    |
+| `identifiers[].type`         | blank — see §3; fails at the `:mdm` stage at INGEST time, not at create, so the contract saves fine and rows silently never land |
 | `/generic_table_id`          | missing when resource_type='generic_table',      |
 |                              | or non-null when not                             |
 | `/name`                      | uniqueness within datalake                       |

package/.agent/tools.md

@@ -74,6 +74,10 @@ the discriminator. Each branch is its own TypeScript type:
    tool_body_type = 'rest_api'       →  generic REST endpoint
    tool_body_type = 'sns'            →  AWS SNS topic (used for
                                         SMS / push notifications)
+   tool_body_type = 'twilio'         →  Twilio Programmable Messaging
+                                        (SMS). A first-class sender —
+                                        do NOT hand-author a rest_api
+                                        body for Twilio; see §2 below
    tool_body_type = 'end_user_messaging'
                                      →  AWS End User Messaging (used
                                         for MMS / media messages via
@@ -99,13 +103,103 @@ discriminator is a string-literal on each branch of the generated
 `ToolBodyWritable` union (`tool_body_type: 's3'`, `'rest_api'`, …).
 Consult the branch literals in
 `packages/sdk/src/generated/types.gen.ts` for the complete set,
-since new body types land independently of doc revisions. The
-platform declares the same twelve variants in
-`platform/lib/platform/tools/tool.ex` (`polymorphic_embeds_one(:body,
-…)`, lines 255–269).
+since new body types land independently of doc revisions.
 
 ## 2. Rules the type cannot encode
 
+### Twilio is a first-class sender — never hand-author `rest_api` for it
+
+Use `tool_body_type: 'twilio'`. Reaching for `intent: 'sms'` + a
+hand-authored `rest_api` body was the old workaround and it is now a
+mistake with a consequence: a `rest_api` Twilio sender has no
+`status_poller/twilio/…` path, so **the send can never learn what
+happened to it** — no delivery status, no reconciliation.
+
+```typescript
+await api.tools.create(tenantSlug, datalakeSlug, {
+  name: 'Campaign Sender — Main Line',
+  intent: 'sms',
+  tool_body_type: 'twilio',
+  variant_type: 'primary',
+  account_sid: 'AC…',           // "AC" + 32 hex
+  auth_token: '…',              // writeOnly — never comes back on a read
+  from_number: '+15550000001',  // XOR with messaging_service_sid
+  // base_url    — nullable; blank means https://api.twilio.com
+  // timeout_ms  — 1..300000, nullable
+  // base_message — ComplexTemplateConfig
+})
+```
+
+**`from_number` and `messaging_service_sid` are mutually exclusive.**
+Twilio resolves the messaging service and ignores `From` when both are
+sent, so a tool carrying both could no longer say which number a message
+went out on — and that join is the entire reason one tool exists per
+sender identity. The type permits both because the spec cannot express
+XOR; the server rejects it.
+
+There is deliberately **no `status_callback_url`**. The platform polls
+Twilio's Messages endpoint; a callback field would advertise a path that
+does not exist.
+
+### One credential, many senders: `variant_type` and `primary_tool_id`
+
+Every sender body — `twilio`, `sns`, `end_user_messaging`, `email` —
+declares which of two things it is:
+
+```
+variant_type = 'primary'   holds its own credential, borrows from nothing
+variant_type = 'variant'   borrows; primary_tool_id is REQUIRED
+```
+
+The problem this solves: one Twilio account behind three numbers used to
+mean three tools each holding the same `account_sid` and `auth_token`.
+Rotation was N edits, and a missed one is a **silent partial outage** —
+the other senders keep working, so nothing looks broken.
+
+**A variant stores no credential at all.** Reading one back, its
+`account_sid` / `api_key` / `access_key_id` / `smtp_*` come back `null`.
+**That is correct and complete, not missing data.** Do not "repair" it by
+copying the primary's credential in — that recreates the exact bug this
+removes. The platform resolves the primary at dispatch.
+
+**Rotation is one write, to the primary.** Any helper that "updates
+credentials across senders" is now wrong by construction: a partial
+rotation has no representation.
+
+**Depth is exactly one**, enforced by a database trigger rather than a
+changeset, because the rule reads another row. A violation is a **422
+with a field on it** — surface the message, do not retry:
+
+```
+names a tool that is itself a variant — a variant must name a primary
+names a tool of another type — a variant borrows from a primary of its own type
+names a primary on another provider — a variant borrows one account's credentials
+```
+
+What stays with the variant is the sender identity and its event routing:
+
+```
+twilio              from_number XOR messaging_service_sid
+sns                 phone_number
+end_user_messaging  phone_number · configuration_set_name
+email :mailgun      from_email · from_name · reply_to · domain
+email :ses          from_email · from_name · reply_to
+email :sendgrid     from_email · from_name · reply_to
+email :smtp         from_email · from_name · reply_to
+```
+
+Everything else — auth, region, endpoints, the MMS staging bucket — comes
+from the primary. Two entries look arbitrary and are not: Mailgun's
+`domain` is also a path segment in the request URL
+(`/v3/{domain}/messages`), and End User Messaging's
+`configuration_set_name` is the *event-routing* address, of which AWS
+permits one per originating number — a number that cannot name its own
+routing cannot be reconciled apart from its siblings.
+
+The split is per body type, and for Email per **provider**. That is the
+concrete reason there is no global credential registry: no single list
+could express it.
+
 ### `intent` and `tool_body_type` are loosely coupled
 
 The TypeScript type lets you combine any intent with any body

package/.agent/workflows.md

@@ -49,6 +49,7 @@ const { data: created } = await api.workflows.create(
     description: 'Send a review-request SMS after a fulfilled appointment',
     dataset_type: 'appointment',            // the dataset this workflow listens on
     status: 'live',                         // 'live' | 'draft' | 'manual' (see §5)
+    tags: ['appointments', 'sms'],          // REQUIRED on every write — [] if untagged (see §2)
     filter_config: {
       type: 'custom',
       body: `{% if appointment.source_uri == "12345.example.com" %}true{% endif %}`,
@@ -138,6 +139,25 @@ authors are Complex) — don't assume every `{ type, body }`-shaped config
 also carries a request-writable `output_schema`; check whether the field
 is pinned or caller-authored for that specific config before authoring one.
 
+### `tags` is required on every write, and has no default
+
+`tags` is a `string[]` on both the request and the response, and it is
+in `required:`. **Every `create()` / `update()` without it is a 422.**
+Send `tags: []` for an untagged workflow — the empty array is how you
+say "no tags", not something you can omit.
+
+The missing default is deliberate. `update()` is full-replacement (there
+is no PATCH, and no add-tag / remove-tag endpoint), so an omitted key
+cannot mean "leave tags alone". With a default, omitting it would have
+silently emptied a workflow's tags and returned 200. A 422 beats losing
+state the caller never mentioned.
+
+The labels are free text — no taxonomy, no shared vocabulary, and the
+execution pipeline does not read them. But they **do** participate in the
+workflow checksum, so retagging shifts the drift fingerprint. Re-tag and
+`checksum()` returns a different value even though nothing executable
+changed.
+
 ### `update()` replaces inline arrays whole
 
 `actions` and `context_datasets` are replaced whole by `update()`.
@@ -164,17 +184,34 @@ The placeholder names depend on the workflow's `dataset_type`
 appointment-driven workflow, customer_id + invoice.id for an
 invoice-driven workflow, etc.).
 
-### Scheduling lives on the ACTION, not on the run
+### Two scheduling levers, and they answer different questions
+
+There are **two**, and picking the wrong one is the most common mistake
+here:
+
+| lever | lives on | answers |
+|---|---|---|
+| `scheduled_at` | the **run** (`.run` body, §5) | *when is this send going out?* |
+| `trigger_template` | each **action** (below) | *when does this action fire, relative to the run?* |
+
+**`scheduled_at` is the one you want for a campaign.** A send time is
+per-send, not per-workflow: "this campaign goes Tuesday 9am" is a
+property of *this* send, and the next one goes at a different time. Pass
+`scheduled_at` on the run and leave the workflow definition alone.
 
-**The scheduling knob is `trigger_template` on each `action` — the
-`.run` / `.execute` calls carry no schedule field.** `.run` takes only
-`{ sql_where_clause, manual_override, mode }` (see §5); there is no
-`run_at`, no `schedule_for`. This is by design: you invoke the run
-*now*, every matched row is evaluated *now*, and each fired action then
-waits for its own `trigger_template` instant. "The platform can't
-schedule a campaign for Tuesday 9am" is the wrong conclusion — you
-schedule the *action* for Tuesday 9am and call `.run` whenever you
-like.
+**`trigger_template` is a property of the workflow itself** — "the
+reminder goes 24h before the appointment", "the follow-up goes 3 days
+after signup". It is relative to the run and belongs in the definition
+because it is true of every run.
+
+Use `trigger_template` for a campaign send time and you are rewriting the
+workflow before every send — a full `update()` per campaign, since
+`update()` replaces the resource whole. That was the only option before
+runs became a resource, and it is no longer the right answer.
+
+Neither lever is a guarantee of the instant a message leaves: the
+action window / quiet hours (below) can push an action later, and a
+`runtime_filter` can drop it entirely.
 
 ### `trigger_template` controls scheduling
 
@@ -322,6 +359,7 @@ are removed, and re-supplied ones are repositioned.
 await api.workflows.create(tenantSlug, datalakeSlug, {
   name: 'Contact-Us Triage',
   dataset_type: 'generic_table',
+  tags: [],
   // …other workflow fields…
   workflow_ai_agents: [
     {
@@ -412,6 +450,8 @@ name                         required string
 description                  optional string
 dataset_type                  required string — the dataset this listens on
 status                       required enum — 'live' | 'draft' | 'manual' (§5 Create)
+tags                         required array — string[]; NO default, send [] if
+                                              untagged; feeds the checksum (§2)
 generic_table_id              optional UUID — required iff dataset_type='generic_table'
 skip_mdm_resolution           optional bool — default false; a deliberate
                                               choice, NOT a generic-table default (§3)
@@ -486,39 +526,95 @@ are all `workflow_slug`-keyed). Passing a slug to `.get` 422s with
 
 ### Run
 
-`.run` evaluates the workflow against a SQL-selected row set. **The
-request body is exactly `{ sql_where_clause, manual_override, mode }` —
-there is no schedule field.** Scheduling is on each action's
-`trigger_template` (§2): `.run` fires the pipeline now; the actions it
-matches wait for their own trigger instants.
+**`.run` does not run the workflow. It records a run and returns.**
+The work happens when that run *fires* — immediately if you did not ask
+for a time, or at `scheduled_at` if you did.
 
 ```typescript
 const { data: run } = await api.workflows.run(
-  tenantSlug, workflowSlug,
+  tenantSlug, datalakeSlug, workflowSlug,
   {
     sql_where_clause: `ra.id = '${appointmentId}'`,  // run against the regulated tables
     mode: 'live',                                    // 'live' | 'dry_run'
     manual_override: false,                          // see below
+    scheduled_at: '2026-08-12T09:00:00+01:00',       // OPTIONAL — see below
   },
 )
-// run.batch_id              — tagged string (e.g. "manual:<uuid>");
-//                              the prefix distinguishes manual runs from
-//                              cron-driven ones
-// run.workflow_run_log_id   — UUID — the batch log row (poll via batchLogs)
-// run.enqueued_count        — number of rows the WHERE clause matched
-```
-
-**`.run`'s response envelope is fire-only — do not trust it to confirm
-success or failure.** `enqueued_count` (and any rendered-message field) can
-come back empty/`undefined` even when the run genuinely succeeded end to
-end — observed live: a manual run returned `enqueued_count: undefined` and
-a null message parse, yet its workflow execution log showed `filter: true`,
-the subject resolved, the action status was `completed`, and a real
-provider `external_id` came back (the SMS actually dispatched). The HTTP
-200 only means the run was *accepted*, not that you now know its outcome.
-**Always poll `workflow_run_log_id` via `batchLogs` + `workflowLogs`, and
-the action's own status, for the actual truth** — never branch logic on
-the immediate response body's counts or message fields.
+// run.workflow_run_id   — UUID of the run. This is the handle for
+//                          everything else: get, cancel, and the ids below.
+// run.status            — 'scheduled' | 'processing' | 'completed'
+//                          | 'cancelled' | 'failed'
+// run.scheduled_at      — when it will fire (always present; "now" is a
+//                          run scheduled for now, not a second code path)
+// run.matched_count     — nullable PREVIEW, see the warning below
+```
+
+**`batch_id`, `workflow_run_log_id` and `enqueued_count` are NOT on this
+response.** They described work that had not happened yet: the segment is
+resolved when the run fires, not when it is scheduled, so a run scheduled
+for Friday reaches Friday's rows. `batch_id` and `workflow_run_log_id`
+become readable from `workflowRuns.get` once the run has fired (below);
+`enqueued_count` has no replacement — count the rows the fan-out actually
+produced via `workflowLogs`, because a count column can claim three while
+nothing was inserted, and rows cannot.
+
+**`matched_count` is a preview, not the audience.** It is what the clause
+matched at schedule time, for sanity-checking the clause you just wrote.
+The segment is resolved *again* at send time with suppressed records
+excluded, so the number that actually goes out can be smaller. Never
+report `matched_count` to a user as "this many people will receive it".
+
+#### Scheduling a run
+
+`scheduled_at` is an ISO-8601 timestamp **with an offset**
+(`2026-08-12T09:00:00+01:00`). Omit it, or pass `null`, and the run fires
+as soon as a worker picks it up.
+
+It is **not** a guarantee of send time. Each action still passes through
+the workflow's action window and its own `trigger_template` (§2), so an
+action may execute later than the run fires — `scheduled_at` says when the
+segment is resolved and the fan-out begins, nothing more.
+
+#### Reading a run back — and the trap in it
+
+```typescript
+const { data: state } = await api.workflowRuns.get(tenantSlug, datalakeSlug, runId)
+```
+
+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 `workflow_run_log_id` and `batch_id` a beat
+later. A predicate on status alone releases you to read a `null`, and
+because `typeof null === 'object'` in JavaScript the symptom is a baffling
+*"expected string, got object"* rather than an obvious nil.
+
+Raise on `status === 'failed'` carrying `failure_reason` instead of
+polling to your deadline — a caller blocked on a run that will never fire
+should learn why on the first read, not thirty seconds later behind a
+generic timeout.
+
+**The HTTP 200 from `.run` means the run was *accepted*, not that you know
+its outcome.** For the actual truth, poll the run to get its
+`workflow_run_log_id`, then read `batchLogs` + `workflowLogs` and the
+action's own status. Never branch logic on the immediate response body.
+
+#### Listing and cancelling
+
+```typescript
+await api.workflowRuns.list(tenantSlug, datalakeSlug, { page: 1, page_size: 50 })
+await api.workflowRuns.cancel(tenantSlug, datalakeSlug, runId)
+```
+
+`list` is **datalake-scoped, not workflow-scoped** — it answers "what is
+going out from this datalake", across every workflow, which is the question
+a campaign screen actually asks. It takes the full Flop query surface
+(`page`, `page_size`, `order_by`, `order_directions`, `filters`).
+
+`cancel` is **refused once a run reaches `processing`**: the fan-out has
+begun and a job already executing cannot be stopped. Cancelling races the
+worker — both sides contend on one conditional update, so exactly one wins
+and the loser is told. Treat a refusal as a normal outcome to surface, not
+an error to retry.
 
 `sql_where_clause` accepts a fragment against the dataset's
 regulated tables (`ra` for appointments, `rp` for patients,
@@ -536,9 +632,11 @@ rejects stays rejected. (The platform pipeline discards the flag before
 filter and decision evaluation — override is not a "force through"
 switch.)
 
-A zero-match `sql_where_clause` still returns 200 and still
-creates a batch log row (`enqueued_count: 0`) — poll
-`workflow_run_log_id` uniformly, no special empty case.
+A zero-match `sql_where_clause` still returns 200 and still records a run
+that fires and writes a batch log row — poll `workflowRuns.get` for the
+`workflow_run_log_id` uniformly, no special empty case. At schedule time a
+zero-match clause reports `matched_count: 0`, but see the warning above:
+that is a preview of the clause, not proof that nothing was sent.
 
 ### Execute (per-row, per-action)
 
@@ -822,7 +920,8 @@ the datalake (live dispatch only):
 | enrichment | runs | runs |
 | action `runtime_filter` | applies | applies |
 | `manual_override` | dedupe/idempotency bypass only | same |
-| answers | `batch_id`, `workflow_run_log_id`, `enqueued_count` | `workflow_execution_log_id`, always `status: 'pending'` |
+| answers | `workflow_run_id`, `status`, `scheduled_at`, `matched_count` (the ids follow from `workflowRuns.get` once it fires) | `workflow_execution_log_id`, always `status: 'pending'` |
+| runs when | the run fires — now, or at `scheduled_at` | immediately |
 
 ### The three states a send can be in