@abloatai/ablo 0.18.0 → 0.19.0

package/dist/schema/ddl.js

@@ -66,6 +66,72 @@ export function sqlType(fieldType) {
     }
 }
 const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+// ── JSON column drift reconciliation ─────────────────────────────────────────
+/**
+ * Detect and repair `field.json()` columns that exist in the live database as a
+ * NON-jsonb type, and emit a salvaging in-place `ALTER … TYPE jsonb`.
+ *
+ * Why this is needed: provisioning uses `ADD COLUMN IF NOT EXISTS` and
+ * `CREATE TABLE IF NOT EXISTS` (idempotent by design). When `ablo push` adopts
+ * a table/column that PRE-EXISTS with a different type — e.g. a `content TEXT`
+ * column from a legacy table — the additive DDL is a no-op and the column
+ * silently stays `text`. The pure schema-to-schema differ
+ * ({@link generateMigrationPlan}) can't see this: the schema says `json` on
+ * both sides, so it emits no change. The drift is only visible by INTROSPECTING
+ * the live database and comparing to the declared type — the drizzle-kit
+ * `pull` discipline. A `json` value bound to a `text` column corrupts to the
+ * literal `"[object Object]"`, so leaving the drift unrepaired is silent data
+ * loss.
+ *
+ * The cast is SALVAGING, never aborting (Postgres won't auto-cast text→jsonb;
+ * invalid rows would otherwise fail the whole ALTER): a row that `IS JSON`
+ * parses to jsonb, anything else (including already-corrupted
+ * `"[object Object]"`) is wrapped as a jsonb string via `to_jsonb`, and NULL
+ * stays NULL. The `IS JSON` predicate requires Postgres 16+ (the fleet runs
+ * 17); on an older engine the ALTER fails LOUD with a structured
+ * `migration_failed` rather than silently — acceptable, since silent corruption
+ * is the thing we're eliminating. See
+ * https://echobind.com/post/safely-alter-postgres-columns-with-using.
+ *
+ * Pure + idempotent: emits a statement ONLY for a json field whose live column
+ * type is present and not already `jsonb`/`json`. A correctly-provisioned schema
+ * yields zero statements, so this is a no-op on every push after the first
+ * repair. Columns absent from `liveColumnTypes` are left to the additive
+ * provisioner (which adds them as jsonb).
+ *
+ * @param liveColumnTypes table name → (column name → information_schema
+ *   `data_type`), as introspected from the target schema.
+ */
+export function generateJsonColumnReconciliation(schema, liveColumnTypes, targetSchema) {
+    const qs = q(targetSchema);
+    const statements = [];
+    for (const [key, model] of Object.entries(schema.models)) {
+        const table = model.tableName ?? key;
+        const liveCols = liveColumnTypes.get(table);
+        if (!liveCols)
+            continue; // table not provisioned yet — nothing to reconcile
+        const qt = `${qs}.${q(table)}`;
+        for (const [fieldName, meta] of Object.entries(model.fields)) {
+            if (meta.type !== 'json')
+                continue;
+            const col = meta.column ?? camelToSnake(fieldName);
+            const liveType = liveCols.get(col);
+            if (liveType === undefined)
+                continue; // column absent — provisioner adds jsonb
+            if (liveType === 'jsonb' || liveType === 'json')
+                continue; // already correct
+            const c = q(col);
+            statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${c} TYPE jsonb USING (\n` +
+                `  CASE\n` +
+                `    WHEN ${c} IS NULL THEN NULL\n` +
+                `    WHEN ${c}::text IS JSON THEN ${c}::text::jsonb\n` +
+                `    ELSE to_jsonb(${c}::text)\n` +
+                `  END\n` +
+                `);`);
+        }
+    }
+    return statements;
+}
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 /**
  * A Postgres-identifier-safe constraint name ≤63 bytes. When the natural

package/dist/schema/index.d.ts

@@ -33,7 +33,7 @@ export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';

package/dist/schema/index.js

@@ -55,7 +55,7 @@ export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash,
 // Schema projection — derive an app's subset from one canonical schema.
 export { selectModels } from './select.js';
 // Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
-export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
+export { generateProvisionPlan, generateMigrationPlan, generateJsonColumnReconciliation, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, } from './ddl.js';
 // Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)

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