The registry

The registry is the system's typed, access-controlled, watchable configuration store — the one place subsystems read their settings from. It looks like three familiar things and is none of them. This page is the map: what the registry is, the few ideas that make it unlike the config systems you already know, and where the rest of the topic goes.

The registry's data model is deliberately small — a tree of keys, each holding named typed values, and nothing else. This page covers that two-level structure, the value type set, the rules for names and case, and the one property everything later depends on: the registry stores a value's type but never interprets its data.

The registry stores values it does not understand. What a value means — its default, its valid range, what reads it — lives outside the registry, in the subsystem that owns it and in regman, the registry's manual. That separation has a consequence worth internalising: the value the registry shows and the value a subsystem is actually using can legitimately differ.

This is the idea the registry is named for, and the one most worth getting right. The trap is picturing layers as a clean stack where the top one wins. In Peios most layers share the same precedence and resolve by recency — per value — so the reality is interwoven, not stacked. This page builds the correct model from the ground up.

Layering earns its complexity by making configuration removable. Because every write carries a layer tag and nothing is overwritten in place, deleting a layer makes its writes vanish and the next-best write resurface automatically — so installing and removing a bundle of configuration is just adding and deleting a layer. This page covers the base layer, tombstones, automatic revert, and the roles and Group Policy built on them.

Deleting in a layered registry is subtler than it looks. Removing a key withdraws one layer's claim to a name, not the key itself — if another layer still names it, it stays. There is no recursive delete, and a key deleted out from under an open handle keeps working until that handle closes.

Every registry key is a secured object, governed by the same KACS access check as files, processes, and tokens — checked once at open, cached on the handle. This page covers the registry-specific rights, the surprises (no traversal check; access is per key, not per value), and the sharp interaction with layers: a security change is not reverted when a layer is removed.

The registry is not passive storage you poll — a process can arm a persistent watch on a key or its subtree and be notified when the effective state changes. This page covers the watch model, what watchers see (effective-state changes, with the layering invisible), and the best-effort delivery that means a watcher must be ready to re-read.

The registry is the configuration store for the whole system — so what configures the registry? It mostly configures itself, which means breaking a circular dependency. It does so by running on compiled-in defaults from the instant the kernel loads, then hot-swapping to registry-backed configuration once its store is available. It never waits for configuration to exist.

The registry can export an entire subtree to a stream and restore one back, wholesale. It is how the system is seeded at first boot, recovered after disaster, and migrated between machines. Restore is a replace, not a merge — and the privilege to perform it is, in effect, the power to rewrite security on everything it touches.

For the whole topic the registry has been one thing. Underneath it is two — a kernel subsystem that is the sole authority, and one or more userspace stores that only persist data. This page names them (LCS and its sources, loregd first among them), draws the line between them, and states the trust boundary honestly: a source is trusted, and a compromised one can lie.

The registry stores a value's type but not its meaning, so the meaning is written down beside the registry — in regman, the manual. regman tells you what a key or value is: its type, default, valid range, when a change takes effect, and what it does. Crucially, it documents what a setting should be, never what it is currently set to.

Private hives and private layers give a single caller its own view of the registry — a sandbox or container can see different keys and different values from everyone else, without a separate path namespace. This is an advanced, forward-looking feature: the registry defines the resolution behaviour, while the credential model it depends on is part of KACS and not yet fully specified.

When several registry writes must take effect together or not at all, a transaction groups them into one atomic commit. It is a developer-facing tool — it is how a role installs without ever being half-applied. This page covers what transactions guarantee, their limits, and how they interact with the layered model.

A registry key can be a symbolic link to another key — open it and you land on the target. This is the single place the registry interprets a value rather than treating it as opaque bytes. This page covers how links work, how layers can redirect them, and why creating one is privileged.