@abloatai/ablo 0.34.1 → 0.36.0

package/dist/InstanceCache.js

@@ -9,11 +9,11 @@
 import { makeObservable, observable, action, computed, runInAction } from 'mobx';
 import { Model } from './Model.js';
 import { ModelRegistry } from './ModelRegistry.js';
-import { getContext } from './context.js';
-import { AbloValidationError } from './errors.js';
-import { ModelScope } from './types/index.js';
-import { ViewRegistry } from './core/ViewRegistry.js';
-import { QueryView } from './core/QueryView.js';
+import { globalRuntime } from './context.js';
+import { AbloValidationError } from './transaction/errors.js';
+import { ModelScope } from './transaction/types/index.js';
+import { ViewRegistry } from './views/ViewRegistry.js';
+import { QueryView } from './views/QueryView.js';
 // Re-exported so `import { ModelScope } from './InstanceCache.js'` resolves
 export { ModelScope };
 /**
@@ -36,7 +36,7 @@ export class InstanceCache {
     // reactivity source; there are no computed getters with conditional cache
     // invalidation to get wrong.
     // Foreign key indexes: Map<"ModelType:fieldName", Map<fieldValue, ObservableSet<modelId>>>
-    // Enables O(1) lookups like "all SlideLayer models where slideId = X"
+    // Enables O(1) lookups like "all Block models where sectionId = X"
     // instead of scanning all models of a type and filtering.
     foreignKeyIndexes = new Map();
     // Registry of which fields to index: Map<modelName, fieldName[]>
@@ -51,6 +51,7 @@ export class InstanceCache {
     };
     // Configuration
     config;
+    runtime;
     gcTimer;
     // ModelRegistry instance — single source of truth for model metadata
     registry;
@@ -106,6 +107,7 @@ export class InstanceCache {
             gcInterval: config.gcInterval ?? 60000, // 1 minute
             useWeakRefs: config.useWeakRefs ?? true,
         };
+        this.runtime = config.runtime ?? globalRuntime;
         // Store the model registry reference
         if (!modelRegistry) {
             throw new AbloValidationError('InstanceCache requires ModelRegistry for production-safe model name lookup', { code: 'pool_registry_missing' });
@@ -187,6 +189,39 @@ export class InstanceCache {
         this.metrics.hits++;
         return model ?? undefined;
     }
+    /**
+     * Look a row up **within one model**.
+     *
+     * The pool is a single id space: `get(id)` returns whatever row carries that
+     * id, whatever model it belongs to. That is the correct storage shape — ids
+     * are globally unique, the same premise as Relay's Global Object
+     * Identification — but it means an *untyped* lookup cannot stand in for a
+     * typed one. Apollo and EmberData avoid the question by keying their identity
+     * maps on `Type:id`; with unique ids the equivalent guarantee comes from
+     * stating the expected model at the lookup instead.
+     *
+     * Returns `undefined` for a row belonging to another model: from the asking
+     * model's perspective that id is simply absent. Callers that must tell "not
+     * here" apart from "here, but another model's" should compare against
+     * {@link get}.
+     *
+     * Prefer this over `get()` anywhere the caller knows which model it wants —
+     * `get()` returning another model's row has caused three product bugs, most
+     * recently a resize gesture that reverted after every commit.
+     */
+    // `T` appears only in the return position, which is normally a caller-chosen
+    // cast in disguise. It is sound here precisely because `modelName` is checked
+    // at runtime below before the row is handed back, so the caller's expected
+    // type and the row's registered identity cannot disagree.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+    getOfType(id, modelName) {
+        const model = this.get(id);
+        if (!model)
+            return undefined;
+        // Checked, so the assertion below is sound: `typeIndex` and
+        // `getModelName()` are the same registered-name identity.
+        return model.getModelName() === modelName ? model : undefined;
+    }
     /**
      * Add model with deduplication support
      */
@@ -231,7 +266,7 @@ export class InstanceCache {
                     (history.lastAction === 'U' || history.lastAction === 'D')) {
                     // Internal delta-ordering anomaly that reconciles on the next
                     // catch-up — forensic, not consumer-actionable → debug.
-                    getContext().logger.debug(`InstanceCache.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
+                    this.runtime.logger.debug(`InstanceCache.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
                 }
             }
             // Update delta history
@@ -341,13 +376,13 @@ export class InstanceCache {
             this.addToTypeIndex(id, modelType);
             // Populate the foreign-key indexes. The single-item `add()` path
             // does this; `addBatch()` used to skip it, which meant every
-            // layer / sheet cell / message that came in through a bulk
-            // loader (`ensureDeckLayers`, `prefetchSlideLayers`, bootstrap
+            // block / ledger cell / message that came in through a bulk
+            // loader (`ensureReportBlocks`, `prefetchSectionBlocks`, bootstrap
             // hydration) was in the pool but invisible to `hasMany` lookups
-            // — `slide.layers` returned `[]` until the user clicked a layer
+            // — `section.blocks` returned `[]` until the user clicked a block
             // and something else ran a non-batch `add` that happened to
             // populate the FK index as a side effect. The UX symptom was
-            // "slides show empty until you click on one." Adding this one
+            // "sections show empty until you click on one." Adding this one
             // line closes the gap.
             this.addToForeignKeyIndex(id, model, modelType);
             this.metrics.additions++;
@@ -461,7 +496,7 @@ export class InstanceCache {
         // FK cleanup silently no-ops — leaving ghost ids in the FK index.
         // That causes `getByForeignKey(..., parentId)` to report
         // `matched > returned` (dropped-no-entry) and, on the UI, keeps the
-        // stale layer visible until the next reload rebuilds the index
+        // stale block visible until the next reload rebuilds the index
         // from fresh data. Do the FK/type cleanup first, then delete the
         // entry.
         runInAction(() => {
@@ -506,7 +541,7 @@ export class InstanceCache {
                     // This is expected during migration from hand-coded → dynamic models.
                 }
                 catch (e) {
-                    getContext().observability.breadcrumb(`Failed to create fallback instance for ${modelClass.name}`, 'sync.database', 'error', {
+                    this.runtime.observability.breadcrumb(`Failed to create fallback instance for ${modelClass.name}`, 'sync.database', 'error', {
                         error: e instanceof Error ? e.message : String(e),
                     });
                     return [];
@@ -598,7 +633,7 @@ export class InstanceCache {
      * data. Cleaner than `createFromData({ __typename, ...data })` — the
      * typename lives in the arg list, not hidden inside the data object.
      *
-     * Used for optimistic local writes: `pool.create('Slide', { id, deckId, ... })`.
+     * Used for optimistic local writes: `pool.create('Section', { id, reportId, ... })`.
      * For hydration from server deltas (where `__typename` already rides on
      * the payload), use `createFromData(data)` directly — that path is kept
      * because the wire format attaches the discriminator to the data itself.
@@ -614,8 +649,8 @@ export class InstanceCache {
             if (modelName === 'Unknown') {
                 // Malformed row with no type marker — dropped, but nothing the consumer
                 // can act on (the actionable schema-drift case is handled below) → debug.
-                getContext().logger.debug('InstanceCache.createFromData: No model identifier found', { data });
-                getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
+                this.runtime.logger.debug('InstanceCache.createFromData: No model identifier found', { data });
+                this.runtime.modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
             if (opts?.strict) {
@@ -628,9 +663,9 @@ export class InstanceCache {
             // Genuinely actionable and NOT self-healing: a model the server is sending
             // isn't in your schema, so these rows are silently skipped. Keep at warn,
             // consumer register (their model name + the `ablo status` fix); forensics ride debug.
-            getContext().logger.warn(`Received data for "${modelName}", which isn't in your schema — these rows will be skipped. Run \`ablo status\` to compare your local schema with the server.`);
-            getContext().logger.debug(`InstanceCache.createFromData: No constructor found for model "${modelName}"`, { data });
-            getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
+            this.runtime.logger.warn(`Received data for "${modelName}", which isn't in your schema — these rows will be skipped. Run \`ablo status\` to compare your local schema with the server.`);
+            this.runtime.logger.debug(`InstanceCache.createFromData: No constructor found for model "${modelName}"`, { data });
+            this.runtime.modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;
         }
         // If the model already exists, update it in place instead of creating a
@@ -643,11 +678,11 @@ export class InstanceCache {
                 existing.updateFromData(data);
                 return existing;
             }
-            // Different type with same ID - this is a shared PK scenario (e.g., Project/Dataroom)
+            // Different type with same ID - this is a shared PK scenario (e.g., two models sharing one row id)
             // Don't return existing, create new model (will use composite key for storage)
         }
         // Log model creation attempt
-        getContext().modelDebugLogger?.logCreation(modelName, data, Constructor);
+        this.runtime.modelDebugLogger?.logCreation(modelName, data, Constructor);
         try {
             // Pass data directly to constructor for Prisma-first models
             const model = new Constructor(data);
@@ -657,14 +692,14 @@ export class InstanceCache {
             const errorMessage = error instanceof Error ? error.message : String(error);
             // Internal construction failure — captured via observability below and
             // re-fetched on resync; the stack is forensic → debug.
-            getContext().logger.debug(`[InstanceCache.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
-            getContext().observability.captureTransactionFailure({
+            this.runtime.logger.debug(`[InstanceCache.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
+            this.runtime.observability.captureMutationFailure({
                 context: 'createFromData',
                 modelName,
                 modelId: data.id,
                 error: errorMessage,
             });
-            getContext().modelDebugLogger?.logError(modelName, 'CREATE', errorMessage, {
+            this.runtime.modelDebugLogger?.logError(modelName, 'CREATE', errorMessage, {
                 data,
                 constructor: Constructor.name,
             });
@@ -849,7 +884,7 @@ export class InstanceCache {
                 // caused silent data loss — any model actively being rendered
                 // through a schema-driven dynamic class (i.e., most of them)
                 // would be demoted, collected, and the next render's
-                // `weakRef.deref()` returned undefined, so layers / cells /
+                // `weakRef.deref()` returned undefined, so blocks / cells /
                 // messages "disappeared" after ~10 min of idle.
                 //
                 // The `hasObservedCollections()` guard used by the eviction
@@ -871,7 +906,7 @@ export class InstanceCache {
                 }
             }
             if (skippedObserved > 0) {
-                getContext().logger.debug(`[InstanceCache GC] Skipped ${skippedObserved} models with active React observers`);
+                this.runtime.logger.debug(`[InstanceCache GC] Skipped ${skippedObserved} models with active React observers`);
             }
             // Also clean up old tracking data
             this.clearDeltaHistory();
@@ -934,8 +969,8 @@ export class InstanceCache {
      * Register a foreign key field for indexing on a model type.
      * Call once during app initialization (e.g., after model registration).
      *
-     * Example: registerForeignKey('SlideLayer', 'slideId')
-     * This enables getByForeignKey('SlideLayer', 'slideId', someSlideId) → O(1) lookup
+     * Example: registerForeignKey('Block', 'sectionId')
+     * This enables getByForeignKey('Block', 'sectionId', someSectionId) → O(1) lookup
      */
     registerForeignKey(modelName, fieldName) {
         const fields = this.foreignKeyConfig.get(modelName) ?? [];
@@ -977,7 +1012,7 @@ export class InstanceCache {
         // entry for this specific parent id (entity genuinely has no
         // children). These used to `console.warn` diagnostic dumps on every
         // call, which turned into hundreds of log lines per second during
-        // cursor hover / rapid re-renders on the deck page. If a caller
+        // cursor hover / rapid re-renders on a busy page. If a caller
         // needs visibility into "why is this empty," wire an opt-in
         // `logger.debug` at the specific call site rather than re-adding
         // a blanket warn here.
@@ -1013,7 +1048,7 @@ export class InstanceCache {
             // has dangling refs (legacy orphan deltas, pending CREATE
             // transactions, etc.). Noisy at warn level, useful during
             // investigation.
-            getContext().logger.debug('[InstanceCache.getByForeignKey] ROWS DROPPED', {
+            this.runtime.logger.debug('[InstanceCache.getByForeignKey] ROWS DROPPED', {
                 modelName,
                 fieldName,
                 fieldValue,

package/dist/LazyReferenceCollection.d.ts

@@ -86,9 +86,9 @@ export declare class LazyReferenceCollection<T extends Model> {
      * so any pool.remove invalidates the computed and re-renders the
      * consumer with the deleted item gone.
      *
-     * Without this, deleting a slide layer would pool.remove() cleanly
-     * but the canvas — which reads `slide.layers.value` — would keep
-     * showing the deleted layer until a full reload rebuilt the
+     * Without this, deleting a block would pool.remove() cleanly
+     * but the view — which reads `section.blocks.value` — would keep
+     * showing the deleted block until a full reload rebuilt the
      * collection.
      */
     get value(): T[];

package/dist/LazyReferenceCollection.js

@@ -7,7 +7,7 @@ import { makeObservable, observable, action, computed, onBecomeObserved, onBecom
 import { Database } from './Database.js';
 import { InstanceCache } from './InstanceCache.js';
 import { getActiveRegistry } from './ModelRegistry.js';
-import { AbloValidationError } from './errors.js';
+import { AbloValidationError } from './transaction/errors.js';
 /**
  * A lazy-loaded one-to-many relationship between a parent {@link Model} and
  * its children. It reads from the local store first and falls back to the
@@ -136,9 +136,9 @@ export class LazyReferenceCollection {
      * so any pool.remove invalidates the computed and re-renders the
      * consumer with the deleted item gone.
      *
-     * Without this, deleting a slide layer would pool.remove() cleanly
-     * but the canvas — which reads `slide.layers.value` — would keep
-     * showing the deleted layer until a full reload rebuilt the
+     * Without this, deleting a block would pool.remove() cleanly
+     * but the view — which reads `section.blocks.value` — would keep
+     * showing the deleted block until a full reload rebuilt the
      * collection.
      */
     get value() {

package/dist/Model.d.ts

@@ -120,10 +120,10 @@ export declare abstract class Model {
      * narrow the return to their concrete store type.
      *
      * @example
-     *   // In a Slide model getter
-     *   const store = Slide.getStore();
+     *   // In a Section model getter
+     *   const store = Section.getStore();
      *   if (!store) return [];
-     *   return store.getByForeignKey<SlideLayer>('SlideLayer', 'slideId', this.id);
+     *   return store.getByForeignKey<Block>('Block', 'sectionId', this.id);
      */
     static getStore<T extends SyncStoreRef = SyncStoreRef>(): T | null;
     /**
@@ -159,7 +159,7 @@ export declare abstract class Model {
      *
      * This per-instance baseline is needed because application code can edit a
      * model in two ways that coexist: a direct property write
-     * (`slide.title = 'foo'`) and a recorded mutation. A design in which every
+     * (`section.title = 'foo'`) and a recorded mutation. A design in which every
      * write went through a single recorded path would not need it, since the
      * last acknowledged state would already be the authoritative baseline.
      */
@@ -172,8 +172,8 @@ export declare abstract class Model {
      * Capture a before-image for `keys` — the single source of truth for the
      * "previous value" that undo inverses are built from. Both undo paths call
      * this so they can never drift: the stream path
-     * (`TransactionQueue.extractPreviousData`) and the manual-record path
-     * (`RecordingTransaction.snapshotFields`).
+     * (`MutationQueue.extractPreviousData`) and the manual-record path
+     * (`RecordingMutation.snapshotFields`).
      *
      * Resolution order per key:
      *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
@@ -246,9 +246,16 @@ export declare abstract class Model {
      * written, `onWrite(key, oldValue, newValue)` is invoked with the value
      * captured immediately before assignment. `applyChanges` passes a hook
      * that records the change in `modifiedProperties`; `updateFromData`
-     * passes none (hydration must not generate outbound mutations). This
-     * is the single source of mutation tracking now that the `mobx-setup`
-     * `observe()` bridge has been removed (one write path: the SDK proxy).
+     * passes none (hydration must not generate outbound mutations).
+     *
+     * This is not the ONLY tracking path. `mobxSetup`'s `observe()` bridge is
+     * live and forwards a DIRECT assignment (`layer.position = next`) to
+     * `propertyChanged` as well — product code writes model fields directly in
+     * plenty of places (keyboard nudge, formatting, AI tools), and those writes
+     * have to reach the server and the undo stream too. The two paths compose:
+     * a direct write establishes the first-old-wins baseline, and a later
+     * `applyChanges` carrying the value the model already holds is a no-op that
+     * leaves that baseline intact.
      */
     private assignFieldsFromData;
     /**
@@ -260,10 +267,13 @@ export declare abstract class Model {
      * brand-new outbound mutation and the record would echo forever. For a
      * local user edit, use `applyChanges` instead.
      *
-     * Suppression is belt-and-suspenders: we pass no `onWrite` hook AND
-     * clear/restore `modifiedProperties` around the assignment, so any
-     * remaining `mobx-setup` `observe()` side-channel writes are discarded
-     * too. (The clear/restore is a harmless no-op once that bridge is gone.)
+     * Suppression takes two forms and BOTH are load-bearing: we pass no
+     * `onWrite` hook, and we clear/restore `modifiedProperties` around the
+     * assignment. The second is what catches `mobxSetup`'s `observe()` bridge,
+     * which fires on the assignment itself and would otherwise record an
+     * inbound delta as a local edit — queueing an outbound mutation that echoes
+     * forever, and putting a collaborator's change on your undo stack. Do not
+     * remove it while that bridge exists (`mobxSetup.M1`).
      */
     updateFromData(data: ModelData): void;
     /**

package/dist/Model.js

@@ -11,7 +11,7 @@ import { v4 as uuid } from 'uuid';
 import { M1 } from './utils/mobxSetup.js';
 import { getActiveRegistry, hasActiveRegistry } from './ModelRegistry.js';
 import { getContext } from './context.js';
-import { AbloValidationError } from './errors.js';
+import { AbloValidationError } from './transaction/errors.js';
 /**
  * Validation error for model validation failures
  */
@@ -78,7 +78,7 @@ export class Model {
         // A record that arrives WITH `createdAt` but WITHOUT `updatedAt` is
         // server/IDB data whose update timestamp didn't survive the wire —
         // falling back to "now" here fabricated an edit time for every such
-        // record on every bootstrap (the decks gallery sorted everything to
+        // record on every bootstrap (the reports gallery sorted everything to
         // "edited just now"). Fall back to createdAt instead; only a genuinely
         // new local model (no dates at all) stamps the current time.
         this.updatedAt = data.updatedAt
@@ -113,10 +113,10 @@ export class Model {
      * narrow the return to their concrete store type.
      *
      * @example
-     *   // In a Slide model getter
-     *   const store = Slide.getStore();
+     *   // In a Section model getter
+     *   const store = Section.getStore();
      *   if (!store) return [];
-     *   return store.getByForeignKey<SlideLayer>('SlideLayer', 'slideId', this.id);
+     *   return store.getByForeignKey<Block>('Block', 'sectionId', this.id);
      */
     static getStore() {
         return Model.store;
@@ -142,9 +142,9 @@ export class Model {
             // Preserve the earliest captured `old` for this field until the entry
             // is cleared (by `clearChanges` on sync-ack or by a mutator consuming
             // it). Consecutive in-place mutations between mutator invocations —
-            // e.g. a drag loop writing `layer.position = ...` on every frame —
+            // e.g. a drag loop writing `block.position = ...` on every frame —
             // would otherwise overwrite `.old` with each frame's predecessor,
-            // destroying the pre-session baseline that `RecordingTransaction`
+            // destroying the pre-session baseline that `RecordingMutation`
             // relies on to record a correct undo inverse. `.new` always reflects
             // the latest value so the transaction queue's `getChanges()` keeps
             // sending the right payload to the server.
@@ -194,7 +194,7 @@ export class Model {
      *
      * This per-instance baseline is needed because application code can edit a
      * model in two ways that coexist: a direct property write
-     * (`slide.title = 'foo'`) and a recorded mutation. A design in which every
+     * (`section.title = 'foo'`) and a recorded mutation. A design in which every
      * write went through a single recorded path would not need it, since the
      * last acknowledged state would already be the authoritative baseline.
      */
@@ -214,8 +214,8 @@ export class Model {
      * Capture a before-image for `keys` — the single source of truth for the
      * "previous value" that undo inverses are built from. Both undo paths call
      * this so they can never drift: the stream path
-     * (`TransactionQueue.extractPreviousData`) and the manual-record path
-     * (`RecordingTransaction.snapshotFields`).
+     * (`MutationQueue.extractPreviousData`) and the manual-record path
+     * (`RecordingMutation.snapshotFields`).
      *
      * Resolution order per key:
      *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
@@ -428,9 +428,16 @@ export class Model {
      * written, `onWrite(key, oldValue, newValue)` is invoked with the value
      * captured immediately before assignment. `applyChanges` passes a hook
      * that records the change in `modifiedProperties`; `updateFromData`
-     * passes none (hydration must not generate outbound mutations). This
-     * is the single source of mutation tracking now that the `mobx-setup`
-     * `observe()` bridge has been removed (one write path: the SDK proxy).
+     * passes none (hydration must not generate outbound mutations).
+     *
+     * This is not the ONLY tracking path. `mobxSetup`'s `observe()` bridge is
+     * live and forwards a DIRECT assignment (`layer.position = next`) to
+     * `propertyChanged` as well — product code writes model fields directly in
+     * plenty of places (keyboard nudge, formatting, AI tools), and those writes
+     * have to reach the server and the undo stream too. The two paths compose:
+     * a direct write establishes the first-old-wins baseline, and a later
+     * `applyChanges` carrying the value the model already holds is a no-op that
+     * leaves that baseline intact.
      */
     assignFieldsFromData(data, onWrite) {
         // Update properties with safety checks for read-only/computed accessors
@@ -489,10 +496,13 @@ export class Model {
      * brand-new outbound mutation and the record would echo forever. For a
      * local user edit, use `applyChanges` instead.
      *
-     * Suppression is belt-and-suspenders: we pass no `onWrite` hook AND
-     * clear/restore `modifiedProperties` around the assignment, so any
-     * remaining `mobx-setup` `observe()` side-channel writes are discarded
-     * too. (The clear/restore is a harmless no-op once that bridge is gone.)
+     * Suppression takes two forms and BOTH are load-bearing: we pass no
+     * `onWrite` hook, and we clear/restore `modifiedProperties` around the
+     * assignment. The second is what catches `mobxSetup`'s `observe()` bridge,
+     * which fires on the assignment itself and would otherwise record an
+     * inbound delta as a local edit — queueing an outbound mutation that echoes
+     * forever, and putting a collaborator's change on your undo stack. Do not
+     * remove it while that bridge exists (`mobxSetup.M1`).
      */
     updateFromData(data) {
         if (this.isDisposed) {

package/dist/ModelRegistry.d.ts

@@ -7,7 +7,8 @@
  * classes. References resolve lazily, so a model may declare a reference to
  * another model that is registered later.
  */
-import { type ModelMetadata, type PropertyMetadata, type ReferenceMetadata, LoadStrategy } from './types/index.js';
+import { type ModelMetadata, type PropertyMetadata, type ReferenceMetadata, LoadStrategy } from './transaction/types/index.js';
+import type { RuntimeContext } from './RuntimeContext.js';
 import type { Model } from './Model.js';
 import type { ConcreteModelConstructor } from './BaseSyncedStore.js';
 /**
@@ -51,9 +52,9 @@ export interface SerializedReferenceMetadata extends Omit<ExtendedReferenceMetad
  * child's pending transactions can be cancelled.
  */
 export interface BackReferenceMetadata {
-    /** The parent model name (e.g., 'SlideDeck') */
+    /** The parent model name (e.g., 'Report') */
     parentModel: string;
-    /** The foreign key property on this model (e.g., 'deckId') */
+    /** The foreign key property on this model (e.g., 'reportId') */
     foreignKey: string;
     /** Whether to cascade-cancel transactions when parent is deleted */
     cascadeDelete: boolean;
@@ -61,6 +62,8 @@ export interface BackReferenceMetadata {
 interface RegistryConfig {
     validateOnRegister?: boolean;
     allowLateReferences?: boolean;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
 }
 /** Set the active ModelRegistry instance (called by createSyncEngine) */
 export declare function setActiveRegistry(registry: ModelRegistry): void;
@@ -80,6 +83,7 @@ export declare class ModelRegistry {
     private backReferences;
     private schemaHash?;
     private config;
+    private readonly runtime;
     private registeredModels;
     private pendingHashUpdate;
     constructor(config?: RegistryConfig);
@@ -107,7 +111,7 @@ export declare class ModelRegistry {
      * transactions for every child model that declares a back-reference to that
      * parent.
      *
-     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Slide')
+     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Section')
      * @param metadata - The back-reference configuration
      */
     registerBackReference(childModelName: string, metadata: BackReferenceMetadata): void;

package/dist/ModelRegistry.js

@@ -8,9 +8,9 @@
  * another model that is registered later.
  */
 // Removed Node.js crypto import for browser compatibility
-import { PropertyType, LoadStrategy, } from './types/index.js';
-import { getContext } from './context.js';
-import { AbloValidationError } from './errors.js';
+import { PropertyType, LoadStrategy, } from './transaction/types/index.js';
+import { globalRuntime } from './context.js';
+import { AbloValidationError } from './transaction/errors.js';
 /**
  * Module-level active registry. Set by createSyncEngine so that Model instances
  * (which don't receive DI) can look up metadata without static maps.
@@ -51,6 +51,7 @@ export class ModelRegistry {
     backReferences = new Map();
     schemaHash;
     config;
+    runtime;
     registeredModels = new Set();
     pendingHashUpdate = false;
     constructor(config = {}) {
@@ -58,6 +59,7 @@ export class ModelRegistry {
             validateOnRegister: config.validateOnRegister ?? true,
             allowLateReferences: config.allowLateReferences ?? true,
         };
+        this.runtime = config.runtime ?? globalRuntime;
     }
     validateModelConstructor(name, constructor) {
         if (typeof constructor !== 'function') {
@@ -71,7 +73,7 @@ export class ModelRegistry {
         const required = ['updateFromData', 'toJSON', 'getModelName'];
         for (const method of required) {
             if (typeof prototype[method] !== 'function') {
-                getContext().logger.debug('Model missing required method', name, { method });
+                this.runtime.logger.debug('Model missing required method', name, { method });
             }
         }
     }
@@ -99,7 +101,7 @@ export class ModelRegistry {
             this.pendingReferences.set(targetName, pending);
         }
         pending.push({ modelName, propertyName, metadata });
-        getContext().logger.debug('Reference deferred', `${modelName}.${propertyName}`, { targetModel: targetName });
+        this.runtime.logger.debug('Reference deferred', `${modelName}.${propertyName}`, { targetModel: targetName });
     }
     resolvePendingReferences(targetModelName) {
         const pending = this.pendingReferences.get(targetModelName);
@@ -108,12 +110,12 @@ export class ModelRegistry {
         for (const ref of pending) {
             try {
                 this.completeReferenceRegistration(ref.modelName, ref.propertyName, ref.metadata);
-                getContext().logger.debug('Reference resolved', `${ref.modelName}.${ref.propertyName}`, {
+                this.runtime.logger.debug('Reference resolved', `${ref.modelName}.${ref.propertyName}`, {
                     targetModel: targetModelName,
                 });
             }
             catch (error) {
-                getContext().observability.breadcrumb(`Failed to resolve reference ${ref.modelName}.${ref.propertyName}`, 'sync.database', 'error', {
+                this.runtime.observability.breadcrumb(`Failed to resolve reference ${ref.modelName}.${ref.propertyName}`, 'sync.database', 'error', {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
@@ -154,10 +156,10 @@ export class ModelRegistry {
         }
         // Check for duplicate
         if (this.models.has(name)) {
-            getContext().logger.debug('Model already registered, skipping', name);
+            this.runtime.logger.debug('Model already registered, skipping', name);
             return;
         }
-        getContext().logger.debug('Registering model', name);
+        this.runtime.logger.debug('Registering model', name);
         // Register. The one cast in this file: input is any Model-subclass
         // constructor (validated above); registered classes are concrete
         // subclasses constructible with `data?` and carrying Model's statics —
@@ -180,7 +182,7 @@ export class ModelRegistry {
         this.resolvePendingReferences(name);
         // Invalidate schema hash
         this.schemaHash = undefined;
-        getContext().logger.debug('Model registered', name, metadata);
+        this.runtime.logger.debug('Model registered', name, metadata);
     }
     /**
      * Register property with validation
@@ -201,7 +203,7 @@ export class ModelRegistry {
         if (existing) {
             if (this.arePropertiesCompatible(existing, metadata)) {
                 // Properties are compatible, skip re-registration
-                getContext().logger.debug('Property already registered (compatible)', `${modelName}.${propertyName}`);
+                this.runtime.logger.debug('Property already registered (compatible)', `${modelName}.${propertyName}`);
                 return;
             }
             else {
@@ -210,7 +212,7 @@ export class ModelRegistry {
         }
         props.set(propertyName, metadata);
         this.schemaHash = undefined;
-        getContext().logger.debug('Property registered', `${modelName}.${propertyName}`, metadata);
+        this.runtime.logger.debug('Property registered', `${modelName}.${propertyName}`, metadata);
     }
     /**
      * Register reference with lazy resolution
@@ -248,7 +250,7 @@ export class ModelRegistry {
      * transactions for every child model that declares a back-reference to that
      * parent.
      *
-     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Slide')
+     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Section')
      * @param metadata - The back-reference configuration
      */
     registerBackReference(childModelName, metadata) {
@@ -265,7 +267,7 @@ export class ModelRegistry {
         }
         // Reverse lookup (parent → children) is derived on demand by
         // `getChildModels`, which scans this map.
-        getContext().logger.debug('BackReference registered', `${childModelName} -> ${metadata.parentModel}`, {
+        this.runtime.logger.debug('BackReference registered', `${childModelName} -> ${metadata.parentModel}`, {
             foreignKey: metadata.foreignKey,
             cascadeDelete: metadata.cascadeDelete,
         });
@@ -365,7 +367,7 @@ export class ModelRegistry {
         const sorted = JSON.stringify(schema, Object.keys(schema).sort());
         // Create hash - browser-compatible simple hash
         this.schemaHash = this.simpleHash(sorted);
-        getContext().logger.debug('Schema hash updated', this.schemaHash);
+        this.runtime.logger.debug('Schema hash updated', this.schemaHash);
         return this.schemaHash;
     }
     /**
@@ -410,10 +412,10 @@ export class ModelRegistry {
         }
         const isValid = errors.length === 0;
         if (isValid) {
-            getContext().logger.info('All model references are valid');
+            this.runtime.logger.info('All model references are valid');
         }
         else {
-            getContext().observability.breadcrumb('Reference validation failed', 'sync.database', 'error');
+            this.runtime.observability.breadcrumb('Reference validation failed', 'sync.database', 'error');
         }
         return {
             valid: isValid,
@@ -458,7 +460,7 @@ export class ModelRegistry {
         this.constructorToModelName.clear();
         this.schemaHash = undefined;
         this.pendingHashUpdate = false;
-        getContext().logger.info('ModelRegistry cleared');
+        this.runtime.logger.info('ModelRegistry cleared');
     }
     /**
      * Static wrapper for backward compatibility