@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/out/uprn/existence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"existence.d.ts","sourceRoot":"","sources":["../../lib/uprn/existence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAwC,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACvG,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAyB,CAAA;AAEzD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAmB,CAAA;AAE1E,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,UAAU,CAAA;IAClB;;OAEG;IACH,UAAU,EAAE,mBAAmB,CAAA;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAqBtF"}
+{"version":3,"file":"existence.d.ts","sourceRoot":"","sources":["../../lib/uprn/existence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAwC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AACrG,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAGzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,QAAyB,CAAA;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAAmB,CAAA;AAE1E,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,UAAU,CAAA;IAClB;;;OAGG;IACH,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAqBtF"}

package/out/uprn/existence.js

@@ -3,12 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  * @file The consult `./lookup.ts`'s docstring instructs: "callers building negative evidence must consult
- *   `readLayerCoverage`, not this reader alone." A bare `null` from `nearestUPRN` is two different facts — no UPRN here,
- *   or nobody surveyed here — and this is the only place that separates them. It answers an {@link Exclusion} or `null`,
+ *   `readLayerCoverage`, not this reader by itself." A bare `null` from `nearestUPRN` is two different facts — no uprn here,
+ *   or an unsurveyed area — and this is the only place that separates them. It answers an {@link Exclusion} or `null`,
  *   so a caller cannot read an unsurveyed cell as an empty one by accident.
  *
- *   `radiusM` is a CALLER'S parameter with no default. There is no radius that is correct for both "which property is
- *   this coordinate" and "is this street built at all", and picking one here would bury that choice where nobody
+ *   `radiusM` is a caller'S parameter with no default. There is no radius that is correct for both "which property is
+ *   this coordinate" and "is this street built at all", and picking one here would bury that choice where reviewers
  *   reviewing an exclusion can see it.
  */
 import { readLayerCoverage, readLayerManifest } from "@mailwoman/core/layers";
@@ -16,36 +16,46 @@ import { foldIdentity, requireExclusionBasis } from "@mailwoman/evidence";
 import { shortCellToParentInt } from "@mailwoman/spatial";
 import { UPRN_COVERAGE_H3_RESOLUTION, UPRN_H3_RESOLUTION, uprnH3Cell } from "#uprn/schema";
 /**
- * The identity fold, on purpose: this probe keys on a COORDINATE, not a name, so there is no string folding for the
- * builder and the probe to disagree about. Passing the same identity as both `probeFold` and `layerFold` records that
- * the fold axis is not in play here, rather than silently omitting the check. It is not a stub.
+ * The identity fold, on purpose: this probe keys on a coordinate rather than a name,
+ * so there is no string folding for the builder and the probe to disagree about.
+ *
+ * The same identity in both `probeFold` and `layerFold` records that the fold axis
+ * is not in play here, rather than silently omitting the check.
+ * It is not a stub.
  */
 export const UPRN_EXISTENCE_FOLD = foldIdentity((s) => s);
 /**
- * The countries OS Open UPRN covers. Northern Ireland is outside the product, so a `null` there is unknown and must
- * never become evidence of absence; the country check is what keeps it out.
+ * The countries OS Open uprn covers.
+ *
+ * Northern Ireland is outside the product, so a `null` there is unknown
+ * and must never become evidence of absence.
+ * The country check is what keeps it out.
  */
 export const UPRN_COVERED_COUNTRIES = new Set(["GB"]);
 /**
- * The coverage cell a coordinate falls in, derived from its stored res-9 cell exactly as the builder derives it — never
- * from the centroid, which lands in a different parent for a fraction of cells.
+ * The coverage cell a coordinate falls in, derived from its stored res-9 cell exactly
+ * as the builder derives it rather than from the centroid.
+ *
+ * The centroid lands in a different parent for a fraction of cells.
  */
 export function uprnCoverageCell(latitude, longitude) {
     return shortCellToParentInt(uprnH3Cell(latitude, longitude), UPRN_H3_RESOLUTION, UPRN_COVERAGE_H3_RESOLUTION);
 }
 /**
- * An {@link Exclusion} when no UPRN lies within `radiusM` AND the layer's coverage licenses saying so; `null` on a hit
- * (presence is not this probe's business) and on every refusal (unsurveyed cell, `source_present` basis, a country the
- * product does not cover). Never throws on a refusal: the caller falls open to the ranking it already had.
+ * An {@link Exclusion} when no uprn lies within `radiusM` and the layer's coverage licenses
+ * saying so; `null` on a hit (presence is not this probe's business) and on every refusal
+ * (unsurveyed cell, `source_present` basis, a country the product does not cover).
+ *
+ * Never throws on a refusal: the caller falls open to the ranking it already had.
  */
 export async function uprnAbsenceAt(input) {
     const coverageCell = uprnCoverageCell(input.latitude, input.longitude);
-    const coverage = await readLayerCoverage(input.contractDB, coverageCell);
+    const coverage = await readLayerCoverage(input.schemadb, coverageCell);
     if (!coverage)
         return null;
     if (input.lookup.nearestUPRN(input.latitude, input.longitude, input.radiusM))
         return null;
-    const manifest = await readLayerManifest(input.contractDB);
+    const manifest = await readLayerManifest(input.schemadb);
     return requireExclusionBasis({
         layer: manifest.name,
         source: manifest.source,

package/out/uprn/existence.js.map

@@ -1 +1 @@
-{"version":3,"file":"existence.js","sourceRoot":"","sources":["../../lib/uprn/existence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAA4B,MAAM,wBAAwB,CAAA;AACvG,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAkB,MAAM,qBAAqB,CAAA;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAGzD,OAAO,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;AAiB1E;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,SAAiB;IACnE,OAAO,oBAAoB,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,kBAAkB,EAAE,2BAA2B,CAAC,CAAA;AAC9G,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAuB;IAC1D,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IACtE,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA;IAExE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE1B,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAA;IAEzF,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IAE1D,OAAO,qBAAqB,CAAC;QAC5B,KAAK,EAAE,QAAQ,CAAC,IAAI;QACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,aAAa;QAC/B,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,mBAAmB;QAC9B,SAAS,EAAE,mBAAmB;QAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,sBAAsB;KACjC,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"existence.js","sourceRoot":"","sources":["../../lib/uprn/existence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAA0B,MAAM,wBAAwB,CAAA;AACrG,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAkB,MAAM,qBAAqB,CAAA;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAGzD,OAAO,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE1F;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;AAkB1E;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,SAAiB;IACnE,OAAO,oBAAoB,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,kBAAkB,EAAE,2BAA2B,CAAC,CAAA;AAC9G,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAuB;IAC1D,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IACtE,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAEtE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE1B,IAAI,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAA;IAEzF,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;IAExD,OAAO,qBAAqB,CAAC;QAC5B,KAAK,EAAE,QAAQ,CAAC,IAAI;QACpB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,OAAO,EAAE,QAAQ,CAAC,aAAa;QAC/B,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,QAAQ;QACd,SAAS,EAAE,mBAAmB;QAC9B,SAAS,EAAE,mBAAmB;QAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,sBAAsB;KACjC,CAAC,CAAA;AACH,CAAC"}

package/out/uprn/lookup.d.ts

@@ -3,79 +3,49 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader for `uprn.db` — the OS Open UPRN layer (`uprn-schema.ts`). Two probes:
- *
- *   - **`coordinateOf(uprn)`**: rowid B-tree hit on the `uprn` integer PK.
- *   - **`nearestUPRN(lat, lon, radiusM)`**: bounded nearest-point search over the res-9 `h3_cell`
- *     index — ring-by-ring `gridDisk` expansion with chunked `IN` probes and haversine ranking.
- *     Rings stop as soon as geometry proves no unprobed cell could beat the best hit — a distance
- *     bound, not POILookup's row-count accumulation, so the early exit can never strand a nearer
- *     point in an unprobed ring.
- *
- *   ## `null` is a claim, scoped by coverage
- *
- *   OS designates Open UPRN complete for GB (every UPRN in AddressBase Premium with geometry), and
- *   the builder writes `layer_coverage` with basis `designated` for every cell the product touches.
- *   So a `null` from either probe inside a covered cell is evidence of absence — "no such published
- *   GB UPRN" / "no UPRN within the radius". Outside coverage (Northern Ireland, the Isle of Man, the
- *   Channel Islands, open water) it is UNKNOWN, per the meaning-of-zero rule — callers building
- *   negative evidence must consult `readLayerCoverage`, not this reader alone.
- *
- *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing is
- *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
+ * Node reader for `uprn.db`, where a `null` is evidence of absence only inside published coverage, so callers building negative evidence must consult `readLayerCoverage`.
  */
+import { type GeoCoordinate } from "@mailwoman/spatial";
 import { DatabaseClient } from "@mailwoman/sqlite/client";
+import type { PathBuilderLike } from "path-ts";
 import type { UPRNDatabase } from "#uprn/schema";
 /**
- * Hard ceiling on `radiusM`. Keeps the probe bounded (10 km → ~72 rings ≈ 15.8k cells ≈ 18 `IN` chunks); a caller who
- * wants a wider search than "which property is this coordinate" has outgrown this reader and should say so loudly.
+ * Hard ceiling on `radiusM` that keeps the probe bounded, since a caller wanting a wider
+ * search than "which property is this coordinate" has outgrown this reader.
  */
 export declare const UPRN_MAX_NEAREST_RADIUS_M = 10000;
-export interface UPRNCoordinate {
-    latitude: number;
-    longitude: number;
-}
 export interface UPRNNearestHit {
     uprn: number;
     latitude: number;
     longitude: number;
     /**
-     * Haversine distance from the query point, metres.
+     * Haversine distance from the query point, meters.
      */
     distanceM: number;
 }
 export interface UPRNLookupOpts {
     /**
-     * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline. Opened read-only.
+     * Path to a `uprn.db` built by `mailwoman`'s gazetteer pipeline, opened read-only.
      */
-    databasePath?: string;
+    databasePath?: PathBuilderLike;
     /**
-     * Pre-opened handle (tests / shared connections). Mutually exclusive with `databasePath`.
+     * Pre-opened handle (tests / shared connections), mutually exclusive with `databasePath`.
      */
     database?: DatabaseClient<UPRNDatabase>;
 }
 /**
- * Node reader over `uprn.db`. `implements Disposable` so callers can `using lookup = new UPRNLookup(...)` — the same
- * precedent as {@link POILookup}.
+ * Node reader over `uprn.db`, disposable so callers can take it with `using`.
  */
 export declare class UPRNLookup implements Disposable {
     #private;
     constructor(opts: UPRNLookupOpts);
     /**
-     * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such UPRN (see the module docstring for
-     * what that `null` claims).
+     * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such uprn.
      */
-    coordinateOf(uprn: number): UPRNCoordinate | null;
+    coordinateOf(uprn: number): GeoCoordinate | null;
     /**
-     * The single nearest UPRN within `radiusM` metres of the query point, or `null` when no UPRN lies inside the radius.
-     *
-     * Bounded two ways: `radiusM` is capped at {@link UPRN_MAX_NEAREST_RADIUS_M}, and rings expand outward only until no
-     * unprobed cell could beat the best hit found so far (or the radius, when nothing has been found). The stop rule is
-     * geometric — a cell at grid distance `g` holds no point nearer than `g` × spacing floor − cell radius, using the
-     * same conservative constants the reach math uses — so unlike POILookup's row-count accumulation there is no
-     * early-exit ambiguity: a break can never strand a nearer point in an unprobed ring. This is what keeps a
-     * capped-radius call over dense ground at milliseconds instead of a full-disk fetch (measured 6.4 s → 13 ms for a 10
-     * km radius over central London, 41.6M-row layer; an empty-sea miss at the cap runs the full expansion, 74 ms).
+     * The single nearest uprn within `radiusM` meters of the query point, or `null`
+     * when no uprn lies inside the radius.
      *
      * @throws {RangeError} When `radiusM` is not a positive finite number, or exceeds the cap.
      */

package/out/uprn/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/uprn/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAGzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAiBhD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAO/C,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,YAAY,CAAC,CAAA;CACvC;AAQD;;;GAGG;AACH,qBAAa,UAAW,YAAW,UAAU;;gBAahC,IAAI,EAAE,cAAc;IAYhC;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAMjD;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAyDxF,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGxB"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../lib/uprn/lookup.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAA+B,KAAK,aAAa,EAAe,MAAM,oBAAoB,CAAA;AACjG,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAchD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAA;AAO/C,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAC9B;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC,YAAY,CAAC,CAAA;CACvC;AAQD;;GAEG;AACH,qBAAa,UAAW,YAAW,UAAU;;IAU5C,YAAY,IAAI,EAAE,cAAc,EAa/B;IAED;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAI/C;IAED;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAmDvF;IAED,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACD"}

package/out/uprn/lookup.js

@@ -3,26 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Node reader for `uprn.db` — the OS Open UPRN layer (`uprn-schema.ts`). Two probes:
- *
- *   - **`coordinateOf(uprn)`**: rowid B-tree hit on the `uprn` integer PK.
- *   - **`nearestUPRN(lat, lon, radiusM)`**: bounded nearest-point search over the res-9 `h3_cell`
- *     index — ring-by-ring `gridDisk` expansion with chunked `IN` probes and haversine ranking.
- *     Rings stop as soon as geometry proves no unprobed cell could beat the best hit — a distance
- *     bound, not POILookup's row-count accumulation, so the early exit can never strand a nearer
- *     point in an unprobed ring.
- *
- *   ## `null` is a claim, scoped by coverage
- *
- *   OS designates Open UPRN complete for GB (every UPRN in AddressBase Premium with geometry), and
- *   the builder writes `layer_coverage` with basis `designated` for every cell the product touches.
- *   So a `null` from either probe inside a covered cell is evidence of absence — "no such published
- *   GB UPRN" / "no UPRN within the radius". Outside coverage (Northern Ireland, the Isle of Man, the
- *   Channel Islands, open water) it is UNKNOWN, per the meaning-of-zero rule — callers building
- *   negative evidence must consult `readLayerCoverage`, not this reader alone.
- *
- *   `latLngToCell`/`gridDisk` come from `h3-js`; the 48-bit short-cell packing is
- *   `@mailwoman/spatial`'s `shortCellToInt` via `uprnFullCell` — never reimplemented here.
+ * Node reader for `uprn.db`, where a `null` is evidence of absence only inside published coverage, so callers building negative evidence must consult `readLayerCoverage`.
  */
 import { allRows } from "@mailwoman/core/utils";
 import { haversineKm, shortCellToInt } from "@mailwoman/spatial";
@@ -30,21 +11,18 @@ import { DatabaseClient } from "@mailwoman/sqlite/client";
 import { gridDisk } from "h3-js";
 import { uprnFullCell } from "#uprn/schema";
 /**
- * Conservative FLOOR on how much CENTRE distance one unit of res-9 GRID distance buys, metres. Adjacent centres sit √3
- * × edge apart (avg edge 174.4 m → ≈302 m); the worst bearing across a ring costs a further ×0.866, and H3's projection
- * distortion shrinks edges by well under the slack this leaves (the true worst is ≈217 m per grid step). Dividing a
- * radius by this over-counts rings and can never miss a cell; multiplying a grid distance by it under-states reach and
- * can never end the ring walk early.
+ * Conservative floor, in meters, on the center distance one unit of res-9 grid distance buys,
+ * so multiplying a grid distance under-states reach and can never end the ring walk early.
  */
 const RES9_CENTER_SPACING_FLOOR_M = 150;
 /**
- * Conservative CEILING on a res-9 cell's centre-to-vertex distance, metres (avg edge 174.4 m; distortion stays well
- * under this). A point within `radiusM` of the query sits in a cell whose CENTRE is within `radiusM` + this.
+ * Conservative ceiling, in meters, on a res-9 cell's center-to-vertex distance, so a point
+ * within `radiusM` of the query sits in a cell whose center is within `radiusM` plus this.
  */
 const RES9_CELL_RADIUS_CEILING_M = 300;
 /**
- * Hard ceiling on `radiusM`. Keeps the probe bounded (10 km → ~72 rings ≈ 15.8k cells ≈ 18 `IN` chunks); a caller who
- * wants a wider search than "which property is this coordinate" has outgrown this reader and should say so loudly.
+ * Hard ceiling on `radiusM` that keeps the probe bounded, since a caller wanting a wider
+ * search than "which property is this coordinate" has outgrown this reader.
  */
 export const UPRN_MAX_NEAREST_RADIUS_M = 10_000;
 /**
@@ -52,50 +30,40 @@ export const UPRN_MAX_NEAREST_RADIUS_M = 10_000;
  */
 const CELL_PROBE_CHUNK = 900;
 /**
- * Node reader over `uprn.db`. `implements Disposable` so callers can `using lookup = new UPRNLookup(...)` — the same
- * precedent as {@link POILookup}.
+ * Node reader over `uprn.db`, disposable so callers can take it with `using`.
  */
 export class UPRNLookup {
     #db;
     /**
-     * Resources this instance opened. A connection handed in by a caller is NOT in here, so disposal cannot reach it —
-     * ownership is membership rather than a flag a later branch has to check.
-     */
-    #resources = new DisposableStack();
-    /**
-     * `uprn` → its point (rowid-alias PK hit).
+     * Ownership is membership: a connection handed in by a caller is not in here,
+     * so disposal cannot reach it.
      */
+    #resources;
     #coordinateProbe;
     constructor(opts) {
+        using resources = new DisposableStack();
         if (opts.database) {
             this.#db = opts.database;
         }
         else if (opts.databasePath) {
-            this.#db = this.#resources.use(new DatabaseClient(opts.databasePath, { readOnly: true }));
+            this.#db = resources.use(new DatabaseClient(opts.databasePath, { readOnly: true }));
         }
         else {
             throw new Error("UPRNLookup needs `databasePath` or `database`");
         }
         this.#coordinateProbe = this.#db.prepare("SELECT lat, lon FROM uprn WHERE uprn = ?");
+        this.#resources = resources.move();
     }
     /**
-     * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such UPRN (see the module docstring for
-     * what that `null` claims).
+     * The WGS84 point OS publishes for `uprn`, or `null` when the layer holds no such uprn.
      */
     coordinateOf(uprn) {
         const row = this.#coordinateProbe.get(uprn);
         return row ? { latitude: row.lat, longitude: row.lon } : null;
     }
     /**
-     * The single nearest UPRN within `radiusM` metres of the query point, or `null` when no UPRN lies inside the radius.
-     *
-     * Bounded two ways: `radiusM` is capped at {@link UPRN_MAX_NEAREST_RADIUS_M}, and rings expand outward only until no
-     * unprobed cell could beat the best hit found so far (or the radius, when nothing has been found). The stop rule is
-     * geometric — a cell at grid distance `g` holds no point nearer than `g` × spacing floor − cell radius, using the
-     * same conservative constants the reach math uses — so unlike POILookup's row-count accumulation there is no
-     * early-exit ambiguity: a break can never strand a nearer point in an unprobed ring. This is what keeps a
-     * capped-radius call over dense ground at milliseconds instead of a full-disk fetch (measured 6.4 s → 13 ms for a 10
-     * km radius over central London, 41.6M-row layer; an empty-sea miss at the cap runs the full expansion, 74 ms).
+     * The single nearest uprn within `radiusM` meters of the query point, or `null`
+     * when no uprn lies inside the radius.
      *
      * @throws {RangeError} When `radiusM` is not a positive finite number, or exceeds the cap.
      */
@@ -109,16 +77,13 @@ export class UPRNLookup {
         const origin = uprnFullCell(latitude, longitude);
         const seenCells = new Set();
         let best = null;
-        // `ring` is H3 grid distance; the loop terminates because the break bound is at most radiusM, which the
-        // RangeError above caps.
+        // The loop terminates because the break bound is at most `radiusM`.
+        // The RangeError above caps that value.
         for (let ring = 0;; ring++) {
-            // A cell at grid distance `ring` holds no point nearer than this. Once it exceeds what could still
-            // win — the best hit so far, or the radius itself — further rings cannot improve the answer.
+            // Once this bound exceeds the best hit so far, or the radius, further rings cannot improve the answer.
             const closestPossibleM = ring * RES9_CENTER_SPACING_FLOOR_M - RES9_CELL_RADIUS_CEILING_M;
             if (closestPossibleM > Math.min(radiusM, best?.distanceM ?? radiusM))
                 break;
-            // gridDisk(origin, ring) returns the WHOLE disk out to `ring`; diffing against what's already been
-            // probed derives just this ring's new cells (the POILookup pattern).
             const diskCells = gridDisk(origin, ring);
             const newCells = [];
             for (const cell of diskCells) {
@@ -130,7 +95,6 @@ export class UPRNLookup {
             for (let i = 0; i < newCells.length; i += CELL_PROBE_CHUNK) {
                 const chunk = newCells.slice(i, i + CELL_PROBE_CHUNK);
                 const placeholders = chunk.map(() => "?").join(", ");
-                // Prepared fresh per chunk arity — a cold, per-call path, same posture as POILookup's batched hydration.
                 const rows = allRows(this.#db.prepare(`SELECT uprn, lat, lon FROM uprn WHERE h3_cell IN (${placeholders})`), ...chunk);
                 for (const row of rows) {
                     const distanceM = haversineKm(latitude, longitude, row.lat, row.lon) * 1000;

package/out/uprn/lookup.js.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../lib/uprn/lookup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../lib/uprn/lookup.ts"],"names":[],"mappings":"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"}

package/out/uprn/schema.d.ts

@@ -3,46 +3,22 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for `uprn.db` — the OS Open UPRN spatial layer: every GB Unique Property Reference
- *   Number with its WGS84 point, so mailwoman results can carry UPRN as an interoperability key
- *   beside our own `@mailwoman/address-id`. One rowid table keyed `uprn INTEGER PRIMARY KEY` (the
- *   rowid alias — the optimal shape for an integer-PK point table; `WITHOUT ROWID` buys nothing
- *   here), plus a secondary res-9 `h3_cell` index for the bounded nearest-point probe.
- *
- *   ## Coordinates are OS's own WGS84 columns
- *
- *   The source CSV publishes BOTH coordinate systems per row — OSGB36 eastings/northings AND WGS84
- *   `LATITUDE`/`LONGITUDE`. This layer stores OS's own lat/lon verbatim and never reconverts from
- *   eastings: `@mailwoman/spatial`'s `osgb36ToWGS84` is a 7-parameter Helmert with a measured p95 of
- *   4.18 m, and re-deriving what the publisher already computed (with OSTN15, exactly) would replace
- *   their answer with a strictly worse one.
- *
- *   ## Why `h3_cell` exists at all
- *
- *   The layer contract requires every domain row to be addressable by at least one spine key —
- *   `writeLayerManifest` throws on a manifest that declares none — and UPRN is its own id space, not
- *   H3/WOF/address-id/street. The res-9 short cell (`shortCellToInt`, the same packing as poi.db and
- *   the OSM situs extracts) is the spine that fits a point table, and its index doubles as the
- *   `nearestUPRN` ring probe.
- *
- *   The DB also embeds the layer-contract tables from `@mailwoman/core/layers`; the builder
- *   (`packages/mailwoman/lib/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
- *   coverage.
+ * Typed schema for `uprn.db`, storing OS's own WGS84 latitude/longitude verbatim rather than reconverting from the source's eastings.
  */
-import type { LayerContractDatabase } from "@mailwoman/core/layers";
+import type { layerschemadatabase } from "@mailwoman/core/layers";
 import { type H3Cell } from "@mailwoman/spatial";
 import type { Kysely } from "kysely";
 /**
- * Resolution the `uprn` table's `h3_cell` column is keyed at — the shared layer-spine resolution (poi.db, the OSM situs
- * extracts).
+ * Resolution the `uprn` table's `h3_cell` column is keyed at, shared with the other layer spines.
  */
 export declare const UPRN_H3_RESOLUTION = 9;
 /**
- * Resolution of the layer's `layer_coverage` cells — coarse, per the contract (matches poi.db).
+ * Resolution of the layer's `layer_coverage` cells, coarse per the layer interface
+ * and shared with the other spines.
  */
 export declare const UPRN_COVERAGE_H3_RESOLUTION = 6;
 /**
- * One UPRN point. `uprn` is the rowid alias, so the primary probe (`coordinateOf`) is a rowid B-tree hit.
+ * One uprn point whose `uprn` is a rowid alias, making the primary probe a rowid B-tree hit.
  */
 export interface UPRNTable {
     /**
@@ -50,7 +26,7 @@ export interface UPRNTable {
      */
     uprn: number;
     /**
-     * WGS84 latitude, as OS published it (never reconverted from eastings — see the module docstring).
+     * WGS84 latitude, as OS published it, never reconverted from eastings.
      */
     lat: number;
     /**
@@ -58,36 +34,38 @@ export interface UPRNTable {
      */
     lon: number;
     /**
-     * 48-bit short H3 cell at {@link UPRN_H3_RESOLUTION} (`uprnH3Cell`) — the layer-contract spine key and the
-     * `nearestUPRN` probe index.
+     * 48-bit short H3 cell at {@link UPRN_H3_RESOLUTION} — the layer-interface spine key
+     * and the `nearestUPRN` probe index.
      */
     h3_cell: number;
 }
 /**
- * Build-provenance key/value pairs the fixed `layer_manifest` columns have no room for: quality-drop counts, the header
- * as found, the upstream licence text verbatim (the Code-Point provenance discipline).
+ * Build-provenance key/value pairs the fixed `layer_manifest` columns have no room for,
+ * including the upstream license text verbatim.
  */
 export interface UPRNMetaTable {
     key: string;
     value: string;
 }
-export interface UPRNDatabase extends LayerContractDatabase {
+export interface UPRNDatabase extends layerschemadatabase {
     uprn: UPRNTable;
     uprn_meta: UPRNMetaTable;
 }
 /**
- * The full res-9 cell for a UPRN point — the ONE derivation both the builder and every consumer share, so a fixture
- * built by a test and a row built by the real ingest can never disagree on which cell a coordinate keys to.
+ * The full res-9 cell for a UPRN point.
+ *
+ * This is the one derivation the builder and its consumers share so their cells cannot disagree.
  */
 export declare function uprnFullCell(latitude: number, longitude: number): H3Cell;
 /**
- * The `h3_cell` column value for a UPRN point: {@link uprnFullCell} packed to the shared 48-bit short-cell integer.
+ * The `h3_cell` column value for a uprn point, packing {@link uprnFullCell} to
+ * the shared 48-bit short-cell integer.
  */
 export declare function uprnH3Cell(latitude: number, longitude: number): number;
 export declare function createUPRNTable(db: Kysely<UPRNDatabase>): Promise<void>;
 export declare function createUPRNMetaTable(db: Kysely<UPRNDatabase>): Promise<void>;
 /**
- * Secondary index for the `nearestUPRN` ring probe. Builders call this AFTER the bulk load (index-after-load).
+ * Secondary index for the `nearestUPRN` ring probe, created after the bulk load.
  */
 export declare function createUPRNIndexes(db: Kysely<UPRNDatabase>): Promise<void>;
 //# sourceMappingURL=schema.d.ts.map

package/out/uprn/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../lib/uprn/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AACnE,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;GAEG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAa,SAAQ,qBAAqB;IAC1D,IAAI,EAAE,SAAS,CAAA;IACf,SAAS,EAAE,aAAa,CAAA;CACxB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7E;AAED,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../lib/uprn/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAkB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAEhE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;GAEG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC;;;GAGG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACxD,IAAI,EAAE,SAAS,CAAA;IACf,SAAS,EAAE,aAAa,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7E;AAED,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjF;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/E"}

package/out/uprn/schema.js

@@ -3,52 +3,30 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Typed schema for `uprn.db` — the OS Open UPRN spatial layer: every GB Unique Property Reference
- *   Number with its WGS84 point, so mailwoman results can carry UPRN as an interoperability key
- *   beside our own `@mailwoman/address-id`. One rowid table keyed `uprn INTEGER PRIMARY KEY` (the
- *   rowid alias — the optimal shape for an integer-PK point table; `WITHOUT ROWID` buys nothing
- *   here), plus a secondary res-9 `h3_cell` index for the bounded nearest-point probe.
- *
- *   ## Coordinates are OS's own WGS84 columns
- *
- *   The source CSV publishes BOTH coordinate systems per row — OSGB36 eastings/northings AND WGS84
- *   `LATITUDE`/`LONGITUDE`. This layer stores OS's own lat/lon verbatim and never reconverts from
- *   eastings: `@mailwoman/spatial`'s `osgb36ToWGS84` is a 7-parameter Helmert with a measured p95 of
- *   4.18 m, and re-deriving what the publisher already computed (with OSTN15, exactly) would replace
- *   their answer with a strictly worse one.
- *
- *   ## Why `h3_cell` exists at all
- *
- *   The layer contract requires every domain row to be addressable by at least one spine key —
- *   `writeLayerManifest` throws on a manifest that declares none — and UPRN is its own id space, not
- *   H3/WOF/address-id/street. The res-9 short cell (`shortCellToInt`, the same packing as poi.db and
- *   the OSM situs extracts) is the spine that fits a point table, and its index doubles as the
- *   `nearestUPRN` ring probe.
- *
- *   The DB also embeds the layer-contract tables from `@mailwoman/core/layers`; the builder
- *   (`packages/mailwoman/lib/gazetteer-pipeline/uprn-layer.ts`) writes the manifest and per-res-6-cell
- *   coverage.
+ * Typed schema for `uprn.db`, storing OS's own WGS84 latitude/longitude verbatim rather than reconverting from the source's eastings.
  */
 import { shortCellToInt } from "@mailwoman/spatial";
 import { latLngToCell } from "h3-js";
 /**
- * Resolution the `uprn` table's `h3_cell` column is keyed at — the shared layer-spine resolution (poi.db, the OSM situs
- * extracts).
+ * Resolution the `uprn` table's `h3_cell` column is keyed at, shared with the other layer spines.
  */
 export const UPRN_H3_RESOLUTION = 9;
 /**
- * Resolution of the layer's `layer_coverage` cells — coarse, per the contract (matches poi.db).
+ * Resolution of the layer's `layer_coverage` cells, coarse per the layer interface
+ * and shared with the other spines.
  */
 export const UPRN_COVERAGE_H3_RESOLUTION = 6;
 /**
- * The full res-9 cell for a UPRN point — the ONE derivation both the builder and every consumer share, so a fixture
- * built by a test and a row built by the real ingest can never disagree on which cell a coordinate keys to.
+ * The full res-9 cell for a UPRN point.
+ *
+ * This is the one derivation the builder and its consumers share so their cells cannot disagree.
  */
 export function uprnFullCell(latitude, longitude) {
     return latLngToCell(latitude, longitude, UPRN_H3_RESOLUTION);
 }
 /**
- * The `h3_cell` column value for a UPRN point: {@link uprnFullCell} packed to the shared 48-bit short-cell integer.
+ * The `h3_cell` column value for a uprn point, packing {@link uprnFullCell} to
+ * the shared 48-bit short-cell integer.
  */
 export function uprnH3Cell(latitude, longitude) {
     return shortCellToInt(uprnFullCell(latitude, longitude));
@@ -70,7 +48,7 @@ export async function createUPRNMetaTable(db) {
         .execute();
 }
 /**
- * Secondary index for the `nearestUPRN` ring probe. Builders call this AFTER the bulk load (index-after-load).
+ * Secondary index for the `nearestUPRN` ring probe, created after the bulk load.
  */
 export async function createUPRNIndexes(db) {
     await db.schema.createIndex("uprn_h3_cell").on("uprn").column("h3_cell").execute();

package/out/uprn/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../lib/uprn/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,cAAc,EAAe,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAGpC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAA;AAuC5C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,SAAiB;IAC/D,OAAO,YAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAW,CAAA;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,SAAiB;IAC7D,OAAO,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAwB;IAC7D,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,MAAM,CAAC;SACnB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,OAAO,EAAE,CAAA;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAwB;IACjE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,WAAW,CAAC;SACxB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAwB;IAC/D,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AACnF,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../lib/uprn/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAe,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAGpC;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAA;AAuC5C;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,SAAiB;IAC/D,OAAO,YAAY,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAW,CAAA;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,SAAiB;IAC7D,OAAO,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAA;AACzD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAwB;IAC7D,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,MAAM,CAAC;SACnB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SACnD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC5C,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACnD,OAAO,EAAE,CAAA;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EAAwB;IACjE,MAAM,EAAE,CAAC,MAAM;SACb,WAAW,CAAC,WAAW,CAAC;SACxB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;SAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAC9C,OAAO,EAAE,CAAA;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAwB;IAC/D,MAAM,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAA;AACnF,CAAC"}

package/out/{uprn/index.d.ts → uprn.d.ts}

@@ -6,4 +6,4 @@
 export * from "#uprn/existence";
 export * from "#uprn/lookup";
 export * from "#uprn/schema";
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=uprn.d.ts.map

package/out/uprn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uprn.d.ts","sourceRoot":"","sources":["../lib/uprn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}

package/out/{uprn/index.js → uprn.js}

@@ -6,4 +6,4 @@
 export * from "#uprn/existence";
 export * from "#uprn/lookup";
 export * from "#uprn/schema";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=uprn.js.map

package/out/uprn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uprn.js","sourceRoot":"","sources":["../lib/uprn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA"}