@abloatai/ablo 0.26.0 → 0.27.0

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @abloatai/ablo — The Collaboration Layer for AI and Humans
+ * @abloatai/ablo — the collaboration layer for AI agents and people.
  *
  * ```ts
  * import Ablo from '@abloatai/ablo';
@@ -14,52 +14,53 @@
  * type Entry = Ablo.Peer;
  * ```
  *
- * `Ablo({ schema, apiKey })` gives typed model clients. `Ablo({ apiKey })`
- * gives the HTTP model/commit client for agents, MCP routes, and custom
- * runtimes.
+ * `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.
  *
- * Stripe / Anthropic / OpenAI all do this: one import, model clients
- * reached via dot-access on the engine, types via namespace dots.
+ * 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
+ * the instance (`ablo.reports.retrieve(...)`) and reach every supporting type
+ * through the namespace (`Ablo.Peer`, `Ablo.Claim`).
  *
- * Public subpaths:
+ * Related surfaces live on their own import subpaths:
  *   @abloatai/ablo/schema   — defineSchema, model, z (Zod)
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
- *   @abloatai/ablo/testing  — test harnesses + mocks
+ *   @abloatai/ablo/testing  — test harnesses and fixtures
  *
- * Reads split by where the data comes from. `ablo.<model>.retrieve({ id })` and
- * `.list({ where })` are the async **server** reads (pool → IDB → network via
- * the `HydrationCoordinator`, single-flight deduped); they're the default and
- * what hosted/stateless callers want, since their local graph starts empty.
- * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
- * **local-graph** snapshots with no network round-trip — for reactive React
- * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
+ * Reads come in two flavors, distinguished by where the data is fetched from.
+ * `ablo.<model>.retrieve({ id })` and `.list({ where })` are asynchronous reads
+ * that consult the local cache first and fall back to the network, de-duplicating
+ * concurrent requests for the same row. They are the default, and the right
+ * choice for stateless callers whose local graph starts empty.
+ * `ablo.<model>.get(id)`, `.getAll(...)`, and `.getCount(...)` are synchronous
+ * snapshots of the already-loaded local graph with no network round-trip — use
+ * them in reactive React selectors (`useAblo((ablo) => ablo.<model>.get(id))`)
+ * once the graph is warm.
  *
- * ── What to import (read this first) ────────────────────────────────
- * Default path — this is all most apps and agents ever need:
- *   • `Ablo` (default export) + `AbloOptions` + the `Model*Params` bags
- *   • the `Ablo*Error` classes, to discriminate failures in catch blocks
- * That's it. If you're reaching past those, you're in advanced territory.
+ * What to import, in short:
+ *   • `Ablo` (the default export), `AbloOptions`, and the `Model*Params` option
+ *     bags cover what most applications and agents ever need.
+ *   • the `Ablo*Error` classes let you discriminate failures in catch blocks.
  *
- * Advanced — opt-in, most apps never import these (each is tagged
- * "Advanced —" at its export below, with the one situation it's for):
- *   • `dataSource` / `abloSource`  — only if your own DB stays canonical
- *   • `defaultPolicy`              — only to customize conflict resolution
- *   • `defineMutators` / `createTransaction` — only for custom mutators
- * If you don't recognize one, you don't need it — the default path covers you.
+ * 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.
+ *   • `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.
  */
 // ── Consumer API ──────────────────────────────────────────────────────────
 // These are the only symbols external consumers should need from this path.
 // Everything else is in a subpath.
-// The canonical surface — `Ablo` is a function, type, and namespace under
-// one name. Matches `Stripe`, `OpenAI`, `Anthropic`. Default export so
-// `import Ablo from '@abloatai/ablo'` works; named export so
-// `import { Ablo }` also compiles.
+// The primary surface. `Ablo` is a function, a type, and a namespace sharing
+// one name. It is the default export, so `import Ablo from '@abloatai/ablo'`
+// works, and a named export, so `import { Ablo }` compiles too.
 export { Ablo } from './client/Ablo.js';
 export { DEFAULT_CONTENTION_RETRIES } from './client/functionalUpdate.js';
-// The stateless HTTP client is constructed ONLY via `Ablo({ transport: 'http' })`
-// (one factory, explicit transport). The `createAbloHttpClient` function stays
-// internal — the factory calls it — but is NOT a public export. Consumers still
-// annotate with the `AbloHttpClient` type (the narrowed return of `transport:'http'`).
+// The stateless HTTP client is constructed through `Ablo({ transport: 'http' })`.
+// There is no separate constructor to import; annotate values with the
+// `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';
 // Participant types live under `Ablo.Participant.*` —
@@ -68,81 +69,83 @@ export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_UR
 // `Ablo.Peer`, `Ablo.Claim`. No flat re-exports.
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
-// Advanced — most apps never import this. Customer-owned storage adapter
-// for Data Source mode: only when Ablo Cloud coordinates state while
-// canonical rows stay in YOUR database. The default is Ablo-managed
-// storage — if you haven't deliberately chosen to keep your own DB
-// canonical, skip this entirely. Type counterparts live under
-// `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
+// Advanced, and rarely imported. The storage adapter for Data Source mode,
+// where Ablo coordinates state while the canonical rows stay in your own
+// 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';
-// Reverse-channel connector: serve the Data Source `commit`/`load`/`list` leg
-// over an OUTBOUND WebSocket (localhost / locked-down VPC, no public inbound
-// URL). The dial-out counterpart to `createPushQueue` for the `events` leg.
+// 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
+// dialing out to Ablo rather than accepting an inbound connection.
 export { createSourceConnector, } from './source/connector.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
-// Advanced — most apps never import this. Conflict policy: `defaultPolicy`
-// (reject-on-stale) is already applied server-side, so you only import it
-// to COMPOSE a custom policy. Leave it alone and stale writes are rejected
-// safely by default. Type counterparts live under `Ablo.Conflict.*`.
+// Advanced, and rarely imported. The default conflict policy rejects writes
+// premised on stale data and is already applied on the server, so import
+// `defaultPolicy` only to build a custom policy on top of it. Leave it be and
+// stale writes are rejected safely. The matching types live under `Ablo.Conflict.*`.
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from './policy/index.js';
-// Typed error hierarchy — Stripe-style. One import gets every class
-// consumers need to discriminate failures (`e instanceof AbloX` or
-// `e.type === 'AbloX'`) plus the HTTP-response translator.
+// The typed error hierarchy. One import brings in every class you need to
+// tell failures apart — by `e instanceof AbloX` or `e.type === 'AbloX'` — along
+// with the helper that translates an HTTP response into the right class.
 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';
-// Canonical wire-egress contract (dependency-free): the error envelope shape +
-// the AbloError-subclass→HTTP-status table. Re-exported so server consumers
-// (e.g. apps/sync-server, which keeps its own self-contained copy) can assert
-// against the ONE source instead of silently drifting. See wire/errorEnvelope.ts.
+// The wire contract for errors, with no dependencies: the JSON envelope shape
+// plus the table mapping each AbloError subclass to an HTTP status. A server
+// that returns Ablo errors can assert against these so its responses never
+// drift from what the client expects.
 export { errorEnvelope, statusForType } from './wire/errorEnvelope.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
-// THE write-options contract — the one Zod schema for the option bag every
-// write door accepts (`ablo.<model>.create/update/delete`, `commits.create`,
-// the HTTP model routes). The SDK validates against it at each boundary;
-// it's exported so consumers can validate/compose options ahead of a call
-// (e.g. an agent tool's input schema). Runtime twin of `MutationOptions`,
-// drift-guarded at compile time.
+// The write-options contract: the single Zod schema for the option bag every
+// write accepts (`ablo.<model>.create/update/delete`, `commits.create`, and the
+// HTTP model routes). The SDK validates against it at each boundary, and it is
+// exported so you can validate or assemble options before a call — for example,
+// as the input schema of an agent tool. It is the runtime counterpart of the
+// `MutationOptions` type.
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
-// Notify-instead-of-abort signal: the value handed back to a committer whose
-// write hit a stale-context conflict under `onStale: 'notify' so its
-// agent can self-heal rather than discard work (see coordination/schema.ts and
-// docs/coordination.md → "Notify, do not abort").
+// The value handed back to a writer whose change hit a stale-context conflict
+// under `onStale: 'notify'`. Instead of throwing, the commit succeeds and
+// returns this notification so the caller can reconcile against the current
+// value and retry rather than discard its work.
 export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
-// Claim log — collect claim events + stale-write collisions into an ordered list
-// you can print for eyeballing or collisions() for evals assertions. Hand
-// `new ClaimLog()` to `Ablo({ observability })`.
+// Collects claim events and stale-write collisions into an ordered list you can
+// print to inspect coordination, or read through `collisions()` to assert on in
+// tests. Pass `new ClaimLog()` as `Ablo({ observability })`.
 export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
 // Spread this to provide a custom `observability` that overrides only the hooks
 // you care about (e.g. captureClaim) and no-ops the rest.
 export { noopObservability } from './SyncEngineContext.js';
-// Storage-wedge detection — lets app shells render a recovery screen when the
-// IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
+// Detects a stuck local store: use these to recognize when the browser's
+// IndexedDB backing store fails to open in time, so your app can show a
+// recovery screen instead of hanging.
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
-// Machine-checked surface manifest — the SDK's own description of its public
-// verb/option names, compile-time-bound to the real types (see surface.ts).
-// The MCP `get_api_surface` imports these so docs can't name a phantom verb.
+// A machine-readable manifest of the SDK's public verb and option names, bound
+// at compile time to the real types so the lists can never name a method or
+// option the API doesn't have. Useful for generating documentation or tooling
+// that needs to enumerate the surface.
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
-// Advanced — most apps never import this. Custom (Zero-style) mutators:
-// `ablo.<model>.create/update/delete` already covers normal writes. Reach
-// for `defineMutators` only when you need a named, multi-step mutation with
-// custom undo. Type counterparts live under the `Ablo` namespace:
+// Advanced, and rarely imported. Custom mutators. Ordinary writes go through
+// `ablo.<model>.create/update/delete`; reach for `defineMutators` only when you
+// need a named, multi-step mutation with its own undo behavior. The matching
+// types live under the `Ablo` namespace:
 //   Ablo.Mutator.Fn, Ablo.Transaction
 //   Ablo.Mutator.UndoEntry, Ablo.Mutator.InverseOp
 //   Ablo.Query, Ablo.QueryBatch, Ablo.QueryBatchResult
 export { defineMutators } from './mutators/defineMutators.js';
-// `createTransaction` is exposed so non-React callers (the sandbox AI
-// executor, server-side workers) can invoke `defineMutators`-style
-// custom mutators without going through `useMutators`. Construct a tx
-// against `ablo.schema` + `ablo._store` + `ablo.organizationId` and
-// pass it as `{ tx, args }` to the mutator function.
+// `createTransaction` lets callers outside React — server-side workers, agent
+// runtimes — run custom mutators without the `useMutators` hook. Build a
+// transaction from the client's schema, store, and organization id, then pass
+// it to your mutator function as `{ tx, args }`.
 export { createTransaction } from './mutators/Transaction.js';
 // Undo runtime is intentionally not part of the public root surface. App code
 // uses `useUndoScope` from `@abloatai/ablo/react`.
-// JSON comparison helpers. A `field.json()` value backed by a Postgres `jsonb`
-// column round-trips with reordered object keys (jsonb doesn't preserve key
-// order), so a naive `JSON.stringify(a) === JSON.stringify(b)` guard misfires
-// when an app reconciles an Ablo row against external editor state. Use these
-// (key-order-insensitive) instead. See `utils/json.ts` for the full rationale.
+// JSON comparison helpers. A `field.json()` value stored in a Postgres `jsonb`
+// column can come back with its object keys reordered, because jsonb does not
+// preserve key order. A naive `JSON.stringify(a) === JSON.stringify(b)` check
+// then reports a difference that isn't real — a common trap when reconciling an
+// Ablo row against external editor state. These compare independent of key
+// order, so use them instead.
 export { deepEqual, stableStringify } from './utils/json.js';

package/dist/interfaces/index.d.ts

@@ -1,9 +1,10 @@
 /**
- * Sync Engine SDK — Dependency Injection Interfaces
+ * The interfaces you implement to plug the SDK into your own environment.
  *
- * These interfaces decouple the SDK from any specific app framework.
- * Consumers implement them to wire in their own logging, observability,
- * GraphQL client, session handling, and analytics.
+ * The SDK depends on these contracts rather than any specific framework, so you
+ * provide the concrete implementations — logging, observability, analytics,
+ * session-error detection, online-status checks, and the transport that carries
+ * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
 import type { StaleNotification, ReadDependency, ParticipantKind } from '../coordination/schema.js';
 export interface SyncLogger {
@@ -69,10 +70,11 @@ export interface CommitZeroSyncIdDetails {
     operations: string[];
 }
 /**
- * One thing that happened to a claim. `phase` is the past-tense state it just
- * entered — the trail you follow to see WHY two participants collided on a row:
- * who asked, who waited behind whom, who was turned away, whose lease lapsed.
- * Each phase mirrors a `claim_*` wire frame.
+ * A single event in the life of a claim. `phase` is the state the claim has just
+ * entered, and the sequence of phases is the trail you follow to see how two
+ * participants collided on a row — who asked for it, who waited behind whom, who
+ * was turned away, and whose lease lapsed. Each phase corresponds to a `claim_*`
+ * frame on the wire.
  */
 export interface ClaimEvent {
     phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
@@ -91,10 +93,10 @@ export interface ClaimEvent {
     reason?: string;
 }
 /**
- * A committed `onStale: 'notify'` write whose premise moved — the in-flight twin
- * of a claim collision. The commit SUCCEEDED, but the guarded ops weren't written
- * because the row changed since the caller's `readAt`; the engine handed back the
- * live value so the actor can self-heal. Records WHICH rows and fields collided.
+ * A committed `onStale: 'notify'` write whose premise had moved. The commit
+ * succeeded, but the guarded operations were not written because the row had
+ * changed since the caller's `readAt`, and the engine returned the current value
+ * so the caller can reconcile. Records which rows and fields collided.
  */
 export interface ConflictEvent {
     /** The client idempotency key whose write was notified. */
@@ -110,8 +112,9 @@ export interface ConflictEvent {
 /** Span attributes for performance monitoring */
 export type SpanAttributes = Record<string, string | number | boolean | undefined>;
 /**
- * Observability provider — replaces direct Sentry dependency.
- * SDK ships a no-op default; consumers provide their own (e.g., Sentry, Datadog, OpenTelemetry).
+ * The observability hooks the SDK calls to report its own lifecycle. The SDK
+ * ships a no-op default; provide your own to forward these events to a monitoring
+ * tool such as Sentry, Datadog, or OpenTelemetry.
  */
 export interface SyncObservabilityProvider {
     /** Set user/org context for error grouping */
@@ -178,30 +181,29 @@ export interface ModelDebugLoggerContract {
 export interface CommitResult {
     lastSyncId: number;
     /**
-     * Stale-context notifications (CoAgent/MTPO notify-instead-of-abort). Present
-     * only when a write guarded with `onStale: 'notify' collided with a
-     * concurrent change; the committer self-heals from these rather than
-     * receiving an `AbloStaleContextError`. See `StaleNotification`.
+     * Stale-context notifications. Present only when a write guarded with
+     * `onStale: 'notify'` collided with a concurrent change: rather than throwing
+     * an `AbloStaleContextError`, the commit succeeds and reports the collision
+     * here so the caller can reconcile. See {@link StaleNotification}.
      */
     notifications?: StaleNotification[];
     /**
-     * Ids of UPDATE/DELETE targets that matched ZERO rows (loud 0-row writes).
-     * Present (non-empty) only when a write missed.
+     * Ids of update or delete targets that matched no rows. Present, and non-empty,
+     * only when a write missed the row it addressed.
      */
     missingIds?: string[];
 }
 /**
- * Per-call knobs attached to any mutation. Mirrors Stripe's options
- * object — the last argument of every `stripe.X.Y(...)` call. Optional
- * everywhere; omitted fields fall back to sensible defaults.
+ * Per-call options accepted by any mutation, passed as the last argument.
+ * Every field is optional; omitted fields fall back to sensible defaults.
  *
- * - `idempotencyKey` — when set, the server caches the response for 24h
- *   and returns the cached value on retries with the same key.
- *   When omitted, the SDK auto-generates a UUIDv4 per mutation so every
- *   call is retry-safe by default. Opt out with `{ idempotencyKey: null }`
- *   if you genuinely want retry-unsafe writes (rare).
- * - `label` — human-readable audit tag. Flows to `mutation_log.label`
- *   server-side for operator debugging ("nightly cleanup", "user click").
+ * - `idempotencyKey` — when set, the server caches the response for 24 hours and
+ *   returns the cached result on any retry using the same key. When omitted, the
+ *   SDK generates a fresh UUID per mutation, so every call is retry-safe by
+ *   default. Pass `{ idempotencyKey: null }` for the rare case where you want a
+ *   write that is not retry-safe.
+ * - `label` — a human-readable tag recorded with the mutation for debugging, such
+ *   as "nightly cleanup" or "user click".
  */
 export interface MutationOptions {
     idempotencyKey?: string | null;
@@ -209,86 +211,76 @@ export interface MutationOptions {
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    /** Claim-pin attribution: the id (or `{ id }`) of the claim this write
-     *  belongs to. Distinct from the `claim` HANDLE on the model write params —
-     *  this is the low-level reference the commit carries to bypass the holder's
-     *  own pin. (Was `intent` before the claim-vocabulary unification.) */
+    /** The id (or `{ id }`) of the claim this write belongs to. This is the
+     *  low-level reference the commit carries so the write is attributed to a claim
+     *  and can pass the holder's own lock. It is distinct from the `claim` handle on
+     *  the model write parameters, which is the higher-level object you usually pass. */
     claimRef?: string | {
         readonly id: string;
     } | null;
     /**
-     * Dormant agent-task lineage field, forwarded as the wire-level
-     * `causedByTaskId`. Turns/tasks were removed from the SDK; nothing
-     * populates this anymore (write attribution rides on the claim
-     * id). Kept optional for wire-compat; always `null` from the client.
+     * Reserved lineage field, forwarded on the wire as `causedByTaskId`. The client
+     * always sends `null`; write attribution now travels on the claim id instead.
      */
     causedByTaskId?: string | null;
     /**
-     * Batch-level read dependencies (the STORM "did anything I looked at change?"
-     * layer). Each entry is a row (`{model,id,readAt,fields?}`) or a sync group
-     * (`{group,readAt}`) this write was premised on; the server validates none
-     * moved since `readAt` and fires the entry's `onStale` over the batch.
-     * Distinct from per-op `readAt` (which guards only the row being written).
+     * Batch-level read dependencies — the answer to "did anything I looked at
+     * change?" Each entry is a row (`{ model, id, readAt, fields? }`) or a sync
+     * group (`{ group, readAt }`) that this write was premised on. The server
+     * 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.
      */
     reads?: ReadDependency[] | null;
 }
 /**
- * The `MutationOptions` subset carried per-write through the offline
- * transaction lane (SyncClient → TransactionQueue → wire operation).
- * ONE shared type so the proxy's public params, the queue, and the wire
- * can never narrow each other silently again — `wait` and `claim` are
- * deliberately absent because they resolve client-side before staging
- * (`wait` at the proxy's confirmation await, `claim` server-side via
- * the active lease on the entity).
+ * The subset of {@link MutationOptions} that travels with each write as it is
+ * queued offline and sent on the wire. A single shared type keeps the public
+ * parameters, the offline queue, and the wire format from diverging. `wait` and
+ * `claim` are deliberately absent: both are resolved on the client before a write
+ * is staged, so neither reaches this layer.
  */
 export type WriteOptions = Pick<MutationOptions, 'readAt' | 'onStale' | 'idempotencyKey' | 'label'>;
-/** A single mutation operation in a batch. `options` rides along so the
- *  server can cache+replay via `mutation_log`. */
+/** A single mutation within a batch. Its `options` travel with it so the server
+ *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {
     type: string;
     model: string;
     id: string;
     input?: Record<string, unknown>;
     /**
-     * Client-side transaction id for THIS operation. The server stamps
-     * it onto the resulting `sync_deltas.transaction_id` so the
-     * confirming delta can be recognized as an echo of the local
-     * optimistic mutation (echo detection at the receive layer drains
-     * the matching id via `OptimisticEchoTracker` and skips the pool
-     * mutation — see `SyncClient.applyDeltaBatchToPool`).
+     * A client-side id for this single operation. The server stamps it onto the
+     * resulting `sync_deltas.transaction_id`, so when the confirming delta arrives
+     * back over the sync stream the client can recognize it as an echo of its own
+     * optimistic write and skip re-applying it locally.
      *
-     * Distinct from the batch-level `client_tx_id` used by
-     * `mutation_log` for idempotency. The mutation_log key dedupes a
-     * RETRIED batch (request-level cache); this transactionId
-     * identifies a specific MUTATION within a batch (per-row identity
-     * for echo matching). Both can coexist on the wire.
+     * This is distinct from the batch-level `client_tx_id` that idempotency uses:
+     * that key de-duplicates a retried batch (a request-level cache), whereas this
+     * id identifies one row within a batch (for echo matching). Both can appear on
+     * the wire at once.
      */
     transactionId?: string;
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /**
-     * Per-op idempotency + audit metadata. `idempotencyKey` doubles as
-     * the `mutation_log.client_tx_id` cache key; `label` is persisted to
-     * `mutation_log.label` for debugging. These are the only `MutationOptions`
-     * fields carried over the wire.
+     * Per-operation idempotency and audit metadata. `idempotencyKey` is also the
+     * cache key the server uses to de-duplicate retries; `label` is stored for
+     * debugging. These are the only {@link MutationOptions} fields sent on the wire.
      */
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 /**
- * Executes mutations against the backend.
- * The SDK calls this interface; consumers implement it with their
- * specific GraphQL client, REST API, or other transport.
+ * The transport that carries mutations to your backend. The SDK calls the
+ * methods on this interface; you implement them over whatever transport you use —
+ * an HTTP API, a WebSocket, or something else.
  */
 export interface MutationExecutor {
     /**
-     * Commit a batch of mutations atomically, returning the sync ack.
-     * `options` apply to the whole batch (timeout, retries) — per-op
-     * idempotencyKey/label live on each `MutationOperation`.
-     *
-     * Name matches the wire frame (`{ type: 'commit' }`) and the
-     * universal mental model for atomic writes (DB transactions, git,
-     * Firestore). Replaces the older `batchAck` name from the retired
-     * GraphQL path.
+     * Commits a batch of mutations atomically and returns the sync
+     * acknowledgement. The `options` argument applies to the whole batch, while
+     * per-operation `idempotencyKey` and `label` live on each
+     * {@link MutationOperation}. The method name matches the `{ type: 'commit' }`
+     * frame on the wire.
      */
     commit(operations: MutationOperation[], options?: MutationOptions): Promise<CommitResult>;
     /** Execute a create mutation for a specific model */
@@ -321,63 +313,60 @@ export interface MutationExecutor {
     onSessionExpired?(callback: () => void): void;
 }
 /**
- * Application-specific configuration for the sync engine.
- * Replaces the 6 hardcoded config maps that were previously
- * embedded in TransactionQueue, Database, and Model.
+ * Application-specific configuration for the sync engine, describing how your
+ * models relate so the engine can order and merge writes correctly.
  */
 export interface SyncEngineConfig {
     /**
-     * FK-ordered create priority, keyed by the typename each model reports
-     * via {@link Model.getModelName}. `TransactionQueue` consults this at
-     * enqueue time and when sorting groups inside a batch — lower numbers
-     * execute first, so parents precede children.
-     *
-     * `createSyncEngine` populates this automatically by topologically
-     * walking `belongsTo` relations: a model with no FK parents gets 10, a
-     * child gets 20, a grandchild 30, and so on (step = 10 to leave room
-     * for consumer overrides). Apps rarely need to touch this — override
-     * through `configOverrides.modelCreatePriority` only when the schema's
-     * declared relations don't reflect an operational constraint (e.g. a
-     * polymorphic FK the SDK can't see).
+     * The order in which to create models, so a row is never inserted before the
+     * parent row its foreign key points at. Keyed by each model's type name, with
+     * lower numbers created first, so parents precede children. The engine fills
+     * this in automatically by walking the schema's `belongsTo` relations — a model
+     * with no parents gets 10, its children 20, their children 30, and so on,
+     * stepping by 10 to leave room for overrides. You rarely set this by hand;
+     * override it only when a relation the schema can't see (such as a polymorphic
+     * foreign key) imposes an ordering the engine wouldn't otherwise know about.
      */
     modelCreatePriority: ReadonlyMap<string, number>;
     /**
-     * Priority assigned to CREATE ops for models missing from
-     * {@link modelCreatePriority}. Falls between the typical top and bottom
-     * of the FK chain, so an unregistered model ends up later than declared
-     * parents but earlier than declared grandchildren — a safe middle.
+     * The create priority for a model not listed in {@link modelCreatePriority}.
+     * It sits in the middle of the range, so an unlisted model is created after
+     * declared parents but before declared grandchildren — a safe default.
      */
     defaultCreatePriority: number;
     /**
-     * Priority for UPDATE/DELETE/ARCHIVE/UNARCHIVE ops, which don't need FK
-     * ordering (the row already exists by the time they run). Must be higher
-     * than any realistic CREATE priority so creates drain first.
+     * The priority for update, delete, archive, and unarchive operations. These
+     * need no ordering among themselves — the row already exists when they run —
+     * so this is set higher than any create priority to ensure creates go first.
      */
     defaultNonCreatePriority: number;
     /**
-     * Essential fields preserved during partial UPDATE merges in IndexedDB.
-     * Prevents losing critical fields when a delta only contains changed fields.
-     * e.g., { Task: ['title', 'projectId'], Slide: ['deckId', 'order'] }
+     * Fields to preserve when merging a partial update into the local store. A
+     * change usually carries only the fields that changed; listing a model's
+     * essential fields here keeps them from being dropped during that merge.
+     * For example: `{ Task: ['title', 'projectId'], Slide: ['deckId', 'order'] }`.
      */
     essentialFields: Readonly<Record<string, readonly string[]>>;
     /**
-     * Fallback class name → model name mapping for Model.getModelName().
-     * Used when the ModelRegistry lookup fails (e.g., minified class names).
-     * e.g., { TaskModel: 'Task', ProjectModel: 'Project' }
+     * A fallback map from class name to model name, used to resolve a model's name
+     * when the usual lookup fails — for instance, when a bundler has minified the
+     * class names. For example: `{ TaskModel: 'Task', ProjectModel: 'Project' }`.
      */
     classNameFallbackMap: Readonly<Record<string, string>>;
     /**
-     * Content hash of the schema THIS client was built against (the same
-     * `schemaHash()` the CLI push + server compute). Used purely to detect
-     * schema drift: when the server reports a different active hash on bootstrap,
-     * the SDK warns the developer to run `ablo push` — otherwise drift only
-     * surfaces later as an opaque DB constraint error. Advisory, not enforced.
+     * The content hash of the schema this client was built against — the same hash
+     * the `ablo push` command and the server compute. It exists only to detect
+     * schema drift: if the server reports a different active hash when the client
+     * connects, the SDK warns you to run `ablo push`, so drift surfaces as a clear
+     * message rather than a confusing database error later. It is advisory, not
+     * enforced.
      */
     expectedSchemaHash?: string;
 }
 /**
- * Allows consumers to extend the WebSocket event map with
- * application-specific collaboration events (cursors, selections, etc.).
+ * Extends the WebSocket event map with your own collaboration events, such as
+ * cursor positions or selections, beyond the core delta, presence, and
+ * bootstrap events.
  */
 export interface WebSocketEventConfig {
     /** Additional event type names beyond the core delta/presence/bootstrap events */

package/dist/interfaces/index.js

@@ -1,8 +1,9 @@
 /**
- * Sync Engine SDK — Dependency Injection Interfaces
+ * The interfaces you implement to plug the SDK into your own environment.
  *
- * These interfaces decouple the SDK from any specific app framework.
- * Consumers implement them to wire in their own logging, observability,
- * GraphQL client, session handling, and analytics.
+ * The SDK depends on these contracts rather than any specific framework, so you
+ * provide the concrete implementations — logging, observability, analytics,
+ * session-error detection, online-status checks, and the transport that carries
+ * mutations to your backend. The SDK ships sensible no-op defaults where it can.
  */
 export {};