@dxos/echo 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

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

@@ -2,9 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation } from './internal';
+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';
 
@@ -12,18 +18,16 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Tag',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['label']),
+  internal.LabelAnnotation.set(['label']),
+  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);
 
-// TODO(burdon): Rename Map.
 export type Map = Record<string, Tag>;
 
 export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
@@ -37,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 }));
+};

package/src/Type.test.ts

@@ -0,0 +1,257 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { DXN, EntityId } from '@dxos/keys';
+
+import * as Entity from './Entity';
+import * as JsonSchema from './JsonSchema';
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+import * as Type from './Type';
+
+describe('Type', () => {
+  describe('Obj.Unknown schema', () => {
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field). `Obj.Unknown` IS
+      // a raw Effect Schema (branded with EchoSchemaKind), so pass it directly.
+      expect(Schema.is(Obj.Unknown)({ id: 'plain-object' })).toBe(true);
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      expect(Schema.is(Obj.Unknown)(obj)).toBe(true);
+    });
+  });
+
+  describe('Relation.Unknown schema', () => {
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field). `Relation.Unknown`
+      // IS a raw Effect Schema (branded with EchoSchemaKind), so pass it directly.
+      expect(Schema.is(Relation.Unknown)({ id: 'plain-object' })).toBe(true);
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      expect(Schema.is(Relation.Unknown)(rel)).toBe(true);
+    });
+  });
+
+  describe('Type.Type meta-schema', () => {
+    test('Type.Type is branded as the type entity kind', ({ expect }) => {
+      // The Type.Type entity itself is an in-memory object (KindId=Object) that
+      // *declares* a type-kind schema (SchemaKindId=Type).
+      expect(Type.isTypeKind(Type.Type)).toBe(true);
+      expect(Type.isObject(Type.Type)).toBe(false);
+      expect(Type.isRelation(Type.Type)).toBe(false);
+    });
+
+    test('static object/relation types are not type-kind', ({ expect }) => {
+      expect(Type.isTypeKind(TestSchema.Person)).toBe(false);
+      expect(Type.isTypeKind(TestSchema.HasManager)).toBe(false);
+    });
+
+    test('Type.getMeta(Type.Type) reports key/version of the meta-schema', ({ expect }) => {
+      // `Type.getMeta` returns the entity's `EntityMeta`. For the static
+      // `Type.Type` meta-schema entity the key/version reflect its registry
+      // identity. The schema-kind brand is on `[SchemaKindId]`, not in meta.
+      const meta = Type.getMeta(Type.Type);
+      expect(meta.key).toBe('org.dxos.type.schema');
+      expect(meta.version).toBe('0.1.0');
+      expect(Type.isTypeKind(Type.Type)).toBe(true);
+    });
+
+    test('Type.getURI(Type.Type) returns the meta-schema DXN', ({ expect }) => {
+      expect(Type.getURI(Type.Type).toString()).toBe('dxn:org.dxos.type.schema:0.1.0');
+    });
+  });
+
+  describe('Type.makeObjectFromJsonSchema', () => {
+    test('creates an instance branded KindId=type', ({ expect }) => {
+      const entity = Type.makeObjectFromJsonSchema({
+        typename: 'com.example.type.test',
+        version: '0.1.0',
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.Number })),
+      });
+      expect((entity as any)[Entity.KindId]).toBe(Entity.Kind.Type);
+      // `typename` / `version` are not direct fields on a persisted `Type.Type`;
+      // they live in `EntityMeta` (the canonical registry-provenance pair).
+      // Read them via the helpers (or `Type.getMeta`).
+      expect(Type.getTypename(entity)).toBe('com.example.type.test');
+      expect(Type.getVersion(entity)).toBe('0.1.0');
+      expect(entity.jsonSchema).toBeDefined();
+    });
+
+    test('defaults version to 0.0.0 for drafts', ({ expect }) => {
+      const draft = Type.makeObjectFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.String })),
+      });
+      // Drafts default version to `'0.0.0'` in `EntityMeta.version`; the
+      // typename (`EntityMeta.key`) is undefined until set.
+      expect(Type.getVersion(draft)).toBe('0.0.0');
+      const meta = Type.getMeta(draft);
+      expect(meta.key).toBeUndefined();
+      expect(meta.version).toBe('0.0.0');
+    });
+
+    test('assigns a stable id', ({ expect }) => {
+      const a = Type.makeObjectFromJsonSchema({ jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})) });
+      const b = Type.makeObjectFromJsonSchema({ jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})) });
+      expect(typeof a.id).toBe('string');
+      expect(a.id).not.toBe(b.id);
+    });
+
+    test('result satisfies isType', ({ expect }) => {
+      const entity = Type.makeObjectFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.Number })),
+      });
+      expect(Type.isType(entity)).toBe(true);
+    });
+  });
+
+  describe('Type.makeRelationFromJsonSchema', () => {
+    test('embeds source/target DXNs into jsonSchema', ({ expect }) => {
+      const entity = Type.makeRelationFromJsonSchema({
+        typename: 'com.example.type.testRel',
+        version: '0.1.0',
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ note: Schema.String })),
+        source: TestSchema.Person,
+        target: TestSchema.Organization,
+      });
+      expect((entity as any)[Entity.KindId]).toBe(Entity.Kind.Type);
+      expect(entity.jsonSchema.entityKind).toBe(Entity.Kind.Relation);
+      expect((entity.jsonSchema as any).relationSource?.$ref).toBe(Type.getURI(TestSchema.Person).toString());
+      expect((entity.jsonSchema as any).relationTarget?.$ref).toBe(Type.getURI(TestSchema.Organization).toString());
+    });
+
+    test('accepts Obj.Unknown as source/target', ({ expect }) => {
+      const entity = Type.makeRelationFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})),
+        source: Obj.Unknown,
+        target: Obj.Unknown,
+      });
+      const unknownURI = 'dxn:org.dxos.schema.anyObject:0.0.0';
+      expect((entity.jsonSchema as any).relationSource?.$ref).toBe(unknownURI);
+      expect((entity.jsonSchema as any).relationTarget?.$ref).toBe(unknownURI);
+    });
+
+    test('defaults version to 0.0.0 for drafts', ({ expect }) => {
+      const draft = Type.makeRelationFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})),
+        source: TestSchema.Person,
+        target: TestSchema.Person,
+      });
+      expect(Type.getVersion(draft)).toBe('0.0.0');
+      const meta = Type.getMeta(draft);
+      expect(meta.key).toBeUndefined();
+      expect(meta.version).toBe('0.0.0');
+    });
+  });
+
+  describe('Obj/Relation/Entity.getType', () => {
+    test('Obj.getType returns the static type entity for instances of Type.makeObject', ({ expect }) => {
+      const person = Obj.make(TestSchema.Person, { name: 'Alice' });
+      expect(Obj.getType(person)).toBe(TestSchema.Person);
+    });
+
+    test('Relation.getType returns the static type entity for instances of Type.makeRelation', ({ expect }) => {
+      const a = Obj.make(TestSchema.Person, { name: 'A' });
+      const b = Obj.make(TestSchema.Person, { name: 'B' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: a,
+        [Relation.Target]: b,
+      });
+      expect(Relation.getType(rel)).toBe(TestSchema.HasManager);
+    });
+
+    test('Entity.getType narrows uniformly across object/relation instances', ({ expect }) => {
+      const person = Obj.make(TestSchema.Person, { name: 'A' });
+      const a = Obj.make(TestSchema.Person, { name: 'A' });
+      const b = Obj.make(TestSchema.Person, { name: 'B' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: a,
+        [Relation.Target]: b,
+      });
+      expect(Entity.getType(person)).toBe(TestSchema.Person);
+      expect(Entity.getType(rel)).toBe(TestSchema.HasManager);
+    });
+  });
+
+  describe('static type factories', () => {
+    test('Type.makeObject stamps schema-kind=object', ({ expect }) => {
+      expect((TestSchema.Person as any)['~@dxos/echo/SchemaKind']).toBe(Entity.Kind.Object);
+      expect(Type.isObject(TestSchema.Person)).toBe(true);
+    });
+
+    test('Type.makeRelation stamps schema-kind=relation', ({ expect }) => {
+      expect((TestSchema.HasManager as any)['~@dxos/echo/SchemaKind']).toBe(Entity.Kind.Relation);
+      expect(Type.isRelation(TestSchema.HasManager)).toBe(true);
+    });
+
+    test('Type.getURI returns the DXN for static types', ({ expect }) => {
+      expect(Type.getURI(TestSchema.Person).toString()).toBe('dxn:com.example.type.person:0.1.0');
+      expect(Type.getURI(TestSchema.HasManager).toString()).toBe('dxn:com.example.type.hasManager:0.1.0');
+    });
+  });
+
+  describe('deterministic id default', () => {
+    // The default id is `EntityId.deterministic(typename, version)` — required so that
+    // `Type.makeObject(...)` never calls `crypto.getRandomValues()` at module-evaluation
+    // time (forbidden by Cloudflare workerd in global scope).
+    const personDxn = DXN.make('com.example.type.deterministic.person', '0.1.0');
+    const worksForDxn = DXN.make('com.example.type.deterministic.worksFor', '0.1.0');
+
+    test('Type.makeObject with the same DXN twice yields entities with identical ids', ({ expect }) => {
+      const a = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      const b = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      expect(a.id).toBe(b.id);
+      expect(a.id).toBe(EntityId.deterministic('com.example.type.deterministic.person', '0.1.0'));
+    });
+
+    test('different versions produce different ids', ({ expect }) => {
+      const v1 = Schema.Struct({ name: Schema.String }).pipe(
+        Type.makeObject(DXN.make('com.example.type.deterministic.person', '0.1.0')),
+      );
+      const v2 = Schema.Struct({ name: Schema.String }).pipe(
+        Type.makeObject(DXN.make('com.example.type.deterministic.person', '0.2.0')),
+      );
+      expect(v1.id).not.toBe(v2.id);
+    });
+
+    test('Type.makeObject({ id }) override is honoured', ({ expect }) => {
+      const explicit = EntityId.random();
+      const entity = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn, { id: explicit }));
+      expect(entity.id).toBe(explicit);
+      // And the default still kicks in when no override is supplied.
+      const defaultEntity = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      expect(defaultEntity.id).not.toBe(explicit);
+    });
+
+    test('Type.makeRelation defaults id to deterministic(typename, version)', ({ expect }) => {
+      const a = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({ dxn: worksForDxn, source: TestSchema.Person, target: TestSchema.Organization }),
+      );
+      const b = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({ dxn: worksForDxn, source: TestSchema.Person, target: TestSchema.Organization }),
+      );
+      expect(a.id).toBe(b.id);
+      expect(a.id).toBe(EntityId.deterministic('com.example.type.deterministic.worksFor', '0.1.0'));
+    });
+
+    test('Type.makeRelation({ id }) override is honoured', ({ expect }) => {
+      const explicit = EntityId.random();
+      const entity = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({
+          dxn: worksForDxn,
+          source: TestSchema.Person,
+          target: TestSchema.Organization,
+          id: explicit,
+        }),
+      );
+      expect(entity.id).toBe(explicit);
+    });
+  });
+});