pika-cloud-lifecycle-loaders

The LifecycleEventKind enum duplicated every variant of RuntimeState and existed only to be converted back via From<LifecycleEventKind> for RuntimeState, which was an identity mapping. Both the enum and the impl are removed, and LifecycleEventKind becomes a simple type alias:

pub type LifecycleEventKind = RuntimeState;

A new test confirms the alias is equivalent:

#[test]
fn lifecycle_event_kind_alias_matches_runtime_state() {
    let kind: LifecycleEventKind = RuntimeState::Ready;
    assert_eq!(kind, RuntimeState::Ready);
}

This avoids the maintenance burden of keeping two identical enum definitions in sync.

A new RuntimeLifecycleLoadError enum is added with four variants covering the distinct failure modes when loading lifecycle artifacts:

Both fmt::Display and std::error::Error (with source() delegation) are implemented manually, ensuring the error messages are human-readable and the causal chain is preserved for anyhow or similar wrappers.

The type is re-exported from lib.rs so consumers outside the crate can match on it if needed.

Two new public functions sit alongside the existing raw decoders:

pub fn decode_runtime_status_artifact(
    source_name: impl Into<String>,
    bytes: &[u8],
) -> Result<RuntimeStatusSnapshot, RuntimeLifecycleLoadError>

pub fn decode_runtime_terminal_result_artifact(
    source_name: impl Into<String>,
    bytes: &[u8],
) -> Result<RuntimeTerminalResult, RuntimeLifecycleLoadError>

They delegate to the original serde_json::from_slice decoders and map the error into the appropriate RuntimeLifecycleLoadError variant, attaching the caller-supplied source_name (typically a file path or description). This pattern keeps the raw decoders available for callers who already have their own error handling while giving higher-level callers an easy upgrade path.

Three new loader functions handle the full read-decode lifecycle:

1. load_runtime_status — reads a status JSON file and decodes it into RuntimeStatusSnapshot.
2. load_runtime_terminal_result — reads a terminal result JSON file and decodes it into RuntimeTerminalResult.
3. load_runtime_events — reads an NDJSON events file line-by-line, skipping blank lines, and decodes each into a LifecycleEvent. On failure it reports the 1-based line number.

All three follow the same pattern:

pub fn load_runtime_status(path: impl AsRef<Path>) -> Result<RuntimeStatusSnapshot, RuntimeLifecycleLoadError> {
    let path = path.as_ref();
    let bytes = fs::read(path).map_err(|source| RuntimeLifecycleLoadError::Read {
        path: path.to_path_buf(),
        source,
    })?;
    decode_runtime_status_artifact(path.display().to_string(), &bytes)
}

The load_runtime_events function deserves special attention: it iterates with enumerate(), adds 1 for human-friendly line numbers, and skips empty lines to tolerate trailing newlines in NDJSON files.

In agent_api.rs the private one-liner decode_guest_lifecycle_status simply forwarded to decode_runtime_status. It is deleted and replaced with a direct call to the new shared decode_runtime_status_artifact, passing &status_path as the source name:

// Before
match decode_guest_lifecycle_status(&status_bytes) { ... }

// After
match decode_runtime_status_artifact(&status_path, &status_bytes) { ... }

The import list is updated accordingly, swapping decode_runtime_status for decode_runtime_status_artifact. The existing test is renamed from decode_guest_lifecycle_status_rejects_malformed_snapshot to decode_runtime_status_artifact_rejects_malformed_snapshot and updated to pass STATUS_PATH as the source name argument.

The pikaci executor had its own private load_guest_terminal_result that performed fs::read followed by decode_runtime_terminal_result, wrapping each step with anyhow::Context. This is replaced by a single call to the shared load_runtime_terminal_result:

// Before
let guest_result = load_guest_terminal_result(&ctx.job_dir.join("artifacts/result.json"))?;

// After
let guest_result = load_runtime_terminal_result(ctx.job_dir.join("artifacts/result.json"))
    .with_context(|| "load guest terminal result".to_string())?;

Note the subtle API difference: the shared function takes impl AsRef<Path> (owned values accepted), so the & is dropped. The .with_context() call wraps the RuntimeLifecycleLoadError in anyhow to stay consistent with the executor's existing error strategy. Both call sites in the executor (run_remote_linux_vm_job and run_tart_job) are updated identically, and the now-unused decode_runtime_terminal_result import is removed.

Six new tests are added across the pika-cloud and pika-server crates:

A helper temp_test_path generates unique temporary file names using nanosecond timestamps to avoid collisions when tests run in parallel. Tests that create files clean up after themselves with fs::remove_file.