@abloatai/ablo 0.14.0 → 0.15.1

package/dist/index.d.ts

@@ -57,8 +57,9 @@ export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+export { createSourceConnector, type SourceConnector, type SourceConnectorOptions, type ConnectorStatus, } from './source/connector.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
@@ -67,6 +68,8 @@ export type { Environment, KeyPrefixEnvironment } from './environment.js';
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
+export type { StaleNotification, ReadDependency } from './coordination/schema.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';

package/dist/index.js

@@ -69,6 +69,10 @@ export default Ablo;
 // canonical, skip this entirely. Type counterparts live under
 // `Ablo.Source.*` (`Ablo.Source.Operation`, `Ablo.Source.Commit.Params`).
 export { dataSource, abloSource, sourceEventForOperation, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
+// Reverse-channel connector: serve the Data Source `commit`/`load`/`list` leg
+// over an OUTBOUND WebSocket (localhost / locked-down VPC, no public inbound
+// URL). The dial-out counterpart to `createPushQueue` for the `events` leg.
+export { createSourceConnector, } from './source/connector.js';
 // Schema DSL is intentionally published from `@abloatai/ablo/schema`.
 // Keeping it out of the root import preserves one clean runtime surface:
 // `import Ablo from '@abloatai/ablo'`.
@@ -80,7 +84,7 @@ export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloNotFoundError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
 export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every
@@ -90,6 +94,11 @@ export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromK
 // (e.g. an agent tool's input schema). Runtime twin of `MutationOptions`,
 // drift-guarded at compile time.
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
+// Notify-instead-of-abort signal: the value handed back to a committer whose
+// write hit a stale-context conflict under `onStale: 'notify' so its
+// agent can self-heal rather than discard work (see coordination/schema.ts and
+// docs/coordination.md → "Notify, do not abort").
+export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';

package/dist/interfaces/index.d.ts

@@ -5,6 +5,7 @@
  * Consumers implement them to wire in their own logging, observability,
  * GraphQL client, session handling, and analytics.
  */
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -140,6 +141,18 @@ export interface ModelDebugLoggerContract {
 /** Result of a successful `commit()` — server's sync cursor after the batch landed. */
 export interface CommitResult {
     lastSyncId: number;
+    /**
+     * Stale-context notifications (CoAgent/MTPO notify-instead-of-abort). Present
+     * only when a write guarded with `onStale: 'notify' collided with a
+     * concurrent change; the committer self-heals from these rather than
+     * receiving an `AbloStaleContextError`. See `StaleNotification`.
+     */
+    notifications?: StaleNotification[];
+    /**
+     * Ids of UPDATE/DELETE targets that matched ZERO rows (loud 0-row writes).
+     * Present (non-empty) only when a write missed.
+     */
+    missingIds?: string[];
 }
 /**
  * Per-call knobs attached to any mutation. Mirrors Stripe's options
@@ -159,7 +172,7 @@ export interface MutationOptions {
     label?: string;
     wait?: 'queued' | 'confirmed';
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /** Claim-pin attribution: the id (or `{ id }`) of the claim this write
      *  belongs to. Distinct from the `claim` HANDLE on the model write params —
      *  this is the low-level reference the commit carries to bypass the holder's
@@ -174,6 +187,14 @@ export interface MutationOptions {
      * id). Kept optional for wire-compat; always `null` from the client.
      */
     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}`) this write was premised on; the server validates none
+     * moved since `readAt` and fires the entry's `onStale` over the batch.
+     * Distinct from per-op `readAt` (which guards only the row being written).
+     */
+    reads?: ReadDependency[] | null;
 }
 /**
  * The `MutationOptions` subset carried per-write through the offline
@@ -208,7 +229,7 @@ export interface MutationOperation {
      */
     transactionId?: string;
     readAt?: number | null;
-    onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
     /**
      * Per-op idempotency + audit metadata. `idempotencyKey` doubles as
      * the `mutation_log.client_tx_id` cache key; `label` is persisted to

package/dist/policy/types.d.ts

@@ -39,6 +39,13 @@ export interface StaleContextConflict extends ConflictBase {
      * cosmetic field. See `docs/internal/per-field-conflict-detection.md`.
      */
     readonly conflictingFields?: readonly string[];
+    /**
+     * The committer's declared `onStale` intent for this op. The default policy
+     * honors it: `'notify'` → notify+hold, anything else → reject. A custom policy
+     * may override (e.g. gate notify on claim ownership). Absent ⇒ treat as
+     * `'reject'` (the unguarded-write default).
+     */
+    readonly requestedMode?: 'reject' | 'overwrite' | 'notify';
 }
 export interface ClaimHeldConflict extends ConflictBase {
     readonly kind: 'claim_held';
@@ -83,6 +90,22 @@ export type ConflictDecision = {
  | {
     readonly action: 'preempt';
     readonly reason?: string;
+}
+/**
+ * Notify-instead-of-abort (non-coercion). Only meaningful for a
+ * `stale_context` conflict, and the engine's aligned disposition: HOLD the
+ * conflicting op (don't write it) and return a `StaleNotification` with the
+ * current value so the actor (agent or human) resolves and re-commits. The
+ * rest of the batch still commits. Maps from `onStale: 'notify'`.
+ *
+ * Serialization order is supplied by the monotonic `sync_id` landing order
+ * (the stale committer always yields/recomputes — an asymmetry that rules out
+ * a symmetric notify-rewrite livelock). Unbounded retry is bounded by the
+ * client's reconciliation retry cap.
+ */
+ | {
+    readonly action: 'notify';
+    readonly reason?: string;
 };
 /**
  * Pluggable decision function. Sync or async.
@@ -98,9 +121,18 @@ export type ConflictDecision = {
  */
 export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
 /**
- * Default: reject every conflict. Safe fallback when no custom policy
- * is wired — the engine never silently allows a stale or
- * claim-conflicting write through.
+ * Default policy.
+ *
+ * `claim_held` conflicts always reject (a foreign claim is honored unless a
+ * privileged policy preempts). `stale_context` conflicts honor the committer's
+ * declared `onStale` intent:
+ *
+ *   • `'notify'` → notify + hold (op withheld; the actor resolves)
+ *   • anything else (incl. `'reject'`, absent) → reject
+ *
+ * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
+ * detection. This preserves the legacy always-reject default for callers that
+ * don't opt into `notify`.
  */
 export declare const defaultPolicy: ConflictPolicy;
 /**

package/dist/policy/types.js

@@ -7,14 +7,27 @@
  * Adding new shapes is additive on the discriminated union.
  */
 /**
- * Default: reject every conflict. Safe fallback when no custom policy
- * is wired — the engine never silently allows a stale or
- * claim-conflicting write through.
+ * Default policy.
+ *
+ * `claim_held` conflicts always reject (a foreign claim is honored unless a
+ * privileged policy preempts). `stale_context` conflicts honor the committer's
+ * declared `onStale` intent:
+ *
+ *   • `'notify'` → notify + hold (op withheld; the actor resolves)
+ *   • anything else (incl. `'reject'`, absent) → reject
+ *
+ * `'overwrite'` never reaches a policy — it's a hard opt-out resolved before
+ * detection. This preserves the legacy always-reject default for callers that
+ * don't opt into `notify`.
  */
-export const defaultPolicy = (conflict) => ({
-    action: 'reject',
-    reason: conflict.kind === 'stale_context' ? 'stale_context' : 'claim_conflict',
-});
+export const defaultPolicy = (conflict) => {
+    if (conflict.kind !== 'stale_context') {
+        return { action: 'reject', reason: 'claim_conflict' };
+    }
+    return conflict.requestedMode === 'notify'
+        ? { action: 'notify', reason: 'stale_notify_hold' }
+        : { action: 'reject', reason: 'stale_context' };
+};
 /**
  * Capability-gated preemption. An `claim_held` conflict is PREEMPTED when the
  * committer holds the `claim.preempt` operation in its capability allowlist

package/dist/server/commit.d.ts

@@ -16,6 +16,7 @@
 import type { ParticipantKind, ConfirmationState } from '../schema/sync-delta-row.js';
 import type { ParticipantRef } from '../schema/sync-delta-wire.js';
 import type { Environment } from '../environment.js';
+import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 export interface CommitContext {
     participantId: string;
     /**
@@ -86,6 +87,14 @@ export interface CommitContext {
      * `caused_by_task_id` when present, but client writes leave it `null`.
      */
     causedByTaskId?: string | null;
+    /**
+     * Batch-level read dependencies (the STORM read-set layer). The committer
+     * declares rows/groups it READ to form this batch; the engine validates none
+     * changed since their `readAt` and fires each entry's `onStale` disposition
+     * over the whole batch. Distinct from the per-op `readAt` guard, which only
+     * validates the rows being WRITTEN. Omit for write-target-only checking.
+     */
+    reads?: ReadDependency[] | null;
 }
 /**
  * The receipt of a commit. Pins the exact `sync_deltas` id range the batch
@@ -97,4 +106,21 @@ export interface CommitContext {
 export interface CommitResult {
     lastSyncId: number;
     firstSyncId: number;
+    /**
+     * Stale-context notifications for ops the committer guarded with
+     * `onStale: 'notify'. Present (non-empty) only when a guarded write
+     * collided with a concurrent change; the committer self-heals from these
+     * rather than receiving an `AbloStaleContextError`. See
+     * `StaleNotification` in `coordination/schema.ts`.
+     */
+    notifications?: StaleNotification[];
+    /**
+     * Ids of UPDATE/DELETE targets that matched ZERO rows — the row doesn't
+     * exist (or is outside the caller's org). The engine has always detected
+     * this (and logged it); surfacing it here lets the client turn a silent
+     * no-op into a loud `AbloNotFoundError`. Present (non-empty) only when at
+     * least one op missed. Ids are globally-unique uuids, so a caller can match
+     * its own target id against this set without ambiguity.
+     */
+    missingIds?: string[];
 }

package/dist/source/connector-protocol.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Data Source reverse-channel wire protocol.
+ *
+ * The `commit`/`load`/`list` leg of Data Source mode is normally an INBOUND
+ * webhook (Ablo Cloud → your HTTPS endpoint). That requires a public URL, so it
+ * doesn't work on `localhost` or inside a locked-down VPC with no inbound path.
+ *
+ * The reverse channel inverts the direction: the customer's connector dials OUT
+ * to Ablo Cloud over a WebSocket and serves those same requests over the open
+ * socket — the Stripe-CLI `stripe listen` pattern. This module defines the
+ * frames that travel over that socket.
+ *
+ * Trust model is unchanged. A `request` frame carries the SAME Standard Webhooks
+ * signature headers (`webhook-id` / `webhook-timestamp` / `webhook-signature`)
+ * and the SAME raw body Ablo would have POSTed, so the connector verifies it
+ * through the unchanged `verifyAbloSourceRequest`. Only the transport differs.
+ *
+ * Frames are validated with zod at the boundary (matching `contract.ts`): a
+ * malformed frame is rejected at the edge, and every wire type is inferred from
+ * one schema so the two sides can never silently drift.
+ */
+import { z } from 'zod';
+/**
+ * Wire-protocol version. Bumped on any breaking frame-shape change so an old
+ * connector talking to a new server (or vice-versa) fails fast at `register`
+ * instead of misparsing a frame mid-stream.
+ */
+export declare const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** Path the connector dials. Appended to the connector's `baseURL`. */
+export declare const SOURCE_CONNECTOR_WS_PATH = "/v1/source/listen";
+/**
+ * Negotiated WebSocket subprotocol that marks a reverse-channel source
+ * connector (vs. the SDK sync client's `ablo.sync.v1`). The server selects and
+ * echoes back ONLY this value, never the token-bearing subprotocol — keeping the
+ * credential out of ALB / proxy logs exactly like the sync socket does.
+ */
+export declare const WS_SOURCE_SUBPROTOCOL = "ablo.source.v1";
+/**
+ * Build the `Sec-WebSocket-Protocol` list a connector offers: the source
+ * protocol plus the bearer credential (`ablo.bearer.<apiKey>`). Browsers can't
+ * set an `Authorization` header on a WebSocket, so the API key rides as a
+ * subprotocol — the same mechanism the SDK sync client uses, read server-side by
+ * the shared `extractBearer`.
+ */
+export declare function sourceConnectorSubprotocols(apiKey: string): string[];
+/**
+ * Connector → server, first frame after the socket opens and authenticates.
+ * Auth and source resolution happen at the WS handshake from the API key; this
+ * frame only carries protocol negotiation + advisory metadata.
+ */
+export declare const registerFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegisterFrame = z.infer<typeof registerFrameSchema>;
+/**
+ * Server → connector, acknowledges a successful `register`. Echoes the resolved
+ * source identity so the connector can log/verify which source it is serving.
+ */
+export declare const readyFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, z.core.$strip>;
+export type ReadyFrame = z.infer<typeof readyFrameSchema>;
+/**
+ * Server → connector, one drained `commit`/`load`/`list` request. `headers` and
+ * `body` are byte-identical to what the inbound webhook path would have sent —
+ * the connector replays them into a synthesized `Request` so the unchanged
+ * handler verifies the signature exactly as in production.
+ */
+export declare const requestFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type RequestFrame = z.infer<typeof requestFrameSchema>;
+/**
+ * Connector → server, the handler's `Response` for one `request`. The server
+ * resolves the pending request keyed by `id` and feeds `status`/`body` back to
+ * the `SourceClient` as if an HTTP response had returned.
+ */
+export declare const responseFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type ResponseFrame = z.infer<typeof responseFrameSchema>;
+/**
+ * Either direction, out-of-band failure not tied to a single request body
+ * (auth rejected, unsupported protocol version, malformed frame). When `id` is
+ * present the error pertains to that pending request and fails it; otherwise it
+ * is a connection-level error.
+ */
+export declare const errorFrameSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ErrorFrame = z.infer<typeof errorFrameSchema>;
+export declare const connectorFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"register">;
+    protocolVersion: z.ZodNumber;
+    client: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ready">;
+    protocolVersion: z.ZodNumber;
+    sourceId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodEnum<{
+        production: "production";
+        sandbox: "sandbox";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"request">;
+    id: z.ZodString;
+    method: z.ZodLiteral<"POST">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"response">;
+    id: z.ZodString;
+    status: z.ZodNumber;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    body: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    id: z.ZodOptional<z.ZodString>;
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>], "type">;
+export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
+/** Thrown when an incoming frame fails to parse or validate. */
+export declare class ConnectorProtocolError extends Error {
+    readonly code = "source_connector_protocol_error";
+    constructor(message: string);
+}
+/** Serialize a frame for transmission. */
+export declare function encodeFrame(frame: ConnectorFrame): string;
+/**
+ * Parse + validate an incoming frame. Accepts the string or binary payloads the
+ * `ws` library / WebSocket `message` events deliver. Throws
+ * `ConnectorProtocolError` on any malformed or unknown frame so callers can
+ * reject the connection rather than act on garbage.
+ */
+export declare function decodeFrame(raw: string | ArrayBuffer | Uint8Array): ConnectorFrame;

package/dist/source/connector-protocol.js

@@ -0,0 +1,161 @@
+/**
+ * Data Source reverse-channel wire protocol.
+ *
+ * The `commit`/`load`/`list` leg of Data Source mode is normally an INBOUND
+ * webhook (Ablo Cloud → your HTTPS endpoint). That requires a public URL, so it
+ * doesn't work on `localhost` or inside a locked-down VPC with no inbound path.
+ *
+ * The reverse channel inverts the direction: the customer's connector dials OUT
+ * to Ablo Cloud over a WebSocket and serves those same requests over the open
+ * socket — the Stripe-CLI `stripe listen` pattern. This module defines the
+ * frames that travel over that socket.
+ *
+ * Trust model is unchanged. A `request` frame carries the SAME Standard Webhooks
+ * signature headers (`webhook-id` / `webhook-timestamp` / `webhook-signature`)
+ * and the SAME raw body Ablo would have POSTed, so the connector verifies it
+ * through the unchanged `verifyAbloSourceRequest`. Only the transport differs.
+ *
+ * Frames are validated with zod at the boundary (matching `contract.ts`): a
+ * malformed frame is rejected at the edge, and every wire type is inferred from
+ * one schema so the two sides can never silently drift.
+ */
+import { z } from 'zod';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+/**
+ * Wire-protocol version. Bumped on any breaking frame-shape change so an old
+ * connector talking to a new server (or vice-versa) fails fast at `register`
+ * instead of misparsing a frame mid-stream.
+ */
+export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+/** Path the connector dials. Appended to the connector's `baseURL`. */
+export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
+/**
+ * Negotiated WebSocket subprotocol that marks a reverse-channel source
+ * connector (vs. the SDK sync client's `ablo.sync.v1`). The server selects and
+ * echoes back ONLY this value, never the token-bearing subprotocol — keeping the
+ * credential out of ALB / proxy logs exactly like the sync socket does.
+ */
+export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
+/**
+ * Build the `Sec-WebSocket-Protocol` list a connector offers: the source
+ * protocol plus the bearer credential (`ablo.bearer.<apiKey>`). Browsers can't
+ * set an `Authorization` header on a WebSocket, so the API key rides as a
+ * subprotocol — the same mechanism the SDK sync client uses, read server-side by
+ * the shared `extractBearer`.
+ */
+export function sourceConnectorSubprotocols(apiKey) {
+    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
+}
+const headerRecord = z.record(z.string(), z.string());
+/**
+ * Connector → server, first frame after the socket opens and authenticates.
+ * Auth and source resolution happen at the WS handshake from the API key; this
+ * frame only carries protocol negotiation + advisory metadata.
+ */
+export const registerFrameSchema = z.object({
+    type: z.literal('register'),
+    protocolVersion: z.number().int(),
+    /**
+     * Advisory client identifier (e.g. `@abloatai/ablo@0.12.0`) for server-side
+     * logging. Not trusted for any decision.
+     */
+    client: z.string().optional(),
+});
+/**
+ * Server → connector, acknowledges a successful `register`. Echoes the resolved
+ * source identity so the connector can log/verify which source it is serving.
+ */
+export const readyFrameSchema = z.object({
+    type: z.literal('ready'),
+    protocolVersion: z.number().int(),
+    sourceId: z.string().optional(),
+    organizationId: z.string().optional(),
+    environment: z.enum(['production', 'sandbox']).optional(),
+});
+/**
+ * Server → connector, one drained `commit`/`load`/`list` request. `headers` and
+ * `body` are byte-identical to what the inbound webhook path would have sent —
+ * the connector replays them into a synthesized `Request` so the unchanged
+ * handler verifies the signature exactly as in production.
+ */
+export const requestFrameSchema = z.object({
+    type: z.literal('request'),
+    /** Correlation id; the matching `response` frame carries the same value. */
+    id: z.string().min(1),
+    method: z.literal('POST'),
+    /** Synthetic absolute URL used only to construct the `Request` object. */
+    url: z.string().min(1),
+    /** Signed Standard Webhooks headers + `Content-Type`. */
+    headers: headerRecord,
+    /** Raw JSON request body — exactly the bytes that were signed. */
+    body: z.string(),
+});
+/**
+ * Connector → server, the handler's `Response` for one `request`. The server
+ * resolves the pending request keyed by `id` and feeds `status`/`body` back to
+ * the `SourceClient` as if an HTTP response had returned.
+ */
+export const responseFrameSchema = z.object({
+    type: z.literal('response'),
+    id: z.string().min(1),
+    status: z.number().int(),
+    headers: headerRecord.optional(),
+    /** Raw JSON response body. */
+    body: z.string(),
+});
+/**
+ * Either direction, out-of-band failure not tied to a single request body
+ * (auth rejected, unsupported protocol version, malformed frame). When `id` is
+ * present the error pertains to that pending request and fails it; otherwise it
+ * is a connection-level error.
+ */
+export const errorFrameSchema = z.object({
+    type: z.literal('error'),
+    id: z.string().min(1).optional(),
+    code: z.string().min(1),
+    message: z.string(),
+});
+export const connectorFrameSchema = z.discriminatedUnion('type', [
+    registerFrameSchema,
+    readyFrameSchema,
+    requestFrameSchema,
+    responseFrameSchema,
+    errorFrameSchema,
+]);
+/** Thrown when an incoming frame fails to parse or validate. */
+export class ConnectorProtocolError extends Error {
+    code = 'source_connector_protocol_error';
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectorProtocolError';
+    }
+}
+/** Serialize a frame for transmission. */
+export function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+/**
+ * Parse + validate an incoming frame. Accepts the string or binary payloads the
+ * `ws` library / WebSocket `message` events deliver. Throws
+ * `ConnectorProtocolError` on any malformed or unknown frame so callers can
+ * reject the connection rather than act on garbage.
+ */
+export function decodeFrame(raw) {
+    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ConnectorProtocolError('Frame is not valid JSON');
+    }
+    const result = connectorFrameSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
+    }
+    return result.data;
+}
+function decodeBinary(raw) {
+    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    return new TextDecoder().decode(bytes);
+}