LCS

The registry data model has six entities: hives, keys, path entries, values, layers, and sources. This section defines each entity, its fields, its constraints, and its relationships to other entities.

§2.1.1 Semantic core

Six rules define the entire registry model. Every section that follows is a consequence of these rules. If a design decision conflicts with one of them, the decision is wrong.

1. Names are layered. A key's presence at a path is per-layer. Different layers can name different keys at the same path. Layer resolution determines which is visible. Removing a layer removes its names.

2. Values are layered. Every value write is tagged with a layer. The effective value is the highest-precedence entry. Removing a layer removes its entries and the next layer's values surface. Tombstones can actively mask lower layers.

3. Key identity is not layered. A key's GUID, Security Descriptor, volatile flag, symlink flag, and last write time belong to the key itself, not to any layer. These properties are direct mutations on the object. They are never automatically reverted.

4. Security is key-bound, not layer-bound. SD modifications are permanent changes to the key object. Removing a layer does NOT revert SD changes that were made while the layer existed. Security policy is operational state, not configuration overlay.

5. Handles are capabilities granted at open. An open key fd carries a granted access mask computed once at open time via AccessCheck. Subsequent operations check the mask, not the SD. SD changes do not affect existing handles. Handle lifetime is independent of path lifetime.

6. Sources persist, the kernel decides meaning. Sources are storage backends. They store path entries, key records, and value entries. They return all layer data on request. They do not evaluate access, resolve layers, dispatch watches, or interpret paths. LCS does all of that.

§2.1.2 Property matrix

§2.1.3 Invariants

The following invariants hold at all times. Violations are implementation bugs.

1. Two-level hierarchy. The registry is keys and values. Keys are containers. Values are named, typed data within keys. This is a hard constraint from registry.pol compatibility.

2. Security at key level. Values inherit their key's access control. There is no per-value SD.

3. Single authority. LCS is the sole registry authority. All access control, path resolution, watch delivery, and layer resolution happens in the kernel. Sources are storage backends.

4. Identity capture at syscall boundary. The kernel captures the calling thread's token (including impersonation tokens) at the syscall boundary. Sources never see caller identity.

5. Fd-based access. Every open key is an fd. Access is checked once at open time and cached on the fd.

6. Hive isolation. Each hive is backed by exactly one source. A source may back multiple hives. Transactions are hive-scoped.

7. Volatile parent, volatile children. Children of volatile keys MUST be volatile. A non-volatile key MUST NOT be created under a volatile parent.

8. Symlinks are privileged. Symlink creation requires KEY_CREATE_LINK on the parent and SeTcbPrivilege or Administrator group membership.

9. Case-preserving, case-insensitive. All path and value name comparisons are case-insensitive. Stored names preserve original case. Non-negotiable for registry.pol compatibility.

10. Global sequence counter. LCS maintains a single monotonic sequence counter across all sources. Every mutation (path entry creation, value write, key hiding) is assigned a sequence number from this counter. The counter provides deterministic tiebreaking within a precedence tier.

A hive is a top-level namespace -- the first path component in every registry path. LCS maintains a routing table mapping hive names to registered sources.

§2.2.1 Fields

§2.2.2 Constraints

• A hive route identity is the tuple (case-folded hive name, scope), where scope is either the global hive namespace or one private scope GUID. A hive route identity MUST be unique across all registered sources. A source attempting to register a route identity already claimed by another source MUST be rejected. The same hive name MAY appear in different scopes; this is how private hives shadow global hives without colliding with them.

• A hive is backed by exactly one source. A source MAY back multiple hives.

• CurrentUser is not a hive. It is a kernel-level alias. When a path begins with CurrentUser\, LCS extracts the calling thread's user SID from their token and rewrites the path to Users\<SID>\<remainder> before routing. This rewriting applies only to the initial caller-supplied path. Symlink targets encountered during path resolution are NOT subject to CurrentUser rewriting -- they are followed literally. This prevents a confused deputy attack where a symlink containing CurrentUser\ redirects a privileged service into the service's own user hive. Symlink targets ARE subject to normal hive routing including private hive routing — if the resolving thread has a private hive that shadows the target's hive, the symlink resolves into the private hive. This is intentional: a sandboxed process should see a consistent view of the registry through symlinks.

• Hive names follow the same naming rules as key name components: no backslash, no forward slash, no null. Case-preserving, case-insensitive.

• The name "CurrentUser" (case-insensitive) MUST NOT be registered as a hive name. LCS MUST reject registration attempts with this name (EINVAL). CurrentUser is reserved as a kernel-level alias and must never collide with a real hive.

§2.2.3 Routing

When a registry syscall provides a path, LCS extracts the first component (everything before the first backslash) and looks it up in the routing table. If the hive is registered and active, the request is routed to the backing source. If the hive is not registered, the syscall fails with ENOENT. If the hive is registered but the source is unavailable, the syscall fails with EIO.

The routing table is updated when sources register or disconnect. There is no static configuration -- hive routing is entirely dynamic, driven by source registration.

§2.2.4 Private hives

A private hive is a hive registered with the RSI_HIVE_PRIVATE flag and a scope GUID. Private hives are not globally visible -- they are only accessible to threads whose credentials carry the matching scope GUID.

§2.2.4.1 Routing with private hives

When routing a path, LCS checks private hives before global hives. For each scope GUID in the calling thread's credentials (in order), LCS checks whether a private hive with the path's hive name and that scope GUID exists. If found, that hive is used. If no private hive matches, the global routing table is checked.

Private hives can shadow global hives. A thread with a private "Machine" hive sees the private version, not the global one. This enables complete registry isolation for sandboxing and containers. The maximum number of scope GUIDs per token is bounded by MaxScopeGUIDsPerToken (default 8).

§2.2.4.2 Credential attachment

A thread's credentials MAY carry an ordered set of scope GUIDs. The mechanism for attaching scope GUIDs to credentials depends on KACS token extensions not yet specified. LCS defines the routing behaviour; KACS defines the credential model.

Security constraint on KACS. When KACS implements scope GUID attachment, it MUST verify that the attaching principal is authorised to join the scope. The specific authorization mechanism (privilege check, scope creator approval, etc.) is a KACS design decision. Without this constraint, any process could claim membership in any scope, defeating private hive isolation.

§2.2.4.3 Scope lifecycle

A scope GUID is an opaque 128-bit identifier generated using a cryptographically secure pseudorandom number generator. It has no inherent lifecycle. It exists as long as at least one private hive or credential references it. When the last private hive using a scope GUID is unregistered and no credentials carry it, the scope is implicitly gone. LCS does not track scope lifecycle -- it only checks for scope GUID matches during routing.

§2.2.5 Default hives

LCS does not hardcode any hive names. The hive namespace is determined entirely by which sources register and what names they claim. In practice, loregd registers Machine and Users at boot. Other sources MAY register additional hives at runtime.

A key is a node in the registry hierarchy. Keys are containers -- they hold subkeys (forming a tree) and values (holding data). Keys are analogous to filesystem inodes: they carry identity and properties, while path entries carry naming.

§2.3.1 Fields

No key property is layer-qualified. Properties belong to the key object itself. To change a key's structural type (volatile, symlink) through a layer, the layer hides the original key and creates a new one at the same path -- the standard overlay pattern.

§2.3.2 Key identity

A key's identity is its GUID, not its path. Two keys at different points in time at the same path are different objects with different GUIDs. A path is a name that maps to an identity. The identity persists independently of the name.

GUIDs are assigned by LCS (not by sources) and pushed to the source at key creation via the RSI. The source persists them as primary keys in its storage schema. After path-to-GUID resolution at open time, all RSI operations use the GUID directly.

LCS does not maintain a persistent retired-GUID catalogue solely to prevent future UUIDv4 collisions. A freshly generated LCS UUIDv4 GUID is fresh for this specification. If a source reports that RSI_CREATE_KEY collided with an existing key GUID, LCS MUST treat that as source/tracker inconsistency and fail closed with EIO. GUIDs dropped through orphan cleanup are not retained solely to prevent future UUIDv4 collisions.

§2.3.3 Naming rules

The following bytes/characters are forbidden in key name components:

• \ (backslash) -- path separator
• / (forward slash) -- normalised to backslash on input, therefore also a separator
• null (\0) -- string terminator

All other valid UTF-8 characters are permitted, including spaces and Unicode. The kernel normalises forward slashes to backslashes on input; the stored canonical form always uses backslashes.

Empty name components are forbidden. Paths containing consecutive separators (Machine\\System) or trailing separators (Machine\System\) are invalid.

§2.3.4 Symlinks

A symlink key uses two complementary mechanisms:

1. The symlink flag on the key record marks the key's structural type. Set at creation via REG_OPTION_CREATE_LINK. Immutable.

2. The default value with type REG_LINK provides the target path. The target is a regular layered value -- a higher-precedence layer can redirect a symlink by writing a different REG_LINK default value.

Both mechanisms are load-bearing. The flag marks identity; the value provides the target. LCS follows symlinks during path resolution, resolving the target path before completing the operation. The fd references the resolved target, not the link.

Target resolution. If the symlink flag is set but the effective default value is not type REG_LINK (e.g., a layer writes REG_SZ as the default value), path resolution fails with EINVAL. LCS does not validate the default value's type at write time -- the error occurs at resolution time. Removing the offending layer restores the original REG_LINK target.

The REG_LINK payload interpreted by LCS is a length-delimited UTF-8 absolute registry path. No trailing null byte is required or permitted. Forward slashes are normalised to backslashes before path processing. The target is validated using the same UTF-8, null-byte, component-length, total-length, empty-component, trailing-separator, and maximum-depth rules as syscall paths. Relative symlink targets are invalid.

CurrentUser\ rewriting is not applied to symlink targets. A target beginning with CurrentUser\ is followed literally and therefore routes as a hive named CurrentUser, which cannot be registered. Symlink targets are otherwise subject to normal hive routing, including private hive routing for the resolving thread.

Invalid REG_LINK encoding or invalid target path structure causes path resolution to fail with EINVAL. The invalid value remains in the registry; removing or overriding the layer that supplied it can restore a valid target.

Recursion limit. Symlink resolution is limited to a configurable depth (default 16). Exceeding the limit produces ELOOP.

Opening the link itself. The REG_OPEN_LINK flag on reg_open_key opens the symlink key rather than following it. This is required for managing the symlink (deleting it, changing its target).

Creation restriction. Symlink creation requires KEY_CREATE_LINK on the parent key and SeTcbPrivilege or Administrator group membership.

§2.3.5 Case comparison

Key name comparison uses Unicode Simple Case Folding (CaseFolding.txt, status S and C entries, Unicode 16.0) -- a fixed one-to-one codepoint mapping with no locale dependency. This provides practical compatibility with Windows' RtlCompareUnicodeString behaviour. The Unicode version is pinned at 16.0 for v0.21. Future versions MAY adopt a newer Unicode version; the upgrade is a deliberate decision, not an implicit consequence of updating a library.

Unicode normalisation (NFC vs NFD) is explicitly not performed. Two different Unicode representations of the same visual character are different keys, matching Windows semantics.

Key existence and naming are layer-qualified. The source stores path entries per-layer, separating naming (which is layered) from identity (which is not). This is analogous to an overlay filesystem: directory entries are per-layer, inodes are shared.

§2.4.1 Fields

§2.4.2 Path resolution

When LCS resolves a path component, the source returns all path entries for that (parent GUID, child name) across all layers. LCS applies layer resolution:

1. Discard entries from inactive layers. A layer is active if it is enabled globally or its name appears in the calling thread's private layer set.
2. Look up each entry's layer precedence from the cached layer table.
3. Select the entry with the highest precedence. If multiple entries share the highest precedence, select the one with the highest sequence number.
4. If the selected entry is HIDDEN, the path does not exist -- lower layers are masked.
5. If the selected entry maps to a GUID, that key is visible.

This is the same resolution algorithm used for values, applied to existence claims rather than data.

§2.4.3 Key creation

Creating a key in a layer always assigns a fresh GUID and produces two records. Fresh means an LCS-generated UUIDv4 GUID as defined in §2.3; it does not require consulting a persistent retired-GUID catalogue.

1. A path entry: (parent GUID, name, layer) → GUID with a new sequence number.
2. A key record via RSI_CREATE_KEY with the fresh GUID.

If a different layer already has a key at the same path, the new layer gets its own distinct GUID. Each layer has its own key object. Layer resolution determines which is visible.

There is no operation that creates a path entry pointing to an existing GUID. reg_create_key always assigns a new GUID. The namespace is always a tree, never a graph.

§2.4.4 No GUID sharing across layers

The path table's structure technically permits multiple entries referencing the same GUID, which would create hard-link-like semantics. This is deliberately not exposed by any API. Every key has exactly one canonical parent and name. This avoids ambiguity in parent GUID semantics, SD inheritance, subtree enumeration, and watch dispatch. If aliasing is needed, symlinks are the explicit, visible mechanism.

§2.4.5 Key hiding

A layer can create a HIDDEN entry at a path, making the key invisible regardless of lower-precedence entries. HIDDEN is the path-level equivalent of a value tombstone. When the hiding layer is removed, the lower-precedence key reappears.

The HIDDEN entry is assigned a sequence number like any other path entry. This provides deterministic behaviour when a layer at the same precedence has both a GUID entry and another layer has a HIDDEN entry -- the higher sequence number wins.

§2.4.6 Hide and replace

A single layer can both hide an existing key and create a new one at the same path. The layer creates a path entry (parent, name, layer) → new-GUID. Lower-precedence layers' path entries for the same (parent, name) are masked by the higher precedence of this layer's entry. When the layer is removed, both the new key and its masking effect disappear, and the lower-precedence key reappears.

No special mechanism is needed. This falls out of per-layer path entries and precedence resolution naturally.

§2.4.7 Layer deletion

When a layer is deleted, all its path entries are removed. Any GUID that is no longer referenced by any path entry across any layer is orphaned. Orphaned keys follow the deletion model described in §2.8.

A value is a named, typed datum stored within a key. Values hold the actual configuration data. A key can hold multiple values, each with a distinct name. One unnamed value per key is permitted (the default value, with the empty string as its name).

§2.5.1 Fields

§2.5.2 Per-layer storage

A single (key GUID, value name) pair can have multiple entries in the source -- one per layer that has written to it. The source stores all entries. LCS resolves the effective value at read time via the layer resolution algorithm. This is the mechanism that enables layer deletion to automatically revert configuration: delete the layer, its entries disappear, the next-highest-precedence entry becomes effective.

§2.5.3 Value tombstones

A layer entry can be a tombstone instead of a normal value -- a marker that means "this value does not exist in this layer, and lower-precedence layers are masked." Layer resolution treats a tombstone as "value not found" without falling through to lower layers.

Tombstones are required for registry.pol compatibility. The **Del.ValueName directive in registry.pol deletes specific values. Without tombstones, a higher-precedence layer can only override values, not express "this value must not be configured." When the tombstone's layer is removed, the lower-precedence value becomes effective again.

In the source's storage, a tombstone is a layer entry with type REG_TOMBSTONE instead of normal type + data. REG_TOMBSTONE is a Peios-internal type, never exposed to callers reading values. Callers see "value not found" (ENOENT) when a tombstone is the effective entry.

§2.5.4 Blanket tombstones

A blanket tombstone is a per-layer marker on a key that masks all values from lower-precedence layers for that key. Unlike per-value tombstones (which mask a specific value name), a blanket tombstone masks every value on the key regardless of name.

Blanket tombstones are required for registry.pol **DelVals semantics. The **DelVals directive means "delete all values in this key before applying new ones." In a layered model, this must mask all lower-precedence values -- including values whose names are not known at the time the blanket is written.

§2.5.4.1 Storage

A blanket tombstone is stored as a flag on the (key GUID, layer) relationship. It occupies no per-value-name entry.

§2.5.4.2 Resolution

When LCS resolves a value on a key, the resolution algorithm checks for blanket tombstones before evaluating per-value entries:

1. Collect all layer entries for the requested (key GUID, value name), plus any blanket tombstones on this key.
2. A blanket tombstone is treated as a tombstone candidate for every value name, competing at its (precedence, sequence) tuple. The candidate with the highest precedence wins; within the same precedence, the highest sequence number wins.
3. If the winning candidate is a blanket tombstone and no per-value entry has a higher (precedence, sequence) tuple, the value is masked. A per-value entry that wins the tiebreak overrides the blanket.

A layer can write a blanket tombstone and also write specific values in the same layer. The specific values are visible; all other values from lower-precedence layers are masked. This is exactly **DelVals followed by new value writes.

§2.5.4.3 Enumeration

When enumerating values on a key with a blanket tombstone, LCS returns only values from the blanket's layer or higher-precedence layers. Lower-precedence values are invisible.

§2.5.4.4 Layer deletion

Removing a layer that holds a blanket tombstone removes the blanket. All previously masked lower-precedence values become visible again.

§2.5.5 Value types

LCS supports the full Windows registry value type set for registry.pol compatibility:

LCS treats values as opaque typed blobs. It stores the type tag and returns it on read, but does not validate or interpret the data payload except for REG_LINK on symlink keys. REG_LINK interpretation is defined in §2.3.

REG_RESOURCE_LIST, REG_FULL_RESOURCE_DESCRIPTOR, and REG_RESOURCE_REQUIREMENTS_LIST (types 8-10) describe hardware resource assignments in the Windows HKLM\HARDWARE hive, which the Windows kernel rebuilds at every boot. Peios has no equivalent -- hardware enumeration is owned by the Linux device model (sysfs, /proc/iomem), not the registry. LCS accepts these type tags solely so that values round-trip without loss; it assigns them no semantics, never interprets them, and never produces them itself. For every LCS operation they behave identically to REG_BINARY. They are included because a registry.pol file or a Windows hive import can carry an arbitrary type tag, and rejecting a faithfully-copied value would break the format fidelity guarantee in §1.4.

LCS validates value type tags at write boundaries. User-visible value writes MUST use one of the value types listed above. Unknown type codes are invalid and fail with EINVAL before sequence allocation, transaction enlistment, or source dispatch.

The following type is internal to LCS and MUST NOT be exposed to userspace callers:

REG_TOMBSTONE is accepted only as the explicit per-value tombstone write operation on REG_IOC_SET_VALUE. A tombstone write MUST have zero-length data. Non-empty tombstone data fails with EINVAL before sequence allocation, transaction enlistment, or source dispatch.

§2.5.6 Naming rules

Value names follow the same case comparison rules as key names (Unicode Simple Case Folding, case-preserving, case-insensitive).

Value names differ from key names in one respect: backslash and forward slash ARE permitted in value names. Value names are not hierarchical, so separators have no special meaning.

Only null (\0) is forbidden. Invalid UTF-8 is rejected. Empty string is reserved for the default value.

§2.5.7 Maximum value size

The maximum data size for a single value is configurable via the self-configuration mechanism (default 1 MB). See §11.4 for the full parameter table. Value data is an opaque byte array and is not subject to UTF-8 string validation unless a specific value type is explicitly interpreted by LCS.

A layer is a named collection of registry writes that can be managed as a unit. Layers have precedence: higher-precedence layers override lower ones. Layers are the mechanism for role management, Group Policy, and configuration revert.

§2.6.1 Fields

§2.6.2 The base layer

The base layer (named "base") is a kernel-reserved implicit layer. It exists unconditionally -- LCS hardcodes its existence even if no persisted layer metadata has been loaded yet.

The base layer:

• MUST NOT be deleted.
• MUST NOT be disabled.
• MUST NOT have its precedence changed.
• Has precedence 0.

Persisted metadata in Machine\System\Registry\Layers\base\ MAY describe the base layer but MUST NOT contradict its existence or properties. LCS MUST ignore self-watch SUBKEY_DELETED events for the base layer -- if a higher-precedence HIDDEN entry masks the base layer's metadata key, LCS MUST NOT process this as a layer deletion. The base layer's existence is hardcoded and cannot be overridden by layer mechanics.

When a write does not specify a layer, it targets the base layer. This is the default for all manual admin operations and system initialisation.

Role layers also have precedence 0. Within the same precedence tier, the most recent write wins (highest sequence number). Group Policy layers have precedence > 0 and override both base and role layers.

§2.6.3 Layer metadata storage

Layer metadata is stored in the registry itself, under Machine\System\Registry\Layers\<LayerName>\. Each layer's metadata is a set of values under its key:

• Precedence (REG_DWORD)
• Enabled (REG_DWORD, 0 or 1)
• Owner (REG_BINARY, SID)

LCS watches this subtree and maintains an in-memory cache of the layer table.

Registry backup LAYER records are not authoritative layer metadata. They are stream manifest records used to validate layer-tagged backup entries and enforce restore-time privilege checks. A backup restores layer metadata only when the backup includes the Machine\System\Registry\Layers\<LayerName>\ metadata subtree as ordinary registry KEY, VALUE, and SD records.

Layer identity is the case-folded UTF-8 layer name. The original spelling is preserved for display and for the metadata key name, but lookups, collision checks, RSI layer-name comparisons, and layer table membership checks use the folded identity. Creating RoleA and rolea therefore refers to the same layer and must be treated as a duplicate rather than two distinct layers.

§2.6.3.1 Circularity

Layer metadata lives in the registry, which is itself layered. This is intentionally circular but safe. LCS resolves the circularity as follows:

• LCS always uses its currently cached layer table when resolving values -- including when resolving layer metadata values.
• When a write to the layer metadata subtree commits, the watch fires and LCS re-reads the affected layer metadata using the current cache.
• LCS updates the cache with the new values.

There is no recursion risk. LCS reads, caches, and uses the cached table for all subsequent resolution until the next watch event. The layer table is never re-resolved mid-operation.

A high-precedence layer (e.g., Group Policy) can override another layer's precedence -- this is useful and intentional. The cached layer table picks up the change on the next watch event.

Modifying layer metadata requires SeTcbPrivilege, which limits the circularity surface to highly privileged callers.

§2.6.4 Layer metadata is global

LCS maintains one authoritative layer table. When additional sources register, LCS provides them with the current layer list. Each source stores layer entries (path entries and value writes tagged with layer names) for its own hives. Layer metadata (precedence, enabled state, owner) is global and lives in one place.

§2.6.5 Access control

§2.6.5.1 Layer lifecycle

SeTcbPrivilege is required specifically for operations that establish or elevate a layer's precedence above 0. This is a defense-in-depth measure: compromise of the Layers\ key SD alone cannot create high-precedence layers without also holding SeTcbPrivilege.

Enforcement. LCS maintains a set of layer metadata key GUIDs and a cached SD for each layer metadata key. The layer table entry, metadata key GUID, and cached SD are published together. A layer is not visible in the in-memory layer table unless its metadata key GUID and authorization SD are also available.

Layer metadata key creation is ordinary registry key creation: LCS computes the key's initial SD from parent inheritance via KACS before asking the source to persist the key. On the normal creation path, the metadata key therefore already has an SD before the layer can be published.

Changes under Machine\System\Registry\Layers\ mark the affected layer names dirty. After the mutating operation commits, but before the syscall returns to userspace, LCS runs a bounded layer metadata refresh for the affected names. For a transaction, this refresh runs once after the source commit succeeds and before REG_IOC_COMMIT returns. The refresh reads the committed metadata key, layer values, and SD, then atomically publishes the new table entry plus cached SD.

The internal self-watch mechanism detects the affected subtree changes, but the watch callback is not the atomicity boundary. It must not publish a partially populated layer entry. LCS must not perform source round trips while holding watch-map locks or layer-table publication locks.

If Precedence is missing, LCS uses 0. If Enabled is missing, LCS uses true. If Owner is missing for a newly created layer, LCS uses the creator SID from the creating effective token. Owner is informational and is not used for access checks.

If a later refresh sees a missing Owner value, LCS retains the previous known-good owner if one exists. If none exists, LCS may use the metadata key SD owner SID as an informational fallback. This does not grant access.

If the metadata key SD cannot be read or parsed during refresh, the source has returned malformed data. LCS emits an audit event, does not publish or update the affected layer entry, and retains any previous known-good entry. If the refresh is required for the operation being completed (for example creating or exposing a layer), the syscall fails with EIO.

SeTcbPrivilege for precedence > 0 is enforced inline at REG_IOC_SET_VALUE time:

1. On every REG_IOC_SET_VALUE, LCS checks whether the target key GUID is in the layer metadata key set.
2. If yes, and the value name matches "Precedence" (case-insensitive, using the same Unicode Simple Case Folding as all other value name comparisons), and the data represents a value > 0, LCS checks the caller's token for SeTcbPrivilege.
3. If SeTcbPrivilege is not held, the ioctl returns EPERM without contacting the source.

This is a synchronous check at ioctl time — no deferred validation, no privilege state recording. The caller's token is available at the syscall boundary.

All other layer operations (writes into a layer, deletion, metadata modification within the same precedence tier) are controlled exclusively by the SD on the layer's metadata key.

§2.6.5.2 Layer lifecycle mechanism

Layers are created and deleted by writing to and deleting keys under Machine\System\Registry\Layers\. There is no dedicated "create layer" or "delete layer" syscall. LCS watches this subtree via the self-watch mechanism:

• Creation: A key is created at Machine\System\Registry\Layers\<name>\ with Precedence, Enabled, and Owner values. Layer creation SHOULD be performed within a transaction so all metadata values are present when the self-watch fires at commit time. If LCS reads the metadata key and finds missing values, it uses defaults: Precedence=0, Enabled=true. LCS adds the layer to the in-memory table.

• Deletion: The key at Machine\System\Registry\Layers\<name>\ is deleted. The self-watch fires a SUBKEY_DELETED event. LCS removes the layer from the in-memory table and sends RSI_DELETE_LAYER to all registered sources. Sources purge all entries tagged with that layer name. LCS determines which keys and values changed effective state and dispatches watch events.

Access control on layer lifecycle operations is enforced by the SDs on the layer metadata keys. Deleting a layer metadata key requires DELETE right on that key's fd.

§2.6.5.3 Writing into a layer

Every mutating operation that targets a layer (value writes, deletions, tombstones, key hides, blanket tombstones) requires layer write authorization: the caller's token MUST have KEY_SET_VALUE on the layer's metadata key at Machine\System\Registry\Layers\<layer_name>\.

This check is in addition to the fd's granted access mask on the target key. Both checks MUST pass.

LCS caches layer metadata SDs alongside the layer table. The cache is invalidated via the self-watch mechanism on the Machine\System\Registry\Layers\ subtree.

The layer metadata key's SD determines who can write into that layer. By default, the base layer's metadata key inherits from the Machine hive root (SYSTEM and Administrators: KEY_ALL_ACCESS). GP layers receive restrictive SDs set by the GP client at creation. Role layers receive SDs set by the role installer.

This prevents both vertical escalation (unprivileged process writing to a GP layer) and lateral movement (one role's service writing into another role's layer).

§2.6.6 Layer count cap

The total number of distinct layers in the in-memory layer table is bounded by MaxTotalLayers (default 1024). Creating a layer when the table is full returns ENOSPC. This prevents unbounded kernel memory consumption from layer creation.

§2.6.7 Per-value layer cap

A maximum number of layers MAY write to the same (key GUID, value name) pair. The default cap is 128. This is a per-value cap, not a global layer count limit. It prevents amplification attacks where every read must resolve an excessive number of entries.

Enforcement. The cap is checked by LCS at REG_IOC_SET_VALUE time, before contacting the source. LCS queries the source for the current entry count at (key GUID, value name) across all layers. If adding a new layer entry would exceed MaxLayersPerValue, the write is rejected with ENOSPC. This check is not performed for writes that replace an existing entry in the same layer (which do not increase the layer count).

This cap is best-effort admission control, not a strict storage invariant. Concurrent writers can race: multiple operations may observe room below the cap and then create new layer entries before the source state reflects the other writes. LCS does not require sources to enforce this cap atomically in v0.21. Once LCS observes the distinct layer count at or above MaxLayersPerValue, new writes that would add another layer entry are rejected with ENOSPC.

MaxLayersPerValue is a performance and memory-amplification guard, not an access-control boundary. Future versions may add source-side atomic enforcement if strict caps are required.

The cap is configurable via the self-configuration mechanism. See §11.4 for the full parameter table.

§2.6.8 Private layers

A private layer is a disabled layer attached to a specific thread's credentials. Private layers are globally invisible during normal resolution but included when resolving on behalf of a thread whose credentials carry the layer.

Private layers enable:

• Per-session configuration overrides. A user opens an application with experimental settings without affecting other sessions.
• Testing. Inject test configuration without modifying the shared registry.
• Sandboxing. A container sees a different view of the registry without a separate hive.

§2.6.8.1 Credential attachment

A thread's credentials MAY carry a set of private layer names. When LCS resolves a value or path entry for that thread, disabled layers whose names appear in the thread's credential set are treated as enabled for the duration of that resolution.

The mechanism for attaching private layers to credentials depends on KACS token extensions not yet specified. LCS defines the resolution behaviour; KACS defines the credential model.

Security constraint on KACS. When KACS implements credential attachment for private layers, it MUST verify at attachment time that the attaching token holds sufficient privilege for the named layer's precedence. Specifically: attaching a layer with precedence

0 MUST require SeTcbPrivilege. Without this constraint, an unprivileged process could attach an existing high-precedence disabled layer to its own credentials, gaining the ability to see (and potentially influence) GP-level configuration.

§2.6.8.2 Resolution interaction

Private layers participate in the normal precedence ordering. A disabled layer with precedence 5 attached to a thread's credentials is resolved at precedence 5, competing with other enabled layers at the same or different precedence levels.

§2.6.8.3 Scope

Private layers are per-thread, not per-process. Different threads in the same process MAY have different private layer sets via different impersonation tokens. The maximum number of private layers per token is bounded by MaxPrivateLayersPerToken (default 16). Exceeding this limit at credential attachment time is an error.

Layer resolution is the algorithm LCS uses to determine the effective state of a path entry or value from multiple per-layer entries. It is the core mechanism that makes the registry layered.

§2.7.1 Sequence counter

LCS maintains a single global monotonic sequence counter. Every mutation that creates a layer-qualified entry (path entry creation, value write, key hiding, blanket tombstone) is assigned the next sequence number from this counter. The counter is never decremented or reset.

The counter is represented internally as next_sequence: the next sequence number LCS will allocate. Allocating a sequence number increments next_sequence. Allocated sequence numbers are never reused, even if the operation later fails, times out, or is aborted as part of a transaction.

Transactional mutating operations are assigned sequence numbers when the operation is accepted into the transaction, not at commit time. This preserves the transaction's operation order for deterministic layer tiebreaking and watch dispatch if the transaction commits. If the transaction aborts, the allocated sequence numbers remain unused gaps.

On startup, each source reports its highest persisted sequence number in the registration handshake. LCS initialises the counter to max(all reported values) + 1. This ensures new writes always have higher sequence numbers than any persisted entry, even after a restart.

When a source registers after next_sequence has already been initialised, LCS advances next_sequence to max(next_sequence, source_max_sequence + 1). If adding one would overflow uint64, registration fails with EOVERFLOW and the source is not made active.

LCS rejects any source-returned layer-qualified entry whose sequence number is greater than or equal to next_sequence. Such an entry is malformed source data: sources store sequence numbers assigned by LCS and cannot legitimately contain future sequence numbers.

Within a single resolution candidate set, duplicate sequence numbers at the same precedence are malformed if they would otherwise be compared to select a winner. LCS rejects the response as malformed source data rather than making an arbitrary choice. Duplicate sequence numbers in unrelated candidate sets are not compared and do not by themselves affect resolution.

The sequence counter provides deterministic tiebreaking within a precedence tier. Wall-clock time is tracked separately via the key's last write time for human-facing metadata.

Sequence numbers are not hive generation numbers. A sequence number orders layer-qualified entries for resolution and is persisted by sources. The hive generation number exposed by REG_IOC_QUERY_KEY_INFO is a volatile LCS-owned per-hive change epoch used for cache and watch overflow recovery. Sources do not persist hive generation numbers.

Registry restore does not persist backup sequence numbers directly. Restore reserves a fresh global sequence range and remaps backup sequence numbers into that range so restored entries are newer than pre-restore state while preserving the backup's internal relative ordering. See §9.1.

§2.7.2 Pseudocode conventions

The resolution algorithms use tuples (precedence, sequence, item) as candidates. Selection uses max() ordered by precedence first, then sequence. Tuple fields are accessed by index: [0] = precedence, [1] = sequence, [2] = item (the entry or a TOMBSTONE sentinel).

A layer is active for a given thread if it is enabled globally or its name appears in the thread's private layer set.

is_active(layer, thread_credentials):
    return layer.enabled or layer.name in thread_credentials.private_layers

§2.7.3 Value resolution

Given a (key GUID, value name) pair, resolve the effective value:

resolve_value(key_guid, value_name, thread_credentials):
    // Step 1: Collect entries and blanket tombstones
    entries = source.query_values(key_guid, value_name)
    blankets = source.query_blanket_tombstones(key_guid)

    // Step 2: Build candidate list from per-value entries
    candidates = []
    for entry in entries:
        layer = layer_table.get(entry.layer)
        if layer is None:
            continue  // unknown layer, discard
        if not is_active(layer, thread_credentials):
            continue
        candidates.append((layer.precedence, entry.sequence, entry))

    // Step 3: Add blanket tombstones as candidates
    // A blanket tombstone acts as a tombstone for every value name
    // at its precedence/sequence.
    for bt in blankets:
        layer = layer_table.get(bt.layer)
        if layer is None:
            continue
        if not is_active(layer, thread_credentials):
            continue
        candidates.append((layer.precedence, bt.sequence, TOMBSTONE))

    // Step 4: Select winner
    if len(candidates) == 0:
        return NOT_FOUND

    // Highest precedence wins. Within same precedence, highest
    // sequence number wins.
    winner = max(candidates, key=lambda c: (c[0], c[1]))

    // Step 5: Evaluate winner
    if winner[2] is TOMBSTONE:
        return NOT_FOUND
    if winner[2].type == REG_TOMBSTONE:
        return NOT_FOUND
    return (winner[2].type, winner[2].data)

§2.7.4 Path entry resolution

Given a (parent GUID, child name) pair, resolve key visibility:

resolve_path(parent_guid, child_name, thread_credentials):
    entries = source.lookup(parent_guid, child_name)

    candidates = []
    for entry in entries:
        layer = layer_table.get(entry.layer)
        if layer is None:
            continue
        if not is_active(layer, thread_credentials):
            continue
        candidates.append((layer.precedence, entry.sequence, entry))

    if len(candidates) == 0:
        return NOT_FOUND

    winner = max(candidates, key=lambda c: (c[0], c[1]))

    if winner[2].target == HIDDEN:
        return NOT_FOUND  // hidden, lower layers masked
    return winner[2].target  // GUID of the visible key

§2.7.5 Value enumeration

Enumerate all effective values for a key:

enumerate_values(key_guid, thread_credentials):
    all_entries = source.query_all_values(key_guid)

    // Collect unique value names across all layers
    names = unique(entry.name for entry in all_entries)

    results = []
    for name in names:
        result = resolve_value(key_guid, name, thread_credentials)
        if result != NOT_FOUND:
            results.append((name, result[0], result[1]))

    return results

Callers see only effective values. Tombstoned values and values masked by blanket tombstones are omitted. The caller never sees per-layer raw data through normal operations.

§2.7.6 Unknown layer entries

Source entries tagged with a well-formed layer name that is not present in the current layer table are valid latent entries. LCS ignores them during resolution while the layer is absent. If a layer with the same folded layer identity is later created, those entries become eligible for normal resolution using the new layer metadata.

This supports restore, import, and boot ordering where source storage may contain entries before their metadata has been loaded. It also follows the core rule that sources persist entries while LCS decides their meaning.

Normal LCS mutating operations do not create entries for missing layers: layer-targeting ioctls still return ENOENT when the target layer is absent from the layer table. Latent unknown-layer entries therefore arise from existing source storage, restore/import ordering, previous boots, or source behaviour. Since sources are trusted components, well-formed latent entries are not malformed solely because their layer is currently absent.

Entries with malformed layer names remain malformed source data and are rejected according to the source validation rules.

§2.7.7 Subkey enumeration

Enumerate all visible child keys:

enumerate_subkeys(parent_guid, thread_credentials):
    all_children = source.enum_children(parent_guid)

    // Collect unique child names across all layers
    names = unique(entry.child_name for entry in all_children)

    results = []
    for name in names:
        guid = resolve_path(parent_guid, name, thread_credentials)
        if guid != NOT_FOUND:
            key_meta = source.read_key(guid)
            results.append((name, key_meta))

    return results

A subkey is visible if its effective path entry (after layer resolution) maps to a GUID, not HIDDEN.

Key deletion operates on two levels: path entries (per-layer naming) and key data (identity and properties).

§2.8.1 Explicit deletion

When a process deletes a key via syscall, LCS removes the path entry for the specified layer. The key's data (GUID, SD, values) is not affected -- only the naming is removed.

Hive root keys cannot be explicitly deleted or hidden. A hive root has no parent GUID or child name, so there is no path-entry tuple to remove or mask with RSI_DELETE_ENTRY or RSI_HIDE_ENTRY. LCS MUST reject delete and hide operations on hive root fds with EINVAL before source dispatch, transaction enlistment, sequence allocation, or watch generation.

If the key still has path entries in other layers, those remain. The key is still visible through those layers.

If no path entries remain across any layer after the deletion, the key is orphaned.

§2.8.2 Layer deletion

When a layer is deleted, all its path entries and value entries are removed across all sources. LCS broadcasts the deletion to all registered sources.

Any GUIDs that lose their last path entry (across all layers) are orphaned. Values that were the highest-precedence entry for their name are removed, and the next-highest-precedence entry becomes effective. Blanket tombstones held by the deleted layer are removed, unmasking lower-precedence values.

Layer deletion is the mechanism for role uninstallation and Group Policy removal.

Interaction with transactions. Before sending RSI_DELETE_LAYER, LCS MUST abort all bound transactions that have written to the layer being deleted. This prevents stale writes from being committed into a deleted layer after RSI_DELETE_LAYER completes. Affected transactions receive EINVAL on their next operation or commit attempt.

§2.8.3 Orphaned keys

An orphaned key is a GUID with no path entries in any layer. It follows the Linux unlink model:

• Existing fds to the orphaned key continue to work. Reads, writes, and enumeration operate normally against the key's GUID.
• The key is alive but unnamed -- no new opens can reach it by path.
• When the last fd closes, LCS tells the source to drop the GUID via RSI_DROP_KEY.

Existing fds to an orphaned key may perform GUID-local operations:

• query, set, and delete values
• set or remove blanket tombstones
• query and set the key Security Descriptor
• query key metadata
• flush the key's hive
• close the fd

Namespace operations are rejected once the fd's key is orphaned:

• creating a child key under the orphaned key returns ENOENT
• relative open or create through the orphaned key returns ENOENT
• deleting the orphaned key's path entry returns ENOENT
• hiding the orphaned key returns ENOENT
• backup of the orphaned key returns ENOENT

An orphaned key is no longer a reachable subtree root. Allowing new path entries beneath an unnamed key would create unreachable subgraphs, so namespace mutation is not permitted.

Existing watches on a key remain armed when the key becomes orphaned. The transition to orphaned state delivers KEY_DELETED. After that, the watch may observe GUID-local changes made through existing fds until the fd closes, but subtree expansion through the orphaned key is not performed. Arming a new watch on an already orphaned key returns ENOENT.

RSI_DROP_KEY removes all data associated with the GUID: the key record, all value entries across all layers, and any remaining path entries that might reference it.

If the last fd to an orphaned key closes while the backing source is Active, LCS sends RSI_DROP_KEY before releasing its in-kernel key state. If the source is Down, LCS releases its in-kernel key state and does not queue a deferred drop. The source's required startup and re-registration orphan cleanup is responsible for purging key records that have no path entries before the source becomes Active.

close() does not report orphan cleanup failure to userspace. If a source cannot complete orphan cleanup, registration fails or the source remains unavailable.

§2.8.4 RSI deletion operations

The deletion model maps to three RSI operations:

• RSI_DELETE_ENTRY(parent_GUID, child_name, layer): Remove a specific layer's path entry. The key's data remains, keyed by GUID. Used for explicit key deletion.

• RSI_DROP_KEY(GUID): Remove all data associated with the GUID. Called by LCS when an orphaned key's last fd closes.

• RSI_DELETE_LAYER(layer_name): Remove all path entries, value entries, and blanket tombstones tagged with the specified layer from the source's storage. Returns the set of orphaned GUIDs. Called by LCS when a layer's metadata key is deleted (see §2.6).

The source does not know about fds. It sees two database operations: remove a path table row, remove all data rows for a GUID.

§2.8.5 Crash recovery

Sources MUST clean up orphaned GUIDs on startup. An orphaned GUID is a key record with no corresponding path entries in any layer. These arise from keys that were orphaned but not yet dropped before the previous shutdown.

On startup or re-registration, a source queries its storage for GUIDs that exist in the key table but have no path entries. It purges them. This is standard referential integrity cleanup and MUST be performed before completing registration with LCS.

§2.8.6 New key at same path

A layer can create a new key at a path where another layer's key already exists. Each layer has its own path entry pointing to its own GUID. Layer resolution determines which is visible.

Existing fds referencing a different GUID at the same path are completely isolated -- different GUIDs, different data, different value entries.

§2.8.7 Constraints

• A key with visible children MUST NOT be deleted. Visibility is evaluated globally (all enabled layers), not relative to the caller's private layer set. This ensures deletion semantics are deterministic regardless of caller credentials. The syscall returns ENOTEMPTY. Recursive deletion is a client-side tree walk, not a kernel primitive.

• Deleting a key does NOT delete its values. Values are associated with the GUID, not the path entry. They are removed when the GUID is dropped (last fd closes on an orphaned key).

The registry's security model is a direct application of KACS. LCS does not define its own access control mechanism -- it uses the same AccessCheck, SDs, tokens, and SIDs that every other Peios subsystem uses. This section describes how KACS primitives integrate with registry operations.

§3.1.1 Access control flow

Every registry operation that opens a key follows the same path:

1. Token capture. The userspace thread makes a registry syscall. LCS captures the thread's effective token -- the impersonation token if one is set, otherwise the primary token. This is the same token capture KACS uses for all syscalls.

2. Path resolution. LCS walks the registry path via RSI Lookup operations, resolving through the layer stack. Symlinks are followed. No access checking occurs during the walk -- intermediate keys are not checked. Only the final key matters.

3. AccessCheck. LCS calls the KACS AccessCheck function with:

   • The caller's token (captured in step 1)
   • The final key's SD (returned by the source in the Lookup response)
   • The desired access mask (from the syscall arguments)

   All requested rights MUST be granted or the open fails with EACCES. There is no partial grant -- the caller gets exactly what they asked for, or nothing.

   The special value MAXIMUM_ALLOWED requests whatever the SD grants. AccessCheck computes the full set of allowed rights and uses that as the granted mask.

4. Granted mask storage. The granted access mask is stored on the key fd. It does not change after open.

5. Per-ioctl access check. Each ioctl has a required access right. Before processing, LCS verifies that the fd's granted mask includes the required right. This is a bitmask check, not an AccessCheck re-evaluation. If the right is not present, EACCES is returned without contacting the source.

§3.1.2 Access rights

Registry access rights are bit positions within the desired_access and granted_access uint32 masks. The values match the Windows registry access rights for registry.pol and Samba compatibility.

§3.1.2.1 Specific rights (bits 0--15)

§3.1.2.2 Standard rights (bits 16--23)

§3.1.2.3 System rights

§3.1.2.4 Generic-to-specific mapping

KEY_READ, KEY_WRITE, and KEY_ALL_ACCESS are concrete registry convenience masks. LCS also accepts the raw KACS generic access bits GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE, and GENERIC_ALL in caller-supplied desired_access and in registry SD ACE masks. Those raw generic bits are mapped through the registry GenericMapping before AccessCheck according to PSD-004 §10.10. GENERIC_EXECUTE maps to 0 because registry keys have no execute right.

§3.1.2.5 Access mask validation

LCS validates caller-supplied desired_access before path resolution or AccessCheck. The valid caller mask is:

• the six specific registry rights listed above;
• DELETE, READ_CONTROL, WRITE_DAC, and WRITE_OWNER;
• ACCESS_SYSTEM_SECURITY;
• MAXIMUM_ALLOWED;
• GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE, and GENERIC_ALL.

If desired_access is 0, LCS MUST fail with EINVAL. If desired_access contains any bit outside the valid caller mask, LCS MUST fail with EINVAL. MAXIMUM_ALLOWED MAY be used alone or combined with specific, standard, system, or raw generic rights, following PSD-004 §10.2.

Registry keys do not support SYNCHRONIZE in v0.21. A caller request containing SYNCHRONIZE is therefore an unknown-bit request and fails with EINVAL.

LCS also validates registry SDs returned by sources before using them for AccessCheck. ACE masks MAY contain registry concrete rights and raw KACS generic bits. ACE masks MUST NOT contain MAXIMUM_ALLOWED. After generic mapping, an ACE mask MUST be a subset of concrete registry rights plus ACCESS_SYSTEM_SECURITY. A source SD that violates these rules is malformed source data: LCS fails the operation closed with EIO and emits the source-validation audit event defined in §3.1.

§3.1.3 SD inheritance

When a key is created via reg_create_key, its initial SD is computed from the parent key's SD using the KACS inheritance algorithm (PSD-004 §3.6).

Registry-specific notes:

• Inheritance is static -- computed once at creation time. Changes to the parent's SD do not automatically propagate to existing children. Re-propagation is an explicit admin action (a client-side tree walk), not a kernel operation.

• OBJECT_INHERIT_ACE is not relevant for registry keys. All registry objects are containers (keys contain subkeys and values). Values are not independent security objects -- they inherit their key's access control. Only CONTAINER_INHERIT_ACE applies.

• If the parent has no inheritable ACEs, the child's DACL is set from the creating token's default DACL.

• LCS delegates the inheritance computation to KACS and passes the resulting SD to the source for storage. LCS does not implement its own inheritance logic.

§3.1.4 Hive root SDs

Hive root keys are the top of the inheritance chain -- they have no parent to inherit from. Their SDs are set by the source at first boot and serve as the seeds for all descendant key permissions.

Machine\ root:

Users\<SID>\ root (per-user hive root):

These defaults match Windows HKLM and HKU semantics. Subsystems that need tighter access (e.g., Machine\Security\) set explicit SDs on their subtree roots at creation time, overriding the inherited defaults.

These SDs are not hardcoded in LCS. They are set by the source (loregd) when creating hive roots. LCS enforces whatever SD the source stores.

§3.1.5 Registry-specific considerations

No traverse checking. LCS does not check access on intermediate path components during path resolution. Only the final key's SD is evaluated. This matches the Windows registry model. A process can access Machine\System\Services\Jellyfin without needing any access to Machine\System\Services or Machine\System.

Symlink security. Opening a symlink follows the target path. LCS evaluates AccessCheck on the target key, not the symlink key (unless REG_OPEN_LINK is specified). Symlink creation is privileged (KEY_CREATE_LINK + SeTcbPrivilege or Administrator membership).

Watch access. Subscribing to watches requires KEY_NOTIFY on the key fd. This prevents processes from monitoring keys they cannot read. Subtree watches expose structural changes (key creation, deletion) in descendants without per-descendant access checks -- the watcher learns that a descendant was created but cannot read its values without opening it separately. This matches Windows RegNotifyChangeKeyValue semantics. Structure visibility is intentionally weaker than content visibility.

SACL evaluation and audit. When LCS performs AccessCheck at key open time and the key's SD contains a SACL with matching audit ACEs, LCS MUST emit audit events via the kernel audit pipeline. SACL evaluation follows the KACS AccessCheck algorithm — the SACL is evaluated alongside the DACL. Audit events include the caller's token, the key GUID, the requested access, and the access decision. Accessing or modifying the SACL itself requires ACCESS_SYSTEM_SECURITY, which is gated by SeSecurityPrivilege (see PSD-004 §7).

For v0.21, the LCS kernel audit pipeline is KMES (PSD-003). KMES is an in-kernel PKM facility. LCS audit emission is synchronous at the audit point in the sense that LCS constructs the audit payload and attempts to enqueue it before continuing past that audit point. LCS MUST NOT wait for a userspace KMES consumer to observe or retain the event.

For a key-open SACL audit, LCS evaluates AccessCheck, determines the access decision and granted mask, constructs a valid KMES audit payload, attempts to enqueue the KMES audit event, and only then publishes the resulting key fd to userspace. If LCS cannot construct a valid audit payload because of malformed internal state, corruption, allocation failure, or any other LCS-side payload-construction failure, LCS fails the open with EIO and does not return a key fd. If KMES cannot retain the event after LCS has constructed a valid payload (including KMES unavailability, ring drops, capacity pressure, or consumer absence), LCS does not alter the AccessCheck decision or key fd publication result. KMES loss accounting is handled by KMES.

SD changes and existing fds. SD modifications take effect for future opens. Existing fds retain their granted access mask from open time (§2.1 semantic rule 5). The admin's recourse for revoking access is to restart the service holding the fd.

SD modification access rights:

SD modifications are NOT layer-qualified. They are direct mutations on the key object (§2.1 semantic rule 4). See §2.5 for the distinction between layered data and non-layered properties.

§3.1.6 LCS audit events

LCS emits the following KMES audit events.

caller token summary is a KMES-safe summary of the effective token used for the operation. It must include enough identity information to correlate the event with the caller without exposing unbounded token internals in the event record.

For v0.21, every LCS audit payload MUST be a single msgpack map with string keys. Map order is not semantically significant, but kernel emitters SHOULD encode fields in the table order below for stable diagnostics. GUID fields are 16-byte Microsoft GUID binary values. SID fields are binary KACS SID encodings.

The caller field used below is itself a msgpack map with the following bounded fields:

The caller summary MUST NOT include group lists, privilege arrays, claims, default DACLs, or other unbounded token internals.

LCS_KEY_OPEN_AUDIT payload:

Backup and restore start/complete payloads:

LCS_SOURCE_VALIDATION_FAILURE payload:

Name validation classes are field-specific: malformed_layer_name identifies source-returned layer-name fields, malformed_key_name identifies source-returned key component or child-name fields, and malformed_value_name identifies source-returned value-name fields.

Other source-validation classes identify structural source data failures: malformed_response_payload identifies otherwise matched responses whose operation-specific success payload has the wrong shape, trailing operation-specific bytes, invalid path-target encoding, or another operation-specific payload encoding error. malformed_key_metadata identifies lookup or enum-children metadata closure failures, including missing, duplicate, unreferenced, or nil metadata GUIDs. malformed_value_payload identifies query-values value type/data failures, including invalid value types, tombstone/data mismatches, and oversized value data. malformed_delete_layer_orphan_list identifies invalid RSI_DELETE_LAYER orphan GUID arrays, including nil or duplicate orphan GUIDs.

LCS_SELF_CONFIG_INVALID payload:

Audit emission failure policy:

• For LCS_KEY_OPEN_AUDIT, payload-construction failure returns EIO and the key fd is not published. KMES enqueue, retention, or consumer failure after valid payload construction does not alter the key-open result.
• For LCS_BACKUP_START and LCS_RESTORE_START, failure to emit returns EIO and the backup or restore does not start.
• For LCS_BACKUP_COMPLETE and LCS_RESTORE_COMPLETE, the operation has already completed or failed. LCS attempts emission; if emission fails, it does not alter the already determined result.
• For LCS_SOURCE_VALIDATION_FAILURE, the triggering operation already fails with EIO. LCS attempts emission; if emission fails, the operation still returns EIO.
• For LCS_SELF_CONFIG_INVALID, the invalid value is ignored and the previous known-good value is retained. LCS attempts emission; if emission fails, the retained configuration remains in force.

The registry provides a change observation mechanism that allows processes to watch for configuration changes and react to them. Services like peinit watch their registry subtrees and respond to changes rather than polling.

§4.1.1 Model

Watches follow the inotify model: persistent subscriptions with best-effort event delivery and overflow fallback.

• Persistent watches. Once armed via REG_IOC_NOTIFY, a watch remains active until the fd is closed. Events keep flowing without re-arming. There is no single-shot behaviour. This is an intentional divergence from Windows' RegNotifyChangeKeyValue (see §1.4).

• Best-effort change log. Each event describes a specific change (what type, what name). Events are delivered in order. If events accumulate faster than the watcher reads them, the queue overflows.

• Overflow fallback. When the event queue fills, the oldest events are dropped and an OVERFLOW event is inserted. The watcher MUST do a full re-read of the watched key (and subtree, if applicable) to recover current state. Subsequent events after overflow continue normally.

• Committed state only. Operations within an uncommitted transaction do not generate events. Events fire at commit time. Watchers never see intermediate transactional states.

• Effective state changes. Events reflect changes to the effective (layer-resolved) state, not layer mechanics. A layer deletion that causes a value to revert generates a VALUE_SET event. A layer deletion that causes a key to reappear generates SUBKEY_CREATED. The layer system is transparent to watchers.

§4.1.2 Event types

§4.1.2.1 Blanket tombstone events

When a blanket tombstone is written, LCS determines which values are newly masked and generates one VALUE_DELETED event per affected value name. When a blanket tombstone is removed, LCS determines which values are newly visible and generates one VALUE_SET event per affected value name.

Watchers do not need to understand blanket tombstones. They see per-value effective state changes.

§4.1.2.2 Layer and restore operation events

When a layer is deleted, changes precedence, or is enabled/disabled, LCS determines which keys and values have changed effective state when the affected diff is bounded by retained mutation context and generates the appropriate events. This may produce a large burst of events -- the overflow mechanism handles this naturally.

Layer-wide operations may affect arbitrary descendants for which LCS does not retain exact per-key or per-value mutation context. In that case LCS MUST increment the affected hive generation and enqueue OVERFLOW for every armed watch on the affected source or hive instead of emitting an incomplete exact diff. The OVERFLOW event is the notification for those layer-wide effective-state changes; the watcher MUST re-read as described above.

REG_IOC_RESTORE is an atomic subtree replacement whose pre-restore and post-restore effective-state diff is not retained by LCS as an exact per-key or per-value mutation log. On successful restore, LCS MUST increment the affected hive generation and enqueue OVERFLOW for armed watches on the affected restore source or hive instead of emitting an incomplete exact diff. Failed or aborted restores MUST NOT emit normal watch events for uncommitted restore mutations.

A watch MUST observe every change to the effective value of a watched key, regardless of whether the change was caused by a direct write, a layer deletion, a precedence change, or a blanket tombstone. Observation may be by exact VALUE_/SUBKEY_ events or by OVERFLOW recovery where this section permits layer-wide or restore recovery dispatch.

§4.1.3 Event format

Each event is a variable-length record read from the key fd via read(). A single read() call returns as many complete events as fit in the caller's buffer (matching inotify semantics). If the buffer is too small for even one event, read() returns EINVAL. Events are never split across read() calls. The format supports forward compatibility -- a total length field allows consumers to skip unknown trailing data added in future versions.

§4.1.3.1 Direct watch events

┌──────────────┬──────────────┬───────────────┬──────────────────┐
│ total_len    │ event_type   │ name_len      │ name             │
│ uint32       │ uint16       │ uint16        │ (variable, UTF-8)│
└──────────────┴──────────────┴───────────────┴──────────────────┘

• total_len: Total event size in bytes. Consumers advance by this amount to reach the next event.
• event_type: One of the defined event type codes.
• name_len: Length of the name field in bytes. Zero for events that carry no name (OVERFLOW, KEY_DELETED, SD_CHANGED).
• name: The name of the changed entity. For value events, the value name. For subkey events, the subkey name.

§4.1.3.2 Subtree watch events

Subtree watch events include additional fields after the name, identifying the path from the watched key to the key where the change occurred:

... name │ path_depth │ path_components              │
         │ uint16     │ (len:uint16 + UTF-8 bytes)...│

• path_depth: Number of path components from the watched key to the changed key. Zero means the change is on the watched key itself.
• path_components: A sequence of length-prefixed strings (uint16 length + UTF-8 bytes), one per component from the watched key down to the changed key. No delimiter between components -- length-prefixed encoding is unambiguous.

Watch event string lengths are byte lengths. If an event name or path component cannot be represented in the uint16 length fields, LCS must not emit a malformed event. It inserts or preserves an OVERFLOW event for the watcher instead.

Length-prefixed components avoid delimiter ambiguity. Registry key and value names can contain backslashes (value names) or any Unicode character, so a single concatenated path string would be unparseable.

Future versions MAY append additional fields after path_components. Old consumers skip them via total_len. New consumers check total_len to determine whether optional fields are present.

Exact byte layouts for event structures are defined in §11.2.

This section defines how LCS determines which watches are affected by a mutation and delivers events to them.

§4.2.1 Watch semantics

Object-semantic, not path-semantic. A watch is attached to a key fd, which references a specific key object (GUID). The watch fires for changes to that object. If a layer change causes a different key to become visible at the same path, the watch does NOT transfer to the new key -- it stays on the original object.

To watch the new key, the process must detect the change (via a parent subtree watch or a KEY_DELETED event on the old object), re-open the path, and arm a new watch. This is consistent with the fd model: the fd is a capability bound to a specific key identity.

Subtree dispatch is also object-semantic. LCS uses the ancestor chain captured on the mutating key fd at open time. It does not re-resolve the current path at event time. If an ancestor in that captured chain is later hidden, deleted, orphaned, or replaced at the same path by a different GUID, watches attached to the original ancestor GUID still receive matching subtree events from descendants mutated through fds opened through that chain. Watches attached to a new key that later appears at the same path do not receive events from the old key.

This is intentional fd/capability semantics. A watch observes key objects and captured object ancestry, not whatever path string currently resolves to at event time.

One watch per fd. Each key fd has at most one active watch. Calling REG_IOC_NOTIFY on an already-armed fd replaces the previous filter and subtree settings. To watch the same key with different filters, open it twice. Calling REG_IOC_NOTIFY with a filter of zero disarms the watch -- pending events are discarded and no further events are queued.

Key re-emergence. If a watched key is hidden (KEY_DELETED delivered) and the hiding layer is later removed, the key reappears at its original path. Because the watch is GUID-bound and the GUID has not changed, the watch resumes receiving events for the re-emerged key. No explicit re-emergence event is defined -- the watcher observes the key's continued activity (value changes, subkey changes) as normal events after the hiding layer is removed.

Arming. A watch is armed by calling REG_IOC_NOTIFY on a key fd. The ioctl takes:

• Filter: A bitmask of event types to receive. Events not matching the filter are not queued.
• Subtree flag: Watch this key only, or this key and descendants up to MaxSubtreeWatchDepth levels deep (default 0 = unlimited, all descendants).

Pollable fd. An armed key fd is pollable via epoll/poll/select. EPOLLIN indicates pending events. read() returns one or more structured event records.

§4.2.2 Kernel data structures

LCS maintains two data structures for dispatch:

1. Watch map. A hash map from GUID to a list of armed watchers (direct watches on that GUID). When a mutation occurs on key B, LCS looks up B's GUID in the watch map and fires matching watchers. O(1) lookup.

2. Subtree watch set. A hash set of GUIDs that have at least one active subtree watch. Used for ancestor chain matching.

§4.2.3 Ancestor chain

When a key is opened, LCS resolves the path component by component via RSI Lookup, collecting the GUID at each level. This ancestor chain (root GUID → ... → parent GUID → key GUID) is stored on the key fd at open time.

The ancestor chain is a byproduct of path resolution -- it requires no additional RSI queries. It is bounded by tree depth (typically < 20 GUIDs). For keys opened through symlinks, the ancestor chain reflects the resolved path (the target key's actual position in the tree), not the symlink path.

For keys opened via relative open (parent fd + relative path), the ancestor chain is the parent fd's ancestor chain extended with the GUIDs resolved during the relative path walk.

§4.2.4 Dispatch algorithm

When a mutation occurs on key B (via a key fd whose ancestor chain is known):

// Map event type codes to filter categories.
// KEY_DELETED and OVERFLOW are always delivered regardless of filter.
event_category(event_type):
    if event_type == VALUE_SET or event_type == VALUE_DELETED:
        return REG_NOTIFY_VALUE
    if event_type == SUBKEY_CREATED or event_type == SUBKEY_DELETED:
        return REG_NOTIFY_SUBKEY
    if event_type == SD_CHANGED:
        return REG_NOTIFY_SD
    if event_type == KEY_DELETED or event_type == OVERFLOW:
        return 0  // always delivered

matches_filter(event_type, filter):
    category = event_category(event_type)
    return category == 0 or (filter & category) != 0

dispatch(key_b_guid, ancestor_chain, event_type, event_data):
    // Step 1: Fire direct watches on B
    watchers = watch_map.get(key_b_guid)
    if watchers is not None:
        for watcher in watchers:
            if matches_filter(event_type, watcher.filter):
                enqueue(watcher, event_type, event_data, path_depth=0)

    // Step 2: Walk ancestor chain for subtree watches
    for ancestor_guid in reversed(ancestor_chain):
        if ancestor_guid == key_b_guid:
            continue  // already handled in step 1
        if ancestor_guid not in subtree_watch_set:
            continue  // no subtree watches here, skip
        watchers = watch_map.get(ancestor_guid)
        if watchers is not None:
            for watcher in watchers:
                if not watcher.subtree:
                    continue  // direct watch, not interested
                if matches_filter(event_type, watcher.filter):
                    path = build_relative_path(ancestor_chain, ancestor_guid, key_b_guid)
                    enqueue(watcher, event_type, event_data, path)

Cost per mutation: O(depth) hash lookups against the subtree watch set. Depth is bounded by tree structure. No RSI round trips. No trie. No string matching. The ancestor chain was captured at open time and hash lookups are O(1) each.

§4.2.5 Transaction batching

When a transaction commits, all changes within the transaction generate their events as a batch. Events are ordered by the sequence in which operations were performed within the transaction. The watcher sees the full set of changes atomically -- no interleaving with events from other operations between the batch members.

LCS derives the batch from the transaction mutation log defined in §5.1. The source commits storage atomically; LCS remains responsible for computing effective-state changes and dispatching watch events.

If the number of events generated for a single watcher from one transaction commit exceeds MaxTransactionWatchEventBurst (default 4096), LCS stops generating individual events and inserts a single OVERFLOW event instead. This prevents a large transaction (e.g., role installation writing thousands of values) from atomically filling a watcher's queue.

Aborted transactions generate no events.

§4.2.6 Layer-wide and restore recovery dispatch

Layer deletion, precedence changes, and enable/disable changes can alter effective state for keys and values whose fds are not open and whose exact descendant contexts are not retained by the kernel. When LCS has a bounded exact diff for a layer operation, it SHOULD dispatch the specific events through the normal algorithm above. When the exact diff is not bounded by retained mutation context, LCS MUST dispatch a no-name OVERFLOW event to every armed watch on the affected source or hive after publishing the corresponding hive generation increment.

Layer-wide OVERFLOW recovery is object-semantic: it is delivered to currently armed watches for objects in the affected source or hive and does not re-resolve path strings. OVERFLOW bypasses the caller's event filter, remains queued through the normal per-fd queue rules, and does not disarm persistent watches.

Successful REG_IOC_RESTORE uses the same recovery mechanism. Because restore replaces an arbitrary subtree from a stream and LCS does not retain a bounded exact effective-state diff for every key and value in that subtree, LCS MUST publish the affected hive generation increment and dispatch no-name OVERFLOW to armed watches on the affected restore source or hive after the restore transaction commits. LCS MUST NOT emit restore watch recovery before the source commit succeeds.

§4.2.7 Source restart behaviour

When a source disconnects and re-registers, LCS cannot determine what changed while the source was down. OVERFLOW is delivered on re-registration, not on disconnect. This ensures watchers can successfully re-read state when they receive the OVERFLOW (the source is available). During the window between disconnect and re-registration, watches remain armed but no events are delivered. Operations on watched keys return EIO during this window.

Watches remain armed across source restarts. The persistent watch model means watchers do not need to re-arm after a source restart.

§4.2.8 Queue management

Each armed key fd has an event queue with a configurable maximum size (NotificationQueueSize, default 256 events). When the queue is full and a new event arrives:

1. The oldest event in the queue is dropped.
2. An OVERFLOW event is inserted if one is not already present.
3. Subsequent events continue to be queued normally.

The maximum queue size is configurable via the self-configuration mechanism (§8.2).

§4.2.8.1 Memory bounding

Each watch queues at most the configured maximum events. Each process can hold at most RLIMIT_NOFILE fds (and therefore at most that many watches). The combination of per-queue limits and per-process fd limits provides kernel memory exhaustion protection without a registry-specific global cap.

Transactions provide atomic multi-key writes within a single source. A process groups registry operations into a transaction -- either all operations commit together or none do. This is the mechanism for consistent configuration updates: a role installation writes service definitions, default config, and registry entries as a single atomic unit.

§5.1.1 Scope

Hive-scoped. A transaction binds to a specific hive on its first mutating operation (value write, key create, key delete, key hide, SD change, blanket tombstone). Read operations within a transaction do NOT bind it. All subsequent operations MUST target keys in the same hive. An operation targeting a different hive fails with EXDEV. LCS enforces hive-scoping before forwarding operations to the source -- sources never receive cross-hive operations within a transaction.

Transaction creation is source-agnostic. reg_begin_transaction() does not choose a source and therefore cannot fail because a particular source lacks transaction support. If the first operation that would bind the transaction targets a source that does not support explicit transactions, that operation fails with ENOTSUP and the transaction remains unbound.

If a source is Down before first bind, the attempted binding operation fails according to normal source-unavailable rules and the transaction remains unbound. If a source goes Down after a transaction is bound, the transaction object enters SOURCE_DOWN as described in §10.1.

Reads with an unbound transaction fd behave as ordinary non-transactional reads. They do not bind the transaction and LCS sends them to the source with txn_id = 0. After a transaction is bound by a mutating operation, reads against the same hive/source use the transaction context and are sent with the transaction ID, providing read-your-own-writes. Reads against a different hive/source than the bound transaction fail with EXDEV. Reads using a committed, aborted, or otherwise closed transaction object fail with EINVAL. Reads using a timed-out transaction object fail with ETIMEDOUT. Reads using a transaction object whose bound source went Down fail with EIO.

Cross-source atomicity would require two-phase commit and is not supported.

§5.1.2 Lifetime

A transaction object is represented by the fd returned by reg_begin_transaction(). It remains addressable until the fd is closed, even after it reaches a terminal state. Four ways a transaction reaches a terminal state:

• Commit. REG_IOC_COMMIT on the transaction fd. The source atomically applies all operations. Watch events fire. The transaction object enters the COMMITTED terminal state. The fd SHOULD be closed after commit. Further mutating or read operations using the committed transaction fd return EINVAL.

• Explicit abort. close() on the transaction fd without committing. The source discards all pending operations. The transaction object enters the ABORTED terminal state during fd release. No watch events are generated.

• Implicit abort. Process death closes the fd, which aborts. The transaction object enters the ABORTED terminal state during fd release. No orphaned transactions.

• Timeout abort. The transaction lifetime timer fires. LCS marks the transaction object TIMED_OUT and aborts it as described below. The fd remains present in the caller's fd table until normal fd close. Further mutating or read operations using the timed-out transaction fd return ETIMEDOUT.

Transaction fds are pollable. When a transaction reaches any terminal state, LCS wakes poll waiters and reports POLLERR | POLLHUP. Callers that need a race-free reason for wakeup query REG_IOC_TXN_STATUS on the transaction fd.

§5.1.3 Timeout

LCS starts a timer when the transaction fd is created. If the transaction is not committed or aborted within the timeout, LCS auto-aborts it. The transaction object is marked TIMED_OUT, poll waiters are woken, and future operations using the transaction fd return ETIMEDOUT. If the transaction was bound and no commit is already in flight, LCS sends RSI_ABORT_TRANSACTION to the source. The fd is not forcibly removed from the caller's fd table; normal close still releases it.

This prevents a stalled or malicious process from holding the source's write lock indefinitely. Because sources like loregd serialise writers via SQLite WAL, a stalled transaction blocks all other registry writes to that source.

The timeout is configurable via the self-configuration mechanism (default 30 seconds). See §8.2.

§5.1.4 Isolation

Read-your-own-writes. Within a transaction, reads see the transaction's own uncommitted writes. This is handled by the source: when LCS sends a read with a txn_id, the source reads from within its open transaction, which naturally includes pending writes. LCS does not cache uncommitted registry data in the kernel for read resolution.

LCS does maintain a bounded transaction mutation log for kernel-owned semantics. Each mutating operation accepted into a transaction records enough metadata for LCS to compute affected keys, values, layer names, sequence numbers, hive generation updates, and watch events after a successful commit. This log is not the source of truth for reads or rollback; source transaction state remains authoritative for uncommitted data.

If LCS cannot allocate the mutation-log entry for a transactional operation, the operation fails before it is sent to the source. On explicit abort, transaction lifetime timeout before commit dispatch, source-down cancellation, a late commit error after a retained post-dispatch timeout, or source connection teardown while a post-dispatch commit response is retained, LCS discards or releases the mutation log and emits no normal watch events for the transaction. On successful commit, LCS uses the mutation log and source queries as needed to compute effective-state changes and emit watch events.

If a successful or late-successful source commit requires source queries only to derive transaction watch events, and those replay snapshot queries cannot complete exactly, LCS MUST NOT reinterpret the already-successful source commit as a failed commit. LCS MUST NOT emit normal per-change watch events from incomplete replay data. Instead, LCS MUST deliver OVERFLOW to affected watchers, release retained transaction replay state once overflow recovery is selected, and continue to report the transaction commit as successful. If an RSI request had already been dispatched before timeout, its in-flight request record remains retained under §10.1 until a matching response or source teardown; the late response is validated normally but does not resurrect normal transaction watch events after overflow recovery has been selected. Malformed replay snapshot source data and malformed replay snapshot protocol follow the source-validation and teardown rules in §10.1.

If REG_IOC_COMMIT returns EBUSY or a synchronous EIO before the transaction reaches a terminal state, the transaction remains ACTIVE_BOUND. LCS MUST retain the mutation log, MUST NOT emit normal watch events, and MUST NOT report terminal poll wakeups for that failed commit attempt. The caller may retry REG_IOC_COMMIT or close the transaction fd to abort.

If a transaction commit request times out after dispatch at the RSI request layer, LCS MUST retain the transaction mutation log until the late commit response is processed or the source connection is torn down. A late successful commit uses the retained log to produce the same generation updates and watch events as an on-time commit. A late commit error releases the log without normal watch events.

External isolation. Other threads and processes see committed state only. A transaction's writes are invisible to external readers until commit.

Layer precedence coherency. If a transaction modifies layer precedence (by writing to Machine\System\Registry\Layers\), the new precedence does NOT take effect within the transaction. LCS resolves layers using its in-memory precedence cache, which is updated only at commit time via the self-watch mechanism. Within the transaction, layer resolution uses the pre-transaction precedence. Reading back the precedence value itself shows the new value (read-your-own-writes from the source), but resolution of other values uses the old order.

§5.1.5 Conflict handling

Transactions are atomic but not conflict-detecting at the key level. If two transactions write to the same value, both commits succeed -- the last to commit wins (its write has the higher sequence number).

Write serialisation is the source's responsibility. Sources MUST serialise concurrent commits. For loregd, SQLite's WAL mode serialises writers at the database level. A second writer blocks until the first commits or the transaction timeout fires.

The RSI contract requires: commits are atomic (all-or-nothing), writes within a transaction are ordered, and concurrent commits are serialised. Key-level conflict detection is not required.

Write starvation. Because writers are serialised, a long-running transaction can block other writers. The transaction timeout bounds the maximum starvation window.

§5.1.6 Watch interaction

Watch events fire at commit time, not during individual operations within the transaction. Watchers never see intermediate transactional states.

All changes within a committed transaction generate their events as a batch, ordered by the sequence in which operations were performed. No interleaving with events from other operations between batch members.

Aborted transactions generate no events.

§5.1.7 Constraints

• No nesting. Transactions are flat. No savepoints, no sub-transactions.

• No cross-source. Transactions MUST NOT span sources.

• One active transaction per fd. A process can have multiple concurrent transactions (multiple transaction fds), but each fd represents exactly one transaction.

• Per-source bound transaction limit. LCS enforces a system-wide maximum number of concurrently bound transactions per source. A transaction becomes bound on its first mutating operation. If the limit is reached, subsequent operations that would bind a new transaction to that source return EBUSY. The limit is configurable via the self-configuration mechanism (MaxBoundTransactionsPerSource, default 16). This prevents transaction chaining attacks where colluding processes hold the source's write lock indefinitely by serially binding transactions at the timeout boundary.

• Reads are permitted. Transactions are not write-only. Reads within a transaction see the transaction's uncommitted state, which is useful for verify-then-write patterns.

LCS uses a hybrid syscall/ioctl model, following the pattern established by KACS within PKM:

• Syscalls for operations that create file descriptors: opening keys, creating keys, beginning transactions. Numbered in the PKM range (1100+).
• Ioctls on key fds for operations on an already-opened key: reading values, writing values, deleting, enumerating, security, watches.
• Ioctls on transaction fds for transaction control (commit).
• close() for releasing key and transaction fds. Standard fd lifecycle.

§6.1.1 Key fds

Key fds are anonymous file descriptors (via anon_inode_getfd) representing an open reference to a registry key. A key fd stores:

Key fds support standard fd semantics: close(), close-on-exec, poll()/epoll(), passing over Unix sockets via SCM_RIGHTS.

§6.1.2 Open-time access checking

When a key is opened, the caller specifies a desired access mask. LCS evaluates AccessCheck against the key's SD using the caller's token. All requested rights MUST be granted or the open fails with EACCES. There is no partial grant.

The special value MAXIMUM_ALLOWED requests whatever the SD grants. This is the only way to get a "give me what I can get" fd.

The granted access mask is stored on the fd and checked on every subsequent ioctl -- a bitmask check, not an AccessCheck re-evaluation.

§6.1.3 Fd delegation

Key fds can be passed over Unix sockets via SCM_RIGHTS. A passed key fd carries its granted access mask -- the recipient gets the access the original opener was granted, regardless of the recipient's own token.

This is explicit capability delegation, consistent with the Peios model where fds are capabilities. Passing a KEY_WRITE fd to another process gives that process write access even if its own token would not pass AccessCheck.

Opening a key relative to a parent key fd avoids redundant path parsing and AccessCheck for the parent portion. This is the common case for traversing a subtree.

§6.1.4 Transaction fds

Transaction fds are anonymous file descriptors representing an active transaction. A transaction fd stores the transaction ID and source binding (determined by the first operation). Transaction lifetime is fd lifetime: closing without committing aborts.

§6.1.5 Ioctl type byte

All key fd ioctls use type byte 'R' (Registry). Transaction fd ioctls use the same type byte.

LCS defines three syscalls, numbered in the PKM range starting at 1100.

§6.2.1 reg_open_key (1100)

Open an existing registry key. Fails if the key does not exist after layer resolution.

int reg_open_key(int parent_fd, const char *path,
                 uint32_t desired_access, uint32_t flags);

§6.2.1.1 Parameters

§6.2.1.2 Returns

Key fd on success. -1 with errno on failure.

§6.2.1.3 Behaviour

1. Parse and canonicalise the path. Normalise forward slashes, validate structure (no empty components, no trailing separator). Validate total path length against MaxTotalPathLength. Validate each component against MaxPathComponentLength.
2. Rewrite CurrentUser\ to Users\<caller SID>\ if the first component is CurrentUser. This rewriting applies only to the caller-supplied path, not to symlink targets encountered during resolution.
3. Route to the source. If parent_fd is -1, extract the first path component (hive name) and look it up in the routing table (private hives first, then global hives — private hives can shadow global hives). If parent_fd is a valid key fd, the source is the same source that backs the parent key's hive. The path is resolved relative to the parent key's GUID.
4. Walk the path component by component via RSI Lookup operations. At each component, resolve through the layer stack to find the effective key. Follow symlinks (unless the final component is a symlink and REG_OPEN_LINK is set). Collect the ancestor chain (GUID at each component).
5. Evaluate AccessCheck against the final key's SD with the caller's token and desired_access.
6. Create an anonymous fd storing the key GUID, granted access mask, resolved path, and ancestor chain. Return the fd.

§6.2.1.4 Symlink path identity

If the path traversed a symlink, the fd stores the resolved path and ancestor chain (actual GUIDs after following the symlink), not the original symlink path. The fd refers to the target object.

To operate on the symlink key itself, open with REG_OPEN_LINK.

§6.2.1.5 Errors

§6.2.2 reg_create_key (1101)

Open or create a registry key. If the key exists after layer resolution, opens it. If not, creates it with an inherited SD. Returns a disposition indicating which occurred.

int reg_create_key(const struct reg_create_key_args *args);

§6.2.2.1 Parameters

§6.2.2.2 Returns

Key fd on success. -1 with errno on failure.

§6.2.2.3 Behaviour (key exists)

Same as reg_open_key. The layer parameter is ignored. Disposition is set to REG_OPENED_EXISTING.

Race handling. If two concurrent reg_create_key calls race on the same path, one creates the key and the other observes it as existing. If RSI_CREATE_ENTRY returns RSI_ALREADY_EXISTS, LCS retries as an open (disposition REG_OPENED_EXISTING). EEXIST is never returned to userspace from reg_create_key.

If RSI_CREATE_ENTRY succeeds but the following RSI_CREATE_KEY for the fresh LCS-assigned GUID returns RSI_ALREADY_EXISTS, LCS MUST treat the source state as inconsistent and fail closed with EIO. This case MUST NOT be retried as open-existing and MUST NOT expose EEXIST to userspace.

§6.2.2.4 Behaviour (key does not exist)

1. Resolve the parent path. The parent MUST exist. Validate that the parent's depth + 1 does not exceed MaxKeyDepth.
2. Evaluate AccessCheck on the parent key with KEY_CREATE_SUB_KEY.
3. Perform layer write authorization: verify the caller's token has KEY_SET_VALUE on the target layer's metadata key at Machine\System\Registry\Layers\<layer>\. If layer is null (base layer), check against the base layer's metadata key. If the base layer's metadata key does not yet exist (first boot before seed restore), LCS uses the compiled-in default SD (SYSTEM and Administrators: KEY_ALL_ACCESS).
4. Assign a new LCS-generated UUIDv4 GUID as defined in §2.3.
5. Compute the new key's SD from the parent's SD via the KACS inheritance algorithm (PSD-004 §3.6).
6. Create a path entry (parent, name, layer) → GUID with a new sequence number via RSI.
7. Create the key record (GUID, name, parent GUID, SD, flags) via RSI.
8. Evaluate AccessCheck on the new key's SD with desired_access. The inherited SD may not grant everything requested.
9. Create the fd with granted access. Set disposition to REG_CREATED_NEW. Return the fd.

§6.2.2.5 Additional errors

§6.2.2.6 Notes

• Creating a volatile key under a non-volatile parent is permitted. Creating a non-volatile key under a volatile parent is forbidden (EINVAL).
• REG_OPTION_CREATE_LINK requires KEY_CREATE_LINK on the parent and SeTcbPrivilege or Administrator group membership.
• Intermediate path components are NOT auto-created. Only the final component is created.

§6.2.3 reg_begin_transaction (1102)

Begin a new registry transaction. Returns a transaction fd.

int reg_begin_transaction(void);

§6.2.3.1 Parameters

None.

§6.2.3.2 Returns

Transaction fd on success. -1 with errno on failure.

§6.2.3.3 Behaviour

1. Allocate a transaction ID (kernel-internal, monotonic).
2. Create an anonymous fd storing the transaction ID. Source binding is deferred until the first operation.
3. Start the transaction timeout timer.
4. Return the fd.

§6.2.3.4 Errors

reg_begin_transaction is source-agnostic. Source transaction support is checked by the first operation that would bind the transaction to a source.

All ioctls on key fds use type byte 'R'. Each ioctl checks the fd's granted access mask before proceeding. If the required access right is not present, the ioctl returns EACCES without contacting the source.

All mutating ioctls accept an optional transaction fd. If provided, the operation is enlisted in the transaction. If the transaction is bound to a different hive than the key's hive, the ioctl returns EXDEV.

If a mutating ioctl would bind an unbound transaction to a source that does not support explicit transactions, the ioctl returns ENOTSUP and the transaction remains unbound.

Read ioctls (REG_IOC_QUERY_VALUE, REG_IOC_QUERY_VALUES_BATCH, REG_IOC_ENUM_VALUES, REG_IOC_ENUM_SUBKEYS) also accept an optional transaction fd. If provided, the read is performed within the transaction's context, providing read-your-own-writes isolation: the caller sees the transaction's uncommitted writes. If the transaction is unbound, the read is performed as a normal non-transactional read and does not bind the transaction. If the transaction is bound to a different hive/source, the read returns EXDEV. If the transaction object is committed, aborted, or otherwise closed, the read returns EINVAL. If the transaction object is timed out, the read returns ETIMEDOUT. If the transaction object's bound source went Down, the read returns EIO.

All mutating ioctls that accept a layer name parameter perform layer write authorization before proceeding. LCS verifies that the caller's token has KEY_SET_VALUE on the target layer's metadata key at Machine\System\Registry\Layers\<layer_name>\. If the caller lacks access, the ioctl returns EACCES. If the named layer does not exist in the layer table, the ioctl returns ENOENT. LCS caches layer metadata SDs alongside the layer table and invalidates the cache via the self-watch mechanism.

Base layer fallback. The base layer's metadata key at Machine\System\Registry\Layers\base\ inherits from the Machine hive root (SYSTEM and Administrators: KEY_ALL_ACCESS). If the base layer's metadata key does not yet exist (first boot before seed restore), LCS uses a compiled-in default SD granting KEY_ALL_ACCESS to SYSTEM and Administrators. This default is replaced when the key is created via seed restore.

§6.3.1 Common ioctl errors

The following errors apply to all key fd ioctls unless stated otherwise:

Individual ioctls document additional errors specific to their operation.

§6.3.2 Variable-size output buffers

Read ioctls that return variable-size data use a uniform two-pass buffer ABI. This applies to REG_IOC_QUERY_VALUE, REG_IOC_QUERY_VALUES_BATCH, REG_IOC_ENUM_VALUES, REG_IOC_ENUM_SUBKEYS, REG_IOC_QUERY_KEY_INFO, and REG_IOC_GET_SECURITY.

For each output buffer described by (buffer_length, buffer_ptr):

• buffer_length = 0 and buffer_ptr = NULL is a valid size probe.
• buffer_length = 0 and buffer_ptr != NULL is also treated as a size probe; LCS ignores the pointer.
• buffer_length > 0 requires buffer_ptr != NULL and writable for buffer_length bytes. Otherwise the ioctl returns EFAULT.

If any output buffer is too small, the ioctl returns ERANGE. On ERANGE, LCS writes all required size fields that it can determine for that operation. If multiple output buffers are too small, all known required sizes are reported in the same returned argument structure. Output buffers MUST NOT be partially filled on ERANGE; their contents are unspecified. Output scalar metadata is valid only on successful return unless the ioctl explicitly documents that a field carries a required size or count on ERANGE.

Input pointer faults return EFAULT. LCS validates user input pointers before source dispatch where possible. Output pointer faults return EFAULT.

§6.3.3 Key fd ioctls

§6.3.3.1 REG_IOC_QUERY_VALUE

Read the effective value of a named value on this key.

Input: Value name (string, empty string for default value), optional transaction fd.

Output: Value type (uint32), data (bytes), data length, effective sequence (uint64), effective layer name (string). When the effective entry is from the base layer, the returned layer name is "base".

Behaviour: LCS sends a query to the source for all layer entries of this (key GUID, value name) plus any blanket tombstones on the key. If a transaction fd is provided, the query is sent within the transaction's context (read-your-own-writes). LCS resolves through the layer stack and returns the effective value. If the effective entry is a tombstone or blanket tombstone, returns ENOENT. If no entries exist, returns ENOENT.

Additional errors:

§6.3.3.2 REG_IOC_SET_VALUE

Write a value entry in a specific layer, with optional conditional write support.

Input: Value name (string), value type (uint32), data (bytes), layer name (string, null for base layer), optional transaction fd, optional expected_sequence (uint64).

Behaviour: LCS assigns the next sequence number from the global counter and sends a write to the source: store (key GUID, value name, layer) → (type, data, sequence).

If type is REG_TOMBSTONE, the source stores a tombstone entry. REG_TOMBSTONE is the explicit per-value tombstone write operation. REG_TOMBSTONE writes MUST have data_len = 0. REG_TOMBSTONE is never exposed to callers reading values.

Updates the key's last write time.

Conditional writes. If expected_sequence is non-zero, LCS passes it to the source in the RSI_SET_VALUE request. The source MUST atomically verify that the layer's current entry at (key GUID, value name, layer) has this sequence number before writing. If the sequence does not match or no entry exists, the source returns RSI_CAS_FAILED and LCS returns EAGAIN to the caller.

The condition is evaluated against the layer's own entry, not the effective value, and is enforced by the source atomically. LCS does not perform a separate query-then-write. This prevents lost updates from concurrent writers within the same layer. Cross-layer overrides are not conflicts -- they are the layer system working as designed.

Additional errors:

§6.3.3.3 REG_IOC_DELETE_VALUE

Remove a layer's entry for a value.

Input: Value name (string), layer name (string, null for base layer), optional transaction fd.

Behaviour: LCS tells the source to remove the entry at (key GUID, value name, layer). If no entry exists for that layer, returns success (idempotent). Updates the key's last write time.

This removes the layer's opinion -- whether it was a normal value or a tombstone. If lower-precedence layers have entries, they become effective.

§6.3.3.4 REG_IOC_BLANKET_TOMBSTONE

Write or remove a blanket tombstone for a layer on this key.

Input: Layer name (string, null for base layer), set flag (boolean -- true to write, false to remove), optional transaction fd.

Behaviour: If set is true, LCS tells the source to set the blanket tombstone flag on (key GUID, layer). This masks all values from lower-precedence layers for this key. A new sequence number is assigned for watch dispatch ordering.

If set is false, LCS tells the source to remove the blanket tombstone. Lower-precedence values become visible again.

Updates the key's last write time. Watch events are generated for each value whose effective state changed.

§6.3.3.5 REG_IOC_QUERY_VALUES_BATCH

Read all effective values for this key in a single call.

Input: Buffer for results.

Output: Array of (name, type, data, data_length) tuples for all effective values. Values masked by tombstones or blanket tombstones are omitted.

Behaviour: LCS requests all values for this key GUID from the source, resolves each through the layer stack (including blanket tombstones), and returns the complete effective value set in one call.

This replaces the index-based REG_IOC_ENUM_VALUES loop for callers that want all values. It avoids the O(n²) cost of repeated single-index enumeration.

Additional errors:

§6.3.3.6 REG_IOC_ENUM_VALUES

Enumerate values by index. Returns one effective value per call.

Input: Index (uint32), buffer for name/type/data.

Output: Value name, type, data, data length at the given index.

Behaviour: LCS requests all values for this key GUID from the source, resolves each through the layer stack, filters out tombstones and blanket-masked values, and returns the entry at the requested index. Returns ENOENT when the index is past the last value.

Additional errors:

Each call re-resolves the full value set. A 0..N-1 enumeration loop performs N full resolutions -- O(n²) total work. For most keys (< 20 values) this is negligible. For hot paths, use REG_IOC_QUERY_VALUES_BATCH.

Enumeration order is not defined. The index-to-entry mapping may change between calls if the key's effective values change (mutations, layer changes). Callers MUST NOT cache indices across mutations. Use REG_IOC_QUERY_VALUES_BATCH for a consistent snapshot of all values.

§6.3.3.7 REG_IOC_ENUM_SUBKEYS

Enumerate child keys by index.

Input: Index (uint32), buffer for name and metadata.

Output: Subkey name, last write time, subkey count, value count at the given index.

Behaviour: LCS requests all child path entries from the source, resolves visibility through the layer stack, and returns the entry at the requested index. Returns ENOENT when past the last subkey.

No per-child AccessCheck is performed during enumeration. All visible children are returned regardless of the caller's access to individual child keys. The caller learns child key names but MUST open each child separately (with AccessCheck) to read its contents. This matches Windows RegEnumKeyEx and filesystem readdir semantics.

Same O(n²) characteristic as REG_IOC_ENUM_VALUES.

Additional errors:

§6.3.3.8 REG_IOC_QUERY_KEY_INFO

Query metadata about the key.

Output: Key name, last write time, subkey count, value count, max subkey name length, max value name length, max value data size, SD size, volatile flag, symlink flag, hive generation number.

Hive generation number. A monotonic per-hive change epoch owned by LCS. It is not a persisted entry sequence number and MUST NOT be interpreted as one. Exposed on every key for convenience. Watchers that receive OVERFLOW can compare their last-seen generation with the current value to detect missed committed changes without speculatively re-reading the entire subtree.

The hive generation number is incremented once per committed mutation or once per committed transaction (not per operation within the transaction). Specifically: a non-transactional write increments by 1; a committed transaction increments by 1 for each affected hive regardless of how many operations it contains.

Layer operations and atomicity. When a layer metadata key is deleted, LCS processes the metadata key deletion and the resulting layer effects (RSI_DELETE_LAYER, effective state recomputation, specific watch events or layer-wide OVERFLOW recovery) as a single atomic generation increment. There is no generation number at which the metadata key is gone but the layer's data entries are still resolving. For layer operations that affect multiple hives, each affected hive's generation number is incremented independently. Layer precedence changes that alter effective state also produce a single generation increment encompassing all effects.

Behaviour: LCS queries the source for subkey and value counts, maximum name/data lengths, and SD size via RSI operations. The key name, flags, last write time, and hive generation number are available from kernel-side state (the fd's metadata and the per-hive generation counter). The hive generation number is purely kernel-side state and is not persisted or reported by the source. Sources persist only layer-entry sequence numbers. On source registration or LCS restart, LCS MAY initialise the volatile hive generation baseline from the source's reported max_sequence so newly observed generations are monotonic relative to persisted entries, but subsequent generation increments are independent of sequence allocation.

Additional errors:

§6.3.3.9 REG_IOC_DELETE_KEY

Remove this key's path entry from a specific layer.

Input: Layer name (string, null for base layer), optional transaction fd.

Behaviour: LCS derives the parent GUID (second-to-last entry in the fd's ancestor chain) and the child name (last component of the fd's resolved path) and tells the source to remove the path entry via RSI_DELETE_ENTRY(parent_GUID, child_name, layer). If no remaining path entries exist across any layer, the key is orphaned (§2.8). Updates the parent key's last write time.

Does NOT delete child keys. Returns ENOTEMPTY if the key has visible children.

Additional errors:

§6.3.3.10 REG_IOC_HIDE_KEY

Create a HIDDEN path entry in a layer, masking this key from visibility.

Input: Layer name (string, null for base layer), optional transaction fd.

Behaviour: LCS derives the parent GUID and child name from the fd's ancestor chain and resolved path (same derivation as REG_IOC_DELETE_KEY) and tells the source to create a HIDDEN path entry via RSI_HIDE_ENTRY(parent_GUID, child_name, layer). The HIDDEN entry masks lower-precedence path entries during resolution. A new sequence number is assigned.

The caller MUST have an open fd to the key being hidden (proving access). The HIDDEN entry is created at the path stored on the fd, in the specified layer.

When the hiding layer is removed, the lower-precedence key reappears.

Additional errors:

§6.3.3.11 REG_IOC_GET_SECURITY

Read the key's Security Descriptor.

Input: Security information flags (which SD components to return: owner, group, DACL, SACL).

Output: SD in binary KACS format.

Security information validation: Valid flags are OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, and SACL_SECURITY_INFORMATION. security_info MUST be non-zero and MUST NOT contain unknown flags. Invalid security_info fails with EINVAL before source contact.

Required rights are computed from all requested components. Owner, group, and DACL queries require READ_CONTROL. SACL queries require ACCESS_SYSTEM_SECURITY. If both categories are requested, both rights must be present on the key fd before source contact.

Additional errors:

§6.3.3.12 REG_IOC_SET_SECURITY

Modify the key's Security Descriptor.

Input: Security information flags (which components to set), SD in binary KACS format, optional transaction fd.

Behaviour: LCS merges the provided SD components into the key's existing SD and tells the source to persist the update. SD changes are NOT layer-qualified -- they modify the key directly. Updates the key's last write time.

Security information validation: Valid flags are OWNER_SECURITY_INFORMATION, GROUP_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION, and SACL_SECURITY_INFORMATION. security_info MUST be non-zero and MUST NOT contain unknown flags. Invalid security_info fails with EINVAL before source contact, transaction enlistment, or mutation.

Required rights are computed from all requested components. Setting owner or group requires WRITE_OWNER. Setting DACL requires WRITE_DAC. Setting SACL requires ACCESS_SYSTEM_SECURITY. If combined flags require multiple rights, all required rights must be present on the key fd before source contact or mutation.

The input SD is one self-relative KACS SD subset. LCS reads only the components indicated by security_info; unindicated components are ignored and the existing key SD components are preserved. The merged resulting SD MUST still have an owner. A null group SID remains valid.

Transaction interaction. If a transaction fd is provided, the SD change is enlisted in the transaction. It commits or aborts with the rest of the transaction's operations. The SD change is still a direct mutation on the key (not tagged with a layer, not reverted on layer deletion) -- the transaction provides atomicity, not layer qualification. An SD change in an aborted transaction is not applied.

Additional errors:

§6.3.3.13 REG_IOC_NOTIFY

Arm this key fd for change watches.

Input: Filter (bitmask of event types), subtree flag (boolean).

Behaviour: Arms the fd. After arming, the fd is pollable via epoll/poll/select -- EPOLLIN indicates pending events. read() on the fd returns structured event records (§4.1).

Calling REG_IOC_NOTIFY on an already-armed fd replaces the previous filter and subtree settings. Calling with filter=0 disarms the watch -- pending events are discarded and no further events are queued until re-armed.

KEY_DELETED and OVERFLOW events are always delivered regardless of filter setting.

Arming a new watch on an already orphaned key returns ENOENT. Watches that were armed before the key became orphaned remain armed as described in §2.8.

§6.3.3.14 REG_IOC_FLUSH

Force the source to persist pending writes for this key's hive.

Behaviour: LCS sends a flush command to the source. Returns when persistence is confirmed. KEY_SET_VALUE is required because flush is only meaningful for callers who have written data that needs durability guarantees. This prevents unprivileged readers from using flush as a disk I/O amplification vector.

§6.3.3.15 REG_IOC_BACKUP

Export this key and its entire subtree to an fd.

Input: Output fd (any writable fd).

Behaviour: LCS opens a read-only source transaction by sending RSI_BEGIN_TRANSACTION with mode RSI_TXN_READ_ONLY to guarantee a point-in-time snapshot, then reads the entire subtree and writes it to the output fd in the standard backup format (§9.1). The read-only transaction is aborted/released when the backup completes; it is never committed. Concurrent mutations do not affect the backup stream. Privilege check only -- no per-key AccessCheck. LCS MUST emit an audit event for every backup operation regardless of SACL state on the target key. The audit event includes the caller's token, the target key GUID, and the output fd. Audit event transport and failure policy are defined in §3.1.

Additional errors:

§6.3.3.16 REG_IOC_RESTORE

Replace this key and its entire subtree from an fd.

Input: Input fd (any readable fd).

Behaviour: See §9.1. Privilege check only -- no per-key AccessCheck. The restore operation MUST be wrapped in a single read-write source transaction. Sources that return RSI_TXN_NOT_SUPPORTED for RSI_BEGIN_TRANSACTION with mode RSI_TXN_READ_WRITE MUST be rejected -- restore requires transactional atomicity. If a GUID collision, checksum failure, or precedence validation failure occurs, the entire restore MUST be rolled back. LCS MUST emit an audit event for every restore operation regardless of SACL state. Audit event transport and failure policy are defined in §3.1.

Precedence validation. After LAYER manifest records are read from the backup stream but before any KEY records are written, LCS MUST check whether any declared layer has Precedence > 0. LCS MUST also check any existing cached layer table entry for the same folded layer identity. If either value is > 0 and the caller's token does not hold SeTcbPrivilege, the restore MUST be aborted with EPERM before any data is written to the source. If the backup stream contains ordinary key/value records for Machine\System\Registry\Layers\<LayerName>\, writes that create or elevate persisted layer metadata to Precedence > 0 are subject to the normal inline SeTcbPrivilege check as well. This prevents SeRestorePrivilege from bypassing the defense-in-depth for high-precedence layers.

Additional errors:

§6.3.4 Transaction fd ioctls

§6.3.4.1 REG_IOC_COMMIT

Commit all operations in this transaction.

Behaviour: LCS tells the bound source to atomically commit all operations. On success, the transaction object enters the COMMITTED terminal state, poll waiters are woken with POLLERR | POLLHUP, and subsequent mutating or read operations using the transaction fd return EINVAL. Watch events for all changes are delivered after commit.

If the source returns the retryable write-lock condition, LCS returns EBUSY and leaves the transaction ACTIVE_BOUND. If the source returns a synchronous commit failure, LCS returns EIO and leaves the transaction ACTIVE_BOUND. In both cases, LCS retains the mutation log, emits no normal watch events, and does not wake poll waiters as if the transaction had become terminal. The caller may retry REG_IOC_COMMIT or close the transaction fd to abort.

Errors (the common key fd error table does not apply to transaction fd ioctls):

§6.3.4.2 REG_IOC_TXN_STATUS

Query the state of a transaction fd.

Input: Pointer to reg_txn_status_args.

Output: Transaction state and terminal errno.

Behaviour: LCS writes the transaction object's current state. If the transaction is terminal, terminal_errno is the errno future mutating or read operations using this transaction fd would return: 0 for COMMITTED, EINVAL for ABORTED, ETIMEDOUT for TIMED_OUT, and EIO for SOURCE_DOWN. For active transactions, terminal_errno is 0.

States:

Errors (the common key fd error table does not apply to transaction fd ioctls):

All syscalls and ioctls use standard Linux error conventions: syscalls return -1 and set errno; ioctls return -1 and set errno.

§6.4.1 Registry-specific errno semantics

The Registry Source Interface (RSI) is the binary protocol and contract between LCS and its backing stores. This section defines the communication channel, message format, and registration lifecycle.

§7.1.1 Communication channel

Sources communicate with LCS via the /dev/pkm_registry character device. The protocol is binary and multiplexed.

Binary. Kernel code produces and consumes fixed-layout messages. No text parsing. Each message has a fixed header followed by operation-specific fields.

Multiplexed. LCS sends concurrent requests tagged with unique request IDs (uint64, monotonic per source connection). The source MAY process requests in any order and sends responses tagged with the matching request ID. LCS matches responses to waiting kernel threads. The maximum number of simultaneously in-flight requests per source is bounded by MaxConcurrentRSIRequests (default 256). When the limit is reached, new operations block until an in-flight request completes or times out.

§7.1.1.1 File-operation semantics

The /dev/pkm_registry fd is message-oriented. The total_len field frames messages, but successful Linux I/O calls never split or join RSI messages.

read(). One successful read() returns exactly one complete RSI request. If no request is queued, blocking read() waits until a request is available or the source fd is closing. If O_NONBLOCK is set and no request is queued, read() returns EAGAIN. If the caller's buffer is too small for the next queued request, read() returns EMSGSIZE and does not consume the request.

write(). One successful write() submits exactly one complete RSI response. The user buffer length MUST equal the response header's total_len and MUST be at least the response header size. Short responses, trailing bytes beyond total_len, unknown request IDs, duplicate responses, response opcodes that do not match the original request, and responses for another source connection fail with EINVAL. No partial response is accepted and successful writes are not short.

Malformed framing or protocol corruption that prevents reliable message parsing is treated as malformed protocol: LCS tears down the connection and marks the source Down. Ordinary per-response semantic errors are reported through RSI status codes and do not tear down the source.

poll()/epoll(). The source fd reports readable when at least one complete request is queued. It reports writable while the source slot is Active and the fd may submit responses. It reports POLLHUP | POLLERR when the source slot is Down or the fd is closing.

MaxConcurrentRSIRequests limits requests dispatched to the source and awaiting response. Kernel callers waiting for an in-flight slot are not themselves dispatched requests and do not have request IDs yet.

Request IDs are monotonic per source connection and are never reused while that connection is live, including after request timeout. A timed-out request remains an in-flight request until a matching response arrives or the source connection is torn down.

RequestTimeoutMs starts when a kernel operation first attempts to reserve an in-flight RSI slot, after local validation and access checks. The same deadline covers waiting for a slot, waiting for the source to read the queued request, and waiting for the response. If the deadline expires before a slot is reserved, the caller receives ETIMEDOUT and no RSI request is sent. If the deadline expires after dispatch, the caller receives ETIMEDOUT and late-response handling follows §10.1.

§7.1.1.2 Timed-out request records

For every dispatched request, LCS keeps a request record until a matching response is processed or the source connection is torn down. The record includes at least the request ID, op code, transaction ID, assigned sequence numbers, affected-object metadata, and any mutation log needed to perform kernel-side effects if the source later reports success.

When RequestTimeoutMs expires after dispatch, LCS detaches the waiting caller from the request record and returns ETIMEDOUT to that caller. The request record remains in the source's in-flight table and continues to count against MaxConcurrentRSIRequests. A source that accumulates timed-out requests can therefore exhaust its in-flight slots until it sends responses or disconnects.

A late response for a retained request is validated exactly like an on-time response. A late response for an unknown request ID, a duplicate response, or any response whose request record has already been released is malformed protocol; LCS tears down the source connection and marks the source Down. This avoids processing a mutation whose kernel-side metadata has been lost.

§7.1.2 Message framing

Request header (22 bytes):

┌───────────┬──────────────┬──────────┬──────────┬─────────────┐
│ total_len │ request_id   │ op_code  │ txn_id   │ payload     │
│ uint32    │ uint64       │ uint16   │ uint64   │ (variable)  │
└───────────┴──────────────┴──────────┴──────────┴─────────────┘

Response header (14 bytes):

┌───────────┬──────────────┬──────────┬─────────────┐
│ total_len │ request_id   │ op_code  │ payload     │
│ uint32    │ uint64       │ uint16   │ (variable)  │
└───────────┴──────────────┴──────────┴─────────────┘

Responses do not include txn_id.

• total_len: Total message size in bytes, including the header. Allows the reader to frame messages on the byte stream.
• request_id: Matches responses to requests. The source copies the request_id from the request into its response.
• op_code: The RSI operation. Responses use the same op_code as the request with the high bit set (op_code | 0x8000).
• txn_id: Transaction ID for operations within a transaction. Zero means no transaction. When non-zero, the source processes the operation within the specified transaction's context. A read-write transaction provides read-your-own-writes isolation; a read-only transaction provides point-in-time snapshot isolation. Present on all requests; responses do not include txn_id.
• payload: Operation-specific fields. Fixed-size fields first (GUIDs, integers, flags), followed by variable-length data (names, SD bytes, value data) with uint32 length prefixes.

All multi-byte integers are little-endian.

§7.1.3 Response status

Every response includes a status code (uint32) as the first field of the payload. Zero indicates success. Non-zero indicates an error from the defined error vocabulary (see Source Errors below).

§7.1.4 Registration

Before entering the request loop, a source registers its hives:

1. Source opens /dev/pkm_registry. The char device's open() handler checks SeTcbPrivilege on the calling thread's token. If the privilege is not held, open() returns EPERM. This prevents unprivileged processes from obtaining an fd to the device at all.
2. Source issues REG_SRC_REGISTER ioctl with:
   • Hive names (string array)
   • Root GUID for each hive
   • Max sequence number (highest write sequence persisted in this source's storage -- LCS uses this to initialise the global counter above any existing value)
   • Flags per hive: PRIVATE (0x01) for private hives
   • Scope GUID per hive (only if PRIVATE flag set -- the scope identifier that threads must carry in their credentials to see this hive)
3. LCS validates:
   • No hive name collisions with other sources' global hives.
   • For private hives: no collisions with other private hives sharing the same scope GUID.
   • SeTcbPrivilege is held by the registering process.
4. On success, the source enters the request loop: read() for requests, write() for responses.

§7.1.4.1 Source slots and re-registration

Successful registration creates a source slot. A source slot is the kernel object that owns one source connection and the hive set registered on that connection.

Each registered hive has a stable hive identity:

• the case-folded hive name
• visibility: global or private
• the private scope GUID, for private hives
• the hive root GUID

Active and Down source slots both reserve their hive identities. Collision checks include Down source slots. A source crash or fd close marks the slot Down; it does not unregister or retire the hive identities.

A new process may resume a Down source slot if it holds SeTcbPrivilege and registers exactly the same hive set as the Down slot. For every hive, the case-folded hive name, visibility, scope GUID, and root GUID must match the previous registration. Partial re-registration is rejected.

If a registration attempts to claim a hive identity reserved by a Down source slot but does not exactly match the complete Down slot, registration fails. If the only mismatch is stale identity data such as a different root GUID for an otherwise matching hive, registration fails with ESTALE. Other malformed or partial resume attempts fail with EINVAL or EEXIST according to the collision being reported.

LCS authenticates a replacement source by SeTcbPrivilege, not by process ID continuity. Process identity cannot survive crash/restart.

New hives must be registered through a new source slot. They cannot be added by mutating a Down source slot during resume. v0.21 defines no implicit retirement or unreservation of Down source slots; any future administrative retirement operation must be explicit.

The maximum number of hives per source is bounded by MaxHivesPerSource (default 64). The maximum number of concurrently registered sources is bounded by MaxRegisteredSources (default 32).

Registration errors:

Layer awareness. Sources do not need the layer table. Sources store entries tagged with layer name strings and return all entries on request. Layer resolution (precedence, enabled state, tombstone evaluation) is performed entirely by LCS. A source that has never seen a particular layer name simply stores entries tagged with it when LCS sends writes. The layer table is a kernel-side concern.

§7.1.5 Source lifecycle

Closed ──register──► Active ──disconnect/crash──► Down
                       ▲                            │
                       └────────re-register─────────┘

• Closed → Active: Source opens /dev/pkm_registry, registers hives. LCS routes traffic to it.
• Active → Down: Source disconnects (fd close) or crashes. LCS marks hives as unavailable. The source slot and its hive identities remain reserved. Active key fds remain valid but operations requiring source round-trips return EIO. Watches remain armed.
• Down → Active: A source process resumes the Down source slot by registering the exact same hive set and root GUIDs. LCS resumes routing. OVERFLOW delivered to all affected watches.

RSI operations fall into five groups: path operations, key operations, value operations, transaction operations, and maintenance operations.

All operations that return layer-qualified data MUST return all entries across all layers. LCS performs layer resolution, not the source. The source returns everything it has; the kernel decides what is effective.

§7.2.1 Path operations

§7.2.1.1 RSI_LOOKUP (op_code: 0x01)

Look up a child entry under a parent key. The primary path-walking primitive -- LCS calls this once per path component.

Request: parent key GUID, child name component (string).

Response: A list of path entries for this (parent, child) pair across all layers. Each entry contains:

For each unique GUID referenced in the entries, the response includes key metadata:

When the key metadata indicates a symlink, LCS resolves the target by performing a separate RSI_QUERY_VALUES for the key's default value (empty-string name) and applying layer resolution to determine the effective REG_LINK target. This ensures symlink targets participate correctly in the layer system.

Empty response (no entries) means the child does not exist in any layer.

§7.2.1.2 RSI_CREATE_ENTRY (op_code: 0x02)

Create a path entry: (parent, child_name, layer) → GUID.

Request: parent GUID, child name, layer name, GUID, sequence number.

Always paired with RSI_CREATE_KEY which provides the fresh GUID.

§7.2.1.3 RSI_HIDE_ENTRY (op_code: 0x03)

Create a HIDDEN path entry at (parent, child_name, layer).

Request: parent GUID, child name, layer name, sequence number.

§7.2.1.4 RSI_DELETE_ENTRY (op_code: 0x04)

Remove the path entry at (parent, child_name, layer). Whether it was a GUID entry or a HIDDEN entry, it is removed.

Request: parent GUID, child name, layer name.

§7.2.1.5 RSI_ENUM_CHILDREN (op_code: 0x05)

Enumerate all child entries under a parent key across all layers.

Request: parent GUID.

Response: For each unique child name, the same entry format as RSI_LOOKUP (per-layer path entries with layer name, target type, GUID, sequence). After all children and their entries, a single deduplicated metadata block covers all unique GUIDs across all children (SD, last write time, volatile flag, symlink flag). This avoids per-child RSI_READ_KEY round trips. HIDDEN entries (zero GUID) do not contribute to the metadata block.

§7.2.2 Key operations

§7.2.2.1 RSI_CREATE_KEY (op_code: 0x10)

Create a new key record. The GUID is assigned by LCS and passed to the source for storage.

Request: GUID, name, parent GUID, SD (binary), volatile flag, symlink flag.

The path entry linking the key into the namespace is created separately via RSI_CREATE_ENTRY. For symlink keys, the target path is written as a separate default REG_LINK value via RSI_SET_VALUE.

§7.2.2.2 RSI_READ_KEY (op_code: 0x11)

Read a key's full record.

Request: GUID.

Response: name, parent GUID, SD, volatile flag, symlink flag, last write time.

§7.2.2.3 RSI_WRITE_KEY (op_code: 0x12)

Update a key's mutable fields. Used for SD updates and last write time updates.

Request: GUID, field bitmask (which fields to update), field values.

Immutable fields (GUID, volatile, symlink flag) MUST NOT be specified. The source MUST reject requests that attempt to modify immutable fields.

§7.2.2.4 RSI_DROP_KEY (op_code: 0x13)

Purge all data associated with a GUID: key record, all value entries across all layers, all path entries, and any blanket tombstones. Called when an orphaned key's last fd closes.

Request: GUID.

RSI_DROP_KEY is idempotent. If the GUID does not exist in the source (e.g., already cleaned up by crash recovery), the source MUST return RSI_OK.

§7.2.3 Value operations

§7.2.3.1 RSI_QUERY_VALUES (op_code: 0x20)

Retrieve all layer entries for a specific value, or all values for a key.

Request: GUID, value name. If value name is the empty sentinel with a query-all flag set, return all values for the key across all layers.

Response: List of entries. Each entry contains:

Additionally, the response includes blanket tombstone state for the key: a list of (layer name, sequence number) pairs for each active blanket tombstone on this key.

§7.2.3.2 RSI_SET_VALUE (op_code: 0x21)

Store a value entry at (GUID, value_name, layer).

Request: GUID, value name, layer name, type, data, sequence number, optional expected_sequence (uint64).

If an entry already exists for this (GUID, value name, layer), it is replaced. If type is REG_TOMBSTONE, the source stores a tombstone marker instead of data.

Conditional write. If expected_sequence is non-zero, the source MUST check that the current entry at (GUID, value name, layer) has this sequence number before writing. If the sequence does not match or no entry exists, the source MUST return RSI_CAS_FAILED without writing.

§7.2.3.3 RSI_DELETE_VALUE_ENTRY (op_code: 0x22)

Remove the entry at (GUID, value_name, layer). Whether it was a normal value or a tombstone, it is removed. Idempotent.

Request: GUID, value name, layer name.

§7.2.3.4 RSI_SET_BLANKET_TOMBSTONE (op_code: 0x23)

Set or remove a blanket tombstone on (GUID, layer).

Request: GUID, layer name, set flag (boolean), sequence number.

If set is true, the source stores a blanket tombstone marker on (GUID, layer) with the given sequence number. If set is false, the source removes the blanket tombstone.

§7.2.4 Transaction operations

§7.2.4.1 RSI_BEGIN_TRANSACTION (op_code: 0x30)

Signal the start of a transaction.

Request: transaction ID (uint64), transaction mode (uint32).

Transaction mode is one of:

The source allocates transaction state. Subsequent operations tagged with this transaction ID are part of the transaction.

For RSI_TXN_READ_WRITE, reads tagged with the transaction ID observe the transaction's own uncommitted writes, and writes tagged with the transaction ID are committed atomically by RSI_COMMIT_TRANSACTION.

For RSI_TXN_READ_ONLY, read operations tagged with the transaction ID MUST observe a stable point-in-time snapshot. Mutating operations MUST NOT be sent by LCS with a read-only transaction ID. If a source receives a mutating operation tagged with a read-only transaction ID, it MUST reject the operation with RSI_INVALID and MUST NOT mutate state. Read-only transactions are released with RSI_ABORT_TRANSACTION; LCS MUST NOT send RSI_COMMIT_TRANSACTION for a read-only transaction.

§7.2.4.2 RSI_COMMIT_TRANSACTION (op_code: 0x31)

Atomically commit all operations in the transaction.

Request: transaction ID.

On success, all changes are durable. On failure, all changes are rolled back and the source reports the error.

§7.2.4.3 RSI_ABORT_TRANSACTION (op_code: 0x32)

Roll back all operations in the transaction.

Request: transaction ID.

Called when the transaction fd is closed without committing, or on timeout. Also used by LCS to release an internal read-only snapshot transaction after REG_IOC_BACKUP completes or fails.

§7.2.5 Layer operations

§7.2.5.1 RSI_DELETE_LAYER (op_code: 0x50)

Remove all entries tagged with a layer name from the source's storage. Called by LCS when a layer's metadata key is deleted.

Request: layer name (string).

Response (success):

The source MUST atomically remove:

• All path entries where layer = layer_name
• All value entries where layer = layer_name
• All blanket tombstones where layer = layer_name

The source MUST NOT remove key records (GUIDs) -- orphan cleanup is managed by LCS via RSI_DROP_KEY when the last fd closes.

If the layer name is unknown to the source (no entries exist for it), the source MUST return RSI_OK with an empty orphaned_guids list. This is not an error -- a layer may have entries in some sources but not others.

§7.2.6 Maintenance operations

§7.2.6.1 RSI_FLUSH (op_code: 0x40)

Persist all pending writes to durable storage for a specific hive.

Request: hive name (string).

This is the only RSI operation that identifies its target by hive name rather than key GUID, because flush is a hive-level operation (e.g., WAL checkpoint), not a key-level one. LCS derives the hive name from the key fd used in the REG_IOC_FLUSH ioctl.

Response: Returns when persistence is confirmed.

A conforming source MUST satisfy all obligations in this section.

§7.3.1 Response timeliness

A source MUST respond to every request. LCS enforces RequestTimeoutMs (default 30 seconds). Unresponsive sources cause ETIMEDOUT for waiting threads. The source is not disconnected on timeout -- it remains active and late responses are processed normally.

RequestTimeoutMs is measured from the point where the kernel operation first attempts to reserve an in-flight RSI slot, after local validation and access checks. The timeout includes waiting for a MaxConcurrentRSIRequests slot, waiting for the source to read the queued request, and waiting for the response.

Timed-out dispatched requests remain in the source's in-flight table until the source responds or disconnects. The source MUST still send exactly one response for every request it has read, even if the original kernel caller timed out.

§7.3.2 Complete layer data

When asked for values or path entries, a source MUST return ALL layer entries. Sources MUST NOT pre-filter, resolve, or omit entries. Layer resolution is LCS's responsibility.

§7.3.3 GUID fidelity

GUIDs are assigned by LCS and passed to the source for storage. Sources MUST persist GUIDs exactly as given. No rewriting, no remapping, no reassignment.

§7.3.4 Concurrency

RSI is multiplexed. A source MUST handle multiple in-flight requests without head-of-line blocking. Sources MAY process requests in any order.

§7.3.5 Transaction support

Sources MUST understand the transaction operations (RSI_BEGIN_TRANSACTION, RSI_COMMIT_TRANSACTION, RSI_ABORT_TRANSACTION). Commits for supported read-write transactions MUST be atomic (all-or-nothing). Concurrent read-write commits MUST be serialised.

Sources whose backing store does not support transactions MAY treat each operation as auto-committed and return RSI_TXN_NOT_SUPPORTED on RSI_BEGIN_TRANSACTION with mode RSI_TXN_READ_WRITE. LCS maps this to ENOTSUP on the first operation that attempts to bind a transaction to that source; source-agnostic reg_begin_transaction still succeeds.

Sources whose backing store does not support stable read-only snapshots MAY return RSI_TXN_NOT_SUPPORTED on RSI_BEGIN_TRANSACTION with mode RSI_TXN_READ_ONLY. LCS maps this to ENOTSUP for REG_IOC_BACKUP. A source MAY support read-only snapshot transactions even if it does not support read-write transactions.

§7.3.6 Conditional write support

Sources MUST support the expected_sequence field on RSI_SET_VALUE. When expected_sequence is non-zero, the source MUST atomically verify the current entry's sequence number matches before writing. If the condition fails, the source MUST return RSI_CAS_FAILED without writing.

§7.3.7 Hive root creation

On first boot (empty database), sources MUST create root key records for each hive they back. The source generates random GUIDs for hive roots, creates the key records with appropriate default SDs (§3.1.4), and persists them. The root GUIDs are provided to LCS in the REG_SRC_REGISTER handshake. Subsequent startups use the persisted root GUIDs.

§7.3.8 Crash recovery

On startup or re-registration, sources MUST clean up orphaned GUIDs before completing registration with LCS. An orphaned GUID is a key record with no path entries in any layer. Sources MUST query for and purge these records as part of their initialisation sequence. If orphan cleanup cannot be completed, the source MUST fail registration rather than becoming Active with known orphaned key records.

§7.3.9 Immutable field protection

Sources MUST reject RSI_WRITE_KEY requests that attempt to modify immutable fields (GUID, volatile flag, symlink flag). Return RSI_INVALID.

§7.3.10 Source errors

Sources report errors via a status code in the response message. LCS maps these to errnos.

§7.3.11 Data validation by LCS

LCS validates every response from a source:

Malformed data (structurally valid RSI response, but invalid content -- SD that doesn't parse, impossible field values):

• Request returns EIO to the caller.
• LCS emits an audit event identifying the source, key GUID, and nature of the validation failure. Audit event transport and failure policy are defined in §3.1.
• Source stays alive. Corruption may be localised.

Sequence number validation. LCS maintains the global counter as next_sequence, the next sequence number it will allocate. LCS MUST reject any layer-qualified entry in an RSI response whose sequence number is greater than or equal to next_sequence. Such entries are treated as malformed data (EIO + audit event). This prevents a compromised source from fabricating sequence numbers to win layer resolution tiebreaks.

Within a single resolution candidate set, duplicate sequence numbers at the same precedence are malformed if they would otherwise be compared to select a winner. LCS rejects the response as malformed data rather than making an arbitrary choice.

The same structural SD validation applies to layer metadata SDs loaded during layer table cache refresh. A malformed SD on a layer metadata key produces an audit event and the layer's cached SD is not updated (the previous known-good SD is retained).

Malformed protocol (RSI message itself is structurally invalid -- framing errors, unknown message types, truncated responses):

• Treated as a source crash. Connection torn down, hives marked unavailable.
• A source that cannot speak the protocol is fundamentally untrustworthy.

§7.3.12 Trust boundary

Sources are in the TCB. A compromised source has full control over the access control outcome for its hives: it can return a permissive SD for any key, causing AccessCheck to grant access that should be denied. LCS validates structural correctness of source responses (malformed SDs produce EIO) but cannot detect semantically incorrect but well-formed data (e.g., an SD that grants Everyone KEY_ALL_ACCESS on a sensitive key).

Mitigations:

• Sources MUST run with tightly scoped privileges and be protected by SDs on their service definitions.
• LCS MUST emit audit events for source data validation failures using the audit event policy defined in §3.1.
• Source processes are critical-path components managed by peinit with PIP (Process Integrity Protection) where available.
• A future hardening path could involve LCS checksumming SDs it computes during inheritance and verifying them on retrieval, but this is not a v0.21 requirement.

Specific high-impact consequences of source compromise:

• Layer table poisoning. A compromised source can return fabricated precedence or enabled values for layer metadata under Machine\System\Registry\Layers\, effectively controlling which layer wins every resolution contest system-wide. The SeTcbPrivilege check at write time does not protect against read-path fabrication.

• Layer write authorization bypass. A compromised source can return permissive SDs for layer metadata keys, granting any process write access to any layer via the layer write authorization check.

• SeRestorePrivilege scope. SeRestorePrivilege effectively confers WRITE_DAC and WRITE_OWNER on any key in the restore subtree, because restore replaces the entire subtree including SDs. Operators granting SeRestorePrivilege should understand it implies full SD modification capability.

§7.3.13 Forward compatibility

The RSI uses a versioned, extensible message format. New optional fields can be appended to requests without breaking existing sources. Sources MUST ignore fields they do not recognise (the total_len field allows skipping unknown trailing data). This enables future features to be added without RSI version bumps.

The registry is the configuration store for the entire system, but the registry itself must be configured and populated. This section defines LCS's behaviour during bootstrap -- how it transitions from "kernel just booted" to "fully operational."

§8.1.1 The bootstrap problem

Three circular dependencies must be broken:

1. peinit needs the registry to start services, but the registry source is a service. peinit cannot read service definitions from the registry because the source providing those definitions hasn't started yet.

2. LCS needs operational parameters from the registry, but the registry needs LCS. LCS reads its configuration from keys that live in a source that LCS manages.

3. First boot has no data. On a fresh install, the source's database is empty.

§8.1.2 Bootstrap rules

§8.1.2.1 Rule 1: Compiled-in defaults

Every LCS operational parameter (see §11.4 for the full list of 19 parameters) has a compiled-in default. LCS operates on these defaults from the moment PKM loads. LCS MUST NOT enter a "waiting for configuration" state. It is always operational.

§8.1.2.2 Rule 2: The base layer exists unconditionally

The base layer is hardcoded in LCS. It exists before any source registers. No persisted metadata is required for the base layer to be functional.

§8.1.2.3 Rule 3: Hot-swap, not restart

When a source registers and the registry becomes available, LCS reads its operational parameters and layer metadata, validates them, and hot-swaps the in-memory values. LCS does not restart or re-initialise. In-flight operations use the values that were active when they started. New operations use the updated values.

§8.1.3 LCS boot sequence

§8.1.3.1 Normal boot (source has existing data)

Kernel boots
  → PKM loaded (KACS + LCS initialised with compiled-in defaults)
  → LCS creates /dev/pkm_registry
  → Base layer exists in memory

Source registers (e.g., loregd started by peinit)
  → Opens /dev/pkm_registry
  → Registers hives with root GUIDs and max sequence number
  → LCS initialises or advances global next_sequence to max + 1

LCS becomes operational for those hives
  → Reads Machine\System\Registry\* (operational parameters)
  → Validates and hot-swaps to registry values
  → Reads Machine\System\Registry\Layers\* (layer metadata)
  → Populates in-memory layer table
  → Arms subtree watch on Machine\System\Registry\

§8.1.3.2 First boot (empty source)

Same as normal boot through source registration

Source registers with empty database
  → Source detects empty database on first startup
  → Source generates random GUIDs for hive root keys
  → Source creates root key records with default SDs
    (Machine root: SYSTEM + Admins KEY_ALL_ACCESS,
     Authenticated Users KEY_READ, all container-inherit)
  → Source persists root GUIDs and registers with LCS
  → Hive roots exist but contain no subkeys

LCS reads Machine\System\Registry\* → ENOENT
  → Retains compiled-in defaults
  → Arms watch on Machine\ root

(peinit detects empty registry, restores seed backup -- this is
peinit's decision, not LCS's concern)

Seed restore populates Machine\ hive via REG_IOC_RESTORE
  → LCS subtree watch fires
  → Re-reads Machine\System\Registry\* (now exists)
  → Validates and hot-swaps to seed values
  → Re-reads layer metadata
  → Normal operation continues

§8.1.4 Bootstrap contract

The following invariants MUST hold during bootstrap and MUST NOT be violated by any future change:

1. LCS is always operational with compiled-in defaults. From the moment PKM loads, LCS can accept syscalls. Before any source registers, all operations return ENOENT (no hives available). After a source registers, operations work against compiled-in defaults until configuration is loaded.

2. The base layer requires no persisted state. LCS hardcodes the base layer's existence, name, precedence, and enabled state. A source that registers with an empty database is fully functional -- the base layer exists in LCS's memory.

3. Hot-swap is the only configuration transition. LCS never blocks, restarts, or re-initialises when transitioning from compiled-in defaults to registry-backed configuration. The self-watch mechanism drives all transitions.

4. Source dependencies are the source's concern. LCS does not know or care what a source depends on. A source that requires the root filesystem, a SYSTEM token, or specific kernel features manages those dependencies itself. LCS's only requirement is that the source can open /dev/pkm_registry and speak RSI.