What does opa build --optimize do to a policy, and what must you give it?

## The same machinery, pointed the other way Partial evaluation is usually explained as "defer what you cannot decide". Build-time optimisation is the mirror image: **decide everything you can, now, so the request path does less**. `opa build --optimize` (short form `-O`) treats `input` as the unknown and the `data` packaged into the bundle as known, evaluates the policy as far as it can go, and writes out a generated policy that is equivalent but pre-specialised. ## What you must supply An **entrypoint**. Optimisation requires at least one `--entrypoint` (`-e`) naming the rule the bundle exists to answer, for example `-e backup/retention/compliant`. Without it, OPA has no target to specialise towards — every rule in the package would have to be preserved in full generality, which is the unoptimised case. This trips people up because a plain `opa build` needs no entrypoint at all; adding `-O` changes the requirement. ## What the levels mean `-O=1` is conservative and `-O=2` is aggressive: the higher level does more inlining of `data` documents and more specialisation of rule bodies. Practically, more optimisation means: - **longer builds** — the optimiser is doing evaluation work up front; - **potentially larger bundles** — inlined data is copied into the generated policy, sometimes several times over; - **cheaper evaluation at request time** — the work you paid for at build time is not repeated per decision. That is the whole trade, and which side you want depends on how latency-sensitive the decision path is and how often the bundle is rebuilt. ## The trap: inlined data is frozen This is the failure that catches teams. If a `data` document is visible to the optimiser, its values can be inlined into the generated policy. Pushing a new version of that data at runtime does not retroactively change the copies that were baked in — the decision keeps using what was compiled. So any value designed to change independently of the policy build, a per-tenant list or a threshold you tune without a release, must not be part of what the optimiser sees; it belongs in `input`, or in a data path deliberately kept out of the optimised build. ## The second trap: what runs is not what you wrote The generated policy is machine-produced. It is valid Rego, but it is not written for a human: rule names are synthesised, bodies are expanded, and reading it to debug a wrong decision is unpleasant. Two consequences. First, **test the built bundle**, not only the source modules, so your tests exercise the artifact that will actually answer requests. Second, when you are diagnosing a wrong answer, reproduce it against the unoptimised policy first; if the two disagree, that is a much more interesting bug than the one you started with, and it usually points at data that should not have been inlined. ## When to reach for it Reach for optimisation when the decision path is genuinely latency-sensitive — a sidecar or library evaluating on every request — and the policy does meaningful work over data that is stable between builds. Do not reach for it as a default. An unoptimised bundle is readable, debuggable, and fast enough for the overwhelming majority of gates that run once per change rather than once per request. Optimisation is a tuning step you apply when you have a number you are trying to hit, not a box you tick because the flag exists.