@alvera-ai/platform-sdk 0.17.0 → 0.18.0

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

@@ -1,364 +0,0 @@
----
-title: Subscription industry bootstrap setup
-summary: Auth as root, sign up + confirm a fresh industry-admin user, create an subscription tenant + datalake. Shared by every subscription scenario cookbook.
-industry: subscription
-slug: subscription
-vitest_source:
-  - integration-tests/tests/subscription/bootstrap.test.ts
-status: green
----
-
-# Problem
-
-Every subscription scenario cookbook needs the same
-starting point: a fresh tenant on the platform with an
-subscription-domain datalake attached, accessed by an
-industry-admin user. Authoring this prelude inline inside every
-scenario cookbook would duplicate the auth + tenant + datalake
-chain across two cookbooks (and six more across the other
-industries). The validator auto-discovers this file from each
-cookbook's `industry: subscription` front-matter and
-inlines its numbered steps ahead of the scenario's own, so the
-generated bun:test spec is hermetic without the cookbook author
-having to copy-paste this prelude.
-
-# Composition
-
-| Resource provisioned          | Owner       |
-|-------------------------------|-------------|
-| Root session                  | setup       |
-| Industry-admin user (`sarah`) | setup       |
-| Subscription tenant     | setup       |
-| Subscription datalake   | setup       |
-
-# Walkthrough
-
-## 001 — root admin signs in and provisions a fresh industry-admin user
-
-Authenticate as the platform's root admin (`admin@dev.local` /
-`devpassword` in local dev) via the tenantless bootstrap login —
-keyless by structural necessity (no tenant exists yet to scope a
-key to), and a dev/test-only surface. Then sign up a per-run industry-admin
-user (`sarah`) under a unique email derived from `runSuffix`, and
-confirm them so they can sign in. Both the signup and the confirm
-endpoints require root scope.
-
-```typescript
-ctx.rootSession = await createBootstrapSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: process.env.ALVERA_ROOT_EMAIL!,
-  password: process.env.ALVERA_ROOT_PASSWORD!,
-})
-ctx.rootApi = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: ctx.rootSession.sessionToken,
-  apiKey: '',
-})
-
-ctx.sarahEmail = `cookbook-sarah-${runSuffix}@dev.local`
-ctx.sarahPassword = 'CookbookPass1!'
-
-const signUpResp = await ctx.rootApi.admin.signUp({
-  email: ctx.sarahEmail,
-  password: ctx.sarahPassword,
-  first_name: 'Cookbook',
-  last_name: 'Sarah',
-})
-ctx.sarahUserId = signUpResp.data.id
-await ctx.rootApi.admin.confirmUser(ctx.sarahUserId)
-```
-
-## 002 — sarah signs in (tenantless) and creates the subscription tenant
-
-Sarah signs in for the first time without a tenant scope (no
-tenant exists yet for her), then immediately creates a fresh
-subscription tenant. The tenant's server-derived `slug` is
-captured into the closure-scoped `tenantSlug` slot for downstream
-steps.
-
-```typescript
-ctx.sarahTenantlessSession = await createBootstrapSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: ctx.sarahEmail,
-  password: ctx.sarahPassword,
-})
-ctx.sarahTenantlessApi = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: ctx.sarahTenantlessSession.sessionToken,
-  apiKey: '',
-})
-
-const tenantResp = await ctx.sarahTenantlessApi.tenants.create({
-  name: `Cookbook Subscription ${runSuffix}`,
-})
-tenantSlug = tenantResp.data.slug!
-```
-
-## 003 — sarah signs in tenant-scoped — the canonical client
-
-Re-mint sarah's session with the new tenant slug. This bearer is
-the canonical tenant-scoped client every subsequent step uses; it
-is assigned to the closure-scoped `api` slot so the scenario
-cookbook's steps inherit it via inlining.
-
-```typescript
-// A tenant-scoped login requires X-API-Key — mint a public_api key for
-// the fresh tenant via the platform-admin side door (root Bearer). In the
-// web console this is Settings -> API Keys; any of the tenant's keys
-// satisfies the login gate, and the minted Bearer inherits this key's
-// origin policy.
-const { data: mintedKey } = await ctx.rootApi.admin.createTenantApiKey(tenantSlug, {
-  name: `Cookbook Bootstrap Key ${runSuffix}`,
-  data_access_mode: 'unregulated',
-})
-ctx.tenantApiKey = mintedKey.api_key
-
-const sarahTenantSession = await createSession({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  email: ctx.sarahEmail,
-  password: ctx.sarahPassword,
-  tenantSlug,
-  apiKey: ctx.tenantApiKey,
-})
-api = createIsolatedPlatformApi({
-  baseUrl: process.env.ALVERA_BASE_URL!,
-  sessionToken: sarahTenantSession.sessionToken,
-  apiKey: ctx.tenantApiKey,
-})
-```
-
-## 004 — sarah creates the subscription datalake
-
-Provision an subscription-domain datalake on the new
-tenant. The DB schemas are scoped to the cookbook run via
-`runSuffix` so parallel cookbook runs do not collide on schema
-names. Local-dev defaults (`postgres` on `localhost:5432`,
-`alvera_dev_subscription`) match the seeded `dev.exs`
-setup; LocalStack S3 (`localhost:4566`) serves the unregulated +
-regulated buckets. The datalake's server-derived `slug` is
-captured into `datalakeSlug`.
-
-```typescript
-const DB_HOST = 'localhost'
-const DB_PORT = 5432
-const DB_USER = 'postgres'
-const DB_PASS = 'postgres'
-const DB_NAME = 'alvera_dev_subscription'
-const UNREG_SCHEMA = `cookbook_${runSuffix}_unreg`
-const REG_SCHEMA = `cookbook_${runSuffix}_reg`
-
-const S3 = {
-  cloud_storage_type: 'aws' as const,
-  region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
-  endpoint: 'http://localhost:4566',
-}
-
-const datalakeResp = await api.datalakes.create(tenantSlug, {
-  name: `Cookbook Subscription Datalake ${runSuffix}`,
-  description: 'Subscription datalake provisioned by cookbook doctest.',
-  data_domain: 'subscription',
-  timezone: 'America/New_York',
-  pool_size: 5,
-
-  unregulated_db_writer_host: DB_HOST,
-  unregulated_db_writer_port: DB_PORT,
-  unregulated_db_writer_name: DB_NAME,
-  unregulated_db_writer_schema: UNREG_SCHEMA,
-  unregulated_db_writer_auth_method: 'password',
-  unregulated_db_writer_user: DB_USER,
-  unregulated_db_writer_pass: DB_PASS,
-  unregulated_db_writer_enable_ssl: false,
-  unregulated_db_reader_host: DB_HOST,
-  unregulated_db_reader_port: DB_PORT,
-  unregulated_db_reader_name: DB_NAME,
-  unregulated_db_reader_schema: UNREG_SCHEMA,
-  unregulated_db_reader_auth_method: 'password',
-  unregulated_db_reader_user: DB_USER,
-  unregulated_db_reader_pass: DB_PASS,
-  unregulated_db_reader_enable_ssl: false,
-
-  regulated_data_db_writer_host: DB_HOST,
-  regulated_data_db_writer_port: DB_PORT,
-  regulated_data_db_writer_name: DB_NAME,
-  regulated_data_db_writer_schema: REG_SCHEMA,
-  regulated_data_db_writer_auth_method: 'password',
-  regulated_data_db_writer_user: DB_USER,
-  regulated_data_db_writer_pass: DB_PASS,
-  regulated_data_db_writer_enable_ssl: false,
-  regulated_data_db_reader_host: DB_HOST,
-  regulated_data_db_reader_port: DB_PORT,
-  regulated_data_db_reader_name: DB_NAME,
-  regulated_data_db_reader_schema: REG_SCHEMA,
-  regulated_data_db_reader_auth_method: 'password',
-  regulated_data_db_reader_user: DB_USER,
-  regulated_data_db_reader_pass: DB_PASS,
-  regulated_data_db_reader_enable_ssl: false,
-
-  unregulated_cloud_storage: { ...S3, bucket: 'subscription-lake-unregulated' },
-  regulated_cloud_storage: { ...S3, bucket: 'subscription-lake-regulated' },
-})
-datalakeSlug = datalakeResp.data.slug!
-// `tools.create` and a few other endpoints accept the datalake by
-// UUID in the request body rather than only the slug in the URL,
-// so keep it on `ctx` for downstream steps that need it.
-ctx.datalakeId = datalakeResp.data.id!
-```
-
-## 005 — enqueue the datalake migrations
-
-`datalakes.create` persists the datalake row in `:new` status but
-does not itself run the schema migrations. Migration is a
-separately-triggered async job so the operator controls when the
-(potentially slow) per-industry DDL runs. `datalakes.migrate`
-enqueues the `DatalakeMigrationWorker` Oban job and returns
-immediately with `status: 'enqueued'` plus the Oban `job_id`. The
-poll in §006 then waits for that worker to finish — without this
-call the datalake would sit at `:new` forever.
-
-```typescript
-const migrateResp = await api.datalakes.migrate(tenantSlug, datalakeSlug)
-if (migrateResp.data.status !== 'enqueued') {
-  throw new Error(
-    `datalake migration not enqueued (status: ${migrateResp.data.status})`,
-  )
-}
-```
-
-## 006 — poll the datalake until status is ready
-
-Datalake migrations are async — the §005 migrate call enqueued a
-`DatalakeMigrationWorker` Oban job that runs the per-industry
-schema migrations (the regulated customer + invoice tables and
-their join tables), deploys PostgREST roles, and provisions the
-service-account bot user. Downstream resource creates (tools,
-workflows) only need `datalakeId` to be persisted (which it is
-the moment §004 returns), but any scenario step that ingests into
-the regulated/unregulated DBs or runs a dataset search requires
-`status: 'ready'`. Polling here makes every subscription
-scenario cookbook deterministic regardless of how long the cold
-migration takes on a given host; the loop exits the moment the
-datalake reaches `:ready`, so the 5-minute cap is paid only in
-failure mode.
-
-```typescript
-const READY_TIMEOUT_MS = 5 * 60_000
-const READY_POLL_MS = 5_000
-const deadline = Date.now() + READY_TIMEOUT_MS
-let datalakeStatus: string | undefined
-while (Date.now() < deadline) {
-  const { data } = await api.datalakes.get(tenantSlug, ctx.datalakeId)
-  datalakeStatus = data.status
-  if (datalakeStatus === 'ready') break
-  await new Promise((r) => setTimeout(r, READY_POLL_MS))
-}
-if (datalakeStatus !== 'ready') {
-  throw new Error(
-    `datalake did not reach :ready within ${READY_TIMEOUT_MS}ms (last status: ${datalakeStatus})`,
-  )
-}
-```
-
-## 007 — a reusable "wait until the run has fired" helper
-
-`workflows.run` only **schedules** a run. It records it and returns
-immediately with `workflow_run_id` / `status` / `scheduled_at`; the
-`workflow_run_log_id` and `batch_id` a scenario needs are written
-later, when the run actually fires, and are read back from
-`workflowRuns.get`.
-
-Two traps live in that gap, so every subscription scenario shares one
-helper rather than re-deriving it:
-
-- **Poll until `workflow_run_log_id` is a string — NOT until `status`
-  leaves `'scheduled'`.** Those are different moments: the run reaches
-  `processing` first and writes the log id a beat later. A predicate on
-  status alone releases you to read a `null`, and because
-  `typeof null === 'object'` the symptom is a baffling *"expected
-  string, got object"* rather than an obvious nil.
-- **Raise on `failed` carrying `failure_reason` rather than polling to
-  the deadline.** A scenario blocked on a run that will never fire
-  should say why on the first read, not thirty seconds later behind a
-  generic timeout.
-
-The helper is stored on the shared `ctx` bag rather than declared as a
-plain function because each numbered step compiles into its own `it()`
-block — a bare `function` here would not be in scope for the steps that
-call it.
-
-```typescript
-const FIRED_TIMEOUT_MS = 60_000
-const FIRED_POLL_MS = 1_000
-
-ctx.waitForFiredRun = async (
-  runDatalakeSlug: string,
-  runId: string,
-  timeoutMs: number = FIRED_TIMEOUT_MS,
-): Promise<{ workflowRunLogId: string; batchId: string | null }> => {
-  const deadline = Date.now() + timeoutMs
-  let lastStatus: string | undefined
-  while (Date.now() < deadline) {
-    const { data } = await api.workflowRuns.get(tenantSlug, runDatalakeSlug, runId)
-    lastStatus = data.status
-    if (data.status === 'failed') {
-      throw new Error(
-        `workflow run ${runId} failed: ${data.failure_reason ?? 'no failure_reason given'}`,
-      )
-    }
-    if (typeof data.workflow_run_log_id === 'string') {
-      return { workflowRunLogId: data.workflow_run_log_id, batchId: data.batch_id ?? null }
-    }
-    await new Promise((r) => setTimeout(r, FIRED_POLL_MS))
-  }
-  throw new Error(
-    `workflow run ${runId} never fired within ${timeoutMs}ms (last status: ${lastStatus})`,
-  )
-}
-```
-
-# Rollback
-
-The cookbook doctest harness does not currently tear down the
-created tenant / datalake / user — each run mints fresh names via
-`runSuffix` so reruns do not collide, and the seeded local DB is
-cheap to reset (`mix ecto.reset` on the platform). When the
-validator graduates to continuous integration at Milestone 18
-(running against the mockoon-backed mock env at `ALVERA_ENV=mock`),
-no real state is created at all.
-
-# Outcome
-
-After this setup runs, the closure-scoped slots are populated as:
-
-- `api` — a tenant-scoped `PlatformApi` client authenticated as
-  the industry-admin user
-- `tenantSlug` — server-derived slug of the fresh
-  subscription tenant
-- `datalakeSlug` — server-derived slug of the fresh
-  subscription datalake
-- `ctx.sarahEmail` / `ctx.sarahPassword` — the per-run admin
-  credentials (kept on `ctx` because no scenario cookbook needs
-  to re-authenticate by default)
-- `ctx.tenantApiKey` — the tenant's publishable API key (minted in
-  setup via `admin.createTenantApiKey`); thread it into any
-  additional tenant-scoped `createSession` a scenario performs
-- `ctx.waitForFiredRun(datalakeSlug, runId)` — polls `workflowRuns.get`
-  until a scheduled run has actually fired, then returns its
-  `{ workflowRunLogId, batchId }`. Use it after every `workflows.run`;
-  reading `workflow_run_log_id` off the run response returns `null`
-  because run-workflow only schedules (see §007)
-
-Scenario cookbooks under `industry: subscription` start at
-their own `§001` with these slots already populated.
-
-# See also
-
-- `.agent/datalakes.md` — datalake create body shape (regulated +
-  unregulated tier configuration)
-- `.agent/AGENTS.md` § SDK auth + client construction — root vs
-  tenantless vs tenant-scoped session scopes
-- `integration-tests/tests/subscription/bootstrap.test.ts` —
-  the green test these snippets are lifted from (the sibling
-  datalake creation and the sanity probes are out of scope for
-  this lean cookbook setup)

package/.agent/cookbook/action-status-updaters.md

@@ -1,278 +0,0 @@
----
-title: "Capability: reconcile delivery status of the messages you send"
-summary: A capability walk for action status updaters. Register a poller tool that reads a delivery-log source (here CloudWatch via LocalStack) and an action status updater that runs on a cron, maps log events back to the messages that produced them, and updates their status (`api.actionStatusUpdaters.create`). So a "sent" SMS becomes "delivered" / "failed" without you polling by hand.
-industry: subscription
-slug: action-status-updaters
-vitest_source:
-  - integration-tests/tests/subscription/action-status-updaters.test.ts
-  - integration-tests/tests/subscription/bootstrap.test.ts
-status: green
----
-
-# Capability
-
-**What you get:** the messages you send (SMS, etc.) get their real delivery
-outcome written back automatically — "sent" becomes "delivered" or "failed" —
-on a schedule, with no manual polling.
-
-An **action status updater (ASU)** is a scheduled reconciler:
-
-- a **poller tool** reads a delivery-log source (CloudWatch log group here;
-  LocalStack stands in locally),
-- the ASU runs on a `cron_expression`,
-- its `message_config` Liquid maps each log event back to the message it came
-  from (by `external_id`) and the new `status`,
-- `sender_tool_ids` scopes it to the messages a given sender tool produced.
-
-This is **global** — the same shape reconciles any sender's delivery status. See
-`action_status_updaters.md` for the wire reference and `tools.md` for the
-poller-tool body.
-
-# Walkthrough
-
-The `_setup/subscription.md` bootstrap left `api`, `tenantSlug`,
-`datalakeSlug`, and `ctx.datalakeId` populated.
-
-## 001 — register a data source for the tools
-
-Tools attach to a data source — the origin registration. Create one for the SMS
-gateway / log source.
-
-```typescript
-const { data: ds } = await api.dataSources.create(tenantSlug, datalakeSlug, {
-  name: `ASU Source ${runSuffix}`,
-  uri: 'sns.local',
-  description: 'SNS / CloudWatch origin for the dunning-SMS delivery reconciler.',
-  status: 'active',
-  is_default: false,
-})
-dataSourceId = ds.id!
-```
-
-## 002 — create the SMS sender tool
-
-The ASU reconciles the delivery status of messages a sender tool produced. Create
-an SNS-backed SMS tool (pointed at LocalStack locally) to be that sender.
-
-```typescript
-const { data: smsTool } = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `ASU SMS Sender ${runSuffix}`,
-  description: 'SNS-backed SMS sender whose delivery status the ASU reconciles.',
-  intent: 'sms',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  data_source_id: dataSourceId,
-  body: {
-    tool_body_type: 'sns',
-    auth_method: 'access_key',
-    region: 'us-east-1',
-    phone_number: '+15551234567',
-    endpoint_url: 'http://localhost:4566',
-    access_key_id: 'test',
-    secret_access_key: 'test',
-  },
-})
-ctx.smsToolId = smsTool.id!
-```
-
-## 003 — create the CloudWatch poller tool
-
-The poller tool supplies the credentials + region for reading the delivery log
-group. `intent: 'status_poller'` tags it as a reconciler source (not a sender),
-and `tool_body_type: 'cloud_watch_log_group'` selects the CloudWatch reader.
-
-```typescript
-const { data: cwTool } = await api.tools.create(tenantSlug, datalakeSlug, {
-  name: `ASU CloudWatch Poller ${runSuffix}`,
-  description: 'CloudWatch log-group poller — reads SNS delivery events for reconciliation.',
-  intent: 'status_poller',
-  status: 'active',
-  datalake_id: ctx.datalakeId,
-  data_source_id: dataSourceId,
-  body: {
-    tool_body_type: 'cloud_watch_log_group',
-    auth_method: 'access_key',
-    region: 'us-east-1',
-    endpoint_url: 'http://localhost:4566',
-    access_key_id: 'test',
-    secret_access_key: 'test',
-  },
-})
-ctx.cwToolId = cwTool.id!
-```
-
-## 004 — create the action status updater
-
-The ASU ties it together: a `cron_expression` schedule, the `updater_tool_id`
-(the poller), the `sender_tool_ids` it reconciles for, and an `updater_body`
-naming the log group + the time window. On `start_time`/`end_time`, use
-`now_msec` — the injected variable holding unix milliseconds — piped through
-`minutes_ago`; the bare `now` is a DateTime and raises here. The
-`message_config` Liquid is rendered ONCE PER EVENT, with the event itself as the
-assigns (there is no `events` list to loop), and emits a FLAT object: the
-`external_id` of the message to update plus the fields to set at the top level.
-`action_log_config` is REQUIRED alongside it — same per-event assigns, rendered
-into the action-log write shape: a JSON object with `external_id` plus at least
-one of `status` / `sent_at` / `metadata`. Omitting it is a 422 (`Missing field:
-action_log_config`).
-
-```typescript
-const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
-  name: `Dunning SMS Delivery Updater ${runSuffix}`,
-  cron_expression: '*/30 * * * *',
-  updater_type: 'cloud_watch',
-  updater_tool_id: ctx.cwToolId,
-  sender_tool_ids: [ctx.smsToolId],
-  datalake_id: ctx.datalakeId,
-  updater_body: {
-    updater_body_type: 'cloud_watch_request',
-    log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now_msec | minutes_ago: 45 }}',
-    end_time: '{{ now_msec }}',
-  },
-  message_config: {
-    type: 'custom',
-    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
-  },
-  action_log_config: {
-    type: 'custom',
-    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
-  },
-})
-actionStatusUpdaterId = asu.id!
-```
-
-## 005 — verify it persisted (read-back + checksum parity)
-
-`get` returns the stored row; its fields echo what you sent. `checksum` recomputes
-the fingerprint from the same body without persisting — it must equal the stored
-row's `checksum`, which is how drift is detected.
-
-```typescript
-const { data: row } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
-if (row.cron_expression !== '*/30 * * * *') {
-  throw new Error(`cron mismatch on read-back: ${row.cron_expression}`)
-}
-
-const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalakeSlug, {
-  name: row.name,
-  cron_expression: row.cron_expression,
-  updater_type: 'cloud_watch',
-  updater_tool_id: ctx.cwToolId,
-  sender_tool_ids: [ctx.smsToolId],
-  datalake_id: ctx.datalakeId,
-  updater_body: {
-    updater_body_type: 'cloud_watch_request',
-    log_group_name: 'sns/us-east-1/000000000000/DirectPublishToPhoneNumber',
-    start_time: '{{ now_msec | minutes_ago: 45 }}',
-    end_time: '{{ now_msec }}',
-  },
-  message_config: {
-    type: 'custom',
-    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
-  },
-  action_log_config: {
-    type: 'custom',
-    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
-  },
-})
-if (typeof ck.checksum !== 'string' || ck.checksum.length === 0) {
-  throw new Error('expected a checksum for the ASU body')
-}
-```
-
-## 006 — discover it (list + metadata)
-
-The ASU shows up in the paginated list, and `metadata` / `metadataDetails`
-return the markdown catalog an agent reads to understand what reconcilers exist.
-
-```typescript
-const { data: list } = await api.actionStatusUpdaters.list(tenantSlug, datalakeSlug)
-if (!(list.data ?? []).some((u) => u.id === actionStatusUpdaterId)) {
-  throw new Error('created ASU not found in the list')
-}
-
-const { data: catalog } = await api.actionStatusUpdaters.metadata(tenantSlug, datalakeSlug)
-if (typeof catalog !== 'string' || catalog.length === 0) {
-  throw new Error('expected a non-empty ASU metadata catalog')
-}
-
-const { data: detail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
-if (typeof detail !== 'string' || detail.length === 0) {
-  throw new Error('expected non-empty ASU metadata details')
-}
-```
-
-## 007 — write the integration test
-
-End the build with a test you keep: one block that re-reads the reconciler
-and asserts the facts the scenario depends on. This block runs live under
-`make validate-cookbook`.
-
-```typescript
-// Re-GET — the stored row echoes what was authored.
-const { data: asuRow } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, actionStatusUpdaterId)
-if (asuRow.cron_expression !== '*/30 * * * *') {
-  throw new Error(`cron mismatch on read-back: ${asuRow.cron_expression}`)
-}
-// last_run_* is the ONLY run surface (there is no per-run log). On a
-// fresh create it is legitimately null — assert the field EXISTS on the
-// wire, never a value.
-if (!('last_run_status' in asuRow)) {
-  throw new Error('ASU response carries no last_run_status field')
-}
-// Behavioural probe — the metadata surface an agent reads must render.
-const { data: asuDetail } = await api.actionStatusUpdaters.metadataDetails(tenantSlug, datalakeSlug, actionStatusUpdaterId)
-if (typeof asuDetail !== 'string' || asuDetail.length === 0) {
-  throw new Error('ASU metadataDetails came back empty')
-}
-```
-
-If the test fails in production, escalate with the failing read's
-evidence (the response body, `last_run_error`) — don't rewrite the config
-blind.
-
-# Gotchas
-
-- **The poller tool's intent is `status_poller`, not the sender's intent.** The
-  reconciler reads logs; it doesn't send. `sender_tool_ids` is the separate list
-  of sender tools whose messages it updates.
-- **`message_config` renders once per event, and emits a FLAT object.** The event
-  is the assigns — there is no `events` list to loop — and every top-level key
-  that is not `external_id` IS the update (`status`, `delivered_at`, …). There is
-  no `set_params` wrapper. Both mistakes are rejected at create.
-- **`action_log_config` is REQUIRED on both create and update (PUT), same as
-  `message_config`.** Omitting it is a 422 (`Missing field: action_log_config`).
-  It renders the same per-event assigns into the action-log write shape:
-  `external_id` plus at least one of `status` / `sent_at` / `metadata`.
-- **The schedule is a cron, evaluated platform-side — and one poll cycle can
-  be fired on demand.** Creating the ASU registers the schedule. The
-  `updater_body` window (`{{ now_msec | minutes_ago: 45 }}` … `{{ now_msec }}`)
-  bounds each run's log query, and must render to unix milliseconds — `now_msec`
-  is the unix-ms variable, not the bare `now` (a DateTime) or the ISO-8601 `now`
-  filter. To trigger a cycle without
-  waiting for the cron tick, `api.actionStatusUpdaters.refresh(tenantSlug,
-  datalakeSlug, id)` answers `202` with the updater row AS-IS (the poll runs
-  async — the row still shows the PREVIOUS run's stamps; re-read later for
-  the outcome). See `action_status_updaters.md` §7.
-- **If it doesn't reconcile, read `last_run_error` — refresh, don't guess.**
-  There is no per-run log (known limitation): the run surface is the
-  read-only `last_run_*` fields. Fire a `refresh`, re-read `last_run_status`
-  / `last_run_events_found` / `last_run_error`, and escalate with that
-  evidence — don't rewrite the config blind between cron ticks.
-- **`last_run_status` has three values — only `'ok'` means done.** `'ok'`
-  is the run that read its whole time window; `'partial'` completed but its
-  provider fetch was truncated, so the newest events may be missing and
-  `last_run_error` says so (it is not null on a `partial`); `'error'` failed.
-  Check `last_run_status === 'ok'` — a `!== 'error'` check silently accepts
-  a truncated `partial` as if it had reconciled.
-- **`checksum` parity is your drift signal.** The fingerprint of the desired body
-  must match the stored row's; a mismatch means the resource drifted.
-
-# See also
-
-- `action_status_updaters.md` — wire shape, `updater_body` variants, `message_config`
-- `tools.md` — `sns` sender body + `cloud_watch_log_group` poller body
-- `_setup/subscription.md` — the bootstrap this walk starts from
-- `integration-tests/tests/subscription/action-status-updaters.test.ts` —
-  the green test these calls are lifted from