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 name MUST be unique across all registered sources. A source attempting to register a hive name already claimed by another source MUST be rejected.

• 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.

§2.3.3 Naming rules

The following 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 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.

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:

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 the Deletion section.

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.

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

§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. 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 the Self-Configuration section for the full parameter table.

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.

§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, populated by the internal self-watch on Machine\System\Registry\Layers\. This set is updated when layer metadata keys are created or deleted. The GUID set and the corresponding SD cache entry MUST be populated atomically within the self-watch callback, before the creating syscall returns to userspace. This eliminates any window where a layer exists in the table but has no cached SD or is absent from the GUID set. If the SD for a newly created layer metadata key cannot be read (source error), the layer MUST NOT be added to the table and the creation syscall MUST fail 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).

The cap is configurable via the self-configuration mechanism. See the Self-Configuration section 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.

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.

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.

§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 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.

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.

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.

§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 the Layer lifecycle mechanism in the Layers section).

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, 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

These mappings are applied during AccessCheck. Callers MAY use generic rights in desired_access. SDs MAY contain generic ACEs. The mapping table is defined by LCS and registered with KACS.

§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 (see the SD Inheritance section of the KACS v0.20 specification).

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 the KACS v0.20 Privileges section).

SD changes and existing fds. SD modifications take effect for future opens. Existing fds retain their granted access mask from open time (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 (semantic rule 4). See the Values section for the distinction between layered data and non-layered properties.

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 the Compatibility section).

• 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 operation events

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

LCS MUST detect and emit events for ALL effective state changes caused by layer operations. 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.

§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.

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 the Struct Layouts appendix.

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.

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.

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 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.7 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. See the Self-Configuration section.

§4.2.7.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.

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

§5.1.2 Lifetime

A transaction exists for the lifetime of its fd (returned by reg_begin_transaction). Three ways a transaction ends:

• Commit. REG_IOC_COMMIT on the transaction fd. The source atomically applies all operations. Watch events fire. The fd SHOULD be closed after commit. Further operations on a committed transaction fd return EINVAL.

• Explicit abort. close() on the transaction fd without committing. The source discards all pending operations. No watch events are generated.

• Implicit abort. Process death closes the fd, which aborts. No orphaned transactions.

§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 (sends RSI_ABORT_TRANSACTION to the source and closes the transaction fd).

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 the Self-Configuration section.

§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 transaction state in the kernel.

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(int parent_fd, const char *path,
                   uint32_t desired_access, const char *layer,
                   uint32_t flags, uint32_t *disposition);

§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.

§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 GUID.
5. Compute the new key's SD from the parent's SD via the KACS inheritance algorithm (see the SD Inheritance section of the KACS v0.20 specification).
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

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.

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.

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 Key fd ioctls

§6.3.2.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.2.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 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.2.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.2.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.2.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.2.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.2.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.2.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 counter representing the highest write sequence number committed to this key's hive. Exposed on every key for convenience. Watchers that receive OVERFLOW can compare their last-seen generation with the current value to detect missed 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 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, watch events) 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, not persisted by the source, and resets to the source's max_sequence on LCS restart.

Additional errors:

§6.3.2.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 (see the Deletion section). 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.2.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.

§6.3.2.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.

Additional errors:

§6.3.2.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.

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.

§6.3.2.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 (see the Watch Model section for event format).

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.

§6.3.2.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.2.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 transaction on the source (via RSI_BEGIN_TRANSACTION) to guarantee a point-in-time snapshot, then reads the entire subtree and writes it to the output fd in the standard backup format (see the Backup Format section). The transaction is closed when the backup completes. 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.

Additional errors:

§6.3.2.16 REG_IOC_RESTORE

Replace this key and its entire subtree from an fd.

Input: Input fd (any readable fd).

Behaviour: See the Backup Format section. Privilege check only -- no per-key AccessCheck. The restore operation MUST be wrapped in a single source transaction. Sources that return RSI_TXN_NOT_SUPPORTED for REG_IOC_RESTORE 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.

Precedence validation. After LAYER records are read from the backup stream but before any KEY records are written, LCS MUST check whether any layer in the backup has Precedence > 0. If so and the caller's token does not hold SeTcbPrivilege, the restore MUST be aborted with EPERM before any data is written to the source. This is cheap (LAYER records precede KEY records in the stream) and prevents SeRestorePrivilege from bypassing the SeTcbPrivilege defense-in-depth for high-precedence layer creation.

Additional errors:

§6.3.3 Transaction fd ioctls

§6.3.3.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 is complete -- subsequent operations return EINVAL. Watch events for all changes are delivered after commit.

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.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 (read-your-own-writes 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.

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. Active key fds remain valid but operations requiring source round-trips return EIO. Watches remain armed.
• Down → Active: Source re-registers the same hive names. 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).

The source allocates transaction state. Subsequent operations tagged with this transaction ID are part of the 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.

§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.

§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 support the transaction operations (RSI_BEGIN_TRANSACTION, RSI_COMMIT_TRANSACTION, RSI_ABORT_TRANSACTION). Commits MUST be atomic (all-or-nothing). Concurrent 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. LCS maps this to ENOTSUP on reg_begin_transaction and the caller never receives a transaction fd.

§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 (see the Hive Root SDs section in security/access-control.md), 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, 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.

§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.
• Source stays alive. Corruption may be localised.

Sequence number validation. LCS MUST reject any entry in an RSI response whose sequence number exceeds the current global sequence counter. Such entries are treated as malformed data (EIO

• audit event). This prevents a compromised source from fabricating sequence numbers to win layer resolution tiebreaks.

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.
• 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 the Configuration Reference appendix 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 global sequence counter 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.

LCS reads its own operational parameters from the registry under Machine\System\Registry\. This is the self-watch mechanism: compiled-in defaults at boot, hot-swapped to registry values when available, updated on change.

§8.2.1 Configuration keys

All keys live under Machine\System\Registry\. Each has a defined type, compiled-in default, and valid range. LCS ignores unknown keys in this subtree.

§8.2.2 Validation

When LCS reads a configuration value via the self-watch mechanism, it validates against the defined range:

• Valid value: Hot-swapped into the in-memory configuration. Takes effect for new operations. In-flight operations use the value active when they started.

• Invalid value (out of range, wrong type, missing): Ignored. LCS retains the previously active value (compiled-in default or last known-good). An audit event is emitted identifying the key, the invalid value, and the value being retained.

Values are never clamped or silently corrected. The write to the registry succeeds (the source does not enforce kernel semantics), but LCS refuses to use it. The registry shows what was written; the audit log shows what LCS is actually using.

§8.2.3 Security

LCS tunables live under Machine\System\Registry\, which inherits the Machine hive root SD (SYSTEM and Administrators: KEY_ALL_ACCESS, Authenticated Users: KEY_READ). Unprivileged processes cannot modify operational parameters.

Domain policy enforcement via Group Policy at a higher precedence layer provides defence against compromised local administrators -- SeTcbPrivilege is required for precedence > 0.

§8.2.4 Self-watch mechanism

LCS monitors its own configuration and layer metadata subtrees using an internal kernel registration — not through the fd-based ioctl interface exposed to userspace.

LCS registers interest in specific subtree GUIDs using the same watch map data structure that backs userspace watches. The registration is a kernel-internal watcher: events are delivered via an internal callback, not via read() on an fd. The watcher has no fd, no granted access mask, and no filter — it receives all event types for the watched subtrees.

On startup, after the first source registers, LCS resolves the GUIDs for Machine\System\Registry\ and Machine\System\Registry\Layers\ via RSI_LOOKUP and registers internal subtree watches on both. If either key does not exist (first boot or empty database), LCS arms a subtree watch on the Machine\ hive root instead. When seed restore creates the Registry\ subtree, the root's subtree watch fires, LCS resolves the specific GUIDs, and re-arms targeted watches on both subtrees. These watches drive:

• Self-configuration hot-swap: changes to operational parameters under Machine\System\Registry\ trigger re-read and validation.
• Layer table updates: changes to layer metadata under Machine\System\Registry\Layers\ trigger re-read of precedence, enabled state, and layer metadata SDs.
• Layer lifecycle: SUBKEY_CREATED and SUBKEY_DELETED events under the Layers\ key trigger layer addition or deletion.

The internal watch mechanism is not exposed to userspace and is not subject to the NotificationQueueSize limit (LCS processes events synchronously in the kernel notification path).

§8.2.5 Bootstrap interaction

1. Source registers → LCS reads Machine\System\Registry\* → keys don't exist yet → compiled-in defaults retained.
2. Seed restore populates Machine\System\Registry\* → subtree watch fires → LCS validates and hot-swaps to seed values.
3. Subsequent admin changes → watch fires → LCS validates and hot-swaps (or rejects with audit event).

At no point does LCS enter a "waiting for configuration" state.

The standard registry backup format is used by REG_IOC_BACKUP and REG_IOC_RESTORE, first-boot seeding, disaster recovery, and offline migration. It is an LCS-level format -- sources never see it. LCS serialises from source data on backup and deserialises into RSI operations on restore.

§9.1.1 Design constraints

• Streamable. Written to an arbitrary fd (file, pipe, socket). No seeking. Single-pass write, single-pass read.
• Full layer fidelity. Every path entry, value, tombstone, and blanket tombstone is stored with its layer tag. Restoring reconstructs the full layered state.
• Depth-first pre-order. Parent keys appear before their children. Restore creates keys top-down without buffering.
• SDs inline. Each key record contains its full SD. No deduplication. External compression (e.g., piped through zstd) handles redundancy.
• Self-verifying. A trailer record contains an integrity check. Truncated or corrupted backups are detected at restore time.

§9.1.2 Versioning

The header contains two version fields:

• Format version: The version used to write the backup.
• Minimum reader version: The oldest reader that can correctly process this backup.

A writer using only older features sets a lower minimum reader version, allowing older LCS implementations to restore the backup. A reader encountering a minimum reader version higher than its own MUST reject the backup.

§9.1.3 Record types

The stream is a sequence of typed records. Every record begins with a common framing header:

The record payload follows immediately after the 6-byte framing header.

§9.1.3.1 HEADER (record_type: 0x01)

First record. Exactly one. Payload:

§9.1.3.2 LAYER (record_type: 0x02)

One per layer that has data in the subtree. Emitted after the header and before any records that reference the layer. Payload:

§9.1.3.3 KEY (record_type: 0x03)

One per unique key object in the subtree, regardless of how many layers name it. Payload:

Name and parent GUID are omitted -- they are derivable from the PATH_ENTRY records that follow.

§9.1.3.4 PATH_ENTRY (record_type: 0x04)

One per name→key mapping per layer. Payload:

§9.1.3.5 VALUE (record_type: 0x05)

One per value entry per layer, including tombstones. Payload:

§9.1.3.6 BLANKET_TOMBSTONE (record_type: 0x06)

One per blanket tombstone per layer. Payload:

§9.1.3.7 TRAILER (record_type: 0xFF)

Last record. Exactly one. Payload:

§9.1.4 Stream ordering

HEADER                          (exactly one)
LAYER records                   (one per layer, before key data)
For each key in depth-first pre-order of the merged tree:
    KEY record                  (the key object)
    PATH_ENTRY records          (all layers' entries for this key)
    VALUE records               (all layers' values for this key)
    BLANKET_TOMBSTONE records   (all layers' blankets for this key)
    (recurse into children)
TRAILER                         (exactly one)

The merged tree is the union of all layers' namespaces. Depth-first pre-order guarantees that a key's parent is always emitted before the key itself.

HIDDEN path entries. A HIDDEN entry (ChildGUID = all zeros) has no corresponding KEY record — it is a tombstone, not a key. HIDDEN entries are emitted as PATH_ENTRY records under the parent key's section in the stream. They appear alongside any GUID-bearing path entries for the same (parent, child name). No KEY record is emitted for the zero GUID. A HIDDEN entry that masks a path where no real key exists in any layer is still a valid PATH_ENTRY record — it expresses "this layer hides this name" regardless of whether any other layer has a key there.

Cross-layer path dependencies. A path entry's parent GUID may belong to a key that only has path entries in a different layer. The merged tree walk handles this correctly.

§9.1.5 Restore semantics

Restore is a replace operation, not a merge. The target key's entire subtree is removed before the backup contents are written. The entire restore (teardown + rebuild) MUST be wrapped in a single source transaction for atomicity. Sources that do not support transactions MUST NOT be used as restore targets.

0. Begin a transaction on the source (RSI_BEGIN_TRANSACTION). Remove the target key's entire subtree by recursively deleting all descendant path entries, values, blanket tombstones, and key records via RSI operations within the transaction.
1. Read and validate HEADER (magic, minimum reader version).
2. Read LAYER records -- build layer context. If any layer has Precedence > 0 and the caller does not hold SeTcbPrivilege, abort the transaction and return EPERM.
3. For each KEY record in stream order (within the transaction): a. Create the key object in the source via RSI. b. Create PATH_ENTRY records via RSI. c. Create VALUE records via RSI. d. Create BLANKET_TOMBSTONE records via RSI.
4. Read TRAILER -- verify record count and checksum.
5. If checksum fails or GUID collision occurs, abort the transaction (all changes rolled back, including teardown).
6. Commit the transaction.

Depth-first pre-order ensures step 3 never encounters a parent GUID that hasn't been created yet.

ParentGUID validation. LCS MUST validate every PATH_ENTRY record's ParentGUID before issuing RSI_CREATE_ENTRY. The ParentGUID MUST either be the restore target's root GUID or appear in a KEY record already processed in the stream. If a ParentGUID references a GUID outside the backup's key set, the restore MUST be aborted with EINVAL. This prevents a crafted backup from injecting path entries into arbitrary locations in the existing namespace outside the restore subtree.

GUID preservation. The backup's GUIDs are written directly into the target. If those GUIDs already exist elsewhere in the source, restore fails. In practice, restore targets the same subtree the backup was taken from (disaster recovery, rollback, first-boot seed).

All record types use length-prefixed strings (uint32 length + UTF-8 bytes) for variable-length fields, matching the RSI wire format encoding defined in the RSI Wire Format appendix.

The registry spans a trust boundary (kernel ↔ userspace source). Failure semantics MUST be explicit.

§10.1.1 Source crash

When a source process dies (connection closed unexpectedly):

1. Hives marked unavailable. Per-hive status set to Down.
2. Pending requests fail with EIO.
3. Open key fds remain valid. The fd holds a GUID and granted access mask, neither of which depends on the source. Operations requiring source round-trips (reads, writes, enumeration) return EIO while the source is unavailable.
4. Transactions cancelled. All open transactions scoped to that source are implicitly aborted.
5. Watches remain armed. Watch state is kernel-side and unaffected by source availability.

When the source restarts and re-registers:

• Hives marked Active.
• OVERFLOW delivered to every watch on keys in those hives.
• Existing fds resume working without re-opening.
• If a key's GUID no longer exists in the restarted source (e.g., database restored from older backup), the first operation on that fd returns ENOENT.

§10.1.2 Request timeout

If a source does not respond within RequestTimeoutMs (default 30 seconds):

• LCS returns ETIMEDOUT to the caller.
• The source stays alive. A slow response is not a crash.
• When the source eventually responds, LCS processes the response normally (watch events dispatched for any mutations). The original caller is gone, so the response has no recipient.
• Caller responsibility: ETIMEDOUT means "may or may not have completed." Callers that need certainty MUST check state before retrying.

§10.1.3 Transaction timeout

If a transaction's lifetime timer fires:

• The transaction fd is closed (implicit abort).
• RSI_ABORT_TRANSACTION sent to the source.
• If a commit was in-flight and succeeds at the source before the abort takes effect, the writes are durable. The kernel has no transaction fd to deliver the response to. The late commit response is processed through the normal pipeline: watch events are dispatched for any mutations the source applied. Watchers may observe the effects of a timed-out transaction.
• Caller responsibility: transaction timeout means "may or may not have committed." Callers MUST check state before retrying.

§10.1.4 Source errors

Sources return errors from the defined vocabulary. LCS maps them to errnos (see the Source Obligations section for the full error table).

Source-specific error details are not exposed to callers. The errno is the interface.

§10.1.5 Source data validation

LCS validates every response from a source before using it.

Malformed data (structurally valid RSI message, invalid content):

• Request returns EIO to the caller.
• Audit event emitted (source, key GUID, validation failure description).
• Source stays alive. Corruption may be localised.

Malformed protocol (RSI message structurally invalid):

• Treated as a source crash. Connection torn down, hives marked unavailable.

§10.1.6 Fd lifecycle

Key fds and transaction fds are standard Linux file descriptors subject to RLIMIT_NOFILE. No registry-specific fd leak protection exists.

When a process exits, all fds are closed via normal kernel cleanup. Key fds released, watches removed, transactions aborted.

§10.1.7 Layer deletion effects

Deleting a layer removes its path entries and value entries. Effects on live state follow from the data model with no special cases:

• Path entries removed. Keys named only by the deleted layer become orphaned. Existing fds remain valid. Dropped when last fd closes.
• Values surface. Where the deleted layer had the highest-precedence entry, the next layer's value becomes effective.
• Blanket tombstones removed. Values previously masked by the deleted layer's blanket tombstone become visible.
• SDs unchanged. SD modifications are permanent (semantic rule 4).
• Watches notified. Appropriate events generated for all effective state changes.

§10.1.8 Memory bounding

Registry kernel memory is bounded by:

• Watch queues: per-queue max (NotificationQueueSize) × per-process fd limit (RLIMIT_NOFILE).
• Open key state: per-fd overhead (GUID, granted mask, ancestor chain, watch state) × RLIMIT_NOFILE.
• Layer table: bounded by the number of layers (MaxLayersPerValue caps per-value resolution cost).
• Pending RSI requests: bounded by the number of threads blocked on registry syscalls, each with one in-flight request.

No registry-specific global memory cap is required. Standard Linux resource limits provide sufficient protection.

All numeric constants used in the LCS interface. An independent implementer can derive all magic numbers from this page.

§11.1.1 Syscall numbers

§11.1.2 Ioctl definitions

Type byte: 'R' (0x52).

§11.1.2.1 Source registration ioctl (on /dev/pkm_registry fd)

Ioctl number namespaces are per-fd-type. REG_SRC_REGISTER (number 0 on /dev/pkm_registry fds) does not conflict with key fd ioctls (number 0 on key fds) because the kernel dispatches ioctls based on the fd's file_operations, not globally.

§11.1.2.2 Key fd ioctls

§11.1.2.3 Transaction fd ioctls

§11.1.3 Syscall flags

§11.1.3.1 reg_open_key flags

§11.1.3.2 reg_create_key flags

§11.1.3.3 Disposition values

§11.1.4 Access rights

§11.1.4.1 Specific rights (bits 0--15)

§11.1.4.2 Standard rights (bits 16--23)

§11.1.4.3 System rights

§11.1.4.4 Generic mappings

§11.1.5 Value types

§11.1.6 Watch event types

§11.1.7 Watch filter bits

§11.1.8 RSI op codes

§11.1.9 RSI error codes

§11.1.10 RSI registration flags

§11.1.11 Backup record types

§11.1.12 Backup magic

0x50 0x45 0x49 0x4F 0x53 0x52 0x45 0x47
 P    E    I    O    S    R    E    G

Byte-level layouts for all structures crossing the kernel/userspace boundary. All multi-byte integers are little-endian. All structs are packed -- fields are placed at the exact offsets shown with no implicit padding. GUIDs are 16 bytes, stored as raw bytes (not a struct of fields).

An independent implementer can write compatible userspace code from this page.

Strings in ioctl structs are length-delimited, not null-terminated. Each string is referenced by a (len, ptr) pair where len is the byte count and ptr is a userspace pointer. LCS reads exactly len bytes from ptr. Null terminators are neither required nor expected.

§11.2.1 Ioctl argument structs

§11.2.1.1 reg_query_value_args (REG_IOC_QUERY_VALUE)

Total: 56 bytes.

If data_len on input is too small, the ioctl returns ERANGE and sets data_len to the required size. The caller retries with a larger buffer.

§11.2.1.2 reg_set_value_args (REG_IOC_SET_VALUE)

Total: 56 bytes.

§11.2.1.3 reg_delete_value_args (REG_IOC_DELETE_VALUE)

Total: 28 bytes.

§11.2.1.4 reg_blanket_tombstone_args (REG_IOC_BLANKET_TOMBSTONE)

Total: 20 bytes.

§11.2.1.5 reg_query_values_batch_args (REG_IOC_QUERY_VALUES_BATCH)

Total: 20 bytes.

Each value in the buffer is packed as:

Values are packed consecutively with no padding between them. If the buffer is too small, the ioctl returns ERANGE and sets buf_len to the required size.

§11.2.1.6 reg_enum_value_args (REG_IOC_ENUM_VALUES)

Total: 36 bytes.

§11.2.1.7 reg_enum_subkey_args (REG_IOC_ENUM_SUBKEYS)

Total: 36 bytes.

§11.2.1.8 reg_query_key_info_args (REG_IOC_QUERY_KEY_INFO)

Total: 56 bytes.

§11.2.1.9 reg_delete_key_args (REG_IOC_DELETE_KEY)

Total: 16 bytes.

§11.2.1.10 reg_hide_key_args (REG_IOC_HIDE_KEY)

Total: 16 bytes.

§11.2.1.11 reg_get_security_args (REG_IOC_GET_SECURITY)

Total: 16 bytes.

§11.2.1.12 reg_set_security_args (REG_IOC_SET_SECURITY)

Total: 20 bytes.

§11.2.1.13 reg_notify_args (REG_IOC_NOTIFY)

Total: 8 bytes.

§11.2.1.14 reg_backup_args (REG_IOC_BACKUP)

Total: 4 bytes.

§11.2.1.15 reg_restore_args (REG_IOC_RESTORE)

Total: 4 bytes.

§11.2.2 Security information flags

Used in reg_get_security_args and reg_set_security_args:

§11.2.3 Watch event structures

§11.2.3.1 Direct watch event

Minimum size: 8 bytes (no name).

§11.2.3.2 Subtree watch event

Extends the direct event with path components:

path_depth of 0 means the change is on the watched key itself (equivalent to a direct event). Consumers distinguish direct from subtree events by checking whether bytes remain after the name field (using total_len).

§11.2.4 RSI registration struct

§11.2.4.1 reg_src_register_args (REG_SRC_REGISTER ioctl)

Total: 20 bytes.

§11.2.4.2 reg_src_hive_entry

Total: 48 bytes per entry.

Byte-level layouts for all RSI messages over /dev/pkm_registry. All multi-byte integers are little-endian. Strings are UTF-8, length-prefixed with uint32. GUIDs are 16 bytes.

§11.3.1 Common header

Every request begins with:

Total request header: 22 bytes. Payload follows immediately.

Response messages begin with:

Total response header: 14 bytes. Payload follows (status + data).

Every response payload begins with:

Status 0 = success. Non-zero = RSI error code.

§11.3.2 Variable-length encoding

Strings and byte arrays are encoded as:

┌──────────────┬───────────────────┐
│ len (uint32) │ data (len bytes)  │
└──────────────┴───────────────────┘

Arrays of structs are encoded as:

┌───────────────┬─────────┬─────────┬─────┐
│ count (uint32)│ entry_0 │ entry_1 │ ... │
└───────────────┴─────────┴─────────┴─────┘

§11.3.3 Path operations

§11.3.3.1 RSI_LOOKUP (0x01)

Request payload:

Response payload (success):

Followed by entry_count path entries:

Followed by key metadata for each unique GUID:

Per metadata entry:

HIDDEN entries (target_type=1, zero GUID) do not contribute metadata entries. The metadata_count reflects only unique non-zero GUIDs.

When the symlink flag is set, LCS resolves the target by issuing a separate RSI_QUERY_VALUES for the key's default value.

§11.3.3.2 RSI_CREATE_ENTRY (0x02)

Request payload:

Response: status only.

§11.3.3.3 RSI_HIDE_ENTRY (0x03)

Request payload:

Response: status only.

§11.3.3.4 RSI_DELETE_ENTRY (0x04)

Request payload:

Response: status only.

§11.3.3.5 RSI_ENUM_CHILDREN (0x05)

Request payload:

Response: Same format as RSI_LOOKUP but with multiple child names. Encoded as:

Per child:

Per entry within child (same as LOOKUP entries):

Followed by key metadata block (same as LOOKUP).

§11.3.4 Key operations

§11.3.4.1 RSI_CREATE_KEY (0x10)

Request payload:

Response: status only.

§11.3.4.2 RSI_READ_KEY (0x11)

Request payload:

Response payload (success):

§11.3.4.3 RSI_WRITE_KEY (0x12)

Request payload:

Field mask bits:

Only fields with their mask bit set are present in the payload, in bit order.

Response: status only.

§11.3.4.4 RSI_DROP_KEY (0x13)

Request payload:

Response: status only.

§11.3.5 Value operations

§11.3.5.1 RSI_QUERY_VALUES (0x20)

Request payload:

Response payload (success):

Per entry:

Followed by blanket tombstone data:

Per blanket:

§11.3.5.2 RSI_SET_VALUE (0x21)

Request payload:

Response: status only (RSI_CAS_FAILED if condition fails).

§11.3.5.3 RSI_DELETE_VALUE_ENTRY (0x22)

Request payload:

Response: status only.

§11.3.5.4 RSI_SET_BLANKET_TOMBSTONE (0x23)

Request payload:

Response: status only.

§11.3.6 Transaction operations

§11.3.6.1 RSI_BEGIN_TRANSACTION (0x30)

Request payload:

Response: status only.

§11.3.6.2 RSI_COMMIT_TRANSACTION (0x31)

Request payload:

Response: status only.

§11.3.6.3 RSI_ABORT_TRANSACTION (0x32)

Request payload:

Response: status only.

§11.3.7 Layer operations

§11.3.7.1 RSI_DELETE_LAYER (0x50)

Request payload:

Response payload (success):

Per orphaned GUID:

§11.3.8 Maintenance operations

§11.3.8.1 RSI_FLUSH (0x40)

Request payload:

The hive name identifies which hive to flush. This is the only RSI operation that routes by hive name rather than key GUID, because flush is a hive-level operation (WAL checkpoint), not a key-level one.

Response: status only.

Complete reference for all LCS self-configuration parameters. Every parameter lives under Machine\System\Registry\ and follows the self-configuration mechanism described in the Self-Configuration section: compiled-in defaults at boot, hot-swapped via self-watch when registry values are available, validated against defined ranges, invalid values rejected with audit event.

All parameters are REG_DWORD (uint32). All have compiled-in defaults that produce correct behaviour without any registry configuration.

§11.4.1 Timeouts

§11.4.2 Path and naming limits

§11.4.3 Value limits

§11.4.4 Layer limits

§11.4.5 Transaction limits

§11.4.6 Source limits

§11.4.7 Watch limits

§11.4.8 Private hive and layer credential limits

§11.4.9 Notes

• All parameters are read from Machine\System\Registry\ via the self-watch mechanism. Changes take effect for new operations after the self-watch callback completes. In-flight operations use the value active when they started.

• Invalid values (out of range, wrong type) are silently ignored. LCS retains the previous known-good value and emits an audit event.

• Values are never clamped. The registry shows what was written; the audit log shows what LCS is actually using.

• The SD on Machine\System\Registry\ controls who can modify these parameters. By default: SYSTEM and Administrators have KEY_ALL_ACCESS, Authenticated Users have KEY_READ. Domain policy via Group Policy at higher precedence layers provides additional protection.