Refactor read filter from per-item grant to per-document ReadCap

Model the read filter on NextGraph's real ReadCap mechanism instead of an
invented per-item grant. Verified in nextgraph-rs: there is no Document type
(document = repo); a store is a container repo referencing other repos by RDF
overlay; holding a store's cap does NOT grant the repos it contains (each repo
needs its own cap; no read-cap inheritance). So the access unit is the
DOCUMENT = an item's `@graph`, never the item.

- caps.ts: CapRegistry (read/write caps per document NURI + public docs;
  open/grantRead/grantWrite/makePublic/canRead/canWrite/governsRead/
  hasReadPolicy). Replaces access.ts (Grant).
- read-filter.ts: filter keeps an item iff its `@graph` document is readable
  (held cap or public); items with no `@graph` or in an ungoverned document are
  kept. No injected grantOf — the filter reads `@graph` and consults the
  registry (automatic, domain-agnostic).
- polyfill.ts: getCaps()/resetCaps() replace setGrantOf/getGrantOf; useShape
  filters only when caps.hasReadPolicy() (else passthrough, no regression).
- tests: caps.test.ts (6) + read-filter.test.ts (4), incl. no-inheritance
  between documents. 10 pass; tsc rc=0.

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

packages/client/src/access.ts

@@ -1,42 +0,0 @@
-/**
- * Capability emulation — pure, generic, no domain rules. Mirrors what the broker
- * will enforce via real caps; at migration these checks disappear (the broker
- * only ever syncs/serves what the wallet is authorized for).
- */
-
-import type { Grant, PrincipalId, Scope } from "./types";
-
-/** May `principal` read a document carrying `grant`? */
-export function canRead(grant: Grant, principal: PrincipalId | null): boolean {
-  if (grant.read.includes("public")) return true;
-  if (principal === null) return false;
-  return grant.read.includes(principal);
-}
-
-/** May `principal` write a document carrying `grant`? */
-export function canWrite(grant: Grant, principal: PrincipalId | null): boolean {
-  if (principal === null) return false;
-  return grant.write.includes(principal);
-}
-
-/**
- * The grant a freshly created document gets, by scope, for its `owner`. These
- * are the *defaults* a creator attaches; further sharing (e.g. granting a
- * connection read on a protected doc) is a separate explicit act.
- */
-export function defaultGrant(scope: Scope, owner: PrincipalId): Grant {
-  switch (scope) {
-    case "public":
-      return { read: ["public"], write: [owner] };
-    case "protected":
-      return { read: [owner], write: [owner] };
-    case "private":
-      return { read: [owner], write: [owner] };
-  }
-}
-
-/** Add a read grant to a principal (e.g. when a connection is accepted). */
-export function grantRead(grant: Grant, principal: PrincipalId): Grant {
-  if (grant.read.includes(principal)) return grant;
-  return { ...grant, read: [...grant.read, principal] };
-}

packages/client/src/caps.ts

@@ -0,0 +1,97 @@
+/**
+ * Capability emulation — generic, no domain rules. Models NextGraph **ReadCaps**
+ * (and write caps) as faithfully as a data layer can.
+ *
+ * In NextGraph a ReadCap is possession of a *document's* (repo's) read key: the
+ * broker only ever delivers documents the wallet holds a cap for. The access
+ * UNIT is therefore the **document = repo**, identified here by its NURI — the
+ * `@graph` an item lives in — **never the item**. (Verified in nextgraph-rs:
+ * a store is just a container repo; holding a store's cap does NOT grant the
+ * repos it references — each document needs its own cap. So this registry is
+ * purely per-document, with NO store-level inheritance.)
+ *
+ * At migration this whole layer disappears: the broker/verifier enforces the
+ * real caps and `useShape` already returns only authorized documents.
+ */
+
+import type { Nuri, PrincipalId, Scope } from "./types";
+
+/**
+ * Who holds the read/write cap of each document. The consumer populates it via
+ * cap operations (create-public, grant-to-a-connection…) exactly as it will in
+ * the target; this layer enforces possession generically — it knows no policy.
+ */
+export class CapRegistry {
+  /** doc NURI → principals holding its READ cap. */
+  private readers = new Map<Nuri, Set<PrincipalId>>();
+  /** doc NURI → principals holding its WRITE cap. */
+  private writers = new Map<Nuri, Set<PrincipalId>>();
+  /** doc NURIs readable by everyone (public_store repos — no cap needed). */
+  private publicDocs = new Set<Nuri>();
+
+  /** Grant `principal` the READ cap of document `doc`. */
+  grantRead(doc: Nuri, principal: PrincipalId): void {
+    add(this.readers, doc, principal);
+  }
+
+  /** Grant `principal` the WRITE cap of document `doc`. */
+  grantWrite(doc: Nuri, principal: PrincipalId): void {
+    add(this.writers, doc, principal);
+  }
+
+  /** Mark `doc` public (readable without a cap — a public_store repo). */
+  makePublic(doc: Nuri): void {
+    this.publicDocs.add(doc);
+  }
+
+  /**
+   * Apply the caps a creator attaches to a fresh document, by scope. Public →
+   * world-readable; protected/private → only the owner reads. The owner always
+   * holds the write cap. Further sharing is a separate explicit grant.
+   */
+  open(doc: Nuri, scope: Scope, owner: PrincipalId): void {
+    if (scope === "public") this.makePublic(doc);
+    else this.grantRead(doc, owner);
+    this.grantWrite(doc, owner);
+  }
+
+  /** Is `doc` under any READ-cap policy? (Undeclared docs are not enforced.) */
+  governsRead(doc: Nuri): boolean {
+    return this.publicDocs.has(doc) || this.readers.has(doc);
+  }
+
+  /** Does `principal` hold a READ cap for `doc` (or is `doc` public)? */
+  canRead(doc: Nuri, principal: PrincipalId | null): boolean {
+    if (this.publicDocs.has(doc)) return true;
+    if (principal === null) return false;
+    return this.readers.get(doc)?.has(principal) ?? false;
+  }
+
+  /** Is `doc` under any WRITE-cap policy? */
+  governsWrite(doc: Nuri): boolean {
+    return this.writers.has(doc);
+  }
+
+  /** Does `principal` hold a WRITE cap for `doc`? */
+  canWrite(doc: Nuri, principal: PrincipalId | null): boolean {
+    if (principal === null) return false;
+    return this.writers.get(doc)?.has(principal) ?? false;
+  }
+
+  /** No READ policy declared → the read filter stays inert (passthrough). */
+  hasReadPolicy(): boolean {
+    return this.readers.size > 0 || this.publicDocs.size > 0;
+  }
+
+  clear(): void {
+    this.readers.clear();
+    this.writers.clear();
+    this.publicDocs.clear();
+  }
+}
+
+function add(m: Map<Nuri, Set<PrincipalId>>, doc: Nuri, principal: PrincipalId): void {
+  let s = m.get(doc);
+  if (!s) m.set(doc, (s = new Set()));
+  s.add(principal);
+}

packages/client/src/polyfill.ts

@@ -9,7 +9,7 @@
  */
 
 import type { NgLike, UseShapeLike, PrincipalId } from "./types";
-import type { GrantResolver } from "./read-filter";
+import { CapRegistry } from "./caps";
 
 export interface EventuallyConfig {
   /** The REAL `@ng-org/web` `ng` (injected to avoid a hard import / alias loop). */
@@ -24,18 +24,17 @@ export interface EventuallyConfig {
   init?: (...args: any[]) => any;
   /** REAL `@ng-org/orm` `initNg` (ORM signals) — forwarded by the lib's `initNg()`. */
   initNg?: (...args: any[]) => any;
-  /** How to read a document's emulated grant. When set, reads are filtered. */
-  grantOf?: GrantResolver;
 }
 
 let cfg: EventuallyConfig | null = null;
 let currentUser: PrincipalId | null = null;
-let grantOf: GrantResolver | null = null;
+/** The emulated ReadCap/WriteCap registry. Empty until the app declares caps;
+ *  while it has no read policy the read filter passes through (no regression). */
+let caps = new CapRegistry();
 
 export function configure(c: EventuallyConfig): void {
   cfg = c;
   currentUser = c.currentUser ?? null;
-  grantOf = c.grantOf ?? null;
 }
 
 /** @internal — used by the SDK-shaped wrappers to reach the injected real SDK. */
@@ -53,16 +52,17 @@ export function getCurrentUser(): PrincipalId | null {
   return currentUser;
 }
 
-/** Set/clear how reads resolve a document's grant. null → reads pass through. */
-export function setGrantOf(fn: GrantResolver | null): void {
-  grantOf = fn;
+/** The emulated cap registry — the app grants/opens caps on it (as it will via
+ *  real cap operations in the target). The read filter consults it. */
+export function getCaps(): CapRegistry {
+  return caps;
 }
 
-export function getGrantOf(): GrantResolver | null {
-  return grantOf;
+/** Reset all emulated caps (mainly for tests / fresh sessions). */
+export function resetCaps(): void {
+  caps = new CapRegistry();
 }
 
-// Capability helpers — polyfill-era surface (caps are emulated now; native at
-// migration). Re-exported here so the whole polyfill API lives under /polyfill.
-export { canRead, canWrite, defaultGrant, grantRead } from "./access";
-export type { GrantResolver } from "./read-filter";
+// Cap surface — polyfill-era (caps are emulated now; native at migration).
+// Re-exported here so the whole polyfill API lives under /polyfill.
+export { CapRegistry } from "./caps";

packages/client/src/read-filter.ts

@@ -1,34 +1,47 @@
 /**
  * Read filter — the polyfill of capability-based read access.
  *
- * In the target, the broker only delivers documents the user holds a read cap
+ * In the target, the broker only delivers documents the user holds a **ReadCap**
  * for, so `useShape` already returns an authorized subset. Here (single shared
- * wallet, everything readable) we reproduce that: a read-filtered VIEW over the
- * reactive set that yields only items whose emulated grant satisfies the current
- * user. Removed at migration (the broker does it natively).
+ * wallet, everything readable) we reproduce that with a read-filtered VIEW over
+ * the reactive set: it keeps only items whose **document** (its `@graph` = the
+ * repo it lives in) the current user may read, per the {@link CapRegistry}.
+ *
+ * Faithful to NextGraph: the access unit is the DOCUMENT, not the item. In a
+ * mono-store layout (every item in one repo) the filter is therefore all-or-
+ * nothing on that document — which is exactly the native behavior, and why
+ * fine-grained isolation requires one document per entity. Removed at migration.
  */
 
-import { canRead } from "./access";
-import type { Grant, PrincipalId } from "./types";
+import type { CapRegistry } from "./caps";
+import type { PrincipalId } from "./types";
+
+/** The document (repo NURI) an item lives in — its `@graph`. */
+function docOf(item: unknown): string | null {
+  const g = (item as Record<string, unknown> | null)?.["@graph"];
+  return typeof g === "string" ? g : null;
+}
 
 /**
- * Reads a document's emulated grant. Return `undefined` when the item carries no
- * grant — such items are kept (the filter only restricts items that DECLARE a
- * grant). The consumer injects this (the lib stays domain-agnostic).
+ * May `user` read this item? An item with no `@graph`, or in a document under no
+ * cap policy, is KEPT (the filter only restricts documents that DECLARE a cap —
+ * mirrors the prior behavior and keeps ungoverned data flowing).
  */
-export type GrantResolver = (item: unknown) => Grant | undefined;
+function readable(item: unknown, caps: CapRegistry, user: PrincipalId | null): boolean {
+  const doc = docOf(item);
+  if (doc === null) return true;
+  if (!caps.governsRead(doc)) return true;
+  return caps.canRead(doc, user);
+}
 
-/** Pure: keep only the items the user may read. Ungranted items are kept. */
+/** Pure: keep only the items the user may read. */
 export function filterReadable<T>(
   items: Iterable<T>,
-  grantOf: GrantResolver,
+  caps: CapRegistry,
   user: PrincipalId | null,
 ): T[] {
   const out: T[] = [];
-  for (const item of items) {
-    const g = grantOf(item);
-    if (g === undefined || canRead(g, user)) out.push(item);
-  }
+  for (const item of items) if (readable(item, caps, user)) out.push(item);
   return out;
 }
 
@@ -41,13 +54,10 @@ export function filterReadable<T>(
  */
 export function makeReadFilteredView<S extends object>(
   set: S,
-  grantOf: GrantResolver,
+  caps: CapRegistry,
   getUser: () => PrincipalId | null,
 ): S {
-  const keep = (item: unknown): boolean => {
-    const g = grantOf(item);
-    return g === undefined || canRead(g, getUser());
-  };
+  const keep = (item: unknown): boolean => readable(item, caps, getUser());
   return new Proxy(set, {
     get(target, prop, receiver) {
       if (prop === Symbol.iterator) {

packages/client/src/types.ts

@@ -13,19 +13,6 @@ export type Scope = "public" | "protected" | "private";
  *  Polyfill: a chosen id (e.g. a username), because everyone shares one wallet. */
 export type PrincipalId = string;
 
-/**
- * Emulated capability attached to a document — mirrors real NextGraph caps,
- * which the broker/verifier will enforce natively at migration. The app attaches
- * these via cap operations exactly as it will in the target; this layer enforces
- * them generically (it does NOT know any authorization policy).
- */
-export interface Grant {
-  /** Read grant: `"public"` = everyone, otherwise explicit principals. */
-  read: Array<PrincipalId | "public">;
-  /** Write grant: principals allowed to write the document. */
-  write: PrincipalId[];
-}
-
 /**
  * Loose shape of the real `@ng-org/web` `ng` object that we wrap. Injected by
  * the consumer at {@link configure} — we never hard-import the SDK, which keeps

packages/client/src/use-shape.ts

@@ -1,16 +1,17 @@
 /**
- * Wrapped `useShape`: same signature as `@ng-org/orm`. When a grant resolver is
- * configured, the returned set is a read-filtered VIEW (only items the current
- * user may read); otherwise it passes the real set through unchanged. At
- * migration the filtering disappears — the broker only delivers authorized docs.
+ * Wrapped `useShape`: same signature as `@ng-org/orm`. When a read-cap policy is
+ * declared, the returned set is a read-filtered VIEW (only items in documents the
+ * current user holds a ReadCap for); otherwise it passes the real set through
+ * unchanged. At migration the filtering disappears — the broker only delivers
+ * authorized documents.
  */
 
-import { getConfig, getCurrentUser, getGrantOf } from "./polyfill";
+import { getConfig, getCurrentUser, getCaps } from "./polyfill";
 import { makeReadFilteredView } from "./read-filter";
 
 export function useShape(shapeType: unknown, scope: unknown): unknown {
   const set = getConfig().useShape(shapeType, scope) as object;
-  const grantOf = getGrantOf();
-  if (!grantOf) return set; // no policy configured → passthrough (filter inert)
-  return makeReadFilteredView(set, grantOf, getCurrentUser);
+  const caps = getCaps();
+  if (!caps.hasReadPolicy()) return set; // no policy configured → passthrough
+  return makeReadFilteredView(set, caps, getCurrentUser);
 }

packages/client/test/access.test.ts

@@ -1,30 +0,0 @@
-import { test, expect } from "bun:test";
-import { canRead, canWrite, defaultGrant, grantRead } from "../src/access";
-
-test("public docs are readable by anyone, even anonymous", () => {
-  const g = defaultGrant("public", "alice");
-  expect(canRead(g, null)).toBe(true);
-  expect(canRead(g, "bob")).toBe(true);
-});
-
-test("protected docs: owner + explicitly granted principals only", () => {
-  let g = defaultGrant("protected", "alice");
-  expect(canRead(g, "alice")).toBe(true);
-  expect(canRead(g, "bob")).toBe(false);
-  g = grantRead(g, "bob"); // e.g. bob becomes a connection of alice
-  expect(canRead(g, "bob")).toBe(true);
-});
-
-test("private docs: owner only", () => {
-  const g = defaultGrant("private", "alice");
-  expect(canRead(g, "alice")).toBe(true);
-  expect(canRead(g, "bob")).toBe(false);
-  expect(canRead(g, null)).toBe(false);
-});
-
-test("write is restricted to the write grant", () => {
-  const g = defaultGrant("public", "alice");
-  expect(canWrite(g, "alice")).toBe(true);
-  expect(canWrite(g, "bob")).toBe(false);
-  expect(canWrite(g, null)).toBe(false);
-});

packages/client/test/caps.test.ts

@@ -0,0 +1,50 @@
+import { test, expect } from "bun:test";
+import { CapRegistry } from "../src/caps";
+
+test("public documents are readable by anyone, even anonymous", () => {
+  const caps = new CapRegistry();
+  caps.open("did:ng:o:pub", "public", "alice");
+  expect(caps.canRead("did:ng:o:pub", null)).toBe(true);
+  expect(caps.canRead("did:ng:o:pub", "bob")).toBe(true);
+});
+
+test("protected documents: owner + explicitly granted principals only", () => {
+  const caps = new CapRegistry();
+  caps.open("did:ng:o:prot", "protected", "alice");
+  expect(caps.canRead("did:ng:o:prot", "alice")).toBe(true);
+  expect(caps.canRead("did:ng:o:prot", "bob")).toBe(false);
+  caps.grantRead("did:ng:o:prot", "bob"); // bob becomes a connection of alice
+  expect(caps.canRead("did:ng:o:prot", "bob")).toBe(true);
+});
+
+test("private documents: owner only", () => {
+  const caps = new CapRegistry();
+  caps.open("did:ng:o:priv", "private", "alice");
+  expect(caps.canRead("did:ng:o:priv", "alice")).toBe(true);
+  expect(caps.canRead("did:ng:o:priv", "bob")).toBe(false);
+  expect(caps.canRead("did:ng:o:priv", null)).toBe(false);
+});
+
+test("write is restricted to write-cap holders; the creator always holds it", () => {
+  const caps = new CapRegistry();
+  caps.open("did:ng:o:pub", "public", "alice");
+  expect(caps.canWrite("did:ng:o:pub", "alice")).toBe(true);
+  expect(caps.canWrite("did:ng:o:pub", "bob")).toBe(false);
+  expect(caps.canWrite("did:ng:o:pub", null)).toBe(false);
+});
+
+test("holding a document's cap does NOT grant another document (no inheritance)", () => {
+  const caps = new CapRegistry();
+  caps.grantRead("did:ng:o:doc1", "alice");
+  expect(caps.canRead("did:ng:o:doc1", "alice")).toBe(true);
+  expect(caps.canRead("did:ng:o:doc2", "alice")).toBe(false); // separate repo, separate cap
+});
+
+test("governsRead / hasReadPolicy distinguish governed from ungoverned documents", () => {
+  const caps = new CapRegistry();
+  expect(caps.hasReadPolicy()).toBe(false);
+  caps.grantRead("did:ng:o:doc1", "alice");
+  expect(caps.hasReadPolicy()).toBe(true);
+  expect(caps.governsRead("did:ng:o:doc1")).toBe(true);
+  expect(caps.governsRead("did:ng:o:unknown")).toBe(false); // not declared → not enforced
+});

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

@@ -1,38 +1,47 @@
 import { test, expect } from "bun:test";
 import { filterReadable, makeReadFilteredView } from "../src/read-filter";
-import type { Grant } from "../src/types";
+import { CapRegistry } from "../src/caps";
 
-interface Item { id: string; grant?: Grant }
-const grantOf = (i: unknown): Grant | undefined => (i as Item).grant;
+// The access unit is the DOCUMENT (an item's `@graph` = the repo it lives in),
+// not the item. Items here carry `@graph`; caps are granted per document.
+interface Item { id: string; "@graph"?: string }
 
-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
+const PRIV: Item = { id: "a", "@graph": "did:ng:o:alice" };   // alice's doc
+const PUB: Item = { id: "p", "@graph": "did:ng:o:public" };   // public doc
+const UNGOV: Item = { id: "n", "@graph": "did:ng:o:other" };  // doc under no policy
+const NOGRAPH: Item = { id: "x" };                            // no document → 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"]);
+function caps(): CapRegistry {
+  const c = new CapRegistry();
+  c.grantRead("did:ng:o:alice", "alice");
+  c.makePublic("did:ng:o:public");
+  return c;
+}
+
+test("filterReadable keeps public, cap-held, ungoverned and graphless items", () => {
+  const items = [PRIV, PUB, UNGOV, NOGRAPH];
+  expect(filterReadable(items, caps(), "alice").map(i => (i as Item).id)).toEqual(["a", "p", "n", "x"]);
+  expect(filterReadable(items, caps(), "bob").map(i => (i as Item).id)).toEqual(["p", "n", "x"]);
+  expect(filterReadable(items, caps(), null).map(i => (i as Item).id)).toEqual(["p", "n", "x"]);
 });
 
 test("makeReadFilteredView filters iteration/size, reflects the current user", () => {
-  const set = new Set<Item>([A, PUB, NOGRANT]);
+  const set = new Set<Item>([PRIV, PUB, UNGOV, NOGRAPH]);
   let user: string | null = "bob";
-  const view = makeReadFilteredView(set, grantOf, () => user);
+  const view = makeReadFilteredView(set, caps(), () => user);
 
-  expect([...view].map(i => i.id)).toEqual(["p", "n"]);
-  expect(view.size).toBe(2);
+  expect([...view].map(i => i.id)).toEqual(["p", "n", "x"]);
+  expect(view.size).toBe(3);
 
   user = "alice"; // read lazily → view updates without rewrapping
-  expect([...view].map(i => i.id)).toEqual(["a", "p", "n"]);
-  expect(view.size).toBe(3);
+  expect([...view].map(i => i.id)).toEqual(["a", "p", "n", "x"]);
+  expect(view.size).toBe(4);
 });
 
 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"] } };
+  const view = makeReadFilteredView(set, caps(), () => "bob");
+  const C: Item = { id: "c", "@graph": "did:ng:o:public" };
 
   view.add(C);
   expect(set.has(C)).toBe(true);     // mutation reached the real set
@@ -43,8 +52,8 @@ test("makeReadFilteredView forwards mutations and membership to the target", ()
 });
 
 test("forEach is filtered too", () => {
-  const set = new Set<Item>([A, PUB]);
+  const set = new Set<Item>([PRIV, PUB]);
   const seen: string[] = [];
-  makeReadFilteredView(set, grantOf, () => "bob").forEach((i) => seen.push((i as Item).id));
+  makeReadFilteredView(set, caps(), () => "bob").forEach((i) => seen.push((i as Item).id));
   expect(seen).toEqual(["p"]);
 });