@alvera-ai/platform-sdk 0.21.2 → 0.21.3-next.g393d024

package/.agent/AGENTS.md

@@ -320,8 +320,8 @@ forms are the SQL table names used by `executeSql`):
 
 `.agent/cookbook/<slug>.md` files are pure-markdown scenario
 stories — one business outcome each, told as a numbered API-call
-sequence drawn from a green end-to-end vitest scenario in the
-platform's integration-tests suite. Agents read these directly
+sequence that the cookbook validator runs, step by step, against a
+live platform. Agents read these directly
 from the filesystem at
 `node_modules/@alvera-ai/platform-sdk/.agent/cookbook/`; there
 is no SDK function and no CLI verb that returns cookbook bytes
@@ -333,24 +333,21 @@ cookbook that is missing one, repeats one, reorders them, leaves one
 empty, or adds a top-level section that is not on this list:
 
 - **Front matter** — `title`, `summary`, `use_case`, `slug`,
-  `vitest_source` (list of integration-test files the snippets
-  are lifted from, anchor file first), `status`. `use_case` is one
+  `status`. `use_case` is one
   of the four surfaces — `organic-marketing`,
   `subscription-saas`, `payments-compliance`,
   `primary-care-feedback` — and there is exactly one cookbook per use
   case. Three are at `cookbook/<use-case>.md`; the fourth is at
-  `cookbook/primary-care.md`, because `use_case` tracks the integration
-  suite it is lifted from (`integration-tests/tests/primary-care-feedback/`)
-  and the filename does not. Read `use_case` from the front matter rather
-  than deriving it from the filename.
+  `cookbook/primary-care.md`, because `use_case` keeps the use case's
+  full name and the filename does not. Read `use_case` from the front
+  matter rather than deriving it from the filename.
 - **Problem** — the business-outcome statement in domain terms,
-  sourced from the anchor vitest's behaviour (not from
+  sourced from what the walk's steps actually do (not from
   customer-narrative documentation).
 - **Composition** — table of resources provisioned, mapped to
   the audience skill that owns each (setup / build / compose).
 - **Walkthrough** — numbered `## NNN — <step>` subsections, each
-  carrying one fenced TypeScript block lifted from the anchor or
-  ancillary vitest. State threads forward across subsections via
+  carrying one fenced TypeScript block. State threads forward across subsections via
   plain JavaScript variables in the validator's generated
   `describe` closure. A numbered step anywhere else in the file
   is refused.
@@ -363,8 +360,7 @@ empty, or adds a top-level section that is not on this list:
   step the cookbook does not have — and every step runs against a
   live platform — so a gotcha cannot outlive the behaviour it warns
   about.
-- **See also** — links to relevant per-resource reference MDs
-  and to the anchor + ancillary vitest files.
+- **See also** — links to relevant per-resource reference MDs.
 
 ### Every cookbook is self-reliant, and repeats what it needs
 
@@ -403,17 +399,14 @@ map inbound rows into the platform's upsert shapes. Inlining
 those templates verbatim inside every cookbook markdown
 bloats each recipe to several hundred lines of Liquid noise
 that obscures the cookbook's lesson. The corpus ships them
-as **vendored fixtures** instead — same pattern the platform
-repo's own integration tests use.
+as **vendored fixtures** instead.
 
 - Fixtures live under
   `.agent/cookbook/_fixtures/<industry>/`. The leading
   underscore marks the directory as fragment infrastructure
   (not a cookbook); the validator's discovery walk skips it.
   Each `<industry>/` subdirectory carries a `README.md`
-  listing every template + which cookbook consumes it + the
-  production source-of-truth path it was vendored from
-  (`platform/priv/liquid_templates/…`).
+  listing every template and which cookbook consumes it.
 - Cookbook code loads fixtures via the
   `COOKBOOK_FIXTURES_DIR` environment variable:
   ```typescript

package/.agent/action_logs.md

@@ -113,8 +113,8 @@ also merges each finished batch into NDJSON artifacts in cold
 storage:
 
 ```
-   <datalake>/workflows/<wf_slug>/<batch_id>/merged.ndjson              (per-subject)
-   <datalake>/workflows/<wf_slug>/<batch_id>/<decision_key>/merged.ndjson  (per-action payloads)
+   <datalake>/workflows/<wf_slug>/merged/<batch_id>.ndjson                 (per-subject)
+   <datalake>/workflows/<wf_slug>/merged/<batch_id>/<decision_key>.ndjson  (per-action payloads)
 ```
 
 The batch log row (`api.workflows.batchLogs.get`) carries the

package/.agent/action_status_updaters.md

@@ -409,6 +409,10 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 | (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 |
 
+`refresh()` has two refusals of its own, both **409** with an empty
+`source.pointer`: the updater is halted, or a poll for it is already
+queued or running. Neither queues anything. See §7.
+
 ## 5. Lifecycle
 
 ### Create
@@ -509,7 +513,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` — 202, and what `last_run_*` means
+## 7. Manual trigger via `refresh` — 202 or 409, and what `last_run_*` means
 
 An action status updater CAN be fired on demand:
 
@@ -548,16 +552,67 @@ while (Date.now() < deadline) {
 // row.last_run_status / last_run_error now describe THIS run
 ```
 
+### When `refresh` answers 409, nothing was queued
+
+`refresh` refuses with **409 Conflict** in two cases. The body is the
+standard `errors[]` envelope (`errors.md`), thrown with
+`_httpStatus === 409`. Either way **no poll is queued**, and a one-shot
+`updater_body` override sent with that call is not queued either, so
+resend it on the retry.
+
+| Case | `detail` | What clears it |
+|------|----------|----------------|
+| **Halted**: `status` is not `'active'` | `Updater is halted: status is <status>. Set status to active to resume polling.`, followed by ` Last run error: <text>` when one is recorded | Fix the cause, then `update()` with `status: 'active'` (below). Retrying `refresh` changes nothing. |
+| **A poll is already queued or running**: a cron tick's, an earlier refresh's, or a later page of a run under way | `A poll for this updater is already queued, so this refresh was not. Retry once it finishes.` | Wait for that poll to finish (`last_run_at` advances), then call `refresh` again. |
+
+Both carry `title: "Conflict"` and an empty `source.pointer`, so
+`title` cannot tell them apart. Read the row instead: the halt is
+checked first, so `status !== 'active'` means halted and anything else
+means a poll is in flight.
+
+```typescript
+async function refreshOrExplain(updaterId: string): Promise<void> {
+  try {
+    await api.actionStatusUpdaters.refresh(tenantSlug, datalakeSlug, updaterId)
+  } catch (err) {
+    if ((err as { _httpStatus?: number })._httpStatus !== 409) throw err
+    const { data } = await api.actionStatusUpdaters.get(tenantSlug, datalakeSlug, updaterId)
+    if (data.status !== 'active') {
+      // Halted. Fix the cause, then update() with status: 'active'.
+      throw new Error(`updater halted (${data.status}): ${data.last_run_error ?? 'no run error recorded'}`)
+    }
+    // A poll is already queued or running. Wait for last_run_at to
+    // advance past data.last_run_at, then call refresh again.
+  }
+}
+```
+
+### One run at a time per updater
+
+A run reads every page of its window before it ends. A cron tick that
+finds an earlier run of the same updater still going does not start a
+second run beside it: it **skips**, and records when in
+`last_skipped_at`. A skip is not a run, so it leaves `last_run_at`,
+`last_run_status`, `last_run_error` and `last_run_events_found` alone.
+The same rule is why `refresh` answers 409 while a poll is queued or
+running.
+
+`last_skipped_at` is `null` until a tick has skipped. A recent one
+means a run outlasted a cron interval. If skips keep recurring, runs
+take longer than the interval: lengthen `cron_expression` or narrow
+the poll window.
+
 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:
+run-outcome surface is four fields on the row itself, plus the skip
+stamp and the halt flag:
 
 ```
 last_run_at            when the poll worker last made progress
 last_run_status        'ok' | 'error'
 last_run_error         why the last run stopped; null when it read its whole window
 last_run_events_found  events fetched so far in the current run
+last_skipped_at        when a cron tick last skipped because a run was still going; null if none has
 status                 'active' | 'cycle_detected'
 ```
 
@@ -584,7 +639,8 @@ 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
+`'active'`.** While it is halted, `refresh` answers 409 and queues
+nothing (above). 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
@@ -593,8 +649,9 @@ declares pagination but whose `path`/`params`/`body` never read
 
 **If a message's status is not reconciling, do this — in order:**
 
-1. Call `refresh()`, wait for `last_run_at` to advance past the
-   baseline you captured, then read `last_run_status` /
+1. Call `refresh()`. A 409 says why nothing was queued: halted, or
+   a poll already in flight (above). Otherwise 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.

package/.agent/async.md

@@ -99,10 +99,10 @@ retry should:
    that names the uniqueness key (usually `/name` or `/slug`).
 3. Treat as "already created" and fetch the existing row.
 
-The integration test suite formalizes this as the
-"idempotent retry path" pattern in places where local state
-may have diverged from server state (e.g. a prior run wrote
-to the server but failed to capture the response locally).
+This is the "idempotent retry path": use it wherever local
+state may have diverged from server state (e.g. a prior run
+wrote to the server but failed to capture the response
+locally).
 
 ## Polling cost
 

package/.agent/cookbook/_fixtures/README.md

@@ -52,15 +52,11 @@ the package.
 
 ## Provenance
 
-Templates are copied verbatim from
-[platform/priv/liquid_templates/](https://github.com/alvera-ai/platform/tree/develop/priv/liquid_templates),
-the production source-of-truth. The same vendoring chain
-already exists in
-`platform/integration-tests/tests/<industry>/fixtures/templates/`;
-this directory extends that chain into the SDK package so the
-cookbook corpus is self-contained at npm-install time.
-
-When a production template changes, re-copy the file here and
+Each template is a verbatim copy of the template the platform
+ships for that feed, vendored here so the cookbook corpus is
+self-contained at npm-install time.
+
+When the platform's template changes, re-copy the file here and
 re-run `make validate-cookbook` to confirm the cookbook still
 passes against the new template shape.
 
@@ -68,21 +64,21 @@ passes against the new template shape.
 
 ### `foundation/`
 
-| File | Consumed by cookbook(s) | Source-of-truth |
-|---|---|---|
-| `_lead_submissions_foundation_legal_entity.liquid` | `birthday-greeting-sms-trigger`, `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_legal_entity.liquid` |
-| `_lead_submissions_foundation_generic_table.liquid` | `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_generic_table.liquid` |
-| `_lead_submissions_foundation_mdm.liquid` | `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_mdm.liquid` |
+| File | Consumed by cookbook(s) |
+|---|---|
+| `_lead_submissions_foundation_legal_entity.liquid` | `birthday-greeting-sms-trigger`, `score-leads-with-llm-categorization` |
+| `_lead_submissions_foundation_generic_table.liquid` | `score-leads-with-llm-categorization` |
+| `_lead_submissions_foundation_mdm.liquid` | `score-leads-with-llm-categorization` |
 
 ### `healthcare/`
 
-| File | Consumed by cookbook(s) | Source-of-truth |
-|---|---|---|
-| `_cahps_appointments_healthcare_patient.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_patient.liquid` |
-| `_cahps_appointments_healthcare_appointment.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_appointment.liquid` |
-| `_cahps_appointments_healthcare_mdm.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_mdm.liquid` |
-| `sample_two_page.pdf` (data) | `ai-agent-invoke` | `integration-tests/tests/healthcare/fixtures/documents/sample_two_page.pdf` |
-| `memorandum-of-association-01.png` (data) | `ai-agent-invoke` | `integration-tests/tests/healthcare/fixtures/documents/memorandum-of-association-01.png` |
+| File | Consumed by cookbook(s) |
+|---|---|
+| `_cahps_appointments_healthcare_patient.liquid` | `appointment-review-sms-workflow` |
+| `_cahps_appointments_healthcare_appointment.liquid` | `appointment-review-sms-workflow` |
+| `_cahps_appointments_healthcare_mdm.liquid` | `appointment-review-sms-workflow` |
+| `sample_two_page.pdf` (data) | `ai-agent-invoke` |
+| `memorandum-of-association-01.png` (data) | `ai-agent-invoke` |
 
 The `contact-us-triage-with-llm` cookbook ingests into a generic
 table via the auto-provisioned identity contract, so it loads no
@@ -90,17 +86,17 @@ vendored template.
 
 ### `subscription/`
 
-| File | Consumed by cookbook(s) | Source-of-truth |
-|---|---|---|
-| `_customers_subscription_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/subscription/stripe/_customers_subscription_customer.liquid` |
-| `_customers_subscription_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` | `priv/liquid_templates/data_activation/interoperability/subscription/stripe/_customers_subscription_mdm.liquid` |
-| `stripe_customers_batch1.csv` (data) | `bulk-ingest` | `integration-tests/tests/subscription/fixtures/csv/stripe_customers_batch1.csv` |
+| File | Consumed by cookbook(s) |
+|---|---|
+| `_customers_subscription_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` |
+| `_customers_subscription_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent`, `bulk-ingest`, `rest-fetch` |
+| `stripe_customers_batch1.csv` (data) | `bulk-ingest` |
 
 ### `payments/`
 
-| File | Consumed by cookbook(s) | Source-of-truth |
-|---|---|---|
-| `_payment_accounts_payments_payment_account.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_payment_accounts_payments_payment_account.liquid` |
-| `_payment_accounts_payments_mdm.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_payment_accounts_payments_mdm.liquid` |
-| `_compliance_screenings_payments_compliance_screening.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_compliance_screenings_payments_compliance_screening.liquid` |
-| `_compliance_screenings_payments_mdm.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payments/atomic_fi/_compliance_screenings_payments_mdm.liquid` |
+| File | Consumed by cookbook(s) |
+|---|---|
+| `_payment_accounts_payments_payment_account.liquid` | `kyc-notification-on-account-activation` |
+| `_payment_accounts_payments_mdm.liquid` | `kyc-notification-on-account-activation` |
+| `_compliance_screenings_payments_compliance_screening.liquid` | `sanctions-screening-with-agent-review` |
+| `_compliance_screenings_payments_mdm.liquid` | `sanctions-screening-with-agent-review` |

package/.agent/cookbook/organic-marketing.md

@@ -3,11 +3,6 @@ title: "Organic marketing: score, greet, campaign — on one raw lake"
 summary: The whole organic-marketing surface in one walk. Stand up a tenant and a raw datalake, then run the scenarios end to end — an LLM agent banding inbound leads into a four-way SMS fan-out, a pure-Liquid birthday trigger that schedules a greeting a year out and closes the loop through its authenticated link, and an A/B campaign that gates on suppression, splits inside the workflow and dispatches on SMS and email in one run. Ends with delivery reconciliation and a natural-language read of the lake.
 use_case: organic-marketing
 slug: organic-marketing
-vitest_source:
-  - integration-tests/tests/organic-marketing/agent-driven-workflow.test.ts
-  - integration-tests/tests/organic-marketing/generic-tables.test.ts
-  - integration-tests/tests/organic-marketing/manual-upload-tool.test.ts
-  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 

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

@@ -3,16 +3,6 @@ title: "Payments compliance: screen, decide, notify — on a tokenized lake"
 summary: The whole payments-compliance surface in one walk. Stand up a tenant and a raw datalake, turn tokenization on because a model is going to read this data, then run two scenarios end to end — an LLM agent disambiguating gray-zone sanctions screenings into a verdict-keyed SMS fan-out, and a KYC notification fired by an account activation. Ends by reading one row back through raw, tokenized and redacted keys to show what each reader actually sees, then inspecting how far the tokenized copy has got and repairing one of its tables.
 use_case: payments-compliance
 slug: payments-compliance
-vitest_source:
-  - integration-tests/tests/payments-compliance/sanctions-review-workflow.test.ts
-  - integration-tests/tests/payments-compliance/kyc-upload-workflow.test.ts
-  - integration-tests/tests/payments-compliance/interoperability-contracts.test.ts
-  - integration-tests/tests/payments-compliance/run-dac-single.test.ts
-  - integration-tests/tests/payments-compliance/create-dac.test.ts
-  - integration-tests/tests/payments-compliance/system-templates.test.ts
-  - integration-tests/tests/payments-compliance/manual-upload-tool.test.ts
-  - integration-tests/tests/payments-compliance/data-sources.test.ts
-  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 

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

@@ -3,11 +3,6 @@ title: "Primary care: review, triage, extract — on a tokenized lake"
 summary: "The whole primary-care surface in one walk. Stand up a tenant, a raw datalake and the tokenized and redacted copies, then run three scenarios end to end — a post-visit review request that only reaches patients whose appointment was actually fulfilled, an LLM agent triaging inbound contact-us messages into a category-keyed fan-out, and a vision agent reading a scanned document. Ends by reading one appointment back through all three lakes to show what each reader sees, then inspecting how far the tokenized copy has got and repairing one of its tables."
 use_case: primary-care-feedback
 slug: primary-care
-vitest_source:
-  - integration-tests/tests/primary-care-feedback/standard-workflow.test.ts
-  - integration-tests/tests/primary-care-feedback/agent-driven-workflow.test.ts
-  - integration-tests/tests/primary-care-feedback/ai-agent-invoke.test.ts
-  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 

package/.agent/cookbook/subscription-saas.md

@@ -3,14 +3,6 @@ title: "Subscription SaaS: one customer spine, three workflows, three ways in"
 summary: "The whole subscription-billing surface in one walk. Stand up a tenant and a raw datalake, declare one customers table, and run three workflows over it — a welcome SMS gated on reachability, a dunning reminder gated on reachability and KYC, and an LLM agent that bands accounts by priority and fans out one SMS per band. Then fill the same table three more ways — a bulk CSV upload, a pull-based REST fetch, and finally a teammate invited onto the tenant."
 use_case: subscription-saas
 slug: subscription-saas
-vitest_source:
-  - integration-tests/tests/subscription-saas/standard-workflow.test.ts
-  - integration-tests/tests/subscription-saas/dunning-sms-workflow.test.ts
-  - integration-tests/tests/subscription-saas/agent-lead-triage.test.ts
-  - integration-tests/tests/subscription-saas/run-dac-bulk.test.ts
-  - integration-tests/tests/subscription-saas/run-dac-fetch.test.ts
-  - integration-tests/tests/subscription-saas/invite-team.test.ts
-  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 

package/.agent/datalakes.md

@@ -82,8 +82,8 @@ well-defined key prefixes inside the bucket the credentials point at:
 
 ```
    {datalake_slug}/data-activations/{client_slug}/{batch_id}/{dataset_table}.ndjson
-   {datalake_slug}/workflows/{wf_slug}/{batch_id}/merged.ndjson
-   {datalake_slug}/workflows/{wf_slug}/{batch_id}/{decision_key}/merged.ndjson
+   {datalake_slug}/workflows/{wf_slug}/merged/{batch_id}.ndjson
+   {datalake_slug}/workflows/{wf_slug}/merged/{batch_id}/{decision_key}.ndjson
 ```
 
 The merged NDJSONs are produced by background jobs

package/.agent/errors.md

@@ -108,11 +108,13 @@ don't distinguish layers from the JSON.
 depends on the failure. Ordinary field validation (`"can't be blank"`,
 `"is invalid"`, a custom `add_error` rule) is **422**. A failure that collides
 with the current state of the resource is **409 Conflict**: a **uniqueness
-collision** (`unique_constraint` / `unsafe_validate_unique`) or a **delete
-blocked by dependants** (a foreign-key/assoc constraint firing on delete). So
-do not assume every semantic conflict is a tidy 422 — read `_httpStatus`, not
-just the body. Read `source.pointer`, fix the field (or resolve the collision),
-resubmit.
+collision** (`unique_constraint` / `unsafe_validate_unique`), a **delete
+blocked by dependants** (a foreign-key/assoc constraint firing on delete), or
+an **action status updater refresh the updater's state refuses**: it is
+halted, or a poll for it is already queued or running
+(`action_status_updaters.md` §7). So do not assume every semantic conflict is
+a tidy 422 — read `_httpStatus`, not just the body. Read `source.pointer`, fix
+the field (or resolve the collision), resubmit.
 
 ## Concrete examples
 
@@ -174,6 +176,25 @@ comes back as a **409 Conflict** (`_httpStatus === 409`):
 }
 ```
 
+**State refusal → 409, no field** (`actionStatusUpdaters.refresh()` while a
+poll for that updater is already queued). The refusal is about the resource,
+not a field in your body, so `source.pointer` is empty and `title` is the
+status phrase:
+
+```json
+{
+  "errors": [
+    { "source": { "pointer": "" },
+      "title": "Conflict",
+      "detail": "A poll for this updater is already queued, so this refresh was not. Retry once it finishes." }
+  ]
+}
+```
+
+A halted updater answers the same way with `Updater is halted: status is
+<status>. Set status to active to resume polling.`, plus ` Last run error:
+<text>` when one is recorded. Nothing was queued in either case.
+
 ## HTTP status codes (under the hood)
 
 The SDK abstracts HTTP responses behind typed methods. Consumers mostly see
@@ -189,7 +210,7 @@ platform maps:
 | 401  | Missing or invalid Bearer / `x-api-key`                         |
 | 403  | Authenticated but role lacks permission                         |
 | 404  | Resource doesn't exist OR cross-tenant access (404, not 403)    |
-| 409  | Uniqueness collision, delete blocked by dependants, or URL/body id mismatch — same `errors[]` envelope |
+| 409  | Uniqueness collision, delete blocked by dependants, URL/body id mismatch, or an updater `refresh()` refused (halted, or a poll already queued) — same `errors[]` envelope |
 | 422  | Validation failed; envelope above is the thrown body            |
 | 5xx  | Platform-internal failure; safe to retry with backoff           |
 
@@ -200,6 +221,11 @@ Treat 5xx as infra noise — retry with exponential backoff. Treat 422 (and the
 resolve the collision, then resubmit. **Never retry a 422 or 409 with the same
 body** — the failure won't clear on its own.
 
+One 409 does clear on its own: `actionStatusUpdaters.refresh()` refused because
+a poll for that updater is already queued or running. Retry it once that poll
+finishes (the updater's `last_run_at` advances). The halted refusal does not
+clear on its own: set the updater's `status` back to `'active'` first.
+
 ## Mapping `source.pointer` back to your TypeScript type
 
 A `source.pointer` like `/db_reader_user` maps directly to the

package/.agent/interoperability_contracts.md

@@ -251,13 +251,10 @@ not interchangeable.
 
 Two related shapes worth keeping straight:
 
-- **`mdm.verify`** (see `mdm.md`) takes looser input — it asks "is this
-  really you?" about an already-known subject, so it needs `value` plus a
-  `uri` **or** a `type`, not both. Its example is not a template for this
-  one.
-- **payments** additionally requires `id_type` on each entry of its own
-  verify payload. Per-domain differences are real; check the domain you are
-  writing for.
+- **`mdm.verify`** (see `mdm.md`) asks "is this really you?" about an
+  already-known subject. Its identifier entries carry `system` and `value`,
+  both required, with `id_type` and `country` optional — the same on every
+  datalake. Its example is not a template for this one.
 
 ## 4. Error envelopes