Role

A Role models a named actor within a Scope. Roles form an optional parent-child chain that is resolved into a flat structure when a scope hierarchy is collapsed.

See Domain Model — Roles and Workforce for a conceptual overview and Merging — Role merging for merge semantics.

DescriptionMode

`DescriptionMode`

Bases: str, Enum

Controls how a Role's description is composed with the parent's during a scope merge.

Attributes:

Name	Type	Description
`OVERRIDE`		The child's description replaces the parent's entirely.
`EXTEND`		The parent's description is prepended to the child's, separated by a blank line.
`PREPEND`		The child's description is prepended to the parent's, separated by a blank line.

Role

`Role`

Bases: MergeableModel, Historized

A named actor within a Scope, optionally derived from a parent Role.

Roles form an optional parent-child hierarchy. When two Scopes are merged, roles sharing the same name across scopes are implicitly linked: the child scope's role receives the parent scope's role as its parent. How the descriptions are composed is controlled by the child's description_mode. Calling flatten() collapses the chain, returning a Role with no parent.

Attributes:

Name	Type	Description
`name`	`str`	Identifier following programming variable naming conventions: starts with a letter or underscore-then-letter, followed by letters, digits, or underscores.
`description`	`str`	Non-empty description of the role's responsibilities.
`description_mode`	`DescriptionMode`	Controls how this role's description is composed with the parent's during a scope merge. Defaults to `OVERRIDE`.
`parent`	`Role \| None`	The role this one is derived from. Defaults to `None`.
`competences`	`frozenset[RoleCompetence]`	Competence bindings for this role. Each binding pairs a :class:`~fushinryu_model.competence.Competence` with a relevance and proficiency threshold. Defaults to an empty frozenset.

`flatten()`

Returns this Role with its parent chain removed.

Walks the parent chain to detect cycles, then returns a copy of self with parent set to None. The leaf Role's field values are preserved as the effective values.

Returns:

Type	Description
`Role`	A new Role with `parent=None`.

Raises:

Type	Description
`ValueError`	If a cycle is detected in the parent chain.