Kernel
Mirrors
packages/hub/src/kernel/in thenoy-dbrepo.
The kernel is the always-on, mandatory core of @noy-db/hub — the code every consumer
ships no matter how the database is configured. It provides the vault (an encrypted
database instance), collections (the typed record sets inside a vault), the query
engine, the keyring (the per-vault structure that wraps each collection's data keys),
and the service bus — an internal, per-instance event bus on which the kernel dispatches
write-lifecycle events so that opt-in with-* services can
observe completed writes (audit, devtools, sync dirty-marking) or gate pending ones
(write guards, closed accounting periods) without the kernel ever naming a service. Nothing
in the kernel is tree-shaken; that is what distinguishes it from a with-* service layer.
Even the smallest possible setup ships the whole kernel:
import { createNoydb } from '@noy-db/hub'
// No store configured, no with-* services opted in — the kernel alone.
// `store` defaults to the built-in in-memory store (non-persistent).
const db = await createNoydb({ user: 'ada', secret: 'a-long-secret' })
const vault = await db.openVault('notes')
// → Vault — encrypted end to end, held in the built-in memory store
Spine files
The kernel folder is mostly flat files, not sub-packages — the spine:
noydb.ts (the Noydb entry point), vault.ts (openVault() → Vault), collection.ts
(vault.collection<T>() → Collection), types.ts, errors.ts, schema.ts, refs.ts,
validation.ts, collection-config.ts, write-queue.ts, constants.ts, events.ts,
debug.ts, env-check.ts, memory-store.ts (the built-in default store), sync-policy.ts,
and money-runtime.ts. Individual .ts files are illustrative and churn over time —
folders are the architecture, and it is the folder level that this documentation tracks.
The five sibling folders
Beside the spine files, kernel/ holds five sub-folders:
| Folder | Role |
|---|---|
kernel/cache | the kernel's internal record-level cache (LRU + eviction policy) — plaintext, per-collection, inside the trust boundary, not pluggable. Not to be confused with a to-* store: to-memory is a ciphertext persistence backend (a storage destination that happens to be RAM); kernel/cache is a read-acceleration tier. They coexist because they answer different questions — where encrypted data lives vs how fast decrypted reads come back. |
kernel/query | the query engine: the builder, the join engine (indexed nested-loop / hash strategies), live-query subscriptions, and predicate matching that back where / orderBy / limit / joins / .live(). |
kernel/via | the field-feature spine: the phased via() pipeline (compose, wiring, dispatch, reconcile) that runs every field feature — money, i18n, lookup, computed, classified, blob — plus the per-vault dependency graph and taint-binding that fold a derived field's security posture from its sources. The feature families themselves live in the top-level via/ folder; kernel/via is the machinery that runs them. See via. |
kernel/util | small stateless helpers shared across the spine — discriminant typing and filename sanitization. |
capsule/enclave-aes | the crypto interior — self-contained, frozen-interface, swappable. See Enclave →. |
The core areas (C1–C6)
The kernel is what noy-db is, not what it does. Six areas are always loaded, totalling roughly 6,500 LOC out of the hub's ~28,000:
| # | Core area | What it covers |
|---|---|---|
| C1 | Vault & Collection model | Noydb, Vault, Collection<T>, lifecycle, openVault, listVaults |
| C2 | Encryption | AES-256-GCM, PBKDF2-SHA256 (600K), AES-KW, KEK→DEK, envelope format — lives in capsule/enclave-aes |
| C3 | Store contract | The 6-method NoydbStore interface (get/put/delete/list/loadAll/saveAll) — the contract door is port/to, see Ports |
| C4 | Keyring & Permissions | Owner-role keyring, DEK wrapping, single-user permission check (multi-user grant/revoke/rotate lives in the team service, gated behind withTeam()) |
| C5 | Schema & Refs | Typed records, foreign-key references, ref-mode dispatch (strict / warn / cascade) |
| C6 | Query basics | where / orderBy / limit / offset / toArray / first / count / scan — implemented in kernel/query |
Next
Enclave → — capsule/enclave-aes, the one swappable core.