@alvera-ai/platform-sdk 0.21.1 → 0.21.2

package/.agent/action_status_updaters.md

@@ -555,24 +555,24 @@ flag:
 
 ```
 last_run_at            when the poll worker last made progress
-last_run_status        'ok' | 'partial' | 'error'
-last_run_error         why the last run failed, or why a partial run was truncated
+last_run_status        'ok' | 'error'
+last_run_error         why the last run stopped; null when it read its whole window
 last_run_events_found  events fetched so far in the current run
 status                 'active' | 'cycle_detected'
 ```
 
-**A poll run has three outcomes, and only `'ok'` means it reconciled its
-whole time window:**
-
-- `'ok'` — the run completed and read its entire window. This is the only
-  value that proves the reconciliation is complete.
-- `'partial'` — the run completed but its provider fetch was **truncated**:
-  the window was not fully read, and the events it missed are the **newest**
-  ones. `last_run_error` carries the detail (it is **not** null on a
-  `partial` run). A client that treats `last_run_status !== 'error'` as
-  healthy silently accepts this incomplete reconciliation — check
-  `last_run_status === 'ok'` instead.
-- `'error'` — the run failed; `last_run_error` says why.
+**A poll run has two outcomes:**
+
+- `'ok'` — the run read its entire window. The reconciliation is
+  complete.
+- `'error'` — the run stopped; `last_run_error` says why.
+
+**There is no partial run.** The poller drains the window as a chain of
+jobs, one page per job, carrying the provider's next-page token into the
+next job, and there is no cap on how many pages it reads — so a run
+either reads every page of its window or stops with an error. A CloudWatch
+poll that is handed the same next-page token twice stops with an error
+naming that page rather than reading it again.
 
 `last_run_events_found` is the event count for the current run; because
 `refresh` is asynchronous (below), a read taken before the run finishes can

package/.agent/advanced_migrations.md

@@ -104,6 +104,14 @@ END $$;
 The same applies to `down_statement`, which is likelier to be run against a
 database that is not in the state you assumed.
 
+### One statement per body
+
+The platform runs each body as a single prepared statement. Two commands in one
+`up_statement` are accepted at create and fail at migrate with Postgres `42601`
+`cannot insert multiple commands into a prepared statement`. The two examples
+above are therefore two migrations, not one body. A `DO $$ … $$` block counts as
+one statement, so steps that must travel together go inside one.
+
 ### The table names are the platform's, not yours
 
 A generic table you declared as `contact_submissions` is physically

package/.agent/async.md

@@ -46,9 +46,10 @@ resource-specific. Common examples:
 **A data-activation-client run is NOT on this list — it is not a
 `waitUntilReady` status-poll target.** `.ingest` / `.ingestFile` /
 `.runManually` return a `202` + a `batch_id` (not a saved row and not
-a pollable status enum); progress is tracked by diffing the DAC's log
-and dataset rows by that `batch_id`, not by polling a `success`/`error`
-status. See `data_activation_clients.md` §6.
+a pollable status enum); progress is tracked through the run record
+and the DAC's log rows for that `batch_id` — a dataset row carries no
+`batch_id` of its own, it points at its log row — not by polling a
+`success`/`error` status. See `data_activation_clients.md` §6.
 
 The Datalake row is the odd one: its top-level `status` enum is
 `new | processing | ready` only — there is no terminal failure

package/.agent/cookbook/organic-marketing.md

@@ -38,7 +38,7 @@ is one call away from here.
 | Tenant + raw datalake               | The marketing team's own world               |
 | SMS tool, email tool, LLM tool      | Shared by every scenario below               |
 | Score Lead AI agent                 | Bands inbound leads                          |
-| Three generic tables                | Leads, the roster, and the audience          |
+| Four generic tables                 | Leads, the roster, the audience, the replies |
 | Three workflows                     | Band fan-out, birthday greeting, campaign    |
 | Authenticated links                 | The greeting's link and the campaign's link  |
 | Action status updater               | Delivery outcomes, reconciled on a cron      |
@@ -1255,6 +1255,11 @@ await ctx.waitForBatches(ctx.leadFormDacSlug, [ctx.batchBirthday, ctx.batchNoDob
 `manual_override: false` so the filter genuinely evaluates rather than
 being bypassed.
 
+The `sql_where_clause` picks the two contacts by the batches that wrote
+them, and that goes **through the log row**: a legal entity carries no
+`batch_id` of its own, it points at the `data_activation_logs` row of the
+ingest that wrote it through `alvera_data_activation_log_id`.
+
 **This run never reaches a terminal status, and waiting for one would hang
 until the deadline.** The birthday row's action is scheduled for a date in
 the future, so its execution log sits at `:executing` for the life of the
@@ -1263,7 +1268,9 @@ execution log, which is the moment the next step can read them.
 
 ```typescript
 const bdRunResp = await api.workflows.run(tenantSlug, datalakeSlug, ctx.birthdayWorkflowSlug, {
-  sql_where_clause: `le.batch_id IN ('${ctx.batchBirthday}', '${ctx.batchNoDob}')`,
+  sql_where_clause:
+    `le.alvera_data_activation_log_id IN (SELECT id FROM data_activation_logs` +
+    ` WHERE batch_id IN ('${ctx.batchBirthday}', '${ctx.batchNoDob}'))`,
   mode: 'live',
   manual_override: false,
 })
@@ -1319,11 +1326,14 @@ if ((bdByStatus.filtered ?? 0) !== 1) {
 ## 027 — find the contact the greeting is for
 
 `workflows.execute` is addressed by dataset id, so the birthday contact's
-legal-entity id has to be resolved first. Search scoped to its own batch.
+legal-entity id has to be resolved first. Search scoped to its own batch —
+through the log row again, since the row has no `batch_id` column.
 
 ```typescript
 const { data: bdSearchDef } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'legal_entity', {
-  search_query: `le.batch_id = '${ctx.batchBirthday}'`,
+  search_query:
+    `le.alvera_data_activation_log_id IN` +
+    ` (SELECT id FROM data_activation_logs WHERE batch_id = '${ctx.batchBirthday}')`,
 })
 if (bdSearchDef.status !== 'completed') {
   throw new Error(`legal_entity user-search status=${bdSearchDef.status} error=${bdSearchDef.error_message ?? '(none)'}`)
@@ -1580,27 +1590,44 @@ await ctx.deployGenericTable(ctx.rosterTableName)
 await ctx.deployGenericTable(ctx.audienceTableName)
 ```
 
-## 032 — the inbound-messages table, which you must not create
+## 032 — the inbound-messages table, which the app creates
 
-Replies land in `inbound_messages`. It is a **system** table: it ships with
-every datalake, its `type` is `'system'` rather than `'custom'`, and nobody
-creates it. You find it by name.
+Replies land in `inbound_messages`, and the app defines that table like any
+other generic table. The platform ships no inbound table: a lake starts with
+none, and an app that receives replies declares its own — with the columns
+its replies carry, nothing reserved about the name.
 
-Trying to create it is the mistake this step exists to prevent — the name is
-reserved and the physical table is already there, so the attempt fails in a
-way that reads like a permissions problem.
+`message_id` is the unique column, which makes a re-ingest of the same reply
+an upsert (§041 relies on it). `handle` and `body` are the sender's contact
+and words, so both are `tokenize`. `potential_duplicate` is the flag a human
+reviews when a handle maps to more than one customer.
 
 ```typescript
-const { data: allTables } = await api.genericTables.list(tenantSlug, datalakeSlug)
-const inbound = (allTables.data ?? []).find((t: { name?: string }) => t.name === 'inbound_messages')
-if (!inbound) {
-  throw new Error('inbound_messages must ship with every datalake')
-}
-if (inbound.type !== 'system') {
-  throw new Error(`inbound_messages must be a system table, got type=${inbound.type}`)
-}
+const inbound = await ctx.ensure(
+  'Inbound Messages table',
+  async () => {
+    const { data } = await api.genericTables.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { title?: string }) => t.title === 'Inbound Messages')
+  },
+  async () => {
+    const { data } = await api.genericTables.create(tenantSlug, datalakeSlug, {
+      title: 'Inbound Messages',
+      description: 'Inbound customer messages — campaign replies re-ingested through the reply client.',
+      columns: [
+        { name: 'message_id', title: 'Message ID', type: 'string', description: 'Vendor-supplied unique inbound-message id', is_unique: true, privacy_requirement: 'none' },
+        { name: 'handle', title: 'Handle', type: 'string', description: 'Sender phone/email the message arrived from', is_unique: false, privacy_requirement: 'tokenize', semantic_kind: 'string' },
+        { name: 'channel', title: 'Channel', type: 'string', description: 'Channel the message arrived on: sms | email', is_unique: false, privacy_requirement: 'none' },
+        { name: 'body', title: 'Body', type: 'string', description: 'Free-text message body', is_unique: false, privacy_requirement: 'tokenize', semantic_kind: 'text' },
+        { name: 'potential_duplicate', title: 'Potential Duplicate', type: 'boolean', description: 'Set when the sender handle maps to more than one LegalEntity — flagged for human review', is_unique: false, privacy_requirement: 'none' },
+      ],
+    })
+    return data
+  },
+)
 ctx.inboundTableId = inbound.id!
 ctx.inboundTableName = inbound.name!
+
+await ctx.deployGenericTable(ctx.inboundTableName)
 ```
 
 ## 033 — the roster contracts, on two clients
@@ -2393,7 +2420,7 @@ if (!campaignTracked.message.opened_at) {
 ## 041 — the reply comes back, and attaches to whoever sent it
 
 A reply arrives on the same handle the campaign sent to. It ingests into the
-**system** inbound table through a client whose `mdm_input_config` keys on
+inbound table §032 created through a client whose `mdm_input_config` keys on
 the same `(uri, value)` namespace §034 wrote — so the platform resolves the
 handle straight back to the customer and stamps their subject on the row.
 
@@ -2799,7 +2826,249 @@ if (advancingPoller.status !== 'active') {
 }
 ```
 
-## 045 — ask the lake a question in plain language
+## 045 — an SES sender on its own endpoint, and its delivery reconciled
+
+The campaign's email went out through the mock provider. A real deployment
+sends through SES, and three things about SES are worth proving rather than
+reading about.
+
+**An SES tool sends to its own `endpoint_url`.** It is the whole request URL;
+left blank, the tool uses `https://email.<region>.amazonaws.com`. Pointed at
+a local AWS stand-in, every send goes there instead, which is how this walk
+sends without an AWS account. A send that reached SES comes back with SES's
+message id, and the message row keeps it as `external_id`.
+
+**A message row comes from a workflow, not from a test call.** A tool's
+`testInvocation` sends, but writes no message row, so there would be nothing
+to reconcile. The step sends one email to one recipient from a workflow
+whose only action uses the SES tool. The action fires after the run is
+recorded, so the step waits for the row. A user search keeps the rows that
+matched when it was created and never picks up a later one, so each try
+creates a new search.
+
+**Name a status template by its provider's path.** Mailgun and SES both ship
+an `email_message_status` under `status_poller`, so the bare name answers
+409 with both paths as candidates. The updater names
+`status_poller/aws_ses/email_message_status`.
+
+**Delivery comes from SES's events.** SES has no CloudWatch Logs destination
+of its own: its events travel configuration set → EventBridge → rule → log
+group, and the platform's SES template reads each one. `detail.mail.messageId`
+finds the message by its `external_id`; a Delivery moves it to `delivered`;
+a Bounce, Complaint or Reject moves it to `failed`; any other event leaves it
+where it is. The local stand-in keeps every email it was sent but publishes
+none of SES's events, so locally the poll finds nothing and the message stays
+`sent`. Against real SES, with the configuration set routed to the updater's
+log group, the same poll moves it to `delivered` at SES's own delivery time.
+The step accepts either, and nothing else.
+
+**`refresh` only enqueues a poll.** It answers 202 with the row as it was;
+read the row again until `last_run_at` moves. `last_run_status` is `ok` when
+the run read its whole window and `error` when it stopped, never anything in
+between.
+
+```typescript
+const SES_ENDPOINT = 'http://localhost:4566'
+const SES_LOG_GROUP = '/aws/events/cookbook-ses-delivery'
+const SES_DECISION_KEY = 'ses_delivery_check'
+
+const sesTool = await ctx.ensure(
+  'SES email sender',
+  async () => {
+    const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((t: { name?: string }) => t.name === 'Cookbook SES Email Sender')
+  },
+  async () => {
+    const { data } = await api.tools.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook SES Email Sender',
+      description: 'SES email dispatcher, pointed at the local AWS stand-in by endpoint_url.',
+      intent: 'email',
+      status: 'active',
+      datalake_id: ctx.datalakeId,
+      body: {
+        tool_body_type: 'email',
+        provider: 'ses',
+        from_email: 'campaigns@bloom-salon.example.com',
+        from_name: 'Bloom Salon',
+        region: 'us-east-1',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
+        endpoint_url: SES_ENDPOINT,
+      },
+    })
+    return data
+  },
+)
+ctx.sesToolId = sesTool.id!
+
+const { data: storedSes } = await api.tools.get(tenantSlug, datalakeSlug, ctx.sesToolId)
+const storedSesBody = storedSes.body as { provider?: string; endpoint_url?: string | null }
+if (storedSesBody.provider !== 'ses' || storedSesBody.endpoint_url !== SES_ENDPOINT) {
+  throw new Error(`the SES tool must keep its endpoint, read back ${JSON.stringify(storedSesBody)}`)
+}
+
+// The bare name is ambiguous between Mailgun and SES.
+let bareName: unknown
+try {
+  await api.templates.metadataDetails(tenantSlug, datalakeSlug, 'email_message_status', 'status_poller')
+} catch (err) {
+  bareName = err
+}
+if ((bareName as { _httpStatus?: number } | undefined)?._httpStatus !== 409) {
+  throw new Error(`the bare email_message_status must answer 409, got ${JSON.stringify(bareName)}`)
+}
+if (!JSON.stringify(bareName).includes('status_poller/aws_ses/email_message_status')) {
+  throw new Error(`the 409 must name the SES path among its candidates: ${JSON.stringify(bareName)}`)
+}
+
+// One email, to one recipient, through the SES tool.
+const sesCheck = await ctx.ensure(
+  'SES delivery check workflow',
+  async () => {
+    const { data } = await api.workflows.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((w: { name?: string }) => w.name === 'Cookbook SES Delivery Check')
+  },
+  async () => {
+    const { data } = await api.workflows.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook SES Delivery Check',
+      description: 'One email through the SES tool, so its delivery can be reconciled.',
+      dataset_type: 'generic_table',
+      generic_table_id: ctx.audienceTableId,
+      status: 'live',
+      tags: ['marketing', 'ses'],
+      skip_mdm_resolution: false,
+      filter_config: { type: 'custom', body: '{% if event_dataset.email and event_dataset.email != "" %}true{% endif %}' },
+      decision_config: {
+        type: 'custom',
+        body: `["${SES_DECISION_KEY}"]`,
+        output_schema: { type: 'array', items: { type: 'string' } },
+      },
+      actions: [
+        {
+          action_type: 'email',
+          tool_id: ctx.sesToolId,
+          decision_key: SES_DECISION_KEY,
+          position: 0,
+          trigger_template: 'now',
+          idempotency_template: '{{ event_dataset.end_customer_id }}/ses-delivery-check',
+          tool_call: {
+            tool_call_type: 'email_request',
+            to: { type: 'custom', body: '{{ event_dataset.email }}' },
+            subject: { type: 'custom', body: 'Your slot at Bloom Salon' },
+            body: {
+              type: 'custom',
+              body:
+                `<p>Hi {{ event_dataset.name }}, we have kept your slot.</p>` +
+                `<p><a href="${ctx.bookingPageUrl}">See your booking</a></p>`,
+            },
+            link_prefix: ctx.campaignLinkPrefix,
+          },
+        },
+      ],
+    })
+    return data
+  },
+)
+ctx.sesCheckWorkflowSlug = sesCheck.slug!
+
+const { data: sesRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.sesCheckWorkflowSlug, {
+  sql_where_clause: `end_customer_id = '${ctx.adaId}'`,
+  mode: 'live',
+  manual_override: false,
+})
+await ctx.waitForFiredRun(datalakeSlug, sesRun.workflow_run_id)
+
+// The message row, found by its idempotency key, which names the same send on every rerun.
+// A search keeps the rows that matched when it was created, so each try creates a new one.
+const sesSentDeadline = Date.now() + 45_000
+let sesMessage: { status?: string; external_id?: string | null; sender_tool_id?: string } | undefined
+while (Date.now() < sesSentDeadline) {
+  const { data: sesSearch } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
+    search_query: `m.idempotency_key = '${ctx.adaId}/ses-delivery-check'`,
+  })
+  if (sesSearch.status !== 'completed') {
+    throw new Error(`message user-search status=${sesSearch.status} error=${sesSearch.error_message ?? '(none)'}`)
+  }
+  const { data } = await api.datasets.search(tenantSlug, datalakeSlug, 'message', {
+    userSearchId: sesSearch.id!,
+    dataAccessMode: 'raw',
+  })
+  sesMessage = (data.data ?? [])[0] as typeof sesMessage
+  if (sesMessage?.external_id) break
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+if (!sesMessage?.external_id) {
+  throw new Error(`the SES send must leave a message carrying SES's id, got ${JSON.stringify(sesMessage)}`)
+}
+if (sesMessage.sender_tool_id !== ctx.sesToolId) {
+  throw new Error(`the message must name the SES tool as its sender, got ${sesMessage.sender_tool_id}`)
+}
+if (!['sent', 'delivered'].includes(sesMessage.status ?? '')) {
+  throw new Error(`the SES send must leave the message sent, got ${sesMessage.status}`)
+}
+
+const sesUpdater = await ctx.ensure(
+  'SES delivery reconciler',
+  async () => {
+    const { data } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((u: { name?: string }) => u.name === 'Cookbook SES Delivery Updater')
+  },
+  async () => {
+    const { data } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook SES Delivery Updater',
+      cron_expression: '*/30 * * * *',
+      updater_type: 'cloud_watch',
+      updater_tool_id: ctx.cwToolId,
+      sender_tool_ids: [ctx.sesToolId],
+      datalake_id: ctx.datalakeId,
+      updater_body: {
+        updater_body_type: 'cloud_watch_request',
+        log_group_name: SES_LOG_GROUP,
+        start_time: '{{ now_msec | minutes_ago: 45 }}',
+        end_time: '{{ now_msec }}',
+      },
+      message_config: { type: 'system', path: 'status_poller/aws_ses/email_message_status' },
+      action_log_config: { type: 'system', path: 'status_poller/aws_ses/email_action_log_status' },
+    })
+    return data
+  },
+)
+ctx.sesUpdaterId = sesUpdater.id!
+
+// refresh only enqueues; the outcome lands on the row.
+const { data: beforePoll } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, ctx.sesUpdaterId)
+await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, ctx.sesUpdaterId)
+let polled = beforePoll
+for (let i = 0; i < 60 && polled.last_run_at === beforePoll.last_run_at; i++) {
+  await new Promise((r) => setTimeout(r, 1_000))
+  polled = (await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, ctx.sesUpdaterId)).data
+}
+if (polled.last_run_at === beforePoll.last_run_at) {
+  throw new Error('the SES poll never ran: last_run_at did not move in 60 seconds')
+}
+if (polled.last_run_status !== 'ok') {
+  throw new Error(`the SES poll must read its whole window, got ${polled.last_run_status}: ${polled.last_run_error}`)
+}
+
+// The message as the poll left it: delivered where SES published a Delivery, still sent where nothing did.
+const sesExternalId = sesMessage.external_id
+const { data: sesPage } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+  sql: `SELECT status, external_id FROM messages WHERE sender_tool_id = '${ctx.sesToolId}' AND channel = 'email'`,
+  mode: 'raw',
+})
+if (typeof sesPage === 'string') {
+  throw new Error('executeSql answered CSV where it should answer rows')
+}
+const sesAfter = (sesPage.data as unknown[][]).find((row) => row[1] === sesExternalId)
+if (!sesAfter) {
+  throw new Error(`no message with SES's id ${sesExternalId} after the poll: ${JSON.stringify(sesPage.data)}`)
+}
+if (!['sent', 'delivered'].includes(String(sesAfter[0]))) {
+  throw new Error(`after the poll the message must be sent or delivered, got ${sesAfter[0]}`)
+}
+```
+
+## 046 — ask the lake a question in plain language
 
 The last thing a marketing team needs is a way to look at any of this
 without writing SQL.
@@ -2827,7 +3096,7 @@ if (typeof generated.model !== 'string' || typeof generated.provider !== 'string
 console.log(`  ↳ ${generated.provider}/${generated.model} proposed: ${generated.sql.trim().slice(0, 120)}`)
 ```
 
-## 046 — run it read-only, then take the same page as CSV
+## 047 — run it read-only, then take the same page as CSV
 
 `executeSql` runs read-only — inserts, updates, deletes and DDL are all
 refused — and returns `{ data, meta }`. **`data` is an array of arrays**,
@@ -2835,7 +3104,7 @@ positional and aligned to `meta.columns`, because arbitrary SQL can produce
 duplicate or expression column names that object keys would collapse.
 
 The deterministic count below keeps the step independent of whatever the
-model proposed a moment ago, which is what you want in a walk: §045 proves
+model proposed a moment ago, which is what you want in a walk: §046 proves
 the generation, this proves the execution, and neither can mask a failure in
 the other.
 
@@ -2879,7 +3148,7 @@ if (!csvExport.data.includes('end_customer_id') || !csvExport.data.includes(ctx.
 }
 ```
 
-## 047 — one person, two identifiers, and what a second ingest leaves alone
+## 048 — one person, two identifiers, and what a second ingest leaves alone
 
 Every recipient so far carries **one** identifier: §034's template picks
 phone-or-email and writes a single slot. A real roster does not look like that.
@@ -3077,7 +3346,7 @@ if (afterSubjects.size !== 1 || !afterSubjects.has(twoIdSubject)) {
 
 # Outcome
 
-After all forty-seven steps run green, on one tenant and **one raw
+After all forty-eight steps run green, on one tenant and **one raw
 datalake**:
 
 - **Every inbound lead is banded.** Three leads land in the Lead Submissions
@@ -3096,18 +3365,21 @@ datalake**:
   is contacted at all, and its split sends each of them one variant on both
   SMS and email, every message carrying its own link to the booking page
   (§031–§040).
-- **A reply attaches to whoever sent it.** It ingests into the system inbound
-  table and resolves back to the recipient's subject without creating a new
-  one (§041).
+- **A reply attaches to whoever sent it.** It ingests into the app's own
+  inbound table and resolves back to the recipient's subject without creating
+  a new one (§032, §041).
 - **Delivery is reconciled, not assumed.** An action status updater turns
   provider delivery events into updates on a schedule, its stored body is
   read back against its checksum, and a poller whose request could never move
-  to the next page is refused at create (§042–§044).
+  to the next page is refused at create (§042–§044). An SES sender sends to
+  its own endpoint, a workflow's email through it leaves a message carrying
+  SES's id, and an updater reconciles that message through the platform's SES
+  template (§045).
 - **The lake answers in plain language.** Text-to-SQL proposes a query
   without running it; the read-only executor runs one and returns the same
-  page as CSV (§045–§046).
+  page as CSV (§046–§047).
 - **One person carries two identifiers.** A second ingest that names only the
-  email leaves the phone slot untouched on the same subject (§047).
+  email leaves the phone slot untouched on the same subject (§048).
 
 Running this walk again reuses all of it.
 
@@ -3136,6 +3408,10 @@ Running this walk again reuses all of it.
    generic-table row is never its own subject. With resolution on, the
    message and every link minted with it name the stamped subject as their
    `legal_entity_id`; skip it and the subject is nil — §038.
+6. **Name a status template by its provider's path.** Mailgun and SES both
+   ship an `email_message_status` under `status_poller`, so the bare name
+   answers 409 with both paths as candidates; use
+   `status_poller/aws_ses/email_message_status` — §045.
 
 # See also
 

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

@@ -1931,7 +1931,10 @@ ctx.bulkBatchId = await ctx.ingestFileAndWait(ctx.dataDacSlug, 4)
 
 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.
+`le` is the legal-entity alias the query compiler expects. A legal entity
+carries no `batch_id` of its own — it points at the `data_activation_logs`
+row of the ingest that wrote it — so the batch scope goes through that log
+row.
 
 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
@@ -1966,7 +1969,9 @@ if (unstamped.length > 0) {
 }
 
 const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'legal_entity', {
-  search_query: `le.batch_id = '${ctx.bulkBatchId}'`,
+  search_query:
+    `le.alvera_data_activation_log_id IN` +
+    ` (SELECT id FROM data_activation_logs WHERE batch_id = '${ctx.bulkBatchId}')`,
 })
 if (search.status !== 'completed') {
   throw new Error(`legal_entity user-search did not compile: ${search.status}`)