@abloatai/ablo 0.10.1 → 0.11.1

package/dist/client/Ablo.js

@@ -19,7 +19,9 @@
  *   await sync.reports.delete({ id: reportId });
  */
 import { z } from 'zod';
-import { AbloClaimedError, AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, toAbloError } from '../errors.js';
+import { baseFieldsSchema } from '../schema/schema.js';
+import { AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, toAbloError, claimedError } from '../errors.js';
+import { descriptionFromMeta } from '../coordination/schema.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
 import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../SyncEngineContext.js';
@@ -32,15 +34,15 @@ import { resolveParticipantIdentity } from './identity.js';
 import { Model } from '../Model.js';
 import { BaseSyncedStore } from '../BaseSyncedStore.js';
 import { createPresenceStream } from '../sync/createPresenceStream.js';
-import { createIntentStream } from '../sync/createIntentStream.js';
-import { awaitIntentGrant } from '../sync/awaitIntentGrant.js';
+import { createClaimStream } from '../sync/createClaimStream.js';
+import { awaitClaimGrant } from '../sync/awaitClaimGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
 // Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
 // which imports this module type-only.
 import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
@@ -240,7 +242,18 @@ function registerModelsFromSchema(schema, registry) {
         }
         // Create a dynamic Model subclass with JSON sub-property getters
         const isLazy = modelDef.lazyObservable === true;
-        const fieldNames = Object.keys(modelDef.shape);
+        // Base provenance fields (`organizationId`, `createdBy`) live in
+        // `baseFieldsSchema`, not the per-model `shape`. The server stamps + emits
+        // them (camelCased on the wire), but hydration (`Model.assignFieldsFromData`)
+        // only assigns keys that already exist as an own/prototype property — so
+        // without a slot here, `deck.createdBy` / `deck.organizationId` silently read
+        // `undefined` (this is why the profile decks tab showed nothing: it filters
+        // `decks.filter(d => d.createdBy === userId)`). `id`/`createdAt`/`updatedAt`
+        // are already seeded by the base Model constructor, so they're excluded.
+        const fieldNames = [
+            ...Object.keys(modelDef.shape),
+            ...Object.keys(baseFieldsSchema.shape).filter((f) => f !== 'id' && f !== 'createdAt' && f !== 'updatedAt' && !(f in modelDef.shape)),
+        ];
         const computed = modelDef.computed;
         const DynamicModel = createDynamicModelClass(modelName, jsonSubFields, fieldNames, computed, isLazy);
         // Respect the schema's load strategy so lazy models skip IDB hydration + bootstrap
@@ -712,6 +725,9 @@ export function Ablo(options) {
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const { logger = consoleLogger } = internalOptions;
+    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
+    // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
+    warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
     // 1. Derive config from schema
@@ -821,8 +837,8 @@ export function Ablo(options) {
     // becomes null, so the first Ablo's commits start throwing
     // `ws_not_ready` forever (terminal AgentJob writes hang on retry).
     syncClient.getTransactionQueue().setMutationExecutor(executor);
-    // Presence + intent streams — built eagerly so `engine.presence`
-    // and `engine.intents` return the same reference for the engine's
+    // Presence + claim streams — built eagerly so `engine.presence`
+    // and `engine.claims` return the same reference for the engine's
     // lifetime. The transport doesn't exist yet (BaseSyncedStore.initialize
     // creates it during ready()), so both streams are constructed in
     // deferred-attach mode and wired after initialize() resolves below.
@@ -837,12 +853,12 @@ export function Ablo(options) {
         syncGroups: internalOptions.syncGroups ?? [],
         isAgent: internalOptions.kind === 'agent',
     });
-    const intentStream = createIntentStream({ participantId });
+    const claimStream = createClaimStream({ participantId });
     const participantManager = createParticipantManager({
         ready,
         getTransport: () => store.getSyncWebSocket() ?? null,
         presence: presenceStream,
-        intents: intentStream,
+        claims: claimStream,
         schema,
     });
     // 6. Validate options up front — fail loudly on obviously wrong inputs so
@@ -990,14 +1006,14 @@ export function Ablo(options) {
                             code: 'bootstrap_fetch_timeout',
                         });
                 }
-                // Wire presence + intents to the now-open transport.
+                // Wire presence + claims to the now-open transport.
                 // `getSyncWebSocket()` returns non-null after a successful
                 // initialize() — the WS is created during the generator's
                 // connect step.
                 const ws = store.getSyncWebSocket();
                 if (ws) {
                     presenceStream.attach(ws);
-                    intentStream.attach(ws);
+                    claimStream.attach(ws);
                 }
                 logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
             }
@@ -1073,10 +1089,10 @@ export function Ablo(options) {
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function normalizeIntentId(intent) {
-        if (typeof intent === 'string')
-            return intent;
-        return intent?.id;
+    function normalizeClaimId(claim) {
+        if (typeof claim === 'string')
+            return claim;
+        return claim?.id;
     }
     function isClaimHandleValue(value) {
         return (typeof value === 'object' &&
@@ -1113,82 +1129,72 @@ export function Ablo(options) {
         }
         return inputOperations.map((op) => normalizeCommitOperation(op, commitOptions));
     }
-    function modelClaimFromActive(intent) {
-        const description = typeof intent.target.meta?.description === 'string'
-            ? intent.target.meta.description
-            : undefined;
+    function modelClaimFromActive(claim) {
+        const description = descriptionFromMeta(claim.target.meta);
         return {
-            id: intent.id,
-            actor: intent.heldBy,
-            participantKind: intent.participantKind,
-            action: intent.reason,
+            id: claim.id,
+            actor: claim.heldBy,
+            participantKind: claim.participantKind,
+            action: claim.reason,
             ...(description ? { description } : {}),
-            field: intent.target.field,
+            field: claim.target.field,
             status: 'active',
-            expiresAt: intent.expiresAt,
+            expiresAt: claim.expiresAt,
             target: {
-                model: intent.target.type,
-                id: intent.target.id,
-                path: intent.target.path,
-                range: intent.target.range,
-                field: intent.target.field,
-                meta: intent.target.meta,
+                model: claim.target.type,
+                id: claim.target.id,
+                path: claim.target.path,
+                range: claim.target.range,
+                field: claim.target.field,
+                meta: claim.target.meta,
             },
         };
     }
-    function modelClaimFromQueued(intent) {
+    function modelClaimFromQueued(claim) {
         return {
-            id: intent.id,
-            actor: intent.heldBy,
-            participantKind: intent.participantKind,
-            action: intent.action,
-            ...(intent.description ? { description: intent.description } : {}),
-            field: intent.target.field,
+            id: claim.id,
+            actor: claim.heldBy,
+            participantKind: claim.participantKind,
+            action: claim.action,
+            ...(claim.description ? { description: claim.description } : {}),
+            field: claim.target.field,
             status: 'queued',
-            position: intent.position,
-            expiresAt: intent.expiresAt,
+            position: claim.position,
+            expiresAt: claim.expiresAt,
             target: {
-                model: intent.target.type,
-                id: intent.target.id,
-                path: intent.target.path,
-                range: intent.target.range,
-                field: intent.target.field,
-                meta: intent.target.meta,
+                model: claim.target.type,
+                id: claim.target.id,
+                path: claim.target.path,
+                range: claim.target.range,
+                field: claim.target.field,
+                meta: claim.target.meta,
             },
         };
     }
-    function targetMatchesModel(target, intent) {
+    function targetMatchesModel(target, claim) {
         if (target.model &&
-            intent.target.type.toLowerCase() !== target.model.toLowerCase()) {
+            claim.target.type.toLowerCase() !== target.model.toLowerCase()) {
             return false;
         }
-        if (target.id && intent.target.id !== target.id)
+        if (target.id && claim.target.id !== target.id)
             return false;
-        if (target.field && intent.target.field !== target.field)
+        if (target.field && claim.target.field !== target.field)
             return false;
         return true;
     }
     function listModelClaims(target) {
-        return intentStream.others
-            .filter((intent) => (target ? targetMatchesModel(target, intent) : true))
+        return claimStream.others
+            .filter((claim) => (target ? targetMatchesModel(target, claim) : true))
             .map(modelClaimFromActive);
     }
     function listModelClaimQueue(target) {
         if (!target?.model || !target.id)
             return [];
-        return publicIntents
+        return publicClaims
             .queueFor({ type: target.model, id: target.id })
-            .filter((intent) => (target.field ? intent.target.field === target.field : true))
+            .filter((claim) => (target.field ? claim.target.field === target.field : true))
             .map(modelClaimFromQueued);
     }
-    function claimedError(target, claims, code) {
-        const label = [target.model, target.id, target.field].filter(Boolean).join('/');
-        const holder = claims[0];
-        const suffix = holder
-            ? ` held by ${holder.actor} (${holder.action})`
-            : ' held by another participant';
-        return new AbloClaimedError(`Model row is claimed: ${label || 'target'}${suffix}.`, { code, claims });
-    }
     function waitForModelUnclaimed(target, options) {
         if (listModelClaims(target).length === 0)
             return Promise.resolve();
@@ -1216,8 +1222,8 @@ export function Ablo(options) {
                 }
             };
             const onAbort = () => {
-                finish(() => reject(new AbloConnectionError('Intent wait aborted.', {
-                    code: 'intent_wait_aborted',
+                finish(() => reject(new AbloConnectionError('Claim wait aborted.', {
+                    code: 'claim_wait_aborted',
                     cause: options?.signal?.reason,
                 })));
             };
@@ -1225,7 +1231,7 @@ export function Ablo(options) {
                 onAbort();
                 return;
             }
-            unsubscribe = intentStream.onChange(check);
+            unsubscribe = claimStream.onChange(check);
             options?.signal?.addEventListener('abort', onAbort, { once: true });
             if (options?.timeout != null) {
                 timeoutId = setTimeout(() => {
@@ -1250,58 +1256,61 @@ export function Ablo(options) {
         }
         await waitForModelUnclaimed(target, { timeout: options?.claimedTimeout });
     }
-    function wrapIntentHandle(claim, waited = false) {
+    function wrapClaimHandle(claim, waited = false) {
         const release = async () => {
             claim.revoke();
         };
         return {
-            id: claim.id,
+            object: 'claim',
+            claimId: claim.claimId,
+            action: claim.action,
+            target: claim.target,
             waited,
             release,
             revoke: claim.revoke,
             [Symbol.asyncDispose]: release,
         };
     }
-    const publicIntents = Object.assign(intentStream, {
-        async create(intentOptions) {
+    const publicClaims = Object.assign(claimStream, {
+        async create(claimOptions) {
             await ready();
-            const claim = intentStream.claim({
-                type: intentOptions.target.model,
-                id: intentOptions.target.id,
-                path: intentOptions.target.path,
-                range: intentOptions.target.range,
-                field: intentOptions.target.field,
-                meta: intentOptions.target.meta,
+            const claim = claimStream.claim({
+                type: claimOptions.target.model,
+                id: claimOptions.target.id,
+                path: claimOptions.target.path,
+                range: claimOptions.target.range,
+                field: claimOptions.target.field,
+                meta: claimOptions.target.meta,
             }, {
-                reason: intentOptions.action,
-                ttl: intentOptions.ttl,
-                queue: intentOptions.queue,
+                reason: claimOptions.action,
+                ttl: claimOptions.ttl,
+                queue: claimOptions.queue,
             });
             // With `queue`, the claim is only really *ours* once the server says
-            // so (`intent_acquired` if the target was free, `intent_granted` once
+            // so (`claim_acquired` if the target was free, `claim_granted` once
             // we reach the head of the FIFO line). Block here on that grant so
             // callers — chiefly `ablo.<model>.claim` — get a handle that already
             // holds the lease, never a half-claimed one racing the queue.
             let waited = false;
-            if (intentOptions.queue) {
+            if (claimOptions.queue) {
                 const ws = store.getSyncWebSocket();
                 if (ws) {
                     try {
-                        ({ waited } = await awaitIntentGrant(ws, claim.id, {
-                            timeoutMs: intentOptions.waitTimeoutMs,
-                            maxQueueDepth: intentOptions.maxQueueDepth,
+                        ({ waited } = await awaitClaimGrant(ws, claim.claimId, {
+                            timeoutMs: claimOptions.waitTimeoutMs,
+                            maxQueueDepth: claimOptions.maxQueueDepth,
                         }));
                     }
                     catch (err) {
                         // Gave up waiting (queue too deep, timed out, or lost) — abandon
-                        // the queued intent so we don't leave a phantom entry in the
+                        // the queued claim so we don't leave a phantom entry in the
                         // line that would block or mislead other claimers.
                         claim.revoke();
                         throw err;
                     }
                 }
             }
-            return wrapIntentHandle(claim, waited);
+            return wrapClaimHandle(claim, waited);
         },
         list(target) {
             return listModelClaims(target);
@@ -1310,14 +1319,14 @@ export function Ablo(options) {
             return waitForModelUnclaimed(target, options);
         },
     });
-    // Build the typed proxy — one property per model. Done after publicIntents
+    // Build the typed proxy — one property per model. Done after publicClaims
     // exists so model clients can expose workflow helpers such as
     // `ablo.files.edit(...)` without importing protocol wiring.
     const modelProxies = {};
     for (const [schemaKey, modelDef] of Object.entries(schema.models)) {
         const registeredModelName = modelDef.typename ?? schemaKey;
         modelProxies[schemaKey] = createModelProxy(schemaKey, registeredModelName, objectPool, syncClient, modelRegistry, hydration, {
-            createIntent: (intentOptions) => publicIntents.create(intentOptions),
+            createClaim: (claimOptions) => publicClaims.create(claimOptions),
             createSnapshot: (modelKey, id) => createSnapshot({
                 pool: objectPool,
                 transport: store.getSyncWebSocket(),
@@ -1331,21 +1340,21 @@ export function Ablo(options) {
                 getLastSyncId: () => syncClient.position.readFloor,
                 entities: { [modelKey]: id },
             }),
-            queue: (target) => publicIntents.queueFor({ type: target.model, id: target.id }),
-            reorder: (target, order) => publicIntents.reorder({ type: target.model, id: target.id }, order),
+            queue: (target) => publicClaims.queueFor({ type: target.model, id: target.id }),
+            reorder: (target, order) => publicClaims.reorder({ type: target.model, id: target.id }, order),
             observe: (target) => {
-                // The live intent stream only tracks *open* (active) claims;
+                // The live claim 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({
+                const held = publicClaims.list({
                     model: target.model,
                     id: target.id,
                 })[0];
                 if (!held)
                     return null;
                 return {
-                    object: 'intent',
+                    object: 'claim',
                     id: held.id,
                     status: 'active',
                     target: {
@@ -1362,8 +1371,20 @@ export function Ablo(options) {
                     expiresAt: held.expiresAt,
                 };
             },
-            waitFor: (target, waitOptions) => publicIntents.waitFor({ model: target.model, id: target.id }, waitOptions),
+            waitFor: (target, waitOptions) => publicClaims.waitFor({ model: target.model, id: target.id }, waitOptions),
             selfParticipantId: participantId,
+            selfParticipantKind: kind,
+            // Read-interest / write-intent enrolment for the typed surface.
+            // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
+            // through the SAME resolver the claim path uses, landing this client in
+            // the entity-scoped group the holder's claim presence fans out on.
+            // Return the store promise so the claim write path can AWAIT pinScope
+            // BEFORE acquiring the lease (closing the subscribe-vs-broadcast race);
+            // read-interest callers (`retrieve`/`claim.state`) still `void` it and
+            // stay fire-and-forget. SOFT either way — the store swallows reconcile
+            // errors so read interest never makes a read reject or stall.
+            enterScope: (scope) => store.enterScope(scope),
+            pinScope: (scope) => store.pinScope(scope),
         });
     }
     const commits = {
@@ -1375,7 +1396,7 @@ export function Ablo(options) {
                 readAt: commitOptions.readAt,
                 onStale: commitOptions.onStale,
                 wait: commitOptions.wait,
-                intent: commitOptions.intent,
+                claim: commitOptions.claim,
             }, 'commits.create');
             const clientTxId = createClientTxId(commitOptions.idempotencyKey);
             // A claim handle supplies the batch stale-guard defaults — same
@@ -1388,8 +1409,8 @@ export function Ablo(options) {
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
             });
             const wait = commitOptions.wait ?? 'confirmed';
-            const intentId = normalizeIntentId(commitOptions.intent) ?? claim?.claimId;
-            void intentId; // The current wire clears intents by entity after commit.
+            const claimId = normalizeClaimId(commitOptions.claimRef) ?? claim?.claimId;
+            void claimId; // The current wire clears claims by entity after commit.
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
             // reconnect, mutationExecutor.commit() owns transport-level
@@ -1462,7 +1483,7 @@ export function Ablo(options) {
                 const id = params.id ?? createModelId();
                 await applyClaimedPolicy({ model: name, id }, params);
                 return commits.create({
-                    intent: params.intent,
+                    claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
@@ -1481,7 +1502,7 @@ export function Ablo(options) {
             async update(params) {
                 await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({
-                    intent: params.intent,
+                    claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
@@ -1500,7 +1521,7 @@ export function Ablo(options) {
             async delete(params) {
                 await applyClaimedPolicy({ model: name, id: params.id }, params);
                 return commits.create({
-                    intent: params.intent,
+                    claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
@@ -1659,7 +1680,7 @@ export function Ablo(options) {
                 logger.warn('Error during sync engine disposal', { error: err.message });
             }
             presenceStream.dispose();
-            intentStream.dispose();
+            claimStream.dispose();
             syncClient.dispose();
         },
         /**
@@ -1711,8 +1732,8 @@ export function Ablo(options) {
         /** Presence livestream — same socket as entity sync, no second
          *  connection. Stable reference across the engine's lifetime. */
         presence: presenceStream,
-        /** Intent livestream — same socket. Stable reference. */
-        intents: publicIntents,
+        /** Claim livestream — same socket. Stable reference. */
+        claims: publicClaims,
         commits,
         model,
         /** Structured multiplayer participation — target-first, no

package/dist/client/ApiClient.d.ts

@@ -5,16 +5,17 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import type { AbloOptions, CommitResource, IntentCreateOptions, IntentHandle, IntentWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { AbloOptions, CommitResource, ClaimCreateOptions, ClaimWaitOptions, ModelClient, ModelClaim, ModelTarget } from './Ablo.js';
+import type { ClaimHandle } from './createModelProxy.js';
 import type { Duration } from '../utils/duration.js';
 export type AbloApiClientOptions = Omit<AbloOptions, 'schema'> & {
     readonly schema?: null | undefined;
     readonly bootstrapBaseUrl?: string | undefined;
 };
-export interface AbloApiIntents {
-    create(options: IntentCreateOptions): Promise<IntentHandle>;
+export interface AbloApiClaims {
+    create(options: ClaimCreateOptions): Promise<ClaimHandle>;
     list(target?: Partial<ModelTarget>): Promise<readonly ModelClaim[]>;
-    waitFor(target: Partial<ModelTarget>, options?: IntentWaitOptions): Promise<void>;
+    waitFor(target: Partial<ModelTarget>, options?: ClaimWaitOptions): Promise<void>;
 }
 export type CapabilityParticipantKind = 'agent' | 'system';
 export interface CapabilityCreateBaseOptions {
@@ -121,7 +122,7 @@ export interface AbloApi {
     dispose(): Promise<void>;
     purge(): Promise<void>;
     readonly capabilities: CapabilityResource;
-    readonly intents: AbloApiIntents;
+    readonly claims: AbloApiClaims;
     readonly commits: CommitResource;
     model<T = Record<string, unknown>>(name: string): ModelClient<T>;
     /**