HOUSES_BACKEND_STANDARD - TheDaniel166/moira GitHub Wiki

The Moira houses backend is a sovereign computational subsystem. Its definitions, layer boundaries, invariants, failure doctrine, and determinism rules are stated here and are frozen until explicitly superseded by a revision to this document.

This document reflects current implementation truth as of Phase 11 (1 189 passing tests across 10 unit files and 1 integration file). It does not describe aspirational future capabilities.

A house cusp in Moira is:

An ecliptic longitude in degrees [0, 360) that marks the opening boundary of one of the twelve astrological houses for a given observer location, Julian date, and house system.

Twelve cusps are always produced. No system produces fewer or more than 12.

A house in Moira is:

The half-open ecliptic arc [cusps[n-1], cusps[n % 12]) for house number n (1–12), where arcs are measured as forward arcs on the circle.

A placement is:

The result of assigning one normalised ecliptic longitude to exactly one house under the interval rule using a specific set of 12 cusps.

An angularity category is:

A structural label derived from the assigned house number alone, independent of cusp positions, system family, or latitude.

Cusp proximity is:

The forward-arc distance from a placed longitude to its nearest bracketing cusp, evaluated against an explicit caller-declared threshold.

A signed cusp delta between two systems is:

(right.cusps[i] - left.cusps[i]) % 360° - 360° when > 180°, else (right.cusps[i] - left.cusps[i]) % 360°.

Result is always in the range (-180°, 180°]. Positive means the right cusp is counter-clockwise ahead of the left; negative means behind.

The backend is organised into ten phases. Each phase operates only on outputs produced by phases below it. No phase reaches upward.

Phase  1 — Truth preservation           (HouseCusps: system / effective_system / fallback)
Phase  2 — Classification               (HouseSystemFamily, HouseSystemCuspBasis, HouseSystemClassification)
Phase  3 — Inspectability               (HouseCusps.__post_init__, _POLAR_SYSTEMS, _KNOWN_SYSTEMS)
Phase  4 — Policy                       (UnknownSystemPolicy, PolarFallbackPolicy, HousePolicy)
Phase  5 — Point-to-house membership    (HousePlacement, assign_house)
Phase  6 — Cusp proximity               (HouseBoundaryProfile, describe_boundary)
Phase  7 — Angularity                   (HouseAngularity, HouseAngularityProfile, describe_angularity)
Phase  8 — System comparison            (HouseSystemComparison, HousePlacementComparison, compare_systems, compare_placements)
Phase  9 — Chart-wide distribution      (HouseOccupancy, HouseDistributionProfile, distribute_points)
Phase 10 — Subsystem hardening         (invariant register, failure-behavior freeze, terminology alignment)

A function in phase N:

• may consume any result vessel from phases 1 through N−1
• may not re-run cusp arithmetic
• may not re-perform house membership independently of assign_house
• may not mutate a vessel produced by an earlier phase
• may not introduce new doctrine inputs that are not explicit parameters

19 house system codes are recognised. _KNOWN_SYSTEMS is the authoritative frozenset.

Polar-incapable systems (_POLAR_SYSTEMS): P, K. These systems produce geometrically disordered cusps above the critical latitude 90° − obliquity (≈ 66.56° at J2000) and fall back to Porphyry under the default policy.

For QUADRANT family systems with cusp_basis == HORIZON (Azimuthal, code H), cusps[0] is a horizon-derived cusp and legitimately differs from the geographic Ascendant. The __post_init__ guard that asserts cusps[0] == asc is skipped for this basis. All non-quadrant families also legitimately place H1 ≠ ASC.

The houses backend delegates to external modules without redefining them.

The backend does not redefine any of these. Changes to those modules propagate automatically to all cusp computations.

All public names are declared in the module moira/houses.py.

Two conditions can redirect the computation away from the default polar fallback path. Both are evaluated before any cusp arithmetic.

The critical latitude is computed from the chart's actual obliquity at call time. At J2000 obliquity (23.4377°) this is ≈ 66.56° — the geometric Arctic Circle, above which some ecliptic degrees become circumpolar and the standard fixed-point semi-arc iteration can produce geometrically invalid cusp orderings. The old fixed 75.0° threshold was incorrect: it silently returned invalid cusp sets from ≈66.6° to 74.9°.

This does not mean Placidus is mathematically impossible above the critical latitude. The 77°N branch-search experiment showed that valid, ordered Placidus solutions can exist in narrow ARMC regimes. Moira therefore distinguishes between:

• globally supported behavior (default production path)
• conditionally solvable high-latitude cases (experimental search path)
• unsupported cases where the current production solver cannot recover a valid branch

Critical latitude takes precedence over unknown system when both conditions are true.

When a fallback occurs:

When no fallback occurs: fallback = False, fallback_reason = None.

PolarFallbackPolicy.EXPERIMENTAL_SEARCH is an explicit opt-in research mode. It currently applies only to HouseSystem.PLACIDUS.

• The engine calls the separate moira.experimental_placidus module.
• The search solves the semi-arc equations directly and accepts the result only when exactly one ordered cusp cycle exists.
• If no ordered cycle exists, or more than one ordered cycle exists, the call raises ValueError rather than silently falling back.
• Successful experimental search returns effective_system == system and fallback == False; the experimental nature of the computation remains visible through HouseCusps.policy.

HousePolicy.default() exactly replicates all pre-Phase-4 behaviour.

The following ordering guarantees are frozen.

The following are explicitly outside the scope of moira/houses.py and all Phase 1–10 layers:

Authoritative runtime: project .venv (Python 3.14, Windows/cmd).

All validation commands must be run as:

.venv\Scripts\python.exe -m pytest <target>

No test may be marked passing unless it passes in .venv with no modifications to the test file. Tests may not be silenced, skipped without a registered marker, or monkey-patched to hide real failures.

New tests added from Phase 10 onward must use the session-scoped conftest fixtures rather than constructing inline HouseCusps:

Tests that require a second system for comparison may construct it inline via calculate_houses with the same reference coordinates.

• Modify moira/houses.py constants or vessel definitions to make a test pass
• Skip a failing test without a registered KNOWN_ISSUES.yml entry
• Assert on internal private names (_circular_diff, _porphyry, etc.) unless testing the specific private behaviour is the stated purpose of that test class
• Use monkeypatch to suppress a ValueError or TypeError that the implementation is meant to raise

The following inputs must always produce the stated error. This table is frozen.

The following inputs must always produce the stated runtime exception at construction time:

The following cross-layer relationships are required to hold at all times.

The Moira houses backend is hereby frozen at Phase 10. The following changes require an explicit revision to this document before implementation:

• Adding a new public vessel or computation function
• Adding a field to any existing vessel
• Changing the default value of any function parameter
• Changing the boundary condition of any interval rule or distance formula
• Adding a new house system code to _KNOWN_SYSTEMS
• Changing the critical-latitude formula (90° − obliquity)
• Changing the cusp tolerance (1e-9°)
• Changing the default near-cusp threshold (3.0°)
• Changing the angularity map (_ANGULARITY_MAP)
• Exposing any name through __init__ (Phase 12)

The following changes do not require a revision:

• Adding new tests within an existing test class
• Adding docstring clarifications that do not change stated doctrine
• Performance improvements that produce identical outputs
• Fixing a defect where the implementation violates a stated invariant in this document