@abloatai/ablo 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,17 +1,55 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- Per-entity coordination intents on the model accessor.
+
+  Coordinate writes to an entity through the same accessor you read it with —
+  `ablo.<model>.intent(id)`, returning a `ModelIntentHandle`. Intent state is one
+  self-describing object (`{ object: 'intent', id, status, target, action, heldBy,
+participantKind, createdAt?, expiresAt? }`) with a single lifecycle:
+  `status: 'active' | 'committed' | 'expired' | 'canceled'`. An `active` intent is
+  the lock.
+
+  ### Added
+  - `ablo.<model>.intent(id)` → `ModelIntentHandle<T>`, beside `create` / `update`
+    / `retrieve` / `load` on every model.
+    - Read side (any participant, synchronous + reactive): `current` (the holder's
+      intent, or `null`), `status` (`'idle'` when free), `settled()`.
+    - Write side (the holder): `acquire()`, `acquireOrAwait()`, lease-guarded
+      `update()`, `release()`, `revoke()`.
+    - `AsyncDisposable`: `await using lock = ablo.<model>.intent(id)` auto-releases
+      on scope exit.
+  - `acquireOrAwait()` — serialize-on-contention: take the lease, or wait out the
+    current holder, re-read the changed row, then take it. The caller never branches
+    on who holds the target — it just gets the target safely. Bind it to an agent's
+    write-tool boundary so agents never reason about coordination.
+  - New exports: `ModelIntentHandle`, `ModelIntentAcquireOptions`.
+
+  ### Changed
+  - `acquire()` is fire-and-forget over the socket — it does not throw on conflict.
+    Resolve contention with `acquireOrAwait()` (wait) or read `current` for a
+    reactive "who's editing" badge, rather than catching a rejection.
+
+  ### Deprecated
+  - Participant-level `intents.claim()` / `onRejected()` and the `intent_rejected`
+    wire frame still work but are superseded by the per-model handle. Their removal
+    is a future breaking change.
+
 ## Unreleased
 
 Schema-driven identity sync-group composition, plus a terser capability surface.
 
 The convention for deriving a participant's allowed sync-groups from its identity is now declared on the consumer's schema as an open registration. Consumers with a `{ regionId, customerId }` identity shape declare their own roles instead of receiving any built-in prefixes from the SDK.
 
-Capability fields shed their redundant `allowed` prefix to match the surrounding vocabulary — capability inputs always describe what the bearer *can* touch, so the prefix was doing no disambiguation work for the consumer.
+Capability fields shed their redundant `allowed` prefix to match the surrounding vocabulary — capability inputs always describe what the bearer _can_ touch, so the prefix was doing no disambiguation work for the consumer.
 
 ### Added
 
 - `DefineSchemaOptions.identityRoles?: readonly IdentityRole[]` — open registration of identity-anchored sync-group roles on `defineSchema(...)`. Each `IdentityRole` declares `{ kind, template, extract }`: a diagnostic label, a `'<prefix>:{id}'` template, and a pure extractor function from an opaque identity context to zero-or-more ids. No closed enum; consumers fully control both the template strings and the extraction logic.
-- `composeIdentitySyncGroups(identity, schema)` exported from `@ablo/sync-engine/schema` — walks the schema's registered `identityRoles`, calls each extractor, and substitutes ids into templates. Stable, deduped output. Returns `[]` when no roles are registered.
+- `composeIdentitySyncGroups(identity, schema)` exported from `@abloatai/ablo/schema` — walks the schema's registered `identityRoles`, calls each extractor, and substitutes ids into templates. Stable, deduped output. Returns `[]` when no roles are registered.
 - `Schema.identityRoles: readonly IdentityRole[]` — the registered list, accessible on every `defineSchema(...)` result.
 - New exported types: `IdentityRole`, `IdentityContext`.
 
@@ -47,7 +85,7 @@ Declarative props absorb every class of lifecycle glue; the status hook returns
 
 ### Added
 
-- `<AbloProvider>` — umbrella provider at `@ablo/sync-engine/react`. Props include data config (`schema`, `url`, `userId`, `organizationId`), auth (`capabilityToken` / `apiKey` / session cookie fallback), declarative behavior (`preventUnsavedChanges`, `lostConnectionTimeout`, `postBootstrap`), callbacks (`onSessionExpired`, `onError`, `resolveUsers`), and DI escape hatches.
+- `<AbloProvider>` — umbrella provider at `@abloatai/ablo/react`. Props include data config (`schema`, `url`, `userId`, `organizationId`), auth (`capabilityToken` / `apiKey` / session cookie fallback), declarative behavior (`preventUnsavedChanges`, `lostConnectionTimeout`, `postBootstrap`), callbacks (`onSessionExpired`, `onError`, `resolveUsers`), and DI escape hatches.
 - `<SyncGroupProvider id="matter:...">` + `useSyncGroup()` — per-entity scope context.
 - `<ClientSideSuspense fallback={...}>` — gate renders until the engine reports `connected`. Phase-1 non-Suspense; phase-2 upgrades to real Suspense.
 - `useSyncStatus()` rewritten as a tagged union: `{ name: 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'needs-auth', ... }`. Impossible states are unrepresentable.
@@ -155,7 +193,7 @@ The SDK covers exactly three integration shapes. Each has a canonical example in
 
 ### Ergonomics (package-wide)
 
-- **`Ablo` class** — `import Ablo from '@ablo/sync-engine'` / `new Ablo({ schema })`. Matches `new Stripe()` / `new OpenAI()` / `new Anthropic()` pattern. `createMesh(opts)` stays available as the functional alias.
+- **`Ablo` class** — `import Ablo from '@abloatai/ablo'` / `new Ablo({ schema })`. Matches `new Stripe()` / `new OpenAI()` / `new Anthropic()` pattern. `createMesh(opts)` stays available as the functional alias.
 - **Model-scoped joins** — `ablo.matters.join(id, { label })` desugars to the generic `join`. Proxy-based so the namespace adapts to any schema. Collisions with reserved admin fields (`roles`, `members`, `audit`, `capabilities`) throw at construction time.
 - **Flat scope form** — `scope: { matters: id }` alongside the array form.
 - **`as` alias** — `{ as: session({...}) }` replaces the security-jargon `onBehalfOf`; both still accepted.
@@ -199,7 +237,7 @@ Initial release.
 - **AI Agent SDK**: `SyncAgent` for backend/AI agent participation as first-class sync citizens
 - **Pluggable auth**: `AuthProvider` interface with built-in API key, JWT, and session providers
 - **Security**: IndexedDB cleanup on session expiry and sync group revocation
-- **Testing utilities**: `@ablo/sync-engine/testing` subpath with mocks, fixtures, and harness
+- **Testing utilities**: `@abloatai/ablo/testing` subpath with mocks, fixtures, and harness
 
 ### Test Coverage
 

package/NOTICE

@@ -1,4 +1,4 @@
-@ablo/sync-engine
+@abloatai/ablo
 Copyright 2025-2026 Fablo Innovation AB
 
 This product includes software developed by Fablo Innovation AB
@@ -7,6 +7,6 @@ This product includes software developed by Fablo Innovation AB
 "Ablo" is a trademark of Fablo Innovation AB. This license does not grant
 permission to use the Ablo name, logo, or trademarks. Third parties
 may describe their use of or compatibility with Ablo factually (e.g.,
-"built with @ablo/sync-engine") but may not use the Ablo name in a way
+"built with @abloatai/ablo") but may not use the Ablo name in a way
 that suggests endorsement, affiliation, or origin without written
 permission.

package/README.md

@@ -13,7 +13,7 @@ schema -> ablo.<model>.create/load/edit/update(...)
 ## Install
 
 ```bash
-npm install @ablo/sync-engine
+npm install @abloatai/ablo
 ```
 
 Requires Node 22+ and TypeScript 5+.
@@ -32,9 +32,9 @@ provider. Do not ship `ABLO_API_KEY` in a browser bundle.
 
 ## Quick Start
 
-```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+````ts
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   weatherReports: model({
@@ -64,13 +64,13 @@ const updated = await ablo.weatherReports.update(created.id, {
 console.log({ id: updated.id, status: updated.status });
 
 await ablo.dispose();
-```
+```c
 
 Expected output:
 
 ```txt
 { id: '...', status: 'ready' }
-```
+````
 
 Pass `schema` for typed model resources. Omit it only for advanced server-side
 resource clients such as custom agents and MCP routes.
@@ -87,33 +87,37 @@ future agents, read [Integration Guide](./docs/integration-guide.md).
 
 ## AI Activity on Existing State
 
-Use `edit` when AI or background work will touch an existing row for more than a
-quick write. Other participants can see the activity while your code runs. The
-activity is cleared when `update` finishes; call `release` if the work ends
-without a write.
+When AI or background work will touch an existing row for more than a quick
+write, coordinate through `ablo.<model>.intent(id)` — the coordination accessor
+that sits beside `create`/`update`/`retrieve`. It returns a handle
+synchronously, so you can see who's already working on a row before you start.
 
 ```ts
-const edit = await ablo.weatherReports.edit('weather_stockholm', {
-  activity: 'checking_weather',
-  field: 'forecast',
-  ttl: '2m',
-});
+const report = ablo.weatherReports.intent('weather_stockholm');
+
+// Read side: is someone already on it? Wait for them to finish.
+if (report.current) {
+  report.current.heldBy; // 'agent:forecaster'
+  await report.settled();
+}
+
+// Write side: acquire so other participants yield while we work.
+await report.acquire({ action: 'checking_weather', field: 'forecast', ttl: '2m' });
 
 // Your existing weather tool or agent call. While this runs, other clients see
 // that weather_stockholm is being checked.
-const weather = await weatherAgent.getWeather(edit.current.location, {
-  signal: edit.signal,
-});
+const row = ablo.weatherReports.retrieve('weather_stockholm');
+const weather = await weatherAgent.getWeather(row.location);
 
-await edit.update({
+await report.update({
   status: 'ready',
   forecast: weather.summary,
 });
 ```
 
-Ablo does not fetch the weather. It keeps the activity visible, gives the agent
-call an abort signal if the row changes, and clears the activity when
-`edit.update(...)` finishes.
+Ablo does not fetch the weather. It keeps the activity visible while the work
+runs, rejects `report.update(...)` with `AbloStaleContextError` if the row
+changed under you, and releases the intent automatically once the write lands.
 
 ## Multiplayer
 
@@ -123,8 +127,8 @@ the same shared resource stream.
 
 - `ablo.<model>.create/update/delete` fan out confirmed deltas to subscribers.
 - `useAblo(...)` gives React clients the live row plus active intents.
-- `ablo.<model>.edit(...)` lets humans and agents see active work before a write lands.
-- `ablo.intents` remains available for custom lower-level coordination.
+- `ablo.<model>.intent(id)` lets humans and agents see and coordinate active work before a write lands.
+- `ablo.intents` remains available for custom lower-level coordination across resources.
 
 If a team writes directly to its own database outside Ablo, that write bypasses
 the multiplayer stream until the app reports it through Data Source events.
@@ -162,9 +166,7 @@ if (busy.length > 0) {
   console.log(`${busy[0].actor} is ${busy[0].action}`);
 }
 
-await ablo.intents.waitFor(
-  { resource: 'weatherReports', id: 'weather_stockholm' },
-);
+await ablo.intents.waitFor({ resource: 'weatherReports', id: 'weather_stockholm' });
 ```
 
 Policy names are literal:
@@ -203,7 +205,7 @@ Data Source endpoint. Your app keeps the database credentials; Ablo sends signed
 commit requests to your route.
 
 ```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+ABLO_API_KEY=sk_live_...
 ```
 
 See [Connect Your Database](./docs/data-sources.md) for the route and commit shape.

package/dist/agent/Agent.d.ts

@@ -9,7 +9,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',

package/dist/agent/Agent.js

@@ -9,7 +9,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',

package/dist/agent/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ * @abloatai/ablo/agent — Agent SDK helpers
  *
  * Two entry points depending on agent lifetime:
  *
@@ -12,7 +12,7 @@
  * server-issued capability token instead of session cookies.
  *
  * ```ts
- * import Ablo from '@ablo/sync-engine';
+ * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({
  *   schema,
@@ -44,7 +44,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',
@@ -78,7 +78,7 @@
  * ```ts
  * import { tool } from 'ai';
  * import { z } from 'zod';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * export const updateSlideTool = () => tool({
  *   description: 'Update a slide title',

package/dist/agent/index.js

@@ -1,5 +1,5 @@
 /**
- * @ablo/sync-engine-internal/agent — Agent SDK helpers
+ * @abloatai/ablo/agent — Agent SDK helpers
  *
  * Two entry points depending on agent lifetime:
  *
@@ -12,7 +12,7 @@
  * server-issued capability token instead of session cookies.
  *
  * ```ts
- * import Ablo from '@ablo/sync-engine';
+ * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({
  *   schema,
@@ -44,7 +44,7 @@
  *
  * ```ts
  * import { generateText, tool, stepCountIs } from 'ai';
- * import { Agent } from '@ablo/sync-engine-internal/agent';
+ * import { Agent } from '@abloatai/ablo/agent';
  *
  * const perception = new Agent({
  *   syncServerUrl: 'http://localhost:8080',
@@ -78,7 +78,7 @@
  * ```ts
  * import { tool } from 'ai';
  * import { z } from 'zod';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * export const updateSlideTool = () => tool({
  *   description: 'Update a slide title',
@@ -117,12 +117,12 @@
 // `Agent` is the class AND the namespace for its types. Reach for
 // options, context, and session options via dot access:
 //
-//   import { Agent } from '@ablo/sync-engine-internal/agent';
+//   import { Agent } from '@abloatai/ablo/agent';
 //   const opts: Agent.Options = { ... };
 //   const ctx:  Agent.Context = { perception };
 //   const s:    Agent.SessionOptions = { ... };
 //
 // Everything else (Activity, Claim, Turn, Peer, ActiveIntent, ...)
 // lives on the `Ablo.*` namespace via
-// `import type { Ablo } from '@ablo/sync-engine'`.
+// `import type { Ablo } from '@abloatai/ablo'`.
 export { Agent } from './Agent.js';

package/dist/agent/types.d.ts

@@ -35,7 +35,7 @@ export interface PresenceAnnouncer {
  *
  * ```ts
  * import { generateText, tool } from 'ai';
- * import { Agent, type AgentContext } from '@ablo/sync-engine-internal/agent';
+ * import { Agent, type AgentContext } from '@abloatai/ablo/agent';
  *
  * const updateSlideTool = () => tool({
  *   inputSchema: z.object({ id: z.string(), title: z.string() }),

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

@@ -1,5 +1,5 @@
 /**
- * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
  * middleware.
  *
  * Two cross-cutting middlewares for any AI SDK consumer using
@@ -24,7 +24,7 @@
  * import {
  *   intentBroadcastMiddleware,
  *   coordinationContextMiddleware,
- * } from '@ablo/sync-engine-internal/ai-sdk';
+ * } from '@abloatai/ablo/ai-sdk';
  *
  * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
  *
@@ -48,7 +48,7 @@
  * Or use the convenience composition for the common case:
  *
  * ```ts
- * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
  *
  * const wrappedModel = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),

package/dist/ai-sdk/index.js

@@ -1,5 +1,5 @@
 /**
- * `@ablo/sync-engine-internal/ai-sdk` — multiplayer-with-AI as language model
+ * `@abloatai/ablo/ai-sdk` — multiplayer-with-AI as language model
  * middleware.
  *
  * Two cross-cutting middlewares for any AI SDK consumer using
@@ -24,7 +24,7 @@
  * import {
  *   intentBroadcastMiddleware,
  *   coordinationContextMiddleware,
- * } from '@ablo/sync-engine-internal/ai-sdk';
+ * } from '@abloatai/ablo/ai-sdk';
  *
  * const target = { entityType: 'SlideDeck', entityId: 'deck-abc' };
  *
@@ -48,7 +48,7 @@
  * Or use the convenience composition for the common case:
  *
  * ```ts
- * import { wrapWithMultiplayer } from '@ablo/sync-engine-internal/ai-sdk';
+ * import { wrapWithMultiplayer } from '@abloatai/ablo/ai-sdk';
  *
  * const wrappedModel = wrapWithMultiplayer({
  *   model: anthropic('claude-opus-4-7'),

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

@@ -11,7 +11,7 @@
  *
  * Open-source-clean: depends only on `@ai-sdk/provider` types and
  * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@ablo/sync-engine`.
+ * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
  *
  * Cost: one WS frame at stream start (`intent_begin`), one at end
  * (`intent_abandon`). No DB I/O, no extra LLM tokens.

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

@@ -11,7 +11,7 @@
  *
  * Open-source-clean: depends only on `@ai-sdk/provider` types and
  * the package's own `SyncAgent`. No app-specific assumptions —
- * Ablo's web app uses this, but so can any consumer of `@ablo/sync-engine`.
+ * Ablo's web app uses this, but so can any consumer of `@abloatai/ablo`.
  *
  * Cost: one WS frame at stream start (`intent_begin`), one at end
  * (`intent_abandon`). No DB I/O, no extra LLM tokens.

package/dist/auth/index.d.ts

@@ -63,7 +63,7 @@ export declare function resolveIdentity(options: ResolveIdentityRequest): Promis
 /**
  * Capability-token refresh scheduler.
  *
- * Long-lived `@ablo/sync-engine` clients hold a server-issued capability
+ * Long-lived `@abloatai/ablo` clients hold a server-issued capability
  * token whose TTL (1h default) is shorter than typical browser sessions.
  * Without proactive refresh, the WebSocket would either be force-closed
  * by the server at expiry (code 1008) or fail its next reconnect with

package/dist/client/Ablo.d.ts

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * Usage:
- *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { Ablo } from '@abloatai/ablo/client';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -21,7 +21,7 @@ import { ObjectPool } from '../ObjectPool.js';
 import type { SyncStoreContract } from '../react/context.js';
 import type { SyncWebSocket } from '../sync/SyncWebSocket.js';
 import { type SyncStatus } from '../BaseSyncedStore.js';
-import type { IntentStream, PresenceStream, Snapshot } from '../types/streams.js';
+import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '../types/streams.js';
 import type { ParticipantManager } from '../sync/participants.js';
 import type { ActiveIntent, Duration, TargetRange } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
@@ -48,7 +48,7 @@ export interface Turn {
  * `ApiKeySetter` exactly so any rotation pattern that works with
  * `@anthropic-ai/sdk` works here.
  *
- * Re-exported from `./auth` so existing import paths (`@ablo/sync-engine`)
+ * Re-exported from `./auth` so existing import paths (`@abloatai/ablo`)
  * keep resolving; the canonical definition lives there alongside the
  * resolvers that consume it.
  */
@@ -69,8 +69,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     authToken?: string | null | undefined;
     /**
-     * Override the Ablo API base URL. Defaults to hosted production and reads
-     * `process.env['ABLO_BASE_URL']` if unset.
+     * Override the Ablo API base URL. Defaults to hosted production.
      */
     baseURL?: string | null | undefined;
     /** Per-request timeout in milliseconds. */
@@ -118,7 +117,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     apiKey?: string | ApiKeySetter | null | undefined;
     /**
      * Bearer auth token. Sent as `Authorization: Bearer <token>` on
-     * every request. Defaults to `process.env['ABLO_AUTH_TOKEN']`.
+     * every request.
      *
      * Use this for self-hosted deployments where your auth layer mints
      * cap tokens directly. Hosted-cloud consumers pass `apiKey` instead;
@@ -129,7 +128,6 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Override the default base URL. Defaults to
      * `wss://mesh.ablo.finance` for hosted production; pass an explicit
      * URL for self-hosted or staging (e.g. `wss://mesh-staging.ablo.finance`).
-     * Reads `process.env['ABLO_BASE_URL']` if unset.
      */
     baseURL?: string | null | undefined;
     /**
@@ -327,7 +325,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
  * deprecated aliases for one release cycle so consumers can migrate
  * without a flag day.
  */
-export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelEditHandle, ModelEditOptions, ModelOperations, } from './createModelProxy.js';
+export type { ModelCountOptions, ModelListOptions, ModelListScope, ModelLoadOptions, ModelIntentAcquireOptions, ModelIntentHandle, ModelOperations, } from './createModelProxy.js';
 import type { ModelOperations } from './createModelProxy.js';
 export type ResourceOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
@@ -366,11 +364,7 @@ export interface BusyOptions {
     /** HTTP API polling interval while waiting. WebSocket clients ignore it. */
     readonly busyPollInterval?: number;
 }
-export interface IntentWaitOptions {
-    readonly timeout?: number;
-    readonly pollInterval?: number;
-    readonly signal?: AbortSignal;
-}
+export type { IntentWaitOptions } from '../types/streams.js';
 export interface ResourceReadOptions extends BusyOptions {
 }
 export interface IntentCreateOptions {
@@ -816,7 +810,7 @@ export declare namespace Ablo {
         type Event = import('../source/index.js').SourceEvent;
         type EventsResult = import('../source/index.js').SourceEventsResult;
         type Scope = import('../source/index.js').SourceScope;
-        type Secret = import('../source/index.js').SourceSecret;
+        type ApiKey = import('../source/index.js').SourceApiKey;
         type Options<S extends _SchemaTypes.SchemaRecord = _SchemaTypes.SchemaRecord, TAuth = unknown> = import('../source/index.js').AbloSourceOptions<S, TAuth>;
         type ModelHandlers<Row, CreateInput, TAuth = unknown> = import('../source/index.js').SourceModelHandlers<Row, CreateInput, TAuth>;
         type SignatureVerificationResult = import('../source/index.js').SourceSignatureVerificationResult;

package/dist/client/Ablo.js

@@ -5,7 +5,7 @@
  * bootstrap, offline queue, DI adapters) behind a single function call.
  *
  * Usage:
- *   import { Ablo } from '@ablo/sync-engine/client';
+ *   import { Ablo } from '@abloatai/ablo/client';
  *   import { schema } from './schema';
  *
  *   const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
@@ -1147,6 +1147,37 @@ export function Ablo(options) {
                 getLastSyncId: () => store.getSyncWebSocket()?.getLastSyncId() ?? store.lastSyncId ?? 0,
                 entities: { [modelKey]: id },
             }),
+            observe: (target) => {
+                // The live intent stream only tracks *open* (active) claims;
+                // terminal states (committed / expired / canceled) drop out of
+                // the list entirely — exactly the ephemeral coordination model.
+                // So a present entry is, by definition, `status: 'active'`.
+                const held = publicIntents.list({
+                    resource: target.resource,
+                    id: target.id,
+                })[0];
+                if (!held)
+                    return null;
+                return {
+                    object: 'intent',
+                    id: held.id,
+                    status: 'active',
+                    target: {
+                        type: held.target.resource,
+                        id: held.target.id,
+                        ...(held.target.path ? { path: held.target.path } : {}),
+                        ...(held.target.range ? { range: held.target.range } : {}),
+                        ...(held.target.field ? { field: held.target.field } : {}),
+                        ...(held.target.meta ? { meta: held.target.meta } : {}),
+                    },
+                    action: held.action,
+                    heldBy: held.actor,
+                    participantKind: held.participantKind,
+                    expiresAt: held.expiresAt,
+                };
+            },
+            waitFor: (target, waitOptions) => publicIntents.waitFor({ resource: target.resource, id: target.id }, waitOptions),
+            selfParticipantId: participantId,
         });
     }
     const commits = {

package/dist/client/auth.d.ts

@@ -7,9 +7,9 @@
  * with an actionable message — so the constructor reads as a
  * sequence of named decisions rather than a stream of `??`-chains.
  *
- * Precedence for every resolver: explicit option → environment
- * variable → built-in default. The same shape Anthropic, OpenAI,
- * and Stripe SDKs use.
+ * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
+ * is the only environment fallback. Other routing/auth overrides are
+ * explicit options so generated apps do not accrete hidden env knobs.
  */
 /**
  * Async callable that resolves to a fresh API key. Mirrors the shape

package/dist/client/auth.js

@@ -7,9 +7,9 @@
  * with an actionable message — so the constructor reads as a
  * sequence of named decisions rather than a stream of `??`-chains.
  *
- * Precedence for every resolver: explicit option → environment
- * variable → built-in default. The same shape Anthropic, OpenAI,
- * and Stripe SDKs use.
+ * Customer-facing env surface is intentionally small: `ABLO_API_KEY`
+ * is the only environment fallback. Other routing/auth overrides are
+ * explicit options so generated apps do not accrete hidden env knobs.
  */
 import { AbloAuthenticationError } from '../errors.js';
 /**
@@ -25,11 +25,11 @@ export function resolveApiKey(input) {
     return input.options.apiKey ?? input.env.ABLO_API_KEY ?? null;
 }
 export function resolveAuthToken(input) {
-    return input.options.authToken ?? input.env.ABLO_AUTH_TOKEN ?? null;
+    return input.options.authToken ?? null;
 }
 export const ABLO_DEFAULT_BASE_URL = 'wss://mesh.ablo.finance';
 export function resolveBaseURL(input) {
-    return (input.options.baseURL ?? input.env.ABLO_BASE_URL ?? ABLO_DEFAULT_BASE_URL);
+    return input.options.baseURL ?? ABLO_DEFAULT_BASE_URL;
 }
 /**
  * Browser guard — apiKey is server-side-only by default. Same check