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

package/src/internal/{proxy → common/proxy}/reactive.ts

@@ -2,9 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type RefTypeId } from '../ref/ref';
-
-import { getProxyTarget } from './proxy-utils';
+import { type RefTypeId } from '../../Ref/ref';
+import { getProxyTarget, isProxy } from './proxy-utils';
 import { ChangeId, EventId } from './symbols';
 
 /**
@@ -15,6 +14,15 @@ import { ChangeId, EventId } from './symbols';
  */
 // TODO(wittjosiah): Consider throwing if obj doesn't have EventId instead of returning no-op.
 export const subscribe = (obj: unknown, callback: () => void): (() => void) => {
+  // Guard against non-reactive inputs (queue-stored typed objects, snapshots, plain shapes
+  // with branded symbols) before `getProxyTarget`'s `ProxyHandlerSlot` invariant kicks in.
+  // `Obj.isObject` (KindId-based) is satisfied by these inputs, so callers like
+  // `Atom.family((obj) => Atom.make((get) => Obj.subscribe(obj, ...)))` legitimately reach
+  // here with a non-proxy. Falling back to a no-op preserves the documented contract that
+  // values without subscription support get a no-op unsubscribe.
+  if (!isProxy(obj)) {
+    return () => {};
+  }
   const target = getProxyTarget(obj as any);
   if (target && EventId in target) {
     return (target as any)[EventId].on(callback);
@@ -24,7 +32,7 @@ export const subscribe = (obj: unknown, callback: () => void): (() => void) => {
 
 /**
  * Deeply removes readonly modifiers from all properties of T.
- * Inside Obj.change, all properties are fully mutable regardless of schema definition.
+ * Inside Obj.update, all properties are fully mutable regardless of schema definition.
  * Ref types are preserved as-is since they are value-like objects that are replaced, not mutated.
  * Primitive types (including branded primitives) are preserved as-is.
  */

package/src/internal/{proxy → common/proxy}/schema.test.ts

@@ -6,14 +6,14 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
-import { createEchoSchema } from '../../testing';
-import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../annotations';
-import { EchoObjectSchema } from '../entities';
+import { createEchoSchema } from '../../../testing';
+import { PropertyMeta, getPropertyMetaAnnotation, getTypeAnnotation } from '../../Annotation';
+import { EchoObjectSchema } from '../../Entity';
 
 // TODO(dmaretskyi): Comment.
 const EmptySchemaType = Schema.Struct({}).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Empty',
+    typename: 'com.example.type.empty',
     version: '0.1.0',
   }),
 );
@@ -27,7 +27,7 @@ describe('dynamic schema', () => {
       field2: Schema.Boolean,
     }).pipe(
       EchoObjectSchema({
-        typename: 'example.com/type/Test',
+        typename: 'com.example.type.test',
         version: '0.1.0',
       }),
     );
@@ -44,7 +44,7 @@ describe('dynamic schema', () => {
       field1: Schema.String,
     }).pipe(
       EchoObjectSchema({
-        typename: 'example.com/type/Test',
+        typename: 'com.example.type.test',
         version: '0.1.0',
       }),
     );
@@ -95,7 +95,7 @@ describe('dynamic schema', () => {
     registered.updateFields({ field3: Schema.Boolean });
     registered.removeFields(['field2']);
     expect(getTypeAnnotation(registered)).to.deep.contain({
-      typename: 'example.com/type/Empty',
+      typename: 'com.example.type.empty',
       version: '0.1.0',
     });
     expect(getPropertyMetaAnnotation(registered.getProperties()[0], metaNamespace)).to.deep.eq(metaInfo);
@@ -111,7 +111,7 @@ describe('dynamic schema', () => {
     });
 
     // First update.
-    const newTypename1 = 'example.com/type/Individual';
+    const newTypename1 = 'com.example.type.individual';
     registered.updateTypename(newTypename1);
 
     // Basic typename update checks.
@@ -132,13 +132,13 @@ describe('dynamic schema', () => {
     expect(nameMeta).toEqual({ maxLength: 10 });
 
     // Second update to ensure multiple updates work.
-    const newTypename2 = 'example.com/type/Person';
+    const newTypename2 = 'com.example.type.person';
     registered.updateTypename(newTypename2);
     expect(registered.typename).toBe(newTypename2);
     expect(registered.jsonSchema.$id).toBe(`dxn:type:${newTypename2}`);
     expect(registered.jsonSchema.typename).toBe(newTypename2);
     expect(getTypeAnnotation(registered)).to.deep.contain({
-      typename: 'example.com/type/Person',
+      typename: 'com.example.type.person',
       version: '0.1.0',
     });
   });

package/src/internal/{proxy → common/proxy}/typed-handler.test.ts

@@ -5,12 +5,11 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { TestSchema } from '../../testing';
-import { EchoObjectSchema } from '../entities';
-import { setValue } from '../object';
-import { Ref } from '../ref';
+import { TestSchema } from '../../../testing';
+import { EchoObjectSchema } from '../../Entity';
+import { setValue } from '../../Obj';
+import { Ref } from '../../Ref';
 import { foreignKey, getMeta } from '../types';
-
 import { makeObject } from './make-object';
 import { change, subscribe } from './reactive';
 
@@ -40,10 +39,10 @@ describe('complex schema validations', () => {
 
   test('references', () => {
     const Foo = Schema.Struct({ field: Schema.String }).pipe(
-      EchoObjectSchema({ typename: 'example.com/type/Foo', version: '0.1.0' }),
+      EchoObjectSchema({ typename: 'com.example.type.foo', version: '0.1.0' }),
     );
     const Bar = Schema.Struct({ fooRef: Ref(Foo) }).pipe(
-      EchoObjectSchema({ typename: 'example.com/type/Bar', version: '0.1.0' }),
+      EchoObjectSchema({ typename: 'com.example.type.bar', version: '0.1.0' }),
     );
     const field = 'hello';
     expect(() => makeObject(Bar, { fooRef: { id: '1', field } as any })).to.throw();

package/src/internal/{proxy → common/proxy}/typed-handler.ts

@@ -2,19 +2,16 @@
 // 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 '../annotations';
-import { ObjectDeletedId } from '../entities';
-import { ParentId, SchemaId, TypeId } from '../types';
-
+import { getSchemaDXN } from '../../Annotation';
+import { ObjectDeletedId, ParentId, SchemaId, TypeId } from '../types';
 import { executeChange, isInChangeContext, queueNotification } from './change-context';
 import { defineHiddenProperty } from './define-hidden-property';
 import { createPropertyDeleteError } from './errors';
@@ -229,7 +226,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).
@@ -237,8 +234,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.',
       );
     }
 
@@ -268,7 +265,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';
@@ -286,15 +283,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.',
       );
     }
 

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

@@ -6,9 +6,8 @@ import * as Schema from 'effect/Schema';
 import type * as Types from 'effect/Types';
 import { describe, expect, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
+import { EchoObjectSchema } from '../../Entity';
 import { getSchema } from '../types';
-
 import { makeObject } from './make-object';
 import { change } from './reactive';
 
@@ -16,7 +15,7 @@ const Organization = Schema.Struct({
   name: Schema.String,
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Organization',
+    typename: 'com.example.type.organization',
     version: '0.1.0',
   }),
 );
@@ -34,7 +33,7 @@ const Contact = Schema.Struct(
 ).pipe(
   Schema.partial,
   EchoObjectSchema({
-    typename: 'example.com/type/Person',
+    typename: 'com.example.type.person',
     version: '0.1.0',
   }),
 );
@@ -87,7 +86,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>>;
 
@@ -101,7 +100,7 @@ describe('EchoObjectSchema class DSL', () => {
         meta: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
       }).pipe(
         EchoObjectSchema({
-          typename: 'dxos.org/type/FunctionTrigger',
+          typename: 'org.dxos.type.functionTrigger',
           version: '0.1.0',
         }),
       );

package/src/internal/{types → common/types}/base.ts

@@ -14,12 +14,12 @@ import { type ATTR_META, type ObjectMeta } from './meta';
  * NOTE: This describes the base type for all database objects.
  * It is stricter than `T extends {}` or `T extends object`.
  */
-// TODO(burdon): Make internal.
 // TODO(burdon): Prefer Record<string, unknown>.
 export type AnyProperties = Record<string, any>;
 
 /**
  * Canonical type for all ECHO entities (objects and relations).
+ * @depreacted Remove, use Entity.Unknown instead.
  */
 // TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
 export interface AnyEntity {

package/src/internal/{types → common/types}/entity.ts

@@ -43,10 +43,10 @@ export enum EntityKind {
 export const EntityKindSchema = Schema.Enums(EntityKind);
 
 /**
- * Typename for generic object references (Type.Obj / Type.Ref(Type.Obj)).
+ * 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 = 'dxos.org/schema/AnyObject';
+export const ANY_OBJECT_TYPENAME = 'org.dxos.schema.anyObject';
 
 /**
  * Version for generic object references.

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

@@ -5,5 +5,6 @@
 export * from './base';
 export * from './entity';
 export * from './meta';
+export * from './model-symbols';
 export * from './typename';
 export * from './version';

package/src/internal/{types → common/types}/meta.ts

@@ -8,6 +8,7 @@ import { ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { type Comparator, intersection } from '@dxos/util';
 
+import type * as Entity from '../../../Entity';
 import { type AnyProperties } from './base';
 
 /**
@@ -18,7 +19,7 @@ export const ATTR_META = '@meta';
 /**
  * Metadata section.
  */
-export const MetaId = Symbol.for('@dxos/echo/Meta');
+export const MetaId: Entity.Meta = Symbol.for('@dxos/echo/Meta') as any;
 
 //
 // ObjectMeta
@@ -35,7 +36,20 @@ export const ObjectMetaSchema = Schema.Struct({
    */
   // 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)),
+
+  /**
+   * 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),
 });
 
 export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;

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

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Internal symbol/string constants for the echo object model.
+ * Defined in common/ so proxy/ can use them without importing from Entity/.
+ * Entity/ re-exports these for external consumers.
+ */
+
+/**
+ * Property name for self DXN when object is serialized to JSON.
+ */
+export const ATTR_SELF_DXN = '@dxn';
+
+/**
+ * DXN to the object itself.
+ */
+export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
+
+/**
+ * Property name for deleted when object is serialized to JSON.
+ */
+export const ATTR_DELETED = '@deleted';
+
+/**
+ * Deletion marker.
+ */
+export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
+
+/**
+ * Object version accessor symbol.
+ */
+export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+
+/**
+ * Object database accessor symbol.
+ */
+export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+
+/**
+ * Property name for relation source when object is serialized to JSON.
+ */
+export const ATTR_RELATION_SOURCE = '@relationSource';
+
+/**
+ * Used to access relation source ref on live ECHO objects.
+ */
+export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
+
+/**
+ * Used to access relation source DXN on live ECHO objects.
+ */
+export const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');
+
+/**
+ * Property name for relation target when object is serialized to JSON.
+ */
+export const ATTR_RELATION_TARGET = '@relationTarget';
+
+/**
+ * Used to access relation target ref on live ECHO objects.
+ */
+export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
+
+/**
+ * Used to access relation target DXN on live ECHO objects.
+ */
+export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');

package/src/internal/{types → common/types}/version.ts

@@ -3,10 +3,9 @@
 //
 
 /**
- * Version type symbol.
+ * Version type identifier.
  */
-export const VersionTypeId: unique symbol = Symbol.for('@dxos/echo/VersionTypeId');
-
+export const VersionTypeId = '~@dxos/echo/VersionTypeId' as const;
 export type VersionTypeId = typeof VersionTypeId;
 
 /**

package/src/internal/index.ts

@@ -5,35 +5,13 @@
 // TODO(burdon): Import directly (not part of ECHO API).
 export { JsonPath, JsonProp, getValue, splitJsonPath } from '@dxos/effect';
 
-export * from './annotations';
-export * from './api';
-export * from './entities';
-export * from './formats';
-export * from './json-schema';
-export * from './ref';
-export * from './types';
-
+export * from './Annotation';
+export * from './common';
+export * from './Entity';
+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 './object';
-export * from './proxy';
-export * from './schema';
-
-// export {
-//   createObject,
-//   createQueueDXN,
-//   isDeleted,
-//   objectFromJSON,
-//   objectToJSON,
-//   setRefResolverOnData,
-//   SchemaValidator,
-//   TypedObject,
-// } from './object';
-// export { makeObject } from './proxy';
-// export {
-//   type BaseSchema,
-//   EchoSchema,
-//   ImmutableSchema,
-//   RuntimeSchemaRegistry,
-//   PersistentSchema,
-//   isMutable,
-// } from './schema';
+export * from './Obj';
+export * from './Query';
+export * from './Ref';
+export * from './Type';

package/src/testing/api.test.ts

@@ -8,7 +8,6 @@ import { describe, test } from 'vitest';
 import { raise } from '@dxos/debug';
 
 import { Entity, Obj, Ref, Relation, Type } from '../index';
-
 import { TestSchema } from './test-schema';
 
 describe('Experimental API review', () => {
@@ -17,11 +16,11 @@ describe('Experimental API review', () => {
     const schema = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
 
     expect(Type.getDXN(schema)?.typename).to.eq(TestSchema.Person.typename);
-    expect(Type.getTypename(schema)).to.eq('example.com/type/Person');
+    expect(Type.getTypename(schema)).to.eq('com.example.type.person');
     expect(Type.getVersion(schema)).to.eq('0.1.0');
     expect(Type.getMeta(schema)).to.deep.eq({
       kind: Entity.Kind.Object,
-      typename: 'example.com/type/Person',
+      typename: 'com.example.type.person',
       version: '0.1.0',
     });
   });
@@ -110,7 +109,7 @@ describe('Experimental API review', () => {
         expect(expando.content).to.eq('Test');
 
         // This should work: assign to Obj.Obj of the schema's instance type
-        const _typed: Obj.Obj<TestSchema.Expando> = expando;
+        const _typed: Obj.OfShape<TestSchema.Expando> = expando;
       }
 
       {
@@ -119,7 +118,7 @@ describe('Experimental API review', () => {
         expect(person.name).to.eq('Test');
 
         // This should work: assign to Obj.Obj of the schema's instance type
-        const _typed: Obj.Obj<TestSchema.Person> = person;
+        const _typed: Obj.OfShape<TestSchema.Person> = person;
       }
     });
   });