Repository navigation
feat(explain): add partial evaluation API with fail-closed root reads - #960
snehabandla wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Partial evaluation can return an unsound exact result because compile-time evaluation of defaults loses dependencies on unknown input.
5 open issues
Preserve default-comprehension dependencies when inferring Exact · New Propagate allocator errors when rendering unknown paths · New Bound unknown-path validation work and charge it to execution limits · New Skip unknown-path scans for roots with no unknowns · New Gate the regex limit case on the regex feature · New
What changed in this PR
Introduces partial evaluation to the RVM behind the default-off explanations feature, building on existing explanation report types. This first stage uses conservative root-read detection rather than generating residual conditions.
Changes:
- Adds structured unknown paths and validation for
inputandcontext. - Adds
RegoVM::partial_evalwithExact/Unsupportedreports, execution restrictions, and fatal-error handling. - Adds tests for validation, root reads, run isolation, and resource limits.
| File | Description |
|---|---|
src/rvm/vm/partial_eval/tests.rs |
Tests partial-evaluation behavior, validation, restrictions, and errors. |
src/rvm/vm/partial_eval.rs |
Implements validation, evaluation, root-read detection, and warnings. |
src/rvm/vm/mod.rs |
Feature-gates the partial-evaluation module. |
src/rvm/vm/machine.rs |
Stores settings and per-evaluation state. |
src/rvm/vm/dispatch.rs |
Invokes partial-evaluation hooks during instruction dispatch. |
src/explain/settings.rs |
Defines unknown roots, paths, and partial-evaluation settings. |
src/explain/mod.rs |
Exports the new settings types. |
src/explain/error.rs |
Adds validation and incompatible-execution errors. |
Review effort: Max
| Ok(PartialEvalResult { | ||
| kind, | ||
| status: ResidualStatus::Exact, |
There was a problem hiding this comment.
The compiler evaluates defaults at compile time, so this also affects normal RVM evaluation; I've documented it as a limitation here, and fixing it needs a compiled-program format change, which will be a separate follow-up.
| if let Some(other) = paths | ||
| .iter() | ||
| .find(|p| p.0 == root && (p.1.starts_with(segments) || segments.starts_with(&p.1))) |
There was a problem hiding this comment.
Agreed; bounding validation and charging it to the execution limits will be a follow-up PR.
There was a problem hiding this comment.
🟡 Changes recommended
Unknown-path validation performs unbounded quadratic work outside VM resource limits, allowing caller-supplied paths to monopolize a worker despite configured execution limits.
6 open issues
Preserve default-comprehension dependencies when inferring Exact Preserve entry-point rule kind with a prologue · New Gate the regex limit case on the regex feature Skip unknown-path scans for roots with no unknowns Bound unknown-path validation work and charge it to execution limits Propagate allocator errors when rendering unknown paths
Review effort: Max
dac56f0 to
81e4816
Compare
Add RegoVM::partial_eval behind the explanations feature. Callers declare unknown input or context paths in PartialEvalSettings. The paths are validated: they must not overlap, and no value may be supplied at or under them. Any read of a root with unknown paths makes the result Unsupported with a warning; otherwise the result is Exact with the concrete value. Partial evaluation errors in suspendable mode and when an explanation recorder is installed. Errors the VM treats as fatal are returned as errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
81e4816 to
5137e5c
Compare
There was a problem hiding this comment.
🟡 Changes recommended
Input-dependent defaults can produce unsound Exact results, while quadratic unknown-path validation runs outside configured VM execution limits.
5 open issues
Enforce memory limits during validation and warning creation · New Preserve default-comprehension dependencies when inferring Exact Check memory limits for root-only and numeric paths · New Bound unknown-path validation work and charge it to execution limits Document default-dependency limits on the public partial_eval API · New
4 resolved since last review
Review effort: Max
| if self.explain_enabled() { | ||
| return Err(ExplainError::PartialEvalWithRecorder); | ||
| } | ||
| let pe_state = self.validate_unknowns()?; |
There was a problem hiding this comment.
Fixed in a01e87f: validation, execution, diagnostics and report creation now share one VM memory budget, with cleanup and reuse regressions.
| let mut text = String::from(root_name(root)); | ||
| for segment in segments { | ||
| match *segment { | ||
| PathSegment::Key(ref key) => { | ||
| let quoted = Value::from(key.as_str()) | ||
| .to_json_str_compact() | ||
| .map_err(VmError::from)?; | ||
| text.push_str(&format!("[{quoted}]")); | ||
| } | ||
| PathSegment::Index(i) => text.push_str(&format!("[{i}]")), | ||
| } | ||
| } | ||
| Ok(text) |
There was a problem hiding this comment.
Fixed in a01e87f: explicit memory checks now cover both path shapes, with input/context regressions and unlimited-budget controls.
| /// separate runs. Returns [`ExplainError::PartialEvalUnknownRuleKind`] if the | ||
| /// kind of rule whose result the entry point returns can't be told, | ||
| /// which only happens for programs not produced by the built-in | ||
| /// compilers. |
There was a problem hiding this comment.
This remains a known limitation requiring a compiled-program format change; it is documented publicly and tracked for a separate follow-up.
Keep one memory budget active through unknown-path validation, execution, diagnostics and report creation. Check root-only and numeric paths explicitly, release execution state on report-time memory failures, and document input-dependent defaults on the public API. Add regressions for budget enforcement, error precedence and VM reuse. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>



Summary
Adds the first part of partial evaluation to the RVM, behind the default-off
explanationsfeature. Callers declare whichinputorcontextpaths are unknown, andRegoVM::partial_evalreports whether the query result depends on them.This part is deliberately fail-closed. If the evaluation reads a root (
inputorcontext) that has unknown paths at or under it, the result isUnsupportedwith a warning that names the root and the source location of the read. Otherwise the result isExactwith the concrete query result. Later changes will track unknown values per register and produce residual conditions, so that more policies return a result instead ofUnsupported.API
PartialEvalSettings { unknowns },UnknownPath(a root andPathSegments, so keys with dots, quotes or digits need no escaping) andUnknownRoot { Input, Context }.RegoVM::set_partial_eval_settingsandRegoVM::partial_eval(entry_point) -> Result<PartialEvalResult, ExplainError>.ExplainErrorvariants:InvalidUnknownPath,UnknownValueSupplied,PartialEvalWithRecorder,PartialEvalSuspendable,PartialEvalUnknownRuleKind.Details
nullinput counts as absent when the wholeinputis unknown, sincenullis the VM's default input.Unsupported. Without a flagged read, errors are returned as usual.partial_evalreturnsPartialEvalUnknownRuleKindinstead of guessing. The built-in Rego and Azure Policy compilers never produce such entry points.MemoryLimitExceededinstead of being turned into a malformed path.input. The compiler evaluatesdefaultrule values once at compile time, wheninputis undefined. A default such asdefault reasons := [x | x := input.reasons[_]]is therefore fixed in the program, and partial evaluation does not see it as a read ofinput. Fixing this needs a change to the compiled program format and is left to a follow-up.partial_evalreturnsPartialEvalWithRecorderwhile an explanation recorder is installed. The same VM can run both, one after the other: take the recorder withtake_explanation_recorder()before callingpartial_eval. Suspendable execution returnsPartialEvalSuspendable.Optionper instruction and calls a cold#[inline(never)]hook only while partial evaluation runs.LoadInputandLoadContextare the only instructions that readinputandcontext.State owner and lifetime:
pe_settingsRegoVMset_partial_eval_settingspe: Option<Box<PeState>>RegoVM;Someonly insidepartial_evalpartial_evalcallPeState.input_has_unknowns,PeState.context_has_unknownsPeStatePeStatePeState.unsupported(first reason and pc)PeStatePeState; a fatal VM error is returned even when setpartial_evalrefuses to run while one is installed, beforepeis setCompatibility
Additive and behind the default-off
explanationsfeature. The new settings types andExplainErrorare#[non_exhaustive]. Behaviour withoutpartial_evalis unchanged.Related
Uses the
PartialEvalResultreport types from #876. The recorder check relates to the evaluation hooks from #898.Testing
src/rvm/vm/partial_eval/tests.rs: reading an unknown root isUnsupported(with acontexttwin that staysExact), repeated evaluations are isolated, whole-input unknowns, path validation and its messages, calls andcontextunknowns fail closed,withis rejected by the compiler, suspendable mode and an installed recorder are errors, fatal errors (instruction, regex and overflow limits) are returned, other errors after a read areUnsupported, unknowns index values as Rego does, and entry points whose rule kind cannot be determined are rejected (with out-of-range entry pcs and rule indexes still returning the VM error).tests/memory_limits.rs: a memory limit hit while rendering an unknown path is returned asMemoryLimitExceeded.cargo xtask pre-push(fmt, clippy, tests).cargo test --features explanations,azure_policy,yaml --lib --test mod: lib 1000 passed (2 ignored), mod 413 passed.cargo test --features explanations,allocator-memory-limits --test memory_limits: 56 passed.scalar_set_membership_preserves_results_under_memory_limitswas skipped because it also fails on the base branch.