diffo-dev · matt-beanland · May 20, 2026 · May 17, 2026 · May 17, 2026 · May 17, 2026
diff --git a/.formatter.exs b/.formatter.exs
@@ -15,6 +15,11 @@ spark_locals_without_parens = [
   feature: 1,
   feature: 2,
   id: 1,
+  inherited_party: 1,
+  inherited_party: 2,
+  inherited_place: 1,
+  inherited_place: 2,
+  instance_ref: 2,
   is_enabled?: 1,
   major_version: 1,
   minor_version: 1,
@@ -23,14 +28,21 @@ spark_locals_without_parens = [
   parties: 3,
   party: 2,
   party: 3,
+  party_ref: 2,
+  party_ref: 3,
   patch_version: 1,
   place: 2,
   place: 3,
+  place_ref: 2,
+  place_ref: 3,
   places: 2,
   places: 3,
+  pool: 2,
   reference: 1,
   role: 2,
   role: 3,
+  source: 1,
+  target: 1,
   tmf_version: 1,
   type: 1,
   update: 1,

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,54 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline
 
 <!-- changelog -->
 
+## [v0.4.0](https://github.com/diffo-dev/diffo/compare/v0.3.0...v0.4.0) (2026-05-20)
+
+### Breaking Changes
+
+* `Diffo.Provider.AssignedToRelationship` replaced by `Diffo.Provider.AssignmentRelationship` — stores pool assignments with top-level `pool`, `thing`, `value`, and `alias` scalar attributes, enabling graph-level filtering in AshNeo4j queries. Any existing graph data on `AssignedToRelationship` nodes must be migrated.
+* `create_assigned_to_relationship` code interface removed — use `create_assignment_relationship` instead.
+* `instance.assignments` now returns `AssignmentRelationship` records (struct name change only).
+
+### Features
+
+* **`DefinedSimpleRelationship`** — new resource for relationships carrying an optional single embedded `NameValuePrimitive` characteristic, frozen at creation. Used by the Assigner and available as a general-purpose committed-relationship primitive. Accessible via `instance.assignments`.
+* **`AssignmentRelationship` aliases** — the `alias` attribute on `AssignmentRelationship` (identity `[:target_id, :alias]`) gives a consuming instance a stable name for an assignment slot. Mirrors the `[:source_id, :alias]` identity on `DefinedSimpleRelationship`. Alias semantics are the foundation of the first-order expectation system (#74).
+* **`relationships do` DSL** — source and target validation pipeline for Instance resources. `ValidateRelationshipPermitted` is injected automatically into relate actions. Supports `:all`, `:none`, and explicit role-name lists.
+* **Resource lifecycle states** — `resource_state` attribute on Instance resources with standard TMF states (`:installed`, `:operating`, `:retired`, etc.). The Assigner enforces `:operating` before allowing assignment.
+* **`inherited_place` / `inherited_party` DSL** — declare inside `places do` / `parties do` on an Instance resource to generate an Ash calculation that traverses the assignment graph by alias and inherits a place or party from the source instance. No `PlaceRef`/`PartyRef` edge is created — the calculation is the reference. Supports single-hop (default: role name as alias) and multi-hop (`via:` list).
+* **`FieldFromAssignment`** (`Diffo.Provider.Calculations.FieldFromAssignment`) — reads a field directly from an `AssignmentRelationship` record (`:value`, `:pool`, `:thing`, `:alias`). Filtered by optional `alias:`. Returns a list.
+* **`FieldViaAssignedRelationship`** (`Diffo.Provider.Calculations.FieldViaAssignedRelationship`) — traverses `AssignmentRelationship` in reverse (target → source) and reads a named field from each source instance. Supports multi-hop `via:` traversal. Returns a list.
+* **`FieldViaRelationship`** (`Diffo.Provider.Calculations.FieldViaRelationship`) — traverses `DefinedSimpleRelationship` forward (source → target) filtered by optional `alias:` and/or `type:`, and reads a named field from each target instance. Returns a list.
+
+### Notable Changes
+
+* Assigner rearchitected — `AssignmentRelationship` carries `pool`, `thing`, `value`, `alias` as top-level attributes for AshNeo4j-level filtering; `assigned_values` and `free_values` use query-level filtering rather than in-memory computation where possible.
+* `TransformBehaviour` moved from persister pipeline to transformer pipeline for correct Spark ordering relative to Ash's own transformers.
+* Characteristic type verifier improved — rejects `characteristic` DSL declarations whose type module is not derived from `BaseCharacteristic`.
+
+### Documentation
+
+* `usage-rules.md` — new sections covering alias semantics, `inherited_place`/`inherited_party` DSL, and all three field calculation modules including a decision table.
+* `AGENTS.md` — updated project structure, DSL inline examples for inherited refs, and new common mistakes section entries.
+* Provider Extension livebook — new section "Aliases, Inherited DSL, and Field Calculations" with Compute-domain examples.
+
+### What's Changed
+
+* defined_simple_relationship by @matt-beanland in https://github.com/diffo-dev/diffo/pull/142
+* refactored assigner using defined_simple_relationship by @matt-beanland in https://github.com/diffo-dev/diffo/pull/143
+* relationships DSL by @matt-beanland in https://github.com/diffo-dev/diffo/pull/146
+* relationships target side validation by @matt-beanlanda in https://github.com/diffo-dev/diffo/pull/148
+* clean code by @matt-beanland in https://github.com/diffo-dev/diffo/pull/150
+* improved assigner using aggregates by @matt-beanland in https://github.com/diffo-dev/diffo/pull/151
+* refactor transformers and persisters by @matt-beanland in https://github.com/diffo-dev/diffo/pull/152
+* resource lifecycle state by @matt-beanland in https://github.com/diffo-dev/diffo/pull/154
+* inherited party and place via instance DSL by @matt-beanland in https://github.com/diffo-dev/diffo/pull/155
+* agent guidance by @matt-beanland in https://github.com/diffo-dev/diffo/pull/161
+* FieldViaAssignedRelationship calculation by @matt-beanland in https://github.com/diffo-dev/diffo/pull/162
+* FieldViaRelationship calculation by @matt-beanland in https://github.com/diffo-dev/diffo/pull/165
+* FieldFromAssignment calculation by @matt-beanland in https://github.com/diffo-dev/diffo/pull/164
+* docs pass — inherited DSL, aliases, and field calculations by @matt-beanland in https://github.com/diffo-dev/diffo/pull/166
+
 ## [v0.3.0](https://github.com/diffo-dev/diffo/compare/v0.2.2...v0.3.0) (2026-05-17)
 
 ### Breaking Changes

diff --git a/documentation/dsls/DSL-Diffo.Provider.Extension.md b/documentation/dsls/DSL-Diffo.Provider.Extension.md
@@ -103,14 +103,19 @@ Provider DSL — structure, roles, and behaviour for this resource kind
    * parties
    * party_ref
    * role
+   * inherited_party
  * [places](#provider-places)
    * place
    * places
    * place_ref
    * role
+   * inherited_place
  * [instances](#provider-instances)
    * role
    * instance_ref
+ * [relationships](#provider-relationships)
+   * source
+   * target
  * [behaviour](#provider-behaviour)
    * actions
      * create
@@ -327,13 +332,14 @@ Declares an assignable pool — a named range of values for auto-assignment
 
 
 ### provider.parties
-Party roles on this resource — `party`/`parties`/`party_ref` for Instance kinds; `role` for Party and Place kinds
+Party roles on this resource — `party`/`parties`/`party_ref`/`inherited_party` for Instance kinds; `role` for Party and Place kinds
 
 ### Nested DSLs
  * [party](#provider-parties-party)
  * [parties](#provider-parties-parties)
  * [party_ref](#provider-parties-party_ref)
  * [role](#provider-parties-role)
+ * [inherited_party](#provider-parties-inherited_party)
 
 
 ### Examples
@@ -343,6 +349,7 @@ parties do
   party :provider, MyApp.Provider
   party_ref :owner, MyApp.InfrastructureCo
   parties :technicians, MyApp.Technician, constraints: [min: 1]
+  inherited_party :customer, source_role: :owner
 end
 
 # Party or Place
@@ -480,15 +487,48 @@ Declares a role this Party or Place kind plays with respect to other Parties
 
 Target: `Diffo.Provider.Extension.PartyRole`
 
+### provider.parties.inherited_party
+```elixir
+inherited_party role
+```
+
+
+Declares a party derived by traversing the assignment graph — generates a calculation, no PartyRef node created
+
+
+
+
+
+### Arguments
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`role`](#provider-parties-inherited_party-role){: #provider-parties-inherited_party-role .spark-required} | `atom` |  | The role name — also the default alias to follow on AssignmentRelationship. |
+### Options
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`source_role`](#provider-parties-inherited_party-source_role){: #provider-parties-inherited_party-source_role .spark-required} | `atom` |  | The PartyRef role to pick up on the arrived-at instance. |
+| [`via`](#provider-parties-inherited_party-via){: #provider-parties-inherited_party-via } | `list(atom)` |  | Sequence of assignment aliases to traverse. Defaults to [role] for single-hop. Use a list for multi-level. |
+
+
+
+
+
+### Introspection
+
+Target: `Diffo.Provider.Extension.InheritedPartyDeclaration`
+
 
 ### provider.places
-Place roles on this resource — `place`/`places`/`place_ref` for Instance kinds; `role` for Party and Place kinds
+Place roles on this resource — `place`/`places`/`place_ref`/`inherited_place` for Instance kinds; `role` for Party and Place kinds
 
 ### Nested DSLs
  * [place](#provider-places-place)
  * [places](#provider-places-places)
  * [place_ref](#provider-places-place_ref)
  * [role](#provider-places-role)
+ * [inherited_place](#provider-places-inherited_place)
 
 
 ### Examples
@@ -497,6 +537,8 @@ Place roles on this resource — `place`/`places`/`place_ref` for Instance kinds
 places do
   place :installation_site, MyApp.GeographicSite
   place_ref :billing_address, MyApp.GeographicAddress
+  inherited_place :a_end, source_role: :location
+  inherited_place :poi, via: [:cvc_link, :nni_link], source_role: :poi
 end
 
 # Party or Place
@@ -634,6 +676,38 @@ Declares a role this Party or Place kind plays with respect to Places
 
 Target: `Diffo.Provider.Extension.PlaceRole`
 
+### provider.places.inherited_place
+```elixir
+inherited_place role
+```
+
+
+Declares a place derived by traversing the assignment graph — generates a calculation, no PlaceRef node created
+
+
+
+
+
+### Arguments
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`role`](#provider-places-inherited_place-role){: #provider-places-inherited_place-role .spark-required} | `atom` |  | The role name — also the default alias to follow on AssignmentRelationship. |
+### Options
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`source_role`](#provider-places-inherited_place-source_role){: #provider-places-inherited_place-source_role .spark-required} | `atom` |  | The PlaceRef role to pick up on the arrived-at instance. |
+| [`via`](#provider-places-inherited_place-via){: #provider-places-inherited_place-via } | `list(atom)` |  | Sequence of assignment aliases to traverse. Defaults to [role] for single-hop. Use a list for multi-level. |
+
+
+
+
+
+### Introspection
+
+Target: `Diffo.Provider.Extension.InheritedPlaceDeclaration`
+
 
 ### provider.instances
 Declares the roles this Party or Place kind plays with respect to Instances
@@ -712,6 +786,75 @@ Declares a reference instance role — no direct edge created, reachable by grap
 Target: `Diffo.Provider.Extension.InstanceRole`
 
 
+### provider.relationships
+Relationship role permissions for this Instance — declares which aliases it may participate in as source or target. Omitting defaults to `:none` per direction.
+
+### Nested DSLs
+ * [source](#provider-relationships-source)
+ * [target](#provider-relationships-target)
+
+
+### Examples
+```
+relationships do
+  source [:provides, :requires]
+  target :all
+end
+
+```
+
+
+
+
+### provider.relationships.source
+```elixir
+source roles
+```
+
+
+Declares permitted source relationship roles — pipeline step, last declaration wins
+
+
+
+
+
+### Arguments
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`roles`](#provider-relationships-source-roles){: #provider-relationships-source-roles .spark-required} | `any` |  | `:all`, `:none`, or a list of role name atoms. |
+
+
+
+
+
+
+
+### provider.relationships.target
+```elixir
+target roles
+```
+
+
+Declares permitted target relationship roles — pipeline step, last declaration wins
+
+
+
+
+
+### Arguments
+
+| Name | Type | Default | Docs |
+|------|------|---------|------|
+| [`roles`](#provider-relationships-target-roles){: #provider-relationships-target-roles .spark-required} | `any` |  | `:all`, `:none`, or a list of role name atoms. |
+
+
+
+
+
+
+
+
 ### provider.behaviour
 Defines the behavioural wiring for the Instance — actions, and in future triggers