@abloatai/ablo 0.6.0 → 0.7.0

package/dist/schema/tenancy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tenancy — the single source of truth for how a model's rows are scoped to a
+ * tenant. This replaces three scattered mechanisms (a hardcoded
+ * `organization_id` literal, an `orgScoped` boolean, and a `scopedVia` ref) with
+ * one Zod discriminated union, resolved in one place and consumed everywhere
+ * (provision/RLS, introspection, runtime, CLI).
+ *
+ * Why a union: every consumer used to re-derive "how is this table scoped?" from
+ * a flag plus a literal — a missed branch was a silent cross-tenant scoping bug.
+ * A discriminated union makes the `switch` exhaustive, so the type system holds
+ * the isolation boundary, and the physical column name lives in exactly one
+ * place (the `column` variant) instead of being hardcoded across the codebase.
+ */
+import { z } from 'zod';
+/** Default physical tenancy column. The ONLY place this literal is canonical. */
+export declare const DEFAULT_ORG_COLUMN = "organization_id";
+/**
+ * Scope a table's rows through a parent table (for rows that carry no tenancy
+ * column of their own — e.g. `slide_layers` → slide → deck → org).
+ */
+export declare const scopedViaRefSchema: z.ZodObject<{
+    localKey: z.ZodString;
+    parentTable: z.ZodString;
+    parentKey: z.ZodOptional<z.ZodString>;
+    parentOrgColumn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ScopedViaRef = z.infer<typeof scopedViaRefSchema>;
+/** How a model's rows are scoped to a tenant. */
+export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    column: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"parent">;
+    via: z.ZodObject<{
+        localKey: z.ZodString;
+        parentTable: z.ZodString;
+        parentKey: z.ZodOptional<z.ZodString>;
+        parentOrgColumn: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strip>], "kind">;
+export type Tenancy = z.infer<typeof tenancySchema>;
+/**
+ * Ergonomic authoring shortcuts accepted on a model. These are *input only* —
+ * `resolveTenancy` normalizes them into the canonical {@link Tenancy} at
+ * model-build time, so they never reach the serialized JSON or any consumer.
+ */
+export interface TenancyInput {
+    tenancy?: Tenancy;
+    /** `false` → not tenant-scoped. */
+    orgScoped?: boolean;
+    /** Scope through a parent table. */
+    scopedVia?: ScopedViaRef;
+    /** Override the column name for a column-scoped model. */
+    orgColumn?: string;
+}
+/**
+ * Normalize authoring sugar into the one canonical {@link Tenancy}. Called once,
+ * at model-build, so `ModelDef`/`ModelJSON` and every consumer see only
+ * `tenancy`. Precedence: explicit `tenancy` → `scopedVia` → `orgScoped:false` →
+ * column (default or `orgColumn`).
+ */
+export declare function resolveTenancy(input: TenancyInput): Tenancy;
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export declare function tenancyColumn(t: Tenancy): string | null;

package/dist/schema/tenancy.js

@@ -0,0 +1,58 @@
+/**
+ * Tenancy — the single source of truth for how a model's rows are scoped to a
+ * tenant. This replaces three scattered mechanisms (a hardcoded
+ * `organization_id` literal, an `orgScoped` boolean, and a `scopedVia` ref) with
+ * one Zod discriminated union, resolved in one place and consumed everywhere
+ * (provision/RLS, introspection, runtime, CLI).
+ *
+ * Why a union: every consumer used to re-derive "how is this table scoped?" from
+ * a flag plus a literal — a missed branch was a silent cross-tenant scoping bug.
+ * A discriminated union makes the `switch` exhaustive, so the type system holds
+ * the isolation boundary, and the physical column name lives in exactly one
+ * place (the `column` variant) instead of being hardcoded across the codebase.
+ */
+import { z } from 'zod';
+/** Default physical tenancy column. The ONLY place this literal is canonical. */
+export const DEFAULT_ORG_COLUMN = 'organization_id';
+/**
+ * Scope a table's rows through a parent table (for rows that carry no tenancy
+ * column of their own — e.g. `slide_layers` → slide → deck → org).
+ */
+export const scopedViaRefSchema = z.object({
+    /** Column on THIS table pointing at the parent (e.g. `'team_id'`). */
+    localKey: z.string().min(1),
+    /** Parent table name (e.g. `'team'`). */
+    parentTable: z.string().min(1),
+    /** Column on the parent that `localKey` references. Default `'id'`. */
+    parentKey: z.string().min(1).optional(),
+    /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+    parentOrgColumn: z.string().min(1).optional(),
+});
+/** How a model's rows are scoped to a tenant. */
+export const tenancySchema = z.discriminatedUnion('kind', [
+    /** Row-local tenancy column (default name `organization_id`, overridable). */
+    z.object({ kind: z.literal('column'), column: z.string().min(1) }),
+    /** Scoped through a parent table's tenancy. */
+    z.object({ kind: z.literal('parent'), via: scopedViaRefSchema }),
+    /** Not tenant-scoped (global / reference data). */
+    z.object({ kind: z.literal('none') }),
+]);
+/**
+ * Normalize authoring sugar into the one canonical {@link Tenancy}. Called once,
+ * at model-build, so `ModelDef`/`ModelJSON` and every consumer see only
+ * `tenancy`. Precedence: explicit `tenancy` → `scopedVia` → `orgScoped:false` →
+ * column (default or `orgColumn`).
+ */
+export function resolveTenancy(input) {
+    if (input.tenancy)
+        return input.tenancy;
+    if (input.scopedVia)
+        return { kind: 'parent', via: input.scopedVia };
+    if (input.orgScoped === false)
+        return { kind: 'none' };
+    return { kind: 'column', column: input.orgColumn ?? DEFAULT_ORG_COLUMN };
+}
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export function tenancyColumn(t) {
+    return t.kind === 'column' ? t.column : null;
+}

package/dist/sync/HydrationCoordinator.d.ts

@@ -113,6 +113,8 @@ export declare class HydrationCoordinator {
     private hydrateExpanded;
     private persistToIdb;
     private resolveTypename;
+    private columnizeField;
+    private columnizeClause;
 }
 /**
  * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`

package/dist/sync/HydrationCoordinator.js

@@ -161,10 +161,10 @@ export class HydrationCoordinator {
         const firstOrder = orderEntries[0];
         const query = {
             model: typename,
-            where: clauses.map((c) => columnizeClause(c)),
+            where: clauses.map((c) => this.columnizeClause(modelName, c)),
             ...(firstOrder
                 ? {
-                    orderBy: columnize(firstOrder[0]),
+                    orderBy: this.columnizeField(modelName, firstOrder[0]),
                     order: firstOrder[1] ?? 'asc',
                 }
                 : {}),
@@ -256,6 +256,27 @@ export class HydrationCoordinator {
             .models?.[modelName];
         return def?.typename ?? modelName;
     }
+    columnizeField(modelName, field) {
+        const fields = this.opts.schema.models?.[modelName]?.fields;
+        if (fields) {
+            const direct = fields[field]?.column;
+            if (direct)
+                return direct;
+            for (const [fieldName, meta] of Object.entries(fields)) {
+                const conventional = columnize(fieldName);
+                if (field === fieldName || field === conventional || field === meta.column) {
+                    return meta.column ?? conventional;
+                }
+            }
+        }
+        return /[A-Z]/.test(field) ? columnize(field) : field;
+    }
+    columnizeClause(modelName, clause) {
+        const finalCol = this.columnizeField(modelName, clause[0]);
+        if (clause.length === 2)
+            return [finalCol, clause[1]];
+        return [finalCol, clause[1], clause[2]];
+    }
 }
 // ── Helpers ────────────────────────────────────────────────────────────
 function stableKey(modelName, clauses, orderBy, limit) {
@@ -350,21 +371,6 @@ export function normalizeWhere(where) {
     }
     return [];
 }
-/**
- * Apply `columnize` to the column name of a wire-bound clause so the
- * server sees `slide_id` instead of `slideId`. Tuple-form clauses from
- * callers are passed through unchanged — they already supply the wire
- * column name (matches what existing `postQuery` consumers do).
- */
-function columnizeClause(clause) {
-    const col = clause[0];
-    // If the column already looks snake_case (no uppercase letters), assume
-    // the caller is already using server-side naming. Otherwise camelize→snake.
-    const finalCol = /[A-Z]/.test(col) ? columnize(col) : col;
-    if (clause.length === 2)
-        return [finalCol, clause[1]];
-    return [finalCol, clause[1], clause[2]];
-}
 /** Equality-only subset of clauses, keyed by column. Used by IDB fast paths. */
 function extractEqClauses(clauses) {
     const out = {};

package/dist/sync/createIntentStream.d.ts

@@ -11,7 +11,8 @@
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
  *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId } }`
+ *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
+ *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
  *     stamped with `declaredAt`, `expiresAt`.
  *   • Inbound: `intent_rejected` event with conflict metadata.

package/dist/sync/createIntentStream.js

@@ -11,7 +11,8 @@
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
  *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId } }`
+ *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
+ *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
  *     stamped with `declaredAt`, `expiresAt`.
  *   • Inbound: `intent_rejected` event with conflict metadata.
@@ -38,6 +39,7 @@ export function createIntentStream(config, transport = null) {
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
+    const lostListeners = new Set();
     const notifyListeners = () => {
         intentsSnapshot = Object.freeze(Array.from(activeByIntentId.values()));
         for (const l of listeners) {
@@ -131,6 +133,24 @@ export function createIntentStream(config, transport = null) {
                 }
             }
         }));
+        // (2a) Server-side LOSS frames — you held it, then lost it (preempted /
+        //      expired). Distinct from a rejection (a claim the server refused).
+        unsubs.push(t.subscribe('intent_lost', (payload) => {
+            const lost = payload;
+            if (!lost.intentId)
+                return;
+            // Drop the lost own-claim so reconnect doesn't re-announce a lease we
+            // no longer hold.
+            ownIntents.delete(lost.intentId);
+            for (const l of lostListeners) {
+                try {
+                    l(lost);
+                }
+                catch {
+                    /* isolate */
+                }
+            }
+        }));
         // (2b) Per-entity wait-queue snapshots. The server fans the full line
         //      out on every queue mutation; we replace our cached line for that
         //      entity and notify so `queue(target)` reads reactively.
@@ -178,6 +198,20 @@ export function createIntentStream(config, transport = null) {
             },
         });
     }
+    function sendReorder(entityType, entityId, order) {
+        if (!attached?.isConnected())
+            return;
+        attached.send({
+            type: 'intent_reorder',
+            payload: {
+                entityType,
+                entityId,
+                // The wire shape identifies a waiter by heldBy + intentId; map the
+                // ergonomic `Intent[]` (what `queueFor` returns) down to that.
+                order: order.map((i) => ({ heldBy: i.heldBy, intentId: i.id })),
+            },
+        });
+    }
     function sendAbandon(intentId, intent) {
         if (!attached?.isConnected())
             return;
@@ -252,6 +286,10 @@ export function createIntentStream(config, transport = null) {
             const ref = resolveTarget(target);
             return queueByEntity.get(entityKey(ref.type, ref.id)) ?? EMPTY_QUEUE;
         },
+        reorder(target, order) {
+            const ref = resolveTarget(target);
+            sendReorder(ref.type, ref.id, order);
+        },
         onChange: (listener) => {
             listeners.add(listener);
             return () => {
@@ -264,6 +302,12 @@ export function createIntentStream(config, transport = null) {
                 rejectionListeners.delete(listener);
             };
         },
+        onLost: (listener) => {
+            lostListeners.add(listener);
+            return () => {
+                lostListeners.delete(listener);
+            };
+        },
         [Symbol.asyncIterator]() {
             return asyncIteratorFrom((onChange) => {
                 listeners.add(onChange);
@@ -279,6 +323,7 @@ export function createIntentStream(config, transport = null) {
             unsubs.length = 0;
             listeners.clear();
             rejectionListeners.clear();
+            lostListeners.clear();
             activeByIntentId.clear();
             ownIntents.clear();
             queueByEntity.clear();

package/dist/sync/participants.js

@@ -1,3 +1,4 @@
+import { scopeKindOf } from '../schema/model.js';
 export function createParticipantManager(config) {
     return {
         async join(input, overrides) {
@@ -74,17 +75,13 @@ export function resolveParticipantSyncGroups(scope, schema) {
 }
 export function syncGroupFromEntityRef(ref, schema) {
     const match = findModelForEntityRef(ref, schema);
-    if (match?.def.syncGroupFormat) {
-        return renderSyncGroupFormat(match.def.syncGroupFormat, { id: ref.id });
-    }
-    return `${ref.type.toLowerCase()}:${ref.id}`;
+    const kind = match ? scopeKindOf(match.def, match.key) : undefined;
+    return `${kind ?? ref.type.toLowerCase()}:${ref.id}`;
 }
 function syncGroupFromSchemaKey(schemaKey, id, schema) {
     const def = schema?.models?.[schemaKey];
-    if (def?.syncGroupFormat) {
-        return renderSyncGroupFormat(def.syncGroupFormat, { id });
-    }
-    return `${schemaKey}:${id}`;
+    const kind = def ? scopeKindOf(def, schemaKey) : undefined;
+    return `${kind ?? schemaKey}:${id}`;
 }
 function findModelForEntityRef(ref, schema) {
     if (!schema?.models)
@@ -98,12 +95,6 @@ function findModelForEntityRef(ref, schema) {
     }
     return null;
 }
-function renderSyncGroupFormat(format, values) {
-    return format.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, key) => {
-        const value = values[key];
-        return value === undefined ? `{${key}}` : value;
-    });
-}
 export function parseParticipantTtlSeconds(value) {
     if (typeof value === 'number' && Number.isFinite(value))
         return value;

package/dist/types/streams.d.ts

@@ -9,6 +9,8 @@
  * the shared coordination substrate.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
+import type { TargetRange, OnStaleMode, IntentClaim, PresenceKind } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, IntentClaim, PresenceKind };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form
  * metadata that will be persisted / transported as JSON — avoids
@@ -113,13 +115,6 @@ export interface ContextChange {
  * snapshot. Defaults to `'reject'` when `readAt` is provided without
  * `onStale`.
  */
-export type OnStaleMode = 'reject' | 'flag' | 'merge' | 'force';
-export interface TargetRange {
-    readonly startLine: number;
-    readonly endLine: number;
-    readonly startColumn?: number;
-    readonly endColumn?: number;
-}
 /**
  * A pointer to one entity, optionally narrowed to a structured
  * subtarget. `type` and `id` are customer schema vocabulary; `path`,
@@ -304,32 +299,6 @@ export interface Peer {
     /** Pending-mutation intents this participant has declared. */
     readonly activeIntents?: ReadonlyArray<IntentClaim>;
 }
-/**
- * Pending-mutation intent on the wire. Declared via `intent_begin`,
- * cleared on `intent_abandon` / commit / disconnect / TTL expiry.
- * Server stamps `declaredAt` and `expiresAt` (ms epoch). The SDK's
- * `IntentStream.others` exposes a richer `ActiveIntent` view (defined
- * below) that adds `heldBy` so callers know which participant owns it.
- */
-export interface IntentClaim {
-    readonly intentId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-    readonly path?: string;
-    readonly range?: TargetRange;
-    readonly action: string;
-    readonly field?: string;
-    readonly meta?: Record<string, unknown>;
-    readonly declaredAt: number;
-    readonly expiresAt: number;
-}
-/**
- * Transition type carried on every presence frame from the server.
- *   - `'enter'`  — first frame the receiver sees for this peer.
- *   - `'update'` — activity / intent change on an already-known peer.
- *   - `'leave'`  — peer departed (explicit disconnect or TTL expiry).
- */
-export type PresenceKind = 'enter' | 'update' | 'leave';
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
     readonly status: 'online' | 'away' | 'offline' | (string & {});
@@ -411,6 +380,15 @@ export interface IntentStream {
      * `subscribe(...)` for change notifications.
      */
     queueFor(target: PresenceTarget): readonly Intent[];
+    /**
+     * Re-rank the wait queue on a target — move the listed waiters to the front
+     * in the given order; unlisted waiters keep their relative FIFO order behind
+     * them. Pass the `Intent[]` from `queueFor(target)` in the order you want
+     * (each `Intent` carries its `heldBy` + `id`). Privileged: the server gates
+     * it (a participant lacking the `intent.reorder` capability is denied), so
+     * this is fire-and-forget — the new order arrives reactively via `queueFor`.
+     */
+    reorder(target: PresenceTarget, order: readonly Intent[]): void;
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -435,6 +413,23 @@ export interface IntentStream {
      * Returns an unsubscribe fn.
      */
     onRejected(listener: (rejection: IntentRejection) => void): () => void;
+    /**
+     * Observe LOSING an intent you held — distinct from `onRejected` (a claim the
+     * server refused). Fires on the server's `intent_lost` frame, carrying why:
+     * `'preempted'` (a privileged participant evicted you) or `'expired'` (your
+     * TTL lapsed). Lets a holder react — re-plan vs re-claim — instead of
+     * silently discovering the lease gone via presence.
+     *
+     * ```ts
+     * participant.intents.onLost((lost) => {
+     *   if (lost.reason === 'preempted') replanAgainst(lost.target);
+     *   else reclaim(lost.target);
+     * });
+     * ```
+     *
+     * Returns an unsubscribe fn.
+     */
+    onLost(listener: (lost: IntentLost) => void): () => void;
     /**
      * Async-iterable view of everyone else's open intents. Each
      * iteration yields the current snapshot on every mutation.
@@ -473,6 +468,31 @@ export interface IntentRejection {
     /** When the existing claim expires (ms since epoch). */
     readonly heldByExpiresAt: number;
 }
+/**
+ * You LOST an intent you were HOLDING — distinct from `IntentRejection` (a
+ * claim the server refused you). Delivered via `onLost`.
+ */
+export interface IntentLost {
+    /** The held claim's id that you just lost. */
+    readonly intentId: string;
+    /**
+     * How you lost it. `'preempted'`: a privileged participant (one holding the
+     * `intent.preempt` capability) evicted you and took the lease — its work now
+     * supersedes yours, so re-plan against the new holder rather than blindly
+     * re-claiming. `'expired'`: your TTL lapsed without finishing — re-claim if
+     * you still need it.
+     */
+    readonly reason: 'expired' | 'preempted';
+    /** The target you no longer hold. */
+    readonly target: {
+        readonly entityType: string;
+        readonly entityId: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly field?: string;
+        readonly meta?: Record<string, unknown>;
+    };
+}
 export interface IntentDeclaration {
     readonly target: EntityRef;
     /** Human-readable reason — "rewriting title" / "restyling chart". */

package/docs/api-keys.md

@@ -22,3 +22,47 @@ Use API keys from trusted runtimes:
 - webhooks
 
 Never ship a secret API key to a browser bundle.
+
+## Test mode and sandboxes
+
+Test and live keys are the same shape; the prefix names the environment:
+
+- `sk_test_…` — a key bound to a **sandbox**. Its reads and writes are isolated
+  to that sandbox and are invisible to live keys (and to other sandboxes).
+- `sk_live_…` — a key against your live data.
+
+Every org has a default **Test mode** sandbox, plus any number of additional
+sandboxes you create. **Data is isolated per sandbox; the schema is shared
+across the whole org.** A schema you push from a test key defines the same
+models your live keys see — only the rows differ. This mirrors how Stripe
+separates test and live data while keeping the API shape identical.
+
+## Scopes
+
+Keys carry scopes following the principle of least privilege — each key gets
+only what its job needs. A secret key with **no scopes** has full org authority
+(the default for a `sk_live_` backend key); a key with a non-empty scope set is
+restricted to exactly those grants:
+
+- `schema:push` — author the org schema (`ablo schema push`, `ablo dev`). A
+  high-risk, org-wide grant: because schema is shared, a push affects the live
+  table shape. A full-authority key has it implicitly; a *restricted* key (such
+  as a sandbox key) needs it granted explicitly.
+- `sandbox:<id>` — marks the key as belonging to a sandbox (its data isolation
+  comes from the sandbox binding, not this scope string).
+
+A key minted from the default **Test mode** sandbox carries `schema:push`, so
+`ablo dev` works out of the box. Keys from other sandboxes are **data-only** by
+default — enable "schema authoring" when minting if you want that key to push
+schema too. Hand data-only keys to embedded apps and CI agents; reserve
+schema-authoring keys for the developer running `ablo dev`.
+
+### `ablo dev`
+
+```sh
+ABLO_API_KEY=sk_test_… npx ablo dev
+```
+
+Pushes your `ablo/schema.ts` to the test sandbox, prints the one line you need
+in `.env.local`, and re-pushes on every save. It refuses `sk_live_` keys so a
+tight save loop can never churn production data.

package/docs/api.md

@@ -36,31 +36,23 @@ Each schema model becomes a typed model on the client:
 - `ablo.weatherReports.update(id, data, options?)` updates a row.
 - `ablo.weatherReports.delete(id, options?)` deletes a row.
 
-`load` and `retrieve` are not aliases. Use `load` when the row may not be in the
-local pool yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
-local read.
+`load` and `retrieve` are not aliases. Use `load` when the row may not be loaded
+yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
+synchronous read.
 
 | Method | Returns | Use when |
 |---|---|---|
 | `load({ where })` | `Promise<T[]>` | You need to hydrate rows from local store and server. |
-| `retrieve(id)` | `T \| undefined` | You already loaded the row and want a synchronous local read. |
-| `list(options?)` | `T[]` | You want a synchronous local list. |
-| `count(options?)` | `number` | You want a synchronous local count. |
+| `retrieve(id)` | `T \| undefined` | You already loaded the row and want a synchronous read. |
+| `list(options?)` | `T[]` | You want a synchronous list of loaded rows. |
+| `count(options?)` | `number` | You want a synchronous count of loaded rows. |
 | `create(data, options?)` | `Promise<T>` | You want to create through the schema model. |
 | `update(id, data, options?)` | `Promise<T>` | You want to update through the schema model. |
 | `delete(id, options?)` | `Promise<void>` | You want to delete through the schema model. |
 
-`list` and `count` read the local pool. They default to live rows and accept:
-
-```ts
-const readyReports = ablo.weatherReports.list({
-  where: { status: 'ready' },
-  filter: (report) => !report.location.startsWith('[archived]'),
-  orderBy: { updatedAt: 'desc' },
-  limit: 20,
-  scope: 'live', // 'live' | 'archived' | 'all'
-});
-```
+`load`, `create`, `update`, and `delete` are the main path — they go through the
+server. `retrieve` / `list` / `count` are **synchronous reads** off the rows a
+session has already loaded, so a cheap re-read needs no round-trip.
 
 ## Protected Writes
 
@@ -150,20 +142,17 @@ Default reads stay open; server/model reads can opt into `ifClaimed: 'wait'` or
 `ifClaimed: 'fail'` when they should not read through active work.
 
 ```ts
-// Read side — who is working on this target right now?
 const claim = ablo.weatherReports.claimState('report_stockholm');
 if (claim) {
-  claim.heldBy; // 'agent:report-writer'
-  claim.action; // 'editing'
+  claim.heldBy;
+  claim.action;
 }
 
-// Write side — claim for the duration of the callback.
 const updated = await ablo.weatherReports.claim(
   'report_stockholm',
   async (report) => ablo.weatherReports.update(report.id, { status: 'ready' }),
   { action: 'editing', ttl: '2m' },
 );
-updated.status; // 'ready'
 ```
 
 Writes go through the normal flat `ablo.<model>.update(id, data)`. While you hold