archsight 0.3.2 → 0.4.0

data/lib/archsight/query.rb

@@ -52,7 +52,7 @@ module Archsight
       def parse(source)
         lexer = Lexer.new(source)
         tokens = lexer.tokenize
-        parser = Parser.new(tokens)
+        parser = Parser.new(tokens, source: source)
         parser.parse
       rescue LexerError, ParseError, InvalidRegexError => e
         # Re-raise with source context

data/lib/archsight/references.rb

@@ -32,7 +32,7 @@ module Archsight
       end
     end
 
-    # The resources a markdown text mentions with `[[...]]` links and `![[View/...]]` embeds, outside code.
+    # The resources a markdown text mentions with `[[...]]` links and `![[Kind/...]]` embeds, outside code.
     # @return [Array<Base>]
     def mentions(markdown, finder)
       visible = markdown.to_s.gsub(FENCE, "").gsub(INLINE_CODE, "")
@@ -111,10 +111,10 @@ module Archsight
         @links.exact_target_for(target)
       end
 
-      # An `![[Kind/Name]]` embed: only views and analyses can be embedded
+      # An `![[Kind/Name]]` embed: any resource but a page
       def embed(reference)
         kind = reference.split("/", 2).first
-        return unless Helpers::Embeds::KINDS.include?(kind)
+        return unless Helpers::Embeds.embeddable_kind?(kind)
 
         reference(reference)
       end

data/lib/archsight/renderer.rb

@@ -40,9 +40,11 @@ module Archsight
     def gnode(graph, inst, opts = {})
       label = "<TABLE><TR><TD><B>#{inst.name}</B></TD></TR><TR><TD>#{inst.klass}</TD></TR></TABLE>"
       label = inst.name if opts[:simple_label]
-      graph.node gname(inst), class: css_class(inst), shape: :box,
-                              style: "rounded,filled", fontname: FONT, label: label,
-                              href: "/kinds/#{inst.klass}/instances/#{inst.name}"
+      attrs = { class: css_class(inst), shape: :box, style: "rounded,filled", fontname: FONT, label: label,
+                href: "/kinds/#{inst.klass}/instances/#{inst.name}" }
+      # A resource at the depth limit with more dependencies: dashed, its own page shows them
+      attrs.merge!(style: "rounded,filled,dashed", tooltip: "More dependencies: open it to explore them") if opts[:truncated]
+      graph.node gname(inst), attrs
     end
 
     def gedge(graph, a_inst, b_inst, label)
@@ -104,29 +106,84 @@ module Archsight
       end
     end
 
-    def create_graph_one(db, klass_pat, name_pat)
-      name = "#{klass_pat}:#{name_pat}"
-      nodes = {}
-      edges = {}
-      Archsight::Graphvis.new(name).draw_dot do |g|
-        klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
-        instances = db.instances[klass]
-        inst = instances[name_pat] || raise("name #{name_pat} for kind #{klass_pat} not found")
-        create_graph_one_inst(db, g, inst, nodes, edges)
+    # The layer an instance graph also follows by default, below the instance's own layer (technology is the bottom
+    # of the stack; implementation points at what it changes)
+    NEXT_LAYER = { "motivation" => "strategy", "strategy" => "business", "business" => "application",
+                   "application" => "technology", "implementation" => "application" }.freeze
+
+    # The layers the graph of a resource of this layer follows when its page opens: its own and the next one below,
+    # every layer for `other` (pages, views, locations, ... refer to anything)
+    def self.default_graph_layers(layer)
+      return Archsight::Resources::LAYERS.dup unless Archsight::Resources::LAYERS.include?(layer) && layer != "other"
+
+      [layer, NEXT_LAYER[layer]].compact
+    end
+
+    # The dependency graph of one instance: the resources its relations lead to, breadth first, so a resource gets
+    # the depth of its shortest path.
+    # @param max_depth [Integer, nil] follow relations this many steps from the instance (nil: all the way). A
+    #   resource at the limit that has more relations is drawn dashed.
+    # @param layers [Array<String>, nil] follow only relations to resources of these layers (nil: every layer); the
+    #   instance itself is always shown
+    def create_graph_one(db, klass_pat, name_pat, max_depth: nil, layers: nil)
+      klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
+      root = db.instances[klass]&.[](name_pat) || raise("name #{name_pat} for kind #{klass_pat} not found")
+
+      Archsight::Graphvis.new("#{klass_pat}:#{name_pat}").draw_dot do |g|
+        nodes = {}
+        edges = {}
+        queue = [[root, 0]]
+        while queue.any?
+          inst, depth = queue.shift
+          next if nodes[inst]
+
+          nodes[inst] = true
+          targets = graph_targets(inst, layers)
+          if max_depth && depth >= max_depth
+            gnode(g, inst, truncated: targets.any?)
+            next
+          end
+
+          gnode(g, inst)
+          targets.each do |verb, rel|
+            edge_name = "#{gname(inst)}|#{verb}|#{gname(rel)}"
+            gedge(g, inst, rel, verb) unless edges[edge_name]
+            edges[edge_name] = true
+            queue << [rel, depth + 1] unless nodes[rel]
+          end
+        end
+      end
+    end
+
+    # The relations of a kind to its own kind (a team's sub-teams, a service's dependencies on other services) as
+    # [verb, key] pairs
+    def self.self_relations(klass)
+      kind = klass.name.to_s.split("::").last
+      klass.declared_relations.filter_map { |verb, key, target| [verb, key] if target.to_s == kind }
+    end
+
+    # The graph of a kind: its resources that are related to each other by its relations to its own kind (an org
+    # chart for BusinessActor). Resources without such a relation are left out, the kind's list shows them.
+    def create_graph_kind(db, klass_pat)
+      klass = Archsight::Resources[klass_pat] || raise("kind #{klass_pat} unknown")
+      relations = Archsight::GraphvisRenderer.self_relations(klass)
+      sources = (db.instances[klass] || {}).values.reject(&:abandoned?)
+      edges = sources.flat_map do |inst|
+        relations.flat_map { |verb, key| inst.relations(verb, key).reject(&:abandoned?).map { |rel| [inst, verb, rel] } }
+      end
+      edges.uniq! { |inst, verb, rel| "#{gname(inst)}|#{verb}|#{gname(rel)}" }
+
+      Archsight::Graphvis.new(klass_pat).draw_dot do |g|
+        edges.flat_map { |inst, _, rel| [inst, rel] }.uniq.each { |inst| gnode(g, inst, simple_label: true) }
+        edges.each { |inst, verb, rel| gedge(g, inst, rel, verb) }
       end
     end
 
-    def create_graph_one_inst(db, graph, inst, nodes, edges)
-      return if nodes[inst] # Already visited - prevent infinite recursion
-
-      gnode(graph, inst)
-      nodes[inst] = true
-      inst.class.relations.each do |verb, kind|
-        inst.relations(verb, kind).each do |rel|
-          edge_name = "#{inst}|#{verb}|#{rel}"
-          gedge(graph, inst, rel, verb) unless edges[edge_name]
-          edges[edge_name] = true
-          create_graph_one_inst(db, graph, rel, nodes, edges)
+    # The [verb, target] pairs of an instance's relations the graph follows: those to resources of the layers
+    def graph_targets(inst, layers)
+      inst.class.relations.flat_map do |verb, kind|
+        inst.relations(verb, kind).filter_map do |rel|
+          [verb, rel] if layers.nil? || layers.include?(rel.class.layer)
         end
       end
     end

data/lib/archsight/resources/analysis.rb

@@ -57,8 +57,9 @@ class Archsight::Resources::Analysis < Archsight::Resources::Base
 
   # Description
   annotation "analysis/description",
-             description: "Human-readable description of what this analysis validates",
-             title: "Description"
+             description: "Human-readable description of what this analysis validates (markdown)",
+             title: "Description",
+             format: :markdown
 
   # Execution configuration
   annotation "analysis/timeout",

data/lib/archsight/resources/application_component.rb

@@ -2,7 +2,7 @@
 
 # ApplicationComponent a part of the ApplicationService
 class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated, :backup
+  include_annotations :git, :architecture, :generated, :backup, :asset, :risk
 
   description <<~MD
     Represents a logical part of an application service that can be deployed independently.
@@ -24,6 +24,53 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     - Backend components
     - Frontend applications
     - Background workers
+
+    ## Choosing this kind
+
+    **Question:** What is built, deployed and versioned?
+    **Test:** It has artifacts and a `component/type`, and can be deployed or linked.
+    **Name:** The part, by runtime role (API, Operator, Worker) as in "Payments:API", not by repository category
+    ("Testing", "Tools", "Infrastructure"). Test, tooling and infrastructure-as-code repositories belong to the
+    component they build, test or deploy.
+
+    A component belongs to exactly one service. See the modeling guide, "Choosing the Kind".
+
+    ## Component types
+
+    Set `component/type` to say what the component is built as; importers set it from the manifests:
+
+    - `executable`: has an entry point and is run or deployed (services, workers, operators, command-line tools)
+    - `library`: imported by other components and not run on its own (shared libraries, SDKs)
+    - `module`: a unit of versioning or dependency that bundles executables and importable libraries (a Go module
+      with `cmd/` and shared packages, a Maven parent, an npm workspace root)
+    - `plugin`: loaded by a host program (kubectl, Terraform, Grafana)
+    - `frontend`: runs in the browser
+    - `other`
+
+    `component/role` refines an executable or plugin (`service`, `cli`, `job`, `operator`, `agent`); importers cannot
+    tell these apart, so it is set by hand and never overwritten. Importers also add machine tags
+    (`namespace:value`) to the regular `architecture/tags`: `ecosystem:go`, `packaging:go-module`,
+    `linkage:shared`; the tags a person set stay, and a re-import only replaces the machine tags of these
+    namespaces. The entry points (main packages such as `cmd/api`) go to `component/entrypoints`, a list that
+    works in queries like a tag but is not a sidebar filter, as there are too many distinct values. Deployable forms (container image, chart, package) are `TechnologyArtifact`s, not
+    component types.
+
+    ## Where it runs
+
+    A component is `servedBy` the `TechnologyService` it is deployed on (a product's cluster, a managed platform) and
+    `servedBy` the `TechnologySystemSoftware` it runs on (the runtime, such as a Kubernetes distribution). Deployment
+    importers write the service per component, so a sidecar or agent deployed into many clusters shows where it runs
+    without making its own service look like it runs in all of them.
+
+    The computed `component/dependents` counts the components that depend on this one, which tells shared libraries
+    and modules from components nobody consumes.
+
+    ## Security and risk modelling
+
+    - **Asset at risk:** set `asset/value` and the protection needs; `assesses` from a vulnerability or risk.
+    - **Control implementation:** a component that implements a control measure `realizes` the requirement and is
+      `evidencedBy` evidence.
+    - **Threat agent:** a component can be the `causedBy` of an event (a compromised service).
   MD
 
   icon "component"
@@ -39,6 +86,18 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              title: "Architecture Size",
              enum: %w[microservice monolith]
 
+  # Classification
+  annotation "component/type",
+             description: "What the component is built as (executable, library, module, ...)",
+             title: "Component Type",
+             enum: %w[executable library module plugin frontend other],
+             filter: :word
+  annotation "component/role",
+             description: "What an executable or plugin does; set by hand",
+             title: "Component Role",
+             enum: %w[service cli job operator agent],
+             filter: :word
+
   # Availability
   annotation "availability/quality",
              description: "Service availability quality target per year",
@@ -122,6 +181,12 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              enum: ["no support", "support by dev", "support by ops", "support by api",
                     "self service support via a frontend"]
 
+  annotation "component/entrypoints",
+             description: "Comma-separated entry points (main packages or commands such as cmd/api), set by importers",
+             title: "Entry points",
+             sidebar: false,
+             filter: :list
+
   # Deployment (from ArgoCD/cluster)
   annotation "deployment/images",
              description: "Deployed container images",
@@ -129,20 +194,21 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
              sidebar: false,
              filter: :list
   annotation "deployment/chart",
-             description: "Deployed Helm chart name",
+             description: "Deployed Helm charts, comma separated",
              title: "Helm Chart",
              sidebar: false,
-             filter: :word
+             filter: :list
   annotation "deployment/namespace",
-             description: "Kubernetes namespace",
+             description: "Kubernetes namespaces, comma separated",
              title: "Namespace",
              sidebar: false,
-             filter: :word
+             filter: :list
   annotation "deployment/cluster",
-             description: "Target cluster name",
+             description: "Target clusters, comma separated",
              title: "Cluster",
-             filter: :word,
-             summary: true
+             filter: :list,
+             summary: true,
+             deprecated: "list the clusters as spec.servedBy.technologyServices"
 
   # Computed Annotations
   computed_annotation "repository/artifacts/total",
@@ -190,6 +256,14 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     end
   end
 
+  computed_annotation "component/dependents",
+                      title: "Dependents",
+                      description: "Number of components that depend directly on this one",
+                      type: Integer,
+                      sidebar: true do
+    count(incoming(:ApplicationComponent))
+  end
+
   computed_annotation "scc/language",
                       title: "Primary Language",
                       summary: true,
@@ -343,6 +417,7 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :realizedThrough, :technologyArtifacts, :TechnologyArtifact
   relation :realizedBy, :technologyComponents, :TechnologyNode
   relation :servedBy, :technologyComponents, :TechnologySystemSoftware
+  relation :servedBy, :technologyServices, :TechnologyService
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent

data/lib/archsight/resources/application_event.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# ApplicationEvent represents an application event: something that happens in an application and triggers or interrupts application behavior
+class Archsight::Resources::ApplicationEvent < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents an application event: something that happens in an application and triggers or interrupts application behavior.
+
+    ## ArchiMate Definition
+
+    **Layer:** Application
+    **Aspect:** Behavior
+
+    An event is something that happens and influences behavior. It does not last: it triggers or interrupts
+    processes and services. In the risk and security overlay of the Open Group paper (*Modeling Enterprise Risk
+    Management and Security with the ArchiMate Language*) a threat event and a loss event are events that carry a
+    type; set `event/type` to say which.
+
+    ## Usage
+
+    Use ApplicationEvent for events on the application level:
+
+    - Threat events and loss events of applications (an exploit of a service, a burst of failed logins, a data leak)
+    - Security alerts raised by an application
+    - Triggers of application services (a message arrives, a job is scheduled)
+
+    ## Event types
+
+    - `threat-event`: an event with the potential to harm an asset; it can trigger a loss event
+    - `attack`: a threat event caused by intentional malicious activity
+    - `loss-event`: an event that harms an asset (a hazard materialises, a vulnerability is exploited)
+    - `incident`: a loss event that has happened
+    - `opportunity-event`: an event that can add value
+    - `audit`, `scan`, `change`: events that produce assessments or alter the architecture
+    - `other`
+
+    Filter, group and query by `event/type`, `risk/domain` and `risk/category` to see, for example, every loss
+    event of a risk domain.
+
+    ## How it connects
+
+    - A threat event `triggers` a loss event or a process or service; threat and loss events may sit on different
+      layers (a technology event triggers an application or business event)
+    - `causedBy` the threat agent (an actor, component or node)
+    - `affects` the assets it harms
+    - A `MotivationDriver` (the threat) `triggers` it; a vulnerability `MotivationAssessment` `influences` it
+  MD
+
+  icon "bell-notification"
+  layer "application"
+
+  annotation "event/type",
+             description: "What kind of event this is (specialization of the event, see the risk and security overlay)",
+             enum: %w[threat-event attack loss-event incident opportunity-event audit scan change other],
+             filter: :word,
+             summary: true
+
+  annotation "event/severity",
+             description: "Severity of the event",
+             enum: %w[info low medium high critical],
+             filter: :word,
+             summary: true
+
+  annotation "event/occurred",
+             description: "When the event happened or is expected (ISO 8601 date or time)",
+             title: "Occurred",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :triggers, :applicationServices, :ApplicationService
+  relation :triggers, :applicationEvents, :ApplicationEvent
+  relation :triggers, :businessEvents, :BusinessEvent
+  relation :causedBy, :businessActors, :BusinessActor
+  relation :causedBy, :applicationComponents, :ApplicationComponent
+  relation :causedBy, :technologyNodes, :TechnologyNode
+  relation :affects, :applicationServices, :ApplicationService
+  relation :affects, :applicationComponents, :ApplicationComponent
+  relation :affects, :dataObjects, :DataObject
+end

data/lib/archsight/resources/application_service.rb

@@ -2,7 +2,7 @@
 
 # ApplicationService represents the high level application service that implements capabilities
 class Archsight::Resources::ApplicationService < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated, :backup
+  include_annotations :git, :architecture, :generated, :backup, :asset, :risk
 
   description <<~MD
     Represents a high-level application service that implements business capabilities.
@@ -20,10 +20,25 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
 
     Use ApplicationService to represent:
 
-    - Complete product offerings (ManagedKubernetes, DBaaS PostgreSQL)
+    - Behaviour software offers to a user or another system ("Payment Authorization", "Document Search")
     - Logical groupings of application components
     - Services exposed to business processes
     - APIs and their implementations as a cohesive unit
+
+    ## Choosing this kind
+
+    **Question:** What behaviour does software offer a consumer?
+    **Test:** It can be described without naming repositories, deployments or runtime objects, and has one owning actor.
+    **Name:** The function, not the technology or a deployment object ("Payment Authorization").
+
+    A component belongs to exactly one service. One service using another is `dependsOn` between the two services, not
+    the other service's components listed again; a service that many others use is modeled once. A service whose only component has the same name is a smell. See
+    the modeling guide, "Choosing the Kind".
+
+    ## Security and risk modelling
+
+    A service is an asset at risk (`asset/*` profile, protection needs) that loss events `affects`, a trigger target
+    for `ApplicationEvent`s, and the place where requirements are realized and evidenced.
   MD
 
   icon "cube"
@@ -212,6 +227,7 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   end
 
   relation :realizedThrough, :applicationComponents, :ApplicationComponent
+  relation :dependsOn, :applicationServices, :ApplicationService
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
   relation :realizes, :motivationConstraints, :MotivationConstraint

data/lib/archsight/resources/base.rb

@@ -35,12 +35,20 @@ module Archsight
       # A kind may mark at most this many annotations as summary (see Base.annotation)
       MAX_SUMMARY_ANNOTATIONS = 3
 
+      # The options `annotation` accepts (see Archsight::Annotations::Annotation)
+      ANNOTATION_OPTIONS = %i[description filter title format enum sidebar type summary editor validator unique
+                              deprecated default].freeze
+
       # Define an annotation using the Annotation class
       # `summary: true` marks it as a summary attribute: it is returned with every search hit of this kind.
-      def self.annotation(key, description: nil, filter: nil, title: nil, format: nil, enum: nil, sidebar: true,
-                          type: nil, summary: false, editor: true, validator: nil)
-        options = { description: description, filter: filter, title: title, format: format, enum: enum,
-                    sidebar: sidebar, type: type, summary: summary, editor: editor, validator: validator }
+      # `unique: true` makes it an identifier: its values (each element of a list) are unique among the resources
+      # of the kind, which `archsight lint` checks, and its values are shown as chips without links (not tags).
+      # `deprecated: "what to use instead"` keeps it working while `archsight lint` lists every use.
+      # `default: "value"` is the value of a resource that does not set it (see #apply_annotation_defaults!).
+      def self.annotation(key, **options)
+        unknown = options.keys - ANNOTATION_OPTIONS
+        raise ArgumentError, "unknown annotation option(s) #{unknown.join(", ")} for #{key}" if unknown.any?
+
         register_annotation(Archsight::Annotations::Annotation.new(key, options))
       end
 
@@ -143,8 +151,11 @@ module Archsight
         end
       end
 
+      # The layer of the kind, one of Archsight::Resources::LAYERS (default `other`)
       def self.layer(layer_name = nil)
         if layer_name
+          raise ArgumentError, "unknown layer #{layer_name.inspect} for #{name}" unless Archsight::Resources::LAYERS.include?(layer_name)
+
           @layer = layer_name
         else
           @layer || "other" # default layer
@@ -223,6 +234,26 @@ module Archsight
         @raw["metadata"]["annotations"][key] = value
       end
 
+      # Gives every annotation with a `default:` that the file does not set its default, in the annotations hash like
+      # a written value, so queries, filters and the page see it. The editor leaves these out (#defaulted?), so a
+      # save does not write them into the file.
+      def apply_annotation_defaults!
+        self.class.annotations.each do |annotation|
+          next if annotation.default.nil? || annotation.pattern? || annotations.key?(annotation.key)
+
+          defaulted = (@defaulted ||= []) #: Array[String]
+          defaulted << annotation.key
+          @raw["metadata"] ||= {}
+          @raw["metadata"]["annotations"] = @raw["metadata"]["annotations"] || {} #: Hash[String, untyped]
+          @raw["metadata"]["annotations"][annotation.key] = annotation.default
+        end
+      end
+
+      # Whether the value of the annotation is its default, not written in the file
+      def defaulted?(key)
+        @defaulted&.include?(key) || false
+      end
+
       # Get a computed annotation value from the cache
       # @param key [String] The annotation key
       # @return [Object, nil] The computed value or nil
@@ -338,7 +369,29 @@ module Archsight
 
       def merge!(inst)
         # NOTE: path reference is preserved from the original instance
-        @raw = Archsight::Helpers.deep_merge(@raw, inst.raw)
+        merged = Archsight::Helpers.deep_merge(@raw, inst.raw)
+        union_list_annotations!(merged, inst.raw)
+        @raw = merged
+      end
+
+      # Annotations hold strings, which replace each other on merge. The values of a list annotation (tags, aliases)
+      # are joined instead, so two documents of one resource can each add to it.
+      def union_list_annotations!(merged, other_raw)
+        mine = @raw.dig("metadata", "annotations")
+        theirs = other_raw.dig("metadata", "annotations")
+        return unless mine.is_a?(Hash) && theirs.is_a?(Hash)
+
+        theirs.each do |key, value|
+          next unless mine[key].is_a?(String) && value.is_a?(String)
+          next unless self.class.annotation_matching(key)&.list?
+
+          values = (split_list(mine[key]) + split_list(value)).uniq
+          merged["metadata"]["annotations"][key] = values.join(",")
+        end
+      end
+
+      def split_list(text)
+        text.split(/,|\n/).map(&:strip).reject(&:empty?)
       end
 
       # raise provides a helper for better error messages including current path and line no

data/lib/archsight/resources/business_actor.rb

@@ -2,7 +2,7 @@
 
 # BusinessActor represents teams or organizational units
 class Archsight::Resources::BusinessActor < Archsight::Resources::Base
-  include_annotations :git, :architecture, :generated
+  include_annotations :git, :architecture, :generated, :asset, :risk
 
   description <<~MD
     Represents a team, organizational unit, or external entity that performs business behavior.
@@ -25,6 +25,19 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
     - External vendors or partners
     - Support organizations
     - Cross-functional groups
+    - Customers and providers: the parties a `BusinessContract` is `agreedBy`
+    - The party behind a `MotivationStakeholder`: the stakeholder is `representedBy` it
+    - The team behind infrastructure: a `TechnologyDevice`, `TechnologyEquipment`, `TechnologyNode` or
+      `TechnologyCommunicationNetwork` is `ownedBy` the team that operates it, and a device, equipment or node is
+      `servedBy` the team it is dedicated to (a test server, a cluster partition)
+
+    ## Security and risk modelling
+
+    - **Threat agent:** an actor (also an external one, such as an attacker group or a supplier) can be the
+      `causedBy` of a threat or loss event.
+    - **Owner and executor:** actors own risks (`MotivationAssessment` `ownedBy`), policies and controls, directly or through a `BusinessRole` they `performedBy`.
+    - **Asset:** a supplier or a team can be an asset at risk; set the `asset/*` profile and `assesses` it from a
+      supplier assessment.
   MD
 
   icon "community"

data/lib/archsight/resources/business_contract.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# BusinessContract represents an agreement between a provider and a consumer
+class Archsight::Resources::BusinessContract < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents an agreement between a provider and a consumer: the rights and obligations both agreed to.
+
+    ## ArchiMate Definition
+
+    **Layer:** Business
+    **Aspect:** Passive Structure
+
+    A contract is a formal or informal specification of an agreement between a provider and a consumer that
+    specifies rights and obligations. It is a specialization of a business object. A product is accompanied by a
+    contract, and a contract can consist of parts.
+
+    ## Usage
+
+    Use BusinessContract to represent:
+
+    - Framework contracts with a customer
+    - Call-offs under a framework contract (an order for one more block of capacity)
+    - Service level agreements
+    - Amendments of a contract
+
+    A contract is a `BusinessContract`, not a `DataObject` and not text in a description: only then do the graph,
+    views and analyses see what it agrees, who agreed it and what delivered it.
+
+    ## How it connects
+
+    - A `BusinessProduct` `aggregates` the contract that comes with it
+    - It is `agreedBy` its parties: the actual organisations (the customer, the provider), not a generic role
+    - It is `composedOf` its parts: call-offs, SLAs and amendments, which are contracts themselves (no cycles)
+    - It `covers` what it obliges the provider to deliver: equipment, nodes, technology and application services
+    - It is `realizedThrough` the `ImplementationDeliverable` that fulfils it; the `ImplementationWorkPackage` that
+      `realizes` the deliverable `affects` the equipment it installs
+
+    The other side shows these as incoming relations: the contracts an actor agreed, what covers a piece of
+    equipment or a service, the contract a deliverable fulfils.
+  MD
+
+  icon "journal-page"
+  layer "business"
+
+  annotation "contract/type",
+             description: "What kind of contract this is",
+             enum: %w[framework call-off sla amendment other],
+             filter: :word,
+             summary: true
+  annotation "contract/reference",
+             description: "The contract number",
+             title: "Reference",
+             summary: true
+  annotation "contract/from",
+             description: "When the contract starts (ISO 8601 date or time)",
+             title: "From",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+  annotation "contract/until",
+             description: "When the contract ends (ISO 8601 date or time)",
+             title: "Until",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :agreedBy, :businessActors, :BusinessActor
+  relation :composedOf, :businessContracts, :BusinessContract
+  relation :covers, :technologyEquipment, :TechnologyEquipment
+  relation :covers, :technologyNodes, :TechnologyNode
+  relation :covers, :technologyServices, :TechnologyService
+  relation :covers, :applicationServices, :ApplicationService
+  relation :realizedThrough, :implementationDeliverables, :ImplementationDeliverable
+end