@abloatai/humans 0.51.0 → 0.53.0

package/dist/client.d.ts

@@ -108,10 +108,10 @@ export type AbloClient<S extends SchemaRecord> = {
      * server verifies it. The browser must never see the `sk_` key, only the
      * per-user session token.
      *
-     * Pass `{ user: { id }, can: { tasks: ['read', 'update'] } }` for an end-user
+     * Pass `{ user: { id }, can: { items: ['read', 'update'] } }` for an end-user
      * session. It mints an `ek_` and attributes writes to a user (recorded as
      * `actor_kind` on the delta row). Pass `{ agent: { id }, can: {
-     * tasks: ['update'] } }` for a scoped agent session, which mints an `rk_`.
+     * items: ['update'] } }` for a scoped agent session, which mints an `rk_`.
      * Both kinds require `can`, typed against your schema's model names. This
      * always authenticates with the original `sk_`, never the client's exchanged
      * sync credential.
@@ -126,10 +126,10 @@ export type AbloClient<S extends SchemaRecord> = {
      * ```ts
      * const agent = await ablo.agents.create({
      *   name: 'researcher',                  // readable label (optional)
-     *   can: { documents: ['read', 'update'] },
+     *   can: { records: ['read', 'update'] },
      *   // id omitted → a fresh uuid: a distinct, independent participant
      * });
-     * await agent.documents.update({ id, data, claim });
+     * await agent.records.update({ id, data, claim });
      * await agent.dispose(); // when the agent is done
      * ```
      *

package/dist/local/Database.d.ts

@@ -14,43 +14,10 @@ import type { AppliedChange } from '../plugin.js';
 import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 import type { SyncDeltaAction } from '@abloatai/transaction/wire/delta';
-import type { OnStaleMode } from '@abloatai/transaction/coordination/schema';
 import type { BootstrapType } from '@abloatai/transaction/types';
+import { type PersistedTransaction } from './transactions/persistedTransaction.js';
 /** Generic record type for model data */
 type ModelData = Record<string, unknown>;
-/** Persisted mutation in a transaction */
-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.
- *
- *  Index signature is part of the contract: this interface targets
- *  the generic record-shaped storage layer (`InMemoryObjectStore.put`
- *  + the IDB ObjectStore equivalent), both of which take
- *  `Record<string, unknown>`. Every declared field below already
- *  satisfies `unknown`; the index signature just makes the
- *  interface assignable to the storage parameter without a cast. */
-interface PersistedTransaction {
-    id: string;
-    type?: string;
-    timestamp?: number;
-    createdAt?: number;
-    mutations?: PersistedMutation[];
-    awaitingDelta?: {
-        syncIdNeeded: number;
-        modelName: string;
-        modelId: string;
-        operationType: string;
-    };
-    [key: string]: unknown;
-}
 export type { BootstrapType };
 export interface BootstrapRequirements {
     type: BootstrapType;

package/dist/local/Database.js

@@ -15,62 +15,20 @@ import { persistenceDatabaseNamesForDeletion, purgeIndexedDbPersistence, } from
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 import { logPositionSchema } from './logPosition.js';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
+import { isAcceptedOutboxPromotion, isSameOutboxRecord, } from './transactions/persistedTransaction.js';
 /**
- * Request identity excludes local timing metadata for re-entrant seals: a
- * retry rebuilds its envelope with a fresh `sequence`/seal clock, so comparing
- * those volatile fields would reject every legitimate same-request re-seal as
- * an idempotency conflict. Only the fields that define the wire request count.
+ * 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 isSameOutboxRecord(existing, candidate) {
-    if (existing.type === 'http_commit_envelope' &&
-        candidate.type === 'http_commit_envelope') {
-        const identity = (record) => ({
-            id: record.id,
-            type: record.type,
-            storageVersion: record.storageVersion,
-            idempotencyKey: record.idempotencyKey,
-            // HTTP outbox rows written before protocol versioning are v1. Normalize
-            // them so a same-request re-seal remains idempotent 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) => ({
-            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));
+function stampSyncIds(results, deltas) {
+    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 JSON.stringify(existing) === JSON.stringify(candidate);
-}
-function isAcceptedOutboxPromotion(existing, candidate) {
-    return (existing !== undefined &&
-        (existing.type === 'commit_envelope' ||
-            existing.type === 'http_commit_envelope') &&
-        existing.type === candidate.type &&
-        existing.acceptedAt === undefined &&
-        candidate.acceptedAt !== undefined);
+    return results;
 }
 export class Database {
     // Core database components
@@ -887,7 +845,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
         const results = new Array(deltas.length);
@@ -1242,7 +1203,7 @@ export class Database {
                 gap: highestSyncId - highestPersistedSyncId,
             });
         }
-        return { results, persistedSyncId: highestPersistedSyncId };
+        return { results: stampSyncIds(results, deltas), persistedSyncId: highestPersistedSyncId };
     }
     /** Get raw data for hydration */
     async hydrateModels(modelName) {

package/dist/local/InstanceCache.d.ts

@@ -12,6 +12,7 @@ import type { RuntimeContext } from './RuntimeContext.js';
 import { ModelScope } 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;
 export { ModelScope };
@@ -51,6 +52,14 @@ export declare class InstanceCache {
     private gcTimer?;
     readonly registry: ModelRegistry;
     readonly viewRegistry: 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: RowWatermarks;
     private subscriptions;
     /**
      * Subscribe to updates for a specific model type.

package/dist/local/InstanceCache.js

@@ -14,6 +14,7 @@ import { AbloValidationError } from '@abloatai/transaction/errors';
 import { ModelScope, PropertyType } from '@abloatai/transaction/types';
 import { ViewRegistry } from './views/ViewRegistry.js';
 import { QueryView } from './views/QueryView.js';
+import { RowWatermarks } from './rowWatermarks.js';
 // Re-exported so `import { ModelScope } from './InstanceCache.js'` resolves
 export { ModelScope };
 /**
@@ -80,6 +81,14 @@ export class InstanceCache {
     registry;
     // ViewRegistry — tracks active QueryViews for incremental view maintenance
     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.
+     */
+    watermarks = new RowWatermarks();
     // Subscription registry
     subscriptions = new Map();
     /**

package/dist/local/Model.js

@@ -937,24 +937,6 @@ export class Model {
         }
         // Try to get model class by identifier
         let ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
-        // If not found by registered name, try mapping to the class name
-        if (!ModelClass) {
-            const classNameMap = {
-                Task: 'TaskModel',
-                Project: 'Project',
-                Comment: 'CommentModel',
-                User: 'UserModel',
-                Organization: 'OrganizationModel',
-                StatusGroup: 'StatusGroupModel',
-                Team: 'TeamModel',
-                Member: 'MemberModel',
-                Role: 'RoleModel',
-            };
-            const className = classNameMap[modelIdentifier];
-            if (className) {
-                ModelClass = getActiveRegistry().getModelByName(className);
-            }
-        }
         if (!ModelClass) {
             throw new AbloValidationError(`Model class not found for: ${modelIdentifier}`, { code: 'model_class_not_registered' });
         }

package/dist/local/SyncClient.d.ts

@@ -17,6 +17,7 @@ import { type CommitLatencySample } from './transactions/mutations/commitLatency
 import { type UnconfirmedWritesMetrics } from './transactions/mutations/UnconfirmedWrites.js';
 import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.js';
 import type { Database } from './Database.js';
+import type { BootstrapData } from './sync/BootstrapFetcher.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { LogPosition } from './logPosition.js';
 interface SyncObserver {
@@ -43,6 +44,14 @@ export interface RehydrationStats {
     healed: number;
     elapsedMs: number;
 }
+/**
+ * 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.
+ */
+export type BootstrapSnapshot = Pick<BootstrapData, 'models' | 'failedModels'> & Partial<Pick<BootstrapData, 'lastSyncId'>>;
 export declare class SyncClient extends EventEmitter {
     private readonly runtime;
     private objectPool;
@@ -127,6 +136,13 @@ export declare class SyncClient extends EventEmitter {
      * deliver the missing deltas and confirm the transaction.
      */
     private setupAwaitingTransactionPersistence;
+    /**
+     * 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;
     /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
     private persistAwaitingTransaction;
     /** Drop the persisted awaiting-row once confirmed (never rejects). */
@@ -451,8 +467,6 @@ export declare class SyncClient extends EventEmitter {
             }[];
         };
     };
-    unassignEntity(entityType: string, entityId: string): Promise<void>;
-    reassignEntity(entityType: string, entityId: string, assigneeType: string, assigneeId: string, id?: string): Promise<void>;
     /**
      * Apply a batch of delta results from Database to the InstanceCache.
      * Owns: model creation, upsert, remove, archive, conflict resolution.
@@ -499,18 +513,16 @@ export declare class SyncClient extends EventEmitter {
      * Apply bootstrap data to the InstanceCache with ghost removal.
      * Owns: model creation, batch upsert, ghost detection + removal.
      */
-    applyBootstrapDataToPool(bootstrapData: {
-        models?: Record<string, unknown[]>;
-        failedModels?: string[];
-    }, protectedIds?: ReadonlySet<string>, options?: {
+    applyBootstrapDataToPool(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;
     }): {

package/dist/local/SyncClient.js

@@ -24,32 +24,6 @@ import { LogPosition } from './logPosition.js';
 import { createLocalMutationPort } from './transactions/localMutation.js';
 import { createReconnectDrain } from './transactions/reconnectDrain.js';
 import { DatabaseCommitOutboxStore } from './transactions/databaseCommitOutbox.js';
-/**
- * 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.
- */
-function rawRecordIsNewer(data, existing) {
-    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;
-}
 /**
  * Converts an untyped server `updatedAt` value — an ISO string, epoch number,
  * or Date read off an untyped row — into epoch milliseconds for
@@ -352,10 +326,16 @@ export class SyncClient extends EventEmitter {
             // void is safe: the handler's body is fully try/catch'd.
             void this.persistAwaitingTransaction(event);
         });
-        // 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) => {
             // void is safe: the handler's body is fully try/catch'd.
             void this.removeAwaitingTransaction(tx.id);
+            this.noteOwnWritePositions(tx);
         });
         // Echo detection bridge. When the queue stages a transaction, the
         // client has already optimistically applied the change to the
@@ -373,6 +353,23 @@ export class SyncClient extends EventEmitter {
             this.echoTracker.drainOnRollback(event.transaction.id);
         });
     }
+    /**
+     * 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.
+     */
+    noteOwnWritePositions(tx) {
+        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). */
     async persistAwaitingTransaction(event) {
         if (!this.database)
@@ -1048,8 +1045,7 @@ export class SyncClient extends EventEmitter {
         // only materializes on the rare force-accept branch, for its log line.
         const shouldForceAcceptServer = (serverData.deletedAt !== undefined && serverData.deletedAt !== null) ||
             (serverData.archivedAt !== undefined && serverData.archivedAt !== null) ||
-            serverData.isActive === false ||
-            (serverData.unassignedAt !== undefined && serverData.unassignedAt !== null);
+            serverData.isActive === false;
         if (shouldForceAcceptServer) {
             this.runtime.logger.debug('Accepting server update - critical state change detected', {
                 modelId: localModel.id,
@@ -1113,13 +1109,10 @@ export class SyncClient extends EventEmitter {
         if (serverData.archivedAt !== undefined) {
             critical.archivedAt = serverData.archivedAt;
         }
-        // Deactivation states - critical for assignments and similar entities
+        // Deactivation states are always critical.
         if (serverData.isActive !== undefined && serverData.isActive === false) {
             critical.isActive = false;
         }
-        if (serverData.unassignedAt !== undefined) {
-            critical.unassignedAt = serverData.unassignedAt;
-        }
         return critical;
     }
     /**
@@ -1475,19 +1468,6 @@ export class SyncClient extends EventEmitter {
             mutationQueue: this.mutationQueue.getDebugInfo(),
         };
     }
-    // --- Best-practice assignment ops ---
-    async unassignEntity(entityType, entityId) {
-        // Call server-side unassign to avoid per-id races
-        await this.mutationExecutor.executeDelete('Assignment', entityId);
-    }
-    async reassignEntity(entityType, entityId, assigneeType, assigneeId, id) {
-        await this.mutationExecutor.executeCreate('Assignment', id || '', {
-            entityType,
-            entityId,
-            assigneeType,
-            assigneeId,
-        });
-    }
     // ── Delta + Bootstrap application (owns InstanceCache writes) ──────────────
     /**
      * Apply a batch of delta results from Database to the InstanceCache.
@@ -1602,7 +1582,13 @@ export class SyncClient extends EventEmitter {
                 idsBeingRemoved.add(r.modelId);
         }
         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
             // mutation, so the pool operation is skipped. The IndexedDB write in
@@ -1638,8 +1624,10 @@ export class SyncClient extends EventEmitter {
                         const model = this.objectPool.createFromData(data, undefined, {
                             deferObservability: true,
                         });
-                        if (model)
+                        if (model) {
+                            this.objectPool.watermarks.advance(model, syncId);
                             modelsToAdd.push(model);
+                        }
                     }
                     break;
                 }
@@ -1712,6 +1700,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 = [];
         const serverIdsByType = new Map();
         let healedCount = 0;
@@ -1747,19 +1736,21 @@ 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)) {
+                    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)
+                    if (model) {
+                        this.objectPool.watermarks.advance(model, snapshotPosition);
                         allModels.push(model);
+                    }
                 }
                 catch {
                     skippedCount++;

package/dist/local/client/createInternalComponents.js

@@ -62,6 +62,10 @@ export function createInternalComponents(input) {
         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
     // WebSocket delta stream keeps hydrated rows fresh so repeat reads serve

package/dist/local/client/createModelProxy.js

@@ -19,6 +19,7 @@ import { toMs } from '@abloatai/transaction/utils/duration';
 import { LEASE_TTL_MS } from '@abloatai/transaction/wire/protocol';
 import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
 import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
+import { 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
@@ -75,7 +76,7 @@ hydration, collaboration, readSetContext) {
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
     // The coordination plane must speak the same wire dialect as the commit
-    // plane: the lowercased typename (`task`), not the schema key (`tasks`). The
+    // plane: the lowercased typename (`item`), not the schema key (`items`). The
     // server's commit-time claim guard probes the lease store with the commit
     // operation's model name, so a lease recorded under the schema key never
     // matches — which would silently disarm the guard for every model whose
@@ -115,6 +116,15 @@ hydration, collaboration, readSetContext) {
         };
     };
     const load = async (options) => {
+        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(schemaKey, options);
         return rows.map((row) => modelAsRow(row));
     };
@@ -649,8 +659,16 @@ hydration, collaboration, readSetContext) {
     const list = guard(async (options) => {
         const registry = readSetContext?.getStore();
         const rows = await load(options);
+        // 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(rows, {
+            hasMore: options?.limit !== undefined && rows.length >= options.limit,
+            nextCursor: null,
+        });
         if (!registry)
-            return rows;
+            return page;
         for (const row of rows) {
             const stamp = hydration.getReadEvidence?.(row);
             if (stamp === undefined) {
@@ -665,7 +683,7 @@ hydration, collaboration, readSetContext) {
             }
             capturePointRead(readSetContext, readSetClientIdentity, wireModel, id, row, stamp);
         }
-        return rows;
+        return page;
     });
     const operations = {
         local,

package/dist/local/interfaces/index.d.ts

@@ -253,13 +253,13 @@ export interface RuntimeConfig {
      * Fields to preserve when merging a partial update into the local store. A
      * change usually carries only the fields that changed; listing a model's
      * essential fields here keeps them from being dropped during that merge.
-     * For example: `{ Task: ['title', 'projectId'], Section: ['reportId', 'order'] }`.
+     * For example: `{ Item: ['title', 'projectId'], Section: ['reportId', 'order'] }`.
      */
     essentialFields: Readonly<Record<string, readonly string[]>>;
     /**
      * A fallback map from class name to model name, used to resolve a model's name
      * when the usual lookup fails — for instance, when a bundler has minified the
-     * class names. For example: `{ TaskModel: 'Task', ProjectModel: 'Project' }`.
+     * class names. For example: `{ ItemModel: 'Item', ProjectModel: 'Project' }`.
      */
     classNameFallbackMap: Readonly<Record<string, string>>;
     /**
@@ -283,7 +283,7 @@ export interface RuntimeConfig {
     expectedSourceSchemaHash?: string;
     /**
      * Per-model content hashes of the schema this client was built against,
-     * keyed by schema key (`tasks` → hash of that model's serialized JSON). The
+     * keyed by schema key (`items` → hash of that model's serialized JSON). The
      * semantic layer of the drift check: on a whole-schema mismatch the client
      * compares only the models IT declares against the server's per-model
      * surface, so a purely additive server-side change (new models this build

package/dist/local/rowWatermarks.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare class RowWatermarks {
+    #private;
+    /** Record that `row`'s pooled copy reflects the log at least through `position`. */
+    advance(row: object, position: number | undefined): void;
+    /** The highest log position `row` is known to reflect, if the client has any evidence. */
+    of(row: object): number | undefined;
+    /**
+     * 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;
+}