@abloatai/ablo 0.27.0 → 0.29.0

package/dist/client/modelRegistration.js

@@ -192,8 +192,19 @@ function isZodObject(schema) {
 }
 /** Create a Model subclass for a schema-defined model */
 function createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, lazyObservable = false) {
+    // Names `toReactiveSnapshot` materializes onto plain snapshots: every
+    // `${field}Json` getter plus every schema-declared computed. Without this,
+    // snapshot rows silently drop getters that the schema's inferred row type
+    // declares — reads like `snapshot.settingsObject` would be `undefined`.
+    const derivedGetterNames = Object.freeze([
+        ...jsonSubFields.map(({ fieldName }) => `${fieldName}Json`),
+        ...Object.keys(computed ?? {}),
+    ]);
     const ModelClass = class extends Model {
         _modelName = modelName;
+        getDerivedGetterNames() {
+            return derivedGetterNames;
+        }
         constructor(data) {
             super(data);
             // Suppress change tracking during initial hydration. `makeObservable()`

package/dist/client/options.d.ts

@@ -1,11 +1,14 @@
 /**
  * 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 { 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
  * rotation — read from a vault, refresh from session storage, or pull from an
@@ -108,6 +111,45 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @default 'memory'
      */
     persistence?: AbloPersistence;
+    /**
+     * 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' },
+     * })
+     * ```
+     */
+    durableWrites?: DurableWritesConfig;
+    /**
+     * @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
+     * workflow lanes that share the same actor identity.
+     */
+    commitOutboxScope?: CommitOutboxScope;
     /**
      * Selects the transport. `'websocket'` (the default) is the live client: a
      * persistent socket, a local synced cache, and `onChange` subscriptions. `'http'`
@@ -118,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'
      */
@@ -222,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>;
     /**
@@ -280,6 +321,12 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * reload-surviving local cache in a browser.
      */
     persistence?: AbloPersistence;
+    /** 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 {};

package/dist/client/resourceTypes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The shared resource types of the client: {@link ModelRead}, {@link ModelClient},
+ * Shared resource types for the typed clients and private HTTP transport.
  * the commit and claim shapes, the session-mint params and resource, and the
  * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
  * imports.
@@ -10,8 +10,7 @@ export type { ModelTarget, ModelClaim };
 import type { SchemaRecord } from '../schema/schema.js';
 import type { SyncGroupInput } from '../schema/roles.js';
 import type { Claim, ClaimStream, ClaimWaitOptions, Duration, HeldClaim } from '../types/streams.js';
-import type { ModelUpdater, ContentionOptions } from './functionalUpdate.js';
-import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, ServerReadOptions } from './createModelProxy.js';
+import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod } from './createModelProxy.js';
 /**
  * The operations available on each model in the sync engine:
  *   `retrieve({ id })` — an async single-row server read
@@ -23,24 +22,13 @@ import type { ClaimOptions, ClaimParams, ClaimReadApi, AwaitedClaimMethod, Serve
 export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './createModelProxy.js';
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
-export interface ModelRead<T = Record<string, unknown>> {
-    /**
-     * The row, or `undefined` when no row matched the id (or it's outside the
-     * caller's scope). A miss is data-absence, not an error — `retrieve` never
-     * throws "not found", mirroring the WebSocket client's `T | undefined`.
-     * Branch on it: `const deal = (await ablo.deals.retrieve({ id })).data; if (!deal) …`.
-     */
-    readonly data: T | undefined;
-    readonly stamp: number;
-    readonly claims: readonly ModelClaim[];
-}
 export type IfClaimedPolicy = 'return' | 'fail';
 export interface ClaimedOptions {
     /**
-     * What to do when another participant has claimed the target: `return`
-     * includes active claim metadata in the response; `fail` throws
-     * `AbloClaimedError`. Waiting for a claim to clear is a claim-side concern —
-     * take `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
+     * What to do when another participant has claimed the target: `return` lets
+     * the read proceed; `fail` throws `AbloClaimedError`. Inspect claim state via
+     * `ablo.<model>.claim.state({ id })`. Waiting is a claim-side concern — take
+     * `ablo.<model>.claim({ id })` (it queues fairly); reads never block.
      */
     readonly ifClaimed?: IfClaimedPolicy;
 }
@@ -73,8 +61,7 @@ export interface ClaimCreateOptions {
 export interface CommitOperationInput {
     readonly action: ModelOperationAction;
     /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-    readonly model?: string;
-    readonly target?: ModelTarget;
+    readonly model: string;
     readonly id?: string | null;
     readonly data?: Record<string, unknown> | null;
     readonly transactionId?: string | null;
@@ -82,9 +69,6 @@ export interface CommitOperationInput {
     readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
 }
 export interface CommitCreateOptions {
-    readonly claimRef?: string | {
-        readonly id: string;
-    } | null;
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'overwrite' | 'notify' | null;
@@ -97,8 +81,8 @@ export interface CommitCreateOptions {
      * Explicit `readAt`/`onStale` on the options win.
      */
     readonly claim?: Claim | null;
-    readonly operation?: CommitOperationInput;
-    readonly operations?: readonly CommitOperationInput[];
+    /** One atomic batch. Use a one-element array for a single operation. */
+    readonly operations: readonly CommitOperationInput[];
     readonly wait?: CommitWait;
     /**
      * Batch-level read dependencies — the "did anything I looked at change?" guard.
@@ -167,66 +151,6 @@ export interface ModelMutationOptions extends ClaimedOptions {
 export type HttpClaimApi<T = Record<string, unknown>> = ((params: ClaimParams<T>) => Promise<HeldClaim<T>>) & {
     [K in keyof ClaimReadApi<T>]: AwaitedClaimMethod<ClaimReadApi<T>[K]>;
 };
-export interface ModelClient<T = Record<string, unknown>> {
-    /**
-     * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
-     * row is on `.data`, alongside the `.stamp` watermark (for stale-context
-     * guards on the following write) and any active `.claims`. A stateless HTTP
-     * client can't synthesize the watermark from a local snapshot, so the
-     * envelope is load-bearing here (the WebSocket client's `retrieve` returns
-     * `T | undefined` because it reads from its local cache).
-     *
-     * ```ts
-     * const deal = await ablo.deals.retrieve({ id });
-     * deal.data?.recommendation;   // ← the row is on .data
-     * deal.stamp;                  // watermark — pass to the next write's readAt
-     * ```
-     */
-    retrieve(params: ModelReadOptions & {
-        readonly id: string;
-    }): Promise<ModelRead<T>>;
-    /**
-     * Collection read over HTTP (server round-trip). Equality `where`, `orderBy`,
-     * `limit`. Present on the stateless protocol client; the store-backed
-     * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
-     */
-    list?(options?: ServerReadOptions<T>): Promise<T[]>;
-    /**
-     * Creates a row and returns the confirmed server row, including framework
-     * defaults such as `createdAt` and `createdBy`. Matches the stateful client's
-     * `create`. Passing an id that already exists is idempotent: the existing row is
-     * returned, not the input.
-     */
-    create(params: ModelMutationOptions & {
-        readonly data: Record<string, unknown>;
-        readonly id?: string | null;
-    }): Promise<T>;
-    update(params: ModelMutationOptions & {
-        readonly id: string;
-        readonly data: Record<string, unknown>;
-    }): Promise<CommitReceipt>;
-    /**
-     * Update under contention with a function of the latest state —
-     * `update(id, current => next)`, the `setState(prev => next)` of the data
-     * layer. The SDK reads the freshest row, runs your updater, writes it as a
-     * compare-and-swap against the row's watermark, and re-reads + re-runs on any
-     * concurrent write. No claim, no identity, no conflict codes surface: the
-     * write either lands or throws {@link AbloContentionError} once its reconcile
-     * budget is spent. Return `null`/`undefined` from the updater to skip the
-     * write (resolves to `undefined`).
-     */
-    update(id: string, updater: ModelUpdater<T>, options?: ContentionOptions): Promise<CommitReceipt | undefined>;
-    delete(params: ModelMutationOptions & {
-        readonly id: string;
-    }): Promise<CommitReceipt>;
-    /**
-     * Durable lease + FIFO wait-line over HTTP — coordination without a socket.
-     * Present on the stateless protocol client (`Ablo({ schema: null })` /
-     * `createAbloHttpClient`); the store-backed `.model(name)` accessor omits it
-     * (the typed `ablo.<model>.claim` proxy is the full reactive namespace there).
-     */
-    claim?: HttpClaimApi<T>;
-}
 /** A single data operation a scoped **agent** session may perform on a model. */
 export type SessionOperation = 'read' | 'create' | 'update' | 'delete';
 /** Parameters for minting an end-user session — full data authority within the

package/dist/client/resourceTypes.js

@@ -1,5 +1,5 @@
 /**
- * The shared resource types of the client: {@link ModelRead}, {@link ModelClient},
+ * Shared resource types for the typed clients and private HTTP transport.
  * the commit and claim shapes, the session-mint params and resource, and the
  * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
  * imports.

package/dist/client/sessionMint.d.ts

@@ -10,14 +10,13 @@ export interface MintSessionContext {
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
     /**
-     * Maps each schema key to its wire type name. Only the schema-aware client
-     * supplies this. A capability is scoped by the lowercased type name the
-     * server checks, but `can` is keyed by schema key — so
+     * Maps each schema key to its wire type name. Every public client supplies
+     * this; it stays optional only for isolated private-transport use. A
+     * capability is scoped by the lowercased type name the server checks, but
+     * `can` is keyed by schema key — so
      * `can: { documents: ['update'] }` on a model whose type name is overridden
      * to `Document` must mint `document.update`, not `documents.update`, or the
-     * server denies the write with `capability_scope_denied`. The schemaless
-     * client omits this map, because there the `can` key is already the wire
-     * token and needs no translation.
+     * server denies the write with `capability_scope_denied`.
      */
     readonly modelTypenames?: Readonly<Record<string, string>>;
 }

package/dist/client/sessionMint.js

@@ -1,7 +1,7 @@
 /**
  * Mints a session token. This is the single implementation behind
- * `sessions.create`, shared by the schema-aware client and the schemaless HTTP
- * client so the two never disagree on how a token is produced.
+ * `sessions.create`, shared by the WebSocket and HTTP clients so the two never
+ * disagree on how a token is produced.
  *
  * Minting is a plain control-plane HTTP call — no socket, no synced data. A
  * backend holding a secret key (`sk_`) exchanges it for a short-lived, scoped
@@ -60,9 +60,8 @@ export async function mintSession(params, ctx) {
     }
     const operations = Object.entries(params.can).flatMap(([model, ops]) => {
         // Translate the schema key the developer used in `can` into the wire type
-        // name the server checks — see `modelTypenames` above. Falls back to the
-        // key itself when no map is supplied (the schemaless client) or the key is
-        // absent from it.
+        // name the server checks — see `modelTypenames` above. The key fallback is
+        // private transport tolerance; every public client supplies the schema map.
         const ns = ctx.modelTypenames?.[model] ?? model;
         return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
     });

package/dist/client/validateAbloOptions.js

@@ -17,9 +17,9 @@ export function validateAbloOptions(input) {
         return new AbloValidationError('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
             `Ablo({ baseURL: 'wss://api.abloatai.com', schema, user })`, { code: 'base_url_missing' });
     }
-    // Schema is optional for the model-first API:
-    //   Ablo({ apiKey }).model('clauses').retrieve(...)
-    // Passing a schema only enables typed model sugar (`ablo.weatherReports.update(...)`).
+    if (!options.schema?.models) {
+        return new AbloValidationError('Ablo: `schema` is required. Define it once and access models as `ablo.<model>`.', { code: 'invalid_options', param: 'schema' });
+    }
     if (!configuredApiKey &&
         !configuredAuthToken &&
         !options.capabilityToken &&

package/dist/client/wsMutationExecutor.d.ts

@@ -17,8 +17,9 @@ import type { MutationExecutor, MutationOperation } from '../interfaces/index.js
  * the ready socket.
  *
  * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
- * retrying a call with the same key is safe; otherwise the executor generates
- * one.
+ * retrying a call with the same key is safe. TransactionQueue always supplies
+ * this key before its first attempt and owns reuse across retries. The fallback
+ * generation below exists only for direct, one-shot executor consumers.
  */
 export declare function createDefaultMutationExecutor(getWs: () => {
     sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null) => Promise<{

package/dist/client/wsMutationExecutor.js

@@ -17,8 +17,9 @@ import { AbloError, AbloConnectionError } from '../errors.js';
  * the ready socket.
  *
  * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
- * retrying a call with the same key is safe; otherwise the executor generates
- * one.
+ * retrying a call with the same key is safe. TransactionQueue always supplies
+ * this key before its first attempt and owns reuse across retries. The fallback
+ * generation below exists only for direct, one-shot executor consumers.
  */
 export function createDefaultMutationExecutor(getWs) {
     async function commit(operations, options) {

package/dist/coordination/schema.d.ts

@@ -157,6 +157,9 @@ export type StaleNotification = z.infer<typeof staleNotificationSchema>;
  *   • Group — `{ group, readAt }`: did anything in this sync group change?
  *             `group` is a sync-group key such as `deck:abc` or `slide:s1`, the
  *             same unit a participant watches and claims.
+ *
+ * See `packages/sync-engine/docs/concurrency-convention.md` (§4) for the
+ * governing convention and the receive → reconcile loop.
  */
 export declare const readDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
     model: z.ZodString;
@@ -304,6 +307,33 @@ export declare const claimRejectionSchema: z.ZodObject<{
     policyReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ClaimRejection = z.infer<typeof claimRejectionSchema>;
+/**
+ * The point-to-point notification sent to a holder whose lease ended without
+ * a successful commit. This remains a wire-shaped target because it arrives
+ * directly from the WebSocket; the schema is the single validation boundary
+ * before the event reaches public `claims.onLost` listeners.
+ */
+export declare const claimLostSchema: z.ZodObject<{
+    claimId: z.ZodString;
+    reason: z.ZodEnum<{
+        expired: "expired";
+        preempted: "preempted";
+    }>;
+    target: z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ClaimLost = z.infer<typeof claimLostSchema>;
 /**
  * What a {@link ModelClaim} points at — the target locator as SDK callers see
  * it, keyed by `model` and `id` rather than the wire schema's `entityType` and

package/dist/coordination/schema.js

@@ -165,6 +165,9 @@ export const staleNotificationSchema = z.object({
  *   • Group — `{ group, readAt }`: did anything in this sync group change?
  *             `group` is a sync-group key such as `deck:abc` or `slide:s1`, the
  *             same unit a participant watches and claims.
+ *
+ * See `packages/sync-engine/docs/concurrency-convention.md` (§4) for the
+ * governing convention and the receive → reconcile loop.
  */
 export const readDependencySchema = z.union([
     z.object({
@@ -249,6 +252,17 @@ export const claimRejectionSchema = z.object({
     heldByClaim: wireClaimSummarySchema.optional(),
     policyReason: z.string().optional(),
 });
+/**
+ * The point-to-point notification sent to a holder whose lease ended without
+ * a successful commit. This remains a wire-shaped target because it arrives
+ * directly from the WebSocket; the schema is the single validation boundary
+ * before the event reaches public `claims.onLost` listeners.
+ */
+export const claimLostSchema = z.object({
+    claimId: z.string(),
+    reason: z.enum(['expired', 'preempted']),
+    target: targetRefSchema,
+});
 /**
  * What a {@link ModelClaim} points at — the target locator as SDK callers see
  * it, keyed by `model` and `id` rather than the wire schema's `entityType` and

package/dist/core/StoreManager.d.ts

@@ -21,6 +21,8 @@ import { LoadStrategy } from '../types/index.js';
  */
 export declare class StoreManager {
     private stores;
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    private transactionStore;
     private syncactionStore;
     private db;
     private isInitialized;

package/dist/core/StoreManager.js

@@ -22,6 +22,8 @@ import { AbloValidationError } from '../errors.js';
  */
 export class StoreManager {
     stores = new Map();
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    transactionStore = null;
     syncactionStore = null;
     db = null;
     isInitialized = false;
@@ -46,6 +48,12 @@ export class StoreManager {
         for (const modelName of allModels) {
             await this.createStoreForModel(modelName);
         }
+        // Special stores are created during the IDB upgrade, but unlike model
+        // stores they have no registry metadata and therefore need an explicit
+        // runtime wrapper. Outbox acknowledgement must mean disk-backed, so this
+        // store opts into strict durability rather than the cache stores' relaxed
+        // mode.
+        this.transactionStore = new ObjectStore(this.db, '__transactions', '__transactions', { loadStrategy: LoadStrategy.instant }, 'strict');
         // Initialize SyncactionStore
         this.syncactionStore = new SyncActionStore(this.db);
         await this.syncactionStore.initialize();
@@ -142,6 +150,9 @@ export class StoreManager {
      * Get ObjectStore for a model
      */
     getStore(modelName) {
+        if (modelName === '__transactions') {
+            return this.transactionStore ?? undefined;
+        }
         return this.stores.get(modelName);
     }
     /**
@@ -295,6 +306,7 @@ export class StoreManager {
         for (const store of this.stores.values()) {
             store.markAsClosing();
         }
+        this.transactionStore?.markAsClosing();
         // SyncActionStore is a standalone store that does not extend ObjectStore
         // and has no markAsClosing equivalent, so it is intentionally skipped here.
         // If closing-state coordination is ever needed for sync actions, add it

package/dist/core/index.d.ts

@@ -21,7 +21,7 @@ export { Model } from '../Model.js';
 export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyReferenceCollection.js';
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
-export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
+export { computeFKDepthPriority } from '../client/Ablo.js';
 export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
 export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';

package/dist/errorCodes.js

@@ -112,7 +112,7 @@ export const ERROR_CODES = {
     jwt_invalid: wire('auth', 401, false, "The bearer JWT failed validation for a reason the server could not classify further. Check the token's issuer, signature, audience, and expiry."),
     jwt_malformed: wire('auth', 401, false, 'The bearer token is not a well-formed JWT and could not be decoded. Check that the full, unmodified token was sent.'),
     jwt_missing_issuer: wire('auth', 401, false, 'The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer.'),
-    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Check the token's issuer claim, or register the issuer with your deployment before retrying."),
     jwt_signature_invalid: wire('auth', 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
     jwt_audience_mismatch: wire('auth', 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
     jwt_missing_subject: wire('auth', 401, false, 'The bearer JWT has no `sub` (subject) claim to identify the user.'),
@@ -161,7 +161,11 @@ export const ERROR_CODES = {
     model_claim_not_configured: client('claim', 'Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically — there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path).'),
     model_watch_not_configured: client('claim', 'watch() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'),
     // ── stale context / idempotency (409) ──────────────────────────────
-    stale_context: wire('conflict', 409, true, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
+    // Not retryable at the transport: the rejected request carries its frozen
+    // `readAt`, so resending the identical payload can never succeed. Recovery
+    // is a caller-level re-read that produces a NEW request with a fresh
+    // watermark — the same shape as `claim_conflict`.
+    stale_context: wire('conflict', 409, false, "The row changed after you read it — the write's `readAt` watermark is older than the current row version. Re-read the row and retry."),
     // Raised by the functional `update(id, current => next)` form once its
     // internal reconcile budget is exhausted, because the row stayed continuously
     // contended. The SDK has already retried; the caller decides whether to back

package/dist/errors.d.ts

@@ -131,10 +131,10 @@ export declare class AbloValidationError extends AbloError {
 }
 /**
  * An update or delete addressed a row that does not exist, or lies outside the
- * caller's organization (HTTP 404). Such targets are reported on
- * {@link CommitReceipt.missingIds}, and the typed resource methods raise this
- * error rather than returning a successful receipt for a write that quietly
- * matched zero rows. The absent ids are carried on {@link missingIds}.
+ * caller's organization (HTTP 404). Raw commit responses may report those
+ * targets as `missingIds`; typed model methods raise this error instead of
+ * returning a successful result for a write that quietly matched zero rows.
+ * The absent ids are carried on {@link missingIds}.
  */
 export declare class AbloNotFoundError extends AbloError {
     readonly type: "AbloNotFoundError";
@@ -292,42 +292,6 @@ export interface RequiredCapability {
      *  capability. */
     readonly nonce?: string;
 }
-/**
- * The receipt returned for every commit, whether it succeeded or was rejected,
- * and regardless of how it was sent — the WebSocket `mutation_result` payload,
- * the HTTP `/v1/commits` response body, and an agent job's result all use this
- * one shape. It is a correlation receipt, carrying the ids and outcome needed to
- * reconcile a commit rather than a cryptographic proof.
- */
-export interface CommitReceipt {
-    readonly object: 'commit_receipt';
-    /** Client-issued idempotency handle. Echoed verbatim. */
-    readonly clientTxId: string;
-    /** Server-issued opaque commit id — typically `String(lastSyncId)`. */
-    readonly serverTxId: string;
-    /** A convenience boolean, equal to `status === 'confirmed'`. */
-    readonly success: boolean;
-    /** `'confirmed'` on apply, `'rejected'` on any failure. */
-    readonly status: 'confirmed' | 'rejected';
-    /** Last syncId visible after this commit (or high-water mark on
-     *  rejection). */
-    readonly lastSyncId?: number;
-    /** Number of operations metered. Reported on both success and
-     *  rejection so quota systems see attempted work. */
-    readonly ops?: number;
-    /** Ids of update or delete targets that matched no row. Present and non-empty
-     *  only when a write missed; the typed resource methods raise
-     *  {@link AbloNotFoundError} from it. */
-    readonly missingIds?: readonly string[];
-    /** Present on rejection. When set, `requiredCapability` carries the structured
-     *  hint describing what would let the request succeed on retry. */
-    readonly error?: {
-        readonly code: string;
-        readonly message: string;
-        readonly field?: string;
-        readonly requiredCapability?: RequiredCapability;
-    };
-}
 /**
  * A scoped credential was denied, either because the key is unknown, revoked, or
  * expired (`capability_invalid`), or because the connection's scope does not

package/dist/errors.js

@@ -150,10 +150,10 @@ export class AbloValidationError extends AbloError {
 }
 /**
  * An update or delete addressed a row that does not exist, or lies outside the
- * caller's organization (HTTP 404). Such targets are reported on
- * {@link CommitReceipt.missingIds}, and the typed resource methods raise this
- * error rather than returning a successful receipt for a write that quietly
- * matched zero rows. The absent ids are carried on {@link missingIds}.
+ * caller's organization (HTTP 404). Raw commit responses may report those
+ * targets as `missingIds`; typed model methods raise this error instead of
+ * returning a successful result for a write that quietly matched zero rows.
+ * The absent ids are carried on {@link missingIds}.
  */
 export class AbloNotFoundError extends AbloError {
     type = 'AbloNotFoundError';
@@ -442,7 +442,7 @@ const ErrorFieldSchema = z
 const ErrorBodyShapeSchema = z
     .object({
     /** The `error` field may be a flat code string, as some endpoints return,
-     *  or a nested error object, as a {@link CommitReceipt} carries. */
+     *  or a nested error object, as commit endpoints return on rejection. */
     error: ErrorFieldSchema,
     code: OptionalWireStringSchema,
     reason: OptionalWireStringSchema,