Crate cove_rules 

A Rust application that embeds the examples/rules package as a typed, bounded, inspectable decision engine.

The Cove half of this example is a pull-request review policy: six rules, a dyn Rule catalog, and one decide that turns a PullRequest into a Decision. examples/rules/README.md describes it. This half is what an embedder writes, and it exists because a rule engine has a shape nothing else in this repository has: it is compiled once and invoked many times, against inputs that arrive one at a time from the application around it.

Everything here uses the public embedding API and nothing else: cove_sema::Compiler with the embedder’s own ModuleSchema, cove_ir::lower_entry, cove_runtime::Vm or cove_runtime::interp::Interpreter, cove_runtime::HostRegistry, cove_runtime::Grants, cove_runtime::Budget, and cove_runtime::TraceSink. Nothing reaches into an internal module, and nothing duplicates a checker or runtime table.

What the embedding is shaped by

Two facts about the API decide the shape of everything below, and both are worth stating plainly because they are not obvious from the outside.

An exported function is called with values, and an entry is called with process arguments. Vm::invoke and Interpreter::invoke take a Vec<Value>, so Session::evaluate hands rules.embedded.evaluate a rules.policy.PullRequest the Rust side built and reads a rules.policy.Decision out of what came back. Nothing crosses the Host API boundary on that path at all. run_entry is still there and still takes a Vec<Rc<str>>, because a command has strings to hand over — Session::decide uses it, and what it costs against evaluate is the measurement in examples/rules/README.md.

This is the half of the example that changed. It was written when run_entry was the only way in: the request identifier went in as the one process argument and the pull request came back out through a Host API call into this crate’s own module, because there was no other channel. Issue #150 was that gap. The reviews module below is not a casualty of closing it — it is what the two paths are measured against each other with, and it is still what a host module is for, which is reaching something outside the process rather than carrying an argument into it.

A host module the toolchain does not ship is invisible to cove check. reviews is this crate’s, so cove check in examples/ reports one warning about examples/rules/embedded/embedded.cove, whose help text says to hand the schema to the compiler. That is what RulePackage::load does, and REVIEWS is the single value both the checker and the boundary read, so the two cannot drift. That no cove command can be handed one is issue #151.

The two things that are paid once

Parsing and resolving and checking the package, and lowering one entry to cove-ir’s executable IR. The two are RulePackage and Lowering, in that order, and cove-rules-measure reports what each of them costs against what one invocation costs. There used to be a third: the predecessor backend read a lowered program’s struct shapes, enum shapes and constants at construction time and built a table of each, so RulePackage::serve had a cost of its own worth reporting beside the other two. cove-ir computes every layout once, while lowering, and cove_runtime::Vm::new reads none of that back out of the program — it allocates the heap region and a table sized to the program’s string count, neither of which grows with how much the program declares. What RulePackage::serve costs is still reported, because a reader should not have to take “now cheap” on faith, but it is no longer a pass over the program the way the other two are.

Structs

Calls

A trace sink that keeps the host calls a run made, in order.

Decision

A policy and the findings that argued for it.

Embedding

Everything an embedding holds beside the compiled package: the registry a run calls through, the log the host writes decisions to, and the trace it records host calls in.

Finding

One thing a rule noticed, as the application receives it.

LoadCost

What loading and checking the rule package cost.

Lowering

What lowering one entry cost, and what it produced.

PullRequest

A pull request, as the application around this embedding holds one.

Recorded

What the host wrote down about one decision, under the request identifier that produced it.

Reviews

The embedder’s own host module: the pull requests the application holds, and the decisions it has been told about.

RulePackage

A rule package, parsed and checked once.

Session

One backend, ready to be invoked as many times as an embedder likes.

Enums

Fault

A way for a test to make the host misbehave, so that the boundary can be seen holding it to its own schema.

ReviewPolicy

What a review policy demands, as the application receives it.

Constants

REVIEWS

What reviews declares about itself.

REVIEWS_NEXT

The next version of REVIEWS, with one operation and one field added and nothing taken away.

REVIEWS_RENAMED

REVIEWS with changedLines renamed, which is the breaking change.

Functions

embedding

Registers reviews, grants grants, imposes limits, and watches the boundary.

embedding_without_trace

The same, with the trace sink left off.

package_root

Where the rule package lives, relative to this crate.

samples

The six pull requests this example is demonstrated on, by request identifier.

Type Aliases

RecordedCall

One recorded host call: the module, the operation, and the first argument when it was a string, which for reviews is the request identifier.