API.md

# Cortiq Decision — API

`cortiq serve cortiq-decision.cmf` starts one HTTP server that speaks two
protocols at the same time:

* the **decisions protocol** of Jev / OpenRouter (`POST /api/alpha/decisions`),
  with an optional `cmf` extension;
* the **cortiq-router API**, schema `1.1` (`POST /v1/route` and the rest), so
  that existing router clients switch by changing the backend address only.

Both run the same local model and the same oracle cascade ([ORACLE.md](ORACLE.md)).
There is no web interface and no CORS layer. Request bodies are never logged:
a log line holds the request id, status, latency and account.

The command and `curl` blocks below were run in order, as written, against
local servers of the published `cortiq-decision.cmf` with cortiq 0.7.8; the
HTTP status each call returned is written after it as `# → 200`. Four parts
used stand-ins or were not run: the `mysql` export of section 8.1 was not run
(the import read a hand-written export of one test key and its counters); the
old router of section 8.3 was a local stand-in, a `cortiq serve` of the same
file holding that imported key at `127.0.0.1:8080`; `cortiq decision
learn` in section 7 called a local mock of the OpenRouter API (`base_url`
pointed at it) instead of OpenRouter; and so did the oracle commands of
[Check your setup](#check-your-setup) in section 1 (`--base-url`, for
`decide` `--oracle-base-url`, pointed at the mock, with a test key). The
examples use `curl` and `jq`.

1. [Start a server](#1-start-a-server)
2. [Keys, plans and limits](#2-keys-plans-and-limits)
3. [Decisions API (Jev / OpenRouter protocol)](#3-decisions-api-jev--openrouter-protocol)
4. [cortiq-router API (schema 1.1)](#4-cortiq-router-api-schema-11)
5. [Administration](#5-administration)
6. [Configuration reference](#6-configuration-reference)
7. [Your own model](#7-your-own-model)
8. [Migrating from cortiq-router](#8-migrating-from-cortiq-router)

## 1. Start a server

Create an API key first. It is printed once; the state directory keeps only
its sha256.

```bash
export KEY=$(cortiq decision keys create --state ./decision.state \
  --plan developer --account acme --json | jq -r .key)
```

An optional configuration file (all fields are listed in
[section 6](#6-configuration-reference)):

```bash
cat > decision.json <<'EOF'
{
  "default_skill": "banking77",
  "task_complexity": {"card_arrival": 0.2, "compromised_card": 0.8},
  "routing_tiers": {"low": "my-small-model", "medium": "my-mid-model", "high": "my-large-model"}
}
EOF
```

Start the server. It stays in the foreground until Ctrl-C; the admin API
needs the token in the server's environment and in the shell that calls it.

```bash
export CORTIQ_DECISION_ADMIN_TOKEN=$(openssl rand -hex 24)
cortiq serve cortiq-decision.cmf --decision-config decision.json \
  --state ./decision.state --port 8080
```

### CPU, Metal or Vulkan

From Cortiq 0.8.0, the default crates.io CLI includes GPU decision support.
Set the device **before starting the process**:

```bash
# Apple Silicon
CORTIQ_DECISION_DEVICE=metal cortiq serve cortiq-decision.cmf \
  --state ./decision.state --port 8080

# A hardware Vulkan device and driver
CORTIQ_DECISION_DEVICE=vulkan cortiq serve cortiq-decision.cmf \
  --state ./decision.state --port 8080
```

Use only one server per state directory. CPU remains the default. On multi-GPU
hosts set `CORTIQ_DECISION_VULKAN_ADAPTER` to a unique part of the adapter name.
`GET /healthz` identifies the encoder device and counts completed GPU submissions.
The decisions endpoints and `/v1/route` use the same accelerated path; a device
error is reported, not silently sent to CPU. [Measurements and limits](GPU.md).

A decision server listens on `127.0.0.1:8080` unless `--host` / `--port` say
otherwise. Other `cortiq serve` flags for decision files: `--break-lock`
(only where the state directory's filesystem has no advisory locks: remove a
stale `LOCK` of a dead process), `--shadow-of URL` and
`--shadow-timeout-s N` ([section 8](#8-migrating-from-cortiq-router)), and
`--oracle MODEL` with its companions `--oracle-budget`, `--oracle-max-calls`,
`--oracle-max-price`, `--oracle-key-env`, `--oracle-base-url` and
`--no-oracle-learning`: the oracle in two steps, the OpenRouter key in
`OPENROUTER_API_KEY` and then this flag
([ORACLE.md](ORACLE.md#connect-openrouter)).
Language-model flags (`--task`, `--gpus`, …) are refused for a decision file.

```bash
export CORTIQ=http://127.0.0.1:8080
curl -s "$CORTIQ/healthz"                                    # → 200
```

The state directory (mode 0700) holds `LOCK`, `keys.json`, `usage/`,
`oracle.jsonl`, `oracle.state`, `learn.log`, `generations/` and `CURRENT`
(and in shadow mode `shadow.jsonl` with its key `shadow.key`). One server
process per state directory; the CLI may change `keys.json` while it runs
(both take `keys.json.lock` for each change). The server holds an advisory
lock (`flock`) on `LOCK` while it runs, and the file names its pid; the
lock ends with the process however it ends, so a `LOCK` left by a server
that was killed (SIGKILL after a stop timeout, an out-of-memory kill, a
crash of the host) is taken over by the next start, with a warning naming
that pid: a restart policy such as `restart: unless-stopped` needs no
`--break-lock`, also in a container where the server is always pid 1. The
lock of a running process is never broken. Versions up to 0.7.8 do not hold
the lock: do not run one on the same directory at the same time.

<a id="check-your-setup"></a>**Check your setup.** Whether the oracle is
ready can be checked before a server with `--oracle MODEL` is started or
anything is spent:

```bash
cortiq decision oracle check               # free: the key, the account, the model
cortiq decision oracle check --test-call   # and one tiny structured call, a small fraction of a cent
```

Each check prints ✓ or ✗ with what to do; the exit code is 0 only when the
oracle is ready (`--json`: `ready` and `problems[]`). A server reports its
oracle as `oracle_status` of `GET /healthz` and `status` of `GET
/v1/admin/oracle` ([section 5](#5-administration)), `cortiq decide …
--json` as `cmf.oracle.status`:

| Status | What to do |
|---|---|
| `ready` | nothing: what the gate rejects goes to the oracle |
| `no_key` | `export OPENROUTER_API_KEY=…` where the server (then restart it) or `decide` runs |
| `bad_key` | fix the variable as the message says (a quote, `Bearer `, a `NAME=…` line, whitespace or a non-ASCII byte in it); nothing was sent |
| `disabled` | start the server with `--oracle MODEL`; if the admin switched it off, `POST /v1/admin/oracle {"enabled": true}` |
| `budget_too_small` | `--oracle-budget` of at least the figure the message names (and `--oracle-max-calls` of 1 or more) |
| `budget_exhausted` | a larger `--oracle-budget` or `--oracle-max-calls` (a server counts its whole ledger; each `decide` run has its own budget) |
| `stopped: <reason>` | fix the cause (`http_401` / `http_403` the key was refused, `http_402` no credit, …), then `POST /v1/admin/oracle {"enabled": true}`, or one `decide` run with `--oracle-resume` |

An admin limit kept in `oracle.state` is lifted by the `POST
/v1/admin/oracle` the message names, not by a restart. One text or a batch
from the command line (only what the gate rejects is sent; the ledger and
the cache are in `<FILE>.state`, or `--state DIR`):

```bash
cortiq decide cortiq-decision.cmf --skill banking77 -p "the exchange rate you gave me looks wrong" \
  --oracle deepseek/deepseek-v4.1-flash
printf '%s\n' '{"text": "I still have not received my new card", "label": "card_arrival"}' \
  '{"text": "can I pay my rent with a virtual card"}' > rows.jsonl
cortiq decide cortiq-decision.cmf --skill banking77 --input rows.jsonl --out results.jsonl \
  --oracle deepseek/deepseek-v4.1-flash --oracle-budget 0.05
jq -c '{answer, action, source, oracle_cost_usd, flags}' results.jsonl
```

Each batch row adds `answer`, `action` (`local`, `oracle`, `cache` or
`abstain`), `source`, `oracle_cost_usd` and `flags` to the local columns;
`--oracle-resume` turns the oracle on again after a stop rule is fixed, and
a `LOCK` a killed run left is taken over by the next one
([ORACLE.md](ORACLE.md#one-text-or-a-batch)).

## 2. Keys, plans and limits

* A key is `cortiq_` followed by 40 hex characters from the OS random
  generator. Send it as `Authorization: Bearer <key>` or `x-api-key: <key>`.
* The server re-reads `keys.json` when it changes (checked at most every 15 s),
  so keys created with the CLI while the server runs start working without a
  restart. Keys created through the admin API work at once.
* **Open mode** (no key needed) holds only while `keys.json` has no key and
  `auth.require` is false; `auth.require: null` (the default) means "required
  unless the server listens on loopback". The open caller may reach the
  oracle and teach the model when the configuration says
  `auth.require: false`. On a loopback address without that setting it may
  reach the oracle only when the server was started with `--oracle MODEL`
  (the operator enabled it explicitly), and it never teaches the model: a
  loopback address says nothing about the client (a reverse proxy on the
  same host forwards anyone), so its feedback is not learned and the
  oracle's answers to it are cached, not learned. Behind a reverse proxy
  set `auth.require: true`.
* A rate window is one fixed minute per account; quotas and credit are
  checked before any work is done, and again before every input of a
  `/v1/route:batch` after the first (402 at the input that finds them used
  up). A *decision* is one answered question: a `/v1/decisions` request
  with more questions than the decision quota has left is refused (402,
  `requested` in the details) before any work. An oracle call is made only
  when its reserved worst-case cost (times `oracle_markup`) fits in the
  credit left; otherwise the questions get the `budget` flag, as past the
  key's `oracle_budget_usd`. The token quota and the local prices are
  checked before the request only, so one request can still go past them
  by its own tokens and price; parallel requests of one account are each
  checked against the usage recorded before them.
* **Teaching the model** is a permission of its own, `learning_allowed`
  (default false for every key, created or imported): the key's feedback is
  learned (a label the skill does not have starts a cold start), and the
  oracle's answers to its questions become training examples. Without it,
  feedback is answered and consumed but not learned, and an oracle answer
  teaches the skill only when the question is exactly the skill's own (its
  rubric's instructions and criteria over all its labels, as `/v1/route`
  asks it). The skills are shared by every account.

| Plan | Requests per minute | Decision quota | Key lifetime |
|---|---|---|---|
| starter | 60 | none | 30 days |
| developer | 120 | 100000 | 30 days |
| pro | 600 | 1000000 | 30 days |
| scale | 3000 | 10000000 | 30 days |

This is cortiq-router's plan table. `auth.plans` in the configuration
replaces entries by name (`{"rate_per_min", "decision_quota", "days"}`,
`days: null` = no expiry); a plan it does not name is refused (400), where
the router minted a key without limits. `cortiq decision keys create` also
takes `--days` (0 = never expires), `--rate-per-min`, `--decision-quota`,
`--token-quota`, `--credit-usd`, `--oracle-budget-usd`, `--oracle-allowed`
and `--learning-allowed` (0 means unlimited for the counters); the admin
API takes the same fields. A key created with the CLI may use the oracle
(`oracle_allowed: true`, like an imported router key) unless it is created
with `--oracle-allowed=false`; the server's oracle switch, budget, the key's
`--oracle-budget-usd` and the stop rules still apply. A key created through
`POST /v1/admin/keys` has `oracle_allowed` only when the body sets it, as
in the router.

```bash
cortiq decision keys list --state ./decision.state
```

Keys through the admin API (router-compatible body; `x-admin-token`):

```bash
curl -s "$CORTIQ/v1/admin/keys" -H "x-admin-token: $CORTIQ_DECISION_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"account": "beta", "plan": "starter", "label": "trial"}' \
  | jq '{account, plan, rate_per_min, expires_at}'           # → 200
curl -s "$CORTIQ/v1/admin/keys" -H "x-admin-token: $CORTIQ_DECISION_ADMIN_TOKEN" \
  | jq '.keys[] | {account, plan, key_hash_prefix}'          # → 200
curl -s -X DELETE "$CORTIQ/v1/admin/keys/beta" \
  -H "x-admin-token: $CORTIQ_DECISION_ADMIN_TOKEN"           # → 200
```

The response of `POST /v1/admin/keys` is the only place the raw key appears.

## 3. Decisions API (Jev / OpenRouter protocol)

`POST /api/alpha/decisions` (also `POST /v1/decisions`), key required.

### 3.1 Request

| Field | Rules |
|---|---|
| `model` | `"cortiq/decision"` or `"cortiq/decision@<12 hex>"` of the served generation; anything else, a Jev name included, is 404 `MODEL_NOT_FOUND` |
| `state` | non-empty string, object or array; an object or array is used as its canonical JSON and the answers are then not certified; at most 32 KiB |
| `questions` | object of 1–32 questions in request order; ids up to 128 characters |
| question | `{type, instructions, criteria}`; `type` is `choice`, `score` or `noul`; `instructions` is required |
| choice `criteria` | object of 2–255 options; option ids 1–256 bytes; each description a string, object, array or `null` up to 24000 bytes; key order is kept |
| score `criteria` | array of 2–10 levels, lowest first |
| noul `criteria` | optional; an object with only `true` and/or `false` |
| `provider`, `user`, `session_id`, `trace` | OpenRouter's optional fields: accepted and ignored |
| `cmf` | extension, all optional: `skill`, `oracle` (bool), `allow_pii_egress` (bool), `round` (`2` or `null`), `explain` (bool), `profile` (`balanced`, `quality-first`, `cost-saver`) |

Any other key at the top level or inside `cmf`, or a key repeated inside any
object, is 400. The body is at most 1 MiB (413) and must be
`Content-Type: application/json` (parameters such as `charset` allowed):
any other content type, or none, is 400 `INVALID_REQUEST` on this API (the
router paths of [section 4](#4-cortiq-router-api-schema-11) answer it with
415, as the router does).

```bash
curl -s "$CORTIQ/api/alpha/decisions" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{
    "model": "cortiq/decision",
    "state": "I still have not received my new card",
    "questions": {
      "intent": {
        "type": "choice",
        "instructions": "Classify the banking customer message.",
        "criteria": {
          "card_arrival": "The customer is waiting for a card to arrive",
          "card_delivery_estimate": "The customer asks when a card will be delivered",
          "lost_or_stolen_card": "The card was lost or stolen"
        }
      }
    }
  }' | jq                                                    # → 200
```

```json
{
  "id": "cmf-dec-1790462653-d5agU2C4o0BM69enIx7G",
  "created": 1790462653,
  "model": "cortiq/decision@386b6e43fd35",
  "provider": "Cortiq",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "card_arrival",
      "probabilities": {
        "card_arrival": 0.9999062,
        "card_delivery_estimate": 0.00003233644,
        "lost_or_stolen_card": 0.00006148422
      },
      "confidence": 0.99985933
    }
  },
  "usage": {"input_tokens": 59, "output_tokens": 3, "cost": 0.0},
  "cmf": {
    "generation": 0,
    "model_sha": "386b6e43fd35d5aa9e9710529dfdf30aa868df98ab4434d8e45dae9829898f85",
    "representation_id": "5e83d2345be08aaa526b63addd243bb511f877e1cbab3caab9749a53e9519c25",
    "timings_us": {"tokenize": 8, "encode": 2000, "hash": 5, "resonance": 2222, "oracle": 0, "total": 4287},
    "questions": {
      "intent": {
        "action": "local",
        "source": "local",
        "skill": "banking77",
        "match": "subset",
        "certified": false,
        "gate": {
          "accepted": true, "p_top": 0.9999062, "tau": 0.7, "novelty": 0.38166195,
          "theta": 0.804234, "is_novel": false, "margin": 0.1587196, "profile": "balanced"
        },
        "errors": {"card_arrival": 0.097457424, "lost_or_stolen_card": 0.32894346, "card_delivery_estimate": 0.3442838},
        "flags": [],
        "confident": true,
        "complexity": {
          "score": 0.15727276, "tier": "low",
          "factors": {"base": 0.2, "ambiguity": 0.00009381771, "novelty": 0.38166195, "margin": 0.0, "length": 0.2}
        },
        "routing": {"target": "my-small-model", "reason": "card_arrival @ complexity 0.16 (low)"},
        "decision_path": "router:uncertified_subset"
      }
    },
    "usage": {
      "local": {"input_tokens": 59, "output_tokens": 3, "processed_tokens": 10, "cost": 0.0},
      "oracle": {"calls": 0, "input_tokens": 0, "output_tokens": 0, "cost": 0.0, "billed": 0.0, "passthrough": true}
    }
  }
}
```

### 3.2 Skill matching and `certified`

The local model looks only at the option ids (instructions and descriptions
matter to the oracle alone). With L = the option ids of a choice question:

| Match | When | Decided by |
|---|---|---|
| `exact` | L equals the active labels of exactly one skill | that skill's certified gate |
| `subset` | L is a strict subset (at least 2) of one skill's labels | argmin, softmax, margin and novelty over L only; the same T, θ, τ; never certified |
| `superset` | one skill's labels plus labels it does not know | the oracle only; its answer teaches that skill only for a key with `learning_allowed` |
| `untrained` | anything else, and every `score` / `noul` question | the oracle only; without it the request is 422 |

`cmf.skill` names the skill and skips the search (an unknown id is 400). An
answer is `certified: true` only for an exact match on a string `state`, the
`balanced` or `quality-first` profile, a skill whose gate is certified, and a
winning label that comes from the training data. The bound (Clopper–Pearson
lower bound ≥ 0.95 on the odd calibration half) covers only `certified: true`
answers, all of them `action: local`, and only for traffic like the skill's
calibration split; subset matches, `cost-saver`, object or array states and
uncertified skills also answer `action: local` with `certified: false`.
`quality-first` answers are a sub-selection of the certified acceptance set,
for which no bound of their own was computed. Oracle and cache answers are
never certified.

An exact question is easiest to build from the skill's own rubric:

```bash
curl -s "$CORTIQ/v1/skills/banking77" -H "Authorization: Bearer $KEY" \
| jq '{model: "cortiq/decision", state: "I still have not received my new card",
       questions: {intent: {type: "choice", instructions: .rubric.instructions,
                            criteria: .rubric.criteria}}}' \
| curl -s "$CORTIQ/api/alpha/decisions" -H "Authorization: Bearer $KEY" \
    -H 'Content-Type: application/json' --data-binary @- \
| jq '{choice: .answers.intent.choice, confidence: .answers.intent.confidence,
       local: (.cmf.questions.intent | {action, match, certified, decision_path})}'
# → 200, 200
```

### 3.3 Response

`200` with `{id, created, model, provider, answers, usage, cmf}` and the header
`x-request-id` equal to `id`.

* **choice, `action: local` or `abstain`** — `{type, choice, probabilities,
  confidence}`: `probabilities` has every option in request order,
  `confidence = (N·p_max − 1)/(N − 1)` (Jev's formula). Numbers are the
  shortest f32 form; `cmf.round: 2` (or `response.round: 2`) rounds to
  hundredths and prints 0 and 1 as integers, as Jev does.
* **choice from the oracle or the cache** — `{type, choice}`.
* **score** (oracle only) — `{type, score, legend}` with the level index.
* **noul** (oracle only) — `{type, noul: 1 | 0, value_semantics:
  "boolean_verdict_not_probability"}`.

`cmf.questions.<id>` explains each answer:

| Field | Meaning |
|---|---|
| `action` | `local` (gate accepted), `abstain` (gate rejected and no oracle answer), `cache`, `oracle` |
| `source`, `skill`, `match`, `certified` | where the answer came from; section 3.2 |
| `gate` | `accepted`, `p_top` and `tau`, `novelty` and `theta`, `is_novel`, `margin`, `profile` |
| `errors` | reconstruction errors of the 5 best labels (all of them with `cmf.explain`) |
| `flags` | e.g. `oracle_disabled`, `no_key` (with `oracle_disabled`: the key variable is not set), `bad_key` (with `oracle_disabled`: it holds something that is not a key), `consent_off`, `budget`, `stopped`, `oracle_unavailable`, `pii_redacted` |
| `confident` | the answer can be used as is (gate accepted and not novel, or a valid oracle answer) |
| `complexity` | `{score, tier, factors: {base, ambiguity, novelty, margin, length}}`, the cortiq-router formula |
| `routing` | `{target, reason}` when `routing_tiers` maps the tier |
| `decision_path` | `router:certified`, `router:uncertified`, `router:uncertified_subset`, `escalate→cache`, `escalate→oracle`, `escalate→oracle_unavailable`, `escalate→disabled` |
| `explanation` | with `cmf.explain`: `{top1_vs_top2, decision_path}` |

When a trained question abstains because the oracle is not ready (flags
`oracle_disabled`, `no_key`, `bad_key`, `budget` or `stopped`, not `consent_off`), the
answer also has `cmf.hint`, one line that says what to do, e.g. `"the oracle
key is not set: set OPENROUTER_API_KEY in the server's environment and
restart it"` or `"no oracle answers the questions the local model cannot
decide: start the server with --oracle MODEL and set OPENROUTER_API_KEY"`.
The router API (section 4) has no hint; the server logs it (each hint at most
once a minute; once, at INFO, on a server started without an oracle).

Complexity: `score = Σ weight·factor` with base = `task_complexity[label]`
(default 0.4), ambiguity = 1 − p_top, novelty, margin = 1 − clamp(8·margin, 0, 1),
length = clamp(words/40, 0, 1); weights 0.40 / 0.25 / 0.15 / 0.10 / 0.10;
tiers low ≤ 0.33 < medium ≤ 0.66 < high.

**Profiles** (`cmf.profile`): `balanced` (default) is the certified gate
`p_top ≥ τ and novelty ≤ θ`; `quality-first` also needs `margin ≥ 0.08` and
`novelty ≤ min(θ, 0.50)` (more abstentions, fewer errors); `cost-saver` uses
`novelty ≤ θ` only and is never certified.

```bash
curl -s "$CORTIQ/api/alpha/decisions" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{
    "model": "cortiq/decision",
    "state": "someone used my card without my permission",
    "questions": {"intent": {"type": "choice", "instructions": "Classify the message.",
      "criteria": {"compromised_card": null, "card_payment_not_recognised": null, "lost_or_stolen_card": null}}},
    "cmf": {"explain": true, "profile": "quality-first", "round": 2}
  }' | jq '{answer: .answers.intent, explanation: .cmf.questions.intent.explanation,
            complexity: .cmf.questions.intent.complexity.tier, routing: .cmf.questions.intent.routing}'
# → 200
```

### 3.4 Usage and price

* `usage.input_tokens` counts WordPiece tokens of everything the model was
  given, as Jev counts them: the `state` plus each question's `instructions`
  and `criteria` (keys and values). An exact question over a 77-label rubric
  therefore counts thousands of tokens although the encoder reads only the
  state; `cmf.usage.local.processed_tokens` is what the encoder read.
* `usage.output_tokens` is the number of values in `probabilities` (1 for an
  oracle, cache or noul answer).
* `usage.cost = input·input_usd_per_1m/1e6 + output·output_usd_per_1m/1e6 +
  request_usd + [oracle passthrough] oracle cost × markup`. **All prices are
  `"0"` by default**, so local answers cost 0 and oracle answers cost what
  OpenRouter charged. Prices are decimal strings in `pricing`.
* Errors are not billed. `GET /v1/usage` shows the caller's own account.

### 3.5 Errors

`{"error": {"code": <HTTP>, "message": "…", "metadata": {"reason": "<CODE>",
"retriable": bool, "request_id": "…", "details": {…}}}}` — OpenRouter's shape
with cortiq-router's codes.

| HTTP | reason | When |
|---|---|---|
| 400 | `INVALID_REQUEST` | schema, limits, duplicate or unknown keys, malformed JSON, a content type other than `application/json` |
| 401 | `UNAUTHORIZED` | key missing, wrong, expired or revoked |
| 402 | `QUOTA_EXCEEDED` | decision or token quota, credit |
| 404 | `MODEL_NOT_FOUND`, `INVALID_REQUEST`, `ADMIN_DISABLED` | unknown model; feedback target not found; admin token not configured |
| 413 | `PAYLOAD_TOO_LARGE` | body over `limits.body_bytes` |
| 422 | `UNSUPPORTED_QUESTION` | untrained question and the oracle not allowed |
| 429 | `RATE_LIMITED`, `OVERLOADED` | the minute window; more than `max_inflight` requests (`Retry-After`) |
| 500 | `INTERNAL` | |
| 502 | `ORACLE_UNAVAILABLE` | untrained question, the oracle call failed |
| 503 | `ORACLE_BUDGET_EXHAUSTED`, `ORACLE_DISABLED` | untrained question, no budget or a stop rule |

A trained question whose oracle call fails is never an error: it is answered
locally with `action: abstain` and the flag `oracle_unavailable`.

```bash
# Jev's model id is not served here
curl -s "$CORTIQ/api/alpha/decisions" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "typesafe/jev-1.13", "state": "x",
       "questions": {"q": {"type": "choice", "instructions": "i", "criteria": {"a": null, "b": null}}}}' \
  | jq .error.metadata.reason                                # → 404
# score and noul questions need the oracle
curl -s "$CORTIQ/api/alpha/decisions" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "cortiq/decision", "state": "The parcel arrived two weeks late.",
       "questions": {"urgency": {"type": "score", "instructions": "How urgent?", "criteria": ["low", "medium", "high"]},
                     "refund": {"type": "noul", "instructions": "Does the customer ask for a refund?"}}}' \
  | jq .error.metadata                                       # → 422
# no key
curl -s "$CORTIQ/api/alpha/decisions" -H 'Content-Type: application/json' \
  -d '{"model": "cortiq/decision", "state": "x",
       "questions": {"q": {"type": "choice", "instructions": "i", "criteria": {"a": null, "b": null}}}}' \
  | jq .error.metadata.reason                                # → 401
```

### 3.6 Feedback, listings, health

`POST /v1/feedback {"id", "question", "label"}` corrects a decision of the
caller's own account (a decision of another account is not found). The label
must be one of the question's options. For a key with `learning_allowed` it
becomes a training example of weight 3, and an option the skill does not
have starts a cold start ([ORACLE.md](ORACLE.md#self-learning)); for any
other key it is consumed and answered 200 with `accepted: false` and
`refused: "learning_not_allowed"`. The router form of feedback (section 4)
accepts any label.

```bash
ID=$(curl -s "$CORTIQ/api/alpha/decisions" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "cortiq/decision", "state": "where is the card you sent me",
       "questions": {"intent": {"type": "choice", "instructions": "Classify the message.",
         "criteria": {"card_arrival": null, "card_delivery_estimate": null}}}}' | jq -r .id)   # → 200
curl -s "$CORTIQ/v1/feedback" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"id\": \"$ID\", \"question\": \"intent\", \"label\": \"card_arrival\"}"             # → 200
```

| Path | Access | Returns |
|---|---|---|
| `GET /v1/models` | open | the model in the shape of an OpenRouter provider listing (`id`, `pricing` as USD-per-token strings, `context_length` 512, `max_output_length` 255) plus `cmf.skills` with each gate |
| `GET /v1/skills` | key | every skill: `id`, `taxonomy_version`, `labels`, `certified`, `tau`, `theta`, `temperature` and `has_rubric` (whether it has a rubric; the rubric itself is per skill) |
| `GET /v1/skills/{id}` | key | the same plus `tasks`, the whole `gate` and `rubric` (`instructions`, `criteria`; `null` without one) |
| `GET /v1/usage` | key | the caller's account (router format; `x-cmf-extensions: 1` adds token and cost totals) |
| `GET /healthz` | open | status, model, generation, skills, `oracle` (on/off) and `oracle_status` (`ready`, `no_key`, `bad_key`, `disabled`, `budget_exhausted`, `budget_too_small`, `stopped: <reason>`; section 5) |

`/v1/models` only has the listing's shape; Cortiq Decision is not listed on
OpenRouter.

```bash
curl -s "$CORTIQ/v1/models" \
  | jq '.data[0] | {id, pricing, skills: [.cmf.skills[] | {id, labels, certified, tau}]}'   # → 200
curl -s "$CORTIQ/v1/skills" -H "Authorization: Bearer $KEY" \
  | jq '[.skills[] | {id, labels: (.labels | length), certified}]'                          # → 200
curl -s "$CORTIQ/v1/usage" -H "Authorization: Bearer $KEY" -H 'x-cmf-extensions: 1' \
  | jq '{account, totals: .cmf.totals}'                                                     # → 200
```

## 4. cortiq-router API (schema 1.1)

The same server answers the router's API with exactly its keys, JSON types and
error envelope, so existing clients need no change:

| Path | Access |
|---|---|
| `POST /v1/route`, `POST /v1/route:batch` (up to 1024 inputs) | key |
| `POST /v1/feedback` `{request_id, correct_task_label}` (`accepted: false` for a key without `learning_allowed`) | key |
| `GET /v1/taxonomies`, `GET /v1/taxonomies/{id}` | key |
| `GET /v1/usage`, `GET /v1/escalations?limit=N` | key (own account only) |
| `GET /v1/healthz`, `GET /v1/readyz`, `GET /metrics` (Prometheus) | open |
| `POST /v1/admin/keys`, `GET /v1/admin/keys`, `DELETE /v1/admin/keys/{account}` | `x-admin-token` |

* `taxonomy_id` is a skill id (`banking77`, `clinc150`, `massive`, or your
  own); without it the server uses `default_skill`, else the file's only skill.
* `options`: `policy_profile` (`balanced`; also `cost-saver`, `quality-first`),
  `allow_oracle` (`true`: consent to the oracle for this input if it is
  undetermined), `allow_pii_egress` (`false`), `top_k` (3, 1–64),
  `return_explanation` (`false`), `routing_table_id` (adds `routing` when
  `routing_tiers` is configured).
* `decision.confidence` is the calibrated `p_top` (1 for an oracle or cache
  answer), `raw_confidence` the winner's `1/(1+E)`; `scores[]` carry
  `probability`, `score` and `reconstruction_error`. A rejected answer that is
  not escalated has the flag `low_confidence` and `confident: false`.
* `input.embedding` (bring your own vector) must have the signal's dimension
  (4480) and `embedding_model`; it is decided locally only.
* The header `x-cmf-extensions: 1` adds a `cmf` object (the `cmf-dec-…` id,
  action, `certified`, gate) to results, listings and errors, and
  `cmf.oracle_status` to `/v1/healthz`. Without it the responses have the
  router's keys only.
* The router's flags keep their vocabulary: an escalation the oracle does
  not answer is `low_confidence` plus `oracle_disabled` (also when the key
  variable is not set or not a key — `no_key` and `bad_key` appear only on
  the decisions API),
  `consent_off`, `budget`, `stopped` or `oracle_unavailable`, in the answer
  and in `/v1/escalations`; the hint of the decisions API is only logged.

```bash
curl -s "$CORTIQ/v1/route" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "I still have not received my new card"},
       "taxonomy_id": "banking77", "options": {"return_explanation": true}}' | jq   # → 200
```

```json
{
  "schema_version": "1.1",
  "request_id": "req_18d9004c29a85ce8000005",
  "decision": {
    "task_id": 12,
    "task_label": "card_arrival",
    "taxonomy_id": "banking77",
    "confidence": 0.9980738,
    "confident": true,
    "raw_confidence": 0.91119707,
    "margin": 0.116146445,
    "is_novel": false,
    "novelty_score": 0.40156537,
    "complexity": {
      "score": 0.1677992,
      "tier": "low",
      "factors": {"base": 0.2, "ambiguity": 0.0019261837, "novelty": 0.40156537, "margin": 0.07082844, "length": 0.2}
    },
    "source": "router",
    "flags": []
  },
  "scores": [
    {"task_id": 12, "task_label": "card_arrival", "probability": 0.9980738, "score": 0.91119707, "reconstruction_error": 0.097457424},
    {"task_id": 14, "task_label": "card_linking", "probability": 0.001209337, "score": 0.7950506, "reconstruction_error": 0.25778145},
    {"task_id": 1, "task_label": "activate_my_card", "probability": 0.00019758825, "score": 0.76862156, "reconstruction_error": 0.30103046}
  ],
  "explanation": {"top1_vs_top2": "card_arrival leads card_linking by 0.116 score", "decision_path": "router:certified"},
  "usage": {"billable_decisions": 1, "oracle_calls": 0},
  "meta": {
    "model_version": "cortiq/decision@386b6e43fd35",
    "taxonomy_version": "banking77@1",
    "latency_ms": 1.234917,
    "embedding_latency_ms": 1.986042,
    "served_by": "cortiq/0.7.8"
  }
}
```

With the configuration of section 1 (`default_skill`, `task_complexity`,
`routing_tiers`), a route without `taxonomy_id` goes to `banking77` and names
the client's model for the complexity tier:

```bash
curl -s "$CORTIQ/v1/route" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "someone used my card without my permission"},
       "options": {"routing_table_id": "default"}}' \
  | jq '{label: .decision.task_label, tier: .decision.complexity.tier, routing}'   # → 200
curl -s "$CORTIQ/v1/route:batch" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"taxonomy_id": "clinc150",
       "inputs": [{"text": "what will the weather be tomorrow"}, {"text": "set an alarm for 7 am"}]}' \
  | jq '[.results[].decision | {task_label, confident}]'                           # → 200
```

Feedback, listings and probes:

```bash
RID=$(curl -s "$CORTIQ/v1/route" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "can I get a card for my teenager"}, "taxonomy_id": "banking77"}' \
  | jq -r .request_id)                                                             # → 200
curl -s "$CORTIQ/v1/feedback" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"request_id\": \"$RID\", \"correct_task_label\": \"age_limit\"}"           # → 200
curl -s "$CORTIQ/v1/taxonomies" -H "Authorization: Bearer $KEY" \
  | jq '[.taxonomies[] | {taxonomy_id, taxonomy_version, labels: (.labels | length)}]'   # → 200
curl -s "$CORTIQ/v1/usage" -H "Authorization: Bearer $KEY" | jq .usage          # → 200
curl -s "$CORTIQ/v1/escalations?limit=5" -H "Authorization: Bearer $KEY" | jq .summary   # → 200
curl -s "$CORTIQ/v1/healthz"                                                     # → 200
curl -s "$CORTIQ/v1/readyz"                                                      # → 200
curl -s "$CORTIQ/metrics" | grep '^cortiq_decisions_total'                       # → 200
curl -s "$CORTIQ/v1/route" -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "hello"}, "taxonomy_id": "data-assistant"}' | jq .error.code   # → 404
```

Router errors keep the router's envelope: `{"schema_version": "1.1",
"request_id": "req_…", "error": {"code": "<CODE>", "message": "…",
"retriable": bool, "details": null}}` with `INVALID_REQUEST` /
`EMBEDDING_REQUIRED` (400), `UNAUTHORIZED` (401), `QUOTA_EXCEEDED` (402),
`TAXONOMY_NOT_FOUND` (404, `details: {"taxonomy_id"}`), `RATE_LIMITED` (429);
`retriable` is true only for 429 and 500. A body the router's own framework
rejects is answered as the router answers it, in plain text: a non-JSON
content type 415, a body over `limits.body_bytes` 413, malformed JSON 400,
wrong field types 422.

## 5. Administration

Every admin path needs `x-admin-token` equal to the environment variable named
by `auth.admin_token_env` (`CORTIQ_DECISION_ADMIN_TOKEN`); when the variable is
unset the admin API answers 404 `ADMIN_DISABLED`.

| Path | Does |
|---|---|
| `POST / GET /v1/admin/keys`, `DELETE /v1/admin/keys/{account}`, `DELETE /v1/admin/keys/hash/{hash12}` | create (raw key returned once), list, revoke |
| `GET /v1/admin/usage` | usage of every account |
| `GET /v1/admin/oracle`, `POST /v1/admin/oracle {"enabled", "budget_usd", "max_calls"}` | oracle status: `status` (`ready`; `no_key` — the key variable is unset or empty; `bad_key` — it holds something that is not a key, never sent; `disabled` — not configured or switched off by the admin; `budget_exhausted` — something was spent and the budget (what is left cannot hold the smallest possible call, or a call it refused) or `max_calls` is used up; `budget_too_small` — nothing spent, and the budget cannot hold one call, `min_call_usd`, or `max_calls` is 0; `stopped: <reason>` — a stop rule), `configured` = `oracle.enabled` of the configuration, `enabled` = not switched off by a stop rule or the admin, `key_present`, `key_ok`, `key_problem` (by position and length, never a byte of the key), `key_trimmed` (surrounding whitespace was trimmed), `key_env` (the variable's name, never its value), `model`, `max_price`, `min_call_usd` (the least budget a call needs: the smallest possible call's reservation, or, once the budget refused a longer call — a budget below the smallest call included — that call's, the larger), spent, calls, stop reason, `last_error` (the code of the last failed call; both from a closed code set, another value read back from `oracle.state` is `unknown_code`); switch it and lower limits within the configuration (kept in `oracle.state` across restarts: when one of them refuses the next call, `cmf.hint` and the startup line name it and the `POST /v1/admin/oracle` that lifts it) |
| `GET /v1/admin/learning` | buffer, cache, quarantine, attempts, promotions, recent events |
| `GET /v1/admin/generations`, `POST /v1/admin/rollback {"generation": N}` | generations; serve generation N (0 = the base file) |
| `GET /v1/admin/shadow` | agreement statistics in shadow mode, and the routed requests not compared since the start (section 8) |

```bash
A="x-admin-token: $CORTIQ_DECISION_ADMIN_TOKEN"
curl -s "$CORTIQ/v1/admin/usage" -H "$A" | jq 'keys'                          # → 200
curl -s "$CORTIQ/v1/admin/oracle" -H "$A" | jq '{status, enabled, configured, key_present, budget_usd, spent_usd}'   # → 200
curl -s "$CORTIQ/v1/admin/learning" -H "$A" | jq '{generation, buffer: .buffer.examples, promotions}'       # → 200
curl -s "$CORTIQ/v1/admin/generations" -H "$A" | jq '{current, model}'        # → 200
curl -s "$CORTIQ/v1/admin/rollback" -H "$A" -H 'Content-Type: application/json' \
  -d '{"generation": 0}' | jq                                                   # → 200
```

With the server stopped, the same is available from the CLI:
`cortiq decision rollback --state DIR --to N --model FILE`, and
`cortiq decision materialize FILE --state DIR -o OUT.cmf` writes the served
generation as one self-contained file (this also works while a server runs).

## 6. Configuration reference

`--decision-config FILE` takes a JSON object; every field is optional and an
unknown key is an error. The defaults:

```json
{
  "state_dir": null,
  "default_skill": null,
  "auth": {"require": null, "admin_token_env": "CORTIQ_DECISION_ADMIN_TOKEN", "key_prefix": "cortiq_"},
  "limits": {"body_bytes": 1048576, "state_bytes": 32768, "questions": 32, "max_inflight": 64},
  "pricing": {"input_usd_per_1m": "0", "output_usd_per_1m": "0", "request_usd": "0",
              "oracle_passthrough": true, "oracle_markup": 1.0},
  "response": {"round": null},
  "oracle": {"enabled": false, "default_per_request": true,
             "base_url": "https://openrouter.ai/api/v1", "api_key_env": "OPENROUTER_API_KEY",
             "model": "deepseek/deepseek-v4.1-flash",
             "provider": {"sort": "price", "require_parameters": true, "allow_fallbacks": true,
                          "max_price": {"prompt": 0.1, "completion": 0.5}},
             "max_tokens_per_question": 64, "deadline_s": 30, "budget_usd": 1.0, "max_calls": 10000,
             "max_errors": 30, "redact_pii": true, "title": "cortiq-decision", "data_collection": null},
  "cache": {"enabled": true, "threshold": 0.97, "cap": 50000},
  "learning": {"enabled": true, "refit_min_new": 25, "dedup": 0.995, "cold_start": true, "synchronous": false},
  "feedback": {"pending_cap": 50000},
  "complexity_weights": {"base": 0.4, "ambiguity": 0.25, "novelty": 0.15, "margin": 0.1, "length": 0.1},
  "complexity_tiers": [{"tier": "low", "max": 0.33}, {"tier": "medium", "max": 0.66}, {"tier": "high", "max": 1.0}],
  "task_complexity": {},
  "routing_tiers": {}
}
```

`state_dir: null` means `<FILE>.state` next to the model. Secrets are never
part of the file: the admin token and the OpenRouter key are read from the
environment variables it names. `auth.plans` may override the plan table.
`oracle.base_url` must be https, or plain http to a loopback address only (a
local proxy). The oracle, cache and learning sections are explained in
[ORACLE.md](ORACLE.md). `cortiq serve --oracle MODEL` and its companions
override the `oracle` section (and `--no-oracle-learning` sets
`learning.enabled` false); a file that sets `oracle.provider` keeps its
`max_price` unless `--oracle-max-price` is given.

## 7. Your own model

A skill is trained from JSONL rows `{"text", "label"}`: a non-empty text up to
32 KiB, a label of 1–256 bytes, no other keys. Duplicates and conflicting
labels are kept (conflicts are reported). A label with a single training row
is kept inactive.

```bash
# the router's datasets_dir layout, read as its read_label_prompts does: one
# directory per label, every file in it, one text per line (trimmed, blank
# lines skipped); in a .jsonl file the line's "text" (else "prompt") string,
# else the line itself; a file that is not UTF-8 is skipped
python3 - datasets > train.jsonl <<'PY'
import json, os, sys
root = sys.argv[1]
for label in sorted(os.listdir(root)):
    d = os.path.join(root, label)
    if not os.path.isdir(d):
        continue
    for name in sorted(os.listdir(d)):
        p = os.path.join(d, name)
        if not os.path.isfile(p):
            continue
        try:
            lines = open(p, encoding="utf-8").read().split("\n")
        except (OSError, UnicodeDecodeError):
            continue
        for line in lines:
            text = line.strip()
            if not text:
                continue
            if name.endswith(".jsonl"):
                try:
                    v = json.loads(text)
                except ValueError:
                    v = None
                if isinstance(v, dict):
                    t = v["text"] if "text" in v else v.get("prompt")
                    if isinstance(t, str):
                        text = t
            print(json.dumps({"text": text, "label": label}, ensure_ascii=False))
PY
cat > question.json <<'EOF'
{
  "instructions": "Classify the task type of the user request.",
  "criteria": {
    "chitchat": "Small talk and greetings",
    "code": "Writing, fixing or explaining code",
    "creative-writing": "Stories, poems and other creative text",
    "extraction": "Pulling structured facts out of a text",
    "math": "Solving a math problem",
    "qa": "A factual question",
    "summarization": "Shortening a text",
    "translation": "Translating between languages"
  }
}
EOF
```

`train` takes the encoder of any decision file byte for byte and adds one
skill; `add-skill` copies every existing skill byte for byte and adds a new one
(an existing id is refused). Outputs are never overwritten.

```bash
cortiq decision train --encoder cortiq-decision.cmf --skill data-assistant \
  --train train.jsonl --question question.json -o data-assistant.cmf
cortiq decision add-skill cortiq-decision.cmf --skill data-assistant \
  --train train.jsonl --question question.json -o cortiq-decision-plus.cmf
cortiq decision info data-assistant.cmf
cortiq decision verify data-assistant.cmf
cortiq decide data-assistant.cmf -p "Write a Python function that merges two sorted lists"
```

* **Skill id**: `[a-z0-9][a-z0-9_-]{0,63}`; it is the `taxonomy_id` of the
  router API.
* **Several training files**: repeat `--train` (the published file was
  trained on train and dev).
* **Calibration**: `--calibration FILE`, or carved out of the training rows
  (inside each label, rows in sha256 order, every fifth row). The calibration
  rows are split by sha256 order into halves: the even half sets the
  temperature T and the novelty threshold θ (95th percentile), the odd half
  picks τ from a fixed grid of 14 thresholds. The gate is **certified** when a
  threshold keeps at least 100 accepted odd-half rows with a Clopper–Pearson
  lower bound ≥ 0.95 at α = 0.05/14; the one accepting the most rows wins.
  Otherwise the skill is served with θ only and `certified: false` (the small
  example above has 160 rows and is not certified). 20 % of the calibration
  rows are held out for self-learning (champion/challenger).
* **K** (`--k`, default 16) is the most directions per label (a label with n
  rows gets min(K, n − 1)). The published skills use K chosen by 5-fold
  cross-validation on train ∪ dev: 32 (banking77), 16 (clinc150),
  24 (massive).
* `--dev FILE` records dev accuracy in the skill; `--threads N` changes speed,
  never the result; `--json` prints the build report.
* After writing, the file is re-opened and the calibration errors, confidence
  and novelty are recomputed and compared bit for bit.

**Pre-training through the oracle** on unlabelled traffic: only the texts the
gate rejects are asked; answers already in driver ledgers are reused by
request sha256 (`--answers`). Each label with new examples is refitted,
checked on the holdout, and the gate is re-certified; if the certified gate
would be lost every promotion of the skill is undone. The effect measured on
the three public sets was neutral ([ORACLE.md](ORACLE.md#measured-effect)).

```bash
cat > traffic.jsonl <<'EOF'
{"text": "Could you tidy up this paragraph so it reads better"}
{"text": "What is the capital of Australia"}
{"text": "my flight got cancelled what now"}
{"text": "the invoice total looks wrong"}
{"text": "Book a table for two at 8 pm"}
EOF
cat > oracle.json <<'EOF'
{
  "oracle": {
    "enabled": true,
    "base_url": "https://openrouter.ai/api/v1",
    "api_key_env": "OPENROUTER_API_KEY",
    "model": "deepseek/deepseek-v4.1-flash",
    "budget_usd": 0.05,
    "max_calls": 100
  }
}
EOF
export OPENROUTER_API_KEY="<your OpenRouter key>"
cortiq decision learn data-assistant.cmf --traffic traffic.jsonl \
  --oracle-config oracle.json -o data-assistant-learned.cmf
```

The key is read from the variable `api_key_env` names
([ORACLE.md](ORACLE.md#connect-openrouter)); every live call is reserved in
`<OUTPUT>.oracle.jsonl` before it is sent.

Batch evaluation and timing (`--input` rows `{"text", "label"?}`; one JSON
result per row, never the text; totals on stderr):

```bash
cortiq decide data-assistant.cmf --input train.jsonl --bench --out rows.jsonl
```

## 8. Migrating from cortiq-router

### 8.1 Keys

Existing keys keep working without reissue: the router stores `sha256(raw)`
and so does this server. Export the router's `api_keys` table (and, for
continuous quotas, `usage_counters`) as JSON lines:

```text
mysql -N -B -r -e "SELECT JSON_OBJECT('key_hash',key_hash,'account',account,'plan',plan,
  'label',label,'active',active,'rate_per_min',rate_per_min,'decision_quota',decision_quota,
  'expires_at',expires_at,'created_at',created_at) FROM api_keys" cortiq > api_keys.jsonl
mysql -N -B -r -e "SELECT JSON_OBJECT('account',account,'decisions',decisions,
  'oracle_calls',oracle_calls) FROM usage_counters" cortiq > usage_counters.jsonl
```

```bash
cortiq decision keys import --state ./router.state --from api_keys.jsonl \
  --usage usage_counters.jsonl
```

* Also accepted: MySQL Shell, Workbench and phpMyAdmin JSON exports, and the
  `[[api_keys]]` of the router's TOML configuration (`--format router-toml`;
  raw keys are hashed as they are read).
* The import is idempotent, checks every row before writing anything, never
  overwrites or re-activates a stored key, and prints no key or hash.
* Imported keys may use the oracle (`oracle_allowed: true`, as every key could
  in the router); `--oracle-allowed=false` imports them without it.
* Imported keys do not teach the model (`learning_allowed: false`): their
  `/v1/feedback` is answered and consumed but not learned (`accepted:
  false`), where the router learned from every key; `--learning-allowed`
  imports them with it. The oracle's answers to their `/v1/route` still
  teach the skill (the route question is the skill's own).
* `--usage` writes the usage ledger: run it while no server holds the state
  directory. Importing a newer export again adds only the new keys, the
  revocations and the growth of the counters.

### 8.2 The taxonomy

A router taxonomy becomes a skill with the same id, trained from the router's
datasets (section 7 shows the conversion of a `datasets_dir`). The router's
self-learned examples are vectors of its own encoder (the router keeps no
texts), so they cannot be carried over; the new skill learns again from the
oracle and from feedback on live traffic.

### 8.3 Shadow mode, switch and rollback

Run the new server next to the old router with `--shadow-of URL`. Every request
to a router path is forwarded unchanged to the old router, with the client's
own `Authorization` header, and its answer goes back to the client byte for
byte (errors included), so clients see no change. A `/v1/route` or
`/v1/route:batch` that the old router answered 200 is also decided locally
(no oracle, no learning, no billing) and compared line by line in
`<state>/shadow.jsonl`: labels, confidence, latency and a keyed digest of the
text (HMAC-SHA256 under a random key kept in `<state>/shadow.key`), never the
text. An answer that is not a 200 — a missing or wrong key, a quota, an error
— is neither decided nor written. The comparisons have 4 slots of their own,
apart from the decisions API's `limits.max_inflight` (64 more may wait; one
past that is dropped), and at most 256 requests are forwarded at a time;
`GET /v1/admin/shadow` counts the requests not compared since the start
(`skipped`).

**Configuration.** The router's own settings do not come over by themselves;
write them into a decision configuration from the router's TOML. For the
router's `deploy/config.prod.toml`:

```bash
cat > router.json <<'EOF'
{
  "default_skill": "data-assistant",
  "auth": {"admin_token_env": "CORTIQ_ADMIN_TOKEN"},
  "complexity_tiers": [{"tier": "low", "max": 0.33}, {"tier": "medium", "max": 0.48},
                       {"tier": "high", "max": 1.0}]
}
EOF
export CORTIQ_ADMIN_TOKEN="<the router's admin token>"
```

* `default_skill` is the router's `taxonomy_id`. Router clients may leave
  `taxonomy_id` out; with several skills in the file and no `default_skill`
  such a request is 400. A skill id is `[a-z0-9][a-z0-9_-]{0,63}`: a router
  `taxonomy_id` outside that pattern (the default `general.task-type`) cannot
  be kept, and its clients have to send the new id.
* `auth.admin_token_env` names the router's variable, so that the portal's
  `x-admin-token` keeps working when this server answers `/v1/admin/keys`
  after the switch (the same token also reads `/v1/admin/shadow`).
* Copy `[complexity_weights]`, `[[complexity_tiers]]` (the default here is
  medium ≤ 0.66), `[task_complexity]` and `[routing_tiers]` (without them no
  response has a `routing` block) as JSON, and `[auth.plans]` if the router
  changes them (`duration_days` is `days` here, 0 is `null`).
* A router that escalated to an oracle: add the `oracle` section of
  [ORACLE.md](ORACLE.md#connect-openrouter).

`--shadow-of` reaches the old router over **https**, or over plain http **only
at a loopback address** (`127.0.0.1`, `::1`, `localhost`), because the
clients' keys pass through it. cortiq-router itself speaks plain http, with
TLS at nginx, so run the new server on the router's host and point it at the
router's own port there.

```bash
# on the router's host; the old router listens on port 8080
cortiq serve cortiq-decision-plus.cmf --decision-config router.json \
  --state ./router.state --port 8090 --shadow-of http://127.0.0.1:8080
```

A router on another machine is named by an https address in front of it
(`--shadow-of https://router-a.internal`); `--shadow-of http://router-a:8080`
is refused. `$ROUTER_KEY` below is the key of one of your router clients: it
was imported in 8.1, so both the old router and the new server accept it.

```bash
export SHADOW=http://127.0.0.1:8090
curl -s "$SHADOW/v1/route" -H "Authorization: Bearer $ROUTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "Write a haiku about autumn"}, "taxonomy_id": "data-assistant"}' \
  | jq .decision.task_label                                                     # → 200
curl -s "$SHADOW/v1/admin/shadow" -H "x-admin-token: $CORTIQ_ADMIN_TOKEN" \
  | jq '{lines, compared, agree, agreement, confident, latency_ms, skipped}'  # → 200
```

nginx on the same host, in place of the `upstream cortiq` block of the
router's `deploy/nginx/nginx.conf`:

```nginx
upstream cortiq {
    least_conn;
    server 127.0.0.1:8090;           # the new server: in shadow mode, then after the switch
    server 127.0.0.1:8080 backup;    # the old router: only while the new server restarts
    keepalive 64;
}
```

With nginx on another machine, as in the router's own `deploy/nginx`
(`server router-a:8080`), start the new server with `--host 0.0.0.0` as well
(it listens on `127.0.0.1` by default) and write `router-a:8090` and
`router-a:8080 backup` in the upstream; `--shadow-of` stays
`http://127.0.0.1:8080`. One state directory serves one process, so quotas
and usage are counted per server.

**1. Shadow.** Start the shadow server, point the upstream at it as above and
reload nginx. Clients are still answered by the old router. Watch
`GET /v1/admin/shadow` (overall agreement, agreement when both sides are
confident, per-label agreement, latency).

**2. Switch** only when the agreement and your own spot checks are good
enough. In shadow mode `/v1/admin/keys` went to the old router: keys the
portal minted or revoked since 8.1, and the decisions the router counted,
are only there. Hold the portal's admin calls, stop the shadow server
(Ctrl-C), export `api_keys` and `usage_counters` again as in 8.1 and import
them once more (new keys are added, keys the router marks inactive are
revoked, and only the growth of the counters is added), then start the
server on the same state directory and port without `--shadow-of`. nginx
sends requests to the old router (`backup`) while the new server is down;
nginx itself needs no change.

```bash
cortiq decision keys import --state ./router.state --from api_keys.jsonl \
  --usage usage_counters.jsonl
cortiq serve cortiq-decision-plus.cmf --decision-config router.json \
  --state ./router.state --port 8090
```

```bash
curl -s "$SHADOW/v1/route" -H "Authorization: Bearer $ROUTER_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": {"text": "Translate good morning into French"}, "taxonomy_id": "data-assistant"}' \
  | jq '{label: .decision.task_label, source: .decision.source}'                 # → 200
curl -s "$SHADOW/v1/usage" -H "Authorization: Bearer $ROUTER_KEY" | jq .usage   # → 200
```

**3. Rollback.** Leave `server 127.0.0.1:8080;` as the only line of the
upstream and reload nginx; the old router was never changed. Decisions the
new server counted after the switch stay in its own usage ledger, not in the
router's `usage_counters`.