Patterns

A reference is a value that points somewhere else in the tree.

When a store returns a collection, it doesn't have to embed every item inline. It can return references, lightweight values that say "the real data is over there." A reference is just a map with a path key:

Each reference is a promise: follow the path and you'll find the value. The client decides which references to follow and when. This gives stores control over response size without a separate "fields" or "expand" mechanism.

References can optionally carry type information, a hint about the shape at the other end:

In the hierarchy, references are a value-level convention. They're ordinary map values: no new primitives, no changes to the data model. Any store can return them, any client can detect them. The path in a reference is the same path you'd use to read the value directly.

Collections that are too large for one read. Solved with paths and references, no new mechanisms.

A paginated response includes items and a reference to the next page. The client doesn't construct pagination URLs; it follows the path the store provides:

When links.next is absent, you've reached the end. The loop is: read a page, process items, follow next.

In the hierarchy, pagination is an interface-level convention. The paginated collection is a struct whose fields (items, links) are backed by behavior; the store computes each page on demand. The client iterates by following references, making it a protocol: an interface through time.

Sometimes you need to know what a path does before you use it.

For any path P in a store, reading meta/P returns information about that path: what operations it supports, what shape the data takes, what sub-paths are available. The data and its description live in the same tree, accessed by the same operations.

This is different from metadata on data. A file's size and modification time describe the data itself: suffix metadata (path/meta). The meta lens describes the path: what the address means, what it affords. The two are orthogonal.

In the hierarchy, the meta lens is structural: it operates across all levels. It can describe a value's type, a struct's fields, an interface's capabilities, or a protocol's state machine. It's introspection over the hierarchy itself.

These aren't independent features. They're layers that stack because they share the same substrate.

Mount a service. Any service. Now interact with it through read and write.

The internet already has naming: DNS, URLs, service registries. What it doesn't have is a uniform interaction model. Every service has its own client library, its own pagination scheme, its own error model, its own authentication flow. You need to learn each one separately, test each one separately, and handle each one's failures separately.

Now imagine you mount a proxy store for a weather API at /weather:

You didn't import a client library. You didn't read API documentation. Meta told you what the store offers. References connected the current weather to the forecast. Pagination bounded the forecast into pages. The proxy store translated your reads into whatever HTTP calls the weather API actually requires. You never saw them.

Now mount another service. And another. Your tree grows:

Every store responds to the same two operations. Every collection paginates the same way. Every path is introspectable through meta. You can read from /github/repos and write to /mail/drafts in the same session, with the same interface, and swap any of them for a mock without changing a line of application code.