@abloatai/ablo 0.34.1 → 0.35.0

package/dist/index.d.ts

@@ -33,7 +33,7 @@
  * 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
+ * `ablo.<model>.local.retrieve(id)`, `.local.list(...)`, and `.local.count(...)` 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.
@@ -51,56 +51,62 @@
  * If you don't recognize one of these, you don't need it.
  */
 export { Ablo } from './client/Ablo.js';
+export { humans } from './client/humans.js';
+export type { HumansSurface } from './client/humans.js';
+export type { AbloCoreClient } from './client/coreClient.js';
+export type { AbloPlugin, PipelineStage, TransportCapabilities } from './transaction/plugin.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 { 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, } from './client/Ablo.js';
+export type { ModelUpdater, ContentionOptions } from './transaction/resources/functionalUpdate.js';
+export { DEFAULT_CONTENTION_RETRIES } from './transaction/resources/functionalUpdate.js';
+export type { AbloReads } from './client/abloClient.js';
+export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './transaction/transport/httpClient.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './transaction/auth/apiKey.js';
+export type { AbloOptions } from './client/Ablo.js';
+export type { LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, } from './client/resourceTypes.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 { HeldClaim } from './client/resourceTypes.js';
 /** The resolved value of the row-free `ablo.<model>.claim(id)` overload — a
  *  held lease on a key whose row Ablo does not hold (a {@link HeldClaim} with
  *  no `.data`). */
-export type { HeldLease } 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';
-export { durableHttpCommitEnvelopeSchema, } from './transactions/httpCommitEnvelope.js';
-export type { DurableHttpCommitEnvelope, } from './transactions/httpCommitEnvelope.js';
+export type { HeldLease } from './client/resourceTypes.js';
+export type { AbloPersistence } from './transaction/persistence.js';
+export { durableWritesConfigSchema, durableWriteStoreSchema, pendingWriteSchema, } from './transactions/mutations/durableWriteStore.js';
+export type { DurableWritesConfig, DurableWriteStore, PendingWrite, } from './transactions/mutations/durableWriteStore.js';
+export { durableCommitEnvelopeSchema, } from './transaction/transactions/settlement/commitEnvelope.js';
+export type { CommitOutboxScope, DurableCommitEnvelope, } from './transaction/transactions/settlement/commitEnvelope.js';
+export { durableHttpCommitEnvelopeSchema, } from './transaction/transactions/settlement/httpCommitEnvelope.js';
+export type { DurableHttpCommitEnvelope, } from './transaction/transactions/settlement/httpCommitEnvelope.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 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 { 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';
-export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
-export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
-export type { Environment, KeyPrefixEnvironment } from './environment.js';
-export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
-export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
+export { AbloSessionError, 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 './transaction/errors.js';
+export type { RequiredCapability } from './transaction/errors.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './transaction/errors.js';
+export { errorEnvelope, statusForType } from './transaction/wire/errorEnvelope.js';
+export type { ErrorEnvelope } from './transaction/wire/errorEnvelope.js';
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './transaction/auth/credentialSource.js';
+export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './transaction/environment.js';
+export type { Environment, KeyPrefixEnvironment } from './transaction/environment.js';
+export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './transaction/resources/writeOptionsSchema.js';
+export type { WriteOptionsInput } from './transaction/resources/writeOptionsSchema.js';
+export type { OnStaleMode } from './transaction/coordination/schema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
-export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
-export type { StaleNotification, ReadDependency } from './coordination/schema.js';
-export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
-export type { ClaimLogEntry } from './coordination/trace.js';
+export { staleNotificationSchema, readDependencySchema } from './transaction/coordination/schema.js';
+export type { StaleNotification, ReadDependency } from './transaction/coordination/schema.js';
+export { ClaimLog, formatClaim, formatConflict } from './coordination/ClaimLog.js';
+export type { ClaimLogEntry } from './coordination/ClaimLog.js';
 export type { ClaimEvent, ConflictEvent, SyncObservabilityProvider, } from './interfaces/index.js';
-export { noopObservability } from './SyncEngineContext.js';
+export { noopObservability } from './RuntimeContext.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+export type { CommitLatencySample } from './transactions/mutations/commitLatency.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';
-export type { Register, DefaultSyncShape } from './types/global.js';
+export type { Register, DefaultSyncShape } from './transaction/types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';
-export { deepEqual, stableStringify } from './utils/json.js';
+export { deepEqual, stableStringify } from './transaction/utils/json.js';

package/dist/index.js

@@ -33,7 +33,7 @@
  * 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
+ * `ablo.<model>.local.retrieve(id)`, `.local.list(...)`, and `.local.count(...)` 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.
@@ -57,16 +57,19 @@
 // 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 reactive materialiser as a declared capability (ADR 0016): installed by
+// default on the socket client, named explicitly when the list is written out.
+// `AbloPlugin` is the one uniform shape every capability declares.
+export { humans } from './client/humans.js';
+export { DEFAULT_CONTENTION_RETRIES } from './transaction/resources/functionalUpdate.js';
 // 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';
-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';
+export {} from './transaction/transport/httpClient.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './transaction/auth/apiKey.js';
+export { durableWritesConfigSchema, durableWriteStoreSchema, pendingWriteSchema, } from './transactions/mutations/durableWriteStore.js';
+export { durableCommitEnvelopeSchema, } from './transaction/transactions/settlement/commitEnvelope.js';
+export { durableHttpCommitEnvelopeSchema, } from './transaction/transactions/settlement/httpCommitEnvelope.js';
 // Participant types live under `Ablo.Participant.*` —
 // `Ablo.Participant.Joined`, `Ablo.Participant.Manager`,
 // `Ablo.Participant.JoinOptions`, etc. Same dot-access shape as
@@ -95,33 +98,37 @@ export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '.
 // 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';
+export { AbloSessionError, 
+// Deprecated alias, removed in 0.36.0. The barrel keeps re-exporting it until
+// then so consumers don't lose the name a version early.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+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 './transaction/errors.js';
 // 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';
+export { errorEnvelope, statusForType } from './transaction/wire/errorEnvelope.js';
+export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './transaction/auth/credentialSource.js';
+export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './transaction/environment.js';
 // 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';
+export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './transaction/resources/writeOptionsSchema.js';
 // 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';
+export { staleNotificationSchema, readDependencySchema } from './transaction/coordination/schema.js';
 // 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';
+export { ClaimLog, formatClaim, formatConflict } from './coordination/ClaimLog.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';
+export { noopObservability } from './RuntimeContext.js';
 // 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.
@@ -135,9 +142,8 @@ export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, }
 // `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
+//   Ablo.Mutator.Fn, Ablo.Mutator.Transaction
+//   Ablo.Mutator.UndoEntry, Ablo.Mutator.UndoScope, Ablo.Mutator.InverseOp
 export { defineMutators } from './mutators/defineMutators.js';
 // `createTransaction` lets callers outside React — server-side workers, agent
 // runtimes — run custom mutators without the `useMutators` hook. Build a
@@ -152,4 +158,4 @@ export { createTransaction } from './mutators/Transaction.js';
 // 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';
+export { deepEqual, stableStringify } from './transaction/utils/json.js';

package/dist/interfaces/index.d.ts

@@ -6,18 +6,15 @@
  * 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 { ReadDependency, TrackDependency, ParticipantKind } from '../coordination/schema.js';
-import type { CommitStatus, MutationCommitResultInput } from '../wire/commit.js';
-export interface SyncLogger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-/** Breadcrumb severity levels */
-export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
-/** Breadcrumb categories for sync engine lifecycle events */
-export type SyncBreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.coordination' | 'sync.groups';
+import type { MutationCommitResultInput } from '../transaction/wire/commit.js';
+import type { OnStaleMode } from '../transaction/coordination/schema.js';
+export type { ClaimEvent, ConflictEvent } from '../transaction/coordination/events.js';
+import type { CoordinationObservability } from '../transaction/observability.js';
+export type { CoordinationObservability } from '../transaction/observability.js';
+export type { Logger } from '../transaction/logger.js';
+import type { Logger } from '../transaction/logger.js';
+export type { BreadcrumbLevel, BreadcrumbCategory, WebSocketErrorDetails, TransportObservability, } from '../transaction/observability.js';
+import type { BreadcrumbCategory, TransportObservability } from '../transaction/observability.js';
 export interface RollbackDetails {
     transactionType: string;
     modelName: string;
@@ -54,12 +51,6 @@ export interface DeltaRetryExhaustedDetails {
     retryCount: number;
     syncIdNeeded?: number;
 }
-export interface WebSocketErrorDetails {
-    context: string;
-    error?: string;
-    code?: number;
-    reason?: string;
-}
 export interface SelfHealingDetails {
     modelName: string;
     modelId: string;
@@ -70,46 +61,6 @@ export interface CommitZeroSyncIdDetails {
     operationCount: number;
     operations: string[];
 }
-/**
- * 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';
-    /** Server claim id, when the frame carries one. */
-    claimId?: string;
-    /** The claimed row + optional field scope. */
-    model?: string;
-    id?: string;
-    field?: string;
-    /** Participant that owns or blocks the lease (on `rejected`, the holder). */
-    actor?: string;
-    participantKind?: ParticipantKind;
-    /** FIFO position when `queued`. */
-    position?: number;
-    /** Rejection or policy reason, when the server supplied one. */
-    reason?: string;
-}
-/**
- * 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. */
-    clientTxId: string;
-    /** The conflicted rows + the fields that collided. */
-    rows: readonly {
-        model: string;
-        id: string;
-        fields: readonly string[];
-        writtenBy?: ParticipantKind;
-    }[];
-}
 /** Span attributes for performance monitoring */
 export type SpanAttributes = Record<string, string | number | boolean | undefined>;
 /**
@@ -117,31 +68,29 @@ export type SpanAttributes = Record<string, string | number | boolean | undefine
  * 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 {
+export interface ObservabilityProvider extends CoordinationObservability, TransportObservability {
     /** Set user/org context for error grouping */
     setContext(userId: string, organizationId: string): void;
     /** Update connection state tag */
     setConnectionState(state: 'connected' | 'disconnected' | 'connecting'): void;
-    /** Add a breadcrumb for sync lifecycle events */
-    breadcrumb(message: string, category: SyncBreadcrumbCategory, level?: BreadcrumbLevel, data?: Record<string, string | number | boolean | undefined>): void;
     /** Capture optimistic rollback (data reverted) */
     captureRollback(details: RollbackDetails): void;
-    /** Capture permanent transaction failure */
-    captureTransactionFailure(details: TransactionFailureDetails): void;
+    /**
+     * Capture permanent mutation failure. Named `captureTransactionFailure`
+     * before 0.35.0; the rename is announced in that release note rather than
+     * aliased, because this member is required — a provider still carrying the
+     * old spelling fails to satisfy the interface and the compiler names the
+     * member, which an optional alias would only have hidden.
+     */
+    captureMutationFailure(details: TransactionFailureDetails): void;
     /** Capture bootstrap failure */
     captureBootstrapFailure(error: Error | unknown, details?: BootstrapFailureDetails): void;
     /** Capture reconciliation needed (delta confirmation timeout) */
     captureReconciliation(details: ReconciliationDetails): void;
     /** Capture delta retry exhausted */
     captureDeltaRetryExhausted(details: DeltaRetryExhaustedDetails): void;
-    /** Capture WebSocket error */
-    captureWebSocketError(details: WebSocketErrorDetails): void;
     /** Capture self-healing event */
     captureSelfHealing(details: SelfHealingDetails): void;
-    /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired) */
-    captureClaim(event: ClaimEvent): void;
-    /** Capture a notify-instead-of-abort stale-write collision */
-    captureConflict(event: ConflictEvent): void;
     /** Capture commit returning lastSyncId: 0 */
     captureCommitZeroSyncId(details: CommitZeroSyncIdDetails): void;
     /** Wrap a synchronous function in a performance span */
@@ -149,7 +98,7 @@ export interface SyncObservabilityProvider {
     /** Wrap an async function in a performance span */
     startSpanAsync<T>(name: string, op: string, fn: () => Promise<T>, attributes?: SpanAttributes): Promise<T>;
 }
-export interface SyncAnalytics {
+export interface Analytics {
     capture(event: string, properties?: Record<string, unknown>): void;
 }
 /**
@@ -184,67 +133,8 @@ export interface ModelDebugLoggerContract {
  * while every explicit queued result requires a WAL correlation.
  */
 export type CommitResult = MutationCommitResultInput;
-/**
- * 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 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. `null` is retained for source compatibility and is treated like
- *   omission; write retries never opt out of request identity.
- * - `label` — a human-readable tag recorded with the mutation for debugging, such
- *   as "nightly cleanup" or "user click".
- */
-export interface MutationOptions {
-    idempotencyKey?: string | null;
-    label?: string;
-    wait?: CommitStatus;
-    readAt?: number | null;
-    onStale?: 'reject' | 'overwrite' | 'notify' | null;
-    /**
-     * The fencing token (Option B) of the held claim this write belongs to. The
-     * server validates it against the entity's persisted high-water and rejects a
-     * stale token. Sourced from the claim handle, never set by hand.
-     */
-    fenceToken?: number | null;
-    /** 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;
-    /**
-     * 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 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.
-     *
-     * See `packages/sync-engine/docs/concurrency-convention.md` (§3 the two
-     * footprints, §4 the read-set) for the governing convention.
-     */
-    reads?: ReadDependency[] | null;
-    /**
-     * Durable read-dependencies — what this write (or the record it produces) should
-     * keep watching. Unlike `reads`, which is checked once at commit and discarded,
-     * each `track` entry is persisted and re-checked against every future delta; a
-     * later matching change opens a `StaleNotification` for the tracking participant,
-     * delivered at their next commit or live to a held claim. Each entry is a row
-     * (`{ model, id }`) or a sync group (`{ group }`), optionally pinned to a `readAt`
-     * baseline (defaults to this commit's watermark).
-     *
-     * See `packages/sync-engine/docs/groups.md` for how `track` drives propagation.
-     */
-    track?: TrackDependency[] | null;
-}
+export type { MutationOptions } from '../transaction/resources/mutationOptions.js';
+import type { MutationOptions } from '../transaction/resources/mutationOptions.js';
 /**
  * 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
@@ -273,7 +163,7 @@ export interface MutationOperation {
      */
     transactionId?: string;
     readAt?: number | null;
-    onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    onStale?: OnStaleMode | null;
     /**
      * The fencing token (Option B) carried on the wire for this op — the held
      * claim's token, validated against the entity's high-water at commit.
@@ -333,7 +223,7 @@ export interface MutationExecutor {
  * Application-specific configuration for the sync engine, describing how your
  * models relate so the engine can order and merge writes correctly.
  */
-export interface SyncEngineConfig {
+export interface RuntimeConfig {
     /**
      * 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
@@ -361,7 +251,7 @@ export interface SyncEngineConfig {
      * 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'] }`.
+     * For example: `{ Task: ['title', 'projectId'], Section: ['reportId', 'order'] }`.
      */
     essentialFields: Readonly<Record<string, readonly string[]>>;
     /**
@@ -389,6 +279,16 @@ export interface SyncEngineConfig {
      * hash above.
      */
     expectedSourceSchemaHash?: string;
+    /**
+     * Per-model content hashes of the schema this client was built against,
+     * keyed by schema key (`tasks` → hash of that model's serialized JSON). The
+     * semantic layer of the drift check: on a whole-schema mismatch the client
+     * compares only the models IT declares against the server's per-model
+     * surface, so a purely additive server-side change (new models this build
+     * never references) is silence, and real divergence names the exact models.
+     * Advisory, like the hashes above.
+     */
+    expectedModelHashes?: Readonly<Record<string, string>>;
 }
 /**
  * Extends the WebSocket event map with your own collaboration events, such as
@@ -399,3 +299,13 @@ export interface WebSocketEventConfig {
     /** Additional event type names beyond the core delta/presence/bootstrap events */
     customEventTypes?: readonly string[];
 }
+/** @deprecated Renamed to {@link Logger}. Removed in 0.36.0. */
+export type SyncLogger = Logger;
+/** @deprecated Renamed to {@link ObservabilityProvider}. Removed in 0.36.0. */
+export type SyncObservabilityProvider = ObservabilityProvider;
+/** @deprecated Renamed to {@link Analytics}. Removed in 0.36.0. */
+export type SyncAnalytics = Analytics;
+/** @deprecated Renamed to {@link RuntimeConfig}. Removed in 0.36.0. */
+export type SyncEngineConfig = RuntimeConfig;
+/** @deprecated Renamed to {@link BreadcrumbCategory}. Removed in 0.36.0. */
+export type SyncBreadcrumbCategory = BreadcrumbCategory;

package/dist/keys/index.d.ts

@@ -1,77 +1 @@
-/**
- * The Ablo API-key format: how keys are minted, hashed, and validated, in one
- * place so every component that issues or checks a key agrees on the format.
- *
- * This module uses `node:crypto` and is therefore Node-only. It is published on
- * the `@abloatai/ablo/keys` subpath and kept off the main browser-facing entry
- * so a browser bundle never pulls in `node:crypto`.
- *
- * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
- * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
- * on parse to `production` or `sandbox`. The recognizable prefix lets secret
- * scanners spot a leaked key, and the trailing checksum lets the format reject a
- * mistyped or forged key locally, without a database round-trip. Older keys
- * (roughly a 43-character base64url body with no checksum) still validate by hash
- * and parse here with `checksummed: false`.
- */
-import { z } from 'zod';
-import { type Environment } from '../environment.js';
-export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral", "publishable"];
-export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
-export declare const API_KEY_ENVS: readonly ["production", "sandbox"];
-export type ApiKeyEnv = Environment;
-/** A structurally-valid Ablo API key, parsed into its parts. */
-export interface ParsedApiKey {
-    /** The original plaintext. */
-    raw: string;
-    kind: ApiKeyKind;
-    env: ApiKeyEnv;
-    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
-    body: string;
-    /** True when this is the new checksummed format (36-char base62 body). */
-    checksummed: boolean;
-}
-/**
- * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
- * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
- * rejected without any network call; an older key with no checksum parses with
- * `checksummed: false` and is left for the server to validate by hash.
- */
-export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
-/** Parse + fully validate (incl. checksum). Returns null when invalid. */
-export declare function parseApiKey(raw: string): ParsedApiKey | null;
-/** True when the key uses the new checksummed format (regardless of validity). */
-export declare function isChecksummedKey(raw: string): boolean;
-/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
-export declare function keyChecksumMatches(raw: string): boolean;
-/**
- * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
- * once), its SHA-256 hash (persisted), and the 12-char display prefix.
- */
-export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
-    plaintext: string;
-    hash: string;
-    prefix: string;
-};
-/**
- * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
- * minted and when one is looked up. A fast hash is the right choice here rather
- * than a password hash like bcrypt: API keys are long random strings, so there is
- * no dictionary of guesses to slow down.
- */
-export declare function hashApiKey(plaintext: string): string;
-/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
-export declare const WEBHOOK_SECRET_PREFIX = "whsec_";
-/**
- * Mints a webhook signing secret following the Standard Webhooks specification
- * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
- * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
- * inside that range. Unlike an API key, a signing secret is not hashed at rest,
- * because signing a request with {@link signAbloSourceRequest} needs the live
- * value. It is therefore kept in a secret store, returned to the customer once at
- * creation, and never shown again.
- */
-export declare function generateWebhookSecret(): {
-    plaintext: string;
-    last4: string;
-};
+export * from '../transaction/keys/index.js';