@alvera-ai/platform-sdk 0.18.2 → 0.19.2-next.g845dfdf

package/.agent/ai_sandbox.md

@@ -157,7 +157,7 @@ trail this trap leaves.
 
 SQL is the second consumer-author surface: WHERE clauses on
 dataset searches (`api.datasets.createUserSearch.search_query`,
-see `data_activation_clients.md` §6.5). Liquid renders some of
+see `data_activation_clients.md` §6.6). Liquid renders some of
 these from templates; others arrive directly as raw SQL
 fragments. Either path lands at the same boundary.
 
@@ -165,7 +165,7 @@ fragments. Either path lands at the same boundary.
 
 - SELECT against the tables exposed by the dataset search aliases
   (`le` for legal entities, `m` for messages, `al` for action logs
-  — see `data_activation_clients.md` §6.5 SQL aliases).
+  — see `data_activation_clients.md` §6.6 SQL aliases).
 - Filter results into the platform's `search_results`
   accumulator scoped to the materialised search id. This is the
   one write the query path performs, and the platform builds it
@@ -305,5 +305,5 @@ guarantees it captures back-stop Layer 1.
 - `account_management.md` §3 — session role vocabularies (Layer 1)
 - `interoperability_contracts.md` §2 — template_config body shape (Layer 2)
 - `workflows.md` gotcha 9 — the `| to_json` vs `| json` trap (Layer 2)
-- `data_activation_clients.md` §6.5 — dataset search SQL aliases (Layer 3)
+- `data_activation_clients.md` §6.6 — dataset search SQL aliases (Layer 3)
 - `mdm.md` — verification surface that composes with Layer 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