Add per-field dimension to caches

[zipdoki]

Summary

As discussed in offline meeting, adds an optional dimension whitelist to cache fields. When set, only edges whose value for that field is in the whitelist are written to the cache; other edges are skipped at write time. Read paths are unchanged — filtered rows are simply absent from the wide row.

Changes

• IndexField (V3) and Cache.Field (V2 codec) gain dimension with empty-set validation.
• EdgeMutationBuilder.buildCacheRecords skips the cache record when any field is outside its dimension.
• AbstractEdgeEncoder.encodeAllCacheEdges applies the same filter on V2 bulk writes.
• Test PrettyObjectWriter matches production mapper's NON_NULL policy.

How to Test

• ./gradlew :core:test :codec-java:test :server:test :engine:test
• EdgeMutationBuilderTest.CacheDimensionFilter — in/out-of-dimension, null dimension, UPDATED transitions, empty-set reject.
• EdgeCacheQueryE2ETest, ActionbaseQueryE2ETest — direct seek and multi-hop CACHE.

AI Assistance

• This PR was written largely with AI assistance.
  • Tool / model: Claude Code (Opus 4.7, 1M context)

[zipdoki]

@em3s
Surfaced by nullable dimension — aligns test mapper with production NON_NULL so nullable fields don't break round-trip fixtures.

[em3s]

Adding context from our offline discussion — this is groundwork for per-dimension limit distribution on multi-field EdgeCache. Today, with a two-field cache (field1, field2) and limit 100, both bulkload and pruner spend the budget in leading-field order, so we can't allocate it across field1 buckets — the bucket set isn't known up front.

Pinning that set in the label via dimension gives bulkload and pruner a shared source, enabling per-dimension top-N.

[em3s]

dimension is EdgeCache-only and stays null on EdgeIndex — time to split off a CacheField.

[em3s]

Left a review comment. Please take a look. @zipdoki

[em3s]

@zipdoki

As also discussed offline: instead of matches, pass the actual dimensionValue through to the caller — so bulkload (and similar) can compute top-N on rowkey + dimensionValue rather than rowkey alone.

[zipdoki]

@em3s
Thanks for both reviews.

1. Splitting CacheField off IndexField — done in Split CacheField off IndexField. dimension now lives only on CacheField.

2. Threading dimensionValue instead of matches — tried, reverted.

Three outcomes have to coexist: skip on mismatch, emit with dimensionValue = null, emit with an encoded value. Merging the predicate and the encoder into one return path looks like:

.flatMap(cache -> {
  List<Cache.Field> dimensionedFields = cache.getDimensionedFields();
  Object[] values = new Object[dimensionedFields.size()];
  for (int i = 0; i < dimensionedFields.size(); i++) {
    Cache.Field f = dimensionedFields.get(i);
    Object v = resolveFieldValue(f.getField(), ts, src, tgt, props);
    if (!f.getDimension().contains(v)) return Stream.empty();
    values[i] = v;
  }
  T dimensionValue = dimensionedFields.isEmpty()
      ? null
      : encodeBufferAsT(buffer -> { /* encode values[i] */ });
  return dirType.getDirs().stream()
      .map(dir -> encodeCacheEdge(...).withDimensionValue(dimensionValue));
})

Costs of merging:

• A per-cache Object[] allocation just to carry resolved values between the validate phase and the encode phase — extra GC pressure on the hot path that the separated form avoids entirely.
• Object[] + Stream.empty() sentinel to encode the three outcomes in a single return.
• Lambda body grows to ~15 lines, vs. two ~5-line helpers.
• Loses the natural filter (predicate) / flatMap (value + expand) mapping onto stream operators.
• Harder to unit-test in isolation.

What the current shape pays for that:

.filter(cache -> passesAllDimensions(cache, ts, src, tgt, props))
.flatMap(cache -> {
  T dimensionValue = encodeDimensionValue(cache, ts, src, tgt, props);
  return dirType.getDirs().stream()
      .map(dir -> encodeCacheEdge(...).withDimensionValue(dimensionValue));
})

resolveFieldValue runs twice per dimensioned field, and the two helpers must stay aligned on iteration. Both iterate cache.getDimensionedFields(), so drift risk is low, and resolveFieldValue is a switch + HashMap.get — sub-100ns. Happy to revisit if that cost ever gets heavier.

[em3s]

Once the three-field tests pass and the bulkload/seek paths we're testing internally are green, we can merge and follow up with the codec-java release. @zipdoki