// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
= Groove Protocol
:toc: preamble

A _groove_ is the estate's inter-service capability-discovery and data protocol:
a bidirectional interface between two systems, each usable standalone but
enhanced when co-present. Every inter-service boundary in the estate is (or may
become) a groove.

== The cleave surface

A groove connection is specified as a layered "cleave surface":

[cols="1,3",options="header"]
|===
| Layer | Concern

| A  | Discovery — finding a co-present groove and its capabilities.
| B1 | Admissibility / compatibility — whether two grooves may connect.
| B2 | *Live-governance / lifecycle-residue* — clean, zero-residue teardown.
| C1 | Logical schema — the message model.
| C2 | Framing / transport — the wire.
|===

== Normative specs

[cols="1,3",options="header"]
|===
| Spec | Layer

| link:spec/GROOVE-RANKED-OWNERSHIP-CLEAVE-SPEC.adoc[Ranked-Ownership Cleave] | B2 — teardown discipline; `RC-1`…`RC-13` with falsifiers.
|===

A / B1 / C1 / C2 are not yet specified here.

Reference implementation: `hyperpolymath/gossamer` (Idris2 ABI proofs +
Zig FFI). See `gossamer#82` for the audit that motivated the B2 spec.
