Skip to content

HARMONICS_BACKEND_STANDARD

Jump to bottom
TheDaniel166 edited this page Jul 25, 2026 · 1 revision

Harmonics Backend Standard

Version: 0.2 Date: 2026-07-19 Status: admitted backend standard

Scope

This standard governs the caller-supplied-longitude harmonic surfaces:

  • moira.harmonics
  • moira.harmonic_transits

It covers:

  • direct harmonic chart projection
  • age-harmonic projection
  • harmonic conjunction detection and pattern scoring
  • harmonic series sweeps and vibrational fingerprints
  • natal aspect decoding as harmonic conjunctions
  • cross-chart composite harmonic conjunctions
  • explicit harmonic-orb scaling policy and resolved provenance
  • sampled mixed-origin harmonic transit configurations
  • the HARMONIC_PRESETS catalogue

It does not govern moira.harmograms, ordinary aspect doctrine, chart or ephemeris construction, progression search, interpretive narrative, or exact harmonic transit ingress/egress solving.

Authority And Provenance

The engine documents the harmonic tradition through:

  • John Addey, Harmonics in Astrology, Chapter 14
  • David Hamblin, Harmonic Charts
  • David Cochrane's harmonic-pattern and vibrational-astrology materials

The VA-informed forecast boundary additionally records:

These sources inform the admitted mixed-origin cardinalities and the idea of activating natal harmonic configurations. They do not establish numerical parity with Sirius or supply Moira's sampled-window geometry.

The computational core is arithmetic over longitudes supplied by a caller. It does not own the astronomical derivation of those longitudes.

Governing Harmonic Transformation

Every input longitude is first reduced to Moira's canonical zero-Aries branch:

lambda_0 = longitude mod 360, where lambda_0 is in [0, 360)
lambda_H = (lambda_0 * H) mod 360

H must be a positive finite real number on a single-harmonic surface. An integer H is the ordinary cyclic harmonic projection. A non-integer H is an explicitly zero-Aries-anchored continuous multiplier: it is evaluated from the canonical [0, 360) representative and must not be described as an origin-free circle endomorphism.

This branch rule makes H=5.5 a first-class value. The engine must not coerce, truncate, round, or clamp it to H=5.

Integer-range products remain integer by doctrine:

  • harmonic_sweep
  • harmonic_aspects
  • vibrational_fingerprint
  • MixedOriginHarmonicTransitForecastPolicy.harmonics

age_harmonic remains the distinct time-derived surface whose multiplier is (jd_now - jd_birth) / tropical_year, subject to its established 1e-6 positive floor at the exact birth instant. It is not an adapter for arbitrary fractional harmonic requests.

Harmonic-Orb Doctrine

HarmonicOrbPolicy is the immutable, provenance-bearing conjunction-orb policy. The admitted scaling mode is HarmonicOrbScalingMode.ADDEY_INVERSE_HARMONIC, expressed as:

O_H = O_1 / H

reference_orb_deg is the caller-configurable H1 reference O_1. Resolution for one harmonic produces HarmonicOrbTruth with two deliberately distinct limits:

  • projected_orb_limit_deg = O_1: the threshold applied after projection on the 360-degree harmonic chart
  • source_orb_limit_deg = O_1 / H: the locally equivalent allowance on the source zodiacal circle

The existing orb argument and REST field continue to mean the projected threshold/H1 reference. Applying O_1/H again on the projected chart would produce an unintended 1/H^2 source scaling and is prohibited.

For non-integer H, the same arithmetic relation is exposed with noninteger_extension=true (continuous_extension=true over REST). That is an explicit Moira continuous extension of the cited integer-harmonic rule, not an attribution of fractional doctrine to the source.

Callers may use the legacy orb argument or orb_policy, but not both in the same engine call. The default reference orb remains 1.0 degree.

Governing Objects

The admitted moira.harmonics objects are:

  • HarmonicPosition
  • HarmonicConjunction
  • HarmonicPatternScore
  • HarmonicSweepEntry
  • HarmonicAspect
  • VibrationFingerprint
  • HarmonicOrbScalingMode
  • HarmonicOrbPolicy
  • HarmonicOrbTruth
  • HarmonicsService
  • HARMONIC_PRESETS

The admitted moira.harmonic_transits objects are:

  • HarmonicTransitMemberOrigin
  • MixedOriginHarmonicTransitMode
  • HarmonicTransitSample
  • HarmonicTransitMember
  • HarmonicTransitPatternSample
  • HarmonicTransitWindow
  • HarmonicTransitForecast
  • MixedOriginHarmonicTransitForecastPolicy

The preset catalogue is descriptive. It is not permission to expose unbounded sweeps or interpretive claims.

Admitted Computations

The harmonic backend admits:

  • calculate_harmonic(planet_longitudes, harmonic)
  • age_harmonic(planet_longitudes, jd_birth, jd_now)
  • harmonic_conjunctions(..., harmonic, orb=None, *, orb_policy=None)
  • harmonic_pattern_score(..., harmonic, orb=None, *, orb_policy=None)
  • harmonic_sweep(..., max_harmonic=32, orb=None, *, orb_policy=None)
  • harmonic_aspects(..., orb=None, max_harmonic=32, *, orb_policy=None)
  • composite_harmonic(..., harmonic, orb=None, ..., *, orb_policy=None)
  • vibrational_fingerprint(..., max_harmonic=32, orb=None, *, orb_policy=None)
  • mixed_origin_harmonic_transit_forecast(natal_longitudes, transit_samples, policy)

All are pure computations over caller-owned longitudes. They do not own a kernel, location, house, ayanamsa, time zone, chart builder, or ephemeris.

The transit forecast is governed separately by HARMONIC_TRANSIT_FORECAST_STANDARD.md.

Required Transport Invariants

Any REST transport for harmonics must preserve:

  • requested and effective harmonic values without integer truncation
  • harmonic kind: integer, continuous_multiplier, age_decimal, range_sweep, or the forecast family's explicit provenance
  • the zero-Aries [0, 360) input branch and projection formula
  • caller-supplied longitude ownership, the normalized source longitude used, and engine-normalized result body labels
  • computed harmonic longitudes and deterministic ordering
  • the H1 reference orb, projected limit, source-circle limit, scaling mode, formula, authority, and continuous-extension truth where applicable
  • maximum body, sample, harmonic, and work bounds for the requested product
  • preset name and description only for integer harmonics in HARMONIC_PRESETS

Transport must reject non-finite values, empty or duplicate-trimmed body identity, invalid harmonics, invalid policy selectors, unbounded ranges, and requests above the product-specific work limits. It must not silently clamp or coerce user intent.

Validation Requirements

The focused backend corpus is:

.\.venv\Scripts\python.exe -m pytest tests\unit\test_harmonics.py tests\unit\test_harmonic_transits.py -q

It must continue to cover:

  • public surface completeness
  • formula truth and output range
  • fractional H distinct from its truncated integer
  • zero-Aries canonical-branch equivalence for out-of-range input longitudes
  • positive-finite-real harmonic rejection policy
  • projected/source orb-limit equivalence and no double scaling
  • integer range doctrine for sweep, aspects, fingerprint, and forecast
  • conjunction, cluster, composite-label, and fingerprint invariants
  • immutable forecast policy, input maps, and result vessels
  • complete-three-member minimum-circular-arc admission
  • both mixed-origin modes
  • sampled window splitting, peak selection, duration filtering, and provenance

REST admission additionally requires adversarial bounds, OpenAPI float-vs-int schema, malformed identity, and route serialization coverage.

Non-Goals

This standard does not admit:

  • interpretive readings of harmonic meaning
  • unbounded harmonic sweeps or forecast work
  • automatic chart or ephemeris construction
  • progression harmonic search
  • interpolation between supplied transit samples
  • exact transit ingress, egress, or event-time claims
  • numerical or feature parity with Sirius
  • harmogram spectral analysis
  • background jobs or chart rendering
  • generic /v1/special/* exposure

Clone this wiki locally