
<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

The catalog module provides an in-memory implementation of the `StarCatalogSource` contract used by `@suaveplan/stars` providers. It accepts a static array of `RawStar` records and exposes them through the same `queryCone` and `getStar` surface that production catalog adapters (Hipparcos, Tycho-2, Gaia DR3) implement, so consumers can swap real catalogs for fixtures without touching call sites.

It is the recommended source for tests, demos, offline planetariums, and bootstrap data flows where pulling a remote catalog is unnecessary or undesirable. The implementation favours predictability over scale: lookups are O(n) for cone queries and O(1) for id resolution backed by a single `Map`.

## Features

- Pure in-memory `StarCatalogSource` with no external dependencies.
- Constant-time `getStar(catalogId)` lookup via internal `Map`.
- Naive Cartesian cone filter on `(ra, dec)` for deterministic test output.
- Returns the same `RawStar` shape consumed by `createStarProvider`.
- Zero allocations on the hot path beyond the result array.

## Usage: Basic Example

```ts
import { createInMemoryCatalogSource } from "@suaveplan/stars";

const source = createInMemoryCatalogSource([
    { catalogId: "HIP-32349", ra: 101.287, dec: -16.716, apparentMagnitude: -1.46 },
]);

const sirius = await source.getStar("HIP-32349");
```

## Usage: Advanced Example

```ts
import { createInMemoryCatalogSource, createStarProvider } from "@suaveplan/stars";

const source = createInMemoryCatalogSource([
    { catalogId: "HIP-32349", ra: 101.287, dec: -16.716, apparentMagnitude: -1.46, spectralClass: "A1V", distance: 2.64 },
    { catalogId: "HIP-37279", ra: 114.825, dec: 5.225, apparentMagnitude: 0.4, spectralClass: "F5IV-V" },
]);
const provider = createStarProvider([source]);
const nearby = await provider.queryCone(101, -16, 5);
```

## API Reference

- `createInMemoryCatalogSource(stars: RawStar[]): StarCatalogSource` — builds a source whose `queryCone(ra, dec, radiusDeg)` returns every star inside the Cartesian disk of the given radius (degrees) around the centre, and whose `getStar(catalogId)` returns the matching record or `null`. Both methods are async to satisfy the interface; neither throws.

## Implementation Notes

The cone filter uses Euclidean distance on raw `(ra, dec)` pairs rather than a spherical-trig great-circle distance. This is deliberate: the source is for fixtures and small catalogs, where simplicity and determinism beat correctness near the poles or across the RA wrap. For real-sky use, layer a cosine-correction adapter or replace the source with a HEALPix-backed implementation. The internal `Map` is built once at construction; mutating the input array post-construction is not supported.