@dxos/feed 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License 
+Copyright (c) 2022 DXOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# @dxos/feed
+
+Append-only replicatable log consisting of blocks.
+
+## Specification
+
+### Concept
+
+The feed is an append-only replicated log where data is stored in immutable blocks.
+It is designed to run in multiple environments:
+
+- **Browser**: Using `wasm-sqlite` in a Client Services Worker.
+- **Node**: Native SQLite.
+- **Cloudflare Workers**: Durable Objects SQL Storage.
+
+All environments use `effect-sql` as the abstraction layer.
+
+### Capacity
+
+- **Feeds per Space**: ~1000
+- **Blocks per Feed**: ~10,000
+
+### Replication
+
+- **Push**: Peers push blocks **without positions**.
+- **Pull**: Peers pull blocks **with positions**, allowing them to reconstruct the global order locally.
+
+#### Partial Replication
+
+The protocol supports partial replication:
+
+- **Per-Feed Configuration**: Each feed has independent replication settings.
+  - **Default**: No replication (None).
+  - **Replica Mode**: `replicate(fromPosition)` -> Replicates `[fromPosition, Infinity)`.
+    - `fromPosition = 0`: Full History.
+    - `fromPosition = current`: Live Tail only.
+    - `fromPosition = now - 3days`: Time-based window (Future potential).
+- **Metadata**: Replication settings are stored alongside feed metadata (locally).
+- **Subset of Feeds**: Clients can choose to replicate only a specific subset of feeds within a Space.
+  - _TODO: Define mechanism for selecting which feeds to replicate._
+- **Range Selection**: Replication is strictly defined from a specific **start position** to the **end** (future blocks).
+  - It is NOT possible to replicate only historical data without subscribing to new data.
+  - Logic: `replicate(feedId, fromPosition) -> [fromPosition, Infinity)`
+
+### Server Architecture (Cloudflare)
+
+- **Initial Strategy**: **One Durable Object (DO) per Space**.
+  - All feeds for a single space are managed by a single DO instance.
+  - Simplifies consistency and coordination.
+- **Scaling Strategy (Future)**: **Sharding by Feed ID**.
+  - Feeds can be distributed across multiple DOs.
+  - Shard Key: Prefix of `hash(feedId)` (e.g., first 2 chars).
+
+### Ordering
+
+Ordering is determined by the following rules:
+
+1.  **Positioned Blocks**: Blocks that have been assigned a global `position` by the Server.
+    - Ordered strictly by `position` (ascending).
+2.  **Unpositioned Blocks**: Blocks pending position assignment (locally created or in-flight).
+    - Ordered by **Lamport Timestamp** rules:
+      1.  `sequence` (Ascending)
+      2.  `actorId` (Lexicographical)
+
+`sequence`: Assigned by the peer (Author). `actorId` + `sequence` forms the Lamport timestamp.
+
+> `nextSeq = max(previous_seq_in_this_feed) + 1`
+
+`position`: Assigned ONLY by the Server. Monotonic counter per Space.
+
+### Idempotency
+
+The protocol is idempotent. A block is uniquely identified by the tuple:
+
+- `(spaceId, feedId, sequence, actorId)`
+  OR
+- `(spaceId, feedId, position)` (if positioned)
+
+Processing the same block multiple times must be handled gracefully (e.g., `ON CONFLICT DO NOTHING`).
+
+### Schema
+
+#### Feeds Table (`feeds`)
+
+Stores the mapping between global feed identifiers and local integer IDs.
+
+| Field           | Type     | Description                                                                   |
+| :-------------- | :------- | :---------------------------------------------------------------------------- |
+| `feedPrivateId` | `number` | **Primary Key**. Local integer identifier for the feed (private to the peer). |
+| `spaceId`       | `string` | The global Space ID (external).                                               |
+| `feedId`        | `string` | The global Feed ID (ULID).                                                    |
+| `feedNamespace` | `string` | **Optional**. Application specific namespace for filtering feeds.             |
+
+**Indexes**:
+
+- Unique Index: `(spaceId, feedId)`
+
+#### Blocks Table (`blocks`)
+
+| Field           | Type             | Description                                           |
+| :-------------- | :--------------- | :---------------------------------------------------- |
+| `feedPrivateId` | `number`         | Foreign key to `feeds.feedPrivateId`.                 |
+| `position`      | `number \| null` | The global position index. `null` if unpositioned.    |
+| `sequence`      | `number`         | **Sequence Number** (Assigned by Author).             |
+| `actorId`       | `string`         | **Actor ID** (Public Key).                            |
+| `predSequence`  | `number`         | **Sequence Number** part of the Predecessor ID.       |
+| `predActorId`   | `string`         | **Actor ID** (Public Key) part of the Predecessor ID. |
+| `timestamp`     | `number`         | Unix timestamp in milliseconds.                       |
+| `data`          | `Uint8Array`     | The content of the block. **Immutable**.              |
+
+**Indexes**:
+
+- Unique Index: `(feedPrivateId, position)`
+- Unique Index: `(feedPrivateId, sequence, actorId)`
+
+#### Subscriptions Table (`subscriptions`)
+
+Stores active subscriptions to optimize wire protocol.
+
+| Field            | Type     | Description                               |
+| :--------------- | :------- | :---------------------------------------- |
+| `subscriptionId` | `string` | **Primary Key**. Unique ID.               |
+| `expiresAt`      | `number` | Unix timestamp when subscription expires. |
+| `feedPrivateIds` | `string` | JSON array of `feedPrivateId`s.           |
+
+### Sync Protocol (Message-Based RPC)
+
+The sync protocol is message-based. All messages include a `requestId`. Responses must copy the `requestId` from the request.
+
+1.  **Query**
+    - Input: `requestId`, `(feedIds: string[]) + cursor` OR `(subscriptionId: string) + cursor`
+    - Output: `requestId`, `Block[]` (Stream or Batch)
+    - Description: Returns blocks from the specified feeds (or subscription) with `position > cursor`.
+
+2.  **Subscribe**
+    - Input: `requestId`, `feedIds: string[]`
+    - Output: `requestId`, `subscriptionId: string`
+    - Description: Registers a subscription for specific feeds. Returns a `subscriptionId`.
+
+3.  **Append**
+    - Input: `requestId`, `namespace?: string`, `blocks: Block[]`
+    - Output: `requestId`, `positions: number[]`
+    - Description: Appends blocks to their respective feeds.
+      - If `namespace` is provided and the feed is new, it sets the feed's namespace.
+      - Returns the assigned global positions.
+
+### Logic
+
+#### Feed Identification
+
+A feed is globally identified by the tuple `(spaceId, feedId)`.
+
+- `spaceId`: String provided externally.
+- `feedId`: ULID string.
+
+#### Timestamps
+
+All timestamps (e.g., `insertionTimestamp`) are Unix timestamps in milliseconds.
+
+## Usage Examples
+
+### 1. Append Blocks
+
+**Request:**
+
+```json
+{
+  "requestId": "req-1",
+  "namespace": "my-app-data",
+  "blocks": [
+    {
+      "actorId": "01H1...",
+      "sequence": 100,
+      "data": "...",
+      "timestamp": 1234567890
+    }
+  ]
+}
+```
+
+**Response:**
+
+```json
+{
+  "requestId": "req-1",
+  "positions": [42]
+}
+```
+
+### 2. Subscribe and Query
+
+**Subscribe Request:**
+
+```json
+{
+  "requestId": "req-2",
+  "feedIds": ["01H1..."]
+}
+```
+
+**Subscribe Response:**
+
+```json
+{
+  "requestId": "req-2",
+  "subscriptionId": "sub-123",
+  "expiresAt": 1234569999
+}
+```
+
+### 3. List Feeds
+
+**Request:**
+
+```json
+{
+  "requestId": "req-4",
+  "namespace": "data"
+}
+```
+
+**Response:**
+
+```json
+{
+  "requestId": "req-4",
+  "feeds": [
+    { "feedId": "01H1...", "namespace": "data" },
+    { "feedId": "02H2...", "namespace": "data" }
+  ]
+}
+```
+
+**Query Request (Poll using Subscription):**
+
+```json
+{
+  "requestId": "req-3",
+  "subscriptionId": "sub-123",
+  "cursor": 41
+}
+```
+
+**Query Response:**
+
+```json
+{
+  "requestId": "req-3",
+  "blocks": [
+    {
+      "position": 42,
+      "sequence": 100,
+      "actorId": "01H1...",
+      "data": "..."
+    }
+  ]
+}
+```

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@dxos/feed",
+  "version": "0.0.0",
+  "description": "Append-only replicatable log",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "info@dxos.org",
+  "sideEffects": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "source": "./src/index.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/index.d.ts",
+      "source": "./src/testing/index.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@effect/sql": "0.48.6",
+    "@effect/sql-sqlite-node": "0.49.1",
+    "@effect/vitest": "0.27.0",
+    "effect": "3.19.11",
+    "@dxos/keys": "0.8.3",
+    "@dxos/async": "0.8.3",
+    "@dxos/log": "0.8.3",
+    "@dxos/invariant": "0.8.3",
+    "@dxos/util": "0.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "beast": {}
+}

package/src/feed-store.test.ts

@@ -0,0 +1,357 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SqliteClient from '@effect/sql-sqlite-node/SqliteClient';
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { ObjectId, SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { FeedStore } from './feed-store';
+import { Block } from './protocol';
+
+const TestLayer = SqliteClient.layer({
+  filename: ':memory:',
+});
+
+// ActorIds.
+const ALICE = 'alice';
+const BOB = 'bob';
+
+describe('Feed V2', () => {
+  it.effect('should append and query blocks via RPC', () =>
+    Effect.gen(function* () {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+
+      const feed = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feed.migrate();
+
+      // Append
+      const block: Block = {
+        feedId: undefined,
+        actorId: feedId,
+        sequence: 123, // Author sequence provided by peer
+        predActorId: null,
+        predSequence: null,
+        position: null, // Input doesn't have position
+        timestamp: Date.now(),
+        data: new Uint8Array([1, 2, 3]),
+      };
+
+      const appendRes = yield* feed.append({ requestId: 'req-1', blocks: [block], spaceId, feedId, namespace: 'data' });
+      expect(appendRes.positions.length).toBe(1);
+      expect(appendRes.positions[0]).toBeDefined();
+      expect(appendRes.requestId).toBe('req-1');
+
+      // Query by feedId
+      const queryRes = yield* feed.query({ requestId: 'req-2', query: { feedIds: [feedId] }, position: -1, spaceId }); // Use position -1 to get everything
+      expect(queryRes.blocks.length).toBe(1);
+      expect(queryRes.blocks[0].position).toBe(appendRes.positions[0]);
+      expect(queryRes.blocks[0].sequence).toBe(123); // Verify Author Sequence is preserved
+      expect(queryRes.requestId).toBe('req-2');
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('should persist feed namespace', () =>
+    Effect.gen(function* () {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+      const namespace = 'data';
+
+      const feed = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feed.migrate();
+
+      // Append with namespace
+      const block = Block.make({
+        feedId: undefined,
+        actorId: ALICE,
+        sequence: 1,
+        predActorId: null,
+        predSequence: null,
+        position: null,
+        timestamp: Date.now(),
+        data: new Uint8Array([1]),
+      });
+
+      yield* feed.append({ requestId: 'req-ns', blocks: [block], namespace, spaceId, feedId });
+
+      // Verify directly from DB (white-box test) to ensure schema is correct
+      const sql = yield* SqliteClient.SqliteClient;
+      const rows = yield* sql<{ feedNamespace: string }>`
+        SELECT feedNamespace FROM feeds WHERE spaceId = ${spaceId} AND feedId = ${feedId}
+      `;
+      expect(rows.length).toBeGreaterThan(0);
+      expect(rows[0].feedNamespace).toBe(namespace);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('should use subscriptions', () =>
+    Effect.gen(function* () {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+
+      const feed = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feed.migrate();
+
+      // Append some data
+      yield* feed.append({
+        requestId: 'req-1',
+        blocks: [
+          Block.make({
+            feedId: undefined,
+            actorId: feedId,
+            sequence: 1,
+            predActorId: null,
+            predSequence: null,
+            position: null,
+            timestamp: Date.now(),
+            data: new Uint8Array([1]),
+          }),
+        ],
+        spaceId,
+        feedId,
+        namespace: 'data',
+      });
+
+      // Subscribe
+      const subRes = yield* feed.subscribe({ requestId: 'req-2', feedIds: [feedId], spaceId });
+      expect(subRes.subscriptionId).toBeDefined();
+      expect(subRes.requestId).toBe('req-2');
+
+      // Query via Subscription
+      const queryRes = yield* feed.query({
+        requestId: 'req-3',
+        spaceId,
+        query: { subscriptionId: subRes.subscriptionId },
+        position: 0,
+      });
+      expect(queryRes.blocks.length).toBe(0);
+      expect(queryRes.requestId).toBe('req-3');
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('should assign monotonic insertionId', () =>
+    Effect.gen(function* () {
+      const feedStore = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feedStore.migrate();
+
+      const spaceId = SpaceId.random();
+
+      yield* feedStore.appendLocal([
+        {
+          spaceId,
+          feedId: 'feed-1',
+          feedNamespace: 'default',
+          data: new Uint8Array([1]),
+        },
+      ]);
+
+      yield* feedStore.appendLocal([
+        {
+          spaceId,
+          feedId: 'feed-2',
+          feedNamespace: 'default',
+          data: new Uint8Array([2]),
+        },
+      ]);
+
+      const result1 = yield* feedStore.query({
+        requestId: 'req1',
+        spaceId,
+        query: { feedIds: ['feed-1'] },
+        position: -1,
+      });
+
+      const result2 = yield* feedStore.query({
+        requestId: 'req2',
+        spaceId,
+        query: { feedIds: ['feed-2'] },
+        position: -1,
+      });
+
+      expect(result1.blocks[0].insertionId).toBeTypeOf('number');
+      expect(result2.blocks[0].insertionId).toBeTypeOf('number');
+      expect(result2.blocks[0].insertionId!).toBeGreaterThan(result1.blocks[0].insertionId!);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('should assign monotonic insertionId and support token based cursor', () =>
+    Effect.gen(function* () {
+      const feedStore = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feedStore.migrate();
+
+      const spaceId = SpaceId.random();
+
+      // Append interleaving blocks
+      yield* feedStore.appendLocal([
+        {
+          spaceId,
+          feedId: 'feed-1',
+          feedNamespace: 'default',
+          data: new Uint8Array([1]),
+        },
+      ]);
+      yield* feedStore.appendLocal([
+        {
+          spaceId,
+          feedId: 'feed-2',
+          feedNamespace: 'default',
+          data: new Uint8Array([2]),
+        },
+      ]);
+      yield* feedStore.appendLocal([
+        {
+          spaceId,
+          feedId: 'feed-1',
+          feedNamespace: 'default',
+          data: new Uint8Array([3]),
+        },
+      ]);
+
+      // Query all with feedId (simulating unified query with no cursor initially)
+      const feed1Res = yield* feedStore.query({
+        requestId: 'req1',
+        spaceId,
+        query: { feedIds: ['feed-1'] },
+        cursor: undefined,
+      });
+      const feed2Res = yield* feedStore.query({
+        requestId: 'req2',
+        spaceId,
+        query: { feedIds: ['feed-2'] },
+        cursor: undefined,
+      });
+
+      // Verify insertionId consistency
+      const block1 = feed1Res.blocks[0]; // data=[1]
+      const block2 = feed2Res.blocks[0]; // data=[2]
+      const block3 = feed1Res.blocks[1]; // data=[3]
+
+      expect(block1.insertionId).toBeLessThan(block2.insertionId!);
+      expect(block2.insertionId).toBeLessThan(block3.insertionId!);
+
+      // Verify Next Cursor format (Token|InsertionId)
+      expect(feed1Res.nextCursor).toBeDefined();
+      expect(feed1Res.nextCursor).toContain('|');
+
+      // Test Query with invalid cursor token
+      const invalidCursor = 'badtoken|0';
+      const result = yield* feedStore
+        .query({
+          requestId: 'req-bad',
+          spaceId,
+          query: { feedIds: ['feed-1'] },
+          cursor: invalidCursor as any,
+        })
+        .pipe(Effect.exit);
+
+      expect(result._tag).toBe('Failure');
+      if (result._tag === 'Failure') {
+        const cause: any = result.cause;
+
+        // Handling Effect Cause structure which might be diff in this version
+        // Ideally we use Cause.isDie(cause) -> error
+        // But for quick check:
+        let error = cause.value || cause.defect || cause;
+        if (cause._tag === 'Die') error = cause.value || cause.defect;
+
+        expect(error).toBeDefined();
+        expect(error.message).toBe('Cursor token mismatch');
+      }
+
+      // Test Query with VALID cursor
+      // Use the cursor from the first block of feed-1 to get the second block
+      // Construct cursor manually or assume we got it from somewhere.
+      // Actually `nextCursor` points to the END.
+      // Let's manually construct a cursor to point after the first item.
+      // We need the token.
+      // We can get it from nextCursor.
+      const token = feed1Res.nextCursor.split('|')[0];
+      const validCursor = `${token}|${block1.insertionId}`;
+
+      const nextRes = yield* feedStore.query({
+        requestId: 'req-next',
+        spaceId,
+        query: { feedIds: ['feed-1'] },
+        cursor: validCursor as any,
+      });
+
+      expect(nextRes.blocks.length).toBe(1);
+      expect(nextRes.blocks[0].data[0]).toBe(3);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('append local', () =>
+    Effect.gen(function* () {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+
+      const feed = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feed.migrate();
+
+      const blocks = yield* feed.appendLocal([
+        {
+          spaceId,
+          feedId,
+          feedNamespace: 'data',
+          data: new Uint8Array([1]),
+        },
+      ]);
+      expect(blocks.length).toBe(1);
+      expect(blocks[0].position).toBeNull();
+      expect(blocks[0].sequence).toBe(0);
+      expect(blocks[0].actorId).toBe(ALICE);
+      expect(blocks[0].predActorId).toBeNull();
+      expect(blocks[0].predSequence).toBeNull();
+      expect(blocks[0].timestamp).toBeGreaterThan(0);
+      expect(blocks[0].data).toEqual(new Uint8Array([1]));
+
+      // Query by feedId
+      const queryRes = yield* feed.query({ query: { feedIds: [feedId] }, position: -1, spaceId }); // Use position '-1' to get everything
+      expect(queryRes.blocks.length).toBe(1);
+      expect(queryRes.blocks.length).toBe(1);
+      expect(queryRes.blocks[0]).toMatchObject({ ...blocks[0], feedId, position: expect.any(Number) });
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('tailing a feed', () =>
+    Effect.gen(function* () {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+
+      const feed = new FeedStore({ localActorId: ALICE, assignPositions: true });
+      yield* feed.migrate();
+
+      yield* feed.appendLocal([
+        {
+          spaceId,
+          feedId,
+          feedNamespace: 'data',
+          data: new Uint8Array([1]),
+        },
+      ]);
+      const query1 = yield* feed.query({ spaceId, query: { feedIds: [feedId] } }); // Use position '-1' to get everything
+      log.info('query 1', { blocks: query1.blocks.length, cursor: query1.nextCursor });
+      expect(query1.blocks.length).toBe(1);
+
+      const query2 = yield* feed.query({ spaceId, query: { feedIds: [feedId] }, cursor: query1.nextCursor });
+      log.info('query 2', { blocks: query2.blocks.length, cursor: query2.nextCursor });
+      expect(query2.blocks.length).toBe(0);
+
+      yield* feed.appendLocal([
+        {
+          spaceId,
+          feedId,
+          feedNamespace: 'data',
+          data: new Uint8Array([2]),
+        },
+      ]);
+      const query3 = yield* feed.query({ spaceId, query: { feedIds: [feedId] }, cursor: query2.nextCursor });
+      log.info('query 3', { blocks: query3.blocks.length, cursor: query3.nextCursor });
+      expect(query3.blocks.length).toBe(1);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+});

package/src/feed-store.ts

@@ -0,0 +1,377 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SqlClient from '@effect/sql/SqlClient';
+import type * as SqlError from '@effect/sql/SqlError';
+import * as Effect from 'effect/Effect';
+
+import { Event } from '@dxos/async';
+
+import {
+  type AppendRequest,
+  type AppendResponse,
+  type Block,
+  FeedCursor,
+  type QueryRequest,
+  type QueryResponse,
+  type SubscribeRequest,
+  type SubscribeResponse,
+} from './protocol';
+
+export interface FeedStoreOptions {
+  localActorId: string;
+  assignPositions: boolean;
+}
+
+export class FeedStore {
+  constructor(private readonly _options: FeedStoreOptions) {}
+
+  readonly onNewBlocks = new Event<void>();
+
+  migrate = Effect.fn('FeedStore.migrate')(function* () {
+    const sql = yield* SqlClient.SqlClient;
+
+    // Feeds Table
+    yield* sql`CREATE TABLE IF NOT EXISTS feeds (
+        feedPrivateId INTEGER PRIMARY KEY AUTOINCREMENT,
+        spaceId TEXT NOT NULL,
+        feedId TEXT NOT NULL,
+        feedNamespace TEXT
+      )`;
+    yield* sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_feeds_spaceId_feedId ON feeds(spaceId, feedId)`;
+
+    // Blocks Table
+    yield* sql`CREATE TABLE IF NOT EXISTS blocks (
+        insertionId INTEGER PRIMARY KEY AUTOINCREMENT,
+        feedPrivateId INTEGER NOT NULL,
+        position INTEGER,
+        sequence INTEGER NOT NULL,
+        actorId TEXT NOT NULL,
+        predSequence INTEGER,
+        predActorId TEXT,
+        timestamp INTEGER NOT NULL,
+        data BLOB NOT NULL,
+        FOREIGN KEY(feedPrivateId) REFERENCES feeds(feedPrivateId)
+      )`;
+    yield* sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_blocks_feedPrivateId_position ON blocks(feedPrivateId, position)`;
+    yield* sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_blocks_feedPrivateId_sequence_actorId ON blocks(feedPrivateId, sequence, actorId)`;
+
+    // Subscriptions Table
+    yield* sql`CREATE TABLE IF NOT EXISTS subscriptions (
+          subscriptionId TEXT PRIMARY KEY,
+          expiresAt INTEGER NOT NULL,
+          feedPrivateIds TEXT NOT NULL -- JSON array
+      )`;
+
+    // Cursor Tokens Table
+    yield* sql`CREATE TABLE IF NOT EXISTS cursor_tokens (
+          spaceId TEXT PRIMARY KEY,
+          token TEXT NOT NULL
+      )`;
+  });
+
+  // Internal Logic
+
+  private _ensureFeed = Effect.fn('Feed.ensureFeed')(
+    (
+      spaceId: string,
+      feedId: string,
+      namespace?: string,
+    ): Effect.Effect<number, SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+
+        const rows = yield* sql<{ feedPrivateId: number }>`
+              SELECT feedPrivateId FROM feeds WHERE spaceId = ${spaceId} AND feedId = ${feedId}
+          `;
+        if (rows.length > 0) return rows[0].feedPrivateId;
+
+        const newRows = yield* sql<{ feedPrivateId: number }>`
+              INSERT INTO feeds (spaceId, feedId, feedNamespace) VALUES (${spaceId}, ${feedId}, ${namespace}) RETURNING feedPrivateId
+          `;
+        return newRows[0].feedPrivateId;
+      }),
+  );
+
+  private _ensureCursorToken = Effect.fn('Feed.ensureCursorToken')(
+    (spaceId: string): Effect.Effect<string, SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const rows = yield* sql<{ token: string }>`SELECT token FROM cursor_tokens WHERE spaceId = ${spaceId}`;
+        if (rows.length > 0) return rows[0].token;
+
+        const token = crypto.randomUUID().replace(/-/g, '').slice(0, 6);
+        yield* sql`INSERT INTO cursor_tokens (spaceId, token) VALUES (${spaceId}, ${token})`;
+        return token;
+      }),
+  );
+
+  // RPCs
+
+  query = Effect.fn('Feed.query')(
+    (request: QueryRequest): Effect.Effect<QueryResponse, SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+        let feedIds: string[] | undefined = [];
+        let cursorInsertionId = -1;
+        let cursorToken: string | undefined;
+
+        if (!request.spaceId) {
+          return yield* Effect.die(new Error('spaceId is required'));
+        }
+
+        if (request.cursor) {
+          const { token, insertionId } = decodeCursor(request.cursor as FeedCursor);
+          if (!token || insertionId === undefined || isNaN(insertionId)) {
+            return yield* Effect.die(new Error(`Invalid cursor format`));
+          }
+          cursorToken = token;
+          cursorInsertionId = insertionId;
+        }
+
+        // Validate Token if cursor used
+        const validCursorToken = yield* this._ensureCursorToken(request.spaceId);
+        if (request.cursor && cursorToken !== validCursorToken) {
+          return yield* Effect.die(new Error(`Cursor token mismatch`));
+        }
+
+        // If cursor is provided, we must validate it against the space token.
+        // If spaceId is not provided in request (e.g. feedIds query), we can't easily validate token unless we look up spaceId for feedIds.
+        // Ideally spaceId should be required for token validation.
+
+        /* 
+           Logic:
+           1. If `cursor` is present, it's `token|insertionId`.
+           2. If `position` is present, it's `position` (legacy/manual).
+           
+           We prioritize `cursor`.
+        */
+
+        const position = request.position ?? -1;
+
+        // Resolve Subscriptions or FeedIds
+        if ('subscriptionId' in request.query) {
+          const rows = yield* sql<{ feedPrivateIds: string; expiresAt: number }>`
+                SELECT feedPrivateIds, expiresAt FROM subscriptions WHERE subscriptionId = ${request.query.subscriptionId}
+            `;
+          if (rows.length > 0) {
+            const { feedPrivateIds, expiresAt } = rows[0];
+            if (Date.now() <= expiresAt) {
+              const privateIds = JSON.parse(feedPrivateIds) as number[];
+              if (privateIds.length > 0) {
+                const feedRows = yield* sql<{ feedId: string }>`
+                             SELECT feedId FROM feeds WHERE feedPrivateId IN ${sql.in(privateIds)}
+                         `;
+                feedIds = feedRows.map((r) => r.feedId);
+              }
+            }
+          }
+        } else if ('feedIds' in request.query) {
+          feedIds = [...(request.query as any).feedIds];
+        } else {
+          feedIds = undefined;
+        }
+
+        if (feedIds !== undefined && feedIds.length === 0) {
+          return { requestId: request.requestId, blocks: [], nextCursor: encodeCursor(validCursorToken, -1) };
+        }
+
+        // Fetch Blocks
+        const query = sql<Block>`
+            SELECT blocks.*, feeds.feedId
+            FROM blocks
+            JOIN feeds ON blocks.feedPrivateId = feeds.feedPrivateId
+            WHERE 1=1
+            ${feedIds !== undefined ? sql`AND feeds.feedId IN ${sql.in(feedIds)}` : sql``}
+            ${request.spaceId ? sql`AND feeds.spaceId = ${request.spaceId}` : sql``}
+            ${
+              'feedNamespace' in request.query && request.query.feedNamespace
+                ? sql`AND feeds.feedNamespace = ${request.query.feedNamespace}`
+                : sql``
+            }
+        `;
+
+        // Add filter based on cursor or position
+        const filter = request.cursor
+          ? sql`AND blocks.insertionId > ${cursorInsertionId}`
+          : sql`AND (blocks.position > ${position} OR blocks.position IS NULL)`;
+
+        const orderBy = request.cursor
+          ? sql`ORDER BY blocks.insertionId ASC`
+          : sql`ORDER BY blocks.position ASC NULLS LAST`;
+
+        const rows = yield* sql<Block>`
+            ${query}
+            ${filter}
+            ${orderBy}
+            ${request.limit ? sql`LIMIT ${request.limit}` : sql``}
+        `;
+
+        const blocks = rows.map((row) => ({
+          ...row,
+          // Have to buffer otherwise we get empty Uint8Array.
+          data: new Uint8Array(row.data),
+        }));
+
+        let nextCursor: FeedCursor = request.cursor ?? encodeCursor(validCursorToken, -1);
+        if (blocks.length > 0 && request.spaceId) {
+          const lastBlock = blocks[blocks.length - 1];
+          if (lastBlock.insertionId !== undefined) {
+            nextCursor = encodeCursor(validCursorToken, lastBlock.insertionId);
+          }
+        }
+
+        return { requestId: request.requestId, blocks, nextCursor } satisfies QueryResponse;
+      }),
+  );
+
+  subscribe = Effect.fn('Feed.subscribe')(
+    (request: SubscribeRequest): Effect.Effect<SubscribeResponse, SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const ttl = 60 * 60 * 1000;
+        const subscriptionId = crypto.randomUUID();
+        const expiresAt = Date.now() + ttl;
+
+        if (!request.spaceId) {
+          // TODO(dmaretskyi): Define error type.
+          return yield* Effect.die(new Error('spaceId required for subscribe'));
+        }
+
+        const feedPrivateIds = yield* Effect.forEach(
+          request.feedIds,
+          (feedId) => this._ensureFeed(request.spaceId!, feedId),
+          { concurrency: 'unbounded' },
+        );
+
+        yield* sql`
+            INSERT INTO subscriptions (subscriptionId, expiresAt, feedPrivateIds)
+            VALUES (${subscriptionId}, ${expiresAt}, ${JSON.stringify(feedPrivateIds)})
+        `;
+
+        return {
+          requestId: request.requestId,
+          subscriptionId,
+          expiresAt,
+        };
+      }),
+  );
+
+  append = Effect.fn('Feed.append')(
+    (request: AppendRequest): Effect.Effect<AppendResponse, SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const positions: number[] = [];
+
+        if (!request.spaceId) {
+          return yield* Effect.die(new Error('spaceId required for append'));
+        }
+
+        for (const block of request.blocks) {
+          const feedId = request.feedId ?? block.actorId;
+          const feedPrivateId = yield* this._ensureFeed(request.spaceId, feedId, request.namespace);
+
+          let nextPos = null;
+          if (this._options.assignPositions) {
+            const maxPosResult = yield* sql<{ maxPos: number | null }>`
+                  SELECT MAX(position) as maxPos 
+                  FROM blocks 
+                  JOIN feeds ON blocks.feedPrivateId = feeds.feedPrivateId
+                  WHERE feeds.spaceId = ${request.spaceId}
+              `;
+            nextPos = (maxPosResult[0]?.maxPos ?? -1) + 1;
+            positions.push(nextPos);
+          }
+
+          yield* sql`
+                INSERT INTO blocks (
+                    feedPrivateId, position, sequence, actorId, 
+                    predSequence, predActorId, timestamp, data
+                ) VALUES (
+                    ${feedPrivateId}, ${nextPos}, ${block.sequence}, ${block.actorId},
+                    ${block.predSequence}, ${block.predActorId}, ${block.timestamp}, ${block.data}
+                ) ON CONFLICT DO NOTHING
+            `;
+        }
+
+        this.onNewBlocks.emit();
+
+        return { requestId: request.requestId, positions };
+      }),
+  );
+
+  appendLocal = Effect.fn('Feed.appendLocal')(
+    (
+      messages: { spaceId: string; feedId: string; feedNamespace: string; data: Uint8Array }[],
+    ): Effect.Effect<Block[], SqlError.SqlError, SqlClient.SqlClient> =>
+      Effect.gen(this, function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const blocks: Block[] = [];
+
+        // Group by spaceId for efficient processing? Or just iterate.
+        // Assuming small batch.
+
+        for (const msg of messages) {
+          // Get last block for this feed to determine sequence and predecessor.
+          // Assumes we are the writer (localActorId).
+          // If we are not localActorId, we shouldn't be creating blocks this way?
+          // The user said: "uses local actorId". So feedId in message might be ignored?
+          // Or message provides feedId?
+          // User said: "client provides (only data + spaceId, feedId, feedNamespace)".
+          // If client provides feedId, does it match localActorId?
+          // If localActorId is fixed for the device, and we are appending to "my" feed, feedId should be localActorId.
+          // If the client explicitly passes feedId, maybe they want to write to a specific feed (e.g. if they have multiple identities?).
+          // But spec says "uses local actorId". I will use `this._options.localActorId`.
+          // But `messages` arg has `feedId`.
+          // I'll assume `msg.feedId` must match `localActorId` or we just use `localActorId` and ignore `msg.feedId`?
+          // User: "client provides ... feedId".
+          // I will use passed feedId but it should probably match localActorId if we are signing? (No signing here yet).
+          // I'll use passed `feedId`.
+
+          const feedPrivateId = yield* this._ensureFeed(msg.spaceId, msg.feedId, msg.feedNamespace);
+
+          // Get last block to determine sequence.
+          const lastBlockResult = yield* sql<{ sequence: number; actorId: string }>`
+              SELECT sequence, actorId FROM blocks 
+              WHERE feedPrivateId = ${feedPrivateId} 
+              ORDER BY sequence DESC 
+              LIMIT 1
+           `; // This gets checks only THIS feed.
+
+          const lastBlock = lastBlockResult[0];
+          const sequence = (lastBlock?.sequence ?? -1) + 1;
+          const predSequence = lastBlock?.sequence ?? null;
+          const predActorId = lastBlock?.actorId ?? null;
+
+          const block: Block = {
+            feedId: undefined,
+            actorId: this._options.localActorId,
+            sequence,
+            predActorId,
+            predSequence,
+            timestamp: Date.now(),
+            data: msg.data,
+            position: null, // assigned by append
+          };
+          blocks.push(block);
+
+          // Call append to persist (and assign position if allowed).
+          yield* this.append({
+            requestId: 'local-append',
+            namespace: msg.feedNamespace,
+            blocks: [block],
+            spaceId: msg.spaceId,
+            feedId: msg.feedId,
+          });
+        }
+        return blocks;
+      }),
+  );
+}
+
+const encodeCursor = (token: string, insertionId: number) => FeedCursor.make(`${token}|${insertionId}`);
+const decodeCursor = (cursor: FeedCursor) => {
+  const [token, insertionId] = cursor.split('|');
+  return { token, insertionId: Number(insertionId) };
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './feed-store';
+export * from './protocol';

package/src/protocol.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+export const FeedCursor = Schema.String.pipe(Schema.brand('@dxos/feed/FeedCursor'));
+export type FeedCursor = Schema.Schema.Type<typeof FeedCursor>;
+
+export const Block = Schema.Struct({
+  /**
+   * Only set on query.
+   */
+  feedId: Schema.UndefinedOr(Schema.String),
+
+  actorId: Schema.String,
+  sequence: Schema.Number,
+  predActorId: Schema.NullOr(Schema.String),
+  predSequence: Schema.NullOr(Schema.Number),
+  position: Schema.NullOr(Schema.Number),
+  timestamp: Schema.Number,
+  data: Schema.Uint8Array,
+
+  /**
+   * Local insertion ID.
+   * Not replicated.
+   */
+  // TODO(dmaretskyi): Remove. Use cursors.
+  insertionId: Schema.optional(Schema.Number),
+});
+export interface Block extends Schema.Schema.Type<typeof Block> {}
+
+//
+// RPC Schemas
+//
+
+// Request is a union of query by subscription or query by feedIds
+export const QueryRequest = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+
+  // TODO(dmaretskyi): Make required.
+  spaceId: Schema.optional(Schema.String),
+
+  query: Schema.Union(
+    Schema.Struct({
+      feedIds: Schema.Array(Schema.String),
+    }),
+    Schema.Struct({
+      subscriptionId: Schema.String,
+    }),
+    Schema.Struct({
+      feedNamespace: Schema.optional(Schema.String),
+    }),
+  ),
+  /**
+   * Get changes following this cursor (exclusive).
+   *
+   * Must not be used with `position`.
+   */
+  cursor: Schema.optional(FeedCursor),
+
+  /**
+   * Get changes following this position.
+   *
+   * Must not be used with `cursor`.
+   */
+  position: Schema.optional(Schema.Number),
+
+  limit: Schema.optional(Schema.Number),
+});
+export interface QueryRequest extends Schema.Schema.Type<typeof QueryRequest> {}
+
+// Response is a stream/array of blocks
+export const QueryResponse = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  nextCursor: FeedCursor,
+  blocks: Schema.Array(Block),
+});
+export interface QueryResponse extends Schema.Schema.Type<typeof QueryResponse> {}
+
+export const SubscribeRequest = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  feedIds: Schema.Array(Schema.String),
+  spaceId: Schema.optional(Schema.String),
+});
+export interface SubscribeRequest extends Schema.Schema.Type<typeof SubscribeRequest> {}
+
+export const SubscribeResponse = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  subscriptionId: Schema.String,
+  expiresAt: Schema.Number,
+});
+export interface SubscribeResponse extends Schema.Schema.Type<typeof SubscribeResponse> {}
+
+export const AppendRequest = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+
+  spaceId: Schema.String,
+  namespace: Schema.String,
+  feedId: Schema.String,
+
+  blocks: Schema.Array(Block),
+});
+export interface AppendRequest extends Schema.Schema.Type<typeof AppendRequest> {}
+
+export const AppendResponse = Schema.Struct({
+  requestId: Schema.optional(Schema.String),
+  positions: Schema.Array(Schema.Number),
+});
+export interface AppendResponse extends Schema.Schema.Type<typeof AppendResponse> {}

package/src/sync.test.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SqlClient from '@effect/sql/SqlClient';
+import * as SqliteClient from '@effect/sql-sqlite-node/SqliteClient';
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+
+import { SpaceId } from '@dxos/keys';
+
+import { FeedStore } from './feed-store';
+import { type Block } from './protocol';
+
+describe.skip('Feed Sync V2 (RPC)', () => {
+  const makePeer = () => {
+    const layer = SqliteClient.layer({ filename: ':memory:' });
+    const runtime = ManagedRuntime.make(layer);
+    const run = <A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>) => runtime.runPromise(effect);
+    return { run };
+  };
+
+  it('should sync blocks from server to client via RPC', async () => {
+    const server = makePeer();
+    const client = makePeer();
+
+    const spaceId = SpaceId.random();
+    const feedId = '01H1V1X1X1X1X1X1X1X1X1X1X3';
+
+    // Server setup: Append blocks
+    await server.run(
+      Effect.gen(function* () {
+        const feed = new FeedStore({ localActorId: 'server', assignPositions: true });
+        const blocks: Block[] = [
+          {
+            feedId: undefined,
+            actorId: feedId,
+            sequence: 1,
+            predActorId: null,
+            predSequence: null,
+            position: null,
+            timestamp: 100,
+            data: new Uint8Array([1]),
+          },
+          {
+            feedId: undefined,
+            actorId: feedId,
+            sequence: 2,
+            predActorId: feedId,
+            predSequence: 1,
+            position: null,
+            timestamp: 200,
+            data: new Uint8Array([2]),
+          },
+        ];
+        yield* feed.append({ requestId: 'req-0', blocks, spaceId, namespace: 'data', feedId });
+      }),
+    );
+
+    // Sync Simulation: Client polls Server
+    // 1. Client subscribes
+    const subId = await server.run(
+      Effect.gen(function* () {
+        // Wait, we flattened it. Tests need to update to NOT use SqlFeedStore!
+        // I will fix the class instantiation in a moment.
+        const feed = new FeedStore({ localActorId: 'server', assignPositions: true });
+        const res = yield* feed.subscribe({ requestId: 'req-sub', feedIds: [feedId], spaceId });
+        return res.subscriptionId;
+      }),
+    );
+
+    // 2. Client queries using subscription
+    const blocks = await server.run(
+      Effect.gen(function* () {
+        const feed = new FeedStore({ localActorId: 'server', assignPositions: true }); // Updated class usage
+        const res = yield* feed.query({ requestId: 'req-query', query: { subscriptionId: subId }, position: 0 });
+        return res.blocks;
+      }),
+    );
+
+    expect(blocks.length).toBe(2);
+    expect(blocks[0].sequence).toBe(1);
+
+    // 3. Client stores them (Verify client persistence)
+    await client.run(
+      Effect.gen(function* () {
+        const feed = new FeedStore({ localActorId: 'client', assignPositions: true }); // Updated class usage
+        // Client appends them.
+        yield* feed.append({ requestId: 'req-push', blocks, spaceId, namespace: 'data', feedId });
+
+        // Verify
+        const myBlocks = yield* feed.query({
+          requestId: 'req-verify',
+          query: { feedIds: [feedId] },
+          position: 0,
+          spaceId,
+        });
+        expect(myBlocks.blocks.length).toBe(2);
+      }),
+    );
+  });
+});

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export {};