Operation

An Operation is owned execution work with explicit inputs, private writable state and declared outputs. It provides commands, filesystem capabilities, allocated tool descriptors and observable progress. It owns cleanup without choosing invocation policy.

Source and concrete API: operation.go.

Properties

Config: execution image, logical root, physical work root, network policy, source trees, jobs, logging and progress callbacks.
CacheDir: caller-owned persistent compiler cache; it outlives temporary work.
Outputs and Previous: declared and already available named results. Toolchains: allocated tool descriptors. Installing: logical installation-path mode.
Command and Result: command arguments, directory, environment, input, failure policy, captured output and exit status.
Event, Reporter and Task: phase identity, timing, declared work units and terminal outcome.

Behavior

Open materializes verified inputs and opens isolated execution. Close stops execution and removes owned temporary work. Source and previous results are read-only; work, staging, outputs and the supplied compiler cache have explicit writable mounts.

Input and import archives are written incrementally. Verification reads the captured archive against the existing immutable tree using a fixed-size byte buffer and an entry index. It compares every path, kind, mode, owner, link, device field and file byte, rejecting missing, unexpected or duplicate entries. It does not allocate another complete tree or encode payloads as JSON. Cancellation is checked between entries and byte chunks. These transport checks do not change artifact or cache identities.

Exec passes literal arguments, streams exact bytes and captures the result. No shell is implied. The base environment is deterministic; additions are explicit. Contexts are used serially.

Output declares a unique named file or subtree; declaration does not create it. Artifact retrieves an already available result. Toolchain retrieves an allocated descriptor rather than selecting a provider.

Read, Write, Copy, Mkdir, Symlink, Exists, Import and Export act only on declared paths and owned destinations. Path traversal, writes through recorded links and unsupported metadata fail. Installation paths are logical root-relative destinations, not host writes. Metadata includes modes, numeric owners and link targets independent of host privilege.

Observation

NewReporter, Reporter.Start, Task.Update, Task.Finish and Reporter.Reused report owned phases. Callbacks are serialized and each task finishes once. Success, failure, cancellation and reuse are distinct outcomes. Cache validation has real elapsed time.

Event.Log binds exact diagnostic bytes to the event’s subject and phase. A sink implementing PhaseWriter receives that identity with each write; ordinary writers receive unchanged bytes. The writer owns presentation and synchronization. Input preparation reports materialization, extraction, permission restoration and content/metadata verification before handler execution, including completion timings. It does not infer progress percentages.

Progress reports nonnegative completed and total units. A positive total requires completed units not to exceed it; zero total means unknown. Diagnostic progress does not alter content identity. Raw process output, including non-UTF-8 bytes, must remain intact. Presentation and percentage estimation are outside this contract.

Isolation

Scratch and mounted compiler caches cannot substitute for published outputs. Cancellation releases processes, containers and temporary resources while preserving caller-owned cache data and diagnostics. Source mutation may invalidate native compiler entries, but it does not authorize deleting persistent cache directories.