@dxos/echo-pipeline 0.4.9 → 0.4.10-main.06ef97a

package/dist/types/src/automerge/automerge-doc-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automerge-doc-loader.d.ts","sourceRoot":"","sources":["../../../../src/automerge/automerge-doc-loader.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAmB,KAAK,IAAI,EAAE,MAAM,gCAAgC,CAAC;AAC/G,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAGhE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEzD,KAAK,kBAAkB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;AAE5C,MAAM,WAAW,uBAAuB;IACtC,sBAAsB,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAEpD,aAAa,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEvC,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,qBAAqB,IAAI,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC7C,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC/D,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtD,uBAAuB,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7E;;OAEG;IACH,qBAAqB,IAAI,MAAM,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,2BAA4B,YAAW,uBAAuB;IAevE,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAfxB,OAAO,CAAC,mBAAmB,CAAoC;IAC/D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAA0C;IACjF;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAqB;IAEjE,SAAgB,sBAAsB,8BAAqC;gBAGxD,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,IAAI;IAG9B,aAAa,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE;IAIzB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjF,kBAAkB,CAAC,QAAQ,EAAE,MAAM;IAgBnC,oBAAoB,CAAC,KAAK,EAAE,kBAAkB;IAW9C,qBAAqB,IAAI,SAAS,CAAC,QAAQ,CAAC;IAK5C,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC;IAY9D,uBAAuB,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM;IAIrE,qBAAqB,IAAI,MAAM,EAAE;IAOxC,OAAO,CAAC,kBAAkB;YAyBZ,cAAc;IAyB5B,OAAO,CAAC,oCAAoC;IAS5C,OAAO,CAAC,cAAc;YAOR,2BAA2B;CA2B1C;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE;QACf,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;KAChC,CAAC;CACH"}

package/dist/types/src/automerge/automerge-doc-loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=automerge-doc-loader.test.d.ts.map

package/dist/types/src/automerge/automerge-doc-loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automerge-doc-loader.test.d.ts","sourceRoot":"","sources":["../../../../src/automerge/automerge-doc-loader.test.ts"],"names":[],"mappings":""}

package/dist/types/src/automerge/automerge-host.d.ts

@@ -1,7 +1,7 @@
 import { Repo, type DocumentId } from '@dxos/automerge/automerge-repo';
 import { type Stream } from '@dxos/codec-protobuf';
 import { PublicKey } from '@dxos/keys';
-import { type HostInfo, type SyncRepoRequest, type SyncRepoResponse } from '@dxos/protocols/proto/dxos/echo/service';
+import { type FlushRequest, type HostInfo, type SyncRepoRequest, type SyncRepoResponse } from '@dxos/protocols/proto/dxos/echo/service';
 import { type Directory } from '@dxos/random-access-storage';
 import { type AutomergeReplicator } from '@dxos/teleport-extension-automerge-replicator';
 export type { DocumentId };
@@ -34,6 +34,7 @@ export declare class AutomergeHost {
     private _automergeDocs;
     private _automergePeers;
     close(): Promise<void>;
+    flush({ documentIds }: FlushRequest): Promise<void>;
     syncRepo(request: SyncRepoRequest): Stream<SyncRepoResponse>;
     sendSyncMessage(request: SyncRepoRequest): Promise<void>;
     getHostInfo(): Promise<HostInfo>;

package/dist/types/src/automerge/automerge-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"automerge-host.d.ts","sourceRoot":"","sources":["../../../../src/automerge/automerge-host.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,IAAI,EAEJ,KAAK,UAAU,EAIhB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AACrH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AASzF,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,qBACa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IAGnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoE;IAEvG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAkB;IAEtC,cAAc,cAAqB;gBAE9B,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,mBAAmB;IAkFxD,IAAI,IAAI,IAAI,IAAI,CAEf;YAEa,WAAW;IAOzB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,eAAe;IAIjB,KAAK;IAUX,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAI5D,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAQtC,eAAe,IAAI,mBAAmB;IAItC,eAAe,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS;CAI1D;AAoBD,eAAO,MAAM,kBAAkB,QAAS,GAAG,KAAG,MAAM,GAAG,IAQtD,CAAC"}
+{"version":3,"file":"automerge-host.d.ts","sourceRoot":"","sources":["../../../../src/automerge/automerge-host.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,IAAI,EAEJ,KAAK,UAAU,EAIhB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AASzF,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B,CAAC;AAEF,qBACa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IAGnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoE;IAEvG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAkB;IAEtC,cAAc,cAAqB;gBAE9B,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,mBAAmB;IAmFxD,IAAI,IAAI,IAAI,IAAI,CAEf;YAEa,WAAW;IAOzB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,SAAS;IA8BjB,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,eAAe;IAIjB,KAAK;IAUL,KAAK,CAAC,EAAE,WAAW,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAI5D,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAQtC,eAAe,IAAI,mBAAmB;IAItC,eAAe,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS;CAI1D;AAoBD,eAAO,MAAM,kBAAkB,QAAS,GAAG,KAAG,MAAM,GAAG,IAQtD,CAAC"}

package/dist/types/src/automerge/index.d.ts

@@ -1,5 +1,8 @@
 export * from './automerge-host';
 export * from './automerge-storage-adapter';
+export * from './automerge-doc-loader';
 export * from './local-host-network-adapter';
 export * from './mesh-network-adapter';
+export * from './types';
+export * from './reference';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/automerge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/automerge/index.ts"],"names":[],"mappings":"AAIA,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/automerge/index.ts"],"names":[],"mappings":"AAIA,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC"}

package/dist/types/src/automerge/reference.d.ts

@@ -0,0 +1,15 @@
+import { Reference } from '@dxos/echo-db';
+export declare const REFERENCE_TYPE_TAG = "dxos.echo.model.document.Reference";
+/**
+ * Reference as it is stored in Automerge document.
+ */
+export type EncodedReferenceObject = {
+    '@type': typeof REFERENCE_TYPE_TAG;
+    itemId: string | null;
+    protocol: string | null;
+    host: string | null;
+};
+export declare const encodeReference: (reference: Reference) => EncodedReferenceObject;
+export declare const decodeReference: (value: any) => Reference;
+export declare const isEncodedReferenceObject: (value: any) => value is EncodedReferenceObject;
+//# sourceMappingURL=reference.d.ts.map

package/dist/types/src/automerge/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../src/automerge/reference.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,eAAO,MAAM,kBAAkB,uCAAuC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,kBAAkB,CAAC;IACnC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,eAAe,cAAe,SAAS,KAAG,sBAMrD,CAAC;AAEH,eAAO,MAAM,eAAe,UAAW,GAAG,cACyC,CAAC;AAEpF,eAAO,MAAM,wBAAwB,UAAW,GAAG,oCACmC,CAAC"}

package/dist/types/src/automerge/types.d.ts

@@ -0,0 +1,67 @@
+import { type EncodedReferenceObject } from './reference';
+export type SpaceState = {
+    rootUrl?: string;
+};
+export interface SpaceDoc {
+    access?: {
+        spaceKey: string;
+    };
+    /**
+     * Objects inlined in the current document.
+     */
+    objects?: {
+        [key: string]: ObjectStructure;
+    };
+    /**
+     * Object id points to an automerge doc url where the object is embedded.
+     */
+    links?: {
+        [echoId: string]: string;
+    };
+}
+/**
+ * Representation of an ECHO object in an AM document.
+ */
+export type ObjectStructure = {
+    data: Record<string, any>;
+    meta: ObjectMeta;
+    system: ObjectSystem;
+};
+/**
+ * Echo object metadata.
+ */
+export type ObjectMeta = {
+    /**
+     * Foreign keys.
+     */
+    keys: ForeignKey[];
+};
+/**
+ * Reference to an object in a foreign database.
+ */
+export type ForeignKey = {
+    /**
+     * Name of the foreign database/system.
+     * E.g. `github.com`.
+     */
+    source?: string;
+    /**
+     * Id within the foreign database.
+     */
+    id?: string;
+};
+/**
+ * Automerge object system properties.
+ * (Is automerge specific.)
+ */
+export type ObjectSystem = {
+    /**
+     * Deletion marker.
+     */
+    deleted?: boolean;
+    /**
+     * Object reference ('protobuf' protocol) type.
+     */
+    type?: EncodedReferenceObject;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/automerge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/automerge/types.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,MAAM,UAAU,GAAG;IAEvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAC;KAChC,CAAC;IACF;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,sBAAsB,CAAC;CAC/B,CAAC"}

package/dist/types/src/space/space.d.ts

@@ -1,5 +1,5 @@
 import { Event } from '@dxos/async';
-import { type Context } from '@dxos/context';
+import { Resource, type Context } from '@dxos/context';
 import { type FeedInfo } from '@dxos/credentials';
 import { type FeedOptions, type FeedWrapper } from '@dxos/feed-store';
 import { type PublicKey } from '@dxos/keys';
@@ -28,7 +28,7 @@ export type CreatePipelineParams = {
 /**
  * Spaces are globally addressable databases with access control.
  */
-export declare class Space {
+export declare class Space extends Resource {
     private readonly _addFeedMutex;
     readonly onCredentialProcessed: Callback<AsyncCallback<Credential>>;
     readonly stateUpdate: Event<void>;
@@ -38,7 +38,6 @@ export declare class Space {
     private readonly _feedProvider;
     private readonly _controlPipeline;
     private readonly _snapshotManager;
-    private _isOpen;
     private _controlFeed?;
     private _dataFeed?;
     constructor(params: SpaceParams);
@@ -59,11 +58,8 @@ export declare class Space {
      * Use for diagnostics.
      */
     getControlFeeds(): FeedInfo[];
-    /**
-     * Use for diagnostics.
-     */
-    open(ctx: Context): Promise<void>;
-    close(): Promise<void>;
+    protected _open(ctx: Context): Promise<void>;
+    protected _close(): Promise<void>;
 }
 export {};
 //# sourceMappingURL=space.d.ts.map

package/dist/types/src/space/space.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../../../../src/space/space.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAmC,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACxE,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;AAElG,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACtC,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,SAAS,EAAE,SAAS,CAAC;IAGrB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,SAAS,CAAC;CAElB,CAAC;AAEF;;GAEG;AAEH,qBAEa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAE7C,SAAgB,qBAAqB,sCAA6C;IAClF,SAAgB,WAAW,cAAe;IAC1C,SACgB,QAAQ,EAAE,aAAa,CAAC;IAExC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAE7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IAEnD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IAEnD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAA2B;IAChD,OAAO,CAAC,SAAS,CAAC,CAA2B;gBAEjC,MAAM,EAAE,WAAW;IAqC/B,IAEI,GAAG,cAEN;IAED,IAAI,MAAM,YAET;IAED,IAAI,cAAc,IAAI,SAAS,CAE9B;IAED,IAAI,cAAc,0BAEjB;IAED,IAAI,WAAW,0BAEd;IAED,IAAI,UAAU,2CAEb;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,gBAAgB,CAEtC;IAED,IAAI,eAAe,IAAI,eAAe,CAErC;IAEK,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;IAO7C,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;IAMhD;;OAEG;IACH,eAAe,IAAI,QAAQ,EAAE;IAI7B;;OAEG;IAMG,IAAI,CAAC,GAAG,EAAE,OAAO;IAejB,KAAK;CAaZ"}
+{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../../../../src/space/space.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAmC,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAkB,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACxE,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,6CAA6C,CAAC;AAC5F,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;AAElG,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACtC,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,SAAS,EAAE,SAAS,CAAC;IAGrB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,SAAS,CAAC;CAElB,CAAC;AAEF;;GAEG;AAEH,qBAEa,KAAM,SAAQ,QAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAE7C,SAAgB,qBAAqB,sCAA6C;IAClF,SAAgB,WAAW,cAAe;IAC1C,SACgB,QAAQ,EAAE,aAAa,CAAC;IAExC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAE7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IAEnD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkB;IAEnD,OAAO,CAAC,YAAY,CAAC,CAA2B;IAChD,OAAO,CAAC,SAAS,CAAC,CAA2B;gBAEjC,MAAM,EAAE,WAAW;IAsC/B,IAEI,GAAG,cAEN;IAED,IAAI,MAAM,YAET;IAED,IAAI,cAAc,IAAI,SAAS,CAE9B;IAED,IAAI,cAAc,0BAEjB;IAED,IAAI,WAAW,0BAEd;IAED,IAAI,UAAU,2CAEb;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,gBAAgB,CAEtC;IAED,IAAI,eAAe,IAAI,eAAe,CAErC;IAEK,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;IAO7C,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC;IAMhD;;OAEG;IACH,eAAe,IAAI,QAAQ,EAAE;cAKJ,KAAK,CAAC,GAAG,EAAE,OAAO;cAWlB,MAAM;CAShC"}

package/dist/types/src/testing/test-agent-builder.d.ts

@@ -26,7 +26,7 @@ export declare class TestAgentBuilder {
     private readonly _storage;
     private readonly _networkManagerProvider;
     constructor({ storage, networkManagerProvider }?: TestAgentBuilderOptions);
-    close(): Promise<void[][]>;
+    close(): Promise<Space[][]>;
     get agents(): TestAgent[];
     getAgent(deviceKey: PublicKey): TestAgent | undefined;
     createPeer(): Promise<TestAgent>;
@@ -50,7 +50,7 @@ export declare class TestAgent {
     private _blobStore?;
     get blobStore(): BlobStore;
     constructor(_networkManagerProvider: NetworkManagerProvider, _feedBuilder: TestFeedBuilder, identityKey: PublicKey, deviceKey: PublicKey);
-    close(): Promise<void[]>;
+    close(): Promise<Space[]>;
     get spaces(): Space[];
     getSpace(spaceKey: PublicKey): Space | undefined;
     private _spaceManager?;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-pipeline",
-  "version": "0.4.9",
+  "version": "0.4.10-main.06ef97a",
   "description": "ECHO database.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -36,35 +36,35 @@
   ],
   "dependencies": {
     "crc-32": "^1.2.2",
-    "@dxos/automerge": "0.4.9",
-    "@dxos/codec-protobuf": "0.4.9",
-    "@dxos/async": "0.4.9",
-    "@dxos/context": "0.4.9",
-    "@dxos/credentials": "0.4.9",
-    "@dxos/debug": "0.4.9",
-    "@dxos/crypto": "0.4.9",
-    "@dxos/echo-db": "0.4.9",
-    "@dxos/feed-store": "0.4.9",
-    "@dxos/hypercore": "0.4.9",
-    "@dxos/keyring": "0.4.9",
-    "@dxos/invariant": "0.4.9",
-    "@dxos/messaging": "0.4.9",
-    "@dxos/log": "0.4.9",
-    "@dxos/keys": "0.4.9",
-    "@dxos/network-manager": "0.4.9",
-    "@dxos/node-std": "0.4.9",
-    "@dxos/protocols": "0.4.9",
-    "@dxos/rpc": "0.4.9",
-    "@dxos/random-access-storage": "0.4.9",
-    "@dxos/teleport": "0.4.9",
-    "@dxos/teleport-extension-automerge-replicator": "0.4.9",
-    "@dxos/teleport-extension-gossip": "0.4.9",
-    "@dxos/teleport-extension-object-sync": "0.4.9",
-    "@dxos/timeframe": "0.4.9",
-    "@dxos/teleport-extension-replicator": "0.4.9",
-    "@dxos/tracing": "0.4.9",
-    "@dxos/typings": "0.4.9",
-    "@dxos/util": "0.4.9"
+    "@dxos/async": "0.4.10-main.06ef97a",
+    "@dxos/codec-protobuf": "0.4.10-main.06ef97a",
+    "@dxos/automerge": "0.4.10-main.06ef97a",
+    "@dxos/context": "0.4.10-main.06ef97a",
+    "@dxos/credentials": "0.4.10-main.06ef97a",
+    "@dxos/crypto": "0.4.10-main.06ef97a",
+    "@dxos/echo-db": "0.4.10-main.06ef97a",
+    "@dxos/debug": "0.4.10-main.06ef97a",
+    "@dxos/feed-store": "0.4.10-main.06ef97a",
+    "@dxos/invariant": "0.4.10-main.06ef97a",
+    "@dxos/hypercore": "0.4.10-main.06ef97a",
+    "@dxos/keyring": "0.4.10-main.06ef97a",
+    "@dxos/keys": "0.4.10-main.06ef97a",
+    "@dxos/messaging": "0.4.10-main.06ef97a",
+    "@dxos/network-manager": "0.4.10-main.06ef97a",
+    "@dxos/log": "0.4.10-main.06ef97a",
+    "@dxos/node-std": "0.4.10-main.06ef97a",
+    "@dxos/random-access-storage": "0.4.10-main.06ef97a",
+    "@dxos/rpc": "0.4.10-main.06ef97a",
+    "@dxos/protocols": "0.4.10-main.06ef97a",
+    "@dxos/teleport": "0.4.10-main.06ef97a",
+    "@dxos/teleport-extension-gossip": "0.4.10-main.06ef97a",
+    "@dxos/teleport-extension-automerge-replicator": "0.4.10-main.06ef97a",
+    "@dxos/teleport-extension-object-sync": "0.4.10-main.06ef97a",
+    "@dxos/teleport-extension-replicator": "0.4.10-main.06ef97a",
+    "@dxos/tracing": "0.4.10-main.06ef97a",
+    "@dxos/util": "0.4.10-main.06ef97a",
+    "@dxos/timeframe": "0.4.10-main.06ef97a",
+    "@dxos/typings": "0.4.10-main.06ef97a"
   },
   "devDependencies": {
     "fast-check": "^3.15.1",

package/src/automerge/automerge-doc-loader.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { expect } from 'chai';
+
+import { sleep } from '@dxos/async';
+import { Repo } from '@dxos/automerge/automerge-repo';
+import { Context } from '@dxos/context';
+import { PublicKey } from '@dxos/keys';
+import { describe, test } from '@dxos/test';
+
+import {
+  type AutomergeDocumentLoader,
+  AutomergeDocumentLoaderImpl,
+  type ObjectDocumentLoaded,
+} from './automerge-doc-loader';
+import { type SpaceDoc } from './types';
+
+const ctx = new Context();
+const SPACE_KEY = PublicKey.random();
+const randomId = () => PublicKey.random().toHex();
+describe('AutomergeDocumentLoader', () => {
+  test('space access is set on root doc handle and it is accessible', async () => {
+    const { loader, spaceRootDocHandle } = await setupTest();
+    expect(loader.getSpaceRootDocHandle()).not.to.throw;
+    expect(spaceRootDocHandle.docSync()?.access?.spaceKey).to.eq(SPACE_KEY.toHex());
+  });
+
+  test('new object document is linked with space and root document', async () => {
+    const objectId = randomId();
+    const { loader, spaceRootDocHandle } = await setupTest();
+    const objectDocHandle = loader.createDocumentForObject(objectId);
+    const handle = spaceRootDocHandle.docSync();
+    expect(objectDocHandle.docSync()?.access?.spaceKey).to.eq(SPACE_KEY.toHex());
+    expect(handle?.links[objectId]).to.eq(objectDocHandle.url);
+  });
+
+  test('listener is invoked after a document is loaded', async () => {
+    const objectId = randomId();
+    const { loader, repo } = await setupTest();
+    const handle = repo.create<SpaceDoc>();
+    const docLoadInfo = waitForDocumentLoad(loader, { objectId, handle });
+    loadLinkedObjects(loader, { [objectId]: handle.url });
+    await sleep(10);
+    expect(docLoadInfo.loaded).to.be.true;
+  });
+
+  test('listener is not invoked if an object was rebound during document loading', async () => {
+    const objectId = randomId();
+    const { loader, repo } = await setupTest();
+    const oldDocHandle = repo.create<SpaceDoc>();
+    const newDocHandle = repo.create<SpaceDoc>();
+    const docLoadInfo = waitForDocumentLoad(loader, { objectId, handle: oldDocHandle });
+    loadLinkedObjects(loader, { [objectId]: oldDocHandle.url });
+    loader.onObjectBoundToDocument(newDocHandle, objectId);
+    await sleep(10);
+    expect(docLoadInfo.loaded).to.be.false;
+  });
+
+  test('document link is not loaded if object exists as inline object', async () => {
+    const objectId = randomId();
+    const { loader, repo } = await setupTest();
+    const existingHandle = repo.create<SpaceDoc>();
+    loader.onObjectBoundToDocument(existingHandle, objectId);
+    const newDocHandle = repo.create<SpaceDoc>();
+    const docLoadInfo = waitForDocumentLoad(loader, { objectId, handle: newDocHandle });
+    loadLinkedObjects(loader, { [objectId]: existingHandle.url });
+    await sleep(10);
+    expect(docLoadInfo.loaded).to.be.false;
+  });
+
+  const setupTest = async () => {
+    const repo = new Repo({ network: [] });
+    const loader = new AutomergeDocumentLoaderImpl(SPACE_KEY, repo);
+    const spaceRootDocHandle = repo.create<SpaceDoc>();
+    await loader.loadSpaceRootDocHandle(ctx, {
+      rootUrl: spaceRootDocHandle.url,
+    });
+    return { loader, spaceRootDocHandle, repo };
+  };
+
+  const loadLinkedObjects = (loader: AutomergeDocumentLoader, links: SpaceDoc['links']) => {
+    Object.keys(links ?? {}).forEach((objectId) => loader.loadObjectDocument(objectId));
+    loader.onObjectLinksUpdated(links);
+  };
+
+  const waitForDocumentLoad = (loader: AutomergeDocumentLoader, expected: ObjectDocumentLoaded) => {
+    const docLoadInfo = { loaded: false };
+    loader.onObjectDocumentLoaded.on((data) => {
+      expect(data.objectId).to.eq(expected.objectId);
+      expect(data.handle.url).to.eq(expected.handle.url);
+      docLoadInfo.loaded = true;
+    });
+    return docLoadInfo;
+  };
+});

package/src/automerge/automerge-doc-loader.ts

@@ -0,0 +1,241 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Event } from '@dxos/async';
+import { type DocHandle, type AutomergeUrl, type DocumentId, type Repo } from '@dxos/automerge/automerge-repo';
+import { cancelWithContext, type Context } from '@dxos/context';
+import { warnAfterTimeout } from '@dxos/debug';
+import { invariant } from '@dxos/invariant';
+import { type PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { type SpaceState, type SpaceDoc } from './types';
+
+type SpaceDocumentLinks = SpaceDoc['links'];
+
+export interface AutomergeDocumentLoader {
+  onObjectDocumentLoaded: Event<ObjectDocumentLoaded>;
+
+  getAllHandles(): DocHandle<SpaceDoc>[];
+
+  loadSpaceRootDocHandle(ctx: Context, spaceState: SpaceState): Promise<void>;
+  loadObjectDocument(objectId: string): void;
+  getSpaceRootDocHandle(): DocHandle<SpaceDoc>;
+  createDocumentForObject(objectId: string): DocHandle<SpaceDoc>;
+  onObjectLinksUpdated(links: SpaceDocumentLinks): void;
+  onObjectBoundToDocument(handle: DocHandle<SpaceDoc>, objectId: string): void;
+
+  /**
+   * @returns objectIds for which we had document handles or were loading one.
+   */
+  clearHandleReferences(): string[];
+}
+
+/**
+ * Manages object <-> docHandle binding and automerge document loading.
+ */
+export class AutomergeDocumentLoaderImpl implements AutomergeDocumentLoader {
+  private _spaceRootDocHandle: DocHandle<SpaceDoc> | null = null;
+  /**
+   * An object id pointer to a handle of the document where the object is stored inline.
+   */
+  private readonly _objectDocumentHandles = new Map<string, DocHandle<SpaceDoc>>();
+  /**
+   * If object was requested via loadObjectDocument but root document links weren't updated yet
+   * loading will be triggered in onObjectLinksUpdated callback.
+   */
+  private readonly _objectsPendingDocumentLoad = new Set<string>();
+
+  public readonly onObjectDocumentLoaded = new Event<ObjectDocumentLoaded>();
+
+  constructor(
+    private readonly _spaceKey: PublicKey,
+    private readonly _repo: Repo,
+  ) {}
+
+  getAllHandles(): DocHandle<SpaceDoc>[] {
+    return [...new Set(this._objectDocumentHandles.values())];
+  }
+
+  public async loadSpaceRootDocHandle(ctx: Context, spaceState: SpaceState): Promise<void> {
+    if (this._spaceRootDocHandle != null) {
+      return;
+    }
+    if (!spaceState.rootUrl) {
+      log.error('Database opened with no rootUrl', { spaceKey: this._spaceKey });
+      this._createContextBoundSpaceRootDocument(ctx);
+    } else {
+      const existingDocHandle = await this._initDocHandle(ctx, spaceState.rootUrl);
+      const doc = existingDocHandle.docSync();
+      invariant(doc);
+      if (doc.access == null) {
+        this._initDocAccess(existingDocHandle);
+      }
+      this._spaceRootDocHandle = existingDocHandle;
+    }
+  }
+
+  public loadObjectDocument(objectId: string) {
+    invariant(this._spaceRootDocHandle);
+    if (this._objectDocumentHandles.has(objectId) || this._objectsPendingDocumentLoad.has(objectId)) {
+      return;
+    }
+    const spaceRootDoc = this._spaceRootDocHandle.docSync();
+    invariant(spaceRootDoc);
+    const documentUrl = (spaceRootDoc.links ?? {})[objectId];
+    if (documentUrl == null) {
+      this._objectsPendingDocumentLoad.add(objectId);
+      log.info('loading delayed until object links are initialized', { objectId });
+      return;
+    }
+    this._loadLinkedObjects({ [objectId]: documentUrl });
+  }
+
+  public onObjectLinksUpdated(links: SpaceDocumentLinks) {
+    if (!links) {
+      return;
+    }
+    const linksAwaitingLoad = Object.entries(links).filter(([objectId]) =>
+      this._objectsPendingDocumentLoad.has(objectId),
+    );
+    this._loadLinkedObjects(Object.fromEntries(linksAwaitingLoad));
+    linksAwaitingLoad.forEach(([objectId]) => this._objectsPendingDocumentLoad.delete(objectId));
+  }
+
+  public getSpaceRootDocHandle(): DocHandle<SpaceDoc> {
+    invariant(this._spaceRootDocHandle);
+    return this._spaceRootDocHandle;
+  }
+
+  public createDocumentForObject(objectId: string): DocHandle<SpaceDoc> {
+    invariant(this._spaceRootDocHandle);
+    const spaceDocHandle = this._repo.create<SpaceDoc>();
+    this._initDocAccess(spaceDocHandle);
+    this.onObjectBoundToDocument(spaceDocHandle, objectId);
+    this._spaceRootDocHandle.change((newDoc: SpaceDoc) => {
+      newDoc.links ??= {};
+      newDoc.links[objectId] = spaceDocHandle.url;
+    });
+    return spaceDocHandle;
+  }
+
+  public onObjectBoundToDocument(handle: DocHandle<SpaceDoc>, objectId: string) {
+    this._objectDocumentHandles.set(objectId, handle);
+  }
+
+  public clearHandleReferences(): string[] {
+    const objectsWithHandles = [...this._objectDocumentHandles.keys()];
+    this._objectDocumentHandles.clear();
+    this._spaceRootDocHandle = null;
+    return objectsWithHandles;
+  }
+
+  private _loadLinkedObjects(links: SpaceDocumentLinks) {
+    if (!links) {
+      return;
+    }
+    for (const [objectId, automergeUrl] of Object.entries(links)) {
+      const logMeta = { objectId, automergeUrl };
+      const objectDocumentHandle = this._objectDocumentHandles.get(objectId);
+      if (objectDocumentHandle != null && objectDocumentHandle.url !== automergeUrl) {
+        log.warn('object already inlined in a different document, ignoring the link', {
+          ...logMeta,
+          actualDocumentUrl: objectDocumentHandle.url,
+        });
+        continue;
+      }
+      if (objectDocumentHandle?.url === automergeUrl) {
+        log.warn('object document was already loaded', logMeta);
+        continue;
+      }
+      const handle = this._repo.find<SpaceDoc>(automergeUrl as DocumentId);
+      log.debug('document loading triggered', logMeta);
+      this._objectDocumentHandles.set(objectId, handle);
+      void this._createObjectOnDocumentLoad(handle, objectId);
+    }
+  }
+
+  private async _initDocHandle(ctx: Context, url: string) {
+    const docHandle = this._repo.find<SpaceDoc>(url as DocumentId);
+    while (true) {
+      try {
+        await warnAfterTimeout(5_000, 'Automerge root doc load timeout (AutomergeDb)', async () => {
+          await cancelWithContext(ctx, docHandle.whenReady()); // TODO(dmaretskyi): Temporary 5s timeout for debugging.
+        });
+        break;
+      } catch (err) {
+        if (`${err}`.includes('Timeout')) {
+          log.info('wraparound', { id: docHandle.documentId, state: docHandle.state });
+          continue;
+        }
+
+        throw err;
+      }
+    }
+
+    if (docHandle.state === 'unavailable') {
+      throw new Error('Automerge document is unavailable');
+    }
+
+    return docHandle;
+  }
+
+  private _createContextBoundSpaceRootDocument(ctx: Context) {
+    const docHandle = this._repo.create<SpaceDoc>();
+    this._spaceRootDocHandle = docHandle;
+    ctx.onDispose(() => {
+      docHandle.delete();
+      this._spaceRootDocHandle = null;
+    });
+  }
+
+  private _initDocAccess(handle: DocHandle<SpaceDoc>) {
+    handle.change((newDoc: SpaceDoc) => {
+      newDoc.access ??= { spaceKey: this._spaceKey.toHex() };
+      newDoc.access.spaceKey = this._spaceKey.toHex();
+    });
+  }
+
+  private async _createObjectOnDocumentLoad(handle: DocHandle<SpaceDoc>, objectId: string) {
+    try {
+      await handle.doc(['ready']);
+      const logMeta = { objectId, docUrl: handle.url };
+      if (this.onObjectDocumentLoaded.listenerCount() === 0) {
+        log.info('document loaded after all listeners were removed', logMeta);
+        return;
+      }
+      const objectDocHandle = this._objectDocumentHandles.get(objectId);
+      if (objectDocHandle?.url !== handle.url) {
+        log.warn('object was rebound while a document was loading, discarding handle', logMeta);
+        return;
+      }
+      this.onObjectDocumentLoaded.emit({ handle, objectId });
+    } catch (err) {
+      const shouldRetryLoading = this.onObjectDocumentLoaded.listenerCount() > 0;
+      log.warn('failed to load a document', {
+        objectId,
+        automergeUrl: handle.url,
+        retryLoading: shouldRetryLoading,
+        err,
+      });
+      if (shouldRetryLoading) {
+        await this._createObjectOnDocumentLoad(handle, objectId);
+      }
+    }
+  }
+}
+
+export interface ObjectDocumentLoaded {
+  handle: DocHandle<SpaceDoc>;
+  objectId: string;
+}
+
+export interface DocumentChanges {
+  createdObjectIds: string[];
+  updatedObjectIds: string[];
+  objectsToRebind: string[];
+  linkedDocuments: {
+    [echoId: string]: AutomergeUrl;
+  };
+}