@abloatai/humans 0.51.0 → 0.53.0

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

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;
@@ -415,7 +419,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;
         void _dropMangled;
@@ -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/local/sync/deltaPipeline.js

@@ -276,7 +276,7 @@ async function drainPendingDeltas(ctx) {
             // 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/dist/local/sync/initialize.js

@@ -43,7 +43,7 @@ export function* initialize(host, context, signal) {
         // 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
@@ -55,7 +55,7 @@ export function* initialize(host, context, signal) {
             // 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/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -167,7 +167,7 @@ export declare 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/dist/local/transactions/mutations/MutationQueue.js

@@ -417,7 +417,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/dist/local/transactions/persistedTransaction.d.ts

@@ -0,0 +1,39 @@
+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[];
+    awaitingDelta?: {
+        syncIdNeeded: number;
+        modelName: string;
+        modelId: string;
+        operationType: string;
+    };
+    [key: string]: unknown;
+}
+/** Compare the stable request identity while ignoring local seal timing. */
+export declare function isSameOutboxRecord(existing: PersistedTransaction, candidate: PersistedTransaction): boolean;
+/** An accepted envelope may replace the otherwise-identical pending envelope. */
+export declare function isAcceptedOutboxPromotion(existing: PersistedTransaction | undefined, candidate: PersistedTransaction): boolean;
+export {};

package/dist/local/transactions/persistedTransaction.js

@@ -0,0 +1,53 @@
+/** Compare the stable request identity while ignoring local seal timing. */
+export 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,
+            // 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) => ({
+            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, candidate) {
+    return (existing !== undefined &&
+        (existing.type === 'commit_envelope' ||
+            existing.type === 'http_commit_envelope') &&
+        existing.type === candidate.type &&
+        existing.acceptedAt === undefined &&
+        candidate.acceptedAt !== undefined);
+}

package/dist/local/utils/mobxSetup.js

@@ -48,7 +48,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         return false;
     };
     // 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/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/dist/react/AbloProvider.d.ts

@@ -206,10 +206,10 @@ export declare 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/dist/react/AbloProvider.js

@@ -400,10 +400,10 @@ export function usePeers(scope) {
 /**
  * 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/dist/react/context.d.ts

@@ -8,7 +8,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.
      *
@@ -38,7 +38,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/dist/react/useAblo.d.ts

@@ -54,13 +54,13 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // 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']>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.51.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.51.0",
+    "@abloatai/transaction": "^0.53.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"