@dashevo/dapi-grpc 4.2.0-dev.1 → 4.2.0-dev.5

package/clients/drive/v0/nodejs/drive_pbjs.js

@@ -20039,6 +20039,7 @@ $root.org = (function() {
                          * @property {number} BETWEEN_EXCLUDE_RIGHT=8 BETWEEN_EXCLUDE_RIGHT value
                          * @property {number} IN=9 IN value
                          * @property {number} STARTS_WITH=10 STARTS_WITH value
+                         * @property {number} IN_TIME_RANGE=11 IN_TIME_RANGE value
                          */
                         GetDocumentsRequest.WhereOperator = (function() {
                             var valuesById = {}, values = Object.create(valuesById);
@@ -20053,6 +20054,7 @@ $root.org = (function() {
                             values[valuesById[8] = "BETWEEN_EXCLUDE_RIGHT"] = 8;
                             values[valuesById[9] = "IN"] = 9;
                             values[valuesById[10] = "STARTS_WITH"] = 10;
+                            values[valuesById[11] = "IN_TIME_RANGE"] = 11;
                             return values;
                         })();
 
@@ -20870,6 +20872,7 @@ $root.org = (function() {
                                     case 8:
                                     case 9:
                                     case 10:
+                                    case 11:
                                         break;
                                     }
                                 if (message.value != null && message.hasOwnProperty("value")) {
@@ -20939,6 +20942,10 @@ $root.org = (function() {
                                 case 10:
                                     message.operator = 10;
                                     break;
+                                case "IN_TIME_RANGE":
+                                case 11:
+                                    message.operator = 11;
+                                    break;
                                 }
                                 if (object.value != null) {
                                     if (typeof object.value !== "object")
@@ -26727,6 +26734,7 @@ $root.org = (function() {
                                  * @property {number|Long|null} [count] RankedEntry count
                                  * @property {number|Long|null} [sum] RankedEntry sum
                                  * @property {number|null} [avg] RankedEntry avg
+                                 * @property {Uint8Array|null} [inKey] RankedEntry inKey
                                  */
 
                                 /**
@@ -26776,6 +26784,14 @@ $root.org = (function() {
                                  */
                                 RankedEntry.prototype.avg = 0;
 
+                                /**
+                                 * RankedEntry inKey.
+                                 * @member {Uint8Array} inKey
+                                 * @memberof org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry
+                                 * @instance
+                                 */
+                                RankedEntry.prototype.inKey = $util.newBuffer([]);
+
                                 // OneOf field names bound to virtual getters and setters
                                 var $oneOfFields;
 
@@ -26822,6 +26838,8 @@ $root.org = (function() {
                                         writer.uint32(/* id 3, wireType 0 =*/24).sint64(message.sum);
                                     if (message.avg != null && Object.hasOwnProperty.call(message, "avg"))
                                         writer.uint32(/* id 4, wireType 1 =*/33).double(message.avg);
+                                    if (message.inKey != null && Object.hasOwnProperty.call(message, "inKey"))
+                                        writer.uint32(/* id 5, wireType 2 =*/42).bytes(message.inKey);
                                     return writer;
                                 };
 
@@ -26868,6 +26886,9 @@ $root.org = (function() {
                                         case 4:
                                             message.avg = reader.double();
                                             break;
+                                        case 5:
+                                            message.inKey = reader.bytes();
+                                            break;
                                         default:
                                             reader.skipType(tag & 7);
                                             break;
@@ -26926,6 +26947,9 @@ $root.org = (function() {
                                         if (typeof message.avg !== "number")
                                             return "avg: number expected";
                                     }
+                                    if (message.inKey != null && message.hasOwnProperty("inKey"))
+                                        if (!(message.inKey && typeof message.inKey.length === "number" || $util.isString(message.inKey)))
+                                            return "inKey: buffer expected";
                                     return null;
                                 };
 
@@ -26966,6 +26990,11 @@ $root.org = (function() {
                                             message.sum = new $util.LongBits(object.sum.low >>> 0, object.sum.high >>> 0).toNumber();
                                     if (object.avg != null)
                                         message.avg = Number(object.avg);
+                                    if (object.inKey != null)
+                                        if (typeof object.inKey === "string")
+                                            $util.base64.decode(object.inKey, message.inKey = $util.newBuffer($util.base64.length(object.inKey)), 0);
+                                        else if (object.inKey.length >= 0)
+                                            message.inKey = object.inKey;
                                     return message;
                                 };
 
@@ -26982,7 +27011,7 @@ $root.org = (function() {
                                     if (!options)
                                         options = {};
                                     var object = {};
-                                    if (options.defaults)
+                                    if (options.defaults) {
                                         if (options.bytes === String)
                                             object.key = "";
                                         else {
@@ -26990,6 +27019,14 @@ $root.org = (function() {
                                             if (options.bytes !== Array)
                                                 object.key = $util.newBuffer(object.key);
                                         }
+                                        if (options.bytes === String)
+                                            object.inKey = "";
+                                        else {
+                                            object.inKey = [];
+                                            if (options.bytes !== Array)
+                                                object.inKey = $util.newBuffer(object.inKey);
+                                        }
+                                    }
                                     if (message.key != null && message.hasOwnProperty("key"))
                                         object.key = options.bytes === String ? $util.base64.encode(message.key, 0, message.key.length) : options.bytes === Array ? Array.prototype.slice.call(message.key) : message.key;
                                     if (message.count != null && message.hasOwnProperty("count")) {
@@ -27013,6 +27050,8 @@ $root.org = (function() {
                                         if (options.oneofs)
                                             object.value = "avg";
                                     }
+                                    if (message.inKey != null && message.hasOwnProperty("inKey"))
+                                        object.inKey = options.bytes === String ? $util.base64.encode(message.inKey, 0, message.inKey.length) : options.bytes === Array ? Array.prototype.slice.call(message.inKey) : message.inKey;
                                     return object;
                                 };
 

package/clients/platform/v0/nodejs/platform_pbjs.js

@@ -19531,6 +19531,7 @@ $root.org = (function() {
                          * @property {number} BETWEEN_EXCLUDE_RIGHT=8 BETWEEN_EXCLUDE_RIGHT value
                          * @property {number} IN=9 IN value
                          * @property {number} STARTS_WITH=10 STARTS_WITH value
+                         * @property {number} IN_TIME_RANGE=11 IN_TIME_RANGE value
                          */
                         GetDocumentsRequest.WhereOperator = (function() {
                             var valuesById = {}, values = Object.create(valuesById);
@@ -19545,6 +19546,7 @@ $root.org = (function() {
                             values[valuesById[8] = "BETWEEN_EXCLUDE_RIGHT"] = 8;
                             values[valuesById[9] = "IN"] = 9;
                             values[valuesById[10] = "STARTS_WITH"] = 10;
+                            values[valuesById[11] = "IN_TIME_RANGE"] = 11;
                             return values;
                         })();
 
@@ -20362,6 +20364,7 @@ $root.org = (function() {
                                     case 8:
                                     case 9:
                                     case 10:
+                                    case 11:
                                         break;
                                     }
                                 if (message.value != null && message.hasOwnProperty("value")) {
@@ -20431,6 +20434,10 @@ $root.org = (function() {
                                 case 10:
                                     message.operator = 10;
                                     break;
+                                case "IN_TIME_RANGE":
+                                case 11:
+                                    message.operator = 11;
+                                    break;
                                 }
                                 if (object.value != null) {
                                     if (typeof object.value !== "object")
@@ -26219,6 +26226,7 @@ $root.org = (function() {
                                  * @property {number|Long|null} [count] RankedEntry count
                                  * @property {number|Long|null} [sum] RankedEntry sum
                                  * @property {number|null} [avg] RankedEntry avg
+                                 * @property {Uint8Array|null} [inKey] RankedEntry inKey
                                  */
 
                                 /**
@@ -26268,6 +26276,14 @@ $root.org = (function() {
                                  */
                                 RankedEntry.prototype.avg = 0;
 
+                                /**
+                                 * RankedEntry inKey.
+                                 * @member {Uint8Array} inKey
+                                 * @memberof org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry
+                                 * @instance
+                                 */
+                                RankedEntry.prototype.inKey = $util.newBuffer([]);
+
                                 // OneOf field names bound to virtual getters and setters
                                 var $oneOfFields;
 
@@ -26314,6 +26330,8 @@ $root.org = (function() {
                                         writer.uint32(/* id 3, wireType 0 =*/24).sint64(message.sum);
                                     if (message.avg != null && Object.hasOwnProperty.call(message, "avg"))
                                         writer.uint32(/* id 4, wireType 1 =*/33).double(message.avg);
+                                    if (message.inKey != null && Object.hasOwnProperty.call(message, "inKey"))
+                                        writer.uint32(/* id 5, wireType 2 =*/42).bytes(message.inKey);
                                     return writer;
                                 };
 
@@ -26360,6 +26378,9 @@ $root.org = (function() {
                                         case 4:
                                             message.avg = reader.double();
                                             break;
+                                        case 5:
+                                            message.inKey = reader.bytes();
+                                            break;
                                         default:
                                             reader.skipType(tag & 7);
                                             break;
@@ -26418,6 +26439,9 @@ $root.org = (function() {
                                         if (typeof message.avg !== "number")
                                             return "avg: number expected";
                                     }
+                                    if (message.inKey != null && message.hasOwnProperty("inKey"))
+                                        if (!(message.inKey && typeof message.inKey.length === "number" || $util.isString(message.inKey)))
+                                            return "inKey: buffer expected";
                                     return null;
                                 };
 
@@ -26458,6 +26482,11 @@ $root.org = (function() {
                                             message.sum = new $util.LongBits(object.sum.low >>> 0, object.sum.high >>> 0).toNumber();
                                     if (object.avg != null)
                                         message.avg = Number(object.avg);
+                                    if (object.inKey != null)
+                                        if (typeof object.inKey === "string")
+                                            $util.base64.decode(object.inKey, message.inKey = $util.newBuffer($util.base64.length(object.inKey)), 0);
+                                        else if (object.inKey.length >= 0)
+                                            message.inKey = object.inKey;
                                     return message;
                                 };
 
@@ -26474,7 +26503,7 @@ $root.org = (function() {
                                     if (!options)
                                         options = {};
                                     var object = {};
-                                    if (options.defaults)
+                                    if (options.defaults) {
                                         if (options.bytes === String)
                                             object.key = "";
                                         else {
@@ -26482,6 +26511,14 @@ $root.org = (function() {
                                             if (options.bytes !== Array)
                                                 object.key = $util.newBuffer(object.key);
                                         }
+                                        if (options.bytes === String)
+                                            object.inKey = "";
+                                        else {
+                                            object.inKey = [];
+                                            if (options.bytes !== Array)
+                                                object.inKey = $util.newBuffer(object.inKey);
+                                        }
+                                    }
                                     if (message.key != null && message.hasOwnProperty("key"))
                                         object.key = options.bytes === String ? $util.base64.encode(message.key, 0, message.key.length) : options.bytes === Array ? Array.prototype.slice.call(message.key) : message.key;
                                     if (message.count != null && message.hasOwnProperty("count")) {
@@ -26505,6 +26542,8 @@ $root.org = (function() {
                                         if (options.oneofs)
                                             object.value = "avg";
                                     }
+                                    if (message.inKey != null && message.hasOwnProperty("inKey"))
+                                        object.inKey = options.bytes === String ? $util.base64.encode(message.inKey, 0, message.inKey.length) : options.bytes === Array ? Array.prototype.slice.call(message.inKey) : message.inKey;
                                     return object;
                                 };
 

package/clients/platform/v0/nodejs/platform_protoc.js

@@ -24389,7 +24389,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsRequest.WhereOperator = {
   BETWEEN_EXCLUDE_LEFT: 7,
   BETWEEN_EXCLUDE_RIGHT: 8,
   IN: 9,
-  STARTS_WITH: 10
+  STARTS_WITH: 10,
+  IN_TIME_RANGE: 11
 };
 
 
@@ -30659,7 +30660,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
     key: msg.getKey_asB64(),
     count: jspb.Message.getFieldWithDefault(msg, 2, "0"),
     sum: jspb.Message.getFieldWithDefault(msg, 3, "0"),
-    avg: jspb.Message.getFloatingPointFieldWithDefault(msg, 4, 0.0)
+    avg: jspb.Message.getFloatingPointFieldWithDefault(msg, 4, 0.0),
+    inKey: msg.getInKey_asB64()
   };
 
   if (includeInstance) {
@@ -30712,6 +30714,10 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
       var value = /** @type {number} */ (reader.readDouble());
       msg.setAvg(value);
       break;
+    case 5:
+      var value = /** @type {!Uint8Array} */ (reader.readBytes());
+      msg.setInKey(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -30769,6 +30775,13 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
       f
     );
   }
+  f = /** @type {!(string|Uint8Array)} */ (jspb.Message.getField(message, 5));
+  if (f != null) {
+    writer.writeBytes(
+      5,
+      f
+    );
+  }
 };
 
 
@@ -30922,6 +30935,66 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
 };
 
 
+/**
+ * optional bytes in_key = 5;
+ * @return {string}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 5, ""));
+};
+
+
+/**
+ * optional bytes in_key = 5;
+ * This is a type-conversion wrapper around `getInKey()`
+ * @return {string}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey_asB64 = function() {
+  return /** @type {string} */ (jspb.Message.bytesAsB64(
+      this.getInKey()));
+};
+
+
+/**
+ * optional bytes in_key = 5;
+ * Note that Uint8Array is not supported on all browsers.
+ * @see http://caniuse.com/Uint8Array
+ * This is a type-conversion wrapper around `getInKey()`
+ * @return {!Uint8Array}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey_asU8 = function() {
+  return /** @type {!Uint8Array} */ (jspb.Message.bytesAsU8(
+      this.getInKey()));
+};
+
+
+/**
+ * @param {!(string|Uint8Array)} value
+ * @return {!proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry} returns this
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.setInKey = function(value) {
+  return jspb.Message.setField(this, 5, value);
+};
+
+
+/**
+ * Clears the field making it undefined.
+ * @return {!proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry} returns this
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.clearInKey = function() {
+  return jspb.Message.setField(this, 5, undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.hasInKey = function() {
+  return jspb.Message.getField(this, 5) != null;
+};
+
+
 
 /**
  * List of repeated fields within this message type.

package/clients/platform/v0/web/platform_pb.d.ts

@@ -2739,6 +2739,7 @@ export namespace GetDocumentsRequest {
     BETWEEN_EXCLUDE_RIGHT: 8;
     IN: 9;
     STARTS_WITH: 10;
+    IN_TIME_RANGE: 11;
   }
 
   export const WhereOperator: WhereOperatorMap;
@@ -3223,6 +3224,13 @@ export namespace GetDocumentsResponse {
       getAvg(): number;
       setAvg(value: number): void;
 
+      hasInKey(): boolean;
+      clearInKey(): void;
+      getInKey(): Uint8Array | string;
+      getInKey_asU8(): Uint8Array;
+      getInKey_asB64(): string;
+      setInKey(value: Uint8Array | string): void;
+
       getValueCase(): RankedEntry.ValueCase;
       serializeBinary(): Uint8Array;
       toObject(includeInstance?: boolean): RankedEntry.AsObject;
@@ -3240,6 +3248,7 @@ export namespace GetDocumentsResponse {
         count: string,
         sum: string,
         avg: number,
+        inKey: Uint8Array | string,
       }
 
       export enum ValueCase {

package/clients/platform/v0/web/platform_pb.js

@@ -24389,7 +24389,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsRequest.WhereOperator = {
   BETWEEN_EXCLUDE_LEFT: 7,
   BETWEEN_EXCLUDE_RIGHT: 8,
   IN: 9,
-  STARTS_WITH: 10
+  STARTS_WITH: 10,
+  IN_TIME_RANGE: 11
 };
 
 
@@ -30659,7 +30660,8 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
     key: msg.getKey_asB64(),
     count: jspb.Message.getFieldWithDefault(msg, 2, "0"),
     sum: jspb.Message.getFieldWithDefault(msg, 3, "0"),
-    avg: jspb.Message.getFloatingPointFieldWithDefault(msg, 4, 0.0)
+    avg: jspb.Message.getFloatingPointFieldWithDefault(msg, 4, 0.0),
+    inKey: msg.getInKey_asB64()
   };
 
   if (includeInstance) {
@@ -30712,6 +30714,10 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
       var value = /** @type {number} */ (reader.readDouble());
       msg.setAvg(value);
       break;
+    case 5:
+      var value = /** @type {!Uint8Array} */ (reader.readBytes());
+      msg.setInKey(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -30769,6 +30775,13 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
       f
     );
   }
+  f = /** @type {!(string|Uint8Array)} */ (jspb.Message.getField(message, 5));
+  if (f != null) {
+    writer.writeBytes(
+      5,
+      f
+    );
+  }
 };
 
 
@@ -30922,6 +30935,66 @@ proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.Rank
 };
 
 
+/**
+ * optional bytes in_key = 5;
+ * @return {string}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 5, ""));
+};
+
+
+/**
+ * optional bytes in_key = 5;
+ * This is a type-conversion wrapper around `getInKey()`
+ * @return {string}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey_asB64 = function() {
+  return /** @type {string} */ (jspb.Message.bytesAsB64(
+      this.getInKey()));
+};
+
+
+/**
+ * optional bytes in_key = 5;
+ * Note that Uint8Array is not supported on all browsers.
+ * @see http://caniuse.com/Uint8Array
+ * This is a type-conversion wrapper around `getInKey()`
+ * @return {!Uint8Array}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.getInKey_asU8 = function() {
+  return /** @type {!Uint8Array} */ (jspb.Message.bytesAsU8(
+      this.getInKey()));
+};
+
+
+/**
+ * @param {!(string|Uint8Array)} value
+ * @return {!proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry} returns this
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.setInKey = function(value) {
+  return jspb.Message.setField(this, 5, value);
+};
+
+
+/**
+ * Clears the field making it undefined.
+ * @return {!proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry} returns this
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.clearInKey = function() {
+  return jspb.Message.setField(this, 5, undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.org.dash.platform.dapi.v0.GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry.prototype.hasInKey = function() {
+  return jspb.Message.getField(this, 5) != null;
+};
+
+
 
 /**
  * List of repeated fields within this message type.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dashevo/dapi-grpc",
-  "version": "4.2.0-dev.1",
+  "version": "4.2.0-dev.5",
   "description": "DAPI GRPC definition file and generated clients",
   "browser": "browser.js",
   "main": "node.js",
@@ -45,7 +45,7 @@
   },
   "homepage": "https://github.com/dashevo/dapi-grpc#readme",
   "dependencies": {
-    "@dashevo/grpc-common": "4.2.0-dev.1",
+    "@dashevo/grpc-common": "4.2.0-dev.5",
     "@dashevo/protobufjs": "6.10.5",
     "@grpc/grpc-js": "^1.14.3",
     "@improbable-eng/grpc-web": "^0.15.0",

package/protos/platform/v0/platform.proto

@@ -594,6 +594,18 @@ message GetDocumentsRequest {
     BETWEEN_EXCLUDE_RIGHT = 8;
     IN = 9;
     STARTS_WITH = 10;
+    // Time-range bucket selection (v1 only; the v0 CBOR surface is
+    // unaffected). `field` names a timestamp covered by a `timeRange`
+    // index. Operand: `text` selector `"newest"`/`"oldest"` when one grid
+    // buckets the field, or `list` `[selector, range, step(, phase)]` in
+    // the contract's declared seconds to name one of several grids (zero
+    // phase is spelled by omission — one wire spelling per grid). The
+    // server resolves it to a bucket-start equality from current block
+    // time; the verifier re-derives the same bucket from the quorum-signed
+    // metadata time — an ordinary index/count proof. See `timeRange` in
+    // the document meta-schema and
+    // `drive::query::resolve_time_range_bucket_clause`.
+    IN_TIME_RANGE = 11;
   }
 
   // Tagged scalar (or list) operand for a `WhereClause`. The
@@ -703,12 +715,21 @@ message GetDocumentsRequest {
   // before release rather than deprecated, because it invented
   // non-SQL grammar for something SQL already expresses.
   //
-  // **`HAVING` cannot yet combine with an aggregate `ORDER BY`.**
-  // The ranked executor reads a pre-sorted per-axis secondary and
-  // has no way to drop groups from the middle of that walk, so a
-  // request carrying both a non-empty `having` and a ranking
-  // `order_by` is rejected with `Unsupported` rather than served
-  // with one of the two silently ignored.
+  // **From protocol v14 a single `HAVING` clause is served as a
+  // bounded range read** (having-range mode): `SELECT <agg> GROUP BY
+  // p HAVING <agg> <op> <value> [ORDER BY <order-key> ASC|DESC]
+  // LIMIT n` answers from the same per-axis secondary as ranked
+  // mode, on an index declaring the matching ranked axis. The
+  // clause's aggregate must be the selected aggregate, the operator
+  // must describe one contiguous range (`NOT_EQUAL` / `IN` are
+  // rejected), and the optional `ORDER BY` picks the walk direction
+  // using the same order-key spelling as ranked mode: `f` for
+  // `SUM(f)` / `AVG(f)`, the `$count` sentinel for `COUNT(*)` —
+  // never an explicit `OrderClause.aggregate` target, which is
+  // rejected. See the supported-shape table on
+  // `GetDocumentsRequestV1`. On protocol v13 and earlier every
+  // non-empty `having` stays rejected with `Unsupported`, exactly as
+  // before.
   //
   // The operator set mirrors `WhereOperator` minus `STARTS_WITH`
   // (prefix matching has no natural meaning against a scalar
@@ -849,12 +870,16 @@ message GetDocumentsRequest {
   // It returns `ResultData.ranked`. See `order_by` and the
   // supported-shape table below.
   //
-  // `having` is a boolean per-group predicate and is **still**
-  // `Unsupported` at every protocol version, ranked mode or not
-  // (`"HAVING clause is not yet implemented"`). It carries no ranking
-  // spelling: an earlier draft put cross-group ranking on the right of
-  // a `HAVING` (`HAVING AVG(grade) IN TOP(5)`) and that grammar was
-  // removed before release in favour of `ORDER BY` + `LIMIT`.
+  // **Having-range mode** is served from protocol v14: a single
+  // `having` clause whose aggregate is the selected aggregate turns
+  // the request into a bounded range read over the same per-axis
+  // secondary ranked mode walks, answered in `ResultData.ranked`.
+  // On protocol v13 and earlier every non-empty `having` is rejected
+  // (`"HAVING clause is not yet implemented"`). `having` carries no
+  // ranking spelling: an earlier draft put cross-group ranking on the
+  // right of a `HAVING` (`HAVING AVG(grade) IN TOP(5)`) and that
+  // grammar was removed before release in favour of `ORDER BY` +
+  // `LIMIT`. See the supported-shape table below.
   //
   // **Supported shapes** (everything else rejects with a typed
   // `QuerySyntaxError::Unsupported` so callers can detect un-wired
@@ -880,12 +905,16 @@ message GetDocumentsRequest {
   // - a is the In field AND b is the range field, in that order → existing compound distinct shape; entries carry both `in_key` (= a's value) and `key` (= b's value).
   //
   // `select=<COUNT(*)|SUM(f)|AVG(f)>, group_by=[p], order_by=[<the selected aggregate>]` (protocol v14+) — **ranked mode**:
-  // - exactly one `group_by` property, exactly one `order_by` clause naming the select's aggregate (`f` for `SUM(f)` / `AVG(f)`, the `$count` sentinel for `COUNT(*)`), a `limit` in `1 ..= 100`, an optional `offset`, and no `where` / `having` / `start_at`, on an index declaring the matching `rankedCountable` / `rankedSummable` / `rankedAverageable` axis → ranked executor, answered in `ResultData.ranked`.
+  // - exactly one `group_by` property, exactly one `order_by` clause naming the select's aggregate (`f` for `SUM(f)` / `AVG(f)`, the `$count` sentinel for `COUNT(*)`), a `limit` in `1 ..= 100`, an optional `offset`, and no `having` / `start_at`, on an index declaring the matching `rankedCountable` / `rankedSummable` / `rankedAverageable` axis → ranked executor, answered in `ResultData.ranked`. On a single-property ranked index no `where` is accepted; on a compound ranked index every leading index property must be pinned (one clause per property, `group_by` names the trailing property) — `EQUAL` pins one prefix, and **at most one** clause may be `IN` (2..=10 distinct elements, `null` legal; a single-element `IN` normalizes to the equality pin; an element whose prefix was never written — at any depth of its pinned chain — contributes an empty branch, union semantics), fanning the walk out across one prefix branch per element and merging by `(aggregate, encoded prefix, group key)`; merged entries carry `in_key`. A non-zero `offset` is rejected together with `IN` (rank-skip is per-secondary; `OFFSET 0` is the offset-free request).
   // - `DESC` is the "top n" reading (walk the axis from the largest aggregate down), `ASC` the "bottom n" reading. Worked example: `SELECT AVG(grade) GROUP BY restaurantId ORDER BY grade DESC LIMIT 1 OFFSET 4` is the 5th-best restaurant.
   //
+  // `select=<COUNT(*)|SUM(f)|AVG(f)>, group_by=[p], having=[<the selected aggregate> <op> <value>]` (protocol v14+) — **having-range mode**:
+  // - exactly one `group_by` property, exactly one `having` clause whose aggregate is the select's aggregate, an operator describing one contiguous range (`EQUAL`, `GREATER_THAN[_OR_EQUALS]`, `LESS_THAN[_OR_EQUALS]`, `BETWEEN*`; `NOT_EQUAL` / `IN` rejected), a `limit` in `1 ..= 100`, an optional `order_by` naming the same aggregate (walk direction; ascending by default), and no `offset` / `start_at` / `start_after`, on an index declaring the matching ranked axis → having-range executor, answered in `ResultData.ranked`. `where` follows the same rule as ranked mode: none on a single-property ranked index; exactly one pin per leading index property on a compound ranked index, at most one of them an `IN` (2..=10 distinct elements; a never-written element contributes an empty branch) that fans the bound out across prefix branches and merges, entries carrying `in_key`.
+  // - no offset or cursor pagination: a page cut at `limit` continues only by tightening the bound past the last *distinct* aggregate value seen; a cut inside a tie (several groups sharing the boundary aggregate) cannot be continued, so size `limit` above the widest expected tie.
+  //
   // **Rejected shapes** (return `Unsupported`):
-  // - any non-empty `having`, at every protocol version.
-  // - at v14+: a ranked-shaped request carrying a `where` clause, a `start_at` / `start_after` cursor, more than one `order_by`, or an `order_by` naming anything but the selected aggregate.
+  // - any non-empty `having` on protocol v13 and earlier; at v14+, any `having` shape outside having-range mode above (multiple clauses, an aggregate other than the select's, `NOT_EQUAL` / `IN` as the having operator, a `where` shape other than the compound-index prefix pins above — equality pins plus at most one bounded `IN` — or a carried `offset` / cursor).
+  // - at v14+: a ranked-shaped request carrying a `where` shape other than the compound-index prefix pins above (an operator other than `EQUAL` or the one permitted `IN`, more than one `IN`, a `null` pin combined with an `IN`, a repeated or non-leading property, or a missing pin), a `start_at` / `start_after` cursor, more than one `order_by`, or an `order_by` naming anything but the selected aggregate.
   // - `select=DOCUMENTS` with non-empty `group_by`.
   // - `select=COUNT` with `group_by` on a field that is not constrained by an `In` or range where clause.
   // - `select=COUNT` with `group_by.len() > 2`.
@@ -1084,12 +1113,13 @@ message GetDocumentsRequest {
     // `HavingClause` / `HavingAggregate` for the operator and
     // aggregate-function catalogs.
     //
-    // **Every non-empty `having` is rejected**, at every protocol
-    // version, with `Unsupported("HAVING clause is not yet
-    // implemented")`. The wire shape ships ahead of evaluation so
-    // callers can construct full `HAVING COUNT(*) > 5 AND
-    // SUM(amount) > 100` requests in their builders, and so the
-    // capability can land without another version bump.
+    // **From protocol v14 a single clause is served** as a bounded
+    // range read — having-range mode; see the message-level
+    // supported-shape table. On v13 and earlier every non-empty
+    // `having` is rejected with `Unsupported("HAVING clause is not
+    // yet implemented")`. Multi-clause `HAVING COUNT(*) > 5 AND
+    // SUM(amount) > 100` requests can still be constructed on the
+    // wire, but stay rejected until a multi-clause evaluator lands.
     //
     // **`having` does not express ranking.** "The n highest-scoring
     // groups" is `ORDER BY <the selected aggregate> DESC LIMIT n`
@@ -1107,13 +1137,17 @@ message GetDocumentsRequest {
     // routes to the ranked executor (`group_by` + a single `order_by`
     // naming the selected aggregate), `offset` skips that many ranks
     // before the returned page, so `ORDER BY avg(grade) DESC LIMIT 1
-    // OFFSET 4` is the 5th-best group. The skip is **count-attested**,
-    // not walked: grovedb proves it from the counted subtree
-    // commitments, so the proof stays `O(log n + k)` at any offset and
-    // the response echoes the attested number in
-    // `RankedEntries.skipped`. There is deliberately no ceiling — an
-    // offset of 4 and an offset of four billion cost the same, so
-    // there is no denial-of-service lever a cap would close. An offset
+    // OFFSET 4` is the 5th-best group. The skip is **counted, not
+    // walked**: grovedb descends on each subtree's aggregate count and
+    // collapses whole subtrees that fit inside the remaining offset, so
+    // the work stays `O(log n + k)` at any offset and the response
+    // reports the skip it performed in `RankedEntries.skipped`. On a
+    // proved request that count is additionally *attested* — committed
+    // to by the proof and re-derived by the verifier; on an unproved
+    // one it is the node's own report. See `RankedEntries.skipped`. There is deliberately no ceiling — an
+    // offset of 4 and an offset of four billion cost the same *order*
+    // of work — neither walks the region it skips — so there is no
+    // denial-of-service lever a cap would close. An offset
     // past the end of the ranking is a provable answer rather than an
     // error: `entries` comes back empty and `skipped` is the ranking's
     // whole population.
@@ -1372,6 +1406,14 @@ message GetDocumentsResponse {
         // than hardcoding the literal.
         double avg = 4;
       }
+      // The prefix branch this entry came from, set **only** on an
+      // `IN`-pinned request (see the supported-shape table): the
+      // encoded index-key bytes of the `IN` property's pinned value —
+      // empty bytes for the `null` (absent-value) branch. Absent on
+      // single-prefix responses. The same group key can legally appear
+      // under two prefixes, so `(in_key, key)` is the entry's identity
+      // on a merged page, exactly as on `CountEntry`.
+      optional bytes in_key = 5;
     }
 
     // Ranked result entries. **Entry order IS the ranking order** —
@@ -1399,20 +1441,31 @@ message GetDocumentsResponse {
       // group rather than the best.
       //
       // **When a requested offset exceeds the population**, `entries`
-      // is empty and `skipped` is the ranking's attested *total*
+      // is empty and `skipped` is the ranking's *total* reported
       // population — a positive, useful answer ("there are only 12
       // groups") rather than a bare empty list.
       //
-      // On the proved path the number is grovedb's cryptographically
-      // attested count, re-derived by the verifier from the counted
-      // subtree commitments in the proof bytes rather than trusted
-      // from this field; a proving client should use the verified
-      // value. On the unproven read there is nothing to attest and
-      // grovedb's read API does not report a short walk, so the server
-      // echoes the requested offset. The two therefore disagree in
-      // exactly one case — an offset past the end, where the unproven
-      // read reports the request and the proved one reports the truth.
-      // Callers who need the population must prove.
+      // Both paths report the same quantity: the offset you asked for
+      // when the skip succeeded, and the ranking's total population
+      // when the walk ran out of groups first. They no longer disagree
+      // anywhere, including past the end.
+      //
+      // What differs is the *warrant*, not the value. On the proved
+      // path the number is cryptographically attested — re-derived by
+      // the verifier from the counted subtree commitments in the proof
+      // bytes rather than trusted from this field — so a proving client
+      // should use the verified value and ignore this one. On the
+      // unproven path it is an **unverified claim**, exactly like the
+      // entries beside it: it equals the attested value on an honest
+      // node, and nothing forces a node to be honest. Read "the true
+      // population" as "what this node says the population is".
+      // Callers who need to trust it, rather than merely receive it,
+      // must still prove.
+      //
+      // Do not assume this field equals the offset you requested. It
+      // equals the offset only when the skip succeeded; when the walk
+      // ran out of groups first it is smaller, and that is the answer
+      // rather than an inconsistency.
       optional uint64 skipped = 2 [jstype = JS_STRING];
     }