@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.f466a3d56e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.ef1bc66f44",
+  "version": "0.8.4-main.f466a3d56e",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -48,6 +48,11 @@
       "types": "./dist/types/src/Err.d.ts",
       "default": "./dist/lib/neutral/Err.mjs"
     },
+    "./Feed": {
+      "source": "./src/Feed.ts",
+      "types": "./dist/types/src/Feed.d.ts",
+      "default": "./dist/lib/neutral/Feed.mjs"
+    },
     "./Filter": {
       "source": "./src/Filter.ts",
       "types": "./dist/types/src/Filter.d.ts",
@@ -68,6 +73,11 @@
       "types": "./dist/types/src/Key.d.ts",
       "default": "./dist/lib/neutral/Key.mjs"
     },
+    "./Migration": {
+      "source": "./src/Migration.ts",
+      "types": "./dist/types/src/Migration.d.ts",
+      "default": "./dist/lib/neutral/Migration.mjs"
+    },
     "./Obj": {
       "source": "./src/Obj.ts",
       "types": "./dist/types/src/Obj.d.ts",
@@ -112,6 +122,11 @@
       "source": "./src/Type.ts",
       "types": "./dist/types/src/Type.d.ts",
       "default": "./dist/lib/neutral/Type.mjs"
+    },
+    "./Extension": {
+      "source": "./src/Extension.ts",
+      "types": "./dist/types/src/Extension.d.ts",
+      "default": "./dist/lib/neutral/Extension.mjs"
     }
   },
   "files": [
@@ -119,19 +134,19 @@
     "src"
   ],
   "dependencies": {
-    "effect": "3.19.16",
-    "@dxos/async": "0.8.4-main.ef1bc66f44",
-    "@dxos/debug": "0.8.4-main.ef1bc66f44",
-    "@dxos/context": "0.8.4-main.ef1bc66f44",
-    "@dxos/effect": "0.8.4-main.ef1bc66f44",
-    "@dxos/echo-protocol": "0.8.4-main.ef1bc66f44",
-    "@dxos/errors": "0.8.4-main.ef1bc66f44",
-    "@dxos/invariant": "0.8.4-main.ef1bc66f44",
-    "@dxos/log": "0.8.4-main.ef1bc66f44",
-    "@dxos/protocols": "0.8.4-main.ef1bc66f44",
-    "@dxos/keys": "0.8.4-main.ef1bc66f44",
-    "@dxos/node-std": "0.8.4-main.ef1bc66f44",
-    "@dxos/util": "0.8.4-main.ef1bc66f44"
+    "effect": "3.20.0",
+    "@dxos/context": "0.8.4-main.f466a3d56e",
+    "@dxos/debug": "0.8.4-main.f466a3d56e",
+    "@dxos/echo-protocol": "0.8.4-main.f466a3d56e",
+    "@dxos/effect": "0.8.4-main.f466a3d56e",
+    "@dxos/errors": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e",
+    "@dxos/keys": "0.8.4-main.f466a3d56e",
+    "@dxos/log": "0.8.4-main.f466a3d56e",
+    "@dxos/node-std": "0.8.4-main.f466a3d56e",
+    "@dxos/protocols": "0.8.4-main.f466a3d56e",
+    "@dxos/util": "0.8.4-main.f466a3d56e",
+    "@dxos/async": "0.8.4-main.f466a3d56e"
   },
   "publishConfig": {
     "access": "public"

package/src/Annotation.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 export {
   DescriptionAnnotation,
   FormInputAnnotation,
@@ -15,11 +17,13 @@ export {
   getTypeAnnotation,
   setDescriptionWithSchema,
   setLabelWithSchema,
-} from './internal/annotations';
+  IconAnnotation,
+  IconFromRefAnnotation,
+} from './internal/Annotation';
 
 import type * as Schema from 'effect/Schema';
 
-import * as internalAnnotations from './internal/annotations';
+import * as internalAnnotations from './internal/Annotation';
 
 interface MakeProps<T> {
   id: string;
@@ -34,7 +38,7 @@ interface MakeProps<T> {
  * @example
  * ```ts
  * const ColorAnnotation = Annotation.make({
- *   id: 'dxos.org/annotation/Color',
+ *   id: 'org.dxos.annotation.color',
  *   schema: Schema.String,
  * });
  *

package/src/Collection.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import * as Annotation from './Annotation';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Ref from './Ref';
+import * as Type from './Type';
+
+/**
+ * A an ordered set of objects.
+ */
+export const Collection = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.collection',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--folder--regular',
+    hue: 'amber',
+  }),
+);
+
+export interface Collection extends Schema.Schema.Type<typeof Collection> {}
+
+export const make = (props: Partial<Obj.MakeProps<typeof Collection>> = {}): Collection =>
+  Obj.make(Collection, { objects: [], ...props });
+
+export const isCollection: (value: unknown) => value is Collection = Obj.instanceOf(Collection);

package/src/Database.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
@@ -9,75 +11,34 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 
-import { type QueryAST } from '@dxos/echo-protocol';
 import { promiseWithCauseCapture } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { DXN, type PublicKey, type SpaceId } from '@dxos/keys';
-import { type QueryOptions as QueryOptionsProto } from '@dxos/protocols/proto/dxos/echo/filter';
+import { DXN, type SpaceId } from '@dxos/keys';
 
 import type * as Entity from './Entity';
 import * as Err from './Err';
 import type * as Filter from './Filter';
 import type * as Hypergraph from './Hypergraph';
-import { isInstanceOf } from './internal/annotations';
-import type { Ref } from './internal/ref/ref';
-import { type AnyProperties } from './internal/types';
+import { isInstanceOf } from './internal/Annotation';
+import { type AnyProperties } from './internal/common/types';
+import type { Ref } from './internal/Ref/ref';
 import type * as Obj from './Obj';
 import type * as Query from './Query';
 import type * as QueryResult from './QueryResult';
 import type * as SchemaRegistry from './SchemaRegistry';
 import type * as Type from './Type';
 
-/**
- * @deprecated Use `QueryAST.QueryOptions` instead.
- */
-export type QueryOptions = {
-  /**
-   * @deprecated Use `spaceIds` instead.
-   */
-  spaces?: PublicKey[];
-
-  /**
-   * Query only in specific spaces.
-   */
-  // TODO(dmaretskyi): Change this to SpaceId.
-  spaceIds?: string[];
-
-  /**
-   * Return only the first `limit` results.
-   */
-  limit?: number;
-
-  /**
-   * Query only local spaces, or remote on agent.
-   * @default `QueryOptions.DataLocation.LOCAL`
-   *
-   * Options:
-   *   - proto3_optional = true
-   */
-  // TODO(burdon): Remove?
-  dataLocation?: QueryOptionsProto.DataLocation;
-};
-
 /**
  * `query` API function declaration.
  */
 // TODO(burdon): Reconcile Query and Filter (should only have one root type).
-// TODO(dmaretskyi): Remove query options.
 export interface QueryFn {
-  <Q extends Query.Any>(
-    query: Q,
-    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
-  ): QueryResult.QueryResult<Query.Type<Q>>;
-
-  <F extends Filter.Any>(
-    filter: F,
-    options?: (QueryAST.QueryOptions & QueryOptions) | undefined,
-  ): QueryResult.QueryResult<Filter.Type<F>>;
+  <Q extends Query.Any>(query: Q): QueryResult.QueryResult<Query.Type<Q>>;
+  <F extends Filter.Any>(filter: F): QueryResult.QueryResult<Filter.Type<F>>;
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;
@@ -110,7 +71,7 @@ export type FlushOptions = {
 
   /**
    * Wait for pending index updates.
-   * @default false
+   * @default true
    */
   indexes?: boolean;
 
@@ -145,7 +106,10 @@ export interface Database extends Queryable {
   /**
    * Return object by local ID.
    */
-  getObjectById<T extends Obj.Unknown = Obj.Obj<AnyProperties>>(id: string, opts?: GetObjectByIdOptions): T | undefined;
+  getObjectById<T extends Obj.Unknown = Obj.OfShape<AnyProperties>>(
+    id: string,
+    opts?: GetObjectByIdOptions,
+  ): T | undefined;
 
   /**
    * Query objects.
@@ -239,11 +203,11 @@ export const resolve: {
   // No type check.
   (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
   // Check matches schema.
-  <S extends Type.Entity.Any>(
+  <S extends Type.AnyEntity>(
     ref: DXN | Ref<any>,
     schema: S,
   ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
-} = (<S extends Type.Entity.Any>(
+} = (<S extends Type.AnyEntity>(
   ref: DXN | Ref<any>,
   schema?: S,
 ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
@@ -265,24 +229,28 @@ export const resolve: {
     }
     invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
     return object as any;
-  })) as any;
+  }).pipe(Effect.withSpan('Database.resolve'))) as any;
 
 /**
  * Loads an object reference.
  */
-export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn(function* (ref) {
-  const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
-  if (!object) {
-    return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
-  }
-  return object;
-});
+export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn('Database.load')(
+  function* (ref) {
+    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
+    }
+    return object;
+  },
+);
 
 /**
  * Loads an object reference option.
  */
 // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(
+  'Database.loadOption',
+)(function* (ref) {
   const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
 
   return Option.fromNullable(object);
@@ -293,21 +261,23 @@ export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, nev
  * @see {@link Database.add}
  */
 export const add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.add(obj)));
+  Service.pipe(Effect.map(({ db }) => db.add(obj))).pipe(Effect.withSpan('Database.add'));
 
 /**
  * Removes an object from the database.
  * @see {@link Database.remove}
  */
 export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));
 
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}
  */
 export const flush = (opts?: FlushOptions) =>
-  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+    Effect.withSpan('Database.flush'),
+  );
 
 /**
  * Creates a `QueryResult` object that can be subscribed to.
@@ -328,7 +298,36 @@ export const runQuery: {
   <Q extends Query.Any>(query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;
   <F extends Filter.Any>(filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;
 } = (queryOrFilter: Query.Any | Filter.Any) =>
-  query(queryOrFilter as any).pipe(Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())));
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    Effect.withSpan('Database.runQuery'),
+  );
+
+/**
+ * Executes the query once and returns the first result as or None.
+ */
+export const runQueryFirst: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<Option.Option<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<Option.Option<Filter.Type<F>>, never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) =>
+      promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),
+    ),
+    Effect.withSpan('Database.runQueryFirst'),
+  );
+
+/**
+ * Persists schemas in the database so they replicate to other clients.
+ * @see {@link SchemaRegistry.SchemaRegistry.register}
+ */
+export const registerSchema = (
+  input: SchemaRegistry.RegisterSchemaInput[],
+): Effect.Effect<Type.RuntimeType[], never, Service> =>
+  Service.pipe(
+    Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.schemaRegistry.register(input))),
+    Effect.withSpan('Database.registerSchema'),
+  );
 
 /**
  * Creates a schema query result that can be subscribed to.

package/src/Dataset.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { pipe } from 'effect/Function';
+import * as Predicate from 'effect/Predicate';
+import * as Schema from 'effect/Schema';
+
+import * as Collection from './Collection';
+import * as Feed from './Feed';
+import * as Obj from './Obj';
+import * as View from './View';
+
+/**
+ * Abstart set of objects, represented by a view, feed, or collection.
+ */
+export const Dataset = Schema.Union(Feed.Feed, Collection.Collection, View.View);
+export type Dataset = Feed.Feed | Collection.Collection | View.View;
+
+export const isDataset: (value: unknown) => value is Dataset = pipe(
+  Obj.instanceOf(Feed.Feed),
+  Predicate.or(Obj.instanceOf(Collection.Collection)),
+  Predicate.or(Obj.instanceOf(View.View)),
+);

package/src/Entity.ts

@@ -2,46 +2,28 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type { ForeignKey } from '@dxos/echo-protocol';
 import type { DXN, ObjectId } from '@dxos/keys';
 
-import {
-  type ChangeCallback,
-  EntityKind,
-  EntityKindSchema,
-  KindId,
-  type Mutable,
-  type ObjectJSON,
-  type ObjectMeta,
-  type ReadonlyMeta,
-  SnapshotKindId,
-  addTag as addTag$,
-  change as change$,
-  getDXN as getDXN$,
-  getDatabase as getDatabase$,
-  getDescription as getDescription$,
-  getEntityKind,
-  getKeys as getKeys$,
-  getLabel as getLabel$,
-  getMetaChecked as getMeta$,
-  getTypeDXN as getTypeDXN$,
-  getTypename as getTypename$,
-  isDeleted as isDeleted$,
-  removeTag as removeTag$,
-  subscribe as subscribe$,
-  objectToJSON as toJSON$,
-} from './internal';
+import * as internal from './internal';
+import type * as Relation from './Relation';
+import type * as Type from './Type';
 
 // Re-export KindId and SnapshotKindId from internal.
-export { KindId, SnapshotKindId };
+export const KindId = internal.KindId;
+export type KindId = typeof internal.KindId;
+export const SnapshotKindId = internal.SnapshotKindId;
+export type SnapshotKindId = typeof internal.SnapshotKindId;
 
 // NOTE: Relation does not extend Obj so that, for example, we can prevent Relations from being used as source and target objects.
 //  However, we generally refer to Obj and Relation instances as "objects",
 //  and many API methods accept both Obj.Unknown and Relation.Unknown (i.e., Entity.Unknown) instances.
 
-export const Kind = EntityKind;
-export type Kind = EntityKind;
-export const KindSchema = EntityKindSchema;
+export const Kind = internal.EntityKind;
+export type Kind = internal.EntityKind;
+export const KindSchema = internal.EntityKindSchema;
 
 /**
  * Assigns a kind to an Object or Relation instance.
@@ -89,7 +71,45 @@ export interface Any extends OfKind<Kind> {
   [key: string]: unknown;
 }
 
-export const getKind = getEntityKind;
+/**
+ * Returns all properties of an object or relation except for the id and kind.
+ */
+export type Properties<T> = Omit<T, 'id' | KindId | Relation.Source | Relation.Target>;
+
+/**
+ * Check if a value is an ECHO entity (object or relation).
+ * Returns `false` for snapshots.
+ */
+export const isEntity = (value: unknown): value is Unknown => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[KindId] !== undefined;
+};
+
+/**
+ * Check if a value is an ECHO entity snapshot.
+ * Returns `false` for entities.
+ */
+export const isSnapshot = (value: unknown): value is Snapshot => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  return (value as any)[SnapshotKindId] !== undefined;
+};
+
+// TODO(dmaretskyi): Type introspection -- move to kind.
+export const getKind = internal.getEntityKind;
+
+/**
+ * Property that accesses metadata for an entity.
+ */
+export const Meta: unique symbol = internal.MetaId as any;
+
+/**
+ * Property that accesses metadata for an entity.
+ */
+export type Meta = typeof Meta;
 
 //
 // Entity-level functions that work on any entity (object or relation).
@@ -100,27 +120,33 @@ export const getKind = getEntityKind;
 /**
  * JSON representation of an entity.
  */
-export type JSON = ObjectJSON;
+export type JSON = internal.ObjectJSON;
 
 /**
  * Get the DXN of an entity (object or relation).
  */
-export const getDXN = (entity: Unknown | Snapshot): DXN => getDXN$(entity);
+export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entity);
 
 /**
  * Get the DXN of an entity's type.
  */
-export const getTypeDXN = getTypeDXN$;
+export const getTypeDXN = internal.getTypeDXN;
+
+/**
+ * Get the schema of an entity.
+ * Returns the branded ECHO schema used to create the entity.
+ */
+export const getSchema: (entity: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
 
 /**
  * Get the typename of an entity's type.
  */
-export const getTypename = (entity: Unknown | Snapshot): string | undefined => getTypename$(entity);
+export const getTypename = (entity: Unknown | Snapshot): string | undefined => internal.getTypename(entity);
 
 /**
  * Get the database an entity belongs to.
  */
-export const getDatabase = (entity: Unknown | Snapshot): any | undefined => getDatabase$(entity);
+export const getDatabase = (entity: Unknown | Snapshot): any | undefined => internal.getDatabase(entity);
 
 /**
  * Get the metadata for an entity.
@@ -128,43 +154,43 @@ export const getDatabase = (entity: Unknown | Snapshot): any | undefined => getD
  * Returns read-only meta when passed a regular entity or snapshot.
  */
 // TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
-export function getMeta(entity: Mutable<Unknown>): ObjectMeta;
-export function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
-export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): ObjectMeta | ReadonlyMeta {
-  return getMeta$(entity);
+export function getMeta(entity: Mutable<Unknown>): internal.ObjectMeta;
+export function getMeta(entity: Unknown | Snapshot): internal.ReadonlyMeta;
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): internal.ObjectMeta | internal.ReadonlyMeta {
+  return internal.getMetaChecked(entity);
 }
 
 /**
  * Get foreign keys for an entity from the specified source.
  */
-export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[] => getKeys$(entity, source);
+export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[] => internal.getKeys(entity, source);
 
 /**
  * Check if an entity is deleted.
  */
-export const isDeleted = (entity: Unknown | Snapshot): boolean => isDeleted$(entity);
+export const isDeleted = (entity: Unknown | Snapshot): boolean => internal.isDeleted(entity);
 
 /**
  * Get the label of an entity.
  */
-export const getLabel = (entity: Unknown | Snapshot): string | undefined => getLabel$(entity);
+export const getLabel = (entity: Unknown | Snapshot): string | undefined => internal.getLabel(entity);
 
 /**
  * Get the description of an entity.
  */
-export const getDescription = (entity: Unknown | Snapshot): string | undefined => getDescription$(entity);
+export const getDescription = (entity: Unknown | Snapshot): string | undefined => internal.getDescription(entity);
 
 /**
  * Convert an entity to its JSON representation.
  */
-export const toJSON = (entity: Unknown | Snapshot): JSON => toJSON$(entity);
+export const toJSON = (entity: Unknown | Snapshot): JSON => internal.objectToJSON(entity);
 
 /**
  * Subscribe to changes on an entity (object or relation).
  * @returns Unsubscribe function.
  */
 export const subscribe = (entity: Unknown, callback: () => void): (() => void) => {
-  return subscribe$(entity, callback);
+  return internal.subscribe(entity, callback);
 };
 
 //
@@ -172,15 +198,15 @@ export const subscribe = (entity: Unknown, callback: () => void): (() => void) =
 //
 
 /**
- * Used to provide a mutable view of an entity within `Entity.change`.
+ * Used to provide a mutable view of an entity within `Entity.update`.
  */
-export type { Mutable };
+export type Mutable<T> = internal.Mutable<T>;
 
 /**
  * Perform mutations on an entity (object or relation) within a change context.
  *
  * Entities are read-only by default. Mutations are batched and notifications fire
- * when the callback completes. Direct mutations outside of `Entity.change` will throw
+ * when the callback completes. Direct mutations outside of `Entity.update` will throw
  * at runtime.
  *
  * @param entity - The echo entity (object or relation) to mutate.
@@ -188,30 +214,30 @@ export type { Mutable };
  *
  * @example
  * ```typescript
- * // Mutate within Entity.change
- * Entity.change(entity, (e) => {
- *   e.name = 'Updated';
- *   e.count = 42;
+ * // Mutate within Entity.update
+ * Entity.update(entity, (obj) => {
+ *   obj.name = 'Updated';
+ *   obj.count = 42;
  * });
  *
  * // Direct mutation throws
- * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.update()
  * ```
  *
- * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ * Note: For type-specific operations, prefer `Obj.update` or `Relation.update`.
  */
-export const change = <T extends Unknown>(entity: T, callback: ChangeCallback<T>): void => {
-  change$(entity, callback);
+export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCallback<T>): void => {
+  internal.change(entity, callback);
 };
 
 /**
  * Add a tag to an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
-export const addTag = (entity: Mutable<Unknown>, tag: string): void => addTag$(entity, tag);
+export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from an entity.
- * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
-export const removeTag = (entity: Mutable<Unknown>, tag: string): void => removeTag$(entity, tag);
+export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);