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

package/.agent/ai_sandbox.md

@@ -0,0 +1,265 @@
+# AI sandbox — the safety contract
+
+Alvera accepts AI-authored fragments from external tools (Claude
+Code, Cursor, ChatGPT, in-tenant AI agents, direct API clients)
+and runs them against tenant data. **None of those fragments
+ever reach arbitrary code execution.** Every author surface — a
+Liquid template body, a SQL fragment, an agent prompt — passes
+through a three-layer sandbox that bounds blast radius.
+
+This page names the three layers, the contract each one
+enforces, and where each one's wire-level details live in the
+rest of the corpus. It's the consumer-side landing for "why is
+it safe to put my AI-authored body here".
+
+The three layers are independent — any one alone would bound
+the worst case — and they compose into defense-in-depth.
+
+## Layer 1 — Compliance gates (who sees what)
+
+Two consumer-set fields decide whether a request reaches raw
+PHI/PII/PCI or only the tokenized projection. Both must
+authorize regulated reach for raw data to flow:
+
+```
+   session role           AI agent data_access     →  outcome
+   ──────────────         ───────────────────         ───────
+   member or admin        regulated                   regulated reachable
+   member or admin        unregulated                 tokenized only
+   member or admin        (no agent on path)          regulated reachable
+   researcher             any value                   tokenized only
+```
+
+- **Session role** is pinned on the membership at invitation
+  time (vocabulary A — `'member' | 'researcher' | 'admin'`; the
+  resulting session carries the corresponding role-record name
+  — see `account_management.md` §3).
+- **AI agent `data_access`** is `'regulated' | 'unregulated'`,
+  pinned at agent creation (immutable post-create — see
+  `ai_agents.md`). Default is `'unregulated'`; `'regulated'` is
+  opt-in.
+
+A `researcher` session can never reach raw PHI regardless of how
+the agent is configured. An `'unregulated'` agent can never
+reach raw PHI regardless of session role. Tenant isolation
+(every row carries a tenant id; queries filter on the session's
+tenant) AND-composes with both of these so a request only sees
+the slice that *all three* allow.
+
+The composition rule is fail-safe: a workflow spec that omits
+`data_access` is treated as `'unregulated'`. Author-side
+mistakes default to less reach, never more.
+
+## Layer 2 — Liquid sandbox (what can execute)
+
+Every consumer-authored template body — interop contract
+`template_config.body`, AI agent `prompt_config.body`, workflow
+filter / decision / action bodies, action `trigger_template`,
+data activation client `row_filter`, tool call `body` templates
+— is a Liquid template. Not arbitrary code. Liquid is the trust
+boundary between consumer fragments and the platform runtime.
+
+### What Liquid bodies CANNOT do
+
+- Invoke runtime code. There is no `{% eval %}` or equivalent.
+- Read the filesystem, open sockets, or reach the network.
+- Mutate state outside the render's own local variable scope.
+- Call any platform capability beyond the explicit custom-filter
+  allowlist (below).
+
+Liquid's stock tag set (`{% if %}`, `{% for %}`, `{% assign %}`,
+`{% unless %}`, `{% capture %}`, etc.) is preserved as-is.
+`{% capture %}` writes to a Liquid-scope variable; it is not a
+runtime eval escape hatch.
+
+### The 11-filter custom allowlist
+
+Beyond stock Liquid, the platform exposes exactly **eleven**
+custom filters. Adding new ones requires a platform release —
+consumers cannot extend the set:
+
+```
+   e164          Phone string → E.164 format for SMS.
+                 Example:  {{ patient.phone | e164 }}  →  +15555550201
+
+   age           Years from a birth date.
+                 Example:  {{ patient.birth_date | age }}  →  66
+
+   date          Format a datetime, optional add/subtract.
+                 Example:  {{ start | date: '%Y-%m-%d', 'subtract', '24 hours' }}
+                           →  2026-03-14
+
+   to_json       Encode a map / array to a JSON string.
+                 Example:  {{ event_dataset | to_json }}  →  {"name":"…"}
+
+   json_escape   Escape a value for safe interpolation inside a
+                 JSON string literal (quotes, backslashes,
+                 control chars).
+                 Example:  "name": "{{ p.name | json_escape }}"
+                           →  "name": "O\"Brien"
+
+   now           Current UTC datetime, ISO 8601.
+                 Example:  {{ '' | now }}  →  2026-03-15T14:30:00Z
+
+   uuid          Generate a new v4 UUID.
+                 Example:  {{ '' | uuid }}  →  a1b2c3d4-…
+
+   parse_date    Parse a date string with a format spec.
+                 Example:  {{ '31/12/2023' | parse_date: '{D}/{0M}/{YY}' }}
+                           →  2023-12-31
+
+   convert_time  Convert a time between formats.
+                 Example:  {{ '10:00 pm' | convert_time: '{h12}:{m} {am}' }}
+                           →  22:00:00
+
+   random        Random integer in a range.
+                 Example:  {{ 10 | random }}  →  0..10
+
+   tz_offset     Current UTC offset for an IANA timezone string.
+                 Example:  {{ timezone | tz_offset }}  →  -04:00
+```
+
+A common trap: `| json` (Shopify / Jekyll spelling) is NOT in
+the allowlist. The lookalike falls through to a generic
+stringification that produces unparseable output. Always use
+`| to_json`. See `workflows.md` gotcha 9 for the diagnostic
+trail this trap leaves.
+
+### Write-time and render-time validation
+
+- **Parse on write.** Every body is parsed before storage.
+  Syntactically invalid Liquid is rejected with a 422 on the
+  body field — bad templates never reach a render site.
+- **Schema on render.** When the embed declares an
+  `output_schema` (most often a JSON Schema describing the
+  expected shape of the rendered JSON), the rendered output is
+  validated against the schema before reaching the downstream
+  consumer. Shape drift surfaces at the point of production, not
+  at the point of use.
+
+## Layer 3 — SQL fragment boundary (what queries can do)
+
+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
+these from templates; others arrive directly as raw SQL
+fragments. Either path lands at the same boundary.
+
+### What SQL fragments CAN do
+
+- SELECT against the regulated tables exposed by the dataset
+  search aliases (`rp` for `regulated_patients`, `rc` for
+  `regulated_customers`, etc. — see `data_activation_clients.md`
+  §6.5 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
+  on the consumer's behalf — the consumer authors the WHERE
+  clause, not the INSERT.
+
+### What SQL fragments CANNOT do
+
+- Read PHI/PII/PCI if Layer 1 disallows it. The dedicated
+  query-connection pool runs with reader-tier credentials
+  scoped to the session's tenant; cross-tenant reach is
+  physically blocked at the connection.
+- INSERT, UPDATE, or DELETE against any table other than the
+  materialised search-results accumulator the platform manages.
+- Invoke functions or extensions outside the read-only set
+  Postgres grants the pool. A consumer-authored fragment that
+  tries to call a write-grant function gets a permission denied
+  error from the database, not from the application.
+
+### Parameterisation
+
+Values that get interpolated into the SQL (typically via Liquid
+filters that render a value into the WHERE clause) are bound as
+parameters, not concatenated into the SQL string. SQL injection
+via consumer-authored fragments is structurally impossible: the
+fragment is the WHERE *expression*, with values supplied via
+positional bindings the platform builds.
+
+## How the three layers compose
+
+```
+   ┌─────────────────────────────────────────────┐
+   │  Layer 1 — compliance gates                 │
+   │    session role  AND  agent data_access     │
+   │    AND  tenant id (RLS)                     │
+   │  Decides: which schema (regulated vs        │
+   │  unregulated) and which tenant the query    │
+   │  hits.                                      │
+   └────────────────────┬────────────────────────┘
+                        │
+   ┌────────────────────▼────────────────────────┐
+   │  Layer 2 — Liquid sandbox                   │
+   │    11-filter allowlist                      │
+   │    + parse-on-write                         │
+   │    + render-time output_schema check        │
+   │  Decides: what the consumer-authored body   │
+   │  can express. No VM reach, no FS/network,   │
+   │  no eval escape hatch.                      │
+   └────────────────────┬────────────────────────┘
+                        │
+   ┌────────────────────▼────────────────────────┐
+   │  Layer 3 — SQL fragment boundary            │
+   │    parameterised bindings                   │
+   │    + reader-tier connection pool            │
+   │    + INSERT-only on search_results          │
+   │  Decides: what SQL fragments the WHERE      │
+   │  clause path can execute. Read-most,        │
+   │  write-one.                                 │
+   └─────────────────────────────────────────────┘
+```
+
+Each layer is independently sufficient: bypassing any single
+layer still leaves the other two enforcing the contract. The
+compound rule is "all three must permit" — read PHI requires
+authorising session role AND regulated-mode agent (when an
+agent is on the path) AND tenant id match.
+
+## Auditability
+
+Every LLM call the platform makes on behalf of a consumer is
+recorded with cloud-storage pointers to the exact input payload
+the agent received and the exact response the provider
+returned. The audit record outlives the host run that produced
+it — a compliance auditor can later replay any agent's input
+and verify what data class (regulated vs tokenized) actually
+reached the model. The audit surface is admin-facing today; the
+guarantees it captures back-stop Layer 1.
+
+## Consumer takeaways
+
+1. **Default to `'unregulated'` agent `data_access`.** Opt into
+   `'regulated'` only when the action genuinely needs raw
+   values, and pair with a session role that's authorised.
+
+2. **Use only the 11 custom filters** named in Layer 2. Bodies
+   that reference other filter names will silently fall through
+   to stock Liquid behavior and produce malformed output.
+
+3. **Anchor JSON bodies on `to_json`.** When a template body
+   must produce valid JSON (most contexts of MDM input,
+   workflow context_mapping, action metadata), wrap nested
+   values with `| to_json` and never with `| json`.
+
+4. **Treat SQL WHERE fragments as expressions, not statements.**
+   The dataset search surface owns the SELECT and the INSERT
+   into `search_results`. Consumer authoring is constrained to
+   the WHERE clause; everything else is platform-built.
+
+5. **Pin output shapes with `output_schema`.** Where the embed
+   supports it (most TemplateConfig surfaces), populating
+   `output_schema` turns render-time shape drift into a clean
+   422 instead of a downstream JSON-decode error two queues
+   later.
+
+## Related
+
+- `ai_agents.md` §2 — `data_access` mode (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)
+- `mdm.md` — verification surface that composes with Layer 1

package/.agent/async.md

@@ -0,0 +1,111 @@
+# Async and readiness
+
+Some operations are async on the server. The create response
+returns immediately with the resource in a non-terminal status;
+downstream operations must wait for the resource to reach its
+terminal status before proceeding.
+
+## Canonical wait shape
+
+```typescript
+async function waitUntilReady<T extends { status: string }>(
+  fetcher: () => Promise<{ data: T }>,
+  isTerminal: (status: string) => 'ready' | 'failed' | 'pending',
+  { intervalMs = 1000, timeoutMs = 60_000 } = {},
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs
+  while (true) {
+    const { data } = await fetcher()
+    const state = isTerminal(data.status)
+    if (state === 'ready') return data
+    if (state === 'failed') {
+      throw new Error(`failed: ${JSON.stringify(data)}`)
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`timed out waiting for ready`)
+    }
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+}
+```
+
+The shape is the same across resources; only the terminal-
+success / terminal-failure status values differ.
+
+## Per-resource readiness signals
+
+The terminal-success and terminal-failure status values are
+resource-specific. Common examples:
+
+| Resource                          | Terminal success | Terminal failure        |
+|-----------------------------------|------------------|-------------------------|
+| Datalake (create + migrate)       | `ready`          | — (no terminal failure) |
+| Data Activation Client run        | `success`        | `error`                 |
+| AWS Lambda tool deploy            | `deployed`       | `failed`                |
+| Workflow run                      | `completed`      | `failed`                |
+
+The Datalake row is the odd one: its top-level `status` enum is
+`new | processing | ready` only — there is no terminal failure
+value. A migration that fails leaves the datalake at
+`processing` (or `new` if it never started). The failure
+surfaces in the admin console's Migration Logs view, which is
+not exposed over the SDK. Consumers polling for datalake
+readiness must therefore rely on `timeoutMs` to bound the wait;
+the `'failed'` branch of `waitUntilReady` never fires for this
+resource.
+
+The AWS Lambda tool row keys on `tool.body.stack_status` (the
+CloudFormation deploy status nested under the polymorphic
+`body`), not on the top-level `tool.status` enum (which is
+`draft | active | inactive | error | marked_for_deletion`).
+`tool.status` flips to `'active'` after a successful deploy
+but `stack_status` is the more precise readiness signal — see
+`tools.md` §2 for the per-body field set.
+
+Each resource's MD §5 (Lifecycle) names its terminal-success
+and terminal-failure status enums. If your resource isn't in
+the table above, its MD is authoritative.
+
+## Downstream resources MUST wait
+
+Downstream operations (creating child resources, running
+workflows, invoking tools) MUST NOT proceed until the parent
+resource is in a terminal-success status. Posting a child
+resource against an unready parent typically surfaces as a
+500 (server-internal) or a 422 with a "parent not ready"
+detail — both are recoverable but indicate a missing wait in
+the caller.
+
+## Idempotency on create
+
+POST creates are NOT idempotent by default. Repeating a POST
+with the same body yields a 422 on uniqueness fields (typically
+the name within scope). Consumers handling retry should:
+
+1. Catch the post-HTTP throw (see `errors.md`).
+2. Inspect for a uniqueness `detail` on a `source.pointer`
+   that names the uniqueness key (usually `/name` or `/slug`).
+3. Treat as "already created" and fetch the existing row.
+
+The integration test suite formalizes this as the
+"idempotent retry path" pattern in places where local state
+may have diverged from server state (e.g. a prior run wrote
+to the server but failed to capture the response locally).
+
+## Polling cost
+
+Polling at 1s intervals against the platform's
+`/<resource>/:slug` endpoint is cheap for most resources but
+becomes expensive at high concurrency. For long-running
+operations (lambda deployments, large data-activation-client
+runs), back off the interval (e.g. 2s → 5s → 10s) after the
+first ~30s of waiting.
+
+## What the SDK does NOT auto-poll
+
+The typed client returns the immediate POST response — it
+does NOT block until the resource reaches terminal status.
+Consumers explicitly write the wait loop above where it
+matters. This is intentional: not every caller wants to
+block (some kick off async work and return; some need the
+ready signal before downstream).