@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/.agent/connected_apps.md

@@ -0,0 +1,407 @@
+# Connected apps
+
+A **connected app** is an external web application registered with
+the platform — typically a customer-facing forms portal hosted on
+Cloudflare Workers / Pages or any other deployment target. The
+platform mints magic links into the app from workflow actions:
+each action renders a URL of the form
+
+```
+   https://<app-primary-url>/t/<short_path>
+```
+
+The customer clicks the link, lands on a route the app discovered
+via `/.well-known/routes.json`, and the app calls back to the
+platform to resolve the page (fetch the underlying message + its
+metadata) and update tracking (opened_at, form_submitted_at).
+
+SDK namespace: `api.connectedApps`.
+
+The namespace splits into **two roles**:
+
+- **Datalake-scoped management** — the admin side. CRUD on the
+  connected-app row, route discovery + sync. Uses the app's
+  UUID `id` as the path key.
+- **Tenant-scoped runtime** — the consumer side. Called BY the
+  connected app itself (authenticated with its auto-provisioned
+  machine-to-machine API key) when a customer hits a magic link. Uses the app's
+  `slug` as the path key.
+
+Connected apps are **Datalake-DB-resident** — the parent datalake
+must be `status: 'ready'` before POST.
+
+## 1. Wire shape
+
+```typescript
+import type {
+  ConnectedAppResponse,
+} from '@alvera-ai/platform-sdk'
+
+const { data: created } = await api.connectedApps.create(
+  tenantSlug,
+  datalakeSlug,
+  {
+    name: 'The Doctors Center',
+    description: 'Patient-facing forms portal',
+    mode: 'self_hosted',                              // 'self_hosted' (only mode active today; see §2)
+    urls: [
+      {
+        url: 'https://the-doctors-center.pages.dev',  // app's deployed origin
+        is_primary: true,                             // exactly one URL must be primary
+        label: 'Production',
+      },
+    ],
+  },
+)
+// created.id, created.slug         — server-derived
+// created.status                   === 'pending' (transient) → 'synced' after route fetch
+// created.api_key_id               — auto-provisioned M2M key id (see §2)
+// created.routes                   — array populated from .well-known/routes.json
+//                                     (empty until first sync)
+// created.last_synced_at           — set when routes successfully validated
+```
+
+The platform validates `/.well-known/routes.json` at the primary
+URL during create. If validation succeeds, routes are saved and
+the status flips to `'synced'`. If it fails, the row persists
+with `status: 'error'` and the failure message in `error`.
+
+## 2. Rules the type cannot encode
+
+### URLs: at least one, exactly one primary
+
+The `urls` array requires at least one entry, and **exactly one
+entry must have `is_primary: true`**. The primary URL is the host
+the platform fetches `/.well-known/routes.json` from and the
+host that magic links are rooted at. Submitting zero primaries
+or multiple primaries returns a 422 on `/urls`.
+
+Additional URLs (staging, preview) are stored for reference but
+aren't used for route discovery or link minting.
+
+### Route discovery is automatic + re-triggerable
+
+```
+/.well-known/routes.json   served by the connected app at its primary URL.
+                            Must return application/json with a JSON array
+                            of route objects:
+
+[
+  { "name": "Review Form",  "path": "/forms/review", "description": "..." },
+  { "name": "CAHPS Survey", "path": "/forms/cahps",  "description": "..." }
+]
+```
+
+Validation rules at fetch time:
+
+- Response content-type must be `application/json`
+- Body must be a JSON array
+- Each route requires `name` (string) and `path` (string);
+  `description` is optional
+
+The platform fetches the manifest at two moments:
+
+1. **At create time** — automatic. Failure flips the row to
+   `status: 'error'` (the row still persists; routes stay empty).
+2. **On explicit `.syncRoutes(id)`** — operator-triggered re-fetch.
+   Updates the saved routes and `last_synced_at`.
+
+The SDK does NOT auto-re-sync routes on a schedule. Re-sync is
+deliberate.
+
+### Modes: only `self_hosted` is active today
+
+```
+mode: 'self_hosted'   active — operator runs the deployment
+                       themselves (e.g. `wrangler deploy`); the
+                       platform registers the resulting URL and
+                       discovers routes from it.
+mode: 'managed'       reserved for a future Cloudflare-Pages
+                       auto-deploy flow. Not provisioned at
+                       runtime today — submitting it succeeds
+                       structurally but no deploy fires.
+```
+
+Treat `'self_hosted'` as the only practical choice for current
+consumers.
+
+### machine-to-machine API key is auto-provisioned
+
+Creating a connected app automatically provisions a machine-to-
+machine API key named `ConnectedApp: <app name>` with the `api`
+role. The key is exposed on the response once (typically rendered
+in the create-flow UI) so the operator can configure it as a
+secret in the deployed app's environment. The platform stores only
+the key's id (`api_key_id` on the response).
+
+The connected app deployment should be configured with:
+
+```
+ALVERA_API_KEY="<auto-provisioned key>"
+ALVERA_DATALAKE_ID="<datalake-uuid>"
+ALVERA_API_URL="https://<platform-host>"
+```
+
+Deleting the connected app deletes the API key.
+
+### `slug` is the runtime reference; `id` is the admin reference
+
+Management endpoints (`list`, `get`, `update`, `syncRoutes`,
+`metadataDetails`) take the UUID `id` as the path key — the
+datalake-scoped admin context.
+
+Runtime endpoints (`resolvePage`, `updateMessageTracking`) take
+the `slug` and skip the datalake path segment entirely. This is
+deliberate: the connected app deployment is authenticated with
+the tenant-scoped machine-to-machine API key and may not know which datalake
+its row lives under.
+
+## 3. Field ownership
+
+**Server-derived (Response-only).** Universal set from
+`type_naming.md`, plus:
+
+```
+status            enum   — 'pending' | 'deploying' | 'deployed' | 'synced' | 'error'
+                            — for the dominant `'self_hosted'` mode the status
+                              flows 'pending' → 'synced' (or 'error' on a
+                              failed route fetch). 'deploying' / 'deployed'
+                              are reserved for the future `'managed'`
+                              Cloudflare-Pages auto-deploy flow (see §2)
+                              and won't appear on self-hosted rows today.
+last_synced_at    string — ISO 8601; set at successful route sync
+error             string — populated when status === 'error'
+routes            array  — discovered from .well-known/routes.json
+                            (each: { name, path, description? })
+api_key_id        UUID   — id of the auto-provisioned M2M key
+```
+
+**Caller-supplied (round-trip).**
+
+```
+name              required string
+description       optional string
+mode              required enum   — 'self_hosted' (only active)
+urls              required array  — see §2; exactly one primary
+```
+
+**Write-only (Request-only).** None. The auto-provisioned API key's
+plaintext value is returned ONCE on the create response (not on
+subsequent reads), but it isn't a "write-only" field in the
+caller-supplied sense.
+
+## 4. Error envelopes
+
+Standard JSON:API envelopes per `errors.md`. Common rejections:
+
+| `source.pointer`              | Cause                                                  |
+|-------------------------------|--------------------------------------------------------|
+| `/urls`                       | empty, missing primary, or multiple primaries          |
+| `/urls/0/url`                 | not a valid URL                                        |
+| `/mode`                       | value not in enum                                      |
+| `/name`                       | uniqueness within datalake — server error literal: "name must be unique within a datalake" |
+
+Route-fetch failures (primary URL unreachable, manifest malformed)
+do NOT reject the create — the row persists with `status: 'error'`
+and `error` populated. Use `.syncRoutes(id)` to retry after fixing
+the deployment.
+
+## 5. Lifecycle
+
+### Create
+
+Synchronous. The platform attempts a single fetch of
+`/.well-known/routes.json` at the primary URL during create.
+Success → `status: 'synced'` and `routes` populated. Failure →
+`status: 'error'` and `error` populated; the row still exists
+and can be retried via `.syncRoutes`.
+
+### Read shapes — management
+
+```
+.list(tenantSlug, datalakeSlug)              Paged: { data, meta }
+.get(tenantSlug, datalakeSlug, id)           One row, by UUID
+.metadata(tenantSlug, datalakeSlug)          Markdown catalog
+.metadataDetails(tenantSlug, datalakeSlug,   Markdown for one app
+                  id)
+```
+
+### Sync routes
+
+```typescript
+const { data: ack } = await api.connectedApps.syncRoutes(
+  tenantSlug, datalakeSlug, appId,
+)
+// 202 Accepted — the sync runs in a background worker:
+// ack.status            — 'enqueued'
+// ack.job_id            — background job id
+// ack.connected_app_id  — echo of the app id
+// ack.enqueued_at       — enqueue timestamp
+```
+
+This is the explicit "re-fetch and save" verb — asynchronous. The
+202 acknowledgement proves the app id resolved and a sync job was
+accepted; the worker then refreshes `routes` + `last_synced_at` and
+lands `status: 'synced'` (or `'error'`) on the app row. Poll
+`.get()` for the outcome. Use it after deploying a new manifest,
+fixing a primary URL outage, or recovering from `status: 'error'`.
+
+Discovery failure modes the platform handles explicitly — each
+leaves the row at `status: 'error'` with `error` populated:
+
+```
+   HTTP 404 from primary URL                — manifest not found
+   HTTP 5xx from primary URL                — server error at the app
+   request timeout                          — primary URL slow / hung
+   TCP connection refused                   — deployment not running
+   response content-type != application/json — wrong endpoint or proxy
+   response body is not a JSON array        — manifest schema wrong
+   route entry missing required `name`      — per-route schema gap
+   route entry missing required `path`      — per-route schema gap
+```
+
+Per-route schema failures stop the sync — the platform validates
+every entry in the array and refuses partial saves. Empty
+manifests (`[]`) succeed with zero routes registered.
+
+The primary URL has a trailing slash stripped before the
+`/.well-known/routes.json` join, so both `https://app.example.com`
+and `https://app.example.com/` produce the same fetch URL.
+
+### Update
+
+`PUT` replays the full body. Mutating the primary URL does NOT
+auto-trigger a route sync — call `.syncRoutes` after the update if
+the new primary URL serves a different manifest.
+
+### Delete
+
+`DELETE` removes the connected app AND the auto-provisioned API
+key. Workflows that still reference the app's id in action
+`connected_app_id` fields fail at run time with the action's
+template-render step erroring on the missing relation. Detach
+workflow actions first.
+
+Delete latency depends on the app's `mode`:
+
+- `mode: 'self_hosted'` — synchronous. The row is gone when
+  the DELETE response returns.
+- `mode: 'managed'` — async. The DELETE response returns
+  immediately, but the actual teardown (Cloudflare Pages
+  project deletion + DNS unregistration) runs in a background
+  worker. The row's `status` transitions through
+  `'deploying'` (during teardown) before disappearing. Poll
+  `.get()` until 404 to confirm removal.
+
+## 6. Runtime: how magic links resolve
+
+This section covers the runtime callers — the connected app
+deployment itself, not the admin.
+
+At workflow run time, an action with `connected_app_id` +
+`connected_app_route` renders a message body that contains a
+URL of the form:
+
+```
+   https://<primary-url>/t/<short_path>
+```
+
+The customer clicks the link, lands on the app, and the app
+resolves the page:
+
+```typescript
+const { data: page } = await api.connectedApps.resolvePage(
+  tenantSlug, slug,                                 // tenant + connected-app slug
+  {
+    short_path: '<the-short-path-from-the-URL>',
+    user_agent: req.headers.get('user-agent') ?? '',
+  },
+)
+// page.message            — the rendered message row
+// page.message.body       — the regulated rendered body (raw)
+// page.route_path         — the route the link was minted against
+//                            (e.g. '/forms/review')
+// page.metadata           — parsed `connected_app_metadata_template`
+//                            output from the workflow action; arbitrary JSON
+```
+
+The app routes to the page named by `route_path`, renders the
+form using `metadata` for prefill, and updates tracking when
+the customer opens or submits the form:
+
+```typescript
+await api.connectedApps.updateMessageTracking(
+  tenantSlug, slug,
+  {
+    short_path: '<same-short-path>',
+    opened_at: new Date().toISOString(),
+    form_submitted_at: new Date().toISOString(),   // only when form completes
+  },
+)
+```
+
+Both calls are authenticated with the connected app's
+auto-provisioned machine-to-machine API key (typically configured as
+`ALVERA_API_KEY` in the deployment environment).
+
+### Workflow-side wiring
+
+A workflow action that emits a magic link must set:
+
+```
+connected_app_id                 UUID  — the registered app
+connected_app_route              string — must match a discovered route's path
+                                          (e.g. '/forms/review')
+connected_app_metadata_template  string — Liquid template rendering a JSON
+                                          object the resolved page returns
+                                          to the app (arbitrary shape; the
+                                          app decides how to use it for
+                                          prefill, headers, etc.)
+```
+
+See `workflows.md` §7 for the action-level field detail.
+
+## 7. Gotchas
+
+1. **Exactly one URL must be `is_primary: true`.** Zero or
+   multiple primaries returns 422. The primary is what the
+   platform fetches routes from AND what magic links are minted
+   against; additional URLs are reference-only.
+
+2. **`status: 'error'` after create is recoverable.** A failed
+   route fetch (manifest 404, malformed JSON, primary URL DNS
+   failure) doesn't reject the row. Fix the deployment and call
+   `.syncRoutes(id)` to retry.
+
+3. **Mode `'managed'` is reserved.** It's structurally valid in
+   the request type but no deploy fires today. Use `'self_hosted'`
+   and run your own deployment.
+
+4. **`.syncRoutes` is NOT automatic.** The platform only fetches
+   the manifest at create time and on explicit re-sync. Operators
+   who change their `/.well-known/routes.json` between deploys
+   must trigger a sync.
+
+5. **Runtime calls use `slug`, not `id`.** `.resolvePage` and
+   `.updateMessageTracking` skip the datalake path segment and
+   key on the app's slug + tenant. The auto-provisioned M2M key
+   is tenant-scoped, so the connected-app deployment authenticates
+   without knowing the datalake.
+
+6. **`connected_app_route` on a workflow action must match a
+   discovered route.** Action templates reference
+   `{{ connected_app_form_url }}` which the platform constructs
+   from the bound app's primary URL + the route path. A route
+   that hasn't been synced into the app's `routes` array still
+   accepts the action at create time but the magic-link
+   resolution fails when a customer clicks the link.
+
+7. **The auto-provisioned API key is revealed ONCE.** It appears
+   on the create response and is never returned again. The
+   create-flow caller is responsible for capturing the plaintext
+   value and configuring it into the connected-app deployment's
+   environment. The platform stores only the key id on the row.
+
+8. **Route manifests must be JSON arrays, not objects.** A
+   common mistake is wrapping the routes in `{ "routes": [...] }`
+   — the manifest's top-level must be the array itself.

package/.agent/cookbook/_fixtures/README.md

@@ -0,0 +1,99 @@
+# Cookbook fixtures
+
+Vendored Liquid templates and CSV fixtures the
+[cookbook recipes](../) load at runtime via
+`fs.readFileSync`. Organized by industry so the corpus stays
+self-describing — an agent crawling this directory can list
+every template available to every cookbook in a given industry
+by reading one path.
+
+## Convention
+
+Cookbook code reads fixtures via the
+`COOKBOOK_FIXTURES_DIR` environment variable. The validator
+(`make validate-cookbook`) exports this variable to the spawned
+`bun test` process; any operator script that runs cookbook code
+directly must set the same variable to the absolute path of
+this directory.
+
+```typescript
+import fs from 'node:fs'
+import path from 'node:path'
+
+const LE_TEMPLATE = fs.readFileSync(
+  path.join(
+    process.env.COOKBOOK_FIXTURES_DIR!,
+    'foundation/_lead_submissions_foundation_legal_entity.liquid',
+  ),
+  'utf8',
+)
+```
+
+Same env-var pattern as the `ALVERA_BASE_URL` /
+`ALVERA_ROOT_EMAIL` / `ALVERA_ROOT_PASSWORD` credentials the
+generated specs already consume.
+
+## Why fixtures instead of inline templates
+
+Inlining each template verbatim inside the cookbook markdown
+would bloat each recipe to several hundred extra lines of
+Liquid noise, which obscures the cookbook's actual lesson (the
+sequence of SDK calls plus the assertions). Loading templates
+by path preserves cookbook readability AND keeps recipes
+executable — the cookbook is shipped as part of the
+`@alvera-ai/platform-sdk` npm package, the fixtures ship
+alongside it via the package's `files: [.agent]` field, and
+the env-var dereference works for any consumer that installed
+the package.
+
+## Provenance
+
+Templates are copied verbatim from
+[platform/priv/liquid_templates/](https://github.com/alvera-ai/platform/tree/develop/priv/liquid_templates),
+the production source-of-truth. The same vendoring chain
+already exists in
+`platform/integration-tests/tests/<industry>/fixtures/templates/`;
+this directory extends that chain into the SDK package so the
+cookbook corpus is self-contained at npm-install time.
+
+When a production template changes, re-copy the file here and
+re-run `make validate-cookbook` to confirm the cookbook still
+passes against the new template shape.
+
+## Per-industry inventory
+
+### `foundation/`
+
+| File | Consumed by cookbook(s) | Source-of-truth |
+|---|---|---|
+| `_lead_submissions_foundation_legal_entity.liquid` | `birthday-greeting-sms-trigger`, `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_legal_entity.liquid` |
+| `_lead_submissions_foundation_generic_table.liquid` | `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_generic_table.liquid` |
+| `_lead_submissions_foundation_mdm.liquid` | `score-leads-with-llm-categorization` | `priv/liquid_templates/data_activation/interoperability/foundation/airflow/_lead_submissions_foundation_mdm.liquid` |
+
+### `healthcare/`
+
+| File | Consumed by cookbook(s) | Source-of-truth |
+|---|---|---|
+| `_cahps_appointments_healthcare_patient.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_patient.liquid` |
+| `_cahps_appointments_healthcare_appointment.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_appointment.liquid` |
+| `_cahps_appointments_healthcare_mdm.liquid` | `appointment-review-sms-workflow` | `priv/liquid_templates/data_activation/interoperability/healthcare/fhir4/athena/_cahps_appointments_healthcare_mdm.liquid` |
+
+The `contact-us-triage-with-llm` cookbook ingests into a generic
+table via the auto-provisioned identity contract, so it loads no
+vendored template.
+
+### `accounts_receivable/`
+
+| File | Consumed by cookbook(s) | Source-of-truth |
+|---|---|---|
+| `_customers_accounts_receivable_customer.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_customer.liquid` |
+| `_customers_accounts_receivable_mdm.liquid` | `welcome-sms-for-customers`, `dunning-sms-for-delinquent` | `priv/liquid_templates/data_activation/interoperability/accounts_receivable/stripe/_customers_accounts_receivable_mdm.liquid` |
+
+### `payment_risk/`
+
+| File | Consumed by cookbook(s) | Source-of-truth |
+|---|---|---|
+| `_payment_accounts_payment_risk_payment_account.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_payment_accounts_payment_risk_payment_account.liquid` |
+| `_payment_accounts_payment_risk_mdm.liquid` | `kyc-notification-on-account-activation` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_payment_accounts_payment_risk_mdm.liquid` |
+| `_compliance_screenings_payment_risk_compliance_screening.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_compliance_screenings_payment_risk_compliance_screening.liquid` |
+| `_compliance_screenings_payment_risk_mdm.liquid` | `sanctions-screening-with-agent-review` | `priv/liquid_templates/data_activation/interoperability/payment_risk/atomic_fi/_compliance_screenings_payment_risk_mdm.liquid` |

package/.agent/cookbook/_fixtures/accounts_receivable/_customers_accounts_receivable_customer.liquid

@@ -0,0 +1,32 @@
+{% comment %}Stripe Customers → Accounts Receivable Customer attrs{% endcomment %}
+{% assign p = msg %}
+{
+  "customer_type": "{{ p.customer_type | default: "individual" | json_escape }}",
+  "status": "{{ p.status | default: "prospect" | json_escape }}",
+  "customer_number": "{{ p.customer_number | json_escape }}",
+  {% if p.currency and p.currency != "" %}"currency": "{{ p.currency | json_escape }}",{% endif %}
+  {% if p.delinquent and p.delinquent != "" %}"delinquent": {{ p.delinquent }},{% endif %}
+  {% if p.tax_exempt and p.tax_exempt != "" %}"tax_exempt": "{{ p.tax_exempt | json_escape }}",{% endif %}
+  {% if p.preferred_locales and p.preferred_locales != "" %}{% assign locales = p.preferred_locales | split: "|" %}"preferred_locales": [{% for l in locales %}"{{ l | json_escape }}"{% unless forloop.last %},{% endunless %}{% endfor %}],{% endif %}
+  "regulated_customer": {
+    {% if p.name and p.name != "" %}"name": "{{ p.name | json_escape }}",{% endif %}
+    {% if p.email and p.email != "" %}"email": "{{ p.email | json_escape }}",{% endif %}
+    {% if p.phone and p.phone != "" %}"phone": "{{ p.phone | json_escape }}",{% endif %}
+    {% if p.tax_id and p.tax_id != "" %}"tax_id": "{{ p.tax_id | json_escape }}",{% endif %}
+    {% if p.address_line1 and p.address_line1 != "" %}"address_line1": "{{ p.address_line1 | json_escape }}",{% endif %}
+    {% if p.address_line2 and p.address_line2 != "" %}"address_line2": "{{ p.address_line2 | json_escape }}",{% endif %}
+    {% if p.address_city and p.address_city != "" %}"address_city": "{{ p.address_city | json_escape }}",{% endif %}
+    {% if p.address_state and p.address_state != "" %}"address_state": "{{ p.address_state | json_escape }}",{% endif %}
+    {% if p.address_postal_code and p.address_postal_code != "" %}"address_postal_code": "{{ p.address_postal_code | json_escape }}",{% endif %}
+    {% if p.address_country and p.address_country != "" %}"address_country": "{{ p.address_country | json_escape }}",{% endif %}
+    {% if p.shipping_name and p.shipping_name != "" %}"shipping_name": "{{ p.shipping_name | json_escape }}",{% endif %}
+    {% if p.shipping_phone and p.shipping_phone != "" %}"shipping_phone": "{{ p.shipping_phone | json_escape }}",{% endif %}
+    {% if p.shipping_address_line1 and p.shipping_address_line1 != "" %}"shipping_address_line1": "{{ p.shipping_address_line1 | json_escape }}",{% endif %}
+    {% if p.shipping_address_line2 and p.shipping_address_line2 != "" %}"shipping_address_line2": "{{ p.shipping_address_line2 | json_escape }}",{% endif %}
+    {% if p.shipping_address_city and p.shipping_address_city != "" %}"shipping_address_city": "{{ p.shipping_address_city | json_escape }}",{% endif %}
+    {% if p.shipping_address_state and p.shipping_address_state != "" %}"shipping_address_state": "{{ p.shipping_address_state | json_escape }}",{% endif %}
+    {% if p.shipping_address_postal_code and p.shipping_address_postal_code != "" %}"shipping_address_postal_code": "{{ p.shipping_address_postal_code | json_escape }}",{% endif %}
+    "shipping_address_country": "{{ p.shipping_address_country | default: "" | json_escape }}"
+  },
+  "source_uri": "{{ p.source_uri | default: "" | json_escape }}"
+}

package/.agent/cookbook/_fixtures/accounts_receivable/_customers_accounts_receivable_mdm.liquid

@@ -0,0 +1,20 @@
+{% comment %}Stripe Customers → Accounts Receivable MDM Input{% endcomment %}
+{% assign p = msg %}
+{
+  "identifiers": [
+    {
+      "system": "urn:{{ p.source_uri | json_escape }}:customer-number",
+      "value": "{{ p.customer_number | json_escape }}"
+    }
+  ],
+  {% assign space_parts = p.name | split: " " %}
+  {% if space_parts.size > 1 %}
+  "given_name": "{{ space_parts | first | json_escape }}",
+  "family_name": "{{ space_parts | last | json_escape }}",
+  {% else %}
+  "family_name": "{{ p.name | strip | json_escape }}",
+  {% endif %}
+  {% if p.phone and p.phone != "" %}"phone": "{{ p.phone | json_escape }}",{% endif %}
+  {% if p.email and p.email != "" %}"email": "{{ p.email | json_escape }}",{% endif %}
+  "gender": "unknown"
+}

package/.agent/cookbook/_fixtures/foundation/_lead_submissions_foundation_generic_table.liquid

@@ -0,0 +1,33 @@
+{% comment %}
+  Foundation Airflow Lead Form → `lead_submissions` generic_table row.
+
+  Maps a single Google-Sheet lead row into the `lead_submissions` GT
+  upsert shape — one JSON field per GT column. Used by Contract B
+  (`resource_type: "generic_table"`, `generic_table_id` pinned to the
+  `lead_submissions` GT). Contract B also carries an
+  `mdm_input_config` (separate template) so the GT event emitted on
+  upsert pins `mdm_subject_id == legal_entity.id` (the LE that
+  Contract A wrote / Foundation MDM resolved by digital_identifier
+  email dedupe).
+
+  GT columns:
+    * `submission_id` — vendor-supplied unique sheet row id (unique col,
+      so re-ingest of the same submission_id idempotently updates the
+      same row instead of inserting a duplicate)
+    * `name`, `email`, `phone` — tokenized PII
+    * `company` — empty string for individual leads, non-empty for
+      business leads (mirrors Contract A's branch logic)
+    * `message` — free-text lead body
+    * `lead_source` — utm_source / sheet tab id, surfaced for downstream
+      attribution dashboards
+{% endcomment %}
+{% assign p = msg %}
+{
+  "submission_id": "{{ p.submission_id | json_escape }}",
+  "name": "{{ p.name | default: "" | json_escape }}",
+  "email": "{{ p.email | default: "" | json_escape }}",
+  "phone": "{{ p.phone | default: "" | json_escape }}",
+  "company": "{{ p.company | default: "" | json_escape }}",
+  "message": "{{ p.message | default: "" | json_escape }}",
+  "lead_source": "{{ p.lead_source | default: "" | json_escape }}"
+}