@alvera-ai/platform-sdk 0.18.1 → 0.18.2-next.g6192a5c

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,8 +221,8 @@ 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,

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,8 +228,8 @@ 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,

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,8 +234,8 @@ 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,

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,8 +249,8 @@ 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,
@@ -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).**

package/.agent/workflows.md

@@ -492,6 +492,73 @@ actions                      required array — inline; replace-on-PUT
 workflow_ai_agents          optional array — inline; replace-on-PUT (see §3)
 ```
 
+Caller-supplied fields **inside each `context_datasets[*]`** row:
+
+```
+dataset_type                 required string — CLOSED ENUM, not free text. An
+                                              arbitrary value 422s at apply and
+                                              the error enumerates the allowed
+                                              types
+generic_table_id             required UUID when dataset_type == 'generic_table';
+                                              omit otherwise. NOT the same field
+                                              as the workflow's own
+                                              `generic_table_id` one level up
+where_clause                 optional string — Liquid, max 10_000 chars (see
+                                              below for what it can reach, and
+                                              which tier it runs against)
+limit                        optional int   — must be positive
+position                     optional int   — default 0
+```
+
+### Reading what a context query returned
+
+`additional_context.<dataset_type>` — the `dataset_type` string **literally**,
+not the table name and not a slug. A `document` context is read at
+`additional_context.document`.
+
+Do not confuse this with the AI-agent form documented above
+(`additional_context.<agent_slug>.<field>`): an agent is keyed by its slug, a
+context dataset by its type.
+
+### ⚠ Two context datasets of the same `dataset_type` silently overwrite
+
+The loader accumulates them into a map keyed by `dataset_type`, so declaring
+two of the same type leaves **only the last one**. There is no error and no
+warning — the workflow runs happily against the wrong context. If you need two
+slices of one type, express it as one query with a wider `where_clause`.
+
+### The `where_clause` reaches the row differently than the filter does
+
+This asymmetry is the easiest thing here to get wrong:
+
+```
+where clause   {{ <dataset_type>.field }}      e.g. {{ generic_table.external_client_id }}
+filter         {{ event_dataset.field }}       the SAME row, different accessor
+```
+
+That makes three conventions for "the current row" across this corpus — the
+third being `msg.row.x` in an interoperability filter versus `msg.x` in its
+transform. Nothing about a name tells you which one you are in; the surface you
+are authoring does.
+
+### Context queries run against the REGULATED tier
+
+The loader reads context in regulated mode, so a `where_clause` must name the
+**regulated** table alias (e.g. `regulated_alvera_custom_unsubscribe_list`),
+not the unregulated name. This changes every where clause you write, and a
+clause written against the unregulated name finds nothing rather than failing
+loudly.
+
+### `context_datasets` cannot be cleared by omission
+
+It is a **required, replace-on-PUT array**. Dropping the block from a manifest
+does not clear it: the server retains what was last deployed, the rendered and
+deployed checksums never converge, and every subsequent `plan` reports drift on
+a config that was just applied. Send an explicit `[]` to mean "no context".
+
+Same class as the `assume_role_external_id` convergence note — an omission that
+reads as "leave it alone" on the wire and as "remove it" in the author's head.
+
 Caller-supplied fields **inside each `actions[*]`** row:
 
 ```

package/README.md

@@ -111,7 +111,7 @@ block of the committed OpenAPI spec and exported as `ENVIRONMENTS`:
 import { ENVIRONMENTS, DEFAULT_ENVIRONMENT } from '@alvera-ai/platform-sdk'
 
 ENVIRONMENTS.local.base_url // http://localhost:4000
-ENVIRONMENTS.demo.base_url  // https://platform-hh.alvera.ai
+ENVIRONMENTS.demo.base_url  // https://demo.alvera.ai
 ENVIRONMENTS.prod.base_url  // https://app.alvera.ai
 
 DEFAULT_ENVIRONMENT // 'prod'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alvera-ai/platform-sdk",
-  "version": "0.18.1",
+  "version": "0.18.2-next.g6192a5c",
   "description": "Typed SDK for the Alvera platform API — manage data sources, tools, generic tables, AI agents, and action status updaters.",
   "type": "module",
   "sideEffects": false,