From 2f42e545d6fabb8bf23eb531c6b1176d9a60cd6d Mon Sep 17 00:00:00 2001
From: Letro Bot <noreply@letro.com>
Date: Thu, 9 Apr 2026 16:19:17 -0500
Subject: [PATCH] Add some docs for debugging policies

---
 crates/policy/src/lib.rs         |  6 ++++++
 docs/development/contributing.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/crates/policy/src/lib.rs b/crates/policy/src/lib.rs
index a5d4805ad..193bacdb2 100644
--- a/crates/policy/src/lib.rs
+++ b/crates/policy/src/lib.rs
@@ -89,6 +89,7 @@ impl Entrypoints {
     }
 }
 
+/// Global static data that stays the same for the life of the [`PolicyFactory`]
 #[derive(Debug)]
 pub struct Data {
     base: BaseData,
@@ -198,6 +199,10 @@ fn merge_data_rec(
     Ok(())
 }
 
+/// Global dynamic data
+///
+/// Hint: there is an admin API to manage this, see
+/// `crates/handlers/src/admin/v1/policy_data/set.rs`
 struct DynamicData {
     version: Option<Ulid>,
     merged: serde_json::Value,
@@ -319,6 +324,7 @@ impl PolicyFactory {
         &self,
         data: &serde_json::Value,
     ) -> Result<Policy, InstantiateError> {
+        tracing::debug!("Instantiating policy with data={}", data);
         let mut store = Store::new(&self.engine, ());
         let runtime = Runtime::new(&mut store, &self.module)
             .await
diff --git a/docs/development/contributing.md b/docs/development/contributing.md
index 206602784..721aa948a 100644
--- a/docs/development/contributing.md
+++ b/docs/development/contributing.md
@@ -108,6 +108,34 @@ If you haven't already, install [Cargo-Nextest](https://nexte.st/docs/installati
   - `make PODMAN=1 test` (runs inside a container; needs Podman installed)
   - `make DOCKER=1 test` (runs inside a container; needs Docker installed)
 
+### Debug policies
+
+When in doubt, rebuild the policies (see the *Build and run MAS* section above). It's
+really easy to make a change to the policies and forget to rebuild them, which can lead
+to maddening debugging sessions.
+
+The policies get a combination of `data` and `input` when they're evaluated.
+
+ - `data`: App-global data. This is a combination of many things:
+    - Static fields defined in `mas_policy::Data`
+    - `mas_policy::DynamicData` is mixed in and is managed with the admin API.
+    - Arbitrary data can be added via configuration (`policy.data`) ([docs](../reference/configuration.md#policy))
+ - `input`: Information passed during evaluation that is derived from each request.
+    - Each policy has its own input schema defined by the types like `CompatLoginInput`, etc.
+
+To debug what the policy template sees, you can add a
+[`print(...)`](https://www.openpolicyagent.org/docs/cheatsheet#print) statement in the
+policy, which will print to the [server
+logs](https://github.com/matrix-org/rust-opa-wasm/blob/17cdd1570448da02f9d37bbe4e89ffad2ffc5e3f/src/policy.rs#L276)
+(FIXME: this currently doesn't work).
+
+Since the way `data` is assembled is a bit complex, you can use
+`RUST_LOG=info,mas_policy=debug` which will show the `tracing::debug!("Instantiating
+policy with data={}", data);` debug logs.
+
+For `input`, you can just log it more directly where you evaluate the policy.
+
+
 ## 8. Submit a pull request
 
 Once you've made changes, you're ready to submit a pull request.