Serial Event And Receipt Shapes

Serial Event And Receipt Shapes

Each serial line is a JSON object followed by LF, at most 2048 bytes including that LF, UTF-8 without a BOM, with exactly these required keys:

Key	Value
schema	projectbuddy/windows-bootstrap-event@1
vmUuid, attemptId	Lowercase canonical UUID strings
bootId	Lowercase UUID string, or null only when boot identity is unavailable
event	launcher-start, launcher-result, installer-start, installer-exit, or boot-state
state	STARTED, PASS, FAIL, or UNKNOWN
reason	null, SETUP_INCOMPLETE, NOT_ELEVATED, PAYLOAD_INVALID, INSTALLER_START_FAILED, INSTALLER_FAILED, CONFIG_DRIFT, READBACK_FAILED, UNAVAILABLE, or INTERRUPTED
exitCode	Signed 32-bit process exit code for installer-exit; otherwise null
policySha256	Lowercase SHA-256 of the expected policy descriptor, or null when not yet available or unreadable

The permitted combinations are:

Event	Permitted state and reason	Exit and identity conditions
launcher-start, installer-start	STARTED, reason=null	exitCode=null; neither is success.
launcher-result	FAIL with NOT_ELEVATED, PAYLOAD_INVALID, or INSTALLER_START_FAILED; or UNKNOWN with SETUP_INCOMPLETE, PAYLOAD_INVALID, INSTALLER_START_FAILED, UNAVAILABLE, or INTERRUPTED	exitCode=null; a missing child result is never synthesized.
installer-exit	PASS with reason=null for exit zero; FAIL with INSTALLER_FAILED for nonzero	The real child exit code is required.
boot-state	STARTED with reason=null; PASS with reason=null; FAIL with CONFIG_DRIFT; or UNKNOWN with READBACK_FAILED or UNAVAILABLE	exitCode=null; PASS requires current non-null bootId and matching policySha256.

For an installer attempt, exactly one launcher-start precedes either a terminal launcher-result or one installer-start followed by the real installer-exit or an interrupted launcher-result. After a successful exit, the launcher requests a fresh witness check; a matching boot-state must occur after that exit record. A definite drift failure cannot become a pass within the same attempt; a subsequent explicitly authorized recheck is required. The host rejects duplicate JSON keys, unknown fields, invalid types, oversized or partial lines at the deadline, mismatched identifiers, and contradictory or out-of-order installer events. Records before the current file boundary are never evidence. The host evaluates the latest complete boot-state for the expected boot and attempt, then performs a separate current WinRM readback. Guest strings, raw command output, and exception text are not allowed in these records.

The expected policy descriptor is UTF-8 JSON with sorted keys, no insignificant whitespace, and these fields: schema (projectbuddy/windows-winrm-policy@1), guestPort (5985), hostAddress (127.0.0.1), hostPort (1-65535), guestAdapterMac (12 uppercase hexadecimal digits), allowedRemoteAddress (the expected canonical IPv4 NAT source address), listenerTransport (HTTP), listenerAddress (explicit * or IP: followed by the selected canonical IPv4 address), serviceStartupType (Automatic), serviceState (Running), firewallRuleName (ProjectBuddy-WinRM-HTTP), firewallEnabled (true), firewallDirection (Inbound), firewallAction (Allow), firewallProtocol (TCP), firewallProfile (Any), allowUnencrypted (false), basic (false), and negotiate (true). The host hashes those exact bytes with SHA-256. The expected source comes from verified host configuration or an explicit operator input, and is checked against the selected guest adapter and observed NAT path; it is not an assumed gateway. If that path cannot be proven, readiness fails. The guest witness and independent host readback compare individual properties as well as the policy hash.

An authorized installer run may narrow or replace a legacy rule only when its complete normalized fingerprint matches an engine-created legacy rule: VmProvisioning-WinRM-HTTP / VM Provisioning WinRM HTTP, or SandboxSbom-WinRM-HTTP / Sandbox SBOM WinRM HTTP, respectively, each inbound, enabled, allow, TCP 5985, all profiles, with unrestricted address, interface, program, and service filters. The fingerprint alone is not proof of provenance: ownership must also be established by protected installation evidence or an explicit operator attestation identifying the exact rule. A different fingerprint or an ambiguous owner is not silently modified. The new owned rule restricts the selected interface and verified NAT source; the installer does not enable broad built-in rules. An unmanaged rule that prevents proving the effective restriction blocks success rather than being silently deleted.

The host emits a redacted JSON receipt with exactly schema (projectbuddy/windows-bootstrap-receipt@1), engineCommit (full 40-character lowercase commit SHA or null if unavailable), installerSha256, policySha256, and bootEvidenceSha256 (lowercase SHA-256 strings or null if unavailable), vmUuid, attemptId, bootId, and priorBootId (lowercase canonical UUID strings or null when unavailable), phase (initial-bootstrap, authorized-rerun, readiness-recheck, fresh-start, managed-restart, guest-reboot, or register-runner), outcome (PASS, FAIL, or UNKNOWN), reason (null, IDENTITY_MISMATCH, VM_STATE_UNSAFE, LOCK_UNAVAILABLE, SERIAL_UNAVAILABLE, SERIAL_INVALID, SETUP_INCOMPLETE, NOT_ELEVATED, PAYLOAD_INVALID, INSTALLER_FAILED, INSTALLER_START_FAILED, INSTALLER_INTERRUPTED, CONFIG_DRIFT, REPAIR_NOT_AUTHORIZED, REBOOT_PROOF_UNAVAILABLE, WINRM_AUTH_FAILED, WINRM_ENCRYPTION_FAILED, CONFIGURATION_MISMATCH, RUNNER_NOT_AUTHORIZED, RUNNER_API_UNAVAILABLE, RUNNER_MISMATCH, or EVIDENCE_UNAVAILABLE), installerExitCode (signed 32-bit integer or null), and checks. checks contains exactly identity, vmState, lock, serial, boot, rebootCorroboration, installer, winrmAuth, winrmEncryption, configuration, and runner, each PASS, FAIL, UNKNOWN, or NOT_APPLICABLE.

Identity, VM state, lock, serial, boot, WinRM authentication, encryption, and configuration apply to every phase. Installer applies only to initial bootstrap and authorized rerun; runner applies only to runner registration; rebootCorroboration applies only to guest-only reboot. Non-applicable checks must be exactly NOT_APPLICABLE, and applicable checks cannot be NOT_APPLICABLE. A managed restart requires a non-null priorBootId different from bootId and observed off/on; a guest-only reboot requires that comparison and a separately verified corroboration record. A fresh-start has no previous boot baseline and is not reboot proof. A readiness-recheck with a known prior boot ID requires the same current boot ID; without a baseline it establishes current readiness only.

An overall PASS requires every applicable check to be PASS, a present engine commit, policy hash, VM UUID, attempt ID and boot ID, and reason=null. Initial bootstrap and rerun additionally require the installer hash and exit code zero. The installer hash may be absent from later-phase receipts when no previous installer hash is available; such a receipt cannot substitute for TEST-061's exact-commit/hash-bound initial bootstrap proof. installerExitCode is null in other phases. Once an independently proven guest-reboot source is specified, its redacted, schema-validated corroboration record must match bootEvidenceSha256; an arbitrary hash alone is not proof. Until that source is specified, rebootCorroboration is UNKNOWN and guest-only reboot cannot pass.

Any applicable FAIL makes the overall outcome FAIL; otherwise any applicable UNKNOWN makes it UNKNOWN. Both require a non-null reason and return nonzero. A reason must describe an actual blocking condition with the same outcome, choosing a failure over an unknown if both exist:

Reason codes	Allowed overall outcome
IDENTITY_MISMATCH, VM_STATE_UNSAFE, NOT_ELEVATED, INSTALLER_FAILED, CONFIG_DRIFT, REPAIR_NOT_AUTHORIZED, WINRM_AUTH_FAILED, CONFIGURATION_MISMATCH, RUNNER_NOT_AUTHORIZED, RUNNER_MISMATCH	FAIL
SERIAL_UNAVAILABLE, SERIAL_INVALID, SETUP_INCOMPLETE, INSTALLER_INTERRUPTED, REBOOT_PROOF_UNAVAILABLE, RUNNER_API_UNAVAILABLE, EVIDENCE_UNAVAILABLE	UNKNOWN
LOCK_UNAVAILABLE, PAYLOAD_INVALID, INSTALLER_START_FAILED, WINRM_ENCRYPTION_FAILED	FAIL for an established violation; UNKNOWN when the required fact cannot be determined

Missing required identity or other evidence is UNKNOWN, never a pass. If safe receipt creation or schema validation fails, report a safe error and return nonzero.