@abloatai/ablo 0.28.0 → 0.29.0

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/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/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/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,

package/dist/index.d.ts

@@ -14,9 +14,9 @@
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` returns typed model clients. `Ablo({ apiKey })`
- * returns the stateless HTTP model and commit client, which suits agents, MCP
- * route handlers, and custom runtimes.
+ * `Ablo({ schema, apiKey })` returns typed model clients. Server-side agents,
+ * MCP route handlers, and workers select `transport: 'http'`; both transports
+ * keep the same `ablo.<model>` application surface.
  *
  * The whole package reaches you through one name: `Ablo` is at once a factory
  * function, a type, and a namespace. You call model clients with dot access on
@@ -45,7 +45,7 @@
  *
  * A handful of exports are for advanced use and are marked "Advanced" at their
  * declaration below, each with the one situation it is for:
- *   • `dataSource` / `abloSource`  — when your own database stays canonical.
+ *   • `dataSource`                 — when your own database stays canonical.
  *   • `defaultPolicy`              — when you customize conflict resolution.
  *   • `defineMutators` / `createTransaction` — when you write custom mutators.
  * If you don't recognize one of these, you don't need it.
@@ -54,12 +54,18 @@ export { Ablo } from './client/Ablo.js';
 export type { MutationExecutor } from './interfaces/index.js';
 export type { ModelUpdater, ContentionOptions } from './client/functionalUpdate.js';
 export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
-export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
 export type { AbloReads } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ClaimHeartbeat, ClaimHeartbeatOptions, HeldClaim, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, } from './client/Ablo.js';
+/**
+ * @deprecated Use `Ablo.Claim.Held`. This compatibility export remains until
+ * the next major release because it was explicitly documented in 0.20.1.
+ */
+export type { HeldClaim } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
+export { durableWritesConfigSchema, durableWriteStoreSchema, pendingWriteSchema, } from './transactions/durableWriteStore.js';
+export type { DurableWritesConfig, DurableWriteStore, PendingWrite, } from './transactions/durableWriteStore.js';
 export type { CommitOutboxRecord, CommitOutboxStore, } from './transactions/commitOutboxStore.js';
 export { durableCommitEnvelopeSchema, } from './transactions/commitEnvelope.js';
 export type { CommitOutboxScope, DurableCommitEnvelope, } from './transactions/commitEnvelope.js';
@@ -67,11 +73,11 @@ export { durableHttpCommitEnvelopeSchema, } from './transactions/httpCommitEnvel
 export type { DurableHttpCommitEnvelope, } from './transactions/httpCommitEnvelope.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
-export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { dataSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './policy/index.js';
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, AbloContentionError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
-export type { CommitReceipt, RequiredCapability } from './errors.js';
+export type { RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
 export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
 export type { ErrorEnvelope } from './wire/errorEnvelope.js';

package/dist/index.js

@@ -14,9 +14,9 @@
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` returns typed model clients. `Ablo({ apiKey })`
- * returns the stateless HTTP model and commit client, which suits agents, MCP
- * route handlers, and custom runtimes.
+ * `Ablo({ schema, apiKey })` returns typed model clients. Server-side agents,
+ * MCP route handlers, and workers select `transport: 'http'`; both transports
+ * keep the same `ablo.<model>` application surface.
  *
  * The whole package reaches you through one name: `Ablo` is at once a factory
  * function, a type, and a namespace. You call model clients with dot access on
@@ -45,7 +45,7 @@
  *
  * A handful of exports are for advanced use and are marked "Advanced" at their
  * declaration below, each with the one situation it is for:
- *   • `dataSource` / `abloSource`  — when your own database stays canonical.
+ *   • `dataSource`                 — when your own database stays canonical.
  *   • `defaultPolicy`              — when you customize conflict resolution.
  *   • `defineMutators` / `createTransaction` — when you write custom mutators.
  * If you don't recognize one of these, you don't need it.
@@ -63,6 +63,8 @@ export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
 // `AbloHttpClient` type, which is the return type of that call.
 export {} from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
+export { durableWritesConfigSchema, durableWriteStoreSchema, pendingWriteSchema, } from './transactions/durableWriteStore.js';
+/* eslint-enable @typescript-eslint/no-deprecated */
 export { durableCommitEnvelopeSchema, } from './transactions/commitEnvelope.js';
 export { durableHttpCommitEnvelopeSchema, } from './transactions/httpCommitEnvelope.js';
 // Participant types live under `Ablo.Participant.*` —
@@ -76,7 +78,7 @@ export default Ablo;
 // database. The default is Ablo-managed storage; reach for this only when you
 // have deliberately chosen to keep your database canonical. The matching types
 // live under `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
-export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { dataSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 // Serves the Data Source `commit`, `load`, and `list` operations over an
 // outbound WebSocket, so a database with no public inbound URL (running on a
 // developer's machine or inside a locked-down network) can still be reached by

package/dist/interfaces/index.d.ts

@@ -230,6 +230,9 @@ export interface MutationOptions {
      * checks that none of them moved since their `readAt` and applies the entry's
      * `onStale` behavior to the whole batch. This is distinct from the per-operation
      * `readAt`, which guards only the row being written.
+     *
+     * See `packages/sync-engine/docs/concurrency-convention.md` (§3 the two
+     * footprints, §4 the read-set) for the governing convention.
      */
     reads?: ReadDependency[] | null;
 }

package/dist/mutators/defineMutators.d.ts

@@ -13,6 +13,14 @@
  */
 import type { Schema } from '../schema/schema.js';
 import type { Transaction } from './Transaction.js';
+import type { ResolveSchema } from '../types/global.js';
+/**
+ * `ResolveSchema` narrowed to satisfy the `Schema` bound — mirrors
+ * {@link Ablo.RegisteredSchema}. When nothing is registered, `ResolveSchema`
+ * is a loose `{ models }` shape that doesn't extend `Schema`, so we fall back
+ * to `Schema` to keep the mutator tree typed rather than collapsing.
+ */
+type RegisteredSchema = ResolveSchema extends Schema ? ResolveSchema : Schema;
 /**
  * The signature of a single custom mutator. The engine supplies `tx`; you control
  * `args`, in whatever shape you like, and the resolved return value. `TArgs` and
@@ -40,3 +48,13 @@ export type MutatorDefs<S extends Schema> = {
  * work here; the function exists purely as a place for type inference to anchor.
  */
 export declare function defineMutators<S extends Schema, const M extends MutatorDefs<S>>(_schema: S, mutators: M): M;
+/**
+ * Register-anchored overload: omit the schema value and the tree is typed
+ * against `ResolveSchema` (this app's registered schema). Shared product code
+ * used across apps that bind different schemas should use this form — it moves
+ * with each app's `Register` instead of pinning one concrete schema, so the
+ * mutator tree stays assignable at every consumer (which reads the same
+ * `Register`). See docs/plans/per-product-schema-projections.md.
+ */
+export declare function defineMutators<const M extends MutatorDefs<RegisteredSchema>>(mutators: M): M;
+export {};

package/dist/mutators/defineMutators.js

@@ -11,12 +11,8 @@
  * `typeof mutators` carries every mutator's precise `args` and result types
  * through to wherever they are invoked.
  */
-/**
- * Returns the mutators object unchanged while constraining its shape against the
- * schema. The `S` generic pins the model keys, and the `M` generic is inferred as
- * a `const`, so each mutator's literal signature survives. There is no runtime
- * work here; the function exists purely as a place for type inference to anchor.
- */
-export function defineMutators(_schema, mutators) {
-    return mutators;
+export function defineMutators(schemaOrMutators, maybeMutators) {
+    // The schema argument is a type anchor only — never read at runtime. With one
+    // argument the mutator tree is in the first slot; with two it's in the second.
+    return (maybeMutators ?? schemaOrMutators);
 }

package/dist/react/index.d.ts

@@ -43,7 +43,7 @@
  *   useAblo((ablo) => ablo.<model>.claim.state(...))  — reactive coordination reads
  *   useWatch({ scope })                               — join a scope to get its peers and claims
  */
-export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveClaims, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
+export type { DefaultSyncShape, ResolveSchema, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
 export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseWatchOptions, type UseWatchReturn, type MeshParticipantStatus, } from './AbloProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';

package/dist/schema/index.d.ts

@@ -32,7 +32,7 @@ export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwr
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type Row, type InferModel, type InferCreate, type InferRow, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
-export { selectModels } from './select.js';
+export { selectModels, omitModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
 export { PG_LOCK_NOT_AVAILABLE, resolveDdlLockTimeout, resolveDdlMaxLockAttempts, ddlLockRetryBackoffMs, type DdlLockEnv, } from './ddlLock.js';
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';

package/dist/schema/index.js

@@ -57,7 +57,7 @@ export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, inter
 // Schema ⇄ JSON — serialize a schema for transport and rebuild it on the far side.
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.
-export { selectModels } from './select.js';
+export { selectModels, omitModels } from './select.js';
 // Schema → Postgres DDL — shared by the host implementation and the command-line tools.
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
 // Safe-DDL locking knobs (lock_timeout plus a bounded retry on lock contention),

package/dist/schema/select.d.ts

@@ -23,3 +23,18 @@
  */
 import type { Schema, SchemaRecord } from './schema.js';
 export declare function selectModels<S extends SchemaRecord, K extends keyof S & string>(schema: Schema<S>, keys: readonly K[]): Schema<Pick<S, K>>;
+/**
+ * `omitModels` is `selectModels` from the other side: keep every model EXCEPT
+ * the named ones. Use it when an app is the general case and another product
+ * owns the omitted models — e.g. the product suite shell drops the standalone
+ * Mail store, which `@ablo/mail-schema` selects for the mail app:
+ *
+ * ```ts
+ * export const schema = omitModels(full, ['mailMailboxes', 'mailThreads']);
+ * ```
+ *
+ * Same validation as `selectModels`: relations into the omitted set are
+ * dropped, and a dropped `parent` edge throws — so a model whose scope routes
+ * through an omitted parent cannot be silently kept.
+ */
+export declare function omitModels<S extends SchemaRecord, K extends keyof S & string>(schema: Schema<S>, keys: readonly K[]): Schema<Omit<S, K>>;