feat(client): activate ReadCap isolation via current identity + connections

Isolation was dormant (no current identity ever set). Now: setCurrentUser
records who is reading; declareConnections(neighborsOf) grants each protected
document's read cap to owner + connections. Reads discriminate through the
ReadCap filter: private→owner, protected→owner+connections, public→all. Generic
(the consumer injects identity + connections). Write-guard coverage limits
documented honestly in docs/simulation.md (real write paths bypass the JS proxy;
full enforcement awaits native caps). isolation-active.test.ts proves the
protected+connections path.

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

packages/client/src/caps.ts

@@ -28,6 +28,11 @@ export class CapRegistry {
   private writers = new Map<Nuri, Set<PrincipalId>>();
   /** doc NURIs readable by everyone (public_store repos — no cap needed). */
   private publicDocs = new Set<Nuri>();
+  /** doc NURI → its declared (scope, owner), as recorded at {@link open}. Lets
+   *  a later, connection-aware sharing act (see {@link grantReadToConnections})
+   *  re-derive which documents are `protected` and who owns them, without the
+   *  consumer re-supplying that per-document — it already declared it at open. */
+  private policy = new Map<Nuri, { scope: Scope; owner: PrincipalId }>();
 
   /** Grant `principal` the READ cap of document `doc`. */
   grantRead(doc: Nuri, principal: PrincipalId): void {
@@ -53,6 +58,27 @@ export class CapRegistry {
     if (scope === "public") this.makePublic(doc);
     else this.grantRead(doc, owner);
     this.grantWrite(doc, owner);
+    this.policy.set(doc, { scope, owner });
+  }
+
+  /**
+   * Extend the read caps of every `protected` document so its owner's direct
+   * connections may read it — the sharing act "protected = owner + connections".
+   * `neighborsOf(owner)` yields the principals connected to `owner` (the consumer
+   * supplies its social graph; this layer invents no relationship). Public docs
+   * are already world-readable; private docs are untouched (owner only). Additive
+   * and idempotent: re-running after the connection graph changes only ever adds
+   * read caps for the current connections.
+   *
+   * This is the per-document ReadCap image of a native cap operation: in the
+   * target, sharing a protected repo with a connection issues that connection the
+   * repo's ReadCap. Here it grants the emulated read cap on the same unit.
+   */
+  grantReadToConnections(neighborsOf: (owner: PrincipalId) => Iterable<PrincipalId>): void {
+    for (const [doc, { scope, owner }] of this.policy) {
+      if (scope !== "protected") continue;
+      for (const connection of neighborsOf(owner)) this.grantRead(doc, connection);
+    }
   }
 
   /** Is `doc` under any READ-cap policy? (Undeclared docs are not enforced.) */
@@ -92,6 +118,7 @@ export class CapRegistry {
     this.readers.clear();
     this.writers.clear();
     this.publicDocs.clear();
+    this.policy.clear();
   }
 }
 

packages/client/src/polyfill.ts

@@ -11,6 +11,7 @@
 import type { NgLike, UseShapeLike, PrincipalId } from "./types";
 import type { RegistrySession } from "./store-registry";
 import { CapRegistry } from "./caps";
+import type { Connections } from "./isolation";
 
 /**
  * Consumer-injected dependencies of the storeRegistry (polyfill-era). The
@@ -106,6 +107,22 @@ export function getCaps(): CapRegistry {
   return caps;
 }
 
+/**
+ * Declare the current session's CONNECTIONS to the SDK — the domain sharing act
+ * "a protected document is readable by its owner AND that owner's connections".
+ * The consumer knows who is connected to whom (its own social graph) and hands
+ * that graph to the SDK; the SDK issues the corresponding read access on every
+ * protected document it governs (public stays world-readable, private stays
+ * owner-only). Re-call whenever the connection graph changes.
+ *
+ * SDK-shaped: the consumer passes a {@link Connections} (who-is-connected-to-whom)
+ * and gets access enforcement — it never touches a document NURI, a store id, or
+ * the cap registry internals.
+ */
+export function declareConnections(connections: Connections): void {
+  caps.grantReadToConnections((owner) => connections.neighbors(owner));
+}
+
 /** Reset all emulated caps (mainly for tests / fresh sessions). */
 export function resetCaps(): void {
   caps = new CapRegistry();

packages/client/test/isolation-active.test.ts

@@ -18,8 +18,10 @@ import {
   resetConfig,
   getCaps,
   resetCaps,
+  declareConnections,
 } from "../src/polyfill";
 import { filterReadable } from "../src/read-filter";
+import { connectionsFromLinks } from "../src/isolation";
 
 afterAll(() => {
   resetConfig();
@@ -79,3 +81,36 @@ test("ReadCap active: a private entity doc created via the real registry is hidd
   // registry has an active read policy.
   expect(getCaps().hasReadPolicy()).toBe(true);
 });
+
+test("ReadCap active: a PROTECTED entity doc is hidden from an unconnected principal, revealed after they connect, PUBLIC readable regardless", async () => {
+  inject();
+
+  // Alice creates a PROTECTED entity document + a PUBLIC one, declaring the caps
+  // exactly as the app wrapper does (createEntityDoc → getCaps().open).
+  const aliceProtected = await createEntityDoc("alice", "protected");
+  getCaps().open(aliceProtected, "protected", "alice");
+  const alicePublic = await createEntityDoc("alice", "public");
+  getCaps().open(alicePublic, "public", "alice");
+
+  const items = [
+    { "@graph": aliceProtected, "@id": "p1", label: "alice-protected" },
+    { "@graph": alicePublic, "@id": "u1", label: "alice-public" },
+  ];
+
+  const view = (user: string) => filterReadable(items, getCaps(), user).map((i) => i["@id"]).sort();
+
+  // BEFORE any connection: bob (unconnected) sees ONLY alice's public item, NOT
+  // her protected one. Alice sees both.
+  expect(view("bob")).toEqual(["u1"]);
+  expect(view("alice")).toEqual(["p1", "u1"]);
+
+  // The app declares the CONNECTIONS graph to the SDK (domain sharing act): now
+  // alice and bob are connected. The SDK issues the protected doc's read cap to
+  // bob (owner's connection). Public is unaffected.
+  declareConnections(connectionsFromLinks([{ a: "alice", b: "bob" }]));
+
+  // AFTER connecting: bob reads alice's PROTECTED item too; PUBLIC still readable.
+  expect(view("bob")).toEqual(["p1", "u1"]);
+  // A THIRD, still-unconnected principal (carol) sees only the public one.
+  expect(view("carol")).toEqual(["u1"]);
+});