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

package/.agent/cookbook/subscription-saas.md

@@ -54,7 +54,7 @@ shows.
 | SMS tool, LLM tool                | Shared by every workflow below            |
 | Contract pair, on two clients     | Identity and table row, deliberately split|
 | Three workflows                   | Welcome, dunning, priority triage         |
-| Two connected apps                | The portal link, and the pay link         |
+| Authenticated links               | The portal link, and the pay link         |
 | Manual-upload, bulk and REST paths| Three ways into the same table            |
 | An invitation                     | A second person on the tenant             |
 
@@ -897,38 +897,30 @@ if (unstamped.length > 0) {
 }
 ```
 
-## 015 — the billing-portal connected app
+## 015 — the billing portal, and the host in front of it
 
-The welcome SMS carries a deep link to the self-serve billing portal. A
-connected app is a thin registration of that page's URL and hosting mode; the
-page itself lives outside the platform (`mode: 'self_hosted'`). Capture the
-server-derived slug — resolving the link in §019 is addressed by it.
+The welcome SMS carries a link to the self-serve billing portal, which lives
+outside the platform. Two addresses are in play, and neither is registered
+with the platform — there is nothing to create here.
+
+The **portal page** is the URL written into the SMS body, exactly as the
+customer should end up seeing it. The **link prefix** is the host you run in
+front of it: at send the platform swaps every URL in the body for
+`<link_prefix>/<token>`, a link minted for this one message, and a tap on it
+reaches that host first. The host asks the platform what the link is, then
+sends the customer on to the portal — §019 does exactly that.
+
+A path is allowed in the prefix; a query, a fragment or a trailing slash is
+not, because the platform appends `/<token>` itself.
 
 ```typescript
-const portalApp = await ctx.ensure(
-  'billing-portal connected app',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug, { page_size: 100 })
-    return ctx.firstNamed(data.data, 'Cookbook Billing Portal')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook Billing Portal',
-      description: 'Self-serve billing portal linked from the outbound welcome SMS.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://billing.example.local', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-connectedAppId = portalApp.id!
-ctx.portalAppId = portalApp.id!
-ctx.portalAppSlug = portalApp.slug!
+ctx.billingPortalUrl = 'https://billing.example.local/portal/welcome'
+ctx.billingLinkPrefix = 'https://go.billing.example.local/l'
 ```
 
 ## 016 — the Welcome SMS workflow
 
-Standard shape — a filter, a decision, one action — with three things worth
+Standard shape — a filter, a decision, one action — with four things worth
 reading closely.
 
 `dataset_type: 'generic_table'` with `generic_table_id` makes §009's table
@@ -937,10 +929,15 @@ filter reads `event_dataset.phone` directly.
 
 `skip_mdm_resolution: false` is set explicitly, and must be. A generic-table
 row is never its own subject — the subject is the legal entity §011's pair
-stamped onto it. With resolution on, the platform loads that subject and
-mints a page token against it, which is what makes
-`{{ connected_app_form_url }}` a *per-customer* link. Skip it and the token
-is never minted and the link renders empty.
+stamped onto it. With resolution on, the platform loads that subject, and
+the message — and the link minted with it — names *this customer* as its
+`legal_entity_id`. Skip it and the link still resolves, but it cannot say
+whose portal session it opens.
+
+The body carries §015's portal URL itself, and the action's `link_prefix`
+turns it into this message's own link at send — `link_prefix` is required
+on every SMS call. `metadata_template` renders once per send and rides on
+the message, so the host gets the customer number back with the link.
 
 The `context_datasets` entry queries the `message` dataset for a welcome
 already sent to this legal entity in the last six months — the platform's
@@ -997,9 +994,7 @@ const welcomeWorkflow = await ctx.ensure(
           position: 0,
           trigger_template: 'now',
           idempotency_template: `{{ event_dataset.customer_number }}-${WELCOME_KEY}`,
-          connected_app_id: ctx.portalAppId,
-          connected_app_route: '/portal/welcome',
-          connected_app_metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
+          metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ event_dataset.phone }}' },
@@ -1007,9 +1002,10 @@ const welcomeWorkflow = await ctx.ensure(
               type: 'custom',
               body:
                 'Hi {{ event_dataset.name }}, welcome to Alvera Billing. ' +
-                'Self-serve billing portal: {{ connected_app_form_url }}',
+                `Self-serve billing portal: ${ctx.billingPortalUrl}`,
             },
             sms_type: 'transactional',
+            link_prefix: ctx.billingLinkPrefix,
           },
         },
       ],
@@ -1130,11 +1126,24 @@ workflow resource is: recreate it against a lake that still holds its rows
 and the id changes while the key does not — the action then correctly refuses
 to fire, and a search for the new id finds nothing at all.
 
-Then resolve the `/t/<token>` the platform baked into the body when it minted
-the page token, and post the tracking a connected-app frontend would post
-when the customer opens the portal. That closes the loop: the message went
-out, the link in it resolves to this customer's page, and the open was
-recorded.
+The stored body is the body as sent, so the portal URL is not in it: in its
+place stand the link prefix and a fifteen-character token. Finding the portal
+URL itself would mean no link was minted.
+
+Then play the host behind the prefix. Hand the token to
+`authenticatedLinks.exchange` with what the tap's request said about itself —
+a phone's browser, because the platform judges from those details whether a
+person tapped, and only a person's tap stamps `link_clicked_at` and the
+message's `clicked_at`. The answer names the customer and carries the
+customer number on `message.metadata`. Both calls need only the tenant's
+publishable key.
+
+Then the portal reports what the customer did, with the same token. The
+message status only moves forward, and `opened` ranks below `clicked`, so
+reporting `opened` after the tap leaves the status at `clicked` while
+`opened_at` still lands; `form_submitted` ranks above both, so the message
+ends there. That closes the loop: the message went out, the link in it leads
+to this customer's page, and the open and the submission were recorded.
 
 ```typescript
 const { data: search } = await api.datasets.createUserSearch(tenantSlug, datalakeSlug, 'message', {
@@ -1153,7 +1162,7 @@ while (Date.now() < msgDeadline && !welcomeBody) {
   })
   welcomeBody = ((data.data ?? []) as Array<Record<string, unknown>>)
     .map((m) => String(m.body ?? ''))
-    .find((body) => body.includes('/t/') && body.includes('welcome to Alvera Billing'))
+    .find((body) => body.includes('welcome to Alvera Billing'))
   if (!welcomeBody) await new Promise((r) => setTimeout(r, 2_000))
 }
 if (!welcomeBody) {
@@ -1162,60 +1171,67 @@ if (!welcomeBody) {
       'the action never fired, or it fired under a different idempotency key',
   )
 }
-const tokenMatch = welcomeBody.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!tokenMatch) throw new Error(`no /t/<token> in the rendered body: ${welcomeBody}`)
+if (welcomeBody.includes(ctx.billingPortalUrl)) {
+  throw new Error(`the portal URL went out as written, so no link was minted: ${welcomeBody}`)
+}
+const welcomeLinkStart = `${ctx.billingLinkPrefix}/`
+const welcomeToken = welcomeBody.split(welcomeLinkStart)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+if (!welcomeToken) throw new Error(`no ${welcomeLinkStart}<token> in the welcome body: ${welcomeBody}`)
 
-const { data: resolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.portalAppSlug,
-  { short_path: tokenMatch[1]!, user_agent: 'cookbook-doctest/subscription-saas' },
-)
-if (resolved.route_path !== '/portal/welcome') {
-  throw new Error(`resolvePage route_path mismatch: ${resolved.route_path}`)
+const { data: tap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: welcomeToken,
+  method: 'GET',
+  user_agent:
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 ' +
+    '(KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+  headers: { 'accept-language': 'en-US' },
+})
+if (tap.destination_url !== ctx.billingPortalUrl) {
+  throw new Error(`the welcome link should lead to ${ctx.billingPortalUrl}, got ${tap.destination_url}`)
+}
+if (!tap.legal_entity_id) {
+  throw new Error('the welcome link names no customer — MDM resolution did not reach the message')
 }
-if (!(resolved.message?.body ?? '').includes('welcome to Alvera Billing')) {
-  throw new Error('the resolved page carries the wrong message')
+if (tap.message.metadata?.customer_number !== ctx.reachNumber) {
+  throw new Error(`metadata_template did not reach the message: ${JSON.stringify(tap.message.metadata)}`)
 }
+if (!tap.link_clicked_at || !tap.message.clicked_at) {
+  throw new Error("a person's tap should stamp link_clicked_at and the message's clicked_at")
+}
+ctx.reachCustomerId = tap.legal_entity_id
 
 const now = new Date().toISOString()
-const { data: tracked } = await api.connectedApps.updateMessageTracking(
-  tenantSlug, datalakeSlug, ctx.portalAppSlug,
-  { short_path: tokenMatch[1]!, opened_at: now, form_submitted_at: now },
-)
-if (!tracked.message?.opened_at || !tracked.message?.form_submitted_at) {
+await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: welcomeToken,
+  status: 'opened',
+  opened_at: now,
+})
+const { data: tracked } = await api.authenticatedLinks.updateMessageTracking(tenantSlug, datalakeSlug, {
+  token: welcomeToken,
+  status: 'form_submitted',
+  form_submitted_at: now,
+})
+if (!tracked.message.opened_at || !tracked.message.form_submitted_at) {
   throw new Error('message tracking did not persist opened_at + form_submitted_at')
 }
+if (tracked.message.status !== 'form_submitted') {
+  throw new Error(`the message should end at form_submitted, got ${tracked.message.status}`)
+}
 ```
 
-## 020 — the pay-portal connected app
+## 020 — the payment page, behind the same host
 
 The dunning SMS carries a different link to a different page: not the
-welcome portal but the one where an overdue invoice gets paid. A second
-connected app, registered the same way.
+welcome portal but the one where an overdue invoice gets paid.
 
-Two apps rather than two routes on one app is a deliberate choice worth
-naming. A connected app is the unit a page token is minted against, so
-separating them means a token issued for a payment page cannot be replayed
-against the welcome page, and revoking one does not take the other down.
+**One host answers both.** The link prefix is only where taps arrive; where a
+link leads is fixed at send, from the URL written into its own message, and
+comes back from the exchange. So the payment page reuses §015's prefix, and a
+link minted for the payment page can never be made to open the welcome page
+— there is no route on the link for anyone to change.
 
 ```typescript
-const payApp = await ctx.ensure(
-  'pay-portal connected app',
-  async () => {
-    const { data } = await api.connectedApps.list(tenantSlug, datalakeSlug, { page_size: 100 })
-    return ctx.firstNamed(data.data, 'Cookbook Payment Portal')
-  },
-  async () => {
-    const { data } = await api.connectedApps.create(tenantSlug, datalakeSlug, {
-      name: 'Cookbook Payment Portal',
-      description: 'Self-serve payment page linked from the outbound dunning SMS.',
-      mode: 'self_hosted',
-      urls: [{ url: 'https://pay.example.local', is_primary: true, label: 'production' }],
-    })
-    return data
-  },
-)
-ctx.payAppId = payApp.id!
-ctx.payAppSlug = payApp.slug!
+ctx.paymentPageUrl = 'https://pay.example.local/portal/pay'
 ```
 
 ## 021 — the Dunning SMS workflow: two gates, not one
@@ -1282,9 +1298,7 @@ const dunningWorkflow = await ctx.ensure(
           position: 0,
           trigger_template: 'now',
           idempotency_template: `{{ event_dataset.customer_number }}-${DUNNING_KEY}`,
-          connected_app_id: ctx.payAppId,
-          connected_app_route: '/portal/pay',
-          connected_app_metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
+          metadata_template: '{"customer_number":"{{ event_dataset.customer_number }}"}',
           tool_call: {
             tool_call_type: 'sms_request',
             to: { type: 'custom', body: '{{ event_dataset.phone }}' },
@@ -1293,9 +1307,10 @@ const dunningWorkflow = await ctx.ensure(
               body:
                 'Hi {{ event_dataset.name }}, an invoice on account ' +
                 '{{ event_dataset.customer_number }} needs your attention. ' +
-                'Pay now: {{ connected_app_form_url }}',
+                `Pay now: ${ctx.paymentPageUrl}`,
             },
             sms_type: 'transactional',
+            link_prefix: ctx.billingLinkPrefix,
           },
         },
       ],
@@ -1372,12 +1387,12 @@ if ((byStatus.filtered ?? 0) !== 1) {
 }
 ```
 
-## 023 — the reminder went out, and it is a different message on a different app
+## 023 — the reminder went out, and it is a different message to a different page
 
 Same read-back idiom as §019, and worth doing twice for one reason: it proves
 the two workflows are genuinely independent. The same customer received two
-messages, under two idempotency keys, carrying two links that resolve against
-two connected apps and two routes.
+messages, under two idempotency keys, carrying two links with two different
+tokens that lead to two different pages — and both name the same customer.
 
 The key here is `<customer number>-send_dunning_sms`, and it names a row that
 persists in the lake long after the run that made it. That is what a
@@ -1400,7 +1415,7 @@ while (Date.now() < msgDeadline && !dunningBody) {
   })
   dunningBody = ((data.data ?? []) as Array<Record<string, unknown>>)
     .map((m) => String(m.body ?? ''))
-    .find((body) => body.includes('/t/') && body.includes('needs your attention'))
+    .find((body) => body.includes('needs your attention'))
   if (!dunningBody) await new Promise((r) => setTimeout(r, 2_000))
 }
 if (!dunningBody) {
@@ -1410,15 +1425,25 @@ if (!dunningBody.includes(ctx.reachNumber)) {
   throw new Error(`the dunning body does not name the overdue account: ${dunningBody}`)
 }
 
-const token = dunningBody.match(/\/t\/([A-Za-z0-9_-]+)/)
-if (!token) throw new Error(`no /t/<token> in the dunning body: ${dunningBody}`)
+if (dunningBody.includes(ctx.paymentPageUrl)) {
+  throw new Error(`the payment page went out as written, so no link was minted: ${dunningBody}`)
+}
+const dunningToken = dunningBody.split(`${ctx.billingLinkPrefix}/`)[1]?.match(/^[A-Za-z0-9_-]{15}/)?.[0]
+if (!dunningToken) throw new Error(`no ${ctx.billingLinkPrefix}/<token> in the dunning body: ${dunningBody}`)
 
-const { data: resolved } = await api.connectedApps.resolvePage(
-  tenantSlug, datalakeSlug, ctx.payAppSlug,
-  { short_path: token[1]!, user_agent: 'cookbook-doctest/subscription-saas' },
-)
-if (resolved.route_path !== '/portal/pay') {
-  throw new Error(`the dunning link resolved to the wrong route: ${resolved.route_path}`)
+const { data: tap } = await api.authenticatedLinks.exchange(tenantSlug, datalakeSlug, {
+  token: dunningToken,
+  method: 'GET',
+  user_agent:
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 ' +
+    '(KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
+  headers: { 'accept-language': 'en-US' },
+})
+if (tap.destination_url !== ctx.paymentPageUrl) {
+  throw new Error(`the dunning link should lead to ${ctx.paymentPageUrl}, got ${tap.destination_url}`)
+}
+if (tap.legal_entity_id !== ctx.reachCustomerId) {
+  throw new Error(`both links should name the same customer (${ctx.reachCustomerId}), got ${tap.legal_entity_id}`)
 }
 ```
 
@@ -1596,6 +1621,11 @@ band. Whichever band comes back picks one and leaves the other two
 hyphens, and Liquid's dot parser would read
 `additional_context.cookbook-priority-triage-agent` as a subtraction.
 
+`link_prefix` is required on every SMS call, these three included, though
+their bodies carry no URL — a body with none is sent unchanged. Leave it off
+and the workflow is refused at create with a 422 on
+`/actions/<n>/tool_call/link_prefix`.
+
 ```typescript
 const BANDS = ['priority_high', 'priority_medium', 'priority_low'] as const
 
@@ -1646,6 +1676,7 @@ const triageWorkflow = await ctx.ensure(
             body: `[${band}] {{ event_dataset.name }}, a note about account {{ event_dataset.customer_number }}.`,
           },
           sms_type: 'transactional' as const,
+          link_prefix: ctx.billingLinkPrefix,
         },
       })),
       workflow_ai_agents: [
@@ -2369,8 +2400,8 @@ After all forty-one steps run green, on one tenant and **one raw datalake**:
   reachability *and* KYC, and the triage workflow hands the question to a
   model and fans out on its answer.
 - **Three outbound messages** are readable from the `message` dataset, each
-  under its own idempotency key, two carrying deep links that resolve against
-  two separate connected apps on two separate routes.
+  under its own idempotency key, two carrying authenticated links — one host,
+  two tokens, two pages, one customer named by both.
 - **A second person** is on the tenant with a `member` role, invited and
   accepted entirely through the SDK.
 
@@ -2401,4 +2432,4 @@ Four things this walk teaches that are easy to learn the expensive way:
   and `workflows.run`
 - `../data_activation_clients.md` — data source → tool → contract → client
 - `../interoperability_contracts.md` — `template_config` vs `mdm_input_config`
-- `../connected_apps.md` — registration, `resolvePage`, message tracking
+- `../authenticated_links.md` — `link_prefix`, `exchange`, message tracking

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

package/.agent/mutations.md

@@ -12,7 +12,7 @@ everything:
    downstream references — never pre-compute a server-derived field yourself.
 
 Non-CRUD methods are out of scope for this page — RESTful sub-actions
-(`.syncRoutes`, `.resolvePage`, `.testInvocation`), artifact issuers
+(`.testInvocation`, `.refresh`), artifact issuers
 (`.createUploadLink`, `.createDownloadLink`), and async triggers (`.run`,
 `.execute`, `.ingest`) each document their own semantics in their resource's MD.
 
@@ -53,9 +53,9 @@ A small set of methods accept a narrow partial body instead of replacing the
 whole resource. Each is named here and documents its partial-body contract in
 its TypeScript method's JSDoc and its per-resource MD §5 (Lifecycle):
 
-| SDK method                                  | Resource MD          |
-|---------------------------------------------|----------------------|
-| `api.connectedApps.updateMessageTracking`   | `connected_apps.md`  |
+| SDK method                                       | Resource MD               |
+|--------------------------------------------------|---------------------------|
+| `api.authenticatedLinks.updateMessageTracking`   | `authenticated_links.md`  |
 
 For every other method, the default holds: `update()` replaces the whole
 resource.