@alvera-ai/platform-sdk 0.14.0 → 0.15.0-next.g09659bd

package/.agent/action_status_updaters.md

@@ -82,11 +82,50 @@ updater_body_type: 'cloud_watch_request'
 follow the same `<verb>_request` naming and carry the fields
 their target API requires.)
 
-`updater_body_type: 'restapi_request'` additionally **requires an
-`events_template` field**. Without it the REST poll fails with
-`missing_events_template`. `events_template` is specific to the REST
-poll's event-list extraction — it is not read by data-activation
-fetches.
+**Four poll-contract fields are required on EVERY updater type**, and
+they live at the **root of the create body** — not inside
+`updater_body`:
+
+```
+events_template                  REQUIRED embed  — { type, body } — event-list
+                                                   extraction; maps the provider's
+                                                   own id into `external_id`
+pagination_context_template      REQUIRED embed  — { type, body } — must render JSON
+                                                   carrying a boolean `has_next`
+events_output_schema             REQUIRED object — JSON Schema; FLOORED at an array
+                                                   whose items list `external_id`
+                                                   in `required`
+pagination_context_output_schema REQUIRED object — JSON Schema; FLOORED at an object
+                                                   listing `has_next` in `required`
+```
+
+**Mind the level.** These sit at the ASU root, deliberately — the
+`restapi_request` body embed is shared with the data-activation
+`tool_call`, and putting them there would force every DAC to supply
+them too. A `restapi_request` body carries its own `events_template`;
+that is a different field at a different level, and supplying it does
+**not** satisfy the root requirement.
+
+This was `restapi`-only while CloudWatch was a separate loop with no
+templates of its own. It is not one any more: every source now renders
+through `events_template` + `pagination_context_template` and
+terminates on the same `has_next`, so a `cloud_watch` updater declares
+the same contract a REST one does — the platform just ships the
+templates it normally points at. An older `cloud_watch` manifest that
+predates the change 422s on its next create.
+
+> ⚠ **The OpenAPI schema is behind the changeset on two of these.**
+> `events_output_schema` and `pagination_context_output_schema` are
+> generated **optional**, but `validate_expected_output_schemas/1`
+> requires them unconditionally. Omit them and the type-checker is
+> happy while the server returns 422. Treat all four as required until
+> the spec catches up.
+
+The floors exist for a reason. `external_id` is what the apply path
+pops off each rendered event to find the message and action-log rows to
+update — an events contract that does not demand it accepts a poll that
+fetches pages forever and reconciles nothing. `has_next` is the key the
+page loop ends on.
 
 `start_time` / `end_time` are Liquid, and they **must render to
 unix milliseconds** — that is what the poll request takes. Use the
@@ -117,6 +156,10 @@ scope — do not loop.
 {"external_id": "{{ notification.messageId }}", "status": "delivered"}
 ```
 
+> **Shape only — do not copy this mapping.** A hardcoded `"delivered"`
+> records every event as delivered, failures included. Real bodies
+> branch on the provider's status; see the SNS and MMS sections below.
+
 It must render a **flat** JSON object:
 
 ```
@@ -139,15 +182,107 @@ events for messages this updater doesn't own.
 Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
 available here, as everywhere.
 
-### MMS delivery tracking uses a system `message_config` template
+### SMS-over-SNS delivery tracking — two `custom` bodies
+
+The SNS SMS delivery receipt is **binary and single-shot**: one terminal
+outcome, `status` of `SUCCESS` or `FAILURE`. Its event shape is
+**disjoint from EUM's** — `status`, `notification.messageId`,
+`notification.timestamp`, `delivery.phoneCarrier`,
+`delivery.providerResponse` all sit at the root. Do not carry an EUM
+template over to SNS or vice versa.
+
+Two convenient consequences, both unlike MMS:
+
+- `delivered_at` is `notification.timestamp` — a UTC
+  `"YYYY-MM-DD HH:MM:SS.sss"` string Ecto casts directly, so **no date
+  filter is needed** (EUM needs `from_unix_ms` on its Unix-ms field).
+- the DLR **does** surface the US carrier as `delivery.phoneCarrier`.
+
+**`message_config`:**
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "{% if status == 'SUCCESS' %}delivered{% else %}failed{% endif %}", "status_description": "{{ delivery.providerResponse | json_escape }}"{% if status == 'SUCCESS' and notification.timestamp %}, "delivered_at": "{{ notification.timestamp }}"{% endif %}{% unless status == 'SUCCESS' %}, "failure_reason": "{{ status | json_escape }}"{% endunless %}{% if delivery.phoneCarrier and delivery.phoneCarrier != '' %}, "sms_carrier": "{{ delivery.phoneCarrier | json_escape }}"{% endif %}}
+```
+
+**`action_log_config`:**
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "{% if status == 'SUCCESS' %}delivered{% else %}failed{% endif %}", "status_description": "{{ delivery.providerResponse | json_escape }}"}
+```
+
+`status_description` is `delivery.providerResponse` verbatim on both
+sides — the carrier's own text, on success and failure alike. Because
+SNS's status is binary, `failure_reason` can only ever be `"FAILURE"`;
+the granular carrier text stays in `status_description`.
+
+**Note how the two SNS bodies differ from each other**: same status
+mapping, fewer emitted fields on the action log (no `delivered_at`,
+`sms_carrier`, or `failure_reason` — those are message concerns). That
+is a *different* reason from MMS's, where the two also disagree on the
+mapping itself. Both channels need two bodies; they need them for
+different reasons.
+
+### MMS delivery tracking needs TWO different templates — author both as `custom`
+
+MMS delivery tracking is a `cloud_watch` updater. Author **both**
+`message_config` and `action_log_config` as `custom` bodies — the two
+render *different* JSON from the same event, so one body cannot serve
+both. This is the single most-missed thing about updaters.
 
-MMS delivery tracking is wired as a `cloud_watch` updater whose
-`message_config` points at a system-defined template rather than a
-hand-authored `custom` body — the system template lives at
-`status_poller/end_user_messaging/mms_delivery_status`. Everything
-else about the updater is ordinary: it still needs an
-`action_log_config` like every other updater (see below) — the
-system template covers `message_config` only.
+**Why they differ.** A message's status vocabulary includes
+`customer_rejected`; an action log's does not. A recipient or carrier
+rejection (`SPAM` / `BLOCKED` / `CARRIER_BLOCKED`) is a message-level
+outcome — the action *did* deliver — so the action-log render must
+**NO-OP** on those events while the message render records
+`customer_rejected`. The message side also carries `delivered_at`,
+`failure_reason`, and `sms_carrier`; only `status` +
+`status_description` are ever applied to an action log.
+
+AWS End User Messaging (`sms-voice`) event fields: top-level
+`messageId`, `eventType` (`MEDIA_*`), `messageStatus`,
+`messageStatusDescription`, `eventTimestamp` (Unix ms), `isFinal`.
+
+**`message_config`** — map every status, emit the extra fields:
+
+```liquid
+{% case messageStatus %}
+{% when 'DELIVERED' %}{% assign mapped_status = 'delivered' %}
+{% when 'SUCCESSFUL' %}{% assign mapped_status = 'sent' %}
+{% when 'PENDING' %}{% assign mapped_status = 'sent' %}
+{% when 'QUEUED' %}{% assign mapped_status = 'queued' %}
+{% when 'SPAM' %}{% assign mapped_status = 'customer_rejected' %}
+{% when 'BLOCKED' %}{% assign mapped_status = 'customer_rejected' %}
+{% when 'CARRIER_BLOCKED' %}{% assign mapped_status = 'customer_rejected' %}
+{% else %}{% assign mapped_status = 'failed' %}
+{% endcase %}
+{"external_id": "{{ messageId }}", "status": "{{ mapped_status }}", "status_description": "{{ messageStatusDescription | json_escape }}"{% if messageStatus == 'DELIVERED' and eventTimestamp %}, "delivered_at": "{{ eventTimestamp | from_unix_ms }}"{% endif %}{% if mapped_status == 'failed' or mapped_status == 'customer_rejected' %}, "failure_reason": "{{ messageStatus | json_escape }}"{% endif %}{% if carrierName and carrierName != '' %}, "sms_carrier": "{{ carrierName | json_escape }}"{% endif %}}
+```
+
+**`action_log_config`** — the rejection statuses fall through to a
+bare `external_id`, which applies nothing:
+
+```liquid
+{% assign al_status = '' %}{% case messageStatus %}{% when 'DELIVERED' %}{% assign al_status = 'delivered' %}{% when 'SUCCESSFUL' %}{% assign al_status = 'sent' %}{% when 'PENDING' %}{% assign al_status = 'sent' %}{% when 'QUEUED' %}{% assign al_status = 'queued' %}{% when 'SPAM', 'BLOCKED', 'CARRIER_BLOCKED' %}{% else %}{% assign al_status = 'failed' %}{% endcase %}{"external_id": "{{ messageId }}"{% if al_status != '' %}, "status": "{{ al_status }}", "status_description": "{{ messageStatusDescription | json_escape }}"{% endif %}}
+```
+
+Note the `{% when 'SPAM', 'BLOCKED', 'CARRIER_BLOCKED' %}` arm is
+deliberately **empty** — it leaves `al_status` blank, so the render
+emits `external_id` alone and the action log is untouched.
+
+**Capture every event, not just the terminal one.** 2–3 events arrive
+per message — interim `MEDIA_QUEUED` / `MEDIA_PENDING` /
+`MEDIA_SUCCESSFUL` (`isFinal: false`), then one terminal event
+(`isFinal: true`), up to 72h late and out of order. Apply is
+idempotent and a monotonic guard only ever advances `status`, so a
+late or interim lower-rank event can never demote a message that
+already reached a higher state. Poll a window that overlaps
+deliberately; nothing is dropped.
+
+`queued_at` and `sent_at` are **your outbound pipeline's** times, set
+when the platform enqueues and dispatches — a delivery poll never
+overwrites them. Only `delivered_at` comes from the carrier event
+(`DELIVERED`'s own `eventTimestamp` via `from_unix_ms`), so
+re-polling a wide window does not drift it.
 
 ### Carrier information is available for SMS, not MMS
 
@@ -160,12 +295,15 @@ events — not something the platform chooses to drop:
   under `delivery.phoneCarrier` (e.g. `"T-mobile USA Inc."`, with
   numeric `mcc`/`mnc`). The SNS status template maps it to
   `sms_carrier`.
-- **MMS via AWS End User Messaging (`sms-voice`)** — the delivery
-  event has no carrier field. Verified on **both** a config-set
-  CloudWatch destination and the EventBridge path: the terminal
-  `MEDIA_DELIVERED` event exposes only `totalCarrierFee` (a cost),
-  never `carrierName`/`mcc`/`mnc`. So `sms_carrier` stays unset for
-  MMS.
+- **MMS via AWS End User Messaging (`sms-voice`)** — the event *can*
+  carry `carrierName`, but it is DLR-populated and comes back
+  **absent for US destinations** (the US DLR does not surface it),
+  unlike the SNS path's `phoneCarrier`, whose US DLR does. So map it
+  when present — `{% if carrierName and carrierName != '' %}` — and
+  expect `sms_carrier` to stay null for US long-code traffic.
+  Verified against real AWS delivery events: the terminal
+  `MEDIA_DELIVERED` event for a US destination exposes
+  `totalCarrierFee` (a cost) and no `carrierName`.
 
 AWS's Nov-2024 EventBridge-integration announcement states MMS
 delivery events carry carrier information in EventBridge, but the
@@ -291,8 +429,16 @@ datalake_id           required UUID
 updater_body          required embed  — { updater_body_type, ... }
 message_config        required embed  — { type, body }
 action_log_config     required embed  — { type, body } (required on create AND update)
+
+events_template                  required embed  — EVERY updater type, not just restapi
+pagination_context_template      required embed  — EVERY updater type
+events_output_schema             required object — JSON Schema
+pagination_context_output_schema required object — JSON Schema, floored at
+                                                   `has_next` in `required`
 ```
 
+The last four widened from `restapi`-only to universal — see §2.
+
 **Write-only (Request-only).** None.
 
 ## 4. Error envelopes
@@ -449,31 +595,49 @@ while (Date.now() < deadline) {
 // row.last_run_status / last_run_error now describe THIS run
 ```
 
-What the ASU still does NOT have is a **per-run log** (nothing like
-a data activation client's `logs` or a workflow's `batchLogs`). The
-run-outcome surface is four fields on the row itself, plus the halt
-flag:
+The ASU now **does** have a per-run log — the sibling of a data
+activation client's `logs` and a workflow's `batchLogs`. There are two
+run-outcome surfaces and they answer different questions:
+
+```
+actionStatusUpdaters.runLogs.list(tenantSlug, datalakeSlug, updaterId, query?)
+actionStatusUpdaters.runLogs.get(tenantSlug, datalakeSlug, updaterId, logId)
+```
+
+`.list` is Flop-paginated like every other list — same `page` /
+`page_size` / `filters` / `order_by` vocabulary (see `async.md`).
+
+**The summary surface — four fields on the updater row, plus the halt
+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 failed
 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:**
+**The per-run surface — one row per poll run, from `runLogs`:**
+
+```
+status                 'ok' | 'partial' | 'error'    ← the outcome of THIS page
+```
 
-- `'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.
+**`'partial'` lives on the run log, NOT on the updater — this is the
+trap.** A truncated fetch means the window was not fully read and the
+events it missed are the **newest** ones. The updater's own
+`last_run_status` cannot tell you that: it carries `'ok' | 'error'`
+only, so a truncated run reads as `'ok'` there. If completeness of
+reconciliation matters to you, read the run log — checking
+`last_run_status === 'ok'` on the updater is **not** sufficient, and a
+client that treats it as sufficient silently accepts an incomplete
+reconciliation.
+
+- `'ok'` — the page completed and read its whole slice of the window.
+- `'partial'` — the page completed but its provider fetch was
+  **truncated**. Only visible on the run-log row.
+- `'error'` — the run failed; `last_run_error` on the updater says why.
 
 `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/cookbook/action-status-updaters.md

@@ -130,6 +130,28 @@ const { data: asu } = await api.actionStatusUpdaters.create(tenantSlug, datalake
     start_time: '{{ now_msec | minutes_ago: 45 }}',
     end_time: '{{ now_msec }}',
   },
+  // The poll contract — REQUIRED on every updater type, and at the body ROOT,
+  // not inside `updater_body`. For an AWS poller, point at the templates the
+  // platform already ships rather than authoring Liquid: `events_template`
+  // projects each log event to `{ external_id, ... }`, and
+  // `pagination_context_template` renders the `has_next` the page loop ends on.
+  events_template: { type: 'system', path: 'status_poller/aws_sns/sms_events' },
+  pagination_context_template: {
+    type: 'system',
+    path: 'status_poller/aws_cloudwatch/pagination',
+  },
+  // The two floors. `external_id` is what the apply path pops off each rendered
+  // event to find the row it updates; `has_next` is what terminates paging.
+  // Demand more of your provider if you know it — you may not demand less.
+  events_output_schema: {
+    type: 'array',
+    items: { type: 'object', required: ['external_id'] },
+  },
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
@@ -167,6 +189,23 @@ const { data: ck } = await api.actionStatusUpdaters.checksum(tenantSlug, datalak
     start_time: '{{ now_msec | minutes_ago: 45 }}',
     end_time: '{{ now_msec }}',
   },
+  // Byte-identical to the create body above — the checksum is a fingerprint of
+  // the whole body, so omitting the poll contract here would compute a
+  // different one and read as drift on a resource that never changed.
+  events_template: { type: 'system', path: 'status_poller/aws_sns/sms_events' },
+  pagination_context_template: {
+    type: 'system',
+    path: 'status_poller/aws_cloudwatch/pagination',
+  },
+  events_output_schema: {
+    type: 'array',
+    items: { type: 'object', required: ['external_id'] },
+  },
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   message_config: {
     type: 'custom',
     body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',

package/.agent/cookbook/appointment-review-sms-workflow.md

@@ -356,6 +356,15 @@ const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug,
   tool_id: ctx.manualUploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [interopContractId, ctx.appointmentContractId],
 })
 dacId = dacResp.data.id!

package/.agent/cookbook/birthday-greeting-sms-trigger.md

@@ -175,7 +175,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       position: 0,
       trigger_template: TRIGGER_TEMPLATE,
       idempotency_template:
-        '{{ subject_id }}-{{ workflow_id }}-{{ action_id }}-{{ "" | uuid }}',
+        '{{ subject_id }}-{{ workflow_id }}-{{ action_id }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/forms/birthday-greeting',
       connected_app_metadata_template:
@@ -285,6 +285,15 @@ const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug,
   tool_id: ctx.manualUploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [interopContractId],
 })
 dacId = dacResp.data.id!

package/.agent/cookbook/bulk-ingest.md

@@ -113,6 +113,15 @@ const { data: dac } = await api.dataActivationClients.create(tenantSlug, datalak
   tool_id: ctx.manualUploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [interopContractId],
 })
 dacId = dac.id!

package/.agent/cookbook/contact-us-triage-with-llm.md

@@ -326,7 +326,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
     tool_id: toolId,
     position: 0,
     trigger_template: 'now',
-    idempotency_template: `{{ subject_id }}-{{ action_id }}-${bucket}-{{ "" | uuid }}`,
+    idempotency_template: `{{ subject_id }}-{{ action_id }}-${bucket}`,
     tool_call: {
       tool_call_type: 'sms_request',
       to: { type: 'custom', body: '+15551234567' },

package/.agent/cookbook/dunning-sms-for-delinquent.md

@@ -189,7 +189,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/pay',
       connected_app_metadata_template:
@@ -303,6 +303,15 @@ const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug,
   tool_id: ctx.manualUploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [interopContractId],
 })
 dacId = dacResp.data.id!

package/.agent/cookbook/kyc-notification-on-account-activation.md

@@ -188,7 +188,7 @@ const workflowResp = await api.workflows.create(tenantSlug, datalakeSlug, {
       decision_key: DECISION_KEY,
       position: 0,
       trigger_template: 'now',
-      idempotency_template: '{{ payment_account.id }}-{{ decision_key }}-{{ "" | uuid }}',
+      idempotency_template: '{{ payment_account.id }}-{{ decision_key }}',
       connected_app_id: connectedAppId,
       connected_app_route: '/portal/kyc',
       connected_app_metadata_template: '{"payment_account_id":"{{ payment_account.id }}"}',
@@ -300,6 +300,15 @@ const dacResp = await api.dataActivationClients.create(tenantSlug, datalakeSlug,
   tool_id: ctx.manualUploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [interopContractId],
 })
 dacId = dacResp.data.id!

package/.agent/cookbook/marketing-campaign-send.md

@@ -273,7 +273,7 @@ const ROSTER_MDM = `{% assign p = msg %}
   "legal_entity_type": "business",
   "business_name": "{{ p.business_name | json_escape }}",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.direct_customer_id | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ p.direct_customer_id | json_escape }}"}
   ]
 }`
 
@@ -304,6 +304,15 @@ const { data: rosterDac } = await api.dataActivationClients.create(tenantSlug, d
   tool_id: ctx.uploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [rosterLe.id!, rosterGt.id!],
 })
 ctx.rosterDacSlug = rosterDac.slug!
@@ -376,7 +385,7 @@ const AUDIENCE_MDM = `{% assign p = msg %}
   {% if first_name != "" %}"first_name": "{{ first_name | json_escape }}",{% endif %}
   {% if last_name != "" %}"last_name": "{{ last_name | json_escape }}",{% endif %}
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ handle | json_escape }}"}
   ]
 }`
 
@@ -406,6 +415,15 @@ const { data: audienceDac } = await api.dataActivationClients.create(tenantSlug,
   tool_id: ctx.uploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [audienceLe.id!, audienceGt.id!],
 })
 dacId = audienceDac.id!
@@ -844,7 +862,7 @@ const REPLY_MDM = `{% assign p = msg %}
 {
   "legal_entity_type": "individual",
   "identifiers": [
-    {"system": "{{ p.source_uri | json_escape }}", "value": "{{ p.handle | json_escape }}"}
+    {"system": "{{ p.source_uri | json_escape }}", "type": "digital_identifier", "value": "{{ p.handle | json_escape }}"}
   ]
 }`
 
@@ -864,6 +882,15 @@ const { data: replyDac } = await api.dataActivationClients.create(tenantSlug, da
   tool_id: ctx.uploadToolId,
   data_source_id: dataSourceId,
   tool_call: { tool_call_type: 'manual_upload' },
+  // REQUIRED on every DAC create, whatever the `tool_call` protocol. A
+  // manual_upload client is push-based — it never fetches and never pages —
+  // but the poll contract is declared uniformly, and `has_next` is the key
+  // the fetch loop would terminate on for a protocol that does page.
+  pagination_context_output_schema: {
+    type: 'object',
+    required: ['has_next'],
+    properties: { has_next: { type: 'boolean' } },
+  },
   interoperability_contract_ids: [replyGt.id!],
 })