@abloatai/ablo 0.22.1 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.23.0
+
+### Minor Changes
+
+- 2807efb: `create` now returns the created row, not a `CommitReceipt`.
+
+  The WebSocket client's `create` already returned the row (`T`); the HTTP client
+  and the `.model(name)` accessor returned a `CommitReceipt`, so "create returns
+  the thing I created" only held on one transport. Both now return the confirmed,
+  authoritative server row (framework defaults like `createdAt`/`createdBy`
+  included). For an idempotent re-create of an existing caller-supplied id, the
+  EXISTING row is returned (not the input).
+
+  BREAKING (HTTP / `.model()` callers only): `await ablo.<model>.create(...)` now
+  resolves to the row instead of `{ status, lastSyncId, ... }`. Code that ignored
+  the return value, or that read `.id` (the row carries `id` too), is unaffected;
+  code that read `lastSyncId` / `serverTxId` / `status` off a typed model create
+  should use the raw `commits.create(...)` resource, which still returns a
+  `CommitReceipt`. WebSocket-client callers are unaffected (already returned `T`).
+
+- 2807efb: `delete` is idempotent — deleting an already-absent row is a no-op success, not
+  an error.
+
+  The WebSocket client's `delete` threw `entity_not_found` when the row wasn't in
+  the local pool, while the HTTP client returned without error — so "delete this"
+  was a hard edge on one transport. Both now agree: a row that isn't present is
+  already gone, so the delete succeeds with no effect. This is AIP-135's
+  recommended behavior for client-assigned-id / declarative APIs (Ablo is exactly
+  that), and it makes delete safe to retry and to race (two actors deleting the
+  same row). The deliberate "loud 0-row" assertion in `@ablo/slides-sdk` is
+  unchanged (it keeps its own `allowMissing` opt-out).
+
+- 2807efb: `retrieve` reports a missing row as `data: undefined` instead of throwing.
+
+  The HTTP client previously threw `model_not_found` for a missing row while the
+  WebSocket client returned `T | undefined` — so the obvious read ("does this row
+  exist?") was a hard edge an agent had to wrap in `try/catch` on one transport
+  only. Both transports now agree: an absent row is data-absence, not an error.
+  `ModelRead.data` is now `T | undefined` (matching the documented `.data?.x`
+  usage). Taking a `claim` on a row that doesn't exist still throws
+  `AbloNotFoundError` — a claim has nothing to hold.
+
 ## 0.22.1
 
 ### Patch Changes

package/dist/BaseSyncedStore.js

@@ -215,7 +215,7 @@ export class BaseSyncedStore {
                     this.hydratedGroups.add(g);
             }
             catch (err) {
-                getContext().logger.warn('[BaseSyncedStore] scoped hydrate failed', {
+                getContext().logger.debug('[BaseSyncedStore] scoped hydrate failed', {
                     syncGroups: need,
                     error: err instanceof Error ? err.message : String(err),
                 });
@@ -684,7 +684,7 @@ export class BaseSyncedStore {
                     }
                 }
                 catch (fallbackError) {
-                    getContext().logger.warn('[BaseSyncedStore] Local fallback failed', {
+                    getContext().logger.debug('[BaseSyncedStore] Local fallback failed', {
                         error: fallbackError.message,
                     });
                 }
@@ -752,7 +752,7 @@ export class BaseSyncedStore {
                         "(e.g. new URL('/api/ablo-session', process.env.NEXT_PUBLIC_APP_URL)).", { error: message });
                 }
                 else {
-                    getContext().logger.warn('access-credential re-mint failed (transient)', { error: message });
+                    getContext().logger.debug('access-credential re-mint failed (transient)', { error: message });
                 }
                 return 'network_error';
             }
@@ -951,7 +951,7 @@ export class BaseSyncedStore {
         const rawObj = (raw ?? {});
         const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
         if (!groupKey) {
-            getContext().logger.warn('[BaseSyncedStore] Group removed delta missing group key', {
+            getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
                 syncId: delta.id,
             });
             return;
@@ -1040,7 +1040,7 @@ export class BaseSyncedStore {
             });
         }
         catch (error) {
-            getContext().logger.warn('[BaseSyncedStore] Failed to check sync group shrinkage', {
+            getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
                 error: error instanceof Error ? error.message : String(error),
             });
         }
@@ -1102,7 +1102,7 @@ export class BaseSyncedStore {
                 hasLocalData = this.objectPool.size > 0;
             }
             catch (hydrateError) {
-                getContext().logger.warn('[sync-engine] IDB hydration failed', { error: hydrateError });
+                getContext().logger.debug('[sync-engine] IDB hydration failed', { error: hydrateError });
                 getContext().observability.captureBootstrapFailure(hydrateError, { type: 'hydration-from-idb' });
             }
             // Get sync baseline for WebSocket
@@ -1221,7 +1221,7 @@ export class BaseSyncedStore {
                 this.updateSyncStatus({ state: 'idle', progress: 100 });
             }
             catch (error) {
-                getContext().logger.warn('[sync-engine] Background bootstrap failed', {
+                getContext().logger.debug('[sync-engine] Background bootstrap failed', {
                     error: error instanceof Error ? error.message : String(error),
                     cause: error,
                 });
@@ -1418,7 +1418,7 @@ export class BaseSyncedStore {
                     return;
                 resolved = true;
                 unsubscribe();
-                getContext().logger.warn(`[BaseSyncedStore] waitForWebSocketConnected timed out after ${timeoutMs}ms — initialize() will return but the next mutation may race the upgrade.`);
+                getContext().logger.debug(`[BaseSyncedStore] waitForWebSocketConnected timed out after ${timeoutMs}ms — initialize() will return but the next mutation may race the upgrade.`);
                 resolve(false);
             }, timeoutMs);
         });
@@ -1519,7 +1519,9 @@ export class BaseSyncedStore {
             // SECURITY: Clear IndexedDB data on session expiry.
             // When auth is revoked, locally cached data must not persist on disk.
             this.database.clear().catch((clearErr) => {
-                getContext().logger.error('[BaseSyncedStore] Failed to clear database on session error', clearErr);
+                // consumer register: session ended, but cached data may remain on disk
+                getContext().logger.error('Your session ended, but some locally cached data could not be cleared from this device.');
+                getContext().logger.debug('[BaseSyncedStore] Failed to clear database on session error', clearErr);
             });
             this.objectPool.clear();
         });
@@ -1533,7 +1535,9 @@ export class BaseSyncedStore {
             this.updateSyncStatus({ state: 'offline', offlineSince: new Date() });
         });
         const onReconnectFailed = this.syncWebSocket.subscribe('reconnect_failed', ({ attempts }) => {
-            getContext().logger.warn('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
+            // consumer register: reconnection exhausted — the app is now offline
+            getContext().logger.warn('Lost connection to the sync service and could not reconnect. Your app is now offline; changes will sync once the connection is restored.');
+            getContext().logger.debug('[BaseSyncedStore] WebSocket reconnection gave up', { attempts });
             this.updateSyncStatus({ state: 'reconnecting' });
         });
         this.disposers.push(onConnected, onDisconnected, onReconnecting, onDelta, onDeltaBatch, onBootstrapRequired, onBootstrapData, onPresenceUpdate, onError, onSessionError, onHandshakeFailed, onReconnectFailed, () => { this.areaOfInterest?.dispose(); this.areaOfInterest = null; });
@@ -2126,7 +2130,7 @@ export class BaseSyncedStore {
             modelId: 'batch',
             error: error instanceof Error ? error : new Error(String(error)),
         });
-        getContext().logger.error('[BaseSyncedStore] Delta flush error', {
+        getContext().logger.debug('[BaseSyncedStore] Delta flush error', {
             error: error instanceof Error ? error.message : String(error),
         });
     };

package/dist/Database.js

@@ -436,7 +436,7 @@ export class Database {
                 }
                 const store = this.getStore(modelName, 'bootstrap');
                 if (!store) {
-                    getContext().logger.warn(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
+                    getContext().logger.debug(`[Bootstrap] NO IDB STORE for ${modelName} — ${modelData.length} items DROPPED`);
                     continue;
                 }
                 let writeErrors = 0;
@@ -1023,7 +1023,7 @@ export class Database {
                 // `DataError`, `AbortError`) so we can find what's wrong with
                 // the `compacted` payload shape or store schema.
                 const idbErr = err instanceof Error ? err : new Error(String(err));
-                getContext().logger.warn('[Database.processDeltaBatch] store tx FAILED', {
+                getContext().logger.debug('[Database.processDeltaBatch] store tx FAILED', {
                     modelName,
                     storeDeltasCount: storeDeltas.length,
                     errorName: idbErr.name,
@@ -1071,7 +1071,7 @@ export class Database {
             // persisted" signal loud when it actually happens. If this fires
             // repeatedly on the same sync IDs, a specific row is un-writable
             // (validation? compact issue?) and needs fixing at that layer.
-            getContext().logger.warn('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
+            getContext().logger.debug('[Database.processDeltaBatch] cursor withheld due to failed store tx', {
                 seen: highestSyncId,
                 persisted: highestPersistedSyncId,
                 gap: highestSyncId - highestPersistedSyncId,

package/dist/ObjectPool.js

@@ -232,7 +232,9 @@ export class ObjectPool {
                 // Warn about suspicious patterns
                 if (deltaInfo.action === 'I' &&
                     (history.lastAction === 'U' || history.lastAction === 'D')) {
-                    getContext().logger.warn(`ObjectPool.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
+                    // Internal delta-ordering anomaly that reconciles on the next
+                    // catch-up — forensic, not consumer-actionable → debug.
+                    getContext().logger.debug(`ObjectPool.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
                 }
             }
             // Update delta history
@@ -609,7 +611,9 @@ export class ObjectPool {
         const Constructor = ModelClass || this.registry.getModelByName(modelName);
         if (!Constructor) {
             if (!ModelClass && modelName === 'Unknown') {
-                getContext().logger.warn('ObjectPool.createFromData: No model identifier found', { data });
+                // Malformed row with no type marker — dropped, but nothing the consumer
+                // can act on (the actionable schema-drift case is handled below) → debug.
+                getContext().logger.debug('ObjectPool.createFromData: No model identifier found', { data });
                 getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
@@ -620,7 +624,11 @@ export class ObjectPool {
                     `. The schema pushed to this org may differ from your local ` +
                     `schema — run \`ablo status\` to compare.`, { code: 'model_not_registered' });
             }
-            getContext().logger.warn(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
+            // Genuinely actionable and NOT self-healing: a model the server is sending
+            // isn't in your schema, so these rows are silently skipped. Keep at warn,
+            // consumer register (their model name + the `ablo status` fix); forensics ride debug.
+            getContext().logger.warn(`Received data for "${modelName}", which isn't in your schema — these rows will be skipped. Run \`ablo status\` to compare your local schema with the server.`);
+            getContext().logger.debug(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
             getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;
         }
@@ -646,7 +654,9 @@ export class ObjectPool {
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
-            getContext().logger.warn(`[ObjectPool.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
+            // Internal construction failure — captured via observability below and
+            // re-fetched on resync; the stack is forensic → debug.
+            getContext().logger.debug(`[ObjectPool.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
             getContext().observability.captureTransactionFailure({
                 context: 'createFromData',
                 modelName,

package/dist/SyncClient.js

@@ -210,7 +210,13 @@ export class SyncClient extends EventEmitter {
                     // cascade), don't re-add it — Object.assign cannot restore the private
                     // isDisposed flag, so the model would be added in a broken state.
                     if (model.disposed) {
-                        getContext().logger.warn('[SyncClient] Skipping rollback restore for disposed model', {
+                        // Follow-on of an already-logged permanent error, not its own
+                        // problem: the tx that failed has already surfaced the cause in
+                        // TransactionQueue. Restoring a disposed model is a no-op by
+                        // design (can't revive the private isDisposed flag), so keep this
+                        // at `debug` instead of emitting a second `warn` that reads as a
+                        // distinct failure in the console.
+                        getContext().logger.debug('[SyncClient] Rollback skipped restore (model already disposed)', {
                             modelId: transaction.modelId,
                             modelName: transaction.modelName,
                             reason,
@@ -1007,8 +1013,14 @@ export class SyncClient extends EventEmitter {
         // this class of misconfiguration surfaces in dev instead of
         // manifesting as "my drag doesn't save."
         if (!this.userId || !this.organizationId) {
-            getContext().logger.warn('[sync] mutations dropped — SyncClient has no identity. ' +
-                'Did the store call `syncClient.initialize(userId, orgId)`?', {
+            // Internal invariant, not a consumer-actionable error: identity (user +
+            // org) hasn't arrived yet. The mutations stay queued and retry once it
+            // does, so this is `debug` — a transient startup race is normal. If it
+            // never clears it means the host app finished sign-in without seeding
+            // identity, which surfaces downstream as "writes never confirm"; we do
+            // NOT name internal wiring (`SyncClient.initialize`) here because that
+            // method isn't part of the @abloatai/ablo surface a reader could act on.
+            getContext().logger.debug('[sync] writes waiting for identity (user/org not set yet) — queued, will retry', {
                 pending: this.pendingMutations.length,
                 userId: this.userId,
                 organizationId: this.organizationId,
@@ -1601,7 +1613,9 @@ export class SyncClient extends EventEmitter {
                     // re-fetch and re-apply. Logged here so silent IDB failures
                     // are observable instead of disappearing into a default switch
                     // fall-through.
-                    getContext().logger.warn('[SyncClient.applyDeltaBatchToPool] skipping pool op for unpersisted delta', {
+                    // Self-healing: the next catch-up poll / reconnect re-fetches and
+                    // re-applies this delta, so it's forensic, not consumer-actionable → debug.
+                    getContext().logger.debug('[SyncClient.applyDeltaBatchToPool] skipping pool op for unpersisted delta', {
                         modelName,
                         modelId: modelId.slice(0, 12),
                     });

package/dist/agent/Agent.js

@@ -145,7 +145,9 @@ export class Agent {
                 await this.opts.announcer.announce(status, activity);
             }
             catch (err) {
-                this.opts.logger.warn('[perception] announcer error', {
+                // Best-effort presence; failing only means peers don't see this
+                // agent's status. Not consumer-actionable → maintainer register.
+                this.opts.logger.debug('[perception] announcer error', {
                     error: err.message,
                 });
             }
@@ -160,11 +162,11 @@ export class Agent {
                 syncGroups: this.opts.syncGroups,
             });
             if (!res.ok) {
-                this.opts.logger.warn(`[perception] announce failed: ${res.status} ${res.statusText}`);
+                this.opts.logger.debug(`[perception] announce failed: ${res.status} ${res.statusText}`);
             }
         }
         catch (err) {
-            this.opts.logger.warn('[perception] announce error', {
+            this.opts.logger.debug('[perception] announce error', {
                 error: err.message,
             });
         }

package/dist/agent/session.js

@@ -21,6 +21,7 @@
  */
 import { Ablo } from '../client/Ablo.js';
 import { AbloConnectionError } from '../errors.js';
+import { getContext } from '../context.js';
 /**
  * Returns a session whose `getAgent` method handles cache, mint,
  * sync_groups alignment, and lifecycle. Call `disposeAll()` from
@@ -100,12 +101,14 @@ export function createAgentSession(options) {
                 await agent.dispose();
             }
             catch { /* ignore */ }
-            // Use console.error directly (rather than the engine logger)
-            // because this path may run before the per-agent logger is
-            // attached. The structured fields match the cap-mint logger in
-            // `connectAgent.ts` so a single search picks both up.
-            // eslint-disable-next-line no-console
-            console.error('[Agent.session] ws bootstrap failed', {
+            // Route through the gated logger so this obeys ABLO_LOG_LEVEL like every
+            // other line: a plain consumer-register `error` headline (the unreachable
+            // URL + code), with the structured fields on a `debug` companion. The
+            // companion's shape matches the cap-mint logger in `connectAgent.ts` so a
+            // single search picks both up.
+            const log = getContext().logger;
+            log.error(`Agent could not connect to the sync server at ${wsUrl}${code ? ` (${code})` : ''}.`);
+            log.debug('[Agent.session] ws bootstrap failed', {
                 url: wsUrl,
                 surfaceClass: identity.surfaceClass,
                 orgId: identity.organizationId,

package/dist/client/Ablo.d.ts

@@ -410,7 +410,13 @@ import type { ModelOperations, ClaimOptions, ClaimParams, ClaimReadApi, AwaitedC
 export type ModelOperationAction = 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
 export type CommitWait = 'queued' | 'confirmed';
 export interface ModelRead<T = Record<string, unknown>> {
-    readonly data: T;
+    /**
+     * The row, or `undefined` when no row matched the id (or it's outside the
+     * caller's scope). A miss is data-absence, not an error — `retrieve` never
+     * throws "not found", mirroring the WebSocket client's `T | undefined`.
+     * Branch on it: `const deal = (await ablo.deals.retrieve({ id })).data; if (!deal) …`.
+     */
+    readonly data: T | undefined;
     readonly stamp: number;
     readonly claims: readonly ModelClaim[];
 }
@@ -572,10 +578,16 @@ export interface ModelClient<T = Record<string, unknown>> {
      * `.model(name)` accessor omits it (use the typed `ablo.<model>.list` there).
      */
     list?(options?: ServerReadOptions<T>): Promise<T[]>;
+    /**
+     * Create a row and return it — the confirmed, authoritative server row (with
+     * framework defaults like `createdAt`/`createdBy`), mirroring the WebSocket
+     * client's `create`. A re-create of an existing caller-supplied id is
+     * idempotent and returns the EXISTING row, not the input.
+     */
     create(params: ModelMutationOptions & {
         readonly data: Record<string, unknown>;
         readonly id?: string | null;
-    }): Promise<CommitReceipt>;
+    }): Promise<T>;
     update(params: ModelMutationOptions & {
         readonly id: string;
         readonly data: Record<string, unknown>;

package/dist/client/Ablo.js

@@ -20,7 +20,7 @@
  */
 import { z } from 'zod';
 import { baseFieldsSchema } from '../schema/schema.js';
-import { AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, toAbloError, claimedError } from '../errors.js';
+import { AbloError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, translateHttpError, toAbloError, claimedError } from '../errors.js';
 import { descriptionFromMeta } from '../coordination/schema.js';
 import { LoadStrategy, PropertyType } from '../types/index.js';
 import { initSyncEngine } from '../context.js';
@@ -1009,11 +1009,13 @@ export function Ablo(options) {
                 if (participantKind === 'user' &&
                     (resolvedSyncGroups.length === 0 ||
                         (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))) {
-                    logger.warn('Ablo({kind:"user"}) initialized with degenerate syncGroups — ' +
-                        'this client will receive zero deltas through the live WS path. ' +
-                        'Either pass `syncGroups` explicitly (typically ' +
-                        '`["org:${orgId}", "user:${userId}"]`) or verify your auth ' +
-                        'provider populates them. See packages/sync-engine/src/client/identity.ts.', { participantKind, resolvedSyncGroups });
+                    // Actionable and NOT self-healing (no live updates until fixed):
+                    // kept at warn, consumer register — engine jargon and the internal
+                    // file pointer stripped; forensic fields ride the debug companion.
+                    logger.warn('This client was started without sync groups, so it will not receive ' +
+                        'live updates. Pass `syncGroups` (for example ' +
+                        '`["org:<id>", "user:<id>"]`) or check that your auth provider supplies them.');
+                    logger.debug('degenerate syncGroups — details', { participantKind, resolvedSyncGroups });
                 }
                 _resolvedOrganizationId = accountScope;
                 if (resolved.refreshScheduler) {
@@ -1577,13 +1579,15 @@ export function Ablo(options) {
             async create(params) {
                 const id = params.id ?? createModelId();
                 await applyClaimedPolicy({ model: name, id }, params);
-                return commits.create({
+                // Confirm, then return the authoritative row (with framework defaults;
+                // the EXISTING row on an idempotent re-create) — mirrors the WS client.
+                await commits.create({
                     claimRef: params.claimRef,
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
                     ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
-                    wait: params.wait,
+                    wait: params.wait ?? 'confirmed',
                     operations: [
                         {
                             action: 'create',
@@ -1593,6 +1597,11 @@ export function Ablo(options) {
                         },
                     ],
                 });
+                const { data } = await retrieveModel(name, id, {});
+                if (data === undefined) {
+                    throw new AbloNotFoundError(`create ${name}/${id} did not yield a readable row (the write did not confirm).`, [id]);
+                }
+                return data;
             },
             update: updateModel,
             async delete(params) {
@@ -1764,7 +1773,8 @@ export function Ablo(options) {
                 await store.disconnect();
             }
             catch (err) {
-                logger.warn('Error during sync engine disposal', { error: err.message });
+                // Best-effort teardown — a disposal hiccup isn't consumer-actionable → debug.
+                logger.debug('Error during sync engine disposal', { error: err.message });
             }
             presenceStream.dispose();
             claimStream.dispose();

package/dist/client/ApiClient.js

@@ -5,7 +5,7 @@
  * IndexedDB, no WebSocket. It maps the public Model / Claim / Commit
  * nouns directly to HTTP routes on sync-server.
  */
-import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
+import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
 import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfCliKeyMismatch, warnIfDatabaseUrlEnvIgnored, warnIfDatabaseUrlDeprecated, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
@@ -502,10 +502,13 @@ export function createProtocolClient(options) {
         const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
             method: 'GET',
         });
-        const data = query.data;
-        if (!data) {
-            throw new AbloValidationError(`Model row not found: ${modelName}/${params.id}`, { code: 'model_not_found' });
-        }
+        // Miss = `data: undefined`, NOT a thrown error. The WebSocket client's
+        // `retrieve` returns `T | undefined` for a missing row; throwing only here
+        // made the obvious read ("does this row exist?") a hard edge that an agent
+        // had to wrap in try/catch. Both transports now agree: absent row → absent
+        // data. Callers branch on `.data` (already the documented `.data?.x` usage).
+        // Normalize a miss to `undefined` (the server may send `null` or omit it).
+        const data = (query.data ?? undefined);
         return {
             data,
             stamp: query.stamp ?? 0,
@@ -628,6 +631,12 @@ export function createProtocolClient(options) {
                 reason: params.reason ?? 'editing',
             });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
+            // A held claim hands back a snapshot; the typed `HeldClaim.data` is `T`.
+            // `retrieve` now reports a miss as `undefined` rather than throwing, but a
+            // claim on a row that doesn't exist has nothing to hold — surface it.
+            if (data === undefined) {
+                throw new AbloNotFoundError(`Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`, [params.id]);
+            }
             const release = () => releaseClaim(params);
             return {
                 object: 'claim',
@@ -730,7 +739,20 @@ export function createProtocolClient(options) {
                 const id = params.id ?? createModelId();
                 return withMutationClaim(id, params, async (options) => {
                     await applyClaimedPolicy({ model: name, id }, options);
-                    return mutateModel('create', name, id, params.data, options);
+                    // Confirm the write, then return the row — the obvious expectation of
+                    // "create" (the WebSocket client already returns the row). The read-
+                    // back is the authoritative server row, so it carries the framework
+                    // defaults (createdAt/createdBy/…) AND, for an idempotent re-create of
+                    // an existing id, the EXISTING row rather than the caller's input.
+                    await mutateModel('create', name, id, params.data, {
+                        ...options,
+                        wait: options?.wait ?? 'confirmed',
+                    });
+                    const { data } = await retrieveModel(name, { id });
+                    if (data === undefined) {
+                        throw new AbloNotFoundError(`create ${name}/${id} did not yield a readable row (the write did not confirm).`, [id]);
+                    }
+                    return data;
                 });
             },
             update: updateModel,

package/dist/client/createModelProxy.js

@@ -539,8 +539,13 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             }
             const { id } = params;
             const model = objectPool.get(id);
+            // Idempotent delete (AIP-135 for client-assigned ids): "ensure absent". A
+            // row that isn't in our replicated view is already gone from our
+            // perspective, so a delete is a no-op success — not an `entity_not_found`
+            // error. This matches the HTTP client (which never threw here) and makes
+            // delete safe to retry / race (two actors deleting the same row).
             if (!model)
-                throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
+                return;
             const claimed = activeClaims.get(id);
             const opts = mutationOptions(params);
             const handle = isClaimHandle(params.claim) ? params.claim : undefined;

package/dist/client/httpClient.d.ts

@@ -47,7 +47,12 @@ export interface AbloHttpClientOptions<S extends SchemaRecord> extends Omit<Ablo
 export interface HttpModelClient<T, C = T> {
     retrieve(params: ModelRetrieveParams & ModelReadOptions): Promise<ModelRead<T>>;
     list(options?: ServerReadOptions<T>): Promise<T[]>;
-    create(params: ModelCreateParams<T, C>): Promise<CommitReceipt>;
+    /**
+     * Create a row and return it — the confirmed, authoritative server row (with
+     * framework defaults), mirroring the WebSocket client's `create`. A re-create
+     * of an existing caller-supplied id is idempotent and returns the EXISTING row.
+     */
+    create(params: ModelCreateParams<T, C>): Promise<T>;
     update(params: ModelUpdateParams<C>): Promise<CommitReceipt>;
     /**
      * Functional update under contention — `update(id, current => next)`, the

package/dist/client/identity.js

@@ -201,7 +201,7 @@ async function resolveHosted(input) {
             return { expiresAtMs: Date.parse(next.expiresAt) };
         },
         onError: (err) => {
-            input.logger.warn('cap token refresh failed; will retry', {
+            input.logger.debug('cap token refresh failed; will retry', {
                 error: err.message,
             });
         },

package/dist/core/DatabaseManager.js

@@ -55,7 +55,7 @@ export class DatabaseManager {
             // safe to delete and re-create. Try exactly once: delete, then re-open.
             if (!(error instanceof IDBOpenTimeoutError))
                 throw error;
-            getContext().logger.warn('[sync-engine] meta DB open timed out — attempting self-heal (delete + retry)', { db: this.metaDbName, reason: error.reason });
+            getContext().logger.debug('[sync-engine] meta DB open timed out — attempting self-heal (delete + retry)', { db: this.metaDbName, reason: error.reason });
             getContext().observability.captureBootstrapFailure(error, {
                 type: 'meta-db-open-timeout',
             });

package/dist/core/StoreManager.js

@@ -33,7 +33,8 @@ export class StoreManager {
     async initializeStores(db) {
         this.db = db;
         if (this.isInitialized) {
-            getContext().logger.warn('StoreManager already initialized');
+            // Idempotent re-entry — harmless, nothing for the consumer to act on → debug.
+            getContext().logger.debug('StoreManager already initialized');
             return;
         }
         getContext().logger.info('Initializing ObjectStore instances for all models');
@@ -95,7 +96,9 @@ export class StoreManager {
                     getContext().logger.debug('Created index', { store: storeName, prop: propName });
                 }
                 catch (error) {
-                    getContext().logger.warn('Failed to create index', { store: storeName, prop: propName, error });
+                    // Internal IndexedDB index setup — a miss only affects local query
+                    // speed and isn't consumer-actionable → debug.
+                    getContext().logger.debug('Failed to create index', { store: storeName, prop: propName, error });
                 }
             }
             // For partial load strategy models, we'll create additional partial index database later

package/dist/mutators/UndoManager.js

@@ -17,6 +17,7 @@
  *     automatically invalidate the undo stack. Consumers should `clear()`
  *     the scope on sync error if they want strict correctness.
  */
+import { getContext } from '../context.js';
 import { createTransaction } from './Transaction.js';
 import { parseUndoEntry } from './inverseOp.js';
 import { resolveOps, DEFAULT_UNDO_CONFLICT_POLICY, } from './undoApply.js';
@@ -384,9 +385,9 @@ export class UndoScope {
             }
             catch (err) {
                 // A faulty observer must never break the editor's recording path.
-                if (typeof console !== 'undefined') {
-                    console.error('[UndoScope] onRecord listener threw', err);
-                }
+                // Routed through the gated logger; the consumer's own onRecord callback
+                // is at fault, so this is actionable → warn (no engine tag on the line).
+                getContext().logger.warn('An undo/redo onRecord listener threw — your callback should not throw', err);
             }
         }
     }
@@ -408,9 +409,9 @@ export class UndoScope {
                 listener();
             }
             catch (err) {
-                if (typeof console !== 'undefined') {
-                    console.error('[UndoScope] onChange listener threw', err);
-                }
+                // Consumer's own onChange callback is at fault → actionable warn,
+                // routed through the gated logger (no engine tag on the line).
+                getContext().logger.warn('An undo/redo onChange listener threw — your callback should not throw', err);
             }
         }
     }

package/dist/query/client.js

@@ -14,6 +14,7 @@
 import { z } from 'zod';
 import { translateHttpError } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
+import { getContext } from '../context.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -64,8 +65,11 @@ export async function postQuery(options, batch) {
             // 401) instead of a bare status. We deliberately DON'T throw —
             // fire-and-forget callers would kill the Next.js router on an
             // unhandled rejection — and still return empty slots, but the failure
-            // is now legible as an Ablo error. Direct console.error is
-            // INTENTIONAL: operators alert on the `[postQuery.error]` prefix.
+            // is now legible as an Ablo error. Routed through the gated logger so it
+            // obeys ABLO_LOG_LEVEL like everything else: a consumer-register `warn`
+            // (their models + the typed message + a wire `code`) with the forensics on
+            // a `debug` companion. Actionable and not self-healing — the read returns
+            // empty until the underlying cause (auth, network) is resolved.
             let body = null;
             try {
                 body = await response.clone().json();
@@ -74,14 +78,24 @@ export async function postQuery(options, batch) {
                 // non-JSON error page — translateHttpError falls back to status text
             }
             const err = translateHttpError(response.status, body);
-            console.error(`[postQuery.error] ${err.type} ${err.code ?? response.status} for ` +
-                `${batch.queries.map((q) => q.model).join(',')}: ${err.message}`);
+            const models = batch.queries.map((q) => q.model).join(', ');
+            getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
+            getContext().logger.debug('[postQuery.error] query http failure', {
+                type: err.type,
+                code: err.code ?? response.status,
+                models,
+                message: err.message,
+            });
             return { results: batch.queries.map(() => []) };
         }
         const raw = await response.json();
         const parsed = QueryBatchResultSchema.safeParse(raw);
         if (!parsed.success) {
-            console.error('[postQuery.error] malformed response:', parsed.error.issues);
+            // A malformed server response isn't something the consumer can act on
+            // (server/protocol issue) → debug, gated like everything else.
+            getContext().logger.debug('[postQuery.error] malformed response', {
+                issues: parsed.error.issues,
+            });
             return { results: batch.queries.map(() => []) };
         }
         return parsed.data;

package/dist/react/useMutators.js

@@ -51,7 +51,9 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                                 return result;
                             }
                             catch (err) {
-                                getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                                // The error is re-thrown to the caller's await (the real
+                                // consumer surface), so this is a forensic follow-on → debug.
+                                getContext().logger.debug(`[useMutators] mutator "${label}" threw`, { error: err });
                                 throw err;
                             }
                         });
@@ -62,7 +64,9 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                         return await fn({ tx, args });
                     }
                     catch (err) {
-                        getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                        // Re-thrown to the caller's await (the real consumer surface) →
+                        // this duplicate is forensic, debug only.
+                        getContext().logger.debug(`[useMutators] mutator "${label}" threw`, { error: err });
                         throw err;
                     }
                 };

package/dist/sync/BootstrapHelper.js

@@ -388,7 +388,7 @@ export class BootstrapHelper {
             });
         }
         catch (error) {
-            getContext().logger.warn('Failed to clear cache', { error });
+            getContext().logger.debug('Failed to clear cache', { error });
         }
     }
     // Cache helpers for offline bootstrap
@@ -402,7 +402,7 @@ export class BootstrapHelper {
             localStorage.setItem(this.getBootstrapCacheKey(orgId), JSON.stringify(data));
         }
         catch (e) {
-            getContext().logger.warn('Failed to cache bootstrap payload', {
+            getContext().logger.debug('Failed to cache bootstrap payload', {
                 error: e instanceof Error ? e.message : String(e),
             });
         }

package/dist/sync/ConnectionManager.js

@@ -141,7 +141,7 @@ export class ConnectionManager {
             this.callbacks?.onStateChange?.(nextState, prevState);
         }
         catch (err) {
-            getContext().logger.warn('[ConnectionManager] onStateChange threw', {
+            getContext().logger.debug('[ConnectionManager] onStateChange threw', {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
@@ -443,7 +443,7 @@ export class ConnectionManager {
      */
     async runRefreshCredential() {
         if (this.credentialRefreshAttempts >= MAX_CREDENTIAL_REFRESH_ATTEMPTS) {
-            getContext().logger.warn('[ConnectionManager] Access key still stale after repeated re-mints — stopping', { attempts: this.credentialRefreshAttempts });
+            getContext().logger.debug('[ConnectionManager] Access key still stale after repeated re-mints — stopping', { attempts: this.credentialRefreshAttempts });
             runInAction(() => {
                 this.credentialRefreshAttempts = 0;
             });
@@ -482,7 +482,7 @@ export class ConnectionManager {
         catch (error) {
             // A thrown refresher is transient by contract (offline / mint endpoint
             // unreachable) — back off and retry, never sign out.
-            getContext().logger.warn('[ConnectionManager] Credential re-mint threw (transient)', { error });
+            getContext().logger.debug('[ConnectionManager] Credential re-mint threw (transient)', { error });
             this.send({ type: 'RECONNECT_FAILED' });
         }
     }
@@ -504,7 +504,7 @@ export class ConnectionManager {
             }
         }
         catch (error) {
-            getContext().logger.error('[ConnectionManager] Reconnect threw', { error });
+            getContext().logger.debug('[ConnectionManager] Reconnect threw', { error });
             this.send({ type: 'RECONNECT_FAILED' });
         }
     }
@@ -517,14 +517,14 @@ export class ConnectionManager {
             // event (or watchdog) restart the cycle when the network comes
             // back.
             if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-                getContext().logger.warn('[ConnectionManager] Max retries while offline — parking until network restored');
+                getContext().logger.debug('[ConnectionManager] Max retries while offline — parking until network restored');
                 getContext().observability.breadcrumb('Max retries — parking offline', 'sync.offline', 'warning');
                 runInAction(() => {
                     this.attempt = 0;
                 });
                 return;
             }
-            getContext().logger.warn('[ConnectionManager] Max retries — hard reload');
+            getContext().logger.debug('[ConnectionManager] Max retries — hard reload');
             getContext().observability.breadcrumb('Max retries — hard reload', 'sync.offline', 'error');
             if (typeof window !== 'undefined') {
                 window.location.reload();
@@ -611,7 +611,7 @@ export class ConnectionManager {
                 // the user with a broken page.
                 const browserOnline = typeof navigator === 'undefined' || navigator.onLine === true;
                 if (this.stuckCycles >= MAX_STUCK_CYCLES_BEFORE_RELOAD && browserOnline) {
-                    getContext().logger.warn('[ConnectionManager] Watchdog: sustained stuck — hard reload');
+                    getContext().logger.debug('[ConnectionManager] Watchdog: sustained stuck — hard reload');
                     getContext().observability.breadcrumb('Watchdog hard reload', 'sync.offline', 'error');
                     if (typeof window !== 'undefined') {
                         window.location.reload();

package/dist/sync/NetworkProbe.js

@@ -141,7 +141,7 @@ export async function probeNetwork(input) {
                     // or an auth-tagged code this SDK doesn't recognise. Re-auth re-mints
                     // the same rejected credential and retrying won't help, so STOP
                     // rather than reconnect-loop or sign the user out.
-                    getContext().logger.warn('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                    getContext().logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
                         status: response.status,
                         code: authFailure,
                         recovery,
@@ -183,7 +183,7 @@ export async function probeNetwork(input) {
         // expected 204; log a warning so misconfigurations surface instead of
         // silently passing.
         if (response.status < 200 || response.status >= 300) {
-            getContext().logger.warn('[NetworkProbe] Unexpected probe response', {
+            getContext().logger.debug('[NetworkProbe] Unexpected probe response', {
                 status: response.status,
                 url,
                 latencyMs,

package/dist/sync/SyncWebSocket.js

@@ -1363,7 +1363,7 @@ export class SyncWebSocket extends EventEmitter {
         if (!this.ws)
             return;
         this.lastForceCloseReason = reason;
-        getContext().logger.warn('[SyncWebSocket] forceClose', {
+        getContext().logger.debug('[SyncWebSocket] forceClose', {
             reason,
             readyState: this.ws.readyState,
             msSinceOpen: this.lastOpenAt != null ? Date.now() - this.lastOpenAt : null,
@@ -1567,7 +1567,7 @@ export class SyncWebSocket extends EventEmitter {
         if (!hasDeltas && typeof payload.currentSyncId === 'number') {
             const serverHead = payload.currentSyncId;
             if (serverHead < this.lastSyncId) {
-                getContext().logger.warn('[SyncWebSocket] local cursor ahead of server head — resetting and resyncing', {
+                getContext().logger.debug('[SyncWebSocket] local cursor ahead of server head — resetting and resyncing', {
                     local: this.lastSyncId,
                     server: serverHead,
                     drift: this.lastSyncId - serverHead,

package/dist/transactions/TransactionQueue.js

@@ -601,7 +601,9 @@ export class TransactionQueue extends EventEmitter {
         }
         if (inFlight.length === 0)
             return;
-        getContext().logger.warn(`[TransactionQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
+        // Internal mechanic: each failed commit surfaces to the consumer via its own
+        // rejection path, so this aggregate is forensic — debug, not warn.
+        getContext().logger.debug(`[TransactionQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
         for (const id of inFlight) {
             const tx = this.commitStore.get(id);
             if (!tx)
@@ -1429,7 +1431,9 @@ export class TransactionQueue extends EventEmitter {
             }
             // If disconnected, re-schedule with same timeout (no backoff while offline)
             if (!this.isConnectedFn()) {
-                getContext().logger.warn('[TransactionQueue] Timeout fired while disconnected - re-scheduling', {
+                // Self-healing: re-schedule the confirmation wait while offline, no
+                // consumer action needed → debug.
+                getContext().logger.debug('[TransactionQueue] Timeout fired while disconnected - re-scheduling', {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                 });
@@ -1471,7 +1475,9 @@ export class TransactionQueue extends EventEmitter {
                     lastSeenSyncId: this.lastSeenSyncId,
                     retryCount: retryCount + 1,
                 });
-                getContext().logger.warn('[TransactionQueue] Re-scheduling with backoff', {
+                // Self-healing retry with backoff — the server already committed; we're
+                // just waiting on the delta. No consumer action → debug.
+                getContext().logger.debug('[TransactionQueue] Re-scheduling with backoff', {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                     nextTimeoutMs: nextTimeout,
@@ -1636,7 +1642,9 @@ export class TransactionQueue extends EventEmitter {
                     tx.status = 'failed';
                     tx.error = error;
                     this.commitLane.shift();
-                    getContext().logger.warn('[TransactionQueue] commit lane permanent error', {
+                    // Internal bookkeeping — the consumer-facing rejection is emitted via
+                    // 'transaction:failed' and surfaced by the permanent-error headline → debug.
+                    getContext().logger.debug('[TransactionQueue] commit lane permanent error', {
                         txId: tx.id.slice(0, 12),
                         attempts: tx.attempts,
                         message: error.message,
@@ -1808,14 +1816,36 @@ export class TransactionQueue extends EventEmitter {
                 const isRepeat = sig === this.lastPermanentErrorSig;
                 this.lastPermanentErrorSig = sig;
                 const logger = getContext().logger;
+                // Two registers, one call site, split by log level (the default
+                // consumer logger is gated at `warn`, so `debug` is invisible unless
+                // someone sets ABLO_LOG_LEVEL=debug to debug the engine itself):
+                //   • the default-visible line speaks the APP DEVELOPER's language —
+                //     their verb (`update`), their model, the typed error's own human
+                //     message, and the wire `code` for grep — the way AI SDK / Next.js
+                //     surface errors. No engine nouns ("TransactionQueue", "permanent",
+                //     "rolling back") and no JSON dump on this line: those alarm and
+                //     don't help someone who just installed @abloatai/ablo.
+                //   • the forensic `details` ride a companion `debug` line for whoever
+                //     is debugging the engine internals.
+                const revertNote = this.config.enableOptimistic
+                    ? ' The local change was reverted.'
+                    : '';
+                const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
+                const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
+                const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}.${revertNote}`;
                 if (isRepeat) {
-                    logger.debug('[TransactionQueue] Permanent error - rolling back (repeat)', details);
+                    // Same write rejected for the same reason on each reconnect replay —
+                    // log the forensics once, stay quiet after.
+                    logger.debug('write rejected again (same reason)', details);
                 }
                 else if (isBenignIdempotent) {
-                    logger.info('[TransactionQueue] Write skipped — row already exists', details);
+                    // Already-exists on a `create` is expected on replay, not a problem.
+                    logger.info(`Your ${transaction.type} to "${transaction.modelName}" was skipped — this row already exists.`);
+                    logger.debug('idempotent skip — details', details);
                 }
                 else {
-                    logger.warn('[TransactionQueue] Permanent error - rolling back', details);
+                    logger.warn(headline);
+                    logger.debug('write rejection — details', details);
                 }
             }
             catch { }

package/package.json

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