@abloatai/ablo 0.48.0 → 0.49.0

package/docs/data-sources.md

@@ -29,7 +29,7 @@ branch's database unavailable instead of silently writing somewhere else.
 
 Yes for the Ablo application path: model reads and lists, coordinated writes,
 claims, subscriptions, idempotency, confirmations, and transactional outbox
-settlement all work against localhost Postgres. The browser, server code, and
+confirmation all work against localhost Postgres. The browser, server code, and
 agents still connect to Ablo Cloud; only database operations cross the narrow
 signed connector to your machine.
 
@@ -47,12 +47,43 @@ path with a network-reachable Postgres endpoint, PrivateLink/peering/VPN, or a
 database-capable secure tunnel. Do not expose Postgres without TLS,
 authentication, and network restrictions.
 
+### For localhost-first open-source projects
+
+Do not require contributors to buy hosted Postgres or expose port 5432 merely to
+run the project. Treat the connector as the default contributor topology:
+
+```json
+{
+  "scripts": {
+    "ablo:setup": "ablo migrate",
+    "ablo:dev": "ablo dev --local"
+  }
+}
+```
+
+Keep `DATABASE_URL=postgres://…@localhost:5432/…` in `.env.example`, commit the
+generated `ablo/data-source.ts` handler, and document two long-running processes:
+the application and `npm run ablo:dev`. Contributors provide their own Ablo
+branch credential through `ablo login`; the repository never contains it.
+
+For collaborative models, route mutations through Ablo or the signed Data Source
+adapter. If the existing project intentionally writes those same tables through
+raw SQL or an unrelated ORM path, choose one explicitly:
+
+- add the supported transactional outbox/source-push integration for those writes;
+- state that only Ablo-mediated changes participate in live coordination locally; or
+- make WAL integration tests opt-in through a secure direct tunnel or hosted test database.
+
+That keeps the zero-cost localhost quickstart honest without weakening Ablo's
+coordination boundary or pretending endpoint mode can see WAL.
+
 ### Local connector errors
 
 Every stable code links to the generated [error reference](https://docs.abloatai.com/errors):
 
 | Code | Meaning and fix |
 |---|---|
+| `database_loopback_requires_connector` | A direct connection was configured with localhost. For the normal OSS/dev path, run `ablo migrate` and `ablo dev --local`; use a direct network route only when arbitrary SQL writes need WAL observation. |
 | `source_connector_not_attached` | The branch is connector-only but no process is attached. Start or restart `ablo dev --local`. |
 | `source_connector_unauthenticated` | The temporary branch key is missing, expired, or rejected. Rerun `ablo dev --local` to mint a fresh key. |
 | `source_connector_requires_secret_key` | The connector received the wrong key kind. Let `ablo dev` supply its branch-bound `sk_` key. |

package/docs/guarantees.md

@@ -2,11 +2,10 @@
 
 > Exactly what a confirmed write, a rejected stale write, and a held claim each promise.
 
-When an Ablo write succeeds, the server has accepted it — and when two agents
-touch the same row, Ablo coordinates them instead of letting one silently
-overwrite the other. This page is the precise list of what you can count on:
-confirmed writes, stale-write protection, claims, and the audit trail behind
-every change.
+When an Ablo write succeeds, the server has confirmed it. Concurrency behavior
+depends on the write form you choose: plain writes are last-write-wins;
+functional updates, stale guards, and claims add protection when a write depends
+on earlier state. This page is the precise list of what each form promises.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them,
 re-reads the fresh row, then hands it to you — so two writers serialize instead
@@ -49,18 +48,18 @@ Use `snapshot(...)` and `readAt` when a write depends on state the agent already
 read:
 
 ```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+if (!report) throw new Error('report missing');
 
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
-`onStale: 'reject'` prevents lost updates. If the target changed after the
-snapshot, the server rejects the write instead of applying stale reasoning.
+The returned row carries opaque evidence. If it changed after the read, the
+server rejects the write instead of applying stale reasoning.
 
 Two other dispositions exist. `overwrite` applies the write with no stale check
 at all. `notify` **holds** the write, so the row is left as it stands, and hands
@@ -70,6 +69,11 @@ and re-issue; the rest of the batch still commits.
 See [Concurrency Convention](./concurrency-convention.md) for the full taxonomy,
 what each disposition is checked against, and where the convention stops.
 
+A plain `update({ id, data })` carries no stale premise. If no one holds a claim
+on the target, it is last-write-wins. That is appropriate for independent values
+such as status flags, but not for a read-modify-write calculation. For the latter,
+use the functional update form or pass exact returned rows through `reads`.
+
 ## Claim Coordination
 
 > The guarantee, not the how-to. Methods, the claim-state object, and the `claim.queue`
@@ -86,10 +90,12 @@ error out, when it should not return a row while someone else is mid-edit. Reads
 never block on a claim — to wait for a row to free up, `claim({ id })` it (the
 claim queues fairly behind the holder).
 
-A claim does not reject or block other writers; it announces work so peers
-serialize behind it rather than racing. While you hold a claim, the matching
-`ablo.<model>.update({ id, ... })` is rejected with `AbloStaleContextError` if the row
-changed underneath you after your claim point.
+By default, a held claim rejects writes from other participants to the claimed
+target. Contenders that call `claim` wait their turn; ordinary reads remain
+open. An explicit model conflict policy can choose another disposition for a
+participant kind. While you hold a claim, the matching
+`ablo.<model>.update({ id, ... })` is rejected with `AbloStaleContextError` if
+the row changed underneath you after your claim point.
 
 ## Agent Runs
 
@@ -172,12 +178,10 @@ separates workflow or deployment lanes sharing the same store.
 
 ## Storage Boundary
 
-Your rows live in your database; Ablo holds only the transaction log and the
-coordination state. Writes enter Ablo's commit chokepoint and land in your
-Postgres through a scoped writer role, and the WAL echo confirms them
-(`queued` → `confirmed`). For a database that can't grant replication, Ablo
-forwards the write to a signed Data Source endpoint instead — the marked
-fallback. Either way Ablo never holds a database connection string. See
+Your rows live in your database; Ablo holds change history and coordination
+state. Writes land in your Postgres through a scoped writer role and are
+confirmed from its authoritative change feed. For a database that cannot grant
+replication, Ablo uses a signed Data Source endpoint instead. See
 [Connect Your Database](./data-sources.md).
 
 ## Writes

package/docs/how-it-works.md

@@ -19,20 +19,20 @@ Ablo is a **coordination layer in front of your Postgres**. Agents, background
 jobs, and the people alongside them all change the same application data through
 one API, and Ablo makes sure their writes don't clobber each other.
 
-- **Writes go through Ablo:** `ablo.<model>.create / update / delete` enter Ablo's
-  commit chokepoint — where claims, ordering, and idempotency are enforced — and
-  Ablo applies the change to your Postgres through a scoped writer role. The commit
-  is accepted (`queued`) the moment Ablo takes it.
+- **Writes go through Ablo:** `ablo.<model>.create / update / delete` are
+  authorized, made idempotent, and applied to your Postgres through a scoped
+  writer role. A plain write is last-write-wins. Use a functional update, a
+  explicit `reads: [returnedRow]`, or a claim when the new value depends on an
+  earlier read.
 - **Your database confirms the write.** Ablo tails your write-ahead log (WAL). When
   the row it wrote shows up there, the receipt is promoted to `confirmed`. So your
   database, not Ablo, is the source of truth for row state — the WAL echo is how
   Ablo *confirms*, not how it writes.
 - **Reads are live.** Ablo serves current state and keeps every connected client up
   to date off that same stream.
-- **Ablo stores only the log.** Ablo holds the ordered transaction log
-  (`sync_deltas`) and the coordination state — the claims, the ordering, the
-  watermarks. Your rows live in your database. Ablo runs no DDL and owns no schema;
-  your migration tool stays in charge of the shape of your database.
+- **Ablo stores only the change history and coordination state.** Your rows live
+  in your database. Ablo does not run application migrations; your migration
+  tool stays in charge of tables and columns.
 
 That's the shape: **you write through Ablo → it lands in your Postgres → the WAL
 echo confirms it → everyone connected sees it live.**
@@ -45,21 +45,7 @@ echo confirms it → everyone connected sees it live.**
 | `Model` | State | The generated `ablo.<model>` model. Use `get`/`list` (async reads), `local.get`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
 | `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral, never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
-| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Awaiting a schema write waits for confirmation. |
-
-### Why each primitive is separate
-
-Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
-does a job the others cannot. If you are coming from Replicache or Yjs you would
-expect just `Commit`. Here is what the other two buy you over that minimum:
-
-- **`Claim` is not a read lock.** Reads stay open. Claims serialize
-  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
-  from fresh state.
-- **`Receipt` is not a `200 OK`.** It is the durable artifact a commit produced:
-  accepted commit id, server-assigned timestamps, stale-check outcome. It is
-  addressable after the fact and replayable into a different client. A status
-  code cannot be re-read by a sub-agent that was not on the original call.
+| `Receipt` | Protocol | The result of a lower-level commit. Awaiting a schema write waits for confirmation. |
 
 ## Where your data lives
 
@@ -117,22 +103,6 @@ const latest = ablo.tasks.local.get('task_42'); // read after claiming, not from
 await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
 ```
 
-## Reading the architecture correctly
-
-The model changed once (ADR 0010), and older material described the earlier one.
-If you've read that a customer's app keeps writing while Ablo only tails the WAL,
-here is the current, correct reading:
-
-- **"Ablo tails the WAL."** True — to *confirm* your writes and serve live reads.
-  It is not the write path. You write **through** Ablo.
-- **"Ablo is out of the write path."** Not anymore. Ablo is the write chokepoint;
-  every write flows through its coordination and then into your database.
-- **"Ablo holds my rows."** Only on a development branch where you have not
-  connected a database yet. Once you connect one, your rows live in *your*
-  Postgres — Ablo keeps just the log.
-- **"Ablo migrates my schema."** No. Ablo writes rows through a scoped role and runs
-  no DDL; your migrations own the shape of your database.
-
 For the setup details, see [Connect Your Database](./data-sources.md). For the
-coordination loop, see [Concurrency Convention](./concurrency-convention.md). For
+coordination loop, see [Coordination](./coordination.md). For
 what `queued` and `confirmed` guarantee, see [Guarantees](./guarantees.md).

package/docs/identity.md

@@ -14,6 +14,54 @@ NextAuth, WorkOS, your own session table. Ablo's job begins **after** you've
 authenticated the user: you hand Ablo the already-authenticated identity, and
 Ablo decides which **sync groups** that identity may read and write.
 
+## Inspect the credential the application is actually using
+
+`ablo whoami` describes the developer running the CLI. Runtime code should
+inspect `ablo.identity`, which is the server-confirmed `EffectiveAuthority` of
+the credential attached to that client. It is never decoded or reconstructed
+locally.
+
+```ts
+import { Ablo } from '@abloatai/ablo';
+import { CapabilityError } from '@abloatai/ablo';
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+await ablo.ready();
+
+console.log(ablo.identity?.operations);
+console.log(ablo.identity?.syncGroups);
+```
+
+The HTTP and stateful clients expose the same value after `ready()`. A denied
+scoped operation throws `CapabilityError`; compare its
+`requiredCapability.scope` directly with `ablo.identity.operations`.
+
+```ts
+try {
+  await ablo.tasks.update({ id, data: { status: 'done' } });
+} catch (error) {
+  if (error instanceof CapabilityError) {
+    console.error('missing grant', error.requiredCapability);
+  }
+}
+```
+
+Do not broaden the credential in the client. A backend holding the project
+secret mints a replacement, least-privilege agent credential with the schema-
+typed grant:
+
+```ts
+const session = await control.sessions.create({
+  agent: { id: agentId },
+  can: { tasks: ['read', 'update'] },
+  syncGroups: [syncGroup('workspace', workspaceId)],
+});
+```
+
+Install `session.token` in the agent process and call `ready()` again. The next
+`ablo.identity` is the authority the server will enforce; no automatic grant
+escalation occurs.
+
 So the integration question is never "how do I log into Ablo?" It's: *"My app
 already knows this request is user `U` in org `O`. How do I tell Ablo, so it
 scopes their realtime data correctly?"* The rest of this doc answers exactly

package/docs/index.md

@@ -140,7 +140,7 @@ default caller, not a special one.
 
 - [How Ablo Works](./how-it-works.md) — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. **Read this first.**
 - [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue`: who holds a row, and who is waiting.
-- [Concurrency Convention](./concurrency-convention.md) — the governing rule for how concurrent writes resolve.
+- [Concurrency Convention](./concurrency-convention.md) — the precise rule for guarded and unguarded writes.
 - [Guarantees](./guarantees.md) — what a confirmed write, a stale-write rejection, and a claim each promise.
 - [Idempotency](./idempotency.md) — make a retried write safe; what replays, what re-runs, and for how long.
 - [Schema Contract](./schema-contract.md) — one schema becomes typed clients, agent writes, React reads, and the push.
@@ -175,7 +175,7 @@ default caller, not a special one.
 
 - [API Reference](./api.md) — model-by-model method shape.
 - [Errors](./errors.md) — the code registry, its categories, and what to do about each.
-- [Version History & Migration](./migration.md) — every breaking change and its migration.
+- [Upgrade Guide](./migration.md) — upgrade a pinned pre-1.0 SDK safely.
 - [Changelog](../CHANGELOG.md) — what shipped recently.
 
 ## Examples