@abloatai/humans 0.52.0 → 0.53.0

package/dist/local/Database.js

@@ -16,6 +16,20 @@ import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
 import { logPositionSchema } from './logPosition.js';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
 import { isAcceptedOutboxPromotion, isSameOutboxRecord, } from './transactions/persistedTransaction.js';
+/**
+ * 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, 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 results;
+}
 export class Database {
     // Core database components
     databaseManager;
@@ -831,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);
@@ -1186,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/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). */
@@ -497,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)
@@ -1585,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
@@ -1621,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;
                 }
@@ -1695,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;
@@ -1730,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
@@ -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/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;
+}

package/dist/local/rowWatermarks.js

@@ -0,0 +1,53 @@
+/**
+ * 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 {
+    #positions = new WeakMap();
+    /** Record that `row`'s pooled copy reflects the log at least through `position`. */
+    advance(row, position) {
+        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) {
+        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, snapshotPosition) {
+        if (snapshotPosition === undefined)
+            return false;
+        const known = this.#positions.get(row);
+        return known !== undefined && known > snapshotPosition;
+    }
+}

package/dist/local/sync/OnDemandLoader.d.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';
 import type { Database } from '../Database.js';
@@ -27,10 +34,16 @@ import type { ModelRegistry } from '../ModelRegistry.js';
 import type { RuntimeContext } from '../RuntimeContext.js';
 import type { RecoveryClass } from '@abloatai/transaction/errorCodes';
 import type { LoadWhere, WhereClause } 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`. */
@@ -44,6 +57,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> {
     /**
@@ -211,18 +231,7 @@ export declare class OnDemandLoader {
     private columnizeField;
     private columnizeClause;
 }
-/**
- * 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 declare function normalizeWhere(where: unknown): readonly WhereClause[];
+export { normalizeWhere };
 /**
  * Operator-aware predicate. Mirrors the server's WhereOp semantics for
  * local matching against pool/IDB rows. LIKE/ILIKE use SQL wildcards