> Source: https://vitna.ai/docs/routing/console-ruling
> Raw Markdown: https://vitna.ai/docs/routing/console-ruling.md
> Corpus index: https://vitna.ai/llms.txt

# Ruling from the console

An owner of an org can accept or refuse an open proposal at `/console`, instead
of running [`aperture:accept`](../cli/aperture/decide.md) at a prompt on the box.

This is the act the register exists for. Until it existed, `/console` could show
you a proposal and not let you answer it, which made it a window onto the
product rather than the place the product happens.

## It is a smaller change than it sounds

A decision is append-only **but for two facts a person writes**, and it was
designed that way from the first migration that created it. From the table's own
note:

> `status` records what happened to the proposal, not which decision is current.
> Append-only but for two facts a person writes through the CLI as the owning
> role, exactly as a candidate's status is written: `status` and the `note`
> giving the reason. The outcome, the thresholds, the inputs, the reason and the
> brief are fixed at insert, so a correction is a new decision that supersedes
> the old one and never an edit.

So nothing became writable here that was not already meant to be written by a
person. What changed is where that person may be standing.

Two columns were added beside those two, `ruled_by` and `ruled_at`, which say
who ruled and when. `decided_at` still means when the engine ran.

## Who may

An **owner**. A membership admits somebody to read an org's register; ruling is
a different kind of act, and it is the first thing in the record to read the
`owner` and `member` distinction that `org_member` has carried since sign-in
shipped. A member sees the proposals and no buttons.

A proposal belonging to an org this account does not own is refused by the same
sentence as a proposal that does not exist. Which of the two it was is
information about somebody else's register.

## What the two buttons do

**Accept** marks the proposal accepted and arms the next review in the same
transaction. That is one transaction on purpose: a decision recorded with
nothing watching for what would overturn it is how a stale strategy survives, so
an acceptance that could not arm must not be able to half happen.

**Refuse** needs a reason, which is kept on the row. No acceptance is written
and the decision the workload is actually running is untouched, because a
refusal is a fact about the proposal rather than a new decision about the
workload.

What a refusal does write is the watch back. A firing spends the watch that
produced the proposal, and until that was added a refusal armed nothing, so a
workload watched for a price move that refused the resulting proposal stopped
being watched for price moves. It puts back the watch that fired and only that
one: the watches armed beside it never fired and are still armed, and arming
them again would fire twice off one move. A review date is the exception and
comes back on a new date, because a date fires whenever it has passed and
putting the same one back would propose again on the next collector pass.

The reason is required for the same cause it is required at the prompt: the
engine will propose the same thing again the next time the market looks like
this, and a refusal nobody wrote a reason for is one the next reader has to make
again from nothing. The re-arm is what makes that sentence true, and the reason
travels with it: the re-armed watch records the refusal in
`armed_by_decision_id`, so the next proposal it writes carries what was said
about the last one.

Neither routes anything. Accepting a switch leaves the workload's incumbent
alone, because whether the traffic moved is not something Vitna can see.

## What it refuses

The refusals are `platform/engine/ruling.mjs`, shared word for word with the CLI.
A person at a prompt and a person pressing a button rule on the same record, so
two implementations would be two answers the day one of them was corrected.

| Refusal | Why |
|---|---|
| The proposal is already accepted or refused | Two people pressed the button. The second is told, rather than ruling twice. |
| The record moved under it | The brief's figures were derived against a tape that is no longer what the workload is doing. Re-run the engine. |
| A refusal with no reason | The next reader would have to make the judgement again from nothing. |
| An acceptance carrying a reason | The brief is the reasoning and is already in the record; that column is where a refusal's reason is read from. |

All of them except the last two are checked **inside the writing transaction**,
on the connection that writes, with the decision row locked. A proposal that was
open when the page rendered can have been ruled on by somebody else by the time
a button is pressed, so the only answer that means anything is the one taken at
the moment of writing.

## No arming flags

`--review-on` and `--price-move-pct` stay at the prompt. Accepting here arms the
defaults, which is what the CLI does when nobody passes a flag.

A threshold typed into a web form without the tape in front of you is a number
chosen to fill a field, and this record is not a place for those.

## The fifth role

Ruling writes with `vitna_console`, which exists only for this and holds:

| | |
|---|---|
| `SELECT` | `aperture.decision`, `aperture.workload`, `aperture.trigger` |
| `UPDATE` | four columns of `aperture.decision`: `status`, `note`, `ruled_by`, `ruled_at` |
| `INSERT` | `aperture.trigger`, so accepting can arm |

And nothing else anywhere. It cannot read a session, a membership, the waitlist
or the market record, and no grant lets it touch an outcome, a title, a reason,
a threshold, an input or a brief. A correction is still a new decision that
supersedes the old one, and that is a privilege the database enforces rather
than a convention the code follows.

A fifth role rather than widening `vitna_auth`, on the reasoning that made
`vitna_auth` a fourth: the value of it being separate is that a bug behind
sign-in reaches the session tables and nothing else, and letting it accept
decisions would spend exactly that. So a bug in the read path cannot rule on
anything, and a bug in the ruling path cannot reach a session.

`tests/console-ruling-scenario.test.mjs` asserts every line of that table
against a real Postgres, by being refused when it reaches past it.

## Configuring an instance

| Variable | What it is |
|---|---|
| `DATABASE_CONSOLE_URL` | The `vitna_console` role. Generated by `deploy/provision-console.sh`. |

Unset, `/console` renders the proposals and no buttons, and ruling stays a
command at a prompt. That is the deliberate degradation: a page offering a
control that would answer 503 is a page that lies about what it does.

**The provisioning script must run before migration 0021 deploys**, the way
`provision-github-auth.sh` had to run before 0013. A password can never live in
a migration, so 0021 only distributes privileges over a role it expects to
exist. A deploy that reaches the migration first fails it, which is safe rather
than silent: the hook aborts before the restart and the previous build keeps
serving.
