@abloatai/ablo 0.18.0 → 0.20.0

package/dist/react/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { ActiveClaim, Peer } from '../types/streams.js';
+import type { Claim, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
 /**
@@ -154,7 +154,7 @@ export interface UseWatchReturn {
     /** Everyone else on the engine's sync groups (`participant.presence.others`), bridged to React. */
     readonly peers: ReadonlyArray<Peer>;
     /** Active claim claims by peers (`participant.claims.others`), bridged to React. */
-    readonly claims: ReadonlyArray<ActiveClaim>;
+    readonly claims: ReadonlyArray<Claim>;
     readonly status: ParticipantStatus;
     readonly error: Error | null;
 }

package/dist/react/useAblo.js

@@ -2,7 +2,7 @@
 import { useContext, useEffect, useState } from 'react';
 import { AbloInternalContext } from './internalContext.js';
 import { getModelClientMeta } from '../client/createModelProxy.js';
-import { Model, modelAsRow } from '../Model.js';
+import { Model } from '../Model.js';
 import { useReactive } from './useReactive.js';
 const EMPTY_CLAIMS = Object.freeze([]);
 function readModelResult(engine, modelClient, id, initial) {
@@ -16,9 +16,19 @@ function readModelResult(engine, modelClient, id, initial) {
         : EMPTY_CLAIMS;
     return { data, claims, claimed: claims.length > 0 };
 }
+/**
+ * Project a reactive read into the value `useReactive` caches and returns.
+ *
+ * For a `Model`, this MUST read the row's fields (via `toReactiveSnapshot`),
+ * not return the bare instance: MobX tracks property access, so reading the
+ * fields inside this tracked function is what subscribes the reaction to them —
+ * and the fresh object identity lets `useReactive`'s equality detect an
+ * in-place delta update. Returning `modelAsRow(value)` (the live instance, no
+ * field read) is why `useAblo(a => a.x.get(id))` used to ignore remote edits.
+ */
 function snapshotValue(value) {
     if (value instanceof Model) {
-        return modelAsRow(value);
+        return value.toReactiveSnapshot();
     }
     if (Array.isArray(value)) {
         return value.map((item) => snapshotValue(item));

package/dist/schema/sugar.js

@@ -66,7 +66,10 @@ function build(shape, opts, baseline) {
  *   - `.manual`   — never auto-loaded; explicit queries only
  */
 export const mutable = {
-    instant: (shape, opts) => build(shape, opts, { mutable: true, load: 'instant', lazyObservable: false }),
+    instant: (shape, opts) => 
+    // Reactive by default (see readonly.instant note): opt out with
+    // `lazyObservable: false` only for very large read-only list models.
+    build(shape, opts, { mutable: true, load: 'instant', lazyObservable: true }),
     lazy: (shape, opts) => build(shape, opts, { mutable: true, load: 'lazy', lazyObservable: true }),
     manual: (shape, opts) => build(shape, opts, { mutable: true, load: 'manual', lazyObservable: true }),
 };
@@ -82,7 +85,12 @@ export const mutable = {
  *     writes
  */
 export const readOnly = {
-    instant: (shape, opts) => build(shape, opts, { mutable: false, load: 'instant', lazyObservable: false }),
+    instant: (shape, opts) => 
+    // Reactive by default (like every variant now): a remote delta that mutates
+    // a row in place must re-render reactive reads. Opt out per-model with
+    // `lazyObservable: false` for very large read-only lists where per-field
+    // atoms cost more than the QueryView's entry-replaced reactivity.
+    build(shape, opts, { mutable: false, load: 'instant', lazyObservable: true }),
     lazy: (shape, opts) => build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
     /**
      * Internal-only: never auto-loaded, never written by clients. The

package/dist/server/read-config.d.ts

@@ -57,4 +57,11 @@ export interface BootstrapModel {
     fieldColumns?: Record<string, string>;
     /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
     columnOverrides?: readonly ColumnOverride[];
+    /**
+     * Physical columns the schema declares as `json` (`field.json()`). A json
+     * field stored in a TEXT column comes back from `row_to_json` as a serialized
+     * string; the bootstrap re-parses these so the wire is the canonical object
+     * regardless of physical column type (jsonb returns objects natively → no-op).
+     */
+    jsonColumns?: readonly string[];
 }

package/dist/sync/HydrationCoordinator.js

@@ -171,7 +171,11 @@ export class HydrationCoordinator {
     async fetchFromNetwork(modelName, typename, clauses, options) {
         const networkRows = await this.queryNetwork(modelName, clauses, options);
         const networkModels = networkRows
-            .map((raw) => this.hydrateOne(raw, typename))
+            // Strict: a row the SERVER returned whose typename this client never
+            // registered is a genuine schema collision (the org's pushed schema
+            // differs from local) — throw it here, naming the cause, rather than
+            // silently dropping the row and failing downstream as `entity_not_found`.
+            .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
             .filter((m) => m !== null);
         if (networkModels.length > 0) {
             this.opts.objectPool.addBatch(networkModels, ModelScope.live);
@@ -288,7 +292,7 @@ export class HydrationCoordinator {
     getModelDef(modelName) {
         return this.opts.schema.models?.[modelName];
     }
-    hydrateOne(raw, typename) {
+    hydrateOne(raw, typename, opts) {
         if (!raw || typeof raw !== 'object')
             return null;
         const obj = raw;
@@ -321,7 +325,7 @@ export class HydrationCoordinator {
         // re-populate it). The typename comes from the schema relation
         // (`'SlideLayer'`, `'SlideLayoutLayer'`, etc.) so no guessing involved.
         const stamped = this.stampTypename(obj, typename);
-        return this.opts.objectPool.createFromData(stamped);
+        return this.opts.objectPool.createFromData(stamped, undefined, opts);
     }
     /**
      * Stamp `__typename` onto a row when it's known (from the schema's

package/dist/sync/SyncWebSocket.d.ts

@@ -179,7 +179,7 @@ export interface PresenceUpdateEvent {
     participantKind?: string;
     timestamp?: number;
     /** Server stamps every presence frame with this participant's open
-     *  claim claims so peers see them without a separate channel. Wire
+     *  claims so peers see them without a separate channel. Wire
      *  shape mirrors `apps/sync-server/src/hub/types.ts Claim`. */
     activeClaims?: Array<{
         claimId: string;
@@ -192,7 +192,7 @@ export interface PresenceUpdateEvent {
             startColumn?: number;
             endColumn?: number;
         };
-        action: string;
+        reason: string;
         field?: string;
         meta?: Record<string, unknown>;
         declaredAt: number;
@@ -490,6 +490,15 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * so a bad notification never sinks an otherwise-successful commit.
      */
     private parseNotifications;
+    /**
+     * Single instrumentation point for claim events. Every `claim_*` frame routes
+     * through here so a developer debugging a collision gets one consistent trace
+     * — a console line AND a structured capture — without each dispatch case
+     * re-deriving the row/holder shape. The wire payload is loosely typed
+     * (`Record<string, unknown>`), so this is the one place that narrows it into
+     * a {@link ClaimEvent}.
+     */
+    private recordClaim;
     sendCommit(operations: ReadonlyArray<MutationOperation>, clientTxId: string, timeoutMs?: number, causedByTaskId?: string | null, reads?: readonly ReadDependency[] | null): Promise<CommitAck>;
     /**
      * Send a commit frame without waiting for `mutation_result`.

package/dist/sync/SyncWebSocket.js

@@ -11,7 +11,8 @@ import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
 import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
-import { subscriptionAckPayloadSchema, staleNotificationSchema, } from '../coordination/schema.js';
+import { subscriptionAckPayloadSchema, staleNotificationSchema, wireParticipantKindSchema, } from '../coordination/schema.js';
+import { formatClaim, formatConflict } from '../coordination/trace.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
@@ -338,8 +339,23 @@ export class SyncWebSocket extends EventEmitter {
                             // the advisory signal so an agent loop can self-heal, AND resolve
                             // the receipt with it (the commit still succeeded).
                             if (notifications && notifications.length > 0) {
+                                const txId = typeof clientTxId === 'string' ? clientTxId : '';
+                                const event = {
+                                    clientTxId: txId,
+                                    rows: notifications.map((n) => ({
+                                        model: n.model,
+                                        id: n.id,
+                                        fields: n.conflictingFields,
+                                        writtenBy: n.writtenBy?.kind,
+                                    })),
+                                };
+                                const message = formatConflict(event);
+                                const ctx = getContext();
+                                ctx.logger.warn(message);
+                                ctx.observability.breadcrumb(message, 'sync.coordination', 'warning');
+                                ctx.observability.captureConflict(event);
                                 this.emit('conflict:notified', {
-                                    clientTxId: typeof clientTxId === 'string' ? clientTxId : '',
+                                    clientTxId: txId,
                                     notifications,
                                 });
                             }
@@ -493,6 +509,7 @@ export class SyncWebSocket extends EventEmitter {
                         // inactive server-side by the time this arrives.
                         const p = message.payload ?? {};
                         if (typeof p.claimId === 'string') {
+                            this.recordClaim('expired', p);
                             this.emit('claim_expired', { claimId: p.claimId });
                         }
                         break;
@@ -502,33 +519,40 @@ export class SyncWebSocket extends EventEmitter {
                         // already claimed by another participant. Forward the
                         // payload as-is — the ClaimStream consumer interprets
                         // the conflict shape (peerId, target, etc.).
+                        this.recordClaim('rejected', message.payload ?? {});
                         this.emit('claim_rejected', message.payload ?? {});
                         break;
                     }
                     case 'claim_acquired': {
                         // Opt-in fair queue: the target was free, so the lease is ours
                         // immediately (no waiting). Payload carries { claimId, target }.
+                        this.recordClaim('acquired', message.payload ?? {});
                         this.emit('claim_acquired', message.payload ?? {});
                         break;
                     }
                     case 'claim_queue': {
-                        // Per-entity wait-queue snapshot for reactive `queue(id)`.
+                        // Per-entity wait-queue snapshot for reactive `queue(id)`. Not a
+                        // single claim's state change, so it isn't logged — the per-claim
+                        // `queued`/`granted` events already tell that story.
                         this.emit('claim_queue', message.payload ?? {});
                         break;
                     }
                     case 'claim_queued': {
                         // Opt-in fair queue: our claim is waiting in line. Payload
                         // carries { claimId, target, position }.
+                        this.recordClaim('queued', message.payload ?? {});
                         this.emit('claim_queued', message.payload ?? {});
                         break;
                     }
                     case 'claim_granted': {
                         // Our queued claim reached the head — the lease is now ours.
+                        this.recordClaim('granted', message.payload ?? {});
                         this.emit('claim_granted', message.payload ?? {});
                         break;
                     }
                     case 'claim_lost': {
                         // A held/granted claim was taken from us (TTL lapse, revoke).
+                        this.recordClaim('lost', message.payload ?? {});
                         this.emit('claim_lost', message.payload ?? {});
                         break;
                     }
@@ -872,6 +896,46 @@ export class SyncWebSocket extends EventEmitter {
         }
         return out.length > 0 ? out : undefined;
     }
+    /**
+     * Single instrumentation point for claim events. Every `claim_*` frame routes
+     * through here so a developer debugging a collision gets one consistent trace
+     * — a console line AND a structured capture — without each dispatch case
+     * re-deriving the row/holder shape. The wire payload is loosely typed
+     * (`Record<string, unknown>`), so this is the one place that narrows it into
+     * a {@link ClaimEvent}.
+     */
+    recordClaim(phase, payload) {
+        const str = (v) => typeof v === 'string' ? v : undefined;
+        // Targets arrive flat ({ entityType, entityId }) or nested under `target`.
+        const target = payload.target && typeof payload.target === 'object'
+            ? payload.target
+            : payload;
+        const kind = wireParticipantKindSchema.safeParse(payload.participantKind);
+        const event = {
+            phase,
+            claimId: str(payload.claimId),
+            model: str(target.entityType) ?? str(target.model),
+            id: str(target.entityId) ?? str(target.id),
+            field: str(target.field),
+            actor: str(payload.actor) ?? str(payload.heldBy),
+            participantKind: kind.success ? kind.data : undefined,
+            position: typeof payload.position === 'number' ? payload.position : undefined,
+            reason: str(payload.policyReason) ?? str(payload.reason),
+        };
+        const message = formatClaim(event);
+        // A rejection or lost lease is the collision a developer is actively
+        // debugging → warn (shows at the default log level). The routine events
+        // (acquired/queued/granted/expired) are debug-only so they never drown the
+        // console until you opt in with `new Ablo({ debug: true })`.
+        const isCollision = phase === 'rejected' || phase === 'lost';
+        const ctx = getContext();
+        if (isCollision)
+            ctx.logger.warn(message);
+        else
+            ctx.logger.debug(message);
+        ctx.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+        ctx.observability.captureClaim(event);
+    }
     sendCommit(operations, clientTxId, timeoutMs = 15_000, causedByTaskId, reads) {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('commit'));

package/dist/sync/createClaimStream.d.ts

@@ -10,7 +10,7 @@
  *
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
+ *       entityType, entityId, reason, field?, estimatedMs? } }`
  *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
  *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeClaims: Claim[]`
@@ -22,12 +22,19 @@
  * deletes.
  */
 import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { ClaimStream } from '../types/streams.js';
+import type { ClaimOptions, Claim, ClaimStream, PresenceTarget } from '../types/streams.js';
 export interface ClaimStreamConfig {
     /** Identity used to filter our own active claims out of `others`. */
     participantId: string;
 }
 export interface AttachableClaimStream extends ClaimStream {
+    /**
+     * INTERNAL lease mint — sends the `claim_begin` frame and returns a held
+     * {@link Claim} (no row `data`; the model door reads the row and stamps it).
+     * Not part of the public `ClaimStream` surface: the only public way to take a
+     * claim is `ablo.<model>.claim({ id })`, which builds on this.
+     */
+    claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
     attach(transport: SyncWebSocket): void;
     dispose(): void;
 }

package/dist/sync/createClaimStream.js

@@ -10,7 +10,7 @@
  *
  * Wire contract (apps/sync-server/src/hub/types.ts):
  *   • Outbound: `{ type: 'claim_begin', payload: { claimId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
+ *       entityType, entityId, reason, field?, estimatedMs? } }`
  *   • Outbound: `{ type: 'claim_abandon', payload: { claimId,
  *       entityType?, entityId? } }`
  *   • Inbound (via presence): `event.activeClaims: Claim[]`
@@ -104,7 +104,9 @@ export function createClaimStream(config, transport = null) {
                     continue;
                 const description = descriptionFromMeta(claim.meta);
                 activeByClaimId.set(claim.claimId, {
+                    object: 'claim',
                     id: claim.claimId,
+                    status: 'active',
                     heldBy: event.userId,
                     participantKind: participantKindFromWire(event.participantKind, event.isAgent),
                     target: {
@@ -115,10 +117,10 @@ export function createClaimStream(config, transport = null) {
                         field: claim.field,
                         meta: claim.meta,
                     },
-                    reason: claim.action,
+                    reason: claim.reason,
                     ...(description ? { description } : {}),
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
-                    announcedAt: claim.declaredAt,
+                    createdAt: claim.declaredAt,
                     expiresAt: claim.expiresAt,
                 });
                 mutated = true;
@@ -220,8 +222,7 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                // Wire field stays `action` (coordination schema); source is `reason`.
-                action: claim.reason,
+                reason: claim.reason,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -293,10 +294,11 @@ export function createClaimStream(config, transport = null) {
         };
         return {
             object: 'claim',
-            claimId,
+            id: claimId,
+            status: 'active',
             reason: args.reason,
             target: {
-                model: args.entityType,
+                type: args.entityType,
                 id: args.entityId,
                 path: args.path,
                 range: args.range,

package/dist/sync/participants.d.ts

@@ -1,12 +1,13 @@
 import type { SyncWebSocket } from './SyncWebSocket.js';
 import type { Schema, SchemaRecord } from '../schema/schema.js';
-import type { ActiveClaim, Activity, EntityRef, ClaimHandle, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { AttachableClaimStream } from './createClaimStream.js';
 /**
  * Scope accepted by participant APIs. The normal SDK shape is an
  * entity target (`{ type, id }`). Raw sync-group strings remain an
  * advanced transport escape hatch.
  */
-export type ParticipantScope = EntityRef | readonly EntityRef[] | string | readonly string[] | {
+export type ParticipantScope = ClaimTarget | readonly ClaimTarget[] | string | readonly string[] | {
     readonly syncGroup: string;
 } | {
     readonly syncGroups: readonly string[];
@@ -44,7 +45,7 @@ export interface ParticipantJoinOptions {
 }
 export interface ScopedPresence {
     readonly self: Peer;
-    readonly focus: EntityRef | null;
+    readonly focus: ClaimTarget | null;
     readonly others: ReadonlyArray<Peer>;
     update(activity: Activity): void;
     reading(detail?: string): void;
@@ -66,15 +67,15 @@ export interface ScopedClaimOptions {
     readonly ttl?: import('../types/streams.js').Duration;
 }
 export interface ScopedClaims {
-    readonly focus: EntityRef | null;
-    readonly others: ReadonlyArray<ActiveClaim>;
+    readonly focus: ClaimTarget | null;
+    readonly others: ReadonlyArray<Claim>;
     /**
      * Claim an exclusive claim on the participant's focus target (or
      * an explicit override via `opts.target`). Single verb — the old
      * `editing / writing / announce / claim(reason, opts)` overloads
      * collapsed into this one method.
      */
-    claim(opts?: ScopedClaimOptions): ClaimHandle;
+    claim(opts?: ScopedClaimOptions): Claim;
     onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
     onChange(listener: () => void): () => void;
 }
@@ -84,14 +85,14 @@ export interface ParticipantFocusOptions {
 }
 export interface JoinedParticipant {
     /** Current exact thing this participant is reading/editing. */
-    readonly target: EntityRef | null;
-    readonly focusTarget: EntityRef | null;
+    readonly target: ClaimTarget | null;
+    readonly focusTarget: ClaimTarget | null;
     /** Transport scopes this participant is joined to for visibility/fan-out. */
     readonly syncGroups: readonly string[];
     readonly presence: ScopedPresence;
     readonly claims: ScopedClaims;
     readonly peers: ReadonlyArray<Peer>;
-    readonly activeClaims: ReadonlyArray<ActiveClaim>;
+    readonly activeClaims: ReadonlyArray<Claim>;
     focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
     leave(): void;
     [Symbol.asyncDispose](): Promise<void>;
@@ -104,11 +105,11 @@ export interface ParticipantManagerConfig {
     readonly ready: () => Promise<void>;
     readonly getTransport: () => SyncWebSocket | null;
     readonly presence: PresenceStream;
-    readonly claims: ClaimStream;
+    readonly claims: AttachableClaimStream;
     readonly schema?: Schema<SchemaRecord>;
 }
 export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
 export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema<SchemaRecord>): string[];
-export declare function syncGroupFromEntityRef(ref: EntityRef, schema?: Schema<SchemaRecord>): string;
+export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema<SchemaRecord>): string;
 export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
 export declare function createParticipantClaimId(): string;

package/dist/sync/participants.js

@@ -220,20 +220,20 @@ function createJoinedParticipant(args) {
         ownHandles.add(handle);
         return {
             object: 'claim',
-            claimId: handle.claimId,
+            id: handle.id,
             reason: handle.reason,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);
-                await handle.release();
+                await handle.release?.();
             },
             revoke() {
                 ownHandles.delete(handle);
-                handle.revoke();
+                handle.revoke?.();
             },
             [Symbol.asyncDispose]: async () => {
                 ownHandles.delete(handle);
-                await handle[Symbol.asyncDispose]();
+                await handle[Symbol.asyncDispose]?.();
             },
         };
     };
@@ -262,7 +262,7 @@ function createJoinedParticipant(args) {
             return;
         left = true;
         for (const handle of Array.from(ownHandles)) {
-            handle.revoke();
+            handle.revoke?.();
             ownHandles.delete(handle);
         }
         args.presence.idle();

package/dist/transactions/TransactionQueue.d.ts

@@ -125,6 +125,7 @@ interface TransactionQueueConfig {
 }
 export declare class TransactionQueue extends EventEmitter {
     private store;
+    private lastPermanentErrorSig?;
     private _mutationExecutor;
     private get mutationExecutor();
     private executionQueue;

package/dist/transactions/TransactionQueue.js

@@ -199,6 +199,12 @@ class TransactionStore {
 }
 export class TransactionQueue extends EventEmitter {
     store = new TransactionStore();
+    // Signature of the last permanent-error we logged at `warn`. A `create`
+    // whose id already exists (`unique_violation`) is a permanent rejection
+    // that the offline queue re-drives on every reconnect/bootstrap — without
+    // this, the identical cause prints on a loop. We log the first occurrence
+    // and demote exact repeats to `debug`.
+    lastPermanentErrorSig;
     // Per-instance executor binding. Set by `setMutationExecutor(...)` from the
     // owning Ablo right after construction. Falls back to `getContext()` only
     // when unset (preserves legacy tests / SDK consumers that haven't migrated).
@@ -470,6 +476,9 @@ export class TransactionQueue extends EventEmitter {
         // promise always settles, regardless of which path produced the
         // terminal state.
         this.on('transaction:completed', (tx) => {
+            // Any successful write clears the permanent-error dedup, so a genuine
+            // recurrence after recovery warns again instead of staying demoted.
+            this.lastPermanentErrorSig = undefined;
             const r = this.confirmationResolvers.get(tx.id);
             if (r) {
                 this.confirmationResolvers.delete(tx.id);
@@ -1254,7 +1263,12 @@ export class TransactionQueue extends EventEmitter {
                             return undefined;
                         };
                         const diagnostics = readDiagnostics(error);
-                        getContext().logger.warn('[TransactionQueue] Batch commit rejected', {
+                        // Mechanic-level breadcrumb. Every batch rejection — transient
+                        // (reconnect retries it) or permanent (`handleFailure` logs the
+                        // authoritative `warn` with the same typed cause) — passes
+                        // through here. Logging it at `warn` made one rejected write
+                        // surface three identical dumps; keep it at `debug`.
+                        getContext().logger.debug('[TransactionQueue] Batch commit rejected', {
                             batchSize: batchOps.length,
                             models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
                             errorType: abloErr?.type ?? error?.name,
@@ -1768,7 +1782,7 @@ export class TransactionQueue extends EventEmitter {
             // expiry (AbloAuthenticationError).
             try {
                 const abloErr = error instanceof AbloError ? error : undefined;
-                getContext().logger.warn('[TransactionQueue] Permanent error - rolling back', {
+                const details = {
                     txId: transaction.id.slice(0, 8),
                     type: transaction.type,
                     model: transaction.modelName,
@@ -1779,7 +1793,30 @@ export class TransactionQueue extends EventEmitter {
                     requestId: abloErr?.requestId,
                     message: error?.message,
                     inputKeys: transaction.data ? Object.keys(transaction.data) : undefined,
-                });
+                };
+                // A `create` whose id already exists is the benign idempotency case:
+                // "this row is already there." It's the least alarming permanent
+                // error, so it doesn't warrant a `warn` — `info` keeps it visible
+                // without crying wolf. Everything else (FK violation, auth expiry,
+                // server 500) stays at `warn`.
+                const isBenignIdempotent = transaction.type === 'create' &&
+                    (abloErr?.code === 'unique_violation' ||
+                        abloErr?.type === 'AbloIdempotencyError');
+                // Demote exact repeats (same write rejected for the same reason on
+                // each reconnect replay) to `debug` so the loop logs once.
+                const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
+                const isRepeat = sig === this.lastPermanentErrorSig;
+                this.lastPermanentErrorSig = sig;
+                const logger = getContext().logger;
+                if (isRepeat) {
+                    logger.debug('[TransactionQueue] Permanent error - rolling back (repeat)', details);
+                }
+                else if (isBenignIdempotent) {
+                    logger.info('[TransactionQueue] Write skipped — row already exists', details);
+                }
+                else {
+                    logger.warn('[TransactionQueue] Permanent error - rolling back', details);
+                }
             }
             catch { }
             // Mark as failed immediately and rollback