improve nbn domain — characteristics inherited via assignment

[matt-beanland]

The NBN domain should surface relevant characteristics from related instances on consuming resources. Today an AVC's TMF JSON shows only its own characteristics, not the context from the CVC that assigned it a cvlan, or transitively the NniGroup that assigned the CVC an svlan. A consumer of the AVC therefore loses upstream context.

Separately, NBN resources also need a way to express local KPIs — counts and bandwidth aggregates across their assignees, and derived ratios like NniGroup utilization — without entangling those with inheritance.

Design

Each resource carries two distinct kinds of typed characteristic:

1. Named characteristic (cvc on CVC, nni_group on NniGroup, etc.) — identity and context for the resource. Inheritable downstream via assignment. AVC inherits CVC's cvc via :cvlan; CVC inherits NniGroup's nni_group via :svlan. Mirrors the Access pattern (Card surfaces Shelf via :slot, Path surfaces Card via :port and Shelf two-hop via [:port, :slot]).
2. metrics characteristic — local aggregates and KPIs. Not inheritable. Captures how this resource fits into the surrounding graph — counts of assignees, summed bandwidth across them, utilization. Computed live.

Rationale: downstream consumers benefit from upstream context (the CVC their AVC belongs to) but don't need to know how many siblings share that CVC. Keeping metrics local and context inheritable matches consumer expectations and keeps the JSON payload sane.

Resource shapes

AVC

• Named avc characteristic — identity (cvlan, bandwidth_profile). Already exists.
• Inherits CVC's cvc via the :cvlan assignment (single-hop).
• Inherits NniGroup's nni_group two-hop via [:cvlan, :svlan].
• No metrics — AVC is a leaf in the downstream direction.

CVC

• Named cvc characteristic — identity (svlan, bandwidth). Already exists.
• Inherits NniGroup's nni_group via the :svlan assignment (single-hop).
• metrics characteristic carries:
  • avcs_count — count of AVCs assigned to this CVC.
  • avcs_total_bandwidth — summed bandwidth across those AVCs.

NniGroup

• Named nni_group characteristic — identity (group_name, location). Already exists.
• No inheritance (top of the chain in this direction).
• metrics characteristic carries:
  • cvcs_count, cvcs_total_bandwidth — aggregates across assigned CVCs (demand side).
  • nnis_count, nnis_total_bandwidth — aggregates across the NNIs this group comprises (capacity side).
  • utilization = cvcs_total_bandwidth / nnis_total_bandwidth — demand over capacity. Expected 0–1 under normal provisioning; >1 under deliberate oversubscription.
• Continues to surface its NNIs as a low-cardinality containment resourceRelationship (no aggregate explosion — typically only a few NNIs per group).

NTD

• Named ntd characteristic — identity (model, serial_number, technology). Already exists.
• No upstream inheritance (NTD sits at the customer edge).
• Surfaces a low-cardinality unis[] view — the UNIs assigned to this NTD's ports (typical NTD has only a handful of UNIs). Each entry references the UNI with the port number carried as a relationship characteristic. Analogous shape to NniGroup's nnis[], just with assignment-style relationship metadata rather than containment.

NbnEthernet (PRI)

• Named pri characteristic — identity (avcid, uniid, technology, bandwidth_profile, speeds_*). Already exists.
• Brings up four characteristics from its related instances:
  • avc from the related AVC (via the :avc owns relationship).
  • uni from the related UNI (via the :uni owns relationship).
  • cvc transitively via AVC's assignment to CVC.
  • ntd transitively via UNI's assignment to NTD.
• Result: an NBN Ethernet access surfaces its full delivery chain in one JSON payload — AVC, the CVC backing that AVC, the UNI at the customer end, and the NTD that UNI plugs into.
• No metrics on PRI — it's a service-level resource; aggregation metrics live on the supporting resources (CVC, NniGroup).

UNI keeps its existing named uni characteristic and is consumed by PRI's bring-up — no changes needed.

Done

Definition of done includes a JSON and MCP surface check to confirm both the inherited characteristics and the metrics render correctly.

[matt-beanland]

PR 1 complete (AVC, CVC, NniGroup) — merged.

What landed:

• AVC inherits cvc via single-hop :cvlan (singular) and nni_group via two-hop [:cvlan, :svlan] (singular). Brought-up as <Characteristic>.Value{} structs on the Ash side; not yet in TMF JSON.
• CVC inherits nni_group via single-hop :svlan (singular). New :metrics characteristic (avcs_count, avcs_total_bandwidth) — surfaces in TMF JSON.
• NniGroup new :metrics characteristic (cvcs_count/cvcs_total_bandwidth, nnis_count/nnis_total_bandwidth, utilization) — surfaces in TMF JSON. New :nnis calc brings up each comprised NNI's typed value via the :contains relationship.

Supporting work:

• Renamed DiffoExample.Calculations.InheritedCharacteristic → InheritedCharacteristicViaAssignment and added sibling InheritedCharacteristicViaRelationship for traversal over Provider.Relationship edges. Both calcs take a singular?: option to unwrap to a single value where the underlying graph identity guarantees ≤1 result.
• BandwidthProfile.downstream/1 maps each profile atom to its representative downstream Mbps for use in metric aggregations.
• Source-side metric aggregations filter on thing: (the pool's thing name, always set from the DSL) rather than alias: (the consumer's slot name, which may be unset). Inheritance traversals from the consumer side continue to filter on alias: (its identity).

Tests: 3 new (AVC inheritance, CVC metrics, NniGroup metrics + nnis[]), plus a @tag :show_json inspector test for ad-hoc payload review. 52/52 pass.

Upstream notes on diffo#172 cover the rename + sibling function. No reverse sibling needed at this time.

Up next: PR 2 — NTD unis[] surface (UNI bundle is otherwise a no-op).

[matt-beanland]

Issue #49 complete — ready to merge 49-pri into dev.

The 49-pri branch stacks all three PRs plus the cross-cutting alias-convention revision:

• Part 1 (2548f63) — AVC/CVC/NniGroup inheritance and metrics; InheritedCharacteristic rename + new InheritedCharacteristicViaRelationship sibling; NniGroup.nnis surface.
• Part 2 (069ed1f) — NTD unis[] via the :port assignment; ReverseInheritedCharacteristic gained a thing: filter option.
• Part 3 (56a6874) — PRI's four bring-ups (:avc, :uni single-hop via owns; :cvc, :ntd two-hop relationship-then-assignment); InheritedCharacteristicViaRelationship gained a then_via: option for mixed paths.
• NBN alias convention (0df10eb) — consumer-side aliases now name the upstream related resource (the role it plays from the consumer's POV), not the slot/thing being received. AVC sets :cvc on its cvlan assignment, CVC sets :nni_group, UNI sets :ntd, PRI's owns relationships use :circuit (AVC) and :port (UNI).
• Access alias convention (2e5d6ff) — same convention applied: Card sets :shelf, Path sets :card, calc walks and Shelf.cards/ShelfTotalPorts aligned.

Behaviour shape, per the design:

• Forward inheritance via assignment is singular (graph identity guarantees ≤1 per hop); InheritedCharacteristicViaAssignment and InheritedCharacteristicViaRelationship both accept singular?: to unwrap.
• Reverse aggregations on the source side filter on thing: (pool's thing name, always set) rather than alias: (consumer's choice, may be unset). The assignment-direction-asymmetry is documented in the calc moduledocs.
• The brought-up calcs return the typed <Characteristic>.Value{} struct — the inner payload, not the wrapping characteristic record. Same shape that surfaces inline in TMF JSON's value field.
• Named characteristics are inheritable; metrics characteristics (CvcMetrics, NniGroupMetrics) are local and never propagate.
• TMF JSON: metrics surface in resourceCharacteristic; brought-up inheritance values are Ash-side only (consumers load :cvc, :nni_group, etc.). Same convention as Access's Card.shelf / Path.shelf.

Verification

• mix compile clean
• mix test → 54 sandboxed tests, 0 failures
• mix test --only show_neo4j → 3 exploration tests, 0 failures; persists the AVC/CVC/NniGroup chain, NTD with UNIs, and full PRI delivery chain into the real Neo4j for browser inspection
• Net code growth ~+350 lines across 5 commits

Upstream notes on diffo#172 already cover the calc rename and the via-relationship sibling. No reverse-via-relationship sibling is needed.

Next: #51 (livebook + documentation), per the existing scope.