Definition Schema

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: