@abloatai/ablo 0.36.0 → 0.37.1

package/docs/internal/per-field-conflict-detection.md

@@ -0,0 +1,165 @@
+# Per-Field Conflict Detection (Track A)
+
+Maintainer decision doc. Scopes the move from entity-level to field-level stale
+detection in `executeCommit`. Library-free; restores Linear parity for the
+disjoint-field case while keeping the agent-specific `readAt` reject.
+
+## Problem
+
+`executeCommit` Step 0 (`apps/sync-server/src/mutators/commit.ts`) detects stale
+writes at **entity granularity**:
+
+```sql
+SELECT MAX(id) FROM sync_deltas WHERE model_name = ? AND model_id = ?
+```
+
+If `observed > op.readAt`, the op conflicts. This means two writers touching
+**different fields** of the same row collide falsely: agent A sets
+`report.status`, human B sets `report.reviewer`, B carried a `readAt` from before A's
+write → B is rejected with `AbloStaleContextError`, even though the edits never
+overlapped.
+
+This is an over-rejection. It is also stricter than the system we
+reverse-engineered from (Linear), which never had this problem.
+
+## Why Linear says this is right
+
+The model is reverse-engineered from Linear's sync engine. Linear's design
+confirms every load-bearing choice here:
+
+- **Transactions are property-level.** Linear's `UpdateTransaction` records
+  "the name of the changed property and its previous value" — it carries only
+  the changed properties, not a whole-object snapshot. Our `changed_fields`
+  column re-derives exactly that.
+- **Resolution is last-writer-wins, per property, by total order:** `syncId`
+  (our `sync_id_seq`) is the total order. A partial transaction applies only its
+  properties, so two clients editing **different** properties both win — LWW
+  only bites on the **same** property.
+- **CRDT is used only for issue descriptions.** Linear keeps LWW-per-property
+  for structured fields and reserves a CRDT for the one rich-text body. That is
+  the same Track A / Track B line we draw: this doc is Track A; rich-text bodies
+  (TipTap `content_json`) are out of scope and belong to a separate CRDT track.
+
+So Track A is not a new feature — it **restores Linear parity** at the property
+level we had flattened to entity level.
+
+Sources: [reverse-linear-sync-engine (CTO-endorsed)](https://github.com/wzhudev/reverse-linear-sync-engine/blob/main/SUMMARY.md),
+[Architectures for Central Server Collaboration — Weidner](https://mattweidner.com/2024/06/04/server-architectures.html).
+
+## The constraint that shapes the design
+
+`sync_deltas.data` stores the **full post-update row**, not the changed columns.
+This was a deliberate change (see `feedback_partial_update_delta_ui_drift`) so
+the live-pool update path fires MobX reactivity for nested fields. Consequence:
+we **cannot** recover "which fields did this delta change" from `data` — a
+full-row snapshot does not tell you what moved.
+
+We do have the changed set for free at write time: `Object.keys(snakeInput)` at
+`commit.ts` UPDATE branch, after the unknown-column strip and before the
+`updated_at` injection. So this is a write-side capture + a read-side
+intersection, not a diff-the-snapshots problem.
+
+## Design
+
+### 1. Schema: `sync_deltas.changed_fields text[]` (nullable)
+
+- Populate **only for UPDATE** with the real changed columns
+  (`Object.keys(snakeInput)` after strip, before `updated_at`).
+- Leave `null` for CREATE / DELETE / ARCHIVE / UNARCHIVE.
+
+`null` is semantically "whole-entity change" and always conflicts. This gives a
+**safe migration**: every pre-migration delta is `null`, so detection falls back
+to exactly today's entity-level behavior. Field granularity phases in only as
+new deltas land — no risky backfill.
+
+We store **field names only**, not previous values. LWW needs no value
+comparison (latest `sync_id` wins); names are sufficient for the overlap check
+that drives the optional reject. Prev-values would only matter for
+"same field, same value ⇒ not a conflict" tie-breaking — defer it.
+
+### 2. Detection rewrite: Step 0 (`commit.ts`)
+
+Replace the scalar `MAX(id)` with a field-aware scan:
+
+```ts
+// op's own field set (snake-cased, framework cols excluded)
+const opFields = new Set(Object.keys(op.input ?? {}).map(toSnakeCase));
+
+const rows = await tx.unsafe(
+  `SELECT id, changed_fields FROM sync_deltas
+    WHERE model_name = $1 AND model_id = $2 AND id > $3
+    ORDER BY id DESC`,
+  [mapping.modelName, op.id, op.readAt] as never[],
+);
+
+// Conflict iff a newer delta touched a field this op also writes,
+// OR a newer delta is whole-entity (changed_fields IS NULL → CREATE/DELETE).
+const overlap = rows.find(
+  (r) => r.changedFields === null || r.changedFields.some((f) => opFields.has(f)),
+);
+if (overlap) {
+  conflicts.push({
+    /* ...existing fields... */
+    observedSyncId: overlap.id,
+    conflictingFields: intersect(overlap.changedFields, opFields),
+  });
+}
+```
+
+Disjoint-field concurrent writes now produce **no conflict** — they both apply.
+That is LWW-per-field achieved by *not rejecting*; no merge code.
+
+### 3. Policy type: additive (`packages/transaction/src/policy/types.ts`)
+
+Extend `StaleContextConflict` with:
+
+```ts
+readonly conflictingFields?: readonly string[];
+```
+
+Pure addition. `defaultPolicy` still rejects; existing policies compile
+unchanged. A policy can now reason at field granularity, e.g. allow when the
+only conflicting field is cosmetic.
+
+### 4. Scope boundary (honest)
+
+Granularity is **column-level**, not JSON-path. Two writers editing different
+keys *inside* one `content_json` column still conflict — that is the rich-text
+case (Track B / CRDT), not this. JSON Merge Patch (RFC 7386) sub-column
+granularity is a later refinement on the same column; v1 stops at columns.
+
+## Relationship to the existing `readAt` reject
+
+Linear is pure LWW-per-property with no stale check. We keep `readAt` /
+`onStale: 'reject'` as an **opt-in** for the agent-reasoned-against-stale-state
+case (an LLM that read a stale value and reasoned on it is a real failure mode
+humans rarely hit). After Track A:
+
+- **No `readAt`** → LWW-per-field, Linear parity: disjoint fields never conflict.
+- **`readAt` set** → reject only if a newer delta touched a field this op also
+  writes. The `changed_fields` column makes that intersection computable.
+- **`onStale: 'overwrite'`** → unchanged; still skips detection entirely.
+
+## Index
+
+Verify a `(model_name, model_id, id)` index exists on `sync_deltas` (the old
+`MAX(id)` relied on it too). The new query is a bounded range scan (`id >
+readAt`, usually a small recent window) on the same index prefix.
+
+## Tests (vitest, sync-server)
+
+- Disjoint fields (A: `status`, B: `assignee`, same row, both stale `readAt`) →
+  **both commit, no `AbloStaleContextError`** — the regression that proves the win.
+- Same field, both stale → still rejects (default policy unchanged).
+- DELETE after `readAt` → conflicts regardless of op fields (`null`).
+- Pre-migration delta (`null`) in the window → conflicts (back-compat).
+- `onStale: 'overwrite'` → still skips detection.
+
+## Touch list
+
+- `sync_deltas` migration — add `changed_fields text[]`.
+- `commit.ts` — Step 0 detect rewrite + UPDATE write path populates
+  `changed_fields` + `deltaInfos` shape.
+- `apps/sync-server/src/db/deltas.ts` — insert path carries `changed_fields`.
+- `packages/transaction/src/policy/types.ts` — additive `conflictingFields`.
+- vitest in sync-server.

package/docs/internal/postgres-replication.md

@@ -0,0 +1,64 @@
+# Postgres replication: internal architecture
+
+> **Status: wired and covered by unit and real-Postgres journeys.** This is server-internal code under `apps/sync-server/src/replication/postgres/`; it is not an SDK surface.
+
+## Why this exists
+
+Ablo observes a customer's Postgres through a publication and logical-replication slot. The customer owns the schema and write path. Ablo decodes committed changes, appends them to its control-plane log, and serves sync from that log. The low-level decoder and lifecycle draw on Zero and PowerSync patterns; ADR 0002 governs the product boundary.
+
+## The one job
+
+**Postgres `pgoutput` messages → `PreparedDelta[]` + a confirmed LSN.** The consumer writes through `appendExternalDeltas`; deltas land in the control-plane `sync_deltas` log and use the normal fan-out pipeline.
+
+## Module map (`apps/sync-server/src/replication/postgres/`)
+
+| file                                                     | role                                                       | provenance                    |
+| -------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------- |
+| `binaryReader.ts`                                        | big-endian protocol reader                                 | modeled on Zero               |
+| `pgoutputTypes.ts`, `pgoutput.ts`                        | typed `pgoutput` messages and decoder                      | modeled on Zero               |
+| `lsn.ts`                                                 | `LSN` string ↔ `bigint` (`toBigInt`/`fromBigInt`)          | ported subset ← Zero `lsn.ts` |
+| `connection.ts`, `stream.ts`, `streamAdapter.ts`         | dedicated query/replication connections and stream adapter | Zero/PowerSync patterns       |
+| `assembler.ts`                                           | buffers a transaction and maps changes to `PreparedDelta`  | Ablo adapter                  |
+| `consumer.ts`                                            | persist-before-ack consume loop with retry                 | PowerSync/Ablo patterns       |
+| `slot.ts`, `slotLease.ts`, `backfill.ts`, `watermark.ts` | slot ownership, initial snapshot, and durable progress     | Ablo                          |
+| `sources.ts`, `fleet.ts`, `start.ts`                     | registry resolution, reconciliation, start/stop lifecycle  | Ablo                          |
+| `preflight.ts`, `readiness.ts`, `publicationDrift.ts`    | registration checks and runtime diagnostics                | Ablo                          |
+
+## Data flow
+
+```
+registered Postgres source
+  → replication slot + initial snapshot
+  → pgoutput stream
+  → TransactionAssembler
+  → WalConsumer
+  → appendExternalDeltas(controlSql, deltas, context)
+  → persist watermark
+  → acknowledge commit LSN
+```
+
+### Mapping (in `TransactionAssembler`, mirrors `events.ts:eventsToDeltas`)
+
+- `actionType`: `insert→'I'`, `update→'U'`, `delete→'D'` (the 1:1 pgoutput↔Ablo coincidence).
+- `modelName`: `mapping.tableToModel(schema, table)` — `null` skips the change.
+- `modelId`: `mapping.rowToModelId(key)` over the replica-identity key.
+- `data`: the row bound as an **object, never pre-stringified** (the jsonb double-encode trap at `deltaAppend.ts`).
+- `transactionId`: `String(xid)`.
+
+## Load-bearing invariants
+
+- **Persist-before-ack** (`WalConsumer`): `appendExternalDeltas` and the watermark transaction resolve before `ack(commitLsn)`. A crash between them replays work instead of losing it.
+- **Keepalive watermark** (`streamAdapter.ts`, `stream.ts`): every reply carries the last confirmed LSN, never the server's live position — the timed status update included.
+- **Liveness off the socket** (`stream.ts`): a status update goes out every 75% of the upstream's `wal_sender_timeout` whether or not the consumer is reading, so backpressure cannot get the connection terminated for silence; inbound silence on a stream we are reading for twice that long destroys it and falls into the per-source backoff. A `wal_sender_timeout` of 0 runs untimed.
+- **Failover-capable slot** (`slot.ts`): from PostgreSQL 17 the slot is created with `FAILOVER true`, so a customer failover leaves our position intact instead of forcing the re-snapshot path. It only takes effect where the standby has `sync_replication_slots = on`, which the preflight recommends and never requires.
+- **Fresh subscription per retry** (`WalConsumer`): every backoff iteration opens a new subscription so a half-dead socket / stale relation cache never carries into the retry.
+- **Per-source isolation** (`start.ts`, `fleet.ts`): one broken source reports and retries without stopping healthy sources.
+- **Runtime reconciliation** (`fleet.ts`): registrations, removals, schema changes, and secret rotations converge without a server restart.
+
+## Tests
+
+Unit tests live beside the implementation in `replication/postgres/__tests__`. Real-Postgres coverage is grouped under `src/__journeys__/postgres-replication-*.journey.test.ts`: registration, registry migration, backfill, live streaming, source changes, bootstrap, query serving, read cutover, and customer-database isolation.
+
+## Operations
+
+Registration is the enable signal. `startPostgresReplication` starts the fleet after the server begins listening; `postgresReplicationReady` is drained during graceful shutdown. Use `docs/runbooks/connect-customer-database-postgres-replication.md` for source setup and live verification.

package/docs/internal/serializable-schema.md

@@ -0,0 +1,119 @@
+# A `Schema` is serializable
+
+A `Schema` (output of `defineSchema`) is JSON-serializable except for two
+things, both of which are client-only:
+
+- **Zod validators:** `model().schema` / `.shape`, `Schema.validators`. Used
+  by the client for type inference + validation. The server never reads them
+  (it checks `information_schema.columns` and does no field-shape validation in
+  the commit path).
+
+Everything the server reads — `typename`, `tableName`, `mutable`, `load`, the
+canonical `tenancy` descriptor (the `policy` authoring option is normalized away
+at build), bootstrap hints, `relations` (`foreignKeyColumn`), field names, and
+`identityRoles` — is plain data.
+
+## Identity roles are pure data
+
+```ts
+interface IdentityRole {
+  kind: string;
+  template: string;            // 'org:{id}'
+  source: IdentityRoleSource;  // { field: 'organizationId', multi: false }
+}
+```
+
+The runtime behaviour lives in `extractIdentityIds(identity, source)`, a pure
+function `composeIdentitySyncGroups` calls once per role. `identityRole({ kind,
+template, source, multi? })` is the factory. Absent/falsy fields yield `[]`, so
+a role whose field isn't present (a user with no `teamIds`) is a silent no-op —
+org-only, org+user, and org+team are just different `identityRoles` arrays, not
+different code paths. The engine ships zero prefixes; `org:`/`user:`/`team:`
+live only in `ablo.schema.ts`.
+
+## Why this matters
+
+Because a `Schema` carries no closures, the same object works in-process and,
+for a hosted multi-tenant server, after being reconstructed from JSON over the
+control plane (the GraphQL `printSchema` / `buildSchema` model). One type,
+both places — no separate server-side schema type.
+
+`apps/sync-server` reads the live `schema` directly today
+(`buildModelMap(schema)`, `composeIdentitySyncGroups` via the `@ablo/schema`
+wrapper).
+
+## Trust boundary
+
+Never trust a client-connection schema for authz (Zero/Convex/Instant). A
+client connection may carry only the schema **version** for compatibility
+gating; the authoritative `Schema` arrives over an authenticated control-plane
+path. The identity passed to `composeIdentitySyncGroups` is server-resolved
+trusted claims.
+
+## Wire form (`serialize.ts`)
+
+`serializeSchema(schema): string` / `parseSchema(json): Schema` are the
+control-plane transport — the GraphQL `printSchema`/`buildSchema` model. The
+JSON (`SchemaJSON`, envelope `{ v, models, identityRoles }`) carries every
+model's routing/scoping metadata, relations (incl. resolved
+`foreignKeyColumn`), field metadata, and identity roles. `parseSchema` rebuilds
+each model's Zod permissively from `FieldMeta` (the server does no field-shape
+validation) and drops `computed` closures. `schemaHash(schema)` is the stable
+FNV-1a content hash used for connect-time gating. Round-trip tested in
+`__tests__/serialize.test.ts`.
+
+## Storage + runtime resolution (`apps/sync-server/src/schema/`): built
+
+- **`ablo_schemas` table** (`packages/database/prisma/models/sync.prisma`,
+  `SchemaArtifact`) — `(organizationId, version, schemaJson, schemaHash, state,
+  error, createdBy, createdAt, activatedAt)`, unique `(orgId, version)`. State
+  `pending|validated|active|overwritten|failed`, ≤1 active per tenant (Convex
+  `_schemas` machine; Zero's "row in the operational DB"). *Migration written,
+  not applied — 0 users, Neon direct-endpoint rule.*
+- **`pgSchemaStore` / `memorySchemaStore`** (`schemaStore.ts`) — mirrors
+  `pgApiKeyStore`. `insertPending` assigns `MAX(version)+1`; `activate` is a
+  transaction that demotes the current active → `overwritten` then promotes the
+  target. State-machine invariants tested.
+- **`createSchemaRegistry(store)`** (`schemaRegistry.ts`) — `load(orgId)` parses
+  the active artifact's `schemaJson` to a `Schema` and caches it (shared
+  in-flight promise across concurrent cold loads); `invalidate(orgId)` busts it
+  on activation (Convex `schema_registry`). This is the seam that turns the
+  boot-time `import { schema }` into per-tenant runtime resolution.
+
+## Push route (`apps/sync-server/src/routes/schema.ts`): built
+
+`POST /api/schema`, mounted in `index.ts` (`schemaRoutes({ provider, store,
+registry })`). Auth: secret `sk_` key carrying the `schema:push` scope —
+`Identity.scopes` was added and `apiKeyProvider` now populates it from the key
+row's `scopes` column (restricted `rk_` keys get no `scopes`, so they're
+excluded). Tenant comes from `identity.organizationId`, never the body. Flow:
+read `{ schema, force? }` → validate via `parseSchema` (throws → 400) →
+authoritative hash via `schemaHash(parsed)` → reject removed-model changes (409)
+unless `force` → no-op fast path on identical hash (200) → `insertPending` →
+`activate` → `registry.invalidate(org)` → 201 `{ schemaId, version, hash }`. 6
+route tests.
+
+## CLI (`packages/ablo-cli`): built
+
+`ablo push` (`src/push.ts`, dispatched from `index.ts`). Imports the
+user's `sync/schema.ts` at runtime via tsx's `tsImport` (the real object —
+`migrate`'s regex parse can't produce a faithful AST), then `serializeSchema`
++ `schemaHash` and POSTs `{ schema, force, renames }` to `POST /api/schema`
+with `Authorization: Bearer $ABLO_API_KEY`. Flags: `--schema`, `--export`,
+`--url` (`$ABLO_API_URL`, default `https://api.abloatai.com`), `--force`,
+`--rename old:new` (repeatable). The route honors `renames` so a renamed model
+isn't flagged as a removed-model incompatibility. `parsePushArgs` unit-tested.
+
+## Schema drift is advisory
+
+Bootstrap includes the tenant's active schema hash. The client compares it to
+its built-in hash and warns once when they differ. Hash drift never closes the
+WebSocket: an additive rollout must allow old and new clients to overlap while
+data is expanded, dual-read/written, backfilled, verified, and finally
+contracted. Breaking wire shapes use the protocol-version codec registry
+instead.
+
+## Not built yet
+- **Switch the hot paths to per-tenant `registry.load(org)`:** boot still does
+  the single-tenant `import { schema }`; `buildModelMap`/bootstrap/commit
+  reading the registry per request is the final multi-tenant wiring.

package/docs/internal/structure.md

@@ -0,0 +1,32 @@
+# Repository Structure
+
+The public repository preserves the same ownership boundaries as the main
+monorepo. `@abloatai/ablo` is the product package; the packages beneath it are
+implementation owners and first-party extension surfaces.
+
+| Workspace | Responsibility |
+| --- | --- |
+| `packages/ablo` | Branded SDK, public entrypoints, docs, examples, release assets |
+| `packages/transaction` | Headless HTTP client, canonical contracts, reads, commits, settlement, claims, durable observation |
+| `packages/humans` | Reactive materializer, WebSocket transport, presence, browser persistence, React |
+| `packages/agent` | Agent behavior, perception, and coordination helpers |
+| `packages/cli` | Project setup, database connection, schema operations, and diagnostics |
+| `packages/tsconfig` | Private shared compiler configuration |
+
+Applications install and import `@abloatai/ablo`. The root entrypoint is the
+headless HTTP API. Human-facing reactive behavior is explicit:
+
+```ts
+import Ablo from '@abloatai/ablo';
+import ReactiveAblo from '@abloatai/ablo/client';
+import { AbloProvider, useAblo } from '@abloatai/ablo/react';
+```
+
+The backend implementation remains in `apps/sync-server` in the private
+monorepo. It consumes transaction contracts but is not part of the public SDK
+repository.
+
+Internal packages must not import the branded facade. Dependencies point from
+the facade to the owners, from humans and agents to transaction, and never back
+upward. The public mirror copies these workspaces as workspaces; it does not
+flatten them or generate compatibility source.

package/docs/mcp.md

@@ -57,7 +57,7 @@ Each tool mirrors an SDK verb, scoped to a model + id. Model names come from
 
 | Tool | Mirrors | Does |
 |---|---|---|
-| `get_model` | `ablo.<model>.local.retrieve(id)` | read latest state + active claims |
+| `get_model` | `ablo.<model>.local.get(id)` | read latest state + active claims |
 | `list_records` | `ablo.<model>.list({…})` | cursor-paginated list with filters |
 | `create_model` | `ablo.<model>.create({ data })` | guarded create |
 | `update_model` | `ablo.<model>.update({ id, … })` | guarded update |
@@ -132,7 +132,7 @@ loading everything into context.
 
 Reusable, parameterised templates that drive an end-to-end flow:
 
-- `integrate-sync-engine` — wire the SDK into an existing project.
+- `integrate-ablo` — wire the SDK into an existing project.
 - `add-agent` — add an agent worker that coordinates via claims and
   conflict-safe writes.
 - `define-schema` — design a Zod-first schema from a description, then run

package/docs/migration.md

@@ -14,7 +14,7 @@ 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** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.get(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 })` |
@@ -56,7 +56,7 @@ unchanged: it has always carried seconds and still does.
 - 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 task  = ablo.tasks.local.get(id);
 + const open  = ablo.tasks.local.list({ where: { status: 'open' } });
 + const count = ablo.tasks.local.count({ where: { status: 'open' } });
 ```
@@ -304,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.local.retrieve(id)) ?? serverTask
++ useAblo((ablo) => ablo.tasks.local.get(id)) ?? serverTask
 ```
 
 `claim` now returns a disposable handle instead of taking a callback. The handle

package/docs/quickstart.md

@@ -215,12 +215,12 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
-Read a single row back with `retrieve({ id })`. It resolves to the row, or to
+Read a single row back with `get({ id })`. It resolves to the row, or to
 `undefined` when no row has that id — so narrow it once, then the fields are
 fully typed:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id: created.id });
+const report = await ablo.weatherReports.get({ id: created.id });
 if (!report) throw new Error(`weatherReports ${created.id} not found`);
 
 console.log(report.status); // 'ready'

package/docs/react.md

@@ -98,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.local.retrieve(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
@@ -108,7 +108,7 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Uses the same `ablo.<model>.local.retrieve(id)` / `.local.list()` methods you'd call anywhere
+1. Uses the same `ablo.<model>.local.get(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.
@@ -123,7 +123,7 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.retrieve(id))`. Older hooks
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.get(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:
@@ -141,12 +141,12 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const report = await ablo.weatherReports.retrieve({ id });
+const report = await ablo.weatherReports.get({ id });
 ```
 
 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
+`await` it. (Server reads come in two shapes: `get({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
 the `local` reads, used in render below.)
 

package/docs/schema-contract.md

@@ -12,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>.local.retrieve(id))`,
+- React selectors through `useAblo((ablo) => ablo.<model>.local.get(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.
@@ -70,14 +70,14 @@ readable, you just don't author them.
 Use async reads when the row may not be local:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id: reportId });
+const report = await ablo.weatherReports.get({ id: reportId });
 const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 ```
 
 Use synchronous local reads in render after data has synced:
 
 ```ts
-const report = ablo.weatherReports.local.retrieve(reportId);
+const report = ablo.weatherReports.local.get(reportId);
 const pending = ablo.weatherReports.local.list({ where: { status: 'pending' } });
 ```