@alvera-ai/platform-sdk 0.21.0 → 0.21.1-next.g4e4bff9

package/.agent/AGENTS.md

@@ -327,7 +327,10 @@ from the filesystem at
 is no SDK function and no CLI verb that returns cookbook bytes
 at runtime.
 
-Each cookbook structure:
+Each cookbook structure — front matter, then these top-level `#`
+sections, each exactly once and in this order. The validator refuses a
+cookbook that is missing one, repeats one, reorders them, leaves one
+empty, or adds a top-level section that is not on this list:
 
 - **Front matter** — `title`, `summary`, `use_case`, `slug`,
   `vitest_source` (list of integration-test files the snippets
@@ -349,14 +352,17 @@ Each cookbook structure:
   carrying one fenced TypeScript block lifted from the anchor or
   ancillary vitest. State threads forward across subsections via
   plain JavaScript variables in the validator's generated
-  `describe` closure.
-- **Branches** — alternate paths the anchor vitest covers (a
-  filter rejection, a transport failure, an agent-classification
-  fallback).
-- **Rollback** — teardown order for the resources the cookbook
-  provisioned.
+  `describe` closure. A numbered step anywhere else in the file
+  is refused.
 - **Outcome** — author's prose summary of what the scenario
   produces.
+- **Gotchas** — one numbered list of the mistakes the walk exists
+  to keep you from making. Each item opens with a bold one-sentence
+  rule, says why it bites, and names the step that proves it as
+  `§NNN`. The validator refuses an item that names no step, or a
+  step the cookbook does not have — and every step runs against a
+  live platform — so a gotcha cannot outlive the behaviour it warns
+  about.
 - **See also** — links to relevant per-resource reference MDs
   and to the anchor + ancillary vitest files.
 

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/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.
 
@@ -3077,12 +3104,66 @@ if (afterSubjects.size !== 1 || !afterSubjects.has(twoIdSubject)) {
 
 # Outcome
 
-The marketing tenant exists with one raw datalake, an SMS tool, an LLM
-tool, a lead-submissions table, and an agent-driven workflow that bands
-every inbound lead and fans out to exactly one of four SMS actions.
+After all forty-seven steps run green, on one tenant and **one raw
+datalake**:
+
+- **Every inbound lead is banded.** Three leads land in the Lead Submissions
+  table through the client the platform provisioned with it, and the Score
+  Lead agent's band steers each one to exactly one of four SMS actions
+  (§014–§018).
+- **A birthday greeting is scheduled a year out.** Two contacts arrive through
+  the lead-form client; the Happy Birthday workflow's pure-Liquid trigger
+  schedules a greeting for the one with a birthday and filters the one
+  without. Fast-forwarded, the greeting carries an authenticated link whose
+  exchange names that contact, and the tap, the page and the form are tracked
+  on the message (§020–§030).
+- **A campaign goes out A/B on two channels.** One business and four
+  recipients land in the roster and audience tables through contract pairs on
+  separate clients, identities first. The campaign workflow's gates decide who
+  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 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).
+- **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).
+- **One person carries two identifiers.** A second ingest that names only the
+  email leaves the phone slot untouched on the same subject (§047).
 
 Running this walk again reuses all of it.
 
+# Gotchas
+
+1. **`link_prefix` is required on every SMS and email call, even one whose
+   body carries no link of its own.** Any URL in the body — including one a
+   lead typed into the form — goes out as `<link_prefix>/<token>`. Leave the
+   prefix off and the workflow is refused at create with a 422 on
+   `/actions/<n>/tool_call/link_prefix` — §012, §038.
+2. **`workflows.run` only schedules a run.** The ids a scenario needs are
+   written later, when the run fires, so poll until `workflow_run_log_id` is
+   a string, not until `status` leaves `'scheduled'`. And a run whose action
+   is scheduled for a future date never reaches a terminal status at all:
+   wait for every row's execution log instead — §007, §025.
+3. **Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+   different questions — received versus written — and a batch whose row is
+   refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`.
+   A gate on `rows_ingested` calls that green, and the failure surfaces three
+   steps later as a workflow that seems broken — §007, §015.
+4. **On a repeat run every action is skipped, and that is correct.** The
+   idempotency key that already fired will not fire again, so read the
+   `message` row the lake keeps, not the execution log of the run you just
+   made — on run two that log carries no body at all — §017, §029.
+5. **`skip_mdm_resolution: false` is set explicitly, and must be.** A
+   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.
+
 # See also
 
 - `datalakes.md` — the create body, and what a derived pair would add

package/.agent/cookbook/payments-compliance.md

@@ -2131,7 +2131,7 @@ truncate a table with an inbound foreign key, regardless of whether the
 referencing tables hold any rows, so repairing a parent empties its whole
 dependent closure, transitively, in a single statement — and all of them are
 re-copied by the same run. `legal_entities` is the target here on purpose:
-§029's contract pair resolved every screened subject through it, and
+§019's contract pair resolved every screened subject through it, and
 `legal_entity_identifications` points at it, so `emptied` genuinely names more
 than one table. Any surface offering this button should read `resync_empties`
 and say the count before it is pressed.
@@ -2208,15 +2208,34 @@ pairs split across four Data Activation Clients, and two agentic workflows
 that between them screen, decide, notify and track — plus the copy's own
 arrival state, read back per table and repaired.
 
-Two things are worth carrying out of this walk. **The pair must not run
-concurrently** (§020) — one writer per subject, or the unique index that
-guards against duplicate entities refuses your row on the only run that
-matters, the first. And **assert end states, not transitions** (§024) — an
-idempotency key that has already fired will not fire again, which is the
-product working, not the walk failing.
-
 Running this walk again reuses all of it.
 
+# Gotchas
+
+1. **The pair must not run concurrently.** One writer per subject, or the
+   unique index that guards against duplicate entities refuses your row on
+   the only run that matters, the first — §020.
+2. **Assert end states, not transitions.** An idempotency key that has
+   already fired will not fire again, which is the product working, not the
+   walk failing — §024.
+3. **Gate on `dataset_updated`, never on `rows_ingested`.** They answer
+   different questions — received versus written — and a batch whose row is
+   refused reports `rows_ingested: 1, dataset_updated: 0, status: 'partial'`.
+   A gate on `rows_ingested` calls that green, and the failure surfaces three
+   steps later as a workflow that seems broken — §008, §022.
+4. **The system-template catalog is paginated, and page 1 is not the
+   catalog.** The template you want is as likely to be on page 3; reading
+   page 1 and concluding a template does not exist is the trap — §014.
+5. **The identifier shape is where the contract pair goes wrong, and there
+   are three of them.** A contract's `mdm_input_config` takes `uri` / `type`
+   / `value`; a LegalEntity identification takes `id_type` / `id_number` /
+   `uri`; `POST /mdm/verify` takes `system` / `id_type` / `value` — §019.
+6. **A repair empties more than the table you name, and its `202` means
+   started.** Postgres will not truncate a table with an inbound foreign key,
+   so repairing a parent empties its whole dependent closure; there is no
+   completion callback, so poll until every emptied table reads `caught_up`
+   again — §039.
+
 # See also
 
 - `datalakes.md` — the create body, and what the derived pair is for

package/.agent/cookbook/primary-care.md

@@ -2194,30 +2194,30 @@ After all thirty-one steps run green, on one tenant and **three datalakes**:
   read back, one table emptied and copied again, and every table the repair
   took with it waited back to `caught_up`.
 
-What this surface teaches that the raw cookbooks cannot:
+# Gotchas
 
 1. **A masked jsonb column is `jsonb` in raw and `text` in both copies, and
    the types are supposed to differ.** Logical replication ships a text
    rendering and feeds it to the subscriber's input function, so
    `jsonb → text` always works and `jsonb → text[]` never does. The
    invariant is scalar-ness, not type parity — and `is_array: true`
-   describes the JSON document, not the Postgres column.
+   describes the JSON document, not the Postgres column — §016.
 2. **The tier follows what the prompt can reach.** The triage agent here runs
    `tokenized` because it reads patient messages; the equivalent agent in
    `subscription-saas` runs `raw` because its prompt carries an account
-   number and nothing else. Neither is a house style.
+   number and nothing else. Neither is a house style — §021.
 3. **The two copies are different from each other on purpose.** `tok_<hash>`
    is a stable join key for a machine; `xxxx-<tail>` is an unjoinable
-   placeholder for a person.
+   placeholder for a person — §029.
 4. **A key the contract does not read is not an error.** It renders nothing,
    the column lands `null`, the batch reports green, and the failure appears
    two steps later as an action rejecting an empty recipient. Assert columns
-   on the row.
+   on the row — §015.
 5. **"The copy exists" and "the copy is complete" are different questions.**
    `finished_copy` has not finished — read `caught_up`, not the state's name.
    And a repair is not scoped to the table you name: Postgres will not
    truncate a table anything references, so the dependent closure goes with
-   it. Both are why `emptied` is returned rather than assumed.
+   it. Both are why `emptied` is returned rather than assumed — §030, §031.
 
 # 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}`)
@@ -2405,7 +2410,7 @@ After all forty-one steps run green, on one tenant and **one raw datalake**:
 - **A second person** is on the tenant with a `member` role, invited and
   accepted entirely through the SDK.
 
-Four things this walk teaches that are easy to learn the expensive way:
+# Gotchas
 
 1. **Never bind a contract pair to one activation client.** The fan-out
    staggers by row, so a pair on one client resolves the same subject twice
@@ -2413,10 +2418,10 @@ Four things this walk teaches that are easy to learn the expensive way:
    sequence them — §012, and again at §030 and §033.
 2. **Gate on `dataset_updated`, not `rows_ingested`.** Received is not
    written. A refused row reports the first and not the second, and a walk
-   gated on the wrong one goes green over an empty table.
+   gated on the wrong one goes green over an empty table — §007, §013.
 3. **Search the idempotency key, never the workflow id.** The key is built
    from a stable business id and names the same message forever; a workflow
-   id changes the moment the resource is recreated.
+   id changes the moment the resource is recreated — §019, §023.
 4. **Assert the end state, not the transition.** An idempotency key fires
    once ever, so every assertion here accepts both the first run's shape and
    the repeat run's — §027 spells that out, and §040 defers its proof to

package/.agent/data_activation_clients.md

@@ -389,7 +389,7 @@ const { data } = await api.dataActivationClients.ingest(
   tenantSlug, datalakeSlug, activationClientSlug,
   { data: rowAsJson },                  // a single row, shaped per the CSV/JSON the contracts expect
 )
-// data.batch_id   — UUID; the row's batch identifier (use to find log rows)
+// data.batch_id   — UUID; the run's batch identifier (use to find the run's log rows)
 // data.key        — storage key for the row's archived ndjson
 // data.jobs_count — number of downstream jobs the platform enqueued
 ```
@@ -400,8 +400,11 @@ been written, poll the logs (§6.4) or use the verification
 pattern (§6.6).
 
 The `batch_id` is the most important field on the response —
-every downstream log row and dataset row carries the same
-`batch_id`, so it's the join key for run-specific verification.
+every log row the run writes carries it, and every dataset row the
+run writes points at one of those log rows through
+`alvera_data_activation_log_id`. A dataset row carries no
+`batch_id` of its own, so the batch reaches the rows through the
+log rows: that is the join for run-specific verification.
 
 ### 6.2 Bulk file ingestion — `.ingestFile`
 
@@ -490,8 +493,9 @@ batch_id            UUID — the run's batch identifier
 dataset_table       string — the target dataset/table name
 rows_ingested       number — count of top-level rows the contract emitted
                               (cascade rows carry 0)
-dataset_updated     number — count of dataset rows whose batch_id this run wrote
-                              (load-bearing: see Gotcha 7)
+dataset_updated     number — count of dataset rows that point at this log row
+                              (each row the run writes carries its log row's id in
+                              alvera_data_activation_log_id; load-bearing: see Gotcha 7)
 output_files        { object_key, mode }[] — merged ndjson archive refs, one per
                                 bucket; mode is 'raw' | 'tokenized' | 'redacted'
                                 (empty until the post-batch merge worker commits).
@@ -639,29 +643,32 @@ spends its full timeout and then reports nothing about the cause.
 
 ### 6.6 Verifying ingestion: the two-step dataset search
 
-> **Simplest landing check — `executeSql`.** Ingestion is async (the row
-> commits a moment after the `202`). When you just need to know a row
-> *landed*, poll `datalakes.executeSql` with a read-only `SELECT … WHERE
-> batch_id = '…'`: **each call is a fresh read, so there is no stale
-> snapshot to recover from** — unlike a `createUserSearch` created before
-> the row commits, which captures nothing and never updates. Gate on it,
-> then run the two-step `createUserSearch` below **once** (race-free) only
-> if you need the dataset's alias-join + tokenization semantics.
+> **Simplest landing check — the run's own log rows.** Ingestion is async
+> (the row commits a moment after the `202`). When you just need to know
+> rows *landed*, read the run's log rows (§6.4) filtered by its
+> `batch_id`. Every dataset row the run writes points at the log row for
+> its table, and that log row's `dataset_updated` counts it — so the log
+> rows answer the question with no query on the dataset table and no
+> table name to know. A dataset row carries no `batch_id` of its own to
+> filter on. **Each call is a fresh read, so there is no stale snapshot to
+> recover from** — unlike a `createUserSearch` created before the row
+> commits, which captures nothing and never updates. Gate on it, then run
+> the two-step `createUserSearch` below **once** (race-free) only if you
+> need the dataset's alias-join + tokenization semantics.
 >
 > ```typescript
-> const { data: probe } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
->   sql: `SELECT 1 FROM ${tableName} WHERE batch_id = '${batchId}' LIMIT 1`,
->   mode: 'raw',
-> })
-> // `data` is an array-of-arrays (a `string` only for { format: 'csv' });
-> // a non-empty page proves the batch landed. The table is named the same
-> // in every lake — `mode` selects which copy answers, not which name.
-> const landed = typeof probe !== 'string' && probe.data.length > 0
+> const { data: logs } = await api.dataActivationClients.logs.list(
+>   tenantSlug, datalakeSlug, activationClientSlug,
+>   { filters: [{ field: 'batch_id', op: '==', value: batchId }] },
+> )
+> // One log row per dataset table the run wrote into; each counts the rows
+> // that point at it. A sum above zero proves the batch landed.
+> const landed = (logs.data ?? []).reduce((n, log) => n + (log.dataset_updated ?? 0), 0) > 0
 > ```
 >
 > `createUserSearch` is the heavier, workflow-oriented surface — reach for
-> it when you need its alias joins (`ri.value`, tokenized read-back), not
-> for a plain "did it land" check.
+> it when you need the rows themselves: its alias joins, tokenized
+> read-back. Not for a plain "did it land" check.
 
 The canonical way to **prove a row landed in the datalake** is
 to query the dataset directly. This is a two-step pattern:
@@ -683,7 +690,8 @@ const { data: search } = await api.datasets.createUserSearch(
   'patient',                                              // dataset name
   {
     search_query: `ri.value = '${externalPatientId}'`     // SQL WHERE-clause fragment
-                   + ` AND le.batch_id = '${batchId}'`,
+                   + ` AND le.alvera_data_activation_log_id IN`
+                   + ` (SELECT id FROM data_activation_logs WHERE batch_id = '${batchId}')`,
   },
 )
 // search.id            — UUID of the materialised result set
@@ -736,8 +744,46 @@ a patient or an appointment is now a generic table you declare, plus
 the legal entity its rows resolve to**; there is no dataset of that
 name to search. The four cookbooks all take this shape.
 
-The `<alias>.batch_id` predicate scopes a search to one run, which is
-the usual reason to reach for this surface at all.
+Scoping a search to one run is the usual reason to reach for this
+surface at all, and it goes **through the log row**. A row carries no
+`batch_id`, `client_id`, `user_id` or `source_uri` of its own: it
+carries `alvera_data_activation_log_id`, the `data_activation_logs` row
+of the ingest that wrote it, and the batch lives there. So the
+predicate is
+
+```
+<alias>.alvera_data_activation_log_id IN
+  (SELECT id FROM data_activation_logs WHERE batch_id = '<batch_id>')
+```
+
+The search runs with read access across the whole lake, so
+`data_activation_logs` is readable from inside it. The pointer is null
+on a row nothing ingested (a row an app wrote itself), so such a row
+never matches a batch predicate.
+
+#### Where a row came from, coming back
+
+A searched row carries the pointer **and** the log row it points at,
+loaded. Measured on a live run — one legal entity, one generic-table row
+— the platform columns that come back are:
+
+```
+id                             string
+inserted_at / updated_at       string
+checksum                       string
+checksum_changed?              boolean   (the key has the question mark)
+legal_entity_id                string    (generic-table rows)
+alvera_data_activation_log_id  string    (null on a row no ingest wrote)
+alvera_data_activation_log     object    — the log row itself:
+    id, batch_id, client_id, user_id, source_uri, dataset_table,
+    rows_ingested, dataset_updated, status, error, input_files,
+    output_files, inserted_at, updated_at
+```
+
+So "which batch wrote this row?" is `row.alvera_data_activation_log.batch_id`,
+and "where did it come from?" is `row.alvera_data_activation_log.source_uri` —
+there is no top-level `batch_id`, `client_id`, `user_id` or `source_uri` on
+the row unless the table declared a column of that name itself.
 
 #### What a masked column looks like coming back
 
@@ -807,13 +853,13 @@ screen. Pick the mode by which of those two readers you are serving.
    pattern in §6.6) before treating the row as ingested.
 
 7. **`dataset_updated > 0` is the load-bearing freshness
-   gate.** `rows_ingested` flips as soon as the per-row job
-   completes, but the dataset row's `batch_id` column is
-   updated by a downstream trigger that can lag. Filtering a
-   `.createUserSearch` by `<base_alias>.batch_id = '<this>'`
-   BEFORE that trigger fires returns an empty result set,
-   and there's no way to refresh the materialised result —
-   you'd have to POST a new search. Poll for
+   gate.** `rows_ingested` counts rows the contract emitted —
+   received, not persisted. `dataset_updated` counts the dataset
+   rows that point at the log row, so it moves only when a row
+   has been written. A `.createUserSearch` scoped to the batch
+   (§6.6) issued BEFORE the rows are written returns an empty
+   result set, and there's no way to refresh the materialised
+   result — you'd have to POST a new search. Poll for
    `dataset_updated > 0` before issuing the search.
 
 8. **`output_files` empty ≠ batch failed.** A log row with