@dxos/client-services 0.10.0 → 0.11.0

package/src/packlets/metadata/sqlite-metadata-store.ts

@@ -0,0 +1,409 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlError from '@effect/sql/SqlError';
+import CRC32 from 'crc-32';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Event, scheduleTaskInterval, synchronized } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { RuntimeProvider } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { DataCorruptionError, STORAGE_VERSION } from '@dxos/protocols';
+import { schema } from '@dxos/protocols/proto';
+import { Invitation, SpaceState } from '@dxos/protocols/proto/dxos/client/services';
+import {
+  type ControlPipelineSnapshot,
+  type EchoMetadata,
+  type EdgeReplicationSetting,
+  type IdentityRecord,
+  type LargeSpaceMetadata,
+  type SpaceCache,
+  type SpaceMetadata,
+} from '@dxos/protocols/proto/dxos/echo/metadata';
+import { SqlTransaction } from '@dxos/sql-sqlite';
+import { type Timeframe } from '@dxos/timeframe';
+import { ComplexMap, arrayToBuffer, forEachAsync, isNonNullable } from '@dxos/util';
+
+import { type IMetadataStore, IMetadataStoreService, hasInvitationExpired } from './metadata-store';
+
+// SqlTransaction.SqlTransaction is the Tag class exported from the SqlTransaction namespace.
+type SqlTransactionTag = SqlTransaction.SqlTransaction;
+
+const EXPIRED_INVITATION_CLEANUP_INTERVAL = 60 * 60 * 1000; // 1 hour
+
+const emptyEchoMetadata = (): EchoMetadata => ({
+  version: STORAGE_VERSION,
+  spaces: [],
+  created: new Date(),
+  updated: new Date(),
+});
+
+const emptyLargeSpaceMetadata = (): LargeSpaceMetadata => ({});
+
+const EchoMetadataCodec = schema.getCodecForType('dxos.echo.metadata.EchoMetadata');
+const LargeSpaceMetadataCodec = schema.getCodecForType('dxos.echo.metadata.LargeSpaceMetadata');
+
+const MAIN_KEY = 'main';
+const largeKey = (spaceKey: PublicKey) => `large:${spaceKey.toHex()}`;
+
+// Legacy invitation type detection.
+const isLegacyInvitationFormat = (invitation: Invitation): boolean => invitation.type === Invitation.Type.MULTIUSE;
+
+export type SqliteMetadataStoreProps = {
+  runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransactionTag>;
+};
+
+/**
+ * SQLite-backed replacement for MetadataStore.
+ * Stores EchoMetadata as a single protobuf blob and LargeSpaceMetadata as per-space blobs.
+ */
+export class SqliteMetadataStore implements IMetadataStore {
+  readonly #runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransactionTag>;
+
+  #metadata: EchoMetadata = emptyEchoMetadata();
+  readonly #spaceLargeMetadata = new ComplexMap<PublicKey, LargeSpaceMetadata>(PublicKey.hash);
+
+  readonly update = new Event<EchoMetadata>();
+  readonly #invitationCleanupCtx = new Context();
+
+  constructor({ runtime }: SqliteMetadataStoreProps) {
+    this.#runtime = runtime;
+  }
+
+  /**
+   * Creates the space_metadata and space_large tables if they do not exist.
+   */
+  readonly migrate: Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient | SqlTransactionTag> = Effect.fn(
+    'SqliteMetadataStore.migrate',
+  )(() =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      yield* sql`CREATE TABLE IF NOT EXISTS space_metadata (
+          key TEXT PRIMARY KEY,
+          value BLOB NOT NULL
+        )`;
+      yield* sql`CREATE TABLE IF NOT EXISTS space_large (
+          space_key TEXT PRIMARY KEY,
+          value BLOB NOT NULL
+        )`;
+      log('space_metadata and space_large tables ready');
+    }).pipe(Effect.withSpan('SqliteMetadataStore.migrate')),
+  )();
+
+  get metadata(): EchoMetadata {
+    return this.#metadata;
+  }
+
+  get version(): number {
+    return this.#metadata.version ?? 0;
+  }
+
+  get spaces(): SpaceMetadata[] {
+    return this.#metadata.spaces ?? [];
+  }
+
+  async close(): Promise<void> {
+    await this.#invitationCleanupCtx.dispose();
+    await this._save();
+    this.#metadata = emptyEchoMetadata();
+    this.#spaceLargeMetadata.clear();
+  }
+
+  /**
+   * Loads metadata from SQLite.
+   */
+  @synchronized
+  async load(): Promise<void> {
+    const rows = await RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        return yield* sql<{ value: Uint8Array }>`SELECT value FROM space_metadata WHERE key = ${MAIN_KEY}`;
+      }),
+    );
+
+    if (rows.length > 0) {
+      try {
+        this.#metadata = this.#decodeWithCrc(rows[0].value, EchoMetadataCodec) ?? emptyEchoMetadata();
+        this.#metadata.spaces?.forEach((space) => {
+          space.state ??= SpaceState.SPACE_ACTIVE;
+        });
+      } catch (err: any) {
+        log.error('failed to load metadata from SQLite', { err });
+        this.#metadata = emptyEchoMetadata();
+      }
+    }
+
+    // Load large metadata for all known spaces.
+    const spaceKeys = [
+      this.#metadata.identity?.haloSpace.key,
+      ...(this.#metadata.spaces?.map((s) => s.key) ?? []),
+    ].filter(isNonNullable);
+
+    await forEachAsync(spaceKeys, async (key) => {
+      try {
+        await this.#loadSpaceLargeMetadata(key);
+      } catch (err: any) {
+        log.error('failed to load large space metadata', { err });
+      }
+    });
+
+    scheduleTaskInterval(
+      this.#invitationCleanupCtx,
+      async () => {
+        for (const invitation of this.#metadata.invitations ?? []) {
+          if (hasInvitationExpired(invitation) || isLegacyInvitationFormat(invitation)) {
+            await this.removeInvitation(invitation.invitationId);
+          }
+        }
+      },
+      EXPIRED_INVITATION_CLEANUP_INTERVAL,
+    );
+  }
+
+  async flush(): Promise<void> {
+    // No-op: SQLite writes are immediate.
+  }
+
+  hasSpace(spaceKey: PublicKey): boolean {
+    if (this.#metadata.identity?.haloSpace.key.equals(spaceKey)) {
+      return true;
+    }
+    return !!this.spaces.find((space) => space.key.equals(spaceKey));
+  }
+
+  getIdentityRecord(): IdentityRecord | undefined {
+    return this.#metadata.identity;
+  }
+
+  async setIdentityRecord(record: IdentityRecord): Promise<void> {
+    invariant(!this.#metadata.identity, 'Cannot overwrite existing identity in metadata');
+    this.#metadata.identity = record;
+    await this._save();
+  }
+
+  getInvitations(): Invitation[] {
+    return this.#metadata.invitations ?? [];
+  }
+
+  async addInvitation(invitation: Invitation): Promise<void> {
+    if (this.#metadata.invitations?.find((i) => i.invitationId === invitation.invitationId)) {
+      return;
+    }
+    (this.#metadata.invitations ??= []).push(invitation);
+    await this._save();
+  }
+
+  async removeInvitation(invitationId: string): Promise<void> {
+    this.#metadata.invitations = (this.#metadata.invitations ?? []).filter((i) => i.invitationId !== invitationId);
+    await this._save();
+  }
+
+  async addSpace(record: SpaceMetadata): Promise<void> {
+    invariant(
+      !(this.#metadata.spaces ?? []).find((space) => space.key.equals(record.key)),
+      'Cannot overwrite existing space in metadata',
+    );
+    (this.#metadata.spaces ??= []).push(record);
+    await this._save();
+  }
+
+  async setSpaceDataLatestTimeframe(spaceKey: PublicKey, timeframe: Timeframe): Promise<void> {
+    this.#getSpace(spaceKey).dataTimeframe = timeframe;
+    await this._save();
+  }
+
+  async setSpaceControlLatestTimeframe(spaceKey: PublicKey, timeframe: Timeframe): Promise<void> {
+    this.#getSpace(spaceKey).controlTimeframe = timeframe;
+    await this._save();
+  }
+
+  async setCache(spaceKey: PublicKey, cache: SpaceCache): Promise<void> {
+    this.#getSpace(spaceKey).cache = cache;
+    await this._save();
+  }
+
+  async setWritableFeedKeys(spaceKey: PublicKey, controlFeedKey: PublicKey, dataFeedKey: PublicKey): Promise<void> {
+    const space = this.#getSpace(spaceKey);
+    space.controlFeedKey = controlFeedKey;
+    space.dataFeedKey = dataFeedKey;
+    await this._save();
+  }
+
+  async setSpaceState(spaceKey: PublicKey, state: SpaceState): Promise<void> {
+    this.#getSpace(spaceKey).state = state;
+    await this._save();
+  }
+
+  getSpaceControlPipelineSnapshot(spaceKey: PublicKey): ControlPipelineSnapshot | undefined {
+    return this.#getLargeSpaceMetadata(spaceKey).controlPipelineSnapshot;
+  }
+
+  async setSpaceControlPipelineSnapshot(spaceKey: PublicKey, snapshot: ControlPipelineSnapshot): Promise<void> {
+    this.#getLargeSpaceMetadata(spaceKey).controlPipelineSnapshot = snapshot;
+    await this._saveSpaceLargeMetadata(spaceKey);
+  }
+
+  getSpaceEdgeReplicationSetting(spaceKey: PublicKey): EdgeReplicationSetting | undefined {
+    return this.hasSpace(spaceKey) ? this.#getSpace(spaceKey).edgeReplication : undefined;
+  }
+
+  async setSpaceEdgeReplicationSetting(spaceKey: PublicKey, setting: EdgeReplicationSetting): Promise<void> {
+    this.#getSpace(spaceKey).edgeReplication = setting;
+    await this._save();
+  }
+
+  get deletedSpaces(): PublicKey[] {
+    return this.#metadata.deletedSpaces ?? [];
+  }
+
+  async addDeletedSpace(spaceKey: PublicKey): Promise<void> {
+    if ((this.#metadata.deletedSpaces ?? []).some((key) => key.equals(spaceKey))) {
+      return;
+    }
+    (this.#metadata.deletedSpaces ??= []).push(spaceKey);
+    await this._save();
+  }
+
+  async clear(): Promise<void> {
+    log('clearing all metadata');
+    await RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql`DELETE FROM space_metadata`;
+        yield* sql`DELETE FROM space_large`;
+      }),
+    );
+    this.#metadata = emptyEchoMetadata();
+    this.#spaceLargeMetadata.clear();
+  }
+
+  #getSpace(spaceKey: PublicKey): SpaceMetadata {
+    if (this.#metadata.identity?.haloSpace.key.equals(spaceKey)) {
+      return this.#metadata.identity.haloSpace;
+    }
+    const space = this.spaces.find((space) => space.key.equals(spaceKey));
+    invariant(space, 'Space not found');
+    return space;
+  }
+
+  #getLargeSpaceMetadata(key: PublicKey): LargeSpaceMetadata {
+    let entry = this.#spaceLargeMetadata.get(key);
+    if (!entry) {
+      entry = emptyLargeSpaceMetadata();
+      this.#spaceLargeMetadata.set(key, entry);
+    }
+    return entry;
+  }
+
+  @synchronized
+  private async _save(): Promise<void> {
+    const data: EchoMetadata = {
+      ...this.#metadata,
+      version: STORAGE_VERSION,
+      created: this.#metadata.created ?? new Date(),
+      updated: new Date(),
+    };
+    this.update.emit(data);
+    const encoded = this.#encodeWithCrc(EchoMetadataCodec, data);
+    await RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql`INSERT OR REPLACE INTO space_metadata (key, value) VALUES (${MAIN_KEY}, ${encoded})`;
+      }),
+    );
+  }
+
+  async #loadSpaceLargeMetadata(key: PublicKey): Promise<void> {
+    const keyStr = largeKey(key);
+    const rows = await RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        return yield* sql<{ value: Uint8Array }>`SELECT value FROM space_large WHERE space_key = ${keyStr}`;
+      }),
+    );
+    if (rows.length > 0) {
+      try {
+        const meta = this.#decodeWithCrc(rows[0].value, LargeSpaceMetadataCodec);
+        if (meta) {
+          this.#spaceLargeMetadata.set(key, meta);
+        }
+      } catch (err: any) {
+        log.error('failed to decode large space metadata', { err });
+      }
+    }
+  }
+
+  @synchronized
+  private async _saveSpaceLargeMetadata(key: PublicKey): Promise<void> {
+    const data = this.#getLargeSpaceMetadata(key);
+    const keyStr = largeKey(key);
+    const encoded = this.#encodeWithCrc(LargeSpaceMetadataCodec, data);
+    await RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql`INSERT OR REPLACE INTO space_large (space_key, value) VALUES (${keyStr}, ${encoded})`;
+      }),
+    );
+  }
+
+  /** Serialize with CRC32 checksum prefix for integrity checking (matches MetadataStore format). */
+  #encodeWithCrc<T>(codec: { encode: (v: T) => Uint8Array }, data: T): Buffer {
+    const encoded = arrayToBuffer(codec.encode(data));
+    const checksum = CRC32.buf(encoded);
+    const result = Buffer.alloc(8 + encoded.length);
+    result.writeInt32LE(encoded.length, 0);
+    result.writeInt32LE(checksum, 4);
+    encoded.copy(result, 8);
+    return result;
+  }
+
+  /** Deserialize with CRC32 integrity check (matches MetadataStore format). */
+  #decodeWithCrc<T>(data: Uint8Array, codec: { decode: (v: Uint8Array) => T }): T | undefined {
+    const buf = Buffer.from(data);
+    if (buf.length < 8) {
+      return undefined;
+    }
+    const dataSize = buf.readInt32LE(0);
+    const checksum = buf.readInt32LE(4);
+    if (dataSize < 0 || dataSize > buf.length - 8) {
+      throw new DataCorruptionError({
+        message: 'Metadata size header is invalid.',
+        context: { fileLength: buf.length, dataSize },
+      });
+    }
+    if (buf.length !== dataSize + 8) {
+      throw new DataCorruptionError({
+        message: 'Metadata payload length does not match framing header.',
+        context: { fileLength: buf.length, dataSize },
+      });
+    }
+    const payload = buf.subarray(8, dataSize + 8);
+    const calculated = CRC32.buf(payload);
+    if (calculated !== checksum) {
+      throw new DataCorruptionError({ message: 'Metadata checksum is invalid.' });
+    }
+    return codec.decode(payload);
+  }
+}
+
+/**
+ * Effect Layer constructing a {@link SqliteMetadataStore} from the ambient SQL runtime.
+ */
+export const SqliteMetadataStoreLayer = (): Layer.Layer<
+  IMetadataStoreService,
+  never,
+  SqlClient.SqlClient | SqlTransactionTag
+> =>
+  Layer.effect(
+    IMetadataStoreService,
+    Effect.gen(function* () {
+      const runtime = yield* RuntimeProvider.currentRuntime<SqlClient.SqlClient | SqlTransactionTag>();
+      return new SqliteMetadataStore({ runtime });
+    }),
+  );

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

@@ -2,11 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
+import * as Runtime from 'effect/Runtime';
 import { afterEach, beforeEach, describe, expect, onTestFinished, test } from 'vitest';
 
 import { Trigger } from '@dxos/async';
 import { Context } from '@dxos/context';
-import { ConnectionState, type NetworkService } from '@dxos/protocols/proto/dxos/client/services';
+import { EffectEx } from '@dxos/effect';
+import { subscribeStream } from '@dxos/protocols';
+import { ConnectionState } from '@dxos/protocols/proto/dxos/client/services';
 
 import { type ServiceContext } from '../services';
 import { createServiceContext } from '../testing';
@@ -14,7 +17,7 @@ import { NetworkServiceImpl } from './network-service';
 
 describe('NetworkService', () => {
   let serviceContext: ServiceContext;
-  let networkService: NetworkService;
+  let networkService: NetworkServiceImpl;
 
   beforeEach(async () => {
     serviceContext = await createServiceContext();
@@ -27,26 +30,30 @@ describe('NetworkService', () => {
   });
 
   test('setNetworkOptions changes network status', async () => {
-    await networkService.updateConfig({
-      swarm: ConnectionState.OFFLINE,
-    });
+    await EffectEx.runPromise(
+      networkService['NetworkService.updateConfig']({
+        swarm: ConnectionState.OFFLINE,
+      }),
+    );
 
     expect(serviceContext.networkManager.connectionState).to.equal(ConnectionState.OFFLINE);
   });
 
   test('subscribeToNetworkStatus returns current network status', async () => {
-    const query = networkService.queryStatus();
+    const stream = networkService['NetworkService.queryStatus']();
     let result = new Trigger<ConnectionState | undefined>();
-    query.subscribe(({ swarm }) => {
-      result.wake(swarm);
+    const cleanup = subscribeStream(Runtime.defaultRuntime, stream, {
+      onData: ({ swarm }) => result.wake(swarm),
     });
-    onTestFinished(() => query.close());
+    onTestFinished(cleanup);
     expect(await result.wait()).to.equal(ConnectionState.ONLINE);
 
     result = new Trigger<ConnectionState | undefined>();
-    await networkService.updateConfig({
-      swarm: ConnectionState.OFFLINE,
-    });
+    await EffectEx.runPromise(
+      networkService['NetworkService.updateConfig']({
+        swarm: ConnectionState.OFFLINE,
+      }),
+    );
     expect(await result.wait()).to.equal(ConnectionState.OFFLINE);
   });
 });

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

@@ -2,37 +2,40 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type RequestOptions } from '@dxos/codec-protobuf';
-import { Stream } from '@dxos/codec-protobuf/stream';
+import * as Effect from 'effect/Effect';
+import * as EffectStream from 'effect/Stream';
+
 import { Context } from '@dxos/context';
 import { type EdgeConnection } from '@dxos/edge-client';
-import { type SignalManager } from '@dxos/messaging';
+import { type SignalManager, type UnsubscribeCallback } from '@dxos/messaging';
 import { type SwarmNetworkManager } from '@dxos/network-manager';
 import {
-  type NetworkService,
   type NetworkStatus,
   type SubscribeSwarmStateRequest,
   type UpdateConfigRequest,
 } from '@dxos/protocols/proto/dxos/client/services';
-import { type Peer, type SwarmResponse } from '@dxos/protocols/proto/dxos/edge/messenger';
+import { type SwarmResponse } from '@dxos/protocols/proto/dxos/edge/messenger';
 import {
   type JoinRequest,
   type LeaveRequest,
   type Message,
   type QueryRequest,
+  type SubscribeMessagesRequest,
 } from '@dxos/protocols/proto/dxos/edge/signal';
+import { type NetworkService } from '@dxos/protocols/rpc';
 
-export class NetworkServiceImpl implements NetworkService {
-  constructor(
+export class NetworkServiceImpl implements NetworkService.Handlers {
+  'constructor'(
     private readonly networkManager: SwarmNetworkManager,
     private readonly signalManager: SignalManager,
     private readonly edgeConnection?: EdgeConnection,
   ) {}
 
-  queryStatus(): Stream<NetworkStatus> {
-    return new Stream<NetworkStatus>(({ ctx, next }) => {
+  ['NetworkService.queryStatus'](): EffectStream.Stream<NetworkStatus, Error> {
+    return EffectStream.async<NetworkStatus, Error>((emit) => {
+      const ctx = Context.default();
       const update = () => {
-        next({
+        void emit.single({
           swarm: this.networkManager.connectionState,
           connectionInfo: this.networkManager.connectionLog?.swarms,
           signaling: this.signalManager.getStatus?.().map(({ host, state }) => ({ server: host, state })),
@@ -42,45 +45,109 @@ export class NetworkServiceImpl implements NetworkService {
       this.networkManager.connectionStateChanged.on(ctx, () => update());
       this.signalManager.statusChanged?.on(ctx, () => update());
       update();
+
+      return Effect.promise(() => ctx.dispose());
     });
   }
 
-  async updateConfig(request: UpdateConfigRequest): Promise<void> {
-    await this.networkManager.setConnectionState(request.swarm);
+  ['NetworkService.updateConfig'](request: UpdateConfigRequest): Effect.Effect<void, Error> {
+    return Effect.tryPromise({
+      try: async () => {
+        await this.networkManager.setConnectionState(request.swarm);
+      },
+      catch: (error) => error as Error,
+    });
   }
 
-  async joinSwarm(request: JoinRequest, options?: RequestOptions): Promise<void> {
-    return this.signalManager.join(options?.ctx ?? Context.default(), request);
+  ['NetworkService.joinSwarm'](request: JoinRequest): Effect.Effect<void, Error> {
+    return Effect.tryPromise({
+      try: async () => {
+        await this.signalManager.join(Context.default(), request);
+      },
+      catch: (error) => error as Error,
+    });
   }
 
-  async leaveSwarm(request: LeaveRequest, options?: RequestOptions): Promise<void> {
-    return this.signalManager.leave(options?.ctx ?? Context.default(), request);
+  ['NetworkService.leaveSwarm'](request: LeaveRequest): Effect.Effect<void, Error> {
+    return Effect.tryPromise({
+      try: async () => {
+        await this.signalManager.leave(Context.default(), request);
+      },
+      catch: (error) => error as Error,
+    });
   }
 
-  async querySwarm(request: QueryRequest, options?: RequestOptions): Promise<SwarmResponse> {
-    return this.signalManager.query(options?.ctx ?? Context.default(), request);
+  ['NetworkService.querySwarm'](request: QueryRequest): Effect.Effect<SwarmResponse, Error> {
+    return Effect.tryPromise({
+      try: async () => {
+        return this.signalManager.query(Context.default(), request);
+      },
+      catch: (error) => error as Error,
+    });
   }
 
-  subscribeSwarmState(request: SubscribeSwarmStateRequest): Stream<SwarmResponse> {
-    return new Stream<SwarmResponse>(({ ctx, next }) => {
+  ['NetworkService.subscribeSwarmState'](
+    request: SubscribeSwarmStateRequest,
+  ): EffectStream.Stream<SwarmResponse, Error> {
+    return EffectStream.async<SwarmResponse, Error>((emit) => {
+      const ctx = Context.default();
       this.signalManager.swarmState?.on(ctx, (state) => {
         if (request.topic.equals(state.swarmKey)) {
-          next(state);
+          void emit.single(state);
         }
       });
+
+      return Effect.promise(() => ctx.dispose());
     });
   }
 
-  async sendMessage(message: Message, options?: RequestOptions): Promise<void> {
-    return this.signalManager.sendMessage(options?.ctx ?? Context.default(), message);
+  ['NetworkService.sendMessage'](message: Message): Effect.Effect<void, Error> {
+    return Effect.tryPromise({
+      try: async () => {
+        await this.signalManager.sendMessage(Context.default(), message);
+      },
+      catch: (error) => error as Error,
+    });
   }
 
-  subscribeMessages(peer: Peer): Stream<Message> {
-    return new Stream<Message>(({ ctx, next }) => {
-      this.signalManager.onMessage.on(ctx, (message) => {
-        if (message.recipient.peerKey === peer.peerKey) {
-          next(message);
-        }
+  ['NetworkService.subscribeMessages'](request: SubscribeMessagesRequest): EffectStream.Stream<Message, Error> {
+    const { peer, tags = [] } = request;
+    return EffectStream.async<Message, Error>((emit) => {
+      const ctx = Context.default();
+
+      // This stream crosses the client-services RPC (protobufjs codec, e.g. dedicated worker → main
+      // thread). Its `Message.payload` is a `google.protobuf.Any` without `preserve_any`, and the
+      // codec refuses to encode an Any lacking '@type' — stamping the opaque form
+      // ('@type': 'google.protobuf.Any' + type_url/value) makes it pass through verbatim.
+      const encodableAny = (payload: Message['payload']): Message['payload'] => ({
+        ...payload,
+        '@type': 'google.protobuf.Any',
+      });
+
+      // The subscription encapsulates routing (DX-1125): point-to-point messages addressed to `peer`,
+      // plus — when `tags` are set — swarm broadcasts whose tags intersect. The returned callback owns
+      // teardown, refcounted so it releases only this stream's tag registration.
+      let unsubscribe: UnsubscribeCallback | undefined;
+      void this.signalManager
+        .subscribeMessages({
+          peer,
+          tags,
+          onMessage: (message) => {
+            void emit.single({ ...message, payload: encodableAny(message.payload) });
+          },
+        })
+        .then((unsub) => {
+          if (ctx.disposed) {
+            void unsub();
+          } else {
+            unsubscribe = unsub;
+          }
+        })
+        .catch((err) => emit.fail(err instanceof Error ? err : new Error(String(err))));
+
+      return Effect.promise(async () => {
+        await unsubscribe?.();
+        await ctx.dispose();
       });
     });
   }

package/src/packlets/pipeline/codec.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Codec } from '@dxos/codec-protobuf';
+import { createCodecEncoding } from '@dxos/hypercore';
+import { schema } from '@dxos/protocols/proto';
+import type { FeedMessage } from '@dxos/protocols/proto/dxos/echo/feed';
+
+/**
+ * Codec for feed messages.
+ */
+export const codec: Codec<FeedMessage> = schema.getCodecForType('dxos.echo.feed.FeedMessage');
+
+/**
+ * Value encoding used by feed store.
+ */
+export const valueEncoding = createCodecEncoding(codec);