@abloatai/ablo 0.27.0 → 0.29.0

package/dist/client/Ablo.d.ts

@@ -18,7 +18,7 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
+import type { Schema, SchemaRecord, InferModel, InferCreate, InferRow } from '../schema/schema.js';
 import type { ModelTarget, ModelClaim } from '../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
 import { InstanceCache } from '../InstanceCache.js';
@@ -26,14 +26,25 @@ import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
 import type { PresenceStream, Snapshot } from '../types/streams.js';
-import { type AbloApi, type AbloApiClientOptions, type AbloApiClaims } from './ApiClient.js';
 import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
 import type { AbloOptions } from './options.js';
-import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams, ModelClient } from './resourceTypes.js';
+import type { AbloSession, CommitResource, CreateAgentClientParams, CreateSessionParams } from './resourceTypes.js';
 export type { ApiKeySetter, AbloOptions, InternalAbloOptions } from './options.js';
-export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, ModelRead, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, ModelClient, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, ModelOperationAction, CommitWait, IfClaimedPolicy, ClaimedOptions, ClaimWaitOptions, ModelReadOptions, ClaimCreateOptions, CommitOperationInput, CommitCreateOptions, CommitReceipt, CommitResource, ClaimResource, ModelMutationOptions, HttpClaimApi, SessionOperation, CreateUserSessionParams, CreateAgentSessionParams, CreateSessionParams, CreateAgentClientParams, AbloSession, } from './resourceTypes.js';
 export { computeFKDepthPriority } from './schemaConfig.js';
 import type { ModelOperations } from './createModelProxy.js';
+/**
+ * The reactive-read client a `useAblo` selector receives. The same surface as
+ * {@link Ablo}, except model reads are typed as reactive rows
+ * ({@link InferRow}: data fields + computeds, no relation accessors, no model
+ * methods) — the shape a reactive read actually delivers after
+ * `toReactiveSnapshot()`. Reading `row.layers` off a reactive read is a
+ * compile error here instead of a silent runtime `undefined`; compose
+ * relations through selectors or hooks that resolve the pool's instance.
+ */
+export type AbloReads<S extends SchemaRecord> = Omit<Ablo<S>, keyof S & string> & {
+    readonly [K in keyof S & string]: ModelOperations<InferRow<Schema<S>, K>, InferCreate<Schema<S>, K>>;
+};
 /** The typed sync engine client — one property per model in the schema */
 export type Ablo<S extends SchemaRecord> = {
     readonly [K in keyof S & string]: ModelOperations<InferModel<Schema<S>, K>, InferCreate<Schema<S>, K>>;
@@ -260,12 +271,6 @@ export type Ablo<S extends SchemaRecord> = {
      * down to `commits.create(...)`.
      */
     readonly commits: CommitResource;
-    /**
-     * Canonical untyped model API. This is the portable API shape that maps
-     * cleanly to HTTP/Python/Ruby/Go clients. Typed `ablo.<model>` properties
-     * are schema-powered sugar over the same model write/read path.
-     */
-    model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     /**
      * Capture a context-staleness watermark over a set of entities.
      * Returns a flat snapshot with `stamp` (thread into writes as
@@ -325,7 +330,6 @@ export declare function Ablo<const S extends SchemaRecord>(options: AbloHttpClie
     transport: 'http';
 }): AbloHttpClient<S>;
 export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
-export declare function Ablo(options: AbloApiClientOptions): AbloApi;
 import type * as _Streams from '../types/streams.js';
 import type * as _Participants from '../sync/participants.js';
 import type * as _Policy from '../policy/types.js';
@@ -333,6 +337,7 @@ import type * as _Mutators from '../mutators/defineMutators.js';
 import type * as _Tx from '../mutators/Transaction.js';
 import type * as _Undo from '../mutators/UndoManager.js';
 import type * as _SchemaTypes from '../schema/schema.js';
+import type * as _Global from '../types/global.js';
 /**
  * The canonical type namespace.
  *
@@ -351,15 +356,11 @@ import type * as _SchemaTypes from '../schema/schema.js';
  */
 export declare namespace Ablo {
     type Options<S extends SchemaRecord = SchemaRecord> = AbloOptions<S>;
-    type Api = AbloApi;
-    type ApiClaims = AbloApiClaims;
-    type Capability = import('./ApiClient.js').Capability;
-    type CapabilityCreateOptions = import('./ApiClient.js').CapabilityCreateOptions;
-    type CapabilityRecord = import('./ApiClient.js').CapabilityRecord;
-    type CapabilityResource = import('./ApiClient.js').CapabilityResource;
-    type CapabilityRevocation = import('./ApiClient.js').CapabilityRevocation;
-    type CapabilityRotateOptions = import('./ApiClient.js').CapabilityRotateOptions;
-    type RotatedCapability = import('./ApiClient.js').RotatedCapability;
+    /**
+     * The read view of the client that `useAblo` selectors receive: model reads
+     * typed as reactive rows (data fields + computeds, no relation accessors).
+     */
+    type Reads<S extends SchemaRecord = SchemaRecord> = AbloReads<S>;
     type IfClaimedPolicy = import('./resourceTypes.js').IfClaimedPolicy;
     type ClaimedOptions = import('./resourceTypes.js').ClaimedOptions;
     type ClaimTarget = _Streams.ClaimTarget;
@@ -387,9 +388,34 @@ export declare namespace Ablo {
         type JoinOptions = _Participants.ParticipantJoinOptions;
     }
     type Schema<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord> = _SchemaTypes.Schema<S>;
+    /**
+     * The schema this program has registered via `interface Register { Schema }`
+     * (falls back to a loose shape when unregistered). Use it where shared code
+     * needs "this app's schema" without importing a specific one —
+     * `Ablo<Ablo.ResolveSchema['models']>` resolves to whatever the consuming
+     * app registered, so one component types correctly across apps that bind
+     * different schemas.
+     */
+    type ResolveSchema = _Global.ResolveSchema;
+    /**
+     * `ResolveSchema` guaranteed to satisfy the `Schema` bound. `ResolveSchema`
+     * falls back to a loose `{ models }` shape when nothing is registered, which
+     * doesn't extend the branded `Schema` type — so generics bounded by `Schema`
+     * (mutator anchors, `Transaction<S>`) can't take `ResolveSchema` directly.
+     * `RegisteredSchema` collapses that fallback to `Schema`, so shared mutator
+     * code can anchor "this app's schema" and stay assignable at the consumer,
+     * which reads the same `Register`. Both resolve in lockstep per app.
+     */
+    type RegisteredSchema = _Global.ResolveSchema extends _SchemaTypes.Schema ? _Global.ResolveSchema : _SchemaTypes.Schema;
     namespace Schema {
         type InferModel<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferModel<S, K>;
         type InferCreate<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferCreate<S, K>;
+        /**
+         * The reactive-row companion to {@link InferModel}: data fields + computed
+         * getters, no relation accessors, no model methods — the shape `useAblo`
+         * reads return.
+         */
+        type InferRow<S extends _SchemaTypes.Schema, K extends keyof S['models']> = _SchemaTypes.InferRow<S, K>;
         type InferModelNames<S extends _SchemaTypes.Schema> = _SchemaTypes.InferModelNames<S>;
     }
     type Conflict = _Policy.Conflict;
@@ -410,6 +436,7 @@ export declare namespace Ablo {
     }
     namespace Claim {
         type Handle = import('./resourceTypes.js').Claim;
+        type Held<T = Record<string, unknown>> = import('../types/streams.js').HeldClaim<T>;
         type CreateOptions = import('./resourceTypes.js').ClaimCreateOptions;
         type WaitOptions = import('./resourceTypes.js').ClaimWaitOptions;
         type Client = import('./resourceTypes.js').ClaimResource;
@@ -417,9 +444,11 @@ export declare namespace Ablo {
     namespace Model {
         type Target = import('./resourceTypes.js').ModelTarget;
         type Claim = import('./resourceTypes.js').ModelClaim;
-        type Read<T = Record<string, unknown>> = import('./resourceTypes.js').ModelRead<T>;
-        type Client<T = Record<string, unknown>> = import('./resourceTypes.js').ModelClient<T>;
-        type ReadOptions = import('./resourceTypes.js').ModelReadOptions;
+        type Operations<T, CreateInput = T> = import('./createModelProxy.js').ModelOperations<T, CreateInput>;
+        type ClaimOptions<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimOptions<T>;
+        type ClaimParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimParams<T>;
+        type ClaimLookupParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimLookupParams<T>;
+        type ClaimReorderParams<T = Record<string, unknown>> = import('./createModelProxy.js').ClaimReorderParams<T>;
         type MutationOptions = import('./resourceTypes.js').ModelMutationOptions;
     }
     namespace Source {
@@ -429,7 +458,7 @@ export declare namespace Ablo {
         type EventsResult = import('../source/index.js').SourceEventsResult;
         type Scope = import('../source/index.js').SourceScope;
         type ApiKey = import('../source/index.js').SourceApiKey;
-        type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').AbloSourceOptions<S, TAuth>;
+        type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').DataSourceOptions<S, TAuth>;
         type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('../source/index.js').SourceModelHandlers<Row, CreateInput, TAuth>;
         type SignatureVerificationResult = import('../source/index.js').SourceSignatureVerificationResult;
         namespace Commit {

package/dist/client/Ablo.js

@@ -18,7 +18,8 @@
  *   });
  *   await sync.reports.delete({ id: reportId });
  */
-import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
+import { durableCommitOperationSchema, } from '../transactions/commitEnvelope.js';
+import { AbloAuthenticationError, AbloConnectionError, AbloValidationError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
@@ -35,10 +36,8 @@ import { createPresenceStream } from '../sync/createPresenceStream.js';
 import { createClaimStream } from '../sync/createClaimStream.js';
 import { awaitClaimGrant } from '../sync/awaitClaimGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
-import { reconcileFunctionalUpdate } from './functionalUpdate.js';
 import { createParticipantManager } from '../sync/participants.js';
-import { createProtocolClient, } from './ApiClient.js';
-// Value import is cycle-safe: httpClient.js and ApiClient.js take the client
+// Value import is cycle-safe: httpClient.js and httpTransport.js take the client
 // types from the `options`/`resourceTypes` leaves, never from this module.
 import { createAbloHttpClient, } from './httpClient.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
@@ -74,11 +73,6 @@ function resolveCredentialResolver(apiKey) {
     return null;
 }
 export function Ablo(options) {
-    if (options.schema == null) {
-        // The protocol client IS the stateless HTTP plane (string-keyed models),
-        // so `transport: 'http'` needs no special-casing here.
-        return createProtocolClient(options);
-    }
     if (options.transport === 'http') {
         return createAbloHttpClient(options);
     }
@@ -489,10 +483,6 @@ export function Ablo(options) {
             await new Promise((resolve) => setTimeout(resolve, 50));
         }
     }
-    const fetchImpl = options.fetch ?? globalThis.fetch;
-    function authHeaders() {
-        return authCredentials.withAuthHeaders({ 'Content-Type': 'application/json' });
-    }
     function createClientTxId(idempotencyKey) {
         if (idempotencyKey && idempotencyKey.length > 0)
             return idempotencyKey;
@@ -500,50 +490,24 @@ export function Ablo(options) {
             ? crypto.randomUUID()
             : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createModelId() {
-        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-            ? crypto.randomUUID()
-            : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-    }
-    function normalizeClaimId(claim) {
-        if (typeof claim === 'string')
-            return claim;
-        return claim?.id;
-    }
-    function isClaimHandleValue(value) {
-        return (typeof value === 'object' &&
-            value !== null &&
-            value.object === 'claim' &&
-            typeof value.id === 'string');
-    }
     function normalizeCommitOperation(op, defaults) {
-        const model = op.model ?? op.target?.model;
-        if (!model) {
-            throw new AbloValidationError('Commit operation requires `model` or `target.model`.', { code: 'commit_operation_model_required' });
-        }
         const type = op.action.toUpperCase();
-        const id = op.id ?? op.target?.id ?? '';
-        return {
+        const id = op.id ?? '';
+        return durableCommitOperationSchema.parse({
             type,
-            model: model.toLowerCase(),
+            model: op.model.toLowerCase(),
             id,
             input: op.data ?? undefined,
             transactionId: op.transactionId ?? undefined,
             readAt: op.readAt ?? defaults.readAt ?? undefined,
             onStale: op.onStale ?? defaults.onStale ?? undefined,
-        };
+        });
     }
     function normalizeCommitOperations(commitOptions) {
-        if (commitOptions.operation && commitOptions.operations) {
-            throw new AbloValidationError('Pass either `operation` or `operations`, not both.', { code: 'commit_operations_ambiguous' });
+        if (commitOptions.operations.length === 0) {
+            throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
         }
-        const inputOperations = commitOptions.operation
-            ? [commitOptions.operation]
-            : commitOptions.operations ?? [];
-        if (inputOperations.length === 0) {
-            throw new AbloValidationError('Commit requires at least one operation.', { code: 'commit_operation_required' });
-        }
-        return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
     function modelClaimFromActive(claim) {
         const description = descriptionFromMeta(claim.target.meta);
@@ -631,16 +595,6 @@ export function Ablo(options) {
             }
         });
     }
-    async function applyClaimedPolicy(target, options) {
-        const policy = options?.ifClaimed ?? 'return';
-        if (policy === 'return')
-            return;
-        const current = listModelClaims(target);
-        if (current.length === 0)
-            return;
-        // policy === 'fail' — gate the read only when the caller opts in.
-        throw claimedError(target, current, 'model_claimed');
-    }
     function wrapClaimHandle(claim, waited = false) {
         const release = async () => {
             claim.revoke?.();
@@ -805,8 +759,6 @@ export function Ablo(options) {
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
             const wait = commitOptions.wait ?? 'confirmed';
-            const claimId = normalizeClaimId(commitOptions.claimRef) ?? claim?.id;
-            void claimId; // The current wire clears claims by entity after commit.
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
             // reconnect, mutationExecutor.commit() owns transport-level
@@ -817,7 +769,7 @@ export function Ablo(options) {
             // SyncClient we already hold from createInternalComponents —
             // no need to leak an accessor through BaseSyncedStore.
             const queue = syncClient.getTransactionQueue();
-            queue.enqueueCommit(clientTxId, operations, {
+            await queue.enqueueCommit(clientTxId, operations, {
                 ...(commitOptions.reads ? { reads: [...commitOptions.reads] } : {}),
             });
             if (wait === 'queued') {
@@ -832,144 +784,6 @@ export function Ablo(options) {
             };
         },
     };
-    async function retrieveModel(modelName, id, options) {
-        await applyClaimedPolicy({ model: modelName, id }, options);
-        await ready();
-        const res = await fetchImpl(`${bootstrapHelper.baseUrl}/sync/query`, {
-            method: 'POST',
-            headers: authHeaders(),
-            body: JSON.stringify({
-                queries: [
-                    {
-                        model: modelName,
-                        where: [['id', '=', id]],
-                        limit: 1,
-                    },
-                ],
-            }),
-        });
-        const bodyText = await res.text();
-        let body = bodyText;
-        if (bodyText.length > 0) {
-            try {
-                body = JSON.parse(bodyText);
-            }
-            catch {
-                // Keep raw body text.
-            }
-        }
-        if (!res.ok) {
-            throw translateHttpError(res.status, body || `Model retrieve failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
-        }
-        const parsed = body;
-        const slot = parsed.results?.[0];
-        const rows = Array.isArray(slot) ? slot : [];
-        const data = rows[0];
-        if (!data) {
-            throw new AbloValidationError(`Model row not found: ${modelName}/${id}`, { code: 'model_not_found' });
-        }
-        const stamp = typeof parsed.lastSyncId === 'number'
-            ? parsed.lastSyncId
-            : store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0;
-        return {
-            data,
-            stamp,
-            claims: listModelClaims({ model: modelName, id }),
-        };
-    }
-    function model(name) {
-        function updateModel(arg, updater, contention) {
-            if (typeof arg === 'string') {
-                const id = arg;
-                if (typeof updater !== 'function') {
-                    throw new AbloValidationError(`${name}.update('${id}', updater): the second argument must be an updater ` +
-                        `function (current) => next. To write a fixed value, use update({ id, data }).`, { code: 'write_options_invalid' });
-                }
-                return reconcileFunctionalUpdate(updater, contention, {
-                    model: name,
-                    id,
-                    readFresh: async () => {
-                        const read = await retrieveModel(name, id, {});
-                        return { data: read.data, stamp: read.stamp };
-                    },
-                    writeNext: (patch, readAt) => commits.create({
-                        readAt,
-                        onStale: 'reject',
-                        wait: 'confirmed',
-                        operations: [
-                            { action: 'update', model: name, id, data: patch },
-                        ],
-                    }),
-                });
-            }
-            const params = arg;
-            return (async () => {
-                await applyClaimedPolicy({ model: name, id: params.id }, params);
-                return commits.create({
-                    claimRef: params.claimRef,
-                    idempotencyKey: params.idempotencyKey,
-                    readAt: params.readAt,
-                    onStale: params.onStale,
-                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
-                    wait: params.wait,
-                    operations: [
-                        { action: 'update', model: name, id: params.id, data: params.data },
-                    ],
-                });
-            })();
-        }
-        return {
-            retrieve(params) {
-                return retrieveModel(name, params.id, params);
-            },
-            async create(params) {
-                const id = params.id ?? createModelId();
-                await applyClaimedPolicy({ model: name, id }, params);
-                // Confirm, then return the authoritative row (with framework defaults;
-                // the existing row on an idempotent re-create) — mirrors the WebSocket client.
-                await commits.create({
-                    claimRef: params.claimRef,
-                    idempotencyKey: params.idempotencyKey,
-                    readAt: params.readAt,
-                    onStale: params.onStale,
-                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
-                    wait: params.wait ?? 'confirmed',
-                    operations: [
-                        {
-                            action: 'create',
-                            model: name,
-                            id,
-                            data: params.data,
-                        },
-                    ],
-                });
-                const { data } = await retrieveModel(name, id, {});
-                if (data === undefined) {
-                    throw new AbloNotFoundError(`create ${name}/${id} did not yield a readable row (the write did not confirm).`, [id]);
-                }
-                return data;
-            },
-            update: updateModel,
-            async delete(params) {
-                await applyClaimedPolicy({ model: name, id: params.id }, params);
-                return commits.create({
-                    claimRef: params.claimRef,
-                    idempotencyKey: params.idempotencyKey,
-                    readAt: params.readAt,
-                    onStale: params.onStale,
-                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
-                    wait: params.wait,
-                    operations: [
-                        {
-                            action: 'delete',
-                            model: name,
-                            id: params.id,
-                        },
-                    ],
-                });
-            },
-        };
-    }
     /**
      * The control-plane credential: always the original configured secret key.
      * Never reads `authCredentials` — that holds the exchanged sync credential
@@ -1071,7 +885,7 @@ export function Ablo(options) {
             },
         },
         // Mint a scoped agent identity and hand back a connected client bound to it —
-        // `sessions.create({ agent })` plus `Ablo({ apiKey })` fused into one call,
+        // `sessions.create({ agent })` plus a typed `Ablo({ schema, apiKey })` client,
         // for agents that run in this (secret-key-holding) process. Omitting `id`
         // yields a fresh uuid per call, so concurrent agents are distinct participants
         // that queue behind each other (even when they share a `name`). Humans don't
@@ -1177,7 +991,6 @@ export function Ablo(options) {
         /** Claim livestream — same socket. Stable reference. */
         claims: publicClaims,
         commits,
-        model,
         /** Context-staleness snapshot — see `engine.snapshot(...)` JSDoc. */
         snapshot(entities) {
             return createSnapshot({

package/dist/client/claimHeartbeatLoop.d.ts

@@ -1,7 +1,7 @@
 /**
  * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
  * implementation shared by both transports (the WebSocket claim stream and the
- * HTTP `ApiClient`), so the cadence and failure semantics cannot drift.
+ * private HTTP transport), so the cadence and failure semantics cannot drift.
  *
  * A beat is the "still working" signal that keeps a lease alive for the
  * duration of real work. The loop's failure handling follows the lease-system

package/dist/client/claimHeartbeatLoop.js

@@ -1,7 +1,7 @@
 /**
  * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
  * implementation shared by both transports (the WebSocket claim stream and the
- * HTTP `ApiClient`), so the cadence and failure semantics cannot drift.
+ * private HTTP transport), so the cadence and failure semantics cannot drift.
  *
  * A beat is the "still working" signal that keeps a lease alive for the
  * duration of real work. The loop's failure handling follows the lease-system

package/dist/client/createInternalComponents.d.ts

@@ -16,6 +16,7 @@ import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import { type AbloPersistence } from './persistence.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../transactions/durableWriteStore.js';
 export interface InternalComponentsInput<S extends SchemaRecord> {
     readonly schema: Schema<S>;
     /** The WebSocket URL. Used to derive the bootstrap HTTP base URL when the
@@ -28,6 +29,9 @@ export interface InternalComponentsInput<S extends SchemaRecord> {
         readonly persistence?: AbloPersistence;
         readonly offline?: boolean;
         readonly inMemory?: boolean;
+        readonly durableWrites?: DurableWritesConfig;
+        /** @deprecated Use `durableWrites`. */
+        readonly commitOutbox?: DurableWriteStore;
     };
     readonly auth?: AuthCredentialSource;
 }

package/dist/client/createInternalComponents.js

@@ -15,6 +15,7 @@ import { OnDemandLoader } from '../sync/OnDemandLoader.js';
 import { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 import { resolveBootstrapBaseUrl } from './auth.js';
 import { shouldUseInMemoryPersistence } from './persistence.js';
+import { resolveDurableWrites } from './durableWrites.js';
 export function createInternalComponents(input) {
     const { schema, url, options, auth } = input;
     // The registry is created here, but model registration happens in the caller,
@@ -41,7 +42,8 @@ export function createInternalComponents(input) {
         // IndexedDB is unavailable there.
         inMemory: shouldUseInMemoryPersistence(options),
     });
-    const syncClient = new SyncClient(objectPool, database);
+    const durableWrites = resolveDurableWrites(options);
+    const syncClient = new SyncClient(objectPool, database, durableWrites.store, durableWrites.namespace ?? url);
     // Lazy-load lane: hydrates the object pool and IndexedDB on demand for
     // entities not in scope at bootstrap (`load: 'lazy'` models, or an entity
     // reached by deep link before the pool warmed up). Single-flight, with

package/dist/client/durableWrites.d.ts

@@ -0,0 +1,21 @@
+/** Normalize the product-facing durable-write option and its legacy aliases. */
+import type { CommitOutboxScope } from '../transactions/commitEnvelope.js';
+import { type DurableWriteStore, type DurableWritesConfig } from '../transactions/durableWriteStore.js';
+interface DurableWriteOptionInput {
+    readonly durableWrites?: DurableWritesConfig;
+    /** Compatibility input for pre-`durableWrites` clients. */
+    readonly commitOutbox?: DurableWriteStore;
+    /** Compatibility input and internal child-client identity seam. */
+    readonly commitOutboxScope?: CommitOutboxScope;
+}
+export interface ResolvedDurableWrites {
+    readonly store?: DurableWriteStore;
+    readonly namespace?: string;
+}
+/**
+ * Resolves one canonical store configuration for both HTTP and WebSocket
+ * clients. Mixed old/new configuration fails loudly so Ablo never persists to
+ * one adapter while the caller believes another adapter is authoritative.
+ */
+export declare function resolveDurableWrites(options: DurableWriteOptionInput): ResolvedDurableWrites;
+export {};

package/dist/client/durableWrites.js

@@ -0,0 +1,46 @@
+/** Normalize the product-facing durable-write option and its legacy aliases. */
+import { AbloValidationError } from '../errors.js';
+import { durableWritesConfigSchema, durableWriteStoreSchema, } from '../transactions/durableWriteStore.js';
+function invalidDurableWrites(message) {
+    return new AbloValidationError(`Ablo: invalid \`durableWrites\` option — ${message}.`, {
+        code: 'invalid_options',
+        param: 'durableWrites',
+    });
+}
+/**
+ * Resolves one canonical store configuration for both HTTP and WebSocket
+ * clients. Mixed old/new configuration fails loudly so Ablo never persists to
+ * one adapter while the caller believes another adapter is authoritative.
+ */
+export function resolveDurableWrites(options) {
+    if (options.durableWrites !== undefined && options.commitOutbox !== undefined) {
+        throw invalidDurableWrites('pass `durableWrites` or the deprecated `commitOutbox`, not both');
+    }
+    if (options.durableWrites !== undefined) {
+        const parsed = durableWritesConfigSchema.safeParse(options.durableWrites);
+        if (!parsed.success) {
+            throw invalidDurableWrites(parsed.error.issues.map((issue) => issue.message).join('; '));
+        }
+        return {
+            store: parsed.data.store,
+            ...(parsed.data.namespace !== undefined
+                ? { namespace: parsed.data.namespace }
+                : options.commitOutboxScope?.namespace !== undefined
+                    ? { namespace: options.commitOutboxScope.namespace }
+                    : {}),
+        };
+    }
+    if (options.commitOutbox !== undefined) {
+        const parsed = durableWriteStoreSchema.safeParse(options.commitOutbox);
+        if (!parsed.success) {
+            throw invalidDurableWrites(parsed.error.issues.map((issue) => issue.message).join('; '));
+        }
+        return {
+            store: parsed.data,
+            ...(options.commitOutboxScope?.namespace !== undefined
+                ? { namespace: options.commitOutboxScope.namespace }
+                : {}),
+        };
+    }
+    return {};
+}