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.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