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.

Field-level gating: when a field declares Field::REQUIRES and the request-scoped authorizer denies it, the matching LET variable is not emitted. 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.

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.

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.

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 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

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.