agent guidance

Author: matt-beanland

AGENTS.md

@@ -271,6 +271,27 @@ Spark runs two separate pipelines during compilation, in this order:
 
 New transformers go under `transformers:`. New persisters go under `persisters:`.
 
+## DSL shape changes
+
+Whenever you add, rename, or remove a DSL entity or section in `Diffo.Provider.Extension`
+(or any Spark extension in this project), run this checklist in order:
+
+1. **Update `.formatter.exs`** — add new entity names to `spark_locals_without_parens` with
+   each supported arity. Without this, `mix format` will add unwanted parentheses to every
+   DSL call site.
+
+2. **Run `mix format`** — apply formatting across the codebase and verify the output looks
+   correct. Run `mix format --check-formatted` to confirm nothing was missed.
+
+3. **Run `mix spark.cheat_sheets`** — regenerates
+   `documentation/dsls/DSL-Diffo.Provider.Extension.md`. This file is Spark-generated;
+   never edit it by hand. Commit the regenerated file alongside the DSL change.
+
+4. **Run `mix test`** — confirm no regressions.
+
+Do not skip step 1 even for a "small" entity addition — the formatter will silently reformat
+every call site in CI and produce noisy diffs in future PRs.
+
 ## Raising upstream bugs
 
 When a bug is found in a dependency (e.g. AshNeo4j, Bolty), raise a GitHub issue on that
@@ -309,11 +330,8 @@ not. Add any useful hypotheses as a follow-up comment on the issue, then leave i
 - Using module names (e.g. `MyApp.CardInstance`) as role values in `relationships do` — roles are atoms like `:provides`, not module references.
 - Forgetting that `relationships do` omitted means `:none` for both source and target — any update action with `argument :relationships, {:array, :struct}` will fail unless the resource declares permissions.
 - Thinking the Assigner requires `relationships do` permissions — it does not. The Assigner writes `DefinedSimpleRelationship` records directly via the Provider domain; `ValidateRelationshipPermitted` only runs on actions that carry `argument :relationships, {:array, :struct}`, which the Assigner's `assign_*` actions do not.
-- Editing `documentation/dsls/DSL-Diffo.Provider.Extension.md` — it is Spark-generated;
-  run `mix spark.cheat_sheets` to regenerate it. Whenever you add, rename, or remove a DSL
-  entity or section, also check `.formatter.exs` — new entity names must be added to
-  `spark_locals_without_parens` (with each arity) so the Spark formatter omits parentheses.
-  Run `mix format` afterward to verify.
+- Editing `documentation/dsls/DSL-Diffo.Provider.Extension.md` — it is Spark-generated.
+  See the **DSL shape changes** section above for the full checklist.
 - 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

documentation/dsls/DSL-Diffo.Provider.Extension.md

@@ -103,11 +103,13 @@ 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
@@ -330,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
@@ -346,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
@@ -483,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
@@ -500,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
@@ -637,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