@abloatai/ablo 0.35.0 → 0.36.0

package/dist/{core/queryUtils.js → views/incrementalView.js}

@@ -1,10 +1,10 @@
 /**
- * Small, self-contained helpers for sorting, filtering, and binary insertion.
- * The incrementally-updated views that implement {@link IncrementalView} rely on
- * these for their ordering and matching, so keeping the rules in one place
- * ensures every view sorts and filters identically. The functions here work on
- * plain arrays and values — they hold no reference to models, pools, or the
- * reactivity system.
+ * The {@link IncrementalView} contract — the interface a live view implements
+ * to receive add/update/remove notifications — together with the sorting,
+ * matching, and binary-insertion rules every view shares. Keeping the rules in
+ * one place ensures every view sorts and filters identically. The functions
+ * here work on plain arrays and values — they hold no reference to models,
+ * pools, or the reactivity system.
  */
 /**
  * Compares two values for sorting, tolerating `null` and `undefined`, which

package/docs/agents.md

@@ -47,7 +47,7 @@ and `claim`. It does **not** expose the stateful-only surface (`get` /
 live connection, so with `transport: 'http'` the return type narrows and they
 are a *compile error*, not a runtime surprise.
 
-## Coordination — claim, queue, reorder
+## Coordination: claim, queue, reorder
 
 The differentiator. A claim is a **durable lease + FIFO wait-line** on a row —
 "who's working on this, who's waiting" — and it's request/response, so an agent

package/docs/api-keys.md

@@ -21,9 +21,9 @@ Pick your row:
 
 | Where your code runs | What to pass | Example |
 |---|---|---|
-| **Server / worker / CLI** (can hold a secret) | your secret `sk_` — it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
-| **Browser — read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
-| **Browser — writing as the signed-in user** | `authEndpoint` — the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, authEndpoint: '/api/ablo-session' })` |
+| **Server / worker / CLI** (can hold a secret) | your secret `sk_`: it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
+| **Browser: read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
+| **Browser: writing as the signed-in user** | `authEndpoint`: the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, authEndpoint: '/api/ablo-session' })` |
 
 That's the whole story: one knob, filled by audience.
 
@@ -31,8 +31,8 @@ That's the whole story: one knob, filled by audience.
 
 | Stripe | Ablo | Where it goes |
 |---|---|---|
-| publishable `pk_` (client-safe) | `pk_` | browser — read-only |
-| secret `sk_` (server, full) | `sk_` | server — full authority |
+| publishable `pk_` (client-safe) | `pk_` | browser: read-only |
+| secret `sk_` (server, full) | `sk_` | server: full authority |
 | restricted `rk_` (granular) | `rk_` | scoped agent sessions (`sessions.create({ agent, can })`) |
 | ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user })`) |
 
@@ -74,7 +74,7 @@ Use API keys from trusted (server-side) runtimes:
 
 Never ship a secret API key to a browser bundle.
 
-## Publishable key (`pk_`) — browser-safe, read-only
+## Publishable key (`pk_`): browser-safe, read-only
 
 For a read-only browser experience, a publishable key is safe to ship in the
 bundle. Like a Stripe `pk_` or a Supabase anon key, it is long-lived,

package/docs/api.md

@@ -120,49 +120,11 @@ blocks), and `ablo.<model>.claim.release({ id })` releases it early. The full
 coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 `claim.release({ id })` / `claim.reorder({ id, order })` hanging off `claim`.
 
-### The Claim State Object
-
-| Field | Type | Description |
-|---|---|---|
-| `object` | `'claim'` | String representing the object's type. |
-| `id` | string | Unique identifier for the claim. |
-| `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
-| `target` | `{ type, id, field? }` | What is being coordinated. |
-| `description` | string | Peer-visible phrase for the work in progress — `'editing'`, `'writing'`, `'reviewing the risk section'`. Defaults to `'editing'`, and rides back in the rejection a blocked writer receives. |
-| `heldBy` | string | Participant id holding the claim. |
-| `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
-| `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
-| `expiresAt` | number | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
-
-```json
-{
-  "object": "claim",
-  "id": "claim_3MtwBwLkdIwHu7ix",
-  "status": "active",
-  "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "description": "editing",
-  "heldBy": "agent:report-writer",
-  "participantKind": "agent",
-  "expiresAt": 1716580000000
-}
-```
-
-### Lifecycle
-
-```
-            claim({ id })              update({ id }) lands
-  (free) ───────────▶ active ───────────────────────▶ committed
-                        │
-            ┌───────────┴───────────┐
-            ▼                       ▼
-        canceled                 expired
-   (release w/o write)        (TTL; holder died)
-```
-
-A target is free when `ablo.<model>.claim.state({ id })` is `null`. Terminal
-states drop out of the live stream, so a present claim is either `active` (the
-holder) or `queued` (waiting in the FIFO line behind the holder; see
-`claim.queue({ id })`).
+The fields on a claim, its lifecycle diagram, and the full method surface are in
+[Coordination](./coordination.md#the-claim-state-object), which is where that
+object is defined. Note that the entity half of `target` is spelled `model`/`id`
+on the SDK's model surface and `type`/`id` on the claim handle and the wait
+line.
 
 ### Reading and claiming
 

package/docs/audit.md

@@ -23,11 +23,12 @@ with which key — and the chain columns that make the log tamper-evident:
   capabilityId:              string | null,    // the API key/capability used for the write
   capabilityLabel:           string | null,    // its human-readable name, for scanning the log
   delegationChainRootUserId: string | null,    // always points at a human
-  actionType:                string,           // e.g. 'weatherReport.update'
-  modelName:                 string,            // e.g. 'claude-opus-4-8'
+  actionType:                'I' | 'U' | 'D',  // insert, update, delete
+  modelName:                 string,           // the model that changed, e.g. 'orders'
+  modelId:                   string,           // the row that changed
   confirmationState:         'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical',
   diffSummary:               unknown,
-  // chain columns — carried on every stored row, checked by verify (below)
+  // chain columns, carried on every stored row and checked by verify (below)
   chainSeq:                  number,
   prevHash:                  string,
   rowHash:                   string,

package/docs/cli.md

@@ -94,18 +94,18 @@ profiles entirely: it acts in whatever project it was minted for.
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
-| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
-| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. |: |
+| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              |: |
+| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           |: |
 | `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
-| `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
+| `ablo dev`                         | **Hosted**: push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
-| `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres** — provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
-| `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
-| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo push`                        | **Hosted**: upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
+| `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
+| `ablo check`                       | **Direct Postgres**: verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
-| `ablo docs`                        | Read these pages for the version you installed — offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
+| `ablo docs`                        | Read these pages for the version you installed: offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
 
 ## `ablo docs`
 
@@ -241,7 +241,7 @@ The one type map, shared by both paths (there is no second mapping):
 | Zod                                                          | Postgres                                                                                                 |
 | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
 | `z.string()`                                                 | `TEXT`                                                                                                   |
-| `z.number()`                                                 | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.number()`                                                 | `DOUBLE PRECISION`: never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
 | `z.boolean()`                                                | `BOOLEAN`                                                                                                |
 | `z.date()`                                                   | `TIMESTAMPTZ`                                                                                            |
 | `z.enum([...])`                                              | `TEXT` + a `CHECK (col IN (...))` constraint                                                             |
@@ -296,7 +296,7 @@ migration can't leave clients gated against tables that don't match.
 
 | Variable                              | Purpose                                                                  | Default                    |
 | ------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
-| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. | —                          |
+| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. |: |
 | `ABLO_API_URL`                        | Control-plane / API host (`push`, `dev`, `status`).                      | `https://api.abloatai.com` |
 | `ABLO_AUTH_URL`                       | Dashboard origin for `ablo login`'s device flow.                         | `https://abloatai.com`     |
 | `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives.                                         | `~/.config/ablo`           |

package/docs/client-behavior.md

@@ -34,7 +34,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
-| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
+| `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |
@@ -218,8 +218,8 @@ Only these imports are public SemVer surface:
 - `@abloatai/ablo`
 - `@abloatai/ablo/schema`
 - `@abloatai/ablo/react`
-- `@abloatai/ablo/testing`
 
 `dataSource(...)` is exported from the root package for customer-owned storage
-adapters. Everything outside the four import paths is internal to Ablo-owned
-apps and infrastructure.
+adapters. Everything outside the three import paths is internal to Ablo-owned
+apps and infrastructure. For adapter authors, `@abloatai/ablo/source/conformance`
+is the suite that proves a storage adapter behaves correctly.

package/docs/concurrency-convention.md

@@ -2,9 +2,9 @@
 
 > The governing rule for how Ablo resolves concurrent writes to shared state.
 
-> The governing convention for how Ablo resolves concurrent writes to shared
-> state, and the boundaries of that convention. This is the contract; the
-> three-layer mechanics live in [`coordination.md`](./coordination.md).
+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).
 
 ---
 
@@ -27,8 +27,8 @@ 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. |
+| **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.
@@ -42,9 +42,9 @@ 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` | **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
@@ -82,9 +82,9 @@ reads: [
 ]
 ```
 
-- **Row** — did this specific row (optionally these fields) change? The literal
+- **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
+- **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.
 
@@ -108,13 +108,13 @@ Shape (canonical in `coordination/schema.ts`):
 
 | field | meaning |
 |---|---|
-| `object` | Stripe-style type tag — `'stale_notification'` |
+| `object` | Stripe-style type tag: `'stale_notification'` |
 | `model`, `id` | the conflicting row (for a group dep, both are the group key) |
 | `group?` | set when this is a group-scoped notification |
 | `readAt` | the watermark the committer reasoned against |
-| `observedSyncId` | the newest delta on the premise — re-read at/after this |
+| `observedSyncId` | the newest delta on the premise: re-read at/after this |
 | `conflictingFields` | fields that moved (empty for group / whole-entity) |
-| `currentValues` | the live values of those fields — the premise to reconcile against (empty for group) |
+| `currentValues` | the live values of those fields: the premise to reconcile against (empty for group) |
 | `writtenBy` | `{ kind, id }` of the concurrent author, reported faithfully |
 
 Only `notify` produces a notification (the write was held). `reject` throws and
@@ -169,7 +169,7 @@ What the convention **guarantees**, and where it **stops**:
    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
+2. **Truthfulness:** `currentValues` / `observedSyncId` reflect committed state at
    detection time, inside the same transaction as the write. A notification is
    never speculative.
 
@@ -185,13 +185,11 @@ What the convention **guarantees**, and where it **stops**:
    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`
-   (back-compat). *Open decision (§7).*
+   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
-   currently resolved directly via each entry's `onStale`, not through the policy
-   seam. *Open decision (§7).*
+   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
@@ -200,29 +198,17 @@ What the convention **guarantees**, and where it **stops**:
 
 ---
 
-## 7. Open decisions (bounded, not yet made)
+## 7. What this convention does not cover
 
-These are deliberately left open; they change behavior and are the user's call.
+Three limits worth knowing before you rely on it.
 
-- **Default disposition for agents.** Should an agent-participant guarded write
-  default to `notify` (philosophy-aligned: surface, don't overwrite) instead of
-  `reject` (back-compat)? Trade-off: alignment vs. a behavior change for existing
-  agent callers.
-- **Batch premises through the policy seam.** Should premise conflicts also
-  pass through `ConflictPolicy` (requires a group-aware conflict shape), or stay
-  on the direct `onStale` mapping?
-
----
-
-## 8. Out of scope
-
-- Irreversible external side-effects (§6.4) — not gated by this convention.
-- Cross-object *serializability proof*. A batch premise is a sound check, not
-  a full precedence-graph guarantee; it catches only what the caller declared.
-  A caller that declares nothing gets **no check at all** — not write-target
-  checking, which needs a `readAt` to check against. A plain write is
-  last-writer-wins, as §6.5 says. The floor is zero, and closing that gap is the
-  subject of ADR 0018.
-- Identity → participant-kind mapping. `writtenBy.kind` reports whatever
-  authenticated (an `sk_` key resolves to `system`, not `agent`); how identities
-  map to kinds is a separate concern.
+- **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.