@abloatai/ablo 0.5.0 → 0.6.0

package/dist/sync/awaitIntentGrant.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `awaitIntentGrant` — the client side of the fair-queue handover.
+ *
+ * When a `claim` is contended, the server enqueues it and replies `queued`
+ * (HTTP 202 on `/v1/intents`, or `intent_queued` over WS). The grant is then
+ * PUSHED later over the WS as `intent_granted` when the claim reaches the head.
+ * This resolves once that frame arrives for our `intentId` — so the caller's
+ * `claim` promise stays pending (event-driven; no poll, no race) until it's
+ * actually our turn. Rejects on `intent_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
+ * lapse on disconnect, revoke) or an optional timeout.
+ *
+ * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
+ * fake; `SyncWebSocket` satisfies it structurally.
+ */
+export interface GrantTransport {
+    subscribe(event: 'intent_acquired' | 'intent_granted' | 'intent_lost' | 'intent_queued', handler: (payload: Record<string, unknown>) => void): () => void;
+}
+export declare function awaitIntentGrant(transport: GrantTransport, intentId: 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<void>;

package/dist/sync/awaitIntentGrant.js

@@ -0,0 +1,60 @@
+/**
+ * `awaitIntentGrant` — the client side of the fair-queue handover.
+ *
+ * When a `claim` is contended, the server enqueues it and replies `queued`
+ * (HTTP 202 on `/v1/intents`, or `intent_queued` over WS). The grant is then
+ * PUSHED later over the WS as `intent_granted` when the claim reaches the head.
+ * This resolves once that frame arrives for our `intentId` — so the caller's
+ * `claim` promise stays pending (event-driven; no poll, no race) until it's
+ * actually our turn. Rejects on `intent_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
+ * lapse on disconnect, revoke) or an optional timeout.
+ *
+ * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
+ * fake; `SyncWebSocket` satisfies it structurally.
+ */
+import { AbloClaimedError } from '../errors.js';
+export function awaitIntentGrant(transport, intentId, options) {
+    return new Promise((resolve, reject) => {
+        const unsubs = [];
+        let timer;
+        const settle = (fn) => {
+            if (timer)
+                clearTimeout(timer);
+            for (const u of unsubs)
+                u();
+            fn();
+        };
+        const onGrant = (p) => {
+            if (p?.intentId === intentId)
+                settle(resolve);
+        };
+        // The target was free → `intent_acquired` (immediate); it was contended,
+        // we waited in line, and reached the head → `intent_granted`. Either frame
+        // means the lease is now ours, so one await covers both grant paths.
+        unsubs.push(transport.subscribe('intent_acquired', onGrant));
+        unsubs.push(transport.subscribe('intent_granted', onGrant));
+        if (options?.maxQueueDepth !== undefined) {
+            const max = options.maxQueueDepth;
+            unsubs.push(transport.subscribe('intent_queued', (p) => {
+                if (p?.intentId !== intentId)
+                    return;
+                const position = typeof p.position === 'number' ? p.position : 0;
+                if (position >= max) {
+                    settle(() => reject(new AbloClaimedError(`Claim queue for ${intentId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' })));
+                }
+            }));
+        }
+        unsubs.push(transport.subscribe('intent_lost', (p) => {
+            if (p?.intentId === intentId) {
+                settle(() => reject(new AbloClaimedError(`Claim lost while queued for ${intentId}.`, {
+                    code: 'claim_lost',
+                })));
+            }
+        }));
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle(() => reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${intentId}.`, { code: 'grant_timeout' })));
+            }, options.timeoutMs);
+        }
+    });
+}

package/dist/sync/createIntentStream.js

@@ -29,6 +29,12 @@ export function createIntentStream(config, transport = null) {
     let intentsSnapshot = Object.freeze([]);
     // ── State: our own open intents (for re-announce on reconnect) ───
     const ownIntents = new Map();
+    // ── State: per-entity wait queues, from `intent_queue` frames ────
+    // Keyed `type:id`; the value is the FIFO line of queued intents. Powers
+    // the reactive `queue(target)` read — who's waiting and what they intend.
+    const queueByEntity = new Map();
+    const entityKey = (type, id) => `${type}:${id}`;
+    const EMPTY_QUEUE = Object.freeze([]);
     // ── Subscribers ──────────────────────────────────────────────────
     const listeners = new Set();
     const rejectionListeners = new Set();
@@ -125,6 +131,21 @@ export function createIntentStream(config, transport = null) {
                 }
             }
         }));
+        // (2b) Per-entity wait-queue snapshots. The server fans the full line
+        //      out on every queue mutation; we replace our cached line for that
+        //      entity and notify so `queue(target)` reads reactively.
+        unsubs.push(t.subscribe('intent_queue', (payload) => {
+            const p = payload;
+            if (!p.target?.type || !p.target.id)
+                return;
+            const key = entityKey(p.target.type, p.target.id);
+            const line = Array.isArray(p.queue) ? p.queue : [];
+            if (line.length === 0)
+                queueByEntity.delete(key);
+            else
+                queueByEntity.set(key, Object.freeze([...line]));
+            notifyListeners();
+        }));
         // (3) On reconnect, re-announce every open self-claim — the
         //     server's intent state is in-memory and is lost across
         //     restarts. Without this, peers would see our claims vanish
@@ -153,13 +174,24 @@ export function createIntentStream(config, transport = null) {
                 field: intent.field,
                 meta: intent.meta,
                 estimatedMs: intent.estimatedMs,
+                queue: intent.queue,
             },
         });
     }
-    function sendAbandon(intentId) {
+    function sendAbandon(intentId, intent) {
         if (!attached?.isConnected())
             return;
-        attached.send({ type: 'intent_abandon', payload: { intentId } });
+        // Carry the target so the server can dequeue us if we were only *waiting*
+        // (a queued claim isn't in the holder set it would otherwise scan). Held
+        // claims are found by intentId regardless; the target is harmless there.
+        attached.send({
+            type: 'intent_abandon',
+            payload: {
+                intentId,
+                entityType: intent?.entityType,
+                entityId: intent?.entityId,
+            },
+        });
     }
     function mintHandle(args) {
         const intentId = crypto.randomUUID();
@@ -173,6 +205,7 @@ export function createIntentStream(config, transport = null) {
             meta: args.meta,
             action: args.action,
             estimatedMs,
+            queue: args.queue,
         };
         ownIntents.set(intentId, intent);
         sendBegin(intentId, intent);
@@ -182,7 +215,7 @@ export function createIntentStream(config, transport = null) {
                 return;
             revoked = true;
             ownIntents.delete(intentId);
-            sendAbandon(intentId);
+            sendAbandon(intentId, intent);
         };
         return {
             id: intentId,
@@ -209,12 +242,17 @@ export function createIntentStream(config, transport = null) {
                 meta: resolved.meta,
                 action: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
+                queue: opts?.queue,
             });
         },
         get others() {
             return intentsSnapshot;
         },
-        subscribe: (listener) => {
+        queueFor(target) {
+            const ref = resolveTarget(target);
+            return queueByEntity.get(entityKey(ref.type, ref.id)) ?? EMPTY_QUEUE;
+        },
+        onChange: (listener) => {
             listeners.add(listener);
             return () => {
                 listeners.delete(listener);
@@ -243,6 +281,7 @@ export function createIntentStream(config, transport = null) {
             rejectionListeners.clear();
             activeByIntentId.clear();
             ownIntents.clear();
+            queueByEntity.clear();
             intentsSnapshot = Object.freeze([]);
             attached = null;
         },

package/dist/sync/createPresenceStream.js

@@ -164,7 +164,7 @@ export function createPresenceStream(config, transport = null) {
             return othersSnapshot;
         },
         othersIn: (syncGroup) => othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
-        subscribe: (listener) => {
+        onChange: (listener) => {
             listeners.add(listener);
             return () => {
                 listeners.delete(listener);

package/dist/sync/participants.d.ts

@@ -54,7 +54,7 @@ export interface ScopedPresence {
     editing(detail?: string): void;
     editing(target: PresenceTarget, detail?: string): void;
     idle(): void;
-    subscribe(listener: () => void): () => void;
+    onChange(listener: () => void): () => void;
 }
 export interface ScopedClaimOptions {
     /** Override the participant's focus target for this one claim. */
@@ -76,7 +76,7 @@ export interface ScopedIntents {
      */
     claim(opts?: ScopedClaimOptions): Claim;
     onRejected(listener: Parameters<IntentStream['onRejected']>[0]): () => void;
-    subscribe(listener: () => void): () => void;
+    onChange(listener: () => void): () => void;
 }
 export interface ParticipantFocusOptions {
     readonly activity?: 'reading' | 'viewing' | 'editing' | false;

package/dist/sync/participants.js

@@ -218,8 +218,8 @@ function createJoinedParticipant(args) {
         idle() {
             args.presence.idle();
         },
-        subscribe(listener) {
-            return args.presence.subscribe(listener);
+        onChange(listener) {
+            return args.presence.onChange(listener);
         },
     };
     const track = (handle) => {
@@ -252,8 +252,8 @@ function createJoinedParticipant(args) {
         onRejected(listener) {
             return args.intents.onRejected(listener);
         },
-        subscribe(listener) {
-            return args.intents.subscribe(listener);
+        onChange(listener) {
+            return args.intents.onChange(listener);
         },
     };
     const leave = () => {

package/dist/types/global.d.ts

@@ -1,27 +1,25 @@
 /**
- * Typed-global augmentation point for SDK consumers.
+ * Type registration point for SDK consumers.
  *
- * Consumers declare their Schema, Presence, Intents, and UserMeta ONCE in a
- * `.d.ts` file and every SDK hook — `useQuery`, `useOne`, `useMutate`,
- * `usePresence`, `useIntent` — reads its types from the resolved global.
- * No generics at call sites. No `schema` runtime arg passed per hook call.
+ * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
+ * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * resolved registration. No generics at call sites, no `schema` arg per call.
  *
- * This is the same canonical TypeScript declaration-merging pattern that
- * Next.js uses for `process.env` / `NodeJS.ProcessEnv`, that CSS Modules
- * use for `declare module '*.module.css'`, and that Liveblocks uses for
- * `interface Liveblocks`. It's a language feature, not a library trick —
- * any file in the compilation can augment the global `AbloSync` interface
- * and every consumer of the resolved types below picks up the augmentation
- * automatically.
+ * Registration is done via **module augmentation** of `@abloatai/ablo` —
+ * the same pattern TanStack Router uses for its `Register` interface. The brand
+ * lives in the module specifier, so the interface is just `Register` (not a
+ * global, not prefixed). It's a language feature, not a library trick: any file
+ * in the compilation can augment it and every resolver below picks it up.
  *
  * Consumer example:
  *
  * ```ts
- * // apps/your-app/src/ablo-sync.d.ts
+ * // apps/your-app/src/ablo.d.ts
  * import type { schema } from './your-schema';
  *
- * declare global {
- *   interface AbloSync {
+ * declare module '@abloatai/ablo' {
+ *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
  *     Intents: { editLayer: { layerId: string } };
@@ -31,17 +29,15 @@
  * export {};
  * ```
  *
- * If `AbloSync` is never declared, every resolver falls back to the
- * `DefaultSyncShape` — a loose `Record<string, unknown>` shape that keeps
- * SDK consumers compiling without typed benefits until they opt in.
+ * If `Register` is never augmented, every resolver falls back to
+ * {@link DefaultSyncShape} — a loose shape that keeps consumers compiling
+ * without typed benefits until they opt in.
  */
 /**
- * Default fallback shapes used when the consumer hasn't declared
- * `interface AbloSync`. `DefaultSyncShape.Schema` is intentionally
- * structural — it carries `{ models: Record<string, unknown> }` so hooks
- * can still validate the model key argument against *something*, just
- * without producing a typed entity shape. Once the consumer augments the
- * global, every resolver below picks up the augmented types automatically.
+ * Default fallback shapes used when the consumer hasn't augmented
+ * {@link Register}. `DefaultSyncShape.Schema` is intentionally structural — it
+ * carries `{ models: Record<string, unknown> }` so hooks can still validate the
+ * model key argument against *something*, just without a typed entity shape.
  */
 export interface DefaultSyncShape {
     readonly Schema: {
@@ -53,54 +49,49 @@ export interface DefaultSyncShape {
         readonly id: string;
     };
 }
-declare global {
-    /**
-     * Global augmentation target. Consumers augment this via
-     * `declare global { interface AbloSync { Schema: ...; Presence: ...; ... } }`.
-     * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
-     * when an expected key is absent.
-     */
-    interface AbloSync {
-    }
+/**
+ * The registration interface. Consumers augment it via
+ * `declare module '@abloatai/ablo' { interface Register { Schema: ...; … } }`.
+ * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
+ * when an expected key is absent. Exported from the package root so the module
+ * augmentation merges into this declaration.
+ */
+export interface Register {
 }
 /**
- * The consumer's schema, or the default shape if undeclared. Hooks use
- * this to type their model-key argument and to infer the entity type
- * returned from queries/mutations.
+ * The consumer's schema, or the default shape if unregistered. Hooks use this
+ * to type their model-key argument and infer the entity type returned.
  */
-export type ResolveSchema = AbloSync extends {
+export type ResolveSchema = Register extends {
     Schema: infer S;
 } ? S extends {
     models: Record<string, unknown>;
 } ? S : DefaultSyncShape['Schema'] : DefaultSyncShape['Schema'];
 /**
- * The consumer's presence shape, or the default shape if undeclared.
- * Used by `usePresence`. The shape is free-form — any serializable JSON
- * the consumer wants to broadcast per session.
+ * The consumer's presence shape, or the default if unregistered. Used by
+ * `usePresence`. Free-form — any serializable JSON broadcast per session.
  */
-export type ResolvePresence = AbloSync extends {
+export type ResolvePresence = Register extends {
     Presence: infer P;
 } ? P : DefaultSyncShape['Presence'];
 /**
- * The consumer's intent vocabulary, or the default if undeclared. Keys
- * are intent names; values are the claim payload for each intent. Used
- * by `useIntent(intentName)`.
+ * The consumer's intent vocabulary, or the default if unregistered. Keys are
+ * intent names; values are the claim payload for each intent. Used by
+ * `useIntent(intentName)`.
  */
-export type ResolveIntents = AbloSync extends {
+export type ResolveIntents = Register extends {
     Intents: infer I;
 } ? I : DefaultSyncShape['Intents'];
 /**
- * The consumer's user-metadata shape, or the default if undeclared.
- * Carries identity info the consumer trusts from their auth layer —
- * the SDK doesn't validate this.
+ * The consumer's user-metadata shape, or the default if unregistered. Carries
+ * identity info the consumer trusts from their auth layer — not SDK-validated.
  */
-export type ResolveUserMeta = AbloSync extends {
+export type ResolveUserMeta = Register extends {
     UserMeta: infer U;
 } ? U : DefaultSyncShape['UserMeta'];
 /**
- * The keys of the consumer's schema models. `useQuery(modelKey)` narrows
- * its first argument to this union, so unknown key literals fail at
- * compile time.
+ * The keys of the consumer's schema models. `useQuery(modelKey)` narrows its
+ * first argument to this union, so unknown key literals fail at compile time.
  */
 export type ResolveModelKey = ResolveSchema extends {
     models: infer M;

package/dist/types/global.js

@@ -1,27 +1,25 @@
 /**
- * Typed-global augmentation point for SDK consumers.
+ * Type registration point for SDK consumers.
  *
- * Consumers declare their Schema, Presence, Intents, and UserMeta ONCE in a
- * `.d.ts` file and every SDK hook — `useQuery`, `useOne`, `useMutate`,
- * `usePresence`, `useIntent` — reads its types from the resolved global.
- * No generics at call sites. No `schema` runtime arg passed per hook call.
+ * A consumer registers their Schema, Presence, Intents, and UserMeta ONCE by
+ * augmenting the {@link Register} interface, and every SDK hook — `useAblo`,
+ * `useQuery`, `useOne`, `usePresence`, `useIntent` — reads its types from the
+ * resolved registration. No generics at call sites, no `schema` arg per call.
  *
- * This is the same canonical TypeScript declaration-merging pattern that
- * Next.js uses for `process.env` / `NodeJS.ProcessEnv`, that CSS Modules
- * use for `declare module '*.module.css'`, and that Liveblocks uses for
- * `interface Liveblocks`. It's a language feature, not a library trick —
- * any file in the compilation can augment the global `AbloSync` interface
- * and every consumer of the resolved types below picks up the augmentation
- * automatically.
+ * Registration is done via **module augmentation** of `@abloatai/ablo` —
+ * the same pattern TanStack Router uses for its `Register` interface. The brand
+ * lives in the module specifier, so the interface is just `Register` (not a
+ * global, not prefixed). It's a language feature, not a library trick: any file
+ * in the compilation can augment it and every resolver below picks it up.
  *
  * Consumer example:
  *
  * ```ts
- * // apps/your-app/src/ablo-sync.d.ts
+ * // apps/your-app/src/ablo.d.ts
  * import type { schema } from './your-schema';
  *
- * declare global {
- *   interface AbloSync {
+ * declare module '@abloatai/ablo' {
+ *   interface Register {
  *     Schema: typeof schema;
  *     Presence: { cursor: { x: number; y: number } | null };
  *     Intents: { editLayer: { layerId: string } };
@@ -31,8 +29,8 @@
  * export {};
  * ```
  *
- * If `AbloSync` is never declared, every resolver falls back to the
- * `DefaultSyncShape` — a loose `Record<string, unknown>` shape that keeps
- * SDK consumers compiling without typed benefits until they opt in.
+ * If `Register` is never augmented, every resolver falls back to
+ * {@link DefaultSyncShape} — a loose shape that keeps consumers compiling
+ * without typed benefits until they opt in.
  */
 export {};

package/dist/types/streams.d.ts

@@ -175,7 +175,7 @@ export interface PresenceStream {
     /**
      * Reactive view of every OTHER participant's current activity on
      * this participant's sync groups. Reads return the current snapshot;
-     * pair with `subscribe(listener)` below to get notified on changes.
+     * pair with `onChange(listener)` below to get notified on changes.
      *
      * An LLM pipeline can include `presence.others` in its system prompt
      * so the model literally reasons with knowledge of what other
@@ -209,7 +209,7 @@ export interface PresenceStream {
      * });
      * ```
      */
-    subscribe(listener: () => void): () => void;
+    onChange(listener: () => void): () => void;
     /**
      * Async-iterable view of the peer roster. Each iteration yields the
      * current `others` snapshot on every mutation — so the consumer
@@ -371,6 +371,15 @@ export interface ClaimOptions extends IntentOptions {
      * app-specific phases.
      */
     readonly reason?: string;
+    /**
+     * Join the server's fair FIFO queue on contention instead of being
+     * rejected. The grant arrives asynchronously (`intent_acquired` if the
+     * target was free, `intent_granted` once promoted to the head of the line).
+     * The low-level `claim` returns its handle immediately regardless; callers
+     * that need to *wait* for the grant use the awaiting wrappers
+     * (`ablo.<model>.claim`), which pair this flag with `awaitIntentGrant`.
+     */
+    readonly queue?: boolean;
 }
 export interface IntentStream {
     /**
@@ -394,6 +403,14 @@ export interface IntentStream {
      * below to get notified on change.
      */
     readonly others: ReadonlyArray<ActiveIntent>;
+    /**
+     * Reactive view of the wait queue on one target — the FIFO line of
+     * `status: 'queued'` intents behind the current holder, each with its
+     * `action`, `heldBy`, and `position`. Synced from the server's per-entity
+     * `intent_queue` frame; empty when no one's waiting. Pair with
+     * `subscribe(...)` for change notifications.
+     */
+    queueFor(target: PresenceTarget): readonly Intent[];
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -401,7 +418,7 @@ export interface IntentStream {
      * returns an unsubscribe fn. Use `useSyncExternalStore` in React or
      * `autorun` in MobX.
      */
-    subscribe(listener: () => void): () => void;
+    onChange(listener: () => void): () => void;
     /**
      * Observe server-side intent rejections. Fires when the server
      * rejects an `intents.writing(...)` / `announce(...)` call because
@@ -494,8 +511,13 @@ export interface ActiveIntent extends IntentDeclaration {
     readonly announcedAt: string;
     readonly expiresAt: string;
 }
-/** Every lifecycle state of a coordination intent, in one enum. */
-export type IntentStatus = 'active' | 'committed' | 'expired' | 'canceled';
+/**
+ * Every lifecycle state of a coordination intent, in one enum.
+ * `active` = the current holder (the lock). `queued` = waiting in the FIFO
+ * line behind the holder (carries `position`). The terminal states drop the
+ * intent from the synced set.
+ */
+export type IntentStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
 /** Options for waiting on a target to become free. */
 export interface IntentWaitOptions {
     readonly timeout?: number;
@@ -509,10 +531,11 @@ export interface IntentWaitOptions {
  *
  * Deliberately omits a Stripe-style `next_action`: a contender's only
  * response is "wait until free, then re-read", and the runtime performs
- * that uniformly at the tool boundary (`IntentHandle.whenFree()` + the
- * stale-context guard that forces a re-read). Encoding a constant
- * instruction the engine always takes would be the kind of ceremony this
- * object exists to remove.
+ * that uniformly — `claim` serializes behind the holder via the server
+ * FIFO queue (or low-level `intents.waitFor` to wait without claiming), and the
+ * stale-context guard forces the re-read. Encoding a constant instruction
+ * the engine always takes would be the kind of ceremony this object exists
+ * to remove.
  */
 export interface Intent {
     readonly object: 'intent';
@@ -532,4 +555,9 @@ export interface Intent {
     readonly createdAt?: string;
     /** Ms-epoch the server auto-expires it if the holder doesn't finish. */
     readonly expiresAt: string;
+    /**
+     * 0-based place in the FIFO line — present only when `status: 'queued'`
+     * (`0` = next in line behind the holder). Absent for the active holder.
+     */
+    readonly position?: number;
 }