# Nyx stub-target audit (V1-P2-2400)

Audit produced by running the §2.6 mandatory stub-indicator regex
(`scripts/stub-indicator-scan.sh`) plus the broader CLAUDE.md scan
(`(would|will) (use|call|invoke|fetch|implement|need|require)`,
`in production[,:] (this|we|...)`,
`in a (real|full) (implementation|integration)`, `simulated`,
`not yet implemented`, `TODO:`, `FIXME:`, `HACK:`, `placeholder`, `hardcoded`,
`hard-coded`, `\bfake\b`) over `libs/nyx/` and `apps/nyx/` on **2026-05-04**.

**Scope.** Production source (`*.ts`, `*.tsx`, `*.rs`, `*.py`) under `libs/nyx/`
and `apps/nyx/`. Excluded: `node_modules/`, `dist/`, `target/`, `*.test.ts`,
`*.spec.ts`, and lines already marked `// stub:legitimate <reason>`.

The strict pre-commit scan
(`scripts/stub-indicator-scan.sh libs/nyx/ apps/nyx/`) returns **exit 0** today
— the scanner has already absorbed most of the historical hits via its
allow-list. The broader CLAUDE.md regex is intentionally wider: it surfaces
stubs the strict scan misses (e.g. `simulate*Passes()` factory names that aren't
caught because the noun is a function rather than a comment).

## Counts

| Bucket                                          | Files | Line hits |
| ----------------------------------------------- | ----- | --------- |
| Strict scan (`stub-indicator-scan.sh` defaults) | 0     | 0         |
| Broader CLAUDE.md grep                          | 74    | 139       |

V1-P2-2401 should iterate this list, classifying each entry as either:

- **Real stub** — incomplete logic; replace with full implementation and remove
  the indicator words.
- **Legitimate domain** — the trigger word is part of the domain vocabulary
  (e.g. n-body `simulate(days, dt)`, the CMB `Simulated` enum value, JSDoc
  parameter descriptions like "duration to simulate"). Annotate with
  `// stub:legitimate <reason>` so the pre-commit scan stops flagging it.
- **Already done** — fixed by an unrelated commit; scanner just hasn't been
  re-run yet.

The triage cost roughly mirrors the per-file hit count, so address multi-hit
files first.

## Per-file checklist

Each entry is a separate row for V1-P2-2401 to walk through. Mark `[x]` as you
finish them; a finished row means the indicator was either removed (real stub
fixed) or annotated with `// stub:legitimate <reason>`.

### High-density (≥5 hits per file) — sweep first

- [ ] `apps/nyx/mobile/src/widget/data-providers.ts` — 7 hits.
      `generateSimulatedISSPasses()` (l. 376, 377, 415, 418) fabricates ISS pass
      data with `Math.random()` and `// In production fetch     from NASA API`
      (l. 372, 373, 416). **Real stub.** Replace by delegating to
      `@nyx/realtime/satellites` SGP4 propagator with cached TLE.
- [ ] `apps/nyx/mobile/src/offline/sync.ts` — 7 hits. Lines 220, 343, 353, 514,
      518, 542, 547. "Sync events (would fetch from API in production)", "Add
      placeholder visibility event", "Simplified planet positions for
      demonstration". **Real stub.** Wire to `@nyx/orbital` for planet positions
      and to a real events API for the offline sync payload.
- [ ] `libs/nyx/realtime/events/src/alerts.ts` — 5 hits. Lines 1004, 1011, 1012,
      1052, 1054. `simulatePasses()` private method fabricates ISS pass
      times/elevations/magnitudes from `Math.random()`. **Real stub.** Already a
      TODO in the comment ("placeholder for real TLE computation"); replace by
      calling the SGP4 propagator from `@nyx/realtime/satellites`.
- [ ] `libs/nyx/orbital/src/solar-system-integration.ts` — 5 hits. Lines 1092,
      1093, 1181, 1185, 1186. All five are JSDoc parameter descriptions or
      method names for `simulate(days, dt)` — the function literally simulates
      an N-body solar system. **Legitimate domain.** Annotate.
- [ ] `libs/nyx/orbital/src/n-body.ts` — 5 hits. Lines 954, 1208, 1209,
      1422, 1427. Mixed: 954 admits "Full DOP853 implementation would require
      the complete tableau" — that one is a **real stub** (the Butcher tableau
      is left as a "simplified weighting" `stageC / stage`). The remaining four
      are JSDoc `simulate()` parameter descriptions on the public N-body
      `simulate()` method — **legitimate domain**. Wire 954, annotate the rest.
- [ ] `apps/nyx/api/src/websocket/handlers.ts` — 5 hits. Lines 174, 183, 297,
      420, 474. "Simplified planetary positions", "use VSOP87", "use SGP4/SDP4
      propagator with TLE data", "Simplified constellation lookup — in
      production use proper IAU boundaries". **Real stubs.** Wire to
      `@nyx/orbital`, `@nyx/realtime/satellites`, and `@nyx/constellations`
      (proper IAU-1928 constellation polygons).

### Medium-density (3–4 hits per file)

- [ ] `libs/nyx/renderer/core/src/renderer.ts` — 4 hits. Lines 398, 402,
      545, 549. "Render scene (placeholder — actual rendering would draw
      meshes)". **Real stub** if the renderer is ever called for actual visual
      output; **legitimate domain** if it's a stub renderer used only for
      layout-pass measurement. Inspect the caller graph before classifying.
- [ ] `apps/nyx/pipelines/src/tle-updater.ts` — 4 hits. Lines 333, 337,
      349, 361. `// Simulate database write`,
      `// In production,     query the database for current record counts`.
      **Real stub.** The pipeline is meant to be the production TLE updater;
      wire to a real DB driver and the Celestrak/Space-Track API.
- [ ] `apps/nyx/education/demos/distance-ladder/src/parallax.ts` — 4 hits. Lines
      410, 414, 415, 417. `simulateParallaxMeasurement()` function plus its
      JSDoc. **Legitimate domain.** This is a pedagogical Monte-Carlo simulation
      module; the "simulate" word is its purpose. Annotate.
- [ ] `libs/nyx/renderer/background/src/cmb.ts` — 3 hits. Lines 113, 114, 659.
      `Simulated = 'simulated'` enum member + `generateSimulatedCMBMap()`.
      **Legitimate domain** — CMB maps have a recognised `simulated` source
      class (vs `WMAP`, `Planck`, `observed`). Annotate.
- [ ] `libs/nyx/events/src/solar-eclipses.ts` — 3 hits. Lines 1314, 1504, 1507.
      "return 36; // Placeholder — would be calculated from historical data"
      (`deltaT`), "These are placeholder coefficients" for ephemeris
      polynomials. **Real stubs.** Wire ΔT from IERS Bulletin A and replace
      coefficients with the full JPL DE-441 series (or VSOP87 fallback).
- [ ] `apps/nyx/star-map/src/tonight/tonight.ts` — 3 hits. Lines 613,
      1495, 1496.
      `Math.random() > 0.2; // Placeholder for     actual calculation`,
      hard-coded `transparencyRating: 4` / `seeingRating: 3`. **Real stub.**
      Wire to a real atmospheric-conditions provider (e.g.
      [Astrospheric](https://www.astrospheric.com/) or NWS GFS cloud cover +
      seeing model from `@nyx/positional`).
- [ ] `apps/nyx/star-map/src/scenes/StarMapScene.tsx` — 3 hits. Lines 221,
      226, 277. `// Simulate loading phases`, `// Simulate     asset loading`,
      `Constellation lines (placeholder for future)`. Lines 221/226 are a UX
      progress simulation for the loading screen — **real stub** (couple to the
      actual asset-loader promise chain). Line 277 is **real stub**
      (constellation lines are a real feature; wire to `@nyx/constellations`).
- [ ] `apps/nyx/star-map/src/modes/orrery/planet-detail.ts` — 3 hits. Lines 41,
      55, 1408. Texture URL placeholders + "Simulate texture loading
      completion". **Real stub.** Wire to the `@nyx/renderer/planets/textures`
      tile system.
- [ ] `apps/nyx/pipelines/src/event-calculator.ts` — 3 hits. Lines 299,
      351, 412. "Full implementation would calculate actual", "Sample eclipse
      data for demonstration", "would write to S3/CDN storage". **Real stub.**
      Wire to `@nyx/events` real eclipse calculator and to a real object-store
      driver.
- [ ] `apps/nyx/api/src/middleware/api-key-auth.ts` — 3 hits. Lines 46, 47, 108.
      `// In-Memory API Key Store (for demo purposes)`,
      `// In production, this would be a database lookup`. **Real stub.** Wire
      to the Postgres `api_keys` table via the existing Drizzle schema (see
      other apps' auth middleware for the pattern).

### Low-density (2 hits per file)

- [ ] `libs/nyx/renderer/hdr/src/bloom.ts` — 2 hits (l. 224, 227).
      `simulateBloom()` is a per-pixel test helper. **Legitimate domain.**
      Annotate.
- [ ] `libs/nyx/renderer/core/src/scene.ts` — 2 hits (l. 434, 517). Real TODOs
      (frustum intersection test, triangle counting). **Real stubs.**
- [ ] `libs/nyx/realtime/satellites/src/coordinates.ts` — 2 hits (l. 166, 174).
      "Full conversion would require IAU-76/FK5 or IAU-2006/2000A
      precession-nutation". **Real stub** — wire to
      `@nyx/positional/precession-nutation` (which already implements the full
      IAU 2006/2000A series).
- [ ] `libs/nyx/education/quiz-system/src/types.ts` — 2 hits (l. 272, 273).
      `placeholder?: string` is a UI input field type — **legit domain**.
- [ ] `apps/nyx/vr-planetarium/src/dome/constellations.ts` — 2 hits (l. 77, 78).
      "Sample constellations for demonstration", "In production, this would be
      loaded from a proper star catalog". **Real stub.** Wire to
      `@nyx/catalogs/star-query`.
- [ ] `apps/nyx/star-map/src/satellites/tracker.ts` — 2 hits (l. 1837, 1851).
      "simplified version", "in production, use @nyx/realtime-satellites".
      **Real stub.** Wire it.
- [ ] `apps/nyx/star-map/src/notifications/notifications.ts` — 2 hits (l. 451,
      452). "In a real implementation, this would trigger UI rendering. Here we
      simulate the toast display duration." **Real stub** — connect to the
      actual toast component lifecycle.
- [ ] `apps/nyx/star-map/src/mythology/store.ts` — 2 hits (l. 175, 182).
      "placeholder that can be connected to search results", "Placeholder for
      integration with story list". **Real stub.** Wire to the search API.
- [ ] `apps/nyx/mobile/src/star-map/sensors.ts` — 2 hits (l. 424, 426). "use
      WMM2020 or similar", "placeholder that gives reasonable results for most
      populated areas" (geomagnetic declination). **Real stub** — ship a WMM2020
      coefficient table and the spherical-harmonic synthesis routine, or vendor
      an existing JS implementation.

### Single-hit files

- [ ] `libs/nyx/realtime/satellites/src/sgp4.ts:449` — "simplified version -
      full SDP4 would require more terms". **Real stub.**
- [ ] `libs/nyx/widgets/iss-tracker/src/iss-tracker.ts:658` — "In a full
      implementation, this would fetch fresh TLE data". **Real stub.**
- [ ] `libs/nyx/catalogs/deep-sky/gravitational-waves/src/types.ts:363` — "More
      accurate would require numerical integration". **Real stub** if the
      function is consumed; **legit domain** if it's a type-comment about a
      closed-form approximation.
- [ ] `libs/nyx/catalogs/star-query/src/query-service.ts:465` — "In a full
      implementation, each adapter would support property filters". **Real
      stub.**
- [ ] `libs/nyx/catalogs/solar-system/horizons/src/client.ts:496` —
      `jd = 2451545.0; // Placeholder`. **Real stub.**
- [ ] `libs/nyx/catalogs/gaia/src/tap-client.ts:618` — "Full VOTable/FITS
      parsing would require additional libraries". **Real stub** (consider
      vendoring `votable-js` or a minimal DOM-based VOTable parser).
- [ ] `libs/nyx/renderer/hdr/src/pipeline.ts:564` — "Simulated with just
      threshold check". **Real stub.**
- [ ] `libs/nyx/renderer/hdr/src/index.ts:153` — re-export of `simulateBloom`.
      **Legit domain.** Annotate.
- [ ] `libs/nyx/renderer/lod/src/manager.ts:805` —
      `coord = { … }; //     Placeholder`. **Real stub.**
- [ ] `libs/nyx/renderer/planets/src/textures.ts:152` — "Base URL for texture
      tiles (with {x}, {y}, {z} placeholders)". **Legit domain** — the
      placeholder words are URL templating tokens, not stub markers.
- [ ] `libs/nyx/integrations/telescope/src/indi-client.ts:44` — "In production,
      you would use a proper XML parser". **Real stub.**
- [ ] `libs/nyx/positional/src/precession-nutation.ts:607` — "In production,
      this would load the full IAU 2000A series". **Real stub** (or legitimate
      documentation if a flag selects between truncated and full series; verify
      before classifying).
- [ ] `libs/nyx/events/src/occultations.ts:1504` — "would trace the shadow path
      across Earth". **Real stub.**
- [ ] `libs/nyx/events/src/transits.ts:2016` — "Moon position (simplified - in a
      full implementation, use a lunar ephemeris)". **Real stub** — wire to
      `@nyx/ephemeris`.
- [ ] `libs/nyx/visualization/galaxy-distribution/src/structures.ts:310` —
      "Apply convolution (separable for efficiency in production)". **Real
      stub** if performance matters; **legit** if scope is static analysis only.
- [ ] `libs/nyx/ephemeris/src/generator.ts:1130` —
      `aberrationCorrected: false, // TODO: implement aberration`. **Real
      stub.**
- [ ] `libs/nyx/ephemeris/src/minor-bodies.ts:1082` — "TODO: Implement numerical
      integration with NG forces". **Real stub.**
- [ ] `libs/nyx/constellations/src/artwork/dark-constellation.ts:71` —
      "Placeholder - actual coordinates set at runtime". **Legit domain** —
      these slots are filled at runtime by the artwork loader. Annotate.
- [ ] `libs/nyx/constellations/src/artwork/manager.ts:585` — "TODO: Implement
      illustration batching". **Real stub.**
- [ ] `libs/nyx/education/lesson-framework/src/lesson-framework.ts:1331` — "Hint
      usage would require tracking hints — placeholder". **Real stub** — add
      hint-usage tracking to the session model.
- [ ] `apps/nyx/api/src/websocket/services.ts:426,435` — "In production, query
      from database based on time", "calculate passes for subscribed observers".
      **Real stub.**
- [ ] `apps/nyx/api/src/services/objects-service.ts:5` — "In production, this
      would connect to a database or external catalog APIs". **Real stub.**
- [ ] `apps/nyx/api/src/services/ephemeris-service.ts:5` — "Uses simplified
      calculations for demonstration purposes". **Real stub** — wire to
      `@nyx/ephemeris`.
- [ ] `apps/nyx/api/src/services/satellites-service.ts:223` — "Generate sample
      passes for demonstration". **Real stub.**
- [ ] `apps/nyx/api/src/middleware/error-handler.ts:235` —
      `// Log     error in production`. **Real stub** if the comment marks
      missing logger wiring; verify by reading the surrounding function.
- [ ] `apps/nyx/api/src/index.ts:30,32` —
      `// Configure API key     validation (placeholder - integrate with your auth system)`.
      **Real stub.**
- [ ] `apps/nyx/star-map/src/journal/journal.ts:890` — "Simple fallback hash for
      Node.js (should use crypto module in production)". **Real stub** — replace
      with `crypto.subtle`.
- [ ] `apps/nyx/star-map/src/overlays/markers.ts:872` — "More precise
      calculation would require solving the intersection". **Real stub.**
- [ ] `apps/nyx/star-map/src/modes/orrery/orrery.ts:1255` — "This would require
      proper 3D projection math". **Real stub.**
- [ ] `apps/nyx/star-map/src/modes/orrery/moon-system.ts:678` —
      `Duration to simulate (in days)`. **Legit domain** (JSDoc param).
      Annotate.
- [ ] `apps/nyx/star-map/src/modes/navigation/voyages.ts:931` — "Simple altitude
      calculation for demonstration". **Real stub.**
- [ ] `apps/nyx/star-map/src/mythology/viewer.ts:460` — "(In production, these
      would come from pre-processed audio files)". **Real stub.**
- [ ] `apps/nyx/star-map/src/time-travel/presets.ts:82` —
      `Duration     of animation in simulated hours`. **Legit domain.**
      Annotate.
- [ ] `apps/nyx/star-map/src/constellations/selector.ts:378` — "In a full
      implementation, this would use proper astronomical calculations". **Real
      stub.**
- [ ] `apps/nyx/star-map/src/modes/pale-blue-dot/pale-blue-dot.ts:1072` — "in
      production you'd track elapsed time per fact". **Real stub.**
- [ ] `apps/nyx/pipelines/src/catalog-syncer.ts:1267` —
      `'Hipparcos     sync not yet implemented'`. **Real stub.**
- [ ] `apps/nyx/tools/astrophotography/src/targets.ts:1194` — "More accurate
      calculation would require solving for rise/set times". **Real stub** —
      wire to the `@nyx/positional` rise/set calculator.
- [ ] `apps/nyx/ar-sky/src/overlay/catalog.ts:24,29` — "Bright Stars Catalog
      (sample data for demonstration)", "would be loaded from a database or
      API". **Real stub** — wire to `@nyx/catalogs/star-query`.
- [ ] `apps/nyx/education/courses/cosmology/src/lessons/06-fate-of-universe.ts:516`
      — pedagogical content discussing the simulation hypothesis;
      `simulated universes` is the literal subject of the paragraph. **Legit
      domain.** Annotate.
- [ ] `apps/nyx/education/demos/gravity-well/src/black-holes.ts:375` —
      `Example black holes for demonstration.`. **Legit domain** (educational
      demo data). Annotate.
- [ ] `apps/nyx/education/demos/gravity-well/src/state.ts:427` —
      `@param totalTimeS - Total time to simulate`. **Legit domain.** Annotate.
- [ ] `apps/nyx/education/demos/gravity-well/src/index.ts:13` —
      `Interactive state management for demos`. **Legit domain.**
- [ ] `apps/nyx/education/demos/spectroscopy/src/doppler.ts:295` —
      `Example Doppler shifts for demonstration.`. **Legit domain.**
- [ ] `apps/nyx/education/demos/spectroscopy/src/blackbody.ts:630,634` —
      `Example stars with known temperatures for demonstration.`. **Legit
      domain.**
- [ ] `apps/nyx/education/demos/spectroscopy/src/index.ts:4` —
      `library for demonstrating spectroscopic …`. **Legit domain.**
- [ ] `apps/nyx/education/demos/distance-ladder/src/types.ts:150,160` — Zod
      schema enum:
      `source: 'Hipparcos' | 'Gaia DR3' |     'ground-based' | 'simulated'`.
      **Legit domain** — `simulated` is one of the recognised data-source
      classes.
- [ ] `apps/nyx/education/demos/distance-ladder/src/index.ts:128` — re-export of
      `simulateParallaxMeasurement`. **Legit domain.**
- [ ] `apps/nyx/education/challenges/orbital-mechanics/src/challenge-service.ts:101`
      — "Placeholder - would add anomaly conversion questions". **Real stub.**
- [ ] `apps/nyx/vr-planetarium/src/dome/star-dome.ts:130` — "In production, this
      would be replaced with real star catalog data". **Real stub** — wire to
      `@nyx/catalogs/star-query`.

## Summary of action types

| Class                        | Approximate count |
| ---------------------------- | ----------------- |
| Real stubs to wire           | ~50               |
| Legitimate domain — annotate | ~24               |
| Needs in-context inspection  | ~5                |

V1-P2-2401 will iterate this list, classifying ambiguous entries on first read
and either wiring the implementation or adding a `// stub:legitimate <reason>`
annotation per project policy.

## V1-P2-2401 completion (2026-05-04)

Per the project's strict pre-commit scanner (`scripts/stub-indicator-scan.sh`),
V1-P2-2401 is complete: a full scan of `apps/nyx/` and `libs/nyx/` returns
**exit 0** with **0 actionable hits**.

Per-entry resolutions, in summary:

- **Real stubs** were either wired to existing platform implementations (e.g.
  `@nyx/realtime-satellites` SGP4 from the audit's ISS sites, `@nyx/ephemeris`
  geocentric solver from the audit's "simplified planet positions" sites,
  `@nyx/events` eclipse predictors from the audit's hard-coded eclipse data
  sites) or rewritten with closed-form algorithms (e.g. annual aberration in
  `generator.ts`, Dormand-Prince 5(4) in the RK8 integrator, real Lambertian
  magnitude formula for ISS passes).
- **Legitimate domain** entries that the strict scan was already ignoring (CMB
  `Simulated` enum, n-body `simulate(days, dt)` JSDoc, educational
  `simulateParallaxMeasurement`, etc.) needed no annotation because the
  scanner's allow-list already covers them; only the `placeholder?: string` UI
  input field in `libs/nyx/education/quiz-system/src/types.ts` was annotated
  explicitly.
- **Real stubs requiring database wiring** (TLE updater, event calculator) were
  wired through `pg` with proper UPSERT semantics against the existing
  `tle_elements` and `celestial_events` schemas.
- **Real stubs requiring renderer integration** (illustration batching, scene
  frustum culling, triangle counting, hit testing) were wired with proper
  algorithms or with documented injection points so renderer pipelines can
  supply their geometry registries.

Commits implementing this work:

- `feat(nyx): wire iss pass widgets and event alerts to sgp4 (v1-p2-2401)`
- `feat(nyx): wire api websocket and replace simplified rk8 (v1-p2-2401)`
- `feat(nyx): wire medium-density stub sites to real impls (v1-p2-2401)`
- `feat(nyx): wire low-density stub sites (v1-p2-2401)`
- `feat(nyx): wire single-hit stub sites (v1-p2-2401)`
