@abloatai/ablo 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- Canonicalize the claim API to one vocabulary, plus DX fixes (breaking).
+  - BREAKING: claim phase field `action` → `reason` on every claim surface
+    (`Claim`, `ClaimHandle`, `ClaimCreateOptions`, `ModelClaim`, ...). The wire
+    is unchanged (still `action`, healed on read) — no server redeploy needed.
+  - BREAKING: claim contention flag `wait` → `queue` (one word everywhere).
+  - BREAKING: React hook `useParticipant` → `useWatch` (aligns with `ablo.<model>.watch`).
+  - `ClaimDeclaration.ttlSeconds` is now `number` (was a `Duration`).
+  - Docs: `retrieve` HTTP envelope (`.data`/`.stamp`) called out; `syncGroups`
+    reworded (provisional, not deprecated); `orgScoped` cross-tenant security
+    warning; React error strings point at `<AbloProvider>`.
+
 ## 0.11.2
 
 ### Patch Changes

package/dist/ai-sdk/claim-broadcast.d.ts

@@ -58,10 +58,11 @@ export interface ClaimBroadcastMiddlewareOptions<R extends SchemaRecord = Schema
     /** Target entity. Null skips the broadcast (purely conversational). */
     readonly target: ClaimTarget | null;
     /**
-     * Action verb describing what the agent is doing. Convention:
-     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`.
+     * Human-readable phase describing what the agent is doing. Convention:
+     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Surfaces to other agents through `ActiveClaim.description`.

package/dist/ai-sdk/claim-broadcast.js

@@ -29,7 +29,7 @@
  */
 export function claimBroadcastMiddleware(options) {
     const { agent, target } = options;
-    const action = options.action ?? 'edit';
+    const reason = options.reason ?? 'edit';
     const description = options.description;
     const openClaim = () => {
         if (!agent || !target)
@@ -42,7 +42,7 @@ export function claimBroadcastMiddleware(options) {
             field: target.field,
             meta: target.meta,
         }, {
-            reason: action,
+            reason,
             description,
             ttl: target.estimatedMs ?? 60_000,
         });

package/dist/ai-sdk/wrap.d.ts

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -40,10 +40,11 @@ export interface WrapWithMultiplayerOptions {
     /** Target entity. Null = pass-through wrap. */
     readonly target: ClaimTarget | null;
     /**
-     * Optional action verb for the broadcast. Default `'edit'`.
-     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`.
+     * Optional human-readable phase for the broadcast. Default `'edit'`.
+     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Other agents receive it in their coordination context.

package/dist/ai-sdk/wrap.js

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -31,12 +31,12 @@ import { wrapLanguageModel } from 'ai';
 import { claimBroadcastMiddleware, } from './claim-broadcast.js';
 import { coordinationContextMiddleware } from './coordination-context.js';
 export function wrapWithMultiplayer(options) {
-    const { model, agent, target, action, description, excludeClaimIds, extraMiddleware } = options;
+    const { model, agent, target, reason, description, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            claimBroadcastMiddleware({ agent, target, action, description }),
+            claimBroadcastMiddleware({ agent, target, reason, description }),
             ...(extraMiddleware ?? []),
         ],
     });

package/dist/cli.cjs

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

package/dist/client/Ablo.d.ts

@@ -332,8 +332,14 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     configOverrides?: Partial<SyncEngineConfig>;
     /**
-     * @deprecated Server derives sync groups from the apiKey's scope.
-     * Required today as a runtime holdover; removed once Phase 3 ships.
+     * Sync groups (entity scopes) this client subscribes to. **Provisional, not
+     * deprecated** — pick the right lane: normally the server derives these from
+     * the apiKey's scope, but passing them is still REQUIRED today in any config
+     * where the key doesn't resolve them (omitting yields a `degenerate
+     * syncGroups` warning and a zero-fan-out client). Keep passing it explicitly
+     * until the server-derived path ships in Phase 3, at which point it becomes a
+     * true no-op and is removed. Build values with `syncGroup(kind, id)` from
+     * `@abloatai/ablo/schema`.
      */
     syncGroups?: string[];
     /**
@@ -388,7 +394,9 @@ export interface ModelReadOptions extends ClaimedOptions {
 }
 export interface ClaimCreateOptions {
     readonly target: ModelTarget;
-    readonly action: string;
+    /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
+     *  word on every claim surface; serialized on the wire as `action`. */
+    readonly reason: string;
     readonly ttl?: Duration;
     /**
      * Join the server's fair FIFO queue when the target is already claimed,
@@ -490,6 +498,20 @@ export interface HttpClaimApi<T> {
     reorder(params: ClaimReorderParams<T>): Promise<void>;
 }
 export interface ModelClient<T = Record<string, unknown>> {
+    /**
+     * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
+     * row is on `.data`, alongside the `.stamp` watermark (for stale-context
+     * guards on the following write) and any active `.claims`. A stateless HTTP
+     * client can't synthesize the watermark from a local snapshot, so the
+     * envelope is load-bearing here (the WebSocket client's `retrieve` returns
+     * `T | undefined` because it reads from the hydrated pool).
+     *
+     * ```ts
+     * const deal = await ablo.deals.retrieve({ id });
+     * deal.data?.recommendation;   // ← the row is on .data
+     * deal.stamp;                  // watermark — pass to the next write's readAt
+     * ```
+     */
     retrieve(params: ModelReadOptions & {
         readonly id: string;
     }): Promise<ModelRead<T>>;

package/dist/client/Ablo.js

@@ -1124,7 +1124,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.reason,
+            reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: 'active',
@@ -1144,7 +1144,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.action,
+            reason: claim.reason,
             ...(claim.description ? { description: claim.description } : {}),
             field: claim.target.field,
             status: 'queued',
@@ -1246,7 +1246,7 @@ export function Ablo(options) {
         return {
             object: 'claim',
             claimId: claim.claimId,
-            action: claim.action,
+            reason: claim.reason,
             target: claim.target,
             waited,
             release,
@@ -1265,7 +1265,7 @@ export function Ablo(options) {
                 field: claimOptions.target.field,
                 meta: claimOptions.target.meta,
             }, {
-                reason: claimOptions.action,
+                reason: claimOptions.reason,
                 ttl: claimOptions.ttl,
                 queue: claimOptions.queue,
             });
@@ -1348,7 +1348,7 @@ export function Ablo(options) {
                         ...(held.target.field ? { field: held.target.field } : {}),
                         ...(held.target.meta ? { meta: held.target.meta } : {}),
                     },
-                    action: held.action,
+                    reason: held.reason,
                     heldBy: held.actor,
                     participantKind: held.participantKind,
                     expiresAt: held.expiresAt,

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/model.d.ts

@@ -95,9 +95,16 @@ export interface ModelOptions {
      */
     tableName?: string;
     /**
-     * Whether this model's table has an organization_id column.
-     * Default: true. When false, the bootstrap query omits the
-     * `WHERE organization_id = $1` clause for this model.
+     * Whether this model's table has an `organization_id` column. Default: true.
+     * When false, the bootstrap/read query omits the `WHERE organization_id = $1`
+     * tenant filter for this model.
+     *
+     * ⚠ SECURITY — `orgScoped: false` makes the table GLOBALLY READABLE: every
+     * client of every tenant sees every row. It is ONLY correct for genuinely
+     * tenant-less tables (the `organizations` table itself, global lookups). If
+     * rows belong to a tenant through a foreign key but this table has no
+     * `organization_id` of its own, use {@link scopedVia} INSTEAD — reaching for
+     * `orgScoped: false` there silently exposes the entire table cross-tenant.
      */
     orgScoped?: boolean;
     /**

package/dist/sync/createClaimStream.js

@@ -192,7 +192,8 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                action: claim.action,
+                // Wire field stays `action` (coordination schema); source is `reason`.
+                action: claim.reason,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -244,7 +245,7 @@ export function createClaimStream(config, transport = null) {
             range: args.range,
             field: args.field,
             meta: args.meta,
-            action: args.action,
+            reason: args.reason,
             estimatedMs,
             queue: args.queue,
         };
@@ -261,7 +262,7 @@ export function createClaimStream(config, transport = null) {
         return {
             object: 'claim',
             claimId,
-            action: args.action,
+            reason: args.reason,
             target: {
                 model: args.entityType,
                 id: args.entityId,
@@ -294,7 +295,7 @@ export function createClaimStream(config, transport = null) {
                 range: resolved.range,
                 field: resolved.field,
                 meta: withDescription(resolved.meta, opts?.description),
-                action: opts?.reason ?? 'editing',
+                reason: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,
             });

package/dist/sync/participants.js

@@ -221,7 +221,7 @@ function createJoinedParticipant(args) {
         return {
             object: 'claim',
             claimId: handle.claimId,
-            action: handle.action,
+            reason: handle.reason,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);

package/dist/types/streams.d.ts

@@ -360,7 +360,7 @@ export interface ClaimStream {
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
-     * `action`, `heldBy`, and `position`. Synced from the server's per-entity
+     * `reason`, `heldBy`, and `position`. Synced from the server's per-entity
      * `claim_queue` frame; empty when no one's waiting. Pair with
      * `subscribe(...)` for change notifications.
      */
@@ -457,10 +457,12 @@ export interface ClaimDeclaration {
     /** Human-readable reason — "rewriting title" / "restyling chart". */
     readonly reason: string;
     /**
-     * Expiry — auto-revoke if the participant doesn't finish in time.
-     * Number = seconds (back-compat); string = duration (`'3m'`).
+     * Seconds remaining until the server auto-expires this claim. An OUTPUT
+     * field carrying a concrete countdown, so it's a plain `number` — distinct
+     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
+     * from `expiresAt - now`.
      */
-    readonly ttlSeconds?: Duration;
+    readonly ttlSeconds?: number;
 }
 /**
  * Handle returned from `announce(...)` / `analyzing(...)` / etc.
@@ -507,7 +509,13 @@ export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposabl
         readonly range?: TargetRange;
         readonly meta?: Record<string, unknown>;
     };
-    readonly action: string;
+    /**
+     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
+     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
+     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
+     * to `'editing'`. Serialized on the wire as `action`.
+     */
+    readonly reason: string;
     readonly description?: string;
     /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
     readonly data?: T;
@@ -565,8 +573,10 @@ export interface Claim {
     readonly status: ClaimStatus;
     /** What is being coordinated. */
     readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
-    readonly action: string;
+    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     *  field on every claim surface; distinct from the CRUD operation. Serialized
+     *  on the wire as `action`. */
+    readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
     /** Participant holding it. */

package/docs/migration.md

@@ -284,7 +284,8 @@ One provider component now owns the full React lifecycle. `<SyncProvider>`,
 - <SyncProvider store={sync._store} organizationId={orgId}>
 -   <AbloProvider ablo={ablo}>{children}</AbloProvider>
 - </SyncProvider>
-+ <AbloProvider schema={schema} url={url} userId={userId} organizationId={orgId}>
++ const ablo = Ablo({ schema, apiKey });
++ <AbloProvider client={ablo}>
 +   {children}
 + </AbloProvider>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",