Families
Structural view of the package catalog. For the usage-first intro and the adapter catalog per family, see Families & ports.
noy-db is an encrypted document store: your data lives in a vault, and everything in it is
encrypted inside the core package, @noy-db/hub, before it touches any other code. Everything
outside the hub ships as a satellite — a separate npm package whose name starts with a
preposition: to-, on-, at-, in-, by-, as-. That prefix is the package's family,
and it is not a naming flourish: a family classifies its members by their relationship to the
trust boundary — whether the code may ever see decrypted data, hold key material, or write
vault state. Each family binds exactly one frozen port subpath
(@noy-db/hub/to, /on, /at, /in, /by, /as) and nothing else — never hub internals.
The preposition reads from the vault owner's perspective: data goes to a backend, the owner gets on via an unlock method, a scoped slice is sealed at a host they control, the hub runs in a host runtime or protocol, sessions sync by a transport, and exports go out as a format.
On disk this is flat: the satellites sit directly in the repository's packages/ directory
alongside the core, so folder listing clusters them by family only alphabetically. A
family-folder nesting (packages/in/in-react-style) is planned but not in place today — the
classification lives in the package name, not the path.
The family table
| Prefix | Reads as | Sees plaintext? | May hold keys? | May write vault state? | Binds |
|---|---|---|---|---|---|
to- | data goes to a backend | No — ciphertext only | No | Envelopes only, as told | /to |
on- | get on via this method | No | Handles unlock material, never data-encryption keys | No | /on |
at- | sealed at a trusted host | Scoped slice | Scoped, on your infra | No | /at |
in- | runs in a host | As an authorized consumer (like app code) | No | Via public API only | /in |
by- | sync by way of | No | No | No | /by |
as- | export as a format | Plaintext (post-decrypt, by design) | Never | Never | /as |
An envelope is the encrypted wrapper a record is stored and shipped as — the only shape a
to-* backend ever handles. at- is the one non-zero-knowledge family, by design: a host you
control can decrypt the scoped slice it unseals. Every other family is zero-knowledge —
either it never sees decrypted data at all (to-, on-, by-), or it sees it only the way
your own application code does, after you unlock the vault (in-, as-).
The to- family also spans two repositories: the three essential stores (file, browser
IndexedDB, and the metering store to-meter, which also carries the one-shot store
probes) ship with noy-db itself, while the nineteen extended
cloud, SQL, server, and remote-filesystem adapters ship separately under the same @noy-db/*
scope and bind the same /to port. to-memory moved from the first group to the second on
2026-09-17 — the split is about which repo publishes a store, not about what it does, and a
package keeps its name and its contract across such a move. See the to- catalog
for the full list.
A package answers a different question than a service
A package family answers "who is this code to the vault?" — a service (see
Service layers) answers "what can the vault itself do?".
Nothing is ever both: the two axes are independent and easy to conflate. to-memory (a family
package) and the kernel's record cache both hold data in RAM, but to-memory is a ciphertext
persistence backend outside the trust boundary while the kernel cache is a plaintext
read-acceleration tier inside it — see Kernel.
Prefix-less packages
No prefix means the package holds no vault and serves someone other than (or larger than) a single vault owner. This is a meaningful third tier, not a junk drawer. There are four such packages:
hub— the core: the trust boundary itself, plus every opt-in service.cli— command-line tooling: inspect.noydbbundles without decrypting, verify integrity, validate config, monitor a live vault's store metrics.create-noy-db— the project scaffolding wizard (npm create noy-db).attestation— a pure, zero-dependency verifier for document attestations. Its user is a counterparty — someone verifying a credential you issued — who runs it offline without installing the hub or holding any key material.
Fleet-level orchestration — managing many sovereign vaults at once — is deliberately not a
noy-db package: it lives in the separate @klum-db/lobby product, which binds noy-db only
through published subpaths — the same one-way law the families follow.
Next
Families & ports → — the usage-first intro and full adapter catalog for each family, organized by category and compared in capability tables.