@abloatai/ablo 0.35.0 → 0.36.0

package/dist/transactions/mutations/MutationQueue.js

@@ -14,7 +14,7 @@
 import { EventEmitter } from 'events';
 import { v4 as uuid } from 'uuid';
 import { Model } from '../../Model.js';
-import { getContext } from '../../context.js';
+import { globalRuntime } from '../../context.js';
 import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloNotFoundError, AbloValidationError, errorCodeSpec, } from '../../transaction/errors.js';
 import { LogPosition } from '../../transaction/logPosition.js';
 import { mutationCommitResultSchema, } from '../../transaction/wire/commit.js';
@@ -51,8 +51,9 @@ export class MutationQueue extends EventEmitter {
     // queue treats as transient and retries endlessly.
     _mutationExecutor = null;
     get mutationExecutor() {
-        return this._mutationExecutor ?? getContext().mutationExecutor;
+        return this._mutationExecutor ?? this.runtime.mutationExecutor;
     }
+    runtime;
     executionQueue = [];
     isProcessing = false;
     processTimer;
@@ -100,7 +101,7 @@ export class MutationQueue extends EventEmitter {
             this.emit(event, payload);
         }
         catch (error) {
-            getContext().observability.captureMutationFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: `commit-lifecycle-listener:${event}`,
                 error: error instanceof Error ? error : String(error),
             });
@@ -121,12 +122,12 @@ export class MutationQueue extends EventEmitter {
             // the caller — without this line the session degrades into "nothing
             // saves and nothing errors". One loud line at the moment the block
             // engages is the only visible trace.
-            getContext().logger.warn('sync paused: a saved write from an earlier session is older than the server replay window, so newer writes are held until it is reviewed', { sealedAt: envelope.sealedAt });
+            this.runtime.logger.warn('sync paused: a saved write from an earlier session is older than the server replay window, so newer writes are held until it is reviewed', { sealedAt: envelope.sealedAt });
             throw this.durableReplayBlock;
         }
     }
     computePriorityScore(type, modelName) {
-        return computePriorityScore(type, modelName);
+        return computePriorityScore(type, modelName, this.runtime);
     }
     ensureDerivedFields(transaction) {
         if (!transaction.modelKey) {
@@ -444,7 +445,7 @@ export class MutationQueue extends EventEmitter {
             await this.commitOutbox.remove(commitEnvelopeRecordId(idempotencyKey));
         }
         catch (error) {
-            getContext().logger.debug('[MutationQueue] Durable-write cleanup deferred', {
+            this.runtime.logger.debug('[MutationQueue] Durable-write cleanup deferred', {
                 idempotencyKey,
                 error: error instanceof Error ? error.message : String(error),
             });
@@ -659,6 +660,7 @@ export class MutationQueue extends EventEmitter {
     confirmationResolvers = new Map();
     constructor(config) {
         super();
+        this.runtime = config?.runtime ?? globalRuntime;
         this.position = config?.position ?? new LogPosition();
         // Bind the confirmation tracker to this queue's store/ledger/events.
         // `isConnected` closes over `isConnectedFn` so `setConnectionChecker`
@@ -671,6 +673,7 @@ export class MutationQueue extends EventEmitter {
             },
             isConnected: () => this.isConnectedFn(),
             position: this.position,
+            runtime: this.runtime,
         });
         if (config) {
             this.config = { ...this.config, ...config };
@@ -804,7 +807,7 @@ export class MutationQueue extends EventEmitter {
             return;
         // Each failed commit reaches the consumer through its own rejection path,
         // so this aggregate line is forensic and logged at debug rather than warn.
-        getContext().logger.debug(`[MutationQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
+        this.runtime.logger.debug(`[MutationQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
         for (const id of inFlight) {
             const tx = this.commitStore.get(id);
             if (!tx)
@@ -877,7 +880,7 @@ export class MutationQueue extends EventEmitter {
         this.batchIndex++;
         const currentBatchIndex = this.batchIndex;
         // Log batch commit for performance monitoring
-        getContext().logger.debug('[MutationQueue] commitCreatedTransactions', {
+        this.runtime.logger.debug('[MutationQueue] commitCreatedTransactions', {
             count: this.createdTransactions.length,
             batchIndex: currentBatchIndex,
             types: this.createdTransactions.map((t) => `${t.type}:${t.modelName}`),
@@ -981,7 +984,7 @@ export class MutationQueue extends EventEmitter {
                         this.optimisticUpdates.delete(tx.id);
                     }
                 }
-                getContext().logger.debug('txn:commit', 0, {
+                this.runtime.logger.debug('txn:commit', 0, {
                     count: batch.length,
                     lastSyncId: result.lastSyncId,
                 });
@@ -990,13 +993,13 @@ export class MutationQueue extends EventEmitter {
             catch (err) {
                 // If one request fails, hand it and every later request back to the
                 // normal lane. Their envelopes stay attached for safe retry.
-                const isOffline = !getContext().onlineStatus.isOnline();
+                const isOffline = !this.runtime.onlineStatus.isOnline();
                 const isNetworkError = err instanceof Error &&
                     (err.message.includes('Failed to fetch') ||
                         err.message.includes('Network request failed') ||
                         err.message.includes('NetworkError'));
                 if (!isOffline || !isNetworkError) {
-                    getContext().observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
+                    this.runtime.observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                 }
@@ -1113,7 +1116,7 @@ export class MutationQueue extends EventEmitter {
         const actualModelName = model.getModelName();
         // Skip Activity delete transactions - activities are permanent audit records
         if (actualModelName === 'Activity') {
-            getContext().logger.debug('MutationQueue.delete() skipping Activity deletion - permanent audit records', { modelId: model.id });
+            this.runtime.logger.debug('MutationQueue.delete() skipping Activity deletion - permanent audit records', { modelId: model.id });
             const modelKey = normalizeModelKey(actualModelName);
             const priorityScore = this.computePriorityScore('delete', actualModelName);
             const mockTransaction = {
@@ -1180,7 +1183,14 @@ export class MutationQueue extends EventEmitter {
         transaction.sourceMutationIds = [
             ...new Set([
                 ...(transaction.sourceMutationIds ?? []),
-                ...canceledUpdates.flatMap((candidate) => candidate.sourceMutationIds ?? []),
+                // Absorb journal sources only from updates that never sealed an
+                // envelope. A sealed update's seal already CONSUMED its journal rows
+                // — they belong to that envelope forever — so listing them here
+                // poisons this delete's own seal: the new-envelope guard finds its
+                // sources missing, rejects with `idempotency_conflict`, and the
+                // optimistic delete reverts. That was a user-visible lost delete
+                // (edit a layer, then delete it while the edit was on the wire).
+                ...canceledUpdates.flatMap((candidate) => candidate.commitEnvelope ? [] : (candidate.sourceMutationIds ?? [])),
                 ...(pendingMerge?.sourceMutationIds ?? []),
             ]),
         ];
@@ -1352,7 +1362,7 @@ export class MutationQueue extends EventEmitter {
         // are already executing, so the server is not flooded with concurrent
         // requests.
         if (this.executingCount >= this.config.maxExecutingTransactions) {
-            getContext().logger.debug('[MutationQueue] Backpressure: delaying batch, too many executing', {
+            this.runtime.logger.debug('[MutationQueue] Backpressure: delaying batch, too many executing', {
                 executingCount: this.executingCount,
                 max: this.config.maxExecutingTransactions,
             });
@@ -1393,7 +1403,7 @@ export class MutationQueue extends EventEmitter {
         this.isProcessing = true;
         // Declare batch outside try so it's accessible in finally for backpressure tracking
         let batch = [];
-        await getContext().observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
+        await this.runtime.observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
             try {
                 // Sort the execution queue by foreign-key priority before selecting a
                 // batch, so a parent row is always committed before its children, even
@@ -1529,7 +1539,7 @@ export class MutationQueue extends EventEmitter {
                                 }
                                 this.store.updateStatus(tx.id, 'awaiting_delta');
                                 this.scheduleReplicationLagTimeout(tx.id, commitIdempotencyKey, result.correlationId);
-                                getContext().logger.debug('tx:awaiting_delta', {
+                                this.runtime.logger.debug('tx:awaiting_delta', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
                                     reason: 'queued_forward_waiting_for_correlated_echo',
@@ -1547,7 +1557,7 @@ export class MutationQueue extends EventEmitter {
                             // A lastSyncId of 0 means the mutation succeeded but the server
                             // emitted no sync delta; record that anomaly for observability.
                             if (lastSyncId === 0) {
-                                getContext().observability.captureCommitZeroSyncId({
+                                this.runtime.observability.captureCommitZeroSyncId({
                                     operationCount: operations.length,
                                     operations: operations.map((op) => `${op.type}:${op.model}:${op.id?.slice(0, 8) ?? '?'}`),
                                 });
@@ -1565,7 +1575,7 @@ export class MutationQueue extends EventEmitter {
                                     this.emit('transaction:completed', tx);
                                     this.emit(`transaction:completed:${tx.id}`, tx);
                                     this.optimisticUpdates.delete(tx.id);
-                                    getContext().logger.debug('tx:confirm_delete_zero_syncid', {
+                                    this.runtime.logger.debug('tx:confirm_delete_zero_syncid', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         reason: 'delete_idempotent_no_delta',
@@ -1580,7 +1590,7 @@ export class MutationQueue extends EventEmitter {
                                     this.emit('transaction:completed', tx);
                                     this.emit(`transaction:completed:${tx.id}`, tx);
                                     this.optimisticUpdates.delete(tx.id);
-                                    getContext().logger.debug('tx:confirm_ack', {
+                                    this.runtime.logger.debug('tx:confirm_ack', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         serverSyncId: lastSyncId,
@@ -1589,7 +1599,7 @@ export class MutationQueue extends EventEmitter {
                                 }
                                 else {
                                     this.store.updateStatus(tx.id, 'awaiting_delta');
-                                    getContext().logger.debug('tx:awaiting_delta', {
+                                    this.runtime.logger.debug('tx:awaiting_delta', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         neededSyncId: lastSyncId,
@@ -1636,7 +1646,7 @@ export class MutationQueue extends EventEmitter {
                         // authoritative `warn` with the same typed cause) — passes
                         // through here. Logging it at `warn` made one rejected write
                         // surface three identical dumps; keep it at `debug`.
-                        getContext().logger.debug('[MutationQueue] Batch commit rejected', {
+                        this.runtime.logger.debug('[MutationQueue] Batch commit rejected', {
                             batchSize: batchOps.length,
                             models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
                             errorType: abloErr?.type ?? error?.name,
@@ -1654,7 +1664,7 @@ export class MutationQueue extends EventEmitter {
                             if (dispatchStarted) {
                                 await this.removeDurableCommit(commitIdempotencyKey);
                             }
-                            getContext().logger.info('[MutationQueue] Graceful handling: entity already deleted', {
+                            this.runtime.logger.info('[MutationQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
@@ -1662,7 +1672,7 @@ export class MutationQueue extends EventEmitter {
                                     // Row already gone: the intended state holds, mark completed.
                                     this.store.updateStatus(tx.id, 'completed');
                                     this.emit('transaction:completed', tx);
-                                    getContext().logger.debug('[MutationQueue] Orphaned transaction treated as success', {
+                                    this.runtime.logger.debug('[MutationQueue] Orphaned transaction treated as success', {
                                         txId: tx.id.slice(0, 12),
                                         model: tx.modelName,
                                         type: op.type,
@@ -1722,7 +1732,7 @@ export class MutationQueue extends EventEmitter {
                     this.scheduleProcessing(true);
                 }
                 const batchEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
-                getContext().logger.debug('txn:batch', batchEnd - batchStart, {
+                this.runtime.logger.debug('txn:batch', batchEnd - batchStart, {
                     maxBatchSize: this.config.maxBatchSize,
                     remaining: this.executionQueue.length,
                     executingCount: this.executingCount,
@@ -2018,7 +2028,7 @@ export class MutationQueue extends EventEmitter {
                         }
                         else {
                             this.scheduleReplicationLagTimeout(tx.id, tx.id, result.correlationId);
-                            getContext().logger.debug('[MutationQueue] commit lane awaiting source echo', {
+                            this.runtime.logger.debug('[MutationQueue] commit lane awaiting source echo', {
                                 txId: tx.id.slice(0, 12),
                             });
                         }
@@ -2058,7 +2068,7 @@ export class MutationQueue extends EventEmitter {
                         // (reconnect or the next enqueueCommit) rather than tight-looping
                         // while the connection is down.
                         tx.status = 'pending';
-                        getContext().logger.debug('[MutationQueue] commit lane transient', {
+                        this.runtime.logger.debug('[MutationQueue] commit lane transient', {
                             txId: tx.id.slice(0, 12),
                             attempts: tx.attempts,
                             transientAttempts: tx.transientAttempts ?? 0,
@@ -2072,7 +2082,7 @@ export class MutationQueue extends EventEmitter {
                     // Internal bookkeeping; the consumer-facing rejection is emitted on
                     // 'transaction:failed' and surfaced by the permanent-error headline,
                     // so this line stays at debug.
-                    getContext().logger.debug('[MutationQueue] commit lane permanent error', {
+                    this.runtime.logger.debug('[MutationQueue] commit lane permanent error', {
                         txId: tx.id.slice(0, 12),
                         attempts: tx.attempts,
                         message: error.message,
@@ -2282,7 +2292,7 @@ export class MutationQueue extends EventEmitter {
                 const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
                 const isRepeat = sig === this.lastPermanentErrorSig;
                 this.lastPermanentErrorSig = sig;
-                const logger = getContext().logger;
+                const logger = this.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):
@@ -2440,7 +2450,7 @@ export class MutationQueue extends EventEmitter {
             }
         }
         catch (error) {
-            getContext().observability.captureMutationFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'load-persisted-transactions',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2470,8 +2480,8 @@ export class MutationQueue extends EventEmitter {
                     envelopes.push(parsed.data);
                 }
                 else {
-                    getContext().logger.warn('A saved local write is unreadable and was held for review.');
-                    getContext().observability.captureMutationFailure({
+                    this.runtime.logger.warn('A saved local write is unreadable and was held for review.');
+                    this.runtime.observability.captureMutationFailure({
                         context: 'restore-commit-envelope',
                         error: parsed.error,
                     });
@@ -2488,8 +2498,8 @@ export class MutationQueue extends EventEmitter {
                 if (envelope.acceptedAt === undefined &&
                     Date.now() - envelope.sealedAt >=
                         MutationQueue.DURABLE_REPLAY_WINDOW_MS) {
-                    getContext().logger.warn('A saved local write is too old to retry safely and was held for review.');
-                    getContext().observability.captureMutationFailure({
+                    this.runtime.logger.warn('A saved local write is too old to retry safely and was held for review.');
+                    this.runtime.observability.captureMutationFailure({
                         context: 'quarantine-expired-commit-envelope',
                         error: `Envelope ${envelope.idempotencyKey} is too old to replay safely`,
                     });
@@ -2500,7 +2510,7 @@ export class MutationQueue extends EventEmitter {
                         envelope.scope.organizationId !== this.commitOutboxScope.organizationId ||
                         envelope.scope.participantId !== this.commitOutboxScope.participantId ||
                         envelope.scope.namespace !== this.commitOutboxScope.namespace)) {
-                    getContext().logger.warn('A saved local write belongs to a different account or server and was held for review.');
+                    this.runtime.logger.warn('A saved local write belongs to a different account or server and was held for review.');
                     continue;
                 }
                 if (this.commitStore.has(envelope.idempotencyKey))
@@ -2533,10 +2543,10 @@ export class MutationQueue extends EventEmitter {
                 void this.processCommitLane();
         }
         catch (error) {
-            getContext().logger.debug('[MutationQueue] Failed to restore durable writes', {
+            this.runtime.logger.debug('[MutationQueue] Failed to restore durable writes', {
                 error: error instanceof Error ? error.message : String(error),
             });
-            getContext().observability.captureMutationFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'restore-commit-envelopes',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2553,15 +2563,15 @@ export class MutationQueue extends EventEmitter {
     deserializeTransaction(data) {
         if (isNonReplayablePersistedRow(data))
             return null;
-        const transaction = deserializePersistedTransaction(data);
+        const transaction = deserializePersistedTransaction(data, this.runtime);
         if (!transaction) {
             const rowId = typeof data === 'object' && data !== null && typeof data.id === 'string'
                 ? data.id
                 : undefined;
-            getContext().logger.debug('[MutationQueue] Dropping malformed persisted transaction', {
+            this.runtime.logger.debug('[MutationQueue] Dropping malformed persisted transaction', {
                 rowId,
             });
-            getContext().observability.captureMutationFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'deserialize-persisted-transaction',
                 error: `Persisted transaction failed schema validation${rowId ? ` (id: ${rowId})` : ''}`,
             });
@@ -2589,7 +2599,7 @@ export class MutationQueue extends EventEmitter {
                     // listener) must surface, not vanish — the status flip above is
                     // already committed either way.
                     void this.rollbackOptimistic(transaction, 'model_cancelled').catch((error) => {
-                        getContext().observability.captureMutationFailure({
+                        this.runtime.observability.captureMutationFailure({
                             context: 'rollback-model-cancelled',
                             error: error instanceof Error ? error : String(error),
                         });
@@ -2623,13 +2633,13 @@ export class MutationQueue extends EventEmitter {
                 if (fkValue === parentId) {
                     this.store.updateStatus(transaction.id, 'rolled_back');
                     void this.rollbackOptimistic(transaction, 'cascade_parent_deleted').catch((error) => {
-                        getContext().observability.captureMutationFailure({
+                        this.runtime.observability.captureMutationFailure({
                             context: 'rollback-cascade-parent-deleted',
                             error: error instanceof Error ? error : String(error),
                         });
                     });
                     cancelled++;
-                    getContext().logger.debug('[MutationQueue] Cascade cancelled orphaned transaction', {
+                    this.runtime.logger.debug('[MutationQueue] Cascade cancelled orphaned transaction', {
                         txId: transaction.id.slice(0, 12),
                         model: childModelName,
                         foreignKey,
@@ -2654,13 +2664,13 @@ export class MutationQueue extends EventEmitter {
         return { ...(remote || {}), ...(local || {}) };
     }
     extractCreateData(model) {
-        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false });
+        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, this.runtime);
     }
     mapChangesToInput(modelName, changes) {
-        return projectCommitPayload(modelName, changes, { dropUndefined: true });
+        return projectCommitPayload(modelName, changes, { dropUndefined: true }, this.runtime);
     }
     extractUpdateData(model) {
-        return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true });
+        return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true }, this.runtime);
     }
     // Derive previous values for changed fields to support accurate rollback.
     // Model-specific special cases do not belong here; a model that needs to

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

@@ -8,6 +8,7 @@
  * transport errors. Nothing here holds queue state or timers, so the batched
  * queue path and the HTTP commit path share the same projection.
  */
+import type { RuntimeContext } from '../../RuntimeContext.js';
 import { MutationOperationType } from '../../transaction/types/index.js';
 import type { OnStaleMode } from '../../transaction/coordination/schema.js';
 import type { MutationOptions, WriteOptions } from '../../interfaces/index.js';
@@ -40,7 +41,7 @@ export type MutationInput = Record<string, unknown>;
  */
 export declare function projectCommitPayload(modelName: string, source: Record<string, unknown>, opts: {
     dropUndefined: boolean;
-}): MutationInput;
+}, runtime?: RuntimeContext): MutationInput;
 export interface QueuedMutation {
     id: string;
     type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
@@ -118,7 +119,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) => 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/transactions/mutations/commitPayload.js

@@ -8,7 +8,7 @@
  * transport errors. Nothing here holds queue state or timers, so the batched
  * queue path and the HTTP commit path share the same projection.
  */
-import { getContext } from '../../context.js';
+import { globalRuntime } from '../../context.js';
 import { MutationOperationType } from '../../transaction/types/index.js';
 import { snapshotJsonValue } from '../../transaction/utils/json.js';
 /**
@@ -35,8 +35,8 @@ const FRAMEWORK_KEYS = new Set(['__class', '__typename', 'clientId', 'syncStatus
  * for example a manually registered model — projection snapshots all serialized
  * data apart from the framework keys.
  */
-export function projectCommitPayload(modelName, source, opts) {
-    const metadata = getContext().getModelMetadata(modelName);
+export function projectCommitPayload(modelName, source, opts, runtime = globalRuntime) {
+    const metadata = runtime.getModelMetadata(modelName);
     const fields = metadata?.fields;
     const out = {};
     if (!fields) {
@@ -90,8 +90,8 @@ export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
  * foreign-key ordering because the row already exists, so they all share the
  * configured default non-create priority.
  */
-export const computePriorityScore = (type, modelName) => {
-    const { modelCreatePriority, defaultCreatePriority, defaultNonCreatePriority } = getContext().config;
+export const computePriorityScore = (type, modelName, runtime = globalRuntime) => {
+    const { modelCreatePriority, defaultCreatePriority, defaultNonCreatePriority } = runtime.config;
     if (type !== 'create')
         return defaultNonCreatePriority;
     return modelCreatePriority.get(modelName) ?? defaultCreatePriority;

package/dist/transactions/mutations/deltaConfirmation.d.ts

@@ -7,6 +7,7 @@
  * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
  * has no cyclic dependency and can be tested on its own.
  */
+import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { LogPosition } from '../../transaction/logPosition.js';
 import type { QueuedMutation } from './commitPayload.js';
 /**
@@ -30,6 +31,8 @@ export interface DeltaConfirmationContext {
     emit(event: string, payload?: unknown): void;
     isConnected(): boolean;
     position: LogPosition;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
 }
 export declare class DeltaConfirmationTracker {
     private readonly ctx;
@@ -37,6 +40,7 @@ export declare class DeltaConfirmationTracker {
     private static readonly DELTA_MAX_TIMEOUT_MS;
     private deltaConfirmationTimeouts;
     private deltaConfirmationRetries;
+    private readonly runtime;
     constructor(ctx: DeltaConfirmationContext);
     /** Applied-cursor alias, kept so the read sites below stay legible. */
     private get lastSeenSyncId();

package/dist/transactions/mutations/deltaConfirmation.js

@@ -7,7 +7,7 @@
  * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
  * has no cyclic dependency and can be tested on its own.
  */
-import { getContext } from '../../context.js';
+import { globalRuntime } from '../../context.js';
 export class DeltaConfirmationTracker {
     ctx;
     // Retry configuration for delta confirmation, using exponential backoff.
@@ -20,8 +20,10 @@ export class DeltaConfirmationTracker {
     deltaConfirmationTimeouts = new Map();
     // Track retry attempts per transaction for exponential backoff
     deltaConfirmationRetries = new Map();
+    runtime;
     constructor(ctx) {
         this.ctx = ctx;
+        this.runtime = ctx.runtime ?? globalRuntime;
     }
     /** Applied-cursor alias, kept so the read sites below stay legible. */
     get lastSeenSyncId() {
@@ -48,7 +50,7 @@ export class DeltaConfirmationTracker {
         const executingTxs = this.ctx.store.getByStatus('executing');
         // Debug: Show state when delta arrives
         if (awaitingTxs.length > 0 || executingTxs.length > 0) {
-            getContext().logger.debug('tx:delta_received', {
+            this.runtime.logger.debug('tx:delta_received', {
                 syncId,
                 lastSeenSyncId: this.lastSeenSyncId,
                 awaitingCount: awaitingTxs.length,
@@ -86,7 +88,7 @@ export class DeltaConfirmationTracker {
                 this.ctx.emit(`transaction:completed:${tx.id}`, tx);
                 this.ctx.optimisticUpdates.delete(tx.id);
                 confirmedCount++;
-                getContext().logger.debug('tx:confirm_via_delta', {
+                this.runtime.logger.debug('tx:confirm_via_delta', {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                     neededSyncId: tx.syncIdNeededForCompletion,
@@ -98,7 +100,7 @@ export class DeltaConfirmationTracker {
         // Log batch summary only if we confirmed something
         if (confirmedCount > 0) {
             // Leave a breadcrumb when transactions confirm.
-            getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
+            this.runtime.observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
                 count: confirmedCount,
                 syncId,
                 remainingAwaiting: awaitingTxs.length - confirmedCount,
@@ -126,7 +128,7 @@ export class DeltaConfirmationTracker {
             if (!this.ctx.isConnected()) {
                 // Self-healing: re-schedule the confirmation wait while offline, no
                 // consumer action needed → debug.
-                getContext().logger.debug('[MutationQueue] Timeout fired while disconnected - re-scheduling', {
+                this.runtime.logger.debug('[MutationQueue] Timeout fired while disconnected - re-scheduling', {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                 });
@@ -135,7 +137,7 @@ export class DeltaConfirmationTracker {
                 return;
             }
             const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
-            getContext().observability.captureReconciliation({
+            this.runtime.observability.captureReconciliation({
                 reason: 'delta_timeout',
                 model: tx.modelName,
                 modelId: tx.modelId,
@@ -165,7 +167,7 @@ export class DeltaConfirmationTracker {
                 });
                 // Self-healing retry with backoff — the server already committed; we're
                 // just waiting on the delta. No consumer action → debug.
-                getContext().logger.debug('[MutationQueue] Re-scheduling with backoff', {
+                this.runtime.logger.debug('[MutationQueue] Re-scheduling with backoff', {
                     txId: tx.id.slice(0, 8),
                     model: tx.modelName,
                     nextTimeoutMs: nextTimeout,
@@ -180,7 +182,7 @@ export class DeltaConfirmationTracker {
                 // session, reconnecting and catching up on deltas will confirm it.
                 this.deltaConfirmationRetries.delete(tx.id);
                 this.deltaConfirmationTimeouts.delete(tx.id);
-                getContext().observability.captureDeltaRetryExhausted({
+                this.runtime.observability.captureDeltaRetryExhausted({
                     txId: tx.id,
                     model: tx.modelName,
                     modelId: tx.modelId,

package/dist/transactions/mutations/replayValidation.d.ts

@@ -16,6 +16,7 @@
  */
 import { z } from 'zod';
 import type { QueuedMutation } from './commitPayload.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
 /**
  * The shape of a persisted transaction that can be replayed: the fields the
  * transaction queue reads when it re-enqueues the row — its id, operation type,
@@ -78,7 +79,7 @@ export declare function isNonReplayablePersistedRow(row: unknown): boolean;
  * fields the stored row lacks — status, attempts, priority, timestamp — are
  * re-derived the same way a freshly staged transaction derives them.
  */
-export declare function deserializePersistedTransaction(row: unknown): QueuedMutation | null;
+export declare function deserializePersistedTransaction(row: unknown, runtime?: RuntimeContext): QueuedMutation | null;
 /**
  * The shape of one entry in the persisted offline mutation queue — an item of
  * the `'queue'` row's `mutations` array, carrying the fields read when the

package/dist/transactions/mutations/replayValidation.js

@@ -16,6 +16,7 @@
  */
 import { z } from 'zod';
 import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
+import { globalRuntime } from '../../context.js';
 import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from '../../transaction/transactions/settlement/commitEnvelope.js';
 import { onStaleModeSchema } from '../../transaction/coordination/schema.js';
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
@@ -87,7 +88,7 @@ export function isNonReplayablePersistedRow(row) {
  * fields the stored row lacks — status, attempts, priority, timestamp — are
  * re-derived the same way a freshly staged transaction derives them.
  */
-export function deserializePersistedTransaction(row) {
+export function deserializePersistedTransaction(row, runtime = globalRuntime) {
     const parsed = persistedTransactionSchema.safeParse(row);
     if (!parsed.success)
         return null;
@@ -105,7 +106,7 @@ export function deserializePersistedTransaction(row) {
         createdAt: tx.createdAt ?? Date.now(),
         attempts: 0,
         priority: 'normal',
-        priorityScore: computePriorityScore(tx.type, tx.modelName),
+        priorityScore: computePriorityScore(tx.type, tx.modelName, runtime),
         ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
         ...(tx.commitEnvelope !== undefined
             ? { commitEnvelope: tx.commitEnvelope }

package/dist/{core → views}/QueryView.d.ts

@@ -12,7 +12,7 @@ import { type IObservableArray } from 'mobx';
 import { type Model } from '../Model.js';
 import { ModelScope } from '../transaction/types/index.js';
 import type { ViewRegistry } from './ViewRegistry.js';
-import type { IncrementalView } from './queryUtils.js';
+import type { IncrementalView } from './incrementalView.js';
 /**
  * The slice of the object pool that a {@link QueryView} reads. It is a minimal
  * structural interface rather than the concrete pool class, which lets a query

package/dist/{core → views}/QueryView.js

@@ -11,7 +11,7 @@
 import { observable, runInAction } from 'mobx';
 import { modelAsRow } from '../Model.js';
 import { ModelScope } from '../transaction/types/index.js';
-import { compareValues, binaryInsertionIndex, findIndexById, } from './queryUtils.js';
+import { compareValues, binaryInsertionIndex, findIndexById, } from './incrementalView.js';
 // ---------------------------------------------------------------------------
 // QueryView
 // ---------------------------------------------------------------------------

package/dist/{core → views}/ViewRegistry.d.ts

@@ -6,7 +6,7 @@
  * QueryView subscribed to that typename.
  */
 import { type Model } from '../Model.js';
-import type { IncrementalView } from './queryUtils.js';
+import type { IncrementalView } from './incrementalView.js';
 export declare class ViewRegistry {
     private views;
     register(typename: string, view: IncrementalView): void;

package/dist/{core/queryUtils.d.ts → views/incrementalView.d.ts}

@@ -1,10 +1,10 @@
 /**
- * Small, self-contained helpers for sorting, filtering, and binary insertion.
- * The incrementally-updated views that implement {@link IncrementalView} rely on
- * these for their ordering and matching, so keeping the rules in one place
- * ensures every view sorts and filters identically. The functions here work on
- * plain arrays and values — they hold no reference to models, pools, or the
- * reactivity system.
+ * The {@link IncrementalView} contract — the interface a live view implements
+ * to receive add/update/remove notifications — together with the sorting,
+ * matching, and binary-insertion rules every view shares. Keeping the rules in
+ * one place ensures every view sorts and filters identically. The functions
+ * here work on plain arrays and values — they hold no reference to models,
+ * pools, or the reactivity system.
  */
 /**
  * The interface a live view implements to receive incremental updates: one call