Peinit

peinit's boot has two phases: a hardcoded bootstrap that brings up the minimum infrastructure, and a registry-driven phase that starts everything else. The boundary between them is registryd. This section defines Phase 1 and the identity model that governs early boot.

§2.1.1 Initramfs contract

peinit assumes the root filesystem is fully assembled, checked, and mountable when it starts. Root storage assembly -- LUKS decryption, LVM activation, RAID array assembly, filesystem checks -- is handled entirely by the initramfs before peinit runs.

The initramfs performs switch_root and transfers control to peinit as PID 1. peinit MUST NOT perform root filesystem assembly, decryption, or repair. These operations require tools and configuration that belong to the initramfs environment.

Non-root storage (data partitions, additional filesystems) is handled by mount pseudo-services in Phase 2.

§2.1.2 Bootstrap identity model

The steady-state identity flow is: peinit requests a token from authd, authd mints the token, peinit installs it on the service process. But authd depends on lpsd, lpsd depends on registryd, and registryd must start before any of them. The bootstrap model resolves this.

Platform services run as SYSTEM. When peinit starts a service during Phase 1 or a platform service during early Phase 2, it MUST clone its own SYSTEM token (S-1-5-18) via kacs_duplicate_token and install the clone on the child process. No authd interaction is needed.

The following services use Identity=SYSTEM:

• registryd -- MUST start before authd exists
• authd -- needs PRIV_TCB and PRIV_CREATE_TOKEN; is the token minter
• lpsd -- MUST start before authd can resolve local identities
• eventd -- starts early, before authd is necessarily available

There is no allowlist restricting which services MAY use Identity=SYSTEM. The security boundary is the registry key SD on Machine\System\Services\ -- an administrator who can create service definitions is trusted to assign any identity.

peinit MUST add a per-service SID to the group list of every cloned SYSTEM token. The SID is derived from the service name using the service SID algorithm defined in the KACS v0.20 specification (SID authority S-1-5-80, sub-authorities from SHA-1 of the UTF-16LE uppercased service name). peinit computes this independently -- no authd involvement is needed. This ensures that platform services are distinguishable to AccessCheck despite all running as SYSTEM.

Once authd and lpsd are running, all subsequent services receive tokens via the normal authd flow. Services with no Identity field default to LocalService -- a well-known principal with minimal privileges. For authd-minted tokens, authd automatically adds a per-service SID to the token's group list.

§2.1.3 Phase 1

Phase 1 is compiled into peinit. It MUST NOT change at runtime and has no registry dependency. Phase 1 performs the minimum operations necessary to prepare the system for Phase 2.

§2.1.3.1 Step 1: Remount root filesystem read-write

The Linux kernel typically mounts the root filesystem read-only. peinit MUST remount it read-write before any other operation. registryd's storage backend requires write access (WAL and shared- memory files) even for read operations.

If the remount fails, peinit MUST enter Recovery mode.

§2.1.3.2 Step 2: Mount virtual filesystems

peinit MUST mount the following virtual filesystems:

The mount set and flags are hardcoded. These filesystems MUST exist before any other process runs.

If any mount fails, peinit MUST enter Recovery mode.

§2.1.3.3 Step 3: Set system clock from hardware RTC

peinit MUST read the hardware RTC and call clock_settime() to initialise the system clock before registryd starts. This ensures timestamps on registry operations, log entries, and the boot attempt counter are meaningful.

§2.1.3.4 Step 4: Start registryd

peinit has a compiled-in service definition for registryd:

peinit MUST:

1. Clone its own SYSTEM token and add the per-service SID for registryd (derived per the KACS v0.20 service SID algorithm).
2. Create registryd's cgroup tree under /sys/fs/cgroup/peinit/.
3. Fork, install the token on the child, and exec /usr/sbin/registryd.
4. Wait for READY=1 via sd_notify with a hardcoded timeout (implementation-defined).

registryd's READY=1 MUST mean "accepting and serving registry requests" -- not merely "process is alive." registryd MUST NOT send READY=1 until its storage backend is open, its schema is validated, and it can handle reads.

After receiving READY=1, peinit MUST perform a probe read: a read of a known registry key to verify the registry is functional. If the probe fails or times out, peinit MUST treat registryd as failed.

If registryd fails to start, its readiness timeout expires, or the probe read fails, peinit MUST enter Recovery mode. There is no Phase 2 without a working registry.

§2.1.3.5 Step 5: Infrastructure setup

After registryd is running, peinit MUST perform the following infrastructure setup before Phase 2 begins:

1. Control socket creation. peinit MUST create its control socket at /run/peinit/control.sock. The socket is used for all runtime commands for the lifetime of the system.
2. JFS device opening. peinit MUST open /dev/jfs and add the fd to its event loop. This enables ad-hoc job submission from services once Phase 2 starts.
3. Loopback interface bring-up. peinit MUST bring up the loopback interface (lo) via a netlink call. Services that bind to 127.0.0.1 (authd, eventd, etc.) require the loopback interface to be operational.

If control socket creation fails, peinit MUST enter Recovery mode. JFS device open failure and loopback bring-up failure MUST be logged as warnings but MUST NOT prevent Phase 2 from starting.

§2.1.4 Phase 1 failure summary

All Phase 1 failures are fatal to boot. Recovery mode is the only option because Phase 2 cannot begin without working infrastructure.

With registryd running, peinit reads the service graph from the registry and boots the system. Phase 2 is entirely registry-driven.

§2.2.1 Step 1: Read service definitions and mount configuration

peinit MUST read all entries under Machine\System\Services\ from the registry. Each key contains a service definition (see the Service Model section). These reads are bounded by LCS's request timeout -- if registryd hangs mid-read, peinit receives ETIMEDOUT and MUST enter Recovery mode.

Only services with a boot trigger are candidates for automatic start. Services with no triggers (demand-only) wait for explicit start commands. Services with Disabled=1 MUST NOT be included in the boot graph. Their definitions are still loaded into peinit's in-memory model for on-demand start via the control interface.

peinit MUST also read mount entries from Machine\System\Boot\Mounts\. Each mount entry generates a pseudo-service named mount:<mountpoint> (e.g., mount:/data).

Mount pseudo-services behave as Oneshot services with RemainAfterExit. The mount operation completes, the pseudo-service stays in the Completed state, and dependents can start. Services that need a mount point declare it as a dependency: Requires = ["mount:/data"].

Mount pseudo-services MUST run fsck on the target device before mounting if the mount configuration specifies it. Root filesystem fsck is handled by the initramfs (see the Bootstrap section), not peinit.

§2.2.2 Step 2: Build and validate the dependency graph

peinit MUST perform a topological sort of all boot-triggered services -- including mount pseudo-services -- and validate the graph before attempting to start anything. The full validation rules are defined in the Dependencies section. The key outcomes:

• Cycle detected: all services in the cycle are marked Failed. If the cycle involves a Critical service, peinit MUST downgrade to Safe mode without rebooting.
• Unresolvable conflict: both services are marked Failed. Same Safe mode escalation if either is Critical.
• Missing Requires dependency: the dependent is marked Failed.
• Validation warnings (e.g., Readiness=Alive with dependents) are logged but do not prevent boot.

Mount pseudo-services participate in the dependency graph. During shutdown, unmount happens after all services that Require the mount have stopped.

§2.2.3 Step 3: Start services in dependency order

peinit MUST walk the dependency graph and start services, parallelising where the graph allows. Services are started up to a configurable concurrency limit:

As each service reaches a satisfied state (Active for Simple, Completed for Oneshot -- both with and without RemainAfterExit), its dependents become eligible and are added to the start queue. A Oneshot without RemainAfterExit transitions Starting -> Completed (releasing dependents) -> Inactive.

The typical Phase 2 boot order, determined by the dependency graph:

1. eudev -- device management. Runs as SYSTEM with RequiredPrivileges stripped to the minimum eudev needs. Starts before authd is available.
2. lpsd -- local identity database. Depends on registryd only. Runs as SYSTEM.
3. authd -- identity authority. Depends on registryd and lpsd. Runs as SYSTEM. Once authd signals readiness, the token minting flow is available.
4. eventd -- logging and audit. Runs as SYSTEM. Services started before eventd log to peinit's pre-eventd buffer.
5. Networking -- network interface configuration. First service to receive a token via authd.
6. Application services -- in dependency order, parallelised where possible.
7. Login services -- started last so the system is fully operational before accepting user sessions.

§2.2.4 Readiness gating

A service's dependents MUST NOT start until the service satisfies its dependents. The satisfaction rules are:

• Simple service: satisfies dependents when it signals READY=1 (Readiness=Notify) or when the process is alive (Readiness=Alive).
• Oneshot service: satisfies dependents when the process exits successfully and the service reaches the Completed state.
• Skipped service: satisfies dependents immediately (the service does not apply to this system).

If a service fails to reach readiness within its StartTimeout:

• Requires dependents: MUST transition to Failed with cause DependencyFailure.
• Wants dependents: MUST start regardless.

§2.2.5 Bootstrap matrix

§2.2.6 Phase 2 failure summary

peinit has three boot modes, forming an escalation path from normal operation to last-resort maintenance.

§2.3.1 Full mode

Full mode is the default. All boot-triggered services start in dependency order as described in the Phase 2 section.

A successful Full boot MUST reset the boot attempt counter to 0. A boot is successful when all Critical services have been Active for a grace period:

§2.3.2 Safe mode

Safe mode starts a reduced set of services. Two categories of services are eligible:

• Critical services (ErrorControl=Critical): MUST start. If a Critical service fails in Safe mode, the normal Critical failure path applies (restart budget, reboot, counter increment, eventual Recovery).
• SafeMode services (SafeMode=1): best-effort. peinit attempts to start them, but if they fail, Safe mode continues without them.

All other services are skipped.

peinit MUST rebuild the dependency graph from scratch using only eligible services (Critical + SafeMode=1). Dependencies on excluded services are dropped -- if service A depends on non- Critical service B, and B is excluded, A's dependency on B does not exist in the Safe mode graph.

A successful Safe boot MUST reset the boot attempt counter to 0.

SafeMode=1 is a filter within the boot-triggered set. A service with no boot trigger does not auto-start in Safe mode regardless of its SafeMode flag.

§2.3.2.1 Entry conditions

• Cycle involving a Critical service at boot: if dependency graph validation detects a cycle that includes a Critical service, peinit MUST downgrade to Safe mode without rebooting. The cycle is a configuration error -- rebooting would hit the same cycle.
• Unresolvable conflict involving a Critical service at boot: if two boot-triggered services conflict and either has ErrorControl=Critical, peinit MUST downgrade to Safe mode without rebooting. Same reasoning as cycles -- the conflict is a configuration error.
• Kernel command line: peios.safemode=1 forces Safe mode.

Safe mode is NOT entered due to a Critical service crash at runtime. That follows the normal path: restart budget, reboot, counter increment, Recovery.

§2.3.3 Recovery mode

Recovery mode is peinit's last resort. There is no TCB guarantee. The administrator gets an unrestricted SYSTEM shell on the console.

§2.3.3.1 Entry conditions

• Boot attempt counter >= N (configurable, default 3). peinit reads the counter from /.peinit/boot-attempts on startup. The counter increments on each boot. Critical service failures (at any time, boot or runtime) trigger sync and reboot, which increments the counter on next boot.
• Kernel command line: peios.recovery=1 forces Recovery regardless of counter.
• Phase 1 registryd failure: if registryd fails during Phase 1, peinit MUST enter Recovery immediately -- no reboot, no counter increment. Without a working registry there is no Phase 2 to boot into.

§2.3.3.2 Behaviour

When entering Recovery mode, peinit MUST:

1. Complete Phase 1 steps 1-3 (remount root read-write, mount virtual filesystems, set clock from RTC) if not already done.
2. Attempt to start registryd. If registryd fails, ignore the failure and continue. Recovery mode MUST deliver a shell regardless of registryd's state.
3. Skip all Phase 2 services.
4. Start a root shell on the console using a compiled-in definition (no registry dependency).
5. Log the failure reason to console.

§2.3.3.3 Offline registry access

If registryd itself caused the recovery, the administrator needs tools that work without registryd. Three recovery paths MUST be available:

1. Inspection: loregd --inspector reads the storage database directly, bypassing LCS, for diagnosis.
2. Backup restore: loregd --recover-from-backup restores from an automatic backup taken on every registryd startup.
3. Database clear: loregd --dangerously-clear-database wipes the registry entirely. Role definitions are the source of truth for service configuration, so a cleared registry is recoverable.

§2.3.3.4 Remote recovery

Recovery mode requires console access (physical, IPMI, or serial). Post-v1 features to address headless servers:

• Registry historical reversion: roll back to a last-known-good registry state from the recovery shell.
• Emergency SSH: a static sshd started without registry involvement, enabling remote access to the recovery environment.

§2.3.4 Boot attempt counter

peinit MUST maintain a boot attempt counter at /.peinit/boot-attempts. The counter is a plain integer stored in a file on the root filesystem (not in the registry, because the registry may be the reason for the failure).

• The counter MUST be incremented at the start of every boot, before Phase 1 begins.
• The counter MUST be reset to 0 on a successful Full or Safe boot (after the grace period).
• If the counter file cannot be written (e.g., disk full), peinit MUST treat the counter as 0 and continue. A write failure MUST NOT trigger Recovery mode.

§2.3.5 Escalation summary

Full boot ---+-- success ----------------> counter reset, operational
             |
             +-- cycle w/ Critical ------> Safe mode (no reboot)
             |
             +-- conflict w/ Critical ---> Safe mode (no reboot)
             |
             +-- Critical failure -------> sync + reboot --+
                                                            |
Safe boot ---+-- success ----------------> counter reset,   |
             |   operational (reduced)                      |
             +-- Critical failure -------> sync + reboot ---+
                                                            |
                              counter increments <----------+
                                         |
                              counter >= N ---------> Recovery mode
                              Phase 1 failure ------> Recovery mode

A service is the primary unit of management in peinit. Every supervised process -- a long-running daemon, a run-to-completion task, a mount operation -- is represented as a service with a definition, a runtime state, and a security policy.

Service definitions are stored in the registry under Machine\System\Services\<name>. The key name is the service name. peinit reads definitions at Phase 2 boot and on demand when an administrator starts a service or issues a reload-config command.

§3.1.1 Service types

peinit supports two service types.

§3.1.1.1 Simple

A long-running daemon. peinit forks, installs a token, and execs the binary. The process IS the service. When it exits, the service has stopped. This is the default type and covers the majority of services (registryd, authd, sshd, application services, etc.).

Readiness: determined by the Readiness field. Notify (default) requires the service to send READY=1 via sd_notify. Alive treats the process as ready as soon as it exists.

Lifecycle: the service transitions to Active on readiness and remains Active until the process exits or is stopped.

§3.1.1.2 Oneshot

A run-to-completion task. peinit forks, installs a token, execs the binary, and waits for it to exit. Success (exit code 0, or any code in SuccessExitCodes) marks the service as completed; failure triggers the failure policy. Used for setup tasks (database initialisation, directory creation, schema migration).

Readiness: the Readiness field is ignored. Oneshot readiness is always "successful exit." A oneshot that exits 0 has succeeded; one that exits non-zero has failed. READY=1 is meaningless for a process whose job is to exit.

Lifecycle differences from Simple:

• Successful exit transitions to Completed. With RemainAfterExit=1, the service remains in Completed. Without RemainAfterExit, the service transitions Completed -> Inactive after dependents are released.
• Non-zero exit transitions to Failed.
• ExecStartPost runs after successful exit, not after a readiness signal. If the oneshot fails, ExecStartPost MUST NOT run.
• StartTimeout covers the entire execution time -- from first pre-hook to process exit.

RemainAfterExit: a Oneshot service with RemainAfterExit=1 stays in the Completed state after its process exits successfully. Without RemainAfterExit, the service passes through Completed (releasing dependents) then transitions to Inactive. RemainAfterExit is useful when the Completed state must persist -- for example, so status queries show the service as finished rather than inactive.

§3.1.2 Triggers

Triggers determine when a service starts. A service's type (Simple/Oneshot) is independent of its triggers. Triggers are stored as a multi_string array on the service definition, each entry in the format type or type:argument.

A service with no triggers is demand-only -- it is started exclusively via explicit control interface commands.

Multiple triggers of the same type are permitted. A service with ["timer:*-*-* 02:00:00", "timer:*-*-* 14:00:00"] runs at 2am and 2pm. The shortcuts daily, weekly, hourly, and monthly are supported.

The trigger model is designed to be extensible. Future trigger types (path, device, event) slot into the same array without schema changes.

§3.1.3 Disabled flag

A service with Disabled=1 MUST NOT be started by any trigger (boot, timer, or future trigger types). The Disabled flag suppresses automatic activation only -- the service MAY still be started explicitly via the control interface.

To prevent a service from being started entirely, modify its ServiceSecurity SD to deny SERVICE_START. This is an access control concern, not a trigger concern.

Enable and disable are registry write operations performed by admin tools, not peinit control commands. peinit picks up Disabled flag changes via registry change notifications or on reload-config.

§3.1.4 Forking daemons

peinit does not support forking daemons. Services that double-fork to "daemonise" themselves are using a workaround for a problem that does not exist when a service manager tracks the process it spawned. peinit tracks the process it forks via pidfd.

If a legacy binary requires double-fork behaviour, the role packager MUST wrap it (e.g., a wrapper script with a --no-daemon flag). This is a packaging concern, not an init concern.

Every service is defined by a registry key under Machine\System\Services\<name>. The key name is the service name. This section defines every field in the service definition and its semantics.

A schema version is stored at Machine\System\Services\SchemaVersion (dword, currently 1). peinit MUST be forward-compatible: unknown registry values MUST be ignored. A newer schema version MUST NOT prevent boot -- peinit logs a warning but continues. The schema evolves additively (new optional fields) without breaking older peinit versions.

§3.2.1 Fields

§3.2.2 Conditions and Asserts

Conditions and Asserts use the same type:argument format and the same check types:

Conditions: if any condition fails, the service is skipped (not failed). A skipped service satisfies its dependents -- it "succeeded" by not needing to run. All entries are AND'd.

Asserts: if any assert fails, the service enters Failed state with cause AssertionError. A failed assert means the service was expected to run but a required precondition is missing. All entries are AND'd.

Conditions are evaluated first. If all conditions pass, asserts are evaluated. Evaluation happens before dependency resolution and pre-exec hooks.

§3.2.3 Command string parsing

Fields that contain executable commands (ExecStartPre, ExecStartPost, ExecReload, HealthCheck) are parsed as follows: whitespace-split into argv, with double-quote grouping for arguments containing spaces. No shell expansion, no variable substitution, no glob expansion. peinit MUST NOT invoke a shell.

If a command requires shell features, a wrapper script MUST be used.

§3.2.4 Registry value types

Service definition fields map to registry value types as follows:

Every service process runs with a KACS token that determines its identity and access rights. peinit is responsible for obtaining or creating the token and installing it on the child process before exec. peinit MUST NOT share its own SYSTEM token directly with any service -- even Identity=SYSTEM services receive a clone.

§3.3.1 Token materialisation

Token materialisation depends on the Identity field:

§3.3.1.1 SYSTEM path

peinit MUST clone its own SYSTEM token via kacs_duplicate_token (or equivalent KACS syscall). The clone is an independent copy -- mutations to the clone (privilege stripping, per-service SID addition) MUST NOT affect peinit's original token.

§3.3.1.2 authd path

For non-SYSTEM identities, peinit connects to authd and requests a token:

1. peinit sends the Identity value to authd verbatim.
2. authd routes to the appropriate identity source:
   • Well-known principals (LocalService, NetworkService): built-in identity with predefined minimal privilege set.
   • Local service accounts: lpsd.
   • Domain accounts: AD connector.
3. The identity source returns principal information (user SID, group SIDs).
4. authd mints a KACS token via kacs_create_token, creates a logon session, and returns the token fd to peinit.

peinit does not know or care whether the identity is local or domain. The routing is authd's responsibility.

§3.3.2 Per-service SID

Every service token MUST carry a per-service SID in its group list. The SID uses authority S-1-5-80 and is derived from the service name using the service SID algorithm defined in the KACS v0.20 specification: SHA-1 of the UTF-16LE uppercased service name, with the 20-byte digest split into five little-endian 32-bit sub-authorities.

• authd-minted tokens: authd adds the per-service SID automatically.
• SYSTEM tokens: peinit adds the per-service SID to the cloned token directly. The SID is a deterministic hash -- no authd involvement is needed.

Per-service SIDs enable fine-grained access control even when services share an identity. Multiple LocalService services each have a unique service SID, so ACLs can target a specific service without requiring a unique principal account.

§3.3.3 Privilege restriction

After token materialisation (both paths), if the service definition includes a RequiredPrivileges field, peinit MUST restrict the token:

1. Read the RequiredPrivileges list from the service definition.
2. Remove every privilege NOT in the list from the token's present bitmask via kacs_restrict_token (or equivalent KACS syscall).

Restriction is purely subtractive -- peinit removes privileges but MUST NOT add them. The enabled, enabled-by-default, and exercised bitmasks are left as the token source (authd or the SYSTEM clone) set them. Enable policy is authd's domain.

If RequiredPrivileges is absent, the token's default privilege set is used unchanged.

§3.3.4 Exec contexts

The same token materialisation rules apply to all exec contexts within a service:

If HookIdentity names SYSTEM, peinit clones its own token for the hook. If HookIdentity names any other principal, peinit requests a token from authd.

Each service has two independent Security Descriptors. This section defines both and the access rights they control.

§3.4.1 Registry key SD

The registry key at Machine\System\Services\<name> has its own SD, inherited from the parent key or set explicitly. This SD controls who can read and write the service definition in the registry. It is enforced by LCS via AccessCheck at key open time.

The registry key SD is not peinit's concern -- it is a registry- level access control mechanism. peinit reads service definitions as SYSTEM, which has full access.

§3.4.2 ServiceSecurity SD

The ServiceSecurity SD controls who can perform runtime operations on the service via peinit's control interface. It is stored as a binary value (ServiceSecurity) on the service's registry key but enforced by peinit, not by LCS.

If ServiceSecurity is absent, the service inherits its parent key's ServiceSecurity. If no ancestor has a ServiceSecurity value, peinit MUST apply a default SD that grants SYSTEM full access and Administrators (S-1-5-32-544) query and stop rights.

§3.4.2.1 Service access rights

Restart requires both SERVICE_STOP and SERVICE_START.

When a client sends a control command via the control socket, peinit MUST:

1. Obtain the caller's token via kacs_open_peer_token.
2. Call AccessCheck with the caller's token against the target service's ServiceSecurity SD.
3. If AccessCheck denies the requested access: return an ACCESS_DENIED error and log the attempt (caller SID, target service, requested right).
4. If AccessCheck grants the requested access: proceed with the command.

§3.4.2.2 ServiceSecurity hot-reload

ServiceSecurity is hot-reloaded. Changes to the ServiceSecurity value in the registry take effect on the next control request without requiring a service restart. peinit MUST pick up ServiceSecurity changes via registry change notifications.

§3.4.3 peinit control SD

System-level operations (shutdown, reload-config) are not per-service -- they are checked against peinit's own SD, stored at Machine\System\Init\ControlSecurity (binary).

peinit MUST load this SD during Phase 2 boot and hot-reload it on registry change notifications.

§3.4.3.1 System access rights

The default ControlSecurity SD MUST grant:

• SYSTEM (S-1-5-18): full access.
• Administrators (S-1-5-32-544): SYSTEM_SHUTDOWN and SYSTEM_RELOAD_CONFIG.

§3.4.4 Independence of SDs

The registry key SD and ServiceSecurity SD are independent. An administrator might have permission to query a service's status (ServiceSecurity grants SERVICE_QUERY_STATUS) but not to read its configuration (registry key SD denies READ). Or vice versa. Both combinations are valid -- runtime control and configuration access are independent concerns.

§3.4.5 The list command

The list command returns all services and their states. peinit MUST filter the result: only services for which the caller has SERVICE_QUERY_STATUS are included. A caller with no service query rights sees an empty list.

peinit operates on snapshots of service definitions, not a live view of the registry. Two generation concepts govern when registry changes take effect.

§3.5.1 Boot generation

At the start of Phase 2, peinit MUST read ALL service definitions from Machine\System\Services\, build the dependency graph, and validate it. The entire boot executes against this snapshot.

Registry changes made during boot (by install scripts, post-hooks, etc.) MUST NOT affect the in-progress boot. This prevents mid-boot graph mutations from creating inconsistent state -- a dependency added while services are Starting would be impossible to honour consistently.

§3.5.2 Activation generation

When peinit starts a specific service (whether at boot or on demand), it MUST snapshot that service's definition. The snapshot governs the entire start lifecycle: pre-exec hooks, token request, readiness timeout, and initial health checks all use the values from the snapshot.

If an administrator changes a field while the service is Starting, the change MUST NOT take effect until the next start.

§3.5.3 Inactive services

A service in Inactive or Failed state has no activation-specific snapshot. When peinit starts such a service, it uses the current version from its in-memory model. This means:

• Creating a new service entry: available after the change notification is processed.
• Changing a timer on an inactive service: takes effect on the next trigger evaluation.
• Changing a dependency on an inactive service: takes effect on the next start.
• Changing a dependency on an active service: takes effect on the next restart.

§3.5.4 Field mutability

Service definition fields have different mutability semantics depending on when they are consumed.

§3.5.4.1 Immutable at runtime

Changes to these fields MUST NOT take effect until the service is restarted:

• ImagePath
• Type
• Identity
• RequiredPrivileges
• ErrorControl

§3.5.4.2 Apply on next start

Changes to these fields take effect on the next service start or explicit graph reload, not while services are running:

• Requires, Wants, BindsTo, Conflicts
• OnFailure
• Conditions, Asserts

§3.5.4.3 Hot-reloaded

Changes to these fields take effect on the next relevant event without requiring a service restart:

• ServiceSecurity (next control request)

§3.5.4.4 Reloadable at runtime

Changes to these fields take effect on the next relevant operation (restart, health check cycle, etc.) without requiring a service restart:

• Arguments, SuccessExitCodes
• All timeout and retry values (StartTimeout, StopTimeout, WatchdogTimeout, RestartDelay, RestartMaxRetries, RestartWindow)
• HealthCheck, HealthCheckInterval, HealthCheckTimeout, HealthCheckRetries
• RestartPolicy
• Environment, WorkingDirectory
• ExecStartPre, ExecStartPost, ExecReload, HookIdentity
• Readiness, NotifyAccess
• LimitNOFILE, LimitCORE
• FdStoreMax
• SafeMode, DisplayName, Description

§3.5.4.5 Trigger changes

Adding or removing triggers and setting the Disabled flag are registry writes performed by admin tools. peinit picks up trigger changes on service restart or when notified via registry change notifications. New timer triggers on inactive services are armed immediately on notification.

§3.5.5 In-memory model

peinit MUST maintain a full in-memory model of all service definitions. The registry is read synchronously only during Phase 2 boot (before meaningful supervision has started) and during reload-config (admin-initiated, bounded). At runtime, peinit operates exclusively on its in-memory model.

Registry change notifications are received as events on a pollable fd. peinit MUST subscribe to Machine\System\Services\ and Machine\System\Init\ at boot. When a notification arrives, peinit processes it in its event loop -- reading the changed key at a time of its choosing, not synchronously at the moment of change.

If the notification queue overflows (bulk admin operations, rapid scripted writes), peinit MUST detect the overflow event and trigger a full reload-config to resynchronise its in-memory model with the registry.

This section defines the exact sequence of operations between "peinit decides to start service X" and "service X's binary is running." Every step is numbered. Failure at any step is handled explicitly.

§4.1.1 Cgroup tree structure

Every service runs in its own cgroup tree:

/sys/fs/cgroup/peinit/<cgroup-id>/         (service root)
/sys/fs/cgroup/peinit/<cgroup-id>/main/    (main process)
/sys/fs/cgroup/peinit/<cgroup-id>/hooks/   (pre/post hooks)
/sys/fs/cgroup/peinit/<cgroup-id>/health/  (health checks)

<cgroup-id> is the service name with / replaced by - (e.g., mount:/data becomes mount:-data). This escaping is internal -- the user-facing name is unchanged.

The sub-cgroup structure satisfies cgroups v2's "no internal processes" constraint (required when controllers are active) and provides clean containment for hooks and health checks.

§4.1.1.1 Cgroup generations

If a service's previous cgroup tree has leaked sub-cgroups (D-state processes that survived SIGKILL -- see the Health Checks section), rmdir on the old tree will fail with EBUSY. In this case, peinit MUST create a generational cgroup tree: /sys/fs/cgroup/peinit/<cgroup-id>.gen<N>/ where N increments on each restart that requires a new tree. Old leaked trees persist until reboot.

§4.1.2 Pre-start evaluation

Before entering the pre-exec sequence, peinit MUST evaluate conditions and asserts while the service is still in Inactive state. This evaluation gates the Inactive → Starting transition.

1. Read the service definition from the in-memory cache (see the Configuration Generations section). This read MUST NOT block on the registry.
2. If the service has Conditions, evaluate all of them. If any condition fails, the service transitions to Skipped and the start is abandoned. Skipped services satisfy their dependents.
3. If all conditions pass and the service has Asserts, evaluate all of them. If any assert fails, the service transitions to Failed with cause AssertionError and the start is abandoned.

Only after conditions and asserts pass does the service transition to Starting and the pre-exec sequence below begins.

§4.1.3 The sequence

The service is in Starting state for the duration of this sequence.

§4.1.3.1 Step 1: Start timeout

peinit MUST start the StartTimeout timer. This timer covers the entire remaining sequence: pre-hooks, fork/exec, and readiness wait. If StartTimeout expires at any point during steps 2-10, peinit MUST abort the start, kill the service's entire cgroup tree, and transition the service to Failed with cause ReadinessTimeout.

§4.1.3.2 Step 2: Create cgroup tree

peinit MUST create the service's cgroup tree (root, main/, hooks/, health/ sub-cgroups).

If cgroup creation fails, no child process exists. peinit MUST transition the service to Failed with cause ParentSetupFailure and return the error (including errno) to the control socket caller.

§4.1.3.3 Step 3: Run pre-exec hooks

If ExecStartPre is configured, peinit MUST run each hook command sequentially. Each hook is forked into the hooks/ sub-cgroup.

For each hook, peinit MUST materialise a token at the point of use: if HookIdentity is set, materialise a token for that identity; otherwise, materialise a token for the service's Identity. Token materialisation follows the rules in the Service Identity section. If token materialisation fails for a hook, the hook fails and the service transitions to Failed with cause PreHookFailure.

If any hook exits non-zero, peinit MUST:

1. Kill the entire service cgroup tree (cleaning up any hook grandchildren).
2. Transition the service to Failed with cause PreHookFailure.

On success of all hooks, peinit MUST kill the hooks/ sub-cgroup to clean up any lingering hook descendants before the main process starts.

§4.1.3.4 Step 4: Materialise service token

peinit MUST materialise the service's main process token as defined in the Service Identity section. For SYSTEM services, clone peinit's token. For all other identities, request a token from authd. Apply RequiredPrivileges restriction if configured.

If token materialisation fails (authd unreachable, identity not found, KACS syscall error), no child process exists. peinit MUST transition the service to Failed with cause ParentSetupFailure.

§4.1.3.5 Step 5: Create error pipe

peinit MUST create a cloexec pipe (pipe2(O_CLOEXEC)). The parent holds the read end; the child will hold the write end. This pipe communicates pre-exec setup errors from the child back to the parent.

If exec succeeds, the write end auto-closes (CLOEXEC) and the parent reads EOF -- meaning setup succeeded. If any setup step fails before exec, the child writes a structured error (step identifier + errno) over the pipe before exiting.

If pipe2 fails, no child process exists. peinit MUST transition the service to Failed with cause ParentSetupFailure.

§4.1.3.6 Step 6: Fork

peinit MUST fork via clone3(CLONE_PIDFD) to atomically obtain a pidfd for the child. There MUST be no window where the child exists without a pidfd.

If clone3 fails, no child process exists. peinit MUST transition the service to Failed with cause ParentSetupFailure. Common causes: EMFILE/ENFILE (fd exhaustion), EAGAIN (PID limit), ENOMEM.

§4.1.3.7 Step 7: Parent post-fork

Immediately after fork, in the parent:

1. Move the child into the main/ sub-cgroup by writing the child PID to main/cgroup.procs. The parent does this -- not the child -- because cgroup writes require SYSTEM privileges that the child's token will not carry after token installation.
2. Close the write end of the error pipe.
3. Read from the error pipe:
   • EOF: exec succeeded. Record the child pidfd as the service's main process.
   • Data: pre-exec setup failed. Parse the step identifier and errno. Log the specific failure. Transition the service to Failed with cause PreExecFailure.

§4.1.3.8 Step 8: Child pre-exec

In the child process. This path MUST be minimal -- no heap allocation, no complex library calls, no logging. Straight-line setup then exec.

1. Close the read end of the error pipe.
2. Install the service's KACS token.
3. Set RLIMIT values (LimitNOFILE, LimitCORE) if configured.
4. Set oom_score_adj:
   • -1000 (OOM-immune) for ErrorControl=Critical services.
   • 0 (default) for all others.
5. Set working directory.
6. Set environment variables (base environment + Environment values from the definition).
7. Set NOTIFY_SOCKET to the notify socket path. This is set unconditionally regardless of the Readiness field -- services use sd_notify for watchdog, STOPPING=1, FDSTORE, and EXTEND_TIMEOUT_USEC in addition to readiness signalling.
8. Inject stored file descriptors if the service has an fd store with entries from a previous run.
9. Exec the binary (ImagePath + Arguments).
10. If exec fails: write error to the pipe, _exit(127).
11. If any step 2-8 fails: write error to the pipe, _exit(126).

§4.1.3.9 Step 9: Wait for readiness

After successful fork and exec:

• Simple, Readiness=Notify: peinit waits for READY=1 via sd_notify. On receipt, the service transitions to Active.
• Simple, Readiness=Alive: the service transitions to Active immediately (the process exists).
• Oneshot: peinit waits for the process to exit. Exit code 0 (or a code in SuccessExitCodes) transitions to Completed. With RemainAfterExit=1 the service remains in Completed; without RemainAfterExit it transitions Completed -> Inactive after dependents are released. Non-zero exit transitions to Failed.

§4.1.3.10 Step 10: Post-readiness

On readiness (Simple) or successful exit (Oneshot):

1. Run ExecStartPost commands. Each hook is forked into the hooks/ sub-cgroup. Hook failure is logged but MUST NOT fail the service.
2. Release dependent services (they become eligible to start).
3. Start the watchdog timer if WatchdogTimeout > 0 (Simple only).
4. Start the health check timer if HealthCheck is set (Simple only).

§4.1.4 Parent-side failure summary

Steps 2, 4, 5, and 6 can fail before any child process exists. In all four cases, peinit handles the failure entirely in the parent:

• Clean up any partially created cgroup tree.
• Transition the service to Failed with cause ParentSetupFailure.
• Return the error (including errno) to the control socket caller.

These failures are system-level resource exhaustion (fd limits, PID limits, memory, cgroup filesystem errors), not service-specific failures.

Active health checks run a command periodically to verify service health beyond "process is alive." This addresses the gap where a service's process is running but is functionally broken (lost database connection, stuck in bad state, returning errors).

§4.2.1 Execution model

The health check command runs with the service's own token. It checks the service's health from the service's perspective.

Each health check invocation runs in an ephemeral health/ sub-cgroup under the service's cgroup tree. It is a child of peinit, not of the service process. When the check completes or times out, peinit MUST kill the entire health/ sub-cgroup -- this cleans up any grandchildren the health check may have spawned.

§4.2.2 Overlap prevention

If a previous health check is still running when the next interval fires, the new check MUST be skipped. A health check that exceeds HealthCheckTimeout triggers a kill of the health/ sub-cgroup and is counted as a failure.

§4.2.3 Failure semantics

HealthCheckRetries consecutive failures mark the service as unhealthy. An unhealthy service is restarted using the same restart policy as a crashed service (RestartPolicy, exponential backoff, and throttling all apply). The health check failure count MUST reset when a check succeeds.

§4.2.4 Flap protection

The restart throttling mechanism (RestartMaxRetries within RestartWindow) protects against health check flapping. A service that repeatedly fails health checks, restarts, passes initial checks, then fails again will eventually exhaust its restart budget and transition to Failed.

This only works if the health check failure cycle is shorter than RestartWindow. The graph validation check (see the Dependencies section) MUST enforce:

HealthCheckRetries * HealthCheckInterval < RestartWindow

Configurations that violate this constraint allow the restart counter to reset between failures, meaning RestartMaxRetries is never reached and the service restarts indefinitely. This is a validation error, not a warning.

§4.2.5 D-state sub-cgroup leak

If a health check process is stuck in uninterruptible kernel sleep (D-state -- typically hung NFS, broken disk controller), SIGKILL on the health/ sub-cgroup will not terminate it. peinit detects this via cgroup.events (populated still 1 after SIGKILL + a post-kill timeout (default 5 seconds)).

Unlike the main process, a stuck health check MUST NOT cause the service to enter the Abandoned state. The health check is a diagnostic probe -- it holds no service resources (ports, file locks, database connections).

Instead, peinit MUST orphan the leaked sub-cgroup:

1. Mark it internally as leaked.
2. Log a warning: "health check sub-cgroup for service X has D-state processes -- likely dead I/O. Sub-cgroup leaked. Underlying I/O problem requires investigation."
3. Continue normal service supervision.

The leaked sub-cgroup remains in the hierarchy until reboot. If the service is later stopped and restarted, peinit creates a generational cgroup tree (see the Pre-Exec Sequence section) because the old tree's rmdir will fail with EBUSY.

The same leak handling applies to hooks/ sub-cgroups -- a pre-exec hook stuck in D-state is orphaned, not elevated to service-level Abandoned.

§4.2.6 Leaked sub-cgroup observability

Leaked sub-cgroups MUST NOT be silent. peinit MUST track leaked sub-cgroups per service and expose them:

• Status queries MUST include a warnings array listing each leak (sub-cgroup path, type, timestamp of detection).
• Start commands on a service with leaked sub-cgroups MUST return a warning in the response: "service has leaked sub-cgroups from a previous generation -- indicates underlying I/O problem requiring investigation."

§4.2.7 Critical service guidance

Every service managed by peinit is in exactly one state at any given time. This section defines the states, their semantics, and every valid transition between them.

§5.1.1 States

§5.1.2 Transition table

Every valid state transition. Transitions not listed here are invalid -- peinit MUST NOT perform them.

§5.1.3 Dependent satisfaction

A service satisfies its dependents only in the following states:

• Active -- running and ready.
• Completed -- Oneshot, finished successfully. Satisfies dependents regardless of RemainAfterExit.
• Skipped -- conditions not met, service does not apply (succeeded by not needing to run).

All other states do not satisfy dependents. A dependent blocked on a Requires dependency that is in any non-satisfying state MUST NOT start.

§5.1.4 Invariants

1. A service MUST be in exactly one state at any given time.
2. Only transitions listed in the transition table are valid.
3. Only peinit MAY transition service runtime state. No external process may directly manipulate a service's state.
4. A service object is securable independently of its process token. The ServiceSecurity SD controls who can manage the service. The service's process token controls what the service can access. These are independent.
5. Readiness is per-start-generation. A READY=1 from a previous incarnation MUST NOT be valid for the current start.

Every state transition carries a cause that records why the transition happened. peinit MUST track both the current state and the cause of the most recent transition. Causes affect restart eligibility, logging detail, OnFailure behaviour, and administrator comprehension.

§5.2.1 Cause taxonomy

§5.2.2 Restart eligibility

Causes are classified into two groups that determine whether the restart policy is consulted.

§5.2.2.1 Restart-eligible causes

For these causes, peinit MUST consult RestartPolicy and the restart budget before deciding the next state. If the policy allows restart and the budget is not exhausted, the service transitions to Starting.

• ProcessCrash
• WatchdogTimeout
• HealthCheckFailure
• ReadinessTimeout
• PreHookFailure
• PreExecFailure
• ParentSetupFailure

§5.2.2.2 Budget-exempt causes

BindsToRecovery transitions Failed → Starting when a bound dependency returns to Active. It is not subject to RestartPolicy evaluation or the restart budget. The service was stopped because its dependency went away, not because it failed on its own.

§5.2.2.3 Never-restart causes

For these causes, peinit MUST NOT consult RestartPolicy. The service transitions directly to Failed (or the cause-specific target state). Retrying cannot help.

• ExplicitStop -- intentional stop.
• ShutdownWave -- system is shutting down.
• ConflictEviction -- the conflict winner would stop it again.
• BindsToPropagation -- bound dependency is down. Recovery is reactive: when the bound service returns to Active, peinit automatically restarts dependents with cause BindsToRecovery.
• ProcessUnkillable -- old cgroup still has live processes.
• RestartBudgetExhausted -- already exhausted.
• ValidationError -- definition is broken.
• CycleDetected -- graph structure is broken.
• DependencyFailure -- dependency is broken.
• AssertionError -- required precondition is missing.
• ConditionSkipped -- not a failure.

§5.2.3 OnFailure

When a service transitions to Failed -- for any cause -- and the service definition includes an OnFailure field, peinit MUST start the designated fallback service. The OnFailure service fires on every transition to Failed regardless of cause. The transition cause is logged, so the OnFailure service or eventd can distinguish causes.

OnFailure is for graceful degradation (e.g., primary web UI fails, start minimal emergency endpoint), not for monitoring or alerting (that is eventd's responsibility).

§5.2.4 Logging contract

Every state transition MUST produce a log entry that includes:

• What failed: service name, operation, specific field if validation.
• Why it failed: cause from the taxonomy above.
• What peinit did: state transition, restart attempt, recovery mode entry.
• What the administrator should do: actionable suggestion where possible (e.g., "check Identity field on service X," "resolve cycle between A, B, C").

Cryptic failure messages are a specification violation. A reboot loop caused by a configuration error with an opaque log message is unacceptable.

§5.3.1 Restart semantics

When a service transitions to Failed with a restart-eligible cause (see the Transition Causes section), peinit evaluates the restart policy:

evaluate_restart(service, cause):
    // Step 1: Check policy.
    if service.restart_policy == Never:
        return STAY_FAILED
    if service.restart_policy == OnFailure:
        if exit_code in service.success_exit_codes:
            return STAY_FAILED
    // restart_policy == Always falls through unconditionally.

    // Step 2: Check budget.
    recent_restarts = count restarts within service.restart_window
    if recent_restarts >= service.restart_max_retries:
        service.cause = RestartBudgetExhausted
        if service.error_control == Critical:
            sync filesystems and reboot
        // Otherwise: service remains in Failed state.
        return STAY_FAILED

    // Step 3: Compute delay.
    delay = service.restart_delay * (2 ^ consecutive_failures)
    delay = min(delay, 60)

    // Step 4: Schedule restart.
    return RESTART_AFTER(delay)

§5.3.1.1 Policy values

For Oneshot services with RestartPolicy=Always, a successful exit (code 0 or SuccessExitCodes match) is NOT restart-eligible. RestartPolicy governs the response to failures. A successful Oneshot exit transitions to Completed (then Inactive if no RemainAfterExit) regardless of RestartPolicy. Only non-zero exits trigger the restart evaluation. Timer triggers are the mechanism for re-running a Oneshot on a schedule.

§5.3.1.2 Exponential backoff

The delay before each restart attempt doubles on each consecutive failure, starting from RestartDelay (default 1 second) and capped at 60 seconds. The consecutive failure counter resets when the service stays healthy for RestartWindow seconds.

§5.3.1.3 Budget exhaustion

If RestartMaxRetries restarts occur within RestartWindow seconds, the service transitions to Failed with cause RestartBudgetExhausted. peinit MUST then apply the service's ErrorControl level:

• Normal: service remains in Failed state.
• Critical: peinit syncs filesystems and reboots.

§5.3.1.4 Budget reset

If a restarted service stays in the Active state for at least RestartWindow seconds without failing, the restart counter MUST reset to zero. This means a service that crashes once every few minutes with a 120-second RestartWindow never exhausts its budget -- each crash is treated as a fresh failure.

§5.3.2 Reload semantics

Reload tells a service to re-read its configuration without restarting. peinit sends the reload command (ExecReload or SIGHUP) and transitions the service to the Reloading state.

§5.3.2.1 Reload lifecycle

evaluate_reload(service):
    // Step 1: Send reload.
    if service.exec_reload is not null:
        if exec_reload starts with "signal:":
            send the named signal to the main process
        else:
            fork and exec the reload command
    else:
        send SIGHUP to the main process

    // Step 2: Enter Reloading state.
    service.state = Reloading
    start detection_window timer (2 seconds)

    // Step 3: Wait for protocol detection.
    // Three outcomes:

    // 3a: RELOADING=1 arrives within detection window.
    //     Service speaks the reload protocol.
    //     Extend wait up to StartTimeout for READY=1.
    on RELOADING=1 within detection_window:
        cancel detection_window
        start extended_wait timer (StartTimeout)

    // 3b: READY=1 arrives at any point during Reloading.
    //     Reload complete. Transition to Active.
    on READY=1:
        service.state = Active
        return "confirmed"

    // 3c: Detection window expires with no RELOADING=1.
    //     Service does not speak the protocol.
    //     Assume reload was instant. Transition to Active.
    on detection_window expired:
        service.state = Active
        return "advisory"

    // 3d: Extended wait expires without READY=1.
    //     Service signalled RELOADING=1 but never completed.
    //     Transition to Active with a warning.
    on extended_wait expired:
        log warning: "service signalled RELOADING=1 but
                      never completed reload"
        service.state = Active
        return "advisory"

The detection window duration (2 seconds) is fixed and is not configurable via the registry.

§5.3.2.2 Auto-detection

The reload protocol is auto-detecting -- no per-service configuration is needed. Services that implement sd_notify reload signalling (RELOADING=1 followed by READY=1) get proper lifecycle tracking. Services that do not get a brief Reloading state that auto-resolves after the detection window.

Reload MUST never get stuck. Every path has a timeout.

§5.3.2.3 Process crash during reload

If the service's main process exits while in the Reloading state, peinit MUST treat it as a ProcessCrash. The restart policy is consulted:

• If RestartPolicy allows restart and the budget is not exhausted, the service transitions Reloading → Starting (restart).
• If RestartPolicy does not allow restart or the budget is exhausted, the service transitions Reloading → Failed.

The reload detection window and extended wait timers are cancelled on process exit.

§5.3.2.4 Reload during stop

If a stop command arrives while a service is in the Reloading state, peinit MUST cancel the reload immediately -- send SIGTERM without waiting for the detection window or extended wait to expire. The service transitions to Stopping.

§5.3.2.5 Wait semantics

The control socket reload command returns immediately by default (wait defaults to false for reload, unlike other lifecycle commands). If wait=true, the connection stays open until the Reloading state resolves. The response includes:

• "mode": "confirmed" -- if READY=1 was received.
• "mode": "advisory" -- if the detection window expired without RELOADING=1, or if the extended wait expired without READY=1.

§5.3.3 Runtime watchdog timeout update

A service MAY update its watchdog interval at runtime by sending WATCHDOG_USEC=<value> via sd_notify.

When peinit receives a WATCHDOG_USEC message:

1. Sender authentication MUST be performed (see the Notify socket section in the Control Interface).
2. The value MUST be parsed as an unsigned integer representing microseconds.
3. If the value is greater than 0, peinit MUST update the service's watchdog interval to the specified value. The current watchdog timer MUST be re-armed immediately with the new interval -- the previous timer is cancelled and a fresh timer starts from the moment of receipt.
4. If the value is 0, peinit MUST disable the watchdog for the service entirely. This is equivalent to WatchdogTimeout=0 in the schema -- no further keepalive pings are expected.

The runtime value does NOT persist across restarts. When a service restarts, the watchdog interval reverts to the schema's WatchdogTimeout value (converted to microseconds). If WatchdogTimeout is 0, the watchdog starts disabled regardless of any runtime update from the previous incarnation.

§5.3.4 Timeout extension

A service MAY request additional time during a start, stop, or reload transition by sending EXTEND_TIMEOUT_USEC=<value> via sd_notify.

When peinit receives an EXTEND_TIMEOUT_USEC message during an active transition (the service is in Starting, Stopping, or Reloading state):

1. Sender authentication MUST be performed.
2. The value MUST be parsed as an unsigned integer representing microseconds.
3. peinit MUST reset the current phase's timeout to expire <value> microseconds from now. The extension is not additive -- each EXTEND_TIMEOUT_USEC message replaces the previous timeout deadline entirely.
4. The service MAY send EXTEND_TIMEOUT_USEC repeatedly. Each message resets the deadline.

§5.3.4.1 Extension caps

The extended timeout MUST NOT exceed the per-service timeout for the current phase multiplied by 4:

If <value> would push the deadline beyond the cap, peinit MUST clamp the deadline to the cap. The message is not rejected -- the timeout is set to the maximum permissible value.

During shutdown, an additional global cap applies: the extended deadline MUST NOT exceed the remaining time in the global ShutdownTimeout. If both caps apply, the stricter (smaller) cap wins.

§5.3.4.2 Outside transitions

If EXTEND_TIMEOUT_USEC is received while the service is in a non-transitional state (Active, Completed, Failed, etc.), peinit MUST ignore the message. There is no timeout to extend.

peinit supports four dependency relationship types. Each type defines how two services interact during start, stop, and failure scenarios.

§6.1.1 Requires

A hard dependency. If service A Requires service B:

Start: B MUST satisfy A's dependency (reach a satisfying state) before A may start. If B is not yet started, peinit MUST start B with transition cause DependencyStart. If B enters Failed, A MUST transition to Failed with cause DependencyFailure without attempting to start.

Stop (explicit): stopping B does not automatically stop A. A continues running. This is a start-ordering constraint, not a runtime coupling.

Failure (runtime): if B crashes at runtime while A is Active, A is NOT affected (Requires is not BindsTo). A continues running. B's restart policy handles B's recovery independently.

Missing target: if B does not exist (no service definition in the registry), A MUST transition to Failed with cause DependencyFailure. Missing Requires targets are detected at graph validation time.

§6.1.2 Wants

A soft dependency. If service A Wants service B:

Start: peinit starts B before A (with transition cause DependencyStart) if B exists and is not Disabled. If B fails to start or does not exist, A starts anyway.

Stop: no effect. A and B are independent at runtime.

Failure: no effect. B's failure does not propagate to A.

Wants is for best-effort ordering -- "start this first if you can, but I'll work without it."

§6.1.3 BindsTo

A runtime coupling. If service A BindsTo service B:

Start: identical to Requires -- B MUST satisfy before A starts. If B is not yet started, peinit starts B with transition cause DependencyStart.

Stop: if B stops (for any reason -- explicit stop, conflict, crash, shutdown), A MUST stop as well. peinit transitions A to Stopping with cause BindsToPropagation.

Recovery: when B returns to Active after a failure, peinit MUST automatically restart any service that is in Failed state with cause BindsToPropagation from B's stop. This is reactive, not polled -- peinit watches B's state transitions. BindsTo recovery restarts MUST NOT consume the restart budget -- the dependent did not fail on its own, it was stopped because its binding target stopped.

BindsTo implies Requires. A service definition MAY list both for clarity, but BindsTo alone is sufficient. If a service lists both BindsTo and Requires for the same target, the BindsTo semantics apply.

§6.1.4 Conflicts

Mutual exclusion. If service A Conflicts with service B:

Start A while B is Active: peinit MUST create a stop operation for B (source: ConflictResolution) and transition B to Stopping with cause ConflictEviction before starting A. If B refuses to stop within its StopTimeout, SIGKILL escalation applies.

Start B while A is Active: peinit MUST create a stop operation for A (source: ConflictResolution) and transition A to Stopping with cause ConflictEviction before starting B.

Conflicts are symmetric. If A declares Conflicts = ["B"], then starting either one stops the other. B does not need to declare the conflict reciprocally -- peinit MUST enforce the relationship regardless of which side declared it.

Both started simultaneously: if the graph contains both A and B as boot-triggered services and they conflict, graph validation detects this as an unresolvable conflict. Both services are marked Failed with cause ValidationError.

§6.1.5 Implicit ordering

Dependencies imply start ordering but not stop ordering (except BindsTo). peinit starts dependencies before dependents. During shutdown, peinit reverses the graph and stops dependents before dependencies (see the Shutdown section). This reversal is derived from the same graph, not from a separate stop-ordering configuration.

§6.1.6 Self-references

A service MUST NOT declare itself in any dependency field. peinit MUST reject self-referential dependencies at graph validation time as a CycleDetected failure.

§6.2.1 Validation

peinit MUST validate the dependency graph before executing it. The graph is built from all boot-triggered services (during boot) or from a specific service's transitive closure (on demand start). Validation runs once per graph build. It is not incremental.

§6.2.1.1 Cycle detection

peinit MUST perform a topological sort of the graph. If the sort fails, a cycle exists.

detect_cycles(graph) -> list of cycles:
    // Standard DFS-based cycle detection.
    // Returns all cycles, not just the first.
    for each unvisited node in graph:
        dfs(node, visited=[], stack=[])

    // Each cycle is a list of service names forming the loop.

All services in a detected cycle MUST be marked Failed with cause CycleDetected. peinit MUST log the full cycle path (e.g., "dependency cycle: A -> B -> C -> A") so the administrator can identify and break the cycle.

If any service in the cycle has ErrorControl=Critical, peinit MUST downgrade to Safe mode (see the Boot Modes section). The cycle is a configuration error -- rebooting would hit the same cycle. Safe mode rebuilds the graph with a reduced service set, potentially excluding the cycle participants.

§6.2.1.2 Missing dependency targets

For each Requires entry, the target MUST exist as a service definition. If the target does not exist:

• The dependent is marked Failed with cause DependencyFailure.
• peinit logs: "service X requires Y, but Y is not defined."

For Wants entries, missing targets are silently dropped -- the entry is ignored.

For BindsTo entries, missing targets are treated as missing Requires (Failed with DependencyFailure).

For Conflicts entries, missing targets are silently dropped -- there is nothing to conflict with.

§6.2.1.3 Unresolvable conflicts

If two boot-triggered services conflict with each other, graph validation detects this as unresolvable. Both MUST be marked Failed with cause ValidationError. If either is Critical, Safe mode applies.

§6.2.1.4 Validation warnings

The following conditions are logged as warnings but do not prevent boot:

• A service uses Readiness=Alive and has dependents that use it as a Requires target. Alive readiness provides no guarantee that the service is functional before dependents start.

§6.2.1.5 Validation errors

The following conditions are validation errors. The service MUST be marked Failed with cause ValidationError:

• A service has HealthCheck configured with timing parameters that violate the flap protection constraint (HealthCheckRetries * HealthCheckInterval < RestartWindow). See the Health Checks section.

§6.2.2 Graph execution

§6.2.2.1 Parallel start

After validation, peinit executes the graph by starting services whose dependencies are all satisfied. Multiple services can start concurrently up to MaxParallelStarts.

execute_graph(graph, max_parallel):
    ready_queue = services with no unsatisfied dependencies
    in_flight = 0

    while ready_queue is not empty or in_flight > 0:
        // Start eligible services up to concurrency limit.
        while ready_queue is not empty and in_flight < max_parallel:
            service = ready_queue.dequeue()
            begin_start(service)
            in_flight += 1

        // Wait for any in-flight service to change state.
        event = wait_for_event()

        match event:
            ServiceSatisfied(s):
                in_flight -= 1
                for each dependent of s:
                    if all dependencies of dependent are satisfied:
                        ready_queue.enqueue(dependent)

            ServiceFailed(s):
                in_flight -= 1
                propagate_failure(s)
                // Failed service's Requires dependents also fail.
                // Wants dependents are unaffected.

§6.2.2.2 Failure propagation

When a service enters Failed during graph execution:

1. All services that Requires the failed service MUST transition to Failed with cause DependencyFailure.
2. All services that Wants the failed service are unaffected -- they start normally.
3. Failure propagation is transitive. If A requires B and B requires C, and C fails, then B fails (DependencyFailure), then A fails (DependencyFailure).

propagate_failure(failed_service):
    for each service that Requires failed_service:
        if service.state == Starting or service is queued:
            service.state = Failed
            service.cause = DependencyFailure
            propagate_failure(service)  // transitive

§6.2.2.3 On-demand start

When a service is started explicitly (not at boot), peinit MUST resolve its transitive dependencies:

1. Collect all transitive Requires and BindsTo dependencies.
2. Collect all transitive Wants dependencies (best-effort).
3. Validate the sub-graph (cycle detection, missing targets).
4. Resolve Conflicts (stop conflicting services).
5. Start the sub-graph using the same parallel execution algorithm. Dependencies started as part of resolution use transition cause DependencyStart (operation source: DependencyPropagation).

Services already in a satisfying state (Active, Completed, Skipped) do not need to be restarted -- their dependency is already met.

§6.2.3 Shutdown ordering

Shutdown reverses the dependency graph. Services that have no dependents stop first; services that others depend on stop last. The full shutdown sequence is defined in the Shutdown section. The dependency graph provides the ordering:

shutdown_order(graph) -> ordered list:
    // Reverse topological sort.
    // Services with no dependents first.
    // Services with the most transitive dependents last.

The last services to stop are the TCB services that everything depends on: eventd, authd, lpsd, and registryd (in that order). registryd is the very last service stopped, mirroring its position as the very first service started.

A job is a single supervised process execution. Every time peinit forks a process -- starting a service's main binary, running a pre-exec hook, executing a health check, or handling an ad-hoc run request -- that execution is a job with a GUID, lifecycle tracking, and log correlation.

Jobs are the observable unit of "what actually ran." Services are definitions that encode identity, policy, and configuration. Jobs are execution instances. A service restart creates a new job. Job history is visible via eventd.

§7.1.1 Lifecycle

Created --> Running --> Completed
                         |
                         +--> Failed
                         |
                         +--> Abandoned

Job states are simpler than service states. A service has Starting, Active, Stopping, Reloading, etc. because those represent policy. A job tracks a process: it is running, or it finished, or it is stuck.

§7.1.2 Fields

Job {
    id:             GUID        // unique identifier
    service:        string?     // parent service name (null for ad-hoc)
    type:           enum        // ServiceMain, PreExecHook,
                                // PostExecHook, HealthCheck, AdHoc
    state:          enum        // Created, Running, Completed,
                                // Failed, Abandoned
    pid:            pid_t?      // main process PID (null until forked)
    pidfd:          fd?         // pidfd for race-free tracking
    token_summary:  object      // identity (SID, groups, privileges)
    image_path:     string      // binary that was exec'd
    arguments:      string[]    // argv
    created_at:     timestamp   // when the job object was created
    started_at:     timestamp?  // when the process was forked
    ended_at:       timestamp?  // when the process exited
    exit_code:      int?        // exit code (null if signal death)
    exit_signal:    int?        // signal (null if clean exit)
    failure_cause:  string?     // structured cause
    cgroup_id:      string      // cgroup path
    cgroup_gen:     int         // cgroup generation number
    operation_id:   GUID?       // the operation that created this
                                // job (null for ad-hoc jobs)
}

The id MUST be assigned before fork. The pid and pidfd are populated at fork time. The ended_at, exit_code, and exit_signal are populated when the process exits.

§7.1.3 Job types

§7.1.3.1 ServiceMain

The main process of a service. Created when a start operation executes the fork/exec sequence. The service tracks its current ServiceMain job GUID. On restart, a new job is created and the service's job GUID updates.

§7.1.3.2 PreExecHook

A pre-exec hook command (ExecStartPre). Each hook invocation is a separate job. Hook jobs run in the hooks/ sub-cgroup.

§7.1.3.3 PostExecHook

A post-exec hook command (ExecStartPost). Each hook invocation is a separate job. Hook jobs run in the hooks/ sub-cgroup.

§7.1.3.4 HealthCheck

A periodic health check invocation. Each health check run is a separate job. Health check jobs run in the health/ sub-cgroup.

§7.1.3.5 AdHoc

An arbitrary process submitted via JFS. Not associated with a persistent service definition. Runs once, reports result. See the Ad-Hoc Jobs section.

§7.1.4 Relationship to services

A service is a long-lived definition with policy. A job is a short-lived process execution.

• A service tracks its current job GUID. Status queries include it.
• When a service restarts, a new job is created. The old job's data was already emitted to eventd.
• Job history for a service is queryable via eventd.

§7.1.4.1 Ownership

§7.1.5 Retention

peinit tracks active jobs in memory. When a job reaches a terminal state (Completed, Failed, Abandoned), peinit MUST emit a structured event to eventd containing the full job record, then drop the job from memory.

peinit does not maintain job history. eventd is the historian.

§7.1.6 eventd integration

peinit MUST emit structured events to eventd at each job lifecycle transition:

job.created -- job object created. Includes job_id, service name, type, image_path, identity, operation_id.

job.started -- process forked. Includes job_id, pid, cgroup path.

job.ended -- process exited or was killed. Includes job_id, final state, exit_code or exit_signal, duration, failure_cause.

All stdout/stderr from a job's process MUST be tagged with the job GUID when forwarded to eventd. This allows queries like "show me logs for job X" to return exactly the output from that execution, not interleaved with previous or subsequent runs.

Ad-hoc jobs are arbitrary supervised processes submitted by services on behalf of their clients. They are not associated with a persistent service definition. They run once, report their result, and are cleaned up.

§7.2.1 The delegation problem

When a service (e.g., PAC) wants peinit to run a process on behalf of a user, it faces a delegation problem. The service has impersonated the user's token, but KACS prevents forwarding that token over IPC without Delegation-level impersonation. Fork inheritance works (the kernel copies the token naturally), but then the service must supervise the process itself -- defeating the purpose of centralised job management.

§7.2.2 JFS consumption protocol

JFS (Job Forwarding Subsystem) solves this problem at the kernel level. JFS is a PKM subsystem that captures the caller's effective KACS token and delivers it to peinit via /dev/jfs.

peinit MUST open /dev/jfs during Phase 1 infrastructure setup (after /dev is mounted) and add the fd to its event loop. When a JFS request arrives:

handle_jfs_request(request):
    // Step 1: Read the request.
    (job_definition, token_fd) = read from /dev/jfs

    // Step 2: Validate the request.
    if job_definition.image_path does not exist:
        write error to /dev/jfs  // unblocks caller
        return
    // Validate arguments, working directory, etc.

    // Step 3: Create job object.
    job = Job {
        id: generate_guid(),
        service: null,   // ad-hoc, no parent service
        type: AdHoc,
        state: Created,
        token_summary: summarise(token_fd),
        image_path: job_definition.image_path,
        arguments: job_definition.arguments,
        created_at: now(),
        operation_id: null,
    }

    // Step 4: Respond to caller.
    write job.id to /dev/jfs  // unblocks caller's syscall

    // Step 5: Execute.
    fork, install token_fd on child, exec
    // Normal supervision: cgroup, log routing, exit tracking.

    // Step 6: Emit lifecycle events.
    emit job.created, job.started, job.ended to eventd

If nothing has /dev/jfs open, the caller's syscall returns ENODEV. JFS is a generic secure forwarding primitive -- peinit happens to be the consumer.

§7.2.3 Ad-hoc job definition

The JFS request contains a job definition with a subset of service definition fields:

The following service-level fields are NOT available for ad-hoc jobs. These are policy concerns that belong to persistent service definitions:

• RestartPolicy, RestartDelay, RestartMaxRetries, RestartWindow
• Requires, Wants, BindsTo, Conflicts
• HealthCheck, WatchdogTimeout
• ErrorControl, SafeMode
• Triggers

§7.2.4 Identity

The job runs with the token captured by JFS -- the caller's effective identity at the time of the syscall. If the caller is impersonating a user, the job runs as that user. If the caller is using its own primary token, the job runs as the caller.

No identity field is accepted in the ad-hoc job definition. The caller MUST NOT name an arbitrary identity -- the caller can only pass through its own (possibly impersonated) token. This prevents escalation: a service cannot create jobs with identities it does not already possess.

§7.2.5 Lifecycle

Ad-hoc jobs have a simpler lifecycle than service jobs:

1. Process is forked with the JFS-provided token.
2. Process runs in a dedicated cgroup under /sys/fs/cgroup/peinit/ (cgroup-id derived from the job GUID).
3. stdout/stderr routed to eventd, tagged with job GUID.
4. On exit: emit job.ended event, clean up cgroup, drop job from memory.
5. No restart. No dependencies. No health checks.

If the process exceeds its Timeout, peinit MUST send SIGTERM, wait the schema default StopTimeout (10 seconds), then SIGKILL. The same escalation as service stops.

§7.2.6 Ad-hoc jobs and operations

Ad-hoc jobs bypass the operations model entirely. The JFS request creates a job directly -- there is no "start" operation for an ad-hoc job because there is no service to start. The job IS the entire lifecycle.

Admin --> start command --> Operation --> peinit forks --> Job
PAC   --> JFS request   -->              peinit forks --> Job
Timer --> timerfd fires  --> Operation --> peinit forks --> Job

An operation is a first-class object representing a requested state machine action on a service. Instead of control commands directly mutating service state, every command creates an operation that is validated, queued, and executed by peinit's event loop.

Operations exist because peinit handles concurrent callers (admin tools, remote SCM, PAC, automated triggers). Without operations, concurrent commands collide with implementation-defined behaviour. With operations, conflict resolution is explicit and observable.

§8.1.1 Lifecycle

Pending --> Running --> Completed
  |                      |
  +--> Merged            +--> Failed
  |                      |
  +--> Cancelled         +--> Aborted

Cancelled and Aborted are the same concept (terminated before completion) at different lifecycle points. Cancelled = never ran. Aborted = was running. The cause (admin action, conflict supersession) is a property of the event, not the state.

§8.1.2 Fields

Operation {
    id:           GUID        // unique identifier
    type:         enum        // Start, Stop, Restart, Reload, Reset
    service:      string      // target service name
    state:        enum        // Pending, Running, Completed, Failed,
                              // Merged, Cancelled, Aborted
    created_at:   timestamp   // when the operation was created
    started_at:   timestamp?  // when execution began
    completed_at: timestamp?  // when terminal state was reached
    source:       enum        // Admin, DependencyPropagation,
                              // RestartPolicy, Timer,
                              // BindsToRecovery, ConflictResolution
    caller:       token_summary?  // caller identity (admin-initiated)
    result:       string?     // human-readable result or error
    merged_into:  GUID?       // if Merged, the target operation
}

§8.1.3 Operation types

§8.1.3.1 Start

Creates a job for the target service. If the service has unsatisfied dependencies, start operations are created for each dependency (source: DependencyPropagation). The operation completes when the service reaches Active (Simple) or Completed/Inactive (Oneshot).

§8.1.3.2 Stop

Sends SIGTERM, starts StopTimeout, escalates to SIGKILL. The operation completes when the service reaches Inactive (clean stop) or Failed (conflict eviction, BindsTo propagation).

§8.1.3.3 Restart

A Stop followed by a Start. Implemented as a single operation -- peinit stops the service then starts it, tracking both phases under one operation GUID. If the service has no running process (Inactive, Completed, Failed, Skipped), the stop phase is skipped and peinit proceeds directly to the start phase. The operation type remains Restart for observability. The operation completes when the service reaches Active after the restart.

§8.1.3.4 Reload

Sends the ExecReload command or signal (see the Restart and Reload section). The operation completes when the reload resolves. Unlike other operations, reload defaults to wait=false -- the caller gets the operation GUID immediately.

§8.1.3.5 Reset

Clears Failed, Abandoned, or Skipped state. Transitions the service to Inactive. Synchronous -- completes immediately.

§8.1.4 Timeout

Operations inherit their target service's StartTimeout or StopTimeout as a maximum lifetime. The timeout clock starts at operation creation (including queue time), not at execution. From the caller's perspective, they have been waiting since they sent the command.

§8.1.5 Retention

peinit retains operation objects in memory while they are Pending or Running. Terminal operations (Completed, Failed, Cancelled, Merged, Aborted) are emitted to eventd as structured events and dropped from memory after a grace period (default 60 seconds -- long enough for a polling client to retrieve the result).

peinit MUST NOT maintain operation history. eventd is the historian.

§8.1.6 eventd integration

peinit MUST emit a structured event at each operation lifecycle transition:

• operation.requested -- operation created. Includes operation_id, type, service, source, caller.
• operation.started -- execution began (Pending -> Running).
• operation.completed -- succeeded. Includes duration, result.
• operation.failed -- did not achieve its goal. Includes failure reason, duration.
• operation.cancelled -- superseded or explicitly cancelled.
• operation.merged -- merged into an existing operation. Includes merged_into GUID.
• operation.aborted -- was running, interrupted.

§8.1.7 Control protocol integration

Every control command returns an operation GUID:

{"status": "ok", "operation_id": "a1b2c3d4-..."}

Callers can poll for completion via the operation-status command:

{"command": "operation-status", "operation_id": "a1b2c3d4-..."}

With wait=true, the control socket connection stays open until the operation reaches a terminal state.

When a new operation is requested and an existing operation for the same service is Pending or Running, peinit MUST apply the conflict resolution rules defined in this section.

§8.2.1 Same-type merging

If the new operation has the same type as the existing operation, peinit MUST merge them. The new caller receives the existing operation's GUID. From the caller's perspective, their request is in progress.

Restart is not mergeable -- a new restart while one is in progress is queued (see cross-type rules below).

§8.2.2 Cross-type conflicts

§8.2.3 Resolution principles

1. Stop wins over start. An explicit stop always takes priority. The admin said stop, so stop. A queued start can follow after.
2. Later operations supersede earlier ones. If an admin sends start then immediately sends stop, the stop wins and the start is cancelled.
3. Merging is transparent. The caller of a merged operation receives the original operation's GUID. They do not know or care that their request merged.

§8.2.4 Dependency propagation

When a start operation executes and the target service has unsatisfied dependencies, peinit MUST create start operations for those dependencies:

• Requires dependencies: start operations with source DependencyPropagation. If any dependency's start operation fails, the parent operation fails with result DependencyFailure.
• Wants dependencies: start operations with source DependencyPropagation. If a Wants dependency's start operation fails, the parent operation continues.
• BindsTo recovery: when a bound service returns to Active, peinit MUST create start operations (source: BindsToRecovery) for any dependents that are Failed with cause BindsToPropagation.

Dependency-created operations follow the same conflict resolution rules as admin-created operations. If a dependency is already starting (due to another service also depending on it), the operations merge.

§8.2.5 Restart policy integration

When a service transitions to Failed with a restart-eligible cause (see the Transition Causes section), peinit MUST create a start operation with source RestartPolicy after the configured RestartDelay. This operation goes through normal validation and conflict resolution -- if an admin has already sent a stop or the restart budget is exhausted, the operation is rejected.

BindsTo recovery restarts (source: BindsToRecovery) are NOT subject to the restart budget. They are created when a bound dependency returns to Active, not in response to a service failure. See the Dependency Relationships section.

§8.2.6 Timer integration

When a timerfd fires, peinit creates operations based on the service's current state:

The catch-up mechanism for Oneshot services creates a start operation when the current execution completes. Multiple missed firings collapse into one pending run.

Timer-created operations follow normal conflict resolution.

§8.2.7 Bulk operations

Shutdown and boot are system lifecycle events, not operations. They produce operations (stop/start for individual services) but are not operations themselves. There is no "shutdown operation" -- shutdown is a mode that peinit enters, which then generates per-service stop operations.

Timers are a trigger type, not a service type. A service with a timer:<schedule> trigger is a regular Simple or Oneshot service that peinit starts on a schedule. Timer semantics are defined here; the trigger model is defined in the Service Model section.

§9.1.1 Calendar expressions

Timer schedules use the following format:

DayOfWeek Year-Month-Day Hour:Minute:Second Timezone

Each field supports:

• Wildcards: * matches any value.
• Lists: 1,15 matches either value.
• Ranges: Mon..Fri matches Monday through Friday.
• Repetition: *:00/15:00 matches every 15 minutes.
• Last day: ~01 in the day field means last day of month. ~02 means second-to-last day.

All fields except Timezone are optional with implicit wildcards. DayOfWeek is omitted entirely if not needed. Timezone is omitted to use system-local time.

§9.1.1.1 Shortcuts

§9.1.1.2 Timezone

Timezone specifiers follow the IANA timezone database format (e.g., Europe/London, US/Eastern, UTC). Expressions without a timezone are interpreted in system-local time.

§9.1.1.3 DST transitions

When a timezone-aware expression evaluates across a DST transition:

• Spring forward (clock skips an hour): scheduled times that fall within the skipped interval MUST NOT fire. The next valid occurrence fires normally.
• Fall back (clock repeats an hour): scheduled times that fall within the repeated interval MUST fire exactly once, on the first occurrence.

§9.1.1.4 Precision

Precision is second-level. Sub-second scheduling is not supported.

§9.1.1.5 Examples

§9.1.2 Timer evaluation

At boot (after the service graph is loaded) and whenever timer configuration changes, peinit MUST compute the next firing time for every active timer trigger and arm a timerfd.

When a timerfd fires:

handle_timer(service, trigger):
    // Step 1: Check service state and create operation.
    match (service.type, service.state):
        (Oneshot, Active or Starting):
            set service.pending_timer = true
            // At most one pending run.

        (Simple, Active or Starting):
            log "timer fired for active Simple service, no-op"
            // No action.

        (_, Inactive or Completed or Failed):
            create_operation(Start, service, source=Timer)

    // Step 2: Record firing.
    write last-run timestamp to registry
    // (async -- peinit does not block on this write)

    // Step 3: Rearm.
    next = compute_next_occurrence(trigger.schedule, now())
    next = next + random(0, service.timer_jitter)
    arm timerfd for next

§9.1.2.1 Oneshot pending runs

When a Oneshot service with a pending flag transitions to Inactive or Completed (finishes running), peinit MUST immediately create a start operation and clear the flag. Multiple missed firings during a single run collapse into one pending run -- there is no queue.

§9.1.2.2 Multiple timers

Multiple timer triggers on a single service are independent. Each has its own timerfd, its own next-firing computation, and its own last-run timestamp. Oneshot services share a single pending flag across all triggers -- a service can only have one pending run regardless of how many timers fired while it was active.

§9.1.3 Persistent timers

TimerPersistent (default 1) controls whether missed timer runs are caught up after a reboot.

On boot, for each persistent timer trigger, peinit MUST:

1. Read the last-run timestamp. For services with a single timer trigger, the timestamp is stored as a REG_QWORD value at Machine\System\Services\<name>\LastTimerRun. For services with multiple timer triggers, each trigger's timestamp is stored as a REG_QWORD value under the subkey Machine\System\Services\<name>\TimerState\, with the value name set to the trigger's schedule string (e.g., the value name *-*-* 02:00:00 stores the timestamp for that trigger).
2. Compute the next scheduled firing after the last-run timestamp.
3. If that time is in the past (at least one run was missed), fire once immediately.
4. Compute the next future occurrence normally.

Persistent catch-up is always a single run, not one per missed occurrence. A daily timer that missed 5 days fires once on boot, not 5 times.

Non-persistent timers (TimerPersistent=0) ignore history. On boot, peinit computes the next future occurrence from now.

§9.1.3.1 Timestamp storage

Last-run timestamps are stored in the registry. Timer firings are low-frequency, so write overhead is negligible.

The timestamp is written after the timer fires and the service start is initiated -- not after the service completes. A service that crashes mid-run MUST NOT re-trigger on next boot (the run was attempted, not missed).

§9.1.4 Jitter

TimerJitter (default 0 seconds) adds a random delay to each timer firing. When peinit computes the next firing time, it MUST add a uniformly random delay between 0 and TimerJitter seconds.

The jitter is recomputed on each firing -- a daily timer with TimerJitter=900 fires at a slightly different time between 00:00 and 00:15 each day.

Jitter is applied after the calendar expression is evaluated. A timer MUST NOT fire before its scheduled time, only after.

§9.1.5 Clock behaviour

peinit MUST use CLOCK_MONOTONIC for timerfd arming (computing "fire in N seconds from now") and CLOCK_REALTIME for last-run timestamp storage (recording when a timer actually fired).

• NTP forward jump: armed timers fire at the correct monotonic interval. The next-occurrence computation uses realtime, so after a forward jump, peinit may compute that the next firing is sooner than expected. This is correct -- the scheduled wall-clock time arrived.
• Runtime clock backward jump: armed timers still fire at the monotonic interval. Last-run timestamps are NOT invalidated at runtime -- the run happened.
• Boot-time clock backward jump: if LastTimerRun is in the future relative to the current wall clock at boot, peinit MUST treat it as "unknown last run" and fire the persistent catch-up immediately. This only applies to the boot-time check, not runtime.
• Bad RTC at boot: if the system boots with a wildly wrong clock and NTP corrects it later, persistent catch-up may fire spuriously or not at all. This is a known edge case with no clean solution short of NTP-aware timer rescheduling.

§10.1.1 Shutdown triggers

Shutdown is initiated through three paths.

§10.1.1.1 Control socket command

An administrator sends a shutdown command via peinit's control socket. The command specifies the type:

The shutdown command is access-controlled via peinit's control SD. Only principals with SYSTEM_SHUTDOWN may initiate shutdown.

§10.1.1.2 Signals

PID 1 handles two shutdown-related signals:

Repeated SIGINT within a short window (3 presses in 5 seconds) MUST trigger an immediate forced shutdown -- skip the graceful stop sequence, SIGKILL all services, sync, reboot.

§10.1.1.3 Critical service failure

When a Critical service enters Failed state (restart budget exhausted), peinit MUST sync filesystems and reboot immediately. This is NOT a graceful shutdown -- there is no service stop ordering. The system is in an undefined state and the fastest path to a known state is a reboot.

§10.1.2 Graceful shutdown sequence

When peinit receives a poweroff, reboot, or halt command:

§10.1.2.1 Step 1: Enter shutdown state

peinit MUST set an internal shutdown flag. While the flag is set:

• No new services may be started.
• Timer triggers are disarmed.
• New control socket commands are rejected (except status queries).

§10.1.2.2 Step 2: Suspend Critical failure semantics

If a Critical service fails during shutdown, the failure is logged but MUST NOT trigger a reboot. The system is already shutting down -- rebooting would create an infinite loop.

§10.1.2.3 Step 3: Clear Completed services

Oneshot services with RemainAfterExit that are in the Completed state have no running process. peinit MUST transition them to Inactive. This releases any dependency relationships they participate in, allowing their dependents to be stopped cleanly.

§10.1.2.4 Step 4: Stop services in reverse dependency order

peinit MUST build the reverse dependency graph and stop services in waves:

1. Each service receives SIGTERM.
2. Each service has StopTimeout seconds to exit.
3. If StopTimeout expires, SIGKILL is sent to the service's entire cgroup.
4. A service MUST NOT be stopped until all services that depend on it (via Requires or BindsTo) have stopped.

Services that send STOPPING=1 via sd_notify are acknowledged. Services that send EXTEND_TIMEOUT_USEC=... during shutdown get additional time, capped by both the per-service StopTimeout (x4) and the global shutdown timeout.

§10.1.2.5 Step 5: Global timeout enforcement

The entire shutdown sequence is bounded by a global timeout:

If the global timeout expires:

1. All remaining services receive SIGKILL via cgroup kill.
2. Services whose cgroups do not empty within the post-kill timeout (default 5 seconds) are marked Abandoned -- their cgroups are leaked.
3. Continue to step 6 regardless of Abandoned services.

§10.1.2.6 Step 6: Unmount filesystems

After all services have stopped:

1. Unmount Phase 2 mounts (registry-defined) in reverse order.
2. Unmount Phase 1 mounts (/run, /dev/shm, /dev/pts, /sys/fs/cgroup).
3. /dev, /sys, /proc are left mounted (kernel needs them).
4. Remount root filesystem read-only.

§10.1.2.7 Step 7: Sync and final action

1. sync() -- flush all pending writes.
2. Call reboot(2) with the appropriate command:
   • RB_POWER_OFF for poweroff.
   • RB_AUTOBOOT for reboot.
   • RB_HALT_SYSTEM for halt.

§10.1.3 Shutdown during boot

If a shutdown is requested while peinit is still in Phase 2 boot, peinit MUST enter shutdown immediately:

• Services in Starting state are killed (SIGKILL -- they never reached Active, no graceful stop).
• Services that reached Active are stopped gracefully per the normal sequence.
• The boot is abandoned.

§10.1.4 Signal summary

PID 1 handles all signals via signalfd. All signals are blocked and read from the event loop -- no signal handlers, no async-signal-safety concerns.

All other signals are ignored. PID 1 cannot be killed by any signal -- the kernel protects PID 1 from fatal signals.

§10.1.5 STOPPING=1 acknowledgement

When a service sends STOPPING=1 via sd_notify, peinit MUST authenticate the sender (see the Notify socket section in the Control Interface) and acknowledge the notification by logging it.

After receiving STOPPING=1, peinit MUST NOT send additional SIGTERM signals to the service. The service has indicated that it is already shutting down gracefully -- a redundant SIGTERM is unnecessary and may interfere with the service's shutdown sequence.

The StopTimeout continues to apply after STOPPING=1 is received. STOPPING=1 does not extend or reset the stop timeout. If the service needs additional time to shut down, it MUST send EXTEND_TIMEOUT_USEC (see the Timeout extension section in Restart and Reload). If StopTimeout expires without the process exiting, peinit escalates to SIGKILL regardless of whether STOPPING=1 was received.

§11.1.1 Control socket

peinit exposes a Unix stream socket at /run/peinit/control.sock for runtime commands. The socket is created during Phase 1 infrastructure setup (after /run is mounted and registryd is running) and exists for the lifetime of the system.

§11.1.1.1 Wire format

Messages are newline-delimited JSON. Each message is one JSON object per line -- no pretty-printing. This eliminates ambiguity about message boundaries.

Request format:

{"command": "start", "service": "jellyfin", "wait": true}

Success response:

{"status": "ok", "operation_id": "a1b2c3d4-...", "service": "jellyfin", "state": "active", "cause": "explicit_start", "warnings": []}

Error response:

{"status": "error", "code": "ACCESS_DENIED", "message": "caller lacks SERVICE_START on jellyfin"}

Field names, types, and value formats in JSON examples throughout this specification are normative.

§11.1.1.2 Peer authentication

When a client connects, peinit MUST obtain the caller's identity via kacs_open_peer_token (KACS syscall). This returns a token fd representing the peer's KACS identity. The kernel provides this -- there is no userspace credential exchange.

The token returned by kacs_open_peer_token is the peer thread's effective token at connection time -- if the peer is impersonating, the impersonation token is captured. This ensures that access control decisions reflect the identity under which the client is actually operating, not its underlying service identity. The exact semantics of kacs_open_peer_token are defined in the KACS v0.20 specification.

For each command, peinit MUST call AccessCheck with:

• Token: the peer's token.
• SD: the target service's ServiceSecurity SD (for service commands) or peinit's control SD (for system commands).
• Desired access: the access right for the command.

If AccessCheck denies access, peinit MUST return an ACCESS_DENIED error and log the attempt.

§11.1.1.3 Limits

peinit MUST enforce hard limits on the control socket:

Connections exceeding MaxControlConnections MUST be rejected. Requests exceeding MaxRequestSize MUST be rejected. Idle connections exceeding ConnectionTimeout MUST be closed.

§11.1.2 Notify socket

peinit creates a Unix datagram socket for sd_notify messages. The path is an internal implementation detail -- services receive it via the NOTIFY_SOCKET environment variable set during pre-exec. No service hardcodes the path.

§11.1.2.1 Sender authentication

peinit MUST authenticate sd_notify senders:

1. Enable SO_PASSCRED on the notify socket.
2. Receive the sender's PID via SCM_CREDENTIALS (kernel-attested).
3. Validate the PID against the service's tracked main PID (verified via pidfd). NotifyAccess=Main is the only supported mode.
4. Validate the start generation -- messages from a previous incarnation MUST be rejected.

Messages from unrecognised senders MUST be dropped and logged. UID/GID from SCM_CREDENTIALS are not policy inputs.

§11.1.3 Fd store

The fd store allows a service to persist file descriptors across restarts. A service pushes fds to peinit via sd_notify; peinit holds them and re-injects them into the new process on restart. This enables stateful daemons (e.g., a web server preserving listening sockets) to restart without dropping connections.

§11.1.3.1 Schema control

The FdStoreMax field in the service definition (default 0) controls the maximum number of file descriptors peinit will hold for the service. When FdStoreMax is 0, the fd store is disabled -- FDSTORE=1 messages are logged and the accompanying fd is closed.

§11.1.3.2 Storing an fd

When a service sends an sd_notify message containing FDSTORE=1 with a file descriptor attached via SCM_RIGHTS:

1. peinit MUST authenticate the sender using the same PID-matching and generation validation as all other sd_notify messages (see Sender authentication above).
2. If the service's FdStoreMax is 0, peinit MUST log the rejection and close the received fd.
3. If the fd store already contains FdStoreMax entries, peinit MUST log the rejection and close the received fd. The existing store is not modified.
4. If FDNAME=<name> is present in the message, the fd is stored under that name. If FDNAME is absent, the fd is stored under the default name "stored".
5. If FDPOLL=0 is present, peinit MUST mark the fd as exempt from poll monitoring. By default, peinit MAY monitor stored fds for error conditions (POLLERR, POLLHUP) and remove fds that become invalid.

Multiple fds MAY share the same name. On injection, all fds with a given name appear in LISTEN_FDNAMES in storage order.

§11.1.3.3 Removing an fd

When a service sends an sd_notify message containing FDSTOREREMOVE=1 with FDNAME=<name>:

1. peinit MUST authenticate the sender.
2. peinit MUST remove all stored fds matching the given name and close them.
3. If no fd with the given name exists, the message is a no-op. peinit MUST NOT treat this as an error.

§11.1.3.4 Injection on restart

When a service restarts (transitions from a failed or stopping state back to Starting), peinit MUST inject stored fds into the new process during child pre-exec (Step 8 of the Pre-Exec Sequence):

1. Stored fds are passed as inherited file descriptors starting at SD_LISTEN_FDS_START (file descriptor 3).
2. The LISTEN_FDS environment variable MUST be set to the number of injected fds.
3. The LISTEN_FDNAMES environment variable MUST be set to a colon-separated list of fd names, in the same order as the fd numbers.
4. After successful injection, the fd store is cleared -- peinit no longer holds the fds.

§11.1.3.5 Clearing the fd store

The fd store MUST be cleared (all stored fds closed) in the following situations:

• Explicit stop: when a service is stopped by an administrator or by shutdown (not a crash-triggered restart). The fds are no longer useful -- the service is not coming back.
• Service removal: when a service definition is removed from the registry. All associated state, including stored fds, is discarded.

The fd store survives across automatic restarts (crash -> restart policy -> new start). This is the entire point of the mechanism -- fds persist through the restart that the service cannot control.

§11.1.4 Outbound IPC

peinit connects to three services:

All outbound IPC MUST be non-blocking. authd and eventd use Unix stream sockets with epoll. Token requests to authd are state- machine driven with timeouts -- if authd is unresponsive, the service start fails rather than PID 1 hanging.

§11.2.1 Service lifecycle commands

§11.2.1.1 Access rights per command

§11.2.2 System commands

§11.2.3 Wait semantics

By default, lifecycle commands block until the operation reaches a terminal state. The client MAY set "wait": false for immediate acknowledgment.

When waiting, the response is sent when:

• The service reaches the target state (Active for start, Inactive for stop).
• The service enters Failed state.
• The operation timeout expires.

For Oneshot services, the start target state is Completed (if RemainAfterExit=1) or Inactive (if RemainAfterExit=0).

Reload defaults to wait=false. If wait=true, the connection stays open until the Reloading state resolves. The response includes "mode": "confirmed" or "mode": "advisory" (see the Restart and Reload section).

§11.2.4 reload-config semantics

reload-config loads a new snapshot of all service definitions from the registry. It MUST NOT live-update the running system.

The reload is atomic: peinit builds and validates a complete new graph snapshot in memory and only swaps it in if validation succeeds. If validation fails, the previous generation remains active and errors are returned to the caller.

• All service definitions are re-read from the registry.
• A new dependency graph is built and validated.
• Running services are NOT affected -- they continue on their activation generation.
• New definitions take effect on the next start, restart, or trigger firing.
• New services become available for start commands immediately.
• Timer triggers on inactive services are re-evaluated.

§11.2.5 Command x state matrix

Commands sent to a service in an unexpected state return an error, not a silent no-op.

• ALREADY: command is redundant. Return current state (not an error).
• NOOP: command has no effect. Return success.
• ERROR: command is invalid for this state. Return error with explanation.
• Clear: reset to Inactive.
• Cancel: abort current operation then proceed.
• QUEUE: operation is queued as Pending. Executes after the current operation completes (see the Conflict Resolution section in Operations).

§11.2.6 Status response

The status response for a service MUST include:

{
    "service": "jellyfin",
    "state": "active",
    "cause": "explicit_start",
    "status_text": "Listening on port 8096",
    "current_job": {
        "id": "a1b2c3d4-...",
        "type": "service_main",
        "pid": 1234,
        "started_at": "...",
        "identity": "jellyfin-svc"
    },
    "current_operation": {
        "id": "e5f6g7h8-...",
        "type": "start",
        "source": "admin"
    },
    "health": "healthy",
    "uptime_seconds": 86400,
    "warnings": []
}

The status_text field carries the most recent STATUS= string sent by the service via sd_notify. If the service has never sent STATUS=, the field MUST be null. peinit MUST clear status_text to null at the start of each new activation generation (restart). A STATUS= from a previous incarnation MUST NOT persist across restarts.

The warnings array MUST include leaked sub-cgroups, if any (see the Health Checks section).

peinit is not a logging system. eventd handles log storage, indexing, and queries. But peinit holds the pipes at birth -- it controls where service output goes, and it must handle the window before eventd is running.

§12.1.1 Output wiring

When peinit forks a service process, it MUST create pipes for stdout and stderr before exec. The child's stdout and stderr are redirected to the write end of these pipes. peinit holds the read end and monitors them via epoll.

peinit MUST read service output line-by-line and tag each line with:

• Service name.
• Stream (stdout or stderr).
• Timestamp (CLOCK_REALTIME).
• Job GUID.

ExecStartPre and ExecStartPost hook output MUST be captured and tagged with the service name and hook identifier (e.g., jellyfin/ExecStartPre[0]).

Health check output MUST be captured -- useful for diagnosing why a health check failed.

§12.1.2 Pre-eventd buffer

Before eventd starts, peinit MUST buffer all captured output in fixed-size in-memory pre-eventd ring buffers:

The audit buffer is separate and additive. A noisy service MUST NOT crowd out audit events.

When either buffer fills, the oldest entries MUST be dropped.

§12.1.3 Flood protection

A noisy service MUST NOT starve peinit's event loop. The following limits apply:

§12.1.3.1 Per-iteration read budget

In each event loop iteration, peinit MUST read at most a bounded number of bytes from service pipes before returning to process other events (signals, control socket, notify socket, timerfds). The exact budget is an implementation tuning parameter.

§12.1.3.2 Backpressure

If a service writes faster than peinit can forward to eventd (or than the pre-eventd ring buffer can absorb), the service's pipe buffer fills. When the kernel pipe buffer is full, the service's write() calls to stdout/stderr block. This is deliberate -- the service naturally slows down.

peinit MUST NOT drop service output silently. Backpressure via the pipe is the flow control mechanism.

§12.1.4 Event loop fairness

No single event source MAY starve the event loop. peinit's event loop MUST cycle back to signal processing (SIGCHLD reaping, shutdown signals) within bounded time regardless of load on any other source.

Signals MUST never be starved. Child reaping and shutdown handling take priority over all other event sources in every iteration.

§12.1.5 eventd handoff

When eventd reaches Active state:

1. peinit MUST connect to eventd via its IPC socket.
2. peinit MUST drain the entire service output pre-eventd ring buffer to eventd (oldest first), preserving timestamps and metadata.
3. peinit MUST drain the audit pre-eventd ring buffer to eventd.
4. peinit MUST switch to real-time forwarding -- new service output is sent to eventd as it arrives.
5. The pre-eventd ring buffers are cleared.

From this point, peinit is a pipe relay: read from service pipes, tag with metadata, forward to eventd.

§12.1.5.1 Outbound write backpressure

The eventd socket is non-blocking. If eventd processes data slower than services generate it, the kernel socket buffer fills. peinit MUST maintain a bounded outbound write buffer (same 1 MB limit as the pre-eventd ring buffer). When the outbound buffer fills, oldest messages are dropped.

peinit MUST NOT block on a write to eventd and MUST NOT allow unbounded memory growth from pending writes.

§12.1.6 eventd failure

If eventd crashes after it was running:

1. peinit detects the disconnection (socket closes).
2. peinit re-enables the pre-eventd ring buffers.
3. When eventd restarts and reaches Active, the handoff sequence repeats.

There is a log gap between eventd crashing and restarting, bounded by the pre-eventd ring buffer size.

§12.1.7 Console output

peinit MUST write its own operational messages to /dev/console:

• Phase 1 progress (mount results, registryd start).
• Phase 2 progress (service start/fail, dependency errors).
• Shutdown progress.
• Recovery mode entry.
• Critical service failures.

Service stdout/stderr MUST NOT be echoed to the console by default. The console is for peinit status messages only.

This section consolidates peinit's security architecture. Individual mechanisms are defined in their respective sections; this section defines the trust model, attack surfaces, and security invariants.

§13.1.1 Trust boundaries

peinit operates at two trust boundaries.

§13.1.1.1 Kernel to peinit

peinit is the first userspace process. The kernel assigns it a SYSTEM token (S-1-5-18, all privileges). This is the root of trust for all userspace identity. peinit MUST NOT drop this token and MUST NOT authenticate to anyone -- its identity is axiomatic.

§13.1.1.2 peinit to services

peinit creates service processes with specific identities and reduced privileges. The trust direction is one-way: peinit trusts the kernel (it has no choice), and services trust peinit (it gave them their identity). Services do not trust each other -- KACS mediates all inter-service access.

peinit is part of the Trusted Computing Base (TCB), alongside the kernel, KACS, LCS, KMES, registryd, authd, lpsd, and eventd. A compromise of any TCB component compromises the entire system.

§13.1.1.3 Pre-FACS scope

The token, privilege, and SD enforcement described in this specification is fully operational for IPC-mediated access (registry, control socket, service-to-service communication). However, pre-FACS, all processes run as UID 0 and the filesystem does not enforce KACS Security Descriptors. A service's token controls what it can access via KACS-protected interfaces but does not prevent it from reading or writing arbitrary files on disk.

The peinit security model becomes fully effective for filesystem objects once FACS is implemented. Until then, the filesystem layer relies on conventional trust (correct packaging, controlled binary paths).

§13.1.2 peinit's privileges

peinit runs as SYSTEM with all privileges for the lifetime of the system. It requires:

• PRIV_TCB -- to request tokens from authd on behalf of services.
• PRIV_IMPERSONATE -- to impersonate control socket callers for AccessCheck evaluation.
• Process creation -- fork/exec authority (inherent to PID 1).
• cgroup management -- create/destroy cgroups under /sys/fs/cgroup/peinit/.
• Signal delivery -- SIGTERM/SIGKILL to managed processes.
• Mount operations -- Phase 1 virtual filesystem mounts.

peinit does not use PRIV_CREATE_TOKEN directly. Token creation is authd's responsibility. peinit receives token fds from authd.

§13.1.3 Attack surface

§13.1.4 Security invariants

Properties that peinit MUST NOT violate under any circumstances:

1. peinit MUST NOT grant privileges it was not asked to grant. RequiredPrivileges is subtractive only. peinit removes privileges; it MUST NOT add them.

2. peinit MUST NOT bypass AccessCheck for control operations. Every control socket command is checked against the appropriate SD. There is no backdoor, no override flag, no "trust localhost."

3. peinit MUST NOT expose one service's state to another without access control. The list command returns only services the caller has SERVICE_QUERY_STATUS on. Status queries are per-service access-controlled.

4. peinit MUST log all access denials. Failed AccessCheck results are logged with caller SID, target, and requested right. Silent denial is not acceptable.

5. The control socket SD and ServiceSecurity SDs are the only policy inputs for runtime access control. peinit MUST NOT consult any other source (config files, environment variables, hardcoded lists) for access decisions.

6. peinit MUST NOT share its SYSTEM token. Even Identity=SYSTEM services receive a clone, never peinit's original token.

7. peinit MUST NOT drop its SYSTEM identity. PID 1 runs as SYSTEM for the lifetime of the system.

8. Identity MUST be deterministic. Every service runs with a known identity. SYSTEM must be explicitly declared. Empty defaults to LocalService. The dangerous case (running as SYSTEM) is never implicit.

This appendix lists every registry key that peinit reads or writes. Definitions and semantics are in the sections referenced below.

§14.1.1 Service definitions

§14.1.2 Boot configuration

§14.1.3 peinit operational parameters