@dxos/echo-protocol 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/package.json

@@ -1,37 +1,36 @@
 {
   "name": "@dxos/echo-protocol",
-  "version": "0.8.4-main.ead640a",
+  "version": "0.8.4-main.effb148878",
   "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.18.3",
-    "@dxos/crypto": "0.8.4-main.ead640a",
-    "@dxos/invariant": "0.8.4-main.ead640a",
-    "@dxos/keys": "0.8.4-main.ead640a",
-    "@dxos/util": "0.8.4-main.ead640a",
-    "@dxos/protocols": "0.8.4-main.ead640a"
+    "effect": "3.20.0",
+    "@dxos/invariant": "0.8.4-main.effb148878",
+    "@dxos/util": "0.8.4-main.effb148878",
+    "@dxos/protocols": "0.8.4-main.effb148878",
+    "@dxos/crypto": "0.8.4-main.effb148878",
+    "@dxos/keys": "0.8.4-main.effb148878"
   },
   "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 { ObjectId, URI } from '@dxos/keys';
 import { visitValues } from '@dxos/util';
 
 import { type RawString } from './automerge';
@@ -41,7 +41,7 @@ export interface DatabaseDirectory {
    * Object id points to an automerge doc url where the object is embedded.
    */
   links?: {
-    [echoId: string]: string | RawString;
+    [echoUri: string]: string | RawString;
   };
 
   /**
@@ -119,9 +119,9 @@ export const ObjectStructure = Object.freeze({
   /**
    * @throws On invalid object structure.
    */
-  getEntityKind: (object: ObjectStructure): 'object' | 'relation' => {
+  getEntityKind: (object: ObjectStructure): '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;
   },
 
@@ -137,6 +137,10 @@ export const ObjectStructure = Object.freeze({
     return object.system?.target;
   },
 
+  getParent: (object: ObjectStructure): EncodedReference | undefined => {
+    return object.system?.parent;
+  },
+
   /**
    * @returns All references in the data section of the object.
    */
@@ -162,7 +166,7 @@ export const ObjectStructure = Object.freeze({
     data,
     keys,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     deleted?: boolean;
     keys?: ForeignKey[];
     data?: unknown;
@@ -187,7 +191,7 @@ export const ObjectStructure = Object.freeze({
     keys,
     data,
   }: {
-    type: DXN.String;
+    type: URI.URI;
     source: EncodedReference;
     target: EncodedReference;
     deleted?: boolean;
@@ -208,6 +212,19 @@ export const ObjectStructure = Object.freeze({
       data: data ?? {},
     };
   },
+
+  makeType: ({ type, keys, data }: { type: URI.URI; keys?: ForeignKey[]; data?: unknown }): ObjectStructure => {
+    return {
+      system: {
+        kind: 'type',
+        type: { '/': type },
+      },
+      meta: {
+        keys: keys ?? [],
+      },
+      data: data ?? {},
+    };
+  },
 });
 
 /**
@@ -226,6 +243,18 @@ export type ObjectMeta = {
    * NOTE: Optional for backwards compatibilty.
    */
   tags?: 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;
 };
 
 /**
@@ -234,12 +263,22 @@ export type ObjectMeta = {
  */
 export type ObjectSystem = {
   /**
-   * 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:type: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;
 
@@ -248,13 +287,19 @@ 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;
 };

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/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';