docs: update line of reasoning for subsequent PRs

[hbraswelrh]

Line of Reasoning for PRs

This sub-issue serves as a simple way to document the functionality introduced for the demo of complypacks being pulled using the complyctl runtime, complytime-providers, and the mock-oci-registry. The features can be demoed using the devcontainer DevPod locally, via codespaces, etc.

complyctl

PR #538 538 (complyctl) extended the mock registry with seedFromDirectory() so it can serve mounted Gemara YAML from a filesystem directory. That's the general mechanism for private/local policies. It's independent and it works today for any provider. PR #540 doesn't use seedFromDirectory() because the OPA test content is embedded, not mounted.

PR #540 (complyctl) adds the OPA test content that the mock registry serves out of the box:

• Gemara policy metadata: test-opa-catalog.yaml + test-opa-policy.yaml with executor.id: opa — seeded via seedDefaults() at policies/test-opa-policy
• Complypack artifact: Rego files + complytime-mapping.json packaged as a tar.gz — seeded via addComplypackArtifact() at complypacks/test-opa-complypack
• Workspace config: complytime.yaml has the test-opa-bp policy-id, the complypack entry, and a test-k8s-deployment target
• Test input: post-create.sh generates a sample K8s Deployment manifest in the workspace

complytime-providers

PR complytime/complytime-providers#41 (complytime-providers) is the ~30-line change that makes the OPA provider read ComplypackContentPath from GenerateRequest instead of requiring opa_bundle_ref. Without it, the provider rejects the generate request with the error you saw.

Demo

The demo flow in a Codespace:
complyctl get

• Fetches policies/test-opa-policy from the mock registry → OCI layout cache
• Fetches complypacks/test-opa-complypack from the mock registry → complypack cache at ~/.complytime/complypacks/opa/1.0.0/

complyctl generate --policy-id test-opa-bp

• Resolves the policy graph from the cached Gemara YAML — finds executor.id: opa
• Looks up the complypack cache for evaluator-id opa — finds content.tar.gz
• Calls RouteGenerate("opa", ...) with ComplypackContentPath set to the cache path
• PR 41: OPA provider's resolvePolicyDir() sees the path, skips conftest pull, reads complytime-mapping.json directly from the complypack content, matches requirement IDs to Rego namespaces, writes scan-config.json

complyctl scan --policy-id test-opa-bp

• Reads scan-config.json from Generate — has BundleDir pointing at the complypack content
• PR 41: resolveScanPolicyDir() uses scanCfg.BundleDir — no opa_bundle_ref needed
• Runs conftest test test-deployment.yaml --policy --namespace kubernetes.run_as_nonroot --namespace kubernetes.resource_limits
• Returns assessment results for the two container security requirements

[hbraswelrh]

When all three PRs are merged and the devcontainer rebuilds, the flow works end-to-end: the mock registry serves both the Gemara policy and the complypack, complyctl get fetches both into local caches, generate passes the complypack content path to the OPA provider, and scan evaluates the Rego policies against the test deployment manifest. No external registry, no opa_bundle_ref, no manual setup.

The caveat: The devcontainer's post-create.sh builds the OPA provider binary from complytime-providers main. PR 41 needs to be merged to upstream main before the devcontainer picks it up. If you spin up a Codespace after PR 540 merges but before PR 41 merges, you'll still get the old provider binary that rejects the generate request.
The merge order that makes this work:

1. PR 538 (already review-ready) — mock registry seedFromDirectory() for mounted bundles
2. PR 540 — OPA test content in mock registry + workspace config
3. PR 41 — OPA provider consumes ComplypackContentPath
   After all three are on their respective main branches, a new Codespace builds everything from main and the demo works.
   For the mounted/private bundles use case (PR 538's seedFromDirectory()): that also works with the OPA provider after PR 41, as long as the mounted directory contains catalog.yaml + policy.yaml for the Gemara metadata and a complypack is configured separately in complytime.yaml. The mock registry serves the Gemara YAML via seedFromDirectory() and the complypack via the complypacks: config entry.

[hbraswelrh]

Recap

The complytime.yaml is the single configuration point.

A user testing locally would:

1. Push their complypack to any OCI registry they have access to (or the mock registry)
2. Add a complypacks: entry in complytime.yaml pointing at that registry reference
3. Run complyctl get — fetches the complypack into the local cache
4. Run **complyctl generate** / complyctl scan — complyctl resolves the cached content path and passes it to the provider

Notes - complypack flow abstracts

The user never touches cache internals, state.json, or provider-specific variables like opa_bundle_ref. The complypack flow abstracts all of that — the config says "here's where the content lives," and complyctl handles the rest.

Devcontainer - identical workflow regardless of where the content is pulled from

For the devcontainer specifically, the mock registry is that "any OCI registry" — it serves the complypack locally on localhost:8765. The complytime.yaml already points there. So from the user's perspective, the workflow is identical whether they're pulling from GitHub Container Registry, a private Artifactory instance, or the devcontainer's mock registry. The only difference is the URL in the config.

[hbraswelrh]

Update:

1. The PRs feat: pre-populate devcontainer cache with local OCI Layout bundles #538 and feat: extend devcontainer to include OPA provider test content #540 have been merged to support the devcontainer environment.
2. The final PR #41 must be merged for a full test of the end-to-end workflow.
   3.[BREAK INTO STEPS FOR DEMO] Using the complypack bundle (rego policies that are used by the Generate RPC) -> cached in mock oci registry and can be addressable by a content path in complytime.yaml -> the user can run complyctl get to make sure all requirements are present -> run complyctl generate --policy-id $POLICY_ID to generate the bundle in preparation for scanning. The OPA Provider will make updates when the generate command detects changes to gemara policies and will create the mapping.json -> complyctl scan --policy-id $POLICY_ID to scan the environment set in the complytime.yaml file that includes the target variables that are aligned with the executor in the Gemara Layer 3 Policy executor: opa would ensure that opa-bp is run using the OPA Provider -> Results of scan can be seen in the terminal via SARIF or Markdown

Note: Once the PR #41 is merged the full flow via devpod/codespace should be ⬇️

complyctl get                              # fetches OPA complypack from mock registry
complyctl generate --policy-id test-opa-bp # provider extracts content.tar.gz, reads mapping
complyctl scan --policy-id test-opa-bp     # evaluates test-deployment.yaml against Rego policies