@dxos/protocols 0.8.3 → 0.8.4-main.1068cf700f

package/package.json

@@ -1,68 +1,60 @@
 {
   "name": "@dxos/protocols",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1068cf700f",
   "description": "Protobuf definitions for DXOS protocols.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "info@dxos.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
-      "browser": "./dist/esm/src/index.js",
-      "import": "./dist/esm/src/index.js",
-      "require": "./dist/cjs/src/index.js",
-      "node": "./dist/cjs/src/index.js"
+      "browser": "./dist/src/index.js",
+      "import": "./dist/src/index.js"
     },
     "./feed-replication": {
-      "browser": "./dist/esm/src/feed-replication.js",
-      "import": "./dist/esm/src/feed-replication.js",
-      "require": "./dist/cjs/src/feed-replication.js",
-      "node": "./dist/cjs/src/feed-replication.js"
+      "browser": "./dist/src/feed-replication.js",
+      "import": "./dist/src/feed-replication.js"
     },
     "./proto": {
-      "browser": "./dist/esm/src/proto/index.js",
-      "import": "./dist/esm/src/proto/index.js",
-      "require": "./dist/cjs/src/proto/index.js",
-      "node": "./dist/cjs/src/proto/index.js"
+      "browser": "./dist/src/proto/index.js",
+      "import": "./dist/src/proto/index.js"
     },
     "./proto/*": {
-      "browser": "./dist/esm/src/proto/gen/*.js",
-      "import": "./dist/esm/src/proto/gen/*.js",
-      "require": "./dist/cjs/src/proto/gen/*.js",
-      "node": "./dist/cjs/src/proto/gen/*.js"
+      "browser": "./dist/src/proto/gen/*.js",
+      "import": "./dist/src/proto/gen/*.js"
     },
     "./buf": {
-      "browser": "./dist/esm/src/buf/index.js",
-      "import": "./dist/esm/src/buf/index.js",
-      "require": "./dist/cjs/src/buf/index.js",
-      "node": "./dist/cjs/src/buf/index.js"
+      "browser": "./dist/src/buf/index.js",
+      "import": "./dist/src/buf/index.js"
     },
     "./buf/*": {
-      "browser": "./dist/esm/src/buf/proto/gen/*.js",
-      "import": "./dist/esm/src/buf/proto/gen/*.js",
-      "require": "./dist/cjs/src/buf/proto/gen/*.js",
-      "node": "./dist/cjs/src/buf/proto/gen/*.js"
+      "browser": "./dist/src/buf/proto/gen/*.js",
+      "import": "./dist/src/buf/proto/gen/*.js"
     }
   },
-  "types": "dist/esm/src/index.d.ts",
+  "types": "dist/src/index.d.ts",
   "typesVersions": {
     "*": {
       "proto/*": [
-        "dist/esm/src/proto/gen/*"
+        "dist/src/proto/gen/*"
       ],
       "buf/*": [
-        "dist/esm/src/buf/proto/gen/*"
+        "dist/src/buf/proto/gen/*"
       ],
       "feed-replication": [
-        "dist/esm/src/feed-replication.d.ts"
+        "dist/src/feed-replication.d.ts"
       ],
       "buf": [
-        "dist/esm/src/buf/index.d.ts"
+        "dist/src/buf/index.d.ts"
       ],
       "proto": [
-        "dist/esm/src/proto/index.d.ts"
+        "dist/src/proto/index.d.ts"
       ]
     }
   },
@@ -71,27 +63,25 @@
     "src"
   ],
   "dependencies": {
-    "@bufbuild/protobuf": "^2.1.0",
-    "@dxos/codec-protobuf": "0.8.3",
-    "@dxos/effect": "0.8.3",
-    "@dxos/keys": "0.8.3",
-    "@dxos/timeframe": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/util": "0.8.3"
+    "@bufbuild/protobuf": "2.11.0",
+    "@dxos/codec-protobuf": "0.8.4-main.1068cf700f",
+    "@dxos/effect": "0.8.4-main.1068cf700f",
+    "@dxos/errors": "0.8.4-main.1068cf700f",
+    "@dxos/invariant": "0.8.4-main.1068cf700f",
+    "@dxos/keys": "0.8.4-main.1068cf700f",
+    "@dxos/util": "0.8.4-main.1068cf700f",
+    "@dxos/timeframe": "0.8.4-main.1068cf700f"
   },
   "devDependencies": {
-    "@bufbuild/buf": "^1.43.0",
-    "@bufbuild/protoc-gen-es": "^2.1.0",
-    "effect": "3.14.21"
+    "@bufbuild/buf": "1.65.0",
+    "@bufbuild/protoc-gen-es": "2.11.0",
+    "effect": "3.19.16",
+    "@dxos/protobuf-compiler": "0.8.4-main.1068cf700f"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.19.16"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "compile:buf": "buf generate",
-    "tsc:cjs": "rm -rf dist/cjs; tsc --module commonjs --moduleResolution node --target es2018 --outdir ./dist/cjs && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json"
   }
 }

package/src/FeedProtocol.ts

@@ -0,0 +1,319 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export {
+  type QueueService,
+  type QueueQuery,
+  type QueueQueryResult as QueryResult,
+  type QueryQueueRequest,
+  type InsertIntoQueueRequest,
+  type DeleteFromQueueRequest,
+} from './proto/gen/dxos/client/services.js';
+
+export const KEY_QUEUE_POSITION = 'dxos.org/key/queue-position';
+
+import * as Schema from 'effect/Schema';
+
+import { invariant } from '@dxos/invariant';
+import { SpaceId } from '@dxos/keys';
+
+import { EdgeService } from './edge/edge.js';
+
+/**
+ * Opaque pagination cursor for feed queries.
+ */
+export const FeedCursor = Schema.String.pipe(Schema.brand('@dxos/feed/FeedCursor'));
+export type FeedCursor = Schema.Schema.Type<typeof FeedCursor>;
+
+/**
+ * Replicated queue block payload and ordering metadata.
+ */
+export const Block = Schema.Struct({
+  /**
+   * Appears on blocks returned from query.
+   */
+  feedId: Schema.UndefinedOr(Schema.String),
+
+  /**
+   * Actor that produced this block.
+   */
+  actorId: Schema.String,
+
+  /**
+   * Per-feed monotonic sequence assigned by the actor.
+   */
+  sequence: Schema.Number,
+
+  /**
+   * Actor of the immediate predecessor block, if any.
+   */
+  prevActorId: Schema.NullOr(Schema.String),
+
+  /**
+   * Sequence of the immediate predecessor block, if any.
+   */
+  prevSequence: Schema.NullOr(Schema.Number),
+
+  /**
+   * Globally ordered position assigned by a position authority.
+   * Unlike `sequence` (per-feed causal order), this enables merged incremental reads across feeds.
+   */
+  position: Schema.NullOr(Schema.Number),
+
+  /**
+   * Milliseconds since Unix epoch when the block was created.
+   */
+  timestamp: Schema.Number,
+
+  /**
+   * Serialized application payload.
+   */
+  data: Schema.Uint8Array,
+
+  /**
+   * Local insertion ID.
+   * Not replicated.
+   */
+  // TODO(dmaretskyi): Remove. Use cursors.
+  insertionId: Schema.optional(Schema.Number),
+});
+export interface Block extends Schema.Schema.Type<typeof Block> {}
+
+//
+// RPC Schemas
+//
+
+/**
+ * Query parameters for retrieving blocks from one namespace in one space.
+ */
+export const QueryRequest = Schema.Struct({
+  /**
+   * Optional request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Target space identifier.
+   */
+  spaceId: SpaceId,
+
+  /**
+   * Feed namespace to query.
+   */
+  feedNamespace: Schema.String,
+
+  query: Schema.optional(
+    Schema.Union(
+      Schema.Struct({
+        /**
+         * Explicit list of feed IDs to read from.
+         */
+        feedIds: Schema.Array(Schema.String),
+      }),
+      Schema.Struct({
+        /**
+         * Existing subscription to resolve feed IDs from.
+         */
+        subscriptionId: Schema.String,
+      }),
+    ),
+  ),
+
+  /**
+   * Get changes following this cursor (exclusive).
+   *
+   * Must not be used with `position`.
+   */
+  cursor: Schema.optional(FeedCursor),
+
+  /**
+   * Get changes following this position.
+   * Returned blocks have strictly greater position than this.
+   *
+   * Must not be used with `cursor`.
+   */
+  position: Schema.optional(Schema.Number),
+
+  /**
+   * Only return blocks that are not positioned.
+   *
+   * Must not be used with `cursor` or `position`.
+   */
+  unpositionedOnly: Schema.optional(Schema.Boolean),
+
+  /**
+   * Maximum number of blocks to return.
+   */
+  limit: Schema.optional(Schema.Number),
+});
+export interface QueryRequest extends Schema.Schema.Type<typeof QueryRequest> {}
+
+/**
+ * Result payload for a query operation.
+ */
+export const QueryResponse = Schema.Struct({
+  /**
+   * Echoed request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Cursor to continue reading from this result boundary.
+   */
+  nextCursor: FeedCursor,
+
+  /**
+   * Indicates whether more matching blocks are available.
+   */
+  hasMore: Schema.Boolean,
+
+  /**
+   * Returned blocks for the current page.
+   */
+  blocks: Schema.Array(Block),
+});
+export interface QueryResponse extends Schema.Schema.Type<typeof QueryResponse> {}
+
+/**
+ * Parameters for creating or refreshing a feed subscription.
+ */
+export const SubscribeRequest = Schema.Struct({
+  /**
+   * Optional request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Optional space scope for the subscription.
+   */
+  spaceId: Schema.optional(Schema.String),
+
+  /**
+   * Feeds to include in the subscription.
+   */
+  feedIds: Schema.Array(Schema.String),
+});
+export interface SubscribeRequest extends Schema.Schema.Type<typeof SubscribeRequest> {}
+
+/**
+ * Response payload for subscription creation.
+ */
+export const SubscribeResponse = Schema.Struct({
+  /**
+   * Echoed request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Identifier to use in subsequent subscription queries.
+   */
+  subscriptionId: Schema.String,
+
+  /**
+   * Expiration timestamp in milliseconds since Unix epoch.
+   */
+  expiresAt: Schema.Number,
+});
+export interface SubscribeResponse extends Schema.Schema.Type<typeof SubscribeResponse> {}
+
+/**
+ * Request payload for appending one or more blocks.
+ */
+export const AppendRequest = Schema.Struct({
+  /**
+   * Optional request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Target space identifier.
+   */
+  spaceId: Schema.String,
+
+  /**
+   * Namespace that all appended blocks belong to.
+   */
+  feedNamespace: Schema.String,
+
+  /**
+   * Blocks to append.
+   */
+  blocks: Schema.Array(Block),
+});
+export interface AppendRequest extends Schema.Schema.Type<typeof AppendRequest> {}
+
+/**
+ * Result payload for append operations.
+ */
+export const AppendResponse = Schema.Struct({
+  /**
+   * Echoed request correlation identifier.
+   */
+  requestId: Schema.optional(Schema.String),
+
+  /**
+   * Assigned global positions for appended blocks.
+   */
+  positions: Schema.Array(Schema.Number),
+});
+export interface AppendResponse extends Schema.Schema.Type<typeof AppendResponse> {}
+
+/**
+ * Tagged transport message union for queue protocol RPC traffic.
+ */
+export const ProtocolMessage = Schema.Union(
+  Schema.TaggedStruct('QueryRequest', QueryRequest.fields),
+  Schema.TaggedStruct('QueryResponse', QueryResponse.fields),
+  Schema.TaggedStruct('SubscribeRequest', SubscribeRequest.fields),
+  Schema.TaggedStruct('SubscribeResponse', SubscribeResponse.fields),
+  Schema.TaggedStruct('AppendRequest', AppendRequest.fields),
+  Schema.TaggedStruct('AppendResponse', AppendResponse.fields),
+  Schema.TaggedStruct('Error', {
+    /**
+     * Human-readable error message.
+     */
+    message: Schema.String,
+  }),
+).pipe(
+  Schema.extend(
+    Schema.Struct({
+      senderPeerId: Schema.UndefinedOr(Schema.String),
+      /**
+       * Could be undefined if the recipient could be assumed from the context.
+       */
+      recipientPeerId: Schema.UndefinedOr(Schema.String),
+    }),
+  ),
+);
+export type ProtocolMessage = Schema.Schema.Type<typeof ProtocolMessage>;
+
+/**
+ * Reserved namespaces with protocol-level semantics.
+ */
+export const WellKnownNamespaces = {
+  data: 'data',
+  trace: 'trace',
+} as const;
+
+export const isWellKnownNamespace = (namespace: string) =>
+  Object.values(WellKnownNamespaces).includes(namespace as any);
+
+/**
+ * Encodes queue replicator service identifier as `<service>:<namespace>:<spaceId>`.
+ */
+export const encodeServiceId = (namespace: string, spaceId: SpaceId) =>
+  `${EdgeService.QUEUE_REPLICATOR}:${namespace}:${spaceId}`;
+
+/**
+ * Decodes and validates queue replicator service identifier.
+ */
+export const decodeServiceId = (
+  serviceId: string,
+): { namespace: keyof typeof WellKnownNamespaces; spaceId: SpaceId } => {
+  const [service, namespace, spaceId] = serviceId.split(':');
+  invariant(service === EdgeService.QUEUE_REPLICATOR, `Invalid service: ${service}`);
+  invariant(isWellKnownNamespace(namespace), `Invalid namespace: ${namespace}`);
+  invariant(SpaceId.isValid(spaceId), `Invalid spaceId: ${spaceId}`);
+  return { namespace: namespace as keyof typeof WellKnownNamespaces, spaceId };
+};

package/src/FunctionProtocol.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type SpaceId } from '@dxos/keys';
+import type * as QueryProto from '@dxos/protocols/proto/dxos/echo/query';
+import type * as DataProto from '@dxos/protocols/proto/dxos/echo/service';
+
+import { type EdgeFunctionEnv } from './edge';
+import type * as FeedProtocol from './FeedProtocol';
+
+//
+// Function protocol definition
+//
+
+// - All types must be trivially serializable - no class instances.
+// - Cannot use effect.
+// - Protobuf service definitions are allowed (Q: What about PublicKey, Timeframe, etc.).
+// - Breaking changes in this interface should be carefully considered.
+
+// TODO(dmaretskyi): Consider moving this to protocols.
+
+/**
+ * Function implementation.
+ * This is a contract between the user-defined function and the runtime.
+ */
+export interface Func {
+  readonly meta: Meta;
+  readonly handler: Handler;
+}
+
+/**
+ * Function metadata.
+ */
+export interface Meta {
+  readonly key: string;
+  name?: string;
+  description?: string;
+  /**
+   * Required services.
+   */
+  readonly services: readonly string[];
+  /**
+   * JSON schema format
+   */
+  readonly inputSchema: unknown;
+  /**
+   * JSON schema format.
+   */
+  readonly outputSchema?: unknown;
+}
+
+/**
+ * Function handler.
+ * Executed by the runtime
+ */
+export type Handler = (opts: { data: unknown; context: Context }) => Promise<unknown>;
+
+/**
+ * Function context.
+ */
+export interface Context {
+  services: {
+    /**
+     * Query service.
+     * Available if the function is invoked in context of a space.
+     */
+    queryService?: QueryProto.QueryService;
+
+    /**
+     * Data service.
+     * Available if the function is invoked in context of a space.
+     */
+    dataService?: DataProto.DataService;
+
+    /**
+     * Queue service.
+     * Available if the function is invoked in context of a space.
+     */
+    queueService?: FeedProtocol.QueueService;
+
+    /**
+     * Functions service.
+     * Available if the function is invoked in context of a space.
+     */
+    functionsAiService?: EdgeFunctionEnv.FunctionsAiService;
+  };
+
+  /**
+   * That space that the function is invoked in context of.
+   */
+  spaceId?: SpaceId;
+
+  /**
+   * Hex-encoded space key.
+   * @deprecated We need to remove this but ECHO keeps dragging this in.
+   */
+  spaceKey?: string;
+
+  /**
+   * Automerge URL of the space-root document.
+   */
+  spaceRootUrl?: string;
+}

package/src/automerge.ts

@@ -16,6 +16,7 @@ export type LeaveProtocolMessage = {
   type: 'leave';
   targetId?: PeerId;
   senderId: PeerId;
+  metadata?: Record<string, unknown>;
 };
 
 export type PeerProtocolMessage = {
@@ -39,6 +40,7 @@ export type RequestProtocolMessage = {
   targetId: PeerId;
   documentId: string;
   data: Uint8Array;
+  metadata?: Record<string, unknown>;
 };
 
 /**
@@ -50,6 +52,7 @@ export type SyncProtocolMessage = {
   targetId: PeerId;
   documentId: string;
   data: Uint8Array;
+  metadata?: Record<string, unknown>;
 };
 
 /**
@@ -61,6 +64,7 @@ export type UnavailableProtocolMessage = {
   senderId: PeerId;
   targetId: PeerId;
   documentId: string;
+  metadata?: Record<string, unknown>;
 };
 
 /**
@@ -82,6 +86,7 @@ export type EphemeralProtocolMessage = {
   sessionId: string;
   documentId: string;
   data: Uint8Array;
+  metadata?: Record<string, unknown>;
 };
 
 export type ErrorProtocolMessage = {
@@ -89,6 +94,7 @@ export type ErrorProtocolMessage = {
   senderId?: PeerId;
   targetId?: PeerId;
   message: string;
+  metadata?: Record<string, unknown>;
 };
 
 export const MESSAGE_TYPE_COLLECTION_QUERY = 'collection-query';
@@ -104,6 +110,7 @@ export type CollectionQueryMessage = {
    * Remote peer will skip sending the state if it has the same tag.
    */
   stateTag?: string;
+  metadata?: Record<string, unknown>;
 };
 
 export const MESSAGE_TYPE_COLLECTION_STATE = 'collection-state';
@@ -123,6 +130,7 @@ export type CollectionStateMessage = {
    * Identifier of the current state.
    */
   stateTag?: string;
+  metadata?: Record<string, unknown>;
 };
 
 export type AutomergeProtocolMessage =

package/src/buf/proto/gen/dxos/agent/dashboard_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/agent/dashboard.proto (package dxos.agent.dashboard, syntax proto3)
 /* eslint-disable */
 
-import type { GenEnum, GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv1";
-import { enumDesc, fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenEnum, GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { enumDesc, fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
 import type { EmptySchema } from "@bufbuild/protobuf/wkt";
 import { file_google_protobuf_empty, file_google_protobuf_struct } from "@bufbuild/protobuf/wkt";
 import type { Runtime_Agent_Plugin } from "../config_pb.js";

package/src/buf/proto/gen/dxos/agent/echo-proxy_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/agent/echo-proxy.proto (package dxos.agent.echoproxy, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
 
 /**

package/src/buf/proto/gen/dxos/agent/epoch_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/agent/epoch.proto (package dxos.agent.epoch, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
 
 /**

package/src/buf/proto/gen/dxos/agent/functions_pb.ts

@@ -2,14 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.11.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/agent/functions.proto (package dxos.agent.functions, syntax proto3)
 /* eslint-disable */
 
 // TODO(burdon): dxos.agent.plugin.functions
 
-import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
 import type { EmptySchema } from "@bufbuild/protobuf/wkt";
 import { file_google_protobuf_empty } from "@bufbuild/protobuf/wkt";
 import type { Message } from "@bufbuild/protobuf";