@abloatai/ablo 0.25.0 → 0.27.0

package/dist/transactions/TransactionStore.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 {
+    private transactions;
+    private byStatus;
+    add(transaction: Transaction): void;
+    get(id: string): Transaction | undefined;
+    updateStatus(id: string, newStatus: Transaction['status']): void;
+    getByStatus(status: Transaction['status']): Transaction[];
+    remove(id: string): void;
+    clear(): void;
+    getAll(): Transaction[];
+}

package/dist/transactions/TransactionStore.js

@@ -0,0 +1,53 @@
+/**
+ * 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();
+    byStatus = new Map();
+    add(transaction) {
+        this.transactions.set(transaction.id, transaction);
+        if (!this.byStatus.has(transaction.status)) {
+            this.byStatus.set(transaction.status, new Set());
+        }
+        this.byStatus.get(transaction.status).add(transaction.id);
+    }
+    get(id) {
+        return this.transactions.get(id);
+    }
+    updateStatus(id, newStatus) {
+        const tx = this.transactions.get(id);
+        if (!tx)
+            return;
+        this.byStatus.get(tx.status)?.delete(id);
+        tx.status = newStatus;
+        if (!this.byStatus.has(newStatus)) {
+            this.byStatus.set(newStatus, new Set());
+        }
+        this.byStatus.get(newStatus).add(id);
+    }
+    getByStatus(status) {
+        const ids = this.byStatus.get(status) || new Set();
+        return Array.from(ids)
+            .map((id) => this.transactions.get(id))
+            .filter(Boolean);
+    }
+    remove(id) {
+        const tx = this.transactions.get(id);
+        if (!tx)
+            return;
+        this.transactions.delete(id);
+        this.byStatus.get(tx.status)?.delete(id);
+    }
+    clear() {
+        this.transactions.clear();
+        this.byStatus.clear();
+    }
+    getAll() {
+        return Array.from(this.transactions.values());
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * 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 ({@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 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 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;
+/**
+ * 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

@@ -0,0 +1,140 @@
+/**
+ * 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 ({@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 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;
+/**
+ * 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' &&
+        tx.status === 'pending' &&
+        tx.attempts === 0 &&
+        isTransactionForModel(tx, modelName, modelId);
+    const stagedIndex = staged.findIndex(isUnsentCreate);
+    if (stagedIndex >= 0) {
+        return staged.splice(stagedIndex, 1)[0];
+    }
+    const queuedIndex = queued.findIndex(isUnsentCreate);
+    if (queuedIndex >= 0) {
+        return queued.splice(queuedIndex, 1)[0];
+    }
+    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'),
+        ...store.getByStatus('executing'),
+        ...store.getByStatus('awaiting_delta'),
+    ].filter((tx) => tx.type === 'create' &&
+        isTransactionForModel(tx, modelName, modelId) &&
+        // A never-attempted pending create can be cancelled instead. Once the
+        // create has been sent, even a retry-pending state is a causal barrier:
+        // the server may already have applied it and only the response was lost.
+        (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);
+    if (!deferred || deferred.length === 0)
+        return;
+    deferredDeletesByCreate.delete(key);
+    for (const deleteTransaction of deferred) {
+        if (store.get(deleteTransaction.id)?.status !== 'pending')
+            continue;
+        enqueue(deleteTransaction);
+    }
+}
+/**
+ * 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 || {};
+    for (const key of Object.keys(src)) {
+        // Special case: metadata payloads may be JSON strings; merge objects instead of clobbering
+        if (key === 'metadata') {
+            const l = out.metadata;
+            const r = src.metadata;
+            // If both sides undefined/null, continue
+            if (l == null && r == null) {
+                continue;
+            }
+            // Normalize to objects
+            const toObj = (v) => {
+                if (v == null)
+                    return {};
+                if (typeof v === 'string') {
+                    try {
+                        return JSON.parse(v);
+                    }
+                    catch {
+                        return {};
+                    }
+                }
+                if (typeof v === 'object')
+                    return v;
+                return {};
+            };
+            const lobj = toObj(l);
+            const robj = toObj(r);
+            const merged = { ...lobj, ...robj };
+            // Re-stringify to match schema input type
+            try {
+                out.metadata = JSON.stringify(merged);
+            }
+            catch {
+                // Fallback to right-hand side if stringify fails
+                out.metadata = typeof r === 'string' ? r : JSON.stringify(robj || {});
+            }
+            continue;
+        }
+        // Default: shallow overwrite with right-hand value
+        out[key] = src[key];
+    }
+    return out;
+}

package/dist/transactions/commitPayload.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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';
+export interface UserContext {
+    userId: string;
+    organizationId: string;
+    role?: string;
+    teamIds?: string[];
+}
+/** Wire-format mutation payload (post-projection). */
+export type MutationInput = Record<string, unknown>;
+/**
+ * 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. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
+ *      `syncStatus`) and anything not declared on the model's schema.
+ *   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 removed so
+ * they are not written as `SET column = NULL` on the server.
+ *
+ * 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;
+}): MutationInput;
+export interface Transaction {
+    id: string;
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    modelName: string;
+    modelId: string;
+    modelKey: string;
+    data?: MutationInput;
+    previousData?: MutationInput | null;
+    context: UserContext;
+    status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed' | 'rolled_back';
+    createdAt: number;
+    attempts: number;
+    priority: 'normal' | 'high';
+    priorityScore: number;
+    writeOptions?: WriteOptions;
+    batchId?: string;
+    /** Completed locally without a server operation; no sync echo will arrive. */
+    localOnly?: boolean;
+    /** Sync-id threshold: the transaction confirms once a delta with an id at least this value arrives. */
+    syncIdNeededForCompletion?: number;
+    /**
+     * 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;
+/**
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
+ *
+ * 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 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>;
+export declare function hasStaleWriteOptions(options?: WriteOptions): boolean;
+export interface WriteOperationFields {
+    readAt?: number | null;
+    onStale?: 'reject' | 'overwrite' | 'notify' | null;
+    options?: Pick<MutationOptions, 'idempotencyKey' | 'label'>;
+}
+/**
+ * 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;
+/**
+ * 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;
+    code?: string | number;
+    extensions?: Record<string, unknown>;
+    locations?: readonly unknown[];
+    path?: readonly (string | number)[];
+    response?: {
+        status?: number;
+        errors?: readonly {
+            extensions?: {
+                code?: string;
+            };
+            message?: string;
+        }[];
+    };
+    error?: string;
+}
+export declare function asTransportError(value: unknown): TransportError;
+export declare function extractStatusCode(error: unknown): number | undefined;