@alvera-ai/platform-sdk 0.17.0 → 0.18.0

package/.agent/mdm.md

@@ -2,8 +2,7 @@
 
 Master Data Management is the platform's entity-resolution layer.
 It binds every inbound row to a canonical **subject** record (the
-domain's primary entity — e.g. `patient` for healthcare-domain
-datalakes, `legal_entity` for foundation-domain datalakes) so
+platform's one identity dataset, the legal entity) so
 that downstream datasets, workflows, and agent prompts reference
 a single, deduplicated identity rather than the raw inbound
 identifiers each upstream system carries.
@@ -22,7 +21,7 @@ see §5 Lifecycle.
 MDM is **Datalake-DB-resident** — the parent datalake must be
 `status: 'ready'` before any MDM verb is called, since
 resolution / verification both look up against the datalake's
-regulated master records.
+master records.
 
 ## 1. Wire shape — `.verify`
 
@@ -33,72 +32,64 @@ recipient) and at runtime (connected apps confirming the form
 submitter before posting tracking updates).
 
 Every MDM subject is ultimately a **person** or a **company**,
-and the request type is the superset of every data domain's
-identity vocabulary organized along that ontology. You send
-`subject_id` plus the identity fields **in your datalake's own
-domain vocabulary** — the platform validates them with that
-domain's verifier, which knows only its own fields.
+and the request type is that ontology's identity vocabulary. You
+send `legal_entity_id` plus the identity fields you hold.
+
+There is ONE field set. GH-859 removed data domains, and with
+them the per-domain verifiers that each knew only their own
+vocabulary — `given_name`, `family_name`, `birth_date` and
+`gender` are gone, not renamed variants to pick between.
 
 ```
-   data_domain            identity fields the verifier matches
-   ───────────            ────────────────────────────────────
-   healthcare             given_name family_name birth_date gender
-                          phone email identifiers
-   foundation             legal_entity_type first_name middle_name
-                          last_name preferred_name date_of_birth
+   MDMVerifyRequest       every field the verifier matches
+   ────────────────       ────────────────────────────────
+   required               legal_entity_id
+   individual             first_name middle_name last_name
+                          preferred_name date_of_birth
                           citizenship_country nationality
-                          business_name doing_business_as_names
+   business               business_name doing_business_as_names
                           date_formed jurisdiction_country
-                          phone email identifiers
-   subscription           customer_type name tax_id phone email
-                          identifiers
-   service_commerce       consumer_type name phone email identifiers
-   core_banking           party_type given_name family_name
-                          company_name birth_date phone email
-                          identifiers
-   payments               account_holder_type given_name family_name
-                          company_name birth_date phone email
-                          identifiers (each entry additionally
-                          requires id_type)
+   either                 legal_entity_type phone email
+                          identifiers addresses
 ```
 
-A subscription example — the customer's own vocabulary:
+An individual example:
 
 ```typescript
 import type {
-  MDMVerifyRequest,
-  MDMVerifyResponse,
+  MdmVerifyRequest,
+  MdmVerifyResponse,
 } from '@alvera-ai/platform-sdk'
 
 const { data: result } = await api.mdm.verify(
   tenantSlug,
   datalakeSlug,
   {
-    subject_id: subjectUuid,           // required, every domain
-    name: 'Test Priya Anand',          // subscription: fuzzy full-name match
-    tax_id: '123-45-6789',             // subscription: exact match
+    legal_entity_id: legalEntityUuid,  // required
+    first_name: 'Priya',               // fuzzy
+    last_name:  'Anand',               // fuzzy
   },
 )
 ```
 
-And a healthcare one — FHIR-shaped demographics:
+And one keyed on an external identifier:
 
 ```typescript
 const { data: result } = await api.mdm.verify(
   tenantSlug,
   datalakeSlug,
   {
-    subject_id: subjectUuid,
-    family_name: 'Garcia',                            // fuzzy
-    given_name:  'Maria',                             // fuzzy
-    birth_date:  '1978-11-03',                        // component-fuzzy
+    legal_entity_id: legalEntityUuid,
+    last_name:     'Garcia',                          // fuzzy
+    first_name:    'Maria',                           // fuzzy
+    date_of_birth: '1978-11-03',                      // component-fuzzy
     identifiers: [                                    // exact
       { system: 'http://hospital.org/mrn', value: 'MRN12345' },
     ],
   },
 )
 // result.status        === 'verified' | 'not_verified'
-// result.subject_id    === body.subject_id
+// 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
@@ -107,8 +98,8 @@ const { data: result } = await api.mdm.verify(
 The response is **polymorphic on `status`**:
 
 ```
-status === 'verified'       → 200 { subject_id, verified_at }
-status === 'not_verified'   → 422 { subject_id, verified_at, errors }
+status === 'verified'       → 200 { legal_entity_id, verified_at }
+status === 'not_verified'   → 422 { legal_entity_id, verified_at, errors }
 ```
 
 A `not_verified` response is a successful identity check that
@@ -116,89 +107,80 @@ 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).
 
-### Subject per data domain
-
-Every datalake has a single canonical **subject entity** — the
-domain's primary identity that all other rows attribute to. The
-verify call resolves against that subject. The subject's wire
-name follows the dataset's `resource_type` (see
-`interoperability_contracts.md` §2 `resource_type`):
+### One subject: the legal entity
 
-```
-   data_domain                  subject resource_type
-   ───────────                  ─────────────────────
-   healthcare                   patient
-   core_banking                 party
-   payments                     legal_entity
-   subscription                 customer
-   service_commerce             consumer
-   trading                      trading_account
-   foundation                   legal_entity
-```
+Every datalake resolves against the same canonical subject — the
+**legal entity**. `legal_entity` and `beneficial_owner` are the
+only identity datasets the platform ships; everything else a
+build needs is a generic table it authors itself.
 
-(`legal_entity` is the subject for both `payments` and
-`foundation` — different domain context, same canonical entity
-shape.)
+That is the whole of it now. There is no per-domain subject to
+look up, no `patient` / `party` / `customer` / `consumer` /
+`trading_account` to map onto, and no table of which domain
+resolves to which entity. GH-859 removed the domains and the
+subjects with them.
 
-Generic tables in a datalake automatically carry a foreign-key
-column to their subject (e.g. `patient_id` in a healthcare-
-domain generic table). Querying that column scopes any custom
-dataset to subjects the verify call has confirmed.
+Generic-table rows carry `legal_entity_id`, populated by MDM
+resolution when the row's contract supplies an `mdm_input_config`
+— not a per-domain foreign key like `patient_id`. Querying that
+column scopes any custom dataset to resolved entities. You do not
+declare the column; every generic-table row struct already has it.
 
 ## 2. Rules the type cannot encode
 
-### `subject_id` is required; identity fields per YOUR domain
+### `legal_entity_id` is required; at least one identity field with it
 
-`subject_id` (the master record to verify against) is the only
-required field. The TypeScript type carries every domain's
-identity fields as optional properties, but the datalake's
-verifier casts **only the fields its domain knows** (§1 table)
-and requires **at least one** of them at runtime:
+`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 `subject_id` → 422 with
+- a body with only `legal_entity_id` → 422 with
   `errors.base: ["at least one verification field is required"]`
-- a body whose identity fields all belong to a *different*
-  domain's vocabulary (e.g. healthcare's `family_name` sent to an
-  subscription datalake) is treated the same way — the
-  foreign fields are **ignored**, not rejected, so the request
-  falls into the same at-least-one 422.
 
-### Verification is per-field, with domain-scoped match rules
+A body carrying the retired vocabulary — `given_name`,
+`family_name`, `birth_date`, `gender` — falls into that same 422,
+and this is the trap worth knowing: unknown keys are **ignored,
+not rejected**. Nothing tells you the field was dropped. Send
+only those and you get the at-least-one error for a request that
+looks full; send one of them alongside a known field and it
+verifies on the known field alone, silently ignoring the rest.
+
+### Verification is per-field
 
-Each supplied identity field the domain knows is checked
-independently against the subject's regulated master record.
+Each supplied identity field is checked independently against
+the legal entity's master record.
 String names are fuzzy-matched, dates component-fuzzy-matched,
 and structured identifiers exact-matched:
 
 ```
-name fields      Jaro-Winkler fuzzy match (thresholds ~0.80-0.85;
-                 core_banking company_name is EXACT)
+name fields      Jaro-Winkler fuzzy match (thresholds ~0.80-0.85)
 date fields      component-wise fuzzy match ≥ 0.80
 identifiers      exact (system, value) match
-tax_id           exact match (subscription)
+addresses        per-component exact, case- and whitespace-
+                 insensitive; at least one address must match
 ```
 
-All supplied known fields must pass for the overall result to be
+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`.
 
-### `subject_id` is the UNREGULATED subject row's id
+### `legal_entity_id` is the legal entity's own id
+
+`legal_entity_id` is `legal_entities.id` — the same value every
+generic-table row carries as its own `legal_entity_id`.
 
-`subject_id` is the subject's id in the datalake's
-**unregulated** schema — the same value every other unregulated
-row carries as `mdm_subject_id`. For a `foundation` or
-`payments` datalake that is `legal_entities.id`. The
-identity FIELDS are matched against the regulated master record,
-but the HANDLE you pass is the unregulated id: supplying the
-regulated twin's id returns a 404 "Subject not found", never a
-`'not_verified'`.
+There is one lake row per entity now, so there is no public
+handle and regulated twin to choose between: GH-859 collapsed the
+two-tier lake, and masking is infrastructure — the tokenized and
+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 `subject_id` doesn't resolve to an unregulated
-subject row, the response is a 404, not a `'not_verified'`. The
-distinction matters:
+If the supplied `legal_entity_id` doesn't resolve, the response
+is a 404, not a `'not_verified'`. The distinction matters:
 
-- `'not_verified'` → "subject exists, identity fields didn't match"
-- 404               → "subject doesn't exist at all"
+- `'not_verified'` -> "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.
@@ -217,13 +199,16 @@ errors         object — present only when status === 'not_verified';
 **Caller-supplied (round-trip on the verified branch).**
 
 ```
-subject_id     required UUID — the master record to verify against
-<identity>     optional      — YOUR domain's fields from the §1 table;
-                               person fields (given/family/first/last
-                               names, birth dates), company fields
-                               (company_name/business_name/name/tax_id),
-                               and universal fields (identifiers, phone,
-                               email, the domain's subject-type axis)
+legal_entity_id  required UUID — the master record to verify against
+<identity>       optional     — any field from the §1 set: person fields
+                                (first/middle/last/preferred names,
+                                date_of_birth, citizenship_country,
+                                nationality), business fields
+                                (business_name, doing_business_as_names,
+                                date_formed, jurisdiction_country), and
+                                fields either kind carries
+                                (legal_entity_type, phone, email,
+                                identifiers, addresses)
 ```
 
 **Write-only (Request-only).** None.
@@ -234,8 +219,8 @@ Standard JSON:API envelopes per `errors.md`. Common rejections:
 
 | `source.pointer`              | Cause                                                  |
 |-------------------------------|--------------------------------------------------------|
-| `/subject_id`                 | missing, or no UNREGULATED subject row has this id (passing the regulated twin's id is the classic cause) |
-| `errors.base`                 | no identity field the domain recognizes was supplied — 422 with `status: "not_verified"` in the body |
+| `/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                   |
 
@@ -243,19 +228,18 @@ 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) in the domain's vocabulary (e.g.
-  `errors.family_name` on healthcare, `errors.base` with
-  "Verification match failed" on subscription). The
-  subject exists; the supplied identity didn't match.
+  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 fields
-  foreign to the domain).
+  was structurally impossible: nothing supplied, or only retired
+  fields, which are ignored.
 
-Malformed identifier entries (e.g. payments's required
-`id_type` missing) surface the embed failure flattened into the
-field's error list — `errors.identifiers:
-["id_type can't be blank"]` — still a 422, never a 500.
+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 —
@@ -267,7 +251,7 @@ see §6 gotcha 2.
 
 The verify call returns the resolution outcome in the response —
 no async polling, no job id. The platform performs the fuzzy
-match against the regulated master record inline.
+match against the master record inline.
 
 ### Other MDM operations are platform-internal
 
@@ -280,7 +264,7 @@ SDK surface:
   pipeline before the dataset upsert. The pipeline matches the
   rendered MDM input against existing subjects (or creates one
   if no match) and produces an `mdm_output` carried forward to
-  the regulated upsert. Consumers configure this implicitly via
+  the legal-entity upsert. Consumers configure this implicitly via
   the contract's `mdm_input_config` — see
   `interoperability_contracts.md` §2 and `data_activation_clients.md`
   §6.
@@ -311,27 +295,28 @@ through `api.mdm`.
    explains which fields failed. Gate the downstream "act on
    this person" path on `result.status === 'verified'`.
 
-2. **`subject_id` missing → 404, identity mismatch → 422 with a
-   body.** A verify call against a deleted or never-existed
-   subject id returns a 404 envelope, NOT a `'not_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 the domain recognizes is
-   required.** A body with only `subject_id` — or only fields
-   from a different domain's vocabulary — returns a 422 with
+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.
 
-4. **The field set is domain-scoped — consult the §1 table for
-   YOUR datalake's domain.** The request type is the superset of
-   every domain's vocabulary; fields outside your domain's set
-   are silently ignored by its verifier (they don't error, they
-   just don't count). Sending only ignored fields lands you in
-   gotcha 3's at-least-one 422.
+4. **Unknown fields are ignored, not rejected.** There is one
+   field set (§1) and no domain scoping, but anything outside it
+   — including the retired `given_name` / `family_name` /
+   `birth_date` / `gender` — is silently dropped rather than
+   erroring. Sending only those lands you in gotcha 3's
+   at-least-one 422; sending one alongside a known field verifies
+   on the known field alone and tells you nothing.
 
 5. **MDM also runs at ingestion — and you don't call it
    directly.** The `mdm_input_config` on each interoperability
@@ -347,25 +332,23 @@ through `api.mdm`.
    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.
-   payments additionally REQUIRES `id_type` on every
-   identifier entry (e.g. `'digital_identifier'`, `'us_ssn'`,
-   `'lei'`) — omitting it is a 422 on `errors.identifiers`.
-
-7. **Send your domain's NATIVE vocabulary — there is no wire
-   translation.** Foundation stores and matches `first_name` /
-   `last_name` / `date_of_birth` (matching `LegalEntity`), so a
-   foundation verify body must carry exactly those names;
-   healthcare's `given_name` / `family_name` / `birth_date` are
-   foreign to foundation and fall into gotcha 3's 422. The same
-   applies in every direction — the field names in §1's table
-   are the wire contract per domain, verbatim.
-
-8. **`subject_id` is the unregulated legal-entity id (`==
-   mdm_subject_id`) — the regulated twin's id 404s.** The most
-   common source of gotcha 2's 404 is a hook that reads the
-   REGULATED subject row and passes ITS id to `mdm.verify` —
-   "Subject not found", even though the person plainly exists.
-   The verify handle is the unregulated row's id, the same value
-   every other unregulated row carries as `mdm_subject_id` (the
-   subject row is its own MDM subject). §1's table names each
-   domain's subject dataset; §2 states the tier rule.
+   `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`
+   mandatory went with the domains.
+
+7. **The field names ARE the wire contract — there is no
+   translation.** The platform stores and matches `first_name` /
+   `last_name` / `date_of_birth`, matching `LegalEntity`, so a
+   verify body must carry exactly those. The retired
+   `given_name` / `family_name` / `birth_date` / `gender` are
+   ignored and fall into gotcha 3's 422. §1's set is the contract,
+   verbatim.
+
+8. **There is no second id to confuse it with.** This gotcha used
+   to warn that passing the REGULATED twin's id 404s while the
+   person plainly exists. GH-859 collapsed the two-tier lake:
+   there is one `legal_entities` row per entity, and masking is
+   infrastructure — the tokenized and redacted lakes — not a
+   second row with its own id. Kept as an entry because the old
+   advice is still in circulation.

package/.agent/messages.md

@@ -31,7 +31,7 @@ Read it like any dataset: `api.datasets.createUserSearch` +
 the plural `messages` is the SQL *table* name (used in
 `executeSql` queries and as this page's title), and passing it as
 the dataset type 422s with `/resource_type is not valid`. Base SQL
-alias: `rm`.
+alias: `m`.
 
 ## 1. The status lifecycle — and who writes each hop
 
@@ -106,11 +106,11 @@ Identity + routing:
 
 ```
 id, direction ('outbound'|'inbound'), channel ('sms'|'email'|
-'voice'|'web_form'|'push'), sender_type, mdm_subject_id,
+'voice'|'web_form'|'push'), sender_type, legal_entity_id,
 thread_id, in_reply_to_id
 ```
 
-Content (tokenized in unregulated mode):
+Content (masked in the tokenized and redacted lakes):
 
 ```
 subject, body, attachments, metadata, sender_id
@@ -134,7 +134,7 @@ Provenance (which workflow produced this):
 
 ```
 workflow_id, action_id, decision_key, context_key,
-idempotency_key            — unique per (mdm_subject_id,
+idempotency_key            — unique per (legal_entity_id,
                              idempotency_key); a repeat fire on the
                              same key lands as status 'invalidated'
                              (nothing sent) — NOT status 'duplicate',
@@ -149,58 +149,60 @@ goes through `action_logs` (which has `batch_id` AND `external_id`)
 ## 3. Reading messages
 
 ```typescript
-// (1) materialise a search — WHERE fragment against alias `rm`
+// (1) materialise a search — WHERE fragment against alias `m`
 //     dataset type is SINGULAR 'message' (the table is plural)
 const { data: search } = await api.datasets.createUserSearch(
   tenantSlug, datalakeSlug, 'message',
-  { search_query: `rm.status = 'failed' AND rm.channel = 'sms'` },
+  { search_query: `m.status = 'failed' AND m.channel = 'sms'` },
 )
 // (2) page through it
 const { data: page } = await api.datasets.search(
   tenantSlug, datalakeSlug, 'message',
-  { userSearchId: search.id, dataAccessMode: 'unregulated' },
+  { userSearchId: search.id, dataAccessMode: 'tokenized' },
 )
 ```
 
 Filterable columns (Flop, the full set): `id`, `inserted_at`,
 `direction`, `channel`, `status`, `sender_type`, `body`, `subject`,
-`mdm_subject_id`, `sender_id`, `sent_at`, `queued_at`, `delivered_at`,
+`legal_entity_id`, `sender_id`, `sent_at`, `queued_at`, `delivered_at`,
 `thread_id`, `external_id`, `global_search`.
 
 **`decision_key` is NOT in the Flop-filterable set** — you cannot
 `?filter[decision_key]=…` (nor can the workflow-run-log endpoints; see
 §4). But you CAN still scope a search by it two other ways, both
-cookbook-proven: put `rm.decision_key = '…'` in the `createUserSearch`
+cookbook-proven: put `m.decision_key = '…'` in the `createUserSearch`
 **`search_query`** SQL WHERE fragment (as the SMS-workflow cookbooks
-do), or `GROUP BY rm.decision_key` in `executeSql` for analytics (§4).
+do), or `GROUP BY m.decision_key` in `executeSql` for analytics (§4).
 The Flop bracket-filter and the raw-SQL surfaces are different lanes —
 `decision_key` lives only on the SQL lane.
 
-`dataAccessMode: 'regulated'` returns raw content; `'unregulated'`
-returns tokenized objects for content columns (see
-`data_activation_clients.md` §6.5 for the shape).
+`dataAccessMode` selects which lake answers: `'raw'` returns the real
+content, `'tokenized'` returns a stable `tok_<hash>` per masked column,
+and `'redacted'` returns an unjoinable placeholder. All three return
+**plain values of the column's own type** — a masked column is a string,
+not a wrapper object.
 
 ## 4. Campaign math (the dashboard recipe)
 
 "How did campaign X do?" — where X is one run's `batch_id`:
 
 ```
-   action_logs (ral)  — has batch_id + external_id
+   action_logs (al)  — has batch_id + external_id
         │ join on external_id
         ▼
-   messages (rm)      — has status + engagement timestamps
+   messages (m)      — has status + engagement timestamps
 ```
 
 ```sql
 SELECT
   count(*)                                            AS sent,
-  count(*) FILTER (WHERE rm.status = 'delivered')     AS delivered,
-  count(*) FILTER (WHERE rm.status = 'failed')        AS undelivered,
-  count(*) FILTER (WHERE rm.opened_at IS NOT NULL)    AS opened,
-  count(*) FILTER (WHERE rm.status = 'clicked')       AS clicked
-FROM action_logs ral
-JOIN messages rm ON rm.external_id = ral.external_id
-WHERE ral.batch_id = '<batch_id>'
+  count(*) FILTER (WHERE m.status = 'delivered')     AS delivered,
+  count(*) FILTER (WHERE m.status = 'failed')        AS undelivered,
+  count(*) FILTER (WHERE m.opened_at IS NOT NULL)    AS opened,
+  count(*) FILTER (WHERE m.status = 'clicked')       AS clicked
+FROM action_logs al
+JOIN messages m ON m.external_id = al.external_id
+WHERE al.batch_id = '<batch_id>'
 ```
 
 Run it with `api.datalakes.executeSql` (read-only tier). Delivered
@@ -211,8 +213,8 @@ merged NDJSON artifact (see `action_logs.md` §5).
 
 ### The message log IS your per-variant analytics table
 
-Every message row (both the regulated and unregulated tier) carries
-the full provenance of the send:
+Every message row, in all three lakes, carries the full provenance of
+the send:
 
 ```
 decision_key   which action fired — the A/B variant key
@@ -220,7 +222,7 @@ channel        sms | email | voice | web_form | push
 status         delivery state
 delivered_at   when the carrier confirmed
 opened_at      engagement (from updateMessageTracking)
-workflow_id, action_id, sender_tool_id, mdm_subject_id
+workflow_id, action_id, sender_tool_id, legal_entity_id
 ```
 
 So "how did variant A do vs variant B?" or "SMS vs email open rate?"
@@ -229,15 +231,15 @@ is a plain `GROUP BY` over the datalake `messages` table via
 
 ```sql
 SELECT
-  rm.decision_key,
-  rm.channel,
+  m.decision_key,
+  m.channel,
   count(*)                                          AS sent,
-  count(*) FILTER (WHERE rm.status = 'delivered')   AS delivered,
-  count(*) FILTER (WHERE rm.status = 'failed')      AS failed,
-  count(*) FILTER (WHERE rm.opened_at IS NOT NULL)  AS opened
-FROM messages rm
-GROUP BY rm.decision_key, rm.channel
-ORDER BY rm.decision_key, rm.channel
+  count(*) FILTER (WHERE m.status = 'delivered')   AS delivered,
+  count(*) FILTER (WHERE m.status = 'failed')      AS failed,
+  count(*) FILTER (WHERE m.opened_at IS NOT NULL)  AS opened
+FROM messages m
+GROUP BY m.decision_key, m.channel
+ORDER BY m.decision_key, m.channel
 ```
 
 Scope it to one campaign run by joining `action_logs` (which carries
@@ -282,7 +284,7 @@ per-channel reporting.
    `opened_at` from an earlier attempt in the thread — read both.
 
 4. **`status: 'invalidated'` is the idempotency guard firing** —
-   the same `(mdm_subject_id, idempotency_key)` already sent. Not
+   the same `(legal_entity_id, idempotency_key)` already sent. Not
    an error; usually exactly what you want.
 
 5. **Delivery events that don't match are dropped silently.** The

package/.agent/mock-services.md

@@ -71,7 +71,7 @@ after one:
 
 ```bash
 AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 \
-  aws s3 mb s3://healthcare-lake-regulated --endpoint-url http://localhost:4566
+  aws s3 mb s3://healthcare-lake --endpoint-url http://localhost:4566
 ```
 
 ## The hosted mock — `wiremock.alvera.ai`

package/.agent/mutations.md

@@ -37,9 +37,9 @@ const { data: current } = await api.tools.get(
 // 2. change in memory
 const next = { ...current, status: 'inactive' }
 
-// 3. send the whole body back
+// 3. send the whole body back. The cast is required — see below.
 const { data: updated } = await api.tools.update(
-  tenantSlug, datalakeSlug, toolId, next,
+  tenantSlug, datalakeSlug, toolId, next as unknown as ToolRequestWritable,
 )
 ```