@abloatai/ablo 0.34.1 → 0.36.0

package/docs/migration.md

@@ -1,5 +1,7 @@
 # Version History & Migration Guide
 
+> Every breaking change and the edit it requires, newest first.
+
 The breaking-changes-first companion to the [Changelog](../CHANGELOG.md). The
 changelog tells the story of each release; this page tells you exactly what to
 change when you upgrade.
@@ -11,6 +13,9 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.36.0** | `ttlSeconds` deprecated on the join surfaces in favour of `ttl` | `useJoin({ scope, ttlSeconds: '5m' })` → `useJoin({ scope, ttl: '5m' })`; same for `ParticipantJoinOptions`. Both spellings work until 0.37.0 |
+| **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.retrieve(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
+| **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
 | **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
 | **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
 | **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useJoin` |
@@ -27,7 +32,79 @@ change when you upgrade.
 
 ---
 
-## 0.34.0 — presence verb renamed `watch` → `join`
+## 0.36.0: one lease is spelled `ttl`
+
+```diff
+- useJoin({ scope: { documents: [id] }, ttlSeconds: '5m' })
++ useJoin({ scope: { documents: [id] }, ttl: '5m' })
+```
+
+`ablo.<model>.join(ids, { ttl })` has always said `ttl`, and so does every other
+lease in the SDK: `claim`'s `ttl`, `ClaimLeaseOptions.ttl`. The lower-level join
+surfaces said `ttlSeconds` while accepting exactly the same values, including
+duration strings, so a `ttl: '5m'` handed down from the model verb arrived as
+`ttlSeconds: '5m'`, a field asserting a unit its value did not carry.
+
+Both spellings work until 0.37.0, and `ttl` wins if you pass both. The wire is
+unchanged: it has always carried seconds and still does.
+
+---
+
+## 0.35.0: the synchronous reads move under `local`
+
+```diff
+- const task  = ablo.tasks.get(id);
+- const open  = ablo.tasks.getAll({ where: { status: 'open' } });
+- const count = ablo.tasks.getCount({ where: { status: 'open' } });
++ const task  = ablo.tasks.local.retrieve(id);
++ const open  = ablo.tasks.local.list({ where: { status: 'open' } });
++ const count = ablo.tasks.local.count({ where: { status: 'open' } });
+```
+
+Options, return types, and reactivity inside `useAblo` selectors are unchanged.
+Every verb now matches its asynchronous sibling, and `local` narrows the read to
+what has already synced — which is what lets it return a value rather than a
+promise.
+
+`getAll` and `getCount` are distinctive enough to rename by search. `get` is not:
+in most codebases it is outnumbered many times over by `Map.get` and
+`headers.get`, and no search separates them. Upgrade the package first and let
+the compiler name the sites — each one is a type error at exactly the call that
+has to move.
+
+## 0.35.0: `causedByTaskId` and the `turn_*` error codes removed
+
+0.9.2 retired the `turn` primitive but left one field standing: `causedByTaskId`
+on the write options bag. It was never usable. The server validated it against a
+task record that nothing in the system has ever created, so supplying it had the
+whole batch rejected with `turn_validation_failed`, while leaving it null passed
+straight through. The safe way to use the option was to not use it.
+
+**Removed:** `MutationOptions.causedByTaskId`, the seven `turn_*` error codes
+(`turn_validation_failed`, `turn_open_failed`, `turn_close_failed`,
+`turn_not_found`, `turn_foreign_agent`, `parent_turn_not_found`,
+`parent_turn_foreign_agent`), and the stored row's provenance slice
+(`deltaProvenanceSchema` and the `DeltaProvenance` type). `syncDeltaRowSchema` is
+now the core and attribution slices composed.
+
+```diff
+- await ablo.documents.update({ id, data, causedByTaskId: turnId });
++ await ablo.documents.update({ id, data });
+```
+
+Attribution is unaffected. A delta still records the actor, the `onBehalfOf`
+principal behind a delegated write, the capability that authorized it, and the
+claim it was made under — which is what answers "who did this, and by what
+right." On the wire the field was optional and nullable, so a client that still
+sends it is accepted and ignored.
+
+The `caused_by_task_id` column stays, for the reason 0.9.2 gave when it kept it:
+the audit hash-chain signs its value into every row. Dropping it is a versioned
+migration of its own.
+
+---
+
+## 0.34.0: presence verb renamed `watch` → `join`
 
 The model-level presence verb read like a data subscription but delivered
 presence — who else is on a row and what they hold — so it now says what it
@@ -35,13 +112,13 @@ does. `ablo.<model>.join(ids, { ttl })` opens the participant handle
 (`.peers`, `.claims`, `await using` disposal); the returned `status` was
 already `'joined'`, and the layer beneath always called itself `join`, so the
 verb now matches. `onChange` remains the way to hear row *values* change, and
-`track` remains the durable read-dependency for actors.
+`track` remains the durable premise for actors.
 
 ```ts
 // before
-await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+await using room = await ablo.documents.watch(documentIds, { ttl: '5m' });
 // after
-await using room = await ablo.slides.join(slideIds, { ttl: '5m' });
+await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
 ```
 
 The React hook follows: `useWatch({ scope })` → `useJoin({ scope })`. There is
@@ -50,7 +127,7 @@ no compatibility alias — rename the call sites and the `WatchOptions` /
 
 ---
 
-## 0.28.0 — dead React multiplayer placeholders removed
+## 0.28.0: dead React multiplayer placeholders removed
 
 Four React exports looked usable but had no live implementation:
 
@@ -65,7 +142,7 @@ Four React exports looked usable but had no live implementation:
 There is no compatibility alias: the replacement APIs were already the only
 working paths.
 
-## 0.11.0 — `intent` → `claim` rename completed
+## 0.11.0: `intent` → `claim` rename completed
 
 > **Historical note:** this section documents the 0.11.0 transition.
 > `useClaim` was subsequently removed in 0.28.0 because its provider callback
@@ -108,7 +185,7 @@ contending holders (`AbloClaimedError.claims` and a policy reason folded into th
 message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
 on presence and claim state.
 
-## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
+## 0.10.0: environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)
 
@@ -148,7 +225,7 @@ distinct stores.
 server-side actors (agents, workers, serverless): the same `ablo.<model>` surface
 and `claim` coordination, but each call is one HTTP round-trip with identity on
 the Bearer credential — no websocket, no local synced pool. The return type
-narrows, so stateful-only APIs (`get` / `getAll` / `onChange`) become compile
+narrows, so stateful-only APIs (the `local` reads, `onChange`) become compile
 errors instead of latent runtime gaps. Existing code keeps the default
 `'websocket'` transport, unchanged.
 
@@ -164,7 +241,7 @@ await ablo.tasks.update({ id, data: { status: 'done' } });
 
 ---
 
-## 0.9.2 — `turn` / agent-`tasks` removed; `intents` deprecated
+## 0.9.2: `turn` / agent-`tasks` removed; `intents` deprecated
 
 The SDK's coordination surface is now exactly two things: `ablo.<model>` writes
 and `claim`. The parallel `turn` / agent-`tasks` mechanism was redundant —
@@ -213,7 +290,7 @@ everywhere you coordinate concurrent work.
 
 ---
 
-## 0.9.0 — one options object per verb; disposable `claim`
+## 0.9.0: one options object per verb; disposable `claim`
 
 Every model verb takes a single options object, so the id, the data, and every
 modifier are named siblings. Reactive local reads stay on the synchronous
@@ -227,7 +304,7 @@ modifier are named siblings. Reactive local reads stay on the synchronous
 + await ablo.tasks.retrieve({ id })
 
 - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
-+ useAblo((ablo) => ablo.tasks.get(id)) ?? serverTask
++ useAblo((ablo) => ablo.tasks.local.retrieve(id)) ?? serverTask
 ```
 
 `claim` now returns a disposable handle instead of taking a callback. The handle
@@ -247,7 +324,7 @@ options object.
 
 ---
 
-## 0.8.0 — callable `claim` namespace
+## 0.8.0: callable `claim` namespace
 
 The flat coordination methods are gone; everything lives under `claim`.
 
@@ -260,7 +337,7 @@ The flat coordination methods are gone; everything lives under `claim`.
 
 ---
 
-## 0.7.0 — legacy React hooks removed
+## 0.7.0: legacy React hooks removed
 
 The query/mutation hooks were replaced by the single `useAblo()` accessor over
 typed model methods.
@@ -282,7 +359,7 @@ shape with the canonical `{ type, code, message, doc_url, request_id }` envelope
 
 ---
 
-## 0.6.0 — `onChange` and the Resource → Model rename
+## 0.6.0: `onChange` and the Resource → Model rename
 
 ```diff
 - ablo.tasks.subscribe(cb)
@@ -298,7 +375,7 @@ Also renamed: `Ablo.Resource.*` → `Ablo.Model.*`, `ModelTarget.resource` →
 
 ---
 
-## 0.5.0 — intent-handle method renames
+## 0.5.0: intent-handle method renames
 
 On the model intent handle (`ablo.<model>.intent(id)`):
 
@@ -315,7 +392,7 @@ unchanged at this release. (They were later folded under `claim` in 0.9.2.)
 
 ---
 
-## 0.3.0 — umbrella `<AbloProvider>`
+## 0.3.0: umbrella `<AbloProvider>`
 
 One provider component now owns the full React lifecycle. `<SyncProvider>`,
 `createAbloContext()`, and `withSync` were removed.
@@ -349,10 +426,10 @@ old code or old docs, this is the through-line:
 
 | Release | State of coordination |
 |---|---|
-| 0.4.0 | `ablo.<model>.intent(id)` introduced — per-entity intent handle |
+| 0.4.0 | `ablo.<model>.intent(id)` introduced: per-entity intent handle |
 | 0.5.0 | Intent-handle methods renamed to claim vocabulary (`acquire`→`claim`, …) |
 | 0.8.0 | Callable `claim` namespace (`claim(id)`, `claim.state`, `claim.queue`, …) |
 | 0.9.0 | `claim` returns an `await using` disposable handle |
-| 0.9.2 | `intents` deprecated and made `@internal` — **`claim` is the one coordination API** |
+| 0.9.2 | `intents` deprecated and made `@internal`: **`claim` is the one coordination API** |
 
 For the full chronological history, see the [Changelog](../CHANGELOG.md).

package/docs/operating-on-your-database.md

@@ -1,5 +1,7 @@
 # Operating on Your Database
 
+> Which actions run freely, which to verify first, and which belong to a human.
+
 Ablo sits over your database as a coordination layer, not an owner. It reads
 your Postgres replication stream and routes each write through a claim-checked
 commit that lands in your own tables. It never runs DDL, never migrates, never
@@ -79,7 +81,7 @@ code question. The question that governs safety is *does removing this drop a
 real table on the next push* — and that one is answered against the database,
 not the codebase. Before removing a model that maps a live table, confirm the
 table is gone or empty and that your push path is additive; otherwise keep the
-model until the data is dealt with. A `load: 'manual'` mapping is often present
+model until the data is dealt with. A `load: 'lazy'` mapping is often present
 precisely to hold a table in place, so treat its comment as load-bearing.
 
 ## The verification loop

package/docs/projects.md

@@ -1,5 +1,7 @@
 # Projects
 
+> One organization, many apps — each with its own schema, data planes, and keys.
+
 A **project** is the isolation unit inside your organization — the shape you
 know from Neon or Supabase. Each app you build gets its own project, and each
 project gets its own schema, its own sandbox/production data planes, and its
@@ -93,5 +95,5 @@ another org's project ids 404 — never confirm existence across orgs.
 
 | Code | Status | Meaning |
 |------|--------|---------|
-| `project_scope_denied` | 403 | The model/resource belongs to another project in your org — use a key minted for that project. |
+| `project_scope_denied` | 403 | The model/resource belongs to another project in your org: use a key minted for that project. |
 | `project_slug_taken` | 409 | A project with this slug already exists in the organization. |

package/docs/quickstart.md

@@ -1,7 +1,9 @@
 # Quickstart
 
+> Make your first coordinated write, on the Postgres you already have.
+
 Build with Ablo on **the Postgres you already have**. You declare a small Ablo
-schema for the models humans and agents edit together, connect Ablo to your
+schema for the models your agents edit together, connect Ablo to your
 database (`ablo connect`), and read and write every one of those models through
 `ablo.<model>`. You write through Ablo; it lands the change in your Postgres and
 confirms it by tailing your write-ahead log (WAL). Your rows live in your database,
@@ -86,6 +88,22 @@ import type { Model } from '@abloatai/ablo/schema';
 type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 ```
 
+The same block is where you name the metadata your claims carry. Add a
+`ClaimMeta` key and every `claim.state`, `claim.queue`, and held claim reads
+`target.meta` as that shape:
+
+```ts
+declare module '@abloatai/ablo' {
+  interface Register {
+    Schema: typeof schema;
+    ClaimMeta: { blocks: string[] };
+  }
+}
+
+const holder = ablo.weatherReports.claim.state({ id });
+holder?.target.meta?.blocks.length; // typed, no guard
+```
+
 (The same `Register` binding types every hook and client — it's the
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
@@ -169,10 +187,9 @@ tables** — Ablo reads them, it does not create or migrate them:
   the tables with your own migration tool; Ablo syncs the subset of models you
   declared and reports the rest as "ignored / owned by you."
 
-> **Optional escape hatch:** if you have no tables yet and want Ablo to scaffold
-> them, `npx ablo migrate` can create your synced-model tables for you. This is
-> not the happy path — connecting a real database is `ablo connect` (step 3), and
-> your own migrations stay in charge of your schema.
+> **Starting from an empty database?** `npx ablo migrate` creates the tables
+> your schema needs. Once they exist, your own migration tool stays in charge
+> of them — Ablo adopts whatever shape you evolve.
 
 Nothing runs locally — there is no dev server to start. Your app talks to Ablo's
 hosted API; the rows live in your database.

package/docs/react.md

@@ -1,5 +1,7 @@
 # React
 
+> Provider, hooks, and reactive reads for the interfaces people watch agent work arrive in.
+
 The React bindings for `@abloatai/ablo`. Use them when you want live
 data on the client without writing fetch + WebSocket plumbing yourself.
 
@@ -25,6 +27,7 @@ the thing, then pass it.
 ```ts
 // lib/ablo.ts
 import Ablo from '@abloatai/ablo';
+import { createAbloReact } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // The browser never holds your API key. It mints a short-lived session token
@@ -33,8 +36,18 @@ export const ablo = Ablo({
   schema,
   authEndpoint: '/api/ablo-session',
 });
+
+// The typed binding: capture the schema once, and every component imports
+// born-typed hooks from this file — `useAblo()` takes no type arguments,
+// and a selector's `ablo` parameter knows your models.
+export const { AbloProvider, useAblo } = createAbloReact(schema);
 ```
 
+Import `AbloProvider` and `useAblo` from `lib/ablo` rather than from the
+package, and the schema generic never appears at a call site again — the
+same one-binding-file convention as tRPC's `createTRPCReact` or
+react-redux's typed hooks.
+
 ## AbloProvider
 
 Mount it once near the root of your tree. It owns the connection, the local
@@ -65,10 +78,10 @@ export function Providers({
 
 | Prop        | Default          | Purpose                                                                                                   |
 | ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
-| `client`    | —                | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
+| `client`    |: | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
 | `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
 | `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `onError`   | —                | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
+| `onError`   |: | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
 
 Everything that used to be a provider prop — `schema`, `url`, `apiKey`,
 `teamIds`, `syncGroups`, `persistence`, `bootstrapMode` — now lives on
@@ -77,7 +90,7 @@ identity comes from, and why the API key never reaches the browser, is the whole
 of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
 org / team / user map to what a participant can see.
 
-## useAblo — model client
+## useAblo: model client
 
 ```tsx
 'use client';
@@ -85,7 +98,7 @@ org / team / user map to what a participant can see.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
@@ -95,7 +108,7 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Uses the same `ablo.<model>.get(id)` / `.getAll()` methods you'd call anywhere
+1. Uses the same `ablo.<model>.local.retrieve(id)` / `.local.list()` methods you'd call anywhere
    else in the SDK — the hook just makes them reactive.
 2. Tracks the model fields read by the selector and re-renders when confirmed
    deltas arrive.
@@ -110,14 +123,14 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.get(id))`. Older hooks
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.retrieve(id))`. Older hooks
 also accept a string model name; prefer the selector form shown above.
 
 For collections, keep the selector on the model client too:
 
 ```tsx
 const reports = useAblo((ablo) =>
-  ablo.weatherReports.getAll({
+  ablo.weatherReports.local.list({
     where: { projectId },
     filter: (report) => report.status !== 'ready',
     state: 'live',
@@ -135,7 +148,7 @@ Use `retrieve` in Server Components when the row may not be in the local pool
 yet — it hydrates from the local store and the server, and returns a Promise, so
 `await` it. (Server reads come in two shapes: `retrieve({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
-`get`/`getAll`/`getCount`, used in render below.)
+the `local` reads, used in render below.)
 
 ## Writes
 
@@ -178,7 +191,7 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useJoin — scoped presence + read interest
+## useJoin: scoped presence + read interest
 
 `useJoin` is the React form of `ablo.<model>.join`. It joins multiplayer for a
 scope on the engine's existing socket (one TCP connection, N logical
@@ -191,11 +204,11 @@ write interest in it.
 
 import { useJoin } from '@abloatai/ablo/react';
 
-export function DeckPresence({ deckId }: { deckId: string }) {
+export function DeckPresence({ workspaceId }: { workspaceId: string }) {
   const { peers, claims, status } = useJoin({
-    scope: { slideDecks: deckId },
+    scope: { slideDecks: workspaceId },
     claim: true,   // I intend to write — pin the scope + let peers observe the claim
-    hydrate: true, // backfill the deck's current rows if not already loaded
+    hydrate: true, // backfill the workspace's current rows if not already loaded
   });
 
   if (status !== 'joined') return <span>connecting…</span>;
@@ -207,10 +220,10 @@ Options (`UseJoinOptions`):
 
 | Option | Default | Effect |
 | --- | --- | --- |
-| `scope` | — | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
-| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant — leave `false` for read-only. |
+| `scope` |: | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
+| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant: leave `false` for read-only. |
 | `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
-| `ttlSeconds` | — | Lease TTL for the scope claim. |
+| `ttlSeconds` |: | Lease TTL for the scope claim. |
 | `paused` | `false` | Tear down and don't re-join while true. |
 
 Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
@@ -218,7 +231,7 @@ Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
 write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
 `paused` flips true.
 
-## usePeers — read-only presence
+## usePeers: read-only presence
 
 `usePeers` is a *pure reader* of the presence stream already flowing on the
 connection. Unlike `useJoin`, it does **not** enter/leave a scope (no
@@ -230,8 +243,8 @@ connection is subscribed to.
 
 import { usePeers } from '@abloatai/ablo/react';
 
-export function CursorBroadcaster({ deckId }: { deckId: string }) {
-  const peers = usePeers({ slideDecks: deckId });
+export function CursorBroadcaster({ workspaceId }: { workspaceId: string }) {
+  const peers = usePeers({ slideDecks: workspaceId });
   const alone = !peers.some((p) => p.participantKind === 'user');
   // suppress live-cursor broadcasts while alone
 }

package/docs/schema-contract.md

@@ -1,5 +1,7 @@
 # Schema Contract
 
+> One schema becomes typed clients, agent writes, interface reads, and the hosted push.
+
 Ablo's schema is the integration contract. Define it once, pass it to `Ablo(...)`,
 and every actor gets the same typed model surface:
 
@@ -10,7 +12,7 @@ defineSchema(...) -> ablo.<model>.create/retrieve/update/claim(...)
 That one object drives:
 
 - typed model clients in trusted server runtimes,
-- React selectors through `useAblo((ablo) => ablo.<model>.get(id))`,
+- React selectors through `useAblo((ablo) => ablo.<model>.local.retrieve(id))`,
 - agent and background-worker writes,
 - Data Source request/response shape when your database stays canonical,
 - hosted schema push, migration planning, and schema-version gating.
@@ -75,8 +77,8 @@ const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 Use synchronous local reads in render after data has synced:
 
 ```ts
-const report = ablo.weatherReports.get(reportId);
-const pending = ablo.weatherReports.getAll({ where: { status: 'pending' } });
+const report = ablo.weatherReports.local.retrieve(reportId);
+const pending = ablo.weatherReports.local.list({ where: { status: 'pending' } });
 ```
 
 Use model writes for every actor:

package/docs/session-settings.md

@@ -0,0 +1,108 @@
+# Session Settings
+
+> Point your row-level-security policies at Ablo's writes, by naming the Postgres session settings they already read.
+
+Ablo writes your rows through a scoped role with `row_security` on and
+`NOBYPASSRLS` set, so your policies govern its writes the same way they govern
+your own application's. They only govern well if they can see who the write is
+for. Before each write, Ablo sets its own identity context on the transaction —
+and if your policies read settings under names you chose, `sessionSettings` maps
+one to the other:
+
+```ts
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    invoices: model({
+      total: z.number(),
+      reference: z.string(),
+    }),
+  },
+  {
+    sessionSettings: { 'app.current_org': 'orgId' },
+  },
+);
+```
+
+A policy written against `current_setting('app.current_org')` now applies to
+Ablo's write, unchanged:
+
+```sql
+CREATE POLICY tenant_isolation ON invoices
+  USING (organization_id = current_setting('app.current_org', true));
+```
+
+The key is the setting name **your** policies read. The value names which piece
+of Ablo's authenticated identity fills it.
+
+## What Ablo sets on its own
+
+Every direct write runs inside a transaction that begins by setting this
+context, whether or not you map anything:
+
+| Setting | Carries |
+| --- | --- |
+| `app.current_org_id` | The organization the credential acts for |
+| `app.current_project_id` | The project |
+| `app.current_environment` | The environment |
+| `app.current_sandbox_id` | The sandbox, when the write is in one |
+| `app.current_participant_id` | The participant making the write |
+| `app.current_participant_kind` | Whether that participant is a person, an agent, or the system |
+| `app.current_user_id` | The person on whose behalf the write is made |
+
+If your policies read these names directly, you need no mapping at all — this
+page is for the case where they read different ones.
+
+`app.current_user_id` is worth reading twice, because it has three states rather
+than two. It carries a person's id when a person is behind the write. It carries
+`*` when a backend credential is acting as the organization itself, which is the
+authority a server-side key holds. And it carries the empty string when no
+identity could be established — written explicitly rather than left alone, so a
+policy on a pooled connection reads absence as absence and denies, instead of
+inheriting whatever the previous transaction left behind.
+
+## What a mapping may name
+
+The value side is a closed set, and every member is resolved by Ablo from the
+authenticated key and the plane:
+
+`orgId` · `projectId` · `environment` · `sandboxId` · `participantId` ·
+`participantKind`
+
+Because none of them come from the caller, a mapping can forward the tenant
+identity Ablo already trusts, but cannot widen what a writer sees. A setting name
+takes exactly one source — the name is the key — so naming the same setting twice
+is unrepresentable rather than something to resolve later.
+
+## What a mapping may not name
+
+The settings in the table above, along with `row_security`, `search_path`,
+`statement_timeout`, and `lock_timeout`, are reserved. `defineSchema` rejects a
+mapping onto any of them, and the engine refuses one at write time too.
+
+The reason is worth stating plainly: those settings are how Ablo bounds its own
+write. A schema that could reassign them could relax the scoping under which
+Ablo writes, which would put the boundary inside the thing being bounded. Point
+your policies at a name you own — `app.current_org` rather than
+`app.current_org_id` — and map that.
+
+## Reads served from the log
+
+One arrangement cannot honour a policy that names a person. When a plane is
+served from its retained log rather than from its tables, every row carries the
+organization and the project, but not the owner — so a rule about who owns a row
+has nothing to act on.
+
+Rather than fold those rows and return a plausible answer, such a read is
+declined whole with `user_scope_not_enforced`: a member reading a colleague's
+private records would otherwise be indistinguishable from a member reading their
+own. Reads made by a credential acting for the organization are unaffected, as is
+every plane served from its tables.
+
+## Related
+
+- [Data Sources](./data-sources.md) — the writer role's privileges, and what it
+  can and cannot do to your database.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions
+  are read-only, which are reversible, and which belong to a human.

package/docs/sessions.md

@@ -1,5 +1,7 @@
 # Sessions
 
+> Short-lived scoped credentials your backend mints for a browser or an agent.
+
 A **session** is a short-lived credential your backend mints with its `sk_` and
 hands to one actor — a signed-in **person's browser** or a scoped **agent**. It's
 the same primitive in both cases (backend-minted, short-lived, scoped); the only
@@ -16,7 +18,7 @@ const userSession = await ablo.sessions.create({
 // A scoped agent session — gated to exactly the operations you name.
 const agentSession = await ablo.sessions.create({
   agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'], Deck: ['read'] },
+  can: { Task: ['read', 'update'], Workspace: ['read'] },
 });
 ```
 
@@ -173,7 +175,7 @@ Your schema lives in a **project** — you push it once (`npx ablo push`) and ev
 session you mint resolves against it. The flow for serving end-users:
 
 1. **Push your schema** to your project.
-2. **Mint an `ek_` per user** — `sessions.create({ user: { id } })`. Your users
+2. **Mint an `ek_` per user:** `sessions.create({ user: { id } })`. Your users
    commit to that one schema.
 
 **Your users do not have Ablo accounts.** You authenticate them however you