@rse/specbook 1.2.3 → 1.2.5

package/dst/specbook-format.yaml

@@ -72,6 +72,15 @@
 # -     All artifacts have a unique 2-word name (e.g. "Context View") and a
 #       corresponding unique 2-letter identifier.
 #
+#   -   The artifacts are ordered coarse to fine wherever a granularity
+#       relation exists (REQS from the Solution Vision down to the Use
+#       Cases, UXUI from the Interaction Concept down to the Visual
+#       Design) and by concern otherwise (DATA structure/behavior/access,
+#       the ARCH viewpoints), while the back-reference rule below settles
+#       the rest. E.g. the Domain Workflows (summary level: many actors,
+#       many sittings) precede the Use Cases (user-goal level: one actor,
+#       one sitting), which reference back into the workflow activities.
+#
 #   -   All object references are strictly back-references, i.e., later
 #       objects reference earlier ones. Only the "referenced" coverage
 #       constraints and the diagram node sets (e.g. the inputs of a "hub"
@@ -107,6 +116,12 @@
         nodes: "[[REQS:*]], [[DATA:*]], [[APIS:*]], [[UXUI:*]], [[ARCH:*]], [[TEST:*]]"
         deep: true
         qualified: true
+        ordered: true
+        nest:
+            kind: true
+            crossing: target
+        config:
+            graph-columns-max: 2
     props:
         -   name: LOGO
             desc: The logo of the specification.
@@ -211,6 +226,10 @@
         resting on a premise are known and revisited once it turns out to be false. The
         artifact complements the Solution Vision: the vision states what the solution aims
         for, the premises state what it takes as given on the way there.
+
+        The premises are not constraints: a constraint is imposed on the solution and belongs
+        to the Non-Functional Requirements or the Domain Rules, whereas a premise lies outside
+        the control of the solution.
     optional: true
     refs: >
         -   ISO/IEC/IEEE 29148:2018: Systems and software engineering -- Life cycle processes -- Requirements engineering (2018),
@@ -226,13 +245,13 @@
         nodes: "[[PREMISE:*]]"
         properties:
             -   TYPE
-            -   LIKELIHOOD
-            -   IMPACT
+            -   FAILURE-LIKELIHOOD
+            -   FAILURE-IMPACT
         config:
             size-node-width-max: 440
             size-node-height-scale: 1.75
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: PREMISE
             desc: >
                 A single premise, named with a short (3-8 word) summary phrased as the fact taken
@@ -259,23 +278,24 @@
                         behave as agreed), or `Risk` (an uncertain event which, if it occurs,
                         harms the achievement of the vision).
                     value: enum(Assumption,Dependency,Risk)
-                -   name: LIKELIHOOD
+                -   name: FAILURE-LIKELIHOOD
                     desc: >
                         The likelihood that the premise fails, i.e. that the assumption turns out
                         to be false, the dependency is not honored, or the risk occurs: `Low`,
-                        `Medium`, or `High`.
+                        `Medium`, or `High`. It rates the failure and not the premise itself, so
+                        `Low` says that the premise most probably holds.
                     value: enum(Low,Medium,High)
-                -   name: IMPACT
+                -   name: FAILURE-IMPACT
                     desc: >
                         The severity of the `CONSEQUENCE` for the solution once the premise fails:
-                        `Low`, `Medium`, or `High`, so that the product of likelihood and impact
-                        ranks the premises by the attention they need.
+                        `Low`, `Medium`, or `High`, so that the product of the failure likelihood
+                        and the failure impact ranks the premises by the attention they need.
                     value: enum(Low,Medium,High)
                 -   name: CONSEQUENCE
                     desc: >
                         What concretely follows for the solution if the premise fails, stated
                         as a 1-2 sentence description of the harm (e.g. `attendees cannot enter
-                        the event`), justifying the `IMPACT` rating.
+                        the event`), justifying the `FAILURE-IMPACT` rating.
                 -   name: MITIGATION
                     desc: >
                         What is done to lower the likelihood or the impact of the failure or to
@@ -307,7 +327,7 @@
         config:
             size-node-width-max: 440
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: TERM
             name: "[A-Z][A-Za-z0-9-]*( [A-Z][A-Za-z0-9-]*)*"
             desc: >
@@ -327,7 +347,7 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[TERM:*]], [[PREMISE:*]], [[RULE:*]], [[DM.ENTITY:*]], [[PERSONA:*]]"
+                nodes: "[[TERM:*]], [[PREMISE:*]], [[RULE:*]], [[DM.ENTITY:*]], [[ROLE:*]], [[PERSONA:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -338,8 +358,9 @@
                     desc: >
                         The kind of concept the term denotes: `Entity` (a thing of the domain,
                         usually materialized by a DATA-MODEL entity), `Actor` (a party acting in
-                        the domain, be it a human role usually embodied by a PERSONA or an external
-                        system), or `Activity` (a process or procedure of the domain).
+                        the domain, be it a human role or an external system, usually played as a
+                        ROLE of the User Personas), or `Activity` (a process or procedure of the
+                        domain).
                     value: enum(Entity,Actor,Activity)
                 -   name: SYNONYMS
                     desc: >
@@ -379,11 +400,16 @@
     id: UP
     file: 04-REQS-UP-User-Personas.md
     desc: >
-        The *archetypal* user profiles representing distinct user groups, capturing their goals,
-        needs, behaviors, and context, complemented by the non-user stakeholders whose interests
-        the solution has to serve.
+        The roles the parties play towards the solution and the *archetypal* user profiles
+        embodying them: a role names the part played (by a human or by an external system) and
+        is the actor of the Use Cases and the Domain Workflows and the unit in which the
+        Authorization Model grants rights, while a persona represents a distinct user group
+        holding one or more roles, capturing its goals, needs, behaviors, and context,
+        complemented by the non-user stakeholders whose interests the solution has to serve.
     optional: true
     refs: >
+        -   Cockburn: Writing Effective Use Cases (2001),
+            https://www.informit.com/store/writing-effective-use-cases-9780201702255
         -   Cooper: The Inmates Are Running the Asylum, 2nd ed. (2004),
             https://www.informit.com/store/inmates-are-running-the-asylum-why-high-tech-products-9780672326141
         -   Cooper et al.: About Face: The Essentials of Interaction Design, 4th ed. (2014),
@@ -391,15 +417,60 @@
         -   Pruitt/Adlin: The Persona Lifecycle: Keeping People in Mind Throughout Product Design (2006),
             https://www.sciencedirect.com/book/9780125662512/the-persona-lifecycle
     diagram:
-        type: grid
-        nodes: "[[PERSONA:*]]"
-        properties:
-            -   TYPE
-            -   ROLE
+        type: graph
+        nodes: "[[ROLE:*]], [[PERSONA:*]]"
+        labeled: true
+        qualified: true
         config:
             size-node-width-max: 440
-            grid-columns-max: 4
-    childs:
+    children:
+        -   kind: ROLE
+            desc: >
+                A single role, named with the canonical name of the part a party plays towards
+                the solution (e.g. `Moderator`, matching its GLOSSARY term of type `Actor`) and
+                described in a concise (1-2 sentence) paragraph by the responsibility the role
+                carries, plus a 1-sentence rationale ("why") stating why the part is cut this way.
+                A role is the name of a part and not of a person: the personas embodying it act in
+                exactly this part and hold exactly the rights the Authorization Model grants to it
+                (plus those of the roles it `INHERITS`), while a persona holding several roles
+                holds the union of them.
+            format:
+                maxTableColumns: 5
+            referenced:
+                -   "[[*]]"
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ROLE:*]], [[TERM:*]], [[PERSONA:*]], [[ACTIVITY:*]], [[USE-CASE:*]],
+                    [[CV.ENTITY:*]]"
+                labeled: true
+                qualified: true
+                config:
+                    size-node-width-max: 440
+                    size-node-height-scale: 1.75
+            props:
+                -   name: TYPE
+                    desc: >
+                        Whether the role is played by a `Person`, i.e. a human part embodied by at
+                        least one persona, or by a `System`, i.e. an external system acting towards
+                        the solution (e.g. a registration system calling the machine-facing
+                        interface), which no persona embodies.
+                    value: enum(Person,System)
+                -   name: TERM
+                    desc: >
+                        Reference to the GLOSSARY term of type `Actor` the role plays, anchoring
+                        the role in the ubiquitous language.
+                    value: "[[TERM:*]]"
+                    optional: true
+                -   name: INHERITS
+                    desc: >
+                        Comma-separated references to the other ROLE objects this role holds in
+                        addition to its own (a role hierarchy, e.g. a manager inheriting the
+                        rights of a moderator), where an inherited permission is not restated in
+                        the Authorization Model.
+                    value: list([[ROLE:*]])
+                    optional: true
+                    acyclic: true
         -   kind: PERSONA
             desc: >
                 An archetypal user profile, named with a per-artifact unique first name of the
@@ -409,8 +480,6 @@
                 line. Non-user stakeholders are modeled as personas of type `Stakeholder`.
             format:
                 maxTableColumns: 5
-            referenced:
-                -   "[[ROLE:*]]"
             props:
                 -   name: TYPE
                     desc: >
@@ -433,9 +502,14 @@
                         The age in years of the persona.
                     value: /^[0-9]+$/
                     optional: true
-                -   name: ROLE
+                -   name: ROLES
                     desc: >
-                        The role of the persona.
+                        Comma-separated references to the ROLE objects the persona embodies, i.e.
+                        the parts it plays towards the solution and hence the rights it acts with,
+                        so that every `User` persona holds at least one role; omitted for a
+                        `Stakeholder` persona playing no part towards the solution itself.
+                    value: list([[ROLE:*]])
+                    optional: true
                 -   name: TERMS
                     desc: >
                         Comma-separated references to the GLOSSARY terms the persona embodies, i.e.
@@ -490,7 +564,7 @@
         nodes: "[[JOURNEY:*]]"
         properties:
             -   ACTORS
-    childs:
+    children:
         -   kind: JOURNEY
             desc: >
                 The end-to-end journey of a single persona (or of multiple personas sharing the same
@@ -501,7 +575,7 @@
                         Comma-separated references to the User Personas objects experiencing the
                         journey.
                     value: list([[PERSONA:*]])
-            childs:
+            children:
                 -   kind: STEP
                     desc: >
                         A single step of the journey, named with a 5-10 word summary of the step at
@@ -569,7 +643,7 @@
         config:
             size-node-width-max: 440
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: REQUIREMENT
             desc: >
                 A single functional requirement, named with a short (3-8 word) summary and described
@@ -628,7 +702,7 @@
         config:
             size-node-width-max: 440
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: REQUIREMENT
             desc: >
                 A single non-functional requirement, named with a short (3-8 word) summary and
@@ -703,7 +777,7 @@
         config:
             size-node-width-max: 440
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: RULE
             desc: >
                 A single domain rule, named with a short (3-8 word) summary and described in a
@@ -806,7 +880,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: WORKFLOW
             desc: >
                 A single workflow, named with a short (2-5 word) summary phrased as the outcome
@@ -822,6 +896,10 @@
                 The workflow is at summary level, above the user-goal level of the Use Cases: it
                 spans several actors and several sittings, and its activities leave the
                 step-by-step interaction with the solution to the use cases referencing them.
+                An activity and a use case relate n:m -- an activity is covered by several use
+                cases, a use case spans several activities, and an activity performed outside the
+                solution is covered by none at all -- so the workflow is no mere sequence of use
+                cases and cannot be assembled from them.
             automaton:
                 nodes: ACTIVITY
                 edges: HANDOFF
@@ -835,17 +913,19 @@
                 edgeSource: FROM
                 edgeTarget: TO
                 onlyConnected: true
-                properties:
-                    -   ACTOR
+                qualified: true
+                nest:
+                    properties:
+                        -   ACTOR
                 config:
                     size-node-width-max: 440
             props:
                 -   name: ACTORS
                     desc: >
-                        Comma-separated references to the User Personas objects taking part in the
-                        workflow, in the order of their first appearance, so that every `ACTOR` of
-                        an activity is listed here.
-                    value: list([[PERSONA:*]])
+                        Comma-separated references to the User Personas ROLE objects taking part
+                        in the workflow, in the order of their first appearance, so that every
+                        `ACTOR` of an activity is listed here.
+                    value: list([[ROLE:*]])
                 -   name: OWNER
                     desc: >
                         Reference to the User Personas object (usually a `Stakeholder`) accountable
@@ -881,7 +961,7 @@
                         checked at a single handoff is referenced from the handoff instead.
                     value: list([[RULE:*]])
                     optional: true
-            childs:
+            children:
                 -   kind: ACTIVITY
                     desc: >
                         A single unit of work within the workflow, performed by one party without a
@@ -895,12 +975,12 @@
                     props:
                         -   name: ACTOR
                             desc: >
-                                Reference to the User Personas object performing the activity, or
-                                `System` for an activity the solution performs on its own (e.g.
+                                Reference to the User Personas ROLE object performing the activity,
+                                or `System` for an activity the solution performs on its own (e.g.
                                 sending the invitations) or `Time` for a waiting period ending with
                                 a deadline; several parties are given only for an activity they
                                 perform jointly, as a change of the acting party is a handoff.
-                            value: list([[PERSONA:*]], enum(System,Time))
+                            value: list([[ROLE:*]], enum(System,Time))
                         -   name: INITIAL
                             desc: >
                                 Whether the activity is the initial one, i.e. the single activity
@@ -969,12 +1049,14 @@
         -   Jacobson/Spence/Bittner: Use-Case 2.0: The Guide to Succeeding with Use Cases (2011),
             https://www.ivarjacobson.com/publications/white-papers/use-case-20-e-book
     diagram:
-        type: grid
-        nodes: "[[USE-CASE:*]]"
+        type: graph
+        nodes: "[[USE-CASE:*]], [[ROLE:*]]"
+        labeled: true
+        qualified: true
+        onlyConnected: true
         config:
-            size-node-height-scale: 4
-            grid-columns-max: 4
-    childs:
+            size-node-width-max: 440
+    children:
         -   kind: USE-CASE
             desc: >
                 A discrete goal a user pursues with the solution, named with a short (3-8 word)
@@ -987,12 +1069,15 @@
                 The use case is at user-goal level: a goal the actor completes in one sitting,
                 neither a summary of many sittings and actors (which belongs to a Domain Workflow
                 as a whole, or to a User Journey when seen by a single persona) nor a single
-                interaction (which belongs to a scenario as one of its steps).
+                interaction (which belongs to a scenario as one of its steps). Its `ACTIVITIES`
+                relate it n:m to the Domain Workflow activities -- a use case spans several
+                activities and an activity is covered by several use cases -- so the two decompose
+                the same domain independently instead of nesting into each other.
             diagram:
                 type: hub
                 center: self
-                nodes: "[[USE-CASE:*]], [[PERSONA:*]], [[STEP:*]], [[ACTIVITY:*]],
-                    [[FR.REQUIREMENT:*]], [[RULE:*]], [[TRANSITION:*]]"
+                nodes: "[[USE-CASE:*]], [[ROLE:*]], [[PERSONA:*]], [[STEP:*]], [[ACTIVITY:*]],
+                    [[FR.REQUIREMENT:*]], [[RULE:*]], [[TRANSITION:*]], [[PERMISSION:*]]"
                 labeled: true
                 qualified: true
                 config:
@@ -1001,9 +1086,18 @@
             props:
                 -   name: ACTOR
                     desc: >
-                        Reference to the PERSONAS object denoting the primary actor pursuing the
-                        goal.
-                    value: "[[PERSONA:*]]"
+                        Reference to the User Personas ROLE object denoting the primary actor
+                        pursuing the goal, i.e. the part played and not the person playing it, so
+                        that a use case is written once per role and not once per persona.
+                    value: "[[ROLE:*]]"
+                -   name: PERSONAS
+                    desc: >
+                        Comma-separated references to the User Personas objects taking the
+                        `ACTOR` role in this use case, i.e. the archetypes for which its flow is
+                        worked out in the Dialog Storyboard and the Test Cases; omitted when every
+                        persona holding the role pursues the goal alike.
+                    value: list([[PERSONA:*]])
+                    optional: true
                 -   name: JOURNEYS
                     desc: >
                         Comma-separated references to the User Journey STEP objects the use case
@@ -1056,7 +1150,7 @@
                     desc: >
                         The condition that holds after the use case completes successfully.
                     optional: true
-            childs:
+            children:
                 -   kind: SCENARIO
                     desc: >
                         A concrete step-by-step flow of the use case, named with a short (3-8 word)
@@ -1122,7 +1216,7 @@
         type: graph
         nodes: "[[DM.ENTITY:*]]"
         edges: "[[RELATION:*]]"
-    childs:
+    children:
         -   kind: ENTITY
             name: "[A-Z][a-zA-Z0-9]*"
             desc: >
@@ -1132,10 +1226,13 @@
             diagram:
                 type: hub
                 center: self
-                nodes: "[[DM.ENTITY:*]]"
+                nodes: "[[DM.ENTITY:*]], [[FR.REQUIREMENT:*]], [[USE-CASE:*]]"
                 edges: "[[RELATION:*]]"
+                labeled: true
+                qualified: true
                 config:
                     size-node-width-max: 440
+                    size-node-height-scale: 1.75
             props:
                 -   name: REQUIREMENTS
                     desc: >
@@ -1144,6 +1241,16 @@
                         tracing the requirements into the data model.
                     value: list([[FR.*]])
                     optional: true
+                -   name: USE-CASES
+                    desc: >
+                        Comma-separated references to the USE-CASES objects whose scenarios
+                        create, read, update, or delete instances of the entity, tracing the use
+                        cases into the data model, so that every entity shows where its data
+                        comes from and where it goes; omitted for an entity no actor goal touches
+                        (e.g. a purely system-maintained one, justified by its `REQUIREMENTS`
+                        alone).
+                    value: list([[USE-CASE:*]])
+                    optional: true
                 -   name: TERMS
                     desc: >
                         Comma-separated references to the GLOSSARY terms the entity materializes,
@@ -1151,7 +1258,7 @@
                         is anchored in the ubiquitous language and every term shows its data.
                     value: list([[TERM:*]])
                     optional: true
-            childs:
+            children:
                 -   kind: ATTRIBUTE
                     name: "[a-z][a-zA-Z0-9]*"
                     desc: >
@@ -1264,7 +1371,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: LIFECYCLE
             desc: >
                 The lifecycle of a single entity, named with the short (1-3 word) name of the
@@ -1290,6 +1397,7 @@
                     -   FINAL
                 config:
                     size-node-width-max: 440
+                    size-node-height-scale: 1.75
             props:
                 -   name: ENTITY
                     desc: >
@@ -1297,7 +1405,7 @@
                         lifecycle per entity (an entity without a lifecycle has a trivial one).
                     value: "[[DM.ENTITY:*]]"
                     unique: true
-            childs:
+            children:
                 -   kind: STATE
                     name: "[A-Z][a-zA-Z0-9]*"
                     desc: >
@@ -1354,11 +1462,12 @@
                             local: true
                         -   name: ACTOR
                             desc: >
-                                Comma-separated references to the PERSONAS objects able to trigger
-                                the transition, and/or `System` for a transition the solution
-                                triggers on its own or `Time` for one triggered by the passing of
-                                time (e.g. an expiry); omitted when the trigger is irrelevant.
-                            value: list([[PERSONA:*]], enum(System,Time))
+                                Comma-separated references to the User Personas ROLE objects able
+                                to trigger the transition, and/or `System` for a transition the
+                                solution triggers on its own or `Time` for one triggered by the
+                                passing of time (e.g. an expiry); omitted when the trigger is
+                                irrelevant.
+                            value: list([[ROLE:*]], enum(System,Time))
                             optional: true
                         -   name: GUARD
                             desc: >
@@ -1378,9 +1487,12 @@
                                 Comma-separated references to the USE-CASES objects whose
                                 scenarios trigger the transition, i.e. in which a scenario step
                                 causes the state change, tracing the transition into the use
-                                cases exercising it; omitted for a transition no use case
-                                triggers (e.g. one triggered by `Time` or by the system alone).
-                            value: list([[USE-CASE:*]])
+                                cases exercising it, or, where not every scenario of a use case
+                                triggers it, to the very `SCENARIO` objects doing so, tracing
+                                the transition into the step-by-step flows causing it; omitted
+                                for a transition no use case triggers (e.g. one triggered by
+                                `Time` or by the system alone).
+                            value: list([[USE-CASE:*]], [[SCENARIO:*]])
                             optional: true
 
 -   kind: DATA
@@ -1388,13 +1500,13 @@
     id: AM
     file: 13-DATA-AM-Authorization-Model.md
     desc: >
-        The access rights of the solution, bundled into the roles a person acts in and stating for
-        each role the operations it may perform on each entity, confined to the lifecycle states
-        of the entity and to a further condition where necessary, so that "who may do what on
-        which entity in which state" is answered in one place instead of being scattered over the
-        actors of the state transitions, the actors of the use cases, and the prose of the domain
-        rules. The model is closed: an operation not granted to a role is forbidden, exactly like
-        a move not listed as a state transition.
+        The access rights of the solution, granted to the roles of the User Personas and stating
+        for each role the operations it may perform on each entity, confined to the lifecycle
+        states of the entity and to a further condition where necessary, so that "who may do what
+        on which entity in which state" is answered in one place instead of being scattered over
+        the actors of the state transitions, the actors of the use cases, and the prose of the
+        domain rules. The model is closed: an operation not granted to a role is forbidden,
+        exactly like a move not listed as a state transition.
     optional: true
     refs: >
         -   Ferraiolo/Kuhn: Role-Based Access Controls, 15th National Computer Security Conference (1992),
@@ -1409,110 +1521,81 @@
         type: graph
         nodes: "[[ROLE:*]], [[DM.ENTITY:*]]"
         edges: "[[PERMISSION:*]]"
+        edgeSource: ROLE
         edgeTarget: ENTITY
         onlyConnected: true
         qualified: true
         config:
             size-node-width-max: 440
             graph-channel-width-max: 340
-    childs:
-        -   kind: ROLE
+    children:
+        -   kind: PERMISSION
             desc: >
-                A single role, named with the canonical name of the domain role it grants (e.g.
-                `Moderator`, matching its GLOSSARY term of type `Actor`) and described in a concise
-                (1-2 sentence) paragraph by the responsibility the role carries, plus a 1-sentence
-                rationale ("why") stating why the rights are bundled this way. A role is the unit
-                in which rights are granted to a person: the personas embodying it hold exactly
-                its `PERMISSION` objects (plus those of the roles it `INHERITS`), while a persona
-                holding several roles holds the union of their permissions.
-            diagram:
-                type: hub
-                center: self
-                deep: true
-                nodes: "[[ROLE:*]], [[PERSONA:*]], [[TERM:*]], [[DM.ENTITY:*]], [[RULE:*]]"
-                labeled: true
-                qualified: true
-                config:
-                    size-node-width-max: 440
-                    size-node-height-scale: 1.75
+                A single right of a role on a single entity, named with a short (2-5 word) verb
+                phrase of what the role may do (e.g. `Decide Pending Messages`) and described by
+                a 1-sentence description of the right, in particular of the reach of its
+                `CONDITION`. One permission covers one entity: the operations it grants, the
+                states of the entity in which they are granted, and the condition under which
+                they are granted, so that the permissions of all roles form the access matrix of
+                roles against entities. Any operation, state, or condition not covered by a
+                permission of the role (or of a role it `INHERITS`) is forbidden.
+            format:
+                maxTableColumns: 8
             props:
-                -   name: ACTORS
+                -   name: ROLE
                     desc: >
-                        Comma-separated references to the User Personas objects embodying the
-                        role, i.e. the personas acting with exactly its rights, so that every
-                        persona holds at least one role and its rights are stated here rather than
-                        implied by its `ROLE` description, and/or to the GLOSSARY terms of type
-                        `Actor` denoting the external systems holding the role (e.g. a registration
-                        system calling the machine-facing interface), as an external system is no
-                        persona.
-                    value: list([[PERSONA:*]], [[TERM:*]])
-                -   name: TERM
+                        Reference to the User Personas ROLE object the permission is granted to,
+                        so that the permissions of a role are found by its references.
+                    value: "[[ROLE:*]]"
+                -   name: ENTITY
+                    desc: Reference to the DATA-MODEL entity the permission is granted on.
+                    value: "[[DM.ENTITY:*]]"
+                -   name: OPERATIONS
+                    desc: >
+                        Comma-separated operations the role may perform on the entity: the
+                        generic `Create`, `Read`, `Update`, and `Delete`, and/or references to
+                        the STATE-MODEL transitions of the entity the role may trigger (a state
+                        change is not an `Update`: it is granted by its transition only), where
+                        every role named as `ACTOR` of a transition holds a permission granting
+                        it.
+                    value: list(enum(Create,Read,Update,Delete), [[TRANSITION:*]])
+                -   name: STATES
+                    desc: >
+                        Comma-separated references to the STATE-MODEL states of the entity in
+                        which the operations are granted (`Create` needs none, as a creation
+                        enters the initial state); omitted when granted in every state or when
+                        the entity has no lifecycle.
+                    value: list([[STATE:*]])
+                    optional: true
+                -   name: CONDITION
+                    desc: >
+                        The condition which, beyond the role and the `STATES`, has to hold for
+                        the operations to be granted, stated as a 1-sentence statement of what
+                        has to hold, typically the ownership of the instance (e.g. `The attendee
+                        is the sender of the message.`), a confinement to certain attributes
+                        (e.g. `The update is confined to the presenter alert.`), or a
+                        configuration of the surrounding entity; omitted when the role and the
+                        states alone grant the operations.
+                    optional: true
+                -   name: RULES
                     desc: >
-                        Reference to the GLOSSARY term of type `Actor` the role grants, anchoring
-                        the role in the ubiquitous language.
-                    value: "[[TERM:*]]"
+                        Comma-separated references to the DOMAIN-RULES objects justifying or
+                        bounding the permission, i.e. the rules whose statement grants or limits
+                        the right.
+                    value: list([[RULE:*]])
                     optional: true
-                -   name: INHERITS
+                -   name: USE-CASES
                     desc: >
-                        Comma-separated references to the other ROLE objects whose permissions
-                        this role holds in addition to its own (a role hierarchy, e.g. a manager
-                        inheriting the rights of a moderator), where an inherited permission is
-                        not restated.
-                    value: list([[ROLE:*]])
+                        Comma-separated references to the USE-CASES objects whose scenarios
+                        exercise the permission, i.e. in which a scenario step performs one of
+                        the granted operations, or, where not every scenario of a use case does
+                        so, to the very `SCENARIO` objects doing so, including the exceptional
+                        scenarios in which the solution refuses an operation at the boundary of
+                        the permission, tracing the permission into the step-by-step flows
+                        exercising and enforcing it; omitted for a permission exercised outside
+                        any use case (e.g. through the configuration).
+                    value: list([[USE-CASE:*]], [[SCENARIO:*]])
                     optional: true
-                    acyclic: true
-            childs:
-                -   kind: PERMISSION
-                    desc: >
-                        A single right of the role on a single entity, named with a short (2-5
-                        word) verb phrase of what the role may do (e.g. `Decide Pending Messages`)
-                        and described by a 1-sentence description of the right, in particular of
-                        the reach of its `CONDITION`. One permission covers one entity: the
-                        operations it grants, the states of the entity in which they are granted,
-                        and the condition under which they are granted, so that the permissions
-                        of all roles form the access matrix of roles against entities. Any
-                        operation, state, or condition not covered by a permission of the role (or
-                        of an inherited one) is forbidden.
-                    format:
-                        maxTableColumns: 7
-                    props:
-                        -   name: ENTITY
-                            desc: Reference to the DATA-MODEL entity the permission is granted on.
-                            value: "[[DM.ENTITY:*]]"
-                        -   name: OPERATIONS
-                            desc: >
-                                Comma-separated operations the role may perform on the entity: the
-                                generic `Create`, `Read`, `Update`, and `Delete`, and/or references
-                                to the STATE-MODEL transitions of the entity the role may trigger
-                                (a state change is not an `Update`: it is granted by its transition
-                                only), where every persona named as `ACTOR` of a transition holds
-                                a role granting it.
-                            value: list(enum(Create,Read,Update,Delete), [[TRANSITION:*]])
-                        -   name: STATES
-                            desc: >
-                                Comma-separated references to the STATE-MODEL states of the entity
-                                in which the operations are granted (`Create` needs none, as a
-                                creation enters the initial state); omitted when granted in every
-                                state or when the entity has no lifecycle.
-                            value: list([[STATE:*]])
-                            optional: true
-                        -   name: CONDITION
-                            desc: >
-                                The condition which, beyond the role and the `STATES`, has to hold
-                                for the operations to be granted, stated as a 1-sentence statement
-                                of what has to hold, typically the ownership of the instance (e.g.
-                                `The attendee is the sender of the message.`), a confinement to
-                                certain attributes (e.g. `The update is confined to the presenter
-                                alert.`), or a configuration of the surrounding entity; omitted
-                                when the role and the states alone grant the operations.
-                            optional: true
-                        -   name: RULES
-                            desc: >
-                                Comma-separated references to the DOMAIN-RULES objects justifying
-                                or bounding the permission, i.e. the rules whose statement grants
-                                or limits the right.
-                            value: list([[RULE:*]])
-                            optional: true
 
 -   kind: APIS
     name: Interface Model
@@ -1544,7 +1627,7 @@
         properties:
             -   KIND
             -   DIRECTION
-    childs:
+    children:
         -   kind: INTERFACE
             desc: >
                 A single interface, named with a short (2-5 word) summary (e.g. `Public REST API`,
@@ -1629,7 +1712,7 @@
         qualified: true
         config:
             size-node-width-max: 440
-    childs:
+    children:
         -   kind: TYPE
             name: "[A-Z][A-Za-z0-9_]*"
             desc: >
@@ -1691,7 +1774,7 @@
                         entities), tracing the interface into the data model.
                     value: list([[DM.ENTITY:*]])
                     optional: true
-            childs:
+            children:
                 -   kind: FIELD
                     name: "[A-Za-z_][A-Za-z0-9_-]*"
                     desc: >
@@ -1792,7 +1875,7 @@
         qualified: true
         config:
             size-node-width-max: 440
-    childs:
+    children:
         -   kind: ENDPOINT
             name: "[A-Za-z_][A-Za-z0-9_-]*"
             desc: >
@@ -1872,7 +1955,7 @@
                         realizes, tracing the requirements into the interface.
                     value: list([[USE-CASE:*]])
                     optional: true
-            childs:
+            children:
                 -   kind: OPTION
                     name: "-{0,2}[A-Za-z_][A-Za-z0-9_-]*"
                     desc: >
@@ -2034,7 +2117,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: PRINCIPLE
             desc: >
                 A single interaction principle, named with a short (2-5 word) summary (e.g.
@@ -2115,7 +2198,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: CONVENTION
             desc: >
                 A single language convention, named with a short (2-5 word) summary (e.g. `Neutral
@@ -2186,7 +2269,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: PATTERN
             desc: >
                 A single reusable dialog pattern, named with a short (2-5 word) summary (e.g.
@@ -2280,7 +2363,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: STORYBOARD
             desc: >
                 A single depicted dialog flow, named with a short (3-8 word) summary of the flow and
@@ -2312,7 +2395,7 @@
                         interface, omitted for a storyboard of a flow no scenario covers.
                     value: "[[SCENARIO:*]]"
                     optional: true
-            childs:
+            children:
                 -   kind: FRAME
                     desc: >
                         A single frame of the storyboard, named with a short (2-5 word) label for
@@ -2385,7 +2468,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: ELEMENT
             desc: >
                 A single visual design element, named with a short (2-5 word) summary (e.g. `Brand
@@ -2515,7 +2598,7 @@
         qualified: true
         properties:
             -   KIND
-    childs:
+    children:
         -   kind: ENTITY
             desc: >
                 A single external entity the solution interacts with, named with a short (2-5 word)
@@ -2571,13 +2654,12 @@
                     optional: true
                 -   name: ACTORS
                     desc: >
-                        Comma-separated references to the User Personas objects acting behind the
-                        entity: a `Person` entity is the boundary-level role class and the referenced
-                        personas are its archetypes, while an `Organization` entity may reference
-                        the `Stakeholder` personas representing it, so the entity aggregates the
-                        personas instead of re-stating them; omitted when no persona stands behind
-                        the entity.
-                    value: list([[PERSONA:*]])
+                        Comma-separated references to the User Personas ROLE objects acting
+                        behind the entity: a `Person` entity is the boundary-level class of the
+                        `Person` roles acting through it, while a `System` entity may reference
+                        the `System` role it plays, so the entity aggregates the roles instead of
+                        re-stating them; omitted when no modeled role stands behind the entity.
+                    value: list([[ROLE:*]])
                     optional: true
                 -   name: PREMISES
                     desc: >
@@ -2612,9 +2694,12 @@
         type: graph
         nodes: "[[FV.COMPONENT:*]]"
         labeled: true
+        nest:
+            properties:
+                -   PART-OF
         properties:
             -   KIND
-    childs:
+    children:
         -   kind: COMPONENT
             desc: >
                 A single functional component, named with a short (2-5 word) summary (e.g.
@@ -2717,8 +2802,16 @@
             https://c4model.com/diagrams/container
     diagram:
         type: grid
-        nodes: "[[TS.TIER:*]]"
-    childs:
+        nodes: "[[TS.TIER:*]], [[TS.TIER:*.COMPONENT:*]]"
+        nest:
+            parent: true
+            layout: grid
+        properties:
+            -   PRODUCT
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 3
+    children:
         -   kind: TIER
             desc: |
                 The architectural tier grouping the technology components belonging to it, named
@@ -2742,7 +2835,7 @@
                 config:
                     size-node-width-max: 440
                     size-node-height-scale: 1.75
-            childs:
+            children:
                 -   kind: COMPONENT
                     desc: >
                         A single technology component, named with a short (2-5 word) summary (e.g.
@@ -3070,7 +3163,7 @@
         nodes: "[[ASPECT:*]]"
         properties:
             -   CATEGORY
-    childs:
+    children:
         -   kind: ASPECT
             desc: >
                 A single development aspect, named with a short (2-5 word) summary (e.g. `Module
@@ -3118,7 +3211,7 @@
         labeled: true
         properties:
             -   KIND
-    childs:
+    children:
         -   kind: UNIT
             desc: >
                 A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker
@@ -3207,14 +3300,18 @@
         type: graph
         nodes: "[[NODE:*]]"
         labeled: true
+        qualified: true
+        nest:
+            properties:
+                -   PART-OF
+                -   TIER
         properties:
-            -   TIER
             -   AREA
             -   KIND
             -   PLATFORM
         config:
             size-node-width-max: 350
-    childs:
+    children:
         -   kind: TIER
             desc: >
                 A single deployment tier, named with a short (1-3 word) summary (e.g. `Client`,
@@ -3455,7 +3552,7 @@
         nodes: "[[CONCERN:*]]"
         properties:
             -   CATEGORY
-    childs:
+    children:
         -   kind: CONCERN
             desc: >
                 A single operational concern, named with a short (2-5 word) summary (e.g. `Rolling
@@ -3567,7 +3664,7 @@
         nodes: "[[TACTIC:*]]"
         properties:
             -   QUALITY
-    childs:
+    children:
         -   kind: TACTIC
             desc: >
                 A single quality tactic, one architectural tactic applied to one quality attribute
@@ -3691,7 +3788,7 @@
         config:
             size-node-width-max: 440
             grid-columns-max: 5
-    childs:
+    children:
         -   kind: DECISION
             desc: |
                 A single architecture decision, named with a short summary of the decision, not
@@ -3931,7 +4028,7 @@
             size-node-width-max: 440
             size-node-height-scale: 2
             grid-columns-max: 4
-    childs:
+    children:
         -   kind: TEST-CASE
             desc: >
                 A single verifiable test case, named with a short (3-8 word) summary and defined by