@abloatai/ablo 0.25.0 → 0.26.0

package/dist/utils/mobx-setup.js

@@ -21,7 +21,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         let obj = target;
         while (obj) {
             const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor && descriptor.get)
+            if (descriptor?.get)
                 return true;
             obj = Object.getPrototypeOf(obj);
             if (obj === Object.prototype)
@@ -34,7 +34,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         let obj = target;
         while (obj) {
             const descriptor = Object.getOwnPropertyDescriptor(obj, propName);
-            if (descriptor && descriptor.set)
+            if (descriptor?.set)
                 return true;
             obj = Object.getPrototypeOf(obj);
             if (obj === Object.prototype)

package/dist/wire/errorEnvelope.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The constant public message for an unclassified 500. Mirrors
+ * `apps/sync-server/src/errors.ts`'s `INTERNAL_ERROR_PUBLIC_MESSAGE` —
+ * the parity test in apps/sync-server pins the two producers together. A raw
+ * `err.message` (driver text, connection strings, stack fragments) must never
+ * be the wire message; callers that need the detail log the original error
+ * server-side before/at the envelope call.
+ */
+export declare const INTERNAL_ERROR_PUBLIC_MESSAGE = "An internal error occurred.";
 /** The canonical wire envelope — Stripe's error-object shape. Every HTTP error
  *  response and every structured frame error carries this exact set of keys,
  *  regardless of which route or transport produced it. */
@@ -12,11 +21,11 @@ export interface ErrorEnvelope {
      *  at once (schema push, batch commit, CLI-arg validation) instead of failing
      *  on the first. `param` stays the single-field convenience case. (RFC 9457
      *  `errors[]` / JSON:API `errors[]` / Google `BadRequest.fieldViolations[]`.) */
-    readonly errors?: ReadonlyArray<{
+    readonly errors?: readonly {
         readonly code?: string;
         readonly message: string;
         readonly param?: string;
-    }>;
+    }[];
     /** Typed-details slot: `AbloError.toJSON()` spreads its `details` (e.g.
      *  `missingIds`, `conflicts`, `retryAfterSeconds`) as top-level members.
      *  Consumers MUST ignore members they don't recognize (forward-compat). */

package/dist/wire/errorEnvelope.js

@@ -18,6 +18,15 @@
  */
 import { AbloError, docUrlForCode } from '../errors.js';
 import { errorCodeSpec } from '../errorCodes.js';
+/**
+ * The constant public message for an unclassified 500. Mirrors
+ * `apps/sync-server/src/errors.ts`'s `INTERNAL_ERROR_PUBLIC_MESSAGE` —
+ * the parity test in apps/sync-server pins the two producers together. A raw
+ * `err.message` (driver text, connection strings, stack fragments) must never
+ * be the wire message; callers that need the detail log the original error
+ * server-side before/at the envelope call.
+ */
+export const INTERNAL_ERROR_PUBLIC_MESSAGE = 'An internal error occurred.';
 /** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
  *  match status semantics (a validation error is a 400, a permission error a
  *  403), so a throw site only picks the right class + code and the status
@@ -72,12 +81,15 @@ export function errorEnvelope(err, requestId) {
             status,
         };
     }
-    const message = err instanceof Error ? err.message : String(err);
+    // Unknown throw → mask. The server copy deliberately never echoes a raw
+    // message on an unclassified 500 (it can carry pg/driver/internal detail);
+    // this producer must not either — sync-web's dashboard routes serve THIS
+    // envelope to browsers. The raw error stays with the caller for logging.
     return {
         body: {
             type: 'AbloServerError',
             code: 'internal_error',
-            message,
+            message: INTERNAL_ERROR_PUBLIC_MESSAGE,
             doc_url: docUrlForCode('internal_error'),
             ...(requestId ? { request_id: requestId } : {}),
         },

package/dist/wire/frames.d.ts

@@ -18,6 +18,7 @@
  * Changing any shape here is a wire-contract change — it requires
  * coordinated client + server updates.
  */
+import { z } from 'zod';
 import type { OnStaleMode, StaleNotification, ReadDependency } from '../coordination/index.js';
 import type { ErrorCode, RequiredCapability } from '../errors.js';
 /**
@@ -50,7 +51,47 @@ export interface CommitOperation {
      * 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.
+     */
+    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.
+ */
+export declare const commitOperationSchema: z.ZodObject<{
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>>;
+    type: z.ZodEnum<{
+        CREATE: "CREATE";
+        UPDATE: "UPDATE";
+        DELETE: "DELETE";
+        ARCHIVE: "ARCHIVE";
+        UNARCHIVE: "UNARCHIVE";
+    }>;
+    model: z.ZodString;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    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}
@@ -96,6 +137,55 @@ export interface CommitMessage {
         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`.
+ */
+export declare const commitPayloadSchema: z.ZodObject<{
+    operations: z.ZodArray<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        type: z.ZodEnum<{
+            CREATE: "CREATE";
+            UPDATE: "UPDATE";
+            DELETE: "DELETE";
+            ARCHIVE: "ARCHIVE";
+            UNARCHIVE: "UNARCHIVE";
+        }>;
+        model: z.ZodString;
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    clientTxId: z.ZodString;
+    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        model: z.ZodString;
+        id: z.ZodString;
+        readAt: z.ZodNumber;
+        fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        onStale: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        group: z.ZodString;
+        readAt: z.ZodNumber;
+        onStale: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+    }, 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

package/dist/wire/frames.js

@@ -1 +1,55 @@
-export {};
+/**
+ * `@abloatai/ablo/wire` — canonical COMMIT-PATH frame contract.
+ *
+ * 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.
+ */
+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).
+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.
+ */
+export const commitOperationSchema = coordinationCommitOperationSchema.extend({
+    bypass: z.boolean().nullish(),
+});
+// z.infer-bound: the schema and the interface cannot drift in either direction.
+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`.
+ */
+export const commitPayloadSchema = z.object({
+    operations: z.array(commitOperationSchema),
+    clientTxId: z.string(),
+    causedByTaskId: z.string().nullish(),
+    reads: z.array(readDependencySchema).nullish(),
+});
+// z.infer-bound: payload schema and CommitMessage['payload'] cannot drift.
+const _commitPayloadContract = true;
+void _commitPayloadContract;

package/dist/wire/index.d.ts

@@ -19,6 +19,9 @@ 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 { 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 { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, } from '../errors.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

@@ -17,5 +17,24 @@
  */
 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
+// 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 { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, } from './protocolVersion.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, } from '../errors.js';
+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).
+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.
+export { PING_INTERVAL_MS, LEASE_TTL_MS, WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from './protocol.js';

package/dist/wire/protocol.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+ *
+ * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * 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.
+ */
+export declare const WS_BEARER_SUBPROTOCOL_PREFIX = "ablo.bearer.";
+export declare const WS_SYNC_SUBPROTOCOL = "ablo.sync.v1";

package/dist/wire/protocol.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+ *
+ * Browsers cannot set an `Authorization` header on a WebSocket, so the SDK
+ * 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.
+ */
+export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
+export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';

package/dist/wire/protocolVersion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function protocolVersionProblem(announced: number | undefined): 'too_old' | 'too_new' | null;
+/** HTTP request header carrying the client's protocol version. */
+export declare const PROTOCOL_VERSION_HEADER = "Ablo-Protocol-Version";

package/dist/wire/protocolVersion.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ *
+ * 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).
+ *
+ * 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.
+ *
+ * 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).
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export function protocolVersionProblem(announced) {
+    const v = announced ?? 1;
+    if (!Number.isInteger(v) || v < MIN_SUPPORTED_PROTOCOL_VERSION)
+        return 'too_old';
+    if (v > PROTOCOL_VERSION)
+        return 'too_new';
+    return null;
+}
+/** HTTP request header carrying the client's protocol version. */
+export const PROTOCOL_VERSION_HEADER = 'Ablo-Protocol-Version';

package/docs/api-keys.md

@@ -21,7 +21,7 @@ Pick your row:
 |---|---|---|
 | **Server / worker / CLI** (can hold a secret) | your secret `sk_` — it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
 | **Browser — read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
-| **Browser — writing as the signed-in user** | a function that fetches a short-lived per-user token from your own backend | `Ablo({ schema, apiKey: () => fetch('/api/ablo-session').then((r) => r.text()) })` |
+| **Browser — writing as the signed-in user** | `authEndpoint` — the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, authEndpoint: '/api/ablo-session' })` |
 
 That's the whole story: one knob, filled by audience.
 
@@ -48,8 +48,9 @@ session model. For a read-only app you don't need any of this — just the `pk_`
 
 Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
 code passes nothing. The secret `sk_` (and `databaseUrl`) are **server-only** — never in a
-browser bundle. There is no `getToken`, `authEndpoint`, or `as` option — `apiKey` (a string,
-or a function for the browser-write case) is the single credential knob.
+browser bundle. There is no `getToken` or `as` option — `apiKey` (the key a server holds)
+and `authEndpoint` (the mint route a browser points at) are the two credential
+knobs, and you set exactly one.
 
 ### Minting per-user / agent tokens (server-side, with your `sk_`)
 

package/docs/examples/existing-python-backend.md

@@ -67,11 +67,11 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// Browser client: no secret key — the `apiKey` resolver fetches the session
-// token your server route mints (see the session route below).
+// Browser client: no secret key — `authEndpoint` points at the session route
+// your server exposes (below); the SDK fetches and refreshes the token.
 const ablo = Ablo({
   schema,
-  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+  authEndpoint: '/api/ablo-session',
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {

package/docs/identity.md

@@ -359,10 +359,10 @@ import { schema } from '@/ablo/schema';
 export function makeAblo(user: { teamIds: string[] }) {
   return Ablo({
     schema,
-    // The browser holds no secret — the `apiKey` resolver fetches the
-    // short-lived session token your `/api/ablo-session` route minted, and the
-    // client keeps it fresh before expiry.
-    apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+    // The browser holds no secret — `authEndpoint` points at the route that
+    // mints the short-lived session token, and the client keeps it fresh
+    // before expiry.
+    authEndpoint: '/api/ablo-session',
     teamIds: user.teamIds,
   });
 }

package/docs/integration-guide.md

@@ -190,7 +190,7 @@ import { schema } from '@/ablo/schema';
 // from your session route (see below) and refreshes it before expiry.
 export const ablo = Ablo({
   schema,
-  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+  authEndpoint: '/api/ablo-session',
 });
 ```
 

package/docs/react.md

@@ -31,7 +31,7 @@ import { schema } from '@/ablo/schema';
 // from your own server route (see Identity below).
 export const ablo = Ablo({
   schema,
-  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+  authEndpoint: '/api/ablo-session',
 });
 ```
 

package/docs/sessions.md

@@ -53,7 +53,7 @@ return Response.json({ token });  // return ONLY the token to the browser
 A user session has **full data authority** within its org — no operation
 allowlist. It's the human acting as themselves.
 
-Build a browser `Ablo` client whose `getToken` fetches from that route, and pass
+Point a browser `Ablo` client's `authEndpoint` at that route, and pass
 the **instance** to [`<AbloProvider>`](/react). The client fetches the token,
 opens the connection, and re-mints before expiry — your app writes no token
 plumbing:
@@ -67,10 +67,7 @@ import { schema } from '@/ablo.schema';
 
 const ablo = Ablo({
   schema,
-  getToken: () =>
-    fetch('/api/ablo-session', { method: 'POST' })
-      .then((r) => r.json())
-      .then((d) => d.token),
+  authEndpoint: '/api/ablo-session',
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {
@@ -81,8 +78,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
 The client owns auth, the credential lifecycle, and the connection; the provider
 is the thin reactive binding over it (Stripe's `<Elements stripe={...}>` model).
 Build the client **once** at module scope — a new instance per render tears down
-the socket. `authEndpoint: '/api/ablo-session'` is accepted as sugar for the
-`getToken` fetch above if you prefer a URL.
+the socket. Need custom headers or a
+body on the exchange? `authEndpoint` also accepts an async resolver that
+returns the token.
 
 ## Agent sessions (`rk_`)