@alvera-ai/platform-sdk 0.12.1 → 0.13.0-next.gf3d2a4a

package/.agent/AGENTS.md

@@ -52,6 +52,28 @@ opening it. If you find yourself emitting a claim about a kind's
 wire shape without having opened that kind's MD in the current
 session, **stop and open it now**.
 
+### You are NOT entitled to conclude "the platform cannot do X"
+
+This corpus is your window onto the platform, not its floor plan.
+**Absence from these guides is not evidence the platform lacks a
+capability** — it usually just means no use case had yet forced that
+capability into the docs. The platform is deliberately generic; the
+same primitives back many verticals, and each new build surfaces a
+fresh batch of capabilities the corpus never had a reason to spell out.
+
+So when a build seems to need something you can't find here, the honest
+output is a **problem statement to the platform team** ("I need to do
+X; the corpus doesn't document a way — does one exist?"), **not a
+verdict** ("the platform can't do X"). A wrong "can't" is expensive: it
+sends an agent to build the wrong thing or to file a request for a
+feature that already ships. Real examples that were *all* in the
+platform but missing from the corpus until a single build forced them
+in: SMS quiet-hours send windows, pausing a scheduled campaign by
+editing an action's `runtime_filter`, scheduling on the action rather
+than the run, per-recipient tracked-link minting, and per-variant
+`GROUP BY decision_key` analytics. Each was momentarily mistaken for a
+platform gap. Don't repeat that — escalate the question, don't rule.
+
 ---
 
 ## If you know MCP — vocabulary mapping
@@ -100,33 +122,91 @@ construction.
 ## SDK auth + client construction
 
 The SDK is a strict-TypeScript REST client for the Alvera
-platform. Two-step auth + client construction:
+platform. Two-step auth + client construction — and there are **two**
+session minters, not one (see `account_management.md` for the full
+treatment):
 
     import {
-      createSession,
+      createBootstrapSession,   // tenantless / root Bearer
+      createSession,            // tenant-scoped Bearer
       createIsolatedPlatformApi,
       type PlatformApi,
     } from '@alvera-ai/platform-sdk'
 
-    // 1. mint a session
+    // 1a. tenantless / root — POST /api/v1/admin/bootstrap-session.
+    //     Keyless by structural necessity (it mints the FIRST Bearer of an
+    //     environment, before any tenant key exists). Returned tenant + role
+    //     are always null. Dev / integration-test route — absent from prod.
+    const bootstrap = await createBootstrapSession({ baseUrl, email, password })
+
+    // 1b. tenant-scoped — the canonical app session. tenantSlug AND apiKey
+    //     are BOTH required; sign-in 401s ("X-API-Key required to sign in to
+    //     a tenant") without a resolvable X-API-Key.
     const session = await createSession({
       baseUrl,
       email,
       password,
-      tenantSlug,    // optional; omit for tenantless session
+      tenantSlug,    // REQUIRED
+      apiKey,        // REQUIRED — the tenant's publishable key
     })
 
     // 2. build a typed client
     const api: PlatformApi = createIsolatedPlatformApi({
       baseUrl,
       sessionToken: session.sessionToken,
+      apiKey,        // rides as X-API-Key on every request
     })
 
-Sessions come in three scopes:
-- **root** — Alvera root admin; user signup + confirmation
+**Two credentials travel together on every request** (Firebase's
+"API key + ID token" pairing, not an either/or): the session token
+(`Authorization: Bearer …`) is what the platform authenticates and
+authorizes as — Bearer always wins identity; the **publishable API
+key** (`X-API-Key: …`) identifies the client and carries the
+origin policy — a `public_api` key declares `allowed_origins`, and
+a browser request's `Origin` is checked against the key that
+resolves. A Bearer session *inherits the origin policy of the key
+that minted it*. Where the key comes from: a tenant admin mints it
+in the platform's API-keys page (Settings → API Keys), or
+programmatically via `api.admin.createTenantApiKey(tenantSlug,
+{ name, data_access_mode })` (platform-admin-gated).
+
+**A CORS preflight is NOT proof the key admits your origin.** A
+browser `OPTIONS` preflight carries no `X-API-Key` (only the method
++ `Access-Control-Request-Headers`), so the server cannot resolve a
+key and answers permissively — EVERY origin gets a friendly
+`access-control-allow-origin` echo. The enforced policy runs on the
+actual authenticated request, against the resolved key's
+`allowed_origins`. Never verify origins with a preflight — verify
+with a real signed-in round-trip. Triage for a failing browser
+sign-in: (1) console says the key env var is missing → your `.env`
+didn't load (restart the dev server after editing it); (2) the REAL
+call is blocked by CORS (no ACAO on it) → the key's
+`allowed_origins` doesn't include your dev origin — mint/patch the
+key, and don't trust the earlier green preflight; (3) a `401` with
+NO CORS error → the request PASSED CORS; the fault is the
+credentials or the key not resolving, not origins.
+
+Sessions come in three scopes, minted by two functions:
+- **root** — Alvera root admin; user signup + confirmation. Minted by
+  `createBootstrapSession` (a tenantless Bearer that belongs to a
+  platform-admin user).
 - **tenantless** — authenticated user with no tenant chosen yet;
-  used once to create a tenant via `api.tenants.create(...)`
-- **tenant-scoped** — the canonical Bearer for tenant operations
+  used once to create a tenant via `api.tenants.create(...)`. Also
+  minted by `createBootstrapSession`.
+- **tenant-scoped** — the canonical Bearer for tenant operations,
+  minted by `createSession` (**requires both `tenantSlug` and a real
+  tenant API key** — the login 401s with `X-API-Key required to sign
+  in to a tenant` otherwise).
+
+**Build apps tenant-scoped, and only tenant-scoped.** The root and
+tenantless scopes exist for the platform's own UI and for
+admin/bootstrap flows (signup, confirmation, tenant creation,
+test-suite setup) — they are NOT app-building surfaces; an app that
+holds a root or tenantless Bearer is misdesigned. An app
+authenticates against exactly one tenant with that tenant's
+publishable key. Likewise, connected apps are **single-tenant by
+construction** — one connected app per tenant, never one deployment
+serving many tenants (see `connected_apps.md`).
 
 Consumers holding multiple concurrent clients in the same file
 (e.g. integration tests that need root + tenantless + tenant-
@@ -189,7 +269,13 @@ business outcome.
    WORKFLOWS  (composition on top)
    ─────────
    workflows.md                  Filter + decision + action;
-                                  standard + agent-driven variants.
+                                  standard + agent-driven variants;
+                                  §8 watching a run.
+   messages.md                   The messages DATASET — what went
+                                  out, delivery status, engagement.
+   action_logs.md                The action_logs DATASET — per-
+                                  action outcomes, batch_id joins,
+                                  audience export.
 ```
 
 Axes are mostly disjoint but a few resources cross. AI Agents
@@ -217,6 +303,13 @@ wire name (snake_case):
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md
 
+Two corpus pages document DATASETS, not namespaces — read
+through `api.datasets` with SINGULAR dataset types (the plural
+forms are the SQL table names used by `executeSql`):
+
+    dataset type 'message'    (table messages)      messages.md
+    dataset type 'action_log' (table action_logs)   action_logs.md
+
 ## Cookbooks (Golden Path scenarios)
 
 `.agent/cookbook/<slug>.md` files are pure-markdown scenario
@@ -357,16 +450,18 @@ The `cookbook/` directory holds two kinds of recipe, both validated by
   an outcome.
 - **Capability docs** (`<capability>.md`) — one platform capability each,
   shown as the minimal call sequence that proves it (e.g. `bulk-ingest`,
-  `ai-agent-invoke`, `custom-tables`, `invite-team`). Read these to learn one
+  `ai-agent-invoke`, `generic-tables`, `invite-team`). Read these to learn one
   capability in isolation; cookbooks weave them into outcomes.
 
 ### Available cookbooks
 
-The nine business-cookbook scenarios. Each is anchored to a green
+The ten business-cookbook scenarios. Each is anchored to a green
 end-to-end vitest scenario in the platform's integration-tests suite and is
 verified at dev time by `make validate-cookbook` at the platform-sdk repo root.
-The entries between the managed markers below are what `alvera-sdk-init` lifts
-into consumer `<cwd>/AGENTS.md` files as a managed block.
+This index is mirrored into the managed block `alvera llm-export` writes to
+consumer `AGENTS.md` files (`buildManagedBlock` in both the SDK and CLI
+packages — kept in sync by hand; the llm-export test suites pin the shipped
+copy, so a dropped entry breaks a test).
 
 <!-- BEGIN:cookbook-index -->
 
@@ -380,7 +475,7 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
   buckets (appointment / job-application / spam) via an LLM
   agent, route each to a tailored SMS action.
 
-**Accounts Receivable**
+**Subscription**
 
 - [welcome-sms-for-customers](./cookbook/welcome-sms-for-customers.md)
   — Send a welcome SMS to newly contracted customers with a
@@ -394,7 +489,7 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
   (high / medium / low) via an LLM agent, route each band to a
   tailored SMS action.
 
-**Payment Risk**
+**Payments**
 
 - [kyc-notification-on-account-activation](./cookbook/kyc-notification-on-account-activation.md)
   — Send a KYC-notification SMS when a payment account
@@ -413,6 +508,11 @@ into consumer `<cwd>/AGENTS.md` files as a managed block.
   — Score inbound leads into four bands
   (hot / warm / cold / spam) via an LLM agent, route each band
   to a tailored SMS action.
+- [marketing-campaign-send](./cookbook/marketing-campaign-send.md)
+  — Send an A/B marketing campaign across SMS and email: the
+  suppression and reachability gates and the A/B split all live
+  in the workflow, each send carries a per-recipient short link,
+  and the reply re-attaches to the customer who sent it.
 
 <!-- END:cookbook-index -->
 
@@ -430,8 +530,8 @@ full wire shape.
   document/image and pull structured JSON out of it (`aiAgents.invoke` with
   files). The correct file-vision path — the agent reads the file; the DAC
   ingests it.
-- [custom-tables](./cookbook/custom-tables.md) — stand up a custom table the
-  built-in datasets don't model; deploy → ingest → search.
+- [generic-tables](./cookbook/generic-tables.md) — stand up a generic table the
+  built-in datasets don't model; deploy → ingest → read back via executeSql.
 - [action-status-updaters](./cookbook/action-status-updaters.md) — reconcile
   the delivery status of messages you send, on a schedule.
 - [system-templates](./cookbook/system-templates.md) — discover the platform's
@@ -447,8 +547,10 @@ full wire shape.
 
 Cross-resource utilities not documented in this corpus:
 
-    api.auth          signUp + auth helpers
-    api.admin         confirmUser + admin actions
+    api.admin         signUp + confirmUser + createTenantApiKey
+                       (dev / integration-test fixtures)
+    api.sessions      verify; top-level createBootstrapSession /
+                       createSession / revokeSession mint + revoke Bearers
     api.tenants       create + tenant lifecycle
     api.datasets      cross-resource search / metadata /
                        user-saved searches

package/.agent/account_management.md

@@ -15,14 +15,14 @@ together:
 
 | Namespace          | Methods                                       |
 |--------------------|-----------------------------------------------|
-| `api.auth`         | `signUp`                                      |
-| `api.admin`        | `confirmUser` — **dev fixture only**          |
+| `api.admin`        | `signUp`, `confirmUser`, `createTenantApiKey` — **dev / integration-test fixtures only** |
 | `api.sessions`     | `verify`                                      |
 | `api.tenants`      | `create`, `list`                              |
 | `api.invitations`  | `create`, `list`, `accept`                    |
 | `api.ping`         | unauthenticated health check (`GET /api/ping`) |
-| `createSession`    | mint a Bearer (top-level helper, not a namespace) |
-| `revokeSession`    | revoke the current Bearer (top-level helper, parallel to `createSession`) |
+| `createBootstrapSession` | mint a **tenantless** Bearer (top-level helper, not a namespace) |
+| `createSession`    | mint a **tenant-scoped** Bearer (top-level helper, not a namespace) |
+| `revokeSession`    | revoke the current Bearer (top-level helper, parallel to the two minters) |
 
 Two top-level concerns sit above the surface:
 
@@ -39,36 +39,69 @@ The Bearer carries the trust-boundary coordinates and travels in
 the `Authorization: Bearer <token>` header on every subsequent
 request.
 
-### Three Bearer scopes
+### Three scopes, two minters
 
-`createSession` mints a Bearer at one of three scopes:
+Sessions come in three scopes — **root**, **tenantless**, and
+**tenant-scoped** — but there are only **two** functions that mint a
+Bearer. `createBootstrapSession` mints the keyless tenantless Bearer
+(root is a tenantless Bearer that happens to belong to a platform-admin
+user); `createSession` mints the tenant-scoped Bearer.
 
 ```typescript
-import { createSession } from '@alvera-ai/platform-sdk'
+import { createBootstrapSession, createSession } from '@alvera-ai/platform-sdk'
 
-// root admin (no tenant) — for confirmUser, signUp on behalf of, etc.
-const root = await createSession({
-  baseUrl, email: rootEmail, password: rootPassword,
+// tenantless — POST /api/v1/admin/bootstrap-session. Keyless by structural
+// necessity (it mints the very first Bearer of an environment, before any
+// tenant key exists). Returned tenant + role are ALWAYS null. This is an
+// integration-test / dev-only route — absent from prod builds.
+const tenantless = await createBootstrapSession({
+  baseUrl, email, password,
 })
+// tenantless.tenant === null  &&  tenantless.role === null
 
-// tenantless — authenticated user who has not picked a tenant yet
-const tenantless = await createSession({
-  baseUrl, email, password,
+// root — the SAME call, with a platform-admin user's credentials. The
+// admin capability comes from the user, not a different function. Use it
+// for admin.signUp / admin.confirmUser / admin.createTenantApiKey.
+const root = await createBootstrapSession({
+  baseUrl, email: rootEmail, password: rootPassword,
 })
-// tenantless.tenant === null
 
-// tenant-scoped — the canonical Bearer for tenant operations
+// tenant-scoped — POST /api/v1/sessions, the canonical Bearer for tenant
+// operations. REQUIRES both tenantSlug AND a resolvable tenant publishable
+// key (sent as X-API-Key): the server 401s with "X-API-Key required to
+// sign in to a tenant" without one, and 403s a key belonging to a different
+// tenant. The minted Bearer inherits the origin policy of the key that
+// minted it, and that same key must accompany every subsequent request.
 const tenant = await createSession({
-  baseUrl, email, password, tenantSlug,
+  baseUrl, email, password, tenantSlug, apiKey: tenantApiKey,
 })
 // tenant.tenant.slug === tenantSlug
 // tenant.role.name   === 'tenant_admin' | 'member' | ...
 ```
 
+The tenant API key is minted by a tenant admin in the platform's
+API-keys page (Settings → API Keys), or programmatically via the
+platform-admin side door (a root Bearer):
+
+```typescript
+const { data: minted } = await rootApi.admin.createTenantApiKey(tenantSlug, {
+  name: 'Bootstrap Key',
+  data_access_mode: 'unregulated',
+})
+// minted.api_key — the publishable key value (thread into createSession)
+```
+
 See `AGENTS.md` "Sessions come in three scopes" for when each is
 appropriate. Tenantless is a transient state used once: to create
 a tenant (creator path) or accept an invitation (invitee path).
 
+**Scope discipline for app builders:** root and tenantless sessions
+are platform-UI / admin-bootstrap surfaces (signup, confirmation,
+tenant creation, test setup) — never ship them inside an app. An
+app authenticates **tenant-scoped against exactly one tenant**,
+with that tenant's publishable key; connected apps in particular
+are single-tenant by construction (`connected_apps.md`).
+
 ### Explicit teardown — `revokeSession`
 
 The inverse of `createSession`. Revokes the current Bearer on
@@ -110,7 +143,9 @@ local server before authentication failures muddy the diagnostic.
 ### Sign up
 
 ```typescript
-const { data: user } = await rootApi.auth.signUp({
+// signUp lives under the admin namespace (there is no `api.auth`); it is an
+// integration-test fixture, reachable only from a root Bearer.
+const { data: user } = await rootApi.admin.signUp({
   email: 'sarah@example.com',
   password: '...',
   first_name: 'Sarah',
@@ -180,11 +215,11 @@ to many tenants; a Bearer is scoped to exactly one.
 ```
   ┌─ creator path ─┐                ┌─ invitee path ─┐
   │                                 │
-  api.auth.signUp                   api.auth.signUp
+  admin.signUp                      admin.signUp
   │                                 │
   api.admin.confirmUser*            api.admin.confirmUser*   (* production: email link)
   │                                 │
-  createSession (no tenantSlug)     createSession (no tenantSlug)
+  createBootstrapSession            createBootstrapSession
   │                                 │
   api.tenants.create                api.invitations.list → .accept
   │                                 │
@@ -203,26 +238,30 @@ role specified in their invitation.
 const { data } = await tenantlessApi.tenants.create({
   name: 'Acme Health',
 })
-// data.tenant.id, data.tenant.slug  — server-derived
-// data.session_token                — see "Gotchas" below
+// data.id, data.slug, data.name — server-derived (flat TenantResponse)
 ```
 
 The slug is server-derived from `name` per the universal slug
 rules (see `type_naming.md` "Never pre-compute the slug
 client-side"). Use the returned slug for downstream calls.
 
-**Gotcha**: the response carries a `session_token` field, but this
-is an *incidental* token — do not treat it as a freshly minted
-tenant-scoped Bearer. The authoritative pattern is to call
-`createSession({ ..., tenantSlug })` after `tenants.create`. This
-gives a fresh Bearer with all role + tenant claims correctly
-populated.
+**Gotcha**: `tenants.create` returns only the tenant — a flat
+`TenantResponse` (`id`, `slug`, `name`, `description`), **not** a Bearer
+and with no `session_token`. The caller's tenantless Bearer stays valid,
+but it is still tenantless. To act on the new tenant, mint a tenant-scoped
+Bearer via `createSession({ ..., tenantSlug, apiKey })` — which is also
+where the mandatory `X-API-Key` first enters the flow. (The tenant's
+default `public_api` key is auto-minted at creation, but its plaintext is
+not returned here — read it from Settings → API Keys, or mint a fresh key
+via `admin.createTenantApiKey`.)
 
 ### `api.tenants.list`
 
 ```typescript
 const { data: tenants } = await api.tenants.list()
 // tenants.data: TenantResponse[] — every tenant the current Bearer can see
+// takes an optional Flop query (page/page_size/order_by/filters —
+// see type_naming.md "List response types")
 ```
 
 A root Bearer sees every tenant; a tenant-scoped Bearer typically
@@ -271,13 +310,13 @@ the invitation enum:
 |-------------------------|------------------------------------|--------------|
 | `'tenant_admin'`        | Full tenant management             | invitation `'admin'`  |
 | `'member'`              | Standard tenant user               | invitation `'member'` |
-| `'tenant_api'`          | Programmatic tenant access (most API keys) | provisioned, not invited |
+| `'public_api'`          | Lowest-privilege publishable key (Stripe `pk_` analogue); the mandatory `X-API-Key` companion | provisioned, not invited |
 | `'datalake_admin'`      | Full datalake management (requires `datalake_id` on session) | console-mediated |
 | `'researcher'`          | Tokenized-only datalake access     | invitation `'researcher'` |
 | `'datalake_api'`        | Programmatic datalake access       | provisioned, not invited |
 
 ```typescript
-const session = await createSession({ baseUrl, email, password, tenantSlug })
+const session = await createSession({ baseUrl, email, password, tenantSlug, apiKey: tenantApiKey })
 // session.role.name === 'tenant_admin'   if accepted from a role: 'admin' invitation
 // session.role.name === 'member'         if accepted from a role: 'member' invitation
 // session.role.name === 'researcher'     if accepted from a role: 'researcher' invitation
@@ -327,7 +366,7 @@ const mine = invites.data.find(i => i.tenant.slug === tenantSlug)
 const { data: membership } = await tenantlessApi.invitations.accept(mine.id)
 
 // Then mint a tenant-scoped Bearer
-const session = await createSession({ baseUrl, email, password, tenantSlug })
+const session = await createSession({ baseUrl, email, password, tenantSlug, apiKey: tenantApiKey })
 // session.role.name === 'member'
 ```
 
@@ -399,16 +438,18 @@ documented in `errors.md`. Common rejections:
 
 | `source.pointer` / shape                        | Cause                                        |
 |-------------------------------------------------|----------------------------------------------|
-| `/email` "has already been taken"               | `auth.signUp` with an existing email         |
+| `/email` "has already been taken"               | `admin.signUp` with an existing email        |
 | `/password` "is too short"                      | password below minimum length                |
 | top-level 401 (no envelope)                     | Bearer missing, expired, or revoked          |
 | top-level 403 (no envelope)                     | role lacks permission for the action         |
 | `/email` "already invited"                      | duplicate `invitations.create`               |
 | `/tenant_slug` "not found"                      | tenant slug doesn't exist or invisible to Bearer |
 
-The `tenants.create` 422 is typically `/name` uniqueness — names
-must be unique platform-wide. Re-attempt with a different name or
-treat as "already exists" via `api.tenants.list` lookup.
+A `tenants.create` `/name` uniqueness collision comes back as a
+**409 Conflict** (not 422 — uniqueness constraints route to 409; see
+`errors.md`) — names must be unique platform-wide. Re-attempt with a
+different name or treat as "already exists" via `api.tenants.list`
+lookup.
 
 ## 6. Gotchas
 
@@ -417,10 +458,10 @@ treat as "already exists" via `api.tenants.list` lookup.
    the SDK method as a test fixture; do not ship code that calls
    it from a customer-facing path.
 
-2. **The `session_token` returned by `tenants.create` is
-   incidental.** Always re-mint a fresh tenant-scoped Bearer via
-   `createSession({ ..., tenantSlug })` after creating a tenant.
-   This guarantees clean role+tenant claims on the Bearer.
+2. **`tenants.create` returns a tenant, not a Bearer.** The response is
+   a flat `TenantResponse` (`id`, `slug`, `name`, `description`) with no
+   `session_token`. After creating a tenant, mint a tenant-scoped Bearer
+   via `createSession({ ..., tenantSlug, apiKey })` to act on it.
 
 3. **Tenantless Bearer is a transient state.** Only two
    operations are useful with it: `tenants.create` (creator path)

package/.agent/action_logs.md

@@ -0,0 +1,144 @@
+# Action logs (datalake dataset)
+
+One row = one action outcome for one subject. Where `messages`
+answers "what went out", `action_logs` answers "what did each
+action do, per subject, per run" — including the actions that did
+NOT send (skipped, filtered, failed).
+
+Like `messages`, this is a **dataset** — read it via
+`api.datasets.createUserSearch` + `api.datasets.search` with
+dataset type `'action_log'` — **singular**; the plural
+`action_logs` is the SQL *table* name (`executeSql`) and 422s as
+a dataset type. Base SQL alias: `ral`. Rows exist only for
+**live** mode — dry runs never write here.
+
+## 1. When a row appears (the scheduled gap)
+
+Not all at once. Two moments:
+
+```
+   at run time          — failed / filtered / skipped outcomes
+                          land immediately
+   at execution time    — a scheduled action gets its row only
+                          when the trigger clock fires and it
+                          actually executes
+```
+
+Between those two moments a scheduled send is INVISIBLE here: its
+execution log exists (the platform accepted it), but no
+action_log row and no message row yet. A UI that only reads the
+datalake shows nothing and looks broken — read the execution logs
+(`workflows.md` §6) and say "scheduled — nothing sent yet".
+
+## 2. Fields
+
+```
+id, workflow_id, action_id, workflow_execution_log_id,
+batch_id            — the run this outcome belongs to; THE
+                      campaign key (messages does not have it)
+decision_key        — which action fired
+context_key         — companion string key; like decision_key, it is
+                      SQL-lane only (neither is Flop-filterable, §5)
+mdm_subject_id, subject_name, session_id
+action_type ('sms'|'email'|'voice'|'data_exchange'), channel,
+classification
+status              — see §3
+external_id         — provider id; joins to messages.external_id
+sent_at, tool_call_payload, idempotency_key, metadata,
+attachments, body, sender_tool_id
+```
+
+## 3. Statuses
+
+```
+   pending → queued → sent → delivered
+                        └──→ failed
+
+   skipped    — the action's runtime_filter said no; nothing sent
+   filtered   — the parent run was filtered out; nothing sent
+   cancelled  — manually cancelled
+```
+
+Initial status mirrors the action execution log's outcome; a
+status updater with an `action_log_config` can move
+`sent → delivered/failed` here too (optional — many setups only
+reconcile messages).
+
+## 4. How everything joins
+
+```
+   run (batch_id) ──── WorkflowRunLog          "how is the batch doing"
+        │
+        ├── WorkflowExecutionLog (per subject) "what did the pipeline decide"
+        │        │
+        │        └── ActionExecutionLog        "what did each action attempt"
+        │                 │  (live + actually executed)
+        │                 ▼
+        └────────── action_logs row            "the outcome, queryable"
+                          │ external_id
+                          ▼
+                    messages row               "the communication + delivery"
+```
+
+Left side lives in the platform DB (read via
+`api.workflows.batchLogs` / `api.workflows.workflowLogs`); the
+bottom two are datalake datasets. `batch_id` ties the datalake
+rows back to the run; `external_id` ties an action_log to its
+message.
+
+## 5. Reading + audience export
+
+```typescript
+// dataset type is SINGULAR 'action_log' (the table is plural)
+const { data: search } = await api.datasets.createUserSearch(
+  tenantSlug, datalakeSlug, 'action_log',
+  { search_query: `ral.batch_id = '${batchId}'` },
+)
+const { data: page } = await api.datasets.search(
+  tenantSlug, datalakeSlug, 'action_log',
+  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+)
+```
+
+Filterable columns (Flop, the full set): `id`, `inserted_at`,
+`action_type`, `channel`, `status`, `batch_id`, `classification`,
+`workflow_id`, `sent_at`, `external_id`, `mdm_subject_id`. Note
+there is **no `global_search`** here (unlike the message dataset) —
+`decision_key`/`context_key` are not in this set either; scope them
+via the `search_query` SQL fragment above.
+
+"Who did this campaign go to" = the query above (subject columns
++ status per row — exportable as-is). For bulk export the platform
+also merges each finished batch into NDJSON artifacts in cold
+storage:
+
+```
+   <datalake>/workflows/<wf_slug>/<batch_id>/merged.ndjson              (per-subject)
+   <datalake>/workflows/<wf_slug>/<batch_id>/<decision_key>/merged.ndjson  (per-action payloads)
+```
+
+The batch log row (`api.workflows.batchLogs.get`) carries the
+download references once the batch completes.
+
+## 6. Gotchas
+
+1. **The scheduled gap (§1).** No action_log row ≠ nothing
+   happened. Check the execution logs before declaring a run
+   empty.
+
+2. **`batch_id` is a string, not a UUID** — manual runs look like
+   `manual:<uuid>`; DAC-triggered runs carry the ingest batch id.
+   Compare as strings.
+
+3. **One subject can have many rows for the same decision.**
+   Re-fires via `workflows.execute` with `manual_override: true`
+   (the retry path) create a NEW action_log each time. Latest row
+   wins for "current state"; the full set is the audit trail.
+
+4. **`skipped`/`filtered` rows are successes of the control
+   system, not failures.** Only `failed` is the retry surface
+   (`workflows.md` §8).
+
+5. **`tool_call_payload` is the rendered call** — what was
+   actually sent to the tool, after Liquid. When a message looks
+   wrong, read this before blaming the template engine.