#49 part 1 — AVC, CVC, NniGroup characteristic inheritance and metrics

* AVC inherits CVC via :cvlan (single-hop) and NniGroup via [:cvlan, :svlan] (two-hop) — singular
* CVC inherits NniGroup via :svlan; new :metrics characteristic with avcs_count, avcs_total_bandwidth
* NniGroup new :metrics with cvcs/nnis counts and totals, plus utilization
* NniGroup new :nnis calc — brings up each comprised NNI's typed value via :contains relationship
* New InheritedCharacteristicViaAssignment (renamed) and InheritedCharacteristicViaRelationship sibling calcs
* BandwidthProfile.downstream/1 maps profile atoms to Mbps
* 3 new tests, 52/52 pass

Author: matt-beanland

CHANGELOG.md

@@ -26,6 +26,17 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
 * `DslAccess.qualify_result` now transitions to `:feasibilityChecked` — restores correct TMF form following [diffo#168](https://github.com/diffo-dev/diffo/pull/168) broadening the Assigner lifecycle gate to include `:feasibilityChecked`
 * `Util.summarise_characteristics/2` no longer called from tests — typed characteristic + pool records now surface in TMF JSON by default ([diffo#169](https://github.com/diffo-dev/diffo/pull/169)). The projection function is retained in [lib/diffo_example/util.ex](lib/diffo_example/util.ex) for future projection demonstrations. Expected JSON strings updated across `cable`, `card`, `cable`, `path`, `shelf`, `dsl_access`, `nbn_ethernet` tests to reflect the real typed/pool surfacing
 
+### Features:
+* NBN — AVC, CVC, NniGroup characteristic inheritance and metrics (issue #49):
+  * AVC inherits the upstream CVC's `cvc` characteristic via the `:cvlan` assignment (single-hop), and the NniGroup's `nni_group` characteristic transitively via `[:cvlan, :svlan]` (two-hop).
+  * CVC inherits the upstream NniGroup's `nni_group` characteristic via the `:svlan` assignment.
+  * New `cvc_metrics` characteristic on CVC carries `avcs_count` and `avcs_total_bandwidth` aggregated live over assigned AVCs.
+  * New `nni_group_metrics` characteristic on NniGroup carries `cvcs_count`/`cvcs_total_bandwidth` (demand), `nnis_count`/`nnis_total_bandwidth` (capacity), and `utilization = cvcs_total_bandwidth / nnis_total_bandwidth`.
+* `BandwidthProfile.downstream/1` — atom-to-Mbps mapping used by the metrics aggregation. CVCs are treated as symmetric capacity in this model (satellite asymmetry ignored).
+
+### Refactors (continued):
+* `DiffoExample.Calculations.InheritedCharacteristic` renamed to `InheritedCharacteristicViaAssignment` to make room for a future `InheritedCharacteristicViaRelationship` sibling (the latter lands in the PRI bring-up work).
+
 ## [v0.2.2](https://github.com/diffo-dev/diffo/compare/v0.2.1..v0.2.2) (2026-05-21)
 
 ### Maintenance:

lib/access/resources/card.ex

@@ -93,7 +93,7 @@ defmodule DiffoExample.Access.Card do
     # in — derived live via the :slot assignment.
     calculate :shelf,
               {:array, :map},
-              {DiffoExample.Calculations.InheritedCharacteristic,
+              {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [via: [:slot], characteristic_module: DiffoExample.Access.ShelfCharacteristic]} do
       public? true
     end

lib/access/resources/path.ex

@@ -80,7 +80,7 @@ defmodule DiffoExample.Access.Path do
     # assigned a port on — via the :port assignment.
     calculate :card,
               {:array, :map},
-              {DiffoExample.Calculations.InheritedCharacteristic,
+              {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [via: [:port], characteristic_module: DiffoExample.Access.CardCharacteristic]} do
       public? true
     end
@@ -97,7 +97,7 @@ defmodule DiffoExample.Access.Path do
     # card, then the card's slot to its shelf. Two-hop via [:port, :slot].
     calculate :shelf,
               {:array, :map},
-              {DiffoExample.Calculations.InheritedCharacteristic,
+              {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [
                  via: [:port, :slot],
                  characteristic_module: DiffoExample.Access.ShelfCharacteristic

…calculations/inherited_characteristic.ex …herited_characteristic_via_assignment.exlib/diffo_example/calculations/inherited_characteristic.ex renamed to lib/diffo_example/calculations/inherited_characteristic_via_assignment.ex lib/diffo_example/calculations/inherited_characteristic.ex renamed to lib/diffo_example/calculations/inherited_characteristic_via_assignment.ex

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: MIT
 
-defmodule DiffoExample.Calculations.InheritedCharacteristic do
+defmodule DiffoExample.Calculations.InheritedCharacteristicViaAssignment do
   @moduledoc """
   Brings up a typed characteristic value from an assignment-source instance.
 
@@ -11,10 +11,15 @@ defmodule DiffoExample.Calculations.InheritedCharacteristic do
   `AssignmentRelationship` by alias to reach source instances, then queries
   the typed characteristic resource on each source and returns its `.value`.
 
-  Local-to-this-repo for now. Worth yarning upstream as a diffo-side
-  `inherited_characteristic` DSL declaration backed by a
-  `Diffo.Provider.Calculations.InheritedCharacteristic` calc, sitting
-  alongside the existing inherited-place and inherited-party machinery.
+  Sibling to `InheritedCharacteristicViaRelationship`, which performs the
+  analogous traversal over `DefinedSimpleRelationship` edges (forward,
+  source → target). Pick the right calc by the kind of edge being
+  traversed — assignment vs. relationship.
+
+  Local-to-this-repo for now. Worth yarning upstream as a pair of
+  diffo-side DSL declarations backed by analogous calcs in the provider
+  extension, sitting alongside the existing inherited-place and
+  inherited-party machinery.
 
   ## Options
 
@@ -26,20 +31,33 @@ defmodule DiffoExample.Calculations.InheritedCharacteristic do
   - `characteristic_module:` *(required)* — the typed characteristic Ash
     resource on the final source (e.g. `ShelfCharacteristic`). The calc
     queries this resource by `instance_id` and returns the `.value`.
+  - `singular?:` *(optional, default `false`)* — when `true`, unwraps the
+    result to a single value (or `nil`) rather than a list. Safe whenever
+    every hop in `via:` traverses an `AssignmentRelationship` with identity
+    `[:target_id, :alias]` — that guarantees ≤1 source per step, so the
+    walk yields at most one value. Declare the calc's return type as `:map`
+    (rather than `{:array, :map}`) when using this option.
 
   ## Example
 
       # Card brings up its shelf's typed characteristic via the slot
       # assignment the shelf made to it (alias :slot on the incoming
       # AssignmentRelationship).
-      calculate :shelf, :map,
-                {DiffoExample.Calculations.InheritedCharacteristic,
+      calculate :shelf, {:array, :map},
+                {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                  [via: [:slot], characteristic_module: ShelfCharacteristic]}
 
       # Path brings up the same via a two-hop chain — port-then-slot.
-      calculate :shelf, :map,
-                {DiffoExample.Calculations.InheritedCharacteristic,
+      calculate :shelf, {:array, :map},
+                {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                  [via: [:port, :slot], characteristic_module: ShelfCharacteristic]}
+
+      # AVC brings up its singular CVC via :cvlan — AssignmentRelationship
+      # identity guarantees ≤1 source, so we declare :map and ask the calc
+      # to unwrap.
+      calculate :cvc, :map,
+                {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
+                 [via: [:cvlan], characteristic_module: CvcCharacteristic, singular?: true]}
   """
   use Ash.Resource.Calculation
 
@@ -50,6 +68,7 @@ defmodule DiffoExample.Calculations.InheritedCharacteristic do
   def calculate(records, opts, _context) do
     via = Keyword.fetch!(opts, :via)
     characteristic_module = Keyword.fetch!(opts, :characteristic_module)
+    singular? = Keyword.get(opts, :singular?, false)
 
     Enum.map(records, fn record ->
       final_ids =
@@ -62,13 +81,16 @@ defmodule DiffoExample.Calculations.InheritedCharacteristic do
           end)
         end)
 
-      Enum.flat_map(final_ids, fn id ->
-        characteristic_module
-        |> Ash.Query.filter_input(instance_id: id)
-        |> Ash.Query.load(:value)
-        |> Ash.read!()
-        |> Enum.map(& &1.value)
-      end)
+      values =
+        Enum.flat_map(final_ids, fn id ->
+          characteristic_module
+          |> Ash.Query.filter_input(instance_id: id)
+          |> Ash.Query.load(:value)
+          |> Ash.read!()
+          |> Enum.map(& &1.value)
+        end)
+
+      if singular?, do: List.first(values), else: values
     end)
   end
 end

lib/diffo_example/calculations/inherited_characteristic_via_relationship.ex

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Calculations.InheritedCharacteristicViaRelationship do
+  @moduledoc """
+  Brings up typed characteristic values from target instances reached via
+  forward `Diffo.Provider.Relationship` edges (source → target), optionally
+  filtered by `type:` and/or `alias:`.
+
+  Sibling to `InheritedCharacteristicViaAssignment`, which performs the
+  analogous traversal over `AssignmentRelationship` edges. Pick the right
+  calc by the kind of edge being traversed — relationship vs. assignment.
+
+  Use this when the edge between the consuming instance and the target was
+  created by a `:relate` action (a `Provider.Relationship` record). Use
+  `InheritedCharacteristicViaAssignment` when the edge was created by the
+  Assigner (an `AssignmentRelationship` record).
+
+  Local-to-this-repo for now. Worth yarning upstream alongside the
+  assignment variant as a pair of provider-side calcs.
+
+  ## Options
+
+  - `characteristic_module:` *(required)* — the typed characteristic Ash
+    resource on each target (e.g. `NniCharacteristic`). The calc queries
+    this resource by `instance_id` and returns the `.value`.
+  - `type:` *(optional)* — filter relationships by type atom (e.g. `:contains`).
+  - `alias:` *(optional)* — filter relationships by alias atom (e.g. `:avc`).
+  - `singular?:` *(optional, default `false`)* — unwrap to a single value
+    when the consumer expects a 1-cardinality result (e.g. PRI's `:avc` or
+    `:uni` aliased owns-relationship). Declare the calc's return type as
+    `:map` (rather than `{:array, :map}`) when using this option.
+
+  ## Examples
+
+      # NniGroup brings up the typed characteristic of every NNI it
+      # comprises — forward traversal of :contains relationships, returns
+      # a list of NniCharacteristic values.
+      calculate :nnis, {:array, :map},
+                {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
+                 [type: :contains, characteristic_module: NniCharacteristic]}
+
+      # PRI brings up the singular AVC it owns via the :avc alias.
+      calculate :avc, :map,
+                {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
+                 [alias: :avc, characteristic_module: AvcCharacteristic, singular?: true]}
+  """
+  use Ash.Resource.Calculation
+  require Ash.Query
+
+  @impl true
+  def load(_query, _opts, _context), do: []
+
+  @impl true
+  def calculate(records, opts, _context) do
+    characteristic_module = Keyword.fetch!(opts, :characteristic_module)
+    type_filter = Keyword.get(opts, :type)
+    alias_filter = Keyword.get(opts, :alias)
+    singular? = Keyword.get(opts, :singular?, false)
+
+    Enum.map(records, fn record ->
+      target_ids =
+        Diffo.Provider.Relationship
+        |> filter_relationships(record.id, type_filter, alias_filter)
+        |> Ash.read!(domain: Diffo.Provider)
+        |> Enum.map(& &1.target_id)
+
+      values =
+        Enum.flat_map(target_ids, fn id ->
+          characteristic_module
+          |> Ash.Query.filter_input(instance_id: id)
+          |> Ash.Query.load(:value)
+          |> Ash.read!()
+          |> Enum.map(& &1.value)
+        end)
+
+      if singular?, do: List.first(values), else: values
+    end)
+  end
+
+  defp filter_relationships(query, source_id, nil, nil),
+    do: Ash.Query.filter_input(query, source_id: source_id)
+
+  defp filter_relationships(query, source_id, type, nil),
+    do: Ash.Query.filter_input(query, source_id: source_id, type: type)
+
+  defp filter_relationships(query, source_id, nil, alias_name),
+    do: Ash.Query.filter_input(query, source_id: source_id, alias: alias_name)
+
+  defp filter_relationships(query, source_id, type, alias_name),
+    do: Ash.Query.filter_input(query, source_id: source_id, type: type, alias: alias_name)
+end

lib/nbn/nbn.ex

@@ -27,7 +27,9 @@ defmodule DiffoExample.Nbn do
   alias DiffoExample.Nbn.Rsp
   alias DiffoExample.Nbn.AvcCharacteristic
   alias DiffoExample.Nbn.CvcCharacteristic
+  alias DiffoExample.Nbn.CvcMetrics
   alias DiffoExample.Nbn.NniGroupCharacteristic
+  alias DiffoExample.Nbn.NniGroupMetrics
   alias DiffoExample.Nbn.NniCharacteristic
   alias DiffoExample.Nbn.NtdCharacteristic
   alias DiffoExample.Nbn.UniCharacteristic
@@ -220,7 +222,9 @@ defmodule DiffoExample.Nbn do
 
     resource AvcCharacteristic
     resource CvcCharacteristic
+    resource CvcMetrics
     resource NniGroupCharacteristic
+    resource NniGroupMetrics
     resource NniCharacteristic
     resource NtdCharacteristic
     resource UniCharacteristic

lib/nbn/resources/avc.ex

@@ -96,6 +96,35 @@ defmodule DiffoExample.Nbn.Avc do
     end
   end
 
+  calculations do
+    # The CVC characteristic value brought up from the singular CVC this
+    # AVC is assigned a cvlan on — single-hop via the :cvlan assignment.
+    calculate :cvc,
+              :map,
+              {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
+               [
+                 via: [:cvlan],
+                 characteristic_module: DiffoExample.Nbn.CvcCharacteristic,
+                 singular?: true
+               ]} do
+      public? true
+    end
+
+    # The singular NniGroup characteristic value brought up transitively —
+    # cvlan to the CVC, then the CVC's svlan to its NniGroup. Two-hop via
+    # [:cvlan, :svlan].
+    calculate :nni_group,
+              :map,
+              {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
+               [
+                 via: [:cvlan, :svlan],
+                 characteristic_module: DiffoExample.Nbn.NniGroupCharacteristic,
+                 singular?: true
+               ]} do
+      public? true
+    end
+  end
+
   def identifier() do
     DiffoExample.Nbn.Util.identifier("AVC")
   end

lib/nbn/resources/characteristic_values/cvc_metrics.ex

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.CvcMetrics do
+  @moduledoc """
+  Local metrics characteristic for a CVC — `avcs_count` and
+  `avcs_total_bandwidth` aggregated live across the AVCs the CVC has
+  assigned a cvlan to. Not inheritable.
+  """
+  use Ash.Resource,
+    fragments: [Diffo.Provider.BaseCharacteristic],
+    domain: DiffoExample.Nbn
+
+  resource do
+    description "Live metrics for a CVC — count and total downstream bandwidth across its assigned AVCs"
+    plural_name :cvc_metrics
+  end
+
+  calculations do
+    calculate :value,
+              Diffo.Type.CharacteristicValue,
+              DiffoExample.Nbn.CvcMetrics.ValueCalculation do
+      public? true
+    end
+  end
+
+  preparations do
+    prepare build(load: [:value])
+  end
+
+  jason do
+    pick [:name, :value]
+    compact true
+  end
+end
+
+defmodule DiffoExample.Nbn.CvcMetrics.Value do
+  @moduledoc false
+  use Ash.TypedStruct, extensions: [AshJason.TypedStruct]
+
+  jason do
+    pick [:avcs_count, :avcs_total_bandwidth]
+    compact true
+    rename avcs_count: "avcsCount", avcs_total_bandwidth: "avcsTotalBandwidth"
+  end
+
+  typed_struct do
+    field :avcs_count, :integer
+    field :avcs_total_bandwidth, :integer
+  end
+end
+
+defmodule DiffoExample.Nbn.CvcMetrics.ValueCalculation do
+  @moduledoc false
+  use Ash.Resource.Calculation
+
+  require Ash.Query
+
+  alias DiffoExample.Nbn.AvcCharacteristic
+  alias DiffoExample.Nbn.BandwidthProfile
+  alias DiffoExample.Nbn.CvcMetrics
+
+  @impl true
+  def load(_, _, _), do: []
+
+  @impl true
+  def calculate(records, _, _) do
+    Enum.map(records, fn r ->
+      # AVCs the CVC has assigned a cvlan to live on the target side of
+      # outgoing AssignmentRelationships sourced from this CVC's :cvlan
+      # pool. Filter by `thing` (the pool's thing name) rather than `alias`
+      # — alias is the consumer's slot name and may be unset.
+      avc_ids =
+        Diffo.Provider.AssignmentRelationship
+        |> Ash.Query.filter_input(source_id: r.instance_id, thing: :cvlan)
+        |> Ash.read!(domain: Diffo.Provider)
+        |> Enum.map(& &1.target_id)
+
+      avcs =
+        Enum.flat_map(avc_ids, fn id ->
+          AvcCharacteristic
+          |> Ash.Query.filter_input(instance_id: id)
+          |> Ash.read!()
+        end)
+
+      %CvcMetrics.Value{
+        avcs_count: length(avcs),
+        avcs_total_bandwidth:
+          Enum.reduce(avcs, 0, fn avc, acc ->
+            acc + BandwidthProfile.downstream(avc.bandwidth_profile)
+          end)
+      }
+    end)
+  end
+end