@abloatai/ablo 0.43.0 → 0.45.0

package/AGENTS.md

@@ -87,4 +87,23 @@ Claims live on a callable namespace beside `create` / `update` / `retrieve`. Eve
 - `ablo.<model>.claim.release({ id })` — release a claim early.
 - `ablo.<model>.claim.reorder({ id, order })` — reorder the waiting queue.
 
+Keep admission behavior together for anything beyond the default wait:
+
+```ts
+const claim = await ablo.tasks.claim({
+  id,
+  contention: {
+    mode: 'skip', // use 'wait' with maxDepth / timeoutMs when waiting is useful
+    onStatus(event) {
+      if (event.type === 'skipped') console.warn(event.error.message);
+    },
+  },
+});
+if (!claim) return; // another participant already owns the work
+```
+
+`onStatus` receives typed `queued`, `granted`, `skipped`, and `failed` events.
+It is request-scoped; use `claim.state` / `claim.queue` for the shared reactive
+view.
+
 Most users declare a schema and write through `ablo.<model>.update({ id, data })`.

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.45.0
+
+### Claim admission is authoritative
+
+A claim used to return a local handle immediately, before the server had
+granted anything, so two agents on different server instances could each
+believe they held the same row. Every claim now waits for the server's grant
+or rejection, and the server fails closed when the shared lease store is
+unavailable rather than admitting claims it cannot coordinate. A two-server
+end-to-end regression pins the behavior.
+
+### Contention has a lifecycle you can watch
+
+The new `contention` option names what happens when the row is already held:
+
+```ts
+const claim = await ablo.tasks.claim({
+  id,
+  contention: {
+    mode: 'skip',
+    onStatus(event) {
+      // queued | granted | skipped | failed
+    },
+  },
+});
+```
+
+`{ mode: 'skip' }` resolves `null` instead of waiting, and `onStatus` reports
+the attempt as it moves. `queue: true` and `queue: false` remain as
+compatible spellings of the two modes.
+
+## 0.44.0
+
+### A scope denial names the wall it hit
+
+`capability_scope_denied` now distinguishes the Ablo capability allowlist
+from the customer database's row-level security. The error carries the
+required capability, the resolved operations, the participant and user
+principal, the branch, the organization and project, and any applied session
+settings, so "permission denied" is a diagnosis instead of a dead end: you
+can see whether your grant was missing a verb or whether your own database's
+row policy rejected the session context Ablo applied.
+
+### Write failures carry their request id
+
+A WebSocket write failure now carries the `requestId` the server logged it
+under, and a `wait: 'confirmed'` write rejects with the complete typed error
+rather than a bare failure, so the error you catch is the error the server
+recorded.
+
+### `doctor` reports readiness, not destiny
+
+`doctor` now says infrastructure is ready rather than promising a write will
+succeed, because database constraints and row-level security still apply at
+write time. The debugging guide explains how to read the new diagnostics,
+and documents that `list()` may answer from the local pool while
+`list({ type: 'complete' })` waits for the server round trip.
+
 ## 0.43.0
 
 ### Keys are branch-first

package/docs/agents.md

@@ -116,9 +116,9 @@ await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the
 await ablo.tasks.claim.reorder({ id: taskId, order: line }); // re-rank the line (privileged)
 ```
 
-Think of it as a queue per row — a durable, inspectable, reorderable lease line
-("SQS for entity contention"). Use `{ queue: false }` for fail-fast dedup: *if
-someone else has this job, skip it.*
+Think of it as a queue per row — a durable, inspectable, reorderable lease
+line. Use `contention: { mode: 'skip' }` for fail-fast dedup: *if someone else
+has this job, skip it.*
 
 ## Messaging between agents
 

package/docs/client-behavior.md

@@ -152,7 +152,9 @@ the latest row, then hands you the fresh row — so you can't overwrite a change
 see. Options on the claim:
 
 - default `claim` waits in the fair queue and re-reads before handing you the row;
-- `{ queue: false }` rejects with `AbloClaimedError` instead of queuing;
+- `{ queue: false }` resolves `null` when another participant already holds the
+  target; two clients with the same participant identity are re-entrant, not
+  contenders;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
@@ -172,7 +174,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloValidationError` | Invalid input or unsupported request shape. |
 | `AbloServerError` | Server-side 5xx. Retry with backoff if the operation is idempotent. |
 | `AbloStaleContextError` | Write was based on stale `readAt` state. Re-read and retry. |
-| `AbloClaimedError` | An active claim conflicted with `{ queue: false }`, the queue was too deep, or a claim wait timed out. |
+| `AbloClaimedError` | A write conflicted with another participant's active claim, the queue was too deep, or a claim wait timed out. |
 
 ```ts
 import { AbloClaimedError } from '@abloatai/ablo';

package/docs/coordination.md

@@ -57,7 +57,7 @@ See [claiming part of a row](#claiming-part-of-a-row).
 > from outside with `signal` (an `AbortSignal`; rejects
 > `claim_wait_aborted`), bound the line you'll join with `maxQueueDepth`
 > (`queue_too_deep`), or skip waiting entirely with `queue: false` — the
-> try-claim, which resolves `null` when the target is held (a declined try
+> try-claim, which resolves `null` when the target is held (skipped work
 > is not an error) and takes no place in line. For
 > callers that manage the wait themselves, the ticket surface remains:
 > `ablo.claims.get({ claimId })` polls a ticket to its grant,
@@ -94,6 +94,13 @@ claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 >
 > Now `agent-0` holds while `agent-1`/`agent-2` queue in FIFO order and drain in
 > turn. See [sessions](./sessions.md#agent-sessions-rk_) for the minting flow.
+>
+> **Testing exclusion:** mint two sessions with different `agent.id` values,
+> assert those values differ, let A acquire the row, and inspect
+> `claim.state({ id })` before B calls `claim({ id, queue: false })`. B must
+> receive `null`. Creating two clients from the same key tests re-entrancy, not
+> contention. An empty `claim.state` is an observation/subscription issue; it
+> does not relax the authoritative lease check.
 
 ---
 
@@ -317,14 +324,15 @@ four axes. `claim({ id })` alone is a complete call; each axis is opt-in.
 | `options.description` | `string` | no | Peer-visible description of the work, shown to observers (default `'editing'`). |
 | `options.meta` | `object` | no | App-defined structured metadata, carried verbatim to every participant observing the claim. Declare its shape once on `Register`'s `ClaimMeta` slot. |
 
-*How you wait* — admission to the line:
+*How you handle contention*:
 
 | name | type | required | description |
 |---|---|---|---|
-| `options.queue` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is the try-claim: if another participant holds the row it resolves `null`: an expected outcome, not an error, so claim-or-skip dedup reads `if (!claim) return` (waiting would double-process). Who holds it stays readable via `claim.state`. A *write* to a held row still rejects `entity_claimed`. |
-| `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
-| `options.waitTimeoutMs` | `number` | no | Cap on how long a queued claim waits for its grant before rejecting with `AbloClaimedError('grant_timeout')`. Omit to wait as long as the line takes. Same meaning on both transports; over HTTP a timed-out wait also leaves the line. |
-| `options.signal` | `AbortSignal` | no | Abort a pending wait from outside: a cancelled agent task or an unmounted component takes its queued claim with it. Rejects with `AbloClaimedError('claim_wait_aborted')`; over HTTP the abort also leaves the line. Ignored once the grant has arrived, release a held lease instead. |
+| `options.contention` | `Claim.ContentionOptions` | no | Keeps the response to a busy target together: `{ mode: 'wait', maxDepth?, timeoutMs?, signal?, onStatus? }`. Use `mode: 'skip'` for claim-or-skip dedup; a foreign holder resolves the claim as `null`. |
+| `options.queue` | `boolean` | no | Compatibility shorthand: `true` waits and `false` skips. Prefer `contention` when configuring more than the mode. |
+| `options.maxQueueDepth` | `number` | no | Legacy flat spelling of `contention.maxDepth`. Prefer `contention` for new code. |
+| `options.waitTimeoutMs` | `number` | no | Legacy flat spelling of `contention.timeoutMs`. Prefer `contention` for new code. |
+| `options.signal` | `AbortSignal` | no | Legacy flat spelling of `contention.signal`. Prefer `contention` for new code. |
 
 *How long you hold* — the lease:
 
@@ -333,6 +341,53 @@ four axes. `claim({ id })` alone is a complete call; each axis is opt-in.
 | `options.ttl` | `Duration` | no | Crash-cleanup floor. Rarely set: the lease renews while your connection is alive, so it only matters once you go silent. |
 | `options.heartbeat` | `true \| Duration \| { every?, onBeat?, onLost? }` | no | Keep the lease alive for work that outlives the TTL: `true` beats every third of the TTL, a duration sets the cadence, and the structured form carries the cadence and both callbacks in one place: `onBeat` fires after every successful beat (chiefly `queueDepth`, the pressure signal), `onLost` once if a beat learns the lease is gone. The loop stops on release. |
 
+The request-scoped `onStatus` callback receives one discriminated event. It is
+observational: an exception in UI or telemetry code never changes the claim
+attempt.
+
+| event | meaning | claim promise |
+|---|---|---|
+| `queued` | this request joined the wait line | remains pending |
+| `granted` | this request owns the lease | resolves with the claim |
+| `skipped` | `mode: 'skip'` found another participant holding the target | resolves `null` |
+| `failed` | the attempt could not complete, for example timeout, cancellation, authorization, or connectivity | rejects with `event.error` |
+
+```ts
+const claim = await ablo.tasks.claim({
+  id,
+  contention: {
+    mode: 'wait',
+    maxDepth: 3,
+    timeoutMs: 30_000,
+    onStatus(event) {
+      if (event.type === 'queued') {
+        console.log(`${event.ahead} participant(s) ahead`);
+      } else if (event.type === 'granted') {
+        console.log(event.waited ? 'your turn' : 'granted immediately');
+      } else {
+        console.warn(event.error.code, event.error.message);
+      }
+    },
+  },
+});
+```
+
+For claim-or-skip work, make the caller's intent explicit and keep its status
+observer beside the decision:
+
+```ts
+const claim = await ablo.tasks.claim({
+  id,
+  contention: {
+    mode: 'skip',
+    onStatus: (event) => {
+      if (event.type === 'skipped') metrics.increment('claim.skipped');
+    },
+  },
+});
+if (!claim) return;
+```
+
 The high-level `claim` queues by default, so on contention you either get the row
 when your turn arrives or one of the [queue errors](#errors) (`claim_lost`,
 `grant_timeout`).
@@ -552,16 +607,22 @@ decide the wait isn't worth it.
 |---|---|---|---|
 | `id` | `string` | yes | The row id. |
 
-**Returns** — a list envelope. `data` contains the queued
-[claim state objects](#the-claim-state-object) in promotion order (head first), excluding
-the active holder; `[]` when no one is waiting.
+**Returns** — a structured queue snapshot:
+
+- `waiting` — queued [claim state objects](#the-claim-state-object) in
+  promotion order, excluding the active holder;
+- `next` — the first waiter, or `null`;
+- `size` — how many participants are waiting;
+- `data` — the same array as `waiting`, retained as the standard list-envelope
+  member for compatibility.
 
 **Example**
 
 ```ts
-const { data: waiting } = ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
-console.log(`${waiting.length} ahead of you`);
-console.log(waiting.map((i) => i.heldBy));
+const line = ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
+console.log(`${line.size} waiting`);
+console.log(`next: ${line.next?.heldBy ?? 'nobody'}`);
+console.log(line.waiting.map((claim) => claim.heldBy));
 ```
 
 ### `claim.release`

package/docs/debugging.md

@@ -15,12 +15,13 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
 
 ## CLI environment and target
 
-`push`, `dev`, and `status` follow the application-facing chain: exported
-`ABLO_API_KEY`, `.env.local`, `.env`, then the stored credential. An exported
-value wins over project files. Connect-family administration is intentionally
-stricter: it reads only the process environment and stored login, so an ambient
-file cannot silently choose the plane a database mutation acts on. When a file
-contains the missing key, the refusal names that rule and the remedy.
+Read-only diagnostics (`status`, `whoami`, `logs`, and `connect locate/check`)
+may inspect the application-facing chain: exported `ABLO_API_KEY`,
+`.env.local`, `.env`, then the stored credential. An exported value wins over
+project files. Mutations (`push` and `connect apply/rotate/register/deregister`)
+are intentionally stricter: they read the process environment, an explicit
+`--env-file`, or a stored compatibility credential. An ambient file cannot
+silently choose the branch a mutation acts on.
 
 Use the two diagnostics according to the question:
 
@@ -232,3 +233,67 @@ AbloValidationError [model_required_field_missing]: A required field was absent.
 ```
 
 Branch on `err.code` (stable) — never on the message (rewordable). See [Client Behavior](./client-behavior.md) for the full error model and which codes are safe to retry.
+
+### Diagnosing `capability_scope_denied`
+
+The same stable code covers two different enforcement layers, so inspect
+`error.details.origin`:
+
+- `capability_allowlist`: the branch/session credential did not grant the
+  operation. `requiredCapability.scope` names the missing `model.verb`, and
+  `details.resolvedOperations` shows the grants the server actually resolved.
+- `database_row_level_security`: Ablo's capability gate allowed the operation,
+  but Postgres rejected it under the customer table's RLS policy.
+  `details.databaseSessionContext` shows the organization, project, branch,
+  participant kind, user principal, and the complete built-in-plus-custom
+  session-setting values configured for that transaction.
+  `customSessionSettings` isolates only the mappings declared by the schema;
+  an empty object there does not mean built-in settings such as
+  `app.current_org_id` were absent.
+
+Do not respond by changing a tenant policy to `USING (true)` or granting
+`BYPASSRLS`. Compare the row's tenant value with
+`databaseSessionContext.sessionSettings.app.current_org_id`. On CREATE, Ablo
+server-stamps the authenticated organization into the model's row-local tenancy
+field; a missing value is a server/version fault to report with `requestId`, not
+a requirement to make the column nullable or open the policy.
+
+Every rejected live commit carries `requestId` on the thrown error and
+`request_id` in its JSON form and warning line:
+
+```ts
+import { AbloError } from '@abloatai/ablo';
+
+try {
+  await ablo.documents.create({
+    data,
+    wait: 'confirmed',
+  });
+} catch (error) {
+  if (error instanceof AbloError) {
+    console.error(error.code, error.requestId, error.requiredCapability, error.details);
+  }
+}
+```
+
+With `wait: 'confirmed'`, the awaited call rejects with that complete typed
+error. `onMutationFailure` remains the notification channel for optimistic
+writes that return before the server answers; it is not required to recover
+details from a confirmed write.
+
+### Local reads versus a confirmed server read
+
+`list()` without a completeness option may return the current local pool
+immediately. That is why it can be empty while Postgres contains rows: it is not
+evidence that the replication source has no history.
+
+Use:
+
+```ts
+await ablo.documents.list({ type: 'complete' });
+```
+
+`type: 'complete'` waits for a server round trip and returns the confirmed
+result. `type: 'unknown'` returns the local result immediately and refreshes it
+in the background. The distinction is freshness/completeness, not claimed
+versus unclaimed data.

package/docs/deployment.md

@@ -2,7 +2,7 @@
 
 > What production takes: a database Ablo can reach, a key minted for the plane you mean, and a schema push in the deploy.
 
-One command answers the question this page exists for — would a write succeed
+One command answers whether the infrastructure needed for a write is ready
 right now, and if not, why:
 
 ```bash
@@ -25,7 +25,7 @@ ABLO_API_KEY=sk_… npx ablo status
           • fulfilments    typename=fulfilments
           • reviews        typename=reviews
 
-  ✓ ready — a write should succeed
+  ✓ write infrastructure is ready — database constraints and row-level policies still apply
 ```
 
 `status` asks the routing authority rather than sampling a read, because reads

package/docs/examples/agent-human.md

@@ -54,15 +54,17 @@ export async function markDone(taskId: string) {
   if (!task) return { status: 'not_found' };
 
   try {
-    // queue: false → don't queue behind a current holder. If someone already
-    // holds the row, claim rejects with AbloClaimedError (caught below), so the
-    // agent yields instead of waiting. Omit it, or pass queue: true, to queue
-    // behind them. description → the label observers see while we work.
-    await using claim = await ablo.tasks.claim({
+    // queue: false → don't queue behind a current holder. If another
+    // participant holds the row, claim resolves null, so the agent yields
+    // instead of waiting. Omit it, or pass queue: true, to queue behind them.
+    const acquired = await ablo.tasks.claim({
       id: taskId,
       queue: false,
       description: 'marking_done',
     });
+    if (!acquired) return { status: 'yielded' };
+
+    await using claim = acquired;
     if (claim.data.status === 'done') return { status: 'noop' };
 
     // Inside an active claim, `update` is stale-checked automatically: the SDK
@@ -89,7 +91,7 @@ export async function markDone(taskId: string) {
 
     return { status: 'done', task: updated };
   } catch (err) {
-    // Someone already holds the row — yield this run and let them finish.
+    // The lease was lost or a foreign holder rejected the write.
     if (err instanceof AbloClaimedError) return { status: 'yielded' };
     // A newer version was saved while we held the claim. The stale-check
     // rejected our commit, so nothing was overwritten — re-run on fresh data.

package/docs/examples/server-agent.md

@@ -29,24 +29,43 @@ const schema = defineSchema({
   }),
 });
 
-const ablo = Ablo({
+const control = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  transport: 'http',
 });
 
-export async function completeTask(taskId: string) {
+async function clientForWorker(workerId: string) {
+  const { token } = await control.sessions.create({
+    agent: { id: workerId },
+    can: { tasks: ['read', 'update'] },
+  });
+  return Ablo({ schema, apiKey: token, transport: 'http' });
+}
+
+export async function completeTask(taskId: string, workerId: string) {
+  // Participant identity comes from this worker-specific session. Two clients
+  // made directly from the same root key are re-entrant, not contenders.
+  const ablo = await clientForWorker(workerId);
   await ablo.ready();
 
   const task = await ablo.tasks.get({ id: taskId });
   if (!task) return { status: 'not_found' };
 
-  await using claim = await ablo.tasks.claim({
+  const acquired = await ablo.tasks.claim({
     id: taskId,
-    queue: false,
+    contention: {
+      mode: 'skip',
+      onStatus(event) {
+        if (event.type === 'skipped') {
+          console.info('task already owned', event.error.code);
+        }
+      },
+    },
     description: 'completing',
   });
+  if (!acquired) return { status: 'already_claimed' };
 
+  await using claim = acquired;
   const updated = await ablo.tasks.update({
     id: claim.data.id,
     data: { status: 'done' },
@@ -67,7 +86,7 @@ The two options on the claim:
 
 - `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. Fail-fast dedup: *if someone else has this job,
-  skip it.* (The default queues.)
+  skip it.* It resolves `null`; it does not throw. (The default queues.)
 - `description: 'completing'` — a readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 

package/docs/quickstart.md

@@ -304,8 +304,9 @@ await using handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' }
 await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
 ```
 
-Use `{ queue: false }` on `claim` when work should be skipped instead of queued
-behind an active holder.
+Use `contention: { mode: 'skip' }` when work should be skipped instead of
+queued behind an active holder. Add `onStatus` inside that object when the
+attempt should also update telemetry or UI.
 
 ## Next steps
 

package/docs/session-settings.md

@@ -54,6 +54,14 @@ context, whether or not you map anything:
 If your policies read these names directly, you need no mapping at all — this
 page is for the case where they read different ones.
 
+For a mutable model with row-local tenancy, Ablo also puts the authenticated
+organization into the CREATE operation as `organizationId`; the source adapter
+maps that field to the model's tenancy column (normally `organization_id`).
+Callers do not supply it, and the column does not need a SQL default. A default
+from `app.current_org_id` can be useful as defense in depth, but it is not a
+substitute for the tenant policy and you should never loosen RLS to make an
+Ablo write pass.
+
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "The public Ablo SDK for coordinated reads, commits, claims, observation, and reactive applications.",
   "license": "Apache-2.0",
   "type": "module",
@@ -124,8 +124,8 @@
     "directory": "packages/ablo"
   },
   "dependencies": {
-    "@abloatai/humans": "^0.43.0",
-    "@abloatai/transaction": "^0.43.0"
+    "@abloatai/humans": "^0.45.0",
+    "@abloatai/transaction": "^0.45.0"
   },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0",