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 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.
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. |
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:
npm run aperture:decision:pack -- <decision_id> --out ./audit-pack.jsonA decision pack bundles:
- The decision and the provenance absences saying what was not recorded.
- The exact
witness.price_periodrecords and observation leaves with their Merkle leaf hashes. - The exact
aperture.evidencemeasurements and SHA-256 evidence digests. - The canonical payload digest and an Ed25519 signature from the authority.
It is verifiable offline without network or database access:
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.
