@dxos/client-services 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/packlets/invitations/invitations-service.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import { Stream } from '@dxos/codec-protobuf/stream';
+import { type RequestOptions, Stream } from '@dxos/codec-protobuf';
 import {
   type AcceptInvitationRequest,
   type AuthenticationRequest,
@@ -27,23 +27,23 @@ export class InvitationsServiceImpl implements InvitationsService {
     };
   }
 
-  createInvitation(options: Invitation): Stream<Invitation> {
+  createInvitation(request: Invitation, options?: RequestOptions): Stream<Invitation> {
     return new Stream<Invitation>(({ ctx, next, close }) => {
       void this._invitationsManager
-        .createInvitation(ctx, options)
+        .createInvitation(ctx, request)
         .then((invitation) => {
           trace.metrics.increment('dxos.invitation.created');
           invitation.subscribe(next, close, close);
         })
         .catch(close);
-    });
+    }, options?.ctx);
   }
 
-  acceptInvitation(request: AcceptInvitationRequest): Stream<Invitation> {
+  acceptInvitation(request: AcceptInvitationRequest, options?: RequestOptions): Stream<Invitation> {
     return new Stream<Invitation>(({ ctx, next, close }) => {
       const invitation = this._invitationsManager.acceptInvitation(ctx, request);
       invitation.subscribe(next, close, close);
-    });
+    }, options?.ctx);
   }
 
   async authenticate(request: AuthenticationRequest): Promise<void> {

package/src/packlets/invitations/space-invitation-protocol.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Context } from '@dxos/context';
+import { type Context } from '@dxos/context';
 import {
   createCancelDelegatedSpaceInvitationCredential,
   createDelegatedSpaceInvitationCredential,
@@ -170,7 +170,7 @@ export class SpaceInvitationProtocol implements InvitationProtocol {
     };
   }
 
-  async accept(response: AdmissionResponse): Promise<Partial<Invitation>> {
+  async accept(ctx: Context, response: AdmissionResponse): Promise<Partial<Invitation>> {
     invariant(response.space);
     const { credential, controlTimeframe, dataTimeframe } = response.space;
     const assertion = getCredentialAssertion(credential);
@@ -182,7 +182,7 @@ export class SpaceInvitationProtocol implements InvitationProtocol {
     }
 
     // Create local space.
-    await this._spaceManager.acceptSpace(Context.default(), {
+    await this._spaceManager.acceptSpace(ctx, {
       spaceKey: assertion.spaceKey,
       genesisFeedKey: assertion.genesisFeedKey,
       controlTimeframe,

package/src/packlets/logging/logging-service.ts

@@ -5,13 +5,7 @@
 import { Event } from '@dxos/async';
 import { Stream } from '@dxos/codec-protobuf/stream';
 import { PublicKey } from '@dxos/keys';
-import {
-  type LogLevel,
-  type LogProcessor,
-  type LogEntry as NaturalLogEntry,
-  getContextFromEntry,
-  log,
-} from '@dxos/log';
+import { type LogLevel, type LogProcessor, type LogEntry as NaturalLogEntry, log } from '@dxos/log';
 import {
   type ControlMetricsRequest,
   type ControlMetricsResponse,
@@ -22,7 +16,7 @@ import {
   type QueryMetricsRequest,
   type QueryMetricsResponse,
 } from '@dxos/protocols/proto/dxos/client/services';
-import { getDebugName, jsonify, numericalValues, tracer } from '@dxos/util';
+import { numericalValues, tracer } from '@dxos/util';
 
 /**
  * Logging service used to spy on logs of the host.
@@ -114,19 +108,25 @@ export class LoggingServiceImpl implements LoggingService {
           return;
         }
 
+        const { filename, line, context: scopeName } = entry.computedMeta;
+        const recordContext: Record<string, any> = { ...entry.computedContext };
+        if (entry.computedError !== undefined) {
+          recordContext.error = entry.computedError;
+        }
+
         const record: LogEntry = {
-          ...entry,
-          message: entry.message ?? (entry.error ? (entry.error.message ?? String(entry.error)) : ''),
-          context: jsonify(getContextFromEntry(entry)),
-          timestamp: new Date(),
+          level: entry.level,
+          message: entry.message ?? entry.computedError ?? '',
+          context: recordContext,
+          timestamp: new Date(entry.timestamp),
           meta: {
             // TODO(dmaretskyi): Fix proto.
-            file: entry.meta?.F ?? '',
-            line: entry.meta?.L ?? 0,
+            file: filename ?? '',
+            line: line ?? 0,
             scope: {
               hostSessionId: this._sessionId,
               uptimeSeconds: (Date.now() - this._started) / 1000,
-              name: getDebugName(entry.meta?.S),
+              name: scopeName ?? '',
             },
           },
         };

package/src/packlets/network/network-service.ts

@@ -2,6 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
+import { type RequestOptions } from '@dxos/codec-protobuf';
 import { Stream } from '@dxos/codec-protobuf/stream';
 import { Context } from '@dxos/context';
 import { type EdgeConnection } from '@dxos/edge-client';
@@ -48,16 +49,16 @@ export class NetworkServiceImpl implements NetworkService {
     await this.networkManager.setConnectionState(request.swarm);
   }
 
-  async joinSwarm(request: JoinRequest): Promise<void> {
-    return this.signalManager.join(Context.default(), request);
+  async joinSwarm(request: JoinRequest, options?: RequestOptions): Promise<void> {
+    return this.signalManager.join(options?.ctx ?? Context.default(), request);
   }
 
-  async leaveSwarm(request: LeaveRequest): Promise<void> {
-    return this.signalManager.leave(Context.default(), request);
+  async leaveSwarm(request: LeaveRequest, options?: RequestOptions): Promise<void> {
+    return this.signalManager.leave(options?.ctx ?? Context.default(), request);
   }
 
-  async querySwarm(request: QueryRequest): Promise<SwarmResponse> {
-    return this.signalManager.query(Context.default(), request);
+  async querySwarm(request: QueryRequest, options?: RequestOptions): Promise<SwarmResponse> {
+    return this.signalManager.query(options?.ctx ?? Context.default(), request);
   }
 
   subscribeSwarmState(request: SubscribeSwarmStateRequest): Stream<SwarmResponse> {
@@ -70,8 +71,8 @@ export class NetworkServiceImpl implements NetworkService {
     });
   }
 
-  async sendMessage(message: Message): Promise<void> {
-    return this.signalManager.sendMessage(Context.default(), message);
+  async sendMessage(message: Message, options?: RequestOptions): Promise<void> {
+    return this.signalManager.sendMessage(options?.ctx ?? Context.default(), message);
   }
 
   subscribeMessages(peer: Peer): Stream<Message> {

package/src/packlets/services/client-rpc-server.ts

@@ -3,7 +3,7 @@
 //
 
 import { type ClientServices } from '@dxos/client-protocol';
-import { type Any, type ServiceHandler, Stream } from '@dxos/codec-protobuf';
+import { type Any, type RequestOptions, type ServiceHandler, Stream } from '@dxos/codec-protobuf';
 import { raise } from '@dxos/debug';
 import { RpcPeer, type RpcPeerOptions, type ServiceBundle, parseMethodName } from '@dxos/rpc';
 import { MapCounter, trace } from '@dxos/tracing';
@@ -16,12 +16,14 @@ export type ClientRpcServerProps = {
   handleCall?: (
     method: string,
     params: Any,
-    handler: (method: string, params: Any) => MaybePromise<Any>,
+    handler: (method: string, params: Any, options?: RequestOptions) => MaybePromise<Any>,
+    options?: RequestOptions,
   ) => Promise<Any>;
   handleStream?: (
     method: string,
     params: Any,
-    handler: (method: string, params: Any) => Stream<Any>,
+    handler: (method: string, params: Any, options?: RequestOptions) => Stream<Any>,
+    options?: RequestOptions,
   ) => MaybePromise<Stream<Any>>;
 } & Omit<RpcPeerOptions, 'callHandler' | 'streamHandler'>;
 
@@ -49,32 +51,33 @@ export class ClientRpcServer {
     this._serviceRegistry = serviceRegistry;
     this._rpcPeer = new RpcPeer({
       ...rpcOptions,
-      callHandler: (method, params) => {
+      callHandler: (method, params, options) => {
         const [serviceName, methodName] = parseMethodName(method);
-        const handler = (method: string, params: Any) => this._getServiceHandler(serviceName).call(method, params);
+        const handler = (method: string, params: Any, handlerOptions?: RequestOptions) =>
+          this._getServiceHandler(serviceName).call(method, params, handlerOptions);
 
         this._callMetrics.inc(`${serviceName}.${methodName} request`);
 
         if (this._handleCall) {
-          return this._handleCall(methodName, params, handler);
+          return this._handleCall(methodName, params, handler, options);
         } else {
-          return handler(methodName, params);
+          return handler(methodName, params, options);
         }
       },
-      streamHandler: (method, params) => {
+      streamHandler: (method, params, options) => {
         const [serviceName, methodName] = parseMethodName(method);
-        const handler = (method: string, params: Any) =>
-          this._getServiceHandler(serviceName).callStream(method, params);
+        const handler = (method: string, params: Any, handlerOptions?: RequestOptions) =>
+          this._getServiceHandler(serviceName).callStream(method, params, handlerOptions);
 
         this._callMetrics.inc(`${serviceName}.${methodName} request stream`);
 
         if (this._handleStream) {
-          return Stream.map(Stream.unwrapPromise(this._handleStream(methodName, params, handler)), (data) => {
+          return Stream.map(Stream.unwrapPromise(this._handleStream(methodName, params, handler, options)), (data) => {
             this._callMetrics.inc(`${serviceName}.${methodName} response stream`);
             return data;
           });
         } else {
-          return handler(methodName, params);
+          return handler(methodName, params, options);
         }
       },
     });

package/src/packlets/services/service-context.ts

@@ -22,12 +22,12 @@ import { type RuntimeProvider } from '@dxos/effect';
 import { FeedFactory, FeedStore } from '@dxos/feed-store';
 import { invariant } from '@dxos/invariant';
 import { Keyring } from '@dxos/keyring';
-import { PublicKey, type SpaceId } from '@dxos/keys';
+import { type SpaceId } from '@dxos/keys';
 import { type LevelDB } from '@dxos/kv-store';
 import { log } from '@dxos/log';
 import { type SignalManager } from '@dxos/messaging';
 import { type SwarmNetworkManager } from '@dxos/network-manager';
-import { InvalidStorageVersionError, STORAGE_VERSION, trace } from '@dxos/protocols';
+import { InvalidStorageVersionError, STORAGE_VERSION } from '@dxos/protocols';
 import { FeedProtocol } from '@dxos/protocols';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type Runtime } from '@dxos/protocols/proto/dxos/config';
@@ -74,7 +74,7 @@ export type ServiceContextRuntimeProps = Pick<
 // TODO(burdon): Rename/break-up into smaller components. And/or make members private.
 // TODO(dmaretskyi): Gets duplicated in CJS build between normal and testing bundles.
 @safeInstanceof('dxos.client-services.ServiceContext')
-@Trace.resource()
+@Trace.resource({ lifecycle: true })
 export class ServiceContext extends Resource {
   private readonly _edgeIdentityUpdateMutex = new Mutex();
 
@@ -104,8 +104,6 @@ export class ServiceContext extends Resource {
 
   private _deviceSpaceSync?: CredentialProcessor;
 
-  private readonly _instanceId = PublicKey.random().toHex();
-
   constructor(
     public readonly storage: Storage,
     public readonly level: LevelDB,
@@ -224,12 +222,11 @@ export class ServiceContext extends Resource {
     }
   }
 
-  @Trace.span()
+  @Trace.span({ op: 'lifecycle' })
   protected override async _open(ctx: Context): Promise<void> {
     await this._checkStorageVersion();
 
     log('opening...');
-    log.trace('dxos.sdk.service-context.open', trace.begin({ id: this._instanceId }));
 
     log('opening identityManager...');
     await this.identityManager.open(ctx);
@@ -240,11 +237,11 @@ export class ServiceContext extends Resource {
     log('network identity set');
 
     log('opening edge connection...');
-    await this._edgeConnection?.open();
+    await this._edgeConnection?.open(ctx);
     log('edge connection opened');
 
     log('opening signal manager...');
-    await this.signalManager.open();
+    await this.signalManager.open(ctx);
     log('signal manager opened');
 
     log('opening network manager...');
@@ -287,14 +284,13 @@ export class ServiceContext extends Resource {
     }
 
     log('opening feed syncer...');
-    await this._feedSyncer?.open();
+    await this._feedSyncer?.open(ctx);
     log('feed syncer opened');
 
     log('loading persistent invitations...');
     const loadedInvitations = await this.invitationsManager.loadPersistentInvitations(ctx);
     log('loaded persistent invitations', { count: loadedInvitations.invitations?.length });
 
-    log.trace('dxos.sdk.service-context.open', trace.end({ id: this._instanceId }));
     log('opened');
   }
 
@@ -321,8 +317,8 @@ export class ServiceContext extends Resource {
     log('closed');
   }
 
-  async createIdentity(params: CreateIdentityOptions = {}) {
-    const ctx = Context.default();
+  async createIdentity(params: CreateIdentityOptions = {}, ctx?: Context) {
+    ctx ??= this._ctx;
     const identity = await this.identityManager.createIdentity(params, ctx);
     await this._setNetworkIdentity({ identity });
     await identity.joinNetwork(ctx);
@@ -398,7 +394,7 @@ export class ServiceContext extends Resource {
       edgeFeatures: this._edgeFeatures,
     });
     log('_initialize: opening DataSpaceManager...');
-    await this.dataSpaceManager.open();
+    await this.dataSpaceManager.open(ctx);
     log('_initialize: DataSpaceManager opened');
 
     this.edgeAgentManager = new EdgeAgentManager(
@@ -408,7 +404,7 @@ export class ServiceContext extends Resource {
       identity,
     );
     log('_initialize: opening EdgeAgentManager...');
-    await this.edgeAgentManager.open();
+    await this.edgeAgentManager.open(ctx);
     log('_initialize: EdgeAgentManager opened');
 
     this._handlerFactories.set(Invitation.Kind.SPACE, (invitation) => {
@@ -442,6 +438,7 @@ export class ServiceContext extends Resource {
           await this.dataSpaceManager.acceptSpace(this._ctx, {
             spaceKey: assertion.spaceKey,
             genesisFeedKey: assertion.genesisFeedKey,
+            tags: assertion.tags,
           });
         } catch (err) {
           log.catch(err);

package/src/packlets/services/service-host.ts

@@ -7,12 +7,11 @@ import * as Effect from 'effect/Effect';
 
 import { Event, synchronized } from '@dxos/async';
 import { type ClientServices, clientServiceBundle } from '@dxos/client-protocol';
-import { type Config } from '@dxos/config';
+import { type Config, resolveTelemetryTag } from '@dxos/config';
 import { Context } from '@dxos/context';
 import { EdgeClient, type EdgeConnection, EdgeHttpClient, createStubEdgeIdentity } from '@dxos/edge-client';
 import { RuntimeProvider } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { PublicKey } from '@dxos/keys';
 import { type LevelDB } from '@dxos/kv-store';
 import { log } from '@dxos/log';
 import { EdgeSignalManager, type SignalManager, WebsocketSignalManager } from '@dxos/messaging';
@@ -22,12 +21,11 @@ import {
   createIceProvider,
   createRtcTransportFactory,
 } from '@dxos/network-manager';
-import { trace } from '@dxos/protocols';
 import { SystemStatus } from '@dxos/protocols/proto/dxos/client/services';
 import { type Storage } from '@dxos/random-access-storage';
 import * as SqlExport from '@dxos/sql-sqlite/SqlExport';
 import type * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
-import { TRACE_PROCESSOR, trace as Trace } from '@dxos/tracing';
+import { trace as Trace } from '@dxos/tracing';
 import { WebsocketRpcClient } from '@dxos/websocket-rpc';
 
 import { EdgeAgentServiceImpl } from '../agents';
@@ -86,8 +84,6 @@ export class ClientServicesHost {
   private readonly _serviceRegistry: ServiceRegistry<ClientServices>;
   private readonly _systemService: SystemServiceImpl;
   private readonly _loggingService: LoggingServiceImpl;
-  private readonly _tracingService = TRACE_PROCESSOR.createTraceSender();
-
   private readonly _statusUpdate = new Event<void>();
 
   private _config?: Config;
@@ -175,7 +171,6 @@ export class ClientServicesHost {
 
     this._serviceRegistry = new ServiceRegistry<ClientServices>(clientServiceBundle, {
       SystemService: this._systemService,
-      TracingService: this._tracingService,
     });
   }
 
@@ -258,7 +253,7 @@ export class ClientServicesHost {
 
     const endpoint = config?.get('runtime.services.edge.url');
     if (endpoint) {
-      const clientTag = config?.get('runtime.app.env.DX_EDGE_CLIENT_TAG');
+      const clientTag = resolveTelemetryTag(config);
       this._edgeConnection = new EdgeClient(createStubEdgeIdentity(), { socketEndpoint: endpoint, clientTag });
       this._edgeHttpClient = new EdgeHttpClient(endpoint, { clientTag });
     }
@@ -299,8 +294,7 @@ export class ClientServicesHost {
       return;
     }
 
-    const traceId = PublicKey.random().toHex();
-    log.trace('dxos.client-services.host.open', trace.begin({ id: traceId }));
+    log('opening service host');
 
     invariant(this._config, 'config not set');
     invariant(this._storage, 'storage not set');
@@ -345,7 +339,7 @@ export class ClientServicesHost {
       this._serviceContext.identityManager,
       this._serviceContext.recoveryManager,
       this._serviceContext.keyring,
-      (params) => this._createIdentity(params),
+      (params, ctx) => this._createIdentity(params, ctx),
       (profile) => this._serviceContext.broadcastProfileUpdate(profile),
     );
 
@@ -365,6 +359,7 @@ export class ClientServicesHost {
       SpacesService: new SpacesServiceImpl(
         this._serviceContext.identityManager,
         this._serviceContext.spaceManager,
+        this._serviceContext.echoHost,
         dataSpaceManagerProvider,
       ),
 
@@ -379,7 +374,6 @@ export class ClientServicesHost {
       ),
 
       LoggingService: this._loggingService,
-      TracingService: this._tracingService,
 
       // TODO(burdon): Move to new protobuf definitions.
       DevtoolsHost: new DevtoolsServiceImpl({
@@ -416,7 +410,6 @@ export class ClientServicesHost {
     this._statusUpdate.emit();
     const deviceKey = this._serviceContext.identityManager.identity?.deviceKey;
     log('opened', { deviceKey });
-    log.trace('dxos.client-services.host.open', trace.end({ id: traceId }));
   }
 
   @synchronized
@@ -440,9 +433,6 @@ export class ClientServicesHost {
   }
 
   async reset(): Promise<void> {
-    const traceId = PublicKey.random().toHex();
-    log.trace('dxos.sdk.client-services-host.reset', trace.begin({ id: traceId }));
-
     log.info('resetting...');
     // Emit this status update immediately so app returns to fallback.
     // This state is never cleared because the app reloads.
@@ -457,12 +447,11 @@ export class ClientServicesHost {
     }
     await this._storage!.reset();
     log.info('reset');
-    log.trace('dxos.sdk.client-services-host.reset', trace.end({ id: traceId }));
     await this._callbacks?.onReset?.();
   }
 
-  private async _createIdentity(params: CreateIdentityOptions) {
-    const identity = await this._serviceContext.createIdentity(params);
+  private async _createIdentity(params: CreateIdentityOptions, ctx?: Context) {
+    const identity = await this._serviceContext.createIdentity(params, ctx);
     await this._serviceContext.initialized.wait();
     return identity;
   }

package/src/packlets/space-export/archive-format.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { SpaceArchive } from '@dxos/protocols/proto/dxos/client/services';
+
+const JSON_EXTENSIONS = ['.dx.json', '.dx.json.gz', '.json'];
+const BINARY_EXTENSIONS = ['.tar', '.tar.gz'];
+
+/**
+ * Detect the format of a space archive.
+ *
+ * Uses filename extension as the primary signal, and falls back to sniffing
+ * the first bytes of the archive contents to distinguish JSON from tar.
+ */
+export const detectSpaceArchiveFormat = (archive: Pick<SpaceArchive, 'filename' | 'contents'>): SpaceArchive.Format => {
+  const filename = archive.filename?.toLowerCase() ?? '';
+  if (JSON_EXTENSIONS.some((ext) => filename.endsWith(ext))) {
+    return SpaceArchive.Format.JSON;
+  }
+  if (BINARY_EXTENSIONS.some((ext) => filename.endsWith(ext))) {
+    return SpaceArchive.Format.BINARY;
+  }
+
+  // Fall back to byte sniffing: JSON archives start with '{' (0x7B) or whitespace.
+  const bytes = archive.contents;
+  if (bytes && bytes.length > 0) {
+    for (let i = 0; i < Math.min(bytes.length, 16); i++) {
+      const byte = bytes[i];
+      // Skip whitespace.
+      if (byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d) {
+        continue;
+      }
+      if (byte === 0x7b /* '{' */) {
+        return SpaceArchive.Format.JSON;
+      }
+      break;
+    }
+  }
+
+  return SpaceArchive.Format.BINARY;
+};

package/src/packlets/space-export/index.ts

@@ -2,5 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './space-archive-writer';
+export * from './archive-format';
+export * from './serialized-space-reader';
+export * from './serialized-space-writer';
 export * from './space-archive-reader';
+export * from './space-archive-writer';

package/src/packlets/space-export/serialized-space-reader.ts

@@ -0,0 +1,111 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Obj } from '@dxos/echo';
+import { type SerializedSpace } from '@dxos/echo-db';
+import { type DatabaseDirectory, type ObjectStructure } from '@dxos/echo-protocol';
+import { assertArgument } from '@dxos/invariant';
+import { type SpaceArchive } from '@dxos/protocols/proto/dxos/client/services';
+
+const ATTR_TYPE = '@type';
+const ATTR_META = '@meta';
+const ATTR_DELETED = '@deleted';
+const ATTR_PARENT = '@parent';
+const ATTR_RELATION_SOURCE = '@relationSource';
+const ATTR_RELATION_TARGET = '@relationTarget';
+
+const INTERNAL_KEYS: ReadonlySet<string> = new Set([
+  'id',
+  ATTR_TYPE,
+  ATTR_META,
+  ATTR_DELETED,
+  ATTR_PARENT,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+]);
+
+/**
+ * Parse a JSON space archive.
+ *
+ * The archive contents are expected to be the UTF-8 encoding of
+ * `JSON.stringify(serializedSpace)`.
+ */
+export const readSerializedSpaceArchive = (archive: SpaceArchive): SerializedSpace => {
+  const text = new TextDecoder().decode(archive.contents);
+  const parsed = JSON.parse(text) as SerializedSpace;
+  assertArgument(typeof parsed === 'object' && parsed !== null, 'archive', 'Invalid JSON archive payload');
+  assertArgument(typeof parsed.version === 'number', 'archive', 'Missing SerializedSpace.version');
+  assertArgument(Array.isArray(parsed.objects), 'archive', 'Missing SerializedSpace.objects');
+  return parsed;
+};
+
+/**
+ * Convert an {@link Obj.JSON} back into an internal {@link ObjectStructure} suitable
+ * for embedding into a {@link DatabaseDirectory}.
+ */
+export const objJsonToObjectStructure = (obj: Obj.JSON): ObjectStructure => {
+  const data: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (INTERNAL_KEYS.has(key)) {
+      continue;
+    }
+    data[key] = value;
+  }
+
+  const system: NonNullable<ObjectStructure['system']> = {};
+
+  const type = obj[ATTR_TYPE];
+  if (type) {
+    system.type = { '/': type as string };
+  }
+
+  const parent = (obj as any)[ATTR_PARENT];
+  if (typeof parent === 'string') {
+    system.parent = { '/': parent };
+  }
+
+  const relationSource = (obj as any)[ATTR_RELATION_SOURCE];
+  const relationTarget = (obj as any)[ATTR_RELATION_TARGET];
+  if (typeof relationSource === 'string' || typeof relationTarget === 'string') {
+    system.kind = 'relation';
+    if (typeof relationSource === 'string') {
+      system.source = { '/': relationSource };
+    }
+    if (typeof relationTarget === 'string') {
+      system.target = { '/': relationTarget };
+    }
+  } else {
+    system.kind = 'object';
+  }
+
+  if ((obj as any)[ATTR_DELETED]) {
+    system.deleted = true;
+  }
+
+  const meta = (obj as any)[ATTR_META];
+  return {
+    system,
+    meta: {
+      keys: meta?.keys ?? [],
+      ...(meta?.tags ? { tags: meta.tags } : {}),
+    },
+    data,
+  };
+};
+
+/**
+ * Build a new {@link DatabaseDirectory} containing every object from the archive,
+ * keyed by object id. The caller is responsible for stamping the `access.spaceKey`
+ * and version fields after the document is created.
+ */
+export const buildDatabaseDirectoryFromObjects = (objects: readonly Obj.JSON[]): DatabaseDirectory => {
+  const map: Record<string, ObjectStructure> = {};
+  for (const obj of objects) {
+    map[obj.id] = objJsonToObjectStructure(obj);
+  }
+  return {
+    objects: map,
+    links: {},
+  };
+};