Harden the POD job model and unify CLI/REST service interfaces

[VPRamon]

Summary

Closes #11

Before this change, the service exposed RunRequest/RunResult, while REST maintained an independent tagged JobStatus enum and string-only failure table. That split allowed lifecycle and error semantics to diverge between interfaces.

This PR introduces a canonical application job model in spod::service:

• JobId remains the shared string identity; REST generates UUID strings and synchronous callers use their configured run ID.
• JobState is the stable serializable lifecycle: pending -> running -> succeeded or pending -> running -> failed.
• JobStatus carries the ID, workflow, optional JobResult, and optional structured JobError.
• JobErrorCode provides stable machine-readable categories: configuration, input, unsupported, artifact, scientific, and internal.
• JobStore centralizes atomic in-memory transitions and deliberately releases its lock before runner execution.

REST now uses the shared status/result/error types and is limited to HTTP adaptation plus the current in-memory store. The CLI run command executes through the same service API and formats the canonical terminal status; it does not implement scientific behavior. Health remains deterministic as {status: "ok", version: ...}.

Semantics and scope

• CLI execution is synchronous and returns a terminal shared JobStatus.
• REST submission is asynchronous and returns an accepted pending status; later inspection reports running, succeeded, or failed.
• Successful status exposes hashed artifact references, including the manifest.
• Failed status exposes a stable category and human-readable message without serializing Rust error sources.
• REST storage remains intentionally in-memory and experimental. Durable persistence, scheduling, retries, distributed workers, and the versioned artifact API in Define stable product and artifact API for POD jobs #28 are deferred; this PR does not implement production infrastructure or Define stable product and artifact API for POD jobs #28.
• Architecture documentation now records the shared model and CLI/REST split.

Validation

• cargo fmt --all -- --check
• cargo check --locked --workspace --all-targets --all-features
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo test --workspace --no-default-features --no-fail-fast
• cargo test --workspace --all-features --no-fail-fast
• cargo test --doc --workspace --all-features
• cargo doc --workspace --no-deps
• bash scripts/check_dep_graph.sh
• bash scripts/check_no_todos.sh
• bash scripts/check_legacy_name_refs.sh
• cargo deny --all-features check
• Local REST smoke test covering health/version, submit, succeeded status with artifacts, and unknown job ID (404)

Review fixes

Follow-up review fixes are included in commit 456f38c: POST /jobs now always returns the retained accepted pending snapshot; REST endpoint tests cover health, submit/pending, eventual success/artifacts, failure/artifact error code, and unknown IDs; service-owned request persistence failures map through ServiceError to the artifact category; lifecycle terminal-field invariants and impossible transition handling are covered; and compiled CLI integration tests cover validation and run success/failure. The explicit example CLI commands and the full validation matrix pass.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 31bdb7ab97

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".