#49 part 2 — NTD brings up assigned UNIs as unis[]

* NTD :unis calc — reverse-inherits each assigned UNI's typed value via :port
* ReverseInheritedCharacteristic extended with thing: filter (source-side principle)
* New test/nbn/show_neo4j_test.exs — sync, non-sandboxed exploration module that builds the NBN graph in real Neo4j for browser inspection. Both prior :show_json tests moved here and re-tagged :show_neo4j
* DataCase reverted to its original shape — sandbox isolates without needing per-module wipes
* 1 new sandboxed test, 53/53 pass

Author: matt-beanland

CHANGELOG.md

@@ -28,14 +28,17 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
 
 ### 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.
+  * 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). Both singular.
+  * CVC inherits the upstream NniGroup's `nni_group` characteristic via the `:svlan` assignment (singular).
+  * NniGroup brings up the typed value of every comprised NNI as `nnis[]` via the `:contains` relationship.
   * 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).
 * `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).
+* `DiffoExample.Calculations.InheritedCharacteristic` renamed to `InheritedCharacteristicViaAssignment`; new sibling `InheritedCharacteristicViaRelationship` traverses `Provider.Relationship` edges (forward source → target). Both calcs accept `singular?:` to unwrap to a single value where graph identity guarantees ≤1 result.
+* `ReverseInheritedCharacteristic` extended with a `thing:` filter option, complementing the existing `alias:` filter. Source-side aggregations should prefer `thing:` since it's always set from the pool DSL — see the assignment-direction-asymmetry rationale.
 
 ## [v0.2.2](https://github.com/diffo-dev/diffo/compare/v0.2.1..v0.2.2) (2026-05-21)
 

lib/diffo_example/calculations/reverse_inherited_characteristic.ex

@@ -26,19 +26,34 @@ defmodule DiffoExample.Calculations.ReverseInheritedCharacteristic do
 
   ## Options
 
-  - `alias:` *(optional)* — filter outgoing assignments by alias (the
-    assignee's slot name). When omitted, all outgoing assignments are
-    included.
   - `characteristic_module:` *(required)* — the typed characteristic Ash
     resource on each assignee (e.g. `CardCharacteristic`).
+  - `alias:` *(optional)* — filter outgoing assignments by alias (the
+    assignee's slot name). Use when every consumer follows the same
+    aliasing convention.
+  - `thing:` *(optional)* — filter outgoing assignments by `thing` (the
+    pool's thing name, e.g. `:slot`, `:port`). Always set from the pool
+    DSL declaration, so this is more robust than `alias:` when consumers
+    don't reliably name their slots. See `[[assignment-direction-asymmetry]]`.
 
-  ## Example
+  Specify either `alias:` or `thing:` (or both); omitting both includes
+  every outgoing assignment from this instance.
+
+  ## Examples
 
       # Shelf brings up the card characteristic from every card it's
-      # assigned a slot to, ordered by slot number.
+      # assigned a slot to, ordered by slot number. Cards-as-assignees
+      # name their slot :slot when requesting.
       calculate :cards, {:array, :map},
                 {DiffoExample.Calculations.ReverseInheritedCharacteristic,
                  [alias: :slot, characteristic_module: CardCharacteristic]}
+
+      # NTD brings up the UNI characteristic from every UNI it's assigned
+      # a port to. The UNIs may not have set an alias on their request,
+      # so filter by `thing` from the :ports pool declaration.
+      calculate :unis, {:array, :map},
+                {DiffoExample.Calculations.ReverseInheritedCharacteristic,
+                 [thing: :port, characteristic_module: UniCharacteristic]}
   """
   use Ash.Resource.Calculation
 
@@ -48,12 +63,13 @@ defmodule DiffoExample.Calculations.ReverseInheritedCharacteristic do
   @impl true
   def calculate(records, opts, _context) do
     alias_filter = Keyword.get(opts, :alias)
+    thing_filter = Keyword.get(opts, :thing)
     characteristic_module = Keyword.fetch!(opts, :characteristic_module)
 
     Enum.map(records, fn record ->
       assignments =
         Diffo.Provider.AssignmentRelationship
-        |> filter_outgoing(record.id, alias_filter)
+        |> filter_outgoing(record.id, alias_filter, thing_filter)
         |> Ash.Query.sort(value: :asc)
         |> Ash.read!(domain: Diffo.Provider)
 
@@ -67,9 +83,20 @@ defmodule DiffoExample.Calculations.ReverseInheritedCharacteristic do
     end)
   end
 
-  defp filter_outgoing(query, source_id, nil),
-    do: query |> Ash.Query.filter_input(source_id: source_id)
+  defp filter_outgoing(query, source_id, nil, nil),
+    do: Ash.Query.filter_input(query, source_id: source_id)
+
+  defp filter_outgoing(query, source_id, alias_filter, nil),
+    do: Ash.Query.filter_input(query, source_id: source_id, alias: alias_filter)
+
+  defp filter_outgoing(query, source_id, nil, thing_filter),
+    do: Ash.Query.filter_input(query, source_id: source_id, thing: thing_filter)
 
-  defp filter_outgoing(query, source_id, alias_filter),
-    do: query |> Ash.Query.filter_input(source_id: source_id, alias: alias_filter)
+  defp filter_outgoing(query, source_id, alias_filter, thing_filter),
+    do:
+      Ash.Query.filter_input(query,
+        source_id: source_id,
+        alias: alias_filter,
+        thing: thing_filter
+      )
 end

lib/nbn/resources/ntd.ex

@@ -115,4 +115,18 @@ defmodule DiffoExample.Nbn.Ntd do
       change Diffo.Provider.Changes.Relate
     end
   end
+
+  calculations do
+    # The UNI characteristic value of every UNI this NTD has assigned a
+    # port to — reverse traversal of outgoing :port AssignmentRelationships
+    # sourced from this NTD. Low cardinality (typical NTD has a handful of
+    # ports). Filter by `thing` (the pool's thing name) rather than `alias`
+    # — see assignment-direction-asymmetry memory.
+    calculate :unis,
+              {:array, :map},
+              {DiffoExample.Calculations.ReverseInheritedCharacteristic,
+               [thing: :port, characteristic_module: DiffoExample.Nbn.UniCharacteristic]} do
+      public? true
+    end
+  end
 end

test/nbn/nbn_ethernet_test.exs

@@ -19,150 +19,6 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
   alias Diffo.Provider.Assignment
   alias Diffo.Provider.Instance.Relationship
 
-  @tag :show_json
-  test "show AVC, CVC, NniGroup as JSON (run with `mix test --only show_json`)" do
-    {:ok, nni_group} = Nbn.build_nni_group(%{})
-
-    {:ok, nni_group} =
-      Nbn.define_nni_group(nni_group, %{
-        characteristic_value_updates: [
-          nni_group: [group_name: "SYD-POI-01", location: "Sydney Olympic Park"],
-          svlans: [first: 1, last: 4000, assignable_type: "svlan"]
-        ]
-      })
-
-    # Two CVCs assigned svlans from this NniGroup
-    cvc_ids =
-      for bandwidth <- [400, 600] do
-        {:ok, cvc} = Nbn.build_cvc(%{})
-
-        {:ok, _} =
-          Nbn.define_cvc(cvc, %{
-            characteristic_value_updates: [
-              cvc: [bandwidth: bandwidth],
-              cvlans: [first: 1, last: 4000, assignable_type: "cvlan"]
-            ]
-          })
-
-        {:ok, _} =
-          Nbn.assign_svlan(nni_group, %{
-            assignment: %Assignment{
-              assignee_id: cvc.id,
-              alias: :svlan,
-              operation: :auto_assign
-            }
-          })
-
-        cvc.id
-      end
-
-    # Two NNIs comprised by this NniGroup — realistic capacities so
-    # utilization comes out in the 0–1 range we expect operationally.
-    nni_ids =
-      for {port_id, capacity} <- [{"SYD-01-ETH-1", 10000}, {"SYD-01-ETH-2", 10000}] do
-        {:ok, nni} = Nbn.build_nni(%{})
-
-        {:ok, _} =
-          Nbn.define_nni(nni, %{
-            characteristic_value_updates: [
-              nni: [port_id: port_id, capacity: capacity]
-            ]
-          })
-
-        nni.id
-      end
-
-    {:ok, _} =
-      Nbn.relate_nni_group(nni_group, %{
-        relationships:
-          Enum.map(nni_ids, fn id ->
-            %Relationship{id: id, direction: :forward, type: :contains}
-          end)
-      })
-
-    # One AVC assigned a cvlan from the first CVC
-    cvc1_id = hd(cvc_ids)
-    {:ok, cvc1} = Nbn.get_cvc_by_id(cvc1_id)
-
-    {:ok, avc} = Nbn.build_avc(%{})
-
-    {:ok, _} =
-      Nbn.define_avc(avc, %{
-        characteristic_value_updates: [avc: [bandwidth_profile: :home_fast]]
-      })
-
-    {:ok, _} =
-      Nbn.assign_cvlan(cvc1, %{
-        assignment: %Assignment{
-          assignee_id: avc.id,
-          alias: :cvlan,
-          operation: :auto_assign
-        }
-      })
-
-    # Reload all three with their inheritance calcs / metrics loaded
-    {:ok, avc} = Nbn.get_avc_by_id(avc.id, load: [:cvc, :nni_group])
-    {:ok, cvc} = Nbn.get_cvc_by_id(cvc1_id, load: [:nni_group])
-    {:ok, nni_group} = Nbn.get_nni_group_by_id(nni_group.id, load: [:nnis])
-
-    cvc_metrics =
-      DiffoExample.Nbn.CvcMetrics
-      |> Ash.Query.filter_input(instance_id: cvc.id)
-      |> Ash.Query.load(:value)
-      |> Ash.read_one!()
-
-    nni_group_metrics =
-      DiffoExample.Nbn.NniGroupMetrics
-      |> Ash.Query.filter_input(instance_id: nni_group.id)
-      |> Ash.Query.load(:value)
-      |> Ash.read_one!()
-
-    IO.puts("\n========== AVC.cvc (single-hop :cvlan) ==========")
-    IO.inspect(avc.cvc, label: "avc.cvc")
-
-    IO.puts("\n========== AVC.nni_group (two-hop [:cvlan, :svlan]) ==========")
-    IO.inspect(avc.nni_group, label: "avc.nni_group")
-
-    IO.puts("\n========== CVC.nni_group (single-hop :svlan) ==========")
-    IO.inspect(cvc.nni_group, label: "cvc.nni_group")
-
-    IO.puts("\n========== CvcMetrics record (live aggregate over assigned AVCs) ==========")
-    IO.inspect(cvc_metrics.value, label: "cvc_metrics.value")
-
-    IO.puts("\n========== NniGroupMetrics record (cvcs/nnis aggregates + utilization) ==========")
-    IO.inspect(nni_group_metrics.value, label: "nni_group_metrics.value")
-
-    IO.puts("\n========== NniGroup.nnis (brought-up via :contains Relationship) ==========")
-    IO.inspect(nni_group.nnis, label: "nni_group.nnis")
-
-    IO.puts("\n========== AVC (TMF JSON, current state) ==========")
-
-    avc
-    |> Jason.encode!()
-    |> Diffo.Util.summarise_dates()
-    |> Jason.decode!()
-    |> Jason.encode!(pretty: true)
-    |> IO.puts()
-
-    IO.puts("\n========== CVC (TMF JSON, current state) ==========")
-
-    cvc
-    |> Jason.encode!()
-    |> Diffo.Util.summarise_dates()
-    |> Jason.decode!()
-    |> Jason.encode!(pretty: true)
-    |> IO.puts()
-
-    IO.puts("\n========== NniGroup (TMF JSON, current state) ==========")
-
-    nni_group
-    |> Jason.encode!()
-    |> Diffo.Util.summarise_dates()
-    |> Jason.decode!()
-    |> Jason.encode!(pretty: true)
-    |> IO.puts()
-  end
-
   describe "build nbn_ethernet" do
     test "create an nbn_ethernet access" do
       {:ok, access} = Nbn.build_nbn_ethernet(%{})
@@ -453,6 +309,43 @@ defmodule DiffoExample.Nbn.NbnEthernetTest do
         )
       end)
     end
+
+    test "ntd brings up assigned UNIs as unis[] via :port assignment" do
+      {:ok, ntd} = Nbn.build_ntd(%{})
+
+      {:ok, ntd} =
+        Nbn.define_ntd(ntd, %{
+          characteristic_value_updates: [
+            ntd: [model: "Sercomm CG4000A", technology: :FTTP],
+            ports: [first: 1, last: 4, assignable_type: "port"]
+          ]
+        })
+
+      # Two UNIs defined and assigned ports from the NTD
+      for {port_num, encap} <- [{1, "DSCP Mapped"}, {2, "untagged"}] do
+        {:ok, uni} = Nbn.build_uni(%{})
+
+        {:ok, _} =
+          Nbn.define_uni(uni, %{
+            characteristic_value_updates: [
+              uni: [port: port_num, encapsulation: encap, technology: :FTTP]
+            ]
+          })
+
+        {:ok, _} =
+          Nbn.assign_port(ntd, %{
+            assignment: %Assignment{assignee_id: uni.id, operation: :auto_assign}
+          })
+      end
+
+      {:ok, ntd} = Nbn.get_ntd_by_id(ntd.id, load: [:unis])
+
+      assert is_list(ntd.unis)
+      assert length(ntd.unis) == 2
+
+      ports = Enum.map(ntd.unis, & &1.port) |> Enum.sort()
+      assert ports == [1, 2]
+    end
   end
 
   describe "build cvc" do