Access — adopt consumer-alias-names-related-resource convention

Match the NBN convention from #49: alias on the consumer's assignment
names the upstream related resource it's part of, not the slot/thing
being received.

* Card sets :shelf on its slot assignment (was :slot)
* Path sets :card on its port assignment (was :port)
* Card.shelf walks via [:shelf]; Card.slot filters alias :shelf
* Path.card walks via [:card]; Path.shelf via [:card, :shelf]; Path.port filters alias :card
* Shelf.cards filters alias :shelf (was :slot)
* ShelfTotalPorts filters alias :shelf
* Tests updated; 54/54 pass

Author: matt-beanland

CHANGELOG.md

@@ -35,7 +35,7 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
   * 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 `: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`.
+* NBN and Access — 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. NBN: 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). Access: Card sets `:shelf` on its slot assignment, Path sets `:card` on its port assignment, and `Shelf.cards` filters on `alias: :shelf`. 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/access/calculations/shelf_total_ports.ex

@@ -7,9 +7,10 @@ defmodule DiffoExample.Access.Calculations.ShelfTotalPorts do
   Sums the `:ports` pool capacity across every card a shelf has assigned
   a slot to.
 
-  For each outgoing slot-assignment (alias `:slot`, source = shelf), looks
-  up the assigned card's `AssignableCharacteristic` for the `:ports` pool
-  and sums `(last - first + 1)` across all of them.
+  For each outgoing slot-assignment (cards consumer-alias their upstream
+  Shelf relationship as `:shelf`), looks up the assigned card's
+  `AssignableCharacteristic` for the `:ports` pool and sums
+  `(last - first + 1)` across all of them.
 
   Local-to-this-repo for now. Could in time become a more general
   diffo-side primitive (`SumPoolCapacityOfAssignees` or similar) once the
@@ -26,7 +27,7 @@ defmodule DiffoExample.Access.Calculations.ShelfTotalPorts do
     Enum.map(records, fn shelf ->
       assignments =
         Diffo.Provider.AssignmentRelationship
-        |> Ash.Query.filter_input(source_id: shelf.id, alias: :slot)
+        |> Ash.Query.filter_input(source_id: shelf.id, alias: :shelf)
         |> Ash.read!(domain: Diffo.Provider)
 
       Enum.reduce(assignments, 0, fn assignment, acc ->

lib/access/resources/card.ex

@@ -89,20 +89,21 @@ defmodule DiffoExample.Access.Card do
   end
 
   calculations do
-    # The shelf characteristic value brought up from the shelf this card is
-    # in — derived live via the :slot assignment.
+    # The shelf characteristic value brought up from the shelf this card
+    # is part of — Card's :shelf consumer-alias on its slot assignment
+    # from the Shelf.
     calculate :shelf,
               {:array, :map},
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
-               [via: [:slot], characteristic_module: DiffoExample.Access.ShelfCharacteristic]} do
+               [via: [:shelf], characteristic_module: DiffoExample.Access.ShelfCharacteristic]} do
       public? true
     end
 
-    # The slot number this card occupies on its shelf — the value of the
-    # shelf's :slots-pool assignment to this card.
+    # The slot number this card occupies on its shelf — the :value of
+    # the assignment Card aliases :shelf (its upstream Shelf).
     calculate :slot,
               {:array, :integer},
-              {Diffo.Provider.Calculations.FieldFromAssignment, [alias: :slot, field: :value]} do
+              {Diffo.Provider.Calculations.FieldFromAssignment, [alias: :shelf, field: :value]} do
       public? true
     end
   end

lib/access/resources/path.ex

@@ -77,29 +77,31 @@ defmodule DiffoExample.Access.Path do
 
   calculations do
     # The card characteristic value brought up from the card this path is
-    # assigned a port on — via the :port assignment.
+    # part of — Path's :card consumer-alias on its port assignment from
+    # the Card.
     calculate :card,
               {:array, :map},
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
-               [via: [:port], characteristic_module: DiffoExample.Access.CardCharacteristic]} do
+               [via: [:card], characteristic_module: DiffoExample.Access.CardCharacteristic]} do
       public? true
     end
 
-    # The port number this path occupies on its card — the value of the
-    # card's :ports-pool assignment to this path.
+    # The port number this path occupies on its card — the :value of the
+    # assignment Path aliases :card (its upstream Card).
     calculate :port,
               {:array, :integer},
-              {Diffo.Provider.Calculations.FieldFromAssignment, [alias: :port, field: :value]} do
+              {Diffo.Provider.Calculations.FieldFromAssignment, [alias: :card, field: :value]} do
       public? true
     end
 
-    # The shelf characteristic value brought up transitively — port to the
-    # card, then the card's slot to its shelf. Two-hop via [:port, :slot].
+    # The shelf characteristic value brought up transitively — Path's
+    # :card alias to the Card, then the Card's :shelf alias to its Shelf.
+    # Two-hop via [:card, :shelf].
     calculate :shelf,
               {:array, :map},
               {DiffoExample.Calculations.InheritedCharacteristicViaAssignment,
                [
-                 via: [:port, :slot],
+                 via: [:card, :shelf],
                  characteristic_module: DiffoExample.Access.ShelfCharacteristic
                ]} do
       public? true

lib/access/resources/shelf.ex

@@ -96,7 +96,7 @@ defmodule DiffoExample.Access.Shelf do
     calculate :cards,
               {:array, :map},
               {DiffoExample.Calculations.ReverseInheritedCharacteristic,
-               [alias: :slot, characteristic_module: DiffoExample.Access.CardCharacteristic]} do
+               [alias: :shelf, characteristic_module: DiffoExample.Access.CardCharacteristic]} do
       public? true
     end
 

test/access/path_test.exs

@@ -104,11 +104,12 @@ defmodule DiffoExample.Access.PathTest do
     # now assign a port from a line card
     [_dslam, line_card] = create_dslam_with_line_card("QDONC-0001", tl(places), parties)
 
-    # path-as-assignee names its slot :port when requesting the port-assignment
-    # from the line card. This alias lets the InheritedCharacteristic calc
-    # traverse path → port → card (and transitively card → slot → shelf).
+    # path-as-assignee names its upstream Card relationship :card when
+    # requesting the port-assignment. The consumer-alias names the
+    # related resource, letting the inheritance calc traverse path → :card
+    # → card (and transitively card → :shelf → shelf).
     Access.assign_port!(line_card, %{
-      assignment: %Assignment{assignee_id: path.id, alias: :port, operation: :auto_assign}
+      assignment: %Assignment{assignee_id: path.id, alias: :card, operation: :auto_assign}
     })
 
     # 5 cables each assigned a pair to the path, plus 1 line card assigned a port
@@ -245,10 +246,11 @@ defmodule DiffoExample.Access.PathTest do
         ]
       })
 
-    # card-as-assignee names its slot :slot when requesting; alias lets
-    # downstream calculations traverse the assignment by name.
+    # card-as-assignee names its upstream Shelf relationship :shelf when
+    # requesting the slot-assignment; consumer-aliases let downstream calcs
+    # traverse by relationship.
     Access.assign_slot!(shelf, %{
-      assignment: %Assignment{assignee_id: card.id, alias: :slot, operation: :auto_assign}
+      assignment: %Assignment{assignee_id: card.id, alias: :shelf, operation: :auto_assign}
     })
 
     [shelf, card]

test/access/shelf_test.exs

@@ -180,15 +180,16 @@ defmodule DiffoExample.Access.ShelfTest do
         ]
       })
 
-    # Each card-as-assignee names its slot :slot when requesting.
+    # Each card-as-assignee names its upstream Shelf relationship :shelf
+    # when requesting.
     {:ok, _shelf} =
       Access.assign_slot(shelf, %{
-        assignment: %Assignment{assignee_id: card_a.id, alias: :slot, operation: :auto_assign}
+        assignment: %Assignment{assignee_id: card_a.id, alias: :shelf, operation: :auto_assign}
       })
 
     {:ok, shelf} =
       Access.assign_slot(shelf, %{
-        assignment: %Assignment{assignee_id: card_b.id, alias: :slot, operation: :auto_assign}
+        assignment: %Assignment{assignee_id: card_b.id, alias: :shelf, operation: :auto_assign}
       })
 
     # Shelf brings up its cards (in slot order) and aggregates total ports.