@abloatai/ablo 0.48.0 → 0.50.0

package/dist/coordination.d.ts

@@ -1,2 +1,10 @@
 export * from '@abloatai/transaction/coordination';
+/**
+ * Coordination vocabulary that the streams module declares.
+ *
+ * A caller that holds a claim, watches presence, or types an activity feed
+ * needs these names, and coordination is where they belong — so they are
+ * surfaced here rather than leaving callers to reach into the type module.
+ */
+export type { Activity, Claim, ClaimTarget } from '@abloatai/transaction/types/streams';
 //# sourceMappingURL=coordination.d.ts.map

package/dist/coordination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../src/coordination.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AAEnD;;;;;;GAMG;AACH,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,11 @@
 export * from '@abloatai/transaction';
 export { Ablo as default } from '@abloatai/transaction';
+/**
+ * The logger shape a caller passes in, and the no-op it can pass instead.
+ *
+ * Anything that supplies its own logging to the client has to name this type,
+ * so it belongs on the surface the client itself is imported from.
+ */
+export { noopLogger } from '@abloatai/transaction/logger';
+export type { Logger } from '@abloatai/transaction/logger';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -1,3 +1,10 @@
 export * from '@abloatai/transaction';
 export { Ablo as default } from '@abloatai/transaction';
+/**
+ * The logger shape a caller passes in, and the no-op it can pass instead.
+ *
+ * Anything that supplies its own logging to the client has to name this type,
+ * so it belongs on the surface the client itself is imported from.
+ */
+export { noopLogger } from '@abloatai/transaction/logger';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC"}

package/docs/agent-messaging.md

@@ -12,7 +12,7 @@ HTTP, or be replayed from the sync cursor.
 | Need | Use | Why |
 | --- | --- | --- |
 | "I am holding this row because..." | `claim({ description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
-| "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
+| "Remember this handoff/status/request" | A `messages` model | Durable row, replayed after reconnect and readable by HTTP agents. |
 
 Claim context is ephemeral. If a participant was offline, reconnected later, or
 only uses `transport: "http"`, it can miss claim/presence frames. Message rows
@@ -141,6 +141,6 @@ their cursor and see the rows they missed while offline.
 ## Retention
 
 Deleting or archiving old `messages` rows is your app's policy. The sync log is
-still durable audit/history: `sync_deltas` has no message-specific TTL. That is
+still durable audit/history: messages have no message-specific TTL. That is
 useful for coordination and compliance, but a chat-scale product should plan
 retention before writing high-volume conversation traffic.

package/docs/api.md

@@ -2,8 +2,8 @@
 
 > The per-method reference for every model call an agent or an interface can make.
 
-> **Upgrading?** Every breaking change and its migration is on the
-> [Version History & Migration Guide](./migration.md).
+> **Upgrading?** Follow the version-matched workflow in the
+> [Upgrade Guide](./migration.md), then read the intervening changelog entries.
 
 This is the per-method reference for reading and writing rows that stay in
 sync across sessions. You declare your models once, then call the same

package/docs/concurrency-convention.md

@@ -1,305 +1,119 @@
 # Concurrency Convention
 
-> The governing rule for how Ablo resolves concurrent writes to shared state.
+> What Ablo checks when a guarded write depends on earlier state.
 
-This page is the contract: the `onStale` dispositions, what a conflict is
-checked against, and where the convention stops. The three-layer mechanics of
-claiming live in [Coordination](./coordination.md).
+Ablo never infers whether a write depends on earlier state. You decide, in two
+places. The model's `conflict` setting in the schema says what each kind of
+participant does when it hits a conflict, and it is the policy for that model.
+A per-write `onStale` states the disposition for one write. Ablo enforces what
+you declared and nothing else.
 
----
+## Unguarded writes
 
-## 1. The principle: non-coercion
-
-**The engine surfaces the truthful current state and lets the intelligent actor —
-agent or human — decide what to do. It does not force a resolution.**
-
-That is the whole convention. Everything below is a consequence of it.
-
-Classical concurrency control is *coercive*: it imposes the remedy. Two-phase
-locking forces a block; optimistic concurrency forces an abort. Ablo's wager is
-that the actor in the loop (an agent reasoning over the change, or a human
-watching the row) is better placed to resolve a conflict than a fixed rule baked
-into the storage layer. So the engine's job narrows to one thing: **report what
-is true, on time, and get out of the way.**
-
-There are two forms of non-coercion, and they are the same principle at two
-moments in time:
-
-| form | when | mechanism |
-|---|---|---|
-| **Claim** | *prospective*: before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
-| **Notification** | *in-flight*: after a concurrent change | surface the changed value; the actor resolves and re-issues. |
-
-Use a claim when you will hold the row across a slow read→reason→write gap. Use a
-notification when you didn't, and the premise moved under you.
-
----
-
-## 2. The dispositions (`onStale`)
-
-Every guarded write (and every premise declared in §4) says what should happen
-when it goes stale. Three modes, split by whether they **force** an outcome:
-
-| mode | coercive? | what the engine does | who resolves | use when |
-|---|---|---|---|---|
-| `notify` | **No**: surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
-| `reject` | **Yes**: force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
-| `overwrite` | **Yes**: force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
-
-> `notify` is the convention. `reject` and `overwrite` are escape hatches for the
-> two ends — "never let this be wrong" and "never bother me." They are not the
-> spirit; they are the boundary of it.
-
----
-
-## 3. What is checked: two premises
-
-A conflict is a **premise intersection** — what your operation was based on
-overlaps a concurrent delta. Ablo checks two premises, and they are independent.
-They differ only in what declared them:
-
-| premise | declared by | question | scope |
-|---|---|---|---|
-| **Write-target** | per-op `readAt` | "did a row I'm **writing** change since I read it?" | the rows in `operations[]` |
-| **Batch** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
-
-The write-target check alone is the narrow case the canary anomaly defeats: an
-agent reads `deal.stage`, writes `task.status`, and a peer moves `deal.stage` —
-`task` never changed, so a write-target-only check waves it through. The batch
-premise closes that gap.
-
----
-
-## 4. The batch premise (`reads[]`)
-
-A commit may declare, at the batch level, what its writes were based on.
-Two granularities, developer's choice per entry:
+A plain write has no stale premise:
 
 ```ts
-reads: [
-  { model: 'Document', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
-  { group: 'workspace:abc', readAt: N, onStale: 'notify' },          // GROUP premise
-]
+await ablo.tasks.update({ id, data: { status: 'done' } });
 ```
 
-- **Row:** did this specific row (optionally these fields) change? The literal
-  per-object premise.
-- **Group:** did *anything* in this sync group change? `group` is a sync-group
-  key (`workspace:abc`, `document:s1`, `org:X`) — the same unit a participant **watches
-  and claims**. This is the more Ablo-native granularity.
+If no active claim conflicts with it, the write is last-write-wins. That is a
+choice rather than a fallback: use it for independent assignments where the
+latest value should win. When a model's writes are never independent, say so
+once in its `conflict` setting instead of at every call site.
 
-**Boundary — a stale premise fires over the whole batch.** Each entry covers
-*all* the writes in the commit, so its disposition governs the batch:
-`reject` aborts it, `notify` holds **every** write and notifies, `overwrite`
-lets them land. Per-entry `onStale` defaults to `reject`.
+## Guarded writes
 
----
+Pass the exact returned rows when a write is based on values previously read:
 
-## 5. The notification (`StaleNotification`)
-
-The non-coercive modes hand back data instead of throwing. The signal is
-delivered **twice**, by design — once as a value, once as an event:
-
-- On the **commit receipt**: `receipt.notifications` (and `CommitResult.notifications`).
-- On the **event channel**: `conflict:notified` (mirrors `reconciliation:needed` /
-  `sync:rollback`).
-
-Shape (canonical in `coordination/schema.ts`): one advisory in two scopes, told
-apart by `scope`, the same way `reads[]` entries come at two granularities.
+```ts
+const task = await ablo.tasks.get({ id });
+const policy = await ablo.policies.get({ id: policyId });
+if (!task || !policy) throw new Error('required input is missing');
+
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: 'done' },
+  reads: [task, policy],
+});
+```
 
-Both scopes carry:
+Ablo privately resolves each exact object to its model, id, and read watermark,
+then compares those premises with current state when the write is accepted.
+Clones, fabrications, and rows returned by another client are rejected locally.
 
-| field | meaning |
+| Disposition | If the premise is stale |
 |---|---|
-| `object` | stable type tag: `'stale_notification'` |
-| `scope` | `'row'` or `'group'` — which premise granularity fired |
-| `target` | **the row that moved**, and which parts: `{ model, id, fields }`. The same locator a claim names its subject with |
-| `readAt` | the watermark the committer reasoned against |
-| `observedSyncId` | the newest delta on the premise: re-read at/after this |
-| `writtenBy` | `{ kind, id }` of the concurrent author, reported faithfully |
-
-`scope: 'row'` adds:
+| `reject` | Reject the write with `AbloStaleContextError`. |
+| `notify` | Keep the current row, return a `StaleNotification`, and let the caller reconcile. |
+| `overwrite` | Apply the new value without enforcing the stale premise. |
 
-| field | meaning |
-|---|---|
-| `currentValues` | the live values of `target.fields`: the premise to reconcile against |
+`notify` is useful when an agent or human can merge the new information.
+`reject` is useful when the caller should restart from fresh state. Use
+`overwrite` only when the newer assignment should unconditionally win.
 
-`scope: 'group'` adds:
+## Functional updates
 
-| field | meaning |
-|---|---|
-| `group` | the group premise that fired (`report:abc`) |
-| `propagation?` | how `target` reached `group`: `{ via, through }` |
-| `changed?` | how much of the group moved: `{ count, sample, truncated }` |
+For a pure read-modify-write calculation, use the functional update form:
 
-`target` names the row that changed in **both** scopes. A group notification
-reports the moved row there and the premise it broke in `group`, so the two are
-never the same field.
+```ts
+await ablo.counters.update(counterId, (current) => ({
+  value: current.value + 1,
+}));
+```
 
-Only `notify` produces a notification (the write was held). `reject` throws and
-`overwrite` is silent — neither notifies.
+It performs the read, guarded write, and bounded reconciliation loop for you.
+See [Coordination](./coordination.md#functional-updates).
 
-### 5.1 The receive → reconcile loop
+## Claims
 
-You receive the signal two ways (same payload), then re-commit against the fresh
-watermark. The engine never re-issues for you — the actor decides.
+A claim protects a target across a longer interval. By default, other
+participants cannot write the claimed target, while contenders that claim it
+wait their turn. Reads remain open. A model's explicit conflict policy can
+choose a different disposition for a participant kind.
 
-```ts
-// Trigger: a guarded write under the non-coercive mode.
-const receipt = await ablo.task.update({
-  id, data: { status: 'blocked' },
-  readAt: myWatermark,
-  onStale: 'notify',
-});
+Claims and stale guards protect different things:
 
-// Receive — pull: the held write surfaces on the receipt.
-for (const n of receipt.notifications ?? []) resolve(n);
-
-// Receive — push: the same StaleNotification[] fires ambiently on the socket.
-ws.subscribe('conflict:notified', ({ notifications }) => notifications.forEach(resolve));
-
-function resolve(n: StaleNotification) {
-  // n.target     — the row that moved, and which fields (both scopes)
-  // n.writtenBy  — who moved it (e.g. { kind: 'agent', id: 'agent-b' })
-  if (n.scope === 'group') {
-    // "something in report:abc moved" — but `target` says WHICH row, so this is
-    // a one-row re-read, not a re-read of the group.
-    // n.propagation?.via — 'self' | 'parent' | 'transitive'
-    return refreshRow(n.target.model, n.target.id, n.observedSyncId);
-  }
-  // n.currentValues — what's actually there now (e.g. { status: 'done' })
-  if (!stillValid(n.currentValues)) return;       // premise gone → drop the write
-
-  return ablo.task.update({
-    id: n.target.id,
-    data: { status: 'blocked' },
-    readAt: n.observedSyncId,   // adopt the new high-water mark — this is what terminates the loop
-    onStale: 'notify',
-  });
-}
-```
+- A claim excludes other participants while it is held.
+- A stale guard proves that the state a write depended on has not changed.
+- A write made under a claim is still rejected if its own claimed snapshot has
+  become stale.
 
-The loop **terminates** because each retry advances `readAt` to `observedSyncId`;
-a peer that keeps writing only ever notifies you against a *newer* baseline, never
-the same one twice.
+See [Coordination](./coordination.md#claims) for the API.
 
-### 5.2 Reading a group notification
+## Cross-row and batch premises
 
-A group premise says "anything in this group", so the notification has to answer
-"what, exactly?" or the only correct response is to re-read the whole group —
-which on a busy group is how a reconcile loop turns into a large, repeated read.
+Model writes and lower-level commits can declare rows they read even when the
+write targets somewhere else. This protects decisions such as “update the task
+only if the deal I inspected has not changed.” A stale batch premise applies to
+the whole batch so atomicity is preserved.
 
-Four fields answer it:
+Use the high-level model methods unless you are building a custom runtime. When
+you do use batch premises, declare only the rows or groups that materially
+influenced the decision; overly broad premises create unnecessary contention.
 
-- **`target`** — the row that moved and the fields that changed on it. Usually a
-  one-row re-read.
-- **`group`** — the premise that fired.
-- **`propagation`** — how the row reached the group. `via: 'self'` means the row
-  *is* the group's scope root; `'parent'` means one containment edge below it;
-  `'transitive'` means further up, with `through` listing the intermediate
-  models (`['slides', 'decks']`).
-- **`changed`** — how much moved, in **distinct rows** rather than deltas.
-  `count` is the total, `sample` names the most recently changed (capped), and
-  `truncated` says whether the sample tells the whole story.
+## Notifications
 
-`changed` is what lets an actor decline. One row moved, re-read one row; twelve
-thousand moved, stop reasoning and resync the group — or abandon:
+A `StaleNotification` identifies the stale premise and provides the current
+state needed to reconcile. The original write has not been applied.
 
-```ts
-if (n.changed && n.changed.count > 50) return null; // too much moved — abandon the write
-for (const row of n.changed?.sample ?? []) await refresh(row.model, row.id);
-```
+A typical loop is:
 
-`propagation` is absent when the commit path has no record-group spec for the
-model, which is the one case where the server knows a group moved without
-knowing the route. Treat its absence as "re-read the group", the old behavior.
+1. Inspect the current value in the notification.
+2. Recompute the intended change.
+3. Submit a new guarded write with a fresh premise.
 
-### 5.3 Gating on what you know
+Give this loop a retry budget. Continuous contention should surface to the
+caller rather than retry forever.
 
-The notification tells you a belief moved. Whether that should *stop you writing*
-is a separate decision, and it belongs on the belief, not on the write.
+## Boundaries
 
-A `track` is a standing premise — what you are watching, with a watermark for
-when you last looked. Its disposition says what a move does to your next commit:
+Concurrency control does not replace:
 
-```ts
-await ablo.documents.track({ id: 's-1' });                     // notify — report it
-await ablo.documents.track({ id: 's-1', onStale: 'reject' });  // reject — gate my next write
-```
+- database constraints and transactions for application invariants;
+- authorization for deciding who may read or write;
+- idempotency for safely replaying the same request;
+- claims for exclusivity across slow, side-effecting work.
 
-`reject` refuses your next commit while that belief is stale, **even if the
-commit writes an unrelated row**. The gate is on what you *know*, not on what you
-are touching — which is the case a read→reason→write agent actually has.
-
-It is enforced at the commit chokepoint, so it is a guarantee rather than a
-convention. And the gate takes a key: it does not reopen on its own, because an
-agent retrying blindly would land exactly the write `reject` was asked to
-prevent. Re-read, then re-register the track to say you have. See
-[Groups](./groups.md#reporting-or-gating-onstale).
-
-A row that goes stale twice is telling you something: the read→reason→write gap
-wants the *prospective* guard, not the in-flight one. Escalate to a claim
-(§1) rather than raising `retries`.
-
----
-
-## 6. Boundaries & invariants
-
-What the convention **guarantees**, and where it **stops**:
-
-1. **Engine surfaces, actor decides.** Under `notify` the engine never
-   repairs, merges, or re-plans. It reports `currentValues` and the actor (agent
-   or human) owns the resolution. The engine does not distinguish them — it is
-   actor-neutral by design.
-
-2. **Truthfulness:** `currentValues` / `observedSyncId` reflect committed state at
-   detection time, inside the same transaction as the write. A notification is
-   never speculative.
-
-3. **No livelock, which is not the same as termination.** The monotonic
-   `sync_id` landing order is the serialization order. The stale committer
-   always yields/recomputes — an asymmetry that rules out the symmetric
-   notify-rewrite livelock, because each round adopts a newer `observedSyncId`
-   and no baseline is ever reasoned against twice.
-
-   It does **not** rule out starvation. A peer writing faster than your
-   read→decide→write gap keeps winning, and the engine never re-issues on your
-   behalf, so the rounds are yours and they are unbounded. Progress in the
-   watermark is not progress in the work — and for an agent, each round is a
-   model call. `update(id, fn)` bounds it for you and hands the conflict to
-   your updater (§5.3); a hand-rolled loop must bound itself.
-
-4. **Scope: reversible DB state only.** The convention governs writes to the
-   shared database, which are inherently reversible (prior value in
-   `sync_deltas`). **Irreversible external side-effects** (emails, payments,
-   third-party calls) are *out of scope* — the engine cannot hold or undo them,
-   so they must not be gated by `notify`.
-
-5. **Defaults.** A plain write (no `readAt`) is last-writer-wins with **no**
-   check. A guarded write with `readAt` but no `onStale` defaults to `reject`.
-
-6. **Policy seam.** Custom `ConflictPolicy` functions see **write-target**
-   conflicts (`stale_context` / `claim_held`). **Batch-premise** conflicts are
-   resolved directly via each entry's `onStale`, not through the policy seam.
-
-7. **Claims win when held.** A non-holder writing to a claimed row is rejected
-   (`AbloClaimedError`) regardless of `readAt` — the prospective form takes
-   precedence over the in-flight form. Only `user`/`system` principals may
-   `bypass` a foreign claim; agents may not.
-
----
-
-## 7. What this convention does not cover
-
-Three limits worth knowing before you rely on it.
-
-- **Irreversible external side-effects.** Emails, payments, and third-party
-  calls are not gated by this convention (§6.4). The engine cannot hold or undo
-  them, so never place one behind `notify`.
-- **A caller that declares nothing gets no check.** The batch premise catches
-  only what you declared. Write-target checking needs a `readAt` to compare
-  against, so a plain write with neither is last-writer-wins (§6.5). What you
-  declare is what is protected.
-- **`writtenBy.kind` reports what authenticated, not what you meant.** An `sk_`
-  key resolves to `system`, not `agent`. How identities map to participant kinds
-  is a separate concern from this convention.
+The rule is simple: the model's `conflict` setting is the policy, and each write
+declares what it read. Plain writes are last-write-wins because declaring
+nothing is itself a decision, so make it deliberately.

package/docs/context.md

@@ -0,0 +1,170 @@
+# Context
+
+> Assemble the current information for an action and carry its authoritative
+> Ablo reads into the write that follows.
+
+`context()` is a standalone SDK function. It does not run a model, keep a
+conversation, search documents, or create memory. The application chooses the
+values; Ablo awaits them and identifies the exact returned rows that can guard
+a later write.
+
+## Context, model, write
+
+This is the complete shape. `loadMemories()` and `parseTaskUpdate()` are
+application functions; they are not Ablo APIs.
+
+```ts
+import { context } from '@abloatai/ablo/context';
+import { contextMessage } from '@abloatai/ablo/ai-sdk';
+import { generateText } from 'ai';
+
+const ctx = await context({
+  ablo,
+  data: {
+    task: ablo.tasks.get({ id: taskId }),
+    documents: ablo.documents.list({ where: { taskId } }),
+    memory: loadMemories(taskId),
+  },
+});
+
+if (!ctx.data.task) throw new Error('Task not found');
+
+const result = await generateText({
+  model,
+  messages: [...history, contextMessage(ctx)],
+  tools,
+});
+
+await ablo.tasks.update({
+  id: ctx.data.task.id,
+  data: parseTaskUpdate(result.text),
+  reads: ctx.reads,
+});
+```
+
+If an authoritative row moves during the model call, the update rejects with
+`AbloStaleContextError`. Rebuild the context before trying again. The model is
+not called or retried by `context()`.
+
+## Choose the protection separately
+
+Context assembly and concurrency policy answer different questions. Choose the
+protection according to the work:
+
+| Situation | Use | Why |
+|---|---|---|
+| Bring several current values into one model call | `context()` | Awaits the selected values and collects their evidence. |
+| Reject if any selected Ablo row moves | `reads: ctx.reads` | Checks those premises when the write reaches the server. |
+| Avoid paying for a model call while another participant owns the row | `claim()` | Waits first, then supplies fresh state. |
+| Compute a patch from one current row without external work | Functional `update()` | Re-reads and retries the pure calculation. |
+
+A stale guard detects a change after the work has happened. When the work is
+slow or costly and must be exclusive, take a claim before assembling context.
+See [Coordination](./coordination.md) for the full choice.
+
+## Result
+
+The result has four members:
+
+| Member | Meaning |
+|---|---|
+| `data` | The selected values, with nested promises resolved. |
+| `reads` | Exact Ablo rows accepted by a write's `reads` option. |
+| `cursor` | The greatest watermark among those authoritative reads, or `null`. |
+| `sources` | One provenance summary for each top-level value. |
+
+If a row in `ctx.reads` moves before the write, the server rejects the write as
+stale. A plain value can inform the action, but it does not gain that guarantee.
+This distinction is visible in `sources`:
+
+```ts
+ctx.sources;
+// [
+//   { key: 'task', kind: 'ablo', guarantee: 'guardable', cursor: 42 },
+//   { key: 'memory', kind: 'value', guarantee: 'informational', cursor: null },
+// ]
+```
+
+A top-level value may contain both kinds. It is then marked `mixed` and only
+its exact Ablo rows appear in `ctx.reads`:
+
+```ts
+// data: { briefing: { task, memory } }
+// sources: [
+//   { key: 'briefing', kind: 'mixed', guarantee: 'partial', cursor: 42 },
+// ]
+```
+
+`partial` does not weaken the included Ablo rows. It says the surrounding value
+also contains information Ablo cannot guard.
+
+## External context
+
+Provider results pass through without an adapter or provider dependency. The
+functions below belong to the application; they may call Mem0, Turbopuffer,
+Reducto, or another system behind their own interfaces.
+
+```ts
+const ctx = await context({
+  ablo,
+  data: {
+    task: ablo.tasks.get({ id: taskId }),
+    memory: loadMemories({ query, userId }),
+    related: findRelatedChunks({ projectId, query }),
+    evidence: extractEvidence({ documentId }),
+  },
+});
+```
+
+These values are informational. Search ranking, citation versions, and memory
+quality remain guarantees of their own systems. They do not become canonical
+Ablo state unless the application writes them to an Ablo model and reads that
+row back.
+
+One rejected promise rejects the whole `context()` call. Requested information
+is never omitted silently.
+
+An absent row remains absent. It contributes no read evidence, so check required
+rows before calling a model. `context()` does not turn a missing read into a
+create-if-absent guard.
+
+## AI SDK
+
+The optional formatter produces a user message. It does not turn retrieved
+content into a system instruction and does not take ownership of the run.
+
+```ts
+import { contextMessage } from '@abloatai/ablo/ai-sdk';
+import { generateText } from 'ai';
+
+await generateText({
+  model,
+  messages: [
+    ...history,
+    contextMessage(ctx, { include: ['task', 'documents', 'memory'] }),
+  ],
+  tools,
+});
+```
+
+Selection, trimming, token budgets, conversation history, and model execution
+remain application or framework policy. Applications may format `ctx.data`
+themselves.
+
+## Current limits
+
+The first version deliberately has no:
+
+- search or memory API;
+- provider registry or provider-specific adapter;
+- `since` cursor or incremental `changes` result;
+- context session, persistence, or sharing lifecycle;
+- token counting, trimming, summarisation, or model call;
+- guarantee that a person or model understood the included information.
+
+Store `ctx.cursor` in application-owned state if it is useful. Incremental
+context is not yet derived from it.
+
+`context` remains available as a schema model name. The helper lives at
+`@abloatai/ablo/context`; it does not add `ablo.context()` or reserve a member
+of the schema-backed client.