@abloatai/ablo 0.26.0 → 0.27.0

package/dist/transactions/TransactionStore.d.ts

@@ -1,8 +1,10 @@
 /**
- * In-memory transaction index — id map plus a by-status secondary index so
- * the queue's hot paths (`getByStatus('pending')` on every batch/coalesce
- * decision) stay O(status bucket) instead of O(all transactions). Lifted out
- * of `TransactionQueue.ts` as a stateful leaf with no queue coupling.
+ * An in-memory index of transactions by id, with a secondary index by status.
+ * The status index keeps the queue's hot paths — such as `getByStatus('pending')`
+ * on every batch and coalesce decision — proportional to the number of
+ * transactions in that status rather than the total across all statuses.
+ * {@link TransactionQueue} owns an instance and routes every status change
+ * through {@link updateStatus}, which keeps the two indexes consistent.
  */
 import type { Transaction } from './commitPayload.js';
 export declare class TransactionStore {

package/dist/transactions/TransactionStore.js

@@ -1,8 +1,10 @@
 /**
- * In-memory transaction index — id map plus a by-status secondary index so
- * the queue's hot paths (`getByStatus('pending')` on every batch/coalesce
- * decision) stay O(status bucket) instead of O(all transactions). Lifted out
- * of `TransactionQueue.ts` as a stateful leaf with no queue coupling.
+ * An in-memory index of transactions by id, with a secondary index by status.
+ * The status index keeps the queue's hot paths — such as `getByStatus('pending')`
+ * on every batch and coalesce decision — proportional to the number of
+ * transactions in that status rather than the total across all statuses.
+ * {@link TransactionQueue} owns an instance and routes every status change
+ * through {@link updateStatus}, which keeps the two indexes consistent.
  */
 export class TransactionStore {
     transactions = new Map();

package/dist/transactions/UnconfirmedWrites.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Tracks the transactions this client has applied locally but the server has
+ * not yet confirmed, so their echoes can be recognized when they return over
+ * the sync stream. When a change is made optimistically, the client updates
+ * its own state at once; the server later broadcasts the same change as a sync
+ * delta stamped with the originating `transactionId`. This tracker lets the
+ * receive path recognize that delta as its own echo and skip re-applying it,
+ * since the optimistic write already reflects it. Without this discriminator
+ * the apply path would re-apply the confirmation on top of state that may have
+ * changed since, producing a visible flicker.
+ *
+ * An entry is added with {@link markPending} and drained either by
+ * {@link consumeEcho} when the matching delta arrives, or by
+ * {@link drainOnRollback} when the originating transaction is cancelled.
+ *
+ * The set is bounded by `maxSize` to guard against unbounded growth if
+ * transactions are somehow never confirmed and never rolled back. When the
+ * bound is reached the oldest id is evicted first, since the backing Map
+ * iterates in insertion order. Eviction carries no correctness risk for the
+ * client that made the write, whose local state already reflects the change;
+ * the only cost is that a later echo of the evicted transaction is applied as
+ * if it were a foreign change, at worst a single redundant re-set.
+ */
+export interface UnconfirmedWritesOptions {
+    /**
+     * The maximum number of unconfirmed transaction ids to track. Once this many
+     * are held, adding another evicts the oldest. Defaults to 10,000, which
+     * leaves ample headroom even for a client with many tabs open during a large
+     * bulk edit.
+     */
+    maxSize?: number;
+}
+export interface UnconfirmedWritesMetrics {
+    /** Total ids currently tracked. */
+    size: number;
+    /** Cumulative ids ever added since construction. */
+    totalAdded: number;
+    /** Cumulative successful echo matches (delta arrived → drained). */
+    hits: number;
+    /** Cumulative explicit rollback drains (transaction never made it). */
+    rollbacks: number;
+    /** Cumulative ids evicted due to maxSize pressure. */
+    evictions: number;
+}
+export declare class UnconfirmedWrites {
+    private readonly ids;
+    private readonly maxSize;
+    private _totalAdded;
+    private _hits;
+    private _rollbacks;
+    private _evictions;
+    constructor(options?: UnconfirmedWritesOptions);
+    /**
+     * Mark a transaction as locally-applied. The next sync delta with a
+     * matching `transactionId` will be recognized as the server's
+     * confirmation of this same write. Idempotent — repeated calls with
+     * the same id are no-ops.
+     */
+    markPending(transactionId: string): void;
+    /**
+     * Reports whether an incoming delta is this client's own echo, draining the
+     * entry if so. Returns true when the id was being tracked, signalling the
+     * caller to skip re-applying the change because the optimistic write already
+     * reflects it; returns false for a change that originated elsewhere, which
+     * should be applied normally.
+     *
+     * The check and drain are combined into one call so the receive path cannot
+     * accidentally treat two deltas carrying the same id, arriving in one batch,
+     * as separate echoes.
+     */
+    consumeEcho(transactionId: string | null | undefined): boolean;
+    /**
+     * Drains the entry for a transaction that was rolled back before the server
+     * confirmed it. No echo will ever arrive for a cancelled transaction, so
+     * without this the pending entry would leak. Rollbacks are counted separately
+     * from confirmed echoes, so a rise in rollbacks relative to hits can flag
+     * network or server trouble.
+     */
+    drainOnRollback(transactionId: string): void;
+    getMetrics(): Readonly<UnconfirmedWritesMetrics>;
+    clear(): void;
+}

package/dist/transactions/UnconfirmedWrites.js

@@ -0,0 +1,104 @@
+/**
+ * Tracks the transactions this client has applied locally but the server has
+ * not yet confirmed, so their echoes can be recognized when they return over
+ * the sync stream. When a change is made optimistically, the client updates
+ * its own state at once; the server later broadcasts the same change as a sync
+ * delta stamped with the originating `transactionId`. This tracker lets the
+ * receive path recognize that delta as its own echo and skip re-applying it,
+ * since the optimistic write already reflects it. Without this discriminator
+ * the apply path would re-apply the confirmation on top of state that may have
+ * changed since, producing a visible flicker.
+ *
+ * An entry is added with {@link markPending} and drained either by
+ * {@link consumeEcho} when the matching delta arrives, or by
+ * {@link drainOnRollback} when the originating transaction is cancelled.
+ *
+ * The set is bounded by `maxSize` to guard against unbounded growth if
+ * transactions are somehow never confirmed and never rolled back. When the
+ * bound is reached the oldest id is evicted first, since the backing Map
+ * iterates in insertion order. Eviction carries no correctness risk for the
+ * client that made the write, whose local state already reflects the change;
+ * the only cost is that a later echo of the evicted transaction is applied as
+ * if it were a foreign change, at worst a single redundant re-set.
+ */
+const DEFAULT_MAX_SIZE = 10_000;
+export class UnconfirmedWrites {
+    // Map (not Set) for O(1) FIFO eviction via insertion order.
+    // Value is unused; Map.keys() iterates in insertion order so
+    // `keys().next()` yields the oldest id.
+    ids = new Map();
+    maxSize;
+    // Metrics — internal counters; exposed via `getMetrics()`. Kept
+    // numeric (not BigInt) since cumulative-since-page-load fits well
+    // under Number.MAX_SAFE_INTEGER for any realistic session.
+    _totalAdded = 0;
+    _hits = 0;
+    _rollbacks = 0;
+    _evictions = 0;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+    }
+    /**
+     * Mark a transaction as locally-applied. The next sync delta with a
+     * matching `transactionId` will be recognized as the server's
+     * confirmation of this same write. Idempotent — repeated calls with
+     * the same id are no-ops.
+     */
+    markPending(transactionId) {
+        if (this.ids.has(transactionId))
+            return;
+        if (this.ids.size >= this.maxSize) {
+            const oldest = this.ids.keys().next().value;
+            if (oldest !== undefined) {
+                this.ids.delete(oldest);
+                this._evictions += 1;
+            }
+        }
+        this.ids.set(transactionId, true);
+        this._totalAdded += 1;
+    }
+    /**
+     * Reports whether an incoming delta is this client's own echo, draining the
+     * entry if so. Returns true when the id was being tracked, signalling the
+     * caller to skip re-applying the change because the optimistic write already
+     * reflects it; returns false for a change that originated elsewhere, which
+     * should be applied normally.
+     *
+     * The check and drain are combined into one call so the receive path cannot
+     * accidentally treat two deltas carrying the same id, arriving in one batch,
+     * as separate echoes.
+     */
+    consumeEcho(transactionId) {
+        if (!transactionId)
+            return false;
+        if (!this.ids.has(transactionId))
+            return false;
+        this.ids.delete(transactionId);
+        this._hits += 1;
+        return true;
+    }
+    /**
+     * Drains the entry for a transaction that was rolled back before the server
+     * confirmed it. No echo will ever arrive for a cancelled transaction, so
+     * without this the pending entry would leak. Rollbacks are counted separately
+     * from confirmed echoes, so a rise in rollbacks relative to hits can flag
+     * network or server trouble.
+     */
+    drainOnRollback(transactionId) {
+        if (this.ids.delete(transactionId)) {
+            this._rollbacks += 1;
+        }
+    }
+    getMetrics() {
+        return {
+            size: this.ids.size,
+            totalAdded: this._totalAdded,
+            hits: this._hits,
+            rollbacks: this._rollbacks,
+            evictions: this._evictions,
+        };
+    }
+    clear() {
+        this.ids.clear();
+    }
+}

package/dist/transactions/coalesceRules.d.ts

@@ -1,34 +1,58 @@
 /**
- * Coalescing rules — the queue's same-entity causality guards, lifted out of
- * `TransactionQueue.ts` as a leaf over a minimal store-shaped interface:
+ * The queue's rules for coalescing operations that touch the same row, so their
+ * causal order is preserved. {@link TransactionQueue} calls into these through a
+ * small store-shaped interface:
  *
- *   • create-then-delete cancellation (`takeUnsentCreateForModel`): a delete
- *     of a row whose create never left the client cancels both locally;
- *   • the create barrier (`findCreateBarrierForDelete`) + deferred-delete
- *     parking (`deferDeleteUntilCreateSettles` / `release…`): once a create
- *     HAS been sent, a delete must wait for it to settle or the server could
- *     see DELETE-before-CREATE;
- *   • update-payload merging (`mergeUpdateData`): collapses rapid same-entity
- *     updates into one wire op.
+ *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
+ *     deleting a row whose create never left the client cancels both locally.
+ *   - The create barrier ({@link findCreateBarrierForDelete}) and deferred-delete
+ *     parking ({@link deferDeleteUntilCreateSettles} /
+ *     {@link releaseDeferredDeletesForCreate}): once a create has been sent, a
+ *     delete must wait for it to settle, or the server could receive the delete
+ *     before the create.
+ *   - Update-payload merging ({@link mergeUpdateData}): collapses rapid updates
+ *     to the same row into one wire operation.
  *
- * The queue's `enqueue`/`delete` verbs stay in the host (they orchestrate
- * optimistic state + events); the RULES live here.
+ * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
+ * state and events; these functions hold only the coalescing rules.
  */
 import type { MutationInput, Transaction } from './commitPayload.js';
-/** The slice of `TransactionStore` the coalescing rules read. */
+/** The subset of {@link TransactionStore} that the coalescing rules read. */
 export interface TransactionStoreLike {
     get(id: string): Transaction | undefined;
     getByStatus(status: Transaction['status']): Transaction[];
 }
 export declare const entityKey: (modelName: string, modelId: string) => string;
 /**
- * Find-and-remove a create for (model, id) that has never been sent —
- * checking the microtask staging area, the execution queue, and the store's
- * pending bucket, in that order. Splices the winner out of whichever queue
- * held it so the caller can cancel it instead of shipping create+delete.
+ * Finds and removes a create for the given model and id that has never been
+ * sent, searching the staging area, the execution queue, and the store's
+ * pending bucket in that order. It splices the match out of whichever queue
+ * held it, so the caller can cancel it rather than send a create followed by a
+ * delete.
  */
 export declare function takeUnsentCreateForModel(staged: Transaction[], queued: Transaction[], store: Pick<TransactionStoreLike, 'getByStatus'>, modelName: string, modelId: string): Transaction | undefined;
+/**
+ * Returns the most recent in-flight create for the given model and id that a
+ * delete must wait behind, or undefined if there is none. A pending create that
+ * has never been attempted is not a barrier, because it can be cancelled
+ * instead; once a create has been sent, even a retry-pending one is a barrier.
+ */
 export declare function findCreateBarrierForDelete(store: Pick<TransactionStoreLike, 'getByStatus'>, modelName: string, modelId: string): Transaction | undefined;
+/**
+ * Parks a delete until the create for the same row settles, keyed by the
+ * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
+ * the parked deletes once that create completes.
+ */
 export declare function deferDeleteUntilCreateSettles(deferredDeletesByCreate: Map<string, Transaction[]>, createTransaction: Transaction, deleteTransaction: Transaction): void;
+/**
+ * Re-enqueues the deletes parked behind a create once that create settles,
+ * skipping any whose status is no longer pending.
+ */
 export declare function releaseDeferredDeletesForCreate(deferredDeletesByCreate: Map<string, Transaction[]>, store: Pick<TransactionStoreLike, 'get'>, enqueue: (transaction: Transaction) => void, createTransaction: Transaction): void;
+/**
+ * Merges two update payloads for the same row into one. Later values win, with
+ * one exception: a `metadata` field is deep-merged as an object — parsing it
+ * first when it arrives as a JSON string — rather than replaced, so partial
+ * metadata updates accumulate instead of overwriting each other.
+ */
 export declare function mergeUpdateData(left: MutationInput | undefined, right: MutationInput | undefined, _modelName?: string): MutationInput;

package/dist/transactions/coalesceRules.js

@@ -1,26 +1,29 @@
 /**
- * Coalescing rules — the queue's same-entity causality guards, lifted out of
- * `TransactionQueue.ts` as a leaf over a minimal store-shaped interface:
+ * The queue's rules for coalescing operations that touch the same row, so their
+ * causal order is preserved. {@link TransactionQueue} calls into these through a
+ * small store-shaped interface:
  *
- *   • create-then-delete cancellation (`takeUnsentCreateForModel`): a delete
- *     of a row whose create never left the client cancels both locally;
- *   • the create barrier (`findCreateBarrierForDelete`) + deferred-delete
- *     parking (`deferDeleteUntilCreateSettles` / `release…`): once a create
- *     HAS been sent, a delete must wait for it to settle or the server could
- *     see DELETE-before-CREATE;
- *   • update-payload merging (`mergeUpdateData`): collapses rapid same-entity
- *     updates into one wire op.
+ *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
+ *     deleting a row whose create never left the client cancels both locally.
+ *   - The create barrier ({@link findCreateBarrierForDelete}) and deferred-delete
+ *     parking ({@link deferDeleteUntilCreateSettles} /
+ *     {@link releaseDeferredDeletesForCreate}): once a create has been sent, a
+ *     delete must wait for it to settle, or the server could receive the delete
+ *     before the create.
+ *   - Update-payload merging ({@link mergeUpdateData}): collapses rapid updates
+ *     to the same row into one wire operation.
  *
- * The queue's `enqueue`/`delete` verbs stay in the host (they orchestrate
- * optimistic state + events); the RULES live here.
+ * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
+ * state and events; these functions hold only the coalescing rules.
  */
 export const entityKey = (modelName, modelId) => `${modelName}:${modelId}`;
 const isTransactionForModel = (transaction, modelName, modelId) => transaction.modelName === modelName && transaction.modelId === modelId;
 /**
- * Find-and-remove a create for (model, id) that has never been sent —
- * checking the microtask staging area, the execution queue, and the store's
- * pending bucket, in that order. Splices the winner out of whichever queue
- * held it so the caller can cancel it instead of shipping create+delete.
+ * Finds and removes a create for the given model and id that has never been
+ * sent, searching the staging area, the execution queue, and the store's
+ * pending bucket in that order. It splices the match out of whichever queue
+ * held it, so the caller can cancel it rather than send a create followed by a
+ * delete.
  */
 export function takeUnsentCreateForModel(staged, queued, store, modelName, modelId) {
     const isUnsentCreate = (tx) => tx.type === 'create' &&
@@ -37,6 +40,12 @@ export function takeUnsentCreateForModel(staged, queued, store, modelName, model
     }
     return store.getByStatus('pending').find(isUnsentCreate);
 }
+/**
+ * Returns the most recent in-flight create for the given model and id that a
+ * delete must wait behind, or undefined if there is none. A pending create that
+ * has never been attempted is not a barrier, because it can be cancelled
+ * instead; once a create has been sent, even a retry-pending one is a barrier.
+ */
 export function findCreateBarrierForDelete(store, modelName, modelId) {
     const liveCreates = [
         ...store.getByStatus('pending'),
@@ -50,12 +59,21 @@ export function findCreateBarrierForDelete(store, modelName, modelId) {
         (tx.status !== 'pending' || tx.attempts > 0));
     return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
 }
+/**
+ * Parks a delete until the create for the same row settles, keyed by the
+ * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
+ * the parked deletes once that create completes.
+ */
 export function deferDeleteUntilCreateSettles(deferredDeletesByCreate, createTransaction, deleteTransaction) {
     const key = entityKey(createTransaction.modelName, createTransaction.modelId);
     const deferred = deferredDeletesByCreate.get(key) ?? [];
     deferred.push(deleteTransaction);
     deferredDeletesByCreate.set(key, deferred);
 }
+/**
+ * Re-enqueues the deletes parked behind a create once that create settles,
+ * skipping any whose status is no longer pending.
+ */
 export function releaseDeferredDeletesForCreate(deferredDeletesByCreate, store, enqueue, createTransaction) {
     const key = entityKey(createTransaction.modelName, createTransaction.modelId);
     const deferred = deferredDeletesByCreate.get(key);
@@ -68,7 +86,12 @@ export function releaseDeferredDeletesForCreate(deferredDeletesByCreate, store,
         enqueue(deleteTransaction);
     }
 }
-// Merge two GraphQL update payloads with special handling for metadata fields
+/**
+ * Merges two update payloads for the same row into one. Later values win, with
+ * one exception: a `metadata` field is deep-merged as an object — parsing it
+ * first when it arrives as a JSON string — rather than replaced, so partial
+ * metadata updates accumulate instead of overwriting each other.
+ */
 export function mergeUpdateData(left, right, _modelName) {
     const out = { ...(left || {}) };
     const src = right || {};

package/dist/transactions/commitPayload.d.ts

@@ -1,13 +1,12 @@
 /**
- * Commit-payload projection — the queue's wire vocabulary, lifted out of
- * `TransactionQueue.ts` as a pure leaf (no queue state, no timers).
- *
- * Owns the `Transaction` record shape plus every helper that turns a local
- * transaction into a wire-safe commit operation: schema-field projection
- * (`projectCommitPayload`), write-option projection (`applyWriteOptions`),
- * FK-aware priority scoring, and the transport-error duck-typing used to
- * classify server rejections. Because nothing here touches the queue's
- * runtime, the HTTP commit path can share this projection too.
+ * The vocabulary a local transaction uses on the wire. This module defines the
+ * {@link Transaction} record and the helpers that turn a transaction into a
+ * wire-safe commit operation: schema-field projection
+ * ({@link projectCommitPayload}), write-option projection
+ * ({@link applyWriteOptions}), foreign-key-aware priority scoring
+ * ({@link computePriorityScore}), and the structural checks used to classify
+ * transport errors. Nothing here holds queue state or timers, so the batched
+ * queue path and the HTTP commit path share the same projection.
  */
 import { MutationOperationType } from '../types/index.js';
 import type { MutationOptions, WriteOptions } from '../interfaces/index.js';
@@ -20,24 +19,22 @@ export interface UserContext {
 /** Wire-format mutation payload (post-projection). */
 export type MutationInput = Record<string, unknown>;
 /**
- * Project a Model's serialized data onto its schema-declared fields
- * and return a wire-safe commit payload. Two jobs:
+ * Projects a model's serialized data onto the fields declared in its schema and
+ * returns a wire-safe commit payload. It does two things:
  *
- *   1. Drop framework internals (`__class`, `__typename`, `clientId`,
+ *   1. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
  *      `syncStatus`) and anything not declared on the model's schema.
- *   2. JSON.stringify values typed as `field.json()` — TEXT columns
- *      storing JSON need explicit stringification; postgres.js won't
- *      auto-serialize for non-JSONB columns.
+ *   2. Passes each declared field's value through unchanged, including
+ *      JSON-typed fields, which are sent as objects rather than pre-serialized
+ *      strings (see the note in the body for why).
  *
- * For updates (`dropUndefined: true`), `undefined` values are also
- * stripped so they don't translate to `SET column = NULL` on the
- * server side.
+ * For updates (`dropUndefined: true`), `undefined` values are also removed so
+ * they are not written as `SET column = NULL` on the server.
  *
- * Fields are read from `ModelRegistry`, populated by
- * `registerModelsFromSchema` at SDK initialization. If the model
- * isn't registered with field metadata (edge case — e.g., tests or
- * manually registered models), projection falls back to identity and
- * the caller gets whatever the Model serialized.
+ * Field metadata comes from the model registry, populated when the schema is
+ * registered at initialization. If a model has no registered field metadata —
+ * for example a manually registered model — projection passes the serialized
+ * data through unchanged apart from dropping the framework keys.
  */
 export declare function projectCommitPayload(modelName: string, source: Record<string, unknown>, opts: {
     dropUndefined: boolean;
@@ -60,36 +57,35 @@ export interface Transaction {
     batchId?: string;
     /** Completed locally without a server operation; no sync echo will arrive. */
     localOnly?: boolean;
-    /** LINEAR PATTERN: syncId threshold - transaction confirms when delta.id >= this value */
+    /** Sync-id threshold: the transaction confirms once a delta with an id at least this value arrives. */
     syncIdNeededForCompletion?: number;
     /**
-     * Resolves when the server has confirmed this transaction (delta arrived
-     * or HTTP ack). Rejects with the originating error if the transaction is
-     * permanently rolled back. Name matches the queue's existing `'confirmed'`
-     * status vocabulary (`commits.create({wait:'confirmed'})`,
-     * `waitForConfirmation`) — gives call sites a single `await` point for
-     * "did my write land?", so failures surface at the source instead of
-     * leaking via silent pool rollback. The rejection error is the same
-     * `AbloError` recorded on the queue's `transaction:failed` event.
+     * Resolves once the server has confirmed this transaction, whether by a delta
+     * or an HTTP acknowledgement, and rejects with the originating error if the
+     * transaction is permanently rolled back. It gives a caller one place to await
+     * the answer to "did my write land?", matching the
+     * `commits.create({ wait: 'confirmed' })` and
+     * {@link TransactionQueue.waitForConfirmation} vocabulary, so a failure
+     * surfaces at the call site instead of only as a silent local rollback. The
+     * rejection value is the same {@link AbloError} carried on the queue's
+     * `transaction:failed` event.
      */
     confirmation?: Promise<void>;
 }
 export declare const normalizeModelKey: (modelName: string) => string;
 export declare const stripModelSuffix: (modelName: string) => string;
 /**
- * FK-ordered create priority.
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
  *
- * Reads `config.modelCreatePriority` out of the runtime SyncEngineContext —
- * this map is populated once at `createSyncEngine(...)` time by walking the
- * schema's `belongsTo` graph (see `computeFKDepthPriority` in
- * `client/createSyncEngine.ts`). The queue stays schema-agnostic: no model
- * names appear here, and consumer applications can override specific
- * priorities via `configOverrides.modelCreatePriority` without touching the
- * SDK.
+ * The score comes from a priority map on the runtime configuration, built once
+ * at initialization by walking the schema's `belongsTo` graph. No model names
+ * are hard-coded here, and an application can override specific priorities
+ * through `configOverrides.modelCreatePriority`.
  *
- * Non-create ops (update/delete/archive/unarchive) don't need FK ordering
- * because the row already exists, so they all share
- * `config.defaultNonCreatePriority`.
+ * Non-create operations (update, delete, archive, unarchive) need no
+ * foreign-key ordering because the row already exists, so they all share the
+ * configured default non-create priority.
  */
 export declare const computePriorityScore: (type: Transaction["type"], modelName: string) => number;
 export declare const TX_TYPE_TO_MUTATION_OP: Record<Transaction['type'], MutationOperationType>;
@@ -100,18 +96,18 @@ export interface WriteOperationFields {
     options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
 }
 /**
- * Project a transaction's `writeOptions` onto the wire operation. Stale
- * guards (`readAt`/`onStale`) ride at the op root; `idempotencyKey`/`label`
- * ride in the op's `options` slot (`MutationOperation.options` — the
- * mutation_log cache key + audit tag). This is the single place the
- * caller-supplied write vocabulary crosses onto the wire.
+ * Copies a transaction's `writeOptions` onto the wire operation. The
+ * stale-context guards (`readAt` and `onStale`) sit at the operation's root,
+ * while `idempotencyKey` and `label` go in its `options` slot — the
+ * `mutation_log` cache key and audit tag. This is the one place caller-supplied
+ * write options cross onto the wire.
  */
 export declare function applyWriteOptions<T extends object>(op: T, transaction: Transaction): T & WriteOperationFields;
 /**
- * Structural shape we duck-type against for transport-layer errors.
- * Captures the union of GraphQL-style and HTTP-style error shapes the
- * mutation executor surfaces — kept narrow on purpose so we don't
- * pretend to know fields the runtime won't always supply.
+ * The structural shape used to inspect transport-layer errors. It covers the
+ * GraphQL-style and HTTP-style error shapes the mutation executor can surface,
+ * and is kept intentionally narrow so it does not claim fields the runtime may
+ * not supply.
  */
 export interface TransportError {
     message?: string;