@dxos/echo 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

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,71 +11,30 @@ 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 { Ref } from './internal/Ref/ref';
+import { type AnyProperties } from './internal/common/types';
 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>>;
 }
 
 /**
@@ -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.
@@ -186,151 +150,168 @@ export const isDatabase = (obj: unknown): obj is Database => {
 
 export const Database: Schema.Schema<Database> = Schema.Any.pipe(Schema.filter((space) => isDatabase(space)));
 
+/**
+ * Effect service tag for Database dependency injection.
+ */
 export class Service extends Context.Tag('@dxos/echo/Database/Service')<
   Service,
   {
     readonly db: Database;
   }
->() {
-  static notAvailable = Layer.succeed(Service, {
-    get db(): Database {
-      throw new Error('Database not available');
-    },
-  });
-
-  static make = (db: Database): Context.Tag.Service<Service> => {
-    return {
-      get db() {
-        return db;
-      },
-    };
-  };
+>() {}
 
-  static layer = (db: Database): Layer.Layer<Service> => {
-    return Layer.succeed(Service, Service.make(db));
+/**
+ * Layer that provides a Database service that throws when accessed.
+ * Useful as a default layer when no database is available.
+ */
+export const notAvailable = Layer.succeed(Service, {
+  get db(): Database {
+    throw new Error('Database not available');
+  },
+});
+
+/**
+ * Creates a Database service instance from a Database.
+ */
+export const makeService = (db: Database): Context.Tag.Service<Service> => {
+  return {
+    get db() {
+      return db;
+    },
   };
+};
 
-  // TODO(dmaretskyi): Move all those to the top-level API of Database.ts module.
+/**
+ * Creates a Layer that provides the Database service.
+ */
+export const layer = (db: Database): Layer.Layer<Service> => {
+  return Layer.succeed(Service, makeService(db));
+};
 
-  /**
-   * Returns the space ID of the database.
-   */
-  static spaceId = Effect.gen(function* () {
-    const { db } = yield* Service;
-    return db.spaceId;
-  });
+/**
+ * Returns the space ID of the database.
+ */
+export const spaceId = Effect.gen(function* () {
+  const { db } = yield* Service;
+  return db.spaceId;
+});
 
-  /**
-   * Resolves an object by its DXN.
-   */
-  static resolve: {
-    // No type check.
-    (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
-    // Check matches schema.
-    <S extends Type.Entity.Any>(
-      ref: DXN | Ref<any>,
-      schema: S,
-    ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
-  } = (<S extends Type.Entity.Any>(
+/**
+ * Resolves an object by its DXN.
+ */
+export const resolve: {
+  // No type check.
+  (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
+  // Check matches schema.
+  <S extends Type.AnyEntity>(
     ref: DXN | Ref<any>,
-    schema?: S,
-  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
-    Effect.gen(function* () {
-      const { db } = yield* Service;
-      const dxn = ref instanceof DXN ? ref : ref.dxn;
-      const object = yield* promiseWithCauseCapture(() =>
-        db.graph
-          .createRefResolver({
-            context: {
-              space: db.spaceId,
-            },
-          })
-          .resolve(dxn),
-      );
-
-      if (!object) {
-        return yield* Effect.fail(new Err.ObjectNotFoundError(dxn));
-      }
-      invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
-      return object as any;
-    })) as any;
+    schema: S,
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
+} = (<S extends Type.AnyEntity>(
+  ref: DXN | Ref<any>,
+  schema?: S,
+): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
+  Effect.gen(function* () {
+    const { db } = yield* Service;
+    const dxn = ref instanceof DXN ? ref : ref.dxn;
+    const object = yield* promiseWithCauseCapture(() =>
+      db.graph
+        .createRefResolver({
+          context: {
+            space: db.spaceId,
+          },
+        })
+        .resolve(dxn),
+    );
 
-  /**
-   * Loads an object reference.
-   */
-  static 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 yield* Effect.fail(new Err.ObjectNotFoundError(dxn));
     }
-    return object;
-  });
+    invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
+    return object as any;
+  })) as any;
 
-  /**
-   * Loads an object reference option.
-   */
-  // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-  static loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
-    const object = yield* Service.load(ref).pipe(
-      Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)),
-    );
+/**
+ * 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;
+});
 
-    return Option.fromNullable(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) {
+  const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
 
-  /**
-   * @link EchoDatabase.add
-   */
-  static add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>
-    Service.pipe(Effect.map(({ db }) => db.add(obj)));
+  return Option.fromNullable(object);
+});
 
-  /**
-   * @link EchoDatabase.remove
-   */
-  static remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-    Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+/**
+ * Adds an object to the database.
+ * @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)));
 
-  /**
-   * @link EchoDatabase.flush
-   */
-  static flush = (opts?: FlushOptions) =>
-    Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+/**
+ * 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)));
 
-  /**
-   * Creates a `QueryResult` object that can be subscribed to.
-   */
-  static query: {
-    <Q extends Query.Any>(query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;
-    <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
-  } = (queryOrFilter: Query.Any | Filter.Any) =>
-    Service.pipe(
-      Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),
-      Effect.withSpan('Service.query'),
-    );
+/**
+ * Flushes pending changes to disk.
+ * @see {@link Database.flush}
+ */
+export const flush = (opts?: FlushOptions) =>
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
 
-  /**
-   * Executes the query once and returns the results.
-   */
-  static 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) =>
-    Service.query(queryOrFilter as any).pipe(
-      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
-    );
+/**
+ * Creates a `QueryResult` object that can be subscribed to.
+ */
+export const query: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  Service.pipe(
+    Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),
+    Effect.withSpan('Database.query'),
+  );
 
-  // TODO(dmaretskyi): Change API to `yield* Service.querySchema(...).first` and `yield* Service.querySchema(...).schema`.
+/**
+ * Executes the query once and returns the results.
+ */
+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())));
 
-  static schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
-    query?: Q & SchemaRegistry.Query,
-  ): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>
-    Service.pipe(
-      Effect.map(({ db }) => db.schemaRegistry.query(query)),
-      Effect.withSpan('Service.schemaQuery'),
-    );
+/**
+ * Creates a schema query result that can be subscribed to.
+ */
+// TODO(dmaretskyi): Change API to `yield* Database.querySchema(...).first` and `yield* Database.querySchema(...).schema`.
+export const schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+  schemaQueryOptions?: Q & SchemaRegistry.Query,
+): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>
+  Service.pipe(
+    Effect.map(({ db }) => db.schemaRegistry.query(schemaQueryOptions)),
+    Effect.withSpan('Database.schemaQuery'),
+  );
 
-  static runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
-    query?: Q & SchemaRegistry.Query,
-  ): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>
-    Service.schemaQuery(query).pipe(Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())));
-}
+/**
+ * Executes a schema query once and returns the results.
+ */
+export const runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(
+  schemaQueryOptions?: Q & SchemaRegistry.Query,
+): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>
+  schemaQuery(schemaQueryOptions).pipe(
+    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+  );

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 entityInternal from './internal/Entity';
+import * as internal from './internal';
+import type * as Relation from './Relation';
 
 // 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,27 @@ 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 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 +148,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);
 };
 
 //
@@ -174,7 +194,7 @@ export const subscribe = (entity: Unknown, callback: () => void): (() => void) =
 /**
  * Used to provide a mutable view of an entity within `Entity.change`.
  */
-export type { Mutable };
+export type Mutable<T> = internal.Mutable<T>;
 
 /**
  * Perform mutations on an entity (object or relation) within a change context.
@@ -200,18 +220,18 @@ export type { Mutable };
  *
  * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
  */
-export const change = <T extends Unknown>(entity: T, callback: ChangeCallback<T>): void => {
-  change$(entity, callback);
+export const change = <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.
  */
-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.
  */
-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);

package/src/Err.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import { BaseError, type BaseErrorOptions } from '@dxos/errors';
 import { type DXN } from '@dxos/keys';
 
@@ -16,3 +18,23 @@ export class ObjectNotFoundError extends BaseError.extend('ObjectNotFoundError',
     super({ context: { dxn }, ...options });
   }
 }
+
+/**
+ * Reason why getting a reactive object from a snapshot failed.
+ * - `no-database`: The snapshot is not associated with a database.
+ * - `object-not-found`: The object was removed or does not exist in the database.
+ */
+export type GetReactiveErrorReason = 'no-database' | 'object-not-found';
+
+/**
+ * Error thrown when a reactive object cannot be resolved from a snapshot.
+ * Extends `BaseError` with a `reason` and optional `snapshotId` in its context.
+ */
+export class GetReactiveError extends BaseError.extend(
+  'GetReactiveError',
+  'Failed to get reactive object from snapshot',
+) {
+  constructor(options: { reason: GetReactiveErrorReason; snapshotId?: string } & BaseErrorOptions) {
+    super({ context: { reason: options.reason, snapshotId: options.snapshotId }, ...options });
+  }
+}