chadtmiller.com/3n2r5ck6rich3
Notes on @atproto/lex-space
Notes on @atproto/lex-space
@atproto/lex-space everything worked pretty well! only major thing that came up was around the scalability of allRecords but I don’t think that’s a big deal right now.
Here's some notes from my agent.
Claude Opus 5.5
From two pieces of work on @atproto/lex-space:
- building a Svelte book club app against a local dev-env network (PLC, two PDSes), with OAuth and
space:scopes. Members share reviews only with each other. - measuring how an app on a group host scales when the browser reads every member's repo in a space itself (
allRecords), with no index service in between.
References:
- atproto branch:
permissioned-data-alpha(head9bd80070f, 2026-11-17) - App: knotless://chadtmiller.com/spaces-bookclub
Overall: the core works, and it's well designed. Most of the friction is ergonomics, and the cost of reading a whole space.
What's good
- Typed by collection.
SpaceClient's typed helpers only accept the collections the space type declares, and that's checked at compile time.allRecords({ collections })narrows each record by type. - The hard parts are built in. Delegation tokens, credential exchange and renewal, routing each request to the right host, MAC verification, and retries after a key rotation or a 401. None of it surfaced in app code.
- The README is excellent. It covers management, building a sync service, and its own limitations, honestly.
Reading a whole space (allRecords)
Measurements
Against a local group host world, debug builds, on a loaded machine:
| Room | Cold open | Downloaded | Client holds | Views in the client | 8 readers at once |
|---|---|---|---|---|---|
| 30 records | 0.25–0.6 s | 15 KB | 0.3 MB | under 0.1 ms | under 1 s each |
| 2,065 records | 0.5–0.8 s | 0.7 MB | 8 MB | 2 ms or less | 1.6–2.2 s each |
| 19,175 records | 3.3–3.6 s, 3.2 s of it client CPU checking records | 5.3 MB | 72 MB | 3–20 ms | 15–17 s each |
Working out views in the client (counts, threads, topics by latest reply) is never the cost. Getting and checking the records is.
Issues
getRepoSnapshothashes every record twice. Reading a repo, it hashes each record once to check the records, and again to compute heads. At 19k records, nearly all of a cold open is that client CPU. Checking without computing heads would roughly halve it (an estimate, not measured).allRecordskeeps nothing between calls.- Every reader pays the full read on every open, and each repo is held in memory whole (README limitation).
- Reading on is cheap at any size: about 6 requests, 6 KB and 150 ms after new writes, and one request when nothing changed. lex-space already has what it needs (
writers({ cursor }), andpullRepofrom kept heads), butallRecordsdoesn't use it. - The fix is to keep each repo's head and records, in memory while the page is open and in IndexedDB between visits, and read on from there. Then a member pays the full read once per device. This matters more than #1 at scale.
- One host's failure fails the whole read.
- Repos are fetched 4 at a time with
Promise.all, so each group waits for its slowest host. - Only
RepoNotFound,RepoTakendown,RepoSuspendedandRepoDeactivatedare skipped. A network error or 5xx from any one member's host fails the whole iteration. - There's no option for partial results, or for per-repo error reporting.
- Repos are fetched 4 at a time with
Where that leaves an app
The browser alone serves groups up to a few thousand records in a space. Past that, an app should read from an index service: one that registers as a syncer of the space (authorizeSpaceSync with notify), keeping counts, links, orders and hiding.
Other library issues
- The README's main example doesn't type-check against generated code. For a
spacedef,lex buildonly emits$nsidandmainon the namespace. SoSpaceClient.openSpace(com.example.forum, …)as documented fails to compile, and you have to passcom.example.forum.main. Record namespaces work as documented, since they expose$type,$buildand so on. - Argument styles vary between constructors.
SpaceClient.openSpace(schema, ref, { agent, ...options })takes the agent in its options.SpaceClient.createSpace(agent, schema, { policy, skey }, options)takes the agent first, and splits input and options into separate arguments. It's easy to putdidResolverin the input object; TypeScript does catch that (TS2353).SpaceManager.open(agent, uri, options)accepts anAgent, and checks at runtime that it's signed in.new SpaceManager(agent, uri)requires anAccountAgent, so passing a plainclient.agentfails to compile (TS2345). The tests work around it with anagentOf()helper.
- Credentials live in memory only, per
SpaceClient. Every page load paysgetDelegationTokenplusauthorizeSpaceSync(two round trips) per space before the first read. Apps also need their own one-client-per-space map, because a new instance exchanges again.@atproto/oauth-clientlets you plug in session and state stores; a credential store hook here would match. - No client-wide DID resolver default. It defaults to plc.directory. In development, every
openSpaceandcreateSpaceneedsdidResolverpassed explicitly.
Checked and fine
- Removing a member with
MemberspacePolicyManager.removeMembers()drops their records fromallRecords()immediately. No separateremoveWriter()is needed for reads.
Suggested follow-ups
| Item | Kind |
|---|---|
allRecords: keep heads and records, and read on with writers({ cursor }) and pullRepo | API |
getRepoSnapshot: hash each record once | Performance |
allRecords: per-repo errors, a partial-results option, a sliding concurrency window | API |
| Generate schema accessors on space namespaces, or fix the README | Codegen / docs |
One argument convention across openSpace, createSpace and SpaceManager; accept Agent everywhere | API |
Credential store hook, and a shared client-level SpaceClient cache | API |