@abloatai/ablo 0.10.1 → 0.11.0

package/dist/types/streams.d.ts

@@ -3,14 +3,14 @@
  *
  * Ablo treats humans and agents as participants on live application
  * entities. Participants announce what they are reading or editing,
- * claim intent before writing, and capture context watermarks before
+ * claim before writing, and capture context watermarks before
  * long-running AI work. The customer keeps their own schema, agent
  * stack, tools, prompts, and product policy; the sync engine provides
  * the shared coordination substrate.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
-import type { TargetRange, OnStaleMode, IntentClaim, PresenceKind } from '../coordination/schema.js';
-export type { TargetRange, OnStaleMode, IntentClaim, PresenceKind };
+import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form
  * metadata that will be persisted / transported as JSON — avoids
@@ -290,15 +290,15 @@ export interface Activity {
  * writes this shape only.
  */
 export interface Peer {
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     readonly participantId: string;
     readonly label?: string;
     readonly syncGroups: readonly string[];
     readonly activity: Activity;
     /** Server timestamp of the most recent frame from this participant. */
     readonly lastActive: string;
-    /** Pending-mutation intents this participant has declared. */
-    readonly activeIntents?: ReadonlyArray<IntentClaim>;
+    /** Pending-mutation claims this participant has declared. */
+    readonly activeClaims?: ReadonlyArray<Claim>;
 }
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
@@ -307,24 +307,24 @@ export interface PresenceUpdatePayload {
     readonly isAgent?: boolean;
 }
 /**
- * Intent broadcasts — "I'm about to do X on Y." Broadcasts flow on
+ * Claim broadcasts — "I'm about to do X on Y." Broadcasts flow on
  * the same WS as presence, so every participant sees them in real
- * time. Cooperative mutex: the intent doesn't enforce exclusion; it
+ * time. Cooperative mutex: the claim doesn't enforce exclusion; it
  * announces. Other agents observe and yield. This is cheaper and
  * more flexible than a central lock table and composes with presence.
  */
 /**
- * Options common to every verb-style intent announcement
- * (`intents.analyzing`, `.drafting`, etc.).
+ * Options common to every verb-style claim announcement
+ * (`claims.analyzing`, `.drafting`, etc.).
  *
  * The one required field is the *target* — everything else is a
- * sensible default. Prefer the verb methods in `IntentStream` below
+ * sensible default. Prefer the verb methods in `ClaimStream` below
  * (`analyzing(entity, { ttl: '3m' })`) over the raw `announce(...)`
  * escape hatch.
  */
-export interface IntentOptions {
+export interface ClaimLeaseOptions {
     /**
-     * How long before the server auto-expires this intent if the
+     * How long before the server auto-expires this claim if the
      * participant doesn't finish the work. Accepts either a number (in
      * seconds — back-compat with `ttlSeconds`) or a duration string:
      * `'500ms'`, `'30s'`, `'3m'`, `'24h'`.
@@ -333,7 +333,7 @@ export interface IntentOptions {
 }
 /** Re-export of the duration helper shape. See `./duration.ts`. */
 export type Duration = import('../utils/duration.js').Duration;
-export interface ClaimOptions extends IntentOptions {
+export interface ClaimOptions extends ClaimLeaseOptions {
     /**
      * Free-form reason describing why you're claiming. Surfaces in conflict
      * messages and the activity overlay. Defaults to `'editing'`. Common
@@ -349,21 +349,21 @@ export interface ClaimOptions extends IntentOptions {
     readonly description?: 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).
+     * rejected. The grant arrives asynchronously (`claim_acquired` if the
+     * target was free, `claim_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`.
+     * (`ablo.<model>.claim`), which pair this flag with `awaitClaimGrant`.
      */
     readonly queue?: boolean;
 }
-export interface IntentStream {
+export interface ClaimStream {
     /**
-     * Claim an exclusive intent on a target. Returns a handle — call
+     * Claim an exclusive claim on a target. Returns a handle — call
      * `.revoke()` to cancel, let it expire via TTL, or use `await using`
      * (TC39 explicit resource management) to auto-revoke on scope exit.
      *
-     * Server rejects via `intent_rejected` when another participant
+     * Server rejects via `claim_rejected` when another participant
      * already holds a claim on the same target. Default `reason` is
      * `'editing'`; pass `{reason: 'writing'}` (or any string) to override.
      *
@@ -372,30 +372,30 @@ export interface IntentStream {
      * scoped `claim(reason, opts)` overload were collapsed into this
      * single primitive.
      */
-    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+    claim(target: PresenceTarget, opts?: ClaimOptions): ClaimHandle;
     /**
-     * Reactive view of every other participant's active intents.
+     * Reactive view of every other participant's active claims.
      * Reads return the current snapshot; pair with `subscribe(...)`
      * below to get notified on change.
      */
-    readonly others: ReadonlyArray<ActiveIntent>;
+    readonly others: ReadonlyArray<ActiveClaim>;
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
-     * `status: 'queued'` intents behind the current holder, each with its
+     * `status: 'queued'` claims 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
+     * `claim_queue` frame; empty when no one's waiting. Pair with
      * `subscribe(...)` for change notifications.
      */
-    queueFor(target: PresenceTarget): readonly Intent[];
+    queueFor(target: PresenceTarget): readonly Claim[];
     /**
      * Re-rank the wait queue on a target — move the listed waiters to the front
      * in the given order; unlisted waiters keep their relative FIFO order behind
-     * them. Pass the `Intent[]` from `queueFor(target)` in the order you want
-     * (each `Intent` carries its `heldBy` + `id`). Privileged: the server gates
-     * it (a participant lacking the `intent.reorder` capability is denied), so
+     * them. Pass the `Claim[]` from `queueFor(target)` in the order you want
+     * (each `Claim` carries its `heldBy` + `id`). Privileged: the server gates
+     * it (a participant lacking the `claim.reorder` capability is denied), so
      * this is fire-and-forget — the new order arrives reactively via `queueFor`.
      */
-    reorder(target: PresenceTarget, order: readonly Intent[]): void;
+    reorder(target: PresenceTarget, order: readonly Claim[]): void;
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -405,30 +405,30 @@ export interface IntentStream {
      */
     onChange(listener: () => void): () => void;
     /**
-     * Observe server-side intent rejections. Fires when the server
-     * rejects an `intents.writing(...)` / `announce(...)` call because
+     * Observe server-side claim rejections. Fires when the server
+     * rejects an `claims.writing(...)` / `announce(...)` call because
      * another participant already holds an open claim on the same
      * target (cooperative mutex → enforced at the server boundary).
      *
      * Use this to surface conflicts to the user:
      * ```ts
-     * participant.intents.onRejected((r) => {
+     * participant.claims.onRejected((r) => {
      *   toast.error(`${r.heldBy} is editing — try again in a moment`);
      * });
      * ```
      *
      * Returns an unsubscribe fn.
      */
-    onRejected(listener: (rejection: IntentRejection) => void): () => void;
+    onRejected(listener: (rejection: ClaimRejection) => void): () => void;
     /**
-     * Observe LOSING an intent you held — distinct from `onRejected` (a claim the
-     * server refused). Fires on the server's `intent_lost` frame, carrying why:
+     * Observe LOSING an claim you held — distinct from `onRejected` (a claim the
+     * server refused). Fires on the server's `claim_lost` frame, carrying why:
      * `'preempted'` (a privileged participant evicted you) or `'expired'` (your
      * TTL lapsed). Lets a holder react — re-plan vs re-claim — instead of
      * silently discovering the lease gone via presence.
      *
      * ```ts
-     * participant.intents.onLost((lost) => {
+     * participant.claims.onLost((lost) => {
      *   if (lost.reason === 'preempted') replanAgainst(lost.target);
      *   else reclaim(lost.target);
      * });
@@ -436,55 +436,29 @@ export interface IntentStream {
      *
      * Returns an unsubscribe fn.
      */
-    onLost(listener: (lost: IntentLost) => void): () => void;
+    onLost(listener: (lost: ClaimLost) => void): () => void;
     /**
-     * Async-iterable view of everyone else's open intents. Each
+     * Async-iterable view of everyone else's open claims. Each
      * iteration yields the current snapshot on every mutation.
      *
      * ```ts
-     * for await (const openIntents of participant.intents) {
-     *   if (openIntents.some((i) => i.target.id === clauseId)) wait();
+     * for await (const openClaims of participant.claims) {
+     *   if (openClaims.some((i) => i.target.id === clauseId)) wait();
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveIntent>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadonlyArray<ActiveClaim>>;
 }
 /**
- * Shape of an `intent_rejected` event delivered to
- * `IntentStream.onRejected`. Server rejects an incoming claim when
- * another participant already holds an open intent on the same target.
- */
-export interface IntentRejection {
-    /** The rejected claim's id (the one the caller just tried to mint). */
-    readonly intentId: string;
-    /** Why the server rejected it — currently always `'conflict'`. */
-    readonly reason: 'conflict';
-    /** The target that's already held. */
-    readonly target: {
-        readonly entityType: string;
-        readonly entityId: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly field?: string;
-        readonly meta?: Record<string, unknown>;
-    };
-    /** Participant id holding the existing claim. */
-    readonly heldBy: string;
-    /** The existing claim's id (for audit / retry correlation). */
-    readonly heldByIntentId: string;
-    /** When the existing claim expires (ms since epoch). */
-    readonly heldByExpiresAt: number;
-}
-/**
- * You LOST an intent you were HOLDING — distinct from `IntentRejection` (a
+ * You LOST an claim you were HOLDING — distinct from `ClaimRejection` (a
  * claim the server refused you). Delivered via `onLost`.
  */
-export interface IntentLost {
+export interface ClaimLost {
     /** The held claim's id that you just lost. */
-    readonly intentId: string;
+    readonly claimId: string;
     /**
      * How you lost it. `'preempted'`: a privileged participant (one holding the
-     * `intent.preempt` capability) evicted you and took the lease — its work now
+     * `claim.preempt` capability) evicted you and took the lease — its work now
      * supersedes yours, so re-plan against the new holder rather than blindly
      * re-claiming. `'expired'`: your TTL lapsed without finishing — re-claim if
      * you still need it.
@@ -500,7 +474,7 @@ export interface IntentLost {
         readonly meta?: Record<string, unknown>;
     };
 }
-export interface IntentDeclaration {
+export interface ClaimDeclaration {
     readonly target: EntityRef;
     /** Human-readable reason — "rewriting title" / "restyling chart". */
     readonly reason: string;
@@ -517,58 +491,100 @@ export interface IntentDeclaration {
  *
  * ```ts
  * {
- *   await using work = participant.intents.analyzing(clause, { ttl: '3m' });
- *   // ... do the work; intent auto-revokes when the block exits
+ *   await using work = participant.claims.analyzing(clause, { ttl: '3m' });
+ *   // ... do the work; claim auto-revokes when the block exits
  * }
  * ```
  */
-export interface Claim extends AsyncDisposable {
-    readonly id: string;
+/**
+ * THE one claim handle. Returned by every claim door — the typed
+ * `ablo.<model>.claim({ id })` (rich: `data`/`readAt`/`target` populated) and
+ * the low-level `participant.claims.claim()` lease (minimal: `claimId` +
+ * `revoke`/`release`). Row-level fields are optional precisely because the
+ * low-level lease has no row snapshot; the model door fills them in.
+ *
+ * Implements `Symbol.asyncDispose` so callers can `await using claim = ...`
+ * and have it auto-release on scope exit.
+ */
+export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
+    readonly object: 'claim';
+    readonly claimId: string;
+    /**
+     * True when the grant came AFTER waiting in the server's FIFO line
+     * (`claim_granted`) — the authoritative "the row may have changed under us"
+     * signal. Absent for an immediate grant or a non-queued lease.
+     */
+    readonly waited?: boolean;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp). Writes
+     * carrying the handle use it as the `readAt` stale guard. Present for
+     * model-scoped claims; absent for low-level leases.
+     */
+    readonly readAt?: number;
+    readonly target: {
+        readonly model: string;
+        readonly id: string;
+        readonly field?: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly meta?: Record<string, unknown>;
+    };
+    readonly action: string;
+    readonly description?: string;
+    /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
+    readonly data?: T;
+    release(): Promise<void>;
     revoke(): void;
 }
-export interface ActiveIntent extends IntentDeclaration {
+export interface ActiveClaim extends ClaimDeclaration {
     readonly id: string;
     readonly heldBy: string;
     /**
-     * Whether the holding participant is a human (session) or an agent.
-     * First-class field so UIs can style "agent editing X" differently
-     * from "user editing X" without string-parsing `heldBy`.
+     * Whether the holding participant is a user (session), an agent, or a
+     * system actor. First-class field so UIs can style "agent editing X"
+     * differently from "user editing X" without string-parsing `heldBy`.
+     * Canonical `'user' | 'agent' | 'system'` — the presence/claim stream
+     * derives the value from the boolean `isAgent` wire flag (so it produces
+     * only `'user'`/`'agent'`), but the type stays the full union it shares
+     * with the HTTP claim surface and lease store.
      */
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     readonly description?: string;
-    readonly announcedAt: string;
-    readonly expiresAt: string;
+    /** Epoch-ms the claim was announced. */
+    readonly announcedAt: number;
+    /** Epoch-ms the server auto-expires it. */
+    readonly expiresAt: number;
 }
 /**
- * Every lifecycle state of a coordination intent, in one enum.
+ * Every lifecycle state of a coordination claim, 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.
+ * claim from the synced set.
  */
-export type IntentStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
+export type ClaimStatus = 'active' | 'queued' | 'committed' | 'expired' | 'canceled';
 /** Options for waiting on a target to become free. */
-export interface IntentWaitOptions {
+export interface ClaimWaitOptions {
     readonly timeout?: number;
     readonly pollInterval?: number;
     readonly signal?: AbortSignal;
 }
 /**
  * The coordination state of one entity. Self-describing on the wire via
- * `object: 'intent'`. Existence with `status: 'active'` *is* the lock;
+ * `object: 'claim'`. Existence with `status: 'active'` *is* the lock;
  * the fields *are* the awareness ("agent X is editing this until Y").
  *
  * 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 — `claim` serializes behind the holder via the server
- * FIFO queue (or low-level `intents.waitFor` to wait without claiming), and the
+ * FIFO queue (or low-level `claims.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';
+export interface Claim {
+    readonly object: 'claim';
     readonly id: string;
-    readonly status: IntentStatus;
+    readonly status: ClaimStatus;
     /** What is being coordinated. */
     readonly target: EntityRef;
     /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
@@ -577,14 +593,14 @@ export interface Intent {
     readonly description?: string;
     /** Participant holding it. */
     readonly heldBy: string;
-    readonly participantKind: 'human' | 'agent';
+    readonly participantKind: ParticipantKind;
     /**
-     * Ms-epoch the holder opened it. Optional until the lease wire carries
+     * Epoch-ms the holder opened it. Optional until the lease wire carries
      * it — derived shapes (e.g. mapped from a presence frame) may omit it.
      */
-    readonly createdAt?: string;
-    /** Ms-epoch the server auto-expires it if the holder doesn't finish. */
-    readonly expiresAt: string;
+    readonly createdAt?: number;
+    /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
+    readonly expiresAt: number;
     /**
      * 0-based place in the FIFO line — present only when `status: 'queued'`
      * (`0` = next in line behind the holder). Absent for the active holder.

package/dist/types/streams.js

@@ -3,7 +3,7 @@
  *
  * Ablo treats humans and agents as participants on live application
  * entities. Participants announce what they are reading or editing,
- * claim intent before writing, and capture context watermarks before
+ * claim before writing, and capture context watermarks before
  * long-running AI work. The customer keeps their own schema, agent
  * stack, tools, prompts, and product policy; the sync engine provides
  * the shared coordination substrate.

package/dist/utils/asyncIterator.d.ts

@@ -5,7 +5,7 @@
  * The inputs are two functions:
  *
  *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `IntentStream`. We register a
+ *     primitive on `PresenceStream` / `ClaimStream`. We register a
  *     listener that enqueues a value every time the source mutates;
  *     we tear it down in `return()`.
  *   - `getSnapshot()` — read the latest value to hand to the

package/dist/utils/asyncIterator.js

@@ -5,7 +5,7 @@
  * The inputs are two functions:
  *
  *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `IntentStream`. We register a
+ *     primitive on `PresenceStream` / `ClaimStream`. We register a
  *     listener that enqueues a value every time the source mutates;
  *     we tear it down in `return()`.
  *   - `getSnapshot()` — read the latest value to hand to the

package/dist/wire/frames.d.ts

@@ -52,7 +52,7 @@ export interface CommitOperation {
 }
 /**
  * Client → Server single named-mutation frame. The named-mutator write
- * primitive (intent + args), as opposed to the raw-op {@link CommitMessage}
+ * primitive (claim + args), as opposed to the raw-op {@link CommitMessage}
  * batch. Server-side mutator dispatch resolves `mutatorName` against the
  * host-provided registry.
  */
@@ -78,7 +78,7 @@ export interface CommitMessage {
         /**
          * Dormant agent-task lineage field. The SDK no longer populates it —
          * turns/tasks were removed and write attribution now rides on the
-         * claim (`intent`) id plus the server-stamped actor/capability. Kept
+         * claim (`claim`) id plus the server-stamped actor/capability. Kept
          * optional for wire-compat; when present the Hub still validates and
          * threads it onto `caused_by_task_id`, but client writes leave it
          * `null` (the audit pane treats null as "no prompt-side context").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -221,6 +221,7 @@
     "ts-morph": "^26.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.8.3",
-    "publint": "^0.3.21"
+    "publint": "^0.3.21",
+    "yjs": "^13.6.29"
   }
 }

package/dist/react/useIntent.js

@@ -1,42 +0,0 @@
-'use client';
-import { useCallback } from 'react';
-import { useSyncContext } from './context.js';
-import { AbloValidationError } from '../errors.js';
-/**
- * Named-intent invoker, typed via `ResolveIntents[IntentName]`.
- *
- * The consumer declares their intent vocabulary in the global:
- *
- * ```ts
- * declare module '@abloatai/ablo' {
- *   interface Register {
- *     Intents: {
- *       editLayer: { slideId: string; layerId: string };
- *       generateWithAI: { entityId: string; tool: string };
- *     };
- *   }
- * }
- * ```
- *
- * Then `useIntent('editLayer')` returns a function whose sole argument
- * is the `editLayer` claim shape — no runtime checks, purely compile-
- * time narrowing.
- *
- * The SDK doesn't own what happens next: the `beginIntent` function on
- * the React context (supplied via `SyncProvider`) is where the intent
- * claim turns into a network effect. A Node-backed consumer wires it
- * through `SyncAgent.beginIntent`; a browser-backed consumer may
- * broadcast it through their own WebSocket. This hook is pure sugar
- * that adds the typed name + claim narrowing.
- */
-export function useIntent(intentName) {
-    const { beginIntent } = useSyncContext();
-    return useCallback((claim) => {
-        if (!beginIntent) {
-            throw new AbloValidationError(`useIntent: no \`beginIntent\` wired into SyncProvider. Pass ` +
-                `a \`beginIntent\` prop (typically bound to your transport) ` +
-                `to enable intent invocations.`, { code: 'intent_not_wired' });
-        }
-        return beginIntent(intentName, claim);
-    }, [beginIntent, intentName]);
-}

package/dist/sync/awaitIntentGrant.d.ts

@@ -1,40 +0,0 @@
-/**
- * `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 interface IntentGrantInfo {
-    /**
-     * True when the grant arrived as `intent_granted` — i.e. the target was
-     * HELD when we asked and we waited in the FIFO line behind the holder.
-     * False for the immediate `intent_acquired` (target was free).
-     *
-     * Callers use this to know the row may have changed while we queued:
-     * intent VISIBILITY is entity-scoped (org-wide subscriptions receive no
-     * presence/intent fan-out — see Hub.broadcastPresenceChange), so the
-     * local coordination snapshot cannot be trusted to detect "we waited".
-     * The grant frame itself is the authoritative signal.
-     */
-    readonly waited: boolean;
-}
-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<IntentGrantInfo>;

package/dist/sync/awaitIntentGrant.js

@@ -1,62 +0,0 @@
-/**
- * `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();
-        };
-        // 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; `waited` records which path it was.
-        unsubs.push(transport.subscribe('intent_acquired', (p) => {
-            if (p?.intentId === intentId)
-                settle(() => resolve({ waited: false }));
-        }));
-        unsubs.push(transport.subscribe('intent_granted', (p) => {
-            if (p?.intentId === intentId)
-                settle(() => resolve({ waited: true }));
-        }));
-        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.d.ts

@@ -1,34 +0,0 @@
-/**
- * Transport-driven IntentStream factory.
- *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Intents derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeIntents` on every presence frame). Outbound
- * announce/revoke ride the same socket via `intent_begin` /
- * `intent_abandon` frames.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `intent_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * IntentStream factory in the SDK; the older compatibility path
- * deletes.
- */
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { IntentStream } from '../types/streams.js';
-export interface IntentStreamConfig {
-    /** Identity used to filter our own active intents out of `others`. */
-    participantId: string;
-}
-export interface AttachableIntentStream extends IntentStream {
-    attach(transport: SyncWebSocket): void;
-    dispose(): void;
-}
-export declare function createIntentStream(config: IntentStreamConfig, transport?: SyncWebSocket | null): AttachableIntentStream;