Update request interface #2601

What to do

• Accept the new sort forms. Today the sort only accepts $hybrid, and any other key fails with REQUEST_STRUCTURE_MISMATCH (FindAndRerankSortClauseDeserializer.java#L36-L37, #L85). Also accept:
  • {"$vectorize": "..."}, {"$vector": [...]} or {"$vector": {"$binary": "..."}}, and {"$lexical": "..."};
  • field sorts such as {"age": -1, "name": 1};
  • {}, null or no sort, which means a filter leg without sorting.
• Rules:
  • a $ key must be the only key, and must be one of $hybrid, $vectorize, $vector or $lexical;
  • the $hybrid path stays as it is;
  • field sorts inside $hybrid stay rejected. Add regression tests for this.
• Parse by key name only. Set LegMode and keep the raw sort.
• Check the values later, at resolve time, with find's sort parser (CollectionSortClauseBuilder.java). This gives us:
  • the same rules and error codes as find;
  • error messages that survive over MCP. Errors thrown while parsing JSON show up there as just Invalid argument [sort].
• Field sort values are 1 or -1 only, like find (CollectionSortClauseBuilder.java#L138-L173). The design doc's {"age": 0} example needs updating.
• Small fix on the way. An invalid $binary in $hybrid.$vector probably returns a 500 (FindAndRerankSortClauseDeserializer.java#L188-L207). find handles the same input properly (SortClauseBuilder.java#L65-L85).
• rerankCandidateLimit:

  • Add a new field to FindAndRerankCommand.Options (FindAndRerankCommand.java#L65-L122).

  • Add config bounds stargate.jsonapi.operations.rerank-candidate-limit as an IntConfigWithBounds, next to the hybrid limits (OperationsConfig.java#L359-L367). Document it in CONFIGURATION.md.

  • Read the default from config. The hybrid limits use a hard-coded default, so their configured default never takes effect (FindAndRerankCommand.java#L132-L136).

  • Validate it in the builder, the same way as validateHybridLimits (FindAndRerankOperationBuilder.java#L139-L166):

    • it must be greater than 1 and at most the max, otherwise return the existing COMMAND_FIELD_VALUE_INVALID;
    • using it with $hybrid is an error;
    • (proposed) using hybridLimits with a single-leg sort is also an error.

    These two errors share one new error code, added to errors.yaml and RequestException.

• To decide:
  • Min, default and max.
  • The defaults differ: a single leg reads 20, while $hybrid reads 50 per leg.