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

package/package.json

@@ -1,37 +1,36 @@
 {
   "name": "@dxos/echo-protocol",
-  "version": "0.8.4-main.fd6878d",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "Core ECHO APIs.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "repository": "github:dxos/dxos",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "effect": "3.17.7",
-    "@dxos/crypto": "0.8.4-main.fd6878d",
-    "@dxos/keys": "0.8.4-main.fd6878d",
-    "@dxos/protocols": "0.8.4-main.fd6878d",
-    "@dxos/util": "0.8.4-main.fd6878d",
-    "@dxos/invariant": "0.8.4-main.fd6878d"
+    "effect": "3.21.3",
+    "@dxos/crypto": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
+    "@dxos/keys": "0.8.4-staging.60fe92afc8",
+    "@dxos/protocols": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8"
   },
   "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,42 +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: 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 {
@@ -153,16 +157,20 @@ export const ObjectStructure = Object.freeze({
     return references;
   },
 
+  getTags: (object: EntityStructure): (EncodedReference | string)[] => {
+    return object.meta.tags ?? [];
+  },
+
   makeObject: ({
     type,
     data,
     keys,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
-  }): ObjectStructure => {
+  }): EntityStructure => {
     return {
       system: {
         kind: 'object',
@@ -183,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',
@@ -204,30 +212,82 @@ 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.
    */
   keys: ForeignKey[];
+
+  /**
+   * Tags.
+   * Encoded references to Tag objects within the space.
+   *
+   * 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?: (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;
 
@@ -236,15 +296,28 @@ export type ObjectSystem = {
    */
   deleted?: boolean;
 
+  /**
+   * Object parent.
+   * Objects with no parent are at the top level of the object hierarchy in the space.
+   */
+  parent?: EncodedReference;
+
   /**
    * Only for relations.
    */
   source?: EncodedReference;
 
   /**
-   * Only for relations.w
+   * 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;
 };
 
 /**
@@ -254,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/echo-feed-codec.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { FeedProtocol } from '@dxos/protocols';
+
+import type { ForeignKey } from './foreign-key';
+
+/** Property name for meta when object is serialized to JSON. Matches @dxos/echo/internal ATTR_META. */
+const ATTR_META = '@meta';
+
+/**
+ * Codec for ECHO objects in feed block payload: JSON object ↔ UTF-8 bytes.
+ * Encodes with queue position stripped; decodes with optional position injection.
+ */
+export class EchoFeedCodec {
+  static readonly #encoder = new TextEncoder();
+  static readonly #decoder = new TextDecoder();
+
+  /**
+   * Prepares a value for feed storage (strips queue position from metadata) and encodes to bytes.
+   */
+  static encode(value: Record<string, unknown>): Uint8Array {
+    const prepared = EchoFeedCodec.#stripQueuePosition(value);
+    return EchoFeedCodec.#encoder.encode(JSON.stringify(prepared));
+  }
+
+  /**
+   * Decodes feed block bytes to a JSON value.
+   * If position is provided, injects queue position into the decoded object's metadata.
+   */
+  static decode(data: Uint8Array, position?: number): Record<string, unknown> {
+    const decoded = JSON.parse(EchoFeedCodec.#decoder.decode(data));
+    if (position !== undefined && typeof decoded === 'object' && decoded !== null) {
+      EchoFeedCodec.#setQueuePosition(decoded, position);
+    }
+    return decoded;
+  }
+
+  static #stripQueuePosition(value: Record<string, unknown>): Record<string, unknown> {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    const obj = structuredClone(value);
+    const meta = obj[ATTR_META] as { keys?: ForeignKey[] } | undefined;
+    if (meta?.keys?.some((key: ForeignKey) => key.source === FeedProtocol.KEY_QUEUE_POSITION)) {
+      meta.keys = meta.keys.filter((key: ForeignKey) => key.source !== FeedProtocol.KEY_QUEUE_POSITION);
+    }
+    return obj;
+  }
+
+  static #setQueuePosition(obj: Record<string, any>, position: number): void {
+    obj[ATTR_META] ??= { keys: [] };
+    obj[ATTR_META]!.keys ??= [];
+    const keys = obj[ATTR_META]!.keys!;
+    for (let i = 0; i < keys.length; i++) {
+      if (keys[i].source === FeedProtocol.KEY_QUEUE_POSITION) {
+        keys.splice(i, 1);
+        i--;
+      }
+    }
+    keys.push({
+      source: FeedProtocol.KEY_QUEUE_POSITION,
+      id: position.toString(),
+    });
+  }
+}

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/foreign-key.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, SchemaAST } from 'effect';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 const ForeignKey_ = Schema.Struct({
   /**
@@ -15,8 +16,8 @@ const ForeignKey_ = Schema.Struct({
    * Id within the foreign database.
    */
   // TODO(wittjosiah): This annotation is currently used to ensure id field shows up in forms.
-  // TODO(dmaretskyi): `false` is not a valid value for the annotation.
-  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: false }),
+  // TODO(dmaretskyi): `false` is not a valid value for the annotation. Use a different annotation.
+  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: 'false' }),
 });
 
 export type ForeignKey = Schema.Schema.Type<typeof ForeignKey_>;

package/src/index.ts

@@ -2,10 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
+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';
 export * from './reference';
 export * from './space-doc-version';
-export type * from './collection-sync';
 export * from './space-id';
-export * from './foreign-key';
-export * from './query';