@abloatai/ablo 0.26.0 → 0.28.0

package/dist/wire/index.d.ts

@@ -1,27 +1,31 @@
 /**
- * `@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';
 export { listEnvelope } from './listEnvelope.js';
 export type { ListEnvelope } from './listEnvelope.js';
-export { commitOperationSchema, commitPayloadSchema } from './frames.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+export type { BootstrapReason } from './bootstrapReason.js';
+export { commitOperationSchema, commitPayloadSchema, commitRequestMessageSchema, commitResultMessageSchema, legacyCommitOperationSchema, legacyCommitPayloadSchema, } 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 type { CommitOperation, MutationMessage, CommitMessage, MutationResultMessage, CommitRequestMessage, CommitResultMessage, LegacyCommitOperation, LegacyCommitMessage, LegacyMutationResultMessage, } 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,45 @@
 /**
- * `@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
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+// 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.
+export { commitOperationSchema, commitPayloadSchema, commitRequestMessageSchema, commitResultMessageSchema, legacyCommitOperationSchema, legacyCommitPayloadSchema, } from './frames.js';
+// 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 {

package/dist/wire/protocol.d.ts

@@ -1,45 +1,38 @@
 /**
- * Cross-boundary protocol TIMING constants — the one place the 30s ping
- * cadence and the claim/presence lease window are defined. Before this leaf
- * existed the pair was copy-pasted across five sites in four modules, kept
- * in sync only by comments ("~3× the 30s ping"); changing the server ping
- * silently skewed the SDK's claim-expiry estimate and presence reaping.
+ * The timing constants both sides of the protocol must agree on: the ping
+ * cadence and the lease window derived from it. Defining them here once keeps
+ * the client and the server from skewing apart — a change to the ping interval
+ * that did not also move the lease window would make claim expiry and presence
+ * timeouts disagree between the two.
  *
- * Consumers (SDK side, relative import):
- *   - `sync/heartbeat.ts` — `HEARTBEAT_INTERVAL_MS`, the SDK's
- *     application-level `{ type: 'ping' }` cadence.
- *   - `client/createModelProxy.ts` — `DEFAULT_LEASE_TTL_MS`, the client's
- *     expiry estimate for a claim taken without an explicit TTL.
+ * {@link PING_INTERVAL_MS} is how often the connection pings to prove it is
+ * alive. {@link LEASE_TTL_MS} is how long a claim or presence entry stays valid
+ * without a renewing ping. On the client, these set the heartbeat cadence and
+ * the fallback expiry for a claim taken without an explicit lease. On the
+ * server, they set the keepalive interval, the lease granted per keepalive, and
+ * the presence-entry lifetime, so a silently disconnected client drops off the
+ * roster within one lease window.
  *
- * Consumers (server side, via `@abloatai/ablo/wire`):
- *   - `apps/sync-server/src/hub/Hub.ts` — the RFC 6455 `ws.ping()`
- *     keepalive interval (the tick that renews claim leases).
- *   - `apps/sync-server/src/hub/claimCoordinator.ts` —
- *     `LEASE_RENEW_TTL_MS`, the lease lifetime granted per keepalive tick.
- *   - `apps/sync-server/src/presence/PresenceStore.ts` — the default
- *     presence-entry TTL (a silently-dead client leaves the roster within
- *     one lease window).
- *
- * INVARIANT: `LEASE_TTL_MS === 3 * PING_INTERVAL_MS`. The lease is renewed
- * on every ping, so a live holder always has ≥ 2 ping intervals of runway,
- * and a silent one lapses ~2 missed pings after it stops renewing. TTL is
- * liveness, not work-duration — never widen the lease without widening the
- * ping (or holders will flap), and never derive either value locally.
+ * The lease is three ping intervals long and is renewed on every ping, so a
+ * live holder always has at least two intervals of runway and a silent one
+ * lapses about two missed pings after it stops renewing. The window measures
+ * liveness, not how long a task may run: widening the lease without also
+ * widening the ping makes holders flap, and neither value should be redefined
+ * anywhere else.
  */
 export declare const PING_INTERVAL_MS = 30000;
 export declare const LEASE_TTL_MS: number;
 /**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
  *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * A browser cannot set an `Authorization` header on a WebSocket, so the client
  * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
  * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Lives in
- * `wire/` (not `auth/`) because it IS the wire contract: client and server
- * import the same constants so the handshake format can never drift.
- * Re-exported from `auth/credentialSource.ts` for existing SDK importers.
+ * credential out of the query string, which access logs, proxies, and browser
+ * history would otherwise capture. The server reads the token from the
+ * subprotocol and echoes back only `ablo.sync.v1`, never the token-bearing
+ * value. Both the client and the server import these constants, so the
+ * handshake format cannot drift.
  */
 export declare const WS_BEARER_SUBPROTOCOL_PREFIX = "ablo.bearer.";
 export declare const WS_SYNC_SUBPROTOCOL = "ablo.sync.v1";

package/dist/wire/protocol.js

@@ -1,45 +1,38 @@
 /**
- * Cross-boundary protocol TIMING constants — the one place the 30s ping
- * cadence and the claim/presence lease window are defined. Before this leaf
- * existed the pair was copy-pasted across five sites in four modules, kept
- * in sync only by comments ("~3× the 30s ping"); changing the server ping
- * silently skewed the SDK's claim-expiry estimate and presence reaping.
+ * The timing constants both sides of the protocol must agree on: the ping
+ * cadence and the lease window derived from it. Defining them here once keeps
+ * the client and the server from skewing apart — a change to the ping interval
+ * that did not also move the lease window would make claim expiry and presence
+ * timeouts disagree between the two.
  *
- * Consumers (SDK side, relative import):
- *   - `sync/heartbeat.ts` — `HEARTBEAT_INTERVAL_MS`, the SDK's
- *     application-level `{ type: 'ping' }` cadence.
- *   - `client/createModelProxy.ts` — `DEFAULT_LEASE_TTL_MS`, the client's
- *     expiry estimate for a claim taken without an explicit TTL.
+ * {@link PING_INTERVAL_MS} is how often the connection pings to prove it is
+ * alive. {@link LEASE_TTL_MS} is how long a claim or presence entry stays valid
+ * without a renewing ping. On the client, these set the heartbeat cadence and
+ * the fallback expiry for a claim taken without an explicit lease. On the
+ * server, they set the keepalive interval, the lease granted per keepalive, and
+ * the presence-entry lifetime, so a silently disconnected client drops off the
+ * roster within one lease window.
  *
- * Consumers (server side, via `@abloatai/ablo/wire`):
- *   - `apps/sync-server/src/hub/Hub.ts` — the RFC 6455 `ws.ping()`
- *     keepalive interval (the tick that renews claim leases).
- *   - `apps/sync-server/src/hub/claimCoordinator.ts` —
- *     `LEASE_RENEW_TTL_MS`, the lease lifetime granted per keepalive tick.
- *   - `apps/sync-server/src/presence/PresenceStore.ts` — the default
- *     presence-entry TTL (a silently-dead client leaves the roster within
- *     one lease window).
- *
- * INVARIANT: `LEASE_TTL_MS === 3 * PING_INTERVAL_MS`. The lease is renewed
- * on every ping, so a live holder always has ≥ 2 ping intervals of runway,
- * and a silent one lapses ~2 missed pings after it stops renewing. TTL is
- * liveness, not work-duration — never widen the lease without widening the
- * ping (or holders will flap), and never derive either value locally.
+ * The lease is three ping intervals long and is renewed on every ping, so a
+ * live holder always has at least two intervals of runway and a silent one
+ * lapses about two missed pings after it stops renewing. The window measures
+ * liveness, not how long a task may run: widening the lease without also
+ * widening the ping makes holders flap, and neither value should be redefined
+ * anywhere else.
  */
 export const PING_INTERVAL_MS = 30_000;
 export const LEASE_TTL_MS = 3 * PING_INTERVAL_MS;
 /**
- * WebSocket subprotocols used to carry the bearer credential OUT of the URL.
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
  *
- * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * A browser cannot set an `Authorization` header on a WebSocket, so the client
  * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
  * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
- * credential out of the query string, which ALB access logs, proxies, and
- * browser history capture. The server reads the token from the subprotocol and
- * echoes back ONLY `ablo.sync.v1`, never the token-bearing value. Lives in
- * `wire/` (not `auth/`) because it IS the wire contract: client and server
- * import the same constants so the handshake format can never drift.
- * Re-exported from `auth/credentialSource.ts` for existing SDK importers.
+ * credential out of the query string, which access logs, proxies, and browser
+ * history would otherwise capture. The server reads the token from the
+ * subprotocol and echoes back only `ablo.sync.v1`, never the token-bearing
+ * value. Both the client and the server import these constants, so the
+ * handshake format cannot drift.
  */
 export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
 export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';

package/dist/wire/protocolVersion.d.ts

@@ -1,56 +1,60 @@
 /**
- * The sync protocol version — ONE monotonically increasing integer covering
- * everything client and server must agree on to speak: WS frame shapes
- * (hub `ClientMessage`/`ServerMessage`), HTTP request/response envelopes, and
- * the persisted delta encodings a client replays. Zero's recipe: schemaHash
- * (WS close 4009) only detects APP-schema drift; this detects PROTOCOL drift —
- * before it, every main-push deploy was an old-client/new-server encounter
- * with no detector at all.
+ * The sync protocol version — a single integer, increasing over time, that
+ * covers everything the client and server must agree on to talk to each other:
+ * the WebSocket frame shapes, the HTTP request and response envelopes, and the
+ * delta encodings a client replays. It is separate from the app-schema hash
+ * (WebSocket close code 4009), which detects drift in your data model; this
+ * detects drift in the protocol itself.
  *
- * Deploy contract: SERVER DEPLOYS FIRST. The server accepts every version in
- * `[MIN_SUPPORTED_PROTOCOL_VERSION, PROTOCOL_VERSION]`; a client never
- * connects to a server older than itself (if it does — a rollback mid-fleet —
- * the too-new rejection below makes it visible instead of undefined behavior).
+ * Deploy ordering: the server is deployed first. It accepts every version in
+ * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
+ * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
+ * server older than itself. If that does happen — for example a partial server
+ * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
+ * mismatch is visible rather than undefined.
  *
- * How to change the protocol:
- *   1. Make the wire change backward-tolerant where possible (the server's
- *      `clientMessageSchema` accepts-and-ignores unknown payload keys — an
- *      ADDITIVE field usually needs NO version bump).
- *   2. For a breaking change: bump `PROTOCOL_VERSION`, append a changelog
- *      entry below, and keep `MIN_SUPPORTED_PROTOCOL_VERSION` covering every
- *      SDK version still in the wild; raise it only with a deprecation window.
- *   3. The contract test (`__tests__/protocolVersion.test.ts`) fails on any
- *      bump — update it in the same change, deliberately.
+ * To change the protocol:
+ *   1. Make the change backward-tolerant where you can. The server ignores
+ *      unknown payload keys, so an additive field usually needs no version bump.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
+ *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
+ *      to cover every client still in use; raise it only after a deprecation
+ *      window.
+ *   3. The protocol-version contract test fails on any bump — update it in the
+ *      same change, deliberately.
  *
- * CHANGELOG
- *   v1 (2026-07-03) — the protocol as of the version field's introduction:
- *      sync_request{cursor,lastSyncId,capabilities,protocolVersion?},
- *      commit/mutation/claim/release/ack/presence_update frames, bootstrap +
- *      delta batches, HTTP envelopes per `wire/errorEnvelope` +
- *      `wire/listEnvelope`. Clients that predate the field send NO
- *      `protocolVersion` — treated as v1 (the field's introduction changed no
- *      semantics).
+ * Changelog
+ *   v1 (2026-07-03) — the protocol as of this field's introduction: the
+ *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
+ *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      presence-update frames, the bootstrap and delta batches, and the HTTP
+ *      error and list envelopes. A client that predates this field sends no
+ *      `protocolVersion` and is treated as v1, since introducing the field
+ *      changed no behavior.
  */
 export declare const PROTOCOL_VERSION = 1;
 /**
- * Oldest client protocol this build still serves. Raising it is a BREAKING
- * cut for un-upgraded clients — do it only with a deprecation window and a
- * changelog entry.
+ * The oldest client protocol version this build still serves. Raising it cuts
+ * off clients that have not upgraded, so do it only after a deprecation window
+ * and with a changelog entry.
  */
 export declare const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
 /**
- * WS application close code for a protocol-version rejection (4001 =
- * credential, 4009 = app-schema drift). The reason string is the error code
- * `protocol_version_unsupported`; the SDK treats this close as TERMINAL —
- * reconnecting cannot heal a version mismatch, upgrading the SDK (or rolling
- * the server forward) can.
+ * The WebSocket close code the server sends to reject a protocol-version
+ * mismatch. It sits alongside the other application close codes (4001 for a
+ * credential problem, 4009 for app-schema drift), and its reason string is the
+ * error code `protocol_version_unsupported`. A client should treat this close
+ * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
+ * client or rolling the server forward can.
  */
 export declare const WS_CLOSE_PROTOCOL_VERSION = 4010;
 /**
- * Classify a peer's announced protocol version. `undefined` (a pre-versioning
- * client) is v1 by definition. Non-integer garbage classifies as `too_old` —
- * fail closed, visibly.
+ * Classifies a peer's announced protocol version against what this build
+ * supports, returning `'too_old'`, `'too_new'`, or `null` when the versions are
+ * compatible. An `undefined` version — a client from before versioning existed
+ * — counts as v1. A non-integer value is treated as `'too_old'` so the check
+ * fails closed and visibly.
  */
 export declare function protocolVersionProblem(announced: number | undefined): 'too_old' | 'too_new' | null;
-/** HTTP request header carrying the client's protocol version. */
+/** The HTTP request header a client uses to announce its protocol version. */
 export declare const PROTOCOL_VERSION_HEADER = "Ablo-Protocol-Version";

package/dist/wire/protocolVersion.js

@@ -1,55 +1,59 @@
 /**
- * The sync protocol version — ONE monotonically increasing integer covering
- * everything client and server must agree on to speak: WS frame shapes
- * (hub `ClientMessage`/`ServerMessage`), HTTP request/response envelopes, and
- * the persisted delta encodings a client replays. Zero's recipe: schemaHash
- * (WS close 4009) only detects APP-schema drift; this detects PROTOCOL drift —
- * before it, every main-push deploy was an old-client/new-server encounter
- * with no detector at all.
+ * The sync protocol version — a single integer, increasing over time, that
+ * covers everything the client and server must agree on to talk to each other:
+ * the WebSocket frame shapes, the HTTP request and response envelopes, and the
+ * delta encodings a client replays. It is separate from the app-schema hash
+ * (WebSocket close code 4009), which detects drift in your data model; this
+ * detects drift in the protocol itself.
  *
- * Deploy contract: SERVER DEPLOYS FIRST. The server accepts every version in
- * `[MIN_SUPPORTED_PROTOCOL_VERSION, PROTOCOL_VERSION]`; a client never
- * connects to a server older than itself (if it does — a rollback mid-fleet —
- * the too-new rejection below makes it visible instead of undefined behavior).
+ * Deploy ordering: the server is deployed first. It accepts every version in
+ * the inclusive range from {@link MIN_SUPPORTED_PROTOCOL_VERSION} to
+ * {@link PROTOCOL_VERSION}, and a client is never expected to connect to a
+ * server older than itself. If that does happen — for example a partial server
+ * rollback — {@link protocolVersionProblem} reports it as `too_new` so the
+ * mismatch is visible rather than undefined.
  *
- * How to change the protocol:
- *   1. Make the wire change backward-tolerant where possible (the server's
- *      `clientMessageSchema` accepts-and-ignores unknown payload keys — an
- *      ADDITIVE field usually needs NO version bump).
- *   2. For a breaking change: bump `PROTOCOL_VERSION`, append a changelog
- *      entry below, and keep `MIN_SUPPORTED_PROTOCOL_VERSION` covering every
- *      SDK version still in the wild; raise it only with a deprecation window.
- *   3. The contract test (`__tests__/protocolVersion.test.ts`) fails on any
- *      bump — update it in the same change, deliberately.
+ * To change the protocol:
+ *   1. Make the change backward-tolerant where you can. The server ignores
+ *      unknown payload keys, so an additive field usually needs no version bump.
+ *   2. For a breaking change, bump {@link PROTOCOL_VERSION}, add a changelog
+ *      entry below, and keep {@link MIN_SUPPORTED_PROTOCOL_VERSION} low enough
+ *      to cover every client still in use; raise it only after a deprecation
+ *      window.
+ *   3. The protocol-version contract test fails on any bump — update it in the
+ *      same change, deliberately.
  *
- * CHANGELOG
- *   v1 (2026-07-03) — the protocol as of the version field's introduction:
- *      sync_request{cursor,lastSyncId,capabilities,protocolVersion?},
- *      commit/mutation/claim/release/ack/presence_update frames, bootstrap +
- *      delta batches, HTTP envelopes per `wire/errorEnvelope` +
- *      `wire/listEnvelope`. Clients that predate the field send NO
- *      `protocolVersion` — treated as v1 (the field's introduction changed no
- *      semantics).
+ * Changelog
+ *   v1 (2026-07-03) — the protocol as of this field's introduction: the
+ *      sync-request frame (`cursor`, `lastSyncId`, `capabilities`, optional
+ *      `protocolVersion`), the commit, mutation, claim, release, ack, and
+ *      presence-update frames, the bootstrap and delta batches, and the HTTP
+ *      error and list envelopes. A client that predates this field sends no
+ *      `protocolVersion` and is treated as v1, since introducing the field
+ *      changed no behavior.
  */
 export const PROTOCOL_VERSION = 1;
 /**
- * Oldest client protocol this build still serves. Raising it is a BREAKING
- * cut for un-upgraded clients — do it only with a deprecation window and a
- * changelog entry.
+ * The oldest client protocol version this build still serves. Raising it cuts
+ * off clients that have not upgraded, so do it only after a deprecation window
+ * and with a changelog entry.
  */
 export const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
 /**
- * WS application close code for a protocol-version rejection (4001 =
- * credential, 4009 = app-schema drift). The reason string is the error code
- * `protocol_version_unsupported`; the SDK treats this close as TERMINAL —
- * reconnecting cannot heal a version mismatch, upgrading the SDK (or rolling
- * the server forward) can.
+ * The WebSocket close code the server sends to reject a protocol-version
+ * mismatch. It sits alongside the other application close codes (4001 for a
+ * credential problem, 4009 for app-schema drift), and its reason string is the
+ * error code `protocol_version_unsupported`. A client should treat this close
+ * as terminal: reconnecting cannot heal a version mismatch, but upgrading the
+ * client or rolling the server forward can.
  */
 export const WS_CLOSE_PROTOCOL_VERSION = 4010;
 /**
- * Classify a peer's announced protocol version. `undefined` (a pre-versioning
- * client) is v1 by definition. Non-integer garbage classifies as `too_old` —
- * fail closed, visibly.
+ * Classifies a peer's announced protocol version against what this build
+ * supports, returning `'too_old'`, `'too_new'`, or `null` when the versions are
+ * compatible. An `undefined` version — a client from before versioning existed
+ * — counts as v1. A non-integer value is treated as `'too_old'` so the check
+ * fails closed and visibly.
  */
 export function protocolVersionProblem(announced) {
     const v = announced ?? 1;
@@ -59,5 +63,5 @@ export function protocolVersionProblem(announced) {
         return 'too_new';
     return null;
 }
-/** HTTP request header carrying the client's protocol version. */
+/** The HTTP request header a client uses to announce its protocol version. */
 export const PROTOCOL_VERSION_HEADER = 'Ablo-Protocol-Version';