ash_neo4j 0.6.0 upgrade + domain extension pattern

Author: matt-beanland

AGENTS.md

@@ -173,15 +173,72 @@ provider do
 end
 ```
 
+## Three usage scenarios
+
+Diffo supports three distinct usage patterns. Every test is tagged with one or more of these
+atoms — absence of all three means the test has not yet been classified.
+
+| Tag | Scenario | Description |
+|-----|----------|-------------|
+| `:provider_only` | Vanilla Provider | Uses `Diffo.Provider` resources as-is. No custom domains, no extensions. Good for basic TMF inventory and for introducing Diffo incrementally. |
+| `:provider_extended` | Extended within Provider | New resource types defined inside `Diffo.Provider` itself, extending base fragments (e.g. `DefinedSimpleRelationship`). Pain point: external users can't add to the Provider domain without forking Diffo. |
+| `:domain_extended` | True domain extension | The **recommended pattern**. An external domain (e.g. `MyApp.SRM`) owns resources using `BaseInstance`, `BaseParty`, `BasePlace`, and `BaseCharacteristic` fragments. Exposes its own API; consumers need not know about Diffo internals. |
+
+Tests may carry `:provider_extended` and `:domain_extended` together when they span both.
+`:provider_only` is mutually exclusive with the other two.
+
+## Domain extension pattern (scenario 3)
+
+Any domain whose resources carry `belongs_to :instance, Diffo.Provider.Instance` (or
+`belongs_to :party, Diffo.Provider.Party`) and use `manage_relationship` to relate them
+**must** include `Diffo.Provider.DomainFragment`:
+
+```elixir
+defmodule MyApp.SRM do
+  use Ash.Domain, fragments: [Diffo.Provider.DomainFragment]
+  ...
+end
+```
+
+**Why this is necessary.** AshNeo4j 0.6.0 matches nodes using
+`label_pair = [domain_label, module_label]`. `Ash.get(Diffo.Provider.Instance, uuid)` builds
+`MATCH (n:Provider:Instance {uuid: $uuid})`. A `ShelfInstance` node in `MyApp.SRM` has
+labels `[:SRM, :ShelfInstance, :Instance]` — `:Provider` is absent, so the lookup returns
+not-found and `manage_relationship` fails.
+
+`Diffo.Provider.DomainFragment` tells AshNeo4j to write `:Provider` as an extra label on
+every node in the domain at CREATE time. `ShelfInstance` then carries
+`[:SRM, :ShelfInstance, :Instance, :Provider]`. Neo4j matches nodes that have **all**
+specified labels regardless of extras, so `MATCH (n:Provider:Instance {uuid: $uuid})` finds
+it. `label_pair` for direct reads on `ShelfInstance` is still `[:SRM, :ShelfInstance]` —
+its own-domain reads remain correctly scoped.
+
+### has_many and the accessing_from path
+
+A separate constraint applies when a `has_many` relationship uses `manage_relationship` on
+the source side: AshNeo4j 0.6.0's `accessing_from` path calls
+`Ash.Resource.Info.reverse_relationship/2`, which does a strict type-equality check. If
+`Characteristic.belongs_to :instance` targets `Diffo.Provider.Instance` but the actual
+source is `ShelfInstance`, the check fails and the edge is not created.
+
+The fix used in Diffo's extension helpers (`Characteristic.relate_instance`,
+`Feature.relate_instance`) is to bypass `manage_relationship` on the source side entirely
+and call `AshNeo4j.Neo4jHelper.relate_nodes/6` directly, using the concrete
+`result.__struct__` label pair. See
+`lib/diffo/provider/components/instance/extension/characteristic.ex` and `feature.ex`.
+
 ## Running tests
 
 Integration tests require a running Neo4j instance.
 
 ```sh
-mix test                          # full suite
-mix test test/provider/extension/ # extension tests only
-mix test path/to/test.exs:LINE    # single test
-mix test --max-failures 5         # stop early
+mix test                              # full suite
+mix test --only domain_extended       # scenario 3 tests only
+mix test --only provider_only         # vanilla provider tests only
+mix test --only provider_extended     # extended-within-provider tests only
+mix test test/provider/extension/     # extension directory only
+mix test path/to/test.exs:LINE        # single test
+mix test --max-failures 5             # stop early
 ```
 
 ## Module naming and Neo4j labels
@@ -256,3 +313,10 @@ not. Add any useful hypotheses as a follow-up comment on the issue, then leave i
   Run `mix format` afterward to verify.
 - Editing content between `<!-- usage-rules-start -->` markers in `CLAUDE.md` — that is
   auto-generated by `mix usage_rules.sync`.
+- Forgetting `Diffo.Provider.DomainFragment` on a scenario 3 domain — any domain whose
+  resources relate back to Provider base types (`belongs_to :instance, Diffo.Provider.Instance`
+  etc.) via `manage_relationship` will get `Ash.Error.Query.NotFound` at runtime without it.
+  See the **Domain extension pattern** section above.
+- Bypassing `manage_relationship` by replacing `argument + manage_relationship` with bare
+  `accept` for relationship IDs in scenario 3 resources — the correct fix is the domain
+  fragment, not removing the relationship management.

lib/diffo/provider/components/party_ref.ex

@@ -51,11 +51,17 @@ defmodule Diffo.Provider.PartyRef do
 
     create :create do
       description "creates a party ref, relating an instance, place or source party to a party"
-      # IDs accepted directly as attributes so AshNeo4j's create_from_attributes path
-      # builds graph edges using the single labels in the relate DSL (:Instance, :Party, :Place).
-      # manage_relationship would fail: it looks up the generic Diffo.Provider.Instance/Party
-      # by label_pair, which doesn't match domain-specific subtypes (ShelfInstance, Person, etc.).
-      accept [:role, :instance_id, :place_id, :source_party_id, :party_id]
+      accept [:role]
+
+      argument :instance_id, :uuid
+      argument :place_id, :string
+      argument :source_party_id, :string
+      argument :party_id, :string
+
+      change manage_relationship(:instance_id, :instance, type: :append_and_remove)
+      change manage_relationship(:place_id, :place, type: :append_and_remove)
+      change manage_relationship(:source_party_id, :source_party, type: :append_and_remove)
+      change manage_relationship(:party_id, :party, type: :append_and_remove)
     end
 
     read :list do

lib/diffo/provider/domain_fragment.ex

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2025 diffo contributors <https://github.com/diffo-dev/diffo/graphs.contributors>
+#
+# SPDX-License-Identifier: MIT
+
+defmodule Diffo.Provider.DomainFragment do
+  @moduledoc """
+  Domain fragment for Ash domains that extend the Diffo Provider.
+
+  Include this fragment in any domain whose resources need to participate in provider
+  polymorphism — i.e., where `belongs_to :instance, Diffo.Provider.Instance` or
+  `belongs_to :party, Diffo.Provider.Party` relationships must resolve via `manage_relationship`.
+
+  Adding this fragment causes AshNeo4j to write `:Provider` as an additional label on every
+  node in the domain at CREATE time. Because AshNeo4j MATCH patterns include all node labels,
+  `Ash.get(Diffo.Provider.Instance, uuid)` (which matches on `[:Provider, :Instance]`) will
+  then find concrete instance nodes (e.g. `ShelfInstance`) that carry both `:Instance` (from
+  `BaseInstance`) and `:Provider` (from this fragment).
+
+  ## Usage
+
+      defmodule MyApp.SRM do
+        use Ash.Domain, fragments: [Diffo.Provider.DomainFragment]
+        ...
+      end
+  """
+  use Spark.Dsl.Fragment,
+    of: Ash.Domain,
+    extensions: [AshNeo4j.DataLayer.Domain]
+
+  neo4j do
+    label :Provider
+  end
+end

test/diffo_test.exs

@@ -5,6 +5,7 @@
 defmodule DiffoTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_only
   doctest Diffo
   doctest Diffo.Unwrap
   doctest Diffo.Type.Primitive

test/provider/characteristic_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.CharacteristicTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_only
   alias Diffo.Test.Patch
   alias Diffo.Type.Value
 

test/provider/defined_simple_relationship_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.DefinedSimpleRelationshipTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_extended
 
   alias Diffo.Type.NameValuePrimitive
   alias Diffo.Type.Primitive

test/provider/entity_ref_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.EntityRefTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_only
   use Outstand
   alias Diffo.Provider.Entity
   alias Diffo.Provider.EntityRef

test/provider/entity_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.EntityTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_only
   use Outstand
 
   setup do

test/provider/event_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.EventTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :provider_only
 
   setup do
     AshNeo4j.Sandbox.checkout()

test/provider/extension/assigner_test.exs

@@ -5,6 +5,7 @@
 defmodule Diffo.Provider.Extension.AssignerTest do
   @moduledoc false
   use ExUnit.Case, async: true
+  @moduletag :domain_extended
   alias Diffo.Provider.Specification
   alias Diffo.Provider.Characteristic
   alias Diffo.Provider.Assignment