Job, Operation, Attempt and Event¶

A Job represents the user's persistent work, a Run stores its internal record, an Attempt identifies one execution, and Events record facts during processing. Records and files awaiting acceptance have lifetimes that continue after execution ends.

See Jobs and storage for creating and finding Jobs from the CLI. Each current Job has one internal Run record; disk run-* IDs, run.json and Run Bundle names remain unchanged for compatibility.

The single-node daemon manages OpenSandbox-profile sb-* sandboxes through VM-only NativeRuntime. Private supervisor records bind each generation to native Run/Attempt IDs; sandbox IDs are not public Job IDs. The API does not implement stage/apply, checkpoints or Run Bundle export. Native execution is embedded, but the Job workflow below is not automatically exposed; external orchestration owns cross-host identities.

Operation: the object being processed¶

Job describes the user's work; Operation describes what pVisor processes. The current production operation is run.execute, containing the program, arguments and working directory along with effective policy decisions and Placement. pvisor owns admission, actual rewrites, scheduling and execution; core defines the records.

Events are externally observable facts; Trace records them. They describe requests, actual rewrites, placement and results. They are not the operation itself and do not guarantee replay of external effects from logs alone. See Operation and Event for fields and causality.

Run: the internal Job record¶

Run identifies a command, configuration and result independently of the OS PID. After the process exits, local records let status, apply and drop refer to the same work. Use status --review to inspect the Run Bundle and staged changes.

Attempt: one execution¶

Attempt identifies one execution by an executor. Each current PVisor::run creates one Attempt. Session in pvisor owns preparation, cancellation, cleanup and terminal publication; Session is the lifecycle owner.

Admission resolves the driver network configuration once, applies scoped policies and carries that final configuration into Attempt preparation. Gateway, explicit proxy and VM networking consume it rather than re-reading the original configuration. Guest workspace overlays require an explicit executor opt-in; executor names are descriptive records, not capability checks. The actual VM network attachment path determines non-bypassable network markers; the backend name is not used for this decision.

Workspace fork creates a file branch from a logical checkpoint; execution fork restores a new Job from a supported machine checkpoint. Both retain lineage, with restoration scope determined by checkpoint kind.

The durable Job service also owns completion publication. ManagedJobRun gives the actual Attempt join and Server::finish to a runtime task; frontends hold a wait adapter. A failed or dropped frontend wait requests cancellation, while accepted completion work continues reconciling and publishing as long as the Tokio runtime remains alive. Runtime shutdown and host-process exit retain their own recovery boundaries.

Attempt completion¶

An Attempt with retained storage confirms its result through completion.json. The receipt contains RunResult and a BLAKE3 digest of the saved Bundle bytes. Validation checks Run/Attempt identity, terminal state, exit code and start/finish times. Run and execution Job states project that result. A terminal field, Bundle file or process exit alone cannot confirm completion.

Session advances normal finalization serially:

1. Stop managed writers, clean up attachments and check observations; synchronize and seal staged files under the stage contract.
2. Save the Bundle, fixing the result, observations and warnings known during finalization.
3. Save the Run state projection and commit the completion receipt binding that result and Bundle.
4. Publish Completed and the run.completed, run.failed, run.cancelled or run.hibernated terminal event. The durable Job service publishes Job state after joining the Attempt.

Once the receipt commits, terminal-event write failure is an audit gap reported through the run return and logs. It neither rewrites the bound Bundle nor publishes an opposite terminal state. Reconcile the execution result and event coverage separately: a valid completion receipt may exist without terminal events.

After owner exit, when the Attempt is no longer held, reads and recovery check its receipt. A valid receipt reconciles Run and an execution Job still targeting that Attempt. Old results cannot overwrite a Job that has advanced to another Attempt or withdrawn continuation rights. A missing receipt retains the stage and yields Unknown. review supplies no unconfirmed execution result; apply, drop and capture requiring a stopped Attempt refuse execution. Corrupt data, digest mismatch or foreign identity returns an error rather than rewriting records to manufacture success.

The receipt binds the Attempt result and Bundle without spanning Journal, apply ledgers, snapshot publication and external services in one transaction. In-memory execution has no such disk receipt. Records and version matrix owns legacy reading rules; Failure semantics owns lost-response recovery.

Source entry points: pvisor/src/session/lifecycle.rs, runtime/attempt.rs, runtime/completion.rs, runtime/registry.rs and runtime/job_service/views.rs. Tests in completion.rs cover repeated commit, identity/digest checks, missing receipts and state projection. Platform and process-fault coverage require separate acceptance.

Effect: consequences of execution¶

For staged files, the current workflow is:

run → stop → review → apply selected files → review remaining changes → apply or drop

Successful process exit and successful file application are separate results. Files from a failed command remain reviewable; later drop does not undo files already applied.

Network requests and external service changes are effects too. File staging neither delays them until approval nor rolls them back.

Checkpoint: filesystem snapshot¶

Default fork --state workspace snapshots the upper layer of a stopped staged Run. The embedded API also supports cooperative AgentCtl quiescence. Checkpoints preserve staged files, the conflict baseline captured at first modification and lineage. They do not save process memory or external service state, or freeze all lower layers. The manifest is published only after snapshot contents are synced to disk. Embedded callers use restore_logical_checkpoint(checkpoint, destination_upper, destination_preimages) to restore files and conflict baselines together.

Native VM checkpoint --kind execution seals a consistent CPU, RAM, device and filesystem execution point. Suspend requires the original VM termination receipt; resume retains the Job ID and creates a new Attempt, while execution fork creates a new Job and private writable layers. Apply/drop are unavailable while suspended; kill first withdraws continuation rights. See the CLI reference for profile and compatibility limits.

See Review and apply for steps and Capabilities and evidence for guarantees.