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

package/src/internal/Ref/ref.ts

@@ -16,11 +16,17 @@ import { Event } from '@dxos/async';
 import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
 import { EncodedReference } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, ObjectId } from '@dxos/keys';
+import { DXN, EID, EntityId, type URI } from '@dxos/keys';
 
 import * as Database from '../../Database';
-import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../Annotation';
-import type { AnyEntity, AnyProperties } from '../common/types';
+import type * as Type from '../../Type';
+import {
+  ReferenceAnnotationId,
+  getSchemaURI,
+  getTypeAnnotation,
+  getTypeIdentifierAnnotation,
+} from '../Annotation/annotations';
+import { type AnyEntity, type AnyProperties, type UnknownTypeSchema, getStaticTypeSchema } from '../common/types';
 import { type JsonSchemaType } from '../JsonSchema';
 
 /**
@@ -31,7 +37,9 @@ export const JSON_SCHEMA_ECHO_REF_ID = '/schemas/echo/ref';
 export const getSchemaReference = (property: JsonSchemaType): { typename: string } | undefined => {
   const { $id, reference: { schema: { $ref } = {} } = {} } = property;
   if ($id === JSON_SCHEMA_ECHO_REF_ID && $ref) {
-    return { typename: DXN.parse($ref).typename };
+    const parsed = DXN.tryMake($ref);
+    const typename = parsed ? DXN.getName(parsed) : undefined;
+    return typename ? { typename } : undefined;
   }
 };
 
@@ -40,7 +48,7 @@ export const createSchemaReference = (typename: string): Types.DeepMutable<JsonS
     $id: JSON_SCHEMA_ECHO_REF_ID,
     reference: {
       schema: {
-        $ref: DXN.fromTypename(typename).toString(),
+        $ref: DXN.make(typename),
       },
     },
   };
@@ -82,7 +90,27 @@ export interface RefSchema<T extends AnyEntity> extends Schema.SchemaClass<Ref<T
  * Type of the `Ref` function and extra methods attached to it.
  */
 export interface RefFn {
-  <S extends Schema.Schema.Any>(schema: S): RefSchema<Schema.Schema.Type<S>>;
+  // A reference target is a `Type.AnyEntity` entity (the canonical Option B
+  // input) or one of the well-known "any object" / "any relation" branded
+  // schemas (`Obj.Unknown` / `Relation.Unknown`). Arbitrary raw schemas are
+  // rejected.
+  //
+  // Referencing a type-kind entity (a meta-schema, e.g. `Type.Type`) yields a
+  // reference to a stored schema record; its loaded target is any registered
+  // entity (`Type.AnyEntity`), since a stored object/relation schema is itself a
+  // `Type.Type` record. Referencing an object/relation type yields a reference
+  // to an instance of that type.
+  <S extends Type.AnyEntity | UnknownTypeSchema<any, any> = Type.AnyEntity>(
+    schema: S,
+  ): RefSchema<
+    S extends Type.AnyType
+      ? Type.AnyEntity
+      : S extends Type.AnyObj | Type.AnyRelation
+        ? Type.InstanceType<S>
+        : S extends UnknownTypeSchema<infer A, any>
+          ? A
+          : never
+  >;
 
   /**
    * @returns True if the object is a reference.
@@ -92,7 +120,7 @@ export interface RefFn {
   /**
    * @returns True if the reference points to the given object id.
    */
-  hasObjectId: (id: ObjectId) => (ref: Ref<any>) => boolean;
+  hasEntityId: (id: EntityId) => (ref: Ref<any>) => boolean;
 
   /**
    * @returns True if the schema is a reference schema.
@@ -111,15 +139,19 @@ export interface RefFn {
   make: <T extends AnyEntity>(object: T) => Ref<T>;
 
   /**
-   * Constructs a reference that points to the object specified by the provided DXN.
+   * Constructs a reference that points to the object specified by the provided URI
+   * (either an `echo:` EID for an object reference or a `dxn:` DXN for a type reference).
    */
-  fromDXN: (dxn: DXN) => Ref<any>;
+  fromURI: (uri: URI.URI) => Ref<any>;
 }
 
 /**
  * Schema builder for references.
  */
-export const Ref: RefFn = <S extends Schema.Schema.Any>(schema: S): RefSchema<Schema.Schema.Type<S>> => {
+export const Ref: RefFn = (input: any): RefSchema<any> => {
+  // `Type.Type` entities carry their source schema on the hidden slot; the
+  // branded `Obj.Unknown` / `Relation.Unknown` schemas are used directly.
+  const schema = getStaticTypeSchema(input) ?? input;
   assertArgument(Schema.isSchema(schema), 'schema', 'Must call with an instance of effect-schema');
   const annotation = getTypeAnnotation(schema);
   if (annotation == null) {
@@ -135,9 +167,9 @@ export const Ref: RefFn = <S extends Schema.Schema.Any>(schema: S): RefSchema<Sc
  */
 export interface Ref<T> extends Pipeable.Pipeable {
   /**
-   * Target object DXN.
+   * Target URI (either an `echo:` EID for an object reference or a `dxn:` DXN for a type reference).
    */
-  get dxn(): DXN;
+  get uri(): URI.URI;
 
   /**
    * Returns true if the reference has a target available (inlined or resolver set).
@@ -215,7 +247,10 @@ Ref.isRef = (obj: any): obj is Ref<any> => {
   return obj && typeof obj === 'object' && RefTypeId in obj;
 };
 
-Ref.hasObjectId = (id: ObjectId) => (ref: Ref<any>) => ref.dxn.isLocalObjectId() && ref.dxn.parts[1] === id;
+Ref.hasEntityId = (id: EntityId) => (ref: Ref<any>) => {
+  const uri = EID.tryParse(ref.uri);
+  return uri !== undefined && EID.isLocal(uri) && EID.getEntityId(uri) === id;
+};
 
 Ref.isRefSchema = (schema: Schema.Schema<any, any>): schema is RefSchema<any> => {
   return Ref.isRefSchemaAST(schema.ast);
@@ -230,16 +265,16 @@ Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
     throw new TypeError('Expected: ECHO object.');
   }
 
-  // TODO(dmaretskyi): Extract to `getObjectDXN` function.
+  // TODO(dmaretskyi): Extract to `getObjectEchoUri` function.
   const id = obj.id;
-  invariant(ObjectId.isValid(id), 'Invalid object ID');
-  const dxn = DXN.fromLocalObjectId(id);
-  return new RefImpl(dxn, obj);
+  invariant(EntityId.isValid(id), 'Invalid object ID');
+  const uri = EID.make({ entityId: id });
+  return new RefImpl(uri, obj);
 };
 
-Ref.fromDXN = (dxn: DXN): Ref<any> => {
-  assertArgument(dxn instanceof DXN, 'dxn', 'Expected DXN');
-  return new RefImpl(dxn);
+Ref.fromURI = (uri: URI.URI): Ref<any> => {
+  assertArgument(typeof uri === 'string', 'uri', 'Expected URI string');
+  return new RefImpl(uri);
 };
 
 /**
@@ -255,18 +290,18 @@ export type JsonSchemaReferenceInfo = {
  */
 // TODO(burdon): Move to json schema and make private?
 export const createEchoReferenceSchema = (
-  echoId: string | undefined,
+  echoUri: string | undefined,
   typename: string | undefined,
   version: string | undefined,
 ): Schema.SchemaClass<Ref<any>, EncodedReference> => {
-  if (!echoId && !typename) {
-    throw new TypeError('Either echoId or typename must be provided.');
+  if (!echoUri && !typename) {
+    throw new TypeError('Either echoUri or typename must be provided.');
   }
 
   const referenceInfo: JsonSchemaReferenceInfo = {
     schema: {
       // TODO(dmaretskyi): Include version?
-      $ref: echoId ?? DXN.fromTypename(typename!).toString(),
+      $ref: echoUri ?? DXN.make(typename!),
     },
     schemaVersion: version,
   };
@@ -279,7 +314,7 @@ export const createEchoReferenceSchema = (
         return (value) =>
           Effect.gen(function* () {
             if (Ref.isRef(value)) {
-              return EncodedReference.fromDXN((value as Ref<any>).dxn);
+              return EncodedReference.fromURI((value as Ref<any>).uri);
             } else if (EncodedReference.isEncodedReference(value)) {
               return value;
             }
@@ -294,7 +329,7 @@ export const createEchoReferenceSchema = (
             // TODO(dmaretskyi): This branch seems to be taken by Schema.is
             if (Ref.isRef(value)) {
               if (Option.isSome(dbService)) {
-                return dbService.value.db.makeRef(value.dxn);
+                return dbService.value.db.makeRef(value.uri);
               } else {
                 return value;
               }
@@ -304,9 +339,9 @@ export const createEchoReferenceSchema = (
               return yield* Effect.fail(new ParseResult.Unexpected(value, 'reference'));
             }
             if (Option.isSome(dbService)) {
-              return dbService.value.db.makeRef(EncodedReference.toDXN(value));
+              return dbService.value.db.makeRef(EncodedReference.toURI(value));
             } else {
-              return Ref.fromDXN(EncodedReference.toDXN(value));
+              return Ref.fromURI(EncodedReference.toURI(value));
             }
           });
       },
@@ -340,23 +375,32 @@ export interface RefResolver {
   /**
    * Resolve ref synchronously from the objects in the working set.
    *
-   * @param dxn
+   * @param uri
    * @param load If true the resolver should attempt to load the object from disk.
    * @param onLoad Callback to call when the object is loaded.
    */
-  resolveSync(dxn: DXN, load: boolean, onLoad?: () => void): AnyProperties | undefined;
+  resolveSync(uri: URI.URI, load: boolean, onLoad?: () => void): AnyProperties | undefined;
 
   /**
    * Resolver ref asynchronously.
    */
-  resolve(dxn: DXN): Promise<AnyProperties | undefined>;
+  resolve(uri: URI.URI): Promise<AnyProperties | undefined>;
 
   // TODO(dmaretskyi): Combine with `resolve`.
-  resolveSchema(dxn: DXN): Promise<Schema.Schema.AnyNoContext | undefined>;
+  resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined>;
+
+  /**
+   * Resolve the source `Type.AnyEntity` entity for a type URI. Used by
+   * deserialization paths (`Obj.fromJSON`) to set the back-reference accessed
+   * via `Obj.getType` / `Entity.getType`. Optional — resolvers that only
+   * carry raw schemas may leave this unimplemented; the deserializer falls
+   * back to leaving the type entity unset.
+   */
+  resolveType?(uri: URI.URI): Promise<unknown | undefined>;
 }
 
 export class RefImpl<T> implements Ref<T> {
-  #dxn: DXN;
+  #uri: URI.URI;
   #resolver?: RefResolver = undefined;
   #resolved = new Event<void>();
 
@@ -373,16 +417,16 @@ export class RefImpl<T> implements Ref<T> {
     this.#resolved.emit();
   };
 
-  constructor(dxn: DXN, target?: T) {
-    this.#dxn = dxn;
+  constructor(uri: URI.URI, target?: T) {
+    this.#uri = uri;
     this.#target = target;
   }
 
   /**
    * @inheritdoc
    */
-  get dxn(): DXN {
-    return this.#dxn;
+  get uri(): URI.URI {
+    return this.#uri;
   }
 
   /**
@@ -401,7 +445,7 @@ export class RefImpl<T> implements Ref<T> {
     }
 
     invariant(this.#resolver, 'Resolver is not set');
-    return this.#resolver.resolveSync(this.#dxn, true, this.#resolverCallback) as T | undefined;
+    return this.#resolver.resolveSync(this.#uri, true, this.#resolverCallback) as T | undefined;
   }
 
   /**
@@ -412,7 +456,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    const obj = await this.#resolver.resolve(this.#dxn);
+    const obj = await this.#resolver.resolve(this.#uri);
     if (obj == null) {
       throw new Error('Object not found');
     }
@@ -427,7 +471,7 @@ export class RefImpl<T> implements Ref<T> {
       return this.#target;
     }
     invariant(this.#resolver, 'Resolver is not set');
-    return (await this.#resolver.resolve(this.#dxn)) as T | undefined;
+    return (await this.#resolver.resolve(this.#uri)) as T | undefined;
   }
 
   /**
@@ -443,14 +487,14 @@ export class RefImpl<T> implements Ref<T> {
    * Clones the reference object.
    */
   noInline(): RefImpl<T> {
-    const ref = new RefImpl<T>(this.#dxn, undefined);
+    const ref = new RefImpl<T>(this.#uri, undefined);
     ref.#resolver = this.#resolver;
     return ref;
   }
 
   encode(): EncodedReference {
     return {
-      '/': this.#dxn.toString(),
+      '/': this.#uri,
       ...(this.#target ? { target: this.#target } : {}),
     };
   }
@@ -470,7 +514,7 @@ export class RefImpl<T> implements Ref<T> {
       return `Ref(${this.#target.toString()})`;
     }
 
-    return `Ref(${this.#dxn.toString()})`;
+    return `Ref(${this.#uri.toString()})`;
   }
 
   [inspectCustom]: CustomInspectFunction = (depth, options, inspect) => {
@@ -486,12 +530,12 @@ export class RefImpl<T> implements Ref<T> {
    * so without this, each access would create a separate cache entry.
    */
   [Hash.symbol](): number {
-    return Hash.hash(this.#dxn.toString());
+    return Hash.hash(this.#uri.toString());
   }
 
   /** Effect Equal trait. See {@link Hash.symbol} for rationale. */
   [Equal.symbol](that: Equal.Equal): boolean {
-    return that instanceof RefImpl && this.#dxn.toString() === that.dxn.toString();
+    return that instanceof RefImpl && this.#uri === that.uri;
   }
 
   /**
@@ -538,8 +582,8 @@ const refVariance: Ref<any>[typeof RefTypeId] = {
 };
 
 export const refFromEncodedReference = (encodedReference: EncodedReference, resolver?: RefResolver): Ref<any> => {
-  const dxn = DXN.parse(encodedReference['/']);
-  const ref = new RefImpl(dxn);
+  const uri = EncodedReference.toURI(encodedReference);
+  const ref = new RefImpl(uri);
 
   // TODO(dmaretskyi): Handle inline target in the encoded reference.
 
@@ -550,23 +594,26 @@ export const refFromEncodedReference = (encodedReference: EncodedReference, reso
 };
 
 export class StaticRefResolver implements RefResolver {
-  public objects = new Map<ObjectId, AnyProperties>();
-  public schemas = new Map<DXN.String, Schema.Schema.AnyNoContext>();
+  public objects = new Map<EntityId, AnyProperties>();
+  public schemas = new Map<URI.URI, Schema.Schema.AnyNoContext>();
 
   addObject(obj: AnyProperties): this {
     this.objects.set(obj.id, obj);
     return this;
   }
 
-  addSchema(schema: Schema.Schema.AnyNoContext): this {
-    const dxn = getSchemaDXN(schema);
-    invariant(dxn, 'Schema has no DXN');
-    this.schemas.set(dxn.toString(), schema);
+  addSchema(input: Type.AnyEntity): this {
+    const schema = getStaticTypeSchema(input);
+    invariant(schema, 'Type entity is missing its source schema');
+    const uri = getSchemaURI(schema);
+    invariant(uri, 'Schema has no URI');
+    this.schemas.set(uri, schema);
     return this;
   }
 
-  resolveSync(dxn: DXN, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
-    const id = dxn?.asEchoDXN()?.echoId;
+  resolveSync(uri: URI.URI, _load: boolean, _onLoad?: () => void): AnyProperties | undefined {
+    const echoUri = EID.tryParse(uri);
+    const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -574,8 +621,9 @@ export class StaticRefResolver implements RefResolver {
     return this.objects.get(id);
   }
 
-  async resolve(dxn: DXN): Promise<AnyProperties | undefined> {
-    const id = dxn?.asEchoDXN()?.echoId;
+  async resolve(uri: URI.URI): Promise<AnyProperties | undefined> {
+    const echoUri = EID.tryParse(uri);
+    const id = echoUri ? EID.getEntityId(echoUri) : undefined;
     if (id == null) {
       return undefined;
     }
@@ -583,7 +631,7 @@ export class StaticRefResolver implements RefResolver {
     return this.objects.get(id);
   }
 
-  async resolveSchema(dxn: DXN): Promise<Schema.Schema.AnyNoContext | undefined> {
-    return this.schemas.get(dxn.toString());
+  async resolveSchema(uri: URI.URI): Promise<Schema.Schema.AnyNoContext | undefined> {
+    return this.schemas.get(uri);
   }
 }

package/src/internal/Type/compose.test.ts

@@ -5,6 +5,8 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
 import { FieldPath } from '../Annotation';
 import { EchoObjectSchema } from '../Entity';
 import { FormatAnnotation, TypeFormat } from '../Format';
@@ -16,7 +18,7 @@ describe('schema composition', () => {
     const BaseType = Schema.Struct({
       name: Schema.String,
       email: Schema.String,
-    }).pipe(EchoObjectSchema({ typename: 'com.example.person', version: '0.1.0' }));
+    }).pipe(EchoObjectSchema(DXN.make('com.example.person', '0.1.0')));
 
     const OverlaySchema = Schema.Struct({
       email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(TypeFormat.Email)),

package/src/internal/Type/index.ts

@@ -2,6 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './echo-schema';
 export * from './manipulation';
-export * from './persistent-schema';
+export * from './type-schema';

package/src/internal/Type/manipulation.ts

@@ -6,9 +6,6 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-
-import { type TypeAnnotation, TypeAnnotationId, TypeIdentifierAnnotationId } from '../Annotation';
 
 // TODO(ZaymonFC): Do this one at a time. This might be dangerous.
 export const addFieldsToSchema = (
@@ -68,25 +65,3 @@ export const updateFieldNameInSchema = (
     ),
   );
 };
-
-export const setTypenameInSchema = (
-  schema: Schema.Schema.AnyNoContext,
-  typename: string,
-): Schema.Schema.AnyNoContext => {
-  const existingAnnotation = schema.ast.annotations[TypeAnnotationId] as TypeAnnotation;
-  invariant(existingAnnotation, `Missing ${String(TypeAnnotationId)}`);
-
-  return schema.annotations({
-    ...schema.ast.annotations,
-    [TypeAnnotationId]: {
-      kind: existingAnnotation.kind,
-      typename,
-      version: existingAnnotation.version,
-    } satisfies TypeAnnotation,
-    [SchemaAST.JSONSchemaAnnotationId]: {
-      ...(schema.ast.annotations[SchemaAST.JSONSchemaAnnotationId] ?? {}),
-      $id: schema.ast.annotations[TypeIdentifierAnnotationId] ?? DXN.fromTypename(typename).toString(),
-      typename,
-    },
-  });
-};

package/src/internal/Type/type-schema.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { IconAnnotation, LabelAnnotation } from '../Annotation';
+import { EntityKind, KindId, SchemaKindId, StaticTypeSchemaSlot } from '../common/types';
+import { EchoTypeKindSchema, TypeMetaSchemaDXN } from '../Entity';
+import { JsonSchemaType } from '../JsonSchema';
+
+/**
+ * Raw struct backing {@link TypeSchema}. Exposed only so `TypeSchema`
+ * (the TS type) can derive its data fields via `Schema.Schema.Type<typeof ...>`;
+ * runtime callers should use {@link TypeSchema} (the piped, branded entity).
+ *
+ * `typename` and `version` are NOT data fields — they live in `EntityMeta.key` /
+ * `EntityMeta.version` (the canonical registry-provenance pair, queryable via
+ * `Filter.key(...)`). The same `jsonSchema` payload also embeds them so a
+ * standalone JSON-Schema export remains self-describing, but the schema-registry
+ * reads/writes them through meta.
+ */
+const TypeSchemaStruct = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  jsonSchema: JsonSchemaType,
+});
+
+/**
+ * Persistent representation of a schema.
+ */
+export const TypeSchema = TypeSchemaStruct.pipe(
+  LabelAnnotation.set(['name']),
+  IconAnnotation.set({
+    icon: 'ph--database--regular',
+    hue: 'green',
+  }),
+  EchoTypeKindSchema(TypeMetaSchemaDXN),
+);
+
+/**
+ * Persistent representation of a schema — the runtime shape that
+ * `db.addType(Type.makeObjectFromJsonSchema(...))` produces
+ * and `Filter.type(Type.Type).run()` returns.
+ *
+ * Structurally identical to a static `Type.Type` entity: the entity-handler's
+ * `get` trap exposes `[SchemaKindId]` (derived from `system.kind` and
+ * `data.jsonSchema.entityKind`) and rebuilds `[StaticTypeSchemaSlot]` lazily
+ * from `jsonSchema`, so a persisted instance satisfies the public `Type<A>`
+ * interface without casting.
+ */
+export type TypeSchema = Schema.Schema.Type<typeof TypeSchemaStruct> & {
+  /** Object identifier — injected by `EchoTypeKindSchema` and stamped at construction. */
+  readonly id: string;
+  /** Entity-kind discriminator (object/relation/type) carried on every entity instance. */
+  readonly [KindId]: EntityKind.Type;
+  /** Kind of schema described by this meta-instance — always `EntityKind.Type` for `Type.Type` itself. */
+  readonly [SchemaKindId]: EntityKind.Type;
+  /** Effect Schema rebuilt lazily from `jsonSchema`; satisfies `Type.getSchema(...)` without an extra cast. */
+  readonly [StaticTypeSchemaSlot]: Schema.Schema.AnyNoContext;
+};

package/src/internal/common/README.md

@@ -7,7 +7,7 @@
 - [x] Unify FOUR different nests of test schema.
 - [x] Remove @deprecated from internal methods and mark @internal (e.g., getSchemaDXN).
   - NOTE: Internal methods should not use the import \* from Obj/Type APIs.
-- [x] import ObjectId => @dxos/keys
+- [x] import EntityId => @dxos/keys
 - [x] Entity.Any = Obj.Any | Relation.Any
   - NOTE: Relation does not extend (in not polymorphic with) Obj.
 - [x] import LabelAnnotation => Annotation.LabelAnnotation

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

@@ -6,18 +6,21 @@ import type { ForeignKey } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
 import type { DeepReadonly } from '@dxos/util';
 
+import type * as Tag from '../../../Tag';
+import type { Ref } from '../../Ref/ref';
 import { type Mutable } from '../proxy';
-import { type AnyProperties, type ObjectMeta, getMeta as getMeta$ } from '../types';
+import { type AnyProperties } from '../types';
+import { type EntityMeta, getMeta as getMeta$ } from '../types/meta';
 
 /**
- * Deeply read-only version of ObjectMeta.
+ * Deeply read-only version of EntityMeta.
  */
-export type ReadonlyMeta = DeepReadonly<ObjectMeta>;
+export type ReadonlyMeta = DeepReadonly<EntityMeta>;
 
 /**
  * Mutable meta type received in meta mutation callbacks.
  */
-export type Meta = Mutable<ObjectMeta>;
+export type Meta = Mutable<EntityMeta>;
 
 /**
  * Get the metadata for an entity with validation.
@@ -61,26 +64,25 @@ export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
 };
 
 /**
- * Add a tag to the entity.
+ * Add a tag (a reference to a {@link Tag} object) to the entity. Idempotent.
  * Must be called within an Obj.update or Relation.update callback.
  */
-export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const addTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  meta.tags ??= [];
-  meta.tags.push(tag);
+  // Two refs to the same target are not `===`; dedupe by URI.
+  if (!meta.tags.some((existing) => existing.uri === tag.uri)) {
+    meta.tags.push(tag);
+  }
 };
 
 /**
- * Remove a tag from the entity.
+ * Remove a tag (a reference to a {@link Tag} object) from the entity. No-op when not present.
  * Must be called within an Obj.update or Relation.update callback.
  */
-export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
+export const removeTag = (entity: Mutable<AnyProperties>, tag: Ref<Tag.Tag>) => {
   const meta = getMetaChecked(entity);
-  if (!meta.tags) {
-    return;
-  }
   for (let i = 0; i < meta.tags.length; i++) {
-    if (meta.tags[i] === tag) {
+    if (meta.tags[i].uri === tag.uri) {
       meta.tags.splice(i, 1);
       i--;
     }