@weaveprotocol/core 0.1.2 → 0.2.0

package/dist/node/space-runtime.js

@@ -1,3 +1,26 @@
+/**
+ * @module node/space-runtime
+ * One open space: its store, its gatekeeper, its peers, its sync.
+ *
+ * A space is the unit of storage and of sync — its own store, its own
+ * rooms and sockets — so two spaces never mix, and a peer you share one space
+ * with learns nothing about the others.
+ *
+ * **A record keeps its key; changes are versions.** Editing a record writes its
+ * next version — same key, `seq` one higher, `prev` naming the one replaced —
+ * and deleting it writes a version marked deleted. Which version is current is
+ * decided by `seq` and id alone (`records/version.ts`), never by a clock, so
+ * every node agrees and nothing replayed can roll a record back.
+ *
+ * **Who may write is the space's access history** (`space/roles.ts`): roles,
+ * members, invites, revoked notes and collection definitions, as records every
+ * version points into with `seen`. A version stands when its author held what
+ * its collection's rules ask, as of what it saw, and nothing it had not seen
+ * took that away. A version that stops standing — its author was removed, and
+ * the remover never saw it — is passed over when reading, and the version
+ * before it counts again, where the store still has one.
+ */
+import { contactKeyPair, isContactPublicKey, openSealed, sealFor } from '../identity/contact-key.js';
 import { createSchemaEngine } from '../schema/schema-engine.js';
 import { parseUCAN, resolveDelegationRoot } from '../identity/ucan.js';
 import { isAgentNote } from '../identity/agent-note.js';
@@ -8,33 +31,35 @@ import { newRecordKey, nextVersion, RECORD_KEY_PATTERN } from '../records/versio
 import { checkLinks } from '../records/links.js';
 import { allows, changedFixedField, describeWho, onePerKey, permissionName } from '../records/rules.js';
 import { reconcileFolder } from '../storage/folder-reconcile.js';
+import { createMirror } from '../storage/mirror.js';
 import { createCryptoGate } from '../validation/crypto-gate.js';
 import { createStructuralGate } from '../validation/structural-gate.js';
 import { createStatefulGate } from '../validation/stateful-gate.js';
 import { createCapabilityGate } from '../validation/capability-gate.js';
 import { createValidationEngine } from '../validation/validation-engine.js';
-import { encryptExpression, decryptExpression } from '../privacy/space-encryption.js';
+import { encryptExpression, decryptExpression, generateSpaceKey, openWith, sealWith, spaceKeyBytes, spaceKeyFromRaw, } from '../privacy/space-encryption.js';
 import { createNetworkManager } from '../network/network-manager.js';
 import { createMesh } from '../network/mesh.js';
 import { createWebSocketTransport } from '../network/ws-transport.js';
 import { createClientAuth, createMeshAuth } from '../network/peer-auth.js';
-import { deriveInviteKey, deriveReadKey, generateInviteSecret, inviteKey as inviteRecordKey, memberKey, revokeKey, roleKey, signInvite, verifyInvite, } from '../space/space-access.js';
-import { ACCESS_COLLECTIONS, DEFINITION_COLLECTION, INVITE_COLLECTION, MEMBER_COLLECTION, REVOKE_COLLECTION, ROLE_COLLECTION, checkRole, replayAccess, roleHolds, standing, } from '../space/roles.js';
+import { BOX_COLLECTION, MEMBER_KEY_COLLECTION, SPACE_KEY_RECORD, SPACE_RELAYS_RECORD, SPACE_KEEPERS_RECORD, memberKeyRecordKey, boxContext, boxKey, earlierKeysContext, membershipContext, deriveInviteKey, deriveReadKey, generateInviteSecret, inviteKey as inviteRecordKey, memberKey, revokeKey, roleKey, signInvite, verifyInvite, } from '../space/space-access.js';
+import { ACCESS_COLLECTIONS, DEFINITION_COLLECTION, INVITE_COLLECTION, KEY_COLLECTION, MANAGE, MAX_RELAYS, RELAYS_COLLECTION, checkRelays, KEEPERS_COLLECTION, checkKeepers, MEMBER_COLLECTION, REVOKE_COLLECTION, ROLE_COLLECTION, checkRole, readers, replayAccess, roleHolds, standing, } from '../space/roles.js';
 import { createSyncEngine } from '../sync/sync-engine.js';
 import { CATALOG_COLLECTION, checkStoredCollection, toJsonSchema, validateJsonSchema, } from '../schema/collection-def.js';
 import { CARRIER_COLLECTION, MEMBERSHIP_COLLECTION, PROFILE_COLLECTION } from '../space/account-registry.js';
 import { PASS_COLLECTION } from '../space/pass.js';
-import { base32Encode, cidFromBytes, sha256 } from '../utils/hash.js';
-import { utf8Encode } from '../utils/encoding.js';
+import { base32Encode, cidFromBytes, cidOfDigest, sha256 } from '../utils/hash.js';
+import { sameTags, tagsFor, topicKey, topicTag } from '../records/topics.js';
+import { base64UrlDecode, base64UrlEncode, utf8Decode, utf8Encode } from '../utils/encoding.js';
 /** Collections the node writes itself, through their own calls — never through `put` */
-const MANAGED = new Set([MEMBERSHIP_COLLECTION, PROFILE_COLLECTION, CARRIER_COLLECTION, PASS_COLLECTION, ...ACCESS_COLLECTIONS]);
+const MANAGED = new Set([MEMBERSHIP_COLLECTION, PROFILE_COLLECTION, CARRIER_COLLECTION, PASS_COLLECTION, BOX_COLLECTION, MEMBER_KEY_COLLECTION, ...ACCESS_COLLECTIONS]);
 /**
  * Access records a peer without the space key must still be able to judge:
  * who holds which role decides every write. Kept in the clear, even in a
  * private space. Collection definitions stay sealed — a peer that cannot
  * read the records has no use for their rules.
  */
-const IN_THE_CLEAR = new Set([ROLE_COLLECTION, MEMBER_COLLECTION, INVITE_COLLECTION, REVOKE_COLLECTION]);
+const IN_THE_CLEAR = new Set([ROLE_COLLECTION, MEMBER_COLLECTION, INVITE_COLLECTION, REVOKE_COLLECTION, KEY_COLLECTION, BOX_COLLECTION, MEMBER_KEY_COLLECTION, RELAYS_COLLECTION, KEEPERS_COLLECTION]);
 /** Which collection each access record key belongs to */
 const ACCESS_KEYS = [
     ['role:', ROLE_COLLECTION],
@@ -42,6 +67,9 @@ const ACCESS_KEYS = [
     ['invite:', INVITE_COLLECTION],
     ['revoke:', REVOKE_COLLECTION],
     ['collection:', DEFINITION_COLLECTION],
+    ['key:', KEY_COLLECTION],
+    ['relays:', RELAYS_COLLECTION],
+    ['keepers:', KEEPERS_COLLECTION],
 ];
 /** How many records a keep list may name */
 const MAX_KEEP = 10_000;
@@ -93,19 +121,53 @@ function isFolderAdapter(adapter) {
     return typeof adapter.reload === 'function';
 }
 const isStringList = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+// ─── What a node holding part of a space remembers ──────────────────
+/** Where it is kept in the space's store */
+const CACHE_KEY = 'cache';
+/** One entry per write of this node's still waiting for keepers: `pending/<id>` */
+const PENDING_PREFIX = 'pending/';
+async function loadCacheState(adapter) {
+    try {
+        const bytes = await adapter.get(CACHE_KEY);
+        const saved = bytes ? JSON.parse(utf8Decode(bytes)) : {};
+        const numbers = (value) => Object.fromEntries(Object.entries(typeof value === 'object' && value !== null ? value : {}).filter(([, v]) => typeof v === 'number'));
+        return { settled: saved.settled === true, used: numbers(saved.used), level: numbers(saved.level) };
+    }
+    catch {
+        return { settled: false, used: {}, level: {} };
+    }
+}
 export async function openSpaceRuntime(deps) {
     const { record, provider, signer, schemas, session, emit } = deps;
-    const { space, key } = record;
+    const { space } = record;
+    let closed = false;
+    /**
+     * Every key of the space this node holds, by id. Encrypted bodies name the
+     * key they were sealed with; the history names which one is current.
+     */
+    const keyring = new Map();
+    for (const held of record.keys ?? [])
+        keyring.set(held.id, held);
+    if (record.key)
+        keyring.set(record.key.id, record.key);
+    /** This account's member key here, which new keys are sealed to */
+    const memberPair = deps.memberKey ? await contactKeyPair(deps.memberKey) : null;
     /** An invite waiting to be used — forgotten here once it is, whatever the stored record still says */
     let waitingInvite = record.invite !== null;
     const adapter = await deps.stores(`spaces/${space.id}`);
-    // Tabs sharing this browser's store are covered by compaction's grace period.
-    // A folder's other writers — a sync service bringing another device's tree
-    // back hours later — are not, so a folder keeps its old nodes.
-    const shared = isFolderAdapter(adapter);
-    const storage = createStorageProvider(adapter, shared ? {} : { compactEvery: 256 });
-    if (!shared)
-        void storage.compact().catch(() => { });
+    const storage = createStorageProvider(adapter);
+    // What this node holds of the space (see "Holding part of the space" below).
+    // Here, before anything can ask: sync asks on every hello.
+    const cache = deps.cache ?? null;
+    const cacheState = await loadCacheState(adapter);
+    // The collections the app declared are held from the start.
+    for (const collection of cache?.collections ?? [])
+        if (!collection.startsWith('sys.'))
+            cacheState.used[collection] ??= Date.now();
+    // A node that may hold part of the space starts by holding only what it
+    // uses: whether the space names keepers is only known once it has caught up.
+    let partial = cache !== null;
+    const holds = () => (partial ? new Set(Object.keys(cacheState.used)) : 'all');
     const resolvePublicKey = async (did) => provider.importPublicKey(didToPublicKey(did).publicKeyBytes);
     const validation = createValidationEngine({
         cryptoGate: createCryptoGate(provider),
@@ -155,10 +217,11 @@ export async function openSpaceRuntime(deps) {
     async function openBody(expression) {
         if (!looksEncrypted(expression.body))
             return { body: expression.body, links: expression.links ?? [], encrypted: false };
-        if (!key)
+        const sealedWith = keyring.get(String(expression.body.keyId));
+        if (!sealedWith)
             return { body: null, links: [], encrypted: true };
         try {
-            const opened = (await decryptExpression(expression, key)).body;
+            const opened = (await decryptExpression(expression, sealedWith)).body;
             const links = checkLinks(opened?.links ?? []) === null ? (opened?.links ?? []) : [];
             return { body: opened?.body ?? null, links, encrypted: true };
         }
@@ -198,6 +261,9 @@ export async function openSpaceRuntime(deps) {
         creator: space.creator,
         roles: space.roles,
         creatorRole: space.creatorRole,
+        ...(space.visibility === 'private' && space.encryptionKeyId && space.readKey
+            ? { key: { keyId: space.encryptionKeyId, readKey: space.readKey } }
+            : {}),
     };
     /** Events, by version id — building one checks signatures and invites, so they are kept */
     const events = new Map();
@@ -275,6 +341,24 @@ export async function openSpaceRuntime(deps) {
                     return null;
                 return { ...base, keep, kind: 'invite', inviteKey: inviteDid, role: body.role, open: body.open };
             }
+            case KEY_COLLECTION: {
+                if (version.key !== SPACE_KEY_RECORD || typeof body.keyId !== 'string' || body.keyId.length > 64)
+                    return null;
+                if (typeof body.readKey !== 'string' || !body.readKey.startsWith('did:key:'))
+                    return null;
+                return { ...base, keep: [], kind: 'key', keyId: body.keyId, readKey: body.readKey };
+            }
+            case RELAYS_COLLECTION: {
+                if (version.key !== SPACE_RELAYS_RECORD || !isStringList(body.relays) || body.relays.length > MAX_RELAYS)
+                    return null;
+                return { ...base, keep: [], kind: 'relays', relays: body.relays };
+            }
+            case KEEPERS_COLLECTION: {
+                const copies = body.copies ?? null;
+                if (version.key !== SPACE_KEEPERS_RECORD || checkKeepers(body.keepers, copies) !== null)
+                    return null;
+                return { ...base, keep: [], kind: 'keepers', keepers: body.keepers, copies: copies };
+            }
             case REVOKE_COLLECTION: {
                 if (typeof body.note !== 'string')
                     return null;
@@ -294,6 +378,23 @@ export async function openSpaceRuntime(deps) {
         return null;
     }
     let accessCache = null;
+    /** The read key readers must prove now — kept at hand, since a handshake asks for it without waiting */
+    let currentReadKey = space.readKey ?? '';
+    /**
+     * Where the members meet: the relays the space names once it names some,
+     * and until then the ones the invite that brought it here named. Handed to
+     * the mesh for this space's room alone.
+     */
+    let relays = record.relays ?? [];
+    let meshRoom = null;
+    function useRelays(named) {
+        if (named.length === 0 || (named.length === relays.length && named.every((url, i) => url === relays[i])))
+            return;
+        relays = [...named];
+        if (meshRoom)
+            deps.mesh?.useRelays(meshRoom, relays);
+        void deps.onRelays?.(relays).catch(() => { });
+    }
     const access = () => (accessCache ??= loadAccess());
     async function loadAccess() {
         const found = [];
@@ -312,6 +413,8 @@ export async function openSpaceRuntime(deps) {
         }
         const history = replayAccess(accessGenesis, found);
         reportRole(history.current);
+        currentReadKey = history.current.keys.at(-1)?.readKey ?? currentReadKey;
+        useRelays(history.current.relays);
         return { history, events: found };
     }
     let reportedRole;
@@ -349,7 +452,7 @@ export async function openSpaceRuntime(deps) {
         }
         return found;
     }
-    /** The rules in force for a collection in one state of the history — null when there are none to judge by */
+    /** The rules and topics in force for a collection in one state of the history — null when there are none to judge by */
     async function rulesAt(state, collection) {
         if (collection.startsWith('sys.'))
             return null;
@@ -357,7 +460,41 @@ export async function openSpaceRuntime(deps) {
         if (!entry)
             return null;
         const found = await definitionIn(entry.event);
-        return typeof found === 'string' ? null : { rules: found.definition.rules ?? {} };
+        return typeof found === 'string' ? null : { rules: found.definition.rules ?? {}, topics: found.definition.topics ?? [] };
+    }
+    // ─── Topic tags ────────────────────────────────────────────────────
+    //
+    // Keyed from the key a record's body was sealed with, in a private space;
+    // from the space id in a public one (`records/topics.ts`).
+    const topicKeys = new Map();
+    /** The tag key for one of the space's keys, or the public one; null when this node doesn't hold that key */
+    function tagKey(keyId) {
+        const name = keyId ?? 'public';
+        let found = topicKeys.get(name);
+        if (!found) {
+            const held = keyId === null ? null : keyring.get(keyId);
+            if (keyId !== null && !held)
+                return null;
+            found = topicKey(held ? { spaceKey: held.key } : { spaceId: space.id });
+            topicKeys.set(name, found);
+        }
+        return found;
+    }
+    /**
+     * Why a version's tags don't match its body under the topics in force, or
+     * null when they do — or when this node can't read the body to tell.
+     */
+    async function tagProblem(expression, topics) {
+        if (topics.length === 0 && !expression.tags?.length)
+            return null;
+        const opened = await openBody(expression);
+        if (opened.body === null)
+            return null;
+        const key = tagKey(opened.encrypted ? String(expression.body.keyId) : null);
+        if (!key)
+            return null;
+        const expected = await tagsFor(await key, expression.collection, topics, opened.body);
+        return sameTags(expression.tags, expected) ? null : { ok: false, reason: `Its topic tags don't match what it says` };
     }
     const standings = new Map();
     /**
@@ -426,6 +563,11 @@ export async function openSpaceRuntime(deps) {
         const judged = history.judge({ id: expression.id, root, seen, note: await noteOf(expression) }, needs);
         if (!judged.ok)
             return judged;
+        if (found && !expression.deleted) {
+            const problem = await tagProblem(expression, found.topics);
+            if (problem)
+                return problem;
+        }
         if (!rules || expression.deleted)
             return STANDS;
         if (expression.seq === 0 && rules.onePer) {
@@ -624,6 +766,7 @@ export async function openSpaceRuntime(deps) {
             definedBy: entry?.definedBy ?? null,
             permissions: definition?.permissions ?? [],
             rules: definition?.rules ?? {},
+            topics: definition?.topics ?? [],
             ...(definition?.screen !== undefined ? { screen: definition.screen } : {}),
             records,
         });
@@ -663,6 +806,7 @@ export async function openSpaceRuntime(deps) {
         const result = new Map();
         // By key: the current version may be anyone's.
         for (const [key, versions] of await storage.histories('profile:')) {
+            let found = null;
             for (const version of versions) {
                 if (version.collection !== PROFILE_COLLECTION)
                     continue;
@@ -673,24 +817,342 @@ export async function openSpaceRuntime(deps) {
                     continue;
                 if (version.deleted)
                     break; // they took it down
-                const name = (await openBody(version)).body?.name;
-                if (typeof name === 'string' && name.trim()) {
-                    result.set(verdict.root, { did: verdict.root, name: name.trim().slice(0, 64), updatedAt: version.createdAt });
+                const body = (await openBody(version)).body;
+                if (!found) {
+                    const name = body?.name;
+                    if (typeof name !== 'string' || !name.trim())
+                        break;
+                    found = { did: verdict.root, name: name.trim().slice(0, 64), updatedAt: version.createdAt };
+                }
+                // The contact key from the newest version that has one: it never changes, and an app
+                // without it that wrote a newer version first must not hide it.
+                if (isContactPublicKey(body?.contactKey)) {
+                    found = { ...found, contactKey: body.contactKey };
+                    break;
                 }
-                break;
             }
+            if (found)
+                result.set(found.did, found);
         }
         return result;
     }
+    /**
+     * Each member's member key, from their own record of it — kept in the
+     * clear, so someone who holds only an older key of the space can still say
+     * where to seal the new one.
+     */
+    let memberKeysCache = null;
+    const memberKeyMap = () => (memberKeysCache ??= loadMemberKeys());
+    async function loadMemberKeys() {
+        const found = new Map();
+        // By key: the current version may be anyone's.
+        for (const [key, versions] of await storage.histories('memberkey:')) {
+            for (const version of versions) {
+                if (version.collection !== MEMBER_KEY_COLLECTION || version.deleted)
+                    continue;
+                const verdict = await judge(version);
+                if (!verdict.verified || !verdict.root || (await memberKeyRecordKey(verdict.root)) !== key)
+                    continue;
+                if (!(await standingOf(version)).ok)
+                    continue;
+                const body = version.body;
+                if (isContactPublicKey(body?.key)) {
+                    found.set(verdict.root, body.key);
+                    break;
+                }
+            }
+        }
+        return found;
+    }
     /** Records changed: everything derived from them may have too. */
     const recordsChanged = () => {
         linkIndexCache = null;
         catalogCache = null;
         profilesCache = null;
+        memberKeysCache = null;
         accessCache = null;
         standings.clear();
         emit({ type: 'records', space: space.id });
+        keepUp();
+        for (const mirror of mirrors)
+            mirror.changed();
+        // The access history may name keepers now, or none.
+        void refreshHolds().catch(() => { });
     };
+    // ─── The space's keys ──────────────────────────────────────────────
+    //
+    // A private space's key changes when someone loses their place in it
+    // (`sys.key`, part of the access history): whoever manages the space makes
+    // a new one, and seals a copy to each member's member key (`sys.box`). The
+    // key record carries every earlier key sealed under the new one, so holding
+    // the current key opens everything written before it — which is how
+    // someone who joins later reads the old records, and someone removed reads
+    // nothing new. This is how Keybase changes a team's key.
+    /** The key the history names now, if this node holds it */
+    function currentKey(state) {
+        const epoch = state.keys.at(-1);
+        return epoch ? (keyring.get(epoch.keyId) ?? null) : null;
+    }
+    /** The newest key this node holds that the history names — what it proves it may read with while behind */
+    function newestKey(state) {
+        for (const epoch of [...state.keys].reverse()) {
+            const held = keyring.get(epoch.keyId);
+            if (held)
+                return held;
+        }
+        return record.key;
+    }
+    /** Box and key record versions already opened, so each is tried once */
+    const opened = new Set();
+    /** Takes in what this node can open: boxes sealed to its member key, and the earlier keys each key record carries */
+    async function learnKeys() {
+        const { history } = await access();
+        const epochs = history.current.keys;
+        const learned = [];
+        const take = (found) => {
+            if (keyring.has(found.id))
+                return false;
+            keyring.set(found.id, found);
+            learned.push(found);
+            return true;
+        };
+        if (memberPair && epochs.some((epoch) => !keyring.has(epoch.keyId))) {
+            for (const versions of (await storage.histories('box:')).values()) {
+                for (const version of versions) {
+                    if (version.collection !== BOX_COLLECTION || version.deleted || opened.has(version.id))
+                        continue;
+                    const body = version.body;
+                    if (body?.to !== deps.rootDid || typeof body.keyId !== 'string' || typeof body.sealed !== 'string')
+                        continue;
+                    const epoch = epochs.find((known) => known.keyId === body.keyId);
+                    if (!epoch || keyring.has(epoch.keyId))
+                        continue;
+                    opened.add(version.id);
+                    const content = (await openSealed(memberPair.privateKey, body.sealed, boxContext(space.id, epoch.keyId, deps.rootDid)));
+                    if (typeof content?.key !== 'string')
+                        continue;
+                    // Whoever sealed it, it is the key the history names or it is nothing.
+                    const found = await spaceKeyFromRaw(base64UrlDecode(content.key)).catch(() => null);
+                    if (found?.id === epoch.keyId && (await deriveReadKey(found, provider)).did === epoch.readKey)
+                        take(found);
+                }
+            }
+        }
+        // Each newer key opens the ones before it — which may open more.
+        let more = true;
+        while (more) {
+            more = false;
+            for (const versions of (await storage.histories('key:')).values()) {
+                for (const version of versions) {
+                    const body = version.body;
+                    if (version.collection !== KEY_COLLECTION || opened.has(version.id) || typeof body?.keyId !== 'string')
+                        continue;
+                    const holder = keyring.get(body.keyId);
+                    if (!holder)
+                        continue;
+                    opened.add(version.id);
+                    const earlier = await openWith(holder, body.earlier, earlierKeysContext(space.id, holder.id));
+                    if (!isStringList(earlier))
+                        continue;
+                    for (const raw of earlier.slice(0, 1000)) {
+                        const found = await spaceKeyFromRaw(base64UrlDecode(raw)).catch(() => null);
+                        if (found && take(found))
+                            more = true;
+                    }
+                }
+            }
+        }
+        if (learned.length === 0)
+            return;
+        const writeWith = newestKey((await access()).history.current);
+        if (writeWith)
+            await deps.onKeys?.([...keyring.values()], writeWith.id);
+        recordsChanged();
+    }
+    /** Makes a new key current, with every key before it sealed inside, and seals it to each member */
+    async function rotateKey() {
+        if (space.visibility !== 'private')
+            throw new Error('A public space has no key to change');
+        const { history } = await access();
+        if (!roleHolds(standing(history.current, deps.rootDid), MANAGE))
+            throw new Error(`Only someone who manages "${space.name}" can change its key`);
+        if (!currentKey(history.current))
+            throw new Error(`This device doesn't hold the current key of "${space.name}" yet`);
+        const next = await generateSpaceKey();
+        const earlier = await Promise.all([...keyring.values()].map(async (held) => base64UrlEncode(await spaceKeyBytes(held))));
+        const body = {
+            keyId: next.id,
+            readKey: (await deriveReadKey(next, provider)).did,
+            earlier: await sealWith(next, earlier, earlierKeysContext(space.id, next.id)),
+        };
+        keyring.set(next.id, next);
+        try {
+            await upsert(KEY_COLLECTION, SPACE_KEY_RECORD, body);
+        }
+        catch (error) {
+            keyring.delete(next.id);
+            throw error;
+        }
+        await deps.onKeys?.([...keyring.values()], next.id);
+        await boxForMembers();
+    }
+    /**
+     * Seals the current key to each member who has no copy from someone who
+     * manages the space. Members show their member key on their profile; one
+     * who hasn't yet gets their copy once they do.
+     */
+    async function boxForMembers() {
+        const { history } = await access();
+        const state = history.current;
+        const epoch = state.keys.at(-1);
+        const key = currentKey(state);
+        if (!epoch || !key)
+            return;
+        const boxed = new Set();
+        for (const versions of (await storage.histories('box:')).values()) {
+            for (const version of versions) {
+                const body = version.body;
+                if (version.collection !== BOX_COLLECTION || body?.keyId !== epoch.keyId || typeof body.to !== 'string')
+                    continue;
+                const { root } = await judge(version);
+                if (root && (root === deps.rootDid || roleHolds(standing(state, root), MANAGE)))
+                    boxed.add(body.to);
+            }
+        }
+        const memberKeys = await memberKeyMap();
+        const raw = base64UrlEncode(await spaceKeyBytes(key));
+        for (const did of [...readers(state)].sort()) {
+            const publicKey = memberKeys.get(did);
+            if (boxed.has(did) || !publicKey)
+                continue;
+            const sealed = await sealFor(publicKey, { key: raw }, boxContext(space.id, epoch.keyId, did));
+            await upsert(BOX_COLLECTION, await boxKey(epoch.keyId, did, deps.rootDid), { keyId: epoch.keyId, to: did, sealed });
+        }
+    }
+    /**
+     * Keeps the keys in step with the history: says where to seal this
+     * account's copy, learns what it can, and — managing the space — changes
+     * the key when due and seals it to whoever lacks it.
+     */
+    async function upkeep() {
+        if (isAgentNote(session.proof())) {
+            if (space.visibility === 'private')
+                await learnKeys();
+            return;
+        }
+        await nameRelays();
+        if (space.visibility !== 'private')
+            return;
+        if (deps.peopleOnly) {
+            await learnKeys();
+            return;
+        }
+        const mine = await memberKeyMap();
+        if (memberPair && mine.get(deps.rootDid) !== memberPair.publicKey && !(await cannotWrite())) {
+            await upsert(MEMBER_KEY_COLLECTION, await memberKeyRecordKey(deps.rootDid), { key: memberPair.publicKey });
+        }
+        await learnKeys();
+        const { history } = await access();
+        const state = history.current;
+        if (!currentKey(state))
+            return;
+        if (!roleHolds(standing(state, deps.rootDid), MANAGE))
+            return;
+        if (state.keyDue)
+            await rotateKey();
+        else
+            await boxForMembers();
+    }
+    /**
+     * A space nobody has said where to meet yet: whoever manages it names the
+     * relays this node uses, so the invites and devices that follow meet there.
+     */
+    async function nameRelays() {
+        const own = (deps.network?.relays ?? []).filter((url) => checkRelays([url]) === null).slice(0, MAX_RELAYS);
+        if (own.length === 0)
+            return;
+        const { history } = await access();
+        if (history.current.relays.length > 0 || !roleHolds(standing(history.current, deps.rootDid), MANAGE))
+            return;
+        await upsert(RELAYS_COLLECTION, SPACE_RELAYS_RECORD, { relays: own });
+    }
+    let keysRunning = null;
+    let keysAgain = false;
+    /** Runs the upkeep once more after whatever changed — one run at a time */
+    function keepUp() {
+        if (closed)
+            return;
+        if (keysRunning) {
+            keysAgain = true;
+            return;
+        }
+        keysRunning = (async () => {
+            do {
+                keysAgain = false;
+                await upkeep().catch(() => {
+                    // A write refused, a peer's junk: the next change tries again.
+                });
+            } while (keysAgain && !closed);
+        })().finally(() => {
+            keysRunning = null;
+        });
+    }
+    /** How this node proves it may read, and checks the peers that connect — against the history at that moment */
+    const readAccess = space.visibility !== 'private'
+        ? null
+        : {
+            async key() {
+                const held = newestKey((await access()).history.current);
+                // A carrier holds the read key pair without the key it comes from: it may be served the space, and cannot open it.
+                return held ? deriveReadKey(held, provider) : (record.read ?? null);
+            },
+            current: () => currentReadKey,
+            async membership() {
+                const held = newestKey((await access()).history.current);
+                return held ? sealWith(held, session.proof(), membershipContext(space.id)) : null;
+            },
+            async admits(peerDid, readKey, membership) {
+                const { history } = await access();
+                const epoch = history.current.keys.find((known) => known.readKey === readKey);
+                const held = epoch ? keyring.get(epoch.keyId) : undefined;
+                if (!held)
+                    return false;
+                const { account } = await accountOf(peerDid, await openWith(held, membership, membershipContext(space.id)));
+                return account !== null && readers(history.current).has(account);
+            },
+        };
+    // ─── Mirrors ───────────────────────────────────────────────────────
+    //
+    // Every mirror is one more peer: what it holds goes through the same gates
+    // as a peer's records, and what this node holds goes out to it.
+    const mirrors = [];
+    for (const [index, store] of (deps.mirrors ?? []).entries()) {
+        mirrors.push(await createMirror({
+            store,
+            space: space.id,
+            storage,
+            state: await deps.stores(`mirrors/${space.id}/${index}`),
+            accept: async (version) => {
+                const verdict = await admit(version);
+                if (!verdict.ok)
+                    return verdict.later ? 'later' : 'refused';
+                await storage.addExpression(version);
+                return 'stored';
+            },
+        }));
+    }
+    /** Reads every mirror in the background: a space that opens from nothing — a host that lost its disk — fills in as it goes */
+    const pullMirrors = () => Promise.all(mirrors.map((mirror) => mirror
+        .pull()
+        .then(({ added }) => {
+        if (added === 0)
+            return;
+        recordsChanged();
+        announceSoon();
+    })
+        .catch(() => {
+        // Out of reach now; what this node holds goes out on the next change.
+    })));
     // ─── Peers ─────────────────────────────────────────────────────────
     let connection = 'offline';
     let rejected = 0;
@@ -699,6 +1161,8 @@ export async function openSpaceRuntime(deps) {
     const routes = new Map();
     const sync = createSyncEngine({
         storageProvider: storage,
+        self: session.did,
+        holds,
         sendToPeer: (peerId, message) => {
             routes.get(peerId)?.send(peerId, { type: 'sync', from: session.did, payload: message });
         },
@@ -723,9 +1187,10 @@ export async function openSpaceRuntime(deps) {
             sync.notifyPeers(connectedPeers());
         }, 100);
     };
-    sync.on('expression-received', () => {
+    sync.on('expression-received', (version) => {
         recordsChanged();
         announceSoon();
+        deps.onArrived?.(version);
     });
     sync.on('rejected', (peer, _expression, reason) => {
         rejected += 1;
@@ -734,15 +1199,16 @@ export async function openSpaceRuntime(deps) {
     const net = deps.network;
     if (net) {
         const room = encodeURIComponent(space.id);
-        // A carrier holds the read key pair without the key it comes from: it may be served the space, and cannot open it.
-        const readKey = space.visibility === 'private' ? (key ? await deriveReadKey(key, provider) : (record.read ?? null)) : null;
+        // Who is at the other end is asked of the history at each handshake: the space's key may change while it is open.
+        await access();
         if (deps.mesh) {
+            meshRoom = await relayRoom(space.id);
+            deps.mesh.useRelays(meshRoom, relays);
             // Every peer met through a relay proves who it is, and in a private space that it may read.
-            const auth = createMeshAuth(space.id, session, space.visibility === 'private' ? { key: readKey, publicDid: space.readKey ?? '' } : null, provider);
-            networks.push(deps.mesh.join(await relayRoom(space.id), auth));
+            networks.push(deps.mesh.join(meshRoom, createMeshAuth(space.id, session, readAccess, provider)));
         }
         // Both sides of a socket to a node prove who they are; in a private space the client also proves it may read.
-        const authenticator = net.nodes?.length ? createClientAuth(space.id, session, readKey, provider) : null;
+        const authenticator = net.nodes?.length ? createClientAuth(space.id, session, readAccess, provider) : null;
         for (const node of net.nodes ?? []) {
             const url = `${node}${node.includes('?') ? '&' : '?'}space=${room}`;
             networks.push(createNetworkManager({
@@ -835,6 +1301,8 @@ export async function openSpaceRuntime(deps) {
             emit({ type: 'status', space: space.id });
         });
     }
+    // Whether to hold part of the space is settled before the first hello says what this node holds.
+    await refreshHolds().catch(() => { });
     if (networks.length > 0) {
         connection = 'connecting';
         // Online as soon as one way in works: a node that is slow to answer, or
@@ -882,10 +1350,172 @@ export async function openSpaceRuntime(deps) {
         ? new globalThis.BroadcastChannel(`weave-node:${deps.rootDid}:${space.id}`)
         : null;
     if (channel) {
-        channel.onmessage = () => recordsChanged();
+        channel.onmessage = () => {
+            // The other tab wrote to the store underneath: what sync compares is read again.
+            storage.invalidate();
+            recordsChanged();
+        };
         // In Node a channel holds the process open; it must never be the only thing doing so.
         channel.unref?.();
     }
+    // ─── Holding part of the space ─────────────────────────────────────
+    //
+    // With `cache` set, and once the space names a keeper, this node holds only
+    // the collections it uses, besides the space's own. Sync takes in nothing
+    // else. Its own writes are pending until enough keepers have them, and a
+    // collection holding a pending write is never dropped. Without a keeper the
+    // space is held whole: then this node may be one of its copies.
+    const HOUR = 3_600_000;
+    const DAY = 24 * HOUR;
+    const declared = new Set((cache?.collections ?? []).filter((c) => !c.startsWith('sys.')));
+    let cacheTimer = null;
+    const saveCache = () => {
+        if (cacheTimer || !cache)
+            return;
+        cacheTimer = setTimeout(() => {
+            cacheTimer = null;
+            void adapter.put(CACHE_KEY, utf8Encode(JSON.stringify(cacheState))).catch(() => { });
+        }, 500);
+        cacheTimer.unref?.();
+    };
+    const flushCache = async () => {
+        if (!cacheTimer)
+            return;
+        clearTimeout(cacheTimer);
+        cacheTimer = null;
+        await adapter.put(CACHE_KEY, utf8Encode(JSON.stringify(cacheState))).catch(() => { });
+    };
+    saveCache();
+    /**
+     * Holds part of the space from the moment it names a keeper, and all of it
+     * again if it stops — once this node has caught up enough to know.
+     */
+    async function refreshHolds() {
+        if (!cache || closed)
+            return;
+        const next = (await access()).history.current.keepers.length > 0 || !cacheState.settled;
+        if (next === partial)
+            return;
+        partial = next;
+        // Peers learn what this node holds now; anything newly held comes across.
+        sync.notifyPeers(connectedPeers());
+        emit({ type: 'status', space: space.id });
+    }
+    /** Collections a query or a screen uses: held from now on. Whether all of them are here yet. */
+    function use(collections) {
+        if (!cache)
+            return true;
+        const now = Date.now();
+        let added = false;
+        for (const collection of collections) {
+            if (typeof collection !== 'string' || collection.startsWith('sys.'))
+                continue;
+            const was = cacheState.used[collection];
+            if (was === undefined)
+                added = true;
+            if (was === undefined || now - was > HOUR) {
+                cacheState.used[collection] = now;
+                saveCache();
+            }
+        }
+        if (added && partial)
+            sync.notifyPeers(connectedPeers());
+        return !partial || collections.every((c) => c.startsWith('sys.') || cacheState.level[c] !== undefined);
+    }
+    /** A write of this node's, waiting for keepers — only on a node that may hold part of a space */
+    async function markPending(version) {
+        if (!cache || version.author !== session.did || version.collection.startsWith('sys.'))
+            return;
+        const pending = { collection: version.collection, by: [] };
+        await adapter.put(`${PENDING_PREFIX}${version.id}`, utf8Encode(JSON.stringify(pending)));
+    }
+    /**
+     * A keeper has some of this node's pending writes: those it named, or every
+     * one in a collection it is level on. Once enough keepers have one, it
+     * stops being pending. Only keepers the space names count.
+     */
+    async function confirm(peer, which) {
+        if (!cache)
+            return;
+        const state = (await access()).history.current;
+        if (!state.keepers.some((keeper) => keeper.did === peer))
+            return;
+        const target = Math.min(state.keepers.length, Math.max(state.copies ?? 2, cache.copies ?? 0));
+        for (const name of await adapter.list(PENDING_PREFIX)) {
+            const id = name.slice(PENDING_PREFIX.length);
+            if (which.ids && !which.ids.has(id))
+                continue;
+            const bytes = await adapter.get(name);
+            if (!bytes)
+                continue;
+            const pending = JSON.parse(utf8Decode(bytes));
+            if (which.collection !== undefined && pending.collection !== which.collection)
+                continue;
+            if (!pending.by.includes(peer))
+                pending.by.push(peer);
+            if (pending.by.length >= target)
+                await adapter.delete(name);
+            else
+                await adapter.put(name, utf8Encode(JSON.stringify(pending)));
+        }
+    }
+    sync.on('synced', (_peer, full) => {
+        if (!cache || !full || cacheState.settled)
+            return;
+        // Caught up with a node holding everything: the access history here is the space's now.
+        cacheState.settled = true;
+        saveCache();
+        void refreshHolds().catch(() => { });
+    });
+    sync.on('stored', (peer, ids) => {
+        void confirm(peer, { ids: new Set(ids) }).catch(() => { });
+    });
+    sync.on('level', (peer, collection, full) => {
+        if (cache && full && cacheState.level[collection] === undefined) {
+            cacheState.level[collection] = Date.now();
+            saveCache();
+            // A query that said "not complete" says so no longer.
+            if (partial)
+                emit({ type: 'records', space: space.id });
+        }
+        void confirm(peer, { collection }).catch(() => { });
+    });
+    /**
+     * Drops collections no query has touched for a while: their records go,
+     * and they are no longer held. Never one the app declared, nor one holding
+     * a write still waiting for keepers.
+     */
+    async function dropUnused() {
+        if (!cache || !partial || closed)
+            return;
+        const cutoff = Date.now() - (cache.unusedAfterDays ?? 30) * DAY;
+        const waiting = new Set();
+        for (const name of await adapter.list(PENDING_PREFIX)) {
+            const bytes = await adapter.get(name);
+            if (bytes)
+                waiting.add(JSON.parse(utf8Decode(bytes)).collection);
+        }
+        let dropped = false;
+        for (const [collection, at] of Object.entries(cacheState.used)) {
+            if (at > cutoff || declared.has(collection) || waiting.has(collection))
+                continue;
+            // No longer held first, so nothing syncs it back while it goes.
+            delete cacheState.used[collection];
+            delete cacheState.level[collection];
+            for (const item of (await storage.items(collection)).items)
+                await storage.removeExpression(cidOfDigest(item.id));
+            dropped = true;
+        }
+        if (!dropped)
+            return;
+        saveCache();
+        recordsChanged();
+        sync.notifyPeers(connectedPeers());
+    }
+    // When the app opens the space, then every few hours while it stays open.
+    const dropTimer = cache ? setInterval(() => void dropUnused().catch(() => { }), 6 * HOUR) : null;
+    const tidying = cache ? dropUnused().catch(() => { }) : Promise.resolve();
+    dropTimer?.unref?.();
     /** Why this account cannot write here at all, or null when it can */
     async function cannotWrite() {
         const { history } = await access();
@@ -914,6 +1544,7 @@ export async function openSpaceRuntime(deps) {
                 throw new Error(problem);
         }
         let payload = null;
+        let tags = [];
         if (!deleted) {
             // Refused here, where the writer can fix it. On arrival a misfit is kept
             // and flagged instead — see `conforms`.
@@ -925,13 +1556,26 @@ export async function openSpaceRuntime(deps) {
             // signature and relay the record, they just cannot read it.
             payload = body;
             if (space.visibility === 'private' && !IN_THE_CLEAR.has(collection)) {
-                if (!key)
-                    throw new Error('This private space has no key on this node');
+                // Always the key the history names now: one someone removed still holds would do nothing.
+                const key = currentKey((await access()).history.current);
+                if (!key) {
+                    throw new Error(keyring.size
+                        ? `The key of "${space.name}" changed, and the new one hasn't reached this device yet — connect to someone in the space first`
+                        : 'This private space has no key on this node');
+                }
                 // Body and links sealed together: a relay learns neither.
                 const content = links.length ? { body, links } : { body };
                 const sealed = await encryptExpression({ id: '', author: '', collection, createdAt: '', body: content, signature: '', key: version.key, seq: version.seq }, key);
                 payload = sealed.body;
             }
+            // Worked out from the body, with the key it is sealed with: what every reader will check.
+            const topics = collection.startsWith('sys.') ? [] : ((await catalog()).get(collection)?.definition.topics ?? []);
+            if (topics.length) {
+                const sealedWith = looksEncrypted(payload) ? String(payload.keyId) : null;
+                const key = tagKey(sealedWith);
+                if (key)
+                    tags = await tagsFor(await key, collection, topics, body);
+            }
         }
         // Whether superseded versions are kept is the writer's decision, carried
         // on the version — never each reader's, or nodes that had seen different
@@ -939,6 +1583,8 @@ export async function openSpaceRuntime(deps) {
         // history keeps everything: it is replayed whole.
         const retain = ACCESS_COLLECTIONS.has(collection) ||
             collection === PROFILE_COLLECTION ||
+            collection === BOX_COLLECTION ||
+            collection === MEMBER_KEY_COLLECTION ||
             (await catalog()).get(collection)?.definition.history === 'all';
         const { history, events: held } = await access();
         const signed = await signer.sign(createExpression({
@@ -953,6 +1599,7 @@ export async function openSpaceRuntime(deps) {
             seen: history.heads(),
             // In the clear only where the body is: a private space sealed them above.
             ...(space.visibility === 'public' && !deleted && links.length ? { links } : {}),
+            ...(tags.length ? { tags } : {}),
         }), writer.key);
         // The same verdict every other peer will reach: refused here, with the reason, rather than there.
         const judged = await judge(signed);
@@ -972,6 +1619,7 @@ export async function openSpaceRuntime(deps) {
                 throw new Error(stands.reason);
         }
         await storage.addExpression(signed);
+        await markPending(signed);
         channel?.postMessage('changed');
         sync.onLocalChange(signed);
         recordsChanged();
@@ -1041,8 +1689,13 @@ export async function openSpaceRuntime(deps) {
         const creator = !!first && (await judge(first)).root === deps.rootDid;
         return allows(who, { member: true, creator, can: (permission) => roleHolds(role, permissionName(collection, permission)) });
     }
+    // Once at open, then after every change.
+    keepUp();
+    const pulling = pullMirrors();
     return Object.freeze({
         async list(options = {}) {
+            if (options.collection)
+                use([options.collection]);
             const current = (await everyCurrent(options.collection)).filter((e) => options.collection || !e.collection.startsWith('sys.'));
             const shown = [];
             for (const version of current) {
@@ -1090,9 +1743,37 @@ export async function openSpaceRuntime(deps) {
             if (await cannotWrite())
                 return;
             const name = profile.name.trim().slice(0, 64);
-            if (!name || (await profileMap()).get(deps.rootDid)?.name === name)
+            const mine = (await profileMap()).get(deps.rootDid);
+            // An app without the contact key must not take away the one another device published.
+            const contactKey = profile.contactKey ?? mine?.contactKey;
+            if (!name || (mine?.name === name && mine.contactKey === contactKey))
                 return;
-            await upsert(PROFILE_COLLECTION, await profileKey(deps.rootDid), { name });
+            await upsert(PROFILE_COLLECTION, await profileKey(deps.rootDid), { name, ...(contactKey ? { contactKey } : {}) });
+        },
+        rotateKey,
+        readAccess: () => readAccess,
+        async setRelays(named) {
+            const problem = checkRelays(named);
+            if (problem)
+                throw new Error(problem);
+            await upsert(RELAYS_COLLECTION, SPACE_RELAYS_RECORD, { relays: [...named] });
+        },
+        async topicTag(collection, field, value) {
+            let keyId = null;
+            if (space.visibility === 'private') {
+                const key = currentKey((await access()).history.current);
+                if (!key)
+                    throw new Error(`This device doesn't hold the current key of "${space.name}" yet`);
+                keyId = key.id;
+            }
+            return topicTag(await tagKey(keyId), collection, field, value);
+        },
+        async setKeepers(keepers, copies = null) {
+            const named = keepers.map((k) => ({ did: k.did, name: k.name }));
+            const problem = checkKeepers(named, copies);
+            if (problem)
+                throw new Error(problem);
+            await upsert(KEEPERS_COLLECTION, SPACE_KEEPERS_RECORD, { keepers: named, copies });
         },
         async update(recordKey, body, options = {}) {
             const current = await requireLive(recordKey);
@@ -1102,6 +1783,8 @@ export async function openSpaceRuntime(deps) {
             return view(await write(current.collection, body, await after(recordKey), false, links, options.as ? { as: options.as } : {}));
         },
         async linked(recordKey, options = {}) {
+            if (options.collection)
+                use([options.collection]);
             const pointing = (await linkIndex()).get(recordKey) ?? [];
             const keys = [...new Set(pointing.filter((p) => !options.rel || p.rel === options.rel).map((p) => p.from))];
             const found = [];
@@ -1152,6 +1835,7 @@ export async function openSpaceRuntime(deps) {
                 ...(input.links !== undefined ? { links: input.links } : {}),
                 ...(input.permissions !== undefined ? { permissions: input.permissions } : {}),
                 ...(input.rules !== undefined ? { rules: input.rules } : {}),
+                ...(input.topics !== undefined ? { topics: input.topics } : {}),
                 ...(input.screen !== undefined ? { screen: input.screen } : {}),
             };
             const problem = checkStoredCollection(definition);
@@ -1186,6 +1870,10 @@ export async function openSpaceRuntime(deps) {
                 invites: [...state.invites].map(([inviteDid, invite]) => ({ key: inviteDid, role: invite.role, open: invite.open })),
                 role,
                 heads: history.heads(),
+                key: state.keys.length ? { changes: state.keys.length - 1, held: currentKey(state) !== null } : null,
+                relays: state.relays.length ? state.relays : relays,
+                keepers: state.keepers,
+                copies: state.copies,
             });
         },
         async setMember(did, role) {
@@ -1272,10 +1960,13 @@ export async function openSpaceRuntime(deps) {
                 connection,
                 peers: connectedPeers(),
                 accounts: Object.fromEntries([...knownAccounts].flatMap(([peer, known]) => (known.account && routes.has(peer) ? [[peer, known.account]] : []))),
-                root: await storage.getRootCid(),
+                fingerprint: await storage.fingerprint(),
                 rejected,
+                holds: partial ? Object.keys(cacheState.used).sort() : 'all',
+                pending: (await adapter.list(PENDING_PREFIX)).length,
             };
         },
+        use,
         async send(message, to) {
             const encoded = JSON.stringify(message ?? null);
             if (encoded.length > MAX_LIVE_BYTES)
@@ -1287,6 +1978,14 @@ export async function openSpaceRuntime(deps) {
             }
         },
         async close() {
+            closed = true;
+            if (dropTimer)
+                clearInterval(dropTimer);
+            await tidying;
+            await flushCache();
+            await keysRunning;
+            await pulling;
+            await Promise.all(mirrors.map((mirror) => mirror.close()));
             if (watchTimer)
                 clearInterval(watchTimer);
             if (announceTimer)