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

# Emitting a routing policy

`aperture:policy` renders an organisation's accepted decisions as a signed
policy document, which is what a Vitna runtime loads and resolves requests
against.

```bash
DATABASE_MIGRATE_URL=... VITNA_SIGNING_KEY=... npm run aperture:policy -- --org convexity
npm run aperture:policy -- --org convexity --out /etc/convexity/vitna-policy.json
```

## Why there are two artifacts

[A config](config.md) is a value a person loads into a variable something
already reads. That is the whole answer for a consumer with a gateway, and it
stays the mode with no runtime footprint at all.

A consumer with no such variable has nothing to load a config into. A policy is
the same decisions in a shape a process can execute: lanes a caller names,
models that answer them, and the decision behind each.

Both come out of one record and one accepted decision. They cannot disagree
about what was decided, and a test emits both from one set of workloads and
asserts they name the same sku from the same decision.

## What is still not true

**Nothing serves this file to a runtime.** A runtime loads its policy from
local disk at boot; a runtime that fetched it from Vitna per request would put
Vitna's availability inside its own, which is the dependency this whole
arrangement exists to refuse. Corrected 2026-09-13: this said there is no
endpoint and there will not be one. Since 2026-08-31 an organisation can
[collect a signed policy](../api/v1/engine/artifacts.md) between deployments,
which is a collection before the runtime starts, not a fetch while a request
waits.

**Nothing here holds a key or calls a provider.** This command reads the record
and writes a file.

**Nothing is applied.** A person puts the file where the runtime reads it.

## Which sku a lane serves

The same rule as a config, for the same reason:

| Outcome | Serves |
|---|---|
| `switch` | The candidate |
| `stay` | The incumbent |
| `test` | The incumbent |

A test is an instruction to measure. Routing its candidate would move production
traffic on the strength of a proposal that said do not.

## The document

JSON, because a runtime loads it and because later phases add a fallback chain
and rules within a lane, which an environment fragment has no shape for.

```json
{
  "statement": "vitna-routing-policy-v1",
  "canonical": "policy-json-v4",
  "org": "convexity",
  "generated": "2026-08-24T09:00:00.000Z",
  "lanes": [
    {
      "alias": "deep-research",
      "model": "claude-opus-4-8",
      "provider": "anthropic",
      "openrouter": "anthropic/claude-opus-4.8",
      "sku": "anthropic/claude-opus-4-8",
      "workload": "convexity/deep-research",
      "decision": "154",
      "decided": "2026-08-10T00:00:00.000Z",
      "outcome": "stay",
      "fallbacks": [
        {
          "position": "1",
          "model": "claude-sonnet-5",
          "provider": "anthropic",
          "openrouter": "anthropic/claude-sonnet-5",
          "sku": "anthropic/claude-sonnet-5",
          "under": "154"
        }
      ],
      "rules": [
        {
          "position": "1",
          "mode": "shadow",
          "kind": "context_chars_over",
          "params": "threshold=800000",
          "model": "claude-sonnet-5",
          "provider": "anthropic",
          "openrouter": "anthropic/claude-sonnet-5",
          "sku": "anthropic/claude-sonnet-5",
          "under": "154"
        }
      ]
    }
  ],
  "digest": "...",
  "signature": "...",
  "publicKey": "..."
}
```

`openrouter` is the substrate's own name for the same model, which is a third
name after the sku id and the provider's call name and cannot be derived from
either: Vitna registers `claude-opus-4-8` and OpenRouter lists
`anthropic/claude-opus-4.8`. It is empty when OpenRouter does not list the sku,
which costs that lane the substrate route and nothing else. It is empty on
purpose, at the same cost, when the workload states a data requirement or an
approved-provider list that does not name `openrouter`: the substrate is one
more party in front of the provider, and neither the requirement nor the list
was checked against it. A fallback or a rule of that lane carries no
OpenRouter name either.

The canonical form is versioned and has moved three times: `v2` added
`openrouter`, `v3` added `fallbacks`, and `v4` added [`rules`](rules.md), each
carrying its mode and the decision that authorises that mode. The statement prefix is unchanged, because it names the
kind of claim rather than the byte format, and the statement itself carries the
canonical version so the two cannot be confused.

**Only the fields inside `lanes` are signed.** The digest is recomputed from
them in a declared field order, so it does not depend on how a serialiser felt
about whitespace. Anything else in the file, including the `warning` line the
emitter writes for whoever opens it, is prose and is covered by nothing.

**Provenance is data rather than a comment.** A config carries "this value came
from decision 13" on a comment line inside the signed body. A lane carries it as
a field, because a runtime cannot read a comment and because "why did this
request run this model" has to resolve to a decision id per request.

The statement prefix is `vitna-routing-policy-v1`, distinct from the config and
attestation prefixes, so no signature can be read as another kind of claim.
For deterministic per-request model and effort selection (`vitna-route`), the
runtime verifies a sibling signed format (`vitna-auto-route-policy-v1` /
`auto-route-json-v1`); see [Per-request auto-routing](../runtime/route.md).

## It reads no clock

The instant is passed in, exactly as [the config](config.md) and the brief
builder take one. The same record and the same instant produce the same bytes,
which is what makes a diff between two policies meaningful.

## The refusals

A workload with no [lane alias](delivery.md) is skipped in silence, whichever
delivery kind it names: an `env` target without one is a config-mode workload
and is complete as it stands. A workload that names a lane and cannot be routed
is named, with the reason:

| Refusal |
|---|
| Names a delivery kind nothing can write |
| Names the `policy` kind and no alias, so no caller could ask for it |
| Names an alias that is not a lane name |
| Claims a lane another workload already claims |
| Has no accepted decision |
| Names a decision that is proposed or superseded rather than accepted |
| Has an accepted switch naming no candidate sku |
| Names no incumbent, so the lane has no model behind it |
| Is decided on a sku the registry does not hold, or one that [cannot be named in a request](model-ids.md) |
| Is decided on a sku that names no provider, so no route could reach it |
| Carries a [chain](fallbacks.md) registered under a decision that no longer stands |
| Carries a chain naming what the lane already serves, or a sku no request can name |
| Carries a [rule](rules.md) whose present-mode authority is not the standing decision |
| Carries a rule with unreadable terms, serving what the lane serves, or a sku no request can name |

Every one is a refusal rather than a silent omission, and nothing is written
when any lane fails. A policy missing a lane leaves a runtime resolving that
alias against whatever it loaded last.

## Checking one

```bash
npm run aperture:policy -- --verify /etc/convexity/vitna-policy.json
```

Needs no key and no database: it recomputes the digest from the lanes, rebuilds
the statement and checks the signature against the public half the file carries.
With a database reachable it also compares that key against the one the record
publishes, which is the half a signature alone cannot answer. Same three
questions, in the same order, as [verifying a config](verifying.md).

## What a policy may not say

A decision that respected a constraint, and a policy that then permitted the
opposite, would be a signed document permitting what the register refuses. The
signature would make that worse rather than better, so the emitter refuses
instead, and it refuses where the document is written rather than where it is
executed: **a policy that cannot contain a violating lane needs no runtime to
check for one**, including every runtime already installed.

**An unapproved provider refuses the whole policy.** If a workload names
`allowsProviders`, a lane, a fallback entry or a rule target from anybody else
is refused, and nothing is written, on the rule that already forbids a partial
policy. The chain is where it matters most: a chain is walked when something has
already gone wrong, which is the worst moment to reach a provider nobody
approved.

**A lane with a data requirement is emitted with no substrate route.** A
requirement is checked against the terms the *decided provider* published.
Riding a substrate puts a second party in front of that provider, and the record
holds no term of that party about this work, so the requirement would be
satisfied on paper by a route nobody checked. Leaving the OpenRouter name out is
how the artifact says so, and it costs the lane exactly the substrate: the field
was already allowed to be empty, and the runtime already refuses that one route
while serving the lane directly.

`VITNA_ALLOW_PROVIDERS` stays and stops being the only place a boundary is
written down. It is the operator's second belt: theirs, about their box, over
whatever policy it is handed.
Human Machine Shift+M