@weaveprotocol/core 0.1.2 → 0.2.1

package/README.md

@@ -4,6 +4,11 @@ A peer-to-peer data protocol for the browser. You own your identity as a
 written-down code, keep your data in signed records that sync directly between
 devices, and every app is a view onto that data rather than its owner.
 
+> **Building a client, or an agent that needs the architecture?** The
+> protocol is specified in [docs/spec](docs/spec/README.md): wire formats,
+> what is signed, and what every peer must check. The tests are its
+> executable half.
+
 ## Architecture
 
 ```
@@ -11,11 +16,11 @@ devices, and every app is a view onto that data rather than its owner.
 │                        Applications                          │
 ├──────────────┬───────────┬────────────┬──────────┬───────────┤
 │   Accounts   │  Spaces   │ Validation │ Privacy  │   Sync    │
-│ seed, vault, │ roles,    │ crypto →   │ AES-GCM  │ MST anti- │
-│ root signer, │ members × │ structural │ per      │ entropy   │
-│ UCAN, pairing│ pub/priv  │ → UCAN     │ space    │ gossip    │
+│ seed, vault, │ roles,    │ crypto →   │ AES-GCM  │ Negentropy│
+│ root signer, │ members × │ structural │ per      │ per       │
+│ UCAN, pairing│ pub/priv  │ → UCAN     │ space    │ collection│
 ├──────────────┴───────────┴────────────┴──────────┴───────────┤
-│    Storage: Merkle Search Tree over a StorageAdapter         │
+│    Storage: signed versions + plain index over an adapter    │
 │    IndexedDB (per origin) · data folder (shared by origins)  │
 ├──────────────────────────────────────────────────────────────┤
 │    Network: WebRTC data channels                             │
@@ -71,7 +76,7 @@ const ucan = await root.delegate({
 const spaces = createSpaceManager(await createIndexedDBAdapter('my-app/registry'));
 const { space } = await spaces.create({ name: 'Notes', visibility: 'public', creator: me.did });
 
-// 4. A signed record, stored in that space's own Merkle tree
+// 4. A signed record, stored in that space's own store
 const storage = createStorageProvider(await createIndexedDBAdapter(`my-app/space/${space.id}`));
 const signed = await createSigner(provider).sign(
   createExpression({
@@ -222,6 +227,105 @@ await calls.answer(ringing.id);  calls.setMuted(true);  await calls.shareScreen(
 
 The messages, and the reasoning, are at the top of `src/calls/calls.ts`.
 
+### Contacts
+
+A DID is a **name, not an address**: it's on everything you sign, so knowing
+it must not be enough to reach you. What lets two people reach each other is a
+space they share. So **a contact is a private space for two**: records you
+write there wait for the other person, and live messages reach them when
+they're online. There's no directory to look people up in, and no inbox
+strangers can knock on — unless you open a door (below).
+
+```typescript
+// In a space you share with Anna — the book club — ask her to add you.
+const { space } = await node.contacts.ask(club.id, anna, { note: "it's Leif from book club" });
+
+// On Anna's side:
+const [request] = await node.contacts.requests(club.id);   // { from, name, note, pairSpace, … }
+await node.contacts.accept(club.id, request.key);           // joins the space for two, adds Leif
+
+await node.contacts.list();          // [{ did, name, space, note, blocked }]
+await node.contacts.put({ did, name: 'Anna K' });   // what you call them — only you see it
+await node.contacts.remove(anna);    // off the list, and out of your space with her
+await node.contacts.block(anna);     // and her requests are hidden in every space
+await node.contacts.others(anna);    // anyone else in your space with her: [] unless someone was let in
+```
+
+- **The list** is one `std.contact` per person, in a **contacts space**
+  derived from the account key the way the account registry is: every device
+  of the account has it, nobody else can find it, and it's hidden from
+  `spaces.list`. `contacts.space()` gives its id. A carrier carries it, so a
+  restore brings the list back.
+- **Asking** (`ask`) makes a private space for the two of you, puts them on
+  your list with it, and posts a `std.contact-request` in the shared space:
+  the new space's invite, **sealed with their contact key**. The other members
+  can see that you asked, not what. The seal is bound to the space it was
+  posted in and to who asked whom, so a request copied into another space, or
+  re-posted by someone else, doesn't open. Joining is the answer: there's no
+  reply record.
+- **The contact key** is a P-256 key for encryption, derived from the seed
+  under its own label (`deriveContactKeyBytes`), so it's the same on every
+  device and comes back with the recovery code. Its public half goes on your
+  profile in every space you write in (`spaces.profiles(id)[n].contactKey`),
+  and only counts on a profile signed by your own account. An app without the
+  key never takes it off: a profile keeps the newest key it was given.
+- **Conversation or group** is decided by how the space was made, not by how
+  many people are in it: a space is your conversation with Anna because your
+  list says so. A space made with "New space" and shared with one person is
+  never one. If a third account turns up in a space for two, `others` says so,
+  and an app can offer to start a new space with just the two of you, or a new
+  group with everyone.
+
+**What an app gets.** A home gives the contacts to an app that asks with
+`contacts: true`: the contacts space as one more space in its grant, and the
+contact key, which opens requests sent to you. Asking someone and accepting
+also make or join a space, so those need `scope: 'account'`, which includes
+the contacts. Agents never get them.
+
+### Doors
+
+Someone you share no space with can still ask to become your contact — if you
+give them a **door**. A door is a code you hand out on purpose (a link, a QR
+code, a line in your bio) and can close. It names a key derived from your
+contact key and the relays whose mailboxes hold knocks on it, and nothing
+about who you are.
+
+```typescript
+const door = await anna.doors.open();              // { id, code, relays, … }
+share(`https://chat.example/#door=${door.code}`);
+
+// Leif, who has never shared a space with Anna, pastes the link:
+await leif.doors.knock(link, { note: 'We met at the gig' });   // a space for two, its invite sealed to the door
+
+// Anna, whenever she's next online:
+const [knock] = await anna.doors.knocks();         // { from, name, note, pairSpace, … } — `from` is proven
+await anna.doors.accept(knock.id);                 // joins; Leif is a contact, and she is his once it syncs
+await anna.doors.close(door.id);                   // the code leads nowhere now; contacts stay
+```
+
+- **The relay keeps a mailbox**, the one thing it holds: a sealed blob under a
+  hash of the door's signing key, for up to 14 days. It sees addresses, as it
+  does for any socket, but not whose door it is, which account knocked, or what
+  they said. A door names up to three relays and a knock goes to all of them,
+  so no one relay can shut it.
+- **A knock proves who knocked** before anyone joins anything: it's signed by
+  the knocker's session key under a note for their whole account, like a
+  record, bound to the door it was left at and to when the relay took it.
+- **An answer proves who opened.** Accepting writes an answer in the space for
+  two, signed with the door's key: that, not joining, makes the owner the
+  knocker's contact, and the invite is closed behind them.
+- **The door is not the account.** Its key is not your contact key, so nobody
+  can link a door to your profile in any space. Every device with the contact
+  key opens the same doors.
+- **Spam** is capped at the mailbox (64 knocks a door; 4 a door and 30 in all
+  an hour from one address). `dismiss` lets one knock go without blocking,
+  blocking hides someone's knocks on every door, and a flooded door is cleared
+  by its owner (`clear`), so its code keeps working.
+
+Next: handles that lead to a door, so `@anna.bsky.social` works where a code
+does (planned in [07 — Doors](docs/spec/07-doors.md), Names). The full design is
+[docs/spec/07-doors.md](docs/spec/07-doors.md).
+
 ## Signing in — the element, and React
 
 Getting to a node takes a sign-in flow: where the data lives (a pod or this
@@ -362,12 +466,51 @@ the account's list on every device.
 An app that is a view onto *everything* — like the example — asks for
 `scope: 'account'`: a note for every space, plus the key the account's space
 list is derived from, so it sees every space and can make and join them. It
+gets the contacts too (see Contacts, above). It
 still never holds the seed: it cannot sign in anywhere as the account, change
 its password or passkeys, or keep access past the note's date.
 
 The home side is `receiveConnectRequest()` and `auth.grant(…)`; see
 [home/README.md](home/README.md).
 
+### Apps hold what they use — keepers hold the rest
+
+A space can name its **keepers**: nodes that hold every record of it, like a
+host or the extension (`node.spaces.setKeepers`, for someone who manages the
+space; the account's carriers are named by themselves in every space it
+manages). Once it does, an app connected to the account home holds only the
+collections it uses, besides the space's own (`sys.*`):
+
+- a query says what it needs — its collection and every `include … from` —
+  and those start syncing from any peer that has them;
+- `result.complete` is false until they have caught up with a node holding
+  the whole space: show "Loading…", not "Nothing here";
+- the app's own writes stay **pending** until enough keepers say they have
+  them (`stored`): the space's `copies`, or 2, never more than it names.
+  Nothing pending is ever dropped;
+- a collection no query has touched for `unusedAfterDays` (30) is dropped,
+  unless the app declared it (`cache.collections`). It syncs back when needed.
+
+A collection can also name **topic fields** (`topics: ['channel', 'mentions']`).
+Each record then carries, on its outside, a keyed hash of each of those values
+(`tags`), so a keeper that can't read the record can still match "in
+#design" or "mentions me" — learning which records share a topic, never which
+topic. `node.collections.tag(space, collection, field, value)` gives the tag to
+match; anyone who can read a record checks its tags and refuses a mismatch.
+
+**"Notify me when…"** (`node.notifications`, and the home's section of that
+name): new records in a collection, in every space or some, perhaps only with
+a topic value ("mentions me"), perhaps only other people's. The account
+registry keeps each one sealed; every carrier gets it with the value replaced
+by each space's tag, so the Weave extension notices matching records as they
+arrive and shows a notification — the space, your label, the time — without
+being able to read them, or what you asked for.
+
+A space that names no keeper is held whole, as before: then the app may be one
+of its copies. How much to hold is each node's choice (`NodeConfig.cache`;
+`startConnectedNode` turns it on unless given `cache: false`); only how
+keepers confirm is protocol. `spaces.status(id)` shows `holds` and `pending`.
+
 ## Modules
 
 ### Identity (`@weaveprotocol/core/identity`)
@@ -484,16 +627,27 @@ Typed, signed data expressions using [Standard Schema](https://standardschema.de
 
 ### Storage (`@weaveprotocol/core/storage`)
 
-Local-first storage with Merkle Search Tree for efficient sync.
+Local-first storage: signed versions, and plain entries saying which is current
+and which versions each collection keeps — the set sync compares.
 
 | Export | Description |
 |--------|-------------|
-| `createStorageProvider()` | MST-backed expression storage; `compact()` deletes tree nodes the root no longer reaches |
+| `createStorageProvider()` | Expression storage: current, first and retained versions (`r/`, `g/`, `h/`), and every kept version by collection (`i/`) for sync; `fingerprint()` is equal on two stores keeping the same versions |
 | `createIndexedDBAdapter()` | IndexedDB storage adapter, scoped to this origin |
 | `createFolderAdapter()` | A user-picked directory, shared by every origin given access |
 | `createEncryptedAdapter()` | Seals chosen keys (space records, space keys) at rest |
-| `reconcileFolder()` | Rebuilds the tree after another writer touched a folder |
-| `insertIntoMST()` / `listMSTEntries()` | Direct MST operations; a listing can stop at a key prefix |
+| `reconcileFolder()` | Places the files another writer added to a folder, and drops entries whose file is gone |
+| `createMirror()` | Keeps a space in a dumb file store too, synced like a peer that never runs code |
+| `createS3BlobStore()` / `createMemoryBlobStore()` | File stores a mirror can use: any S3-compatible bucket (R2, B2, MinIO, AWS), or memory |
+
+**Mirrors.** A bucket or an app folder can hold a space: each writer (one store
+on one device, with a random id) only ever adds immutable segments in its own
+folder, named by a counter and the hash of their bytes — so nothing is written
+twice and nothing needs a lock. A segment holds versions exactly as they travel,
+private bodies still sealed, and everything read back passes the same gates as a
+peer's records: the store can hide things, not forge them. What a writer knows
+the store holds, it never uploads again; a writer compacts its own segments
+into fewer. Merging is the protocol's own — a set of versions that only grows.
 
 ### Spaces
 
@@ -523,7 +677,7 @@ const { space, key } = await spaces.create({
 });
 ```
 
-Give each space its own storage and its own MST and a peer you share one list
+Give each space its own storage and its own sync and a peer you share one list
 with learns nothing about the others.
 
 #### Who may write: roles, and a history every peer replays
@@ -543,8 +697,9 @@ and roles ranked below you, and give out roles up to your own rank. Two people
 at the same rank can never remove each other, only themselves — so the creator
 **hands over** by giving someone their role, then leaving, and the space goes on.
 
-Roles, members, invites, revoked notes and collection definitions are records
-(`sys.role`, `sys.member`, `sys.invite`, `sys.revoke`, `sys.collection`), and
+Roles, members, invites, revoked notes, collection definitions and changes of a
+private space's key are records (`sys.role`, `sys.member`, `sys.invite`,
+`sys.revoke`, `sys.collection`, `sys.key`), and
 every record written anywhere names the latest of them its writer knew, as
 `seen`. That makes the **access history** a small graph, which every peer
 replays the same way (`space/roles.ts`): a change comes after what it saw;
@@ -586,15 +741,35 @@ connect under someone else's name, and in a private space with the read key
 too, checked against its public half. A stranger who learns a space's id, or a
 relay that sees its room, gets no ciphertext. A peer-to-peer handshake also
 signs both ends' DTLS fingerprints, so a relay that swapped in its own offer to
-sit in the middle is caught. Roles govern writing only: someone removed keeps
-the read key until the space's key changes for everyone (BLOCK-14 §2).
+sit in the middle is caught.
+
+**Removing someone from a private space changes its key**, the way Keybase
+changes a team's key. Whoever manages the space, seeing someone lose their
+place (removed, left, or their role deleted), makes a new key by itself and
+writes a `sys.key` record: the new key's id and public read key, and every
+earlier key sealed under the new one. It is part of the access history, so two
+new keys made apart resolve like any other change, and only `manage` may make
+one. Each member's copy goes in a `sys.box`, sealed to their **member key**: a
+key pair per account per space, derived from the account's vault key, whose
+public half each member publishes in the clear (`sys.memberkey`). An account
+home hands an app the member keys of exactly the spaces it grants.
+
+From then on new records are sealed with the new key. Someone removed keeps what
+they could already read, and nothing after it. Holding the current key opens
+every earlier one, so a newcomer reads the space's past. A member who was away
+when the key changed still holds only the older read key: they prove that, and
+send their note sealed under the older key, and a peer holding it lets them in
+if they are still a member. A host with no key takes the current read key only.
+View-only links made before the change stop working; share a new one.
+`node.spaces.changeKey(space)` does the same by hand, for a lost device.
 
 A space's **id is the hash of what is fixed at creation**: creator, visibility,
 starting roles and which one the creator holds, time, a random nonce and the
-read key (the name is left out, so it can change). `join` refuses an invite
-whose space does not hash to its id, or whose key is not the one the space
-names — so whoever passes an invite on cannot change who started the space, or
-with which roles.
+first read key (the name is left out, so it can change). `join` refuses an
+invite whose space does not hash to its id — so whoever passes an invite on
+cannot change who started the space, or with which roles. The key an invite
+carries may be a later one; its id is its hash, so it is either the key the
+history names or one that opens nothing.
 
 **Spaces describe themselves.** A space stores its collections' definitions —
 name, title, description and a JSON Schema — as signed records in
@@ -774,23 +949,36 @@ tell a Weave peer from anyone else, so set coturn's own quotas (`user-quota`,
 `total-quota`, `max-bps`). TURN only forwards encrypted packets; it can't
 see or hear a call.
 
+The relay's Docker image (`server/`, deployed to Fly) runs coturn beside it when
+`TURN_SECRET` is set, already capped that way: `server/fly.toml` says how.
+
 Only peers already in a room hear about a newcomer, so exactly one side creates
 the offer and the two never collide.
 
 ### Sync (`@weaveprotocol/core/sync`)
 
-Anti-entropy gossip protocol for eventual consistency.
+Range-based set reconciliation (Negentropy, as Nostr's NIP-77), one collection at a time.
 
 | Export | Description |
 |--------|-------------|
-| `createSyncEngine()` | Automatic MST reconciliation with heartbeat |
-| `verifyNode()` / `unknownChildren()` | The pieces of a tree walk |
-
-Two peers compare roots — equal means identical, one round trip. Otherwise each
-walks the other's tree from the root, skipping every subtree already in its own,
-so cost follows the size of the difference: one changed entry in 10,000 costs
-about 37 KB on the wire, where sending every key cost 508 KB. Whether a subtree
-is already here is one lookup in the store, not a read of the whole local tree.
+| `createSyncEngine()` | Reconciles a space with its peers, with a heartbeat |
+| `createReconciler()` / `ItemSet` / `fingerprintOf()` | Negentropy itself, wire-compatible with the reference implementation |
+
+A peer says hello with a fingerprint of each collection it keeps — in essence
+the sum of its version ids. Equal fingerprints mean the same versions, and that
+collection is done. For each one that differs, the peer whose id sorts first
+compares fingerprints of ever smaller ranges with the other until both know
+exactly which versions each lacks; then it asks for what it lacks and sends what
+the other does. Cost follows the difference, not the size: one new version
+among 2,000 syncs in under 8 KB, all told. Nothing is stored for sync beyond
+the versions' own index entries: the sets and sums live in memory, updated by
+every change and read again when another writer (a tab, a folder) changed the
+store.
+
+Each hello also says what the peer holds — `all`, or some collections — and
+two peers reconcile only the collections both hold. A version for a collection
+a node doesn't hold is passed over; one it takes in, it tells the sender it has
+(`stored`). One peer's messages are handled in the order they came.
 
 The engine's `validate` hook is the seam where the validation engine sits.
 Expressions a peer sends are only committed if it accepts them; the rest are
@@ -862,7 +1050,7 @@ interface StorageAdapter {
 - `createIndexedDBAdapter(name)` — works in every browser. Origin-scoped.
 - `createFolderAdapter(directory, namespace)` — a directory the user picked, via the File System Access API. **Not** origin-scoped. Chrome, Edge and Opera on the desktop.
 
-The always-on node (`weave run`) uses the folder adapter on disk, in the same layout. **Planned**: mirrors, which keep a space in storage the user already pays for (a Dropbox app folder, Drive, S3) and sync with it like a peer — see `docs/blocks/BLOCK-03-mirrors.md`. OPFS is not on the list: it is origin-private, so it would inherit exactly the limitation a data folder exists to avoid.
+The always-on node (`weave run`) uses the folder adapter on disk, in the same layout. **Planned**: mirrors, which keep a space in storage the user already pays for (a Dropbox app folder, Drive, S3) and sync with it like a peer — see [05 — Sync and storage](docs/spec/05-sync-and-storage.md). OPFS is not on the list: it is origin-private, so it would inherit exactly the limitation a data folder exists to avoid.
 
 ### Data folders — storage that outlives the origin
 
@@ -877,7 +1065,7 @@ A directory handle is the exception. Each origin asks for permission once, and b
   accounts.json                       name, DID and id of each account (readable without unlocking)
   accounts/<id>/account.json          that account's seed, encrypted once per way of unlocking it
   accounts/<id>/stores/<namespace>/
-    kv/<key>                          MST nodes, the root pointer, space records (sealed)
+    kv/<key>                          index entries (current, first, retained, by collection), space records (sealed)
     expressions/<cid>.json            one signed record per file
 ```
 
@@ -910,11 +1098,11 @@ const registry = createEncryptedAdapter(
 );
 ```
 
-**Expressions are the truth; the MST is an index over them.** That inversion is what lets several writers share one folder without taking a lock. Every expression file is named by its own content hash, so concurrent writers can only ever add files that agree; the single mutable thing, the root pointer, is derived state that either side can rebuild. `reconcileFolder()` rebuilds it — call it on an interval, on window focus, or after a sync round, since the web has no filesystem change notification.
+**Expressions are the truth; the entries are an index over them.** That inversion is what lets several writers share one folder without taking a lock. Every expression file is named by its own content hash, so concurrent writers can only ever add files that agree; the one thing both can overwrite, which version a record's current entry names, is derived state either side can put right. `reconcileFolder()` does — it places every file that appeared, which corrects an entry a race left wrong — so call it on an interval, on window focus, or after a sync round, since the web has no filesystem change notification.
 
 Two consequences worth having:
 
-- **The folder is the account.** Copy it to a USB stick and it is your whole identity. Put it in iCloud, Dropbox or Syncthing and several devices converge with no relay at all — the folder becomes a second transport alongside WebRTC, and both meet in the same anti-entropy merge.
+- **The folder is the account.** Copy it to a USB stick and it is your whole identity. Put it in iCloud, Dropbox or Syncthing and several devices converge with no relay at all — the folder becomes a second transport alongside WebRTC, and both meet in the same merge: the set of versions only grows, and the version rule picks the same current one everywhere.
 - **It changes nothing about the mesh.** A folder-backed node is an ordinary peer that happens to be durable and readable by several origins — an availability role, never an authority one. Where there is no folder (Safari, Firefox, mobile) a node keeps an origin-scoped replica and gossips exactly as before.
 
 ### Locking the folder
@@ -939,7 +1127,7 @@ await accounts.write(account, withWrap(vault, wrap));
 
 `deviceWrapsFor(vault, rpId)` says which wraps this origin can even attempt; the rest name keys it cannot reach. The gate is enforced in application code rather than by cryptography — see `src/identity/device-key.ts` for what that does and does not protect against. The recovery code needs no wrap, because it *is* the seed in printable form — it opens the folder anywhere, including on a phone or in a browser with no File System Access API, and it is shown once and stored nowhere.
 
-`createEncryptedAdapter` seals `space:`, `spacekey:`, `spaceinvite:` and `spacerole:` values under the vault key, which is what makes a private space genuinely unreadable to someone holding the folder. It is scoped deliberately narrowly: expressions and MST nodes pass through, so what stays legible is each record's author, timestamp and collection, plus anything in a space its owner made public. Sealing those too would mean an opaque blob store, which would cost the property that makes a folder worth having.
+`createEncryptedAdapter` seals `space:`, `spacekey:`, `spaceinvite:` and `spacerole:` values under the vault key, which is what makes a private space genuinely unreadable to someone holding the folder. It is scoped deliberately narrowly: expressions and index entries pass through, so what stays legible is each record's author, timestamp and collection, plus anything in a space its owner made public. Sealing those too would mean an opaque blob store, which would cost the property that makes a folder worth having.
 
 ### Where the root key lives
 
@@ -991,6 +1179,18 @@ space with is a peer in that one only.
 **Several relays**, so there is no single phone book — a peer announced by two
 of them is announced upward once, and replies go back the way they arrived.
 
+**The space says where it meets**, like a Nostr relay list, but the space's
+own. `sys.relays` is part of the access history, so only someone who manages
+the space changes it (`node.spaces.setRelays`), and a new space names its
+creator's relays by itself. Invites carry the list, so a joiner whose app uses
+other relays reaches the space before anything has synced. Every member then
+joins the space's room on those relays as well as their own
+(`mesh.useRelays(room, relays)`); relays only one space names are joined for
+that space's room alone, and dropped once no open space names them. Moving a
+space to another relay, a self-hosted one say, is one change, and everyone
+follows. No DHT: browsers can't be DHT nodes, and would need a relay to reach
+one anyway.
+
 **Peers introduce peers**, so a relay is only needed for the *first* connection.
 Once you are connected to someone, their data channel carries signalling for the
 peers you have not met: `__peers` says who I can see, `__signal` carries
@@ -1089,6 +1289,27 @@ it doubles as a relay), and `weave mcp` to hand the same operations to an agent.
 It reads and writes the same data folder layout a browser does. See
 [cli/README.md](cli/README.md).
 
+**Hosting.** `weave host` keeps many accounts' spaces online without being able
+to read them: it is the extension's carrier (`createCarrierNode`) with one carry
+space per paying account (`createHostNode`), each space held once however many
+members pay for it. A subscription is a key the account makes and keeps in its
+registry (`sys.hosting`), so every device signs as it; `node.hosting.use(url)`
+starts one, and whichever device notices it is paid hands the host the carry
+space. Every call to the host is signed over method, path, time and body.
+The home knows nothing about payment ([06 — Nodes, sessions and apps](docs/spec/06-nodes-and-sessions.md), Hosts): a host describes itself at
+`/.well-known/weave-host` (like a Nostr relay's NIP-11 document), signs every
+status it gives — the home keeps the latest in the registry as the person's
+proof — and takes payments on its own pay page, which `node.hosting.payPage(url)`
+links to with a signature by the subscription key, valid for an hour at that
+host only. On the page: Stripe Checkout and the Customer Portal (card, Apple
+Pay, Google Pay), whose webhook moves a paid-until date taken from Stripe's own
+billing period; and USDC from a crypto wallet straight to the host's address,
+checked on the network by the host. Past the date: a grace period, then the host drops
+the spaces and deletes its copy. With a bucket (`WEAVE_S3_*`) the host's disk
+is only a cache — every carried space and the subscription list live in the
+bucket, sealed, and a new machine starts from it. The account home's Settings
+has **Keep my spaces online**.
+
 ## Example app
 
 `example/` is the Weave website — a landing page for developers at `/`, and
@@ -1101,11 +1322,44 @@ npm install && (cd example && npm install) && (cd home && npm install)   # the C
 npm run dev
 ```
 
-That starts three things: the example app on 5173, the account home it
-connects to on 5174, and an always-on node on port 8787 that is also the relay.
-The node gets a throwaway identity on first run (`cli/.env.dev`, data in
-`.weave-dev/`), and `example/.env.development` points the app at the other two.
-Override either in a `.env.local`.
+That starts everything, with coloured output per part, and Ctrl-C stops it all:
+
+| Part | Where | What |
+|---|---|---|
+| app | http://localhost:5173 | The example app |
+| home | http://localhost:5174 | The account home it connects to |
+| node | port 8787 | An always-on node that is also the relay; a throwaway identity on first run (`cli/.env.dev`, data in `.weave-dev/`) |
+| host | http://localhost:8788 | `weave host`, what "Keep my spaces online" uses, with its pay page at `/pay`; settings in `cli/.env.host.dev` |
+| stripe | — | Only when you add a Stripe test key (below): forwards Stripe's webhooks to the host |
+
+`example/.env.development` and `home/.env.development` point the app and home
+at the rest. Override any of them in a `.env.local`, and the host in
+`cli/.env.host.local`.
+
+**Trying hosting and payments.** In the home: Settings, **Keep my spaces
+online**, **Keep online** (the dev host is filled in), then **Payment**, which
+opens the host's pay page in a new tab. What you can pay with there:
+
+- **A browser wallet, on by default.** Payments go to Base Sepolia, a test
+  network: test money only. In MetaMask (or any browser wallet), get test ETH
+  for the fee from a Base Sepolia faucet (Coinbase's, or Alchemy's) and test
+  USDC from faucet.circle.com (choose Base Sepolia). Pay, and the pay page
+  says "Payment received"; back in the home's tab, the host shows "paid until"
+  and takes your spaces. To see payments arrive, set your own address as
+  `WEAVE_WALLET_ADDRESS` in `cli/.env.host.local`.
+- **A card, in Stripe's test mode.** In `cli/.env.host.local`, add
+  `STRIPE_SECRET_KEY=sk_test_…` and the price ids of a monthly and a yearly
+  recurring test price (`STRIPE_PRICE_MONTHLY`, `STRIPE_PRICE_YEARLY`, from the Stripe
+  dashboard in test mode). With the Stripe CLI installed, `npm run dev`
+  forwards Stripe's webhooks to the host by itself. Pay with card
+  4242 4242 4242 4242, any future date, any CVC.
+- **Phone wallets, by QR code.** Add `WEAVE_WALLETCONNECT_PROJECT_ID` (free at
+  dashboard.reown.com, with localhost allowed in the project) to
+  `cli/.env.host.local`; `npm run dev` builds what the pay page needs. The
+  wallet has to be on Base Sepolia too.
+
+`npm test` covers the same paths without any of this: a fake network, fake
+Stripe calls, and the home's side against a real host.
 
 The example never signs anyone in: "Connect with Weave" opens the home, where
 you make an account or sign in, and allow the example your whole account. Its
@@ -1129,7 +1383,7 @@ between pods, pair a phone by QR code, and see which apps you connected. In the
 example: make private or public spaces, just yours or with people you invite, and share one with a
 friend via an invite link. Everyone in a space is shown by the name
 they gave. Every record is signed by a delegated session key, stored in that
-space's MST, encrypted first if the space is private, and gossiped to peers over
+space's own store, encrypted first if the space is private, and gossiped to peers over
 WebRTC; a record says *verified* once its signature and its delegation chain
 check out here, and *encrypted* when it arrived encrypted.
 
@@ -1190,7 +1444,23 @@ the agents it finds, and they start `weave mcp` themselves: a node of its own,
 over WebRTC (`node-datachannel`), that follows the account and keeps working
 with every tab closed. What it writes shows "via agent", and every peer
 ignores an agent changing collections, who may do what, or the account's own
-list of spaces. See BLOCK-20.
+list of spaces. See [06 — Nodes, sessions and apps](docs/spec/06-nodes-and-sessions.md), Agents.
+
+## Still to do in the library
+
+What the protocol still has planned is in [the spec](docs/spec/README.md), under
+**Planned** in each part. Library work that isn't protocol:
+
+- **Typed queries, further.** Typed field paths and operator values in
+  `where`, a misspelled collection name as a compile error, typed link roles,
+  types generated from a space's stored definitions, and a dev-time warning
+  when declared schemas differ from the space's catalogue.
+- **Typed collections.** One TypeScript builder that emits the schema, the
+  rules and the types, and typed handles (`node.use(space, Poll)`).
+- **Definitions that update themselves.** `useSchemas` and `addApp` applying
+  harmless changes, with `differences()` in `src/schemas/apps.ts` replaced by
+  the planned `compare` ([02](docs/spec/02-records.md), compatible definitions).
+- **Web components** for the standard schemas.
 
 ## Releasing
 
@@ -1201,11 +1471,18 @@ workspace) are released together, always with the same version:
 npm run release
 ```
 
-It typechecks and runs the tests, then [bumpp](https://github.com/antfu-collective/bumpp)
+It checks you're logged in to npm first (and runs `npm login` if not),
+typechecks and runs the tests, then [bumpp](https://github.com/antfu-collective/bumpp)
 asks for the next version, writes it to both packages, and commits and tags
-it (`v0.1.2`). Both are published (each builds itself first: `dist/` for the
-core, one bundled file for the CLI), and only then is the commit pushed. The
-settings are in `bump.config.ts`.
+it (`v0.1.2`), locally. Both are published (each builds itself first: `dist/`
+for the core, one bundled file for the CLI), and only then are the commit and
+tag pushed.
+
+If a release stops partway — npm login, a one-time password, the network —
+fix it and run `npm run release` again. It sees the version isn't fully on npm
+yet and publishes what's missing, instead of bumping again. `npm run release
+-- --dry-run` does everything but publish and push. The script is
+`scripts/release.mjs`; bumpp's settings are in `bump.config.ts`.
 
 ## Tests
 
@@ -1218,8 +1495,8 @@ for the same private scalars, and pinned to recorded DIDs so an accidental
 change cannot slip through; recovery codes; account vaults, wraps and account
 stores; data folders with several writers; spaces, invites and
 encrypt-then-sign; UCAN issuing, attenuation and chain validation; phone
-pairing; peer introductions; the MST; the validation gates; and two peers
-reconciling over the anti-entropy protocol, including the forged, stolen,
+pairing; peer introductions; Negentropy, checked against the reference
+implementation; the validation gates; and two peers reconciling, including the forged, stolen,
 unauthorized and malformed expressions their gatekeepers reject. Above those:
 the node API — versioned records, links, queries, collection definitions,
 profiles, the account registry, moving and merging accounts — and the CLI.