@abloatai/ablo 0.28.0 → 0.29.0

package/dist/client/{ApiClient.js → httpTransport.js}

@@ -1,8 +1,9 @@
 /**
- * The stateless API client behind `Ablo({ apiKey })`. It carries no schema,
- * object pool, local database, or WebSocket, and maps the public Model, Claim,
- * and Commit nouns directly to HTTP routes on the server. This is the transport
- * used for server-side agents, workers, and serverless code.
+ * Private HTTP protocol client behind `Ablo({ schema, transport: 'http' })`.
+ * It carries no object pool, local database, or WebSocket and maps Model,
+ * Claim, and Commit protocol shapes directly to server routes. The typed
+ * facade in `httpClient.ts` is the application boundary; this module owns
+ * transport envelopes, watermarks, replay, and route details.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloIdempotencyError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
 import { z } from 'zod';
@@ -11,10 +12,11 @@ import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
-import { toMs, toSeconds } from '../utils/duration.js';
+import { toMs } from '../utils/duration.js';
 import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
 import { mintSession } from './sessionMint.js';
 import { parseIdentityResolveResponse } from '../auth/schemas.js';
+import { staleNotificationSchema } from '../coordination/schema.js';
 /**
  * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
  * than `held` means the lease is no longer ours (a holder cannot be `queued`;
@@ -33,7 +35,8 @@ function heldHeartbeatReply(reply, label) {
 }
 import { assertWriteOptions } from './writeOptionsSchema.js';
 import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCommitEnvelopeSchema, httpCommitEnvelopeRecordId, isHttpCommitReplayExpired, } from '../transactions/httpCommitEnvelope.js';
-/** Default per-request deadline for the stateless HTTP transport. */
+import { resolveDurableWrites } from './durableWrites.js';
+/** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const successfulCommitResponseSchema = z
     .object({
@@ -45,6 +48,7 @@ const successfulCommitResponseSchema = z
     success: z.literal(true),
     lastSyncId: z.number().int().nonnegative().optional(),
     ops: z.number().int().positive(),
+    notifications: z.array(staleNotificationSchema).optional(),
     /** Ids of UPDATE/DELETE targets that matched zero rows (loud 0-row writes). */
     missingIds: z.array(z.string().min(1)).optional(),
 })
@@ -61,8 +65,30 @@ function parseSuccessfulCommitResponse(value, idempotencyKey) {
     }
     return parsed.data;
 }
-const DEFAULT_AGENT_LEASE = '10m';
-export function createProtocolClient(options) {
+/** Decode the HTTP claim DTO into the one public Claim shape. */
+function claimFromModelClaim(claim) {
+    return {
+        object: 'claim',
+        id: claim.id,
+        ...(claim.status ? { status: claim.status } : {}),
+        reason: claim.reason,
+        ...(claim.description ? { description: claim.description } : {}),
+        heldBy: claim.actor,
+        participantKind: claim.participantKind,
+        expiresAt: claim.expiresAt,
+        ...(claim.position !== undefined ? { position: claim.position } : {}),
+        target: {
+            type: claim.target.model,
+            id: claim.target.id,
+            ...(claim.target.path ? { path: claim.target.path } : {}),
+            ...(claim.target.range ? { range: claim.target.range } : {}),
+            ...(claim.target.field ? { field: claim.target.field } : {}),
+            ...(claim.target.meta ? { meta: claim.target.meta } : {}),
+        },
+    };
+}
+/** @internal Constructed only by the typed HTTP facade. */
+export function createHttpTransport(options) {
     const env = readProcessEnv();
     const authInput = { options, env };
     const configuredApiKey = resolveApiKey(authInput);
@@ -123,7 +149,12 @@ export function createProtocolClient(options) {
         url,
         bootstrapBaseUrl: options.bootstrapBaseUrl,
     }).replace(/\/+$/, '');
-    const commitOutbox = options.commitOutbox;
+    const durableWrites = resolveDurableWrites(options);
+    // Internal replay code retains transactional-outbox terminology. The public
+    // constructor exposes the behavior as `durableWrites`.
+    const commitOutbox = durableWrites.store;
+    const durableWriteNamespace = durableWrites.namespace ?? 'http';
+    const legacyCommitOutboxScope = options.commitOutboxScope;
     const httpOutboxPlaneNamespace = canonicalHttpCommitBody({
         apiBaseUrl,
         defaultQuery: Object.entries(options.defaultQuery ?? {}).sort(([a], [b]) => a.localeCompare(b)),
@@ -141,14 +172,19 @@ export function createProtocolClient(options) {
             return null;
         if (httpOutboxScopeNamespace)
             return httpOutboxScopeNamespace;
-        let scope = options.commitOutboxScope;
+        let scope = legacyCommitOutboxScope
+            ? {
+                ...legacyCommitOutboxScope,
+                namespace: durableWriteNamespace,
+            }
+            : undefined;
         if (!scope) {
             const rawIdentity = await requestJson('/auth/identity', { method: 'GET' }, true);
             const identity = parseIdentityResolveResponse(rawIdentity);
             scope = {
                 organizationId: identity.accountScope,
                 participantId: identity.participantId,
-                namespace: 'http',
+                namespace: durableWriteNamespace,
             };
         }
         httpOutboxScopeNamespace = canonicalHttpCommitBody({
@@ -180,11 +216,11 @@ export function createProtocolClient(options) {
             throw error;
         }
     }
-    async function authHeaders() {
+    async function authHeaders(sealedProtocolVersion) {
         const apiKey = await resolveApiKeyValue(configuredApiKey);
         const token = apiKey ?? configuredAuthToken;
         if (!token) {
-            throw new AbloAuthenticationError('Ablo({ apiKey }) requires an API key. Pass `apiKey` or set ABLO_API_KEY.', { code: 'api_key_required' });
+            throw new AbloAuthenticationError('The HTTP client requires an API key. Pass `apiKey` or set ABLO_API_KEY.', { code: 'api_key_required' });
         }
         const headers = {
             'Content-Type': 'application/json',
@@ -201,6 +237,12 @@ export function createProtocolClient(options) {
                 headers[key] = value;
             }
         }
+        // A durable write owns its wire version. Force the sealed value after
+        // caller defaults so a restarted (or rolled-back) SDK cannot rewrite the
+        // protocol identity of a request that may already have reached the server.
+        if (sealedProtocolVersion !== undefined) {
+            headers[PROTOCOL_VERSION_HEADER] = String(sealedProtocolVersion);
+        }
         return headers;
     }
     function endpoint(path) {
@@ -215,8 +257,8 @@ export function createProtocolClient(options) {
     async function requestJson(path, init, skipReady = false) {
         if (!skipReady)
             await ready();
-        const { idempotencyKey, ...requestInit } = init;
-        const headers = await authHeaders();
+        const { idempotencyKey, sealedProtocolVersion, ...requestInit } = init;
+        const headers = await authHeaders(sealedProtocolVersion);
         if (idempotencyKey)
             headers['Idempotency-Key'] = idempotencyKey;
         // Deadline: abort the request after `timeoutMs` so a black-holed server
@@ -340,6 +382,7 @@ export function createProtocolClient(options) {
                 const raw = await requestJson(envelope.request.path, {
                     method: envelope.request.method,
                     idempotencyKey: envelope.idempotencyKey,
+                    sealedProtocolVersion: envelope.protocolVersion,
                     body: envelope.request.body,
                 }, true);
                 const response = parseSuccessfulCommitResponse(raw, envelope.idempotencyKey);
@@ -366,7 +409,7 @@ export function createProtocolClient(options) {
             return null;
         const scopeNamespace = await resolveHttpOutboxScope();
         if (!scopeNamespace) {
-            throw new AbloValidationError('HTTP commit outbox scope was not resolved', {
+            throw new AbloValidationError('HTTP durable-write scope was not resolved', {
                 code: 'write_options_invalid',
             });
         }
@@ -424,6 +467,9 @@ export function createProtocolClient(options) {
                 const raw = await requestJson(input.path, {
                     method: input.method,
                     idempotencyKey: input.idempotencyKey,
+                    ...(durableEnvelope
+                        ? { sealedProtocolVersion: durableEnvelope.protocolVersion }
+                        : {}),
                     body: requestBody,
                 }, true);
                 response = parseSuccessfulCommitResponse(raw, input.idempotencyKey);
@@ -462,32 +508,11 @@ export function createProtocolClient(options) {
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function childClient(authToken, scope) {
-        return createProtocolClient({
-            ...options,
-            apiKey: null,
-            authToken,
-            schema: null,
-            ...(scope
-                ? {
-                    commitOutboxScope: {
-                        ...scope,
-                        namespace: options.commitOutboxScope?.namespace ?? 'http',
-                    },
-                }
-                : { commitOutboxScope: undefined }),
-        });
-    }
     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 id = op.id ?? op.target?.id ?? null;
         return {
             action: op.action,
-            model,
-            id,
+            model: op.model,
+            id: op.id ?? null,
             data: op.data ?? null,
             transactionId: op.transactionId ?? null,
             readAt: op.readAt ?? defaults.readAt ?? null,
@@ -495,20 +520,10 @@ export function createProtocolClient(options) {
         };
     }
     function normalizeCommitOperations(commitOptions) {
-        if (commitOptions.operation && commitOptions.operations) {
-            throw new AbloValidationError('Pass either `operation` or `operations`, not both.', { code: 'commit_operations_ambiguous' });
-        }
-        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' });
+        if (commitOptions.operations.length === 0) {
+            throw new AbloValidationError('Commit requires a non-empty `operations` array.', { code: 'commit_operation_required' });
         }
-        return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
-    }
-    async function listClaims(target) {
-        const state = await listClaimState(target);
-        return state.active;
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
     async function listClaimState(target) {
         const params = new URLSearchParams();
@@ -525,54 +540,6 @@ export function createProtocolClient(options) {
             queue: body.queue ?? [],
         };
     }
-    function delay(ms, signal) {
-        if (signal?.aborted) {
-            return Promise.reject(new AbloConnectionError('Claim wait aborted.', {
-                code: 'claim_wait_aborted',
-                cause: signal.reason,
-            }));
-        }
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(done, ms);
-            function cleanup() {
-                clearTimeout(timeout);
-                signal?.removeEventListener('abort', onAbort);
-            }
-            function done() {
-                cleanup();
-                resolve();
-            }
-            function onAbort() {
-                cleanup();
-                reject(new AbloConnectionError('Claim wait aborted.', {
-                    code: 'claim_wait_aborted',
-                    cause: signal?.reason,
-                }));
-            }
-            signal?.addEventListener('abort', onAbort, { once: true });
-        });
-    }
-    async function waitForNoClaims(target, options) {
-        const startedAt = Date.now();
-        const pollInterval = options?.pollInterval;
-        for (;;) {
-            const claims = await listClaims(target);
-            if (claims.length === 0)
-                return;
-            if (pollInterval == null) {
-                throw new AbloValidationError('Cannot wait for claims over the HTTP client without `pollInterval`. ' +
-                    'Use the schema client for event-driven claim waits, pass `ifClaimed: "return"`, ' +
-                    'or provide an explicit poll interval for this runtime.', { code: 'claim_wait_poll_interval_required' });
-            }
-            if (options?.timeout != null && Date.now() - startedAt >= options.timeout) {
-                throw claimedError(target, claims, 'model_claimed_timeout');
-            }
-            const remaining = options?.timeout == null
-                ? pollInterval
-                : Math.max(0, Math.min(pollInterval, options.timeout - (Date.now() - startedAt)));
-            await delay(remaining, options?.signal);
-        }
-    }
     async function applyClaimedPolicy(target, options, defaultPolicy = 'return') {
         const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
@@ -603,9 +570,6 @@ export function createProtocolClient(options) {
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
             const requestBody = {
-                clientTxId,
-                idempotencyKey: clientTxId,
-                claim: normalizeClaimId(commitOptions.claimRef) ?? claim?.id,
                 operations,
                 reads: commitOptions.reads,
             };
@@ -637,195 +601,15 @@ export function createProtocolClient(options) {
                 id: body.id ?? body.clientTxId,
                 status,
                 lastSyncId: body.lastSyncId,
+                ...(body.notifications && body.notifications.length > 0
+                    ? { notifications: body.notifications }
+                    : {}),
                 ...(body.missingIds && body.missingIds.length > 0
                     ? { missingIds: body.missingIds }
                     : {}),
             };
         },
     };
-    const capabilities = {
-        async create(capabilityOptions) {
-            const ttlSeconds = capabilityOptions.ttlSeconds ?? // eslint-disable-line @typescript-eslint/no-deprecated -- compatibility alias
-                capabilityOptions.leaseSeconds ??
-                toSeconds(capabilityOptions.ttl ?? capabilityOptions.lease ?? DEFAULT_AGENT_LEASE); // eslint-disable-line @typescript-eslint/no-deprecated -- compatibility alias
-            const body = await requestJson('/v1/capabilities', {
-                method: 'POST',
-                body: JSON.stringify({
-                    participantKind: capabilityOptions.participantKind ?? 'agent',
-                    participantId: capabilityOptions.participantId,
-                    syncGroups: capabilityOptions.syncGroups,
-                    operations: capabilityOptions.operations,
-                    ttlSeconds,
-                    label: capabilityOptions.label,
-                    wideScope: capabilityOptions.wideScope,
-                    userMeta: capabilityOptions.userMeta,
-                }),
-            });
-            const id = body.capabilityId ?? body.id;
-            if (!id) {
-                throw new AbloValidationError('Capability create response did not include an id.', { code: 'capability_id_missing' });
-            }
-            return {
-                id,
-                token: body.token,
-                expiresAt: body.expiresAt,
-                organizationId: body.organizationId,
-                scope: body.scope,
-                userMeta: body.userMeta,
-                client: () => childClient(body.token, {
-                    organizationId: body.organizationId,
-                    participantId: body.scope.participantId,
-                }),
-            };
-        },
-        async retrieve(id) {
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'GET' });
-            return {
-                id: body.capabilityId ?? body.id ?? id,
-                organizationId: body.organizationId,
-                participantKind: body.participantKind,
-                participantId: body.participantId,
-                label: body.label,
-                status: body.status,
-                issuedAt: body.issuedAt,
-                expiresAt: body.expiresAt,
-                revokedAt: body.revokedAt,
-                lastUsedAt: body.lastUsedAt,
-                operations: body.operations ?? [],
-                syncGroups: body.syncGroups ?? [],
-            };
-        },
-        async revoke(id) {
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}`, { method: 'DELETE' });
-            return {
-                id: body.capabilityId ?? body.id ?? id,
-                deleted: body.deleted ?? true,
-                activeSessionsClosed: body.activeSessionsClosed,
-            };
-        },
-        async rotate(id, rotateOptions = {}) {
-            const graceSeconds = rotateOptions.graceSeconds ??
-                (rotateOptions.grace !== undefined ? toSeconds(rotateOptions.grace) : undefined);
-            const leaseSeconds = rotateOptions.leaseSeconds ??
-                (rotateOptions.lease !== undefined ? toSeconds(rotateOptions.lease) : undefined);
-            const body = await requestJson(`/v1/capabilities/${encodeURIComponent(id)}/rotate`, {
-                method: 'POST',
-                body: JSON.stringify({
-                    ...(graceSeconds !== undefined ? { graceSeconds } : {}),
-                    ...(leaseSeconds !== undefined ? { ttlSeconds: leaseSeconds } : {}),
-                }),
-            });
-            const newId = body.capabilityId ?? body.id;
-            if (!newId) {
-                throw new AbloValidationError('Capability rotate response did not include an id.', { code: 'capability_id_missing' });
-            }
-            return {
-                id: newId,
-                token: body.token,
-                expiresAt: body.expiresAt,
-                organizationId: body.organizationId,
-                scope: body.scope,
-                rotatedFrom: {
-                    id: body.rotatedFrom.capabilityId ?? body.rotatedFrom.id ?? id,
-                    expiresAt: body.rotatedFrom.expiresAt,
-                },
-                client: () => childClient(body.token, {
-                    organizationId: body.organizationId,
-                    participantId: body.scope.participantId,
-                }),
-            };
-        },
-        mint(options) {
-            return capabilities.create(options);
-        },
-    };
-    const claims = {
-        async create(claimOptions) {
-            const claimId = createClaimId();
-            const body = await requestJson('/v1/claims', {
-                method: 'POST',
-                body: JSON.stringify({
-                    claimId,
-                    target: claimOptions.target,
-                    reason: claimOptions.reason,
-                    ttl: claimOptions.ttl,
-                    queue: claimOptions.queue,
-                }),
-            });
-            // The fair-queue grant is pushed over a WebSocket (`claim_granted`), which
-            // this stateless HTTP client doesn't hold. Returning a handle here would be
-            // a phantom holder — a lease we can't confirm is ours. So a queued response
-            // is surfaced as a typed claimed signal; callers that need to wait in line
-            // use the realtime (WebSocket-backed) `ablo.<model>.claim`.
-            if (body.status === 'queued') {
-                throw new AbloClaimedError(`Target ${claimOptions.target.model}/${claimOptions.target.id} is held; ` +
-                    `queued at position ${body.position ?? 0}. The HTTP client can't await ` +
-                    `the grant (no socket) — use the realtime client to wait in line.`, { code: 'claim_queued' });
-            }
-            const id = body.claim?.id ?? claimId;
-            let released = false;
-            const release = async () => {
-                if (released)
-                    return;
-                released = true;
-                await requestJson(`/v1/claims/${encodeURIComponent(id)}`, { method: 'DELETE' });
-            };
-            // The by-id twin of the model-scoped heartbeat — same reply contract.
-            const heartbeat = async (beatOptions) => {
-                const resolved = resolveHeartbeatOptions(beatOptions);
-                const reply = await requestJson(`/v1/claims/${encodeURIComponent(id)}/heartbeat`, {
-                    method: 'POST',
-                    body: JSON.stringify({
-                        ...(resolved.ttl !== undefined ? { ttl: resolved.ttl } : {}),
-                        ...(resolved.details !== undefined
-                            ? { details: resolved.details }
-                            : {}),
-                    }),
-                });
-                return heldHeartbeatReply(reply, `claim ${id}`);
-            };
-            return {
-                object: 'claim',
-                id,
-                heartbeat,
-                reason: claimOptions.reason,
-                target: {
-                    type: claimOptions.target.model,
-                    id: claimOptions.target.id,
-                    ...(claimOptions.target.field ? { field: claimOptions.target.field } : {}),
-                    ...(claimOptions.target.path ? { path: claimOptions.target.path } : {}),
-                    ...(claimOptions.target.range ? { range: claimOptions.target.range } : {}),
-                    ...(claimOptions.target.meta ? { meta: claimOptions.target.meta } : {}),
-                },
-                release,
-                revoke: () => {
-                    void release().catch(() => { });
-                },
-                [Symbol.asyncDispose]: release,
-            };
-        },
-        list: listClaims,
-        waitFor(target, options) {
-            return waitForNoClaims(target, options);
-        },
-        async heartbeatAll(options) {
-            const reply = await requestJson('/v1/claims/heartbeat', {
-                method: 'POST',
-                body: JSON.stringify(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
-            });
-            return (reply.results ?? []).flatMap((entry) => typeof entry.claimId === 'string' && typeof entry.expiresAt === 'number'
-                ? [
-                    {
-                        claimId: entry.claimId,
-                        expiresAt: entry.expiresAt,
-                        ...(entry.queueDepth !== undefined
-                            ? { queueDepth: entry.queueDepth }
-                            : {}),
-                    },
-                ]
-                : []);
-        },
-    };
     async function listModel(modelName, options) {
         const params = new URLSearchParams();
         if (options?.limit !== undefined)
@@ -906,7 +690,6 @@ export function createProtocolClient(options) {
             : undefined;
         const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
-            idempotencyKey: clientTxId,
             claim: normalizeClaimId(options?.claimRef) ?? claimHandle?.id,
             onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
             readAt,
@@ -1064,11 +847,14 @@ export function createProtocolClient(options) {
             state: async (params) => {
                 const res = await claimsForEntity(params);
                 const first = res.claims?.[0];
-                return first ?? null;
+                return first ? claimFromModelClaim(first) : null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: res.queue ?? [] };
+                return {
+                    object: 'list',
+                    data: (res.queue ?? []).map(claimFromModelClaim),
+                };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {
@@ -1184,8 +970,6 @@ export function createProtocolClient(options) {
         }),
         async dispose() { },
         async purge() { },
-        capabilities,
-        claims,
         commits,
         model,
         sessions: {
@@ -1201,6 +985,9 @@ export function createProtocolClient(options) {
                     apiKey,
                     baseUrl: apiBaseUrl,
                     ...(options.fetch ? { fetch: options.fetch } : {}),
+                    ...(options.modelTypenames
+                        ? { modelTypenames: options.modelTypenames }
+                        : {}),
                 });
             },
         },

package/dist/client/options.d.ts

@@ -1,12 +1,13 @@
 /**
  * The option types for the {@link Ablo} client: the public {@link AbloOptions}
- * bag callers pass, and the fuller {@link InternalAbloOptions} construction
- * surface. This module holds only types and has no runtime imports.
+ * bag callers pass, and the fuller monorepo-only {@link InternalAbloOptions}
+ * construction surface exposed through `@abloatai/ablo/core`.
+ * This module holds only types and has no runtime imports.
  */
 import type { Schema, SchemaRecord } from '../schema/schema.js';
 import type { SyncEngineConfig, SyncLogger, MutationExecutor, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider } from '../interfaces/index.js';
 import type { AbloPersistence } from './persistence.js';
-import type { CommitOutboxStore } from '../transactions/commitOutboxStore.js';
+import type { DurableWriteStore, DurableWritesConfig } from '../transactions/durableWriteStore.js';
 import type { CommitOutboxScope } from '../transactions/commitEnvelope.js';
 /**
  * An async function that resolves an apiKey at request time. Use it for credential
@@ -111,16 +112,38 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     persistence?: AbloPersistence;
     /**
-     * Durable commit-envelope storage for server-side agents and workers.
-     * The stateful browser client uses its strict IndexedDB transaction store;
-     * the stateless HTTP client has no implicit filesystem and therefore needs a
-     * workflow-, SQLite-, or filesystem-backed implementation to survive a
-     * process restart. One store may serve several actors because every record
-     * is checked against its authenticated scope before replay.
+     * Makes `create`, `update`, and `delete` survive process restarts and
+     * ambiguous network responses. Server-side agents and workers inject a
+     * workflow-, SQLite-, or filesystem-backed store; authenticated identity is
+     * used to fence replay to the actor that originally made the write.
+     *
+     * Most clients leave this unset and use Ablo's default in-memory cache.
+     * `durableWrites` is independent of that cache: it is the optional outbound
+     * write journal for workers that must recover automatically after a crash.
+     * Browsers only use IndexedDB when `persistence: 'indexeddb'` is explicitly
+     * enabled for offline/reload behavior.
+     *
+     * @example
+     * ```ts
+     * Ablo({
+     *   schema,
+     *   apiKey,
+     *   durableWrites: { store, namespace: 'agent-worker' },
+     * })
+     * ```
      */
-    commitOutbox?: CommitOutboxStore;
+    durableWrites?: DurableWritesConfig;
     /**
-     * Stable actor/server scope for an injected HTTP {@link commitOutbox}.
+     * @deprecated Use `durableWrites: { store, namespace }`.
+     * Retained as a compatibility alias through the next major release.
+     */
+    commitOutbox?: DurableWriteStore;
+    /**
+     * @deprecated Actor identity is resolved from authentication. Use
+     * `durableWrites.namespace` only when shared storage needs separate workflow
+     * or deployment lanes.
+     *
+     * Stable actor/server scope for an injected HTTP `commitOutbox`.
      * Omit it to resolve `organizationId` and `participantId` from the authenticated
      * `/auth/identity` endpoint. Supplying it avoids that one setup request in
      * trusted worker environments; `namespace` distinguishes deployments or
@@ -137,8 +160,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * {@link AbloHttpClient}, so stateful-only capabilities such as `get`, `getAll`,
      * and `onChange` become compile errors instead of runtime gaps.
      *
-     * Note: session minting through `sessions.create` runs on the default WebSocket
-     * client, not the HTTP client.
+     * Session minting through `sessions.create` is available on both transports.
      *
      * @default 'websocket'
      */
@@ -241,9 +263,9 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /**
      * TypeScript schema defined with `defineSchema()`.
      *
-     * The root `Ablo(...)` client is schema-first so consumers get typed
-     * model clients such as `ablo.weatherReports.update(...)`. Omit `schema`
-     * only for the advanced Model / Claim / Commit client.
+     * Required on every public `Ablo(...)` construction. It produces typed model
+     * clients such as `ablo.weatherReports.update(...)`; schema-agnostic routing
+     * exists only inside the private HTTP transport.
      */
     schema: Schema<S>;
     /**
@@ -299,9 +321,11 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * reload-surviving local cache in a browser.
      */
     persistence?: AbloPersistence;
-    /** Internal mirror of {@link AbloOptions.commitOutbox}. */
-    commitOutbox?: CommitOutboxStore;
-    /** Internal mirror of {@link AbloOptions.commitOutboxScope}. */
+    /** Internal mirror of {@link AbloOptions.durableWrites}. */
+    durableWrites?: DurableWritesConfig;
+    /** @deprecated Internal mirror of {@link AbloOptions.commitOutbox}. */
+    commitOutbox?: DurableWriteStore;
+    /** @deprecated Internal mirror of {@link AbloOptions.commitOutboxScope}. */
     commitOutboxScope?: CommitOutboxScope;
     /** @deprecated Use `persistence: 'indexeddb'` for durable browser storage. */
     offline?: boolean;

package/dist/client/options.js

@@ -1,6 +1,7 @@
 /**
  * The option types for the {@link Ablo} client: the public {@link AbloOptions}
- * bag callers pass, and the fuller {@link InternalAbloOptions} construction
- * surface. This module holds only types and has no runtime imports.
+ * bag callers pass, and the fuller monorepo-only {@link InternalAbloOptions}
+ * construction surface exposed through `@abloatai/ablo/core`.
+ * This module holds only types and has no runtime imports.
  */
 export {};