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

package/dist/types/src/Registry.d.ts

@@ -0,0 +1,131 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { type ReadOnlyEvent } from '@dxos/async';
+import type * as Database from './Database';
+import * as Entity from './Entity';
+import type * as Filter from './Filter';
+import type * as Query from './Query';
+/**
+ * Identifier denoting an ECHO Registry.
+ */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/**
+ * Composable, in-memory registry of keyed ECHO entities.
+ *
+ * Entities are stored by id and queried via the standard ECHO Query API.
+ * A registry may delegate to an optional upstream registry: results from the local
+ * registry take precedence and upstream results fill in anything not found locally.
+ *
+ * Intended use cases include caches of schemas, operations, blueprints, routines, plugins,
+ * etc., sourced from 3rd-party plugins, local code, or local space objects.
+ *
+ * Types (schema-definition entities produced by `Type.makeObject` / `Type.makeRelation`) are
+ * stored the same way as any other entity — via `add()`. Use `list().filter(Type.isType)` to
+ * retrieve them.
+ *
+ * Scope: a Registry is independent of any ECHO space or Hypergraph — it is a process-local,
+ * in-memory cache. Wire one per space (e.g. as a Layer scoped to the space's Effect runtime)
+ * or share a single instance across spaces depending on the use case.
+ *
+ * The concrete implementation (and the `makeRegistry` / `registryLayer` factories) lives in
+ * `@dxos/echo-client`; this module declares only the interface so that the `@dxos/echo` API surface
+ * stays free of query-matching dependencies.
+ */
+export interface Registry {
+    readonly [TypeId]: TypeId;
+    /**
+     * Stable per-instance identifier. Used to key process-local resources (e.g. memoized
+     * reactive atoms) to a specific registry instance, analogous to {@link Database.spaceId}.
+     */
+    readonly id: string;
+    /**
+     * Fires whenever local registry contents change (add, remove, or clear).
+     */
+    readonly changed: ReadOnlyEvent<void>;
+    /**
+     * All locally-stored entities.
+     * Does not include upstream entities — use {@link list} for that.
+     */
+    readonly local: readonly Entity.Unknown[];
+    /**
+     * Add or replace one or more entities in the local registry.
+     * Existing entries with the same id are replaced.
+     * Also indexes type entities by DXN for fast lookup.
+     */
+    add(entities: readonly Entity.Unknown[]): void;
+    /**
+     * Remove an entity by id from the local registry.
+     * @returns true if an entity was removed, false if it was not found.
+     */
+    remove(id: string): boolean;
+    /**
+     * Remove all locally-stored entities.
+     * Does not affect the upstream registry.
+     */
+    clear(): void;
+    /**
+     * Get an entity by id.
+     * Searches the local registry first, then falls back to the upstream registry.
+     */
+    get(id: string): Entity.Unknown | undefined;
+    /**
+     * Get an entity by one of its addressing URIs — a type entity by its typename DXN (or, when
+     * persisted, its identifier EID), a keyed entity by its `dxn:<key>[:<version>]`. Accepts legacy
+     * DXN forms (normalized internally). Searches the local registry first, then falls back to the
+     * upstream registry. Narrow the result with `Type.isType` when a type entity is required.
+     */
+    getByURI(uri: string): Entity.Unknown | undefined;
+    /**
+     * List all entities.
+     * Local entities take precedence over upstream entities with the same id.
+     */
+    list(): Entity.Unknown[];
+    /**
+     * Run an ECHO query against the registry's entities (implements {@link Database.Queryable}).
+     *
+     * Matching happens in-memory over {@link list}. Scope (`from`) clauses are unwrapped and
+     * ignored — a direct registry query always targets the registry's own entities. The primary
+     * way to query registry contents is still through the database (`db.query(...).from(Scope.registry())`),
+     * which fans the database and registry together; this method is for querying a registry directly.
+     *
+     * Only locally-evaluable AST nodes are supported: `select`, `filter`, `limit`, `from`, `options`,
+     * and boolean combinators. Server-side concerns (order, traversal, text/timestamp filters) throw.
+     */
+    query: Database.QueryFn;
+}
+/**
+ * Type guard for {@link Registry}.
+ */
+export declare const isRegistry: (obj: unknown) => obj is Registry;
+/**
+ * Options for the registry factory (`makeRegistry` in `@dxos/echo-client`).
+ */
+export type Options = {
+    /**
+     * Optional upstream registry. Queries fall back to upstream when an entity
+     * is not present in the local registry.
+     */
+    upstream?: Registry;
+    /**
+     * Initial set of entities to seed the local registry with.
+     */
+    initial?: readonly Entity.Unknown[];
+};
+declare const Service_base: Context.TagClass<Service, "@dxos/echo/Registry/Service", Registry>;
+/**
+ * Effect Context tag for {@link Registry}.
+ * Use this to inject a registry into Effect-based code.
+ */
+export declare class Service extends Service_base {
+}
+/**
+ * Executes a query against the registry and returns the results.
+ * Analogous to {@link Database.query} `.run` for the in-process registry.
+ */
+export declare 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>;
+};
+export {};
+//# sourceMappingURL=Registry.d.ts.map

package/dist/types/src/Registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Registry.d.ts","sourceRoot":"","sources":["../../../src/Registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,KAAK,QAAQ,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AACnC,OAAO,KAAK,KAAK,MAAM,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,SAAS,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,MAAM,eAAoC,CAAC;AACxD,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,CAAC,OAAO,EAAE,CAAC;IAE1C;;;;OAIG;IACH,GAAG,CAAC,QAAQ,EAAE,SAAS,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IAE/C;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;OAGG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;IAElD;;;OAGG;IACH,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,QAAS,OAAO,KAAG,GAAG,IAAI,QAC8D,CAAC;AAEhH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,CAAC,OAAO,EAAE,CAAC;CACrC,CAAC;;AAEF;;;GAGG;AACH,qBAAa,OAAQ,SAAQ,YAA+D;CAAG;AAE/F;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;CAKjF,CAAC"}

package/dist/types/src/Relation.d.ts

@@ -1,61 +1,359 @@
-import * as Schema from 'effect/Schema';
-import { DXN } from '@dxos/keys';
-import { type Live } from '@dxos/live-object';
-import * as EchoSchema from './internal';
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { EID, type EntityId, type URI } from '@dxos/keys';
+import type * as Database from './Database';
+import * as Entity from './Entity';
+import * as internal from './internal';
 import * as Obj from './Obj';
+import type * as Ref from './Ref';
+import type * as Tag from './Tag';
 import * as Type from './Type';
+export type Endpoints<Source, Target> = {
+    [Source]: Source;
+    [Target]: Target;
+};
 /**
- * NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
+ * Base type for all ECHO relations.
+ * @private
  */
-interface BaseRelation<Source, Target> extends EchoSchema.HasId, Type.Relation.Endpoints<Source, Target>, Type.OfKind<EchoSchema.EntityKind.Relation> {
+interface BaseRelation<Source, Target> extends internal.AnyEntity, Endpoints<Source, Target>, Entity.OfKind<internal.EntityKind.Relation> {
 }
 /**
- * Relation type with specific properties.
+ * Relation with no known properties beyond id, kind, source, and target.
+ * Use this when the relation's schema/properties are not known.
+ *
+ * NOTE: This is a TypeScript type only, not a schema.
+ * To validate that a value is an ECHO relation, use `Relation.isRelation`.
  */
-export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = BaseRelation<Source, Target> & Props;
+export interface Unknown extends BaseRelation<Obj.Unknown, Obj.Unknown> {
+}
 /**
- * Base type for all ECHO relations.
+ * Runtime Effect schema for any ECHO relation.
+ * Use for validation, parsing, or as a reference target for collections.
+ * A relation has `id`, source, and target fields plus any additional properties.
+ *
+ * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).
+ * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.
+ *
+ * @example
+ * ```ts
+ * // Structural type guard (accepts any object with id field)
+ * if (Schema.is(Type.Relation)(unknownValue)) { ... }
+ *
+ * // ECHO instance type guard (checks KindId brand)
+ * if (Relation.isRelation(unknownValue)) { ... }
+ * ```
  */
-export interface Any extends BaseRelation<Obj.Any, Obj.Any> {
+export declare const Unknown: internal.UnknownTypeSchema<Unknown, typeof Entity.Kind.Relation>;
+/**
+ * Relation type with specific source and target types.
+ */
+export type OfShape<Source extends Obj.Unknown, Target extends Obj.Unknown, Props> = BaseRelation<Source, Target> & Props;
+/**
+ * Base type for snapshot relations (has SnapshotKindId instead of KindId).
+ */
+interface BaseRelationSnapshot<Source, Target> extends internal.AnyEntity, Endpoints<Source, Target> {
+    readonly [Entity.SnapshotKindId]: internal.EntityKind.Relation;
+    readonly id: EntityId;
 }
-export declare const Any: Type.relation<Schema.Struct<{}>, Type.obj<Schema.Struct<{}>>, Type.obj<Schema.Struct<{}>>>;
+/**
+ * JSON-encoded properties for relations.
+ */
+export interface BaseRelationJson {
+    id: string;
+    [internal.ATTR_RELATION_SOURCE]: string;
+    [internal.ATTR_RELATION_TARGET]: string;
+}
+/**
+ * Immutable snapshot of an ECHO relation.
+ * Branded with SnapshotKindId (not KindId).
+ * Property values are frozen at the time the snapshot was created.
+ * Returned by getSnapshot() and hooks.
+ */
+export type Snapshot<T extends Unknown = Unknown> = Omit<T, Entity.KindId> & BaseRelationSnapshot<Obj.Unknown, Obj.Unknown>;
 export declare const Source: unique symbol;
 export type Source = typeof Source;
 export declare const Target: unique symbol;
 export type Target = typeof Target;
-type MakeProps<T extends Any> = {
-    id?: EchoSchema.ObjectId;
+/**
+ * Get relation source type.
+ */
+export type SourceOf<A> = A extends Endpoints<infer S, infer _T> ? S : never;
+/**
+ * Get relation target type.
+ */
+export type TargetOf<A> = A extends Endpoints<infer _S, infer T> ? T : never;
+/**
+ * Internal props type for relation instance creation.
+ */
+type MakePropsInternal<T extends Endpoints<any, any>> = {
+    id?: EntityId;
     [Source]: T[Source];
     [Target]: T[Target];
-} & Type.Properties<T>;
+} & Entity.Properties<T>;
+/**
+ * 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<Type.InstanceType<S>>;
 /**
  * Creates new relation.
  * @param schema - Relation schema.
  * @param props - Relation properties. Endpoints are passed as [Relation.Source] and [Relation.Target] keys.
- * @param meta - Relation metadata.
+ * @param meta - Relation metadata. (deprecated; use [Obj.Meta] instead)
  * @returns
  */
-export declare const make: <S extends Type.Relation.Any>(schema: S, props: NoInfer<MakeProps<Schema.Schema.Type<S>>>, meta?: EchoSchema.ObjectMeta) => Live<Schema.Schema.Type<S> & Type.OfKind<EchoSchema.EntityKind.Relation>>;
-export declare const isRelation: (value: unknown) => value is Any;
+export declare const make: <T extends Type.AnyRelation>(type: T, props: NoInfer<MakeProps<T>>) => Type.InstanceType<T> & Entity.OfKind<typeof Entity.Kind.Relation>;
 /**
- * @returns Relation source DXN.
+ * 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 declare 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>;
+};
+/**
+ * Type guard for relations.
+ * Returns true for both reactive relations and relation snapshots.
+ */
+export declare const isRelation: (value: unknown) => value is Unknown;
+export declare const isSnapshot: (value: unknown) => value is Snapshot;
+/**
+ * @returns Relation source URI.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export declare const getSourceDXN: (value: Any) => DXN;
+export declare const getSourceURI: (value: Unknown | Snapshot) => EID.EID;
 /**
- * @returns Relation target DXN.
+ * @returns Relation target URI.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export declare const getTargetDXN: (value: Any) => DXN;
+export declare const getTargetURI: (value: Unknown | Snapshot) => EID.EID;
 /**
  * @returns Relation source.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export declare const getSource: <T extends Any>(relation: T) => Type.Relation.Source<T>;
+export declare const getSource: <T extends Unknown | Snapshot>(relation: T) => SourceOf<T>;
 /**
  * @returns Relation target.
+ * Accepts both reactive relations and snapshots.
  * @throws If the object is not a relation.
  */
-export declare const getTarget: <T extends Any>(relation: T) => Type.Relation.Target<T>;
+export declare 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.update`.
+ */
+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.update` will throw
+ * an error for echo relations.
+ *
+ * @param relation - The echo relation to mutate. Use `Obj.update` for objects.
+ * @param callback - The callback that performs mutations on the relation.
+ *
+ * @example
+ * ```ts
+ * const worksFor = Relation.make(EmployedBy, {
+ *   [Relation.Source]: person,
+ *   [Relation.Target]: company,
+ *   role: 'Engineer',
+ * });
+ *
+ * // Mutate within Relation.update
+ * Relation.update(worksFor, (obj) => {
+ *   obj.role = 'Senior Engineer';
+ * });
+ * ```
+ *
+ * Note: Only accepts relations. Use `Obj.update` for objects.
+ */
+export declare const update: <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>) => void;
+/**
+ * Returns an immutable snapshot of a relation.
+ * The snapshot is branded with SnapshotKindId instead of KindId,
+ * making it distinguishable from the reactive relation at the type level.
+ */
+export declare const getSnapshot: <T extends Unknown>(rel: T) => Snapshot<T>;
+/**
+ * Subscribe to relation updates.
+ * The callback is called synchronously when the relation is modified.
+ * Only accepts reactive relations (not snapshots).
+ * @returns Unsubscribe function.
+ */
+export declare const subscribe: (rel: Unknown, callback: () => void) => (() => void);
+/**
+ * Get a deeply nested property from a relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const getValue: (rel: Unknown | Snapshot, path: readonly (string | number)[]) => any;
+/**
+ * Set a deeply nested property on a relation.
+ * 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 declare const setValue: (rel: Mutable<Unknown>, path: readonly (string | number)[], value: any) => void;
+/**
+ * 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 declare const getURI: (entity: Unknown | Snapshot, options?: internal.GetURIOptions) => URI.URI;
+/**
+ * @returns The DXN of the relation's type.
+ */
+export declare const getTypeURI: (obj: internal.AnyProperties) => URI.URI | undefined;
+/**
+ * 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 declare const getType: (relation: Unknown | Snapshot) => Type.AnyRelation | undefined;
+/**
+ * @returns The typename of the relation's type.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const getTypename: (entity: Unknown | Snapshot) => string | undefined;
+/**
+ * Get the database the relation belongs to.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const getDatabase: (entity: Unknown | Snapshot) => Database.Database | undefined;
+/**
+ * Property that accesses metadata for an entity.
+ *
+ * Alias for `Entity.Meta`.
+ */
+export declare const Meta: symbol;
+/**
+ * Deeply read-only version of EntityMeta.
+ */
+export type ReadonlyMeta = internal.ReadonlyMeta;
+/**
+ * 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.update` callback).
+ * Returns read-only meta when passed a regular relation or snapshot.
+ */
+export declare function getMeta(entity: Mutable<Unknown>): Meta;
+export declare function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
+/**
+ * @returns Foreign keys for the relation from the specified source.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const getKeys: (entity: Unknown | Snapshot, source: string) => ForeignKey[];
+/**
+ * Delete all keys from the relation for the specified source.
+ * 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 declare const deleteKeys: (entity: Mutable<Unknown>, source: string) => void;
+/**
+ * Add a tag to the relation.
+ * 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 declare const addTag: (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>) => void;
+/**
+ * Remove a tag from the relation.
+ * 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 declare const removeTag: (entity: Mutable<Unknown>, tag: Ref.Ref<Tag.Tag>) => void;
+/**
+ * Check if the relation is deleted.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const isDeleted: (entity: Unknown | Snapshot) => boolean;
+/**
+ * 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 declare const getLabel: (entity: Unknown | Snapshot, options?: internal.GetLabelOptions) => string | undefined;
+/**
+ * Set the label of the relation.
+ * 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 declare const setLabel: (entity: Mutable<Unknown>, label: string) => void;
+/**
+ * Get the description of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const getDescription: (entity: Unknown | Snapshot) => string | undefined;
+/**
+ * Set the description of the relation.
+ * 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 declare const setDescription: (entity: Mutable<Unknown>, description: string) => void;
+/**
+ * JSON representation of a relation.
+ */
+export type JSON = internal.ObjectJSON;
+/**
+ * Converts relation to its JSON representation.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const toJSON: (entity: Unknown | Snapshot) => JSON;
+/**
+ * Comparator function type for sorting relations.
+ * Accepts both reactive relations and snapshots.
+ */
+export type Comparator = internal.Comparator<Unknown | Snapshot>;
+export declare const sortByLabel: Comparator;
+export declare const sortByTypename: Comparator;
+export declare const sort: (...comparators: Comparator[]) => Comparator;
+export declare const VersionTypeId: "~@dxos/echo/VersionTypeId";
+export declare const isVersion: (entity: unknown) => entity is internal.EntityVersion;
+/**
+ * Represent relation version.
+ */
+export type Version = internal.EntityVersion;
+/**
+ * Returns the version of the relation.
+ * Accepts both reactive relations and snapshots.
+ */
+export declare const version: (entity: Unknown | Snapshot) => Version;
+export declare const atom: <T extends Unknown>(relation: T) => import("@effect-atom/atom/Atom").Atom<Snapshot<T>>;
 export {};
 //# sourceMappingURL=Relation.d.ts.map

package/dist/types/src/Relation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../../src/Relation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAI9C,OAAO,KAAK,UAAU,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;GAEG;AACH,UAAU,YAAY,CAAC,MAAM,EAAE,MAAM,CACnC,SAAQ,UAAU,CAAC,KAAK,EACtB,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACvC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC;CAAG;AAElD;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;AAEnH;;GAEG;AACH,MAAM,WAAW,GAAI,SAAQ,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;CAAG;AAE9D,eAAO,MAAM,GAAG,4FAOf,CAAC;AAGF,eAAO,MAAM,MAAM,EAAE,OAAO,MAA2C,CAAC;AACxE,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AACnC,eAAO,MAAM,MAAM,EAAE,OAAO,MAA2C,CAAC;AACxE,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC;AAEnC,KAAK,SAAS,CAAC,CAAC,SAAS,GAAG,IAAI;IAC9B,EAAE,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC;IACzB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;CACrB,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAEvB;;;;;;GAMG;AAGH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,EAC9C,QAAQ,CAAC,EACT,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAChD,OAAO,UAAU,CAAC,UAAU,KAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAkB1E,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,GAUpD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,GAAG,KAAG,GAMzC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,GAAG,KAAG,GAMzC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,GAAG,EAAE,UAAU,CAAC,KAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAM5E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,GAAG,EAAE,UAAU,CAAC,KAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAM5E,CAAC"}
+{"version":3,"file":"Relation.d.ts","sourceRoot":"","sources":["../../../src/Relation.ts"],"names":[],"mappings":"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"}

package/dist/types/src/Relation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Relation.test.d.ts.map

package/dist/types/src/Relation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relation.test.d.ts","sourceRoot":"","sources":["../../../src/Relation.test.ts"],"names":[],"mappings":""}

package/dist/types/src/Scope.d.ts

@@ -0,0 +1,35 @@
+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 declare const space: (options?: {
+    id?: string;
+    includeAllFeeds?: boolean;
+}) => QueryAST.SpaceScope;
+/**
+ * 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 declare const registry: (location?: 'local' | 'remote') => QueryAST.RegistryScope;
+/**
+ * Scope targeting a specific feed (by its underlying queue EID).
+ */
+export declare const feed: (feedUri: string) => QueryAST.FeedScope;
+//# sourceMappingURL=Scope.d.ts.map

package/dist/types/src/Scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scope.d.ts","sourceRoot":"","sources":["../../../src/Scope.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,aAAc;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,KAAG,QAAQ,CAAC,UAIpF,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,cAAc,OAAO,GAAG,QAAQ,KAAa,QAAQ,CAAC,aAGzE,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,IAAI,YAAa,MAAM,KAAG,QAAQ,CAAC,SAG9C,CAAC"}

package/dist/types/src/Tag.d.ts

@@ -1,17 +1,34 @@
 import * as Schema from 'effect/Schema';
+import type { ForeignKey } from '@dxos/echo-protocol';
+import type * as Database from './Database';
+import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
-export declare const Tag: Type.obj<Schema.Struct<{
-    label: typeof Schema.String;
-    hue: Schema.optional<typeof Schema.String>;
-}>>;
-export type Tag = Schema.Schema.Type<typeof Tag>;
-export declare const make: (props: Obj.MakeProps<typeof Tag>) => import("@dxos/live-object").Live<Type.OfKind<import("./internal").EntityKind.Object> & {
-    label: string;
-    hue?: string | undefined;
-}>;
+export declare const Tag: Type.Obj<{
+    readonly label: string;
+    readonly hue?: string | undefined;
+}, Schema.Struct.Fields>;
+export type Tag = Type.InstanceType<typeof Tag>;
+export declare const make: (props: Obj.MakeProps<typeof Tag>) => Obj.OfShape<{
+    readonly label: string;
+    readonly hue?: string | undefined;
+} & import("./Entity").OfKind<internal.EntityKind.Object>>;
 export type Map = Record<string, Tag>;
 export declare const sortTags: ({ label: a }: Tag, { label: b }: Tag) => number;
 export declare const createTagList: (tags: Map) => Tag[];
 export declare const findTagByLabel: (tags: Map | undefined, name: string) => Tag | 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 declare const findOrCreate: (db: Pick<Database.Database, 'query' | 'add'>, options: {
+    label: string;
+    hue?: string;
+    key?: ForeignKey;
+}) => Promise<Tag>;
 //# sourceMappingURL=Tag.d.ts.map

package/dist/types/src/Tag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Tag.d.ts","sourceRoot":"","sources":["../../../src/Tag.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B,eAAO,MAAM,GAAG;;;GASf,CAAC;AAEF,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;AAEjD,eAAO,MAAM,IAAI,GAAI,OAAO,GAAG,CAAC,SAAS,CAAC,OAAO,GAAG,CAAC;;;EAAyB,CAAC;AAG/E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC,eAAO,MAAM,QAAQ,GAAI,cAAc,GAAG,EAAE,cAAc,GAAG,WAAuB,CAAC;AAErF,eAAO,MAAM,aAAa,GAAI,MAAM,GAAG,KAAG,GAAG,EAG1B,CAAC;AAEpB,eAAO,MAAM,cAAc,GAAI,MAAM,GAAG,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,GAAG,GAAG,SAG1E,CAAC"}
+{"version":3,"file":"Tag.d.ts","sourceRoot":"","sources":["../../../src/Tag.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,KAAK,QAAQ,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B,eAAO,MAAM,GAAG;;;wBAQf,CAAC;AAEF,MAAM,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,GAAG,CAAC,CAAC;AAEhD,eAAO,MAAM,IAAI,UAAW,GAAG,CAAC,SAAS,CAAC,OAAO,GAAG,CAAC;;;0DAAyB,CAAC;AAE/E,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtC,eAAO,MAAM,QAAQ,iBAAkB,GAAG,gBAAgB,GAAG,WAAuB,CAAC;AAErF,eAAO,MAAM,aAAa,SAAU,GAAG,KAAG,GAAG,EAG1B,CAAC;AAEpB,eAAO,MAAM,cAAc,SAAU,GAAG,GAAG,SAAS,QAAQ,MAAM,KAAG,GAAG,GAAG,SAG1E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,OACnB,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,WACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,UAAU,CAAA;CAAE,KACzD,OAAO,CAAC,GAAG,CA2Bb,CAAC"}