Jobs

Durable jobs of the three stages: states, stage progress, queue position, turns and limits, cancellation, retries, logs and failure codes.

  • Availability: Planned
  • Evidence: Read from source
  • Reference

Operations

Operation Request Capability Retry
jobs.list GET /v1/applications/{application}/jobs?state= application.read
jobs.read GET /v1/jobs/{job} application.read
jobs.cancel POST /v1/jobs/{job}/cancel release.prepare natural
jobs.logs GET /v1/jobs/{job}/logs application.read

A job is durable work that continues without an open browser tab. Reading a job never starts, resumes or schedules anything.

The job

Member Meaning
kind registration runs the stage resolve. preparation runs prepare, analyze, generate and validate.
state queued, running, waiting_turn, succeeded, failed, cancelled, limit_exceeded
stage The stage in progress, or the one where the job ended
stages One entry per stage: state (pending, running, succeeded, failed, skipped, cancelled, limit_exceeded), started, ended, done, total, and hits
plan free or premium: the scheduling policy the job runs under, fixed when it was admitted
queue Present while the job waits: position and the turns already used
registration, graph, release What the job works on
usage Milliseconds measured so far per category: wait, download, analysis, build, diagnostics
failure Required when the state is failed or limit_exceeded

hits counts units that a compatible authorized output satisfied without new execution. A cache hit adds no build time and no charge.

How free work is scheduled

Free organizations share one queue with no SLA. The scheduler gives each application a short turn, round-robin. At the end of a turn the job stops starting new modules, lets the module in progress finish within a grace period, and returns to the queue as waiting_turn. At the hard deadline the isolated worker is actually terminated; outputs that were already verified are kept.

Premium jobs run the same tasks without the short turn. They keep safety timeouts and credit limits.

When a module cannot fit

Compilation cannot be paused and resumed. A module that cannot finish inside its allowed execution budget ends in limit_exceeded, with the failure code LIMIT_EXCEEDED, and the job reports that it needs an expanded plan. It is never retried automatically, because repeating it would fail the same way.

Retries

Transient failures are retried with exponential backoff, a bounded number of times. Deterministic failures and limit_exceeded outcomes are not retried. Every attempt is recorded once, so a duplicated or late delivery of the same work cannot publish an outcome twice or charge twice.

Cancelling

jobs.cancel detaches this job from its work units. A unit that other authorized jobs still consume keeps running, and verified completed outputs are retained. Cancelling a job that already ended answers its final state, unchanged.

Logs

jobs.logs pages through persisted log lines: sequence, time, level (debug, info, warning, error), stage and message. Messages are sanitized: credentials and other tenants' data never appear. For live progress use the realtime events.

Failure codes

A failure has a code, a message, and optionally the stage, the module and compiler diagnostics with file and line. These codes travel inside jobs, releases, inventory items and events; they are not HTTP answers.

Code Meaning
RESOLUTION_FAILED The graph could not be pinned: missing version, conflicting constraints or unsatisfied peer
INTEGRITY_MISMATCH A downloaded archive does not match the pinned integrity
FETCH_FAILED A pinned package could not be downloaded
ANALYSIS_FAILED The reachable inventory could not be computed from the entries
DYNAMIC_IMPORT_UNKNOWN An undeclared dynamic import prevents a complete closure
BUILD_FAILED A module did not compile; essential build errors are always reported
CLOSURE_INCOMPLETE A required output of the serving closure is missing, failed or not retrievable
CANCELLED The work was cancelled before it completed
LIMIT_EXCEEDED The work cannot fit its execution or preparation budget
QUOTA_EXCEEDED A quota was reached while fetching or storing
CREDIT_INSUFFICIENT Credit ran out before the work could be admitted
BUDGET_EXHAUSTED The global admission budget did not admit the work
UNSUPPORTED_INPUT An input cannot be processed by this version
UPSTREAM_UNAVAILABLE A registry or provider was unavailable for an input that was not cached
INTERNAL Unexpected failure