@pulseindex/sdk 3.2.0 → 4.0.1

package/CHANGELOG.md

@@ -1,6 +1,119 @@
 # Changelog
 
-## 3.2.0
+## 4.0.1
+
+### The covering threshold, corrected against a real app
+
+`withinRadius` is a pre-filter the caller narrows exactly afterwards, so excess
+area is cheaper than predicates. 4.0.0's threshold was too strict: it rejected
+the coarse cell at 5 km, turning a 10-cell covering into 167. Measured through
+the sibling PHP SDK against a real application with 100,000 properties, a 5 km
+radius went from 3,082 µs to 926 µs on wall time — the cost is the request, not
+the search.
+
+The coarse cell is now taken up to 3.0× the circle, which still rejects it at
+2 km where it wastes 4.73× to 6.91×. Both SDKs are regenerated against one
+shared vector fixture, so they still agree cell for cell.
+
+## 4.0.0
+
+**A major, not a minor.** The previous draft of these notes said 3.2.0. Checking
+what actually breaks says otherwise, so the number says otherwise too.
+
+### Breaking
+
+1. **`withinRadius` returns different results.** It has to: above 8 km it was
+   returning **nothing at all**, and below that it over-matched by up to 5.4x.
+   Measured against a real engine with 20,000 points:
+
+   | radius | true | before | after |
+   |--------|-----:|-------:|------:|
+   | 2 km   | 7    | 38     | 9     |
+   | 5 km   | 36   | 109    | 42    |
+   | 15 km  | 386  | **0**  | 518   |
+   | 50 km  | 4,282| **0**  | 4,800 |
+
+2. **`getCoveringHashes()` refuses a precision nothing is indexed at.** Passing
+   4 used to return cells that matched no entity; it now throws.
+
+3. **A radius too large for the indexed precisions is refused**, naming the
+   latitude. Cells narrow toward the poles, so 50 km is available to about 82
+   degrees and 15 km to about 89. Previously such a request came back
+   silently covering a fraction of its own circle.
+
+4. **`SearchResponse` gained a required `totalIsExact`.** Code that *builds* the
+   type — a test double, a cache, a mapper — fails to compile until it sets it
+   (`TS2741`). Code that only reads search results is unaffected.
+
+### Migrating
+
+Nothing to change for the common case: index the same way, call `withinRadius`
+the same way, and get results that are actually inside the radius you asked for.
+
+If you pinned expectations to the old counts, they will move. If you passed an
+explicit precision, pass one of the indexed precisions or drop the argument. If
+you search above 80 degrees latitude at a large radius, catch the refusal.
+
+### Everything else in this release
+
+### The total on a paged search is not the number of matches
+
+A paged search stops as soon as the page is full — that is what makes it cost
+microseconds — so the total it reports is whatever it had counted when it
+stopped. On a million entities, a query with 166,325 matches reported 10,866
+when asked for a page of 100. Anything printing "page 1 of N" from that number
+is wrong by an order of magnitude and looks entirely fine.
+
+The result now says which it is, and there is a call that gets you the real one:
+
+```ts
+const page = await client.search(query.limit(20));
+page.totalIsExact;   // false — the search early-exited
+
+const both = await client.searchWithTotal(query.limit(20));
+both.totalIsExact;   // true, at the cost of a second round trip
+both.totalMatches;   // the real total
+```
+
+`limit(0)` still asks for the count alone and is exact by itself; nothing about
+that changed, and `searchWithTotal` skips its second call when you already
+passed it.
+
+
+### `withinRadius` was returning nothing above 8 km
+
+`optimalPrecisionForRadius` chose geohash precision 4 for any radius over 8 km,
+and entities are only ever tagged at precisions 5 and 6. A covering at
+precision 4 therefore matched **nothing at all**. Measured against a real
+engine with 20,000 points around Riyadh:
+
+| radius | true matches | returned, before | returned, after |
+|--------|-------------:|-----------------:|----------------:|
+| 2 km   | 7            | 38               | 9               |
+| 5 km   | 36           | 109              | 42              |
+| 15 km  | 386          | **0**            | 518             |
+| 50 km  | 4,282        | **0**            | 4,800           |
+
+The precision is now always one the index carries, and of those the finest
+whose complete covering fits a cell budget. Small radii also tightened: 2 km
+went from 5.4x the true count to 1.3x.
+
+### A covering is no longer truncated in silence
+
+The 64-cell limit stopped the search mid-covering and returned what it had, so
+a 50 km circle came back covered 18% and a 1 km circle at fine precision came
+back covered 30% — with no error either time. The limit is now a budget the
+precision is chosen to fit, so the covering always completes. A radius too
+large for any indexed precision is refused by name.
+
+### `withinRadius` is a pre-filter, not an exact radius
+
+Cells are rectangles and the query is a circle, so the result still contains
+some points outside it — now about 1.1x to 1.8x the circle's area rather than
+up to 6x. The engine stores no coordinates, so only you can filter the
+remainder, from your own data after hydration. This was always true and was
+never written down.
+
 
 ### Delete many entities in one call
 

package/README.md

@@ -71,6 +71,11 @@ const result = await client.search(
     .limit(50),
 );
 
+> **`withinRadius` is a fast pre-filter, not an exact radius.** It expands the
+> circle into geohash cells, which are rectangles, so results include some points
+> outside the radius — about 1.1x to 1.8x the circle's area. The engine stores no
+> coordinates, so filter the remainder from your own data after hydration.
+
 const ids = result.matchedEntityIds;
 await client.close();
 ```

package/dist/index.d.mts

@@ -47,6 +47,17 @@ interface SearchResponse {
     matchedEntityIds: string[];
     totalMatches: number;
     executionTimeUs: number;
+    /**
+     * Whether `totalMatches` is the real number of matches or the early-exit
+     * count from a paged search. A paged search stops as soon as the page is
+     * full, which is what makes it cost microseconds — and leaves the total far
+     * below the truth. Measured on a million entities: a query with 166,325
+     * matches reported 10,866 when asked for a page of 100.
+     *
+     * Use {@link PulseIndexClient.searchWithTotal} when you need a number you can
+     * divide by a page size.
+     */
+    totalIsExact: boolean;
 }
 interface IndexEntityRequest {
     entityId: string;
@@ -298,6 +309,19 @@ declare class PulseIndexClient implements QueryExecutor {
     static query(): QueryBuilder;
     query(): QueryBuilder;
     search(query: QueryBuilder | SearchRequestOptions): Promise<SearchResponse>;
+    /**
+     * A page of ids together with the real number of matches.
+     *
+     * A paged search stops as soon as the page is full — that is what makes it
+     * cost microseconds — so its total is whatever it had counted when it
+     * stopped. Measured on a million entities: a query with 166,325 matches
+     * reported 10,866 for a page of 100. Anything that prints "page 1 of N" from
+     * that number is wrong by an order of magnitude and looks fine.
+     *
+     * This sends the count query as well, so it costs two round trips and returns
+     * a total you can divide by a page size.
+     */
+    searchWithTotal(query: QueryBuilder | SearchRequestOptions): Promise<SearchResponse>;
     index(entityIdOrInput: EntityId | EntityInput, attributes?: EntityAttributes): Promise<IndexEntityResponse>;
     indexEntity(entityId: EntityId, categories?: string[], price?: number, locationPrefix?: EntityId, tenantId?: string): Promise<boolean>;
     batchIndex(entities: Array<EntityInput | BatchEntityInput>): Promise<BatchIndexResponse>;
@@ -354,7 +378,41 @@ declare class GeoHash {
     static readonly INDEX_PRECISIONS: readonly [5, 6];
     private static readonly BASE32;
     private static readonly EARTH_RADIUS_KM;
-    private static readonly MAX_COVERING_CELLS;
+    /**
+     * Most cells one radius query may expand into, and therefore the most SHOULD
+     * predicates it sends.
+     *
+     * This used to be 64 and it was a truncation limit: the walk stopped mid
+     * covering and returned what it had, so a 50 km search covered 18% of its own
+     * circle and said nothing. It is now a budget the precision is chosen to fit,
+     * so a covering is always complete or the request is refused.
+     *
+     * The number is set by latitude, not by radius. Cells needed at the coarsest
+     * indexed precision, measured: 50 km costs 376 at the equator, 592 at London,
+     * 720 at Oslo, 1,044 at Tromso, 2,028 at 80N. A first attempt used 512,
+     * chosen at one latitude, and it refused a 50 km search anywhere above 60
+     * degrees — Oslo, Stockholm, Helsinki, Saint Petersburg.
+     *
+     * The cost is bounded: measured against a live engine, a covering costs about
+     * 0.57 us per cell, so a query at the full budget spends roughly 1.2 ms in
+     * the engine, and stays half of its 4,096-filter ceiling.
+     */
+    static readonly COVERING_CELL_BUDGET = 2048;
+    /**
+     * How much area outside the circle a covering may carry before a finer
+     * precision is worth its cell count.
+     *
+     * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+     * excess area is cheaper than predicates.
+     *
+     * 2.0 was the first attempt and it was too strict. It rejected the coarse
+     * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+     * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+     * time — the cost is the request, not the search. 3.0 keeps the cheap
+     * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+     * it wastes 4.73x to 6.91x depending on latitude.
+     */
+    static readonly ACCEPTABLE_COVER_RATIO = 3;
     private static readonly NEIGHBORS;
     private static readonly BORDERS;
     static encode(lat: number, lon: number, precision?: number): string;
@@ -372,14 +430,83 @@ declare class GeoHash {
     static neighbors(hash: string): string[];
     static neighborhood3x3(hash: string): string[];
     static neighborhoodTags(lat: number, lon: number, precision?: number): string[];
-    static optimalPrecisionForRadius(radiusKm: number): number;
-    static precisionForRadius(radiusKm: number): number;
+    /**
+     * The precision a radius query should cover at, at this point on the globe.
+     *
+     * Only ever one of {@link INDEX_PRECISIONS}. That is the correction: this
+     * used to return 4 for anything over 8 km, and nothing is indexed at
+     * precision 4, so **every radius above 8 km matched nothing at all**.
+     * Measured against a real engine with entities tagged by `encodeMultiTags`:
+     * 15 km returned 0 of 386, 50 km returned 0 of 4,282 — an empty page, with
+     * no error to explain it.
+     *
+     * Of the indexed precisions it returns the finest whose complete covering
+     * fits {@link COVERING_CELL_BUDGET}, because a finer cell wastes less area
+     * outside the circle. Measured at Riyadh: 5 km takes 140 cells at precision
+     * 6 for 1.21x the circle, against 10 cells at precision 5 for 2.76x; 15 km
+     * needs 1,120 at precision 6 and so falls to 47 at precision 5 for 1.44x.
+     *
+     * Latitude is a parameter because it changes the answer: a cell keeps its
+     * width in degrees, so it narrows in kilometres toward the poles and the same
+     * radius needs more of them.
+     *
+     * @throws when no indexed precision can cover the radius within the budget —
+     *         refused rather than half-covered.
+     */
+    static optimalPrecisionForRadius(radiusKm: number, lat?: number, lon?: number): number;
+    static precisionForRadius(radiusKm: number, lat?: number, lon?: number): number;
+    /**
+     * GeoHashes whose cells cover the search circle.
+     *
+     * The covering is always complete. It used to stop at 64 cells and return
+     * what it had, so a caller asking for 50 km got cells covering 18% of that
+     * circle — with no error. Now the precision is chosen to fit the budget and
+     * the walk always finishes, so the result either covers the circle or the
+     * call refuses.
+     *
+     * Passing `precision` explicitly overrides the choice, and is checked against
+     * {@link INDEX_PRECISIONS}: entities carry tags only at those, so any other
+     * precision matches nothing at all rather than matching loosely.
+     */
     static getCoveringHashes(lat: number, lon: number, radiusKm: number, precision?: number): string[];
+    /**
+     * Every cell at `precision` that intersects the circle, breadth-first from
+     * the centre and expanding only through cells that intersect.
+     *
+     * `limit` exists only so the precision chooser can stop early once a
+     * precision is known not to fit; a null limit walks to completion, which is
+     * what every caller that wants an answer passes.
+     */
+    private static walkCovering;
     static tag(geohash: string): string;
     static encodeTag(lat: number, lon: number, precision?: number): string;
     static encodeMultiTags(lat: number, lon: number): string[];
     static haversineKm(lat1: number, lon1: number, lat2: number, lon2: number): number;
     private static cellIntersectsCircle;
+    /**
+     * The longitude in [lonMin, lonMax] nearest to `lon`, going the short way
+     * round the globe.
+     *
+     * A plain clamp is wrong at the antimeridian, because -180 and +180 are the
+     * same meridian and a numeric comparison does not know it. Measured before
+     * this: a query at lon 179.99 against the cell spanning -180 to -179.989
+     * clamped to -179.989 and measured 2.334 km, when the true nearest point is
+     * -180.0 at 1.112 km. The cell was rejected from a 2 km radius it is well
+     * inside, and five of sixteen points on that circle's rim fell outside the
+     * covering — silently.
+     *
+     * Working in deltas normalised to +/-180 removes the discontinuity: the cell
+     * either straddles the query meridian, or lies wholly to one side of it and
+     * the nearer edge is the answer.
+     */
+    private static closestLongitude;
+    /** A longitude difference folded into [-180, 180]. */
+    private static normalizeLonDelta;
+    /**
+     * Covered area divided by the circle's, so a precision can be judged on what
+     * it wastes rather than only on what it costs.
+     */
+    private static coveredRatio;
     private static adjacent;
     private static normalizeHash;
     private static assertLatitude;

package/dist/index.d.ts

@@ -47,6 +47,17 @@ interface SearchResponse {
     matchedEntityIds: string[];
     totalMatches: number;
     executionTimeUs: number;
+    /**
+     * Whether `totalMatches` is the real number of matches or the early-exit
+     * count from a paged search. A paged search stops as soon as the page is
+     * full, which is what makes it cost microseconds — and leaves the total far
+     * below the truth. Measured on a million entities: a query with 166,325
+     * matches reported 10,866 when asked for a page of 100.
+     *
+     * Use {@link PulseIndexClient.searchWithTotal} when you need a number you can
+     * divide by a page size.
+     */
+    totalIsExact: boolean;
 }
 interface IndexEntityRequest {
     entityId: string;
@@ -298,6 +309,19 @@ declare class PulseIndexClient implements QueryExecutor {
     static query(): QueryBuilder;
     query(): QueryBuilder;
     search(query: QueryBuilder | SearchRequestOptions): Promise<SearchResponse>;
+    /**
+     * A page of ids together with the real number of matches.
+     *
+     * A paged search stops as soon as the page is full — that is what makes it
+     * cost microseconds — so its total is whatever it had counted when it
+     * stopped. Measured on a million entities: a query with 166,325 matches
+     * reported 10,866 for a page of 100. Anything that prints "page 1 of N" from
+     * that number is wrong by an order of magnitude and looks fine.
+     *
+     * This sends the count query as well, so it costs two round trips and returns
+     * a total you can divide by a page size.
+     */
+    searchWithTotal(query: QueryBuilder | SearchRequestOptions): Promise<SearchResponse>;
     index(entityIdOrInput: EntityId | EntityInput, attributes?: EntityAttributes): Promise<IndexEntityResponse>;
     indexEntity(entityId: EntityId, categories?: string[], price?: number, locationPrefix?: EntityId, tenantId?: string): Promise<boolean>;
     batchIndex(entities: Array<EntityInput | BatchEntityInput>): Promise<BatchIndexResponse>;
@@ -354,7 +378,41 @@ declare class GeoHash {
     static readonly INDEX_PRECISIONS: readonly [5, 6];
     private static readonly BASE32;
     private static readonly EARTH_RADIUS_KM;
-    private static readonly MAX_COVERING_CELLS;
+    /**
+     * Most cells one radius query may expand into, and therefore the most SHOULD
+     * predicates it sends.
+     *
+     * This used to be 64 and it was a truncation limit: the walk stopped mid
+     * covering and returned what it had, so a 50 km search covered 18% of its own
+     * circle and said nothing. It is now a budget the precision is chosen to fit,
+     * so a covering is always complete or the request is refused.
+     *
+     * The number is set by latitude, not by radius. Cells needed at the coarsest
+     * indexed precision, measured: 50 km costs 376 at the equator, 592 at London,
+     * 720 at Oslo, 1,044 at Tromso, 2,028 at 80N. A first attempt used 512,
+     * chosen at one latitude, and it refused a 50 km search anywhere above 60
+     * degrees — Oslo, Stockholm, Helsinki, Saint Petersburg.
+     *
+     * The cost is bounded: measured against a live engine, a covering costs about
+     * 0.57 us per cell, so a query at the full budget spends roughly 1.2 ms in
+     * the engine, and stays half of its 4,096-filter ceiling.
+     */
+    static readonly COVERING_CELL_BUDGET = 2048;
+    /**
+     * How much area outside the circle a covering may carry before a finer
+     * precision is worth its cell count.
+     *
+     * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+     * excess area is cheaper than predicates.
+     *
+     * 2.0 was the first attempt and it was too strict. It rejected the coarse
+     * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+     * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+     * time — the cost is the request, not the search. 3.0 keeps the cheap
+     * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+     * it wastes 4.73x to 6.91x depending on latitude.
+     */
+    static readonly ACCEPTABLE_COVER_RATIO = 3;
     private static readonly NEIGHBORS;
     private static readonly BORDERS;
     static encode(lat: number, lon: number, precision?: number): string;
@@ -372,14 +430,83 @@ declare class GeoHash {
     static neighbors(hash: string): string[];
     static neighborhood3x3(hash: string): string[];
     static neighborhoodTags(lat: number, lon: number, precision?: number): string[];
-    static optimalPrecisionForRadius(radiusKm: number): number;
-    static precisionForRadius(radiusKm: number): number;
+    /**
+     * The precision a radius query should cover at, at this point on the globe.
+     *
+     * Only ever one of {@link INDEX_PRECISIONS}. That is the correction: this
+     * used to return 4 for anything over 8 km, and nothing is indexed at
+     * precision 4, so **every radius above 8 km matched nothing at all**.
+     * Measured against a real engine with entities tagged by `encodeMultiTags`:
+     * 15 km returned 0 of 386, 50 km returned 0 of 4,282 — an empty page, with
+     * no error to explain it.
+     *
+     * Of the indexed precisions it returns the finest whose complete covering
+     * fits {@link COVERING_CELL_BUDGET}, because a finer cell wastes less area
+     * outside the circle. Measured at Riyadh: 5 km takes 140 cells at precision
+     * 6 for 1.21x the circle, against 10 cells at precision 5 for 2.76x; 15 km
+     * needs 1,120 at precision 6 and so falls to 47 at precision 5 for 1.44x.
+     *
+     * Latitude is a parameter because it changes the answer: a cell keeps its
+     * width in degrees, so it narrows in kilometres toward the poles and the same
+     * radius needs more of them.
+     *
+     * @throws when no indexed precision can cover the radius within the budget —
+     *         refused rather than half-covered.
+     */
+    static optimalPrecisionForRadius(radiusKm: number, lat?: number, lon?: number): number;
+    static precisionForRadius(radiusKm: number, lat?: number, lon?: number): number;
+    /**
+     * GeoHashes whose cells cover the search circle.
+     *
+     * The covering is always complete. It used to stop at 64 cells and return
+     * what it had, so a caller asking for 50 km got cells covering 18% of that
+     * circle — with no error. Now the precision is chosen to fit the budget and
+     * the walk always finishes, so the result either covers the circle or the
+     * call refuses.
+     *
+     * Passing `precision` explicitly overrides the choice, and is checked against
+     * {@link INDEX_PRECISIONS}: entities carry tags only at those, so any other
+     * precision matches nothing at all rather than matching loosely.
+     */
     static getCoveringHashes(lat: number, lon: number, radiusKm: number, precision?: number): string[];
+    /**
+     * Every cell at `precision` that intersects the circle, breadth-first from
+     * the centre and expanding only through cells that intersect.
+     *
+     * `limit` exists only so the precision chooser can stop early once a
+     * precision is known not to fit; a null limit walks to completion, which is
+     * what every caller that wants an answer passes.
+     */
+    private static walkCovering;
     static tag(geohash: string): string;
     static encodeTag(lat: number, lon: number, precision?: number): string;
     static encodeMultiTags(lat: number, lon: number): string[];
     static haversineKm(lat1: number, lon1: number, lat2: number, lon2: number): number;
     private static cellIntersectsCircle;
+    /**
+     * The longitude in [lonMin, lonMax] nearest to `lon`, going the short way
+     * round the globe.
+     *
+     * A plain clamp is wrong at the antimeridian, because -180 and +180 are the
+     * same meridian and a numeric comparison does not know it. Measured before
+     * this: a query at lon 179.99 against the cell spanning -180 to -179.989
+     * clamped to -179.989 and measured 2.334 km, when the true nearest point is
+     * -180.0 at 1.112 km. The cell was rejected from a 2 km radius it is well
+     * inside, and five of sixteen points on that circle's rim fell outside the
+     * covering — silently.
+     *
+     * Working in deltas normalised to +/-180 removes the discontinuity: the cell
+     * either straddles the query meridian, or lies wholly to one side of it and
+     * the nearer edge is the answer.
+     */
+    private static closestLongitude;
+    /** A longitude difference folded into [-180, 180]. */
+    private static normalizeLonDelta;
+    /**
+     * Covered area divided by the circle's, so a precision can be judged on what
+     * it wastes rather than only on what it costs.
+     */
+    private static coveredRatio;
     private static adjacent;
     private static normalizeHash;
     private static assertLatitude;

package/dist/index.js

@@ -41,7 +41,41 @@ var GeoHash = class {
   static INDEX_PRECISIONS = [5, 6];
   static BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz";
   static EARTH_RADIUS_KM = 6371;
-  static MAX_COVERING_CELLS = 64;
+  /**
+   * Most cells one radius query may expand into, and therefore the most SHOULD
+   * predicates it sends.
+   *
+   * This used to be 64 and it was a truncation limit: the walk stopped mid
+   * covering and returned what it had, so a 50 km search covered 18% of its own
+   * circle and said nothing. It is now a budget the precision is chosen to fit,
+   * so a covering is always complete or the request is refused.
+   *
+   * The number is set by latitude, not by radius. Cells needed at the coarsest
+   * indexed precision, measured: 50 km costs 376 at the equator, 592 at London,
+   * 720 at Oslo, 1,044 at Tromso, 2,028 at 80N. A first attempt used 512,
+   * chosen at one latitude, and it refused a 50 km search anywhere above 60
+   * degrees — Oslo, Stockholm, Helsinki, Saint Petersburg.
+   *
+   * The cost is bounded: measured against a live engine, a covering costs about
+   * 0.57 us per cell, so a query at the full budget spends roughly 1.2 ms in
+   * the engine, and stays half of its 4,096-filter ceiling.
+   */
+  static COVERING_CELL_BUDGET = 2048;
+  /**
+   * How much area outside the circle a covering may carry before a finer
+   * precision is worth its cell count.
+   *
+   * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+   * excess area is cheaper than predicates.
+   *
+   * 2.0 was the first attempt and it was too strict. It rejected the coarse
+   * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+   * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+   * time — the cost is the request, not the search. 3.0 keeps the cheap
+   * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+   * it wastes 4.73x to 6.91x depending on latitude.
+   */
+  static ACCEPTABLE_COVER_RATIO = 3;
   static NEIGHBORS = {
     n: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
     s: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],
@@ -166,31 +200,98 @@ var GeoHash = class {
   static neighborhoodTags(lat, lon, precision = 6) {
     return this.neighborhood3x3(this.encode(lat, lon, precision)).map((cell) => this.tag(cell));
   }
-  static optimalPrecisionForRadius(radiusKm) {
+  /**
+   * The precision a radius query should cover at, at this point on the globe.
+   *
+   * Only ever one of {@link INDEX_PRECISIONS}. That is the correction: this
+   * used to return 4 for anything over 8 km, and nothing is indexed at
+   * precision 4, so **every radius above 8 km matched nothing at all**.
+   * Measured against a real engine with entities tagged by `encodeMultiTags`:
+   * 15 km returned 0 of 386, 50 km returned 0 of 4,282 — an empty page, with
+   * no error to explain it.
+   *
+   * Of the indexed precisions it returns the finest whose complete covering
+   * fits {@link COVERING_CELL_BUDGET}, because a finer cell wastes less area
+   * outside the circle. Measured at Riyadh: 5 km takes 140 cells at precision
+   * 6 for 1.21x the circle, against 10 cells at precision 5 for 2.76x; 15 km
+   * needs 1,120 at precision 6 and so falls to 47 at precision 5 for 1.44x.
+   *
+   * Latitude is a parameter because it changes the answer: a cell keeps its
+   * width in degrees, so it narrows in kilometres toward the poles and the same
+   * radius needs more of them.
+   *
+   * @throws when no indexed precision can cover the radius within the budget —
+   *         refused rather than half-covered.
+   */
+  static optimalPrecisionForRadius(radiusKm, lat = 0, lon = 0) {
     if (radiusKm < 0) {
       throw new Error("Radius must be non-negative.");
     }
-    if (radiusKm <= 1.5) {
-      return 6;
+    const budget = this.COVERING_CELL_BUDGET;
+    let fallback = null;
+    for (const precision of [...this.INDEX_PRECISIONS].sort((a, b) => a - b)) {
+      const cells = this.walkCovering(lat, lon, radiusKm, precision, budget + 1);
+      if (cells.length > budget) {
+        continue;
+      }
+      if (radiusKm > 0 && this.coveredRatio(cells, radiusKm) <= this.ACCEPTABLE_COVER_RATIO) {
+        return precision;
+      }
+      fallback = precision;
     }
-    if (radiusKm <= 8) {
-      return 5;
+    if (fallback !== null) {
+      return fallback;
     }
-    return 4;
+    throw new Error(
+      `A ${radiusKm} km radius at latitude ${lat.toFixed(1)} needs more than ${budget} geohash cells at every indexed precision (${this.INDEX_PRECISIONS.join(", ")}). Geohash cells narrow toward the poles, so the same radius costs more cells the further from the equator it is asked. Use a smaller radius, move the search nearer the equator, or index a coarser precision.`
+    );
   }
-  static precisionForRadius(radiusKm) {
-    return this.optimalPrecisionForRadius(radiusKm);
+  static precisionForRadius(radiusKm, lat = 0, lon = 0) {
+    return this.optimalPrecisionForRadius(radiusKm, lat, lon);
   }
+  /**
+   * GeoHashes whose cells cover the search circle.
+   *
+   * The covering is always complete. It used to stop at 64 cells and return
+   * what it had, so a caller asking for 50 km got cells covering 18% of that
+   * circle — with no error. Now the precision is chosen to fit the budget and
+   * the walk always finishes, so the result either covers the circle or the
+   * call refuses.
+   *
+   * Passing `precision` explicitly overrides the choice, and is checked against
+   * {@link INDEX_PRECISIONS}: entities carry tags only at those, so any other
+   * precision matches nothing at all rather than matching loosely.
+   */
   static getCoveringHashes(lat, lon, radiusKm, precision) {
     if (radiusKm < 0) {
       throw new Error("Radius must be non-negative.");
     }
-    const resolvedPrecision = precision ?? this.optimalPrecisionForRadius(radiusKm);
-    this.assertPrecision(resolvedPrecision);
-    const center = this.encode(lat, lon, resolvedPrecision);
+    let resolved;
+    if (precision === void 0) {
+      resolved = this.optimalPrecisionForRadius(radiusKm, lat, lon);
+    } else {
+      this.assertPrecision(precision);
+      if (!this.INDEX_PRECISIONS.includes(precision)) {
+        throw new Error(
+          `Precision ${precision} is not indexed, so a covering at it matches nothing. Indexed precisions: ${this.INDEX_PRECISIONS.join(", ")}.`
+        );
+      }
+      resolved = precision;
+    }
+    return this.walkCovering(lat, lon, radiusKm, resolved, null);
+  }
+  /**
+   * Every cell at `precision` that intersects the circle, breadth-first from
+   * the centre and expanding only through cells that intersect.
+   *
+   * `limit` exists only so the precision chooser can stop early once a
+   * precision is known not to fit; a null limit walks to completion, which is
+   * what every caller that wants an answer passes.
+   */
+  static walkCovering(lat, lon, radiusKm, precision, limit) {
     const covering = [];
     const visited = /* @__PURE__ */ new Set();
-    const queue = [center];
+    const queue = [this.encode(lat, lon, precision)];
     while (queue.length > 0) {
       const current = queue.shift();
       if (current === void 0 || visited.has(current)) {
@@ -201,8 +302,8 @@ var GeoHash = class {
         continue;
       }
       covering.push(current);
-      if (covering.length >= this.MAX_COVERING_CELLS) {
-        break;
+      if (limit !== null && covering.length >= limit) {
+        return covering;
       }
       for (const neighbor of this.neighbors(current)) {
         if (!visited.has(neighbor)) {
@@ -231,9 +332,49 @@ var GeoHash = class {
   static cellIntersectsCircle(hash, lat, lon, radiusKm) {
     const bounds = this.decodeBounds(hash);
     const closestLat = Math.min(Math.max(lat, bounds.latMin), bounds.latMax);
-    const closestLon = Math.min(Math.max(lon, bounds.lonMin), bounds.lonMax);
+    const closestLon = this.closestLongitude(lon, bounds.lonMin, bounds.lonMax);
     return this.haversineKm(lat, lon, closestLat, closestLon) <= radiusKm;
   }
+  /**
+   * The longitude in [lonMin, lonMax] nearest to `lon`, going the short way
+   * round the globe.
+   *
+   * A plain clamp is wrong at the antimeridian, because -180 and +180 are the
+   * same meridian and a numeric comparison does not know it. Measured before
+   * this: a query at lon 179.99 against the cell spanning -180 to -179.989
+   * clamped to -179.989 and measured 2.334 km, when the true nearest point is
+   * -180.0 at 1.112 km. The cell was rejected from a 2 km radius it is well
+   * inside, and five of sixteen points on that circle's rim fell outside the
+   * covering — silently.
+   *
+   * Working in deltas normalised to +/-180 removes the discontinuity: the cell
+   * either straddles the query meridian, or lies wholly to one side of it and
+   * the nearer edge is the answer.
+   */
+  static closestLongitude(lon, lonMin, lonMax) {
+    const toMin = this.normalizeLonDelta(lonMin - lon);
+    const toMax = this.normalizeLonDelta(lonMax - lon);
+    if (toMin <= 0 && toMax >= 0) {
+      return lon;
+    }
+    return Math.abs(toMin) <= Math.abs(toMax) ? lonMin : lonMax;
+  }
+  /** A longitude difference folded into [-180, 180]. */
+  static normalizeLonDelta(delta) {
+    return ((delta + 180) % 360 + 360) % 360 - 180;
+  }
+  /**
+   * Covered area divided by the circle's, so a precision can be judged on what
+   * it wastes rather than only on what it costs.
+   */
+  static coveredRatio(cells, radiusKm) {
+    const rad = (d) => d * Math.PI / 180;
+    const covered = cells.reduce((sum, hash) => {
+      const b = this.decodeBounds(hash);
+      return sum + this.EARTH_RADIUS_KM * rad(b.latMax - b.latMin) * this.EARTH_RADIUS_KM * Math.cos(rad((b.latMax + b.latMin) / 2)) * rad(b.lonMax - b.lonMin);
+    }, 0);
+    return covered / (Math.PI * radiusKm ** 2);
+  }
   static adjacent(hash, direction) {
     if (hash.length === 0) {
       throw new Error("GeoHash must not be empty.");
@@ -1095,7 +1236,37 @@ var PulseIndexClient = class _PulseIndexClient {
     return {
       matchedEntityIds: (raw.matchedEntityIds ?? []).map((id) => String(id)),
       totalMatches: Number(raw.totalMatches ?? 0),
-      executionTimeUs: Number(raw.executionTimeUs ?? 0)
+      executionTimeUs: Number(raw.executionTimeUs ?? 0),
+      // Exact only when nothing made the engine stop early. limit=0 asks for
+      // the count and no ids, and is the only shape that counts every match;
+      // any page can early-exit as soon as it is full.
+      totalIsExact: builder.toArray().limit === 0
+    };
+  }
+  /**
+   * A page of ids together with the real number of matches.
+   *
+   * A paged search stops as soon as the page is full — that is what makes it
+   * cost microseconds — so its total is whatever it had counted when it
+   * stopped. Measured on a million entities: a query with 166,325 matches
+   * reported 10,866 for a page of 100. Anything that prints "page 1 of N" from
+   * that number is wrong by an order of magnitude and looks fine.
+   *
+   * This sends the count query as well, so it costs two round trips and returns
+   * a total you can divide by a page size.
+   */
+  async searchWithTotal(query) {
+    const page = await this.search(query);
+    if (page.totalIsExact) {
+      return page;
+    }
+    const builder = query instanceof QueryBuilder ? query : QueryBuilder.fromOptions(query);
+    const counted = await this.search(builder.limit(0));
+    return {
+      matchedEntityIds: page.matchedEntityIds,
+      totalMatches: counted.totalMatches,
+      executionTimeUs: page.executionTimeUs + counted.executionTimeUs,
+      totalIsExact: true
     };
   }
   async index(entityIdOrInput, attributes = {}) {

package/dist/index.mjs

@@ -18,7 +18,41 @@ var GeoHash = class {
   static INDEX_PRECISIONS = [5, 6];
   static BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz";
   static EARTH_RADIUS_KM = 6371;
-  static MAX_COVERING_CELLS = 64;
+  /**
+   * Most cells one radius query may expand into, and therefore the most SHOULD
+   * predicates it sends.
+   *
+   * This used to be 64 and it was a truncation limit: the walk stopped mid
+   * covering and returned what it had, so a 50 km search covered 18% of its own
+   * circle and said nothing. It is now a budget the precision is chosen to fit,
+   * so a covering is always complete or the request is refused.
+   *
+   * The number is set by latitude, not by radius. Cells needed at the coarsest
+   * indexed precision, measured: 50 km costs 376 at the equator, 592 at London,
+   * 720 at Oslo, 1,044 at Tromso, 2,028 at 80N. A first attempt used 512,
+   * chosen at one latitude, and it refused a 50 km search anywhere above 60
+   * degrees — Oslo, Stockholm, Helsinki, Saint Petersburg.
+   *
+   * The cost is bounded: measured against a live engine, a covering costs about
+   * 0.57 us per cell, so a query at the full budget spends roughly 1.2 ms in
+   * the engine, and stays half of its 4,096-filter ceiling.
+   */
+  static COVERING_CELL_BUDGET = 2048;
+  /**
+   * How much area outside the circle a covering may carry before a finer
+   * precision is worth its cell count.
+   *
+   * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+   * excess area is cheaper than predicates.
+   *
+   * 2.0 was the first attempt and it was too strict. It rejected the coarse
+   * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+   * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+   * time — the cost is the request, not the search. 3.0 keeps the cheap
+   * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+   * it wastes 4.73x to 6.91x depending on latitude.
+   */
+  static ACCEPTABLE_COVER_RATIO = 3;
   static NEIGHBORS = {
     n: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
     s: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],
@@ -143,31 +177,98 @@ var GeoHash = class {
   static neighborhoodTags(lat, lon, precision = 6) {
     return this.neighborhood3x3(this.encode(lat, lon, precision)).map((cell) => this.tag(cell));
   }
-  static optimalPrecisionForRadius(radiusKm) {
+  /**
+   * The precision a radius query should cover at, at this point on the globe.
+   *
+   * Only ever one of {@link INDEX_PRECISIONS}. That is the correction: this
+   * used to return 4 for anything over 8 km, and nothing is indexed at
+   * precision 4, so **every radius above 8 km matched nothing at all**.
+   * Measured against a real engine with entities tagged by `encodeMultiTags`:
+   * 15 km returned 0 of 386, 50 km returned 0 of 4,282 — an empty page, with
+   * no error to explain it.
+   *
+   * Of the indexed precisions it returns the finest whose complete covering
+   * fits {@link COVERING_CELL_BUDGET}, because a finer cell wastes less area
+   * outside the circle. Measured at Riyadh: 5 km takes 140 cells at precision
+   * 6 for 1.21x the circle, against 10 cells at precision 5 for 2.76x; 15 km
+   * needs 1,120 at precision 6 and so falls to 47 at precision 5 for 1.44x.
+   *
+   * Latitude is a parameter because it changes the answer: a cell keeps its
+   * width in degrees, so it narrows in kilometres toward the poles and the same
+   * radius needs more of them.
+   *
+   * @throws when no indexed precision can cover the radius within the budget —
+   *         refused rather than half-covered.
+   */
+  static optimalPrecisionForRadius(radiusKm, lat = 0, lon = 0) {
     if (radiusKm < 0) {
       throw new Error("Radius must be non-negative.");
     }
-    if (radiusKm <= 1.5) {
-      return 6;
+    const budget = this.COVERING_CELL_BUDGET;
+    let fallback = null;
+    for (const precision of [...this.INDEX_PRECISIONS].sort((a, b) => a - b)) {
+      const cells = this.walkCovering(lat, lon, radiusKm, precision, budget + 1);
+      if (cells.length > budget) {
+        continue;
+      }
+      if (radiusKm > 0 && this.coveredRatio(cells, radiusKm) <= this.ACCEPTABLE_COVER_RATIO) {
+        return precision;
+      }
+      fallback = precision;
     }
-    if (radiusKm <= 8) {
-      return 5;
+    if (fallback !== null) {
+      return fallback;
     }
-    return 4;
+    throw new Error(
+      `A ${radiusKm} km radius at latitude ${lat.toFixed(1)} needs more than ${budget} geohash cells at every indexed precision (${this.INDEX_PRECISIONS.join(", ")}). Geohash cells narrow toward the poles, so the same radius costs more cells the further from the equator it is asked. Use a smaller radius, move the search nearer the equator, or index a coarser precision.`
+    );
   }
-  static precisionForRadius(radiusKm) {
-    return this.optimalPrecisionForRadius(radiusKm);
+  static precisionForRadius(radiusKm, lat = 0, lon = 0) {
+    return this.optimalPrecisionForRadius(radiusKm, lat, lon);
   }
+  /**
+   * GeoHashes whose cells cover the search circle.
+   *
+   * The covering is always complete. It used to stop at 64 cells and return
+   * what it had, so a caller asking for 50 km got cells covering 18% of that
+   * circle — with no error. Now the precision is chosen to fit the budget and
+   * the walk always finishes, so the result either covers the circle or the
+   * call refuses.
+   *
+   * Passing `precision` explicitly overrides the choice, and is checked against
+   * {@link INDEX_PRECISIONS}: entities carry tags only at those, so any other
+   * precision matches nothing at all rather than matching loosely.
+   */
   static getCoveringHashes(lat, lon, radiusKm, precision) {
     if (radiusKm < 0) {
       throw new Error("Radius must be non-negative.");
     }
-    const resolvedPrecision = precision ?? this.optimalPrecisionForRadius(radiusKm);
-    this.assertPrecision(resolvedPrecision);
-    const center = this.encode(lat, lon, resolvedPrecision);
+    let resolved;
+    if (precision === void 0) {
+      resolved = this.optimalPrecisionForRadius(radiusKm, lat, lon);
+    } else {
+      this.assertPrecision(precision);
+      if (!this.INDEX_PRECISIONS.includes(precision)) {
+        throw new Error(
+          `Precision ${precision} is not indexed, so a covering at it matches nothing. Indexed precisions: ${this.INDEX_PRECISIONS.join(", ")}.`
+        );
+      }
+      resolved = precision;
+    }
+    return this.walkCovering(lat, lon, radiusKm, resolved, null);
+  }
+  /**
+   * Every cell at `precision` that intersects the circle, breadth-first from
+   * the centre and expanding only through cells that intersect.
+   *
+   * `limit` exists only so the precision chooser can stop early once a
+   * precision is known not to fit; a null limit walks to completion, which is
+   * what every caller that wants an answer passes.
+   */
+  static walkCovering(lat, lon, radiusKm, precision, limit) {
     const covering = [];
     const visited = /* @__PURE__ */ new Set();
-    const queue = [center];
+    const queue = [this.encode(lat, lon, precision)];
     while (queue.length > 0) {
       const current = queue.shift();
       if (current === void 0 || visited.has(current)) {
@@ -178,8 +279,8 @@ var GeoHash = class {
         continue;
       }
       covering.push(current);
-      if (covering.length >= this.MAX_COVERING_CELLS) {
-        break;
+      if (limit !== null && covering.length >= limit) {
+        return covering;
       }
       for (const neighbor of this.neighbors(current)) {
         if (!visited.has(neighbor)) {
@@ -208,9 +309,49 @@ var GeoHash = class {
   static cellIntersectsCircle(hash, lat, lon, radiusKm) {
     const bounds = this.decodeBounds(hash);
     const closestLat = Math.min(Math.max(lat, bounds.latMin), bounds.latMax);
-    const closestLon = Math.min(Math.max(lon, bounds.lonMin), bounds.lonMax);
+    const closestLon = this.closestLongitude(lon, bounds.lonMin, bounds.lonMax);
     return this.haversineKm(lat, lon, closestLat, closestLon) <= radiusKm;
   }
+  /**
+   * The longitude in [lonMin, lonMax] nearest to `lon`, going the short way
+   * round the globe.
+   *
+   * A plain clamp is wrong at the antimeridian, because -180 and +180 are the
+   * same meridian and a numeric comparison does not know it. Measured before
+   * this: a query at lon 179.99 against the cell spanning -180 to -179.989
+   * clamped to -179.989 and measured 2.334 km, when the true nearest point is
+   * -180.0 at 1.112 km. The cell was rejected from a 2 km radius it is well
+   * inside, and five of sixteen points on that circle's rim fell outside the
+   * covering — silently.
+   *
+   * Working in deltas normalised to +/-180 removes the discontinuity: the cell
+   * either straddles the query meridian, or lies wholly to one side of it and
+   * the nearer edge is the answer.
+   */
+  static closestLongitude(lon, lonMin, lonMax) {
+    const toMin = this.normalizeLonDelta(lonMin - lon);
+    const toMax = this.normalizeLonDelta(lonMax - lon);
+    if (toMin <= 0 && toMax >= 0) {
+      return lon;
+    }
+    return Math.abs(toMin) <= Math.abs(toMax) ? lonMin : lonMax;
+  }
+  /** A longitude difference folded into [-180, 180]. */
+  static normalizeLonDelta(delta) {
+    return ((delta + 180) % 360 + 360) % 360 - 180;
+  }
+  /**
+   * Covered area divided by the circle's, so a precision can be judged on what
+   * it wastes rather than only on what it costs.
+   */
+  static coveredRatio(cells, radiusKm) {
+    const rad = (d) => d * Math.PI / 180;
+    const covered = cells.reduce((sum, hash) => {
+      const b = this.decodeBounds(hash);
+      return sum + this.EARTH_RADIUS_KM * rad(b.latMax - b.latMin) * this.EARTH_RADIUS_KM * Math.cos(rad((b.latMax + b.latMin) / 2)) * rad(b.lonMax - b.lonMin);
+    }, 0);
+    return covered / (Math.PI * radiusKm ** 2);
+  }
   static adjacent(hash, direction) {
     if (hash.length === 0) {
       throw new Error("GeoHash must not be empty.");
@@ -1072,7 +1213,37 @@ var PulseIndexClient = class _PulseIndexClient {
     return {
       matchedEntityIds: (raw.matchedEntityIds ?? []).map((id) => String(id)),
       totalMatches: Number(raw.totalMatches ?? 0),
-      executionTimeUs: Number(raw.executionTimeUs ?? 0)
+      executionTimeUs: Number(raw.executionTimeUs ?? 0),
+      // Exact only when nothing made the engine stop early. limit=0 asks for
+      // the count and no ids, and is the only shape that counts every match;
+      // any page can early-exit as soon as it is full.
+      totalIsExact: builder.toArray().limit === 0
+    };
+  }
+  /**
+   * A page of ids together with the real number of matches.
+   *
+   * A paged search stops as soon as the page is full — that is what makes it
+   * cost microseconds — so its total is whatever it had counted when it
+   * stopped. Measured on a million entities: a query with 166,325 matches
+   * reported 10,866 for a page of 100. Anything that prints "page 1 of N" from
+   * that number is wrong by an order of magnitude and looks fine.
+   *
+   * This sends the count query as well, so it costs two round trips and returns
+   * a total you can divide by a page size.
+   */
+  async searchWithTotal(query) {
+    const page = await this.search(query);
+    if (page.totalIsExact) {
+      return page;
+    }
+    const builder = query instanceof QueryBuilder ? query : QueryBuilder.fromOptions(query);
+    const counted = await this.search(builder.limit(0));
+    return {
+      matchedEntityIds: page.matchedEntityIds,
+      totalMatches: counted.totalMatches,
+      executionTimeUs: page.executionTimeUs + counted.executionTimeUs,
+      totalIsExact: true
     };
   }
   async index(entityIdOrInput, attributes = {}) {

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@pulseindex/sdk",
-  "version": "3.2.0",
-  "description": "Official Node.js & TypeScript SDK for PulseIndex — hosted search and filtering for large entity sets",
+  "version": "4.0.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-alfarra/pulseindex-js.git"
+  },
+  "description": "Official Node.js & TypeScript SDK for PulseIndex \u2014 hosted search and filtering for large entity sets",
   "license": "MIT",
   "author": "PulseIndex",
   "keywords": [