@abloatai/ablo 0.26.0 → 0.27.0

package/dist/client/validateAbloOptions.d.ts

@@ -1,22 +1,20 @@
 /**
- * Up-front validation of `AbloOptions`. Returns the first error
- * encountered or null if all checks pass — caller writes the error
- * into `store.syncStatus` so consumers see it through the existing
- * status surface rather than catching it at the call site.
+ * Validates the options passed when constructing a client, before any
+ * connection is attempted. Returns the first problem it finds as an
+ * {@link AbloError}, or null when every check passes. The caller records that
+ * error on the client's sync status, so a misconfiguration surfaces through the
+ * normal status channel rather than throwing at the call site.
  *
- * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
- * so the validation rules are readable in isolation. The order of
- * checks matters: missing `url` is checked before identity options
- * because the error messages reference URLs and would mislead if a
- * URL was actually present.
+ * The order of checks matters: a missing `url` is reported before any identity
+ * problem, because the identity error messages mention the URL and would
+ * mislead if the URL were the thing actually missing.
  */
 import { AbloError } from '../errors.js';
 /**
- * Minimal subset of `AbloOptions` the validator actually inspects.
- * Defined here as its own interface so the validator doesn't pull
- * the whole 200+-line `AbloOptions` type — and to avoid a circular
- * import with `Ablo.ts`. Fields are kept structurally identical to
- * `AbloOptions` so a real options object satisfies this shape.
+ * The subset of client options this validator reads. It is declared as its own
+ * interface, structurally compatible with the full options type, so a real
+ * options object satisfies it without the validator having to depend on the
+ * complete type.
  */
 export interface ValidatableAbloOptions {
     readonly schema?: {

package/dist/client/validateAbloOptions.js

@@ -1,14 +1,13 @@
 /**
- * Up-front validation of `AbloOptions`. Returns the first error
- * encountered or null if all checks pass — caller writes the error
- * into `store.syncStatus` so consumers see it through the existing
- * status surface rather than catching it at the call site.
+ * Validates the options passed when constructing a client, before any
+ * connection is attempted. Returns the first problem it finds as an
+ * {@link AbloError}, or null when every check passes. The caller records that
+ * error on the client's sync status, so a misconfiguration surfaces through the
+ * normal status channel rather than throwing at the call site.
  *
- * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
- * so the validation rules are readable in isolation. The order of
- * checks matters: missing `url` is checked before identity options
- * because the error messages reference URLs and would mislead if a
- * URL was actually present.
+ * The order of checks matters: a missing `url` is reported before any identity
+ * problem, because the identity error messages mention the URL and would
+ * mislead if the URL were the thing actually missing.
  */
 import { AbloError, AbloValidationError } from '../errors.js';
 export function validateAbloOptions(input) {

package/dist/client/writeOptionsSchema.d.ts

@@ -1,18 +1,19 @@
 /**
- * THE write-options schema — one Zod schema for the write dialect every
- * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
- * HTTP model routes). Validated once at each public boundary so a plain-JS
- * caller passing `onStale: 'rejct'` fails loudly at the call site with a
- * typed `AbloValidationError`, not silently (or 400) at the server.
+ * The Zod schema for write options — the settings accepted by every write
+ * entry point, including `ablo.<model>.create/update/delete`, `commits.create`,
+ * and the HTTP write routes. Each of those boundaries validates against this
+ * one schema, so a caller who passes, say, `onStale: 'rejct'` fails right away
+ * with a typed {@link AbloValidationError} at the call site instead of silently
+ * or with a 400 from the server.
  *
- * Mirrors `source/contract.ts`: the schema is the runtime twin of the
- * `MutationOptions` interface, with a compile-time drift guard at the
- * bottom so the two can never silently diverge.
+ * The schema is the runtime counterpart of the {@link MutationOptions}
+ * interface. A compile-time check at the bottom of this file asserts that the
+ * two describe the same shape, so they cannot drift apart.
  *
- * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `claim` slot legally
- * carries live handles (`ClaimHandle` / claim leases) whose
- * `release`/`revoke` functions must survive — so we assert, never replace.
+ * Validation only inspects; it never transforms. Callers keep the exact options
+ * object they passed in. This matters because the `claim` field can hold a live
+ * claim handle whose `release` and `revoke` functions must survive, so the code
+ * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
 export declare const onStaleModeSchema: z.ZodEnum<{
@@ -40,9 +41,10 @@ export declare const writeOptionsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
 /**
- * Assert a write-options bag against THE schema. Throws a typed
- * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
- * `param` pointing at the offending field) and returns nothing — the
- * caller keeps its original object.
+ * Validates a write-options object against {@link writeOptionsSchema}. On
+ * failure it throws a typed {@link AbloValidationError} — with
+ * `code: 'write_options_invalid'` and a `param` pointing at the offending
+ * field — and on success returns nothing, leaving the caller's original object
+ * untouched. A `null` or `undefined` value passes.
  */
 export declare function assertWriteOptions(value: unknown, context?: string): void;

package/dist/client/writeOptionsSchema.js

@@ -1,24 +1,26 @@
 /**
- * THE write-options schema — one Zod schema for the write dialect every
- * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
- * HTTP model routes). Validated once at each public boundary so a plain-JS
- * caller passing `onStale: 'rejct'` fails loudly at the call site with a
- * typed `AbloValidationError`, not silently (or 400) at the server.
+ * The Zod schema for write options — the settings accepted by every write
+ * entry point, including `ablo.<model>.create/update/delete`, `commits.create`,
+ * and the HTTP write routes. Each of those boundaries validates against this
+ * one schema, so a caller who passes, say, `onStale: 'rejct'` fails right away
+ * with a typed {@link AbloValidationError} at the call site instead of silently
+ * or with a 400 from the server.
  *
- * Mirrors `source/contract.ts`: the schema is the runtime twin of the
- * `MutationOptions` interface, with a compile-time drift guard at the
- * bottom so the two can never silently diverge.
+ * The schema is the runtime counterpart of the {@link MutationOptions}
+ * interface. A compile-time check at the bottom of this file asserts that the
+ * two describe the same shape, so they cannot drift apart.
  *
- * Validation-only by design: callers keep their ORIGINAL options object.
- * Zod's parse output strips unknown keys, and the `claim` slot legally
- * carries live handles (`ClaimHandle` / claim leases) whose
- * `release`/`revoke` functions must survive — so we assert, never replace.
+ * Validation only inspects; it never transforms. Callers keep the exact options
+ * object they passed in. This matters because the `claim` field can hold a live
+ * claim handle whose `release` and `revoke` functions must survive, so the code
+ * asserts the shape rather than replacing the value with a parsed copy.
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export const writeOptionsSchema = z.object({
-    /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
+    /** Idempotency key the server records in `mutation_log` to make retries
+     *  safe; `null` opts out of that protection. */
     idempotencyKey: z.string().min(1).max(255).nullish(),
     /** Human-readable audit tag, persisted to `mutation_log.label`. */
     label: z.string().max(255).optional(),
@@ -28,17 +30,18 @@ export const writeOptionsSchema = z.object({
     readAt: z.number().int().nonnegative().nullish(),
     /** What the server does when the target moved past `readAt`. */
     onStale: onStaleModeSchema.nullish(),
-    /** Claim/claim attribution — an id, or a live lease handle (loose: the
-     *  handle's `release`/`revoke` functions ride along untouched). */
+    /** The claim this write belongs to — either a claim id, or a live claim
+     *  handle whose `release`/`revoke` functions are preserved untouched. */
     claim: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
-    /** Dormant wire-compat field; always `null` from current clients. */
+    /** Reserved wire-compatibility field; current clients always send `null`. */
     causedByTaskId: z.string().nullish(),
 });
 /**
- * Assert a write-options bag against THE schema. Throws a typed
- * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
- * `param` pointing at the offending field) and returns nothing — the
- * caller keeps its original object.
+ * Validates a write-options object against {@link writeOptionsSchema}. On
+ * failure it throws a typed {@link AbloValidationError} — with
+ * `code: 'write_options_invalid'` and a `param` pointing at the offending
+ * field — and on success returns nothing, leaving the caller's original object
+ * untouched. A `null` or `undefined` value passes.
  */
 export function assertWriteOptions(value, context) {
     if (value == null)

package/dist/client/wsMutationExecutor.d.ts

@@ -1,30 +1,25 @@
 /**
- * The default `MutationExecutor` — sends `{ type: 'commit', ... }` frames over
- * the engine's own WebSocket, resolved lazily at commit time (the WS doesn't
- * exist when the executor is constructed).
- *
- * Extracted from `Ablo.ts`; the factory wires it up with a `getWs` closure
- * over the store holder unless the caller supplies its own executor.
+ * The default {@link MutationExecutor}. It sends each change as a `commit`
+ * frame over the sync engine's own WebSocket, resolving that socket lazily at
+ * commit time because it does not exist yet when the executor is created. A
+ * client wires this up automatically unless you supply your own executor.
  */
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 import type { MutationExecutor, MutationOperation } from '../interfaces/index.js';
 /**
- * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
- * the sync engine's own WebSocket.
+ * Creates the default mutation executor, which sends each change as a `commit`
+ * frame over the sync engine's own WebSocket. The engine owns its socket, so
+ * you pass a URL and credentials rather than transport callbacks.
  *
- * Transport ownership follows the Zero / Liveblocks pattern — the engine
- * owns its socket end-to-end and the executor is internal. Apps pass URLs
- * and auth; they do NOT inject transport callbacks. That's why this
- * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
- * doesn't exist when the executor is constructed (it's created later in
- * `Ablo` during `BaseSyncedStore` init), so we resolve it
- * lazily at commit time. Same trick Zero uses internally — see
- * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
- * constructed before the socket then wired up at connect time.
+ * The factory takes a `getWs` accessor instead of a socket directly because the
+ * socket is created later during client startup and does not exist yet when
+ * this executor is constructed. The accessor is called at commit time to reach
+ * the ready socket.
  *
-     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
-     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
-     */
+ * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
+ * retrying a call with the same key is safe; otherwise the executor generates
+ * one.
+ */
 export declare function createDefaultMutationExecutor(getWs: () => {
     sendCommit?: (operations: readonly MutationOperation[], clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null) => Promise<{
         lastSyncId: number;

package/dist/client/wsMutationExecutor.js

@@ -1,30 +1,25 @@
 /**
- * The default `MutationExecutor` — sends `{ type: 'commit', ... }` frames over
- * the engine's own WebSocket, resolved lazily at commit time (the WS doesn't
- * exist when the executor is constructed).
- *
- * Extracted from `Ablo.ts`; the factory wires it up with a `getWs` closure
- * over the store holder unless the caller supplies its own executor.
+ * The default {@link MutationExecutor}. It sends each change as a `commit`
+ * frame over the sync engine's own WebSocket, resolving that socket lazily at
+ * commit time because it does not exist yet when the executor is created. A
+ * client wires this up automatically unless you supply your own executor.
  */
 import { AbloError, AbloConnectionError } from '../errors.js';
 // ── Default mutation executor (wire: `commit` frame over WebSocket) ──────
 /**
- * Default mutation executor: sends `{ type: 'commit', payload: ... }` over
- * the sync engine's own WebSocket.
+ * Creates the default mutation executor, which sends each change as a `commit`
+ * frame over the sync engine's own WebSocket. The engine owns its socket, so
+ * you pass a URL and credentials rather than transport callbacks.
  *
- * Transport ownership follows the Zero / Liveblocks pattern — the engine
- * owns its socket end-to-end and the executor is internal. Apps pass URLs
- * and auth; they do NOT inject transport callbacks. That's why this
- * factory takes a `getWs` closure instead of a full SyncWebSocket: the WS
- * doesn't exist when the executor is constructed (it's created later in
- * `Ablo` during `BaseSyncedStore` init), so we resolve it
- * lazily at commit time. Same trick Zero uses internally — see
- * `packages/zero-client/src/client/zero.ts` where `Pusher`/`Puller` are
- * constructed before the socket then wired up at connect time.
+ * The factory takes a `getWs` accessor instead of a socket directly because the
+ * socket is created later during client startup and does not exist yet when
+ * this executor is constructed. The accessor is called at commit time to reach
+ * the ready socket.
  *
-     * `options.idempotencyKey` becomes the wire-level `clientTxId` when set,
-     * matching Stripe-style retry semantics. Otherwise the SDK generates one.
-     */
+ * When set, `options.idempotencyKey` is sent as the wire-level `clientTxId`, so
+ * retrying a call with the same key is safe; otherwise the executor generates
+ * one.
+ */
 export function createDefaultMutationExecutor(getWs) {
     async function commit(operations, options) {
         const ws = getWs();
@@ -41,9 +36,8 @@ export function createDefaultMutationExecutor(getWs) {
             options?.causedByTaskId, options?.reads);
         }
         catch (err) {
-            // Wrap transport-level failures as connection errors so the
-            // TransactionQueue's retry classifier treats them as transient
-            // (matches the old HTTP path's network-error handling).
+            // Wrap transport-level failures as connection errors so the transaction
+            // queue's retry classifier treats them as transient and retries them.
             if (err instanceof AbloError)
                 throw err;
             if (err instanceof Error) {

package/dist/context.d.ts

@@ -1,9 +1,11 @@
 /**
- * Module-level context accessor
+ * Module-level accessor for the sync engine's shared context.
  *
- * Set once during SDK initialization via `initSyncEngine(context)`.
- * All internal SDK files access dependencies through `getContext()`.
- * This avoids threading context through every constructor.
+ * The context is set once, during initialization, by {@link initSyncEngine}.
+ * Code throughout the package reaches its shared dependencies — logger,
+ * observability, online-status detector, configuration, and the mutation
+ * executor — through {@link getContext} instead of receiving them through every
+ * constructor.
  */
 import type { SyncEngineContext } from './SyncEngineContext.js';
 /**

package/dist/context.js

@@ -1,9 +1,11 @@
 /**
- * Module-level context accessor
+ * Module-level accessor for the sync engine's shared context.
  *
- * Set once during SDK initialization via `initSyncEngine(context)`.
- * All internal SDK files access dependencies through `getContext()`.
- * This avoids threading context through every constructor.
+ * The context is set once, during initialization, by {@link initSyncEngine}.
+ * Code throughout the package reaches its shared dependencies — logger,
+ * observability, online-status detector, configuration, and the mutation
+ * executor — through {@link getContext} instead of receiving them through every
+ * constructor.
  */
 import { noopLogger, noopObservability, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from './SyncEngineContext.js';
 let _context = null;

package/dist/coordination/index.d.ts

@@ -1,13 +1,15 @@
 /**
- * `@abloatai/ablo/coordination` — the canonical wire schema for the three
- * coordination layers (presence, pessimistic claims, optimistic stale-context).
- * See `./schema.ts` for the model and the per-layer schemas.
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
  *
- * Explicit named list (not `export *`): every addition to schema.ts must be a
- * deliberate export decision here, so new symbols don't silently become public
- * API of the published package.
+ * Exports are listed by name rather than re-exported wholesale, so every symbol
+ * that becomes part of this package's public API is a deliberate choice.
  */
-export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
+export { targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participantKindFromWire, descriptionFromMeta, targetRefSchema, onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, commitOperationTypeSchema, commitOperationSchema, presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';
 export type { Conflict, ConflictAxis, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, ClaimHeldConflict, } from '../policy/types.js';
-export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';
+export type { TargetRange, ParticipantKind, TargetRef, OnStaleMode, WriteGuard, StaleNotification, ReadDependency, ClaimStatus, WireClaimSummary, ClaimError, WireClaim, ClaimRejection, ModelTarget, ModelClaim, ClaimBeginPayload, ClaimAbandonPayload, ClaimReorderPayload, ClaimHeartbeatPayload, ClaimHeartbeatAckPayload, ClaimHeartbeatBatchPayload, ClaimHeartbeatBatchAckPayload, UpdateSubscriptionPayload, SubscriptionAckPayload, CommitOperationType, CommitOperation, AnyCommitOperation, PresenceKind, PresenceActivity, PresenceUpdateFrame, } from './schema.js';

package/dist/coordination/index.js

@@ -1,11 +1,13 @@
 /**
- * `@abloatai/ablo/coordination` — the canonical wire schema for the three
- * coordination layers (presence, pessimistic claims, optimistic stale-context).
- * See `./schema.ts` for the model and the per-layer schemas.
+ * The `@abloatai/ablo/coordination` entry point. It re-exports the wire
+ * schemas and inferred types for the three coordination layers: presence (who
+ * is currently active), claims (taking exclusive hold of a target before
+ * writing it), and stale-context guards (rejecting a write that was based on an
+ * out-of-date read). The definitions themselves live in the sibling schema
+ * module.
  *
- * Explicit named list (not `export *`): every addition to schema.ts must be a
- * deliberate export decision here, so new symbols don't silently become public
- * API of the published package.
+ * Exports are listed by name rather than re-exported wholesale, so every symbol
+ * that becomes part of this package's public API is a deliberate choice.
  */
 // Runtime schemas + helpers.
 export { 
@@ -14,16 +16,16 @@ targetRangeSchema, participantKindSchema, wireParticipantKindSchema, participant
 // Layer 3 — optimistic stale-context
 onStaleModeSchema, writeGuardSchema, staleNotificationSchema, readDependencySchema, 
 // Layer 2 — pessimistic claim / claim-lease
-claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, 
+claimStatusSchema, wireClaimSummarySchema, claimErrorSchema, wireClaimSchema, claimRejectionSchema, modelTargetSchema, modelClaimSchema, claimBeginPayloadSchema, claimAbandonPayloadSchema, claimReorderPayloadSchema, claimHeartbeatPayloadSchema, claimHeartbeatAckPayloadSchema, claimHeartbeatBatchPayloadSchema, claimHeartbeatBatchAckPayloadSchema, 
 // Read interest — area-of-interest navigation
 updateSubscriptionPayloadSchema, subscriptionAckPayloadSchema, 
 // Commit operation — carries the optimistic write-guard
 commitOperationTypeSchema, commitOperationSchema, 
 // Layer 1 — presence
 presenceKindSchema, presenceActivitySchema, presenceUpdateFrameSchema, } from './schema.js';
-// Conflict-policy runtime — the engine detects, the policy decides. Lives in
-// `../policy/types.js` (a dependency-free leaf: its only imports are types),
-// exported here so a server-side consumer reaches the coordination vocabulary
-// AND its default resolution through one leaf subpath instead of the root
-// barrel (which would evaluate the whole browser client stack in Node).
+// Conflict-policy runtime — the engine detects a conflict, and the policy
+// decides what to do about it. These are re-exported here so that server-side
+// code can reach both the coordination vocabulary and its default conflict
+// resolution from this one subpath, without importing the full client from the
+// package root.
 export { defaultPolicy, capabilityPreemptPolicy, interpretConflictAxis } from '../policy/types.js';