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

package/src/Annotation.ts

@@ -7,10 +7,11 @@
 export {
   DescriptionAnnotation,
   FormInputAnnotation,
+  FormInlineAnnotation,
   GeneratorAnnotation,
   LabelAnnotation,
   ReferenceAnnotation,
-  SystemTypeAnnotation,
+  HiddenAnnotation,
   TypeAnnotation,
   getDescriptionWithSchema,
   getLabelWithSchema,
@@ -18,12 +19,71 @@ export {
   setDescriptionWithSchema,
   setLabelWithSchema,
   IconAnnotation,
+  IconFromRefAnnotation,
 } from './internal/Annotation';
 
-import type * as Schema from 'effect/Schema';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import * as Types from 'effect/Types';
 
+import * as Entity from './Entity';
 import * as internalAnnotations from './internal/Annotation';
 
+export const TypeId = '~@dxos/echo/Annotation' as const;
+export type TypeId = typeof TypeId;
+
+// TODO(dmaretskyi): Reconcile different get/set styles: mutate in-place, return.
+// TODO(dmaretskyi): Reconcile Annotation methods vs static functions.
+// TODO(dmaretskyi): Reconcile Annotation.Key vs DXN -- work-out approach to versioning.
+
+/**
+ * Annotation is a typed property that can be assigned to a schema or an entity instance.
+ */
+export interface Annotation<T> {
+  [TypeId]: {
+    _Type: T;
+  };
+
+  // TODO(dmaretskyi): Make this a DXN?
+  /**
+   * Unique fully-qualified identifier for the annotation.
+   * @example "org.dxos.annotation.color"
+   */
+  readonly key: Key;
+
+  /**
+   * Schema of the annotation value.
+   */
+  readonly schema: Schema.Schema<T, unknown, never>;
+
+  /**
+   * Get the annotation value from an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — to read an annotation off a `Type.Type`
+   * entity, unwrap it first with `Type.getSchema(entity)`. This keeps the
+   * annotation pipeline single-shaped and forces annotations to live on the
+   * source schema, not on the post-construction Type entity.
+   */
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  /**
+   * Get the annotation value from the AST.
+   */
+  getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  /**
+   * Set the annotation on an Effect schema.
+   *
+   * Only accepts `Schema.Schema.Any` — annotations must be applied to the
+   * source schema BEFORE wrapping it with `Type.makeObject` / `Type.makeRelation`.
+   * In a pipe, place every `Annotation.X.set(...)` before the `Type.make...` step.
+   */
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+export const Key = internalAnnotations.Key;
+export type Key = Schema.Schema.Type<typeof Key>;
+
 interface MakeProps<T> {
   id: string;
   schema: Schema.Schema<T, any, never>;
@@ -44,5 +104,93 @@ interface MakeProps<T> {
  * const schema = Schema.String.annotations(ColorAnnotation.set('red'));
  * ```
  */
-export const make: <T>(props: MakeProps<T>) => internalAnnotations.AnnotationHelper<T> =
-  internalAnnotations.makeUserAnnotation;
+export const make: <T>(props: MakeProps<T>) => Annotation<T> = internalAnnotations.makeUserAnnotation;
+
+/**
+ * Get the value of an annotation from an entity instance or snapshot.
+ * For schema-level reads use the annotation instance method (e.g. `ColorAnnotation.get(schema)`).
+ * For getting an annotation value from a dictionary, use `getDictionary`.
+ */
+export const get: {
+  <T>(annotation: Annotation<T>): (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>;
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (target: Entity.Unknown | Entity.Snapshot) => Option.Option<T>,
+  <T>(target: Entity.Unknown | Entity.Snapshot, annotation: Annotation<T>) => Option.Option<T>
+>(2, (target, annotation) => {
+  return internalAnnotations.get(target, annotation);
+});
+
+/**
+ * Set the value of an annotation on an entity instance.
+ * For schema-level writes use the annotation instance method (e.g. `ColorAnnotation.set('red')`).
+ * For setting an annotation value on a dictionary, use `setDictionary`.
+ */
+export const set: {
+  <T>(annotation: Annotation<T>, value: T): (target: Entity.Mutable<Entity.Unknown>) => void;
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (target: Entity.Mutable<Entity.Unknown>) => void,
+  <T>(target: Entity.Mutable<Entity.Unknown>, annotation: Annotation<T>, value: T) => void
+>(3, (target, annotation, value) => {
+  return internalAnnotations.set(target, annotation, value);
+});
+
+export const getFromAst: {
+  <T>(annotation: Annotation<T>): (ast: SchemaAST.AST) => Option.Option<T>;
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (ast: SchemaAST.AST) => Option.Option<T>,
+  <T>(ast: SchemaAST.AST, annotation: Annotation<T>) => Option.Option<T>
+>(2, (ast, annotation) => {
+  return internalAnnotations.getFromAst(ast, annotation);
+});
+
+/**
+ * Set of annotation values.
+ *
+ * Can be used inside an object/relation schema:
+ *
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   extensions: Annotation.Dictionary,
+ * });
+ * ```
+ */
+export const Dictionary = internalAnnotations.Dictionary;
+export interface Dictionary extends Schema.Schema.Type<typeof Dictionary> {}
+
+/**
+ * Get the value of an annotation from a Dictionary.
+ */
+export const getDictionary: {
+  <T>(annotation: Annotation<T>): (values: Dictionary) => Option.Option<T>;
+  <T>(values: Dictionary, annotation: Annotation<T>): Option.Option<T>;
+} = Function.dual<
+  <T>(annotation: Annotation<T>) => (values: Dictionary) => Option.Option<T>,
+  <T>(values: Dictionary, annotation: Annotation<T>) => Option.Option<T>
+>(2, (values, annotation) => {
+  return internalAnnotations.getDictionary(values, annotation);
+});
+
+/**
+ * Set the value of an annotation in a Dictionary.
+ *
+ * Can also be used within Obj.update callback:
+ *
+ * ```ts
+ * Obj.update(obj, (obj) => {
+ *   Annotation.setDictionary(obj.annotations, ColorAnnotation, 'red');
+ * });
+ * ```
+ */
+export const setDictionary: {
+  <T>(annotation: Annotation<T>, value: T): (values: Dictionary) => void;
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T): void;
+} = Function.dual<
+  <T>(annotation: Annotation<T>, value: T) => (values: Dictionary) => void,
+  <T>(values: Types.Mutable<Dictionary>, annotation: Annotation<T>, value: T) => void
+>(3, (values, annotation, value) => {
+  return internalAnnotations.setDictionary(values, annotation, value);
+});

package/src/Collection.ts

@@ -6,6 +6,9 @@
 
 import * as Schema from 'effect/Schema';
 
+import { DXN } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
 import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Ref from './Ref';
@@ -18,13 +21,11 @@ export const Collection = Schema.Struct({
   name: Schema.String.pipe(Schema.optional),
   objects: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(internal.FormInputAnnotation.set(false)),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.collection',
-    version: '0.1.0',
-  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--folder--regular', hue: 'amber' }),
+  Type.makeObject(DXN.make('org.dxos.type.collection', '0.1.0')),
 );
 
-export interface Collection extends Schema.Schema.Type<typeof Collection> {}
+export type Collection = Type.InstanceType<typeof Collection>;
 
 export const make = (props: Partial<Obj.MakeProps<typeof Collection>> = {}): Collection =>
   Obj.make(Collection, { objects: [], ...props });

package/src/Database.ts

@@ -6,26 +6,28 @@
 
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Effectable from 'effect/Effectable';
 import * as Layer from 'effect/Layer';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
-import type * as Types from 'effect/Types';
 
 import { promiseWithCauseCapture } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { DXN, type SpaceId } from '@dxos/keys';
+import { type SpaceId, type URI } 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/Annotation';
+import { type AnyProperties, EntityKind, KindId } from './internal/common/types';
+// Deep import (not the `./internal/Entity` barrel) to avoid a cycle:
+// Database → internal/Entity → entity → JsonSchema → Ref → Database.
+import { isInstanceOf } from './internal/Entity/type-uri';
 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 Registry from './Registry';
 import type * as Type from './Type';
 
 /**
@@ -38,7 +40,7 @@ export interface QueryFn {
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;
@@ -62,6 +64,16 @@ export type AddOptions = {
   placeIn?: ObjectPlacement;
 };
 
+/**
+ * Rejects Type entities from {@link Database.add} at compile time via their `[KindId]` brand. Used
+ * as `T & RejectTypeEntity<T>` to preserve inference of `T`. Bounding `add` on
+ * `Obj.Unknown | Relation.Unknown` instead would reject broadly-typed instance adds (e.g.
+ * `Entity.Any`, `Obj.OfShape<T>`), forcing casts repo-wide.
+ */
+export type RejectTypeEntity<T> = T extends { readonly [KindId]: EntityKind.Type }
+  ? { __error: 'Type entities must be persisted via db.addType(), not db.add().' }
+  : T;
+
 export type FlushOptions = {
   /**
    * Write any pending changes to disk.
@@ -96,11 +108,15 @@ export interface Database extends Queryable {
 
   get spaceId(): SpaceId;
 
-  // TODO(burdon): Can we move this into graph?
-  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
-
   get graph(): Hypergraph.Hypergraph;
 
+  /**
+   * Registry for this database. Delegates type lookups to the shared hypergraph registry.
+   * To persist a schema so it replicates to other clients, add the type entity with
+   * {@link addType} (e.g. `await db.addType(Type.makeObjectFromJsonSchema(...))`).
+   */
+  readonly registry: Registry.Registry;
+
   toJSON(): object;
 
   /**
@@ -120,16 +136,28 @@ export interface Database extends 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<T>;
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(uri: URI.URI): Ref<T>;
 
   /**
-   * Adds object to the database.
+   * Adds an object or relation to the database.
+   *
+   * Only Object and Relation entities are accepted. To persist a Type definition use
+   * {@link addType} — passing a Type entity is rejected at compile time (and at runtime).
    */
-  add<T extends Entity.Unknown = Entity.Unknown>(obj: T, opts?: AddOptions): T;
+  add<T extends Entity.Unknown = Entity.Unknown>(obj: T & RejectTypeEntity<T>, opts?: AddOptions): T;
+
+  /**
+   * Persists a Type definition (clones/forks the entity) so it replicates to other peers.
+   *
+   * Runs a conflict query first: if a type with the same typename + version already exists in
+   * this space, the existing persisted entity is returned and no duplicate is created. This is
+   * the only supported way to add Type entities — {@link add} rejects them.
+   */
+  addType<T extends Type.AnyEntity>(type: T): Promise<T>;
 
   /**
    * Removes object from the database.
@@ -201,19 +229,19 @@ export const spaceId = Effect.gen(function* () {
  */
 export const resolve: {
   // No type check.
-  (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
+  (ref: URI.URI | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;
   // Check matches schema.
   <S extends Type.AnyEntity>(
-    ref: DXN | Ref<any>,
+    ref: URI.URI | Ref<any>,
     schema: S,
-  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;
+  ): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service>;
 } = (<S extends Type.AnyEntity>(
-  ref: DXN | Ref<any>,
+  ref: URI.URI | Ref<any>,
   schema?: S,
-): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>
+): Effect.Effect<Type.InstanceType<S>, Err.EntityNotFoundError, Service> =>
   Effect.gen(function* () {
     const { db } = yield* Service;
-    const dxn = ref instanceof DXN ? ref : ref.dxn;
+    const dxn = typeof ref === 'string' ? ref : ref.uri;
     const object = yield* promiseWithCauseCapture(() =>
       db.graph
         .createRefResolver({
@@ -225,93 +253,125 @@ export const resolve: {
     );
 
     if (!object) {
-      return yield* Effect.fail(new Err.ObjectNotFoundError(dxn));
+      return yield* Effect.fail(new Err.EntityNotFoundError(dxn));
     }
-    invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');
+    // `isInstanceOf` uses a conditional generic that TS can't resolve through
+    // the local `S extends Type.AnyEntity` parameter — runtime accepts it fine.
+    invariant(!schema || isInstanceOf(schema as any, object), 'Object type mismatch.');
     return object as any;
-  })) as any;
+  }).pipe(Effect.withSpan('Database.resolve'))) as any;
 
 /**
  * Loads an object reference.
  */
-export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn(function* (ref) {
-  const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
-  if (!object) {
-    return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));
-  }
-  return object;
-});
+export const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.EntityNotFoundError, never> = Effect.fn('Database.load')(
+  function* (ref) {
+    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new Err.EntityNotFoundError(ref.uri));
+    }
+    return object;
+  },
+);
 
 /**
  * Loads an object reference option.
  */
 // TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.
-export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
-  const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));
+export const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(
+  'Database.loadOption',
+)(function* (ref) {
+  const object = yield* load(ref).pipe(Effect.catchTag('EntityNotFoundError', () => Effect.succeed(undefined)));
 
   return Option.fromNullable(object);
 });
 
 /**
- * Adds an object to the database.
+ * Adds an object or relation 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)));
+export const add = <T extends Entity.Unknown>(obj: T & RejectTypeEntity<T>): Effect.Effect<T, never, Service> =>
+  Service.pipe(Effect.map(({ db }) => db.add<T>(obj))).pipe(Effect.withSpan('Database.add'));
+
+/**
+ * Persists a Type definition to the database.
+ * @see {@link Database.addType}
+ */
+export const addType = <T extends Type.AnyEntity>(type: T): Effect.Effect<T, never, Service> =>
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.addType(type)))).pipe(
+    Effect.withSpan('Database.addType'),
+  );
 
 /**
  * Removes an object from the database.
  * @see {@link Database.remove}
  */
 export const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>
-  Service.pipe(Effect.map(({ db }) => db.remove(obj)));
+  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));
 
 /**
  * Flushes pending changes to disk.
  * @see {@link Database.flush}
  */
 export const flush = (opts?: FlushOptions) =>
-  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts)))).pipe(
+    Effect.withSpan('Database.flush'),
+  );
 
 /**
  * Creates a `QueryResult` object that can be subscribed to.
  */
 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>;
+  <Q extends Query.Any>(query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Service>;
+  <F extends Filter.Any>(filter: F): QueryResult.QueryResultEffect<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'),
+    makeQueryResultEffect,
   );
 
 /**
  * Executes the query once and returns the results.
+ * @deprecated Use `yield* query(...).run` instead.
  */
 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())));
-
-/**
- * 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'),
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    Effect.withSpan('Database.runQuery'),
   );
 
 /**
- * Executes a schema query once and returns the results.
+ * Executes the query once and returns the first result as or None.
+ * @deprecated Use `yield* query(...).first` instead.
  */
-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())),
+export const runQueryFirst: {
+  <Q extends Query.Any>(query: Q): Effect.Effect<Option.Option<Query.Type<Q>>, never, Service>;
+  <F extends Filter.Any>(filter: F): Effect.Effect<Option.Option<Filter.Type<F>>, never, Service>;
+} = (queryOrFilter: Query.Any | Filter.Any) =>
+  query(queryOrFilter as any).pipe(
+    Effect.flatMap((queryResult) =>
+      promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),
+    ),
+    Effect.withSpan('Database.runQueryFirst'),
   );
+
+const makeQueryResultEffect = <T>(
+  eff: Effect.Effect<QueryResult.QueryResult<T>, never, Service>,
+): QueryResult.QueryResultEffect<T, never, Service> => {
+  return {
+    run: Effect.flatMap(eff, (result) => promiseWithCauseCapture(() => result.run())),
+    first: Effect.flatMap(eff, (result) =>
+      promiseWithCauseCapture(async () => Option.fromNullable(await result.firstOrUndefined())),
+    ),
+
+    // Effect internals
+    ...Effectable.CommitPrototype,
+    commit() {
+      return eff;
+    },
+  } as any;
+};

package/src/Dataset.ts

@@ -11,13 +11,21 @@ import * as Schema from 'effect/Schema';
 import * as Collection from './Collection';
 import * as Feed from './Feed';
 import * as Obj from './Obj';
+import * as Type from './Type';
 import * as View from './View';
 
 /**
- * Abstart set of objects, represented by a view, feed, or collection.
+ * Abstract set of objects, represented by a view, feed, or collection.
+ * Schema-level union of the underlying type entities (rebuilt via
+ * `Type.getSchema`) so this can still be consumed by Schema-side APIs such
+ * as `Filter.type(...)` on a union.
  */
-export const Dataset = Schema.Union(Feed.Feed, Collection.Collection, View.View);
 export type Dataset = Feed.Feed | Collection.Collection | View.View;
+export const Dataset = Schema.Union(
+  Type.getSchema(Feed.Feed),
+  Type.getSchema(Collection.Collection),
+  Type.getSchema(View.View),
+);
 
 export const isDataset: (value: unknown) => value is Dataset = pipe(
   Obj.instanceOf(Feed.Feed),

package/src/Entity.test.ts

@@ -4,19 +4,129 @@
 
 import { describe, expect, test } from 'vitest';
 
-import type * as Entity from './Entity';
+import * as Entity from './Entity';
 import * as Obj from './Obj';
 import * as Relation from './Relation';
 import { TestSchema } from './testing';
+import * as Type from './Type';
+
+const makeObject = () =>
+  Obj.make(TestSchema.Person, {
+    name: 'Test',
+    username: 'test',
+    email: 'test@example.com',
+    tasks: [],
+  });
+
+const makeRelation = (obj: TestSchema.Person) =>
+  Relation.make(TestSchema.HasManager, { [Relation.Source]: obj, [Relation.Target]: obj });
 
 describe('Entity', () => {
   test('Entity.Unknown accepts any object or relation', () => {
-    const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-    const rel = Relation.make(TestSchema.HasManager, { [Relation.Source]: obj, [Relation.Target]: obj });
-    const doSomething = (entity: Entity.Unknown) => {
-      return entity;
-    };
+    const obj = makeObject();
+    const rel = makeRelation(obj);
+    const doSomething = (entity: Entity.Unknown) => entity;
     expect(doSomething(obj)).toBe(obj);
     expect(doSomething(rel)).toBe(rel);
   });
+
+  // `isEntity` is a bare brand check (`[KindId] !== undefined`). All three entity
+  // kinds — objects, relations, and type entities — carry the brand, so all three
+  // are recognised as entities. (Type entities brand with `EntityKind.Type`.)
+  describe('isEntity / isSnapshot', () => {
+    test('object instance is an entity', () => {
+      const obj = makeObject();
+      expect(Entity.isEntity(obj)).toBe(true);
+      expect(Entity.isSnapshot(obj)).toBe(false);
+    });
+
+    test('relation instance is an entity', () => {
+      const rel = makeRelation(makeObject());
+      expect(Entity.isEntity(rel)).toBe(true);
+      expect(Entity.isSnapshot(rel)).toBe(false);
+    });
+
+    test('type entity is an entity', () => {
+      expect(Entity.isEntity(TestSchema.Person)).toBe(true);
+      expect(Entity.isSnapshot(TestSchema.Person)).toBe(false);
+    });
+
+    test('non-entities are rejected', () => {
+      expect(Entity.isEntity(null)).toBe(false);
+      expect(Entity.isEntity({})).toBe(false);
+      expect(Entity.isEntity({ id: 'x' })).toBe(false);
+      expect(Entity.isEntity('string')).toBe(false);
+    });
+  });
+
+  // Object and relation instances behave identically across the Entity.* accessor
+  // surface: these accessors are written for runtime instances and read the
+  // instance's identity, type pointer and metadata.
+  describe.each([
+    ['object', () => makeObject(), 'com.example.type.person'],
+    ['relation', () => makeRelation(makeObject()), 'com.example.type.hasManager'],
+  ] as const)('instance accessors (%s)', (_label, make, typename) => {
+    test('getURI returns an echo URI', () => {
+      const entity = make();
+      expect(Entity.getURI(entity)).toMatch(/^echo:/);
+    });
+
+    test('getTypename returns the typename', () => {
+      expect(Entity.getTypename(make())).toBe(typename);
+    });
+
+    test('getTypeURI returns the type DXN', () => {
+      expect(Entity.getTypeURI(make())).toBe(`dxn:${typename}:0.1.0`);
+    });
+
+    test('getType resolves back to the type entity', () => {
+      const type = Entity.getType(make());
+      expect(type).toBeDefined();
+      expect(Type.getTypename(type!)).toBe(typename);
+    });
+
+    test('getMeta returns metadata', () => {
+      expect(Entity.getMeta(make())).toBeDefined();
+    });
+
+    test('isDeleted is false for a live entity', () => {
+      expect(Entity.isDeleted(make())).toBe(false);
+    });
+
+    test('toJSON serializes the entity', () => {
+      const json = Entity.toJSON(make());
+      expect(json).toMatchObject({ '@type': expect.stringContaining(typename) });
+    });
+  });
+
+  // Type entities are first-class entities: the Entity.* accessors work on them too.
+  // `getURI`/`getTypename` return the type's OWN identity, while `getType`/`getTypeURI`
+  // (which mean "the type this entity is an instance of") resolve to the meta-type
+  // `Type.Type`.
+  describe('type entity', () => {
+    test('isEntity / getMeta / isDeleted', () => {
+      expect(Entity.isEntity(TestSchema.Person)).toBe(true);
+      expect(Entity.getMeta(TestSchema.Person)).toBeDefined();
+      expect(Entity.isDeleted(TestSchema.Person)).toBe(false);
+    });
+
+    test('getURI / getTypename return the type entity’s own identity', () => {
+      expect(Entity.getURI(TestSchema.Person)).toBe('dxn:com.example.type.person:0.1.0');
+      expect(Entity.getTypename(TestSchema.Person)).toBe('com.example.type.person');
+    });
+
+    test('getType / getTypeURI resolve to the meta-type (Type.Type)', () => {
+      expect(Entity.getType(TestSchema.Person)).toBe(Type.Type);
+      expect(Entity.getTypeURI(TestSchema.Person)).toBe('dxn:org.dxos.type.schema:0.1.0');
+    });
+
+    test('Entity.* and Type.* agree on type identity', () => {
+      expect(Entity.getURI(TestSchema.Person)).toBe(Type.getURI(TestSchema.Person));
+      expect(Entity.getTypename(TestSchema.Person)).toBe(Type.getTypename(TestSchema.Person));
+      expect(Type.isType(TestSchema.Person)).toBe(true);
+      expect(Type.isObject(TestSchema.Person)).toBe(true);
+      expect(Type.isRelation(TestSchema.HasManager)).toBe(true);
+      expect(Type.getVersion(TestSchema.Person)).toBe('0.1.0');
+    });
+  });
 });