frutebox-node 0.1.0__py3-none-any.whl

frutebox/signedconfig.py

@@ -0,0 +1,259 @@
+"""Control-plane-signed configuration, and what a gateway does when it goes stale (file 02-A5).
+
+WHY SIGNED
+Policy, the model registry and feature flags decide which models may run, which nodes are
+eligible, and what a user is allowed to do. A gateway that accepts those over plain HTTP trusts
+whoever can answer as the directory — DNS, a proxy, a compromised sibling. So the control plane
+signs the blob and a gateway REFUSES anything unsigned or badly signed. There is no "warn and
+apply": applying unverified policy is the failure, not the warning.
+
+The signature is the repo's existing hybrid Ed25519 + ML-DSA-65 (`signing.py`), so the config
+path is post-quantum on the same terms as everything else (global rule 9).
+
+WHY DEGRADED AUTONOMY
+The alternative to serving on a slightly stale policy is refusing to serve at all the moment the
+directory is unreachable — turning a control-plane blip into a full outage while the nodes sit
+idle and perfectly capable. So a gateway keeps serving on the last VERIFIED blob:
+
+    fresh        (< FRUTEBOX_CONFIG_TTL_S,    default 900 s)  normal
+    autonomous   (< FRUTEBOX_AUTONOMY_MAX_S,  default 6 h)    serving, refresh failing, noisy
+    fail-closed  (beyond that)                                refuse NEW network jobs, 503
+
+Fail-closed is the honest end state: after six hours of not being able to check, we no longer
+know whether a node was revoked or a model was withdrawn, and continuing to dispatch on that is
+worse than an honest error.
+
+LOCAL INFERENCE IS NEVER AFFECTED. It does not pass through here, and cutting a user's own
+on-device model because OUR control plane is unreachable would punish them for our problem.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Dict, Optional
+
+from . import signing
+from .envvars import env as envvar
+
+#: How long a signed blob is considered current.
+CONFIG_TTL_S = float(envvar("CONFIG_TTL_S", "900"))
+
+#: How long we will keep serving on a blob we can no longer refresh.
+AUTONOMY_MAX_S = float(envvar("AUTONOMY_MAX_S", "21600"))
+
+#: The signing key lives in the PORTABLE secret store (README rule 10) — an env var delivered by
+#: whatever the deployment uses, never Google Secret Manager or Azure Key Vault, so the platform
+#: can move clouds. Referenced by NAME here; the value never appears in code or logs.
+SIGNING_SEED_ENV = "FRUTEBOX_CONFIG_SIGNING_KEY"
+
+#: Gateways verify with a public key baked into the image at build time, so a gateway cannot be
+#: talked into trusting a new signer by anything it receives at runtime.
+PUBLIC_KEY_ENV = "FRUTEBOX_CONFIG_PUBLIC_KEY"
+
+#: Read through `envvar`, which tries FRUTEBOX_ then STEVAI_.
+#:
+#: ⚠️ THESE TWO WERE RAW `os.environ.get(PUBLIC_KEY_ENV)` AGAINST A HARD-CODED `STEVAI_` NAME, AND
+#: THAT MADE THE RENAME A SILENT DISARM. `enforcing()` below returns True *exactly when* the public
+#: key is set, and that is what arms signed-config enforcement. So renaming the variable on the
+#: service to `FRUTEBOX_CONFIG_PUBLIC_KEY` — which F-86 instructs every lane to do today — would have
+#: made `enforcing()` return False, and the gateway would have stopped requiring signed configuration
+#: WITH NO ERROR ANYWHERE. A security control switched off by a correct-looking rename.
+#:
+#: The seed half fails the other way, safely but just as quietly: signing would refuse with
+#: "not set" while the value sat in the environment under the other spelling.
+def config_public_key() -> str:
+    """The baked-in verification key, under either spelling. "" when unset."""
+    return (envvar("CONFIG_PUBLIC_KEY") or "").strip()
+
+
+def config_signing_seed() -> str:
+    """The signing seed, under either spelling. "" when unset. The VALUE never gets logged."""
+    return (envvar("CONFIG_SIGNING_KEY") or "").strip()
+
+#: The last blob we verified. Mutated, never rebound.
+CACHE: Dict[str, Any] = {"config": None, "verified_at": 0.0, "issued_at": 0.0, "source": ""}
+
+
+class ConfigRejected(Exception):
+    """The blob did not verify. The caller must NOT apply it."""
+
+
+class NoVerifyKey(ConfigRejected):
+    """We have no key to verify WITH — a different finding from "verified and failed".
+
+    A distinct type because the caller's decision hinges on it, and hinging it on a substring of the
+    message (`if "not set" in str(e)`) means one reworded sentence silently turns a refusal into a warning.
+    """
+
+
+def sign_blob(kind: str, payload: dict, *, ttl_s: float) -> str:
+    """Sign any small control-plane payload with the SAME hybrid key as the config. "" if we cannot.
+
+    ⚠️ THIS MODULE OWNS THE SEED, and that is why the function lives here. File 22 needed a signed
+    node-package manifest, and the first version read `SIGNING_SEED_ENV` from `directory_public` — which
+    another lane's guard caught immediately (`test_provider_credential_env_bypass_guard`: an environment
+    variable read through a COMPUTED name is the obvious way to reintroduce a credential bypass, so it
+    must be reviewed). The guard was right about more than it could see: a second module reaching for
+    another module's secret env var is also how two spellings of one key name start to drift.
+
+    `kind` is carried INSIDE the signed claims, so a ticket minted for one purpose cannot be replayed as
+    another — a config blob must not pass as a package manifest, and `verify_blob` checks it.
+
+    Returns "" when no seed is configured, rather than raising: an unsigned manifest is a state the
+    caller must be able to report honestly. `sign_config` keeps raising, because a config that cannot be
+    signed must not be published at all.
+    """
+    # NO `seed_hex` OVERRIDE, and it had one until another lane's guard caught it: nothing in production
+    # supplied it, so the branch behind it was proven by tests and unreachable in the product
+    # (`test_no_unsupplied_keyword_args`). `sign_config` keeps its override because the control plane
+    # genuinely passes one; copying the parameter here was habit, not a requirement.
+    seed = config_signing_seed()
+    if not seed:
+        return ""
+    try:
+        priv, _pub = signing.keypair_from_seed(seed)
+        return signing.mint_ticket(priv, {"kind": kind, **payload}, ttl_s=ttl_s)
+    except Exception:
+        # Signing must never take an endpoint down. The caller reports it as unsigned, which is true.
+        return ""
+
+
+def verify_blob(kind: str, blob: str, *, public_key: str = "") -> dict:
+    """Verify a `sign_blob` payload and return its claims. Raises `ConfigRejected`.
+
+    No "unsigned is fine" branch, deliberately: a caller that wants to tolerate an unsigned deployment
+    decides that in the open, where it can be read, rather than inheriting it from a library default.
+    """
+    pub_b64 = public_key or config_public_key()
+    if not pub_b64:
+        raise NoVerifyKey(f"{PUBLIC_KEY_ENV} is not set — refusing an unverifiable {kind} payload")
+    if not blob:
+        raise ConfigRejected(f"the {kind} payload carries no signature")
+    try:
+        claims = signing.verify_ticket(signing.load_public_key(pub_b64), blob)
+    except Exception as e:
+        raise ConfigRejected(f"signature did not verify: {type(e).__name__}") from e
+    if claims.get("kind") != kind:
+        raise ConfigRejected(f"wrong ticket kind {claims.get('kind')!r}")
+    return claims
+
+
+def sign_config(config: dict, *, seed_hex: str = "") -> str:
+    """Sign a config blob. Runs on the control plane, never on a gateway."""
+    seed = seed_hex or config_signing_seed()
+    if not seed:
+        raise ConfigRejected(f"{SIGNING_SEED_ENV} is not set — cannot sign configuration")
+    priv, _pub = signing.keypair_from_seed(seed)
+    claims = {"kind": "gateway-config", "issued_at": time.time(), "config": config}
+    # The ticket stays verifiable through the whole autonomy window; STALENESS is our policy to
+    # judge (below), not the token's. Folding both into one expiry would mean a blob that is
+    # merely stale becomes indistinguishable from one that is forged.
+    return signing.mint_ticket(priv, claims, ttl_s=AUTONOMY_MAX_S * 2)
+
+
+def verify_config(blob: str, *, public_key: str = "") -> dict:
+    """Verify and return the config. Raises `ConfigRejected` on anything suspicious."""
+    pub_b64 = public_key or config_public_key()
+    if not pub_b64:
+        # No baked-in key means we cannot tell the control plane from an impostor. Refusing is
+        # the only safe answer; applying "because it is probably fine" is the whole attack.
+        raise ConfigRejected(f"{PUBLIC_KEY_ENV} is not set — refusing unverifiable configuration")
+    if not blob:
+        raise ConfigRejected("empty configuration blob")
+    try:
+        pub = signing.load_public_key(pub_b64)
+        claims = signing.verify_ticket(pub, blob)
+    except Exception as e:
+        raise ConfigRejected(f"signature did not verify: {type(e).__name__}") from e
+
+    if claims.get("kind") != "gateway-config":
+        raise ConfigRejected(f"wrong ticket kind {claims.get('kind')!r}")
+    config = claims.get("config")
+    if not isinstance(config, dict):
+        raise ConfigRejected("configuration payload is not an object")
+    return {"config": config, "issued_at": float(claims.get("issued_at") or 0.0)}
+
+
+def apply_blob(blob: str, *, public_key: str = "", source: str = "") -> dict:
+    """Verify a blob and make it the live config. Returns the config it applied."""
+    result = verify_config(blob, public_key=public_key)
+    CACHE.update({"config": result["config"], "verified_at": time.time(),
+                  "issued_at": result["issued_at"], "source": source})
+    return result["config"]
+
+
+def age_s(now: Optional[float] = None) -> float:
+    """Seconds since the live config was issued. `inf` when we have never had one."""
+    issued = float(CACHE.get("issued_at") or 0.0)
+    if not issued:
+        return float("inf")
+    return max(0.0, (now if now is not None else time.time()) - issued)
+
+
+def status(now: Optional[float] = None) -> str:
+    """'fresh' | 'autonomous' | 'fail-closed'."""
+    if CACHE.get("config") is None:
+        return "fail-closed"
+    a = age_s(now)
+    if a <= CONFIG_TTL_S:
+        return "fresh"
+    if a <= AUTONOMY_MAX_S:
+        return "autonomous"
+    return "fail-closed"
+
+
+def enforcing() -> bool:
+    """Whether signed-config enforcement is live on this gateway.
+
+    It activates exactly when the operator bakes a public key into the image. Before that there
+    is no config distribution to refresh FROM, so enforcing would mean every gateway refuses
+    every network job the moment this code ships — turning a not-yet-deployed feature into a
+    total outage. Provisioning the key is the deliberate act that arms it.
+    """
+    return bool(config_public_key())
+
+
+def accepting_network_jobs(now: Optional[float] = None) -> bool:
+    """Whether this gateway may still dispatch NEW network work.
+
+    False does not mean the product is down: local/on-device inference never passes through
+    here and is deliberately untouched.
+    """
+    if not enforcing():
+        return True
+    return status(now) != "fail-closed"
+
+
+def refusal_reason(now: Optional[float] = None) -> str:
+    """A message a user can act on, rather than a bare 503."""
+    if CACHE.get("config") is None:
+        return ("this gateway has never received a signed configuration and will not dispatch "
+                "network jobs without one")
+    hours = age_s(now) / 3600.0
+    return (f"this gateway has not been able to refresh its signed configuration for "
+            f"{hours:.1f}h (limit {AUTONOMY_MAX_S / 3600:.0f}h); it is refusing new network "
+            f"jobs rather than dispatching on policy it can no longer verify")
+
+
+def current(now: Optional[float] = None) -> Optional[dict]:
+    """The live config while it may still be used, else None."""
+    return CACHE.get("config") if accepting_network_jobs(now) else None
+
+
+def snapshot(now: Optional[float] = None) -> dict:
+    """For /health, so the degradation is visible before it becomes an outage."""
+    a = age_s(now)
+    return {
+        "enforcing": enforcing(),
+        "status": status(now),
+        "age_s": None if a == float("inf") else round(a, 1),
+        "ttl_s": CONFIG_TTL_S,
+        "autonomy_max_s": AUTONOMY_MAX_S,
+        "accepting_network_jobs": accepting_network_jobs(now),
+        "source": CACHE.get("source") or "",
+    }
+
+
+def reset() -> None:
+    CACHE.update({"config": None, "verified_at": 0.0, "issued_at": 0.0, "source": ""})

frutebox/signing.py

@@ -0,0 +1,208 @@
+"""Signed authorization tickets — HYBRID classical + post-quantum (Ed25519 +
+ML-DSA-65 / FIPS 204).
+
+Only the directory (the control plane) holds the operator's private keys (derived
+deterministically from a 32-byte seed), so only it can *mint* a ticket that says
+"this request, for this model, in this region, is authorized." Gateways are given
+only the **public keys**; they can *verify* a ticket but can never forge one —
+even a fully compromised gateway cannot self-authorize traffic.
+
+HYBRID-BY-DEFAULT (§6): every ticket carries BOTH an Ed25519 signature and an
+ML-DSA-65 signature over the same payload, and verification requires BOTH to pass.
+We don't drop the classical algorithm — we pair it — so a ticket is safe if EITHER
+the classical curve OR the lattice scheme holds: Shor's algorithm breaks Ed25519 on
+a quantum computer, while an undiscovered flaw in a young PQC scheme would break
+ML-DSA on a classical one. This mirrors the Node side (`web/src/lib/crypto/pqc.ts`
+`hybridSign`/`hybridVerify` = Ed25519 + ML-DSA-65). Ed25519 comes from `cryptography`
+(already a dependency); ML-DSA from pure-Python `dilithium_py` — no new native build.
+
+The signing seed is a 32-byte secret the operator generates and sets as
+STEVAI_SIGNING_SEED; it must never pass through anyone but the operator, and it
+deterministically derives BOTH keys so tickets stay valid across restarts/clouds.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from typing import Tuple
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from dilithium_py.ml_dsa import ML_DSA_65
+
+_ALG = "ed25519+ml-dsa-65"
+
+
+def _b64u(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def _b64u_dec(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+class TicketError(Exception):
+    pass
+
+
+class TicketExpired(TicketError):
+    """The signatures verified, but `exp` has passed.
+
+    Kept DISTINCT from every other TicketError because the two mean opposite things
+    about the holder. A signature failure is evidence: somebody produced bytes the
+    operator never signed. An expiry is not — both signatures checked out, so the
+    holder is provably the legitimate subject of a grant that simply ran out (or the
+    signing seed rotated, or a clock drifted). Callers that punish tampering must not
+    punish this: treating a lapsed credential as forgery is how an honest node gets
+    slashed off the network for doing nothing wrong. Subclasses TicketError so every
+    existing `except TicketError` handler keeps working unchanged.
+    """
+
+
+@dataclass(frozen=True)
+class HybridPrivate:
+    ed_sk: Ed25519PrivateKey
+    dsa_sk: bytes
+
+
+@dataclass(frozen=True)
+class HybridPublic:
+    ed_pk: Ed25519PublicKey
+    dsa_pk: bytes
+
+
+def alg() -> str:
+    return _ALG
+
+
+def _pub_b64(ed_pk: Ed25519PublicKey, dsa_pk: bytes) -> str:
+    """Public form gateways receive: '<ed25519_pub>.<ml_dsa_pub>' (both b64url)."""
+    return f"{_b64u(ed_pk.public_bytes_raw())}.{_b64u(dsa_pk)}"
+
+
+def generate_keypair() -> Tuple[HybridPrivate, str]:
+    """Return (private, public_b64). Public form is what gateways get."""
+    ed_sk = Ed25519PrivateKey.generate()
+    dsa_pk, dsa_sk = ML_DSA_65.keygen()
+    return HybridPrivate(ed_sk, dsa_sk), _pub_b64(ed_sk.public_key(), dsa_pk)
+
+
+def keypair_from_seed(seed_hex: str) -> Tuple[HybridPrivate, str]:
+    """Deterministically derive BOTH operator keys from a 32-byte hex seed, so the
+    signing keys are STABLE across restarts and portable across clouds (same seed →
+    same keys → tickets stay valid after a redeploy). The Ed25519 and ML-DSA keys
+    are derived from independent sub-seeds so neither key leaks the other."""
+    raw = bytes.fromhex(seed_hex.strip())
+    if len(raw) != 32:
+        raise ValueError("signing seed must be 32 bytes (64 hex chars)")
+    ed_seed = hashlib.sha256(b"stevai-ed25519\x00" + raw).digest()
+    dsa_seed = hashlib.sha256(b"stevai-ml-dsa\x00" + raw).digest()
+    ed_sk = Ed25519PrivateKey.from_private_bytes(ed_seed)
+    dsa_pk, dsa_sk = ML_DSA_65._keygen_internal(dsa_seed)
+    return HybridPrivate(ed_sk, dsa_sk), _pub_b64(ed_sk.public_key(), dsa_pk)
+
+
+def load_public_key(pub_b64: str) -> HybridPublic:
+    """Gateways load the operator's public keys to verify tickets."""
+    try:
+        ed_b64, dsa_b64 = pub_b64.split(".", 1)
+    except ValueError:
+        raise TicketError("malformed public key")
+    return HybridPublic(
+        Ed25519PublicKey.from_public_bytes(_b64u_dec(ed_b64)),
+        _b64u_dec(dsa_b64),
+    )
+
+
+def sign_blob(priv: HybridPrivate, msg: bytes) -> str:
+    """Sign ARBITRARY BYTES with the same hybrid pair a ticket uses. `<ed_sig>~<dsa_sig>`, b64url.
+
+    FILE 22-3 asks for ML-DSA signatures "asserted on file-02 signed config AND file-17
+    appliance/update signing". The ticket functions below could not serve the second: a ticket
+    embeds `iat`/`exp` and expires in 30 seconds, which is right for a dispatch authorisation and
+    wrong for a release — a signed release must stay verifiable for as long as it is installable,
+    and its freshness is governed by the update metadata's own `expires`.
+
+    So this is the ticket's signing core without the lifecycle: both signatures over the caller's
+    own bytes, and `verify_blob` requires BOTH. One scheme for both halves of 22-3, rather than a
+    second scheme for the second half — which is how the two would come to disagree about what
+    "signed" means.
+    """
+    ed_sig = priv.ed_sk.sign(msg)
+    dsa_sig = ML_DSA_65.sign(priv.dsa_sk, msg)
+    return f"{_b64u(ed_sig)}~{_b64u(dsa_sig)}"
+
+
+def verify_blob(pub: HybridPublic, msg: bytes, sig: str) -> bool:
+    """Verify BOTH signatures over `msg`. One valid signature is not enough.
+
+    Returns a bool rather than raising, because its caller is a policy decision that collects
+    several reasons (`applianceupdate.verify_update`) rather than a request that must fail fast.
+    A malformed signature is `False`, never an exception reaching the caller — an update verifier
+    that threw on a hostile input would be a denial of service on the update path.
+    """
+    try:
+        ed_sig_b64, dsa_sig_b64 = str(sig or "").split("~", 1)
+    except ValueError:
+        return False
+    try:
+        pub.ed_pk.verify(_b64u_dec(ed_sig_b64), msg)
+    except Exception:
+        return False
+    try:
+        return bool(ML_DSA_65.verify(pub.dsa_pk, msg, _b64u_dec(dsa_sig_b64)))
+    except Exception:
+        return False
+
+
+def mint_ticket(priv: HybridPrivate, claims: dict, ttl_s: float = 30.0) -> str:
+    """Create a signed, short-lived ticket. Format:
+    <payload_b64>.<ed_sig_b64>~<dsa_sig_b64> — BOTH signatures over the payload."""
+    body = dict(claims)
+    now = time.time()
+    body["iat"] = round(now, 3)
+    body["exp"] = round(now + ttl_s, 3)
+    payload = _b64u(json.dumps(body, separators=(",", ":")).encode())
+    msg = payload.encode()
+    ed_sig = priv.ed_sk.sign(msg)
+    dsa_sig = ML_DSA_65.sign(priv.dsa_sk, msg)
+    return f"{payload}.{_b64u(ed_sig)}~{_b64u(dsa_sig)}"
+
+
+def verify_ticket(pub: HybridPublic, token: str) -> dict:
+    """Verify BOTH signatures + expiry; return the claims, or raise TicketError.
+    A ticket is rejected unless the Ed25519 AND the ML-DSA signature both check
+    out — one valid signature is not enough (defence-in-depth)."""
+    try:
+        payload, sigblob = token.split(".", 1)
+        ed_sig_b64, dsa_sig_b64 = sigblob.split("~", 1)
+    except ValueError:
+        raise TicketError("malformed ticket")
+    msg = payload.encode()
+
+    try:
+        pub.ed_pk.verify(_b64u_dec(ed_sig_b64), msg)
+    except InvalidSignature:
+        raise TicketError("classical (ed25519) signature check failed")
+    except Exception:
+        raise TicketError("classical (ed25519) signature malformed")
+
+    try:
+        dsa_ok = ML_DSA_65.verify(pub.dsa_pk, msg, _b64u_dec(dsa_sig_b64))
+    except Exception:
+        raise TicketError("post-quantum (ml-dsa) signature check failed")
+    if not dsa_ok:
+        raise TicketError("bad post-quantum signature")
+
+    claims = json.loads(_b64u_dec(payload))
+    if claims.get("exp", 0) < time.time():
+        # Signatures already checked out above, so the bearer IS the subject named in
+        # the payload — this is a lifecycle event, not an attack (see TicketExpired).
+        raise TicketExpired("ticket expired")
+    return claims

frutebox/thinkbudget.py

@@ -0,0 +1,155 @@
+"""How much reasoning this turn is worth — effort tiers, in ONE place, chosen by triage.
+
+THE PROBLEM, MEASURED on qwen3:4b via Ollama 0.35 (2026-10-11, local engine, temperature 0):
+
+    prompt "hi"                       751 chars of thinking, 196 output tokens, 4.7 s
+                                      ...for a 37-character answer.
+    prompt "Prove that the square
+    root of 2 is irrational"         2431 chars of thinking, 1266 output tokens, 29.9 s
+
+The second is the model earning its keep. The first is a page of chain-of-thought to say "Hi there!
+How can I help you today?" — and `THINK_ALWAYS = True` asks for it on every turn, because the owner's
+2026-10-03 ruling was that models must always think. That ruling stands; what was missing is that
+EFFORT is a separate decision from WHETHER.
+
+FOUR MECHANISMS WERE MEASURED BEFORE THIS MODULE WAS WRITTEN, AND THREE OF THEM DO NOT WORK. This
+matters more than the tiers, because each one looks like it works:
+
+  1. `think: "low"` / `"high"` — Ollama 0.35 ACCEPTS the string and qwen3:4b IGNORES it. Byte-for-byte
+     identical output to `think: true`: 751 chars, 196 tokens. A knob that is accepted and ignored is
+     worse than none, so NO level is sent at all — see the note on `BUDGET`.
+  2. `think: false` — costs THE SAME 196 tokens and moves the monologue into the answer: 798 chars of
+     content beginning "Okay, the user said 'hi'...". This is the finding already recorded at
+     `gateway.py:4260`, re-measured. It relocates the spend; it does not remove it.
+  3. `options.num_predict` as a thinking cap — genuinely bounds generation (24 tokens -> 88 chars of
+     thinking) and `done_reason: "length"` with an EMPTY ANSWER. It truncates the turn, not the
+     thinking.
+  4. Two-phase (cap the think, then re-ask for the answer with the truncated thinking as context) —
+     310 tokens and 7.9 s against a 196-token, 4.5 s baseline. MORE expensive, and phase two
+     monologued inline anyway. Refuted.
+
+SO THE BUDGET HAS TWO TEETH, AND NEITHER IS AN ENGINE PARAMETER ALONE:
+
+  * A CAP ON THE REASONING CHANNEL, enforced in the node's streaming loop. It bounds what the caller
+    receives, what the governance store keeps, and what the §6A post-gate has to screen — on every
+    engine, including one that ignores its own knob. It does NOT reduce engine tokens on such a
+    model, and this module does not pretend otherwise: measurement 1 is why.
+  * THE TIER AS A ROUTING SIGNAL. This is where the real saving is, and it is large: the same "hi" on
+    `llama3.2:1b` is 8 output tokens and 1.74 s against 196 tokens and 4.71 s — 24x the tokens and
+    2.7x the latency, for the same useful answer. `effort == NONE` is the selector's licence to take
+    a non-reasoning model in tier when the fleet has one. On the hard prompt the cheap model is NOT
+    a substitute, which is why this is a per-turn decision and not a fleet-wide one.
+
+NOT A FIXED MAX, which the brief is explicit about. The tier comes from the signals the gateway
+already computes before dispatch — `pipeline.triage` (keyword, microseconds) and `router.route()`,
+which already returns `reasoning_needed` and a tier and already runs at `gateway.py:4474`.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+#: The tiers, cheapest first. `max_reasoning_tokens == 0` means UNBOUNDED, not zero — a budget of
+#: nothing would be `NONE`, and the two must not be spelled the same way.
+NONE = "none"
+LOW = "low"
+MEDIUM = "medium"
+HIGH = "high"
+
+TIERS = (NONE, LOW, MEDIUM, HIGH)
+
+#: tier -> (max reasoning tokens forwarded, one-line reason)
+#:
+#: The numbers are sized against the measurement in this module's docstring: a hard prompt spent
+#: 2431 chars (~600 tokens) of thinking on qwen3:4b, so MEDIUM at 1024 does not bite a genuinely
+#: hard turn and HIGH is unbounded for the ones that are harder still. LOW at 192 is above the
+#: ~190 tokens the trivial prompt wanted and below the hard one, so it is a real cap rather than a
+#: number that never fires.
+BUDGET: dict[str, tuple[int, str]] = {
+    NONE:   (0,    "trivial: a greeting, an acknowledgement, or a one-token question"),
+    LOW:    (192,  "simple: answerable without multi-step work"),
+    MEDIUM: (1024, "ordinary: the default when nothing says otherwise"),
+    HIGH:   (0,    "hard: the triage or the router asked for reasoning"),
+}
+
+#: NO ENGINE LEVEL IS SENT, and that is a decision with a measurement behind it rather than an
+#: omission. Ollama's `think` takes EITHER a bool or a level string, so asking for a level means
+#: replacing the bool that is known to work. Measured 2026-10-11 on qwen3:4b / Ollama 0.35:
+#: `think: "low"` and `think: "high"` are both accepted and produce output byte-identical to
+#: `think: true` — 751 chars of thinking, 196 tokens, in every case. So sending a level would trade a
+#: field that works for one that does nothing on the roster's own default model. If a model that
+#: honours levels (gpt-oss) is ever served, this is the note that says what to add and what to
+#: re-measure first. Rule 12: there is no `engine_level()` here, because nothing would call it.
+
+#: NONE means "forward no reasoning at all"; HIGH means "do not bound it". Both are 0 in the table
+#: above and they are opposites, so the distinction is a function and not a comparison on the number.
+UNBOUNDED = {HIGH}
+
+
+def max_reasoning_tokens(tier: str) -> Optional[int]:
+    """The cap for this tier, or None for unbounded. `NONE` returns 0, which is a real cap."""
+    if tier in UNBOUNDED:
+        return None
+    return BUDGET.get(tier, BUDGET[MEDIUM])[0]
+
+
+def reason(tier: str) -> str:
+    return BUDGET.get(tier, BUDGET[MEDIUM])[1]
+
+
+#: TRIVIAL TURNS, matched on the WHOLE message rather than on a keyword anywhere in it. "hi" is
+#: trivial; "hi, can you prove the Collatz conjecture" is not, and a substring match would call both
+#: of them greetings. Anchored, and the message must be SHORT as well as matching — a 400-word
+#: message that happens to open with "thanks" is not an acknowledgement.
+_TRIVIAL_RE = re.compile(
+    r"^\s*(?:hi|hey|hello|yo|sup|hiya|howdy|good\s+(?:morning|afternoon|evening)|"
+    r"thanks|thank\s+you|thx|ta|cheers|ok|okay|k|cool|nice|great|got\s+it|"
+    r"yes|no|yep|nope|sure|please|bye|goodbye|see\s+you|good\s?night)"
+    r"[\s!.,?:;)\-~]*$",
+    re.IGNORECASE)
+
+#: Above this many characters a message is not trivial whatever it matches.
+TRIVIAL_MAX_CHARS = 32
+
+
+def is_trivial(query: str) -> bool:
+    """A greeting or an acknowledgement, and nothing else in the message."""
+    q = (query or "").strip()
+    return bool(q) and len(q) <= TRIVIAL_MAX_CHARS and bool(_TRIVIAL_RE.match(q))
+
+
+def effort_for(query: str, *, difficulty: str = "", reasoning_needed: Optional[bool] = None,
+               routed_tier: str = "", quality: str = "quality") -> str:
+    """The effort tier for this turn, from the signals the gateway already has before dispatch.
+
+    PRECEDENCE, and every step of it is a decision rather than a default:
+
+      1. TRIVIAL WINS OVER EVERYTHING. A greeting gets `NONE` even on the quality profile and even if
+         the router asked for reasoning, because there is nothing to reason about. This is the case
+         the brief is about.
+      2. The TRIAGE's "hard" and the ROUTER's `reasoning_needed` both mean HIGH. Either one is
+         enough: they are independent classifiers of the same question and a turn only has to look
+         hard to one of them to be worth the tokens. `routed_tier` in the top tiers (A/S) means the
+         same thing — a frontier-tier question is not a LOW-effort one.
+      3. The SPEED profile drops one tier. A caller who asked for speed asked for this.
+      4. Otherwise MEDIUM, which is the old behaviour bounded: 1024 tokens does not bite a turn that
+         was going to spend 600.
+
+    `quality` is read but is NOT the gate. `profile.quality` is "quality" for every request that says
+    nothing, so keying effort on it would mean MEDIUM-or-higher on every ordinary turn — the trap the
+    deleted thinking hint fell into and the one `CONFIG.cove_enabled` was added for.
+    """
+    if is_trivial(query):
+        return NONE
+    if difficulty == "hard" or reasoning_needed is True or (routed_tier or "").upper() in ("A", "S"):
+        return HIGH
+    if quality == "speed":
+        return LOW
+    return MEDIUM
+
+
+def describe(tier: str) -> dict:
+    """What this tier does, for a response's diagnostics. No secrets, no prompt text."""
+    cap = max_reasoning_tokens(tier)
+    return {"effort": tier, "max_reasoning_tokens": cap,
+            "unbounded": cap is None, "why": reason(tier)}