@abloatai/humans 0.52.0 → 0.53.0

package/dist/local/sync/OnDemandLoader.js

@@ -19,33 +19,31 @@
  * 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 { ModelScope } from '../InstanceCache.js';
 import { AbloValidationError } from '@abloatai/transaction/errors';
 import { postQuery } from '../query/client.js';
-function timestampMs(value) {
-    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;
-}
+import { normalizeWhere } from '@abloatai/transaction/resources/where';
+const LOCAL = { 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, model) {
-    const incoming = timestampMs(data.updatedAt);
-    const resident = timestampMs(model.updatedAt);
-    return incoming !== undefined && resident !== undefined && incoming <= resident;
+function snapshotPosition(raw, evidenceById, readFloorAtIssue) {
+    const id = raw && typeof raw === 'object' ? raw.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 {
     opts;
@@ -194,7 +192,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 !== null);
             if (idbModels.length > 0) {
                 this.opts.objectPool.addBatch(idbModels, ModelScope.live);
@@ -224,18 +222,22 @@ export class OnDemandLoader {
     async fetchFromNetwork(modelName, typename, clauses, options) {
         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 !== 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) {
             this.opts.objectPool.addBatch(networkModels, ModelScope.live);
@@ -303,7 +305,7 @@ export class OnDemandLoader {
                 continue;
             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 !== null);
             if (models.length > 0) {
                 this.opts.objectPool.addBatch(models, ModelScope.live);
@@ -352,7 +354,7 @@ export class OnDemandLoader {
     getModelDef(modelName) {
         return this.opts.schema.models?.[modelName];
     }
-    hydrateOne(raw, typename, opts) {
+    hydrateOne(raw, origin, typename, opts) {
         if (!raw || typeof raw !== 'object')
             return null;
         const obj = raw;
@@ -362,24 +364,26 @@ 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) {
-                const stamped = this.stampTypename(obj, typename);
-                // 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))
+                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;
-                // 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.
+                const stamped = this.stampTypename(obj, typename);
+                // 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;
@@ -440,6 +444,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,
             getAuthToken: this.authTokenProvider ?? undefined,
@@ -464,9 +471,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 };
     }
     /**
      * Hydrate nested expanded rows. Resolves each relation's target
@@ -475,8 +482,11 @@ export class OnDemandLoader {
      * `__typename` field gets mangled by `postgres.camel` (`__typename`
      * → `_Typename`), so the SDK can't trust whatever string lands.
      */
-    hydrateExpanded(parentModelName, rows, relationNames) {
+    hydrateExpanded(parentModelName, rows, relationNames, position) {
         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 = { kind: 'network', position: position > 0 ? position : undefined };
         for (const row of rows) {
             if (!row || typeof row !== 'object')
                 continue;
@@ -495,7 +505,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);
                 }
@@ -624,35 +634,10 @@ async function scanIdb(database, modelName, clauses) {
         return [];
     }
 }
-/**
- * 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) {
-    if (where == null)
-        return [];
-    if (Array.isArray(where)) {
-        // Tuple form — assumed to already use server-side column names.
-        return where;
-    }
-    if (typeof where === 'object') {
-        const obj = where;
-        return Object.entries(obj).map(([key, value]) => {
-            if (Array.isArray(value)) {
-                return [key, 'IN', value];
-            }
-            return [key, value];
-        });
-    }
-    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) {
     const out = {};

package/dist/local/sync/bootstrapApply.d.ts

@@ -15,6 +15,7 @@
  */
 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
  *  added, updated, removed, skipped, and healed, plus the elapsed time. */
@@ -38,10 +39,7 @@ export interface PoolContext {
     /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
     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[];
-    }, protectedIds?: ReadonlySet<string>): {
+    applyBootstrapDataToPool(bootstrapData: BootstrapSnapshot, protectedIds?: ReadonlySet<string>): {
         added: number;
         updated: number;
         removed: number;

package/dist/plugin.d.ts

@@ -77,6 +77,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;
 }
 /**
  * What each stage hands its handlers. Read off the delta pipeline these

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.52.0",
+    "@abloatai/transaction": "^0.53.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/local/Database.ts

@@ -34,6 +34,23 @@ import {
 /** Generic record type for model data */
 type ModelData = Record<string, unknown>;
 
+/**
+ * Carry each input delta's log position onto the change that answers it.
+ * `processDeltaBatch` builds its results index-aligned with its input, so the
+ * position is stamped once here rather than at every construction site.
+ */
+function stampSyncIds(
+  results: AppliedChange[],
+  deltas: readonly { syncId?: number }[],
+): AppliedChange[] {
+  for (let index = 0; index < results.length; index++) {
+    const change = results[index];
+    const syncId = deltas[index]?.syncId;
+    if (change && typeof syncId === 'number') change.syncId = syncId;
+  }
+  return results;
+}
+
 // Re-exported, not redeclared. `@abloatai/transaction`'s `types` module owns this
 // vocabulary and documents what each mode does; this package held a byte-identical
 // second copy while its own test fixtures already imported the canonical one.
@@ -1119,7 +1136,10 @@ export class Database {
           updatedAt: new Date(),
         };
       }
-      return { results: inMemResults, persistedSyncId: inMemPersistedSyncId };
+      return {
+        results: stampSyncIds(inMemResults, deltas),
+        persistedSyncId: inMemPersistedSyncId,
+      };
     }
 
     // Prepare results aligned with input order
@@ -1540,7 +1560,7 @@ export class Database {
       });
     }
 
-    return { results, persistedSyncId: highestPersistedSyncId };
+    return { results: stampSyncIds(results, deltas), persistedSyncId: highestPersistedSyncId };
   }
 
   /** Get raw data for hydration */

package/src/local/InstanceCache.ts

@@ -16,6 +16,7 @@ import { AbloValidationError } from '@abloatai/transaction/errors';
 import { ModelScope, PropertyType } from '@abloatai/transaction/types';
 import { ViewRegistry } from './views/ViewRegistry.js';
 import { QueryView, type QueryViewOptions } from './views/QueryView.js';
+import { RowWatermarks } from './rowWatermarks.js';
 
 /** Constructor type for Model subclasses - uses abstract to handle variance */
 type ModelConstructor<T extends Model> = abstract new (...args: never[]) => T;
@@ -124,6 +125,15 @@ export class InstanceCache {
   // ViewRegistry — tracks active QueryViews for incremental view maintenance
   readonly viewRegistry: ViewRegistry = new ViewRegistry();
 
+  /**
+   * The log position each pooled row is known to reflect. Every door a row
+   * enters through (delta, own ack, bootstrap, server read) advances it, and
+   * every snapshot that would overwrite a resident row is judged against it —
+   * see {@link RowWatermarks}. Keyed by instance so it lives and dies with the
+   * pooled model.
+   */
+  readonly watermarks = new RowWatermarks();
+
   // Subscription registry
   private subscriptions = new Map<string, Set<(model: Model) => void>>();
 

package/src/local/SyncClient.ts

@@ -34,7 +34,9 @@ import {
   type UnconfirmedWritesMetrics,
 } from './transactions/mutations/UnconfirmedWrites.js';
 import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.js';
+import type { CommitTransaction } from './transactions/mutations/commitLane.js';
 import type { Database } from './Database.js';
+import type { BootstrapData } from './sync/BootstrapFetcher.js';
 import type { MutationPersistencePort } from './mutationPersistence.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { LogPosition } from './logPosition.js';
@@ -73,30 +75,29 @@ export interface RehydrationStats {
 type EventHandler = () => void;
 
 /**
- * Reports whether an incoming snapshot record is strictly newer than the
- * model already in the pool. The comparison uses the server-stamped
- * `updatedAt` timestamp, since rows carry no numeric version and the delta
- * pipeline resolves order by arrival (last write wins). An undefined incoming
- * timestamp counts as not newer, so a known row is never clobbered; an
- * undefined existing timestamp means the pooled row is unversioned, so the
- * incoming record wins. The scoped hydrate-on-enter path uses this to drop
- * snapshot rows that a live delta has already advanced past.
+ * The slice of a bootstrap answer the pool applies: its rows, the models whose
+ * server query failed, and the log position the snapshot was taken at — the
+ * position every row in it reflects. `lastSyncId` is optional only for callers
+ * applying rows with no snapshot position to speak of; the fetcher always
+ * names one.
  */
-function rawRecordIsNewer(data: Record<string, unknown>, existing: Model): boolean {
-  const raw = data.updatedAt;
-  const inMs =
-    raw instanceof Date
-      ? raw.getTime()
-      : typeof raw === 'string'
-        ? (Number.isNaN(Date.parse(raw)) ? undefined : Date.parse(raw))
-        : typeof raw === 'number'
-          ? raw
-          : undefined;
-  const exMs = existing.updatedAt instanceof Date ? existing.updatedAt.getTime() : undefined;
-  if (inMs === undefined) return false;
-  if (exMs === undefined) return true;
-  return inMs > exMs;
-}
+export type BootstrapSnapshot = Pick<BootstrapData, 'models' | 'failedModels'> &
+  Partial<Pick<BootstrapData, 'lastSyncId'>>;
+
+/**
+ * What `transaction:completed` carries: a model mutation (one row, confirmed
+ * at `syncIdNeededForCompletion`) or an explicit commit (one row per operation,
+ * confirmed at `lastSyncId`). Each arm projects its own queue record.
+ */
+type CompletedTransaction =
+  | (Pick<QueuedMutation, 'id' | 'modelId' | 'syncIdNeededForCompletion'> & {
+      lastSyncId?: undefined;
+      operations?: undefined;
+    })
+  | (Pick<CommitTransaction, 'id' | 'lastSyncId' | 'operations'> & {
+      modelId?: undefined;
+      syncIdNeededForCompletion?: undefined;
+    });
 
 /**
  * Converts an untyped server `updatedAt` value — an ISO string, epoch number,
@@ -464,12 +465,18 @@ export class SyncClient extends EventEmitter {
       }
     );
 
-    // Clean up persisted awaiting transactions when they're finally confirmed
+    // Clean up persisted awaiting transactions when they're finally confirmed,
+    // and record the confirmed position on every row the transaction wrote.
+    // The acknowledgement is the earliest proof of where this client's own
+    // write landed in the log — earlier than its delta echo, which the pool
+    // suppresses on apply — so a snapshot read before the write cannot regress
+    // the row in the window between the two.
     this.mutationQueue.on(
       'transaction:completed',
-      (tx: { id: string; modelName: string; modelId: string }) => {
+      (tx: CompletedTransaction) => {
         // void is safe: the handler's body is fully try/catch'd.
         void this.removeAwaitingTransaction(tx.id);
+        this.noteOwnWritePositions(tx);
       }
     );
 
@@ -495,6 +502,23 @@ export class SyncClient extends EventEmitter {
     );
   }
 
+  /**
+   * Advance the pooled rows a completed transaction wrote to the log position
+   * its acknowledgement named. A model mutation names one row; an explicit
+   * commit names one per operation. Rows no longer pooled have nothing to
+   * advance — a fresh instance starts without evidence.
+   */
+  private noteOwnWritePositions(tx: CompletedTransaction): void {
+    const position = tx.lastSyncId ?? tx.syncIdNeededForCompletion;
+    if (position === undefined) return;
+    const rowIds =
+      tx.operations !== undefined ? tx.operations.map((op) => op.id) : [tx.modelId];
+    for (const rowId of rowIds) {
+      const row = this.objectPool.peek(rowId);
+      if (row) this.objectPool.watermarks.advance(row, position);
+    }
+  }
+
   /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
   private async persistAwaitingTransaction(event: {
     txId: string;
@@ -1952,7 +1976,13 @@ export class SyncClient extends EventEmitter {
     }
 
     for (const result of dbResults) {
-      const { modelName, modelId, action, transactionId } = result;
+      const { modelName, modelId, action, transactionId, syncId } = result;
+
+      // Every delta names the log position the row now reflects — recorded
+      // before echo detection, because an own echo is exactly a position the
+      // pooled row has reached even though its fields are not re-applied.
+      const resident = this.objectPool.peek(modelId);
+      if (resident) this.objectPool.watermarks.advance(resident, syncId);
 
       // Echo detection: if this delta carries a transaction id that matches
       // one already applied optimistically, the pool already reflects the
@@ -1990,7 +2020,10 @@ export class SyncClient extends EventEmitter {
             const model = this.objectPool.createFromData(data, undefined, {
               deferObservability: true,
             });
-            if (model) modelsToAdd.push(model);
+            if (model) {
+              this.objectPool.watermarks.advance(model, syncId);
+              modelsToAdd.push(model);
+            }
           }
           break;
         }
@@ -2058,17 +2091,18 @@ export class SyncClient extends EventEmitter {
    * Owns: model creation, batch upsert, ghost detection + removal.
    */
   applyBootstrapDataToPool(
-    bootstrapData: { models?: Record<string, unknown[]>; failedModels?: string[] },
+    bootstrapData: BootstrapSnapshot,
     protectedIds?: ReadonlySet<string>,
     options?: {
       /**
        * Scoped backfill for the hydrate-on-enter path: the snapshot covers only
        * the groups just entered, not the whole model type. Two behaviors change
-       * so the subset cannot corrupt the pool. First, the upsert is
-       * version-guarded ({@link InstanceCache.upsertIfNewer}) so a concurrent live
-       * delta is not clobbered back to the snapshot version. Second, ghost
-       * removal is skipped, because a subset snapshot must never evict rows of
-       * the same type that belong to other, unhydrated groups.
+       * so the subset cannot corrupt the pool. First, a row the pool already
+       * knows to reflect a position beyond the snapshot's `lastSyncId` is
+       * skipped, so a concurrent live delta is not clobbered back to the
+       * snapshot version. Second, ghost removal is skipped, because a subset
+       * snapshot must never evict rows of the same type that belong to other,
+       * unhydrated groups.
        */
       scoped?: boolean;
     },
@@ -2076,6 +2110,7 @@ export class SyncClient extends EventEmitter {
     if (!bootstrapData.models) {
       return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0 };
     }
+    const snapshotPosition = bootstrapData.lastSyncId;
 
     const allModels: Model[] = [];
     const serverIdsByType = new Map<string, Set<string>>();
@@ -2110,16 +2145,22 @@ export class SyncClient extends EventEmitter {
         // taken at a server watermark. If a concurrent live delta already
         // advanced this row past the snapshot, skip it. `createFromData`
         // mutates the pooled model in place to keep instances alive, so this
-        // version guard has to run before it; a guard at the upsert layer would
-        // be too late, because the row would already be clobbered.
+        // guard has to run before it; a guard at the upsert layer would be too
+        // late, because the row would already be clobbered.
         if (options?.scoped && recordId) {
-          const existing = this.objectPool.get(recordId);
-          if (existing && !rawRecordIsNewer(data, existing)) { skippedCount++; continue; }
+          const existing = this.objectPool.peek(recordId);
+          if (existing && this.objectPool.watermarks.isAheadOf(existing, snapshotPosition)) {
+            skippedCount++;
+            continue;
+          }
         }
 
         try {
           const model = this.objectPool.createFromData(data);
-          if (model) allModels.push(model);
+          if (model) {
+            this.objectPool.watermarks.advance(model, snapshotPosition);
+            allModels.push(model);
+          }
         } catch {
           skippedCount++;
         }

package/src/local/client/createInternalComponents.ts

@@ -121,6 +121,10 @@ export function createInternalComponents<S extends SchemaRecord>(
     baseUrl: bootstrapBaseUrl,
     getAuthToken: auth?.getAuthToken,
     runtime,
+    // The one canonical log position; the loader reads its floor when a query
+    // leaves so a late answer cannot overwrite a row the pool already knows to
+    // be further along.
+    position: syncClient.position,
   });
 
   // Drop the lazy-lane hydration ledger on reconnect. While connected, the

package/src/local/client/createModelProxy.ts

@@ -38,6 +38,7 @@ import {
   startClaimHeartbeatLoop,
 } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
 import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
+import { modelList, type ModelList } from '@abloatai/transaction/resources/httpResources';
 import { subTarget } from '@abloatai/transaction/coordination';
 // A named claim-meta crossing (see `claim-meta-crossings-are-enumerated` in
 // .dependency-cruiser.cjs): the reactive proxy's self-claim targets are
@@ -504,6 +505,18 @@ export function createModelProxy<T, C>(
   };
 
   const load = async (options?: ServerReadOptions<T>): Promise<T[]> => {
+    if (options?.cursor !== undefined) {
+      // The live client hydrates a working set into the local graph rather than
+      // handing back pages, so there is no cursor for this read to resume from.
+      // Accepting the option and ignoring it would return page one every time
+      // while the caller believed it was advancing.
+      throw new AbloValidationError(
+        '`cursor` resumes a page of the stateless read. This client keeps a ' +
+          'local graph and loads a working set instead of pages: narrow the ' +
+          '`where`, or construct the client with `transport: \'http\'` to page.',
+        { code: 'invalid_options', param: 'cursor' },
+      );
+    }
     const rows = await hydration.fetch<T>(schemaKey, options);
     return rows.map((row) => modelAsRow<T>(row));
   };
@@ -1146,10 +1159,18 @@ export function createModelProxy<T, C>(
 
   const list = guard(async (
     options?: ServerReadOptions<T>,
-  ): Promise<CapturedRow<T>[]> => {
+  ): Promise<ModelList<CapturedRow<T>>> => {
     const registry = readSetContext?.getStore();
     const rows = await load(options);
-    if (!registry) return rows as CapturedRow<T>[];
+    // This transport loads a working set rather than pages, so there is no
+    // cursor to hand back. `limit` can still cut the set short, and a full
+    // count is exactly the case where the caller cannot tell: report it rather
+    // than claim completeness this read cannot vouch for.
+    const page = modelList<CapturedRow<T>>(rows as CapturedRow<T>[], {
+      hasMore: options?.limit !== undefined && rows.length >= options.limit,
+      nextCursor: null,
+    });
+    if (!registry) return page;
     for (const row of rows) {
       const stamp = hydration.getReadEvidence?.(row as object);
       if (stamp === undefined) {
@@ -1174,7 +1195,7 @@ export function createModelProxy<T, C>(
         stamp,
       );
     }
-    return rows as CapturedRow<T>[];
+    return page;
   });
 
   const operations: ModelOperations<T, C> = {