#49 — consumer-aliases name the upstream related resource

Convention refinement across PRs 1-3: aliases on assignments and on PRI's
owns relationships now identify the related resource each consumer is
part of (its domain role), not the slot/thing being received.

* avc sets :cvc, cvc sets :nni_group, uni sets :ntd on their assignments
* pri's owns relationships aliased :circuit (AVC) and :port (UNI)
* inheritance walks updated to follow the new aliases
* pool/metrics aggregations unaffected (still filter by `thing`)
* memories and moduledoc examples revised

Author: matt-beanland

CHANGELOG.md

@@ -34,7 +34,8 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
   * 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`.
 * NBN — NTD brings up assigned UNIs as `unis[]` via the `:port` assignment (issue #49 part 2).
-* NBN — NbnEthernet (PRI) brings up four characteristics surfacing the full delivery chain (issue #49 part 3): `avc` single-hop via the `:avc` owns relationship, `uni` single-hop via the `:uni` owns relationship, `cvc` two-hop via `:avc` then `:cvlan`, and `ntd` two-hop via `:uni` then `:port`. All singular.
+* NBN — NbnEthernet (PRI) brings up four characteristics surfacing the full delivery chain (issue #49 part 3): `avc` single-hop via the `:circuit` owns relationship, `uni` single-hop via the `:port` owns relationship, `cvc` two-hop via `:circuit` then `:cvc`, and `ntd` two-hop via `:port` then `:ntd`. All singular.
+* NBN — consumer-side aliases on assignments and relationships now name the **upstream related resource** the consumer is part of (its domain role), not the slot/thing being received: AVC sets `:cvc` on its cvlan assignment, CVC sets `:nni_group` on its svlan assignment, UNI sets `:ntd` on its port assignment; PRI's two `:owns` relationships are aliased `:circuit` (AVC) and `:port` (UNI). Inheritance walks use these consumer-aliases. Pool/metric aggregations are unaffected — they still filter by `thing`.
 * `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):

lib/diffo_example/calculations/inherited_characteristic_via_assignment.ex

@@ -27,7 +27,9 @@ defmodule DiffoExample.Calculations.InheritedCharacteristicViaAssignment do
     from this instance back to the source whose characteristic we want.
     Each step filters `AssignmentRelationship` by `target_id` and `alias`,
     then follows `source_id` to the next set of instances. The aliases are
-    the assignee's slot names, supplied when the assignment is made.
+    the **consumer's name for the upstream related resource** at each hop
+    (e.g. AVC names its CVC slot `:cvc`, CVC names its NniGroup slot
+    `:nni_group`) — set when the assignment is made.
   - `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`.
@@ -52,12 +54,12 @@ defmodule DiffoExample.Calculations.InheritedCharacteristicViaAssignment do
                 {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.
+      # AVC brings up its singular CVC via its :cvc consumer-alias on the
+      # cvlan assignment from the CVC. 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]}
+                 [via: [:cvc], characteristic_module: CvcCharacteristic, singular?: true]}
   """
   use Ash.Resource.Calculation
 

lib/diffo_example/calculations/inherited_characteristic_via_relationship.ex

@@ -27,13 +27,14 @@ defmodule DiffoExample.Calculations.InheritedCharacteristicViaRelationship do
     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`).
-  - `then_via:` *(optional)* — list of `AssignmentRelationship` aliases to
-    walk **after** the relationship hop. Each step walks back through the
-    target's incoming assignments (`target_id + alias` identity, so each
-    step has cardinality ≤1). Use this for mixed paths — one relationship
-    hop followed by one or more assignment hops — e.g. PRI's `:cvc`
-    bring-up: `:avc` owns relationship, then `:cvlan` assignment back to
-    the CVC.
+  - `then_via:` *(optional)* — list of consumer-alias atoms to walk back
+    via `AssignmentRelationship` **after** the relationship hop. Each step
+    walks back through the target's incoming assignments (`target_id +
+    alias` identity, so each step has cardinality ≤1). Aliases name the
+    upstream related resource each consumer is part of. Use this for mixed
+    paths — one relationship hop followed by one or more assignment hops
+    — e.g. PRI's `:cvc` bring-up: `:circuit` owns relationship, then `:cvc`
+    assignment back to the CVC.
   - `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
@@ -48,16 +49,19 @@ defmodule DiffoExample.Calculations.InheritedCharacteristicViaRelationship do
                 {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
                  [type: :contains, characteristic_module: NniCharacteristic]}
 
-      # PRI brings up the singular AVC it owns via the :avc alias.
+      # PRI brings up the singular AVC it owns — PRI calls this related
+      # resource :circuit (its domain role), set as the alias on PRI's
+      # owns relationship.
       calculate :avc, :map,
                 {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
-                 [alias: :avc, characteristic_module: AvcCharacteristic, singular?: true]}
+                 [alias: :circuit, characteristic_module: AvcCharacteristic, singular?: true]}
 
-      # PRI brings up the singular CVC two-hop — :avc owns relationship,
-      # then back via the AVC's incoming :cvlan assignment to the CVC.
+      # PRI brings up the singular CVC two-hop — :circuit owns relationship
+      # from PRI to AVC, then back via the AVC's :cvc consumer-alias
+      # assignment from CVC.
       calculate :cvc, :map,
                 {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
-                 [alias: :avc, then_via: [:cvlan],
+                 [alias: :circuit, then_via: [:cvc],
                   characteristic_module: CvcCharacteristic, singular?: true]}
   """
   use Ash.Resource.Calculation

lib/nbn/resources/avc.ex

@@ -98,26 +98,27 @@ defmodule DiffoExample.Nbn.Avc do
 
   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.
+    # AVC is part of — single-hop via the AVC's :cvc consumer-alias on its
+    # cvlan assignment from the CVC.
     calculate :cvc,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [
-                 via: [:cvlan],
+                 via: [:cvc],
                  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].
+    # AVC's :cvc alias to the CVC, then the CVC's :nni_group alias to its
+    # NniGroup. Two-hop via [:cvc, :nni_group].
     calculate :nni_group,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [
-                 via: [:cvlan, :svlan],
+                 via: [:cvc, :nni_group],
                  characteristic_module: DiffoExample.Nbn.NniGroupCharacteristic,
                  singular?: true
                ]} do

lib/nbn/resources/cvc.ex

@@ -112,13 +112,13 @@ defmodule DiffoExample.Nbn.Cvc do
 
   calculations do
     # The NniGroup characteristic value brought up from the singular
-    # NniGroup this CVC is assigned an svlan on — single-hop via the
-    # :svlan assignment.
+    # NniGroup this CVC is part of — single-hop via the CVC's :nni_group
+    # consumer-alias on its svlan assignment from the NniGroup.
     calculate :nni_group,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [
-                 via: [:svlan],
+                 via: [:nni_group],
                  characteristic_module: DiffoExample.Nbn.NniGroupCharacteristic,
                  singular?: true
                ]} do

lib/nbn/resources/nbn_ethernet.ex

@@ -95,52 +95,59 @@ defmodule DiffoExample.Nbn.NbnEthernet do
   end
 
   calculations do
-    # The singular AVC this access owns — single-hop via :avc owns relationship.
+    # PRI names its two owns relationships by the domain role each plays —
+    # `:circuit` for the AVC (Access Virtual Circuit) and `:port` for the
+    # UNI (the customer's port). Both are consumer-aliases on PRI's owns
+    # relationships, set at relate time.
+
+    # The singular AVC this access owns — single-hop via the :circuit owns relationship.
     calculate :avc,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
                [
-                 alias: :avc,
+                 alias: :circuit,
                  characteristic_module: DiffoExample.Nbn.AvcCharacteristic,
                  singular?: true
                ]} do
       public? true
     end
 
-    # The singular UNI this access owns — single-hop via :uni owns relationship.
+    # The singular UNI this access owns — single-hop via the :port owns relationship.
     calculate :uni,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
                [
-                 alias: :uni,
+                 alias: :port,
                  characteristic_module: DiffoExample.Nbn.UniCharacteristic,
                  singular?: true
                ]} do
       public? true
     end
 
-    # The singular CVC backing this access's AVC — two-hop via :avc owns
-    # relationship, then back via the AVC's incoming :cvlan assignment.
+    # The singular CVC backing this access's circuit — two-hop via the
+    # :circuit owns relationship, then back via the AVC's :cvc consumer-alias
+    # assignment to its CVC.
     calculate :cvc,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
                [
-                 alias: :avc,
-                 then_via: [:cvlan],
+                 alias: :circuit,
+                 then_via: [:cvc],
                  characteristic_module: DiffoExample.Nbn.CvcCharacteristic,
                  singular?: true
                ]} do
       public? true
     end
 
-    # The singular NTD this access's UNI plugs into — two-hop via :uni
-    # owns relationship, then back via the UNI's incoming :port assignment.
+    # The singular NTD this access's port plugs into — two-hop via the
+    # :port owns relationship, then back via the UNI's :ntd consumer-alias
+    # assignment to its NTD.
     calculate :ntd,
               :map,
               {DiffoExample.Calculations.InheritedCharacteristicViaRelationship,
                [
-                 alias: :uni,
-                 then_via: [:port],
+                 alias: :port,
+                 then_via: [:ntd],
                  characteristic_module: DiffoExample.Nbn.NtdCharacteristic,
                  singular?: true
                ]} do

test/nbn/nbn_ethernet_test.exs

@@ -186,14 +186,14 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
           ]
         })
 
-      # AVC takes a cvlan from CVC; UNI takes a port from NTD. Set explicit
-      # aliases so the inheritance walks (target_id + alias identity)
-      # resolve cleanly.
+      # AVC takes a cvlan from CVC; UNI takes a port from NTD. Consumer
+      # aliases name the upstream resource each is part of, so the
+      # inheritance walks (target_id + alias identity) resolve cleanly.
       {:ok, _} =
         Nbn.assign_cvlan(cvc, %{
           assignment: %Assignment{
             assignee_id: avc.id,
-            alias: :cvlan,
+            alias: :cvc,
             operation: :auto_assign
           }
         })
@@ -202,19 +202,21 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
         Nbn.assign_port(ntd, %{
           assignment: %Assignment{
             assignee_id: uni.id,
-            alias: :port,
+            alias: :ntd,
             operation: :auto_assign
           }
         })
 
-      # PRI owns the AVC and UNI
+      # PRI owns the AVC and UNI. Aliases name the role each related
+      # resource plays from PRI's perspective — the AVC is the :circuit,
+      # the UNI is the :port.
       {:ok, pri} = Nbn.build_nbn_ethernet(%{})
 
       {:ok, _} =
         Nbn.relate_nbn_ethernet(pri, %{
           relationships: [
-            %Relationship{id: avc.id, direction: :forward, type: :owns, alias: :avc},
-            %Relationship{id: uni.id, direction: :forward, type: :owns, alias: :uni}
+            %Relationship{id: avc.id, direction: :forward, type: :owns, alias: :circuit},
+            %Relationship{id: uni.id, direction: :forward, type: :owns, alias: :port}
           ]
         })
 
@@ -313,7 +315,7 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
         Nbn.assign_svlan(nni_group, %{
           assignment: %Assignment{
             assignee_id: cvc.id,
-            alias: :svlan,
+            alias: :nni_group,
             operation: :auto_assign
           }
         })
@@ -329,7 +331,7 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
         Nbn.assign_cvlan(cvc, %{
           assignment: %Assignment{
             assignee_id: avc.id,
-            alias: :cvlan,
+            alias: :cvc,
             operation: :auto_assign
           }
         })

test/nbn/show_neo4j_test.exs

@@ -55,7 +55,7 @@ defmodule DiffoExample.Nbn.ShowNeo4jTest do
           Nbn.assign_svlan(nni_group, %{
             assignment: %Assignment{
               assignee_id: cvc.id,
-              alias: :svlan,
+              alias: :nni_group,
               operation: :auto_assign
             }
           })
@@ -102,7 +102,7 @@ defmodule DiffoExample.Nbn.ShowNeo4jTest do
       Nbn.assign_cvlan(cvc1, %{
         assignment: %Assignment{
           assignee_id: avc.id,
-          alias: :cvlan,
+          alias: :cvc,
           operation: :auto_assign
         }
       })
@@ -214,7 +214,7 @@ defmodule DiffoExample.Nbn.ShowNeo4jTest do
       Nbn.assign_cvlan(cvc, %{
         assignment: %Assignment{
           assignee_id: avc.id,
-          alias: :cvlan,
+          alias: :cvc,
           operation: :auto_assign
         }
       })
@@ -223,19 +223,19 @@ defmodule DiffoExample.Nbn.ShowNeo4jTest do
       Nbn.assign_port(ntd, %{
         assignment: %Assignment{
           assignee_id: uni.id,
-          alias: :port,
+          alias: :ntd,
           operation: :auto_assign
         }
       })
 
-    # PRI owns AVC and UNI
+    # PRI owns AVC (named :circuit from PRI's view) and UNI (named :port).
     {:ok, pri} = Nbn.build_nbn_ethernet(%{})
 
     {:ok, _} =
       Nbn.relate_nbn_ethernet(pri, %{
         relationships: [
-          %Relationship{id: avc.id, direction: :forward, type: :owns, alias: :avc},
-          %Relationship{id: uni.id, direction: :forward, type: :owns, alias: :uni}
+          %Relationship{id: avc.id, direction: :forward, type: :owns, alias: :circuit},
+          %Relationship{id: uni.id, direction: :forward, type: :owns, alias: :port}
         ]
       })
 
@@ -290,7 +290,11 @@ defmodule DiffoExample.Nbn.ShowNeo4jTest do
 
       {:ok, _} =
         Nbn.assign_port(ntd, %{
-          assignment: %Assignment{assignee_id: uni.id, operation: :auto_assign}
+          assignment: %Assignment{
+            assignee_id: uni.id,
+            alias: :ntd,
+            operation: :auto_assign
+          }
         })
     end