@dxos/protocols 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/index.ts

@@ -2,16 +2,15 @@
 // Copyright 2021 DXOS.org
 //
 
-export * from './automerge.js';
-export * from './edge-error.js';
-export * from './edge.js';
-export * from './errors/index.js';
-export * from './indexing.js';
-export * from './profile-archive.js';
-export * from './query.js';
-export * from './queue.js';
-export * from './space-archive.js';
-export * from './storage.js';
-export * from './tracing.js';
-export type * from './types.js';
-export * as FunctionProtocol from './FunctionProtocol.js';
+export * from './automerge.ts';
+export * from './edge/index.ts';
+export * from './errors/index.ts';
+export * from './indexing.ts';
+export * from './messenger.ts';
+export * from './profile-archive.ts';
+export * from './space-archive.ts';
+export * from './storage.ts';
+export type * from './types.ts';
+export * as FunctionProtocol from './FunctionProtocol.ts';
+export * as FeedProtocol from './FeedProtocol.ts';
+export * as TraceProtocol from './TraceProtocol.ts';

package/src/indexing.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ObjectPointerVersion, objectPointerCodec } from './indexing.js';
+import { ObjectPointerVersion, objectPointerCodec } from './indexing.ts';
 
 describe('Indexing object pointer codec', () => {
   test('getVersion', async () => {

package/src/invitation.ts

@@ -4,11 +4,11 @@
 
 import * as Schema from 'effect/Schema';
 
-import { ParamKeyAnnotation } from '@dxos/effect';
+import { SchemaEx } from '@dxos/effect';
 
 // TODO(burdon): Use uniformly for processing HTTP params.
 export const InvitationUrl = Schema.Struct({
   accessToken: Schema.String, // TODO(burdon): Remove.
-  deviceInvitationCode: Schema.String.pipe(ParamKeyAnnotation({ key: 'deviceInvitationCode' })),
-  spaceInvitationCode: Schema.String.pipe(ParamKeyAnnotation({ key: 'spaceInvitationCode' })),
+  deviceInvitationCode: Schema.String.pipe(SchemaEx.ParamKeyAnnotation({ key: 'deviceInvitationCode' })),
+  spaceInvitationCode: Schema.String.pipe(SchemaEx.ParamKeyAnnotation({ key: 'spaceInvitationCode' })),
 });

package/src/messenger.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type CleanupFn } from '@dxos/async';
+
+import { type GossipMessage } from './proto/gen/dxos/mesh/teleport/gossip';
+
+/**
+ * Message passing abstraction.
+ */
+export interface Messenger {
+  /**
+   * Register channel listener.
+   */
+  listen: (channel: string, callback: (message: GossipMessage) => void) => CleanupFn;
+
+  /**
+   * Send message to channel.
+   */
+  postMessage: (channel: string, message: any) => Promise<void>;
+}

package/src/profile-archive.ts

@@ -8,17 +8,30 @@
 export type ProfileArchive = {
   meta: {
     timestamp: string;
+    /** Host (e.g. `main.composer.space`, `localhost:5173`) where the archive was exported. */
+    origin?: string;
   };
   storage: ProfileArchiveEntry[];
 };
 
 export type ProfileArchiveEntry = {
   type: ProfileArchiveEntryType;
+  /**
+   * FILE: filename in random-access storage.
+   * KEY_VALUE: binary LevelDB key.
+   * SQLITE_DATABASE: OPFS database filename (e.g. `DXOS`).
+   */
   key: string | Uint8Array;
+  /**
+   * FILE / KEY_VALUE / SQLITE_DATABASE: binary payload.
+   * SQLITE_DATABASE must be a valid SQLite file (magic `SQLite format 3`).
+   */
   value: string | Uint8Array;
 };
 
 export enum ProfileArchiveEntryType {
   FILE = 1,
   KEY_VALUE = 2,
+  /** OPFS-hosted SQLite database; `key` is the OPFS filename, `value` is raw SQLite bytes. */
+  SQLITE_DATABASE = 3,
 }

package/src/proto/dxos/client/invitation.proto

@@ -43,6 +43,9 @@ enum SpaceState {
   /// Space is active. Swarming and replication will be done.
   SPACE_ACTIVE = 6;
 
+  /// Space is tombstoned (soft-deleted). Replicated to other devices; never auto-opened.
+  SPACE_DELETED = 9;
+
   ///
   /// Runtime states:
   ///
@@ -85,8 +88,12 @@ message Invitation {
   }
 
   enum Kind {
-    DEVICE = 0;
-    SPACE = 1;
+    /// Unset / unknown. Must not be used for new invitations.
+    INVALID = 0;
+
+    DEVICE = 1;
+
+    SPACE = 2;
   }
 
   enum AuthMethod {

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

@@ -0,0 +1,102 @@
+syntax = "proto3";
+
+package dxos.client.services;
+
+import "google/protobuf/empty.proto";
+
+
+message QueueQuery {
+  string space_id = 1;
+
+  optional string queues_namespace = 2;
+
+  /// Queries the whole space if missing.
+  repeated string queue_ids = 3;
+
+  /// Filter items after this cursor. Exclusive.
+  optional string after = 4;
+
+  /// Filter items before this cursor. Exclusive.
+  optional string before = 5;
+
+  /// Filter items after this position. Inclusive.
+  optional int64 begin_position = 6;
+
+  /// Filter items before this position. Exclusive.
+  optional int64 end_position = 7;
+
+  optional int32 limit = 8;
+  optional bool reverse = 9;
+
+  // TODO(dmaretskyi): Remove this field -- raw queues dont index object IDs anymore.
+  repeated string object_ids = 100;
+}
+
+message QueueQueryResult {
+  /// 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.
+  string next_cursor = 2;
+
+  string prev_cursor = 3;
+}
+
+message QueryQueueRequest {
+  QueueQuery query = 1;
+}
+
+message InsertIntoQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  repeated string objects = 4;
+}
+
+message DeleteFromQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  repeated string object_ids = 4;
+}
+
+message SyncQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  /// Whether to push local changes to the server. Defaults to true.
+  optional bool should_push = 4;
+  /// Whether to pull remote changes from the server. Defaults to true.
+  optional bool should_pull = 5;
+}
+
+message GetSyncStateRequest {
+  string space_id = 1;
+  /// If empty, returns state for all namespaces synced by the client.
+  repeated string namespaces = 2;
+}
+
+message QueueNamespaceSyncState {
+  string namespace = 1;
+  /// Blocks still to pull from remote. 0 when caught up.
+  int64 blocks_to_pull = 2;
+  /// Unpositioned blocks still to push to remote. 0 when caught up.
+  int64 blocks_to_push = 3;
+  /// Total blocks stored locally for this namespace in the space.
+  int64 total_blocks = 4;
+}
+
+message GetSyncStateResponse {
+  repeated QueueNamespaceSyncState namespaces = 1;
+}
+
+service QueueService {
+  rpc QueryQueue(QueryQueueRequest) returns (QueueQueryResult);
+  rpc InsertIntoQueue(InsertIntoQueueRequest) returns (google.protobuf.Empty);
+  rpc DeleteFromQueue(DeleteFromQueueRequest) returns (google.protobuf.Empty);
+  rpc SyncQueue(SyncQueueRequest) returns (google.protobuf.Empty);
+  rpc GetSyncState(GetSyncStateRequest) returns (GetSyncStateResponse);
+}

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

@@ -72,6 +72,7 @@ message Platform {
     BROWSER = 0;
     SHARED_WORKER = 1;
     NODE = 2;
+    DEDICATED_WORKER = 3;
   }
 
   PLATFORM_TYPE type = 1;
@@ -145,6 +146,8 @@ message RecoverIdentityRequest {
     string recovery_code = 1;
     ExternalSignature external = 2;
     string token = 3;
+    /// One-time proof minted by edge kms-service after a successful OAuth recovery flow.
+    string recovery_proof = 4;
   }
 }
 
@@ -331,6 +334,8 @@ message Space {
   optional PipelineState pipeline = 3;
   optional dxos.error.Error error = 4;
   optional dxos.echo.metadata.EdgeReplicationSetting edge_replication = 6;
+  repeated string tags = 7;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 8;
 
   repeated SpaceMember members = 10;
   optional dxos.keys.PublicKey creator = 11;
@@ -341,6 +346,11 @@ message Space {
 
 // TODO(burdon): Create type for epoch?
 
+message CreateSpaceRequest {
+  repeated string tags = 1;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 2;
+}
+
 message UpdateSpaceRequest {
   dxos.keys.PublicKey space_key = 1;
 
@@ -435,12 +445,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 {
@@ -449,6 +469,8 @@ message ExportSpaceResponse {
 
 message ImportSpaceRequest {
   SpaceArchive archive = 1;
+  /// Immutable tags to set on the imported space at creation time.
+  repeated string tags = 2;
 }
 
 message ImportSpaceResponse {
@@ -457,7 +479,7 @@ message ImportSpaceResponse {
 }
 
 service SpacesService {
-  rpc CreateSpace(google.protobuf.Empty) returns (Space);
+  rpc CreateSpace(CreateSpaceRequest) returns (Space);
   rpc UpdateSpace(UpdateSpaceRequest) returns (google.protobuf.Empty);
   rpc QuerySpaces(google.protobuf.Empty) returns (stream QuerySpacesResponse);
 

package/src/proto/dxos/config.proto

@@ -59,7 +59,7 @@ message Module {
   optional string id = 8;   // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
   optional string name = 1; // TODO(burdon): Replace with id (or key?)
   optional string type = 2; // TODO(burdon): Define namespace (e.g.,
-                            // 'dxos.org/type/frame' vs. 'dxos.type.frame')
+                            // 'org.dxos.type.frame')
 
   // TODO(burdon): Developer info message.
 
@@ -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/devtools/host.proto

@@ -78,6 +78,13 @@ service DevtoolsHost {
   rpc SubscribeToSignalStatus(google.protobuf.Empty) returns (stream SubscribeToSignalStatusResponse);
   rpc SubscribeToSignal(google.protobuf.Empty) returns (stream SignalResponse);
   rpc SubscribeToSwarmInfo(SubscribeToSwarmInfoRequest) returns (stream SubscribeToSwarmInfoResponse);
+
+  //
+  // SQLite
+  //
+
+  rpc ExportSqliteDatabase(google.protobuf.Empty) returns (ExportSqliteDatabaseResponse);
+  rpc RunSqliteQuery(RunSqliteQueryRequest) returns (RunSqliteQueryResponse);
 }
 
 message Event {
@@ -338,3 +345,23 @@ message SubscribeToSwarmInfoRequest {}
 message SubscribeToSwarmInfoResponse {
   repeated dxos.devtools.swarm.SwarmInfo data = 1;
 }
+
+//
+// SQLite
+//
+
+message ExportSqliteDatabaseResponse {
+  bytes data = 1;
+}
+
+message RunSqliteQueryRequest {
+  string query = 1;
+  // JSON-encoded array of query parameters.
+  optional string params = 2;
+}
+
+message RunSqliteQueryResponse {
+  // JSON-encoded array of row objects.
+  string rows = 1;
+  optional string error = 2;
+}

package/src/proto/dxos/echo/metadata.proto

@@ -34,6 +34,9 @@ message EchoMetadata {
 
   // TODO(burdon): Circular dep.
   repeated dxos.client.services.Invitation invitations = 12;
+
+  /// Keys of spaces that have been tombstoned (soft-deleted). Survives restart; prevents re-acceptance.
+  repeated dxos.keys.PublicKey deleted_spaces = 13;
 }
 
 /// Per-space metadata. Frequent updates. Keep small.
@@ -54,6 +57,9 @@ message SpaceMetadata {
   /// Space key.
   dxos.keys.PublicKey key = 1;
 
+  /// Immutable tags assigned at space creation time.
+  repeated string tags = 12;
+
   /// ACTIVE, INACTIVE, etc.
   optional dxos.client.services.SpaceState state = 10;
 

package/src/proto/dxos/echo/query.proto

@@ -36,9 +36,12 @@ message Heads {
 message QueryResult {
   string id = 1;
   string spaceId = 4;
-  string documentId = 5;
+  optional string documentId = 5;
+  optional string queueId = 6;
+  optional string queueNamespace = 7;
   float rank = 3;
 
+  /// In the ECHO Json object format.
   optional string document_json = 10;
   optional bytes document_automerge = 11;
   

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

@@ -6,6 +6,7 @@ syntax = "proto3";
 
 import "dxos/keys.proto";
 import "google/protobuf/empty.proto";
+import "google/protobuf/struct.proto";
 
 package dxos.echo.service;
 
@@ -59,14 +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 to true for init mutation of document.
-   * default: undefined.
+   * 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 is_new = 3;
+  optional bool requesting = 3;
 }
 
 message DocHeadsList {
@@ -94,6 +102,26 @@ message ReIndexHeadsRequest {
   repeated string document_ids = 1;
 }
 
+message CreateDocumentRequest {
+  /**
+   * Space id where the document will be created.
+   */
+  string space_id = 1;
+
+  /**
+   * Automerge encoded initial document value.
+   * Optional - if not provided, an empty document will be created.
+   */
+  optional google.protobuf.Struct initial_value = 2;
+}
+
+message CreateDocumentResponse {
+  /**
+   * The generated document id.
+   */
+  string document_id = 1;
+}
+
 message GetSpaceSyncStateRequest {
   string space_id = 1;
 }
@@ -157,6 +185,12 @@ service DataService {
    */
   rpc UpdateSubscription(UpdateSubscriptionRequest) returns (google.protobuf.Empty);
 
+  /**
+   * Create a new automerge document.
+   * Returns the generated document id which is controlled by the host.
+   */
+   rpc CreateDocument(CreateDocumentRequest) returns (CreateDocumentResponse);
+
   /**
    * Write incremental updates to multiple automerge documents.
    * Used to propagate changes from client to services.

package/src/proto/dxos/edge/messenger.proto

@@ -76,9 +76,19 @@ message Message {
   /// Maybe be used to address a service at EDGE, but also to address components inside the client.
   optional string service_id = 20;
 
+  optional TraceContext trace_context = 21;
+
   optional google.protobuf.Any payload = 100;
 }
 
+/// W3C Trace Context propagation (https://www.w3.org/TR/trace-context/).
+message TraceContext {
+  /// W3C `traceparent` header value (e.g. "00-<trace-id>-<parent-id>-<trace-flags>").
+  string traceparent = 1;
+  /// W3C `tracestate` header value; vendor-specific key-value pairs.
+  optional string tracestate = 2;
+}
+
 //
 // Swarms are used to publish and subscribe to messages based on a topic.
 //

package/src/proto/dxos/halo/credentials.proto

@@ -28,9 +28,18 @@ import "dxos/keys.proto";
 // First message written to initial Feed in a new Space.
 //
 
+enum MembershipPolicy {
+  /// Members can be invited by admins/owners.
+  INVITE = 0;
+  /// No new members can be added after genesis.
+  LOCKED = 1;
+}
+
 // [ASSERTION]
 message SpaceGenesis {
   dxos.keys.PublicKey space_key = 1; // Feeds belong to Spaces.
+  repeated string tags = 2;
+  MembershipPolicy membership_policy = 3;
 }
 
 //
@@ -60,6 +69,9 @@ message SpaceMember {
   dxos.keys.PublicKey space_key = 1;
   Role role = 2;
 
+  /// Immutable tags assigned at space creation time.
+  repeated string tags = 6;
+
   // TODO(burdon): Identity key?
   optional ProfileDocument profile = 3;
 
@@ -75,6 +87,15 @@ message MemberProfile {
   optional ProfileDocument profile = 3;
 }
 
+// [ASSERTION]: Space has been tombstoned (soft-deleted) by its owner.
+// Written to the identity's HALO so the deletion replicates across the user's devices.
+// A tombstone stops replication and unloads the space; data is not removed until garbage collection.
+message SpaceDeleted {
+  dxos.keys.PublicKey space_key = 1;
+  google.protobuf.Timestamp deleted_at = 2;
+  optional string reason = 3;
+}
+
 // [ASSERTION]: Device is authorized to sign messages for a given Agent (Identity).
 // NOTE: Devices are Admitted to Identities.
 message AuthorizedDevice {
@@ -163,6 +184,8 @@ enum DeviceType {
   UNKNOWN = 0;
   BROWSER = 1;
   NATIVE = 2;
+  // TODO(wittjosiah): Rename "agent" to avoid naming collision with AI agents.
+  // TODO(wittjosiah): Unknown, Browser, CLI, Desktop, Mobile, Custodian?
   AGENT = 3;
   AGENT_MANAGED = 4;
   MOBILE = 5;
@@ -188,6 +211,7 @@ message DeviceProfile {
 }
 
 /// [ASSERTION]: Sets default space for identity.
+/// @deprecated Default space is no longer managed by the SDK. Existing credentials are ignored.
 message DefaultSpace {
   string space_id = 1;
 }

package/src/proto/dxos/halo/invitations.proto

@@ -16,8 +16,11 @@ package dxos.halo.invitations;
 
 message InvitationOptions {
   enum Role {
-    GUEST = 0;
-    HOST = 1;
+    // Sentinel so neither real role is the proto3 default (which is stripped on the wire,
+    // causing the receiver to see `role === undefined` and reject with InvalidInvitationExtensionRoleError).
+    INVALID = 0;
+    GUEST = 1;
+    HOST = 2;
   }
 
   /// Role of the peer.

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.
@@ -39,6 +36,7 @@ message AppContextRequest {
   /// The key of the joined space.
   optional dxos.keys.PublicKey space_key = 2;
 
+  // TODO(wittjosiah): Make the generated type be `SpaceId`.
   /// The id of the joined space.
   optional string space_id = 5;