@abloatai/ablo 0.5.1 → 0.7.0

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

@@ -9,6 +9,8 @@
  * 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 };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form
  * metadata that will be persisted / transported as JSON — avoids
@@ -113,13 +115,6 @@ export interface ContextChange {
  * snapshot. Defaults to `'reject'` when `readAt` is provided without
  * `onStale`.
  */
-export type OnStaleMode = 'reject' | 'flag' | 'merge' | 'force';
-export interface TargetRange {
-    readonly startLine: number;
-    readonly endLine: number;
-    readonly startColumn?: number;
-    readonly endColumn?: number;
-}
 /**
  * A pointer to one entity, optionally narrowed to a structured
  * subtarget. `type` and `id` are customer schema vocabulary; `path`,
@@ -175,7 +170,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 +204,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
@@ -304,32 +299,6 @@ export interface Peer {
     /** Pending-mutation intents this participant has declared. */
     readonly activeIntents?: ReadonlyArray<IntentClaim>;
 }
-/**
- * Pending-mutation intent on the wire. Declared via `intent_begin`,
- * cleared on `intent_abandon` / commit / disconnect / TTL expiry.
- * Server stamps `declaredAt` and `expiresAt` (ms epoch). The SDK's
- * `IntentStream.others` exposes a richer `ActiveIntent` view (defined
- * below) that adds `heldBy` so callers know which participant owns it.
- */
-export interface IntentClaim {
-    readonly intentId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-    readonly path?: string;
-    readonly range?: TargetRange;
-    readonly action: string;
-    readonly field?: string;
-    readonly meta?: Record<string, unknown>;
-    readonly declaredAt: number;
-    readonly expiresAt: number;
-}
-/**
- * Transition type carried on every presence frame from the server.
- *   - `'enter'`  — first frame the receiver sees for this peer.
- *   - `'update'` — activity / intent change on an already-known peer.
- *   - `'leave'`  — peer departed (explicit disconnect or TTL expiry).
- */
-export type PresenceKind = 'enter' | 'update' | 'leave';
 /** Outbound `presence_update` payload. */
 export interface PresenceUpdatePayload {
     readonly status: 'online' | 'away' | 'offline' | (string & {});
@@ -371,6 +340,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 +372,23 @@ 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[];
+    /**
+     * 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
+     * this is fire-and-forget — the new order arrives reactively via `queueFor`.
+     */
+    reorder(target: PresenceTarget, order: readonly Intent[]): void;
     /**
      * Framework-agnostic reactivity. Same contract as
      * `PresenceStream.subscribe` — register a listener fired on every
@@ -401,7 +396,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
@@ -418,6 +413,23 @@ export interface IntentStream {
      * Returns an unsubscribe fn.
      */
     onRejected(listener: (rejection: IntentRejection) => 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:
+     * `'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) => {
+     *   if (lost.reason === 'preempted') replanAgainst(lost.target);
+     *   else reclaim(lost.target);
+     * });
+     * ```
+     *
+     * Returns an unsubscribe fn.
+     */
+    onLost(listener: (lost: IntentLost) => void): () => void;
     /**
      * Async-iterable view of everyone else's open intents. Each
      * iteration yields the current snapshot on every mutation.
@@ -456,6 +468,31 @@ export interface IntentRejection {
     /** When the existing claim expires (ms since epoch). */
     readonly heldByExpiresAt: number;
 }
+/**
+ * You LOST an intent you were HOLDING — distinct from `IntentRejection` (a
+ * claim the server refused you). Delivered via `onLost`.
+ */
+export interface IntentLost {
+    /** The held claim's id that you just lost. */
+    readonly intentId: string;
+    /**
+     * How you lost it. `'preempted'`: a privileged participant (one holding the
+     * `intent.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.
+     */
+    readonly reason: 'expired' | 'preempted';
+    /** The target you no longer hold. */
+    readonly target: {
+        readonly entityType: string;
+        readonly entityId: string;
+        readonly path?: string;
+        readonly range?: TargetRange;
+        readonly field?: string;
+        readonly meta?: Record<string, unknown>;
+    };
+}
 export interface IntentDeclaration {
     readonly target: EntityRef;
     /** Human-readable reason — "rewriting title" / "restyling chart". */
@@ -494,8 +531,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 +551,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 +575,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;
 }

package/docs/api-keys.md

@@ -22,3 +22,47 @@ Use API keys from trusted runtimes:
 - webhooks
 
 Never ship a secret API key to a browser bundle.
+
+## Test mode and sandboxes
+
+Test and live keys are the same shape; the prefix names the environment:
+
+- `sk_test_…` — a key bound to a **sandbox**. Its reads and writes are isolated
+  to that sandbox and are invisible to live keys (and to other sandboxes).
+- `sk_live_…` — a key against your live data.
+
+Every org has a default **Test mode** sandbox, plus any number of additional
+sandboxes you create. **Data is isolated per sandbox; the schema is shared
+across the whole org.** A schema you push from a test key defines the same
+models your live keys see — only the rows differ. This mirrors how Stripe
+separates test and live data while keeping the API shape identical.
+
+## Scopes
+
+Keys carry scopes following the principle of least privilege — each key gets
+only what its job needs. A secret key with **no scopes** has full org authority
+(the default for a `sk_live_` backend key); a key with a non-empty scope set is
+restricted to exactly those grants:
+
+- `schema:push` — author the org schema (`ablo schema push`, `ablo dev`). A
+  high-risk, org-wide grant: because schema is shared, a push affects the live
+  table shape. A full-authority key has it implicitly; a *restricted* key (such
+  as a sandbox key) needs it granted explicitly.
+- `sandbox:<id>` — marks the key as belonging to a sandbox (its data isolation
+  comes from the sandbox binding, not this scope string).
+
+A key minted from the default **Test mode** sandbox carries `schema:push`, so
+`ablo dev` works out of the box. Keys from other sandboxes are **data-only** by
+default — enable "schema authoring" when minting if you want that key to push
+schema too. Hand data-only keys to embedded apps and CI agents; reserve
+schema-authoring keys for the developer running `ablo dev`.
+
+### `ablo dev`
+
+```sh
+ABLO_API_KEY=sk_test_… npx ablo dev
+```
+
+Pushes your `ablo/schema.ts` to the test sandbox, prints the one line you need
+in `.env.local`, and re-pushes on every save. It refuses `sk_live_` keys so a
+tight save loop can never churn production data.