@abloatai/ablo 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 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/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,57 @@ 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 custom session-setting values applied
+  to that transaction.
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.43.0",
+  "version": "0.44.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.44.0",
+    "@abloatai/transaction": "^0.44.0"
   },
   "peerDependencies": {
     "ai": "^6.0.0 || ^7.0.0",