Get started

Ruling from the console

Source

An owner of an org can accept or refuse an open proposal at /console, instead of running `aperture:accept` 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.

RefusalWhy
The proposal is already accepted or refusedTwo people pressed the button. The second is told, rather than ruling twice.
The record moved under itThe 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 reasonThe next reader would have to make the judgement again from nothing.
An acceptance carrying a reasonThe 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:

SELECTaperture.decision, aperture.workload, aperture.trigger
UPDATEfour columns of aperture.decision: status, note, ruled_by, ruled_at
INSERTaperture.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

VariableWhat it is
DATABASE_CONSOLE_URLThe 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.