Power Capabilities and Wake-on-LAN

1. Issuing a command is not proof of a power-state transition

Node power control contains at least three separate events: a request is issued, delivery may or may not occur, and the actual state must then be observed. SetSuspendState or a sent Magic Packet is only an action mechanism. Without independent telemetry, keep the outcome UNKNOWN or another bounded non-success state; command success alone is not READY.

2. LOC-015 ownership boundary

This lesson owns only the Node Power Capability & Wake Verification Matrix v1: capability → authorization/privilege → bounded request → delivery evidence → observed liveness → application readiness. LOC-013 owns the Control Grant, LOC-014 owns Resource Envelope, and LOC-016 owns Desired State reconciliation. Their outcomes are inputs, not logic to absorb here.

3. Record capability before requesting an action

Each node needs a versioned power_capability_version tied to explicit evidence. For wake, keep nic_magic_packet_capability and wake_enabled separate. A MAC address does not prove that the adapter supports Magic Packet or that wake is currently enabled. Capability is a prerequisite, not delivery proof.

4. Power states are not equivalent

Sleep, hibernate, shutdown, and hybrid shutdown do not have identical wake behavior. Windows documentation makes WoL support power-state dependent and does not treat Fast Startup/S5 like S3 or explicit hibernation. observed_power_state must therefore participate in the decision instead of collapsing all “off” states into one boolean.

5. Privilege and project authorization are separate layers

On Windows, suspend/hibernate via SetSuspendState requires SE_SHUTDOWN_NAME. MAKNOW also requires the applicable project grant. A valid grant does not prove OS privilege, and OS privilege does not create project authorization. Power actions should keep both evidence layers auditable.

6. A Magic Packet is only a delivery attempt

A Magic Packet commonly carries the wake pattern based on the target MAC, but packet construction does not prove that the frame reached the NIC. Record target_mac, network_path, the relay/broadcast mechanism, and delivery_evidence separately. If the path is unknown, at most record a bounded attempt and preserve UNKNOWN until independent observation arrives.

7. Keep wake-enabled separate from wake-capable

An adapter may support wake by Magic Packet while the current setting is disabled. nic_magic_packet_capability=SUPPORTED with wake_enabled=FALSE is a valid state and should block dispatch. Do not promote historical capability inventory into effective enablement.

8. Keep request issuance separate from delivery evidence

request_issued=true only proves that the coordinator started an attempt. A local suspend call may be accepted; a remote wake may be handed to a relay. Neither proves the node's final state. delivery_evidence can be SENT, UNKNOWN, or FAILED, and all still require post-transition observation.

9. Heartbeat means awake, not necessarily ready

An identity-bound heartbeat strengthens liveness evidence, but the application can still be NOT_SERVING. When heartbeat_after_wake=true and health_after_wake=NOT_SERVING, the result is NOT_READY, not READY. Readiness closes only after valid health/readiness evidence.

10. Timeout and retry must be bounded

A wake loop must not send Magic Packets forever. Record a finite timeout, retry_state, and manual-recovery path. When the network path or delivery is uncertain, retry only within a declared budget; after exhaustion, move to a bounded DEGRADED/BLOCKED or manual recovery state.

11. Shutdown and sleep are evidence-confirmed too

Do not equate a shutdown or suspend request with the observed transition. If project authorization or required privilege is missing, return DENIED. If the request was issued but the follow-up observation cannot prove the expected state, preserve UNKNOWN. The evidence contract applies in both directions.

12. The matrix needs reason and recovery

Every row should include final_state and reason, plus manual_recovery or a recheck trigger when closure is incomplete. Examples: “WoL capability unsupported; do not dispatch” or “path unknown; refresh relay/path evidence.” Without a reason, later audit cannot reconstruct why automation stopped.

13. Worked example: N-31 on the local LAN

N-31 is in S3, the grant is valid, the adapter supports Magic Packet, wake is enabled, and the local path is reachable. A packet is sent; seconds later an identity-bound heartbeat returns and the health endpoint reports SERVING. Only then may the matrix record READY. Packet-send alone never earned that state.

14. Deterministic failure probes

Run four mutations: remove Magic Packet capability while keeping MAC and grant valid; change the path to UNKNOWN; return heartbeat but keep health NOT_SERVING; and remove shutdown privilege for a shutdown request. The results must respectively block dispatch, preserve unknown outcome, return NOT_READY, and return DENIED. No optimistic shortcut is allowed.

15. Transfer: remote site with a trusted relay

Move the same workflow to a site where direct broadcast is unavailable and a trusted relay emits the wake packet locally. Capability and grant semantics remain, but network_path, delivery evidence, timeout, and recovery are recomputed. Do not copy the local-LAN decision; READY still requires identity-bound heartbeat and health at the remote site.