vitna.ai/docs/concepts/decision Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/concepts/decision
> Raw Markdown: https://vitna.ai/docs/concepts/decision.md
> Corpus index: https://vitna.ai/llms.txt

# Workloads, triggers and decisions

Aperture, the engine half. Witness records what things cost; Aperture decides
whether a change is worth making, and records that nobody has acted on it yet.

## Workload

A thing you run: a name, the [sku](sku.md) it currently runs on, the unit it is
measured in, a priority, and a usage profile.

The registry refuses a workload whose incumbent is unregistered, whose incumbent
belongs to another market, whose profile names a key its class does not spend,
or whose incumbent has no profile to spend it against. Those refusals are the
point: a workload the engine cannot reason about should fail at entry rather
than produce a confident brief later.

A workload is a registry row and not a record, so it can be corrected with
`aperture:workload:edit`. Evidence and decisions cannot: those stay append-only.

## Candidate

A sku in play against the incumbent for a given workload.

## Evidence

A measurement about a candidate: a kind, a label, a date, a sample size `n`, one
or more metrics, and a source reference that is a URL or a commit.

Recording a metric the engine never reads is refused. A measurement nothing
consumes is a number that looks like evidence and functions as decoration.

## Trigger

An armed watch on the record. `price_move` with a threshold percentage is the
worked example.

A trigger fires when the record moves past its condition, and firing spends it:
it will not fire again until a decision arms a new one. That is what stops one
volatile cell from producing the same notification every hour until it is muted,
and muted watches are how monitoring systems stop being read.

```bash
curl "https://vitna.ai/api/v1/watches?state=armed"
```

## Decision

What the engine proposed, and what a person did about it.

| Status | Meaning |
|---|---|
| `proposed` | The engine produced a brief. Nobody has ruled on it. |
| `accepted` | A person accepted it, arming the next review. |
| `superseded` | A person refused it, with the reason kept on the row. |

```bash
curl "https://vitna.ai/api/v1/proposals?status=proposed"
```

`meta.awaitingReview` counts the proposals waiting on a person, which is the
number worth watching in this record.

The third row is the one worth reading twice, because the word invites the
opposite reading. `superseded` is written by one act only, a person refusing a
proposal, from the prompt or from the console, and both keep the reason on the
row. A decision that is merely overtaken by a later one **keeps its own
status**: an accepted decision stays accepted forever, because what it records
is that somebody accepted it at the time, and that stayed true. Which decision
a workload is currently running is the chain of supersessions, never this
column. This table said "it was overtaken without being accepted" until
2026-08-26, which described neither.

## One decision has an address

Every decision an org publishes is a page:

```
https://vitna.ai/decisions/{id}
```

It carries what `/api/v1/proposals` carries plus the brief the run wrote, the
chain on either side of it, and a section naming the columns the row does not
hold and why each one is allowed to be empty.

The gate is the same one this whole register is published under. A decision has
a page exactly when it has JSON: `org.feed_public` decides, and an org whose
feed is private has neither. A decision belonging to such an org answers 404,
identically to an id nobody ever issued, because which of the two it was is
information about somebody else's register.

## Inputs are published

Every decision carries the exact `witness.price_period` and `aperture.evidence`
ids the run read. All of them are append-only, so a brief can be regenerated
and checked at any distance.

Publishing the verdict without them would be publishing an opinion.

## Exporting a signed decision pack

Step 8 of model change control. Any accepted or recorded decision exports as
a signed decision pack:

```bash
npm run aperture:decision:pack -- <decision_id> --out ./audit-pack.json
```

A decision pack bundles:

1. The decision and the provenance absences saying what was not recorded.
2. The exact `witness.price_period` records and observation leaves with their Merkle leaf hashes.
3. The exact `aperture.evidence` measurements and SHA-256 evidence digests.
4. The canonical payload digest and an Ed25519 signature from the authority.

It is verifiable offline without network or database access:

```bash
npm run aperture:decision:pack -- --verify ./audit-pack.json --key <public_key>
```

Public decisions can also be downloaded directly from `/decisions/{id}` or
via `GET /api/v1/decisions/{id}/pack`.

## The engine proposes and does not act

Worth being unambiguous, because "decision engine" invites the opposite
assumption.

Running the engine writes a proposed decision. Nothing is accepted, and nothing
is routed. Accepting is a person's act through the CLI, and acceptance is
refused if the record moved underneath the proposal, so a stale brief cannot be
accepted into force.

This is enforced below the application, not just in the UI, and the exact grants
are worth stating because they are narrow rather than absent.

**Two application roles hold `UPDATE` in `aperture`, each on named columns of
one table and nothing else:**

| Role | Table | Columns | Since |
|---|---|---|---|
| `vitna_collector` | `aperture.trigger` | `fired_at`, `fired_by_event_id` | `0009` |
| `vitna_console` | `aperture.decision` | `status`, `note`, `ruled_by`, `ruled_at` | `0021` |

The first records that a watch fired. The second records a person's ruling and
who made it. Nothing holds `UPDATE` on a workload, a candidate or a measurement
at all, and nothing anywhere can touch a decision's outcome, thresholds,
inputs, reason or brief: those are fixed at insert, so a correction is a new
decision that supersedes the old one and never an edit.

So the property is not that a decision cannot be changed. It is that the only
thing anything can change about a decision is what a person decided about it,
and widening that needs a migration granting a privilege that does not exist.

Until 2026-08-26 this page claimed the schema held no such grant at all. That
was true when it was written and `0009` ended it one phase later, which is the
argument for a table of grants over a sentence about them: the table is wrong
in a way somebody notices, and `tests/docs-drift.test.mjs` now fails if any page
or module comment goes back to claiming the absolute.

A fired trigger is a question put to a person. Vitna records the answer.
Changing what production runs happens in another system.
Human Machine Shift+M