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

# Rendering a policy for a gateway you already run

A signed policy is a document a Vitna runtime executes. An adapter renders that
same document as the configuration of a gateway you run instead, so one accepted
decision configures whatever is already in your request path rather than asking
you to adopt something new.

```bash
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target litellm --policy policy.json --out litellm.yaml
```

Add `--via openrouter` to write the same policy for a gateway holding one
OpenRouter key rather than a key per provider.

Written targets: `litellm`, `cloudflare`, `portkey` and `openrouter`. Vercel,
the sixth in [#111](https://github.com/convexityos/vitna/issues/111), is
refused rather than unbuilt, and the section at the end says why.

## An adapter reads the policy, never the register

This is the property that makes six targets one product rather than six
products. Every adapter takes the signed policy as its only input, so no adapter
can disagree with what was decided: it never re-reads what the decision read.

It follows that an adapter needs no database, no credentials and no network. It
reads a file and writes a file.

## The key is required, and for the runtime's reason

`VITNA_PUBLIC_KEY` pins the key the policy must carry. Without it the command
refuses to run.

A policy that verifies against its own key proves only that the file agrees with
itself, and anybody can produce a file that agrees with itself. What this
command writes is a configuration that will route production traffic, so it is
pinned exactly as [a runtime pins it](../runtime/serving.md): take the key the
record publishes on [/witness](https://vitna.ai/witness) once, out of band.

## Nothing is applied

The command writes a file. Getting it to the gateway is yours, whether that is a
commit somebody reviews or a deployment you already run.

That is the architecture rather than a missing feature. A runtime that fetched
its routing from vitna.ai at request time would have made Vitna's availability a
term in its own, and the same is true of a gateway. What Vitna emits is a
document; when it takes effect is your decision, made in your repository.

## What no adapter carries: rules

Each target below refuses a routing rule, and each names its own nearest miss.
The reason is the same one four times, so it is worth reading once here rather
than as four separate limitations.

**A rule is measured, not just executed.** A rule is registered in shadow, which
means it logs what it *would* have served as two fields on the ledger row of
what actually ran. It is promoted to routing only under an accepted decision
whose brief cites those shadow readings by window. The ladder is

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

and every step after the first depends on readings from the step before.

**A gateway has no ledger**, so it produces no readings. That is why a routing
rule is refused rather than approximated, and why a shadow rule is dropped
rather than rendered: not because the gateways lack a routing feature, but
because they are not instruments. Rendering a Vitna share onto a `weight`, a
`percentage` or a `loadbalance` would produce a canary that routes and can never
graduate, because the evidence its promotion requires would never exist.

**So what an adapter carries is decisions, and what it does not carry is the
apparatus for earning the next one.** Every accepted decision reaches your
gateway with its chain, in order, naming the decision that put it there.

If you want the ladder, the path is not to adopt a Vitna runtime permanently. It
is to run one for the measurement period, let the shadow rows accumulate, accept
the decision those readings support, and hand that decision to the gateway you
already run. The runtime is how a decision is earned; an adapter is how one is
run.

## What OpenRouter presets can carry, and what they cannot

```bash
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target openrouter --policy policy.json --out presets.json
```

A [preset](https://openrouter.ai/docs/features/presets) holds the config-shaped
fields of a request, and a lane's chain is
[an array in priority order](https://openrouter.ai/docs/guides/routing/model-fallbacks):
`{"models": ["anthropic/claude-opus-4.8", "openai/gpt-5.6-luna"]}`, tried in
order, the next one used when the previous returns an error. There is no
separate primary field: the primary is the first element. Formats read
2026-08-29.

| Policy | OpenRouter | Carried |
|---|---|---|
| Lane alias | the preset slug, called as `@preset/<slug>` | Yes |
| The decided model | first element of `models` | Yes |
| Fallback chain | the rest of `models`, in order | Yes, in the policy's order |
| A shadow rule | nothing | Dropped, and named in the file |
| A routing rule | nothing | **Refused** |
| Which decision put it there | nothing that persists | Beside the body, not inside it |

**This target needs no arguments at all**, and that is the policy's doing.
Portkey needs `--provider` because a target names an integration only you have.
OpenRouter names models in its own public namespace, and the policy already
carries that name per lane and per chain entry. That field exists precisely
because Vitna registers `claude-opus-4-8` and OpenRouter lists
`claude-opus-4.8`: an adapter deriving one from the other would fail on the dot.

**There is no direct route, and asking for one is refused.** Every other adapter
picks between two names because the gateway could call a provider itself or go
through OpenRouter. This gateway is OpenRouter, so the choice does not exist.

**A sku OpenRouter does not list makes the lane impossible rather than merely
unrouted.** Elsewhere an empty name costs the substrate file and the direct one
still renders. Here there is no other file.

**Applying one is the strangest of the four.** A preset is created and versioned
by POSTing to an inference route, `POST /api/v1/presets/{slug}/chat/completions`,
with a body shaped like a request. OpenRouter persists the fields that overlap
with the preset config and silently ignores the transient ones (`messages`,
`input`, `prompt`, `stream`). An existing slug gains a new active version.

So the file this emits is not a document stored as written: it is a request body
whose persistent half becomes the preset. Nothing transient is included, because
a `messages` array in a generated file is one somebody would reasonably expect
to be sent.

**Applying it is a one-way door, and this is the only target where that is
true.** A preset cannot be removed or disabled through the API. Checked
2026-08-30 against a real account: `DELETE` by slug, `DELETE` by id, `PATCH` and
`PUT` all answer `404`, and after the first of those the preset was still listed.
OpenRouter's published spec documents no such route, so unlike the two places
this file records a vendor disagreeing with its own schema, here the schema's
silence was accurate.

The lifecycle exists and is simply not public: a preset carries a `status` whose
documented values are `active`, `disabled` and `archived`. Removing one is a
dashboard action.

Two consequences for a target this file otherwise presents as CI-appliable.
Versions accumulate, with no documented way to prune them. And a lane that is
later decided away leaves its preset behind, still callable as
`@preset/<slug>`, holding the last models it was given. So a policy that drops a
lane does not retract the preset that lane created, and nothing in the emitted
file can. Compare Cloudflare, where a generated route and the gateway holding it
were both created and deleted over the API in the same session.

**And deleting one burns its name, invisibly.** Removing a preset from the
dashboard archives it rather than destroying it, and an archived preset keeps
its slug permanently. What makes that worse than it sounds is that nothing shows
you: `GET /presets` omits it and `GET /presets/{slug}` answers `404`, exactly as
though the name were free. The only thing that reveals it is a create, which
fails with `Cannot create a new version of a archived preset`. Measured
2026-08-30, on slugs deleted by hand earlier the same day.

For this adapter that is a constraint on lane aliases rather than a curiosity.
A preset slug is the lane alias, so a lane whose preset has ever been deleted
cannot be rendered to this target again under the same name: the emitted file
will be correct, the POST will fail, and no read beforehand would have warned
you. Renaming the lane is the only way out, and a lane alias is not a free
variable, it is the string a caller has in their code.

**A routing rule refuses with no near miss to decline.** LiteLLM had `weight`,
Cloudflare `percentage`, Portkey `loadbalance`, each a probabilistic thing worth
naming. A preset has no field for a share of traffic and none that reads the
size of a request. There is simply nowhere to put one, which is a cleaner
refusal and no less total. Provenance is beside the body for a sharper reason
than elsewhere too: an unknown key would be accepted and dropped rather than
rejected.

## What Portkey can carry, and what it cannot

```bash
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target portkey --policy policy.json --out configs.json \
    --provider anthropic=@anthropic-prod --provider openai=@openai-prod
```

A [Portkey config](https://portkey.ai/docs/product/ai-gateway/configs) is
`{ strategy, targets }`, and targets under `strategy.mode: "fallback"` are tried
in the order written. That is the closest fit to a lane any target has offered:
LiteLLM needed a map beside its deployment list and Cloudflare needed a graph,
and this is an ordered array that means what it looks like. Format read
2026-08-29.

| Policy | Portkey | Carried |
|---|---|---|
| Lane alias | the config `name`, referenced by its saved id | Yes |
| The decided model | `targets[].override_params.model` | Yes, by the route `--via` names |
| Fallback chain | `targets` under `strategy.mode: "fallback"` | Yes, in the policy's order |
| A shadow rule | nothing | Dropped, and named in the file |
| A routing rule | nothing | **Refused** |
| Which decision put it there | nothing in the schema | Beside the config, not inside it |

**`--provider` is required, and it is the first thing an adapter has needed
besides the policy.** A target names a provider integration saved in your
Portkey account: `@openai-prod`, or whatever the person who set it up typed. A
signed policy carries `openai`, and cannot know the rest. So the mapping is an
argument, a provider with no mapping refuses the whole file and names every one
that is missing, and a slug written without its leading `@` is refused rather
than corrected.

That widening is worth being precise about. It does not let the adapter disagree
with the decision, which is what the contract protects: the map says how to
address a provider the decision already named, in a namespace only you have. It
is the same category as `--via`, which picks between two names the policy itself
carries. The alternative was emitting `@anthropic` and hoping, and a config
naming an integration that does not exist fails at the first request.

**Applying it is one call under your own key**, unlike Cloudflare: `POST
/v1/configs` creates one and `PUT /v1/configs/{slug}` versions it, and
`GET /v1/configs/{slug}/versions` lists what came before. Post `name` and
`config` as the request body; `vitna` is not part of it. The verb was corrected
on 2026-08-29, from `PATCH /v1/configs/{id}`, against Portkey's published
OpenAPI and its prose docs, which agree with each other and define no PATCH.

**A routing rule refuses the whole file**, against a third nearest thing.
Portkey's `loadbalance` mode splits across targets by `weight`, which is
LiteLLM's mismatch again: a share is decided by cohort, not by a draw. No
documented mode reads the size of a request, so `context_chars_over` has nothing
to become either.

## What Cloudflare can carry, and what it cannot

```bash
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target cloudflare --policy policy.json --out routes.json \
    --timeout 60000 --retries 2
```

A Cloudflare AI Gateway [dynamic
route](https://developers.cloudflare.com/ai-gateway/features/dynamic-routing/)
is a graph rather than a list: `{ id, name, elements }`, where each element is
one of `start`, `conditional`, `percentage`, `rate`, `model`, `end` and they
point at each other by `outputs.<name>.elementId`. Every route must start with a
Start element, and a route is called by putting `dynamic/<name>` where the model
name goes. Schema read from [the JSON configuration
page](https://developers.cloudflare.com/ai-gateway/features/dynamic-routing/json-configuration/),
retrieved 2026-08-29.

| Policy | Cloudflare | Carried |
|---|---|---|
| Lane alias | the route `name`, called as `dynamic/<name>` | Yes |
| The decided model | a `model` element's `properties.provider` and `.model` | Yes, direct route only |
| Fallback chain | each model's `outputs.fallback`, pointing at the next | Yes, in the policy's order |
| A shadow rule | nothing | Dropped, and named in the file |
| A routing rule | nothing | **Refused** |
| Which decision put it there | nothing in the schema | **Beside the route, not inside it** |

**One route per lane, and the chain is the structure.** A model element carries
`outputs.success` and `outputs.fallback` natively, so the primary points its
fallback at the first entry, that entry points at the second, and each points
success at the End. This is a better fit than LiteLLM's, where the chain lives
in a map beside the deployment list: here there is no second place to write the
order down, so it cannot drift. The last model falls back to the same End its
success points at, because Cloudflare requires a `fallback` output on every
model element and arriving at the End is what having nothing left to try looks
like here.

**`--timeout` and `--retries` are required, and this target is the second to
need something beside the policy.** Cloudflare's model element requires both and
documents no default for either: the JSON configuration page calls them "Request
timeout in milliseconds" and "Number of retry attempts" and shows 60000 and 4 in
an example, which is an example and not a default. A signed policy carries
neither, and neither is harmless to invent. Retries interact with the chain: a
non-zero value has the primary attempted several times over before the first
fallback is reached at all, which is failover behaviour no decision decided.
Cloudflare bounds it as "up to 5 attempts" without saying whether the initial
call counts as one, so this file does not say either. Both are inputs, refused
rather than defaulted, in the same category as Portkey's `--provider`: they say
how to operate a route the decision already determined.

**A routing rule refuses the whole file, and `percentage` is the trap.** That
element routes requests *probabilistically*, which is the same mismatch as
LiteLLM's `weight` wearing different clothes: a Vitna share is a deterministic
cohort bucket. `conditional` reads request body, headers and metadata, and the
expression language it reads them with is not documented on that page, so
`context_chars_over` would be a guess at syntax.

**A decision id cannot ride inside the route.** Cloudflare's model element
documents `provider`, `model`, `timeout` and `retries` and says nothing about
custom fields, so each route carries its decision under a `vitna` key beside
`elements`, and the file says that key must be removed before posting. What that
costs a Cloudflare user is a lookup rather than an answer: the decision is in the
register either way.

**Applying it is automated after all, and this file said otherwise until
2026-08-29.** Cloudflare's prose pages still say dynamic routing "is not
currently available on the REST API", and two other things Cloudflare publishes
contradict that sentence. Its API schema repository carries

```
POST /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/routes
```

under the operation id `aig-config-post-gateway-dynamic-route`, summarised
"Create a new AI Gateway Dynamic Route", with `PATCH`, `GET`, `DELETE` and
`/versions` and `/deployments` beside it; and Cloudflare's official TypeScript
SDK exposes exactly those paths as `client.aiGateway.dynamicRouting.*`. Both
retrieved 2026-08-29 ([api-schemas](https://github.com/cloudflare/api-schemas),
[SDK](https://github.com/cloudflare/cloudflare-typescript)).

And the endpoint answers. A route generated by this adapter has been posted to a
real gateway, read back and deployed, which settles it against the prose page
rather than leaving three sources disagreeing on paper. The
[section below](#cloudflare-which-rejected-what-this-repo-used-to-emit) records
what that established and what it did not.

So this is a target CI can apply, and the emitted file names the endpoint rather
than sending the reader to the dashboard.

## What LiteLLM can carry, and what it cannot

| Policy | LiteLLM | Carried |
|---|---|---|
| Lane alias | `model_list[].model_name` | Yes |
| The decided model | `litellm_params.model` | Yes, by the route `--via` names |
| Fallback chain | `router_settings.fallbacks`, which is attempted in order | Yes, in the policy's order |
| A shadow rule | nothing | Dropped, and named in the file |
| A routing rule | nothing | **Refused** |
| Which decision put it there | `model_info`, returned by `GET /model/info` | Yes, per lane |

Format read from [the config
reference](https://docs.litellm.ai/docs/proxy/configs) and [the reliability
page](https://docs.litellm.ai/docs/proxy/reliability), both retrieved
2026-08-29.

## LiteLLM exercised, not only read

**This section is about LiteLLM alone.** It was the first target given to the
software it configures, and for a while the only one. Cloudflare and OpenRouter
have since been exercised too, separately and with different results, in [their
own section below](#cloudflare-and-openrouter-exercised-and-portkey-not).
Nothing here is evidence about them, or about Portkey, which has still met no
account.

Every LiteLLM row began as documentation too. On 2026-08-29 a generated config
was fed to LiteLLM 1.98.0, and what that establishes is listed rather than
summarised, because "it works" is the kind of claim this record does not make.

| Checked | Result |
|---|---|
| The proxy starts on the config | `/health/readiness` answers `{"status":"healthy"}` |
| The lane alias is the callable name | `/v1/models` lists `deep-research`, `classification` |
| Provenance reaches the running gateway | `/model/info` returns every `vitna_` field |
| A decision id stays a string | `"vitna_decision":"154"`, not `154` |
| The chain is accepted as emitted | `Router.fallbacks` is `[{'deep-research': ['gpt-4o-mini']}]` |
| The substrate form resolves | LiteLLM infers provider `openrouter` from `openrouter/anthropic/claude-3.5-sonnet` |

**What it does not establish, which is the more important half.** No request was
routed, no provider was called, and no failover was observed. Every check above
is about a config the gateway accepts and reports back, not about a config that
serves. Whether fallbacks fire in the written order under a real failure is
still LiteLLM's documentation talking. It has since been answered for OpenRouter
alone, in the section below, and answering it there says nothing about here:
LiteLLM's chain lives in a different field of a different document and has never
been made to fall through.

One practical note for anybody repeating this on Windows: LiteLLM's startup
banner cannot encode into cp1252 and the proxy exits before it binds. Set
`PYTHONUTF8=1`. The failure is nothing to do with the config, and it looks like
everything to do with it.

### A routing rule refuses the whole file

Neither rule kind survives the translation, and reaching for the nearest
LiteLLM feature would ship something that looks right and answers a different
question.

A `traffic_share` is not a `weight`. A weight is a draw per request; a Vitna
share is `FNV-1a(cohort key) % 100 < share`, so the same caller lands the same
way every time, promoting five percent to twenty five grows that arm instead of
reshuffling it, and every serve can be recomputed from the ledger. A weight has
none of those three properties.

A `context_chars_over` is not a `context_window_fallbacks`. That fires when a
provider returns a context-window error. A Vitna threshold fires on a number you
chose, before anybody is called. One is a recovery and the other is a routing
decision.

The refusal costs the whole file rather than the one lane, on the rule
[emitting a policy](policy.md) already holds: a partial configuration leaves
whatever the gateway already had for the lanes it omits, which is a routing
state nobody decided.

### A shadow rule is dropped, and the file says so

A shadow rule routes nothing, so a configuration without it behaves identically
and refusing would be false strictness. What is lost is not behaviour but
evidence. The would-haves a promotion has to cite are recorded by a Vitna
runtime and by nothing else, so a lane whose canary is being measured should not
be run through an adapter yet. The generated file names each dropped rule where
whoever is reading the configuration will see it.

## Cloudflare and OpenRouter exercised, and Portkey not

Three of the four targets have now been given to the gateway they configure.
Portkey has not, and says so below rather than going quiet.

Two of these found real defects, and they found opposite ones, which is the
reason each was posted rather than reasoned about. **A published schema is not
the service.** Cloudflare's understates nothing and its API rejected what this
repo was emitting; OpenRouter's overstates a requirement its API does not
enforce. Reading either one alone would have produced a confident wrong answer,
in a different direction each time. All of the below was done 2026-08-29.

### Cloudflare, which rejected what this repo used to emit

The prose page says dynamic routing "is not currently available on the REST
API". A scratch gateway was created, routes were posted into it, and it was
deleted afterwards.

| Checked | Result |
|---|---|
| Does the REST surface answer | Yes. `GET .../gateways/<any>/routes` returns a `200` with a paginated envelope, where a path that genuinely does not exist returns `404 "Route not found"` |
| **The shape this adapter emitted before today** | **Rejected, `400`.** Cloudflare named five paths: `properties.timeout` and `properties.retries` on both model elements, and `outputs.fallback` on the last one |
| The shape it emits now | Accepted, `200` |
| Does the chain survive | Yes. Read back with the primary's `fallback` pointing at the chain entry, that entry's at the End, and both `success` outputs at the End |
| Do the operator numbers survive | Yes, `"timeout":60000,"retries":2` on every model element |
| A lane with no chain | Accepted |
| Versions and deployments | Both answer. The route was created with an `active` version and an auto-created deployment naming that `version_id` |

So this adapter had been emitting routes Cloudflare refuses, since it was
written, and nothing would have caught it: the file validated against nothing,
and the one page it was written from says the endpoint does not exist. The three
required fields are real rather than an artifact of a generated schema, which is
exactly what the OpenRouter row below shows cannot be assumed.

**What it does not establish.** No request was routed through a dynamic route.
The gateway accepted the configuration, reported it back and deployed it, and
whether traffic falls through the chain in the written order under a real
provider failure is still Cloudflare's documentation talking. The `vitna` key
was stripped before posting, as the file says to; whether Cloudflare would have
rejected it is untested, because the emitted instruction is to remove it.

### OpenRouter, which accepted a body its own schema calls invalid

| Checked | Result |
|---|---|
| The emitted `body`, posted unmodified | Accepted, `200`, preset created and active |
| What its published schema says about that | That it is invalid. `ChatRequest` marks `messages` required with `minItems: 1`, and the body carries none. The service does not enforce it, so the emitted instruction is correct and the schema is not |
| Does the chain survive | Yes. The stored config is `{"models":["anthropic/claude-haiku-4.5","openai/gpt-4.1-nano"]}`, the emitted array exactly and in order |
| "An existing slug gains a new active version" | Confirmed. A second POST produced `v2` and moved `designated_version` to it, so re-running a policy updates a preset in place |
| Is an unknown key really accepted and dropped | Yes, and this is why provenance sits beside the body. A `vitna` key posted alongside `models` returned `200`, and the stored config came back holding `models` alone |
| **Is the lane alias callable, and does it serve** | **Yes. A request was routed.** `@preset/<slug>` was answered by the decided model, `finish_reason: stop`, at a cost of $0.0000088 |

That last row is the only place in this document where a real request reached a
real provider through a generated configuration.

#### The chain, made to fall through

Every ordering claim in this file was the vendor's documentation talking. On
this one target it is now a reading, and getting there took three attempts
because the first two were not what they looked like.

| Checked | Result |
|---|---|
| A first entry that cannot serve the request | **Skipped, and the next entry in the written order served.** An image sent to a text-only first entry was answered by the second, `200` |
| The control, without which that proves nothing | That same entry alone returned `404 "No endpoints found that support image input"`, so the chain rescued a lane that would otherwise have failed |
| **An entry naming a model OpenRouter does not list** | **Kills the whole request, `400`, fallback or not.** `"... is not a valid model ID"`, identical with a healthy second entry present and without it |
| A prompt larger than the first entry's context window | Not a failure at all. Alone, that entry truncated the prompt and answered `200`, so context overflow is an input to selection rather than a trigger for failover |

**The third row is the important one, and it settles a refusal this adapter
already made.** An unlisted sku does not cost you that entry, it costs you every
request through the lane, including the ones the surviving entries could have
served. That is why this target refuses the whole file when a lane or any chain
entry has no OpenRouter name, and the refusal now rests on a `400` rather than
on reasoning.

**What it still does not establish.** Whether OpenRouter discovers an entry
cannot serve before calling the provider or by calling it and getting an error.
The response names the model that answered and carries no attempt trail, so the
two are indistinguishable from the outside, and the distinction matters: a
provider that is up but failing is the case a chain exists for, and it is not
the case demonstrated here. What is demonstrated is narrower and still worth
having: the order is honoured, and an entry that cannot serve does not take the
lane down with it unless it is unlisted.

The fourth row is a caution about method rather than about OpenRouter. The
oversized prompt was the first thing tried, the chained call did fall through to
the second entry, and it looked like a clean demonstration until the control
showed the first entry would have answered anyway. A fallback that fires and a
model that was never going to be chosen produce the same reading, and only the
control separates them.

### Portkey, which has met no account

No Portkey credentials were available, so nothing was posted. What was done is
weaker and is not the same claim:

| Checked | Result |
|---|---|
| The emitted `{ name, config }` against `POST /configs` | Validates against Portkey's published OpenAPI |
| Which verb updates an existing config | `PUT /configs/{slug}`. Both Portkey's spec and its prose docs say so and neither defines `PATCH`. This file and the emitted `apply` line said `PATCH /v1/configs/{id}`, and now say `PUT` |
| How far that validation reaches | Not far. The spec types `config` as a bare `object` and mentions `override_params` nowhere, so nothing checked the `strategy` and `targets` shape that carries the lane |
| Whether a missed `vitna` strip is caught | No. Extra keys are not forbidden at the root |

**What it does not establish, and the Cloudflare row above is the warning.**
Schema validation passing means less than it sounds, because the part of a
Portkey config that encodes the decision is the part the spec declines to
describe. Cloudflare's adapter also looked correct by inspection and was
rejected by the first real POST. The verb correction rests on two
Portkey-published sources agreeing with each other, not on a request that
returned 405.

#### It is gated twice, and not for want of a key

An earlier version of this section said this target was where the next
credential should go. That was wrong, and the correction is worth stating
because it changes what "unexercised" costs here. Measured 2026-08-30 against a
real account holding a valid Portkey key:

| Route | Result |
|---|---|
| `GET /v1/configs`, `/virtual-keys`, `/integrations`, `/api-keys` | `403` `AB03`, "You do not have enough permissions" |
| `POST /v1/chat/completions` carrying the config inline in `x-portkey-config` | `400` `inline_config_blocked` |

The `403` is not a `401`, so the key is valid and simply not an admin one.
Portkey files admin API keys under its enterprise offering, so saving a config
through the API is an Enterprise action rather than a key you can go and make.
And the other door is shut by `block_inline_config`, a governance flag that
refuses an inline config object and demands a saved `pc-...` slug, which is the
thing the `403` prevents creating. `x-portkey-virtual-key` stays allowed when
inline configs are blocked, and carries no `strategy` or `targets`, so it cannot
exercise what this adapter emits.

So the honest statement is not that nobody has got round to it. On a
non-Enterprise account there is currently no way to hand Portkey a generated
config at all.

#### The one thing that could be settled, and was

That left a specific and unpleasant possibility. Portkey's open source gateway
validates a config with a Zod schema
([`src/middlewares/requestValidator/schema/config.ts`](https://github.com/Portkey-AI/gateway),
read 2026-08-29) which enumerates the permitted keys, and `override_params` is
not among them, while Zod strips unknown keys by default. This adapter puts the
decided model in `targets[].override_params.model`. If that validator were what
runs, the emitted config would be accepted and would route to the target's
default model instead of the decided one: valid, plausible, and wrong in the
one way this whole document exists to prevent.

The hosted product could not answer it, per the two gates above. The open source
gateway could, since it is the codebase that validator lives in. Run 2026-08-30
against `@portkey-ai/gateway@1.15.2` with a mock provider recording what the
gateway sent upstream, because a gateway's response names the target it used and
not the model it asked for:

| Cell | Upstream received |
|---|---|
| Control, a target with no `override_params` | the request body's model, so the path works and the mock sees what is sent |
| The shape this adapter emits, `override_params.model` set | **the override**, not the body's model |

So `override_params` is applied, and the OSS validator's omission of the key is a
stale schema rather than a live behaviour. The decided model goes somewhere the
gateway honours.

**What that does not cover.** It is the open source gateway, not the hosted
product. And the OSS gateway has no concept of an account integration, so the
target was addressed as `provider` plus `api_key` rather than as the `@slug`
form the adapter emits: what was tested is the `strategy`, `targets` and
`override_params` structure, not the slug addressing. A hosted account that can
save a config is still the only thing that would close this target.

### The part of this that CI now keeps

Everything above was done by hand once. A finding that is true on the day it is
written and unwatched afterwards is how the Cloudflare defect survived from the
day that adapter was written, so the schema half of it is now a test.

`tests/adapter-vendor-schemas.test.mjs` holds each adapter's output against the
request schema its vendor publishes, archived under `tests/fixtures/` by
`scripts/export-vendor-schemas.mjs` and kept verbatim. It runs offline, like
every other test here.

**What it checks is required-field presence, not full schema validation.** That
narrowing is the finding rather than a shortcut: every one of the five errors
Cloudflare returned was `7001 Required`, so missing required fields is the
failure mode that actually shipped, and checking it needs no validator in a
dependency tree that has none. A config could still be refused for something
this does not model.

Three things it pins that are easy to lose:

- The Cloudflare route carries every field Cloudflare marks required, and a
  **regression cell** rebuilds the pre-2026-08-29 shape and asserts it is still
  caught. Without that, a passing suite is also consistent with the check having
  quietly stopped checking.
- Portkey's spec still types `config` as a bare object. The scoping above
  depends on that, so if Portkey starts describing the config object the test
  fails and this section is stale.
- OpenRouter still requires `messages` on a route that accepts a body without
  one. That disagreement is the example this file uses for a schema overstating
  its requirements, and if OpenRouter drops the requirement the example is gone.

Re-running the exporter and reading the diff is how a vendor changing its mind
becomes visible, which is the event nothing used to notice.

### And the part that only a real gateway can answer

The test above inherits a blind spot it cannot fix: a published schema is not
the service. Cloudflare refused a route its schema also refuses, which an
offline check catches; OpenRouter accepted a body its own schema calls invalid,
which no offline check ever could. Both were found by posting, and both
directions are recorded here because neither is predictable from the other.

```bash
npm run aperture:adapter:verify                       # every target it has keys for
npm run aperture:adapter:verify -- --target cloudflare
```

`platform/engine/adapter-verify.mjs` generates a config from a signed policy,
gives it to the gateway, reads it back, and checks the chain survived in order.
Three properties are deliberate.

**A target with no credentials is skipped, not failed.** A verification that
goes red because nobody exported a key is one people learn to ignore, and this
file already records what a permanently red check costs.

**It is not in CI, and that is a decision rather than a gap.** The Cloudflare
token cannot be narrowed below account scope, so a repository secret would hand
every workflow edit rights over every AI Gateway on the account. An unattended
job that creates objects in a real account also leaves orphans when it fails.
So it runs when a person runs it.

**Every target posts something that must be refused.** A harness that only ever
sends valid configs cannot tell you the gateway validates anything. Cloudflare
is sent the pre-2026-08-29 shape and OpenRouter a chain naming an unlisted
model; both must be rejected, and a PASS elsewhere means less than it looks if
either is accepted. That discipline is not theoretical here: the first failover
result in this document was a false positive until a control cell killed it.

Cleanup runs in a `finally` and is confirmed by reading the account back rather
than by trusting a status code. Cloudflare's routes and gateway are removed.
OpenRouter's preset cannot be, so the command uses one stable slug,
`vitna-verify-roundtrip`, and versions it in place rather than littering a new
name on every run.

Portkey is written and has never been executed, because no account existed to
run it against. It says so when it runs, and it will fail loudly rather than
pass quietly if any of it is wrong. Among other things it is the request that
would settle the `PUT` correction above, which currently rests on two published
sources agreeing with each other rather than on a response. Cloudflare's and
Portkey's specs are OpenAPI 3.0 and OpenRouter's is 3.1, so anyone reaching for
a full validator instead wants a 2020-12 one for the third, which is the only
mechanical trap in it.

## A decision id in the config, which saves a lookup

**What answers "why does production run this" is the decision in the register,
not the config**, and that is true whichever target you use. A decision keeps the
exact price-period and evidence ids it read, its prediction is regenerated from
those append-only rows rather than stored, and every mode carries every accepted
decision. None of that depends on the emitted file carrying anything.

So what follows is a convenience rather than a property. Where a target lets a
config hold a decision id, this writes one, because during an incident somebody
is looking at a gateway and not at Vitna, and a lookup is expensive at exactly
that moment. Where a target does not, the answer is still in the register and
costs a lookup.

LiteLLM is the one target of four that lets a config hold it as data:

```yaml
  - model_name: deep-research
    litellm_params:
      model: anthropic/claude-opus-4-8
    model_info:
      vitna_sku: "anthropic/claude-opus-4-8"
      vitna_workload: "acme/deep-research"
      vitna_decision: "154"
      vitna_decided: "2026-08-10T00:00:00.000Z"
```

LiteLLM stores arbitrary `model_info` fields and returns them from
`GET /model/info`, which its documentation describes as the mechanism for
annotating a model with your own metadata (retrieved 2026-08-29). So on that
target the id comes back from the running gateway.

That is not a thing gateways cannot do. LiteLLM is a general-purpose gateway and
does it fine. What a gateway has no way to put there is a decision, because it
makes settings rather than decisions, and that difference belongs to the record
rather than to this file.

**A chain entry carries its sku and no decision.** Two lanes can fall back to
one sku under chains decided separately, and they share one deployment, so a
decision id there would be one lane's answer presented as the deployment's.
Which lane reaches it, and in what order, is `router_settings.fallbacks` beside
that lane's own entry.

## Two routes, and the file commits to one

The policy carries two names for every model: the provider's own, and
OpenRouter's. A runtime picks between them per lane, by which key its operator
holds. A config file cannot pick per request, so `--via` picks once for the whole
document.

| `--via` | What `litellm_params.model` says | The key the gateway needs |
|---|---|---|
| `direct` (default) | `anthropic/claude-opus-4-8` | One per provider |
| `openrouter` | `openrouter/anthropic/claude-opus-4-8` | `OPENROUTER_API_KEY` |

The substrate form has three segments because OpenRouter's own ids carry a
slash, so `openrouter/` prefixes a name that already looks like a path. That is
LiteLLM's own convention, from [its OpenRouter
page](https://docs.litellm.ai/docs/providers/openrouter) retrieved 2026-08-29,
where `api_base` is optional and defaults to OpenRouter's.

**A name does not change with the route, only the string it resolves to.** A
lane is its alias and a chain entry is its direct model id under either route, so
switching `--via` changes the `model` lines of a diff and nothing else. Somebody
moving onto or off the substrate should be able to read what changed.

**A sku OpenRouter does not list refuses the substrate file.** The policy leaves
that name empty, which is a fact about the market rather than a gap, and a config
naming `openrouter/` and nothing would fail every request. The same policy still
renders for `--via direct`, so the refusal is about the route rather than about
the policy.

Per-provider mixing is not offered. A runtime can be told to reach one provider
directly and another through the substrate; this writes one route per file, which
is how a gateway operator actually holds keys.

### Which route to write

The two executors reach differently, and that is not a disagreement about the
decision. The Vitna runtime speaks OpenAI and Anthropic directly and reaches
everything else through OpenRouter; LiteLLM speaks many providers directly. So a
Google lane written `--via direct` is `google/gemini-3.7-flash`, which LiteLLM
can call and the runtime cannot, and written `--via openrouter` both take the
same route to the same place.

Which is right is a fact about your gateway, not about the decision. Under either
route it is the same sku.

## One name is one destination

A lane alias and a model id are drawn from the same character set, so a lane
called `claude-opus-4-8` can sit beside a chain falling back to that model.
LiteLLM keys a deployment by `model_name`, so the two would claim one name and
one of them would silently serve the other's model, in a file that is valid and
a gateway that starts.

That is refused, naming both destinations. Rename the lane, or take one of them
out of the policy.

## Multi-gateway policy delivery

When an infrastructure stack runs more than one gateway concurrently, delivering
configurations individually risks configuration drift between targets. The
delivery runner renders and writes verified gateway configurations across
Portkey, OpenRouter, and LiteLLM in one command, asserting signatures and
cryptographic digests before any destination file is written:

```bash
npm run aperture:policy:deliver -- --policy policy.json --out-dir ./gateway-configs
```

Optional flags include `--targets` to restrict destinations, `--provider` to supply
Portkey provider slug mappings (for example `--provider openai=@openai-prod`),
and `--expected-key` to enforce public key pinning.

## Why there is no Vercel target

Vercel AI Gateway is the sixth target
[#111](https://github.com/convexityos/vitna/issues/111) names, and it is
refused rather than pending. The reason is not effort. A lane has nowhere to
live in what Vercel's gateway configures.

Its team-wide surface is [routing
rules](https://vercel.com/docs/ai-gateway/models-and-providers/routing-rules),
read 2026-08-29, and a rule is a rewrite or a deny that **matches requests by
model**:

```bash
vercel ai-gateway rules add --type rewrite \
  --source anthropic/claude-opus-5 --destination anthropic/claude-haiku-4.5
```

Three things follow, and each on its own is enough.

**`--source` is a model, not a name you can define.** The documentation puts it
plainly: "your application keeps requesting the source model and AI Gateway
substitutes the destination". A rewrite redirects a model somebody already asks
for. A lane alias like `deep-research` is not a model, nobody asks for it, and
there is no documented way to make the gateway answer to one.

**A rewrite is one source to one destination.** There is no ordered list, so a
chain has nowhere to go. Vercel does support fallbacks, and they are part of
"everything else you send": per request, from application code, which is the one
place an adapter must not write.

**Vercel says not to depend on it.** The page carries their own caution that
routing rules are in beta and "avoid relying on them in production".

None of that is a gap in Vercel. Its gateway rules are a governance primitive,
for standardising a team on a model or blocking one nobody approved, and they do
that job. It is simply a different job from naming an intent and giving it an
ordered set of models to try. An adapter here would translate a routing decision
into a governance rule and lose the alias and the chain on the way, which is the
kind of near-miss every other target's refusals exist to prevent.

**What would change this.** A named route or a model alias, something a request
can address that is not already a model. If Vercel adds one, the lane gets
somewhere to live and this is worth revisiting. The rewrite rule is not it.
