@dxos/echo 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/internal/common/proxy/typed-handler.ts

@@ -2,18 +2,17 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type InspectOptionsStylized } from 'node:util';
-
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import { type InspectOptionsStylized } from 'node:util';
 
 import { Event } from '@dxos/async';
 import { inspectCustom } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
-
-import { getSchemaDXN } from '../../Annotation';
-import { ObjectDeletedId, ParentId, SchemaId, TypeId } from '../types';
+import { assertArgument, invariant } from '@dxos/invariant';
 
+import { getSchemaURI } from '../../Annotation/annotations';
+import { toEffectSchema } from '../../JsonSchema/json-schema';
+import { ObjectDeletedId, ParentId, SchemaId, StaticTypeSchemaSlot, TypeEntityId, TypeId } from '../types';
 import { executeChange, isInChangeContext, queueNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
 import { createPropertyDeleteError } from './errors';
@@ -144,7 +143,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   private constructor() {}
 
   init(target: ProxyTarget): void {
-    invariant(typeof target === 'object' && target !== null);
+    assertArgument(typeof target === 'object' && target !== null, 'target');
     invariant(SchemaId in target, 'Schema is not defined for the target');
 
     // Only set EventId on root objects (those without an owner).
@@ -210,6 +209,27 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
         // Uses target as both the context key and event target for non-database objects.
         return (callback: (obj: any) => void) => executeChange(target, target, receiver, callback);
       }
+      case TypeEntityId: {
+        // The back-reference to the type entity is metadata — return the raw
+        // value so we don't re-wrap an already-reactive `Type.Type` entity in
+        // another proxy (which would fail the SchemaId-in-target invariant).
+        return Reflect.get(target, prop, receiver);
+      }
+      case StaticTypeSchemaSlot: {
+        // Lazily rebuild the source Effect Schema from `jsonSchema` and cache it on
+        // the slot; the set-trap invalidates the cache when `jsonSchema` is mutated.
+        const existing = Reflect.get(target, prop, receiver);
+        if (existing !== undefined) {
+          return existing;
+        }
+        const jsonSchema = (target as any).jsonSchema;
+        if (jsonSchema == null) {
+          return undefined;
+        }
+        const rebuilt = toEffectSchema(jsonSchema);
+        defineHiddenProperty(target, StaticTypeSchemaSlot, rebuilt);
+        return rebuilt;
+      }
     }
 
     // Handle getter properties.
@@ -228,7 +248,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   set(target: ProxyTarget, prop: string | symbol, value: any, receiver: any): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip check if the object is still being initialized (no ChangeId handler yet).
     // Also skip for non-initialized root objects (those without EventId).
     // Skip for symbol properties (internal infrastructure, not user data).
@@ -236,8 +256,8 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
     const isSymbolProp = typeof prop === 'symbol';
     if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
       throw new Error(
-        `Cannot modify object property "${String(prop)}" outside of Obj.change(). ` +
-          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+        `Cannot modify object property "${String(prop)}" outside of Obj.update(). ` +
+          'Use Obj.update(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
       );
     }
 
@@ -247,6 +267,11 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
       batchEvents(() => {
         const { echoRoot: _, preparedValue } = this._prepareValueForAssignment(target, prop, value);
         result = Reflect.set(target, prop, preparedValue, receiver);
+        // Invalidate the cached source Effect Schema when `jsonSchema` changes
+        // (e.g. `Type.addFields`) so `Type.getSchema` rebuilds from the new shape.
+        if (prop === 'jsonSchema') {
+          Reflect.deleteProperty(target, StaticTypeSchemaSlot);
+        }
         // Queue notification instead of emitting immediately (batched).
         if (isInitialized) {
           queueNotification(echoRoot);
@@ -267,7 +292,7 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   deleteProperty(target: ProxyTarget, property: string | symbol): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip for symbol properties (internal infrastructure, not user data).
     const isInitialized = (echoRoot as any)[ChangeId] === true || EventId in echoRoot;
     const isSymbolProp = typeof property === 'symbol';
@@ -285,15 +310,15 @@ export class TypedReactiveHandler implements ReactiveHandler<ProxyTarget> {
   defineProperty(target: ProxyTarget, property: string | symbol, attributes: PropertyDescriptor): boolean {
     const echoRoot = getEchoRoot(target);
 
-    // Check readonly enforcement - mutations only allowed within Obj.change().
+    // Check readonly enforcement - mutations only allowed within Obj.update().
     // Skip check if the object is still being initialized (no ChangeId handler yet).
     // Skip for symbol properties (internal infrastructure, not user data).
     const isInitialized = ChangeId in echoRoot || EventId in echoRoot;
     const isSymbolProp = typeof property === 'symbol';
     if (isInitialized && !isSymbolProp && !isInChangeContext(echoRoot)) {
       throw new Error(
-        `Cannot modify object property "${String(property)}" outside of Obj.change(). ` +
-          'Use Obj.change(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
+        `Cannot modify object property "${String(property)}" outside of Obj.update(). ` +
+          'Use Obj.update(obj, (mutableObj) => { mutableObj.property = value; }) instead.',
       );
     }
 
@@ -402,16 +427,49 @@ const toJSON = (target: ProxyTarget): any => {
   return { '@type': 'TypedReactiveObject', ...target };
 };
 
+/**
+ * Pointer to a `Type.Type` entity, stamped as the back-reference (`TypeEntityId`)
+ * on instances and read by the `SchemaId` getter installed below.
+ *
+ * Structural shape (not `Type.AnyEntity`) because `internal/common/proxy/`
+ * can't import the top-level `Type` module without a cycle. Every kind of
+ * `Type.Type` entity satisfies this shape:
+ *   - Static (`Type.makeObject(dxn)` pipe) — slot set directly on the object.
+ *   - Persisted (echo-handler-wrapped) — slot exposed via that handler's
+ *     `get` trap (rebuilds from `data.jsonSchema`).
+ *   - In-memory pre-persist (`Type.makeObjectFromJsonSchema`) — slot exposed
+ *     via the `case StaticTypeSchemaSlot:` arm in this file's `get` trap.
+ */
+export type TypeSource = { readonly [StaticTypeSchemaSlot]?: Schema.Schema.AnyNoContext };
+
 /**
  * Recursively set AST on all potential proxy targets.
  */
-const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
-  const schemaType = getSchemaDXN(schema);
+const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext, typeSource?: TypeSource) => {
+  const schemaType = getSchemaURI(schema);
   if (schemaType != null) {
     defineHiddenProperty(obj, TypeId, schemaType);
   }
 
-  defineHiddenProperty(obj, SchemaId, schema);
+  if (typeSource != null) {
+    // Keep a back-reference to the type entity so `Obj.getType` /
+    // `Relation.getType` / `Entity.getType` can return it.
+    defineHiddenProperty(obj, TypeEntityId, typeSource);
+
+    // Install `SchemaId` as a getter that reads through the entity's static
+    // schema slot. The three entity shapes (static / persisted / in-memory
+    // pre-persist) each populate the slot via their own get-trap path, so
+    // `Type.update` / `Type.addFields` mutations propagate into validation
+    // for objects created via `Obj.make(typeEntity, ...)` without this file
+    // having to rebuild from `jsonSchema` itself.
+    Object.defineProperty(obj, SchemaId, {
+      get: () => typeSource[StaticTypeSchemaSlot] ?? schema,
+      enumerable: false,
+      configurable: true,
+    });
+  } else {
+    defineHiddenProperty(obj, SchemaId, schema);
+  }
   for (const key in obj) {
     if (isValidProxyTarget(obj[key])) {
       const elementSchema = SchemaValidator.getTargetPropertySchema(obj, key);
@@ -422,7 +480,9 @@ const setSchemaProperties = (obj: any, schema: Schema.Schema.AnyNoContext) => {
   }
 };
 
-export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
+// Accepts any encoded type: the typed handler operates on the decoded representation, so schemas
+// whose encoded form differs (e.g. refs encode as `{ '/': uri }`) are valid here.
+export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T, any>, typeSource?: TypeSource) => {
   // log.info('prepareTypedTarget', { target, schema });
   if (!SchemaAST.isTypeLiteral(schema.ast)) {
     throw new Error('schema has to describe an object type');
@@ -431,7 +491,7 @@ export const prepareTypedTarget = <T>(target: T, schema: Schema.Schema<T>) => {
   SchemaValidator.validateSchema(schema);
   const _ = Schema.asserts(schema)(target);
   makeArraysReactive(target);
-  setSchemaProperties(target, schema);
+  setSchemaProperties(target, schema, typeSource);
 };
 
 const makeArraysReactive = (target: any) => {

package/src/internal/common/proxy/typed-object.test.ts

@@ -6,22 +6,20 @@ import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 import { describe, expect, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
+import * as Obj from '../../../Obj';
+import * as Type from '../../../Type';
 import { EchoObjectSchema } from '../../Entity';
 import { getSchema } from '../types';
-
 import { makeObject } from './make-object';
 import { change } from './reactive';
 
 const Organization = Schema.Struct({
   name: Schema.String,
-}).pipe(
-  EchoObjectSchema({
-    typename: 'com.example.type.organization',
-    version: '0.1.0',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.organization', '0.1.0')));
 
-interface Organization extends Schema.Schema.Type<typeof Organization> {}
+type Organization = Type.InstanceType<typeof Organization>;
 
 const Contact = Schema.Struct(
   {
@@ -31,27 +29,21 @@ const Contact = Schema.Struct(
     key: Schema.String,
     value: Schema.Any,
   },
-).pipe(
-  Schema.partial,
-  EchoObjectSchema({
-    typename: 'com.example.type.person',
-    version: '0.1.0',
-  }),
-);
+).pipe(Schema.partial, EchoObjectSchema(DXN.make('com.example.type.person', '0.1.0')));
 
-interface Contact extends Schema.Schema.Type<typeof Contact> {}
+type Contact = Type.InstanceType<typeof Contact>;
 
-const TEST_ORG: Omit<Organization, 'id'> = { name: 'Test' };
+const TEST_ORG = { name: 'Test' } satisfies Pick<Organization, 'name'>;
 
 describe('EchoObjectSchema class DSL', () => {
   test('can get object schema', async () => {
-    const obj = makeObject(Organization, TEST_ORG);
-    expect(getSchema(obj)).to.deep.eq(Organization);
+    const obj = Obj.make(Organization, TEST_ORG);
+    expect(getSchema(obj)).to.deep.eq(Type.getSchema(Organization));
   });
 
   describe('class options', () => {
     test('can assign undefined to partial fields', async () => {
-      const person = makeObject(Contact, { name: 'John' });
+      const person = Obj.make(Contact, { name: 'John' });
       change(person, (p) => {
         p.name = undefined;
         p.recordField = 'hello';
@@ -87,7 +79,7 @@ describe('EchoObjectSchema class DSL', () => {
     }
 
     {
-      // Plain object (not a reactive proxy) - doesn't need Obj.change.
+      // Plain object (not a reactive proxy) - doesn't need Obj.update.
       // Note: Schema.Schema.Type generates readonly types, so we cast to mutable for plain objects.
       type Test1 = Types.Mutable<Schema.Schema.Type<typeof schema>>;
 
@@ -99,14 +91,9 @@ describe('EchoObjectSchema class DSL', () => {
     {
       const Test2 = Schema.Struct({
         meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
-      }).pipe(
-        EchoObjectSchema({
-          typename: 'org.dxos.type.function-trigger',
-          version: '0.1.0',
-        }),
-      );
-
-      const object = makeObject(Test2, {});
+      }).pipe(EchoObjectSchema(DXN.make('org.dxos.type.functionTrigger', '0.1.0')));
+
+      const object = Obj.make(Test2, {});
       change(object, (o) => {
         (o.meta ??= {}).test = 100;
       });

package/src/internal/common/types/base.ts

@@ -5,9 +5,9 @@
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { type ObjectId } from '@dxos/keys';
+import { type EntityId } from '@dxos/keys';
 
-import { type ATTR_META, type ObjectMeta } from './meta';
+import { type ATTR_META, type EntityMeta } from './meta';
 
 /**
  * Base type for all data objects (reactive, ECHO, and other raw objects).
@@ -23,7 +23,7 @@ export type AnyProperties = Record<string, any>;
  */
 // TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
 export interface AnyEntity {
-  readonly id: ObjectId;
+  readonly id: EntityId;
 }
 
 export type ExcludeId<T extends AnyProperties> = Omit<T, 'id'>;
@@ -31,7 +31,7 @@ export type ExcludeId<T extends AnyProperties> = Omit<T, 'id'>;
 export type PropertyKey<T extends AnyProperties> = Extract<keyof ExcludeId<T>, string>;
 
 // TODO(dmaretskyi): Remove. This should be using the symbol type.
-type WithMeta = { [ATTR_META]?: ObjectMeta };
+type WithMeta = { [ATTR_META]?: EntityMeta };
 
 /**
  * The raw object should not include the ECHO id, but may include metadata.

package/src/internal/common/types/entity.ts

@@ -33,11 +33,90 @@ export const SnapshotKindId = '~@dxos/echo/SnapshotKind' as const;
 export type SnapshotKindId = typeof SnapshotKindId;
 
 /**
- * Kinds of entities stored in ECHO: objects and relations.
+ * Hidden slot on a static `Type.Type` entity that holds the source Effect
+ * Schema. `Type.getSchema(...)` reads this for static types; persisted types
+ * rebuild from `jsonSchema` instead. Stored as a string key for declaration
+ * portability (see KindId comment above).
+ */
+export const StaticTypeSchemaSlot = '~@dxos/echo/Type.StaticSchema' as const;
+export type StaticTypeSchemaSlot = typeof StaticTypeSchemaSlot;
+
+/**
+ * Read the hidden `StaticTypeSchemaSlot` off any value that may carry one.
+ * Returns `undefined` for raw schemas (no slot) and non-object inputs.
+ * Single point-of-cast for the slot lookup.
+ */
+export const getStaticTypeSchema = (value: unknown): Schema.Schema.AnyNoContext | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [StaticTypeSchemaSlot]?: Schema.Schema.AnyNoContext })[StaticTypeSchemaSlot];
+};
+
+/**
+ * Read the `[SchemaKindId]` brand off a value. Returns `undefined` for raw
+ * schemas (which don't carry the brand on their static type) and non-object
+ * inputs. Single point-of-cast for the brand lookup.
+ */
+export const getSchemaKind = (value: unknown): EntityKind | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [SchemaKindId]?: EntityKind })[SchemaKindId];
+};
+
+/**
+ * Read the `[KindId]` brand off a value. Returns `undefined` for raw schemas
+ * and non-object inputs. Companion to {@link getSchemaKind}.
+ */
+export const getEntityKindBrand = (value: unknown): EntityKind | undefined => {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  return (value as { [KindId]?: EntityKind })[KindId];
+};
+
+/**
+ * Phantom string key on `Type<A>` entities that carries the instance type `A`.
+ * Lets internal helpers (`makeObject`, `createObject`, etc.) pattern-match the
+ * instance type from an entity input without importing from the top-level
+ * `Type` module. Mirrors `Type.InstancePhantomId` (declared in `Type.ts`).
+ *
+ * Stored as a string key so declarations remain portable across packages
+ * (see KindId comment above).
+ */
+export const InstancePhantomId = '~@dxos/echo/Type.Instance' as const;
+export type InstancePhantomId = typeof InstancePhantomId;
+
+/**
+ * Nominal brand carried by the well-known "any object" / "any relation"
+ * schemas (`Obj.Unknown`, `Relation.Unknown`). The brand lets `Ref.Ref`,
+ * `Filter.type`, and `Query.type` accept these schemas in addition to
+ * `Type.Type` entities, without opening the door to arbitrary raw schemas.
+ *
+ * Stored as a string key so declarations remain portable across packages
+ * (see KindId comment above).
+ */
+export const UnknownTypeSchemaBrandId = '~@dxos/echo/UnknownTypeSchemaBrand' as const;
+export type UnknownTypeSchemaBrandId = typeof UnknownTypeSchemaBrandId;
+
+/**
+ * Schema-side companion to `Type.Type` entities for the "any object" /
+ * "any relation" cases. Branded so `Ref.Ref` / `Filter.type` / `Query.type`
+ * can pattern-match on it; arbitrary `Schema.Schema` values do not satisfy
+ * this shape.
+ */
+export interface UnknownTypeSchema<A, K extends EntityKind> extends Schema.Schema<A, any, never> {
+  readonly [UnknownTypeSchemaBrandId]: K;
+}
+
+/**
+ * Kinds of entities stored in ECHO: objects, relations, and types.
  */
 export enum EntityKind {
   Object = 'object',
   Relation = 'relation',
+  Type = 'type',
 }
 
 export const EntityKindSchema = Schema.Enums(EntityKind);
@@ -46,7 +125,7 @@ export const EntityKindSchema = Schema.Enums(EntityKind);
  * Typename for generic object references (Type.Obj / Ref.Ref(Obj.Unknown)).
  * Used when referencing any object without a specific schema.
  */
-export const ANY_OBJECT_TYPENAME = 'org.dxos.schema.any-object';
+export const ANY_OBJECT_TYPENAME = 'org.dxos.schema.anyObject';
 
 /**
  * Version for generic object references.

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

@@ -4,7 +4,12 @@
 
 export * from './base';
 export * from './entity';
-export * from './meta';
+// NOTE: `./meta` is intentionally NOT re-exported here. It depends on the Ref schema (`Ref/ref`),
+// which transitively pulls in `Annotation` + `Database`; re-exporting it from this low-level barrel
+// — imported by `Annotation/util`, `Annotation/annotations`, `Entity/type-uri`, and `Ref/ref` —
+// would create an eval-order cycle (TDZ on `createAnnotationHelper`). Import meta from `./meta`
+// directly, or from the top-level `@dxos/echo/internal` barrel (re-exported there after Ref loads).
 export * from './model-symbols';
 export * from './typename';
 export * from './version';
+export * from './well-known-types';

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

@@ -4,13 +4,19 @@
 
 import * as Schema from 'effect/Schema';
 
-import { ForeignKey } from '@dxos/echo-protocol';
+import { type EncodedReference, ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
 import { type Comparator, intersection } from '@dxos/util';
 
 import type * as Entity from '../../../Entity';
-
+import type * as Tag from '../../../Tag';
+import { Dictionary } from '../../Annotation/dictionary';
+// `meta` is no longer re-exported from the `common/types` barrel (see ./index.ts), so importing the
+// Ref schema builder here no longer forms an eval-order cycle with `Annotation`/`Database`.
+import { type Ref, createEchoReferenceSchema } from '../../Ref/ref';
 import { type AnyProperties } from './base';
+import { TagTypeDXN } from './well-known-types';
 
 /**
  * Property name for meta when object is serialized to JSON.
@@ -23,25 +29,53 @@ export const ATTR_META = '@meta';
 export const MetaId: Entity.Meta = Symbol.for('@dxos/echo/Meta') as any;
 
 //
-// ObjectMeta
+// EntityMeta
 //
 
-// TODO(dmaretskyi): Rename to ObjectMeta
-export const ObjectMetaSchema = Schema.Struct({
+/**
+ * Schema for references to {@link Tag} objects stored in {@link EntityMetaSchema.tags}.
+ *
+ * Built from the shared {@link createEchoReferenceSchema} (the same builder `Ref.Ref` uses) via
+ * `Schema.suspend`, so it reuses the canonical ref codec rather than duplicating it. The Tag type
+ * identity comes from the shared {@link TagTypeDXN} constant; `suspend` defers construction until
+ * first use, and `Tag` is referenced type-only, so no `Tag` value import is needed.
+ */
+const TagRefSchema = Schema.suspend(
+  (): Schema.Schema<Ref<Tag.Tag>, EncodedReference> =>
+    // The factory yields a loosely-typed `Ref<any>` schema; narrow it to the Tag-typed ref.
+    createEchoReferenceSchema(undefined, DXN.getName(TagTypeDXN), DXN.getVersion(TagTypeDXN)) as Schema.Schema<
+      Ref<Tag.Tag>,
+      EncodedReference
+    >,
+);
+
+export const EntityMetaSchema = Schema.Struct({
   keys: Schema.Array(ForeignKey),
 
   /**
-   * A set of tags.
-   * Tags are arbitrary application-defined strings.
-   * ECHO makes no assumptions about the tag structure.
+   * Tags applied to this entity, as references to {@link Tag} objects.
+   */
+  tags: Schema.Array(TagRefSchema),
+
+  /**
+   * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).
+   * Identifies the canonical registry entry the object instance was created from.
+   */
+  key: Schema.optional(Schema.String),
+
+  /**
+   * Semantic version of the registry entry the object was created from.
+   * Must be a valid semver string (e.g. `1.2.3`).
+   */
+  version: Schema.optional(Schema.String),
+
+  /**
+   * Dictionary of annotations to this entity.
    */
-  // TODO(dmaretskyi): Has to be optional for compatibility with old data.
-  // Defaulting to an empty array is possible but requires a bit more work.
-  // TODO(dmaretskyi): In automerge this should be a map of { [tag]: boolean } for uniqueness and conflict resolution.
-  tags: Schema.optional(Schema.Array(Schema.String)),
+  annotations: Dictionary,
 });
 
-export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
+export type EntityMeta = Schema.Schema.Type<typeof EntityMetaSchema>;
 
 /*
  * Get metadata from object.
@@ -50,9 +84,9 @@ export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;
  * @internal (use Obj.getMeta or Relation.getMeta)
  */
 // TODO(burdon): Refine type to BaseObj.
-export const getMeta = (obj: AnyProperties): ObjectMeta => {
+export const getMeta = (obj: AnyProperties): EntityMeta => {
   const metadata = (obj as any)[MetaId];
-  invariant(metadata, 'ObjectMeta not found.');
+  invariant(metadata, 'EntityMeta not found.');
   return metadata;
 };
 

package/src/internal/common/types/model-symbols.ts

@@ -2,6 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
+// TODO(rename): These internal entity-wide symbols/types still use the `Object*` prefix but apply
+// to all entities (objects AND relations). Rename to `Entity*` in a follow-up pass (deferred from the
+// EchoURI→EID / ObjectId→EntityId / ObjectMeta→EntityMeta rename, which covered only public SDK API):
+//   ObjectCore, ObjectInternals, ObjectVersion, ObjectVersionId, ObjectDeletedId, ObjectDatabaseId,
+//   ObjectLoader, ObjectDocumentLoaded, ObjectUnavailable.
+// (ObjectMigration / ObjectMigrationContext intentionally excluded — object-only, not entity-wide.)
+
 /**
  * Internal symbol/string constants for the echo object model.
  * Defined in common/ so proxy/ can use them without importing from Entity/.
@@ -9,14 +16,19 @@
  */
 
 /**
- * Property name for self DXN when object is serialized to JSON.
+ * Property name for the object's own URI when serialized to JSON.
+ */
+export const ATTR_SELF_URI = '@uri';
+
+/**
+ * @deprecated Legacy JSON property name accepted on read for backward compat.
  */
-export const ATTR_SELF_DXN = '@dxn';
+export const ATTR_SELF_URI_LEGACY = '@dxn';
 
 /**
- * DXN to the object itself.
+ * Symbol carrying the object's own URI on live entities.
  */
-export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
+export const SelfURIId = Symbol.for('@dxos/echo/URI');
 
 /**
  * Property name for deleted when object is serialized to JSON.

package/src/internal/common/types/typename.ts

@@ -30,11 +30,20 @@ export const ATTR_PARENT = '@parent';
 export const ParentId = Symbol.for('@dxos/echo/Parent');
 
 /**
- * Returns the schema for the given object if one is defined.
+ * Reference to the object's type entity (`Type.Obj`, `Type.Relation`, or
+ * `Type.Type`). Set at instance creation by `createObject` / `makeObject`
+ * when the entity is known. Public read-back via `Obj.getType` / `Relation.getType`
+ * / `Entity.getType`.
+ */
+export const TypeEntityId = Symbol.for('@dxos/echo/TypeEntity');
+
+/**
+ * Returns the Effect Schema for the given object if one is defined.
  *
- * @internal (Use Obj.getSchema)
+ * @internal
+ * Internal callers needing schema-side validation read from `SchemaId`.
+ * Public callers should use `Type.getSchema(Obj.getType(obj))` instead.
  */
-// TODO(burdon): Narrow type.
 // TODO(dmaretskyi): For echo objects, this always returns the root schema.
 export const getSchema = (obj: unknown | undefined): Schema.Schema.AnyNoContext | undefined => {
   if (obj) {
@@ -53,3 +62,30 @@ export const setSchema = (obj: any, schema: Schema.Schema.AnyNoContext): void =>
     configurable: false,
   });
 };
+
+/**
+ * Returns the type entity (`Type.AnyEntity`) for the given instance.
+ * Set at instance creation; every entity has a type. Defensive: returns
+ * undefined for null/undefined input so callers can safely probe arbitrary
+ * values via this helper.
+ *
+ * @internal Re-exported via `Obj.getType` / `Relation.getType` / `Entity.getType`.
+ */
+export const getType = (obj: unknown): unknown => {
+  if (obj == null) {
+    return undefined;
+  }
+  return (obj as any)[TypeEntityId];
+};
+
+/**
+ * @internal
+ */
+export const setType = (obj: any, type: unknown): void => {
+  Object.defineProperty(obj, TypeEntityId, {
+    value: type,
+    writable: false,
+    enumerable: false,
+    configurable: true,
+  });
+};

package/src/internal/common/types/well-known-types.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { DXN } from '@dxos/keys';
+
+/**
+ * DXN identity of the system {@link Tag} type.
+ *
+ * Defined in this low-level leaf so it can be shared by the public `Tag` type (which brands the
+ * schema with this DXN) and by `EntityMetaSchema.tags` (which builds a `Ref<Tag>` schema from it)
+ * without either importing the other — `Tag` is top-level and `meta` is deep-internal, so a direct
+ * dependency between them would form an eval-order cycle.
+ */
+export const TagTypeDXN = DXN.make('org.dxos.type.tag', '0.1.0');

package/src/internal/index.ts

@@ -12,5 +12,11 @@ export * from './Format';
 export * from './JsonSchema';
 // TODO(wittjosiah): Required to ensure types are portable (need to export all types required for downstream inference).
 export * from './Obj';
+export * from './Query';
 export * from './Ref';
 export * from './Type';
+
+// Re-exported here (not from the low-level `common/types` barrel) so consumers keep importing meta
+// from `@dxos/echo/internal`, while that barrel stays free of the Ref/Annotation eval cycle. Placed
+// after `./Ref` so the ref schema `meta` depends on is initialized first.
+export * from './common/types/meta';