start sketching out ideas for 1362

This is a partial and incomplete design which, when completed, might
close #1362. Putting this up and switching focus because that issue
has been deprioritized.

roadmap/implementers-guide/src/SUMMARY.md

@@ -11,6 +11,7 @@
   - [Initializer Module](runtime/initializer.md)
   - [Configuration Module](runtime/configuration.md)
   - [Disputes Module](runtime/disputes.md)
+  - [DisputeInherent Module](runtime/disputeinherent.md)
   - [Paras Module](runtime/paras.md)
   - [Scheduler Module](runtime/scheduler.md)
   - [Inclusion Module](runtime/inclusion.md)
@@ -29,6 +30,7 @@
   - [Validation Code](runtime-api/validation-code.md)
   - [Candidate Pending Availability](runtime-api/candidate-pending-availability.md)
   - [Candidate Events](runtime-api/candidate-events.md)
+  - [Misbehavior Reporting](runtime-api/misbehavior-reporting.md)
 - [Node Architecture](node/README.md)
   - [Subsystems and Jobs](node/subsystems-and-jobs.md)
   - [Overseer](node/overseer.md)

roadmap/implementers-guide/src/runtime-api/misbehavior-reporting.md

@@ -0,0 +1,46 @@
+# Misbehavior Reporting
+
+This API is the boundary layer between the runtime modules, which understand only the current block
+in a fork-free model of the blockchain, and the node subsystems, which handle forking and finality.
+As such, there are two types of misbehavior which we are concerned with: local and remote.
+
+## Local Disputes
+
+Local disputes are detected by the runtime and communicated to the node by an as-yet-unspecified
+mechanism.
+
+> TODO: figure out that mechanism.
+>
+> A pull mechanism which lets the node request new disputes from the runtime is most similar to
+> existing runtime APIs; it might look like:
+>
+> ```rust
+> fn get_new_disputes(at: Block) -> Vec<Dispute>
+> ```
+>
+> However, that design feels suboptimal. There is probably a push design possible which would allow
+> the runtime to directly notify the node when it discovers cause for a dispute, but it's not obvious
+> as of now what such a design would look like.
+
+Local disputes are forwarded as [`ProvisionerMessage`](../types/overseer-protocol.md#provisioner-message)`::Dispute`.
+
+## Remote Disputes
+
+When a dispute has occurred on another fork, we need to transplant that dispute to every other fork.
+This preserves the property that a misbehaving validator is slashed in every possible future; it can't
+escape punishment just because its misbehavior was detected and prevented before taking effect.
+
+### Concluded Remote Dispute
+
+A concluded remote dispute has had the dispute process run to completion: it simply rolls up
+all [attestations](../types/backing.md#signed-statement-type) for and against the block.
+It can be resolved in a single transaction; it is an open-and-shut case of a quorum of validators
+disagreeing with each other.
+
+```rust
+struct ConcludedRemoteDispute {
+    attestations: Vec<SignedStatement>,
+}
+
+fn concluded_remote_distpute(dispute: ConcludedRemoteDispute)
+```

roadmap/implementers-guide/src/runtime/disputeinherent.md

@@ -0,0 +1,22 @@
+# DisputeInherent Module
+
+This module propagates remote dispute data into the runtime. This entrypoint is mandatory, in that
+it must be invoked exactly once within every block, and it is also inherent in that it is provided
+with no origin by the block author. The data wihtin it carries its own authentication. If any of
+the steps within fails, the entrypoint is considered to have failed and the block will be invalid.
+
+## Storage
+
+```rust
+Included: Option<()>,
+```
+
+## Finalization
+
+1. Take (get and clear) the value of `Included`. Ensure that it is `None` or throw an unrecoverable error.
+
+## Entry Points
+
+- `disputes`.
+
+  > TODO: design how the disputes inherent is used to propagate unconcluded remote disputes