@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/coordination/awaitClaimGrant.js

@@ -0,0 +1,124 @@
+/**
+ * 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; the duplex `WsTransport` satisfies it.
+ */
+import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { modelTarget } from './locator.js';
+import { noopLogger } from '../logger.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) {
+    const logger = options?.logger ?? noopLogger;
+    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) {
+                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.
+                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({
+                    ...modelTarget(rejection.target),
+                    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?.signal) {
+            const signal = options.signal;
+            const abort = () => settle(() => {
+                reject(new AbloClaimedError(`The wait for claim ${claimId} was aborted before the grant arrived.`, { code: 'claim_wait_aborted' }));
+            });
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener('abort', abort, { once: true });
+            unsubs.push(() => { signal.removeEventListener('abort', abort); });
+        }
+        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);
+        }
+    });
+}

package/dist/{client → transaction/coordination}/claimHeartbeatLoop.d.ts

@@ -23,6 +23,40 @@ import type { ClaimHeartbeat, ClaimHeartbeatOptions, Duration } from '../types/s
  * shorthand cannot drift.
  */
 export declare function resolveHeartbeatOptions(input: Duration | ClaimHeartbeatOptions | undefined): ClaimHeartbeatOptions;
+/**
+ * The structured spelling of the auto-heartbeat — cadence and both callbacks
+ * in one place, so the lease axis of a claim is two members (`ttl`,
+ * `heartbeat`) rather than four. `true` and a bare Duration remain the
+ * shorthands: `heartbeat: '2m'` ≡ `heartbeat: { every: '2m' }`.
+ */
+export interface ClaimHeartbeatPlan {
+    /** Cadence between beats. Omitted: a third of the TTL, so two beats can
+     *  fail before the lease is at risk. */
+    readonly every?: Duration;
+    /** Called after every successful beat (auto or manual) with the server's
+     *  answer — chiefly `queueDepth`, the cooperative-yield pressure signal. */
+    readonly onBeat?: (beat: ClaimHeartbeat) => void;
+    /** Called once when a beat learns the lease is no longer yours. The loop
+     *  has already stopped; abandon the work or re-claim. */
+    readonly onLost?: (error: AbloClaimedError) => void;
+}
+/** What the handle assembly reads, whichever spelling the caller used. */
+export interface ResolvedHeartbeatPlan {
+    /** Whether the auto-beat loop runs at all. */
+    readonly loop: boolean;
+    /** Feed for {@link heartbeatCadenceMs} — `true` means the TTL-derived default. */
+    readonly cadence: true | Duration;
+    readonly onBeat?: (beat: ClaimHeartbeat) => void;
+    readonly onLost?: (error: AbloClaimedError) => void;
+}
+/**
+ * One reading of the heartbeat option, shared by both transports' handle
+ * assembly — cadence and callbacks from whichever spelling the caller used
+ * (`true`, a bare Duration, or the structured plan).
+ */
+export declare function resolveHeartbeatPlan(options: {
+    readonly heartbeat?: true | Duration | ClaimHeartbeatPlan;
+}): ResolvedHeartbeatPlan;
 /**
  * The beat cadence for a lease of `ttlMs`: an explicit duration when the
  * caller set one, otherwise a third of the TTL (floored at 1s) — the

package/dist/{client → transaction/coordination}/claimHeartbeatLoop.js

@@ -30,6 +30,26 @@ export function resolveHeartbeatOptions(input) {
     }
     return input;
 }
+/**
+ * One reading of the heartbeat option, shared by both transports' handle
+ * assembly — cadence and callbacks from whichever spelling the caller used
+ * (`true`, a bare Duration, or the structured plan).
+ */
+export function resolveHeartbeatPlan(options) {
+    const { heartbeat } = options;
+    if (heartbeat !== undefined && typeof heartbeat === 'object') {
+        return {
+            loop: true,
+            cadence: heartbeat.every ?? true,
+            ...(heartbeat.onBeat ? { onBeat: heartbeat.onBeat } : {}),
+            ...(heartbeat.onLost ? { onLost: heartbeat.onLost } : {}),
+        };
+    }
+    return {
+        loop: Boolean(heartbeat),
+        cadence: heartbeat === undefined || heartbeat === true ? true : heartbeat,
+    };
+}
 /**
  * The beat cadence for a lease of `ttlMs`: an explicit duration when the
  * caller set one, otherwise a third of the TTL (floored at 1s) — the

package/dist/transaction/coordination/claimMeta.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+import type { ResolveClaimMeta } from '../types/global.js';
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export declare function declaredMeta(raw: unknown): ResolveClaimMeta;
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export declare function wireMeta(meta: unknown): Record<string, unknown>;

package/dist/transaction/coordination/claimMeta.js

@@ -0,0 +1,52 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export function declaredMeta(raw) {
+    return raw;
+}
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export function wireMeta(meta) {
+    return meta;
+}

package/dist/transaction/coordination/createClaimStream.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+import type { WsTransport } from '../transport/wsTransport.js';
+import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
+import { type Logger } from '../logger.js';
+/**
+ * The wire capability the claim stream actually uses: subscribe to typed
+ * inbound frames, check liveness, and send outbound frames. The duplex
+ * `WsTransport` 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<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
+export interface ClaimStreamConfig {
+    /** Identity used to filter our own active claims out of `others`. */
+    participantId: string;
+    /** Where the coordination trace is logged. Defaults to silent. */
+    logger?: Logger;
+}
+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;
+    /**
+     * Seeds the participant identity once the host resolves it. The stream can
+     * be built before identity is known — a hosted client learns who it is
+     * from its credential's scope during connect — and until then the
+     * construction-time id (possibly empty) would let the participant's own
+     * claims into `others`. Idempotent; later frames filter on the new id.
+     */
+    setParticipant(participant: {
+        id: string;
+    }): void;
+    dispose(): void;
+}
+export declare function createClaimStream(config: ClaimStreamConfig, transport?: ClaimTransport | null): AttachableClaimStream;