@dxos/protocols 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

package/src/proto/dxos/client/queue.proto

@@ -2,7 +2,6 @@ syntax = "proto3";
 
 package dxos.client.services;
 
-import "google/protobuf/struct.proto";
 import "google/protobuf/empty.proto";
 
 
@@ -34,9 +33,12 @@ message QueueQuery {
 }
 
 message QueueQueryResult {
-  repeated google.protobuf.Struct objects = 1;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  /// We use JSON strings instead of google.protobuf.Struct because Struct
+  /// coerces `undefined` to `null`, corrupting optional fields.
+  repeated string objects = 1;
 
-  /// Cursor to query the next items. Can be passed to `after` in query to keep querying. 
+  /// Cursor to query the next items. Can be passed to `after` in query to keep querying.
   string next_cursor = 2;
 
   string prev_cursor = 3;
@@ -50,7 +52,8 @@ message InsertIntoQueueRequest {
   string subspace_tag = 1;
   string space_id = 2;
   string queue_id = 3;
-  repeated google.protobuf.Struct objects = 4;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  repeated string objects = 4;
 }
 
 message DeleteFromQueueRequest {

package/src/proto/dxos/client/services.proto

@@ -443,12 +443,22 @@ message JoinBySpaceKeyRequest {
 }
 
 message SpaceArchive {
+  enum Format {
+    // Tar-based binary archive (default).
+    BINARY = 0;
+    // JSON encoding of {@link dxos.echo.db.SerializedSpace}.
+    JSON = 1;
+  }
+
   string filename = 1;
   bytes contents = 2;
+  optional Format format = 3;
 }
 
 message ExportSpaceRequest {
   string space_id = 1;
+  // Archive format to produce. Defaults to BINARY.
+  optional SpaceArchive.Format format = 2;
 }
 
 message ExportSpaceResponse {

package/src/proto/dxos/config.proto

@@ -84,6 +84,17 @@ message Module {
 
 message Runtime {
   message Client {
+    /// Where client services run. Drives `createClientServices` routing.
+    enum ServicesMode {
+      UNSPECIFIED_SERVICES_MODE = 0;
+      /// Run services in the same thread as the client.
+      HOST = 1;
+      /// Run services in a SharedWorker (single instance shared across tabs).
+      SHARED_WORKER = 2;
+      /// Run services in a dedicated Worker elected via a lock (leader/follower).
+      DEDICATED_WORKER = 3;
+    }
+
     message Storage {
       enum StorageDriver {
         RAM = 0;
@@ -98,6 +109,20 @@ message Runtime {
         JSONDOWN = 12;
       }
 
+      /// Storage backing for SQLite (indexes & persistent state). The caller must supply the
+      /// matching worker factory / path — `createClientServices` does not pick a mode from the
+      /// presence of options.
+      enum SqliteMode {
+        UNSPECIFIED_SQLITE_MODE = 0;
+        /// Ephemeral in-memory SQLite. Indexes are rebuilt on each start.
+        MEMORY = 1;
+        /// OPFS-backed SQLite running in a dedicated worker (browser).
+        /// Requires `createOpfsWorker` to be passed to `createClientServices`.
+        OPFS = 2;
+        /// File-backed SQLite (Node/Bun). Uses `data_root` to locate the database file.
+        FILE = 3;
+      }
+
       optional bool persistent = 1;
       optional StorageDriver key_store = 2;
       optional StorageDriver data_store = 3;
@@ -107,6 +132,9 @@ message Runtime {
        * @deprecated
        */
       optional bool space_fragmentation = 5;
+
+      /// Backing store for SQLite runtimes. Defaults to MEMORY when unset.
+      optional SqliteMode sqlite_mode = 6;
     }
 
     message Log {
@@ -117,6 +145,8 @@ message Runtime {
     message EdgeFeatures {
       optional bool feed_replicator = 1;
       optional bool echo_replicator = 2;
+      /// Enables Subduction sedimentree transport for Automerge document replication.
+      optional bool subduction_replicator = 5;
       optional bool signaling = 3;
       optional bool agents = 4;
     }
@@ -155,6 +185,25 @@ message Runtime {
     optional bool enable_vector_indexing = 12;
 
     optional EdgeFeatures edge_features = 11;
+
+    /// Observability group attached as metadata to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional string observability_group = 13;
+
+    /// Enable telemetry metadata attached to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional bool signal_telemetry_enabled = 14;
+
+    /// Use in-process (single-client) coordinator for dedicated-worker mode.
+    /// Bypasses SharedWorker; used for WKWebView where the coordinator SharedWorker port is unreliable.
+    optional bool single_client_mode = 15;
+
+    /// Deployment mode for client services. Read by `createClientServices` to select between
+    /// in-process (HOST), SharedWorker, and dedicated Worker runtimes. Required when no
+    /// `remote_source` is configured.
+    optional ServicesMode services_mode = 16;
   }
 
   message App {

package/src/proto/dxos/echo/service.proto

@@ -60,8 +60,21 @@ message DocumentUpdate {
   /**
    * Automerge document incremental update.
    * Value returned by `Automerge.saveSince()`.
+   * Optional: if absent, the update only carries a transition signal (e.g.
+   * `requesting`) and not new bytes.
    */
-  bytes mutation = 2;
+  optional bytes mutation = 2;
+
+  /**
+   * Set by the worker when the disk probe for this document completes
+   * negative — i.e. the document is not on local storage, and the worker
+   * has started a network fetch. The client moves the corresponding
+   * `DocHandleProxy` from `'pending'` to `'requesting'`. Once the bytes
+   * eventually arrive, a normal `mutation` update follows and the handle
+   * transitions to `'ready'`. Used by query-driven (disk-only) callers to
+   * give up on a load without waiting on the network.
+   */
+  optional bool requesting = 3;
 }
 
 message DocHeadsList {

package/src/proto/dxos/iframe.proto

@@ -15,9 +15,6 @@ message StartRequest {
   string origin = 1;
   /// Key for the iframe resource lock used to determine when the service is closing.
   optional string lock_key = 2;
-  // TODO(nf): extract or remove?
-  optional string observabilityGroup = 3;
-  optional bool signalTelemetryEnabled = 4;
 }
 
 /// Iframe-to-worker RPCs.

package/src/proto/dxos/rpc.proto

@@ -29,11 +29,18 @@ message RpcMessage {
   }
 }
 
+/// W3C trace context carried across RPC boundaries.
+message TraceContext {
+  string traceparent = 1;
+  optional string tracestate = 2;
+}
+
 message Request {
   int32 id = 1;
   string method = 2;
   google.protobuf.Any payload = 3;
   bool stream = 4;
+  optional TraceContext trace_context = 5;
 }
 
 message Response {

package/src/proto/dxos/tracing.proto

@@ -30,42 +30,6 @@ message ResourceLink {
   google.protobuf.Struct attributes = 4;
 }
 
-message Span {
-  int32 id = 1;
-  optional int32 parent_id = 2;
-  optional int32 resource_id = 3;
-  string method_name = 4;
-
-  // TODO(dmaretskyi): Figure out proper sub-millisecond timestamp type.
-  string start_ts = 5;
-  optional string end_ts = 6;
-
-  optional dxos.error.Error error = 11;
-}
-
-message StreamTraceEvent {
-  message ResourceAdded {
-    Resource resource = 1;
-  }
-
-  message ResourceRemoved {
-    int32 id = 1;
-  }
-
-  message SpanAdded {
-    Span span = 1;
-  }
-
-  message LogAdded {
-    dxos.client.services.LogEntry log = 1;
-  }
-
-  repeated ResourceAdded resource_added = 1;
-  repeated ResourceRemoved resource_removed = 2;
-  repeated SpanAdded span_added = 3;
-  repeated LogAdded log_added = 4;
-}
-
 message Metric {
   message Counter {
     double value = 1;
@@ -110,7 +74,3 @@ message Metric {
     Custom custom = 199;
   }
 }
-
-service TracingService {
-  rpc StreamTrace(google.protobuf.Empty) returns (stream StreamTraceEvent);
-}

package/src/proto/gen/dxos/agent/dashboard.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/dashboard.proto}
+ * Defined in: `../../../dxos/agent/dashboard.proto`
  */
 export interface AgentStatus {
     status: AgentStatus.Status;
@@ -88,8 +87,7 @@ export namespace AgentStatus {
         OFF = 1
     }
     /**
-     * Defined in:
-     *   {@link file://./../../../dxos/agent/dashboard.proto}
+     * Defined in: `../../../dxos/agent/dashboard.proto`
      */
     export interface Memory {
         /**
@@ -104,8 +102,7 @@ export namespace AgentStatus {
     }
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/dashboard.proto}
+ * Defined in: `../../../dxos/agent/dashboard.proto`
  */
 export interface PluginState {
     id: string;

package/src/proto/gen/dxos/agent/echoproxy.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/echo-proxy.proto}
+ * Defined in: `../../../dxos/agent/echo-proxy.proto`
  */
 export interface Config {
     /**

package/src/proto/gen/dxos/agent/epoch.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/epoch.proto}
+ * Defined in: `../../../dxos/agent/epoch.proto`
  */
 export interface EpochMonitorConfig {
     /**

package/src/proto/gen/dxos/agent/functions.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface FunctionsConfig {
     /**
@@ -82,39 +81,34 @@ export interface FunctionsConfig {
     manifest?: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface Function {
     id: string;
     route: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface RegisterRequest {
     endpoint: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface RegisterResponse {
     registrationId: string;
     endpoint: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface UpdateRegistrationRequest {
     registrationId: string;
     functions?: Function[];
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/functions.proto}
+ * Defined in: `../../../dxos/agent/functions.proto`
  */
 export interface UnregisterRequest {
     registrationId: string;

package/src/proto/gen/dxos/bot.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../example/testing/data.js";
 import * as example_testing_rpc from "../example/testing/rpc.js";
 import * as google_protobuf from "../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface BotPackageSpecifier {
     /**
@@ -78,8 +77,7 @@ export interface BotPackageSpecifier {
     localPath?: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface Bot {
     id: string;
@@ -139,8 +137,7 @@ export namespace Bot {
         SPAWNING = 4
     }
     /**
-     * Defined in:
-     *   {@link file://./../../dxos/bot.proto}
+     * Defined in: `../../dxos/bot.proto`
      */
     export interface Runtime {
         /**
@@ -161,15 +158,13 @@ export namespace Bot {
     }
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface GetBotsResponse {
     bots?: Bot[];
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface SpawnBotRequest {
     /**
@@ -193,8 +188,7 @@ export interface SpawnBotRequest {
     spaceKey?: ReturnType<(typeof substitutions)["dxos.keys.PublicKey"]["decode"]>;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface SendCommandRequest {
     /**
@@ -209,8 +203,7 @@ export interface SendCommandRequest {
     command?: Uint8Array;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface SendCommandResponse {
     /**
@@ -220,22 +213,19 @@ export interface SendCommandResponse {
     response?: Uint8Array;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface GetLogsResponse {
     chunk: Uint8Array;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface GetLogsRequest {
     botId: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface BotReport {
     /**
@@ -263,8 +253,7 @@ export interface BotFactoryService {
     removeAll: (request: void, options?: RequestOptions) => Promise<void>;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface InitializeRequest {
     /**
@@ -290,8 +279,7 @@ export interface InitializeRequest {
     id?: string;
 }
 /**
- * Defined in:
- *   {@link file://./../../dxos/bot.proto}
+ * Defined in: `../../dxos/bot.proto`
  */
 export interface StartRequest {
     /**