@abloatai/ablo 0.25.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 */
@@ -70,7 +65,7 @@ export class Model {
     _observedCollections = new Set();
     constructor(data = {}) {
         // Always generate permanent UUID on client
-        this.id = data.id || Model.generateId();
+        this.id = data.id ?? Model.generateId();
         this.clientId = this.id; // No more temp IDs!
         // Ensure dates are Date objects, not strings
         this.createdAt = data.createdAt
@@ -91,7 +86,7 @@ export class Model {
             : data.createdAt
                 ? new Date(this.createdAt)
                 : new Date();
-        this.syncStatus = data.syncStatus || 'pending';
+        this.syncStatus = data.syncStatus ?? 'pending';
     }
     /**
      * Generate unique ID
@@ -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.
+     * 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.
      *
-     * 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.
-     *
-     * 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
@@ -340,9 +325,7 @@ export class Model {
      * Add validation rule
      */
     addValidationRule(propName, rule) {
-        if (!this.validationRules[propName]) {
-            this.validationRules[propName] = [];
-        }
+        this.validationRules[propName] ??= [];
         this.validationRules[propName].push(rule);
     }
     /**
@@ -364,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(),
             };
@@ -373,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(),
@@ -394,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(),
         };
@@ -411,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(),
         };
@@ -428,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(),
         };
@@ -439,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`
@@ -499,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
@@ -529,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) {
@@ -566,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(),
@@ -575,7 +558,7 @@ export class Model {
             syncStatus: this.syncStatus,
         };
         if (this.archivedAt !== undefined) {
-            result.archivedAt = this.archivedAt?.toISOString() || null;
+            result.archivedAt = this.archivedAt?.toISOString() ?? null;
         }
         if (properties) {
             const self = this;
@@ -616,7 +599,7 @@ export class Model {
         const className = this.constructor.name;
         // Use consumer-provided fallback map from config (replaces hardcoded Prisma name map)
         const fallbackMap = getContext().config.classNameFallbackMap;
-        return fallbackMap[className] || className.replace(/Model$/, '');
+        return fallbackMap[className] ?? className.replace(/Model$/, '');
     }
     /**
      * Read a field value by name. Runtime-safe dynamic field access —
@@ -658,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;
@@ -809,13 +792,13 @@ export class Model {
      */
     static fromJSON(data) {
         // Support both __class and __typename, and handle both old and new naming
-        const modelIdentifier = data.__typename || data.__class || data.modelName;
+        const modelIdentifier = data.__typename ?? data.__class ?? data.modelName;
         if (!modelIdentifier) {
             throw new AbloValidationError('Model identifier (__typename, __class, or modelName) not found in data', { code: 'model_identifier_missing' });
         }
         // 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,17 +1,35 @@
 /**
- * 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 { ModelMetadata, PropertyMetadata, ReferenceMetadata, LoadStrategy } from './types/index.js';
+import { type ModelMetadata, type PropertyMetadata, type ReferenceMetadata, LoadStrategy } from './types/index.js';
+import type { Model } from './Model.js';
+import type { ConcreteModelConstructor } from './BaseSyncedStore.js';
 /**
- * Extended ReferenceMetadata with additional Linear-style options
+ * What callers may hand to {@link ModelRegistry.registerModel}: any concrete
+ * `Model` subclass constructor. `never[]` params make every subclass
+ * constructor assignable (construct-signature params are contravariant).
+ */
+export type ModelClassInput = new (...args: never[]) => Model;
+/**
+ * What the registry hands BACK: a registered model class — concretely
+ * constructible with an optional data row (`ConcreteModelConstructor`, the
+ * SDK's existing Model-vs-row construction seam) and carrying `Model`'s
+ * statics (`fromJSON`, …). `Omit<typeof Model, never>` keeps the statics
+ * while stripping the ABSTRACT construct signature (mapped types drop
+ * construct signatures), so `new registry.getModelByName(n)!(...)` is legal.
+ * The one cast from {@link ModelClassInput} lives at the validated
+ * registration boundary below.
+ */
+export type RegisteredModelClass = Omit<typeof Model, never> & ConcreteModelConstructor<Model>;
+/**
+ * {@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';
@@ -28,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') */
@@ -62,7 +81,6 @@ export declare class ModelRegistry {
     private schemaHash?;
     private config;
     private registeredModels;
-    private batchMode;
     private pendingHashUpdate;
     constructor(config?: RegistryConfig);
     private validateModelConstructor;
@@ -73,7 +91,7 @@ export declare class ModelRegistry {
     /**
      * Register a model with validation
      */
-    registerModel(name: string, constructor: any, metadata?: ModelMetadata): void;
+    registerModel(name: string, constructor: ModelClassInput, metadata?: ModelMetadata): void;
     /**
      * Register property with validation
      */
@@ -83,19 +101,20 @@ 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. */
     getModelsByLoadStrategy(strategy: LoadStrategy): string[];
     /** Get model name from constructor (production-safe). */
-    getModelNameFromConstructor(constructor: any): string | undefined;
+    getModelNameFromConstructor(constructor: unknown): string | undefined;
     /** Get properties for a model. */
     getPropertiesForModel(modelName: string): Map<string, PropertyMetadata>;
     /**
@@ -103,7 +122,7 @@ export declare class ModelRegistry {
      */
     getRegisteredModelNames(): string[];
     /** Get model constructor by name */
-    getModelByName(name: string): any;
+    getModelByName(name: string): RegisteredModelClass | undefined;
     /** Check if model is registered */
     hasModel(name: string): boolean;
     /** Get model metadata by name */
@@ -117,12 +136,14 @@ export declare class ModelRegistry {
     /** Get back-references for a child model */
     getBackReferences(childModelName: string): BackReferenceMetadata[];
     /** Get child models for a parent */
-    getChildModels(parentModelName: string): Array<{
+    getChildModels(parentModelName: string): {
         childModel: string;
         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;
     /**