Houses & Cusps

Moira Houses Backend Standard

Governing Principle

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 for the public house-system surface. It does not describe aspirational future capabilities.

For the clean-room sovereignty remediation path beyond current implementation truth, see HOUSES_SOVEREIGNTY_REMEDIATION_ROADMAP.md. For the house-system derivation and discretionary divergence record, see HOUSE_SYSTEM_DIVERGENCE.md.

---

Part I — Architecture Standard

1. Authoritative Computational Definitions

1.1 House cusp

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.

1.2 House

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.

1.3 Ecliptic longitude placement

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.

1.3a Selected-zodiac house frame (2026-09-09 correction)

calculate_houses and houses_from_armc accept ayanamsa_offset in degrees. For physical/quadrant and equal-degree systems, the same offset changes ecliptic labels on positions and boundaries; ARMC and true-equatorial physical boundary vectors do not rotate. Assignment requires positions and cusps in the same longitude frame.

Whole Sign (W) and Solar Sign (S) are sign-defined sectors, not a rotated copy of a previously selected tropical sign. Their first cusp is the opening of the selected-zodiac sign containing ASC or the supplied tropical Sun minus the offset, respectively. All twelve returned cusps remain exact multiples of 30 degrees in that zodiac. This applies to the effective system, including a policy-directed Whole Sign fallback. Tropical and zero-offset results are unchanged. Solar inputs remain tropical; callers must not subtract the offset twice. The correction does not alter polar admissibility or fallback policy.

Regression authority is the explicit sign-sector definition and rotation invariants, not a new external ephemeris accuracy claim. See tests/unit/test_house_sidereal_frame.py.

1.4 Angularity category

An angularity category is:

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

1.5 Cusp proximity

Cusp proximity is:

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

1.6 Signed cusp delta

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.

---

2. Layer Structure

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)

Layer boundary rules

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

---

3. Supported Systems

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

Polar-incapable systems (_POLAR_SYSTEMS): K, C, R, and T. Placidus (P) has integrated branch-search doctrine for high latitudes (unique ordered semi-arc cycles when they exist for the position); it is no longer blanket pre-empted and is marked polar_capable=True. When no unique ordered solution exists for a given high-lat ARMC, policy still governs fallback/raise. Alcabitius (B) likewise has integrated direct zero-pole ordered-figure doctrine and is marked polar_capable=True. APC remains directly computable at high latitude only when its projected cusps form one strictly ordered ecliptic cycle; otherwise its declared polar policy governs fallback or raise. The remaining listed systems fall back (or raise) under default policy above critical latitude (90° − obliquity ≈ 66.56° at J2000).

QUADRANT H1 exception

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.

---

4. Delegated Assumptions

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.

---

5. Public Surface

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

Enumerations

Frozen dataclass vessels

Computation functions

Module-level constants

---

6. Fallback and Policy Doctrine

6.1 Fallback triggers

Two conditions can redirect the computation away from the requested system. Unknown-system policy is resolved before polar admissibility; projected-cycle quality is evaluated after the affected 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.

6.2 Fallback truth preservation

When a fallback occurs:

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

6.3 Fallback reason strings (pattern)

6.3a Experimental high-latitude search

PolarFallbackPolicy.EXPERIMENTAL_SEARCH is an explicit opt-in research mode that loads the separate experimental_<system>.py module for a requested polar system when such a module is registered. The per-system module owns the definition of an admissible high-latitude figure for that geometry.

• The engine calls the registered moira.experimental_<system> module for the requested system.
• The search accepts the result only when the module's own doctrine identifies exactly one admissible ordered cusp cycle.
• 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.

6.4 Policy factory methods

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

---

7. Invariant Register

7.1 HouseCusps invariants (enforced by __post_init__)

7.2 HousePlacement invariants

7.3 HouseBoundaryProfile invariants

7.4 HouseAngularityProfile invariants

7.5 HouseSystemComparison invariants

7.6 HousePlacementComparison invariants

7.7 HouseOccupancy invariants

7.8 HouseDistributionProfile invariants

---

8. Determinism and Ordering Rules

The following ordering guarantees are frozen.

---

9. Non-Goals and Excluded Concerns

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

---

Part II — Validation Codex

10. Validation Environment

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.

---

11. Test File Register

Exact test counts belong to live pytest output, not this doctrine file.

---

12. Validation Doctrine

12.1 What must be validated per layer

12.2 Conftest fixture usage (Phase 10 onward)

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.

12.3 What tests must NOT do

• 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

---

13. Guaranteed Failure Conditions

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:

---

14. Cross-Layer Consistency Requirements

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

---

15. Scope-Freeze Statement

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