API Reference barrel_spaces v#1.0.1

Capability tokens for spaces: opaque random tokens verified against server-side grant documents in the _barrel_spaces registry, so revocation is immediate and no key material lives on disk (only a SHA-256 of the full token is stored).

Handoffs: transfer work between agents as a shared space plus a capability. Creating a handoff issues a grant for the space and returns the token once; POSSESSION OF THE TOKEN IS THE RIGHT TO ACCEPT (barrel_memory's handoffs let any authenticated caller accept anything; this closes that hole). Accepting flips the handoff doc pending -> accepted with a rev CAS (double accepts lose), opens the shared space, and creates a session for the acceptor IN it: context is read in place, no snapshot copying.

Sessions: an agent's working context inside a space, folded down from barrel_memory's mechanisms. A session is a regular document (session:Sid) in the space database carrying data, summary, and pinned context; its messages are separate documents (session:Sid:msg:PaddedTs-Rand) whose ids sort chronologically, so history reads are ordered prefix folds.

Spaces: shared context containers for agents. A space IS a barrel database created through this layer: sharing context means holding a capability for the space (see barrel_caps), and every barrel feature (documents, search, channels, timeline, sync, per-database encryption) works inside one unchanged.

Application entry point for the barrel agent layer.

Janitor for session leftovers: when the space's TTL sweeper tombstones an idle session doc, its message docs (which carry no TTL of their own) become orphans. The janitor periodically walks each OPEN space's session: prefix and deletes message groups whose session root is gone. Bounded per pass; deletions are real tombstones.

Top supervisor for the agent layer. Spaces are plain barrel databases owned by Barrel's database lifecycle manager; the only static child (added with sessions) is the janitor that garbage-collects orphaned session messages.