Oya Domain — Technical Specifications

Technical specifications for the Oya drone and autonomous aerial systems domain: the foundation type system, coordinate mathematics, physical constants, the error taxonomy, and the six published @oya/* packages. Every type, schema, enum value, constant, and function documented under "Implemented" exists in real source under libs/oya/. Sections marked (planned) trace to docs/proposals/OYA_DOMAIN_PROPOSAL.md and TODOS Phase 33 and are not yet implemented.

This document specifies the Oya domain at field-level precision. It begins with the technology stack and package structure, then documents @oya/core's foundation layer (types.ts, constants.ts, coordinate-transforms.ts, math-utils.ts, validation.ts, errors.ts) in full detail. It then catalogs the 95 higher-level subsystem modules in @oya/core and the five sibling readiness-evaluator packages. The (planned) section at the end describes expansion that is scoped but not yet implemented.

All 101 @oya/core modules were confirmed adversarially clean of stub markers in the V1-P2-2110 audit (docs/releases/p2/oya-stub-audit.md, 2026-05-04).

Technology Stack#

The table below describes the full technology stack for all six Oya packages. Note that @oya/core has exactly one runtime dependency — zod — keeping the library lightweight for consumers who only need the type and math layer.

@oya/core is published as @oya/core version 0.1.0, private: true, with main/types pointing at ./src/index.ts. Path mapping @oya/* → libs/oya/*/src/index.ts is registered in tsconfig.base.json.

Package Structure#

The Oya domain ships six packages under libs/oya/. There is no apps/oya/ or services/oya/.

libs/oya/
├── core/                 → @oya/core               (101 source modules)
├── flight-control/       → @oya/flight-control      (readiness evaluator)
├── mission-planning/     → @oya/mission-planning    (readiness evaluator)
├── safety/               → @oya/safety              (readiness evaluator)
├── swarm-intelligence/   → @oya/swarm-intelligence  (swarm primitives + evaluator)
└── telemetry/            → @oya/telemetry           (readiness evaluator)

@oya/core is by far the largest: 101 TypeScript source modules in libs/oya/core/src/ (excluding *.test.ts), with an 8,265-line public barrel index.ts that re-exports the named API of every module. The five sibling packages are each a single-file src/index.ts (16–31 KB) with a focused "readiness evaluator" or "swarm primitive" surface.

This specification documents the foundation layer of @oya/core (types.ts, constants.ts, coordinate-transforms.ts, math-utils.ts, validation.ts, errors.ts) at field-level depth, then catalogs the higher-level @oya/core subsystem modules and the five sibling packages, then documents the (planned) library expansion.

@oya/core — Foundation Type System (types.ts)#

libs/oya/core/src/types.ts (642 lines) is the root of the type vocabulary. Every type below has both a TypeScript type and a corresponding Zod schema. The TypeScript type is derived from the schema via z.infer<...> except where noted. Zod schemas are the single source of truth: change the schema and the static type updates automatically.

Branded ID Types#

Fleet management code routinely passes multiple ID categories — drone IDs, mission IDs, waypoint IDs, swarm IDs — through the same data structures. Without nominal typing these are all plain strings, and a copy-paste error silently passes the wrong ID. Branded types make that a compile-time error instead.

IDs are nominal branded strings. The brand helper is:

type Brand<T, B extends string> = T & { readonly __brand: B };

The four ID types are:

export type DroneId = Brand<string, 'DroneId'>;
export type SwarmId = Brand<string, 'SwarmId'>;
export type MissionId = Brand<string, 'MissionId'>;
export type WaypointId = Brand<string, 'WaypointId'>;

Each ID has a Zod schema that validates the string against a UUID v4 pattern (UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i) and is cast to z.ZodType<...> of the branded type:

• DroneIdSchema — message 'Invalid DroneId: must be a valid UUID v4'
• SwarmIdSchema — message 'Invalid SwarmId: must be a valid UUID v4'
• MissionIdSchema — message 'Invalid MissionId: must be a valid UUID v4'
• WaypointIdSchema — message 'Invalid WaypointId: must be a valid UUID v4'

The schemas reject non-UUID strings at service boundaries; the branded type prevents passing (for example) a MissionId where a DroneId is expected at compile time.

3D Math Types#

All drone navigation and sensor data is three-dimensional. These types form the mathematical substrate for every computation in Oya. Note that Position3D is geodetic (latitude/longitude/altitude), not Cartesian — this is the standard for outdoor drone operations where Earth curvature matters.

Position3D is geodetic, not Cartesian:

export const Position3DSchema = z.object({
  latitude: z.number().min(-90).max(90), // decimal degrees
  longitude: z.number().min(-180).max(180), // decimal degrees
  altitude: z.number(), // meters above MSL
});

Velocity3D — { vx, vy, vz }, each an unconstrained z.number() in m/s. Acceleration3D — { ax, ay, az }, each an unconstrained z.number() in m/s².

Orientation uses Euler angles in radians, Tait-Bryan ZYX intrinsic convention, with bounded ranges:

export const OrientationSchema = z.object({
  roll: z.number().min(-Math.PI).max(Math.PI), // [-π, π]
  pitch: z
    .number()
    .min(-Math.PI / 2)
    .max(Math.PI / 2), // [-π/2, π/2]
  yaw: z.number().min(-Math.PI).max(Math.PI), // [-π, π]
});

Quaternion — { w, x, y, z }, each z.number().min(-1).max(1), with a .refine() that enforces unit norm (|norm − 1| < 0.01); the refinement message is 'Quaternion must be a unit quaternion (norm approximately 1)'.

EulerAngles is a literal alias: EulerAnglesSchema = OrientationSchema and type EulerAngles = Orientation. It exists to emphasize the angle representation at call sites.

Coordinate Frame Types#

Drone navigation involves three distinct spatial reference frames. Each is a separate TypeScript type so that functions that require, say, a GPS coordinate cannot accidentally receive a body-frame coordinate.

Three coordinate frames are defined as distinct object types:

• GPSCoordinates — { latitude, longitude, altitude }, identical shape and bounds to Position3DSchema. WGS84 datum, altitude above MSL.
• LocalCoordinates — { north, east, down }, all z.number() meters. Local North-East-Down (NED) frame relative to an origin; down positive = below origin.
• BodyCoordinates — { forward, right, down }, all z.number() meters. Drone-body frame relative to the center of mass; forward positive = nose direction, right positive = starboard, down positive = below.

Enumerations#

All enums are TypeScript string enums (value === key string). They are consumed in Zod schemas via z.nativeEnum(...), which means Zod will reject any string not present in the enum at runtime.

FlightMode — the complete set of flight control modes, from fully manual to fully autonomous:

DroneState — the full operational lifecycle of a drone: Idle, Preflight, Armed, TakingOff, Flying, Hovering, Landing, Landed, Emergency, Disarmed.

ConnectionStatus — the state of the communication link between ground station and drone: Disconnected, Connecting, Connected, Reconnecting, Lost, Error.

AirspaceClass — ICAO airspace classification, covering all regulated categories plus special-use designations: A, B, C, D, E, G, Restricted, Prohibited, Danger, TemporaryFlightRestriction.

GimbalMode — the four standard gimbal operating modes: Free, Follow, Lock, FPV.

GeofenceBehavior — what the drone does when it approaches or crosses a geofence boundary: Warn, ReturnToHome, Land, Stop.

GeofenceType — the supported geofence shapes: Circle, Polygon.

EmergencyType — the four emergency response actions ordered from safest to most drastic: ReturnToHome, Land, Hover, MotorKill (motor kill is the last-resort option).

FlightPlanStatus — the lifecycle stages of a flight plan: Draft, Approved, Active, Completed, Cancelled, Failed.

WaypointAction — actions that can be executed when a drone reaches a waypoint: TakePhoto, StartVideo, StopVideo, SetGimbal, ChangeSpeed, ChangeAltitude, Hover, OrbitPOI.

WeatherResistance — hardware weather-resistance rating classes: None, Light, Moderate, Heavy, AllWeather.

Composite Types#

These are the structured record types that combine the primitives above into the objects passed across service boundaries and stored in the database.

BatteryState — the complete battery telemetry record:

{
  voltage: number >= 0,                          // volts
  current: number,                               // amps (negative = charging)
  percentage: number 0..100,                     // state of charge
  temperatureCelsius: number -40..85,
  cellCount: integer 1..14,
  timeRemainingSeconds: number >= 0,
  isCharging: boolean,
  cycleCount: integer >= 0,
}

Telemetry — the complete real-time snapshot from one drone. This is the canonical record for logging, dashboards, and mission replays:

{
  droneId: DroneId,                              // DroneIdSchema
  timestamp: ISO-8601 string,                    // z.string().datetime()
  position: Position3D,
  velocity: Velocity3D,
  acceleration: Acceleration3D,
  orientation: Orientation,
  batteryState: BatteryState,
  gpsCoordinates: GPSCoordinates,
  signalStrength: number -120..0,                // dBm, higher is better
  satellites: integer 0..50,
  flightMode: FlightMode,                        // z.nativeEnum
  droneState: DroneState,                        // z.nativeEnum
  connectionStatus: ConnectionStatus,            // z.nativeEnum
}

signalStrength is in dBm (range −120…0), not a 0–100 percentage. There is no separate localPosition, gpsFix, gpsHdop, or motorRpms field on Telemetry — GPS fix quality, HDOP/VDOP, and motor RPM live in the higher-level telemetry modules (@oya/telemetry, core/src/telemetry-collection.ts).

DroneCapabilities — hardware/software capability descriptor: maxSpeed (m/s), maxAltitude (m), maxFlightTime (minutes), hasCamera, hasGimbal, hasRTK, hasThermal, hasLidar, maxPayloadGrams, obstacleAvoidance (boolean), weatherResistance (WeatherResistance enum).

CameraSettings — resolution (string, e.g. "3840x2160"), fps (integer 1..240), codec (string), fov (degrees 0..360), whiteBalance (Kelvin 0..10000, 0 = auto), iso (0..102400, 0 = auto), shutterSpeed (fraction denominator, ≥0, 0 = auto), format (string).

GimbalState — pan (degrees −180..180), tilt (degrees −90..90), roll (degrees −45..45), mode (GimbalMode).

PayloadInfo — id (string), name (string), type (string, e.g. "Camera", "Sensor", "Delivery", "Sprayer"), weightGrams (≥0), isActive (boolean).

WeatherConditions — windSpeedMs (≥0), windDirection (degrees 0..360, 0 = North), temperatureCelsius (−60..60), humidity (% 0..100), pressure (hPa 870..1084), visibility (meters ≥0), precipitation (string).

GeofenceZone — id, name, type (GeofenceType), center (GPSCoordinates, optional — for circles), radius (≥0, optional — for circles), vertices (array of GPSCoordinates, min 3, optional — for polygons), minAltitude (number), maxAltitude (number), behavior (GeofenceBehavior).

WaypointActionEntry — { action: WaypointAction, params?: Record<string, unknown> }.

Waypoint — id (WaypointId), position (GPSCoordinates), speed (m/s ≥0), heading (degrees 0..360), holdTimeSeconds (≥0), actions (array of WaypointActionEntry), radius (acceptance radius in meters, ≥0).

MissionConstraints — maxAltitude, minAltitude, maxSpeed, minBatteryPercent (0..100), maxWindSpeed, allowedAirspace (array of AirspaceClass).

MissionMetadata — createdBy, createdAt (ISO-8601), updatedAt (ISO-8601), description, tags (string array).

Mission — id (MissionId), name (non-empty string), waypoints (array of Waypoint, min 1), constraints (MissionConstraints), metadata (MissionMetadata), estimatedDuration (seconds ≥0), totalDistance (meters ≥0).

FlightPlan — links a mission to a drone: id (string), missionId (MissionId), droneId (DroneId), plannedAt, estimatedStartTime, estimatedEndTime (all ISO-8601), weatherCheck ({ passed: boolean, conditions?: WeatherConditions, warnings: string[] }), airspaceCheck ({ passed: boolean, airspaceClass?: AirspaceClass, authorization?: string, warnings: string[] }), status (FlightPlanStatus).

EmergencyProcedure — type (EmergencyType), priority (integer 1..10, 1 = highest), conditions (string array of triggering conditions), altitudeLimit (meters ≥0, 0 = no limit).

@oya/core — Physical Constants (constants.ts)#

libs/oya/core/src/constants.ts (972 lines) defines physical, atmospheric, hardware, and operational constants used throughout all Oya subsystems. Having these as named constants rather than inline literals ensures algorithms agree on the same values and makes them easy to audit for regulatory compliance.

WGS84 Ellipsoid#

These are the Earth ellipsoid model parameters used by all coordinate transform algorithms. Using WGS84 ensures Oya's geodesy is consistent with GPS receivers and mapping software worldwide.

WGS84_A = 6_378_137.0 m (semi-major axis); WGS84_INVERSE_F = 298.257223563; WGS84_F = 1/WGS84_INVERSE_F; WGS84_B = WGS84_A·(1−f) (semi-minor axis); WGS84_E2 = 2f − f² (first eccentricity squared); WGS84_E = √WGS84_E2.

Physical Constants#

STANDARD_GRAVITY = 9.80665 m/s²; EARTH_MEAN_RADIUS = 6_371_008.8 m; SPEED_OF_SOUND_SEA_LEVEL = 340.29 m/s; EARTH_EQUATORIAL_RADIUS = WGS84_A; EARTH_POLAR_RADIUS = WGS84_B.

Atmospheric Model (International Standard Atmosphere)#

The ISA model provides altitude-dependent values for air density, pressure, and temperature — used by propeller thrust models, range calculations, and fuel-cell altitude compensation.

Constants: AIR_DENSITY_SEA_LEVEL = 1.225 kg/m³; STANDARD_PRESSURE_SEA_LEVEL = 101_325.0 Pa; STANDARD_TEMPERATURE_SEA_LEVEL = 288.15 K; TEMPERATURE_LAPSE_RATE = −0.0065 K/m; TROPOPAUSE_ALTITUDE = 11_000.0 m; DRY_AIR_GAS_CONSTANT = 287.058 J/(kg·K); DRY_AIR_SPECIFIC_HEAT_RATIO = 1.4; DRY_AIR_MOLAR_MASS = 0.0289644 kg/mol; UNIVERSAL_GAS_CONSTANT = 8.31446 J/(mol·K).

Three ISA model functions (valid for the troposphere, 0–11 km, clamping their input to that range):

• airDensityAtAltitude(altitudeMeters) → kg/m³, via the barometric formula ρ = ρ₀·(T/T₀)^((−g/(L·R)) − 1).
• atmosphericPressureAtAltitude(altitudeMeters) → Pa, exponent −g/(L·R).
• temperatureAtAltitude(altitudeMeters) → K, linear lapse-rate model.

Drone Class and Wind Limits#

Drone class determines the maximum wind speed at which operations are considered safe. The MAX_WIND_SPEED_BY_CLASS map provides the per-class limit for automated go/no-go decisions.

DroneClass enum: Micro (<250 g), Mini (250 g–2 kg), Small (2–25 kg), Medium (25–150 kg), Large (>150 kg). MAX_WIND_SPEED_BY_CLASS maps each class to a sustained-wind limit in m/s: Micro 5.0, Mini 10.0, Small 15.0, Medium 20.0, Large 25.0.

Regulatory and Operating Limits#

FAA_MAX_ALTITUDE_AGL_FT = 400; FAA_MAX_ALTITUDE_AGL_M = 121.92. Operating temperature limits: consumer MIN_OPERATING_TEMP_CELSIUS = −10, MAX_OPERATING_TEMP_CELSIUS = 40; industrial MIN_OPERATING_TEMP_INDUSTRIAL_CELSIUS = −20, MAX_OPERATING_TEMP_INDUSTRIAL_CELSIUS = 50.

Battery Chemistry Tables#

Accurate battery modeling requires chemistry-specific voltage curves and discharge characteristics. Oya ships frozen constant objects for the three main drone battery chemistries.

BATTERY_LIPO, BATTERY_LION, BATTERY_LIHV — each a frozen object with nominalVoltage, fullVoltage, minVoltage, cutoffVoltage, storageVoltage, energyDensityWhKg, maxDischargeRateC, maxChargeRateC, cycleLife, and four temperature limits (max/min × Discharge/Charge).

The three chemistries in brief: LiPo is 3.7 V nominal / 4.2 V full / 3.3 V min, 180 Wh/kg, 25 C discharge, 300-cycle life; Li-ion is 3.6 V nominal, 250 Wh/kg, 500-cycle life; LiHV (high-voltage lithium polymer) is 3.85 V nominal / 4.35 V full, 200 Wh/kg.

Propeller and Motor Models#

Real propeller and motor data — sourced from APC/UIUC propeller databases and manufacturer KV curves — underpins Oya's thrust estimation and battery life predictions.

PropellerEfficiencyEntry interface (diameterInches, pitchInches, thrustCoefficient, powerCoefficient, figureOfMerit, staticThrustGrams, referenceRpm). PROPELLER_EFFICIENCY_TABLE is a 10-entry readonly array covering 5″ through 28″ propellers, sourced from APC / UIUC propeller data.

MotorKvEntry interface (kvRating, propDiameterRange, recommendedCells, typicalMaxThrustGrams, typicalMaxPowerWatts, useCase). MOTOR_KV_TABLE is an 8-entry readonly array from 2600 KV (3″ micro racing) down to 100 KV (28″+ VTOL/air-taxi propulsion).

ESC and Control Constants#

ESC (Electronic Speed Controller) protocol selection directly affects control loop latency — a dshot1200 ESC can respond 1,500× faster than a traditional pwm ESC.

ESC_RESPONSE_TIMES — protocol response times in microseconds (pwm 20000, oneshot125 250, oneshot42 84, multishot 25, dshot150 106.7, dshot300 53.3, dshot600 26.7, dshot1200 13.3, bidirectionalDshot 30). ESC_MIN_UPDATE_RATES — minimum FC loop rates in Hz (hover 50, acrobatic 400, autonomous 100, racing 1000).

PIDGains interface (kp, ki, kd); DronePIDProfile interface (eight PIDGains sets: roll/pitch/yaw rate, roll/pitch/yaw angle, altitude, position). PID_DEFAULTS is a Record<string, DronePIDProfile> with five conservative first-flight tuning profiles: racing_5inch, consumer_photo, cinelifter, agriculture, vtol.

MAX_ANGULAR_VELOCITY — deg/s limits per mode (normal, sport, cinematic, autonomous), each with roll/pitch/yaw values. MAX_LINEAR_ACCELERATION — m/s² limits per class (micro, consumer, industrial, heavyLift, cinematic), each with horizontal/vertical/deceleration.

Noise and Communication#

NOISE_LIMITS — regulatory dBA limits with measurement distance and regulation name (eu_c0…eu_c3, us_residential, faa_proposed). COMMUNICATION_RANGE — per-protocol rangeMeters/latencyMs/bandwidthKbps/frequencyGHz/protocol for 8 links (rc_2_4ghz, rc_900mhz, video_5_8ghz, dji_ocusync, cellular_4g, cellular_5g, lora, mavlink_wifi).

Battery, Telemetry, Speed, Geofence, and Navigation Defaults#

These defaults are used when an application does not override them, providing safe conservative starting values that match regulatory limits.

Battery thresholds: BATTERY_CRITICAL_PERCENT = 10, BATTERY_LOW_PERCENT = 20, BATTERY_WARNING_PERCENT = 30, plus BATTERY_MAX_TEMP_CELSIUS = 60, BATTERY_MIN_TEMP_CELSIUS = 0, BATTERY_MIN_CELL_VOLTAGE = 3.3, BATTERY_NOMINAL_CELL_VOLTAGE = 3.7, BATTERY_FULL_CELL_VOLTAGE = 4.2.

Telemetry intervals (ms): TELEMETRY_INTERVAL_HIGH_FREQ_MS = 20, _MED_FREQ_MS = 100, _LOW_FREQ_MS = 1000, _GPS_MS = 200, TELEMETRY_HEARTBEAT_INTERVAL_MS = 500, TELEMETRY_HEARTBEAT_TIMEOUT_MS = 3000.

SPEED_LIMITS — a Record<FlightMode, number> of m/s caps per mode: Manual 30, Stabilized 25, Altitude 20, Position 15, Mission 15, ReturnToHome 10, Land 3, Loiter 0, Guided 20, Acro 35.

Geofence defaults: DEFAULT_GEOFENCE_RADIUS = 500 m, DEFAULT_GEOFENCE_MAX_ALTITUDE = 120 m, DEFAULT_GEOFENCE_MIN_ALTITUDE = 0, REGULATORY_MAX_ALTITUDE = 120 m. DEFAULT_GEOFENCE is an Omit<GeofenceZone, 'id' | 'name'> circle with ReturnToHome behavior.

DEFAULT_EMERGENCY_PROCEDURES — a readonly array of four EmergencyProcedure entries ordered by priority: priority 1 MotorKill, priority 2 Land, priority 3 ReturnToHome, priority 4 Hover, each with realistic triggering conditions.

Navigation defaults: DEFAULT_WAYPOINT_RADIUS = 2.0 m, DEFAULT_LOITER_RADIUS = 30.0 m, DEFAULT_CRUISE_SPEED = 10.0 m/s, DEFAULT_LANDING_SPEED = 1.0 m/s, DEFAULT_TAKEOFF_SPEED = 2.0 m/s, DEFAULT_RTH_ALTITUDE = 50.0 m, MIN_SAFE_AGL = 5.0 m.

Communication: GCS_SYSTEM_ID = 255, GCS_COMPONENT_ID = 0, DEFAULT_DRONE_SYSTEM_ID = 1, MAX_SWARM_SIZE = 256.

@oya/core — Coordinate Transforms (coordinate-transforms.ts)#

libs/oya/core/src/coordinate-transforms.ts (379 lines) implements the frame transforms and geodesy primitives. Every navigation algorithm in Oya ultimately calls these functions to move sensor data between the GPS geodetic frame, the local NED planning frame, and the drone's body frame.

Angle utilities: degreesToRadians(degrees), radiansToDegrees(radians), normalizeAngle(radians) (wraps to [−π, π]).

GPS ↔ NED: gpsToLocal(gps, origin) and localToGps(local, origin) use a flat-Earth approximation with WGS84 radii of curvature — the prime-vertical radius N = a/√(1 − e²·sin²lat) and the meridian radius (a·(1−e²))/(1 − e²·sin²lat)^1.5. Accurate to ~1 m within ~10 km of the origin.

NED ↔ Body: localToBody(local, orientation) and bodyToLocal(body, orientation) apply the ZYX Tait-Bryan rotation matrix (yaw → pitch → roll) and its transpose. Body convention: forward = +X, right = +Y, down = +Z.

Quaternion ↔ Euler: quaternionToEuler(q) returns EulerAngles in radians and explicitly clamps pitch at ±90° to handle gimbal lock; eulerToQuaternion( euler) returns a unit Quaternion. Both use the ZYX convention.

Distance and bearing:

• haversineDistance(a, b) — great-circle horizontal distance in meters (ignores altitude), using EARTH_MEAN_RADIUS.
• distance3D(a, b) — Haversine horizontal distance combined with altitude difference by the Pythagorean theorem.
• bearing(from, to) — initial bearing (forward azimuth) in radians, 0 = North, normalized to [0, 2π).
• destinationPoint(start, bearingRad, distanceMeters) — forward geodesic on a sphere; altitude is copied from start.

@oya/core — Math Utilities (math-utils.ts)#

libs/oya/core/src/math-utils.ts (1,842 lines) is the numeric toolkit used by every estimator and planner in the domain. It is the largest foundation file and covers geodesy, linear algebra, interpolation, signal processing, control theory, and geometry.

High-precision geodesy: vincentyDistance(a, b) — geodesic distance via the Vincenty inverse formula, accurate to ~0.5 mm on the WGS84 ellipsoid; falls back to Haversine for non-converging antipodal points.

Rotation matrices: RotationMatrix type (a readonly 9-tuple); eulerToRotationMatrix, rotationMatrixToEuler, multiplyRotationMatrices, transposeRotationMatrix, and the IDENTITY_MATRIX constant.

Interpolation: slerp(q0, q1, t) (quaternion spherical linear interpolation), lerp, inverseLerp, remap, clamp, cubicSpline (returns an interpolating function), bsplineEval / bsplineEvalND, bezierQuadratic, bezierCubic, bezierCubicND.

Signal filters (classes): MovingAverageFilter, ExponentialMovingAverageFilter, KalmanFilter, ExtendedKalmanFilter, ComplementaryFilter, MadgwickFilter (AHRS orientation filter), LowPassFilter, HighPassFilter, BandPassFilter, RateLimiter, DeadBandFilter.

Controllers: PIDConfig interface; PIDController class (with anti-windup); CascadedPIDController class.

Geometry / collision: isInsideCircle, BoundingBox3D interface, createBoundingBox, isInsideBoundingBox, boundingBoxesIntersect, sphereCollision, pointInSphere.

Time and data integrity: TimestampSynchronizer class; UnitConversion object (imperial ↔ metric helpers); crc8, crc16, crc32 checksum functions.

@oya/core — Runtime Validation (validation.ts)#

libs/oya/core/src/validation.ts (356 lines) provides higher-level validation that goes beyond Zod schema parsing. Where types.ts schemas enforce structural correctness (right fields, right types), the functions here enforce semantic correctness — a battery at 5% is structurally valid but semantically dangerous.

• validateGPSCoordinates(coords) → boolean — safeParse against GPSCoordinatesSchema.
• validateBatteryState(battery) → string[] — returns human-readable warnings for percentage thresholds (critical / low / warning), temperature out of [BATTERY_MIN_TEMP_CELSIUS, BATTERY_MAX_TEMP_CELSIUS], per-cell voltage below BATTERY_MIN_CELL_VOLTAGE, negative current without the isCharging flag, and percentage/time-remaining inconsistency.
• validateFlightPlan(plan, capabilities) → string[] — checks the weather and airspace clearance flags, that end time is after start time, that planned duration does not exceed capabilities.maxFlightTime, and warns on terminal plan status (Failed/Cancelled).
• validateGeofence(zone) → boolean — verifies altitude ordering, and that circle zones have a valid center + positive radius / polygon zones have ≥3 valid vertices.
• isWithinGeofence(position, zone) → boolean — altitude-bounds check, then Haversine-distance test for circles or ray-casting point-in-polygon for polygons (the internal isPointInPolygon casts an eastward ray and counts edge crossings).
• validateMission(mission, geofences) → { valid: boolean; violations: string[] } — checks every waypoint for GPS validity, against REGULATORY_MAX_ALTITUDE, against the mission's own altitude/speed constraints, and against every supplied geofence; also verifies non-zero total distance for multi-waypoint missions and non-zero estimated duration.

@oya/core — Error Taxonomy (errors.ts)#

libs/oya/core/src/errors.ts (1,702 lines) defines the structured error system. Every error in Oya carries a machine-readable code, a severity level, recovery suggestions, and optional drone/swarm context — rather than plain Error strings that a catch block can only log and discard.

ErrorSeverity enum — Info, Warning, Error, Critical, Fatal.

OyaError — base class extending Error. Carries a structured code (OyaErrorCode), severity, ISO-8601 timestamp, optional droneId, recoverySuggestions (string array), and a details record. Methods: serialize() → SerializedOyaError, static deserialize(data), and the isEmergency getter (true for Critical or Fatal).

OyaErrorCode is a template-literal union of 24 prefixes — OYA_CONN_${string}, OYA_AUTH_…, OYA_CMD_…, OYA_TIMEOUT_…, OYA_BATT_…, OYA_GPS_…, OYA_IMU_…, OYA_MOTOR_…, OYA_ESC_…, OYA_COMPASS_…, OYA_BARO_…, OYA_CAM_…, OYA_GIMBAL_…, OYA_GEOFENCE_…, OYA_ALT_…, OYA_SPEED_…, OYA_COLLISION_…, OYA_WEATHER_…, OYA_MISSION_…, OYA_SWARM_…, OYA_COMM_…, OYA_PAYLOAD_…, OYA_REG_…, OYA_EMERGENCY_….

Error subclasses (each derives severity from its sub-type and ships context-aware recoverySuggestions). The table below documents every subclass and the discriminant union it carries:

Cross-cutting error functions:

• getRecoverySuggestions(error, context?) — augments an error's suggestions using runtime context (batteryPercent, altitude, distanceFromHome, isAutonomous).
• SwarmErrorSummary interface and aggregateSwarmErrors(errors, totalDrones, abortThresholdPercent = 25) — aggregates errors across a swarm, grouping by severity and by code-prefix category, and computes a shouldAbort flag (true if any fatal error, or if the fraction of drones with critical errors meets the abort threshold).
• ERROR_SEVERITY_TO_LOG_LEVEL — maps ErrorSeverity to a logger level string.
• formatErrorForLogging(error) — produces a structured JSON-Lines log entry (logger: 'oya.drone').
• createErrorTelemetryPayload(errors, maxErrors = 50) — sorts errors most-severe-first and serializes up to maxErrors of them for transmission.

@oya/core — Subsystem Modules#

Beyond the foundation, @oya/core contains 95 further subsystem modules. They are real, fully-implemented TypeScript (verified clean by the V1-P2-2110 stub-indicator audit, docs/releases/p2/oya-stub-audit.md, 2026-05-04). Each ships a matching *.test.ts. They are re-exported by name through core/src/index.ts. The sections below group them by domain area.

Kinematics, Dynamics, and Flight Control#

The flight control stack runs from low-level 6-DOF rigid body dynamics and motor mixing all the way up to trajectory-level path planning and gimbal coordination.

• kinematics.ts — Vec3/Quat types and a vector/quaternion algebra (vec3, vec3Add, vec3Sub, vec3Scale, vec3Dot, vec3Cross, vec3Mag, vec3Normalize, quatIdentity, quatNormalize, quatMultiply, …) plus rigid-body dynamics and rotor-mixing models.
• physics-simulation.ts — physics-based flight simulation.
• attitude-control.ts — cascaded PID and SO(3) geometric attitude control.
• velocity-position-control.ts — velocity and position control loops.
• path-planning.ts — trajectory generation (minimum-snap, Dubins, B-spline smoothing).
• obstacle-avoidance.ts — potential-field and occupancy-grid avoidance.
• gimbal-control.ts, camera-gimbal-api.ts — 3-axis gimbal stabilization and the camera/gimbal command API.
• shot-planning.ts, cinematography-trajectory.ts — cinematic shot library and keyframed flight-path generation.

Sensors, Navigation, and State Estimation#

State estimation combines data from multiple sensors — each with different update rates, failure modes, and accuracy profiles — into a single unified estimate of position, velocity, and attitude.

• gps-navigation.ts — GNSS navigation, RTK corrections, u-blox UBX parsing.
• imu-orientation.ts — IMU fusion (Madgwick / Mahony AHRS).
• lidar-integration.ts, depth-sensors.ts — LiDAR point clouds and depth sensing.
• multi-sensor-fusion.ts — EKF fusion of GPS / IMU / barometer / optical flow / UWB.
• indoor-positioning.ts — GPS-denied indoor positioning.
• visual-slam.ts, advanced-slam-vio.ts, event-camera-navigation.ts — SLAM and visual-inertial odometry.
• ikd-tree.ts, gtsam-bridge.ts, scene-change-detector.ts — spatial index, factor-graph bridge, and scene-change detection helpers.
• coordinate-transforms.ts, math-utils.ts — see foundation sections above.

Computer Vision and AI#

The vision pipeline covers detection, pose estimation, segmentation, tracking, and edge inference — the full stack required for applications from search-and- rescue to precision agriculture.

• Detection: yolov12-integration.ts, rtdetr-integration.ts, uavdetr-integration.ts.
• Pose / human analysis: pose-detection-2d.ts, advanced-pose-estimation.ts, detrpose-integration.ts, sapiens-integration.ts, body-reconstruction-3d.ts, form-analysis.ts, human-aware-navigation.ts.
• Segmentation / tracking: sam-integration.ts, subject-tracking.ts, temporal-tracking.ts, multi-view-fusion.ts, multi-camera-coordination.ts.
• Models / inference: pretrained-models.ts, model-optimization.ts, model-inference.ts, edge-deployment.ts.

Swarm Coordination#

Swarm modules add distributed intelligence on top of the single-drone control primitives — from leader election and formation geometry to graph-neural-network collective behavior and inter-drone mesh communication.

• swarm-api.ts, swarm-coordination.ts, formation-flying.ts — swarm API, coordination, and formation flight.
• consensus-algorithms.ts, gnn-swarm-intelligence.ts — distributed consensus and graph-neural-network swarm intelligence.
• task-allocation.ts — distributed task assignment (contract-net / Hungarian).
• swarm-collision-avoidance.ts — ORCA multi-agent avoidance.
• inter-drone-communication.ts — multi-agent MAVLink messaging and mesh networking.

Mission, Geofencing, and Safety#

Mission execution is a state machine that takes a validated Mission object and drives a drone from waypoint to waypoint while monitoring geofences, battery state, and emergency conditions at each step.

• mission-execution.ts — the mission state machine: MissionUploader, MissionValidator (with ValidationSeverity / ValidationIssue / MissionValidationResult), WaypointSequencer, WaypointNavigationStateMachine (NavigationState enum), WaypointAcceptanceChecker, StraightLineNavigation, CurvedWaypointTransition, StopAndTurnMode, FlythroughMode, and the totalMissionDistance helper.
• geofencing.ts — geofence shapes and enforcement: PolygonGeofence, CircularGeofence, CylindricalGeofence, CorridorGeofence, AltitudeFloorCeiling, NoFlyZoneManager, DynamicGeofence, GeofenceImporter, MultiZoneManager, NestedGeofenceManager, BreachDetector (BreachSeverity), GraduatedWarningSystem, ContainmentActionExecutor (ContainmentAction), ReEntryDetector, GeofenceVisualizer.
• emergency-procedures.ts, health-check.ts — failsafe procedures and pre-flight health checks.

Protocols, Autopilots, and Simulation#

This group covers the wire protocol layer (MAVLink v2), the autopilot integration layers (PX4, ArduPilot), hardware abstraction (DJI, Pixhawk-family, 2025-generation compute boards), and the simulation backends.

• mavlink-protocol.ts — MAVLink v2 (heartbeat, COMMAND_LONG/INT, mission, parameter, FTP, logging, camera, gimbal v2 protocols; message signing; router).
• protocol-sender.ts — protocol message transport helper.
• px4-autopilot.ts, ardupilot.ts — PX4 and ArduPilot integration layers.
• dji-sdk.ts, generic-hardware.ts, hardware-platforms-2025.ts — DJI SDK, generic autopilot hardware abstraction, and 2025-generation hardware profiles.
• camera-systems.ts, camera-discovery-providers.ts — camera subsystem and discovery.
• audio-systems.ts, whisper-asr-bridge.ts — onboard audio and an ASR bridge.
• Simulation: sitl-integration-framework.ts, gazebo-integration.ts, airsim-integration.ts, jmavsim-integration.ts, modern-simulation-platforms.ts.

Regulatory, Power, Enterprise, and Data#

The remaining modules cover the business and operational layers: regulatory compliance, next-generation power systems, enterprise fleet management, spatial data, observability, logging, and the database access layer.

• regulatory-compliance.ts, faa-bvlos-compliance.ts — airspace / LAANC / Remote ID / BVLOS compliance.
• nextgen-power-systems.ts — solid-state BMS, hydrogen fuel cells, energy harvesting, charging infrastructure.
• enterprise-platform.ts — DaaS, fleet management, UTM, drone-in-a-box, AI mission agent, and industry-specific solution templates.
• gaussian-splatting-integration.ts, spatial-data.ts — photogrammetry into 3DGS, and GeoJSON spatial data management.
• telemetry-collection.ts, timeseries-storage.ts — telemetry aggregation and time-series storage.
• flight-logging.ts, post-flight-analysis.ts, observability.ts — flight logs, post-flight analysis, and metrics.
• realtime-streaming.ts, video-streaming.ts — low-latency telemetry and video streaming.
• database-schema.ts, data-access-layer.ts — typed DB schema and the repository layer.
• natural-language-control.ts — natural-language drone/mission control.

SDK and Cross-Domain Integration#

The SDK layer is the consumer-facing surface. The cross-domain adapter modules define the typed boundaries toward other Oshun domains; the concrete runtime wiring to event-bus, storage, and metrics is part of the planned expansion.

• sdk-core.ts — the SDK kernel: SdkConfig, DEFAULT_SDK_CONFIG, SdkCore, ConnectionManager, SdkAuthenticator (SdkAuthMethod — apikey/token/certificate/none), SdkEventBus, plus middleware, plugin, feature-flag, health, and diagnostic types.
• drone-control-api.ts, telemetry-api.ts — high-level command API and the typed telemetry subscription stream.
• Cross-domain adapters: isis-integration.ts, lilith-integration.ts, sophia-integration.ts, aja-integration.ts, aphrodite-integration.ts, yemaya-integration.ts, bellona-integration.ts.

Sibling Package — @oya/flight-control#

libs/oya/flight-control/src/index.ts (16 KB) is a flight-control readiness evaluator: it scores whether a fleet's flight controllers are production-ready for remote drone operation. It is not the low-level control loop itself (that lives in @oya/core's attitude-control.ts / velocity-position-control.ts). The evaluator produces a structured report with coverage ratios and blocking or warning issues that a pre-flight checklist UI or CI gate can consume directly.

Status / readiness types. OYA_FLIGHT_CONTROL_STATUS constant (READY/NEEDS_ATTENTION/BLOCKED) with derived OyaFlightControlStatus; OyaControlReadiness = 'ready' | 'needs-attention' | 'blocked'. OyaFlightMode = 'manual' | 'stabilized' | 'altitude' | 'position' | 'mission' | 'guided' | 'loiter' | 'rth' | 'land'. OyaGpsFix = 'none' | '2d' | '3d' | 'dgps' | 'rtk_float' | 'rtk_fixed'. OyaVec3 = { x, y, z } readonly.

Model interfaces. OyaFlightControlLoop (per-loop tuning gates: updateRateHz vs targetUpdateRateHz, rmsError vs maxAllowedRmsError, saturationPct vs maxAllowedSaturationPct, failsafeHookReady); OyaFlightNavigationRoute (planner/obstacle/GPS/velocity/position-hold/ replanning/geofence-clamp readiness flags and a cross-track error gate); OyaFlightControllerNode (a single drone's controller: flightMode, armed, firmware/parameter sync, GPS fix, sensor health, motor health, battery, and the three nested loops attitudeLoop/velocityLoop/positionLoop plus navigation); OyaFlightControlScenario (a labelled set of controllers with minimum coverage ratios).

Evaluation outputs. OyaFlightControlIssue (typed issueType — controller-missing / low-level-low / stabilization-low / navigation-low / safety-low / battery-low / required-controller-blocked — with 'warning' | 'blocking' severity); OyaFlightControllerEvaluation, OyaFlightControlScenarioEvaluation, OyaFlightControlReport, OyaFlightControlRunResult.

Functions. evaluateOyaFlightControlScenario(scenario), createOyaFlightControlReport(scenarios), runOyaFlightControl(scenarios). The evaluator computes four coverage ratios per controller — low-level (arming, command-ack, firmware, parameter sync, GPS fix ≠ none/2d, ≥10 satellites, IMU/baro/mag health, motor health), stabilization (the three loops within tolerance plus a non-manual flight mode), navigation, and safety — escalates issues to blocking when the scenario and controller are both required, and rolls scenario results into a report with averaged ratios, a status, and a deduplicated nextActions list. The report also embeds a JSON exportPayload.

Sibling Package — @oya/telemetry#

libs/oya/telemetry/src/index.ts (18 KB) is a telemetry readiness evaluator: it scores whether real-time drone telemetry feeds are production-ready for remote capture. It evaluates six coverage dimensions per feed and aggregates them into a single typed report.

Status / readiness. OYA_TELEMETRY_STATUS constant + OyaTelemetryStatus; OyaTelemetryReadiness; OyaGpsFix (same six-value union as @oya/flight-control).

Snapshot interfaces. OyaTelemetryBatterySnapshot (voltage, current, percent remaining vs minimum, temperature vs max, per-cell voltages, cell imbalance, estimated flight time vs minimum); OyaTelemetryGpsSnapshot (fixType, satellites vs minimum, HDOP/VDOP vs maxima, RTK availability, position validity); OyaTelemetryImuSnapshot (accel/gyro/mag health, vibration RMS vs max, temperature vs max); OyaTelemetryMotorSnapshot (motorId, RPM vs expected minimum, ESC temperature, current, faultCode); OyaTelemetryTemperatureSnapshot (flight-controller / payload / airframe temperatures vs maxima); OyaDroneTelemetryFeed (one drone's feed: latency/sample-rate/link-quality/timecode/redundancy gates plus the five nested snapshots).

Evaluation outputs. OyaTelemetryScenario, OyaTelemetryIssue (issueType — feed-missing / realtime-low / battery-low / gps-low / imu-low / motor-low / temperature-low / required-feed-blocked), OyaTelemetryFeedEvaluation, OyaTelemetryScenarioEvaluation, OyaTelemetryReport, OyaTelemetryRunResult.

Function. runOyaTelemetry(scenarios) — evaluates six coverage ratios per feed (realtime, battery, GPS, IMU, motor, temperature), escalates blocking issues for required feeds, and produces an aggregate report with averaged ratios, status, nextActions, and a JSON exportPayload.

Sibling Package — @oya/mission-planning#

libs/oya/mission-planning/src/index.ts (18 KB) is a mission-planning readiness evaluator for pre-programmed waypoints, actions, triggers, and mission-upload gates. It answers the question: is this mission plan ready to upload and execute?

Status / readiness. OYA_MISSION_PLANNING_STATUS + OyaMissionPlanningStatus; OyaMissionPlanningReadiness. OyaMissionActionType and OyaMissionTriggerType are string-literal unions enumerating mission action and trigger kinds.

Model interfaces. OyaMissionPosition; OyaMissionWaypoint; OyaMissionAction; OyaMissionTrigger; OyaMissionPlan (a plan with waypoints, actions, triggers and upload gates); OyaMissionPlanningScenario.

Evaluation outputs. OyaMissionPlanningIssue, OyaMissionPlanEvaluation, OyaMissionPlanningScenarioEvaluation, OyaMissionPlanningReport, OyaMissionPlanningRunResult.

Function. runOyaMissionPlanning(scenarios) — evaluates mission plans for planning/upload readiness and produces an aggregate report.

Sibling Package — @oya/safety#

libs/oya/safety/src/index.ts (16 KB) is a safety readiness evaluator for geofencing, emergency procedures, and regulatory compliance. It evaluates whether a drone's complete safety posture — geofence rules, emergency procedures, and regulatory framework compliance — meets the required standard before a flight is authorized.

Status / readiness. OYA_SAFETY_STATUS + OyaSafetyStatus; OyaSafetyReadiness. OyaEmergencyProcedureType is a string-literal union of emergency-procedure kinds. OyaRegulatoryFramework = 'faa-part-107' | 'easa-open' | 'caa' | 'local-film-permit'.

Model interfaces. OyaGeofenceRule; OyaEmergencyProcedure; OyaRegulatoryComplianceGate; OyaSafetyCase (a drone's combined geofence, emergency-procedure, and regulatory posture); OyaSafetyScenario.

Evaluation outputs. OyaSafetyIssue, OyaSafetyCaseEvaluation, OyaSafetyScenarioEvaluation, OyaSafetyReport, OyaSafetyRunResult.

Function. runOyaSafety(scenarios) — evaluates safety cases for geofence / emergency / regulatory readiness and produces an aggregate report.

Sibling Package — @oya/swarm-intelligence#

libs/oya/swarm-intelligence/src/index.ts (31 KB) is the largest sibling package. It has two distinct layers: concrete swarm-control primitives that are used directly in application code, and a swarm-intelligence readiness evaluator that scores whether a swarm configuration is production-ready for autonomous multi-drone operation.

Swarm-Control Primitives#

These are the building blocks for implementing swarm behavior: leader election, formation geometry, task allocation, and kinematic simulation.

String-literal unions:

• AllocationStrategy — nearest / load_balanced / capability_match / priority.
• ElectionStrategy — highest_battery / closest_to_center / manual / round_robin.
• FormationType — line / v_formation / grid / circle / diamond / custom.
• MsgPriority — low / normal / high / critical.

Interfaces: SwarmPos ({ x, y, z }), SwarmDroneInfo (id, role — leader/follower/scout/relay/standby — position, batteryPct, online, capabilities), SwarmConfig (name, maxDrones, separationM, communicationRangeM, formationType, electionStrategy), FormationSlot, SwarmMissionWaypoint, SwarmSimResult, SwarmTask (id, description, assignedTo, priority, status — pending/assigned/in_progress/ completed/failed — position).

Implemented control classes:

• SwarmCreationAPI — allocates swarm IDs.
• DroneRegistrationAPI — a drone registry keyed by drone ID.
• LeaderElectionAPI — implements all four ElectionStrategy variants: highest-battery reduce, closest-to-centroid, round-robin, and manual fallback.
• FormationControlAPI — computes per-drone FormationSlot offsets with real geometry for line, V, grid, circle, diamond, and custom formations.
• TaskAllocationAPI — creates SwarmTasks and allocates them by nearest-by-distance or first-available strategy.
• SwarmMissionAPI — loads and starts a waypoint mission across the swarm.
• SwarmSimulationAPI — steps a proportional-pursuit kinematic simulation, counts pairwise collisions, and reports formation accuracy.

Swarm-Intelligence Readiness Evaluator#

OYA_SWARM_INTELLIGENCE_STATUS + OyaSwarmIntelligenceStatus; OyaSwarmReadiness; OyaSwarmMissionSegmentPriority = Extract<MsgPriority, 'normal' | 'high' | 'critical'>. Interfaces: OyaSwarmIntelligenceDrone, OyaSwarmFormationPlan, OyaSwarmMissionSegment, OyaSwarmIntelligenceScenario, OyaSwarmIntelligenceIssue, OyaSwarmCommandModel, OyaSwarmIntelligenceEvaluation, OyaSwarmIntelligenceReport, OyaSwarmIntelligenceRunResult.

Functions: buildOyaSwarmCommandModel(...), evaluateOyaSwarmIntelligenceScenario(scenario), createOyaSwarmIntelligenceReport(scenarios), runOyaSwarmIntelligence(scenarios) — evaluates whether a swarm's formation plans, mission segments, and command model are ready for autonomous multi-drone operation.

Integration Points#

@oya/core ships TypeScript cross-domain adapter modules (*-integration.ts) that define the typed boundary toward other Oshun domains. The boundary exists because Oya owns aerial autonomy primitives and not the downstream processing. For example, Oya captures geotagged imagery but Maya owns 3DGS reconstruction; Oya estimates human poses from footage but Aja owns motion-capture archiving. The adapter modules define the exact types passed at each boundary.

observability.ts, flight-logging.ts, database-schema.ts, and data-access-layer.ts define the typed surfaces for metrics export, structured logging, and persistence. The concrete platform-level wiring to @oshun/storage, @oshun/event-bus, @oshun/metrics, and @oshun/database is part of the planned expansion below.

Planned Library Expansion (planned)#

The following are not implemented. They trace to docs/proposals/OYA_DOMAIN_PROPOSAL.md and TODOS Phase 33 ("Oya — AI-Controlled Drone & Swarm Management Platform"), which scopes Oya as a platform capability domain consumed by Lilith, Yemaya, and Aphrodite.

• Application / service tier (planned) — there is currently no apps/oya/ or services/oya/. A ground control station, fleet dashboard, and mission planner front-end, plus any long-running telemetry ingestion service, are planned consumers of @oya/core.
• Platform-bus wiring (planned) — concrete runtime integration of the *-integration.ts adapter surfaces with @oshun/storage, @oshun/event-bus, @oshun/metrics, and @oshun/database (telemetry archive, mission history, drone registry, captured-imagery storage, event publication).
• Gaia weather/cyclone consumption (planned) — per features.md, Phase 175 plans for Oya to consume Gaia cyclone, wind, precipitation, lightning, and severe-weather products as inputs to mission planning (no-fly cones, hurricane-hunter swarm tasking, outdoor mission gating). No Gaia adapter exists in libs/oya/ today.
• Rust performance tier (planned) — high-frequency telemetry processing and MAVLink framing are candidates for Rust crates exposed to TypeScript via WASM (wasm-pack) or native bindings (napi-rs), as noted in architecture.md's technology considerations.