core: let a requirement take its subjects from an object's keys

[pbeckham]

Adds a keys field to requirements. Each listed key of the object at from becomes a subject, with the key as its id. A key the object doesn't have is still a subject, so its checks fail as absent under that name.

Why

Evidence often arrives as an object keyed by name, and the policy knows which names must be there. A build might record its test runs like this:

{"build": {"test_runs": {
  "unit-test": {"result": "passed", "report_url": "https://ci.example.com/r/101"},
  "integration-test": {"result": "passed", "report_url": "https://ci.example.com/r/102"},
  "smoke-test": {"result": "passed", "report_url": "https://ci.example.com/r/103"}
}}}

and the rule is "unit-test, integration-test and system-test each ran, passed and attached a report". Today ergo can't express that directly. from turns a list into one subject per item, but an object becomes a single subject, and the entries don't carry their own name. That leaves three workarounds, and each has a cost:

• Reshape the input into a list before calling ergo. The checks are written once, but the policy is no longer checking the evidence as it arrived. Whether a missing run is caught depends on Rego outside ergo, which ergo's tests can't protect. If that code drops missing names, the requirement passes on the ones that are there.
• Write one requirement per name. Nothing is reshaped, but the same checks are copied for each name, and the report's requirement names change with the parameters.
• Make the parent object the subject and generate checks per name (unit-test.passed, system-test.passed, ...). There's one requirement, but the checks multiply with the names, and the report says the build failed system-test.passed rather than that the system test run failed passed.

With keys, the checks are written once against the evidence as it arrived, and each required name is checked by name:

"tests_passed": {
	"subject_type": "test run",
	"from": ["build", "test_runs"],
	"keys": ["unit-test", "integration-test", "system-test"],
	"checks": {
		"passed": {"description": "The tests passed", "op": "equals", "path": ["result"], "value": "passed"},
		"report": {"description": "The test report is attached", "op": "present", "path": ["report_url"]},
	},
}

Against the input above, the system test run fails passed and report with cause absent, and the smoke test run plays no part. A count-based check like min_subjects couldn't tell those apart, because there are still three entries.

Failing closed

• Keys are sorted and duplicates dropped, so key order doesn't change the report.
• from leading nowhere, or to something that isn't an object: every key is still a subject and fails as absent.
• An empty keys list gives no subjects, so $min_subjects fails.
• keys that isn't a list, or keys together with id, fails $well_formed, and the requirement is never met, even with min_subjects: 0 or require: "some". requirement_satisfied now checks this itself, because it doesn't go through well_formed.

Requirements without keys produce the same report as before. The $well_formed row only gains its keys and id inputs when keys is set.

Checks

• opa check --strict . --ignore .github, opa fmt --list . (prints nothing) and opa test . --ignore .github: 332/332 pass, 100% coverage.
• Removing the new guard from requirement_satisfied fails four of the new tests. Reading the id from the subject instead of the key fails seven.
• The REFERENCE.md example output comes from running the example with opa eval.

Not in this PR

A null item in a list-valued from is counted as a subject but loses its check rows, because its id can't be read from null. The requirement still fails, but the rows that would explain why are missing. That bug already exists on main and gets its own fix. Keyed subjects don't run into it, because their id comes from the key.

🤖 Generated with Claude Code

[jbpros]

With require: "some", a requirement with keys passes as soon as one key passes, even if the other keys are missing. With keys a and b and only a in the object, the report is compliant: true, and b fails passed as absent.

That's how some works everywhere else, so I wouldn't forbid it, because "at least one of these suites ran" is a fair thing to ask for. But the PR presents keys as "these names must be there", so someone could easily reach for some and get a pass they didn't expect. Could REFERENCE.md say what keys with some means, and could a test pin that behaviour down?

Separately, it would help if keys could also mean "every key the object has", for when the names aren't known in advance. Today a policy can do it with PR 42 by building the list itself:

run_keys := sort(object.keys(input.runs)) if is_object(input.runs) else := []

That works, but both parts are easy to get wrong. Without sort, keys is a set and $well_formed fails. Without the is_object guard, a missing runs or one that isn't an object makes the whole report undefined, so allow is false and there's no report saying why. Something like "keys": "*" would remove that code, and $min_subjects would still catch an empty or missing object.

[jbpros]

I've opened #52 for a broader way of choosing subjects that would cover keys too, as one step in from. It's worth deciding there before this merges, because once keys is a field on the requirement, ergo has to keep supporting it.

[jbpros]

#66 will likely replace this. It's the first half of #52, and it moves keys into a step at the end of from:

"from": ["build", "test_runs", {"each_as": "run", "keys": ["unit-test", "integration-test", "system-test"]}],

The behaviour is the same as here. Each key is a subject identified by its key, and a missing key fails as absent. Keys are sorted and duplicates dropped. Unlisted entries aren't checked. Without keys, every entry of the object is a subject. It also names the subject ($run), so checks inside all/any can read it.

Leaving this open until #66 is settled.

[jbpros]

Replaced by #66, now merged: keys lives on the each_as step at the end of from.