relationships dsl

[matt-beanland]

Motivation

Instance-to-instance relationship roles have no compile-time contract today. We want a structural declaration — what roles this Instance kind may participate in, and with what target kind — introspectable at runtime, the same way parties/0 and places/0 are today.

Enforcement (validating that only declared roles are used, auto-wiring in build_after, multiplicity constraints) is behaviour and is out of scope until the expectations model is settled.

Proposed DSL

```elixir
provider do
relationships do
relationship :provides, MyApp.BackboneService
relationship :requires, MyApp.AccessService
relationship_ref :peer, MyApp.AccessService # reference — no direct edge
end
end
```

Scope

• RelationshipDeclaration struct (name, instance_type, reference)
• PersistRelationships — bakes relationships/0 and relationship/1 onto the module
• VerifyRelationships — compile-time: no duplicate role names, target is a BaseInstance-derived resource
• instance_transformer_test.exs coverage
• AGENTS.md and usage-rules.md updated

Explicitly deferred

• Enforcement via relate_instance/2 or VerifyBehaviour
• Auto-wiring in build_after
• Multiplicity constraints
• Reverse-side declaration (target-side instances do equivalent)

[matt-beanland]

Implementation plan

Modelled directly on the parties and places pattern.

1. RelationshipDeclaration struct

defstruct [:name, :instance_type, :constraints, __spark_metadata__: nil]

Lives in lib/diffo/provider/extension/relationship_declaration.ex.

2. DSL entities in extension.ex

Two entities under a relationships do section, mirroring party/parties:

• relationship :requires, AccessService — singular, implies exactly one (1:1 by convention)
• relationships :provides, CircuitInstance — plural, unconstrained by default
• relationships :provides, CircuitInstance, constraints: [min: 1, max: 2] — explicitly bounded

The role name describes the relationship type generically (e.g. :provides, :requires). Multiple runtime Relationship records of the same role are natural — a composite service providing two circuits would have two :provides relationships, both targeting CircuitInstance.

Omitting constraints means unconstrained (0..n). min defaults to 0.

3. PersistRelationships transformer

Mirrors PersistParties — bakes relationships/0 and relationship/1 helper functions onto the module at compile time.

4. VerifyRelationships verifier

Checks:

• No duplicate role names
• instance_type module exists (Code.ensure_loaded?)
• instance_type extends BaseInstance (Info.instance?/1)

Registered in extension.ex alongside the other verifiers.

5. Info.relationships/1 and Info.relationship/2

Add to Diffo.Provider.Extension.Info via Spark.InfoGenerator (automatic from the section declaration).

6. Tests

In instance_transformer_test.exs (baking) and instance_verifier_test.exs (duplicate role, non-existent module, non-BaseInstance module).

7. AGENTS.md and usage-rules.md

Add relationship/relationships to the provider DSL cheat sheet.

Out of scope (per issue)

Enforcement of constraints in relate_instance/2, auto-wiring in build_after, reverse-side declaration.

[matt-beanland]

Update: dropping relationship_ref — instance-to-instance relationships always go through a Relationship node, so there is no meaningful direct vs reference distinction at this level. The DSL will have a single relationship entity only.

[matt-beanland]

Constraint defaulting: omitting constraints means the relationship is unconstrained (0..n). min defaults to 0, not 1. Explicit constraints are only needed when you want to bound the multiplicity.

[matt-beanland]

Versioning consideration: relationship declarations reference specific modules, which are major-version-pinned. A CircuitInstance → CircuitInstanceV2 bump requires updating every instance kind that declares relationships :provides, CircuitInstance. The blast radius is potentially larger than for parties/places since relationships span more instance kinds.\n\nImportantly, this problem does not exist for parties and places — Party and Place resources have no specification concept and no major version, so there is no OrganizationV2 scenario. The versioning trap is unique to instance-to-instance relationships.\n\nA future option is to declare by specification name (e.g. relationships :provides, "circuit") which is stable across major versions — the verifier would resolve the name to a known BaseInstance-derived module at compile time. This is the more natural key since both sides are instance kinds with stable specification names. Noting as a known limitation for now and a strong candidate for the final design.

[matt-beanland]

External relationships (future): currently only internal relationships are supported — both instances live in the same graph and the target is resolved by UUID. External relationships (target is an instance in another system, referenced by href) are a future requirement. For external relationships the target cannot be resolved to a known module, so the declaration would need a different form — likely just a role name and a TMF specification name/version as a string, with no compile-time module resolution. The internal-only constraint should be noted in the DSL documentation.

[matt-beanland]

ok, we are going to stop/change spec here.
Most important things are, as an instant, do I allow relationships with other instances?
Split is forward (outgoing), reverse (incoming).
Do I allow myself to permanently relate to others? how
Do I allow others to permanently relate to me? how
By default we should not.
We can then allow all, or allow particular roles in each direction.
source - target, me-other. use existing terminology, don' t confuse terms from

The AssignedToRelationship is a bad smell. It really is a collapsed since characteristic primitive value Relationship, which is immutable. ImmutableSimpleRelationship. We'll raise a card to refactor that first, as it will help us with our DSL.

raised #140 and #141 and will come back then with more insight.

[matt-beanland]

Updated design (post #140/#141)

DSL shape

relationships do
  source [:provides, :requires]   # allow these roles when I am the source
  source :all                     # or allow all
  target [:hosted_by]             # allow these roles when I am the target
  # omitting a direction defaults to :none (deny all)
end

• source and target are pipeline steps — repeatable, applied in order, last applicable wins
• Each step takes :all, :none, or an explicit list of role atoms
• No module references — role names only, no target type constraint (preserves polymorphism)
• Omitting relationships do entirely means deny all in both directions

Why pipeline steps

Modelled on AshJason's pick — steps compose, run in declared order, and leave room for future steps (aliases, expectations, external relationships, agent negotiation) without redesigning the DSL.

Runtime enforcement

TransformRelationships (registered under transformers:) resolves the pipeline at compile time into two sets — permitted_source_roles/0 and permitted_target_roles/0 — baked as module functions. It also injects a ValidateRelationshipPermitted change into the relate_instance action on BaseInstance. Enforcement is automatic — callers do not wire it up themselves.

Struct

%RelationshipStep{direction: :source | :target, roles: :all | :none | [:atom]}

relationships/0 returns the ordered list of steps. permitted_source_roles/0 and permitted_target_roles/0 return the resolved sets.

Transformer placement

TransformRelationships goes under transformers: in extension.ex — the first module correctly placed there. TransformBehaviour remains in persisters: for now (tracked in #144).

Scope

• RelationshipStep struct
• source/target DSL entities under relationships do
• TransformRelationships — resolves pipeline, bakes functions, injects ValidateRelationshipPermitted
• VerifyRelationships — no duplicate role names per direction, valid as: values
• ValidateRelationshipPermitted — the injected change
• Tests, AGENTS.md, usage-rules.md

Deferred

• Constraints, aliases, expectations
• External relationships
• Reverse-side declaration
• Agent negotiation

[matt-beanland]

Design update — enforcement in scope

Consent model

The relationships do pipeline IS consent — baked into the specification at compile time. Both sides must declare willingness:

• The source declares what roles it may initiate (source [...])
• The target declares what roles it will accept (target [...])

Either side denying blocks the relationship. Neither side can be forced. This is symmetric opt-in.

Runtime agent negotiation happens at the specification level — agents discuss DSL evolution ("I need you to add :hosted_by to your target roles"), which surfaces as a new specification version. The instance just enforces what its specification declared. There is no runtime consent mechanism — the static declaration is the right model permanently.

Validation — both sides checked by the source

ValidateRelationshipPermitted runs as a proper Ash.Resource.Validation injected into relate_instance by TransformRelationships:

1. Checks source_module.permitted_source_roles/0 — does the source permit this role outgoing?
2. Loads the target instance, gets its module, checks target_module.permitted_target_roles/0 — does the target permit this role incoming?

Both checks run on the source side. The source honours the target's compiled declaration on its behalf. Either failing returns a clean Ash validation error.

Compiled functions baked by TransformRelationships

• relationships/0 — the raw ordered pipeline of %RelationshipStep{} structs (for introspection)
• permitted_source_roles/0 — resolved set: :all, :none, or MapSet of atoms
• permitted_target_roles/0 — resolved set: :all, :none, or MapSet of atoms

Resolution walks the pipeline left to right, last step wins.

Transformer placement

TransformRelationships goes under transformers: in extension.ex — correctly classified per pipeline rules (see #144). It both resolves/bakes and injects the validation — one module, no separate persister needed.

Full scope for this card

• RelationshipStep struct (direction, roles)
• source/target DSL entities under relationships do
• TransformRelationships — resolves pipeline, bakes three functions, injects ValidateRelationshipPermitted into relate_instance
• VerifyRelationships — no duplicate roles per direction, valid role atoms
• ValidateRelationshipPermitted — Ash.Resource.Validation, checks both sides
• Tests: transformer (baking), verifier (compile errors), integration (enforcement)
• AGENTS.md and usage-rules.md updated

Deferred

• Constraints, aliases, expectations
• External relationships
• Reverse-side declaration on relate_instance target

[matt-beanland]

raised #145 as we aren't enforcing the target side, perhaps could be done by introspection.

[matt-beanland]

Adds a relationships do section to the Diffo.Provider.Extension DSL, giving Instance resources declarative control over which relationship roles they permit as source or target.

What was built

DSL — A new relationships do section with source and target pipeline steps. Each step accepts :all, :none, or a list of role name atoms. Multiple declarations for the same direction are resolved last-wins, matching the intent of a pipeline. Omitting the section entirely defaults to :none for both directions.

Transformer — TransformRelationships runs at compile time and bakes three functions onto every module using the extension: relationships/0 (raw pipeline steps), permitted_source_roles/0, and permitted_target_roles/0. Correctly registered under transformers: (not persisters:).

Verifier — VerifyRelationships rejects non-atom role values and empty role lists at compile time with a Spark.Error.DslError.

Runtime enforcement — ValidateRelationshipPermitted is added as a resource-level change on BaseInstance with on: [:update]. It self-skips when no :relationships argument is present, so it has zero cost on non-relate actions. Currently enforces source-side permissions only; target-side enforcement is tracked separately as issue #145.

RelationshipStep struct — thin struct holding direction, roles, and spark_metadata (required by Spark to suppress deprecation warnings).

Test resources updated

ShelfInstance gained source :all and CardInstance gained target :all to opt in to the new defaults, since omitting the section now means :none.

Tests

Twelve tests across three describe blocks covering transformer baking, last-wins pipeline resolution, default :none on resources with no section, compile-time verifier errors, and integration enforcement of both the permit and reject paths.

Docs and tooling

AGENTS.md — project structure, DSL example, common mistakes, and a new rule linking formatter review to cheat sheet regeneration
usage-rules.md — new relationships do section with table, pipeline explanation, generated functions list, and common mistakes
documentation/how_to/use_diffo_provider_extension.livemd — livebook resources updated to declare relationships, stale AssignedToRelationship references corrected throughout
.formatter.exs — added source: 1, target: 1, and several previously missing entries (pool: 2, party_ref: 2/3, place_ref: 2/3, instance_ref: 2)
mix spark.cheat_sheets and mix usage_rules.sync run to regenerate all derived artefacts