party and place inheritance via instance DSL

[matt-beanland]

Title: Party inheritance via relationship path in the instances DSL

Description

Currently, when a resource needs to record party ownership it does so explicitly — storing the party's id as an attribute (e.g. rsp_id) and wiring it up manually in a change. This works for a flat ownership model but breaks down when ownership is implicit in the graph topology.
In the NBN domain, an RSP owns NNI Groups directly. Everything beneath that — CVCs, AVCs, NNIs — belongs to the same RSP by virtue of how it relates back through the graph. There is no meaningful sense in which an AVC is independently owned; its ownership is inherited from the NNI Group it terminates at.
The same pattern applies to Place. A resource located at a place that belongs to a party should be able to inherit that party context without redundantly recording it as an attribute.

What we need

The instances DSL should support declaring that a party relationship is inherited through a named relationship path, with the ability to assign a local role that may differ from the role the party holds on the parent. For example:

instances do
  inherit_party :operator, from: :owner, via: :reverse_relationships
end

This would tell diffo that the owning party is resolved by following the given relationship, inheriting the party context from the related resource rather than recording it as a local attribute.

Why it matters

Without this, every resource in a topology must independently store and maintain party ownership — creating redundant data, extra edges or attributes, and a maintenance burden when ownership changes. Inheritance through the graph reflects how ownership actually works in network domains, and keeps the model honest.

This is also relevant to how Place relates to Party — the same inheritance semantics apply wherever party context flows through a relationship rather than being directly asserted.

[matt-beanland]

The idea here is that the extended Party behaves as if the party was directly related in the role. Maybe the right way to do this is still with a PartyRef, and PartyRef has an indirect option where it handles the indirection (in BaseParty). So it loads PartyRef-Party, but goes to the datalayer twice as they won't be related (has-none relationship :-).

[matt-beanland]

Actually thinking the right way to do this is that the transformer injects an Ash calculation, however it will need to traverse via relationship, where it will need an alias on the relationship (and in the dsl).

[matt-beanland]

Full design: inherited_place and inherited_party DSL + Ash Calculation

Covers both parties and places. The approach: new DSL declarations (inherited_place, inherited_party) inside places do / parties do that the transformer converts into Ash Calculations on the instance. No intermediate node (PlaceRef/PartyRef) is created for inherited cases — the calculation returns the Place or Party directly. The role name is the calculation name on the instance.

DSL — places

places do
  place :location, MyPlace              # direct: Instance → PlaceRef → Place (node in graph)

  inherited_place :a_end,              # indirect: calculation on instance, no node
    source_role: :location             # PlaceRef role to pick up from the source instance
    # via: defaults to :a_end — follows AssignmentRelationship where alias == :a_end
end

Multi-level (e.g. AVC → CVC → NNIGroup → POI place):

inherited_place :poi,
  via: [:cvc_link, :nni_link],         # aliases to follow in sequence
  source_role: :poi

DSL — parties

parties do
  party :customer, MyApp.Customer         # direct
  inherited_party :owner,                 # indirect: calculation, no node
    source_role: :customer               # PartyRef role to follow on the source instance
end

Traversal (4 hops per level)

Instance ←[target_id]— AssignmentRelationship {alias: :a_end} —[source_id]→ Instance —→ PlaceRef/PartyRef {role: :location} —→ Place/Party

Each hop is a typed Ash query — no raw Cypher. Multi-level is an iterative fold over the via path list. via defaults to a single-element list containing the declaration name.

Calculation (generated by transformer)

def calculate(records, opts, _context) do
  path = List.wrap(opts[:via])
  source_role = opts[:source_role]

  Enum.map(records, fn record ->
    final_ids =
      Enum.reduce(path, [record.id], fn alias_step, ids ->
        Enum.flat_map(ids, fn id ->
          AssignmentRelationship
          |> Ash.Query.filter_input(target_id: id, alias: alias_step)
          |> Ash.read!(domain: Diffo.Provider)
          |> Enum.map(& &1.source_id)
        end)
      end)

    Enum.flat_map(final_ids, fn id ->
      PlaceRef  # or PartyRef
      |> Ash.Query.filter_input(instance_id: id, role: source_role)
      |> Ash.Query.load(:place)  # or :party
      |> Ash.read!(domain: Diffo.Provider)
      |> Enum.map(& &1.place)
    end)
  end)
end

Why no intermediate node

• Direct: Instance → PlaceRef → Place — the PlaceRef node exists in the graph
• Inherited: the calculation returns Place/Party directly; the role is the calculation name
• Both render into the same JSON array — consumer just loads :a_end like any field
• Keeps the graph clean — no materialised edges for derived topology

Key dependency: alias on AssignmentRelationship

AssignmentRelationship needs an optional alias attribute (atom, nil for unaliased) with identity [:target_id, :alias] (pre_check: true). The alias is the "baby name" — set by the consuming instance before the source may exist, stable for the life of the assignment. Rendered in TMF JSON as a resourceRelationshipCharacteristic { name: "alias", value: "a_end" }.

Compilation constraint

The full via path must be declared on the consuming instance — the transformer only sees its own DSL state and cannot inspect other resources at compile time. Multi-level chains cannot self-assemble from each resource's single-hop declaration.

Related

• indirect place_ref #123 (indirect place_ref — superseded by this approach)
• Indirect parties with no_attributes #124 (indirect parties — same design applies)

[matt-beanland]

Progress on branch 122-party-inheritance-via-instance-dsl

Done — alias foundation

• AssignmentRelationship: added alias attribute (optional atom), identity [:target_id, :alias] with pre_check?: true, rendered as a resourceRelationshipCharacteristic entry when present, threaded through the Assignment TypedStruct and Assigner
• Relationship: added [:source_id, :alias] identity with pre_check?: true; removed [:source_id, :target_id] which was unenforced (AshNeo4j has no DB-level unique constraints) and too restrictive (legitimate use case: multiple same-type relationships between the same pair, distinguished by alias)
• AGENTS.md: alias documented as the join key between expectation and fulfilment, pointing to this ticket

Next — inherited_place / inherited_party DSL

New DSL declarations in places do / parties do that the transformer converts into Ash Calculations on the instance. No PlaceRef/PartyRef node is created for derived cases — the calculation returns Place/Party directly.

places do
  place :location, MyPlace              # direct — PlaceRef node in graph
  inherited_place :a_end,              # derived — calculation on instance, no node
    source_role: :location             # via: defaults to :a_end (single-hop)
end

Multi-level:

inherited_place :poi, via: [:cvc_link, :nni_link], source_role: :poi

The generated calculation does a 4-hop traversal per level:

Instance ←[target_id]— AssignmentRelationship {alias: :a_end} —[source_id]→ Instance → PlaceRef {role: :location} → Place

Multi-level is an iterative fold over the via list — single-level is a one-element list. via: defaults to the declaration name. Same pattern for inherited_party / parties do.

The full via path must be declared on the consuming instance — the transformer only sees its own DSL state and cannot inspect other resources at compile time.

[matt-beanland]

Phase 1 — Alias on Assignment and Relationship

Added an alias attribute (:atom, optional) to both AssignmentRelationship and Relationship. The alias is a stable, consumer-given name for a relationship slot — a "baby name" assigned before or when the target instance is bound, which survives the relationship's lifetime. It is the foundation for the first-order expectation system.

Identity constraints were added to enforce uniqueness: [:target_id, :alias] on AssignmentRelationship (the consumer/target gives the alias, so it must be unique per target) and [:source_id, :alias] on Relationship (source gives the alias, so it must be unique per source). Both use pre_check?: true since AshNeo4j has no DB-level unique constraints.

The alias is passed through the Assignment struct and Assigner pipeline when creating an AssignmentRelationship.

Phase 2 — inherited_place and inherited_party DSL

Added two new DSL entities — inherited_place and inherited_party — to the places do and parties do blocks on instance resources. These declare that a place or party is inherited transitively through the assignment alias graph rather than held directly.

At compile time, TransformInheritedRefs injects an Ash calculation for each declaration. The calculation performs a fold over the via: path (defaulting to [role] for single-hop), walking AssignmentRelationship records by target_id and alias to find source instances, then reading their PlaceRef or PartyRef records to resolve the inherited ref.

Multi-hop traversal is supported via via: [:step_one, :step_two], declared on the consuming instance. Single-hop defaults without needing via:.

Phase 3 — Integration test

Added AccessService as a minimal test service instance declaring inherited_place :primary, source_role: :location. Integration tests verify that a service correctly inherits a place from an assigned card via the :primary alias, returns an empty list when no matching assignment exists, and filters correctly when multiple aliases are present.