@abloatai/humans 0.55.0 → 0.56.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/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/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/package.json

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

package/src/local/Database.ts

@@ -21,7 +21,7 @@ import {
 } from './stores/persistenceCleanup.js';
 import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
-import { logPositionSchema } from './logPosition.js';
+import { logPositionSnapshotSchema } from './logPosition.js';
 import type { SyncDeltaAction } from '@abloatai/transaction/wire/delta';
 import type { BootstrapType } from '@abloatai/transaction/types';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
@@ -448,7 +448,7 @@ export class Database {
     // 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;
+      logPositionSnapshotSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
     const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
 
     // ── Cache-validity check ─────────────────────────────────────

package/src/local/client/options.ts

@@ -90,15 +90,18 @@ 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/src/local/logPosition.ts

@@ -1,12 +1,25 @@
+/**
+ * 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';
+import { logPositionSchema } from '@abloatai/transaction/syncLog/contract';
 
-export const logPositionSchema = z.object({
-  persisted: z.number().int().nonnegative(),
-  applied: z.number().int().nonnegative(),
-  acked: z.number().int().nonnegative(),
+export const logPositionSnapshotSchema = z.object({
+  persisted: logPositionSchema,
+  applied: logPositionSchema,
+  acked: logPositionSchema,
 });
 
-export type LogPositionSnapshot = z.infer<typeof logPositionSchema>;
+export type LogPositionSnapshot = z.infer<typeof logPositionSnapshotSchema>;
 
 export interface LogPositionPort {
   readonly persisted: number;
@@ -21,7 +34,7 @@ export interface LogPositionPort {
 }
 
 export function parseLogPosition(value: unknown): LogPositionSnapshot | null {
-  const result = logPositionSchema.safeParse(value);
+  const result = logPositionSnapshotSchema.safeParse(value);
   return result.success ? result.data : null;
 }
 

package/src/local/sync/SyncWebSocket.ts

@@ -531,6 +531,21 @@ export class SyncWebSocket<
             }
           );
         });
+      } 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;
       }
     }