@rse/ase 2.0.4 → 2.0.6

package/plugin/meta/ase-format-specbook.yaml

@@ -789,6 +789,9 @@
   desc: >
     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
+  coverage:
+    - "[[DM.ENTITY:*]]"
+    - "[[USE-CASE:*]]"
   children:
     - kind: PERMISSION
       desc: >
@@ -1194,6 +1197,8 @@
   desc: >
     The sequenced visual or textual depiction of a specific dialog flow, illustrating how an interaction unfolds screen by screen or turn by turn.
   optional: true
+  coverage:
+    - "[[USE-CASE:*]]"
   children:
     - kind: STORYBOARD
       desc: >
@@ -1433,6 +1438,9 @@
   desc: >
     The functional components of the solution, their responsibilities, interfaces, and primary interactions, describing *how* the solution's runtime elements are structured and which responsibility each owns, delivering the behaviors the Functional Requirements state.
   optional: true
+  coverage:
+    - "[[FR.REQUIREMENT:*]]"
+    - "[[DM.ENTITY:*]]"
   children:
     - kind: COMPONENT
       desc: >
@@ -1473,7 +1481,7 @@
           optional: true
         - name: PROVIDES
           desc: >
-            Comma-separated references to the INTERFACE-MODEL objects the component provides, i.e. through which other components and external entities interact with it; omitted when the component provides no modeled interface (e.g. a user interface or an internal module).
+            Comma-separated references to the INTERFACE-MODEL objects the component provides, i.e. through which other components and external entities interact with it, which are always `Provided` ones, as a `Required` interface is offered by an external entity instead; omitted when the component provides no modeled interface (e.g. a user interface or an internal module).
           value: list([[INTERFACE:*]])
           optional: true
         - name: CONSUMES
@@ -1487,10 +1495,150 @@
           value: list([[FV.COMPONENT:*]])
           optional: true
 
+- kind: ARCH
+  name: Runtime View
+  id: RV
+  file: 26-ARCH-RV-Runtime-View.md
+  desc: >
+    The runtime interactions of the solution: for each significant use case scenario or technical situation, the ordered messages its participants -- roles, Functionality View components, and Context View entities -- exchange, describing *how* the components collaborate at runtime to deliver the behaviors their static structure merely enables.
+  optional: true
+  coverage:
+    - "[[USE-CASE:*]]"
+    - "[[SCENARIO:*]]"
+  children:
+    - kind: INTERACTION
+      desc: >
+        A single runtime interaction, named with a short (2-5 word) summary of the situation it shows (e.g. `Ask a Question`, `Login with Token`) and described in a concise (1-3 sentence) paragraph by its trigger and its outcome, plus a 1-sentence rationale ("why") stating what the interaction makes explicit, while its MESSAGE children, in document order, are the messages its participants exchange.
+      optional: true
+      props:
+        - name: REALIZES
+          desc: >
+            Comma-separated references to the USE-CASES objects (use cases or their scenarios) the interaction realizes, tracing the runtime behavior back to the behavior the requirements state; omitted for a purely technical interaction (e.g. a startup or a failover).
+          value: list([[USE-CASE:*]], [[SCENARIO:*]])
+          optional: true
+      children:
+        - kind: MESSAGE
+          desc: >
+            A single message of the interaction, named with a short (1-4 word), per-interaction unique summary of the operation, event, or response it carries (e.g. `submit question`, `question stored`) and described by a 1-sentence description of its effect.
+          props:
+            - name: FROM
+              desc: >
+                Reference to the participant sending the message: a USER-PERSONAS role, a FUNCTIONALITY-VIEW component, or a CONTEXT-VIEW entity.
+              value: list([[ROLE:*]], [[FV.COMPONENT:*]], [[CV.ENTITY:*]])
+            - name: TO
+              desc: >
+                Comma-separated references to the participants receiving the message (several ones yielding one message each): USER-PERSONAS roles, FUNCTIONALITY-VIEW components, or CONTEXT-VIEW entities.
+              value: list([[ROLE:*]], [[FV.COMPONENT:*]], [[CV.ENTITY:*]])
+            - name: KIND
+              desc: |
+                The kind of the message, one of:
+                -   `Call`:    Synchronous request the sender waits for (the default).
+                -   `Signal`:  Asynchronous notification the sender does not wait for.
+                -   `Return`:  Response to the latest unanswered call of its receiver.
+                -   `Create`:  Instantiation of its receiver, which starts there.
+                -   `Destroy`: Termination of its receiver, which ends there.
+              value: enum(Call,Signal,Return,Create,Destroy)
+              optional: true
+            - name: DURATION
+              desc: >
+                Duration constraint of a call up to its return (e.g. `< 200ms`), drawn as a bracket beside the lifeline of the caller.
+              optional: true
+            - name: TIME
+              desc: >
+                Time constraint or observation at the start of the message (e.g. `t = now`), drawn beside the lifeline of the sender.
+              optional: true
+
+- kind: ARCH
+  name: Concurrency View
+  id: CO
+  file: 27-ARCH-CO-Concurrency-View.md
+  desc: >
+    The concurrency structure of the solution, mapping functional components to processes and threads, and defining how they coordinate and communicate. The artifact is absent when the solution runs as a single sequential unit of execution and has no concurrency structure worth describing.
+  optional: true
+  coverage:
+    - "[[FV.COMPONENT:*]]"
+  children:
+    - kind: RESOURCE
+      desc: >
+        A single coordination resource the concurrency units share, named with a short (2-5 word) summary (e.g. `Ingest Queue`, `Database Connections`, `Render Lock`) and described in a concise (1-3 sentence) paragraph by what its items are and how full it may get, plus a 1-sentence rationale ("why") for its bound.
+
+        The resources and the units form a Petri net: a resource is a place holding items (tokens), a unit a transition taking items out of the resources it names in `CONSUMES` and putting items into the resources it names in `PRODUCES`, so the analysis of the net reveals unbounded resources (missing backpressure), deadlocks, and units never or no longer able to work.
+      optional: true
+      props:
+        - name: KIND
+          desc: |
+            The kind of the coordination resource, one of:
+
+            -   `Queue`:     A buffer of work items between producers and consumers.
+            -   `Topic`:     A publish/subscribe channel delivering messages.
+            -   `Pool`:      A bounded set of reusable instances (e.g. connections).
+            -   `Mutex`:     An exclusive lock (a single token).
+            -   `Semaphore`: A counting lock (several tokens).
+          value: enum(Queue,Topic,Pool,Mutex,Semaphore)
+        - name: CAPACITY
+          desc: >
+            The maximum number of items the resource holds (e.g. a queue limit or the size of a pool), omitted for an unbounded resource.
+          value: /^[1-9][0-9]*$/
+          optional: true
+        - name: TOKENS
+          desc: >
+            The number of items the resource initially holds (e.g. the free connections of a pool or the `1` of a free mutex), omitted for none.
+          value: /^(?:0|[1-9][0-9]*)$/
+          optional: true
+    - kind: UNIT
+      desc: >
+        A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise (1-3 sentence) paragraph by how it executes and how it avoids or manages contention, races, and deadlocks (including its start order and failure/restart behavior where non-obvious), plus a 1-sentence rationale ("why") for the chosen concurrency structure.
+
+        A unit executes work at runtime: a queue or channel between units is not a unit but the coordination mechanism stated in `COORDINATION`, its contract an Interface Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element hosting a managed broker a Deployment View `Managed` node -- only the executing structure itself belongs to the Concurrency View.
+      optional: true
+      props:
+        - name: KIND
+          desc: |
+            The kind of the concurrency unit, one of:
+
+            -   `Process`:   An independent OS process with its own address space.
+            -   `Thread`:    A thread of execution within a process.
+            -   `Task`:      A lightweight cooperative task (e.g. coroutine, fiber).
+            -   `Pool`:      A managed group of interchangeable workers.
+            -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
+          value: enum(Process,Thread,Task,Pool,EventLoop)
+        - name: PART-OF
+          desc: >
+            Reference to the CONCURRENCY-VIEW object this unit is contained in, expressing the containment the kinds imply: a `Thread`, `Task`, `Pool`, or `EventLoop` references the `Process` it executes within, and a `Task` the `EventLoop` or `Pool` scheduling it; omitted for a top-level unit.
+          value: "[[UNIT:*]]"
+          optional: true
+          acyclic: true
+        - name: HOSTS
+          desc: >
+            Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside this concurrency unit; omitted when no modeled component runs inside it.
+          value: list([[FV.COMPONENT:*]])
+          optional: true
+        - name: MULTIPLICITY
+          desc: >
+            How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n auto-scaled`).
+        - name: COORDINATES-WITH
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW objects this unit coordinates or communicates with at runtime, naming the peer unit only (e.g. a producer names the consumer it feeds through a shared queue), while the mechanism is stated by `COORDINATION`.
+          value: list([[UNIT:*]])
+          optional: true
+        - name: COORDINATION
+          desc: >
+            The mechanism by which the unit coordinates or communicates with other units, usually those referenced in `COORDINATES-WITH` (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
+        - name: CONSUMES
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW resources the unit takes work items or instances out of (e.g. the queue it drains, the pool it takes a connection from), modeling the unit as a transition of the Petri net its resources form; omitted when it consumes from none.
+          value: list([[RESOURCE:*]])
+          optional: true
+        - name: PRODUCES
+          desc: >
+            Comma-separated references to the CONCURRENCY-VIEW resources the unit puts work items or freed instances into (e.g. the queue it feeds, the pool it returns a connection to); omitted when it produces into none.
+          value: list([[RESOURCE:*]])
+          optional: true
+
 - kind: ARCH
   name: Technology Stack
   id: TS
-  file: 26-ARCH-TS-Technology-Stack.md
+  file: 28-ARCH-TS-Technology-Stack.md
   desc: >
     The concrete technology products the solution is built upon, organized by tier and lifecycle phase, recording for each component its chosen product, its purpose, and the alternatives that were considered but not chosen.
   optional: true
@@ -1764,7 +1912,7 @@
 - kind: ARCH
   name: Development Aspects
   id: DA
-  file: 27-ARCH-DA-Development-Aspects.md
+  file: 29-ARCH-DA-Development-Aspects.md
   desc: >
     The architecture supporting the software development process, defining the module organization, build approach, and codeline conventions. The artifact is absent when the development conventions are governed outside the specification (e.g. by repository-level contributor instructions).
   optional: true
@@ -1786,61 +1934,15 @@
           value: list([[MAXIM:*]], [[AT.PRINCIPLE:*]])
           optional: true
 
-- kind: ARCH
-  name: Concurrency View
-  id: CO
-  file: 28-ARCH-CO-Concurrency-View.md
-  desc: >
-    The concurrency structure of the solution, mapping functional components to processes and threads, and defining how they coordinate and communicate. The artifact is absent when the solution runs as a single sequential unit of execution and has no concurrency structure worth describing.
-  optional: true
-  children:
-    - kind: UNIT
-      desc: >
-        A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise (1-3 sentence) paragraph by how it executes and how it avoids or manages contention, races, and deadlocks (including its start order and failure/restart behavior where non-obvious), plus a 1-sentence rationale ("why") for the chosen concurrency structure.
-
-        A unit executes work at runtime: a queue or channel between units is not a unit but the coordination mechanism stated in `COORDINATION`, its contract an Interface Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element hosting a managed broker a Deployment View `Managed` node -- only the executing structure itself belongs to the Concurrency View.
-      optional: true
-      props:
-        - name: KIND
-          desc: |
-            The kind of the concurrency unit, one of:
-
-            -   `Process`:   An independent OS process with its own address space.
-            -   `Thread`:    A thread of execution within a process.
-            -   `Task`:      A lightweight cooperative task (e.g. coroutine, fiber).
-            -   `Pool`:      A managed group of interchangeable workers.
-            -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
-          value: enum(Process,Thread,Task,Pool,EventLoop)
-        - name: PART-OF
-          desc: >
-            Reference to the CONCURRENCY-VIEW object this unit is contained in, expressing the containment the kinds imply: a `Thread`, `Task`, `Pool`, or `EventLoop` references the `Process` it executes within, and a `Task` the `EventLoop` or `Pool` scheduling it; omitted for a top-level unit.
-          value: "[[UNIT:*]]"
-          optional: true
-          acyclic: true
-        - name: HOSTS
-          desc: >
-            Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside this concurrency unit; omitted when no modeled component runs inside it.
-          value: list([[FV.COMPONENT:*]])
-          optional: true
-        - name: MULTIPLICITY
-          desc: >
-            How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n auto-scaled`).
-        - name: COORDINATES-WITH
-          desc: >
-            Comma-separated references to the CONCURRENCY-VIEW objects this unit coordinates or communicates with at runtime, naming the peer unit only (e.g. a producer names the consumer it feeds through a shared queue), while the mechanism is stated by `COORDINATION`.
-          value: list([[UNIT:*]])
-          optional: true
-        - name: COORDINATION
-          desc: >
-            The mechanism by which the unit coordinates or communicates with other units, usually those referenced in `COORDINATES-WITH` (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
-
 - kind: ARCH
   name: Deployment View
   id: DV
-  file: 29-ARCH-DV-Deployment-View.md
+  file: 30-ARCH-DV-Deployment-View.md
   desc: >
     The environment into which the solution is deployed, partitioning it into tiers and mapping software elements to the runtime platform, hardware, and network topology.
   optional: true
+  coverage:
+    - "[[UNIT:*]]"
   children:
     - kind: TIER
       desc: >
@@ -1870,6 +1972,27 @@
 
         An area is a logically distinct, domain-induced partition of the solution deployed as physical units of its own, the *vertical* split when drawn (a `TIER` is the *horizontal*, technology-induced one): a node dedicated to the area references it via its `AREA`, a node shared by several areas references none, and a domain grouping without deployment units of its own is a Functionality View `Subsystem` instead. The kind is absent when the solution is not split vertically.
       optional: true
+    - kind: NETWORK
+      desc: >
+        A single network segment the deployment nodes are attached to, named with a short (2-5 word) summary (e.g. `Public Internet`, `Backend VLAN`, `Database Subnet`) and described in a concise (1-3 sentence) paragraph by its reach, its isolation from the other segments, and the traffic it carries, plus a 1-sentence rationale ("why") for the segmentation.
+
+        A segment is the medium the nodes communicate over: the attached nodes reference it via `NETWORKS`, the directed links between them are their `CONNECTS-TO` references, and the contract of the carried traffic is an Interface Model interface -- only the network itself belongs here. The kind is absent when the topology has no segmentation worth describing.
+      optional: true
+      props:
+        - name: SCOPE
+          desc: |
+            The reach of the segment, one of:
+            -   `Public`:   Reachable from the Internet.
+            -   `Private`:  Reachable from the solution's own nodes only.
+            -   `Isolated`: Reachable from selected nodes only (e.g. a database subnet).
+          value: enum(Public,Private,Isolated)
+        - name: PROTOCOLS
+          desc: >
+            The protocols and ports carried by the segment (e.g. `HTTPS 443, WSS 443`, `HTTP, WS, TCP 5432`).
+        - name: ADDRESSING
+          desc: >
+            The address range or naming of the segment (e.g. `10.0.0.0/8`, `public IPv4 and IPv6`, `*.example.com`).
+          optional: true
     - kind: NODE
       desc: >
         A single deployment node, named with a short (2-5 word) summary (e.g. `Web Servers`, `Database Cluster`, `Edge CDN`) and described in a concise (1-3 sentence) paragraph by the node, its sizing, and its place in the deployment topology, plus a 1-sentence rationale ("why") for the node's placement and platform choice.
@@ -1925,32 +2048,11 @@
             Comma-separated references to the DEPLOYMENT-VIEW network segments the node is attached to (e.g. a public ingress and a private backend network); omitted when the topology models no network segments.
           value: list([[NETWORK:*]])
           optional: true
-    - kind: NETWORK
-      desc: >
-        A single network segment the deployment nodes are attached to, named with a short (2-5 word) summary (e.g. `Public Internet`, `Backend VLAN`, `Database Subnet`) and described in a concise (1-3 sentence) paragraph by its reach, its isolation from the other segments, and the traffic it carries, plus a 1-sentence rationale ("why") for the segmentation.
-
-        A segment is the medium the nodes communicate over: the attached nodes reference it via `NETWORKS`, the directed links between them are their `CONNECTS-TO` references, and the contract of the carried traffic is an Interface Model interface -- only the network itself belongs here. The kind is absent when the topology has no segmentation worth describing.
-      optional: true
-      props:
-        - name: SCOPE
-          desc: |
-            The reach of the segment, one of:
-            -   `Public`:   Reachable from the Internet.
-            -   `Private`:  Reachable from the solution's own nodes only.
-            -   `Isolated`: Reachable from selected nodes only (e.g. a database subnet).
-          value: enum(Public,Private,Isolated)
-        - name: PROTOCOLS
-          desc: >
-            The protocols and ports carried by the segment (e.g. `HTTPS 443, WSS 443`, `HTTP, WS, TCP 5432`).
-        - name: ADDRESSING
-          desc: >
-            The address range or naming of the segment (e.g. `10.0.0.0/8`, `public IPv4 and IPv6`, `*.example.com`).
-          optional: true
 
 - kind: ARCH
   name: Operations View
   id: OV
-  file: 30-ARCH-OV-Operations-View.md
+  file: 31-ARCH-OV-Operations-View.md
   desc: >
     The way the solution is operated, administered, and supported in production, defining the standing procedures by which the operating organization installs, configures, migrates, observes, protects, upgrades, scales, and supports the running solution.
   optional: true
@@ -2012,7 +2114,7 @@
 - kind: ARCH
   name: Quality Perspectives
   id: QP
-  file: 31-ARCH-QP-Quality-Perspectives.md
+  file: 32-ARCH-QP-Quality-Perspectives.md
   desc: >
     How the Non-Functional Requirements (NR) are addressed by the architecture, through the tactics built into the solution across the views.
   optional: true
@@ -2070,7 +2172,7 @@
 - kind: ARCH
   name: Design Decisions
   id: DD
-  file: 32-ARCH-DD-Design-Decisions.md
+  file: 33-ARCH-DD-Design-Decisions.md
   desc: >
     The major decisions related to the solution design, each recording the forces at play, the chosen response, and the reasoning that justifies it. The artifact is the last decision-level one of the architecture, as a decision references the requirements forcing it, the elements it shapes, and the tactics and products it chose, all of which precede it, while the Code Patterns following it reference the decisions they implement.
   optional: true
@@ -2257,7 +2359,7 @@
 - kind: ARCH
   name: Code Patterns
   id: CP
-  file: 33-ARCH-CP-Code-Patterns.md
+  file: 34-ARCH-CP-Code-Patterns.md
   desc: >
     The implementation patterns the source code of the solution follows, each prescribing how one recurring concern (e.g. authorization enforcement, entity persistence, error propagation) is coded and showing it as a code listing. The artifact follows the Design Decisions, as a pattern is the coded form of the tactics and decisions preceding it, and is absent when the coding conventions are governed outside the specification (e.g. by repository-level contributor instructions).
   optional: true
@@ -2304,7 +2406,7 @@
 - kind: TEST
   name: Test Cases
   id: TC
-  file: 34-TEST-TC-Test-Cases.md
+  file: 35-TEST-TC-Test-Cases.md
   desc: >
     The verifiable conditions and steps used to confirm that requirements, domain rules, use case scenarios, state transitions, and the mechanisms, procedures, and decisions of the architecture are correctly implemented, with mandatory defined inputs, mandatory expected outcomes, and optional pre- and post-conditions. The artifact is the last one, as a test case verifies objects of every preceding kind.