phase 6 - AssignerRelationship extends BaseRelationship

Author: matt-beanland

AGENTS.md

@@ -40,11 +40,13 @@ lib/diffo/provider/
   assigner/
     assigner.ex                 # Diffo.Provider.Assigner — assign/3 (pools do) and assign/4
     assignable_characteristic.ex # AssignableCharacteristic — pool bounds + algorithm
+    assigned_to_relationship.ex # AssignedToRelationship — assignedTo edges (pool/thing/assigned)
   base_instance.ex              # Ash Fragment for Instance resources
   base_party.ex                 # Ash Fragment for Party resources
   base_place.ex                 # Ash Fragment for Place resources
   components/
     base_characteristic.ex      # Ash Fragment for typed characteristic resources
+    base_relationship.ex          # Ash Fragment for shared Relationship structure
     calculations/
       characteristic_value.ex   # Calculation: builds .Value TypedStruct from record fields
       assigned_values.ex        # Calculation: returns list of assigned integers for a pool+thing
@@ -162,6 +164,9 @@ mix test --max-failures 5         # stop early
 - Using the removed `AssignableValue` TypedStruct — it no longer exists; use `pools do`.
 - Calling `Assigner.assign/4` when a `pools do` declaration exists — prefer `Assigner.assign/3` which looks up the thing automatically.
 - Forgetting to call `Pool.update_pools/3` in `:define` actions when the resource has `pools do` — pool bounds (`first`, `last`, `algorithm`) are set here.
+- Using `characteristic :pool_name, Diffo.Provider.AssignedToRelationship` — `AssignedToRelationship` is not a characteristic; use `pools do / pool :name, :thing / end` instead.
+- Querying `Diffo.Provider.Relationship` for assignment records — assignment relationships are on `Diffo.Provider.AssignedToRelationship`; access them via `instance.assignments`.
+- Filtering `instance.forward_relationships` for `type == :assignedTo` — those records no longer exist there; use `instance.assignments` directly.
 - Calling `build_before/1` or `build_after/2` in actions — these run automatically.
 - Declaring `:specified_by`, `:features`, `:characteristics` as action arguments.
 - Editing `documentation/dsls/DSL-Diffo.Provider.Extension.md` — it is Spark-generated;

documentation/how_to/use_diffo_provider_extension.livemd

@@ -153,7 +153,7 @@ arguments automatically onto that action.
 
 Each characteristic is a dedicated Ash resource using the `Diffo.Provider.BaseCharacteristic` fragment. It carries direct typed attributes and a `:value` calculation that builds a companion `<Module>.Value` TypedStruct for ordered JSON encoding. The TypedStruct uses [AshJason.TypedStruct](https://hexdocs.pm/ash_jason/) to control field order in the JSON output.
 
-For partial resource allocation and assignment we've created `Diffo.Provider.Assigner`. The host resource declares a `pools do` section listing each assignable pool by name and the kind of thing being assigned. Pool bounds (first/last value, algorithm) are set via a `:define` action. Assignment to Services or Resources is via `type: :assignedTo` Relationships that carry the assigned value directly on the Relationship node.
+For partial resource allocation and assignment we've created `Diffo.Provider.Assigner`. The host resource declares a `pools do` section listing each assignable pool by name and the kind of thing being assigned. Pool bounds (first/last value, algorithm) are set via a `:define` action. Each assignment is stored as a `Diffo.Provider.AssignedToRelationship` node (Neo4j label `:AssignmentRelationship`) carrying `pool`, `thing`, and the `assigned` value. These are distinct from regular TMF `Diffo.Provider.Relationship` nodes and are accessible on an instance via `instance.assignments`.
 
 Let's imagine a Compute domain which operates GPU and NPU resources. We want to expose a Cluster composite resource which can be dynamically composed of a number of GPU and NPU cores.
 
@@ -763,7 +763,7 @@ gpu_1 = Compute.define_gpu!(gpu_1, %{characteristic_value_updates: gpu_attrs})
 gpu_2 = Compute.define_gpu!(gpu_2, %{characteristic_value_updates: gpu_attrs})
 ```
 
-The `:cores` pool is backed by an `AssignableCharacteristic` node that records the range bounds and algorithm. Free cores are computed at assignment time from the count of existing `:assignedTo` relationships — there is no stored `free` counter. We can render one as json:
+The `:cores` pool is backed by an `AssignableCharacteristic` node that records the range bounds and algorithm. Free cores are computed at assignment time from the count of existing `AssignmentRelationship` records — there is no stored `free` counter. We can render one as json:
 
 ```elixir
 Jason.encode!(gpu_1, pretty: true) |> IO.puts
@@ -783,16 +783,16 @@ gpu_1 = Compute.assign_gpu_core!(gpu_1, assignment)
 gpu_2 = Compute.assign_gpu_core!(gpu_2, assignment)
 ```
 
-Now our cluster should have a core from each GPU. Check in the Neo4j browser for `:assignedTo` Relationship nodes from `gpu_1` and `gpu_2` to `cluster_1`. There should be four — each Relationship carries `pool: :cores`, `thing: :core`, and the `assigned` integer value (e.g. 1, 2, 3 from gpu_1 and 1 from gpu_2).
+Now our cluster should have a core from each GPU. Check in the Neo4j browser for `:AssignmentRelationship` nodes from `gpu_1` and `gpu_2` to `cluster_1`. There should be four — each carries `pool: :cores`, `thing: :core`, and the `assigned` integer value (e.g. 1, 2, 3 from gpu_1 and 1 from gpu_2).
 
-The GPU's `forward_relationships` include each `:assignedTo` relationship, showing the assigned core number in the JSON encoding as a `resourceRelationshipCharacteristic`:
+The GPU's `assignments` hold each assignment, showing the assigned core number in the JSON encoding as a `resourceRelationshipCharacteristic`:
 
 ```elixir
 Jason.encode!(gpu_1, pretty: true) |> IO.puts
 ```
 
-Make sure you have a look at it in the neo4j browser. There should be Relationship nodes with a role of :assignedTo from each GPU resource instance to the cluster_1 resource instance. Each Relationship should be defined by a Characteristic with the assigned core number.
-There is no central assignment table, rather the relationships ARE the assignments.
+Make sure you have a look at it in the neo4j browser. There should be `:AssignmentRelationship` nodes from each GPU resource instance to the `cluster_1` resource instance, each carrying the assigned core number.
+There is no central assignment table — the `AssignedToRelationship` nodes ARE the assignments. They are separate from the regular `:Relationship` nodes used for TMF service/resource relationships, and are accessible in Elixir via `instance.assignments`.
 
 As an exercise, clone the GPU resource to create an NPU resource and assign some NPU cores from it to your cluster. Check that the assigned NPU cores are unique.
 
@@ -805,7 +805,7 @@ In this tutorial you've used Diffo's unified `provider do` extension to define a
 
 - A composite Cluster resource that receives GPU cores via `Diffo.Provider.Assigner`
 - A GPU resource using `pools do` to declare the `:cores` assignable pool — `pool :cores, :core` replaces the old `characteristic :cores, AssignableValue` pattern
-- Assignment stored directly on `:assignedTo` Relationship nodes (no separate Characteristic nodes for assignments)
+- Assignments stored on `Diffo.Provider.AssignedToRelationship` nodes (Neo4j label `:AssignmentRelationship`, distinct from TMF `:Relationship` nodes); accessible via `instance.assignments`
 - `Tenant` and `Engineer` Party kinds declared with `provider do` that express which instances they operate and manage
 - A `DataCentre` Place kind that declares the instances located at it
 

lib/diffo/provider.ex

@@ -59,7 +59,6 @@ defmodule Diffo.Provider do
 
     resource Diffo.Provider.Relationship do
       define :create_relationship, action: :create
-      define :create_assignment_relationship, action: :create_assignment
 
       define :get_relationship_by_id, action: :read, get_by: :id
       define :list_relationships, action: :list
@@ -78,6 +77,12 @@ defmodule Diffo.Provider do
       define :delete_relationship, action: :destroy
     end
 
+    resource Diffo.Provider.AssignedToRelationship do
+      define :create_assigned_to_relationship, action: :create_assignment
+      define :get_assigned_to_relationship_by_id, action: :read, get_by: :id
+      define :delete_assigned_to_relationship, action: :destroy
+    end
+
     resource Diffo.Provider.AssignableCharacteristic do
       define :create_assignable_characteristic, action: :create
       define :get_assignable_characteristic_by_id, action: :read, get_by: :id

lib/diffo/provider/assigner/assigned_to_relationship.ex

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.AssignedToRelationship do
+  @moduledoc """
+  Ash Resource for a pool assignment relationship.
+
+  Carries the assignment attributes (`pool`, `thing`, `assigned`) that link a
+  source instance to an assignee instance. Stored as an `:AssignedToRelationship`
+  Neo4j node, distinct from the `:Relationship` nodes used for TMF service/resource
+  relationships. Accessible on an instance via `instance.assignments`.
+
+  Created by `Diffo.Provider.Assigner` via `Diffo.Provider.create_assigned_to_relationship/1`.
+  """
+  use Ash.Resource,
+    fragments: [Diffo.Provider.BaseRelationship],
+    otp_app: :diffo,
+    domain: Diffo.Provider
+
+  resource do
+    description "An Ash Resource for a pool assignment relationship"
+    plural_name :assigned_to_relationships
+  end
+
+  neo4j do
+    relate [
+      {:source, :RELATES, :incoming, :Instance},
+      {:target, :RELATES, :outgoing, :Instance}
+    ]
+  end
+
+  jason do
+    pick [:type]
+
+    customize fn result, record ->
+      target_type = Map.get(record, :target_type)
+
+      reference = %Diffo.Provider.Reference{
+        id: record.target_id,
+        href: Map.get(record, :target_href)
+      }
+
+      list_name =
+        Diffo.Provider.Relationship.derive_relationship_characteristic_list_name(target_type)
+
+      result
+      |> Diffo.Util.set(target_type, reference)
+      |> Diffo.Util.set(list_name, [%{name: record.thing, value: record.assigned}])
+    end
+
+    order [
+      :type,
+      :service,
+      :resource,
+      :serviceRelationshipCharacteristic,
+      :resourceRelationshipCharacteristic
+    ]
+  end
+
+  actions do
+    create :create_assignment do
+      description "creates an assignedTo relationship with pool/thing/assigned attributes"
+      accept [:pool, :thing, :assigned]
+
+      argument :source_id, :uuid
+      argument :target_id, :string
+
+      change set_attribute(:type, :assignedTo)
+      change manage_relationship(:source_id, :source, type: :append)
+      change manage_relationship(:target_id, :target, type: :append)
+      change Diffo.Changes.DetailRelationship
+    end
+  end
+
+  attributes do
+    attribute :pool, :atom do
+      description "the pool name on the source instance"
+      allow_nil? true
+      public? true
+    end
+
+    attribute :thing, :atom do
+      description "the kind of thing being assigned within the pool"
+      allow_nil? true
+      public? true
+    end
+
+    attribute :assigned, :integer do
+      description "the assigned value from the pool"
+      allow_nil? true
+      public? true
+    end
+  end
+
+  identities do
+    identity :unique_assignment, [:source_id, :target_id, :pool, :thing, :assigned]
+  end
+
+  preparations do
+    prepare build(sort: [created_at: :asc])
+  end
+end

lib/diffo/provider/assigner/assigner.ex

@@ -4,13 +4,13 @@
 
 defmodule Diffo.Provider.Assigner do
   @moduledoc """
-  Helper to perform Assignment using Relationship attributes.
+  Helper to perform Assignment using `Diffo.Provider.AssignedToRelationship`.
 
-  Assignment state is stored directly on `Diffo.Provider.Relationship` nodes
-  (pool, thing, assigned) rather than creating a separate Characteristic node.
+  Assignment state is stored on `AssignedToRelationship` nodes (pool, thing, assigned),
+  distinct from regular TMF `Diffo.Provider.Relationship` nodes.
   """
   alias Diffo.Provider.AssignableCharacteristic
-  alias Diffo.Provider.Relationship
+  alias Diffo.Provider.AssignedToRelationship
 
   @doc """
   Assign a thing using the pool declared via `pools do` on the instance module.
@@ -66,7 +66,7 @@ defmodule Diffo.Provider.Assigner do
   defp relate_is_assigned(result, pool, thing, value, assignee_id)
        when is_struct(result) and is_atom(pool) and is_atom(thing) and is_integer(value) and
               is_bitstring(assignee_id) do
-    case Diffo.Provider.create_assignment_relationship(%{
+    case Diffo.Provider.create_assigned_to_relationship(%{
            pool: pool,
            thing: thing,
            assigned: value,
@@ -103,15 +103,14 @@ defmodule Diffo.Provider.Assigner do
   end
 
   defp find_assignment(source_id, target_id, pool, thing, value) do
-    Relationship
+    AssignedToRelationship
     |> Ash.Query.new()
     |> Ash.Query.filter_input(
       source_id: source_id,
       target_id: target_id,
       pool: pool,
       thing: thing,
-      assigned: value,
-      type: :assignedTo
+      assigned: value
     )
     |> Ash.read_one(domain: Diffo.Provider)
   end

lib/diffo/provider/components/base_instance.ex

@@ -188,6 +188,7 @@ defmodule Diffo.Provider.BaseInstance do
       {:process_statuses, :STATUSES, :incoming, :ProcessStatus},
       {:forward_relationships, :RELATES, :outgoing, :Relationship},
       {:reverse_relationships, :RELATES, :incoming, :Relationship},
+      {:assignments, :RELATES, :outgoing, :AssignedToRelationship},
       {:features, :HAS, :outgoing, :Feature},
       {:characteristics, :HAS, :outgoing, :Characteristic},
       {:entities, :RELATES, :outgoing, :EntityRef},
@@ -209,6 +210,7 @@ defmodule Diffo.Provider.BaseInstance do
       :specification,
       :process_statuses,
       :forward_relationships,
+      :assignments,
       :features,
       :characteristics,
       :entities,
@@ -407,6 +409,12 @@ defmodule Diffo.Provider.BaseInstance do
       public? true
     end
 
+    has_many :assignments, Diffo.Provider.AssignedToRelationship do
+      description "the instance's outgoing pool assignment relationships"
+      destination_attribute :source_id
+      public? true
+    end
+
     has_many :features, Diffo.Provider.Feature do
       description "the instance's collection of defining features"
       public? true
@@ -655,6 +663,7 @@ defmodule Diffo.Provider.BaseInstance do
                 :specification,
                 :process_statuses,
                 :forward_relationships,
+                :assignments,
                 :entities,
                 :notes,
                 :features,

lib/diffo/provider/components/base_relationship.ex

@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.BaseRelationship do
+  @moduledoc """
+  Ash Resource Fragment which is the shared foundation for TMF Relationship resources.
+
+  Provides the common attributes, relationships, validations, and actions shared
+  between `Diffo.Provider.Relationship` (TMF service/resource relationships) and
+  `Diffo.Provider.AssignedToRelationship` (pool assignment relationships).
+
+  ## Common attributes
+
+  - `id` — uuid4 primary key
+  - `type` — relationship type atom
+  - `target_href` — denormalised target href (set by the `DetailRelationship` change)
+  - `target_type` — denormalised target type (`:service` or `:resource`)
+  - `created_at`, `updated_at` — timestamps
+
+  ## Common Ash relationships
+
+  - `belongs_to :source, Diffo.Provider.Instance`
+  - `belongs_to :target, Diffo.Provider.Instance`
+  """
+  use Spark.Dsl.Fragment,
+    of: Ash.Resource,
+    otp_app: :diffo,
+    domain: Diffo.Provider,
+    data_layer: AshNeo4j.DataLayer,
+    extensions: [AshJason.Resource]
+
+  attributes do
+    uuid_primary_key :id do
+      description "a uuid4, unique to this relationship, generated by default"
+      public? true
+    end
+
+    attribute :type, :atom do
+      description "the type of the relationship from the source to the target"
+      allow_nil? false
+      public? true
+    end
+
+    attribute :target_href, :string do
+      description "the target href, denormalised from the target instance"
+      allow_nil? true
+      writable? false
+      public? true
+    end
+
+    attribute :target_type, :atom do
+      description "the target type, denormalised from the target instance"
+      allow_nil? true
+      writable? false
+      public? true
+    end
+
+    create_timestamp :created_at
+    update_timestamp :updated_at
+  end
+
+  relationships do
+    belongs_to :source, Diffo.Provider.Instance do
+      description "the source instance which originates this relationship"
+      allow_nil? false
+      public? true
+    end
+
+    belongs_to :target, Diffo.Provider.Instance do
+      description "the target instance which is the destination of this relationship"
+      allow_nil? false
+      public? true
+    end
+  end
+
+  validations do
+    validate {Diffo.Validations.IsUuid4OrNil, attribute: :source_id}, on: :create
+    validate {Diffo.Validations.IsUuid4OrNil, attribute: :target_id}, on: :create
+  end
+
+  actions do
+    defaults [:read, :destroy]
+  end
+end

lib/diffo/provider/components/calculations/assigned_values.ex

@@ -14,13 +14,12 @@ defmodule Diffo.Provider.Calculations.AssignedValues do
     thing = context.arguments[:thing]
 
     Enum.map(records, fn record ->
-      Diffo.Provider.Relationship
+      Diffo.Provider.AssignedToRelationship
       |> Ash.Query.new()
       |> Ash.Query.filter_input(
         source_id: record.instance_id,
         pool: record.name,
-        thing: thing,
-        type: :assignedTo
+        thing: thing
       )
       |> Ash.read!(domain: Diffo.Provider)
       |> Enum.map(& &1.assigned)