fix(viewtools): restore aggregation tree for VTL $estool.search (#36026)

[fabrizzio-dotCMS]

Fix for #36026 — VTL aggregation return-type regression

The Elasticsearch → OpenSearch migration made the search aggregation API vendor-neutral and, in doing so, changed the type exposed to Velocity as $results.aggregations ($estool.search(...)), silently breaking existing VTL templates (Velocity runs with runtime.references.strict=false, so broken accessors render empty instead of erroring).

• Before: $results.aggregations → org.elasticsearch.search.aggregations.Aggregations (object tree)
• After (broken): $results.aggregations → Map<String, List<AggregationBucket>>, where AggregationBucket exposed only key() / docCount() and nested sub-aggregations were dropped.

Three regressions

1. aggregations.<name>.buckets → null (the map value was already the bucket list).
2. bucket.getKeyAsNumber() / getDocCount() gone; the fluent key() / docCount() are not reachable as Velocity properties (no get/is prefix).
3. Nested top_hits per bucket unrecoverable — ContentSearchResponse.from(...) mapped only first-level terms.

The fix — restore a vendor-neutral aggregation tree

A neutral tree that mirrors the legacy ES API shape, so existing templates keep working unchanged (honoring the migration's "no visible behavior change" goal).

• New Aggregation type — getBuckets() (terms), getHits() (top_hits), Iterable over buckets. The container is a plain Map<String, Aggregation> (Velocity resolves $aggs.name via Map#get) — no separate container class.
• AggregationBucket gains getKey() / getKeyAsString() / getKeyAsNumber() (lenient: null on non-numeric) / getDocCount() and nested getAggregations(); ES and OS factories now capture sub-aggregations.
• SearchHit / SearchHits accessors switched to bean-style (getId(), getHits(), …) so $topHits.getHits().getHits() → $hit.id resolve without alias methods.
• ContentSearchResponse keeps the flat aggregations() Map intact (now @Value.Derived from the tree) → ContentTypeAPIImpl / WorkflowHelper and existing tests are unaffected; adds aggregationTree(). ContentSearchResults.getAggregations() (the VTL entry point) returns the tree.

The flat map is always derived from the tree, so the two views can never disagree.

Tests

AggregationDomainTest (unit) — Jackson round-trip with no duplicate id property, lenient getKeyAsNumber(), flat-map derivation excludes bucket-less aggs, nested sub-aggs reachable.

ContentSearchToolTest (integration, run against real OpenSearch):

Test	Purpose
verbatimCustomerVtl_rendersAfterFix	The customer template, verbatim, now renders buckets (key: / docCount:) and nested top_hits hits (hit id:).
neutralFluentVtl_emitsBuckets	The fluent neutral form ($group.key() / docCount(), iterating the Aggregation).
aggregationTreePreservesTopHits	API-level: aggregationTree() preserves first-level buckets and nested top_hits with its hits.
raw_flatAggregationsMapStillPopulated	The flat Map used by Java callers stays populated.

✅ Unit 4/4 · ✅ Integration 4/4 against OpenSearch.

Closes #36026

🤖 Generated with Claude Code

[claude]

Claude finished @fabrizzio-dotCMS's task in 3m 5s —— View job

---

PR Review

• Gathering context
• Reading changed files
• Analysis & review

---

The fix is structurally sound and the tests are well-written. A few issues worth addressing:

---

Issues

1. flatten() discriminator is fragile — getHits() == null

ContentSearchResponse.flatten() (line 89) uses aggregation.getHits() == null to decide whether to include an aggregation in the flat map. This works today because only top_hits sets getHits(). But if any future aggregation type also sets getHits() (or someone builds an Aggregation with both buckets and hits set), it will silently vanish from the flat map. The discriminant should be based on the type string, not an inferred null check.

Fix this →

---

2. Unknown OS aggregation types are silently dropped

Aggregation.fromSingleOS() (line 121–151) returns null for any type that isn't sterms, lterms, dterms, or top_hits. Those nulls are filtered out in fromOS() with no log. Aggregation types like date_histogram, range, avg, cardinality, etc. disappear without trace. A Logger.debug call with the skipped type name would save hours of debugging when a template stops returning results.

---

3. SearchHit.from(osHit) drops ES-style fields for OpenSearch hits

The ES factory calls .fields(esSearchHit.getFields()) (line 98), but the OS factory (line 110–128) never calls .fields(...). Any template using $hit.fields.someField on a top_hits result backed by OpenSearch will silently get an empty map. The OS Hit has osHit.fields() — it should be mapped.

---

4. @NotNull annotation inconsistency in SearchHits

SearchHits.iterator() imports org.jetbrains.annotations.NotNull (line 11), while Aggregation and AggregationBucket use javax.annotation.Nullable. The codebase standard (as seen in surrounding files) is javax.annotation. Pick one.

---

5. serialVersionUID on a non-Serializable class

ContentSearchResults (line 26) declares serialVersionUID = 1L but does not implement java.io.Serializable. The field is meaningless. Pre-existing, but now is a good time to clean it up.

---

6. Broken javadoc {@link Aggregations} in ContentSearchResponse

Line 24 of ContentSearchResponse.java references {@link Aggregations} — no such class exists. Should be Map<String, Aggregation> or just removed.

---

7. DoubleTermsBucket key may render in scientific notation

String.valueOf(osBucket.key()) for a double can produce "1.23E7" style strings. getKeyAsNumber() recovers the double correctly, but Velocity's $bucket.getKeyAsString() would render the scientific notation literally, which may not match what existing templates expect.

---

Reviewer request not yet implemented

@wezell requested converting SearchHit and SearchHits to records. The current Immutables approach works, but the reviewer's request is open. Not a blocker if agreed to defer, but needs a reply.

[wezell]

Make SearchHit a record, not immutable :)

[wezell]

Maybe a record too? Let me know if that is too much. work but it would be good to start flexing this muscle.