@abloatai/ablo 0.26.0 → 0.27.0

package/dist/Model.d.ts

@@ -1,16 +1,10 @@
 /**
- * Model - Clean base class for domain models
- *
- * Models are pure domain objects that:
- * - Hold data and business logic
- * - Track their own changes
- * - Validate themselves
- * - Return updates/changes (not perform them)
- *
- * Models do NOT:
- * - Access stores or singletons
- * - Perform side effects (saving, notifications)
- * - Know about sync infrastructure
+ * Model is the base class for the sync engine's domain models. A model is a
+ * plain domain object: it holds data and business logic, tracks its own
+ * property changes, and validates itself, and it returns the changes to apply
+ * rather than applying them. It does not reach into stores or singletons and
+ * does not perform side effects such as saving or sending notifications;
+ * persistence and sync are driven by the store that owns the model.
  */
 /** Store interface — methods that Model subclasses can call on the store */
 interface SyncStoreRef {
@@ -67,9 +61,10 @@ export interface ModelChanges {
     timestamp: Date;
 }
 /**
- * Abstract Model - Base class for all domain models
- *
- * Pure domain object with no external dependencies
+ * The abstract base class every domain model extends. It holds the model's id
+ * and timestamps, tracks in-place property changes for change detection and
+ * undo, and serializes itself, while leaving persistence and sync to the store
+ * that owns it.
  */
 export declare abstract class Model {
     /** Static reference to active SyncedStore for reactive queries */
@@ -156,27 +151,17 @@ export declare abstract class Model {
      */
     isNew(): boolean;
     /**
-     * Read-only view of the snapshot taken at `markAsPersisted()` /
-     * load. Used by recording-transaction undo to derive a pre-session
-     * baseline for fields that weren't yet pre-mutated (so
-     * `modifiedProperties` has no entry for them). Returns the same
-     * underlying object — callers must not mutate it.
-     *
-     * Architectural note: this method exists because we allow direct
-     * property writes (`slide.title = 'foo'`) AND mutator-recorded
-     * writes to coexist. Zero / Replicache structurally avoids this:
-     * every mutation MUST go through a registered mutator function,
-     * mutator args are serialized, and on server pull all unacked
-     * mutations are dropped and the mutator functions are replayed on
-     * the new basis (rebase). That makes per-instance baselines
-     * unnecessary because the b-tree at the new basis IS the
-     * authoritative pre-session state.
+     * Return a read-only view of the snapshot taken at {@link markAsPersisted}
+     * or at load time. The undo machinery uses it to recover a field's pre-edit
+     * value when the field was written without first being tracked in
+     * `modifiedProperties`. The returned object is the live snapshot, so callers
+     * must not mutate it.
      *
-     * If we ever migrate to "mutators are the only write path," this
-     * snapshot field, `_originalData`, and most of
-     * `RecordingTransaction.snapshotFields` become dead code. See
-     * `packages/replicache/src/db/rebase.ts` (rocicorp/mono) for the
-     * pattern.
+     * 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
+     * write went through a single recorded path would not need it, since the
+     * last acknowledged state would already be the authoritative baseline.
      */
     getOriginalSnapshot(): Readonly<ModelData> | undefined;
     /**
@@ -184,7 +169,7 @@ export declare abstract class Model {
      */
     clearChanges(): void;
     /**
-     * Capture a before-image for `keys` — the SINGLE source of truth for the
+     * 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
@@ -194,10 +179,10 @@ export declare abstract class Model {
      *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
      *      baseline, set whenever the field was mutated in place before commit.
      *   2. `getOriginalSnapshot()[key]` — the last loaded/acked row, the correct
-     *      before-image for a key written WITHOUT a prior in-place mutation
+     *      before-image for a key written without a prior in-place mutation
      *      (e.g. a `precomputedChanges` write).
      *   3. `fallbackToLive` only — the current live value. The manual-record path
-     *      wants this last resort; the stream path deliberately OMITS unresolved
+     *      wants this last resort; the stream path deliberately omits unresolved
      *      keys so `buildUndoOps` drops an un-revertible inverse rather than
      *      inventing one. The flag is the one intentional difference between the
      *      two callers — do not collapse it.
@@ -205,8 +190,8 @@ export declare abstract class Model {
      * `id` is always skipped. Values are read out per-key, so the
      * `getOriginalSnapshot()` "callers must not mutate" contract is preserved.
      *
-     * Invariant this relies on: a given undo scope is EITHER stream-recorded
-     * (`recordFromStream: true`) OR manual (`useMutators({ undoScope })`), never
+     * Invariant this relies on: a given undo scope is either stream-recorded
+     * (`recordFromStream: true`) or manual (`useMutators({ undoScope })`), never
      * both — otherwise a write would be captured twice. No surface sets both.
      */
     capturePreviousValues(keys: Iterable<string>, opts?: {
@@ -214,7 +199,7 @@ export declare abstract class Model {
     }): ModelData;
     /**
      * Drop the `modifiedProperties` entries for `keys` — re-baselines a field
-     * after its `.old` has been frozen into a committed transaction, so the NEXT
+     * after its `.old` has been frozen into a committed transaction, so the next
      * write to the same field starts from this commit's result rather than the
      * stale pre-session `.old` that {@link propertyChanged}'s first-old-wins
      * policy preserves. Safe because the committed transaction owns its own
@@ -257,7 +242,7 @@ export declare abstract class Model {
      * properties, and coercing date fields. Shared by `updateFromData`
      * (hydration) and `applyChanges` (local user update).
      *
-     * Change tracking is EXPLICIT, not magic: for every field actually
+     * Change tracking is explicit: for every field actually
      * 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`
@@ -270,10 +255,10 @@ export declare abstract class Model {
      * Update from raw data (hydration)
      *
      * Used for inbound server deltas and pool upserts. Change tracking is
-     * deliberately suppressed: hydration writes must NOT land in
+     * deliberately suppressed: hydration writes must not land in
      * `modifiedProperties`, otherwise applying a server delta would queue a
      * brand-new outbound mutation and the record would echo forever. For a
-     * LOCAL user edit, use `applyChanges` instead.
+     * 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
@@ -282,18 +267,18 @@ export declare abstract class Model {
      */
     updateFromData(data: ModelData): void;
     /**
-     * Apply a LOCAL user-initiated update from a data object — the write
-     * path for `proxy.update({ id, data })`, which is the ONE AND ONLY way
+     * Apply a local, user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the one and only way
      * application code mutates synced fields.
      *
      * Unlike `updateFromData` (hydration, untracked), this records every
      * written field in `modifiedProperties` via `propertyChanged`, so
-     * `getChanges()` / the transaction queue send the edited fields to the
-     * server and the undo system gets a correct pre-write baseline.
-     * Recording is EXPLICIT here (via the `onWrite` hook) — it does not rely
-     * on any MobX `observe()` side-channel.
+     * `getChanges()` and the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline. Recording
+     * is explicit here, through the `onWrite` hook, and does not rely on any
+     * MobX `observe()` side channel.
      *
-     * `_originalData` is intentionally NOT reset here: it stays as the
+     * `_originalData` is intentionally not reset here: it stays as the
      * last-persisted baseline until `clearChanges()` runs on sync-ack.
      */
     applyChanges(data: ModelData): void;
@@ -335,7 +320,7 @@ export declare abstract class Model {
     _unregisterObservedCollection(collection: Disposable): void;
     /**
      * Check if any collection on this model is currently being observed by React
-     * Used by ObjectPool GC to prevent disposing models in active use
+     * Used by InstanceCache GC to prevent disposing models in active use
      */
     hasObservedCollections(): boolean;
     /**

package/dist/Model.js

@@ -1,20 +1,14 @@
 /**
- * Model - Clean base class for domain models
- *
- * Models are pure domain objects that:
- * - Hold data and business logic
- * - Track their own changes
- * - Validate themselves
- * - Return updates/changes (not perform them)
- *
- * Models do NOT:
- * - Access stores or singletons
- * - Perform side effects (saving, notifications)
- * - Know about sync infrastructure
+ * Model is the base class for the sync engine's domain models. A model is a
+ * plain domain object: it holds data and business logic, tracks its own
+ * property changes, and validates itself, and it returns the changes to apply
+ * rather than applying them. It does not reach into stores or singletons and
+ * does not perform side effects such as saving or sending notifications;
+ * persistence and sync are driven by the store that owns the model.
  */
 import { runInAction, isComputedProp } from 'mobx';
 import { v4 as uuid } from 'uuid';
-import { M1 } from './utils/mobx-setup.js';
+import { M1 } from './utils/mobxSetup.js';
 import { getActiveRegistry, hasActiveRegistry } from './ModelRegistry.js';
 import { getContext } from './context.js';
 import { AbloValidationError } from './errors.js';
@@ -30,9 +24,10 @@ export class ValidationError extends Error {
     }
 }
 /**
- * Abstract Model - Base class for all domain models
- *
- * Pure domain object with no external dependencies
+ * The abstract base class every domain model extends. It holds the model's id
+ * and timestamps, tracks in-place property changes for change detection and
+ * undo, and serializes itself, while leaving persistence and sync to the store
+ * that owns it.
  */
 export class Model {
     /** Static reference to active SyncedStore for reactive queries */
@@ -189,27 +184,17 @@ export class Model {
         return this._isNew;
     }
     /**
-     * Read-only view of the snapshot taken at `markAsPersisted()` /
-     * load. Used by recording-transaction undo to derive a pre-session
-     * baseline for fields that weren't yet pre-mutated (so
-     * `modifiedProperties` has no entry for them). Returns the same
-     * underlying object — callers must not mutate it.
-     *
-     * Architectural note: this method exists because we allow direct
-     * property writes (`slide.title = 'foo'`) AND mutator-recorded
-     * writes to coexist. Zero / Replicache structurally avoids this:
-     * every mutation MUST go through a registered mutator function,
-     * mutator args are serialized, and on server pull all unacked
-     * mutations are dropped and the mutator functions are replayed on
-     * the new basis (rebase). That makes per-instance baselines
-     * unnecessary because the b-tree at the new basis IS the
-     * authoritative pre-session state.
+     * Return a read-only view of the snapshot taken at {@link markAsPersisted}
+     * or at load time. The undo machinery uses it to recover a field's pre-edit
+     * value when the field was written without first being tracked in
+     * `modifiedProperties`. The returned object is the live snapshot, so callers
+     * must not mutate it.
      *
-     * If we ever migrate to "mutators are the only write path," this
-     * snapshot field, `_originalData`, and most of
-     * `RecordingTransaction.snapshotFields` become dead code. See
-     * `packages/replicache/src/db/rebase.ts` (rocicorp/mono) for the
-     * pattern.
+     * 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
+     * write went through a single recorded path would not need it, since the
+     * last acknowledged state would already be the authoritative baseline.
      */
     getOriginalSnapshot() {
         return this._originalData;
@@ -224,7 +209,7 @@ export class Model {
         });
     }
     /**
-     * Capture a before-image for `keys` — the SINGLE source of truth for the
+     * 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
@@ -234,10 +219,10 @@ export class Model {
      *   1. `modifiedProperties.get(key).old` — first-old-wins pre-session
      *      baseline, set whenever the field was mutated in place before commit.
      *   2. `getOriginalSnapshot()[key]` — the last loaded/acked row, the correct
-     *      before-image for a key written WITHOUT a prior in-place mutation
+     *      before-image for a key written without a prior in-place mutation
      *      (e.g. a `precomputedChanges` write).
      *   3. `fallbackToLive` only — the current live value. The manual-record path
-     *      wants this last resort; the stream path deliberately OMITS unresolved
+     *      wants this last resort; the stream path deliberately omits unresolved
      *      keys so `buildUndoOps` drops an un-revertible inverse rather than
      *      inventing one. The flag is the one intentional difference between the
      *      two callers — do not collapse it.
@@ -245,8 +230,8 @@ export class Model {
      * `id` is always skipped. Values are read out per-key, so the
      * `getOriginalSnapshot()` "callers must not mutate" contract is preserved.
      *
-     * Invariant this relies on: a given undo scope is EITHER stream-recorded
-     * (`recordFromStream: true`) OR manual (`useMutators({ undoScope })`), never
+     * Invariant this relies on: a given undo scope is either stream-recorded
+     * (`recordFromStream: true`) or manual (`useMutators({ undoScope })`), never
      * both — otherwise a write would be captured twice. No surface sets both.
      */
     capturePreviousValues(keys, opts) {
@@ -271,7 +256,7 @@ export class Model {
     }
     /**
      * Drop the `modifiedProperties` entries for `keys` — re-baselines a field
-     * after its `.old` has been frozen into a committed transaction, so the NEXT
+     * after its `.old` has been frozen into a committed transaction, so the next
      * write to the same field starts from this commit's result rather than the
      * stale pre-session `.old` that {@link propertyChanged}'s first-old-wins
      * policy preserves. Safe because the committed transaction owns its own
@@ -362,7 +347,7 @@ export class Model {
             // New model - return create operation
             return {
                 type: 'create',
-                modelName: this.getModelName(), // Use Prisma model name
+                modelName: this.getModelName(), // the registered model name
                 modelId: this.id,
                 timestamp: new Date(),
             };
@@ -371,7 +356,7 @@ export class Model {
             // Existing model with changes - return update operation
             return {
                 type: 'update',
-                modelName: this.getModelName(), // Use Prisma model name
+                modelName: this.getModelName(), // the registered model name
                 modelId: this.id,
                 changes: new Map(this.modifiedProperties),
                 timestamp: new Date(),
@@ -392,7 +377,7 @@ export class Model {
         this.willDelete();
         return {
             type: 'delete',
-            modelName: this.getModelName(), // Use Prisma model name
+            modelName: this.getModelName(), // the registered model name
             modelId: this.id,
             timestamp: new Date(),
         };
@@ -409,7 +394,7 @@ export class Model {
         this.archivedAt = new Date();
         return {
             type: 'archive',
-            modelName: this.getModelName(), // Use Prisma model name
+            modelName: this.getModelName(), // the registered model name
             modelId: this.id,
             timestamp: new Date(),
         };
@@ -426,7 +411,7 @@ export class Model {
         this.archivedAt = null;
         return {
             type: 'unarchive',
-            modelName: this.getModelName(), // Use Prisma model name
+            modelName: this.getModelName(), // the registered model name
             modelId: this.id,
             timestamp: new Date(),
         };
@@ -437,7 +422,7 @@ export class Model {
      * properties, and coercing date fields. Shared by `updateFromData`
      * (hydration) and `applyChanges` (local user update).
      *
-     * Change tracking is EXPLICIT, not magic: for every field actually
+     * Change tracking is explicit: for every field actually
      * 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`
@@ -497,10 +482,10 @@ export class Model {
      * Update from raw data (hydration)
      *
      * Used for inbound server deltas and pool upserts. Change tracking is
-     * deliberately suppressed: hydration writes must NOT land in
+     * deliberately suppressed: hydration writes must not land in
      * `modifiedProperties`, otherwise applying a server delta would queue a
      * brand-new outbound mutation and the record would echo forever. For a
-     * LOCAL user edit, use `applyChanges` instead.
+     * 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
@@ -527,18 +512,18 @@ export class Model {
         this.didUpdate();
     }
     /**
-     * Apply a LOCAL user-initiated update from a data object — the write
-     * path for `proxy.update({ id, data })`, which is the ONE AND ONLY way
+     * Apply a local, user-initiated update from a data object — the write
+     * path for `proxy.update({ id, data })`, which is the one and only way
      * application code mutates synced fields.
      *
      * Unlike `updateFromData` (hydration, untracked), this records every
      * written field in `modifiedProperties` via `propertyChanged`, so
-     * `getChanges()` / the transaction queue send the edited fields to the
-     * server and the undo system gets a correct pre-write baseline.
-     * Recording is EXPLICIT here (via the `onWrite` hook) — it does not rely
-     * on any MobX `observe()` side-channel.
+     * `getChanges()` and the transaction queue send the edited fields to the
+     * server and the undo system gets a correct pre-write baseline. Recording
+     * is explicit here, through the `onWrite` hook, and does not rely on any
+     * MobX `observe()` side channel.
      *
-     * `_originalData` is intentionally NOT reset here: it stays as the
+     * `_originalData` is intentionally not reset here: it stays as the
      * last-persisted baseline until `clearChanges()` runs on sync-ack.
      */
     applyChanges(data) {
@@ -564,8 +549,8 @@ export class Model {
         const modelName = this.getModelName();
         const properties = getActiveRegistry().getProperties(modelName);
         const result = {
-            __class: this.getModelName(), // Use Prisma model name for consistency
-            __typename: this.getModelName(), // Also add __typename for GraphQL compatibility
+            __class: this.getModelName(), // the registered model name for consistency
+            __typename: this.getModelName(), // __typename mirrors __class as the wire type discriminator
             id: this.id,
             createdAt: this.createdAt?.toISOString(),
             updatedAt: this.updatedAt?.toISOString(),
@@ -656,7 +641,7 @@ export class Model {
     }
     /**
      * Check if any collection on this model is currently being observed by React
-     * Used by ObjectPool GC to prevent disposing models in active use
+     * Used by InstanceCache GC to prevent disposing models in active use
      */
     hasObservedCollections() {
         return this._observedCollections.size > 0;
@@ -813,7 +798,7 @@ export class Model {
         }
         // Try to get model class by identifier
         let ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
-        // If not found with Prisma name, try mapping to class name
+        // If not found by registered name, try mapping to the class name
         if (!ModelClass) {
             const classNameMap = {
                 Task: 'TaskModel',

package/dist/ModelRegistry.d.ts

@@ -1,13 +1,11 @@
 /**
- * ModelRegistry - Type-safe model metadata management
- *
- * Key improvements:
- * - Instance-based for better testing
- * - Validation at registration
- * - Lazy reference resolution
- * - Crypto-based schema hashing
- * - Comprehensive error reporting
- * - Best practices from Linear Sync Engine
+ * ModelRegistry is the source of truth for model metadata: which model classes
+ * exist, the properties and references declared on each, the back-references
+ * used for cascade handling, and a stable hash of the whole schema.
+ * {@link Model} instances resolve their metadata through the active registry,
+ * and {@link InstanceCache} uses it to map between model names and constructor
+ * 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 { Model } from './Model.js';
@@ -30,7 +28,8 @@ export type ModelClassInput = new (...args: never[]) => Model;
  */
 export type RegisteredModelClass = Omit<typeof Model, never> & ConcreteModelConstructor<Model>;
 /**
- * Extended ReferenceMetadata with additional Linear-style options
+ * {@link ReferenceMetadata} extended with cascade behavior: what happens to a
+ * referencing model when the referenced model is deleted or archived.
  */
 export interface ExtendedReferenceMetadata extends ReferenceMetadata {
     onDelete?: 'cascade' | 'nullify' | 'restrict';
@@ -47,8 +46,9 @@ export interface SerializedReferenceMetadata extends Omit<ExtendedReferenceMetad
     referencedModel: string;
 }
 /**
- * BackReference metadata for cascade-aware transaction handling
- * Linear pattern: When parent is deleted, cancel pending transactions for children
+ * Metadata that records a child model's foreign key to a parent model, used
+ * for cascade-aware transaction handling: when the parent is deleted, the
+ * child's pending transactions can be cancelled.
  */
 export interface BackReferenceMetadata {
     /** The parent model name (e.g., 'SlideDeck') */
@@ -81,7 +81,6 @@ export declare class ModelRegistry {
     private schemaHash?;
     private config;
     private registeredModels;
-    private batchMode;
     private pendingHashUpdate;
     constructor(config?: RegistryConfig);
     private validateModelConstructor;
@@ -102,13 +101,14 @@ export declare class ModelRegistry {
      */
     registerReference(modelName: string, propertyName: string, metadata: ExtendedReferenceMetadata): void;
     /**
-     * LINEAR PATTERN: Register a back-reference for cascade-aware transaction handling
+     * Register a back-reference for cascade-aware transaction handling.
      *
-     * When a parent model is deleted, the TransactionQueue will cancel pending
-     * transactions for all child models that have a backReference to that parent.
+     * When a parent model is deleted, the transaction queue cancels pending
+     * transactions for every child model that declares a back-reference to that
+     * parent.
      *
-     * @param childModelName - The model that has a FK to the parent (e.g., 'Slide')
-     * @param metadata - BackReference configuration
+     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Slide')
+     * @param metadata - The back-reference configuration
      */
     registerBackReference(childModelName: string, metadata: BackReferenceMetadata): void;
     /** Get all models with specific load strategy. */
@@ -141,7 +141,9 @@ export declare class ModelRegistry {
         foreignKey: string;
     }[];
     /**
-     * Calculate schema hash using crypto
+     * Compute a stable hash of the registered schema — model names, property
+     * types, and their indexed and optional flags. Memoized until the schema
+     * changes.
      */
     getSchemaHash(): string;
     /**

package/dist/ModelRegistry.js

@@ -1,13 +1,11 @@
 /**
- * ModelRegistry - Type-safe model metadata management
- *
- * Key improvements:
- * - Instance-based for better testing
- * - Validation at registration
- * - Lazy reference resolution
- * - Crypto-based schema hashing
- * - Comprehensive error reporting
- * - Best practices from Linear Sync Engine
+ * ModelRegistry is the source of truth for model metadata: which model classes
+ * exist, the properties and references declared on each, the back-references
+ * used for cascade handling, and a stable hash of the whole schema.
+ * {@link Model} instances resolve their metadata through the active registry,
+ * and {@link InstanceCache} uses it to map between model names and constructor
+ * classes. References resolve lazily, so a model may declare a reference to
+ * another model that is registered later.
  */
 // Removed Node.js crypto import for browser compatibility
 import { PropertyType, LoadStrategy, } from './types/index.js';
@@ -43,19 +41,17 @@ export class ModelRegistry {
     properties = new Map();
     references = new Map();
     pendingReferences = new Map();
-    // 🔧 PROPER FIX: Static mapping from constructor to model name.
-    // Keyed `unknown` on purpose: lookups arrive as `this.constructor`
-    // (Function) and as typed model classes — both accepted without casts.
+    // Maps a constructor back to its model name. Keyed as `unknown` on purpose:
+    // lookups arrive both as `this.constructor` (a Function) and as typed model
+    // classes, and both are accepted without a cast.
     constructorToModelName = new Map();
-    // LINEAR PATTERN: BackReferences for cascade-aware transaction handling.
-    // Maps childModelName → BackReferenceMetadata[] (which parent models
-    // own this child). The inverse direction (parentModelName → children)
-    // is derived on demand by `getChildModels`, populated only here.
+    // Back-references for cascade-aware transaction handling. Maps a child model
+    // name to the parent models it references. The inverse direction (parent to
+    // children) is derived on demand by `getChildModels`; it is populated here.
     backReferences = new Map();
     schemaHash;
     config;
     registeredModels = new Set();
-    batchMode = false;
     pendingHashUpdate = false;
     constructor(config = {}) {
         this.config = {
@@ -169,7 +165,7 @@ export class ModelRegistry {
         const modelClass = constructor;
         this.models.set(name, modelClass);
         this.modelMetadata.set(name, metadata);
-        // 🔧 PROPER FIX: Create reverse mapping from constructor to model name
+        // Record the reverse mapping from constructor to model name
         this.constructorToModelName.set(constructor, name);
         // Initialize property maps
         if (!this.properties.has(name)) {
@@ -246,13 +242,14 @@ export class ModelRegistry {
         this.completeReferenceRegistration(modelName, propertyName, metadata);
     }
     /**
-     * LINEAR PATTERN: Register a back-reference for cascade-aware transaction handling
+     * Register a back-reference for cascade-aware transaction handling.
      *
-     * When a parent model is deleted, the TransactionQueue will cancel pending
-     * transactions for all child models that have a backReference to that parent.
+     * When a parent model is deleted, the transaction queue cancels pending
+     * transactions for every child model that declares a back-reference to that
+     * parent.
      *
-     * @param childModelName - The model that has a FK to the parent (e.g., 'Slide')
-     * @param metadata - BackReference configuration
+     * @param childModelName - The model that holds a foreign key to the parent (e.g., 'Slide')
+     * @param metadata - The back-reference configuration
      */
     registerBackReference(childModelName, metadata) {
         // Add to instance map
@@ -345,7 +342,9 @@ export class ModelRegistry {
         return children;
     }
     /**
-     * Calculate schema hash using crypto
+     * Compute a stable hash of the registered schema — model names, property
+     * types, and their indexed and optional flags. Memoized until the schema
+     * changes.
      */
     getSchemaHash() {
         if (this.schemaHash)
@@ -428,7 +427,6 @@ export class ModelRegistry {
      * Start batch registration mode to optimize performance
      */
     startBatch() {
-        this.batchMode = true;
         this.pendingHashUpdate = false;
     }
     /**
@@ -438,7 +436,6 @@ export class ModelRegistry {
      * End batch registration mode and update schema hash if needed
      */
     endBatch() {
-        this.batchMode = false;
         if (this.pendingHashUpdate) {
             this.getSchemaHash(); // This will recalculate if needed
             this.pendingHashUpdate = false;
@@ -460,7 +457,6 @@ export class ModelRegistry {
         this.backReferences.clear();
         this.constructorToModelName.clear();
         this.schemaHash = undefined;
-        this.batchMode = false;
         this.pendingHashUpdate = false;
         getContext().logger.info('ModelRegistry cleared');
     }

package/dist/NetworkMonitor.d.ts

@@ -1,10 +1,9 @@
 /**
- * NetworkMonitor - Network connectivity tracking with visibility awareness
- *
- * Monitors online/offline state using browser events AND visibility changes.
- * When a tab becomes visible after being hidden (e.g., laptop sleep/wake),
- * the WebSocket may have silently died without triggering online/offline events.
- * The visibility handler detects this and emits 'online' to trigger recovery.
+ * NetworkMonitor tracks network connectivity and reports it through events.
+ * It listens to the browser's online and offline events, and it also watches
+ * for a tab becoming visible again: after a laptop sleep/wake or a long spell
+ * in the background, the WebSocket can die silently without an offline event
+ * firing, so returning to the tab emits a recovery signal the store can act on.
  */
 import { EventEmitter } from 'events';
 export declare class NetworkMonitor extends EventEmitter {

package/dist/NetworkMonitor.js

@@ -1,10 +1,9 @@
 /**
- * NetworkMonitor - Network connectivity tracking with visibility awareness
- *
- * Monitors online/offline state using browser events AND visibility changes.
- * When a tab becomes visible after being hidden (e.g., laptop sleep/wake),
- * the WebSocket may have silently died without triggering online/offline events.
- * The visibility handler detects this and emits 'online' to trigger recovery.
+ * NetworkMonitor tracks network connectivity and reports it through events.
+ * It listens to the browser's online and offline events, and it also watches
+ * for a tab becoming visible again: after a laptop sleep/wake or a long spell
+ * in the background, the WebSocket can die silently without an offline event
+ * firing, so returning to the tab emits a recovery signal the store can act on.
  */
 import { EventEmitter } from 'events';
 import { getContext } from './context.js';