@abloatai/ablo 0.13.0 → 0.15.0

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,12 @@ 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[];
 }

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);
+}

package/dist/source/connector.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Customer-side Data Source reverse-channel connector.
+ *
+ * The dial-out half of the reverse channel (see `connector-protocol.ts`). The
+ * customer runs this next to their database; it opens an OUTBOUND WebSocket to
+ * Ablo Cloud and serves the `commit`/`load`/`list` leg over that socket instead
+ * of receiving inbound webhooks. This is the symmetric primitive to
+ * `createPushQueue` (which already gives the `events` leg an outbound transport)
+ * and mirrors the Stripe CLI's `stripe listen`.
+ *
+ * The connector does NOT reimplement any handler logic. It wraps the SAME
+ * `(request: Request) => Promise<Response>` the customer's deployed route uses:
+ *
+ *   import { dataSource, createSourceConnector } from '@abloatai/ablo';
+ *   import { sourceOptions } from './ablo.source'; // shared with route.ts
+ *
+ *   const connector = createSourceConnector({
+ *     apiKey: process.env.ABLO_API_KEY!,
+ *     handler: dataSource(sourceOptions),
+ *   });
+ *   await connector.run(controller.signal);
+ *
+ * Each drained `request` frame is replayed into a synthesized `Request` carrying
+ * the original Standard Webhooks signature headers, so the handler verifies it
+ * through the unchanged `verifyAbloSourceRequest` — identical to the webhook
+ * path. The transport changes; the trust model does not.
+ */
+/**
+ * Reconnect backoff, in ms, indexed by consecutive failed connect attempts.
+ * Unlike the (multi-day) Standard Webhooks delivery schedule, a long-lived
+ * control socket should re-establish quickly and cap at a steady interval, so
+ * this is a short capped curve. The last entry repeats for further attempts. A
+ * clean `ready` resets the counter to 0.
+ */
+export declare const DEFAULT_RECONNECT_SCHEDULE: readonly number[];
+/**
+ * Minimal structural WebSocket surface — the browser/`globalThis.WebSocket` API,
+ * which Node 24+ implements natively. The `ws` package's default export also
+ * satisfies this (it exposes `addEventListener`). Injectable for tests.
+ */
+export interface ConnectorWebSocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: (event: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+}
+export type ConnectorWebSocketFactory = (url: string, protocols: readonly string[]) => ConnectorWebSocket;
+/** Lifecycle of the connector's socket, surfaced via `onStatus`. */
+export type ConnectorStatus = 'connecting' | 'ready' | 'disconnected';
+export interface SourceConnectorOptions {
+    /**
+     * Ablo project API key. Defaults gate to `sk_test_*` (local-dev / sandbox);
+     * an `sk_live_*` key is only accepted when the source has opted into
+     * reverse-channel for production server-side.
+     */
+    readonly apiKey: string;
+    /**
+     * The unchanged Data Source handler — `dataSource(options)` /
+     * `abloSource(options)`. The connector feeds it synthesized `Request`s and
+     * relays the `Response`s back; it never inspects or alters them.
+     */
+    readonly handler: (request: Request) => Promise<Response>;
+    /** Ablo Cloud base URL. Default `https://api.abloatai.com`. */
+    readonly baseURL?: string;
+    /** Inject a WebSocket implementation. Default `globalThis.WebSocket`. */
+    readonly webSocket?: ConnectorWebSocketFactory;
+    /** Override reconnect backoff. Default `DEFAULT_RECONNECT_SCHEDULE`. */
+    readonly reconnectSchedule?: readonly number[];
+    /** Random jitter on reconnect delays. Default ±10%. Set 0 to disable. */
+    readonly jitter?: number;
+    /** Advisory client id sent in the `register` frame for server-side logs. */
+    readonly client?: string;
+    /** Pluggable clock (tests). */
+    readonly now?: () => number;
+    /** Observe connection lifecycle transitions. */
+    readonly onStatus?: (status: ConnectorStatus) => void;
+    /** Observe non-fatal errors (decode failures, handler throws, socket errors). */
+    readonly onError?: (error: unknown) => void;
+}
+export interface SourceConnector {
+    /**
+     * Run the connect → serve → reconnect loop until `signal` aborts. Resolves
+     * when aborted. Rejects only on a fatal, non-retryable condition (e.g. no
+     * WebSocket implementation available).
+     */
+    run(signal: AbortSignal): Promise<void>;
+}
+export declare function createSourceConnector(options: SourceConnectorOptions): SourceConnector;