@alvera-ai/platform-sdk 0.19.2 → 0.20.0-next.g8dc7938

package/.agent/AGENTS.md

@@ -93,7 +93,7 @@ corpus page documents the surface you already know:
 | Sampling              | Dataset event triggers       | `data_activation_clients.md` §6.4 logs        |
 | Tools                 | Tool Calls (polymorphic body)| `tools.md`                                    |
 | Roots                 | Datalake boundaries          | `datalakes.md`                                |
-| Human-in-the-loop     | Connected Apps + page tokens | `connected_apps.md`                           |
+| Human-in-the-loop     | Authenticated links          | `authenticated_links.md`                      |
 | Sandboxed execution   | Liquid + SQL fragment lanes  | `ai_sandbox.md`                               |
 
 A few caveats on the mapping:
@@ -204,9 +204,9 @@ admin/bootstrap flows (signup, confirmation, tenant creation,
 test-suite setup) — they are NOT app-building surfaces; an app that
 holds a root or tenantless Bearer is misdesigned. An app
 authenticates against exactly one tenant with that tenant's
-publishable key. Likewise, connected apps are **single-tenant by
-construction** — one connected app per tenant, never one deployment
-serving many tenants (see `connected_apps.md`).
+publishable key. Likewise, the host behind an action's
+`link_prefix` resolves its links against one tenant, on that tenant's
+publishable key (see `authenticated_links.md`).
 
 Consumers holding multiple concurrent clients in the same file
 (e.g. integration tests that need root + tenantless + tenant-
@@ -248,7 +248,6 @@ numbered steps inside the cookbook whose use case motivates it.
                                   consumed by other resources.
    ai_agents.md                  LLM-backed workers.
    action_status_updaters.md     Polling reconcilers.
-   connected_apps.md             External app bridges.
    mdm.md                        Entity resolution + identity
                                   verification across domains.
    ai_sandbox.md                 Three-layer safety contract
@@ -279,13 +278,16 @@ numbered steps inside the cookbook whose use case motivates it.
    action_logs.md                The action_logs DATASET — per-
                                   action outcomes, batch_id joins,
                                   audience export.
+   authenticated_links.md        Every URL a message carries, as
+                                  <link_prefix>/<token>; the host
+                                  behind the prefix resolves taps
+                                  and reports the page.
 ```
 
 Axes are mostly disjoint but a few resources cross. AI Agents
 anchor INFRASTRUCTURE and appear in DATA ACTIVATION (they
 tokenize during ingestion) and WORKFLOWS (workflows invoke
-them). Connected Apps anchor INFRASTRUCTURE and tag into
-WORKFLOWS.
+them).
 
 Each resource is exposed via a TypeScript namespace on the
 typed client. The SDK namespace name follows TS conventions
@@ -299,13 +301,13 @@ wire name (snake_case):
     api.tools                           tools.md
     api.aiAgents                        ai_agents.md
     api.actionStatusUpdaters            action_status_updaters.md
-    api.connectedApps                   connected_apps.md
     api.mdm                             mdm.md
     api.genericTables                   generic_tables.md
     api.advancedMigrations              advanced_migrations.md
     api.interoperabilityContracts       interoperability_contracts.md
     api.dataActivationClients           data_activation_clients.md
     api.workflows                       workflows.md
+    api.authenticatedLinks              authenticated_links.md
 
 Two corpus pages document DATASETS, not namespaces — read
 through `api.datasets` with SINGULAR dataset types (the plural

package/.agent/account_management.md

@@ -99,15 +99,16 @@ a tenant (creator path) or accept an invitation (invitee path).
 are platform-UI / admin-bootstrap surfaces (signup, confirmation,
 tenant creation, test setup) — never ship them inside an app. An
 app authenticates **tenant-scoped against exactly one tenant**,
-with that tenant's publishable key; connected apps in particular
-are single-tenant by construction (`connected_apps.md`).
+with that tenant's publishable key; the host behind an action's
+`link_prefix` in particular resolves links for one tenant
+(`authenticated_links.md`).
 
 ### Key-only clients — machine-to-machine on the publishable key
 
-`sessionToken` is optional on the client config. A deployed
-connected app that authenticates purely on its tenant's publishable
-key constructs with just the key — no session mint, no fabricated
-empty token:
+`sessionToken` is optional on the client config. The host behind an
+action's `link_prefix`, authenticating purely on its tenant's
+publishable key, constructs with just the key — no session mint, no
+fabricated empty token:
 
 ```typescript
 const api = createIsolatedPlatformApi({ baseUrl, apiKey })
@@ -118,15 +119,15 @@ and reaches exactly the `public_api` (publishable-key) allowlist —
 five calls:
 
 ```
-   api.connectedApps.resolvePage             mint/read a delivered page
-   api.connectedApps.updateMessageTracking   opened_at / form_submitted_at
-   api.dataActivationClients.ingest          submit rows
-   api.dataActivationClients.ingestFile      submit a file
-   api.mdm.verify                            resolve an identity
+   api.authenticatedLinks.exchange                a tap on a link
+   api.authenticatedLinks.updateMessageTracking   opened / form_submitted
+   api.dataActivationClients.ingest               submit rows
+   api.dataActivationClients.ingestFile           submit a file
+   api.mdm.verify                                 resolve an identity
 ```
 
-(The same allowlist `connected_apps.md` documents — that guide owns
-the runtime-call details.) Every call outside these five returns
+(`authenticated_links.md` owns the details of the two link calls.)
+Every call outside these five returns
 401; that ceiling is the point, not an error to work around.
 Minting a session and passing `sessionToken` unlocks the full
 tenant-scoped API exactly as before — the two credentials are

package/.agent/action_status_updaters.md

@@ -635,9 +635,10 @@ is the part that matters:
   decision (`mode: 'live'`, `manual_override: true`) — the same
   call as any manual dispatch; there is no retry endpoint. See
   `workflows.md` §8.
-- **Engagement is not here either.** `opened_at` /
-  `form_submitted_at` arrive via
-  `connectedApps.updateMessageTracking` (magic-link seam,
-  `connected_apps.md` §6) and never touch `status`.
+- **Engagement is not here either.** `clicked` arrives via
+  `authenticatedLinks.exchange`, and `opened` / `form_submitted`
+  with their times via `authenticatedLinks.updateMessageTracking`
+  — both called by the host behind the action's `link_prefix`
+  (`authenticated_links.md`).
 - Field-by-field semantics of the rows being updated:
   `messages.md`, `action_logs.md`.

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/authenticated_links.md

@@ -0,0 +1,247 @@
+# Authenticated links
+
+Every URL in an SMS or MMS body, and every `href` in an email body, goes out
+as an **authenticated link**:
+
+```
+   <link_prefix>/<token>
+```
+
+`link_prefix` is set on the action's tool call. It is the address of a host
+**you** run. The platform appends only the token; any path belongs to the
+prefix. When a person taps the link, the request reaches your host, and your
+host asks the platform what the link is with one call and reports what the
+person did on the page with a second.
+
+SDK namespace: `api.authenticatedLinks` — `exchange` and
+`updateMessageTracking`.
+
+```
+  workflow action  (sms_request · mms_request · email_request)
+    link_prefix = "https://go.example.com/l"
+    body        = "Book a slot: https://booking.example.com/slots"
+         │ send
+         ▼
+  delivered     "Book a slot: https://go.example.com/l/q3v9RkZ0aB7xYtL"
+         │ a person taps
+         ▼
+  your host at go.example.com/l
+    exchange({ token, method, user_agent, ip, country, headers })
+      → destination_url "https://booking.example.com/slots",
+        legal_entity_id, workflow, run, action, expires_at, message
+    send the person on to destination_url
+         │ the page opens · the form is submitted
+         ▼
+    updateMessageTracking({ token, status: 'opened', opened_at })
+    updateMessageTracking({ token, status: 'form_submitted', form_submitted_at })
+```
+
+**Both calls need only the tenant's publishable key.** The host is a key-only
+client: no session, no user.
+
+```typescript
+import { createIsolatedPlatformApi } from '@alvera-ai/platform-sdk'
+
+const links = createIsolatedPlatformApi({
+  baseUrl: 'https://api.alvera.ai',
+  apiKey: 'pk_live_tenant_publishable_key',
+})
+```
+
+This replaces Connected Apps and page tokens, which the platform retired:
+there is no app to register, no route discovery, no `resolvePage`, and no
+`{{ connected_app_form_url }}`. Write the real destination URL into the
+message body; the platform turns it into an authenticated link at send.
+
+## 1. Wire shape
+
+### On the action — set when you build the workflow
+
+| Field | Where | Shape |
+|---|---|---|
+| `link_prefix` | `SmsCallRequest`, `MmsCallRequest`, `EmailCallRequest` | **required** string — the address of your host |
+| `link_validity_days` | the same three | optional whole number, at least 1, default **365** — how many days each link resolves after the send |
+| `metadata_template` | every action type | optional Liquid template rendered to JSON once per send |
+
+```typescript
+import type { AgenticWorkflowRequestWritable } from '@alvera-ai/platform-sdk'
+
+type Action = NonNullable<AgenticWorkflowRequestWritable['actions']>[number]
+
+const reviewRequest: Action['tool_call'] = {
+  tool_call_type: 'sms_request',
+  sms_type: 'transactional',
+  to: { type: 'custom', body: '{{ event_dataset.phone }}' },
+  body: {
+    type: 'custom',
+    body: 'Thanks for visiting. Tell us how it went: https://reviews.example.com/visit',
+  },
+  link_prefix: 'https://go.example.com/l',
+  link_validity_days: 30,
+}
+```
+
+### `exchange` — a tap on the link
+
+```typescript
+import type { AuthenticatedLinkExchangeRequest } from '@alvera-ai/platform-sdk'
+
+const tap: AuthenticatedLinkExchangeRequest = {
+  token: 'q3v9RkZ0aB7xYtL',            // required: from <link_prefix>/<token>
+  method: 'GET',                        // the tap's HTTP method
+  user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)',
+  ip: '203.0.113.7',
+  country: 'US',
+  headers: { 'accept-language': 'en-US' },
+}
+```
+
+### `updateMessageTracking` — what happened on the page
+
+```typescript
+import type { AuthenticatedLinkUpdateMessageTrackingRequest } from '@alvera-ai/platform-sdk'
+
+const submitted: AuthenticatedLinkUpdateMessageTrackingRequest = {
+  token: 'q3v9RkZ0aB7xYtL',             // required: the same token
+  status: 'form_submitted',              // typically 'opened' or 'form_submitted'
+  form_submitted_at: '2026-10-04T10:00:00Z',
+}
+```
+
+### The answer — `AuthenticatedLinkResponse`, from both calls
+
+| Field | Meaning |
+|---|---|
+| `destination_url` | the URL as written in the message |
+| `legal_entity_id` | the recipient's legal entity, when MDM resolved one — else `null` |
+| `message_id` | the message the link went out in |
+| `workflow_id` | the workflow that sent it |
+| `workflow_execution_log_id` | the workflow run that sent it |
+| `action_id` | the action that sent it |
+| `expires_at` | when the link stops resolving |
+| `link_clicked_at` | when a person first clicked this link — `null` until then |
+| `message` | the message, a `MessageResponse` |
+
+`message.metadata` holds the recipient's `to` merged with what the action's
+`metadata_template` rendered, as stored at send. The message carries each
+engagement status with its own time: `read` (`read_at`), `opened`
+(`opened_at`), `clicked` (`clicked_at`) and `form_submitted`
+(`form_submitted_at`).
+
+## 2. Rules the type cannot encode
+
+### `link_prefix` is an absolute URL with nothing after the path
+
+An absolute `http` or `https` URL. A path is allowed —
+`https://go.example.com/l` — but no query, no fragment and **no trailing
+slash**: the platform appends `/<token>` itself.
+
+### A person's tap moves the message to `clicked`; a machine's does not
+
+`exchange` answers every tap, but only a person's moves anything. The first
+click stamps the link's `link_clicked_at` and the message's `clicked_at`;
+later taps keep both. The platform judges a tap from what your host forwards,
+and these look automated and move nothing:
+
+- a `HEAD` request;
+- a prefetch header — `sec-purpose`, `purpose`, `x-purpose`, `x-moz`;
+- an empty user agent, or one naming a bot, a link preview or a mail scanner.
+
+Every tap is recorded with the details you forwarded and the signal that
+flagged it, if one did. Headers are recorded as client headers — never cookies
+or credentials.
+
+### The message status only moves forward
+
+`updateMessageTracking` applies its `status` through the message's order
+guard: reporting `opened` after `form_submitted` leaves the message at
+`form_submitted`. A time you leave empty keeps the message's value. The
+`status` field is a plain string on the type; one a message cannot have is
+refused with `422`.
+
+### A link answers until it expires
+
+Each link resolves for `link_validity_days` after the send, then answers
+`410`. The response's `expires_at` says when.
+
+### `metadata_template` renders once, at send
+
+It renders to JSON once per send, on every action type, and is stored on the
+message. A template that does not render **fails the send**. You read the
+result back from `message.metadata` — not from a field on the link.
+
+## 3. Field ownership
+
+| Field | Written by |
+|---|---|
+| `link_prefix`, `link_validity_days`, `metadata_template` | you, on the action |
+| `destination_url` | you, as the URL written in the body |
+| the token, `expires_at`, `message_id`, `workflow_id`, `workflow_execution_log_id`, `action_id` | the platform, at send |
+| `legal_entity_id` | the platform, when MDM resolves the recipient |
+| `link_clicked_at`, `message.clicked_at` | the platform, on a person's first tap |
+| `message.opened_at`, `message.form_submitted_at` | your host, through `updateMessageTracking` |
+
+## 4. Error envelopes
+
+Both calls throw on a refusal, and the thrown value carries the HTTP status
+as `_httpStatus` (see `errors.md`). They refuse in ways a host must tell
+apart:
+
+| Status | `exchange` | `updateMessageTracking` | Meaning |
+|---|---|---|---|
+| `404` | yes | yes | a token the platform never minted |
+| `410` | yes | yes | the link is past `expires_at` |
+| `503` | yes | yes | the datalake cannot be reached right now |
+| `422` | — | yes | a status the message cannot have |
+| `401` | yes | yes | no publishable key, or one that does not resolve |
+
+```typescript
+async function resolveTap(token: string, userAgent: string): Promise<string> {
+  try {
+    const { data } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+      token,
+      method: 'GET',
+      user_agent: userAgent,
+    })
+    return data.destination_url
+  } catch (err) {
+    const status = (err as { _httpStatus?: number })._httpStatus
+    if (status === 410) return 'https://go.example.com/expired'
+    if (status === 404) return 'https://go.example.com/not-found'
+    if (status === 503) return 'https://go.example.com/try-again'
+    throw err
+  }
+}
+```
+
+## 5. Lifecycle
+
+1. **Build.** Give every SMS, MMS and email action a `link_prefix`, and a
+   `metadata_template` when your page needs more than the recipient.
+2. **Send.** Each URL in the body becomes `<link_prefix>/<token>`, valid for
+   `link_validity_days`.
+3. **Tap.** Your host calls `exchange` with the token and the tap's request
+   details, and sends the person on to `destination_url`. A person's tap
+   moves the message to `clicked`.
+4. **Page.** Your host reports `opened` when its page opens and
+   `form_submitted` when the form is done, each with its time.
+5. **Expiry.** After `expires_at` both calls answer `410`.
+
+## 6. Gotchas
+
+- **Forward what the tap said about itself.** Only the token is required, but
+  a host that forwards nothing else gives the platform nothing to judge a
+  person by. Pass the method, user agent and headers of the request that
+  reached you, not those of your own server-side call.
+- **Link previews are taps too.** Messaging apps fetch a link to draw its
+  preview; those are recorded and do not count as clicks.
+- **Put the path in the prefix.** The platform appends only the token, so
+  `https://go.example.com/l` gives `https://go.example.com/l/<token>`. A
+  trailing slash is refused.
+- **`metadata` lives on the message.** Read `data.message.metadata`; the link
+  itself has no metadata field.
+- **Coming from Connected Apps.** `connected_app_id`, `connected_app_route`
+  and `connected_app_metadata_template` are gone from actions;
+  `link_metadata_template` is now `metadata_template`; the body carries the
+  destination URL itself instead of `{{ connected_app_form_url }}`; and
+  `updateMessageTracking` is keyed by the link's token, not a page token.

package/.agent/data_activation_clients.md

@@ -377,7 +377,7 @@ Three run shapes exist, selected by the bound tool's
 All three produce **log rows** observable through
 `api.dataActivationClients.logs.*` (§6.4), and the canonical way
 to **verify** that ingestion worked is the two-step
-dataset-search pattern in §6.5.
+dataset-search pattern in §6.6.
 
 ### 6.1 Inline JSON ingestion — `.ingest`
 
@@ -397,7 +397,7 @@ const { data } = await api.dataActivationClients.ingest(
 The response returns **immediately after enqueueing**, not
 after ingestion completes. To know when the row has actually
 been written, poll the logs (§6.4) or use the verification
-pattern (§6.5).
+pattern (§6.6).
 
 The `batch_id` is the most important field on the response —
 every downstream log row and dataset row carries the same
@@ -534,7 +534,110 @@ merge step has committed the ndjson archive. Use
 `output_files.length > 0` as the "this batch's rows are fully
 durable" signal — not just the presence of the log row.
 
-### 6.5 Verifying ingestion: the two-step dataset search
+### 6.5 Runs subresource — `.batches.list` / `.batches.get`
+
+A **run** is one record; the log rows of §6.4 are one record per
+dataset table that run wrote into. Read the run to answer *"is this
+over, and how did it end"*; read the logs for the per-table detail,
+filtered on the same `batch_id`.
+
+Before this record existed, the only way to ask whether a run had
+finished was to count log rows and guess — which cannot tell a run
+still going from one that produced nothing and never will. A run
+that was skipped or that died looked exactly like a slow one until
+the caller's timeout expired.
+
+```
+batch_id     UUID — the run identifier, the same one `.ingest`,
+                    `.ingestFile` and `.runManually` hand back, and the
+                    one stamped on every per-table log row of this run
+client_id    UUID — the owning activation client
+closed_at    ISO timestamp | null — when the run was attempted and
+                    exhausted. Null while it is still going. It does NOT
+                    mean rows landed and it does NOT mean the archive was
+                    merged — read `status` for the outcome, and only once
+                    this is set.
+status       'processing' | 'succeeded' | 'partial' | 'skipped' | 'failed'
+rows_total   number — source rows enqueued for this run. The run's own
+                    count; each per-table log keeps its own.
+inserted_at  ISO timestamp — when the run started
+```
+
+**`status` means nothing until `closed_at` is set.** A run in flight
+always reads `processing`. Once it is closed:
+
+| status | what happened |
+|---|---|
+| `succeeded` | it ran and nothing was refused |
+| `partial` | it ran and at least one row was refused on the way in; the rows that landed are still there |
+| `skipped` | it ran and there was nothing to do — empty file, every row filtered out, or the client has no contracts |
+| `failed` | it died before writing anything |
+
+```typescript
+// Paginated list of runs for an activation client. Takes the full Flop
+// query (page / page_size / order_by / order_directions / filters —
+// type_naming.md); without it, page 1 only.
+const { data } = await api.dataActivationClients.batches.list(
+  tenantSlug, datalakeSlug, activationClientSlug,
+  { page: 1, page_size: 50, order_by: ['inserted_at'], order_directions: ['desc'] },
+)
+// data.data — array of run records; data.meta — pagination
+
+// Fetch one run by its batch_id.
+const { data: run } = await api.dataActivationClients.batches.get(
+  tenantSlug, datalakeSlug, activationClientSlug, batchId,
+)
+```
+
+> **The fourth argument is the `batch_id`, not the record's `id`.**
+> A run record carries both, and both are UUIDs. The route looks the
+> run up by its `batch_id` — the identifier the ingest handed you — so
+> passing the record's own `id` is a **404**, not a type error.
+
+#### Waiting on a run
+
+This is what the run record is for. Poll until `closed_at` is set,
+then branch on `status` — never poll `status` alone, because a run
+in flight reads `processing` forever and tells you nothing:
+
+```typescript
+const { data: ingest } = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, activationClientSlug, { data: row },
+)
+
+const deadline = Date.now() + 120_000
+let run
+for (;;) {
+  const { data } = await api.dataActivationClients.batches.get(
+    tenantSlug, datalakeSlug, activationClientSlug, ingest.batch_id,
+  )
+  if (data.closed_at != null) { run = data; break }
+  if (Date.now() > deadline) throw new Error(`run ${ingest.batch_id} never closed`)
+  await new Promise((r) => setTimeout(r, 1_000))
+}
+
+if (run.status === 'failed') {
+  throw new Error(`run ${ingest.batch_id} failed before writing anything`)
+}
+if (run.status === 'skipped') {
+  throw new Error(`run ${ingest.batch_id} had nothing to do — check the row filter and the client's contracts`)
+}
+// 'succeeded' or 'partial' — the run is over and rows were written.
+// For a partial, read the log rows (§6.4) for which table refused what.
+```
+
+A run that failed or was skipped **ends the wait immediately, carrying
+why**. That is the whole difference from counting rows: a blind poll
+spends its full timeout and then reports nothing about the cause.
+
+> **`closed_at` is not the same as "my row is queryable".** It says the
+> run is over. It does not say the archive was merged (that is
+> `output_files` on the log rows, §6.4), and for one specific row it
+> does not replace the landing check in §6.6 — it makes that check a
+> single read after the run is known finished, instead of a guess
+> against a deadline.
+
+### 6.6 Verifying ingestion: the two-step dataset search
 
 > **Simplest landing check — `executeSql`.** Ingestion is async (the row
 > commits a moment after the `202`). When you just need to know a row
@@ -701,7 +804,7 @@ screen. Pick the mode by which of those two readers you are serving.
    response carries `batch_id` + `jobs_count`, signalling that
    downstream jobs have been enqueued — not that they've
    completed. Poll logs (or use the search verification
-   pattern in §6.5) before treating the row as ingested.
+   pattern in §6.6) before treating the row as ingested.
 
 7. **`dataset_updated > 0` is the load-bearing freshness
    gate.** `rows_ingested` flips as soon as the per-row job

package/.agent/datalakes.md

@@ -110,7 +110,7 @@ The platform does NOT expose a query API over the archive itself —
 cold reads happen externally so the platform's processes aren't
 responsible for analytical workloads. Live data lives in the
 datalake's Postgres halves (queryable via the dataset search
-two-step pattern in `data_activation_clients.md` §6.5); historical
+two-step pattern in `data_activation_clients.md` §6.6); historical
 data lives in the cloud-storage buckets configured here.
 
 ### Canonical create body

package/.agent/interoperability_contracts.md

@@ -299,7 +299,7 @@ in the datalake and there is nothing to search afterwards. The
 contract's `resource_type` destination) runs only when the DAC
 worker ingests a row — i.e. on `dataActivationClients.ingest`, not
 on `.run`. To prove a row *landed*, ingest and then query by
-`batch_id` (see `data_activation_clients.md` §6.5).
+`batch_id` (see `data_activation_clients.md` §6.6).
 
 ```typescript
 const { data: result } = await api.interoperabilityContracts.run(

package/.agent/mdm.md

@@ -26,10 +26,10 @@ master records.
 ## 1. Wire shape — `.verify`
 
 Verify that a person on the other end of a workflow action or a
-connected-app form submission matches an existing subject in the
+form behind an authenticated link matches an existing subject in the
 datalake. Used at action time (workflows confirming an SMS
-recipient) and at runtime (connected apps confirming the form
-submitter before posting tracking updates).
+recipient) and at runtime (the host behind `link_prefix` confirming
+the form submitter before posting tracking updates).
 
 Every MDM subject is ultimately a **person** or a **company**,
 and the request type is that ontology's identity vocabulary. You
@@ -339,7 +339,7 @@ SDK surface:
 
 Today there is no `.list`, `.get`, or `.metadata` on the MDM
 namespace — subjects themselves are queried through the dataset
-search surface (see `data_activation_clients.md` §6.5), not
+search surface (see `data_activation_clients.md` §6.6), not
 through `api.mdm`.
 
 ## 6. Gotchas

package/.agent/messages.md

@@ -44,7 +44,12 @@ alias: `m`.
          invalidated  (idempotency key collision — the fire was
                        rejected, nothing went out)
          received     (inbound message, direction: 'inbound')
-         clicked      (link in the message was clicked)
+
+   engagement, each with its own time:
+         read            read_at
+         opened          opened_at          the link host's page opened
+         clicked         clicked_at         a person first tapped a link
+         form_submitted  form_submitted_at  the link host's form was submitted
 ```
 
 `accepted` (the provider took the send request) and `sending`
@@ -53,13 +58,14 @@ and `sent`; the order above is the order the contract declares them.
 Treat any of them as "in flight, outcome unknown" — see **Status is
 eventually honest** below.
 
-Three different writers touch a message row. Know which is which:
+Four different writers touch a message row. Know which is which:
 
 | Writer | Writes | When |
 |---|---|---|
 | the action executor | the row itself; `pending`→`sent`, `external_id`, `sent_at`; also `duplicate` | at execution (writes the row at `pending`; advances to `sent` + sets `external_id` only on a live tool call — a dry-run stops at `pending`). Lands `duplicate` when the provider id it got back is already held by another send through the same tool |
 | the action status updater | `delivered` / `failed`, `delivered_at`, `failure_reason` | later, when its poll runs (see `action_status_updaters.md` §7) |
-| `connectedApps.updateMessageTracking` | `opened_at`, `form_submitted_at` — **never `status`** | when the recipient opens/submits the magic-link page |
+| `authenticatedLinks.exchange` | `clicked`, `clicked_at` (the first person's tap only) | when the host behind `link_prefix` forwards a tap; automated taps move nothing |
+| `authenticatedLinks.updateMessageTracking` | `opened` / `form_submitted`, `opened_at`, `form_submitted_at` | when the host reports its page opened or its form submitted; status only moves forward |
 
 Two consequences:
 

package/.agent/mock-services.md

@@ -95,21 +95,21 @@ flowchart TD
     end
 ```
 
-**It lives in this repo**, at `cloudflare-workers/mock/`. Deploy from a normal checkout:
+**It lives in this repo**, at `cloudflare/workers/mock/`. Deploy from a normal checkout:
 
 ```bash
-cd cloudflare-workers/mock && wrangler deploy
+cd cloudflare/workers/mock && wrangler deploy
 ```
 
 The single line that makes this work without a vendored copy of the corpus:
 
 ```jsonc
-"image_build_context": ".."
+"image_build_context": "../../.."
 ```
 
 That sets the Docker build context to the repo root, so the Dockerfile copies
 `wm_mappings/` and `wm_response_files/` from where they already live. Without it
-the context is `cloudflare-workers/mock/` and the corpus would have to be duplicated there —
+the context is `cloudflare/workers/mock/` and the corpus would have to be duplicated there —
 two directories that look identical until they quietly aren't.
 
 ### There is no authentication
@@ -190,4 +190,3 @@ flip.
 
 - [Tools](tools.md) — tool bodies, `endpoint_url`, and REST API auth methods
 - [Datalakes](datalakes.md) — how datalake provisioning uses MiniStack
-- [Connected Apps](connected_apps.md) — the third-party integrations the corpus stands in for