@dxos/echo 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/src/Entity.ts

@@ -4,12 +4,16 @@
 
 // @import-as-namespace
 
+import * as Schema from 'effect/Schema';
+
 import type { ForeignKey } from '@dxos/echo-protocol';
-import type { DXN, ObjectId } from '@dxos/keys';
+import type { EntityId, URI } from '@dxos/keys';
 
 import * as internal from './internal';
+import type * as Ref from './Ref';
 import type * as Relation from './Relation';
-import type * as Type from './Type';
+import type * as Tag from './Tag';
+import * as Type from './Type';
 
 // Re-export KindId and SnapshotKindId from internal.
 export const KindId = internal.KindId;
@@ -31,7 +35,7 @@ export const KindSchema = internal.EntityKindSchema;
  */
 export interface OfKind<K extends Kind> {
   readonly [KindId]: K;
-  readonly id: ObjectId;
+  readonly id: EntityId;
 }
 
 /**
@@ -39,7 +43,7 @@ export interface OfKind<K extends Kind> {
  */
 export interface SnapshotOfKind<K extends Kind> {
   readonly [SnapshotKindId]: K;
-  readonly id: ObjectId;
+  readonly id: EntityId;
 }
 
 /**
@@ -52,6 +56,27 @@ export type Entity<Props> = OfKind<Kind> & Props;
  */
 export interface Unknown extends OfKind<Kind> {}
 
+/**
+ * Effect Schema for any ECHO entity (object or relation).
+ *
+ * Kind-agnostic counterpart to `Obj.Unknown` / `Relation.Unknown` — validates
+ * the structural shape (id + properties) without constraining `[KindId]`. Used
+ * in operation input schemas that accept any entity flavour (e.g.
+ * `Schema.Array(Entity.Unknown)`).
+ *
+ * The cast bridges the runtime structural schema to the branded `Unknown` type:
+ * `[KindId]` is a symbol brand that can't be expressed in a runtime `Struct`,
+ * so the entity guarantee is carried at the type level only (same approach as
+ * `Obj.Unknown` / `Relation.Unknown`). Unlike those, this is kind-agnostic so it
+ * isn't an `UnknownTypeSchema<_, K>` (there's no single `K`) and carries no
+ * `TypeAnnotation`.
+ */
+export const Unknown: Schema.Schema<Unknown> = Schema.Struct({
+  id: Schema.String,
+}).pipe(
+  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+) as unknown as Schema.Schema<Unknown>;
+
 /**
  * Snapshot of an Obj or Relation.
  * Branded with SnapshotKindId instead of KindId.
@@ -80,12 +105,30 @@ export type Properties<T> = Omit<T, 'id' | KindId | Relation.Source | Relation.T
  * 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;
+export const isEntity: (value: unknown) => value is Unknown = internal.isEntity;
+
+/**
+ * Test if a value is an instance of a given object or relation type.
+ *
+ * Kind-agnostic counterpart to `Obj.instanceOf` / `Relation.instanceOf` —
+ * use this when the caller's input type is `Type.AnyObj | Type.AnyRelation`.
+ *
+ * @example
+ * ```ts
+ * // Caller doesn't know whether `type` is object- or relation-kind.
+ * const matches = <T extends Type.AnyObj | Type.AnyRelation>(type: T, value: unknown) =>
+ *   Entity.instanceOf(type, value);
+ * ```
+ */
+export const instanceOf: {
+  <S extends Type.AnyEntity>(schema: S): (value: unknown) => value is Type.InstanceType<S>;
+  <S extends Type.AnyEntity>(schema: S, value: unknown): value is Type.InstanceType<S>;
+} = ((...args: [schema: Type.AnyEntity, value?: unknown]) => {
+  if (args.length === 1) {
+    return (entity: unknown) => internal.isInstanceOf(args[0], entity);
   }
-  return (value as any)[KindId] !== undefined;
-};
+  return internal.isInstanceOf(args[0], args[1]);
+}) as any;
 
 /**
  * Check if a value is an ECHO entity snapshot.
@@ -123,25 +166,58 @@ export type Meta = typeof Meta;
 export type JSON = internal.ObjectJSON;
 
 /**
- * Get the DXN of an entity (object or relation).
+ * Whether the entity is a type-kind entity (a `Type.Type` produced by
+ * `Type.makeObject` / `Type.makeRelation`, or a persisted schema). Type entities
+ * carry their identity (typename/version) on themselves rather than referencing a
+ * separate type, so the accessors below route them through the `Type.*` module.
  */
-export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entity);
+const isTypeEntity = (entity: unknown): boolean => internal.getEntityKindBrand(entity) === internal.EntityKind.Type;
 
 /**
- * Get the DXN of an entity's type.
+ * Any value the read accessors operate on: a reactive entity or a snapshot.
+ * Type entities (`Type.AnyEntity`) are also accepted — they're first-class
+ * entities, and `Unknown`'s kind-agnostic brand already subsumes them.
  */
-export const getTypeDXN = internal.getTypeDXN;
+export type AnyInput = Unknown | Snapshot;
 
 /**
- * Get the schema of an entity.
- * Returns the branded ECHO schema used to create the entity.
+ * Get the canonical URI of an entity (object, relation, or type). Returns `URI.URI` —
+ * an `EID` for object/relation instances and persisted types, or a typename
+ * `DXN` for static type entities; narrow with `EID.parse(uri)` or
+ * `DXN.tryMake(uri)` at the point of use.
  */
-export const getSchema: (entity: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
+export const getURI = (entity: AnyInput): URI.URI =>
+  isTypeEntity(entity) ? Type.getURI(entity as Type.AnyEntity) : internal.getUri(entity as Unknown);
 
 /**
- * Get the typename of an entity's type.
+ * Get the DXN of an entity's type. For object/relation instances this is the URI
+ * of the type they were created from; for a type entity it is the URI of the
+ * meta-type ({@link Type.Type}, `dxn:org.dxos.type.schema:0.1.0`).
  */
-export const getTypename = (entity: Unknown | Snapshot): string | undefined => internal.getTypename(entity);
+export const getTypeURI = (entity: AnyInput): URI.URI | undefined =>
+  isTypeEntity(entity) ? Type.getURI(Type.Type) : internal.getTypeURI(entity as Unknown);
+
+/**
+ * Get the type entity (`Type.AnyEntity`) the instance was created from.
+ *
+ * Returns `undefined` when the entity's type isn't registered in this runtime
+ * (e.g. a freshly deserialized snapshot whose type entity hasn't been wired
+ * up yet, or an entity loaded from storage before its schema is known). To
+ * get the Effect Schema from the returned entity, use `Type.getSchema(...)`.
+ *
+ * For a type entity, returns the meta-type {@link Type.Type} (a type entity's
+ * type is "Type").
+ */
+export const getType = (entity: AnyInput): Type.AnyEntity | undefined =>
+  isTypeEntity(entity) ? Type.Type : (internal.getType(entity) as Type.AnyEntity | undefined);
+
+/**
+ * Get the typename of an entity's type. For object/relation instances this is the
+ * typename of the type they were created from; for a type entity it is the type's
+ * own typename (e.g. `com.example.type.person`).
+ */
+export const getTypename = (entity: AnyInput): string | undefined =>
+  isTypeEntity(entity) ? Type.getTypename(entity as Type.AnyEntity) : internal.getTypename(entity as Unknown);
 
 /**
  * Get the database an entity belongs to.
@@ -154,9 +230,9 @@ export const getDatabase = (entity: Unknown | Snapshot): any | undefined => inte
  * 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>): internal.ObjectMeta;
+export function getMeta(entity: Mutable<Unknown>): internal.EntityMeta;
 export function getMeta(entity: Unknown | Snapshot): internal.ReadonlyMeta;
-export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): internal.ObjectMeta | internal.ReadonlyMeta {
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): internal.EntityMeta | internal.ReadonlyMeta {
   return internal.getMetaChecked(entity);
 }
 
@@ -172,14 +248,31 @@ export const isDeleted = (entity: Unknown | Snapshot): boolean => internal.isDel
 
 /**
  * Get the label of an entity.
+ *
+ * @param options.fallback `'typename'` returns the entity's typename when no
+ *   label is set (e.g. `org.dxos.type.table`).
+ */
+export const getLabel = (entity: Unknown | Snapshot, options?: internal.GetLabelOptions): string | undefined =>
+  internal.getLabel(entity, options);
+
+/**
+ * Set the label of an entity.
+ * Must be called within an `Entity.update` / `Obj.update` / `Relation.update` callback.
  */
-export const getLabel = (entity: Unknown | Snapshot): string | undefined => internal.getLabel(entity);
+export const setLabel = (entity: Mutable<Unknown>, label: string): void => internal.setLabel(entity, label);
 
 /**
  * Get the description of an entity.
  */
 export const getDescription = (entity: Unknown | Snapshot): string | undefined => internal.getDescription(entity);
 
+/**
+ * Get the icon annotation for an entity (object or relation), resolved via its type-level
+ * `IconAnnotation`. Returns the full `{ icon, hue }` annotation so callers can use both
+ * the phosphor icon name and the suggested colour.
+ */
+export const getIcon = (entity: Unknown | Snapshot): internal.IconAnnotation | undefined => internal.getIcon(entity);
+
 /**
  * Convert an entity to its JSON representation.
  */
@@ -234,10 +327,10 @@ export const update = <T extends Unknown>(entity: T, callback: internal.ChangeCa
  * Add a tag to an entity.
  * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
-export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
+export const addTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from an entity.
  * Must be called within an `Entity.update`, `Obj.update`, or `Relation.update` callback.
  */
-export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);
+export const removeTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.removeTag(entity, tag);

package/src/Err.ts

@@ -5,7 +5,7 @@
 // @import-as-namespace
 
 import { BaseError, type BaseErrorOptions } from '@dxos/errors';
-import { type DXN } from '@dxos/keys';
+import { type URI } from '@dxos/keys';
 
 export class SchemaNotFoundError extends BaseError.extend('SchemaNotFoundError', 'Schema not found') {
   constructor(schema: string, options?: BaseErrorOptions) {
@@ -13,9 +13,9 @@ export class SchemaNotFoundError extends BaseError.extend('SchemaNotFoundError',
   }
 }
 
-export class ObjectNotFoundError extends BaseError.extend('ObjectNotFoundError', 'Object not found') {
-  constructor(dxn: DXN, options?: BaseErrorOptions) {
-    super({ context: { dxn }, ...options });
+export class EntityNotFoundError extends BaseError.extend('EntityNotFoundError', 'Entity not found') {
+  constructor(uri: URI.URI, options?: BaseErrorOptions) {
+    super({ context: { uri }, ...options });
   }
 }
 

package/src/Feed.ts

@@ -10,7 +10,7 @@ import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
-import { DXN } from '@dxos/keys';
+import { DXN, EID } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import type * as Entity from './Entity';
@@ -43,21 +43,15 @@ export const Feed = Schema.Struct({
    */
   namespace: Schema.optional(Schema.Literal('data', 'trace')),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.feed',
-    version: '0.1.0',
-  }),
-  internal.SystemTypeAnnotation.set(true),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--rows--regular',
-    hue: 'yellow',
-  }),
+  internal.HiddenAnnotation.set(true),
+  Annotation.IconAnnotation.set({ icon: 'ph--rows--regular', hue: 'yellow' }),
+  Type.makeObject(DXN.make('org.dxos.type.feed', '0.1.0')),
 );
 
 /**
  * TypeScript instance type for a Feed object.
  */
-export interface Feed extends Schema.Schema.Type<typeof Feed> {}
+export type Feed = Type.InstanceType<typeof Feed>;
 
 //
 // Types
@@ -90,6 +84,19 @@ export interface SyncOptions {
   shouldPull?: boolean;
 }
 
+/**
+ * Queue replication backlog for a feed namespace.
+ * `0` / `0` means caught up on pull and push.
+ */
+export interface SyncState {
+  /** Blocks still to pull from remote. */
+  blocksToPull: number;
+  /** Unpositioned blocks still to push to remote. */
+  blocksToPush: number;
+  /** Total blocks stored locally for the feed namespace. */
+  totalBlocks: number;
+}
+
 //
 // Factory
 //
@@ -106,18 +113,11 @@ export interface SyncOptions {
 export const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(Feed, props);
 
 /**
- * Derives the queue DXN from the feed object's DXN.
- * Returns `undefined` when the feed is not stored in a space yet.
+ * Returns the feed object's EID when the feed is stored in a space.
  *
  * Used internally by the feed service layer.
  */
-export const getQueueDxn = (feed: Feed): DXN | undefined => {
-  const self = Obj.getDXN(feed).asEchoDXN();
-  if (!self || !self.spaceId) {
-    return undefined;
-  }
-  return new DXN(DXN.kind.QUEUE, [feed.namespace ?? 'data', self.spaceId, self.echoId]);
-};
+export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));
 
 //
 // Service
@@ -139,7 +139,6 @@ export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
     /**
      * Removes items from a feed by ID.
      */
-    // TODO(dmaretskyi): Change type to ObjectId.
     remove(feed: Feed, ids: string[]): Promise<void>;
 
     /**
@@ -154,6 +153,11 @@ export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
      * Syncs the feed with the server.
      */
     sync(feed: Feed, options?: SyncOptions): Promise<void>;
+
+    /**
+     * Returns queue replication backlog for the feed's namespace.
+     */
+    getSyncState(feed: Feed): Promise<SyncState>;
   }
 >() {}
 
@@ -167,6 +171,21 @@ export type Service = FeedService;
  */
 export const Service = FeedService;
 
+/**
+ * Effect context service that holds the current feed for a scoped operation.
+ *
+ * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
+ * over hiding it behind a context service.
+ */
+export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
+  ContextFeedService,
+  {
+    readonly feed: Feed;
+  }
+>() {
+  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
+}
+
 /**
  * Layer that provides a Feed service that throws when accessed.
  * Useful as a default layer when no feed service is available.
@@ -184,27 +203,11 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
   sync: () => {
     throw new Error('Feed.FeedService not available');
   },
+  getSyncState: () => {
+    throw new Error('Feed.FeedService not available');
+  },
 } as Context.Tag.Service<FeedService>);
 
-//
-// Context (per-call) service
-//
-
-/**
- * Effect service exposing a single `Feed.Feed` as the "current" feed for a call site.
- *
- * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
- * over hiding it behind a context service.
- */
-export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
-  ContextFeedService,
-  {
-    readonly feed: Feed;
-  }
->() {
-  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
-}
-
 //
 // Operations
 //
@@ -293,6 +296,20 @@ export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, nev
     yield* Effect.promise(() => service.sync(feed, options));
   });
 
+/**
+ * Returns queue replication backlog for the feed's namespace.
+ *
+ * @example
+ * ```ts
+ * const { blocksToPull, blocksToPush } = yield* Feed.getSyncState(feed);
+ * ```
+ */
+export const getSyncState = (feed: Feed): Effect.Effect<SyncState, never, FeedService> =>
+  Effect.gen(function* () {
+    const service = yield* FeedService;
+    return yield* Effect.promise(() => service.getSyncState(feed));
+  });
+
 /**
  * Creates a cursor for iterating over feed items.
  * Currently stubbed — cursor operations are not yet implemented.

package/src/Filter.ts

@@ -11,11 +11,13 @@ import type * as Types from 'effect/Types';
 
 import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
 import { assertArgument } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EID, EntityId, type URI } from '@dxos/keys';
 
 import * as internal from './internal';
 import type * as Obj from './Obj';
 import * as Ref from './Ref';
+// eslint-disable-next-line @dxos/rules/import-as-namespace
+import type * as Type$ from './Type';
 
 export interface Filter<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
@@ -77,11 +79,11 @@ export const nothing = (): FilterClass => {
 };
 
 /*
- * Filter by ObjectId.
+ * Filter by EntityId.
  */
-export const id = (...ids: ObjectId[]): Any => {
+export const id = (...ids: EntityId[]): Any => {
   assertArgument(
-    ids.every((id) => ObjectId.isValid(id)),
+    ids.every((id) => EntityId.isValid(id)),
     'ids',
     'ids must be valid',
   );
@@ -100,27 +102,46 @@ export const id = (...ids: ObjectId[]): Any => {
 
 /**
  * Filter by type.
+ *
+ * Accepts a `Type.Type` entity (the value produced by `Type.makeObject` /
+ * `Type.makeRelation`), a `Schema.Union` of such entities (for filtering across a
+ * union of ECHO types), or a non-qualified typename string.
  */
-export const type = <S extends Schema.Schema.All>(
-  schema: S | string,
-  props?: Props<Schema.Schema.Type<S>>,
-): Filter<Schema.Schema.Type<S>> => {
-  if (Schema.isSchema(schema) && SchemaAST.isUnion(schema.ast)) {
-    const typenames = schema.ast.types.map((type) => internal.getTypeDXNFromSpecifier(Schema.make(type)));
+export const type: {
+  <T extends Type$.AnyEntity>(type: T, props?: Props<Type$.InstanceType<T>>): Filter<Type$.InstanceType<T>>;
+  // Schema-side overload restricted to the well-known unknown schemas and to
+  // `Schema.Union(...)` of `Type.Type` entities (for filtering across a union
+  // of ECHO types). Other raw schemas are rejected.
+  <S extends internal.UnknownTypeSchema<any, any>>(
+    schema: S,
+    props?: Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>>;
+  <S extends Schema.Union<readonly Schema.Schema.AnyNoContext[]>>(
+    union: S,
+    props?: Props<Schema.Schema.Type<S>>,
+  ): Filter<Schema.Schema.Type<S>>;
+  (schema: string, props?: Props<unknown>): Filter<any>;
+  // Passthrough overload for callers that hold a `Type.AnyEntity | string` union
+  // (e.g. Query.type / Query.sourceOf / Query.targetOf impls). Listed last so the
+  // typed overloads above still win for monomorphic inputs.
+  (input: Type$.AnyEntity | string, props?: Props<unknown>): Filter<unknown>;
+} = (input: Type$.AnyEntity | Schema.Schema.AnyNoContext | string, props?: Props<unknown>): any => {
+  if (Schema.isSchema(input) && SchemaAST.isUnion(input.ast)) {
+    const typenames = input.ast.types.map((t) => internal.getTypeURIFromSpecifier(Schema.make(t)));
     return new FilterClass({
       type: 'or',
       filters: typenames.map((typename) => ({
         type: 'object',
-        typename: typename.toString(),
+        typename,
         props: {},
       })),
     });
   }
 
-  const dxn = internal.getTypeDXNFromSpecifier(schema);
+  const uri = internal.getTypeURIFromSpecifier(input);
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     ...propsFilterToAst(props ?? {}),
   });
 };
@@ -132,18 +153,19 @@ export const typename = (typename: string): Any => {
   assertArgument(!typename.startsWith('dxn:'), 'typename', 'Typename must no be qualified');
   return new FilterClass({
     type: 'object',
-    typename: DXN.fromTypename(typename).toString(),
+    typename: DXN.make(typename),
     props: {},
   });
 };
 
 /**
- * Filter by fully qualified type DXN.
+ * Filter by fully qualified type URI — either a typename DXN (for static schemas) or
+ * a schema-as-object EID (for stored dynamic schemas). See `getSchemaURI`.
  */
-export const typeDXN = (dxn: DXN): Any => {
+export const typeURI = (uri: URI.URI): Any => {
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     props: {},
   });
 };
@@ -223,14 +245,14 @@ export const text = (
 /**
  * Filter by foreign keys.
  */
-export const foreignKeys = <S extends Schema.Schema.All>(
-  schema: S | string,
+export const foreignKeys = <S extends Type$.AnyEntity | string>(
+  schema: S,
   keys: ForeignKey[],
-): Filter<Schema.Schema.Type<S>> => {
-  const dxn = internal.getTypeDXNFromSpecifier(schema);
+): Filter<S extends Type$.AnyEntity ? Type$.InstanceType<S> : unknown> => {
+  const uri = internal.getTypeURIFromSpecifier(schema);
   return new FilterClass({
     type: 'object',
-    typename: dxn.toString(),
+    typename: uri,
     props: {},
     foreignKeys: keys,
   });
@@ -378,7 +400,7 @@ export type ChildOfOptions = {
 /**
  * Filter objects that are children of the specified parent(s).
  * Accepts ECHO objects, Refs, or arrays of either.
- * Refs are resolved to DXNs without loading; objects use {@link Obj.getDXN}.
+ * Refs are resolved to DXNs without loading; objects use {@link Obj.getURI}.
  * With transitive=true (default), also matches grandchildren and beyond.
  */
 export const childOf = (
@@ -388,9 +410,9 @@ export const childOf = (
   const items = Array.isArray(parents) ? parents : [parents];
   const dxns = items.map((item) => {
     if (Ref.isRef(item)) {
-      return item.dxn.toString();
+      return EID.parse(item.uri);
     }
-    return internal.getDXN(item).toString();
+    return internal.getUri(item);
   });
   return new FilterClass({
     type: 'child-of',
@@ -432,7 +454,7 @@ export const or = <Filters extends readonly Any[]>(...filters: Filters): Filter<
 // TODO(dmaretskyi): Add `Filter.match` to support pattern matching on string props.
 
 const propsFilterToAst = (predicates: Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
-  let idFilter: readonly ObjectId[] | undefined;
+  let idFilter: readonly EntityId[] | undefined;
   if ('id' in predicates) {
     assertArgument(
       typeof predicates.id === 'string' || Array.isArray(predicates.id),
@@ -440,7 +462,7 @@ const propsFilterToAst = (predicates: Props<any>): Pick<QueryAST.FilterObject, '
       'invalid id filter',
     );
     idFilter = typeof predicates.id === 'string' ? [predicates.id] : predicates.id;
-    Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
+    Schema.Array(EntityId).pipe(Schema.validateSync)(idFilter);
   }
 
   return {

package/src/Hypergraph.ts

@@ -2,14 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type DXN } from '@dxos/keys';
+import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
 import type * as internal from './internal';
 import type * as Key from './Key';
 import type * as Ref from './Ref';
-import type * as SchemaRegistry from './SchemaRegistry';
+import type * as Registry from './Registry';
 
 /**
  * Resolution context.
@@ -22,10 +22,10 @@ export interface RefResolutionContext {
   space?: Key.SpaceId;
 
   /**
-   * Feed that the resolution is happening from (as the underlying queue DXN).
+   * Feed that the resolution is happening from.
    * This feed will be searched first, and then the space it belongs to.
    */
-  feed?: DXN;
+  feed?: URI.URI;
 }
 
 export interface RefResolverOptions {
@@ -46,7 +46,12 @@ export interface RefResolverOptions {
  * Manages cross-space database interactions.
  */
 export interface Hypergraph extends Database.Queryable {
-  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
+  /**
+   * In-process registry of keyed objects and static schema types.
+   * Populated at startup via `registry.add(objects)` / `registry.add(schemas)`.
+   * Queries that include no explicit from() clause will fan out to this registry automatically.
+   */
+  get registry(): Registry.Registry;
 
   /**
    * Query objects.
@@ -57,11 +62,11 @@ export interface Hypergraph extends Database.Queryable {
    * Creates a reference to an existing object in the database.
    *
    * NOTE: The reference may be dangling if the object is not present in the database.
-   * NOTE: Difference from `Ref.fromDXN`
-   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
+   * NOTE: Difference from `Ref.fromURI`
+   * `Ref.fromURI(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
    * `db.makeRef(dxn)` is preferable in cases with access to the database.
    */
-  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref.Ref<T>;
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(uri: URI.URI): Ref.Ref<T>;
 
   /**
    * @param hostDb Host database for reference resolution.

package/src/Json.test.ts

@@ -4,17 +4,17 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EID, EntityId } from '@dxos/keys';
 import { safeStringify } from '@dxos/util';
 
 import * as Database from './Database';
 import * as Json from './Json';
 
 /** Mint a random ECHO object id usable as both a stub-db key and a DXN payload. */
-const newId = (): string => ObjectId.random();
+const newId = (): string => EntityId.random();
 
 /** Build a fake encoded ref for a local-space object id. */
-const encodeRef = (id: string): { '/': string } => ({ '/': DXN.fromLocalObjectId(id).toString() });
+const encodeRef = (id: string): { '/': string } => ({ '/': EID.make({ entityId: id }) });
 
 /** Minimal stub: `createRefReplacer` only touches `db.getObjectById`. */
 const makeStubDb = (objects: Record<string, unknown>): Database.Database => {
@@ -93,7 +93,7 @@ describe('createRefReplacer', () => {
 
   test('leaves non-echo dxns untouched (e.g. type DXN)', () => {
     // Type DXNs share the `dxn:` prefix but `asEchoDXN()` returns undefined.
-    const typeRef = { '/': DXN.fromTypename('com.example.Thing').toString() };
+    const typeRef = { '/': DXN.make('com.example.Thing') };
     const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
     expect(stringifyWith(replacer, { ref: typeRef })).toEqual({ ref: typeRef });
   });