Support FHIRPath trace() function

[piotrszul]

Spec link: https://hl7.org/fhirpath/#trace-name-string-projection-expression-collection

The trace() function adds a string representation of the input collection to a diagnostic log using the name argument, then returns the input collection unchanged. An optional projection argument allows logging the result of a sub-expression instead of the full input.

contained.where(criteria).trace('unmatched', id).empty()

Split from #2395, which now covers only type() reflection.

Scope

Only the first argument (name : String) will be implemented. The optional projection argument is out of scope.

Limitations

• The name argument must be a string literal. Dynamic expressions (e.g., trace(someField)) are not supported and will raise an error.
• The optional projection argument is not supported.

Trace sinks

Two sinks will be implemented for trace output:

1. SLF4J logging - trace entries are logged at TRACE level via SLF4J during expression evaluation. This covers standalone library usage and the server.
2. FHIRPath Lab API response - trace entries are returned in the FHIR Parameters response so they can be displayed in the FHIRPath Lab UI. See Include trace entries in FHIRPath Lab API response #2585.

Changes required

fhirpath module

Implement the trace() function in the FHIRPath engine (first argument only). During evaluation, each trace() call logs to SLF4J at TRACE level and collects trace entries (name + string representation of the collection) into a list. Add trace entries to SingleInstanceEvaluationResult alongside the existing results and expectedReturnType fields.

library-api module

Thread trace entries through PathlingContext.evaluateFhirPath() so they are available in the result returned to callers.

Python library

Update PathlingContext.evaluate_fhirpath() to extract trace entries from the Java result and include them in the returned dict (e.g. a trace key containing a list of {name, value} dicts).

[johngrimes]

@piotrszul I added the scope clarification to this, as discussed.