The direction is not a detail of the AQL — it decides whether the facet finds anything at all. A model whose edges leave the document (doc is the _from) reaches its vertices OUTBOUND; one whose edges point at it reaches them INBOUND. Follow the wrong way and the traversal is perfectly valid and matches nothing, so the facet answers empty buckets in 200 without a word — the shape of silent degradation this library refuses.

Three rules, and each is deliberate:

• the default is Traversal::INBOUND, which is what every linked facet compiled before this option existed — so a declaration that says nothing keeps its query byte for byte;
• Traversal::ANY is accepted, and means what it says: linked in either direction. It is the right answer for a relation that is not oriented — with the caveat that a document linked both ways to the same vertex is then reached twice, so Facet::DISTINCT earns its keep;
• an unknown value is refused, never quietly replaced. Traversal::get() would have fallen back on the default, turning a typo into empty buckets — the very failure the option exists to close — so Traversal::validate() answers instead.

The three join facets — HasFacetJoin, HasFacetJoinAggregate and HasFacetJoinComplex — differ in what they do with the joined documents (test their existence, aggregate a numeric field over them, match several of their fields), never in how they reach them. That reaching is this helper: it reads the join definition and returns the three fragments every one of them needs.

The join is doc_<key>.<AQL::KEY> == doc.<Facet::PROPERTY>, with AQL::KEY the joined side (default _key) and Facet::PROPERTY the main side (default the facet key) — which expresses both "the document holds the foreign key" and the reverse one-to-many "the joined documents reference the document". When AQL::ARRAY is set the main side holds an array of keys, so the equality becomes a membership test (IN).

A facet accepts two shapes on the wire — the bare value (?facets={"author":"alice"}) and the object form (?facets={"author":{"op":"like","val":"al"}}). Only the object form may override the configuration, and only through the keys it actually carries: the caller passes its already-resolved defaults in, and gets back the triplet to keep working with.

An associative array is the object form; a list is a multi-value bare value (["alice","bob"]) and travels untouched.

The presence of val is tested with array_key_exists(), not isset(), so an explicit {"op":"eq","val":null} is honoured as a null value rather than read as a missing one. An object form with no val at all cannot be compared against anything: the helper returns null and the caller drops the facet — which is why the abandon signal is a null return, and not a null value.