@abloatai/humans 0.55.0 → 0.57.0

package/src/local/client/createModelProxy.ts

@@ -37,8 +37,25 @@ import {
   resolveHeartbeatPlan,
   startClaimHeartbeatLoop,
 } from '@abloatai/transaction/coordination/claimHeartbeatLoop';
-import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
-import { modelList, type ModelList } from '@abloatai/transaction/resources/httpResources';
+import {
+  assertWriteOptions,
+  assertWriteTarget,
+} from '@abloatai/transaction/resources/writeOptionsSchema';
+import {
+  createModelId,
+  resolveCreatedRows,
+  resolveCreateId,
+} from '@abloatai/transaction/resources/modelCreate';
+import type {
+  CommitCreateOptions,
+  CommitReceipt,
+} from '@abloatai/transaction/resources/httpResources';
+import type { HttpModelMutationParams } from '@abloatai/transaction/transport/httpClient';
+import {
+  collectModelList,
+  modelList,
+  type 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
@@ -76,6 +93,7 @@ export type {
   LocalReadOptions,
   LocalCountOptions,
   ServerReadOptions,
+  ListAllOptions,
   ServerGetOptions,
   ServerRetrieveOptions,
   ClaimTargetOptions,
@@ -112,6 +130,7 @@ import type {
   JoinOptions,
   LocalCountOptions,
   LocalReadOptions,
+  ModelCreateManyParams,
   ModelCreateParams,
   ModelDeleteParams,
   ModelRetrieveParams,
@@ -119,6 +138,7 @@ import type {
   ModelTrackResult,
   ModelUpdateParams,
   ServerReadOptions,
+  ListAllOptions,
 } from '@abloatai/transaction/resources/modelOperations';
 import {
   claimQueueView,
@@ -165,6 +185,17 @@ type EntityHalf = Pick<ModelTarget, 'model' | 'id'>;
 export interface ModelCollaboration {
   /** Exact point evidence from the HTTP read boundary (stamp captured before data). */
   readPoint(model: string, id: string): Promise<{ 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.
@@ -1198,19 +1229,98 @@ export function createModelProxy<T, C>(
     return page;
   });
 
-  const operations: ModelOperations<T, C> = {
-    local,
+  /**
+   * Creates many rows as one atomic commit, and returns them in caller order.
+   */
+  const createManyRows = async (
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T[]> => {
+    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' },
+      );
+    }
 
-    get,
-    retrieve: get,
+    const prepared = prepareReadSet(
+      readSetContext,
+      readSetClientIdentity,
+      undefined,
+      undefined,
+      params.idempotencyKey,
+      params.reads,
+    );
+    try {
+      const organizationId = syncClient.getOrganizationId() ?? undefined;
+      const ids: string[] = [];
+      const operations = params.data.map((row) => {
+        const fields = row as Record<string, unknown>;
+        const id =
+          resolveCreateId(undefined, fields) ??
+          createModelId(
+            registeredModelName,
+            params.idempotencyKey ? `${params.idempotencyKey}:${ids.length}` : null,
+          );
+        ids.push(id);
+        return {
+          action: 'create' as const,
+          model: registeredModelName,
+          data: { organizationId: fields.organizationId ?? organizationId, ...fields, id },
+          id,
+        };
+      });
 
-    // No automatic scope enrolment on bulk `list`: that would subscribe to an
-    // unbounded set of rows' entity groups.
-    list,
+      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<T>({
+        modelName: registeredModelName,
+        ids,
+        operationResults: receipt.operationResults,
+        readRow: async (id) => {
+          const read = await collaboration.readPoint(registeredModelName, id);
+          return read.data as T | undefined;
+        },
+      });
+      consumeReadSet(
+        readSetContext,
+        readSetClientIdentity,
+        prepared.consumed,
+        prepared.automaticCommit,
+      );
+      return rows;
+    } catch (error) {
+      abortReadSetCommit(readSetContext, prepared.automaticCommit);
+      throw error;
+    }
+  };
 
-    create: guardWrite(async (params: ModelCreateParams<T, C>): Promise<T> => {
-      const id = params.id ?? Model.generateId();
-      const claim = params.claim;
+  // `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:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T | T[]> => {
+    if (Array.isArray(params.data)) {
+      return createManyRows(params as HttpModelMutationParams<ModelCreateManyParams<C>>);
+    }
+    const single = params as ModelCreateParams<T, C>;
+      const id = resolveCreateId(single.id, single.data) ?? Model.generateId();
+      const claim = single.claim;
       let autoLease: Claim | undefined;
       if (claim && !isClaimHandle(claim)) {
         if (!collaboration) {
@@ -1258,7 +1368,7 @@ export function createModelProxy<T, C>(
       });
       let prepared: PreparedReadSet | undefined;
       try {
-        const resolved = preparedMutation(params);
+        const resolved = preparedMutation(single);
         prepared = resolved.prepared;
         const effective: MutationOptions = {
           ...resolved.options,
@@ -1294,8 +1404,42 @@ export function createModelProxy<T, C>(
       } finally {
         await autoLease?.release?.().catch(() => {});
       }
+  });
+
+  // Two public signatures over one implementation. A property arrow would
+  // collapse them to their union, and a single create would start
+  // resolving to `T | T[]` for every caller.
+  function createRows(
+    params: HttpModelMutationParams<ModelCreateParams<T, C>>,
+  ): Promise<T>;
+  function createRows(
+    params: HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T[]>;
+  function createRows(
+    params:
+      | HttpModelMutationParams<ModelCreateParams<T, C>>
+      | HttpModelMutationParams<ModelCreateManyParams<C>>,
+  ): Promise<T | T[]> {
+    return createImpl(params);
+  }
+
+  const operations: ModelOperations<T, C> = {
+    local,
+
+    get,
+    retrieve: get,
+
+    // No automatic scope enrolment on bulk `list`: that would subscribe to an
+    // unbounded set of rows' entity groups.
+    list,
+    listAll: guard(async (options: ListAllOptions<T> = {}) => {
+      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(...)`
@@ -1400,6 +1544,10 @@ export function createModelProxy<T, C>(
           });
         }
         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) {
@@ -1495,6 +1643,9 @@ export function createModelProxy<T, C>(
     })(),
 
     delete: guardWrite(async (params: ModelDeleteParams<T, C>): Promise<void> => {
+      // 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) {

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/client/reactiveEngine.ts

@@ -589,6 +589,9 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
       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({
@@ -701,7 +704,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	        return { id: clientTxId, status: 'queued' };
 	      }
 
-	      const { lastSyncId, notifications, missingIds } =
+	      const { lastSyncId, notifications, missingIds, operationResults } =
 	        await queue.waitForCommitReceipt(clientTxId);
 	      return {
 	        id: clientTxId,
@@ -709,6 +712,7 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	        lastSyncId,
 	        ...(notifications && notifications.length > 0 ? { notifications } : {}),
 	        ...(missingIds && missingIds.length > 0 ? { missingIds } : {}),
+	        ...(operationResults && operationResults.length > 0 ? { operationResults } : {}),
 	      };
 	    },
 	    async get({ id }) {

package/src/local/client/wsMutationExecutor.ts

@@ -95,6 +95,7 @@ import { AbloError, AbloConnectionError } from '@abloatai/transaction/errors';
 	          ...(receipt.correlationId ? { correlationId: receipt.correlationId } : {}),
 	          ...(receipt.notifications ? { notifications: receipt.notifications } : {}),
 	          ...(receipt.missingIds ? { missingIds: receipt.missingIds } : {}),
+	          ...(receipt.operationResults ? { operationResults: receipt.operationResults } : {}),
 	        });
 	      }
 	      if (!ws.sendCommit) {

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;
       }
     }
 

package/src/local/syncClientTypes.ts

@@ -0,0 +1,59 @@
+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 function toEpochMs(value: unknown): number {
+  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;
+}