@abloatai/ablo 0.25.0 → 0.27.0

package/dist/wire/frames.d.ts

@@ -1,29 +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';
@@ -31,31 +26,70 @@ 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 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;
 }
 /**
- * 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.
+ * 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>>;
+    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>;
+/**
+ * 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';
@@ -66,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';
@@ -77,33 +111,80 @@ 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;
     };
 }
 /**
- * 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.
+ * 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<{
+        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>;
+/**
+ * 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';
@@ -116,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 +1,48 @@
-export {};
+/**
+ * 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.
+ *
+ * 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';
+// 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}. 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(),
+});
+// Pins the schema to the interface: this fails to compile if either side drifts.
+const _commitOperationContract = true;
+void _commitOperationContract;
+/**
+ * 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),
+    clientTxId: z.string(),
+    causedByTaskId: z.string().nullish(),
+    reads: z.array(readDependencySchema).nullish(),
+});
+// 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,24 +1,29 @@
 /**
- * `@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 { 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 { 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,21 +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';
+// 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 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, } from '../errors.js';
+export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, 
+// 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 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

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ *
+ * {@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.
+ *
+ * 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;
+/**
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
+ *
+ * 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 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

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ *
+ * {@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.
+ *
+ * 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;
+/**
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
+ *
+ * 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 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';