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