Place DSL — BasePlace fragment, Place/Party/Instance Extension sections, persisters, verifiers, and tests

Extracts BasePlace as a Spark.Dsl.Fragment following the BaseParty pattern. Adds instances/parties/places DSL sections to Place.Extension and Party.Extension, with persisters baking role declarations onto resources at compile time and a VerifyRoles verifier checking for duplicates and correct base types across all sections. Adds places do to Instance.Extension structure do, with PersistPlaces and place/1 generated via TransformBehaviour.

Four test fixtures illustrate the simple and complex patterns for both Party and Place. Moduledocs across BaseInstance, BaseParty, and BasePlace now document the domain-specific attributes contract explicitly. Livebook updated with a Place Extension section and simplified cluster creation using the domain API.

Author: matt-beanland

lib/diffo/provider/components/base_party.ex

@@ -76,6 +76,32 @@ defmodule Diffo.Provider.BaseParty do
         end
       end
 
+  ## Domain-specific attributes
+
+  Add Ash `attribute` declarations directly to your derived resource for any fields beyond the
+  base set. Those attributes can only be set via actions you declare on the derived resource —
+  the base `create` action provided by `BaseParty` only accepts the base fields (`id`, `href`,
+  `name`, `type`, `referred_type`). Use your domain API to call the derived resource's action:
+
+      defmodule MyApp.Carrier do
+        use Ash.Resource, fragments: [BaseParty], domain: MyApp.Domain
+
+        attributes do
+          attribute :abn, :string, public?: true
+          attribute :carrier_code, :string, public?: true
+        end
+
+        actions do
+          create :build do
+            accept [:id, :href, :name, :abn, :carrier_code]
+            change set_attribute(:type, :Organization)
+          end
+        end
+      end
+
+      # Use the domain API — Provider.create_party!/1 does not know about :abn
+      MyApp.Domain.create_carrier!(%{name: "Acme", abn: "51824753556", carrier_code: "ACM"})
+
   ## TMF type and referred_type
 
   The `type` and `referred_type` attributes map to the TMF `@type` and `@referredType` JSON

lib/diffo/provider/components/base_place.ex

@@ -53,6 +53,32 @@ defmodule Diffo.Provider.BasePlace do
         end
       end
 
+  ## Domain-specific attributes
+
+  Add Ash `attribute` declarations directly to your derived resource for any fields beyond the
+  base set. Those attributes can only be set via actions you declare on the derived resource —
+  the base `create` action provided by `BasePlace` only accepts the base fields (`id`, `href`,
+  `name`, `type`, `referred_type`). Use your domain API to call the derived resource's action:
+
+      defmodule MyApp.DataCentre do
+        use Ash.Resource, fragments: [BasePlace], domain: MyApp.Domain
+
+        attributes do
+          attribute :tier, :integer, public?: true
+          attribute :power_capacity_kw, :integer, public?: true
+        end
+
+        actions do
+          create :build do
+            accept [:id, :href, :name, :tier, :power_capacity_kw]
+            change set_attribute(:type, :GeographicSite)
+          end
+        end
+      end
+
+      # Use the domain API — Provider.create_place!/1 does not know about :tier
+      MyApp.Domain.create_data_centre!(%{name: "M2", tier: 3, power_capacity_kw: 40_000})
+
   ## TMF type and referred_type
 
   The `type` and `referred_type` attributes map to the TMF `@type` and `@referredType` JSON

lib/diffo/provider/components/party/extension.ex

@@ -106,5 +106,13 @@ defmodule Diffo.Provider.Party.Extension do
   }
 
   use Spark.Dsl.Extension,
-    sections: [@instances, @parties, @places]
+    sections: [@instances, @parties, @places],
+    persisters: [
+      Diffo.Provider.Party.Extension.Persisters.PersistInstances,
+      Diffo.Provider.Party.Extension.Persisters.PersistParties,
+      Diffo.Provider.Party.Extension.Persisters.PersistPlaces
+    ],
+    verifiers: [
+      Diffo.Provider.Party.Extension.Verifiers.VerifyRoles
+    ]
 end

lib/diffo/provider/components/party/extension/persisters/persist_instances.ex

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Party.Extension.Persisters.PersistInstances do
+  @moduledoc "Persists instance role declarations and bakes instances/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    declarations = Transformer.get_entities(dsl_state, [:instances])
+    escaped = Macro.escape(declarations)
+    dsl_state = Transformer.persist(dsl_state, :instances, declarations)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def instances, do: unquote(escaped)
+    end)}
+  end
+end

lib/diffo/provider/components/party/extension/persisters/persist_parties.ex

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Party.Extension.Persisters.PersistParties do
+  @moduledoc "Persists party role declarations and bakes parties/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    declarations = Transformer.get_entities(dsl_state, [:parties])
+    escaped = Macro.escape(declarations)
+    dsl_state = Transformer.persist(dsl_state, :parties, declarations)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def parties, do: unquote(escaped)
+    end)}
+  end
+end

lib/diffo/provider/components/party/extension/persisters/persist_places.ex

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Party.Extension.Persisters.PersistPlaces do
+  @moduledoc "Persists place role declarations and bakes places/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    declarations = Transformer.get_entities(dsl_state, [:places])
+    escaped = Macro.escape(declarations)
+    dsl_state = Transformer.persist(dsl_state, :places, declarations)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def places, do: unquote(escaped)
+    end)}
+  end
+end

lib/diffo/provider/components/party/extension/verifiers/verify_roles.ex

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Party.Extension.Verifiers.VerifyRoles do
+  @moduledoc "Verifies role declarations across instances, parties, and places sections"
+  use Spark.Dsl.Verifier
+
+  alias Spark.Dsl.Verifier
+  alias Spark.Error.DslError
+  alias Diffo.Provider.Instance.Extension.Info, as: InstanceInfo
+  alias Diffo.Provider.Party.Extension.Info, as: PartyInfo
+  alias Diffo.Provider.Place.Extension.Info, as: PlaceInfo
+
+  @impl true
+  def verify(dsl_state) do
+    resource = Verifier.get_persisted(dsl_state, :module)
+
+    errors =
+      check_section(dsl_state, [:instances], :party_type, &InstanceInfo.instance?/1,
+        "instances", "instance_type", "BaseInstance", resource) ++
+      check_section(dsl_state, [:parties], :party_type, &PartyInfo.party?/1,
+        "parties", "party_type", "BaseParty", resource) ++
+      check_section(dsl_state, [:places], :place_type, &PlaceInfo.place?/1,
+        "places", "place_type", "BasePlace", resource)
+
+    case errors do
+      [] -> :ok
+      _ -> {:error, errors}
+    end
+  end
+
+  defp check_section(dsl_state, path, type_field, type_check?, section, field, base, resource) do
+    entities = Verifier.get_entities(dsl_state, path)
+    duplicate_errors(entities, section, resource) ++
+      type_errors(entities, type_field, type_check?, section, field, base, resource)
+  end
+
+  defp duplicate_errors(entities, section, resource) do
+    entities
+    |> Enum.group_by(& &1.role)
+    |> Enum.filter(fn {_role, list} -> length(list) > 1 end)
+    |> Enum.map(fn {role, _} ->
+      DslError.exception(
+        module: resource,
+        path: [String.to_atom(section)],
+        message: "#{section}: role #{inspect(role)} is declared more than once"
+      )
+    end)
+  end
+
+  defp type_errors(entities, type_field, type_check?, section, field, base, resource) do
+    Enum.reduce(entities, [], fn entity, acc ->
+      mod = Map.get(entity, type_field)
+
+      cond do
+        is_nil(mod) ->
+          acc
+
+        !Code.ensure_loaded?(mod) ->
+          [DslError.exception(
+            module: resource,
+            path: [String.to_atom(section)],
+            message: "#{section}: #{field} #{inspect(mod)} does not exist"
+          ) | acc]
+
+        !type_check?.(mod) ->
+          [DslError.exception(
+            module: resource,
+            path: [String.to_atom(section)],
+            message: "#{section}: #{field} #{inspect(mod)} does not extend #{base}"
+          ) | acc]
+
+        true ->
+          acc
+      end
+    end)
+  end
+end

lib/diffo/provider/components/place/extension.ex

@@ -107,5 +107,13 @@ defmodule Diffo.Provider.Place.Extension do
   }
 
   use Spark.Dsl.Extension,
-    sections: [@instances, @parties, @places]
+    sections: [@instances, @parties, @places],
+    persisters: [
+      Diffo.Provider.Place.Extension.Persisters.PersistInstances,
+      Diffo.Provider.Place.Extension.Persisters.PersistParties,
+      Diffo.Provider.Place.Extension.Persisters.PersistPlaces
+    ],
+    verifiers: [
+      Diffo.Provider.Place.Extension.Verifiers.VerifyRoles
+    ]
 end

lib/diffo/provider/components/place/extension/persisters/persist_instances.ex

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Place.Extension.Persisters.PersistInstances do
+  @moduledoc "Persists instance role declarations and bakes instances/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    declarations = Transformer.get_entities(dsl_state, [:instances])
+    escaped = Macro.escape(declarations)
+    dsl_state = Transformer.persist(dsl_state, :instances, declarations)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def instances, do: unquote(escaped)
+    end)}
+  end
+end

lib/diffo/provider/components/place/extension/persisters/persist_parties.ex

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.Place.Extension.Persisters.PersistParties do
+  @moduledoc "Persists party role declarations and bakes parties/0"
+  use Spark.Dsl.Transformer
+  alias Spark.Dsl.Transformer
+
+  @impl true
+  def transform(dsl_state) do
+    declarations = Transformer.get_entities(dsl_state, [:parties])
+    escaped = Macro.escape(declarations)
+    dsl_state = Transformer.persist(dsl_state, :parties, declarations)
+
+    {:ok, Transformer.eval(dsl_state, [], quote do
+      @doc false
+      def parties, do: unquote(escaped)
+    end)}
+  end
+end