Support proto-format plan bundles (opa build --format=proto)

[sspaink]

Summary

Add support for loading protobuf-format plan bundles produced by OPA's new opa build --format=proto flag (open-policy-agent/opa#8825, merged).

Background

OPA now emits IR plan bundles in two wire formats:

--format	Plan file	Manifest file
json (default)	/plan.json	/.manifest
proto (new)	/plan.pb	/.manifest.pb

The protobuf encoding is defined by the schemas added in open-policy-agent/opa#8775:

• v1/ir/plan.proto — the IR plan
• v1/bundle/manifest.proto — the bundle manifest

The proto form is significantly smaller on the wire (per the PR, a minimal policy produces plan.pb 469 bytes vs plan.json 2098 bytes; .manifest.pb 21 bytes vs .manifest 59 bytes). OPA's own bundle reader auto-detects either form and rejects mixed-format bundles.

Current state in this package

The package today only understands the JSON forms:

• BundleLoader switches on the hard-coded filenames plan.json, .manifest, and data.json, and DirectoryLoader.keepFiles is Set(["data.json", "plan.json", ".manifest"]).
• Policy.init(jsonData:) (Sources/IR/IR+Decode.swift) decodes the IR plan with JSONDecoder.
• OPA.Manifest(from:) (Sources/Rego/Manifest+Codable.swift) decodes the manifest from JSON.

There is no path to load a bundle built with --format=proto.

Proposed work

1. Bundle detection — teach BundleLoader / DirectoryLoader to recognize plan.pb and .manifest.pb alongside plan.json / .manifest, matching OPA's auto-detection and mixed-format rejection semantics (don't allow a bundle to mix .json and .pb plan/manifest forms).
2. Proto plan decoding — add a Policy.init(protobufData:) (or similar) that decodes plan.pb per v1/ir/plan.proto into the existing IR Policy model, then runs the same prepareForExecution() static-analysis passes as the JSON path.
3. Proto manifest decoding — add an OPA.Manifest initializer that decodes .manifest.pb per v1/bundle/manifest.proto.
4. Schema source & codegen — decide how to generate the Swift bindings from the .proto schemas (likely swift-protobuf via protoc-gen-swift), pinning the schemas to a specific OPA release for reproducible output. Consider whether the generated code / SwiftProtobuf dependency should be isolated behind a product/target so consumers who only need JSON aren't forced to pull in protobuf.
5. Tests — round-trip fixtures built with both --format=json and --format=proto from the same policy, asserting identical evaluation results; plus a mixed-format-bundle rejection test. The ComplianceSuite could exercise both formats.

Open questions

• Should proto support be a separate target/product or folded into Rego/IR?
• Which OPA release should we pin the .proto schemas to?
• Do we need write support (emitting .pb bundles), or is read-only sufficient for this package's use cases?

References

• OPA PR adding the flag: add --format flag for proto/JSON plan bundles opa#8825
• OPA PR adding the proto schemas: Add proto schemas for the IR plan and bundle manifest opa#8775

[philipaconrad]

I appreciate the detailed writeup! Thanks for cross-linking to those references. 🙂

That said, I'm not generally a fan of protobuf as a technology-- it adds a lot of development overhead and maintenance burden for a small serdes overhead reduction in some cases at runtime.

Until this week when we bumped to Swift 6.1 (#183), this would not be a change I would have even considered for this project, because it would have broken our "minimal-to-no external dependencies" policy. However, now that we have package traits available, it may be possible to add optional (toggle-on at build time) support for protobuf formats, without gumming up the works for everyone else. 🤔

This is not a high-priority item for me right now, so if you know of people who need or want this protobuf support soon, please let me know!

[sspaink]

Thanks for taking a look. This can definitely be low-priority, I made it just for parity sake and there isn't anyone I know that is asking for this in Swift.

[philipaconrad]

Gotcha! That makes sense. Thanks for filing the issue, and I'll add this to my list of things to look into as we start using package traits more.