@dxos/echo 0.8.4-main.406dc2a → 0.8.4-main.40e3dcdf1b

package/src/internal/{schema → Type}/echo-schema.ts

@@ -8,10 +8,12 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { invariant } from '@dxos/invariant';
 import { type ObjectId } from '@dxos/keys';
 
-import { type SchemaMeta, SchemaMetaSymbol, type TypeAnnotation, getTypeAnnotation } from '../ast';
-import { toEffectSchema, toJsonSchema } from '../json';
-import { type JsonSchemaType } from '../json-schema';
-import { type TypedObject, type TypedObjectPrototype } from '../object';
+import type * as Type from '../../Type';
+import { type SchemaMeta, SchemaMetaSymbol, type TypeAnnotation, getTypeAnnotation } from '../Annotation';
+import { type JsonSchemaType, toEffectSchema, toJsonSchema } from '../JsonSchema';
+import { type TypedObject, type TypedObjectPrototype, getSnapshot } from '../Obj';
+import { ChangeId } from '../common/proxy';
+import { EntityKind, SchemaKindId } from '../common/types';
 
 import {
   addFieldsToSchema,
@@ -20,14 +22,14 @@ import {
   updateFieldNameInSchema,
   updateFieldsInSchema,
 } from './manipulation';
-import { getSnapshot } from './snapshot';
-import { StoredSchema } from './stored-schema';
+import { PersistentSchema } from './persistent-schema';
 
 /**
  * Base schema type.
  */
 // TODO(burdon): Merge with ImmutableSchema.
 export interface BaseSchema<A = any, I = any> extends TypedObject<A, I> {
+  // TODO(burdon): Different from mutable?
   get readonly(): boolean;
   // TODO(burdon): Change to external function.
   get mutable(): EchoSchema<A, I>;
@@ -83,6 +85,10 @@ export class ImmutableSchema<A = any, I = any> implements BaseSchema<A, I> {
   // TypedObject
   //
 
+  get kind(): EntityKind {
+    return this._objectAnnotation.kind;
+  }
+
   get typename(): string {
     return this._objectAnnotation.typename;
   }
@@ -124,8 +130,10 @@ const EchoSchemaConstructor = (): TypedObjectPrototype => {
    */
   return class {
     private static get _schema() {
-      // The field is DynamicEchoSchema in runtime, but is serialized as StoredEchoSchema in automerge.
-      return Schema.Union(StoredSchema, Schema.instanceOf(EchoSchema)).annotations(StoredSchema.ast.annotations);
+      // The field is DynamicEchoSchema in runtime, but is serialized as PersisentSchema in automerge.
+      return Schema.Union(PersistentSchema, Schema.instanceOf(EchoSchema)).annotations(
+        PersistentSchema.ast.annotations,
+      );
     }
 
     static readonly [Schema.TypeId] = schemaVariance;
@@ -159,7 +167,7 @@ const schemaVariance = {
 };
 
 /**
- * Represents a schema that is stored in the ECHO database.
+ * Represents a schema that is persisted in the ECHO database.
  * Schema can me mutable or readonly (specified by the {@link EchoSchema.readonly} field).
  *
  * Schema that can be modified at runtime via the API.
@@ -170,20 +178,26 @@ const schemaVariance = {
  *
  * @example
  * ```ts
- * export class TableType extends Schema.Struct({...}).pipe(Type.Obj({ typename: 'example.org/type/Table', version: '0.1.0' })){
+ * export class TableType extends Schema.Struct({...}).pipe(Type.object({ typename: 'com.example.type.table', version: '0.1.0' })){
  *   title: Schema.String,
  *   schema: Schema.optional(ref(EchoSchema)),
  *   props: Schema.mutable(S.Array(TablePropSchema)),
  * }) {}
  * ```
  *
- * The ECHO API will translate any references to StoredSchema objects to be resolved as EchoSchema objects.
+ * The ECHO API will translate any references to PersistentSchema objects to be resolved as EchoSchema objects.
  */
 export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implements BaseSchema<A, I> {
   private _schema: Schema.Schema.AnyNoContext | undefined;
   private _isDirty = true;
 
-  constructor(private readonly _storedSchema: StoredSchema) {
+  /**
+   * Schema kind key that marks this as an ECHO schema.
+   * Makes EchoSchema satisfy the Type.AnyObj type.
+   */
+  readonly [SchemaKindId]: EntityKind.Object = EntityKind.Object;
+
+  constructor(private readonly _persistentSchema: PersistentSchema) {
     super();
   }
 
@@ -196,11 +210,11 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   public get Type() {
-    return this._storedSchema as A;
+    return this._persistentSchema as A;
   }
 
   public get Encoded() {
-    return this._storedSchema as I;
+    return this._persistentSchema as I;
   }
 
   public get Context() {
@@ -227,12 +241,17 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   // BaseSchema
   //
 
+  public get kind(): EntityKind.Object {
+    // Dynamic schemas are always object schemas.
+    return EntityKind.Object;
+  }
+
   public get typename(): string {
-    return this._storedSchema.typename;
+    return this._persistentSchema.typename;
   }
 
   public get version(): string {
-    return this._storedSchema.version;
+    return this._persistentSchema.version;
   }
 
   public get readonly(): boolean {
@@ -247,10 +266,10 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   /**
-   * @reactive
+   * Returns the JSON schema for the schema.
    */
   public get jsonSchema(): JsonSchemaType {
-    return this._storedSchema.jsonSchema;
+    return this._persistentSchema.jsonSchema;
   }
 
   /**
@@ -269,25 +288,25 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    * Id of the ECHO object containing the schema.
    */
   public get id(): ObjectId {
-    return this._storedSchema.id;
+    return this._persistentSchema.id;
   }
 
   /**
    * Short name of the schema.
    */
   public get name(): string | undefined {
-    return this._storedSchema.name;
+    return this._persistentSchema.name;
   }
 
   public get [SchemaMetaSymbol](): SchemaMeta {
-    return { id: this.id, typename: this.typename, version: this._storedSchema.version };
+    return { id: this.id, typename: this.typename, version: this._persistentSchema.version };
   }
 
   /**
-   * Reference to the underlying stored schema object.
+   * Reference to the underlying persistent schema object.
    */
-  public get storedSchema(): StoredSchema {
-    return this._storedSchema;
+  public get persistentSchema(): Type.PersistentType {
+    return this._persistentSchema as Type.PersistentType;
   }
 
   public getProperties(): SchemaAST.PropertySignature[] {
@@ -307,8 +326,10 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateTypename(typename: string): void {
     const updated = setTypenameInSchema(this._getSchema(), typename);
-    this._storedSchema.typename = typename;
-    this._storedSchema.jsonSchema = toJsonSchema(updated);
+    this._change((schema) => {
+      schema.typename = typename;
+      schema.jsonSchema = toJsonSchema(updated);
+    });
   }
 
   /**
@@ -316,7 +337,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public addFields(fields: Schema.Struct.Fields): void {
     const extended = addFieldsToSchema(this._getSchema(), fields);
-    this._storedSchema.jsonSchema = toJsonSchema(extended);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(extended);
+    });
   }
 
   /**
@@ -324,7 +347,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateFields(fields: Schema.Struct.Fields): void {
     const updated = updateFieldsInSchema(this._getSchema(), fields);
-    this._storedSchema.jsonSchema = toJsonSchema(updated);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(updated);
+    });
   }
 
   /**
@@ -332,7 +357,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateFieldPropertyName({ before, after }: { before: PropertyKey; after: PropertyKey }): void {
     const renamed = updateFieldNameInSchema(this._getSchema(), { before, after });
-    this._storedSchema.jsonSchema = toJsonSchema(renamed);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(renamed);
+    });
   }
 
   /**
@@ -340,7 +367,21 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public removeFields(fieldNames: string[]): void {
     const removed = removeFieldsFromSchema(this._getSchema(), fieldNames);
-    this._storedSchema.jsonSchema = toJsonSchema(removed);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(removed);
+    });
+  }
+
+  /**
+   * Wrapper for Obj.change that handles the change context for the persistent schema.
+   */
+  private _change(callback: (schema: PersistentSchema) => void): void {
+    const changeFn = (this._persistentSchema as any)[ChangeId];
+    if (changeFn) {
+      changeFn(callback);
+    } else {
+      callback(this._persistentSchema);
+    }
   }
 
   //
@@ -348,7 +389,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   //
 
   /**
-   * Called by EchoSchemaRegistry on update.
+   * Called by DatabaseSchemaRegistry on update.
    */
   _invalidate(): void {
     this._isDirty = true;
@@ -359,12 +400,12 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   _rebuild(): void {
     if (this._isDirty || this._schema == null) {
-      this._schema = toEffectSchema(getSnapshot(this._storedSchema.jsonSchema));
+      this._schema = toEffectSchema(getSnapshot(this._persistentSchema).jsonSchema);
       this._isDirty = false;
     }
   }
 
-  private _getSchema(): Schema.Schema.AnyNoContext {
+  _getSchema(): Schema.Schema.AnyNoContext {
     this._rebuild();
     return this._schema!;
   }

package/src/internal/Type/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './echo-schema';
+export * from './manipulation';
+export * from './persistent-schema';

package/src/internal/{schema → Type}/manipulation.ts

@@ -8,7 +8,7 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../ast';
+import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation';
 
 // TODO(ZaymonFC): Do this one at a time. This might be dangerous.
 export const addFieldsToSchema = (

package/src/internal/Type/persistent-schema.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { IconAnnotation } from '../Annotation';
+import { LabelAnnotation, TypenameSchema, VersionSchema } from '../Annotation';
+import { EchoObjectSchema } from '../Entity';
+import { JsonSchemaType } from '../JsonSchema';
+
+/**
+ * Persistent representation of a schema.
+ */
+// TODO(burdon): Move.
+export const PersistentSchema = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  typename: TypenameSchema,
+  version: VersionSchema,
+  jsonSchema: JsonSchemaType,
+}).pipe(
+  EchoObjectSchema({
+    typename: 'org.dxos.type.schema',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  IconAnnotation.set({
+    icon: 'ph--brackets-curly--regular',
+    hue: 'blue',
+  }),
+);
+
+export interface PersistentSchema extends Schema.Schema.Type<typeof PersistentSchema> {}

package/src/internal/common/README.md

@@ -0,0 +1,102 @@
+## Refactor
+
+1. Remove access from outisde of @dxos/echo-db
+
+- [x] completely restructure @dxos/echo src/internal
+- [x] Remove import "." and ".."! (create lint rule).
+- [x] Unify FOUR different nests of test schema.
+- [x] Remove @deprecated from internal methods and mark @internal (e.g., getSchemaDXN).
+  - NOTE: Internal methods should not use the import \* from Obj/Type APIs.
+- [x] import ObjectId => @dxos/keys
+- [x] Entity.Any = Obj.Any | Relation.Any
+  - NOTE: Relation does not extend (in not polymorphic with) Obj.
+- [x] import LabelAnnotation => Annotation.LabelAnnotation
+- [x] import Expando => @dxos/schema (Expando.Expando)
+- [x] live => Obj.make
+- [x] Rename live => makeObject
+- [x] Rename {EchoObject, EchoRelation} => {EchoObjecSchema, EchoRelationSchema}
+- [x] Rename AnyProperties => AnyProperties
+- [x] Created Entity.Any (=> AnyEchoObject).
+- [x] TypeFormat => TypeFormat
+- [x] JsonSchemaType defs
+- [x] Fix database.add() input/output types and search for "Obj.Any = db.add" (also QueryResult types).
+- [x] TODO(burdon): FIX!!!
+- [x] Fix failing tests.
+- [x] Reconcile types/version with entities/model/version
+- [x] Expando moved to @dxos/schema
+- [x] Narrow QueryResult and match Schema and Object generics.
+
+2. Clean-up
+
+- [x] QueryResult namespace
+- [x] SchemaRegistry interface
+- [x] Schema registry should return Type.AnyEntity instead of Schema.Schema.AnyNoContext.
+- [x] Hypergraph interface
+- [x] Obj.getDatabase
+- [x] SpaceAction.AddObject target should be a db not a space.
+- [x] Add Relation.MakeProps
+- [x] Add Obj.Unknown and Relation.Unknown to match Entity.Unknown.
+- [x] TODO(wittjosiah): Should be Type.obj<...> or equivalent.
+- [x] TODO(wittjosiah): Find a simpler way to define this type.
+- [x] Ref.Array.targets doesn't satisfy Obj.Any because it uses AnyEchoObject.
+- [x] Remove echo-db/AnyLiveObject<T> => Obj.Obj<T>
+- [x] Rename AnyEchoObject => AnyEntity
+- [x] Remove WithId => AnyEntity
+- [x] Remove WithMeta => AnyEntity
+- [x] Obj.Any => Obj.Unknown
+- [x] Relation.Any => Relation.Unknown
+- [x] Ref.Any => Ref.Unknown
+- [x] Obj.AnyProps => Obj.Any
+- [x] Factor Expando out of @dxos/echo (moved to @dxos/schema)
+- [x] Obj.instanceOf works with Expando (tested in @dxos/schema)
+- [x] Obj.Snapshot should be same shape as Obj.Obj but with a different brand
+- [x] Mutators should only work on object after it is made mutable
+
+- [ ] Review usage of Obj.Any, see if it could be stricter
+- [ ] Type.Obj should validate using the echo object brand
+- [ ] Mutable could be a branded type to fix "NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`"
+- [ ] space properties, queues, messagins preventing getSpace from being removed
+- [ ] Schema registry should use Query.Query.
+- [ ] Move EchoSchemaRegistry into hypergraph
+- [ ] Narrow QueryResult and match Schema and Object generics.
+- [ ] BaseSchema
+- [ ] Directly import JSONPath, etc. from @dxos/effect.
+- [ ] Promote parts of src/internal/ref to Ref.ts
+- [ ] JsonPath, JsonProp, getValue, setValue => Json.Path?
+- [ ] DISCUSS: Standradize $ suffix to disambuguate imports (GPT recommended).
+
+3. Audit usage from @dxos/echo-db
+
+- [ ] Ability to extract Struct from Type.Obj
+- [ ] created/updated system props (const { created } = Obj.getTimestamps)?
+- [ ] QueryFn, QueryOptions => Database
+- [ ] Datatbase.query() options?
+- [ ] Expando type is used as a fallback in many plance.
+- [ ] Standardize '@automerge/automerge' imports (A vs. next).
+
+## NOTES
+
+- Marking types as @internal (even for unexported types) erases type information.
+
+## 0.9.0
+
+- [ ] Database, Queue, Space, Type, namespaces.
+- [ ] Support class variant for types.
+- [ ] Support defaults.
+- [ ] Support effect Date, Timestamp formats.
+- [ ] Metadata for created, updated timestamps.
+- [ ] Effect team design review.
+- [ ] @category annotations to group types in the API.
+- [ ] TSdoc and LLM training for function generation.
+- [ ] Rename TypeFormat => Primitive?
+- [ ] Don't re-export effect?
+
+## Issues
+
+- [ ] Build error when changing from TypedObject using Ref$: Type 'Task' does not satisfy the constraint 'WithId' (see echo-schema/testing/schema.ts)
+- [ ] Reconcile all schema variants (Base, Immutable, TypedObject, EchoObject, etc.)
+- [ ] Consolidate getters (getType, getSchema, getTypename, getSchemaTypename, etc.)
+- [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
+- [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
+- [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
+- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).

package/src/internal/common/api/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Shared API helpers for Obj and Relation modules.
+ * These implementations use generic Entity types.
+ * Obj and Relation modules re-export with strongly-typed signatures.
+ *
+ * TODO(wittjosiah): Could this become the new "internal" where we slowly refactor
+ * existing internal modules into here? This would provide a cleaner boundary
+ * and prevent external packages from using internals directly.
+ */
+
+export * from './meta';

package/src/internal/common/api/meta.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { assertArgument, invariant } from '@dxos/invariant';
+import type { DeepReadonly } from '@dxos/util';
+
+import { type Mutable } from '../proxy';
+import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+
+/**
+ * Deeply read-only version of ObjectMeta.
+ */
+export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+
+/**
+ * Mutable meta type received in meta mutation callbacks.
+ */
+export type Meta = Mutable<ObjectMeta>;
+
+/**
+ * Get the metadata for an entity with validation.
+ * Returns mutable meta when passed a mutable entity (inside change callback).
+ * Returns read-only meta when passed a regular entity or snapshot.
+ *
+ * TODO(burdon): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+ */
+export function getMetaChecked(entity: Mutable<AnyProperties>): Meta;
+export function getMetaChecked(entity: AnyProperties): ReadonlyMeta;
+export function getMetaChecked(entity: AnyProperties): Meta | ReadonlyMeta {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMeta$(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta;
+}
+
+/**
+ * @returns Foreign keys for the entity from the specified source.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] => {
+  assertArgument(entity, 'entity', 'Should be an entity.');
+  const meta = getMetaChecked(entity);
+  invariant(meta != null, 'Invalid entity.');
+  return meta.keys.filter((key) => key.source === source);
+};
+
+/**
+ * Delete all keys from the entity for the specified source.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
+  const meta = getMetaChecked(entity);
+  for (let i = 0; i < meta.keys.length; i++) {
+    if (meta.keys[i].source === source) {
+      meta.keys.splice(i, 1);
+      i--;
+    }
+  }
+};
+
+/**
+ * Add a tag to the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  meta.tags ??= [];
+  meta.tags.push(tag);
+};
+
+/**
+ * Remove a tag from the entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+  const meta = getMetaChecked(entity);
+  if (!meta.tags) {
+    return;
+  }
+  for (let i = 0; i < meta.tags.length; i++) {
+    if (meta.tags[i] === tag) {
+      meta.tags.splice(i, 1);
+      i--;
+    }
+  }
+};

package/src/internal/{testing → common}/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './api';
+export * from './proxy';
 export * from './types';
-export * from './utils';

package/src/internal/common/proxy/change-context.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { batchEvents } from './event-batch';
+import { EventId } from './symbols';
+
+/**
+ * Generic change context tracking.
+ * Only one object can be in a change context at a time (synchronous changes).
+ *
+ * This module provides a unified change context mechanism used by both:
+ * - TypedReactiveHandler (for non-database objects, using target as key)
+ * - EchoReactiveHandler (for database objects, using ObjectCore as key)
+ */
+
+/**
+ * The object currently in a change context.
+ * Can be a target object (for typed reactive) or ObjectCore (for database objects).
+ */
+let currentChangeContext: object | null = null;
+
+/**
+ * The primary object that has pending notifications, if any.
+ * This uses the contextKey (target or ObjectCore).
+ */
+let pendingNotificationKey: object | null = null;
+
+/**
+ * Additional objects (owner chain) that need notifications.
+ * These are separate from the primary notification because they use EventId directly.
+ */
+const pendingOwnerNotifications = new Set<object>();
+
+/**
+ * Enter a change context for the given key.
+ * While in a change context, mutations are allowed on the associated object.
+ * Nested Obj.change calls are not supported.
+ *
+ * @param key - The key to enter the change context for (target object or ObjectCore).
+ * @returns A cleanup function that exits the change context.
+ */
+export const enterChangeContext = (key: object): (() => void) => {
+  currentChangeContext = key;
+  return () => {
+    currentChangeContext = null;
+  };
+};
+
+/**
+ * Check if the given key is currently in a change context.
+ *
+ * @param key - The key to check (target object or ObjectCore).
+ * @returns True if the key is in a change context, false otherwise.
+ */
+export const isInChangeContext = (key: object): boolean => {
+  return currentChangeContext === key;
+};
+
+/**
+ * Queue a notification for the given key to be fired when the change context exits.
+ *
+ * @param key - The key to queue a notification for.
+ */
+export const queueNotification = (key: object): void => {
+  if (currentChangeContext === key) {
+    pendingNotificationKey = key;
+  }
+};
+
+/**
+ * Queue an owner notification. Owner notifications are for objects in the ownership
+ * chain that should be notified when a nested object changes.
+ * These objects have EventId and emit directly.
+ * Skip if the target is already the current change context (to avoid duplicate notifications).
+ *
+ * @param target - The owner target that has EventId.
+ */
+export const queueOwnerNotification = (target: object): void => {
+  // Skip if this is the object already being changed (primary notification handles it).
+  if (currentChangeContext !== null && target !== currentChangeContext) {
+    pendingOwnerNotifications.add(target);
+  }
+};
+
+/**
+ * Check if there are any pending notifications for the given key.
+ *
+ * @param key - The key to check.
+ * @returns True if there are pending notifications, false otherwise.
+ */
+export const hasPendingNotifications = (key: object): boolean => {
+  return pendingNotificationKey === key;
+};
+
+/**
+ * Clear any pending notifications for the given key.
+ *
+ * @param key - The key to clear notifications for.
+ */
+export const clearPendingNotifications = (key: object): void => {
+  if (pendingNotificationKey === key) {
+    pendingNotificationKey = null;
+  }
+};
+
+/**
+ * Execute a callback within a change context.
+ * This is the shared implementation used by both TypedReactiveHandler and EchoReactiveHandler.
+ *
+ * @param contextKey - The key for the change context (target for typed, ObjectCore for db).
+ * @param eventTarget - The object that has the EventId for notifications.
+ * @param proxy - The proxy object to pass to the callback.
+ * @param callback - The callback to execute with mutations allowed.
+ */
+export const executeChange = (
+  contextKey: object,
+  eventTarget: object,
+  proxy: any,
+  callback: (proxy: any) => void,
+): void => {
+  const exitContext = enterChangeContext(contextKey);
+  try {
+    batchEvents(() => callback(proxy));
+  } finally {
+    exitContext();
+    // Fire primary notification.
+    if (hasPendingNotifications(contextKey)) {
+      clearPendingNotifications(contextKey);
+      (eventTarget as any)[EventId]?.emit();
+    }
+    // Fire owner chain notifications.
+    for (const ownerTarget of pendingOwnerNotifications) {
+      (ownerTarget as any)[EventId]?.emit();
+    }
+    pendingOwnerNotifications.clear();
+  }
+};