Aspects & Orbs

Moira Aspect Backend Standard

Governing Principle

The Moira aspect 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. Focused verification counts belong in completion receipts rather than frozen doctrine.

---

Part I — Architecture Standard

1. Authoritative Computational Definitions

1.1 Ecliptic aspect

An ecliptic aspect in Moira is:

A detected angular relationship between two distinct celestial bodies whose angular separation along the ecliptic falls within a declared orb of a canonical aspect angle.

The admission test is fully reconstructable from the stored vessel:

orb        == abs(separation - angle)
orb        <= allowed_orb
separation  = angular_distance(lon1, lon2)

1.2 Declination aspect

A declination aspect in Moira is:

A parallel or contra-parallel between two distinct celestial bodies whose signed declinations satisfy one of the two defined relationships within a declared orb.

Two points exactly on the equator form one exact Parallel. A single equatorial point has no hemisphere and forms neither relation with a non-equatorial point. Hemisphere qualification precedes the orb formula so both relations cannot be emitted for one pair near 0°.

Detected DeclinationAspect vessels carry no motion data; consequently the legacy generic aspect_motion_state(DeclinationAspect) remains NONE. The separate DeclinationAspectMotionWitness is the first-class temporal product when declination rates are supplied.

1.2.1 Module ownership

moira.declination_aspects governs parallels, contra-parallels, their hemisphere/equator doctrine, policy, result vessels, and signed motion witness. moira.aspects governs ecliptic-longitude and whole-sign relationships and retains compatibility re-exports for the historical declination imports. Shared domain/tier/family classification types live in the private moira._aspect_types taxonomy layer so both engines use identical enum and classification objects without circular imports.

Declination is a second angular coordinate on the celestial sphere. It is not full Cartesian 3D geometry because radial distance is not part of these relationships.

1.2.2 Whole-sign direction and overcoming

moira.aspects also owns Hellenistic aspect direction and whole-sign overcoming. hellenistic_superiority_truth() is the governing atomic receipt for one ordered body pair: HellenisticDirectionTruth preserves directed-arc geometry and sinister/dexter applicability, while HellenisticOvercomingTruth preserves both inclusive sign places and the typed winner-or-neither relation.

Direction is not_evaluable when no aspect angle is supplied, for conjunction or opposition, or at an exact directed conjunction/opposition boundary. The reason is preserved and an evaluable direction cannot be suppressed. Overcoming remains evaluated for finite pair geometry. Sign counting is inclusive: the first body overcomes the second only when the first occupies the tenth sign from the second, which is nine zero-based sign steps forward. Reversing the operands reverses the question. A third-sign/fourth-sign confusion must not be accepted merely because the bodies form an undirected square.

AspectData.direction and overcoming(lon1, lon2) are compatibility projections from that shared raw truth. Detector-produced AspectData also carries the aggregate hellenistic_superiority_truth receipt. No additive dignity or superiority score is admitted by this composition layer.

1.3 Admitted aspect

An aspect is admitted when the admission test passes. Admission is binary: the aspect either qualifies or it does not. There is no partial admission and no confidence score at the detection layer.

---

2. Layer Structure

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

Phase  1 — Core aspect detection
Phase  2 — Relational truth preservation
Phase  3 — Classification
Phase  4 — Inspectability
Phase  5 — Doctrine inputs
Phase  6 — Policy surface
Phase  7 — Geometric strength
Phase  8 — Temporal state
Phase  9 — Canonical configuration
Phase 10 — Multi-body pattern layer
Phase 11 — Relational graph / network layer
Phase 12 — Harmonic / family intelligence layer

Layer boundary rule

A function in phase N may consume results from phases 1 through N−1. It may not:

• re-run position arithmetic
• re-compute aspect admission
• alter a vessel produced by an earlier phase in place
• introduce new doctrine inputs not present in that phase's entry point

---

3. Delegated Assumptions

The aspect engine delegates to external modules without redefining them:

The aspect backend does not redefine any of these. Changes to these constants propagate automatically.

---

4. Canonical Aspect Set

The complete set of recognised and detectable aspect types is declared in CANONICAL_ASPECTS — a module-level tuple of 24 names, frozen at import time.

Rules:

• The 22 zodiacal names correspond 1-to-1 with entries in Aspect.ALL.
• The 2 declination names are produced exclusively by find_declination_aspects.
• CANONICAL_ASPECTS carries no detection logic; it is a declaration only.
• No aspect not in CANONICAL_ASPECTS can be produced by any detection function.

---

5. Classification

AspectClassification classifies every admitted aspect on three independent axes:

Classification is descriptive only. It describes what was detected, not how it should be interpreted. Strength, dignity weighting, and reception scoring are excluded from the classification layer.

Family grouping

Aspects in the same harmonic series share a family:

---

6. Policy Layer

AspectPolicy encapsulates longitude-aspect doctrine and retains declination_orb as a compatibility adapter for historical callers.

When a policy argument is passed to a detection function it takes full precedence over any corresponding individual keyword arguments. Individual parameters remain available for backward compatibility.

DEFAULT_POLICY reproduces the historical default behaviour of all four detection functions.

DeclinationAspectPolicy is the governing declination policy:

Policy validation

AspectPolicy validates its fields at construction:

---

7. Geometric Strength

AspectStrength is a pure arithmetic exactness summary derived from orb and allowed_orb only.

surplus   = allowed_orb - orb
exactness = 1.0 - orb / allowed_orb

aspect_strength does not interpret strength. It does not weight by aspect family, body dignity, or orbital speed.

Strength validation

aspect_strength validates its input before computing:

Whole-sign aspects are categorical rather than orb-admitted. Their strength identity is orb = allowed_orb = surplus = 0 and exactness = 1.

---

8. Temporal-State Doctrine

MotionState formalises the motion-aware truth already stored in applying and stationary. It maps the complete decision space without ambiguity:

Categorical/no-motion domains yield NONE. For zodiacal aspects, EXACT takes precedence over stationary and applying/separating classification.

Temporal consistency rules

• APPLYING ↔ is_applying is True and is_separating is False
• SEPARATING ↔ is_separating is True and is_applying is False
• is_applying and is_separating are never simultaneously True
• Both are False when applying is None

First-class declination motion

DeclinationAspectMotionWitness classifies a selected relationship from caller-supplied declinations and optional declination rates, all expressed in the same declared frame, timescale, origin, and correction regime.

Away from exactness, orb = abs(E) and orb_rate = sign(E) * dE/dt. A negative orb rate is APPLYING; a positive orb rate is SEPARATING. Exactness takes precedence. A relative rate inside the policy tolerance is STATIONARY, while missing or partial rates are INDETERMINATE. An individual zero declination rate does not force STATIONARY when the relationship's relative error is still changing.

The witness is instantaneous (instantaneous_no_event_search). It does not prove that a relationship will perfect before either body reverses in declination; that stronger claim requires an epoch-based exact-root search.

---

9. Multi-Body Pattern Doctrine

find_patterns operates over an already-admitted list[AspectData]. It does not re-run position arithmetic.

Implemented patterns and their structural requirements:

Pattern ordering rules

• Output order: Stellia, T-Squares, Grand Trines, Grand Crosses, Yods.
• Each pattern kind is emitted at most once per unique body set (frozenset).
• Stellium: smaller subsets contained within a larger Stellium are suppressed.
• All other kinds are independent. A Grand Cross may also contain T-Squares; both are reported.
• Within each kind, patterns are ordered by sorted body-name iteration (outer loops always iterate over sorted(all_bodies)).

Pattern contributing-aspects ordering

The aspects tuple inside each AspectPattern is sorted by (body1, body2, aspect). This ordering is stable and independent of the input list ordering.

Structural aspect counts

---

10. Relational Graph Doctrine

build_aspect_graph expresses the chart as a deterministic aspect network. Bodies become nodes; each admitted AspectData becomes an edge.

Graph construction rules

• Every body that appears in at least one aspect gets a node.
• Bodies supplied via bodies= that have no aspects get degree-0 nodes.
• nodes is sorted by body name.
• edges is sorted by (body1, body2, aspect).
• components is sorted by (min(component), len(component)) ascending.

Node invariants

family_counts keys are AspectData.aspect strings (e.g. "Trine"), not AspectFamily enum values. This is intentional: it preserves per-name granularity at the graph layer (Trine vs Biquintile both count as QUINTILE family at the harmonic layer, but remain distinct at the graph layer).

Derived properties

---

11. Harmonic Intelligence Doctrine

aspect_harmonic_profile derives the family distribution of admitted aspects at both the chart level and per body.

Profile construction rules

• chart covers all aspects in the input list.
• by_body has one entry per body that appears in at least one aspect.
• by_body keys are in sorted body-name order.
• A body with no aspects has no entry in by_body.

Family resolution order (when classification is absent)

1. a.classification.family when classification is not None (normal case).
2. _FAMILY_BY_NAME[a.aspect] when classification is None and the name is a known zodiacal name.
3. AspectFamily.DECLINATION as the fallback for any unrecognised name (covers "Parallel", "Contra-Parallel", or custom names).

AspectFamilyProfile invariants

---

12. Non-Goals

The following concerns are explicitly outside the scope of the current aspect backend:

---

Part II — Validation Codex

1. Validation Environment

No test in test_aspects.py may be modified to make the implementation pass. A failing test is always treated as an implementation defect, not a test defect, unless the test itself is proven incorrect.

---

2. Invariant Register

This register is the normative source of truth for all subsystem invariants. Each invariant is identified by a short code for traceable reference.

INV-TRUTH — Truth preservation

INV-CLASS — Classification

INV-STR — Geometric strength

INV-MOT — Temporal state

INV-PAT — Pattern layer

INV-GRAPH — Relational graph

INV-HARM — Harmonic layer

INV-POL — Policy

---

3. Determinism Register

The following ordering guarantees are normative. Any permutation of an input list must produce identical output on all of these:

---

4. Failure Doctrine

The following table lists every condition that raises an exception, the exception type, and the diagnostic guarantee:

All functions remain pure computations over valid inputs. Collection-oriented detectors return empty results for empty valid mappings; first-class analysis surfaces require at least two included points.

Behaviour on empty input

---

5. No-Mutation Guarantee

Every public function beyond the detection layer accepts its inputs by value and does not mutate them:

---

6. Cross-Layer Consistency Rules

These rules govern the logical relationship between layers. Each rule must hold on any output produced by the detection layer.

---

7. Public Surface Register

Complete public surface of moira.aspects as of Phase 12:

Enumerations

Frozen dataclasses

Immutable result vessels

The vessels are terminal (not designed for subclassing) and document their structural invariants explicitly in their class docstrings.

Module-level constants

Detection functions

Derived-layer functions

---

8. Validation Baseline

Validation uses the authoritative project .venv and the focused aspect, moiety, signed-motion, synastry, pattern, public-surface, external-reference, and relationship REST slices. Test counts are not frozen doctrine; the completion receipt for a change records the exact commands, outcomes, skips, fixtures, and scope exercised. Tests may change only when an explicitly admitted contract changes, with regression coverage for the replacement law.