Serve replicated records via XRPC read endpoints

Replicated repos' blocks are in IPFS but weren't queryable via standard
atproto endpoints. This adds an IpfsReadableBlockstore adapter and
ReplicatedRepoReader service that loads ReadableRepo instances on demand,
making getRecord, listRecords, and describeRepo work for replicated DIDs.

Also fixes rev extraction: syncDid() now decodes the commit block CBOR to
get the actual TID rev (instead of storing the root CID as rev), and stores
both root_cid and rev separately in replication_state.

src/index.ts

···
 import type { BlockStore, NetworkService } from "./ipfs.js";
 import type { BlobStore } from "./blobs.js";
 import type { ReplicationManager } from "./replication/replication-manager.js";
+import type { ReplicatedRepoReader } from "./replication/replicated-repo-reader.js";
 import * as sync from "./xrpc/sync.js";
 import * as repo from "./xrpc/repo.js";
 import * as server from "./xrpc/server.js";
···
 	networkService?: NetworkService,
 	blobStore?: BlobStore,
 	replicationManager?: ReplicationManager,
+	replicatedRepoReader?: ReplicatedRepoReader,
 ) {
 	const app = new Hono<{ Bindings: Config }>();
 
···
 		sync.getRepo(c, repoManager),
 	);
 	app.get("/xrpc/com.atproto.sync.getRepoStatus", (c) =>
-		sync.getRepoStatus(c, repoManager),
+		sync.getRepoStatus(c, repoManager, replicatedRepoReader),
 	);
 	app.get("/xrpc/com.atproto.sync.getBlocks", (c) =>
 		sync.getBlocks(c, repoManager),
···
 		sync.getBlob(c, repoManager),
 	);
 	app.get("/xrpc/com.atproto.sync.listRepos", (c) =>
-		sync.listRepos(c, repoManager),
+		sync.listRepos(c, repoManager, replicatedRepoReader),
 	);
 	app.get("/xrpc/com.atproto.sync.listBlobs", (c) =>
 		sync.listBlobs(c, repoManager),
···
 		if (!requestedRepo || requestedRepo === config.DID) {
 			return repo.describeRepo(c, repoManager);
 		}
+		if (
+			replicatedRepoReader &&
+			requestedRepo &&
+			replicatedRepoReader.isReplicatedDid(requestedRepo)
+		) {
+			return repo.describeRepoReplicated(c, replicatedRepoReader, requestedRepo);
+		}
 		await next();
 	});
 
···
 		if (!requestedRepo || requestedRepo === config.DID) {
 			return repo.getRecord(c, repoManager);
 		}
+		if (
+			replicatedRepoReader &&
+			requestedRepo &&
+			replicatedRepoReader.isReplicatedDid(requestedRepo)
+		) {
+			return repo.getRecordReplicated(c, replicatedRepoReader, requestedRepo);
+		}
 		await next();
 	});
 
···
 		const requestedRepo = c.req.query("repo");
 		if (!requestedRepo || requestedRepo === config.DID) {
 			return repo.listRecords(c, repoManager);
+		}
+		if (
+			replicatedRepoReader &&
+			requestedRepo &&
+			replicatedRepoReader.isReplicatedDid(requestedRepo)
+		) {
+			return repo.listRecordsReplicated(c, replicatedRepoReader, requestedRepo);
 		}
 		await next();
 	});

src/replication/ipfs-readable-blockstore.ts

···
+/**
+ * Adapter: wraps our BlockStore interface to implement @atproto/repo's
+ * ReadableBlockstore abstract class (getBytes, has, getBlocks).
+ */
+
+import { CID } from "multiformats";
+import { ReadableBlockstore, BlockMap } from "@atproto/repo";
+import type { BlockStore } from "../ipfs.js";
+
+export class IpfsReadableBlockstore extends ReadableBlockstore {
+	constructor(private blockStore: BlockStore) {
+		super();
+	}
+
+	async getBytes(cid: CID): Promise<Uint8Array | null> {
+		return this.blockStore.getBlock(cid.toString());
+	}
+
+	async has(cid: CID): Promise<boolean> {
+		return this.blockStore.hasBlock(cid.toString());
+	}
+
+	async getBlocks(cids: CID[]): Promise<{ blocks: BlockMap; missing: CID[] }> {
+		const blocks = new BlockMap();
+		const missing: CID[] = [];
+		for (const cid of cids) {
+			const bytes = await this.blockStore.getBlock(cid.toString());
+			if (bytes) {
+				blocks.set(cid, bytes);
+			} else {
+				missing.push(cid);
+			}
+		}
+		return { blocks, missing };
+	}
+}

src/replication/replicated-repo-reader.ts

···
+/**
+ * Service that loads and caches ReadableRepo instances for replicated DIDs.
+ * Provides read-only access to replicated repo data via IPFS blocks.
+ */
+
+import { CID } from "multiformats";
+import { ReadableRepo } from "@atproto/repo/dist/readable-repo.js";
+import type { BlockStore } from "../ipfs.js";
+import { IpfsReadableBlockstore } from "./ipfs-readable-blockstore.js";
+import type { SyncStorage } from "./sync-storage.js";
+
+export class ReplicatedRepoReader {
+	private cache = new Map<string, ReadableRepo>();
+	private readableBlockstore: IpfsReadableBlockstore;
+
+	constructor(
+		blockStore: BlockStore,
+		private syncStorage: SyncStorage,
+	) {
+		this.readableBlockstore = new IpfsReadableBlockstore(blockStore);
+	}
+
+	/**
+	 * Check if a DID is tracked for replication.
+	 */
+	isReplicatedDid(did: string): boolean {
+		const state = this.syncStorage.getState(did);
+		return state !== null;
+	}
+
+	/**
+	 * Load a ReadableRepo for a replicated DID (cached until invalidated).
+	 */
+	async getRepo(did: string): Promise<ReadableRepo | null> {
+		const cached = this.cache.get(did);
+		if (cached) return cached;
+
+		const state = this.syncStorage.getState(did);
+		if (!state?.rootCid) return null;
+
+		try {
+			const commitCid = CID.parse(state.rootCid);
+			const repo = await ReadableRepo.load(
+				this.readableBlockstore,
+				commitCid,
+			);
+			this.cache.set(did, repo);
+			return repo;
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * Get a single record from a replicated repo.
+	 */
+	async getRecord(
+		did: string,
+		collection: string,
+		rkey: string,
+	): Promise<{ cid: string; value: unknown } | null> {
+		const repo = await this.getRepo(did);
+		if (!repo) return null;
+
+		// Get the record CID from the MST
+		const key = `${collection}/${rkey}`;
+		const recordCid = await repo.data.get(key);
+		if (!recordCid) return null;
+
+		// Read the record value
+		const value = await repo.getRecord(collection, rkey);
+		if (value === null) return null;
+
+		return { cid: recordCid.toString(), value };
+	}
+
+	/**
+	 * List records from a collection in a replicated repo.
+	 */
+	async listRecords(
+		did: string,
+		collection: string,
+		opts: { limit?: number; cursor?: string; reverse?: boolean } = {},
+	): Promise<{
+		records: Array<{ uri: string; cid: string; value: unknown }>;
+		cursor?: string;
+	}> {
+		const repo = await this.getRepo(did);
+		if (!repo) return { records: [] };
+
+		const limit = opts.limit ?? 50;
+		const prefix = `${collection}/`;
+		const records: Array<{ uri: string; cid: string; value: unknown }> = [];
+
+		// Use walkRecords with a starting key for cursor support
+		const startKey = opts.cursor
+			? `${collection}/${opts.cursor}`
+			: collection;
+
+		// Collect matching records via MST list
+		// MST.list(count, after, before) returns Leaf[] sorted by key
+		const leaves = opts.reverse
+			? await repo.data.list(undefined, undefined, `${collection}0`)
+			: await repo.data.list(
+					undefined,
+					opts.cursor ? `${collection}/${opts.cursor}` : undefined,
+				);
+
+		for (const leaf of leaves) {
+			if (records.length >= limit) break;
+			if (!leaf.key.startsWith(prefix)) {
+				// If we've passed the collection prefix, stop
+				if (leaf.key > prefix + "\xff") break;
+				continue;
+			}
+
+			const rkey = leaf.key.slice(prefix.length);
+			const value = await this.readableBlockstore.attemptReadRecord(
+				leaf.value,
+			);
+			if (value !== null) {
+				records.push({
+					uri: `at://${did}/${collection}/${rkey}`,
+					cid: leaf.value.toString(),
+					value,
+				});
+			}
+		}
+
+		if (opts.reverse) {
+			records.reverse();
+		}
+
+		const result: {
+			records: Array<{ uri: string; cid: string; value: unknown }>;
+			cursor?: string;
+		} = { records };
+
+		if (records.length === limit) {
+			const lastRecord = records[records.length - 1]!;
+			const lastUri = lastRecord.uri;
+			// cursor is the rkey of the last record
+			result.cursor = lastUri.split("/").pop()!;
+		}
+
+		return result;
+	}
+
+	/**
+	 * Describe a replicated repo (list collections).
+	 */
+	async describeRepo(
+		did: string,
+	): Promise<{ did: string; collections: string[] } | null> {
+		const repo = await this.getRepo(did);
+		if (!repo) return null;
+
+		const collections = new Set<string>();
+		for await (const entry of repo.walkRecords()) {
+			collections.add(entry.collection);
+		}
+
+		return { did, collections: Array.from(collections).sort() };
+	}
+
+	/**
+	 * Get repo status for a replicated DID.
+	 */
+	getRepoStatus(
+		did: string,
+	): { did: string; rev: string | null; rootCid: string | null; active: boolean } | null {
+		const state = this.syncStorage.getState(did);
+		if (!state) return null;
+
+		return {
+			did,
+			rev: state.lastSyncRev,
+			rootCid: state.rootCid,
+			active: state.status === "synced",
+		};
+	}
+
+	/**
+	 * Get repo statuses for all replicated DIDs.
+	 */
+	getAllRepoStatuses(): Array<{
+		did: string;
+		rev: string | null;
+		rootCid: string | null;
+		active: boolean;
+	}> {
+		return this.syncStorage.getAllStates().map((state) => ({
+			did: state.did,
+			rev: state.lastSyncRev,
+			rootCid: state.rootCid,
+			active: state.status === "synced",
+		}));
+	}
+
+	/**
+	 * Invalidate the cached ReadableRepo for a DID (call after sync).
+	 */
+	invalidateCache(did: string): void {
+		this.cache.delete(did);
+	}
+}

src/replication/replication-manager.ts

···
 import type { BlockStore, NetworkService } from "../ipfs.js";
 import type { DidResolver } from "../did-resolver.js";
 import { readCarWithRoot } from "@atproto/repo";
+import { decode as cborDecode } from "../cbor-compat.js";
+import type { ReplicatedRepoReader } from "./replicated-repo-reader.js";
 
 import {
 	PEER_NSID,
···
 		private networkService: NetworkService,
 		private didResolver: DidResolver,
 		verificationConfig?: Partial<VerificationConfig>,
+		private replicatedRepoReader?: ReplicatedRepoReader,
 	) {
 		this.syncStorage = new SyncStorage(db);
 		this.repoFetcher = new RepoFetcher(didResolver);
···
 		}
 		this.syncStorage.updateVerifiedAt(did);
 
-		// 8. Determine rev from the root commit
-		// The root CID string serves as a rev identifier when we can't extract the actual rev
-		const rev = root.toString();
+		// 8. Extract actual rev from the commit block
+		const rootCidStr = root.toString();
+		let rev = rootCidStr; // fallback
+		const commitBytes = internalMap?.get(rootCidStr);
+		if (commitBytes) {
+			try {
+				const commitObj = cborDecode(commitBytes) as Record<string, unknown>;
+				if (typeof commitObj.rev === "string") {
+					rev = commitObj.rev;
+				}
+			} catch {
+				// If CBOR decode fails, fall back to root CID as rev
+			}
+		}
+
+		// 9. Update sync state with both rev and root CID
+		this.syncStorage.updateSyncProgress(did, rev, rootCidStr);
 
-		// 9. Update sync state
-		this.syncStorage.updateSyncProgress(did, rev);
+		// 9b. Invalidate cached ReadableRepo so it reloads with new root
+		this.replicatedRepoReader?.invalidateCache(did);
 
 		// 10. Update manifest record
 		const rkey = didToRkey(did);
···
 		}
 
 		return result;
+	}
+
+	/**
+	 * Get the underlying SyncStorage instance.
+	 */
+	getSyncStorage(): SyncStorage {
+		return this.syncStorage;
+	}
+
+	/**
+	 * Set the replicated repo reader for cache invalidation after sync.
+	 */
+	setReplicatedRepoReader(reader: ReplicatedRepoReader): void {
+		this.replicatedRepoReader = reader;
 	}
 
 	/**

src/replication/replication.test.ts

···
 import { BlockVerifier, RemoteVerifier } from "./verification.js";
 import { RepoFetcher, extractPdsEndpoint } from "./repo-fetcher.js";
 import { PeerDiscovery } from "./peer-discovery.js";
+import { IpfsReadableBlockstore } from "./ipfs-readable-blockstore.js";
+import { ReplicatedRepoReader } from "./replicated-repo-reader.js";
+import { decode as cborDecode } from "../cbor-compat.js";
+import { Firehose } from "../firehose.js";
+import { createApp } from "../index.js";
 
 /** Create a CID string from raw bytes using SHA-256. */
 async function makeCidStr(bytes: Uint8Array): Promise<string> {
···
 		expect(layer1!.checked).toBe(5);
 	});
 });
+
+// ============================================
+// IpfsReadableBlockstore
+// ============================================
+
+describe("IpfsReadableBlockstore", () => {
+	let tmpDir: string;
+	let ipfsService: IpfsService;
+	let readableBlockstore: IpfsReadableBlockstore;
+
+	beforeEach(async () => {
+		tmpDir = mkdtempSync(join(tmpdir(), "ipfs-readable-bs-test-"));
+		ipfsService = new IpfsService({
+			blocksPath: join(tmpDir, "blocks"),
+			datastorePath: join(tmpDir, "datastore"),
+			networking: false,
+		});
+		await ipfsService.start();
+		readableBlockstore = new IpfsReadableBlockstore(ipfsService);
+	});
+
+	afterEach(async () => {
+		if (ipfsService.isRunning()) await ipfsService.stop();
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("getBytes roundtrip", async () => {
+		const bytes = new TextEncoder().encode("readable-test");
+		const cidStr = await makeCidStr(bytes);
+		await ipfsService.putBlock(cidStr, bytes);
+
+		const { CID: MfCID } = await import("multiformats");
+		const cid = MfCID.parse(cidStr);
+		const result = await readableBlockstore.getBytes(cid);
+		expect(result).not.toBeNull();
+		expect(Buffer.from(result!)).toEqual(Buffer.from(bytes));
+	});
+
+	it("has returns true/false correctly", async () => {
+		const bytes = new TextEncoder().encode("has-test");
+		const cidStr = await makeCidStr(bytes);
+		await ipfsService.putBlock(cidStr, bytes);
+
+		const { CID: MfCID } = await import("multiformats");
+		const present = MfCID.parse(cidStr);
+		expect(await readableBlockstore.has(present)).toBe(true);
+
+		const missingBytes = new TextEncoder().encode("missing-test");
+		const missingCidStr = await makeCidStr(missingBytes);
+		const missing = MfCID.parse(missingCidStr);
+		expect(await readableBlockstore.has(missing)).toBe(false);
+	});
+
+	it("getBlocks returns blocks + missing", async () => {
+		const bytes1 = new TextEncoder().encode("block-a");
+		const cidStr1 = await makeCidStr(bytes1);
+		await ipfsService.putBlock(cidStr1, bytes1);
+
+		const bytes2 = new TextEncoder().encode("block-b-missing");
+		const cidStr2 = await makeCidStr(bytes2);
+
+		const { CID: MfCID } = await import("multiformats");
+		const cid1 = MfCID.parse(cidStr1);
+		const cid2 = MfCID.parse(cidStr2);
+
+		const { blocks, missing } = await readableBlockstore.getBlocks([
+			cid1,
+			cid2,
+		]);
+		expect(blocks.has(cid1)).toBe(true);
+		expect(missing).toHaveLength(1);
+		expect(missing[0]!.toString()).toBe(cidStr2);
+	});
+});
+
+// ============================================
+// ReplicatedRepoReader
+// ============================================
+
+describe("ReplicatedRepoReader", () => {
+	let tmpDir: string;
+	let sourceDb: InstanceType<typeof Database>;
+	let replicaDb: InstanceType<typeof Database>;
+	let sourceIpfs: IpfsService;
+	let replicaIpfs: IpfsService;
+	let sourceRepo: RepoManager;
+	let syncStorage: SyncStorage;
+	let reader: ReplicatedRepoReader;
+	const sourceDid = "did:plc:test123";
+
+	beforeEach(async () => {
+		tmpDir = mkdtempSync(join(tmpdir(), "replicated-reader-test-"));
+
+		// Source setup
+		const sourceConfig = testConfig(join(tmpDir, "source"), []);
+		sourceDb = new Database(join(tmpDir, "source.db"));
+		sourceIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "source-ipfs-blocks"),
+			datastorePath: join(tmpDir, "source-ipfs-datastore"),
+			networking: false,
+		});
+		await sourceIpfs.start();
+		sourceRepo = new RepoManager(sourceDb, sourceConfig);
+		sourceRepo.init(undefined, sourceIpfs, sourceIpfs);
+
+		// Replica IPFS + sync storage
+		replicaDb = new Database(join(tmpDir, "replica.db"));
+		replicaIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "replica-ipfs-blocks"),
+			datastorePath: join(tmpDir, "replica-ipfs-datastore"),
+			networking: false,
+		});
+		await replicaIpfs.start();
+
+		syncStorage = new SyncStorage(replicaDb);
+		syncStorage.initSchema();
+
+		reader = new ReplicatedRepoReader(replicaIpfs, syncStorage);
+	});
+
+	afterEach(async () => {
+		if (sourceIpfs.isRunning()) await sourceIpfs.stop();
+		if (replicaIpfs.isRunning()) await replicaIpfs.stop();
+		sourceDb.close();
+		replicaDb.close();
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	/** Helper: create records in source, export CAR, store blocks in replica IPFS, record root_cid. */
+	async function replicateSource(): Promise<{ rootCid: string; rev: string }> {
+		const carBytes = await sourceRepo.getRepoCar();
+		const { root, blocks } = await readCarWithRoot(carBytes);
+		await replicaIpfs.putBlocks(blocks);
+
+		const rootCidStr = root.toString();
+
+		// Extract rev from commit block
+		const internalMap = (
+			blocks as unknown as { map: Map<string, Uint8Array> }
+		).map;
+		let rev = rootCidStr;
+		const commitBytes = internalMap?.get(rootCidStr);
+		if (commitBytes) {
+			const commitObj = cborDecode(commitBytes) as Record<string, unknown>;
+			if (typeof commitObj.rev === "string") {
+				rev = commitObj.rev;
+			}
+		}
+
+		// Record in sync storage
+		syncStorage.upsertState({
+			did: sourceDid,
+			pdsEndpoint: "https://pds.example.com",
+		});
+		syncStorage.updateSyncProgress(sourceDid, rev, rootCidStr);
+
+		return { rootCid: rootCidStr, rev };
+	}
+
+	it("returns null for unknown DID", async () => {
+		const result = await reader.getRecord(
+			"did:plc:unknown",
+			"app.bsky.feed.post",
+			"abc",
+		);
+		expect(result).toBeNull();
+		expect(reader.isReplicatedDid("did:plc:unknown")).toBe(false);
+	});
+
+	it("getRecord returns record with correct CID and value", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "Hello replicated!",
+			createdAt: "2025-01-01T00:00:00.000Z",
+		});
+		await replicateSource();
+
+		// List records from source to get the rkey
+		const sourceRecords = await sourceRepo.listRecords("app.bsky.feed.post", {
+			limit: 10,
+		});
+		const firstRecord = sourceRecords.records[0]!;
+		const rkey = firstRecord.uri.split("/").pop()!;
+
+		const result = await reader.getRecord(
+			sourceDid,
+			"app.bsky.feed.post",
+			rkey,
+		);
+		expect(result).not.toBeNull();
+		expect(result!.cid).toBeDefined();
+		expect(typeof result!.cid).toBe("string");
+		const value = result!.value as Record<string, unknown>;
+		expect(value.text).toBe("Hello replicated!");
+	});
+
+	it("listRecords returns records with cursor support", async () => {
+		// Create multiple records
+		for (let i = 0; i < 5; i++) {
+			await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+				$type: "app.bsky.feed.post",
+				text: `Post ${i}`,
+				createdAt: new Date().toISOString(),
+			});
+		}
+		await replicateSource();
+
+		// First page
+		const page1 = await reader.listRecords(sourceDid, "app.bsky.feed.post", {
+			limit: 3,
+		});
+		expect(page1.records).toHaveLength(3);
+		expect(page1.cursor).toBeDefined();
+
+		// Second page
+		const page2 = await reader.listRecords(sourceDid, "app.bsky.feed.post", {
+			limit: 3,
+			cursor: page1.cursor,
+		});
+		expect(page2.records).toHaveLength(2);
+
+		// All records have correct URIs
+		for (const rec of [...page1.records, ...page2.records]) {
+			expect(rec.uri).toMatch(
+				new RegExp(`^at://${sourceDid}/app\\.bsky\\.feed\\.post/`),
+			);
+			expect(rec.cid).toBeDefined();
+			expect(rec.value).toBeDefined();
+		}
+	});
+
+	it("describeRepo returns collections list", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "post",
+			createdAt: new Date().toISOString(),
+		});
+		await sourceRepo.putRecord("app.bsky.actor.profile", "self", {
+			$type: "app.bsky.actor.profile",
+			displayName: "Test",
+		});
+		await replicateSource();
+
+		const result = await reader.describeRepo(sourceDid);
+		expect(result).not.toBeNull();
+		expect(result!.did).toBe(sourceDid);
+		expect(result!.collections).toContain("app.bsky.feed.post");
+		expect(result!.collections).toContain("app.bsky.actor.profile");
+	});
+
+	it("getRepoStatus returns rev and root CID", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "status test",
+			createdAt: new Date().toISOString(),
+		});
+		const { rootCid, rev } = await replicateSource();
+
+		const status = reader.getRepoStatus(sourceDid);
+		expect(status).not.toBeNull();
+		expect(status!.did).toBe(sourceDid);
+		expect(status!.rootCid).toBe(rootCid);
+		expect(status!.rev).toBe(rev);
+		expect(status!.active).toBe(true);
+	});
+
+	it("cache invalidation works", async () => {
+		// First sync
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "First post",
+			createdAt: new Date().toISOString(),
+		});
+		await replicateSource();
+
+		const result1 = await reader.listRecords(
+			sourceDid,
+			"app.bsky.feed.post",
+			{ limit: 100 },
+		);
+		expect(result1.records).toHaveLength(1);
+
+		// Add another record and re-sync
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "Second post",
+			createdAt: new Date().toISOString(),
+		});
+		reader.invalidateCache(sourceDid);
+		await replicateSource();
+
+		const result2 = await reader.listRecords(
+			sourceDid,
+			"app.bsky.feed.post",
+			{ limit: 100 },
+		);
+		expect(result2.records).toHaveLength(2);
+	});
+});
+
+// ============================================
+// XRPC integration (replicated repos)
+// ============================================
+
+describe("XRPC integration: replicated repos", () => {
+	let tmpDir: string;
+	let sourceDb: InstanceType<typeof Database>;
+	let replicaDb: InstanceType<typeof Database>;
+	let sourceIpfs: IpfsService;
+	let replicaIpfs: IpfsService;
+	let sourceRepo: RepoManager;
+	let replicaRepo: RepoManager;
+	let syncStorage: SyncStorage;
+	let reader: ReplicatedRepoReader;
+	let app: ReturnType<typeof createApp>;
+	const sourceDid = "did:plc:test123";
+	const replicaDid = "did:plc:replica456";
+
+	beforeEach(async () => {
+		tmpDir = mkdtempSync(join(tmpdir(), "xrpc-replicated-test-"));
+
+		// Source setup
+		const sourceConfig = testConfig(join(tmpDir, "source"), []);
+		sourceDb = new Database(join(tmpDir, "source.db"));
+		sourceIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "source-ipfs-blocks"),
+			datastorePath: join(tmpDir, "source-ipfs-datastore"),
+			networking: false,
+		});
+		await sourceIpfs.start();
+		sourceRepo = new RepoManager(sourceDb, sourceConfig);
+		sourceRepo.init(undefined, sourceIpfs, sourceIpfs);
+
+		// Replica setup
+		const replicaConfig = testConfig(join(tmpDir, "replica"), [sourceDid]);
+		replicaConfig.DID = replicaDid;
+		replicaConfig.SIGNING_KEY =
+			"0000000000000000000000000000000000000000000000000000000000000002";
+		replicaDb = new Database(join(tmpDir, "replica.db"));
+		replicaIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "replica-ipfs-blocks"),
+			datastorePath: join(tmpDir, "replica-ipfs-datastore"),
+			networking: false,
+		});
+		await replicaIpfs.start();
+		replicaRepo = new RepoManager(replicaDb, replicaConfig);
+		replicaRepo.init(undefined, replicaIpfs, replicaIpfs);
+
+		syncStorage = new SyncStorage(replicaDb);
+		syncStorage.initSchema();
+		reader = new ReplicatedRepoReader(replicaIpfs, syncStorage);
+
+		const firehose = new Firehose(replicaRepo);
+		app = createApp(
+			replicaConfig,
+			replicaRepo,
+			firehose,
+			replicaIpfs,
+			replicaIpfs,
+			undefined,
+			undefined,
+			reader,
+		);
+	});
+
+	afterEach(async () => {
+		if (sourceIpfs.isRunning()) await sourceIpfs.stop();
+		if (replicaIpfs.isRunning()) await replicaIpfs.stop();
+		sourceDb.close();
+		replicaDb.close();
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	async function replicateSource(): Promise<void> {
+		const carBytes = await sourceRepo.getRepoCar();
+		const { root, blocks } = await readCarWithRoot(carBytes);
+		await replicaIpfs.putBlocks(blocks);
+
+		const rootCidStr = root.toString();
+		const internalMap = (
+			blocks as unknown as { map: Map<string, Uint8Array> }
+		).map;
+		let rev = rootCidStr;
+		const commitBytes = internalMap?.get(rootCidStr);
+		if (commitBytes) {
+			const commitObj = cborDecode(commitBytes) as Record<string, unknown>;
+			if (typeof commitObj.rev === "string") {
+				rev = commitObj.rev;
+			}
+		}
+
+		syncStorage.upsertState({
+			did: sourceDid,
+			pdsEndpoint: "https://pds.example.com",
+		});
+		syncStorage.updateSyncProgress(sourceDid, rev, rootCidStr);
+		reader.invalidateCache(sourceDid);
+	}
+
+	it("GET getRecord for replicated DID → 200", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "XRPC replicated test",
+			createdAt: "2025-01-01T00:00:00.000Z",
+		});
+		await replicateSource();
+
+		const sourceRecords = await sourceRepo.listRecords("app.bsky.feed.post", {
+			limit: 10,
+		});
+		const rkey = sourceRecords.records[0]!.uri.split("/").pop()!;
+
+		const res = await app.request(
+			`/xrpc/com.atproto.repo.getRecord?repo=${sourceDid}&collection=app.bsky.feed.post&rkey=${rkey}`,
+			undefined,
+			{},
+		);
+		expect(res.status).toBe(200);
+
+		const json = (await res.json()) as {
+			uri: string;
+			cid: string;
+			value: Record<string, unknown>;
+		};
+		expect(json.uri).toContain(sourceDid);
+		expect(json.value.text).toBe("XRPC replicated test");
+	});
+
+	it("GET listRecords for replicated DID → 200", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "list test 1",
+			createdAt: new Date().toISOString(),
+		});
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "list test 2",
+			createdAt: new Date().toISOString(),
+		});
+		await replicateSource();
+
+		const res = await app.request(
+			`/xrpc/com.atproto.repo.listRecords?repo=${sourceDid}&collection=app.bsky.feed.post`,
+			undefined,
+			{},
+		);
+		expect(res.status).toBe(200);
+
+		const json = (await res.json()) as {
+			records: Array<{ uri: string; value: Record<string, unknown> }>;
+		};
+		expect(json.records.length).toBe(2);
+	});
+
+	it("GET describeRepo for replicated DID → 200", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "describe test",
+			createdAt: new Date().toISOString(),
+		});
+		await replicateSource();
+
+		const res = await app.request(
+			`/xrpc/com.atproto.repo.describeRepo?repo=${sourceDid}`,
+			undefined,
+			{},
+		);
+		expect(res.status).toBe(200);
+
+		const json = (await res.json()) as {
+			did: string;
+			collections: string[];
+		};
+		expect(json.did).toBe(sourceDid);
+		expect(json.collections).toContain("app.bsky.feed.post");
+	});
+
+	it("non-replicated foreign DID → 404", async () => {
+		const res = await app.request(
+			`/xrpc/com.atproto.repo.getRecord?repo=did:plc:nonexistent&collection=app.bsky.feed.post&rkey=abc`,
+			undefined,
+			{},
+		);
+		expect(res.status).toBe(404);
+	});
+
+	it("local DID still works via existing path", async () => {
+		await replicaRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "local post",
+			createdAt: new Date().toISOString(),
+		});
+
+		const records = await replicaRepo.listRecords("app.bsky.feed.post", {
+			limit: 10,
+		});
+		const rkey = records.records[0]!.uri.split("/").pop()!;
+
+		const res = await app.request(
+			`/xrpc/com.atproto.repo.getRecord?repo=${replicaDid}&collection=app.bsky.feed.post&rkey=${rkey}`,
+			undefined,
+			{},
+		);
+		expect(res.status).toBe(200);
+
+		const json = (await res.json()) as {
+			uri: string;
+			value: Record<string, unknown>;
+		};
+		expect(json.value.text).toBe("local post");
+	});
+});
+
+// ============================================
+// root_cid + rev extraction
+// ============================================
+
+describe("root_cid + rev extraction", () => {
+	let tmpDir: string;
+	let sourceDb: InstanceType<typeof Database>;
+	let sourceIpfs: IpfsService;
+	let sourceRepo: RepoManager;
+	let replicaDb: InstanceType<typeof Database>;
+	let replicaIpfs: IpfsService;
+	let syncStorage: SyncStorage;
+
+	beforeEach(async () => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rev-extraction-test-"));
+
+		const sourceConfig = testConfig(join(tmpDir, "source"), []);
+		sourceDb = new Database(join(tmpDir, "source.db"));
+		sourceIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "source-ipfs-blocks"),
+			datastorePath: join(tmpDir, "source-ipfs-datastore"),
+			networking: false,
+		});
+		await sourceIpfs.start();
+		sourceRepo = new RepoManager(sourceDb, sourceConfig);
+		sourceRepo.init(undefined, sourceIpfs, sourceIpfs);
+
+		replicaDb = new Database(join(tmpDir, "replica.db"));
+		replicaIpfs = new IpfsService({
+			blocksPath: join(tmpDir, "replica-ipfs-blocks"),
+			datastorePath: join(tmpDir, "replica-ipfs-datastore"),
+			networking: false,
+		});
+		await replicaIpfs.start();
+
+		syncStorage = new SyncStorage(replicaDb);
+		syncStorage.initSchema();
+	});
+
+	afterEach(async () => {
+		if (sourceIpfs.isRunning()) await sourceIpfs.stop();
+		if (replicaIpfs.isRunning()) await replicaIpfs.stop();
+		sourceDb.close();
+		replicaDb.close();
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("after sync, replication_state has both root_cid and last_sync_rev (actual TID)", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "rev test",
+			createdAt: new Date().toISOString(),
+		});
+
+		const carBytes = await sourceRepo.getRepoCar();
+		const { root, blocks } = await readCarWithRoot(carBytes);
+		await replicaIpfs.putBlocks(blocks);
+
+		const rootCidStr = root.toString();
+		const internalMap = (
+			blocks as unknown as { map: Map<string, Uint8Array> }
+		).map;
+		let rev = rootCidStr;
+		const commitBytes = internalMap?.get(rootCidStr);
+		if (commitBytes) {
+			const commitObj = cborDecode(commitBytes) as Record<string, unknown>;
+			if (typeof commitObj.rev === "string") {
+				rev = commitObj.rev;
+			}
+		}
+
+		const did = "did:plc:test123";
+		syncStorage.upsertState({
+			did,
+			pdsEndpoint: "https://pds.example.com",
+		});
+		syncStorage.updateSyncProgress(did, rev, rootCidStr);
+
+		const state = syncStorage.getState(did);
+		expect(state).not.toBeNull();
+		expect(state!.rootCid).toBe(rootCidStr);
+		expect(state!.lastSyncRev).toBe(rev);
+		// Rev should be a TID (not a CID)
+		expect(state!.lastSyncRev).not.toBe(rootCidStr);
+	});
+
+	it("root_cid is a valid CID string and last_sync_rev is a TID", async () => {
+		await sourceRepo.createRecord("app.bsky.feed.post", undefined, {
+			$type: "app.bsky.feed.post",
+			text: "cid validation test",
+			createdAt: new Date().toISOString(),
+		});
+
+		const carBytes = await sourceRepo.getRepoCar();
+		const { root, blocks } = await readCarWithRoot(carBytes);
+		await replicaIpfs.putBlocks(blocks);
+
+		const rootCidStr = root.toString();
+		const internalMap = (
+			blocks as unknown as { map: Map<string, Uint8Array> }
+		).map;
+		let rev = rootCidStr;
+		const commitBytes = internalMap?.get(rootCidStr);
+		if (commitBytes) {
+			const commitObj = cborDecode(commitBytes) as Record<string, unknown>;
+			if (typeof commitObj.rev === "string") {
+				rev = commitObj.rev;
+			}
+		}
+
+		// root_cid should be parseable as a CID
+		const { CID: MfCID } = await import("multiformats");
+		expect(() => MfCID.parse(rootCidStr)).not.toThrow();
+
+		// rev should be a TID (base32-sortable, 13 chars)
+		expect(rev).toMatch(/^[a-z2-7]{13}$/);
+	});
+});

src/replication/sync-storage.ts

···
 				peer_id TEXT,
 				peer_info_fetched_at TEXT,
 				last_sync_rev TEXT,
+				root_cid TEXT,
 				last_sync_at TEXT,
 				last_verified_at TEXT,
 				status TEXT NOT NULL DEFAULT 'pending',
···
 				PRIMARY KEY (did, cid)
 			);
 		`);
+
+		// Migration: add root_cid column if missing (for existing databases)
+		const columns = this.db
+			.prepare("PRAGMA table_info(replication_state)")
+			.all() as Array<{ name: string }>;
+		if (!columns.some((c) => c.name === "root_cid")) {
+			this.db.exec(
+				"ALTER TABLE replication_state ADD COLUMN root_cid TEXT",
+			);
+		}
 	}
 
 	/**
···
 	/**
 	 * Update sync progress after a successful sync.
 	 */
-	updateSyncProgress(did: string, rev: string): void {
+	updateSyncProgress(did: string, rev: string, rootCid?: string): void {
 		this.db
 			.prepare(
 				`UPDATE replication_state
-				 SET last_sync_rev = ?, last_sync_at = datetime('now'),
+				 SET last_sync_rev = ?, root_cid = COALESCE(?, root_cid),
+				     last_sync_at = datetime('now'),
 				     status = 'synced', error_message = NULL
 				 WHERE did = ?`,
 			)
-			.run(rev, did);
+			.run(rev, rootCid ?? null, did);
 	}
 
 	/**
···
 			peerId: (row.peer_id as string) ?? null,
 			peerInfoFetchedAt: (row.peer_info_fetched_at as string) ?? null,
 			lastSyncRev: (row.last_sync_rev as string) ?? null,
+			rootCid: (row.root_cid as string) ?? null,
 			lastSyncAt: (row.last_sync_at as string) ?? null,
 			lastVerifiedAt: (row.last_verified_at as string) ?? null,
 			status: row.status as SyncState["status"],

src/replication/types.ts

···
 	peerId: string | null;
 	peerInfoFetchedAt: string | null;
 	lastSyncRev: string | null;
+	rootCid: string | null;
 	lastSyncAt: string | null;
 	lastVerifiedAt: string | null;
 	status: "pending" | "syncing" | "synced" | "error";

src/server.ts

···
 import { DidResolver } from "./did-resolver.js";
 import { InMemoryDidCache } from "./did-cache.js";
 import { ReplicationManager } from "./replication/replication-manager.js";
+import { ReplicatedRepoReader } from "./replication/replicated-repo-reader.js";
 
 // Load configuration
 const config = loadConfig();
···
 	didCache: new InMemoryDidCache(),
 });
 
-// Initialize replication manager (if IPFS enabled and DIDs configured)
+// Initialize replication manager and replicated repo reader (if IPFS enabled and DIDs configured)
 let replicationManager: ReplicationManager | undefined;
+let replicatedRepoReader: ReplicatedRepoReader | undefined;
 if (ipfsService && config.REPLICATE_DIDS.length > 0) {
 	replicationManager = new ReplicationManager(
 		db,
···
 		ipfsService,
 		didResolver,
 	);
+	replicatedRepoReader = new ReplicatedRepoReader(
+		ipfsService,
+		replicationManager.getSyncStorage(),
+	);
+	replicationManager.setReplicatedRepoReader(replicatedRepoReader);
 }
 
 // Create Hono app
-const app = createApp(config, repoManager, firehose, ipfsService, ipfsService, blobStore, replicationManager);
+const app = createApp(config, repoManager, firehose, ipfsService, ipfsService, blobStore, replicationManager, replicatedRepoReader);
 
 // Create HTTP server using @hono/node-server's request listener
 const requestListener = getRequestListener(app.fetch);

src/xrpc/repo.ts

···
 import type { AppEnv, AuthedAppEnv } from "../types.js";
 import { validator } from "../validation.js";
 import { detectContentType } from "../format.js";
+import type { ReplicatedRepoReader } from "../replication/replicated-repo-reader.js";
 
 function invalidRecordError(
 	c: Context<AuthedAppEnv>,
···
 
 	return c.json(result);
 }
+
+// ============================================
+// Replicated repo handlers
+// ============================================
+
+export async function getRecordReplicated(
+	c: Context<AppEnv>,
+	reader: ReplicatedRepoReader,
+	did: string,
+): Promise<Response> {
+	const collection = c.req.query("collection");
+	const rkey = c.req.query("rkey");
+
+	if (!collection || !rkey) {
+		return c.json(
+			{
+				error: "InvalidRequest",
+				message: "Missing required parameters: repo, collection, rkey",
+			},
+			400,
+		);
+	}
+
+	const result = await reader.getRecord(did, collection, rkey);
+
+	if (!result) {
+		return c.json(
+			{
+				error: "RecordNotFound",
+				message: `Record not found: ${collection}/${rkey}`,
+			},
+			404,
+		);
+	}
+
+	return c.json({
+		uri: `at://${did}/${collection}/${rkey}`,
+		cid: result.cid,
+		value: result.value,
+	});
+}
+
+export async function listRecordsReplicated(
+	c: Context<AppEnv>,
+	reader: ReplicatedRepoReader,
+	did: string,
+): Promise<Response> {
+	const collection = c.req.query("collection");
+	const limitStr = c.req.query("limit");
+	const cursor = c.req.query("cursor");
+	const reverseStr = c.req.query("reverse");
+
+	if (!collection) {
+		return c.json(
+			{
+				error: "InvalidRequest",
+				message: "Missing required parameters: repo, collection",
+			},
+			400,
+		);
+	}
+
+	const limit = Math.min(limitStr ? Number.parseInt(limitStr, 10) : 50, 100);
+	const reverse = reverseStr === "true";
+
+	const result = await reader.listRecords(did, collection, {
+		limit,
+		cursor: cursor || undefined,
+		reverse,
+	});
+
+	return c.json(result);
+}
+
+export async function describeRepoReplicated(
+	c: Context<AppEnv>,
+	reader: ReplicatedRepoReader,
+	did: string,
+): Promise<Response> {
+	const result = await reader.describeRepo(did);
+
+	if (!result) {
+		return c.json(
+			{
+				error: "RepoNotFound",
+				message: `Repository not found: ${did}`,
+			},
+			404,
+		);
+	}
+
+	return c.json({
+		did: result.did,
+		collections: result.collections,
+		handleIsCorrect: false,
+	});
+}

src/xrpc/sync.ts

···
 import type { RepoManager } from "../repo-manager.js";
 import type { AppEnv } from "../types.js";
 import { detectContentType } from "../format.js";
+import type { ReplicatedRepoReader } from "../replication/replicated-repo-reader.js";
 
 export async function getRepo(
 	c: Context<AppEnv>,
···
 export async function getRepoStatus(
 	c: Context<AppEnv>,
 	repoManager: RepoManager,
+	replicatedRepoReader?: ReplicatedRepoReader,
 ): Promise<Response> {
 	const did = c.req.query("did");
 
···
 		);
 	}
 
-	if (did !== c.env.DID) {
-		return c.json(
-			{ error: "RepoNotFound", message: `Repository not found for DID: ${did}` },
-			404,
-		);
+	if (did === c.env.DID) {
+		const data = await repoManager.getRepoStatus();
+		return c.json({
+			did: data.did,
+			active: true,
+			status: "active",
+			rev: data.rev,
+		});
 	}
 
-	const data = await repoManager.getRepoStatus();
+	// Check replicated repos
+	if (replicatedRepoReader) {
+		const status = replicatedRepoReader.getRepoStatus(did);
+		if (status) {
+			return c.json({
+				did: status.did,
+				active: status.active,
+				status: status.active ? "active" : "deactivated",
+				rev: status.rev,
+			});
+		}
+	}
 
-	return c.json({
-		did: data.did,
-		active: true,
-		status: "active",
-		rev: data.rev,
-	});
+	return c.json(
+		{ error: "RepoNotFound", message: `Repository not found for DID: ${did}` },
+		404,
+	);
 }
 
 export async function listRepos(
 	c: Context<AppEnv>,
 	repoManager: RepoManager,
+	replicatedRepoReader?: ReplicatedRepoReader,
 ): Promise<Response> {
 	const data = await repoManager.getRepoStatus();
 
-	return c.json({
-		repos: [
-			{
-				did: data.did,
-				head: data.head,
-				rev: data.rev,
-				active: true,
-			},
-		],
-	});
+	const repos: Array<{
+		did: string;
+		head?: string;
+		rev: string | null;
+		active: boolean;
+	}> = [
+		{
+			did: data.did,
+			head: data.head,
+			rev: data.rev,
+			active: true,
+		},
+	];
+
+	// Include replicated repos if reader is available
+	if (replicatedRepoReader) {
+		for (const status of replicatedRepoReader.getAllRepoStatuses()) {
+			repos.push({
+				did: status.did,
+				head: status.rootCid ?? undefined,
+				rev: status.rev,
+				active: status.active,
+			});
+		}
+	}
+
+	return c.json({ repos });
 }
 
 export async function listBlobs(