This runtime assertion validates type safety for Documents. If the provided value is not an instance of Documents, an UnexpectedValueException is thrown with a descriptive message.

This is especially useful when handling dynamically typed data or container-resolved dependencies, where you want to enforce strict model integrity.

A relation is emitted by two parallel walks that must stay symmetric : the LET sub-query (buildVariables) and the projected key (aqlFields). When a definition declares AQL::REQUIRES and the authorizer denies it, the LET is not emitted — so the matching marker must also disappear from the projected fields, otherwise the RETURN would reference an unbound variable. This helper performs that field-side purge : it is applied at every point where a prepared fields array meets its edges/joins registries, right before buildVariables() / aqlFields() run on them.

Resolution mirrors buildVariables() : the definition is looked up in the registry under the field key, a string value being a one-hop alias to another registry entry. A marker without a resolvable array definition is left untouched (buildVariables skips it anyway — nothing to desynchronize).

The check itself is delegated to isAuthorized() with the whole definition (its AQL::REQUIRES key equals Field::REQUIRES), so the semantics are exactly the field-level ones : no marker → allowed, no authorizer → allowed (fail open), a list of subjects → logical OR. The definition-level gate COMPOSES with the field-level Field::REQUIRES (evaluated downstream) : either level can drop the relation.

The function is pure and idempotent : applying it twice — e.g. once on the LET walk and once on the projection walk of a wrapped reference — yields the same fields, which is precisely what keeps both walks symmetric.

When an edge/join definition declares its own projection (AQL::FIELDS / AQL::SKIN_FIELDS), that ad-hoc field list replaces the target model's $fields — so the Field::REQUIRES markers carried by the target model are not applied, and a field hidden from reading could be re-projected in clear through the relation. This helper closes that hole by dropping every projected field whose source attribute is refused by the target model's own projection (isPathAuthorized() against $documents->fields), mirroring the read-side gate applied everywhere else.

The source attribute — Field::NAME when the field aliases a document attribute, otherwise the output key — is what gets gated, never the output label, so an alias cannot dodge (or borrow) the wrong permission.

Relation-scoped OR alternative — Field::SELF_REQUIRES. A field refused by the target model is nonetheless kept when it declares Field::SELF_REQUIRES and the authorizer grants at least one of its subjects — the relation being a legitimately broader context (reading a sub-field of a resource the caller owns). This override lives only here: first-level model reads never pass through this helper, so it never widens a model's direct reads. The subjects are normalized to a non-empty list of strings before the check, so an empty / malformed value cannot borrow isAuthorized()'s "no subject → true" fail-open and re-open T6.

Fail-open and idempotent: with no target model, no $documents->fields, a field carrying no Field::REQUIRES on the target, or no authorizer injected, the field is kept — and re-running it on a projection that already came from $documents->fields changes nothing.

AQL forbids a computed collection in FOR … IN …, so the relation is compiled as an APPEND of guarded static branches: one sub-query per Arango::MAP entry, each guarded by an equality on the discriminator so only the matching branch yields rows. The $buildBranch callback is the only relation-specific part — it turns a branch definition + its guard into a parenthesized sub-query string (a join wraps buildJoinSubquery(), an edge delegates to the already-parenthesized buildEdgeSubquery()).

Security (fail-closed):

• Per-branch gate — a branch denied by isAuthorized() (Field::REQUIRES / AQL::REQUIRES) is dropped from the APPEND; its collection is never queried, so neither a value nor an existence bit of the hidden type leaks.
• Fallback — an optional Arango::FALLBACK branch catches discriminator values matching none of the DECLARED types, guarded by NOT IN [ … ] over all map keys (gated or not), so a document of a denied type routes to nothing, never to the fallback (no oracle).
• When every branch is dropped the LET holds [], so the projection resolves to null / [] rather than a broken statement.

The flat list is the shape produced by a depth-ranged edge projection (see buildEdgeVariable() with AQL::MAX_DEPTH): every element is an associative row that knows its parent — either through the AQL::WITH_PATH injected _parent key (default), or through a parent field the document already stores (pass its name as $parentSource, e.g. 'broader').

Each returned node gains a $childrenKey (default children) holding its direct children, recursively.

Roots

• When $rootKey is given, the roots are the nodes whose parent equals it (the start vertex of the traversal — its own key). This is what buildTreeAlter() passes (the document's _key).
• When $rootKey is null, a node is a root when its parent key is absent from the list (a depth-1 node points at the — unlisted — start vertex).

Robustness

The reconstruction is O(n) and cycle-safe: a node already seen on the current branch is never descended into again (pathological self-referential data cannot cause infinite recursion). A node whose parent is missing simply becomes a root. Each node is expected to have a single parent — with AQL::WITH_PATH this is guaranteed by the traversal's global vertex uniqueness. Rows that are not associative arrays are ignored.

Declare it on the field that carries the depth-ranged projection:

use oihana\arango\models\enums\Alter ;
use function oihana\arango\models\helpers\buildTreeAlter ;

AQL::FIELDS =>
[
    Prop::DESCENDANTS =>
    [
        Field::FILTER => Filter::EDGES ,
        Field::ALTERS => [ [ Alter::MAP , buildTreeAlter() ] ] ,
    ],
],
AQL::EDGES =>
[
    Prop::DESCENDANTS =>
    [
        AQL::MODEL     => 'concept_links' ,
        AQL::DIRECTION => Traversal::OUTBOUND ,
        AQL::MAX_DEPTH => 5 ,
        AQL::WITH_PATH => true , // provides the `_parent` used to rebuild the tree
    ],
],

At map time the callback:

• leaves the value untouched when it is not an array (an absent/scalar relation),
• reads the root from the enclosing document's $keyField (the traversal start vertex — its own _key),
• returns the nested tree built by buildTree().

The parent link source defaults to AQL::_PARENT (_parent, injected by AQL::WITH_PATH); pass a stored field name instead (e.g. 'broader') when the document already carries its parent.

Permission gating happens at TWO composable levels — either one can drop the relation (logical AND across levels, logical OR inside a declared subjects list):

• Field-level — the FIELDS entry (the relation marker) declares Field::REQUIRES: gates this projection of the relation in this parent. Combined with the symmetric drop in aqlFields(), the field disappears from both the AQL projection and the response — no key in the JSON, no orphan reference in the AQL.
• Definition-level — the edge/join definition itself declares AQL::REQUIRES: gates the relation wherever the definition is used. The symmetric field-side drop is handled upstream by authorizeRelationFields() at every point where a prepared fields array meets its registries.

The check is uniform: edges, joins, and edge-counts all share the same gating contract. A Filter::EDGES_COUNT companion is gated exactly the same way as the others — it is simply not gated by default because no Field::REQUIRES is declared on it. To gate the count, declare Field::REQUIRES on the count entry itself (or AQL::REQUIRES on the shared definition to gate every usage).

This helper function is a shortcut for extractVertexIds() with $side fixed to Schema::_FROM. It returns a unique list of vertex IDs from the "_from" field in an array of edge documents (objects or associative arrays).

This function can work in two modes:

1. Resolution mode: Resolves target model from config via container, then extracts relations
2. Direct mode: Extracts relations from an already-resolved target model

In both modes, the function merges the extracted relations with any explicit AQL::EDGES and AQL::JOINS defined in the relation configuration.

Resolution mode (for parseFilterSegment):

$relations = extractNestedRelations(
    config: $edgeConfig,
    isEdge: true,
    container: $container
);

Direct mode (for buildEdgeTraversal/buildJoinTraversal):

$relations = extractNestedRelations(
    config: $edgeConfig,
    targetModel: $alreadyResolvedModel
);

This helper function is a shortcut for extractVertexIds() with $side fixed to Schema::_TO. It returns a unique list of vertex IDs from the "_to" field in an array of edge documents (objects or associative arrays).

This helper function is used to extract either the "_from" or "_to" vertex IDs from an array of edge documents (objects or arrays) and return only the unique IDs.

This helper function returns a Documents object from: a direct instance, an array definition, a service name within a PSR-11 container, or falls back to a provided default value.

Behavior:

• If $definition is a Documents instance, it is returned as-is.
• If $definition is an array, the function looks for the $key (default: Arango::DOCUMENTS).
• If $definition is a non-empty string and $container contains a service with that name, the corresponding service is fetched.
• If none of the above conditions are met, the $default value is returned.

The whitelists that gate what can be queried (AQL::FILTERS, Arango::FACETS, Arango::GROUPABLE) are disjoint from the projection permission (Field::REQUIRES on $fields). Without this bridge, a field declared queryable but hidden from reading could still be filtered / faceted / grouped on, and the presence, the distribution or the order of the results would leak the hidden value (an oracle).

This helper closes that gap the same way SortTrait does for sorting: it looks the attribute up in the projection map $fields and, when that field carries a Field::REQUIRES subject, defers the decision to the shared isAuthorized() gate (backend-agnostic closure injected through $init[Arango::AUTHORIZER]). Devise: « what you cannot read, you cannot query on ».

Resolution rules (aligned on the field-level semantics):

• $fields is not an array, or the attribute is absent / not an array definition → true (nothing to inherit, no gating).
• The field definition carries no Field::REQUIRES → true (no gating).
• Otherwise → the result of isAuthorized() (OR over the subjects list, fail-open when no authorizer is injected).

Reads the optional Field::REQUIRES permission subject(s) declared on the field definition, then defers the actual decision to a backend-agnostic Closure(string $subject): bool injected through $init[Arango::AUTHORIZER].

The framework remains agnostic of the underlying authorization layer (Casbin, OPA, custom, ...) — the consumer is responsible for binding the callable to a real enforcer and a request-scoped user identifier.

Resolution rules:

• No Field::REQUIRES declared on the definition → true (no gating).
• Field::REQUIRES resolves to an empty list → true (no gating).
• No Arango::AUTHORIZER injected, or value is not callable → true (authorization layer disabled, fail open).
• One or more subjects declared → true if at least one subject is granted by the callable (logical OR).

This is the depth-aware counterpart of isAttributeAuthorized(): instead of gating explode('.', $path)[0] (the root only), it walks the whole path segment by segment, descending through the sub-fields of the structural fields (Field::FIELDS, or the per-skin buckets AQL::SKIN_FIELDS) and reading the optional Field::REQUIRES at every level. A single locked level anywhere on the path denies the whole path — « what you cannot read, you cannot query on ».

The decision at each level is deferred to the shared isAuthorized() gate (backend-agnostic closure injected through $init[Arango::AUTHORIZER]), so the semantics (OR over the subjects list, fail-open when no authorizer is injected) match the field-level gate exactly.

Resolution rules (aligned on isAttributeAuthorized(), extended in depth) :

• $fields is not an array → true (nothing to inherit, no gating).
• A segment is absent from the current field map(s), or only declared as a scalar / bool definition → true (no Field::REQUIRES to inherit here).
• A segment carries a Field::REQUIRES refused by the authorizer → false.
• Otherwise the walk descends into the sub-fields and continues; a path with no deeper declared sub-fields resolves to true.

Sub-fields resolution (fail-closed union). A structural field can declare its sub-fields under Field::FIELDS and / or under per-skin buckets AQL::SKIN_FIELDS. Because a Field::REQUIRES is a permission (independent of the projection skin), the descent gathers the sub-field from every source and treats it as locked as soon as it is locked in any one of them — a sub-field hidden in a single skin bucket stays gated on every path.

A single-segment path behaves exactly like isAttributeAuthorized() — it is its degenerate case. Each segment is stripped of the [*] array-expansion marker, so the same helper serves the hierarchical filter leaves.

A polymorphic relation replaces the single AQL::MODEL by:

• Arango::DISCRIMINATOR — the parent field path deciding the branch (e.g. selector.areaScope for a join, kind for an edge) ;
• Arango::MAP — a non-empty type => relation-definition table, one branch per discriminator value (each branch is itself a regular relation definition) ;
• Arango::FALLBACK (optional) — the branch used when the discriminator value matches no Arango::MAP key.

Three notations are accepted and may be mixed within the same array:

• Associative (legacy) — urlKey => fieldPath. The public ?sort= token (the array key) resolves to the AQL field (the value). The value may be a string or an array path ([ 'address', 'city' ] → address.city). This is the historical form and is returned untouched.
• Indexed shorthand — a plain string fieldName. The token equals the field (urlKey === fieldPath), so the redundant field => field map is avoided.
• Indexed alias — a single-pair array [ urlKey => fieldPath ], for the rare case where the public token differs from the AQL field (?sort=name → givenName is written [ 'name' => 'givenName' ]). The pair direction is always [ urlKey => fieldPath ], identical to the associative form.

The pair direction [ urlKey => fieldPath ] is preserved across every notation, so the legacy associative map and the new indexed forms speak the same language.

Robustness rules:

• null (open mode, no whitelist) is returned as-is.
• In an indexed alias, an entry keyed by a non-string (a pure list such as [ 'address', 'city' ] with no token) is dropped — an alias must carry a token.
• An indexed value that is neither a string nor an array contributes nothing.

The function is idempotent: re-running it on an already-canonical map returns the same map, so it is safe to apply at construction even when the input is already legacy.

This function analyzes a filter path segment and determines its type (simple field, document, array expansion, edge, or join). It validates the segment against the configuration and, for edges and joins, resolves nested relations from target models.

Key Features:

• Validates array notation consistency (e.g., employee[*] must be of type EDGES/JOINS/ARRAY_EXPANSION)
• Resolves nested edges/joins from target models for multi-level traversals
• Supports both explicit relation references (via AQL::RELATION) and implicit (segment key)
• Accumulates full path for better error reporting

Nested Relations Resolution: For edges, the function:

1. Gets the edge model from the container
2. Determines target model based on traversal direction (INBOUND → from, OUTBOUND → to)
3. Extracts edges/joins from target model
4. Merges with explicit nested relations from edge configuration

For joins, the function:

1. Gets the join target model from the container
2. Extracts edges/joins from target model

Steps:

1. Look the definition up in $registry ($edges or $joins) by $key; a string value is a shortcut reference to another entry, dereferenced once.
2. Return null when nothing resolves (the caller skips the relation).
3. Two composable gates (logical AND): Field::REQUIRES on the FIELDS entry ($field) and AQL::REQUIRES on the definition itself. Either one denied returns null, dropping the relation from both the LET walk and — mirrored upstream by authorizeRelationFields() — the projection.
4. Stamp Field::UNIQUE onto the definition (the caller-provided AQL variable name override).

A Filter::EDGES_COUNT is gated the same way: its count LET is dropped only when the entry (or the shared definition) declares a requirement — otherwise the cardinality stays visible, as knowing it is rarely a leak.

This helper interprets a flexible sort definition and constructs the appropriate AQL 'SORT' expression, shared by sortEdgeVariable() and sortJoinVariable(). The only thing those two wrappers customize is which variable reference carries the sort property and which one carries the default fallback property:

• An explicit sort property (string definition, or AQL::SORT in an array) is sorted on $sortRef (the vertex for an edge, the join document for a join).
• The fallback (no AQL::SORT provided) sorts by $defaultProperty on $defaultRef in DESC order (the edge for an edge relation, the same join document for a join).

Converts a vertex key into a complete ArangoDB vertex ID by optionally prefixing it with a collection name.

This is useful when preparing _from or _to fields in edge queries, ensuring the correct collection/key format.

Behavior

• If $vertexKey is null, the function returns null.
• If $collection is a Documents instance with a collection property, the returned ID will be prefixed with this collection.
• If $collection is a string, it will be used directly as the collection prefix.
• If $collection is null, the function returns the raw $vertexKey.