@abloatai/ablo 0.26.0 → 0.28.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;
     /**
@@ -379,8 +364,25 @@ export declare abstract class Model {
      * the schema's `T` describes. Computed relations (`referenceModel`/
      * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
      * row projection; they're lazy/recursive and not part of the row's data.
+     *
+     * Schema-derived getters (`computed:` entries and `${field}Json` getters) ARE
+     * materialized, as non-enumerable own values. The schema's inferred row type
+     * includes them, so omitting them would make every snapshot read of a computed
+     * silently `undefined` — a type-level lie. They're evaluated here, inside the
+     * caller's tracked function, so the reaction subscribes to whatever fields the
+     * getter reads. Non-enumerable keeps write-path parity with model instances:
+     * an instance's getters sit on the prototype and never enter `{...model}`
+     * spreads or `JSON.stringify`, and materialized values must not either — a
+     * spread-into-update would otherwise send computed keys to the server.
      */
     toReactiveSnapshot<T = ModelData>(): T;
+    /**
+     * Names of schema-derived getters — `computed:` entries and `${field}Json`
+     * getters — that {@link toReactiveSnapshot} materializes onto snapshots.
+     * The dynamic model class built by `registerModelsFromSchema` overrides this;
+     * hand-written Model subclasses default to none.
+     */
+    getDerivedGetterNames(): readonly string[];
     /**
      * Get field changes for activity tracking
      */

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';
@@ -29,10 +23,13 @@ export class ValidationError extends Error {
         this.name = 'ValidationError';
     }
 }
+/** Shared frozen default for {@link Model.getDerivedGetterNames}. */
+const EMPTY_DERIVED_GETTERS = Object.freeze([]);
 /**
- * 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 +186,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 +211,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 +221,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 +232,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 +258,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 +349,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 +358,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 +379,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 +396,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 +413,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 +424,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 +484,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 +514,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 +551,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 +643,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;
@@ -749,6 +736,16 @@ export class Model {
      * the schema's `T` describes. Computed relations (`referenceModel`/
      * `referenceCollection`) and ephemeral fields are skipped, matching `toJSON`'s
      * row projection; they're lazy/recursive and not part of the row's data.
+     *
+     * Schema-derived getters (`computed:` entries and `${field}Json` getters) ARE
+     * materialized, as non-enumerable own values. The schema's inferred row type
+     * includes them, so omitting them would make every snapshot read of a computed
+     * silently `undefined` — a type-level lie. They're evaluated here, inside the
+     * caller's tracked function, so the reaction subscribes to whatever fields the
+     * getter reads. Non-enumerable keeps write-path parity with model instances:
+     * an instance's getters sit on the prototype and never enter `{...model}`
+     * spreads or `JSON.stringify`, and materialized values must not either — a
+     * spread-into-update would otherwise send computed keys to the server.
      */
     toReactiveSnapshot() {
         const snapshot = {
@@ -759,8 +756,8 @@ export class Model {
         if (this.archivedAt !== undefined)
             snapshot.archivedAt = this.archivedAt;
         const properties = getActiveRegistry().getProperties(this.getModelName());
+        const self = this;
         if (properties) {
-            const self = this;
             for (const [propName, metadata] of properties) {
                 if (metadata.type === 'ephemeralProperty' ||
                     metadata.type === 'referenceModel' ||
@@ -772,8 +769,27 @@ export class Model {
                 snapshot[propName] = self[propName];
             }
         }
+        for (const name of this.getDerivedGetterNames()) {
+            Object.defineProperty(snapshot, name, {
+                // Evaluated on the model instance so `${field}Json` caches stay on it
+                // and the enclosing reaction tracks the fields the getter reads.
+                value: self[name],
+                enumerable: false,
+                configurable: true,
+                writable: false,
+            });
+        }
         return snapshot;
     }
+    /**
+     * Names of schema-derived getters — `computed:` entries and `${field}Json`
+     * getters — that {@link toReactiveSnapshot} materializes onto snapshots.
+     * The dynamic model class built by `registerModelsFromSchema` overrides this;
+     * hand-written Model subclasses default to none.
+     */
+    getDerivedGetterNames() {
+        return EMPTY_DERIVED_GETTERS;
+    }
     /**
      * Get field changes for activity tracking
      */
@@ -813,7 +829,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;
     /**