@dxos/echo 0.8.4-main.03d5cd7b56 → 0.8.4-main.05e74ebcff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.03d5cd7b56",
+  "version": "0.8.4-main.05e74ebcff",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -135,18 +135,18 @@
   ],
   "dependencies": {
     "effect": "3.20.0",
-    "@dxos/context": "0.8.4-main.03d5cd7b56",
-    "@dxos/debug": "0.8.4-main.03d5cd7b56",
-    "@dxos/errors": "0.8.4-main.03d5cd7b56",
-    "@dxos/echo-protocol": "0.8.4-main.03d5cd7b56",
-    "@dxos/effect": "0.8.4-main.03d5cd7b56",
-    "@dxos/invariant": "0.8.4-main.03d5cd7b56",
-    "@dxos/async": "0.8.4-main.03d5cd7b56",
-    "@dxos/keys": "0.8.4-main.03d5cd7b56",
-    "@dxos/log": "0.8.4-main.03d5cd7b56",
-    "@dxos/protocols": "0.8.4-main.03d5cd7b56",
-    "@dxos/node-std": "0.8.4-main.03d5cd7b56",
-    "@dxos/util": "0.8.4-main.03d5cd7b56"
+    "@dxos/async": "0.8.4-main.05e74ebcff",
+    "@dxos/context": "0.8.4-main.05e74ebcff",
+    "@dxos/debug": "0.8.4-main.05e74ebcff",
+    "@dxos/echo-protocol": "0.8.4-main.05e74ebcff",
+    "@dxos/errors": "0.8.4-main.05e74ebcff",
+    "@dxos/invariant": "0.8.4-main.05e74ebcff",
+    "@dxos/keys": "0.8.4-main.05e74ebcff",
+    "@dxos/log": "0.8.4-main.05e74ebcff",
+    "@dxos/node-std": "0.8.4-main.05e74ebcff",
+    "@dxos/protocols": "0.8.4-main.05e74ebcff",
+    "@dxos/util": "0.8.4-main.05e74ebcff",
+    "@dxos/effect": "0.8.4-main.05e74ebcff"
   },
   "publishConfig": {
     "access": "public"

package/src/Database.ts

@@ -38,7 +38,7 @@ export interface QueryFn {
 }
 
 /**
- * Common interface for Database and Queue.
+ * Common interface for Database, Feed, and Hypergraph.
  */
 export interface Queryable {
   query: QueryFn;

package/src/Feed.ts

@@ -10,7 +10,7 @@ import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
-import { DXN, type ObjectId } from '@dxos/keys';
+import { DXN } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import type * as Entity from './Entity';
@@ -80,6 +80,16 @@ export interface RetentionOptions {
   cursor?: string;
 }
 
+/**
+ * Sync options for a feed.
+ */
+export interface SyncOptions {
+  /** Push local changes to the server. Defaults to true. */
+  shouldPush?: boolean;
+  /** Pull remote changes from the server. Defaults to true. */
+  shouldPull?: boolean;
+}
+
 //
 // Factory
 //
@@ -109,27 +119,6 @@ export const getQueueDxn = (feed: Feed): DXN | undefined => {
   return new DXN(DXN.kind.QUEUE, [feed.namespace ?? 'data', self.spaceId, self.echoId]);
 };
 
-/**
- * Creates a Feed object from a queue DXN, inferring the feed's id and namespace from the DXN parts.
- *
- * The resulting Feed, when added to the same space as the queue, will have a queue DXN
- * equal to the input (see `Feed.getQueueDxn`). Useful when migrating `Ref(Queue)` fields to
- * `Ref(Feed.Feed)`.
- *
- * @remarks Unsafe because the caller must ensure the queue DXN's space matches the database
- * the feed is added to; the feed id is set from the queue id, bypassing id generation.
- */
-export const unsafeFromQueueDXN = (queueDxn: DXN): Feed => {
-  const parts = queueDxn.asQueueDXN();
-  if (!parts) {
-    throw new Error(`Expected a queue DXN, got: ${queueDxn.toString()}`);
-  }
-  return Obj.make(Feed, {
-    id: parts.queueId as ObjectId,
-    namespace: parts.subspaceTag === 'trace' ? 'trace' : undefined,
-  });
-};
-
 //
 // Service
 //
@@ -160,6 +149,11 @@ export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
       <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
       <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
     };
+
+    /**
+     * Syncs the feed with the server.
+     */
+    sync(feed: Feed, options?: SyncOptions): Promise<void>;
   }
 >() {}
 
@@ -187,8 +181,30 @@ export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService,
   query: () => {
     throw new Error('Feed.FeedService not available');
   },
+  sync: () => {
+    throw new Error('Feed.FeedService not available');
+  },
 } as Context.Tag.Service<FeedService>);
 
+//
+// Context (per-call) service
+//
+
+/**
+ * Effect service exposing a single `Feed.Feed` as the "current" feed for a call site.
+ *
+ * @deprecated Prefer threading a `Feed.Feed` explicitly through function signatures
+ * over hiding it behind a context service.
+ */
+export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<
+  ContextFeedService,
+  {
+    readonly feed: Feed;
+  }
+>() {
+  static layer = (feed: Feed): Layer.Layer<ContextFeedService> => Layer.succeed(ContextFeedService, { feed });
+}
+
 //
 // Operations
 //
@@ -262,6 +278,21 @@ export const runQuery: {
 } = (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
   query(feed, queryOrFilter as any).pipe(Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())));
 
+/**
+ * Syncs the feed with the server.
+ *
+ * @example
+ * ```ts
+ * yield* Feed.sync(feed);
+ * yield* Feed.sync(feed, { shouldPush: false });
+ * ```
+ */
+export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, FeedService> =>
+  Effect.gen(function* () {
+    const service = yield* FeedService;
+    yield* Effect.promise(() => service.sync(feed, options));
+  });
+
 /**
  * Creates a cursor for iterating over feed items.
  * Currently stubbed — cursor operations are not yet implemented.
@@ -292,13 +323,13 @@ export const nextOption = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<
 
 /**
  * Sets the local retention policy for a feed.
- * Currently stubbed — queues do not yet support retention.
+ * Currently stubbed — feeds do not yet support retention.
  *
  * @example
  * ```ts
  * yield* Feed.setRetention(feed, { count: 1000 });
  * ```
  */
-// TODO(feed): Implement when queue retention is supported.
+// TODO(dmaretskyi): Implement when feed retention is supported.
 export const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, FeedService> =>
   Effect.void;

package/src/Filter.ts

@@ -158,6 +158,37 @@ export const tag = (tag: string): Any => {
   });
 };
 
+/**
+ * Options for {@link key} filter.
+ */
+export type KeyFilterOptions = {
+  /**
+   * Optional semver range expression (e.g. `^1.2.3`, `~2.0.0`, `>=1.0.0 <2.0.0`).
+   * Matches the object's meta `version` field against the range.
+   * If omitted, matches any version (including objects with no version).
+   */
+  version?: string;
+};
+
+/**
+ * Filter by registry key stored in object meta.
+ *
+ * @example
+ * ```ts
+ * Filter.key('org.example.type.foo');
+ * Filter.key('org.example.type.foo', { version: '^1.2.3' });
+ * ```
+ */
+export const key = (key: string, options?: KeyFilterOptions): Any => {
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    props: {},
+    metaKey: key,
+    metaVersion: options?.version,
+  });
+};
+
 /**
  * Filter by properties.
  */

package/src/Hypergraph.ts

@@ -22,10 +22,10 @@ export interface RefResolutionContext {
   space?: Key.SpaceId;
 
   /**
-   * Queue that the resolution is happening from.
-   * This queue will be searched first, and then the space it belongs to.
+   * Feed that the resolution is happening from (as the underlying queue DXN).
+   * This feed will be searched first, and then the space it belongs to.
    */
-  queue?: DXN;
+  feed?: DXN;
 }
 
 export interface RefResolverOptions {

package/src/Migration.ts

@@ -10,19 +10,31 @@ import { type DXN } from '@dxos/keys';
 
 import type * as Database from './Database';
 import type * as Entity from './Entity';
-import { getSchemaDXN } from './internal';
+import { MetaId, type ObjectMeta, getSchemaDXN } from './internal';
+
+/**
+ * Result returned by a migration's `transform` callback.
+ * The data shape matches the target schema; the optional `[Obj.Meta]` symbol key lets the
+ * transform update the object's meta (e.g. `key` / `version`) atomically with the data swap.
+ */
+export type TransformResult<To extends Schema.Schema.AnyNoContext> = Omit<
+  Schema.Schema.Type<To>,
+  'id' | Entity.KindId
+> & {
+  [MetaId]?: Partial<ObjectMeta>;
+};
 
 type DefineObjectMigrationOptions<From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext> = {
   from: From;
   to: To;
   /**
    * Pure function that converts the old object data to the new object data.
+   *
+   * The returned object may include an optional `[Obj.Meta]` entry to update the object's meta
+   * (e.g. registry `key` / `version`) atomically with the data swap.
    */
   // TODO(dmaretskyi): `id` should not be a part of the schema.
-  transform: (
-    from: Schema.Schema.Type<From>,
-    context: ObjectMigrationContext,
-  ) => Promise<Omit<Schema.Schema.Type<To>, 'id' | Entity.KindId>>;
+  transform: (from: Schema.Schema.Type<From>, context: ObjectMigrationContext) => Promise<TransformResult<To>>;
 
   /**
    * Callback that is called after the object is migrated. Called for every object that is migrated.
@@ -30,7 +42,7 @@ type DefineObjectMigrationOptions<From extends Schema.Schema.AnyNoContext, To ex
    * NOTE: Database mutations performed in this callback are not guaranteed to be idempotent.
    *       If multiple peers run the migration separately, the effects may be applied multiple times.
    */
-  onMigration: (params: OnMigrateProps<From, To>) => Promise<void>;
+  onMigration?: (params: OnMigrateProps<From, To>) => Promise<void>;
 };
 
 /**
@@ -55,7 +67,7 @@ export type ObjectMigration = {
   fromSchema: Schema.Schema.AnyNoContext;
   toSchema: Schema.Schema.AnyNoContext;
   transform: (from: unknown, context: ObjectMigrationContext) => Promise<unknown>;
-  onMigration: (params: OnMigrateProps<any, any>) => Promise<void>;
+  onMigration?: (params: OnMigrateProps<any, any>) => Promise<void>;
 };
 
 /**

package/src/Obj.ts

@@ -664,6 +664,7 @@ export const setParent = (entity: Unknown, parent: Any | undefined) => {
   assumeType<internal.InternalObjectProps>(entity);
   assumeType<internal.InternalObjectProps | undefined>(parent);
   entity[internal.ParentId] = parent;
+  return entity;
 };
 
 interface UpdateFromOptions<T> {

package/src/Query.test.ts

@@ -523,7 +523,7 @@ describe('query api', () => {
           "from": {
             "_tag": "scope",
             "scope": {
-              "allQueuesFromSpaces": true,
+              "allFeedsFromSpaces": true,
             },
           },
           "query": {
@@ -563,17 +563,17 @@ describe('query api', () => {
     test('Query.type(...).from(feed) sets queue scope', async () => {
       const spaceId = SpaceId.random();
       const feedId = ObjectId.random();
-      const feedDxn = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
+      const feedDXN = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
       const feed = (await Obj.fromJSON(
         {
           '@type': 'dxn:type:org.dxos.type.feed:0.1.0',
           id: feedId,
           name: 'test-feed',
         },
-        { dxn: feedDxn },
+        { dxn: feedDXN },
       )) as Feed.Feed;
 
-      const expectedQueueDxn = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
+      const expectedQueueDXN = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
 
       const query = Query.type(TestSchema.Person).from(feed);
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -582,7 +582,7 @@ describe('query api', () => {
         from: {
           _tag: 'scope',
           scope: {
-            queues: [expectedQueueDxn.toString()],
+            feeds: [expectedQueueDXN.toString()],
           },
         },
         query: {
@@ -686,13 +686,13 @@ describe('query api', () => {
 
   describe('Filter.childOf', () => {
     test('childOf with Ref', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const filter = Filter.childOf(parentRef);
 
       expect(filter.ast).toMatchObject({
         type: 'child-of',
-        parents: [parentDxn.toString()],
+        parents: [parentDXN.toString()],
         transitive: true,
       });
       Schema.validateSync(QueryAST.Filter)(filter.ast);
@@ -736,15 +736,15 @@ describe('query api', () => {
     });
 
     test('childOf in select query', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const query = Query.select(Filter.childOf(parentRef));
 
       expect(query.ast).toMatchObject({
         type: 'select',
         filter: {
           type: 'child-of',
-          parents: [parentDxn.toString()],
+          parents: [parentDXN.toString()],
           transitive: true,
         },
       });
@@ -752,8 +752,8 @@ describe('query api', () => {
     });
 
     test('childOf combined with type filter', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(parentDxn);
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
       const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.childOf(parentRef)));
 
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -763,7 +763,7 @@ describe('query api', () => {
           type: 'and',
           filters: [
             { type: 'object', typename: 'dxn:type:com.example.type.person:0.1.0' },
-            { type: 'child-of', parents: [parentDxn.toString()], transitive: true },
+            { type: 'child-of', parents: [parentDXN.toString()], transitive: true },
           ],
         },
       });
@@ -779,8 +779,8 @@ describe('query api', () => {
 
     test('childOf with mixed objects and Refs', () => {
       const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
-      const refDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const parentRef = Ref.fromDXN(refDxn);
+      const refDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(refDXN);
       const filter = Filter.childOf([parent, parentRef]);
 
       expect(filter.ast).toMatchObject({

package/src/Query.ts

@@ -359,7 +359,7 @@ class QueryClass implements Any {
         from: {
           _tag: 'scope',
           scope: {
-            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
           },
         },
       });
@@ -384,7 +384,7 @@ class QueryClass implements Any {
           _tag: 'scope',
           scope: {
             spaceIds: databases.map((db) => db.spaceId),
-            ...(options?.includeFeeds ? { allQueuesFromSpaces: true } : {}),
+            ...(options?.includeFeeds ? { allFeedsFromSpaces: true } : {}),
           },
         },
       });
@@ -410,10 +410,15 @@ class QueryClass implements Any {
       }
     }
 
-    const feeds = items as Feed.Feed[];
-    const queueDxns = feeds.flatMap((feed) => {
+    const feedItems = items as Feed.Feed[];
+    const feedDXNs = feedItems.map((feed) => {
       const dxn = Feed.getQueueDxn(feed);
-      return dxn ? [dxn.toString()] : [];
+      if (!dxn) {
+        throw new TypeError(
+          `Query.from() expects persisted Feed objects with a queue DXN; got feed without a space (id=${Obj.getDXN(feed).toString()}).`,
+        );
+      }
+      return dxn.toString();
     });
     return new QueryClass({
       type: 'from',
@@ -421,7 +426,7 @@ class QueryClass implements Any {
       from: {
         _tag: 'scope',
         scope: {
-          queues: queueDxns,
+          feeds: feedDXNs,
         },
       },
     });
@@ -551,7 +556,7 @@ export const from = (
   return wrapper.from(source as any, options);
 };
 
-const SCOPE_KEYS = new Set(['spaceIds', 'queues', 'allQueuesFromSpaces']);
+const SCOPE_KEYS = new Set(['spaceIds', 'feeds', 'allFeedsFromSpaces']);
 
 /** Detect a raw Scope object (plain object with only Scope-valid keys). */
 const _isScope = (value: unknown): value is QueryAST.Scope => {

package/src/Ref.ts

@@ -85,6 +85,8 @@ export const make = refInternal.Ref.make;
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
 export const fromDXN = refInternal.Ref.fromDXN;
 
+export const hasObjectId = refInternal.Ref.hasObjectId;
+
 // TODO(wittjosiah): Factor out?
 export const isRefType = (ast: SchemaAST.AST): boolean => {
   return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(

package/src/internal/Entity/model.ts

@@ -66,6 +66,8 @@ export interface InternalObjectProps {
 export interface ObjectMetaJSON {
   keys: ForeignKey[];
   tags?: string[];
+  key?: string;
+  version?: string;
 }
 
 /**

package/src/internal/Obj/ids.ts

@@ -5,7 +5,7 @@
 import { DXN, ObjectId, QueueSubspaceTags, SpaceId } from '@dxos/keys';
 
 /**
- * @deprecated Use `db.queues.create()`
+ * @deprecated Use `Feed.make(...)` + `db.add(feed)` then `Feed.getQueueDxn(feed)`.
  */
 // TODO(burdon): Move to @dxos/keys.
 export const createQueueDXN = (spaceId = SpaceId.random(), queueId = ObjectId.random()) =>

package/src/internal/Obj/json-serializer.ts

@@ -116,15 +116,15 @@ export const objectFromJSON = async (
   const isRelation =
     typeof jsonData[ATTR_RELATION_SOURCE] === 'string' || typeof jsonData[ATTR_RELATION_TARGET] === 'string';
   if (isRelation) {
-    const sourceDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
-    const targetDxn: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
+    const sourceDXN: DXN = DXN.parse(jsonData[ATTR_RELATION_SOURCE] ?? raise(new TypeError('Missing relation source')));
+    const targetDXN: DXN = DXN.parse(jsonData[ATTR_RELATION_TARGET] ?? raise(new TypeError('Missing relation target')));
 
-    const source = (await refResolver?.resolve(sourceDxn)) as AnyEntity | undefined;
-    const target = (await refResolver?.resolve(targetDxn)) as AnyEntity | undefined;
+    const source = (await refResolver?.resolve(sourceDXN)) as AnyEntity | undefined;
+    const target = (await refResolver?.resolve(targetDXN)) as AnyEntity | undefined;
 
     defineHiddenProperty(obj, KindId, EntityKind.Relation);
-    defineHiddenProperty(obj, RelationSourceDXNId, sourceDxn);
-    defineHiddenProperty(obj, RelationTargetDXNId, targetDxn);
+    defineHiddenProperty(obj, RelationSourceDXNId, sourceDXN);
+    defineHiddenProperty(obj, RelationTargetDXNId, targetDXN);
     defineHiddenProperty(obj, RelationSourceId, source);
     defineHiddenProperty(obj, RelationTargetId, target);
   } else {
@@ -142,8 +142,8 @@ export const objectFromJSON = async (
   }
 
   if (jsonData[ATTR_PARENT]) {
-    const parentDxn = DXN.parse(jsonData[ATTR_PARENT]);
-    const resolvedParent = (await refResolver?.resolve(parentDxn)) as Obj.Unknown | undefined;
+    const parentDXN = DXN.parse(jsonData[ATTR_PARENT]);
+    const resolvedParent = (await refResolver?.resolve(parentDXN)) as Obj.Unknown | undefined;
     defineHiddenProperty(obj, ParentId, resolvedParent);
   } else if (parent) {
     defineHiddenProperty(obj, ParentId, parent);
@@ -184,7 +184,7 @@ const stripInternalJsonKeys = (jsonData: unknown) => {
     [ATTR_TYPE]: _type,
     [ATTR_META]: _meta,
     [ATTR_DELETED]: _deleted,
-    [ATTR_SELF_DXN]: _selfDxn,
+    [ATTR_SELF_DXN]: _selfDXN,
     [ATTR_RELATION_SOURCE]: _relationSource,
     [ATTR_RELATION_TARGET]: _relationTarget,
     ...props

package/src/internal/Query.ts

@@ -10,6 +10,18 @@ import { type QueryAST } from '@dxos/echo-protocol';
 export const prettyFilter = (filter: QueryAST.Filter): string => {
   switch (filter.type) {
     case 'object': {
+      // A type-less object filter with only a meta-key constraint is `Filter.key(...)`.
+      if (
+        filter.typename === null &&
+        (filter.id === undefined || filter.id.length === 0) &&
+        Object.keys(filter.props).length === 0 &&
+        (filter.foreignKeys === undefined || filter.foreignKeys.length === 0) &&
+        filter.metaKey !== undefined
+      ) {
+        return filter.metaVersion !== undefined
+          ? `Filter.key(${JSON.stringify(filter.metaKey)}, { version: ${JSON.stringify(filter.metaVersion)} })`
+          : `Filter.key(${JSON.stringify(filter.metaKey)})`;
+      }
       const parts: string[] = [];
       if (filter.typename !== null) {
         parts.push(String(filter.typename));
@@ -25,6 +37,13 @@ export const prettyFilter = (filter: QueryAST.Filter): string => {
       if (filter.foreignKeys !== undefined && filter.foreignKeys.length > 0) {
         parts.push(`foreignKeys: [${filter.foreignKeys.map((fk) => JSON.stringify(fk)).join(', ')}]`);
       }
+      if (filter.metaKey !== undefined) {
+        parts.push(
+          filter.metaVersion !== undefined
+            ? `metaKey: ${JSON.stringify(filter.metaKey)} (${filter.metaVersion})`
+            : `metaKey: ${JSON.stringify(filter.metaKey)}`,
+        );
+      }
       return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
     }
     case 'compare':
@@ -121,11 +140,11 @@ export const prettyQuery = (query: QueryAST.Query): string => {
         if (scope.spaceIds !== undefined) {
           parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
         }
-        if (scope.queues !== undefined) {
-          parts.push(`queues: [${scope.queues.map(String).join(', ')}]`);
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
         }
-        if (scope.allQueuesFromSpaces !== undefined) {
-          parts.push(`allQueuesFromSpaces: ${scope.allQueuesFromSpaces}`);
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
         }
         return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
       }

package/src/internal/common/proxy/reactive.test.ts

@@ -28,7 +28,7 @@ describe('Obj.subscribe', () => {
     expect(calls).toBe(seen);
   });
 
-  // Regression: queue-stored typed objects (e.g. ContextBinding) and other Obj-shaped values
+  // Regression: queue-stored typed objects (e.g. AiContext.Binding) and other Obj-shaped values
   // satisfy `Obj.isObject` (KindId is set) but are not wrapped in a reactive Proxy. Earlier
   // versions invariant'd inside `getProxyTarget` when an atom body did `Obj.subscribe(obj)` on
   // such an input. The contract is "no-op for non-reactive inputs"; verify the function

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

@@ -38,6 +38,18 @@ export const ObjectMetaSchema = Schema.Struct({
   // Defaulting to an empty array is possible but requires a bit more work.
   // TODO(dmaretskyi): In automerge this should be a map of { [tag]: boolean } for uniqueness and conflict resolution.
   tags: Schema.optional(Schema.Array(Schema.String)),
+
+  /**
+   * Fully-qualified registry key for the object (FQN format, e.g. `org.example.type.foo`).
+   * Identifies the canonical registry entry the object instance was created from.
+   */
+  key: Schema.optional(Schema.String),
+
+  /**
+   * Semantic version of the registry entry the object was created from.
+   * Must be a valid semver string (e.g. `1.2.3`).
+   */
+  version: Schema.optional(Schema.String),
 });
 
 export type ObjectMeta = Schema.Schema.Type<typeof ObjectMetaSchema>;

package/dist/lib/neutral/chunk-FHYIM4RD.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/Database.ts"],
-  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Context from 'effect/Context';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\nimport * as Option from 'effect/Option';\nimport * as Schema from 'effect/Schema';\nimport type * as Types from 'effect/Types';\n\nimport { promiseWithCauseCapture } from '@dxos/effect';\nimport { invariant } from '@dxos/invariant';\nimport { DXN, type SpaceId } from '@dxos/keys';\n\nimport type * as Entity from './Entity';\nimport * as Err from './Err';\nimport type * as Filter from './Filter';\nimport type * as Hypergraph from './Hypergraph';\nimport { isInstanceOf } from './internal/Annotation';\nimport { type AnyProperties } from './internal/common/types';\nimport type { Ref } from './internal/Ref/ref';\nimport type * as Obj from './Obj';\nimport type * as Query from './Query';\nimport type * as QueryResult from './QueryResult';\nimport type * as SchemaRegistry from './SchemaRegistry';\nimport type * as Type from './Type';\n\n/**\n * `query` API function declaration.\n */\n// TODO(burdon): Reconcile Query and Filter (should only have one root type).\nexport interface QueryFn {\n  <Q extends Query.Any>(query: Q): QueryResult.QueryResult<Query.Type<Q>>;\n  <F extends Filter.Any>(filter: F): QueryResult.QueryResult<Filter.Type<F>>;\n}\n\n/**\n * Common interface for Database and Queue.\n */\nexport interface Queryable {\n  query: QueryFn;\n}\n\nexport type GetObjectByIdOptions = {\n  deleted?: boolean;\n};\n\nexport type ObjectPlacement = 'root-doc' | 'linked-doc';\n\nexport type AddOptions = {\n  /**\n   * Where to place the object in the Automerge document tree.\n   * Root document is always loaded with the space.\n   * Linked documents are loaded lazily.\n   * Placing large number of objects in the root document may slow down the initial load.\n   *\n   * @default 'linked-doc'\n   */\n  placeIn?: ObjectPlacement;\n};\n\nexport type FlushOptions = {\n  /**\n   * Write any pending changes to disk.\n   * @default true\n   */\n  disk?: boolean;\n\n  /**\n   * Wait for pending index updates.\n   * @default true\n   */\n  indexes?: boolean;\n\n  /**\n   * Flush pending updates to objects and queries.\n   * @default false\n   */\n  updates?: boolean;\n};\n\n/**\n * Identifier denoting an ECHO Database.\n */\nexport const TypeId = Symbol.for('@dxos/echo/Database');\nexport type TypeId = typeof TypeId;\n\n/**\n * ECHO Database interface.\n */\nexport interface Database extends Queryable {\n  readonly [TypeId]: TypeId;\n\n  get spaceId(): SpaceId;\n\n  // TODO(burdon): Can we move this into graph?\n  get schemaRegistry(): SchemaRegistry.SchemaRegistry;\n\n  get graph(): Hypergraph.Hypergraph;\n\n  toJSON(): object;\n\n  /**\n   * Return object by local ID.\n   */\n  getObjectById<T extends Obj.Unknown = Obj.OfShape<AnyProperties>>(\n    id: string,\n    opts?: GetObjectByIdOptions,\n  ): T | undefined;\n\n  /**\n   * Query objects.\n   */\n  query: QueryFn;\n\n  /**\n   * Creates a reference to an existing object in the database.\n   *\n   * NOTE: The reference may be dangling if the object is not present in the database.\n   * NOTE: Difference from `Ref.fromDXN`\n   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.\n   * `db.makeRef(dxn)` is preferable in cases with access to the database.\n   */\n  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref<T>;\n\n  /**\n   * Adds object to the database.\n   */\n  add<T extends Entity.Unknown = Entity.Unknown>(obj: T, opts?: AddOptions): T;\n\n  /**\n   * Removes object from the database.\n   */\n  // TODO(burdon): Return true if removed (currently throws if not present).\n  remove(obj: Entity.Unknown): void;\n\n  /**\n   * Wait for all pending changes to be saved to disk.\n   * Optionaly waits for changes to be propagated to indexes and event handlers.\n   */\n  flush(opts?: FlushOptions): Promise<void>;\n}\n\nexport const isDatabase = (obj: unknown): obj is Database => {\n  return obj ? typeof obj === 'object' && TypeId in obj && obj[TypeId] === TypeId : false;\n};\n\nexport const Database: Schema.Schema<Database> = Schema.Any.pipe(Schema.filter((space) => isDatabase(space)));\n\n/**\n * Effect service tag for Database dependency injection.\n */\nexport class Service extends Context.Tag('@dxos/echo/Database/Service')<\n  Service,\n  {\n    readonly db: Database;\n  }\n>() {}\n\n/**\n * Layer that provides a Database service that throws when accessed.\n * Useful as a default layer when no database is available.\n */\nexport const notAvailable = Layer.succeed(Service, {\n  get db(): Database {\n    throw new Error('Database not available');\n  },\n});\n\n/**\n * Creates a Database service instance from a Database.\n */\nexport const makeService = (db: Database): Context.Tag.Service<Service> => {\n  return {\n    get db() {\n      return db;\n    },\n  };\n};\n\n/**\n * Creates a Layer that provides the Database service.\n */\nexport const layer = (db: Database): Layer.Layer<Service> => {\n  return Layer.succeed(Service, makeService(db));\n};\n\n/**\n * Returns the space ID of the database.\n */\nexport const spaceId = Effect.gen(function* () {\n  const { db } = yield* Service;\n  return db.spaceId;\n});\n\n/**\n * Resolves an object by its DXN.\n */\nexport const resolve: {\n  // No type check.\n  (ref: DXN | Ref<any>): Effect.Effect<Entity.Unknown, never, Service>;\n  // Check matches schema.\n  <S extends Type.AnyEntity>(\n    ref: DXN | Ref<any>,\n    schema: S,\n  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service>;\n} = (<S extends Type.AnyEntity>(\n  ref: DXN | Ref<any>,\n  schema?: S,\n): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Service> =>\n  Effect.gen(function* () {\n    const { db } = yield* Service;\n    const dxn = ref instanceof DXN ? ref : ref.dxn;\n    const object = yield* promiseWithCauseCapture(() =>\n      db.graph\n        .createRefResolver({\n          context: {\n            space: db.spaceId,\n          },\n        })\n        .resolve(dxn),\n    );\n\n    if (!object) {\n      return yield* Effect.fail(new Err.ObjectNotFoundError(dxn));\n    }\n    invariant(!schema || isInstanceOf(schema, object), 'Object type mismatch.');\n    return object as any;\n  }).pipe(Effect.withSpan('Database.resolve'))) as any;\n\n/**\n * Loads an object reference.\n */\nexport const load: <T>(ref: Ref<T>) => Effect.Effect<T, Err.ObjectNotFoundError, never> = Effect.fn('Database.load')(\n  function* (ref) {\n    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());\n    if (!object) {\n      return yield* Effect.fail(new Err.ObjectNotFoundError(ref.dxn));\n    }\n    return object;\n  },\n);\n\n/**\n * Loads an object reference option.\n */\n// TODO(dmaretskyi): Do we need this -- you can just use `Effect.catchTag` in calling code instead.\nexport const loadOption: <T>(ref: Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(\n  'Database.loadOption',\n)(function* (ref) {\n  const object = yield* load(ref).pipe(Effect.catchTag('ObjectNotFoundError', () => Effect.succeed(undefined)));\n\n  return Option.fromNullable(object);\n});\n\n/**\n * Adds an object to the database.\n * @see {@link Database.add}\n */\nexport const add = <T extends Entity.Unknown>(obj: T): Effect.Effect<T, never, Service> =>\n  Service.pipe(Effect.map(({ db }) => db.add(obj))).pipe(Effect.withSpan('Database.add'));\n\n/**\n * Removes an object from the database.\n * @see {@link Database.remove}\n */\nexport const remove = <T extends Entity.Unknown>(obj: T): Effect.Effect<void, never, Service> =>\n  Service.pipe(Effect.map(({ db }) => db.remove(obj))).pipe(Effect.withSpan('Database.remove'));\n\n/**\n * Flushes pending changes to disk.\n * @see {@link Database.flush}\n */\nexport const flush = (opts?: FlushOptions) =>\n  Service.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts)))).pipe(\n    Effect.withSpan('Database.flush'),\n  );\n\n/**\n * Creates a `QueryResult` object that can be subscribed to.\n */\nexport const query: {\n  <Q extends Query.Any>(query: Q): Effect.Effect<QueryResult.QueryResult<Query.Type<Q>>, never, Service>;\n  <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult.QueryResult<Filter.Type<F>>, never, Service>;\n} = (queryOrFilter: Query.Any | Filter.Any) =>\n  Service.pipe(\n    Effect.map(({ db }) => db.query(queryOrFilter as any) as QueryResult.QueryResult<any>),\n    Effect.withSpan('Database.query'),\n  );\n\n/**\n * Executes the query once and returns the results.\n */\nexport const runQuery: {\n  <Q extends Query.Any>(query: Q): Effect.Effect<Query.Type<Q>[], never, Service>;\n  <F extends Filter.Any>(filter: F): Effect.Effect<Filter.Type<F>[], never, Service>;\n} = (queryOrFilter: Query.Any | Filter.Any) =>\n  query(queryOrFilter as any).pipe(\n    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),\n    Effect.withSpan('Database.runQuery'),\n  );\n\n/**\n * Executes the query once and returns the first result as or None.\n */\nexport const runQueryFirst: {\n  <Q extends Query.Any>(query: Q): Effect.Effect<Option.Option<Query.Type<Q>>, never, Service>;\n  <F extends Filter.Any>(filter: F): Effect.Effect<Option.Option<Filter.Type<F>>, never, Service>;\n} = (queryOrFilter: Query.Any | Filter.Any) =>\n  query(queryOrFilter as any).pipe(\n    Effect.flatMap((queryResult) =>\n      promiseWithCauseCapture(async () => Option.fromNullable(await queryResult.firstOrUndefined())),\n    ),\n    Effect.withSpan('Database.runQueryFirst'),\n  );\n\n/**\n * Persists schemas in the database so they replicate to other clients.\n * @see {@link SchemaRegistry.SchemaRegistry.register}\n */\nexport const registerSchema = (\n  input: SchemaRegistry.RegisterSchemaInput[],\n): Effect.Effect<Type.RuntimeType[], never, Service> =>\n  Service.pipe(\n    Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.schemaRegistry.register(input))),\n    Effect.withSpan('Database.registerSchema'),\n  );\n\n/**\n * Creates a schema query result that can be subscribed to.\n */\n// TODO(dmaretskyi): Change API to `yield* Database.querySchema(...).first` and `yield* Database.querySchema(...).schema`.\nexport const schemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(\n  schemaQueryOptions?: Q & SchemaRegistry.Query,\n): Effect.Effect<QueryResult.QueryResult<SchemaRegistry.ExtractQueryResult<Q>>, never, Service> =>\n  Service.pipe(\n    Effect.map(({ db }) => db.schemaRegistry.query(schemaQueryOptions)),\n    Effect.withSpan('Database.schemaQuery'),\n  );\n\n/**\n * Executes a schema query once and returns the results.\n */\nexport const runSchemaQuery = <Q extends Types.NoExcessProperties<SchemaRegistry.Query, Q>>(\n  schemaQueryOptions?: Q & SchemaRegistry.Query,\n): Effect.Effect<SchemaRegistry.ExtractQueryResult<Q>[], never, Service> =>\n  schemaQuery(schemaQueryOptions).pipe(\n    Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),\n  );\n"],
-  "mappings": ";;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;AAMA,YAAYA,aAAa;AACzB,YAAYC,YAAY;AACxB,YAAYC,WAAW;AACvB,YAAYC,YAAY;AACxB,YAAYC,YAAY;AAGxB,SAASC,+BAA+B;AACxC,SAASC,iBAAiB;AAC1B,SAASC,WAAyB;AAqElC,IAAA,eAAA;AA+DSC,IAAM,SAAOA,uBAAQ,IAAA,qBAAsBA;AAClD,IAAA,aAAA,CAAA,QAAA;AAEF,SAAO,MAAMC,OAAoCC,QAAOC,YAASD,UAAc,OAACE,IAAUC,MAAAA,MAAWD,SAAS;AAE9G;;AAUA,IAAA,UAAA,cAAA,YAAA,6BAAA,EAAA,EAAA;;AAMI,IAAM,eAAU,cAAA,SAAA;EAClB,IAAA,KAAA;AACC,UAAA,IAAA,MAAA,wBAAA;EAEH;;AAKI,IAAIE,cAAK,CAAA,OAAA;;IAET,IAAA,KAAA;AACF,aAAA;IACA;EAEF;;AAKE,IAAA,QAAA,CAAA,OAAA;AAEF,SAAA,cAAA,SAAA,YAAA,EAAA,CAAA;;AAKSA,IAAGC,UAAO,WAAA,aAAA;AAChB,QAAA,EAAA,GAAA,IAAA,OAAA;AAEH,SAAA,GAAA;;AAiBI,IAAMC,UAAMC,CAAAA,KAAAA,WAA2BA,WAAID,aAAG;AAC9C,QAAME,EAAAA,GAAAA,IAAS,OAAOC;cAGhBC,eAAS,MAAA,MAAA,IAAA;iBACPR,OAAUG,wBAAO,MAAA,GAAA,MAAA,kBAAA;IACnB,SAAA;MAEDM,OAAQL,GAAAA;IAGRE;EACH,CAAA,EAAA,QAAO,GAAOI,CAAAA;AAChB,MAAA,CAAA,QAAA;AACAC,WAAWC,OAAUC,YAAAA,IAAaD,oBAAiB,GAAA,CAAA;EACnD;AACCE,YAAKJ,CAAOK,UAAS,aAAA,QAA6B,MAAA,GAAA,yBAAA,EAAA,YAAA,YAAA,GAAA,cAAA,GAAA,IAAA,GAAA,MAAA,GAAA,CAAA,2CAAA,yBAAA,EAAA,CAAA;AAEvD,SAAA;;AAMST,IAAQ,OAAA,UAAA,eAAA,EAAA,WAAA,KAAA;QACX,SAAO,OAAOI,wBAAoBM,MAAAA,IAAAA,QAAwBZ,CAAAA;AAC5D,MAAA,CAAA,QAAA;AACA,WAAOE,OAAAA,YAAAA,IAAAA,oBAAAA,IAAAA,GAAAA,CAAAA;EAET;AAEF,SAAA;;AASE,IAAOW,aAAoBX,UAAAA,qBAAAA,EAAAA,WAAAA,KAAAA;AAC1B,QAAA,SAAA,OAAA,KAAA,GAAA,EAAA,KAAA,gBAAA,uBAAA,MAAA,eAAA,MAAA,CAAA,CAAA;AAEH,SAAA,oBAAA,MAAA;;;;;;;;;;;",
-  "names": ["Context", "Effect", "Layer", "Option", "Schema", "promiseWithCauseCapture", "invariant", "DXN", "obj", "Database", "Schema", "Any", "space", "isDatabase", "db", "spaceId", "dxn", "ref", "object", "promiseWithCauseCapture", "context", "resolve", "Effect", "invariant", "schema", "isInstanceOf", "pipe", "withSpan", "ObjectNotFoundError", "Option"]
-}