relationships - target side validation

[matt-beanland]

Background

ValidateRelationshipPermitted currently enforces source-side permissions only — it calls permitted_source_roles/0 on the changeset's own resource and rejects the action if the role isn't allowed.

Target-side enforcement is missing: a resource with target :none can still be related to by any source, because the change only runs on the source's update action and has no way to resolve the target's resource module from its record ID alone.

The gap

When relate_shelf runs with a CardInstance as the target, we call ShelfInstance.permitted_source_roles/0 ✓. We do not call CardInstance.permitted_target_roles/0 ✗. A CardInstance with target :none would silently accept incoming relationships.

Implementation plan — runtime introspection, no registry needed

All the information we need is available at runtime. No compile-time registry required.

How it works

At the point ValidateRelationshipPermitted runs, we have changeset.domain. The approach:

1. Call Ash.Domain.Info.resources(changeset.domain) to enumerate all resource modules in the domain.
2. Filter to those that export permitted_target_roles/0 (via function_exported?(module, :permitted_target_roles, 0)) — these are all Instance resources using the provider extension.
3. For each relationship in the :relationships argument, try Ash.get(module, rel.id, domain: domain, authorize?: false) across candidate modules until one returns {:ok, record}.
4. Call module.permitted_target_roles/0 on the resolved module and check the relationship alias against it.
5. If no module resolves the ID, fail with a clear error.

Cost

O(N queries) in the number of Instance resource types in the domain per relationship — in practice a small, bounded number. Only fires on update actions that carry argument :relationships, {:array, :struct}.

Future optimisation (not required)

If the O(N) cost becomes a concern, build a %{spec_uuid => module} lookup map at startup from all modules that export specification_id/0. The Specification instance data is the natural registry key since it is already the stable identifier for a resource kind. This would make resolution O(1). Defer until benchmarking shows it is needed.

Acceptance criteria

• A resource with target :none rejects incoming relationships at the source's relate action.
• A resource with target :all accepts them.
• A resource with target [:consumes] only accepts relationships whose alias matches.
• Unit test: relate_shelf targeting a CardInstance with target :none fails with "not permitted as target".
• Unit test: same action targeting a CardInstance with target :all succeeds.
• Existing source-side tests continue to pass unchanged.

[matt-beanland]

Target-side validation is implemented and working (branch 145-relationships---target-side-validation), but the current implementation resolves the target's specification via a raw AshNeo4j.Cypher.run call — which couples Diffo's change layer directly to the data layer and is not acceptable long-term.

The correct approach is to use Ash.get to load the target instance and read specification_id from it. This is blocked by a bug in AshNeo4j where belongs_to FK attributes are not populated on reads: diffo-dev/ash_neo4j#258.

Once that is fixed, ValidateRelationshipPermitted.resolve_target_module/3 should be updated to use Ash.get instead of the raw Cypher query.

[matt-beanland]

ash_neo4j 0.6.0 upgrade + domain extension pattern

Upgraded to ash_neo4j 0.6.0, which changed all MATCH operations to use a two-label pair [domain_label, module_label] instead of the single resource label used in 0.5.x. This broke several things in the test suite that relied on the old single-label polymorphic matching.

Fixes applied

Specification.relate_instance — cleared specification_id before calling for_update to prevent Ash seeing old == new and generating a spurious remove step on a non-existent edge.
Characteristic.relate_instance and Feature.relate_instance — bypassed manage_relationship on the has_many source side. The 0.6.0 accessing_from path requires Ash.Resource.Info.reverse_relationship to find a matching reverse relationship using strict type equality; with polymorphic base types this always returns nil. Both helpers now call AshNeo4j.Neo4jHelper.relate_nodes/6 directly using the concrete resource's label pair.
Introduced Diffo.Provider.DomainFragment — a Spark domain fragment that writes :Provider as an additional label on every node in a domain at CREATE time. Applied it to Diffo.Test.Servo and Diffo.Test.Nbn. This enables Ash.get(Diffo.Provider.Instance, uuid) to find concrete subtypes like ShelfInstance because Neo4j matches nodes carrying all specified labels regardless of extras, so MATCH (n:Provider:Instance) finds any node with both :Provider and :Instance labels.
Test classification

Tagged all 38 test files with one or more of :provider_only, :provider_extended, :domain_extended to classify three supported usage scenarios. Tags compose; absence means unclassified. Runnable with mix test --only domain_extended etc.

Documentation

Updated AGENTS.md with the three-scenario taxonomy, domain fragment pattern and the accessing_from bypass rationale. Updated usage-rules.md to mandate the domain extension pattern as the recommended usage, require Diffo.Provider.DomainFragment in consumer domains with explanation of why, state the Neo4j browser observation policy, and update all examples to use a consistent MyApp.SRM domain.

648 tests, 0 failures.

now know ash_neo4j 0.6.0 is good and supports the domain extension/polymorphism required by diffo.
next we remove the cypher in diffo as this is an anti-pattern, we should be using aggregates/calculations which run in the datalayer whenever possible.

[matt-beanland]

ValidateRelationshipPermitted was implemented as an Ash.Resource.Change, which is semantically wrong — it had no side effects and existed only to decide valid or invalid. It also short-circuited on source errors, skipping target validation entirely, which meant a developer could only discover one class of problem per attempt.

Both issues are now fixed:

Moved to Ash.Resource.Validation.
The module is renamed Diffo.Provider.Validations.ValidateRelationshipPermitted, lives under lib/diffo/provider/validations/, and implements init/1 and validate/3. BaseInstance registers it under validations do rather than changes do. The old changes/ folder is removed.

Full error accumulation.
Source and target checks now always both run. All errors are collected and returned together as a list, consistent with Ash's Splode accumulation model. A developer misconfiguring relationship permissions sees every problem in one pass rather than one at a time.

AGENTS.md updated with two new entries in Common Agent Mistakes: one on writing fail-fast validations instead of accumulating errors, and one on using Change for what should be a Validation.

All 648 tests pass.