Skip to content

fix(cli): route policy commands to the bundle each action's scope binds - #1311

Merged
ragnorc merged 11 commits into
ModernRelay:mainfrom
ragnorc:fix/761-policy-bundle-routing
Nov 9, 2026
Merged

ragnorc merged 11 commits into
ModernRelay:mainfrom
ragnorc:fix/761-policy-bundle-routing

Conversation

@ragnorc

@ragnorc ragnorc commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

omnigraph policy validate|test|explain now pick a bundle per scope the way a server does. Graph actions are answered by the bundle bound to --graph <id>. graph_list and config_manage are answered by the bundle bound to cluster, compiled as a cluster bundle. Neither scope falls back to the other.

Closes #761

Reproduction

On main 2e7921c4 (and unchanged at ead05c40), with the layout docs/user/operations/policy.md documents (graph-access → [knowledge], server-access → [cluster]), every policy command refused:

graph `knowledge` in cluster `/tmp/.tmpAmwXtb` matches 2 policy bundles ([graph-access, server-access]); the cluster model expects one bundle per graph scope

The new test cli_data::policy_commands_route_each_action_to_its_bound_bundle_issue_761 fails on main with that error and passes with this change. It also covers the other two defects from the issue: a cluster whose only bundle is the cluster one (validated as a graph bundle on main, so config_manage was refused), and explain --action graph-list / config-manage (evaluated against the graph bundle on main, so the answer could never be allow).

Root cause

select_cluster_policy in crates/omnigraph-cli/src/commands/control/mod.rs matched every bundle bound to graph.<id> or cluster, required exactly one, and always compiled it with PolicyEngine::load_graph_from_source. Serving (crates/omnigraph-server/src/settings.rs) routes bindings to one slot per graph plus one cluster slot and loads the cluster slot with load_cluster_from_source. The CLI had drifted from that model.

Change

  • PolicyBundles::select resolves at most one graph-bound bundle (by --graph, or the sole graph-bound bundle without it) and at most one cluster bundle. Two bundles for one scope stay a loud error, as serving refuses them.
  • explain routes by PolicyAction::resource_kind(): Graph → graph bundle; Server/Cluster → cluster bundle.
  • test partitions cases the same way and runs each group against its bundle; failures from both groups are reported together.
  • validate checks each applied bundle of the selection as its own kind and prints one policy valid: line per bundle. It refuses only when neither scope has a bundle.
  • An action whose scope has no bundle is refused with a message naming the missing scope (no policy bundle bound to graph … / no policy bundle bound to the cluster scope), never answered by the other bundle.

Docs: docs/user/operations/policy.md (Validate and test) states the routing. Skill: references/server-policy.md replaces the "matches 2 policy bundles" limitation with the routing rule, and the matching row leaves the SKILL.md gotchas table. Release note: changelog.d/policy-commands-route-by-scope.fixed.md; docs/releases/v0.15.0.md regenerated.

Decisions and alternatives

  • Route by the action's resource kind rather than add a --scope flag: the action already determines which bundle a server consults, so a flag would only let the user pick a wrong answer.
  • No fallback between scopes, as the issue asks: a graph without its own bundle is not answered by the cluster bundle, and the reverse. Serving behaves this way.
  • Without --graph, keep the existing rule (the sole graph-bound bundle, else ask for --graph) instead of validating every graph's bundle; that would change output for multi-graph clusters and is not needed for this defect.

Evidence

  • Before: the new test fails on main with the refusal above. After: it passes.
  • cargo dev-nextest -E 'package(omnigraph-cli) | package(omnigraph-policy) | (binary(=integration) & test(/policy/))' (with RUST_MIN_STACK=16777216 as CI sets it): 829 of 830 pass. The one failure, cli_cluster::managed_lifecycle_capture_and_retry_records_refuse_symlinks_without_reading_targets (exit 1 instead of 2 on a symlinked cluster push source), is in managed cluster push code this change does not touch; the local box runs tests as root. CI on this PR is the reference for it.
  • cargo dev-clippy, cargo fmt --all --check, scripts/check-agents-md.sh, scripts/check-docs.py: clean.

Tests added

  • cli_data::policy_commands_route_each_action_to_its_bound_bundle_issue_761, with a converged_policy_cluster fixture in tests/support that applies a graph bundle, a cluster bundle, or both.

Risks and not verified

  • The CLI's output for policy validate gains a second line when a cluster bundle is applied. Scripts that read only the first line still see the graph bundle first.
  • GQT and DST were not run locally: neither depends on omnigraph-cli, which is the only crate whose code changed. Lance is not involved.

Workflow run: run-wf-reproduce-modernrelay-omnigraph-issue-20261109T0142Z-9674b3
Response run: run-wf-respond-modernrelay-omnigraph-pr-20261109T0310Z-90e65a
Response run: run-wf-respond-modernrelay-omnigraph-pr-20261109T0510Z-5e7651
Response run: run-wf-respond-modernrelay-omnigraph-pr-20261109T0640Z-4c2279

policy validate/test/explain matched every bundle bound to graph.<id> or
cluster and refused when both matched, which is the layout the policy guide
documents. A cluster bundle was also compiled as a graph bundle, and
graph_list/config_manage were evaluated against the graph bundle.

Select bundles per scope the way serving does: graph actions from the
--graph bundle, graph_list and config_manage from the cluster bundle, each
compiled as its own kind, with no fallback between scopes.

Closes ModernRelay#761

@ragnorc ragnorc left a comment

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.

Review of #1311 at 605f715a

Why. omnigraph policy validate|test|explain refused the layout that the docs tell users to apply: one bundle bound to a graph and one bundle bound to cluster (#761). A cluster with only a cluster bundle also failed, and explain --action graph-list asked the wrong bundle.

What and how. The CLI now selects at most one bundle for each scope, as serving does. A graph action uses the bundle bound to --graph. graph_list and config_manage use the cluster bundle, which is now compiled as a cluster bundle. When a scope has no bundle, the command refuses and names that scope. The other scope's bundle never answers.

Impact. The policy commands now work on a normal cluster. policy validate prints one line for each applied bundle.

Outcome: no blocking defects. I compared the routing with serving (crates/omnigraph-server/src/settings.rs:150-184) and with config validation, which already refuses a bundle that mixes binding kinds (policy_mixed_binding_kinds) and two bundles for one scope (duplicate_policy_binding, crates/omnigraph-cluster/src/config.rs). They agree. The new regression test fails on main for the predicted reason and passes at this head (see Validation). One design change is recommended (R1). The other items are optional.

Recommended (R1): the cause of #761 is still present

The cause of #761 is a copied rule. The CLI had its own copy of "applied bindings → one bundle per scope, compiled as its kind", and that copy drifted from serving. This PR replaces the wrong copy with a correct one. The rule now exists in three places:

  • server: crates/omnigraph-server/src/settings.rs:150-184. It fills one slot per graph and one cluster slot, then removes graph.og_catalog into a separate catalogue slot (line 184);
  • cluster deployment authorization: crates/omnigraph-cluster/src/authorization.rs:261-292. It compiles one engine per binding;
  • CLI: PolicyBundles::select (crates/omnigraph-cli/src/commands/control/mod.rs:239-310, this PR).

The rule "which bundle kind answers an action" also exists twice: scope_of (control/mod.rs:227) and validate_kind_alignment (crates/omnigraph-policy/src/lib.rs:716-726, where a cluster engine admits Cluster and Server actions).

The copies already differ. Serving does not count the catalogue binding as a graph bundle. The CLI without --graph counts every graph.* binding (control/mod.rs:271). A probe at this head, with a graph bundle, a cluster bundle and an og_catalog bundle applied:

$ omnigraph policy validate --target <cluster>
cluster `<cluster>` has 2 graph policy bundles ([catalogue-access, graph-access]); pass --graph <id> to select one

Serving finds one graph bundle in this layout. Main also refuses it (with "has 3 policy bundles"), so this is not a regression. It shows that the copies drift.

Proposal: make omnigraph-cluster, which owns ServingPolicy, the single owner. Add one function that routes &[ServingPolicy] into { cluster, catalogue, graphs: BTreeMap<graph id, bundle> } and refuses duplicate or unknown bindings. Use it in settings.rs, authorization.rs and this command. Also move the action-to-engine-kind mapping into omnigraph-policy (for example PolicyAction::engine_kind()), and use it in validate_kind_alignment and in the CLI.

  • Cost: one small public type, and about 40 lines moved from each caller.
  • Removes: two copies that can drift.
  • After five more changes of this kind, each change edits one place. Likely changes are stacked bundles per scope (the comment at settings.rs:151 calls them "a later slice") or a new scope kind. Today each one needs three edits that agree.

If this is too large for this PR, please open a follow-up issue. Also change the PolicyBundles doc comment so it says it is a copy of serving's routing, not only that it routes "the way serving routes them".

Optional

  • O1. One header for test failures. When both groups fail, the error repeats its header, because each run_tests call adds one and the loop joins them (control/mod.rs:104-120). Probe at this head:
    policy tests failed:
    andrew-reads: expected Allow but got deny
    policy tests failed:
    bruno-lists: expected Allow but got deny
    
    Collect the case lines from both groups and print one header.
  • O2. One fixture builder. converged_policy_cluster (tests/support/mod.rs:832) repeats the cluster.yaml template and setup of converged_loaded_cluster (tests/support/mod.rs:788). docs/dev/testing.md asks to extend the existing fixture. One builder with an optional graph bundle, an optional cluster bundle and an optional seed would keep one copy of the template.
  • O3. Coverage. The test covers "no --graph" only for the cluster-only layout. One validate call without --graph on the two-bundle layout would cover the main documented case on that path.

Checked and found correct

  • PolicyTestConfig::load still refuses a test file with version other than 1 before the cases are split, so a file with no cases cannot skip that check (probe: version: 2, cases: [] → policy test version must be 1).
  • Failure lines carry the case id, so splitting the cases does not renumber them.
  • The graph-id label used without --graph ("default") only names the Cedar resource entity. It does not change decisions, and the behavior is unchanged from main.
  • Context: #1175 adds maintain and reclaim as graph-scoped actions. scope_of sends them to the graph bundle with no change. Because the match over PolicyResourceKind is exhaustive, a new resource kind will fail to compile here. That is the correct failure mode.

Tradeoffs and liability

The PR removes a wrong rule and adds no public API, state or storage effect. Lance is not involved. It adds about 125 net lines to the CLI. Most of these are the third copy of the binding routing (R1), and that copy is the main long-term cost.

Validation

Clean detached worktree at 605f715a (base ead05c40 = current main).

  • Regression proof: cargo dev-nextest -E 'package(omnigraph-cli) & (test(/issue_761/) | test(/^cli_data::policy_/))'
    • at 605f715a: 4 passed;
    • with crates/omnigraph-cli/src/commands/control/mod.rs from ead05c40 (tests from the head): policy_commands_route_each_action_to_its_bound_bundle_issue_761 failed with graph `knowledge` in cluster … matches 2 policy bundles ([graph-access, server-access]), which is the predicted reason; the other 3 passed. The file was then restored.
  • cargo dev-nextest --no-fail-fast -E 'package(omnigraph-policy) | (package(omnigraph-cli) & (kind(lib) | kind(bin) | test(/policy/)))': 409 passed, 9 failed. All 9 failures are server-backed tests (system_local::local_cli_*_policy, system_remote::remote_policy_enforces_branch_first_cli_workflow, cli_data::a_policy_refused_served_load_reports_not_started). They failed with "server did not become ready or report its bound address" on this sandbox, also when run one at a time. None of them call the policy commands. Test Workspace passed at this exact head in CI.
  • CLI probes at 605f715a for O1, the catalogue case in R1, and the test-file version check (temporary clusters under /tmp, removed).
  • cargo fmt --all --check, git diff --check, scripts/check-agents-md.sh: clean. I did not run scripts/check-docs.py (this host lacks the pinned docs environment). CI reports it green.
  • CI at 605f715a: 26 passed, 4 skipped, 1 pending (Storage Upgrade Compatibility).
  • Not run: clippy, GQT, DST, the full workspace graph. This PR does not change GQT-expressible behavior, so a CLI integration test is the correct owner for the regression.

@ragnorc

ragnorc commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

I merged main (bd36563d) into this branch to clear a merge conflict. The branch can be merged again.

@ragnorc

ragnorc commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

I merged main (3f249cc0) into this branch to clear a merge conflict. The branch can be merged again.

@ragnorc

ragnorc commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

I merged main (373834b4) into this branch to clear a merge conflict. The branch can be merged again.

  • The only conflict was docs/releases/v0.15.0.md, a generated file. release(notes): link #1308 and order the v0.15.0 fixes #1315 changed it on main. I took main's copy and regenerated it with scripts/release_notes.py snapshot --replace (93cc2436). Against main, the file now adds only this PR's fixed note.
  • release(notes): link #1308 and order the v0.15.0 fixes #1315 added a ## Note order list to changelog.d/v0.15.0.md. This PR's note policy-commands-route-by-scope.fixed.md is not on that list, so the generator puts it after the listed fixes. I did not change the order. Add the note to the list if it should go elsewhere.
  • No code changed. The merge is f9a980b0, and the push is a fast-forward with no rebase or force.
  • Local checks: check-docs.py, check-agents-md.sh, release_notes.py verify --version v0.15.0, check-release-note.py and cargo fmt --check pass. cargo dev-test --test integration -- policy issue_761 issue_484 write_max_bytes passes: 83 passed, 0 failed.
  • CI on 93cc2436: 28 passed, 4 skipped, 0 failed.
  • There are no review comments to answer.

@ragnorc
ragnorc merged commit fc8f21e into ModernRelay:main Nov 9, 2026
34 checks passed
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.

policy commands refuse the documented graph-plus-cluster bundle layout

1 participant