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/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);
+}