From bb8e2652ad9d54b25f798de0cd95359583db381e Mon Sep 17 00:00:00 2001
From: Sohan Maheshwar <1119120+sohanmaheshwar@users.noreply.github.com>
Date: Wed, 17 Jun 2026 15:11:41 +0200
Subject: [PATCH 1/2] feat: add ai-agents example schema

Adds an example showing an AI agent inheriting view access to documents
on behalf of a user via an arrow on a `delegates` permission.
---
 schemas/ai-agents/README.md            |  3 ++
 schemas/ai-agents/schema-and-data.yaml | 72 ++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 schemas/ai-agents/README.md
 create mode 100644 schemas/ai-agents/schema-and-data.yaml

diff --git a/schemas/ai-agents/README.md b/schemas/ai-agents/README.md
new file mode 100644
index 0000000..9a7702f
--- /dev/null
+++ b/schemas/ai-agents/README.md
@@ -0,0 +1,3 @@
+# AI Agents acting on behalf of a user
+
+An AI agent inherits view access to the documents a user can read or write, but cannot edit them on its own.
diff --git a/schemas/ai-agents/schema-and-data.yaml b/schemas/ai-agents/schema-and-data.yaml
new file mode 100644
index 0000000..1e76f84
--- /dev/null
+++ b/schemas/ai-agents/schema-and-data.yaml
@@ -0,0 +1,72 @@
+---
+schema: |-
+  /**
+   * an entity that can be granted permissions
+   */
+  definition user {
+      /**
+       * users can have one or more AI agents that act on their behalf
+       */
+      relation agent: ai_agent
+
+      /**
+       * the set of AI agents that may act on this user's behalf
+       */
+      permission delegates = agent
+  }
+
+  /**
+   * an AI agent that can act on behalf of a user
+   */
+  definition ai_agent {}
+
+  /**
+   * a resource that we are trying to protect
+   */
+  definition document {
+      /**
+       * users can be made writers of specific documents
+       */
+      relation writer: user
+
+      /**
+       * users can be made readers of specific documents
+       */
+      relation reader: user
+
+      /**
+       * if a user has the writer relationship to a specific document, they automatically get permission to edit it
+       */
+      permission edit = writer
+
+      /**
+       * a user can view a document if they are a reader (or can edit it).
+       * an AI agent can view a document if it acts on behalf of a reader or a writer of that document.
+       */
+      permission view = reader + edit + reader->delegates + writer->delegates
+  }
+
+relationships: |-
+  document:firstdoc#writer@user:tom
+  document:firstdoc#reader@user:fred
+  user:tom#agent@ai_agent:assistant_tom
+  user:fred#agent@ai_agent:assistant_fred
+
+assertions:
+  assertTrue:
+    - "document:firstdoc#edit@user:tom"
+    - "document:firstdoc#view@user:tom"
+    - "document:firstdoc#view@user:fred"
+    - "document:firstdoc#view@ai_agent:assistant_tom"
+    - "document:firstdoc#view@ai_agent:assistant_fred"
+  assertFalse:
+    - "document:firstdoc#edit@user:fred"
+    - "document:firstdoc#edit@ai_agent:assistant_tom"
+    - "document:firstdoc#edit@ai_agent:assistant_fred"
+
+validation:
+  document:firstdoc#view:
+    - "[user:tom] is <document:firstdoc#writer>"
+    - "[user:fred] is <document:firstdoc#reader>"
+    - "[ai_agent:assistant_tom] is <document:firstdoc#writer>/<user:tom#agent>"
+    - "[ai_agent:assistant_fred] is <document:firstdoc#reader>/<user:fred#agent>"

From 72e72659c2f3150494b5aefb2d025f646176f945 Mon Sep 17 00:00:00 2001
From: Sohan Maheshwar <1119120+sohanmaheshwar@users.noreply.github.com>
Date: Wed, 17 Jun 2026 15:30:11 +0200
Subject: [PATCH 2/2] fix: correct validation chain for ai-agents example

---
 schemas/ai-agents/schema-and-data.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/schemas/ai-agents/schema-and-data.yaml b/schemas/ai-agents/schema-and-data.yaml
index 1e76f84..e552b95 100644
--- a/schemas/ai-agents/schema-and-data.yaml
+++ b/schemas/ai-agents/schema-and-data.yaml
@@ -68,5 +68,5 @@ validation:
   document:firstdoc#view:
     - "[user:tom] is <document:firstdoc#writer>"
     - "[user:fred] is <document:firstdoc#reader>"
-    - "[ai_agent:assistant_tom] is <document:firstdoc#writer>/<user:tom#agent>"
-    - "[ai_agent:assistant_fred] is <document:firstdoc#reader>/<user:fred#agent>"
+    - "[ai_agent:assistant_tom] is <user:tom#agent>"
+    - "[ai_agent:assistant_fred] is <user:fred#agent>"