ballistics-engine 0.43.0 → 0.45.0

package/README.md

@@ -7,7 +7,7 @@ A high-performance ballistics trajectory calculation engine with comprehensive p
 ## Features
 
 - **Full 3D Trajectory Integration** - Six-state ballistic modeling with adaptive RK45 and fixed-step RK4 integration methods
-- **Advanced Drag Models** - Full standard-projectile family (G1, G2, G5, G6, G7, G8, GI, GS, and the British RA4 reference function), each backed by its own real Mach-indexed table with automatic transonic corrections, plus user-supplied custom Cd(Mach) drag tables (`--drag-table`, used as-is with endpoint hold outside their measured domain, no transonic correction applied — see [CLI_USAGE.md](CLI_USAGE.md#custom-drag-tables); `bc_value` is ignored while a custom table is active), with an optional `--cd-scale <FACTOR>` whole-curve truing multiplier (Hornady AFF / AB CDF style; `1.0` = neutral, typical range 0.90-1.10; requires `--drag-table` — see [CLI_USAGE.md](CLI_USAGE.md#whole-curve-drag-scale---cd-scale)). `true-velocity`/`plan-truing`'s forward model is deliberately G1/G7 only. GL is out of scope — its only public source is velocity-domain data, which doesn't fit this engine's Mach-indexed table format.
+- **Advanced Drag Models** - Full standard-projectile family (G1, G2, G5, G6, G7, G8, GI, GS, and the British RA4 reference function), each backed by its own real Mach-indexed table with automatic transonic corrections, plus user-supplied custom Cd(Mach) drag tables (`--drag-table`, used as-is with endpoint hold outside their measured domain, no transonic correction applied — see [CLI_USAGE.md](CLI_USAGE.md#custom-drag-tables); `bc_value` is ignored while a custom table is active; over the JSON bridge the same curve rides inline as solve-json's `projectile.drag_table`, which can also fly a reference curve such as an airgun pellet law together with the BC measured against it — see [docs/SOLVE_JSON_V1.md](docs/SOLVE_JSON_V1.md#projectiledrag_table-mba-1597)), with an optional `--cd-scale <FACTOR>` whole-curve truing multiplier (Hornady AFF / AB CDF style; `1.0` = neutral, typical range 0.90-1.10; requires `--drag-table` — see [CLI_USAGE.md](CLI_USAGE.md#whole-curve-drag-scale---cd-scale)). `true-velocity`/`plan-truing`'s forward model is deliberately G1/G7 only. GL is out of scope — its only public source is velocity-domain data, which doesn't fit this engine's Mach-indexed table format.
 - **Automatic Zeroing** - Calculate sight adjustments and apply zero angles automatically; `trajectory` echoes the solved bore angle (degrees, additive across table/JSON/CSV) whenever auto-zero ran, and `zero --from-angle <DEGREES>` solves the zero RANGE(S) a previously solved/stored bore angle produces — a bore angle generally implies two zeros (the classic 25/300-yard relationship), so both are reported rather than one being silently picked — so the angle can be captured once and reused later, independent of the day it was solved — see [CLI_USAGE.md](CLI_USAGE.md#solving-range-from-a-stored-angle---from-angle)
 - **Canted-Rifle Modeling** - Model a rifle zeroed level but fired canted (`--cant <DEGREES>`, alias `--cant-angle`, on `trajectory`/`monte-carlo`); clockwise cant shifts point of impact right and low downrange for a rifle with an upward zero correction — see [CLI_USAGE.md](CLI_USAGE.md#canted-shooting)
 - **Deliberate Zero POI Offset** - Record that the rifle is deliberately zeroed off — e.g. 0.1 in high / 0.2 in left at the zero range (Kestrel ZH/ZO semantics) — and shift the whole solution by the equivalent angular bias (`--zero-poi-up`/`--zero-poi-right`, inches imperial / cm metric, on `trajectory` and every zero-solving subcommand; solve-json `shot.zero_poi_up_m`/`zero_poi_right_m`; saved-profile fields; `.a7p` zero click counts convertible via `profile import --zero-click`) — see [CLI_USAGE.md](CLI_USAGE.md#sight-geometry-and-zero-state)
@@ -26,6 +26,7 @@ A high-performance ballistics trajectory calculation engine with comprehensive p
 - **Unit Conversion** - Seamless switching between Imperial (default) and Metric units
 - **BC Segmentation** - Velocity-dependent ballistic coefficient modeling with automatic estimation
 - **Atmospheric Modeling** - Temperature, pressure, humidity, and altitude effects with ICAO standard atmosphere; also accepts a single **density altitude** reading (`trajectory --density-altitude`, feet imperial / meters metric) as a direct alternative to entering altitude/pressure/temperature separately — back-solves an ISA-equivalent atmosphere (preserving Mach/lapse-rate/segmented-atmosphere behavior, not a density-only shortcut) and supersedes `--altitude`/`--pressure`/`--pressure-type` entirely, with an explicit `--temperature` still honored for correct powder-temperature sensitivity — see [CLI_USAGE.md](CLI_USAGE.md#density-altitude-as-a-direct-input---density-altitude)
+- **Density Altitude for Apps** - The `atmosphere.density_altitude` bridge command resolves a solve-json atmosphere exactly as a solve does and reports pressure altitude, the solver's CIPM-2007 air density, and density altitude under both of its field definitions by name — `faa_rule` (NWS pressure altitude plus the FAA 120 ft/°C rule, humidity-free, the same formula as the DOPE card header) and `density_matched` (ISA altitude of equal actual density, humidity included) — refusing air that cannot exist, which is what a unit mistake looks like; see [docs/ATMOSPHERE_DENSITY_ALTITUDE.md](docs/ATMOSPHERE_DENSITY_ALTITUDE.md)
 - **Clock-Position Wind Entry** - Enter wind direction as the dominant field convention: marked clock positions (`--wind-direction 3oc`, `10h30`, or `10:30`; 12 o'clock = headwind, minutes count 0.5°) alongside plain degrees on every wind-direction flag and the WASM terminal; inside `--wind-segment` the colon-free forms apply (`10:3oc:400`) while `10:30:400` keeps its numeric SPEED:ANGLE:DIST meaning; bare numbers stay degrees everywhere — see [CLI_USAGE.md](CLI_USAGE.md#wind-direction-entry-degrees-clock-positions--mba-1367)
 - **Earth-Fixed Compass Wind Bearings** - Store wind as absolute compass bearings and let the solver re-reference them against the shot azimuth (`--wind-ref compass` + `--shot-direction` on `trajectory`/`monte-carlo`; covers the single direction, location-CSV WIND_DIR, and every `--wind-segment` angle; Monte Carlo converts before dispersion sampling; solve-json `wind.wind_reference`; WASM builder `setWindReference`/`setShotDirection`; wind FROM north on a shot due north = pure headwind, pinned) — see [CLI_USAGE.md](CLI_USAGE.md#earth-fixed-compass-bearings---wind-ref-compass--mba-1368)
 - **Wind Effects** - 3D wind calculations with altitude-dependent wind shear modeling, **downrange-segmented wind** (`--wind-segment SPEED:ANGLE:DIST[:VERTICAL]`, repeatable — model wind that varies along the path, e.g. muzzle plus downrange sensor readings), and **vertical wind** (`--wind-vertical <SPEED>` on `trajectory`/`monte-carlo`, or the segment's optional 4th field; positive = updraft, raises point of impact) — see [CLI_USAGE.md](CLI_USAGE.md#vertical-wind)

package/ballistics_engine.d.ts

@@ -18,7 +18,9 @@ export class Calculator {
     addWindSegment(speed_mph: number, direction_deg: number, until_yards: number): Calculator;
     /**
      * Calculate trajectory and return result as JavaScript object
-     * Returns: { range_yards, drop_inches, windage_inches, velocity_fps, energy_ftlb, time_sec }
+     * Returns: { range_yards, drop_inches, drift_inches, velocity_fps, energy_ftlb, time_seconds }
+     * (`drift_inches`, not `windage_inches` -- the wrong name here is what a wasm test was
+     * written against, and it failed on a field that has never existed. MBA-1535.)
      */
     calculateTrajectory(range_yards: number): any;
     /**
@@ -30,6 +32,10 @@ export class Calculator {
     /**
      * Get full trajectory table as array of points
      * Returns array of: [{ range_yards, drop_inches, windage_inches, velocity_fps, energy_ftlb, time_sec }, ...]
+     *
+     * ⚠️ DIFFERENT KEYS FROM [`Self::calculate_trajectory`], which answers `drift_inches`
+     * and `time_seconds`. The two have never agreed and the difference is load-bearing for
+     * existing embedders, so it is documented here rather than quietly unified (MBA-1535).
      */
     getFullTrajectory(): any;
     /**

package/ballistics_engine.js

@@ -39,7 +39,9 @@ export class Calculator {
     }
     /**
      * Calculate trajectory and return result as JavaScript object
-     * Returns: { range_yards, drop_inches, windage_inches, velocity_fps, energy_ftlb, time_sec }
+     * Returns: { range_yards, drop_inches, drift_inches, velocity_fps, energy_ftlb, time_seconds }
+     * (`drift_inches`, not `windage_inches` -- the wrong name here is what a wasm test was
+     * written against, and it failed on a field that has never existed. MBA-1535.)
      * @param {number} range_yards
      * @returns {any}
      */
@@ -82,6 +84,10 @@ export class Calculator {
     /**
      * Get full trajectory table as array of points
      * Returns array of: [{ range_yards, drop_inches, windage_inches, velocity_fps, energy_ftlb, time_sec }, ...]
+     *
+     * ⚠️ DIFFERENT KEYS FROM [`Self::calculate_trajectory`], which answers `drift_inches`
+     * and `time_seconds`. The two have never agreed and the difference is load-bearing for
+     * existing embedders, so it is documented here rather than quietly unified (MBA-1535).
      * @returns {any}
      */
     getFullTrajectory() {

package/package.json

@@ -5,7 +5,7 @@
     "Alex Jokela <email@tinycomputers.io>"
   ],
   "description": "High-performance ballistics trajectory engine with professional physics (WASM build)",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",