Routes and ledger¶

Two symptoms that are read from the gateway's own records rather than from a provider: a route update the registry refuses, and a usage ledger whose empty window is mistaken for a zero. The rest of the runbook is at runbook.

A route update is refused¶

An alias resolves to exactly one route. The registry document that says so carries three known top-level fields — schema_version, deployments and routes — and routes maps each alias to its single destination. Its schema_version is the number one. The deserializer refuses an unknown top-level field, and refusing it rejects the whole document, so a file that still carries an extra field stops being loaded at all:

{
  "deployments": {
    "mini": {"local": "http://127.0.0.1:8080",
              "tailscale": "https://mini.tail-scale.ts.net"}
  },
  "routes": {
    "fast": {"primary": "mini/llama-3.1-8b"}
  }
}

The version line is left out of the example above on purpose; write it into the file as the top-level schema_version field with the value one.

What the file validation says¶

These are the sentences an operator actually reads when the registry file is rejected (concepts/alias):

• inference routes must be a regular non-symlink file — the path is a directory, a device, or a symlink; point the configuration at the real file.
• inference routes must not be accessible by group or other — the mode has to be owner-only, matching every atomic write the gateway performs on it.
• inference route '<alias>' repeats destination '<destination>' — one alias names the same destination twice; an alias has one destination, so remove the duplicate.
• inference deployment '<name>' has no safe local or Tailscale endpoint — the deployment declares no endpoint the gateway is allowed to call.

The admin endpoint¶

PUT /v1/admin/routes takes exactly {"alias","primary"} and DELETE /v1/admin/routes takes {"alias"}; both answer {"ok":true,"routes":<document>} with the document as it now stands (http-api). Any other field in the body is refused with the deserializer's own sentence. The two refusals an operator meets most often:

• runtime route registry is not configured (409) — no BRAMA_INFERENCE_ROUTES_FILE is in effect; configure it (the launcher seeds one) before editing routes at runtime.
• unknown route alias (400) — the alias in the body is not declared, so there is nothing to point at a destination. brama aliases prints each declared alias with its state and its route; a completion naming a declared alias that cannot serve answers 503 alias_unserviceable with details.state and details.route, and an unknown alias answers 404 whose details carry the same two keys.

The file is re-read per request, so a repaired file needs no restart.

A document carrying a field the deserializer refuses¶

A registry file written before this contract can still carry a top-level field that is no longer known. Every read of it — startup, an admin write, brama aliases — is refused, and the alias state reads routes_file_invalid. The repair is a command, not a text editor:

$ brama routes migrate

It reads the configured registry document, keeps only the known top-level fields, validates the result, and commits it with the same atomic owner-only replacement every other registry write uses. It prints the resulting document and is idempotent: running it again on a document already in this shape commits the same content and prints the same thing (cli/routes/migrate). Re-run brama aliases afterwards: each alias should read serving, or no_route where the migration removed a destination nothing declared, or capability_absent where the route names a provider this host was never granted (credentials and subscriptions).

The ledger looks wrong, not the pool¶

An empty limits array in a listing is one of three states told apart by the newest check — a refused credential, a subscription nothing has used, or a provider that publishes no plan state. Only the last may be read as "no plan window"; none of them is a zero. A reading marked stale: true is the last value the provider actually reported, kept and labelled because the report has been failing since — information about the report, not about health (concepts/subscription).