# ==================================================================================================================== #
#              _____ ____    _        _      ____                       _                                              #
#  _ __  _   _| ____|  _ \  / \      / \    |  _ \ ___ _ __   ___  _ __| |_ ___                                        #
# | '_ \| | | |  _| | | | |/ _ \    / _ \   | |_) / _ \ '_ \ / _ \| '__| __/ __|                                       #
# | |_) | |_| | |___| |_| / ___ \  / ___ \ _|  _ <  __/ |_) | (_) | |  | |_\__ \                                       #
# | .__/ \__, |_____|____/_/   \_\/_/   \_(_)_| \_\___| .__/ \___/|_|   \__|___/                                       #
# |_|    |___/                                        |_|                                                              #
# ==================================================================================================================== #
# Authors:                                                                                                             #
#   Patrick Lehmann                                                                                                    #
#                                                                                                                      #
# License:                                                                                                             #
# ==================================================================================================================== #
# Copyright 2026-2026 Electronic Design Automation Abstraction (EDA²)                                                  #
#                                                                                                                      #
# Licensed under the Apache License, Version 2.0 (the "License");                                                      #
# you may not use this file except in compliance with the License.                                                     #
# You may obtain a copy of the License at                                                                              #
#                                                                                                                      #
#   http://www.apache.org/licenses/LICENSE-2.0                                                                         #
#                                                                                                                      #
# Unless required by applicable law or agreed to in writing, software                                                  #
# distributed under the License is distributed on an "AS IS" BASIS,                                                    #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.                                             #
# See the License for the specific language governing permissions and                                                  #
# limitations under the License.                                                                                       #
#                                                                                                                      #
# SPDX-License-Identifier: Apache-2.0                                                                                  #
# ==================================================================================================================== #
#
"""
Abstract data model of requirements management.

A :class:`RequirementSpecification` is the root: it registers the persons, personas, labels, documents and layers its
items refer to, and every requirement and specification item by its ID.

A :class:`Requirement` has a title, a description, a creation time, a state, a kind and an obligation. It names its
authors and owners (:class:`~pyEDAA.Reports.Person`), the personas it is about (:class:`Persona`), its labels
(:class:`Label`), the documents attached to it (:class:`Document`), and the layer it belongs to (:class:`Layer`) - all
registered in the same specification. A requirement contains child requirements, which refine it.

A :class:`SpecificationItem` mirrors a requirement: it states how the system meets requirements. Specification items and
requirements are in an N:M relation.

An item's :class:`Link` states a relationship to another item, e.g. to its counterpart in another layer. An item's
history lists the events of its life cycle (:class:`HistoryEvent`), e.g. a split into other requirements.
"""
from __future__            import annotations

from datetime              import datetime
from enum                  import Enum, Flag
from typing                import Any, Callable, ClassVar, Generator, Hashable, Iterable, Mapping
from typing                import Optional as Nullable, Self

from pyTooling.Common      import getFullyQualifiedName, getTypeName
from pyTooling.DataModel   import KeyValuePairsMixin
from pyTooling.Decorators  import export, readonly
from pyTooling.Exceptions  import AlreadyInHierarchyError, DuplicateElementError, NotInSameHierarchyError
from pyTooling.MetaClasses import ExtendedType
from pyTooling.Versioning  import SemanticVersion

from pyEDAA.Reports        import Person, ReportException


@export
class RequirementsError(ReportException):
	"""Base-exception of the requirements model."""


@export
class NotInSameSpecificationError(RequirementsError, NotInSameHierarchyError):
	"""
	The exception is raised when an element is used together with an element or a person of another specification.

	The element or person itself is valid, only its ownership is wrong: add it to the specification first. E.g. a link
	from a requirement to a requirement of another specification.
	"""


@export
class AlreadyInSpecificationError(RequirementsError, AlreadyInHierarchyError):
	"""The exception is raised when an element is added to a specification or an item, but it already has a parent."""


@export
class DuplicatePersonaError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a persona of the same ID."""


@export
class DuplicateLabelError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a label of the same ID."""


@export
class DuplicateDocumentError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a document of the same ID."""


@export
class DuplicateLayerError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification already contains a layer of the same ID."""


@export
class DuplicatePersonError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a person of the same user ID."""


@export
class DuplicateRequirementError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a requirement of the same ID."""


@export
class DuplicateSpecificationItemError(RequirementsError, DuplicateElementError):
	"""The exception is raised when a specification or an item already contains a specification item of the same ID."""


@export
class DuplicateLinkError(RequirementsError, DuplicateElementError):
	"""The exception is raised when an item already has a link of the same kind to the same destination."""


@export
class ItemState(Enum):
	"""
	The state of an item in its life cycle.

	An item is open from :attr:`Placeholder` over :attr:`Draft`, :attr:`InReview`, :attr:`Final` and :attr:`Implemented`
	to :attr:`Verified`. It ends :attr:`Closed` after its verification, or :attr:`Rejected` or :attr:`Obsolete` at any
	time.
	"""

	Placeholder = 1  #: Reserved, e.g. an ID and a title, but not yet written.
	Draft =       2  #: Written, but not yet reviewed.
	InReview =    3  #: Under review by its stakeholders.
	Final =       4  #: Reviewed and agreed by its stakeholders; it binds the design.
	Implemented = 5  #: Implemented, but not yet verified.
	Verified =    6  #: Implemented and verified; open for a regression.
	Closed =      7  #: Verified and released, e.g. in a baseline; it changes no more.
	Rejected =    8  #: Not accepted by its stakeholders.
	Obsolete =    9  #: No longer valid, e.g. replaced by another one, split or merged.


@export
class RequirementKind(Enum):
	"""
	The kind of a requirement: what it constrains.

	The kinds follow the requirement types of ISO/IEC/IEEE 29148, with safety and security as kinds of their own, as
	functional safety and security standards treat them separately.
	"""

	Functional =    1   #: A function the system performs, e.g. a register map or a protocol's behavior.
	Performance =   2   #: How well a function is performed, e.g. a clock frequency, latency or throughput.
	Quality =       3   #: A quality attribute, e.g. reliability, maintainability or usability.
	Safety =        4   #: A measure against hazards, e.g. a safety mechanism of ISO 26262 or IEC 61508.
	Security =      5   #: A measure against threats, e.g. encrypted bitstreams or secure boot.
	Interface =     6   #: An interface to another system, e.g. a pin-out, a bus or a signal level.
	Environmental = 7   #: An operating condition, e.g. a temperature range, vibration or EMC.
	Constraint =    8   #: A design or implementation constraint, e.g. an FPGA family or a language.
	Regulatory =    9   #: A standard, law or certification the system complies with.
	Other =         10  #: Any other requirement.


@export
class Obligation(Enum):
	"""
	The obligation of a requirement: whether it must, should or may be met.

	The levels are those of the keywords of ISO/IEC/IEEE 29148 (*shall*, *should*, *may*) and of RFC 2119 (*MUST*,
	*SHOULD*, *MAY*). A negated requirement (*shall not*) has the obligation of its positive keyword; the negation is part
	of its text.
	"""

	Mandatory =   1  #: Binding: the requirement must be met (*shall*, *must*).
	Recommended = 2  #: A goal: the requirement should be met, deviations are justified (*should*).
	Optional =    3  #: A permission: the requirement may be met (*may*).


# A class with a property named like a class - ``Obligation`` - can't name that class in the annotation of a field: the
# class body's namespace, where annotations are evaluated, binds the name to the property.
_Obligation = Obligation


@export
class VerificationMethod(Flag):
	"""
	The methods verifying a requirement, as flags.

	The methods follow the verification methods of ISO/IEC/IEEE 29148 - inspection, analysis, demonstration and test -,
	with simulation and formal verification as methods of their own, as hardware designs are verified by them.
	"""

	Unknown =       0   #: Not decided yet.
	Inspection =    1   #: Examining the item, e.g. reviewing a schematic or source code.
	Analysis =      2   #: Calculating or modeling, e.g. a timing analysis or a power budget.
	Demonstration = 4   #: Operating the system without measurements, e.g. showing a feature works.
	Test =          8   #: Operating the system with measurements under defined conditions, e.g. on a test bench.
	Simulation =    16  #: Simulating a model of the design, e.g. a VHDL testbench.
	Formal =        32  #: Proving properties of the design, e.g. by formal property checking.


@export
class Base(KeyValuePairsMixin, metaclass=ExtendedType, slots=True):
	"""
	Base-class of every element of the requirements model: key-value pairs, a reference to the element containing it, and
	a reference to the specification it is part of.
	"""

	_PARENT_TYPE: ClassVar[tuple[type, ...]]          #: The types a parent may have; set by each class with a parent.

	_parent:      Nullable[Base]                      #: The element containing this one, or ``None``.
	_root:        Nullable[RequirementSpecification]  #: The specification, or ``None`` while the element isn't in one.

	def __init__(self, *, keyValuePairs: Nullable[Mapping[Hashable, Any]] = None, parent: Nullable[Base] = None) -> None:
		"""
		Initializes an element with its key-value pairs, its parent, and the parent's specification.

		The parent doesn't list the element yet: the class setting the field the parent stores it by - an ID - adds it with
		``parent._AddElement(self)``.

		:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
		:param parent:        Optional, the element containing this one. Default: ``None``.
		:raises TypeError:    If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:    If parameter ``parent`` isn't of a type this class declares in :attr:`_PARENT_TYPE`.
		"""
		super().__init__(keyValuePairs)

		if parent is None:
			self._parent = None
			self._root =   None
		elif not isinstance(parent, self._PARENT_TYPE):
			typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
			ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
			ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
			raise ex
		else:
			self._parent = parent
			self._root =   parent._root

	@property
	def Parent(self) -> Nullable[Base]:
		"""
		Property to access the element containing this one (:attr:`_parent`).

		Assigning a parent to an element without one adds the element to it, and sets the parent's specification as the
		specification of this element and of every element below it.

		:returns:                                The parent, or ``None``.
		:raises ValueError:                      If ``None`` is assigned.
		:raises TypeError:                       If the assigned parent isn't of a type this class declares in
		                                         :attr:`_PARENT_TYPE`.
		:raises TypeError:                       If a parent is assigned to a :class:`RequirementSpecification`, which has
		                                         no
		                                         parent.
		:raises AlreadyInSpecificationError:     If the element already has a parent.
		:raises DuplicatePersonaError:           If the element is a persona, and the specification already contains a
		                                         persona of its ID.
		:raises DuplicateLabelError:             If the element is a label, and the specification already contains a label
		                                         of its ID.
		:raises DuplicateDocumentError:          If the element is a document, and the specification already contains a
		                                         document of its ID.
		:raises DuplicateLayerError:             If the element is a layer, and the specification already contains a layer
		                                         of its ID.
		:raises DuplicateRequirementError:       If the specification already contains a requirement of an ID of this
		                                         requirement or of a requirement below it.
		:raises DuplicateSpecificationItemError: If the specification already contains a specification item of an ID of this
		                                         item or of an item below it.
		"""
		return self._parent

	@Parent.setter
	def Parent(self, parent: Base) -> None:
		if parent is None:
			raise ValueError("Parameter 'parent' is None.")
		elif not isinstance(parent, self._PARENT_TYPE):
			typeNames = " or ".join(f"'{parentType.__name__}'" for parentType in self._PARENT_TYPE)
			ex = TypeError(f"Parameter 'parent' is not of type {typeNames}.")
			ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
			raise ex

		if self._parent is not None:
			raise AlreadyInSpecificationError(f"{getTypeName(self)} already has a parent.")

		parent._AddElement(self)
		self._parent = parent
		self._root =   parent._root

	@readonly
	def Root(self) -> Nullable[RequirementSpecification]:
		"""
		Read-only property to access the specification this element is part of (:attr:`_root`).

		The specification is maintained by :attr:`Parent`: assigning a parent sets it for this element and every element
		below it.

		:returns: The specification, or ``None`` while the element isn't part of one.
		"""
		return self._root


@export
class BaseWithID(Base):
	"""
	Base-class of the elements of the requirements model, which have an ID and a description.

	The ID is unique among the elements of the same class in a specification.
	"""

	_DUPLICATE_ERROR: ClassVar[type[RequirementsError]]  #: The error a second element of an ID raises; set by each class.

	_id:          str  #: The element's ID.
	_description: str  #: The element's description, or ``""``.

	def __init__(
		self,
		identifier: str,
		*,
		description: str = "",
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[Base] = None
	) -> None:
		"""
		Initializes an element with its ID, its description, its key-value pairs and its parent.

		:param identifier:    The element's ID.
		:param description:   Optional, the element's description. Default: ``""``.
		:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
		:param parent:        Optional, the element containing this one. Default: ``None``.
		:raises TypeError:    If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:    If parameter ``parent`` isn't of a type this class declares in :attr:`_PARENT_TYPE`.
		:raises ValueError:   If parameter ``identifier`` is ``None``.
		:raises TypeError:    If parameter ``identifier`` isn't of type :class:`str`.
		:raises ValueError:   If parameter ``identifier`` is empty.
		:raises ValueError:   If parameter ``description`` is ``None``.
		:raises TypeError:    If parameter ``description`` isn't of type :class:`str`.
		"""
		super().__init__(keyValuePairs=keyValuePairs, parent=parent)

		if identifier is None:
			raise ValueError("Parameter 'identifier' is None.")
		elif not isinstance(identifier, str):
			ex = TypeError("Parameter 'identifier' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(identifier)}'.")
			raise ex
		elif identifier == "":
			raise ValueError("Parameter 'identifier' is empty.")

		if description is None:
			raise ValueError("Parameter 'description' is None.")
		elif not isinstance(description, str):
			ex = TypeError("Parameter 'description' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(description)}'.")
			raise ex

		self._id =          identifier
		self._description = description

	@readonly
	def ID(self) -> str:
		"""
		Read-only property to access the element's ID (:attr:`_id`).

		:returns: The ID.
		"""
		return self._id

	@readonly
	def Description(self) -> str:
		"""
		Read-only property to access the element's description (:attr:`_description`).

		:returns: The description, or ``""``.
		"""
		return self._description


@export
class RequirementSpecification(Base):
	"""
	The root of the requirements model: the requirements and specification items of a system, and the personas, labels,
	documents and layers they refer to.

	It registers every requirement and every specification item by its ID - also a child item -, and is its own
	specification.

	Persons have no parent: the specification registers the persons its items refer to by their user IDs, and a person may
	be registered in several specifications.
	"""

	_name:               Nullable[str]                 #: The specification's name, or ``None``.
	_version:            SemanticVersion               #: The version of the specification.
	_persons:            dict[str, Person]             #: The persons, by user ID.
	_personas:           dict[str, Persona]            #: The personas, by ID.
	_labels:             dict[str, Label]              #: The labels, by ID.
	_documents:          dict[str, Document]           #: The documents, by ID.
	_layers:             dict[str, Layer]              #: The layers, by ID.
	_requirements:       dict[str, Requirement]        #: Every requirement, by ID, in the order they were added.
	_specificationItems: dict[str, SpecificationItem]  #: Every specification item, by ID, in the order they were added.

	def __init__(
		self,
		version: SemanticVersion,
		name: Nullable[str] = None,
		*,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
	) -> None:
		"""
		Initializes an empty requirement specification.

		:param version:       The version of the specification.
		:param name:          Optional, the specification's name. Default: ``None``.
		:param keyValuePairs: Optional, the key-value pairs. Default: ``None``.
		:raises TypeError:    If parameter ``keyValuePairs`` isn't a mapping.
		:raises ValueError:   If parameter ``version`` is ``None``.
		:raises TypeError:    If parameter ``version`` isn't of type :class:`~pyTooling.Versioning.SemanticVersion`.
		:raises TypeError:    If parameter ``name`` isn't of type :class:`str`.
		:raises ValueError:   If parameter ``name`` is empty.
		"""
		super().__init__(keyValuePairs=keyValuePairs)

		if version is None:
			raise ValueError("Parameter 'version' is None.")
		elif not isinstance(version, SemanticVersion):
			ex = TypeError("Parameter 'version' is not of type 'SemanticVersion'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(version)}'.")
			raise ex

		if name is not None:
			if not isinstance(name, str):
				ex = TypeError("Parameter 'name' is not of type 'str'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
				raise ex
			elif name == "":
				raise ValueError("Parameter 'name' is empty.")

		self._root =               self
		self._name =               name
		self._version =            version
		self._persons =            {}
		self._personas =           {}
		self._labels =             {}
		self._documents =          {}
		self._layers =             {}
		self._requirements =       {}
		self._specificationItems = {}

	@Base.Parent.setter
	def Parent(self, parent: None) -> None:
		ex = TypeError(f"A '{getFullyQualifiedName(self)}' has no parent.")
		ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
		raise ex

	def _AddElement(self, element: BaseWithID) -> None:
		"""
		Register a persona, label, document, layer, top-level requirement or top-level specification item, which names the
		specification as its parent.

		:param element:                          The element.
		:raises DuplicatePersonaError:           If the specification already contains a persona of the element's ID.
		:raises DuplicateLabelError:             If the specification already contains a label of the element's ID.
		:raises DuplicateDocumentError:          If the specification already contains a document of the element's ID.
		:raises DuplicateLayerError:             If the specification already contains a layer of the element's ID.
		:raises DuplicateRequirementError:       If the specification already contains a requirement of the ID of the
		                                         requirement or of a requirement below it.
		:raises DuplicateSpecificationItemError: If the specification already contains a specification item of the ID of the
		                                         item or of an item below it.
		"""
		if isinstance(element, BaseItem):
			self._AddItems(element)
			return

		if isinstance(element, Persona):
			elements = self._personas
		elif isinstance(element, Label):
			elements = self._labels
		elif isinstance(element, Document):
			elements = self._documents
		else:
			elements = self._layers

		if element._id in elements:
			raise element._DUPLICATE_ERROR(
				f"{getTypeName(element)} '{element._id}' already exists in the specification."
			)

		elements[element._id] = element

	def _AddItems(self, item: BaseItem) -> None:
		"""
		Register an item and every item below it by their IDs, and set the specification as their specification and the
		specification of their history events.

		Either all of them are registered, or none.

		:param item:                             The item joining the specification.
		:raises DuplicateRequirementError:       If the item is a requirement, and an ID of these requirements is registered
		                                         already, or used twice by them.
		:raises DuplicateSpecificationItemError: If the item is a specification item, and an ID of these items is registered
		                                         already, or used twice by them.
		"""
		items =   self._requirements if isinstance(item, Requirement) else self._specificationItems
		ids =     set()
		subtree = (item, *item.IterateDescendants())
		for element in subtree:
			if element._id in items or element._id in ids:
				raise element._DUPLICATE_ERROR(
					f"{getTypeName(element)} '{element._id}' already exists in the specification."
				)

			ids.add(element._id)

		for element in subtree:
			element._root =     self
			items[element._id] = element
			for event in element._history:
				event._root = self

	@readonly
	def Name(self) -> Nullable[str]:
		"""
		Read-only property to access the specification's name (:attr:`_name`).

		:returns: The name, or ``None``.
		"""
		return self._name

	@readonly
	def Version(self) -> SemanticVersion:
		"""
		Read-only property to access the version of the specification (:attr:`_version`).

		:returns: The version.
		"""
		return self._version

	@readonly
	def Persons(self) -> dict[str, Person]:
		"""
		Read-only property to access the persons (:attr:`_persons`).

		:returns: The persons, by user ID.
		"""
		return self._persons

	def IteratePersons(self, predicate: Nullable[Callable[[Person], bool]] = None) -> Generator[Person, None, None]:
		"""
		Iterate all or selected persons.

		If parameter ``predicate`` is not None, the given filter function is used to skip persons in the generator.

		:param predicate: Optional, filter function accepting a person and returning a boolean. Default: ``None``.
		:returns:         A generator of the persons, in the order they were added.
		"""
		if predicate is None:
			yield from self._persons.values()
		else:
			for person in self._persons.values():
				if predicate(person):
					yield person

	def AddPerson(self, person: Person) -> None:
		"""
		Register a person, whom the specification's items can refer to.

		E.g. an author or an owner of requirements. A person has no parent: the same person may be registered in several
		specifications.

		:param person:                The person.
		:raises ValueError:           If parameter ``person`` is ``None``.
		:raises TypeError:            If parameter ``person`` isn't of type :class:`~pyEDAA.Reports.Person`.
		:raises DuplicatePersonError: If the specification already contains a person of this user ID.
		"""
		if person is None:
			raise ValueError("Parameter 'person' is None.")
		elif not isinstance(person, Person):
			ex = TypeError("Parameter 'person' is not of type 'Person'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(person)}'.")
			raise ex
		elif person._userID in self._persons:
			raise DuplicatePersonError(f"Person '{person._userID}' already exists in the specification.")

		self._persons[person._userID] = person

	@readonly
	def Personas(self) -> dict[str, Persona]:
		"""
		Read-only property to access the personas (:attr:`_personas`).

		:returns: The personas, by ID.
		"""
		return self._personas

	def IteratePersonas(self, predicate: Nullable[Callable[[Persona], bool]] = None) -> Generator[Persona, None, None]:
		"""
		Iterate all or selected personas.

		If parameter ``predicate`` is not None, the given filter function is used to skip personas in the generator.

		:param predicate: Optional, filter function accepting a persona and returning a boolean. Default: ``None``.
		:returns:         A generator of the personas, in the order they were added.
		"""
		if predicate is None:
			yield from self._personas.values()
		else:
			for persona in self._personas.values():
				if predicate(persona):
					yield persona

	@readonly
	def Labels(self) -> dict[str, Label]:
		"""
		Read-only property to access the labels (:attr:`_labels`).

		:returns: The labels, by ID.
		"""
		return self._labels

	def IterateLabels(self, predicate: Nullable[Callable[[Label], bool]] = None) -> Generator[Label, None, None]:
		"""
		Iterate all or selected labels.

		If parameter ``predicate`` is not None, the given filter function is used to skip labels in the generator.

		:param predicate: Optional, filter function accepting a label and returning a boolean. Default: ``None``.
		:returns:         A generator of the labels, in the order they were added.
		"""
		if predicate is None:
			yield from self._labels.values()
		else:
			for label in self._labels.values():
				if predicate(label):
					yield label

	@readonly
	def Documents(self) -> dict[str, Document]:
		"""
		Read-only property to access the documents (:attr:`_documents`).

		:returns: The documents, by ID.
		"""
		return self._documents

	def IterateDocuments(self, predicate: Nullable[Callable[[Document], bool]] = None) -> Generator[Document, None, None]:
		"""
		Iterate all or selected documents.

		If parameter ``predicate`` is not None, the given filter function is used to skip documents in the generator.

		:param predicate: Optional, filter function accepting a document and returning a boolean. Default: ``None``.
		:returns:         A generator of the documents, in the order they were added.
		"""
		if predicate is None:
			yield from self._documents.values()
		else:
			for document in self._documents.values():
				if predicate(document):
					yield document

	@readonly
	def Layers(self) -> dict[str, Layer]:
		"""
		Read-only property to access the layers (:attr:`_layers`).

		:returns: The layers, by ID.
		"""
		return self._layers

	def IterateLayers(self, predicate: Nullable[Callable[[Layer], bool]] = None) -> Generator[Layer, None, None]:
		"""
		Iterate all or selected layers.

		If parameter ``predicate`` is not None, the given filter function is used to skip layers in the generator.

		:param predicate: Optional, filter function accepting a layer and returning a boolean. Default: ``None``.
		:returns:         A generator of the layers, in the order they were added.
		"""
		if predicate is None:
			yield from self._layers.values()
		else:
			for layer in self._layers.values():
				if predicate(layer):
					yield layer

	@readonly
	def Requirements(self) -> dict[str, Requirement]:
		"""
		Read-only property to access every requirement (:attr:`_requirements`), also the child requirements.

		:returns: The requirements, by ID, in the order they were added.
		"""
		return self._requirements

	@readonly
	def SpecificationItems(self) -> dict[str, SpecificationItem]:
		"""
		Read-only property to access every specification item (:attr:`_specificationItems`), also the child items.

		:returns: The specification items, by ID, in the order they were added.
		"""
		return self._specificationItems

	def IterateRequirements(
		self,
		predicate: Nullable[Callable[[Requirement], bool]] = None
	) -> Generator[Requirement, None, None]:
		"""
		Iterate all or selected requirements, also the child requirements, in the order they were added.

		If parameter ``predicate`` is not None, the given filter function is used to skip requirements in the generator.

		:param predicate: Optional, filter function accepting a requirement and returning a boolean. Default: ``None``.
		:returns:         A generator of the requirements.
		"""
		if predicate is None:
			yield from self._requirements.values()
		else:
			for requirement in self._requirements.values():
				if predicate(requirement):
					yield requirement

	def IterateSpecificationItems(
		self,
		predicate: Nullable[Callable[[SpecificationItem], bool]] = None
	) -> Generator[SpecificationItem, None, None]:
		"""
		Iterate all or selected specification items, also the child items, in the order they were added.

		If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.

		:param predicate: Optional, filter function accepting a specification item and returning a boolean. Default:
		                  ``None``.
		:returns:         A generator of the specification items.
		"""
		if predicate is None:
			yield from self._specificationItems.values()
		else:
			for specification in self._specificationItems.values():
				if predicate(specification):
					yield specification


@export
class BaseWithName(BaseWithID):
	"""
	Base-class of the elements a specification registers for its requirements to refer to: an ID, a name and a
	description.

	Its parent is the :class:`RequirementSpecification`.
	"""

	_PARENT_TYPE: ClassVar[tuple[type, ...]] = (RequirementSpecification, )  #: The element is in a specification.

	_name:        str                                                        #: The element's name.

	def __init__(
		self,
		identifier: str,
		name: str,
		*,
		description: str = "",
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[RequirementSpecification] = None
	) -> None:
		"""
		Initializes an element with its ID, name and description, and registers it in its specification.

		:param identifier:              The element's ID.
		:param name:                    The element's name.
		:param description:             Optional, the element's description. Default: ``""``.
		:param keyValuePairs:           Optional, the key-value pairs. Default: ``None``.
		:param parent:                  Optional, the specification. Default: ``None``.
		:raises TypeError:              If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:              If parameter ``parent`` isn't of type :class:`RequirementSpecification`.
		:raises ValueError:             If parameter ``identifier`` is ``None``.
		:raises TypeError:              If parameter ``identifier`` isn't of type :class:`str`.
		:raises ValueError:             If parameter ``identifier`` is empty.
		:raises ValueError:             If parameter ``description`` is ``None``.
		:raises TypeError:              If parameter ``description`` isn't of type :class:`str`.
		:raises ValueError:             If parameter ``name`` is ``None``.
		:raises TypeError:              If parameter ``name`` isn't of type :class:`str`.
		:raises ValueError:             If parameter ``name`` is empty.
		:raises DuplicatePersonaError:  If the element is a persona, and the specification already contains a persona of
		                                this ID.
		:raises DuplicateLabelError:    If the element is a label, and the specification already contains a label of this
		                                ID.
		:raises DuplicateDocumentError: If the element is a document, and the specification already contains a document of
		                                this ID.
		:raises DuplicateLayerError:    If the element is a layer, and the specification already contains a layer of this
		                                ID.
		"""
		super().__init__(identifier, description=description, keyValuePairs=keyValuePairs, parent=parent)

		if name is None:
			raise ValueError("Parameter 'name' is None.")
		elif not isinstance(name, str):
			ex = TypeError("Parameter 'name' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(name)}'.")
			raise ex
		elif name == "":
			raise ValueError("Parameter 'name' is empty.")

		self._name = name

		if parent is not None:
			parent._AddElement(self)

	@readonly
	def Name(self) -> str:
		"""
		Read-only property to access the element's name (:attr:`_name`).

		:returns: The name.
		"""
		return self._name


@export
class Persona(BaseWithName):
	"""
	A persona: a role a user of the system acts in, like the role of a use case or a user story.

	E.g. an administrator, a reviewer or a quality inspector. A real person, e.g. an author, is a
	:class:`~pyEDAA.Reports.Person`.
	"""

	_DUPLICATE_ERROR = DuplicatePersonaError  #: The error a second persona of an ID raises.


@export
class Label(BaseWithName):
	"""
	A label to classify items across layers and kinds.

	E.g. a product variant, a release or a customer.
	"""

	_DUPLICATE_ERROR = DuplicateLabelError  #: The error a second label of an ID raises.


@export
class Document(BaseWithName):
	"""
	A document attached to items.

	E.g. a datasheet, a schematic or a standard.
	"""

	_DUPLICATE_ERROR = DuplicateDocumentError  #: The error a second document of an ID raises.


@export
class Layer(BaseWithName):
	"""
	A layer of the system: the items of one engineering discipline.

	E.g. electrical, mechanical, FPGA firmware and software requirements are four layers. Each item belongs to at most one
	layer. A requirement of one layer has its counterparts in other layers, e.g. an electrical requirement in the FPGA
	firmware, and this one in the software; links of kind :attr:`LinkKind.CounterpartOf` or :attr:`LinkKind.DerivesFrom`
	state it.
	"""

	_DUPLICATE_ERROR = DuplicateLayerError  #: The error a second layer of an ID raises.

	def IterateRequirements(
		self,
		predicate: Nullable[Callable[[Requirement], bool]] = None
	) -> Generator[Requirement, None, None]:
		"""
		Iterate all or selected requirements of this layer, in the order the specification registered them.

		If parameter ``predicate`` is not None, the given filter function is used to skip requirements in the generator.

		:param predicate: Optional, filter function accepting a requirement and returning a boolean. Default: ``None``.
		:returns:         A generator of the layer's requirements; an empty one, while the layer isn't part of a
		                  specification.
		"""
		if self._root is None:
			return

		if predicate is None:
			for requirement in self._root._requirements.values():
				if requirement._layer is self:
					yield requirement
		else:
			for requirement in self._root._requirements.values():
				if requirement._layer is self and predicate(requirement):
					yield requirement

	def IterateSpecificationItems(
		self,
		predicate: Nullable[Callable[[SpecificationItem], bool]] = None
	) -> Generator[SpecificationItem, None, None]:
		"""
		Iterate all or selected specification items of this layer, in the order the specification registered them.

		If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.

		:param predicate: Optional, filter function accepting a specification item and returning a boolean. Default:
		                  ``None``.
		:returns:         A generator of the layer's specification items; an empty one, while the layer isn't part of a
		                  specification.
		"""
		if self._root is None:
			return

		if predicate is None:
			for specification in self._root._specificationItems.values():
				if specification._layer is self:
					yield specification
		else:
			for specification in self._root._specificationItems.values():
				if specification._layer is self and predicate(specification):
					yield specification


# A class with a property named like a class - ``Layer`` - can't name that class in the annotation of a field: the class
# body's namespace, where annotations are evaluated, binds the name to the property.
_Layer = Layer


@export
class BaseItem(BaseWithID):
	"""
	Base-class of the items of a specification - requirements and specification items -: a title, a creation time, a
	state, the layer, the persons, personas, labels and documents it refers to, its child items, its links and its
	history.

	An item refers only to persons, personas, labels, documents and layers of its own specification, so it must be part of
	one to refer to any. A child item has the class of its parent; its ID is unique in the specification, too.
	"""

	_title:         str                  #: The item's title.
	_rationale:     str                  #: Why the item exists or is as it is, or ``""``.
	_created:       datetime             #: The time the item was created.
	_state:         ItemState            #: The item's state in its life cycle.
	_layer:         Nullable[_Layer]     #: The layer the item belongs to, or ``None``.
	_authors:       dict[str, Person]    #: The authors of the item, by user ID.
	_owners:        dict[str, Person]    #: The owners of the item, by user ID.
	_personas:      dict[str, Persona]   #: The personas the item is about, by ID.
	_labels:        dict[str, Label]     #: The labels of the item, by ID.
	_attachments:   dict[str, Document]  #: The documents attached to the item, by ID.
	_children:      dict[str, Self]      #: The child items, by ID.
	_outboundLinks: list[Link]           #: The links from this item, in the order they were added.
	_inboundLinks:  list[Link]           #: The links to this item, in the order they were added.
	_history:       list[HistoryEvent]   #: The events in the item's life cycle, in chronological order.

	def __init__(
		self,
		identifier: str,
		title: str,
		description: str = "",
		created: Nullable[datetime] = None,
		*,
		rationale: str = "",
		state: ItemState = ItemState.Draft,
		layer: Nullable[Layer] = None,
		authors: Nullable[Iterable[Person]] = None,
		owners: Nullable[Iterable[Person]] = None,
		personas: Nullable[Iterable[Persona]] = None,
		labels: Nullable[Iterable[Label]] = None,
		attachments: Nullable[Iterable[Document]] = None,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[BaseItem | RequirementSpecification] = None
	) -> None:
		"""
		Initializes an item with its title, creation time, state, layer, and the persons, personas, labels and documents it
		refers to.

		:param identifier:                   The item's ID.
		:param title:                        The item's title.
		:param description:                  Optional, the item's description. Default: ``""``.
		:param created:                      Optional, the time the item was created; without a time zone, it is a local
		                                     time.
		                                     Default: ``None``, the current time.
		:param rationale:                    Optional, why the item exists or is as it is. Default: ``""``.
		:param state:                        Optional, the item's state. Default: :attr:`ItemState.Draft`.
		:param layer:                        Optional, the layer the item belongs to. Default: ``None``.
		:param authors:                      Optional, the authors of the item. Default: ``None``.
		:param owners:                       Optional, the owners of the item. Default: ``None``.
		:param personas:                     Optional, the personas the item is about. Default: ``None``.
		:param labels:                       Optional, the labels of the item. Default: ``None``.
		:param attachments:                  Optional, the documents attached to the item. Default: ``None``.
		:param keyValuePairs:                Optional, the key-value pairs. Default: ``None``.
		:param parent:                       Optional, the parent item or the specification. Default: ``None``.
		:raises TypeError:                   If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:                   If parameter ``parent`` isn't of a type this class declares in
		                                     :attr:`_PARENT_TYPE`.
		:raises ValueError:                  If parameter ``identifier`` is ``None``.
		:raises TypeError:                   If parameter ``identifier`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``identifier`` is empty.
		:raises ValueError:                  If parameter ``description`` is ``None``.
		:raises TypeError:                   If parameter ``description`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``title`` is ``None``.
		:raises TypeError:                   If parameter ``title`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``title`` is empty.
		:raises ValueError:                  If parameter ``rationale`` is ``None``.
		:raises TypeError:                   If parameter ``rationale`` isn't of type :class:`str`.
		:raises TypeError:                   If parameter ``created`` isn't of type :class:`~datetime.datetime`.
		:raises ValueError:                  If parameter ``state`` is ``None``.
		:raises TypeError:                   If parameter ``state`` isn't of type :class:`ItemState`.
		:raises TypeError:                   If parameter ``layer`` isn't of type :class:`Layer`.
		:raises NotInSameSpecificationError: If parameter ``layer`` isn't part of the item's specification.
		:raises TypeError:                   If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                     ``attachments``
		                                     isn't iterable, or is a single element.
		:raises TypeError:                   If parameter ``authors`` or ``owners`` contains an element not of type
		                                     :class:`~pyEDAA.Reports.Person`.
		:raises TypeError:                   If parameter ``personas``, ``labels`` or ``attachments`` contains an element
		                                     not of
		                                     type :class:`Persona`, :class:`Label` or :class:`Document`.
		:raises NotInSameSpecificationError: If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                     ``attachments``
		                                     contains an element, which isn't part of the item's specification.
		:raises DuplicatePersonError:        If parameter ``authors`` or ``owners`` contains a person twice.
		:raises DuplicatePersonaError:       If parameter ``personas`` contains a persona twice.
		:raises DuplicateLabelError:         If parameter ``labels`` contains a label twice.
		:raises DuplicateDocumentError:      If parameter ``attachments`` contains a document twice.
		"""
		super().__init__(identifier, description=description, keyValuePairs=keyValuePairs, parent=parent)

		if title is None:
			raise ValueError("Parameter 'title' is None.")
		elif not isinstance(title, str):
			ex = TypeError("Parameter 'title' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(title)}'.")
			raise ex
		elif title == "":
			raise ValueError("Parameter 'title' is empty.")

		if rationale is None:
			raise ValueError("Parameter 'rationale' is None.")
		elif not isinstance(rationale, str):
			ex = TypeError("Parameter 'rationale' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(rationale)}'.")
			raise ex

		if created is None:
			created = datetime.now()
		elif not isinstance(created, datetime):
			ex = TypeError("Parameter 'created' is not of type 'datetime'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(created)}'.")
			raise ex

		if state is None:
			raise ValueError("Parameter 'state' is None.")
		elif not isinstance(state, ItemState):
			ex = TypeError("Parameter 'state' is not of type 'ItemState'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(state)}'.")
			raise ex

		if layer is not None:
			if not isinstance(layer, Layer):
				ex = TypeError("Parameter 'layer' is not of type 'Layer'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(layer)}'.")
				raise ex
			elif self._root is None or layer._root is not self._root:
				ex = NotInSameSpecificationError("Parameter 'layer' isn't part of the item's specification.")
				ex.add_note(f"Got layer '{layer._id}'.")
				raise ex

		self._title =         title
		self._rationale =     rationale
		self._created =       created
		self._state =         state
		self._layer =         layer
		self._authors =       {}
		self._owners =        {}
		self._personas =      {}
		self._labels =        {}
		self._attachments =   {}
		self._children =      {}
		self._outboundLinks = []
		self._inboundLinks =  []
		self._history =       []

		for parameterName, references, referenceType, container, duplicateError in (
			("authors",     authors,     Person,   self._authors,     DuplicatePersonError),
			("owners",      owners,      Person,   self._owners,      DuplicatePersonError),
			("personas",    personas,    Persona,  self._personas,    DuplicatePersonaError),
			("labels",      labels,      Label,    self._labels,      DuplicateLabelError),
			("attachments", attachments, Document, self._attachments, DuplicateDocumentError),
		):
			if references is None:
				continue
			elif not isinstance(references, Iterable):
				ex = TypeError(f"Parameter '{parameterName}' is not iterable.")
				ex.add_note(f"Got type '{getFullyQualifiedName(references)}'.")
				raise ex
			elif isinstance(references, KeyValuePairsMixin):
				ex = TypeError(f"Parameter '{parameterName}' is a single element, not an iterable of elements.")
				ex.add_note(f"Got type '{getFullyQualifiedName(references)}'.")
				raise ex

			for reference in references:
				if not isinstance(reference, referenceType):
					ex = TypeError(f"Parameter '{parameterName}' contains an element not of type '{referenceType.__name__}'.")
					ex.add_note(f"Got type '{getFullyQualifiedName(reference)}'.")
					raise ex

				if referenceType is Person:
					key =        reference._userID
					registered = self._root is not None and self._root._persons.get(key) is reference
				else:
					key =        reference._id
					registered = self._root is not None and reference._root is self._root

				if not registered:
					ex = NotInSameSpecificationError(
						f"Parameter '{parameterName}' contains an element not part of the item's specification."
					)
					ex.add_note(f"Got {referenceType.__name__.lower()} '{key}'.")
					raise ex
				elif key in container:
					ex = duplicateError(f"Parameter '{parameterName}' contains an element twice.")
					ex.add_note(f"Got {referenceType.__name__.lower()} '{key}'.")
					raise ex

				container[key] = reference

	def _AddElement(self, element: Self | HistoryEvent) -> None:
		"""
		Add a child item or a history event, which names this item as its parent.

		A child item is registered with every item below it in the specification.

		:param element:                          The child item or history event.
		:raises DuplicateRequirementError:       If the child is a requirement, and the specification already contains a
		                                         requirement of an ID of the child or a requirement below it.
		:raises DuplicateSpecificationItemError: If the child is a specification item, and the specification already
		                                         contains a specification item of an ID of the child or an item below it.
		:raises DuplicateRequirementError:       If the child is a requirement, this item isn't part of a specification, and
		                                         it has a child of this ID already.
		:raises DuplicateSpecificationItemError: If the child is a specification item, this item isn't part of a
		                                         specification, and it has a child of this ID already.
		:raises RequirementsError:               If the history event is earlier than the item's creation or its last event.
		"""
		if isinstance(element, HistoryEvent):
			previous = self._history[-1]._timestamp if len(self._history) > 0 else self._created
			if element._timestamp.astimezone() < previous.astimezone():
				ex = RequirementsError("History event is earlier than the item's creation or its last event.")
				ex.add_note(f"Got '{element._timestamp.isoformat()}' after '{previous.isoformat()}'.")
				raise ex from ValueError(f"Parameter 'timestamp' is earlier than '{previous.isoformat()}'.")

			self._history.append(element)
		else:
			if self._root is not None:
				self._root._AddItems(element)
			elif element._id in self._children:
				raise element._DUPLICATE_ERROR(f"{getTypeName(self)} '{self._id}' already has a child '{element._id}'.")

			self._children[element._id] = element

	@readonly
	def Title(self) -> str:
		"""
		Read-only property to access the item's title (:attr:`_title`).

		:returns: The title.
		"""
		return self._title

	@readonly
	def Rationale(self) -> str:
		"""
		Read-only property to access why the item exists or is as it is (:attr:`_rationale`).

		:returns: The rationale, or ``""``.
		"""
		return self._rationale

	@readonly
	def Created(self) -> datetime:
		"""
		Read-only property to access the time the item was created (:attr:`_created`).

		:returns: The time; without a time zone, it is a local time.
		"""
		return self._created

	@property
	def State(self) -> ItemState:
		"""
		Property to access the item's state in its life cycle (:attr:`_state`).

		:returns:           The state.
		:raises ValueError: If ``None`` is assigned.
		:raises TypeError:  If the assigned state isn't of type :class:`ItemState`.
		"""
		return self._state

	@State.setter
	def State(self, state: ItemState) -> None:
		if state is None:
			raise ValueError("Parameter 'state' is None.")
		elif not isinstance(state, ItemState):
			ex = TypeError("Parameter 'state' is not of type 'ItemState'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(state)}'.")
			raise ex

		self._state = state

	@readonly
	def Layer(self) -> Nullable[Layer]:
		"""
		Read-only property to access the layer the item belongs to (:attr:`_layer`).

		:returns: The layer, or ``None``.
		"""
		return self._layer

	@readonly
	def Authors(self) -> dict[str, Person]:
		"""
		Read-only property to access the authors of the item (:attr:`_authors`).

		:returns: The authors, by user ID.
		"""
		return self._authors

	@readonly
	def Owners(self) -> dict[str, Person]:
		"""
		Read-only property to access the owners of the item (:attr:`_owners`).

		:returns: The owners, by user ID.
		"""
		return self._owners

	@readonly
	def Personas(self) -> dict[str, Persona]:
		"""
		Read-only property to access the personas the item is about (:attr:`_personas`).

		E.g. the role of a user story: "As a reviewer, I want ...".

		:returns: The personas, by ID.
		"""
		return self._personas

	@readonly
	def Labels(self) -> dict[str, Label]:
		"""
		Read-only property to access the labels of the item (:attr:`_labels`).

		:returns: The labels, by ID.
		"""
		return self._labels

	@readonly
	def Attachments(self) -> dict[str, Document]:
		"""
		Read-only property to access the documents attached to the item (:attr:`_attachments`).

		:returns: The documents, by ID.
		"""
		return self._attachments

	@readonly
	def Children(self) -> dict[str, Self]:
		"""
		Read-only property to access the child items (:attr:`_children`).

		:returns: The child items, by ID.
		"""
		return self._children

	@readonly
	def OutboundLinks(self) -> list[Link]:
		"""
		Read-only property to access the links from this item (:attr:`_outboundLinks`).

		:returns: The links, in the order they were added.
		"""
		return self._outboundLinks

	@readonly
	def InboundLinks(self) -> list[Link]:
		"""
		Read-only property to access the links to this item (:attr:`_inboundLinks`).

		:returns: The links, in the order they were added.
		"""
		return self._inboundLinks

	@readonly
	def History(self) -> list[HistoryEvent]:
		"""
		Read-only property to access the events in the item's life cycle (:attr:`_history`).

		:returns: The events, in chronological order.
		"""
		return self._history

	def IterateChildren(self, predicate: Nullable[Callable[[Self], bool]] = None) -> Generator[Self, None, None]:
		"""
		Iterate all or selected child items.

		If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator.

		:param predicate: Optional, filter function accepting an item and returning a boolean. Default: ``None``.
		:returns:         A generator of the child items.
		"""
		if predicate is None:
			yield from self._children.values()
		else:
			for child in self._children.values():
				if predicate(child):
					yield child

	def IterateDescendants(self, predicate: Nullable[Callable[[Self], bool]] = None) -> Generator[Self, None, None]:
		"""
		Iterate all or selected items below this one - its children, grandchildren, ... -, depth-first: each child
		followed by the items below it.

		If parameter ``predicate`` is not None, the given filter function is used to skip items in the generator. A skipped
		item's children are still iterated.

		:param predicate: Optional, filter function accepting an item and returning a boolean. Default: ``None``.
		:returns:         A generator of the items below this one.
		"""
		if predicate is None:
			for child in self._children.values():
				yield child
				yield from child.IterateDescendants()
		else:
			for child in self._children.values():
				if predicate(child):
					yield child

				yield from child.IterateDescendants(predicate)

	def LinkTo(
		self,
		destination: BaseItem,
		kind: LinkKind,
		*,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
	) -> Link:
		"""
		Create an outbound link from this item to the given item.

		:param destination:                  The item the link points to.
		:param kind:                         The relationship the link states.
		:param keyValuePairs:                Optional, the key-value pairs of the link. Default: ``None``.
		:returns:                            The link from this item to the destination.
		:raises TypeError:                   If parameter ``keyValuePairs`` isn't a mapping.
		:raises NotInSameSpecificationError: If this item isn't part of a specification.
		:raises ValueError:                  If parameter ``destination`` is ``None``.
		:raises TypeError:                   If parameter ``destination`` isn't of type :class:`BaseItem`.
		:raises ValueError:                  If parameter ``destination`` is this item.
		:raises NotInSameSpecificationError: If parameter ``destination`` isn't part of this item's specification.
		:raises ValueError:                  If parameter ``kind`` is ``None``.
		:raises TypeError:                   If parameter ``kind`` isn't of type :class:`LinkKind`.
		:raises DuplicateLinkError:          If this item has a link of this kind to the destination already.

		.. seealso::

		   :meth:`LinkFrom`
		      |rarr| Create an inbound link from the given item to this item.
		"""
		return Link(self, destination, kind, keyValuePairs=keyValuePairs)

	def LinkFrom(
		self,
		source: BaseItem,
		kind: LinkKind,
		*,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
	) -> Link:
		"""
		Create an inbound link from the given item to this item.

		:param source:                       The item the link starts at.
		:param kind:                         The relationship the link states.
		:param keyValuePairs:                Optional, the key-value pairs of the link. Default: ``None``.
		:returns:                            The link from the source to this item.
		:raises TypeError:                   If parameter ``keyValuePairs`` isn't a mapping.
		:raises ValueError:                  If parameter ``source`` is ``None``.
		:raises TypeError:                   If parameter ``source`` isn't of type :class:`BaseItem`.
		:raises NotInSameSpecificationError: If parameter ``source`` isn't part of a specification.
		:raises ValueError:                  If parameter ``source`` is this item.
		:raises NotInSameSpecificationError: If this item isn't part of the source's specification.
		:raises ValueError:                  If parameter ``kind`` is ``None``.
		:raises TypeError:                   If parameter ``kind`` isn't of type :class:`LinkKind`.
		:raises DuplicateLinkError:          If the source has a link of this kind to this item already.

		.. seealso::

		   :meth:`LinkTo`
		      |rarr| Create an outbound link from this item to the given item.
		"""
		return Link(source, self, kind, keyValuePairs=keyValuePairs)

	def IterateOutboundLinks(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[Link, None, None]:
		"""
		Iterate all or selected links from this item.

		If parameter ``predicate`` is not None, the given filter function is used to skip links in the generator.

		:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
		:returns:         A generator of the links from this item.
		"""
		if predicate is None:
			yield from self._outboundLinks
		else:
			for link in self._outboundLinks:
				if predicate(link):
					yield link

	def IterateInboundLinks(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[Link, None, None]:
		"""
		Iterate all or selected links to this item.

		If parameter ``predicate`` is not None, the given filter function is used to skip links in the generator.

		:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
		:returns:         A generator of the links to this item.
		"""
		if predicate is None:
			yield from self._inboundLinks
		else:
			for link in self._inboundLinks:
				if predicate(link):
					yield link

	def _IterateTrace(
		self,
		predicate: Nullable[Callable[[Link], bool]],
		inbound: bool
	) -> Generator[BaseItem, None, None]:
		"""
		Iterate the items reached by following links transitively, depth-first, each item once.

		:param predicate: Filter function accepting a link and returning a boolean, or ``None`` to follow every link.
		:param inbound:   ``True`` to follow links to their sources, ``False`` to their destinations.
		:returns:         A generator of the items reached, without this item.
		"""
		visited = {self}

		if predicate is None:
			def follow(item: BaseItem) -> Generator[BaseItem, None, None]:
				"""
				Nested function for recursion, following every link.

				:param item: The item, whose links are followed.
				:returns:    A generator of the items reached from the item, not visited before.
				"""
				for link in (item._inboundLinks if inbound else item._outboundLinks):
					reached = link._source if inbound else link._destination
					if reached not in visited:
						visited.add(reached)
						yield reached
						yield from follow(reached)
		else:
			def follow(item: BaseItem) -> Generator[BaseItem, None, None]:
				"""
				Nested function for recursion, following the links the predicate accepts.

				:param item: The item, whose links are followed.
				:returns:    A generator of the items reached from the item, not visited before.
				"""
				for link in (item._inboundLinks if inbound else item._outboundLinks):
					reached = link._source if inbound else link._destination
					if reached not in visited and predicate(link):
						visited.add(reached)
						yield reached
						yield from follow(reached)

		yield from follow(self)

	def IterateTrace(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[BaseItem, None, None]:
		"""
		Iterate the items this item traces to: the destinations of its links, and of their links, ..., depth-first, each
		item once.

		If parameter ``predicate`` is not None, only links accepted by the given filter function are followed.

		:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
		:returns:         A generator of the items reached, without this item.
		"""
		yield from self._IterateTrace(predicate, False)

	def IterateInboundTrace(self, predicate: Nullable[Callable[[Link], bool]] = None) -> Generator[BaseItem, None, None]:
		"""
		Iterate the items tracing to this item: the sources of its inbound links, and of their inbound links, ...,
		depth-first, each item once.

		If parameter ``predicate`` is not None, only links accepted by the given filter function are followed.

		:param predicate: Optional, filter function accepting a link and returning a boolean. Default: ``None``.
		:returns:         A generator of the items reached, without this item.
		"""
		yield from self._IterateTrace(predicate, True)


@export
class Requirement(BaseItem):
	"""
	A requirement: a condition or capability the system must, should or may meet, its kind and its obligation.

	Its parent is the :class:`RequirementSpecification` for a top-level requirement, or the :class:`Requirement` it
	refines - a child requirement. The specification registers either by its ID.
	"""

	_PARENT_TYPE:         ClassVar[tuple[type, ...]]    #: In a requirement or the specification; assigned below.

	_kind:                RequirementKind               #: What the requirement constrains.
	_obligation:          _Obligation                   #: Whether the requirement must, should or may be met.
	_verificationMethods: VerificationMethod            #: The methods verifying the requirement.
	_acceptanceCriteria:  list[str]                     #: The criteria the verification accepts the requirement by.
	_specificationItems:  dict[str, SpecificationItem]  #: The specification items specifying this requirement, by ID.

	def __init__(
		self,
		identifier: str,
		title: str,
		kind: RequirementKind,
		description: str = "",
		created: Nullable[datetime] = None,
		*,
		obligation: Obligation = Obligation.Mandatory,
		verificationMethods: VerificationMethod = VerificationMethod.Unknown,
		acceptanceCriteria: Nullable[Iterable[str]] = None,
		rationale: str = "",
		state: ItemState = ItemState.Draft,
		layer: Nullable[Layer] = None,
		authors: Nullable[Iterable[Person]] = None,
		owners: Nullable[Iterable[Person]] = None,
		personas: Nullable[Iterable[Persona]] = None,
		labels: Nullable[Iterable[Label]] = None,
		attachments: Nullable[Iterable[Document]] = None,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[Requirement | RequirementSpecification] = None
	) -> None:
		"""
		Initializes a requirement, adds it to its parent, and registers it in its specification.

		:param identifier:                   The requirement's ID.
		:param title:                        The requirement's title.
		:param kind:                         What the requirement constrains.
		:param description:                  Optional, the requirement's description. Default: ``""``.
		:param created:                      Optional, the time the requirement was created; without a time zone, it is a
		                                     local time. Default: ``None``, the current time.
		:param obligation:                   Optional, whether the requirement must, should or may be met. Default:
		                                     :attr:`Obligation.Mandatory`.
		:param verificationMethods:          Optional, the methods verifying the requirement. Default:
		                                     :attr:`VerificationMethod.Unknown`.
		:param acceptanceCriteria:           Optional, the criteria the verification accepts the requirement by. Default:
		                                     ``None``.
		:param rationale:                    Optional, why the requirement exists or is as it is. Default: ``""``.
		:param state:                        Optional, the requirement's state. Default: :attr:`ItemState.Draft`.
		:param layer:                        Optional, the layer the requirement belongs to. Default: ``None``.
		:param authors:                      Optional, the authors of the requirement. Default: ``None``.
		:param owners:                       Optional, the owners of the requirement. Default: ``None``.
		:param personas:                     Optional, the personas the requirement is about. Default: ``None``.
		:param labels:                       Optional, the labels of the requirement. Default: ``None``.
		:param attachments:                  Optional, the documents attached to the requirement. Default: ``None``.
		:param keyValuePairs:                Optional, the key-value pairs. Default: ``None``.
		:param parent:                       Optional, the requirement this one refines, or the specification. Default:
		                                     ``None``.
		:raises TypeError:                   If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:                   If parameter ``parent`` isn't of type :class:`Requirement` or
		                                     :class:`RequirementSpecification`.
		:raises ValueError:                  If parameter ``identifier`` is ``None``.
		:raises TypeError:                   If parameter ``identifier`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``identifier`` is empty.
		:raises ValueError:                  If parameter ``description`` is ``None``.
		:raises TypeError:                   If parameter ``description`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``title`` is ``None``.
		:raises TypeError:                   If parameter ``title`` isn't of type :class:`str`.
		:raises ValueError:                  If parameter ``title`` is empty.
		:raises ValueError:                  If parameter ``rationale`` is ``None``.
		:raises TypeError:                   If parameter ``rationale`` isn't of type :class:`str`.
		:raises TypeError:                   If parameter ``created`` isn't of type :class:`~datetime.datetime`.
		:raises ValueError:                  If parameter ``state`` is ``None``.
		:raises TypeError:                   If parameter ``state`` isn't of type :class:`ItemState`.
		:raises TypeError:                   If parameter ``layer`` isn't of type :class:`Layer`.
		:raises NotInSameSpecificationError: If parameter ``layer`` isn't part of the requirement's specification.
		:raises TypeError:                   If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                     ``attachments``
		                                     isn't iterable, or is a single element.
		:raises TypeError:                   If parameter ``authors`` or ``owners`` contains an element not of type
		                                     :class:`~pyEDAA.Reports.Person`.
		:raises TypeError:                   If parameter ``personas``, ``labels`` or ``attachments`` contains an element
		                                     not
		                                     of type :class:`Persona`, :class:`Label` or :class:`Document`.
		:raises NotInSameSpecificationError: If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                     ``attachments``
		                                     contains an element, which isn't part of the requirement's specification.
		:raises DuplicatePersonError:        If parameter ``authors`` or ``owners`` contains a person twice.
		:raises DuplicatePersonaError:       If parameter ``personas`` contains a persona twice.
		:raises DuplicateLabelError:         If parameter ``labels`` contains a label twice.
		:raises DuplicateDocumentError:      If parameter ``attachments`` contains a document twice.
		:raises ValueError:                  If parameter ``kind`` is ``None``.
		:raises TypeError:                   If parameter ``kind`` isn't of type :class:`RequirementKind`.
		:raises ValueError:                  If parameter ``obligation`` is ``None``.
		:raises TypeError:                   If parameter ``obligation`` isn't of type :class:`Obligation`.
		:raises ValueError:                  If parameter ``verificationMethods`` is ``None``.
		:raises TypeError:                   If parameter ``verificationMethods`` isn't of type :class:`VerificationMethod`.
		:raises TypeError:                   If parameter ``acceptanceCriteria`` isn't iterable, or is a single string.
		:raises TypeError:                   If parameter ``acceptanceCriteria`` contains an element not of type
		                                     :class:`str`.
		:raises ValueError:                  If parameter ``acceptanceCriteria`` contains an empty criterion.
		:raises DuplicateRequirementError:   If the specification already contains a requirement of this ID.
		"""
		super().__init__(
			identifier,
			title,
			description,
			created,
			rationale=rationale,
			state=state,
			layer=layer,
			authors=authors,
			owners=owners,
			personas=personas,
			labels=labels,
			attachments=attachments,
			keyValuePairs=keyValuePairs,
			parent=parent
		)

		if kind is None:
			raise ValueError("Parameter 'kind' is None.")
		elif not isinstance(kind, RequirementKind):
			ex = TypeError("Parameter 'kind' is not of type 'RequirementKind'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
			raise ex

		if obligation is None:
			raise ValueError("Parameter 'obligation' is None.")
		elif not isinstance(obligation, Obligation):
			ex = TypeError("Parameter 'obligation' is not of type 'Obligation'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(obligation)}'.")
			raise ex

		if verificationMethods is None:
			raise ValueError("Parameter 'verificationMethods' is None.")
		elif not isinstance(verificationMethods, VerificationMethod):
			ex = TypeError("Parameter 'verificationMethods' is not of type 'VerificationMethod'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(verificationMethods)}'.")
			raise ex

		self._acceptanceCriteria = []
		if acceptanceCriteria is not None:
			if not isinstance(acceptanceCriteria, Iterable):
				ex = TypeError("Parameter 'acceptanceCriteria' is not iterable.")
				ex.add_note(f"Got type '{getFullyQualifiedName(acceptanceCriteria)}'.")
				raise ex
			elif isinstance(acceptanceCriteria, str):
				ex = TypeError("Parameter 'acceptanceCriteria' is a single string, not an iterable of strings.")
				ex.add_note(f"Got value '{acceptanceCriteria}'.")
				raise ex

			for criterion in acceptanceCriteria:
				if not isinstance(criterion, str):
					ex = TypeError("Parameter 'acceptanceCriteria' contains an element not of type 'str'.")
					ex.add_note(f"Got type '{getFullyQualifiedName(criterion)}'.")
					raise ex
				elif criterion == "":
					raise ValueError("Parameter 'acceptanceCriteria' contains an empty criterion.")

				self._acceptanceCriteria.append(criterion)

		self._kind =                kind
		self._obligation =          obligation
		self._verificationMethods = verificationMethods
		self._specificationItems =  {}

		if parent is not None:
			parent._AddElement(self)

	@readonly
	def Kind(self) -> RequirementKind:
		"""
		Read-only property to access what the requirement constrains (:attr:`_kind`).

		:returns: The requirement's kind.
		"""
		return self._kind

	@readonly
	def Obligation(self) -> Obligation:
		"""
		Read-only property to access whether the requirement must, should or may be met (:attr:`_obligation`).

		:returns: The requirement's obligation.
		"""
		return self._obligation

	@readonly
	def VerificationMethods(self) -> VerificationMethod:
		"""
		Read-only property to access the methods verifying the requirement (:attr:`_verificationMethods`).

		:returns: The verification methods.
		"""
		return self._verificationMethods

	@readonly
	def AcceptanceCriteria(self) -> list[str]:
		"""
		Read-only property to access the criteria the verification accepts the requirement by (:attr:`_acceptanceCriteria`).

		:returns: The acceptance criteria, in the order given.
		"""
		return self._acceptanceCriteria

	@readonly
	def SpecificationItems(self) -> dict[str, SpecificationItem]:
		"""
		Read-only property to access the specification items specifying this requirement (:attr:`_specificationItems`).

		The relation is maintained by :meth:`SpecificationItem.AddRequirement`.

		:returns: The specification items, by ID.
		"""
		return self._specificationItems


Requirement._PARENT_TYPE =     (Requirement, RequirementSpecification)
Requirement._DUPLICATE_ERROR = DuplicateRequirementError


@export
class SpecificationItem(BaseItem):
	"""
	A specification item: how the system meets requirements.

	E.g. a design decision, an architecture or an interface description. It mirrors a requirement - with an ID, a title, a
	state, a layer, persons, personas, labels, documents, child items, links and a history -, and specifies any number of
	requirements; a requirement is specified by any number of specification items.

	Its parent is the :class:`RequirementSpecification` for a top-level item, or the :class:`SpecificationItem` it
	details. The specification registers either by its ID.
	"""

	_PARENT_TYPE:  ClassVar[tuple[type, ...]]  #: An item is in an item or the specification; assigned below the class.

	_requirements: dict[str, Requirement]      #: The requirements this item specifies, by ID.

	def __init__(
		self,
		identifier: str,
		title: str,
		description: str = "",
		created: Nullable[datetime] = None,
		*,
		requirements: Nullable[Iterable[Requirement]] = None,
		rationale: str = "",
		state: ItemState = ItemState.Draft,
		layer: Nullable[Layer] = None,
		authors: Nullable[Iterable[Person]] = None,
		owners: Nullable[Iterable[Person]] = None,
		personas: Nullable[Iterable[Persona]] = None,
		labels: Nullable[Iterable[Label]] = None,
		attachments: Nullable[Iterable[Document]] = None,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[SpecificationItem | RequirementSpecification] = None
	) -> None:
		"""
		Initializes a specification item, adds it to its parent, registers it in its specification, and relates it to the
		requirements it specifies.

		:param identifier:                       The item's ID.
		:param title:                            The item's title.
		:param description:                      Optional, the item's description. Default: ``""``.
		:param created:                          Optional, the time the item was created; without a time zone, it is a local
		                                         time. Default: ``None``, the current time.
		:param requirements:                     Optional, the requirements the item specifies. Default: ``None``.
		:param rationale:                        Optional, why the item exists or is as it is. Default: ``""``.
		:param state:                            Optional, the item's state. Default: :attr:`ItemState.Draft`.
		:param layer:                            Optional, the layer the item belongs to. Default: ``None``.
		:param authors:                          Optional, the authors of the item. Default: ``None``.
		:param owners:                           Optional, the owners of the item. Default: ``None``.
		:param personas:                         Optional, the personas the item is about. Default: ``None``.
		:param labels:                           Optional, the labels of the item. Default: ``None``.
		:param attachments:                      Optional, the documents attached to the item. Default: ``None``.
		:param keyValuePairs:                    Optional, the key-value pairs. Default: ``None``.
		:param parent:                           Optional, the specification item this one details, or the specification.
		                                         Default: ``None``.
		:raises TypeError:                       If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:                       If parameter ``parent`` isn't of type :class:`SpecificationItem` or
		                                         :class:`RequirementSpecification`.
		:raises ValueError:                      If parameter ``identifier`` is ``None``.
		:raises TypeError:                       If parameter ``identifier`` isn't of type :class:`str`.
		:raises ValueError:                      If parameter ``identifier`` is empty.
		:raises ValueError:                      If parameter ``description`` is ``None``.
		:raises TypeError:                       If parameter ``description`` isn't of type :class:`str`.
		:raises ValueError:                      If parameter ``title`` is ``None``.
		:raises TypeError:                       If parameter ``title`` isn't of type :class:`str`.
		:raises ValueError:                      If parameter ``title`` is empty.
		:raises ValueError:                      If parameter ``rationale`` is ``None``.
		:raises TypeError:                       If parameter ``rationale`` isn't of type :class:`str`.
		:raises TypeError:                       If parameter ``created`` isn't of type :class:`~datetime.datetime`.
		:raises ValueError:                      If parameter ``state`` is ``None``.
		:raises TypeError:                       If parameter ``state`` isn't of type :class:`ItemState`.
		:raises TypeError:                       If parameter ``layer`` isn't of type :class:`Layer`.
		:raises NotInSameSpecificationError:     If parameter ``layer`` isn't part of the item's specification.
		:raises TypeError:                       If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                         ``attachments`` isn't iterable, or is a single element.
		:raises TypeError:                       If parameter ``authors`` or ``owners`` contains an element not of type
		                                         :class:`~pyEDAA.Reports.Person`.
		:raises TypeError:                       If parameter ``personas``, ``labels`` or ``attachments`` contains an
		                                         element not of type :class:`Persona`, :class:`Label` or :class:`Document`.
		:raises NotInSameSpecificationError:     If parameter ``authors``, ``owners``, ``personas``, ``labels`` or
		                                         ``attachments`` contains an element, which isn't part of the item's
		                                         specification.
		:raises DuplicatePersonError:            If parameter ``authors`` or ``owners`` contains a person twice.
		:raises DuplicatePersonaError:           If parameter ``personas`` contains a persona twice.
		:raises DuplicateLabelError:             If parameter ``labels`` contains a label twice.
		:raises DuplicateDocumentError:          If parameter ``attachments`` contains a document twice.
		:raises TypeError:                       If parameter ``requirements`` isn't iterable, or is a single element.
		:raises TypeError:                       If parameter ``requirements`` contains an element not of type
		                                         :class:`Requirement`.
		:raises NotInSameSpecificationError:     If parameter ``requirements`` contains a requirement, which isn't part of
		                                         the item's specification.
		:raises DuplicateRequirementError:       If parameter ``requirements`` contains a requirement twice.
		:raises DuplicateSpecificationItemError: If the specification already contains a specification item of this ID.
		"""
		super().__init__(
			identifier,
			title,
			description,
			created,
			rationale=rationale,
			state=state,
			layer=layer,
			authors=authors,
			owners=owners,
			personas=personas,
			labels=labels,
			attachments=attachments,
			keyValuePairs=keyValuePairs,
			parent=parent
		)

		self._requirements = {}

		if requirements is not None:
			if not isinstance(requirements, Iterable):
				ex = TypeError("Parameter 'requirements' is not iterable.")
				ex.add_note(f"Got type '{getFullyQualifiedName(requirements)}'.")
				raise ex
			elif isinstance(requirements, KeyValuePairsMixin):
				ex = TypeError("Parameter 'requirements' is a single element, not an iterable of elements.")
				ex.add_note(f"Got type '{getFullyQualifiedName(requirements)}'.")
				raise ex

			for requirement in requirements:
				if not isinstance(requirement, Requirement):
					ex = TypeError("Parameter 'requirements' contains an element not of type 'Requirement'.")
					ex.add_note(f"Got type '{getFullyQualifiedName(requirement)}'.")
					raise ex
				elif self._root is None or requirement._root is not self._root:
					ex = NotInSameSpecificationError(
						"Parameter 'requirements' contains a requirement not part of the item's specification."
					)
					ex.add_note(f"Got requirement '{requirement._id}'.")
					raise ex
				elif requirement._id in self._requirements:
					ex = DuplicateRequirementError("Parameter 'requirements' contains a requirement twice.")
					ex.add_note(f"Got requirement '{requirement._id}'.")
					raise ex

				self._requirements[requirement._id] = requirement

		if parent is not None:
			parent._AddElement(self)

		for requirement in self._requirements.values():
			requirement._specificationItems[identifier] = self

	@readonly
	def Requirements(self) -> dict[str, Requirement]:
		"""
		Read-only property to access the requirements this item specifies (:attr:`_requirements`).

		:returns: The requirements, by ID.
		"""
		return self._requirements

	def AddRequirement(self, requirement: Requirement) -> None:
		"""
		Relate this item to a requirement it specifies: the item lists the requirement, and the requirement lists the item.

		:param requirement:                  The requirement.
		:raises ValueError:                  If parameter ``requirement`` is ``None``.
		:raises TypeError:                   If parameter ``requirement`` isn't of type :class:`Requirement`.
		:raises NotInSameSpecificationError: If parameter ``requirement`` isn't part of the item's specification.
		:raises DuplicateRequirementError:   If the item specifies the requirement already.
		"""
		if requirement is None:
			raise ValueError("Parameter 'requirement' is None.")
		elif not isinstance(requirement, Requirement):
			ex = TypeError("Parameter 'requirement' is not of type 'Requirement'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(requirement)}'.")
			raise ex
		elif self._root is None or requirement._root is not self._root:
			ex = NotInSameSpecificationError("Parameter 'requirement' isn't part of the item's specification.")
			ex.add_note(f"Got requirement '{requirement._id}'.")
			raise ex
		elif requirement._id in self._requirements:
			raise DuplicateRequirementError(
				f"Specification item '{self._id}' specifies requirement '{requirement._id}' already."
			)

		self._requirements[requirement._id] =       requirement
		requirement._specificationItems[self._id] = self


SpecificationItem._PARENT_TYPE =     (SpecificationItem, RequirementSpecification)
SpecificationItem._DUPLICATE_ERROR = DuplicateSpecificationItemError


@export
class LinkKind(Enum):
	"""
	The relationship a link states: the source item *<kind>* the destination item.

	A link connects items of the same or of different layers, e.g. an FPGA firmware requirement derived from an electrical
	one. Which specification item specifies which requirement, isn't a link, but the relation of
	:attr:`SpecificationItem.Requirements` and :attr:`Requirement.SpecificationItems`.
	"""

	Refines =       1  #: The source states the destination in more detail, outside the item hierarchy.
	DerivesFrom =   2  #: The source is derived from the destination, e.g. from a higher layer.
	CounterpartOf = 3  #: The source is the destination's counterpart in another layer.
	DependsOn =     4  #: The source can only be met, if the destination is met.
	ConflictsWith = 5  #: The source and the destination can't both be met.
	Duplicates =    6  #: The source states the same as the destination.
	Replaces =      7  #: The source replaces the destination, which is obsolete.
	RelatesTo =     8  #: Any other relationship.


@export
class Link(KeyValuePairsMixin, metaclass=ExtendedType, slots=True):
	"""
	A link from an item - its source - to another item of the same specification - its destination -, and the
	relationship it states.

	A link connects two items of the item hierarchy; it is no element of the hierarchy and has no parent. The source
	lists it in :attr:`~BaseItem.OutboundLinks`, the destination in :attr:`~BaseItem.InboundLinks`.
	"""

	_source:      BaseItem  #: The item the link starts at.
	_destination: BaseItem  #: The item the link points to.
	_kind:        LinkKind  #: The relationship the link states.

	def __init__(
		self,
		source: BaseItem,
		destination: BaseItem,
		kind: LinkKind,
		*,
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None
	) -> None:
		"""
		Initializes a link, and adds it to its source and its destination.

		:param source:                       The item the link starts at.
		:param destination:                  The item the link points to.
		:param kind:                         The relationship the link states.
		:param keyValuePairs:                Optional, the key-value pairs. Default: ``None``.
		:raises TypeError:                   If parameter ``keyValuePairs`` isn't a mapping.
		:raises ValueError:                  If parameter ``source`` is ``None``.
		:raises TypeError:                   If parameter ``source`` isn't of type :class:`BaseItem`.
		:raises NotInSameSpecificationError: If parameter ``source`` isn't part of a specification.
		:raises ValueError:                  If parameter ``destination`` is ``None``.
		:raises TypeError:                   If parameter ``destination`` isn't of type :class:`BaseItem`.
		:raises ValueError:                  If parameter ``destination`` is the source.
		:raises NotInSameSpecificationError: If parameter ``destination`` isn't part of the source's specification.
		:raises ValueError:                  If parameter ``kind`` is ``None``.
		:raises TypeError:                   If parameter ``kind`` isn't of type :class:`LinkKind`.
		:raises DuplicateLinkError:          If the source has a link of this kind to this destination already.
		"""
		super().__init__(keyValuePairs)

		if source is None:
			raise ValueError("Parameter 'source' is None.")
		elif not isinstance(source, BaseItem):
			ex = TypeError("Parameter 'source' is not of type 'BaseItem'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(source)}'.")
			raise ex
		elif source._root is None:
			ex = NotInSameSpecificationError("Parameter 'source' isn't part of a specification.")
			ex.add_note(f"Got item '{source._id}'.")
			raise ex

		if destination is None:
			raise ValueError("Parameter 'destination' is None.")
		elif not isinstance(destination, BaseItem):
			ex = TypeError("Parameter 'destination' is not of type 'BaseItem'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(destination)}'.")
			raise ex
		elif destination is source:
			ex = ValueError("Parameter 'destination' is the source.")
			ex.add_note(f"Got item '{destination._id}'.")
			raise ex
		elif destination._root is not source._root:
			ex = NotInSameSpecificationError("Parameter 'destination' isn't part of the source's specification.")
			ex.add_note(f"Got item '{destination._id}'.")
			raise ex

		if kind is None:
			raise ValueError("Parameter 'kind' is None.")
		elif not isinstance(kind, LinkKind):
			ex = TypeError("Parameter 'kind' is not of type 'LinkKind'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
			raise ex

		for link in source._outboundLinks:
			if link._destination is destination and link._kind is kind:
				ex = DuplicateLinkError(f"{getTypeName(source)} '{source._id}' has a '{kind.name}' link already.")
				ex.add_note(f"Got destination '{destination._id}'.")
				raise ex

		self._source =      source
		self._destination = destination
		self._kind =        kind

		source._outboundLinks.append(self)
		destination._inboundLinks.append(self)

	@readonly
	def Source(self) -> BaseItem:
		"""
		Read-only property to access the item the link starts at (:attr:`_source`).

		:returns: The source item.
		"""
		return self._source

	@readonly
	def Destination(self) -> BaseItem:
		"""
		Read-only property to access the item the link points to (:attr:`_destination`).

		:returns: The destination item.
		"""
		return self._destination

	@readonly
	def Kind(self) -> LinkKind:
		"""
		Read-only property to access the relationship the link states (:attr:`_kind`).

		:returns: The link's kind.
		"""
		return self._kind


@export
class EventKind(Enum):
	"""
	The kind of an event in the life cycle of an item.
	"""

	Opened =    1   #: The item was opened, e.g. written as a draft.
	Modified =  2   #: The item's text or fields were changed.
	Reviewed =  3   #: The item was reviewed.
	Approved =  4   #: The item was approved: it became final.
	Rejected =  5   #: The item was rejected.
	Split =     6   #: The item was split; the event names the other items involved.
	Merged =    7   #: The item was merged; the event names the other items involved.
	Closed =    8   #: The item was closed after its verification, e.g. released.
	Reopened =  9   #: The closed item was opened again.
	Obsoleted = 10  #: The item became obsolete, e.g. replaced by the items the event names.


# A class with a property named like a class - ``Person`` - can't name that class in the annotation of a field: the
# class body's namespace, where annotations are evaluated, binds the name to the property.
_Person = Person


@export
class HistoryEvent(Base):
	"""
	An event in the life cycle of an item: its kind, its time, the person causing it, and the other items involved.

	Its parent is the item, which lists it in :attr:`~BaseItem.History`, in chronological order. A split or a merge names
	the other items involved, e.g. the requirements a requirement was split into, or merged with.
	"""

	_PARENT_TYPE: ClassVar[tuple[type, ...]] = (BaseItem, )  #: An event is in the history of an item.

	_kind:        EventKind                                  #: The kind of the event.
	_timestamp:   datetime                                   #: The time of the event.
	_person:      Nullable[_Person]                          #: The person causing the event, or ``None``.
	_involved:    list[BaseItem]                             #: The other items involved, in the order given.
	_description: str                                        #: The event's description, or ``""``.

	def __init__(
		self,
		kind: EventKind,
		timestamp: datetime,
		*,
		person: Nullable[Person] = None,
		involved: Nullable[Iterable[BaseItem]] = None,
		description: str = "",
		keyValuePairs: Nullable[Mapping[Hashable, Any]] = None,
		parent: Nullable[BaseItem] = None
	) -> None:
		"""
		Initializes a history event, and adds it to the history of its item.

		:param kind:                             The kind of the event.
		:param timestamp:                        The time of the event; without a time zone, it is a local time.
		:param person:                           Optional, the person causing the event. Default: ``None``.
		:param involved:                         Optional, the other items involved. Default: ``None``.
		:param description:                      Optional, the event's description. Default: ``""``.
		:param keyValuePairs:                    Optional, the key-value pairs. Default: ``None``.
		:param parent:                           Optional, the item the event happened to. Default: ``None``.
		:raises TypeError:                       If parameter ``keyValuePairs`` isn't a mapping.
		:raises TypeError:                       If parameter ``parent`` isn't of type :class:`BaseItem`.
		:raises ValueError:                      If parameter ``kind`` is ``None``.
		:raises TypeError:                       If parameter ``kind`` isn't of type :class:`EventKind`.
		:raises ValueError:                      If parameter ``timestamp`` is ``None``.
		:raises TypeError:                       If parameter ``timestamp`` isn't of type :class:`~datetime.datetime`.
		:raises TypeError:                       If parameter ``person`` isn't of type :class:`~pyEDAA.Reports.Person`.
		:raises NotInSameSpecificationError:     If parameter ``person`` isn't part of the item's specification.
		:raises TypeError:                       If parameter ``involved`` isn't iterable, or is a single element.
		:raises TypeError:                       If parameter ``involved`` contains an element not of type
		                                         :class:`BaseItem`.
		:raises NotInSameSpecificationError:     If parameter ``involved`` contains an item, which isn't part of the item's
		                                         specification.
		:raises DuplicateRequirementError:       If parameter ``involved`` contains a requirement twice.
		:raises DuplicateSpecificationItemError: If parameter ``involved`` contains a specification item twice.
		:raises ValueError:                      If parameter ``involved`` names no item for a split or a merge.
		:raises ValueError:                      If parameter ``description`` is ``None``.
		:raises TypeError:                       If parameter ``description`` isn't of type :class:`str`.
		:raises RequirementsError:               If parameter ``timestamp`` is earlier than the item's creation or its last
		                                         event.
		"""
		super().__init__(keyValuePairs=keyValuePairs, parent=parent)

		if kind is None:
			raise ValueError("Parameter 'kind' is None.")
		elif not isinstance(kind, EventKind):
			ex = TypeError("Parameter 'kind' is not of type 'EventKind'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(kind)}'.")
			raise ex

		if timestamp is None:
			raise ValueError("Parameter 'timestamp' is None.")
		elif not isinstance(timestamp, datetime):
			ex = TypeError("Parameter 'timestamp' is not of type 'datetime'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(timestamp)}'.")
			raise ex

		if person is not None:
			if not isinstance(person, Person):
				ex = TypeError("Parameter 'person' is not of type 'Person'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(person)}'.")
				raise ex
			elif self._root is None or self._root._persons.get(person._userID) is not person:
				ex = NotInSameSpecificationError("Parameter 'person' isn't part of the item's specification.")
				ex.add_note(f"Got person '{person._userID}'.")
				raise ex

		self._involved = []
		if involved is not None:
			if not isinstance(involved, Iterable):
				ex = TypeError("Parameter 'involved' is not iterable.")
				ex.add_note(f"Got type '{getFullyQualifiedName(involved)}'.")
				raise ex
			elif isinstance(involved, KeyValuePairsMixin):
				ex = TypeError("Parameter 'involved' is a single element, not an iterable of elements.")
				ex.add_note(f"Got type '{getFullyQualifiedName(involved)}'.")
				raise ex

			for item in involved:
				if not isinstance(item, BaseItem):
					ex = TypeError("Parameter 'involved' contains an element not of type 'BaseItem'.")
					ex.add_note(f"Got type '{getFullyQualifiedName(item)}'.")
					raise ex
				elif self._root is None or item._root is not self._root:
					ex = NotInSameSpecificationError(
						"Parameter 'involved' contains an item not part of the item's specification."
					)
					ex.add_note(f"Got item '{item._id}'.")
					raise ex
				elif item in self._involved:
					ex = item._DUPLICATE_ERROR("Parameter 'involved' contains an item twice.")
					ex.add_note(f"Got item '{item._id}'.")
					raise ex

				self._involved.append(item)

		if len(self._involved) == 0 and kind in (EventKind.Split, EventKind.Merged):
			raise ValueError(f"Parameter 'involved' names no item for a '{kind.name}' event.")

		if description is None:
			raise ValueError("Parameter 'description' is None.")
		elif not isinstance(description, str):
			ex = TypeError("Parameter 'description' is not of type 'str'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(description)}'.")
			raise ex

		self._kind =        kind
		self._timestamp =   timestamp
		self._person =      person
		self._description = description

		if parent is not None:
			parent._AddElement(self)

	@readonly
	def Kind(self) -> EventKind:
		"""
		Read-only property to access the kind of the event (:attr:`_kind`).

		:returns: The event's kind.
		"""
		return self._kind

	@readonly
	def Timestamp(self) -> datetime:
		"""
		Read-only property to access the time of the event (:attr:`_timestamp`).

		:returns: The time; without a time zone, it is a local time.
		"""
		return self._timestamp

	@readonly
	def Person(self) -> Nullable[Person]:
		"""
		Read-only property to access the person causing the event (:attr:`_person`).

		:returns: The person, or ``None``.
		"""
		return self._person

	@readonly
	def Involved(self) -> list[BaseItem]:
		"""
		Read-only property to access the other items involved in the event (:attr:`_involved`).

		:returns: The items, in the order given.
		"""
		return self._involved

	@readonly
	def Description(self) -> str:
		"""
		Read-only property to access the event's description (:attr:`_description`).

		:returns: The description, or ``""``.
		"""
		return self._description