astrology design library
Ephemeris4 MIN READ10 / 31

Astrology Semantics — High-Level Design

Reading guide: The current package architecture defines the binder boundary. Sections below describe reference designs unless an implementation note says otherwise. Standalone facade, cache and provenance services are dropped; their integration responsibilities belong to the consumer.

Status: Draft for review · Part of: Astro Binder · Updated: 2026-10-24

The module turns canonical astronomy into signs, nakshatras, padas, motion, aspects and houses. It is pure, in-process, with no provider, network, clock or locale.

The pure derivations are implemented in the separate @astrology/astrology-semantics package. The package guide describes the exported functions, default aspect profile and caller-owned context checks. The diagram below remains the reference design for the wider binder.

1. Purpose

Two providers can return the same longitude yet produce different charts if each feature implements its own rules. This module implements them once, so charts, transits and panchang agree on sign and nakshatra.

It answers meaning, not position:

  • Which sign and degree within it?
  • Which nakshatra and pada?
  • Is the body retrograde?
  • Which aspects are in orb, applying or separating?
  • Which house holds the body?

2. Where it sits

canonical positions + houses ──▶ astrology semantics ──▶ semantic annotations
  • Upstream: the canonical normalizer resolves units, frame and zodiac.
  • Downstream: the calculation facade attaches annotations.
  • Never: calls a provider, reads a cache, writes storage.

3. Responsibilities

Component Owns Deterministic rule
Sign + degree 12 signs from 0° Aries sign = floor(longitude / 30), degree = longitude mod 30
Nakshatra + pada 27 nakshatras from 0° sidereal Aries nakshatra = floor(longitude / 13°20′), pada = floor((longitude mod 13°20′) / 3°20′) + 1
Motion state Retrograde flag, speed exposure retrograde = speedLongitude < 0, except a declared node convention
Aspects Separation, orb, applying/separating Shortest arc against the orb profile
House placement Cusp interval holding a body Cusps in zodiacal order, wrap at 360°
Reference tables Sign, nakshatra, orb definitions Read-only, versioned

4. Architecture

Astrology semantics — high-level design Reference design. A pure module inside Astro Binder derives signs, nakshatras, motion state, aspects and house placement from canonical positions and houses. Reference tables are read-only and versioned. No provider, network, clock or locale is involved. Astrology Semantics — High-Level Design Provider-independent meaning derived from canonical positions and houses, inside Astro Binder. Canonical positions longitude · latitude · speed sidereal or tropical, resolved Houses and angles 12 cusps · ascendant · MC house system already applied Request context zodiac · ayanamsa · orb profile node type · house system position-derived house-derived shared tables Sign + degree 12 signs from 0° Aries degree within sign 0–30 Nakshatra + pada 27 × 13°20′ from 0° Aries 4 padas of 3°20′ Motion state retrograde from longitude speed mean or true node respected Aspects separation vs orb profile applying or separating House placement cusp interval lookup wraps at 360° Whole-sign is a sign offset from the ascendant sign. Other systems walk cusps forward and wrap at 360°. Reference tables signs · nakshatras · orbs versioned with the module Nakshatra stays null for tropical requests: no silent ayanamsa mix. Tables are read-only data. longitude · speed cusps · angles zodiac · ayanamsa · orbs annotations Semantic annotations per-body and chart annotations sign · nakshatra · pada · aspects pure module · no I/O · no clock · one ayanamsa subtraction dependency module result

Diagram: reference design, not deployed behaviour.

The module is small pure functions over one canonical input, with no orchestration and no request spine. Any subset of derivations can be requested without changing the others.

5. Rules

  1. One ayanamsa subtraction. Longitude already sits in the requested zodiac; a second subtraction is a defect, not a configuration.
  2. Sidereal meanings stay sidereal. Nakshatra and pada are null for a tropical request, never derived from a mixed zodiac.
  3. No rounding. Full double precision; serialisation rounds once, in the normalizer’s output contract.
  4. Canonical identifiers only. aries, ashwini, conjunction — lowercase; labels and translations stay in the client.
  5. Half-open intervals. Boundary longitude starts the next sign, nakshatra or house: [0, 30) is Aries, 30.0 is Taurus.
  6. Unknown input is rejected upstream. Validated values only; no defaults for missing bodies or cusps.

6. Edge cases

Case Behaviour
Longitude 359.9999° Wraps for aspects; sign is Pisces, not Aries
Exact boundary (30°, 13°20′, cusp) Next interval, per the half-open rule
Mean vs true node Differs near boundaries; response records nodeType
Retrograde station Near-zero speed follows speedLongitude sign; no hysteresis
Applying vs separating Relative speed and shortest arc, not orb size
Houses at high latitude Engine rejects upstream; never guesses a cusp
Tropical + nakshatra request Omitted, not converted silently

7. Out of scope

  • Provider selection, caching, retries, provenance (facade, router).
  • Unit, frame and zodiac conversion (normalizer).
  • Interpretations, dignity scoring, yogas, dasha periods (later product logic).
  • Localised names and glyphs (presentation layer).

8. Planned code

Piece Responsibility
semantics/SignResolver Sign and degree
semantics/NakshatraResolver Nakshatra, pada, sidereal guard
semantics/MotionResolver Retrograde, node state
semantics/AspectResolver Separation, orb, applying/separating
semantics/HouseResolver Cusp interval, whole-sign
semantics/ReferenceTables Versioned sign, nakshatra, orb data