@abloatai/ablo 0.26.0 → 0.27.0

package/dist/wire/frames.d.ts

@@ -1,30 +1,24 @@
 /**
- * `@abloatai/ablo/wire` — canonical COMMIT-PATH frame contract.
+ * The write-path message shapes for the sync protocol. These cover the frames
+ * a client sends to commit work — {@link CommitMessage} (a batch of raw
+ * operations) and {@link MutationMessage} (a single named mutation) — and the
+ * server's {@link MutationResultMessage} acknowledgement. The same frames flow
+ * over a WebSocket connection and over the HTTP commit endpoint.
  *
- * These are the WebSocket (and HTTP-fallback) message shapes for the
- * write path: the client's `commit` / `mutation` frames and the server's
- * `mutation_result` ack. They live here — not in the server app and not
- * inlined in the SDK's `SyncWebSocket` — so the client, the server, and
- * any future `@abloatai/ablo/server` host all import ONE definition
- * and cannot drift.
- *
- * Scope note: the delta/sync frames (`sync_response`, `delta`) are NOT
- * here yet — they reference `SyncDelta`, which currently has two
- * definitions (server `db/deltas` vs package `core`) pending unification.
- * They stay server-local until that lands. Everything in this file
- * depends only on package-canonical types (`OnStaleMode`, `ErrorCode`,
- * `RequiredCapability`), so it is safe to share today.
- *
- * Changing any shape here is a wire-contract change — it requires
- * coordinated client + server updates.
+ * Both the client and the server import these definitions from here, so the two
+ * sides cannot drift. Each interface is paired with a Zod validator
+ * ({@link commitOperationSchema}, {@link commitPayloadSchema}) pinned to it at
+ * compile time, so the runtime check and the type stay in lockstep. Changing
+ * any shape in this file changes the wire contract and requires the client and
+ * server to update together.
  */
 import { z } from 'zod';
 import type { OnStaleMode, StaleNotification, ReadDependency } from '../coordination/index.js';
 import type { ErrorCode, RequiredCapability } from '../errors.js';
 /**
- * A single operation within a {@link CommitMessage} batch. The atomic unit
- * the server's commit executor applies (and, once the mutator seam lands,
- * the raw-op fallback path when no named mutator is registered).
+ * A single operation within a {@link CommitMessage} batch. Each operation is
+ * the smallest unit the server applies atomically — one create, update,
+ * delete, archive, or unarchive against one model row.
  */
 export interface CommitOperation {
     type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
@@ -32,45 +26,44 @@ export interface CommitOperation {
     id?: string | null;
     input?: Record<string, unknown> | null;
     /**
-     * Per-op client transaction id. Stamped onto `sync_deltas.transaction_id`
-     * so the originating client can recognize the broadcast as an echo of its
-     * own optimistic mutation. Distinct from the batch-level `clientTxId`
-     * (which keys `mutation_log` for retry idempotency).
+     * A client-generated transaction id for this one operation. The server
+     * stamps it onto the `sync_deltas.transaction_id` column so the originating
+     * client can recognize the resulting broadcast as an echo of its own
+     * optimistic write. This is distinct from the batch-level `clientTxId` on
+     * {@link CommitMessage}, which the server uses to deduplicate retried batches.
      */
     transactionId?: string | null;
     /**
-     * Watermark from `context.capture`. The server checks whether the target
-     * has received deltas since this id; if so the operation's `onStale` mode
-     * applies.
+     * A read watermark captured when the client last read this row. The server
+     * checks whether the target has changed since this point; if it has, the
+     * operation's {@link CommitOperation.onStale} mode decides what happens.
      */
     readAt?: number | null;
     /**
-     * Mode on stale detection (non-coercion). `'reject'` (default) throws
-     * AbloStaleContextError; `'overwrite'` applies unconditionally (blind LWW);
-     * `'notify'` holds the write and returns a `StaleNotification` for the actor
-     * to resolve.
+     * What to do when the server detects the row changed since
+     * {@link CommitOperation.readAt}. `'reject'` (the default) fails the
+     * operation with a stale-context error; `'overwrite'` applies the write
+     * regardless; `'notify'` holds the write and returns a
+     * {@link StaleNotification} for the caller to resolve.
      */
     onStale?: OnStaleMode | null;
     /**
-     * Write even if another participant holds a claim on this entity. The
-     * default (`false`) rejects with `AbloClaimedError` when claimed — `bypass`
-     * is the explicit, recorded override, honored only for participants the
-     * claim guard trusts (humans / framework identities; agent `bypass` is
-     * ignored). Previously honored by the server's commit executor without
-     * being declared here — the exact contract drift this file exists to
-     * prevent.
+     * Write even when another participant holds a claim on this row. The default
+     * (`false`) rejects the operation with a claimed-entity error while a claim
+     * is held. Setting `bypass` overrides that, and the override is recorded. It
+     * is honored only for participants the claim guard trusts, such as human and
+     * framework identities; a bypass requested by an agent is ignored.
      */
     bypass?: boolean | null;
 }
 /**
- * Runtime validator for {@link CommitOperation} — the per-op ingest gate both
- * commit transports (WS `commit` frame, HTTP `/v1/commits`) run before an
- * operation reaches the executor. Extends the canonical coordination-layer
- * schema (writeGuard `readAt`/`onStale`/`bypass` + op identity), widening only
- * `bypass` to `nullish` to match the interface (`boolean | null`).
- *
- * `readAt` is `z.number()` — a string watermark previously flowed into the
- * stale-guard SQL (`id > $3`) unvalidated.
+ * Runtime validator for {@link CommitOperation}. Both commit transports — the
+ * WebSocket `commit` frame and the HTTP `/v1/commits` endpoint — run this check
+ * on every operation before it is applied, so a malformed operation is rejected
+ * at the edge. It builds on the shared coordination schema, widening `bypass`
+ * to also accept `null` so the validator and the interface match exactly. Note
+ * that `readAt` must be a number: it feeds the server's stale-check comparison,
+ * so a non-numeric watermark is refused here.
  */
 export declare const commitOperationSchema: z.ZodObject<{
     readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -93,10 +86,10 @@ export declare const commitOperationSchema: z.ZodObject<{
     bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
 /**
- * Client → Server single named-mutation frame. The named-mutator write
- * primitive (claim + args), as opposed to the raw-op {@link CommitMessage}
- * batch. Server-side mutator dispatch resolves `mutatorName` against the
- * host-provided registry.
+ * A client-to-server frame that invokes a single named mutation by name and
+ * arguments, as opposed to the raw operation batch in {@link CommitMessage}.
+ * The server resolves `mutatorName` against the set of mutations registered on
+ * it and runs the matching one.
  */
 export interface MutationMessage {
     type: 'mutation';
@@ -107,10 +100,10 @@ export interface MutationMessage {
     };
 }
 /**
- * Client → Server "commit this batch of operations" frame. Formerly named
- * `batch_ack` / `BatchAckMessage` — renamed pre-stable to the customer-facing
- * verb (`commit`) consistently across the wire and the SDK method
- * (`MutationExecutor.commit`).
+ * A client-to-server frame that asks the server to commit a batch of operations
+ * atomically. This is the raw-operation counterpart to {@link MutationMessage};
+ * it carries a list of {@link CommitOperation} entries plus the batch metadata
+ * below.
  */
 export interface CommitMessage {
     type: 'commit';
@@ -118,30 +111,28 @@ export interface CommitMessage {
         operations: CommitOperation[];
         clientTxId: string;
         /**
-         * Dormant agent-task lineage field. The SDK no longer populates it —
-         * turns/tasks were removed and write attribution now rides on the
-         * claim (`claim`) id plus the server-stamped actor/capability. Kept
-         * optional for wire-compat; when present the Hub still validates and
-         * threads it onto `caused_by_task_id`, but client writes leave it
-         * `null` (the audit pane treats null as "no prompt-side context").
+         * Optional lineage id linking this batch to the task that caused it. When
+         * present, the server validates it and records it on the delta's
+         * `caused_by_task_id` column for audit trails; when omitted or `null`, the
+         * batch simply carries no task attribution.
          */
         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}`) the batch's writes were premised on; the
-         * server validates none moved since `readAt` and fires the entry's
-         * `onStale` disposition over the batch. Omitted ⇒ only write-targets are
-         * checked (legacy behavior).
+         * The reads this batch's writes were premised on. Each entry names either a
+         * specific row (`{ model, id, readAt, fields? }`) or a sync group
+         * (`{ group, readAt }`) that must not have changed since its `readAt`
+         * watermark. The server checks every entry and applies its `onStale`
+         * disposition to the whole batch if one moved. When omitted, only the rows
+         * being written are checked for staleness.
          */
         reads?: ReadDependency[] | null;
     };
 }
 /**
- * Runtime validator for {@link CommitMessage}'s payload — every field the
- * server's commit path actually honors (`operations`, `clientTxId`,
- * `causedByTaskId`, `reads`), each entry validated by
- * {@link commitOperationSchema} / the canonical `readDependencySchema`.
+ * Runtime validator for the payload of {@link CommitMessage}. It checks every
+ * field the server acts on — `operations`, `clientTxId`, `causedByTaskId`, and
+ * `reads` — validating each operation with {@link commitOperationSchema} and
+ * each read dependency with the shared read-dependency schema.
  */
 export declare const commitPayloadSchema: z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
@@ -187,13 +178,13 @@ export declare const commitPayloadSchema: z.ZodObject<{
     }, z.core.$strip>]>>>>;
 }, z.core.$strip>;
 /**
- * Wire ack for a `commit` frame. Payload mirrors the canonical
- * `CommitReceipt` shape so WebSocket, HTTP `/v1/commits`, and persisted
- * `AgentJob.result.receipt` all carry identical fields.
+ * The server's acknowledgement of a {@link CommitMessage}. Its payload mirrors
+ * the commit-receipt shape, so a commit acknowledged over a WebSocket, over the
+ * HTTP `/v1/commits` endpoint, or read back from a persisted job result all
+ * carry the same fields.
  *
- * `object`, `status`, and `ops` are typed optional because pre-unification
- * WS clients didn't ship them; servers always populate them on the way out.
- * New clients can rely on them.
+ * `object`, `status`, and `ops` are optional in the type but the server always
+ * populates them, so a current client can rely on them being present.
  */
 export interface MutationResultMessage {
     type: 'mutation_result';
@@ -206,25 +197,27 @@ export interface MutationResultMessage {
         lastSyncId?: number;
         ops?: number;
         /**
-         * Stale-context notifications for `onStale: 'notify' ops whose
-         * premise moved concurrently. Present only on a successful ack that hit a
-         * notify-resolved conflict; the client surfaces these via the
-         * `conflict:notified` event and the commit receipt instead of rejecting.
+         * Notifications for operations that used `onStale: 'notify'` and whose
+         * premise changed while the batch was being applied. Present only on a
+         * successful acknowledgement that resolved such a conflict; the client
+         * surfaces each one through its `conflict:notified` event and the commit
+         * receipt rather than failing the write.
          */
         notifications?: StaleNotification[];
         /**
-         * Ids of UPDATE/DELETE targets that matched ZERO rows (don't exist or are
-         * outside the org). Present (non-empty) only when a write missed. The
-         * client turns this into a loud `AbloNotFoundError` for the affected
-         * caller instead of treating the no-op as success.
+         * Ids of update or delete targets that matched no rows — because they do
+         * not exist or fall outside the caller's organization. Present and
+         * non-empty only when a write missed. The client raises a not-found error
+         * for the affected caller rather than treating the no-op as a success.
          */
         missingIds?: string[];
         error?: {
             code: ErrorCode;
             message: string;
             field?: string;
-            /** Structured rejection body (x402-style) emitted when the cap
-             *  verifier denies the commit. */
+            /** The capability the commit required but the caller lacked. Present when
+             *  the commit was denied for want of a capability, so the client can tell
+             *  the caller exactly what to obtain. */
             requiredCapability?: RequiredCapability;
         };
     };

package/dist/wire/frames.js

@@ -1,48 +1,41 @@
 /**
- * `@abloatai/ablo/wire` — canonical COMMIT-PATH frame contract.
+ * The write-path message shapes for the sync protocol. These cover the frames
+ * a client sends to commit work — {@link CommitMessage} (a batch of raw
+ * operations) and {@link MutationMessage} (a single named mutation) — and the
+ * server's {@link MutationResultMessage} acknowledgement. The same frames flow
+ * over a WebSocket connection and over the HTTP commit endpoint.
  *
- * These are the WebSocket (and HTTP-fallback) message shapes for the
- * write path: the client's `commit` / `mutation` frames and the server's
- * `mutation_result` ack. They live here — not in the server app and not
- * inlined in the SDK's `SyncWebSocket` — so the client, the server, and
- * any future `@abloatai/ablo/server` host all import ONE definition
- * and cannot drift.
- *
- * Scope note: the delta/sync frames (`sync_response`, `delta`) are NOT
- * here yet — they reference `SyncDelta`, which currently has two
- * definitions (server `db/deltas` vs package `core`) pending unification.
- * They stay server-local until that lands. Everything in this file
- * depends only on package-canonical types (`OnStaleMode`, `ErrorCode`,
- * `RequiredCapability`), so it is safe to share today.
- *
- * Changing any shape here is a wire-contract change — it requires
- * coordinated client + server updates.
+ * Both the client and the server import these definitions from here, so the two
+ * sides cannot drift. Each interface is paired with a Zod validator
+ * ({@link commitOperationSchema}, {@link commitPayloadSchema}) pinned to it at
+ * compile time, so the runtime check and the type stay in lockstep. Changing
+ * any shape in this file changes the wire contract and requires the client and
+ * server to update together.
  */
 import { z } from 'zod';
-// Runtime schema primitives come from the coordination LEAF module (a pure
-// zod file), not the barrel — keeps `wire/` lean (zod-leaf runtime deps only).
+// The runtime schema primitives are imported straight from the coordination
+// schema module to keep this file's runtime dependencies limited to Zod.
 import { commitOperationSchema as coordinationCommitOperationSchema, readDependencySchema, } from '../coordination/schema.js';
 /**
- * Runtime validator for {@link CommitOperation} — the per-op ingest gate both
- * commit transports (WS `commit` frame, HTTP `/v1/commits`) run before an
- * operation reaches the executor. Extends the canonical coordination-layer
- * schema (writeGuard `readAt`/`onStale`/`bypass` + op identity), widening only
- * `bypass` to `nullish` to match the interface (`boolean | null`).
- *
- * `readAt` is `z.number()` — a string watermark previously flowed into the
- * stale-guard SQL (`id > $3`) unvalidated.
+ * Runtime validator for {@link CommitOperation}. Both commit transports — the
+ * WebSocket `commit` frame and the HTTP `/v1/commits` endpoint — run this check
+ * on every operation before it is applied, so a malformed operation is rejected
+ * at the edge. It builds on the shared coordination schema, widening `bypass`
+ * to also accept `null` so the validator and the interface match exactly. Note
+ * that `readAt` must be a number: it feeds the server's stale-check comparison,
+ * so a non-numeric watermark is refused here.
  */
 export const commitOperationSchema = coordinationCommitOperationSchema.extend({
     bypass: z.boolean().nullish(),
 });
-// z.infer-bound: the schema and the interface cannot drift in either direction.
+// Pins the schema to the interface: this fails to compile if either side drifts.
 const _commitOperationContract = true;
 void _commitOperationContract;
 /**
- * Runtime validator for {@link CommitMessage}'s payload — every field the
- * server's commit path actually honors (`operations`, `clientTxId`,
- * `causedByTaskId`, `reads`), each entry validated by
- * {@link commitOperationSchema} / the canonical `readDependencySchema`.
+ * Runtime validator for the payload of {@link CommitMessage}. It checks every
+ * field the server acts on — `operations`, `clientTxId`, `causedByTaskId`, and
+ * `reads` — validating each operation with {@link commitOperationSchema} and
+ * each read dependency with the shared read-dependency schema.
  */
 export const commitPayloadSchema = z.object({
     operations: z.array(commitOperationSchema),
@@ -50,6 +43,6 @@ export const commitPayloadSchema = z.object({
     causedByTaskId: z.string().nullish(),
     reads: z.array(readDependencySchema).nullish(),
 });
-// z.infer-bound: payload schema and CommitMessage['payload'] cannot drift.
+// Pins the schema to the payload type: fails to compile if either side drifts.
 const _commitPayloadContract = true;
 void _commitPayloadContract;

package/dist/wire/index.d.ts

@@ -1,19 +1,19 @@
 /**
- * `@abloatai/ablo/wire` — the canonical HTTP/frame WIRE CONTRACT, with no
- * client-runtime (mobx / react / IndexedDB) dependency, so a server-side
- * consumer — a Next.js route handler, an edge function — can import the
- * envelope producers without pulling in the whole sync client.
+ * The wire contract for the sync protocol: the HTTP envelope shapes and the
+ * write-path frames, with no dependency on the client runtime. A server — a
+ * route handler, an edge function — can import the envelope producers here
+ * without pulling in the full sync client.
  *
- * Two halves, both Stripe-shaped and used across every Ablo surface:
- *   - ERROR egress — {@link errorEnvelope} / {@link ErrorEnvelope} /
- *     {@link statusForType} turn any thrown value into
- *     `{ type, code, param, message, doc_url, request_id }`.
- *   - LIST egress — {@link listEnvelope} / {@link ListEnvelope} stamp the
+ * It has two halves, used across every endpoint:
+ *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
+ *     {@link statusForType} turn any thrown value into the uniform
+ *     `{ type, code, param, message, doc_url, request_id }` body.
+ *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
  *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
  *
- * The {@link AbloError} hierarchy + {@link docUrlForCode} + the wire-PARSE
- * helpers are re-exported so a route can THROW the right typed error and
- * SERIALIZE it through a single import.
+ * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
+ * helpers are re-exported too, so a single import lets a route throw the right
+ * typed error and serialize it back out.
  */
 export { errorEnvelope, statusForType } from './errorEnvelope.js';
 export type { ErrorEnvelope } from './errorEnvelope.js';
@@ -22,6 +22,8 @@ export type { ListEnvelope } from './listEnvelope.js';
 export { commitOperationSchema, commitPayloadSchema } from './frames.js';
 export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, } from './protocolVersion.js';
 export type { CommitOperation, MutationMessage, CommitMessage, MutationResultMessage, } from './frames.js';
+export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './delta.js';
+export type { ParticipantKind, ConfirmationState, SyncDeltaAction, WireDeltaData, ParticipantRef, SyncDeltaWireCore, ClientSyncDelta, ServerSyncDelta, } from './delta.js';
 export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, errorCodeSpec, } from '../errors.js';
 export type { ErrorCode, WireErrorCode } from '../errors.js';
 export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';

package/dist/wire/index.js

@@ -1,40 +1,44 @@
 /**
- * `@abloatai/ablo/wire` — the canonical HTTP/frame WIRE CONTRACT, with no
- * client-runtime (mobx / react / IndexedDB) dependency, so a server-side
- * consumer — a Next.js route handler, an edge function — can import the
- * envelope producers without pulling in the whole sync client.
+ * The wire contract for the sync protocol: the HTTP envelope shapes and the
+ * write-path frames, with no dependency on the client runtime. A server — a
+ * route handler, an edge function — can import the envelope producers here
+ * without pulling in the full sync client.
  *
- * Two halves, both Stripe-shaped and used across every Ablo surface:
- *   - ERROR egress — {@link errorEnvelope} / {@link ErrorEnvelope} /
- *     {@link statusForType} turn any thrown value into
- *     `{ type, code, param, message, doc_url, request_id }`.
- *   - LIST egress — {@link listEnvelope} / {@link ListEnvelope} stamp the
+ * It has two halves, used across every endpoint:
+ *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
+ *     {@link statusForType} turn any thrown value into the uniform
+ *     `{ type, code, param, message, doc_url, request_id }` body.
+ *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
  *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
  *
- * The {@link AbloError} hierarchy + {@link docUrlForCode} + the wire-PARSE
- * helpers are re-exported so a route can THROW the right typed error and
- * SERIALIZE it through a single import.
+ * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
+ * helpers are re-exported too, so a single import lets a route throw the right
+ * typed error and serialize it back out.
  */
 export { errorEnvelope, statusForType } from './errorEnvelope.js';
 export { listEnvelope } from './listEnvelope.js';
-// Commit-path frame contract — the canonical write-path message shapes shared
-// by the SDK client, the sync-server, and any `@abloatai/ablo/server` host.
-// The runtime Zod validators live beside the interfaces (z.infer-bound so the
-// two cannot drift) — the per-op / per-payload ingest gates for both commit
+// The write-path frame contract: the message shapes shared by the client and
+// the server. The runtime Zod validators sit beside the interfaces and are
+// pinned to them, and they gate every operation and payload on both commit
 // transports.
 export { commitOperationSchema, commitPayloadSchema } from './frames.js';
-// Protocol versioning — the one integer client and server compare to know
-// they can speak, plus the typed WS rejection close code. See the module's
-// changelog + deploy contract.
+// Protocol versioning: the single integer the client and server compare to
+// confirm they can speak to each other, plus the WebSocket close code used to
+// reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
 export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, } from './protocolVersion.js';
+// The read-path delta contract: the shape the server broadcasts to clients as the
+// payload of a `delta` or `sync_response` frame, together with the shared
+// participant vocabulary it carries. Both ends derive their delta type from these
+// schemas, so the client and server cannot drift apart.
+export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './delta.js';
 // The error surface a wire consumer needs to throw, classify, and serialize.
 export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, 
-// The code→{httpStatus,retryable} registry table — dependency-free data a
-// server needs to resolve a code's canonical status exactly like the SDK's
-// wire producer does (pinned by the sync-server envelope parity test).
+// The table mapping each error code to its HTTP status and retryable flag —
+// plain data a server can use to resolve a code's canonical status the same
+// way the client's error serializer does.
 errorCodeSpec, } from '../errors.js';
-// Protocol timing constants — the 30s ping cadence + the 3×-ping claim/
-// presence lease window shared by the SDK heartbeat, the Hub keepalive,
-// the claim coordinator, and the presence reaper (see protocol.ts) — plus
-// the WS auth-handshake subprotocols shared by SyncWebSocket and the Hub.
+// Protocol timing constants — the 30-second ping cadence and the lease window
+// derived from it, shared by the client heartbeat and the server keepalive,
+// claim leasing, and presence expiry (see protocol.ts) — plus the WebSocket
+// subprotocols used during the authenticated handshake.
 export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';

package/dist/wire/listEnvelope.d.ts

@@ -1,24 +1,16 @@
 /**
- * The canonical Ablo LIST envelope — the one shape every endpoint that returns
- * a collection uses, so a consumer can detect + paginate any list uniformly
- * instead of learning a per-endpoint payload key (`{ keys }`, `{ origins }`,
- * `{ events }`, `{ buckets }`…).
+ * The envelope every endpoint that returns a collection wraps its results in.
+ * Because the shape is always the same — `{ object: 'list', data, has_more,
+ * next_cursor }` — a consumer can detect and paginate any list the same way,
+ * instead of learning a different payload key for each endpoint.
  *
- * `{ object: 'list', data: [...], has_more, next_cursor }` is the shape the
- * hosted `GET /v1/models/:model` endpoint already emits (apps/sync-server
- * `routes/query.ts`) and that `@ablo/mcp` already consumes — promoted here so
- * sync-web's dashboard lists, the SDK, and any future surface produce the
- * identical envelope from one definition.
- *
- * The field NAMES are Stripe's (`object`/`has_more`/`next_cursor`), not
- * PlanetScale's (`type`/`cursor_start`/`has_next`): the rest of the Ablo API is
- * Stripe-modeled, so this keeps one vocabulary across the surface. The
- * PlanetScale discipline we deliberately borrow is *"every list is the same
- * envelope"* — not the concrete key names.
+ * The list endpoints emit this shape and the {@link listEnvelope} helper
+ * produces it, so every list across the API reads from one definition. The
+ * generic type parameter carries the row type of `data`.
  */
 export interface ListEnvelope<T> {
-    /** Discriminator — always `'list'`. Lets a generic client recognise a
-     *  paginated collection without per-endpoint special-casing. */
+    /** Always the literal `'list'`. Lets a generic client recognize a collection
+     *  response without special-casing each endpoint. */
     readonly object: 'list';
     /** The page of results. Always present (an empty array when there are none),
      *  never omitted, so `body.data` is a stable access path. */
@@ -31,13 +23,14 @@ export interface ListEnvelope<T> {
     readonly next_cursor: string | null;
 }
 /**
- * Stamp the uniform {@link ListEnvelope} onto an already-resolved page of rows.
+ * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
  *
- * Pagination stays the caller's responsibility (fetch `limit + 1`, decide
- * `hasMore`, derive the cursor from the last row's order key) — this only
- * applies the envelope so no endpoint hand-rolls the shape. The defaults model
- * the common "small, unpaginated collection" case (`has_more: false`,
- * `next_cursor: null`); a paginated endpoint passes both explicitly.
+ * Pagination stays the caller's job — fetch one more row than the limit to
+ * decide `hasMore`, and derive the cursor from the last row's sort key. This
+ * helper only applies the envelope so no endpoint has to build the shape by
+ * hand. The defaults describe a small, unpaginated collection
+ * (`has_more: false`, `next_cursor: null`); a paginated endpoint passes both
+ * explicitly.
  */
 export declare function listEnvelope<T>(data: readonly T[], opts?: {
     hasMore?: boolean;

package/dist/wire/listEnvelope.js

@@ -1,11 +1,12 @@
 /**
- * Stamp the uniform {@link ListEnvelope} onto an already-resolved page of rows.
+ * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
  *
- * Pagination stays the caller's responsibility (fetch `limit + 1`, decide
- * `hasMore`, derive the cursor from the last row's order key) — this only
- * applies the envelope so no endpoint hand-rolls the shape. The defaults model
- * the common "small, unpaginated collection" case (`has_more: false`,
- * `next_cursor: null`); a paginated endpoint passes both explicitly.
+ * Pagination stays the caller's job — fetch one more row than the limit to
+ * decide `hasMore`, and derive the cursor from the last row's sort key. This
+ * helper only applies the envelope so no endpoint has to build the shape by
+ * hand. The defaults describe a small, unpaginated collection
+ * (`has_more: false`, `next_cursor: null`); a paginated endpoint passes both
+ * explicitly.
  */
 export function listEnvelope(data, opts = {}) {
     return {