@abloatai/ablo 0.34.0 → 0.35.0

package/dist/sync/awaitClaimGrant.d.ts

@@ -1,46 +1,6 @@
 /**
- * Waits for a queued claim to reach the head of the line — the client side of
- * the fair-queue handover. When a claim is contended, the server puts it in a
- * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
- * `claim_queued` frame over the WebSocket). The grant is delivered later, when
- * the claim reaches the head, as a `claim_granted` frame. This resolves once
- * that frame arrives for the given `claimId`, so the caller's `claim` promise
- * stays pending — event-driven, with no polling — until it is actually the
- * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
- * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
- *
- * It needs only a minimal `{ subscribe }` transport, so it can be tested
- * against a fake; {@link SyncWebSocket} satisfies it.
+ * Moved to the settlement core (ADR 0016): claim push is coordination, and
+ * coordination is the product. This path re-exports it so existing importers
+ * stay unchanged.
  */
-export interface GrantTransport {
-    subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
-}
-export interface ClaimGrantInfo {
-    /**
-     * True when the grant arrived as `claim_granted` — the target was held when
-     * the caller asked, and the caller waited in the FIFO line behind the holder.
-     * False for the immediate `claim_acquired`, where the target was free.
-     *
-     * Callers read this to know the row may have changed while they queued. Claim
-     * visibility is scoped to the entity, so a broad, organization-wide
-     * subscription receives no presence or claim fan-out, and the local
-     * coordination snapshot cannot be trusted to tell whether the caller waited.
-     * The grant frame itself is the authoritative signal.
-     */
-    readonly waited: boolean;
-    /**
-     * The fencing token the server minted for this grant (Option B), read off the
-     * grant frame — the authoritative source, since the token is server-stamped.
-     * `undefined` when the server does not fence (no minter wired).
-     */
-    readonly fenceToken?: number;
-}
-export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
-    timeoutMs?: number;
-    /**
-     * Backpressure: reject instead of waiting if, when we join the line, the
-     * server reports `position >= maxQueueDepth` (i.e. that many claims are
-     * already ahead of us). Omit to wait however deep the queue is.
-     */
-    maxQueueDepth?: number;
-}): Promise<ClaimGrantInfo>;
+export { awaitClaimGrant, type GrantTransport, type ClaimGrantInfo, } from '../transaction/coordination/awaitClaimGrant.js';

package/dist/sync/awaitClaimGrant.js

@@ -1,111 +1,6 @@
 /**
- * Waits for a queued claim to reach the head of the line — the client side of
- * the fair-queue handover. When a claim is contended, the server puts it in a
- * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
- * `claim_queued` frame over the WebSocket). The grant is delivered later, when
- * the claim reaches the head, as a `claim_granted` frame. This resolves once
- * that frame arrives for the given `claimId`, so the caller's `claim` promise
- * stays pending — event-driven, with no polling — until it is actually the
- * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
- * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
- *
- * It needs only a minimal `{ subscribe }` transport, so it can be tested
- * against a fake; {@link SyncWebSocket} satisfies it.
+ * Moved to the settlement core (ADR 0016): claim push is coordination, and
+ * coordination is the product. This path re-exports it so existing importers
+ * stay unchanged.
  */
-import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
-import { getContext } from '../context.js';
-/** Read the server-stamped fencing token off a grant frame, if present. */
-function readFenceToken(p) {
-    return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
-}
-export function awaitClaimGrant(transport, claimId, options) {
-    return new Promise((resolve, reject) => {
-        const unsubs = [];
-        let timer;
-        const settle = (fn) => {
-            if (timer)
-                clearTimeout(timer);
-            for (const u of unsubs)
-                u();
-            fn();
-        };
-        // The target was free → `claim_acquired` (immediate); it was contended,
-        // we waited in line, and reached the head → `claim_granted`. Either frame
-        // means the lease is now ours; `waited` records which path it was.
-        unsubs.push(transport.subscribe('claim_acquired', (p) => {
-            if (p?.claimId === claimId) {
-                getContext().logger.debug(`claim: acquired ${claimId} (target was free)`);
-                const fenceToken = readFenceToken(p);
-                settle(() => {
-                    resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
-                });
-            }
-        }));
-        unsubs.push(transport.subscribe('claim_granted', (p) => {
-            if (p?.claimId === claimId) {
-                // Promoted to the head of the line — the creator's "it's the agent's
-                // turn now" moment after waiting behind a holder.
-                getContext().logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
-                const fenceToken = readFenceToken(p);
-                settle(() => {
-                    resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
-                });
-            }
-        }));
-        if (options?.maxQueueDepth !== undefined) {
-            const max = options.maxQueueDepth;
-            unsubs.push(transport.subscribe('claim_queued', (p) => {
-                if (p?.claimId !== claimId)
-                    return;
-                const position = typeof p.position === 'number' ? p.position : 0;
-                if (position >= max) {
-                    settle(() => {
-                        reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
-                    });
-                }
-            }));
-        }
-        unsubs.push(transport.subscribe('claim_rejected', (p) => {
-            const rejection = p;
-            if (rejection.claimId !== claimId)
-                return;
-            const target = rejection.target
-                ? claimTargetLabel({
-                    model: rejection.target.entityType,
-                    id: rejection.target.entityId,
-                    field: rejection.target.field,
-                })
-                : claimId;
-            settle(() => {
-                reject(new AbloClaimedError(formatClaimedErrorMessage({
-                    targetLabel: target,
-                    heldBy: rejection.heldBy,
-                    claim: rejection.heldByClaim,
-                    policyReason: rejection.policyReason,
-                    fallback: `Claim rejected for ${target}.`,
-                }), {
-                    code: rejection.reason === 'conflict'
-                        ? 'claim_conflict'
-                        : 'claim_lease_unavailable',
-                    claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
-                }));
-            });
-        }));
-        unsubs.push(transport.subscribe('claim_lost', (p) => {
-            if (p?.claimId === claimId) {
-                settle(() => {
-                    reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
-                        code: 'claim_lost',
-                    }));
-                });
-            }
-        }));
-        if (options?.timeoutMs && options.timeoutMs > 0) {
-            timer = setTimeout(() => {
-                settle(() => {
-                    reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
-                });
-            }, options.timeoutMs);
-        }
-    });
-}
+export { awaitClaimGrant, } from '../transaction/coordination/awaitClaimGrant.js';

package/dist/sync/commitFrames.d.ts

@@ -1,42 +1,8 @@
 /**
- * Builds the outgoing frames the sync WebSocket sends on the commit path, and
- * provides the single place claim events are traced. These are stateless
- * helpers that hold no socket state, so both the transport and its frame
- * dispatch can share them.
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * commit-path frame builders are stateless wire helpers. This path re-exports
+ * them so existing importers stay unchanged. The core's `buildCommitFrame`
+ * takes the structural `CommitFrameOperation` slice, which this package's
+ * `MutationOperation` satisfies.
  */
-import type { CommitMessage } from '../wire/index.js';
-import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
-import type { MutationOperation, ClaimEvent } from '../interfaces/index.js';
-import type { StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
-/**
- * The value a commit acknowledgement resolves to. `notifications` is present
- * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
- * carries the advisory signal that lets the writer self-heal, and the same
- * signal also arrives on the `conflict:notified` event.
- */
-export type CommitAck = CanonicalCommitAck;
-/**
- * Converts the client's list of {@link MutationOperation} values into the wire
- * {@link CommitMessage} the server accepts. This is the one place the loosely
- * typed operation — its `type` is a string, and it carries client-only
- * `options` the server never reads — becomes the strict wire contract. Mapping
- * each field by hand means a change to {@link CommitOperation} fails to compile
- * here; the single `as` cast narrows the validated `type` to the wire union and
- * is the only place that loosening happens.
- */
-export declare function buildCommitFrame(operations: readonly MutationOperation[], clientTxId: string, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): CommitMessage;
-/**
- * Defensively validate the optional `notifications` array off a commit ack.
- * Untrusted wire data — a malformed entry is dropped rather than throwing,
- * so a bad notification never sinks an otherwise-successful commit.
- */
-export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
-/**
- * The single place claim events are traced. Every `claim_*` frame passes
- * through here, so a developer debugging a collision gets one consistent record
- * — a console line and a structured capture — without each frame case
- * re-deriving the row and holder shape. The wire payload is loosely typed
- * (`Record<string, unknown>`), so this is the one place that narrows it into a
- * {@link ClaimEvent}.
- */
-export declare function recordClaim(phase: ClaimEvent['phase'], payload: Record<string, unknown>): void;
+export { buildCommitFrame, parseNotifications, recordClaim, type CommitAck, type CommitFrameOperation, type ClaimTracePorts, } from '../transaction/transport/commitFrames.js';

package/dist/sync/commitFrames.js

@@ -1,99 +1,8 @@
 /**
- * Builds the outgoing frames the sync WebSocket sends on the commit path, and
- * provides the single place claim events are traced. These are stateless
- * helpers that hold no socket state, so both the transport and its frame
- * dispatch can share them.
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * commit-path frame builders are stateless wire helpers. This path re-exports
+ * them so existing importers stay unchanged. The core's `buildCommitFrame`
+ * takes the structural `CommitFrameOperation` slice, which this package's
+ * `MutationOperation` satisfies.
  */
-import { getContext } from '../context.js';
-import { staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
-import { formatClaim } from '../coordination/trace.js';
-/**
- * Converts the client's list of {@link MutationOperation} values into the wire
- * {@link CommitMessage} the server accepts. This is the one place the loosely
- * typed operation — its `type` is a string, and it carries client-only
- * `options` the server never reads — becomes the strict wire contract. Mapping
- * each field by hand means a change to {@link CommitOperation} fails to compile
- * here; the single `as` cast narrows the validated `type` to the wire union and
- * is the only place that loosening happens.
- */
-export function buildCommitFrame(operations, clientTxId, causedByTaskId, reads, track) {
-    const payload = {
-        operations: operations.map((op) => ({
-            type: op.type,
-            model: op.model,
-            id: op.id,
-            input: op.input,
-            transactionId: op.transactionId,
-            readAt: op.readAt,
-            onStale: op.onStale,
-            fenceToken: op.fenceToken,
-        })),
-        clientTxId,
-    };
-    if (causedByTaskId)
-        payload.causedByTaskId = causedByTaskId;
-    // The read set the batch was premised on: the rows or groups the writer read before committing.
-    if (reads && reads.length > 0)
-        payload.reads = [...reads];
-    // Durable read-dependencies the writer is registering: the rows or groups it
-    // wants to keep hearing about after this commit, delivered on a future receipt.
-    if (track && track.length > 0)
-        payload.track = [...track];
-    return { type: 'commit', payload };
-}
-/**
- * Defensively validate the optional `notifications` array off a commit ack.
- * Untrusted wire data — a malformed entry is dropped rather than throwing,
- * so a bad notification never sinks an otherwise-successful commit.
- */
-export function parseNotifications(raw) {
-    if (!Array.isArray(raw) || raw.length === 0)
-        return undefined;
-    const out = [];
-    for (const entry of raw) {
-        const parsed = staleNotificationSchema.safeParse(entry);
-        if (parsed.success)
-            out.push(parsed.data);
-    }
-    return out.length > 0 ? out : undefined;
-}
-/**
- * The single place claim events are traced. Every `claim_*` frame passes
- * through here, so a developer debugging a collision gets one consistent record
- * — a console line and a structured capture — without each frame case
- * re-deriving the row and holder shape. The wire payload is loosely typed
- * (`Record<string, unknown>`), so this is the one place that narrows it into a
- * {@link ClaimEvent}.
- */
-export function recordClaim(phase, payload) {
-    const str = (v) => typeof v === 'string' ? v : undefined;
-    // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
-    const target = payload.target && typeof payload.target === 'object'
-        ? payload.target
-        : payload;
-    const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
-    const event = {
-        phase,
-        claimId: str(payload.claimId),
-        model: str(target.entityType) ?? str(target.model),
-        id: str(target.entityId) ?? str(target.id),
-        field: str(target.field),
-        actor: str(payload.actor) ?? str(payload.heldBy),
-        participantKind: kind.success ? kind.data : undefined,
-        position: typeof payload.position === 'number' ? payload.position : undefined,
-        reason: str(payload.policyReason) ?? str(payload.reason),
-    };
-    const message = formatClaim(event);
-    // A rejection or lost lease is the collision a developer is actively
-    // debugging → warn (shows at the default log level). The routine events
-    // (acquired/queued/granted/expired) are debug-only so they never drown the
-    // console until you opt in with `new Ablo({ debug: true })`.
-    const isCollision = phase === 'rejected' || phase === 'lost';
-    const ctx = getContext();
-    if (isCollision)
-        ctx.logger.warn(message);
-    else
-        ctx.logger.debug(message);
-    ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
-    ctx.observability.captureClaim(event);
-}
+export { buildCommitFrame, parseNotifications, recordClaim, } from '../transaction/transport/commitFrames.js';

package/dist/sync/contextPorts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The runtime context, sliced into the ports the settlement core's transport
+ * takes. The core is injected, never service-located (ADR 0016), while this
+ * package resolves its shared dependencies through `getContext()` — so these
+ * adapters bridge the two: each method reads the context at call time, which
+ * preserves the lazy semantics of `getContext()` (a context installed after
+ * construction is still picked up, and the pre-init fallback still applies).
+ */
+import type { Logger } from '../transaction/logger.js';
+import type { SocketObservability } from '../transaction/observability.js';
+/** The context's logger, resolved at call time. */
+export declare const contextLogger: Logger;
+/** The context's observability, resolved at call time, in the transport's shape. */
+export declare const contextSocketObservability: SocketObservability;
+/** The context's online-status provider, resolved at call time. */
+export declare const contextOnlineStatus: {
+    isOnline: () => boolean;
+};

package/dist/sync/contextPorts.js

@@ -0,0 +1,31 @@
+/**
+ * The runtime context, sliced into the ports the settlement core's transport
+ * takes. The core is injected, never service-located (ADR 0016), while this
+ * package resolves its shared dependencies through `getContext()` — so these
+ * adapters bridge the two: each method reads the context at call time, which
+ * preserves the lazy semantics of `getContext()` (a context installed after
+ * construction is still picked up, and the pre-init fallback still applies).
+ */
+import { getContext } from '../context.js';
+/** The context's logger, resolved at call time. */
+export const contextLogger = {
+    debug: (message, ...args) => { getContext().logger.debug(message, ...args); },
+    info: (message, ...args) => { getContext().logger.info(message, ...args); },
+    warn: (message, ...args) => { getContext().logger.warn(message, ...args); },
+    error: (message, ...args) => { getContext().logger.error(message, ...args); },
+};
+/** The context's observability, resolved at call time, in the transport's shape. */
+export const contextSocketObservability = {
+    breadcrumb: (message, category, level, data) => {
+        getContext().observability.breadcrumb(message, category, level, data);
+    },
+    captureWebSocketError: (details) => {
+        getContext().observability.captureWebSocketError(details);
+    },
+    captureClaim: (event) => { getContext().observability.captureClaim(event); },
+    captureConflict: (event) => { getContext().observability.captureConflict(event); },
+};
+/** The context's online-status provider, resolved at call time. */
+export const contextOnlineStatus = {
+    isOnline: () => getContext().onlineStatus.isOnline(),
+};

package/dist/sync/createClaimStream.d.ts

@@ -1,51 +1,7 @@
 /**
- * Creates a {@link ClaimStream} over a live sync connection. A claim is a
- * short-lived, advisory lease a participant takes on an entity (or a field of
- * one) to signal "I'm working on this"; the stream lets you take claims, see
- * everyone else's, and watch the wait queue when a claim is contended.
- *
- * The stream is built directly on the sync WebSocket and shares that one
- * connection. It learns about other participants' claims from the same
- * `presence_update` frames the {@link createPresenceStream} presence stream
- * consumes — the server piggybacks each participant's `activeClaims` on every
- * presence frame — and sends its own claims as `claim_begin` and
- * `claim_abandon` frames.
- *
- * Wire frames:
- *   • Outbound `claim_begin` — announce a claim: `{ claimId, entityType,
- *       entityId, description, field?, estimatedMs? }`.
- *   • Outbound `claim_abandon` — release it: `{ claimId, entityType?,
- *       entityId? }`.
- *   • Inbound, via presence — `event.activeClaims`, each stamped with
- *       `declaredAt` and `expiresAt`.
- *   • Inbound `claim_rejected` — the server refused the claim, with conflict
- *       metadata.
+ * Moved to the settlement core (ADR 0016): claim push is coordination, and
+ * coordination is the product — a contending agent wants `claim_granted`
+ * pushed exactly as much as a person does. This path re-exports it so
+ * existing importers stay unchanged.
  */
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
-/**
- * The wire capability the claim stream actually uses: subscribe to typed
- * inbound frames, check liveness, and send outbound frames. `SyncWebSocket`
- * satisfies it, so production wiring is unchanged — but depending on the port
- * rather than the whole socket class lets a test drive it with a plain object,
- * no cast. `Pick` carries the exact (generic, typed-payload) `subscribe`
- * signature, so every handler stays fully typed.
- */
-export type ClaimTransport = Pick<SyncWebSocket, 'subscribe' | 'isConnected' | 'send'>;
-export interface ClaimStreamConfig {
-    /** Identity used to filter our own active claims out of `others`. */
-    participantId: string;
-}
-export interface AttachableClaimStream extends ClaimStream {
-    /**
-     * Mints a lease directly: sends the `claim_begin` frame and returns a held
-     * {@link Claim} that carries no row `data` (the resource layer reads the row
-     * and stamps it). This is an internal entry point, not part of the public
-     * {@link ClaimStream}; application code takes a claim through
-     * `ablo.<model>.claim({ id })`, which is built on this.
-     */
-    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
-    attach(transport: ClaimTransport): void;
-    dispose(): void;
-}
-export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;
+export { createClaimStream, type ClaimTransport, type ClaimStreamConfig, type AttachableClaimStream, } from '../transaction/coordination/createClaimStream.js';