Get started

Rules within a lane

Source

The per-request question, answered without an oracle: a declared predicate on an observable request attribute, routing to a named sku, shadow first.

The refused alternative, and why this shape

Within one lane, a request to find three citations and a request to synthesize forty sources are different work, and a per-lane incumbent prices both at the dearest one. The tempting answer is a classifier choosing models per request, and an unrecorded one is refused: that is a decision made a million times a day with no record, no threshold anyone wrote down and no brief anyone can regenerate. A rule is the opposite of that in every part: its predicate is declared, its terms are signed into the policy, and every request it touches resolves to a decision id.

What the refusal names is those three absences, not choosing per request. Until 2026-09-29 this page said the classifier "is refused" without the qualifier, which was wider than the reason it gave. A per-request router can keep all three: Switchyard, which Vitna is building, scores each request by rules written in its configuration, keeps one ledger row per request with the decision's reasons and no prompt text, and re-runs recorded decisions under a new policy before that policy serves. It is a separate program and not part of this runtime, and the two kinds below remain the runtime's per-request answer.

The two kinds

KindParamsMatches when
context_chars_over--threshold, in charactersThe request carries more content than the threshold
traffic_share--share, a whole percent from 1 to 99The request falls in the first share buckets of a hundred

Registering one, which is always shadow

bash
npm run aperture:rule:add -- --workload convexity/deep-research \
  --kind context_chars_over --threshold 800000 \
  --sku anthropic/claude-sonnet-5
bash
npm run aperture:rule:add -- --workload convexity/deep-research \
  --kind traffic_share --share 5 \
  --sku openai/gpt-5.6-luna

Since 2026-08-29 the same act is on the workload's own page under Start a rollout, which is the same refusals through a form: the console builds the argument vector this command would have taken and hands it to the same functions, so a sentence you see in a browser is the one you would have seen here. Promoting a rule and taking one out stayed at a prompt on purpose, and composing says why.

There is no flag that registers a routing rule, and that is the design: a rule's effect is evidence before it is behaviour. A shadow rule reaches runtimes through the policy and logs, on each request it would have changed, what it would have served, as two fields on the ledger row of what actually ran. It routes nothing.

--threshold is in CHARACTERS of request content, counted exactly by the runtime, never tokens estimated by anybody. The record's context bands price the provider's own token thresholds; how a character threshold maps onto a band is the operator's claim, made reviewable in the decision that promotes the rule.

The refusals mirror a fallback's: a lane nobody has ruled on, a sku the lane already serves, one from another market or that no request can name, a duplicate predicate, a held position.

Promoting one, which needs a ruling that cites the shadows

bash
npm run aperture:rule:promote -- <rule-id> --under <decision-id> \
  --readings 2026-08-20..2026-08-24 --source-ref "ledger, box 1"

The order of authority is the point. First the shadow rows accumulate. Then somebody weighs them, writes a brief that cites them, and that decision is accepted through the ordinary path. Only then does this command record that the ruling covers the rule, and it refuses:

Refusal
A decision of another workload, or one that is a proposal
An accepted decision a later one has superseded: a rule routes under what stands
A decision decided BEFORE the rule was registered, whose brief cannot have weighed shadow evidence that did not exist yet
No --readings window, or no --source-ref naming where the cited rows live

The citation lands on the rule's own row (promoted_readings, promoted_source_ref), so "why does this rule route" answers from the register without opening a document.

What a routed rule does at request time

The rule's target goes to the head of the lane's attempts, and the lane's own order stands behind it: serving the decided model is always authorized, so a rule target that cannot answer degrades to the primary and its chain rather than to an error. Every attempt is its own ledger row, attributed to its own authority: the rule's serve to the decision that promoted it, the primary's to the lane's standing decision.

Going stale

Re-deciding a lane retires its rules exactly as it retires its chain: the policy emitter refuses a shadow rule whose registering decision, or a routing rule whose promoting decision, is no longer the standing one, naming what to re-register or re-promote under. A rule assembled against one incumbent is not self-evidently right for its replacement.

Removing one

bash
npm run aperture:rule:remove -- <rule-id> --reason "threshold was wrong"

Dated and kept, as everywhere in this schema: a rule that shadowed or routed traffic is part of what happened to that traffic.

A share, and the ladder it completes

A traffic_share rule is the canary this register could not run. It changes none of the epistemics: born shadow, promoted only under an accepted decision whose brief cites its shadow readings, removed by a dated row that is kept. What changes is that the promoted form may route five percent instead of all of it.

text
watching  ->  shadow  ->  5% canary  ->  25%  ->  accepted incumbent

Not every workload needs every rung. What matters is that an organisation can read the ladder off the record, with a decision at each one.

It is a bucket, not a draw

The assignment is FNV-1a(cohort key) % 100 < share. Three things follow, and each is why it is not a random number:

  • The same request always lands the same way. A canary is reproducible rather than merely measurable.
  • The ledger can be audited. Every row carries cohort, the bucket the assignment used, beside serve: "rule:<n>", so a reader can recompute which arm any request belonged to. A draw would have made that impossible.
  • Promoting is growing, not reshuffling. The buckets are nested, so moving a share from 5 to 25 keeps everything already on the new side there. The readings before and after a promotion are about overlapping populations.

Requests, not users, unless you say otherwise

Without a cohort key, the bucket is derived from the request itself, so a share is a share of requests. Two requests from the same person can land on different sides, which means the reading measures the model and not the experience.

Send x-vitna-cohort with something stable, a session or an account id, and the share becomes a share of whatever that identifies. The runtime reads that one header and nothing else about a caller's headers reaches routing.

The bounds are the meaning rather than validation. Zero is a rule that does nothing, which is what leaving it unregistered already says. A hundred is not a share, it is the lane, and moving a whole lane is a decision about its incumbent rather than a rule inside it.