@abloatai/humans 0.59.0 → 0.59.2

package/dist/humans.d.ts

@@ -13,7 +13,7 @@ export interface HumansSurface {
     readonly [kStoreCluster]?: StoreCluster;
 }
 export declare function humans(): {
-    readonly id: "humans";
+    readonly id: 'humans';
     readonly requires: {
         readonly duplex: true;
     };

package/dist/local/BaseSyncedStore.d.ts

@@ -647,9 +647,7 @@ export declare class BaseSyncedStore<TCollaboration extends EventMap<TCollaborat
      * (no plugins installed) and the `humans()` apply handler both call it.
      */
     applyChangesToPool(changes: readonly AppliedChange[]): void;
-    /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
-    protected getStateFields(_modelName: string): string[];
-    /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+    /** Deduplicate repeated delivery of the same positive sync id. */
     protected deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
     /** Process incoming delta with smart batching */
     protected processDeltaWithBatching(delta: SyncDelta): void;

package/dist/local/BaseSyncedStore.js

@@ -1179,7 +1179,6 @@ export class BaseSyncedStore {
             acknowledge: (syncId) => { this.syncWebSocket.acknowledge(syncId); },
             get objectPool() { return store.objectPool; },
             // Dynamic-dispatch hooks — protected override points on this class.
-            getStateFields: (modelName) => this.getStateFields(modelName),
             isCustomEntity: (modelName) => this.isCustomEntity(modelName),
             createCustomEntity: (modelName, modelId, data) => this.createCustomEntity(modelName, modelId, data),
             deduplicateDeltas: (deltas) => this.deduplicateDeltas(deltas),
@@ -1202,13 +1201,9 @@ export class BaseSyncedStore {
     applyChangesToPool(changes) {
         this.syncClient.applyDeltaBatchToPool(changes, (name, data) => this.enrichRelations(name, data));
     }
-    /** Get fields that represent meaningful state for deduplication. Override for model-specific fields. */
-    getStateFields(_modelName) {
-        return ['status', 'state', 'isActive'];
-    }
-    /** Deduplicate deltas to the same entity — keep meaningful state transitions only */
+    /** Deduplicate repeated delivery of the same positive sync id. */
     deduplicateDeltas(deltas) {
-        return deltaPipeline.deduplicateDeltas(this.deltaPipelineContext, deltas);
+        return deltaPipeline.deduplicateDeltas(deltas);
     }
     /** Process incoming delta with smart batching */
     processDeltaWithBatching(delta) {

package/dist/local/Database.d.ts

@@ -101,7 +101,7 @@ export declare class Database {
      * where a missing store points to silent data loss. Callers that
      * already expect optional behavior (e.g. lazy lookups) can omit it.
      */
-    getStore(modelName: string, context?: string): import("./stores/ObjectStore.js").ObjectStore | InMemoryObjectStore | undefined;
+    getStore(modelName: string, context?: string): InMemoryObjectStore | import("./stores/ObjectStore.js").ObjectStore | undefined;
     /** Get store or throw if not found (for operations that require the store). */
     private getRequiredStore;
     /** Log preserved fields during partial UPDATE merge (debug helper) */
@@ -274,7 +274,7 @@ export declare class Database {
      * `getStore(modelName, context?)` is defined near the top of this
      * class — single accessor for both inMemory and IDB modes.
      */
-    getAllStores(): Map<string, import("./stores/ObjectStore.js").ObjectStore> | Map<string, InMemoryObjectStore>;
+    getAllStores(): Map<string, InMemoryObjectStore> | Map<string, import("./stores/ObjectStore.js").ObjectStore>;
     /**
      * Model persistence tracking
      */

package/dist/local/LazyReferenceCollection.d.ts

@@ -65,7 +65,7 @@ export declare class LazyReferenceCollection<T extends Model> {
     private get database();
     /** Get objectPool from static dependencies */
     private get objectPool();
-    constructor(modelName: string, parent: Model, foreignKey: string, customQuery?: any | undefined, options?: LazyCollectionOptions);
+    constructor(modelName: string, parent: Model, foreignKey: string, customQuery?: any, options?: LazyCollectionOptions);
     /**
      * Set up MobX observation lifecycle hooks
      * When React components observe this collection, we prevent GC of the parent model

package/dist/local/Model.js

@@ -306,7 +306,7 @@ export class Model {
      */
     capturePreviousValues(keys, opts) {
         const out = {};
-        const modified = this.modifiedProperties instanceof Map ? this.modifiedProperties : null;
+        const modified = this.modifiedProperties;
         const original = this.getOriginalSnapshot();
         for (const key of keys) {
             if (key === 'id')
@@ -334,7 +334,7 @@ export class Model {
      * is never consumed. With no `keys`, consumes every tracked field.
      */
     consumeModifiedFields(keys) {
-        if (!(this.modifiedProperties instanceof Map) || this.modifiedProperties.size === 0) {
+        if (this.modifiedProperties.size === 0) {
             return;
         }
         const only = keys ? new Set(keys) : null;

package/dist/local/SyncClient.d.ts

@@ -409,14 +409,14 @@ export declare class SyncClient extends EventEmitter {
      * Get detailed debug info for the sync debug page
      */
     getDebugInfo(): {
-        connectionState: "connected" | "disconnected" | "connecting";
+        connectionState: "connected" | "connecting" | "disconnected";
         pendingMutationsCount: number;
         mutationQueue: {
             lastSeenSyncId: number;
             awaitingDeltaCount: number;
             awaitingDeltaTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "archive" | "create" | "delete" | "unarchive" | "update";
                 modelName: string;
                 modelId: string;
                 syncIdNeeded: number | undefined;
@@ -425,13 +425,13 @@ export declare class SyncClient extends EventEmitter {
             }[];
             pendingTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "archive" | "create" | "delete" | "unarchive" | "update";
                 modelName: string;
                 modelId: string;
             }[];
             executingTransactions: {
                 id: string;
-                type: "update" | "create" | "delete" | "archive" | "unarchive";
+                type: "archive" | "create" | "delete" | "unarchive" | "update";
                 modelName: string;
                 modelId: string;
             }[];

package/dist/local/SyncClient.js

@@ -10,7 +10,7 @@
 import { runInAction } from 'mobx';
 import { InstanceCache, ModelScope } from './InstanceCache.js';
 import { Model } from './Model.js';
-import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
+import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 // ModelRegistry instance accessed via this.objectPool.registry
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.js';
@@ -1588,6 +1588,25 @@ export class SyncClient extends EventEmitter {
             // otherwise re-add it for the brief window before the matching delete
             // confirmation lands.
             if (this.echoTracker.consumeEcho(transactionId)) {
+                // A direct assignment can re-enter change tracking while this
+                // optimistic write is in flight. Leaving the acknowledged field dirty
+                // makes conflict resolution preserve it over the next collaborator
+                // delta, so peers appear desynchronized until refresh.
+                //
+                // Re-baseline only values this echo actually confirms. If the user has
+                // edited the same field again since the write was sent, its current
+                // dirty value differs from the echo and remains queued.
+                if (resident && result.data) {
+                    const acknowledgedFields = [];
+                    for (const [field, change] of resident.modifiedProperties) {
+                        if (Object.prototype.hasOwnProperty.call(result.data, field) &&
+                            deepEqual(change.new, result.data[field])) {
+                            acknowledgedFields.push(field);
+                        }
+                    }
+                    resident.consumeModifiedFields(acknowledgedFields);
+                    resident.markAsSynced();
+                }
                 continue;
             }
             // If a later op in this batch will remove this id, skip earlier

package/dist/local/interfaces/index.d.ts

@@ -141,7 +141,7 @@ import type { MutationOptions } from '@abloatai/transaction/client/resources/mut
  * `claim` are deliberately absent: both are resolved on the client before a write
  * is staged, so neither reaches this layer.
  */
-export type WriteOptions = Pick<MutationOptions, 'readAt' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
+export type WriteOptions = Pick<MutationOptions, 'readAt' | 'reads' | 'idempotencyKey' | 'label' | 'fenceToken' | 'claimRef'>;
 /** A single mutation within a batch. Its `options` travel with it so the server
  *  can cache and replay the operation for idempotent retries. */
 export interface MutationOperation {

package/dist/local/stores/syncAction.d.ts

@@ -11,13 +11,13 @@ export declare const syncActionSchema: z.ZodObject<{
     modelId: z.ZodString;
     action: z.ZodEnum<{
         A: "A";
-        I: "I";
-        U: "U";
-        D: "D";
-        V: "V";
         C: "C";
+        D: "D";
         G: "G";
+        I: "I";
         S: "S";
+        U: "U";
+        V: "V";
     }>;
     data: z.ZodUnknown;
     __class: z.ZodDefault<z.ZodLiteral<"SyncAction">>;

package/dist/local/sync/deltaPipeline.d.ts

@@ -73,7 +73,6 @@ export interface DeltaPipelineContext {
          *  {@link handleGroupHandlerFailure}). */
         clear(): void;
     };
-    getStateFields(modelName: string): string[];
     isCustomEntity(modelName: string): boolean;
     createCustomEntity(modelName: string, modelId: string, data: Record<string, unknown>): Model | null;
     deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
@@ -94,8 +93,17 @@ export interface DeltaPipelineContext {
  * It never throws, because it runs inside the pipeline's fire-and-forget path.
  */
 export declare function handleGroupHandlerFailure(ctx: DeltaPipelineContext, delta: SyncDelta, error: unknown): void;
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export declare function deduplicateDeltas(ctx: DeltaPipelineContext, deltas: SyncDelta[]): SyncDelta[];
+/**
+ * Deduplicate repeated delivery of the same log entry.
+ *
+ * A row may legitimately change several times in one receive frame. Those
+ * changes are ordered facts, even when a small subset of fields (such as
+ * `status`) happens to remain equal. Collapsing by entity or a partial state
+ * signature can therefore discard the newest row image while the cursor still
+ * advances past it. Only an identical positive sync id proves duplicate
+ * delivery; non-positive ids carry no usable log identity and stay untouched.
+ */
+export declare function deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
 /**
  * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when
  * the delta was pushed onto `pendingDeltas` — a regular batchable insert,

package/dist/local/sync/deltaPipeline.js

@@ -52,90 +52,37 @@ export function handleGroupHandlerFailure(ctx, delta, error) {
         // Best-effort: the reconnect/bootstrap cycle self-heals on next connect.
     }
 }
-/** Builds a small signature of a delta's state fields, used to detect no-op duplicate deltas. */
-function extractStateSignature(ctx, delta) {
-    if (!delta.data || typeof delta.data !== 'object')
-        return null;
-    const data = typeof delta.data === 'string'
-        ? JSON.parse(delta.data)
-        : (delta.data);
-    // Generic state fields — subclasses can override getStateFields() for model-specific fields
-    const fieldsToCheck = ctx.getStateFields(delta.modelName);
-    const signature = {
-        actionType: delta.actionType,
-        modelName: delta.modelName,
-    };
-    for (const field of fieldsToCheck) {
-        if (field in data)
-            signature[field] = data[field];
-    }
-    return signature;
-}
-function isSameState(a, b) {
-    if (!a || !b)
-        return false;
-    const keys = Object.keys(a);
-    if (keys.length !== Object.keys(b).length)
-        return false;
-    return keys.every((k) => a[k] === b[k]);
-}
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export function deduplicateDeltas(ctx, deltas) {
-    // The dominant live-publication shape is a frame of independent entity
-    // creates. When every entity key occurs once, reconciliation cannot remove
-    // or reorder anything: preserve the already commit-ordered input directly
-    // and avoid allocating a bucket array, state signature, and two sorts per
-    // delta. The first duplicate falls through to the full transition logic.
-    const uniqueEntities = new Set();
-    let hasDuplicateEntity = false;
-    for (const delta of deltas) {
-        const key = `${delta.modelName}:${delta.modelId}`;
-        if (uniqueEntities.has(key)) {
-            hasDuplicateEntity = true;
+/**
+ * Deduplicate repeated delivery of the same log entry.
+ *
+ * A row may legitimately change several times in one receive frame. Those
+ * changes are ordered facts, even when a small subset of fields (such as
+ * `status`) happens to remain equal. Collapsing by entity or a partial state
+ * signature can therefore discard the newest row image while the cursor still
+ * advances past it. Only an identical positive sync id proves duplicate
+ * delivery; non-positive ids carry no usable log identity and stay untouched.
+ */
+export function deduplicateDeltas(deltas) {
+    if (deltas.length < 2 || deltas.some((delta) => delta.id <= 0))
+        return deltas;
+    let strictlyOrdered = true;
+    for (let index = 1; index < deltas.length; index += 1) {
+        if (deltas[index - 1].id >= deltas[index].id) {
+            strictlyOrdered = false;
             break;
         }
-        uniqueEntities.add(key);
     }
-    if (!hasDuplicateEntity)
+    if (strictlyOrdered)
         return deltas;
-    const byEntity = new Map();
-    for (const d of deltas) {
-        const key = `${d.modelName}:${d.modelId}`;
-        if (!byEntity.has(key))
-            byEntity.set(key, []);
-        byEntity.get(key).push(d);
-    }
-    const result = [];
-    for (const entityDeltas of byEntity.values()) {
-        const sorted = entityDeltas.sort((a, b) => a.id - b.id);
-        // DELETE wins — it's the final state
-        const del = sorted.find((d) => d.actionType === 'D');
-        if (del) {
-            result.push(del);
-            continue;
-        }
-        // Keep deltas that represent different states
-        const unique = [];
-        let prev = null;
-        for (const d of sorted) {
-            const sig = extractStateSignature(ctx, d);
-            if (!isSameState(prev, sig)) {
-                unique.push(d);
-                prev = sig;
-            }
-        }
-        if (unique.length > 0) {
-            result.push(...unique);
-        }
-        else {
-            // `sorted` is never empty (every byEntity bucket gets at least one
-            // delta pushed) — the guard only narrows the indexed access.
-            const last = sorted.at(-1);
-            if (last)
-                result.push(last);
-        }
-    }
-    return result.sort((a, b) => a.id - b.id);
+    const seen = new Set();
+    return [...deltas]
+        .sort((a, b) => a.id - b.id)
+        .filter((delta) => {
+        if (seen.has(delta.id))
+            return false;
+        seen.add(delta.id);
+        return true;
+    });
 }
 /**
  * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when

package/dist/local/sync/schemas.d.ts

@@ -18,19 +18,19 @@ import type { RuntimeContext } from "../RuntimeContext.js";
  */
 export declare const ServerDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
-    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
     actionType: z.ZodEnum<{
         A: "A";
-        I: "I";
-        U: "U";
-        D: "D";
-        V: "V";
         C: "C";
+        D: "D";
         G: "G";
+        I: "I";
         S: "S";
+        U: "U";
+        V: "V";
     }>;
     modelName: z.ZodString;
     modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
 }, z.core.$loose>;
 export type ValidatedServerDelta = z.infer<typeof ServerDeltaSchema>;
 export declare const BootstrapResponseSchema: z.ZodObject<{
@@ -42,19 +42,19 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
     models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodString, z.ZodNull]>, z.ZodTransform<unknown[], string | unknown[] | null>>>>;
     deltas: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
-        data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
         actionType: z.ZodEnum<{
             A: "A";
-            I: "I";
-            U: "U";
-            D: "D";
-            V: "V";
             C: "C";
+            D: "D";
             G: "G";
+            I: "I";
             S: "S";
+            U: "U";
+            V: "V";
         }>;
         modelName: z.ZodString;
         modelId: z.ZodString;
+        data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
     }, z.core.$loose>>>;
     deltaCount: z.ZodOptional<z.ZodNumber>;
     failedModels: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/local/transactions/mutations/MutationQueue.d.ts

@@ -477,7 +477,7 @@ export declare class MutationQueue extends EventEmitter {
         awaitingDeltaCount: number;
         awaitingDeltaTransactions: {
             id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
+            type: "archive" | "create" | "delete" | "unarchive" | "update";
             modelName: string;
             modelId: string;
             syncIdNeeded: number | undefined;
@@ -486,13 +486,13 @@ export declare class MutationQueue extends EventEmitter {
         }[];
         pendingTransactions: {
             id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
+            type: "archive" | "create" | "delete" | "unarchive" | "update";
             modelName: string;
             modelId: string;
         }[];
         executingTransactions: {
             id: string;
-            type: "update" | "create" | "delete" | "archive" | "unarchive";
+            type: "archive" | "create" | "delete" | "unarchive" | "update";
             modelName: string;
             modelId: string;
         }[];

package/dist/local/transactions/mutations/batchProcessing.js

@@ -1,5 +1,5 @@
 import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
-import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+import { applyWriteOptions, collectQueuedReads, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
 export async function processBatch(ctx) {
     if (ctx.durableReplayBlock)
         return;
@@ -69,6 +69,7 @@ export async function processBatch(ctx) {
                         origin: 'model_batch',
                         operations: batchOps.map(({ op }) => op),
                         sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                        commitOptions: { reads: collectQueuedReads(batch) },
                         createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
                         sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
                         sequence: batch[0]?.commitEnvelope?.sequence,
@@ -84,6 +85,9 @@ export async function processBatch(ctx) {
                     dispatchStarted = true;
                     const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(operations, {
                         idempotencyKey: commitIdempotencyKey,
+                        ...(durableEnvelope.commitOptions.reads !== undefined
+                            ? { reads: durableEnvelope.commitOptions.reads }
+                            : {}),
                     }));
                     await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
                     const lastSyncId = result.lastSyncId;

package/dist/local/transactions/mutations/commitPayload.d.ts

@@ -105,6 +105,8 @@ export interface QueuedMutation {
      */
     confirmation?: Promise<void>;
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export declare function collectQueuedReads(transactions: readonly QueuedMutation[]): MutationOptions['reads'] | undefined;
 export declare const normalizeModelKey: (modelName: string) => string;
 export declare const stripModelSuffix: (modelName: string) => string;
 /**
@@ -120,7 +122,7 @@ export declare const stripModelSuffix: (modelName: string) => string;
  * foreign-key ordering because the row already exists, so they all share the
  * configured default non-create priority.
  */
-export declare const computePriorityScore: (type: QueuedMutation["type"], modelName: string, runtime?: RuntimeContext) => number;
+export declare const computePriorityScore: (type: QueuedMutation['type'], modelName: string, runtime?: RuntimeContext) => number;
 export declare const TX_TYPE_TO_MUTATION_OP: Record<QueuedMutation['type'], MutationOperationType>;
 export declare function hasStaleWriteOptions(options?: WriteOptions): boolean;
 /** Options whose identity/audit semantics forbid merging two caller writes. */

package/dist/local/transactions/mutations/commitPayload.js

@@ -75,6 +75,20 @@ export function projectCommitPayload(modelName, source, opts, runtime = globalRu
     }
     return snapshotJsonValue(out, '$.input');
 }
+/** Merge per-write premises into the one batch-level read set sent on wire. */
+export function collectQueuedReads(transactions) {
+    const declared = transactions
+        .map((transaction) => transaction.writeOptions?.reads)
+        .filter((reads) => reads !== undefined);
+    if (declared.length === 0)
+        return undefined;
+    const unique = new Map();
+    for (const dependency of declared.flatMap((reads) => reads ?? [])) {
+        unique.set(JSON.stringify(dependency), dependency);
+    }
+    const reads = [...unique.values()];
+    return reads.length > 0 ? reads : null;
+}
 export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
 export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
 /**

package/dist/local/transactions/mutations/failureHandling.js

@@ -1,5 +1,5 @@
-import { AbloError } from '@abloatai/transaction/errors';
 import { extractStatusCode } from './commitPayload.js';
+import { reportPermanentMutationFailure } from './failureReporting.js';
 export function transientRetryDelayMs(error, attempt, retryBackoff) {
     const { baseMs, capMs } = retryBackoff;
     let base = baseMs;
@@ -16,85 +16,12 @@ export async function handleFailure(ctx, transaction, error) {
     transaction.attempts++;
     // Check whether this is a permanent error that should not be retried.
     if (ctx.isPermanentError(error)) {
-        // Logged at warn: a permanent error means the server rejected the write,
-        // so the developer should see the reason in the console. The typed
-        // AbloError fields (`type`, `code`, `httpStatus`) are included so the
-        // cause is visible — for example a foreign-key violation
-        // (AbloValidationError) versus expired authentication
-        // (AbloAuthenticationError).
-        try {
-            const abloErr = error instanceof AbloError ? error : undefined;
-            const details = {
-                txId: transaction.id.slice(0, 8),
-                type: transaction.type,
-                model: transaction.modelName,
-                modelId: transaction.modelId.slice(0, 12),
-                errorType: abloErr?.type ?? error?.name,
-                errorCode: abloErr?.code,
-                httpStatus: abloErr?.httpStatus,
-                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 === ctx.getLastPermanentErrorSignature();
-            ctx.setLastPermanentErrorSignature(sig);
-            const logger = ctx.runtime.logger;
-            // Two registers from one call site, split by log level (the default
-            // logger is gated at `warn`, so `debug` stays hidden unless
-            // ABLO_LOG_LEVEL=debug is set to inspect the engine):
-            //   - the default-visible line speaks the application developer's
-            //     language: their verb (such as `update`), their model, the typed
-            //     error's own message, and the wire `code` for searching. It uses
-            //     no engine jargon and prints no JSON dump, which would alarm
-            //     without helping.
-            //   - the forensic `details` ride a companion `debug` line for anyone
-            //     debugging the engine internals.
-            const revertNote = ctx.config.enableOptimistic
-                ? ' The local change was reverted.'
-                : '';
-            const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
-            const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
-            const requestRef = abloErr?.requestId
-                ? ` [request_id: ${abloErr.requestId}]`
-                : '';
-            // An optimistic write resolves before the server answers, so a later
-            // rejection has no caller left to return to and this log is the only
-            // place it appears. That reads to an application developer as their own
-            // save silently failing — the write showed, then vanished — and sends
-            // them into their editor instead of here. Name the subscription that
-            // hands them the same typed error, so the application can say what
-            // happened rather than only the console.
-            const channelNote = ctx.config.enableOptimistic
-                ? ' To surface this in your app, subscribe with `ablo.onMutationFailure(…)`.'
-                : '';
-            const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}${requestRef}.${revertNote}${channelNote}`;
-            if (isRepeat) {
-                // 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) {
-                // 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(headline);
-                logger.debug('write rejection — details', details);
-            }
-        }
-        catch { }
+        reportPermanentMutationFailure({
+            runtime: ctx.runtime,
+            enableOptimistic: ctx.config.enableOptimistic,
+            getLastPermanentErrorSignature: ctx.getLastPermanentErrorSignature,
+            setLastPermanentErrorSignature: ctx.setLastPermanentErrorSignature,
+        }, transaction, error);
         // Mark as failed immediately and rollback
         ctx.store.updateStatus(transaction.id, 'failed');
         if (ctx.config.enableOptimistic) {
@@ -108,7 +35,8 @@ export async function handleFailure(ctx, transaction, error) {
         return;
     }
     transaction.firstTransientFailureAt ??= Date.now();
-    const insideAvailabilityWindow = Date.now() - transaction.firstTransientFailureAt < ctx.config.availabilityRetryWindowMs;
+    const insideAvailabilityWindow = Date.now() - transaction.firstTransientFailureAt <
+        ctx.config.availabilityRetryWindowMs;
     if (transaction.attempts < ctx.config.maxRetries || insideAvailabilityWindow) {
         // Exponential backoff with full jitter on every transient retry:
         // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses

package/dist/local/transactions/mutations/failureReporting.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { QueuedMutation } from './commitPayload.js';
+export interface PermanentFailureReportingContext {
+    readonly runtime: RuntimeContext;
+    readonly enableOptimistic: boolean;
+    readonly getLastPermanentErrorSignature: () => string | undefined;
+    readonly setLastPermanentErrorSignature: (signature: string) => void;
+}
+/** Report a terminal rejection at a severity that matches its meaning. */
+export declare function reportPermanentMutationFailure(ctx: PermanentFailureReportingContext, transaction: QueuedMutation, error: Error): void;