@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.0

package/src/Relation.test.ts

@@ -44,13 +44,13 @@ describe('Relation', () => {
       });
       const snapshot = Relation.getSnapshot(rel);
 
-      // getSourceDXN - works with both.
-      expect(Relation.getSourceDXN(rel)).toBeDefined();
-      expect(Relation.getSourceDXN(snapshot)).toBeDefined();
+      // getSourceURI - works with both.
+      expect(Relation.getSourceURI(rel)).toBeDefined();
+      expect(Relation.getSourceURI(snapshot)).toBeDefined();
 
-      // getTargetDXN - works with both.
-      expect(Relation.getTargetDXN(rel)).toBeDefined();
-      expect(Relation.getTargetDXN(snapshot)).toBeDefined();
+      // getTargetURI - works with both.
+      expect(Relation.getTargetURI(rel)).toBeDefined();
+      expect(Relation.getTargetURI(snapshot)).toBeDefined();
 
       // getSource - works with both.
       expect(Relation.getSource(rel)).toBeDefined();
@@ -61,12 +61,12 @@ describe('Relation', () => {
       expect(Relation.getTarget(snapshot)).toBeDefined();
 
       // getDXN - works with both.
-      expect(Relation.getDXN(rel)).toBeDefined();
-      expect(Relation.getDXN(snapshot)).toBeDefined();
+      expect(Relation.getURI(rel)).toBeDefined();
+      expect(Relation.getURI(snapshot)).toBeDefined();
 
       // getTypename - works with both.
-      expect(Relation.getTypename(rel)).toBe('com.example.type.has-manager');
-      expect(Relation.getTypename(snapshot)).toBe('com.example.type.has-manager');
+      expect(Relation.getTypename(rel)).toBe('com.example.type.hasManager');
+      expect(Relation.getTypename(snapshot)).toBe('com.example.type.hasManager');
 
       // getMeta - works with both.
       expect(Relation.getMeta(rel)).toBeDefined();

package/src/Relation.ts

@@ -8,17 +8,20 @@ import * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
 import type { ForeignKey } from '@dxos/echo-protocol';
-import { createJsonPath } from '@dxos/effect';
+import { SchemaEx } from '@dxos/effect';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN, type ObjectId } from '@dxos/keys';
+import { EID, type EntityId, type URI, DXN } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
 import type * as Database from './Database';
 import * as Entity from './Entity';
 import * as internal from './internal';
 import * as entityInternal from './internal/Entity';
+import * as objInternal from './internal/Obj';
 import * as Obj from './Obj';
-import type * as Type from './Type';
+import type * as Ref from './Ref';
+import type * as Tag from './Tag';
+import * as Type from './Type';
 
 export type Endpoints<Source, Target> = {
   [Source]: Source;
@@ -59,24 +62,20 @@ export interface Unknown extends BaseRelation<Obj.Unknown, Obj.Unknown> {}
  * ```
  */
 // TODO(dmaretskyi): Change ObjModule.Any to ObjModule.Unknown to have stricter types.
-export const Unknown: Type.Relation<Unknown, Obj.Any, Obj.Any> = Schema.Struct({
+export const Unknown: internal.UnknownTypeSchema<Unknown, typeof Entity.Kind.Relation> = Schema.Struct({
   id: Schema.String,
 }).pipe(
   Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
-  // TODO(dmaretskyi): Clean this up.
-  // NOTE: The EchoRelationSchema annotation is required for Ref.Ref(Relation.Unknown) to work.
-  //   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.
-  internal.EchoRelationSchema({
-    typename: 'org.dxos.schema.anyRelation',
-    version: '0.0.0',
-    source: Obj.Unknown,
-    target: Obj.Unknown,
+  Schema.annotations({
+    [internal.TypeAnnotationId]: {
+      kind: Entity.Kind.Relation,
+      typename: 'org.dxos.schema.anyRelation',
+      version: '0.0.0',
+      sourceSchema: DXN.make(internal.ANY_OBJECT_TYPENAME, internal.ANY_OBJECT_VERSION),
+      targetSchema: DXN.make(internal.ANY_OBJECT_TYPENAME, internal.ANY_OBJECT_VERSION),
+    },
   }),
-  (schema) =>
-    Object.assign(schema, {
-      [internal.SchemaKindId]: (schema as any)[internal.SchemaKindId],
-    }) as unknown as Type.Relation<Unknown, Obj.Any, Obj.Any>,
-);
+) as unknown as internal.UnknownTypeSchema<Unknown, typeof Entity.Kind.Relation>;
 
 /**
  * Relation type with specific source and target types.
@@ -89,7 +88,7 @@ export type OfShape<Source extends Obj.Unknown, Target extends Obj.Unknown, Prop
  */
 interface BaseRelationSnapshot<Source, Target> extends internal.AnyEntity, Endpoints<Source, Target> {
   readonly [Entity.SnapshotKindId]: internal.EntityKind.Relation;
-  readonly id: ObjectId;
+  readonly id: EntityId;
 }
 
 /**
@@ -129,18 +128,20 @@ export type TargetOf<A> = A extends Endpoints<infer _S, infer T> ? T : never;
 /**
  * Internal props type for relation instance creation.
  */
-type MakePropsInternal<T extends Unknown> = {
-  id?: ObjectId;
-  [Meta]?: internal.ObjectMeta;
+type MakePropsInternal<T extends Endpoints<any, any>> = {
+  id?: EntityId;
+  [Meta]?: Partial<internal.EntityMeta>;
   [Source]: T[Source];
   [Target]: T[Target];
 } & Entity.Properties<T>;
 
 /**
- * Props type for relation creation with a given schema.
- * Takes a schema type (created with Type.Relation) and extracts the props type.
+ * Props type for relation creation with a given schema. Accepts a `Type.AnyRelation`
+ * entity (created with `Type.makeRelation`) and derives the props shape via
+ * `Type.InstanceType`. Object-kind entities are rejected at the type level —
+ * use `Obj.MakeProps` for those.
  */
-export type MakeProps<S extends Type.AnyRelation> = MakePropsInternal<Schema.Schema.Type<S>>;
+export type MakeProps<S extends Type.AnyRelation> = MakePropsInternal<Type.InstanceType<S>>;
 
 /**
  * Creates new relation.
@@ -151,10 +152,11 @@ export type MakeProps<S extends Type.AnyRelation> = MakePropsInternal<Schema.Sch
  */
 // NOTE: Writing the definition this way (with generic over schema) makes typescript perfer to infer the type from the first param (this schema) rather than the second param (the props).
 // TODO(dmaretskyi): Move meta into props.
-export const make = <S extends Type.AnyRelation>(
-  schema: S,
-  props: NoInfer<MakeProps<S>>,
-): Schema.Schema.Type<S> & Entity.OfKind<typeof Entity.Kind.Relation> => {
+export const make = <T extends Type.AnyRelation>(
+  type: T,
+  props: NoInfer<MakeProps<T>>,
+): Type.InstanceType<T> & Entity.OfKind<typeof Entity.Kind.Relation> => {
+  const schema = Type.getSchema(type);
   assertArgument(
     internal.getTypeAnnotation(schema)?.kind === internal.EntityKind.Relation,
     'schema',
@@ -162,22 +164,48 @@ export const make = <S extends Type.AnyRelation>(
   );
   assertArgument(props[internal.ParentId] === undefined, 'props', 'Parent is not allowed for relations');
 
-  let meta: internal.ObjectMeta | undefined = undefined;
+  let meta: internal.EntityMeta | undefined = undefined;
 
   if (props[internal.MetaId] != null) {
     meta = props[internal.MetaId] as any;
     delete props[internal.MetaId];
   }
 
-  const sourceDXN = internal.getObjectDXN(props[Source]) ?? raise(new Error('Unresolved relation source'));
-  const targetDXN = internal.getObjectDXN(props[Target]) ?? raise(new Error('Unresolved relation target'));
+  const sourceDXN = internal.getObjectEchoUri(props[Source]) ?? raise(new Error('Unresolved relation source'));
+  const targetDXN = internal.getObjectEchoUri(props[Target]) ?? raise(new Error('Unresolved relation target'));
 
   (props as any)[internal.RelationSourceDXNId] = sourceDXN;
   (props as any)[internal.RelationTargetDXNId] = targetDXN;
 
-  return internal.makeObject<Schema.Schema.Type<S>>(schema, props as any, meta);
+  // Pass the type entity through as `typeSource` so the resulting instance
+  // carries a back-reference resolvable via `Relation.getType` / `Entity.getType`.
+  return internal.makeObject(schema as any, props as any, meta, type as any) as any;
 };
 
+/**
+ * Test if a value is an instance of a given relation type.
+ *
+ * Mirrors `Obj.instanceOf` but only accepts `Type.AnyRelation` — use
+ * `Obj.instanceOf` for objects and `Type.isType` for `Type.Type` entities.
+ *
+ * @example
+ * ```ts
+ * const isEmployedBy = Relation.instanceOf(EmployedBy);
+ * if (isEmployedBy(relation)) {
+ *   // relation is EmployedBy
+ * }
+ * ```
+ */
+export const instanceOf: {
+  <S extends Type.AnyRelation>(schema: S): (value: unknown) => value is Type.InstanceType<S>;
+  <S extends Type.AnyRelation>(schema: S, value: unknown): value is Type.InstanceType<S>;
+} = ((...args: [schema: Type.AnyRelation, value?: unknown]) => {
+  if (args.length === 1) {
+    return (entity: unknown) => internal.isInstanceOf(args[0], entity);
+  }
+  return internal.isInstanceOf(args[0], args[1]);
+}) as any;
+
 /**
  * Type guard for relations.
  * Returns true for both reactive relations and relation snapshots.
@@ -203,29 +231,29 @@ export const isSnapshot = (value: unknown): value is Snapshot => {
 };
 
 /**
- * @returns Relation source DXN.
+ * @returns Relation source URI.
  * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getSourceDXN = (value: Unknown | Snapshot): DXN => {
+export const getSourceURI = (value: Unknown | Snapshot): EID.EID => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(value);
-  const dxn = (value as internal.InternalObjectProps)[internal.RelationSourceDXNId];
-  invariant(dxn instanceof DXN);
-  return dxn;
+  const uri = (value as internal.InternalObjectProps)[internal.RelationSourceDXNId];
+  invariant(EID.isEID(uri));
+  return uri;
 };
 
 /**
- * @returns Relation target DXN.
+ * @returns Relation target URI.
  * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export const getTargetDXN = (value: Unknown | Snapshot): DXN => {
+export const getTargetURI = (value: Unknown | Snapshot): EID.EID => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(value);
-  const dxn = (value as internal.InternalObjectProps)[internal.RelationTargetDXNId];
-  invariant(dxn instanceof DXN);
-  return dxn;
+  const uri = (value as internal.InternalObjectProps)[internal.RelationTargetDXNId];
+  invariant(EID.isEID(uri));
+  return uri;
 };
 
 /**
@@ -264,7 +292,7 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of a relation within `Relation.change`.
+ * Used to provide a mutable view of a relation within `Relation.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -272,10 +300,10 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo relation within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Relation.change` will throw
+ * when the callback completes. Direct mutations outside of `Relation.update` will throw
  * an error for echo relations.
  *
- * @param relation - The echo relation to mutate. Use `Obj.change` for objects.
+ * @param relation - The echo relation to mutate. Use `Obj.update` for objects.
  * @param callback - The callback that performs mutations on the relation.
  *
  * @example
@@ -286,15 +314,15 @@ export type Mutable<T> = internal.Mutable<T>;
  *   role: 'Engineer',
  * });
  *
- * // Mutate within Relation.change
- * Relation.change(worksFor, (obj) => {
+ * // Mutate within Relation.update
+ * Relation.update(worksFor, (obj) => {
  *   obj.role = 'Senior Engineer';
  * });
  * ```
  *
- * Note: Only accepts relations. Use `Obj.change` for objects.
+ * Note: Only accepts relations. Use `Obj.update` for objects.
  */
-export const change = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(relation, callback);
 };
 
@@ -332,12 +360,12 @@ export const subscribe = (rel: Unknown, callback: () => void): (() => void) => {
  * Accepts both reactive relations and snapshots.
  */
 export const getValue = (rel: Unknown | Snapshot, path: readonly (string | number)[]): any => {
-  return internal.getValue(rel, createJsonPath(path));
+  return SchemaEx.getValue(rel, SchemaEx.createJsonPath(path));
 };
 
 /**
  * Set a deeply nested property on a relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -350,21 +378,30 @@ export const setValue: (rel: Mutable<Unknown>, path: readonly (string | number)[
 //
 
 /**
- * Get the DXN of the relation.
- * Accepts both reactive relations and snapshots.
+ * Get the canonical URI of the relation. Returns `URI.URI` — today always an EID,
+ * but future entity kinds may surface other URI schemes; narrow with `EID.parse(uri)`
+ * or `DXN.tryMake(uri)` at the point of use. Accepts both reactive relations and snapshots.
+ *
+ * @param options.prefer - Controls the URI form (see {@link internal.GetURIOptions}).
  */
-export const getDXN = (entity: Unknown | Snapshot): DXN => internal.getDXN(entity);
+export const getURI = (entity: Unknown | Snapshot, options?: internal.GetURIOptions): URI.URI =>
+  internal.getUri(entity, options);
 
 /**
  * @returns The DXN of the relation's type.
  */
-export const getTypeDXN = internal.getTypeDXN;
+export const getTypeURI: (obj: internal.AnyProperties) => URI.URI | undefined = internal.getTypeURI;
 
 /**
- * Get the schema of the relation.
- * Returns the branded ECHO schema used to create the relation.
+ * Get the type entity (`Type.AnyRelation`) the relation was created from.
+ *
+ * Returns `undefined` when the relation's type isn't registered in this
+ * runtime (e.g. a freshly deserialized snapshot whose type entity hasn't been
+ * wired up yet, or a relation loaded from storage before its schema is known).
+ * To get the Effect Schema from the returned entity, use `Type.getSchema(...)`.
  */
-export const getSchema: (rel: unknown | undefined) => Type.AnyEntity | undefined = internal.getSchema as any;
+export const getType = (relation: Unknown | Snapshot): Type.AnyRelation | undefined =>
+  internal.getType(relation) as Type.AnyRelation | undefined;
 
 /**
  * @returns The typename of the relation's type.
@@ -394,18 +431,18 @@ export const getDatabase = (entity: Unknown | Snapshot): Database.Database | und
 export const Meta = internal.MetaId;
 
 /**
- * Deeply read-only version of ObjectMeta.
+ * Deeply read-only version of EntityMeta.
  */
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Relation.getMeta` inside a `Relation.change` callback.
+ * Mutable meta type returned by `Relation.getMeta` inside a `Relation.update` callback.
  */
 export type Meta = internal.Meta;
 
 /**
  * Get the metadata for a relation.
- * Returns mutable meta when passed a mutable relation (inside `Relation.change` callback).
+ * Returns mutable meta when passed a mutable relation (inside `Relation.update` callback).
  * Returns read-only meta when passed a regular relation or snapshot.
  */
 // TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
@@ -423,7 +460,7 @@ export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[
 
 /**
  * Delete all keys from the relation for the specified source.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -432,21 +469,21 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
  */
-export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.addTag(entity, tag);
+export const addTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.addTag(entity, tag);
 
 /**
  * Remove a tag from the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
  */
-export const removeTag = (entity: Mutable<Unknown>, tag: string): void => internal.removeTag(entity, tag);
+export const removeTag = (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>): void => internal.removeTag(entity, tag);
 
 /**
  * Check if the relation is deleted.
@@ -461,12 +498,16 @@ export const isDeleted = (entity: Unknown | Snapshot): boolean => internal.isDel
 /**
  * Get the label of the relation.
  * Accepts both reactive relations and snapshots.
+ *
+ * @param options.fallback `'typename'` returns the relation's typename when no
+ *   label is set (e.g. `org.dxos.type.table`).
  */
-export const getLabel = (entity: Unknown | Snapshot): string | undefined => internal.getLabel(entity);
+export const getLabel = (entity: Unknown | Snapshot, options?: internal.GetLabelOptions): string | undefined =>
+  internal.getLabel(entity, options);
 
 /**
  * Set the label of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -481,7 +522,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -535,3 +576,9 @@ export type Version = internal.EntityVersion;
  * Accepts both reactive relations and snapshots.
  */
 export const version = (entity: Unknown | Snapshot): Version => internal.version(entity);
+
+//
+// Atoms
+//
+
+export const atom = objInternal.makeRelation;

package/src/Scope.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+/**
+ * Scope targeting a space's automerge documents.
+ *
+ * With no `spaceId`, targets the owning space — i.e. the space of whichever database
+ * executes the query — so callers can reference "this space" without looking up its id.
+ *
+ * @example
+ * ```ts
+ * db.query(Filter.type(Person).from(Scope.space()));            // owning space
+ * db.query(Filter.type(Person).from(Scope.space({ id: otherSpaceId }))); // a specific space
+ * ```
+ */
+export const space = (options?: { id?: string; includeAllFeeds?: boolean }): QueryAST.SpaceScope => ({
+  _tag: 'space',
+  ...(options?.id !== undefined ? { spaceId: options.id } : {}),
+  ...(options?.includeAllFeeds ? { includeAllFeeds: true } : {}),
+});
+
+/**
+ * Scope targeting a code-shipped object/type registry.
+ *
+ * - `'local'`  — the in-process registry attached to the hypergraph (default).
+ * - `'remote'` — a remote registry service (not yet implemented).
+ *
+ * @example
+ * ```ts
+ * // Discover all types — persisted in the space and code-shipped in the registry.
+ * db.query(Filter.type(Type.Type).from(Scope.space(), Scope.registry()));
+ * ```
+ */
+export const registry = (location: 'local' | 'remote' = 'local'): QueryAST.RegistryScope => ({
+  _tag: 'registry',
+  location,
+});
+
+/**
+ * Scope targeting a specific feed (by its underlying queue EID).
+ */
+export const feed = (feedUri: string): QueryAST.FeedScope => ({
+  _tag: 'feed',
+  feedUri,
+});

package/src/Tag.md

@@ -0,0 +1,88 @@
+# Tag
+
+`Tag` is the ECHO type for labelling other objects. The schema is tiny — `{ label, hue? }` — but the _attachment pattern_ varies by use case. This doc covers what's available and which pattern to use.
+
+## What `Tag` is
+
+Definition: [`Tag.ts`](./src/Tag.ts) — `Schema.Struct({ label: String, hue?: String })` with DXN `org.dxos.type.tag@0.1.0`. Carries the `SystemTypeAnnotation` so it's treated as a built-in type by the ECHO runtime.
+
+Helpers on the same module:
+
+- `Tag.make(props)` — constructor.
+- `Tag.Map` — `Record<string, Tag>` alias used by call-site indexes.
+- `Tag.createTagList(tags)` — `Map → Tag[]`, sorted by label.
+- `Tag.findTagByLabel(tags, name)` — case-insensitive label lookup.
+- `Tag.sortTags(a, b)` — `localeCompare` on label.
+
+### Colour (`hue`)
+
+`hue` is a Tailwind colour name (`red`, `orange`, `amber`, …). The canonical list lives in [`IconAnnotation`'s schema](./src/internal/Annotation/annotations.ts) (search `IconAnnotationSchema`). Surfaces that render chips read `hue` to colour the chip; rendering hashes the tag id as a fallback when `hue` is absent.
+
+## Attachment patterns
+
+Three ways an object can carry tags. Pick the one that matches your storage shape:
+
+### 1. `Obj.getMeta(obj).tags` — DXN refs on the object's metadata
+
+The canonical user-tagging path. Each tag lives as a standalone `Tag` object in the space; the _target_ object holds an array of DXN refs to those tags inside its metadata bag. The form layer's [`ObjectProperties`](../../ui/react-ui-form/src/components/ObjectProperties) writes these via the `pinnedTags` control.
+
+Use when: the target object is mutable. Tags can be added/removed cheaply by editing the metadata.
+
+```ts
+const tag = Obj.make(Tag.Tag, { label: 'important', hue: 'amber' });
+db.add(tag);
+Obj.update(target, (t) => {
+  Obj.getMeta(t).tags = [tag.dxn];
+});
+```
+
+### 2. Container-owned tag map — inverse index on the parent
+
+For containers that hold immutable-in-feed objects (mailboxes hold messages, magazines hold posts), the children can't carry tag refs because they're immutable. Instead, the container holds an inverted `tagId → Ref<child>[]` map. Tag _definitions_ live in the same map alongside the assignments.
+
+Use when: the children are append-only feed records, OR you need a fast "all objects tagged X" query without scanning each child.
+
+Reference shape (from plugin-inbox's [`Mailbox.tags`](../../plugins/plugin-inbox/src/types/Mailbox.ts)):
+
+```ts
+Mailbox.tags: Record<TagId, {
+  label: string,
+  hue?: string,
+  source?: 'provider' | 'user',
+  messages: Ref<Message>[],
+}>
+```
+
+Tag-id strategy depends on origin:
+
+| source                              | tag id                            | rationale                                                                                |
+| ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
+| provider-synced (e.g. Gmail labels) | external id (Gmail's `Label_123`) | preserves re-sync idempotence — same external id → same map entry, no duplicates         |
+| user-applied                        | random `EntityId`                 | stable across renames; case-insensitive label dedupe via `findTagByLabel` at create time |
+
+Trade-offs considered and rejected:
+
+- Slug from label (`kebab-case(label)`) — natural dedupe but renaming a tag breaks references that point at the old key.
+- EntityId for everything — uniform but Gmail re-syncs would duplicate provider tags every run unless you also dedupe by label, which loses the external id.
+
+### 3. `HasSubject` relation (deprecated)
+
+The older pattern: a relation with `Source = Tag, Target = Object`. Lives at [`@dxos/types/HasSubject`](../../sdk/types/src/types/HasSubject.ts) and is marked `@deprecated`.
+
+Use when: never, for new code. Existing data is being migrated to one of the two patterns above. The shape is functionally identical to (1), but doing it via a separate relation creates a query overhead (walk all relations for the object) that (1) avoids by inlining the refs.
+
+## Hue conventions
+
+Always store the Tailwind colour name (e.g. `'amber'`), not a hex. Surfaces translate via `data-hue` on the chip, which the design system maps to the right shade. See [`getHashStyles`](../../ui/react-ui-components) for the fallback hash when `hue` is unset.
+
+## plugin-inbox: how the inbox uses Tag
+
+Single source of truth: [`Mailbox.tags`](../../plugins/plugin-inbox/src/types/Mailbox.ts). Pattern 2 (container map). Replaces both the older `Mailbox.labels` (Gmail provider dictionary) and the `HasSubject`-relation user-tagging path with one record.
+
+- Provider labels: `syncLabels` writes `mailbox.tags[gmailLabelId] = { label, source: 'provider', messages: [...] }`. Gmail's id is the map key so re-sync is idempotent.
+- Per-message provider assignments: at sync time, after appending a message to the feed, the sync loop pushes `Ref.make(message)` onto each `mailbox.tags[labelId].messages` it was given.
+- User tags / extractor tags: `Mailbox.applyTag(mailbox, { label, hue? }, message)` find-or-creates a `source: 'user'` entry and pushes a Ref. Idempotent.
+- UI: `Mailbox.buildMessageTagsIndex(mailbox)` inverts the map to `messageId → Tag[]` for `MessageStack` tile chips; `Mailbox.getTagsForMessage(mailbox, message)` for the single-message case in `MessageHeader`.
+- Extractor tagging: extractors that want to tag the source message return `{ tags: [{ label, hue? }] }` in their `ExtractResult`; the `ExtractMessage` dispatcher applies them after persistence. See the trip extractor for an example (`tags: [{ label: 'trip', hue: 'sky' }]`).
+
+Adopting the same pattern in a new plugin: pick this shape when your plugin owns a mutable container with immutable feed-stored children, OR when you want a fast "tagged-with-X" inverted lookup. Copy `applyTag` / `removeTag` / `buildMessageTagsIndex` / `getTagsForMessage` (≈ 80 lines, no plugin-specific logic) and you have a working tag system on day one.

package/src/Tag.ts

@@ -6,6 +6,10 @@
 
 import * as Schema from 'effect/Schema';
 
+import type { ForeignKey } from '@dxos/echo-protocol';
+
+import type * as Database from './Database';
+import * as Filter from './Filter';
 import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
@@ -14,15 +18,13 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.tag',
-    version: '0.1.0',
-  }),
   internal.LabelAnnotation.set(['label']),
-  internal.SystemTypeAnnotation.set(true),
+  internal.HiddenAnnotation.set(true),
+  // Shared DXN so `meta.tags` (the `Ref<Tag>` schema) and this type stay in sync.
+  Type.makeObject(internal.TagTypeDXN),
 );
 
-export type Tag = Schema.Schema.Type<typeof Tag>;
+export type Tag = Type.InstanceType<typeof Tag>;
 
 export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
 
@@ -39,3 +41,44 @@ export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undef
   const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
   return entry ? { ...entry[1], id: entry[0] } : undefined;
 };
+
+/**
+ * Finds or creates a {@link Tag} object in the database.
+ *
+ * - With a foreign `key` (system/provider tags): matched by that key; the label is kept current on
+ *   re-sync. Use a stable key (e.g. `{ source: 'google.com/gmail/label', id }`) for tags whose
+ *   identity is external or well-known.
+ * - Without a key (user tags): matched by case-insensitive label among tags that carry **no**
+ *   foreign key, so it never collides with a keyed system/provider tag of the same label.
+ */
+export const findOrCreate = async (
+  db: Pick<Database.Database, 'query' | 'add'>,
+  options: { label: string; hue?: string; key?: ForeignKey },
+): Promise<Tag> => {
+  const { label, hue, key } = options;
+  const withHue = hue ? { hue } : {};
+  if (key) {
+    const [existing] = await db.query(Filter.foreignKeys(Tag, [key])).run();
+    if (existing) {
+      // Keep label (and hue, when provided) current on re-sync. `hue` is only touched when supplied,
+      // so a label-only re-sync (e.g. Gmail) doesn't wipe a user-set colour.
+      if (existing.label !== label || (hue !== undefined && existing.hue !== hue)) {
+        Obj.update(existing, (existing) => {
+          existing.label = label;
+          if (hue !== undefined) {
+            existing.hue = hue;
+          }
+        });
+      }
+      return existing;
+    }
+    return db.add(Obj.make(Tag, { [Obj.Meta]: { keys: [key] }, label, ...withHue }));
+  }
+
+  const lowered = label.toLowerCase();
+  const candidates = await db.query(Filter.type(Tag)).run();
+  const existing = candidates.find(
+    (tag) => tag.label.toLowerCase() === lowered && (Obj.getMeta(tag).keys ?? []).length === 0,
+  );
+  return existing ?? db.add(make({ label, ...withHue }));
+};