@abloatai/ablo 0.11.2 → 0.13.0

package/dist/client/ApiClient.js

@@ -11,6 +11,18 @@ import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
 import { mintSession } from './sessionMint.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
+/**
+ * The `/v1/claims` and model-query routes still emit the wire field `action`
+ * for the claim phase; the public `Claim` / `ModelClaim` expose it as `reason`.
+ * Heal on read so the SDK shape is consistent without a coordinated server
+ * deploy — `reason ?? action`. When the server adopts `reason`, this is a no-op.
+ */
+function healClaimPhase(claim) {
+    const raw = claim;
+    if (raw.reason !== undefined)
+        return claim;
+    return { ...claim, reason: raw.action ?? 'editing' };
+}
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -173,8 +185,8 @@ export function createProtocolClient(options) {
         const suffix = params.toString();
         const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' });
         return {
-            active: body.claims ?? [],
-            queue: body.queue ?? [],
+            active: (body.claims ?? []).map(healClaimPhase),
+            queue: (body.queue ?? []).map(healClaimPhase),
         };
     }
     function delay(ms, signal) {
@@ -374,7 +386,8 @@ export function createProtocolClient(options) {
                 body: JSON.stringify({
                     claimId,
                     target: claimOptions.target,
-                    action: claimOptions.action,
+                    // Wire field stays `action`; public option is `reason`.
+                    action: claimOptions.reason,
                     ttl: claimOptions.ttl,
                     queue: claimOptions.queue,
                 }),
@@ -400,7 +413,7 @@ export function createProtocolClient(options) {
             return {
                 object: 'claim',
                 claimId: id,
-                action: claimOptions.action,
+                reason: claimOptions.reason,
                 target: claimOptions.target,
                 release,
                 revoke: () => {
@@ -451,7 +464,7 @@ export function createProtocolClient(options) {
         return {
             data,
             stamp: query.stamp ?? 0,
-            claims: query.claims ?? [],
+            claims: (query.claims ?? []).map(healClaimPhase),
         };
     }
     /**
@@ -533,13 +546,14 @@ export function createProtocolClient(options) {
             const body = await requestJson(claimPath(params.id), {
                 method: 'POST',
                 body: JSON.stringify({
-                    action: params.action ?? 'editing',
+                    // Wire field stays `action`; public option is `reason`.
+                    action: params.reason ?? 'editing',
                     ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
                     ...(params.description !== undefined ? { description: params.description } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
-                    // `wait` (default true) → queue behind the holder; false → fail-fast
+                    // `queue` (default true) → queue behind the holder; false → fail-fast
                     // with AbloClaimedError (work-distribution dedup).
-                    queue: params.wait ?? true,
+                    queue: params.queue ?? true,
                 }),
             });
             if (body.status === 'queued') {
@@ -565,7 +579,7 @@ export function createProtocolClient(options) {
                     ...(params.range ? { range: params.range } : {}),
                     ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
                 },
-                action: params.action ?? 'editing',
+                reason: params.reason ?? 'editing',
                 ...(params.description ? { description: params.description } : {}),
                 data,
                 release,
@@ -580,11 +594,12 @@ export function createProtocolClient(options) {
             release: releaseClaim,
             state: async (params) => {
                 const res = await claimsForEntity(params);
-                return res.claims?.[0] ?? null;
+                const first = res.claims?.[0];
+                return first ? healClaimPhase(first) : null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
-                return { object: 'list', data: res.queue ?? [] };
+                return { object: 'list', data: (res.queue ?? []).map(healClaimPhase) };
             },
             reorder: async (params) => {
                 await requestJson(`${claimPath(params.id)}/reorder`, {

package/dist/client/createModelProxy.d.ts

@@ -90,7 +90,8 @@ export interface ModelCollaboration<T> {
             range?: TargetRange;
             meta?: Record<string, unknown>;
         };
-        action: string;
+        /** Human-readable phase (`'editing'`); wire field is `action`. */
+        reason: string;
         ttl?: Duration;
         /**
          * Block on the server's fair FIFO queue when the target is held, rather
@@ -178,8 +179,9 @@ export interface ModelCollaboration<T> {
     createWatch?(modelKey: string, ids: string | readonly string[], options?: WatchOptions): Promise<JoinedParticipant>;
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
-    /** Phase shown to observers while held. Defaults to `'editing'`. */
-    action?: string;
+    /** Human-readable phase shown to observers while held. Defaults to
+     *  `'editing'`. The same word on every claim surface; wire field is `action`. */
+    reason?: string;
     /** Peer-visible explanation of the work being performed. */
     description?: string;
     /** Field-level target, for fine-grained claimed-state badges. */
@@ -199,8 +201,14 @@ export interface ClaimTargetOptions<T = Record<string, unknown>> {
      * `AbloClaimedError` instead of waiting (claim-or-skip). Use `false` for
      * work-distribution dedup ("if someone else has this job, skip it") where
      * waiting would mean double-processing.
+     *
+     * Named `queue` to match every other claim surface (low-level
+     * `claims.claim`, HTTP `claim.create`, and the wire). The high-level typed
+     * claim defaults it ON because it serializes writers; the low-level lease
+     * and HTTP default it OFF — they return/resolve immediately and can't
+     * transparently wait for a grant.
      */
-    wait?: boolean;
+    queue?: boolean;
     /**
      * Backpressure: willing to queue, but not behind too many. If the server
      * reports `position >= maxQueueDepth` when we join the line, reject with
@@ -226,7 +234,7 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
  * ```ts
  * const claim = await ablo.weatherReports.claim({
  *   id: 'report_stockholm',
- *   action: 'forecasting',
+ *   reason: 'forecasting',
  *   description: 'Fetching current weather before writing the forecast.',
  * });
  * try {
@@ -258,7 +266,7 @@ export type ClaimOptions<T = Record<string, unknown>> = ClaimTargetOptions<T>;
  *   data: { title },
  *   claim: {
  *     field: 'title',
- *     action: 'renaming',
+ *     reason: 'renaming',
  *     description: 'Renaming the task to match the project brief.',
  *   },
  * });
@@ -379,7 +387,7 @@ export interface ModelOperations<T, CreateInput> {
      * ```ts
      * const claim = await ablo.weatherReports.claim({
      *   id: 'report_stockholm',
-     *   action: 'forecasting',
+     *   reason: 'forecasting',
      *   description: 'Fetching fresh weather before updating the report.',
      * });
      * const weather = await getWeather(claim.data.location);

package/dist/client/createModelProxy.js

@@ -77,7 +77,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // `release({ id })` and `update({ id, data })` find the lease + snapshot a `claim({ id })`
     // took — no per-call handle. Released on dispose, explicit release, or TTL.
     //
-    // `target` / `action` / `expiresAt` are kept alongside the lease so
+    // `target` / `reason` / `expiresAt` are kept alongside the lease so
     // `claim.state` can synthesize a self-claim: the server excludes a holder's
     // own presence frames, so the local proxy is the ONLY place that knows "I
     // hold this." `expiresAt` is the client's best estimate from the requested
@@ -103,7 +103,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.action,
+            reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: claim.status,
@@ -143,8 +143,8 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // claim (a free / already-mine target can't have changed under us).
         const held = collaboration.observe({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-        const failFast = options?.wait === false;
-        // Fail-fast (`wait: false`): if another participant already holds it,
+        const failFast = options?.queue === false;
+        // Fail-fast (`queue: false`): if another participant already holds it,
         // reject now instead of queuing. Best-effort at the client (a racing
         // claim not yet synced into our snapshot slips through here) — the
         // commit-time claim guard is the authoritative backstop that rejects
@@ -176,7 +176,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // in the group when `createClaim` lands. Awaited because the broadcast
         // ordering depends on it; still soft (the store swallows reconcile errors).
         await collaboration.pinScope?.({ [schemaKey]: id });
-        // Acquire the lease. Default (`wait` !== false) goes through the server's
+        // Acquire the lease. Default (`queue` !== false) goes through the server's
         // fair FIFO queue — `queue: true` resolves only once the lease is genuinely
         // ours, blocking behind any current holder, with no TOCTOU gap (the server
         // orders contenders). Fail-fast skips the queue: we already rejected an
@@ -190,7 +190,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 ...(options?.range ? { range: options.range } : {}),
                 ...(claimMeta(options) ? { meta: claimMeta(options) } : {}),
             },
-            action: options?.action ?? 'editing',
+            reason: options?.reason ?? 'editing',
             ttl: options?.ttl,
             queue: !failFast,
             maxQueueDepth: options?.maxQueueDepth,
@@ -213,7 +213,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
-        const action = options?.action ?? 'editing';
+        const reason = options?.reason ?? 'editing';
         // The self-claim's `EntityRef` mirrors what a peer's `claim.state` would
         // report (`observe` maps `held.target.model` → `type`), so a holder and a
         // peer see the SAME target.type for one row — the wire model token.
@@ -231,7 +231,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             lease,
             snapshot,
             target: selfTarget,
-            action,
+            reason,
             expiresAt,
         });
         const target = {
@@ -248,7 +248,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             claimId: lease.claimId,
             readAt: snapshot.stamp,
             target,
-            action,
+            reason,
             ...(options?.description ? { description: options.description } : {}),
             data: modelAsRow(model),
             release,
@@ -281,7 +281,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     id: own.lease.claimId,
                     status: 'active',
                     target: own.target,
-                    action: own.action,
+                    reason: own.reason,
                     heldBy: collaboration?.selfParticipantId ?? '',
                     participantKind: collaboration?.selfParticipantKind ?? 'user',
                     expiresAt: own.expiresAt,
@@ -381,9 +381,9 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                         ...(claim.range ? { range: claim.range } : {}),
                         ...(claimMeta(claim) ? { meta: claimMeta(claim) } : {}),
                     },
-                    action: claim.action ?? 'creating',
+                    reason: claim.reason ?? 'creating',
                     ttl: claim.ttl,
-                    queue: claim.wait !== false,
+                    queue: claim.queue !== false,
                     maxQueueDepth: claim.maxQueueDepth,
                 });
             }

package/dist/coordination/schema.d.ts

@@ -281,7 +281,7 @@ export declare const modelClaimSchema: z.ZodReadonly<z.ZodObject<{
         agent: "agent";
         system: "system";
     }>>;
-    action: z.ZodString;
+    reason: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     field: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<{

package/dist/coordination/schema.js

@@ -203,7 +203,9 @@ export const modelClaimSchema = z
     id: z.string(),
     actor: z.string(),
     participantKind: wireParticipantKindSchema,
-    action: z.string(),
+    /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
+     *  wire carries the same value as `action` (healed on read). */
+    reason: z.string(),
     description: z.string().optional(),
     field: z.string().optional(),
     status: z.enum(['active', 'queued']).optional(),

package/dist/errors.d.ts

@@ -161,7 +161,9 @@ export interface ClaimContext {
     readonly claimId?: string;
     readonly actor?: string;
     readonly participantKind?: ParticipantKind;
-    readonly action?: string;
+    /** Human-readable phase the holder is in (`'editing'`). Matches the public
+     *  claim surface; the wire summary carries the same value as `action`. */
+    readonly reason?: string;
     readonly description?: string;
     readonly field?: string;
     readonly status?: string;

package/dist/errors.js

@@ -162,7 +162,12 @@ export class AbloStaleContextError extends AbloError {
     }
 }
 function claimAction(claim) {
-    return claim?.action;
+    if (!claim)
+        return undefined;
+    // The public `ClaimContext` exposes the phase as `reason`; the wire
+    // `WireClaimSummary` projection still carries it under `action`. Read both.
+    const c = claim;
+    return c.reason ?? c.action;
 }
 function claimDescription(claim) {
     if (!claim)

package/dist/react/AbloProvider.d.ts

@@ -15,7 +15,7 @@ import { type SyncStoreContract } from './context.js';
  *   - **One component, one import.** Consumers write the provider
  *     once at the root; nothing else needs to plumb the engine.
  *   - **Multiplayer is default.** React consumers are always browsers doing
- *     multiplayer UI, so `useParticipant()` / `useAblo()` are always
+ *     multiplayer UI, so `useWatch()` / `useAblo()` are always
  *     available. No opt-in prop.
  *   - **Declarative props for app glue.** `preventUnsavedChanges`,
  *     `onSessionExpired`, `postBootstrap`, `resolveUsers` — each
@@ -114,11 +114,11 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
 export declare function AbloProvider<R extends SchemaRecord = SchemaRecord>(props: AbloProviderProps<R>): React.ReactElement;
 export type { EngineParticipant, ParticipantScope, ParticipantStatus };
 /**
- * Options for `useParticipant`. The hook reuses the engine's single
+ * Options for `useWatch`. The hook reuses the engine's single
  * WebSocket and opens a scoped claim on it when `scope` is provided:
  * one TCP connection, N logical sub-syncgroup participants.
  */
-export interface UseParticipantOptions {
+export interface UseWatchOptions {
     readonly scope?: ParticipantScope;
     readonly ttlSeconds?: number | string | null;
     /** Tear down + don't re-join while true. */
@@ -149,7 +149,7 @@ export interface UseParticipantOptions {
 }
 /** @deprecated Use `ParticipantStatus`. */
 export type MeshParticipantStatus = ParticipantStatus;
-export interface UseParticipantReturn {
+export interface UseWatchReturn {
     readonly participant: EngineParticipant | null;
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: ReadonlyArray<Peer>;
@@ -163,15 +163,19 @@ export interface UseParticipantReturn {
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
+ * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
  * The returned `participant` is an `EngineParticipant` — `.presence`
  * + `.claims` only — backed by the engine's existing socket. For
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export declare function useParticipant(opts: UseParticipantOptions): UseParticipantReturn;
+export declare function useWatch(opts: UseWatchOptions): UseWatchReturn;
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useParticipant}, this does
+ * connection, bridged to React. Unlike {@link useWatch}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -184,7 +188,7 @@ export declare function useParticipant(opts: UseParticipantOptions): UseParticip
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useParticipant` on the same scope would warm-drop the owner's
+ * `useWatch` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts

package/dist/react/AbloProvider.js

@@ -204,12 +204,16 @@ const EMPTY_INTENTS = Object.freeze([]);
  * lifecycle status. Auto-cleans up on unmount or when `paused`
  * flips to true.
  *
+ * `useWatch` is the React form of `ablo.<model>.watch` — scope-level
+ * read-interest + presence; returns the reactive participant facade
+ * (peers/claims/status).
+ *
  * The returned `participant` is an `EngineParticipant` — `.presence`
  * + `.claims` only — backed by the engine's existing socket. For
  * headless-bot patterns (a separate identity in the same browser
  * tab), construct a second `Ablo({ kind: 'agent', ... })` directly.
  */
-export function useParticipant(opts) {
+export function useWatch(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
@@ -342,7 +346,7 @@ export function useParticipant(opts) {
 }
 /**
  * Read-only presence: the OTHER participants currently visible to this
- * connection, bridged to React. Unlike {@link useParticipant}, this does
+ * connection, bridged to React. Unlike {@link useWatch}, this does
  * NOT enter/leave a scope (no `update_subscription`, no warm-TTL churn) —
  * it is a pure reader of the engine's already-flowing presence stream.
  *
@@ -355,7 +359,7 @@ export function useParticipant(opts) {
  * Use this to answer "is anyone else here?" — e.g. suppressing live-cursor
  * broadcasts while alone — when some OTHER mount already owns the scope's
  * read interest (scope `leave` is not reference-counted, so a second
- * `useParticipant` on the same scope would warm-drop the owner's
+ * `useWatch` on the same scope would warm-drop the owner's
  * subscription on unmount).
  *
  * ```ts
@@ -366,7 +370,7 @@ export function useParticipant(opts) {
 export function usePeers(scope) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
-    // Resolve scope → groups through the schema (same idiom as useParticipant).
+    // Resolve scope → groups through the schema (same idiom as useWatch).
     // The stringified, sorted key is the stable effect dependency.
     const scopeKey = JSON.stringify(resolveParticipantSyncGroups(scope, engine?.schema).sort());
     const groups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
@@ -383,7 +387,7 @@ export function usePeers(scope) {
         // Plain useState + onChange — presence changes on join/leave/activity
         // only (never on cursor traffic, a separate channel), so this fires
         // rarely; a frame of stale presence is harmless (same rationale as
-        // useParticipant's peers bridge).
+        // useWatch's peers bridge).
         setPeers(compute());
         return presence.onChange(() => setPeers(compute()));
     }, [engine, scopeKey]);

package/dist/react/context.d.ts

@@ -140,8 +140,9 @@ export interface SyncReactContext {
 }
 export declare const SyncContext: import("react").Context<SyncReactContext | null>;
 /**
- * Access the sync store from React components.
- * Must be used within a SyncProvider.
+ * Access the sync store from React components. The context is provided by
+ * `<AbloProvider>` (which renders the internal {@link SyncProvider}); public
+ * consumers wire `<AbloProvider client={ablo}>`, never this directly.
  */
 export declare function useSyncContext(): SyncReactContext;
 /**
@@ -162,18 +163,12 @@ export interface SyncProviderProps {
     children?: ReactNode;
 }
 /**
- * SyncProvider wires the sync store into React so SDK hooks
- * (useModel, useModels, useMutations) can access it.
+ * SyncProvider — the INTERNAL low-level provider that wires a built sync store
+ * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
  *
- * @example
- * import { SyncProvider } from '@abloatai/ablo/react';
- *
- * function App() {
- *   return (
- *     <SyncProvider store={syncStore} organizationId={orgId}>
- *       <YourApp />
- *     </SyncProvider>
- *   );
- * }
+ * Public consumers do NOT use this directly (it is not exported from
+ * `@abloatai/ablo/react`). `<AbloProvider client={ablo}>` constructs the
+ * store from your `Ablo({ schema, apiKey })` client and renders this provider
+ * underneath — reach for `<AbloProvider>`.
  */
 export declare function SyncProvider({ store, organizationId, schema, children, }: SyncProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<SyncReactContext | null>>;

package/dist/react/context.js

@@ -3,32 +3,27 @@ import { createContext, createElement, useContext } from 'react';
 import { AbloValidationError } from '../errors.js';
 export const SyncContext = createContext(null);
 /**
- * Access the sync store from React components.
- * Must be used within a SyncProvider.
+ * Access the sync store from React components. The context is provided by
+ * `<AbloProvider>` (which renders the internal {@link SyncProvider}); public
+ * consumers wire `<AbloProvider client={ablo}>`, never this directly.
  */
 export function useSyncContext() {
     const ctx = useContext(SyncContext);
     if (!ctx) {
-        throw new AbloValidationError('useSyncContext must be used within a SyncProvider', {
+        throw new AbloValidationError('Sync hooks must be used within an <AbloProvider>.', {
             code: 'sync_context_missing_provider',
         });
     }
     return ctx;
 }
 /**
- * SyncProvider wires the sync store into React so SDK hooks
- * (useModel, useModels, useMutations) can access it.
+ * SyncProvider — the INTERNAL low-level provider that wires a built sync store
+ * into React so SDK hooks (useModel, useModels, useMutations) can reach it.
  *
- * @example
- * import { SyncProvider } from '@abloatai/ablo/react';
- *
- * function App() {
- *   return (
- *     <SyncProvider store={syncStore} organizationId={orgId}>
- *       <YourApp />
- *     </SyncProvider>
- *   );
- * }
+ * Public consumers do NOT use this directly (it is not exported from
+ * `@abloatai/ablo/react`). `<AbloProvider client={ablo}>` constructs the
+ * store from your `Ablo({ schema, apiKey })` client and renders this provider
+ * underneath — reach for `<AbloProvider>`.
  */
 export function SyncProvider({ store, organizationId, schema, children, }) {
     return createElement(SyncContext.Provider, { value: { store, organizationId, schema } }, children);

package/dist/react/index.d.ts

@@ -2,8 +2,12 @@
  * @abloatai/ablo/react — React bindings (v0.3.0)
  *
  * Umbrella provider:
- *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
- *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
+ *     — `client` is the only required prop (construct it yourself; the provider
+ *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
+ *     is optional + informational. Owns sync engine + multiplayer lifecycle;
+ *     the `fallback` prop
  *     gates children on first bootstrap. Pass `fallback="passthrough"`
  *     to disable the gate.
  *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
@@ -27,7 +31,7 @@
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
+ *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -41,7 +45,7 @@
  *   migration notes in CHANGELOG.md.
  */
 export type { DefaultSyncShape, ResolveSchema, ResolvePresence, ResolveClaims, ResolveUserMeta, ResolveModelKey, } from '../types/global.js';
-export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseParticipantOptions, type UseParticipantReturn, type MeshParticipantStatus, } from './AbloProvider.js';
+export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, type AbloProviderProps, type ParticipantScope, type ParticipantStatus, type UseWatchOptions, type UseWatchReturn, type MeshParticipantStatus, } from './AbloProvider.js';
 export { ClientSideSuspense, type ClientSideSuspenseProps, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 export type { SyncStoreContract } from './context.js';

package/dist/react/index.js

@@ -2,8 +2,12 @@
  * @abloatai/ablo/react — React bindings (v0.3.0)
  *
  * Umbrella provider:
- *   <AbloProvider schema={...} userId={...} orgId={...} fallback={<Skeleton/>}>
- *     — owns sync engine + multiplayer lifecycle; the `fallback` prop
+ *   const ablo = Ablo({ schema, apiKey })   // build once — module scope or useMemo
+ *   <AbloProvider client={ablo} fallback={<Skeleton/>}>
+ *     — `client` is the only required prop (construct it yourself; the provider
+ *     is the thin reactive binding, like `<Elements stripe={...}>`). `userId`
+ *     is optional + informational. Owns sync engine + multiplayer lifecycle;
+ *     the `fallback` prop
  *     gates children on first bootstrap. Pass `fallback="passthrough"`
  *     to disable the gate.
  *   <ClientSideSuspense fallback={<Skeleton/>}> — NESTED gate inside an
@@ -27,7 +31,7 @@
  *
  * Multiplayer (always available — `<AbloProvider>` always constructs a client):
  *   useAblo((ablo) => ablo.<model>.claim.state(...)) — reactive coordination reads
- *   useParticipant({ scope }) — join multiplayer for a scope, get peers/claims
+ *   useWatch({ scope }) — join multiplayer for a scope, get peers/claims
  *
  * ── Breaking changes from v0.2.x ───────────────────────────────────
  * Removed: <SyncProvider>, SyncContext, useSyncContext — folded into
@@ -41,7 +45,7 @@
  *   migration notes in CHANGELOG.md.
  */
 // ── Umbrella provider + lifecycle hooks ────────────────────────────
-export { AbloProvider, useParticipant, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
+export { AbloProvider, useWatch, usePeers, useSync, useSyncStore, } from './AbloProvider.js';
 export { ClientSideSuspense, } from './ClientSideSuspense.js';
 export { DefaultFallback } from './DefaultFallback.js';
 // ── Status + errors + identity ─────────────────────────────────────

package/dist/react/useMutators.js

@@ -17,8 +17,9 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
     const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators);
     const options = (isExplicit ? maybeOptions : mutatorsOrOptions);
     if (!schema) {
-        throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'mutators_schema_missing' });
+        throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg, ' +
+            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+            'zero-arg overload can read it from context.', { code: 'mutators_schema_missing' });
     }
     const { undoScope } = options ?? {};
     return useMemo(() => {

package/dist/react/useUndoScope.js

@@ -34,8 +34,9 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     const name = isExplicit ? nameOrOptions : schemaOrName;
     const options = (isExplicit ? maybeOptions : nameOrOptions);
     if (!schema) {
-        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg ' +
-            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'undo_scope_schema_missing' });
+        throw new AbloValidationError('useUndoScope: no schema available. Pass the schema as the first arg, ' +
+            'or build the <AbloProvider> above with `Ablo({ schema })` so the ' +
+            'zero-arg overload can read it from context.', { code: 'undo_scope_schema_missing' });
     }
     const scope = useMemo(() => {
         // Store is the identity for the manager — one per SyncProvider.

package/dist/schema/index.d.ts

@@ -23,13 +23,13 @@
 export { z } from 'zod';
 export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } from './tenancy.js';
 export { planeSchema, DEFAULT_PLANE, type SchemaPlane } from './plane.js';
 export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './sync-delta-row.js';
 export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from './sync-delta-wire.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';

package/dist/schema/index.js

@@ -27,7 +27,7 @@ export { field, indexed, getFieldMeta } from './field.js';
 // Relation builders
 export { relation } from './relation.js';
 // Tenancy — the single source of truth for how a model's rows are tenant-scoped.
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
 // Database plane — which DB a model's rows live in (`tenant` portable to a BYO
 // customer DB, `control` = Ablo's own). Sibling axis to `tenancy`.
 export { planeSchema, DEFAULT_PLANE } from './plane.js';
@@ -46,7 +46,7 @@ export { model, scopeKindOf, } from './model.js';
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.