@squawk/mcp 0.12.0 → 0.13.0

package/README.md

@@ -98,7 +98,7 @@ version explicitly in the client config:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "@squawk/mcp@0.12.0"]
+      "args": ["-y", "@squawk/mcp@0.13.0"]
     }
   }
 }
@@ -144,14 +144,17 @@ rest of the server keeps working normally. If you do not need aircraft lookups,
 is required.
 
 To enable lookups, install the data package alongside `@squawk/mcp`. Through `npx` the cleanest
-option is the `-p` flag, which adds extra packages to the temporary install npx builds:
+option is the `-p` flag, which adds extra packages to the temporary install npx builds. Once more
+than one package is involved, npx no longer infers which one to run, so give it each package
+behind its own `-p` and name the actual binary (`squawk-mcp`, not the package name) as the
+trailing command:
 
 ```json
 {
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "-p", "@squawk/icao-registry-data", "@squawk/mcp"]
+      "args": ["-y", "-p", "@squawk/icao-registry-data", "-p", "@squawk/mcp", "squawk-mcp"]
     }
   }
 }
@@ -164,7 +167,14 @@ Pinning works the same way:
   "mcpServers": {
     "squawk": {
       "command": "npx",
-      "args": ["-y", "-p", "@squawk/icao-registry-data@0.8.12", "@squawk/mcp@0.12.0"]
+      "args": [
+        "-y",
+        "-p",
+        "@squawk/icao-registry-data@0.8.12",
+        "-p",
+        "@squawk/mcp@0.13.0",
+        "squawk-mcp"
+      ]
     }
   }
 }
@@ -395,9 +405,9 @@ left to the model itself.
 
 ### Server diagnostics
 
-| Tool                 | Purpose                                                                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `get_dataset_status` | Report NASR cycle date, build timestamp, and record counts for every loaded snapshot (incl. lazy-load state) |
+| Tool                 | Purpose                                                                                                                 |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `get_dataset_status` | Report NASR/CIFP cycle date, build timestamp, and record counts for every bundled snapshot, plus whether each is loaded |
 
 ## Configuration
 
@@ -462,13 +472,16 @@ Two things worth knowing before you trim:
 - **`datasets` is a group like any other.** It holds `get_dataset_status`, the tool that
   reports which NASR and CIFP cycles the running server is serving. An allowlist that
   leaves it out means you can no longer ask how current the data is, so include it unless
-  you are sure you do not want it. It is the cheapest group in the catalog.
-- **Groups gate the catalog, not the data.** The bundled snapshots are loaded and indexed
-  at startup no matter which groups you register, so trimming the catalog does not reduce
-  the server's startup time or memory use. It also means a group you kept keeps working
-  even when it reads data belonging to a group you dropped - `flightplan` still resolves
-  airports and navaids in a route string with `airports` and `navaids` disabled, because
-  you disabled those tools, not that data.
+  you are sure you do not want it. It is the cheapest group in the catalog, and it stays
+  cheap: cycle dates and record counts are read from a small metadata module in each data
+  package, so asking for status never loads a snapshot.
+- **Trimming the catalog trims the data too.** Each snapshot is decompressed the first time
+  a tool actually reads it, so a group you never register is a group whose data never
+  loads. Dropping `procedures` from a session that never asks about approach plates saves
+  its load outright, not just its share of the context window. A group you kept still works
+  when it reads data belonging to a group you dropped - `flightplan` resolves airports and
+  navaids in a route string with `airports` and `navaids` disabled, loading those snapshots
+  on its own first call, because you disabled those tools, not that data.
 
 ## Notes
 
@@ -479,7 +492,11 @@ Two things worth knowing before you trim:
 - Live weather tools issue HTTPS requests to `https://aviationweather.gov/api/data/...` (or the
   override above). They are the only tools that touch the network at invocation time; everything
   else operates against bundled snapshots in memory.
-- The bundled snapshots are decompressed and indexed once when the server starts, which takes on
-  the order of a second and is unaffected by which tool groups you register. The aircraft
-  registration snapshot (the largest, and an optional peer dependency) is decompressed lazily on
-  the first `lookup_aircraft_by_icao_hex` call, if the package is installed.
+- Snapshots are decompressed and indexed on first use rather than at startup, so the server comes
+  up immediately and each dataset pays a one-time cost the first time a tool reads it. Every later
+  call against a loaded dataset is served from memory. Procedures is the largest of these loads and
+  navaids by far the smallest, with airports, fixes, airspace, and airways in between; loading all
+  of them is on the order of a second. Parsing a route string triggers the biggest single first
+  call, since `flightplan` draws on five snapshots at once. The aircraft registration snapshot (the
+  largest overall, and an optional peer dependency) loads on the first `lookup_aircraft_by_icao_hex`
+  call, if the package is installed.

package/dist/resolvers.d.ts

@@ -1,14 +1,20 @@
 /**
  * @packageDocumentation
- * Shared resolver instances used across the squawk MCP tool modules. Each
- * resolver is constructed once at module load time so the bundled FAA data
- * snapshots are decoded and indexed exactly once per server process.
+ * Shared resolver accessors used across the squawk MCP tool modules. Every
+ * bundled FAA snapshot loads on demand: the first accessor call dynamically
+ * imports its data package, decompresses and indexes the snapshot, and caches
+ * the result for the life of the process. A session that only asks about
+ * airports never decompresses the CIFP procedure snapshot, and a session that
+ * asks nothing pays nothing beyond process start.
  *
- * The ICAO registry is the only resolver that loads lazily, and its data
+ * Each accessor memoizes the in-flight load rather than the finished
+ * resolver, so concurrent tool calls needing the same dataset share one
+ * import and one index build instead of racing to build two.
+ *
+ * The ICAO registry follows the same shape with one extra wrinkle: its data
  * package (`@squawk/icao-registry-data`) is declared as an optional peer
- * dependency rather than a required dep. The registry is built on the first
- * {@link getIcaoRegistry} call (decompressing ~40 MB on first access) and
- * cached for subsequent calls. When the peer is not installed, the import
+ * dependency rather than a required dep, so a failed import is an expected
+ * outcome rather than a broken install. When the peer is absent the import
  * throws `ERR_MODULE_NOT_FOUND` and {@link getIcaoRegistry} surfaces a
  * {@link MissingDataPackageError} for the tool handler to format.
  */
@@ -19,18 +25,75 @@ import { type FixResolver } from '@squawk/fixes';
 import { type IcaoRegistry } from '@squawk/icao-registry';
 import { type NavaidResolver } from '@squawk/navaids';
 import { type ProcedureResolver } from '@squawk/procedures';
-/** Eagerly-built airport resolver backed by the US NASR snapshot. */
-export declare const airportResolver: AirportResolver;
-/** Eagerly-built airspace resolver backed by the US NASR airspace GeoJSON snapshot. */
-export declare const airspaceResolver: AirspaceResolver;
-/** Eagerly-built airway resolver backed by the US NASR snapshot. */
-export declare const airwayResolver: AirwayResolver;
-/** Eagerly-built fix resolver backed by the US NASR snapshot. */
-export declare const fixResolver: FixResolver;
-/** Eagerly-built navaid resolver backed by the US NASR snapshot. */
-export declare const navaidResolver: NavaidResolver;
-/** Eagerly-built procedure resolver backed by the US NASR snapshot. */
-export declare const procedureResolver: ProcedureResolver;
+/**
+ * Returns the shared airport resolver, importing and indexing the bundled US
+ * NASR airport snapshot on the first call.
+ *
+ * @returns The shared airport resolver.
+ */
+export declare function getAirportResolver(): Promise<AirportResolver>;
+/**
+ * Returns the shared airspace resolver, importing and indexing the bundled US
+ * NASR airspace GeoJSON snapshot on the first call.
+ *
+ * @returns The shared airspace resolver.
+ */
+export declare function getAirspaceResolver(): Promise<AirspaceResolver>;
+/**
+ * Returns the shared airway resolver, importing and indexing the bundled US
+ * NASR airway snapshot on the first call.
+ *
+ * @returns The shared airway resolver.
+ */
+export declare function getAirwayResolver(): Promise<AirwayResolver>;
+/**
+ * Returns the shared fix resolver, importing and indexing the bundled US NASR
+ * fix snapshot on the first call.
+ *
+ * @returns The shared fix resolver.
+ */
+export declare function getFixResolver(): Promise<FixResolver>;
+/**
+ * Returns the shared navaid resolver, importing and indexing the bundled US
+ * NASR navaid snapshot on the first call.
+ *
+ * @returns The shared navaid resolver.
+ */
+export declare function getNavaidResolver(): Promise<NavaidResolver>;
+/**
+ * Returns the shared procedure resolver, importing and indexing the bundled
+ * FAA CIFP procedure snapshot on the first call.
+ *
+ * @returns The shared procedure resolver.
+ */
+export declare function getProcedureResolver(): Promise<ProcedureResolver>;
+/**
+ * Whether each required bundled snapshot has been loaded into the running
+ * process. Build metadata is not part of this shape: it is available from
+ * each data package's `/meta` subpath without loading anything, so only the
+ * in-memory state has to be read from here.
+ */
+export interface BundledDatasetLoadState {
+    /** Whether the airport snapshot is loaded. */
+    readonly airports: boolean;
+    /** Whether the airspace snapshot is loaded. */
+    readonly airspace: boolean;
+    /** Whether the airway snapshot is loaded. */
+    readonly airways: boolean;
+    /** Whether the fix snapshot is loaded. */
+    readonly fixes: boolean;
+    /** Whether the navaid snapshot is loaded. */
+    readonly navaids: boolean;
+    /** Whether the procedure snapshot is loaded. */
+    readonly procedures: boolean;
+}
+/**
+ * Reports which required bundled snapshots are currently in memory, without
+ * loading any of them.
+ *
+ * @returns Per-dataset load state.
+ */
+export declare function getBundledDatasetLoadState(): BundledDatasetLoadState;
 /**
  * Error thrown when a tool tries to load an optional data package peer that
  * has not been installed alongside `@squawk/mcp`. Tool handlers catch this
@@ -59,12 +122,10 @@ type IcaoRegistryDataLoader = () => Promise<typeof import('@squawk/icao-registry
  * the bundled FAA aircraft registration snapshot on the first call. Subsequent
  * calls reuse the cached instance.
  *
- * The registry is initialized lazily because the underlying data package is
- * the largest snapshot in the suite (roughly 40 MB raw) and is declared as an
- * optional peer dependency rather than a required dep. Sessions that never
- * look up an aircraft by ICAO hex avoid the cost entirely, and consumers who
- * never install the peer see only the structured missing-package error
- * surfaced by the tool handler.
+ * The registry's data package is the largest snapshot in the suite (roughly
+ * 40 MB raw) and is declared as an optional peer dependency rather than a
+ * required dep, so consumers who never install the peer see only the
+ * structured missing-package error surfaced by the tool handler.
  *
  * @returns The shared registry instance.
  * @throws {MissingDataPackageError} when `@squawk/icao-registry-data` is not
@@ -76,8 +137,8 @@ export declare function getIcaoRegistry(): Promise<IcaoRegistry>;
  *
  * Test-only seam for swapping the optional data package loader. Production
  * code must not call this. Pass `undefined` to restore the default loader
- * and clear all cached state (instance, metadata, and the missing-peer
- * sticky flag) so subsequent tests start from a clean slate.
+ * and clear all cached state (instance, in-flight load, metadata, and the
+ * missing-peer sticky flag) so subsequent tests start from a clean slate.
  *
  * @param loader - Replacement loader, or `undefined` to reset.
  */

package/dist/resolvers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAGjF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE9E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAErF,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,eAE5B,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAE,gBAE7B,CAAC;AAEH,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,cAE3B,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,WAAW,EAAE,WAAiE,CAAC;AAE5F,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,cAE3B,CAAC;AAEH,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,EAAE,iBAE9B,CAAC;AAEH;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQrD;AAoBD,2EAA2E;AAC3E,KAAK,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,4BAA4B,CAAC,CAAC,CAAC;AA2BzF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAuB7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,sBAAsB,GAAG,SAAS,GACzC,IAAI,CAKN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IACrC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAEzD"}
+{"version":3,"file":"resolvers.d.ts","sourceRoot":"","sources":["../src/resolvers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAmGrF;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAEjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,uBAAuB,CASpE;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAQrD;AA0BD,2EAA2E;AAC3E,KAAK,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,4BAA4B,CAAC,CAAC,CAAC;AAwDzF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC,CAS7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,sBAAsB,GAAG,SAAS,GACzC,IAAI,CAMN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IACrC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAEzD"}

package/dist/resolvers.js

@@ -1,52 +1,146 @@
 /**
  * @packageDocumentation
- * Shared resolver instances used across the squawk MCP tool modules. Each
- * resolver is constructed once at module load time so the bundled FAA data
- * snapshots are decoded and indexed exactly once per server process.
+ * Shared resolver accessors used across the squawk MCP tool modules. Every
+ * bundled FAA snapshot loads on demand: the first accessor call dynamically
+ * imports its data package, decompresses and indexes the snapshot, and caches
+ * the result for the life of the process. A session that only asks about
+ * airports never decompresses the CIFP procedure snapshot, and a session that
+ * asks nothing pays nothing beyond process start.
  *
- * The ICAO registry is the only resolver that loads lazily, and its data
+ * Each accessor memoizes the in-flight load rather than the finished
+ * resolver, so concurrent tool calls needing the same dataset share one
+ * import and one index build instead of racing to build two.
+ *
+ * The ICAO registry follows the same shape with one extra wrinkle: its data
  * package (`@squawk/icao-registry-data`) is declared as an optional peer
- * dependency rather than a required dep. The registry is built on the first
- * {@link getIcaoRegistry} call (decompressing ~40 MB on first access) and
- * cached for subsequent calls. When the peer is not installed, the import
+ * dependency rather than a required dep, so a failed import is an expected
+ * outcome rather than a broken install. When the peer is absent the import
  * throws `ERR_MODULE_NOT_FOUND` and {@link getIcaoRegistry} surfaces a
  * {@link MissingDataPackageError} for the tool handler to format.
  */
-import { usBundledAirports } from '@squawk/airport-data';
 import { createAirportResolver } from '@squawk/airports';
 import { createAirspaceResolver } from '@squawk/airspace';
-import { usBundledAirspace } from '@squawk/airspace-data';
-import { usBundledAirways } from '@squawk/airway-data';
 import { createAirwayResolver } from '@squawk/airways';
-import { usBundledFixes } from '@squawk/fix-data';
 import { createFixResolver } from '@squawk/fixes';
 import { createIcaoRegistry } from '@squawk/icao-registry';
-import { usBundledNavaids } from '@squawk/navaid-data';
 import { createNavaidResolver } from '@squawk/navaids';
-import { usBundledProcedures } from '@squawk/procedure-data';
 import { createProcedureResolver } from '@squawk/procedures';
-/** Eagerly-built airport resolver backed by the US NASR snapshot. */
-export const airportResolver = createAirportResolver({
-    data: usBundledAirports.records,
-});
-/** Eagerly-built airspace resolver backed by the US NASR airspace GeoJSON snapshot. */
-export const airspaceResolver = createAirspaceResolver({
-    data: usBundledAirspace,
-});
-/** Eagerly-built airway resolver backed by the US NASR snapshot. */
-export const airwayResolver = createAirwayResolver({
-    data: usBundledAirways.records,
-});
-/** Eagerly-built fix resolver backed by the US NASR snapshot. */
-export const fixResolver = createFixResolver({ data: usBundledFixes.records });
-/** Eagerly-built navaid resolver backed by the US NASR snapshot. */
-export const navaidResolver = createNavaidResolver({
-    data: usBundledNavaids.records,
-});
-/** Eagerly-built procedure resolver backed by the US NASR snapshot. */
-export const procedureResolver = createProcedureResolver({
-    data: usBundledProcedures.records,
-});
+/**
+ * Builds a {@link LazyDataset} around a data package's dynamic import.
+ *
+ * The in-flight promise is what gets memoized, not the finished resolver, so
+ * two tool calls arriving before the first load settles share a single import
+ * and a single index build. A rejected load clears the memo so a later call
+ * retries rather than inheriting a permanently poisoned cache.
+ *
+ * @typeParam TDataset - Dataset object exported by the data package.
+ * @typeParam TResolver - Resolver type built over the dataset records.
+ * @param importDataset - Dynamic import resolving to the bundled dataset.
+ * @param buildResolver - Builds the resolver from the imported dataset.
+ * @returns Accessors over the lazily-loaded dataset.
+ */
+function createLazyDataset(importDataset, buildResolver) {
+    let loaded;
+    let pending;
+    return {
+        getResolver: () => {
+            if (loaded !== undefined) {
+                return Promise.resolve(loaded);
+            }
+            pending ??= importDataset().then((dataset) => {
+                loaded = buildResolver(dataset);
+                return loaded;
+            }, (err) => {
+                pending = undefined;
+                throw err;
+            });
+            return pending;
+        },
+        isLoaded: () => loaded !== undefined,
+    };
+}
+/** Lazily-loaded airport dataset backed by the US NASR snapshot. */
+const airportDataset = createLazyDataset(async () => (await import('@squawk/airport-data')).usBundledAirports, (dataset) => createAirportResolver({ data: dataset.records }));
+/** Lazily-loaded airspace dataset backed by the US NASR airspace GeoJSON snapshot. */
+const airspaceDataset = createLazyDataset(async () => (await import('@squawk/airspace-data')).usBundledAirspace, (dataset) => createAirspaceResolver({ data: dataset }));
+/** Lazily-loaded airway dataset backed by the US NASR snapshot. */
+const airwayDataset = createLazyDataset(async () => (await import('@squawk/airway-data')).usBundledAirways, (dataset) => createAirwayResolver({ data: dataset.records }));
+/** Lazily-loaded fix dataset backed by the US NASR snapshot. */
+const fixDataset = createLazyDataset(async () => (await import('@squawk/fix-data')).usBundledFixes, (dataset) => createFixResolver({ data: dataset.records }));
+/** Lazily-loaded navaid dataset backed by the US NASR snapshot. */
+const navaidDataset = createLazyDataset(async () => (await import('@squawk/navaid-data')).usBundledNavaids, (dataset) => createNavaidResolver({ data: dataset.records }));
+/** Lazily-loaded procedure dataset backed by the FAA CIFP snapshot. */
+const procedureDataset = createLazyDataset(async () => (await import('@squawk/procedure-data')).usBundledProcedures, (dataset) => createProcedureResolver({ data: dataset.records }));
+/**
+ * Returns the shared airport resolver, importing and indexing the bundled US
+ * NASR airport snapshot on the first call.
+ *
+ * @returns The shared airport resolver.
+ */
+export function getAirportResolver() {
+    return airportDataset.getResolver();
+}
+/**
+ * Returns the shared airspace resolver, importing and indexing the bundled US
+ * NASR airspace GeoJSON snapshot on the first call.
+ *
+ * @returns The shared airspace resolver.
+ */
+export function getAirspaceResolver() {
+    return airspaceDataset.getResolver();
+}
+/**
+ * Returns the shared airway resolver, importing and indexing the bundled US
+ * NASR airway snapshot on the first call.
+ *
+ * @returns The shared airway resolver.
+ */
+export function getAirwayResolver() {
+    return airwayDataset.getResolver();
+}
+/**
+ * Returns the shared fix resolver, importing and indexing the bundled US NASR
+ * fix snapshot on the first call.
+ *
+ * @returns The shared fix resolver.
+ */
+export function getFixResolver() {
+    return fixDataset.getResolver();
+}
+/**
+ * Returns the shared navaid resolver, importing and indexing the bundled US
+ * NASR navaid snapshot on the first call.
+ *
+ * @returns The shared navaid resolver.
+ */
+export function getNavaidResolver() {
+    return navaidDataset.getResolver();
+}
+/**
+ * Returns the shared procedure resolver, importing and indexing the bundled
+ * FAA CIFP procedure snapshot on the first call.
+ *
+ * @returns The shared procedure resolver.
+ */
+export function getProcedureResolver() {
+    return procedureDataset.getResolver();
+}
+/**
+ * Reports which required bundled snapshots are currently in memory, without
+ * loading any of them.
+ *
+ * @returns Per-dataset load state.
+ */
+export function getBundledDatasetLoadState() {
+    return {
+        airports: airportDataset.isLoaded(),
+        airspace: airspaceDataset.isLoaded(),
+        airways: airwayDataset.isLoaded(),
+        fixes: fixDataset.isLoaded(),
+        navaids: navaidDataset.isLoaded(),
+        procedures: procedureDataset.isLoaded(),
+    };
+}
 /**
  * Error thrown when a tool tries to load an optional data package peer that
  * has not been installed alongside `@squawk/mcp`. Tool handlers catch this
@@ -77,6 +171,11 @@ export class MissingDataPackageError extends Error {
 }
 /** Cached ICAO registry instance, populated on the first {@link getIcaoRegistry} call. */
 let icaoRegistryInstance;
+/**
+ * In-flight registry load, memoized so concurrent lookups share one import
+ * and one index build. Cleared when the load rejects so a later call retries.
+ */
+let icaoRegistryPending;
 /**
  * Cached metadata captured the first time the registry is loaded. Held
  * separately from the registry instance so {@link getIcaoRegistryMetadata}
@@ -111,17 +210,44 @@ let icaoRegistryDataLoader = defaultIcaoRegistryDataLoader;
 function isModuleNotFoundError(err) {
     return err instanceof Error && 'code' in err && err.code === 'ERR_MODULE_NOT_FOUND';
 }
+/**
+ * Imports the optional registry peer and builds the registry, populating the
+ * module-level caches. Split out of {@link getIcaoRegistry} so the memoized
+ * in-flight promise has a single body behind it.
+ *
+ * @returns The newly built registry instance.
+ * @throws {MissingDataPackageError} when the peer is not installed.
+ */
+async function loadIcaoRegistry() {
+    let registryDataModule;
+    try {
+        registryDataModule = await icaoRegistryDataLoader();
+    }
+    catch (err) {
+        icaoRegistryPending = undefined;
+        if (isModuleNotFoundError(err)) {
+            icaoRegistryMissing = true;
+            throw new MissingDataPackageError('icao-registry', '@squawk/icao-registry-data');
+        }
+        throw err;
+    }
+    const { usBundledRegistry } = registryDataModule;
+    icaoRegistryInstance = createIcaoRegistry({ data: usBundledRegistry.records });
+    icaoRegistryMetadata = {
+        generatedAt: usBundledRegistry.properties.generatedAt,
+        recordCount: usBundledRegistry.properties.recordCount,
+    };
+    return icaoRegistryInstance;
+}
 /**
  * Returns the shared {@link IcaoRegistry} instance, decompressing and indexing
  * the bundled FAA aircraft registration snapshot on the first call. Subsequent
  * calls reuse the cached instance.
  *
- * The registry is initialized lazily because the underlying data package is
- * the largest snapshot in the suite (roughly 40 MB raw) and is declared as an
- * optional peer dependency rather than a required dep. Sessions that never
- * look up an aircraft by ICAO hex avoid the cost entirely, and consumers who
- * never install the peer see only the structured missing-package error
- * surfaced by the tool handler.
+ * The registry's data package is the largest snapshot in the suite (roughly
+ * 40 MB raw) and is declared as an optional peer dependency rather than a
+ * required dep, so consumers who never install the peer see only the
+ * structured missing-package error surfaced by the tool handler.
  *
  * @returns The shared registry instance.
  * @throws {MissingDataPackageError} when `@squawk/icao-registry-data` is not
@@ -131,40 +257,26 @@ export async function getIcaoRegistry() {
     if (icaoRegistryMissing) {
         throw new MissingDataPackageError('icao-registry', '@squawk/icao-registry-data');
     }
-    if (icaoRegistryInstance === undefined) {
-        let registryDataModule;
-        try {
-            registryDataModule = await icaoRegistryDataLoader();
-        }
-        catch (err) {
-            if (isModuleNotFoundError(err)) {
-                icaoRegistryMissing = true;
-                throw new MissingDataPackageError('icao-registry', '@squawk/icao-registry-data');
-            }
-            throw err;
-        }
-        const { usBundledRegistry } = registryDataModule;
-        icaoRegistryInstance = createIcaoRegistry({ data: usBundledRegistry.records });
-        icaoRegistryMetadata = {
-            generatedAt: usBundledRegistry.properties.generatedAt,
-            recordCount: usBundledRegistry.properties.recordCount,
-        };
+    if (icaoRegistryInstance !== undefined) {
+        return icaoRegistryInstance;
     }
-    return icaoRegistryInstance;
+    icaoRegistryPending ??= loadIcaoRegistry();
+    return icaoRegistryPending;
 }
 /**
  * @internal
  *
  * Test-only seam for swapping the optional data package loader. Production
  * code must not call this. Pass `undefined` to restore the default loader
- * and clear all cached state (instance, metadata, and the missing-peer
- * sticky flag) so subsequent tests start from a clean slate.
+ * and clear all cached state (instance, in-flight load, metadata, and the
+ * missing-peer sticky flag) so subsequent tests start from a clean slate.
  *
  * @param loader - Replacement loader, or `undefined` to reset.
  */
 export function __setIcaoRegistryDataLoaderForTest(loader) {
     icaoRegistryDataLoader = loader ?? defaultIcaoRegistryDataLoader;
     icaoRegistryInstance = undefined;
+    icaoRegistryPending = undefined;
     icaoRegistryMetadata = undefined;
     icaoRegistryMissing = false;
 }

package/dist/tools/airports.d.ts

@@ -1,14 +1,16 @@
 /**
  * @packageDocumentation
  * MCP tool module wrapping `@squawk/airports` airport lookup methods, backed
- * by the US NASR snapshot in `@squawk/airport-data`. The dataset is loaded
- * and indexed eagerly when the shared {@link airportResolver} is imported.
+ * by the US NASR snapshot in `@squawk/airport-data`. The dataset is imported
+ * and indexed by the first handler to call {@link getAirportResolver}, so a
+ * session that never asks about an airport never pays for the snapshot.
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 /**
  * Registers airport lookup tools (by FAA ID, by ICAO code, nearest, text
- * search) on the given MCP server. Tools share the {@link airportResolver}
- * singleton built at module load time from the bundled US NASR dataset.
+ * search) on the given MCP server. Tools share the resolver singleton from
+ * {@link getAirportResolver}, which builds the bundled US NASR dataset on
+ * the first invocation and reuses it thereafter.
  *
  * @param server - The MCP server instance to register tools on.
  */

package/dist/tools/airports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"airports.d.ts","sourceRoot":"","sources":["../../src/tools/airports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkBzE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2J5D"}
+{"version":3,"file":"airports.d.ts","sourceRoot":"","sources":["../../src/tools/airports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkBzE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6J5D"}