@abloatai/humans 0.51.0 → 0.53.0

package/src/local/rowWatermarks.ts

@@ -0,0 +1,54 @@
+/**
+ * The log position each pooled row is known to reflect — the client-side
+ * companion of the server's per-row watermark (`ModelListEvidence.stamp`).
+ *
+ * A row's copy in the pool moves through four doors, and every one of them
+ * names the log position it delivers: the ordered delta stream (the delta's
+ * id), the acknowledgement of this client's own commit (`lastSyncId`), a
+ * bootstrap snapshot (its `lastSyncId`), and a server read (the row's evidence
+ * stamp). Recording that position per row is what lets a later snapshot be
+ * judged. A snapshot taken at position P cannot carry anything the log did not
+ * hold at P, so when the pooled copy already reflects a position beyond P the
+ * snapshot is stale for that row and is left unapplied. Deltas repair every
+ * peer change a skipped snapshot would have carried; nothing repairs a
+ * snapshot that regresses this client's own confirmed write, because own
+ * echoes are suppressed on apply — which is why the rule errs toward keeping
+ * the resident copy.
+ *
+ * The row's `updatedAt` is not consulted. It is an application field the
+ * server never stamps and the client fabricates when a row arrives without one,
+ * so it orders nothing; the log does.
+ *
+ * Positions are `sync_deltas` ids, the same space as {@link LogPosition}. Zero
+ * and `undefined` mean "no evidence" and never advance a row.
+ */
+
+export class RowWatermarks {
+  readonly #positions = new WeakMap<object, number>();
+
+  /** Record that `row`'s pooled copy reflects the log at least through `position`. */
+  advance(row: object, position: number | undefined): void {
+    if (position === undefined || !(position > 0)) return;
+    const known = this.#positions.get(row);
+    if (known === undefined || position > known) this.#positions.set(row, position);
+  }
+
+  /** The highest log position `row` is known to reflect, if the client has any evidence. */
+  of(row: object): number | undefined {
+    return this.#positions.get(row);
+  }
+
+  /**
+   * Whether the pooled copy of `row` is known to be ahead of a snapshot that
+   * reflects the log through `snapshotPosition`. `snapshotPosition` is a lower
+   * bound: the position the snapshot provably includes (a row's evidence stamp,
+   * a bootstrap's `lastSyncId`, or the client's own read floor at the moment
+   * the read was issued — the server had at least that much when it answered).
+   * A snapshot with no known position is never judged stale.
+   */
+  isAheadOf(row: object, snapshotPosition: number | undefined): boolean {
+    if (snapshotPosition === undefined) return false;
+    const known = this.#positions.get(row);
+    return known !== undefined && known > snapshotPosition;
+  }
+}

package/src/local/sync/OnDemandLoader.ts

@@ -19,6 +19,13 @@
  * loaded models) or the live delta stream (pushed over the WebSocket). It only
  * fills the gap for lazily loaded models read by id or filter after the engine
  * is ready.
+ *
+ * A network answer is a snapshot, unordered against that stream: it may leave
+ * before a write and return after it. Each returned row therefore meets the
+ * pool by log position — the position the row provably reflects against the
+ * position the pooled copy is already known to hold ({@link RowWatermarks}) —
+ * never by wall-clock `updatedAt`, which the server does not stamp and which
+ * orders nothing.
  */
 
 import type { InstanceCache } from '../InstanceCache.js';
@@ -30,12 +37,18 @@ import type { ModelRegistry, RegisteredModelClass } from '../ModelRegistry.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
 import { postQuery } from '../query/client.js';
 import type { RecoveryClass } from '@abloatai/transaction/errorCodes';
-import type { LoadWhere, Query, WhereClause, WhereOp, WherePrimitive } from '../query/types.js';
+import type { LoadWhere, Query, WhereClause, WhereOp } from '../query/types.js';
+import { normalizeWhere } from '@abloatai/transaction/resources/where';
 import type { Schema } from '@abloatai/transaction/schema/schema';
+import type { LogPositionPort } from '../logPosition.js';
 
 export interface OnDemandLoaderOptions {
   readonly objectPool: InstanceCache;
-  readonly database: Database;
+  /**
+   * The local tier reads and writes rows through a model's store, so store
+   * lookup is the whole of the loader's dependency on the database.
+   */
+  readonly database: Pick<Database, 'getStore'>;
   readonly registry: ModelRegistry;
   readonly schema: Schema;
   /** Bootstrap base URL (without trailing slash), e.g. `https://api.example.com/api`. */
@@ -49,6 +62,13 @@ export interface OnDemandLoaderOptions {
   readonly getCapabilityToken?: () => string | null;
   /** The owning client's runtime. Defaults to the module-global bridge. */
   readonly runtime?: RuntimeContext;
+  /**
+   * The client's position in the log. Read at the moment a query is issued:
+   * the server holds at least that much when it answers, so it is the position
+   * every returned row provably reflects — the bound a resident row is judged
+   * against before a snapshot may overwrite it (see {@link RowWatermarks}).
+   */
+  readonly position: Pick<LogPositionPort, 'readFloor'>;
 }
 
 export interface FetchOptions<T> {
@@ -96,28 +116,39 @@ interface SchemaModelDef {
   >;
 }
 
-function timestampMs(value: unknown): number | undefined {
-  if (value instanceof Date) {
-    const timestamp = value.getTime();
-    return Number.isFinite(timestamp) ? timestamp : undefined;
-  }
-  if (typeof value === 'number' && Number.isFinite(value)) return value;
-  if (typeof value !== 'string') return undefined;
-  const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? undefined : parsed;
-}
+/**
+ * Where a row being hydrated came from, and what that says about how it may
+ * meet a row already in the pool.
+ *
+ * A network snapshot is unordered against the delta stream: it may have been
+ * issued before a write and answered after it. It carries the position it
+ * provably reflects, and a resident row known to be beyond that position is
+ * left as it is. A local read (IndexedDB) exists to fill pool misses; the pool
+ * is never behind local storage for a row it already holds, so a resident row
+ * is kept untouched.
+ */
+type HydrationOrigin =
+  | { readonly kind: 'network'; readonly position: number | undefined }
+  | { readonly kind: 'local' };
+
+const LOCAL: HydrationOrigin = { kind: 'local' };
 
 /**
- * A query response is a snapshot, not an ordered delta. It may have started
- * before a local optimistic write and completed after it. Only treat the row
- * as authoritative over an existing model when its server timestamp is newer;
- * missing timestamps retain the legacy merge behavior for custom sources that
- * do not expose `updatedAt`.
+ * The position a returned row provably reflects: the greater of its own
+ * evidence stamp (the row's watermark, which lags for a row that has not
+ * changed in a while) and the client's read floor when the query was issued
+ * (which the server had already passed when it answered). Both are lower
+ * bounds; the tighter one judges. `undefined` when neither says anything.
  */
-function snapshotDoesNotAdvanceModel(data: Record<string, unknown>, model: Model): boolean {
-  const incoming = timestampMs(data.updatedAt);
-  const resident = timestampMs(model.updatedAt);
-  return incoming !== undefined && resident !== undefined && incoming <= resident;
+function snapshotPosition(
+  raw: unknown,
+  evidenceById: ReadonlyMap<string, number>,
+  readFloorAtIssue: number,
+): number | undefined {
+  const id = raw && typeof raw === 'object' ? (raw as { id?: unknown }).id : undefined;
+  const stamp = typeof id === 'string' ? (evidenceById.get(id) ?? 0) : 0;
+  const position = Math.max(stamp, readFloorAtIssue);
+  return position > 0 ? position : undefined;
 }
 
 export class OnDemandLoader {
@@ -308,7 +339,7 @@ export class OnDemandLoader {
     if (local.length === 0) {
       const fromIdb = await scanIdb(this.opts.database, typename, clauses);
       const idbModels = fromIdb
-        .map((raw) => this.hydrateOne(raw, typename))
+        .map((raw) => this.hydrateOne(raw, LOCAL, typename))
         .filter((m): m is Model => m !== null);
       if (idbModels.length > 0) {
         this.opts.objectPool.addBatch(idbModels, ModelScope.live);
@@ -345,18 +376,29 @@ export class OnDemandLoader {
   ): Promise<Model[]> {
     const network = await this.queryNetwork(modelName, clauses, options);
     const networkRows = network.rows;
+    const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
     const networkModels = networkRows
       // Strict: a row the server returned whose type name this client never
       // registered is a genuine schema collision (the pushed schema differs
       // from the local one). Throw here, naming the cause, rather than silently
       // dropping the row and failing downstream as `entity_not_found`.
-      .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
+      .map((raw) =>
+        this.hydrateOne(
+          raw,
+          { kind: 'network', position: snapshotPosition(raw, evidenceById, network.position) },
+          typename,
+          { strict: true },
+        ),
+      )
       .filter((m): m is Model => m !== null);
 
-    const evidenceById = new Map(network.evidence.map((entry) => [entry.id, entry.stamp]));
     for (const model of networkModels) {
       const stamp = evidenceById.get(model.id);
-      if (stamp !== undefined) this.readEvidence.set(model, stamp);
+      if (stamp === undefined) continue;
+      // The read's evidence, kept for the premise a guarded write may cite;
+      // and the position the pooled row now reflects, for freshness.
+      this.readEvidence.set(model, stamp);
+      this.opts.objectPool.watermarks.advance(model, stamp);
     }
 
     if (networkModels.length > 0) {
@@ -437,7 +479,7 @@ export class OnDemandLoader {
 
       const rows = await this.readChildrenLocal(targetTypename, foreignKey, missing);
       const models = rows
-        .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), targetTypename))
+        .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), LOCAL, targetTypename))
         .filter((m): m is Model => m !== null);
       if (models.length > 0) {
         this.opts.objectPool.addBatch(models, ModelScope.live);
@@ -492,6 +534,7 @@ export class OnDemandLoader {
 
   private hydrateOne(
     raw: unknown,
+    origin: HydrationOrigin,
     typename?: string,
     opts?: { strict?: boolean },
   ): Model | null {
@@ -502,26 +545,27 @@ export class OnDemandLoader {
       // Keep the existing instance alive when a query refreshes it. A query
       // can carry fresher server state after a missed delta, but unlike the
       // ordered delta stream it can also finish late with an older snapshot;
-      // the reconciliation below distinguishes those cases before applying.
+      // the origin decides which before anything is applied.
       const existing = this.opts.objectPool.get(obj.id);
       if (existing) {
+        if (origin.kind === 'local') return existing;
+        // A request that began before an optimistic write can return afterward
+        // with the old row; applying it would visibly snap the live model
+        // back, and the matching authoritative delta cannot repair it because
+        // own echoes are suppressed. The pool knows the position the row
+        // already reflects; a snapshot from before it is left unapplied.
+        if (this.opts.objectPool.watermarks.isAheadOf(existing, origin.position)) return existing;
+
         const stamped = this.stampTypename(obj, typename) as Record<string, unknown>;
-        // Network queries are unordered snapshots. A request that began before
-        // an optimistic resize can return afterward with the old row; applying
-        // it here would visibly snap the live model back, and the matching
-        // authoritative delta cannot repair it because own echoes are
-        // intentionally suppressed. Keep a newer resident row intact.
-        if (snapshotDoesNotAdvanceModel(stamped, existing)) return existing;
-
-        // If the source has no comparable timestamp, retain pending local
-        // fields while accepting unrelated server fields. This is the same
-        // local-first merge contract used by SyncClient's delta resolver.
+        // Retain pending local fields while accepting the server's others —
+        // the same local-first merge contract SyncClient's delta resolver uses.
         const localChanges = existing.getChanges();
         existing.updateFromData(
           Object.keys(localChanges).length > 0
             ? { ...stamped, ...localChanges, updatedAt: existing.updatedAt }
             : stamped,
         );
+        this.opts.objectPool.watermarks.advance(existing, origin.position);
         return existing;
       }
       return null;
@@ -556,7 +600,7 @@ export class OnDemandLoader {
     // that disagrees with the schema's: these rows were returned FOR this
     // model's query, so the schema typename is correct by construction — and
     // without stripping it, the spread would put the row's variant (a server
-    // echoing the schema KEY `tasks` instead of the typename `Task`) back on
+    // echoing the schema KEY `items` instead of the typename `Item`) back on
     // top of the stamp, sending hydration to the strict unknown-model error.
     const { _Typename: _dropMangled, __typename: _dropRowVariant, ...rest } = obj as Record<
       string,
@@ -574,6 +618,8 @@ export class OnDemandLoader {
   ): Promise<{
     rows: unknown[];
     evidence: readonly { id: string; stamp: number }[];
+    /** The client's read floor when the query was issued — what every returned row provably reflects. */
+    position: number;
   }> {
     const typename = this.resolveTypename(modelName);
     const orderEntries = options?.orderBy ? Object.entries(options.orderBy) : [];
@@ -592,6 +638,9 @@ export class OnDemandLoader {
         ? { related: options.expand }
         : {}),
     };
+    // Read before the request leaves: the server holds at least this much of
+    // the log when it answers, so it is the position the response reflects.
+    const position = this.opts.position.readFloor;
     const result = await postQuery(
       {
         baseUrl: this.opts.baseUrl,
@@ -620,9 +669,9 @@ export class OnDemandLoader {
     // own typed pool, then leave the nested arrays in place on the
     // primary row.
     if (options?.expand && options.expand.length > 0) {
-      this.hydrateExpanded(modelName, normalized, options.expand);
+      this.hydrateExpanded(modelName, normalized, options.expand, position);
     }
-    return { rows: normalized, evidence };
+    return { rows: normalized, evidence, position };
   }
 
   /**
@@ -636,8 +685,12 @@ export class OnDemandLoader {
     parentModelName: string,
     rows: unknown[],
     relationNames: readonly string[],
+    position: number,
   ): void {
     const parentDef = this.getModelDef(parentModelName);
+    // Nested rows carry no evidence of their own; the read floor at issue
+    // time is what they provably reflect. A floor of zero says nothing.
+    const origin: HydrationOrigin = { kind: 'network', position: position > 0 ? position : undefined };
 
     for (const row of rows) {
       if (!row || typeof row !== 'object') continue;
@@ -655,7 +708,7 @@ export class OnDemandLoader {
         for (const item of items) {
           const stamped = this.stampTypename(item, targetTypename);
           stampedItems.push(stamped);
-          const m = this.hydrateOne(stamped);
+          const m = this.hydrateOne(stamped, origin);
           if (m) models.push(m);
         }
         if (models.length > 0) {
@@ -756,7 +809,7 @@ function scanPool(
 }
 
 async function scanIdb(
-  database: Database,
+  database: Pick<Database, 'getStore'>,
   modelName: string,
   clauses: readonly WhereClause[],
 ): Promise<unknown[]> {
@@ -805,34 +858,10 @@ async function scanIdb(
   }
 }
 
-/**
- * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`
- * tuple form used throughout `runFetch`. Tuple inputs pass through; object
- * inputs become one `['col', '=', val]` or `['col', 'IN', vals]` per key.
- *
- * Detection: an array whose first element is itself an array is treated
- * as tuple form. Object form is the fallback.
- *
- * Exported so callers can pre-normalize (e.g., for tests, or to inspect
- * the canonical clauses before passing them to `load`/`subscribe`).
- */
-export function normalizeWhere(where: unknown): readonly WhereClause[] {
-  if (where == null) return [];
-  if (Array.isArray(where)) {
-    // Tuple form — assumed to already use server-side column names.
-    return where as readonly WhereClause[];
-  }
-  if (typeof where === 'object') {
-    const obj = where as Record<string, unknown>;
-    return Object.entries(obj).map(([key, value]) => {
-      if (Array.isArray(value)) {
-        return [key, 'IN', value as readonly WherePrimitive[]] as WhereClause;
-      }
-      return [key, value as WherePrimitive] as WhereClause;
-    });
-  }
-  return [];
-}
+// `normalizeWhere` lives with the grammar it produces, so both transports read
+// the same one; re-exported here for callers that pre-normalize (tests, or
+// inspecting the canonical clauses before `load`/`subscribe`).
+export { normalizeWhere };
 
 /** Equality-only subset of clauses, keyed by column. Used by IDB fast paths. */
 function extractEqClauses(clauses: readonly WhereClause[]): Record<string, unknown> {

package/src/local/sync/bootstrapApply.ts

@@ -17,6 +17,7 @@
 import { globalRuntime } from '../context.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
 import type { BootstrapResult } from '../Database.js';
+import type { BootstrapSnapshot } from '../SyncClient.js';
 import type { SyncDelta } from './SyncWebSocket.js';
 
 /** Counts describing what applying a bootstrap changed in the pool: entities
@@ -43,7 +44,7 @@ export interface PoolContext {
   applyDeltaBatchToPool(results: NonNullable<BootstrapResult['deltaResults']>): void;
   /** Writes bootstrap data into the pool: creates models, heals partial rows, upserts, and removes stale local copies the server no longer reports. */
   applyBootstrapDataToPool(
-    bootstrapData: { models?: Record<string, unknown[]>; failedModels?: string[] },
+    bootstrapData: BootstrapSnapshot,
     protectedIds?: ReadonlySet<string>,
   ): { added: number; updated: number; removed: number; skipped: number; healed: number };
   /** Pool size — for the completion log line. */

package/src/local/sync/deltaPipeline.ts

@@ -396,7 +396,7 @@ async function drainPendingDeltas(ctx: DeltaPipelineContext): Promise<void> {
       // A sustained stream can refill the detached queue before every
       // persistence promise settles. Promise-only looping then forms an
       // unbounded microtask chain that starves WebSocket reads, timers and
-      // replication keepalives. Give the host one macrotask turn between
+      // replication keepalives. Give the host one macroitem turn between
       // owned batches; Node has setImmediate, browsers fall back to a timer.
       await yieldToHost();
     }

package/src/local/sync/initialize.ts

@@ -92,7 +92,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
       // Bootstrap from server if needed.
       //
       // `bootstrapMode: 'none'` participants (headless workers and
-      // task runners) skip baseline replication — they read via
+      // item runners) skip baseline replication — they read via
       // `model.get()` round-trips and rely on covering deltas
       // from filtered subscriptions to populate the pool lazily. The
       // WS is already open by `setupWebSocketSync` above, so live
@@ -110,7 +110,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
         // initiates the upgrade, but it does NOT await the 'connected'
         // event — it returns synchronously after wiring listeners.
         // For bootstrapMode='none' consumers (headless workers and
-        // task runners), this branch is the entire body of initialize()
+        // item runners), this branch is the entire body of initialize()
         // after the WS is set up, so `ready()` would otherwise resolve
         // while the WS is still in 'connecting' state. The very next
         // `commits.create` then throws "SyncWebSocket not connected".

package/src/local/transactions/mutations/MutationQueue.ts

@@ -645,7 +645,7 @@ export class MutationQueue extends EventEmitter {
   /**
    * Relates stale notifications back to write targets without assuming the
    * server's canonical model name uses the same spelling as the public schema
-   * key (`Task` versus `tasks`). Exact `(model,id)` wins; a globally unique id
+   * key (`Item` versus `items`). Exact `(model,id)` wins; a globally unique id
    * is the compatibility fallback. An ambiguous same-id cross-model mismatch
    * is deliberately left unclassified, so it cannot falsely settle a queued
    * write. A notification with no write-target id (or an explicit group) is a

package/src/local/transactions/persistedTransaction.ts

@@ -0,0 +1,112 @@
+import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
+
+type ModelData = Record<string, unknown>;
+
+/** One mutation retained in the durable local transaction journal. */
+interface PersistedMutation {
+  type: 'create' | 'update' | 'delete' | 'archive';
+  modelData: ModelData;
+  modelName: string;
+  timestamp: string;
+  writeOptions?: {
+    readAt?: number | null;
+    onStale?: OnStaleMode | null;
+  };
+}
+
+/**
+ * Persisted transaction for offline/retry support.
+ *
+ * The index signature is part of the contract: this targets the generic
+ * record-shaped storage layer (`InMemoryObjectStore.put` and its IndexedDB
+ * equivalent), both of which take `Record<string, unknown>`.
+ */
+export interface PersistedTransaction {
+  id: string;
+  type?: string;
+  timestamp?: number;
+  createdAt?: number;
+  mutations?: PersistedMutation[];
+  // Awaiting-delta transactions survive a tab close. Reconnect and delta
+  // catch-up confirm them during the next session.
+  awaitingDelta?: {
+    syncIdNeeded: number;
+    modelName: string;
+    modelId: string;
+    operationType: string;
+  };
+  [key: string]: unknown;
+}
+
+/** Compare the stable request identity while ignoring local seal timing. */
+export function isSameOutboxRecord(
+  existing: PersistedTransaction,
+  candidate: PersistedTransaction,
+): boolean {
+  if (
+    existing.type === 'http_commit_envelope' &&
+    candidate.type === 'http_commit_envelope'
+  ) {
+    const identity = (record: PersistedTransaction): unknown => ({
+      id: record.id,
+      type: record.type,
+      storageVersion: record.storageVersion,
+      idempotencyKey: record.idempotencyKey,
+      // Pre-versioning HTTP outbox rows are v1. Normalizing them preserves
+      // idempotency when the same request is resealed after an upgrade.
+      protocolVersion: record.protocolVersion ?? 1,
+      request: record.request,
+      scopeNamespace: record.scopeNamespace,
+    });
+    if (
+      existing.correlationId !== undefined &&
+      candidate.correlationId !== undefined &&
+      existing.correlationId !== candidate.correlationId
+    ) {
+      return false;
+    }
+    return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
+  }
+
+  if (
+    existing.type === 'commit_envelope' &&
+    candidate.type === 'commit_envelope'
+  ) {
+    const identity = (record: PersistedTransaction): unknown => ({
+      id: record.id,
+      type: record.type,
+      storageVersion: record.storageVersion,
+      origin: record.origin,
+      idempotencyKey: record.idempotencyKey,
+      operations: record.operations,
+      sourceMutationIds: record.sourceMutationIds,
+      commitOptions: record.commitOptions,
+      scope: record.scope,
+    });
+    if (
+      existing.correlationId !== undefined &&
+      candidate.correlationId !== undefined &&
+      existing.correlationId !== candidate.correlationId
+    ) {
+      return false;
+    }
+    return JSON.stringify(identity(existing)) === JSON.stringify(identity(candidate));
+  }
+
+  return JSON.stringify(existing) === JSON.stringify(candidate);
+}
+
+/** An accepted envelope may replace the otherwise-identical pending envelope. */
+export function isAcceptedOutboxPromotion(
+  existing: PersistedTransaction | undefined,
+  candidate: PersistedTransaction,
+): boolean {
+  return (
+    existing !== undefined &&
+    (existing.type === 'commit_envelope' ||
+      existing.type === 'http_commit_envelope') &&
+    existing.type === candidate.type &&
+    existing.acceptedAt === undefined &&
+    candidate.acceptedAt !== undefined
+  );
+}

package/src/local/utils/mobxSetup.ts

@@ -77,7 +77,7 @@ export function M1<T extends M1Target>(
   };
 
   // Skip if target has its own observability setup
-  // This allows models like Task to handle their own MobX setup
+  // This allows models like Item to handle their own MobX setup
   if (target.setupObservability || target._hasCustomObservability) {
     getContext().modelDebugLogger?.logDebug(`${target.constructor.name} has custom observability, skipping M1`);
     return;

package/src/plugin.ts

@@ -94,6 +94,13 @@ export interface AppliedChange {
    * no client transaction behind them.
    */
   transactionId?: string;
+  /**
+   * The log position of the delta this change answers — its `sync_deltas` id.
+   * The apply stage records it per row so a later snapshot can be judged
+   * against what the row already reflects. Absent when the source carried no
+   * position.
+   */
+  syncId?: number;
 }
 
 /**

package/src/react/AbloProvider.tsx

@@ -675,10 +675,10 @@ export function usePeers(scope?: ParticipantScope): readonly Peer[] {
 /**
  * Returns the raw `SyncEngine` proxy. Typically you want the typed
  * hooks (`useQuery`, `useOne`, `useMutate`) — this is for rare cases
- * where you need direct access (e.g., `sync.tasks.onChange(cb)`).
+ * where you need direct access (e.g., `sync.items.onChange(cb)`).
  *
  * The generic parameter narrows the return type to your schema's
- * model record so call sites get typed `sync.tasks.findMany()` /
+ * model record so call sites get typed `sync.items.findMany()` /
  * `sync.sections.create(...)` without a cast at the call site:
  *
  * ```ts

package/src/react/context.ts

@@ -19,7 +19,7 @@ export interface SyncReactContext {
   organizationId: string;
   /**
    * An optional schema. When provided, hooks that take a model by name (such as
-   * `useQuery('tasks')`) read that model's metadata from this schema, so
+   * `useQuery('items')`) read that model's metadata from this schema, so
    * callers don't pass a schema at every call site. When omitted, those hooks
    * require the schema as an argument instead.
    *
@@ -60,7 +60,7 @@ export interface SyncProviderProps {
   organizationId: string;
   /**
    * An optional schema. Provide it to enable hooks that take a model by name
-   * (such as `useQuery('tasks')`); the model types also narrow through your
+   * (such as `useQuery('items')`); the model types also narrow through your
    * `Register` augmentation. Omit it to pass the schema to those hooks directly
    * instead.
    */

package/src/react/useAblo.ts

@@ -138,13 +138,13 @@ function snapshotValue<T>(value: T): T {
  * // With the Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const doc = await ablo.documents.get({ id }); // async server read
+ * const doc = await ablo.records.get({ id }); // async server read
  *
  * // Reactive selector (a synchronous local snapshot). The selector's reads
  * // are typed as snapshot rows — data fields + computeds, no relation
  * // accessors — matching what the hook actually returns:
- * const doc = useAblo((ablo) => ablo.documents.local.get(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
+ * const doc = useAblo((ablo) => ablo.records.local.get(id)) ?? serverDoc;
+ * const active = useAblo((ablo) => ablo.records.claim.state({ id }));
  *
  * // Without the augmentation, pass the schema as a type argument:
  * const ablo = useAblo<(typeof schema)['models']>();