> Source: https://vitna.ai/docs/cli/aperture/workloads
> Raw Markdown: https://vitna.ai/docs/cli/aperture/workloads.md
> Corpus index: https://vitna.ai/llms.txt

# Workload commands

Entering and correcting the things you run.

```bash
npm run aperture:workloads
npm run aperture:workload:add -- --id <org/slug> --name "..." --class model --incumbent <sku> --unit-label "..." --priority economics
npm run aperture:workload:edit -- <id> [flags]
npm run aperture:workload:profile -- --workload <id> [flags]
```

`workload:add` also takes `--volume N`, and repeatable `--profile k=v` and
`--constraint k=v`.

## Listing

`aperture:workloads` prints every workload, what it is running now, and where
one cannot be decided on, the reason.

Printing the blocking reason beside the workload is the point. A register that
listed workloads and left you to discover which were undecidable would send you
to the failure one command at a time.

## How far round the loop each one has come

Every workload prints a rung count and one next step:

```
  progress      4 of 10 steps of the loop
  next          npm run aperture:candidate:add -- --workload acme/lane --sku <sku>
                Something to move to. A firing with no candidate has nothing to propose.
```

The ten rungs are the loop in the order a workload climbs it: registered, an
incumbent named, a unit profile, a candidate in play, a measurement, a decision
taken, a ruling, a watch armed, production coming back, and a runtime rather
than a person being what sent it.

**It is a meter and not a score.** A workload on four rungs is one somebody has
got four steps into, and the line under the count says what to type rather than
what is missing. There is no percentage, deliberately.

The next step is always the first unmet rung you can act on now, which is why a
waiting proposal is what you are told to rule on rather than being told to arm
another watch, and why a workload with nothing proposed is sent back to the
engine rather than to an acceptance with nothing to accept.

Two rungs are worth reading carefully. **Production coming back** is any window
of usage the register holds for the workload, however it arrived. **A runtime
pushed it** is narrower: a reading carrying latency and tokens, which only a
runtime produces, since a reading typed from an export carries none of them.
Nothing here can see a policy file or a running process, because neither leaves
a row, and a rung the record cannot answer would be a rung that lies.

## The four refusals on entry

`aperture:workload:add` refuses:

| Refusal |
|---|
| An incumbent the registry does not hold |
| An incumbent from another market |
| A profile key the class does not spend |
| An incumbent with no profile to spend it against |

All four are the same principle: a workload the engine cannot reason about
should fail at entry, loudly, rather than produce a confident brief later from
inputs that never made sense.

## A workload is a registry row, not a record

`aperture:workload:edit` corrects one, because a workload is a description of
something you run and descriptions are wrong sometimes.

Evidence and decisions are not editable. Those are the record, and they stay
append-only.

`--env-key` and `--policy-alias` set the
[delivery target](../../routing/delivery.md): the first is a variable a consumer
loads, the second a lane a runtime resolves, and a workload may carry both. They
merge, and an empty value removes that half.
