Allow nested arg resolvers to run before parent model is saved

[spawnia]

Summary

Adds SaveAwareArgResolver interface (@api) that lets ArgResolver directives declare whether they run before or after the parent model is saved during mutation execution.

Motivation

For BelongsTo relations, the FK lives on the parent model and must be set before $model->save().
The existing implicit detection in SaveModel handles this for known relation methods, but there was no way for custom directives to participate in the pre-save phase.

SaveAwareArgResolver is the extension point: any directive implementing it can control its execution timing relative to $model->save().

Design decisions

NestDirective becomes a pure marker — ResolveNested handles recursion directly, creating a fresh instance without SaveModel to prevent double-saves at each nesting level. Pre-save resolvers inside @nest are recursively lifted to the top level by ArgPartitioner::liftPreSaveResolversFromNest().

@nest now validates at schema build time that it is used on a non-list input object type (via ArgManipulator and InputFieldManipulator).

runBeforeSave(Model $model) is class-based, not instance-dependent — the model may not yet be hydrated when this is called. Implementations must base the decision on the model class and its relations.

When runBeforeSave() returns true, __invoke() may receive null as $value if the client sends null for a nullable input field.

Documentation

• New SaveAwareArgResolver section in docs/master/custom-directives/input-value-directives.md with usage example
• @nest directive reference notes the type constraint
• ArgResolver interface PHPDoc improved with description and @see reference

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new resolver marker interface to control nested mutation execution ordering, enabling relation directives to run nested resolvers either before or after the parent model is persisted. This is aimed at preventing NOT NULL FK violations for BelongsTo nested mutations by setting the FK prior to saving.

Changes:

• Introduce PreSaveArgResolver to mark nested arg resolvers that must run before the parent model is saved.
• Update ResolveNested to split nested resolvers into pre-save vs post-save execution phases.
• Extend @belongsTo and @hasOne to support INPUT_FIELD_DEFINITION and act as nested arg resolvers.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/Support/Contracts/PreSaveArgResolver.php	Adds a marker interface to indicate pre-save nested arg resolution.
src/Execution/Arguments/ResolveNested.php	Partitions nested resolvers into pre-save/post-save and changes execution order accordingly.
src/Schema/Directives/BelongsToDirective.php	Enables @belongsTo on input fields and implements pre-save nested resolver behavior.
src/Schema/Directives/HasOneDirective.php	Enables @hasOne on input fields and implements nested resolver behavior (post-save).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.