docs: Policy Monitor (#192)

* docs: Policy Monitor

* Update developer/wip/for-contributors/control-plane/policy-monitor.md

Co-authored-by: Paul Latzelsperger <[email protected]>

* Update developer/wip/for-contributors/control-plane/policy-monitor.md

Co-authored-by: Paul Latzelsperger <[email protected]>

* Update developer/wip/for-contributors/control-plane/policy-monitor.md

Co-authored-by: Paul Latzelsperger <[email protected]>

* Update developer/wip/for-contributors/control-plane/policy-monitor.md

Co-authored-by: Paul Latzelsperger <[email protected]>

* pr suggestions

---------

Co-authored-by: Paul Latzelsperger <[email protected]>

developer/wip/for-contributors/contributor-handbook.md

@@ -165,6 +165,10 @@ Detailed documentation about the EDC service layers can be found [here](./contro
 
 ### 2.7 Policy Monitor
 
+The policy monitor is a component that watches over on-going transfers and ensures that the policies associated with the transfer are still valid.
+
+Detailed documentation about the policy monitor can be found [here](./control-plane/policy-monitor.md)
+
 ### 2.8 Protocol extensions (DSP)
 
 ### 3. (Postgre-)SQL persistence

developer/wip/for-contributors/control-plane/entities.md

@@ -10,8 +10,10 @@
         * [2.3 Policy evaluation functions](#23-policy-evaluation-functions)
         * [2.4 Example: binding an evaluation function](#24-example-binding-an-evaluation-function)
         * [2.5 Advanced policy concepts](#25-advanced-policy-concepts)
-            * [Pre- and Post-Evaluators](#pre--and-post-evaluators)
-            * [Dynamic functions](#dynamic-functions)
+            * [2.5.1 Pre- and Post-Evaluators](#251-pre--and-post-evaluators)
+            * [2.5.2 Dynamic functions](#252-dynamic-functions)
+        * [2.6 Bundled policy functions](#26-bundled-policy-functions)
+            * [2.6.1 Contract expiration function](#261-contract-expiration-function)
     * [3. Contract definitions](#3-contract-definitions)
     * [4. Contract negotiations](#4-contract-negotiations)
     * [5. Contract agreements](#5-contract-agreements)
@@ -352,13 +354,13 @@ documentation](https://eclipse-edc.github.io/Connector/openapi/management-api/#/
 
 ### 2.5 Advanced policy concepts
 
-###### Pre- and Post-Evaluators
+#### 2.5.1 Pre- and Post-Evaluators
 
 Pre- and post-validators are functions that are executed before and after the actual policy evaluation, respectively.
 They can be used to perform preliminary evaluation of a policy or to enrich the `PolicyContext`. For example, EDC uses
 pre-validators to inject DCP scope strings using dedicated `ScopeExtractor` objects.
 
-###### Dynamic functions
+#### 2.5.2 Dynamic functions
 
 These are very similar to `AtomicConstraintFunctions`, with one significant difference: they also receive the
 left-operand as function parameter. This is useful when the function cannot be bound to a left-operand of a policy,
@@ -402,6 +404,10 @@ Let's revisit our headquarter policy from earlier and change it a little:
 This means two things. One, our policy has changed its semantics: now we require the headquarter to be in the EU, or to
 have more than 5000 employees.
 
+### 2.6 Bundled policy functions
+
+#### 2.6.1 Contract expiration function
+
 ## 3. Contract definitions
 
 Contract definitions are how [assets](#1-assets) and [policies](#2-policies) are linked together. It is EDC's way of

developer/wip/for-contributors/control-plane/policy-monitor.md

@@ -0,0 +1,20 @@
+# The Policy Monitor
+
+Some transfer types, once accepted by the `provider`, never reach the `COMPLETED` state. Streaming and HTTP transfers in consumer pull scenario are examples of this. In those scenarios the transfer will remain active (`STARTED`) until it gets terminated either manually by using the transfer processes [management API](./entities.md#7-transfer-processes), or automatically by the policy monitor, if it has been configured in the EDC runtime.
+
+The policy monitor (`PolicyMonitorManager`) is a component that watches over on-going transfers on the provider side and ensures that the associated policies are still valid. The default implementation of the policy monitor tracks the monitored transfer processes in it's own entity `PolicyMonitorEntry` stored in the `PolicyMonitorStore`.
+
+Once a transfer process transition to the `STARTED` state on the provider side, the policy monitor gets notified through the [eventing system](./service-layers.md#6-events-and-callbacks) of EDC and start tracking transfer process. For each monitored transfer process in the `STARTED` state the policy monitor retrieves the policy associated (through [contract agreement](./entities.md#5-contract-agreements)) and runs the [Policy Engine](./entities.md#22-policy-scopes-and-bindings) using the `policy.monitor` as scope. 
+If the policy is no longer valid, the policy monitor marks the transfer process for termination (`TERMINATING`) and stops tracking it.
+
+The data plane also gets notified through the [data plane signaling](../contributor-handbook.md#210-data-plane-signaling) protocol about the termination of the transfer process, and if accepted by the data plane, the data transfer terminates as well.
+
+## Note for implementors
+
+Implementors that want a [Policy function](./entities.md#23-policy-evaluation-functions) to be evaluated at the policy monitor layer need to bind such function to the `policy.monitor` scope.
+
+Note that because the policy evaluation happens in the background, the `PolicyContext` does not contain `ParticipantAgent` as context data. This means that the Policy Monitor cannot evaluate policies that involve VerifiableCredentials.
+
+Currently the only information published in the `PolicyContext` available for functions in the `policy.monitor` scope are the [`ContractAgreement`](./entities.md#5-contract-agreements), and the `Instant` at the time of the evaluation.
+
+A bundled example of a [Policy function](./entities.md#23-policy-evaluation-functions) that runs in the `policy.monitor` scope is the `ContractExpiryCheckFunction` which checks if the [contract agreement](./entities.md#5-contract-agreements) is not expired.