@abloatai/humans 0.37.0

package/dist/local/transactions/mutations/MutationStore.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 MutationQueue} owns an instance and routes every status change
+ * through {@link updateStatus}, which keeps the two indexes consistent.
+ */
+import type { QueuedMutation } from './commitPayload.js';
+export declare class MutationStore {
+    private transactions;
+    private byStatus;
+    add(transaction: QueuedMutation): void;
+    get(id: string): QueuedMutation | undefined;
+    updateStatus(id: string, newStatus: QueuedMutation['status']): void;
+    getByStatus(status: QueuedMutation['status']): QueuedMutation[];
+    remove(id: string): void;
+    clear(): void;
+    getAll(): QueuedMutation[];
+}

package/dist/local/transactions/mutations/MutationStore.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 MutationQueue} owns an instance and routes every status change
+ * through {@link updateStatus}, which keeps the two indexes consistent.
+ */
+export class MutationStore {
+    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/local/transactions/mutations/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/local/transactions/mutations/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/local/transactions/mutations/batchProcessing.d.ts

@@ -0,0 +1,64 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { MutationQueueConfig } from './MutationQueue.js';
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+import type { MutationStore } from './MutationStore.js';
+import type { OptimisticUpdateEntry } from './localMutation.js';
+import type { StaleNotification } from '@abloatai/transaction/coordination/schema';
+import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+export interface BatchProcessingContext {
+    readonly runtime: RuntimeContext;
+    readonly config: MutationQueueConfig;
+    readonly durableReplayBlock: object | null;
+    readonly executionQueue: QueuedMutation[];
+    readonly isProcessing: boolean;
+    readonly setIsProcessing: (value: boolean) => void;
+    readonly takeNextExecutionBatch: () => QueuedMutation[];
+    readonly ensureDerivedFields: (transaction: QueuedMutation) => void;
+    readonly ensureCommitEnvelope: (batch: QueuedMutation[]) => string;
+    readonly executingCount: number;
+    readonly setExecutingCount: (value: number) => void;
+    readonly inFlightByModel: Set<string>;
+    readonly pendingMergeByModel: Map<string, {
+        data: MutationInput;
+        sourceMutationIds: string[];
+    }>;
+    readonly generateId: () => string;
+    readonly computePriorityScore: (type: QueuedMutation['type'], modelName: string) => number;
+    readonly store: MutationStore;
+    readonly enqueue: (transaction: QueuedMutation) => void;
+    readonly optimisticUpdates: Map<string, OptimisticUpdateEntry>;
+    readonly commitNotifications: Map<string, StaleNotification[]>;
+    readonly commitMissingIds: Map<string, string[]>;
+    readonly sourceMutationIdsFor: (batch: readonly QueuedMutation[]) => string[];
+    readonly dispatchCommitBounded: (...args: Parameters<import('../../interfaces/index.js').MutationExecutor['commit']>) => ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>;
+    readonly parseMutationCommitResult: (value: Awaited<ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>>) => MutationCommitResult;
+    readonly persistDurableCommitAcceptance: (envelope: DurableCommitEnvelope, result: MutationCommitResult) => Promise<DurableCommitEnvelope>;
+    readonly removeDurableCommit: (idempotencyKey: string) => Promise<void>;
+    readonly assertEnvelopeInsideReplayWindow: (envelope: DurableCommitEnvelope) => void;
+    readonly sealDurableCommit: (input: Parameters<typeof import('./commitTransport.js').sealDurableCommit>[1]) => Promise<DurableCommitEnvelope>;
+    readonly noteAck: (syncId: number | undefined) => void;
+    readonly classifyReceiptNotifications: (operations: readonly {
+        model: string;
+        id: string;
+    }[], notifications: readonly StaleNotification[]) => {
+        holdsEntireBatch: boolean;
+        heldTargets: Set<string>;
+        notificationsByTarget: Map<string, StaleNotification[]>;
+    };
+    readonly receiptTargetKey: (modelName: string, modelId: string) => string;
+    readonly scheduleReplicationLagTimeout: (transactionId: string, clientTxId?: string, correlationId?: string) => void;
+    readonly scheduleDeltaConfirmationTimeout: (transaction: QueuedMutation, timeoutMs: number) => void;
+    readonly clearReplicationLagState: (transactionId: string) => void;
+    readonly completeQueuedCommit: (transaction: import('./commitLane.js').CommitTransaction, syncId: number) => void;
+    readonly queuedCommitMatchesCorrelation: (transaction: import('./commitLane.js').CommitTransaction, correlationId: string) => boolean;
+    readonly recentDeltaCorrelations: Map<string, number>;
+    readonly lastSeenSyncId: number;
+    readonly scheduleProcessing: (immediate?: boolean) => void;
+    readonly handleFailure: (transaction: QueuedMutation, error: Error) => Promise<void>;
+    readonly isDefinitiveRejection: (error: Error) => boolean;
+    readonly emitCommitLifecycle: (event: string, payload: object) => void;
+    readonly emit: (event: string, payload: object) => boolean;
+    readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, error?: Error) => Promise<void>;
+}
+export declare function processBatch(ctx: BatchProcessingContext): Promise<void>;