Skip to content

feat(explain): add partial evaluation API with fail-closed root reads - #960

Open
snehabandla wants to merge 2 commits into
microsoft:mainfrom
snehabandla:explain/pe-core
Open

snehabandla wants to merge 2 commits into
microsoft:mainfrom
snehabandla:explain/pe-core

Conversation

@snehabandla

@snehabandla snehabandla commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds the first part of partial evaluation to the RVM, behind the default-off explanations feature. Callers declare which input or context paths are unknown, and RegoVM::partial_eval reports whether the query result depends on them.

This part is deliberately fail-closed. If the evaluation reads a root (input or context) that has unknown paths at or under it, the result is Unsupported with a warning that names the root and the source location of the read. Otherwise the result is Exact with the concrete query result. Later changes will track unknown values per register and produce residual conditions, so that more policies return a result instead of Unsupported.

API

  • PartialEvalSettings { unknowns }, UnknownPath (a root and PathSegments, so keys with dots, quotes or digits need no escaping) and UnknownRoot { Input, Context }.
  • RegoVM::set_partial_eval_settings and RegoVM::partial_eval(entry_point) -> Result<PartialEvalResult, ExplainError>.
  • New ExplainError variants: InvalidUnknownPath, UnknownValueSupplied, PartialEvalWithRecorder, PartialEvalSuspendable, PartialEvalUnknownRuleKind.

Details

  • Validation. Unknown paths must not overlap, and no value may be supplied at or under one. A value counts as supplied wherever Rego would read one: a key also selects a set member and an index also selects an object's number key. A null input counts as absent when the whole input is unknown, since null is the VM's default input.
  • Errors. Errors the VM treats as fatal (resource limits, numeric overflow, builtin limits) are always returned as errors, so limits are enforced. Other errors after a flagged read may come from an unknown being undefined, so they give Unsupported. Without a flagged read, errors are returned as usual.
  • Result kind. The result kind (complete, partial set, partial object) comes from the rule that the entry point returns. If an entry point's code does not show which rule it returns and the program has partial or function rules, partial_eval returns PartialEvalUnknownRuleKind instead of guessing. The built-in Rego and Azure Policy compilers never produce such entry points.
  • Path rendering. Paths in validation errors are rendered with the VM's memory checks. A memory limit hit while rendering is returned as MemoryLimitExceeded instead of being turned into a malformed path.
  • Limitation: defaults that read input. The compiler evaluates default rule values once at compile time, when input is undefined. A default such as default reasons := [x | x := input.reasons[_]] is therefore fixed in the program, and partial evaluation does not see it as a read of input. Fixing this needs a change to the compiled program format and is left to a follow-up.
  • Separate runs. partial_eval returns PartialEvalWithRecorder while an explanation recorder is installed. The same VM can run both, one after the other: take the recorder with take_explanation_recorder() before calling partial_eval. Suspendable execution returns PartialEvalSuspendable.
  • Cost when not in use. With the feature enabled, the VM checks one Option per instruction and calls a cold #[inline(never)] hook only while partial evaluation runs. LoadInput and LoadContext are the only instructions that read input and context.
  • Residual queries are always empty in this change.

State owner and lifetime:

State Owner Lifetime Invalidation Error path
pe_settings RegoVM until the next set_partial_eval_settings replaced by the setter evaluation never modifies it
pe: Option<Box<PeState>> RegoVM; Some only inside partial_eval one partial_eval call set after validation, taken right after the run nothing can return between set and take, so a VM error still clears it; validation errors return before it is set
PeState.input_has_unknowns, PeState.context_has_unknowns PeState one evaluation fixed after validation dropped with PeState
PeState.unsupported (first reason and pc) PeState one evaluation first flag wins, never cleared dropped with PeState; a fatal VM error is returned even when set
explanation recorder caller caller-controlled — partial_eval refuses to run while one is installed, before pe is set

Compatibility

Additive and behind the default-off explanations feature. The new settings types and ExplainError are #[non_exhaustive]. Behaviour without partial_eval is unchanged.

Related

Uses the PartialEvalResult report types from #876. The recorder check relates to the evaluation hooks from #898.

Testing

  • New tests in src/rvm/vm/partial_eval/tests.rs: reading an unknown root is Unsupported (with a context twin that stays Exact), repeated evaluations are isolated, whole-input unknowns, path validation and its messages, calls and context unknowns fail closed, with is 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 are Unsupported, 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).
  • New test in tests/memory_limits.rs: a memory limit hit while rendering an unknown path is returned as MemoryLimitExceeded.
  • 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_limits was skipped because it also fails on the base branch.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Partial evaluation can return an unsound exact result because compile-time evaluation of defaults loses dependencies on unknown input.

5 open issues
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 input and context.
  • Adds RegoVM::partial_eval with Exact/Unsupported reports, 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

Comment on lines +157 to +159
Ok(PartialEvalResult {
kind,
status: ResidualStatus::Exact,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/rvm/vm/partial_eval.rs Resolved
Comment on lines +171 to +173
if let Some(other) = paths
.iter()
.find(|p| p.0 == root && (p.1.starts_with(segments) || segments.starts_with(&p.1)))

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed; bounding validation and charging it to the execution limits will be a follow-up PR.

Comment thread src/rvm/vm/partial_eval.rs Resolved
Comment thread src/rvm/vm/partial_eval/tests.rs Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Review effort: Max

Comment thread src/rvm/vm/partial_eval.rs Resolved
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if self.explain_enabled() {
return Err(ExplainError::PartialEvalWithRecorder);
}
let pe_state = self.validate_unknowns()?;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a01e87f: validation, execution, diagnostics and report creation now share one VM memory budget, with cleanup and reuse regressions.

Comment on lines +92 to +104
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)

@snehabandla snehabandla Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants