Moira

Astronomy-First Ephemeris and Astrology Computation Engine

Moira is a sovereign, astronomy-first computation engine built for transparent astrological derivation, reproducible chart reduction, and an inspectable calculation chain from physical ephemerides to astrological outputs. Grounded in JPL DE441/DE440 state vectors, IAU 2000A/2006 precession-nutation models, ERFA/SOFA-aligned astrometry, and Gaia DR3-linked stellar catalogs, Moira pairs a zero-dependency Python orchestration and policy layer with a required C++17 numerical extension (_moira_native, compiled via pybind11).

Where conventional astrology libraries return terminal numbers from opaque defaults, Moira operates as a Light Box: computation stages are named and individually toggleable, doctrinal and source variants are explicit parameters rather than silent assumptions, and validation is maintained as version-bound, replayable evidence.

Table of Contents

• Why Moira & The Light Box Doctrine
• Requirements and Installation
• Quick Start
• The Reduction Pipeline
  • Worked Example: Mars at 2000-01-01 12:00 UT1
  • Pipeline Controls
• What Moira Computes
  • Positions and Celestial Catalogs
  • Chart Architecture and Traditional Western
  • Predictive and Time-Lord Techniques
  • Vedic / Jyotish Suite
  • Phenomena, Visibility, and Locational Astronomy
• REST API Server (moira_server)
• Kernel Setup and Small-Body Archives
  • Planetary Kernels (JPL SPK)
  • Kernel Manager GUI, CLI, and Custom DAF Writer
  • Small-Body Catalogs (Asteroids and Comets)
• Data Inventory
• Native C++ Performance
• Validation Evidence and Light Box Conformance
• AI and LLM Visibility
• Project Documentation and Artifact Governance
• License

Why Moira & The Light Box Doctrine

Astronomy is the foundation. Astrology is the purpose. Validation is the proof. Visibility is the doctrine.

Who It Is For: Developers, ephemeris engineers, historians of astronomy/astrology, and researchers who require a programmable, audit-grade engine for reproducible pipelines and rigorous comparison against primary texts and physical oracles.

What It Is Not: Moira is not a consumer UI application, not a thin wrapper over opaque compiled stacks, and not convenience-first text generation without mathematical traceability.

Requirements and Installation

• Python: >=3.10 (3.10–3.14 supported; Python 3.14 is the canonical CI baseline).
• Native extension: Installed automatically from published platform wheels, or compiled from source via a C++17 compiler, cmake >= 3.24, and pybind11 >= 2.12.
• Planetary kernel: A JPL DE-series .bsp kernel (de440.bsp, de441.bsp, or de430.bsp — downloaded separately; see Kernel Setup).

# Standard engine install (uses a published wheel when available)
pip install moira-astro

# With the FastAPI REST server (FastAPI, Starlette, Uvicorn, Pydantic)
pip install "moira-astro[server]"

# With Lunar Graze support (spiceypy, laspy, requests)
pip install "moira-astro[lunar-graze]"

Quick Start

Moira initializes cleanly even before a planetary kernel is configured. Kernel-dependent calls (such as m.chart()) raise an explicit MissingEphemerisKernelError with remediation instructions until a kernel is present in kernels/ or ~/.moira/kernels/.

from datetime import datetime, timezone
from moira import HouseSystem, Moira
from moira.facade import planet_reduction_breakdown_at
from moira.houses import house_of
from moira.patterns import find_all_patterns

m = Moira()
dt = datetime(2000, 1, 1, 12, 0, tzinfo=timezone.utc)

# 1. Planetary chart reduction
chart = m.chart(dt)
print(f"Sun:  {chart.planets['Sun'].longitude:.6f} deg ({chart.planets['Sun'].sign})")
print(f"Moon: {chart.planets['Moon'].longitude:.6f} deg ({chart.planets['Moon'].sign})")

# 2. House cusps and placement (Placidus, London)
houses = m.houses(
    dt,
    latitude=51.5074,
    longitude=-0.1278,
    system=HouseSystem.PLACIDUS,
)
sun_house = house_of(chart.planets["Sun"].longitude, houses)
print(f"ASC: {houses.asc:.4f} deg | MC: {houses.mc:.4f} deg | Sun House: {sun_house}")

# 3. Aspect pattern detection
for pattern in find_all_patterns(chart.longitudes()):
    print(f"{pattern.name}: {', '.join(pattern.bodies)}")

# 4. Light Box inspectability: per-stage astrometric breakdown at JD_UT1 2451545.0
breakdown = planet_reduction_breakdown_at("Mars", 2451545.0)
print(f"Mars apparent longitude: {breakdown.final_longitude:.6f} deg")
print(f"Light-time delay (days): {breakdown.light_time_days:.6f}")

The Reduction Pipeline

flowchart TD
    A["JPL Planetary Kernel<br/>Chebyshev state vectors"] --> B["SSB Barycentric Position<br/>km · ICRF"]
    C["Sovereign Star Registry<br/>1,809 named stars"] --> D["Stellar Astrometric Position<br/>proper motion · parallax"]
    B --> E["1 · Light-Time Iteration<br/>body at t − τ  (τ = d/c)"]
    E --> F["2 · Gravitational Deflection<br/>Sun · Jupiter · Saturn"]
    F --> G["3 · Annual Aberration<br/>relativistic · IAU SOFA"]
    G --> H["4 · IAU 2006 Frame Bias<br/>ICRF → Mean Equator J2000"]
    D --> H
    H --> I["5 · IAU 2006 Precession<br/>P03 polynomial series"]
    I --> J["6 · IAU 2000A Nutation<br/>1358 luni-solar + 1056 planetary terms"]
    J --> K["True Equinox and Equator of Date"]
    K --> L["7 · Topocentric Parallax<br/>WGS-84 · optional"]
    K --> N["Ecliptic Projection<br/>True obliquity of date"]
    L --> R["8 · Diurnal Aberration<br/>observer rotation · optional"]
    R --> M["Atmospheric Refraction<br/>sky altitude only · optional"]
    N --> O["Zodiacal Longitude · Latitude · Distance"]
    K --> P["Sidereal Frame · Ayanamsa<br/>optional"]
    K --> Q["House Cusps · 22 Systems<br/>requires lat/lon"]

Worked Example: Mars at 2000-01-01 12:00 UT1

This snapshot is reproduced by planet_reduction_breakdown_at("Mars", 2451545.0, reader) with the admitted DE441 kernel. The input is JD_UT1 2451545.0; it is about 63.829 seconds after the exact J2000.0 TT epoch and is therefore not labelled as exact J2000.0.

Time: JD_UT1 2451545.000000 → JD_TT 2451545.000739 ($\Delta T = +63.829\text{ s}$)

Final position: Aquarius 27° 57′ 48″ · $\lambda = 327.963300^\circ$ · $\beta = -1.067779^\circ$ · distance = $1.849688\text{ AU}$ · speed = $+0.775674^\circ/\text{day}$

Total visible reduction from the geometric J2000-ecliptic reference to the final true-of-date ecliptic longitude: $-43.759719\text{ arcseconds}$.

The stage contributions above come from the typed reduction receipt. They should not be reconstructed by subtracting unrelated coordinate frames or by treating apparent=False as "no frame transformation."

Pipeline Controls

Selected correction policies can be toggled via planet_at(). The table below shows the measurable effect of disabling each exposed policy in this JD_UT1 = 2451545.0 Mars snapshot.

What Moira Computes

Positions and Celestial Catalogs

• Planets and luminaries — Geocentric and topocentric reduction with iterative light-time, annual aberration, multi-body relativistic deflection (Sun, Jupiter, and Saturn, excluding the target body), IAU 2006 frame bias, and WGS-84 topocentric parallax.
• Received-light cone (light_cone) — Explicit comparison of apparent observed ecliptic positions (at photon emission epoch $t - \tau$) against instantaneous geometric positions (at $t$), exposing one-way light travel time, emission Julian Date, and angular displacement.
• Fixed stars — Sovereign registry of 1,809 named stars with 3D proper motion, annual parallax, epoch propagation, and Stellar Quality classification. Audited anchor residual against SOFA/ERFA: 0.00048 arcseconds (J1000–J3000).
• Variable and multiple star systems — Phase and magnitude engine for eclipsing binaries and intrinsic variables (including a dedicated Algol API); Keplerian orbital mechanics for visually resolvable binary pairs (Sirius AB, Alpha Centauri AB) across VISUAL, WIDE, SPECTROSCOPIC, and OPTICAL system classes.
• Deep-sky coordinate anchors — A bundled, release-bound selection of 60 galaxies, nebulae, star clusters, compact objects, stellar remnants, and confirmed exoplanet host stars. Extended objects are represented by sourced SIMBAD ICRS/J2000 catalog centers rather than point-mass claims; host-star positions delegate to the sovereign star registry.
• Typed cosmic references and galactic frames — Full equatorial-to-galactic transforms, the legacy five-point compatibility table, and 12 fixed ICRS/J2000 directions kept in three explicit classes: physical objects, coordinate landmarks, and declared proxies (keeping the formal supergalactic origin distinct from the legacy Virgo/M87 astrological SGC, and exposing selected cluster anchors for broad structures such as the Great Attractor and Shapley Concentration).
• Position-capable asteroid ephemeris — Two layers:
  1. Wheel catalog (moira-asteroids-wheel release 2026.08.14.1): 25 named bodies (classical four, named Centaurs including Chiron, named TNOs, and selected others) bundled as one Type-13 shard so Chiron and the locked roster compute immediately after pip install plus a planetary kernel.
  2. External archive (release 2026.10.10.1): 11,223 selected asteroids in release 2026.10.10.1 (449 Type-13 SPK shards from JPL Horizons, a 10-day / 7-node base with certified adaptive apsidal sampling for 59 audited bodies, manifest-discovered under any kernel search root). The wheel also carries the matching 11,223-body canonical identity registry (names only, no positional vectors). Separate from the positional shards, Moira bundles the Proper25/PDS asteroid-family membership catalog (342 families, 200,726 unique numbered asteroids, 221,095 membership rows).
• Numbered periodic comets — 497 comets (1P/Halley through 516P) in immutable external release 2026.10.10.1, generated from JPL Horizons as 20 sharded Type-13 kernels with certified adaptive apsidal sampling for all 497 bodies, manifest-declared coverage, canonical numbered designations ("1P/Halley"), and curated family-scoped short aliases (comet: qualifier supported on unified chart surfaces).
• Lunar nodes and planetary apsides — True Node, Mean Node, Mean Lilith, True Lilith, and osculating/geometric orbital nodes and apsides for planetary bodies.
• Uranian / Hamburg School bodies — Source-orbit, apparent geocentric positions for the 8 Hamburg hypothetical bodies (Cupido through Poseidon; Neely 1980 elements) plus separately sourced Transpluto (Sevin/Strubell 1952 elements), with latitude, distance, and signed motion.

Chart Architecture and Traditional Western

• House systems — 22 systems including Placidus, Koch, Regiomontanus, Campanus, Morinus, Porphyry, Whole Sign, Equal, Alcabitius, APC, Krusinski-Pisa-Goelzer, Pullen Sinusoidal Delta/Ratio, and Sunshine. Includes branch-aware high-latitude doctrine where admitted, explicit polar fallback policy receipts, 3D house-boundary geometry curves, and house_of placement lookups.
• Aspects and motion witness — 22 zodiacal aspects with applying/separating/stationary signed motion-witness detection; declination parallels and contra-parallels; antiscia and contra-antiscia; exact partile (is_partile) and orbed platic (is_platic) status markers; geometric aspect strength.
• Aspect patterns and Jones chart shapes — 21 multi-body configurations (T-Square, Grand Trine, Grand Cross, Yod, Kite, Mystic Rectangle, Grand Sextile, Thor's Hammer, Boomerang Yod, and more) plus all 7 Marc Edmund Jones temperament chart shapes with computation truth receipts.
• Planet-first stelliums — Explicit Strict (four-planet) and Broad (three-planet) core counts, independent sign/house/total-span evidence, and associated bodies that attach without manufacturing a cluster. See STELLIUM_ANALYSIS_STANDARD.md.
• Midpoints — Full midpoint matrix, midpoint trees, 90°/45°/22.5° dial projections, and planetary pictures.
• Traditional dignities and almutens — Domicile, exaltation, triplicity (Dorothean/Ptolemaic diurnal/nocturnal), Egyptian/Ptolemaic/Chaldean terms, face, sect, hayz, Reception, and Almuten Figuris.
• Arabic Parts (Lots) — 512 lot definitions with dependency graphs, diurnal/nocturnal reversal policies, and condition profiling.
• Classical decanates — Chaldean faces, triplicity decans, and Vedic drekkana; the Gundel/Harley Hermetic name-and-face catalog is reconstructed for research while its geometry remains excluded from public/REST surfaces.
• Unified Hellenistic profile — Non-interpretive, score-free Whole Sign composition of typed receipts for essential dignity components, sect, joy, solar proximity/phase, besieging, receptions, lots, annual and dated monthly profections, Decennials L1/L2, and Zodiacal Releasing, with explicit not_evaluable truth when dependencies are absent.
• Draconic, Astrodynes, and Huber — Node-anchored Draconic charts (True or Mean Node rotation with anchor_residual verification); Church of Light Cosmodyne/Astrodyne power, harmony, and discord tables; and Bruno & Louise Huber's 72-year Life Clock age-point progression and golden-section ($\Phi$) house intensity profiles.

Predictive and Time-Lord Techniques

• Progressions — Secondary, tertiary, minor, solar arc (longitude and right ascension), Naibod, and ascendant arc, with direct and converse variants and explicit rate-authority receipts.
• Primary directions — 8 admitted geometry methods across in-mundo and in-zodiaco policies (Placidus mundane, Ptolemy semi-arc, Placidian classic, meridian, Morinus, Regiomontanus, Campanus, and topocentric), exposed through 25 named presets, direct/converse doctrines, speculum computation, fixed-star targets, and Ptolemy/Naibod/Cardan/solar time keys.
• Returns, transits, and cycles — Solar and lunar returns; arbitrary planetary and small-body longitude returns; station-aware transit window search; and outer-planet synodic cycle tracking.
• Time lords and vitality — Annual profections with exact civil-anniversary-bounded monthly intervals; Zodiacal Releasing (Vettius Valens L1–L4 with loosing-of-the-bond); admitted Decennials L1/L2; Firdaria (diurnal and nocturnal sequences including the Bonatti variant); Lord of the Orb and Lord of the Turn; and Hyleg/Alcocoden vitality calculations.

Vedic / Jyotish Suite

Admitted Vedic surfaces name their governing classical source, modern lineage, or source-scoped witness (including Brihat Parashara Hora Shastra [BPHS], Brihat Jataka, Saravali, Phaladeepika, Uttara Kalamrita, Jataka Parijata, Jaimini Upadesa Sutras, and the named 1879 Agastya- and 2024 Bogamuni-attributed Pancha Pakshi witnesses). Where sources disagree or a modern composition is required, Moira exposes the policy or qualification instead of presenting one silent universal rule.

• Sidereal foundation and Panchanga — 12 admitted ayanamsha systems (including Lahiri, True Chitrapaksha, Raman, Krishnamurti, Fagan-Bradley, Pushya Paksha, and star-anchored True ayanamshas); 27-nakshatra and 28-Abhijit division with pada and ruler truth; and classical five-limb Panchanga (Tithi, Vara, Nakshatra, Yoga, Karana) plus daily sunrise-owned Panchanga (DAILY_PANCHANGA_STANDARD.md).
• Vimshottari, Kalachakra, and Alternate Dashas —
  • Vimshottari Dasha with exact nakshatra balance and multi-level sequence trees.
  • Kalachakra Dasha (bphs_santhanam_longitude_row_cycle_v1, exposed in Python and via GET /v1/dasha/kalachakra/profiles and POST /v1/dasha/kalachakra/sequence) with exact Savya/Apasavya BPHS/Santhanam source years, Deha/Jeeva signs, Gati jump classification, and bounded Mahadasha/Antardasha trees (KALACHAKRA_DASHA_STANDARD.md).
  • Alternate Conditional Dashas (Ashtottari, Shodashottari, Dwadashottari, Panchottari, Shatabdika, Chaturashiti Sama, Dwisaptati Sama, Shashtihayani, Shat-Trimshat Sama, and Yogini) with explicit applicability gates (ALTERNATE_DASHAS_BACKEND_STANDARD.md).
• Jaimini system and source-defined Chara/Argala profiles — Rasi drishti, arudha padas A1–A12 (Rath/JHora exception default, Raman variant as policy), karakamsa (Rath D9 vs. K.N. Rao D1), plus 6.10.0 source-defined Chara Dasha profiles and bounded Argala (argala) assessments across three Chara and three Argala source selectors (JAIMINI_PROFILE_ASSESSMENT_STANDARD.md).
• Yogas and source-defined Yoga extensions — 61 classical yogas across six families (Pancha Mahapurusha, Chandra, Surya, all 32 Nabhasa, Raja core, Dhana core) returned as proof objects with formation conditions and cancellation (bhanga) clauses, plus 6.10.0 source-defined Yoga Extensions covering four named profiles and 21 admitted rules with explicit frame/branch receipts (YOGA_EXTENSION_STANDARD.md).
• Vargas and Shadbala — Divisional charts D1–D60 (navamsa, dashamansa, dwadashamsa, saptamsa, trimshamsa, shashtiamsa, etc.), Vimshopaka Bala (BPHS 20-point varga strength) with vargottama detection, and the complete six-fold Shadbala system plus Bhava Bala, Ishta/Kashta Phala, and Graha Yuddha planetary war transfer disclosure.
• Ashtakavarga, Upagrahas, and Avasthas — Bindu tables, kakshya transit evaluation (Saturn-first lord order), and Shodhya Pinda validated to the digit against BPHS Ch. 69; the five kalavelas (Gulika, Kala, Mrityu, Ardhaprahara, Yamaghantaka) and five Sun-derived upagrahas; Baladi, Jagradadi, Deeptadi, Lajjitadi, and source-bound Sayanadi Avasthas (SAYANADI_ADMISSION_STANDARD.md).
• Muhurta, Varshaphal, Gochara, and Sade Sati — Annual Tajika Varshaphal charts; Tara Bala, Chandra Bala, Panchanga Shuddhi (PANCHANGA_SHUDDHI_STANDARD.md), marriage/purpose electional evaluation, and named Muhurtas; Gochara transit windows; and kernel-timed Sade Sati phase windows with Ashtama/Kantaka Shani flags.
• Pancha Pakshi (Source-Scoped Madras 1879 & Bogamuni 2024 Profiles) — Explicitly source-bound schedule, relationship, astronomical-paksha, solar-proportional, fixed-clock, EAT-seed, natal-Moon identity, and Padu-bird lookup surfaces with zero silent cross-routing.

Phenomena, Visibility, and Locational Astronomy

• Eclipses and occultations — NASA-canon contact solver for solar and lunar eclipses, Saros series classification with heptagonal vertex labelling, local eclipse circumstances, and lunar occultations of stars and planets.
• Visibility and heliacal phenomena — Heliacal and acronychal rising and setting, planetary elongation extremes, Yallop lunar-crescent classification, and opt-in physical point-source visibility (moira-physical-heliacal-visibility 1.2.0 data pack; see PHYSICAL_HELIACAL_VISIBILITY_CAPABILITY_MATRIX.generated.md).
• Stations, solar conditions, and void-of-course Moon — Retrograde/direct stationary-point search with velocity/acceleration motion truth; cazimi, combustion, and under-the-beams solar condition events; and void-of-course Moon windows with exact aspect-domain and ingress receipts.
• Locational astrology and parans — Astrocartography (ACG) horizon/meridian curves and crossing lattices, Local Space azimuth/altitude bearings, Gauquelin 36-sector plus-zone analysis, and paranatellonta (paran) field analysis with contour extraction.
• Harmonics and harmograms — Addey/Hamblin harmonic chart projection, inverse-harmonic orb conjunctions ($O_H = O_1 / H$), cluster pattern scoring, vibrational fingerprints, and continuous H1–H5 harmogram wave traces.
• Synastry, relationship, and Natal Discovery — Inter-chart synastry aspects and house overlays, midpoint composite charts, spherical-midpoint Davison charts, and bounded Natal Discovery packets (traditional dispositor chains, Jones 10-planet shape evidence, and source-verified natal lunar context).

REST API Server (moira_server)

Moira includes an optional FastAPI transport layer (moira_server) that exposes 531 OpenAPI operations (527 versioned /v1 routes plus 4 operational endpoints) with strict Pydantic request/response validation and embedded provenance receipts.

pip install "moira-astro[server]"
uvicorn --factory moira_server:create_app

For latency-sensitive deployments, opt in to a bounded per-worker startup warmup before accepting computational traffic:

$env:MOIRA_SERVER_PREWARM = "1"
uvicorn --factory moira_server:create_app

• Readiness vs. Liveness: With MOIRA_SERVER_PREWARM=1, /ready returns HTTP 503 until kernel-backed warmup succeeds, while /health remains immediately available for liveness checks.
• Transport Boundary: All astronomical and astrological doctrine resides in moira; moira_server provides typed serialization, input validation, bounded LRU caching, and OpenAPI discovery (/openapi.json, /docs, /redoc).
• Complete Route Inventory: See REST_API_REFERENCE.md for the generated inventory of all 531 operations.

Kernel Setup and Small-Body Archives

Planetary Kernels (JPL SPK)

Moira requires a JPL DE-series SPK planetary kernel for planetary calculations. All kernel reading is performed by Moira's native C++17 SPK/DAF reader (_moira_native) with zero jplephem fallback. Ordinary ephemeris calculations are strictly local and never make outbound network requests.

Place your .bsp file in kernels/ (relative to the repository root) or ~/.moira/kernels/, or configure a custom path in Python:

from moira import Moira
from moira.spk_reader import set_kernel_path

set_kernel_path("/path/to/de440.bsp")
m = Moira()
print(m.is_kernel_available(), m.available_kernels)

Kernel Manager GUI, CLI, and Custom DAF Writer

# CLI: list kernel status or download missing planetary kernels
moira-download-kernels --list
moira-download-kernels --yes

# Tkinter GUI: browse, download with progress bar, and activate kernels
moira-kernel-manager

# Tkinter GUI: build custom Type-13 SPK kernels from JPL Horizons
moira-daf-writer

Small-Body Catalogs (Asteroids and Comets)

• Bundled Wheel Roster (moira-asteroids-wheel 2026.08.14.1): Ships inside the wheel under moira/kernels/asteroids_wheel/ with 25 named bodies (including Chiron, Ceres, Pallas, Juno, Vesta, Pholus, Nessus, Chariklo, Eris, Sedna, Haumea, Makemake, Quaoar, Orcus, Hygiea, Psyche, Eros, Lilith, Sappho, Iris, Astraea, Hebe, Flora, Metis, and Eunomia) ready for immediate calculation once a planetary kernel is present.
• Full External Catalogs (Release 2026.10.10.1):
  • Asteroids: 11,223 selected asteroids across 449 Type-13 SPK shards in release 2026.10.10.1 (with certified adaptive apsidal sampling for 59 audited high-eccentricity bodies).
  • Comets: 497 comets (1P/Halley through 516P) across 20 Type-13 SPK shards in release 2026.10.10.1 (with certified adaptive apsidal sampling for all 497 bodies).
  • Download shards and manifests from the Moira Small-Body Ephemerides Archive and place the complete release contents (manifest.json, SHA256SUMS, .bsp shards, and .metadata.json files) directly inside kernels/asteroids/ or kernels/comets/ (or ~/.moira/kernels/asteroids/ and ~/.moira/kernels/comets/).

Verify an extracted small-body catalog release or archive before use:

.\.venv\Scripts\python.exe -m moira.small_body_catalog_release verify C:\path\to\catalog-release
.\.venv\Scripts\python.exe -m moira.small_body_catalog_release verify-archive C:\path\to\catalog-release.zip

Data Inventory

Native C++ Performance

Moira's required numerical extension (_moira_native) is implemented in C++17 with pybind11. Published wheels install the compiled binary directly; source builds compile it via CMake during installation.

• Native-Owned Numerical Substrates: IAU 2000A nutation, P03 precession, SPK/DAF segment reading and Chebyshev/Hermite evaluation, apparent planetary reduction via NativePlanetaryEvaluator, coordinate frame rotations, light-time iteration primitives, harmogram wave synthesis, and selected event-search kernels.
• Python-Owned Semantics & Policy: Public API contracts, doctrinal policy selection, source-conflict disclosure, and compositional orchestration remain in Python so numerical speed never obscures astrological or astronomical provenance.

Validation Evidence and Light Box Conformance

Moira is validated across a three-layer corpus—Astronomy (IAU ERFA/SOFA, JPL Horizons, NASA, IERS), Astrology (named primary texts, source-owned fixtures, doctrine-grounded invariants, and bounded secondary comparisons), and Experimental/Sovereign domains—governed by three gates:

1. Gate of Source — Inputs and reference tables are tied to an independent primary authority.
2. Gate of Flow — The computational derivation is explicit and inspectable.
3. Gate of Validation — Outputs satisfy a product-appropriate external authority, source-owned golden, independent invariant, or replayable release contract.

Light Box Conformance Program (GAP-007)

Beyond narrative validation ledgers, Moira enforces machine-checked Light Box Conformance across the entire public calculation denominator (moira.facade.__all__ + FastAPI OpenAPI):

• Complete Public Denominator: 1,251 canonical calculation surfaces (1,255 total including 4 aliases) classified across 150 reviewed families.
• 100% P0 Production-User Coverage: All 171 canonical P0 surfaces used by production consumers—plus 38 additional P1/P2 exemplar surfaces (209 total)—are structurally admitted and bound to 63 replayable evidence contracts (tests/evidence/lightbox/contracts.json).
• Replayable Release Gate: Exact-release receipts (scripts/replay_lightbox_receipts.py) and the release gate (scripts/check_lightbox_release_gate.py) verify contract coverage and inventory fingerprints while keeping remaining P1/P2 unresolved residuals explicitly visible rather than hidden behind universal claims.

AI and LLM Visibility

Moira is structured for high-integrity discovery and collaboration with AI coding and research agents:

• Machine-Readable Indexes: llms.txt provides a concise root summary and llms-full.txt provides the comprehensive documentation index.
• Agent Operational Constitution: AGENTS.md defines the Urania collaboration persona, protected zones, runtime laws, and verification gates.
• Canonical Wiki & Standards: Full architectural standards and validation ledgers live in wiki/.

Project Documentation and Artifact Governance

The canonical documentation tree lives in wiki/. The flat moira.wiki/ Git wiki mirror is synchronized from wiki/ and should not be edited by hand in isolation. Website-publishable documents are governed by website_docs/publication_sources.json.

Refresh affected generated artifacts in dependency order using the project .venv (.\.venv\Scripts\python.exe) before pushing:

1. scripts/generate_hellenistic_inventory.py when admitted Hellenistic families change.
2. scripts/sync_rest_api_reference.py after server route changes.
3. scripts/generate_lightbox_calculation_inventory.py, scripts/generate_lightbox_conformance_manifest.py, scripts/generate_lightbox_family_register.py, scripts/generate_lightbox_family_assessment.py, scripts/replay_lightbox_receipts.py, scripts/generate_lightbox_assurance_matrix.py, and scripts/generate_lightbox_public_status.py when public calculation surfaces or admissions change.
4. scripts/sync_git_wiki.py after canonical documentation changes.
5. scripts/build_website_docs_bundle.py after public exports, route references, or allowlisted documents change.

Before publishing, run the consistency, release-identity, and generated-artifact gates defined in Release Hardening (scripts/check_doc_consistency.py and scripts/check_release_identity.py).

License

MIT (c) 2026 TheDaniel166. See PROVENANCE.md for license and Swiss-lineage provenance clarity.