From e9d2a83fa94a651bb53583683edb00f1e4710c64 Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Thu, 9 Jul 2026 11:41:41 +0100
Subject: [PATCH] Clarify nested plugin composition

---
 docs/eve-migration-roadmap.md              |  6 +++---
 docs/plugin-architecture.md                | 10 ++++++----
 plugins/incubating/sai-vn.plugin.json      |  4 ++++
 schemas/gamecult.eve.plugin.v1.schema.json |  8 ++++++++
 4 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/docs/eve-migration-roadmap.md b/docs/eve-migration-roadmap.md
index b92c387..6c4bf9c 100644
--- a/docs/eve-migration-roadmap.md
+++ b/docs/eve-migration-roadmap.md
@@ -657,9 +657,9 @@ Recently cut:
   conformance consumer can assert plugin ABI operations and capabilities with
   `--expect-plugin-operation` and `--expect-plugin-capability`, and the export
   now carries plugin manifest paths, advertisement paths, split targets,
-  graduation triggers, and optional plugin dependencies. Sai and Norn can prove
-  the plugin contract from the conformance export without reading Eve's parity
-  manifest.
+  graduation triggers, and optional nested composition claims. Sai and Norn can
+  prove the plugin contract from the conformance export without reading Eve's
+  parity manifest.
 - EveUnity now has a split lifecycle smoke at
   `scripts/run-eveunity-lifecycle-smoke.ps1`. It validates the existing
   `packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json`
diff --git a/docs/plugin-architecture.md b/docs/plugin-architecture.md
index 5e8b83f..ed38f1f 100644
--- a/docs/plugin-architecture.md
+++ b/docs/plugin-architecture.md
@@ -429,8 +429,8 @@ Sai plugin responsibilities:
 - define visual manifest schema as Eve-facing representation input;
 - provide slots for embedded surfaces inside VN scenes without owning the
   embedded surface semantics;
-- declare optional plugin dependencies such as Norn graph and TeX math when a
-  scene embeds those documents;
+- declare optional nested composition slots such as Norn graph and TeX math
+  when a scene embeds those documents;
 - provide fixtures for Eve parity;
 - provide a web/static-site reference implementation.
 
@@ -472,7 +472,7 @@ TeX plugin responsibilities:
 - define fallback and capability-gap behavior when a renderer cannot typeset;
 - provide inline, block, and scene-placed math fixtures for Eve parity.
 
-Sai may declare optional dependencies:
+Sai may advertise optional nested composition slots:
 
 ```json
 {
@@ -480,6 +480,7 @@ Sai may declare optional dependencies:
   "optionalPlugins": [
     {
       "pluginId": "norn.graph",
+      "relationship": "optional-nested-composition",
       "capabilities": [
         "embed.norn",
         "graph.node.activate"
@@ -487,6 +488,7 @@ Sai may declare optional dependencies:
     },
     {
       "pluginId": "tex.math",
+      "relationship": "optional-nested-composition",
       "capabilities": [
         "embed.tex",
         "tex.inline",
@@ -616,7 +618,7 @@ For Sai VN:
 - choice command fixture;
 - continue command fixture;
 - visual manifest asset fixture;
-- embedded surface slot fixture with optional Norn/TeX plugin dependencies;
+- embedded surface slot fixture with optional Norn/TeX composition slots;
 - degraded renderer fixture for clients without scene placement;
 - receipt round-trip fixture driven by a fake provider.
 - ABI fixture proving `describe`, `validate`, `project`, `lower`, `measure`,
diff --git a/plugins/incubating/sai-vn.plugin.json b/plugins/incubating/sai-vn.plugin.json
index 3868949..8fece20 100644
--- a/plugins/incubating/sai-vn.plugin.json
+++ b/plugins/incubating/sai-vn.plugin.json
@@ -76,6 +76,8 @@
     "optionalPlugins": [
       {
         "pluginId": "norn.graph",
+        "relationship": "optional-nested-composition",
+        "authority": "Sai can place an embed.norn surface when norn.graph is available; Norn remains the independent graph plugin owner and Sai must not import graph internals.",
         "capabilities": [
           "embed.norn",
           "graph.node.activate"
@@ -83,6 +85,8 @@
       },
       {
         "pluginId": "tex.math",
+        "relationship": "optional-nested-composition",
+        "authority": "Sai can place an embed.tex surface when tex.math is available; TeX remains the independent math plugin owner and Sai must not import TeX internals.",
         "capabilities": [
           "embed.tex",
           "tex.inline",
diff --git a/schemas/gamecult.eve.plugin.v1.schema.json b/schemas/gamecult.eve.plugin.v1.schema.json
index 5e56006..f9584b0 100644
--- a/schemas/gamecult.eve.plugin.v1.schema.json
+++ b/schemas/gamecult.eve.plugin.v1.schema.json
@@ -252,6 +252,14 @@
                 "type": "string",
                 "minLength": 1
               },
+              "relationship": {
+                "type": "string",
+                "minLength": 1
+              },
+              "authority": {
+                "type": "string",
+                "minLength": 1
+              },
               "capabilities": {
                 "type": "array",
                 "items": {