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

package/.agent/mdm.md

@@ -41,8 +41,8 @@ vocabulary — `given_name`, `family_name`, `birth_date` and
 `gender` are gone, not renamed variants to pick between.
 
 ```
-   MDMVerifyRequest       every field the verifier matches
-   ────────────────       ────────────────────────────────
+   MDMVerifyRequest       every field the request takes
+   ────────────────       ─────────────────────────────
    required               legal_entity_id
    individual             first_name middle_name last_name
                           preferred_name date_of_birth
@@ -53,6 +53,18 @@ vocabulary — `given_name`, `family_name`, `birth_date` and
                           identifiers addresses
 ```
 
+Not every field is evidence on its own (§2):
+
+```
+   can stand alone        first_name last_name preferred_name
+                          date_of_birth business_name date_formed
+                          phone identifiers addresses
+   only beside one        legal_entity_type middle_name
+   of those               citizenship_country nationality
+                          doing_business_as_names
+                          jurisdiction_country email
+```
+
 An individual example:
 
 ```typescript
@@ -88,24 +100,56 @@ const { data: result } = await api.mdm.verify(
     ],
   },
 )
-// result.status        === 'verified' | 'not_verified'
+// result.status          === 'verified'   — the only success body
 // result.legal_entity_id === body.legal_entity_id
-// result.verified_at   — ISO 8601 timestamp
-// when status === 'not_verified':
-//   result.errors      — { <field_name>: [reason, ...] } per-field failure detail
+// result.verified_at     — ISO 8601 timestamp
 ```
 
-The response is **polymorphic on `status`**:
+`verified` is the **only** success body. A subject that does not
+verify is not a body you read — the call throws, like every other
+route that answers 4xx:
 
 ```
-status === 'verified'       → 200 { legal_entity_id, verified_at }
-status === 'not_verified'   → 422 { legal_entity_id, verified_at, errors }
+verified           → 200 { status: 'verified', legal_entity_id, verified_at }
+did not verify     → throws AlveraApiError, _httpStatus 422
+                       { errors: [ { title: 'Invalid value',
+                                     source: { pointer: '/<field>' },
+                                     detail: '<why it failed>' } ] }
+                       one entry per field that did not match
+subject not found  → throws AlveraApiError, _httpStatus 404
+```
+
+So `data` is only ever the verified answer, and every failed check
+reaches you in `catch`, in the same envelope every other 422 uses
+(see `errors.md`). Read which fields failed from each entry's
+`source.pointer`:
+
+```typescript
+import type { AlveraApiError } from '@alvera-ai/platform-sdk'
+
+try {
+  const { data } = await api.mdm.verify(tenantSlug, datalakeSlug, {
+    legal_entity_id: '00000000-0000-0000-0000-000000000000',
+    last_name: 'Garcia',
+    addresses: [{ postal_code: '94110', country: 'US' }],
+  })
+  // data.status === 'verified' — act on this person
+} catch (err) {
+  const status = (err as { _httpStatus?: number })._httpStatus
+  if (status === 422) {
+    for (const e of (err as AlveraApiError).errors) {
+      // e.source.pointer — '/last_name', '/addresses', '/base', …
+      // e.detail         — 'does not match any known name', …
+    }
+  } else if (status === 404) {
+    // no legal entity has this id
+  } else {
+    throw err
+  }
+}
 ```
 
-A `not_verified` response is a successful identity check that
-returned a negative result — it arrives as a 422 whose body
-still carries the full envelope. Distinguish it from the other
-rejections (404 for missing subject, 401 for missing auth).
+A 401 (missing or wrong key) throws too.
 
 ### One subject: the legal entity
 
@@ -128,14 +172,23 @@ declare the column; every generic-table row struct already has it.
 
 ## 2. Rules the type cannot encode
 
-### `legal_entity_id` is required; at least one identity field with it
+### `legal_entity_id` is required; at least one field that stands alone with it
 
 `legal_entity_id` (the master record to verify against) is the
 only required field. Every other property is optional, and the
-verifier requires **at least one** of them at runtime:
-
-- a body with only `legal_entity_id` → 422 with
-  `errors.base: ["at least one verification field is required"]`
+verifier requires **at least one field that can stand alone as
+evidence** at runtime: `first_name`, `last_name`, `preferred_name`,
+`date_of_birth`, `business_name`, `date_formed`, `phone`,
+`identifiers` or `addresses`. The other seven (`legal_entity_type`,
+`middle_name`, `citizenship_country`, `nationality`,
+`doing_business_as_names`, `jurisdiction_country`, `email`) are
+accepted, but count only beside one of those nine.
+
+- a body with only `legal_entity_id`, or with only fields from the
+  seven → 422, one entry with `source.pointer: '/base'` and
+  `detail: 'at least one verification field is required'`
+- an address alone is enough evidence; if it does not match, the
+  422 carries the `/addresses` entry and nothing else
 
 A body carrying the retired vocabulary — `given_name`,
 `family_name`, `birth_date`, `gender` — falls into that same 422,
@@ -160,9 +213,33 @@ addresses        per-component exact, case- and whitespace-
                  insensitive; at least one address must match
 ```
 
-All supplied fields must pass for the overall result to be
-`'verified'`. A single failing field flips the result to
-`'not_verified'` and surfaces the field name in `errors`.
+All supplied fields must pass for the call to return
+`'verified'`. Each field that fails adds one entry to the thrown
+422, pointing at the field you sent:
+
+```
+source.pointer      detail
+/last_name          does not match any known name
+/first_name         does not match any known name   (see below)
+/business_name      does not match any known name
+/date_of_birth      does not match
+/date_formed        does not match
+/identifiers        no matching identifier found
+/phone              does not match any known phone number
+/addresses          no matching address found
+/addresses/country  can't be blank                  (an address sent without a country)
+/base               at least one verification field is required
+```
+
+First, middle and preferred names are checked together as one
+bag of given names, so they fail as one entry. It points at a
+given-name field you actually sent: `/first_name` if you sent one,
+else `/middle_name`, else `/preferred_name`.
+
+Two fields failing is two entries; nothing is summarised into a
+single verdict. The mock answers its wrong-details case with one
+`/base` entry, `detail: 'Verification match failed'`; the platform
+itself names the field.
 
 ### `legal_entity_id` is the legal entity's own id
 
@@ -176,11 +253,12 @@ redacted lakes — rather than a second row with its own id. The
 old failure mode where passing the regulated twin's id returned a
 404 cannot arise.
 
-If the supplied `legal_entity_id` doesn't resolve, the response
-is a 404, not a `'not_verified'`. The distinction matters:
+If the supplied `legal_entity_id` doesn't resolve, the call throws
+a 404 envelope (`title: 'Not Found'`, `detail: 'Subject not found'`,
+empty `source.pointer`), not a 422. The distinction matters:
 
-- `'not_verified'` -> "entity exists, identity fields didn't match"
-- 404               -> "entity doesn't exist at all"
+- 422 -> "entity exists, identity fields didn't match"
+- 404 -> "entity doesn't exist at all"
 
 A consumer that conflates the two will mis-route an identity
 challenge as a missing-record error.
@@ -245,13 +323,14 @@ Two limits that follow from the same rule:
 **Server-derived (Response-only).**
 
 ```
-status         enum   — 'verified' | 'not_verified'
-verified_at    string — ISO 8601 timestamp of the verification attempt
-errors         object — present only when status === 'not_verified';
-                         maps field name to an array of failure reasons
+status         enum   — 'verified', its only value
+verified_at    string — ISO 8601 timestamp of the verification
 ```
 
-**Caller-supplied (round-trip on the verified branch).**
+There is no `errors` field on the response: a failed check is a
+thrown 422 (§4), never a body.
+
+**Caller-supplied (round-trip in the verified answer).**
 
 ```
 legal_entity_id  required UUID — the master record to verify against
@@ -270,35 +349,35 @@ legal_entity_id  required UUID — the master record to verify against
 
 ## 4. Error envelopes
 
-Standard JSON:API envelopes per `errors.md`. Common rejections:
-
-| `source.pointer`              | Cause                                                  |
-|-------------------------------|--------------------------------------------------------|
-| `/legal_entity_id`            | missing, or no legal entity has this id |
-| `errors.base`                 | no identity field was supplied, or only retired ones (`given_name`, `family_name`, `birth_date`, `gender`) which are ignored — 422 with `status: "not_verified"` in the body |
-| `/identifiers/0/system`       | missing system on an identifier entry                  |
-| `/identifiers/0/value`        | missing value on an identifier entry                   |
-
-The `not_verified` outcome is always a **422 response** carrying
-the full body envelope; the two shapes differ only in `errors`:
-
-- **Identity mismatch (most common)** — `errors` keyed by the
-  failing field(s), e.g. `errors.last_name`, or `errors.base`
-  with "Verification match failed". The entity exists; the
-  supplied identity didn't match.
-- **No usable identity fields** — `errors.base` set to
-  `["at least one verification field is required"]`. Verification
-  was structurally impossible: nothing supplied, or only retired
-  fields, which are ignored.
-
-Malformed identifier entries surface the embed failure flattened
-into the field's error list — `errors.identifiers: ["value can't
-be blank"]` — still a 422, never a 500. `system` and `value` are
-the required pair; `id_type` and `country` are optional.
-
-Pattern-match on `status` first, then on the HTTP status code.
-The 404 case (subject doesn't exist) is a separate envelope —
-see §6 gotcha 2.
+Every error `.verify` returns is the standard JSON:API envelope
+per `errors.md`, thrown as `AlveraApiError`. There is no second
+shape. Common rejections:
+
+| HTTP | `source.pointer`          | Cause |
+|------|---------------------------|-------|
+| 422  | `/<field>`                | a field you sent did not match the master record — one entry per field (§2 lists the pointers and details) |
+| 422  | `/base`                   | no field that can stand alone as evidence was supplied (§2) — including a body of only `email`, `middle_name` or the other five that count only beside one, or only retired fields (`given_name`, `family_name`, `birth_date`, `gender`), which are ignored |
+| 422  | `/legal_entity_id`        | `legal_entity_id` missing from the body |
+| 422  | `/identifiers/0/system`   | missing system on an identifier entry |
+| 422  | `/identifiers/0/value`    | missing value on an identifier entry |
+| 404  | `""` (empty)              | no legal entity has this id — `title: 'Not Found'`, `detail: 'Subject not found'` |
+
+A subject that does not verify and a body the platform refuses
+arrive the same way: a 422 whose entries all carry
+`title: 'Invalid value'`. Read the field from `source.pointer`.
+There is no `errors` map keyed by field name, and a failure body
+carries no `status`, `legal_entity_id` or `verified_at`.
+
+`system` and `value` on an identifier are required by the request
+schema, so a missing one is refused before verification runs, and
+its pointer carries the entry's index. An embed the verifier
+itself rejects points at the embed's field without an index: an
+address sent without a country is `/addresses/country`, not
+`/addresses/0/country`. `id_type` and `country` on an identifier
+are optional. Either way it is a 422, never a 500.
+
+Branch on `_httpStatus`: 422 for a failed check or a refused body,
+404 for a subject that does not exist (§6 gotcha 2).
 
 ## 5. Lifecycle
 
@@ -344,26 +423,30 @@ through `api.mdm`.
 
 ## 6. Gotchas
 
-1. **Every `not_verified` outcome is a 422 whose body still
-   carries the envelope.** Read the body's `status` — don't let
-   generic 4xx handling swallow the `errors` payload that
-   explains which fields failed. Gate the downstream "act on
-   this person" path on `result.status === 'verified'`.
-
-2. **`legal_entity_id` missing → 404, identity mismatch → 422
-   with a body.** A verify call against a deleted or never-existed
-   entity id returns a 404 envelope, NOT a `'not_verified'`
-   response. Consumers that handle only the polymorphic
-   verify body will surface the 404 as an unexpected exception.
-   Wrap the verify call in standard 4xx handling per `errors.md`.
-
-3. **At least one identity field is required.** A body with only
-   `legal_entity_id` — or only retired fields like `given_name`
-   or `birth_date`, which are ignored — returns a 422 with
-   `errors.base` set to `["at least one verification field is
-   required"]` and `status: "not_verified"` in the body. This is
-   enforced at runtime rather than in the request schema, so the
-   TypeScript type permits the body but the wire rejects it.
+1. **A subject that does not verify throws; there is no
+   `not_verified` body.** `data` is only ever the verified answer.
+   Every failed check is a thrown `AlveraApiError` with
+   `_httpStatus === 422`, one entry per mismatched field. Code
+   written for the old `{ status: 'not_verified', errors: {…} }`
+   body never runs: its branch is unreachable and the 422 lands in
+   `catch`. Don't let generic 4xx handling swallow it — read each
+   entry's `source.pointer` to learn which fields failed.
+
+2. **Subject missing → 404, identity mismatch → 422.** Both
+   throw, in the same envelope. A verify call against a deleted
+   or never-existed entity id throws a 404 (`title: 'Not Found'`,
+   empty pointer), not a 422. Branch on `_httpStatus` before
+   reading pointers, per `errors.md`.
+
+3. **At least one field that can stand alone is required.** A body
+   with only `legal_entity_id` — or only fields that count just
+   beside another (`email`, `middle_name`, `nationality`, …), or
+   only retired fields like `given_name` or `birth_date`, which are
+   ignored — throws a 422 with one
+   entry: `source.pointer: '/base'`, `detail: 'at least one
+   verification field is required'`. This is enforced at runtime
+   rather than in the request schema, so the TypeScript type
+   permits the body but the wire rejects it.
 
 4. **Unknown fields are ignored, not rejected.** There is one
    field set (§1) and no domain scoping, but anything outside it
@@ -385,8 +468,9 @@ through `api.mdm`.
    case, and trailing slashes in `system` URIs all matter.
    Compare with the master record's identifier system strings
    character-for-character; a `'http://hospital.org/mrn'` vs
-   `'http://hospital.org/mrn/'` mismatch will flip the verifier
-   to `'not_verified'` even when the value is correct.
+   `'http://hospital.org/mrn/'` mismatch fails the check with an
+   `/identifiers` entry (`no matching identifier found`) even when
+   the value is correct.
    `system` and `value` are the required pair. `id_type`
    (`'digital_identifier'`, `'us_ssn'`, `'lei'`) and `country`
    are optional — the per-domain rule that once made `id_type`

package/.agent/tools.md

@@ -792,12 +792,16 @@ the ASU's AI metadata. A failed poll lands its structured reason in
 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:
+usable as a proof — four 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.
+- **`refresh` can answer `409` and queue nothing.** A halted updater
+  (`status` not `'active'`) refuses until you set `status` back to
+  `'active'`. An updater with a poll already queued or running refuses
+  until that poll finishes; retry then. The error's `detail` says which.
 - **`last_run_status` has two values.** `'ok'` means the run read its
   whole time window; `'error'` means it stopped, and `last_run_error`
   says why. There is no partial run: every page of the window is read,

package/dist/index.d.mts

@@ -690,6 +690,10 @@ type ActionStatusUpdaterResponse = {
    * Outcome of the last poll run: `ok` when the run read its whole window, `error` when it stopped — read `last_run_error` for why. A run is never partial: every page of the window is read, one job per page.
    */
   readonly last_run_status?: 'ok' | 'error';
+  /**
+   * When a cron tick last skipped because an earlier run of this updater was still going (null if none has). A skip is not a run and leaves the last-run fields alone.
+   */
+  readonly last_skipped_at?: string | null;
   message_config: SimpleTemplateConfigResponse;
   /**
    * Updater name
@@ -999,21 +1003,20 @@ declare enum ActionType {
  *
  * Every legal entity is ultimately a **person** or a **company**, so the identity
  * fields are organized along that ontology rather than per industry. All identity
- * fields are optional on the wire; the datalake's own data-domain validator casts
- * only the fields its domain knows and requires **at least one** of them — a body
- * that carries only fields foreign to the datalake's domain (or none at all)
- * returns 422 with `errors.base: ["at least one verification field is required"]`.
+ * fields are optional on the wire, and every datalake reads the same set.
  *
- * Field vocabulary per data domain:
+ * At least one field that can stand alone as evidence is required: `first_name`,
+ * `last_name`, `preferred_name`, `date_of_birth`, `business_name`, `date_formed`,
+ * `phone`, `identifiers` or `addresses`. The rest (`legal_entity_type`,
+ * `middle_name`, `citizenship_country`, `nationality`, `doing_business_as_names`,
+ * `jurisdiction_country`, `email`) are accepted but cannot be the only evidence.
+ * A body with none returns 422 in the house error envelope, pointer `/base`.
  *
- * | identity fields |
- * |---|---|
- * | `legal_entity_type`, `first_name`, `middle_name`, `last_name`, `preferred_name`, `date_of_birth`, `citizenship_country`, `nationality`, `business_name`, `doing_business_as_names`, `date_formed`, `jurisdiction_country`, `phone`, `email`, `identifiers` |
- *
- * Every property below is cast by `Platform.MDMInput`'s
- * `@verification_fields`. Keep the two in step — a property advertised here
- * but absent there is accepted by the router and then silently dropped by
- * `cast/3`, which reads to the caller as "my attribute did not match".
+ * Every property below is cast by `Platform.MDMInput.verification_changeset/2`:
+ * `@verification_fields` plus the `identifiers` and `addresses` embeds. Keep the
+ * two in step — a property advertised here but absent there is accepted by the
+ * router and then silently dropped by `cast/3`, which reads to the caller as "my
+ * attribute did not match".
  *
  */
 type MdmVerifyRequest = {
@@ -3324,7 +3327,7 @@ type SqlDatabaseResponse = {
 /**
  * MDMVerifyResponse
  *
- * Result of MDM identity verification
+ * A legal entity that verified against its master record
  */
 type MdmVerifyResponse = {
   /**
@@ -3336,22 +3339,6 @@ type MdmVerifyResponse = {
    * Timestamp of verification
    */
   verified_at: string;
-} | {
-  /**
-   * Field-level verification failure details
-   */
-  errors: {
-    [key: string]: Array<string>;
-  };
-  /**
-   * The legal entity id that failed verification
-   */
-  legal_entity_id: string;
-  status: 'not_verified';
-  /**
-   * Timestamp of verification attempt
-   */
-  verified_at: string;
 };
 /**
  * S3CloudStorageAwsResponse