@abloatai/humans 0.55.0 → 0.57.0

package/dist/local/Database.js

@@ -13,7 +13,7 @@ import { globalRuntime } from './context.js';
 import { AbloConnectionError, AbloValidationError } from '@abloatai/transaction/errors';
 import { persistenceDatabaseNamesForDeletion, purgeIndexedDbPersistence, } from './stores/persistenceCleanup.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
-import { logPositionSchema } from './logPosition.js';
+import { logPositionSnapshotSchema } from './logPosition.js';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
 import { isAcceptedOutboxPromotion, isSameOutboxRecord, } from './transactions/persistedTransaction.js';
 /**
@@ -320,7 +320,7 @@ export class Database {
         // (a corrupted negative/float cursor would previously pass `|| 0`,
         // which only catches falsy, and get sent to the server as the resume
         // point). Invalid → 0 → full bootstrap, the safe degradation.
-        const metadataLastSyncId = logPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
+        const metadataLastSyncId = logPositionSnapshotSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
         const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
         // ── Cache-validity check ─────────────────────────────────────
         //

package/dist/local/Model.js

@@ -936,7 +936,7 @@ export class Model {
             throw new AbloValidationError('Model identifier (__typename, __class, or modelName) not found in data', { code: 'model_identifier_missing' });
         }
         // Try to get model class by identifier
-        let ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
+        const ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
         if (!ModelClass) {
             throw new AbloValidationError(`Model class not found for: ${modelIdentifier}`, { code: 'model_class_not_registered' });
         }

package/dist/local/SyncClient.d.ts

@@ -17,41 +17,11 @@ 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 {
-    onSync?: (event: SyncEvent) => void;
-}
-interface SyncEvent {
-    type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
-    modelType: string;
-    model?: Model;
-    modelId?: string;
-    transactionType?: string;
-}
-interface SyncState {
-    connectionState: 'connected' | 'disconnected' | 'connecting';
-    pendingMutations: number;
-    lastSyncAt?: Date;
-    error?: Error;
-}
-export interface RehydrationStats {
-    added: number;
-    updated: number;
-    removed: number;
-    skipped: number;
-    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'>>;
+import { type RehydrationStats, type SyncObserver, type SyncState } from './syncClientTypes.js';
+import type { BootstrapSnapshot } from './syncClientTypes.js';
+export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
 export declare class SyncClient extends EventEmitter {
     private readonly runtime;
     private objectPool;
@@ -533,4 +503,3 @@ export declare class SyncClient extends EventEmitter {
         healed: number;
     };
 }
-export {};

package/dist/local/SyncClient.js

@@ -24,22 +24,7 @@ import { LogPosition } from './logPosition.js';
 import { createLocalMutationPort } from './transactions/localMutation.js';
 import { createReconnectDrain } from './transactions/reconnectDrain.js';
 import { DatabaseCommitOutboxStore } from './transactions/databaseCommitOutbox.js';
-/**
- * Converts an untyped server `updatedAt` value — an ISO string, epoch number,
- * or Date read off an untyped row — into epoch milliseconds for
- * last-write-wins comparison. Falsy or non-date values become 0, matching the
- * conflict resolver's rule that a missing timestamp sorts as the epoch.
- */
-function toEpochMs(value) {
-    if (!value)
-        return 0;
-    if (value instanceof Date)
-        return value.getTime();
-    if (typeof value === 'string' || typeof value === 'number') {
-        return new Date(value).getTime();
-    }
-    return 0;
-}
+import { toEpochMs, } from './syncClientTypes.js';
 export class SyncClient extends EventEmitter {
     runtime;
     objectPool;

package/dist/local/client/createModelProxy.d.ts

@@ -10,6 +10,7 @@
  * The factory returns a plain object; the client assembles the `ablo.<model>`
  * lookup table from one of these per model.
  */
+import type { CommitCreateOptions, CommitReceipt } from '@abloatai/transaction/resources/httpResources';
 import type { ModelTarget } from '@abloatai/transaction/coordination/schema';
 import type { ModelRegistry } from '../ModelRegistry.js';
 import type { InstanceCache } from '../InstanceCache.js';
@@ -17,7 +18,7 @@ import type { SyncClient } from '../SyncClient.js';
 import type { OnDemandLoader } from '../sync/OnDemandLoader.js';
 import type { JoinedParticipant } from '../sync/participants.js';
 import type { Duration, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease, ClaimWaitOptions, Snapshot } from '@abloatai/transaction/types/streams';
-export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ServerGetOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimSkipOptions, ClaimSkipParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '@abloatai/transaction/resources/modelOperations';
+export type { ModelListScope, ModelTrackParams, ModelTrackResult, LocalReadOptions, LocalCountOptions, ServerReadOptions, ListAllOptions, ServerGetOptions, ServerRetrieveOptions, ClaimTargetOptions, ClaimParams, ClaimContentionOptions, ClaimAttemptEvent, ClaimQueueView, ClaimSkipOptions, ClaimSkipParams, ClaimLookupParams, ClaimReorderParams, ClaimOptions, ClaimReadApi, AwaitedClaimMethod, ClaimApi, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, JoinOptions, } from '@abloatai/transaction/resources/modelOperations';
 export type { Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, HeldLease };
 import type { ClaimApi, ClaimAttemptEvent, JoinOptions, LocalCountOptions, LocalReadOptions } from '@abloatai/transaction/resources/modelOperations';
 import type { HttpModelClient } from '@abloatai/transaction/transport/httpClient';
@@ -39,6 +40,17 @@ export interface ModelCollaboration {
         data: unknown;
         stamp: number;
     }>;
+    /**
+     * The batch commit lane, for a create handed a list of rows.
+     *
+     * A reactive client's single writes go through the mutation queue and land
+     * optimistically, because a rejected write rolls one row back. A batch
+     * cannot: it is atomic, so applying the rows one at a time would paint a
+     * half-written state the server may then decline whole. It goes down the
+     * same commit door the stateless client uses and the rows arrive on the
+     * ordinary stream, the way a teammate's would.
+     */
+    commitBatch(options: CommitCreateOptions): Promise<CommitReceipt>;
     createClaim(options: {
         /**
          * The locator, in the spelling the SDK surface and the HTTP routes use.

package/dist/local/client/createModelProxy.js

@@ -18,8 +18,9 @@ import { Model, modelAsRow } from '../Model.js';
 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 { assertWriteOptions, assertWriteTarget, } from '@abloatai/transaction/resources/writeOptionsSchema';
+import { createModelId, resolveCreatedRows, resolveCreateId, } from '@abloatai/transaction/resources/modelCreate';
+import { collectModelList, 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
@@ -685,6 +686,150 @@ hydration, collaboration, readSetContext) {
         }
         return page;
     });
+    /**
+     * Creates many rows as one atomic commit, and returns them in caller order.
+     */
+    const createManyRows = async (params) => {
+        if (params.data.length === 0)
+            return [];
+        if (!collaboration) {
+            throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so a batch ` +
+                `create is unavailable here. Use the standard Ablo({ schema, apiKey }) client.`, { code: 'model_claim_not_configured' });
+        }
+        const prepared = prepareReadSet(readSetContext, readSetClientIdentity, undefined, undefined, params.idempotencyKey, params.reads);
+        try {
+            const organizationId = syncClient.getOrganizationId() ?? undefined;
+            const ids = [];
+            const operations = params.data.map((row) => {
+                const fields = row;
+                const id = resolveCreateId(undefined, fields) ??
+                    createModelId(registeredModelName, params.idempotencyKey ? `${params.idempotencyKey}:${ids.length}` : null);
+                ids.push(id);
+                return {
+                    action: 'create',
+                    model: registeredModelName,
+                    data: { organizationId: fields.organizationId ?? organizationId, ...fields, id },
+                    id,
+                };
+            });
+            const receipt = await collaboration.commitBatch({
+                operations,
+                wait: 'confirmed',
+                ...(prepared.idempotencyKey
+                    ? { idempotencyKey: prepared.idempotencyKey }
+                    : params.idempotencyKey
+                        ? { idempotencyKey: params.idempotencyKey }
+                        : {}),
+                ...(prepared.reads
+                    ? { reads: [...prepared.reads] }
+                    : {}),
+                ...(params.track ? { track: [...params.track] } : {}),
+            });
+            const rows = await resolveCreatedRows({
+                modelName: registeredModelName,
+                ids,
+                operationResults: receipt.operationResults,
+                readRow: async (id) => {
+                    const read = await collaboration.readPoint(registeredModelName, id);
+                    return read.data;
+                },
+            });
+            consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
+            return rows;
+        }
+        catch (error) {
+            abortReadSetCommit(readSetContext, prepared.automaticCommit);
+            throw error;
+        }
+    };
+    // `create` takes one row or a list of them. The list form is atomic and
+    // is therefore NOT applied optimistically: see `createManyRows`.
+    const createImpl = guardWrite(async (params) => {
+        if (Array.isArray(params.data)) {
+            return createManyRows(params);
+        }
+        const single = params;
+        const id = resolveCreateId(single.id, single.data) ?? Model.generateId();
+        const claim = single.claim;
+        let autoLease;
+        if (claim && !isClaimHandle(claim)) {
+            if (!collaboration) {
+                throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
+            }
+            // Write intent: enter the new row's entity scope before acquiring the
+            // create-claim so the holder's claim presence broadcasts to everyone
+            // already in this entity group (closing the subscribe-versus-broadcast
+            // race — see `takeClaim`). Released with the lease in the `finally`
+            // below. Awaited for broadcast ordering; still best-effort.
+            await collaboration.pinScope?.({ [schemaKey]: id });
+            const contention = resolveClaimContentionOptions(claim);
+            autoLease = await collaboration.createClaim({
+                target: {
+                    model: wireModel,
+                    id,
+                    ...subTarget(claim, schemaKey),
+                },
+                description: claimDescription(claim, 'creating'),
+                ttl: claim.ttl,
+                queue: contention.wait,
+                maxQueueDepth: contention.maxDepth,
+                waitTimeoutMs: contention.timeoutMs,
+                signal: contention.signal,
+                onStatus: contention.onStatus,
+            });
+        }
+        // Default `organizationId` from the client's identity, matching the other
+        // write path — without this, a caller that omits it would create an
+        // org-unscoped row on one write path but not the other. An explicit value
+        // in `data` still wins via the spread.
+        const orgDefault = params.data.organizationId ??
+            syncClient.getOrganizationId();
+        const model = new ModelClass({
+            id,
+            ...(orgDefault != null ? { organizationId: orgDefault } : {}),
+            ...params.data,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        });
+        let prepared;
+        try {
+            const resolved = preparedMutation(single);
+            prepared = resolved.prepared;
+            const effective = {
+                ...resolved.options,
+                ...(autoLease
+                    ? {
+                        claimRef: { id: autoLease.id },
+                        ...(autoLease.fenceToken !== undefined
+                            ? { fenceToken: autoLease.fenceToken }
+                            : {}),
+                    }
+                    : {}),
+                ...(isClaimHandle(claim)
+                    ? {
+                        claimRef: { id: claim.id },
+                        ...(claim.fenceToken !== undefined
+                            ? { fenceToken: claim.fenceToken }
+                            : {}),
+                    }
+                    : {}),
+            };
+            syncClient.add(model, effective);
+            await waitForMutation(model);
+            consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
+            return modelAsRow(model);
+        }
+        catch (error) {
+            abortReadSetCommit(readSetContext, prepared?.automaticCommit ?? false);
+            throw error;
+        }
+        finally {
+            await autoLease?.release?.().catch(() => { });
+        }
+    });
+    function createRows(params) {
+        return createImpl(params);
+    }
     const operations = {
         local,
         get,
@@ -692,85 +837,12 @@ hydration, collaboration, readSetContext) {
         // No automatic scope enrolment on bulk `list`: that would subscribe to an
         // unbounded set of rows' entity groups.
         list,
-        create: guardWrite(async (params) => {
-            const id = params.id ?? Model.generateId();
-            const claim = params.claim;
-            let autoLease;
-            if (claim && !isClaimHandle(claim)) {
-                if (!collaboration) {
-                    throw new AbloValidationError(`Model "${schemaKey}" was built without the collaboration runtime, so claim() is unavailable here. Claiming needs no per-model config — use the standard Ablo({ schema, apiKey }) client and every model is claimable.`, { code: 'model_claim_not_configured' });
-                }
-                // Write intent: enter the new row's entity scope before acquiring the
-                // create-claim so the holder's claim presence broadcasts to everyone
-                // already in this entity group (closing the subscribe-versus-broadcast
-                // race — see `takeClaim`). Released with the lease in the `finally`
-                // below. Awaited for broadcast ordering; still best-effort.
-                await collaboration.pinScope?.({ [schemaKey]: id });
-                const contention = resolveClaimContentionOptions(claim);
-                autoLease = await collaboration.createClaim({
-                    target: {
-                        model: wireModel,
-                        id,
-                        ...subTarget(claim, schemaKey),
-                    },
-                    description: claimDescription(claim, 'creating'),
-                    ttl: claim.ttl,
-                    queue: contention.wait,
-                    maxQueueDepth: contention.maxDepth,
-                    waitTimeoutMs: contention.timeoutMs,
-                    signal: contention.signal,
-                    onStatus: contention.onStatus,
-                });
-            }
-            // Default `organizationId` from the client's identity, matching the other
-            // write path — without this, a caller that omits it would create an
-            // org-unscoped row on one write path but not the other. An explicit value
-            // in `data` still wins via the spread.
-            const orgDefault = params.data.organizationId ??
-                syncClient.getOrganizationId();
-            const model = new ModelClass({
-                id,
-                ...(orgDefault != null ? { organizationId: orgDefault } : {}),
-                ...params.data,
-                createdAt: new Date(),
-                updatedAt: new Date(),
-            });
-            let prepared;
-            try {
-                const resolved = preparedMutation(params);
-                prepared = resolved.prepared;
-                const effective = {
-                    ...resolved.options,
-                    ...(autoLease
-                        ? {
-                            claimRef: { id: autoLease.id },
-                            ...(autoLease.fenceToken !== undefined
-                                ? { fenceToken: autoLease.fenceToken }
-                                : {}),
-                        }
-                        : {}),
-                    ...(isClaimHandle(claim)
-                        ? {
-                            claimRef: { id: claim.id },
-                            ...(claim.fenceToken !== undefined
-                                ? { fenceToken: claim.fenceToken }
-                                : {}),
-                        }
-                        : {}),
-                };
-                syncClient.add(model, effective);
-                await waitForMutation(model);
-                consumeReadSet(readSetContext, readSetClientIdentity, prepared.consumed, prepared.automaticCommit);
-                return modelAsRow(model);
-            }
-            catch (error) {
-                abortReadSetCommit(readSetContext, prepared?.automaticCommit ?? false);
-                throw error;
-            }
-            finally {
-                await autoLease?.release?.().catch(() => { });
-            }
+        listAll: guard(async (options = {}) => {
+            const { maxPages, signal, ...readOptions } = options;
+            signal?.throwIfAborted();
+            return collectModelList(await list(readOptions), { maxPages, signal });
         }),
+        create: createRows,
         // `update` is overloaded — classic `update({ id, data })` + functional
         // `update(id, current => next)`. The IIFE keeps the shared error-guard
         // wrapping while exposing the two public signatures (a plain `guard(...)`
@@ -839,6 +911,10 @@ hydration, collaboration, readSetContext) {
                     });
                 }
                 const params = arg;
+                // Named before anything reads it. Without this the row lookup below
+                // reports `Entity not found: Model/undefined`, which sends the reader
+                // looking for a missing row rather than at the unaddressed write.
+                assertWriteTarget('update', registeredModelName, params.id);
                 const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
                 if (autoClaim) {
                     const handle = await takeClaim({ ...autoClaim, id: params.id });
@@ -912,6 +988,9 @@ hydration, collaboration, readSetContext) {
             return update;
         })(),
         delete: guardWrite(async (params) => {
+            // Before the idempotent "ensure absent" below can read this as a row that
+            // is simply not here. An unaddressed delete is a mistake, not an absence.
+            assertWriteTarget('delete', registeredModelName, params.id);
             const autoClaim = params.claim && !isClaimHandle(params.claim) ? params.claim : null;
             if (autoClaim) {
                 const handle = await takeClaim({ ...autoClaim, id: params.id });

package/dist/local/client/options.d.ts

@@ -71,14 +71,17 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
      * Pins this client to one Ablo project. During `ready()` the server resolves
      * the API key's actual project and the client refuses to start when it differs.
-     * Defaults to `ABLO_PROJECT_ID`; `ablo dev` writes that value beside the key.
-     * This is an assertion, never a routing selector — the key remains authoritative.
+     * Defaults to `ABLO_PROJECT_ID`. This is an assertion, never a routing
+     * selector — the key remains authoritative and already names its own project,
+     * so leave this unset unless one deployment can be handed keys for more than
+     * one project and you want the mismatch to fail loudly.
      */
     projectId?: string | null | undefined;
     /**
      * Pins this client to one immutable Ablo branch. Defaults to
-     * `ABLO_BRANCH_ID`; `ablo dev` writes it beside the branch key. Like
-     * `projectId`, this is a startup assertion and never selects a branch.
+     * `ABLO_BRANCH_ID`. Like `projectId`, this is a startup assertion that never
+     * selects a branch, and is worth setting only where a key for the wrong
+     * environment could reach this process.
      */
     branchId?: string | null | undefined;
     /**

package/dist/local/client/reactiveEngine.js

@@ -408,6 +408,9 @@ export function buildReactiveEngine(inputs) {
         const registeredModelName = modelDef.typename ?? schemaKey;
         modelProxies[schemaKey] = createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, modelRegistry, hydration, {
             createClaim: (claimOptions) => publicClaims.create(claimOptions),
+            // Lazily referenced: `commits` is declared below this loop, and this
+            // only runs when someone actually writes a batch.
+            commitBatch: (commitOptions) => commits.create(commitOptions),
             readPoint,
             createSnapshot: (modelKey, id) => createSnapshot({
                 pool: objectPool,
@@ -502,13 +505,14 @@ export function buildReactiveEngine(inputs) {
             if (wait === 'queued') {
                 return { id: clientTxId, status: 'queued' };
             }
-            const { lastSyncId, notifications, missingIds } = await queue.waitForCommitReceipt(clientTxId);
+            const { lastSyncId, notifications, missingIds, operationResults } = await queue.waitForCommitReceipt(clientTxId);
             return {
                 id: clientTxId,
                 status: 'confirmed',
                 lastSyncId,
                 ...(notifications && notifications.length > 0 ? { notifications } : {}),
                 ...(missingIds && missingIds.length > 0 ? { missingIds } : {}),
+                ...(operationResults && operationResults.length > 0 ? { operationResults } : {}),
             };
         },
         async get({ id }) {

package/dist/local/client/wsMutationExecutor.js

@@ -50,6 +50,7 @@ export function createDefaultMutationExecutor(getWs, readSetContext) {
                     ...(receipt.correlationId ? { correlationId: receipt.correlationId } : {}),
                     ...(receipt.notifications ? { notifications: receipt.notifications } : {}),
                     ...(receipt.missingIds ? { missingIds: receipt.missingIds } : {}),
+                    ...(receipt.operationResults ? { operationResults: receipt.operationResults } : {}),
                 });
             }
             if (!ws.sendCommit) {

package/dist/local/logPosition.d.ts

@@ -1,10 +1,21 @@
+/**
+ * The three log positions a connected client owns.
+ *
+ * Each field is a {@link logPositionSchema}, the one position type, and the
+ * field name says who is claiming what: `applied` is what arrival processed,
+ * `persisted` is what local storage durably holds IN DELIVERED ORDER, and
+ * `acked` is what the server has been told. They are the same kind of number
+ * as the server's heads and cursors, and deliberately not comparable to them
+ * without saying which owner you mean. See the owner table on
+ * `@abloatai/transaction/syncLog/contract`.
+ */
 import { z } from 'zod';
-export declare const logPositionSchema: z.ZodObject<{
+export declare const logPositionSnapshotSchema: z.ZodObject<{
     persisted: z.ZodNumber;
     applied: z.ZodNumber;
     acked: z.ZodNumber;
 }, z.core.$strip>;
-export type LogPositionSnapshot = z.infer<typeof logPositionSchema>;
+export type LogPositionSnapshot = z.infer<typeof logPositionSnapshotSchema>;
 export interface LogPositionPort {
     readonly persisted: number;
     readonly applied: number;

package/dist/local/logPosition.js

@@ -1,11 +1,23 @@
+/**
+ * The three log positions a connected client owns.
+ *
+ * Each field is a {@link logPositionSchema}, the one position type, and the
+ * field name says who is claiming what: `applied` is what arrival processed,
+ * `persisted` is what local storage durably holds IN DELIVERED ORDER, and
+ * `acked` is what the server has been told. They are the same kind of number
+ * as the server's heads and cursors, and deliberately not comparable to them
+ * without saying which owner you mean. See the owner table on
+ * `@abloatai/transaction/syncLog/contract`.
+ */
 import { z } from 'zod';
-export const logPositionSchema = z.object({
-    persisted: z.number().int().nonnegative(),
-    applied: z.number().int().nonnegative(),
-    acked: z.number().int().nonnegative(),
+import { logPositionSchema } from '@abloatai/transaction/syncLog/contract';
+export const logPositionSnapshotSchema = z.object({
+    persisted: logPositionSchema,
+    applied: logPositionSchema,
+    acked: logPositionSchema,
 });
 export function parseLogPosition(value) {
-    const result = logPositionSchema.safeParse(value);
+    const result = logPositionSnapshotSchema.safeParse(value);
     return result.success ? result.data : null;
 }
 const ZERO = { persisted: 0, applied: 0, acked: 0 };

package/dist/local/sync/SyncWebSocket.js

@@ -396,6 +396,22 @@ export class SyncWebSocket extends WsTransport {
                     });
                 });
             }
+            else if (serverHead > this.cursor.lastSyncId) {
+                // The other direction: we are behind the server head and the server
+                // sent nothing. That is not a stall, it is proof. An empty response
+                // means the server walked the log up to `currentSyncId` under this
+                // client's own project and capability scope and found nothing we are
+                // entitled to, and it measured that head through the settled barrier,
+                // so no lower id can still be in flight. Adopting it is therefore
+                // exact, not optimistic.
+                //
+                // Without this, a client on a plane whose head moves for reasons it
+                // cannot see — another project, another sync group, a model outside
+                // its allowlist — never converges. Its cursor sticks, every catch-up
+                // poll finds a gap, and each of those polls takes the plane's advisory
+                // lock to read the settled head. The cost lands on the write path.
+                this.cursor.lastSyncId = serverHead;
+            }
         }
         if (payload.requiresBootstrap) {
             this.emit('bootstrap_required', payload.bootstrapHint);

package/dist/local/syncClientTypes.d.ts

@@ -0,0 +1,41 @@
+import type { Model } from './Model.js';
+import type { BootstrapData } from './sync/BootstrapFetcher.js';
+import type { QueuedMutation } from './transactions/mutations/MutationQueue.js';
+import type { CommitTransaction } from './transactions/mutations/commitLane.js';
+export interface SyncObserver {
+    onSync?: (event: SyncEvent) => void;
+}
+export interface SyncEvent {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
+    modelType: string;
+    model?: Model;
+    modelId?: string;
+    transactionType?: string;
+}
+export interface SyncState {
+    connectionState: 'connected' | 'disconnected' | 'connecting';
+    pendingMutations: number;
+    lastSyncAt?: Date;
+    error?: Error;
+}
+export interface RehydrationStats {
+    added: number;
+    updated: number;
+    removed: number;
+    skipped: number;
+    healed: number;
+    elapsedMs: number;
+}
+export type EventHandler = () => void;
+/** The bootstrap fields applied to the local object pool. */
+export type BootstrapSnapshot = Pick<BootstrapData, 'models' | 'failedModels'> & Partial<Pick<BootstrapData, 'lastSyncId'>>;
+/** A completed queued mutation or explicit commit. */
+export type CompletedTransaction = (Pick<QueuedMutation, 'id' | 'modelId' | 'syncIdNeededForCompletion'> & {
+    lastSyncId?: undefined;
+    operations?: undefined;
+}) | (Pick<CommitTransaction, 'id' | 'lastSyncId' | 'operations'> & {
+    modelId?: undefined;
+    syncIdNeededForCompletion?: undefined;
+});
+/** Normalize an untyped server timestamp for last-write-wins comparison. */
+export declare function toEpochMs(value: unknown): number;

package/dist/local/syncClientTypes.js

@@ -0,0 +1,11 @@
+/** Normalize an untyped server timestamp for last-write-wins comparison. */
+export function toEpochMs(value) {
+    if (!value)
+        return 0;
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'string' || typeof value === 'number') {
+        return new Date(value).getTime();
+    }
+    return 0;
+}

package/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -18,6 +18,7 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import { type LogPositionPort } from '../../logPosition.js';
 import type { WriteOptions } from '../../interfaces/index.js';
 import type { StaleNotification, ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import { type CommitOperationResult } from '@abloatai/transaction/wire/commit';
 import { type MutationInput, type QueuedMutation, type UserContext } from './commitPayload.js';
 import { type CommitOutboxScope } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
@@ -373,6 +374,7 @@ export declare class MutationQueue extends EventEmitter {
         lastSyncId: number;
         notifications?: StaleNotification[];
         missingIds?: string[];
+        operationResults?: CommitOperationResult[];
     }>;
     private isReorderPayload;
     private isPermanentError;