add RSP multi-tenancy, JSON API, and NBN domain documentation for v0.2.0

- RSP resource with AshStateMachine lifecycle (inactive/active/suspended)
- Ash Policy multi-tenancy: SetRspId change, OwnedByActor and NoActor checks, RspOwnership macro shared across 5 RSP-owned resources
- NTD and UNI are NBN-owned infrastructure: readable by any RSP, mutable only by nil actor
- JSON API via AshJsonApi and Plug.Cowboy on port 4000
- RSP list action with epid sort; field_policy restricts state visibility to record owner
- Livebook moved to documentation/domains/diffo_example_nbn.livemd with Kino RSP selector and actor-scoped provisioning flow
- documentation/domains/nbn.md: Perentie ecosystem narrative and RSP spirit animals
- README updated to describe both NBN and Access domains

Author: matt-beanland

.gitignore

@@ -24,4 +24,7 @@ diffo-*.tar
 
 /.elixir_ls
 
-.DS_Store
+.DS_Store
+
+# Agent related
+.claude/*

README.md

@@ -8,14 +8,24 @@ SPDX-License-Identifier: MIT
 
 [![Module Version](https://img.shields.io/hexpm/v/diffo)](https://hex.pm/packages/diffo_example)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen)](https://hexdocs.pm/diffo_example/)
-[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fmain%2Fdiffo_example.livemd)
 [![License](https://img.shields.io/hexpm/l/diffo)](https://github.com/diffo-dev/diffo_example/blob/master/LICENSES/MIT.md)
 [![REUSE status](https://api.reuse.software/badge/github.com/diffo-dev/diffo_example)](https://api.reuse.software/info/github.com/diffo-dev/diffo_example)
 
-This repo contains Diffo Examples.
-
 [Diffo](https://github.com/diffo-dev/diffo) is a Telecommunications Management Forum (TMF) Service and Resource Manager, built for autonomous networks.
 
+This repo contains two independent example domains, each modelling a different slice of a telco network.
+
+## NBN Domain
+
+A declarative model of a fictional NBN Ethernet access hierarchy — NbnEthernet, UNI, AVC, NTD, CVC, NNI Group, and NNI — built entirely with the Diffo Provider Instance DSL. Includes multi-tenancy via Ash Policy: each RSP can only see and manage the resources they own.
+
+[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fdev%2Fdocumentation%2Fdomains%2Fdiffo_example_nbn.livemd)
+
+The livebook walks through provisioning a complete NBN Ethernet access circuit, selecting an RSP to operate as, and demonstrating how the `mine` actions propagate technology, speeds, CVLAN, and port assignments up the resource hierarchy.
+
+## Access Domain
+
+A copper-network equivalent covering DSL access services — Cable, Card, Path, and Shelf. Explore `lib/access/` for the domain model.
 
 ## Installation
 
@@ -32,13 +42,6 @@ end
 
 You need [Neo4j](https://github.com/neo4j/neo4j) available. We recommend the Neo4j Community 5 latest, available at [Neo4j Deploymnent Centre](https://neo4j.com/deployment-center/) which can be installed locally. You can also configure connection to a cloud based database service such as [Neo4j AuraDB](https://neo4j.com/product/auradb/).
 
-## Tutorial
-
-Click the **Run in Livebook** badge above to open the interactive tutorial, or find it at [diffo_example.livemd](diffo_example.livemd).
-
-The diffo_example livebook walks through provisioning a complete NBN Ethernet access circuit — NTD, UNI, AVC, CVC, NNI Group, and NNI — showing how the `mine` actions propagate technology, speeds, CVLAN, and port assignments up the resource hierarchy.
-
-
 ## Contributions
 
 Contributions are welcome, please start with an [issue](https://github.com/diffo-dev/diffo_example/issues)

diffo_example.livemd …ntation/domains/diffo_example_nbn.livemddiffo_example.livemd renamed to documentation/domains/diffo_example_nbn.livemd diffo_example.livemd renamed to documentation/domains/diffo_example_nbn.livemd

@@ -10,20 +10,24 @@ SPDX-License-Identifier: MIT
 Mix.install(
   [
     {:diffo_example, "~> 0.2.0"},
+    {:kino, "~> 0.14"},
     {:req, "~> 0.5"}
   ],
-    config: [
-    bolty: [{Bolt, [
-      uri: "bolt://localhost:7687",
-      auth: [username: "neo4j", password: "password"],
-      user_agent: "diffoExampleLivebook/1",
-      pool_size: 15,
-      max_overflow: 3,
-      prefix: :default,
-      name: Bolt,
-      log: false,
-      log_hex: false
-    ]}]
+  config: [
+    bolty: [
+      {Bolt,
+       [
+         uri: "bolt://localhost:7687",
+         auth: [username: "neo4j", password: "password"],
+         user_agent: "diffoExampleLivebook/1",
+         pool_size: 15,
+         max_overflow: 3,
+         prefix: :default,
+         name: Bolt,
+         log: false,
+         log_hex: false
+       ]}
+    ]
   ],
   consolidate_protocols: false
 )
@@ -67,42 +71,28 @@ It is helpful to have a Neo4j browser open locally, typically at http://localhos
 AshNeo4j.Neo4jHelper.delete_all()
 ```
 
-## Setup Aliases
-
-```elixir
-require Ash.Query
-alias DiffoExample.Nbn
-alias DiffoExample.Nbn.NbnEthernet
-alias DiffoExample.Nbn.Uni
-alias DiffoExample.Nbn.Avc
-alias DiffoExample.Nbn.Ntd
-alias DiffoExample.Nbn.Cvc
-alias DiffoExample.Nbn.NniGroup
-alias DiffoExample.Nbn.Nni
-alias DiffoExample.Nbn.Technology
-alias DiffoExample.Nbn.Speeds
-import Jason, only: [encode: 2]
-```
-
-## About NBN
+## About NBN Co
 
 NBN (National Broadband Network) is Australia's wholesale fixed-line access network, operated by NBN Co. It provides standardised access products to Retail Service Providers (RSPs), who in turn deliver internet and other services to end customers.
 
+For the purpose of this example we are going to refer to a simplified, and re-imagined NBN Co as NBN.
+
 An RSP typically combines:
 
 * An **NBN Ethernet** access circuit (UNI + AVC) at the customer premises — the access and aggregation layer modelled in this domain
 * A **home gateway** device installed at the UNI, which provides the customer's LAN, Wi-Fi, and sometimes voice
 * Transport, aggregation, and edge infrastructure connecting the NNI to the RSP's network and on to the internet
 
-NBN Co connects the customer premises to the RSP's network via a Point of Interconnect (POI). The NNI sits at the POI, grouped into NNI Groups. AVCs carrying customer traffic are aggregated onto a CVC, which terminates at the NNI Group. The RSP purchases CVC capacity to carry the aggregate traffic of its customers at that POI.
+NBN connects the customer premises to the RSP's network via a Point of Interconnect (POI). The NNI sits at the POI, grouped into NNI Groups. AVCs carrying customer traffic are aggregated onto a CVC, which terminates at the NNI Group. The RSP purchases CVC capacity to carry the aggregate traffic of its customers at that POI.
 
-NBN is delivered over several access technologies — FTTP, FTTN, FTTB, FTTC, HFC, Fixed Wireless, and Satellite — which determine which bandwidth profiles and speeds are available to a given premises.
+NBN delivers over several access technologies — FTTP, FTTN, FTTB, FTTC, HFC, Fixed Wireless, and Satellite — which determine which bandwidth profiles and speeds are available to a given premises.
 
-## Technology and Speeds
+## NBN Ethernet Technology and Speeds
 
 The NBN domain defines Technology as an Ash Enum covering all NBN access types:
 
 ```elixir
+alias DiffoExample.Nbn.{Technology,Speeds}
 Technology.values()
 ```
 
@@ -125,21 +115,51 @@ Speeds.speeds(:wireless_superfast, :FixedWireless)
 Speeds.speeds(:home_fast, :FixedWireless)
 ```
 
-## Building the Network Hinterland
+## Multi-tenancy
+
+Each RSP operates in isolation — they can only see and manage the resources they own. This multi-tenancy is enforced at the Ash policy layer: every NBN resource is stamped with the owning RSP's id at creation, and subsequent reads, updates, and destroys are scoped to the record owner.
+
+Select the RSP you want to operate as for the rest of this livebook. All resources you build will be owned by that RSP and isolated from resources owned by others.
+
+```elixir
+alias DiffoExample.Nbn
+alias DiffoExample.Nbn.Rsp
+import Jason, only: [encode: 2]
+DiffoExample.Nbn.Initializer.init()
+rsps = Nbn.list_rsps!()
+Kino.DataTable.new(rsps, keys: [:epid, :name, :short_name, :state])
+```
+
+```elixir
+rsp_input = Kino.Input.select(
+  "Operate as RSP",
+  Enum.map(rsps, fn rsp -> {rsp.name, Atom.to_string(rsp.short_name)} end)
+)
+```
+
+```elixir
+actor = Enum.find(rsps, fn rsp -> rsp.name == Kino.Input.read(rsp_input) end)
+actor
+```
+
+## Maintaining Shareable Resources
+
+As an RSP we need maintain some shareable network resources: NNI, NNI Group, and CVC.
 
-Before we can provision an NBN Ethernet access we need the shared network resources: NNI, NNI Group, and CVC.
+We'll need these everywhere we operate, in advance of and sufficient for all the NBN Ethernet Accesses we have. We'll just build one of each right now.
 
-Build an NNI — the physical interconnect between the RSP and NBN Co:
+Build an NNI — the physical interconnect between the RSP and NBN:
 
 ```elixir
-nni = Nbn.build_nni!(%{})
+alias DiffoExample.Nbn.{Nni, NniGroup, CVC}
+nni = Nbn.build_nni!(%{}, actor: actor)
 nni |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
 Build an NNI Group — a logical grouping of NNIs at a point of interconnect:
 
 ```elixir
-nni_group = Nbn.build_nni_group!(%{})
+nni_group = Nbn.build_nni_group!(%{}, actor: actor)
 nni_group |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
@@ -148,30 +168,33 @@ Define the NNI Group with an SVLAN assignment and relate the NNI:
 ```elixir
 nni_group = Nbn.define_nni_group!(nni_group, %{
   characteristic_value_updates: [nni_group: [svlan: 100]]
-})
+}, actor: actor)
 nni_group = Nbn.relate_nni_group!(nni_group, %{
   relationships: [%Diffo.Provider.Instance.Relationship{id: nni.id, alias: :nni, type: :isAssigned}]
-})
+}, actor: actor)
 nni_group |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
 Build a CVC — the aggregation virtual circuit that terminates at the NNI Group:
 
 ```elixir
-cvc = Nbn.build_cvc!(%{})
+cvc = Nbn.build_cvc!(%{}, actor: actor)
 cvc = Nbn.relate_cvc!(cvc, %{
   relationships: [%Diffo.Provider.Instance.Relationship{id: nni_group.id, alias: :nni_group, type: :isAssigned}]
-})
+}, actor: actor)
 cvc |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
-## Provisioning an NBN Ethernet Access
+## Provisioning NBN Ethernet
+
+For each customer site we want to provide service to, we need an NBN Ethernet composite resource, involving an NTD, UNI, AVC and CVC.
 
-With the hinterland in place we can provision a customer-facing NBN Ethernet access.
+The NTD is NBN infrastructure — built and managed by NBN, visible to any RSP. It may not exist at a new or existing customer site, so may be built on demand by NBN.
 
 Build an NTD — the device installed at the customer premises:
 
 ```elixir
+alias DiffoExample.Nbn.{Ntd, Uni, Avc, NbnEthernet}
 ntd = Nbn.build_ntd!(%{})
 ntd = Nbn.define_ntd!(ntd, %{
   characteristic_value_updates: [ntd: [technology: :FTTP, ports: [1, 2, 3, 4]]]
@@ -203,28 +226,28 @@ uni |> Jason.encode!(pretty: true) |> IO.puts
 Build an AVC and assign it a CVLAN from the CVC:
 
 ```elixir
-avc = Nbn.build_avc!(%{})
+avc = Nbn.build_avc!(%{}, actor: actor)
 avc = Nbn.define_avc!(avc, %{
   characteristic_value_updates: [avc: [bandwidth_profile: :home_ultrafast]]
-})
+}, actor: actor)
 cvc = Nbn.assign_cvlan!(cvc, %{
   assignment: %Assignment{assignee_id: avc.id, operation: :auto_assign}
-})
-avc = Nbn.mine_avc!(avc, %{})
+}, actor: actor)
+avc = Nbn.mine_avc!(avc, %{}, actor: actor)
 avc |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
 Now build the top-level NBN Ethernet access and relate it to both the UNI and AVC:
 
 ```elixir
-pri = Nbn.build_nbn_ethernet!(%{})
+pri = Nbn.build_nbn_ethernet!(%{}, actor: actor)
 pri = Nbn.relate_nbn_ethernet!(pri, %{
   relationships: [
     %Diffo.Provider.Instance.Relationship{id: uni.id, alias: :uni, type: :isAssigned},
     %Diffo.Provider.Instance.Relationship{id: avc.id, alias: :avc, type: :isAssigned}
   ]
-})
-pri = Nbn.mine_nbn_ethernet!(pri, %{})
+}, actor: actor)
+pri = Nbn.mine_nbn_ethernet!(pri, %{}, actor: actor)
 pri |> Jason.encode!(pretty: true) |> IO.puts
 ```
 
@@ -251,19 +274,19 @@ The NBN domain exposes a JSON API via `Plug.Cowboy` on port 4000. Start the serv
 First check the catalog — all NBN specifications are initialised on startup:
 
 ```elixir
-Req.get!("http://localhost:4000/catalog").body |> Jason.encode!(pretty: true) |> IO.puts()
+Req.get!("http://localhost:4000/catalog", decode_body: false).body |> IO.puts()
 ```
 
 Now retrieve all NBN Ethernet instances:
 
 ```elixir
-Req.get!("http://localhost:4000/nbnEthernet").body |> Jason.encode!(pretty: true) |> IO.puts()
+Req.get!("http://localhost:4000/nbnEthernet", decode_body: false).body |> IO.puts()
 ```
 
 Or fetch the one we provisioned above by id:
 
 ```elixir
-Req.get!("http://localhost:4000/nbnEthernet/#{pri.id}").body |> Jason.encode!(pretty: true) |> IO.puts()
+Req.get!("http://localhost:4000/nbnEthernet/#{pri.id}", decode_body: false).body |> IO.puts()
 ```
 
 ## What Next?

documentation/domains/nbn.md

@@ -0,0 +1,23 @@
+<!--
+SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+
+SPDX-License-Identifier: MIT
+-->
+
+# The NBN Domain
+
+## The Perentie Ecosystem
+
+NBN Co operates as **Perentie** — Australia's largest monitor lizard, ancient and continent-wide. Perentie owns the territory. It does not compete with the animals moving through its country; it simply defines the ground they all walk on.
+
+The RSPs are the spirit animals of the ecosystem, each finding their niche in Perentie's range:
+
+| RSP                | Spirit Animal      | Inspiration                                                                                                              |
+| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| Wedge-tail Telecom | Wedge-tailed Eagle | Australia's apex aerial predator — dominant, territorial, commands every landscape it surveys                          |
+| Quokka Connect     | Quokka             | Famously friendly, genuinely Australian, radiates good energy — operates in WA under bilateral agreement with Perentie |
+| Ibis Telecom       | White Ibis         | Beloved in spite of its reputation, scrappy, surprisingly capable                                                        |
+| Taipan Group       | Taipan             | Carries the TPG initials; fast, precise, not to be underestimated                                                        |
+| Echidna Networks   | Echidna            | Prickly on the surface, uniquely capable beneath it                                                                      |
+| Dugong Digital     | Dugong             | Slow and steady, but still very much alive                                                                               |
+| Lyrebird           | Lyrebird           | Mimics everything, loops back on itself, endlessly clever                                                                |

lib/diffo_example/application.ex

@@ -9,10 +9,13 @@ defmodule DiffoExample.Application do
 
   @impl true
   def start(_type, _args) do
-    children = [
-      {Plug.Cowboy, scheme: :http, plug: DiffoExample.Nbn.Router, options: [port: 4000]},
-      {Task, &DiffoExample.Nbn.Initializer.init/0}
-    ]
+    children =
+      [
+        {Task, &DiffoExample.Nbn.Initializer.init/0}
+      ] ++
+        if Mix.env() == :test,
+          do: [],
+          else: [{Plug.Cowboy, scheme: :http, plug: DiffoExample.Nbn.Router, options: [port: 4000]}]
 
     Supervisor.start_link(children, strategy: :one_for_one, name: DiffoExample.Supervisor)
   end

lib/nbn/changes/set_rsp_id.ex

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.Changes.SetRspId do
+  use Ash.Resource.Change
+
+  def change(changeset, _opts, %{actor: %{id: id}}) do
+    Ash.Changeset.force_change_attribute(changeset, :rsp_id, id)
+  end
+
+  def change(changeset, _opts, _context), do: changeset
+end

lib/nbn/checks/no_actor.ex

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.Checks.NoActor do
+  @moduledoc false
+  use Ash.Policy.SimpleCheck
+
+  @impl true
+  def describe(_opts), do: "no actor present (internal Perentie call)"
+
+  @impl true
+  def match?(nil, _context, _opts), do: true
+  def match?(_actor, _context, _opts), do: false
+end

lib/nbn/checks/owned_by_actor.ex

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2025 diffo_example contributors <https://github.com/diffo-dev/diffo_example/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule DiffoExample.Nbn.Checks.OwnedByActor do
+  @moduledoc false
+  use Ash.Policy.FilterCheck
+
+  @impl true
+  def describe(_opts), do: "actor owns resource (rsp_id matches actor id)"
+
+  @impl true
+  def filter(actor, _context, _opts) do
+    case actor do
+      %{id: id} -> [rsp_id: id]
+      _ -> false
+    end
+  end
+end