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

# Rules within a lane

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](https://vitna.ai/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

| Kind | Params | Matches when |
|---|---|---|
| `context_chars_over` | `--threshold`, in characters | The request carries more content than the threshold |
| `traffic_share` | `--share`, a whole percent from 1 to 99 | The 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](console-composing.md) 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](../runtime/ledger.md)
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](../concepts/price-period.md) 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](fallbacks.md): 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](fallbacks.md) 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](policy.md) 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.

```
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.
