@abloatai/ablo 0.34.1 → 0.36.0

package/dist/NetworkMonitor.d.ts

@@ -6,10 +6,12 @@
  * firing, so returning to the tab emits a recovery signal the store can act on.
  */
 import { EventEmitter } from 'events';
+import type { RuntimeContext } from './RuntimeContext.js';
 export declare class NetworkMonitor extends EventEmitter {
+    private readonly runtime;
     private isOnline;
     private lastOnlineCheck;
-    constructor();
+    constructor(runtime?: RuntimeContext);
     private handleOnline;
     private handleOffline;
     /**

package/dist/NetworkMonitor.js

@@ -6,15 +6,17 @@
  * firing, so returning to the tab emits a recovery signal the store can act on.
  */
 import { EventEmitter } from 'events';
-import { getContext } from './context.js';
+import { globalRuntime } from './context.js';
 export class NetworkMonitor extends EventEmitter {
+    runtime;
     // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
     // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
     // would seed `false` (offline) on every server client — start optimistic.
     isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
     lastOnlineCheck = new Date();
-    constructor() {
+    constructor(runtime = globalRuntime) {
         super();
+        this.runtime = runtime;
         this.setupListeners();
     }
     handleOnline = () => {
@@ -22,7 +24,7 @@ export class NetworkMonitor extends EventEmitter {
         this.isOnline = true;
         this.lastOnlineCheck = new Date();
         if (wasOffline) {
-            getContext().logger.info('Network connection restored');
+            this.runtime.logger.info('Network connection restored');
             this.emit('online');
         }
     };
@@ -32,7 +34,7 @@ export class NetworkMonitor extends EventEmitter {
         if (wasOnline) {
             // Symmetric with 'Network connection restored' (info) — expected,
             // transient connectivity state, not an actionable warning.
-            getContext().logger.info('Network connection lost');
+            this.runtime.logger.info('Network connection lost');
             this.emit('offline');
         }
     };
@@ -49,7 +51,7 @@ export class NetworkMonitor extends EventEmitter {
         this.isOnline = navigator.onLine;
         this.lastOnlineCheck = new Date();
         if (this.isOnline) {
-            getContext().logger.info('Tab became visible with network available — emitting visibility_online');
+            this.runtime.logger.info('Tab became visible with network available — emitting visibility_online');
             this.emit('visibility_online');
         }
     };

package/dist/{SyncEngineContext.d.ts → RuntimeContext.d.ts}

@@ -1,17 +1,18 @@
 /**
- * SyncEngineContext — Runtime dependency container
+ * RuntimeContext — Runtime dependency container
  *
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
-import type { SyncLogger, SyncObservabilityProvider, SyncAnalytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, SyncEngineConfig } from './interfaces/index.js';
-export interface SyncEngineContext {
+import type { Logger, ObservabilityProvider, Analytics, SessionErrorDetector, OnlineStatusProvider, ModelDebugLoggerContract, MutationExecutor, RuntimeConfig } from './interfaces/index.js';
+import type { ModelMetadata } from './transaction/types/index.js';
+export interface RuntimeContext {
     /** Structured logger */
-    logger: SyncLogger;
+    logger: Logger;
     /** Error tracking & performance monitoring */
-    observability: SyncObservabilityProvider;
+    observability: ObservabilityProvider;
     /** Product analytics (optional) */
-    analytics?: SyncAnalytics;
+    analytics?: Analytics;
     /** Session error detection for auth redirect decisions */
     sessionErrorDetector: SessionErrorDetector;
     /** Network connectivity detection */
@@ -21,17 +22,23 @@ export interface SyncEngineContext {
     /** Backend mutation transport (GraphQL, REST, etc.) */
     mutationExecutor: MutationExecutor;
     /** Application-specific sync configuration */
-    config: SyncEngineConfig;
+    config: RuntimeConfig;
+    /**
+     * Model metadata lookup. Injected by the client (it wires this from its
+     * `ModelRegistry`) so the settlement core can resolve a model's metadata
+     * without importing the registry — the dependency inversion that keeps the
+     * core free of the client's `Model` layer (ADR 0013).
+     */
+    getModelMetadata: (name: string) => ModelMetadata | undefined;
 }
-/** No-op logger — silently discards all log calls */
-export declare const noopLogger: SyncLogger;
+export { noopLogger } from './transaction/logger.js';
 /** No-op observability — silently discards all observability calls */
-export declare const noopObservability: SyncObservabilityProvider;
+export declare const noopObservability: ObservabilityProvider;
 /** No-op analytics — silently discards all analytics calls */
-export declare const noopAnalytics: SyncAnalytics;
+export declare const noopAnalytics: Analytics;
 /** Browser-native online status provider */
 export declare const browserOnlineStatus: OnlineStatusProvider;
-/** Session error detector — delegates to SyncSessionError so detection is
+/** Session error detector — delegates to AbloSessionError so detection is
  *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export declare const defaultSessionErrorDetector: SessionErrorDetector;
 /**
@@ -42,4 +49,4 @@ export declare const defaultSessionErrorDetector: SessionErrorDetector;
  * never exercise FK ordering; consumers who do rely on it should finish
  * wiring the engine before the first `create()` fires.
  */
-export declare const emptyConfig: SyncEngineConfig;
+export declare const emptyConfig: RuntimeConfig;

package/dist/{SyncEngineContext.js → RuntimeContext.js}

@@ -1,27 +1,26 @@
 /**
- * SyncEngineContext — Runtime dependency container
+ * RuntimeContext — Runtime dependency container
  *
  * All SDK classes receive this context at construction time.
  * It bundles every injectable dependency so constructors stay clean.
  */
-import { SyncSessionError } from './errors.js';
+import { AbloSessionError } from './transaction/errors.js';
 // ─────────────────────────────────────────────
 // No-op defaults for optional dependencies
 // ─────────────────────────────────────────────
-/** No-op logger — silently discards all log calls */
-export const noopLogger = {
-    debug() { },
-    info() { },
-    warn() { },
-    error() { },
-};
+// Re-exported, not redeclared. `@ablo/transaction/logger` owns the no-op that
+// sits beside the `Logger` port. This package held a second, behaviourally
+// identical copy, and half of it imported the canonical one while the other
+// half imported this — so any change of semantics there would have reached
+// only one side, invisibly, because the identifier reads the same at both.
+export { noopLogger } from './transaction/logger.js';
 /** No-op observability — silently discards all observability calls */
 export const noopObservability = {
     setContext() { },
     setConnectionState() { },
     breadcrumb() { },
     captureRollback() { },
-    captureTransactionFailure() { },
+    captureMutationFailure() { },
     captureBootstrapFailure() { },
     captureReconciliation() { },
     captureDeltaRetryExhausted() { },
@@ -51,7 +50,7 @@ export const browserOnlineStatus = {
         return !(typeof navigator !== 'undefined' && navigator.onLine === false);
     },
 };
-/** Session error detector — delegates to SyncSessionError so detection is
+/** Session error detector — delegates to AbloSessionError so detection is
  *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
 export const defaultSessionErrorDetector = {
     isSessionError(error) {
@@ -61,7 +60,7 @@ export const defaultSessionErrorDetector = {
         return false;
     },
     isSessionErrorResponse(status, body) {
-        return SyncSessionError.isSessionErrorResponse(status, body);
+        return AbloSessionError.isSessionErrorResponse(status, body);
     },
 };
 /**

package/dist/SyncClient.d.ts

@@ -4,18 +4,21 @@
  * optimistic changes, holds them while the client is offline, sends them to
  * the server when connectivity returns, and resolves conflicts when the
  * server's version of a row disagrees with the local one. It sits between the
- * reactive object pool and the {@link TransactionQueue} that delivers writes
+ * reactive object pool and the {@link MutationQueue} that delivers writes
  * over the network.
  */
 import { InstanceCache } from './InstanceCache.js';
 import { Model } from './Model.js';
+import type { AppliedChange } from './transaction/plugin.js';
+import type { RuntimeContext } from './RuntimeContext.js';
 import { EventEmitter } from 'events';
-import { TransactionQueue } from './transactions/TransactionQueue.js';
-import { type UnconfirmedWritesMetrics } from './transactions/UnconfirmedWrites.js';
+import { MutationQueue } from './transactions/mutations/MutationQueue.js';
+import { type CommitLatencySample } from './transactions/mutations/commitLatency.js';
+import { type UnconfirmedWritesMetrics } from './transactions/mutations/UnconfirmedWrites.js';
 import type { Database } from './Database.js';
 import type { WriteOptions } from './interfaces/index.js';
-import { SyncPosition } from './sync/syncPosition.js';
-import type { DurableWriteStore } from './transactions/durableWriteStore.js';
+import { LogPosition } from './transaction/logPosition.js';
+import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.js';
 interface SyncObserver {
     onSync?: (event: SyncEvent) => void;
 }
@@ -41,6 +44,7 @@ export interface RehydrationStats {
     elapsedMs: number;
 }
 export declare class SyncClient extends EventEmitter {
+    private readonly runtime;
     private objectPool;
     private database;
     private get mutationExecutor();
@@ -71,12 +75,12 @@ export declare class SyncClient extends EventEmitter {
     private isDisposed;
     /**
      * The client's position in the global delta order, held as the single
-     * canonical {@link SyncPosition} instance. The store advances `applied` and
+     * canonical {@link LogPosition} instance. The store advances `applied` and
      * `persisted` as deltas land, the queue advances `acked` on commit
      * responses, and snapshots and claims read `readFloor`.
      */
-    readonly position: SyncPosition;
-    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: DurableWriteStore, commitOutboxNamespace?: string);
+    readonly position: LogPosition;
+    constructor(objectPool: InstanceCache, database: Database, commitOutbox?: DurableWriteStore, commitOutboxNamespace?: string, runtime?: RuntimeContext);
     /**
      * Setup network monitoring handlers
      */
@@ -98,13 +102,13 @@ export declare class SyncClient extends EventEmitter {
      *      discard the optimistic state silently.
      *
      * Treating both paths the same caused the deletion-flicker bug: every
-     * cancelled update on a multi-layer chart fired a per-model observer
+     * cancelled update on a multi-child record fired a per-model observer
      * event and a `[SyncClient.rollback]` warn, producing N renders and N
      * spam log lines for one user-initiated delete.
      */
     private setupTransactionRollbackHandling;
     /**
-     * Forward reconciliation requests from the {@link TransactionQueue} to the
+     * Forward reconciliation requests from the {@link MutationQueue} to the
      * sync layer. When delta confirmation times out, the queue emits
      * `reconciliation:needed` instead of rolling back, so optimistic state the
      * server may already have committed is never destroyed.
@@ -145,7 +149,7 @@ export declare class SyncClient extends EventEmitter {
      * 2. **Required-field gate** — if the row is missing any field listed
      *    in the model's `requiredFields`, return `null` so the caller
      *    skips this record. Used for FK columns whose absence renders the
-     *    row unrecoverable (e.g. a SlideLayer with no slideId).
+     *    row unrecoverable (e.g. a Block with no sectionId).
      *
      * The engine itself is product-neutral: model identity (which fields
      * to back-fill, which absences are fatal) lives entirely in the
@@ -196,10 +200,10 @@ export declare class SyncClient extends EventEmitter {
     /**
      * Update existing model with pre-computed changes.
      * Used by saveManyOptimized when incoming models have empty change-tracking
-     * (e.g. freshly constructed SpreadsheetCellModels from decomposeSpreadsheetDocument).
+     * (e.g. freshly constructed cell models from a bulk document decomposition).
      */
     updateWithChanges(model: Model, changes?: Record<string, unknown>): void;
-    /** Expose the GraphQL client for atomic mutations (e.g., createSlideWithLayers).
+    /** Expose the GraphQL client for atomic mutations (e.g., createSectionWithBlocks).
      *  Used by SyncedStore for operations that bypass the transaction queue
      *  but still need optimistic pool updates at the sync layer. */
     get gql(): import("./interfaces/index.js").MutationExecutor;
@@ -207,12 +211,12 @@ export declare class SyncClient extends EventEmitter {
     delete(model: Model, options?: WriteOptions): void;
     /**
      * Clear all pending mutations for a specific model
-     * Called before deletion to prevent "layer not found" errors on the server
+     * Called before deletion to prevent "record not found" errors on the server
      */
     private clearPendingMutationsForModel;
     /**
      * Upload a file and create its attachment record. The upload runs through
-     * the {@link TransactionQueue}, and a model is built from the server's
+     * the {@link MutationQueue}, and a model is built from the server's
      * response and added to the pool.
      */
     uploadFile(file: File, options: {
@@ -246,7 +250,7 @@ export declare class SyncClient extends EventEmitter {
      * IndexedDB persistence and the server push are deferred to a microtask, so
      * many pushes within the same tick collapse into a single serialization and
      * a single process call. Without the deferral, queueing a hundred mutations
-     * at once — a large paste, a document import, bulk layer creation — would
+     * at once — a large paste, a document import, bulk row creation — would
      * reserialize the whole growing queue a hundred times, an O(N²) cost in
      * `model.toJSON()`.
      *
@@ -275,11 +279,11 @@ export declare class SyncClient extends EventEmitter {
      *
      * Best Practice: Only sync models that still exist locally (local-first principle)
      * - If a model was deleted locally → skip any pending updates/creates for it
-     * - This prevents "layer not found" errors from fast copy-paste-delete workflows
+     * - This prevents "record not found" errors from fast copy-paste-delete workflows
      */
     processPendingMutations(): Promise<void>;
     /**
-     * Stage mutation to TransactionQueue - mutations in same tick are batched via microtask
+     * Stage mutation to MutationQueue - mutations in same tick are batched via microtask
      *
      * @param mutation.capturedChanges - Pre-captured changes to use instead of re-reading from model
      */
@@ -347,7 +351,7 @@ export declare class SyncClient extends EventEmitter {
      */
     dispose(): void;
     /**
-     * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
+     * Notify the {@link MutationQueue} of an incoming delta so it can confirm
      * hosted writes by sync-id threshold and queued forwards by their echoed
      * source-batch correlation id.
      * @param syncId - The sync id of the received delta.
@@ -360,15 +364,15 @@ export declare class SyncClient extends EventEmitter {
      * deletion. The store calls this when a delete delta arrives for a parent,
      * cancelling any queued writes on children that reference it.
      *
-     * @param childModelName - The child model type (for example, `SlideLayer`).
-     * @param foreignKey - The foreign-key property name (for example, `slideId`).
+     * @param childModelName - The child model type (for example, `Block`).
+     * @param foreignKey - The foreign-key property name (for example, `sectionId`).
      * @param parentId - The id of the deleted parent.
      * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName: string, foreignKey: string, parentId: string): number;
     /**
      * Wait for a transaction to be confirmed by its delta echo. Delegates to the
-     * {@link TransactionQueue}, which handles the confirmation timeout.
+     * {@link MutationQueue}, which handles the confirmation timeout.
      */
     waitForDeltaConfirmation(transactionId: string): Promise<void>;
     /**
@@ -386,7 +390,7 @@ export declare class SyncClient extends EventEmitter {
         objectPoolStats: ReturnType<InstanceCache['getStats']>;
     };
     /**
-     * Get pending transaction count from TransactionQueue
+     * Get pending transaction count from MutationQueue
      * Used by SyncedStore to compute hasUnsyncedChanges
      */
     getPendingTransactionCount(): number;
@@ -397,7 +401,7 @@ export declare class SyncClient extends EventEmitter {
     onTransactionEvent(event: 'created' | 'completed' | 'failed', callback: () => void): () => void;
     /**
      * Subscribe to mutation failures with the full payload. Mirrors the
-     * underlying TransactionQueue 'transaction:failed' shape so consumers
+     * underlying MutationQueue 'transaction:failed' shape so consumers
      * can render typed UI (toast keyed by `AbloError.type`, route-level
      * "this entity reverted" boundaries, telemetry).
      *
@@ -407,28 +411,37 @@ export declare class SyncClient extends EventEmitter {
      * this typed listener drives user-visible surfaces.
      */
     onMutationFailure(listener: (payload: {
-        transaction: import('./transactions/TransactionQueue.js').Transaction;
+        transaction: import('./transactions/mutations/MutationQueue.js').QueuedMutation;
         error: Error;
         permanent?: boolean;
     }) => void): () => void;
     /**
-     * Subscribe to local transaction creation with the full {@link Transaction}
+     * Subscribe to commit round-trip latency, split into the local seal and the
+     * remote acknowledgement. Fires once per completed commit.
+     *
+     * Taps the {@link MutationQueue} emitter for the same reason
+     * {@link onMutationFailure} does: the commit lifecycle events originate
+     * there and the SyncClient's own emitter never rebroadcasts them.
+     */
+    onCommitLatency(listener: (sample: CommitLatencySample) => void): () => void;
+    /**
+     * Subscribe to local transaction creation with the full {@link QueuedMutation}
      * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
      * the feed the store's local-mutation subscription taps for undo recording.
      *
-     * It subscribes to the {@link TransactionQueue}'s emitter directly, since
+     * It subscribes to the {@link MutationQueue}'s emitter directly, since
      * that is the only emitter that fires `transaction:created`. The SyncClient's
      * own emitter (reached through {@link subscribe}) never rebroadcasts that
      * event, so routing undo through `subscribe('transaction:created')` would
      * record nothing. {@link onMutationFailure} taps the queue for the same
      * reason.
      */
-    onLocalTransaction(listener: (tx: import('./transactions/TransactionQueue.js').Transaction) => void): () => void;
+    onLocalTransaction(listener: (tx: import('./transactions/mutations/MutationQueue.js').QueuedMutation) => void): () => void;
     /**
      * Wait for the latest in-flight transaction for (modelName, modelId)
      * to be confirmed by the server, or reject if it's rolled back.
      * Resolves immediately when no transaction is in flight — see
-     * `TransactionQueue.confirmationFor` for the lookup contract.
+     * `MutationQueue.confirmationFor` for the lookup contract.
      *
      * Distinct from `waitForDeltaConfirmation(transactionId)` which keys
      * off a known tx id; this variant is for call sites that hold a
@@ -441,7 +454,7 @@ export declare class SyncClient extends EventEmitter {
     getDebugInfo(): {
         connectionState: "connected" | "disconnected" | "connecting";
         pendingMutationsCount: number;
-        transactionQueue: {
+        mutationQueue: {
             lastSeenSyncId: number;
             awaitingDeltaCount: number;
             awaitingDeltaTransactions: {
@@ -478,7 +491,7 @@ export declare class SyncClient extends EventEmitter {
      * Mark a local transaction as optimistically applied. The matching
      * server delta (when it arrives with the same `transactionId`) will
      * be recognized as an echo and skip the pool mutation. Called
-     * automatically by `TransactionQueue` when a transaction is staged;
+     * automatically by `MutationQueue` when a transaction is staged;
      * exposed publicly so tests can drive the API directly.
      */
     markTransactionPending(transactionId: string): void;
@@ -490,28 +503,15 @@ export declare class SyncClient extends EventEmitter {
      */
     getEchoMetrics(): Readonly<UnconfirmedWritesMetrics>;
     /**
-     * Package-internal accessor for the {@link TransactionQueue}. Used by
+     * Package-internal accessor for the {@link MutationQueue}. Used by
      * `Ablo.commits.create()` to route raw multi-operation envelopes through the
      * same retry-on-reconnect lane as the model proxy path, and by tests to
      * exercise the queue's interaction with {@link markTransactionPending} on the
      * real instance the SyncClient subscribes to. It is not re-exported to SDK
      * consumers; `Ablo` is the public surface.
      */
-    getTransactionQueue(): TransactionQueue;
-    applyDeltaBatchToPool(dbResults: {
-        action: string;
-        modelName: string;
-        modelId: string;
-        data?: Record<string, unknown> | null;
-        /**
-         * Server-stamped transaction id, echoing the client's commit op
-         * id. Used by echo detection to recognize "this is the
-         * confirmation of a mutation I've already applied locally."
-         * Optional because system-emitted deltas (sync_group changes,
-         * schema-derived deltas, etc.) don't have a client transaction.
-         */
-        transactionId?: string;
-    }[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
+    getMutationQueue(): MutationQueue;
+    applyDeltaBatchToPool(dbResults: readonly AppliedChange[], enrichRelations: (modelName: string, data: Record<string, unknown>) => Record<string, unknown>): void;
     /**
      * Apply bootstrap data to the InstanceCache with ghost removal.
      * Owns: model creation, batch upsert, ghost detection + removal.