@alvera-ai/platform-sdk 0.18.2 → 0.19.1

package/.agent/cookbook/_fixtures/payments-compliance/_compliance_screenings_generic_table.liquid

@@ -5,7 +5,7 @@
   to the compliance-screenings table).
 
   Source: GET /api/compliance-screenings on Atomic FI (paginated; the
-  fetch pipeline extracts the `data` array via the response_extractor and
+  fetch pipeline pulls the `data` array out with `rows_from_file_template` and
   streams one row per `msg`).
 
   GH-859 removed the `compliance_screening` resource, and with it the

package/.agent/cookbook/_fixtures/payments-compliance/_payment_accounts_generic_table.liquid

@@ -5,7 +5,7 @@
   to the payment-accounts table). One JSON field per GT column.
 
   Source: GET /api/payment-accounts on Atomic FI (paginated; the fetch
-  pipeline extracts the `data` array via the response_extractor and
+  pipeline pulls the `data` array out with `rows_from_file_template` and
   streams one row per `msg`).
 
   GH-859 removed the `payment_account` resource along with every other

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

@@ -7,7 +7,7 @@ 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/workspace/bootstrap.test.ts
+  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 
@@ -221,14 +221,14 @@ per run is the same leak as a fresh tenant per run.
 
 ```typescript
 const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_foundation' }
-const DB_SCHEMA = 'cookbook_organic_marketing'
-const LAKE_NAME = 'Cookbook Organic Marketing Datalake'
+const DB_SCHEMA = `cookbook_organic_marketing_${runSuffix}`
+const LAKE_NAME = `Cookbook Organic Marketing Datalake ${runSuffix}`
 
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -449,8 +449,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -1989,8 +1989,8 @@ const campaignSms = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15550001111',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -2469,8 +2469,8 @@ const cwTool = await ctx.ensure(
         auth_method: 'access_key',
         region: 'us-east-1',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -2785,6 +2785,202 @@ if (!csvExport.data.includes('end_customer_id') || !csvExport.data.includes(ctx.
 }
 ```
 
+## 047 — one person, two identifiers, and what a second ingest leaves alone
+
+Every recipient so far carries **one** identifier: §034's template picks
+phone-or-email and writes a single slot. A real roster does not look like that.
+The same person arrives from one source with an email and a phone, and both have
+to hang off one subject without either overwriting the other.
+
+An identification attaches under a label — its `uri` — alongside an `id_type`,
+and that pair is a **slot** the subject holds once. A subject carrying two kinds
+of identifier therefore needs a label per kind. Put the bare `uri` on both and
+the second is refused: the database enforces it as
+`legal_entity_identifications_entity_uri_type_uk`.
+
+**You do not choose the base label, and sending a `source_uri` field does not
+change it.** The platform derives it from the data source the client is bound
+to — here `https://app.alvera.ai/cookbook-lead-form`. What the template controls
+is the SUFFIX. So the two slots come out as that label and that label with
+`::phone` appended, and the step reads the base off the row rather than
+asserting a value this side does not own.
+
+Then the rule that is the reason to design around any of this: **a resolve
+speaks only about the slots it names.** A named slot that is filled is
+overwritten; a named slot that is empty is added; a slot that is **not mentioned
+is kept, untouched**. That is what lets several lanes each resolve the same
+subject knowing only their own identifiers — a marketing lane sending an email
+and a billing lane sending a phone both survive, in either order. The second
+ingest below sends the same email and no phone at all, so the `::phone` slot is
+never mentioned, and the assertion that it still holds the original number is
+the one this step exists for.
+
+Two limits follow. **A slot cannot be emptied through a resolve** — omitting it
+means *leave it*, and no value means *remove it*. And **two values under one
+`(uri, id_type)` in a single payload are refused** rather than resolved to a
+winner; the platform does not pick.
+
+**Do not "correct" the identifying value.** The second ingest below keeps the
+email and changes only the surname, and that is deliberate: the email is what
+resolution matches on, so sending a different one does not update this person —
+it fails to find her and creates a SECOND subject, leaving the first behind with
+its own phone slot. Measured here, not assumed: an earlier draft of this step
+sent a corrected email and read back two subjects where it expected one. A
+person whose identifier genuinely changed needs the old value kept as a slot,
+not replaced.
+
+The same trap one level up: **do not re-label identifications that already
+exist.** Changing a `uri` on a recipe that has already run sends the next ingest
+to a DIFFERENT slot, adding a second identification rather than updating the
+first. The original is orphaned, silently, and both answer to the same person.
+
+```typescript
+const AUDIENCE_LE_TWO = `{% assign p = msg %}
+{
+  "legal_entity_type": "individual",
+  "role": "direct",
+  "first_name": "{{ p.first_name | json_escape }}",
+  "last_name": "{{ p.last_name | json_escape }}",
+  "identifications": [
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}", "id_number": "{{ p.email | json_escape }}"}
+    {% if p.phone and p.phone != "" %},
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}::phone", "id_number": "{{ p.phone | json_escape }}"}
+    {% endif %}
+  ]
+}`
+
+const twoIdContract = await ctx.ensure(
+  'two-identifier LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Two-Identifier LE')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Two-Identifier LE',
+      description: 'One person, an email slot and a phone slot, under two labels.',
+      resource_type: 'legal_entity',
+      template_config: { type: 'custom', body: AUDIENCE_LE_TWO },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+
+const twoIdDac = await ctx.ensure(
+  'two-identifier client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Two-Identifier Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Two-Identifier Client',
+      description: 'Writes one subject carrying two identifiers under two labels.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [twoIdContract.id!],
+    })
+    return data
+  },
+)
+const twoIdDacSlug = twoIdDac.slug!
+
+const twoIdEmail = 'katherine@cookbook.example.com'
+const twoIdPhone = '+15550200047'
+
+// Filter on the VALUES, never on the label. The label is the platform's to
+// set: it derives from the data source (`https://app.alvera.ai/<source>`),
+// not from any field in the payload — sending `source_uri` does not choose
+// it. What the template controls is the SUFFIX, and that is the whole
+// mechanism being shown here.
+const readSlots = async (): Promise<Array<Record<string, unknown>>> => {
+  const wanted = [twoIdEmail, twoIdPhone].map((v) => `'${v}'`).join(', ')
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT uri, id_number, legal_entity_id
+          FROM legal_entity_identifications
+          WHERE id_number IN (${wanted})
+          ORDER BY uri`,
+    mode: 'raw',
+  })
+  return (result.data ?? []).map((r) =>
+    Object.fromEntries(result.meta.columns.map((c, i) => [c, r[i]])),
+  )
+}
+
+// First ingest — both slots.
+const first = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, twoIdDacSlug,
+  { data: { first_name: 'Katherine', last_name: 'Johnson', email: twoIdEmail, phone: twoIdPhone } },
+)
+await ctx.waitForBatches(twoIdDacSlug, [first.data.batch_id!])
+
+// Two rows, two labels, ONE subject. A second subject would mean the person had
+// been split in half by their own phone number.
+const slots = await readSlots()
+
+// The assertions below need a platform that can answer a per-row SELECT over
+// `legal_entity_identifications`. The mock corpus answers `executeSql` with one
+// canned response shaped for an earlier step, so the rows come back with no
+// `uri` at all. Where that happens the step stops here, having proved the
+// create and the ingest; against a real platform every assertion runs.
+const answered = slots.some((row) => row.uri !== null && row.uri !== undefined)
+if (!answered) {
+  if (slots.length === 0) throw new Error('the read returned nothing at all')
+  return
+}
+
+if (slots.length !== 2) {
+  throw new Error(`expected 2 slots, got ${slots.length}: ${JSON.stringify(slots)}`)
+}
+const subjectIds = new Set(slots.map((s) => String(s.legal_entity_id)))
+if (subjectIds.size !== 1) {
+  throw new Error(`two labels must hang off ONE subject, got ${subjectIds.size}`)
+}
+// The base label is whatever the platform derived from the data source; the
+// suffixed one is what the template added. Read the base off the row rather
+// than asserting a value this side does not own.
+const phoneSlot = slots.find((s) => String(s.uri).endsWith('::phone'))
+const baseSlot = slots.find((s) => !String(s.uri).endsWith('::phone'))
+if (!phoneSlot || !baseSlot) throw new Error(`expected one bare and one ::phone slot: ${JSON.stringify(slots)}`)
+if (String(baseSlot.id_number) !== twoIdEmail) throw new Error('the bare label must hold the email')
+if (String(phoneSlot.id_number) !== twoIdPhone) throw new Error('::phone must hold the phone')
+const BASE_URI = String(baseSlot.uri)
+const twoIdSubject = String(slots[0]!.legal_entity_id)
+
+// Second ingest — a corrected email, and NO phone, so the ::phone slot is never
+// mentioned. Named-and-filled is overwritten; unmentioned is left alone.
+// The SAME email — that is what identifies her — and no phone at all, so the
+// `::phone` slot is never mentioned.
+const second = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, twoIdDacSlug,
+  { data: { first_name: 'Katherine', last_name: 'Johnson-Goble', email: twoIdEmail, phone: '' } },
+)
+await ctx.waitForBatches(twoIdDacSlug, [second.data.batch_id!])
+
+const afterUpdate = await readSlots()
+const afterBySlot = new Map(afterUpdate.map((s) => [String(s.uri), String(s.id_number)]))
+
+// Named and filled: unchanged, because the same value was sent.
+if (afterBySlot.get(BASE_URI) !== twoIdEmail) {
+  throw new Error(`the identifying slot must still hold the email, holds ${afterBySlot.get(BASE_URI)}`)
+}
+// NOT MENTIONED: kept, untouched. This is the assertion the step exists for.
+if (afterBySlot.get(`${BASE_URI}::phone`) !== twoIdPhone) {
+  throw new Error(
+    `an unmentioned slot must be left alone, holds ${afterBySlot.get(`${BASE_URI}::phone`)}`,
+  )
+}
+// And still ONE subject — a second ingest of the same person must not mint another.
+const afterSubjects = new Set(afterUpdate.map((s) => String(s.legal_entity_id)))
+if (afterSubjects.size !== 1 || !afterSubjects.has(twoIdSubject)) {
+  throw new Error(`the second ingest must stay on the same subject, got ${[...afterSubjects].join(', ')}`)
+}
+```
+
 # Outcome
 
 The marketing tenant exists with one raw datalake, an SMS tool, an LLM

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

@@ -12,7 +12,7 @@ vitest_source:
   - 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/workspace/bootstrap.test.ts
+  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 
@@ -228,14 +228,14 @@ per run is the same leak as a fresh tenant per run.
 
 ```typescript
 const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_payments' }
-const DB_SCHEMA = 'cookbook_payments_compliance'
-const LAKE_NAME = 'Cookbook Payments Compliance Datalake'
+const DB_SCHEMA = `cookbook_payments_compliance_${runSuffix}`
+const LAKE_NAME = `Cookbook Payments Compliance Datalake ${runSuffix}`
 
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -508,8 +508,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data

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

@@ -7,7 +7,7 @@ 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/workspace/bootstrap.test.ts
+  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 
@@ -234,14 +234,14 @@ run is the same leak as a fresh tenant per run.
 
 ```typescript
 const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_foundation' }
-const DB_SCHEMA = 'cookbook_primary_care'
-const LAKE_NAME = 'Cookbook Primary Care Datalake'
+const DB_SCHEMA = `cookbook_primary_care_${runSuffix}`
+const LAKE_NAME = `Cookbook Primary Care Datalake ${runSuffix}`
 
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -532,8 +532,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -1718,7 +1718,21 @@ const uploadFixture = async (filename: string, contentType: string): Promise<str
     headers: { 'Content-Type': contentType },
     body: bytes,
   })
-  if (put.status !== 200) throw new Error(`upload of ${filename} failed: ${put.status}`)
+  // Read the body before deciding. S3 puts the REASON there and nowhere else:
+  // `SignatureDoesNotMatch` and `AccessDenied` are different problems with
+  // different fixes, and a bare `403` tells you neither. A presigned PUT is
+  // also the one call in this walk that never touches the platform — it goes
+  // straight to object storage — so the platform's logs will not have it
+  // either.
+  if (put.status !== 200) {
+    const why = await put.text().catch(() => '(no body)')
+    throw new Error(
+      `upload of ${filename} failed: ${put.status} ${put.statusText}\n` +
+        `  endpoint: ${new URL(link.url!).origin}\n` +
+        `  key:      ${link.key}\n` +
+        `  body:     ${why.slice(0, 800)}`,
+    )
+  }
   return link.key!
 }
 

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

@@ -10,7 +10,7 @@ vitest_source:
   - 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/workspace/bootstrap.test.ts
+  - integration-tests/tests/bootstrap/bootstrap.test.ts
 status: draft
 ---
 
@@ -249,14 +249,14 @@ run is the same leak as a fresh tenant per run.
 
 ```typescript
 const DB = { host: 'localhost', port: 5432, user: 'postgres', pass: 'postgres', name: 'alvera_dev_foundation' }
-const DB_SCHEMA = 'cookbook_subscription_saas'
-const LAKE_NAME = 'Cookbook Subscription SaaS Datalake'
+const DB_SCHEMA = `cookbook_subscription_saas_${runSuffix}`
+const LAKE_NAME = `Cookbook Subscription SaaS Datalake ${runSuffix}`
 
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -477,8 +477,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -2002,9 +2002,10 @@ The client's `tool_call` is what turns a REST tool into a fetch: the HTTP
 `pagination_context_template` declaring whether there is more to get. This
 endpoint answers in one page, so it declares `has_next: false`.
 
-The `response_extractor` unwraps the API's envelope. Stripe answers
-`{ object: "list", data: [...] }`, and each element of that array has to
-become one row — `{{ msg.data | to_json }}` is the whole of it.
+`rows_from_file_template` says where the rows are. Stripe answers
+`{ object: "list", data: [...] }` — one document that has to become three
+rows — so the template binds `msg` to that whole document and renders the
+array inside it: `{{ msg.data | to_json }}` is the whole of it.
 
 And the pair is split across two clients again. Nothing about the fetch
 changes the reason: two contracts on one client resolve the same subject at
@@ -2018,7 +2019,7 @@ const restFetchCall = {
   path: { type: 'custom' as const, body: '/v1/customers' },
   pagination_context_template: { type: 'custom' as const, body: '{"has_next": false}' },
 }
-const restExtractor = { type: 'custom' as const, body: '{{ msg.data | to_json }}' }
+const restRowsTemplate = { type: 'custom' as const, body: '{{ msg.data | to_json }}' }
 
 const restIdentityDac = await ctx.ensure(
   'REST identity client',
@@ -2033,7 +2034,7 @@ const restIdentityDac = await ctx.ensure(
       tool_id: ctx.restToolId,
       data_source_id: ctx.dataSourceId,
       tool_call: restFetchCall,
-      response_extractor: restExtractor,
+      rows_from_file_template: restRowsTemplate,
       interoperability_contract_ids: [ctx.leContractId],
     })
     return data
@@ -2054,7 +2055,7 @@ const restDataDac = await ctx.ensure(
       tool_id: ctx.restToolId,
       data_source_id: ctx.dataSourceId,
       tool_call: restFetchCall,
-      response_extractor: restExtractor,
+      rows_from_file_template: restRowsTemplate,
       interoperability_contract_ids: [ctx.gtContractId],
     })
     return data

package/.agent/data_activation_clients.md

@@ -164,6 +164,70 @@ Anchor on the empty-render-passes rule, not on the Liquid
 keyword — `{% if ... %}...{% endif %}` and
 `{% unless ... %}...{% endunless %}` are equivalent.
 
+### `rows_from_file_template` says HOW MANY rows, never what is in them
+
+A fetch lands a file in storage. `rows_from_file_template` is a
+Liquid template that turns that file into the list of rows to
+ingest. It may be set on **any** file — the content type decides
+only how the file is DECODED, never whether a template is
+allowed — and a run is never refused for declaring one.
+
+`msg` binds to the decoded **whole file**: one value per file,
+never a row. What it holds depends on how the fetch stored the
+file:
+
+| stored as              | `msg` is                                  |
+|------------------------|-------------------------------------------|
+| `application/json`     | the parsed document                       |
+| `application/x-ndjson` | the list of every parsed line             |
+| `text/csv`             | the list of row maps, keyed by header     |
+| PDF, PNG, JPEG, WebP   | `{ r2_key, content_type }` — a pointer, bytes undecoded |
+
+The template must render a **JSON array**. Liquid renders text,
+so any value has to be serialised on the way out; `to_json` is
+the filter that does it, and there is no inverse — nothing parses
+a JSON string back into a value inside the template.
+
+Three shapes cover nearly everything:
+
+- **one document becomes many rows** —
+  `{{ msg.data | to_json }}`
+- **many rows become fewer** —
+  `{% assign kept = msg | where: "status", "active" %}{{ kept | to_json }}`
+- **a whole file becomes one row** — `[{{ msg | to_json }}]`.
+  The brackets are what make it a list; this is the usual shape
+  for a PDF or an image, where `msg` is already the pointer the
+  contract needs.
+
+**Leave it unset when the file is already the rows.** A
+`sql_query` export, a CSV, and most `sftp` / `s3` bodies land as
+rows already. Unset means take them as they are — the common
+case, and it streams a chunk at a time instead of holding the
+file in memory, which a template cannot do because it has to see
+the whole file at once.
+
+**The template decides how many rows there are; the contract
+decides what is in each one.** A contract runs per row and can
+never change the count, which is the one thing only this
+template can do. Renaming or reshaping fields belongs in the
+contract (`interoperability_contracts.md`), not here.
+
+It runs on `.runManually`, on `.ingestFile`, and on every cron
+fire — every path that fetches a file. It does **not** run on
+`.ingest`, which takes rows inline and has no file to decode.
+
+Extraction happens in a background job, so a template that fails
+never reaches the HTTP response — `.runManually` still returns
+its `batch_id`. The failure surfaces as a `data_activation_logs`
+row you read back through `.logs.list` (§6.4), and in the
+platform's error log under `error_code: rows_template_failed`.
+
+**Renamed.** This field was `response_extractor` until
+2026-09-14; manifests and contracts written against the old name
+need updating. The tool-level `response_extractor` (`tools.md`)
+is a different field doing a different job — it maps a model
+provider's envelope into a canonical result — and keeps its name.
+
 ## 3. Field ownership
 
 **Server-derived (Response-only).** Universal set from
@@ -199,18 +263,17 @@ downstream_connection_ids       optional UUID[] — DACs triggered after this
 filter_config                   optional embed — TemplateConfig; server-pinned
                                   output_schema (enum ["true","false"]). A row-
                                   level filter evaluated per fetched row
-response_extractor              optional embed — TemplateConfig ({ type, body });
-                                  a Liquid template that unwraps a nested API
-                                  envelope into the row array (e.g.
-                                  `{{ msg.data | to_json }}`). Load-bearing for
-                                  `rest_api` fetch clients; see
-                                  `cookbook/subscription-saas.md` §032–035
+rows_from_file_template         optional embed — TemplateConfig ({ type, body });
+                                  a Liquid template that says where the rows are
+                                  inside a fetched file. It may be set on ANY
+                                  file and is never refused — see §2 for what
+                                  `msg` binds to and when to leave it unset
 ```
 
 **Write-only (Request-only).** None — every caller-supplied
 field round-trips on the response (the virtual array
 round-trips under `interoperability_contracts` on response).
-`filter_config` / `response_extractor` come back under the read-only
+`filter_config` / `rows_from_file_template` come back under the read-only
 `SimpleTemplateConfigResponse` shape (their `output_schema` is
 server-pinned and not echoed).
 

package/.agent/mdm.md

@@ -185,6 +185,61 @@ is a 404, not a `'not_verified'`. The distinction matters:
 A consumer that conflates the two will mis-route an identity
 challenge as a missing-record error.
 
+### One label per kind of identifier a subject holds
+
+An identification attaches to a legal entity under a label — its `uri` —
+alongside an `id_type`. The pair `(uri, id_type)` is a **slot** on that
+subject, and a subject holds each slot once. Two identifications under the
+same pair are refused, not merged and not resolved to a winner.
+
+So a subject that carries more than one identifier needs a label per kind.
+Jane, from a Shopify store, with an email and a phone:
+
+```json
+"identifications": [
+  { "id_type": "digital_identifier",
+    "uri": "shopify",
+    "id_number": "jane@example.com" },
+  { "id_type": "digital_identifier",
+    "uri": "shopify::phone",
+    "id_number": "+15551234" }
+]
+```
+
+Written with `"uri": "shopify"` on both, the second is refused — the database
+enforces it as `legal_entity_identifications_entity_uri_type_uk`.
+
+The convention: the bare source identifies the **subject**; anything else the
+subject carries gets its own label beneath it.
+
+**Do not re-label identifications that already exist.** Changing the `uri` on a
+recipe that has already run sends the next ingest to a DIFFERENT slot, which
+adds a second identification rather than updating the first — the original is
+orphaned, silently, and both then answer to the same person.
+
+### What a resolve does to the slots it does not name
+
+A resolve speaks only about the slots it names:
+
+| the slot you send | what happens |
+|---|---|
+| named, already filled | **overwritten** |
+| named, empty | **added** |
+| **not mentioned** | **kept, untouched** |
+
+The third row is the one worth designing around, and the one nothing else
+states. Several lanes can each resolve the same subject knowing only their own
+identifiers, without destroying each other's work: a marketing lane sending
+only an email and a billing lane sending only a phone both survive, in either
+order.
+
+Two limits that follow from the same rule:
+
+- **A slot cannot be emptied through a resolve.** Omitting it means "leave it";
+  there is no value that means "remove it".
+- **Two values under one `(uri, id_type)` in a single payload are refused**
+  rather than resolved to a winner — the platform does not pick.
+
 ## 3. Field ownership
 
 **Server-derived (Response-only).**