@dxos/echo-protocol 0.8.4-staging.ac66bdf99f → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-protocol",
-  "version": "0.8.4-staging.ac66bdf99f",
+  "version": "0.9.0",
   "description": "Core ECHO APIs.",
   "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": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -20,20 +20,17 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "effect": "3.20.0",
-    "@dxos/crypto": "0.8.4-staging.ac66bdf99f",
-    "@dxos/invariant": "0.8.4-staging.ac66bdf99f",
-    "@dxos/keys": "0.8.4-staging.ac66bdf99f",
-    "@dxos/protocols": "0.8.4-staging.ac66bdf99f",
-    "@dxos/util": "0.8.4-staging.ac66bdf99f"
+    "effect": "3.21.3",
+    "@dxos/crypto": "0.9.0",
+    "@dxos/protocols": "0.9.0",
+    "@dxos/util": "0.9.0",
+    "@dxos/keys": "0.9.0",
+    "@dxos/invariant": "0.9.0"
   },
   "publishConfig": {
     "access": "public"

package/src/document-structure.ts

@@ -3,7 +3,7 @@
 //
 
 import { invariant } from '@dxos/invariant';
-import type { DXN, ObjectId } from '@dxos/keys';
+import type { EntityId, URI } from '@dxos/keys';
 import { visitValues } from '@dxos/util';
 
 import { type RawString } from './automerge';
@@ -19,8 +19,8 @@ export type SpaceState = {
 /**
  * Array indexes get converted to strings.
  */
-export type ObjectProp = string;
-export type ObjectPropPath = ObjectProp[];
+export type EntityProp = string;
+export type EntityPropPath = EntityProp[];
 
 /**
  * Link to all documents that hold objects in the space.
@@ -35,13 +35,13 @@ export interface DatabaseDirectory {
    * Objects inlined in the current document.
    */
   objects?: {
-    [id: string]: ObjectStructure;
+    [id: string]: EntityStructure;
   };
   /**
    * Object id points to an automerge doc url where the object is embedded.
    */
   links?: {
-    [echoId: string]: string | RawString;
+    [echoUri: string]: string | RawString;
   };
 
   /**
@@ -67,11 +67,11 @@ export const DatabaseDirectory = Object.freeze({
     return rawKey;
   },
 
-  getInlineObject: (doc: DatabaseDirectory, id: ObjectId): ObjectStructure | undefined => {
+  getInlineObject: (doc: DatabaseDirectory, id: EntityId): EntityStructure | undefined => {
     return doc.objects?.[id];
   },
 
-  getLink: (doc: DatabaseDirectory, id: ObjectId): string | undefined => {
+  getLink: (doc: DatabaseDirectory, id: EntityId): string | undefined => {
     return doc.links?.[id]?.toString();
   },
 
@@ -81,7 +81,7 @@ export const DatabaseDirectory = Object.freeze({
     links,
   }: {
     spaceKey: string;
-    objects?: Record<string, ObjectStructure>;
+    objects?: Record<string, EntityStructure>;
     links?: Record<string, RawString>;
   }): DatabaseDirectory => ({
     access: {
@@ -95,11 +95,11 @@ export const DatabaseDirectory = Object.freeze({
 /**
  * Representation of an ECHO object in an AM document.
  */
-export type ObjectStructure = {
+export type EntityStructure = {
   // TODO(dmaretskyi): Missing in some cases.
-  system?: ObjectSystem;
+  system?: EntitySystem;
 
-  meta: ObjectMeta;
+  meta: EntityMeta;
   /**
    * User-defined data.
    * Adheres to schema in `system.type`
@@ -107,46 +107,46 @@ export type ObjectStructure = {
   data: Record<string, any>;
 };
 
-// Helper methods to interact with the {@link ObjectStructure}.
-export const ObjectStructure = Object.freeze({
+// Helper methods to interact with the {@link EntityStructure}.
+export const EntityStructure = Object.freeze({
   /**
    * @throws On invalid object structure.
    */
-  getTypeReference: (object: ObjectStructure): EncodedReference | undefined => {
+  getTypeReference: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.type;
   },
 
   /**
    * @throws On invalid object structure.
    */
-  getEntityKind: (object: ObjectStructure): 'object' | 'relation' => {
+  getEntityKind: (object: EntityStructure): 'object' | 'relation' | 'type' => {
     const kind = object.system?.kind ?? 'object';
-    invariant(kind === 'object' || kind === 'relation', 'Invalid kind');
+    invariant(kind === 'object' || kind === 'relation' || kind === 'type', 'Invalid kind');
     return kind;
   },
 
-  isDeleted: (object: ObjectStructure): boolean => {
+  isDeleted: (object: EntityStructure): boolean => {
     return object.system?.deleted ?? false;
   },
 
-  getRelationSource: (object: ObjectStructure): EncodedReference | undefined => {
+  getRelationSource: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.source;
   },
 
-  getRelationTarget: (object: ObjectStructure): EncodedReference | undefined => {
+  getRelationTarget: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.target;
   },
 
-  getParent: (object: ObjectStructure): EncodedReference | undefined => {
+  getParent: (object: EntityStructure): EncodedReference | undefined => {
     return object.system?.parent;
   },
 
   /**
    * @returns All references in the data section of the object.
    */
-  getAllOutgoingReferences: (object: ObjectStructure): { path: ObjectPropPath; reference: EncodedReference }[] => {
-    const references: { path: ObjectPropPath; reference: EncodedReference }[] = [];
-    const visit = (path: ObjectPropPath, value: unknown) => {
+  getAllOutgoingReferences: (object: EntityStructure): { path: EntityPropPath; reference: EncodedReference }[] => {
+    const references: { path: EntityPropPath; reference: EncodedReference }[] = [];
+    const visit = (path: EntityPropPath, value: unknown) => {
       if (isEncodedReference(value)) {
         references.push({ path, reference: value });
       } else {
@@ -157,7 +157,7 @@ export const ObjectStructure = Object.freeze({
     return references;
   },
 
-  getTags: (object: ObjectStructure): string[] => {
+  getTags: (object: EntityStructure): (EncodedReference | string)[] => {
     return object.meta.tags ?? [];
   },
 
@@ -166,11 +166,11 @@ export const ObjectStructure = Object.freeze({
     data,
     keys,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
-  }): ObjectStructure => {
+  }): EntityStructure => {
     return {
       system: {
         kind: 'object',
@@ -191,13 +191,13 @@ export const ObjectStructure = Object.freeze({
     keys,
     data,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     source: EncodedReference;
     target: EncodedReference;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
-  }): ObjectStructure => {
+  }): EntityStructure => {
     return {
       system: {
         kind: 'relation',
@@ -212,12 +212,25 @@ export const ObjectStructure = Object.freeze({
       data: data ?? {},
     };
   },
+
+  makeType: ({ type, keys, data }: { type: URI.URI; keys?: ForeignKey[]; data?: unknown }): EntityStructure => {
+    return {
+      system: {
+        kind: 'type',
+        type: { '/': type },
+      },
+      meta: {
+        keys: keys ?? [],
+      },
+      data: data ?? {},
+    };
+  },
 });
 
 /**
  * Echo object metadata.
  */
-export type ObjectMeta = {
+export type EntityMeta = {
   /**
    * Foreign keys.
    */
@@ -225,25 +238,56 @@ export type ObjectMeta = {
 
   /**
    * Tags.
-   * An array of DXNs of Tag objects within the space.
+   * Encoded references to Tag objects within the space.
    *
-   * NOTE: Optional for backwards compatibilty.
+   * NOTE: Optional for backwards compatibility; legacy data may store bare DXN strings, which are
+   * upgraded to encoded references on read (see `object-core.ts`).
    */
-  tags?: string[];
+  tags?: (EncodedReference | 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?: string;
+
+  /**
+   * Semantic version of the registry entry the object was created from.
+   * Must be a valid semver string (e.g. `1.2.3`).
+   */
+  version?: string;
+
+  /**
+   * Dictionary of annotations to this entity.
+   *
+   * NOTE: Optional for backwards compatibility. Values are arbitrary decoded automerge primitives;
+   * typed as `any` so `EntityStructure` stays assignable to `DecodedAutomergePrimaryValue`.
+   */
+  annotations?: { readonly [key: string]: any };
 };
 
 /**
  * Automerge object system properties.
  * (Is automerge specific.)
  */
-export type ObjectSystem = {
+export type EntitySystem = {
   /**
-   * Entity kind.
+   * Entity kind. `'type'` covers persisted ECHO type definitions (instances of
+   * the `Type.Type` meta-schema); `'object'` / `'relation'` cover regular ECHO
+   * instances.
    */
-  kind?: 'object' | 'relation';
+  kind?: 'object' | 'relation' | 'type';
 
   /**
-   * Object reference ('protobuf' protocol) type.
+   * Object reference ('protobuf' protocol) type — DXN of the schema this
+   * entity instantiates.
+   *
+   * - For `kind === 'object'` / `'relation'` instances, this is the URI of the
+   *   user-defined schema the entity was created from (e.g. `dxn:org.example.Person:1.0.0`).
+   * - For `kind === 'type'` entities (persisted Type.Type meta-instances) this
+   *   is always the URI of the `TypeSchema` meta-schema itself
+   *   (`dxn:org.dxos.type.schema:0.1.0`). The kind that the meta-instance
+   *   _describes_ (object/relation/type) lives in `data.jsonSchema.entityKind`.
    */
   type?: EncodedReference;
 
@@ -267,6 +311,13 @@ export type ObjectSystem = {
    * Only for relations.
    */
   target?: EncodedReference;
+
+  /**
+   * Unix ms timestamp recorded at object creation time.
+   * Set once when the ObjectStructure is first written; never modified after that.
+   * Survives compaction / migrations (unlike automerge change timestamps).
+   */
+  createdAt?: number;
 };
 
 /**
@@ -276,6 +327,6 @@ export const PROPERTY_ID = 'id';
 
 /**
  * Data namespace.
- * The key on {@link ObjectStructure} that contains the user-defined data.
+ * The key on {@link EntityStructure} that contains the user-defined data.
  */
 export const DATA_NAMESPACE = 'data';

package/src/edge-peer.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type SpaceId } from '@dxos/keys';
+import { EdgeService } from '@dxos/protocols';
+import { compositeKey } from '@dxos/util';
+
+/**
+ * Returns true if the given peerId belongs to an EDGE replicator (Automerge or Subduction).
+ *
+ * When `spaceId` is provided, the match is scoped to that space (peerId must start with
+ * `<service>:<spaceId>`). When omitted, only the leading service segment is checked
+ * (peerId must start with `<service>:`), which is useful when the caller doesn't have a
+ * spaceId on hand or wants to match any edge replicator regardless of space.
+ */
+export const isEdgePeerId = (peerId: string, spaceId?: SpaceId): boolean => {
+  const automergePrefix =
+    spaceId !== undefined
+      ? compositeKey(EdgeService.AUTOMERGE_REPLICATOR, spaceId)
+      : `${EdgeService.AUTOMERGE_REPLICATOR}:`;
+  const subductionPrefix =
+    spaceId !== undefined
+      ? compositeKey(EdgeService.SUBDUCTION_REPLICATOR, spaceId)
+      : `${EdgeService.SUBDUCTION_REPLICATOR}:`;
+  return peerId.startsWith(automergePrefix) || peerId.startsWith(subductionPrefix);
+};

package/src/index.ts

@@ -4,6 +4,7 @@
 
 export type * from './collection-sync';
 export * from './document-structure';
+export * from './edge-peer';
 export * from './echo-feed-codec';
 export * from './foreign-key';
 export * from './query';

package/src/query/ast.ts

@@ -5,13 +5,14 @@
 import * as Match from 'effect/Match';
 import * as Schema from 'effect/Schema';
 
-import { DXN, ObjectId } from '@dxos/keys';
+import { EID, EntityId, URI } from '@dxos/keys';
 
 import { ForeignKey } from '../foreign-key';
 
-const TypenameSpecifier = Schema.Union(DXN.Schema, Schema.Null).annotations({
-  description: 'DXN or null; null matches any type',
-});
+// Type identifier URI — either a DXN (typename) or an EID (stored-schema-as-object).
+// Matches the URI written into an object's `system.type` (see `getSchemaURI`). Null
+// matches any type.
+const TypenameSpecifier = Schema.Union(URI.Schema, Schema.Null);
 
 // NOTE: This pattern with 3 definitions per schema is need to make the types opaque, and circular references in AST to not cause compiler errors.
 
@@ -26,7 +27,7 @@ const FilterObject_ = Schema.Struct({
 
   typename: TypenameSpecifier,
 
-  id: Schema.optional(Schema.Array(ObjectId)),
+  id: Schema.optional(Schema.Array(EntityId)),
 
   /**
    * Filter by property.
@@ -42,6 +43,17 @@ const FilterObject_ = Schema.Struct({
    */
   foreignKeys: Schema.optional(Schema.Array(ForeignKey)),
 
+  /**
+   * Match objects whose meta `key` equals this fully-qualified registry key (FQN format).
+   */
+  metaKey: Schema.optional(Schema.String),
+
+  /**
+   * Semver range matched against the object's meta `version`.
+   * Only consulted when {@link metaKey} is set. Objects with no `version` do not satisfy a version-constrained filter.
+   */
+  metaVersion: Schema.optional(Schema.String),
+
   // NOTE: Make sure to update `FilterStep.isNoop` if you change this.
 });
 export interface FilterObject extends Schema.Schema.Type<typeof FilterObject_> {}
@@ -173,7 +185,7 @@ export const FilterOr: Schema.Schema<FilterOr> = FilterOr_;
 const FilterChildOf_ = Schema.Struct({
   type: Schema.Literal('child-of'),
   /** Parent DXNs to match children of. */
-  parents: Schema.Array(DXN.Schema),
+  parents: Schema.Array(EID.Schema),
   /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
   transitive: Schema.Boolean,
 });
@@ -344,6 +356,12 @@ const Order_ = Schema.Union(
     kind: Schema.Literal('rank'),
     direction: OrderDirection,
   }),
+  Schema.Struct({
+    // Order by system timestamp (createdAt / updatedAt) from the object meta index.
+    kind: Schema.Literal('timestamp'),
+    field: Schema.Literal('createdAt', 'updatedAt'),
+    direction: OrderDirection,
+  }),
 );
 
 export type Order = Schema.Schema.Type<typeof Order_>;
@@ -391,7 +409,7 @@ export const QueryFromClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   from: Schema.Union(
     Schema.TaggedStruct('scope', {
-      scope: Schema.suspend(() => Scope),
+      scopes: Schema.Array(Schema.suspend(() => Scope)),
     }),
     Schema.TaggedStruct('query', {
       query: Schema.suspend(() => Query),
@@ -425,34 +443,55 @@ export const QueryOptions = Schema.Struct({
    * Nested select statements will use this option to filter deleted objects.
    */
   deleted: Schema.optional(Schema.Literal('include', 'exclude', 'only')),
+
+  /**
+   * Diagnostics-only label for logs / tooling (not used by execution semantics).
+   */
+  debugLabel: Schema.optional(Schema.String),
 });
 
 export interface QueryOptions extends Schema.Schema.Type<typeof QueryOptions> {}
 
 /**
- * Specifies the scope of the data to query from.
+ * Selects from a space (automerge documents).
+ * When `spaceId` is omitted, targets the owning space — i.e. the space of whichever
+ * database executes the query. This lets callers reference "this space" without
+ * having to look up its id.
+ * When `includeAllFeeds` is true, also selects from all feeds belonging to that space.
  */
-export const Scope = Schema.Struct({
-  /**
-   * The nested select statemets will select from the given spaces.
-   *
-   * NOTE: Spaces and queues are unioned together if both are specified.
-   */
-  spaceIds: Schema.optional(Schema.Array(Schema.String)),
+export const SpaceScope = Schema.TaggedStruct('space', {
+  spaceId: Schema.optional(Schema.String),
+  includeAllFeeds: Schema.optional(Schema.Boolean),
+});
+export interface SpaceScope extends Schema.Schema.Type<typeof SpaceScope> {}
 
-  /**
-   * If true, the nested select statements will select from all queues in the spaces specified by `spaceIds`.
-   */
-  allQueuesFromSpaces: Schema.optional(Schema.Boolean),
+/**
+ * Selects from a specific feed (by its underlying queue DXN).
+ */
+export const FeedScope = Schema.TaggedStruct('feed', {
+  feedUri: Schema.String,
+});
+export interface FeedScope extends Schema.Schema.Type<typeof FeedScope> {}
 
-  /**
-   * The nested select statemets will select from the given queues.
-   *
-   * NOTE: Spaces and queues are unioned together if both are specified.
-   */
-  queues: Schema.optional(Schema.Array(DXN.Schema)),
+/**
+ * Selects from a code-shipped object registry.
+ *
+ * - `'local'`  — the in-process registry attached to the hypergraph.
+ * - `'remote'` — a future remote registry service (not yet implemented).
+ *
+ * To include both, add two separate `RegistryScope` entries to the `scopes` array.
+ */
+export const RegistryScope = Schema.TaggedStruct('registry', {
+  location: Schema.Literal('local', 'remote'),
 });
-export interface Scope extends Schema.Schema.Type<typeof Scope> {}
+export interface RegistryScope extends Schema.Schema.Type<typeof RegistryScope> {}
+
+/**
+ * Specifies the scope of the data to query from.
+ * A `from` clause may carry multiple scopes; results are unioned across them.
+ */
+export const Scope = Schema.Union(SpaceScope, FeedScope, RegistryScope);
+export type Scope = Schema.Schema.Type<typeof Scope>;
 
 export const visit = (query: Query, visitor: (node: Query) => void) => {
   visitor(query);