feat(client): read filter — capability-based view over the reactive set

makeReadFilteredView wraps a DeepSignalSet in a Proxy whose iteration/size/forEach
yield only items the current user may read (canRead on the item's emulated grant), while
add/delete and the underlying reactivity pass through. filterReadable is the pure core.
useShape applies it only when a grantOf resolver is configured (else passthrough, so
ungranted apps are unaffected). grantOf/setGrantOf added to the polyfill surface. Mirrors
the broker delivering only authorized docs; removed at migration. 4 unit tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/client/test/read-filter.test.ts

@@ -0,0 +1,50 @@
+import { test, expect } from "bun:test";
+import { filterReadable, makeReadFilteredView } from "../src/read-filter";
+import type { Grant } from "../src/types";
+
+interface Item { id: string; grant?: Grant }
+const grantOf = (i: unknown): Grant | undefined => (i as Item).grant;
+
+const A: Item = { id: "a", grant: { read: ["alice"], write: ["alice"] } };
+const PUB: Item = { id: "p", grant: { read: ["public"], write: ["bob"] } };
+const NOGRANT: Item = { id: "n" }; // no grant → always kept
+
+test("filterReadable keeps public, owner-readable, and ungranted items", () => {
+  const items = [A, PUB, NOGRANT];
+  expect(filterReadable(items, grantOf, "alice").map(i => (i as Item).id)).toEqual(["a", "p", "n"]);
+  expect(filterReadable(items, grantOf, "bob").map(i => (i as Item).id)).toEqual(["p", "n"]);
+  expect(filterReadable(items, grantOf, null).map(i => (i as Item).id)).toEqual(["p", "n"]);
+});
+
+test("makeReadFilteredView filters iteration/size, reflects the current user", () => {
+  const set = new Set<Item>([A, PUB, NOGRANT]);
+  let user: string | null = "bob";
+  const view = makeReadFilteredView(set, grantOf, () => user);
+
+  expect([...view].map(i => i.id)).toEqual(["p", "n"]);
+  expect(view.size).toBe(2);
+
+  user = "alice"; // read lazily → view updates without rewrapping
+  expect([...view].map(i => i.id)).toEqual(["a", "p", "n"]);
+  expect(view.size).toBe(3);
+});
+
+test("makeReadFilteredView forwards mutations and membership to the target", () => {
+  const set = new Set<Item>([PUB]);
+  const view = makeReadFilteredView(set, grantOf, () => "bob");
+  const C: Item = { id: "c", grant: { read: ["bob"], write: ["bob"] } };
+
+  view.add(C);
+  expect(set.has(C)).toBe(true);     // mutation reached the real set
+  expect([...view].map(i => i.id)).toEqual(["p", "c"]);
+
+  view.delete(C);
+  expect(set.has(C)).toBe(false);
+});
+
+test("forEach is filtered too", () => {
+  const set = new Set<Item>([A, PUB]);
+  const seen: string[] = [];
+  makeReadFilteredView(set, grantOf, () => "bob").forEach((i) => seen.push((i as Item).id));
+  expect(seen).toEqual(["p"]);
+});