@alvera-ai/platform-sdk 0.13.0 → 0.15.0

package/.agent/cookbook/welcome-sms-for-customers.md

@@ -182,7 +182,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       decision_key: DECISION_KEY,
       position: 0,
       trigger_template: 'now',
-      idempotency_template: '{{ customer_id }}-{{ decision_key }}-{{ "" | uuid }}',
+      idempotency_template: '{{ customer_id }}-{{ decision_key }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/portal/welcome',
       connected_app_metadata_template: '{"customer_id":"{{ mdm_output.customer.id }}"}',
@@ -520,6 +520,38 @@ if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
 }
 ```
 
+## 014 — write the integration test
+
+End the build with a test you keep: re-read the workflow and prove the
+pipeline still executes — without a side effect. `mode: 'dry_run'` with a
+never-matching selection runs the FULL pipeline (selection → filter →
+decision) and intercepts only the final action call, so no message
+leaves, yet the acknowledgement proves the workflow is runnable. This
+block runs live under `make validate-cookbook`.
+
+```typescript
+// Re-GET — the workflow must still be live, or nothing will run.
+const { data: wfRow } = await api.workflows.get(tenantSlug, datalakeSlug, workflowId)
+if (wfRow.status !== 'live') {
+  throw new Error(`workflow regressed from live: ${wfRow.status}`)
+}
+// Behavioural probe — a dry run against a selection no row can match:
+// the pipeline executes end-to-end, the final action call is
+// intercepted, and the acknowledgement carries the run-log id.
+const { data: probeRun } = await api.workflows.run(tenantSlug, datalakeSlug, ctx.workflowSlug, {
+  sql_where_clause: "ra.batch_id = 'test-never-matching-batch'",
+  mode: 'dry_run',
+  manual_override: false,
+})
+if (typeof probeRun.workflow_run_log_id !== 'string' || probeRun.workflow_run_log_id.length === 0) {
+  throw new Error('dry-run probe returned no workflow_run_log_id')
+}
+```
+
+If the probe fails in production, escalate with the run response as
+evidence — don't flip the workflow's status or rewrite its configs to
+chase the error.
+
 # Branches
 
 - **The no-phone customer is filtered, not failed** — §011

package/.agent/datalakes.md

@@ -240,7 +240,7 @@ a hostname pattern; values like `"invalid_host!"` (with
 non-hostname punctuation) are rejected.
 
 This is the only field-format constraint surfaced before the
-synchronous reachability probe runs (see §6 Gotcha 9) — a
+synchronous reachability probe runs (see §8 Gotcha 9) — a
 malformed identifier never gets as far as a connection attempt.
 
 ### Schema names must be unique within a database
@@ -576,7 +576,7 @@ agent-facing markdown, or the whole-domain catalog can be fetched
 in one shot via `api.datasets.metadata(tenantSlug, datalakeSlug)`. Pair `.systemDatasets()` with a
 `page_size: 1` probe per name as a post-migration smoke (proves
 each industry-built table is queryable; the post-ready probe
-code is in §6 Gotcha 3).
+code is in §8 Gotcha 3).
 
 ```typescript
 const { data: catalog } = await api.datalakes.systemDatasets(
@@ -641,7 +641,48 @@ const { data: csv } = await api.datalakes.executeSql(
 ) // csv is a string, not the JSON envelope
 ```
 
-## 6. Gotchas
+## 6. Logical name → physical table
+
+The name you author is not the name you query. Datasets are addressed
+**logically** everywhere in a manifest or SDK call, and **physically** in SQL:
+
+| You author | You query in SQL | Schema |
+|---|---|---|
+| `message` | `regulated_messages` | `app_regulated` |
+| `action_log` | `action_logs` | `app_unregulated` |
+| a generic table `clients` | `regulated_alvera_custom_clients` | `app_regulated` |
+
+Custom (generic) tables carry an `alvera_custom_` prefix, and the regulated side
+adds a further `regulated_` prefix on top. The schema follows `execute-sql`'s
+`--mode` (`regulated` → `app_regulated`, `unregulated` → `app_unregulated`).
+
+**Don't derive these by hand — read them.** Guessing column and table names is
+how six turns get spent on `column "error_message" does not exist` (the real
+column is `failure_reason`):
+
+- `alvera get-metadata dataset --only <type>` prints the **physical dataset
+  name** plus every column, from the Ecto struct itself.
+- `alvera get-metadata generic-table --only <slug>` prints the exact **primary
+  table alias** to use in a `WHERE` clause, with a worked `SELECT`.
+
+An `execute-sql` failure on an undefined column, relation, table, or schema now
+names these verbs in its error, so the correction path is one command away.
+
+## 7. The roster owns the dedupe uri — don't inject it per source
+
+MDM matches on the full identification triple, so a `source_uri` injected
+per data source participates in matching. Two sources describing the same
+subject then produce two different triples, and the same subject is written
+**twice** instead of being reconciled onto one entity.
+
+Derive the dedupe uri **once, at the roster**, and let every data source inherit
+it. Never compute a per-source `source_uri` and expect MDM to see through it.
+
+This divergence is **not visible through `get-metadata`**: the roster value and
+the per-source values each look well-formed in isolation, and only the duplicate
+rows downstream reveal the mismatch. Check the derivation, not the metadata.
+
+## 8. Gotchas
 
 1. **`create()` does NOT auto-enqueue migration.** The create response
    returns immediately with `status: 'new'`; Datalake-DB-resident
@@ -780,3 +821,27 @@ const { data: csv } = await api.datalakes.executeSql(
     `meta.columns[i]`); never assume `row.someColumn`. The `?format=csv`
     branch returns a CSV **string** with no `meta` envelope — for the
     structural metadata, use the JSON call.
+
+14. **On a FRESH create, never query the lake before `migrate` has
+    run.** The schema does not exist between `create()` and a completed
+    migration, so any check that queries the lake in that window fails
+    with `relation "…" does not exist` — and if that failing check
+    *halts your provisioning flow* (a CLI contract hook's
+    `afterCreateOrUpdate` runs exactly there), the halt lands BEFORE
+    migrate ever fires. The lake is then created-but-unmigrated, and a
+    reconcile-style flow reads it `unchanged` forever after —
+    unrecoverable without a manual migrate. Sequence query-the-lake
+    checks strictly after migrate + `ready` (in a CLI contract, that
+    means `afterMigrate`/`assertReady`, never `afterCreateOrUpdate`);
+    the create-then-migrate window is for platform-DB work only (§5's
+    storage-location split).
+
+15. **A pooled reader endpoint can serve a stale schema on a
+    just-migrated lake.** If a reader profile points at a connection
+    pooler (e.g. Neon's `-pooler` host), a per-datalake DB session
+    started against the unmigrated schema can keep resolving the old,
+    empty `search_path` even after the migration lands — writes then
+    fail with `undefined_table` while `executeSql` reads the same table
+    fine. Prefer the direct (non-pooler) endpoint for the writer
+    profiles; if ingest 202s but nothing lands on a fresh lake, this is
+    the first thing to check. (Platform tracking: platform#784.)

package/.agent/interoperability_contracts.md

@@ -236,6 +236,35 @@ match the consumer's expectations. If `filter_result === 'skip'`
 (`stage === 'filtered'`), the row was filtered out before rendering
 — useful for verifying the filter semantics on a known-skip example.
 
+#### `.run` takes your payload VERBATIM — the pipeline adds two fields
+
+The sandbox renders exactly what you send it. A real ingest does
+not: before the templates see a row, the pipeline injects two
+fields the sandbox has no way to know.
+
+```
+source_uri   the URI of the DATA SOURCE behind the bound data
+             activation client — not anything in the row. A datalake's
+             default manual-upload data source is created with
+             `<datalake_id>.alvera.ai`, so that is what a row ingested
+             through it carries.
+timezone     the datalake's timezone
+```
+
+Neither is bound during `.run` — there is no client in scope — so
+`{{ p.source_uri }}` renders whatever your sample row happens to
+carry (commonly nothing, or a placeholder like `test://crm/clients`).
+Both templates are faithful; the INPUT differs.
+
+The consequence bites when the identification `uri` is derived from
+`source_uri`: MDM stores the rendered `uri` verbatim, so the sandbox
+shows your placeholder and the persisted
+`legal_entity_identifications` row shows `<datalake_id>.alvera.ai`.
+**Do not assert on a `uri` that comes from `source_uri` in `.run`
+output** — assert on `id_type` / `id_number`, which are row-derived
+and survive persistence unchanged. To verify the client-derived
+half, ingest through the DAC and query the persisted row.
+
 ### Generic-table contracts: auto-created identity contracts
 
 When you create a generic table (see `generic_tables.md`), the

package/.agent/tool-call-configs.md

@@ -17,6 +17,7 @@ Fetches data via REST API with pagination support.
 - **body** (TemplateConfig, nullable) — Request body, rendered as Liquid template
 - **params** (TemplateConfig, nullable) — Query parameters, rendered as Liquid template
 - **pagination_context_template** (TemplateConfig) — Pagination control template, must render to JSON with `has_next` boolean field
+- **events_template** (TemplateConfig, nullable) — Extracts the raw event array from a response page; required when this config drives an action status updater REST poll (the poll fails with `missing_events_template` otherwise), unused by data-activation fetches
 
 <!-- alvera:section kind="tool-call-config" atom="sql_query" module="Platform.Tools.ToolCallConfig.SQLQuery" -->
 
@@ -79,6 +80,16 @@ Sends an SMS message via the configured SMS provider.
 - **body** (TemplateConfig) — Message body, rendered as Liquid template
 - **sms_type** (enum: transactional, promotional) — Message classification; defaults to `transactional`
 
+<!-- alvera:section kind="tool-call-config" atom="mms_request" module="Platform.Tools.ToolCallConfig.MMSRequest" -->
+
+## Tool Call Configuration (mms_request)
+
+Sends an MMS (media message) via AWS End User Messaging.
+
+- **to** (TemplateConfig) — Recipient phone number in E.164 format, rendered as Liquid template
+- **body** (TemplateConfig) — Message body (caption), rendered as Liquid template
+- **media_url** (string) — Public http(s) URL of the media to attach; verified reachable (GET 2xx + image/*) at authoring, fetched and re-staged into the tool's S3 media bucket at send
+
 <!-- alvera:section kind="tool-call-config" atom="email_request" module="Platform.Tools.ToolCallConfig.EmailRequest" -->
 
 ## Tool Call Configuration (email_request)

package/.agent/tools.md

@@ -36,6 +36,7 @@ Intent enum (typed):
 
    ToolIntent.DATA_EXCHANGE   // fetch / push payloads
    ToolIntent.SMS             // outbound text messages
+   ToolIntent.MMS             // outbound MMS (media) messages
    ToolIntent.EMAIL           // outbound email
    ToolIntent.VOICE           // outbound voice / voicemail
    ToolIntent.EXPORT          // report / extract generation
@@ -53,11 +54,11 @@ Intent enum (typed):
                               //  with AI agents (see ai_agents.md).
 ```
 
-`ToolIntent` has exactly these seven members — the wire values are
-`sms`, `email`, `export`, `voice`, `data_exchange`, `status_poller`,
-`llm_enrichment` (`Ecto.Enum` in `platform/lib/platform/tools/tool.ex`
-line 236; `enum ToolIntent` in
-`packages/sdk/src/generated/types.gen.ts` line 863). There is no
+`ToolIntent` has exactly these eight members — the wire values are
+`sms`, `mms`, `email`, `export`, `voice`, `data_exchange`,
+`status_poller`, `llm_enrichment` (`Ecto.Enum` in
+`platform/lib/platform/tools/tool.ex` line 241; `enum ToolIntent` in
+`packages/sdk/src/generated/types.gen.ts` line 881). There is no
 `chat_completion` or `context_extraction` intent.
 
 Polymorphic body dispatch — the `body.tool_body_type` field is
@@ -73,6 +74,10 @@ the discriminator. Each branch is its own TypeScript type:
    tool_body_type = 'rest_api'       →  generic REST endpoint
    tool_body_type = 'sns'            →  AWS SNS topic (used for
                                         SMS / push notifications)
+   tool_body_type = 'end_user_messaging'
+                                     →  AWS End User Messaging (used
+                                        for MMS / media messages via
+                                        the SendMediaMessage API)
    tool_body_type = 'sharepoint'     →  Microsoft Graph SharePoint
    tool_body_type = 'aws_lambda'     →  invoke a Lambda function
    tool_body_type = 'sqs'            →  AWS SQS queue
@@ -95,9 +100,9 @@ discriminator is a string-literal on each branch of the generated
 Consult the branch literals in
 `packages/sdk/src/generated/types.gen.ts` for the complete set,
 since new body types land independently of doc revisions. The
-platform declares the same eleven variants in
+platform declares the same twelve variants in
 `platform/lib/platform/tools/tool.ex` (`polymorphic_embeds_one(:body,
-…)`, lines 250–266).
+…)`, lines 255–269).
 
 ## 2. Rules the type cannot encode
 
@@ -111,6 +116,7 @@ create time:
    data_exchange  →  s3, sftp, sql_database, rest_api,
                      manual_upload, aws_lambda, sharepoint, sqs
    sms            →  sns, rest_api (provider-specific)
+   mms            →  end_user_messaging
    email          →  email (dedicated body), rest_api,
                      aws_lambda (custom dispatchers)
    voice          →  rest_api (Twilio Voice, etc.)
@@ -148,6 +154,21 @@ Each branch has its own required-list. Common patterns:
                                 + optional endpoint_url)
                             OR (iam_role)
 
+   end_user_messaging body  region, auth_method (same three-way
+                              access_key / iam_role / assume_role
+                              shape as sns — gotcha 3), phone_number
+                              (E.164 origination number), media_bucket,
+                              configuration_set_name, plus EITHER
+                              (access_key_id + secret_access_key)
+                            OR (iam_role)
+                            OR (assume_role_arn +
+                                assume_role_external_id);
+                              optional endpoint_url (overrides the End
+                              User Messaging API endpoint) and
+                              media_endpoint_url (overrides the S3
+                              media-staging endpoint; blank ⇒ S3
+                              derived from the tool's region)
+
    sql_database body        db_type, db_host, db_port, db_name,
                               auth_method, db_username,
                               db_password (or iam_role)
@@ -383,7 +404,7 @@ Common rejections:
    ─────────────────────────────                 ─────────────────────────────
    "is invalid" on intent                         value not in ToolIntent enum
    "is invalid" on tool_body_type                 value not one of the
-                                                    eleven body-branch
+                                                    twelve body-branch
                                                     discriminator literals
    "is invalid" on body                           intent ↔ body_type pairing
                                                     rejected at platform level
@@ -430,22 +451,32 @@ await api.tools.testInvocation(
 inlines the value verbatim; `type: 'system'` references a
 platform-shipped template (see `templates.md`).
 
-**Test-invocation accepts exactly FOUR `tool_call_type` variants** —
+**Test-invocation accepts exactly FIVE `tool_call_type` variants** —
 the interactive ones. Its request casts into a `ManualToolInvocation`
 embed (`on_type_not_found: :raise`) whose polymorphic set is
-`sms_request`, `email_request`, `restapi_request`,
+`sms_request`, `mms_request`, `email_request`, `restapi_request`,
 `aws_lambda_request`. A tool whose body is SFTP / S3 / SQL /
 SharePoint has **no** test-invocation variant and cannot be exercised
 through this endpoint (same shape as the `status_poller` case below).
 Those config shapes still exist — but on the broader **workflow-action
 `ToolCallConfig`** surface (see `tool-call-configs.md`), not here. The
-per-branch required-list for the four test-invocable variants:
+per-branch required-list for the five test-invocable variants:
 
 ```
    tool_call_type: 'sms_request'
      required:   to, body, sms_type
      enums:      sms_type ∈ { 'transactional' (default), 'promotional' }
 
+   tool_call_type: 'mms_request'
+     required:   to, body, media_url
+     notes:      body is the message caption; media_url is a PLAIN
+                 STRING — a public http(s) URL, no Liquid. The server
+                 verifies it at authoring (GET must answer 2xx with an
+                 image/* content-type; malformed/non-http 422s without
+                 fetching), then re-stages it into the tool's
+                 media_bucket before send — targets a tool whose body
+                 is end_user_messaging
+
    tool_call_type: 'email_request'
      required:   to, subject, body
      embeds:     TemplateConfig variants accepted on each ({ type:
@@ -472,10 +503,10 @@ the workflow-action `ToolCallConfig` catalog in `tool-call-configs.md`;
 they are **not** part of test-invocation.
 
 Liquid template bodies (`query`, `payload`, body/params on
-`restapi_request`, `sms_request` body, `email_request` body) are
-parsed at create time — invalid Liquid syntax surfaces as a field
-rejection on the corresponding TemplateConfig path, not on the
-outer request.
+`restapi_request`, `sms_request` body, `mms_request` body,
+`email_request` body) are parsed at create time — invalid Liquid
+syntax surfaces as a field rejection on the corresponding
+TemplateConfig path, not on the outer request.
 
 The response shape:
 
@@ -495,27 +526,63 @@ Only platform-internal failures (DB unreachable, etc.) produce
 5xx. Treat 5xx as infra noise; treat `200 + status:"error"` as a
 real (and handleable) configuration problem.
 
-### `status_poller` tools cannot be test-invoked — the proof seam is the ASU
-
-The `tool_call_type` set above is closed, and it carries **no
-variant** for a `status_poller`-intent tool (`cloud_watch_log_group`
-or a poller-side `rest_api`) — a poller tool cannot be exercised
-standalone. Its run surface is the **action status updater that
-fetches through it**: after the ASU's cron fires, read the ASU's
-read-only `last_run_at` / `last_run_status` / `last_run_error` /
-`last_run_events_found` fields (they are excluded from the drift
-checksum, so a poll never reads as config drift) and the `Last run`
-section of the ASU's AI metadata. A failed poll lands its
-structured reason in `last_run_error`.
-
-There is **no manual trigger and no per-run log** for an ASU —
-unlike a data activation client (run-manually + `/logs`) or a
-workflow (execute + workflow-logs) — so `last_run_*` is the ONLY
-run surface; see `action_status_updaters.md` §7 (KNOWN
-LIMITATION). A born-red contract for a poller tool should assert
-the tool's own create/config truths and prove the polling
-behaviour on the owning ASU's `last_run_*`, not chase a
-test-invocation variant that doesn't exist.
+### Proving a `status_poller` tool — it depends on the BODY, not the intent
+
+Invocability is keyed on the tool's **body type**, not its intent.
+`restapi_request` is the call type for ANY intent with a `rest_api`
+body, so a `status_poller` with a `rest_api` body — the shape a
+provider events-API poller takes — **can** be test-invoked, and
+that is the cheapest way to prove its credentials:
+
+```typescript
+await api.tools.testInvocation(tenantSlug, datalakeSlug, pollerId, {
+  tool_call: {
+    tool_call_type: 'restapi_request',
+    method: 'get',
+    path: { type: 'custom', body: '/v3/YOUR-DOMAIN/events' },
+    params: { type: 'custom', body: '{"limit": 1}' },   // keep it read-only
+  },
+})
+```
+
+A `cloud_watch_log_group` body is the one that has no call type —
+nothing in the closed `tool_call_type` set fits it. **That** poller's
+run surface is the action status updater that fetches through it:
+its `last_run_at` / `last_run_status` / `last_run_error` /
+`last_run_events_found` fields (excluded from the drift checksum, so
+a poll never reads as config drift) plus the `Last run` section of
+the ASU's AI metadata. A failed poll lands its structured reason in
+`last_run_error`.
+
+You do **not** have to wait for the cron. `actionStatusUpdaters.refresh`
+fires one poll cycle on demand (CLI: `alvera refresh-action-status-updater
+--id <uuid>`), and reading `last_run_*` correctly is what makes it
+usable as a proof — three things to get right:
+
+- **`refresh` answers `202` with the updater row AS-IS.** The poll runs
+  asynchronously, so the response carries the PREVIOUS run's stamps.
+  Capture `last_run_at` as a baseline BEFORE calling it, then poll the
+  row until `last_run_at` advances past that baseline.
+- **`last_run_status` has three values.** `'ok'` means the run completed
+  and read its whole time window; `'partial'` means the provider fetch was
+  truncated, so the newest events may be missing and `last_run_error`
+  carries the detail; `'error'` means the run failed. Only
+  `last_run_status === 'ok'` proves a complete reconciliation — a
+  `!== 'error'` check silently accepts a truncated `partial`.
+  `last_run_events_found` counts the current run's events, and because
+  `refresh` is async an early read can show an in-progress figure.
+- **`status` is the halt flag.** It is `'active'` normally and the
+  server sets `'cycle_detected'` when a run re-reads events it has
+  already handled — every later job then fails without calling the
+  provider, and only setting it back to `'active'` resumes polling. It
+  is also the fastest deterministic failure to assert on: a
+  non-advancing pagination config trips it within seconds, no provider
+  credential rejection required.
+
+See `action_status_updaters.md` §7 for the full refresh + `last_run_*`
+contract. A born-red contract for a CloudWatch poller should assert the
+tool's own config truths and prove the polling behaviour through the
+owning ASU on those terms.
 
 ### Update
 

package/.agent/type_naming.md

@@ -105,6 +105,10 @@ await api.tools.get(tenantSlug, datalakeSlug, toolId)
 // 2b. downstream resources reference the tool by id
 await api.actionStatusUpdaters.create(tenantSlug, datalakeSlug, {
   updater_tool_id: toolId,
+  action_log_config: {
+    type: 'custom',
+    body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+  },
   // …
 })
 ```