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

package/.agent/account_management.md

@@ -102,6 +102,37 @@ app authenticates **tenant-scoped against exactly one tenant**,
 with that tenant's publishable key; connected apps in particular
 are single-tenant by construction (`connected_apps.md`).
 
+### Key-only clients — machine-to-machine on the publishable key
+
+`sessionToken` is optional on the client config. A deployed
+connected app that authenticates purely on its tenant's publishable
+key constructs with just the key — no session mint, no fabricated
+empty token:
+
+```typescript
+const api = createIsolatedPlatformApi({ baseUrl, apiKey })
+```
+
+Such a client sends `X-API-Key` and **no `Authorization` header**,
+and reaches exactly the `public_api` (publishable-key) allowlist —
+five calls:
+
+```
+   api.connectedApps.resolvePage             mint/read a delivered page
+   api.connectedApps.updateMessageTracking   opened_at / form_submitted_at
+   api.dataActivationClients.ingest          submit rows
+   api.dataActivationClients.ingestFile      submit a file
+   api.mdm.verify                            resolve an identity
+```
+
+(The same allowlist `connected_apps.md` documents — that guide owns
+the runtime-call details.) Every call outside these five returns
+401; that ceiling is the point, not an error to work around.
+Minting a session and passing `sessionToken` unlocks the full
+tenant-scoped API exactly as before — the two credentials are
+complementary (the key identifies the client; the Bearer
+authorizes), never substitutes.
+
 ### Explicit teardown — `revokeSession`
 
 The inverse of `createSession`. Revokes the current Bearer on

package/.agent/action_status_updaters.md

@@ -40,8 +40,8 @@ const { data: created } = await api.actionStatusUpdaters.create(
     updater_body: {
       updater_body_type: 'cloud_watch_request',
       log_group_name: 'sns/us-east-1/...',
-      start_time: '{{ now | minutes_ago: 45 }}',     // Liquid window
-      end_time:   '{{ now }}',
+      start_time: '{{ now_msec | minutes_ago: 45 }}', // Liquid window
+      end_time:   '{{ now_msec }}',
     },
 
     // Liquid, rendered ONCE PER EVENT — the event IS the assigns, so there is no
@@ -51,6 +51,14 @@ const { data: created } = await api.actionStatusUpdaters.create(
       type: 'custom',
       body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
     },
+
+    // REQUIRED on every updater, both types, on create AND update. Same
+    // per-event rendering contract as `message_config`, but targets the
+    // action_log row instead of the message row.
+    action_log_config: {
+      type: 'custom',
+      body: '{"external_id": "{{ notification.messageId }}", "status": "delivered"}',
+    },
   },
 )
 ```
@@ -74,22 +82,69 @@ updater_body_type: 'cloud_watch_request'
 follow the same `<verb>_request` naming and carry the fields
 their target API requires.)
 
+**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. On
-these two fields `now` is a **variable already holding unix ms**,
-so pipe it through the relative-time filters:
+unix milliseconds** — that is what the poll request takes. Use the
+**`now_msec`** variable (unix ms) and pipe it through the
+relative-time filters. **Not the bare `now`** — that is a DateTime,
+and feeding it a millisecond filter now raises at render:
 
 ```
-start_time: '{{ now | minutes_ago: 45 }}'    // 45 minutes back
-end_time:   '{{ now }}'                       // right now
+start_time: '{{ now_msec | minutes_ago: 45 }}'    // 45 minutes back
+end_time:   '{{ now_msec }}'                       // right now
 ```
 
 Also available: `hours_ago: N`.
 
-**Do not use the ISO-8601 `now` filter here.** `{{ "" | now }}` is
-a different thing — it renders a datetime *string*, which is not a
-valid window, and the platform rejects it at create. An ISO 8601
-literal is not valid on these fields either.
+**Do not use the bare `now` variable or the ISO-8601 `now` filter
+here.** The `now` variable is a DateTime and `{{ "" | now }}`
+renders a datetime *string* — neither is a valid unix-ms window,
+and the platform rejects both. An ISO 8601 literal is not valid on
+these fields either.
 
 ### `message_config.body` renders ONCE PER EVENT
 
@@ -101,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:
 
 ```
@@ -123,6 +182,174 @@ events for messages this updater doesn't own.
 Custom Liquid filters (`json_escape`, `e164`, `to_json`, ...) are
 available here, as everywhere.
 
+### 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.
+
+**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
+
+The recipient's mobile carrier is present on SMS delivery events but
+not MMS. This is AWS behavior — verified against real delivery
+events — not something the platform chooses to drop:
+
+- **SMS via Amazon SNS** — the delivery-status log
+  (`sns/<region>/<account>/DirectPublishToPhoneNumber`) nests carrier
+  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 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
+real events do not — a documented doc-vs-behavior discrepancy. For
+per-number US carrier, use `PhoneNumberValidate` (returns `Carrier` +
+`PhoneType`) at enrollment and join on destination/`messageId`; it is
+not in the delivery stream.
+
+### `action_log_config` is required — same rendering contract as `message_config`
+
+`action_log_config` is a **required** field on every action status
+updater — `cloud_watch` and `restapi` alike — on **both `create()` and
+`update()`**. There is no updater for which it is optional and no way
+to omit it on a PUT.
+
+It follows the same per-event rendering contract as `message_config`
+(§2 above), but targets the **action_log** row instead of the message
+row: it must render a JSON object containing `external_id` plus at
+least one updatable action-log field — one of `status`, `sent_at`, or
+`metadata`. A minimal valid value:
+
+```liquid
+{"external_id": "{{ notification.messageId }}", "status": "delivered"}
+```
+
+Two distinct rejections come off this field, and they read differently:
+
+- **Missing entirely** — omitting `action_log_config` on create or
+  update is a 422 with `Missing field: action_log_config` at
+  `source.pointer: /action_log_config`.
+- **Present but renders nothing** — a value that passes shallow
+  validation but renders `null` or an empty result at run time (e.g.
+  a `{"type": "null"}` config) is refused with a 422 whose detail
+  begins `must render a JSON object containing external_id`.
+
+**Response nullability is lazy, not retroactive.** Updaters created
+before this became required still read back `action_log_config: null`
+— the platform does not backfill a template onto old rows. That
+`null` persists until the row's **next edit** forces a real template
+through, and "next edit" is broader than a plain field change: it
+also includes resuming a halted updater by setting `status` back to
+`'active'` (§7) and issuing a `refresh()` call with a one-shot
+`updater_body` override (§7) — both now require `action_log_config`
+to be present too, which is what completes the migration for an old
+row.
+
 ### `cron_expression` is a standard 5-field cron string
 
 ```
@@ -201,8 +428,17 @@ sender_tool_ids       required UUID[] — tools whose messages this updater trac
 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
@@ -216,6 +452,8 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | `/sender_tool_ids/0`                | tool id doesn't exist or wrong datalake            |
 | `/updater_body/updater_body_type`   | value not in the polymorphic embed's type enum     |
 | `/message_config/body`              | empty when `type: 'custom'`                        |
+| `/action_log_config`                | missing entirely — `Missing field: action_log_config` (create AND update) |
+| (detail, not pointer)               | `action_log_config` present but renders `null`/empty — detail begins `must render a JSON object containing external_id` |
 | `/base`                             | `cron_management_failed` — body validated and saved but scheduler registration failed; the row is rolled back |
 
 ## 5. Lifecycle
@@ -318,7 +556,7 @@ check or retry for partial-delete states.
    The poll follows pages while `has_next` is true and stops on
    the first empty page.
 
-## 7. Manual trigger via `refresh` — but still no per-run log
+## 7. Manual trigger via `refresh` — 202, and what `last_run_*` means
 
 An action status updater CAN be fired on demand:
 
@@ -328,28 +566,103 @@ const { data } = await api.actionStatusUpdaters.refresh(
 );
 ```
 
-`refresh` runs one poll cycle synchronously and returns the updater
-row with its `last_run_*` fields freshly stamped. Apply jobs are
-asynchronous — observe delivery status on the message rows, not in
-this response. (CLI: `alvera refresh-updater <id>`.)
+**`refresh` answers `202` with the updater row AS-IS — the poll is
+ENQUEUED, not run.** The `last_run_*` fields on that response are the
+PREVIOUS run's stamps; reading them as the outcome of the refresh you
+just issued is the single most common mistake here. An optional body
+carries a one-shot `updater_body` override (e.g. a widened
+`start_time`/`end_time` window for a backfill) that does not mutate
+the persisted updater. Apply jobs are asynchronous too — observe
+delivery status on the message rows, not in this response.
+(CLI: `alvera refresh-action-status-updater --id <uuid>`, alias
+`refresh-updater`.)
 
-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
-only run-outcome surface is four fields on the row itself,
-describing the most recent poll only:
+The correct read is baseline-then-advance:
+
+```ts
+const before = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+const baseline = before.data.last_run_at ?? null      // BEFORE refreshing
+
+await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, updaterId)
+
+let row = before.data
+const deadline = Date.now() + 60_000
+while (Date.now() < deadline) {
+  await new Promise((r) => setTimeout(r, 2_000))
+  const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+  if (data.last_run_at && data.last_run_at !== baseline) { row = data; break }
+}
+// row.last_run_status / last_run_error now describe THIS run
+```
+
+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 completed a run
+last_run_at            when the poll worker last made progress
 last_run_status        'ok' | 'error'
-last_run_error         why the last run failed (structured text)
-last_run_events_found  how many events that run fetched
+last_run_error         why the last run failed
+last_run_events_found  events fetched so far in the current run
+status                 'active' | 'cycle_detected'
 ```
 
+**The per-run surface — one row per poll run, from `runLogs`:**
+
+```
+status                 'ok' | 'partial' | 'error'    ← the outcome of THIS page
+```
+
+**`'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
+legitimately show a smaller, in-progress figure than the final count.
+
+**`status` is the halt flag.** The server sets `'cycle_detected'` when
+a run re-reads events it has already handled — the runtime backstop for
+a poll whose pagination does not advance (a provider cursor that never
+drains, or a one-shot `updater_body` override). Every later job then
+fails without calling the provider, and `last_run_error` carries the
+diagnostic. **Nothing clears it but setting `status` back to
+`'active'`.** It is also the cheapest deterministic failure to assert
+on: a non-advancing config trips it within seconds, no provider
+credential rejection required. Related: a `restapi` updater that
+declares pagination but whose `path`/`params`/`body` never read
+`msg.pagination_context` or `msg.page` is now refused at create/update
+— see §2's template contract.
+
 **If a message's status is not reconciling, do this — in order:**
 
-1. Call `refresh()` and read `last_run_status` / `last_run_error`
-   off the response. They name the failing stage: window render,
-   source fetch, template render, or JSON parse.
+1. Call `refresh()`, wait for `last_run_at` to advance past the
+   baseline you captured, then read `last_run_status` /
+   `last_run_error` / `status`. They name the failing stage: window
+   render, source fetch, template render, JSON parse — or a halted
+   poll cycle.
 2. Check the config against §2 above. A config that violates the
    template contract is rejected at create, so a *deployed* updater's
    templates are structurally sound — the fault is more likely the

package/.agent/ai_sandbox.md

@@ -103,10 +103,12 @@ consumers cannot extend the set:
 
    minutes_ago   Unix ms N minutes before a unix-ms input. Bounds
                  the start of an ActionStatusUpdater poll window.
-                 Example:  {{ now | minutes_ago: 45 }}  →  1773585000000
+                 `now_msec` is the injected unix-ms variable (the
+                 bare `now` is a DateTime — feeding it here raises).
+                 Example:  {{ now_msec | minutes_ago: 45 }}  →  1773585000000
 
    hours_ago     Unix ms N hours before a unix-ms input.
-                 Example:  {{ now | hours_ago: 2 }}  →  1773578400000
+                 Example:  {{ now_msec | hours_ago: 2 }}  →  1773578400000
 
    uuid          Generate a new v4 UUID.
                  Example:  {{ '' | uuid }}  →  a1b2c3d4-…

package/.agent/connected_apps.md

@@ -64,7 +64,8 @@ const { data: created } = await api.connectedApps.create(
 )
 // created.id, created.slug         — server-derived
 // created.status                   === 'pending' (transient) → 'synced' after route fetch
-// created.api_key_id               — auto-provisioned M2M key id (see §2)
+// (an M2M key IS auto-provisioned at create (see §2), but its id is NOT
+//  echoed on the resource — no response carries an api_key_id field)
 // created.routes                   — array populated from .well-known/routes.json
 //                                     (empty until first sync)
 // created.last_synced_at           — set when routes successfully validated
@@ -191,9 +192,13 @@ last_synced_at    string — ISO 8601; set at successful route sync
 error             string — populated when status === 'error'
 routes            array  — discovered from .well-known/routes.json
                             (each: { name, path, description? })
-api_key_id        UUID   — id of the auto-provisioned M2M key
 ```
 
+(The auto-provisioned M2M key's id is **not** among these — neither
+`.get` nor `get-metadata` returns an `api_key_id`. Don't assert on it
+in a contract hook; the key itself reaches the deployment as
+`ALVERA_API_KEY`, §2.)
+
 **Caller-supplied (round-trip).**
 
 ```