RegCube — kernel hives and Strategy A (deskgui)

RegCube is the kernel-owned configuration store (string hives/keys). Ring-3 reads and writes through dedicated syscalls; persistence is optional and path-driven.

1. Kernel API

Implemented in src/sys/regcube.rs and exposed via src/kernel/syscalls.rs (numbers in syscalls-reference.md):

  • Get — NUL-terminated hive/key, fills user buffer, returns length or error token.

  • Set — hive/key/value NUL-terminated strings; updates in-memory hive.

  • Flush — serializes to a path (FAT / VFS write).

  • Load — reads file and merges into hives.

Invariant: kernel is authoritative; userland caches are advisory and must follow cache rules below.

2. Strategy A (single façade in deskgui)

Problem it solves: split-brain — some UI code talking to sys_regcube_* directly while other code used a local mock registry, causing inconsistent theme/settings/mixer state.

Rule: under apps/deskgui/src/, all RegCube access for compositor features goes through RegCubeClient (apps/deskgui/src/regcube_client.rs).

CI / hygiene: scripts/check_no_os_registry_deskgui.ps1 fails if os_registry / OSLocalRegistry strings reappear under apps/deskgui/src/.

3. RegCubeClient contract

3.1 Authority

  • Reads: get_string / get_optional / get_f32 consult in-memory cache; on miss, syscall get, then insert into cache on success.

  • Writes: set_string / set_f32 — kernel first (syscall set), then update cache entry so subsequent reads see the same value.

3.2 Invalidation

  • invalidate_hive(hive) — removes all cached keys for that hive without calling the kernel (used after bulk external changes or editor loads).

3.3 Flush / load helpers

The client exposes flush, load, snapshot_for_editor, and small helpers (e.g. mixer launch pulse) — each maps to explicit syscall sequences; read the impl for exact hive names.

4. Ecosystem settings pattern (required)

For control domains (time/display/network/game runtime), RegCube is the persisted state plane in the standard model:

  • p1-<domain>svc daemon owns transitions and background policy

  • <domain>ctl CLI and Settings GUI are user/operator frontends

  • Both frontend paths converge on the same RegCube keys and service behavior

Rule: no domain should keep a hidden second source of truth outside RegCube for persisted policy.

5. Edge cases

Case

Policy

Get failure

Returns default string / None / default float per API; only successful syscall gets cached for string getters.

Concurrent writers

Last writer wins at kernel; cache must be write-through on set to stay aligned.

Very large values

Buffer sizes are fixed in client (256 bytes in syscall_get path) — oversized keys/values truncate or fail; do not store blobs in RegCube.

6. Operational keys in active use

Hive

Key

Used by

HIVE_LOCAL_MACHINE

network/legacy_kernel_driver

Init + networking stack mode selection

HIVE_LOCAL_MACHINE

time/ntp_server

p1-timesvc, timectl

HIVE_LOCAL_MACHINE

time/auto_sync

p1-timesvc, timectl

HIVE_LOCAL_MACHINE

time/sync_interval_sec

p1-timesvc, timectl

HIVE_LOCAL_MACHINE

time/last_sync_status

p1-timesvc, timectl status output

HIVE_LOCAL_MACHINE

time/last_sync_unix

Last successful SNTP epoch

HIVE_LOCAL_MACHINE

time/timezone_id

Local time display policy (settings, timectl, deskgui)

HIVE_LOCAL_MACHINE

time/tz_offset_min

Signed UTC offset minutes for local display

HIVE_LOCAL_MACHINE

region/location

Region profile selection (settings, timectl)

HIVE_LOCAL_MACHINE

region/language

Language preference key for future i18n consumers

HIVE_LOCAL_MACHINE

region/date_format

Date/time formatting preference key

HIVE_LOCAL_MACHINE

display/resolution, display/refresh_hz, display/scale, display/brightness, display/auto_detect, display/last_apply_status

p1-dispsvc, dispctl, settings

7. See also