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 and mountable when it starts. Root storage assembly -- LUKS decryption, LVM activation, RAID array assembly, and any filesystem check -- is the initramfs's responsibility, performed (if at all) before peinit runs. peinit neither performs nor assumes a root fsck.

The initramfs transfers control to peinit as PID 1 by chroot-ing into the assembled root and exec'ing peinit there -- not via switch_root/pivot_root, because the kernel forbids relocating onto the initramfs rootfs. Consequently the initramfs rootfs is not gone: it remains the mount-namespace root (emptied and unreachable from peinit's view). peinit MUST NOT assume a clean single-root mount topology and MUST NOT attempt pivot_root.

peinit is installed at a fixed path on the real root (/usr/bin/peinit); the boot-image tooling sets the kernel init= command line to that path, which the initramfs honours when transferring control.

At handoff the initramfs has already mounted the real root read-write at /, and has mounted /proc, /sys, and /dev and moved them into the real root. peinit therefore neither assembles nor remounts the root, and does not blindly re-mount those three pseudo-filesystems (see Phase 1, Steps 1-2). registryd's storage backend requires a writable root (WAL and shared-memory files) even for read-only registry operations; delivering the root writable is the initramfs's responsibility, not peinit's.

peinit MUST NOT perform root filesystem assembly, decryption, or repair. These operations require tools and configuration that belong to the initramfs environment.

peinit starts with a minimal environment -- the initramfs provides TERM only, with no PATH or other variables -- and an argv of just its own path. peinit MUST NOT rely on inheriting any environment from the initramfs, and MUST NOT pass its own near-empty startup environment through to services; the base environment handed to services is defined by peinit (see §4.1).

Non-root storage (data partitions, additional filesystems) is out of scope for peinit. It is handled at the services/roles layer (e.g. a Oneshot service that performs the mount), not by peinit directly -- peinit has no built-in mount feature.

§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 materialise a SYSTEM token (S-1-5-18) by minting one from its own token (kacs_create_token; see §3.3) and install it on the child process. No authd interaction is needed -- indeed authd does not yet exist when these services start.

The following services use Identity=SYSTEM:

• registryd -- MUST start before authd exists
• authd -- needs SeTcbPrivilege and SeCreateTokenPrivilege; is the token minter for non-platform services
• 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 include a per-service SID in the group list of every SYSTEM token it mints. The SID is derived from the service name using the service SID algorithm defined in PSD-004 (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: Verify the root filesystem is writable

The initramfs delivers the real root mounted read-write (see the initramfs contract). peinit MUST NOT remount the root -- root assembly and mount flags are the initramfs's responsibility, and a redundant remount of an already-writable or overlay root can fail spuriously.

peinit MUST confirm the root is writable with a single probe write (create and remove a file under /.peinit/). registryd's storage backend requires write access (WAL and shared-memory files) even for read operations, so a read-only root cannot support Phase 2.

If the probe write fails -- the root is unexpectedly read-only or the filesystem is faulty -- peinit MUST enter Recovery mode.

§2.1.3.2 Step 2: Mount remaining virtual filesystems

The initramfs has already mounted /proc, /sys, and /dev and moved them into the real root (see the initramfs contract). peinit MUST NOT blindly re-mount them: a redundant mount stacks a second filesystem over the populated one, and on some kernel/flag combinations returns EBUSY.

peinit MUST ensure the following filesystems are present, mounting each only if it is not already mounted:

The mount set and flags are hardcoded; all seven MUST exist before any other process runs. For the initramfs-provided mounts (/proc, /sys, /dev), peinit MUST treat an already-mounted filesystem (including an EBUSY result from an attempted mount) as success.

If a filesystem peinit is responsible for mounting (/dev/pts, /dev/shm, /run, /sys/fs/cgroup) cannot be mounted, 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. Mint a SYSTEM token from its own token (kacs_create_token), including registryd's per-service SID in the group list (derived per the PSD-004 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 of Machine\System\Services\SchemaVersion (the schema-version guard; see §3.2 and the appendix) to verify the registry is serving reads. This key is guaranteed to exist on any valid system. If the probe read 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

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 root candidates for automatic start. Services with no triggers (demand-only) are not root boot candidates, but MAY be pulled into the boot transaction as dependencies of a boot-triggered service. 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.

§2.2.2 Step 2: Build and validate the dependency graph

peinit MUST build the boot graph from all boot-triggered root candidate services plus the transitive dependency closure of their Requires, BindsTo, and existing non-disabled Wants dependencies. Requires and BindsTo dependencies pull in their target even if the target has no boot trigger. Existing non-disabled Wants dependencies are pulled in as best-effort boot transaction members. Missing or disabled Wants dependencies are ignored. Missing or disabled Requires or BindsTo dependencies fail the dependent with cause DependencyFailure.

peinit MUST perform a topological sort of this boot graph and validate it before attempting to start anything. The full validation rules are defined in §6. 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.

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

A successful Full boot MUST reset the boot attempt counter to 0. A boot is successful when every Critical service has reached and held a dependent-satisfying state -- Active, Completed, or Skipped (§5.1) -- for a grace period. The criterion is "satisfying," not "Active," because a Critical Oneshot reaches Completed and never Active; requiring Active would make such a service unable to ever mark the boot successful.

§2.3.2 Safe mode

Safe mode starts a reduced set of boot-triggered services. A service with no boot trigger does not auto-start in Safe mode, regardless of SafeMode or ErrorControl; it remains demand-only. Within the boot-triggered set, 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 and ErrorControl=Critical are filters within the boot-triggered set. They do not make a demand-only service auto-start in Safe mode.

§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 (verify the root is writable, mount the remaining 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). peinit MUST exec /bin/recsh if it is present and executable, otherwise /bin/sh, running it as SYSTEM on /dev/console. peinit does not care where either binary comes from. If the shell exits, peinit MUST respawn it -- Recovery mode never exits to an unmanaged PID 1. If neither /bin/recsh nor /bin/sh can be exec'd, peinit cannot deliver a Recovery shell; it MUST log the reason to /dev/console, sync, and halt (PID 1 exiting would panic the kernel). A missing shell is a binary-integrity failure, outside the boot-attempt machinery's remit.
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).

• peinit MUST read the counter at startup, before selecting the boot mode. The Recovery threshold (counter >= N) is evaluated against this pre-increment value, so a default N of 3 admits exactly three boot attempts before Recovery.
• peinit MUST increment the counter once per boot, immediately after Phase 1 Step 1 confirms the root is writable, and before Phase 2 begins. peinit MUST NOT increment before the root is known writable: doing so on a read-only root would silently lose the increment and defeat escalation entirely.
• 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 or a run-to-completion task -- 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 names

A service name MUST consist of characters from [A-Za-z0-9._-] and MUST be 1-128 bytes long. Any other character makes the name a validation error (cause ValidationError). In particular / is disallowed (names map directly onto cgroup ids, §4.1, and registry key names) and : is reserved for peinit-internal synthetic naming.

§3.1.2 Service types

peinit supports two service types.

§3.1.2.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.2.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.3 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.4 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.5 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

Known service-definition fields MUST NOT appear more than once in a collected definition. Duplicate known fields are validation errors. This is a defensive Peinit ingestion rule even when the LCS registry representation ordinarily provides at most one value per name. Unknown registry values are still ignored for forward compatibility.

§3.2.2 Field value formats

• String fields -- when present, string fields MUST be non-empty unless this section explicitly defines empty-string handling for the field. An empty string for Identity is treated the same as an absent Identity and defaults to LocalService. An empty string for HookIdentity is treated the same as an absent HookIdentity and falls back to the service's Identity. DisplayName and Description use empty string as absence.

• WorkingDirectory -- when present, MUST be a non-empty absolute path. If absent, it defaults to /. Filesystem existence, type, and access checks are performed by the later validation or runtime rules that consume the working directory.

• SuccessExitCodes -- each entry is a decimal integer in the range 0-255 (a process exit code). Signal names and ranges are NOT accepted. Code 0 is always success implicitly and need not be listed.

• Identity / HookIdentity -- either a well-known principal name (SYSTEM, LocalService, NetworkService, …), matched case-insensitively, or a literal SID string (S-1-5-18). authd resolves any other name (§3.3).

§3.2.3 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.1 Evaluation constraints

peinit is single-threaded PID 1 and MUST NOT block its event loop while evaluating checks. Two constraints follow:

• registry: checks are cache-only. A registry:<key> check may only reference a key peinit already caches (under Machine\System\Services\ or Machine\System\Init\, §3.5); it is evaluated against the in-memory model, never via a live registry read. A registry: check naming any other key is a validation error -- the definition is rejected at load (cause ValidationError).
• Filesystem checks (path:/file:/directory:) are evaluated off the main loop. A stat() can block uninterruptibly on hung I/O, so peinit evaluates these in a bounded forked helper rather than calling stat() from its event loop (see §4.1).

A check that cannot complete within its timeout is treated as not satisfied (fail-safe): the Condition skips the service, and the Assert fails it with cause AssertionError.

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

For command parsing, whitespace means ASCII space, horizontal tab, line feed, carriage return, form feed, and vertical tab. Other Unicode whitespace code points are ordinary argument characters.

Double quotes group text into a single argv element and are not retained in the resulting argument. Quote grouping MAY occur inside an argument; for example, --name="hello world" becomes one argv entry with the value --name=hello world. Empty quoted strings are preserved as empty argv entries.

Backslash has no escape semantics and is copied literally. Single quote is an ordinary character.

An empty or whitespace-only command string is invalid. An unclosed double quote is invalid. Invalid command strings are definition validation errors.

Command string parsing only produces argv. Executable path validation, if any, is performed by the service-definition validation or runtime execution rules that consume the parsed argv.

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

§3.2.5 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 separately materialised token of their own.

§3.3.1 Token materialisation

Token materialisation depends on the Identity field:

§3.3.1.1 SYSTEM path

peinit MUST materialise an independent SYSTEM token by minting one with kacs_create_token, using its own token as the template: peinit reads its own SYSTEM token via kacs_open_self_token (user SID S-1-5-18, group list, and privilege set) and mints a new primary token with that same identity, adding the per-service SID to the group list (see Per-service SID). The minted token is fully independent -- the later privilege restriction MUST NOT affect peinit's own token. Minting requires peinit to hold SeCreateTokenPrivilege, which the boot SYSTEM token carries.

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

External dependency (authd). The steps above describe what peinit requires of authd -- send the Identity value, receive a materialised token fd -- not the wire interface. authd's request/response schema, its socket path, and the fd-passing mechanism (expected to be SCM_RIGHTS over a Unix socket) are owned by authd, and no authd spec exists yet (authd's design is deliberately deferred until KACS and the registry are settled). Every non-SYSTEM service start depends on this interface; it is not fully implementable from PSD-007 alone, and this path becomes normative once authd is specified.

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 PSD-004: 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 includes the per-service SID in the group list when it mints the token (kacs_create_token; see SYSTEM path). 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.2 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 the KACS_IOC_ADJUST_PRIVS ioctl on the token fd -- one kacs_priv_entry per removed privilege, carrying the privilege-removed attribute, and requiring the KACS_TOKEN_ADJUST_PRIVS right on the fd. peinit MUST NOT use KACS_IOC_RESTRICT: that builds a restricted-SID token and does not alter the privilege bitmask.

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 minted SYSTEM token) set them. Enable policy is authd's domain.

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

§3.3.3 Exec contexts

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

If HookIdentity names SYSTEM, peinit mints a SYSTEM token (SYSTEM path) 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.

These notifications use the LCS Watch mechanism defined in PSD-005: a persistent subscription that delivers change events on a pollable key fd, with an OVERFLOW event when the kernel-side notification queue is exceeded.

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

§3.5.6 Service removal

When a service definition is removed from Machine\System\Services\, peinit learns of it through the same change-notification path. Removal handling depends on whether the service is running:

• Not running (Inactive, Failed, Completed, Skipped, Abandoned): peinit discards the in-memory entry immediately. There is no process to consider.
• Running (Active, Starting, Reloading, Backoff, Stopping): peinit MUST NOT kill the running instance. The running process is a job, and a job's lifecycle is independent of its service definition -- removing the definition stops future management, it does not terminate work in progress. peinit marks the entry definition-removed and retains the cached definition solely to keep supervising the existing instance. When that instance exits it is NOT restarted (RestartPolicy is moot -- the definition is gone), and peinit then discards the entry entirely.

While an entry is definition-removed:

• it keeps satisfying its dependents for as long as the instance is alive (it is still running);
• stop is accepted -- an administrator may drain it cleanly, using the cached StopTimeout;
• start, restart, and reload are rejected with UNKNOWN_SERVICE (§11.1) -- there is no definition to (re)start from;
• status reports the current runtime state plus a definition_removed: true flag (§11.2), so the draining instance is visible, not silent.

definition-removed is a flag on the existing runtime state, not a distinct state -- the state machine (§5.1) and the command x state matrix (§11.2) are unchanged. Once the instance exits or is stopped, the entry -- including any fd-store contents (§11.1) -- is discarded. A dependent that Requires a removed service keeps being satisfied while the instance runs; after it exits and the entry is discarded, the dependent's next start sees an unresolved dependency, handled by the normal validation path.

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 every character outside [A-Za-z0-9._-] percent-encoded (% followed by the byte's two uppercase hex digits). Service names are already restricted to that character set (§3.1), so in practice the cgroup id equals the service name; the encoding is a defensive, injective guarantee that distinct names always map to distinct, cgroup-safe ids (unlike a plain /->- substitution, where a/b and a-b would collide). It 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 §4.2), 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 §3.5). 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.2.1 Non-blocking evaluation

peinit MUST NOT call a blocking syscall from its event loop while evaluating checks (§3.2):

• registry: checks are evaluated against the in-memory model (§3.5). A non-cached key is a validation error (§3.2), so this evaluation never reads the registry live.
• path:/file:/directory: checks are performed by a short-lived forked helper in a dedicated cgroup -- not by stat() on the main loop. The helper stats the service's filesystem checks and reports the results over a pipe; peinit waits on the helper's pidfd and the pipe via epoll, never blocking. The helper is bounded by a timeout.

If the helper does not report within the timeout (e.g. stat() is wedged in uninterruptible sleep on a hung mount), peinit MUST treat the affected checks as not satisfied -- a Condition skips the service, an Assert fails it with cause AssertionError -- and continue. peinit SIGKILLs the helper; if it survives (D-state), its cgroup is leaked and abandoned exactly as a service process that survives SIGKILL (§4.2). The event loop is never held up by a hung check.

§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 §3.3. 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 §3.3. For SYSTEM services, mint a token from peinit's own SYSTEM identity (kacs_create_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 | CLONE_INTO_CGROUP), targeting the service's main/ sub-cgroup (created in Step 2). This atomically (a) obtains a pidfd for the child and (b) places the child directly into main/ at creation. There MUST be no window where the child exists without a pidfd, and none where it runs or execs in peinit's own cgroup before being placed.

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. Close the write end of the error pipe.
2. 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.

The child is already in the main/ sub-cgroup -- CLONE_INTO_CGROUP (Step 6) placed it there atomically at creation, so the parent performs no post-fork cgroup move. This removes the window in which a child could exec in peinit's cgroup, and avoids requiring the child to write its own cgroup.procs, which its post-installation token could not do.

§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. Reset the signal environment: restore the signal mask to unblock all signals and reset every signal disposition to SIG_DFL. peinit blocks all signals for its signalfd (§10.1) and the child inherits that mask across fork; a service MUST NOT start with signals blocked or with peinit's handlers installed.
3. Install the service's KACS token.
4. Set RLIMIT values (LimitNOFILE, LimitCORE) if configured.
5. Set oom_score_adj:
   • -1000 (OOM-immune) for ErrorControl=Critical services.
   • 0 (default) for all others.
6. Set working directory.
7. Set environment variables (base environment + Environment values from the definition).
8. 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.
9. Inject stored file descriptors if the service has an fd store with entries from a previous run.
10. Exec the binary (ImagePath + Arguments).
11. If exec fails: write error to the pipe, _exit(127).
12. If any step 2-9 fails: write error to the pipe, _exit(126).

§4.1.3.9 Inherited execution context

A service MUST inherit only the execution context peinit explicitly hands it: its stdio (the stdout/stderr pipes and the /dev/null stdin -- see §12.1) and any file descriptors injected from the fd store (sub-step 9). Every other file descriptor peinit holds -- the control socket, the notify socket, the epoll fd, the JFS device fd, and the registryd/authd/eventd connections -- MUST be created with O_CLOEXEC (or have CLOEXEC set immediately on creation) so that it closes automatically at exec and never leaks into a service. The signal reset (sub-step 2) and the CLOEXEC discipline together guarantee a service starts from a clean context, not from peinit's privileged one.

§4.1.3.10 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.11 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 Base environment

peinit constructs each service or hook process's environment in layers, lowest precedence first:

1. Compiled-in base. A fixed floor peinit always provides:

   Variable	Value
   PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

2. Global EnvVars. Each value under Machine\System\Init\EnvVars\ is injected as a variable (value name = variable name, REG_SZ data = value). An EnvVars\PATH value overrides the compiled-in PATH; other names add. Because this key is served by registryd, it is available only to services started in Phase 2: the Phase 1 / early-Phase 2 platform services (registryd, authd, lpsd, eventd) are launched with the compiled-in base only, since the registry is not yet readable when they start.

3. Per-service Environment. The definition's Environment values, which override layers 1-2.

4. Protocol variables. NOTIFY_SOCKET (always) and LISTEN_FDS / LISTEN_FDNAMES (only when stored fds are injected), set by the pre-exec sequence above. These have the highest precedence and MUST NOT be overridable by EnvVars\ or a service's Environment -- a service overriding NOTIFY_SOCKET would break sd_notify.

A change to EnvVars\ takes effect on a service's next start (like the per-service Environment field); it is not applied to already-running services.

peinit does NOT set HOME, USER, LOGNAME, SHELL, or TERM by default. Peios identity is a KACS token (a SID), not a passwd entry, so there is no canonical home directory or login shell to populate; a service that needs any of these supplies it via EnvVars\ or its Environment field. peinit's own minimal startup environment (TERM=linux only; see §2.1) is NOT passed through -- the environment is constructed by peinit, not inherited.

Security. Write access to Machine\System\Init\EnvVars\ lets a principal inject environment into every service peinit starts (LD_PRELOAD, LD_LIBRARY_PATH, and the like), so it is equivalent to compromising those services. peinit MUST NOT filter variable names -- the key's Security Descriptor is the control boundary, consistent with the registry's write-authority threat model. That SD MUST NOT be permissive; the recommended default is SYSTEM full, Administrators read-only.

§4.1.5 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 (§6.2) 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 (§4.1) 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 three 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 Backoff (and then to Starting once the backoff delay elapses; see §5.3). Otherwise it transitions to Failed.

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

§5.2.2.2 Always-only restart causes

CleanExitRestart is consulted only when a Simple service exits successfully (exit code 0 or SuccessExitCodes) and RestartPolicy=Always. It uses the same exponential backoff and RestartMaxRetries budget as restart-eligible failures. This prevents a daemon that exits cleanly in a tight loop from bypassing restart throttling.

CleanExitRestart MUST NOT be treated as ProcessCrash. Logs and status MUST make clear that the process exited successfully and was restarted solely because the service policy is Always.

§5.2.2.3 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.4 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 and the service definition includes an OnFailure field, peinit MUST start the designated fallback service -- except for the causes excluded below. The transition cause is logged, so the OnFailure service or eventd can distinguish causes.

OnFailure MUST NOT fire for:

• ShutdownWave -- no new services may start during shutdown (§10.1), so a fallback would be both impossible and pointless. A Starting service SIGKILLed by the shutdown wave transitions to Failed without triggering OnFailure.
• ValidationError, CycleDetected, DependencyFailure, AssertionError -- these are definition or dependency-graph breakage, not runtime degradation. A broken or unsatisfiable definition cannot meaningfully trigger a fallback, and the fallback would likely sit in the same broken graph. OnFailure is for degrading a running service, not for configuration errors.

For all other Failed causes -- including ProcessCrash, WatchdogTimeout, HealthCheckFailure, the startup-failure causes, and RestartBudgetExhausted -- OnFailure fires.

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.3.1 Loop guard

An OnFailure service can itself fail and carry its own OnFailure, so a misconfiguration (A's OnFailure is B, B's OnFailure is A) could loop indefinitely. peinit MUST bound the chain originating from a single failure: it tracks the set of services already started as OnFailure handlers for that originating failure and MUST NOT start one already in the set, and MUST NOT follow the chain beyond a fixed depth (16). When the guard trips, peinit logs the loop and stops -- it does not keep firing fallbacks.

§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 restart-eligible cause occurs (§5.2), or when a Simple clean exit produces the always-only CleanExitRestart cause (§5.2), peinit evaluates the restart policy. The outcome is either Failed (no restart) or Backoff -- the service waits out a delay, then transitions to Starting:

evaluate_restart(service, cause):
    // Step 1: Check policy.
    if service.restart_policy == Never:
        return STAY_FAILED
    if cause == CleanExitRestart and service.restart_policy != Always:
        return INVALID_CAUSE_FOR_POLICY
    if service.restart_policy == OnFailure:
        // A termination counts as success (no restart) only when the
        // cause is a process exit whose code is in SuccessExitCodes.
        // Only ProcessCrash and CleanExitRestart carry an exit code.
        // CleanExitRestart is Always-only and was handled above.
        // Every other
        // restart-eligible cause (WatchdogTimeout, HealthCheckFailure,
        // ReadinessTimeout, PreHookFailure, PreExecFailure,
        // ParentSetupFailure -- see §5.2) has no exit code and is
        // always a failure under OnFailure.
        if cause == ProcessCrash and exit_code in service.success_exit_codes:
            return STAY_FAILED
    // restart_policy == Always falls through unconditionally.

    // Step 2: Check budget. consecutive_failures is the count of
    // prior consecutive restart-eligible failures (the same counter
    // backoff uses in Step 3). It resets to 0 only after the service
    // stays Active for RestartWindow seconds -- it is NOT a count of
    // restarts within a trailing window.
    if consecutive_failures >= 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)

RESTART_AFTER(delay) places the service in the Backoff state for delay seconds; when the delay elapses the service transitions to Starting and the normal activation sequence (and its StartTimeout) begins. A restart-policy retry therefore never passes through Failed -- Failed is reached only via STAY_FAILED (RestartPolicy=Never, invalid policy for CleanExitRestart, or budget exhausted). This is why OnFailure (§5.2), which fires on entry to Failed, does not fire on each retry, only when the service finally fails out. While in Backoff the service is down and does not satisfy dependents; an explicit start honors the remaining delay and a stop cancels the pending restart (§11.2).

§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

Once RestartMaxRetries restarts have occurred without the service recovering -- that is, without it staying Active for RestartWindow seconds to reset the counter -- the next failure is not restarted: 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. A service that recovers and stays Active for longer than RestartWindow between crashes therefore never exhausts its budget -- each crash starts from a counter of zero. Only failures recurring faster than the service can sustain RestartWindow of health accumulate toward RestartMaxRetries.

§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: Issue the reload and enter the Reloading state.
    // ExecReload is either a signal (e.g. "signal:SIGHUP") or an
    // external command. An external command runs in the service's
    // hooks/ sub-cgroup under the service's own Identity (§3.3) --
    // never peinit's token, and HookIdentity does not apply.
    service.state = Reloading

    if service.exec_reload is null:
        send SIGHUP to the main process
        return await_signal_reload(service)
    if service.exec_reload starts with "signal:":
        send the named signal to the main process
        return await_signal_reload(service)
    else:
        materialise the service token, fork the command into hooks/,
        exec it, and wait for it to exit
        return await_command_reload(service)

// Signal / SIGHUP path: there is no command exit to observe, so
// completion is inferred from the main process's sd_notify protocol.
await_signal_reload(service):
    start detection_window timer (2 seconds)

    on READY=1 (any time):
        service.state = Active
        return "confirmed"
    on RELOADING=1 within detection_window:
        cancel detection_window
        start extended_wait timer (StartTimeout)
    on detection_window expired (no RELOADING=1):
        service.state = Active
        return "advisory"
    on extended_wait expired (no READY=1):
        log warning: "service signalled RELOADING=1 but never
                      completed reload"
        service.state = Active
        return "advisory"

// External-command path: the command's exit gates FAILURE; the main
// process's READY=1 (if any) gates CONFIRMATION.
await_command_reload(service):
    on command exits non-zero:
        log error: "ExecReload command failed (exit <code>)"
        service.state = Active   // a failed reload does NOT kill a running service
        return "failed"
    on command runtime exceeds StartTimeout:
        SIGKILL the command and its hooks/ descendants
        log error: "ExecReload command timed out"
        service.state = Active
        return "failed"
    on command exits zero:
        service.state = Active
        if READY=1 was received from the main process during reload:
            return "confirmed"
        else:
            return "advisory"

The detection window duration (2 seconds) is fixed and is not configurable via the registry. A failed reload (either branch) leaves the service Active -- reload failure is reported to the caller but never transitions a running service out of Active.

§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 → Backoff (then Starting after the backoff delay).
• 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. This concerns the service's main process crashing -- distinct from an external ExecReload command exiting non-zero, which is the "failed" reload outcome above and leaves the main process (and the service) running.

§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" -- READY=1 was received (signal path), or the ExecReload command exited 0 and READY=1 was received.
• "mode": "advisory" -- the detection window expired without RELOADING=1, the extended wait expired without READY=1, or the ExecReload command exited 0 without a READY=1 from the main process.
• "mode": "failed" -- the ExecReload command exited non-zero or timed out. The service remains Active.

§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 (§11.1).
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 (§10.1). 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 Multiple validation findings

A service can have more than one validation finding in the same graph validation pass. peinit MUST retain and log all findings for diagnostics. The service runtime state records a single primary Failed cause. When multiple failed causes apply to the same service, peinit MUST choose the primary cause by this precedence:

1. CycleDetected
2. ValidationError
3. DependencyFailure

This precedence affects only the primary cause stored on the service state. It MUST NOT suppress logging of the lower-precedence findings, Safe-mode downgrade evidence, or any other validation side effect required by this section.

§6.2.1.2 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 (§2.3). 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.3 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.4 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.5 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.6 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 §4.2.

§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 §10.1. 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 as a KMES event.
• 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 via KMES (kmes_emit) containing the full job record, then drop the job from memory.

peinit does not maintain job history. eventd is the historian -- it consumes these events from the KMES kernel ring buffer.

§7.1.6 Event emission

peinit MUST emit structured events via KMES (kmes_emit / kmes_emit_batch; eventd consumes them from the kernel ring buffer, not over any socket from peinit -- see §11.1) 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.

The event type is the dotted string above (job.created, …); the listed per-event fields form the event payload, encoded as msgpack per the KMES event-record format (PSD-003). The same encoding applies to the operation events in §8.1.

All stdout/stderr from a job's process MUST be forwarded to eventd's log socket with the job's GUID in the log record's job_id field (PSD-008 §4.2) -- this is the log path, distinct from the KMES event path above. It 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 via KMES (kmes_emit).
    emit job.created, job.started, job.ended

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.

External dependency (JFS). The pseudocode above shows the shape of the JFS consumption protocol, not its wire interface. The byte-level /dev/jfs ABI is owned by the JFS kernel subsystem, not by PSD-007, and no JFS spec exists yet. In particular, JFS -- not this spec -- defines: the encoding of the request (job definition) read from the device; the kernel mechanism by which the caller's token_fd is delivered into peinit's descriptor table on read (a device read returns bytes, not a descriptor, so fd delivery requires explicit kernel support); and how the job id or error is written back to unblock the caller. peinit's JFS consumption is therefore not fully implementable from PSD-007 alone; this section becomes normative once JFS is specified.

§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, Boot, Shutdown,
                              // 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.4 Operation sources

Operation sources identify why peinit created an operation:

§8.1.4.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.4.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.4.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.4.4 Reload

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

§8.1.4.5 Reset

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

§8.1.5 Timeout

Start, reload, and reset operations inherit their target service's StartTimeout as their maximum lifetime. Stop operations inherit their target service's StopTimeout as their maximum lifetime. Restart operations have two timeout legs: the stop leg uses StopTimeout and the start leg uses StartTimeout. The maximum restart operation lifetime is the sum of those two legs, and each leg is still enforced against its own timeout.

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. For restart operations, queue time counts against the combined operation lifetime before the stop and start legs execute.

§8.1.6 Retention

peinit retains operation objects in memory while they are Pending or Running. Terminal operations (Completed, Failed, Cancelled, Merged, Aborted) are emitted as structured events via KMES 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 -- it consumes these events from the KMES kernel ring buffer.

§8.1.7 Event emission

peinit MUST emit a structured event via KMES (kmes_emit; eventd consumes it from the kernel ring buffer, not over a socket from peinit) 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.8 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 (§5.2), 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 §6.1.

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

Boot-generated per-service start operations use source Boot. Shutdown-generated per-service stop operations use source Shutdown.

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

§9.1.1 Calendar expressions

Timer schedules use systemd's OnCalendar expression format. The grammar below is normative and self-contained: an implementation MUST parse exactly this grammar.

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

§9.1.1.1 Fields and defaults

A time-only expression (e.g. 02:00:00) implies date *-*-*. When only Hour:Minute is given, the seconds component defaults to 00.

§9.1.1.2 Component syntax

Each numeric component (year, month, day, hour, minute, second) and the weekday accept:

• Wildcard: * matches any value.
• List: comma-separated values, e.g. 1,15 -- matches any listed value.
• Range: two values separated by .., e.g. Mon..Fri or 8..17 -- matches the inclusive range.
• Repetition: a value or range suffixed with / and a step:
  • value/step matches value and value plus every multiple of step (e.g. 0/15 in the minute field matches 0, 15, 30, 45).
  • start..end/step matches start, then start+step, start+2xstep, ... up to and including end.

Weekdays are English names, case-insensitive, abbreviated (Mon) or full (Monday), and accept lists and .. ranges.

§9.1.1.3 Last day of month

A ~ may be used in place of the - separating Month and Day to count the day from the end of the month -- Year-Month~Day, where ~01 is the last day, ~02 the second-to-last, ~03 the third-to-last, and so on. Repetition combines with ~: Mon *-05~07/1 means "the last Monday in May." Thus *-*~01 is the last day of every month and *-02~03 is the third-to-last day of February.

§9.1.1.4 Special expressions

The following named shortcuts are accepted, each equivalent to the calendar expression shown:

§9.1.1.5 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.6 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.7 Precision

Precision is second-level. Unlike systemd, peinit does NOT support sub-second fractional seconds in the seconds component -- service scheduling has no use for finer granularity, and dropping it keeps the parser simpler. A fractional second in an expression MUST be rejected as a parse error.

§9.1.1.8 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 an absolute CLOCK_REALTIME timerfd for next
    // (TFD_TIMER_ABSTIME | TFD_TIMER_CANCEL_ON_SET; see Clock behaviour)

§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\. A schedule string contains characters (spaces, :, *) that may not be valid LCS value names (PSD-005), so the value name is the schedule string with every character outside [A-Za-z0-9._-] percent-encoded -- the same injective encoding used for cgroup ids (§4.1). For example the schedule *-*-* 02:00:00 is stored under the value name %2A-%2A-%2A%2002%3A00%3A00.
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

Calendar timers are wall-clock schedules, so peinit MUST arm them as absolute CLOCK_REALTIME timers: timerfd_settime with TFD_TIMER_ABSTIME | TFD_TIMER_CANCEL_ON_SET, set to the computed next occurrence (plus jitter). TFD_TIMER_CANCEL_ON_SET makes the timerfd read() return ECANCELED whenever the realtime clock is discontinuously changed (NTP step, manual set); on ECANCELED peinit MUST recompute the next occurrence against the new wall clock and re-arm. This keeps a schedule like *-*-* 02:00:00 anchored to 02:00 wall-clock across clock corrections.

Interval timers -- the watchdog, health checks, restart backoff, and the Start/Stop/Reload phase timeouts -- are genuine relative durations and MUST use CLOCK_MONOTONIC. They MUST NOT lurch when the realtime clock is set: "wait 30 seconds" means 30 elapsed seconds regardless of wall-clock adjustments.

Last-run timestamps are stored on CLOCK_REALTIME (recording when a timer actually fired).

• Realtime clock step (NTP or manual), runtime: the armed absolute timer is cancelled (ECANCELED); peinit recomputes the next occurrence against the new wall clock and re-arms. A backward step pushes the next firing later; a forward step that crosses a missed occurrence fires it once (see below).
• Suspend / resume: an absolute CLOCK_REALTIME deadline that elapsed while suspended fires once on resume. peinit fires a missed occurrence once -- not once per occurrence that elapsed during the gap.
• Missed wall-clock occurrence within one uptime: fire once, then compute the next future occurrence normally. peinit MUST NOT replay every occurrence that elapsed during the gap. (This mirrors the persistent cross-reboot catch-up rule.)
• 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. The runtime half of this is mitigated by CANCEL_ON_SET -- once NTP corrects the clock, armed calendar timers are cancelled and recomputed -- but the boot-time catch-up decision is already made by then, so this remains a known edge case short of NTP-aware 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 the Phase 1 virtual filesystems peinit mounted (/run, /dev/shm, /dev/pts, /sys/fs/cgroup).
2. /dev, /sys, /proc are left mounted (kernel needs them).
3. 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 (§11.1) 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 (§5.3). 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 Error codes

The code field of an error response MUST be one of the following canonical values. The message field is human-readable and non-normative.

Connections that exceed MaxControlConnections are rejected at the socket level before any request is read; that rejection is a connection close, not one of the error codes above.

§11.1.1.3 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 PSD-004.

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

A connection is "idle" only when it has no in-flight request. A connection blocked awaiting completion of a wait=true operation MUST NOT be treated as idle, even when the operation runs longer than ConnectionTimeout. peinit MUST keep such a connection open until the operation resolves, bounded by the operation's own timeout (e.g. StartTimeout) rather than ConnectionTimeout.

§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 and its entry is finally discarded -- immediately if the service was not running, or on the running instance's exit otherwise (§3.5). All associated state, including stored fds, is discarded at that point.

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 uses a Unix stream socket with epoll; eventd's log socket is a Unix datagram socket. Token requests to authd are state-machine driven with timeouts -- if authd is unresponsive, the service start fails rather than PID 1 hanging.

Structured events (job and operation lifecycle, audit records) are NOT sent over any of these sockets. peinit emits them via the KMES kmes_emit / kmes_emit_batch syscalls into the kernel ring buffer, whence eventd consumes them. KMES is the sole event path (PSD-003) -- there is no event socket to eventd.

§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" (§5.3).

§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: the service is already in the command's target state and no operation of this type is in flight. Return current state (not an error).
• MERGE: an operation of this type is already in progress. The command merges into it (§8.2); the caller receives the in-flight operation's GUID and, when waiting, blocks on that operation's terminal state.
• 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 (§8.2).

In the Backoff column the service is down with an automatic restart pending (§5.1): start merges into that pending restart and honors the backoff delay; stop cancels the pending restart (the service goes Inactive); restart cancels the automatic restart and performs an admin-initiated one; reload and reset are invalid (no process exists).

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

The definition_removed field MUST be true when the service's definition has been removed from the registry but a running instance is still draining (§3.5), and false otherwise. A start, restart, or reload on a definition-removed service returns UNKNOWN_SERVICE; stop drains it.

The health field MUST be one of:

§11.2.7 list response

list returns every service the caller can query, with a compact per-service summary. Services for which the caller lacks SERVICE_QUERY_STATUS are omitted (not denied).

{
    "status": "ok",
    "services": [
        {"service": "jellyfin", "state": "active", "cause": "explicit_start", "health": "healthy"},
        {"service": "registryd", "state": "active", "cause": "dependency_start", "health": null}
    ]
}

§11.2.8 operation-status response

operation-status returns the state of a single operation by GUID. If the GUID is unknown or its record has been dropped after the retention grace (§8.1), peinit MUST return the UNKNOWN_OPERATION error (§11.1).

{
    "status": "ok",
    "operation": {
        "id": "e5f6g7h8-...",
        "type": "start",
        "service": "jellyfin",
        "source": "admin",
        "state": "completed",
        "result": "active",
        "merged_into": null,
        "error": null,
        "requested_at": "...",
        "completed_at": "..."
    }
}

The operation state MUST be one of pending, running, completed, failed, cancelled, merged, or aborted (§8). result carries the resulting service state on success; error carries the failure reason on failed; merged_into carries the surviving operation's GUID on merged. Fields that do not apply to the current state MUST be null.

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.

The child's stdin MUST be redirected to /dev/null. peinit does not provide an interactive input channel to services; a service that requires input MUST obtain it through an explicit mechanism (a socket or a stored fd), never inherited stdin.

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 log buffer

Before eventd starts there is nowhere to send service logs -- eventd's log datagram socket does not exist until eventd binds it. peinit MUST therefore buffer captured stdout/stderr in a fixed-size in-memory pre-eventd log buffer (default 1 MB). When the buffer fills, the oldest entries MUST be dropped.

peinit's own audit records (access denials, critical failures, recovery-mode entry, graph errors, security-relevant state transitions) are events, not logs: peinit emits them via KMES (kmes_emit), and the KMES kernel ring buffer persists them from the moment PKM loads -- before eventd, before the registry. peinit therefore keeps NO pre-eventd buffer for them; eventd picks them up from the kernel ring buffer when it attaches (see §11.1).

§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 read from its pipe, the kernel pipe buffer fills and the service's write() calls to stdout/stderr block. This is deliberate -- the service naturally slows down. Backpressure via the pipe is the flow-control mechanism between the service and peinit; at this stage peinit MUST NOT drop output -- it MUST keep reading the pipe within its per-iteration budget.

Downstream of the pipe, delivery is loss-tolerant by design: the pre-eventd log buffer drops oldest entries when full, and eventd's datagram log socket may drop records under load (see Lossy log delivery). The no-silent-drop guarantee covers reading the pipe, not delivery to eventd -- logs are a best-effort path. Audit events are not subject to this loss; they go through KMES.

§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 begin sending to eventd's log datagram socket (path from Machine\System\eventd\LogSocketPath).
2. peinit MUST replay the pre-eventd log buffer (oldest first), preserving each line's timestamp and metadata. This replay is best-effort: the records are msgpack datagrams on a loss-tolerant socket (PSD-008 §4.2), so some MAY be dropped by the kernel under load. peinit MUST NOT block waiting to deliver them.
3. peinit MUST switch to real-time forwarding -- new service output is sent as it arrives, as msgpack records (batched as an array of maps under load).
4. The pre-eventd log buffer is cleared.

From this point, peinit is a pipe relay: read from service pipes, tag each line with metadata (service name in origin, stream in is_error, the line timestamp, and the job's job_id), and forward as msgpack datagrams. Audit records continue to flow as KMES events, independent of this log path.

§12.1.5.1 Lossy log delivery

The eventd log socket is a non-blocking Unix datagram socket. If eventd cannot drain it fast enough, its SO_RCVBUF fills and the kernel drops further datagrams silently (PSD-008 §4.2) -- log ingestion MUST NOT exert backpressure on senders. peinit therefore keeps no stream-style outbound write buffer: it sends each record (or batch) as a datagram and accepts that some MAY be dropped under load.

peinit MUST NOT block on a send to eventd and MUST NOT allow unbounded memory growth from pending log records.

§12.1.6 eventd failure

If eventd crashes after it was running: